@ultimat3/cli 6.0.0 → 7.0.0

package/src/island-solid-production.ts

@@ -0,0 +1,129 @@
+// Every `solid-js` import in an island chunk resolves to Solid's PRODUCTION browser build.
+// `Bun.build({ target: 'browser' })` always adds the `development` export condition and offers no
+// option that removes it — `conditions`, `production`, `env` and `define` were each measured under
+// Bun 1.4 and none of them does — so without this seam an island ships the dev bundle silently.
+
+// `node:path` by necessity: Bun ships no path API, and this file resolves a package entry back
+// to the directory its `exports` map is relative to.
+import { dirname, join } from 'node:path';
+import type { BunPlugin } from 'bun';
+import { IslandBuildFailedError } from './errors';
+
+/**
+ * The conditions an island's `solid-js` subpath is resolved under. `development` is the one NOT in
+ * the set, which is the whole point of the file; `production` is in it because an island chunk is
+ * only ever built to be shipped — `x dev` serves the same chunk the container does, so a second
+ * answer here would be a bundle the byte budget never measured.
+ */
+const ISLAND_CONDITIONS: ReadonlySet<string> = new Set([
+  'production',
+  'browser',
+  'module',
+  'import',
+  'default',
+]);
+
+/** `solid-js` and its subpaths, and nothing else: Solid is the runtime an island is compiled for. */
+const SOLID_SPECIFIER = /^solid-js(?:\/|$)/;
+
+/**
+ * Node's conditional-exports walk, restricted to what this file needs: the first key of the object
+ * that the build's condition set contains, depth-first, with an array as an ordered fallback list.
+ * Written out rather than delegated to `Bun.resolveSync` because the ONE thing it has to do
+ * differently from Bun's resolver is refuse `development` — and `types` with it, which would
+ * otherwise win on Solid's map and hand the bundler a `.d.ts`.
+ */
+export function selectCondition(node: unknown, conditions: ReadonlySet<string>): string | null {
+  if (typeof node === 'string') return node;
+  if (Array.isArray(node)) {
+    for (const alternative of node as readonly unknown[]) {
+      const picked = selectCondition(alternative, conditions);
+      if (picked !== null) return picked;
+    }
+    return null;
+  }
+  if (typeof node !== 'object' || node === null) return null;
+  for (const [condition, value] of Object.entries(node)) {
+    if (!conditions.has(condition)) continue;
+    const picked = selectCondition(value, conditions);
+    if (picked !== null) return picked;
+  }
+  return null;
+}
+
+/** One parse per manifest: an island imports Solid from several files, and every file asks again. */
+const exportsCache = new Map<string, unknown>();
+
+async function exportsOf(manifest: string): Promise<unknown> {
+  const hit = exportsCache.get(manifest);
+  if (hit !== undefined || exportsCache.has(manifest)) return hit;
+  const parsed: unknown = JSON.parse(await Bun.file(manifest).text());
+  const field =
+    typeof parsed === 'object' && parsed !== null && 'exports' in parsed
+      ? (parsed as { readonly exports?: unknown }).exports
+      : undefined;
+  exportsCache.set(manifest, field);
+  return field;
+}
+
+/** Test seam: the cache is process-global because `x dev` rebuilds in one process. */
+export function clearSolidExportsCache(): void {
+  exportsCache.clear();
+}
+
+/**
+ * The absolute file `specifier` must resolve to, or `null` for "Bun's own answer is already the
+ * right one" — which is every subpath Solid declares as a plain string or a pattern, since a
+ * declaration with no conditions on it cannot select the development build.
+ */
+export async function solidProductionEntry(
+  specifier: string,
+  resolveDir: string,
+  importer: string,
+): Promise<string | null> {
+  let manifest: string;
+  try {
+    // `solid-js/package.json` is an `exports` entry of Solid's own map, so this reaches the exact
+    // copy the island would have imported — not a hoisted sibling at a different version.
+    manifest = Bun.resolveSync('solid-js/package.json', resolveDir);
+  } catch {
+    // Solid is not installed here. Bun's resolver says so, in its own words, naming the importer.
+    return null;
+  }
+  const field = await exportsOf(manifest);
+  const subpath = specifier === 'solid-js' ? '.' : `.${specifier.slice('solid-js'.length)}`;
+  if (typeof field !== 'object' || field === null || !(subpath in field)) return null;
+
+  const entry = selectCondition((field as Record<string, unknown>)[subpath], ISLAND_CONDITIONS);
+  const file = entry === null ? null : join(dirname(manifest), entry);
+  if (file === null || !(await Bun.file(file).exists())) {
+    throw new IslandBuildFailedError({
+      file: importer.length > 0 ? importer : specifier,
+      logs:
+        `${specifier} has no production browser entry: ${manifest} answers ` +
+        `${entry === null ? 'nothing' : JSON.stringify(entry)} under ` +
+        `[${[...ISLAND_CONDITIONS].join(', ')}], and an island may not ship Solid's ` +
+        'development build',
+    });
+  }
+  return file;
+}
+
+/**
+ * The plugin `island-bundle.ts` hands `Bun.build`, beside `solidJsxPlugin`. Stateless apart from
+ * the manifest cache, so one frozen descriptor serves every concurrent island build.
+ *
+ * The absolute path it answers with no longer matches `SOLID_SPECIFIER`, so Solid's own internal
+ * `import … from 'solid-js'` is the only re-entry — and that one is wanted: it is how `web.js`
+ * reaches `solid.js` rather than `dev.js`.
+ */
+export const solidProductionPlugin: BunPlugin = {
+  name: 'ultimate-island-solid-production',
+  setup(build): void {
+    build.onResolve({ filter: SOLID_SPECIFIER }, async ({ path, importer, resolveDir }) => {
+      const from = resolveDir.length > 0 ? resolveDir : dirname(importer);
+      const entry = await solidProductionEntry(path, from, importer);
+      return entry === null ? undefined : { path: entry };
+    });
+  },
+};

package/src/island-styles.ts

@@ -0,0 +1,41 @@
+// The stylesheet half of an island build: `import styles from './x.module.scss'` answers the class
+// map the SERVER hashed, and the CSS lands in the same registry a document renders from. Bun's
+// default loader answers the asset PATH — a string — so `styles['track']` is `undefined`, every
+// element renders unclassed, and `Bun.build` reports `success: true` with no log.
+
+import { renderThrowable, UltimateError } from '@ultimat3/core';
+import { loadStylesheet } from '@ultimat3/render';
+import type { BunPlugin } from 'bun';
+import { IslandBuildFailedError } from './errors';
+
+/**
+ * The same spelling `installRenderLoader` filters on, so there is ONE answer to "what is a
+ * stylesheet import" across the server loader and the island bundler. A plain `.css`/`.scss` is in
+ * deliberately: it compiles to an empty class map and registers its rules, which is what a global
+ * stylesheet an island imports has to do.
+ */
+const STYLESHEET = /\.s?css$/;
+
+/**
+ * `loadStylesheet`, not `compileStylesheet`: compiling alone answers the class names and drops the
+ * RULES on the floor, and an island is the one importer a document's own module graph never sees.
+ * Registering here is what puts them in `stylesFor(surface)` — `buildIslands` runs before the first
+ * document is rendered, in `x dev` and in `prerenderSite` alike.
+ */
+export const islandStylesPlugin: BunPlugin = {
+  name: 'ultimate-island-styles',
+  setup(build): void {
+    build.onLoad({ filter: STYLESHEET }, async ({ path }) => {
+      const source = await Bun.file(path).text();
+      try {
+        return { contents: loadStylesheet(path, source), loader: 'js' };
+      } catch (error) {
+        // A coded failure already names the file and carries a fix — re-wrapping it would bury
+        // both. Anything else is rendered through `renderThrowable`, because this is the plugin's
+        // last frame and a value that fights being read would escape a Bun plugin as a bare throw.
+        if (error instanceof UltimateError) throw error;
+        throw new IslandBuildFailedError({ file: path, logs: renderThrowable(error) });
+      }
+    });
+  },
+};

package/src/mcp-errors.ts

@@ -48,6 +48,15 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_JOB_UNKNOWN: 'x jobs ls --json',
   X_FIX_TARGET_UNKNOWN: 'x fix boundary apps/web/site/page.tsx --json',
   X_ERROR_FIX_INVALID: 'x verify --json   # the finding names the file, the line and the fix text',
+  X_WORKSPACE_DEP_UNDECLARED:
+    'x verify --json   # the package-shape finding carries the dependency line to add',
+  X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
+  X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
+  X_GH_NOT_AUTHENTICATED: 'gh auth login',
+  X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',
+  X_GH_RESPONSE_INVALID: 'x pr review --json   # the finding names the field that did not parse',
+  X_PR_NOT_FOUND: 'x pr review --pr 1 --json   # or open one first with: gh pr create',
+  X_CI_RUN_NOT_FOUND: 'x ci --branch main --json',
   X_ERROR_CODE_UNDOCUMENTED: 'x verify --json   # the finding names the code and the missing page',
   X_ERROR_CODE_UNREGISTERED:
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',

package/src/messages.ts

@@ -159,7 +159,71 @@ const CATALOG = {
   'cli.routes.empty': 'no routes in the manifest — run `x manifest` first',
   'cli.tasks.count': '{count} task(s)',
   'cli.tasks.shown': '{name} — {cron} ({tz}), next {next}',
+  'cli.affected.count':
+    '{count} workspace(s) affected by {base}...HEAD, from {changed} changed file(s)',
+  'cli.affected.dirty':
+    '  including the working tree (--dirty): every uncommitted change in this checkout, whoever made it',
+  'cli.affected.none': 'no workspace is affected by {base}...HEAD, from {changed} changed file(s)',
+  'cli.affected.rootWide':
+    '  every workspace: {files} belongs to none of them and changes what all of them compile',
+  // `x shot` — the picture is the `lines`, the verdict is the artifact. The summary names the
+  // GATING fact, and a redirect comes first: a photograph of the sign-in page with every island
+  // missing reads as a bug in the app, and it is a bug in the capture.
+  'cli.shot.ok': '{route} clean — {islands} island(s) mounted, nothing logged and nothing threw',
+  'cli.shot.errors': '{route}: {errors} console error(s) — verdict.json names each one',
+  'cli.shot.redirected': '{route} redirected to {url} — the picture is not the route asked for',
+  'cli.shot.server.booted': '  server   booted for this shot on {url}',
+  'cli.shot.server.reused': '  server   the x dev already running on {url}',
+  'cli.shot.canvas': '  canvas   {width}x{height}',
+  'cli.shot.canvasUnreadable': '  canvas   unreadable — {bytes} byte(s), not a decodable image',
+  'cli.shot.islands': '  islands  {booted} of {declared} mounted ({strategies})',
+  'cli.shot.islandsUnknown': '  islands  not counted — the page answered no probe',
+  'cli.shot.network': '  network  {requests} request(s), {refused} refused, {dropped} dropped',
+  'cli.shot.console': '  console  {level}: {text}',
+  'cli.shot.threw': '{route}: {thrown} uncaught exception(s) — {first}',
+  'cli.shot.pageError': '  threw    {message}  {at}',
+  'cli.shot.picture': '  picture  {path}',
+  'cli.shot.verdict': '  verdict  {path}',
+  'cli.shot.blind.status':
+    'HTTP response status is not observed — the port records requests, never responses',
+  'cli.ci.failed':
+    '{failed} of {runs} workflow run(s) on {branch} failed — {findings} finding(s) recovered from the log',
+  'cli.ci.green': 'every one of {runs} workflow run(s) on {branch} passed',
+  'cli.ci.job': '  {conclusion}  {job}  ({steps})',
+  'cli.ci.jobs.other': '  {count} other job(s) in this run',
+  'cli.ci.logs.empty': '  the failed step wrote no log — {url}',
+  /** The conclusion of a run GitHub has not finished — a value, not a column key. */
+  'cli.ci.pending': 'pending',
+  'cli.ci.run': '{conclusion}  {workflow}  {url}',
+  'cli.ci.running':
+    '{running} of {runs} workflow run(s) on {branch} has not finished — nothing has failed yet',
+  'cli.ci.tail': '  log tail, {job}:',
+  'cli.pr.body.truncated': '      … {hidden} more line(s) — re-run with --full',
+  /** The line of a thread whose anchor GitHub answers null for — a value, not a column key. */
+  'cli.pr.line.unknown': '-',
+  'cli.pr.replied': 'replied on thread {id}: {url}',
+  // Resolving closes a CONVERSATION. Whether the finding is fixed is a fact about the code that
+  // no GitHub mutation observes, and a summary saying "addressed" would assert one from the other.
+  'cli.pr.resolved':
+    'thread {id} is marked resolved on GitHub — that records the conversation, not that the finding is fixed',
+  'cli.pr.review.count':
+    '{unresolved} unresolved and {resolved} resolved review thread(s) on {repo}#{pr}',
+  'cli.pr.review.current': '  submitted against the current head {head}',
+  'cli.pr.review.decision': '  review: {decision} by {author} at {submitted}',
+  'cli.pr.review.none': 'no review thread is anchored to a line on {repo}#{pr}',
+  'cli.pr.review.stale':
+    '  submitted against {commit}; the head is now {head} ({committed}) — this decision predates the current code',
+  'cli.pr.review.truncated':
+    '  more than {count} threads — this is the first page, not the whole review',
+  'cli.pr.review.undecided': '  GitHub reports no review decision yet',
+  'cli.pr.thread.closed': '  resolved    {path}:{line}  {id}',
+  'cli.pr.thread.comment': '    {author} at {createdAt}',
+  'cli.pr.thread.more': '    {hidden} more comment(s) on this thread',
+  'cli.pr.thread.open': '  unresolved  {path}:{line}  {id}',
+  'cli.pr.thread.outdated':
+    '    the diff has moved under this thread — {line} is where the comment was written',
   'cli.test.fail': '{failed} of {workers} shard(s) failed',
+  'cli.test.affected.none': 'nothing is affected by {base}...HEAD — 0 test file(s) ran',
   'cli.test.pass': '{files} test file(s) on {workers} worker(s) passed in {ms}ms',
   'cli.test.sampled': 'sampled {kept} of {total} {type} file(s)',
   'cli.test.type.fail': '{type} — {failed} of {workers} shard(s) failed',

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;
+}