@valescoagency/runway 0.4.0 → 0.6.0

package/dist/commands/doctor.js

@@ -1,10 +1,18 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { execa } from "execa";
-import { detectBaseBranch } from "../git.js";
-import { loadPolicy } from "../policy.js";
-import { loadConfig } from "../config.js";
-import { validateLinearConfig } from "../linear.js";
+import { DIAGNOSTICS, runDiagnostics, } from "../diagnostics/index.js";
+import { renderJson, renderText } from "../diagnostics/render.js";
+// ---------------------------------------------------------------------------
+// Required sections — failures in any of these set the exit code to 1.
+// "Repo state" is informational only (dirty tree, no scaffold) so its
+// failures don't affect the exit code.
+// ---------------------------------------------------------------------------
+const REQUIRED_SECTIONS = new Set([
+    "Host tooling",
+    "Environment",
+    "Docker image",
+    "Linear configuration",
+]);
 // ---------------------------------------------------------------------------
 // Usage
 // ---------------------------------------------------------------------------
@@ -17,7 +25,7 @@ and you want a sanity report.
 
 USAGE
   cd /path/to/your/repo   # (or runway's own clone)
-  runway doctor [--tier=1|2] [--detailed] [--json]
+  runway doctor [--tier=1|2] [--detailed] [--json] [--check=NAME ...]
 
 OPTIONS
   --tier=N        Force tier 1 or 2 checks. Default: auto-detect from
@@ -25,6 +33,8 @@ OPTIONS
   --detailed      Print version numbers, paths, and full error output.
                   Default mode is terse (just ✓/✗/⚠).
   --json          Machine-readable output for CI / scripted health checks.
+  --check=NAME    Run only diagnostics with the given name (repeatable).
+                  Use --check=help to list available names.
   --help, -h      Show this help.
 
 SECTIONS REPORTED
@@ -34,10 +44,11 @@ SECTIONS REPORTED
                     tier 2 also checks OP_SERVICE_ACCOUNT_TOKEN.
   3. Repo state     git repo? clean tree? branch? scaffold detected?
   4. Docker image   sandcastle:<sanitized-cwd> exists; user/group match.
+  5. Linear config  team, workflow states, HITL label on the team.
 
 EXIT CODES
   0   All required checks pass (warnings allowed).
-  1   At least one ✗ in tooling, environment, or image checks.
+  1   At least one ✗ in tooling, environment, image, or Linear checks.
       Repo-state issues (no init, dirty tree) are warnings only.
 `);
 }
@@ -48,6 +59,7 @@ function parseDoctorArgs(argv) {
     let tierOverride;
     let detailed = false;
     let json = false;
+    const checks = [];
     for (const arg of argv) {
         if (arg === "--help" || arg === "-h") {
             printDoctorUsage();
@@ -65,61 +77,76 @@ function parseDoctorArgs(argv) {
         else if (arg === "--json") {
             json = true;
         }
+        else if (arg.startsWith("--check=")) {
+            const name = arg.slice("--check=".length).trim();
+            if (name.length === 0) {
+                throw new Error("--check requires a name (e.g. --check=node)");
+            }
+            checks.push(name);
+        }
         else {
             throw new Error(`unknown argument: ${arg}`);
         }
     }
-    return { tierOverride, detailed, json };
+    return {
+        tierOverride,
+        detailed,
+        json,
+        checks: checks.length > 0 ? checks : undefined,
+    };
+}
+/**
+ * Validate that every `--check=NAME` matches a registered diagnostic.
+ * Unknown names fail fast with the available list so the user sees
+ * what to type instead.
+ */
+function validateCheckNames(checks) {
+    if (!checks?.length)
+        return;
+    if (checks.includes("help")) {
+        const available = DIAGNOSTICS.map((d) => `  ${d.name}  (${d.section})`).join("\n");
+        console.log(`Available --check names:\n${available}`);
+        process.exit(0);
+    }
+    const known = new Set(DIAGNOSTICS.map((d) => d.name));
+    const unknown = checks.filter((n) => !known.has(n));
+    if (unknown.length > 0) {
+        throw new Error(`unknown --check name(s): ${unknown.join(", ")}. ` +
+            `Available: ${[...known].sort().join(", ")} (or --check=help for a grouped list)`);
+    }
 }
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
 export async function doctorCommand(argv) {
     const opts = parseDoctorArgs(argv);
+    validateCheckNames(opts.checks);
     const cwd = process.cwd();
     const repo = detectRepoState(cwd);
     const tier = opts.tierOverride ?? repo.tier;
-    // If no scaffold AND no override → still run host-tooling, but skip the rest.
-    // We pick tier 2 as the "default check posture" for tooling so varlock/op
-    // are reported (Valesco's standard), unless the user explicitly says tier 1.
-    const tierForToolingChecks = tier ?? 2;
+    const tierForChecks = tier ?? 2;
     const initialised = tier !== null;
-    const sections = [];
-    sections.push(await checkHostTooling(tierForToolingChecks));
-    if (initialised || opts.tierOverride !== undefined) {
-        sections.push(await checkEnvironment(tierForToolingChecks, cwd, repo));
-        sections.push(await checkRepoState(cwd, repo));
-        sections.push(await checkDockerImage(cwd));
-        sections.push(await checkLinearConfig());
-    }
-    else {
-        // Push placeholder skipped sections so JSON output stays well-shaped.
-        sections.push(skippedSection("Environment"));
-        sections.push(skippedSection("Repo state"));
-        sections.push(skippedSection("Docker image"));
-        sections.push(skippedSection("Linear configuration"));
-    }
-    // Render
+    const ctx = {
+        cwd,
+        tier: tierForChecks,
+        repo,
+        options: opts,
+    };
+    const sections = await runDiagnostics(ctx);
+    const failed = sections.some((s) => s.ran &&
+        REQUIRED_SECTIONS.has(s.title) &&
+        [...s.checks.values()].some((c) => c.status === "fail"));
     if (opts.json) {
-        renderJson(sections, tier, initialised);
+        renderJson(sections, tier, !failed);
     }
     else {
         renderText(sections, tier, initialised, opts.detailed);
     }
-    // Exit code: required-check failures = 1.
-    // Required: 0 host tooling, 1 environment, 3 docker image, 4 Linear
-    // config. Section 2 (repo state) is informational.
-    const requiredSections = [
-        sections[0],
-        sections[1],
-        sections[3],
-        sections[4],
-    ];
-    const failed = requiredSections.some((s) => s?.ran && [...s.checks.values()].some((c) => c.status === "fail"));
     process.exit(failed ? 1 : 0);
 }
 // ---------------------------------------------------------------------------
-// Repo / tier detection
+// Repo / tier detection — produces the DoctorContext, not itself a
+// diagnostic.
 // ---------------------------------------------------------------------------
 function detectRepoState(cwd) {
     const hasDockerfile = existsSync(join(cwd, ".sandcastle", "Dockerfile"));
@@ -157,594 +184,3 @@ function detectRepoState(cwd) {
     }
     return { tier, hasDockerfile, hasSchema, authMode, hasConflictingAuthVars };
 }
-// ---------------------------------------------------------------------------
-// Section: Host tooling
-// ---------------------------------------------------------------------------
-async function checkHostTooling(tier) {
-    const checks = new Map();
-    checks.set("git", await checkBinaryVersion("git", ["--version"]));
-    const nodeVersion = process.versions.node;
-    const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
-    checks.set("node", nodeMajor >= 22
-        ? { status: "ok", label: "node", detail: `v${nodeVersion}` }
-        : {
-            status: "fail",
-            label: "node",
-            detail: `v${nodeVersion} — node ≥ 22 required`,
-        });
-    checks.set("docker", await checkDockerDaemon());
-    checks.set("gh", await checkGhAuth());
-    if (tier === 2) {
-        checks.set("varlock", await checkBinaryVersion("varlock", ["--version"]));
-        checks.set("op", await checkBinaryVersion("op", ["--version"]));
-    }
-    return { title: "Host tooling", checks, ran: true };
-}
-async function checkBinaryVersion(bin, args) {
-    try {
-        const { stdout, stderr } = await execa(bin, args, { reject: false });
-        const out = (stdout || stderr || "").split("\n")[0]?.trim() ?? "";
-        return { status: "ok", label: bin, detail: out || "(installed)" };
-    }
-    catch {
-        return {
-            status: "fail",
-            label: bin,
-            detail: `${bin} not on PATH`,
-        };
-    }
-}
-async function checkDockerDaemon() {
-    try {
-        await execa("docker", ["--version"], { reject: true });
-    }
-    catch {
-        return {
-            status: "fail",
-            label: "docker",
-            detail: "docker not on PATH (Docker Desktop or Podman)",
-        };
-    }
-    try {
-        await execa("docker", ["info"], { reject: true });
-        return { status: "ok", label: "docker", detail: "daemon up" };
-    }
-    catch (err) {
-        return {
-            status: "fail",
-            label: "docker",
-            detail: `daemon not running — ${errMsg(err)}`,
-        };
-    }
-}
-async function checkGhAuth() {
-    try {
-        await execa("gh", ["--version"], { reject: true });
-    }
-    catch {
-        return {
-            status: "fail",
-            label: "gh",
-            detail: "gh not on PATH",
-        };
-    }
-    try {
-        const { stdout, stderr } = await execa("gh", ["auth", "status"], {
-            reject: true,
-        });
-        // First non-empty line of `gh auth status` is the host header.
-        const summary = (stdout || stderr || "")
-            .split("\n")
-            .map((s) => s.trim())
-            .find((s) => s.length > 0);
-        return {
-            status: "ok",
-            label: "gh",
-            detail: summary ?? "authenticated",
-        };
-    }
-    catch (err) {
-        return {
-            status: "fail",
-            label: "gh",
-            detail: `not authenticated — ${errMsg(err)}`,
-        };
-    }
-}
-// ---------------------------------------------------------------------------
-// Section: Environment
-// ---------------------------------------------------------------------------
-async function checkEnvironment(tier, cwd, repo) {
-    const checks = new Map();
-    checks.set("LINEAR_API_KEY", envSet("LINEAR_API_KEY", "fail"));
-    // Informational: which Linear scope a `runway run` would use.
-    const team = process.env.RUNWAY_LINEAR_TEAM?.trim() || "VA";
-    const project = process.env.RUNWAY_LINEAR_PROJECT?.trim();
-    checks.set("linear_scope", {
-        status: "ok",
-        label: "linear scope",
-        detail: project
-            ? `team ${team} / project ${project}`
-            : `team ${team} (team-wide — RUNWAY_LINEAR_PROJECT unset)`,
-    });
-    // Informational: which base branch a `runway run` would diff against
-    // and target with PRs. Detection failure here is a real problem —
-    // surface it as a fail so the user knows up front.
-    const override = process.env.RUNWAY_BASE_BRANCH?.trim();
-    if (override) {
-        checks.set("base_branch", {
-            status: "ok",
-            label: "base branch",
-            detail: `${override} (RUNWAY_BASE_BRANCH override)`,
-        });
-    }
-    else {
-        try {
-            const detected = await detectBaseBranch(cwd);
-            checks.set("base_branch", {
-                status: "ok",
-                label: "base branch",
-                detail: `${detected} (detected from origin/HEAD)`,
-            });
-        }
-        catch (err) {
-            checks.set("base_branch", {
-                status: "fail",
-                label: "base branch",
-                detail: errMsg(err),
-            });
-        }
-    }
-    if (tier === 2) {
-        // Tier 2: needed by varlock to resolve op:// refs in the container.
-        checks.set("OP_SERVICE_ACCOUNT_TOKEN", envSet("OP_SERVICE_ACCOUNT_TOKEN", "fail"));
-        // Surface which Claude Code auth env var the .env.schema declares.
-        // ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN aren't
-        // interchangeable; a mismatch between this and what's stored in
-        // 1Password yields a generic "Invalid API key" inside the
-        // container with no useful diagnostic.
-        if (repo.hasConflictingAuthVars) {
-            checks.set("auth_mode", {
-                status: "fail",
-                label: "claude auth mode",
-                detail: ".env.schema declares both ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN — pick one (they are not interchangeable)",
-            });
-        }
-        else if (repo.authMode === "oauth") {
-            checks.set("auth_mode", {
-                status: "ok",
-                label: "claude auth mode",
-                detail: "oauth (CLAUDE_CODE_OAUTH_TOKEN — Pro/Max subscription)",
-            });
-        }
-        else if (repo.authMode === "api-key") {
-            checks.set("auth_mode", {
-                status: "ok",
-                label: "claude auth mode",
-                detail: "api-key (ANTHROPIC_API_KEY — pay-per-token)",
-            });
-        }
-        else {
-            checks.set("auth_mode", {
-                status: "fail",
-                label: "claude auth mode",
-                detail: ".env.schema declares neither ANTHROPIC_API_KEY nor CLAUDE_CODE_OAUTH_TOKEN",
-            });
-        }
-    }
-    // VA-352: surface the active impl-pass write-path policy so the
-    // operator can see whether an agent run can touch CI workflows, etc.
-    try {
-        const policy = loadPolicy(cwd);
-        checks.set("policy", {
-            status: "ok",
-            label: "impl policy",
-            detail: `${policy.source} (${policy.forbiddenPaths.length} forbidden path${policy.forbiddenPaths.length === 1 ? "" : "s"})`,
-        });
-    }
-    catch (err) {
-        checks.set("policy", {
-            status: "fail",
-            label: "impl policy",
-            detail: errMsg(err),
-        });
-    }
-    return { title: "Environment", checks, ran: true };
-}
-function envSet(name, missingStatus) {
-    const v = process.env[name];
-    if (v && v.trim().length > 0) {
-        return { status: "ok", label: name, detail: "set" };
-    }
-    return {
-        status: missingStatus,
-        label: name,
-        detail: "unset or empty",
-    };
-}
-// ---------------------------------------------------------------------------
-// Section: Repo state
-// ---------------------------------------------------------------------------
-async function checkRepoState(cwd, repo) {
-    const checks = new Map();
-    // Is this a git repo?
-    let isGitRepo = false;
-    try {
-        await execa("git", ["rev-parse", "--git-dir"], { cwd });
-        isGitRepo = true;
-        checks.set("git_repo", { status: "ok", label: "git repo" });
-    }
-    catch {
-        checks.set("git_repo", {
-            status: "warn",
-            label: "git repo",
-            detail: "not inside a git repo",
-        });
-    }
-    if (isGitRepo) {
-        // Working tree clean? (info-only)
-        try {
-            const { stdout } = await execa("git", ["status", "--porcelain"], { cwd });
-            if (stdout.trim().length === 0) {
-                checks.set("clean_tree", { status: "ok", label: "working tree clean" });
-            }
-            else {
-                const count = stdout.trim().split("\n").length;
-                checks.set("clean_tree", {
-                    status: "warn",
-                    label: "working tree clean",
-                    detail: `${count} change(s) — info only`,
-                });
-            }
-        }
-        catch {
-            checks.set("clean_tree", {
-                status: "warn",
-                label: "working tree clean",
-                detail: "git status failed",
-            });
-        }
-        // Current branch
-        try {
-            const { stdout } = await execa("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd });
-            checks.set("branch", {
-                status: "ok",
-                label: "branch",
-                detail: stdout.trim() || "(detached)",
-            });
-        }
-        catch {
-            checks.set("branch", {
-                status: "warn",
-                label: "branch",
-                detail: "no commits yet",
-            });
-        }
-    }
-    // Scaffold detection
-    if (repo.tier === null) {
-        checks.set("scaffold", {
-            status: "warn",
-            label: "runway scaffold",
-            detail: "no runway scaffold detected — run `runway init` first " +
-                "(only host-tooling diagnostics apply until then)",
-        });
-    }
-    else {
-        checks.set("scaffold", {
-            status: "ok",
-            label: "runway scaffold",
-            detail: `tier ${repo.tier} — Dockerfile=${repo.hasDockerfile} schema=${repo.hasSchema}`,
-        });
-    }
-    return { title: "Repo state", checks, ran: true };
-}
-// ---------------------------------------------------------------------------
-// Section: Docker image
-// ---------------------------------------------------------------------------
-async function checkDockerImage(cwd) {
-    const checks = new Map();
-    const imageName = expectedImageName(cwd);
-    try {
-        const { stdout } = await execa("docker", ["image", "inspect", imageName, "--format", "{{.Config.User}}"], { reject: true });
-        const imageUser = stdout.trim();
-        checks.set("image_present", {
-            status: "ok",
-            label: `image ${imageName}`,
-            detail: "present",
-        });
-        // User mismatch warning per sandcastle's pre-flight diagnostic:
-        // image was built for one UID:GID; if the host UID:GID differs the
-        // bind-mount permissions will be off.
-        const hostUid = process.getuid?.() ?? 1000;
-        const hostGid = process.getgid?.() ?? 1000;
-        const expected = `${hostUid}:${hostGid}`;
-        if (imageUser && imageUser !== expected) {
-            checks.set("image_user", {
-                status: "warn",
-                label: "image user matches host UID:GID",
-                detail: `image User=${imageUser}, host=${expected} — rebuild with --build-arg AGENT_UID/AGENT_GID`,
-            });
-        }
-        else {
-            checks.set("image_user", {
-                status: "ok",
-                label: "image user matches host UID:GID",
-                detail: imageUser ? `User=${imageUser}` : `User unset (root); host=${expected}`,
-            });
-        }
-        // VA-351: container readiness — pnpm on PATH + HOME/cache env
-        // baked in. Cheap one-shot run; fails fast if the image is stale.
-        try {
-            const probe = await execa("docker", [
-                "run",
-                "--rm",
-                imageName,
-                "bash",
-                "-lc",
-                'set -e; which pnpm >/dev/null && printf "HOME=%s\\nXDG_CACHE_HOME=%s\\nTURBO_CACHE_DIR=%s\\n" "$HOME" "$XDG_CACHE_HOME" "$TURBO_CACHE_DIR"',
-            ], { reject: false });
-            const out = probe.stdout ?? "";
-            const missing = [];
-            if (probe.exitCode !== 0)
-                missing.push("pnpm");
-            if (!/^HOME=\/home\/agent\s*$/m.test(out))
-                missing.push("HOME");
-            if (!/^XDG_CACHE_HOME=\/home\/agent\/.cache\s*$/m.test(out)) {
-                missing.push("XDG_CACHE_HOME");
-            }
-            if (!/^TURBO_CACHE_DIR=\/tmp\/turbo-cache\s*$/m.test(out)) {
-                missing.push("TURBO_CACHE_DIR");
-            }
-            if (missing.length === 0) {
-                checks.set("container_ready", {
-                    status: "ok",
-                    label: "container readiness",
-                    detail: "pnpm on PATH; HOME, XDG_CACHE_HOME, TURBO_CACHE_DIR set",
-                });
-            }
-            else {
-                checks.set("container_ready", {
-                    status: "warn",
-                    label: "container readiness",
-                    detail: `missing or wrong inside container: ${missing.join(", ")} — rebuild via \`runway upgrade-repo && docker build .sandcastle -t ${imageName}\``,
-                });
-            }
-        }
-        catch (err) {
-            checks.set("container_ready", {
-                status: "warn",
-                label: "container readiness",
-                detail: `probe failed: ${errMsg(err)}`,
-            });
-        }
-    }
-    catch (err) {
-        checks.set("image_present", {
-            status: "fail",
-            label: `image ${imageName}`,
-            detail: `not built — ${errMsg(err)}`,
-        });
-    }
-    return { title: "Docker image", checks, ran: true };
-}
-// ---------------------------------------------------------------------------
-// Section: Linear configuration (VA-354)
-// ---------------------------------------------------------------------------
-/**
- * Validate that the team, workflow states, and HITL label `runway run`
- * would use actually exist on the Linear workspace. Without this,
- * misconfiguration only surfaces deep inside a long agent run — too
- * late to fix without losing the work.
- */
-async function checkLinearConfig() {
-    const checks = new Map();
-    // The config loader's only hard requirement is LINEAR_API_KEY; the
-    // rest defaults. If the key is missing, the Environment section
-    // already fails — surface a skip here rather than re-failing.
-    if (!process.env.LINEAR_API_KEY) {
-        checks.set("linear_config", {
-            status: "skip",
-            label: "Linear config",
-            detail: "LINEAR_API_KEY unset — skipped",
-        });
-        return { title: "Linear configuration", checks, ran: true };
-    }
-    let config;
-    try {
-        config = loadConfig();
-    }
-    catch (err) {
-        checks.set("linear_config", {
-            status: "fail",
-            label: "Linear config",
-            detail: `failed to load runway config: ${errMsg(err)}`,
-        });
-        return { title: "Linear configuration", checks, ran: true };
-    }
-    let result;
-    try {
-        result = await validateLinearConfig(config);
-    }
-    catch (err) {
-        checks.set("linear_api", {
-            status: "fail",
-            label: "Linear API",
-            detail: `validation request failed: ${errMsg(err)}`,
-        });
-        return { title: "Linear configuration", checks, ran: true };
-    }
-    if (result.team.kind === "missing") {
-        checks.set("team", {
-            status: "fail",
-            label: `team ${config.linearTeam}`,
-            detail: `Linear team key "${result.team.key}" not found — set RUNWAY_LINEAR_TEAM`,
-        });
-        // States/labels are skipped when the team missing; surface
-        // explicitly so the user knows they weren't checked.
-        checks.set("states", {
-            status: "skip",
-            label: "workflow states",
-            detail: "skipped (team missing)",
-        });
-        checks.set("hitl_label", {
-            status: "skip",
-            label: "HITL label",
-            detail: "skipped (team missing)",
-        });
-        return { title: "Linear configuration", checks, ran: true };
-    }
-    checks.set("team", {
-        status: "ok",
-        label: `team ${config.linearTeam}`,
-        detail: `id=${result.team.id}`,
-    });
-    for (const [key, configured, state] of [
-        ["ready_state", config.readyStatus, result.readyStatus],
-        ["in_progress_state", config.inProgressStatus, result.inProgressStatus],
-        ["in_review_state", config.inReviewStatus, result.inReviewStatus],
-    ]) {
-        if (state.kind === "ok") {
-            checks.set(key, {
-                status: "ok",
-                label: `workflow state "${configured}"`,
-                detail: "present",
-            });
-        }
-        else if (state.kind === "skipped") {
-            checks.set(key, {
-                status: "skip",
-                label: `workflow state "${configured}"`,
-                detail: state.reason,
-            });
-        }
-        else {
-            checks.set(key, {
-                status: "fail",
-                label: `workflow state "${configured}"`,
-                detail: `not found on team; available: ${formatList(state.available)}`,
-            });
-        }
-    }
-    if (result.hitlLabel.kind === "ok") {
-        checks.set("hitl_label", {
-            status: "ok",
-            label: `HITL label "${config.hitlLabel}"`,
-            detail: "present",
-        });
-    }
-    else if (result.hitlLabel.kind === "skipped") {
-        checks.set("hitl_label", {
-            status: "skip",
-            label: `HITL label "${config.hitlLabel}"`,
-            detail: result.hitlLabel.reason,
-        });
-    }
-    else {
-        checks.set("hitl_label", {
-            status: "fail",
-            label: `HITL label "${config.hitlLabel}"`,
-            detail: `not found on team — set RUNWAY_HITL_LABEL or create the label. Available: ${formatList(result.hitlLabel.available)}`,
-        });
-    }
-    return { title: "Linear configuration", checks, ran: true };
-}
-function formatList(items) {
-    if (items.length === 0)
-        return "(none)";
-    if (items.length <= 8)
-        return items.join(", ");
-    return `${items.slice(0, 8).join(", ")}, …(+${items.length - 8} more)`;
-}
-/**
- * Sanitize the cwd's basename the same way sandcastle's `defaultImageName`
- * does: lowercase, replace any char outside `[a-z0-9_.-]` with `-`, fall
- * back to "local" if empty. Prefix `sandcastle:`.
- */
-function expectedImageName(cwd) {
-    const dirName = cwd
-        .replace(/[\\/]+$/, "")
-        .split(/[\\/]/)
-        .pop() ?? "local";
-    const sanitized = dirName.toLowerCase().replace(/[^a-z0-9_.-]/g, "-") || "local";
-    return `sandcastle:${sanitized}`;
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function skippedSection(title) {
-    return { title, checks: new Map(), ran: false };
-}
-function errMsg(err) {
-    if (err instanceof Error)
-        return err.message.split("\n")[0] ?? err.message;
-    return String(err);
-}
-// ---------------------------------------------------------------------------
-// Renderers
-// ---------------------------------------------------------------------------
-function statusGlyph(s) {
-    switch (s) {
-        case "ok":
-            return "✓";
-        case "fail":
-            return "✗";
-        case "warn":
-            return "⚠";
-        case "skip":
-            return "·";
-    }
-}
-function renderText(sections, tier, initialised, detailed) {
-    const tierLabel = tier === null ? "not initialized" : `tier ${tier}`;
-    console.log(`runway doctor — ${tierLabel}`);
-    console.log("");
-    for (const section of sections) {
-        console.log(`${section.title}`);
-        if (!section.ran) {
-            console.log("  · skipped (no runway scaffold detected)");
-            console.log("");
-            continue;
-        }
-        for (const check of section.checks.values()) {
-            const glyph = statusGlyph(check.status);
-            if (detailed && check.detail) {
-                console.log(`  ${glyph} ${check.label} — ${check.detail}`);
-            }
-            else if (check.status !== "ok" && check.detail) {
-                // Always surface non-OK detail even in terse mode.
-                console.log(`  ${glyph} ${check.label} — ${check.detail}`);
-            }
-            else {
-                console.log(`  ${glyph} ${check.label}`);
-            }
-        }
-        console.log("");
-    }
-    if (!initialised) {
-        console.log("Hint: cwd has no runway scaffold. Run `runway init` from a target repo " +
-            "to enable the full diagnostic.");
-    }
-}
-function renderJson(sections, tier, _initialised) {
-    const sectionKey = (title) => title.toLowerCase().replace(/\s+/g, "_");
-    const checksByName = (s) => {
-        const out = {};
-        for (const [k, v] of s.checks.entries())
-            out[k] = v.status;
-        return out;
-    };
-    // Determine `ok` from required sections (tooling, env, docker image).
-    const requiredSections = [sections[0], sections[1], sections[3]];
-    const ok = !requiredSections.some((s) => s?.ran && [...s.checks.values()].some((c) => c.status === "fail"));
-    const checks = {};
-    for (const s of sections) {
-        checks[sectionKey(s.title)] = s.ran ? checksByName(s) : null;
-    }
-    const payload = {
-        ok,
-        tier,
-        checks,
-    };
-    console.log(JSON.stringify(payload, null, 2));
-}