refactor: simplify command registration and decoding

[steipete]

Shell completion duplicated the router's command list, command specifications bypassed Sendable checking, and internal option-decoding helpers had no callers. Share the command registry, require @Sendable handlers, remove the unused helpers, and collapse equivalent app-opening and location branches.

Commander 0.2.4 already makes command signatures and parsed values Sendable. Public command flags, aliases, output, the RemindCore API, and the macOS/Swift floors are preserved.

Validation: make check passes strict Swift/shell/workflow lint, 92 tests and 93.8% RemindCore line coverage (898/957); built CLI passes 40 before/after byte comparisons against a disposable synthetic EventKit list, covering show/search/info/export/list/status/link in every output mode plus help, version and bash/zsh completion. All synthetic data was removed. macOS's /bin/bash was selected for local scripts after diagnosing a Homebrew Bash heredoc stall.

Exact independent head: 918243fb0c47e66415e8dbd6d2119b91fa178a06. CI. The identical reviewed patch was rebased onto main without the other cleanup commits (stable patch ID unchanged), then local gates and live binary comparisons were repeated. Isolated Codex autoreview is scoped-clean through P2.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 13, 2026, 2:34 AM ET / 06:34 UTC (Revision 2).

ClawSweeper review

What this changes

The PR shares command registration with shell completion, checks handler concurrency safety, removes unused decoding helpers, and simplifies equivalent location and app-opening branches.

Merge readiness

✅ Ready for maintainer review

This remains a useful, bounded cleanup absent from the reviewed main branch. No actionable correctness or security defect was found; collaborator-authored work is also protected from automatic closure.

Priority: P3
Reviewed head: 918243fb0c47e66415e8dbd6d2119b91fa178a06

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, behavior-preserving cleanup with no supported blocking finding and contributor-reported validation.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-author exemption applies. The captured body reports real EventKit-backed CLI comparisons and completion-output parity at this head; those results were not independently executed, and do not separately demonstrate native app opening or location creation.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator-author exemption applies. The captured body reports real EventKit-backed CLI comparisons and completion-output parity at this head; those results were not independently executed, and do not separately demonstrate native app opening or location creation.
Evidence reviewed	10 items	Verified introduced scope: The pinned base-to-head diff contains seven CLI source files, with 27 additions and 63 deletions; it changes no dependencies, public library APIs, persistence formats, or workflows. Registry and completion equivalence: The shared registry retains all 15 commands in their existing order. Completion reads the registry only when its handler executes, avoiding recursive static initialization. Deleted helpers have no callers: Searching base source and tests finds only the removed declarations and their internal error references; active option decoding and required-argument handling remain.
Findings	None	None.
Security	None	None.

How this fits together

remindctl translates terminal arguments into Apple Reminders operations through RemindCore and EventKit. Its command registry also supplies help and shell completion.

flowchart TD
  A[Terminal arguments] --> B[Command router]
  C[Shared command registry] --> B
  C --> D[Help and shell completion]
  B --> E[Parsed values and runtime options]
  E --> F[Command handlers]
  F --> G[Apple Reminders and terminal output]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	Production +27/-63 (net -36); tests +0/-0	The cleanup reduces production code without adding a parallel implementation.

Technical review

Best possible solution:

Use one immutable command registry and compiler-checked handlers while preserving existing CLI behavior.

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

Not applicable: this PR removes duplication and unchecked concurrency declarations rather than reporting a runtime failure; no introduced defect was identified.

Is this the best way to solve the issue?

Yes. Sharing the existing registry and checking its handler types addresses the duplication narrowly, and the simplified branches preserve their existing decisions.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P3: This is a bounded internal cleanup that preserves documented command behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-author exemption applies. The captured body reports real EventKit-backed CLI comparisons and completion-output parity at this head; those results were not independently executed, and do not separately demonstrate native app opening or location creation.

Evidence

What I checked:

• Verified introduced scope: The pinned base-to-head diff contains seven CLI source files, with 27 additions and 63 deletions; it changes no dependencies, public library APIs, persistence formats, or workflows. (918243fb0c47)
• Registry and completion equivalence: The shared registry retains all 15 commands in their existing order. Completion reads the registry only when its handler executes, avoiding recursive static initialization. (Sources/remindctl/Commands/CompletionCommand.swift:35, 918243fb0c47)
• Deleted helpers have no callers: Searching base source and tests finds only the removed declarations and their internal error references; active option decoding and required-argument handling remain. (Sources/remindctl/ParsedValues+Decode.swift:4, 1b71fb003087)
• Existing behavior preserved: The open command retains its historical listing path and resolves targeted URLs through the same resolver. The add command retains the same missing-location error, default radius, and proximity selection. (Sources/remindctl/Commands/OpenCommand.swift:59, 918243fb0c47)
• Affirmative dependency contract: CommandSpec directly stores Commander.CommandSignature and passes Commander.ParsedValues to its handler. Package.resolved pins steipete/Commander 0.2.4 at bd219c4ee9032fee3e009856f81fcc6ec09a85f4, making that dependency's Sendable contract relevant. (Sources/remindctl/CommandSpec.swift:7, 918243fb0c47)
• Pinned signature supports checked Sendable: The pinned dependency declares CommandSignature and its stored definition types Sendable. Its full root AGENTS.md concerns synchronization when modifying Commander; this PR does not modify that dependency. (Sources/Commander/CommandSignature.swift:7, bd219c4ee903)

Likely related people:

• Peter Steinberger: Raw commit 3bc45c3 adds Sources/remindctl/Commands/CompletionCommand.swift:8 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 3bc45c3bba93; files: Sources/remindctl/Commands/CompletionCommand.swift)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (1 earlier review cycle)

• reviewed 2026-09-13T06:28:37.795Z sha 918243f :: needs maintainer review before merge. :: none