@ultimat3/cli 2.0.0 → 4.0.0

package/src/cmd-routes.ts

@@ -4,11 +4,12 @@
 // The rows are `@ultimat3/render`'s own `describeRoutes()`: the CLI prints the route table, it
 // does not keep a second one.
 
-import type { RouteDescriptor } from '@ultimat3/render';
-import { describeRoutes } from '@ultimat3/render';
+import type { RouteDescriptor, Surface } from '@ultimat3/render';
+import { describeRoutes, SURFACES } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
+import { BadFlagError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagString } from './parse';
@@ -43,18 +44,40 @@ const routeJson = (routes: readonly RouteDescriptor[]): JsonValue =>
     budget: { js: route.budgetJs, lcp: route.budgetLcp },
   }));
 
+/**
+ * A closed set, because the filter was a bare `===`: `x routes --surface App` and `--surface pages`
+ * matched no row and reported `0 routes` with exit 0, which is the same output an app with no
+ * routes gives — so a typo and an empty route table are indistinguishable, and only one of them is
+ * a bug the caller can see. `SURFACES` is `@ultimat3/render`'s own declaration of what a surface
+ * is; a list restated here would be a second answer to it (`x g --surface` is `generate-kinds.ts`'s
+ * narrower question — which surface to SCAFFOLD onto — and takes site|app alone).
+ */
+export function readSurfaceFilter(raw: string | undefined): Surface | undefined {
+  const surfaces: readonly string[] = SURFACES;
+  if (raw === undefined) return undefined;
+  if (surfaces.includes(raw)) return raw as Surface;
+  throw new BadFlagError({
+    flag: 'surface',
+    command: 'routes',
+    reason: `"${raw}" is not a surface (known: ${SURFACES.join(', ')})`,
+    fix: 'x routes --surface app --json',
+  });
+}
+
 export const routesCommand: CliCommand = {
   spec: {
     name: 'routes',
     summary: 'the route table: path, surface, render mode, hydrate, offline',
-    usage: 'x routes [--surface site|app] [--json]',
+    usage: 'x routes [--surface site|app|api|shared] [--json]',
     requiresApp: true,
     flags: [{ name: 'surface', type: 'string', summary: 'filter by surface' }],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('routes', ctx.cwd).dir;
+    // 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'));
     const { findings } = await loadApp(root);
-    const surface = flagString(ctx.args, 'surface');
     const routes = describeRoutes().filter(
       (route) => surface === undefined || route.surface === surface,
     );

package/src/cmd-secrets.ts

@@ -32,7 +32,7 @@ import { ENV_SCHEMA_EXPORT, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import {
-  BadFlagError,
+  MissingPositionalError,
   SecretsEditFailedError,
   SecretsEditorMissingError,
   SecretsExistsError,
@@ -210,11 +210,11 @@ async function edit(ctx: CommandContext, io: SecretsIo): Promise<CommandResult>
 async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
   const name = ctx.args.positionals[0];
   if (name === undefined) {
-    throw new BadFlagError({
-      flag: 'name',
-      command: 'secrets',
-      reason: 'x secrets set <NAME> needs the environment variable name to seal the value under',
-      fix: 'printf %s "$TOKEN" | x secrets set STRIPE_KEY --json',
+    // The name is the positional this command seals under, never a `--name` flag it does not have.
+    throw new MissingPositionalError({
+      command: 'secrets set',
+      positional: 'NAME',
+      example: 'printf %s "$TOKEN" | x secrets set STRIPE_KEY --json',
     });
   }
   const { root, key } = open(ctx, 'set');

package/src/cmd-test.ts

@@ -9,9 +9,10 @@ import { readIntFlag } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
+import { quoteArg } from './shell-quote';
 import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
-import { quoteArg, runShards } from './test-shards';
-import { defaultWorkers } from './test-workers';
+import { runShards } from './test-shards';
+import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import type { TestType } from './verify-tests';
 import { TEST_TYPES } from './verify-tests';
 
@@ -25,6 +26,12 @@ const readIndex = (args: ParsedArgs, name: string, min: number): number | undefi
     name,
     command: 'test',
     min,
+    // The ceiling the summary already claimed and the reader never enforced: `--workers 5000` was
+    // accepted, `planShards` clamps only to the file count, and `runParallel` `Promise.all`s them —
+    // one Bun process per test FILE, each with the framework module graph and a cloned database.
+    // `--worker` is an index into that split, so the same bound holds it (the exact upper index is
+    // `workers - 1`, refused a line below by the check that knows the real width).
+    max: WORKER_CEILING,
     example: `x test --${name} ${Math.max(min, 1)}`,
   });
 
@@ -54,7 +61,11 @@ export const testCommand: CliCommand = {
     usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--workers N] [--worker I] [--json]`,
     positionalChoices: TEST_TYPES,
     flags: [
-      { name: 'workers', type: 'string', summary: 'process count (default: CPUs - 1, max 8)' },
+      {
+        name: 'workers',
+        type: 'string',
+        summary: `process count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+      },
       {
         name: 'worker',
         type: 'string',

package/src/cmd-verify.ts

@@ -13,6 +13,8 @@ import {
   MANIFEST_FILENAME,
   verifyContract,
 } from '@ultimat3/manifest';
+import type { MetaIssue } from '@ultimat3/seo';
+import { validateMeta } from '@ultimat3/seo';
 import { checkAgentsMd } from './app-agents-md';
 import { checkAppBoundaries } from './app-boundaries';
 import { envExampleFindings } from './app-env';
@@ -24,13 +26,15 @@ import type { CliCommand, CommandContext } from './command';
 import { checkDestructiveMigrations } from './db-destructive';
 import { checkDocumentStyles, documentSurfaces } from './document-styles';
 import { checkSourceDrift } from './drift';
-import { checkErrorFixes } from './error-contract';
+import { checkErrorFixReport } from './error-contract';
 import { readIntFlag } from './flag-number';
 import { guardFindings } from './guards';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
+import { scanSiteMeta } from './seo-meta';
+import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import {
   floorProblemFindings,
   floorRequires,
@@ -44,6 +48,9 @@ import { TEST_STEPS } from './verify-tests';
 import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
 
 /** The whole contract, in cost order. Every check the framework knows how to make lives here. */
+/** The one file that makes the `roadmap` step answerable, and therefore what `applies` reads. */
+const ROADMAP_FILE = join('docs', 'idea', '14-roadmap.md');
+
 export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'typecheck',
@@ -111,8 +118,21 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     summary: 'every X_* code has a runnable fix and a docs page',
     // The fix-line half runs anywhere source does. The docs half needs a reference page to check
     // against, and which file that is belongs to the host repo — hence `hostFindings`.
-    run: async (ctx) =>
-      fromFindings([...(await checkErrorFixes(ctx.root)), ...(await hostFindings(ctx, 'errors'))]),
+    //
+    // The coverage line rides in `output`, which `--json` carries verbatim: a scan without a
+    // parser cannot read every fix, and a step that reports only findings claims a completeness
+    // it does not have. "checked 412, could not read 27" is what a reader can act on.
+    async run(ctx) {
+      const report = await checkErrorFixReport(ctx.root);
+      const findings = [...report.findings, ...(await hostFindings(ctx, 'errors'))];
+      return {
+        ...fromFindings(findings),
+        output: msg('cli.verify.fixCoverage', {
+          checked: report.checked,
+          unreadable: report.unreadable,
+        }),
+      };
+    },
   },
   ...TEST_STEPS,
   {
@@ -186,6 +206,30 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       ]);
     },
   },
+  {
+    name: 'seo',
+    summary: 'every indexable site/ route has a title and a description a search result can render',
+    // The SEO checkers shipped in `@ultimat3/seo` with no caller anywhere — `validateMeta` and its
+    // asserts were reachable only by an app that called them itself, which is what
+    // `packages/seo/src/errors.ts`'s own header said. This is the caller.
+    //
+    // Its own step rather than a rider on `budgets`: that step asks what a document WEIGHS and
+    // this one asks what it SAYS, and a missing `<title>` reported under `budgets` would hand the
+    // reader a fix for the wrong question (axiom 4). It costs no second app load — `loadApp`
+    // imports each module once per process, so this runs on the registries `budgets` just filled.
+    applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
+    async run(ctx) {
+      const scan = await scanSiteMeta(ctx.root);
+      // No `baseUrl`: an app declares no base URL anywhere (`packages/core/src/config.ts` has no
+      // such key), so canonical checks are skipped rather than run against an origin this file
+      // invented. `seo-meta.ts` spells out why that is the honest half.
+      const report = validateMeta(scan.records);
+      return {
+        ok: scan.findings.length === 0 && report.ok,
+        findings: [...scan.findings, ...report.issues.map(seoFinding)],
+      };
+    },
+  },
   {
     name: 'manifest',
     summary: 'the files an agent reads: generated facts, hand-written conventions, the env example',
@@ -224,8 +268,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     name: 'roadmap',
     summary: "every roadmap milestone's status marker matches what is actually on disk",
     // A generated app ships no `docs/idea/14-roadmap.md` — only the framework monorepo does, so
-    // only a host that registers this check has anything for the step to verify.
-    applies: async (ctx) => ctx.hostChecks?.roadmap !== undefined,
+    // the FILE is what decides. It keyed on `ctx.hostChecks?.roadmap` until `As of 2026-08`, which
+    // is a fact about the CALL: a caller of the exported `runVerify(VERIFY_STEPS, ctx)` passing no
+    // `hostChecks`, in a repo whose committed `x.verify.json` names `roadmap`, got
+    // `X_VERIFY_SUITE_VANISHED` — whose `fix:` is the command that had just failed.
+    applies: async (ctx) => existsSync(join(ctx.root, ROADMAP_FILE)),
     run: async (ctx) => fromFindings(await hostFindings(ctx, 'roadmap')),
   },
 ];
@@ -377,6 +424,18 @@ function findingOf(error: unknown, step: string): Finding {
   };
 }
 
+/**
+ * One `MetaIssue` as the gate reports it. `at` is the route FILE and never the URL: every seo error
+ * already names the file in its cause, and `at` is what an agent opens.
+ */
+const seoFinding = (issue: MetaIssue): Finding => ({
+  code: issue.code,
+  cause: issue.cause,
+  fix: issue.fix,
+  docs: `https://ultimate.dev/errors/${issue.code}`,
+  at: issue.file,
+});
+
 export const verifyCommand: CliCommand = {
   spec: {
     name: 'verify',
@@ -390,7 +449,7 @@ export const verifyCommand: CliCommand = {
       {
         name: 'workers',
         type: 'string',
-        summary: 'test processes per parallel step (default: CPUs - 1, max 8)',
+        summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
       },
     ],
   },
@@ -405,13 +464,24 @@ export const verifyCommand: CliCommand = {
   },
 };
 
-/** `x test --workers` refuses the same values for the same reason — and now through the same
- * reader, so the claim is enforced rather than asserted in a comment. */
-const readWorkers = (args: ParsedArgs): number | undefined =>
+/**
+ * Both bounds are the constants the flag summary already names, so `x help verify` and the reader
+ * cannot disagree. Exported for the test that pins them: the command's `run` reaches this only
+ * after the whole gate would have started.
+ *
+ * `max` is the ceiling. Without it `--workers 5000` parsed, `planShards` clamped only to the file
+ * count, and `runParallel` `Promise.all`ed one Bun process per test file. `min` is `WORKER_FLOOR`,
+ * the same number `defaultWorkers` will not go below — the gate spreads or it does not shard, and
+ * `--workers 1` was a serial run the summary said was impossible. `x test --workers 1` stays legal
+ * and is deliberately NOT this reader: `runShards` clamps the width to the file count, so a
+ * one-file corpus makes `X_TEST_SHARD_FAILED`'s own `fix:` say `--workers 1`.
+ */
+export const readWorkers = (args: ParsedArgs): number | undefined =>
   readIntFlag(args, {
     name: 'workers',
     command: 'verify',
-    min: 1,
+    min: WORKER_FLOOR,
+    max: WORKER_CEILING,
     example: 'x verify --workers 4',
   });
 

package/src/command.ts

@@ -20,14 +20,22 @@ export interface CliCommand {
   run(ctx: CommandContext): Promise<CommandResult>;
 }
 
+/**
+ * `ok` is written AFTER the spread in both helpers, and that order is the whole contract: the
+ * function's NAME is the verdict, and `extra` may carry every other field. Spread last, a caller
+ * passing `{ ok: true }` to `failed()` got a result `exitCodeFor` exits 0 on while its own summary
+ * says it failed — a green CI over a red command. `command` and `summary` stay before the spread
+ * on purpose: those are arguments a caller may legitimately refine, and only the verdict is the
+ * helper's to keep.
+ */
 export const ok = (
   command: string,
   summary: string,
   extra: Partial<CommandResult> = {},
-): CommandResult => ({ ok: true, command, summary, ...extra });
+): CommandResult => ({ command, summary, ...extra, ok: true });
 
 export const failed = (
   command: string,
   summary: string,
   extra: Partial<CommandResult> = {},
-): CommandResult => ({ ok: false, command, summary, ...extra });
+): CommandResult => ({ command, summary, ...extra, ok: false });

package/src/db-branch.ts

@@ -48,6 +48,24 @@ export function isBranchName(value: string): boolean {
   }
 }
 
+/**
+ * The database a connection URL names. `url.split('/').at(-1)` took the query string with it, so
+ * a refusal built from it named `postly?sslmode=require_branch_x` — a database that does not exist
+ * — in a message whose whole point is that a reader can check it. `pathname` is the one part that
+ * IS the database, and it arrives percent-encoded, which `pg_database` does not.
+ *
+ * Falls back rather than throwing: the caller is already reporting a failure, and a second throw
+ * from the reporter replaces a checkable refusal with a stack trace.
+ */
+export function databaseNameOf(url: string, fallback = 'postgres'): string {
+  try {
+    const name = decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+    return name === '' ? fallback : name;
+  } catch {
+    return fallback;
+  }
+}
+
 /** Where a branch's app answers once something serves it — the preview half of the design. */
 export const previewUrl = (branch: string, port: number): string =>
   `http://${branch}.localhost:${port}`;

package/src/db-generate.ts

@@ -14,7 +14,7 @@ import {
 } from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
 import { loadApp } from './app-load';
-import { writeSchemaHash } from './drift';
+import { reconcileSchemaHash, writeSchemaHash } from './drift';
 import { hashFileName, MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
 import type { Finding } from './output';
 
@@ -24,11 +24,20 @@ export interface GenerateMigrationOptions {
   readonly allowDestructive?: boolean | undefined;
 }
 
+/**
+ * What this run actually did — four different things, and `--json` has to tell them apart. A
+ * `hash-recorded` run wrote a file and generated no migration; reporting it as `generated` would
+ * claim a migration nobody can apply, and reporting it as `unchanged` would hide the one write.
+ */
+export type GenerateOutcome = 'generated' | 'hash-recorded' | 'unchanged' | 'blocked';
+
 export interface GeneratedFiles {
-  /** Absent when the entities and the migrations already agree — nothing was written. */
+  readonly outcome: GenerateOutcome;
+  /** Absent unless `outcome` is `generated` — the other three write no migration. */
   readonly migration?: GeneratedMigration | undefined;
   /** App-root-relative paths written, in write order. Empty when there was nothing to write. */
   readonly files: readonly string[];
+  /** What the source hashes to, whenever this run was in a position to record it. */
   readonly schemaHash?: string | undefined;
   /** Modules that would not load. Non-empty means nothing was generated. */
   readonly findings: readonly Finding[];
@@ -72,7 +81,7 @@ export async function generateAppMigration(
   options: GenerateMigrationOptions,
 ): Promise<GeneratedFiles> {
   const app = await loadApp(root);
-  if (app.findings.length > 0) return { files: [], findings: app.findings };
+  if (app.findings.length > 0) return { outcome: 'blocked', files: [], findings: app.findings };
 
   const migrations = await readMigrations(root);
   const current = declaredSchema(migrations);
@@ -90,9 +99,31 @@ export async function generateAppMigration(
     name: options.name,
     ...(options.allowDestructive === true ? { allowDestructive: true } : {}),
   });
-  // An empty diff writes nothing. A migration with no statement still takes a ledger row, a
-  // checksum and a place in the apply order — a permanent record that nothing changed.
-  if (migration.up.trim().length === 0) return { files: [], findings: [] };
+  // An empty diff writes no MIGRATION — one with no statement still takes a ledger row, a checksum
+  // and a place in the apply order, a permanent record that nothing changed. It re-records the
+  // sidecar instead, and that is what makes `X_DB_DRIFT`'s `fix:` a real instruction: the hash
+  // covers every non-test file under `packages/db/src`, so editing a seed or a helper moves it with
+  // no DDL behind it, and the command the error names used to write nothing at all.
+  //
+  // Nothing is masked, because of what has already been proved above: `loadApp` reported no
+  // findings, so the registry is whole rather than short; `declaredSchema` returned a real snapshot
+  // rather than `undefined`, so the diff had something to run against; and the emptiness is the
+  // generator's OWN verdict — the same call, the same classifier — as the written path. A DDL
+  // change that reaches here is a `generateMigration` that missed it, and the sidecar was never the
+  // thing that caught that: an author following the fix simply stayed red with nothing left to run.
+  if (migration.up.trim().length === 0) {
+    const newest = migrations[migrations.length - 1];
+    // No migration to record against, which in this branch means no entity is declared either —
+    // a registry against zero migrations is `create table` for all of it, never an empty diff.
+    if (newest === undefined) return { outcome: 'unchanged', files: [], findings: [] };
+    const reconciled = await reconcileSchemaHash(root, newest.id);
+    return {
+      outcome: reconciled.written ? 'hash-recorded' : 'unchanged',
+      schemaHash: reconciled.hash,
+      files: reconciled.written ? [`${MIGRATIONS_DIR}/${hashFileName(newest.id)}`] : [],
+      findings: [],
+    };
+  }
 
   const dir = join(root, MIGRATIONS_DIR);
   const sql = `${migration.id}.sql`;
@@ -104,6 +135,7 @@ export async function generateAppMigration(
   const schemaHash = await writeSchemaHash(root, migration.id);
 
   return {
+    outcome: 'generated',
     migration,
     schemaHash,
     files: [sql, snapshot, hashFileName(migration.id)].map((file) => `${MIGRATIONS_DIR}/${file}`),