@mnemom/mnemom 0.17.4-next.3 → 0.17.4-next.5

package/dist/lib/first-run/governed.js

@@ -0,0 +1,253 @@
+/**
+ * Did a Claude Code transcript already run through Mnemom? A session is GOVERNED — and
+ * left out of the first-run look — if ANY signal fires. When in doubt, exclude.
+ *
+ *   registry_cc_id     the transcript's session id is a `cc_session_id` in the launch
+ *                      ledger (~/.mnemom/sessions.jsonl, lib/agent-ledger.ts)
+ *   registry_conv_id   … or a ledger `conversation_id`
+ *   registry_window    its first event is within [launch-60s, launch+10min] of a ledger
+ *                      launch that recorded no cc_session_id (--server, older rows)
+ *   rc_proxy_window    the same window match against a Remote Control proxy log
+ *   text_marker        the bytes carry a gateway marker ('[mnemom', 'x-mnemom', 'covers=',
+ *                      …). Also fires on sessions that merely DISCUSS Mnemom: over-excludes,
+ *                      the safe direction
+ *   settings_env       a settings file (global or the session cwd's) or the transcript
+ *                      text points ANTHROPIC_BASE_URL / HTTPS_PROXY at a mnemom host or a
+ *                      localhost proxy
+ *   agent_sdk_host     entrypoint sdk-py / sdk-ts: an Agent-SDK host can route through
+ *                      the gateway with env no transcript records
+ *   (a session is governed if its top transcript OR any subagent transcript fires)
+ *
+ * Read-only on ~/.claude and ~/.mnemom. No network.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { forEachLine, isoSeconds, parseJson } from "./lines.js";
+export const AGENT_SDK_ENTRYPOINTS = new Set(["sdk-py", "sdk-ts"]);
+/** Lowercase byte markers. Candidate lines are found by the case-variant probes below. */
+export const TEXT_MARKERS = [
+    "[mnemom",
+    "x-mnemom",
+    "mnemom goal contract",
+    "mnemom context digest",
+    "mnemom inferred goal",
+    "mnemom guardrail",
+    "covers=",
+];
+const PROBES = ["nemom", "NEMOM", "covers=", "COVERS="].map((s) => Buffer.from(s));
+const ENV_PROBES = ["ANTHROPIC_BASE_URL", "HTTPS_PROXY", "anthropic_base_url", "https_proxy"].map((s) => Buffer.from(s));
+// The variable, its separator, then a host. Bounded, no nested quantifiers.
+const ENV_RE = /(?:ANTHROPIC_BASE_URL|HTTPS_PROXY)["'\s:=]{1,8}(?:https?:\/\/)?([a-z0-9.-]{1,253})/gi;
+const WINDOW_BEFORE_S = 60;
+const WINDOW_AFTER_S = 600;
+/** The head scan reads this much of a file for its first records. */
+const HEAD_BYTES = 256 * 1024;
+export function lineHasMarker(line) {
+    if (!PROBES.some((p) => line.indexOf(p) !== -1))
+        return false;
+    const low = line.toString("utf8").toLowerCase();
+    return TEXT_MARKERS.some((m) => low.includes(m));
+}
+function governedHost(host) {
+    const h = host.toLowerCase();
+    return h.includes("mnemom") || h === "127.0.0.1" || h === "localhost";
+}
+export function lineHasEnv(line) {
+    if (!ENV_PROBES.some((p) => line.indexOf(p) !== -1))
+        return false;
+    const s = line.toString("utf8");
+    for (const m of s.matchAll(ENV_RE)) {
+        if (governedHost(m[1]))
+            return true;
+    }
+    return false;
+}
+function settingsEnvHits(path) {
+    let d;
+    try {
+        d = parseJson(readFileSync(path, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    const env = d?.env ?? {};
+    for (const k of ["ANTHROPIC_BASE_URL", "HTTPS_PROXY", "https_proxy"]) {
+        const v = String(env[k] ?? "").toLowerCase();
+        if (v && (v.includes("mnemom") || v.includes("127.0.0.1") || v.includes("localhost"))) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Session id of a transcript path: its own uuid, or the parent's for a subagent file. */
+export function sessionIdFor(path) {
+    const parts = path.split("/");
+    const i = parts.lastIndexOf("subagents");
+    if (i > 0)
+        return parts[i - 1];
+    const base = parts[parts.length - 1];
+    return base.endsWith(".jsonl") ? base.slice(0, -6) : base;
+}
+export class Governance {
+    ccIds = new Set();
+    convIds = new Set();
+    windows = [];
+    globalSettingsEnv;
+    registryRows = 0;
+    cwdCache = new Map();
+    constructor(inp = {}) {
+        const home = inp.home ?? homedir();
+        const mnemomDir = inp.mnemomDir ?? join(home, ".mnemom");
+        const tmp = inp.tmp ?? tmpdir();
+        let ledger;
+        try {
+            ledger = readFileSync(join(mnemomDir, "sessions.jsonl"), "utf8");
+        }
+        catch {
+            ledger = "";
+        }
+        for (const line of ledger.split("\n")) {
+            if (!line.trim())
+                continue;
+            const r = parseJson(line);
+            if (!r)
+                continue;
+            this.registryRows++;
+            const t = isoSeconds(r.started_at);
+            if (typeof r.cc_session_id === "string" && r.cc_session_id)
+                this.ccIds.add(r.cc_session_id);
+            if (typeof r.conversation_id === "string" && r.conversation_id) {
+                this.convIds.add(r.conversation_id);
+            }
+            if (!r.cc_session_id && t !== null)
+                this.windows.push(["registry_window", t]);
+        }
+        // Remote Control proxy logs: $TMPDIR/mnemom-code-rc.*/proxy.log, ~/.mnemom/*rc-proxy*.log
+        const logs = [];
+        for (const d of safeList(tmp)) {
+            if (d.startsWith("mnemom-code-rc."))
+                logs.push(join(tmp, d, "proxy.log"));
+        }
+        for (const f of safeList(mnemomDir)) {
+            if (f.includes("rc-proxy") && f.endsWith(".log"))
+                logs.push(join(mnemomDir, f));
+        }
+        for (const lp of logs) {
+            let text;
+            try {
+                text = readFileSync(lp, "utf8");
+            }
+            catch {
+                continue;
+            }
+            for (const line of text.split("\n")) {
+                if (!line.includes(" listening "))
+                    continue;
+                const t = isoSeconds(line.split(" ", 1)[0]);
+                if (t !== null)
+                    this.windows.push(["rc_proxy_window", t]);
+            }
+        }
+        this.globalSettingsEnv = ["settings.json", "settings.local.json"].some((f) => settingsEnvHits(join(home, ".claude", f)));
+    }
+    cwdEnv(cwd) {
+        if (!cwd)
+            return false;
+        let v = this.cwdCache.get(cwd);
+        if (v === undefined) {
+            v = ["settings.json", "settings.local.json"].some((f) => settingsEnvHits(join(cwd, ".claude", f)));
+            this.cwdCache.set(cwd, v);
+        }
+        return v;
+    }
+    /** The first records of a file: first timestamp, cwd, session id, entrypoint. */
+    head(path, maxBytes = HEAD_BYTES) {
+        const h = { firstTs: null, cwd: null, sessionId: null, entrypoint: null };
+        forEachLine(path, (line) => {
+            fillHead(h, line);
+            return !(h.firstTs !== null && h.cwd && h.sessionId && h.entrypoint);
+        }, maxBytes);
+        return h;
+    }
+    /** Signals that follow from a file's head records alone. */
+    headSignals(sid, h, sig) {
+        if (h.sessionId && h.sessionId !== sid) {
+            if (this.ccIds.has(h.sessionId) || this.convIds.has(h.sessionId))
+                sig.add("registry_cc_id");
+        }
+        if (h.entrypoint && AGENT_SDK_ENTRYPOINTS.has(h.entrypoint))
+            sig.add("agent_sdk_host");
+        if (this.cwdEnv(h.cwd))
+            sig.add("settings_env");
+        if (h.firstTs !== null) {
+            for (const [name, t] of this.windows) {
+                if (t - WINDOW_BEFORE_S <= h.firstTs && h.firstTs <= t + WINDOW_AFTER_S) {
+                    sig.add(name);
+                    break;
+                }
+            }
+        }
+    }
+    /**
+     * Classify one transcript. The cheap signals (ledger, head records, settings, windows)
+     * are checked first; the full byte scan for markers runs only when none fired (the
+     * session is excluded either way, so the scan would change nothing). The full scan
+     * also completes head fields that a large first record pushed past the head read.
+     */
+    classify(path) {
+        const sid = sessionIdFor(path);
+        const sig = new Set();
+        if (this.ccIds.has(sid))
+            sig.add("registry_cc_id");
+        if (this.convIds.has(sid))
+            sig.add("registry_conv_id");
+        if (this.globalSettingsEnv)
+            sig.add("settings_env");
+        const h = this.head(path);
+        this.headSignals(sid, h, sig);
+        if (sig.size === 0) {
+            const complete = () => h.firstTs !== null && h.cwd !== null && h.sessionId !== null && h.entrypoint !== null;
+            let marker = false;
+            let env = false;
+            const ok = forEachLine(path, (line) => {
+                // The scan stops at the first hit, so neither flag is ever already set here.
+                marker = lineHasMarker(line);
+                env = lineHasEnv(line);
+                if (!complete())
+                    fillHead(h, line);
+                // Either hit excludes the session; the rest of the file cannot change that.
+                return !(marker || env);
+            });
+            if (!ok)
+                sig.add("unreadable");
+            if (marker)
+                sig.add("text_marker");
+            if (env)
+                sig.add("settings_env");
+            this.headSignals(sid, h, sig);
+        }
+        return { ...h, signals: [...sig].sort() };
+    }
+}
+function fillHead(h, line) {
+    const d = parseJson(line);
+    if (!d)
+        return;
+    if (h.firstTs === null && d.timestamp)
+        h.firstTs = isoSeconds(d.timestamp);
+    if (h.cwd === null && typeof d.cwd === "string")
+        h.cwd = d.cwd;
+    if (h.sessionId === null && typeof d.sessionId === "string")
+        h.sessionId = d.sessionId;
+    if (h.entrypoint === null && typeof d.entrypoint === "string")
+        h.entrypoint = d.entrypoint;
+}
+function safeList(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/first-run/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The `mnemom agent` first-run look: on the first interactive launch, offer (opt-in) to
+ * backtest the user's last 30 days of Claude Code sessions on this machine and show what
+ * Mnemom would have saved. `mnemom agent --first-run` shows it again at any time.
+ *
+ * Privacy: READ-ONLY on ~/.claude and every transcript; no network call anywhere in this
+ * module tree; only token counts, model ids, timestamps and Claude Code's own limit
+ * records are read. Writes only the offer state file and a local audit (both 0600,
+ * under ~/.mnemom).
+ *
+ * State file (~/.mnemom/first-run.json): { offers, last_offer, last_answer, accepted_at?,
+ * never? }. The offer is made while neither `accepted_at` nor `never` is set:
+ * Enter / y shows the screen and records acceptance; n skips until the next launch;
+ * never stops asking. A non-interactive launch is never asked and writes nothing.
+ */
+import { type Audit, type Variation } from "./screen.js";
+export declare const STATE_FILE = "first-run.json";
+export declare const AUDIT_FILE = "first-run-audit.json";
+export declare const OFFER_TEXT: string[];
+export declare const OFFER_QUESTION = "Take a look? [Y/n/never]";
+export interface FirstRunState {
+    offers?: number;
+    last_offer?: string;
+    last_answer?: OfferAnswer;
+    accepted_at?: string;
+    never?: boolean;
+}
+export type OfferAnswer = "yes" | "no" | "never";
+export declare function statePath(mnemomDir: string): string;
+export declare function readState(path: string): FirstRunState;
+export declare function writeState(path: string, st: FirstRunState): void;
+/** Should this launch offer the first-run look? Only interactive, only until answered. */
+export declare function shouldOffer(st: FirstRunState, interactive: boolean): boolean;
+export declare function parseAnswer(raw: string | null): OfferAnswer;
+export declare function recordAnswer(st: FirstRunState, ans: OfferAnswer, now: Date): FirstRunState;
+export interface ScanOptions {
+    home?: string;
+    mnemomDir?: string;
+    tmp?: string;
+    roots?: string[];
+    now?: number;
+    retentionDays?: number;
+    progress?: (msg: string) => void;
+}
+export interface FirstRunResult {
+    lines: string[];
+    audit: Audit;
+    variation?: Variation;
+    counts: Record<string, number>;
+    seconds: number;
+}
+/** Scan, classify, price and build the screen. Read-only on every transcript. */
+export declare function computeFirstRun(opts?: ScanOptions): FirstRunResult;
+/** The screen's hard budget: a regression in buildScreen's line dropping must fail loudly. */
+export declare function assertScreenBudget(lines: readonly string[]): void;
+/** A transcript's mtime (ms), 0 when it vanished since discovery (it then sorts first). */
+export declare function mtimeOf(p: string): number;
+export interface FirstRunDeps {
+    mnemomDir: string;
+    interactive: boolean;
+    /** Ask a question, return the answer, or null on EOF. */
+    ask(question: string): Promise<string | null>;
+    /** Screen output (stdout). */
+    print(line: string): void;
+    /** Progress / notes (stderr). */
+    note(line: string): void;
+    now(): Date;
+    compute(): FirstRunResult;
+}
+/** Show the screen and write the local audit. Never throws: a failed look never blocks a launch. */
+export declare function showFirstRun(deps: FirstRunDeps): boolean;
+/**
+ * The first-launch hook: offer once (interactive only), record the answer, show on yes.
+ * Returns what happened, for tests and the caller's logging.
+ */
+export declare function maybeOfferFirstRun(deps: FirstRunDeps): Promise<"shown" | "declined" | "never" | "skipped" | "failed">;

package/dist/lib/first-run/index.js

@@ -0,0 +1,243 @@
+/**
+ * The `mnemom agent` first-run look: on the first interactive launch, offer (opt-in) to
+ * backtest the user's last 30 days of Claude Code sessions on this machine and show what
+ * Mnemom would have saved. `mnemom agent --first-run` shows it again at any time.
+ *
+ * Privacy: READ-ONLY on ~/.claude and every transcript; no network call anywhere in this
+ * module tree; only token counts, model ids, timestamps and Claude Code's own limit
+ * records are read. Writes only the offer state file and a local audit (both 0600,
+ * under ~/.mnemom).
+ *
+ * State file (~/.mnemom/first-run.json): { offers, last_offer, last_answer, accepted_at?,
+ * never? }. The offer is made while neither `accepted_at` nor `never` is set:
+ * Enter / y shows the screen and records acceptance; n skips until the next launch;
+ * never stops asking. A non-interactive launch is never asked and writes nothing.
+ */
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { estimate, loadTranscript, origContext, ruleRate } from "./backtest.js";
+import { analyzeSeat } from "./seat.js";
+import { ORG_SEAT_TYPES, authShape, billingClass, buildScope, configDirOf, prettyProject, } from "./scope.js";
+import { DAYS, MAX_LINES, WIDTH, buildScreen, labelFor, } from "./screen.js";
+export const STATE_FILE = "first-run.json";
+export const AUDIT_FILE = "first-run-audit.json";
+export const OFFER_TEXT = [
+    "Mnemom can look at your recent Claude Code sessions and show you what it would have saved.",
+    "It runs on this machine. Nothing is uploaded.",
+];
+export const OFFER_QUESTION = "Take a look? [Y/n/never]";
+export function statePath(mnemomDir) {
+    return join(mnemomDir, STATE_FILE);
+}
+export function readState(path) {
+    try {
+        const v = JSON.parse(readFileSync(path, "utf8"));
+        return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writePrivate(path, body) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, body, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+export function writeState(path, st) {
+    writePrivate(path, `${JSON.stringify(st, null, 1)}\n`);
+}
+/** Should this launch offer the first-run look? Only interactive, only until answered. */
+export function shouldOffer(st, interactive) {
+    return interactive && !st.never && !st.accepted_at;
+}
+export function parseAnswer(raw) {
+    if (raw === null)
+        return "no"; // EOF: skip this time
+    const a = raw.trim().toLowerCase();
+    if (a === "" || a === "y" || a === "yes")
+        return "yes";
+    if (a === "never" || a === "nev")
+        return "never";
+    return "no"; // n, no, or anything unclear
+}
+export function recordAnswer(st, ans, now) {
+    const iso = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+    const out = {
+        ...st,
+        offers: (st.offers ?? 0) + 1,
+        last_offer: iso,
+        last_answer: ans,
+    };
+    if (ans === "never")
+        out.never = true;
+    if (ans === "yes")
+        out.accepted_at = iso;
+    return out;
+}
+/** Scan, classify, price and build the screen. Read-only on every transcript. */
+export function computeFirstRun(opts = {}) {
+    const t0 = Date.now();
+    const home = opts.home ?? homedir();
+    const now = opts.now ?? Date.now() / 1000;
+    const cut = now - DAYS * 86400;
+    const scope = buildScope({
+        home,
+        roots: opts.roots,
+        mnemomDir: opts.mnemomDir,
+        tmp: opts.tmp,
+        since: cut,
+        retentionDays: opts.retentionDays,
+        now,
+        progress: opts.progress,
+    });
+    const counts = {
+        sessions_total: scope.sessions.size,
+        sessions_recent: scope.inWindow,
+        excluded_governed_or_doubt: scope.excluded.size,
+        kept: scope.kept.size,
+    };
+    for (const sigs of scope.excluded.values()) {
+        for (const s of sigs)
+            counts[`signal_${s}`] = (counts[`signal_${s}`] ?? 0) + 1;
+    }
+    // Oldest first, so a message copied into a later (resumed / forked) transcript is billed
+    // once, to its origin.
+    const ordered = [...scope.kept.values()]
+        .map((s) => ({ s, m: mtimeOf(s.top) }))
+        .sort((a, b) => a.m - b.m)
+        .map((x) => x.s);
+    const seen = new Set();
+    const shapes = new Map();
+    const sessions = [];
+    const subSessions = [];
+    // A Team / Enterprise subscriber: a subscription-billed session, or a Team / Enterprise
+    // login in any kept session's config dir. Only these plans can run through Mnemom on
+    // their subscription (lib/subscription-login.ts), so only they get the usage sentence.
+    let orgLogin = false;
+    const seatInputs = new Map();
+    ordered.forEach((s, i) => {
+        if (i % 25 === 0)
+            opts.progress?.(`pricing sessions ${i + 1}/${ordered.length}`);
+        const paths = [s.top, ...[...s.subs].sort()];
+        const rows = paths.flatMap((p) => loadTranscript(p, seen));
+        if (!rows.length) {
+            counts.no_usage = (counts.no_usage ?? 0) + 1;
+            return;
+        }
+        const cfg = configDirOf(s.root);
+        let shape = shapes.get(cfg);
+        if (!shape) {
+            shape = authShape(cfg, home);
+            shapes.set(cfg, shape);
+        }
+        const subLogin = shape.oauth &&
+            (shape.billingType ?? "").includes("subscription") &&
+            ORG_SEAT_TYPES.has(shape.orgType ?? "");
+        const { cls } = billingClass(s, rows, shape);
+        counts[`billing_${cls}`] = (counts[`billing_${cls}`] ?? 0) + 1;
+        if (cls === "subscription_org") {
+            // Recorded in the audit only: the screen never shows a hit count or overage dollars.
+            const acct = seatInputs.get(cfg) ?? { extra: shape.extraUsage, ss: [] };
+            acct.ss.push({ rows, rates: rows.map((r) => ruleRate(origContext(r)).screen), paths });
+            seatInputs.set(cfg, acct);
+        }
+        const rowsIn = rows.filter((r) => r.t >= cut);
+        if (!rowsIn.length)
+            return;
+        // Every class is priced at API list prices; the screen says so.
+        const e = estimate(rowsIn);
+        const end = rowsIn.reduce((m, r) => Math.max(m, r.t), -Infinity);
+        const sc = {
+            label: labelFor(prettyProject(s.pdir)),
+            end,
+            actual: e.actual,
+            saved: e.saved,
+        };
+        sessions.push(sc);
+        if (cls === "subscription_org")
+            subSessions.push(sc);
+        orgLogin ||= subLogin;
+    });
+    const seat = [...seatInputs.values()].map((a) => analyzeSeat(a.ss, a.extra, now));
+    const use = subSessions.length ? subSessions : sessions;
+    const sub = subSessions.length || orgLogin
+        ? {
+            sessions: use.length,
+            actual: use.reduce((t, r) => t + r.actual, 0),
+            saved: use.reduce((t, r) => t + r.saved, 0),
+        }
+        : null;
+    const { lines, audit, variation } = buildScreen({ sessions, sub });
+    assertScreenBudget(lines);
+    audit.seat = {
+        shown: null,
+        raw: seat,
+        method: "seat.analyzeSeat per Team/Enterprise account; recorded, never shown",
+    };
+    return { lines, audit, variation, counts, seconds: (Date.now() - t0) / 1000 };
+}
+/** The screen's hard budget: a regression in buildScreen's line dropping must fail loudly. */
+export function assertScreenBudget(lines) {
+    if (lines.length > MAX_LINES || lines.some((l) => l.length > WIDTH)) {
+        throw new Error("first-run screen exceeded its 16 x 78 budget");
+    }
+}
+/** A transcript's mtime (ms), 0 when it vanished since discovery (it then sorts first). */
+export function mtimeOf(p) {
+    try {
+        return statSync(p).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Show the screen and write the local audit. Never throws: a failed look never blocks a launch. */
+export function showFirstRun(deps) {
+    let res;
+    try {
+        res = deps.compute();
+    }
+    catch (err) {
+        deps.note(`mnemom agent: could not look at your sessions (${err instanceof Error ? err.message : String(err)}).`);
+        return false;
+    }
+    deps.print("");
+    for (const l of res.lines)
+        deps.print(l);
+    deps.print("");
+    try {
+        writePrivate(join(deps.mnemomDir, AUDIT_FILE), `${JSON.stringify({ at: deps.now().toISOString(), seconds: res.seconds, counts: res.counts, numbers: res.audit, lines: res.lines }, null, 1)}\n`);
+    }
+    catch {
+        /* the audit is a convenience; the screen already printed */
+    }
+    return true;
+}
+/**
+ * The first-launch hook: offer once (interactive only), record the answer, show on yes.
+ * Returns what happened, for tests and the caller's logging.
+ */
+export async function maybeOfferFirstRun(deps) {
+    if (!deps.interactive)
+        return "skipped"; // never read or write state off a terminal
+    const path = statePath(deps.mnemomDir);
+    const st = readState(path);
+    if (!shouldOffer(st, deps.interactive))
+        return "skipped";
+    for (const l of OFFER_TEXT)
+        deps.print(l);
+    const ans = parseAnswer(await deps.ask(OFFER_QUESTION));
+    try {
+        writeState(path, recordAnswer(st, ans, deps.now()));
+    }
+    catch {
+        /* an unwritable state dir means we may ask again; never block the launch */
+    }
+    if (ans === "never")
+        return "never";
+    if (ans === "no")
+        return "declined";
+    return showFirstRun(deps) ? "shown" : "failed";
+}

package/dist/lib/first-run/lines.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Read-only, streamed line access to Claude Code transcripts for the first-run look
+ * (lib/first-run). Transcripts can be hundreds of MB, so files are read in fixed chunks
+ * and handed out one line (a Buffer view, no copy) at a time; callers decode only the
+ * lines they need. Opened read-only; never written.
+ */
+/**
+ * Call `onLine` for every line of `path` (without the trailing newline). Return `false`
+ * from `onLine` to stop early. `maxBytes` caps how much of the file is read (the head
+ * scan). Returns false when the file cannot be opened.
+ */
+export declare function forEachLine(path: string, onLine: (line: Buffer) => unknown, maxBytes?: number): boolean;
+/** JSON.parse that returns null instead of throwing. */
+export declare function parseJson(line: Buffer | string): Record<string, unknown> | null;
+/** ISO-8601 → epoch seconds, or null. */
+export declare function isoSeconds(v: unknown): number | null;

package/dist/lib/first-run/lines.js

@@ -0,0 +1,80 @@
+/**
+ * Read-only, streamed line access to Claude Code transcripts for the first-run look
+ * (lib/first-run). Transcripts can be hundreds of MB, so files are read in fixed chunks
+ * and handed out one line (a Buffer view, no copy) at a time; callers decode only the
+ * lines they need. Opened read-only; never written.
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+const CHUNK = 4 * 1024 * 1024;
+const NL = 0x0a;
+/**
+ * Call `onLine` for every line of `path` (without the trailing newline). Return `false`
+ * from `onLine` to stop early. `maxBytes` caps how much of the file is read (the head
+ * scan). Returns false when the file cannot be opened.
+ */
+export function forEachLine(path, onLine, maxBytes = Infinity) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const buf = Buffer.allocUnsafe(CHUNK);
+        let carry = null;
+        let readTotal = 0;
+        for (;;) {
+            if (readTotal >= maxBytes)
+                break;
+            const n = readSync(fd, buf, 0, Math.min(CHUNK, maxBytes - readTotal), null);
+            if (n <= 0)
+                break;
+            readTotal += n;
+            const view = buf.subarray(0, n);
+            let start = 0;
+            let nl = view.indexOf(NL, start);
+            while (nl !== -1) {
+                let line = view.subarray(start, nl);
+                if (carry) {
+                    line = Buffer.concat([carry, line]);
+                    carry = null;
+                }
+                if (onLine(line) === false)
+                    return true;
+                start = nl + 1;
+                nl = view.indexOf(NL, start);
+            }
+            if (start < n) {
+                const rest = Buffer.from(view.subarray(start, n));
+                carry = carry ? Buffer.concat([carry, rest]) : rest;
+            }
+        }
+        if (carry && carry.length)
+            onLine(carry);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** JSON.parse that returns null instead of throwing. */
+export function parseJson(line) {
+    try {
+        const v = JSON.parse(typeof line === "string" ? line : line.toString("utf8"));
+        return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** ISO-8601 → epoch seconds, or null. */
+export function isoSeconds(v) {
+    if (typeof v !== "string" || !v)
+        return null;
+    const ms = Date.parse(v);
+    return Number.isFinite(ms) ? ms / 1000 : null;
+}