mneme-ai 0.24.0 → 0.25.0

package/dist/iris/adaptive.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Iris — adaptive verbosity per user history.
+ *
+ * Goal: first-time users of `mneme forensics` see the verbose "how to read"
+ * guide.  After they've run it 5+ times, we trust they know — collapse the
+ * guide to a one-liner.
+ *
+ * State lives in `<repoRoot>/.mneme/iris-state.json` (sibling to session.json).
+ * Atomic writes via temp-file rename.
+ *
+ * Pure-ish: state is read/written through a small, file-only API.  All policy
+ * decisions (`shouldShowVerboseGuide`, etc.) are pure functions of the state.
+ */
+export interface IrisState {
+    /** Command name → run count. */
+    commandsRun: Record<string, number>;
+    /** Toggled true after 5+ uses of any one command. */
+    preferTerse: boolean;
+    /** Command → ISO timestamp of most recent run. */
+    lastSeen: Record<string, string>;
+}
+/** Threshold above which we start showing the terse output. */
+export declare const VERBOSE_GUIDE_THRESHOLD = 5;
+/** Read state — returns a clean default if missing or corrupt. */
+export declare function readIrisState(repoRoot: string): IrisState;
+/** Persist state atomically. */
+export declare function writeIrisState(repoRoot: string, state: IrisState): void;
+/** Increment the run-count for a command and persist.  Best-effort. */
+export declare function recordCommandRun(repoRoot: string, command: string): void;
+/**
+ * Should we show the verbose how-to-read guide for this command?
+ *
+ * True when the user has run the command fewer than 5 times.  We do NOT
+ * gate on `preferTerse` for the per-command decision — preferTerse only
+ * influences shared chrome (banners, footers).
+ */
+export declare function shouldShowVerboseGuide(state: IrisState, command: string): boolean;
+/** Reset state — used by tests and `mneme reset-iris`. */
+export declare function clearIrisState(repoRoot: string): void;
+//# sourceMappingURL=adaptive.d.ts.map

package/dist/iris/adaptive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive.d.ts","sourceRoot":"","sources":["../../src/iris/adaptive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,qDAAqD;IACrD,WAAW,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,+DAA+D;AAC/D,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAUzC,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAmCzD;AAwBD,gCAAgC;AAChC,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAEvE;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAYxE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGjF;AAED,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQrD"}

package/dist/iris/adaptive.js

@@ -0,0 +1,131 @@
+/**
+ * Iris — adaptive verbosity per user history.
+ *
+ * Goal: first-time users of `mneme forensics` see the verbose "how to read"
+ * guide.  After they've run it 5+ times, we trust they know — collapse the
+ * guide to a one-liner.
+ *
+ * State lives in `<repoRoot>/.mneme/iris-state.json` (sibling to session.json).
+ * Atomic writes via temp-file rename.
+ *
+ * Pure-ish: state is read/written through a small, file-only API.  All policy
+ * decisions (`shouldShowVerboseGuide`, etc.) are pure functions of the state.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+/** Threshold above which we start showing the terse output. */
+export const VERBOSE_GUIDE_THRESHOLD = 5;
+function statePath(repoRoot) {
+    return join(repoRoot, ".mneme", "iris-state.json");
+}
+function emptyState() {
+    return { commandsRun: {}, preferTerse: false, lastSeen: {} };
+}
+/** Read state — returns a clean default if missing or corrupt. */
+export function readIrisState(repoRoot) {
+    const path = statePath(repoRoot);
+    if (!existsSync(path))
+        return emptyState();
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return emptyState();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return emptyState();
+    }
+    if (!parsed || typeof parsed !== "object")
+        return emptyState();
+    const s = parsed;
+    const commandsRun = {};
+    if (s.commandsRun && typeof s.commandsRun === "object") {
+        for (const [k, v] of Object.entries(s.commandsRun)) {
+            if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+                commandsRun[k] = v;
+        }
+    }
+    const lastSeen = {};
+    if (s.lastSeen && typeof s.lastSeen === "object") {
+        for (const [k, v] of Object.entries(s.lastSeen)) {
+            if (typeof v === "string")
+                lastSeen[k] = v;
+        }
+    }
+    return {
+        commandsRun,
+        preferTerse: typeof s.preferTerse === "boolean" ? s.preferTerse : false,
+        lastSeen,
+    };
+}
+function atomicWrite(path, contents) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            return;
+        }
+    }
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+    try {
+        writeFileSync(tmp, contents, "utf8");
+        renameSync(tmp, path);
+    }
+    catch {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Persist state atomically. */
+export function writeIrisState(repoRoot, state) {
+    atomicWrite(statePath(repoRoot), JSON.stringify(state, null, 2));
+}
+/** Increment the run-count for a command and persist.  Best-effort. */
+export function recordCommandRun(repoRoot, command) {
+    const state = readIrisState(repoRoot);
+    state.commandsRun[command] = (state.commandsRun[command] ?? 0) + 1;
+    state.lastSeen[command] = new Date().toISOString();
+    // Once any command has hit threshold, mark this user as a "power user".
+    for (const n of Object.values(state.commandsRun)) {
+        if (n >= VERBOSE_GUIDE_THRESHOLD) {
+            state.preferTerse = true;
+            break;
+        }
+    }
+    writeIrisState(repoRoot, state);
+}
+/**
+ * Should we show the verbose how-to-read guide for this command?
+ *
+ * True when the user has run the command fewer than 5 times.  We do NOT
+ * gate on `preferTerse` for the per-command decision — preferTerse only
+ * influences shared chrome (banners, footers).
+ */
+export function shouldShowVerboseGuide(state, command) {
+    const count = state.commandsRun[command] ?? 0;
+    return count < VERBOSE_GUIDE_THRESHOLD;
+}
+/** Reset state — used by tests and `mneme reset-iris`. */
+export function clearIrisState(repoRoot) {
+    const path = statePath(repoRoot);
+    if (!existsSync(path))
+        return;
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        /* ignore */
+    }
+}
+//# sourceMappingURL=adaptive.js.map

package/dist/iris/adaptive.js.map

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

package/dist/iris/adaptive.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adaptive.test.d.ts.map

package/dist/iris/adaptive.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive.test.d.ts","sourceRoot":"","sources":["../../src/iris/adaptive.test.ts"],"names":[],"mappings":""}

package/dist/iris/adaptive.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VERBOSE_GUIDE_THRESHOLD, clearIrisState, readIrisState, recordCommandRun, shouldShowVerboseGuide, writeIrisState, } from "./adaptive.js";
+let tmpDir;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mneme-iris-state-test-"));
+});
+afterEach(() => {
+    if (existsSync(tmpDir))
+        rmSync(tmpDir, { recursive: true, force: true });
+});
+describe("readIrisState", () => {
+    it("returns clean default when no state file exists", () => {
+        const s = readIrisState(tmpDir);
+        expect(s.commandsRun).toEqual({});
+        expect(s.lastSeen).toEqual({});
+        expect(s.preferTerse).toBe(false);
+    });
+    it("returns clean default when JSON is corrupt", () => {
+        mkdirSync(join(tmpDir, ".mneme"), { recursive: true });
+        writeFileSync(join(tmpDir, ".mneme", "iris-state.json"), "{not json", "utf8");
+        const s = readIrisState(tmpDir);
+        expect(s.commandsRun).toEqual({});
+    });
+    it("ignores malformed counts (negative / non-number)", () => {
+        mkdirSync(join(tmpDir, ".mneme"), { recursive: true });
+        writeFileSync(join(tmpDir, ".mneme", "iris-state.json"), JSON.stringify({
+            commandsRun: { good: 3, bad: "string", negative: -1 },
+            lastSeen: {},
+            preferTerse: false,
+        }), "utf8");
+        const s = readIrisState(tmpDir);
+        expect(s.commandsRun).toEqual({ good: 3 });
+    });
+});
+describe("recordCommandRun", () => {
+    it("increments count + writes timestamp", () => {
+        recordCommandRun(tmpDir, "ask");
+        let s = readIrisState(tmpDir);
+        expect(s.commandsRun.ask).toBe(1);
+        expect(s.lastSeen.ask).toBeTruthy();
+        recordCommandRun(tmpDir, "ask");
+        s = readIrisState(tmpDir);
+        expect(s.commandsRun.ask).toBe(2);
+    });
+    it("maintains separate counts per command", () => {
+        recordCommandRun(tmpDir, "ask");
+        recordCommandRun(tmpDir, "forensics");
+        recordCommandRun(tmpDir, "forensics");
+        const s = readIrisState(tmpDir);
+        expect(s.commandsRun.ask).toBe(1);
+        expect(s.commandsRun.forensics).toBe(2);
+    });
+    it("flips preferTerse to true once threshold is crossed", () => {
+        for (let i = 0; i < VERBOSE_GUIDE_THRESHOLD; i++) {
+            recordCommandRun(tmpDir, "ask");
+        }
+        const s = readIrisState(tmpDir);
+        expect(s.preferTerse).toBe(true);
+    });
+    it("preferTerse stays false until threshold", () => {
+        for (let i = 0; i < VERBOSE_GUIDE_THRESHOLD - 1; i++) {
+            recordCommandRun(tmpDir, "ask");
+        }
+        const s = readIrisState(tmpDir);
+        expect(s.preferTerse).toBe(false);
+    });
+});
+describe("shouldShowVerboseGuide", () => {
+    it("true for first-time users", () => {
+        const s = readIrisState(tmpDir);
+        expect(shouldShowVerboseGuide(s, "ask")).toBe(true);
+    });
+    it("true while count < threshold", () => {
+        const s = { commandsRun: { ask: 4 }, preferTerse: false, lastSeen: {} };
+        expect(shouldShowVerboseGuide(s, "ask")).toBe(true);
+    });
+    it("false when count ≥ threshold", () => {
+        const s = { commandsRun: { ask: 5 }, preferTerse: true, lastSeen: {} };
+        expect(shouldShowVerboseGuide(s, "ask")).toBe(false);
+    });
+    it("tracks per-command (other commands keep verbose)", () => {
+        const s = { commandsRun: { ask: 10 }, preferTerse: true, lastSeen: {} };
+        expect(shouldShowVerboseGuide(s, "ask")).toBe(false);
+        expect(shouldShowVerboseGuide(s, "forensics")).toBe(true);
+    });
+});
+describe("round-trip read/write", () => {
+    it("survives write+read roundtrip", () => {
+        const state = {
+            commandsRun: { a: 3, b: 7 },
+            lastSeen: { a: "2024-01-01T00:00:00Z", b: "2024-01-02T00:00:00Z" },
+            preferTerse: true,
+        };
+        writeIrisState(tmpDir, state);
+        const back = readIrisState(tmpDir);
+        expect(back).toEqual(state);
+    });
+});
+describe("clearIrisState", () => {
+    it("removes the state file", () => {
+        recordCommandRun(tmpDir, "ask");
+        expect(existsSync(join(tmpDir, ".mneme", "iris-state.json"))).toBe(true);
+        clearIrisState(tmpDir);
+        expect(existsSync(join(tmpDir, ".mneme", "iris-state.json"))).toBe(false);
+    });
+    it("is a no-op when no state file exists", () => {
+        expect(() => clearIrisState(tmpDir)).not.toThrow();
+    });
+});
+//# sourceMappingURL=adaptive.test.js.map

package/dist/iris/adaptive.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive.test.js","sourceRoot":"","sources":["../../src/iris/adaptive.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,IAAI,MAAc,CAAC;AAEnB,UAAU,CAAC,GAAG,EAAE;IACd,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,wBAAwB,CAAC,CAAC,CAAC;AACjE,CAAC,CAAC,CAAC;AACH,SAAS,CAAC,GAAG,EAAE;IACb,IAAI,UAAU,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3E,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,iBAAiB,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QAC9E,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,aAAa,CACX,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,iBAAiB,CAAC,EACzC,IAAI,CAAC,SAAS,CAAC;YACb,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE;YACrD,QAAQ,EAAE,EAAE;YACZ,WAAW,EAAE,KAAK;SACnB,CAAC,EACF,MAAM,CACP,CAAC;QACF,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAC9B,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC;QAEpC,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAC1B,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,gBAAgB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACtC,gBAAgB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACtC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,uBAAuB,EAAE,CAAC,EAAE,EAAE,CAAC;YACjD,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,uBAAuB,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACrD,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;IACtC,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAChC,MAAM,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACxE,MAAM,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACvE,MAAM,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACxE,MAAM,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrD,MAAM,CAAC,sBAAsB,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,KAAK,GAAG;YACZ,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;YAC3B,QAAQ,EAAE,EAAE,CAAC,EAAE,sBAAsB,EAAE,CAAC,EAAE,sBAAsB,EAAE;YAClE,WAAW,EAAE,IAAI;SAClB,CAAC;QACF,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,wBAAwB,EAAE,GAAG,EAAE;QAChC,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzE,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/iris/contract.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Iris — 30-second contract validator.
+ *
+ * Every Mneme command output should be scannable in ~30 seconds.  This file
+ * encodes that as a checkable contract — both for tests ("does my command
+ * obey the contract?") and for users (`mneme verify-output`).
+ *
+ * Pure function.  No I/O.
+ */
+/** Strip ANSI escapes for visible-width math.  Local copy to avoid coupling. */
+export declare function stripAnsi(s: string): string;
+export interface ContractResult {
+    ok: boolean;
+    violations: string[];
+}
+/**
+ * Validate that a rendered output meets the 30-second readability contract.
+ *
+ * Checks:
+ *   1. First 5 lines must contain a headline-like sentence (bold + icon).
+ *   2. Output must contain at least one actionable hint
+ *      (e.g. `mneme `, `Try `, `Run `).
+ *   3. No line wider than 200 visible chars (post-ANSI strip).
+ *   4. No section nested deeper than 3 levels (6 leading spaces).
+ *   5. Either has `→ Try next` or has fewer than 30 lines (tight).
+ */
+export declare function checkContract(output: string): ContractResult;
+//# sourceMappingURL=contract.d.ts.map

package/dist/iris/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/iris/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAsCD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAsC5D"}

package/dist/iris/contract.js

@@ -0,0 +1,98 @@
+/**
+ * Iris — 30-second contract validator.
+ *
+ * Every Mneme command output should be scannable in ~30 seconds.  This file
+ * encodes that as a checkable contract — both for tests ("does my command
+ * obey the contract?") and for users (`mneme verify-output`).
+ *
+ * Pure function.  No I/O.
+ */
+const ANSI_RE = /\x1b\[[0-9;]*m|\x1b\]8;;[^\x1b]*\x1b\\/g;
+/** Strip ANSI escapes for visible-width math.  Local copy to avoid coupling. */
+export function stripAnsi(s) {
+    return s.replace(ANSI_RE, "");
+}
+/** Heuristic: a "headline-like" line has a leading icon glyph + non-trivial
+ *  text.  When ANSI is present we additionally accept a bold escape, but we
+ *  do NOT require it — pipes and CI strip colour, and the contract has to
+ *  pass either way. */
+function looksLikeHeadline(line) {
+    const visible = stripAnsi(line);
+    const head = visible.trimStart();
+    if (head.length < 4)
+        return false;
+    // Non-ASCII glyph (icon) within the first 12 visible chars.
+    const hasIcon = /[^\x00-\x7F]/.test(head.slice(0, 12));
+    return hasIcon;
+}
+/** Detect whether the output offers an actionable hint. */
+function hasActionableHint(stripped) {
+    // "mneme " (a follow-up command), "Try ", "Run ", "→ Try", or fenced cmd.
+    if (/\bmneme\s+\w+/.test(stripped))
+        return true;
+    if (/\bTry\b/.test(stripped))
+        return true;
+    if (/\bRun\b/.test(stripped))
+        return true;
+    if (/→\s*Try/.test(stripped))
+        return true;
+    return false;
+}
+/** Walk lines and find max indent depth (every 2 spaces = 1 level). */
+function maxIndentDepth(lines) {
+    let max = 0;
+    for (const raw of lines) {
+        const visible = stripAnsi(raw);
+        const m = visible.match(/^(\s*)/);
+        const spaces = m ? m[1].length : 0;
+        const depth = Math.floor(spaces / 2);
+        if (depth > max)
+            max = depth;
+    }
+    return max;
+}
+/**
+ * Validate that a rendered output meets the 30-second readability contract.
+ *
+ * Checks:
+ *   1. First 5 lines must contain a headline-like sentence (bold + icon).
+ *   2. Output must contain at least one actionable hint
+ *      (e.g. `mneme `, `Try `, `Run `).
+ *   3. No line wider than 200 visible chars (post-ANSI strip).
+ *   4. No section nested deeper than 3 levels (6 leading spaces).
+ *   5. Either has `→ Try next` or has fewer than 30 lines (tight).
+ */
+export function checkContract(output) {
+    const violations = [];
+    const rawLines = output.split("\n");
+    const stripped = stripAnsi(output);
+    // 1. Headline in first 5 lines.
+    const top5 = rawLines.slice(0, 5);
+    if (!top5.some(looksLikeHeadline)) {
+        violations.push("no headline in first 5 lines (need bold + leading icon)");
+    }
+    // 2. At least one actionable hint.
+    if (!hasActionableHint(stripped)) {
+        violations.push("no actionable hint found ('mneme', 'Try', 'Run')");
+    }
+    // 3. No line wider than 200 visible chars.
+    for (let i = 0; i < rawLines.length; i++) {
+        const visibleLen = stripAnsi(rawLines[i]).length;
+        if (visibleLen > 200) {
+            violations.push(`line ${i + 1} too wide: ${visibleLen} visible chars (max 200)`);
+            break; // one report is enough — keep the message tight
+        }
+    }
+    // 4. Indent depth ≤ 3 levels (i.e. 6 leading spaces).
+    const depth = maxIndentDepth(rawLines);
+    if (depth > 3) {
+        violations.push(`section nested too deep: depth=${depth} (max 3)`);
+    }
+    // 5. Try-next OR fewer than 30 lines.
+    const hasTryNext = /→\s*Try next/.test(stripped) || /\bTry next\b/.test(stripped);
+    if (!hasTryNext && rawLines.length >= 30) {
+        violations.push(`output is ${rawLines.length} lines without '→ Try next' (cap at 30)`);
+    }
+    return { ok: violations.length === 0, violations };
+}
+//# sourceMappingURL=contract.js.map

package/dist/iris/contract.js.map

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

package/dist/iris/contract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.test.d.ts.map

package/dist/iris/contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.test.d.ts","sourceRoot":"","sources":["../../src/iris/contract.test.ts"],"names":[],"mappings":""}

package/dist/iris/contract.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { checkContract } from "./contract.js";
+import { renderPyramid, singleSection } from "./pyramid.js";
+beforeEach(() => {
+    // Contract checks rely on ANSI bold being present, so we DO want colour on.
+    delete process.env.NO_COLOR;
+});
+afterEach(() => {
+    process.env.NO_COLOR = "1";
+});
+describe("checkContract — passes on a journalist-shaped output", () => {
+    it("a renderPyramid output with headline + actionable hint passes", () => {
+        const out = renderPyramid({
+            headline: "📰 3 critical anomalies",
+            sections: [
+                singleSection("lede", "✦ Findings", ["Run mneme forensics --verbose for detail"]),
+            ],
+            whyShown: "Try forensics next",
+            widthOverride: 80,
+        });
+        const r = checkContract(out);
+        if (!r.ok)
+            console.error(r.violations, JSON.stringify(out));
+        expect(r.ok).toBe(true);
+        expect(r.violations).toEqual([]);
+    });
+});
+describe("checkContract — failure modes", () => {
+    it("flags missing headline (plain text output)", () => {
+        const r = checkContract("just a wall of plain text\nwith nothing fancy");
+        expect(r.ok).toBe(false);
+        expect(r.violations.some((v) => v.includes("headline"))).toBe(true);
+    });
+    it("flags missing actionable hint", () => {
+        // Build output WITH a headline but NO mneme/Try/Run hint.
+        const out = "\x1b[1m\x1b[36m  📰 Headline only\x1b[0m\nfiller content\nmore filler\n";
+        const r = checkContract(out);
+        expect(r.violations.some((v) => v.includes("actionable hint"))).toBe(true);
+    });
+    it("flags lines wider than 200 chars", () => {
+        const huge = "\x1b[1m\x1b[36m  📰 head\x1b[0m\n" + "x".repeat(220) + "\n run mneme forensics";
+        const r = checkContract(huge);
+        expect(r.violations.some((v) => v.includes("too wide"))).toBe(true);
+    });
+    it("flags excessively deep indentation", () => {
+        const deeplyNested = "\x1b[1m\x1b[36m  📰 ok\x1b[0m\n" +
+            "          deep content here\n" + // 10 spaces = depth 5
+            "Try mneme ask";
+        const r = checkContract(deeplyNested);
+        expect(r.violations.some((v) => v.includes("nested too deep"))).toBe(true);
+    });
+    it("flags long output without 'Try next' marker", () => {
+        const lines = ["\x1b[1m\x1b[36m  📰 ok\x1b[0m"];
+        for (let i = 0; i < 35; i++)
+            lines.push(`line ${i}`);
+        lines.push("Run mneme ask");
+        const r = checkContract(lines.join("\n"));
+        expect(r.violations.some((v) => v.includes("Try next"))).toBe(true);
+    });
+    it("does not flag long output WITH 'Try next'", () => {
+        const lines = ["\x1b[1m\x1b[36m  📰 ok\x1b[0m"];
+        for (let i = 0; i < 35; i++)
+            lines.push(`line ${i}`);
+        lines.push("→ Try next: mneme ask");
+        const r = checkContract(lines.join("\n"));
+        expect(r.violations.some((v) => v.includes("Try next"))).toBe(false);
+    });
+});
+describe("checkContract — return shape", () => {
+    it("returns ok=true with empty violations on a perfect output", () => {
+        const out = renderPyramid({
+            headline: "📰 ok",
+            sections: [singleSection("body", undefined, ["Run mneme ask now"])],
+            widthOverride: 80,
+        });
+        const r = checkContract(out);
+        expect(r).toHaveProperty("ok");
+        expect(r).toHaveProperty("violations");
+        expect(Array.isArray(r.violations)).toBe(true);
+    });
+});
+//# sourceMappingURL=contract.test.js.map

package/dist/iris/contract.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.test.js","sourceRoot":"","sources":["../../src/iris/contract.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE5D,UAAU,CAAC,GAAG,EAAE;IACd,4EAA4E;IAC5E,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;AAC9B,CAAC,CAAC,CAAC;AACH,SAAS,CAAC,GAAG,EAAE;IACb,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC;AAC7B,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,sDAAsD,EAAE,GAAG,EAAE;IACpE,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,GAAG,GAAG,aAAa,CAAC;YACxB,QAAQ,EAAE,yBAAyB;YACnC,QAAQ,EAAE;gBACR,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,0CAA0C,CAAC,CAAC;aAClF;YACD,QAAQ,EAAE,oBAAoB;YAC9B,aAAa,EAAE,EAAE;SAClB,CAAC,CAAC;QACH,MAAM,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5D,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,+BAA+B,EAAE,GAAG,EAAE;IAC7C,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,CAAC,GAAG,aAAa,CAAC,+CAA+C,CAAC,CAAC;QACzE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,0DAA0D;QAC1D,MAAM,GAAG,GAAG,yEAAyE,CAAC;QACtF,MAAM,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,IAAI,GAAG,mCAAmC,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,wBAAwB,CAAC;QAC9F,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,YAAY,GAChB,iCAAiC;YACjC,+BAA+B,GAAG,sBAAsB;YACxD,eAAe,CAAC;QAClB,MAAM,CAAC,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;QACtC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,KAAK,GAAa,CAAC,+BAA+B,CAAC,CAAC;QAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC5B,MAAM,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,MAAM,KAAK,GAAa,CAAC,+BAA+B,CAAC,CAAC;QAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACpC,MAAM,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,GAAG,GAAG,aAAa,CAAC;YACxB,QAAQ,EAAE,OAAO;YACjB,QAAQ,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC;YACnE,aAAa,EAAE,EAAE;SAClB,CAAC,CAAC;QACH,MAAM,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/iris/entity.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Iris — visual entity continuity.
+ *
+ * The pillar:  "abc1234" must look identical in every command — same colour,
+ * same spacing, same prefix glyph — so the user's eye learns one visual
+ * language across `mneme ask`, `mneme why`, `mneme forensics`, etc.
+ *
+ * All renderers below are deterministic: same input → byte-identical output
+ * (modulo NO_COLOR for CI). No randomization, no per-command flair.
+ *
+ * These helpers wrap kleur + osc8.  They DO NOT replace `cli/src/ui.ts` —
+ * they fix a small set of *visual decisions* (colour, glyph, format) that
+ * commands previously made in eight different ways.
+ */
+export interface RenderCommitOpts {
+    /** Pack onto one line if true (no body indent). Default: false. */
+    compact?: boolean;
+    /** Highlight as the "primary" commit (e.g. the answer's top citation). */
+    emphasized?: boolean;
+    /** Click-through URL (GitHub/GitLab/Bitbucket). */
+    url?: string;
+}
+export interface RenderableCommit {
+    hash: string;
+    shortHash?: string;
+    subject: string;
+    authorName?: string;
+    authorDate?: string;
+}
+/**
+ * Render a commit citation IDENTICALLY across every command.
+ *
+ *   ●  abc1234   [2024-08-12 · alice]   feat: add payment retry
+ *
+ * Compact form:
+ *   abc1234  feat: add payment retry  [alice · 2024-08-12]
+ */
+export declare function renderCommit(c: RenderableCommit, opts?: RenderCommitOpts): string;
+export interface RenderAuthorOpts {
+    /** Mark this author as "you" (the current git user). */
+    isYou?: boolean;
+}
+/**
+ * Render an author identity uniformly.
+ *
+ *   alice <alice@bank.com>            (default)
+ *   you (Alice <alice@bank.com>)      (isYou)
+ */
+export declare function renderAuthor(name: string, email?: string, opts?: RenderAuthorOpts): string;
+export interface RenderFileOpts {
+    /** Optional `:start-end` line range. */
+    lineRange?: string;
+    /** How many times this file was touched (badge). */
+    touched?: number;
+}
+/**
+ * Render a file path uniformly.
+ *
+ *   src/payment/service.ts
+ *   src/payment/service.ts:12-44      (with lineRange)
+ *   src/payment/service.ts (×7)       (with touched)
+ */
+export declare function renderFile(path: string, opts?: RenderFileOpts): string;
+export interface RenderHashRefOpts {
+    /** Click-through URL. */
+    url?: string;
+}
+/**
+ * Render a commit hash reference INLINE (e.g. inside a sentence).
+ *
+ *   …rolled back in `abc1234`.
+ *
+ * Always bold + monospace-styled.  Never adds a leading dot or trailing meta.
+ */
+export declare function renderHashRef(shortHash: string, opts?: RenderHashRefOpts): string;
+//# sourceMappingURL=entity.d.ts.map

package/dist/iris/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/iris/entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA+BH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAkBrF;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAQ9F;AAED,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,MAAM,CAQ1E;AAED,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAIrF"}