@illuminis/comprism 0.1.3 → 0.1.5

package/out/lib/sessions.js

@@ -0,0 +1,221 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessions = sessions;
+exports.failure = failure;
+exports.exitFor = exitFor;
+exports.pick = pick;
+exports.cmdSessions = cmdSessions;
+/**
+ * A person's sessions, as the service keeps them (manual chapter 8).
+ *
+ * Nothing about a session is decided or stored here. The list, the numbers,
+ * the names, the costs, whether the conversation was kept and the words of
+ * every line come from the service's `sessions` intent; this file sends the
+ * question, draws the answer, and runs the arrow key list for `--resume`.
+ */
+const ui = __importStar(require("./ui"));
+const gateway_1 = require("./gateway");
+const out = (s = '') => process.stdout.write(s + '\n');
+/** Ask the service one sessions question, with where this machine is. */
+async function sessions(op, extra = {}, folder) {
+    const { resolveProject, asWire } = await Promise.resolve().then(() => __importStar(require('./project')));
+    const { currentWorkspace } = await Promise.resolve().then(() => __importStar(require('../commands/settings')));
+    const facts = resolveProject(folder ?? currentWorkspace().path, []);
+    return (0, gateway_1.ask)({
+        intent: 'sessions',
+        prompt: '',
+        sessionsPayload: {
+            op,
+            project: asWire(facts),
+            // The service writes the times, in this machine's own clock.
+            tz_minutes: -new Date().getTimezoneOffset(),
+            ...extra,
+        },
+    });
+}
+/** Why a sessions question got no answer, in the service's words when it has them. */
+function failure(reply) {
+    if (reply.served === false) {
+        return 'Your workspace is running a build without sessions yet.';
+    }
+    return reply.message || 'Your workspace could not be reached.';
+}
+/** The exit number for a sessions question that got no answer (Appendix B). */
+function exitFor(reply) {
+    if (reply.message === 'this machine is not signed in')
+        return 3;
+    if (!reply.ok && reply.message === 'the service could not be reached')
+        return 6;
+    return 1;
+}
+/**
+ * Choose one line with the arrow keys; Enter picks, Esc or Ctrl+C leaves.
+ * Resolves with the index chosen, or null. Without a terminal it asks for a
+ * number instead, so a script is never left waiting on keys it cannot send.
+ */
+async function pick(lines) {
+    if (lines.length === 0)
+        return null;
+    if (!process.stdin.isTTY) {
+        lines.forEach((l, i) => out(`${String(i + 1).padStart(3)}. ${l.trimStart()}`));
+        const { ask: askLine, closePrompt } = await Promise.resolve().then(() => __importStar(require('./prompt')));
+        const said = (await askLine('  which one? ')).trim();
+        closePrompt();
+        const n = Number(said);
+        return Number.isInteger(n) && n >= 1 && n <= lines.length ? n - 1 : null;
+    }
+    const stdin = process.stdin;
+    let at = 0;
+    const draw = (first) => {
+        if (!first)
+            process.stdout.write(`\x1b[${lines.length}A`);
+        lines.forEach((l, i) => {
+            const mark = i === at ? ui.c.bold('> ') : '  ';
+            process.stdout.write(`\x1b[2K${mark}${i === at ? ui.c.bold(l.trimStart()) : l.trimStart()}\n`);
+        });
+    };
+    out(ui.c.dim('  Up and Down to choose, Enter to resume, Esc to leave.'));
+    draw(true);
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    return new Promise((resolve) => {
+        const done = (chosen) => {
+            stdin.off('data', onKey);
+            stdin.setRawMode(Boolean(wasRaw));
+            stdin.pause();
+            resolve(chosen);
+        };
+        const onKey = (buf) => {
+            const key = buf.toString();
+            if (key === '\x1b[A' || key === 'k') {
+                at = (at + lines.length - 1) % lines.length;
+                draw(false);
+            }
+            else if (key === '\x1b[B' || key === 'j') {
+                at = (at + 1) % lines.length;
+                draw(false);
+            }
+            else if (key === '\r' || key === '\n')
+                done(at);
+            else if (key === '\x1b' || key === '\x03' || key === 'q')
+                done(null);
+        };
+        stdin.on('data', onKey);
+    });
+}
+/** Print what the service sent, or why it sent nothing. */
+function answered(reply) {
+    out();
+    if (!reply.ok || !reply.sessions) {
+        out(ui.fail(failure(reply)));
+        out();
+        return exitFor(reply);
+    }
+    for (const line of reply.sessions.lines)
+        out(line);
+    out();
+    return 0;
+}
+const USAGE = [
+    'comprism sessions [--search <words>] [--pr <number>]',
+    'comprism sessions rename <number> "<name>"',
+    'comprism sessions branch <number>',
+    'comprism sessions export <number> [--format json]',
+];
+/**
+ * `comprism sessions` and its words (manual 8.5 to 8.7, 8.10). Every answer,
+ * every line and every refusal is the service's; the export is written to
+ * standard output exactly as it came, so `> session.md` holds the file.
+ */
+async function cmdSessions(args) {
+    const [word, key, ...rest] = args;
+    if (word === 'rename') {
+        const name = rest.join(' ').trim();
+        if (!key || !name) {
+            out(ui.fail(`Say which session and the new name: ${USAGE[1]}`));
+            return 2;
+        }
+        return answered(await sessions('rename', { key, name }));
+    }
+    if (word === 'branch') {
+        if (!key) {
+            out(ui.fail(`Say which session to branch: ${USAGE[2]}`));
+            return 2;
+        }
+        return answered(await sessions('branch', { key }));
+    }
+    if (word === 'export') {
+        const at = rest.indexOf('--format');
+        const format = at === -1 ? 'markdown' : rest[at + 1];
+        if (!key || (format !== 'markdown' && format !== 'json' && format !== 'md')) {
+            process.stderr.write(ui.fail(`Say which session, and json or markdown: ${USAGE[3]}`) + '\n');
+            return 2;
+        }
+        const reply = await sessions('export', { key, format: format === 'json' ? 'json' : 'markdown' });
+        const got = reply.sessions;
+        if (!reply.ok || !got) {
+            process.stderr.write(ui.fail(failure(reply)) + '\n');
+            return exitFor(reply);
+        }
+        process.stdout.write(got.format === 'json'
+            ? `${JSON.stringify(got.document, null, 2)}\n`
+            : `${String(got.text ?? '')}\n`);
+        return 0;
+    }
+    const prAt = args.indexOf('--pr');
+    if (prAt !== -1) {
+        const pr = args[prAt + 1];
+        if (!pr) {
+            out(ui.fail('Say which pull request: comprism sessions --pr 42'));
+            return 2;
+        }
+        return answered(await sessions('by_pr', { pr }));
+    }
+    const at = args.indexOf('--search');
+    const search = at === -1 ? '' : args.slice(at + 1).join(' ').trim();
+    if (at !== -1 && !search) {
+        out(ui.fail('Say what to search for: comprism sessions --search parser'));
+        return 2;
+    }
+    if (word && !word.startsWith('-')) {
+        out(ui.fail(`There is no sessions command called "${word}".`));
+        for (const u of USAGE)
+            out(`      ${ui.c.dim(u)}`);
+        return 2;
+    }
+    return answered(await sessions('list', { search, limit: 20 }));
+}

package/out/lib/startcache.d.ts

@@ -0,0 +1,13 @@
+import type { SessionOut } from './gateway';
+import type { CommandList } from './commandlist';
+export interface StartCache {
+    /** Which workspace these answers came from; another workspace's are never used. */
+    url?: string;
+    me?: SessionOut | null;
+    hasKey?: boolean;
+    /** The project line, by project folder. */
+    lines?: Record<string, string>;
+    list?: CommandList | null;
+}
+export declare function readStart(url: string): StartCache;
+export declare function saveStart(url: string, change: Partial<StartCache>): void;

package/out/lib/startcache.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStart = readStart;
+exports.saveStart = saveStart;
+/**
+ * What the service said the last time a session opened, kept so the next one
+ * can open at once.
+ *
+ * Opening a session asks the service four things (who you are, whether a key
+ * is stored, the project line, the command list). Asked from a laptop whose
+ * database is a region away, each takes seconds, and the prompt waited for all
+ * of them. Now the last answers are drawn immediately and the same questions
+ * are asked again in the background; the fresh answers are kept for next time,
+ * and a change that matters (no key any more) is said as soon as it is known.
+ *
+ * Only the service's own answers are kept, exactly as sent. Nothing here is
+ * decided on this machine, and a missing or unreadable file simply means the
+ * session waits for the service, as it always did.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("./config");
+function file() {
+    return path.join((0, config_1.ensureHome)(), 'start-cache.json');
+}
+function readStart(url) {
+    try {
+        const got = JSON.parse(fs.readFileSync(file(), 'utf8'));
+        return got.url === url ? got : { url };
+    }
+    catch {
+        return { url };
+    }
+}
+function saveStart(url, change) {
+    try {
+        const now = readStart(url);
+        const next = {
+            ...now, ...change, url,
+            lines: { ...(now.lines ?? {}), ...(change.lines ?? {}) },
+        };
+        fs.writeFileSync(file(), JSON.stringify(next), { mode: 0o600 });
+    }
+    catch { /* a cache that cannot be written only means the next start waits */ }
+}

package/out/lib/stdin.d.ts

@@ -0,0 +1,32 @@
+import * as tty from 'node:tty';
+import * as attach from './attach';
+/** The name piped text is attached under. */
+export declare const STDIN_NAME = "standard input";
+/**
+ * Everything piped in, read to the end. Null when standard input is a
+ * terminal, and empty when the pipe closed with nothing on it.
+ *
+ * A pipe that stays open with nothing coming (a command still running, or one
+ * that never closes) is announced after two seconds on standard error, so the
+ * person is not left looking at a still screen. Ctrl+C ends it as usual.
+ */
+export declare function readPiped(input?: NodeJS.ReadableStream & {
+    isTTY?: boolean;
+}, say?: (line: string) => void): Promise<string | null>;
+/**
+ * The piped text, uploaded as `standard input`. Written to a temporary file so
+ * it travels exactly like any attachment, and the file removed straight after.
+ */
+export declare function attachPiped(text: string, baseUrl: string, credential: string): Promise<{
+    attached: attach.Attached[];
+    refused: {
+        file: string;
+        why: string;
+    }[];
+}>;
+/**
+ * The terminal the person is sitting at, when standard input is a pipe.
+ * Null when there is none (a script, a scheduler, a container), which makes
+ * the job unattended.
+ */
+export declare function openTerminal(platform?: string): tty.ReadStream | null;

package/out/lib/stdin.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STDIN_NAME = void 0;
+exports.readPiped = readPiped;
+exports.attachPiped = attachPiped;
+exports.openTerminal = openTerminal;
+/**
+ * Text piped in, and the keyboard behind the pipe (manual 3.9).
+ *
+ * `git diff | comprism work "write a commit message"` hands the tool two
+ * things through two doors: the diff on standard input and the person at the
+ * terminal. They are never confused. Standard input is read to its end and
+ * attached as a file called `standard input`; it is material to read, never
+ * an answer. Approval questions go to the terminal itself (`/dev/tty`, or the
+ * Windows console), so a `y` in the piped text can never approve anything.
+ * With no terminal at all, the job is unattended (manual 10.1).
+ */
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const tty = __importStar(require("node:tty"));
+const attach = __importStar(require("./attach"));
+/** The name piped text is attached under. */
+exports.STDIN_NAME = 'standard input';
+/** How long a pipe may stay silent before the person is told it is waited on. */
+const QUIET_MS = 2000;
+/**
+ * Everything piped in, read to the end. Null when standard input is a
+ * terminal, and empty when the pipe closed with nothing on it.
+ *
+ * A pipe that stays open with nothing coming (a command still running, or one
+ * that never closes) is announced after two seconds on standard error, so the
+ * person is not left looking at a still screen. Ctrl+C ends it as usual.
+ */
+function readPiped(input = process.stdin, say = (l) => { process.stderr.write(`${l}\n`); }) {
+    if (input.isTTY)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        const chunks = [];
+        const quiet = setTimeout(() => say('  waiting for standard input (Ctrl+C to stop)'), QUIET_MS);
+        input.on('data', (c) => {
+            chunks.push(typeof c === 'string' ? Buffer.from(c) : c);
+        });
+        const done = () => {
+            clearTimeout(quiet);
+            resolve(Buffer.concat(chunks).toString('utf8'));
+        };
+        input.on('end', done);
+        input.on('error', done);
+    });
+}
+/**
+ * The piped text, uploaded as `standard input`. Written to a temporary file so
+ * it travels exactly like any attachment, and the file removed straight after.
+ */
+async function attachPiped(text, baseUrl, credential) {
+    const folder = fs.mkdtempSync(path.join(os.tmpdir(), 'comprism-stdin-'));
+    const file = path.join(folder, exports.STDIN_NAME);
+    try {
+        fs.writeFileSync(file, text);
+        return await attach.upload(baseUrl, credential, [file]);
+    }
+    finally {
+        fs.rmSync(folder, { recursive: true, force: true });
+    }
+}
+/**
+ * The terminal the person is sitting at, when standard input is a pipe.
+ * Null when there is none (a script, a scheduler, a container), which makes
+ * the job unattended.
+ */
+function openTerminal(platform = process.platform) {
+    try {
+        const fd = fs.openSync(platform === 'win32' ? 'CONIN$' : '/dev/tty', 'r');
+        if (!tty.isatty(fd)) {
+            fs.closeSync(fd);
+            return null;
+        }
+        return new tty.ReadStream(fd);
+    }
+    catch {
+        return null;
+    }
+}

package/out/lib/store.d.ts

@@ -0,0 +1,40 @@
+export declare const LEDGER_FILE = "ledger.jsonl";
+export declare const DECISIONS_FILE = "decisions.jsonl";
+export declare const SESSIONS_FILE = "sessions.json";
+/**
+ * Files that may never carry a supersede row and may never be resolved through
+ * `latestByKey`. Adding a file here is a promise that its rows are frozen.
+ */
+export declare const IMMUTABLE_FILES: ReadonlySet<string>;
+export declare function storePath(file: string): string;
+/**
+ * Append to a supersedable store. Refuses the immutable ones by name.
+ */
+export declare function appendRow(file: string, row: object): void;
+/**
+ * Append to an immutable store. The only write path to `decisions.jsonl`.
+ *
+ * Refuses any row carrying `supersedes`. A decision record that supersedes
+ * another is not a correction, it is a second decision, and it belongs in the
+ * file as its own row with its own id.
+ */
+export declare function appendImmutable(file: string, row: object): void;
+/**
+ * Read every parseable row.
+ *
+ * A truncated final line - the process died mid-write on a machine without the
+ * fsync guarantee, or the file was copied while being written - is skipped
+ * rather than thrown. One lost row is a gap in the evidence; an exception here
+ * would make every row after it unreadable, which is a far worse failure.
+ */
+export declare function readRows<T>(file: string): T[];
+/**
+ * Resolve supersede chains: the last row wins per key.
+ *
+ * Takes the file name rather than just the rows, so that calling it on an
+ * immutable store is an error at the call site rather than a review comment
+ * somebody has to catch.
+ */
+export declare function latestByKey<T>(file: string, rows: T[], key: (row: T) => string): Map<string, T>;
+/** Row count without parsing, for reports and the gate. */
+export declare function countRows(file: string): number;

package/out/lib/store.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMMUTABLE_FILES = exports.SESSIONS_FILE = exports.DECISIONS_FILE = exports.LEDGER_FILE = void 0;
+exports.storePath = storePath;
+exports.appendRow = appendRow;
+exports.appendImmutable = appendImmutable;
+exports.readRows = readRows;
+exports.latestByKey = latestByKey;
+exports.countRows = countRows;
+/**
+ * The append-only store.
+ *
+ * One JSON object per line. A row is written once and never edited. There is no
+ * update path, no delete path and no rewrite path in this file, and that is the
+ * point: the discipline is structural rather than a convention someone has to
+ * remember at three in the morning.
+ *
+ * Two grades of immutability, and the difference matters:
+ *
+ *   - Ordinary stores (the ledger) are append-only with supersession. A
+ *     correction is a NEW row carrying `supersedes`, and `latestByKey` resolves
+ *     the chain at read time. Nothing is lost; the earlier belief stays on the
+ *     record.
+ *   - `decisions.jsonl` is stricter. It is never superseded, for any reason,
+ *     because it means exactly one thing forever: what the system knew and
+ *     chose at decision time. A supersede row would make it a claim about the
+ *     present instead. The fences below make that unenforceable by accident:
+ *     `appendRow` refuses the file, `appendImmutable` refuses a `supersedes`
+ *     field, and `latestByKey` refuses to run against it at all.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const config_1 = require("./config");
+exports.LEDGER_FILE = 'ledger.jsonl';
+exports.DECISIONS_FILE = 'decisions.jsonl';
+exports.SESSIONS_FILE = 'sessions.json';
+/**
+ * Files that may never carry a supersede row and may never be resolved through
+ * `latestByKey`. Adding a file here is a promise that its rows are frozen.
+ */
+exports.IMMUTABLE_FILES = new Set([exports.DECISIONS_FILE]);
+function storePath(file) {
+    return node_path_1.default.join((0, config_1.homeDir)(), file);
+}
+/**
+ * The single write primitive. Everything that appends goes through here.
+ *
+ * `fsync` after every row is the reason a kill mid-session leaves a parseable
+ * file: the bytes are on the disk, not in a buffer that dies with the process.
+ * It costs a syscall per call, against a network round trip to a model, so the
+ * cost is not measurable and the guarantee is absolute.
+ */
+function writeLine(file, row) {
+    (0, config_1.ensureHome)();
+    const line = `${JSON.stringify(row)}\n`;
+    const fd = node_fs_1.default.openSync(storePath(file), 'a', 0o600);
+    try {
+        node_fs_1.default.writeSync(fd, line, null, 'utf8');
+        node_fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+/**
+ * Append to a supersedable store. Refuses the immutable ones by name.
+ */
+function appendRow(file, row) {
+    if (exports.IMMUTABLE_FILES.has(file)) {
+        throw new Error(`${file} is immutable: append through appendImmutable, which forbids supersession.`);
+    }
+    writeLine(file, row);
+}
+/**
+ * Append to an immutable store. The only write path to `decisions.jsonl`.
+ *
+ * Refuses any row carrying `supersedes`. A decision record that supersedes
+ * another is not a correction, it is a second decision, and it belongs in the
+ * file as its own row with its own id.
+ */
+function appendImmutable(file, row) {
+    if (!exports.IMMUTABLE_FILES.has(file)) {
+        throw new Error(`${file} is not an immutable store: append through appendRow.`);
+    }
+    if (Object.prototype.hasOwnProperty.call(row, 'supersedes')) {
+        throw new Error(`${file} rows are never superseded. A later decision is a new record, not a correction.`);
+    }
+    writeLine(file, row);
+}
+/**
+ * Read every parseable row.
+ *
+ * A truncated final line - the process died mid-write on a machine without the
+ * fsync guarantee, or the file was copied while being written - is skipped
+ * rather than thrown. One lost row is a gap in the evidence; an exception here
+ * would make every row after it unreadable, which is a far worse failure.
+ */
+function readRows(file) {
+    const p = storePath(file);
+    if (!node_fs_1.default.existsSync(p))
+        return [];
+    const out = [];
+    for (const line of node_fs_1.default.readFileSync(p, 'utf8').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+/**
+ * Resolve supersede chains: the last row wins per key.
+ *
+ * Takes the file name rather than just the rows, so that calling it on an
+ * immutable store is an error at the call site rather than a review comment
+ * somebody has to catch.
+ */
+function latestByKey(file, rows, key) {
+    if (exports.IMMUTABLE_FILES.has(file)) {
+        throw new Error(`${file} is never superseded, so resolving it through latestByKey would imply it can be.`);
+    }
+    const map = new Map();
+    for (const row of rows)
+        map.set(key(row), row);
+    return map;
+}
+/** Row count without parsing, for reports and the gate. */
+function countRows(file) {
+    return readRows(file).length;
+}

package/out/lib/sync.d.ts

@@ -0,0 +1,18 @@
+export interface SyncTarget {
+    /** Tenant base URL, e.g. https://acme.completionprism.ai */
+    url: string;
+    /** A tenant session token. Never written to any file by this command. */
+    token: string;
+    /** Only needed on localhost, where there is no subdomain to resolve. */
+    tenant?: string;
+}
+export interface SyncOutcome {
+    accepted: Record<string, number>;
+    duplicates: Record<string, number>;
+    rejected: Record<string, string[]>;
+    reconciliation: Record<string, unknown>;
+    sent: Record<string, number>;
+}
+/** Everything the local stores hold, in the shape the tenant expects. */
+export declare function collectBatch(): Record<string, unknown>;
+export declare function sync(target: SyncTarget): Promise<SyncOutcome>;