@ultimat3/cli 21.0.0 → 22.0.0

package/src/cmd-new.ts

@@ -7,13 +7,16 @@ import { chmod } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { dedupe } from './cmd-generate';
+import { newSpec } from './cmd-new-spec';
 import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
-import { AppNameIsPathError, MissingPositionalError } from './errors';
+import { AppNameEmptyError, AppNameIsPathError, MissingPositionalError } from './errors';
 import type { Runner } from './exec';
+import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
+import { quoteArg } from './shell-quote';
 import type { GeneratedFile } from './templates';
 import { appFiles, EXECUTABLE_FILES, names, repoFiles, resourceFiles } from './templates';
 import { loadVersion } from './version-loader';
@@ -59,6 +62,17 @@ const GIT_STEPS: readonly (readonly string[])[] = [
 /** What `--no-git` records, so `data.git` has the same shape whichever way the flag went. */
 const NO_GIT: RepositoryInit = { initialized: false, committed: false, problem: SKIPPED };
 
+/** `--force` into a directory that already existed: its files are not ours to commit. */
+const PRE_EXISTING: RepositoryInit = {
+  initialized: false,
+  committed: false,
+  problem: 'the directory already existed, so nothing was committed — its files are yours',
+};
+
+/** Every flag the caller set, in the spelling that reproduces it (`invocation-flags.ts`). */
+const callerFlags = (ctx: CommandContext): readonly string[] =>
+  reproducedFlags(newCommand.spec, ctx.args);
+
 /**
  * A scaffold is a REPOSITORY, because three surfaces of this CLI already assume one and answered
  * `not a git repository` in a fresh app: `x affected`, `x ci` and `x pr`. It was four —
@@ -151,34 +165,7 @@ export function appNamePath(raw: string): { parent: string; base: string } | und
 }
 
 export const newCommand: CliCommand = {
-  spec: {
-    name: 'new',
-    summary: 'scaffold a new Ultimate monorepo that already runs',
-    // Every flag the table below declares, in the spelling that turns it off where the default is
-    // on: the usage line offered `--no-example` while the table listed `--example`, and a reader
-    // had to reconcile the two to answer "which one do I get if I type neither".
-    usage: 'x new <name> [--dir path] [--no-example] [--no-git] [--dry-run] [--force] [--json]',
-    flags: [
-      { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
-      {
-        // The summary carries the default and the negation because the page has to answer "which
-        // one do I get if I type neither": the usage line offered `--no-example`, this table said
-        // `--example`, and `default: true` is a field only `--json` renders. 136 files against 109.
-        name: 'example',
-        type: 'boolean',
-        summary: 'include the example feature slice (default: on; --no-example for an empty app/)',
-        default: true,
-      },
-      {
-        name: 'git',
-        type: 'boolean',
-        summary: 'git init and commit the scaffold (default: on; --no-git for a bare directory)',
-        default: true,
-      },
-      { name: 'dry-run', type: 'boolean', summary: 'print the file list, write nothing' },
-      { name: 'force', type: 'boolean', summary: 'write into a directory that already exists' },
-    ],
-  },
+  spec: newSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const raw = ctx.args.positionals[0];
     // The class, not a hand-built finding with the same code: `MissingPositionalError` is what
@@ -202,6 +189,13 @@ export const newCommand: CliCommand = {
       throw new AppNameIsPathError({ name: raw, invocation: invocationOf(ctx, 'new'), ...path });
     }
     const app = names(raw);
+    if (app.kebab === '') {
+      throw new AppNameEmptyError({
+        name: raw,
+        invocation: invocationOf(ctx, 'new'),
+        flags: callerFlags(ctx),
+      });
+    }
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);
     const options: NewAppOptions = { name: raw, example: ctx.args.flags.get('example') !== false };
 
@@ -224,22 +218,33 @@ export const newCommand: CliCommand = {
           {
             code: 'X_GENERATE_CONFLICT',
             cause: `${target} already exists`,
-            fix: `x new ${app.kebab} --force, or choose another name`,
+            // The invocation the caller ran, with every flag it set: dropping `--dir` wrote a
+            // second app into the cwd, and the literal `x` is not installed under create-ultimate.
+            fix: `${[invocationOf(ctx, 'new'), quoteArg(app.kebab), ...callerFlags(ctx), '--force'].join(' ')}   # or choose another name`,
             docs: ERROR_DOCS_URL,
             at: target,
           },
         ],
       };
     }
+    // Read BEFORE writing: `--force` into a directory that already held files must never
+    // `git add -A && git commit` them — they are the user's, and `x new` did not write them.
+    const existed = existsSync(target);
     const written = await writeNewApp(target, options);
     const git =
-      ctx.args.flags.get('git') === false ? NO_GIT : await initRepository(ctx.runner, target);
+      ctx.args.flags.get('git') === false
+        ? NO_GIT
+        : existed
+          ? PRE_EXISTING
+          : await initRepository(ctx.runner, target);
     const lines = [msg('cli.new.wrote', { count: written.files.length, dir: target })];
-    if (git.problem !== null && git.problem !== SKIPPED) {
+    if (git.problem !== null && git.problem !== SKIPPED && git !== PRE_EXISTING) {
       lines.push(msg('cli.new.noRepository', { problem: git.problem }));
       // Raw, unlike the two prose lines around it: this one is an instruction to run verbatim, and
       // a translated command is a broken one (`packages/cli/CLAUDE.md`).
-      lines.push(`  run: cd ${target} && git init && git add -A && git commit -m 'x new'`);
+      lines.push(
+        `  run: cd ${quoteArg(target)} && git init && git add -A && git commit -m 'x new'`,
+      );
     }
     return {
       ok: true,

package/src/cmd-policy-spec.ts

@@ -0,0 +1,13 @@
+// `x policy`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-policy.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const policySpec: CommandSpec = {
+  name: 'policy',
+  summary: 'which clause decided a permission, and why',
+  usage: 'x policy [list|explain <subject>] [--json]',
+  requiresApp: true,
+  subcommands: ['list', 'explain'],
+  defaultSubcommand: 'list',
+};

package/src/cmd-policy.ts

@@ -5,11 +5,11 @@
 import { nearestName } from '@ultimat3/core';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { policySpec } from './cmd-policy-spec';
 import type { CliCommand, CommandContext } from './command';
 import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
-
 import type { DeclarationExplanation } from './policy-facts';
 import { explainPolicy, knownPolicySubjects, listPolicy } from './policy-facts';
 import { renderTable } from './table';
@@ -123,14 +123,7 @@ function runExplain(ctx: CommandContext, findings: readonly Finding[]): CommandR
 }
 
 export const policyCommand: CliCommand = {
-  spec: {
-    name: 'policy',
-    summary: 'which clause decided a permission, and why',
-    usage: 'x policy [list|explain <subject>] [--json]',
-    requiresApp: true,
-    subcommands: ['list', 'explain'],
-    defaultSubcommand: 'list',
-  },
+  spec: policySpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('policy', ctx.cwd).dir;
     const { findings } = await loadApp(root);

package/src/cmd-pr-spec.ts

@@ -0,0 +1,39 @@
+// `x pr`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-pr.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const PR_SUBCOMMANDS = ['review', 'resolve', 'reply'] as const;
+
+export const prSpec: CommandSpec = {
+  name: 'pr',
+  summary: 'inline review threads: list them with their ids, resolve one, reply in one',
+  usage:
+    'x pr review [--pr <n>] [--repo owner/name] [--all] [--full] | x pr resolve <thread-id> | x pr reply <thread-id> --body "…"',
+  subcommands: PR_SUBCOMMANDS,
+  flags: [
+    { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
+    { name: 'pr', type: 'string', summary: 'pull request number; this branch own by default' },
+    // Scoped to the subcommand each summary already names: `resolve` and `reply` WRITE to
+    // somebody else's pull request, and a flag they silently ignore is a flag whose caller
+    // believed it did something to a request that cannot be re-run.
+    {
+      name: 'all',
+      type: 'boolean',
+      summary: 'review: resolved threads too, not just open ones',
+      subcommands: ['review'],
+    },
+    {
+      name: 'full',
+      type: 'boolean',
+      summary: 'review: whole comment bodies, never truncated',
+      subcommands: ['review'],
+    },
+    {
+      name: 'body',
+      type: 'string',
+      summary: 'reply: the comment text to post in the thread',
+      subcommands: ['reply'],
+    },
+  ],
+};

package/src/cmd-pr.ts

@@ -5,6 +5,7 @@
 // `reviewDecision` outlives the push that answered it, and a RESOLVED thread is a closed
 // conversation rather than a fixed finding.
 
+import { PR_SUBCOMMANDS, prSpec } from './cmd-pr-spec';
 import type { CliCommand, CommandContext } from './command';
 import {
   BadFlagError,
@@ -13,6 +14,7 @@ import {
   UnknownCommandError,
 } from './errors';
 import { parseIntFlag } from './flag-number';
+import { commentBlock } from './foreign-text';
 import { PrNotFoundError, resolvePrNumber, resolveRepo } from './gh-target';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
@@ -20,7 +22,7 @@ import { flagBool, flagString } from './parse';
 import type { PrReviewReport, PrThread } from './pr-threads';
 import { fetchReviewReport, replyToThread, resolveThread, THREAD_PAGE } from './pr-threads';
 
-export const PR_SUBCOMMANDS = ['review', 'resolve', 'reply'] as const;
+export { PR_SUBCOMMANDS } from './cmd-pr-spec';
 
 /**
  * Every catalog key this command renders, declared. `msg()` answers `⟦key⟧` for a key nobody
@@ -51,38 +53,7 @@ export const PR_MESSAGE_KEYS = [
 export const BODY_LINES = 20;
 
 export const prCommand: CliCommand = {
-  spec: {
-    name: 'pr',
-    summary: 'inline review threads: list them with their ids, resolve one, reply in one',
-    usage:
-      'x pr review [--pr <n>] [--repo owner/name] [--all] [--full] | x pr resolve <thread-id> | x pr reply <thread-id> --body "…"',
-    subcommands: PR_SUBCOMMANDS,
-    flags: [
-      { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
-      { name: 'pr', type: 'string', summary: 'pull request number; this branch own by default' },
-      // Scoped to the subcommand each summary already names: `resolve` and `reply` WRITE to
-      // somebody else's pull request, and a flag they silently ignore is a flag whose caller
-      // believed it did something to a request that cannot be re-run.
-      {
-        name: 'all',
-        type: 'boolean',
-        summary: 'review: resolved threads too, not just open ones',
-        subcommands: ['review'],
-      },
-      {
-        name: 'full',
-        type: 'boolean',
-        summary: 'review: whole comment bodies, never truncated',
-        subcommands: ['review'],
-      },
-      {
-        name: 'body',
-        type: 'string',
-        summary: 'reply: the comment text to post in the thread',
-        subcommands: ['reply'],
-      },
-    ],
-  },
+  spec: prSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     // No `defaultSubcommand`: `resolve` and `reply` both WRITE to a pull request, so "whatever the
     // caller left out" is not a safe guess for any of the three.
@@ -201,38 +172,7 @@ function threadLines(thread: PrThread, bodyLines: number): readonly string[] {
   return out;
 }
 
-const BLOCK_OPEN = '<comment id=';
-const BLOCK_CLOSE = '</comment>';
-
-/**
- * The fence, as a READER would parse it rather than as this file spells it.
- *
- * Two literal `replaceAll`s were the whole neutralisation, and markup is not spelled one way:
- * `</comment >`, `</COMMENT>` and `< comment id=` all end or open a block for anything reading
- * tags, and none of the three matched. One pattern over `<`, an optional `/`, and whitespace
- * around a case-insensitive `comment` covers every spelling of the delimiter; the escape goes on
- * the `<`, so what the reviewer wrote after it survives byte for byte.
- */
-const BLOCK_DELIMITER = /<(\s*\/?\s*comment\b)/gi;
-
-/**
- * One comment body, fenced and labelled with the thread id it came from — `@ultimat3/ai`'s
- * `documentBlock` (`rag.ts`), applied to the other place foreign text enters an agent's context.
- * `x pr review` exists because an agent cannot read the GitHub web UI, and a review body is
- * written by anyone who can comment on the pull request: rendered as bare indented text it arrived
- * in that agent's context indistinguishable from the command's own output, which is prompt
- * injection with a shell attached.
- *
- * The fence is neutralised INSIDE the payload rather than deleted, so every word the reviewer
- * wrote still reads, and the label is stripped of the three characters that would end the
- * attribute. Influence only, and deliberately not sold as more: a fence tells a reader this text
- * is data, and it can never stop one that decides otherwise.
- */
-export function commentBlock(id: string, lines: readonly string[]): readonly string[] {
-  const label = id.replaceAll('"', "'").replaceAll('>', ')').replaceAll('<', '(');
-  const body = lines.map((line) => line.replace(BLOCK_DELIMITER, '<\\$1'));
-  return [`${BLOCK_OPEN}"${label}">`, ...body, BLOCK_CLOSE];
-}
+export { commentBlock };
 
 /**
  * A review body is prose written for a browser: the ones in this repo run to six thousand

package/src/cmd-registries-spec.ts

@@ -0,0 +1,32 @@
+// `x actions`, `x queries` and `x entities`' declarations, apart from their body: the parser, `x help`
+// and the `errors` step read them without loading `cmd-registries.ts` and the three registries it
+// projects, which `registry.ts` imports only when one of the commands runs.
+
+import type { CommandSpec } from './parse';
+
+export const actionsSpec: CommandSpec = {
+  name: 'actions',
+  summary: 'the action registry: input/output schema, policy, tags, MCP exposure',
+  usage: 'x actions [list|describe <name>] [--json]',
+  subcommands: ['list', 'describe'],
+  defaultSubcommand: 'list',
+  requiresApp: true,
+};
+
+export const queriesSpec: CommandSpec = {
+  name: 'queries',
+  summary: 'the query registry: schema, policy, live, cache tags',
+  usage: 'x queries [list|describe <name>] [--json]',
+  subcommands: ['list', 'describe'],
+  defaultSubcommand: 'list',
+  requiresApp: true,
+};
+
+export const entitiesSpec: CommandSpec = {
+  name: 'entities',
+  summary: 'the entity registry: columns, invariants, indexes, tenancy',
+  usage: 'x entities [list|describe <name>] [--json]',
+  subcommands: ['list', 'describe'],
+  defaultSubcommand: 'list',
+  requiresApp: true,
+};

package/src/cmd-registries.ts

@@ -13,12 +13,12 @@ import type { AnyQuery, QueryDescriptor } from '@ultimat3/query';
 import { describeQueries, getQuery } from '@ultimat3/query';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { actionsSpec, entitiesSpec, queriesSpec } from './cmd-registries-spec';
 import type { CliCommand, CommandContext } from './command';
 import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import type { CommandSpec } from './parse';
-
 import { renderTable } from './table';
 
 /**
@@ -53,14 +53,7 @@ interface RegistryKind<D extends { readonly name: string }, Raw extends { descri
 const ACTIONS: RegistryKind<ActionDescriptor, AnyAction> = {
   kind: 'actions',
   singular: 'action',
-  spec: {
-    name: 'actions',
-    summary: 'the action registry: input/output schema, policy, tags, MCP exposure',
-    usage: 'x actions [list|describe <name>] [--json]',
-    subcommands: ['list', 'describe'],
-    defaultSubcommand: 'list',
-    requiresApp: true,
-  },
+  spec: actionsSpec,
   header: ['name', 'verb', 'resource', 'path', 'capability', 'mcp'],
   list: describeActions,
   find: getAction,
@@ -71,14 +64,7 @@ const ACTIONS: RegistryKind<ActionDescriptor, AnyAction> = {
 const QUERIES: RegistryKind<QueryDescriptor, AnyQuery> = {
   kind: 'queries',
   singular: 'query',
-  spec: {
-    name: 'queries',
-    summary: 'the query registry: schema, policy, live, cache tags',
-    usage: 'x queries [list|describe <name>] [--json]',
-    subcommands: ['list', 'describe'],
-    defaultSubcommand: 'list',
-    requiresApp: true,
-  },
+  spec: queriesSpec,
   header: ['name', 'live', 'capability', 'tags', 'ttlMs'],
   list: describeQueries,
   find: getQuery,
@@ -97,14 +83,7 @@ const QUERIES: RegistryKind<QueryDescriptor, AnyQuery> = {
 const ENTITIES: RegistryKind<EntityDescription, RegistryEntry> = {
   kind: 'entities',
   singular: 'entity',
-  spec: {
-    name: 'entities',
-    summary: 'the entity registry: columns, invariants, indexes, tenancy',
-    usage: 'x entities [list|describe <name>] [--json]',
-    subcommands: ['list', 'describe'],
-    defaultSubcommand: 'list',
-    requiresApp: true,
-  },
+  spec: entitiesSpec,
   header: ['name', 'table', 'columns', 'invariants', 'indexes', 'orgScoped'],
   list: describeEntities,
   find: getEntity,

package/src/cmd-routes-spec.ts

@@ -0,0 +1,12 @@
+// `x routes`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-routes.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const routesSpec: CommandSpec = {
+  name: 'routes',
+  summary: 'the route table: path, surface, render mode, hydrate, offline',
+  usage: 'x routes [--surface site|app|api|shared] [--json]',
+  requiresApp: true,
+  flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],
+};

package/src/cmd-routes.ts

@@ -8,6 +8,7 @@ import type { RouteDescriptor, Surface } from '@ultimat3/render';
 import { describeRoutes, SURFACES } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { routesSpec } from './cmd-routes-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
 import { msg } from './messages';
@@ -65,13 +66,7 @@ export function readSurfaceFilter(raw: string | undefined): Surface | undefined
 }
 
 export const routesCommand: CliCommand = {
-  spec: {
-    name: 'routes',
-    summary: 'the route table: path, surface, render mode, hydrate, offline',
-    usage: 'x routes [--surface site|app|api|shared] [--json]',
-    requiresApp: true,
-    flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],
-  },
+  spec: routesSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('routes', ctx.cwd).dir;
     // Read before the app is loaded: a typo must not cost a boot to report, the rule `x mcp`'s

package/src/cmd-secrets-spec.ts

@@ -0,0 +1,19 @@
+// `x secrets`'s declaration, apart from its body: the parser, `x help` and the `errors` step
+// read it without loading `cmd-secrets.ts`, which `registry.ts` imports only when the command runs.
+
+import { ENV_SCHEMA_EXPORT } from './app-env';
+import type { CommandSpec } from './parse';
+
+export const SECRETS_SUBCOMMANDS = ['show', 'init', 'edit', 'set', 'rotate'] as const;
+
+export const secretsSpec: CommandSpec = {
+  name: 'secrets',
+  summary: `the committed encrypted secrets, decrypted into the ${ENV_SCHEMA_EXPORT} variables of the same names`,
+  usage: 'x secrets [show|init|edit|set <NAME>|rotate] [--json]',
+  requiresApp: true,
+  subcommands: [...SECRETS_SUBCOMMANDS],
+  // The bare `x secrets` answers without a key ever leaving the file. Declared, not inherited
+  // from the array's order — `init`, `edit`, `set` and `rotate` all write.
+  defaultSubcommand: 'show',
+  flags: [],
+};

package/src/cmd-secrets.ts

@@ -30,6 +30,7 @@ import {
 } from '@ultimat3/core';
 import { ENV_SCHEMA_EXPORT, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
+import { secretsSpec } from './cmd-secrets-spec';
 import type { CliCommand, CommandContext } from './command';
 import {
   MissingPositionalError,
@@ -39,9 +40,11 @@ import {
 } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
+import { recoverRotation, rotateMasterKey } from './secrets-rotation';
+import { shredOnSignal } from './signal-shred';
 import { renderTable } from './table';
 
-export const SECRETS_SUBCOMMANDS = ['show', 'init', 'edit', 'set', 'rotate'] as const;
+export { SECRETS_SUBCOMMANDS } from './cmd-secrets-spec';
 
 /** In order of precedence. `VISUAL` outranks `EDITOR` by POSIX convention on an interactive tty. */
 export const EDITOR_VARS = ['VISUAL', 'EDITOR'] as const;
@@ -74,9 +77,10 @@ interface Session {
   readonly key: MasterKeyRef;
 }
 
-const open = (ctx: CommandContext, subcommand: string): Session => {
+/** The root and its key — after finishing or abandoning a rotation a crash interrupted. */
+const open = async (ctx: CommandContext, subcommand: string): Promise<Session> => {
   const root = requireAppRoot(`secrets ${subcommand}`, ctx.cwd).dir;
-  return { root, key: requireMasterKey(root, ctx.env) };
+  return { root, key: await recoverRotation(root, requireMasterKey(root, ctx.env)) };
 };
 
 const names = (values: SecretValues): readonly string[] => Object.keys(values).sort();
@@ -148,7 +152,7 @@ async function init(ctx: CommandContext): Promise<CommandResult> {
  * of the two harms. Leaving decrypted values on disk so they can be recovered is the larger one.
  */
 async function edit(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
-  const { root, key } = open(ctx, 'edit');
+  const { root, key } = await open(ctx, 'edit');
   const editor = EDITOR_VARS.map((name) => ctx.env[name]).find(
     (value): value is string => value !== undefined && value.trim().length > 0,
   );
@@ -157,9 +161,9 @@ async function edit(ctx: CommandContext, io: SecretsIo): Promise<CommandResult>
   const dir = await mkdtemp(join(tmpdir(), 'ultimate-secrets-'));
   const buffer = join(dir, 'secrets.json');
   const shred = (): void => rmSync(dir, { recursive: true, force: true });
-  // A `finally` does not run for a signal, and Ctrl-C inside an editor kills this process too.
-  process.once('SIGINT', shred);
-  process.once('SIGTERM', shred);
+  // A `finally` does not run for a signal, and Ctrl-C inside an editor kills this process too —
+  // after the shred, which `shredOnSignal` runs and then re-raises the signal for.
+  const unlisten = shredOnSignal(shred);
   try {
     await Bun.write(buffer, serializeSecretValues(before));
     // `$EDITOR` may carry flags (`code --wait`), and there is no shell here to split them.
@@ -195,8 +199,7 @@ async function edit(ctx: CommandContext, io: SecretsIo): Promise<CommandResult>
     };
   } finally {
     shred();
-    process.off('SIGINT', shred);
-    process.off('SIGTERM', shred);
+    unlisten();
   }
 }
 
@@ -217,7 +220,7 @@ async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
       example: 'printf %s "$TOKEN" | x secrets set STRIPE_KEY --json',
     });
   }
-  const { root, key } = open(ctx, 'set');
+  const { root, key } = await open(ctx, 'set');
   const before = await readSecretsFile(root, key);
   // Exactly one trailing newline, because `echo` adds one and a secret with a stray `\n` fails
   // against the service it authenticates to with an error that names nothing.
@@ -242,23 +245,18 @@ async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
 }
 
 /**
- * A new master key over the same values. The committed file is written FIRST and the key file last,
- * because only one of the two can be recovered: `secrets.enc.json` is in git, and a master key that
- * is half-overwritten is gone. Interrupted between the two writes, the old key still on disk meets
- * a file it cannot open — `X_SECRETS_KEY_MISMATCH`, whose fix restores the file from git.
+ * A new master key over the same values: staged beside the old one, the file sealed with it, then
+ * made live (`rotateMasterKey`). Sealed first with the key file written last, a crash between the
+ * two left a committed file no key on disk could open.
  */
 async function rotate(ctx: CommandContext): Promise<CommandResult> {
-  const { root, key } = open(ctx, 'rotate');
+  const { root, key } = await open(ctx, 'rotate');
   const values = await readSecretsFile(root, key);
   const previous = await masterKeyIdOf(key);
-  const next: MasterKeyRef = {
-    hex: generateMasterKey(),
-    source: 'file',
-    at: masterKeyPath(root),
-  };
-  await writeSecretsFile(root, values, next);
+  // Ignored BEFORE any key file is written, staged one included; the order inside is
+  // `secrets-rotation.ts`'s: stage the key, seal, then rename it live.
   await ensureIgnored(root);
-  writeMasterKeyFile(root, next.hex);
+  const next = await rotateMasterKey(root, values);
   const keyId = await masterKeyIdOf(next);
   return {
     ok: true,
@@ -286,7 +284,7 @@ async function rotate(ctx: CommandContext): Promise<CommandResult> {
  * `x secrets edit`. A `--reveal` flag would be a second path that `--json` could not honour.
  */
 async function show(ctx: CommandContext): Promise<CommandResult> {
-  const { root, key } = open(ctx, 'show');
+  const { root, key } = await open(ctx, 'show');
   const values = await readSecretsFile(root, key);
   const schema = await loadEnvSchema(root);
   const summaries = describeSecrets(values);
@@ -337,17 +335,7 @@ async function show(ctx: CommandContext): Promise<CommandResult> {
 
 export function createSecretsCommand(io: SecretsIo): CliCommand {
   return {
-    spec: {
-      name: 'secrets',
-      summary: `the committed encrypted secrets, decrypted into the ${ENV_SCHEMA_EXPORT} variables of the same names`,
-      usage: 'x secrets [show|init|edit|set <NAME>|rotate] [--json]',
-      requiresApp: true,
-      subcommands: [...SECRETS_SUBCOMMANDS],
-      // The bare `x secrets` answers without a key ever leaving the file. Declared, not inherited
-      // from the array's order — `init`, `edit`, `set` and `rotate` all write.
-      defaultSubcommand: 'show',
-      flags: [],
-    },
+    spec: secretsSpec,
     async run(ctx: CommandContext): Promise<CommandResult> {
       switch (ctx.args.subcommand ?? 'show') {
         case 'init':

package/src/cmd-shot-island.ts

@@ -9,10 +9,10 @@
 
 // why: no Bun native joins or resolves a path; `--out` is resolved against the app root.
 import { join, resolve } from 'node:path';
-import type { ScrapeDriver } from '@ultimat3/scraping';
 import type { IslandStatesManifest, IslandViewport } from '@ultimat3/testing';
 import { findIslandStates } from '@ultimat3/testing';
 import { appBrowser } from './browser-launcher';
+import type { ShotDriver } from './browser-launcher-port';
 import { BadFlagError } from './errors';
 import type { IslandBrowser } from './island-shot';
 import { ISLAND_SHOT_DIR, runIslandShot, runIslandSweep } from './island-shot';
@@ -39,19 +39,18 @@ export function islandBrowser(input: {
   readonly executablePath?: string | undefined;
   readonly cdpUrl?: string | undefined;
 }): IslandBrowser {
-  const byViewport = new Map<string, Promise<ScrapeDriver>>();
-  return (viewport: IslandViewport): Promise<ScrapeDriver> => {
+  const byViewport = new Map<string, Promise<ShotDriver>>();
+  return (viewport: IslandViewport): Promise<ShotDriver> => {
     const key = `${viewport.width}x${viewport.height}`;
-    const held = byViewport.get(key);
-    if (held !== undefined) return held;
-    const started = appBrowser({
-      root: input.root,
-      ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
-      ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
-      viewport: { width: viewport.width, height: viewport.height },
-    });
-    byViewport.set(key, started);
-    return started;
+    const held =
+      byViewport.get(key) ??
+      appBrowser({
+        ...(input.executablePath === undefined ? {} : { executablePath: input.executablePath }),
+        ...(input.cdpUrl === undefined ? {} : { cdpUrl: input.cdpUrl }),
+        viewport: { width: viewport.width, height: viewport.height },
+      });
+    byViewport.set(key, held);
+    return held;
   };
 }