[roodboi]

Small CLI follow-ups to #368 and #370 (HACK-1339, and the code parts of HACK-1338; not the M3 host gate).

Root cause

• Missing project codes differed (HACK-1339 item 1). requireProjectContext threw a plain MissingProjectContextError. Only up, down and restart caught it and mapped it to E_PROJECT_NOT_FOUND. Every other project command let it reach the top-level handler, which reported it as E_UNEXPECTED under --json and, without --json, printed a stack trace. Before this change:
  • hack ps -p <empty dir> --json and hack logs -p <empty dir> --json reported E_UNEXPECTED.
  • hack up -p <empty dir> --json and down reported E_PROJECT_NOT_FOUND.
• Empty native run selections were ambiguous (HACK-1338 item 5). On the native runtime, hack run --env "" resolved to the base env (null) and --profile "" resolved to no profiles ([]). Each was then compared with the running selection. Against a project started with the base env and no profiles, both silently matched and the command ran. Against any other selection, they were refused with the "does not match" message. So an empty value meant different things depending on what was running.

Fix

• MissingProjectContextError now extends HackCliError with code E_PROJECT_NOT_FOUND. Most commands already used that code, and the MCP and target-inspect contracts use it too. ps, logs, run, exec and open now report the same envelope as up, down and restart. Without --json they print one closed E_PROJECT_NOT_FOUND line and no stack. The existing up/down/restart catch sites are unchanged.

• Native run: an empty --env or --profile is a closed E_USAGE usage error. Values that contain only whitespace (--env " ") or only commas (--profile " , ") count as empty. The check runs in runBackendSelection, before the value is resolved, the project is loaded, or any runtime request is made. The error message is exported as NATIVE_RUN_EMPTY_SELECTION_REFUSAL:

  Native hack run does not accept an empty --env or --profile value. Omit the option to use the running selection, or pass the env or profiles hack up started with. No command ran.

  Omitting both options still inherits the running selection. The Compose run path is unchanged: there, an empty --env still means the base layers.

• requireNativeRunSelection: removed the redundant run.effectiveEnvName === undefined || clause (item 7). A legacy mapping with no recorded env still refuses: undefined never equals a given selection, which is always a string or null. The existing legacy-mapping unit test still covers this.

• Docs:

  • docs/cli.md has a new "Option parsing" section. It describes per-command parsing and the residual edge (item 3): an option placed before the command name that is a flag in one command and takes a value in another is read as a flag. It also records the parse differences that fix(cli): parse options per resolved command so -p means --path again #370's old-versus-new comparison found (item 4). The only difference was the intended one: -p <dir> on a project command now sets --path. The section lists the edge cases that parse the same as before.
  • docs/cli.md now states the missing-project code.
  • docs/guides/native-candidate.md states the empty-value rule.

Tests (each checked by mutation)

• New tests/missing-project-error-code.test.ts. It spawns the source CLI with privateCliEnv and checks two things:

  • ps, logs, up, down and restart with -p <empty dir> --json all return {ok:false, error:{code:"E_PROJECT_NOT_FOUND", ...}}.
  • ps without --json prints exactly one ERROR: E_PROJECT_NOT_FOUND: ... line and no stack.

  Mutation: reverting the class to a plain Error fails the ps, logs and non-JSON ps tests.

• tests/native-run-selection-cli.test.ts:

  • Five new refusal cases: --env "", --env=, --env " ", --profile "" and --profile " , ". They run against a project started with the base env and no profiles, where the old code would have run the command. Each must print one closed E_USAGE line and make no runtime call.
  • One control case: omitting both options still runs.

  Mutations:

  • Dropping the env check fails 3 tests.
  • Matching only a literal "" profile fails the comma case.
  • Not trimming the env value fails the whitespace case.
  • Always refusing fails the 6 existing match and mismatch tests.

• tests/cli-per-command-options.test.ts (item 2): I mutated each branch of scanInvocation, scanPositional, scanOption, consumesNextToken, omitsOptionValue and representativeDeclarations, then ran the parser suites against each mutant. Two non-equivalent mutants survived, and I added a test for each:

  • A lone - is a positional, so it can start the child command. Mutation: treating - as an option.
  • After a command's own positional, a subcommand name is the child command. This uses a synthetic passthrough command that also has a subcommand. Mutation: not clearing subcommands after a positional.

  Both new tests fail under their mutation. Two mutants still survive, and both are equivalent:

  • Removing the includes("=") early return in scanOption: no long or short key can contain =.
  • Continuing the scan after "done": no subcommands remain, and no passthrough index is set.

• tests/cli-closed-error-output.test.ts (item 6):

  • The handler-usage-refusal test used the removed "restart with the requested selections first" string. It now uses the run handler's current CliUsageError ("Missing required argument: service").
  • A new test renders the current NATIVE_RUN_SELECTION_REFUSAL, raised by the real requireNativeRunSelection, as one coded E_USAGE line with no hint.
  • The --json usage test's stale "Native exec does not support --env." text is updated to the current exec refusal.

Evidence

• Bun 1.4.2 (mise x bun@1.4.2), base origin/next 16f4547 (which includes a25160d).
• bun run --cwd packages/cli typecheck: 0 errors. Root bun run check (includes privacy:check: ok): 0 errors. The changed files pass biome check cleanly.
• Focused suites, run locally: 176/176 across cli-per-command-options, cli-closed-error-output, native-run-selection-cli, missing-project-error-code, native-project-one-off, cli-passthrough-argv, cli-command, project-up-command, lifecycle-json, project-run-command, native-project-exec, cli-reference-docs and output-hygiene. Also 44/44 across env-key-argument-redaction-cli, cli-renderer-loading, integration-ownership and mcp.
• bun run docs:cli-reference: no change to docs/reference/cli.md, because the help surface is unchanged. No consumer agent guidance changed, so I did not regenerate the plugins. No package.json scripts changed, so nothing needed re-pinning.
• gitleaks 8.30.1 (gitleaks dir over a git log -p origin/next..HEAD export): no leaks.
• Full suite on the M3 at exactly 07306f2 (detached worktree, Bun 1.4.2, after bun run build:config-compiler): 7691 pass, 126 skip, 4 fail, across 549 files in 2750.78s. None of the 4 failures touch this change, and the same 4 also fail on unrelated branches run on the same M3:
  • repository catalog > the checked-in .hack/tasks.json recipes are all reviewed. On the M3 it fails with E_USAGE detached_checkout ("Detached linked worktree cannot select an instance implicitly"), because the M3 harness checks out a detached worktree. It passes locally on a branch checkout at this head. It also failed this way in the F20r3, G35, G36 and G41 runs.
  • Three native recovery tests in native-authored-process-incarnation and native-authored-project-recovery ("original capture uses its live session…", "new no-host death uses real read-only quiescence facts…" and "new no-host recovery retains original bindings on last-await"). These are timing-dependent. The identical set failed in the F20r3 run, and they also show up in the G35 and G41 runs.
  • I queued serial reruns of these files with --timeout 60000 at this head. The shared M3 CI lock stayed busy for over 100 minutes, so I cancelled the reruns before they got the lock. No lock or worktree was left behind.
• Focused suites on a trial merge with the current next (8e53df3), which merges cleanly: 68/68 across missing-project-error-code, native-run-selection-cli, cli-per-command-options, cli-closed-error-output, project-run-command and lifecycle-json.
• Hosted CI at 07306f2: every job passes except docker-e2e shard 3/4. That shard failed in pattern-p01-dependency-bootstrap with docker inspect <id>, then Error: No such object: the fixture container disappeared between listing and inspect. That scenario does not use the code this PR changes. I did not re-run the job.

Gaps

• The empty-value rule covers only the native one-off path (HACK_RUNTIME_BACKEND=native, nativeProjectOneOff). Two paths are unchanged:
  • The authored native-Compose run path (tryNativeComposeCommand), which prepares a new generation, still resolves --env "" as the base env.
  • Compose run, where an empty --env still means the base env.
• The P02 example README was not changed, to avoid churning the pattern fingerprints. The native guide carries the rule.
• The M3 host gate in HACK-1338 is out of scope.

Refs HACK-1339
Refs HACK-1338

🤖 Generated with Claude Code

[linear-code]

HACK-1339

HACK-1338

[blacksmith-sh]

Found 1 test failure on Blacksmith runners:

Failure

Test	View Logs
pattern-p01-dependency-bootstrap (181.9s) — docker inspect pattern fixture operation/ pattern-p01-dependency-bootstrap (181.9s) — docker inspect pattern fixture operation	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}