@ultimat3/cli 22.15.0 → 24.0.0

package/src/cmd-jobs.ts

@@ -1,11 +1,24 @@
-// `x jobs ls|show|retry|cancel|drain` — introspect and recover the job queue, bound to
+// `x jobs ls|show|retry|cancel|rm|promote|pause|resume|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`, and getting hold of the queue at all is `jobs-driver.ts` — shared with `x db`.
 
+import { renderFixShellArg } from '@ultimat3/core';
 import type { JobDriver } from '@ultimat3/jobs';
-import { cancelJob, createNatsDriver, createRedisDriver } from '@ultimat3/jobs';
+import {
+  cancelJob,
+  createNatsDriver,
+  createRedisDriver,
+  DEFAULT_JOB_PAGE,
+  jobCursor,
+  MAX_JOB_PAGE,
+  pauseQueue,
+  promoteJob,
+  removeJob,
+  resumeQueue,
+} from '@ultimat3/jobs';
+import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { DRAIN_TARGETS, jobsSpec } from './cmd-jobs-spec';
 import type { CliCommand, CommandContext } from './command';
@@ -21,6 +34,8 @@ import {
   drainSkipToJson,
   jobRecordToJson,
   jobTraceToJson,
+  pausedToJson,
+  workerToJson,
 } from './jobs-json';
 import { listJobs, retryJob, showJob } from './jobs-report';
 import { renderJobTable } from './jobs-table';
@@ -51,7 +66,18 @@ function refuseMemoryTarget(): never {
   });
 }
 
-function requireIdPositional(ctx: CommandContext, sub: string): string {
+/**
+ * A uuid in any spelling Postgres' `uuid` input accepts: canonical, upper-case, unhyphenated,
+ * braced. Every driver mints its ids with core's `uuid()`, and `x_jobs.id` is a `uuid` column.
+ */
+const JOB_ID = /^\{?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\}?$/i;
+
+/**
+ * The id, parsed at the door — admin's `readableId` rule: an id no driver could hold is a job that
+ * does not exist, answered before a statement is sent. `x jobs show nosuch` reached Postgres and
+ * came back a raw `X_DB_STATEMENT_FAILED [22P02]` whose fix was a psql session.
+ */
+function requireIdPositional(ctx: CommandContext, sub: string, driver: JobDriver): string {
   const id = ctx.args.positionals[0];
   if (id === undefined) {
     // `--id on "x jobs"` is a flag `x jobs` does not declare; the id is a positional and says so.
@@ -61,9 +87,37 @@ function requireIdPositional(ctx: CommandContext, sub: string): string {
       example: 'x jobs ls --json',
     });
   }
+  if (!JOB_ID.test(id)) throw new JobUnknownError({ id, driver: driver.name });
   return id;
 }
 
+function requireQueuePositional(ctx: CommandContext, sub: string): string {
+  const queue = ctx.args.positionals[0];
+  if (queue === undefined) {
+    throw new MissingPositionalError({
+      command: `jobs ${sub}`,
+      positional: 'queue',
+      example: `x jobs ${sub} default --json`,
+    });
+  }
+  return queue;
+}
+
+/**
+ * A page past the queue's own bound is refused HERE, as a flag error with the command that walks
+ * instead — `list()` would refuse it too, in the vocabulary of a caller holding a driver.
+ */
+function refuseOversizedPage(limit: string | undefined): void {
+  if (limit === undefined || !/^\d+$/.test(limit) || Number(limit) <= MAX_JOB_PAGE) return;
+  throw new BadFlagError({
+    flag: 'limit',
+    command: 'jobs',
+    reason: `one page holds at most ${MAX_JOB_PAGE} jobs`,
+    // The bound is the queue's own constant, screened like any value spliced into a command.
+    fix: `x jobs ls --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.next as --after for the page that follows`,
+  });
+}
+
 function requireEnvUrl(env: CommandContext['env'], name: string, target: string): string {
   const value = env[name];
   if (value === undefined || value.trim().length === 0) {
@@ -97,16 +151,34 @@ export function buildDrainTarget(to: string | undefined, env: CommandContext['en
 }
 
 async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const limit = flagString(ctx.args, 'limit');
+  refuseOversizedPage(limit);
   const result = await listJobs(driver, {
     queue: flagString(ctx.args, 'queue'),
     state: flagString(ctx.args, 'state'),
     name: flagString(ctx.args, 'name'),
-    limit: flagString(ctx.args, 'limit'),
+    limit,
+    after: flagString(ctx.args, 'after'),
   });
+  // A FULL page may have another behind it: `next` is the cursor that asks for it, and `null`
+  // says this was the last one — so a walk never has to guess from a row count.
+  const size = limit === undefined ? DEFAULT_JOB_PAGE : Number(limit);
+  const last = result.rows[result.rows.length - 1];
+  const next = last === undefined || result.rows.length < size ? null : jobCursor(last);
+  const [paused, workers] = await Promise.all([
+    driver.introspect?.pausedQueues() ?? [],
+    driver.introspect?.workers() ?? [],
+  ]);
   const lines = [`  ${msg('cli.jobs.listed', { count: result.rows.length })}`];
   if (result.rows.length > 0) {
     lines.push(...renderJobTable(result.rows).map((line) => `  ${line}`));
   }
+  if (next !== null) lines.push(`  ${msg('cli.jobs.nextPage', { cursor: next })}`);
+  if (paused.length > 0) {
+    lines.push(
+      `  ${msg('cli.jobs.pausedQueues', { queues: paused.map((q) => q.name).join(', ') })}`,
+    );
+  }
   if (result.deadLetters.length > 0) {
     lines.push(`  ${msg('cli.jobs.deadLetters', { count: result.deadLetters.length })}`);
     for (const entry of result.deadLetters) {
@@ -143,12 +215,15 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
       rows: result.rows.map(jobRecordToJson),
       deadLetters: result.deadLetters.map(deadLetterToJson),
       backfills: result.backfills.map(backfillToJson),
+      next,
+      pausedQueues: paused.map(pausedToJson),
+      workers: workers.map(workerToJson),
     },
   };
 }
 
 async function runShow(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const trace = await showJob(driver, requireIdPositional(ctx, 'show'));
+  const trace = await showJob(driver, requireIdPositional(ctx, 'show', driver));
   return {
     ok: true,
     command: 'jobs',
@@ -163,7 +238,7 @@ async function runShow(driver: JobDriver, ctx: CommandContext): Promise<CommandR
 }
 
 async function runRetry(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const id = requireIdPositional(ctx, 'retry');
+  const id = requireIdPositional(ctx, 'retry', driver);
   const trace = await retryJob(driver, id, flagString(ctx.args, 'from-step'));
   return {
     ok: true,
@@ -180,7 +255,7 @@ async function runRetry(driver: JobDriver, ctx: CommandContext): Promise<Command
  * 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 id = requireIdPositional(ctx, 'cancel', driver);
   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.
@@ -193,6 +268,48 @@ async function runCancel(driver: JobDriver, ctx: CommandContext): Promise<Comman
   };
 }
 
+/** Exit 0 means the row is gone. An id nobody queued is `X_JOB_UNKNOWN`; a running one refuses. */
+async function runRm(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const id = requireIdPositional(ctx, 'rm', driver);
+  const removed = await removeJob(driver, id);
+  if (removed === undefined) throw new JobUnknownError({ id, driver: driver.name });
+  return {
+    ok: true,
+    command: 'jobs',
+    summary: msg('cli.jobs.removed', { id: removed.id, state: removed.state }),
+    data: jobRecordToJson(removed),
+  };
+}
+
+async function runPromote(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
+  const promoted = await promoteJob(driver, requireIdPositional(ctx, 'promote', driver));
+  return {
+    ok: true,
+    command: 'jobs',
+    summary: msg('cli.jobs.promoted', { id: promoted.id }),
+    data: jobRecordToJson(promoted),
+  };
+}
+
+/**
+ * Both verbs answer the list as the queue NOW holds it, read back after the write: the pause is a
+ * row every worker's next claim reads, so "paused" here is paused fleet-wide within one poll.
+ */
+async function runPause(
+  driver: JobDriver,
+  ctx: CommandContext,
+  sub: 'pause' | 'resume',
+): Promise<CommandResult> {
+  const queue = requireQueuePositional(ctx, sub);
+  const paused = await (sub === 'pause' ? pauseQueue(driver, queue) : resumeQueue(driver, queue));
+  return {
+    ok: true,
+    command: 'jobs',
+    summary: msg(sub === 'pause' ? 'cli.jobs.paused' : 'cli.jobs.resumed', { queue }),
+    data: { queue, paused: sub === 'pause', pausedQueues: paused.map(pausedToJson) },
+  };
+}
+
 /**
  * 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
@@ -246,6 +363,9 @@ async function runDrain(
   return drainResult(await drainJobs(driver, target, flagBool(ctx.args, 'dry-run')));
 }
 
+/** The subcommands that answer a `JobTrace`. `ls`, `rm`, `promote` and the rest read rows only. */
+const TRACE_SUBCOMMANDS: ReadonlySet<string> = new Set(['show', 'retry', 'cancel']);
+
 export const jobsCommand: CliCommand = {
   spec: jobsSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -258,10 +378,19 @@ export const jobsCommand: CliCommand = {
     // word they typed was refused by name. It also opens a connection to a target the command
     // then refuses, which is a socket nothing closes.
     const target = sub === 'drain' ? buildDrainTarget(flagString(ctx.args, 'to'), ctx.env) : null;
+    // A TRACE is the queue row projected through the job's own declaration — its concurrency key,
+    // its retry schedule — and a declaration exists in this process only once the app is loaded.
+    // Unloaded, `show` answered `concurrencyKey: null` and `retryDelaysMs: []` for every job of
+    // every app. The findings are deliberately dropped: a trace is read to debug a stuck queue,
+    // so an app that half-loads degrades those two fields and still answers.
+    if (TRACE_SUBCOMMANDS.has(sub)) await loadApp(root);
     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 === 'rm') return runRm(driver, ctx);
+      if (sub === 'promote') return runPromote(driver, ctx);
+      if (sub === 'pause' || sub === 'resume') return runPause(driver, ctx, sub);
       if (target !== null) return runDrain(driver, target, ctx);
       return runLs(driver, ctx);
     });

package/src/cmd-manifest-spec.ts

@@ -6,7 +6,7 @@ import type { CommandSpec } from './parse';
 export const manifestSpec: CommandSpec = {
   name: 'manifest',
   summary: 'regenerate x.manifest.json and openapi.json from the code',
-  usage: 'x manifest [--check] [--json]',
+  usage: 'x manifest [--check] [--no-openapi] [--json]',
   requiresApp: true,
   flags: [
     { name: 'check', type: 'boolean', summary: 'fail if the committed files are stale' },

package/src/cmd-manifest.ts

@@ -4,16 +4,15 @@
 
 import { join } from 'node:path';
 import type { Manifest } from '@ultimat3/manifest';
-import { assertNoDrift, MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { writeAppArtifacts } from './app-artifacts';
 import { appManifest } from './app-manifest';
-import { openApiStaleness } from './app-openapi';
 import { requireAppRoot } from './app-root';
 import { manifestSpec } from './cmd-manifest-spec';
 import type { CliCommand, CommandContext } from './command';
+import { manifestStaleness } from './manifest-staleness';
 import { msg } from './messages';
-import type { CommandResult, Finding, JsonValue } from './output';
-import { findingFrom } from './output';
+import type { CommandResult, JsonValue } from './output';
 import { flagBool } from './parse';
 
 const countsOf = (manifest: Manifest): JsonValue => ({
@@ -27,21 +26,6 @@ const countsOf = (manifest: Manifest): JsonValue => ({
   policies: manifest.policies.length,
 });
 
-/**
- * The identical comparison `x verify`'s `manifest` step makes, through the identical function.
- * A buildId equality test here would answer "fresh" for a hand-edited file whose body no longer
- * hashes to the id it carries — and two commands giving two answers about one file is itself the
- * drift the manifest exists to prevent.
- */
-async function staleness(root: string, manifest: Manifest): Promise<Finding | undefined> {
-  try {
-    await assertNoDrift({ manifest, path: join(root, MANIFEST_FILENAME) });
-    return undefined;
-  } catch (error) {
-    return { ...findingFrom(error), at: MANIFEST_FILENAME };
-  }
-}
-
 export const manifestCommand: CliCommand = {
   spec: manifestSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -50,12 +34,9 @@ export const manifestCommand: CliCommand = {
     const counts = countsOf(manifest);
 
     if (flagBool(ctx.args, 'check')) {
-      // BOTH files the command writes: `--check` compared only `x.manifest.json`, so a stale
-      // `openapi.json` — the one the typed client is generated from — read as fresh.
-      const stale = [
-        ...[await staleness(root, manifest)].filter((one) => one !== undefined),
-        ...(await openApiStaleness(root, manifest)),
-      ];
+      // The gate's own check, through its function (`manifest-staleness.ts`): both files this
+      // command writes, and the same code for each condition `x verify`'s `manifest` step gives.
+      const stale = await manifestStaleness(root, manifest);
       return {
         ok: stale.length === 0 && findings.length === 0,
         command: 'manifest',

package/src/cmd-mcp.ts

@@ -3,17 +3,24 @@
 // 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, timingSafeEqual } from '@ultimat3/core';
+import {
+  markListening,
+  nanoid,
+  renderFixShellArg,
+  timingSafeEqual,
+  UltimateError,
+} from '@ultimat3/core';
 import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
 import { DEFAULT_PORT, mcpSpec } from './cmd-mcp-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
-import { intFlagOr, PORT_RANGE } from './flag-number';
+import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { CliMcpServer } from './mcp-host';
 import { createDevMcpServer, DEV_TOOL_SCOPES } from './mcp-host';
 import { msg } from './messages';
+import { isAddressInUse } from './metrics-endpoint';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
 
@@ -56,6 +63,21 @@ const notFound = (path: string): Response =>
     { status: 404, headers: { 'content-type': 'application/json' } },
   );
 
+/**
+ * The MCP port is bound already — by another `x mcp serve`, or by the inspector, whose default
+ * 9229 this one shares. `metrics-endpoint.ts`'s pattern: an `EADDRINUSE` throw becomes the
+ * framework's `X_PORT_IN_USE`, with the invocation one port over.
+ */
+export class McpPortInUseError extends UltimateError {
+  constructor(input: { port: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `port ${String(input.port)} is already bound, so x mcp serve could not open its HTTP transport`,
+      fix: `x mcp serve --transport http --port ${renderFixShellArg(String(neighbouringPort(input.port)), '9230')}`,
+    });
+  }
+}
+
 /** A running HTTP transport. `stop()` releases the socket AND the host's lazily booted services. */
 export interface McpHttpServer {
   readonly result: CommandResult;
@@ -70,7 +92,7 @@ export interface McpHttpServer {
  * directory outlive `run()` otherwise, and nothing — a test, an embedding caller, or a signal —
  * could ever release them.
  */
-export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
+export async function startMcpHttp(host: CliMcpServer, port: number): Promise<McpHttpServer> {
   const token = nanoid(32);
   const route = mcpHttpRoute({
     server: host.server,
@@ -83,17 +105,26 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
         ? { actor: host.caller.actor, scopes: DEV_TOOL_SCOPES }
         : null,
   });
-  const handle = Bun.serve({
-    port,
-    hostname: 'localhost',
-    fetch: (request: Request): Response | Promise<Response> => {
-      const url = new URL(request.url);
-      if (request.method !== route.method || url.pathname !== route.path) {
-        return notFound(route.path);
-      }
-      return route.handle(request);
-    },
-  });
+  let handle: ReturnType<typeof Bun.serve>;
+  try {
+    handle = Bun.serve({
+      port,
+      hostname: 'localhost',
+      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);
+        }
+        // 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 });
+      },
+    });
+  } catch (error) {
+    // The host booted before the bind; a refusal that left it open would leak its database.
+    await host.close();
+    if (isAddressInUse(error)) throw new McpPortInUseError({ port });
+    throw error;
+  }
   // Announces the socket as this process's own, so a caller on it is never mistaken for egress.
   const stopListening = markListening(handle.url.origin);
   const url = `${handle.url.origin}${route.path}`;
@@ -179,7 +210,7 @@ export const mcpCommand: CliCommand = {
     // starts is what releases the socket and the database. Registering a shutdown hook and
     // returning was the older shape — nothing installed a signal handler, so the hook was never
     // reached and the exit code closed the socket the line above had just announced.
-    const served = startMcpHttp(host, port);
+    const served = await startMcpHttp(host, port);
     return { ...served.result, hold: holdUntilShutdown('mcp', () => served.stop()) };
   },
 };

package/src/cmd-new.ts

@@ -110,7 +110,21 @@ export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
     ...appFiles(app, options.example),
   ];
   if (options.example) {
-    files.push(...resourceFiles('post', { surfaceDir: 'apps/web/app', feature: 'post' }));
+    files.push(
+      ...resourceFiles('post', {
+        surfaceDir: 'apps/web/app',
+        feature: 'post',
+        // The package `repoFiles` just named: the slice's `repo.ts` imports the typed handle from it.
+        dbModule: `@${app.kebab}/db`,
+        // And the catalog package beside it: every component the slice writes reads its strings
+        // through `useT()` from the module that registers them — the idiom `x g resource` writes
+        // into this same app, so the scaffold shows one way and not two (issue #249).
+        catalogModule: `@${app.kebab}/i18n`,
+        // `appFiles` above writes `apps/web/shared/shell.tsx`, so the page sits in the app frame —
+        // the same answer `x g resource` reads off the disk of this app afterwards.
+        shell: true,
+      }),
+    );
   }
   // `repoFiles`' own catalog entry and the example resource's both target the same flat catalog
   // file, so this has to be the merge-aware dedupe — the one `cmd-generate.ts` uses for `x g` —

package/src/cmd-planned.ts

@@ -3,8 +3,8 @@
 // does not exist", which is false and sends an agent looking for a typo. X_NOT_IMPLEMENTED plus a
 // fix naming the closest shipped command says the true thing, and `x help` lists them honestly.
 
+import { NotImplementedError } from '@ultimat3/core';
 import type { CliCommand } from './command';
-import { CliNotImplementedError } from './errors';
 import type { CommandResult } from './output';
 import type { CommandSpec } from './parse';
 
@@ -134,18 +134,28 @@ export const PLANNED_SUBCOMMANDS: readonly PlannedSubcommand[] = [
  * 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 {
+export function plannedSubcommand(command: string, subcommand: string): NotImplementedError {
   const planned = PLANNED_SUBCOMMANDS.find(
     (entry) => entry.command === command && entry.subcommand === subcommand,
   );
-  return new CliNotImplementedError({
-    feature: `x ${command} ${subcommand}`,
+  return new NotImplementedError({
+    cause: `x ${command} ${subcommand} is not implemented in this build`,
     // `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}`,
   });
 }
 
+/**
+ * What every invocation of a planned command answers — its `run`, and the dispatcher when the
+ * parser refused a flag before any `run` was reached. One builder, so the two cannot drift.
+ */
+export const plannedCommandError = (planned: PlannedCommand): NotImplementedError =>
+  new NotImplementedError({
+    cause: `x ${planned.name} is not implemented in this build`,
+    fix: planned.fix,
+  });
+
 const specFor = (planned: PlannedCommand): CommandSpec => ({
   name: planned.name,
   summary: `${planned.summary} (planned)`,
@@ -167,10 +177,7 @@ const toCommand = (planned: PlannedCommand): CliCommand => ({
   // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
   // promise this signature promises, including the dispatcher's own error path.
   async run(): Promise<CommandResult> {
-    throw new CliNotImplementedError({
-      feature: `x ${planned.name}`,
-      fix: planned.fix,
-    });
+    throw plannedCommandError(planned);
   },
 });
 

package/src/cmd-routes.ts

@@ -10,11 +10,21 @@ 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 { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagString } from './parse';
 
+/**
+ * Where a route comes from. A file route names its file; a MOUNTED one names the call that
+ * mounted it and every permission that gates it — there is no `page.tsx` to name, and printing the
+ * package would send a reader looking for a route file inside `node_modules`.
+ */
+const declaredBy = (route: RouteDescriptor): string =>
+  route.mount === undefined
+    ? route.file
+    : `${route.mount.by}() · ${route.mount.permissions.join(' + ')}`;
+
 /** Fixed-width columns so the output diffs cleanly between runs and between machines. */
 export function renderRouteTable(routes: readonly RouteDescriptor[]): readonly string[] {
   const rows = routes.map((route) => [
@@ -23,7 +33,7 @@ export function renderRouteTable(routes: readonly RouteDescriptor[]): readonly s
     route.mode,
     route.hydrate,
     route.offline,
-    route.file,
+    declaredBy(route),
   ]);
   const header = ['path', 'surface', 'render', 'hydrate', 'offline', 'file'];
   const widths = header.map((title, index) =>
@@ -42,7 +52,11 @@ const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
     render: route.mode,
     hydrate: route.hydrate,
     offline: route.offline,
-    budget: { js: route.budgetJs, lcp: route.budgetLcp },
+    budget: { js: route.budgetJs },
+    // Absent on a file route, never `null`: only a mounted route has the fact.
+    ...(route.mount === undefined
+      ? {}
+      : { mount: { by: route.mount.by, permissions: [...route.mount.permissions] } }),
   }));
 
 /**
@@ -69,6 +83,16 @@ export const routesCommand: CliCommand = {
   spec: routesSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('routes', ctx.cwd).dir;
+    // No positional: `x routes list --json` ran only because a stray word was ignored, which is
+    // how a retired spelling stayed in the route-miss fix lines. Refused before the app loads.
+    const stray = ctx.args.positionals[0];
+    if (stray !== undefined) {
+      throw new UnknownCommandError({
+        path: `routes ${stray}`,
+        known: ['routes'],
+        suggestion: 'routes --json',
+      });
+    }
     // Read before the app is loaded: a typo must not cost a boot to report, the rule `x mcp`'s
     // `--transport` already follows.
     const surface = readSurfaceFilter(flagString(ctx.args, 'surface'));

package/src/cmd-secrets-ring.ts

@@ -0,0 +1,76 @@
+// `x secrets rotate`'s key ring: the retired master keys kept in the sealed file so a value
+// `seal()` wrote under the previous key still opens after a rotation. Pure over the decrypted
+// map — `cmd-secrets.ts` owns the files and the terminal; `@ultimat3/core` owns the variable's
+// name and how a process reads it.
+
+import type { SecretValues } from '@ultimat3/core';
+import {
+  masterKeyId,
+  parseMasterKey,
+  SECRETS_FILE,
+  SECRETS_RETIRED_KEYS_ENV,
+  splitRetiredKeys,
+} from '@ultimat3/core';
+import { BadFlagError } from './errors';
+import { quoteArg } from './shell-quote';
+
+/** The app's own secrets: the ring is the framework's entry, never one `envSchema` declares. */
+export function appSecrets(values: SecretValues): SecretValues {
+  const { [SECRETS_RETIRED_KEYS_ENV]: _ring, ...rest } = values;
+  return rest;
+}
+
+const withRing = (values: SecretValues, ring: readonly string[]): SecretValues =>
+  ring.length === 0
+    ? appSecrets(values)
+    : { ...values, [SECRETS_RETIRED_KEYS_ENV]: ring.join(',') };
+
+const idOf = (hex: string, index: number): Promise<string> =>
+  masterKeyId(
+    parseMasterKey(
+      hex,
+      `${SECRETS_RETIRED_KEYS_ENV} (entry ${index + 1}) in ${SECRETS_FILE}`,
+      SECRETS_RETIRED_KEYS_ENV,
+    ),
+  );
+
+/** The ids of the keys the file still declares as retired, newest first. Safe to print. */
+export function retiredKeyIds(values: SecretValues): Promise<readonly string[]> {
+  return Promise.all(splitRetiredKeys(values[SECRETS_RETIRED_KEYS_ENV]).map(idOf));
+}
+
+/**
+ * The values a rotation seals: the same ones, with the key being replaced put at the head of the
+ * ring. Kept by DEFAULT and never behind a flag — the rotation overwrites the only copy of the old
+ * key on disk, so a rotation that did not keep it would make every sealed value unreadable with
+ * nothing left to recover it from.
+ */
+export function retire(values: SecretValues, previousHex: string): SecretValues {
+  const ring = splitRetiredKeys(values[SECRETS_RETIRED_KEYS_ENV]);
+  return withRing(values, [previousHex, ...ring.filter((hex) => hex !== previousHex)]);
+}
+
+/** The values without one retired key, named by id — or `X_CLI_BAD_FLAG` listing the ids there are. */
+export async function dropRetired(values: SecretValues, keyId: string): Promise<SecretValues> {
+  const ring = splitRetiredKeys(values[SECRETS_RETIRED_KEYS_ENV]);
+  const ids = await retiredKeyIds(values);
+  if (!ids.includes(keyId)) {
+    const [first] = ids;
+    throw new BadFlagError({
+      flag: 'drop',
+      command: 'secrets rotate',
+      reason:
+        first === undefined
+          ? `${SECRETS_FILE} declares no retired master key, so there is none to drop`
+          : `no retired master key has that id — ${SECRETS_FILE} declares ${ids.join(', ')}`,
+      fix:
+        first === undefined
+          ? 'x secrets show --json'
+          : `x secrets rotate --drop ${quoteArg(first)} --json`,
+    });
+  }
+  return withRing(
+    values,
+    ring.filter((_hex, index) => ids[index] !== keyId),
+  );
+}

package/src/cmd-secrets-spec.ts

@@ -9,11 +9,19 @@ export const SECRETS_SUBCOMMANDS = ['show', 'init', 'edit', 'set', 'rotate'] as
 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]',
+  usage: 'x secrets [show|init|edit|set <NAME>|rotate [--drop <keyId>]] [--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: [],
+  flags: [
+    {
+      name: 'drop',
+      type: 'string',
+      summary:
+        'rotate: remove one retired master key by id once every value sealed under it is re-sealed; generates no new key',
+      subcommands: ['rotate'],
+    },
+  ],
 };