fix(calendar): reject invalid time windows before querying events - #1298

How this fits together

Calendar commands pass date flags through shared timezone-aware range resolution and formatting before querying Google Calendar and printing events or availability.

flowchart LR
  A[Calendar CLI flags] --> B[Calendar command]
  B --> C[Timezone and range resolver]
  C --> D[Request timestamp formatter]
  D --> E[Google Calendar API]
  E --> F[Events or availability output]

Technical review

Best possible solution:

Keep the shared range validation and instant-preserving formatter, and settle the explicit-start search default before landing.

Do we have a high-confidence way to reproduce the issue?

Current-main source establishes both invalid-window paths, and the contributor supplies exact release-versus-head CLI request bounds and exit codes; this read-only review ran no target code.

Is this the best way to solve the issue?

The implementation uses existing owners and mechanisms with focused command regressions; its broader change to successful search windows is a product choice rather than a demonstrated code defect.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against dc6bf1f3bba8.

Provenance checked

• Search's omitted-end default changes intended behavior with a stated reason (006d02e: Restore now-relative search defaults; 184f085 subsequently preserved them in the shared resolver.)
• Calendar request timestamp serialization changes intended behavior with a stated reason (0ca019d: Timezone-aware range support formatted bounds as RFC3339; team queries adopted direct formatting in f8b83e5. UTC conversion now preserves instants that minute-only offsets cannot represent.)
• Existing window-flag semantics keeps the original intent (fix(calendar): honour --from when --days is given, reject ambiguous window flags #981: Honor explicit starts with --days and reject ambiguous flag combinations; this patch leaves those decisions intact.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Current main retains the reported bug: Verified default-branch SHA is dc6bf1f; search supplies only now-relative offsets, and the shared resolver returns bounds without checking their order. (internal/cmd/calendar_search.go:44, dc6bf1f3bba8)
• Focused shared repair: The introduced patch uses the existing ToFromOffset mechanism, compares bounds at request precision, and routes team requests through the existing shared formatter. (internal/cmd/time_helpers.go:279, fd0f83879db8)
• Updated shipped-CLI evidence: The full PR body records macOS arm64 release-versus-head CLI results against the same local Calendar API fake: corrected future bounds, exit 2 without Events.List for invalid bounds, preserved historical Paris instants, unchanged no-flag defaults, and the changed past-start window. (fd0f83879db8)
• Original default was deliberate: Commit 006d02e restored search's now-plus-90-days end even with an explicit start; 184f085 carried that behavior into shared defaults. The current body explicitly identifies and requests a decision on changing successful past-start searches. (internal/cmd/calendar_search.go:45, 006d02e17e18)
• Linked report and earlier fix: bug(calendar): --from or --to alone can produce an inverted window that fails as an API error #1280 establishes the affected v0.47.1 paths; fix(calendar): honour --from when --days is given, reject ambiguous window flags #981 addressed --from with --days and ambiguous flags, leaving this endpoint-order defect unresolved. (internal/cmd/calendar_window_flags_test.go:210, fd0f83879db8)
• Policy and history coverage: Read the complete root AGENTS.md; no nested AGENTS.md, maintainer-notes directory, or pr-simplify skill was present. Feature-history searches covered resolver, search, team, and tests; follow-history reached an unavailable older object after the relevant feature commits. (AGENTS.md:1, dc6bf1f3bba8)

Likely related people:

• Peter Steinberger: Raw commit 184f085 adds internal/cmd/time_helpers.go:57 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 184f085be51e; files: internal/cmd/time_helpers.go)
• salmonumbrella: Raw commit 0ca019d adds internal/cmd/time_helpers.go:52 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 0ca019dc8966; files: internal/cmd/time_helpers.go)
• Frank: Raw commit 0d80885 adds internal/cmd/time_helpers.go:167 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 0d8088534f09; files: internal/cmd/time_helpers.go)

Preflight source

Source unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified.

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: ⏳ waiting on maintainer: Only explicit maintainer approvals or decisions remain; merge is still blocked.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 📣 needs proof: Current PR status label is status: ⏳ waiting on maintainer.

Label justifications:

• P2: Specific Calendar query windows fail; explicit valid bounds remain available.
• merge-risk: 🚨 compatibility: Successful past-start searches can return a different event interval after upgrading.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: ⏳ waiting on maintainer: Only explicit maintainer approvals or decisions remain; merge is still blocked.
• proof: sufficient: Contributor real behavior proof is sufficient.

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Record the Calendar owner's choice on the omitted end for explicit-start searches.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

History