crewhaus 0.1.8 → 0.2.1

package/dist/doctor-checks.js

@@ -1,6 +1,8 @@
 import { resolveAuth } from "@crewhaus/adapter-anthropic";
+import { lower } from "@crewhaus/compiler";
 import { parseModelString } from "@crewhaus/model-router";
 import { parseSpec } from "@crewhaus/spec";
+import { CHANNEL_PLATFORMS, platformSecretRefs } from "./channel-provision";
 function isSet(env, name) {
     const v = env[name];
     return typeof v === "string" && v !== "";
@@ -104,6 +106,21 @@ function statusFor(provider, env) {
             };
     }
 }
+/**
+ * Item 13 — online/offline mode selection for `crewhaus scaffold-evals`:
+ * true when the provider `model` routes to has visibly satisfied credentials
+ * (shares `statusFor` with the doctor checks, so the two never disagree).
+ * Unparseable model strings return false — the scaffold then stays on its
+ * deterministic template path instead of attempting a doomed call. Note the
+ * bedrock check is env-visible only (the AWS SDK's default chain may still
+ * work); scaffold prefers the safe offline mode in that ambiguity.
+ */
+export function providerCredentialsSatisfied(model, env) {
+    const provider = selectedProvider(model);
+    if (provider === undefined)
+        return false;
+    return statusFor(provider, env).satisfied;
+}
 const PROVIDER_LABEL = {
     anthropic: "Anthropic credentials",
     openai: "OpenAI credentials",
@@ -111,6 +128,25 @@ const PROVIDER_LABEL = {
     bedrock: "Bedrock (AWS) credentials",
     local: "Local endpoint",
 };
+/**
+ * Item 40 — the canonical env var(s) `doctor --fix` stubs into `.env` for a
+ * provider whose credential check is failing. One representative name per
+ * provider (the first the status check reads); bedrock/local need no stub
+ * (bedrock uses the SDK default chain; local bakes the URL into the model
+ * string), so they map to []. Kept next to the status tables so the stub set
+ * can't drift from what the checks actually probe.
+ */
+const PROVIDER_ENV_STUBS = {
+    anthropic: ["ANTHROPIC_API_KEY"],
+    openai: ["OPENAI_API_KEY"],
+    gemini: ["GEMINI_API_KEY"],
+    bedrock: [],
+    local: [],
+};
+/** Env var names `doctor --fix` should stub for a selected provider. */
+export function providerEnvStubs(provider) {
+    return PROVIDER_ENV_STUBS[provider];
+}
 /** Providers whose env check is INFORMATIONAL even when selected: the AWS
  *  SDK's default credential chain is authoritative for bedrock (env vars are
  *  only one of its sources), and local/ endpoints need no credentials. */
@@ -176,3 +212,59 @@ export function buildCredentialChecks(specModel, env) {
     checks.push({ label: "Anthropic credentials", pass: false, reason: anthropic.detail });
     return checks;
 }
+/**
+ * Item 61 — tolerantly extract the lowered channels block from a
+ * crewhaus.yaml text. Returns undefined when the spec doesn't parse/lower or
+ * is not a channel target, mirroring {@link extractSpecModel}'s tolerance —
+ * doctor must never fail because the cwd spec is a different shape. Lowering
+ * (not raw parsing) is deliberate: `lower()` is where `$VAR_NAME` strings
+ * become env-refs, so the check shares the compiled daemon's exact env
+ * semantics instead of re-implementing the regex.
+ */
+export function extractChannelIr(yamlText) {
+    try {
+        const ir = lower(parseSpec(yamlText));
+        return ir.target === "channel" ? ir.channels : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Item 61 — channel-target doctor checks: one per configured platform
+ * (slack/telegram/discord), asserting that every secret env-ref the compiled
+ * daemon requires at boot (target-channel-bot's startup check exits 2 on the
+ * same set) is actually set. Returns [] for non-channel specs, so the check
+ * only appears when the cwd spec is a channel target. Offline by design —
+ * live platform probes (granted scopes, webhook state) belong to
+ * `crewhaus channel verify`, which the failure reason points at.
+ */
+export function buildChannelEnvChecks(yamlText, env) {
+    const channels = extractChannelIr(yamlText);
+    if (channels === undefined)
+        return [];
+    const checks = [];
+    for (const platform of CHANNEL_PLATFORMS) {
+        const refs = platformSecretRefs(platform, channels);
+        if (refs.length === 0)
+            continue;
+        const envNames = refs.flatMap((r) => (r.ref.kind === "env" ? [r.ref.name] : []));
+        const missing = envNames.filter((name) => !isSet(env, name)).map((name) => `$${name}`);
+        const label = envNames.length > 0
+            ? `${PLATFORM_TITLE[platform]} channel env (${envNames.join(", ")})`
+            : `${PLATFORM_TITLE[platform]} channel env (inline literals)`;
+        checks.push(missing.length === 0
+            ? { label, pass: true }
+            : {
+                label,
+                pass: false,
+                reason: `unset: ${missing.join(", ")} — the compiled daemon exits at boot without them; run \`crewhaus channel verify\` for live platform probes`,
+            });
+    }
+    return checks;
+}
+const PLATFORM_TITLE = {
+    slack: "Slack",
+    telegram: "Telegram",
+    discord: "Discord",
+};

package/dist/doctor-detect.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Item 40 — `crewhaus doctor --detect`. The read-only INVENTORY half of the
+ * "doctor that detects and fixes" pair (the mutating half is `doctor-fix.ts`).
+ *
+ * Nothing in the CLI reads a local Ollama/vLLM endpoint, a `.mcp.json`, or a
+ * Claude Desktop config today — `doctor` only checks whether the cwd spec's
+ * provider env is set. `--detect` builds an inventory of what's ACTUALLY
+ * available so `init --interactive` (#39) can prefill model/mcp choices and an
+ * operator can see, in one command, which providers/models/servers they can
+ * reach without editing a spec first.
+ *
+ * Side-effect-free and directly unit-testable, mirroring `doctor-checks.ts` /
+ * `scope-audit.ts`: every ambient dependency (env, fs reads, the localhost
+ * HTTP probe) is an INJECTED seam so tests drive the inventory from fixtures
+ * with no real network or filesystem.
+ */
+/** A reachable model provider inferred purely from visible env vars. */
+export type DetectedProvider = {
+    readonly id: "anthropic" | "openai" | "gemini" | "bedrock";
+    readonly label: string;
+    /** The env var(s) that made this provider look reachable. */
+    readonly via: readonly string[];
+};
+/** An MCP server discovered in a `.mcp.json` or Claude Desktop config. */
+export type DetectedMcpServer = {
+    readonly name: string;
+    readonly source: string;
+    readonly transport: "stdio" | "sse" | "unknown";
+    /** stdio command (best-effort) or sse url, for the operator's eyes. */
+    readonly detail?: string;
+};
+/** A local OpenAI-compatible endpoint (Ollama / vLLM / LM Studio, …). */
+export type DetectedLocalEndpoint = {
+    readonly baseUrl: string;
+    readonly reachable: boolean;
+    /** Model ids the endpoint advertises at `/models`, when reachable. */
+    readonly models: readonly string[];
+    /** Populated when the probe failed — why it is not reachable. */
+    readonly error?: string;
+};
+export type DetectInventory = {
+    readonly providers: readonly DetectedProvider[];
+    readonly local: DetectedLocalEndpoint;
+    readonly mcpServers: readonly DetectedMcpServer[];
+};
+/**
+ * Infer which model providers are reachable from visible env vars alone. This
+ * shares the credential-name tables with `doctor-checks.ts` but answers a
+ * different question: not "does the cwd spec's provider have creds" but "which
+ * providers COULD I use right now". Bedrock's default credential chain (IRSA /
+ * instance profile / ~/.aws) is not inspected here — only the env surface — so
+ * a machine on an instance profile with no AWS env vars reports no bedrock,
+ * which is the honest offline answer.
+ */
+export declare function detectProviders(env: NodeJS.ProcessEnv): DetectedProvider[];
+/**
+ * The base URL the local probe hits: `OPENAI_BASE_URL` when set (a vLLM /
+ * LM Studio endpoint the operator already pointed at), else the router's
+ * `LOCAL_DEFAULT_BASE_URL` (`http://localhost:11434/v1`, the Ollama default
+ * that `local/<m>@<url>` bakes in when no `@url` is given).
+ */
+export declare function localBaseUrl(env: NodeJS.ProcessEnv): string;
+/** Injected HTTP seam so the localhost probe is testable without a network. */
+export type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/**
+ * Probe an OpenAI-compatible endpoint's `/models` list. Ollama, vLLM, and
+ * LM Studio all serve `GET <base>/models` → `{ data: [{ id }, …] }`. Never
+ * throws: an unreachable endpoint (connection refused, timeout, non-200,
+ * malformed body) yields `{ reachable: false, models: [], error }` so
+ * `--detect` degrades to a one-line "not running" note rather than failing.
+ */
+export declare function probeLocalEndpoint(baseUrl: string, fetchImpl: FetchLike): Promise<DetectedLocalEndpoint>;
+/**
+ * Parse an MCP server map out of a `.mcp.json` (Claude Code / crewhaus format:
+ * `{ mcpServers: { name: { command | url, … } } }`) or a Claude Desktop config
+ * (identical `mcpServers` shape). Tolerant: a malformed file, a missing
+ * `mcpServers` key, or a non-object entry contributes nothing rather than
+ * throwing — `--detect` must never fail because a config file is junk.
+ */
+export declare function parseMcpConfig(text: string, source: string): DetectedMcpServer[];
+/**
+ * Assemble the full inventory. `readConfig(path)` returns the file text or
+ * `undefined` when absent/unreadable (injected fs seam); `configPaths` is the
+ * ordered list of MCP config locations to inspect (cwd `.mcp.json` first, then
+ * the platform Claude Desktop config). Deterministic and pure given its seams.
+ */
+export declare function buildInventory(opts: {
+    readonly env: NodeJS.ProcessEnv;
+    readonly fetchImpl: FetchLike;
+    readonly readConfig: (path: string) => string | undefined;
+    readonly configPaths: readonly string[];
+    /** Skip the localhost probe (e.g. `--detect --no-probe`); default probes. */
+    readonly skipProbe?: boolean;
+}): Promise<DetectInventory>;
+/** Render the inventory as the human-readable `--detect` report block. */
+export declare function formatInventory(inv: DetectInventory): string;
+/**
+ * The platform-specific default Claude Desktop config path. macOS and Windows
+ * only — Linux has no official Claude Desktop build, so it returns undefined
+ * and the inventory just skips that source.
+ */
+export declare function claudeDesktopConfigPath(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string | undefined;

package/dist/doctor-detect.js

@@ -0,0 +1,214 @@
+import { LOCAL_DEFAULT_BASE_URL } from "@crewhaus/model-router";
+function isSet(env, name) {
+    const v = env[name];
+    return typeof v === "string" && v !== "";
+}
+/**
+ * Infer which model providers are reachable from visible env vars alone. This
+ * shares the credential-name tables with `doctor-checks.ts` but answers a
+ * different question: not "does the cwd spec's provider have creds" but "which
+ * providers COULD I use right now". Bedrock's default credential chain (IRSA /
+ * instance profile / ~/.aws) is not inspected here — only the env surface — so
+ * a machine on an instance profile with no AWS env vars reports no bedrock,
+ * which is the honest offline answer.
+ */
+export function detectProviders(env) {
+    const out = [];
+    const anthropicVia = ["ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY"].filter((n) => isSet(env, n));
+    if (anthropicVia.length > 0) {
+        out.push({ id: "anthropic", label: "Anthropic", via: anthropicVia });
+    }
+    const openaiVia = ["OPENAI_API_KEY", "OPENAI_BASE_URL"].filter((n) => isSet(env, n));
+    if (openaiVia.length > 0) {
+        out.push({ id: "openai", label: "OpenAI (or OpenAI-compatible)", via: openaiVia });
+    }
+    const geminiVia = [
+        "GEMINI_API_KEY",
+        "GOOGLE_API_KEY",
+        "GOOGLE_GENAI_USE_VERTEXAI",
+        "GOOGLE_CLOUD_PROJECT",
+    ].filter((n) => isSet(env, n));
+    if (geminiVia.length > 0) {
+        out.push({ id: "gemini", label: "Gemini", via: geminiVia });
+    }
+    const bedrockVia = [
+        "AWS_BEARER_TOKEN_BEDROCK",
+        "AWS_ACCESS_KEY_ID",
+        "AWS_PROFILE",
+        "AWS_REGION",
+    ].filter((n) => isSet(env, n));
+    if (bedrockVia.length > 0) {
+        out.push({ id: "bedrock", label: "Bedrock (AWS)", via: bedrockVia });
+    }
+    return out;
+}
+/**
+ * The base URL the local probe hits: `OPENAI_BASE_URL` when set (a vLLM /
+ * LM Studio endpoint the operator already pointed at), else the router's
+ * `LOCAL_DEFAULT_BASE_URL` (`http://localhost:11434/v1`, the Ollama default
+ * that `local/<m>@<url>` bakes in when no `@url` is given).
+ */
+export function localBaseUrl(env) {
+    const override = env["OPENAI_BASE_URL"];
+    if (typeof override === "string" && override !== "")
+        return override;
+    return LOCAL_DEFAULT_BASE_URL;
+}
+/**
+ * Probe an OpenAI-compatible endpoint's `/models` list. Ollama, vLLM, and
+ * LM Studio all serve `GET <base>/models` → `{ data: [{ id }, …] }`. Never
+ * throws: an unreachable endpoint (connection refused, timeout, non-200,
+ * malformed body) yields `{ reachable: false, models: [], error }` so
+ * `--detect` degrades to a one-line "not running" note rather than failing.
+ */
+export async function probeLocalEndpoint(baseUrl, fetchImpl) {
+    const url = `${baseUrl.replace(/\/+$/, "")}/models`;
+    try {
+        const res = await fetchImpl(url);
+        if (!res.ok) {
+            return { baseUrl, reachable: false, models: [], error: `HTTP ${res.status}` };
+        }
+        const body = (await res.json());
+        const models = Array.isArray(body?.data) === true
+            ? body.data
+                .map((m) => m?.id)
+                .filter((id) => typeof id === "string" && id.length > 0)
+            : [];
+        return { baseUrl, reachable: true, models };
+    }
+    catch (err) {
+        return { baseUrl, reachable: false, models: [], error: err.message };
+    }
+}
+/**
+ * Parse an MCP server map out of a `.mcp.json` (Claude Code / crewhaus format:
+ * `{ mcpServers: { name: { command | url, … } } }`) or a Claude Desktop config
+ * (identical `mcpServers` shape). Tolerant: a malformed file, a missing
+ * `mcpServers` key, or a non-object entry contributes nothing rather than
+ * throwing — `--detect` must never fail because a config file is junk.
+ */
+export function parseMcpConfig(text, source) {
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (root === null || typeof root !== "object")
+        return [];
+    const servers = root.mcpServers;
+    if (servers === null || typeof servers !== "object" || Array.isArray(servers))
+        return [];
+    const out = [];
+    for (const [name, raw] of Object.entries(servers)) {
+        if (raw === null || typeof raw !== "object") {
+            out.push({ name, source, transport: "unknown" });
+            continue;
+        }
+        const cfg = raw;
+        if (typeof cfg.url === "string" && cfg.url !== "") {
+            out.push({ name, source, transport: "sse", detail: cfg.url });
+        }
+        else if (typeof cfg.command === "string" && cfg.command !== "") {
+            const args = Array.isArray(cfg.args) ? cfg.args.filter((a) => typeof a === "string") : [];
+            const detail = [cfg.command, ...args].join(" ");
+            out.push({ name, source, transport: "stdio", detail });
+        }
+        else {
+            out.push({ name, source, transport: "unknown" });
+        }
+    }
+    return out;
+}
+/**
+ * Assemble the full inventory. `readConfig(path)` returns the file text or
+ * `undefined` when absent/unreadable (injected fs seam); `configPaths` is the
+ * ordered list of MCP config locations to inspect (cwd `.mcp.json` first, then
+ * the platform Claude Desktop config). Deterministic and pure given its seams.
+ */
+export async function buildInventory(opts) {
+    const providers = detectProviders(opts.env);
+    const baseUrl = localBaseUrl(opts.env);
+    const local = opts.skipProbe === true
+        ? { baseUrl, reachable: false, models: [], error: "probe skipped" }
+        : await probeLocalEndpoint(baseUrl, opts.fetchImpl);
+    const mcpServers = [];
+    const seen = new Set();
+    for (const path of opts.configPaths) {
+        const text = opts.readConfig(path);
+        if (text === undefined)
+            continue;
+        for (const server of parseMcpConfig(text, path)) {
+            // De-dup by (source-independent) name so the same server declared in
+            // both .mcp.json and Claude Desktop shows once, first source winning.
+            if (seen.has(server.name))
+                continue;
+            seen.add(server.name);
+            mcpServers.push(server);
+        }
+    }
+    return { providers, local, mcpServers };
+}
+/** Render the inventory as the human-readable `--detect` report block. */
+export function formatInventory(inv) {
+    const lines = [];
+    lines.push("inventory (what's reachable right now):");
+    lines.push("");
+    lines.push("  model providers (from env):");
+    if (inv.providers.length === 0) {
+        lines.push("    (none — no provider env vars visible)");
+    }
+    else {
+        for (const p of inv.providers) {
+            lines.push(`    ✓ ${p.label} — via ${p.via.join(", ")}`);
+        }
+    }
+    lines.push("");
+    lines.push(`  local endpoint (${inv.local.baseUrl}):`);
+    if (inv.local.reachable) {
+        if (inv.local.models.length === 0) {
+            lines.push("    ✓ reachable, but advertises no models");
+        }
+        else {
+            lines.push(`    ✓ reachable — ${inv.local.models.length} model(s):`);
+            for (const m of inv.local.models)
+                lines.push(`        ${m}`);
+        }
+    }
+    else {
+        lines.push(`    ✗ not reachable (${inv.local.error ?? "unknown"})`);
+    }
+    lines.push("");
+    lines.push("  MCP servers (from .mcp.json / Claude Desktop config):");
+    if (inv.mcpServers.length === 0) {
+        lines.push("    (none found)");
+    }
+    else {
+        for (const s of inv.mcpServers) {
+            const detail = s.detail !== undefined ? ` — ${s.detail}` : "";
+            lines.push(`    • ${s.name} [${s.transport}]${detail}  (${s.source})`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * The platform-specific default Claude Desktop config path. macOS and Windows
+ * only — Linux has no official Claude Desktop build, so it returns undefined
+ * and the inventory just skips that source.
+ */
+export function claudeDesktopConfigPath(platform, env) {
+    if (platform === "darwin") {
+        const home = env["HOME"];
+        if (home === undefined || home === "")
+            return undefined;
+        return `${home}/Library/Application Support/Claude/claude_desktop_config.json`;
+    }
+    if (platform === "win32") {
+        const appData = env["APPDATA"];
+        if (appData === undefined || appData === "")
+            return undefined;
+        return `${appData}\\Claude\\claude_desktop_config.json`;
+    }
+    return undefined;
+}

package/dist/doctor-fix.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Item 40 — `crewhaus doctor --fix`. The MUTATING half of the "doctor that
+ * detects and fixes" pair. Every doctor check today prints a remediation
+ * string and exits; `--fix` attaches a mechanical fixer to the checks where a
+ * SAFE deterministic fix exists, and leaves the rest advisory.
+ *
+ * Dry-run is the DEFAULT: without `--fix`, doctor plans the fixes and prints a
+ * diff of what it WOULD do; `--fix` opts into applying them. This module is
+ * side-effect-free — it computes {@link FixAction}s over injected fs seams and
+ * a per-fixer planner; the CLI wrapper in `index.ts` executes the plan (or
+ * just prints it) and owns all real I/O. That keeps every fix path
+ * unit-testable from fixtures, mirroring `scope-audit.ts` / `doctor-checks.ts`.
+ */
+/** One planned change. `apply()` performs the real mutation; the CLI calls it
+ *  only when `--fix` is passed. `diff` is the human-readable preview printed in
+ *  both dry-run and applied modes. */
+export type FixAction = {
+    /** Stable id of the check this remediates (for grouping/output). */
+    readonly check: string;
+    /** One-line summary of the change. */
+    readonly summary: string;
+    /** Multi-line diff preview (created/edited content). */
+    readonly diff: string;
+    /** Perform the mutation. Throws on failure; the CLI reports it. */
+    apply(): void;
+};
+/** Injected filesystem seam — every fixer reads/writes through this so the
+ *  planner is pure and testable. Mirrors the node:fs subset the fixers need. */
+export type FixFs = {
+    exists(path: string): boolean;
+    read(path: string): string;
+    write(path: string, content: string): void;
+    mkdirp(path: string): void;
+};
+/**
+ * Fixer 1 — scaffold a missing `crewhaus.yaml`. The check "crewhaus.yaml in
+ * cwd" is advisory today (`run \`crewhaus init\``); `--fix` writes the SAME
+ * minimal cli spec `runInit` scaffolds, so a fresh directory becomes runnable
+ * in one command. `specName` is the cwd basename (matching `init`'s default).
+ * Returns undefined when the spec already exists (nothing to fix).
+ */
+export declare function planScaffoldSpec(opts: {
+    readonly fs: FixFs;
+    readonly specPath: string;
+    readonly specName: string;
+}): FixAction | undefined;
+/**
+ * Fixer 2 — create missing `.crewhaus` state dirs. The runtime resolves the
+ * session store and audit/eval/spec sub-stores under `.crewhaus/`; a missing
+ * root is harmless (the runtime mkdirs on demand) but pre-creating it is a
+ * safe, idempotent convenience the operator can preview. Returns undefined
+ * when the dir already exists.
+ */
+export declare function planCrewhausDirs(opts: {
+    readonly fs: FixFs;
+    readonly crewhausDir: string;
+}): FixAction | undefined;
+export declare function planScopeFix(opts: {
+    readonly fs: FixFs;
+    readonly specPath: string;
+    readonly specTarget: string;
+    readonly toolName: string;
+}): FixAction | undefined;
+/**
+ * Fixer 4 — append commented env stubs to `.env` for the providers a spec
+ * needs but the environment lacks. Commented (so nothing is accidentally set
+ * to a placeholder) and idempotent: a var already present in `.env` (set OR
+ * commented) is skipped. Returns undefined when there is nothing to append.
+ *
+ * `neededVars` is the ordered list of env var names to stub (the caller derives
+ * these from the failing credential checks); each becomes a `# NAME=` line
+ * under a generated header, appended to the existing `.env` (created if
+ * absent).
+ */
+export declare function planEnvStubs(opts: {
+    readonly fs: FixFs;
+    readonly envPath: string;
+    readonly neededVars: readonly string[];
+}): FixAction | undefined;
+/** Format a plan (dry-run or applied) as the `--fix` report block. */
+export declare function formatFixPlan(actions: readonly FixAction[], applied: boolean): string;

package/dist/doctor-fix.js

@@ -0,0 +1,164 @@
+import { applySpecPatch } from "@crewhaus/spec-patch";
+/** Render an "added file" diff block (all `+` lines). */
+function addedDiff(path, content) {
+    const body = content
+        .split("\n")
+        .map((l) => `+ ${l}`)
+        .join("\n");
+    return `--- /dev/null\n+++ ${path}\n${body}`;
+}
+/**
+ * Fixer 1 — scaffold a missing `crewhaus.yaml`. The check "crewhaus.yaml in
+ * cwd" is advisory today (`run \`crewhaus init\``); `--fix` writes the SAME
+ * minimal cli spec `runInit` scaffolds, so a fresh directory becomes runnable
+ * in one command. `specName` is the cwd basename (matching `init`'s default).
+ * Returns undefined when the spec already exists (nothing to fix).
+ */
+export function planScaffoldSpec(opts) {
+    if (opts.fs.exists(opts.specPath))
+        return undefined;
+    const content = `name: ${opts.specName}
+target: cli
+agent:
+  model: claude-opus-4-7
+  instructions: |
+    You are a helpful assistant. Replace these instructions with your
+    agent's actual behavior, persona, and constraints.
+`;
+    return {
+        check: "crewhaus.yaml in cwd",
+        summary: `create ${opts.specPath} (minimal cli spec)`,
+        diff: addedDiff(opts.specPath, content),
+        apply: () => opts.fs.write(opts.specPath, content),
+    };
+}
+/**
+ * Fixer 2 — create missing `.crewhaus` state dirs. The runtime resolves the
+ * session store and audit/eval/spec sub-stores under `.crewhaus/`; a missing
+ * root is harmless (the runtime mkdirs on demand) but pre-creating it is a
+ * safe, idempotent convenience the operator can preview. Returns undefined
+ * when the dir already exists.
+ */
+export function planCrewhausDirs(opts) {
+    if (opts.fs.exists(opts.crewhausDir))
+        return undefined;
+    return {
+        check: ".crewhaus state dir",
+        summary: `create ${opts.crewhausDir}/`,
+        diff: `--- /dev/null\n+++ ${opts.crewhausDir}/  (directory)`,
+        apply: () => opts.fs.mkdirp(opts.crewhausDir),
+    };
+}
+/**
+ * Fixer 3 — mark an outward-reaching tool `scope: external` via a mechanical
+ * CST spec-patch. `auditToolScopes` (surfaced through `doctor
+ * --philosophy-alignment` / `compile --strict`) flags outward sinks left at a
+ * non-external scope; the safe mechanical fix is to set their scope, which
+ * `applySpecPatch` writes back preserving comments + key order.
+ *
+ * NOTE: the built-in `tools:` list is an array of NAME strings — there is no
+ * per-tool `scope` field to patch there (scope is a property of the registered
+ * tool, not the spec reference). This fixer therefore targets a `tool_config`
+ * entry: it sets `tool_config.<name>.scope: "external"`, the documented place a
+ * spec asserts an operator-vetted scope. The patch is validated by
+ * `applySpecPatch` (re-parses through `parseSpec`), so an unpatchable finding
+ * surfaces as a thrown error the CLI reports rather than a silent no-op.
+ *
+ * Returns undefined for findings whose tool name is not a plain identifier
+ * (e.g. an `mcp__*` dynamic sink) — those need human vetting, not a mechanical
+ * scope stamp, so they stay advisory.
+ */
+const PLAIN_TOOL_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
+export function planScopeFix(opts) {
+    // `mcp__server__tool` dynamic sinks match the identifier charset but are
+    // definitionally external and must be vetted by a human, not stamped
+    // mechanically — leave them advisory.
+    if (opts.toolName.startsWith("mcp__"))
+        return undefined;
+    if (!PLAIN_TOOL_NAME_RE.test(opts.toolName))
+        return undefined;
+    const path = ["tool_config", opts.toolName, "scope"];
+    const summary = `set tool_config.${opts.toolName}.scope: "external" in ${opts.specPath}`;
+    return {
+        check: "tool scope audit",
+        summary,
+        diff: `~ ${opts.specPath}: + tool_config.${opts.toolName}.scope: "external"`,
+        apply: () => {
+            const yamlText = opts.fs.read(opts.specPath);
+            const result = applySpecPatchAddOrReplace(yamlText, {
+                target: opts.specTarget,
+                path,
+                value: "external",
+                rationale: "doctor --fix: mark outward tool external (scope audit)",
+            });
+            opts.fs.write(opts.specPath, result);
+        },
+    };
+}
+/** Apply a spec patch as "add", retrying as "replace" when the path exists.
+ *  Both go through `applySpecPatch`, so the result is always re-validated. */
+function applySpecPatchAddOrReplace(yamlText, patch) {
+    try {
+        return applySpecPatch(yamlText, { ...patch, op: "add" }).yaml;
+    }
+    catch {
+        return applySpecPatch(yamlText, { ...patch, op: "replace" }).yaml;
+    }
+}
+/**
+ * Fixer 4 — append commented env stubs to `.env` for the providers a spec
+ * needs but the environment lacks. Commented (so nothing is accidentally set
+ * to a placeholder) and idempotent: a var already present in `.env` (set OR
+ * commented) is skipped. Returns undefined when there is nothing to append.
+ *
+ * `neededVars` is the ordered list of env var names to stub (the caller derives
+ * these from the failing credential checks); each becomes a `# NAME=` line
+ * under a generated header, appended to the existing `.env` (created if
+ * absent).
+ */
+export function planEnvStubs(opts) {
+    if (opts.neededVars.length === 0)
+        return undefined;
+    const existing = opts.fs.exists(opts.envPath) ? opts.fs.read(opts.envPath) : "";
+    // A var is "present" if any line names it as a key, set or commented:
+    //   NAME=...        or        # NAME=...
+    const present = new Set();
+    for (const rawLine of existing.split("\n")) {
+        const m = /^\s*#?\s*([A-Z_][A-Z0-9_]*)\s*=/.exec(rawLine);
+        if (m?.[1] !== undefined)
+            present.add(m[1]);
+    }
+    const toAdd = opts.neededVars.filter((v) => !present.has(v));
+    if (toAdd.length === 0)
+        return undefined;
+    const header = "# added by `crewhaus doctor --fix` — fill in and uncomment";
+    const stubLines = [header, ...toAdd.map((v) => `# ${v}=`)];
+    const stubBlock = stubLines.join("\n");
+    const needsLeadingNewline = existing !== "" && !existing.endsWith("\n");
+    const appended = `${existing}${needsLeadingNewline ? "\n" : ""}${stubBlock}\n`;
+    return {
+        check: "provider credentials",
+        summary: `append ${toAdd.length} commented env stub(s) to ${opts.envPath}`,
+        diff: [`~ ${opts.envPath}:`, ...stubLines.map((l) => `+ ${l}`)].join("\n"),
+        apply: () => opts.fs.write(opts.envPath, appended),
+    };
+}
+/** Format a plan (dry-run or applied) as the `--fix` report block. */
+export function formatFixPlan(actions, applied) {
+    if (actions.length === 0) {
+        return applied
+            ? "doctor --fix: nothing to fix — all mechanical checks already clean.\n"
+            : "doctor --fix (dry-run): nothing to fix — all mechanical checks already clean.\n";
+    }
+    const lines = [];
+    lines.push(applied
+        ? `doctor --fix: applied ${actions.length} fix(es):`
+        : `doctor --fix (dry-run): ${actions.length} fix(es) available — re-run with --fix to apply:`);
+    for (const a of actions) {
+        lines.push("");
+        lines.push(`  [${a.check}] ${a.summary}`);
+        for (const dl of a.diff.split("\n"))
+            lines.push(`    ${dl}`);
+    }
+    return `${lines.join("\n")}\n`;
+}