@isaacriehm/cairn-state 0.22.5

package/dist/config.js

@@ -0,0 +1,26 @@
+/**
+ * Top-level `.cairn/config.yaml` reader for the non-component sections.
+ *
+ * (The `components:` block has its own typed loader in components.ts.)
+ * Kept deliberately small + tolerant: a missing or malformed config is
+ * never fatal — callers get the documented defaults.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { cairnDir } from "./home.js";
+/** Parse `.cairn/config.yaml` into a plain object ({} when absent/broken). */
+export function loadCairnConfig(repoRoot) {
+    const p = cairnDir(repoRoot, "config.yaml");
+    if (!existsSync(p))
+        return {};
+    try {
+        const doc = parseYaml(readFileSync(p, "utf8"));
+        return typeof doc === "object" && doc !== null
+            ? doc
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,CAAC,GAAG,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;YAC5C,CAAC,CAAE,GAA+B;YAClC,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/drift.d.ts

@@ -0,0 +1,8 @@
+import { DriftEvent } from "./schemas.js";
+export interface DriftSnapshot {
+    generated: string;
+    /** Open drift events at the time of the snapshot. */
+    events: DriftEvent[];
+}
+export declare function recordDriftEvent(repoRoot: string, event: DriftEvent): void;
+export declare function writeDriftSnapshot(repoRoot: string, events: DriftEvent[]): string;

package/dist/drift.js

@@ -0,0 +1,23 @@
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { getLogger } from "./logger.js";
+import { stalenessCurrentPath, stalenessDir, stalenessLogPath } from "./paths.js";
+import { DriftEvent } from "./schemas.js";
+const log = getLogger();
+export function recordDriftEvent(repoRoot, event) {
+    const validated = DriftEvent.parse(event);
+    mkdirSync(stalenessDir(repoRoot), { recursive: true });
+    const line = `${JSON.stringify(validated)}\n`;
+    appendFileSync(stalenessLogPath(repoRoot), line, "utf8");
+    log.info({ kind: validated.kind, path: validated.path, severity: validated.severity }, "drift");
+}
+export function writeDriftSnapshot(repoRoot, events) {
+    mkdirSync(stalenessDir(repoRoot), { recursive: true });
+    const snapshot = {
+        generated: new Date().toISOString(),
+        events,
+    };
+    const path = stalenessCurrentPath(repoRoot);
+    writeFileSync(path, JSON.stringify(snapshot, null, 2), "utf8");
+    return path;
+}
+//# sourceMappingURL=drift.js.map

package/dist/drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.js","sourceRoot":"","sources":["../src/drift.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;AAQxB,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,KAAiB;IAClE,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1C,SAAS,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC;IAC9C,cAAc,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACzD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC;AAClG,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,MAAoB;IACvE,SAAS,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAkB;QAC9B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,MAAM;KACP,CAAC;IACF,MAAM,IAAI,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC5C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/file-candidates-map.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `.cairn/ground/file-candidates-map.yaml` — per-file count of
+ * topic-index entries with `dec_id IS NULL`.
+ *
+ * Built (and rebuilt) anywhere `topic-index.yaml` is written. The
+ * read-enrich PostToolUse hook on `Read` consults this map per file
+ * touched by the agent — `O(1)` lookup avoids re-walking the topic
+ * index on every read. When an entry has its `dec_id` stamped
+ * (phase 6 emit, PR 2 `cairn_propose_decision`), the index writer is
+ * responsible for refreshing this file too — that's why the helper is
+ * a pure pair of `(topicIndex) → FileCandidatesMap` plus a writer.
+ */
+import { FileCandidatesMap, type TopicIndex } from "./schemas.js";
+export declare function emptyFileCandidatesMap(): FileCandidatesMap;
+/**
+ * Compute the per-file candidate count by walking the topic-index.
+ * Each entry without a `dec_id` contributes 1 to its `sot_source`
+ * bucket. Files with zero unpromoted candidates are omitted from the
+ * map (so `Map.has(file)` is the gate, not a zero-check).
+ */
+export declare function buildFileCandidatesMap(topicIndex: TopicIndex): FileCandidatesMap;
+export declare function readFileCandidatesMap(repoRoot: string): FileCandidatesMap;
+export declare function writeFileCandidatesMap(repoRoot: string, topicIndex: TopicIndex): string;

package/dist/file-candidates-map.js

@@ -0,0 +1,76 @@
+/**
+ * `.cairn/ground/file-candidates-map.yaml` — per-file count of
+ * topic-index entries with `dec_id IS NULL`.
+ *
+ * Built (and rebuilt) anywhere `topic-index.yaml` is written. The
+ * read-enrich PostToolUse hook on `Read` consults this map per file
+ * touched by the agent — `O(1)` lookup avoids re-walking the topic
+ * index on every read. When an entry has its `dec_id` stamped
+ * (phase 6 emit, PR 2 `cairn_propose_decision`), the index writer is
+ * responsible for refreshing this file too — that's why the helper is
+ * a pure pair of `(topicIndex) → FileCandidatesMap` plus a writer.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { writeFileSafe } from "./fs.js";
+import { getLogger } from "./logger.js";
+import { fileCandidatesMapPath } from "./paths.js";
+import { FileCandidatesMap, } from "./schemas.js";
+const log = getLogger();
+export function emptyFileCandidatesMap() {
+    return {
+        version: 1,
+        generated: new Date().toISOString(),
+        file_candidates: {},
+    };
+}
+/**
+ * Compute the per-file candidate count by walking the topic-index.
+ * Each entry without a `dec_id` contributes 1 to its `sot_source`
+ * bucket. Files with zero unpromoted candidates are omitted from the
+ * map (so `Map.has(file)` is the gate, not a zero-check).
+ */
+export function buildFileCandidatesMap(topicIndex) {
+    const counts = new Map();
+    for (const entry of Object.values(topicIndex.topics)) {
+        if (entry.dec_id !== undefined)
+            continue;
+        const cur = counts.get(entry.sot_source) ?? 0;
+        counts.set(entry.sot_source, cur + 1);
+    }
+    const file_candidates = {};
+    const sortedFiles = [...counts.keys()].sort();
+    for (const f of sortedFiles)
+        file_candidates[f] = counts.get(f);
+    return {
+        version: 1,
+        generated: new Date().toISOString(),
+        file_candidates,
+    };
+}
+export function readFileCandidatesMap(repoRoot) {
+    const path = fileCandidatesMapPath(repoRoot);
+    if (!existsSync(path))
+        return emptyFileCandidatesMap();
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = FileCandidatesMap.safeParse(parseYaml(raw));
+        if (!parsed.success) {
+            log.warn({ path, error: parsed.error.message }, "file-candidates-map invalid; treating as empty");
+            return emptyFileCandidatesMap();
+        }
+        return parsed.data;
+    }
+    catch (err) {
+        log.warn({ path, err }, "file-candidates-map read failed; treating as empty");
+        return emptyFileCandidatesMap();
+    }
+}
+export function writeFileCandidatesMap(repoRoot, topicIndex) {
+    const path = fileCandidatesMapPath(repoRoot);
+    const map = buildFileCandidatesMap(topicIndex);
+    writeFileSafe(path, stringifyYaml(map));
+    log.debug({ path, files: Object.keys(map.file_candidates).length }, "wrote file-candidates-map");
+    return path;
+}
+//# sourceMappingURL=file-candidates-map.js.map

package/dist/file-candidates-map.js.map

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

package/dist/frontmatter.d.ts

@@ -0,0 +1,32 @@
+import { type ProvenanceFrontmatter as ProvenanceType } from "./schemas.js";
+export interface ParsedDocument {
+    frontmatter: ProvenanceType | null;
+    body: string;
+    /** Raw YAML block before parsing (empty if no frontmatter present). */
+    raw: string;
+    /** Number of lines the frontmatter (incl. fences) occupies. */
+    fenceLineCount: number;
+}
+/**
+ * Extract frontmatter from `source` and return it as an unvalidated
+ * `Record<string, unknown>` alongside the remaining body. Returns
+ * `{ fm: {}, body: source }` on any parse failure or absent frontmatter.
+ *
+ * Use this instead of an inline `.match(/^---…/)` when callers need
+ * arbitrary field access without a Zod schema.
+ */
+export declare function parseFrontmatterRecord(source: string): {
+    fm: Record<string, unknown>;
+    body: string;
+};
+export declare function parseFrontmatter(source: string): ParsedDocument;
+export declare function readFrontmatter(absPath: string): ParsedDocument;
+export interface FreshnessVerdict {
+    /** ISO timestamp from frontmatter, or null if missing/unparseable. */
+    verifiedAt: string | null;
+    /** Days since verifiedAt; null if verifiedAt is missing. */
+    ageDays: number | null;
+    /** "fresh" | "warn" | "block" | "unknown" — matches FILESYSTEM_LAYOUT §3. */
+    status: "fresh" | "warn" | "block" | "unknown";
+}
+export declare function evaluateFreshness(fm: ProvenanceType | null, warnDays?: number, blockDays?: number, now?: Date): FreshnessVerdict;

package/dist/frontmatter.js

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { ProvenanceFrontmatter } from "./schemas.js";
+const FENCE_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
+/**
+ * Extract frontmatter from `source` and return it as an unvalidated
+ * `Record<string, unknown>` alongside the remaining body. Returns
+ * `{ fm: {}, body: source }` on any parse failure or absent frontmatter.
+ *
+ * Use this instead of an inline `.match(/^---…/)` when callers need
+ * arbitrary field access without a Zod schema.
+ */
+export function parseFrontmatterRecord(source) {
+    const match = source.match(FENCE_RE);
+    if (match === null || match.index !== 0) {
+        return { fm: {}, body: source };
+    }
+    const raw = match[1] ?? "";
+    const body = source.slice(match[0].length);
+    if (raw.trim().length === 0)
+        return { fm: {}, body };
+    try {
+        const parsed = parseYaml(raw);
+        if (typeof parsed === "object" && parsed !== null) {
+            return { fm: parsed, body };
+        }
+    }
+    catch {
+        /* ignore — malformed YAML */
+    }
+    return { fm: {}, body };
+}
+export function parseFrontmatter(source) {
+    const match = source.match(FENCE_RE);
+    if (!match || match.index !== 0) {
+        return { frontmatter: null, body: source, raw: "", fenceLineCount: 0 };
+    }
+    const raw = match[1] ?? "";
+    const fence = match[0];
+    const body = source.slice(fence.length);
+    const fenceLineCount = fence.split(/\r?\n/).length - 1;
+    if (raw.trim().length === 0) {
+        return { frontmatter: null, body, raw, fenceLineCount };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return { frontmatter: null, body, raw, fenceLineCount };
+    }
+    const result = ProvenanceFrontmatter.safeParse(parsed);
+    return {
+        frontmatter: result.success ? result.data : null,
+        body,
+        raw,
+        fenceLineCount,
+    };
+}
+export function readFrontmatter(absPath) {
+    const source = readFileSync(absPath, "utf8");
+    return parseFrontmatter(source);
+}
+export function evaluateFreshness(fm, warnDays = 30, blockDays = 60, now = new Date()) {
+    if (!fm || !fm["verified-at"]) {
+        return { verifiedAt: null, ageDays: null, status: "unknown" };
+    }
+    const ts = Date.parse(fm["verified-at"]);
+    if (Number.isNaN(ts)) {
+        return { verifiedAt: fm["verified-at"], ageDays: null, status: "unknown" };
+    }
+    const ageMs = now.getTime() - ts;
+    const ageDays = Math.floor(ageMs / 86_400_000);
+    const status = ageDays >= blockDays ? "block" : ageDays >= warnDays ? "warn" : "fresh";
+    return { verifiedAt: fm["verified-at"], ageDays, status };
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

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

package/dist/fs.d.ts

@@ -0,0 +1,36 @@
+import { type Dirent } from "node:fs";
+/**
+ * Write `data` to `path`, creating parent directories as needed.
+ * Encoding is always UTF-8.
+ */
+export declare function writeFileSafe(path: string, data: string): void;
+/**
+ * Generic directory walker options.
+ */
+export interface WalkFsOptions {
+    /** The root directory to start walking from. */
+    dir: string;
+    /** Optional set of directory names to skip (e.g., .git, node_modules). */
+    skipDirs?: Set<string>;
+    /**
+     * Callback for each file found.
+     * @param rel Repo-relative path (if repoRoot provided) or dir-relative path.
+     * @param abs Absolute path to the file.
+     * @param entry The Dirent object.
+     */
+    onFile?: (rel: string, abs: string, entry: Dirent) => void;
+    /**
+     * Callback for each directory found.
+     * @returns false to skip recursion into this directory.
+     */
+    onDir?: (rel: string, abs: string, entry: Dirent) => boolean | void;
+    /**
+     * If provided, relative paths passed to callbacks will be relative to this root.
+     * If not provided, paths will be relative to `dir`.
+     */
+    repoRoot?: string;
+}
+/**
+ * Generic recursive directory walker.
+ */
+export declare function walkFs(opts: WalkFsOptions): void;

package/dist/fs.js

@@ -0,0 +1,47 @@
+import { readdirSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+/**
+ * Write `data` to `path`, creating parent directories as needed.
+ * Encoding is always UTF-8.
+ */
+export function writeFileSafe(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, data, "utf8");
+}
+/**
+ * Generic recursive directory walker.
+ */
+export function walkFs(opts) {
+    const { dir, skipDirs, onFile, onDir, repoRoot } = opts;
+    const root = repoRoot ?? dir;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const currentDir = stack.pop();
+        if (currentDir === undefined)
+            break;
+        let entries;
+        try {
+            entries = readdirSync(currentDir, { withFileTypes: true, encoding: "utf8" });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const abs = join(currentDir, entry.name);
+            const rel = relative(root, abs).replace(/\\/g, "/");
+            if (entry.isDirectory()) {
+                if (skipDirs?.has(entry.name))
+                    continue;
+                const shouldRecurse = onDir ? onDir(rel, abs, entry) : true;
+                if (shouldRecurse !== false) {
+                    stack.push(abs);
+                }
+            }
+            else if (entry.isFile()) {
+                if (onFile)
+                    onFile(rel, abs, entry);
+            }
+        }
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAY;IACtD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AA6BD;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,IAAmB;IACxC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACxD,MAAM,IAAI,GAAG,QAAQ,IAAI,GAAG,CAAC;IAE7B,MAAM,KAAK,GAAa,CAAC,GAAG,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QAC/B,IAAI,UAAU,KAAK,SAAS;YAAE,MAAM;QAEpC,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/E,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAEpD,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,SAAS;gBACxC,MAAM,aAAa,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC5D,IAAI,aAAa,KAAK,KAAK,EAAE,CAAC;oBAC5B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAClB,CAAC;YACH,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC1B,IAAI,MAAM;oBAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/glob.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Minimal glob matcher (no external dep). Supports `**`, `*`, `?`, and literal
+ * segments. Patterns are POSIX-style; segments separator is forward slash.
+ *
+ * Single home for glob matching across the package — walker, GC sweep,
+ * sensors, mirror dirty-overlap, and MCP tools all import from here.
+ */
+export declare function matchGlob(path: string, glob: string): boolean;
+export declare function matchAnyGlob(path: string, globs: readonly string[]): boolean;
+export declare function compileGlob(glob: string): RegExp;

package/dist/glob.js

@@ -0,0 +1,46 @@
+/**
+ * Minimal glob matcher (no external dep). Supports `**`, `*`, `?`, and literal
+ * segments. Patterns are POSIX-style; segments separator is forward slash.
+ *
+ * Single home for glob matching across the package — walker, GC sweep,
+ * sensors, mirror dirty-overlap, and MCP tools all import from here.
+ */
+export function matchGlob(path, glob) {
+    return compileGlob(glob).test(path);
+}
+export function matchAnyGlob(path, globs) {
+    return globs.some((g) => matchGlob(path, g));
+}
+export function compileGlob(glob) {
+    let re = "^";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                i += 1;
+                if (glob[i + 1] === "/") {
+                    i += 1;
+                    re += "(?:.*/)?";
+                }
+                else {
+                    re += ".*";
+                }
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            re += "[^/]";
+        }
+        else if (c !== undefined && /[.+^${}()|[\]\\]/.test(c)) {
+            re += `\\${c}`;
+        }
+        else {
+            re += c ?? "";
+        }
+    }
+    re += "$";
+    return new RegExp(re);
+}
+//# sourceMappingURL=glob.js.map

package/dist/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../src/glob.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAY;IAClD,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAAwB;IACjE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,EAAE,GAAG,GAAG,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACd,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACxB,CAAC,IAAI,CAAC,CAAC;gBACP,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;oBACxB,CAAC,IAAI,CAAC,CAAC;oBACP,EAAE,IAAI,UAAU,CAAC;gBACnB,CAAC;qBAAM,CAAC;oBACN,EAAE,IAAI,IAAI,CAAC;gBACb,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,EAAE,IAAI,OAAO,CAAC;YAChB,CAAC;QACH,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACrB,EAAE,IAAI,MAAM,CAAC;QACf,CAAC;aAAM,IAAI,CAAC,KAAK,SAAS,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,EAAE,IAAI,KAAK,CAAC,EAAE,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IACD,EAAE,IAAI,GAAG,CAAC;IACV,OAAO,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC"}

package/dist/home.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Cairn state-home resolver — the single source of truth for *where* a repo's
+ * Cairn state lives. Committed mode (the default) returns `<repoRoot>/.cairn`,
+ * byte-for-byte today's behavior. Ghost mode returns an out-of-repo directory
+ * under `~/.cairn/state/<repo-id>/`, so nothing Cairn-shaped ever lands in the
+ * client tree.
+ *
+ * This is pure indirection: every `paths.ts` helper (and every other call site
+ * that used to hardcode `join(repoRoot, ".cairn", …)`) builds on `cairnHome`
+ * here. Centralizing the state location is a standalone win independent of
+ * ghost — it makes the location relocatable, testable, and a single seam.
+ *
+ * The resolver chicken-and-egg (the ghost flag normally lives in the config
+ * file, but in ghost that file is *inside* the out-of-repo home) is broken by a
+ * global registry outside any client repo: `~/.cairn/registry.yaml`.
+ */
+/**
+ * Global Cairn state home — `~/.cairn/state/`. Hardcoded (the operator hates
+ * env vars). Per-repo ghost state lives at `<stateHome>/<repo-id>/`, mirroring
+ * the in-repo `.cairn/` layout (`ground/`, `config.yaml`, `git-hooks/`, …) but
+ * physically outside every client repo tree.
+ */
+export declare function stateHome(): string;
+/** `~/.cairn/state/<repoId>` — the out-of-repo home for one ghost repo. */
+export declare function ghostStateDir(repoId: string): string;
+/** `~/.cairn/registry.yaml` — the global repo→mode map, outside any repo. */
+export declare function registryPath(): string;
+/** One registry record. `<repo-id>` keys on the move-stable root-commit SHA. */
+export interface RegistryEntry {
+    /** "ghost" | "committed" — only "ghost" entries relocate state. */
+    mode: string;
+    /** Absolute out-of-repo state dir. */
+    state_dir: string;
+    /** Move-stable identity: the repo's root-commit SHA. */
+    root_commit?: string;
+    /** Last-seen absolute path of the client checkout (abs-path fallback). */
+    last_path?: string;
+}
+interface Registry {
+    repos?: Record<string, RegistryEntry>;
+}
+/**
+ * Drop the memoized resolution for a repo (or all repos). Call after mutating
+ * the registry — e.g. `cairn init --ghost` registers a repo, then seed must
+ * resolve to the *new* out-of-repo home rather than a stale committed cache.
+ */
+export declare function invalidateCairnHomeCache(repoRoot?: string): void;
+/** Read `~/.cairn/registry.yaml`; null when absent/broken (→ committed). */
+export declare function readRegistry(): Registry | null;
+/**
+ * Resolve the Cairn state home for a repo — the base every path helper builds
+ * on. Committed: `<repoRoot>/.cairn`. Ghost: the out-of-repo `state_dir`.
+ */
+export declare function cairnHome(repoRoot: string): string;
+/** True when this repo is registered ghost. Registry lookup, memoized. */
+export declare function isGhost(repoRoot: string): boolean;
+/**
+ * `join(cairnHome(repoRoot), ...segments)` — the workhorse builder that
+ * replaces every `join(repoRoot, ".cairn", …)` outside `paths.ts`.
+ */
+export declare function cairnDir(repoRoot: string, ...segments: string[]): string;
+/**
+ * Register a repo as ghost in the global registry, keyed on its root-commit
+ * SHA (abs-path key fallback for pre-first-commit repos), and return the
+ * resolved out-of-repo state dir. Invalidates the resolver cache so subsequent
+ * `cairnHome` calls relocate immediately.
+ */
+export declare function registerGhostRepo(repoRoot: string): RegistryEntry;
+export {};