syndes 0.1.0

package/runtime/spool.mjs

@@ -0,0 +1,92 @@
+/**
+ * Spool files: the handoff between the blocking hook and the detached worker.
+ *
+ * One file per hook invocation, never a shared one. appendFile under O_APPEND is
+ * atomic for small writes on POSIX and is NOT on Windows, so two hooks racing
+ * into one file would interleave bytes on a third of our supported platforms.
+ * Per-process files remove the race instead of guarding it.
+ *
+ * The hook writes to a `.part` name and renames into place. rename is atomic
+ * everywhere, so the worker can never observe a half-written spool file — the
+ * alternative is silently discarding a torn line, which is data loss.
+ */
+
+import { readdirSync, unlinkSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { spoolDir } from './paths.mjs';
+import { streamRecords } from './jsonl.mjs';
+import { debug } from './log.mjs';
+
+/** Spool entries this old were written by a worker that never came back for them. */
+const ABANDONED_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function listSpoolFiles() {
+  try {
+    return readdirSync(spoolDir)
+      .filter((name) => name.endsWith('.jsonl'))
+      .sort() // names begin with a zero-padded epoch, so lexical order is time order
+      .map((name) => join(spoolDir, name));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read every pending spool file into one time-ordered batch.
+ *
+ * Files are NOT deleted here. The caller retires them only after their records
+ * are durably chained — losing a worker must cost latency, never data.
+ *
+ * @returns {Promise<{records: object[], files: string[]}>}
+ */
+export async function drainSpool(limit = 20_000) {
+  const files = listSpoolFiles();
+  const records = [];
+  const consumed = [];
+
+  for (const file of files) {
+    if (records.length >= limit) break;
+    try {
+      for await (const record of streamRecords(file)) records.push(record);
+      consumed.push(file);
+    } catch (error) {
+      debug('unreadable spool file', file, error.message);
+      consumed.push(file); // unreadable now means unreadable forever; do not wedge the drain
+    }
+  }
+
+  // Hook clocks come from the same machine, so ties are ordered by the
+  // monotonic counter the hook stamps alongside the wall clock.
+  records.sort((a, b) => (a.t ?? 0) - (b.t ?? 0) || (a.n ?? 0) - (b.n ?? 0));
+
+  return { records, files: consumed };
+}
+
+export function retire(files) {
+  for (const file of files) {
+    try {
+      unlinkSync(file);
+    } catch {
+      // Already gone, or held open on Windows. The next drain will re-read it,
+      // and chain append is idempotent per spool id.
+    }
+  }
+}
+
+/** Clear `.part` files abandoned by a hook that died between write and rename. */
+export function sweepAbandoned() {
+  const cutoff = Date.now() - ABANDONED_MS;
+  try {
+    for (const name of readdirSync(spoolDir)) {
+      if (!name.endsWith('.part')) continue;
+      const file = join(spoolDir, name);
+      try {
+        if (statSync(file).mtimeMs < cutoff) unlinkSync(file);
+      } catch { /* raced with another sweep */ }
+    }
+  } catch { /* no spool directory yet */ }
+}
+
+export function pendingCount() {
+  return listSpoolFiles().length;
+}

package/runtime/worker.mjs

@@ -0,0 +1,275 @@
+/**
+ * The detached worker. Everything the hook refused to do.
+ *
+ * Spawned with detached:true and stdio:'ignore', unref'd, so Claude Code never
+ * waits on it and it outlives the hook that started it.
+ *
+ * Pipeline: lock → drain spool → classify → tail transcripts → chain → rollups
+ * → practice rules → deliver → release.
+ *
+ * Single-writer by construction: if the lock is held, this process exits at once
+ * rather than queueing. The next hook spawns another, and the spool is still
+ * there. Losing a worker costs latency, never data.
+ */
+
+import { ensureDataDirs } from './paths.mjs';
+import { acquire, release } from './lock.mjs';
+import { drainSpool, retire, sweepAbandoned } from './spool.mjs';
+import { loadConfig } from './config.mjs';
+import { debug } from './log.mjs';
+import { append } from '../ledger/append.mjs';
+import { draft, KIND } from '../ledger/schema.mjs';
+import { classify } from '../collect/classify.mjs';
+import * as sessions from '../collect/sessions.mjs';
+import { projectFor, rememberProject } from '../collect/projects.mjs';
+import { sync as syncTranscript } from '../collect/transcript.mjs';
+import { commitsSince, branchOf, headOf } from '../collect/git.mjs';
+import { updateRollups } from '../analytics/rollup.mjs';
+import { runCoach } from '../practices/engine.mjs';
+import { pollTails } from '../collect/tail.mjs';
+
+/** Events after which the user has paused, so coaching may run. */
+const BREAKPOINTS = new Set(['Stop', 'SessionEnd', 'SubagentStop']);
+/** Bound on drain passes, so a flood cannot keep one worker alive forever. */
+const MAX_PASSES = 8;
+
+async function main() {
+  ensureDataDirs();
+  if (!acquire()) {
+    debug('another worker holds the lock; exiting');
+    return;
+  }
+
+  try {
+    const result = await run();
+    debug('worker done', result);
+  } catch (error) {
+    debug('worker failed', error?.stack ?? String(error));
+  } finally {
+    release();
+  }
+}
+
+async function run() {
+  sweepAbandoned();
+
+  let appended = 0;
+  let sawBreakpoint = false;
+
+  for (let pass = 0; pass < MAX_PASSES; pass += 1) {
+    const { records, files } = await drainSpool();
+    if (!records.length) break;
+
+    const { drafts, touched, breakpoint } = process_(records);
+    sawBreakpoint ||= breakpoint;
+
+    drafts.push(...collectUsage(touched));
+    drafts.push(...collectCommits(touched));
+    drafts.push(...reap());
+
+    // Chain first, retire second. If this process dies between them the spool is
+    // re-read and the batch is written twice — visible duplication, which verify
+    // reports and a human can reason about. The other order loses data silently.
+    if (drafts.length) {
+      const written = await append(sortByTime(drafts));
+      appended += written.written;
+    }
+    retire(files);
+    sessions.save();
+  }
+
+  // Poll other agents OUTSIDE the drain loop, and unconditionally.
+  //
+  // It used to sit inside, which meant it only ran when Claude Code hooks had
+  // also fired — so somebody using only Codex recorded nothing at all, because
+  // the loop breaks on the first empty spool.
+  const tailed = followOtherAgents();
+  if (tailed.length) {
+    const written = await append(sortByTime(tailed));
+    appended += written.written;
+  }
+
+  if (appended) await updateRollups();
+  if (sawBreakpoint) await runCoach();
+
+  return { appended, tailed: tailed.length };
+}
+
+/** @returns {{drafts: object[], touched: Map, breakpoint: boolean}} */
+function process_(records) {
+  const drafts = [];
+  const touched = new Map();
+  let breakpoint = false;
+
+  for (const spooled of records) {
+    let payload;
+    try {
+      payload = JSON.parse(spooled.p);
+    } catch {
+      continue;
+    }
+    spooled.parsed = payload;
+
+    const sessionId = payload.session_id ?? 'unknown';
+    const session = sessions.get(sessionId);
+    const config = loadConfig(payload.cwd);
+    const project = payload.cwd ? projectFor(payload.cwd) : null;
+
+    if (!wanted(payload.hook_event_name, config)) continue;
+
+    if (project && session.project !== project.id) {
+      session.project = project.id;
+      rememberProject(project);
+    }
+    session.cwd = payload.cwd ?? session.cwd;
+    session.transcript = payload.transcript_path ?? session.transcript;
+    session.startedAt ??= spooled.t;
+    session.lastAt = spooled.t;
+
+    drafts.push(...classify(spooled, { config, session, project }));
+    count(session, payload.hook_event_name, drafts[drafts.length - 1]);
+
+    if (BREAKPOINTS.has(payload.hook_event_name)) breakpoint = true;
+    if (payload.hook_event_name === 'SessionEnd') {
+      touched.set(sessionId, { session, config, ending: true });
+    } else {
+      const existing = touched.get(sessionId);
+      touched.set(sessionId, { session, config, ending: existing?.ending ?? false });
+    }
+  }
+
+  return { drafts, touched, breakpoint };
+}
+
+/** Config gates the expensive hooks; an event nobody asked for is dropped here. */
+function wanted(event, config) {
+  if (event === 'PreToolUse' || event === 'PostToolUse') return config.track.tools;
+  if (event === 'UserPromptSubmit') return config.track.prompts;
+  if (event === 'PermissionRequest') return config.track.permissions;
+  return true;
+}
+
+function count(session, event, last) {
+  const counts = session.counts;
+  if (event === 'UserPromptSubmit') counts.prompts += 1;
+  else if (event === 'PostToolUse') counts.tools += 1;
+  else if (event === 'PermissionRequest') counts.blocks += 1;
+  else if (event === 'PreCompact') counts.compacts += 1;
+  if (last?.kind === KIND.FILE_TOUCH) counts.writes += 1;
+  if (last?.kind === KIND.TOOL_POST && last.data.failed) counts.errors += 1;
+}
+
+/** Token, cost and cache numbers, read incrementally from each transcript. */
+function collectUsage(touched) {
+  const drafts = [];
+
+  for (const [sessionId, { session, config }] of touched) {
+    if (!config.track.transcript || !session.transcript) continue;
+
+    const result = syncTranscript(session.transcript, session.cursor ?? 0);
+    session.cursor = result.cursor;
+    if (result.errors) session.counts.errors += result.errors;
+
+    for (const sample of result.samples) {
+      drafts.push(draft(KIND.USAGE, {
+        ts: sample.ts ?? session.lastAt ?? Date.now(),
+        session: sessionId,
+        project: session.project,
+        data: {
+          model: sample.model,
+          input: sample.input,
+          output: sample.output,
+          cacheRead: sample.cacheRead,
+          cacheWrite: sample.cacheWrite,
+          thinking: sample.thinking,
+          toolUses: sample.toolUses,
+          sidechain: sample.sidechain,
+        },
+      }));
+    }
+  }
+  return drafts;
+}
+
+function collectCommits(touched) {
+  const drafts = [];
+
+  for (const [sessionId, { session, config }] of touched) {
+    if (!config.track.git || !session.cwd) continue;
+
+    const head = headOf(session.cwd);
+    if (!head) continue;
+    if (!session.head) { session.head = head; continue; } // baseline only
+    if (session.head === head) continue;
+
+    for (const commit of commitsSince(session.cwd, session.head)) {
+      drafts.push(draft(KIND.GIT_COMMIT, {
+        ts: session.lastAt ?? Date.now(),
+        session: sessionId,
+        project: session.project,
+        data: { ...commit, branch: branchOf(session.cwd) },
+      }));
+    }
+    session.head = head;
+  }
+  return drafts;
+}
+
+/**
+ * Other agents, read from their own session files.
+ *
+ * Folded into the same drain as the hooks, so anything Codex did since the last
+ * pass lands in the same chain, in timestamp order, with `source` telling them
+ * apart. Costs one stat per followed file when nothing has changed.
+ */
+function followOtherAgents() {
+  try {
+    const { drafts, lines } = pollTails();
+    if (lines) debug('tailed', lines, 'lines from other agents');
+    return drafts;
+  } catch (error) {
+    debug('tail poll failed', error?.message);
+    return [];
+  }
+}
+
+/** A session that stopped reporting ended without a hook. Say so, do not guess a clean close. */
+function reap() {
+  return sessions.reapStale().map(({ id, session }) => draft(KIND.SESSION_END, {
+    ts: session.lastAt ?? Date.now(),
+    session: id,
+    project: session.project,
+    data: {
+      reason: 'inferred',
+      durationMs: session.startedAt ? (session.lastAt ?? 0) - session.startedAt : null,
+      counts: { ...session.counts },
+    },
+  }));
+}
+
+/**
+ * Same-millisecond events are ordered by what must logically come first.
+ * Two hooks can land in one millisecond and their pids say nothing about order.
+ */
+const RANK = {
+  [KIND.SESSION_START]: 0, [KIND.PROMPT]: 1, [KIND.TOOL_BLOCKED]: 2,
+  [KIND.TOOL_PRE]: 3, [KIND.TOOL_POST]: 4, [KIND.FILE_TOUCH]: 5,
+  [KIND.USAGE]: 6, [KIND.GIT_COMMIT]: 7, [KIND.COMPACT]: 8,
+  [KIND.STOP]: 9, [KIND.SUBAGENT_STOP]: 9, [KIND.SESSION_END]: 10,
+};
+
+function sortByTime(drafts) {
+  return drafts
+    .map((record, index) => ({ record, index }))
+    .sort((a, b) =>
+      a.record.ts - b.record.ts ||
+      (RANK[a.record.kind] ?? 5) - (RANK[b.record.kind] ?? 5) ||
+      a.index - b.index)
+    .map(({ record }) => record);
+}
+
+// Started last, on purpose. With top-level await, the module body pauses here —
+// so anything declared with const or let BELOW this line is still in its
+// temporal dead zone while main() runs. Function declarations hoist; RANK does
+// not. Keeping the entry point at the bottom is what makes that a non-issue.
+await main();

package/src/briefing.mjs

@@ -0,0 +1,94 @@
+/**
+ * The post-install briefing.
+ *
+ * Its own module because two callers print it — `syndes install` and the npm
+ * postinstall — and a second copy would drift the moment either changed.
+ */
+
+import {
+  bold, grey, cyan, green, write, pad, stream,
+} from './term.mjs';
+import { loadConfig } from '../runtime/config.mjs';
+import { existsSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { dataDir, displayPath, briefingPending } from '../runtime/paths.mjs';
+
+/** Ask for the briefing to be shown on the user's next command. */
+export function deferBriefing() {
+  try {
+    mkdirSync(dirname(briefingPending), { recursive: true });
+    writeFileSync(briefingPending, `${Date.now()}\n`);
+  } catch {
+    // Losing the marker costs a briefing, never an install.
+  }
+}
+
+/** Forget any owed briefing, for callers that just printed one themselves. */
+export function clearPending() {
+  try { rmSync(briefingPending, { force: true }); } catch { /* nothing owed */ }
+}
+
+/** Show it once if it is owed, then forget. @returns {Promise<boolean>} */
+export async function showBriefingIfPending() {
+  if (!existsSync(briefingPending)) return false;
+  try { rmSync(briefingPending, { force: true }); } catch { /* shown either way */ }
+  await runBriefing({ events: [] });
+  return true;
+}
+
+/** @param {{events: string[]}} result  what install() reported */
+export async function runBriefing(result) {
+  const port = loadConfig().dashboard.port;
+  const rule = grey('─'.repeat(52));
+
+  write();
+  await stream(`  ${green('Recording.')} ${grey('Every prompt, tool call and permission stop from here on.')}`);
+  write();
+
+  await stream(`  ${bold('WHAT THIS IS')}`);
+  write(`  ${rule}`);
+  await stream(`  ${grey('SynDes keeps a tamper-evident ledger of how you work with coding')}`);
+  await stream(`  ${grey('agents, scores it, and tells you the few habits worth changing.')}`);
+  await stream(`  ${grey('It runs entirely on this machine. Nothing is sent anywhere.')}`);
+  write();
+
+  await stream(`  ${bold('EVERYDAY')}`);
+  write(`  ${rule}`);
+  for (const [command, what] of [
+    ['syndes', 'today at a glance'],
+    ['syndes report 7d', 'the week, in the terminal'],
+    ['syndes habits', 'what is worth changing, with the evidence'],
+    ['syndes verify', 'prove the ledger has not been altered'],
+  ]) {
+    await stream(`  ${cyan(pad(command, 22))} ${grey(what)}`);
+  }
+  write();
+
+  await stream(`  ${bold('THE DASHBOARD')}`);
+  write(`  ${rule}`);
+  await stream(`  ${grey('start')}   ${cyan('syndes dashboard')}   ${grey(`opens your browser on 127.0.0.1:${port}`)}`);
+  await stream(`  ${grey('stop')}    ${cyan('ctrl-c')}             ${grey('in the terminal running it')}`);
+  await stream(`  ${grey('busy?')}   ${cyan('syndes dashboard --port=' + (port + 1))}`);
+  write();
+  await stream(`  ${grey('It also shuts itself down after an hour idle, so a forgotten tab')}`);
+  await stream(`  ${grey('is never left listening. No password — the link carries a one-time')}`);
+  await stream(`  ${grey('key. Want a lock? ')}${cyan('syndes lock system')}${grey(' asks Touch ID.')}`);
+  write();
+
+  await stream(`  ${bold('WORTH KNOWING')}`);
+  write(`  ${rule}`);
+  for (const line of [
+    [`Secrets are scrubbed ${bold('before')} anything is written.`, 'syndes config privacy'],
+    ['Pause and resume tracking whenever you like.', 'syndes off  /  syndes on'],
+    ['Other agents are followed too, no setup needed.', 'syndes sources'],
+    ['Something looks wrong? This says what and why.', 'syndes doctor'],
+    ['Removing it keeps your history unless you say otherwise.', 'syndes uninstall --purge'],
+  ]) {
+    await stream(`  ${grey('·')} ${line[0]}`);
+    await stream(`    ${cyan(line[1])}`);
+  }
+
+  write();
+  write(grey(`  Ledger: ${displayPath(dataDir)}`));
+  write();
+}

package/src/doctor.mjs

@@ -0,0 +1,153 @@
+/**
+ * `syndes doctor` — what is wired, what actually works, what does not.
+ *
+ * Every check either passes, fails with the command that fixes it, or reports
+ * "not applicable here" — never a green tick it did not earn. On Windows it says
+ * plainly that 0600 did not apply, because a security claim that is false on a
+ * third of installs is worse than no claim.
+ */
+
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  installDir, installedHookScript, packageRoot, isInstalledCopy, dataDir,
+  chainKeyFile, displayPath, settingsFile,
+} from '../runtime/paths.mjs';
+import { platformName, isSupportedPlatform, honoursFileModes } from '../runtime/platform.mjs';
+import { installedEvents, HOOK_EVENTS, hookCommand } from './settings.mjs';
+import { loadKey } from '../ledger/keys.mjs';
+import { verify } from '../ledger/verify.mjs';
+import { height } from '../ledger/read.mjs';
+import { usage } from '../ledger/retention.mjs';
+import { pendingCount } from '../runtime/spool.mjs';
+import { isHeld } from '../runtime/lock.mjs';
+import { describe as describeAuth } from '../dashboard/auth.mjs';
+import { probe } from '../notify/index.mjs';
+import { readJson, loadConfig } from '../runtime/config.mjs';
+import { configFile } from '../runtime/paths.mjs';
+
+function versionOf(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')).version;
+  } catch {
+    return null;
+  }
+}
+
+const pass = (name, detail) => ({ name, ok: true, detail });
+const fail = (name, detail, fix) => ({ name, ok: false, detail, fix });
+const note = (name, detail) => ({ name, ok: null, detail });
+
+export async function diagnose({ deep = false } = {}) {
+  const checks = [];
+
+  checks.push(isSupportedPlatform
+    ? pass('platform', `${platformName}, Node ${process.version}`)
+    : fail('platform', `${platformName} is not supported`, 'macOS, Windows or Linux only'));
+
+  // ── Installation ──────────────────────────────────────────────────────────
+  const { events, commands, error } = installedEvents();
+  if (error) {
+    checks.push(fail('settings.json', `does not parse: ${error}`, `fix ${displayPath(settingsFile)} by hand`));
+  } else if (!events.length) {
+    checks.push(fail('hooks', 'no syndes hooks are wired', 'syndes install'));
+  } else {
+    const missing = HOOK_EVENTS.filter((event) => !events.includes(event));
+    checks.push(missing.length
+      ? fail('hooks', `wired on ${events.length}/${HOOK_EVENTS.length} events, missing ${missing.join(', ')}`, 'syndes install')
+      : pass('hooks', `all ${events.length} events wired`));
+  }
+
+  checks.push(existsSync(installedHookScript)
+    ? pass('hook script', displayPath(installedHookScript))
+    : fail('hook script', `missing at ${displayPath(installedHookScript)}`, 'syndes install'));
+
+  // Upgrading the npm package replaces the binary but NOT the copy the hooks
+  // point at, so the two can silently diverge and the user keeps running old
+  // collection code against a new CLI.
+  const running = versionOf(join(packageRoot, 'package.json'));
+  const installed = versionOf(join(installDir, 'package.json'));
+  if (running && installed) {
+    checks.push(running === installed
+      ? pass('installed version', installed)
+      : fail('installed version', `hooks run ${installed}, this CLI is ${running}`, 'syndes install'));
+  }
+
+  // The nvm trap: settings.json holds an absolute path to the node that ran the
+  // install. Switching or removing that Node version silently breaks every hook.
+  const nodePath = commands[0] ? /^"([^"]+)"/.exec(commands[0])?.[1] : null;
+  if (nodePath) {
+    checks.push(existsSync(nodePath)
+      ? pass('node path', displayPath(nodePath))
+      : fail('node path', `${displayPath(nodePath)} no longer exists — every hook is failing`, 'syndes install --repair'));
+  }
+
+  if (!isInstalledCopy && commands.length) {
+    checks.push(note('running copy', `you are running ${displayPath(packageRoot)}, hooks point at ${displayPath(installDir)}`));
+  }
+
+  // ── The ledger ────────────────────────────────────────────────────────────
+  const key = loadKey();
+  if (!key) {
+    checks.push(fail('chain key', 'no key at ' + displayPath(chainKeyFile), 'syndes install'));
+  } else if (!honoursFileModes) {
+    checks.push(note('chain key', `${key.keyId} — file modes do not apply on ${platformName}, so 0600 was not enforced`));
+  } else {
+    const mode = statSync(chainKeyFile).mode & 0o777;
+    checks.push(mode === 0o600
+      ? pass('chain key', `${key.keyId}, mode 0600`)
+      : fail('chain key', `${key.keyId}, mode ${mode.toString(8)} — readable by others`, `chmod 600 ${displayPath(chainKeyFile)}`));
+  }
+
+  const { seq, days } = height();
+  const { bytes } = usage();
+  checks.push(seq < 0
+    ? note('ledger', 'empty — nothing recorded yet')
+    : pass('ledger', `${seq + 1} records across ${days} day${days === 1 ? '' : 's'}, ${Math.round(bytes / 1024)}KB`));
+
+  if (seq >= 0) {
+    const result = await verify({ full: deep });
+    checks.push(result.ok
+      ? pass('chain', `verified${deep ? ' with seals' : ''} to seq ${result.tip?.seq}`)
+      : fail('chain', `${result.problems.length} problem(s), first: ${result.firstBad.type} at seq ${result.firstBad.seq}`, 'syndes verify --full'));
+  }
+
+  // ── The pipeline ──────────────────────────────────────────────────────────
+  const pending = pendingCount();
+  // A spool that keeps growing means hooks are writing and no worker is draining.
+  checks.push(pending > 200
+    ? fail('spool', `${pending} unprocessed events — the worker is not draining`, 'syndes drain')
+    : pass('spool', pending ? `${pending} pending` : 'empty'));
+
+  checks.push(isHeld() ? note('writer lock', 'held — a worker is running right now') : pass('writer lock', 'free'));
+
+  // ── Interfaces ────────────────────────────────────────────────────────────
+  const notifications = await probe();
+  checks.push(notifications.available
+    ? pass('notifications', notifications.channel)
+    : note('notifications', `no channel on this ${notifications.platform} — the terminal card still works`));
+
+  const lock = describeAuth();
+  checks.push(pass('dashboard lock', lock.mode === 'open'
+    ? 'open — the launch link from `syndes dashboard` is the key'
+    : lock.mode === 'system'
+      ? `system (${lock.system.method})`
+      : 'PIN'));
+  if (lock.mode !== 'system' && lock.system.available) {
+    checks.push(note('system unlock', `${lock.system.method} is available here — syndes lock system`));
+  }
+
+  const config = readJson(configFile);
+  if (config.exists && config.error) {
+    checks.push(fail('config', `syndes.json does not parse: ${config.error}`, 'fix or delete it; defaults will be used'));
+  } else {
+    checks.push(pass('config', `privacy=${loadConfig().privacy}, coach=${loadConfig().coach.enabled ? 'on' : 'off'}`));
+  }
+
+  return {
+    checks,
+    failures: checks.filter((check) => check.ok === false).length,
+    dataDir: displayPath(dataDir),
+    expectedCommand: hookCommand(),
+  };
+}

package/src/export.mjs

@@ -0,0 +1,68 @@
+/**
+ * Streamed export to json, ndjson or csv.
+ *
+ * Streamed rather than buffered: a year of records must not have to fit in
+ * memory to leave the building. `--verify` emits the chain proof alongside so an
+ * exported ledger stays checkable outside this tool — an export that cannot be
+ * verified is just a text file.
+ */
+
+import { createWriteStream } from 'node:fs';
+import { readRange } from '../ledger/read.mjs';
+import { verify } from '../ledger/verify.mjs';
+import { listSeals, readSeal } from '../ledger/segments.mjs';
+import { rangeFor } from '../analytics/ranges.mjs';
+
+export async function exportLedger({ format = 'ndjson', range = 'all', out = null, withProof = false } = {}) {
+  const window = rangeFor(range);
+  const stream = out ? createWriteStream(out) : process.stdout;
+  const push = (text) => new Promise((resolve) => {
+    if (stream.write(text)) resolve();
+    else stream.once('drain', resolve);
+  });
+
+  let count = 0;
+
+  if (format === 'csv') {
+    await push('seq,ts,iso,kind,session,project,data\n');
+    for await (const record of readRange(window.from, window.to)) {
+      count += 1;
+      await push([
+        record.seq, record.ts, new Date(record.ts).toISOString(), record.kind,
+        record.session ?? '', record.project ?? '', quote(JSON.stringify(record.data ?? {})),
+      ].join(',') + '\n');
+    }
+  } else if (format === 'json') {
+    await push('{"records":[');
+    let first = true;
+    for await (const record of readRange(window.from, window.to)) {
+      count += 1;
+      await push((first ? '' : ',') + JSON.stringify(record));
+      first = false;
+    }
+    await push(']');
+    if (withProof) await push(`,"proof":${JSON.stringify(await proof())}`);
+    await push('}');
+  } else {
+    for await (const record of readRange(window.from, window.to)) {
+      count += 1;
+      await push(`${JSON.stringify(record)}\n`);
+    }
+    if (withProof) await push(`${JSON.stringify({ proof: await proof() })}\n`);
+  }
+
+  if (out) await new Promise((resolve) => stream.end(resolve));
+  return { count, format, range: window.label, out };
+}
+
+async function proof() {
+  return {
+    verified: await verify({ full: true }),
+    seals: listSeals().map((day) => readSeal(day)).filter(Boolean),
+    exportedAt: new Date().toISOString(),
+  };
+}
+
+function quote(value) {
+  return `"${String(value).replace(/"/g, '""')}"`;
+}