agentera 0.0.0 → 3.0.0-dev.0

package/dist/setup/doctor.js

@@ -0,0 +1,1269 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { expanduser, isFile, pathExists, resolvePath } from "../core/paths.js";
+import { SETUP_EVIDENCE, classifyResolvedRoot, } from "../state/installRoot.js";
+import { loadRegistry } from "../registries/runtimeAdapterRegistry.js";
+import { parseToml as parseTomlLocal } from "../core/toml.js";
+export const SCHEMA_VERSION = "agentera.setupDoctor.v1";
+export const STATUSES = ["pass", "warn", "fail", "skip"];
+const REGISTRY = loadRegistry();
+export const DOCTOR_RUNTIME_VIEWS = Object.fromEntries(REGISTRY.runtimeIds.map((runtime) => [runtime, REGISTRY.consumerView("doctor", runtime)]));
+export const RUNTIMES = REGISTRY.runtimeIds;
+export const WRITABLE_RUNTIMES = ["copilot", "codex"];
+export const RUNTIME_BINARIES = Object.fromEntries(RUNTIMES.map((runtime) => [runtime, DOCTOR_RUNTIME_VIEWS[runtime].host_detection.binary_names[0]]));
+export const OPENCODE_SKILL_INSTALL_COMMAND = "npx skills add jgabor/agentera -g -a opencode --skill agentera -y";
+export const OPENCODE_SKILL_NAMES = ["agentera"];
+export const OPENCODE_COMMAND_DESCRIPTIONS = {
+    agentera: "Compound agent orchestration suite: 12 capabilities in one bundled skill",
+};
+export const CANONICAL_ENTRIES = SETUP_EVIDENCE;
+// Self-contained model: runtime hooks invoke the bundled CLI (npx -y agentera
+// hook <name>); there are no per-install helper script files to verify.
+export const HELPER_ENTRIES = [];
+export const SMOKE_TIMEOUT_SECONDS = 30;
+export const ENV_FALLBACKS = ["AGENTERA_HOME", "CLAUDE_PLUGIN_ROOT"];
+export const COPILOT_MARKER = "# agentera: AGENTERA_HOME (managed)";
+export const INSTALLER_SCHEMA_VERSION = "agentera.setupInstaller.v1";
+export const SUPPORT_PATH_RE = /(?<![\w/.$-])(?<path>references\/[A-Za-z0-9][A-Za-z0-9_./-]*)/;
+// ── registry-view accessors (mirror the Python helpers) ─────────────
+export function diagnosticCheckNames(runtime) {
+    return DOCTOR_RUNTIME_VIEWS[runtime].diagnostics.check_names;
+}
+export function diagnosticMessages(runtime) {
+    return DOCTOR_RUNTIME_VIEWS[runtime].diagnostics.primary_messages;
+}
+export function diagnosticStatusLabels(runtime) {
+    return DOCTOR_RUNTIME_VIEWS[runtime].diagnostics.status_labels;
+}
+export function diagnosticGapLabels(runtime) {
+    return DOCTOR_RUNTIME_VIEWS[runtime].diagnostics.gap_labels;
+}
+export function availabilityProbeLabel(runtime) {
+    return String(DOCTOR_RUNTIME_VIEWS[runtime].host_detection.availability_probe_label);
+}
+export const AVAILABILITY_CHECKS = Object.fromEntries(RUNTIMES.map((rt) => [rt, availabilityProbeLabel(rt)]));
+export const PASS_STATUSES = Object.fromEntries(RUNTIMES.map((rt) => [rt, diagnosticStatusLabels(rt)[0]]));
+export const WARN_STATUSES = Object.fromEntries(RUNTIMES.map((rt) => [rt, diagnosticStatusLabels(rt)[1]]));
+export const FAIL_STATUSES = Object.fromEntries(RUNTIMES.map((rt) => [rt, diagnosticStatusLabels(rt)[2]]));
+export const SKIP_STATUSES = Object.fromEntries(RUNTIMES.map((rt) => [rt, diagnosticStatusLabels(rt)[3]]));
+export const USER_ENVIRONMENT_GAPS = Object.fromEntries(RUNTIMES.map((rt) => [rt, diagnosticGapLabels(rt)[1]]));
+export const RUNTIME_CONFIG_GAPS = Object.fromEntries(RUNTIMES.map((rt) => [rt, diagnosticGapLabels(rt)[0]]));
+export const INSTALLER_FIXABLE_GAPS = {
+    copilot: [RUNTIME_CONFIG_GAPS.copilot, USER_ENVIRONMENT_GAPS.copilot],
+    codex: [RUNTIME_CONFIG_GAPS.codex, USER_ENVIRONMENT_GAPS.codex],
+};
+// ── install-root classification ─────────────────────────────────────
+export function verifyInstallRoot(root) {
+    const classification = classifyResolvedRoot(root, { source: "explicit" });
+    if (classification.kind === "managed_fresh")
+        return [];
+    return SETUP_EVIDENCE.filter((entry) => !pathExists(path.join(root, entry)));
+}
+export function verifyHelperAccess(root) {
+    return HELPER_ENTRIES.filter((entry) => !isFile(path.join(root, entry)));
+}
+function moduleDir() {
+    try {
+        return path.dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return process.cwd();
+    }
+}
+export function autoDetectInstallRoot(env, start = null) {
+    for (const variable of ENV_FALLBACKS) {
+        const value = env[variable];
+        if (value) {
+            const candidate = resolvePath(value);
+            if (verifyInstallRoot(candidate).length === 0)
+                return candidate;
+        }
+    }
+    let current = resolvePath(start ?? moduleDir());
+    for (;;) {
+        if (verifyInstallRoot(current).length === 0)
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function setupMissing(root) {
+    return SETUP_EVIDENCE.filter((entry) => !pathExists(path.join(root, entry)));
+}
+export function classifyInstallRoot(explicitRoot, env) {
+    const source = explicitRoot !== null ? "argument" : "auto";
+    const root = explicitRoot !== null ? resolvePath(expanduser(explicitRoot)) : autoDetectInstallRoot(env);
+    if (root === null) {
+        return {
+            status: "fail",
+            path: null,
+            source,
+            kind: null,
+            gap: "user_environment",
+            message: "could not resolve an Agentera install root; pass --install-root or set AGENTERA_HOME",
+            missing: [...SETUP_EVIDENCE],
+        };
+    }
+    const classification = classifyResolvedRoot(root, { source: explicitRoot !== null ? "explicit" : "default" });
+    if (classification.kind !== "managed_fresh") {
+        return {
+            status: "fail",
+            path: root,
+            source,
+            kind: null,
+            gap: "bundle_packaging",
+            message: "install root is missing canonical Agentera entries",
+            missing: setupMissing(root),
+        };
+    }
+    const helperMissing = verifyHelperAccess(root);
+    const status = helperMissing.length === 0 ? "pass" : "fail";
+    return {
+        status,
+        path: root,
+        source,
+        kind: pathExists(path.join(root, ".git")) ? "local-clone" : "installed-bundle",
+        gap: status === "pass" ? null : "bundle_packaging",
+        message: status === "pass"
+            ? "install root is valid"
+            : "install root is valid but shared helper scripts are missing",
+        missing: helperMissing,
+    };
+}
+// ── generic check / aggregation helpers ─────────────────────────────
+export function mkCheck(name, status, message, opts = {}) {
+    return {
+        name,
+        status,
+        message,
+        source: opts.source ?? null,
+        path: opts.path ?? null,
+        gap: opts.gap ?? null,
+        details: opts.details ?? [],
+    };
+}
+export function aggregateStatus(checks) {
+    const statuses = checks.map((c) => c.status);
+    if (statuses.length > 0 && statuses.every((s) => s === "skip"))
+        return "skip";
+    if (statuses.includes("fail"))
+        return "fail";
+    if (statuses.includes("warn"))
+        return "warn";
+    if (statuses.includes("pass"))
+        return "pass";
+    return "skip";
+}
+export function summarizeStatuses(items) {
+    const counts = {};
+    for (const status of STATUSES)
+        counts[status] = 0;
+    const values = Array.isArray(items) ? items : Object.values(items);
+    for (const item of values)
+        counts[item.status] += 1;
+    return counts;
+}
+export function tail(text, limit = 5) {
+    const lines = text.split(/\r\n|\r|\n/).filter((line) => line.trim());
+    return lines.slice(-limit);
+}
+// ===========================================================================
+// Slice 2: runtime scaffolding, OpenCode diagnostics, reference validation
+// ===========================================================================
+import fs from "node:fs";
+import os from "node:os";
+import { classifyResolvedRoot as _classifyResolvedRoot } from "../state/installRoot.js";
+function rootClassification(root, source) {
+    return _classifyResolvedRoot(root, { source });
+}
+/** shutil.which: first PATH entry whose `${dir}/${cmd}` is an executable file. */
+export function which(cmd, pathStr) {
+    const accessCheck = (fn) => {
+        try {
+            const st = fs.statSync(fn);
+            if (st.isDirectory())
+                return false;
+            fs.accessSync(fn, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (cmd.includes("/")) {
+        return accessCheck(cmd) ? cmd : null;
+    }
+    const entries = (pathStr ?? "").split(path.delimiter);
+    const seen = new Set();
+    for (const dir of entries) {
+        if (!dir || seen.has(dir))
+            continue;
+        seen.add(dir);
+        const fn = path.join(dir, cmd);
+        if (accessCheck(fn))
+            return fn;
+    }
+    return null;
+}
+export function runtimeSkip(runtime, env) {
+    const binary = RUNTIME_BINARIES[runtime];
+    return {
+        runtime,
+        status: SKIP_STATUSES[runtime],
+        available: false,
+        binary: null,
+        checks: [
+            mkCheck(AVAILABILITY_CHECKS[runtime], SKIP_STATUSES[runtime], `${binary} executable not found on PATH`, {
+                source: "PATH",
+                gap: USER_ENVIRONMENT_GAPS[runtime],
+                details: [env.PATH ?? ""],
+            }),
+        ],
+    };
+}
+export function configuredRootCheck(runtime, name, candidate, installRoot, source) {
+    const classification = rootClassification(candidate, "environment");
+    if (String(classification.kind).startsWith("missing_")) {
+        return mkCheck(name, FAIL_STATUSES[runtime], "configured Agentera root does not exist", {
+            source,
+            path: candidate,
+            gap: RUNTIME_CONFIG_GAPS[runtime],
+        });
+    }
+    if (classification.kind !== "managed_fresh") {
+        return mkCheck(name, FAIL_STATUSES[runtime], "configured Agentera root is not a valid suite bundle", {
+            source,
+            path: candidate,
+            gap: "bundle_packaging",
+            details: setupMissing(candidate),
+        });
+    }
+    const helperMissing = verifyHelperAccess(candidate);
+    if (helperMissing.length > 0) {
+        return mkCheck(name, FAIL_STATUSES[runtime], "configured Agentera root cannot reach shared helper scripts", {
+            source,
+            path: candidate,
+            gap: "bundle_packaging",
+            details: helperMissing,
+        });
+    }
+    if (resolvePath(candidate) !== resolvePath(installRoot)) {
+        return mkCheck(name, WARN_STATUSES[runtime], "runtime points at a different valid Agentera install root", {
+            source,
+            path: candidate,
+            gap: RUNTIME_CONFIG_GAPS[runtime],
+        });
+    }
+    return mkCheck(name, PASS_STATUSES[runtime], HELPER_ACCESS_MESSAGE, { source, path: candidate });
+}
+export function binaryPath(runtime, env) {
+    return which(RUNTIME_BINARIES[runtime], env.PATH);
+}
+export function runtimeHostPathProblem(runtime, env) {
+    const binary = RUNTIME_BINARIES[runtime];
+    for (const entry of (env.PATH ?? "").split(path.delimiter)) {
+        if (!entry)
+            continue;
+        const candidate = path.join(entry, binary);
+        try {
+            if (fs.statSync(candidate).isDirectory()) {
+                return [candidate, `${binary} PATH candidate is a directory, not an executable`];
+            }
+        }
+        catch {
+            /* not present */
+        }
+        if (pathExists(candidate)) {
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+            }
+            catch {
+                return [candidate, `${binary} PATH candidate is not executable`];
+            }
+        }
+    }
+    return null;
+}
+export function runtimeResult(runtime, env, checks) {
+    const binary = binaryPath(runtime, env);
+    if (binary === null)
+        return runtimeSkip(runtime, env);
+    const binaryCheck = mkCheck(AVAILABILITY_CHECKS[runtime], PASS_STATUSES[runtime], `${RUNTIME_BINARIES[runtime]} executable found`, { source: "PATH", path: binary });
+    const allChecks = [binaryCheck, ...checks];
+    return {
+        runtime,
+        status: aggregateStatus(allChecks),
+        available: true,
+        binary,
+        checks: allChecks,
+    };
+}
+// HELPER_ACCESS_MESSAGE mirrors COPILOT_HELPER_MESSAGE (registry-derived).
+export const HELPER_ACCESS_MESSAGE = diagnosticMessages("copilot")[0];
+// ── OpenCode diagnostics ────────────────────────────────────────────
+const OPENCODE_PLUGIN_CHECK = diagnosticCheckNames("opencode")[0];
+const OPENCODE_HOME_CHECK = diagnosticCheckNames("opencode")[1];
+const OPENCODE_COMMANDS_CHECK = diagnosticCheckNames("opencode")[2];
+const OPENCODE_SKILL_PATHS_CHECK = diagnosticCheckNames("opencode")[3];
+const OPENCODE_SUPPORT_CHECK = diagnosticCheckNames("opencode")[4];
+const OC_MSG = diagnosticMessages("opencode");
+const OPENCODE_COMMANDS_CURRENT_MESSAGE = OC_MSG[4];
+const OPENCODE_COMMANDS_DRIFT_MESSAGE = OC_MSG[5];
+const OPENCODE_SKILL_PATHS_CURRENT_MESSAGE = OC_MSG[6];
+const OPENCODE_SKILL_PATHS_DRIFT_MESSAGE = OC_MSG[7];
+const OPENCODE_SUPPORT_REFERENCES_PASS_MESSAGE = OC_MSG[8];
+const OPENCODE_SUPPORT_REFERENCES_DRIFT_MESSAGE = OC_MSG[9];
+const OPENCODE_PASS_STATUS = diagnosticStatusLabels("opencode")[0];
+const OPENCODE_WARN_STATUS = diagnosticStatusLabels("opencode")[1];
+const OC_GAP = diagnosticGapLabels("opencode");
+const OPENCODE_COMMAND_DRIFT_GAP = OC_GAP[2];
+const OPENCODE_SKILL_PATH_DRIFT_GAP = OC_GAP[3];
+const OPENCODE_VALIDATION_DRIFT_GAP = OC_GAP[4];
+export function opencodeConfigDir(home, env) {
+    const value = env.OPENCODE_CONFIG_DIR;
+    return value ? resolvePath(expanduser(value)) : path.join(home, ".config", "opencode");
+}
+export function opencodeCommandTemplate(name) {
+    return ("---\n" +
+        `description: "${OPENCODE_COMMAND_DESCRIPTIONS[name]}"\n` +
+        "agentera_managed: true\n" +
+        "---\n" +
+        `Load and execute the ${name} skill for this project.\n`);
+}
+export function hasManagedMarker(text) {
+    const lines = text.split("\n");
+    if (lines.length === 0 || lines[0] !== "---")
+        return false;
+    const closing = lines.indexOf("---", 1);
+    if (closing === -1)
+        return false;
+    return lines.slice(1, closing).some((line) => line.trim() === "agentera_managed: true");
+}
+export function diagnoseOpencodeCommands(home, env) {
+    const commandsDir = path.join(opencodeConfigDir(home, env), "commands");
+    const missing = [];
+    const stale = [];
+    const userOwned = [];
+    for (const name of OPENCODE_SKILL_NAMES) {
+        const command = path.join(commandsDir, `${name}.md`);
+        const expected = opencodeCommandTemplate(name);
+        let actual;
+        try {
+            actual = fs.readFileSync(command, "utf8");
+        }
+        catch {
+            missing.push(name);
+            continue;
+        }
+        if (actual === expected)
+            continue;
+        if (hasManagedMarker(actual))
+            stale.push(name);
+        else
+            userOwned.push(name);
+    }
+    if (missing.length === 0 && stale.length === 0) {
+        const details = userOwned.map((name) => `user-owned command preserved: ${name}`);
+        return mkCheck(OPENCODE_COMMANDS_CHECK, OPENCODE_PASS_STATUS, OPENCODE_COMMANDS_CURRENT_MESSAGE, {
+            path: commandsDir,
+            details,
+        });
+    }
+    const details = [...missing.map((n) => `missing: ${n}`), ...stale.map((n) => `stale: ${n}`)];
+    if (userOwned.length > 0)
+        details.push(...userOwned.map((n) => `user-owned command preserved: ${n}`));
+    details.push("action: start OpenCode with the Agentera plugin to restore managed commands");
+    return mkCheck(OPENCODE_COMMANDS_CHECK, OPENCODE_WARN_STATUS, OPENCODE_COMMANDS_DRIFT_MESSAGE, {
+        path: commandsDir,
+        gap: OPENCODE_COMMAND_DRIFT_GAP,
+        details,
+    });
+}
+function isAgenteraManagedSkillPath(target, name) {
+    let linkTarget;
+    try {
+        linkTarget = fs.readlinkSync(target);
+    }
+    catch {
+        return false;
+    }
+    const normalized = linkTarget.toLowerCase();
+    return normalized.includes("agentera") || path.basename(linkTarget) === name;
+}
+function isSymlink(p) {
+    try {
+        return fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function diagnoseOpencodeSkillPaths(installRoot, home, env) {
+    const skillsDir = path.join(opencodeConfigDir(home, env), "skills");
+    const missing = [];
+    const broken = [];
+    const userOwned = [];
+    const missingSource = [];
+    for (const name of OPENCODE_SKILL_NAMES) {
+        const source = path.join(installRoot, "skills", name, "SKILL.md");
+        const target = path.join(skillsDir, name);
+        if (!isFile(source)) {
+            missingSource.push(name);
+            continue;
+        }
+        if (!pathExists(target) && !isSymlink(target)) {
+            missing.push(name);
+            continue;
+        }
+        if (isFile(path.join(target, "SKILL.md")))
+            continue;
+        if (isAgenteraManagedSkillPath(target, name))
+            broken.push(name);
+        else
+            userOwned.push(name);
+    }
+    if (missing.length === 0 && broken.length === 0 && missingSource.length === 0) {
+        const details = userOwned.map((name) => `user-owned skill path preserved: ${name}`);
+        return mkCheck(OPENCODE_SKILL_PATHS_CHECK, OPENCODE_PASS_STATUS, OPENCODE_SKILL_PATHS_CURRENT_MESSAGE, {
+            path: skillsDir,
+            details,
+        });
+    }
+    const details = [...missing.map((n) => `missing: ${n}`), ...broken.map((n) => `broken: ${n}`)];
+    if (missingSource.length > 0) {
+        details.push(...missingSource.map((n) => `missing install source: ${n}`));
+        details.push(`action: ${OPENCODE_SKILL_INSTALL_COMMAND}`);
+    }
+    else {
+        details.push("action: start OpenCode with the Agentera plugin to restore managed skill paths");
+    }
+    if (userOwned.length > 0)
+        details.push(...userOwned.map((n) => `user-owned skill path preserved: ${n}`));
+    return mkCheck(OPENCODE_SKILL_PATHS_CHECK, OPENCODE_WARN_STATUS, OPENCODE_SKILL_PATHS_DRIFT_MESSAGE, {
+        path: skillsDir,
+        gap: OPENCODE_SKILL_PATH_DRIFT_GAP,
+        details,
+    });
+}
+// ── bundled reference validation ────────────────────────────────────
+function trimChars(s, chars) {
+    let start = 0;
+    let end = s.length;
+    while (start < end && chars.includes(s[start]))
+        start++;
+    while (end > start && chars.includes(s[end - 1]))
+        end--;
+    return s.slice(start, end);
+}
+export function normalizeReference(raw) {
+    const candidate = trimChars(raw, "`'\"()[]{}.,:;");
+    if (!candidate || path.isAbsolute(candidate) || candidate.includes("\\"))
+        return null;
+    const parts = candidate.split("/");
+    if (parts.some((part) => part === "" || part === "." || part === ".."))
+        return null;
+    return candidate;
+}
+export function extractReferencePaths(text) {
+    const refs = [];
+    const seen = new Set();
+    const re = /(?<![\w/.$-])(?<path>references\/[A-Za-z0-9][A-Za-z0-9_./-]*)/g;
+    for (const match of text.matchAll(re)) {
+        const ref = normalizeReference(match.groups.path);
+        if (ref !== null && !seen.has(ref)) {
+            refs.push(ref);
+            seen.add(ref);
+        }
+    }
+    return refs;
+}
+function globSkillFiles(skillsDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        const skillFile = path.join(skillsDir, entry, "SKILL.md");
+        if (isFile(skillFile))
+            out.push(skillFile);
+    }
+    return out.sort();
+}
+export function diagnoseBundledReferenceValidation(installRoot) {
+    const skillsDir = path.join(installRoot, "skills");
+    const missing = [];
+    for (const skillFile of globSkillFiles(skillsDir)) {
+        const text = fs.readFileSync(skillFile, "utf8");
+        const parentName = path.basename(path.dirname(skillFile));
+        for (const ref of extractReferencePaths(text)) {
+            if (!pathExists(path.join(path.dirname(skillFile), ref))) {
+                missing.push(`${parentName}: ${ref}`);
+            }
+        }
+    }
+    if (missing.length === 0) {
+        return mkCheck(OPENCODE_SUPPORT_CHECK, OPENCODE_PASS_STATUS, OPENCODE_SUPPORT_REFERENCES_PASS_MESSAGE, {
+            path: skillsDir,
+        });
+    }
+    return mkCheck(OPENCODE_SUPPORT_CHECK, OPENCODE_WARN_STATUS, OPENCODE_SUPPORT_REFERENCES_DRIFT_MESSAGE, {
+        path: skillsDir,
+        gap: OPENCODE_VALIDATION_DRIFT_GAP,
+        details: missing,
+    });
+}
+export function smokeCheck(name, category, status, message, opts = {}) {
+    return {
+        name,
+        category,
+        status,
+        message,
+        command: opts.command ?? [],
+        path: opts.path ?? null,
+        details: opts.details ?? [],
+    };
+}
+// ===========================================================================
+// Slice 3: per-runtime diagnostics
+// ===========================================================================
+// Claude
+const CLAUDE_ROOT_CHECK = diagnosticCheckNames("claude")[0];
+const CLAUDE_MISSING_ENV_MESSAGE = diagnosticMessages("claude")[1];
+const CLAUDE_WARN_STATUS = diagnosticStatusLabels("claude")[1];
+const CLAUDE_USER_ENVIRONMENT_GAP = diagnosticGapLabels("claude")[1];
+// OpenCode (additional to slice 2)
+const OPENCODE_PLUGIN_PRESENT_MESSAGE = OC_MSG[0];
+const OPENCODE_PLUGIN_MISSING_MESSAGE = OC_MSG[1];
+const OPENCODE_HOME_MISSING_MESSAGE = OC_MSG[3];
+const OPENCODE_RUNTIME_CONFIG_GAP = OC_GAP[0];
+// Copilot
+const COPILOT_HOME_CHECK = diagnosticCheckNames("copilot")[0];
+const CO_MSG = diagnosticMessages("copilot");
+const COPILOT_MISSING_MESSAGE = CO_MSG[1];
+const COPILOT_RC_CONFIGURED_MESSAGE = CO_MSG[2];
+const COPILOT_PASS_STATUS = diagnosticStatusLabels("copilot")[0];
+const COPILOT_WARN_STATUS = diagnosticStatusLabels("copilot")[1];
+const COPILOT_RUNTIME_CONFIG_GAP = diagnosticGapLabels("copilot")[0];
+// Codex
+const CODEX_HOME_CHECK = diagnosticCheckNames("codex")[0];
+const CODEX_CONFIG_ERROR_MESSAGE = diagnosticMessages("codex")[1];
+const CODEX_WARN_STATUS = diagnosticStatusLabels("codex")[1];
+const CODEX_FAIL_STATUS = diagnosticStatusLabels("codex")[2];
+const CODEX_RUNTIME_CONFIG_GAP = diagnosticGapLabels("codex")[0];
+// Cursor
+const CURSOR_HOME_CHECK = diagnosticCheckNames("cursor")[0];
+const CURSOR_HOOKS_CHECK = diagnosticCheckNames("cursor")[1];
+const CURSOR_AGENTS_CHECK = diagnosticCheckNames("cursor")[2];
+const CURSOR_HELPER_MESSAGE = diagnosticMessages("cursor")[0];
+const CURSOR_PASS_STATUS = diagnosticStatusLabels("cursor")[0];
+const CURSOR_WARN_STATUS = diagnosticStatusLabels("cursor")[1];
+const CURSOR_FAIL_STATUS = diagnosticStatusLabels("cursor")[2];
+const CURSOR_USER_ENVIRONMENT_GAP = diagnosticGapLabels("cursor")[1];
+const CURSOR_HOOK_DRIFT_GAP = diagnosticGapLabels("cursor")[2];
+const CURSOR_AGENT_DRIFT_GAP = diagnosticGapLabels("cursor")[3];
+// Cursor-agent
+const CURSOR_AGENT_HOME_CHECK = diagnosticCheckNames("cursor-agent")[0];
+const CURSOR_AGENT_WARN_STATUS = diagnosticStatusLabels("cursor-agent")[1];
+const CURSOR_AGENT_USER_ENVIRONMENT_GAP = diagnosticGapLabels("cursor-agent")[1];
+export function diagnoseClaude(installRoot, _home, env) {
+    const value = env.CLAUDE_PLUGIN_ROOT;
+    let checks;
+    if (!value) {
+        checks = [
+            mkCheck(CLAUDE_ROOT_CHECK, CLAUDE_WARN_STATUS, CLAUDE_MISSING_ENV_MESSAGE, {
+                source: "environment",
+                gap: CLAUDE_USER_ENVIRONMENT_GAP,
+            }),
+        ];
+    }
+    else {
+        checks = [
+            configuredRootCheck("claude", CLAUDE_ROOT_CHECK, resolvePath(expanduser(value)), installRoot, "environment"),
+        ];
+    }
+    return runtimeResult("claude", env, checks);
+}
+export function diagnoseOpencode(installRoot, home, env) {
+    const checks = [];
+    const configDir = opencodeConfigDir(home, env);
+    const plugin = path.join(configDir, "plugins", "agentera.js");
+    if (isFile(plugin)) {
+        checks.push(mkCheck(OPENCODE_PLUGIN_CHECK, OPENCODE_PASS_STATUS, OPENCODE_PLUGIN_PRESENT_MESSAGE, { path: plugin }));
+    }
+    else {
+        checks.push(mkCheck(OPENCODE_PLUGIN_CHECK, OPENCODE_WARN_STATUS, OPENCODE_PLUGIN_MISSING_MESSAGE, {
+            path: plugin,
+            gap: OPENCODE_RUNTIME_CONFIG_GAP,
+        }));
+    }
+    if (env.AGENTERA_HOME) {
+        const p = resolvePath(expanduser(env.AGENTERA_HOME));
+        checks.push(configuredRootCheck("opencode", OPENCODE_HOME_CHECK, p, installRoot, "environment"));
+    }
+    else {
+        const candidates = [
+            ["default-install-root", path.join(home, ".agents", "agentera")],
+            ["default-skill-root", path.join(home, ".agents", "skills", "agentera")],
+        ];
+        const existing = candidates.filter(([, p]) => pathExists(p));
+        if (existing.length > 0) {
+            const [source, p] = existing[0];
+            checks.push(configuredRootCheck("opencode", OPENCODE_HOME_CHECK, resolvePath(p), installRoot, source));
+        }
+        else {
+            checks.push(mkCheck(OPENCODE_HOME_CHECK, OPENCODE_WARN_STATUS, OPENCODE_HOME_MISSING_MESSAGE, {
+                source: "environment/defaults",
+                gap: OPENCODE_RUNTIME_CONFIG_GAP,
+            }));
+        }
+    }
+    checks.push(diagnoseOpencodeCommands(home, env));
+    checks.push(diagnoseOpencodeSkillPaths(installRoot, home, env));
+    checks.push(diagnoseBundledReferenceValidation(installRoot));
+    return runtimeResult("opencode", env, checks);
+}
+function copilotRcPaths(home) {
+    return [
+        path.join(home, ".bashrc"),
+        path.join(home, ".zshrc"),
+        path.join(home, ".config", "fish", "config.fish"),
+    ];
+}
+function extractCopilotMarkerRoot(text) {
+    const lines = text.split(/\r\n|\r|\n/);
+    for (let index = 0; index < lines.length; index++) {
+        if (lines[index].replace(/\s+$/, "") !== COPILOT_MARKER)
+            continue;
+        if (index + 1 >= lines.length)
+            return null;
+        const exportLine = lines[index + 1].trim();
+        for (const prefix of ['export AGENTERA_HOME="', 'set -x AGENTERA_HOME "']) {
+            if (exportLine.startsWith(prefix) && exportLine.endsWith('"')) {
+                return exportLine.slice(prefix.length, -1);
+            }
+        }
+    }
+    return null;
+}
+function copilotShellManualBoundaryMessage(prefix = "") {
+    const lead = prefix ? `${prefix} ` : "";
+    return (`${lead}Agentera will not edit shell startup files; cleanup is a ` +
+        "user-owned manual boundary. For Copilot app context, pass " +
+        "AGENTERA_HOME for a single invocation or use runtime-native " +
+        "environment support when available.");
+}
+export function diagnoseCopilot(installRoot, home, env) {
+    const value = env.AGENTERA_HOME;
+    if (value) {
+        const checks = [
+            configuredRootCheck("copilot", COPILOT_HOME_CHECK, resolvePath(expanduser(value)), installRoot, "environment"),
+        ];
+        return runtimeResult("copilot", env, checks);
+    }
+    for (const rcPath of copilotRcPaths(home)) {
+        if (!isFile(rcPath))
+            continue;
+        const rcText = fs.readFileSync(rcPath, "utf8");
+        const markerRoot = extractCopilotMarkerRoot(rcText);
+        if (markerRoot === null)
+            continue;
+        const check = configuredRootCheck("copilot", COPILOT_HOME_CHECK, resolvePath(expanduser(markerRoot)), installRoot, rcPath);
+        if (check.status === COPILOT_PASS_STATUS) {
+            check.message = COPILOT_RC_CONFIGURED_MESSAGE;
+        }
+        check.message = copilotShellManualBoundaryMessage(check.message);
+        return runtimeResult("copilot", env, [check]);
+    }
+    const checks = [
+        mkCheck(COPILOT_HOME_CHECK, COPILOT_WARN_STATUS, COPILOT_MISSING_MESSAGE, {
+            source: "environment/rc",
+            gap: COPILOT_RUNTIME_CONFIG_GAP,
+        }),
+    ];
+    return runtimeResult("copilot", env, checks);
+}
+export function readCodexAgenteraHome(configPath) {
+    if (!isFile(configPath))
+        return [null, "missing"];
+    let data;
+    try {
+        data = parseTomlLocal(fs.readFileSync(configPath, "utf8"));
+    }
+    catch (exc) {
+        return [null, `invalid TOML: ${exc.message}`];
+    }
+    const policy = data.shell_environment_policy;
+    if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+        return [null, "missing shell_environment_policy.set.AGENTERA_HOME"];
+    }
+    const setTable = policy.set;
+    if (!setTable || typeof setTable !== "object" || Array.isArray(setTable)) {
+        return [null, "missing shell_environment_policy.set.AGENTERA_HOME"];
+    }
+    const value = setTable.AGENTERA_HOME;
+    if (typeof value !== "string" || !value) {
+        return [null, "missing shell_environment_policy.set.AGENTERA_HOME"];
+    }
+    return [value, null];
+}
+export function diagnoseCodex(installRoot, home, env) {
+    const config = path.join(home, ".codex", "config.toml");
+    const [value, error] = readCodexAgenteraHome(config);
+    let checks;
+    if (error !== null) {
+        const status = error === "missing" || error.startsWith("missing ") ? CODEX_WARN_STATUS : CODEX_FAIL_STATUS;
+        checks = [
+            mkCheck(CODEX_HOME_CHECK, status, `${CODEX_CONFIG_ERROR_MESSAGE}: ${error}`, {
+                source: config,
+                path: config,
+                gap: CODEX_RUNTIME_CONFIG_GAP,
+            }),
+        ];
+    }
+    else {
+        checks = [
+            configuredRootCheck("codex", CODEX_HOME_CHECK, resolvePath(expanduser(value)), installRoot, config),
+        ];
+    }
+    return runtimeResult("codex", env, checks);
+}
+function globMdFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((e) => e.endsWith(".md") && isFile(path.join(dir, e))).sort();
+}
+export function diagnoseCursor(installRoot, home, env) {
+    const checks = [];
+    const value = env.AGENTERA_HOME;
+    if (value) {
+        checks.push(configuredRootCheck("cursor", CURSOR_HOME_CHECK, resolvePath(expanduser(value)), installRoot, "environment"));
+    }
+    else {
+        checks.push(mkCheck(CURSOR_HOME_CHECK, CURSOR_WARN_STATUS, CURSOR_HELPER_MESSAGE, {
+            source: "environment",
+            gap: CURSOR_USER_ENVIRONMENT_GAP,
+        }));
+    }
+    const hooksPath = path.join(installRoot, ".cursor", "hooks.json");
+    if (isFile(hooksPath)) {
+        const text = fs.readFileSync(hooksPath, "utf8");
+        if (text.includes("cursor_session_start.py") && text.includes("cursor_pre_tool_use.py")) {
+            checks.push(mkCheck(CURSOR_HOOKS_CHECK, CURSOR_PASS_STATUS, "Cursor hooks.json is present and references Agentera helpers", {
+                path: hooksPath,
+            }));
+        }
+        else {
+            checks.push(mkCheck(CURSOR_HOOKS_CHECK, CURSOR_WARN_STATUS, "Cursor hooks.json is present but missing Agentera hook references", {
+                path: hooksPath,
+                gap: CURSOR_HOOK_DRIFT_GAP,
+            }));
+        }
+    }
+    else {
+        checks.push(mkCheck(CURSOR_HOOKS_CHECK, CURSOR_FAIL_STATUS, "Cursor hooks.json is missing", {
+            path: hooksPath,
+            gap: CURSOR_HOOK_DRIFT_GAP,
+        }));
+    }
+    const agentsDir = path.join(installRoot, ".cursor", "agents");
+    const managed = globMdFiles(agentsDir);
+    if (managed.length >= 12) {
+        checks.push(mkCheck(CURSOR_AGENTS_CHECK, CURSOR_PASS_STATUS, "Cursor managed capability agents are current", {
+            path: agentsDir,
+            details: managed,
+        }));
+    }
+    else if (managed.length > 0) {
+        checks.push(mkCheck(CURSOR_AGENTS_CHECK, CURSOR_WARN_STATUS, `Cursor managed agents incomplete (${managed.length}/12)`, {
+            path: agentsDir,
+            gap: CURSOR_AGENT_DRIFT_GAP,
+        }));
+    }
+    else {
+        checks.push(mkCheck(CURSOR_AGENTS_CHECK, CURSOR_FAIL_STATUS, "Cursor managed capability agents are missing", {
+            path: agentsDir,
+            gap: CURSOR_AGENT_DRIFT_GAP,
+        }));
+    }
+    return runtimeResult("cursor", env, checks);
+}
+export function diagnoseCursorAgent(installRoot, _home, env) {
+    const checks = [];
+    const value = env.AGENTERA_HOME;
+    if (value) {
+        checks.push(configuredRootCheck("cursor-agent", CURSOR_AGENT_HOME_CHECK, resolvePath(expanduser(value)), installRoot, "environment"));
+    }
+    else {
+        checks.push(mkCheck(CURSOR_AGENT_HOME_CHECK, CURSOR_AGENT_WARN_STATUS, "cursor-agent helper access depends on AGENTERA_HOME or shell rc configuration", { source: "environment", gap: CURSOR_AGENT_USER_ENVIRONMENT_GAP }));
+    }
+    return runtimeResult("cursor-agent", env, checks);
+}
+export const DIAGNOSTICS = {
+    claude: diagnoseClaude,
+    opencode: diagnoseOpencode,
+    copilot: diagnoseCopilot,
+    codex: diagnoseCodex,
+    cursor: diagnoseCursor,
+    "cursor-agent": diagnoseCursorAgent,
+};
+// ===========================================================================
+// Slice 4: build_report, renderers, installer, CLI
+// ===========================================================================
+import { planChange as codexPlanChange } from "./codex.js";
+/** Python json.dumps(obj, indent=2, sort_keys=True, ensure_ascii=True). */
+function jsonAscii(str) {
+    let out = '"';
+    for (const ch of str) {
+        const cp = ch.codePointAt(0);
+        if (ch === '"')
+            out += '\\"';
+        else if (ch === "\\")
+            out += "\\\\";
+        else if (cp === 0x08)
+            out += "\\b";
+        else if (cp === 0x09)
+            out += "\\t";
+        else if (cp === 0x0a)
+            out += "\\n";
+        else if (cp === 0x0c)
+            out += "\\f";
+        else if (cp === 0x0d)
+            out += "\\r";
+        else if (cp < 0x20)
+            out += "\\u" + cp.toString(16).padStart(4, "0");
+        else if (cp < 0x80)
+            out += ch;
+        else if (cp > 0xffff) {
+            const v = cp - 0x10000;
+            out += "\\u" + (0xd800 + (v >> 10)).toString(16).padStart(4, "0");
+            out += "\\u" + (0xdc00 + (v & 0x3ff)).toString(16).padStart(4, "0");
+        }
+        else
+            out += "\\u" + cp.toString(16).padStart(4, "0");
+    }
+    return out + '"';
+}
+export function pyJsonIndent(value, level = 0) {
+    const pad = "  ".repeat(level);
+    const padIn = "  ".repeat(level + 1);
+    if (value === null || value === undefined)
+        return "null";
+    if (value === true)
+        return "true";
+    if (value === false)
+        return "false";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? String(value) : String(value);
+    if (typeof value === "string")
+        return jsonAscii(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        const items = value.map((v) => padIn + pyJsonIndent(v, level + 1));
+        return "[\n" + items.join(",\n") + "\n" + pad + "]";
+    }
+    if (typeof value === "object") {
+        const keys = Object.keys(value).sort();
+        if (keys.length === 0)
+            return "{}";
+        const items = keys.map((k) => padIn + jsonAscii(k) + ": " + pyJsonIndent(value[k], level + 1));
+        return "{\n" + items.join(",\n") + "\n" + pad + "}";
+    }
+    return "null";
+}
+function summarize(runtimes) {
+    return summarizeStatuses(runtimes);
+}
+export function buildReport(opts = {}) {
+    const runtimes = opts.runtimes ?? RUNTIMES;
+    const liveModelAllowed = opts.liveModelAllowed ?? false;
+    const sourceEnv = { ...(opts.env ?? process.env) };
+    const rootReport = classifyInstallRoot(opts.installRoot ?? null, sourceEnv);
+    const rootPath = rootReport.path ? rootReport.path : null;
+    const homePath = resolvePath(expanduser(opts.home ?? os.homedir()));
+    const runtimeReports = {};
+    if (rootPath === null || rootReport.status === "fail") {
+        for (const runtime of runtimes) {
+            runtimeReports[runtime] = runtimeResult(runtime, sourceEnv, [
+                mkCheck("install_root", "fail", "runtime diagnosis requires a valid Agentera install root", {
+                    gap: rootReport.gap,
+                    details: rootReport.missing,
+                }),
+            ]);
+        }
+    }
+    else {
+        for (const runtime of runtimes) {
+            runtimeReports[runtime] = DIAGNOSTICS[runtime](rootPath, homePath, sourceEnv);
+        }
+    }
+    const summaryCounts = summarize(runtimeReports);
+    const emptySummary = {};
+    for (const status of STATUSES)
+        emptySummary[status] = 0;
+    let smokeReport = {
+        enabled: false,
+        liveModelAllowed,
+        modelCallsAttempted: false,
+        summary: emptySummary,
+        checks: [],
+    };
+    if (opts.runSmoke) {
+        throw new Error("setup doctor --smoke is not yet ported (pending Phase 9 node hook invocation)");
+    }
+    const ok = rootReport.status !== "fail" && summaryCounts.fail === 0 && smokeReport.summary.fail === 0;
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok,
+        installRoot: rootReport,
+        runtimes: runtimeReports,
+        summary: summaryCounts,
+        smoke: smokeReport,
+    };
+}
+export function renderHuman(report) {
+    const lines = [
+        "Agentera setup doctor",
+        `install root: ${report.installRoot.status} - ${report.installRoot.message}`,
+    ];
+    if (report.installRoot.path)
+        lines.push(`  path: ${report.installRoot.path}`);
+    if (report.installRoot.missing && report.installRoot.missing.length > 0) {
+        lines.push("  missing: " + report.installRoot.missing.join(", "));
+    }
+    for (const [runtime, result] of Object.entries(report.runtimes)) {
+        lines.push(`${runtime}: ${result.status}`);
+        for (const check of result.checks) {
+            const suffix = check.gap ? ` [${check.gap}]` : "";
+            lines.push(`  - ${check.name}: ${check.status} - ${check.message}${suffix}`);
+            if (check.path)
+                lines.push(`    path: ${check.path}`);
+            if (check.details && check.details.length > 0)
+                lines.push("    details: " + check.details.join(", "));
+        }
+    }
+    const smoke = report.smoke ?? {};
+    if (smoke.enabled) {
+        lines.push("smoke: enabled");
+        lines.push(`  model calls attempted: ${pyBool(smoke.modelCallsAttempted)}`);
+        for (const check of (smoke.checks ?? [])) {
+            lines.push(`  - ${check.name}: ${check.status} - ${check.message} [${check.category}]`);
+            if (check.path)
+                lines.push(`    path: ${check.path}`);
+            if (check.details && check.details.length > 0)
+                lines.push("    details: " + check.details.join(", "));
+        }
+    }
+    return lines.join("\n");
+}
+function pyBool(value) {
+    return value ? "True" : "False";
+}
+export function renderInstaller(installer) {
+    const lines = ["Agentera setup installer", `status: ${installer.message}`];
+    if (!installer.changes || installer.changes.length === 0)
+        return lines.join("\n");
+    for (const change of installer.changes) {
+        lines.push(`${change.runtime}: ${change.status}`);
+        lines.push(`  target: ${change.target || "(none)"}`);
+        lines.push(`  reason: ${change.reason}`);
+        lines.push(`  action: ${change.action} - ${change.message}`);
+    }
+    if (installer.afterDoctor !== null && installer.afterDoctor !== undefined) {
+        const after = installer.afterDoctor;
+        lines.push(`doctor after install: ${after.ok ? "pass" : "fail"} (summary: ${pyDict(after.summary)})`);
+    }
+    else if (installer.summary.pending && !installer.dryRun) {
+        lines.push("confirmation required: re-run with --yes to apply these changes");
+    }
+    return lines.join("\n");
+}
+/** Python str(dict) repr for the summary line. */
+function pyDict(obj) {
+    const parts = Object.entries(obj).map(([k, v]) => `'${k}': ${typeof v === "string" ? `'${v}'` : v}`);
+    return "{" + parts.join(", ") + "}";
+}
+export function publicInstaller(installer) {
+    if (installer === null)
+        return null;
+    const pub = { ...installer };
+    pub.changes = installer.changes.map((change) => {
+        const c = {};
+        for (const [key, value] of Object.entries(change)) {
+            if (key !== "newText" && key !== "diff")
+                c[key] = value;
+        }
+        return c;
+    });
+    return pub;
+}
+// ── installer ───────────────────────────────────────────────────────
+function installerChange(opts) {
+    return {
+        runtime: opts.runtime,
+        target: opts.target,
+        reason: opts.reason,
+        status: opts.status,
+        action: opts.action,
+        message: opts.message,
+        newText: opts.newText ?? "",
+        diff: opts.diff ?? "",
+    };
+}
+function fixableReason(runtimeReport, checkName, gaps = null) {
+    if (!runtimeReport.available)
+        return null;
+    const runtime = String(runtimeReport.runtime ?? "");
+    const fixableGaps = gaps ?? INSTALLER_FIXABLE_GAPS[runtime] ?? [];
+    for (const check of (runtimeReport.checks ?? [])) {
+        if (check.name !== checkName)
+            continue;
+        if (check.status !== WARN_STATUSES[runtime] && check.status !== FAIL_STATUSES[runtime])
+            continue;
+        if (!fixableGaps.includes(check.gap))
+            continue;
+        return String(check.message || "doctor found a fixable setup gap");
+    }
+    return null;
+}
+function planCodexInstallerChange(installRoot, home, runtimeReport) {
+    const reason = fixableReason(runtimeReport, CODEX_HOME_CHECK, [CODEX_RUNTIME_CONFIG_GAP]);
+    if (reason === null)
+        return null;
+    const target = path.join(home, ".codex", "config.toml");
+    let outcome;
+    try {
+        const currentText = pathExists(target) ? fs.readFileSync(target, "utf8") : null;
+        outcome = codexPlanChange(currentText, installRoot, { force: false });
+    }
+    catch (exc) {
+        return installerChange({
+            runtime: "codex",
+            target,
+            reason,
+            status: "blocked",
+            action: "blocked",
+            message: `cannot safely plan Codex config change: ${exc.message}`,
+        });
+    }
+    if (outcome.action === "noop") {
+        return installerChange({ runtime: "codex", target, reason, status: "noop", action: outcome.action, message: outcome.message });
+    }
+    if (outcome.action === "conflict") {
+        return installerChange({
+            runtime: "codex",
+            target,
+            reason,
+            status: "blocked",
+            action: outcome.action,
+            message: outcome.message,
+            diff: outcome.diff,
+        });
+    }
+    return installerChange({
+        runtime: "codex",
+        target,
+        reason,
+        status: "pending",
+        action: outcome.action,
+        message: outcome.message,
+        newText: outcome.newText,
+        diff: outcome.diff,
+    });
+}
+function planCopilotInstallerChange() {
+    return null;
+}
+function summarizeInstaller(changes) {
+    const statuses = ["pending", "applied", "noop", "blocked", "failed"];
+    const summary = {};
+    for (const status of statuses)
+        summary[status] = 0;
+    for (const change of changes)
+        summary[change.status] += 1;
+    return summary;
+}
+export function buildInstallerPlan(report, opts) {
+    const changes = [];
+    const rootPath = report.installRoot?.path;
+    if (!rootPath || report.installRoot?.status === "fail") {
+        return {
+            schemaVersion: INSTALLER_SCHEMA_VERSION,
+            confirmed: opts.confirmed,
+            dryRun: opts.dryRun,
+            changes,
+            summary: summarizeInstaller(changes),
+            afterDoctor: null,
+            message: "installer requires a valid Agentera install root",
+        };
+    }
+    const installRoot = rootPath;
+    for (const runtime of opts.runtimes) {
+        const runtimeReport = report.runtimes[runtime];
+        let change = null;
+        if (runtime === "codex")
+            change = planCodexInstallerChange(installRoot, opts.home, runtimeReport);
+        else if (runtime === "copilot")
+            change = planCopilotInstallerChange();
+        if (change !== null)
+            changes.push(change);
+    }
+    return {
+        schemaVersion: INSTALLER_SCHEMA_VERSION,
+        confirmed: opts.confirmed,
+        dryRun: opts.dryRun,
+        changes,
+        summary: summarizeInstaller(changes),
+        afterDoctor: null,
+        message: changes.length === 0 ? "no installer changes needed" : "installer changes planned",
+    };
+}
+export function applyInstallerPlan(plan) {
+    for (const change of plan.changes) {
+        if (change.status !== "pending")
+            continue;
+        const target = change.target;
+        try {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, change.newText, "utf8");
+        }
+        catch (exc) {
+            change.status = "failed";
+            change.message = `error writing ${target}: ${exc.message}`;
+            continue;
+        }
+        change.status = "applied";
+        change.message = `wrote ${target}: ${String(change.message).replaceAll("would ", "")}`;
+    }
+    plan.summary = summarizeInstaller(plan.changes);
+}
+export function doctorMain(argv = [], io = {}) {
+    const writeOut = io.out ?? ((text) => process.stdout.write(text));
+    const writeErr = io.err ?? ((text) => process.stderr.write(text));
+    const out = (line) => writeOut(line + "\n");
+    const env = io.env ?? process.env;
+    const args = {
+        installRoot: null,
+        home: null,
+        runtime: [],
+        smoke: false,
+        install: false,
+        yes: false,
+        dryRun: false,
+        allowLiveModel: false,
+        json: false,
+    };
+    const valueFlag = (a, name) => {
+        if (a === name)
+            return "__NEXT__";
+        if (a.startsWith(name + "="))
+            return a.slice(name.length + 1);
+        return null;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        let v;
+        if ((v = valueFlag(a, "--install-root")) !== null)
+            args.installRoot = v === "__NEXT__" ? argv[++i] : v;
+        else if ((v = valueFlag(a, "--home")) !== null)
+            args.home = v === "__NEXT__" ? argv[++i] : v;
+        else if ((v = valueFlag(a, "--runtime")) !== null) {
+            const rt = v === "__NEXT__" ? argv[++i] : v;
+            if (!RUNTIMES.includes(rt)) {
+                writeErr(`setup_doctor: error: argument --runtime: invalid choice: '${rt}'\n`);
+                return 2;
+            }
+            args.runtime.push(rt);
+        }
+        else if (a === "--smoke")
+            args.smoke = true;
+        else if (a === "--install")
+            args.install = true;
+        else if (a === "--yes")
+            args.yes = true;
+        else if (a === "--dry-run")
+            args.dryRun = true;
+        else if (a === "--allow-live-model")
+            args.allowLiveModel = true;
+        else if (a === "--json")
+            args.json = true;
+        else {
+            writeErr(`setup_doctor: error: unrecognized arguments: ${a}\n`);
+            return 2;
+        }
+    }
+    if (args.yes && !args.install) {
+        writeErr("setup_doctor: error: --yes requires --install\n");
+        return 2;
+    }
+    if (args.dryRun && !args.install) {
+        writeErr("setup_doctor: error: --dry-run requires --install\n");
+        return 2;
+    }
+    const runtimes = args.runtime.length > 0 ? args.runtime : RUNTIMES;
+    const sourceEnv = { ...env };
+    const home = resolvePath(expanduser(args.home ?? os.homedir()));
+    const report = buildReport({
+        installRoot: args.installRoot,
+        home,
+        env: sourceEnv,
+        runtimes,
+        runSmoke: args.smoke,
+        liveModelAllowed: args.allowLiveModel,
+    });
+    let installer = null;
+    if (args.install) {
+        installer = buildInstallerPlan(report, {
+            home,
+            env: sourceEnv,
+            runtimes,
+            confirmed: args.yes,
+            dryRun: args.dryRun,
+        });
+        if (args.yes) {
+            applyInstallerPlan(installer);
+            installer.afterDoctor = buildReport({
+                installRoot: args.installRoot,
+                home,
+                env: sourceEnv,
+                runtimes,
+                runSmoke: args.smoke,
+                liveModelAllowed: args.allowLiveModel,
+            });
+        }
+    }
+    if (args.json) {
+        const payload = installer !== null ? { doctor: report, installer: publicInstaller(installer) } : report;
+        out(pyJsonIndent(payload));
+    }
+    else {
+        out(renderHuman(report));
+        if (installer !== null) {
+            out("");
+            out(renderInstaller(installer));
+        }
+    }
+    if (installer === null)
+        return report.ok ? 0 : 1;
+    if (installer.summary.failed || installer.summary.blocked)
+        return 1;
+    if (installer.summary.pending && !args.dryRun && !args.yes)
+        return 1;
+    if (installer.afterDoctor !== null && installer.afterDoctor !== undefined && !installer.afterDoctor.ok)
+        return 1;
+    if (!report.ok && !(installer.summary.pending || installer.summary.applied))
+        return 1;
+    return 0;
+}
+//# sourceMappingURL=doctor.js.map