@ultimat3/cli 23.0.0 → 24.0.0

package/src/cmd-deploy.ts

@@ -176,10 +176,10 @@ export function planDeploy(
       command: [
         'docker',
         'compose',
-        // Compose interpolates `${SYNC_URL:?…}` and `${POSTGRES_PASSWORD:?…}` from the shell and
-        // `--env-file` only — never from a service's `env_file:`. Without this an operator who put
-        // them in `.env.production`, the one file the compose file tells them to fill, had every
-        // step die on a parse error. Global flag, so it precedes `-f`; the shell still wins over it.
+        // Compose interpolates `${SYNC_URL:?…}`, `${APP_URL:?…}` and `${POSTGRES_PASSWORD:?…}` from
+        // the shell and `--env-file` only — never from a service's `env_file:`. Without this an
+        // operator who put them in `.env.production`, the one file the compose file tells them to
+        // fill, had every step die on a parse error. Global flag, so it precedes `-f`; the shell still wins over it.
         '--env-file',
         join(root, PROD_ENV_FILE),
         '-f',

package/src/cmd-dev.ts

@@ -13,7 +13,6 @@ import type { OverlayNotice, RequestContext } from '@ultimat3/http';
 import { asCtx } from '@ultimat3/http';
 import type { Manifest } from '@ultimat3/manifest';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
-import { createIsrController } from '@ultimat3/render/server';
 import { loadSignInPath } from './app-auth';
 import { appManifest } from './app-manifest';
 import type { StalePin } from './app-reload-graph';
@@ -50,6 +49,7 @@ import {
   resolveServices,
   withRealtimeEvents,
 } from './runtime-bindings';
+import { attachedIsr } from './runtime-isr';
 import { liveFeedLabel } from './runtime-live-feed';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { replicaOverrides } from './runtime-replica';
@@ -239,9 +239,10 @@ async function bootDev(
   };
   const panels = devPanels(dashboard).map((panel) => panel.key);
 
-  // `x dev`'s own, so a reload can empty it: an `isr` page's first render was otherwise served for
-  // its whole ttl after every save, whatever the modules behind it now said.
-  const isr = createIsrController({ buildId });
+  // `x dev`'s own, so a reload can empty it (a save otherwise kept a page's first render for its
+  // ttl); attached, so a tag bust reaches it too. Released with the roles.
+  const { isr, release: releaseIsr } = attachedIsr({ buildId });
+  acquired.push(releaseIsr);
   const { routes, theme, speculation, errorStyles, mcpPath, mcpPaths } = await devRouteTable({
     isr,
     root: options.root,
@@ -350,16 +351,16 @@ async function bootDev(
     async stop() {
       watcher.close();
       await running.stop();
+      releaseIsr();
       await runtime.stop();
       // Released after the roles: a span opened by an in-flight request still has an exporter to
       // end into. `configureTelemetry` merges, so handing back the noop is how it is uninstalled —
       // leaving it in place would keep every span of the next `startDev` in this process's buffer.
       configureTelemetry({ exporter: noopExporter });
       traces.reset();
-      // Released with the exporter, after the roles, for the same reason: a statement still in
-      // flight is observed by the ledger that counted the rest of its request. Leaving it
-      // installed would keep every statement of the next `startDev` in this process's counts —
-      // and, worse, keep instrumentation on in a process that is no longer a dev server.
+      // With the exporter, for the same reason: an in-flight statement is observed by the ledger
+      // that counted its request. Left installed, the next `startDev`'s statements land in these
+      // counts — and instrumentation stays on in a process that is no longer a dev server.
       setStatementObserver(undefined);
       statements.reset();
     },

package/src/cmd-doctor-spec.ts

@@ -3,19 +3,12 @@
 
 import type { CommandSpec } from './parse';
 
-/** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
-export const DEFAULT_DOCTOR_PORT = 3000;
-
 export const doctorSpec: CommandSpec = {
   name: 'doctor',
   summary: 'environment, versions, drift, ports, PWA prerequisites — each with a fix command',
   usage: 'x doctor [--port 3000] [--json]',
   flags: [
-    {
-      name: 'port',
-      type: 'string',
-      summary: 'port to test',
-      default: String(DEFAULT_DOCTOR_PORT),
-    },
+    // No `default`: it would be indistinguishable from a typed value, and `PORT` could never win.
+    { name: 'port', type: 'string', summary: 'port to test (default: PORT, then 3000)' },
   ],
 };

package/src/cmd-doctor.ts

@@ -19,16 +19,18 @@ import {
 } from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
-import { DEFAULT_DOCTOR_PORT, doctorSpec } from './cmd-doctor-spec';
+import { doctorSpec } from './cmd-doctor-spec';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
+import { appUrlFindings } from './doctor-app-url';
+import { type AuthStorageFact, authStorageFindings, authStorageProbe } from './doctor-auth';
 import { coverageExcludesProbe, withCoverageExcludes } from './doctor-coverage';
 import { shippedGuardsProbe, withGuardListing } from './doctor-guards';
 import type { OfflineFallbackFact } from './doctor-offline';
 import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
 import type { SealedKeysFact } from './doctor-sealed';
 import { sealedKeyFindings, sealedKeysProbe } from './doctor-sealed';
-import { intFlagOr, PORT_RANGE, portPairAfter } from './flag-number';
+import { PORT_RANGE, portPairAfter, readIntFlag } from './flag-number';
 import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -37,6 +39,7 @@ import type { ParsedArgs } from './parse';
 import { portFree } from './port-probe';
 import { syncPortFor } from './role-sync';
 import { checkMigrationDrift } from './schema-drift';
+import { portFromEnv } from './serve-env';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -49,6 +52,8 @@ export interface DoctorProbe {
   /** App root, or undefined when the command runs outside an app. */
   readonly root: string | undefined;
   readonly port: number;
+  /** `APP_URL` as this environment declares it; `undefined` when unset. */
+  readonly appUrl: string | undefined;
   /** True while cursors are signed with the key shipped in the published package. */
   readonly devCursorSecret: boolean;
   /**
@@ -101,6 +106,11 @@ export interface DoctorProbe {
    * a retired key beside a sealed column means is `sealedKeyFindings`' pure rule.
    */
   sealedKeys(): Promise<SealedKeysFact>;
+  /**
+   * What an upgrade left in the auth tables for an operator to finish: unsealed second-factor
+   * secrets, and tables no release reads. Asked of an external database only.
+   */
+  authStorage(): Promise<AuthStorageFact>;
 }
 
 /** What `x doctor` reads about the embedded database, without opening it. */
@@ -257,6 +267,7 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
     );
   }
   findings.push(...(await portFindings(probe)));
+  findings.push(...appUrlFindings(probe.appUrl, probe.port));
   // `@ultimat3/pwa`'s own codes, not CLI twins of them. `X_PWA_NO_ICON_SOURCE` and
   // `X_PWA_NO_FALLBACK` used to be declared here for the same two conditions the package already
   // names — two codes for one condition, one of them registered by nobody, so `x errors explain`
@@ -293,20 +304,28 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   findings.push(...(await probe.snapshots()));
   // Sealed columns against the key ring: no key at all, or a rotation whose re-seal is pending.
   findings.push(...sealedKeyFindings(await probe.sealedKeys()));
+  findings.push(...authStorageFindings(await probe.authStorage()));
   return findings;
 }
 
 /**
- * The port to TEST, and the one place `x doctor` reads it. `PORT_RANGE.min` is 0 because `x dev
- * --port 0` means "let the kernel pick"; here 0 means nothing, and `Bun.serve({ port: 0 })` always
- * succeeds — so the port check could not fail, which is worse than not running it.
+ * The port to TEST, and the one place `x doctor` reads it: `devPortFor`'s order — `--port`, then
+ * `PORT` (`portFromEnv`, the one reader of it), then 3000 — so the probe answers about the port
+ * `x dev` will bind. It probed 3000 under `PORT=4000` while dev bound 4000 and 4001. `PORT_RANGE.min`
+ * is 0 because `x dev --port 0` means "let the kernel pick"; here 0 means nothing, and
+ * `Bun.serve({ port: 0 })` always succeeds — so the port check could not fail.
  */
-export const doctorPort = (args: ParsedArgs): number =>
-  intFlagOr(
-    args,
-    { name: 'port', command: 'doctor', ...PORT_RANGE, min: 1, example: 'x doctor --port 3000' },
-    DEFAULT_DOCTOR_PORT,
-  );
+export const doctorPort = (
+  args: ParsedArgs,
+  env: Readonly<Record<string, string | undefined>>,
+): number =>
+  readIntFlag(args, {
+    name: 'port',
+    command: 'doctor',
+    ...PORT_RANGE,
+    min: 1,
+    example: 'x doctor --port 3000',
+  }) ?? portFromEnv(env);
 
 /**
  * `DATABASE_URL` as BOTH halves of the database question read it: unset and blank are one case.
@@ -375,12 +394,19 @@ async function probeDatabase(url: string | undefined): Promise<Finding | null> {
   }
 }
 
-export function probeFor(cwd: string, bunVersion: string, port: number): DoctorProbe {
+export function probeFor(
+  cwd: string,
+  bunVersion: string,
+  port: number,
+  // The environment `doctorPort` read `PORT` from, so `APP_URL` is judged against the same one.
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): DoctorProbe {
   const root = findAppRoot(cwd)?.dir;
   return {
     bunVersion,
     root,
     port,
+    appUrl: env['APP_URL'],
     devCursorSecret: usesDevCursorSecret(),
     devStorageSecret: usesDevStorageSecret(),
     // `ULTIMATE_ENV`, through core — the one key that says which deploy this is, with `NODE_ENV`
@@ -408,14 +434,15 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
       root === undefined ? { fallback: null, routes: undefined } : offlineFallbackProbe(root),
     sealedKeys: async () =>
       root === undefined ? { columns: undefined, keys: undefined } : sealedKeysProbe(root),
+    authStorage: () => authStorageProbe(process.env['DATABASE_URL']),
   };
 }
 
 export const doctorCommand: CliCommand = {
   spec: doctorSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const port = doctorPort(ctx.args);
-    const probe = probeFor(ctx.cwd, ctx.bunVersion, port);
+    const port = doctorPort(ctx.args, ctx.env);
+    const probe = probeFor(ctx.cwd, ctx.bunVersion, port, ctx.env);
     const findings = await runDoctor(probe);
     const listed = withGuardListing(
       {

package/src/cmd-env.ts

@@ -4,15 +4,39 @@
 
 // Bun ships no path-join primitive, and `.env.example` is written app-root-relative.
 import { join } from 'node:path';
-import { checkEnv, ENV_EXAMPLE_PATH, ERROR_DOCS_URL, maskedEnvValues } from '@ultimat3/core';
+import {
+  checkEnv,
+  ENV_EXAMPLE_PATH,
+  ERROR_DOCS_URL,
+  maskedEnvValues,
+  UltimateError,
+} from '@ultimat3/core';
 import { envExampleFor, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
 import { envSpec } from './cmd-env-spec';
 import type { CliCommand, CommandContext } from './command';
-import { EnvSchemaMissingError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 
+/**
+ * `x env` was run in an app whose `app.config.ts` exports no `envSchema`. Not a silent success:
+ * writing a `.env.example` with no variables in it, or reporting "0 declared variables, all
+ * present", both read as a working environment declaration to whoever runs the command next.
+ *
+ * `X_CONFIG_INVALID` is core's code for "a configuration this process cannot boot on — env or
+ * `app.config.ts`", which is exactly this; the CLI names it in `CLI_BORROWED_ERROR_CODES` rather
+ * than minting a synonym.
+ */
+export class EnvSchemaMissingError extends UltimateError {
+  constructor(input: { subcommand: string }) {
+    super({
+      code: 'X_CONFIG_INVALID',
+      cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
+      fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
+    });
+  }
+}
+
 /**
  * Every subcommand needs the declaration, and an app without one is a usage error rather than an
  * empty success: `x env example` writing a two-comment file would look like it worked.

package/src/cmd-generate.ts

@@ -5,7 +5,7 @@
 import { existsSync } from 'node:fs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { registerAdminResources } from './admin-registration';
-import { registerGeneratedPrimitives } from './api-registration';
+import { indexBindingFindings, registerGeneratedPrimitives } from './api-registration';
 import { writeAppArtifacts } from './app-artifacts';
 import { appManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
@@ -18,7 +18,8 @@ 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 { refuseShadowedTypes } from './generate-shadow';
+import { containedPath, planWrites, writeFiles } from './generate-write';
 import { declareGeneratedImports } from './generated-imports';
 import { registerGeneratedEntities, resolveDbModule } from './handle-registration';
 import { resolveCatalogModule } from './i18n-audit';
@@ -28,6 +29,7 @@ import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
 import { quoteArg } from './shell-quote';
+import type { GeneratedFile } 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
@@ -40,6 +42,24 @@ export { GENERATORS } from './generate-kinds';
 export type { WriteReport } from './generate-write';
 export { dedupe, writeFiles } from './generate-write';
 
+/**
+ * Names to suggest when the API index already holds the requested one, in order: the feature's
+ * prefix, the kind's suffix, then that suffix numbered — kebab output, so each pastes into a shell
+ * as one argument. The caller re-plans each and offers the first the index does not hold either.
+ */
+const freeNames = (
+  kind: Generator,
+  name: string,
+  feature: string | undefined,
+): readonly string[] => {
+  const suffixed = `${kebab(name)}-${kind.split(':').at(-1) ?? kind}`;
+  return [
+    ...(feature === undefined ? [] : [`${kebab(feature)}-${kebab(name)}`]),
+    suffixed,
+    ...Array.from({ length: 8 }, (_unused, index) => `${suffixed}-${index + 2}`),
+  ];
+};
+
 export const generateCommand: CliCommand = {
   spec: generateSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -72,41 +92,68 @@ export const generateCommand: CliCommand = {
     // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
     const sliceEntity = await readSliceFile(root, kind, slice, 'entity.ts');
     const sliceRepo = await readSliceFile(root, kind, slice, 'repo.ts');
-    const files = generate({
-      kind,
-      name,
-      ...(featureFlag === undefined ? {} : { feature: featureFlag }),
-      ...(sliceErrors === undefined ? {} : { sliceErrors }),
-      ...(sliceEntity === undefined ? {} : { sliceEntity }),
-      ...(sliceRepo === undefined ? {} : { sliceRepo }),
-      ...(at === undefined ? {} : { at }),
-      ...(permission === undefined ? {} : { permission }),
-      surface,
-      live: flagBool(ctx.args, 'live'),
-      admin: flagBool(ctx.args, 'admin'),
-      locales,
-      ...(catalogModule === undefined ? {} : { catalogModule }),
-      ...(dbModule === undefined ? {} : { dbModule }),
-      shell,
-    });
+    const planFor = (planned: string) =>
+      generate({
+        kind,
+        name: planned,
+        ...(featureFlag === undefined ? {} : { feature: featureFlag }),
+        ...(sliceErrors === undefined ? {} : { sliceErrors }),
+        ...(sliceEntity === undefined ? {} : { sliceEntity }),
+        ...(sliceRepo === undefined ? {} : { sliceRepo }),
+        ...(at === undefined ? {} : { at }),
+        ...(permission === undefined ? {} : { permission }),
+        surface,
+        live: flagBool(ctx.args, 'live'),
+        admin: flagBool(ctx.args, 'admin'),
+        locales,
+        ...(catalogModule === undefined ? {} : { catalogModule }),
+        ...(dbModule === undefined ? {} : { dbModule }),
+        shell,
+      });
+    const files = planFor(name);
+    // On the planned files, before a dry run answers or anything lands: a name whose type spelling
+    // the emitted code also uses as a global is a slice that does not compile.
+    refuseShadowedTypes(files, kind, name);
+    // The caller's own invocation, EVERY flag it set included: without `--feature` the fix wrote
+    // a second slice beside the one that conflicted.
+    const flags = reproducedFlags(generateCommand.spec, ctx.args);
+    const invocation = [invocationOf(ctx, 'g'), kind, quoteArg(name), ...flags].join(' ');
+    // A module the API index would list under a name it already holds: refused before anything is
+    // written, with the same run under a name that is free — re-planned and re-checked, so the
+    // suggestion is never itself a conflict.
+    const pathsOf = (planned: readonly GeneratedFile[]) => planned.map((file) => file.path);
+    const held = await indexBindingFindings(root, pathsOf(files), '');
+    let bindings: readonly Finding[] = [];
+    if (held.length > 0) {
+      let free = freeNames(kind, name, featureFlag).at(-1) ?? name;
+      for (const candidate of freeNames(kind, name, featureFlag)) {
+        if ((await indexBindingFindings(root, pathsOf(planFor(candidate)), '')).length > 0)
+          continue;
+        free = candidate;
+        break;
+      }
+      const renamed = [invocationOf(ctx, 'g'), kind, quoteArg(free), ...flags].join(' ');
+      bindings = held.map((finding) => ({ ...finding, fix: renamed }));
+    }
+    const force = flagBool(ctx.args, 'force');
     if (flagBool(ctx.args, 'dry-run')) {
+      // The write plan, never the bare file list: what the real run would write, skip and refuse.
+      const plan = await planWrites(root, files, force, invocation);
+      const findings = [...plan.conflicts, ...bindings];
+      const planned = findings.length === 0 ? plan.written : [];
       return {
-        ok: true,
+        ok: findings.length === 0,
         command: 'g',
-        summary: msg('cli.generate.planned', { count: files.length, kind, name }),
-        data: { files: files.map((file) => file.path), dryRun: true },
-        lines: files.map((file) => msg('cli.file.added', { path: file.path })),
+        summary: msg('cli.generate.planned', { count: planned.length, kind, name }),
+        data: { files: planned, dryRun: true },
+        lines: planned.map((file) => msg('cli.file.added', { path: file })),
+        findings,
       };
     }
-    // The caller's own invocation, EVERY flag it set included: without `--feature` the fix wrote
-    // a second slice beside the one that conflicted.
-    const invocation = [
-      invocationOf(ctx, 'g'),
-      kind,
-      quoteArg(name),
-      ...reproducedFlags(generateCommand.spec, ctx.args),
-    ].join(' ');
-    const report = await writeFiles(root, files, flagBool(ctx.args, 'force'), invocation);
+    const report =
+      bindings.length > 0
+        ? { written: [], conflicts: bindings }
+        : await writeFiles(root, files, force, invocation);
     // 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

package/src/cmd-help.ts

@@ -2,7 +2,9 @@
 // never describe a flag that does not exist. Built as a factory over the spec list to keep the
 // registry acyclic.
 
+import { nearestName } from '@ultimat3/core';
 import type { CliCommand, CommandContext } from './command';
+import { UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import type { CommandSpec, FlagSpec } from './parse';
@@ -18,17 +20,28 @@ const flagLine = (flag: FlagSpec): string => {
  * The one resolution of a topic, read by both renderers. `--json` filtered on `spec.name === topic`
  * of its own, so the two disagreed about exactly the inputs a caller is least sure of: `x help
  * generate --json` answered `[]` — "that command does not exist" — while the page beside it printed
- * `g`, and `x help nosuch --json` answered `[]` while the page printed the whole catalogue.
+ * `g`. A topic naming no command is refused, as `x <topic>` itself is: answering the catalogue
+ * with exit 0 read as that command's usage to a caller that never compared the names.
  */
 const specFor = (
   specs: readonly CommandSpec[],
   topic: string | undefined,
-): CommandSpec | undefined =>
-  topic === undefined
-    ? undefined
-    : specs.find((entry) => entry.name === topic || (entry.aliases ?? []).includes(topic));
+): CommandSpec | undefined => {
+  if (topic === undefined) return undefined;
+  const found = specs.find(
+    (entry) => entry.name === topic || (entry.aliases ?? []).includes(topic),
+  );
+  if (found !== undefined) return found;
+  const names = specs.map((entry) => entry.name);
+  const nearest = nearestName(topic, [...names, ...specs.flatMap((entry) => entry.aliases ?? [])]);
+  throw new UnknownCommandError({
+    path: `help ${topic}`,
+    known: names,
+    suggestion: nearest === undefined ? 'help' : `help ${nearest}`,
+  });
+};
 
-/** What `--json` reports: the one resolved command, or — as the human render does — all of them. */
+/** What `--json` reports: the one resolved command, or — with no topic — all of them. */
 export function helpTopic(
   specs: readonly CommandSpec[],
   topic: string | undefined,

package/src/cmd-i18n.ts

@@ -196,14 +196,15 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   const { registered, findings: indexFindings } = await syncI18nIndex(root);
 
   const keys = catalogKeys(seeded).length;
+  // The catalog is on disk either way, but a finding fails the run: a `packages/i18n/src/index.ts`
+  // that would not import is why `from` may be the framework's `en` instead of the app's own
+  // default, and an index the locale could not be registered in is a red `i18n` gate step.
+  const findings = [...indexFindings, ...app.findings];
   return {
-    // The catalog is on disk, so the command did what it was asked. `loadApp`'s findings ride along
-    // rather than flip that: a `packages/i18n/src/index.ts` that would not import is why `from` may
-    // be the framework's `en` instead of the app's own default, and silence there is the bug.
-    ok: true,
+    ok: findings.length === 0,
     command: 'i18n',
     summary: msg('cli.i18n.added', { locale, keys, from: from ?? locale }),
-    findings: [...indexFindings, ...app.findings],
+    findings,
     // `registered` is false only for an app with no `packages/i18n` at all — a fact a caller has
     // to be able to read, because it is the one case where the locale is on disk and unselectable.
     data: { locale, from: from ?? locale, keys, path, registered },
@@ -274,16 +275,16 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
   const { registered, findings: indexFindings } = await syncI18nIndex(root);
 
   const total = catalogKeys(merged).length;
+  // Same as `runAdd`: the merge landed, and a finding still fails the run.
+  const findings = [...indexFindings, ...app.findings];
   return {
-    // Same as `runAdd`: the merge landed, and `loadApp`'s findings say whether `from` is the app's
-    // own default or the framework's fallback standing in for an i18n module that would not import.
-    ok: true,
+    ok: findings.length === 0,
     command: 'i18n',
     summary: msg('cli.i18n.synced', { locale, from: from ?? locale, added: added.length, total }),
     // The keys themselves, raw — `runCheck` lists gaps the same way, because a key is a value an
     // author copies and never prose the catalog owns.
     lines: seeded ? added.map((key) => `  ${key}`) : [],
-    findings: [...indexFindings, ...app.findings],
+    findings,
     data: {
       locale,
       from: from ?? locale,

package/src/cmd-jobs.ts

@@ -66,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.
@@ -76,6 +87,7 @@ 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;
 }
 
@@ -211,7 +223,7 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
 }
 
 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',
@@ -226,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,
@@ -243,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.
@@ -258,7 +270,7 @@ 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 id = requireIdPositional(ctx, 'rm', driver);
   const removed = await removeJob(driver, id);
   if (removed === undefined) throw new JobUnknownError({ id, driver: driver.name });
   return {
@@ -270,7 +282,7 @@ async function runRm(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
 }
 
 async function runPromote(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const promoted = await promoteJob(driver, requireIdPositional(ctx, 'promote'));
+  const promoted = await promoteJob(driver, requireIdPositional(ctx, 'promote', driver));
   return {
     ok: true,
     command: 'jobs',

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',