Skip to content

Fix CLI error-handling papercuts and make the gate pass on macOS#163

Merged
alexkroman merged 1 commit into
mainfrom
fix/cli-qa-papercuts-and-gate-portability
Jun 14, 2026
Merged

Fix CLI error-handling papercuts and make the gate pass on macOS#163
alexkroman merged 1 commit into
mainfrom
fix/cli-qa-papercuts-and-gate-portability

Conversation

@alexkroman

Copy link
Copy Markdown
Collaborator

Summary

Manual QA across the command surface (run via parallel subagents) surfaced a cluster of user-input errors mislabeled as internal "report a bug" failures, plus a few smaller inconsistencies. While verifying the fixes through scripts/check.sh, two macOS-only gate failures also turned up and are fixed here so the gate is green on both macOS and Linux.

CLI fixes

Command Before After
webhooks listen --port out-of-range port → Unexpected error … report a bug min=0/max=65535 → clean exit-2 validation error
init <tmpl> file/sub raw [Errno 20] Not a directory mid-scaffold rejected up front as a clean usage error
stream --redact-pii-sub bad value leaked a pydantic dump + errors.pydantic.dev URL now a PIISubstitutionPolicy enum → clean [hash|entity_name] choice error
clip --out-dir <file> "doesn't exist" (misleading) "is not a directory"
config path failed on a corrupt config.toml — the one command you'd use to find the broken file reports the location anyway (deferred parse error; real commands still re-raise it; a bad --env still wins)
llm (bad key) exit 1 + raw 401 dict body exit-4 auth_failure like transcribe; entitlement/proxy 403s keep their exit-1 passthrough
account commands two confusingly-different no-credentials messages reworded to explain why account data needs a browser session vs an API key
telemetry enable "✓ Telemetry enabled" even when DO_NOT_TRACK/AAI_TELEMETRY_DISABLED overrides it appends a note that the env kill-switch keeps it off

Gate fixes (scripts/check.sh) — macOS parity

  • brew audit: Homebrew 6+ disabled brew audit [path …]; a formula must be audited by name. The step now copies Formula/assembly.rb into an ephemeral local tap and audits it by name (works on macOS + Linuxbrew, old + new brew), with cleanup that survives set -e.
  • "no new escape hatches": the baseline count used git grep -E while the working tree used rg, which disagree on \b — macOS's ERE engine silently ignores it, so a pre-existing time.sleep made the working count exceed the baseline and failed the gate on macOS only. Both sides now use one matcher, git grep -P (PCRE), via shared hatch_base/hatch_work helpers (--untracked counts newly-added files the way rg did).
  • Also fixes test_validate_out_rejects_the_input_via_hard_link to tolerate case-insensitive filesystems (macOS).

Verification

./scripts/check.shAll checks passed (exit 0), including:

  • 2556 tests pass
  • 100% patch coverage on all changed source files
  • mutation gate: 16/16 mutants killed on changed lines
  • brew audit, escape-hatch gate, build + twine — all green

🤖 Generated with Claude Code

Manual QA across the command surface surfaced a cluster of user-input
errors that were mislabeled as internal "report a bug" failures, plus a
few smaller inconsistencies. Fixes:

- webhooks listen --port: add min=0/max=65535 so an out-of-range port is
  a clean exit-2 validation error, not a socket-layer crash.
- init <tmpl> file/sub: reject a target that descends through a file up
  front instead of failing mid-scaffold with a raw NotADirectoryError.
- stream --redact-pii-sub: make it a PIISubstitutionPolicy enum (like
  transcribe) so a bad value is a clean choice error, no pydantic dump.
- clip --out-dir: distinguish "is not a directory" from "doesn't exist".
- config path: report the file location even when config.toml is corrupt
  (defer the callback's parse error; real commands still re-raise it; a
  bad --env still wins).
- llm: a bad-key 401 now routes to the same clean exit-4 auth_failure as
  transcribe; entitlement/proxy 403s keep their exit-1 passthrough.
- account commands: reword the no-session message to explain why it
  differs from API-key commands.
- telemetry enable: note when an env kill-switch overrides the persisted
  choice.

Gate (scripts/check.sh) — fix two macOS-only failures:

- brew audit: Homebrew 6+ disabled `brew audit [path]`; audit the formula
  by name via an ephemeral local tap so it works on macOS and Linuxbrew.
- "no new escape hatches": baseline used `git grep -E` and the working
  tree used `rg`, which disagree on `\b` (ERE ignores it on macOS), so a
  pre-existing time.sleep failed the gate on macOS. Use `git grep -P` for
  both sides via shared helpers.

Also fix test_validate_out_rejects_the_input_via_hard_link to tolerate
case-insensitive filesystems (macOS).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@alexkroman alexkroman added this pull request to the merge queue Jun 13, 2026
Merged via the queue into main with commit 8fc05e2 Jun 14, 2026
16 checks passed
@alexkroman alexkroman deleted the fix/cli-qa-papercuts-and-gate-portability branch June 14, 2026 00:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants