@ultimat3/cli 6.0.0 → 8.0.0

package/src/parse.ts

@@ -2,7 +2,19 @@
 // same way and `--json` / `--help` behave identically everywhere. Pure: no I/O, no process
 // access, so the parser is unit-testable and the dispatcher owns all side effects.
 
+import { nearestName } from '@ultimat3/core';
 import { BadFlagError, MissingSubcommandError, UnknownCommandError } from './errors';
+// `shell-quote.ts` is a leaf — it imports nothing — so the parser stays pure and importable from
+// anywhere while still refusing with a fix line a shell reads as one argument.
+import { quoteArg } from './shell-quote';
+
+/**
+ * The historical name for `@ultimat3/core`'s `nearestName`, kept because it shipped on this
+ * package's exported surface and removing it would be a major for a rename. One implementation
+ * behind both — this is a delegation, not the second copy of the algorithm that `@ultimat3/policy`
+ * used to carry. New callers import `nearestName` from core.
+ */
+export const nearest = nearestName;
 
 export type FlagValue = string | boolean;
 
@@ -12,6 +24,15 @@ export interface FlagSpec {
   readonly summary: string;
   readonly short?: string;
   readonly default?: FlagValue;
+  /**
+   * The subcommands that READ this flag, where it is not command-wide. Absent means every one —
+   * opt-in, because most flags really are. Declared from the same fact the summary states, and
+   * enforced: `x db gen --dry-run` parsed, ran the generator and WROTE the migration, because the
+   * parser validates a flag against the COMMAND and nothing then validates it against the word
+   * that decides what runs. A dry run that writes a file is the direction a mistake may never
+   * fail in. `parse.test.ts` pins that every entry names a subcommand its command declares.
+   */
+  readonly subcommands?: readonly string[];
 }
 
 export interface CommandSpec {
@@ -87,41 +108,11 @@ export const wantsJson = (argv: readonly string[]): boolean =>
 const HELP_ALIASES = new Set(['--help', '-h', 'help']);
 const VERSION_ALIASES = new Set(['--version', '-v', '-V']);
 
-function distance(a: string, b: string): number {
-  const rows = a.length + 1;
-  const cols = b.length + 1;
-  const grid: number[] = new Array<number>(rows * cols).fill(0);
-  const at = (r: number, c: number): number => grid[r * cols + c] ?? 0;
-  for (let r = 0; r < rows; r += 1) grid[r * cols] = r;
-  for (let c = 0; c < cols; c += 1) grid[c] = c;
-  for (let r = 1; r < rows; r += 1) {
-    for (let c = 1; c < cols; c += 1) {
-      const cost = a[r - 1] === b[c - 1] ? 0 : 1;
-      grid[r * cols + c] = Math.min(at(r - 1, c) + 1, at(r, c - 1) + 1, at(r - 1, c - 1) + cost);
-    }
-  }
-  return at(rows - 1, cols - 1);
-}
-
-/** Nearest known name within an edit distance of 3, so the error can suggest a retry. */
-export function nearest(input: string, candidates: readonly string[]): string | undefined {
-  let best: string | undefined;
-  let bestScore = 4;
-  for (const candidate of candidates) {
-    const score = distance(input, candidate);
-    if (score < bestScore) {
-      best = candidate;
-      bestScore = score;
-    }
-  }
-  return best;
-}
-
 function resolveCommand(token: string, specs: readonly CommandSpec[]): CommandSpec {
   const found = specs.find((spec) => spec.name === token || (spec.aliases ?? []).includes(token));
   if (found !== undefined) return found;
   const names = specs.map((spec) => spec.name);
-  const suggestion = nearest(token, names);
+  const suggestion = nearestName(token, names);
   throw new UnknownCommandError(
     suggestion === undefined
       ? { path: token, known: names }
@@ -168,6 +159,9 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   const spec = resolveCommand(first, specs);
   const flags = defaults(spec);
   const positionals: string[] = [];
+  // What argv actually SET, as against what `defaults()` seeded: a default is nobody's request,
+  // and refusing a flag the caller never typed would refuse the command itself.
+  const given = new Set<string>();
   let index = 1;
 
   while (index < tokens.length) {
@@ -183,7 +177,7 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
     const flag = findFlag(name, spec);
     if (flag === undefined) {
       const known = [...GLOBAL_FLAGS, ...(spec.flags ?? [])].map((entry) => entry.name);
-      const suggestion = nearest(name, known);
+      const suggestion = nearestName(name, known);
       throw new BadFlagError({
         flag: name,
         command: spec.name,
@@ -193,6 +187,7 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
             : `unknown flag — did you mean --${suggestion}?`,
       });
     }
+    given.add(flag.name);
     if (flag.type === 'boolean') {
       if (inlineValue !== undefined) {
         throw new BadFlagError({
@@ -204,30 +199,79 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
       flags.set(flag.name, !negated);
       continue;
     }
+    // `--no-<string flag>` used to fall through to the value read below, so `--no-name feat` set
+    // `name` to `feat`: the caller asked for the flag to be OFF and argv's next token became its
+    // value. There is nothing a string flag can be negated to, so this is a refusal.
+    if (negated) {
+      throw new BadFlagError({
+        flag: flag.name,
+        command: spec.name,
+        reason: `--no- negates a boolean flag, and --${flag.name} takes a value`,
+      });
+    }
     const value = inlineValue ?? tokens[index];
-    if (value === undefined || value.startsWith('--')) {
+    if (value === undefined) {
+      throw new BadFlagError({ flag: flag.name, command: spec.name, reason: 'expects a value' });
+    }
+    // A value beginning `--` is a flag as far as this loop can tell, and the caller who really
+    // meant it as a value has one form available — so the refusal names it rather than leaving
+    // `--filter --json` looking like a parser that cannot express the input.
+    if (value.startsWith('--')) {
       throw new BadFlagError({
         flag: flag.name,
         command: spec.name,
-        reason: 'expects a value',
+        reason: `expects a value, and "${value}" is a flag — write --${flag.name}=${value} to pass it as the value`,
       });
     }
     if (inlineValue === undefined) index += 1;
     flags.set(flag.name, value);
   }
 
-  const subcommand = readSubcommand(spec, positionals);
+  // Before `readSubcommand`, which THROWS on a missing or unknown one: `x db --help`, `x mcp
+  // --help` and `x pr --help` all exited 1 with `X_CLI_BAD_FLAG` — usage refused to the caller
+  // asking what the usage is, on every command that takes a subcommand. Help is answered by
+  // `dispatch`, which needs only the command name.
+  const help = flags.get('help') === true;
+  const subcommand = help ? undefined : readSubcommand(spec, positionals);
+  if (subcommand !== undefined) assertFlagsApply(spec, subcommand, given, flags);
   return {
     command: spec.name,
     subcommand,
     positionals: subcommand === undefined ? positionals : positionals.slice(1),
     flags,
     json: flags.get('json') === true,
-    help: flags.get('help') === true,
+    help,
     passthrough,
   };
 }
 
+/**
+ * A flag the resolved subcommand does not read is refused, never ignored. Only what argv SET is
+ * judged, and only against a flag that declared a scope: an undeclared flag stays command-wide.
+ *
+ * The fix carries the caller's own value through `quoteArg`, because it is pasted into a shell
+ * verbatim — `x db backfill --status 'a b'` runs, `--status a b` runs something else.
+ */
+function assertFlagsApply(
+  spec: CommandSpec,
+  subcommand: string,
+  given: ReadonlySet<string>,
+  flags: ReadonlyMap<string, FlagValue>,
+): void {
+  for (const flag of spec.flags ?? []) {
+    const only = flag.subcommands;
+    if (only === undefined || only.includes(subcommand) || !given.has(flag.name)) continue;
+    const value = flags.get(flag.name);
+    const argument = typeof value === 'string' ? ` ${quoteArg(value)}` : '';
+    throw new BadFlagError({
+      flag: flag.name,
+      command: `${spec.name} ${subcommand}`,
+      reason: `read by ${only.map((word) => `x ${spec.name} ${word}`).join(' / ')} only — "${subcommand}" would ignore it`,
+      fix: `x ${spec.name} ${only[0]} --${flag.name}${argument}`,
+    });
+  }
+}
+
 function splitInline(raw: string): [string, string | undefined] {
   const eq = raw.indexOf('=');
   if (eq === -1) return [raw, undefined];
@@ -243,7 +287,7 @@ function readSubcommand(spec: CommandSpec, positionals: readonly string[]): stri
     throw new MissingSubcommandError({ command: spec.name, known: allowed });
   }
   if (allowed.includes(token)) return token;
-  const suggestion = nearest(token, allowed);
+  const suggestion = nearestName(token, allowed);
   throw new UnknownCommandError(
     suggestion === undefined
       ? { path: `${spec.name} ${token}`, known: allowed }

package/src/pr-threads.ts

@@ -0,0 +1,291 @@
+// The GraphQL a review lives behind, and the rows it becomes. `gh pr view --comments` shows ISSUE
+// comments; the findings a reviewer anchored to a line are `reviewThreads`, and the thread id that
+// resolves one exists in no REST response and in no web URL — this file is where that query stops
+// being folklore.
+
+import { t } from '@ultimat3/schema';
+import type { GhHost } from './gh';
+import { GhResponseInvalidError, ghGraphql } from './gh';
+import type { GhRepo } from './gh-target';
+
+/**
+ * How many threads one page holds. The query is built from it, so the report and the request can
+ * never disagree about what "the first page" was.
+ */
+export const THREAD_PAGE = 100;
+
+/** And how many comments of each. A long argument still shows the finding that opened it. */
+export const COMMENT_PAGE = 10;
+
+/**
+ * One document, because the two hazards are only visible together: a `reviewDecision` survives
+ * later pushes, so `CHANGES_REQUESTED` may predate the commits that addressed it, and the only
+ * thing that settles it is the head oid — asking for the threads and then asking for the head is
+ * two answers about two moments.
+ */
+export const REVIEW_QUERY =
+  'query($owner:String!,$name:String!,$n:Int!){repository(owner:$owner,name:$name){' +
+  'pullRequest(number:$n){number url headRefOid reviewDecision ' +
+  'commits(last:1){nodes{commit{oid committedDate}}} ' +
+  'latestOpinionatedReviews(first:20){nodes{state submittedAt author{login} commit{oid}}} ' +
+  `reviewThreads(first:${THREAD_PAGE}){pageInfo{hasNextPage} nodes{id isResolved isOutdated ` +
+  `path line originalLine comments(first:${COMMENT_PAGE}){totalCount ` +
+  'nodes{author{login} createdAt body}}}}}}}';
+
+const AUTHOR = t.nullable(t.object({ login: t.string }));
+
+const REVIEW_RESPONSE = t.object({
+  data: t.object({
+    repository: t.nullable(
+      t.object({
+        pullRequest: t.nullable(
+          t.object({
+            number: t.number,
+            url: t.string,
+            headRefOid: t.string,
+            reviewDecision: t.nullable(t.string),
+            commits: t.object({
+              nodes: t.array(
+                t.object({ commit: t.object({ oid: t.string, committedDate: t.string }) }),
+              ),
+            }),
+            latestOpinionatedReviews: t.object({
+              nodes: t.array(
+                t.object({
+                  state: t.string,
+                  submittedAt: t.nullable(t.string),
+                  author: AUTHOR,
+                  commit: t.nullable(t.object({ oid: t.string })),
+                }),
+              ),
+            }),
+            reviewThreads: t.object({
+              pageInfo: t.object({ hasNextPage: t.boolean }),
+              nodes: t.array(
+                t.object({
+                  id: t.string,
+                  isResolved: t.boolean,
+                  isOutdated: t.boolean,
+                  path: t.string,
+                  line: t.nullable(t.number),
+                  originalLine: t.nullable(t.number),
+                  comments: t.object({
+                    totalCount: t.number,
+                    nodes: t.array(
+                      t.object({ author: AUTHOR, createdAt: t.string, body: t.string }),
+                    ),
+                  }),
+                }),
+              ),
+            }),
+          }),
+        ),
+      }),
+    ),
+  }),
+});
+
+export interface PrComment {
+  readonly author: string;
+  readonly createdAt: string;
+  readonly body: string;
+}
+
+export interface PrThread {
+  readonly id: string;
+  readonly path: string;
+  /** The line the comment is anchored to NOW; `null` once the diff has moved under it. */
+  readonly line: number | null;
+  /** Where it was anchored when it was written — the only locator an outdated thread still has. */
+  readonly originalLine: number | null;
+  readonly isResolved: boolean;
+  readonly isOutdated: boolean;
+  readonly comments: readonly PrComment[];
+  /** Every comment on the thread, against the ten this page carries. */
+  readonly commentCount: number;
+}
+
+export interface PrReview {
+  readonly state: string;
+  readonly author: string;
+  readonly submittedAt: string | null;
+  readonly commit: string | null;
+  /**
+   * The review was submitted against a commit that is no longer the head. A verdict about the
+   * COMMIT, not about the clock: two reviews seconds apart can straddle a push, and a timestamp
+   * comparison would call one of them current.
+   */
+  readonly stale: boolean;
+}
+
+export interface PrReviewReport {
+  readonly repo: string;
+  readonly number: number;
+  readonly url: string;
+  readonly headSha: string;
+  readonly headCommittedAt: string | null;
+  readonly reviewDecision: string | null;
+  /** The review the decision came from, when one of the opinionated reviews states it. */
+  readonly decidingReview: PrReview | null;
+  readonly threads: readonly PrThread[];
+  /** More threads exist than one page holds, so `threads` is the first page and not the set. */
+  readonly truncated: boolean;
+}
+
+/** GitHub answers `null` for a deleted account. A row with no author still carries its finding. */
+const loginOf = (author: { readonly login: string } | null): string => author?.login ?? 'ghost';
+
+/**
+ * The review a `reviewDecision` came from. GitHub derives the decision from every opinionated
+ * review at once, so the one that STATES it is the one to date — falling back to the newest, which
+ * is the only defensible guess when none of them spells the decision out.
+ */
+export function decidingReview(
+  reviews: readonly PrReview[],
+  decision: string | null,
+): PrReview | null {
+  const stating = reviews.filter((review) => review.state === decision);
+  const pool = stating.length > 0 ? stating : reviews;
+  return pool.reduce<PrReview | null>(
+    (newest, review) =>
+      newest === null || (review.submittedAt ?? '') > (newest.submittedAt ?? '') ? review : newest,
+    null,
+  );
+}
+
+/** Unresolved first, then by file and line: the order an agent works the list in. */
+export function orderThreads(threads: readonly PrThread[]): readonly PrThread[] {
+  return [...threads].sort((left, right) => {
+    if (left.isResolved !== right.isResolved) return left.isResolved ? 1 : -1;
+    if (left.path !== right.path) return left.path < right.path ? -1 : 1;
+    return (left.line ?? left.originalLine ?? 0) - (right.line ?? right.originalLine ?? 0);
+  });
+}
+
+/**
+ * One round trip, one report. `repository` and `pullRequest` are both nullable in the schema
+ * because GraphQL answers `null` for either — but gh exits non-zero on the `errors` block that
+ * accompanies it, so reaching here with a `null` means GitHub answered a shape nobody has seen,
+ * and `X_GH_RESPONSE_INVALID` is a better sentence for that than a `TypeError` two frames later.
+ */
+export async function fetchReviewReport(
+  host: GhHost,
+  repo: GhRepo,
+  number: number,
+): Promise<PrReviewReport | null> {
+  const response = await ghGraphql(
+    host,
+    REVIEW_QUERY,
+    { owner: repo.owner, name: repo.name, n: number },
+    REVIEW_RESPONSE,
+    {
+      label: `gh api graphql (review threads on ${repo.slug}#${number})`,
+      fix: `gh pr view ${number} --repo ${repo.slug} --json number   # confirm the pull request is visible to this token`,
+    },
+  );
+  const pull = response.data.repository?.pullRequest;
+  if (pull === undefined || pull === null) return null;
+  const head = pull.commits.nodes[0]?.commit ?? null;
+  const reviews: readonly PrReview[] = pull.latestOpinionatedReviews.nodes.map((review) => ({
+    state: review.state,
+    author: loginOf(review.author),
+    submittedAt: review.submittedAt,
+    commit: review.commit?.oid ?? null,
+    stale: review.commit?.oid !== pull.headRefOid,
+  }));
+  return {
+    repo: repo.slug,
+    number: pull.number,
+    url: pull.url,
+    headSha: pull.headRefOid,
+    headCommittedAt: head?.committedDate ?? null,
+    reviewDecision: pull.reviewDecision,
+    decidingReview: decidingReview(reviews, pull.reviewDecision),
+    truncated: pull.reviewThreads.pageInfo.hasNextPage,
+    threads: orderThreads(
+      pull.reviewThreads.nodes.map((thread) => ({
+        id: thread.id,
+        path: thread.path,
+        line: thread.line,
+        originalLine: thread.originalLine,
+        isResolved: thread.isResolved,
+        isOutdated: thread.isOutdated,
+        commentCount: thread.comments.totalCount,
+        comments: thread.comments.nodes.map((comment) => ({
+          author: loginOf(comment.author),
+          createdAt: comment.createdAt,
+          body: comment.body,
+        })),
+      })),
+    ),
+  };
+}
+
+export const RESOLVE_MUTATION =
+  'mutation($t:ID!){resolveReviewThread(input:{threadId:$t}){thread{id isResolved}}}';
+
+// Both levels nullable, because both are nullable in GitHub's schema (`ResolveReviewThreadPayload.
+// thread` is an OBJECT, not a NON_NULL one) — and a payload that does not carry the thread it
+// claims to have resolved is exactly the answer this command must not read as a success.
+const RESOLVE_RESPONSE = t.object({
+  data: t.object({
+    resolveReviewThread: t.nullable(
+      t.object({ thread: t.nullable(t.object({ id: t.string, isResolved: t.boolean })) }),
+    ),
+  }),
+});
+
+/**
+ * Marks the CONVERSATION resolved, and says only that. Whether the finding is addressed is a fact
+ * about the code, which no GitHub mutation can observe — the summary this returns feeds a line
+ * that refuses to conflate the two.
+ */
+export async function resolveThread(host: GhHost, threadId: string): Promise<string> {
+  const fix = 'x pr review --json   # the id column is the thread id this mutation takes';
+  const label = `gh api graphql (resolve ${threadId})`;
+  const response = await ghGraphql(host, RESOLVE_MUTATION, { t: threadId }, RESOLVE_RESPONSE, {
+    label,
+    fix,
+  });
+  const thread = response.data.resolveReviewThread?.thread;
+  // A mutation that exited 0 and did not come back saying the thread is resolved has not told us
+  // it worked, and reporting `resolved` off the exit code alone is how a command claims an effect
+  // it never observed.
+  if (thread?.isResolved !== true) {
+    throw new GhResponseInvalidError({
+      label,
+      detail: 'the mutation returned no resolved thread',
+      fix,
+    });
+  }
+  // The id GitHub echoed, not the one that was sent: they are the same string on every success,
+  // and reporting the one we sent would make a summary that cannot tell a hit from a miss.
+  return thread.id;
+}
+
+export const REPLY_MUTATION =
+  'mutation($t:ID!,$b:String!){addPullRequestReviewThreadReply(' +
+  'input:{pullRequestReviewThreadId:$t,body:$b}){comment{id url}}}';
+
+const REPLY_RESPONSE = t.object({
+  data: t.object({
+    addPullRequestReviewThreadReply: t.nullable(
+      t.object({ comment: t.nullable(t.object({ id: t.string, url: t.string })) }),
+    ),
+  }),
+});
+
+/** A reply lands IN the thread, which is the only place a reviewer reads it. Returns its URL. */
+export async function replyToThread(host: GhHost, threadId: string, body: string): Promise<string> {
+  const fix = 'x pr review --json   # the id column is the thread id this mutation takes';
+  const label = `gh api graphql (reply on ${threadId})`;
+  const response = await ghGraphql(host, REPLY_MUTATION, { t: threadId, b: body }, REPLY_RESPONSE, {
+    label,
+    fix,
+  });
+  const url = response.data.addPullRequestReviewThreadReply?.comment?.url;
+  if (url === undefined || url === null) {
+    throw new GhResponseInvalidError({ label, detail: 'the mutation posted no comment', fix });
+  }
+  return url;
+}

package/src/prerender.ts

@@ -14,13 +14,19 @@ import { measureDocumentJs, writeBuildStats } from './budgets';
 import { routeDocument } from './dev-render';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
+import type { SkippedRoute } from './static-report';
+import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 
 /**
- * `static` only. `isr` revalidates and `ssr`/`stream`/`spa` need a process, so writing any of them
- * to disk would publish a page whose staleness nothing can correct — and the route already
- * declared which of the five it is.
+ * `static` only. `isr` revalidates and `ssr`/`stream` need a process, so writing any of them to
+ * disk would publish a page whose staleness nothing can correct — and the route already declared
+ * which of the four it is.
+ *
+ * DERIVED from `skipReasonFor`, never a second `=== 'static'`: the answer and the reason reported
+ * beside it are one decision, and two copies of it is how a route came to be dropped silently.
  */
-export const isPrerenderable = (entry: RouteEntry): boolean => entry.config.render === 'static';
+export const isPrerenderable = (entry: RouteEntry): boolean =>
+  skipReasonFor({ surface: entry.surface, render: entry.config.render }) === null;
 
 export interface PrerenderOptions {
   readonly root: string;
@@ -30,6 +36,8 @@ export interface PrerenderOptions {
 }
 
 export interface PrerenderedPage {
+  /** The DECLARED route, `/blog/:slug` — one route can write many pages, and the report groups them. */
+  readonly route: string;
   readonly path: string;
   /** Relative to `out`, POSIX, as `renderStatic` computed it. */
   readonly file: string;
@@ -47,8 +55,13 @@ export interface PrerenderReport {
   readonly out: string;
   readonly buildId: string;
   readonly pages: readonly PrerenderedPage[];
-  /** Routes that exist and are not static. Reported, so "only 2 pages" is never a mystery. */
-  readonly skipped: readonly string[];
+  /**
+   * Every declared route that wrote no file, WITH the cause. A bare path list was the whole of
+   * #242: `.x/static/` held a partial site, the report said only which paths were missing, and a
+   * screenshot tool pointed at the directory filed "the island did not mount" against a route that
+   * had never been in the artifact. The reason is what tells an author whether an edit exists.
+   */
+  readonly skipped: readonly SkippedRoute[];
   /**
    * Routes whose budget this build could not weigh, with the reason. `X_BUDGET_UNMEASURED` is what
    * the gate then reports for each; this is the half that says WHY, which a per-route finding read
@@ -57,6 +70,8 @@ export interface PrerenderReport {
   readonly unmeasured: readonly UnmeasuredRoute[];
   /** Where the measured stats landed, for the `budgets` gate step to read. */
   readonly stats: string;
+  /** Where the emitted/skipped inventory landed, for `x build --target static` to read back. */
+  readonly report: string;
   /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
   readonly islands: readonly string[];
 }
@@ -104,7 +119,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const buildId = (await appManifest(options.root)).manifest.buildId;
   const origin = options.origin ?? DEFAULT_ORIGIN;
   const pages: PrerenderedPage[] = [];
-  const skipped: string[] = [];
+  const skipped: SkippedRoute[] = [];
   const routes: RouteStats[] = [];
   const unmeasured: UnmeasuredRoute[] = [];
 
@@ -115,8 +130,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   await writeIslands(islands, options.out);
 
   for (const entry of routeEntries()) {
-    if (!isPrerenderable(entry)) {
-      skipped.push(entry.path);
+    const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
+    const reason = skipReasonFor(facts);
+    if (reason !== null) {
+      skipped.push(skippedRoute(facts, reason));
       if (!declaresBudget(entry)) continue;
       // Non-fatal, and that is deliberate: an ssr page's `load` may want a request, a session or a
       // database this build does not have, and a `x build --target static` that started failing on
@@ -152,10 +169,24 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         ),
       { buildId },
     );
+    // `enumeratePrerender` answers `[]` for a dynamic route with no `prerender()`, so a
+    // `render: 'static'` route with a param writes nothing and used to be reported NOWHERE — past
+    // the skip branch by its mode, absent from `pages` by its zero artifacts. A route in neither
+    // list is the defect this report exists to close, wearing its other shape.
+    if (artifacts.length === 0) {
+      skipped.push(skippedRoute(facts, 'no-prerender-paths'));
+      continue;
+    }
     for (const artifact of artifacts) {
       const file = join(options.out, artifact.outputPath);
       const bytes = await Bun.write(file, artifact.html);
-      pages.push({ path: artifact.path, file: artifact.outputPath, hash: artifact.hash, bytes });
+      pages.push({
+        route: entry.path,
+        path: artifact.path,
+        file: artifact.outputPath,
+        hash: artifact.hash,
+        bytes,
+      });
       // Measured from the document that was just written, so the `budgets` step compares a
       // declared budget against bytes that exist on disk rather than against a graph's estimate.
       const measured = await measureDocumentJs(artifact.html, options.out);
@@ -168,6 +199,16 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     }
   }
   const stats = await writeBuildStats(options.root, { routes });
+  // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does
+  // not reach `prerenderSite` produces neither — and `x verify`'s `budgets` step already reds that
+  // app with `X_BUDGET_UNMEASURED`, which is why this side needs no second code of its own.
+  const report = await writeStaticReport(options.root, {
+    target: 'static',
+    out: options.out,
+    buildId,
+    emitted: pages.map((page) => ({ route: page.route, path: page.path, file: page.file })),
+    skipped,
+  });
   return {
     out: options.out,
     buildId,
@@ -175,6 +216,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     skipped,
     unmeasured,
     stats,
+    report,
     islands: islands.chunks.map((chunk) => chunk.file),
   };
 }

package/src/realtime-browser-probe-fixture.ts

@@ -0,0 +1,9 @@
+// The browser island `wiki/Realtime.md` promises: one live hook and nothing else. It is a real
+// module rather than a string a test writes to a temp path, because module resolution is the thing
+// under test — `@ultimat3/realtime`'s client entry must reach neither the bus nor the WAL decoder.
+// Bundled AND imported by `realtime-browser-barrel.test.ts` — the import is what gives it an lcov
+// record, since `Bun.build()` reads this file without evaluating it.
+
+import { useLive } from '@ultimat3/realtime';
+
+export const probeUseLive = useLive;

package/src/registry.ts

@@ -1,7 +1,9 @@
 // The command registry: the one list the parser, the help catalogue and the dispatcher all read.
 // A command that is not here does not exist — there is no second place to register one.
 
+import { affectedCommand } from './cmd-affected';
 import { buildCommand } from './cmd-build';
+import { ciCommand } from './cmd-ci';
 import { dbCommand } from './cmd-db';
 import { deployCommand } from './cmd-deploy';
 import { devCommand } from './cmd-dev';
@@ -19,9 +21,11 @@ import { mcpCommand } from './cmd-mcp';
 import { newCommand } from './cmd-new';
 import { plannedCommands } from './cmd-planned';
 import { policyCommand } from './cmd-policy';
+import { prCommand } from './cmd-pr';
 import { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
 import { routesCommand } from './cmd-routes';
 import { secretsCommand } from './cmd-secrets';
+import { shotCommand } from './cmd-shot';
 import { tasksCommand } from './cmd-tasks';
 import { testCommand } from './cmd-test';
 import { verifyCommand } from './cmd-verify';
@@ -69,6 +73,10 @@ const CORE: readonly CliCommand[] = [
   errorsCommand,
   docsCommand,
   fixCommand,
+  affectedCommand,
+  shotCommand,
+  prCommand,
+  ciCommand,
 ];
 
 /**