@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.2

package/dist/core/doctor/agents.js

@@ -0,0 +1,222 @@
+/**
+ * The agent surface: which tool files this repo should hold, which it does, and
+ * whether they still describe this binary.
+ *
+ * The registry filter lives here rather than in the config loader because a
+ * config written by a newer binary may name a tool this one has never heard of,
+ * and refusing to load it would break every command rather than just this
+ * check. A tool loam cannot plan files for is a tool it has nothing to say
+ * about — so the preflight stays read-only instead of crashing on a config from
+ * the future.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import {} from "../envelope/config.js";
+import { LOAM_VERSION } from "../envelope/version.js";
+import { agentsPath } from "../repo/paths.js";
+import { DELIVERIES, plannedCommandFiles, } from "../agent/scaffold.js";
+import { AGENT_TOOLS } from "../agent/tools/registry.js";
+import { agentsStaleFinding, binaryBehindFinding, agentsStampLine, agentsStampVersion, versionTrails, } from "../agent/agents-stamp.js";
+import {} from "./report.js";
+export function recordedTools(config) {
+    const ids = (config?.agentTools ?? []).filter((t) => t in AGENT_TOOLS);
+    return ids.length === 0 ? null : ids;
+}
+/**
+ * Which tools this repo has agent files for, asked of the layout itself: a tool
+ * counts when any file it would be given is already there.
+ *
+ * The fallback for a loam.json written before `agentTools` existed, and the
+ * only answer a hand-written one can have — so its absence must never be the
+ * thing that reports a problem. This asks a narrower question than `init`'s
+ * own scan, and on purpose: init scans for a tool's dot-directory to decide
+ * what a repo would LIKE, while doctor grades what loam has already put there.
+ * A repo that runs Claude Code and took `--no-commands --no-skills` has chosen
+ * to have no loam files, and is not behind the binary for it.
+ */
+export function detectedTools(repoRoot) {
+    return Object.keys(AGENT_TOOLS).filter((id) => plannedCommandFiles(repoRoot, [id]).some((f) => existsSync(f.path)));
+}
+/**
+ * Which deliveries this repo actually HOLDS for one tool — a delivery counts
+ * when at least one of its files is on disk.
+ *
+ * `loam init --no-skills` (or `--no-commands`) records the tool in `agentTools`
+ * and writes one delivery, so planning both and subtracting what exists reported
+ * every skill file as missing on a brand-new repo — under a message saying it
+ * "was initialized by an older loam" and a `fix` that re-runs init without the
+ * flag that was the whole point. Which deliveries a repo asked for is written
+ * down nowhere, and must not be: the files ARE the record (there is no state
+ * file loam can disagree with). So the question is asked of them.
+ *
+ * A tool with NO files at all is the other story — recorded, then deleted — and
+ * the caller falls back to the full plan there, which is what the finding's
+ * "or they were deleted" already says.
+ */
+export function heldDeliveries(repoRoot, tool, profile = "full") {
+    const held = DELIVERIES.filter((d) => plannedCommandFiles(repoRoot, [tool], [d], profile).some((f) => existsSync(f.path)));
+    return held.length > 0 ? held : DELIVERIES;
+}
+/**
+ * Of the planned files that ARE here, the ones whose stamp is missing or older
+ * than this binary.
+ *
+ * The STALENESS check reads only the stamp, never the body. Safe refresh is a
+ * separate decision made by `init`: the current bytes must match the digest
+ * recorded when loam wrote them. That proof lets an unchanged pointer refresh
+ * without turning a differing body into an offer to overwrite it. A stamp is a
+ * different claim — it says which loam wrote these instructions — and it can
+ * be false while every edit around it is legitimate. Same doctrine as
+ * AGENTS.md (agents-stamp.ts); a customized file is repaired only when a human
+ * reviews it and bumps the stamp or deletes it for `loam init` to recreate.
+ *
+ * Absence of a stamp counts, because that is what every file written before
+ * stamping existed looks like — precisely the "initialized by an older loam"
+ * population this check is for.
+ */
+export async function staleAgentFiles(repoRoot, planned) {
+    // Read them together rather than one after another. `planned` is bounded by
+    // the tool registry — every delivery of every tool loam knows, a couple of
+    // hundred small files — so there is nothing here worth a concurrency cap, and
+    // `Promise.all` preserves input order, which is the only property the caller
+    // asks of the list it gets back.
+    const graded = await Promise.all(planned.map(async (file) => {
+        let text;
+        try {
+            text = await readFile(file.path, "utf8");
+        }
+        catch {
+            // Unreadable is not stale: it is either the missing-file finding above or
+            // a permissions problem, and neither is answered by editing a stamp.
+            return null;
+        }
+        const stamp = agentsStampVersion(text);
+        if (stamp === null || versionTrails(stamp, LOAM_VERSION)) {
+            return relative(repoRoot, file.path).split(/[\\/]/).join("/");
+        }
+        return null;
+    }));
+    return graded.filter((p) => p !== null);
+}
+/**
+ * What the running binary would write for this repo's tools that is not here,
+ * and what is here under an older loam's name.
+ *
+ * Presence is `existsSync`, the same probe `init` uses to compute its `skipped`
+ * list, so doctor cannot disagree with init about which files init would write.
+ */
+export async function inspectAgentSurface(repoRoot, config, docsDir, findings) {
+    const recorded = recordedTools(config);
+    const tools = recorded ?? detectedTools(repoRoot);
+    const profile = config?.agentProfile ?? "full";
+    const planned = tools.flatMap((id) => plannedCommandFiles(repoRoot, [id], heldDeliveries(repoRoot, id, profile), profile));
+    const present = planned.filter((f) => existsSync(f.path));
+    const missingFiles = planned
+        .filter((f) => !existsSync(f.path))
+        .map((f) => relative(repoRoot, f.path).split(/[\\/]/).join("/"));
+    const staleFiles = await staleAgentFiles(repoRoot, present);
+    if (missingFiles.length > 0) {
+        // A warning, never a blocker: an out-of-date command set is a repo whose
+        // agents have fewer entry points than they could, not one where anything
+        // refuses to run. doctor's blockers are for the second kind.
+        //
+        // The fix spells `--docs` and `--tools` and deliberately NOT `--service`:
+        // `init` spreads the committed config forward, and a `--docs`-less re-run
+        // keeps the pointer the repo already commits, so the binding survives
+        // untouched. Every interpolation here stands for exactly one argument —
+        // test/agent-commands-runnable.test.ts parses this string, and a `${flags}`
+        // holding three of them is a command it cannot check.
+        findings.push({
+            severity: "warning",
+            code: "doctor.agent-files-missing",
+            message: `${missingFiles.length} of the ${planned.length} command and skill files loam v${LOAM_VERSION} `
+                + `lays down for ${tools.join(", ")} are not in this repo — it was initialized by an older loam, `
+                + `or they were deleted: ${missingFiles.join(", ")}`,
+            fix: `Re-run \`loam init --docs ${config?.docsDirAsWritten ?? "<dir>"} --tools ${tools.join(",")}\` `
+                + "here — it creates files that are absent and keeps this repo's service binding. Files unchanged "
+                + "since loam wrote them refresh safely; customized files stay untouched.",
+        });
+    }
+    if (staleFiles.length > 0) {
+        // Also a warning, and for a stronger reason than the one above: these files
+        // are the team's now. Only a person can say whether their edits still mean
+        // what the current binary's tables say, so loam reports and stops.
+        findings.push({
+            severity: "warning",
+            code: "doctor.agent-files-stale",
+            message: `${staleFiles.length} of the ${planned.length} command and skill files here carry no `
+                + `\`${agentsStampLine(LOAM_VERSION)}\` stamp, or one older than this loam — the protocol and `
+                + `code tables they instruct an agent with may describe a loam that no longer exists: `
+                + `${staleFiles.join(", ")}`,
+            fix: "Read each against the body this loam writes, then set its stamp line to "
+                + `\`${agentsStampLine(LOAM_VERSION)}\`; or re-run \`loam init\`. A file whose recorded digest `
+                + "still matches is refreshed; a customized file is preserved and remains yours to review.",
+        });
+    }
+    // AGENTS.md lives in the DOCS repo, not here: it travels with the thing it
+    // describes. The comparison is `agentsStaleFinding`'s, not a second copy of
+    // it — doctor only adds the `fix` column its own findings owe the reader.
+    const agentsFile = docsDir === null ? null : agentsPath(docsDir);
+    let agentsText = null;
+    if (agentsFile !== null) {
+        try {
+            agentsText = await readFile(agentsFile, "utf8");
+        }
+        catch {
+            // Unreadable reads as absent, exactly as `validate --all` treats it: no
+            // file, no contract to have drifted. An unreadable docs repo is already
+            // its own finding.
+        }
+    }
+    const stale = agentsStaleFinding(agentsText, LOAM_VERSION);
+    if (stale !== null) {
+        findings.push({
+            severity: "warning",
+            code: stale.code,
+            message: stale.message,
+            fix: `Review ${agentsFile} against the current \`loam --help\`, then set its stamp line to `
+                + `\`${agentsStampLine(LOAM_VERSION)}\`. loam never rewrites that file — bumping the stamp IS `
+                + "the record that somebody looked.",
+        });
+    }
+    // The mirror, and a different fix: nothing is wrong with the documents, the
+    // reader is behind them — so this one never points at AGENTS.md.
+    const behind = binaryBehindFinding(agentsText, LOAM_VERSION);
+    if (behind !== null) {
+        findings.push({
+            severity: "warning",
+            code: behind.code,
+            message: behind.message,
+            fix: "Upgrade loam (`npm i -g @ybotok/loam`), then re-run. Do not edit AGENTS.md: its stamp is correct and this binary is the older half.",
+        });
+    }
+    return {
+        tools,
+        profile,
+        toolsSource: recorded === null ? "disk" : "config",
+        plannedFiles: planned.length,
+        missingFiles,
+        staleFiles,
+        stamp: {
+            path: agentsFile,
+            present: agentsText !== null,
+            version: agentsText === null ? null : agentsStampVersion(agentsText),
+            stale: stale !== null,
+        },
+    };
+}
+/**
+ * Grade what a write that did not finish left in the docs repo.
+ *
+ * Three of the four are blockers, which is unusual for doctor and deliberate:
+ * they are not "you have fewer entry points than you could", they are "the
+ * living docs may be half-written and the next reader cannot tell". Before this
+ * existed, a SIGKILL between two of archive's renames left `doctor: healthy:
+ * true` over merged spec.md + openapi.yaml and an unmerged landscape, and the
+ * next `loam archive` reported loam's own half-merge as the author's bug.
+ *
+ * The temp files are the exception: a `.loam-*.tmp` was never linked into place,
+ * so nothing reads it and nothing depends on it. It is litter, not damage.
+ */
+//# sourceMappingURL=agents.js.map

package/dist/core/doctor/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../../src/core/doctor/agents.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The agent surface: which tool files this repo should hold, which it does, and\n * whether they still describe this binary.\n *\n * The registry filter lives here rather than in the config loader because a\n * config written by a newer binary may name a tool this one has never heard of,\n * and refusing to load it would break every command rather than just this\n * check. A tool loam cannot plan files for is a tool it has nothing to say\n * about — so the preflight stays read-only instead of crashing on a config from\n * the future.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { type LoamConfig } from \"../envelope/config.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport { agentsPath } from \"../repo/paths.js\";\nimport {\n  DELIVERIES,\n  plannedCommandFiles,\n  type AgentProfile,\n  type Delivery,\n} from \"../agent/scaffold.js\";\nimport { AGENT_TOOLS } from \"../agent/tools/registry.js\";\nimport {\n  agentsStaleFinding,\n  binaryBehindFinding,\n  agentsStampLine,\n  agentsStampVersion,\n  versionTrails,\n} from \"../agent/agents-stamp.js\";\nimport { type AgentSurface, type DoctorFinding } from \"./report.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\nexport function recordedTools(config: LoamConfig | null): string[] | null {\n  const ids = (config?.agentTools ?? []).filter((t) => t in AGENT_TOOLS);\n  return ids.length === 0 ? null : ids;\n}\n\n/**\n * Which tools this repo has agent files for, asked of the layout itself: a tool\n * counts when any file it would be given is already there.\n *\n * The fallback for a loam.json written before `agentTools` existed, and the\n * only answer a hand-written one can have — so its absence must never be the\n * thing that reports a problem. This asks a narrower question than `init`'s\n * own scan, and on purpose: init scans for a tool's dot-directory to decide\n * what a repo would LIKE, while doctor grades what loam has already put there.\n * A repo that runs Claude Code and took `--no-commands --no-skills` has chosen\n * to have no loam files, and is not behind the binary for it.\n */\nexport function detectedTools(repoRoot: string): string[] {\n  return Object.keys(AGENT_TOOLS).filter((id) =>\n    plannedCommandFiles(repoRoot, [id]).some((f) => existsSync(f.path)));\n}\n\n/**\n * Which deliveries this repo actually HOLDS for one tool — a delivery counts\n * when at least one of its files is on disk.\n *\n * `loam init --no-skills` (or `--no-commands`) records the tool in `agentTools`\n * and writes one delivery, so planning both and subtracting what exists reported\n * every skill file as missing on a brand-new repo — under a message saying it\n * \"was initialized by an older loam\" and a `fix` that re-runs init without the\n * flag that was the whole point. Which deliveries a repo asked for is written\n * down nowhere, and must not be: the files ARE the record (there is no state\n * file loam can disagree with). So the question is asked of them.\n *\n * A tool with NO files at all is the other story — recorded, then deleted — and\n * the caller falls back to the full plan there, which is what the finding's\n * \"or they were deleted\" already says.\n */\nexport function heldDeliveries(\n  repoRoot: string,\n  tool: string,\n  profile: AgentProfile = \"full\",\n): readonly Delivery[] {\n  const held = DELIVERIES.filter((d) =>\n    plannedCommandFiles(repoRoot, [tool], [d], profile).some((f) => existsSync(f.path)));\n  return held.length > 0 ? held : DELIVERIES;\n}\n\n/**\n * Of the planned files that ARE here, the ones whose stamp is missing or older\n * than this binary.\n *\n * The STALENESS check reads only the stamp, never the body. Safe refresh is a\n * separate decision made by `init`: the current bytes must match the digest\n * recorded when loam wrote them. That proof lets an unchanged pointer refresh\n * without turning a differing body into an offer to overwrite it. A stamp is a\n * different claim — it says which loam wrote these instructions — and it can\n * be false while every edit around it is legitimate. Same doctrine as\n * AGENTS.md (agents-stamp.ts); a customized file is repaired only when a human\n * reviews it and bumps the stamp or deletes it for `loam init` to recreate.\n *\n * Absence of a stamp counts, because that is what every file written before\n * stamping existed looks like — precisely the \"initialized by an older loam\"\n * population this check is for.\n */\nexport async function staleAgentFiles(\n  repoRoot: string,\n  planned: Array<{ path: string }>,\n): Promise<string[]> {\n  // Read them together rather than one after another. `planned` is bounded by\n  // the tool registry — every delivery of every tool loam knows, a couple of\n  // hundred small files — so there is nothing here worth a concurrency cap, and\n  // `Promise.all` preserves input order, which is the only property the caller\n  // asks of the list it gets back.\n  const graded = await Promise.all(planned.map(async (file): Promise<string | null> => {\n    let text: string;\n    try {\n      text = await readFile(file.path, \"utf8\");\n    } catch {\n      // Unreadable is not stale: it is either the missing-file finding above or\n      // a permissions problem, and neither is answered by editing a stamp.\n      return null;\n    }\n    const stamp = agentsStampVersion(text);\n    if (stamp === null || versionTrails(stamp, LOAM_VERSION)) {\n      return relative(repoRoot, file.path).split(/[\\\\/]/).join(\"/\");\n    }\n    return null;\n  }));\n  return graded.filter((p) => p !== null);\n}\n\n/**\n * What the running binary would write for this repo's tools that is not here,\n * and what is here under an older loam's name.\n *\n * Presence is `existsSync`, the same probe `init` uses to compute its `skipped`\n * list, so doctor cannot disagree with init about which files init would write.\n */\nexport async function inspectAgentSurface(\n  repoRoot: string,\n  config: LoamConfig | null,\n  docsDir: DocsDir | null,\n  findings: DoctorFinding[],\n): Promise<AgentSurface> {\n  const recorded = recordedTools(config);\n  const tools = recorded ?? detectedTools(repoRoot);\n  const profile = config?.agentProfile ?? \"full\";\n  const planned = tools.flatMap((id) =>\n    plannedCommandFiles(repoRoot, [id], heldDeliveries(repoRoot, id, profile), profile));\n  const present = planned.filter((f) => existsSync(f.path));\n  const missingFiles = planned\n    .filter((f) => !existsSync(f.path))\n    .map((f) => relative(repoRoot, f.path).split(/[\\\\/]/).join(\"/\"));\n  const staleFiles = await staleAgentFiles(repoRoot, present);\n\n  if (missingFiles.length > 0) {\n    // A warning, never a blocker: an out-of-date command set is a repo whose\n    // agents have fewer entry points than they could, not one where anything\n    // refuses to run. doctor's blockers are for the second kind.\n    //\n    // The fix spells `--docs` and `--tools` and deliberately NOT `--service`:\n    // `init` spreads the committed config forward, and a `--docs`-less re-run\n    // keeps the pointer the repo already commits, so the binding survives\n    // untouched. Every interpolation here stands for exactly one argument —\n    // test/agent-commands-runnable.test.ts parses this string, and a `${flags}`\n    // holding three of them is a command it cannot check.\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.agent-files-missing\",\n      message:\n        `${missingFiles.length} of the ${planned.length} command and skill files loam v${LOAM_VERSION} `\n        + `lays down for ${tools.join(\", \")} are not in this repo — it was initialized by an older loam, `\n        + `or they were deleted: ${missingFiles.join(\", \")}`,\n      fix:\n        `Re-run \\`loam init --docs ${config?.docsDirAsWritten ?? \"<dir>\"} --tools ${tools.join(\",\")}\\` `\n        + \"here — it creates files that are absent and keeps this repo's service binding. Files unchanged \"\n        + \"since loam wrote them refresh safely; customized files stay untouched.\",\n    });\n  }\n\n  if (staleFiles.length > 0) {\n    // Also a warning, and for a stronger reason than the one above: these files\n    // are the team's now. Only a person can say whether their edits still mean\n    // what the current binary's tables say, so loam reports and stops.\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.agent-files-stale\",\n      message:\n        `${staleFiles.length} of the ${planned.length} command and skill files here carry no `\n        + `\\`${agentsStampLine(LOAM_VERSION)}\\` stamp, or one older than this loam — the protocol and `\n        + `code tables they instruct an agent with may describe a loam that no longer exists: `\n        + `${staleFiles.join(\", \")}`,\n      fix:\n        \"Read each against the body this loam writes, then set its stamp line to \"\n        + `\\`${agentsStampLine(LOAM_VERSION)}\\`; or re-run \\`loam init\\`. A file whose recorded digest `\n        + \"still matches is refreshed; a customized file is preserved and remains yours to review.\",\n    });\n  }\n\n  // AGENTS.md lives in the DOCS repo, not here: it travels with the thing it\n  // describes. The comparison is `agentsStaleFinding`'s, not a second copy of\n  // it — doctor only adds the `fix` column its own findings owe the reader.\n  const agentsFile = docsDir === null ? null : agentsPath(docsDir);\n  let agentsText: string | null = null;\n  if (agentsFile !== null) {\n    try {\n      agentsText = await readFile(agentsFile, \"utf8\");\n    } catch {\n      // Unreadable reads as absent, exactly as `validate --all` treats it: no\n      // file, no contract to have drifted. An unreadable docs repo is already\n      // its own finding.\n    }\n  }\n  const stale = agentsStaleFinding(agentsText, LOAM_VERSION);\n  if (stale !== null) {\n    findings.push({\n      severity: \"warning\",\n      code: stale.code,\n      message: stale.message,\n      fix:\n        `Review ${agentsFile} against the current \\`loam --help\\`, then set its stamp line to `\n        + `\\`${agentsStampLine(LOAM_VERSION)}\\`. loam never rewrites that file — bumping the stamp IS `\n        + \"the record that somebody looked.\",\n    });\n  }\n  // The mirror, and a different fix: nothing is wrong with the documents, the\n  // reader is behind them — so this one never points at AGENTS.md.\n  const behind = binaryBehindFinding(agentsText, LOAM_VERSION);\n  if (behind !== null) {\n    findings.push({\n      severity: \"warning\",\n      code: behind.code,\n      message: behind.message,\n      fix: \"Upgrade loam (`npm i -g @ybotok/loam`), then re-run. Do not edit AGENTS.md: its stamp is correct and this binary is the older half.\",\n    });\n  }\n\n  return {\n    tools,\n    profile,\n    toolsSource: recorded === null ? \"disk\" : \"config\",\n    plannedFiles: planned.length,\n    missingFiles,\n    staleFiles,\n    stamp: {\n      path: agentsFile,\n      present: agentsText !== null,\n      version: agentsText === null ? null : agentsStampVersion(agentsText),\n      stale: stale !== null,\n    },\n  };\n}\n\n/**\n * Grade what a write that did not finish left in the docs repo.\n *\n * Three of the four are blockers, which is unusual for doctor and deliberate:\n * they are not \"you have fewer entry points than you could\", they are \"the\n * living docs may be half-written and the next reader cannot tell\". Before this\n * existed, a SIGKILL between two of archive's renames left `doctor: healthy:\n * true` over merged spec.md + openapi.yaml and an unmerged landscape, and the\n * next `loam archive` reported loam's own half-merge as the author's bug.\n *\n * The temp files are the exception: a `.loam-*.tmp` was never linked into place,\n * so nothing reads it and nothing depends on it. It is litter, not damage.\n */\n"]}

package/dist/core/doctor/config.js

@@ -0,0 +1,135 @@
+/**
+ * The config and the fleet map, read the way every other command reads them.
+ *
+ * `doctor` used to carry its own config validator. It agreed with `loadConfig`
+ * on the fields both happened to check and disagreed everywhere else — it
+ * accepted a `gherkinDir` of `"../shared"` that `loadConfig` refused outright,
+ * so `doctor` reported a healthy repo in which no command could run. Two
+ * validators are two opinions about one file, and the one the user reads is
+ * never the one the commands obey.
+ *
+ * The landscape is READ, not stat'ed, for the same reason: `doctor` once
+ * reported `landscape: yes` for a file full of conflict markers, which answers
+ * "is there a file" — not the question anyone runs doctor to ask.
+ */
+import { access, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { configPath, parseConfig } from "../envelope/config.js";
+import { loadFile } from "../c4/likec4.js";
+import { conflictMarkerLines } from "../conflict-markers.js";
+import {} from "./report.js";
+/**
+ * Read and validate the config the way every other command does — through
+ * `parseConfig`, never through a second implementation.
+ *
+ * doctor used to carry its own validator. It agreed with `loadConfig` on the
+ * fields both happened to check and disagreed everywhere else: doctor accepted
+ * a `gherkinDir` of `"../shared"` that `loadConfig` refused outright, so
+ * `doctor` reported a healthy repo in which no command could run. Two
+ * validators are two opinions about the same file, and the one the user reads
+ * is never the one the commands obey.
+ */
+export async function inspectConfig(cwd) {
+    const path = configPath(cwd);
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { status: "missing", config: null, error: null };
+        return {
+            status: "invalid",
+            config: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        return { status: "valid", error: null, config: parseConfig(raw, dirname(path)) };
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            config: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function canAccess(path, mode) {
+    try {
+        await access(path, mode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the landscape, don't just stat it. `doctor` reported `landscape: yes`
+ * for a file full of conflict markers — the check answered "is there a file",
+ * which is not the question anyone runs doctor to ask.
+ */
+export async function inspectLandscape(path, findings) {
+    let source;
+    try {
+        source = await readFile(path, "utf8");
+    }
+    catch (error) {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.landscape-unreadable",
+            message: `${path} exists but could not be read: ${error instanceof Error ? error.message : String(error)}`,
+            fix: `Check permissions on ${path}.`,
+        });
+        return;
+    }
+    // The three-way merge left its markers in the file. Checked BEFORE the
+    // parser, because a conflicted landscape does parse sometimes — both sides of
+    // a conflict can be syntactically valid LikeC4 — and "your map contains two
+    // halves of two different maps" is a more useful sentence than any parser
+    // error. This is the failure mode of onboarding a fleet: ten people adopt ten
+    // services into one landscape.likec4 in the same week.
+    //
+    // The scan itself is conflict-markers's, which is where the same rule already
+    // grades every other document loam reads. doctor kept a second copy of it,
+    // and a second copy of a rule is a second chance to spell it differently;
+    // what doctor owns is what a conflicted landscape COSTS, which is the finding
+    // below and not the search.
+    const conflicted = conflictMarkerLines(source);
+    if (conflicted.length > 0) {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.landscape-merge-conflict",
+            message: `architecture/landscape.likec4 still contains merge conflict markers ` +
+                `(line${conflicted.length === 1 ? "" : "s"} ${conflicted.join(", ")}).`,
+            fix: `Resolve the conflict in ${path} — keep BOTH services' elements and edges, then re-run \`loam doctor\`.`,
+        });
+        return;
+    }
+    const doc = await loadFile(path);
+    if (doc.errors.length > 0) {
+        const first = doc.errors[0];
+        findings.push({
+            severity: "blocker",
+            code: "doctor.landscape-invalid",
+            message: `architecture/landscape.likec4 does not parse: ${first.message}` +
+                (first.line === undefined ? "" : ` (line ${first.line})`) +
+                (doc.errors.length > 1 ? ` — and ${doc.errors.length - 1} more` : ""),
+            fix: `Fix ${path}; every fleet-wide check is blind until it parses.`,
+        });
+    }
+}
+/**
+ * The tool ids loam.json records `init` as having written files for, or null
+ * when it records none we can plan for.
+ *
+ * `parseConfig` checks `agentTools`' SHAPE and deliberately not its contents —
+ * a config written by a newer binary may name a tool this one has never heard
+ * of, and refusing to load it would break every command, not just this check.
+ * So the registry filter belongs here: `plannedCommandFiles` throws on an id it
+ * does not know, and a config from the future must not turn the read-only
+ * preflight into a crash. A tool we cannot plan files for is a tool we have
+ * nothing to say about.
+ */
+//# sourceMappingURL=config.js.map

package/dist/core/doctor/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/doctor/config.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The config and the fleet map, read the way every other command reads them.\n *\n * `doctor` used to carry its own config validator. It agreed with `loadConfig`\n * on the fields both happened to check and disagreed everywhere else — it\n * accepted a `gherkinDir` of `\"../shared\"` that `loadConfig` refused outright,\n * so `doctor` reported a healthy repo in which no command could run. Two\n * validators are two opinions about one file, and the one the user reads is\n * never the one the commands obey.\n *\n * The landscape is READ, not stat'ed, for the same reason: `doctor` once\n * reported `landscape: yes` for a file full of conflict markers, which answers\n * \"is there a file\" — not the question anyone runs doctor to ask.\n */\nimport { access, readFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { configPath, parseConfig, type LoamConfig } from \"../envelope/config.js\";\nimport { loadFile } from \"../c4/likec4.js\";\nimport { conflictMarkerLines } from \"../conflict-markers.js\";\nimport { type DoctorFinding, type DoctorReport } from \"./report.js\";\n\nexport interface ConfigInspection {\n  status: DoctorReport[\"config\"][\"status\"];\n  config: LoamConfig | null;\n  error: string | null;\n}\n\n/**\n * Read and validate the config the way every other command does — through\n * `parseConfig`, never through a second implementation.\n *\n * doctor used to carry its own validator. It agreed with `loadConfig` on the\n * fields both happened to check and disagreed everywhere else: doctor accepted\n * a `gherkinDir` of `\"../shared\"` that `loadConfig` refused outright, so\n * `doctor` reported a healthy repo in which no command could run. Two\n * validators are two opinions about the same file, and the one the user reads\n * is never the one the commands obey.\n */\nexport async function inspectConfig(cwd: string): Promise<ConfigInspection> {\n  const path = configPath(cwd);\n  let raw: string;\n  try {\n    raw = await readFile(path, \"utf8\");\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n    if (code === \"ENOENT\") return { status: \"missing\", config: null, error: null };\n    return {\n      status: \"invalid\",\n      config: null,\n      error: error instanceof Error ? error.message : String(error),\n    };\n  }\n\n  try {\n    return { status: \"valid\", error: null, config: parseConfig(raw, dirname(path)) };\n  } catch (error) {\n    return {\n      status: \"invalid\",\n      config: null,\n      error: error instanceof Error ? error.message : String(error),\n    };\n  }\n}\n\nexport async function canAccess(path: string, mode: number): Promise<boolean> {\n  try {\n    await access(path, mode);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Read the landscape, don't just stat it. `doctor` reported `landscape: yes`\n * for a file full of conflict markers — the check answered \"is there a file\",\n * which is not the question anyone runs doctor to ask.\n */\nexport async function inspectLandscape(path: string, findings: DoctorFinding[]): Promise<void> {\n  let source: string;\n  try {\n    source = await readFile(path, \"utf8\");\n  } catch (error) {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.landscape-unreadable\",\n      message: `${path} exists but could not be read: ${error instanceof Error ? error.message : String(error)}`,\n      fix: `Check permissions on ${path}.`,\n    });\n    return;\n  }\n\n  // The three-way merge left its markers in the file. Checked BEFORE the\n  // parser, because a conflicted landscape does parse sometimes — both sides of\n  // a conflict can be syntactically valid LikeC4 — and \"your map contains two\n  // halves of two different maps\" is a more useful sentence than any parser\n  // error. This is the failure mode of onboarding a fleet: ten people adopt ten\n  // services into one landscape.likec4 in the same week.\n  //\n  // The scan itself is conflict-markers's, which is where the same rule already\n  // grades every other document loam reads. doctor kept a second copy of it,\n  // and a second copy of a rule is a second chance to spell it differently;\n  // what doctor owns is what a conflicted landscape COSTS, which is the finding\n  // below and not the search.\n  const conflicted = conflictMarkerLines(source);\n  if (conflicted.length > 0) {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.landscape-merge-conflict\",\n      message:\n        `architecture/landscape.likec4 still contains merge conflict markers ` +\n        `(line${conflicted.length === 1 ? \"\" : \"s\"} ${conflicted.join(\", \")}).`,\n      fix: `Resolve the conflict in ${path} — keep BOTH services' elements and edges, then re-run \\`loam doctor\\`.`,\n    });\n    return;\n  }\n\n  const doc = await loadFile(path);\n  if (doc.errors.length > 0) {\n    const first = doc.errors[0]!;\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.landscape-invalid\",\n      message:\n        `architecture/landscape.likec4 does not parse: ${first.message}` +\n        (first.line === undefined ? \"\" : ` (line ${first.line})`) +\n        (doc.errors.length > 1 ? ` — and ${doc.errors.length - 1} more` : \"\"),\n      fix: `Fix ${path}; every fleet-wide check is blind until it parses.`,\n    });\n  }\n}\n\n/**\n * The tool ids loam.json records `init` as having written files for, or null\n * when it records none we can plan for.\n *\n * `parseConfig` checks `agentTools`' SHAPE and deliberately not its contents —\n * a config written by a newer binary may name a tool this one has never heard\n * of, and refusing to load it would break every command, not just this check.\n * So the registry filter belongs here: `plannedCommandFiles` throws on an id it\n * does not know, and a config from the future must not turn the read-only\n * preflight into a crash. A tool we cannot plan files for is a tool we have\n * nothing to say about.\n */\n"]}