@ultimat3/cli 6.0.0 → 8.0.0

package/src/drift.ts

@@ -11,7 +11,9 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { describeEntities } from '@ultimat3/entity';
 import { countDeclaredEntities } from './app-entities';
+import { loadApp } from './app-load';
 // One declaration of where migrations live, and it belongs to the module that reads them —
 // `x db migrate` and this sidecar must never disagree about the directory they share.
 import { hashFileName, MIGRATIONS_DIR } from './migrations';
@@ -20,7 +22,48 @@ import type { Finding } from './output';
 export const DB_PACKAGE = join('packages', 'db');
 const SCHEMA_GLOB = 'packages/db/src/**/*.ts';
 
-/** Content hash of the whole schema, order-independent per file path. */
+/**
+ * Canonical JSON: object keys sorted, arrays in their own order. The registry's description is a
+ * BUILD INPUT committed to disk as a hash, so a field reordered inside `describe()` upstream would
+ * otherwise move every app's hash and report drift over a framework upgrade nobody made.
+ */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+      a < b ? -1 : a > b ? 1 : 0,
+    );
+    return `{${entries.map(([key, held]) => `${JSON.stringify(key)}:${canonicalJson(held)}`).join(',')}}`;
+  }
+  // `undefined` has no JSON form and an optional field left unset must hash as absent, not throw.
+  return JSON.stringify(value) ?? 'null';
+}
+
+/**
+ * What the app's entities declare, as the registry describes them — the half `SCHEMA_GLOB` cannot
+ * see. `x new` puts an entity at `apps/web/app/<feature>/entity.ts` and `packages/db/src/schema.ts`
+ * merely re-exports it, so a column added there moved NO byte the glob reads: three generated
+ * entities and one migration reported clean, with every `.hash` sidecar identical. The registry is
+ * the same fact `x db gen` diffs (`describeEntities()`), so the check and the generator now read
+ * one schema instead of two.
+ *
+ * `loadApp` is what fills that registry, and it is called on every path rather than only where the
+ * caller happens to have loaded already: a hash computed against an EMPTY registry would differ
+ * from the one `x db gen` recorded with the app loaded, and every app would read as drifted.
+ * A module that will not import leaves the registry SHORT rather than raising — the stance
+ * `countDeclaredEntities` already documents — so `x doctor` still answers on the app it diagnoses.
+ */
+async function declaredSchemaJson(root: string): Promise<string> {
+  await loadApp(root);
+  return canonicalJson(describeEntities());
+}
+
+/**
+ * Content hash of the whole schema: the entity registry first, then every non-test file under
+ * `packages/db/src`, order-independent per file path. Both halves, because they answer different
+ * questions — the registry is what reaches the database, and the glob is what catches a seed or a
+ * helper moving under it (which is what `reconcileSchemaHash` exists to re-record).
+ */
 export async function schemaHash(root: string): Promise<string> {
   const glob = new Bun.Glob(SCHEMA_GLOB);
   const paths: string[] = [];
@@ -29,6 +72,7 @@ export async function schemaHash(root: string): Promise<string> {
   }
   paths.sort();
   const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(await declaredSchemaJson(root));
   for (const path of paths) {
     hasher.update(path);
     hasher.update(await Bun.file(join(root, path)).text());
@@ -77,9 +121,10 @@ export interface HashReconciliation {
 }
 
 /**
- * Re-record the sidecar for a migration that is already the right one. `SCHEMA_GLOB` covers every
- * non-test file under `packages/db/src`, not only the ones that imply DDL, so editing a seed or a
- * helper moves the hash with no diff behind it — and `X_DB_DRIFT`'s `fix:` has to have somewhere to
+ * Re-record the sidecar for a migration that is already the right one. Neither half of the hash is
+ * DDL-only — `SCHEMA_GLOB` covers every non-test file under `packages/db/src`, and the registry
+ * carries invariants and tags a diff can leave empty — so an edit can move the hash with no
+ * statement behind it, and `X_DB_DRIFT`'s `fix:` has to have somewhere to
  * land or the instruction is unfollowable. The caller owes the proof that the DDL genuinely did not
  * move (`db-generate.ts` reaches this only on an empty diff off a fully loaded registry); this
  * function decides only whether a write is needed.
@@ -107,9 +152,9 @@ export type DeclaredEntityCount = () => Promise<number>;
  * Empty result = no drift. A missing db package is not drift (an app may have no database yet);
  * a schema with no migration at all is — *provided* the app declares an entity for one to record.
  *
- * The entity count is read lazily and ONLY in that first branch, so an app past its first migration
- * pays nothing for it: every other path answers from file hashes alone, with no app load and no
- * database, which is what lets the gate run this in a CI with neither.
+ * The entity count is read lazily and ONLY in that first branch; the hash itself loads the app on
+ * every path, because the registry is half of what it covers. Still no database anywhere here,
+ * which is what lets the gate run this in a CI with nothing listening.
  */
 export async function checkSourceDrift(
   root: string,

package/src/error-codes.ts

@@ -56,6 +56,10 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_ROLE_UNKNOWN',
   'X_PORT_INVALID',
   'X_DEV_ALREADY_RUNNING',
+  // The OTHER thing the preflight can find, and it was reported as the one above: an unreadable
+  // lock this process could not remove made `DevAlreadyRunningError` name THIS pid as the holder,
+  // so the remedy printed was `kill <self>` — unrunnable, and a cause that was simply untrue.
+  'X_DEV_LOCK_UNREADABLE',
   // The boot's own consistency check. `startServices` captures the drivers it built, and
   // `loadApp` runs AFTER it — so an app module calling `setJobDriver(theirs)` moved the ambient
   // slot and left the captured object alone: every `handle.enqueue()` went to their queue while
@@ -96,6 +100,14 @@ export const CLI_OWNED_ERROR_CODES = [
   // CLI's problem alone, and core would have no `fix:` to offer for one.
   'X_SECRETS_EDITOR_MISSING',
   'X_SECRETS_EDIT_FAILED',
+  'X_WORKSPACE_DEP_UNDECLARED',
+  'X_SHOT_BROWSER_MISSING',
+  'X_GH_UNAVAILABLE',
+  'X_GH_NOT_AUTHENTICATED',
+  'X_GH_COMMAND_FAILED',
+  'X_GH_RESPONSE_INVALID',
+  'X_PR_NOT_FOUND',
+  'X_CI_RUN_NOT_FOUND',
 ] as const;
 
 /**
@@ -169,6 +181,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ROLE_UNKNOWN: 'ROLE names something that is not a role',
   X_PORT_INVALID: 'PORT is not a TCP port number',
   X_DEV_ALREADY_RUNNING: 'another x dev already owns this checkout',
+  X_DEV_LOCK_UNREADABLE: 'the dev lock file cannot be read or removed',
   X_RUNTIME_DRIVER_SPLIT: 'the ambient driver is not the one this process serves',
   X_GENERATE_CONFLICT: 'a generator would overwrite a file',
   X_PORT_IN_USE: 'the dev port is taken',
@@ -188,6 +201,14 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_CLI_FLAG_UNREAD: 'a command declares a flag no code reads',
   X_SECRETS_EDITOR_MISSING: 'no $EDITOR to open the decrypted secrets in',
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
+  X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
+  X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
+  X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
+  X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
+  X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',
+  X_GH_RESPONSE_INVALID: "gh's output is not the shape the command reads",
+  X_PR_NOT_FOUND: 'no pull request for this checkout',
+  X_CI_RUN_NOT_FOUND: 'no workflow run for this branch',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/framework-scope.ts

@@ -4,9 +4,10 @@
 // directory or they describe different builds.
 
 // `node:fs`/`node:path` because Bun ships neither: `dirname` walks a resolved module up to the
-// directory that owns it, and `existsSync` is what says which directory that is.
+// directory that owns it, `basename` names the two segments the store layout is recognised by,
+// and `existsSync` is what says which directory is really there.
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 
 /**
  * Deep enough for `src/index.ts` and for any entry an `exports` map could point at, shallow enough
@@ -14,6 +15,45 @@ import { dirname, join } from 'node:path';
  */
 const MAX_DEPTH = 6;
 
+/** The two segments Bun's isolated layout is recognised by: `node_modules/.bun/<pkg>@<version>/`. */
+const STORE_DIR = '.bun';
+const NODE_MODULES = 'node_modules';
+
+/**
+ * `node_modules/.bun/@ultimat3+core@7.0.0/node_modules/@ultimat3` → `node_modules/@ultimat3`.
+ *
+ * Bun's **isolated** layout gives every package its own store entry, and a store entry's scope
+ * directory holds exactly the one package it was created for. `Bun.resolveSync` follows the
+ * install's symlink into that store, so walking up from the resolved entry lands there rather
+ * than in the tree an app actually installed: measured on a fixture install, `x docs` saw
+ * **1** of 6 packages, and `x errors explain` answered *"nothing in the installed framework raises
+ * X_…"* — with `ok: true` — for 400 of 405 codes. A confident wrong answer, from a walk that had
+ * never looked at the app's own `node_modules`.
+ *
+ * The store is recognised by its own shape and never by an app root handed in from outside: the
+ * two callers here are a module-scope memo (`error-fixes.ts`) and a command that may run under
+ * `--cwd`, so a cwd-derived root would be wrong for one of them and absent for the other.
+ *
+ * `undefined` — leaving the caller on the resolved answer — whenever this is not a store path or
+ * the sibling scope directory is not there. A hoisted install already resolves to
+ * `node_modules/@ultimat3/core` and a workspace checkout to `packages/core`, and neither has a
+ * `.bun` above it.
+ */
+function installedScopeFor(storeScope: string): string | undefined {
+  const scopeName = basename(storeScope);
+  let dir = storeScope;
+  for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    if (basename(dir) === STORE_DIR && basename(parent) === NODE_MODULES) {
+      const candidate = join(parent, scopeName);
+      return existsSync(candidate) ? candidate : undefined;
+    }
+    dir = parent;
+  }
+  return undefined;
+}
+
 /**
  * Resolved from the CLI's own dependency on `@ultimat3/core` rather than from the user's cwd:
  * these are the packages this `x` would actually run. Resolution follows the symlink, so a
@@ -29,18 +69,30 @@ const MAX_DEPTH = 6;
  * framework raises the code. Walking up from the entry to the directory that owns its
  * `package.json` depends on nothing but the entry that is already imported.
  *
+ * Following the symlink is also what makes the last step necessary rather than optional: under
+ * Bun's isolated layout the entry resolves *into the store*, whose scope directory holds one
+ * package. `installedScopeFor` is the correction, and it is a shape test on the path — never a
+ * `readdir` of the resolved package's parent, which is the read that reported one package as the
+ * whole framework.
+ *
+ * `resolveFrom` exists so a test can point this at a fixture install; nothing passes it in
+ * production, where the only defensible base is this module's own directory.
+ *
  * `undefined` means the CLI cannot see its own dependency, which is a broken install and not
  * merely an undocumented one; every caller reports that rather than answering emptily.
  */
-export function frameworkScopeDir(): string | undefined {
+export function frameworkScopeDir(resolveFrom: string = import.meta.dir): string | undefined {
   let dir: string;
   try {
-    dir = dirname(Bun.resolveSync('@ultimat3/core', import.meta.dir));
+    dir = dirname(Bun.resolveSync('@ultimat3/core', resolveFrom));
   } catch {
     return undefined;
   }
   for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
-    if (existsSync(join(dir, 'package.json'))) return dirname(dir);
+    if (existsSync(join(dir, 'package.json'))) {
+      const scope = dirname(dir);
+      return installedScopeFor(scope) ?? scope;
+    }
     const parent = dirname(dir);
     if (parent === dir) return undefined;
     dir = parent;

package/src/generate-kinds.ts

@@ -2,6 +2,7 @@
 // because "what a generator emits" and "which spelling reaches it" are two jobs — and the file
 // that held both had reached the 500-line ceiling, one generator short of failing its own gate.
 
+import { nearestName } from '@ultimat3/core';
 import { BadFlagError, MissingPositionalError, UnknownCommandError } from './errors';
 import type { Surface } from './templates';
 
@@ -42,13 +43,30 @@ export function assertSurfaceSupported(kind: Generator, surface: Surface, name:
   });
 }
 
+/**
+ * The generator a spelling reaches, or a refusal that leads with the one it is nearest.
+ *
+ * The lead used to be the literal `g resource`, whatever was typed: `x g rout x` — one edit from
+ * `route` — answered `fix: x g resource`, the WRONG PRIMITIVE, and one that refuses in turn
+ * because it carries no `<name>`. `nearestName` is what `parse.ts` already does with a mistyped
+ * command, over this file's own list.
+ *
+ * Two rules hold the fix line to a command that runs. A near miss is completed with that
+ * generator's own `EXAMPLE_NAME`, because `x g route <name>` pasted into a shell is a redirect.
+ * A word near NOTHING gets `x help g` rather than an invented lead — the same rule `parse.test.ts`
+ * pins for a command that resembles nothing, and the reason `nearestName` is never asked about an
+ * ABSENT kind: the empty string is within the cutoff of `job`, so `x g` would "suggest" a
+ * generator nobody typed.
+ */
 export function readKind(raw: string | undefined): Generator {
   const kinds: readonly string[] = GENERATORS;
   if (raw !== undefined && kinds.includes(raw)) return raw as Generator;
+  const near = raw === undefined ? undefined : nearestName(raw, kinds);
+  const suggestion = GENERATORS.find((kind) => kind === near);
   throw new UnknownCommandError({
     path: `g ${raw ?? ''}`.trim(),
     known: GENERATORS,
-    suggestion: 'g resource',
+    suggestion: suggestion === undefined ? 'help g' : `g ${suggestion} ${EXAMPLE_NAME[suggestion]}`,
   });
 }
 

package/src/gh-target.ts

@@ -0,0 +1,118 @@
+// Which repository, which pull request, which branch — the three facts `x pr` and `x ci` both
+// need before they can ask GitHub anything, resolved once here so the two commands can never
+// disagree about what "this checkout" means.
+
+import { UltimateError } from '@ultimat3/core';
+import { t } from '@ultimat3/schema';
+import { BadFlagError } from './errors';
+import type { GhHost } from './gh';
+import { GhFailedError, ghJson } from './gh';
+
+/** `owner/name`, split once so a caller never re-splits it and never re-joins it wrong. */
+export interface GhRepo {
+  readonly owner: string;
+  readonly name: string;
+  /** The `owner/name` spelling, which is what `--repo` takes and what every render prints. */
+  readonly slug: string;
+}
+
+/**
+ * A repository name is `[A-Za-z0-9._-]+` on both sides of one slash. Refused here rather than by
+ * GitHub, because `--repo` is the one field a caller types by hand: `--repo ultimate` reaches the
+ * API as an owner with no name and comes back `Could not resolve to a Repository`, which reads as
+ * "that repository is gone" rather than "that is not a repository reference".
+ */
+const SLUG = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+const REPO_VIEW = t.object({ nameWithOwner: t.string });
+
+/** No pull request for the branch this checkout is on. A number the caller knows closes it. */
+export class PrNotFoundError extends UltimateError {
+  constructor(input: { detail: string }) {
+    super({
+      code: 'X_PR_NOT_FOUND',
+      cause: `GitHub reports no pull request for this checkout: ${input.detail}`,
+      fix: 'x pr review --pr 241 --json   # or open one first with: gh pr create',
+    });
+  }
+}
+
+/**
+ * The repository this command is about. `--repo` when given, otherwise `gh repo view`, which
+ * resolves the same remote `gh pr` and `gh run` resolve — asking git for the remote here would be
+ * a second answer to a question gh already owns.
+ */
+export async function resolveRepo(
+  host: GhHost,
+  command: string,
+  flag: string | undefined,
+): Promise<GhRepo> {
+  if (flag !== undefined) {
+    if (!SLUG.test(flag)) {
+      throw new BadFlagError({
+        flag: 'repo',
+        command,
+        reason: `"${flag}" is not an owner/name repository reference`,
+        fix: `x ${command} --repo developerz-ai/ultimate --json`,
+      });
+    }
+    return repoOf(flag);
+  }
+  const viewed = await ghJson(host, ['repo', 'view', '--json', 'nameWithOwner'], REPO_VIEW, {
+    label: 'gh repo view',
+    fix: `x ${command} --repo developerz-ai/ultimate --json`,
+  });
+  return repoOf(viewed.nameWithOwner);
+}
+
+function repoOf(slug: string): GhRepo {
+  const [owner = '', name = ''] = slug.split('/');
+  return { owner, name, slug };
+}
+
+const PR_VIEW = t.object({ number: t.number });
+
+/**
+ * The pull request for the current branch. gh exits non-zero when there is none, with a message
+ * that names the branch — so the refusal keeps gh's own sentence and adds the remedy gh has no
+ * opinion about: name the number, or open the PR.
+ */
+export async function resolvePrNumber(host: GhHost, repo: GhRepo): Promise<number> {
+  try {
+    const viewed = await ghJson(
+      host,
+      ['pr', 'view', '--repo', repo.slug, '--json', 'number'],
+      PR_VIEW,
+      { label: 'gh pr view', fix: 'x pr review --pr 241 --json' },
+    );
+    return viewed.number;
+  } catch (error) {
+    if (error instanceof GhFailedError) throw new PrNotFoundError({ detail: error.cause });
+    throw error;
+  }
+}
+
+/**
+ * The branch this checkout is on, from git rather than from gh: gh has no "current branch"
+ * question, only commands that answer one for you. A detached HEAD answers `HEAD`, which matches
+ * no branch on GitHub — the caller's own "no run for this branch" refusal names `--branch`, so a
+ * second refusal here would only move the same instruction one step earlier.
+ *
+ * Spawn failures are deliberately NOT caught: `exec.ts` refuses a missing program with a fix that
+ * already names `git`, and re-labelling that as a GitHub problem would send the reader to the
+ * wrong install.
+ */
+export async function currentBranch(host: GhHost): Promise<string> {
+  const result = await host.runner(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: host.cwd,
+  });
+  if (!result.ok) {
+    throw new GhFailedError({
+      label: 'git rev-parse --abbrev-ref HEAD',
+      code: result.code,
+      detail: result.stderr.split('\n')[0]?.trim() ?? '',
+      fix: 'x ci --branch main --json',
+    });
+  }
+  return result.stdout.trim();
+}

package/src/gh.ts

@@ -0,0 +1,204 @@
+// The one seam between the CLI and the `gh` binary. Every GitHub call is built here and spawned
+// through the injected `Runner`, so a test asserts the exact argv with no network and no `gh`
+// installed — and the four ways this shell-out fails (no binary, no credentials, a non-zero exit,
+// an answer that will not parse) each get one code and one executable fix instead of a stack trace.
+
+import { renderThrowable, singleLine, UltimateError } from '@ultimat3/core';
+import type { AnySchema, InferOutput } from '@ultimat3/schema';
+import { formatPath } from '@ultimat3/schema';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+
+/** What a gh call needs from a `CommandContext`, and nothing more — so a test passes two fields. */
+export interface GhHost {
+  readonly runner: Runner;
+  readonly cwd: string;
+}
+
+export interface GhOptions {
+  /**
+   * A short name for this call. Every refusal is titled with it rather than with the argv,
+   * because a GraphQL document pasted into a `cause:` is a page of text where a reader needs a
+   * sentence.
+   */
+  readonly label: string;
+  /**
+   * The caller's remedy, and REQUIRED: the seam knows a call failed and never what the operator
+   * was trying to do, so a generic fix here would be axiom 4 inverted at the one boundary every
+   * GitHub call crosses. Making it a field of the options is what turns "state a remedy" into a
+   * build error rather than a convention.
+   */
+  readonly fix: string;
+}
+
+/** The one binary this file spawns. Named once, so every argv assertion has a single source. */
+export const GH_BIN = 'gh';
+
+/**
+ * No `gh` on PATH. `exec.ts` already refuses a missing program with `X_CLI_UNEXPECTED`, and that
+ * code's fix names the binary — but "the CLI itself failed" is the wrong sentence for a machine
+ * that simply has no GitHub client, and `gh auth login` is not reachable from it.
+ */
+export class GhUnavailableError extends UltimateError {
+  constructor(input: { cwd: string; detail: string }) {
+    super({
+      code: 'X_GH_UNAVAILABLE',
+      cause: `the GitHub CLI could not be run from ${input.cwd}: ${input.detail}`,
+      fix: 'install the GitHub CLI from https://cli.github.com, then run: gh auth login',
+    });
+  }
+}
+
+/** `gh` is installed and holds no usable credentials for this host. One command closes it. */
+export class GhNotAuthenticatedError extends UltimateError {
+  constructor(input: { label: string; detail: string }) {
+    super({
+      code: 'X_GH_NOT_AUTHENTICATED',
+      cause: `${input.label} was refused by GitHub: ${input.detail}`,
+      fix: 'gh auth login',
+    });
+  }
+}
+
+/** Any other non-zero exit — a bad id, a repository that is not there, a rate limit. */
+export class GhFailedError extends UltimateError {
+  constructor(input: { label: string; code: number; detail: string; fix: string }) {
+    super({
+      code: 'X_GH_COMMAND_FAILED',
+      cause: `${input.label} exited ${input.code}: ${input.detail}`,
+      fix: input.fix,
+    });
+  }
+}
+
+/**
+ * `gh` answered, and the answer is not the shape this command reads. A cast would carry the
+ * mismatch into the render and print `undefined` at whichever field moved; the parse refuses at
+ * the boundary instead, which is the only place the argv that produced it is still known.
+ */
+export class GhResponseInvalidError extends UltimateError {
+  constructor(input: { label: string; detail: string; fix: string }) {
+    super({
+      code: 'X_GH_RESPONSE_INVALID',
+      cause: `${input.label} answered something this command cannot read: ${input.detail}`,
+      fix: input.fix,
+    });
+  }
+}
+
+/**
+ * The spellings `gh` uses when the token is the problem. Matched against its own output rather
+ * than against an exit code, because every one of these exits 1 exactly like a typo'd id does —
+ * and the two have different remedies.
+ */
+const UNAUTHENTICATED =
+  /not logged in|gh auth login|HTTP 401|Bad credentials|GH_TOKEN|GITHUB_TOKEN|authentication/i;
+
+/** The first line a human would read, escaped and bounded — a `cause:` is one line by contract. */
+export function ghDetail(result: ExecResult): string {
+  const merged = execOutput(result);
+  const first = merged.split('\n').find((line) => line.trim().length > 0) ?? '';
+  const text = singleLine(first.trim().replace(/^gh:\s*/, ''));
+  return text.length > 200 ? `${text.slice(0, 200)}…` : text;
+}
+
+/**
+ * One `gh` invocation, refused four ways. A spawn failure is mapped rather than rethrown: it is
+ * the "no GitHub CLI on this machine" case, and `exec.ts`'s own refusal cannot offer `gh auth
+ * login` as the next step.
+ */
+export async function runGh(
+  host: GhHost,
+  args: readonly string[],
+  options: GhOptions,
+): Promise<ExecResult> {
+  let result: ExecResult;
+  try {
+    result = await host.runner([GH_BIN, ...args], { cwd: host.cwd });
+  } catch (error) {
+    // Never interpolated: the thrown value is genuinely unknown here (Bun raises `ENOENT` for a
+    // missing program and `EACCES` for an unrunnable one), which is what `bun run error-render`
+    // refuses to see reach a `cause:` through `${…}`.
+    throw new GhUnavailableError({ cwd: host.cwd, detail: renderThrowable(error) });
+  }
+  if (result.ok) return result;
+  const detail = ghDetail(result);
+  if (UNAUTHENTICATED.test(detail)) {
+    throw new GhNotAuthenticatedError({ label: options.label, detail });
+  }
+  throw new GhFailedError({ label: options.label, code: result.code, detail, fix: options.fix });
+}
+
+/**
+ * `gh --json`, parsed rather than cast. The response is untrusted input — a different `gh`
+ * version, a proxy that answered HTML, a field GitHub renamed — so it goes through the schema the
+ * caller declared and a mismatch is a coded refusal naming the call that produced it.
+ */
+export async function ghJson<S extends AnySchema>(
+  host: GhHost,
+  args: readonly string[],
+  schema: S,
+  options: GhOptions,
+): Promise<InferOutput<S>> {
+  const result = await runGh(host, args, options);
+  let payload: unknown;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch (error) {
+    throw new GhResponseInvalidError({
+      label: options.label,
+      detail: renderThrowable(error),
+      fix: options.fix,
+    });
+  }
+  const parsed = schema.safeParse(payload);
+  if (parsed.issues !== undefined) {
+    const first = parsed.issues[0];
+    // `formatPath` is the schema package's own renderer for an issue path — a second spelling of
+    // `items[0].price` here would be a field name that does not match the one every other
+    // validation failure in the framework prints.
+    throw new GhResponseInvalidError({
+      label: options.label,
+      detail:
+        first === undefined
+          ? 'the response matched no field this command declares'
+          : `${formatPath(first.path)} ${first.message}`.trim(),
+      fix: options.fix,
+    });
+  }
+  return parsed.value as InferOutput<S>;
+}
+
+/**
+ * A GraphQL call, and the two `gh` field flags are not interchangeable — the type of the variable
+ * decides which one is correct, so the type of the value decides here.
+ *
+ * A **string** rides as `-f`, never `-F`: `-F` reads `@file` as "load this from disk", so a review
+ * reply whose body begins with an `@` would post the contents of a local file. A **number** has to
+ * ride as `-F`, because `-f` sends every value as a GraphQL `String` and a `$n:Int!` parameter
+ * refuses one (measured: `gh api graphql … -f n=238` against `Int!` is a `variableNotUsed`/type
+ * error, `-F n=238` succeeds). `-F` is safe for a number precisely because a number can never
+ * spell `@file`.
+ *
+ * The caller's schema describes the WHOLE envelope (`{ data: … }`) rather than its inside: gh
+ * exits non-zero whenever the response carries `errors`, so a partial answer never reaches here,
+ * and a caller that spells out the envelope keeps every nullable GitHub returns visible.
+ */
+export async function ghGraphql<S extends AnySchema>(
+  host: GhHost,
+  document: string,
+  variables: Readonly<Record<string, string | number>>,
+  schema: S,
+  options: GhOptions,
+): Promise<InferOutput<S>> {
+  const args = [
+    'api',
+    'graphql',
+    '-f',
+    `query=${document}`,
+    ...Object.entries(variables).flatMap(([name, value]) =>
+      typeof value === 'number' ? ['-F', `${name}=${value}`] : ['-f', `${name}=${value}`],
+    ),
+  ];
+  return ghJson(host, args, schema, options);
+}