fix(cli): harden stash env — all 10 findings from the branch review

An 8-angle adversarial review of this branch confirmed 10 defects (plus one
skill nit); this commit fixes all of them:

1. --write's overwrite decision (refusal AND interactive confirm) now runs
   BEFORE minting — a declined overwrite previously discarded a live,
   shown-exactly-once access key, contradicting the file's own contract.
2. Stdout is now actually pipe-clean: every clack call routes chrome to
   stderr via { output: process.stderr }, so `stash env > prod.env` and
   pipes into dotenv consumers capture only the block. (clack defaults
   everything to stdout — the old comment's claim was wrong.)
3. This also fixes prompts rendering into redirected stdout (isInteractive
   is stdin-only): prompts on stderr stay visible on the terminal.
4. `--write <path>` is now a feature, not a parse trap: parseArgs put the
   path in values.write leaving flags.write undefined, silently printing
   secrets to stdout. main.ts passes values.write ?? flags.write and the
   command accepts a target path.
5. `--name` followed by another flag gets its own name_requires_value
   diagnostic instead of a false missing_name.
6. `stash env <positional>` is rejected with did-you-mean --name guidance
   instead of silently vanishing into the subcommand slot.
7. --json + --write now compose: the file is written and the JSON
   confirmation ({ status: 'written' }) is deliberately secret-free.
8. 0600 is enforced on overwrite too (writeFileSync's mode only applies on
   creation) via an explicit chmod.
9. All three API responses are zod-validated; non-base64 client_key is
   refused before Node's lenient decoder can transcode garbage; a service
   shape change can no longer print undefined into a credentials file.
10. The member role is pinned in the request (wire value verified lowercase
    in cts-common) AND asserted on the response — a non-member key is
    refused with revocation guidance, so the documented 'cannot mint admin
    keys' invariant is enforced, not assumed.
11. All exits go through CliExit (never deep process.exit), so run()
    records env outcomes for telemetry; cancel paths use CliExit(0). The
    three divergent dead-code exit trailers are gone.
12. skills/stash-cli: the bare --env-file mention is attributed to
    `supabase functions serve`, per the manifest-resolution rule.

Tests: 21 env unit tests (preflight-before-mint asserted via zero fetch
calls; chrome-on-stderr; role pinning; validation refusals; json+write
secret-free event; chmod-on-overwrite) and 4 e2e cases (all credential-free
pre-mint failures, including asserting error chrome lands on stderr, not
stdout). Full suite: 534 unit / 62 e2e green, code:check exit 0.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

Author: coderdan

.changeset/stash-env-mint-credentials.md

@@ -5,15 +5,24 @@
 `stash env` now works: it mints deployment credentials from your device-code
 session and prints them as env vars — no dashboard copy-paste. The command
 creates a fresh ZeroKMS client and a member-role CipherStash access key (named
-via `--name`), then emits `CS_WORKSPACE_CRN`, `CS_CLIENT_ID`, `CS_CLIENT_KEY`,
-and `CS_CLIENT_ACCESS_KEY` to stdout, `--write` (`.env.production.local`, mode
-0600), or `--json`. Creating access keys requires the admin role in the
-workspace; the minted key itself is always member — the CLI deliberately
-cannot mint admin keys.
+via `--name`; the role is pinned in the request and verified on the response —
+the CLI deliberately cannot mint admin keys), then emits `CS_WORKSPACE_CRN`,
+`CS_CLIENT_ID`, `CS_CLIENT_KEY`, and `CS_CLIENT_ACCESS_KEY`.
+
+Output goes to stdout by default — and stdout is pipe-clean (progress UI is on
+stderr), so `stash env --name x > prod.env` and pipes into secret stores are
+safe. `--write [path]` writes a file instead (default `.env.production.local`,
+enforced mode 0600 even when overwriting), confirming before overwriting and
+refusing non-interactively — always *before* anything is minted, so a refusal
+never discards the shown-exactly-once access key. `--json` emits NDJSON; with
+`--write` the confirmation event is deliberately secret-free. API responses
+are schema-validated so a service change can never print `undefined` into a
+credentials file. Creating access keys requires the admin role in the
+workspace.
 
 This is also the supported credential path for WASM/edge local development
 (Supabase Edge Functions, Cloudflare Workers, Deno), where the runtime cannot
 read the `~/.cipherstash` device profile: mint a key and feed it via
-`--env-file` or the platform's secret store.
+`supabase functions serve --env-file` or the platform's secret store.
 
 The `STASH_EXPERIMENTAL_ENV_CMD` gate is removed.

packages/cli/src/bin/main.ts

@@ -533,9 +533,17 @@ async function dispatch(
       break
     case 'env':
       await envCommand({
-        write: flags.write,
+        // parseArgs puts `--write path/x` in values and bare `--write` in
+        // flags — accept both so a path after --write targets that file
+        // instead of silently printing secrets to stdout.
+        write: values.write ?? flags.write,
         json: flags.json,
         name: values.name,
+        // `--name` followed by another flag (or nothing) is booleanised by
+        // parseArgs; surface it as its own error instead of missing_name.
+        nameMissingValue: flags.name === true,
+        // `stash env my-app` would otherwise vanish into `subcommand`.
+        unexpectedArg: subcommand ?? commandArgs[0],
       })
       break
     case 'manifest':

packages/cli/src/cli/registry.ts

@@ -545,10 +545,15 @@ export const registry: CommandGroup[] = [
           'admin keys) and is shown exactly once — pipe the output into your',
           'deployment secret store. Creating access keys requires your user to',
           'have the admin role in the workspace.',
+          '',
+          'Stdout carries only the dotenv block (or the --json events);',
+          'progress UI goes to stderr, so `stash env --name x > prod.env`',
+          'and pipes into secret stores are safe.',
         ].join('\n'),
         examples: [
           'env --name my-app-prod',
           'env --name my-app-prod --write',
+          'env --name staging --write .env.staging.local',
           'env --name edge-dev --json',
         ],
         flags: [
@@ -560,13 +565,14 @@ export const registry: CommandGroup[] = [
           },
           {
             name: '--write',
+            value: '[path]',
             description:
-              'Write the vars to .env.production.local (mode 0600) instead of printing them.',
+              'Write the vars to a file (default .env.production.local, mode 0600) instead of printing them. An existing file prompts before overwriting — and is refused non-interactively — before anything is minted.',
           },
           {
             name: '--json',
             description:
-              'Emit a single machine-readable JSON object (or a { status: "error" } envelope) instead of a dotenv block. Implies no prompts.',
+              'Emit machine-readable NDJSON (a { status: "minted" } object, or { status: "written" } with --write — deliberately secret-free since the secrets are in the file; failures are { status: "error" }). Implies no prompts.',
           },
         ],
       },