@cairn-tool/cairn 2.0.0

package/dist/sqlite-store.d.ts

@@ -0,0 +1,62 @@
+import type { SqliteDatabase } from "./sqlite.js";
+/**
+ * Opening and migrating a SQLite store this project owns.
+ *
+ * Two stores use it — the usage store and the artifact archive index — and they
+ * share it rather than each carrying a copy, because the parts that are easy to
+ * get subtly wrong are the same in both: running migrations inside one
+ * transaction, writing `user_version` inside that same transaction, and refusing
+ * a file from the future instead of writing to it.
+ *
+ * These are **migrated** stores, not caches. `src/url-cache.ts` and the
+ * workspace index invalidate by discarding, which is safe because their contents
+ * are always re-derivable. Neither of these is: an archive holds the only copy
+ * of files that may since have been deleted, and the usage store can outlive the
+ * transcripts it was built from. So a version bump carries the data forward, and
+ * the rules in {@link Migration} are not optional.
+ */
+export interface Migration {
+    version: number;
+    description: string;
+    up(db: SqliteDatabase): void;
+}
+/**
+ * Thrown when the file on disk was written by a newer build.
+ *
+ * Refusing is the point. A newer schema may carry columns this build does not
+ * know about, and opening it read-write would drop them on the next write — for
+ * a store that may hold the only copy of something, silently.
+ */
+export declare class StoreTooNewError extends Error {
+    readonly label: string;
+    readonly found: number;
+    readonly supported: number;
+    constructor(label: string, found: number, supported: number);
+}
+export interface StoreOptions {
+    path: string;
+    /** Ordered migrations. The highest version is what this build writes. */
+    migrations: readonly Migration[];
+    /** Names the store in error messages, e.g. "usage database". */
+    label: string;
+    /** Open without migrating, and refuse to create. */
+    readOnly?: boolean;
+    /** Apply pending migrations. Default true. */
+    migrate?: boolean;
+}
+export interface StoreHandle {
+    db: SqliteDatabase;
+    /** Version before this call did anything. */
+    from: number;
+    /** Version now. */
+    to: number;
+    /** Versions applied by this call, in order. */
+    applied: number[];
+}
+export declare function latestVersion(migrations: readonly Migration[]): number;
+export declare function userVersion(db: SqliteDatabase): number;
+export declare function openStore(options: StoreOptions): StoreHandle;
+/** Closing must never fail a caller that already has its answer. */
+export declare function closeQuietly(db: SqliteDatabase | undefined): void;
+/** Runs `work` inside a transaction, rolling back if it throws. */
+export declare function transact<T>(db: SqliteDatabase, work: () => T): T;

package/dist/sqlite-store.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { requireSqlite } from "./sqlite.js";
+/**
+ * Thrown when the file on disk was written by a newer build.
+ *
+ * Refusing is the point. A newer schema may carry columns this build does not
+ * know about, and opening it read-write would drop them on the next write — for
+ * a store that may hold the only copy of something, silently.
+ */
+export class StoreTooNewError extends Error {
+    label;
+    found;
+    supported;
+    constructor(label, found, supported) {
+        super(`The ${label} is at schema version ${found}, but this build of cairn ` +
+            `understands ${supported}. Upgrade cairn to read it.`);
+        this.label = label;
+        this.found = found;
+        this.supported = supported;
+        this.name = "StoreTooNewError";
+    }
+}
+export function latestVersion(migrations) {
+    return migrations.reduce((highest, migration) => Math.max(highest, migration.version), 0);
+}
+export function userVersion(db) {
+    const value = db.prepare("PRAGMA user_version").get()?.user_version;
+    return typeof value === "number" ? value : 0;
+}
+export function openStore(options) {
+    const sqlite = requireSqlite();
+    const readOnly = options.readOnly === true;
+    const latest = latestVersion(options.migrations);
+    if (readOnly && !fs.existsSync(options.path)) {
+        throw new Error(`No ${options.label} at ${options.path}.`);
+    }
+    if (!readOnly)
+        fs.mkdirSync(path.dirname(options.path), { recursive: true });
+    const db = new sqlite.DatabaseSync(options.path, readOnly ? { readOnly: true } : {});
+    try {
+        if (!readOnly) {
+            // WAL so a reader in another process is not blocked by an import, which is
+            // the normal shape here: a report runs while another terminal writes.
+            db.exec("PRAGMA journal_mode = WAL");
+            db.exec("PRAGMA synchronous = NORMAL");
+        }
+        // Both schemas lean on ON DELETE CASCADE to replace a row's children. With
+        // this pragma off SQLite silently orphans them instead.
+        db.exec("PRAGMA foreign_keys = ON");
+        const from = userVersion(db);
+        if (from > latest)
+            throw new StoreTooNewError(options.label, from, latest);
+        const applied = [];
+        if (options.migrate !== false && !readOnly && from < latest) {
+            const pending = options.migrations
+                .filter((migration) => migration.version > from)
+                .sort((a, b) => a.version - b.version);
+            db.exec("BEGIN");
+            try {
+                for (const migration of pending) {
+                    migration.up(db);
+                    applied.push(migration.version);
+                }
+                // A pragma takes no bound parameter, so the value is interpolated. It is
+                // a number derived from this build's own migration list, never input.
+                db.exec(`PRAGMA user_version = ${latest}`);
+                db.exec("COMMIT");
+            }
+            catch (error) {
+                db.exec("ROLLBACK");
+                throw error;
+            }
+        }
+        return { db, from, to: userVersion(db), applied };
+    }
+    catch (error) {
+        closeQuietly(db);
+        throw error;
+    }
+}
+/** Closing must never fail a caller that already has its answer. */
+export function closeQuietly(db) {
+    try {
+        db?.close();
+    }
+    catch {
+        // Best-effort.
+    }
+}
+/** Runs `work` inside a transaction, rolling back if it throws. */
+export function transact(db, work) {
+    db.exec("BEGIN");
+    try {
+        const result = work();
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+//# sourceMappingURL=sqlite-store.js.map

package/dist/sqlite-store.js.map

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

package/dist/sqlite.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The `node:sqlite` boundary.
+ *
+ * Two very different callers share this module. The antigravity provider opens
+ * somebody else's database read-only and treats every failure as a missing
+ * token column; the usage store and the artifact archive own their databases and
+ * write to them. What they have in common is the loader below, which must not be
+ * duplicated: the `process.emitWarning` swap it performs is load-bearing, and a
+ * second copy would be a second chance to get it wrong.
+ *
+ * The interfaces are hand-written rather than imported from `node:sqlite`
+ * because the module is only required at runtime — `@types/node` declares it,
+ * but importing the type would make `dist` depend on a module the type checker
+ * resolves and the emitted code must not.
+ */
+export interface SqliteRow {
+    [column: string]: unknown;
+}
+/** The subset of `StatementSync` this project uses. */
+export interface SqliteStatement {
+    all(...parameters: unknown[]): SqliteRow[];
+    get(...parameters: unknown[]): SqliteRow | undefined;
+    run(...parameters: unknown[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    iterate(...parameters: unknown[]): IterableIterator<SqliteRow>;
+}
+/** The subset of `DatabaseSync` this project uses. */
+export interface SqliteDatabase {
+    prepare(sql: string): SqliteStatement;
+    exec(sql: string): void;
+    close(): void;
+}
+export interface SqliteModule {
+    DatabaseSync: new (path: string, options?: object) => SqliteDatabase;
+}
+/**
+ * Loads `node:sqlite`, suppressing its experimental warning.
+ *
+ * The warning goes to stderr, and stderr carries the JSON payload whenever a
+ * command reports findings — so letting it through would corrupt a consumer's
+ * parse. This is the same rule that keeps the update notifier off machine-
+ * readable streams.
+ *
+ * Returns null when the runtime has no `node:sqlite`. For the antigravity
+ * provider that costs the token column and nothing else; for the usage store it
+ * is fatal, and `openDatabase` says so rather than degrading silently.
+ *
+ * The tri-state memo is deliberate: `undefined` means untried, `null` means
+ * tried and unavailable, so a missing module is not re-required per call.
+ */
+export declare function loadSqlite(): SqliteModule | null;
+/** Thrown when a caller that requires SQLite cannot have it. */
+export declare class SqliteUnavailableError extends Error {
+    constructor();
+}
+/** Loads the module or throws. For callers that cannot degrade. */
+export declare function requireSqlite(): SqliteModule;

package/dist/sqlite.js

@@ -0,0 +1,51 @@
+import { createRequire } from "node:module";
+let sqliteModule;
+/**
+ * Loads `node:sqlite`, suppressing its experimental warning.
+ *
+ * The warning goes to stderr, and stderr carries the JSON payload whenever a
+ * command reports findings — so letting it through would corrupt a consumer's
+ * parse. This is the same rule that keeps the update notifier off machine-
+ * readable streams.
+ *
+ * Returns null when the runtime has no `node:sqlite`. For the antigravity
+ * provider that costs the token column and nothing else; for the usage store it
+ * is fatal, and `openDatabase` says so rather than degrading silently.
+ *
+ * The tri-state memo is deliberate: `undefined` means untried, `null` means
+ * tried and unavailable, so a missing module is not re-required per call.
+ */
+export function loadSqlite() {
+    if (sqliteModule !== undefined)
+        return sqliteModule;
+    const emit = process.emitWarning;
+    try {
+        process.emitWarning = () => { };
+        // A synchronous require of a builtin, which `import` cannot do from a
+        // non-async call site. `createRequire` is how ESM asks for one.
+        sqliteModule = createRequire(import.meta.url)("node:sqlite");
+    }
+    catch {
+        sqliteModule = null;
+    }
+    finally {
+        process.emitWarning = emit;
+    }
+    return sqliteModule;
+}
+/** Thrown when a caller that requires SQLite cannot have it. */
+export class SqliteUnavailableError extends Error {
+    constructor() {
+        super("This build of Node has no `node:sqlite`. The usage store needs it; " +
+            "run with --no-index to report without one.");
+        this.name = "SqliteUnavailableError";
+    }
+}
+/** Loads the module or throws. For callers that cannot degrade. */
+export function requireSqlite() {
+    const module = loadSqlite();
+    if (!module)
+        throw new SqliteUnavailableError();
+    return module;
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../src/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyC5C,IAAI,YAA6C,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,UAAU;IACxB,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IACpD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,CAAC,WAAW,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;QAC/B,sEAAsE;QACtE,gEAAgE;QAChE,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,aAAa,CAAiB,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,YAAY,GAAG,IAAI,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,gEAAgE;AAChE,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C;QACE,KAAK,CACH,qEAAqE;YACnE,4CAA4C,CAC/C,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,UAAU,aAAa;IAC3B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,sBAAsB,EAAE,CAAC;IAChD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/toc.d.ts

@@ -0,0 +1,58 @@
+import { type MdCodeBlock, type MdHeading } from "./markdown-ast.js";
+export declare const TOC_START = "<!-- cairn:toc:start -->";
+export declare const TOC_END = "<!-- cairn:toc:end -->";
+/**
+ * The pre-rename markers, still recognized so documents already carrying them
+ * keep synchronizing.
+ *
+ * A found pair keeps its own spelling: `synchronizeToc` only ever rewrites the
+ * interior between the markers, never the markers themselves. Migrating them on
+ * `--write` would report every legacy document as stale for a change that alters
+ * no table of contents, so the two spellings are equal forever and only an
+ * inserted pair uses the current one.
+ */
+export declare const LEGACY_TOC_START = "<!-- claude-cli:toc:start -->";
+export declare const LEGACY_TOC_END = "<!-- claude-cli:toc:end -->";
+export declare function renderToc(headings: MdHeading[], ordered?: boolean): string;
+/**
+ * Offsets of the bytes strictly between the markers.
+ *
+ * Reported so a caller can express the update as a scoped edit rather than a
+ * whole-file replacement; `synchronizeToc` computes it either way.
+ */
+export interface TocRange {
+    start: number;
+    end: number;
+}
+export type TocSynchronization = {
+    status: "missing";
+} | {
+    status: "malformed";
+    message: string;
+} | {
+    status: "current";
+    content: string;
+    block: string;
+    range: TocRange;
+} | {
+    status: "stale";
+    content: string;
+    replacement: string;
+    block: string;
+    range: TocRange;
+    /** The rendered interior that belongs between the markers. */
+    interior: string;
+};
+/**
+ * Locates the marker block, ignoring markers inside fenced code.
+ *
+ * Markers are found by scanning raw text, so a fenced block *documenting* the
+ * syntax — as this project's own README and `md toc` page both do — would
+ * otherwise look like a real pair, and writing a table of contents into a code
+ * sample would corrupt it.
+ *
+ * `codeBlocks` is optional only so a caller that already parsed the document
+ * can avoid a second parse. Omitting it parses rather than skipping the check,
+ * so a caller cannot silently opt out.
+ */
+export declare function synchronizeToc(content: string, toc: string, codeBlocks?: readonly MdCodeBlock[]): TocSynchronization;

package/dist/toc.js

@@ -0,0 +1,83 @@
+import { extractCodeBlocks, isLineInCodeBlock, parseMarkdown, } from "./markdown-ast.js";
+export const TOC_START = "<!-- cairn:toc:start -->";
+export const TOC_END = "<!-- cairn:toc:end -->";
+/**
+ * The pre-rename markers, still recognized so documents already carrying them
+ * keep synchronizing.
+ *
+ * A found pair keeps its own spelling: `synchronizeToc` only ever rewrites the
+ * interior between the markers, never the markers themselves. Migrating them on
+ * `--write` would report every legacy document as stale for a change that alters
+ * no table of contents, so the two spellings are equal forever and only an
+ * inserted pair uses the current one.
+ */
+export const LEGACY_TOC_START = "<!-- claude-cli:toc:start -->";
+export const LEGACY_TOC_END = "<!-- claude-cli:toc:end -->";
+export function renderToc(headings, ordered = false) {
+    if (!headings.length)
+        return "";
+    const baseDepth = Math.min(...headings.map((heading) => heading.depth));
+    return headings
+        .map((heading) => `${"  ".repeat(heading.depth - baseDepth)}${ordered ? "1." : "-"} [${heading.text}](#${heading.slug})`)
+        .join("\n");
+}
+/** 1-based line containing `offset`. */
+function lineOf(content, offset) {
+    let line = 1;
+    for (let index = 0; index < offset && index < content.length; index++) {
+        if (content[index] === "\n")
+            line++;
+    }
+    return line;
+}
+/**
+ * Locates the marker block, ignoring markers inside fenced code.
+ *
+ * Markers are found by scanning raw text, so a fenced block *documenting* the
+ * syntax — as this project's own README and `md toc` page both do — would
+ * otherwise look like a real pair, and writing a table of contents into a code
+ * sample would corrupt it.
+ *
+ * `codeBlocks` is optional only so a caller that already parsed the document
+ * can avoid a second parse. Omitting it parses rather than skipping the check,
+ * so a caller cannot silently opt out.
+ */
+export function synchronizeToc(content, toc, codeBlocks) {
+    const fenced = codeBlocks ?? extractCodeBlocks(parseMarkdown(content));
+    const outsideFence = (match) => !isLineInCodeBlock(lineOf(content, match.index), [...fenced]);
+    const matches = (marker) => [...content.matchAll(new RegExp(marker, "g"))].filter(outsideFence);
+    const starts = [...matches(TOC_START), ...matches(LEGACY_TOC_START)];
+    const ends = [...matches(TOC_END), ...matches(LEGACY_TOC_END)];
+    if (!starts.length && !ends.length)
+        return { status: "missing" };
+    if (starts.length !== 1 || ends.length !== 1)
+        return { status: "malformed", message: "Expected exactly one TOC marker pair" };
+    // Both spellings are read, but a pair may not mix them: the two halves of one
+    // block always came from the same writer, so a mixed pair is a hand edit that
+    // silently lost half a rename rather than something to guess at.
+    const legacy = starts[0][0] === LEGACY_TOC_START;
+    if (legacy !== (ends[0][0] === LEGACY_TOC_END))
+        return { status: "malformed", message: "TOC start and end markers use different spellings" };
+    const startMarker = legacy ? LEGACY_TOC_START : TOC_START;
+    const endMarker = legacy ? LEGACY_TOC_END : TOC_END;
+    const startEnd = starts[0].index + startMarker.length;
+    const endStart = ends[0].index;
+    if (endStart < startEnd)
+        return { status: "malformed", message: "TOC end marker appears before start marker" };
+    const eol = content.includes("\r\n") ? "\r\n" : "\n";
+    const normalizedToc = toc.replace(/\r?\n/g, eol);
+    const interior = `${eol}${normalizedToc}${normalizedToc ? eol : ""}`;
+    const block = `${startMarker}${interior}${endMarker}`;
+    const range = { start: startEnd, end: endStart };
+    if (content.slice(startEnd, endStart) === interior)
+        return { status: "current", content, block, range };
+    return {
+        status: "stale",
+        content,
+        replacement: content.slice(0, startEnd) + interior + content.slice(endStart),
+        block,
+        range,
+        interior,
+    };
+}
+//# sourceMappingURL=toc.js.map

package/dist/toc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toc.js","sourceRoot":"","sources":["../src/toc.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,GAGd,MAAM,mBAAmB,CAAC;AAE3B,MAAM,CAAC,MAAM,SAAS,GAAG,0BAA0B,CAAC;AACpD,MAAM,CAAC,MAAM,OAAO,GAAG,wBAAwB,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AAChE,MAAM,CAAC,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAE5D,MAAM,UAAU,SAAS,CAAC,QAAqB,EAAE,OAAO,GAAG,KAAK;IAC9D,IAAI,CAAC,QAAQ,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,OAAO,QAAQ;SACZ,GAAG,CACF,CAAC,OAAO,EAAE,EAAE,CACV,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,CAAC,IAAI,MAAM,OAAO,CAAC,IAAI,GAAG,CACzG;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AA2BD,wCAAwC;AACxC,SAAS,MAAM,CAAC,OAAe,EAAE,MAAc;IAC7C,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,IAAI,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACtE,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI;YAAE,IAAI,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,GAAW,EACX,UAAmC;IAEnC,MAAM,MAAM,GAAG,UAAU,IAAI,iBAAiB,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IACvE,MAAM,YAAY,GAAG,CAAC,KAAyC,EAAW,EAAE,CAC1E,CAAC,iBAAiB,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,KAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAEjE,MAAM,OAAO,GAAG,CAAC,MAAc,EAAqB,EAAE,CACpD,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAsB,CAAC;IAE3F,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACjE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAC1C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC;IAElF,8EAA8E;IAC9E,8EAA8E;IAC9E,iEAAiE;IACjE,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAAC;IACjD,IAAI,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC;QAC5C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,mDAAmD,EAAE,CAAC;IAC/F,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1D,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC;IAEpD,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAM,GAAG,WAAW,CAAC,MAAM,CAAC;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,KAAM,CAAC;IAChC,IAAI,QAAQ,GAAG,QAAQ;QACrB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,4CAA4C,EAAE,CAAC;IACxF,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,GAAG,GAAG,GAAG,aAAa,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACrE,MAAM,KAAK,GAAG,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,EAAE,CAAC;IACtD,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;IACjD,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,QAAQ;QAChD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACtD,OAAO;QACL,MAAM,EAAE,OAAO;QACf,OAAO;QACP,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC5E,KAAK;QACL,KAAK;QACL,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+export interface Issue {
+    file: string;
+    line: number;
+    checker: string;
+    message: string;
+}
+export type OutputFormat = "llm" | "human" | "json" | "jsonl" | "sarif";

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/update-notifier.d.ts

@@ -0,0 +1,95 @@
+/** How long a cached result stays fresh. */
+export declare const CHECK_INTERVAL_MS: number;
+/** argv token that runs the detached cache refresh. Hidden from help. */
+export declare const REFRESH_COMMAND = "__refresh-update-cache";
+/** User-facing command that checks explicitly; suppresses the passive notice. */
+export declare const CHECK_COMMAND = "check-update";
+/**
+ * Contract-discovery commands. Their stdout is unconditionally a machine
+ * document, so a notice is never useful alongside them.
+ */
+export declare const DESCRIBE_COMMAND = "describe";
+export declare const SCHEMA_COMMAND = "schema";
+export declare const COMPLETION_COMMAND = "completion";
+/**
+ * `scripts run` hands its stderr to a child process, so a notice appended at exit
+ * would land inside whatever the calling hook captured.
+ */
+export declare const SCRIPTS_COMMAND = "scripts";
+export declare const SCRIPTS_RUN_SUBCOMMAND = "run";
+/**
+ * The machine-stream guarantees, published through `describe` so consumers can
+ * read them rather than infer them. Exported from here, next to the gate that
+ * enforces them, so the two cannot drift.
+ */
+export declare const NOTIFIER_CONTRACT: {
+    readonly description: "The update notice is advisory only and never appears on a machine-readable stream.";
+    readonly stream: "stderr";
+    readonly suppressedWhen: readonly ["CAIRN_NO_UPDATE_NOTIFIER=1", "CI is set", "stderr is not a TTY", "--format is json, jsonl, or sarif, including a project-configured format", "the command is check-update, describe, schema, completion, scripts run, or the internal cache refresh"];
+    readonly optOutEnv: "CAIRN_NO_UPDATE_NOTIFIER";
+};
+/**
+ * How long a held refresh lock is trusted. Must exceed the child's own fetch
+ * timeout so a working refresh is never treated as abandoned.
+ */
+export declare const LOCK_STALE_MS = 60000;
+export interface UpdateCache {
+    /** Epoch ms of the last attempt — set even when the attempt failed, so failures back off too. */
+    lastCheckedAt: number;
+    /** Last known published version, or null if never resolved. */
+    latestVersion: string | null;
+}
+export declare function getCachePath(env?: NodeJS.ProcessEnv, homedir?: string): string;
+export declare function readCache(cachePath: string): UpdateCache | null;
+export declare function writeCache(cachePath: string, cache: UpdateCache): boolean;
+export declare function getLockPath(cachePath: string): string;
+/**
+ * Exclusively claims the right to spawn a refresh, so concurrent invocations
+ * cannot each start their own child process. Uses an atomic `wx` create rather
+ * than an exists-then-write check, which would race.
+ *
+ * Returns false when another refresh is already in flight.
+ */
+export declare function acquireRefreshLock(lockPath: string, now: number, staleMs?: number): boolean;
+export declare function releaseRefreshLock(lockPath: string): void;
+export declare function isCacheStale(cache: UpdateCache | null, now: number, intervalMs?: number): boolean;
+/**
+ * True when `candidate` is a strictly newer release than `current`.
+ *
+ * Deliberately conservative: unparseable input and prerelease-to-prerelease
+ * comparisons return false. A wrong `true` nags the user on every command, so
+ * staying quiet is the safer failure mode.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+/** Detects JSON output from already-normalised argv (cli.ts expands `-fj` first). */
+export declare function hasJsonOutput(argv: readonly string[]): boolean;
+export interface NotifyDecision {
+    currentVersion: string;
+    cache: UpdateCache | null;
+    argv: readonly string[];
+    isTty: boolean;
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Whether the notice may be shown at all. Also gates the background refresh, so
+ * non-interactive callers never spawn a child process either.
+ */
+export declare function isNotifierAllowed(ctx: Omit<NotifyDecision, "cache" | "currentVersion">): boolean;
+export declare function shouldNotify(ctx: NotifyDecision): boolean;
+export declare function formatNotice(current: string, latest: string, packageName: string): string;
+export interface InstallOptions {
+    currentVersion: string;
+    packageName: string;
+    argv: readonly string[];
+    /** Path to the CLI entry point, re-invoked for the detached refresh. */
+    entryPoint: string;
+    env?: NodeJS.ProcessEnv;
+    now?: number;
+    isTty?: boolean;
+    cachePath?: string;
+}
+/**
+ * Prints an update notice from cache at process exit and kicks off a detached refresh when
+ * the cache is stale. Never delays or fails a command.
+ */
+export declare function installUpdateNotifier(opts: InstallOptions): void;