@ultimat3/cli 29.4.0 → 30.0.0

package/src/cmd-jobs-spec.ts

@@ -14,6 +14,7 @@ export const JOBS_SUBCOMMANDS = [
   'cancel',
   'delete',
   'promote',
+  'resolve-step',
   'pause',
   'resume',
   'drain',
@@ -24,9 +25,9 @@ export const jobsSpec: CommandSpec = {
   // Never ENDING in "(planned)": that suffix is how `x help` and the planned-table tests tell a
   // planned COMMAND from a shipped one, and `x jobs` ships — only its `drain` does not.
   summary:
-    'list, show, retry, cancel, delete and promote jobs; pause and resume a queue (drain is planned)',
+    'list, show, retry, cancel, delete and promote jobs; resolve a step; pause and resume a queue (drain is planned)',
   usage:
-    'x jobs [list|show <id>|retry <id>|cancel <id>|delete <id>|promote <id>|pause <queue>|resume <queue>|drain] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--json]',
+    'x jobs [list|show <id>|retry <id>|cancel <id>|delete <id>|promote <id>|resolve-step <id> <step>|pause <queue>|resume <queue>|drain] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--ran|--not-ran] [--output json] [--json]',
   requiresApp: true,
   subcommands: JOBS_SUBCOMMANDS,
   // The bare `x jobs` lists; it never retries, cancels or drains anything.
@@ -57,5 +58,23 @@ export const jobsSpec: CommandSpec = {
       summary: 'cancel: why, recorded on the job',
       subcommands: ['cancel'],
     },
+    {
+      name: 'ran',
+      type: 'boolean',
+      summary: 'resolve-step: the step happened — record --output as its answer',
+      subcommands: ['resolve-step'],
+    },
+    {
+      name: 'not-ran',
+      type: 'boolean',
+      summary: 'resolve-step: the step did not happen — the next run calls it again',
+      subcommands: ['resolve-step'],
+    },
+    {
+      name: 'output',
+      type: 'string',
+      summary: 'resolve-step: with --ran, the JSON a replay of the step returns (default null)',
+      subcommands: ['resolve-step'],
+    },
   ],
 };

package/src/cmd-jobs.ts

@@ -1,8 +1,8 @@
-// `x jobs list|show|retry|cancel|delete|promote|pause|resume` — introspect and recover the job queue,
-// bound to `@ultimat3/jobs`'s own introspection so the CLI, `/_x` and MCP report identically;
-// `drain` is planned (`cmd-planned.ts`): Postgres is the one durable driver. CLI wiring only:
-// the driver-injected logic is `jobs-report.ts`, the `--json` shapes `jobs-json.ts`, the table
-// `jobs-table.ts`, and getting hold of the queue at all is `jobs-driver.ts` — shared with `x db`.
+// `x jobs list|show|retry|cancel|delete|promote|resolve-step|pause|resume` — introspect and
+// recover the job queue, bound to `@ultimat3/jobs`'s own introspection so the CLI, `/_x` and MCP
+// report identically; `drain` is planned (`cmd-planned.ts`): Postgres is the one durable driver.
+// CLI wiring only: the driver-injected logic is `jobs-report.ts`, the `--json` shapes
+// `jobs-json.ts`, the table `jobs-table.ts`, the queue `jobs-driver.ts` — shared with `x db`.
 
 import { renderFixShellArg } from '@ultimat3/core';
 import type { JobDriver } from '@ultimat3/jobs';
@@ -16,6 +16,7 @@ import {
 } from '@ultimat3/jobs';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { runResolveStep } from './cmd-jobs-resolve';
 import { jobsSpec } from './cmd-jobs-spec';
 import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
@@ -250,7 +251,7 @@ async function runPause(
 }
 
 /** The subcommands that answer a `JobTrace`. `list`, `delete`, `promote` and the rest read rows only. */
-const TRACE_SUBCOMMANDS: ReadonlySet<string> = new Set(['show', 'retry', 'cancel']);
+const TRACE_SUBCOMMANDS: ReadonlySet<string> = new Set(['show', 'retry', 'cancel', 'resolve-step']);
 
 export const jobsCommand: CliCommand = {
   spec: jobsSpec,
@@ -274,6 +275,9 @@ export const jobsCommand: CliCommand = {
       if (sub === 'cancel') return runCancel(driver, ctx);
       if (sub === 'delete') return runDelete(driver, ctx);
       if (sub === 'promote') return runPromote(driver, ctx);
+      if (sub === 'resolve-step') {
+        return runResolveStep(driver, ctx, requireIdPositional(ctx, sub, driver));
+      }
       if (sub === 'pause' || sub === 'resume') return runPause(driver, ctx, sub);
       return runList(driver, ctx);
     });

package/src/cmd-mail-spec.ts

@@ -0,0 +1,28 @@
+// `x mail`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-mail.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const MAIL_SUBCOMMANDS = ['preview'] as const;
+
+export const mailSpec: CommandSpec = {
+  name: 'mail',
+  summary: "render a mail's declared preview in every locale, nothing sent",
+  usage: 'x mail preview <id> [--locale <tag>] [--tz <zone>] [--out <dir>] [--json]',
+  requiresApp: true,
+  subcommands: MAIL_SUBCOMMANDS,
+  defaultSubcommand: 'preview',
+  flags: [
+    { name: 'locale', type: 'string', summary: 'one locale; default every locale the app routes' },
+    {
+      name: 'tz',
+      type: 'string',
+      summary: 'IANA zone every date in the body renders in; default UTC, as the /_x panel',
+    },
+    {
+      name: 'out',
+      type: 'string',
+      summary: 'write <id>.<locale>.html and .txt into this directory',
+    },
+  ],
+};

package/src/cmd-mail.ts

@@ -0,0 +1,70 @@
+// `x mail preview <id>` — a template checked in every locale without triggering the flow that
+// sends it: `@ultimat3/mail`'s `previewMail` over the mail's declared `preview` data. A key a
+// locale cannot resolve is named in `--json` and fails the command, as `send` would refuse it.
+
+// why: Bun exposes no path-join primitive; `--out` is a directory the files are joined under.
+import { join, resolve } from 'node:path';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
+import { previewMail } from '@ultimat3/mail';
+import { assertTimeZone } from '@ultimat3/time';
+import { loadApp } from './app-load';
+import { requireAppRoot } from './app-root';
+import { mailSpec } from './cmd-mail-spec';
+import type { CliCommand, CommandContext } from './command';
+import { MissingPositionalError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { flagString } from './parse';
+
+/** A sample has no reader, so no reader's zone: UTC unless `--tz` names one — never the ambient. */
+const PREVIEW_ZONE = 'UTC';
+
+export const mailCommand: CliCommand = {
+  spec: mailSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('mail', ctx.cwd).dir;
+    const id = ctx.args.positionals[0];
+    if (id === undefined) {
+      throw new MissingPositionalError({
+        command: 'mail preview',
+        positional: 'id',
+        example: 'x mail preview welcome --locale es',
+      });
+    }
+    await loadApp(root);
+    const asked = flagString(ctx.args, 'locale');
+    const locales = asked === undefined ? (await appLocaleSet(root)).locales : [asked];
+    const tz = assertTimeZone(flagString(ctx.args, 'tz') ?? PREVIEW_ZONE);
+    const out = flagString(ctx.args, 'out');
+    const previews: Record<string, JsonValue>[] = [];
+    for (const locale of locales) {
+      const preview = previewMail(id, { locale, tz });
+      const files: string[] = [];
+      if (out !== undefined) {
+        const base = join(resolve(ctx.cwd, out), `${id}.${preview.locale}`);
+        await Bun.write(`${base}.html`, preview.html);
+        await Bun.write(`${base}.txt`, preview.text);
+        files.push(`${base}.html`, `${base}.txt`);
+      }
+      previews.push({
+        locale: preview.locale,
+        subject: preview.subject,
+        missing: preview.misses.map((miss) => miss.key),
+        files,
+      });
+    }
+    const missing = previews.filter(
+      (each) => Array.isArray(each['missing']) && each['missing'].length > 0,
+    );
+    return {
+      ok: missing.length === 0,
+      command: 'mail',
+      summary: msg(missing.length === 0 ? 'cli.mail.preview.ok' : 'cli.mail.preview.missing', {
+        id,
+        missing: missing.length,
+        locales: previews.length,
+      }),
+      data: { id, previews, tz },
+    };
+  },
+};

package/src/cmd-mcp-lock.ts

@@ -0,0 +1,69 @@
+// `x mcp lock <name>` — fetch a remote MCP server's tools named by the app's `mcpTools({ name,
+// allow })` and write what a reviewer accepts into `tools.lock.json`. `--check` writes nothing and
+// fails on a drift (`X_MCP_REMOTE_TOOL_CHANGED`): the convention's build error, for `verify`.
+
+// why: Bun exposes no path-join primitive; the lock sits at the app root.
+import { join } from 'node:path';
+import { renderFixShellArg } from '@ultimat3/core';
+import {
+  assertLocked,
+  declaredMcpServers,
+  McpRemoteToolChangedError,
+  readToolsLock,
+  TOOLS_LOCK_FILE,
+  writeToolsLock,
+} from '@ultimat3/mcp';
+import { loadApp } from './app-load';
+import type { CommandContext } from './command';
+import { MissingPositionalError } from './errors';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagBool } from './parse';
+
+export async function mcpLock(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const name = ctx.args.positionals[0];
+  if (name === undefined) {
+    throw new MissingPositionalError({
+      command: 'mcp lock',
+      positional: 'name',
+      example: 'x mcp lock <name> --json   # the name given to mcpTools({ name })',
+    });
+  }
+  // The app's own modules evaluate every `mcpTools()`; a missing lock is a load finding, not a stop.
+  await loadApp(root);
+  const server = declaredMcpServers().get(name);
+  if (server === undefined) {
+    throw new McpRemoteToolChangedError({
+      server: name,
+      changes: [
+        `no mcpTools({ name: ${renderFixShellArg(name, '<name>')} }) is declared (declared: ${[...declaredMcpServers().keys()].join(', ') || 'none'})`,
+      ],
+    });
+  }
+  const file = join(root, TOOLS_LOCK_FILE);
+  const handle = Bun.file(file);
+  const previous: unknown = (await handle.exists())
+    ? ((await handle.json()) as unknown)
+    : undefined;
+  const live = await server.client.listTools();
+  if (flagBool(ctx.args, 'check')) {
+    assertLocked(name, readToolsLock(previous).get(name), server.url, server.allow, live);
+    return {
+      ok: true,
+      command: 'mcp',
+      summary: msg('cli.mcp.lock_current', { server: name, file: TOOLS_LOCK_FILE }),
+      data: { server: name, file: TOOLS_LOCK_FILE, changed: false },
+    };
+  }
+  await Bun.write(file, writeToolsLock(previous, name, server.url, server.allow, live));
+  return {
+    ok: true,
+    command: 'mcp',
+    summary: msg('cli.mcp.locked', {
+      server: name,
+      tools: server.allow.length,
+      file: TOOLS_LOCK_FILE,
+    }),
+    data: { server: name, file: TOOLS_LOCK_FILE, tools: [...server.allow] },
+  };
+}

package/src/cmd-mcp-spec.ts

@@ -8,14 +8,33 @@ export const DEFAULT_PORT = 9229;
 export const mcpSpec: CommandSpec = {
   name: 'mcp',
   summary: 'serve the dev tools: routes, schema, policies, db, queues, logs, tests, verify',
-  usage: 'x mcp tools | x mcp serve [--transport stdio|http] [--port 9229] [--json]',
+  usage:
+    'x mcp tools | x mcp serve [--transport stdio|http] [--port 9229] | x mcp lock <name> [--check] [--json]',
   requiresApp: true,
-  subcommands: ['serve', 'tools'],
+  subcommands: ['serve', 'tools', 'lock'],
   // No default, deliberately: `wiki/CLI-Reference.md` already says to write `x mcp serve` rather
   // than a bare `x mcp`, and the parser's old first-element guess made the bare form START A
   // SERVER — the one thing a word typed by mistake must not do. Refusing enforces the guidance.
   flags: [
-    { name: 'transport', type: 'string', summary: 'stdio | http', default: 'stdio' },
-    { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
+    {
+      name: 'transport',
+      type: 'string',
+      summary: 'stdio | http',
+      default: 'stdio',
+      subcommands: ['serve', 'tools'],
+    },
+    {
+      name: 'port',
+      type: 'string',
+      summary: 'HTTP port',
+      default: String(DEFAULT_PORT),
+      subcommands: ['serve', 'tools'],
+    },
+    {
+      name: 'check',
+      type: 'boolean',
+      summary: 'compare the remote server to tools.lock.json, write nothing',
+      subcommands: ['lock'],
+    },
   ],
 };

package/src/cmd-mcp.ts

@@ -10,13 +10,16 @@ import {
   timingSafeEqual,
   UltimateError,
 } from '@ultimat3/core';
-import { mcpHttpRoute, type StdioTransportInput, serveStdio } from '@ultimat3/mcp';
+import { jsonResponse, methodNotAllowed, toProblem } from '@ultimat3/http';
+import { mcpHostRefused, mcpHttpRoute, type StdioTransportInput, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
+import { mcpLock } from './cmd-mcp-lock';
 import { DEFAULT_PORT, mcpSpec } from './cmd-mcp-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
 import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
+import { isLoopbackHostname } from './loopback-host';
 import type { CliMcpServer } from './mcp-host';
 import { createDevMcpServer, DEV_TOOL_SCOPES } from './mcp-host';
 import { msg } from './messages';
@@ -119,8 +122,18 @@ export async function startMcpHttp(host: CliMcpServer, port: number): Promise<Mc
       idleTimeout: 0,
       fetch: (request: Request, server): Response | Promise<Response> => {
         const url = new URL(request.url);
-        if (request.method !== route.method || url.pathname !== route.path) {
-          return notFound(route.path);
+        // Where this server IS reached — every refusal's fix names it, never the Host a request sent.
+        const endpoint = `${server.url.origin}${route.path}`;
+        // Before anything else, as `/_x` does: this server serves this machine, and a rebound name
+        // reaches it with a Host and an Origin that agree, which no Origin rule can tell apart.
+        if (!isLoopbackHostname(url.hostname)) return mcpHostRefused(endpoint);
+        if (url.pathname !== route.path) return notFound(route.path);
+        // `@ultimat3/http`'s own 405, the one the pipeline answers on an app's mounted `/mcp`.
+        if (request.method !== route.method) {
+          return jsonResponse(toProblem(methodNotAllowed(request.method, route.path, ['POST'])), {
+            status: 405,
+            headers: { allow: 'POST' },
+          });
         }
         // The socket's peer: failed tokens are metered per address, and only the server knows it.
         return route.handle(request, { address: server.requestIP(request)?.address });
@@ -211,6 +224,7 @@ export const mcpCommand: CliCommand = {
   spec: mcpSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('mcp', ctx.cwd).dir;
+    if (ctx.args.subcommand === 'lock') return mcpLock(ctx, root);
     const transport = flagString(ctx.args, 'transport') ?? 'stdio';
     // Validated before the app is loaded: a typo must not cost a boot to report.
     if (!isTransport(transport)) {

package/src/cmd-new-spec.ts

@@ -1,6 +1,7 @@
 // `x new`'s declaration, apart from its body: the parser, `x help` and the `errors` step
 // read it without loading `cmd-new.ts`, which `registry.ts` imports only when the command runs.
 
+import { NEW_SHAPES } from './new-shapes';
 import type { CommandSpec } from './parse';
 
 export const newSpec: CommandSpec = {
@@ -9,7 +10,7 @@ export const newSpec: CommandSpec = {
   // 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]',
+  usage: `x new <name> [--dir path] [--shape ${NEW_SHAPES.join('|')}] [--no-example] [--no-git] [--dry-run] [--force] [--json]`,
   flags: [
     { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
     {
@@ -21,6 +22,12 @@ export const newSpec: CommandSpec = {
       summary: 'include the example feature slice (default: on; --no-example for an empty app/)',
       default: true,
     },
+    {
+      // The list is `NEW_SHAPES`, so `x help new` cannot name a shape `x new` refuses.
+      name: 'shape',
+      type: 'string',
+      summary: `start from an app shape: ${NEW_SHAPES.join(', ')} (default: none — the dashboard and example slice; never with --no-example)`,
+    },
     {
       name: 'git',
       type: 'boolean',

package/src/cmd-new.ts

@@ -14,17 +14,23 @@ import { AppNameEmptyError, AppNameIsPathError, MissingPositionalError } from '.
 import type { Runner } from './exec';
 import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
+import { type NewShape, readShape } from './new-shapes';
+import { runShapeGenerators } from './new-shapes-generate';
 import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
 import { quoteArg } from './shell-quote';
 import type { GeneratedFile } from './templates';
 import { appFiles, names, repoFiles, resourceFiles } from './templates';
+import { applyOverlay, SHAPE_OVERLAYS } from './templates/shapes';
 import { loadVersion } from './version-loader';
+import { writeGenerated } from './write-generated';
 
 export interface NewAppOptions {
   readonly name: string;
   /** The example feature slice. `--no-example` gives the same shape with an empty app/. */
   readonly example: boolean;
+  /** `--shape`: an overlay over the scaffold below (`templates/shapes/`); absent is the default. */
+  readonly shape?: NewShape | undefined;
 }
 
 /** `--no-git`'s `problem`, matched rather than re-spelled where the report decides on a line. */
@@ -102,6 +108,21 @@ export async function initRepository(runner: Runner, dir: string): Promise<Repos
   return { initialized: true, committed: true, problem: null };
 }
 
+/** git's refusal of a commit on a box with no `user.name` / `user.email` configured. */
+const NO_IDENTITY = /Author identity unknown|Please tell me who you are|empty ident/i;
+
+/**
+ * The commands that finish what `initRepository` could not: no `git init` once `.git` exists, and
+ * the identity first when that is what refused, or the pasted commit fails the same way.
+ */
+export function repositoryFix(git: RepositoryInit): string {
+  const commit = "git add -A && git commit -m 'x new'";
+  if (!git.initialized) return `git init && ${commit}`;
+  return NO_IDENTITY.test(git.problem ?? '')
+    ? `git config user.name '<your name>' && git config user.email '<you@example.com>' && ${commit}`
+    : commit;
+}
+
 /** `path` relative to `cwd` when it lies under it, else absolute — never a `../../` walk. */
 const displayPath = (cwd: string, path: string): string => {
   const rel = relative(cwd, path);
@@ -111,8 +132,18 @@ const displayPath = (cwd: string, path: string): string => {
 /** The `cd` operand of the next-steps line: the target as typed from `cwd`, pasteable verbatim. */
 const cdTarget = (cwd: string, target: string): string => quoteArg(displayPath(cwd, target));
 
+/** The `x g` lines a shape runs once its files are written, as a reader would type them. */
+const shapeGenerateLines = (shape: NewShape): readonly string[] =>
+  (SHAPE_OVERLAYS[shape].generate ?? []).map((argv) => ['x', 'g', ...argv].join(' '));
+
 /** Pure: the complete file list for a new app, so `--dry-run` and the test see the same thing. */
 export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
+  if (options.shape !== undefined) {
+    const overlay = SHAPE_OVERLAYS[options.shape];
+    const base = planNewApp({ name: options.name, example: overlay.example });
+    // Merge-aware, as below: a shape's catalog keys land in the one catalog the base wrote.
+    return dedupe(applyOverlay(base, overlay, names(options.name)));
+  }
   const app = names(options.name);
   const files: GeneratedFile[] = [
     ...repoFiles(app, loadVersion(), options.example),
@@ -159,7 +190,8 @@ export interface WrittenApp {
  */
 export async function writeNewApp(target: string, options: NewAppOptions): Promise<WrittenApp> {
   const files = planNewApp(options);
-  for (const file of files) await Bun.write(join(target, file.path), file.contents);
+  // In order, so a link's target (`CLAUDE.md` before `AGENTS.md`) is on disk when it lands.
+  for (const file of files) await writeGenerated(target, file);
   return { dir: target, files: files.map((file) => file.path) };
 }
 
@@ -231,7 +263,13 @@ export const newCommand: CliCommand = {
       });
     }
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);
-    const options: NewAppOptions = { name: raw, example: ctx.args.flags.get('example') !== false };
+    // Before the target is touched: a refused shape writes nothing, `--dry-run` included.
+    const shape = readShape(ctx.args, invocationOf(ctx, 'new'), app.kebab);
+    const options: NewAppOptions = {
+      name: raw,
+      example: ctx.args.flags.get('example') !== false,
+      shape,
+    };
 
     if (flagBool(ctx.args, 'dry-run')) {
       const files = planNewApp(options);
@@ -243,7 +281,13 @@ export const newCommand: CliCommand = {
           dir: target,
           cd: cdTarget(ctx.cwd, target),
         }),
-        data: { dir: target, files: files.map((file) => file.path), dryRun: true },
+        data: {
+          dir: target,
+          files: files.map((file) => file.path),
+          // What a real run then runs in the app, so a dry run names the files it cannot plan.
+          ...(shape === undefined ? {} : { generate: shapeGenerateLines(shape) }),
+          dryRun: true,
+        },
         // Where each file WOULD land, as the caller would reach it: relative to the cwd, `--dir`
         // included — `${app.kebab}/…` named the wrong place whenever `--dir` was set.
         lines: files.map((file) =>
@@ -273,26 +317,34 @@ export const newCommand: CliCommand = {
     // `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);
+    // Before the first commit, so the repository starts with what the shape's generators wrote.
+    const generated =
+      shape === undefined
+        ? []
+        : await runShapeGenerators(ctx, shape, target, SHAPE_OVERLAYS[shape].generate ?? []);
     const git =
       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 })];
+    const files = [...new Set([...written.files, ...generated])];
+    const lines = [msg('cli.new.wrote', { count: files.length, dir: target })];
     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 ${quoteArg(target)} && git init && git add -A && git commit -m 'x new'`,
+        msg(git.initialized ? 'cli.new.uncommitted' : '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 ${quoteArg(target)} && ${repositoryFix(git)}`);
     }
     return {
       ok: true,
       command: 'new',
       summary: msg('cli.new.done', { name: app.kebab, cd: cdTarget(ctx.cwd, target) }),
-      data: { dir: written.dir, files: written.files, git },
+      data: { dir: written.dir, files, git },
       lines,
     };
   },

package/src/cmd-planned.ts

@@ -42,12 +42,6 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
     usage: 'x status [--json]',
     fix: 'x doctor --json',
   },
-  {
-    name: 'upgrade',
-    summary: 'move every @ultimat3/* in lockstep, with codemods',
-    usage: 'x upgrade [--dry-run] [--json]',
-    fix: 'bun update --latest && x verify',
-  },
   {
     name: 'logs',
     summary: 'structured logs and OTel spans, filterable',

package/src/cmd-repro-spec.ts

@@ -0,0 +1,31 @@
+// `x repro`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-repro.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const reproSpec: CommandSpec = {
+  name: 'repro',
+  summary: 'a dead job or a captured 5xx, as a failing test: x repro <id> --write --verify',
+  usage:
+    'x repro <jobId|requestId|traceId|fingerprint> [--write] [--verify] | x repro --list [--code X_…] | x repro --from <file> [--write] [--verify] [--json]',
+  requiresApp: true,
+  flags: [
+    {
+      name: 'write',
+      type: 'boolean',
+      summary: 'write the test to repro/repro-<id>.<kind>.test.ts',
+    },
+    {
+      name: 'verify',
+      type: 'boolean',
+      summary: 'run the written test and answer { reproduced, code, fingerprint }',
+    },
+    { name: 'list', type: 'boolean', summary: 'the captured bundles, newest first' },
+    { name: 'code', type: 'string', summary: 'list: only bundles of this X_* code' },
+    {
+      name: 'from',
+      type: 'string',
+      summary: 'a bundle file (x repro <id> --json) instead of the database',
+    },
+  ],
+};