@ultimat3/cli 22.14.0 → 23.0.0

package/src/cmd-generate.ts

@@ -4,6 +4,7 @@
 
 import { existsSync } from 'node:fs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { registerAdminResources } from './admin-registration';
 import { registerGeneratedPrimitives } from './api-registration';
 import { writeAppArtifacts } from './app-artifacts';
 import { appManifest } from './app-manifest';
@@ -13,18 +14,21 @@ import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
 import { assertFeatureExists } from './generate-feature';
 import { generate, sliceDir } from './generate-files';
+import { ungrantedByGenerator } from './generate-grant-findings';
 import { grantGeneratedPermissions } from './generate-grants';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { containedPath, writeFiles } from './generate-write';
+import { declareGeneratedImports } from './generated-imports';
+import { registerGeneratedEntities, resolveDbModule } from './handle-registration';
 import { resolveCatalogModule } from './i18n-audit';
-import { syncI18nIndex } from './i18n-index';
+import { catalogLocales, syncI18nIndex } from './i18n-index';
 import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
 import { quoteArg } from './shell-quote';
-import { kebab, resolveLocales } from './templates';
+import { kebab, names, resolveLocales } from './templates';
 
 // One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
 // fixture reach the kinds, the pure file list and the writer through this module, and a second path
@@ -46,7 +50,7 @@ export const generateCommand: CliCommand = {
     // Both flags are resolved before a single file is planned: a bad surface or a locale that is
     // really a path fails here, with nothing written and nothing to undo.
     const surface = readSurface(flagString(ctx.args, 'surface'), kind, name);
-    const locales = resolveLocales(flagList(ctx.args, 'locales'));
+    const locales = resolveLocales(await namedOrAppLocales(root, flagList(ctx.args, 'locales')));
     const at = flagString(ctx.args, 'at');
     // Read with the two above, and refused here for their reason: the value is spliced into the
     // emitted source three times, and a value that is not a `<resource>:<verb>` is a page the app
@@ -55,6 +59,10 @@ export const generateCommand: CliCommand = {
     // Read before a file is planned, like the flags above: which module a generated component
     // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
     const catalogModule = await resolveCatalogModule(root);
+    // And for the same reason: which package a generated `repo.ts` imports the typed handle from.
+    const dbModule = await resolveDbModule(root);
+    // And whether the app has the frame a resource's page sits in.
+    const shell = existsSync(containedPath(root, SHELL_MODULE));
     // Read for the same reason: which errors the slice declares is written on THIS app's disk.
     const slice = sliceDir(surface, kebab(featureFlag ?? name));
     // A named slice that is not there is refused, never invented (X_FEATURE_UNKNOWN).
@@ -78,6 +86,8 @@ export const generateCommand: CliCommand = {
       admin: flagBool(ctx.args, 'admin'),
       locales,
       ...(catalogModule === undefined ? {} : { catalogModule }),
+      ...(dbModule === undefined ? {} : { dbModule }),
+      shell,
     });
     if (flagBool(ctx.args, 'dry-run')) {
       return {
@@ -97,13 +107,29 @@ export const generateCommand: CliCommand = {
       ...reproducedFlags(generateCommand.spec, ctx.args),
     ].join(' ');
     const report = await writeFiles(root, files, flagBool(ctx.args, 'force'), invocation);
-    // The two edits a generated primitive needs outside its own slice, performed rather than left
-    // as findings: a declared permission granted to a role, and a job listed in `defineApi`.
-    // Before the manifest load below, so the projection sees both.
+    // The three edits a generated primitive needs outside its own slice, performed rather than
+    // left as findings: a declared permission granted to a role, a job listed in `defineApi`, and
+    // an entity added to the typed handle its `repo.ts` reads through. Before the manifest load
+    // below, so the projection sees all three — a repo reading a table the handle lacks would not
+    // load at all.
+    const handle = await registerGeneratedEntities(root, report.written, dbModule);
+    // And a fourth, for `--admin`: the override it wrote, listed where `defineAdmin()` reads it.
+    const adminWiring = await registerAdminResources(root, report.written);
+    // And a fifth, last because the others add imports too: every sibling workspace a written file
+    // imports, declared in the manifest it landed under — or `package-shape` refuses the output.
     const edited = [
-      ...(await grantGeneratedPermissions(root, report.written)),
-      ...(await registerGeneratedPrimitives(root, report.written)),
+      ...new Set([
+        ...(await grantGeneratedPermissions(root, report.written)),
+        ...(await registerGeneratedPrimitives(root, report.written)),
+        ...handle.edited,
+        ...adminWiring.edited,
+        ...(await declareGeneratedImports(root, report.written)),
+      ]),
     ];
+    // A grant that edit could not place is said so, with the role each permission belongs to: an
+    // app whose role map is not the scaffold's got no grant and no word, and a 403 on every
+    // endpoint the run had just written.
+    const ungranted = await ungrantedByGenerator(root, report.written);
     // A locale's catalog existing on disk and the app being able to select it are two different
     // facts — see `syncI18nIndex`. Runs before the manifest load below so a route or resource
     // this same invocation just wrote never gets projected against a stale catalog registration.
@@ -133,17 +159,36 @@ export const generateCommand: CliCommand = {
         buildId = manifest.buildId;
       } else loadFailures.push(...findings);
     }
-    const findings = [...report.conflicts, ...indexSync.findings, ...loadFailures];
+    const findings = [
+      ...report.conflicts,
+      ...handle.findings,
+      ...ungranted,
+      ...adminWiring.findings,
+      ...indexSync.findings,
+      ...loadFailures,
+    ];
     // One list behind all three renderings. The manifest was printed as a `+` line while the count
     // beside it came from `report.written` alone, so `x g island` said "wrote 2 file(s)" over three
     // lines — and `--json` carried the shorter list, which is the drift `--json` exists to prevent.
     const written = [...report.written, ...edited, ...artifacts];
+    // Named only over a clean run: with a finding, the finding's own `fix:` is the next command.
+    const table = names(isEntityKind(kind) ? name : (featureFlag ?? name)).table;
+    const next = findings.length === 0 ? nextSteps(report.written, edited, table) : [];
     return {
       ok: findings.length === 0,
       command: 'g',
-      summary: msg('cli.generate.wrote', { count: written.length, kind, name }),
+      summary:
+        next.length === 0
+          ? msg('cli.generate.wrote', { count: written.length, kind, name })
+          : msg('cli.generate.wroteNext', {
+              count: written.length,
+              kind,
+              name,
+              next: next.join(' && '),
+            }),
       data: {
         files: written,
+        ...(next.length === 0 ? {} : { next }),
         ...(buildId === undefined ? {} : { manifest: { buildId } }),
       },
       lines: written.map((path) => msg('cli.file.added', { path })),
@@ -152,6 +197,59 @@ export const generateCommand: CliCommand = {
   },
 };
 
+/**
+ * `--locales` when the caller named any, and otherwise every locale the app already has a catalog
+ * for: a key written to `en` alone in an app that also ships `es` renders ⟦key⟧ for every Spanish
+ * reader. A stem that is not a locale tag is some other JSON file, and not a catalog to write to.
+ */
+async function namedOrAppLocales(
+  root: string,
+  named: readonly string[],
+): Promise<readonly string[]> {
+  if (named.length > 0) return named;
+  return (await catalogLocales(root)).filter((stem) => {
+    try {
+      return Intl.getCanonicalLocales(stem).length === 1;
+    } catch {
+      return false;
+    }
+  });
+}
+
+const isEntityKind = (kind: Generator): boolean => kind === 'entity' || kind === 'resource';
+
+/**
+ * What a run that declared a table owes before the app can read it, in the order it has to
+ * happen — each one a command that runs as printed. `bunx x`, never a bare `x`: `bun install`
+ * links the binary into `./node_modules/.bin` and nowhere on PATH.
+ *
+ * `bun install` leads when a manifest gained a workspace edge: the handle imports the entity from
+ * the web workspace, and an edge only a manifest declares is not linked until the install runs.
+ * `x db gen` then writes the migration AND `packages/db/schema/`, which the `drift` step holds.
+ */
+export function nextSteps(
+  written: readonly string[],
+  edited: readonly string[],
+  table: string,
+): readonly string[] {
+  if (!written.some((path) => path.endsWith('/entity.ts'))) return [];
+  return [
+    ...(edited.some((path) => path.endsWith('package.json')) ? ['bun install'] : []),
+    `bunx x db gen "create ${table}"`,
+    'bunx x db migrate',
+    // A page that mounts an island has a byte budget only a build can weigh — measured on `x new`'s
+    // app (`RESOURCE_PAGE_BUDGET`), and an app that charges more per document is over it on this
+    // run rather than on the next `bin/check`.
+    ...(written.some((path) => path.endsWith('/page.tsx')) ? [MEASURE_PAGE] : []),
+  ];
+}
+
+/** The two commands that weigh a page against its budget: the build writes the bytes it reads. */
+export const MEASURE_PAGE = 'bunx x build --target static && bunx x verify --only budgets';
+
+/** The frame `x new` writes: a resource's page renders inside it when the app has one. */
+export const SHELL_MODULE = 'apps/web/shared/shell.tsx';
+
 /**
  * The slice's `errors.ts`, for the two generators whose template throws from it. Only those two:
  * a route or an island names no slice, and the "feature" the fallback derives for them is a path
@@ -167,20 +265,23 @@ async function readSliceErrors(
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }
 
+/** The generators whose output depends on what the slice's `entity.ts` / `repo.ts` declare. */
+const READS_SLICE: ReadonlySet<Generator> = new Set(['job', 'task', 'action', 'mutator', 'query']);
+
 /**
- * `job`, `task`, `action` and `mutator`: the slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the
- * generator's kind is neither or the file does not exist yet. `readSliceErrors`'s reason —
- * whichever generator reads it decides on THIS app's disk, not on a default the template assumes.
+ * The slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the generator's kind reads
+ * neither or the file does not exist yet. `readSliceErrors`'s reason — whichever generator reads
+ * it decides on THIS app's disk, not on a default the template assumes. `query` reads them for its
+ * test alone: whether it may store a row is a fact about the entity an author may have reshaped.
+ * Exported so a test can ask which kinds read the disk without running a whole generation.
  */
-async function readSliceFile(
+export async function readSliceFile(
   root: string,
   kind: Generator,
   slice: string,
   name: 'entity.ts' | 'repo.ts',
 ): Promise<string | undefined> {
-  if (kind !== 'job' && kind !== 'task' && kind !== 'action' && kind !== 'mutator') {
-    return undefined;
-  }
+  if (!READS_SLICE.has(kind)) return undefined;
   const file = containedPath(root, `${slice}/${name}`);
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }

package/src/cmd-jobs-spec.ts

@@ -3,7 +3,17 @@
 
 import type { CommandSpec } from './parse';
 
-export const JOBS_SUBCOMMANDS = ['ls', 'show', 'retry', 'cancel', 'drain'] as const;
+export const JOBS_SUBCOMMANDS = [
+  'ls',
+  'show',
+  'retry',
+  'cancel',
+  'rm',
+  'promote',
+  'pause',
+  'resume',
+  'drain',
+] as const;
 
 /**
  * The drivers a drain may move work ONTO — every one of them durable, and that is the whole rule.
@@ -13,9 +23,9 @@ export const DRAIN_TARGETS = ['redis', 'nats'] as const;
 
 export const jobsSpec: CommandSpec = {
   name: 'jobs',
-  summary: 'list, show, retry, cancel and drain the job queue',
+  summary: 'list, show, retry, cancel, remove and promote jobs; pause and resume a queue; drain',
   usage:
-    '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]',
+    'x jobs [ls|show <id>|retry <id>|cancel <id>|rm <id>|promote <id>|pause <queue>|resume <queue>|drain --to <driver>] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--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.
@@ -25,6 +35,12 @@ export const jobsSpec: CommandSpec = {
     { 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: 'after',
+      type: 'string',
+      summary: 'ls: the next page — the cursor the previous page printed',
+      subcommands: ['ls'],
+    },
     // Each of these is read by ONE subcommand — `retryJob`, `cancelJob`, `runDrain` — and says
     // so in its own summary. The scope is what makes the parser refuse it anywhere else instead
     // of accepting it and ignoring it: `x db gen --dry-run` parsed and wrote the migration.

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';
@@ -64,6 +79,33 @@ function requireIdPositional(ctx: CommandContext, sub: string): string {
   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 +139,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,6 +203,9 @@ 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),
     },
   };
 }
@@ -193,6 +256,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');
+  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'));
+  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 +351,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 +366,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-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-routes.ts

@@ -15,6 +15,16 @@ 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) =>
@@ -43,6 +53,10 @@ const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
     hydrate: route.hydrate,
     offline: route.offline,
     budget: { js: route.budgetJs, lcp: route.budgetLcp },
+    // 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] } }),
   }));
 
 /**

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'],
+    },
+  ],
 };