plumbbob 0.8.18 → 0.9.1

package/dist/verbs/doctor.js

@@ -1,27 +1,37 @@
-// `plumbbob doctor` — two diagnostics under one verb.
+// `plumbbob doctor` — the health report, five sections under one verb.
 //
 // 1. The global plugin link (read-only). After `plumbbob init`, plumbbob lives as a
 //    symlink at ~/.claude/skills/plumbbob pointing at the installed package; Claude
 //    Code loads it in place as a plugin (skills `/plumbbob:*`, the post-edit hook from
 //    hooks.json). doctor verifies the link resolves to a package carrying the manifest,
 //    the skills, and the hook — and names the fix for anything missing. The failure
-//    class it exists for is SILENT (a `/pb-status` that opens an empty dashboard
+//    class it exists for is SILENT (a `/plumbbob:status` that opens an empty dashboard
 //    because the plugin never linked).
 //
-// 2. The repo sidecar layout. A repo scaffolded by a pre-restructure plumbbob carries a
-//    legacy FLAT sidecar (`.plumbbob/intent.md`, `config`, `archive/`) fully git-excluded.
-//    doctor detects it and, with `--migrate`, moves it into the tracked `builds/<slug>/`
-//    layout (D31): archive entries and the active session become build folders, `config`
-//    becomes `settings.json`, and the whole move is STAGED but never committed — the human
-//    owns that commit (Q8). The move is the one that turns a build's record from local-only
-//    (dies with `git worktree remove`) into a tracked folder that rides the branch into
-//    the PR (supersedes D20).
+// 2. The repo sidecar layout. plumbbob keeps its per-repo state in a `.plumbbob/`
+//    sidecar: a tracked artifact plane (settings.json plus one `builds/<slug>/` folder
+//    per build — intent, build-log, checkpoints, report — that rides its branch into
+//    the PR) and a git-excluded control plane of per-worktree files. A repo scaffolded
+//    by an older plumbbob carries the legacy FLAT sidecar instead (`.plumbbob/intent.md`,
+//    `config`, `archive/`), fully git-excluded, whose record dies with
+//    `git worktree remove`. doctor detects it and, with `--migrate`, moves it into the
+//    tracked `builds/<slug>/` layout: archive entries and the active session become
+//    build folders, `config` becomes `settings.json`, and the whole move is STAGED but
+//    never committed — the human owns that commit.
 //
-// 3. The check gate (D32). When a `check` setting overrides checkride, doctor names the
-//    command; otherwise it runs checkride's own doctor and prints the slot/adapter table —
-//    "detected but tool missing" is the footgun this exists for.
+// 3. Agent validation. Every resolvable user-authored agent gets its manifest and its
+//    `command` statically checked, so a broken agent surfaces here rather than mid-build.
 //
-// Functional, node builtins plus checkride (C1/C2).
+// 4. The check gate. When a `check` setting overrides checkride (the default heavy
+//    check), doctor names the command; otherwise it runs checkride's own doctor and
+//    prints the slot/adapter table — "detected but tool missing" is the footgun this
+//    exists for.
+//
+// 5. The approval latch. Reports whether the harness's turn ledger is live (checkpoint
+//    can latch on a recorded human turn) or dormant (guidance only) — dormant is a
+//    state, never a failure.
+//
+// Functional, node builtins plus checkride.
 import { accessSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join } from 'node:path';
@@ -33,12 +43,18 @@ import { marketplacePlumbbob } from "../lib/plugins.js";
 import { findRepoRoot, gitPath, stagePath } from "../lib/git.js";
 import { buildDir, excludeControl, listBuilds, readTurn, setActiveBuild, sidecarDir, slugify } from "../lib/sidecar.js";
 import { resolveBoolean, resolveString, settingsPath } from "../lib/settings.js";
-// The plumbbob package's own skills/ dir (the canonical set), off this module's
-// URL so it resolves the same from src/ (dev) and dist/ (published).
+/**
+ * Resolve a directory shipped inside the plumbbob package (e.g. its skills/).
+ *
+ * Resolved off this module's URL so it lands the same from src/ (dev) and
+ * dist/ (published).
+ */
 function packageDir(name) {
     return fileURLToPath(new URL(`../../${name}/`, import.meta.url));
 }
-// Skill directories (those carrying a SKILL.md) under `dir`.
+/**
+ * Skill directories (those carrying a SKILL.md) under `dir`.
+ */
 function listSkills(dir) {
     try {
         return readdirSync(dir).filter((n) => existsSync(join(dir, n, 'SKILL.md')));
@@ -47,8 +63,10 @@ function listSkills(dir) {
         return [];
     }
 }
-// Resolve the dir the plugin link points at: a symlink's target, or the path
-// itself if a real directory was copied there. null if nothing is linked.
+/**
+ * Resolve the dir the plugin link points at: a symlink's target, or the path
+ * itself if a real directory was copied there. null if nothing is linked.
+ */
 function linkedPackage(link) {
     try {
         const st = lstatSync(link);
@@ -61,6 +79,12 @@ function linkedPackage(link) {
         return null;
     }
 }
+/**
+ * The link-install checks: manifest, skill set, and post-edit hook, each with its fix.
+ *
+ * `shipped` is the canonical skill list read from the package itself; an installed
+ * count below it means a stale or partial link, and every fix is the same re-link.
+ */
 function buildChecks(link, pkg, shipped) {
     const installed = listSkills(join(pkg, 'skills'));
     return [
@@ -76,7 +100,15 @@ function buildChecks(link, pkg, shipped) {
             : { ok: false, label: 'hook missing (hooks/hooks.json)', fix: 're-link: plumbbob init' },
     ];
 }
-// The plugin-link diagnostic: the checks to print plus how many failed.
+/**
+ * The plugin-link diagnostic: how plumbbob is installed into Claude Code, as checks.
+ *
+ * Two install kinds are recognized: the marketplace plugin (one green line — skills
+ * load and the CLI rides the plugin's bin/, nothing to verify piecemeal) and the
+ * init-style link at ~/.claude/skills/plumbbob (verified piece by piece). Both at
+ * once is a collision — two plugins named plumbbob fight over /plumbbob:* — reported
+ * first, with the keep-one fix.
+ */
 function pluginChecks() {
     const home = process.env.HOME ?? homedir();
     const link = join(home, '.claude', 'skills', 'plumbbob');
@@ -98,7 +130,9 @@ function pluginChecks() {
     }
     return checks;
 }
-// Read a directory's immediate sub-directory names, sorted; [] when it is absent.
+/**
+ * Read a directory's immediate sub-directory names, sorted; [] when it is absent.
+ */
 function subdirs(dir) {
     try {
         return readdirSync(dir, { withFileTypes: true })
@@ -110,11 +144,15 @@ function subdirs(dir) {
         return [];
     }
 }
-// Detect a legacy flat sidecar, or null when the repo is already on the new layout
-// (or has no sidecar). `config` and `archive/` are unambiguous pre-restructure markers
-// — the new layout has neither. A flat `intent.md` alone would also match today's
-// `--local` layout, so it only counts as legacy when the repo is NOT already migrated
-// (no `builds/`, no `settings.json`): that guard is what keeps `--local` untouched.
+/**
+ * Detect a legacy flat sidecar, or null when the repo is on the current layout
+ * (or has no sidecar).
+ *
+ * `config` and `archive/` are unambiguous legacy markers — the builds/ layout has
+ * neither. A flat `intent.md` alone would also match today's `--local` layout, so it
+ * only counts as legacy when the repo is NOT already migrated (no `builds/`, no
+ * `settings.json`): that guard is what keeps `--local` untouched.
+ */
 export function inspectLegacy(root) {
     const dir = sidecarDir(root);
     if (!existsSync(dir))
@@ -127,7 +165,9 @@ export function inspectLegacy(root) {
         return null;
     return { config, archive, session };
 }
-// The first `# Heading` in a flat intent.md — the build title the slug derives from.
+/**
+ * The first `# Heading` in a flat intent.md — the build title the slug derives from.
+ */
 function titleFromIntent(path) {
     try {
         for (const line of readFileSync(path, 'utf8').split('\n')) {
@@ -141,7 +181,9 @@ function titleFromIntent(path) {
     }
     return '';
 }
-// The `check=<cmd>` line from a legacy `.plumbbob/config`, or null when absent.
+/**
+ * The `check=<cmd>` line from a legacy `.plumbbob/config`, or null when absent.
+ */
 function configCheck(path) {
     try {
         for (const line of readFileSync(path, 'utf8').split('\n')) {
@@ -155,9 +197,13 @@ function configCheck(path) {
     }
     return null;
 }
-// A slug not already claimed by `taken`, suffixing `-2`, `-3`, … only on collision.
-// `start` refuses on collision (D38), but migration is mechanically moving folders that
-// already exist, so it disambiguates rather than aborting mid-move.
+/**
+ * A slug not already claimed by `taken`, suffixing `-2`, `-3`, … only on collision.
+ *
+ * `start` refuses a colliding slug outright — the human picks a new title — but
+ * migration is mechanically moving folders that already exist, so it disambiguates
+ * rather than aborting mid-move.
+ */
 function uniqueSlug(base, taken) {
     const slug = base.length > 0 ? base : 'migrated-build';
     if (!taken.has(slug))
@@ -167,7 +213,9 @@ function uniqueSlug(base, taken) {
         n += 1;
     return `${slug}-${n}`;
 }
-// Move whichever of `names` exist from `from/` into `to/`.
+/**
+ * Move whichever of `names` exist from `from/` into `to/`.
+ */
 function moveInto(from, to, names) {
     mkdirSync(to, { recursive: true });
     for (const name of names) {
@@ -176,9 +224,15 @@ function moveInto(from, to, names) {
             renameSync(src, join(to, name));
     }
 }
-// Drop the blanket `.plumbbob/` line the legacy layout wrote to info/exclude, then add
-// the narrowed control-plane patterns (D17) — so the moved `builds/` and `settings.json`
-// become trackable while the per-worktree control files stay excluded.
+/**
+ * Replace the legacy blanket `.plumbbob/` exclude with the narrowed control-plane
+ * patterns.
+ *
+ * The flat layout excluded the whole sidecar via the shared gitdir's info/exclude;
+ * dropping that line and writing the per-worktree control patterns is what lets the
+ * moved `builds/` and `settings.json` become trackable while the control files stay
+ * excluded.
+ */
 function narrowExcludes(root) {
     const exclude = gitPath(root, 'info/exclude');
     try {
@@ -195,14 +249,17 @@ function narrowExcludes(root) {
     }
     excludeControl(root);
 }
-// Perform the migration and return a human-readable list of what moved. STAGES the
-// result but never commits (Q8). Returns the actions so doctor can print them; call
-// only when `inspectLegacy` reported a legacy layout.
+/**
+ * Perform the migration and return a human-readable list of what moved.
+ *
+ * STAGES the result but never commits — the human owns that commit. Call only when
+ * `inspectLegacy` reported a legacy layout; doctor prints the returned actions.
+ */
 export function migrateSidecar(root) {
     const dir = sidecarDir(root);
     const actions = [];
     const taken = new Set(listBuilds(root));
-    // config → settings.json (only when the new file is not already present).
+    // config → settings.json (skipped when settings.json already exists).
     const configPath = join(dir, 'config');
     if (existsSync(configPath)) {
         if (!existsSync(settingsPath(root))) {
@@ -217,8 +274,9 @@ export function migrateSidecar(root) {
         }
         rmSync(configPath, { force: true });
     }
-    // The flat active session → its own build folder, and the cursor points at it: it is
-    // the one in-flight build (D28). Migrate it first so it keeps the slug from its title.
+    // The flat active session → its own build folder, and the active-build cursor
+    // (.plumbbob/STATE) points at it: it is the one in-flight build. Migrate it first
+    // so it keeps the slug from its title.
     const flatIntent = join(dir, 'intent.md');
     if (existsSync(flatIntent)) {
         const slug = uniqueSlug(slugify(titleFromIntent(flatIntent)), taken);
@@ -243,9 +301,13 @@ export function migrateSidecar(root) {
     actions.push('staged the move (builds/ + settings.json) — commit it yourself');
     return actions;
 }
-// The sidecar section: legacy detection + the offer, or the migration report under
-// `--migrate`. Returns the lines to print and how many problems it found (an
-// un-migrated legacy layout counts as one, so the exit code flags it).
+/**
+ * The sidecar section: legacy detection plus the migrate offer, or the migration
+ * report under `--migrate`.
+ *
+ * Returns the lines to print and how many problems it found (an un-migrated legacy
+ * layout counts as one, so the exit code flags it).
+ */
 function sidecarReport(cwd, migrate) {
     const root = findRepoRoot(cwd);
     const legacy = root === null ? null : inspectLegacy(root);
@@ -270,16 +332,21 @@ function sidecarReport(cwd, migrate) {
     lines.push('        (archive/ + the active session → builds/, config → settings.json; staged, never committed)');
     return { lines, failed: 1 };
 }
-// --- agent validation (D48) ---
-// Interpreters recognized as the program of a manifest `command`: when the command
-// is `sh <script>` / `node <script>` / …, the checkable artifact is the script
-// argument (the interpreter reads it — the file need not carry +x), not the
-// interpreter, which we trust to be on PATH.
+// --- agent validation ---
+/**
+ * Interpreters recognized as the program of a manifest `command`: when the command
+ * is `sh <script>` / `node <script>` / …, the checkable artifact is the script
+ * argument (the interpreter reads it — the file need not carry +x), not the
+ * interpreter, which we trust to be on PATH.
+ */
 const INTERPRETERS = new Set(['sh', 'bash', 'zsh', 'dash', 'node', 'deno', 'bun', 'python', 'python3', 'ruby', 'perl']);
-// Expand PLUMBBOB_AGENT_DIR (D49) in a command and split it into bare tokens
-// (surrounding quotes stripped). A deliberately shallow split — enough for the
-// static command check below, not a shell parser (which is neither possible nor
-// wanted for a best-effort diagnostic).
+/**
+ * Expand PLUMBBOB_AGENT_DIR in a command and split it into bare tokens
+ * (surrounding quotes stripped).
+ *
+ * A deliberately shallow split — enough for the static command check below, not a
+ * shell parser (which is neither possible nor wanted for a best-effort diagnostic).
+ */
 function commandTokens(command, agentDir) {
     const expanded = command.replaceAll('${PLUMBBOB_AGENT_DIR}', agentDir).replaceAll('$PLUMBBOB_AGENT_DIR', agentDir);
     return expanded
@@ -287,14 +354,17 @@ function commandTokens(command, agentDir) {
         .filter((t) => t.length > 0)
         .map((t) => t.replace(/^['"]/, '').replace(/['"]$/, ''));
 }
-// Statically check a manifest `command` for the footgun D48 names: a script file
-// that does not exist, or a directly-invoked one missing its +x bit. The command
-// is a shell string spawned via `sh -c` at the repo root (D49), so a relative path
-// resolves against `root` and PLUMBBOB_AGENT_DIR points at the agent's own dir.
-// Best-effort by design — a path-shaped program or an interpreter's script
-// argument is checked; a bare command (a PATH binary, an inline `node -e` program)
-// is trusted, because we cannot prove a shell line broken without running it.
-// Returns the problem string, or null when nothing checkable is wrong.
+/**
+ * Statically check a manifest `command` for the silent footguns: a script file that
+ * does not exist, or a directly-invoked one missing its +x bit.
+ *
+ * The command is a shell string spawned via `sh -c` with the repo root as cwd, so a
+ * relative path resolves against `root` and PLUMBBOB_AGENT_DIR points at the agent's
+ * own dir. Best-effort by design — a path-shaped program or an interpreter's script
+ * argument is checked; a bare command (a PATH binary, an inline `node -e` program)
+ * is trusted, because we cannot prove a shell line broken without running it.
+ * Returns the problem string, or null when nothing checkable is wrong.
+ */
 function checkCommand(command, agentDir, root) {
     const tokens = commandTokens(command, agentDir);
     if (tokens.length === 0)
@@ -323,21 +393,29 @@ function checkCommand(command, agentDir, root) {
     }
     return null;
 }
-// One agent's problem (D48), or null when it validates: a malformed or
-// unsupported-contract manifest surfaces as its resolution error; an
-// otherwise-valid agent is checked for a missing/non-executable command.
+/**
+ * One agent's problem, or null when it validates.
+ *
+ * A malformed or unsupported-contract manifest surfaces as its resolution error; an
+ * otherwise-valid agent is checked for a missing/non-executable command.
+ */
 function agentProblem(listing, root) {
     if (!listing.resolution.ok)
         return listing.resolution.error;
     const { manifest, dir } = listing.resolution.agent;
     return checkCommand(manifest.command, dir, root);
 }
-// The agent-validation section (D48): walk every resolvable agent across both
-// tiers (project + personal) and flag a malformed agent.json, an unsupported
-// contract version (both arrive as the listing's parse error), or a
-// missing/non-executable command. A repo with no agents shows no section (like the
-// sidecar one), keeping doctor quiet for the common case; outside a repo there is
-// no project tier to anchor to, so the section is skipped entirely.
+/**
+ * The agent-validation section: walk every resolvable user-authored agent across
+ * both tiers (project `.plumbbob/agents/` + personal `~/.plumbbob/agents/`) and flag
+ * anything broken.
+ *
+ * Flags a malformed agent.json, an unsupported contract version (both arrive as the
+ * listing's parse error), or a missing/non-executable command. A repo with no agents
+ * shows no section (like the sidecar one), keeping doctor quiet for the common case;
+ * outside a repo there is no project tier to anchor to, so the section is skipped
+ * entirely.
+ */
 function agentReport(cwd) {
     const root = findRepoRoot(cwd);
     if (root === null)
@@ -360,11 +438,15 @@ function agentReport(cwd) {
     }
     return { lines, failed };
 }
-// The check-gate section (D32): a configured `check` setting names the spawn
-// override and asks nothing more; otherwise checkride's own doctor reports the
-// slot/adapter table. Only rows checkride marks `required` count as problems —
-// an empty slot ("no tool detected") is informational, not a failure, because
-// the runtime gate already refuses a vacuous run.
+/**
+ * The check-gate section: what gates `checkpoint`, and whether it can run.
+ *
+ * A configured `check` setting names the spawn override and asks nothing more;
+ * otherwise checkride's own doctor reports the slot/adapter table. Only rows
+ * checkride marks `required` count as problems — an empty slot ("no tool detected")
+ * is informational, not a failure, because the runtime gate already refuses a
+ * vacuous run.
+ */
 async function gateReport(cwd, env) {
     const root = findRepoRoot(cwd);
     if (root === null)
@@ -391,11 +473,10 @@ async function gateReport(cwd, env) {
             if (c.required && c.status !== 'ok')
                 failed += 1;
         }
-        // The week-1 bounce, called out where the human can see it coming
-        // (research/07 Build 2a): no CODE checks detected means checkpoints are
-        // gated only by checkride's always-on repo checks — either a vacuous
-        // refusal or, worse, a green that tested nothing. Informational, with the
-        // exact fix; `start` surfaces the same probe at plan time.
+        // Called out where the human can see it coming: no CODE checks detected means
+        // checkpoints would be gated only by checkride's always-on repo checks — either
+        // a vacuous refusal or, worse, a green that tested nothing. Informational, with
+        // the exact fix; `start` surfaces the same probe at plan time.
         if (!gateDetectsTools(report.checks)) {
             lines.push('  ○ gate: no code checks detected — checkpoints would be gated by the always-on repo checks alone;' +
                 ' set {"check": "npm test"} in .plumbbob/settings.json, or add tool configs checkride can see');
@@ -407,8 +488,10 @@ async function gateReport(cwd, env) {
         return { lines: [...lines, `  ✗ checkride doctor failed — ${message}`], failed: 1 };
     }
 }
-// One slot line: `✓ types ← tsc (6.0.3)`, `✗ dead ← fallow` with its install
-// hint, or `○ spell — no tool detected` for an empty (skipping) slot.
+/**
+ * One slot line: `✓ types ← tsc (6.0.3)`, `✗ dead ← fallow` with its install
+ * hint, or `○ spell — no tool detected` for an empty (skipping) slot.
+ */
 function toolRow(c) {
     if (c.adapter === null || c.adapter === undefined) {
         return `  ○ ${c.slot ?? c.name} — ${c.hint ?? 'no tool detected (slot skips)'}`;
@@ -418,15 +501,20 @@ function toolRow(c) {
     const hint = c.status !== 'ok' && c.hint !== null ? `\n      → ${c.hint}` : '';
     return `  ${mark} ${c.slot ?? c.name} ← ${c.adapter}${version}${hint}`;
 }
-// The approval-latch health probe (D64): is the turn ledger live? `.plumbbob/TURN`
-// holds a count once the UserPromptSubmit hook has ticked at least once, so a present
-// count means the checkpoint latch is armed — its absence means the tick is
-// guidance-only. Dormant is a legitimate state (a host with no hooks behaves exactly
-// as it always has), never a failure — so this section adds nothing to the problem
-// count. The dormant hint names the hook because a missing ledger almost always means
-// it never wired, and that hook rides in either install kind (the marketplace
-// plugin's hooks/hooks.json or an init-style link). Outside a repo there is no
-// worktree ledger to read, so the section is skipped entirely.
+/**
+ * The approval-latch health probe: is the turn ledger live?
+ *
+ * The latch is `checkpoint`'s refusal to land a step until the harness has recorded
+ * a human turn since the step was entered. `.plumbbob/TURN` holds a count once the
+ * UserPromptSubmit hook has ticked at least once, so a present count means the latch
+ * is armed — its absence means the tick is guidance-only. Dormant is a legitimate
+ * state (a host with no hooks simply has no ledger), never a failure — so this
+ * section adds nothing to the problem count. The dormant hint names the hook because
+ * a missing ledger almost always means it never wired, and that hook rides in either
+ * install kind (the marketplace plugin's hooks/hooks.json or an init-style link).
+ * Outside a repo there is no worktree ledger to read, so the section is skipped
+ * entirely.
+ */
 function latchReport(cwd) {
     const root = findRepoRoot(cwd);
     if (root === null)
@@ -436,14 +524,23 @@ function latchReport(cwd) {
         ? '  ○ latch: dormant — guidance only (no turn ledger yet; it ticks on your first prompt when the UserPromptSubmit hook is wired — re-run after one to confirm)'
         : `  ✓ latch: live (turn ${turn})`;
     const lines = ['', 'plumbbob doctor — approval latch (D64)', line];
-    // D67: a settings `auto` used to be a standing grant; the latch no longer honors it
-    // (a model can write that file). Surface a set value so a human who relied on it isn't
+    // The latch ignores a settings `auto`: a model can write that file, and a grant
+    // the model can forge is no grant — self-approval comes only from the human's
+    // typed `/build --auto`. Surface a set value so a human relying on it isn't
     // silently changed — informational, never a problem.
     if (resolveBoolean(root, 'auto', false)) {
-        lines.push('  ○ auto: set in settings but not a grant since D67 — self-approve per run with `/pb-build --auto`');
+        lines.push('  ○ auto: set in settings but not a grant since D67 — self-approve per run with `/plumbbob:build --auto`');
     }
     return { lines, failed: 0 };
 }
+/**
+ * Run every doctor section, print the report, and return the exit code.
+ *
+ * Sections in order: plugin install, sidecar layout (migrating under `--migrate`),
+ * agents, check gate, approval latch. Exit 1 when any section reported a problem, so
+ * scripts can gate on it; the closing lines cover the restart and the PATH story
+ * either way. `env` injects a deterministic toolchain probe for tests (see GateEnv).
+ */
 export async function doctor(cwd, args = [], env) {
     const checks = pluginChecks();
     const out = ['plumbbob doctor — plugin install'];
@@ -463,7 +560,7 @@ export async function doctor(cwd, args = [], env) {
     out.push(failed === 0
         ? 'plumbbob: all checks passed. If a skill still misbehaves, restart Claude Code (or /reload-plugins).'
         : `plumbbob: ${failed} problem(s) — apply the → fixes, then restart Claude Code.`);
-    out.push('plumbbob: skills shell a bare `plumbbob`. The marketplace plugin puts it on PATH only inside a Claude Code session (via bin/) — there is no terminal `plumbbob`; for one (or the skills-dir install) run `npm i -g plumbbob`. In-session you can also run this as `/pb-doctor`. Sessions are per-project via `plumbbob start`.');
+    out.push('plumbbob: skills shell a bare `plumbbob`. The marketplace plugin puts it on PATH only inside a Claude Code session (via bin/) — there is no terminal `plumbbob`; for one (or the skills-dir install) run `npm i -g plumbbob`. In-session you can also run this as `/plumbbob:doctor`. Sessions are per-project via `plumbbob start`.');
     process.stdout.write(`${out.join('\n')}\n`);
     return failed === 0 ? 0 : 1;
 }