@ultimat3/cli 7.0.0 → 8.0.0

package/src/cmd-new.ts

@@ -5,9 +5,11 @@
 import { existsSync } from 'node:fs';
 import { chmod } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
+import { renderThrowable } from '@ultimat3/core';
 import { dedupe } from './cmd-generate';
 import type { CliCommand, CommandContext } from './command';
 import { MissingPositionalError } from './errors';
+import type { Runner } from './exec';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagBool, flagString } from './parse';
@@ -21,6 +23,70 @@ export interface NewAppOptions {
   readonly example: boolean;
 }
 
+/** `--no-git`'s `problem`, matched rather than re-spelled where the report decides on a line. */
+export const SKIPPED = 'skipped by --no-git';
+
+/**
+ * What `git init && git add -A && git commit` did, reported on `data.git` either way.
+ *
+ * A type alias and not an `interface`, because it IS `CommandResult.data`: an interface has no
+ * implicit index signature, so it is not assignable to `JsonValue` and the `--json` contract would
+ * not compile (TS2322).
+ */
+export type RepositoryInit = {
+  readonly initialized: boolean;
+  readonly committed: boolean;
+  /**
+   * Why not — `null` when both halves ran. Required rather than optional, so `data.git` has one
+   * shape for a machine reading `--json`: a key that appears only on failure is a key every
+   * consumer has to guess at. Never a raw thrown value; `renderThrowable` writes it.
+   */
+  readonly problem: string | null;
+};
+
+/**
+ * Plain `git init`, with no `--initial-branch`: that flag is git 2.28+, and a scaffold that failed
+ * on an older git would trade a working tree for a branch name. The repository takes whatever
+ * `init.defaultBranch` this machine already agreed on.
+ */
+const GIT_STEPS: readonly (readonly string[])[] = [
+  ['git', 'init'],
+  ['git', 'add', '-A'],
+  ['git', 'commit', '-m', 'x new'],
+];
+
+/** What `--no-git` records, so `data.git` has the same shape whichever way the flag went. */
+const NO_GIT: RepositoryInit = { initialized: false, committed: false, problem: SKIPPED };
+
+/**
+ * A scaffold is a REPOSITORY, because three surfaces of this CLI already assume one and answered
+ * `not a git repository` in a fresh app: `x affected`, `x ci` and `x pr`. It was four —
+ * `X_ROUTE_FILE_INVALID`'s `fix:` was a `git mv` that exits 128 with no `.git` to run in, and that
+ * one is now a plain `mv -n` (`packages/render/src/registry.ts`) rather than a reason to init.
+ *
+ * It never fails `x new`. The command's job is the tree, that tree is on disk by the time this
+ * runs, and a box with no `git` or no configured `user.email` would otherwise get an app it cannot
+ * see — so the outcome is DATA, and a failure is one line naming the commands to run by hand.
+ */
+export async function initRepository(runner: Runner, dir: string): Promise<RepositoryInit> {
+  let initialized = false;
+  for (const command of GIT_STEPS) {
+    try {
+      const result = await runner(command, { cwd: dir });
+      if (!result.ok) {
+        const detail = (result.stderr.trim() || result.stdout.trim()).split('\n')[0] ?? '';
+        return { initialized, committed: false, problem: `${command.join(' ')}: ${detail}` };
+      }
+    } catch (error) {
+      // The thrown value is genuinely unknown — `exec` refuses a missing program by throwing —
+      // and core's renderer is the one spelling that cannot itself throw on a hostile `toString`.
+      return { initialized, committed: false, problem: renderThrowable(error) };
+    }
+    initialized = true;
+  }
+  return { initialized: true, committed: true, problem: null };
+}
+
 /** Pure: the complete file list for a new app, so `--dry-run` and the test see the same thing. */
 export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
   const app = names(options.name);
@@ -68,13 +134,25 @@ 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] [--force] [--json]',
+    // Every flag the table below declares, in the spelling that turns it off where the default is
+    // on: the usage line offered `--no-example` while the table listed `--example`, and a reader
+    // had to reconcile the two to answer "which one do I get if I type neither".
+    usage: 'x new <name> [--dir path] [--no-example] [--no-git] [--dry-run] [--force] [--json]',
     flags: [
       { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
       {
+        // The summary carries the default and the negation because the page has to answer "which
+        // one do I get if I type neither": the usage line offered `--no-example`, this table said
+        // `--example`, and `default: true` is a field only `--json` renders. 134 files against 107.
         name: 'example',
         type: 'boolean',
-        summary: 'include the example feature slice',
+        summary: 'include the example feature slice (default: on; --no-example for an empty app/)',
+        default: true,
+      },
+      {
+        name: 'git',
+        type: 'boolean',
+        summary: 'git init and commit the scaffold (default: on; --no-git for a bare directory)',
         default: true,
       },
       { name: 'dry-run', type: 'boolean', summary: 'print the file list, write nothing' },
@@ -124,12 +202,21 @@ export const newCommand: CliCommand = {
       };
     }
     const written = await writeNewApp(target, options);
+    const git =
+      ctx.args.flags.get('git') === false ? NO_GIT : await initRepository(ctx.runner, target);
+    const lines = [msg('cli.new.wrote', { count: written.files.length, dir: target })];
+    if (git.problem !== null && git.problem !== SKIPPED) {
+      lines.push(msg('cli.new.noRepository', { problem: git.problem }));
+      // Raw, unlike the two prose lines around it: this one is an instruction to run verbatim, and
+      // a translated command is a broken one (`packages/cli/CLAUDE.md`).
+      lines.push(`  run: cd ${target} && git init && git add -A && git commit -m 'x new'`);
+    }
     return {
       ok: true,
       command: 'new',
       summary: msg('cli.new.done', { name: app.kebab }),
-      data: { dir: written.dir, files: written.files },
-      lines: [`  ${written.files.length} files in ${target}`],
+      data: { dir: written.dir, files: written.files, git },
+      lines,
     };
   },
 };

package/src/cmd-policy.ts

@@ -2,13 +2,14 @@
 // only: the fact-gathering (registries, matrix rows) lives in `policy-facts.ts`, so the matrix
 // logic is testable without an app — same split as `cmd-jobs.ts` / `jobs-report.ts`.
 
+import { nearestName } from '@ultimat3/core';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
-import { nearest } from './parse';
+
 import type { DeclarationExplanation } from './policy-facts';
 import { explainPolicy, knownPolicySubjects, listPolicy } from './policy-facts';
 import { renderTable } from './table';
@@ -91,7 +92,7 @@ function runExplain(ctx: CommandContext, findings: readonly Finding[]): CommandR
   const explanation = explainPolicy(name);
   if (explanation === undefined) {
     const known = knownPolicySubjects();
-    const suggestion = nearest(name, known);
+    const suggestion = nearestName(name, known);
     throw new DeclarationUnknownError(
       suggestion === undefined
         ? { kind: 'policy', singular: 'policy subject', name, known, verb: 'explain' }

package/src/cmd-pr.ts

@@ -60,9 +60,27 @@ export const prCommand: CliCommand = {
     flags: [
       { name: 'repo', type: 'string', summary: 'owner/name; the checkout own remote by default' },
       { name: 'pr', type: 'string', summary: 'pull request number; this branch own by default' },
-      { name: 'all', type: 'boolean', summary: 'review: resolved threads too, not just open ones' },
-      { name: 'full', type: 'boolean', summary: 'review: whole comment bodies, never truncated' },
-      { name: 'body', type: 'string', summary: 'reply: the comment text to post in the thread' },
+      // Scoped to the subcommand each summary already names: `resolve` and `reply` WRITE to
+      // somebody else's pull request, and a flag they silently ignore is a flag whose caller
+      // believed it did something to a request that cannot be re-run.
+      {
+        name: 'all',
+        type: 'boolean',
+        summary: 'review: resolved threads too, not just open ones',
+        subcommands: ['review'],
+      },
+      {
+        name: 'full',
+        type: 'boolean',
+        summary: 'review: whole comment bodies, never truncated',
+        subcommands: ['review'],
+      },
+      {
+        name: 'body',
+        type: 'string',
+        summary: 'reply: the comment text to post in the thread',
+        subcommands: ['reply'],
+      },
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -175,7 +193,7 @@ function threadLines(thread: PrThread, bodyLines: number): readonly string[] {
       msg('cli.pr.thread.comment', { author: comment.author, createdAt: comment.createdAt }),
     );
     const clamped = clampBody(comment.body, bodyLines);
-    for (const line of clamped.lines) out.push(`      | ${line}`);
+    out.push(...commentBlock(thread.id, clamped.lines));
     if (clamped.hidden > 0) out.push(msg('cli.pr.body.truncated', { hidden: clamped.hidden }));
   }
   const hidden = thread.commentCount - thread.comments.length;
@@ -183,6 +201,39 @@ function threadLines(thread: PrThread, bodyLines: number): readonly string[] {
   return out;
 }
 
+const BLOCK_OPEN = '<comment id=';
+const BLOCK_CLOSE = '</comment>';
+
+/**
+ * The fence, as a READER would parse it rather than as this file spells it.
+ *
+ * Two literal `replaceAll`s were the whole neutralisation, and markup is not spelled one way:
+ * `</comment >`, `</COMMENT>` and `< comment id=` all end or open a block for anything reading
+ * tags, and none of the three matched. One pattern over `<`, an optional `/`, and whitespace
+ * around a case-insensitive `comment` covers every spelling of the delimiter; the escape goes on
+ * the `<`, so what the reviewer wrote after it survives byte for byte.
+ */
+const BLOCK_DELIMITER = /<(\s*\/?\s*comment\b)/gi;
+
+/**
+ * One comment body, fenced and labelled with the thread id it came from — `@ultimat3/ai`'s
+ * `documentBlock` (`rag.ts`), applied to the other place foreign text enters an agent's context.
+ * `x pr review` exists because an agent cannot read the GitHub web UI, and a review body is
+ * written by anyone who can comment on the pull request: rendered as bare indented text it arrived
+ * in that agent's context indistinguishable from the command's own output, which is prompt
+ * injection with a shell attached.
+ *
+ * The fence is neutralised INSIDE the payload rather than deleted, so every word the reviewer
+ * wrote still reads, and the label is stripped of the three characters that would end the
+ * attribute. Influence only, and deliberately not sold as more: a fence tells a reader this text
+ * is data, and it can never stop one that decides otherwise.
+ */
+export function commentBlock(id: string, lines: readonly string[]): readonly string[] {
+  const label = id.replaceAll('"', "'").replaceAll('>', ')').replaceAll('<', '(');
+  const body = lines.map((line) => line.replace(BLOCK_DELIMITER, '<\\$1'));
+  return [`${BLOCK_OPEN}"${label}">`, ...body, BLOCK_CLOSE];
+}
+
 /**
  * A review body is prose written for a browser: the ones in this repo run to six thousand
  * characters with a shell script embedded in each. Clamped in ONE place, so `--json` carries the

package/src/cmd-registries.ts

@@ -6,6 +6,7 @@
 
 import type { ActionDescriptor, AnyAction } from '@ultimat3/action';
 import { describeActions, getAction, jsonSchemaOf } from '@ultimat3/action';
+import { nearestName } from '@ultimat3/core';
 import type { EntityDescription, RegistryEntry } from '@ultimat3/entity';
 import { describeEntities, getEntity } from '@ultimat3/entity';
 import type { AnyQuery, QueryDescriptor } from '@ultimat3/query';
@@ -17,7 +18,7 @@ import { DeclarationUnknownError, MissingPositionalError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import type { CommandSpec } from './parse';
-import { nearest } from './parse';
+
 import { renderTable } from './table';
 
 /**
@@ -154,7 +155,7 @@ function describeResult<D extends { readonly name: string }, Raw extends { descr
   const raw = kind.find(name);
   if (raw === undefined) {
     const known = kind.list().map((item) => item.name);
-    const suggestion = nearest(name, known);
+    const suggestion = nearestName(name, known);
     throw new DeclarationUnknownError(
       suggestion === undefined
         ? { kind: kind.kind, singular: kind.singular, name, known }

package/src/cmd-shot.ts

@@ -22,7 +22,8 @@ import { intFlagOr, PORT_RANGE } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagBool, flagString } from './parse';
-import type { ShotArtifacts } from './shot-verdict';
+import { SETTLE_POLL_MS, settleIslands } from './shot-settle';
+import type { IslandCount, ShotArtifacts } from './shot-verdict';
 import {
   buildVerdict,
   ISLAND_PROBE,
@@ -62,10 +63,50 @@ const pathOf = (url: string): string => {
   }
 };
 
+/**
+ * A reserved name (RFC 2606) that resolves nowhere, so the origin check below can never be
+ * satisfied by an accident of what the app's own host happens to be.
+ */
+const ROUTE_BASE = 'http://route.invalid';
+
+/**
+ * Where a browser would actually go. The refusal above reads `scheme:` and nothing else, and this
+ * is the question it was standing in for: a path is a path only if resolving it lands back on the
+ * origin it was resolved against.
+ */
+const resolvedOrigin = (path: string): string => {
+  try {
+    return new URL(path, ROUTE_BASE).origin;
+  } catch {
+    // A path `new URL` will not parse is one no browser will fetch either, and reporting it as the
+    // origin it is not is the honest answer here.
+    return '';
+  }
+};
+
+const refuseRoute = (reason: string): never => {
+  throw new BadFlagError({
+    flag: 'route',
+    command: 'shot',
+    reason,
+    // A placeholder, because there is nothing safe to substitute: unlike an absolute URL, an
+    // origin-escaping route carries no path the caller can be assumed to have meant.
+    fix: 'x shot /<path> --json',
+  });
+};
+
 /**
  * A path on the app, never a URL. `x shot https://example.com` would photograph somebody else's
  * site through a headless browser inside your network, which is the SSRF shape `allowHosts` exists
  * to refuse — so it is refused here, at the argument, where the reader can still see why.
+ *
+ * `scheme:` was the ONLY spelling refused until 2026-08-22, and it is one of four: `//evil/x` is a
+ * protocol-relative URL, `\evil\x` is the same thing to every URL parser (a backslash IS a slash
+ * for a special scheme), and a TAB inside the path is deleted by the parser before the host is
+ * read, so `/⇥/evil/x` becomes `//evil/x`. Each one reached `new URL(route, server.url)` and came
+ * back pointed at another host. `allowHostsFrom` one layer down could not catch any of them: it
+ * allows a HOSTNAME, and the hostname it is given is the one the page has already left — which is
+ * how `x shot //localhost:9200/_cat/indices` photographed whatever else was on the dev box.
  */
 export function readRoute(raw: string | undefined): string {
   if (raw === undefined || raw.trim() === '') {
@@ -82,7 +123,20 @@ export function readRoute(raw: string | undefined): string {
       fix: `x shot ${pathOf(route)} --json`,
     });
   }
-  return route.startsWith('/') ? route : `/${route}`;
+  const path = route.startsWith('/') ? route : `/${route}`;
+  // Its own refusal rather than folded into the origin check: `/a\b` stays on this origin and is
+  // still not the route that was typed — the verdict would record `/a\b` beside a picture of
+  // `/a/b`, which is the artifact lying about its own subject.
+  if (path.includes('\\')) {
+    return refuseRoute(`"${route}" contains a backslash, which a URL parser reads as "/"`);
+  }
+  const origin = resolvedOrigin(path);
+  if (origin !== ROUTE_BASE) {
+    return refuseRoute(
+      `"${route}" is not a path on the app: a browser resolves it to ${origin === '' ? 'no URL at all' : origin}`,
+    );
+  }
+  return path;
 }
 
 /**
@@ -164,10 +218,18 @@ export async function runShot(options: ShotRun): Promise<ShotArtifacts> {
     // The probe may legitimately answer nothing — a page that refuses evaluation, a driver with no
     // JS engine. `null` says so; a `0` would read as "the route renders no islands", which is a
     // different and much more alarming claim.
-    const islands = await page
-      .evaluate(ISLAND_PROBE)
-      .then(parseIslandProbe)
-      .catch(() => null);
+    const probe = (): Promise<IslandCount | null> =>
+      page
+        .evaluate(ISLAND_PROBE)
+        .then(parseIslandProbe)
+        .catch(() => null);
+    // The same budget again, and deliberately no new flag: `settleMs` is the deadline at which the
+    // runtime CALLS `import()`, so a mount gets exactly as long to settle as the runtime got to
+    // start it — and `--settle 0`, which asks for no wait, still gets none.
+    const islands = await settleIslands(probe, {
+      windowMs: options.settleMs,
+      pollMs: SETTLE_POLL_MS,
+    });
     const bytes = await page.screenshot({ fullPage: options.fullPage });
     // Read AFTER the capture, so an error logged while the page settled is in the verdict that
     // ships with the picture it explains.

package/src/cmd-tasks.ts

@@ -3,7 +3,7 @@
 // an agent reading `0 3 * * *` and guessing. CLI wiring only; the pure computation lives in
 // `tasks-facts.ts` — the same split `cmd-jobs.ts` makes against `jobs-report.ts`.
 
-import { systemClock } from '@ultimat3/core';
+import { nearestName, systemClock } from '@ultimat3/core';
 import type { TaskHandle } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
 import { loadApp } from './app-load';
@@ -12,7 +12,7 @@ import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, DeclarationUnknownError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
-import { flagString, nearest } from './parse';
+import { flagString } from './parse';
 import { renderTable } from './table';
 import {
   findTaskHandle,
@@ -92,7 +92,7 @@ function requireHandle(ctx: CommandContext): TaskHandle {
   const handle = findTaskHandle(name);
   if (handle !== undefined) return handle;
   const known = knownTaskNames();
-  const suggestion = nearest(name, known);
+  const suggestion = nearestName(name, known);
   throw new DeclarationUnknownError(
     suggestion === undefined
       ? { kind: 'tasks', singular: 'task', name, known, verb: 'show' }
@@ -138,7 +138,12 @@ export const tasksCommand: CliCommand = {
     subcommands: ['list', 'show'],
     defaultSubcommand: 'list',
     flags: [
-      { name: 'count', type: 'string', summary: 'show: how many upcoming occurrences to list' },
+      {
+        name: 'count',
+        type: 'string',
+        summary: 'show: how many upcoming occurrences to list',
+        subcommands: ['show'],
+      },
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {

package/src/cmd-verify.ts

@@ -1,17 +1,25 @@
 // `x verify` — the contract. Every check is a named step with its own pass/fail and duration, the
 // same list in the terminal and in --json, and a non-zero exit if any step fails. Green means
-// shippable (axiom 5): one step list, no second checklist, no CI-only step, and no way to narrow
-// the run — `--only` and `--skip` would make "green" mean whatever the caller chose.
+// shippable (axiom 5): one step list, no second checklist, no CI-only step.
+//
+// `--only <step>` is the ONE narrowing, decided as D6, and it does not weaken that: the GATE is
+// the no-flag run, and a narrowed run says `NOT A GATE RUN` in the summary and in `--json` so no
+// reader of either can take it for one. `--skip` stays refused — it would let a caller drop the
+// step that was going to fail and still read the output as a whole-tree verdict.
 
+import { nearestName } from '@ultimat3/core';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
+import { BadFlagError } from './errors';
 import { readIntFlag } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
+import { flagString } from './parse';
 import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import { VERIFY_STEPS } from './verify-checks';
 import { runVerify } from './verify-run';
 import type { VerifyStepName } from './verify-step';
+import { VERIFY_STEP_NAMES } from './verify-step';
 
 // One import path for the gate, unchanged by the split: `index.ts`, `x build` and the MCP host all
 // reach the list and the runner through this module, and a second path to either would be the
@@ -23,30 +31,63 @@ export const verifyCommand: CliCommand = {
   spec: {
     name: 'verify',
     summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
-    usage: 'x verify [--workers N] [--json]',
+    usage: 'x verify [--only <step>] [--workers N] [--json]',
     requiresApp: true,
-    // The only flag, and it is not `--only`/`--skip` in disguise: it changes how wide the test
-    // steps spread, never which steps run. Every step still runs, so "green" still means the
-    // same thing at `--workers 1` as at `--workers 8`.
+    // Two flags, and only one of them narrows. `--workers` changes how wide the test steps
+    // spread, never which steps run. `--only` runs one step and says so in both renderers —
+    // never silently, which is the whole of what makes it safe to have.
     flags: [
       {
         name: 'workers',
         type: 'string',
         summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
       },
+      {
+        name: 'only',
+        type: 'string',
+        summary:
+          'run ONE step by name — an iteration loop, NOT A GATE RUN; the gate is this command with no flag',
+      },
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('verify', ctx.cwd).dir;
+    // Both readers before the run: an unrunnable flag must be refused in milliseconds, not after
+    // `tsc -b` has spent fourteen seconds on a run the caller cannot use.
     const workers = readWorkers(ctx.args);
+    const only = readOnlyStep(ctx.args);
     return runVerify(VERIFY_STEPS, {
       root,
       runner: ctx.runner,
       ...(workers === undefined ? {} : { workers }),
+      ...(only === undefined ? {} : { only }),
     });
   },
 };
 
+/**
+ * The step `--only` names, or nothing. Refused against `VERIFY_STEP_NAMES` — the same constant the
+ * runner's list is built from — so a typo can never be read as "narrow to no steps at all", which
+ * is a run that passes by checking nothing.
+ *
+ * A near miss leads with the step it is near; a word near NOTHING gets the gate itself rather than
+ * an invented lead, which is the rule `parse.ts` already follows for a command that resembles
+ * none. Both arms are commands that run.
+ */
+export const readOnlyStep = (args: ParsedArgs): VerifyStepName | undefined => {
+  const raw = flagString(args, 'only');
+  if (raw === undefined) return undefined;
+  const found = VERIFY_STEP_NAMES.find((name) => name === raw);
+  if (found !== undefined) return found;
+  const suggestion = nearestName(raw, VERIFY_STEP_NAMES);
+  throw new BadFlagError({
+    flag: 'only',
+    command: 'verify',
+    reason: `"${raw}" is not a gate step (${VERIFY_STEP_NAMES.join(', ')})`,
+    fix: suggestion === undefined ? 'x verify --json' : `x verify --only ${suggestion} --json`,
+  });
+};
+
 /**
  * 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

package/src/dev-cache.ts

@@ -17,7 +17,7 @@ import {
   resetTiers,
 } from '@ultimat3/cache';
 import { logger } from '@ultimat3/core';
-import type { Transport, TransportSubscription } from '@ultimat3/realtime';
+import type { Transport, TransportSubscription } from '@ultimat3/realtime/server';
 import type { Env } from './dev-services';
 
 /**