@ultimat3/cli 22.15.0 → 23.0.0

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

package/src/cmd-secrets.ts

@@ -30,6 +30,7 @@ import {
 } from '@ultimat3/core';
 import { ENV_SCHEMA_EXPORT, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
+import { appSecrets, dropRetired, retire, retiredKeyIds } from './cmd-secrets-ring';
 import { secretsSpec } from './cmd-secrets-spec';
 import type { CliCommand, CommandContext } from './command';
 import {
@@ -40,6 +41,7 @@ import {
 } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
+import { flagString } from './parse';
 import { recoverRotation, rotateMasterKey } from './secrets-rotation';
 import { shredOnSignal } from './signal-shred';
 import { renderTable } from './table';
@@ -244,36 +246,65 @@ async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
   };
 }
 
+/**
+ * The closing half of a rotation: one retired key leaves the ring, by id, once nothing sealed
+ * under it is left. No new key is generated and the key file is not touched — the committed file
+ * is resealed under the key already in force.
+ */
+async function drop(session: Session, keyId: string): Promise<CommandResult> {
+  const { root, key } = session;
+  const after = await dropRetired(await readSecretsFile(root, key), keyId);
+  await writeSecretsFile(root, after, key);
+  const retired = await retiredKeyIds(after);
+  return {
+    ok: true,
+    command: 'secrets',
+    summary: msg('cli.secrets.dropped', { path: SECRETS_FILE, kid: keyId, count: retired.length }),
+    data: {
+      path: SECRETS_FILE,
+      keyId: await masterKeyIdOf(key),
+      dropped: keyId,
+      retiredKeyIds: [...retired],
+    },
+  };
+}
+
 /**
  * A new master key over the same values: staged beside the old one, the file sealed with it, then
  * made live (`rotateMasterKey`). Sealed first with the key file written last, a crash between the
  * two left a committed file no key on disk could open.
+ *
+ * The key being replaced joins the ring INSIDE the sealed file (`cmd-secrets-ring.ts`), so a value
+ * `seal()` wrote under it still opens and a deploy is still handed exactly one key.
  */
 async function rotate(ctx: CommandContext): Promise<CommandResult> {
-  const { root, key } = await open(ctx, 'rotate');
-  const values = await readSecretsFile(root, key);
+  const session = await open(ctx, 'rotate');
+  const dropping = flagString(ctx.args, 'drop');
+  if (dropping !== undefined) return drop(session, dropping);
+  const { root, key } = session;
+  const values = retire(await readSecretsFile(root, key), key.hex);
   const previous = await masterKeyIdOf(key);
   // Ignored BEFORE any key file is written, staged one included; the order inside is
   // `secrets-rotation.ts`'s: stage the key, seal, then rename it live.
   await ensureIgnored(root);
   const next = await rotateMasterKey(root, values);
   const keyId = await masterKeyIdOf(next);
+  const count = Object.keys(appSecrets(values)).length;
   return {
     ok: true,
     command: 'secrets',
-    summary: msg('cli.secrets.rotated', {
-      path: SECRETS_FILE,
-      from: previous,
-      to: keyId,
-      count: Object.keys(values).length,
-    }),
-    lines: [msg('cli.secrets.redeploy', { env: SECRETS_KEY_ENV, keyPath: SECRETS_KEY_FILE })],
+    summary: msg('cli.secrets.rotated', { path: SECRETS_FILE, from: previous, to: keyId, count }),
+    lines: [
+      msg('cli.secrets.redeploy', { env: SECRETS_KEY_ENV, keyPath: SECRETS_KEY_FILE }),
+      msg('cli.secrets.retired', { kid: previous }),
+    ],
     data: {
       path: SECRETS_FILE,
       keyPath: SECRETS_KEY_FILE,
       previousKeyId: previous,
       keyId,
-      count: Object.keys(values).length,
+      count,
+      retiredKeyIds: [...(await retiredKeyIds(values))],
     },
   };
 }
@@ -285,9 +316,12 @@ async function rotate(ctx: CommandContext): Promise<CommandResult> {
  */
 async function show(ctx: CommandContext): Promise<CommandResult> {
   const { root, key } = await open(ctx, 'show');
-  const values = await readSecretsFile(root, key);
+  const sealed = await readSecretsFile(root, key);
+  // The ring is the framework's own entry: reported by key id below, never as an app secret that
+  // `envSchema` forgot to declare.
+  const retired = await retiredKeyIds(sealed);
   const schema = await loadEnvSchema(root);
-  const summaries = describeSecrets(values);
+  const summaries = describeSecrets(appSecrets(sealed));
   const keyId = await masterKeyIdOf(key);
   const declared = (name: string): boolean | undefined =>
     schema === undefined ? undefined : schema[name] !== undefined;
@@ -309,6 +343,7 @@ async function show(ctx: CommandContext): Promise<CommandResult> {
       : [
           msg('cli.secrets.undeclared', { count: undeclared.length, names: undeclared.join(', ') }),
         ]),
+    ...(retired.length === 0 ? [] : [msg('cli.secrets.ring', { kids: retired.join(', ') })]),
   ];
   return {
     ok: true,
@@ -322,6 +357,7 @@ async function show(ctx: CommandContext): Promise<CommandResult> {
       path: SECRETS_FILE,
       keySource: key.source,
       keyId,
+      retiredKeyIds: [...retired],
       count: summaries.length,
       secrets: summaries.map((entry) => ({
         name: entry.name,