@ultimat3/cli 6.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

@@ -0,0 +1,359 @@
+// `x pr review|resolve|reply` — the inline review, in a terminal. `gh pr view --comments` prints
+// ISSUE comments, so the findings a reviewer anchored to a line are invisible to it and the thread
+// id needed to resolve one exists nowhere a human can copy. This command is the one place that
+// query lives, and the one place the two facts a reviewer's verdict hides behind are stated: a
+// `reviewDecision` outlives the push that answered it, and a RESOLVED thread is a closed
+// conversation rather than a fixed finding.
+
+import type { CliCommand, CommandContext } from './command';
+import {
+  BadFlagError,
+  MissingPositionalError,
+  MissingSubcommandError,
+  UnknownCommandError,
+} from './errors';
+import { parseIntFlag } from './flag-number';
+import { PrNotFoundError, resolvePrNumber, resolveRepo } from './gh-target';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { flagBool, flagString } from './parse';
+import type { PrReviewReport, PrThread } from './pr-threads';
+import { fetchReviewReport, replyToThread, resolveThread, THREAD_PAGE } from './pr-threads';
+
+export const PR_SUBCOMMANDS = ['review', 'resolve', 'reply'] as const;
+
+/**
+ * Every catalog key this command renders, declared. `msg()` answers `⟦key⟧` for a key nobody
+ * added — loud in a terminal and SILENT to a build — so the list is exported and
+ * `cmd-pr.test.ts` holds it against the catalog, which turns a missing string into a failing test
+ * instead of a rendered artefact of one.
+ */
+export const PR_MESSAGE_KEYS = [
+  'cli.pr.review.count',
+  'cli.pr.review.none',
+  'cli.pr.review.decision',
+  'cli.pr.review.stale',
+  'cli.pr.review.current',
+  'cli.pr.review.undecided',
+  'cli.pr.review.truncated',
+  'cli.pr.thread.open',
+  'cli.pr.thread.closed',
+  'cli.pr.thread.outdated',
+  'cli.pr.thread.comment',
+  'cli.pr.thread.more',
+  'cli.pr.body.truncated',
+  'cli.pr.line.unknown',
+  'cli.pr.resolved',
+  'cli.pr.replied',
+] as const;
+
+/** Lines of each comment body shown before it is cut. CodeRabbit's run to several thousand. */
+export const BODY_LINES = 20;
+
+export const prCommand: CliCommand = {
+  spec: {
+    name: 'pr',
+    summary: 'inline review threads: list them with their ids, resolve one, reply in one',
+    usage:
+      'x pr review [--pr <n>] [--repo owner/name] [--all] [--full] | x pr resolve <thread-id> | x pr reply <thread-id> --body "…"',
+    subcommands: PR_SUBCOMMANDS,
+    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' },
+      // 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> {
+    // No `defaultSubcommand`: `resolve` and `reply` both WRITE to a pull request, so "whatever the
+    // caller left out" is not a safe guess for any of the three.
+    const sub = ctx.args.subcommand;
+    if (sub === undefined) {
+      throw new MissingSubcommandError({ command: 'pr', known: PR_SUBCOMMANDS });
+    }
+    if (sub === 'review') return runReview(ctx);
+    if (sub === 'resolve') return runResolve(ctx);
+    if (sub === 'reply') return runReply(ctx);
+    throw new UnknownCommandError({
+      path: `pr ${sub}`,
+      known: PR_SUBCOMMANDS,
+      suggestion: 'help pr',
+    });
+  },
+};
+
+/** `--pr` bounds, declared once so the refusal and the resolution cannot disagree about them. */
+const PR_NUMBER = {
+  name: 'pr',
+  command: 'pr review',
+  min: 1,
+  example: 'x pr review --pr 241 --json',
+} as const;
+
+async function runReview(ctx: CommandContext): Promise<CommandResult> {
+  // 'pr review', not 'pr': `resolveRepo` builds its refusal's `fix:` from this word, and
+  // `x pr --repo …` is a command that throws `MissingSubcommandError` — a fix line that
+  // reproduces its own failure is the shape `MissingSubcommandError`'s own doc block warns about.
+  const repo = await resolveRepo(ctx, 'pr review', flagString(ctx.args, 'repo'));
+  const raw = flagString(ctx.args, 'pr');
+  const number =
+    raw === undefined ? await resolvePrNumber(ctx, repo) : parseIntFlag(raw, PR_NUMBER);
+  const report = await fetchReviewReport(ctx, repo, number);
+  if (report === null) {
+    throw new PrNotFoundError({ detail: `${repo.slug}#${number} answered no pull request` });
+  }
+  const all = flagBool(ctx.args, 'all');
+  const shown = all ? report.threads : report.threads.filter((thread) => !thread.isResolved);
+  const bodyLines = flagBool(ctx.args, 'full') ? Number.POSITIVE_INFINITY : BODY_LINES;
+  const unresolved = report.threads.filter((thread) => !thread.isResolved).length;
+  return {
+    // An inspection command, so the verdict is "the report was produced" and never "the review is
+    // clean": an agent loops read → edit → resolve on this output, and a non-zero exit for every
+    // open thread would report the work still to do as a failure of the command that listed it.
+    ok: true,
+    command: 'pr',
+    summary:
+      report.threads.length === 0
+        ? msg('cli.pr.review.none', { repo: report.repo, pr: report.number })
+        : msg('cli.pr.review.count', {
+            unresolved,
+            resolved: report.threads.length - unresolved,
+            repo: report.repo,
+            pr: report.number,
+          }),
+    lines: [...decisionLines(report), ...shown.flatMap((thread) => threadLines(thread, bodyLines))],
+    data: reviewJson(report, shown, bodyLines, unresolved),
+  };
+}
+
+/**
+ * The staleness hazard, rendered before the threads. A `reviewDecision` survives every later push,
+ * so `CHANGES_REQUESTED` on a branch that has since been fixed reads exactly like one that has
+ * not — and the answer is the commit the review was submitted against, which is a fact rather than
+ * a timestamp comparison across a push.
+ */
+function decisionLines(report: PrReviewReport): readonly string[] {
+  const review = report.decidingReview;
+  if (review === null) {
+    return [msg('cli.pr.review.undecided'), ...truncationLines(report)];
+  }
+  return [
+    msg('cli.pr.review.decision', {
+      decision: report.reviewDecision ?? review.state,
+      author: review.author,
+      submitted: review.submittedAt ?? '',
+    }),
+    review.stale
+      ? msg('cli.pr.review.stale', {
+          commit: short(review.commit),
+          head: short(report.headSha),
+          committed: report.headCommittedAt ?? '',
+        })
+      : msg('cli.pr.review.current', { head: short(report.headSha) }),
+    ...truncationLines(report),
+  ];
+}
+
+const truncationLines = (report: PrReviewReport): readonly string[] =>
+  report.truncated ? [msg('cli.pr.review.truncated', { count: THREAD_PAGE })] : [];
+
+/** Seven characters is what every GitHub UI shows, and enough to paste into `git show`. */
+const short = (sha: string | null): string => (sha === null ? '' : sha.slice(0, 7));
+
+const lineOf = (thread: PrThread): string =>
+  thread.line === null
+    ? (thread.originalLine?.toString() ?? msg('cli.pr.line.unknown'))
+    : String(thread.line);
+
+function threadLines(thread: PrThread, bodyLines: number): readonly string[] {
+  const head = thread.isResolved ? 'cli.pr.thread.closed' : 'cli.pr.thread.open';
+  const out = [msg(head, { path: thread.path, line: lineOf(thread), id: thread.id })];
+  if (thread.isOutdated) out.push(msg('cli.pr.thread.outdated', { line: lineOf(thread) }));
+  for (const comment of thread.comments) {
+    out.push(
+      msg('cli.pr.thread.comment', { author: comment.author, createdAt: comment.createdAt }),
+    );
+    const clamped = clampBody(comment.body, bodyLines);
+    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;
+  if (hidden > 0) out.push(msg('cli.pr.thread.more', { hidden }));
+  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
+ * same bytes the terminal shows and `--full` moves both — a `lines` render that carried less than
+ * the data would be two reports of one review.
+ */
+export function clampBody(
+  body: string,
+  limit: number,
+): { readonly lines: readonly string[]; readonly hidden: number } {
+  const lines = body.replaceAll('\r\n', '\n').split('\n');
+  if (lines.length <= limit) return { lines, hidden: 0 };
+  return { lines: lines.slice(0, limit), hidden: lines.length - limit };
+}
+
+function reviewJson(
+  report: PrReviewReport,
+  shown: readonly PrThread[],
+  bodyLines: number,
+  unresolved: number,
+): JsonValue {
+  const review = report.decidingReview;
+  return {
+    repo: report.repo,
+    pr: report.number,
+    url: report.url,
+    headSha: report.headSha,
+    headCommittedAt: report.headCommittedAt,
+    reviewDecision: report.reviewDecision,
+    review:
+      review === null
+        ? null
+        : {
+            state: review.state,
+            author: review.author,
+            submittedAt: review.submittedAt,
+            commit: review.commit,
+            // The hazard as a field, because an agent reading `--json` never sees the line above.
+            stale: review.stale,
+          },
+    counts: {
+      total: report.threads.length,
+      unresolved,
+      resolved: report.threads.length - unresolved,
+      shown: shown.length,
+    },
+    truncated: report.truncated,
+    threads: shown.map((thread) => {
+      const comments = thread.comments.map((comment) => {
+        const clamped = clampBody(comment.body, bodyLines);
+        return {
+          author: comment.author,
+          createdAt: comment.createdAt,
+          body: clamped.lines.join('\n'),
+          bodyLinesHidden: clamped.hidden,
+        };
+      });
+      return {
+        id: thread.id,
+        path: thread.path,
+        line: thread.line,
+        originalLine: thread.originalLine,
+        isResolved: thread.isResolved,
+        isOutdated: thread.isOutdated,
+        commentCount: thread.commentCount,
+        comments,
+      };
+    }),
+  };
+}
+
+/** A thread id is a positional: it comes out of `x pr review`, so it is never typed by hand. */
+function threadIdOf(ctx: CommandContext, subcommand: string, example: string): string {
+  const id = ctx.args.positionals[0];
+  if (id === undefined) {
+    throw new MissingPositionalError({
+      command: `pr ${subcommand}`,
+      positional: 'thread-id',
+      example,
+    });
+  }
+  return id;
+}
+
+/**
+ * Resolving is a statement about the CONVERSATION. Nothing GitHub can be asked observes whether
+ * the finding is fixed, so the summary says what happened and refuses to imply the other thing —
+ * a command that reported "addressed" would be the framework asserting a fact it cannot check.
+ */
+async function runResolve(ctx: CommandContext): Promise<CommandResult> {
+  const id = threadIdOf(ctx, 'resolve', 'x pr resolve PRRT_kwDOTkDHL86a6ivd --json');
+  const resolved = await resolveThread(ctx, id);
+  return {
+    ok: true,
+    command: 'pr',
+    summary: msg('cli.pr.resolved', { id: resolved }),
+    data: { threadId: resolved, isResolved: true },
+  };
+}
+
+async function runReply(ctx: CommandContext): Promise<CommandResult> {
+  const id = threadIdOf(
+    ctx,
+    'reply',
+    'x pr reply PRRT_kwDOTkDHL86a6ivd --body "fixed in 0f3a91c" --json',
+  );
+  const body = flagString(ctx.args, 'body');
+  if (body === undefined || body.trim() === '') {
+    throw new BadFlagError({
+      flag: 'body',
+      command: 'pr reply',
+      reason: 'a reply posts a comment, and an empty one says nothing to the reviewer',
+      fix: 'x pr reply PRRT_kwDOTkDHL86a6ivd --body "fixed in 0f3a91c" --json',
+    });
+  }
+  const url = await replyToThread(ctx, id, body);
+  return {
+    ok: true,
+    command: 'pr',
+    summary: msg('cli.pr.replied', { id, url }),
+    data: { threadId: id, url },
+  };
+}

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 }