@ultimat3/cli 1.2.0 → 3.0.0

package/src/cmd-i18n.ts

@@ -201,6 +201,8 @@ export const i18nCommand: CliCommand = {
     usage: 'x i18n [check|add <locale>|sync <locale>] [--json]',
     requiresApp: true,
     subcommands: I18N_SUBCOMMANDS,
+    // The bare `x i18n` audits; `add` and `sync` write catalogs and must be asked for.
+    defaultSubcommand: 'check',
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('i18n', ctx.cwd).dir;

package/src/cmd-jobs.ts

@@ -1,17 +1,18 @@
-// `x jobs ls|show|retry|drain` — introspect and recover the job queue, bound to `@ultimat3/jobs`'s
+// `x jobs ls|show|retry|cancel|drain` — introspect and recover the job queue, bound to
+// `@ultimat3/jobs`'s
 // own introspection so the CLI, `/_x` and MCP report identically. This file is CLI wiring only:
 // the driver-injected logic is `jobs-report.ts`, the `--json` shapes `jobs-json.ts`, the table
-// `jobs-table.ts`.
+// `jobs-table.ts`, and getting hold of the queue at all is `jobs-driver.ts` — shared with `x db`.
 
 import type { JobDriver } from '@ultimat3/jobs';
-import { createMemoryDriver, createNatsDriver, createRedisDriver, jobDriver } from '@ultimat3/jobs';
+import { cancelJob, createMemoryDriver, createNatsDriver, createRedisDriver } from '@ultimat3/jobs';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { startQueue } from './dev-queue';
-import { resolveServices } from './dev-services';
-import { BadFlagError } from './errors';
+import { BadFlagError, JobUnknownError } from './errors';
 import { drainJobs } from './jobs-drain';
+import { withJobDriver } from './jobs-driver';
 import {
+  backfillToJson,
   deadLetterToJson,
   depthToJson,
   drainFailureToJson,
@@ -25,33 +26,10 @@ import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
 
-export const JOBS_SUBCOMMANDS = ['ls', 'show', 'retry', 'drain'] as const;
+export const JOBS_SUBCOMMANDS = ['ls', 'show', 'retry', 'cancel', 'drain'] as const;
 
 const DRAIN_TARGETS = ['memory', 'redis', 'nats'] as const;
 
-/**
- * `x jobs` needs the app's real driver. Reuse an already-running one first — inside `x dev` or
- * `x mcp serve`, `jobDriver()` is already set and booting a second queue on top of it would talk
- * to the wrong database. Otherwise boot just the db + jobs half (`startQueue`, not the full
- * `startServices`: this command touches no transport, storage or mail) and always release it, or
- * a CLI that exits holding the PGlite lock breaks the next command run against this app.
- */
-async function withDriver(
-  root: string,
-  ctx: CommandContext,
-  fn: (driver: JobDriver) => Promise<CommandResult>,
-): Promise<CommandResult> {
-  const ambient = jobDriver();
-  if (ambient !== undefined) return fn(ambient);
-  const services = resolveServices(root, ctx.env);
-  const queue = await startQueue(services);
-  try {
-    return await fn(queue.jobs);
-  } finally {
-    await queue.stop();
-  }
-}
-
 function requireIdPositional(ctx: CommandContext, sub: string): string {
   const id = ctx.args.positionals[0];
   if (id === undefined) {
@@ -114,6 +92,17 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
       );
     }
   }
+  // Same shape as the dead-letter section above, and here for the same reason: a sweep in flight
+  // is a fact the depth counts cannot show. Name, rows so far and cursor, because "how far has it
+  // got" is the whole question — the finished passes are `x db backfill --list`'s answer.
+  if (result.backfills.length > 0) {
+    lines.push(`  ${msg('cli.jobs.backfills', { count: result.backfills.length })}`);
+    for (const pass of result.backfills) {
+      const cursor = pass.cursor ?? msg('cli.jobs.backfillNoCursor');
+      const progress = msg('cli.jobs.backfillRow', { name: pass.name, rows: pass.rows, cursor });
+      lines.push(`    ${pass.runId}  ${progress}`);
+    }
+  }
   return {
     ok: true,
     command: 'jobs',
@@ -129,6 +118,7 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
       depth: depthToJson(result.depth),
       rows: result.rows.map(jobRecordToJson),
       deadLetters: result.deadLetters.map(deadLetterToJson),
+      backfills: result.backfills.map(backfillToJson),
     },
   };
 }
@@ -159,6 +149,26 @@ async function runRetry(driver: JobDriver, ctx: CommandContext): Promise<Command
   };
 }
 
+/**
+ * There is no silent-success path here, and that is the whole reason this subcommand can exist as
+ * four lines: `cancelJob` throws `X_JOB_NOT_CANCELLABLE` for a job that has already finished and
+ * for a driver with no `cancel` at all, so an exit code of 0 means the job is genuinely stopped.
+ * The trace is rendered by the same projection `show` and `retry` use — one shape for one job.
+ */
+async function runCancel(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const id = requireIdPositional(ctx, 'cancel');
+  const trace = await cancelJob(driver, id, flagString(ctx.args, 'reason'));
+  // `cancelJob` re-reads the job after cancelling, so `undefined` would mean the row vanished
+  // between the two — reported as the same refusal rather than rendered as a success with no job.
+  if (trace === undefined) throw new JobUnknownError({ id, driver: driver.name });
+  return {
+    ok: true,
+    command: 'jobs',
+    summary: msg('cli.jobs.cancelled', { id: trace.id, state: trace.state }),
+    data: jobTraceToJson(trace),
+  };
+}
+
 /**
  * A skipped candidate is not an error — a job whose `runAt` has not arrived is unclaimable by
  * design — so it carries no `X_*` finding. It still fails the command: `x jobs drain` is run to
@@ -204,17 +214,20 @@ async function runDrain(driver: JobDriver, ctx: CommandContext): Promise<Command
 export const jobsCommand: CliCommand = {
   spec: {
     name: 'jobs',
-    summary: 'list, show, retry and drain the job queue',
+    summary: 'list, show, retry, cancel and drain the job queue',
     usage:
-      'x jobs [ls|show <id>|retry <id>|drain --to <driver>] [--queue q] [--state s] [--limit n] [--from-step name] [--to driver] [--dry-run] [--json]',
+      'x jobs [ls|show <id>|retry <id>|cancel <id>|drain --to <driver>] [--queue q] [--state s] [--limit n] [--from-step name] [--reason text] [--to driver] [--dry-run] [--json]',
     requiresApp: true,
     subcommands: JOBS_SUBCOMMANDS,
+    // The bare `x jobs` lists; it never retries, cancels or drains anything.
+    defaultSubcommand: 'ls',
     flags: [
       { name: 'queue', type: 'string', summary: 'filter by queue name' },
       { name: 'state', type: 'string', summary: 'filter by job state' },
       { name: 'limit', type: 'string', summary: 'max rows to return' },
       { name: 'name', type: 'string', summary: 'filter by job name' },
       { name: 'from-step', type: 'string', summary: 'retry: drop this step so it re-executes' },
+      { name: 'reason', type: 'string', summary: 'cancel: why, recorded on the job' },
       { name: 'to', type: 'string', summary: 'drain target driver: memory, redis, nats' },
       { name: 'dry-run', type: 'boolean', summary: 'drain: report the plan, move nothing' },
     ],
@@ -222,9 +235,10 @@ export const jobsCommand: CliCommand = {
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('jobs', ctx.cwd).dir;
     const sub = ctx.args.subcommand ?? 'ls';
-    return withDriver(root, ctx, (driver) => {
+    return withJobDriver(root, ctx, (driver) => {
       if (sub === 'show') return runShow(driver, ctx);
       if (sub === 'retry') return runRetry(driver, ctx);
+      if (sub === 'cancel') return runCancel(driver, ctx);
       if (sub === 'drain') return runDrain(driver, ctx);
       return runLs(driver, ctx);
     });

package/src/cmd-mcp.ts

@@ -3,7 +3,7 @@
 // supplies only the app, the caller and the socket. A tool answered here would be a second answer
 // to a question the framework already answers.
 
-import { markListening, nanoid } from '@ultimat3/core';
+import { markListening, nanoid, timingSafeEqual } from '@ultimat3/core';
 import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -73,8 +73,14 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
   const token = nanoid(32);
   const route = mcpHttpRoute({
     server: host.server,
+    // `timingSafeEqual`, not `===`: this was the only secret comparison in the framework that
+    // short-circuited on the first differing character. Localhost and a per-process `nanoid(32)`
+    // make it hard to exploit and neither makes it correct — an exception nobody can point at is
+    // an exception the next transport copies.
     resolveToken: (candidate) =>
-      candidate === token ? { actor: host.caller.actor, scopes: DEV_TOOL_SCOPES } : null,
+      timingSafeEqual(candidate, token)
+        ? { actor: host.caller.actor, scopes: DEV_TOOL_SCOPES }
+        : null,
   });
   const handle = Bun.serve({
     port,
@@ -143,6 +149,9 @@ export const mcpCommand: CliCommand = {
     usage: 'x mcp tools | x mcp serve [--transport stdio|http] [--port 9229] [--json]',
     requiresApp: true,
     subcommands: ['serve', 'tools'],
+    // 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) },

package/src/cmd-new.ts

@@ -7,7 +7,6 @@ import { chmod } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
 import { dedupe } from './cmd-generate';
 import type { CliCommand, CommandContext } from './command';
-import { writeSchemaHash } from './drift';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
@@ -40,16 +39,23 @@ export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
 export interface WrittenApp {
   readonly dir: string;
   readonly files: readonly string[];
-  readonly schemaHash: string;
 }
 
+/**
+ * Every byte it writes is in `planNewApp`, so `--dry-run` and the disk cannot disagree.
+ *
+ * It writes NO migration and no `.hash`: `x db gen` is the one writer of `packages/db/migrations`,
+ * and it writes `.sql`, `.snapshot.json` and `.hash` together. A scaffold that wrote a `.hash` for
+ * a migration whose snapshot never existed is what made the app's first two database commands
+ * refuse each other — `x db migrate` naming `x db gen`, and `x db gen` refusing a sidecar version
+ * control never had. The consequence is deliberate: `x verify`'s `drift` step is red on a pristine
+ * scaffold until `x db gen "initial"` runs, which is what `cli.new.done` tells the author to do.
+ */
 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);
   for (const path of EXECUTABLE_FILES) await chmod(join(target, path), 0o755);
-  // Record the schema hash beside the initial migration so `x verify` sees no drift on run one.
-  const hash = await writeSchemaHash(target, '0000_initial');
-  return { dir: target, files: files.map((file) => file.path), schemaHash: hash };
+  return { dir: target, files: files.map((file) => file.path) };
 }
 
 function parentDir(cwd: string, dirFlag: string | undefined): string {
@@ -61,7 +67,7 @@ export const newCommand: CliCommand = {
   spec: {
     name: 'new',
     summary: 'scaffold a new Ultimate monorepo that already runs',
-    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--json]',
+    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--force] [--json]',
     flags: [
       { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
       {
@@ -102,7 +108,7 @@ export const newCommand: CliCommand = {
         command: 'new',
         summary: msg('cli.new.done', { name: app.kebab }),
         data: { dir: target, files: files.map((file) => file.path), dryRun: true },
-        lines: files.map((file) => `  + ${app.kebab}/${file.path}`),
+        lines: files.map((file) => msg('cli.file.added', { path: `${app.kebab}/${file.path}` })),
       };
     }
     if (existsSync(target) && !flagBool(ctx.args, 'force')) {
@@ -126,7 +132,7 @@ export const newCommand: CliCommand = {
       ok: true,
       command: 'new',
       summary: msg('cli.new.done', { name: app.kebab }),
-      data: { dir: written.dir, files: written.files, schemaHash: written.schemaHash },
+      data: { dir: written.dir, files: written.files },
       lines: [`  ${written.files.length} files in ${target}`],
     };
   },

package/src/cmd-planned.ts

@@ -34,7 +34,7 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
     name: 'branch',
     summary: 'copy-on-write branch environments with a preview URL',
     usage: 'x branch [<name>|rm <name>] [--json]',
-    fix: 'x db branch <name>   # the database half, shipped today',
+    fix: 'x db branch ls --json   # the database half: ls, create <name>, drop <name>',
   },
   {
     name: 'status',
@@ -48,13 +48,6 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
     usage: 'x upgrade [--dry-run] [--json]',
     fix: 'bun update --latest && x verify',
   },
-  {
-    name: 'env',
-    summary: 'validate the typed env; --fix writes the missing keys',
-    usage: 'x env check [--fix] [--json]',
-    subcommands: ['check'],
-    fix: 'x doctor --json   # reports the env problems it can already see',
-  },
   {
     name: 'logs',
     summary: 'structured logs and OTel spans, filterable',
@@ -76,12 +69,18 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
     subcommands: ['eval', 'cache', 'reindex'],
     fix: 'x test eval --json   # every eval, scored against its committed baseline',
   },
+  // `registerCurrency()` ships `As of 2026-08`, and this row is deliberately NOT deleted with it.
+  // What is planned is a GENERATOR — the one thing a process that exits can contribute, since a
+  // registration has to land in the app's own source to survive the run — and a generator that
+  // emits the one call is not a second path any more than `x g route` is a second way to declare a
+  // route (axiom 1). The whole table is shaped this way: `x status` beside `x doctor`, `x cache`
+  // beside the `/_x` panel. What changed is only that the `fix:` is now true.
   {
     name: 'money',
     summary: 'extend the currency table',
     usage: 'x money add-currency <ISO> --exponent <n> [--json]',
     subcommands: ['add-currency'],
-    fix: 'x manifest --json   # currencies ship in @ultimat3/money; add yours in app.config.ts',
+    fix: "x errors explain X_CURRENCY_UNKNOWN --json   # extend it in code: registerCurrency({ code: 'GHS', exponent: 2, name: 'Ghana Cedi' }) at boot",
   },
   {
     name: 'config',
@@ -92,11 +91,57 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
   },
 ];
 
+export interface PlannedSubcommand {
+  readonly command: string;
+  readonly subcommand: string;
+  /** Runnable today, and closer to the answer than nothing. Never a doc link. */
+  readonly fix: string;
+}
+
+/**
+ * A subcommand of a shipped command that this build does not implement. Same promise as the table
+ * above, one level down: `x db studio` stays in `x db`'s subcommand list, so the parser accepts it
+ * and `x help db` still lists it, and it exits X_NOT_IMPLEMENTED naming what to run instead.
+ *
+ * `studio` is here because the migration engine is `@ultimat3/db`'s and only that. It used to
+ * shell out to `bunx drizzle-kit studio` — a second schema tool, fetched unpinned at run time,
+ * declared in no `package.json` — while every other `x db` subcommand went through the framework's
+ * own ledger. One subcommand is not worth a second engine.
+ */
+export const PLANNED_SUBCOMMANDS: readonly PlannedSubcommand[] = [
+  {
+    command: 'db',
+    subcommand: 'studio',
+    fix: 'x dev   # then the db panel at /_x: schema, rows, and a guarded SQL console',
+  },
+];
+
+/**
+ * Thrown by the owning command, so the subcommand fails exactly where it would have run. Returns
+ * the error rather than throwing it, because a `run` that throws synchronously escapes the
+ * promise its signature promises — the caller does `throw plannedSubcommand(...)`.
+ */
+export function plannedSubcommand(command: string, subcommand: string): CliNotImplementedError {
+  const planned = PLANNED_SUBCOMMANDS.find(
+    (entry) => entry.command === command && entry.subcommand === subcommand,
+  );
+  return new CliNotImplementedError({
+    feature: `x ${command} ${subcommand}`,
+    // `x help <command>`, not `x <command> --help`: for a command that declares subcommands and no
+    // default, the latter is refused by the parser before help is ever rendered.
+    fix: planned?.fix ?? `x help ${command}`,
+  });
+}
+
 const specFor = (planned: PlannedCommand): CommandSpec => ({
   name: planned.name,
   summary: `${planned.summary} (planned)`,
   usage: planned.usage,
-  ...(planned.subcommands === undefined ? {} : { subcommands: planned.subcommands }),
+  // A planned command answers X_NOT_IMPLEMENTED however it is invoked, so the bare form must
+  // reach its `run` rather than being refused for a subcommand that does not exist yet.
+  ...(planned.subcommands === undefined
+    ? {}
+    : { subcommands: planned.subcommands, defaultSubcommand: planned.subcommands[0] }),
 });
 
 /**

package/src/cmd-policy.ts

@@ -126,6 +126,7 @@ export const policyCommand: CliCommand = {
     usage: 'x policy [list|explain <subject>] [--json]',
     requiresApp: true,
     subcommands: ['list', 'explain'],
+    defaultSubcommand: 'list',
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('policy', ctx.cwd).dir;

package/src/cmd-registries.ts

@@ -57,6 +57,7 @@ const ACTIONS: RegistryKind<ActionDescriptor, AnyAction> = {
     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,
   },
   header: ['name', 'verb', 'resource', 'path', 'capability', 'mcp'],
@@ -74,6 +75,7 @@ const QUERIES: RegistryKind<QueryDescriptor, AnyQuery> = {
     summary: 'the query registry: schema, policy, live, cache tags',
     usage: 'x queries [list|describe <name>] [--json]',
     subcommands: ['list', 'describe'],
+    defaultSubcommand: 'list',
     requiresApp: true,
   },
   header: ['name', 'live', 'capability', 'tags', 'ttlMs'],
@@ -99,6 +101,7 @@ const ENTITIES: RegistryKind<EntityDescription, RegistryEntry> = {
     summary: 'the entity registry: columns, invariants, indexes, tenancy',
     usage: 'x entities [list|describe <name>] [--json]',
     subcommands: ['list', 'describe'],
+    defaultSubcommand: 'list',
     requiresApp: true,
   },
   header: ['name', 'table', 'columns', 'invariants', 'indexes', 'orgScoped'],