@rig-c/core 2.63.0 → 2.64.1

package/README.md

@@ -617,7 +617,7 @@ commands take it and what its default is.
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
 | `guide <RULE>` / `guide §<n>[.<m>[.<k>]] [--all]` | the guide's row for the rule a failure line names — every `FAIL` line, `vote --record` refusal, `ingest` finding and coded compile error ends with ` (see rigc guide <RULE>)`; only legacy uncoded library errors point at `§5.1` — or a section's heading, own prose and subsection index, read from the installed `docs/AUTHORING.md` when it runs. `--all` includes the subsection bodies; a leaf prints its full text either way. Sizes describe full ledger spans. `--all` with a rule is refused, exit 2; an unknown name is refused with the nearest real ones, exit 1 |
 | `skills install [--dir …] [--copy]` | links every agent skill the package ships into `.agents/skills` (or `--dir`) as relative symlinks, or copies them with `--copy` — where Codex, Gemini CLI and Antigravity look. A second run has nothing to do; an entry already there that is not this command's is refused by name and nothing is written |
-| `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package, with every argument untouched and its exit code returned: `rigc review open <dir>` prints a loopback URL to give a person, `check <dir>` validates the folder it would serve, `feedback <dir>` prints what they left, and `rigc review --help` is review's own usage. rigc does not depend on it: without it the command prints `rigc review: @rig-c/review is not installed — npm i -D @rig-c/review` and exits 2. An empty argument (`""`) is handed over only where the running Bun keeps one when it starts a process — Bun 1.2.0 drops it, measured by a probe rather than by version — and is otherwise refused by name, `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …`, exit 2 |
+| `review <dir> […]` | the human review of a build, handed to the `rig-review` bin of `@rig-c/review` installed beside the package; rigc does not depend on it and never installs it. `rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]` is `rig-review open <dir> …` with those flags 1:1 and prints the loopback URL to give a person; a first argument that is one of review's own words (`open`, `check`, `feedback`, `control`, `strip`, `compare`) or starts with `-` (`--help`, `--`) is handed over untouched. stdout is review's byte for byte, stderr review's plus the launcher's own refusals, the exit code review's. Refused by name, exit 2, before the bin starts: `REVIEW_OUTPUT_MISSING <path>` (the target is not a directory); `REVIEW_NOT_INSTALLED` with two lines, `bun add -d @rig-c/review` and `bunx @rig-c/review open <dir> …` carrying the flags given — the same on a terminal and off, with nothing installed or written; `REVIEW_BUN_TOO_OLD: Bun <found>, @rig-c/review needs <required>`, the floor read off the installed package's `engines.bun`; and an empty argument (`""`) under a Bun that drops one (Bun 1.2.0, measured by a probe), `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …`. docs/AUTHORING.md lists every line |
 
 `diff`, `bonedist`, `check` and `bench` measure against something you were given; the
 first three work on any reference you have, and `bench` is a repository workflow that needs a clone

package/bin/rigc.cjs

@@ -56,7 +56,15 @@ const entry = present === null ? 'cli_core.ts' : 'cli.ts';
 const args = process.argv.slice(2);
 const result = spawnSync('bun', [path.join(root, entry), ...args], { stdio: 'inherit' });
 
-if (!result.error && result.status === 0 && args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
+// ⚠️ The exit and the signal are read before `error` (issue #1488): Bun 1.2.0 —
+// the declared minimum, and what runs this file as `bun bin/rigc.cjs` — sets
+// `error` on every child that exits non-zero, so reading it first answered the
+// CLI's own refusal (exit 2) with "could not launch bun" and exit 1. `error` is
+// a launch that failed only where the child left neither a status nor a signal.
+// Node never sets `error` beside a status, so under node nothing here changes.
+const launched = typeof result.status === 'number' || result.signal !== null;
+
+if (launched && result.status === 0 && args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
   process.stderr.write(
     present === null
       ? `entry: ${entry} — ${RUNTIME} absent — the round trip and the commands that need it are not available here; see --help\n`
@@ -64,20 +72,18 @@ if (!result.error && result.status === 0 && args.length === 1 && (args[0] === '-
   );
 }
 
-if (result.error) {
-  if (result.error.code === 'ENOENT') {
-    process.stderr.write('rigc runs on Bun, which was not found on PATH — install it from https://bun.sh\n');
-  } else {
-    process.stderr.write(`rigc: could not launch bun: ${result.error.message}\n`);
-  }
-  process.exit(1);
-}
-
-if (result.signal) {
+if (typeof result.status === 'number') {
+  process.exit(result.status);
+} else if (result.signal !== null) {
   // A signal (e.g. Ctrl-C) killed the child — die the same way instead of
   // inventing an exit code, so the caller sees the same thing it would have
   // seen running bun directly.
   process.kill(process.pid, result.signal);
 } else {
-  process.exit(typeof result.status === 'number' ? result.status : 1);
+  if (result.error && result.error.code === 'ENOENT') {
+    process.stderr.write('rigc runs on Bun, which was not found on PATH — install it from https://bun.sh\n');
+  } else if (result.error) {
+    process.stderr.write(`rigc: could not launch bun: ${result.error.message}\n`);
+  }
+  process.exit(1);
 }

package/docs/AUTHORING.md

@@ -143,9 +143,9 @@ bun cli.ts vote --candidate path/to/spine-a --candidate path/to/spine-b   # -> b
 bun cli.ts vote --record vote-<id>.json                                   # -> votes.jsonl
 
 # …and when the build is for a person to look at rather than for you to choose
-# between, hand it over: with @rig-c/review installed beside rigc, give the person
-# the loopback URL this prints (rigc review --help is review's own usage):
-bun cli.ts review open path/to/spine
+# between, hand it over: give the person the loopback URL this prints on stdout
+# (`rigc review <dir>` is `rig-review open <dir>`; rigc review --help is review's own usage):
+bun cli.ts review path/to/spine [--reference reference.mp4] [--animation <name>]
 ```
 
 `build` compiles, runs the named assertions — through a `@esotericsoftware/spine-core`
@@ -326,6 +326,29 @@ the package's copy (<file> differs)`. A link to the package's own folder is not
 the way however it is spelled, so an absolute link somebody else made is kept and
 reported `already linked`.
 
+`review` is the third, and it is a launcher: its body is the `rig-review` bin of
+`@rig-c/review`, a separate package rigc does not depend on and **never installs**.
+`rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]`
+hands over `open <dir> …` with those flags 1:1; a first argument that is one of
+rig-review's own words — `open`, `check`, `feedback`, `control`, `strip`,
+`compare`, or anything starting with `-` (`--help`, `-h`, and `--`, which hands
+the rest over as it is) — is handed over untouched. Nothing else is added: no
+`--reference` is derived, because no build rigc writes records the clip it was
+retargeted from. What comes back is review's: **stdout is review's stdout byte for
+byte** (the URL line an agent gives a person), stderr is review's plus only the
+launcher's own refusals, and the exit code is review's. The launcher relies on
+review's side of that contract — the URL alone on stdout, its diagnostics on
+stderr, its own refusals in its own words — and does not restate it. Before the
+bin starts, it refuses by name, exit 2, nothing on stdout:
+
+| Line on stderr | When | What to do |
+| --- | --- | --- |
+| `rigc review: REVIEW_OUTPUT_MISSING <path>: nothing is there — …` (or `it is not a directory`) | the first argument was read as a target and is not a directory. Checked first, before the package is looked for | point it at the `--out` a green `build` wrote, or pass `--` first to hand the argument over as it is |
+| `rigc review: REVIEW_NOT_INSTALLED: @rig-c/review is not installed beside this project or beside rig-c, and rigc does not install it — …`, then `bun add -d @rig-c/review`, then `bunx @rig-c/review <what the bin would have been handed>` | the package resolves neither from the working directory up nor from rig-c's root up. The same three lines on a terminal and off one; nothing is installed, fetched or written, and `package.json` and `bun.lock` are untouched | run the first line to install it, or the second to run it once without installing (it fetches into Bun's cache — that is your choice to make, not rigc's) |
+| `rigc review: REVIEW_BUN_TOO_OLD: Bun <found>, @rig-c/review needs <required>` | the installed package's own `engines.bun` floor is above the running Bun. `<required>` is read off that manifest, not written in rigc | upgrade Bun |
+| `rigc review: REVIEW_BUN_RANGE_UNREAD: @rig-c/review declares engines.bun "<range>", and rigc reads only ">=X.Y.Z" — …` | the installed package's `engines.bun` is a range shape rigc does not read, so whether this Bun satisfies it was not guessed | run the bin yourself (`bunx rig-review …` from the project), or a rigc that reads that shape |
+| `rigc review: argument N is empty, and Bun <version>, the Bun running this, drops an empty argument when it starts a process — …` | an `""` argument under a Bun that would drop it (Bun 1.2.0), measured by a probe | give it a value, or run rigc under a Bun that keeps it |
+
 Pick the profile deliberately, and know which one you got by saying nothing. The
 default is `spine`: "is this valid Spine 4.3 that any runtime plays correctly",
 which is the question a rig authored anywhere is asking. `--profile rig-play`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.63.0",
+  "version": "2.64.1",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/cli/core_commands.ts

@@ -47,6 +47,7 @@ import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, fram
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
+import { writeWhole } from './write_whole.ts';
 import { GUIDE_FILE, GUIDE_RULE_TABLES_ELSEWHERE, guideAnswer, refusalLine } from '../guide.ts';
 import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
@@ -2213,7 +2214,9 @@ export function cmdGuide(flags: Record<string, string>, positional: string[]): v
   }
   const answer = guideAnswer(positional[0], { guide: readFileSync(join(PACKAGE_ROOT, GUIDE_FILE), 'utf8'), elsewhere }, { all: flags.all !== undefined });
   if (!answer.ok) throw new GuideError(refusalLine(answer.rule, answer.detail));
-  for (const line of answer.lines) console.log(line);
+  // One write of the whole answer, not `console.log`: a §section with `--all` runs past 64 KiB, which Bun 1.2.0's
+  // console corrupts at a chunk boundary and a non-blocking pipe cuts short on every Bun (issue #1487, `writeWhole`).
+  writeWhole(1, answer.lines.map((line) => `${line}\n`).join(''));
 }
 
 // ---------------------------------------------------------------------------
@@ -2341,31 +2344,128 @@ export function emptyArgumentRefusal(pkg: string, raw: readonly string[], keeps:
   );
 }
 
+/**
+ * One argument as a POSIX shell reads it back (issue #1486): left bare when it is made only of characters no shell
+ * treats specially, otherwise single-quoted with each `'` spelled `'\''`. The empty argument is `''`. Deterministic
+ * — the same argument always prints the same word — so a guidance line naming the flags a caller gave is one string.
+ */
+export function shellWord(arg: string): string {
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg)) return arg;
+  return `'${arg.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * What a delegating command hands its bin, and the build directory it was pointed at (issue #1486). A delegate that
+ * names a `bareTarget` subcommand treats a first argument that is none of its `subcommands` and does not start with
+ * `-` (`--help`, `-h`, `--` and every flag pass through) as a target: `rigc review <dir> …` hands over
+ * `open <dir> …`. Every other command line — no argument at all, an empty first argument, or a subcommand — is handed
+ * over as given, and `target` is `null`.
+ */
+export function delegateArguments(delegate: { subcommands?: readonly string[]; bareTarget?: string }, raw: readonly string[]): { argv: string[]; target: string | null } {
+  const first = raw[0];
+  if (delegate.bareTarget === undefined || first === undefined || first === '' || first.startsWith('-') || (delegate.subcommands ?? []).includes(first)) {
+    return { argv: [...raw], target: null };
+  }
+  return { argv: [delegate.bareTarget, ...raw], target: first };
+}
+
+/**
+ * The refusal for a delegated package that does not resolve (issue #1486): `REVIEW_NOT_INSTALLED` and two guidance
+ * lines — the command that installs it, and the one that runs it once without installing, carrying `argv` (what the
+ * bin would have been handed, a bare target already spelled `open <dir>`) word for word. With nothing to carry, the
+ * second line names the target it needs as `<output>`. Nothing reads the terminal, so it is the same on a TTY and
+ * off one, and rigc runs neither line: an install and a one-off fetch both change state the caller did not ask for.
+ */
+export function notInstalledRefusal(pkg: string, argv: readonly string[]): string {
+  const words = argv.length === 0 ? ['open', '<output>'] : argv.map(shellWord);
+  return (
+    `REVIEW_NOT_INSTALLED: ${pkg} is not installed beside this project or beside rig-c, and rigc does not install it — ` +
+    `install it, or run it once without installing:\n` +
+    `bun add -d ${pkg}\n` +
+    `bunx ${pkg} ${words.join(' ')}`
+  );
+}
+
+/**
+ * The refusal for a delegated package whose manifest declares a Bun floor the running Bun is under, or `null`
+ * (issue #1486). The floor is read off the resolved package's own `engines.bun`, never written here: a package that
+ * declares none has no floor to hold. Only `>=X.Y.Z` is read; any other range shape is refused by name rather than
+ * guessed at (`REVIEW_BUN_RANGE_UNREAD`). A running version with a pre-release tag is below its own release, as
+ * semver orders them.
+ */
+export function bunFloorRefusal(pkg: string, engines: unknown, running: string): string | null {
+  if (engines === undefined) return null;
+  const isObject = typeof engines === 'object' && engines !== null && !Array.isArray(engines);
+  const range = isObject ? (engines as Record<string, unknown>).bun : undefined;
+  if (isObject && range === undefined) return null;
+  const floor = typeof range === 'string' ? /^\s*>=\s*(\d+)\.(\d+)\.(\d+)\s*$/.exec(range) : null;
+  if (floor === null) {
+    const what = isObject ? `engines.bun ${JSON.stringify(range)}` : `engines ${JSON.stringify(engines)}`;
+    return `REVIEW_BUN_RANGE_UNREAD: ${pkg} declares ${what}, and rigc reads only ">=X.Y.Z" — it did not guess whether Bun ${running} satisfies it`;
+  }
+  const found = /^(\d+)\.(\d+)\.(\d+)(-\S*)?/.exec(running);
+  const below = ((): boolean => {
+    if (found === null) return true;
+    for (let i = 1; i <= 3; i++) {
+      const a = Number(found[i]);
+      const b = Number(floor[i]);
+      if (a !== b) return a < b;
+    }
+    return found[4] !== undefined;
+  })();
+  return below ? `REVIEW_BUN_TOO_OLD: Bun ${running}, ${pkg} needs ${range as string}` : null;
+}
+
 /**
  * A delegating command's body (`CommandDoc.delegate`, issue #1457): resolve the
  * package's bin and run it under the Bun running this — the bin is a Bun script
- * — with every argument untouched and stdio inherited, then exit with its code,
- * or die by its signal the way `bin/rigc.cjs` does, so a caller reads what it
- * would have read running the bin itself. Not installed, it is refused by name
- * with the one command that installs it, exit 2, and nothing else is printed.
+ * — with stdio inherited, then exit with its code, or die by its signal the way
+ * `bin/rigc.cjs` does, so a caller reads what it would have read running the bin
+ * itself: stdout is the bin's byte for byte, stderr the bin's plus only the
+ * launcher's own refusals, the exit code the bin's.
+ *
+ * Issue #1486 put four things in front of the spawn, in this order, each a
+ * refusal by name with exit 2 and nothing on stdout: a bare target that is not a
+ * directory (`REVIEW_OUTPUT_MISSING <path>`, read before the install because a
+ * guidance line pointing at nothing is no guidance); the package absent
+ * (`REVIEW_NOT_INSTALLED` and two guidance lines — never an install, never a
+ * `bunx`); a Bun below the package's declared floor (`REVIEW_BUN_TOO_OLD`); an
+ * empty argument this Bun would drop (issue #1465). The argument list is the
+ * caller's, a bare target prefixed with `open`, and nothing else: no
+ * `--reference` is derived, because no build rigc writes records the clip it was
+ * retargeted from.
  */
 function cmdDelegate(command: string, raw: readonly string[]): void {
   const delegate = COMMANDS.find((c) => c.name === command)?.delegate;
   if (delegate === undefined) throw new Error(`internal: ${command} names no delegate`);
+  const { argv, target } = delegateArguments(delegate, raw);
+  if (target !== null && !(existsSync(target) && statSync(target).isDirectory())) {
+    throw new DelegateError(
+      `REVIEW_OUTPUT_MISSING ${target}: ${existsSync(target) ? 'it is not a directory' : 'nothing is there'} — \`rigc review <dir>\` opens a build's output directory, ` +
+        `and the first argument is read as one because it is none of ${(delegate.subcommands ?? []).join(', ')} and does not start with "-" (\`rigc review -- <arg>\` hands it over as it is)`,
+      2,
+    );
+  }
   const manifest = resolveDelegate(delegate.package);
-  if (manifest === null) throw new DelegateError(`${delegate.package} is not installed — npm i -D ${delegate.package}`, 2);
-  const bins = (readJsonFile(manifest) as { bin?: unknown }).bin;
+  if (manifest === null) throw new DelegateError(notInstalledRefusal(delegate.package, argv), 2);
+  const read = readJsonFile(manifest) as { bin?: unknown; engines?: unknown };
+  const bins = read.bin;
   const relativeBin = typeof bins === 'object' && bins !== null ? (bins as Record<string, unknown>)[delegate.bin] : undefined;
   const bin = typeof relativeBin === 'string' ? join(dirname(manifest), relativeBin) : null;
   if (bin === null || !existsSync(bin)) {
     throw new DelegateError(
-      `${delegate.package} at ${dirname(manifest)} ${bin === null ? `declares no "${delegate.bin}" bin` : `declares the "${delegate.bin}" bin ${String(relativeBin)}, which is not there`} — npm i -D ${delegate.package}`,
+      `${delegate.package} at ${dirname(manifest)} ${bin === null ? `declares no "${delegate.bin}" bin` : `declares the "${delegate.bin}" bin ${String(relativeBin)}, which is not there`} — bun add -d ${delegate.package}`,
       2,
     );
   }
-  const dropped = emptyArgumentRefusal(delegate.package, raw, spawnKeepsEmptyArguments, process.versions.bun ?? 'unknown');
+  const old = bunFloorRefusal(delegate.package, read.engines, process.versions.bun ?? 'unknown');
+  if (old !== null) throw new DelegateError(old, 2);
+  const dropped = emptyArgumentRefusal(delegate.package, argv, spawnKeepsEmptyArguments, process.versions.bun ?? 'unknown');
   if (dropped !== null) throw new DelegateError(dropped, 2);
-  const ran = spawnSync(process.execPath, [bin, ...raw], { stdio: 'inherit' });
+  // 🔒 The `--` is Bun's, not the bin's: Bun 1.2.0 and 1.4.2 alike drop one `--` standing right after the script, so
+  // `rigc review -- <dir>` reached the bin as `<dir>` (measured, issue #1486). One given here is the one dropped, and
+  // the arguments after it arrive as they were.
+  const ran = spawnSync(process.execPath, [bin, '--', ...argv], { stdio: 'inherit' });
   // ⚠️ The exit and the signal are read before `error`: Bun 1.2.0 — the declared minimum — sets `error` on every
   // child that exits non-zero, so reading it first refused review's own exit 7 as "could not run". `error` is a
   // launch that failed only where the child left neither a status nor a signal.

package/src/cli/shared.ts

@@ -70,6 +70,7 @@ import { RepackError } from '../repack.ts';
 import { SplitError } from '../meshsplit.ts';
 import { SpineRuntimeError, SPINE_SIDE_ABSENT } from '../spine_side.ts';
 import type { CompileResult, DroppedState } from '../types.ts';
+import { routeConsoleLogThroughWriteWhole, StdoutWriteError } from './write_whole.ts';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 
@@ -1418,8 +1419,12 @@ interface CommandDoc {
    * delegate's exit code is the command's. `flags` is empty for that reason:
    * rigc documents no flag of a program it does not own. A control that reads
    * a command's flag table off `--help` reads it off the commands without this.
+   *
+   * `bareTarget` and `subcommands` (issue #1486): a first argument that is none
+   * of `subcommands` and does not start with `-` is a target, handed over as
+   * `<bareTarget> <target> …` — the one rewrite the launcher makes.
    */
-  delegate?: { package: string; bin: string };
+  delegate?: { package: string; bin: string; bareTarget?: string; subcommands?: readonly string[] };
 }
 
 export const COMMANDS: CommandDoc[] = [
@@ -1952,9 +1957,12 @@ export const COMMANDS: CommandDoc[] = [
     name: 'review',
     runtime: false,
     spineFormat: false,
-    delegate: { package: '@rig-c/review', bin: 'rig-review' },
+    // rig-review's own first words: every one of them, `--help`, `-h` and `--` (rig-review's way to its legacy bare
+    // form) pass through; anything else first is a build directory, handed over as `open <dir>` (issue #1486).
+    delegate: { package: '@rig-c/review', bin: 'rig-review', bareTarget: 'open', subcommands: ['open', 'check', 'feedback', 'control', 'strip', 'compare'] },
     usage: [
-      "rigc review <dir> [...]      (@rig-c/review's rig-review, installed beside: every argument handed over untouched, its exit code returned — `rigc review open <dir>` prints a loopback URL to give a person, `rigc review --help` is rig-review's own usage)",
+      "rigc review <dir> [--reference <video>] [--animation <name>] [--compare <dir>]   (rig-review open <dir> …: prints a loopback URL to give a person)",
+      "rigc review open|check|feedback|control|strip|compare|--help …   (@rig-c/review's rig-review, installed beside: every argument handed over untouched, its stdout and exit code returned; rigc never installs it)",
     ],
     flags: [],
   },
@@ -2960,6 +2968,8 @@ export function helpArgv(rest: readonly string[]): string[] | null {
  * always had, written once for both entries.
  */
 export function runCli(entry: CliEntry, argv: readonly string[]): void {
+  // Before anything prints: every line on stdout goes out whole, or is refused by name (issue #1493).
+  routeConsoleLogThroughWriteWhole();
   const docs = entryCommands(entry.linksRuntime);
   const known = docs.map((doc) => doc.name);
   const registered = Object.keys(entry.runs).sort();
@@ -3178,6 +3188,12 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     console.error(`rigc skills install: ${err.message}`);
     process.exit(1);
   }
+  // A document the reader stopped taking (issue #1487): exit 1 like a lookup that could not answer, and the line
+  // says how many bytes went out of how many and why — a silent short write is what `writeWhole` exists to refuse.
+  if (err instanceof StdoutWriteError) {
+    console.error(`rigc ${command}: ${err.message}`);
+    process.exit(1);
+  }
   // A rule or section the guide does not have (issue #1397): exit 1 like a lookup that found nothing, and the
   // message names what was asked and the nearest real names — the usage under it would bury them.
   if (err instanceof GuideError) {

package/src/cli/write_whole.ts

@@ -0,0 +1,124 @@
+/**
+ * `writeWhole(fd, text)`: every byte of `text`, UTF-8, onto `fd`, or a named
+ * refusal — the writer a command uses for a document too large to trust to
+ * `console.log` (issue #1487).
+ *
+ * ⚖️ Why not `console.log`: on Bun 1.2.0, the declared minimum, one ~322 KB
+ * line with non-ASCII in it came out 330,634 bytes for 330,632, a stray
+ * `\xe2\x00` at a 64 KiB chunk boundary — to a file, a pipe and a slow pipe
+ * alike. And on a stdout whose pipe is non-blocking (a parent set `O_NONBLOCK`
+ * on it), it stopped near 64 KiB on 1.2.0 *and* 1.4.2 with exit 0.
+ *
+ * ⚖️ Why a loop and not one `writeSync(fd, text)`: on that non-blocking pipe
+ * `writeSync` returns a short count — 65,536 of 330,632 — and throws nothing,
+ * so a single call drops the rest in silence on both Buns. Each call here
+ * writes from where the last one stopped.
+ *
+ * ⚖️ Why not `process.stdout.write` and a wait for `drain`: whole on 1.4.2,
+ * but on 1.2.0 over the non-blocking pipe it wrote more bytes than it was
+ * given (397,312 and climbing, diverging at byte 69,633) and never exited.
+ *
+ * A pipe that is full answers `EAGAIN` (or a zero count): the loop waits —
+ * 1 ms, doubling to {@link STALL_WAIT_CAP_MS} — and tries again, and after
+ * {@link MAX_STALLS} answers in a row with no byte taken it refuses with
+ * {@link StdoutWriteError}. `EPIPE` — the reader closed its end, as `| head`
+ * does — stops the write quietly, which is what `console.log` did there (exit 0
+ * on both Buns, measured): the reader has what it asked for. Any other error
+ * (`EBADF`, `EIO`) refuses at once.
+ * The wait is `Atomics.wait` on a cell nothing notifies: a delay, not a reading
+ * of the clock — no value written depends on how long it lasted, and the bound
+ * is a count of attempts, so whether it refuses depends on the reader alone.
+ */
+import { writeSync } from 'node:fs';
+
+/** The answers in a row with no byte taken before the writer refuses — about a minute of waits at the cap. */
+export const MAX_STALLS = 1000;
+/** The longest single wait between two attempts on a full pipe, in milliseconds. */
+export const STALL_WAIT_CAP_MS = 64;
+
+/** A write the reader never took: what was written, of how many bytes, and why it stopped. */
+export class StdoutWriteError extends Error {
+  override name = 'StdoutWriteError';
+}
+
+/** `fs.writeSync`'s buffer form: bytes written, or a throw carrying `code`. */
+export type WriteFn = (fd: number, buffer: Uint8Array, offset: number, length: number) => number;
+
+/**
+ * The selftest's plants (issue #1487): `write` stands in for `fs.writeSync` so a
+ * short count or an `EAGAIN` can be forced, and `wait` for the delay so a plant
+ * runs without sleeping. Nothing outside the selftest passes either.
+ */
+export interface WriteWholePlants {
+  write?: WriteFn;
+  wait?: (ms: number) => void;
+}
+
+const STALL_CODES = new Set(['EAGAIN', 'EWOULDBLOCK', 'EINTR']);
+
+function sleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function writeWhole(fd: number, text: string, plants: WriteWholePlants = {}): void {
+  const write = plants.write ?? ((f: number, b: Uint8Array, o: number, l: number) => writeSync(f, b, o, l));
+  const wait = plants.wait ?? sleep;
+  const bytes = Buffer.from(text, 'utf8');
+  let offset = 0;
+  let stalls = 0;
+  while (offset < bytes.length) {
+    let taken = 0;
+    try {
+      taken = write(fd, bytes, offset, bytes.length - offset);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      // The reader closed its end (`| head`): it has what it asked for, and nobody is left to read the rest.
+      if (code === 'EPIPE') return;
+      if (code === undefined || !STALL_CODES.has(code)) {
+        throw new StdoutWriteError(`${offset} of ${bytes.length} byte(s) confirmed written to fd ${fd} before it stopped: ${code ?? String(err)} — the descriptor is not writable`);
+      }
+    }
+    if (taken > 0) {
+      offset += taken;
+      stalls = 0;
+      continue;
+    }
+    stalls += 1;
+    if (stalls > MAX_STALLS) {
+      throw new StdoutWriteError(`${offset} of ${bytes.length} byte(s) confirmed written to fd ${fd}, and the reader took nothing for ${MAX_STALLS} attempt(s) in a row — it stopped reading`);
+    }
+    wait(Math.min(2 ** (stalls - 1), STALL_WAIT_CAP_MS));
+  }
+}
+
+/**
+ * The CLI's one stdout policy (issue #1493): `console.log` of this process,
+ * every call, through {@link writeWhole} on fd 1 — so the ~250 lines the
+ * commands print are written the way the guide's document is, and a
+ * non-blocking pipe gets all of them instead of the first ~64 KiB with exit 0.
+ * `runCli` installs it before anything prints, for both entries; calling it
+ * again changes nothing.
+ *
+ * ⚖️ One `writeWhole` per call, not a buffer flushed at exit or at a size:
+ * Bun's own `console.log` is synchronous per call on a blocking stdout — a
+ * line printed between two `console.error` lines lands between them under
+ * `2>&1`, to a file and to a pipe, on 1.2.0 and 1.4.2 (measured) — and a
+ * write per call keeps that order, keeps a long `render` or `check` printing
+ * as it goes, and leaves nothing behind for a `process.exit` to drop, or for a
+ * delegate's child, which writes to the same fd, to overtake. A buffer would
+ * have to answer all three and still reorders `2>&1`.
+ *
+ * The text is what Bun's `console.log` prints: the arguments joined by one
+ * space, a string as it is and anything else as `Bun.inspect` shows it, and a
+ * newline. Format directives (`%s` with a second argument) are not applied —
+ * every call in the CLI passes one string, so none has one to apply.
+ */
+let consoleLogRouted = false;
+
+export function routeConsoleLogThroughWriteWhole(): void {
+  if (consoleLogRouted) return;
+  consoleLogRouted = true;
+  console.log = (...args: unknown[]): void => {
+    writeWhole(1, `${args.map((arg) => (typeof arg === 'string' ? arg : Bun.inspect(arg))).join(' ')}\n`);
+  };
+}