fix(cli): stop echoing value-bearing --project and --target arguments

[roodboi]

Summary

Follow-up to #308, which made hack env and hack host refuse value-bearing arguments without echoing them. Two echoes were left:

1. --project on other commands. The command slugged the argument and printed the slug in Unknown project "<slug>". For example, --project x=secret printed Unknown project "xsecret".
2. --target on up/down/restart. The refusal printed Invalid --target value: <argument>. It also happened late, after project discovery and the Docker check.

Policy: a value is never echoed, logged, passed to a child argv or written into a file name. Well-formed identifiers can still be echoed.

Changes

• src/cli/project-selector.ts (new). Holds parseProjectSelectorOption, moved here from env-arguments.ts, plus unknownProjectMessage and resolveRegisteredProjectOption.
  • An argument that contains =, or any character outside PROJECT_SELECTOR_PATTERN, is refused with fixed text before the registry is read.
  • Unknown project "<name>" names the project only when it was typed in canonical form. Otherwise the message is Unknown project. Run 'hack init' ....
• Shared resolver. These resolvers now use resolveRegisteredProjectOption: project.ts (up/down/restart/ps/run/exec/logs/open), branch.ts, config.ts, tui.ts, project-admin.ts and env.ts.
• runCli check. runCli now parses --project for every command that declares optProject, before the handler runs, in the same way as the shared --env check. This covers the filter commands (status, usage, projects, projects prune, host ps) and the unsupported remote/gateway commands too.
• Native Compose selectors. native-compose-selection.ts and native-compose-adoption-command.ts use the same parser.
• Project filters. status/projects (src/commands/projects.ts, resolveListingFilter) name the filter only when it was typed canonically or selects a registered project, whose name the listing shows anyway. Otherwise:
  • the panel prints No projects matched the --project filter.;
  • --json reports "filter": null with "filter_redacted": true (the field used to carry the slug, e.g. "filter": "sk-live-secret-9z" for --project Sk_Live_Secret_9z);
  • the daemon is skipped and the filter is matched in process, because hackd's /v1/projects echoes its filter query back. The slug never leaves the process.
• --target on up/down/restart. The fixed message is now Invalid --target value. Expected one of: auto, local, remote., thrown as a CliUsageError. Each handler checks --target first, before project discovery or runtime work.
• Legacy alias spellings that already worked still work: My_App, my_app, MY-APP and my app all select my-app.
• Docs. docs/cli.md documents the --project echo rule and filter_redacted.

Validation

• New tests/project-target-argument-redaction-cli.test.ts runs the real CLI in subprocesses. Isolation: a temp HOME/HACK_HOME/global config, an isolated DOCKER_CONFIG, a PATH that holds only git, and the spawn-argv recorder. Each case checks that the canary, including its case-folded/slugged form, is absent from stdout, stderr, child argv/env and file names, and that no child other than git started.
  • Value-bearing --project: 3 values (x=…, ….x, …:x) against every command path that declares optProject in CLI_SPEC. The list is derived and guarded with arrayContaining.
  • Unregistered non-canonical --project: checked on 15 project-resolving commands. The test also confirms that a canonical name is still printed.
  • Listing filters: status, projects, projects prune --dry-run, and their --json variants (plus projects --json --summary) never echo a non-canonical unmatched filter. The JSON assertions check filter: null, filter_redacted: true, the canonical name for a canonical filter, and my-app for the registered alias My_App.
  • Daemon query: a fake hackd on a Unix socket (same version, echoes filter like the real payload) proves that an unnameable filter never reaches /v1/projects. Canonical and registered-alias filters still reach it, so the check is not vacuous.
  • Legacy aliases: the alias spellings of a registered project still resolve (config get).
  • --target: up/down/restart --target x=… and --target <Alias> are refused in an empty cwd with the fixed message.
• tests/project-execution-routing.test.ts now expects a CliUsageError with the exact fixed message. tests/env-key-argument-redaction-cli.test.ts imports from the new module.
• Mutation testing: 7 mutations, all caught by the new tests:
  • removing the runCli check
  • always naming the unknown project
  • skipping the selector pattern
  • echoing --target
  • checking --target late
  • echoing a slugged listing filter
  • refusing alias spellings
• Rework mutations (each caught, then reverted): restoring the previous projects.ts; sending the redacted filter to the daemon; emitting a non-null JSON filter when redacted; treating only canonical input as nameable; treating every filter as nameable.
• Checks run:
  • bun test on the new test file, project-execution-routing, env-key-argument-redaction-cli, integration-ownership, config-command, native-compose-selection, experimental-gating, native-config-command, mcp-inspect-tools, projects-command, projects-registry, projects-prune and cli-command: all pass.
  • bun run --cwd packages/cli typecheck: clean.
  • bun run --cwd packages/cli check: 0 errors. The 34 warnings come from files this PR does not change.
  • bun run docs:cli-reference: no diff, because the CLI surface is unchanged.

Remaining gaps

• remote and gateway (unsupported) keep their own sanitizeProjectSlug resolvers. The new runCli check refuses value-bearing arguments for them, but a well-formed non-canonical name such as My_App is still printed in slug form in their "Unknown project" message.
• usage and host ps are covered for value-bearing arguments only. A well-formed filter makes them read the process table with ps, so the test does not run that case.
• The unsupported supervisor extension (hack x supervisor ... --project) parses --project itself, outside CLI_SPEC and the runCli check. Its resolver would print Unknown project "<slug>", and its "Extension disabled" hint echoes the raw argv. This is the same on next and needs a follow-up issue.
• Full bun run test and hosted CI were not run locally.

🤖 Generated with Claude Code

---

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