@isaacriehm/cairn-core 0.1.0

package/dist/doctor/index.js

@@ -0,0 +1,460 @@
+/**
+ * `cairn doctor` — verify the adoption is healthy.
+ *
+ * Pure filesystem reads + a status.json check. No LLM. No subprocess fan-out.
+ * Returns a structured `DoctorReport` the CLI renders. Exit-code mapping:
+ *   0 — all checks pass
+ *   1 — at least one error (missing core file, broken layout)
+ *   2 — at least one warning (drafty brand, empty scope, daemon not running, …)
+ *
+ * Spec: BUILD_REPORT.md "Task D — cairn doctor command".
+ */
+import { existsSync, readdirSync, readFileSync, statSync, } from "node:fs";
+import { basename, delimiter, join, resolve as resolvePath } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { buildDecisionsLedger, buildInvariantsLedger, } from "../ground/index.js";
+import { normalizeProjectName } from "../paths/index.js";
+export function runDoctor(opts) {
+    const repoRoot = opts.repoRoot;
+    const projectName = normalizeProjectName(basename(repoRoot));
+    const checks = [];
+    // ── Core checks ────────────────────────────────────────────────────
+    checks.push(checkCairnLayout(repoRoot));
+    checks.push(checkMcpRegistration(repoRoot));
+    checks.push(checkClaudeHooks(repoRoot));
+    // ── Ground state checks ────────────────────────────────────────────
+    checks.push(checkDecisions(repoRoot));
+    checks.push(checkBrandOverview(repoRoot));
+    checks.push(checkScopeIndex(repoRoot));
+    // ── Sensor presence ────────────────────────────────────────────────
+    for (const c of checkSensorAvailability(repoRoot))
+        checks.push(c);
+    let errors = 0;
+    let warnings = 0;
+    for (const c of checks) {
+        if (c.status === "error")
+            errors++;
+        else if (c.status === "warn")
+            warnings++;
+    }
+    return { projectName, repoRoot, checks, errors, warnings };
+}
+// ── Core checks ──────────────────────────────────────────────────────
+function checkCairnLayout(repoRoot) {
+    const groundDir = join(repoRoot, ".cairn", "ground");
+    if (!existsSync(groundDir)) {
+        return {
+            group: "core",
+            label: ".cairn/",
+            status: "error",
+            detail: "missing — run cairn init",
+            fixCommand: "cairn init",
+        };
+    }
+    let count = 0;
+    const stack = [groundDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const abs = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (e.name === "_inbox")
+                    continue;
+                stack.push(abs);
+            }
+            else if (e.isFile()) {
+                count++;
+            }
+        }
+    }
+    return {
+        group: "core",
+        label: ".cairn/",
+        status: "ok",
+        detail: `layout complete (${count} ground files)`,
+    };
+}
+function checkMcpRegistration(repoRoot) {
+    const path = join(repoRoot, ".mcp.json");
+    if (!existsSync(path)) {
+        return {
+            group: "core",
+            label: ".mcp.json",
+            status: "error",
+            detail: "missing — run cairn init",
+            fixCommand: "cairn init",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {
+            group: "core",
+            label: ".mcp.json",
+            status: "error",
+            detail: "unreadable — re-run cairn init",
+            fixCommand: "cairn init --force",
+        };
+    }
+    const servers = parsed["mcpServers"];
+    if (typeof servers !== "object" || servers === null) {
+        return {
+            group: "core",
+            label: ".mcp.json",
+            status: "error",
+            detail: "missing mcpServers — re-run cairn init",
+            fixCommand: "cairn init --force",
+        };
+    }
+    if (servers["cairn"] === undefined) {
+        return {
+            group: "core",
+            label: ".mcp.json",
+            status: "error",
+            detail: "no cairn entry — re-run cairn init",
+            fixCommand: "cairn init --force",
+        };
+    }
+    return {
+        group: "core",
+        label: ".mcp.json",
+        status: "ok",
+        detail: "cairn MCP server registered",
+    };
+}
+function checkClaudeHooks(repoRoot) {
+    const path = join(repoRoot, ".claude", "settings.json");
+    if (!existsSync(path)) {
+        return {
+            group: "core",
+            label: ".claude/",
+            status: "error",
+            detail: "missing settings.json — re-run cairn init",
+            fixCommand: "cairn init --force",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {
+            group: "core",
+            label: ".claude/",
+            status: "error",
+            detail: "settings.json unreadable",
+            fixCommand: "cairn init --force",
+        };
+    }
+    const hooks = parsed["hooks"];
+    if (typeof hooks !== "object" || hooks === null) {
+        return {
+            group: "core",
+            label: ".claude/",
+            status: "warn",
+            detail: "no hooks block — re-run cairn init",
+            fixCommand: "cairn init --force",
+        };
+    }
+    const labels = [];
+    if (Array.isArray(hooks["SessionStart"])) {
+        labels.push("SessionStart");
+    }
+    if (Array.isArray(hooks["PostToolUse"])) {
+        labels.push("PostToolUse");
+    }
+    if (labels.length === 0) {
+        return {
+            group: "core",
+            label: ".claude/",
+            status: "warn",
+            detail: "no SessionStart / PostToolUse entries",
+            fixCommand: "cairn init --force",
+        };
+    }
+    return {
+        group: "core",
+        label: ".claude/",
+        status: "ok",
+        detail: `${labels.join(" + ")} registered`,
+    };
+}
+// ── Ground state checks ──────────────────────────────────────────────
+function checkDecisions(repoRoot) {
+    let accepted = 0;
+    let drafts = 0;
+    try {
+        accepted = buildDecisionsLedger({ repoRoot }).length;
+    }
+    catch {
+        return {
+            group: "ground",
+            label: "decisions",
+            status: "warn",
+            detail: "ledger build failed",
+        };
+    }
+    const inboxDir = join(repoRoot, ".cairn", "ground", "decisions", "_inbox");
+    if (existsSync(inboxDir)) {
+        try {
+            const entries = readdirSync(inboxDir, {
+                withFileTypes: true,
+                encoding: "utf8",
+            });
+            for (const e of entries) {
+                if (e.isFile() && e.name.endsWith(".draft.md"))
+                    drafts++;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    // Count active invariants for the same line.
+    let invariants = 0;
+    try {
+        invariants = buildInvariantsLedger({ repoRoot }).length;
+    }
+    catch {
+        // ignore
+    }
+    if (drafts > 0) {
+        return {
+            group: "ground",
+            label: "decisions",
+            status: "warn",
+            detail: `${accepted} accepted, ${invariants} invariants, ${drafts} drafts pending`,
+            fixCommand: "cairn attention",
+        };
+    }
+    return {
+        group: "ground",
+        label: "decisions",
+        status: "ok",
+        detail: `${accepted} accepted, ${invariants} invariants, no drafts pending`,
+    };
+}
+function checkBrandOverview(repoRoot) {
+    const path = join(repoRoot, ".cairn", "ground", "brand", "overview.md");
+    if (!existsSync(path)) {
+        return {
+            group: "ground",
+            label: "brand/overview",
+            status: "warn",
+            detail: "missing — re-run cairn init",
+            fixCommand: "cairn init --force",
+        };
+    }
+    const status = readFrontmatterStatus(path) ?? "(none)";
+    if (status === "current" || status === "accepted") {
+        return {
+            group: "ground",
+            label: "brand/overview",
+            status: "ok",
+            detail: `status:${status}`,
+        };
+    }
+    return {
+        group: "ground",
+        label: "brand/overview",
+        status: "warn",
+        detail: `status:${status}`,
+        fixCommand: "cairn configure brand",
+    };
+}
+function checkScopeIndex(repoRoot) {
+    const path = join(repoRoot, ".cairn", "ground", "scope-index.yaml");
+    if (!existsSync(path)) {
+        return {
+            group: "ground",
+            label: "scope-index",
+            status: "warn",
+            detail: "missing — run cairn scope rebuild",
+            fixCommand: "cairn scope rebuild",
+        };
+    }
+    let count = 0;
+    try {
+        const parsed = parseYaml(readFileSync(path, "utf8"));
+        if (typeof parsed === "object" && parsed !== null) {
+            const filesRaw = parsed["files"];
+            if (typeof filesRaw === "object" && filesRaw !== null) {
+                count = Object.keys(filesRaw).length;
+            }
+        }
+    }
+    catch {
+        return {
+            group: "ground",
+            label: "scope-index",
+            status: "warn",
+            detail: "unreadable — re-run cairn scope rebuild",
+            fixCommand: "cairn scope rebuild",
+        };
+    }
+    if (count === 0) {
+        return {
+            group: "ground",
+            label: "scope-index",
+            status: "warn",
+            detail: "empty — run cairn scope rebuild",
+            fixCommand: "cairn scope rebuild",
+        };
+    }
+    return {
+        group: "ground",
+        label: "scope-index",
+        status: "ok",
+        detail: `${count} file${count === 1 ? "" : "s"} classified`,
+    };
+}
+// ── Sensors ──────────────────────────────────────────────────────────
+function checkSensorAvailability(repoRoot) {
+    const path = join(repoRoot, ".cairn", "config", "sensors.yaml");
+    if (!existsSync(path)) {
+        return [
+            {
+                group: "sensors",
+                label: "sensors.yaml",
+                status: "warn",
+                detail: "missing — re-run cairn init",
+                fixCommand: "cairn init --force",
+            },
+        ];
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(readFileSync(path, "utf8"));
+    }
+    catch {
+        return [
+            {
+                group: "sensors",
+                label: "sensors.yaml",
+                status: "warn",
+                detail: "unreadable",
+            },
+        ];
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return [];
+    const sensorsRaw = parsed["sensors"];
+    if (!Array.isArray(sensorsRaw))
+        return [];
+    const disabled = parsed["disabled_per_project"];
+    const disabledSet = new Set(Array.isArray(disabled)
+        ? disabled.filter((x) => typeof x === "string")
+        : []);
+    const checks = [];
+    for (const raw of sensorsRaw) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const r = raw;
+        const id = typeof r["id"] === "string" ? r["id"] : null;
+        if (id === null)
+            continue;
+        if (disabledSet.has(id)) {
+            checks.push({
+                group: "sensors",
+                label: id,
+                status: "info",
+                detail: "disabled per project",
+            });
+            continue;
+        }
+        const failSeverity = typeof r["fail_severity"] === "string" ? r["fail_severity"] : "soft";
+        const command = typeof r["command"] === "string" ? r["command"] : null;
+        if (command !== null && command.length > 0) {
+            const found = which(command);
+            if (!found) {
+                checks.push({
+                    group: "sensors",
+                    label: id,
+                    status: failSeverity === "hard" ? "error" : "warn",
+                    detail: `${command} not on PATH — install or disable in sensors.yaml`,
+                });
+                continue;
+            }
+        }
+        checks.push({
+            group: "sensors",
+            label: id,
+            status: "ok",
+            detail: failSeverity === "hard" ? "registered" : "registered (warn-only)",
+        });
+    }
+    return checks;
+}
+function which(binary) {
+    const pathEnv = process.env["PATH"];
+    if (typeof pathEnv !== "string" || pathEnv.length === 0)
+        return false;
+    for (const dir of pathEnv.split(delimiter)) {
+        if (dir.length === 0)
+            continue;
+        const candidate = resolvePath(dir, binary);
+        try {
+            if (statSync(candidate).isFile())
+                return true;
+        }
+        catch {
+            // continue
+        }
+    }
+    return false;
+}
+// ── Shared helpers ───────────────────────────────────────────────────
+function readFrontmatterStatus(path) {
+    try {
+        const text = readFileSync(path, "utf8");
+        const m = text.match(/^---\n([\s\S]*?\n)---/);
+        if (!m)
+            return null;
+        const fm = m[1] ?? "";
+        const sm = fm.match(/^status:\s*(\S+)\s*$/m);
+        return sm && sm[1] ? sm[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runFix(opts) {
+    const report = runDoctor({ repoRoot: opts.repoRoot });
+    const applied = [];
+    const manual = [];
+    for (const c of report.checks) {
+        if (c.status !== "warn" && c.status !== "error")
+            continue;
+        if (c.label === "scope-index" && opts.rebuildScopeIndexFn !== undefined) {
+            try {
+                const r = await opts.rebuildScopeIndexFn(opts.repoRoot);
+                applied.push(`scope-index → ${r.filesClassified} file${r.filesClassified === 1 ? "" : "s"} classified`);
+            }
+            catch (err) {
+                manual.push({
+                    check: c.label,
+                    command: c.fixCommand ?? null,
+                });
+                void err;
+            }
+            continue;
+        }
+        manual.push({
+            check: c.label,
+            command: c.fixCommand ?? null,
+        });
+    }
+    return { appliedFixes: applied, manualFixes: manual };
+}
+//# sourceMappingURL=index.js.map

package/dist/doctor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/doctor/index.ts"],"names":[],"mappings":"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"}

package/dist/events/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Invalidation events — `.cairn/events/<msTs>-<kind>.json`.
+ *
+ * Locked write tools emit events after their write completes. Plugin
+ * Stop hooks in other live sessions poll this directory and surface an
+ * inline A/B/C if an event touches a DEC/§V/path the reader has in
+ * scope. 7-day retention via `gcStaleEvents`.
+ *
+ * Spec: PLUGIN_ARCHITECTURE §7 (three-layer conflict catch, layer 2).
+ */
+export { eventsDir } from "./paths.js";
+export { writeInvalidationEvent } from "./writer.js";
+export type { InvalidationEvent, InvalidationEventRef, InvalidationEventSource, WriteInvalidationEventInput, WriteInvalidationEventResult, } from "./writer.js";
+export { eventsSince, gcStaleEvents } from "./reader.js";
+export type { EventsSinceArgs, EventsSinceResult, GcStaleEventsArgs, GcStaleEventsResult, } from "./reader.js";

package/dist/events/index.js

@@ -0,0 +1,14 @@
+/**
+ * Invalidation events — `.cairn/events/<msTs>-<kind>.json`.
+ *
+ * Locked write tools emit events after their write completes. Plugin
+ * Stop hooks in other live sessions poll this directory and surface an
+ * inline A/B/C if an event touches a DEC/§V/path the reader has in
+ * scope. 7-day retention via `gcStaleEvents`.
+ *
+ * Spec: PLUGIN_ARCHITECTURE §7 (three-layer conflict catch, layer 2).
+ */
+export { eventsDir } from "./paths.js";
+export { writeInvalidationEvent } from "./writer.js";
+export { eventsSince, gcStaleEvents } from "./reader.js";
+//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAQrD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/events/paths.d.ts

@@ -0,0 +1,2 @@
+/** `.cairn/events/` — invalidation event log directory. */
+export declare function eventsDir(repoRoot: string): string;

package/dist/events/paths.js

@@ -0,0 +1,6 @@
+import { join } from "node:path";
+/** `.cairn/events/` — invalidation event log directory. */
+export function eventsDir(repoRoot) {
+    return join(repoRoot, ".cairn", "events");
+}
+//# sourceMappingURL=paths.js.map

package/dist/events/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/events/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,2DAA2D;AAC3D,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,OAAO,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC5C,CAAC"}

package/dist/events/reader.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Invalidation event reader + retention GC.
+ *
+ * `eventsSince(repoRoot, sinceMs)` — list events with ts > sinceMs,
+ * sorted ascending. Used by the plugin Stop hook to surface only events
+ * that landed during the current session.
+ *
+ * `gcStaleEvents(repoRoot, opts?)` — drops events older than 7 days.
+ * Wired into the standard sweep so the events directory stays bounded.
+ */
+import type { InvalidationEvent } from "./writer.js";
+export interface EventsSinceArgs {
+    repoRoot: string;
+    /** Lower bound — only events with `ts > sinceMs` are returned. */
+    sinceMs: number;
+    /** Optional cap on results; sorted ascending so a cap drops the tail. */
+    limit?: number;
+}
+export interface EventsSinceResult {
+    events: InvalidationEvent[];
+    /** Files we tried to read but couldn't parse — surfaced for telemetry. */
+    malformed: string[];
+}
+export declare function eventsSince(args: EventsSinceArgs): EventsSinceResult;
+export interface GcStaleEventsArgs {
+    repoRoot: string;
+    /** Default 7 days. */
+    maxAgeMs?: number;
+    /** Override Date.now() — tests use this. */
+    now?: () => number;
+}
+export interface GcStaleEventsResult {
+    removed: string[];
+    kept: string[];
+}
+/**
+ * Remove event files older than `maxAgeMs` (default 7 days). Uses each
+ * file's parsed `ts` when present; falls back to `mtimeMs` otherwise.
+ */
+export declare function gcStaleEvents(args: GcStaleEventsArgs): GcStaleEventsResult;