@ultimat3/cli 2.0.0 → 4.0.0

package/src/cmd-deploy.ts

@@ -2,11 +2,10 @@
 // not know the name of a cloud, a KV store or an edge runtime (axiom 7). What it emits is a plan
 // anything that runs containers can execute.
 
-import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, CliNotImplementedError } from './errors';
+import { BadFlagError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
 import { flagBool, flagString } from './parse';
@@ -28,11 +27,35 @@ import { flagBool, flagString } from './parse';
  * the serving roles were asked to start and not after they are ready. The barrier that makes
  * "after" true is declarative and belongs to the compose file, not to this plan: the `backfill`
  * service needs `depends_on: { web: { condition: service_healthy } }`, which `docker compose run`
- * honours. Both compose definitions — `docker/docker-compose.prod.yml` and the one
- * `templates/scaffold-container.ts` scaffolds — still owe that service and that condition.
+ * honours. Both compose definitions carry it — `docker/docker-compose.prod.yml`'s `backfill` and
+ * the one `templates/scaffold-container.ts` scaffolds, which also gates on `migrate` completing.
+ * This paragraph said they "still owe" both for as long as they have had them.
  */
 export const DEPLOY_ROLES = ['migrate', 'web', 'sync', 'worker', 'scheduler', 'backfill'] as const;
 
+/** The two ways to run the plan. Closed, and read three ways: the default, the check, the refusal. */
+export const DEPLOY_METHODS = ['compose', 'helm'] as const;
+
+export type DeployMethod = (typeof DEPLOY_METHODS)[number];
+
+/**
+ * Refused, never defaulted. `=== 'helm' ? 'helm' : 'compose'` made every other spelling a Compose
+ * deploy that reported `ok: true` and `method: "compose"` — so `x deploy --method helmm` (or
+ * `Helm`, or `kubectl`) ran the six-step Compose plan against a cluster whose operator had asked
+ * for a Helm upgrade, and the report agreed with the plan rather than with the request.
+ * `cmd-build.ts`'s `readTarget` is the same shape for the same reason.
+ */
+export function readMethod(raw: string | undefined): DeployMethod {
+  const methods: readonly string[] = DEPLOY_METHODS;
+  if (raw === undefined) return 'compose';
+  if (methods.includes(raw)) return raw as DeployMethod;
+  throw new UnknownCommandError({
+    path: `deploy --method ${raw}`,
+    known: DEPLOY_METHODS,
+    suggestion: 'deploy --method compose',
+  });
+}
+
 /** The roles that run to completion and exit, as against the ones that stay up serving. */
 const ONE_SHOT_ROLES: readonly string[] = ['migrate', 'backfill'];
 
@@ -62,7 +85,7 @@ export function helmImageOverrides(image: string): readonly string[] {
     : ['--set', `image.repository=${repository}`, '--set', `image.tag=${tag}`];
 }
 
-export function planDeploy(image: string, method: 'compose' | 'helm', root: string): DeployPlan {
+export function planDeploy(image: string, method: DeployMethod, root: string): DeployPlan {
   if (method === 'helm') {
     // `repo@sha256:…` is a reference this chart cannot express: it renders `repository:tag` and
     // has no digest branch, so passing one through would deploy `repo@sha256:…:<appVersion>` —
@@ -119,24 +142,29 @@ export const deployCommand: CliCommand = {
       { name: 'image', type: 'string', summary: 'image reference to deploy' },
       { name: 'method', type: 'string', summary: 'compose | helm', default: 'compose' },
       { name: 'dry-run', type: 'boolean', summary: 'print the plan, run nothing' },
-      { name: 'critical', type: 'boolean', summary: 'security deploy: forces clients to reload' },
+      // `--critical` was here and is gone. It parsed, it was echoed into the plan JSON as
+      // `critical: <bool>`, and no file in `packages/` read that field — so the flag changed
+      // nothing about what `x deploy` did, on either method. `flag-reads.ts`'s
+      // `X_CLI_FLAG_UNREAD` passed it, because that gate proves a flag is READ and this one was:
+      // into a field with no reader. Forcing a reload is `@ultimat3/pwa`'s
+      // `updateSignal({ reason: 'security' })`, which has no runtime caller either; a flag that
+      // triggers it is a change in that package, and this was not it.
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('deploy', ctx.cwd).dir;
     const image = flagString(ctx.args, 'image') ?? 'ultimate-app:dev';
-    const method = flagString(ctx.args, 'method') === 'helm' ? 'helm' : 'compose';
-    if (method === 'helm' && !existsSync(join(root, 'docker', 'helm'))) {
-      throw new CliNotImplementedError({
-        feature: 'helm deploy without docker/helm in the app',
-        fix: 'copy docker/helm from the framework repo, or use: x deploy --method compose',
-      });
-    }
+    // No "is there a chart?" branch. It threw X_NOT_IMPLEMENTED — "this build does not implement
+    // helm" — over a build that implements it completely (`planDeploy` above); what was missing was
+    // a FILE, and its fix said to copy it from the framework repository, which `packages/cli`'s
+    // `files:` ships in no tarball. `x new` writes `docker/helm` now, the way it has always written
+    // `docker/docker-compose.prod.yml`. An app that deleted the chart gets helm's own error through
+    // X_DEPLOY_FAILED, whose fix is the exact command to rerun.
+    const method = readMethod(flagString(ctx.args, 'method'));
     const plan = planDeploy(image, method, root);
     const planJson: JsonValue = {
       image: plan.image,
       method,
-      critical: flagBool(ctx.args, 'critical'),
       steps: plan.steps.map((step) => ({ role: step.role, command: step.command.join(' ') })),
     };
     if (flagBool(ctx.args, 'dry-run')) {

package/src/cmd-dev.ts

@@ -42,6 +42,7 @@ import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagString } from './parse';
+import { metricsPortFor } from './serve';
 import { loopFacts, loopFinding, loopNotice } from './statement-loop';
 
 const DEFAULT_PORT = 3000;
@@ -185,6 +186,10 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   const running = await startRoles({
     roles: options.roles ?? DEV_ROLES,
     port: options.port,
+    // `serve.ts`'s expression, called rather than restated: `METRICS_PORT` was read in the
+    // container and ignored here, so the scrape port an operator moved was the one port `x dev`
+    // could not move — and the second `x dev` on a box died binding the hardcoded 9090.
+    metricsPort: metricsPortFor(options.env, options.port),
     buildId,
     runtime,
     routes,
@@ -266,14 +271,16 @@ export const devCommand: CliCommand = {
   spec: {
     name: 'dev',
     summary: 'all roles in one process: embedded services, sub-second reload, /_x mounted',
-    usage: 'x dev [--port 3000] [--role web,worker] [--json]',
+    usage: 'x dev [--port 3000] [--role web,worker] [--once] [--json]',
     requiresApp: true,
     flags: [
       { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
       {
         name: 'role',
         type: 'string',
-        summary: `roles to run (default: all of ${DEV_ROLES.join(',')})`,
+        // `replicator` is named because it is selectable and NOT default — it takes a replication
+        // slot on a shared database, which is not something every `x dev` should do by starting.
+        summary: `roles to run (default: all of ${DEV_ROLES.join(',')}; replicator is opt-in)`,
       },
       { name: 'once', type: 'boolean', summary: 'boot, report, exit — for smoke tests and CI' },
     ],

package/src/cmd-docs.ts

@@ -9,8 +9,10 @@ import { nearestTopics, scanInstalledDocs, searchDocs } from '@ultimat3/manifest
 import type { CliCommand, CommandContext } from './command';
 import { MissingPositionalError } from './errors';
 import { frameworkScopeDir } from './framework-scope';
+import { parseLimitFlag } from './jobs-report';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
+import { flagString } from './parse';
 
 /** Matches printed by default. Enough to choose between, few enough to read all of. */
 const DEFAULT_LIMIT = 5;
@@ -150,9 +152,11 @@ export const docsCommand: CliCommand = {
     }
 
     const entries = await scanInstalledDocs(scope);
-    const rawLimit = ctx.args.flags.get('limit');
-    const parsed = typeof rawLimit === 'string' ? Number.parseInt(rawLimit, 10) : Number.NaN;
-    const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_LIMIT;
+    // `x jobs ls --limit`'s reader, and its `command` parameter exists for exactly this second
+    // caller. A local `Number.parseInt` accepted `--limit 1e9` as 1 and answered with one match,
+    // and fell silently through to the default for `abc`, `0` and `-3` — a bound other than the one
+    // typed, from the same binary that refuses all four one command over.
+    const limit = parseLimitFlag(flagString(ctx.args, 'limit'), 'docs') ?? DEFAULT_LIMIT;
     const hits = searchDocs(entries, query, limit);
     if (hits.length === 0) return missResult(query, entries);
 

package/src/cmd-doctor.ts

@@ -11,9 +11,10 @@ import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
 import { ICON_SOURCE } from './dev-assets';
 import { checkSourceDrift } from './drift';
-import { intFlagOr, PORT_RANGE } from './flag-number';
+import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
+import type { ParsedArgs } from './parse';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -126,7 +127,7 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       finding(
         'X_PORT_IN_USE',
         `port ${probe.port} is already listening`,
-        `x dev --port ${probe.port + 1}`,
+        `x dev --port ${neighbouringPort(probe.port)}`,
       ),
     );
   }
@@ -165,6 +166,18 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   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.
+ */
+export const doctorPort = (args: ParsedArgs): number =>
+  intFlagOr(
+    args,
+    { name: 'port', command: 'doctor', ...PORT_RANGE, min: 1, example: 'x doctor --port 3000' },
+    DEFAULT_DOCTOR_PORT,
+  );
+
 const portFree = async (port: number): Promise<boolean> => {
   try {
     const server = Bun.serve({ port, fetch: () => new Response('') });
@@ -213,11 +226,7 @@ export const doctorCommand: CliCommand = {
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const port = intFlagOr(
-      ctx.args,
-      { name: 'port', command: 'doctor', ...PORT_RANGE, example: 'x doctor --port 3000' },
-      DEFAULT_DOCTOR_PORT,
-    );
+    const port = doctorPort(ctx.args);
     const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
     return {
       ok: findings.length === 0,

package/src/cmd-fix.ts

@@ -8,7 +8,7 @@ import { requireAppRoot } from './app-root';
 import type { BoundaryCut } from './boundary-cuts';
 import { planBoundaryCuts } from './boundary-cuts';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, FixTargetUnknownError } from './errors';
+import { BadFlagError, FixTargetUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { nearest } from './parse';
@@ -103,10 +103,22 @@ export const fixCommand: CliCommand = {
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('fix', ctx.cwd).dir;
+    // Refused before the scan, never defaulted to `''`: an empty string reached `resolveTarget` as
+    // a file NAME, so a bare `x fix` answered X_FIX_TARGET_UNKNOWN with `"" is not one of the 42
+    // source file(s)…` — and `nearest('')` almost never suggests anything, so the fix degraded to
+    // `x routes --json` for a caller who had simply not said which file.
+    const file = ctx.args.positionals[0];
+    if (file === undefined) {
+      throw new MissingPositionalError({
+        command: 'fix boundary',
+        positional: 'file',
+        example: 'x routes --json   # every registered route file, app-root-relative',
+      });
+    }
     const files = await readAppSources(root);
     const target = resolveTarget(
-      ctx.args.positionals[0] ?? '',
-      files.map((file) => file.path),
+      file,
+      files.map((source) => source.path),
     );
     const cuts = planBoundaryCuts(target, appImportGraph(files));
 

package/src/cmd-generate.ts

@@ -286,7 +286,12 @@ type WritePlan =
   | { readonly kind: 'skip' }
   | { readonly kind: 'conflict'; readonly finding: Finding };
 
-function planFile(file: GeneratedFile, absolute: string, force: boolean): WritePlan {
+function planFile(
+  file: GeneratedFile,
+  absolute: string,
+  force: boolean,
+  invocation: string,
+): WritePlan {
   // A foundation file belongs to the slice, not to the generator that needs it: several generators
   // emit the same `repo.ts`, so an existing one is the author's — never a conflict, and never
   // overwritten, `--force` included. `--force` is about the primitive the author named; clobbering
@@ -303,7 +308,10 @@ function planFile(file: GeneratedFile, absolute: string, force: boolean): WriteP
       finding: {
         code: 'X_GENERATE_CONFLICT',
         cause: `${file.path} already exists`,
-        fix: `x g --force to overwrite, or pass a different name`,
+        // The caller's own invocation, not `x g <kind>`: `x g --force` is X_CLI_UNKNOWN_COMMAND
+        // when run, and a `fix:` is copied and pasted verbatim. Same construction as
+        // `generate-kinds.ts`'s `assertSurfaceSupported`.
+        fix: `${invocation} --force   # overwrites ${file.path}, or pass a different name`,
         docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
         at: file.path,
       },
@@ -325,12 +333,20 @@ export async function writeFiles(
   root: string,
   files: readonly GeneratedFile[],
   force: boolean,
+  /**
+   * The command line that produced these files, so a conflict's `fix:` can hand it back with
+   * `--force` on the end. Optional for a caller assembling files itself; the fallback is the
+   * shape, not a runnable line, and every generator path supplies the real one.
+   */
+  invocation = 'x g <kind> <name>',
 ): Promise<WriteReport> {
   const plans: WritePlan[] = [];
   for (const file of files) {
     const absolute = containedPath(root, file.path);
     plans.push(
-      file.merge === 'json' ? await planJsonMerge(file, absolute) : planFile(file, absolute, force),
+      file.merge === 'json'
+        ? await planJsonMerge(file, absolute)
+        : planFile(file, absolute, force, invocation),
     );
   }
   const conflicts = plans.flatMap((plan) => (plan.kind === 'conflict' ? [plan.finding] : []));
@@ -381,6 +397,10 @@ export const generateCommand: CliCommand = {
     // drifted — it omitted `backfill` — and a usage line that can disagree with the list it
     // describes is exactly the second source of truth axiom 2 forbids.
     usage: `x g ${GENERATORS.join('|')} <name> [--feature f]`,
+    // Declared from the SAME constant `readKind` validates against: without it `fix-command.ts`
+    // has no set to judge the word after `x g`, and two shipped `@ultimat3/admin` fix lines said
+    // `x g migration` — a generator that has never existed — straight through the `errors` gate.
+    positionalChoices: GENERATORS,
     requiresApp: true,
     flags: [
       { name: 'feature', type: 'string', summary: 'feature slice to write into' },
@@ -425,7 +445,12 @@ export const generateCommand: CliCommand = {
         lines: files.map((file) => msg('cli.file.added', { path: file.path })),
       };
     }
-    const report = await writeFiles(root, files, flagBool(ctx.args, 'force'));
+    const report = await writeFiles(
+      root,
+      files,
+      flagBool(ctx.args, 'force'),
+      `x g ${kind} ${name}`,
+    );
     // 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.

package/src/cmd-help.ts

@@ -14,10 +14,31 @@ const flagLine = (flag: FlagSpec): string => {
   return `  ${short}${name.padEnd(24)} ${flag.summary}`;
 };
 
+/**
+ * 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.
+ */
+const specFor = (
+  specs: readonly CommandSpec[],
+  topic: string | undefined,
+): CommandSpec | undefined =>
+  topic === undefined
+    ? undefined
+    : specs.find((entry) => entry.name === topic || (entry.aliases ?? []).includes(topic));
+
+/** What `--json` reports: the one resolved command, or — as the human render does — all of them. */
+export function helpTopic(
+  specs: readonly CommandSpec[],
+  topic: string | undefined,
+): readonly CommandSpec[] {
+  const spec = specFor(specs, topic);
+  return spec === undefined ? specs : [spec];
+}
+
 export function renderHelp(specs: readonly CommandSpec[], topic: string | undefined): string[] {
-  const spec = specs.find(
-    (entry) => entry.name === topic || (entry.aliases ?? []).includes(topic ?? ''),
-  );
+  const spec = specFor(specs, topic);
   if (spec === undefined) {
     // `cli.hint.help` is deliberately absent from this list: it is the command's own `summary`, and
     // `renderHuman` prints every line and THEN the summary — so the catalogue ended with the same
@@ -77,7 +98,7 @@ export function createHelpCommand(specs: () => readonly CommandSpec[]): CliComma
         command: 'help',
         summary: msg('cli.hint.help'),
         lines: renderHelp(all, topic),
-        data: topic === undefined ? catalogue(all) : catalogue(all.filter((s) => s.name === topic)),
+        data: catalogue(helpTopic(all, topic)),
       };
     },
   };

package/src/cmd-i18n.ts

@@ -12,7 +12,7 @@ import { catalogKeys, catalogMissingKeys } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, CatalogExistsError } from './errors';
+import { BadFlagError, CatalogExistsError, MissingPositionalError } from './errors';
 import {
   auditApp,
   loadCatalogs,
@@ -64,10 +64,13 @@ async function writeNewCatalog(absolute: string, locale: string, contents: strin
 function requireLocalePositional(ctx: CommandContext, sub: string): string {
   const raw = ctx.args.positionals[0];
   if (raw === undefined) {
-    throw new BadFlagError({
-      flag: 'locale',
-      command: 'i18n',
-      reason: `"x i18n ${sub}" needs a locale: x i18n ${sub} <locale>`,
+    // The locale is a positional. `--locale on "x i18n"` is the cause a MALFORMED one takes, from
+    // the shared validator below — and there the flag name is what `resolveLocales` was told to
+    // report; here there is no value at all, and naming a flag sends the retry to a flag loop.
+    throw new MissingPositionalError({
+      command: `i18n ${sub}`,
+      positional: 'locale',
+      example: `x i18n ${sub} es`,
     });
   }
   return raw;

package/src/cmd-jobs.ts

@@ -8,7 +8,7 @@ import type { JobDriver } from '@ultimat3/jobs';
 import { cancelJob, createMemoryDriver, createNatsDriver, createRedisDriver } from '@ultimat3/jobs';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, JobUnknownError } from './errors';
+import { BadFlagError, JobUnknownError, MissingPositionalError } from './errors';
 import { drainJobs } from './jobs-drain';
 import { withJobDriver } from './jobs-driver';
 import {
@@ -33,10 +33,11 @@ const DRAIN_TARGETS = ['memory', 'redis', 'nats'] as const;
 function requireIdPositional(ctx: CommandContext, sub: string): string {
   const id = ctx.args.positionals[0];
   if (id === undefined) {
-    throw new BadFlagError({
-      flag: 'id',
-      command: 'jobs',
-      reason: `"x jobs ${sub}" needs a job id: x jobs ${sub} <id>`,
+    // `--id on "x jobs"` is a flag `x jobs` does not declare; the id is a positional and says so.
+    throw new MissingPositionalError({
+      command: `jobs ${sub}`,
+      positional: 'id',
+      example: 'x jobs ls --json',
     });
   }
   return id;

package/src/cmd-mcp.ts

@@ -8,6 +8,7 @@ import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
+import { intFlagOr, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { CliMcpServer } from './mcp-host';
 import { createDevMcpServer, DEV_TOOL_SCOPES } from './mcp-host';
@@ -128,19 +129,22 @@ async function serveOverStdio(host: CliMcpServer): Promise<CommandResult> {
   };
 }
 
-function readPort(ctx: CommandContext): number {
-  const raw = flagString(ctx.args, 'port') ?? String(DEFAULT_PORT);
-  const port = Number.parseInt(raw, 10);
-  if (!Number.isInteger(port) || port < 0 || port > 65535) {
-    throw new BadFlagError({
-      flag: 'port',
+/**
+ * `flag-number.ts`'s reader, never a bare `Number.parseInt`: the range check alone accepted every
+ * prefix parse, so `--port 1e5` bound port 1 and `--port 0x10` bound 0 — a socket at an address the
+ * operator did not type, on the transport whose whole output is the url it is reachable at.
+ */
+const readPort = (ctx: CommandContext): number =>
+  intFlagOr(
+    ctx.args,
+    {
+      name: 'port',
       command: 'mcp serve',
-      reason: `expects a port in 0..65535, got "${raw}"`,
-      fix: `x mcp serve --transport http --port ${DEFAULT_PORT}`,
-    });
-  }
-  return port;
-}
+      ...PORT_RANGE,
+      example: `x mcp serve --transport http --port ${DEFAULT_PORT}`,
+    },
+    DEFAULT_PORT,
+  );
 
 export const mcpCommand: CliCommand = {
   spec: {

package/src/cmd-new.ts

@@ -7,6 +7,7 @@ import { chmod } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
 import { dedupe } from './cmd-generate';
 import type { CliCommand, CommandContext } from './command';
+import { MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
@@ -25,7 +26,7 @@ export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
   const app = names(options.name);
   const files: GeneratedFile[] = [
     ...repoFiles(app, loadVersion(), options.example),
-    ...appFiles(app),
+    ...appFiles(app, options.example),
   ];
   if (options.example) {
     files.push(...resourceFiles('post', { surfaceDir: 'apps/web/app', feature: 'post' }));
@@ -67,7 +68,7 @@ export const newCommand: CliCommand = {
   spec: {
     name: 'new',
     summary: 'scaffold a new Ultimate monorepo that already runs',
-    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--json]',
+    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--force] [--json]',
     flags: [
       { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
       {
@@ -82,20 +83,15 @@ export const newCommand: CliCommand = {
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const raw = ctx.args.positionals[0];
+    // The class, not a hand-built finding with the same code: `MissingPositionalError` is what
+    // names the missing POSITIONAL, and a finding assembled here is a second, unenforced copy of
+    // a cause the class already writes — one that said "x new needs a name" and not what a name is.
     if (raw === undefined) {
-      return {
-        ok: false,
+      throw new MissingPositionalError({
         command: 'new',
-        summary: msg('cli.usage'),
-        findings: [
-          {
-            code: 'X_CLI_BAD_FLAG',
-            cause: 'x new needs a name',
-            fix: 'x new myapp',
-            docs: 'https://ultimate.dev/errors/X_CLI_BAD_FLAG',
-          },
-        ],
-      };
+        positional: 'name',
+        example: 'x new myapp',
+      });
     }
     const app = names(raw);
     const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);

package/src/cmd-planned.ts

@@ -91,6 +91,19 @@ export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
   },
 ];
 
+/**
+ * The planned command a resolved command NAME belongs to, if any. Exported for `dispatch.ts`'s
+ * parse-failure branch: the parser refuses an undeclared flag before any `run` is reached, and a
+ * planned command declares only the four global flags — so `x logs tail --follow` answered
+ * X_CLI_BAD_FLAG listing "known: json, help, cwd, verbose", a flag set belonging to a command that
+ * does not exist yet, while `x logs tail` answered the honest X_NOT_IMPLEMENTED one invocation away.
+ *
+ * Takes the name `commandFor` resolved, never the raw word: aliases are that function's business
+ * and a second matcher here would be a second answer to "which command did they type".
+ */
+export const plannedCommandFor = (name: string | undefined): PlannedCommand | undefined =>
+  PLANNED_COMMANDS.find((planned) => planned.name === name);
+
 export interface PlannedSubcommand {
   readonly command: string;
   readonly subcommand: string;

package/src/cmd-policy.ts

@@ -5,7 +5,7 @@
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, DeclarationUnknownError } from './errors';
+import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { nearest } from './parse';
@@ -74,11 +74,13 @@ function declarationLines(declaration: DeclarationExplanation): readonly string[
 function requireSubject(ctx: CommandContext): string {
   const name = ctx.args.positionals[0];
   if (name === undefined) {
-    throw new BadFlagError({
-      flag: 'subject',
-      command: 'policy',
-      reason: 'x policy explain <subject> needs a permission, action, query or route path',
-      fix: 'x policy list --json',
+    // Never `BadFlagError`: its cause read `--subject on "x policy"`, and the next thing an agent
+    // typed was `x policy explain --subject posts:read`, which is a second X_CLI_BAD_FLAG for a
+    // flag this command does not declare. The positional is what is missing, so it is what is named.
+    throw new MissingPositionalError({
+      command: 'policy explain',
+      positional: 'subject',
+      example: 'x policy list --json',
     });
   }
   return name;

package/src/cmd-registries.ts

@@ -13,7 +13,7 @@ import { describeQueries, getQuery } from '@ultimat3/query';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { BadFlagError, DeclarationUnknownError } from './errors';
+import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import type { CommandSpec } from './parse';
@@ -143,11 +143,12 @@ function describeResult<D extends { readonly name: string }, Raw extends { descr
 ): CommandResult {
   const name = ctx.args.positionals[0];
   if (name === undefined) {
-    throw new BadFlagError({
-      flag: 'name',
-      command: kind.kind,
-      reason: `x ${kind.kind} describe <name> needs a name`,
-      fix: `x ${kind.kind} list --json`,
+    // A positional, so `MissingPositionalError` — `--name on "x actions"` named a flag no registry
+    // command declares, and reading it as one is a second refusal for the first one's advice.
+    throw new MissingPositionalError({
+      command: `${kind.kind} describe`,
+      positional: 'name',
+      example: `x ${kind.kind} list --json`,
     });
   }
   const raw = kind.find(name);