syndes 0.1.0

package/collect/tail.mjs

@@ -0,0 +1,126 @@
+/**
+ * Following other agents' session files.
+ *
+ * Agents without a hook API cannot tell us what they did, so we read what they
+ * write down. Each tail target keeps a byte cursor, and only the bytes appended
+ * since last time are parsed — reading a whole transcript on every poll would
+ * be quadratic over a long session.
+ *
+ * Two things this must never do: re-emit a line it has already recorded, and
+ * advance past a line that is only half written. Both are handled by never
+ * moving the cursor past the last complete newline.
+ */
+
+import { openSync, readSync, fstatSync, closeSync, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { dirname, basename } from 'node:path';
+import { join } from 'node:path';
+import { stateDir } from '../runtime/paths.mjs';
+import { parseLine } from '../runtime/jsonl.mjs';
+import { loadConfig } from '../runtime/config.mjs';
+import { projectFor } from './projects.mjs';
+import { tailTargets, classify } from '../adapters/index.mjs';
+import { debug } from '../runtime/log.mjs';
+
+const CURSORS = join(stateDir, 'tail-cursors.json');
+/** Cap one poll so a huge backlog cannot stall the worker. */
+const MAX_BYTES = 4 * 1024 * 1024;
+
+function loadCursors() {
+  try {
+    return JSON.parse(readFileSync(CURSORS, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveCursors(cursors) {
+  try {
+    mkdirSync(dirname(CURSORS), { recursive: true });
+    const staging = `${CURSORS}.tmp`;
+    writeFileSync(staging, `${JSON.stringify(cursors)}\n`);
+    renameSync(staging, CURSORS);
+  } catch (error) {
+    debug('tail cursor save failed', error.message);
+  }
+}
+
+/**
+ * Poll every tail source once.
+ *
+ * @param {{firstRunSkipsHistory?: boolean}} options
+ *   On the very first sighting of a file we jump to its end rather than
+ *   importing the whole thing. Back-filling months of somebody's history the
+ *   moment they install would make the first dashboard a wall of records they
+ *   never asked us to keep.
+ * @returns {{drafts: object[], files: number, lines: number}}
+ */
+export function pollTails({ firstRunSkipsHistory = true } = {}) {
+  const cursors = loadCursors();
+  const config = loadConfig();
+  const drafts = [];
+  let files = 0;
+  let lines = 0;
+
+  for (const { source, file } of tailTargets()) {
+    if (!existsSync(file)) continue;
+    files += 1;
+
+    let handle;
+    try {
+      handle = openSync(file, 'r');
+      const size = fstatSync(handle).size;
+      const known = cursors[file];
+
+      if (known === undefined) {
+        cursors[file] = firstRunSkipsHistory ? size : 0;
+        if (firstRunSkipsHistory) continue;
+      }
+
+      // Shorter than our cursor means the file was rotated or replaced.
+      let from = cursors[file] > size ? 0 : cursors[file];
+      if (from === size) continue;
+
+      const capped = Math.min(size - from, MAX_BYTES);
+      const buffer = Buffer.alloc(capped);
+      readSync(handle, buffer, 0, capped, from);
+
+      const text = buffer.toString('utf8');
+      const end = text.lastIndexOf('\n');
+      if (end === -1) continue; // nothing complete yet
+
+      const session = `${source}:${basename(file).replace(/\.jsonl$/, '')}`;
+      const ctx = { config, project: projectFor(process.cwd()), session };
+
+      for (const raw of text.slice(0, end).split('\n')) {
+        const line = parseLine(raw);
+        if (!line) continue;
+        lines += 1;
+        try {
+          drafts.push(...classify(source, { line, file, session, at: Date.now() }, ctx));
+        } catch (error) {
+          // One unrecognised line must never abort the whole poll.
+          debug('tail classify failed', source, error.message);
+        }
+      }
+
+      cursors[file] = from + Buffer.byteLength(text.slice(0, end + 1));
+    } catch (error) {
+      debug('tail read failed', file, error.message);
+    } finally {
+      if (handle !== undefined) {
+        try { closeSync(handle); } catch { /* already closed */ }
+      }
+    }
+  }
+
+  saveCursors(cursors);
+  drafts.sort((a, b) => a.ts - b.ts);
+  return { drafts, files, lines };
+}
+
+/** Forget every cursor, so the next poll re-imports from the top. */
+export function resetCursors() {
+  saveCursors({});
+}
+
+export { CURSORS };

package/collect/tools.mjs

@@ -0,0 +1,121 @@
+/**
+ * Tool taxonomy, and the normalisation the metrics depend on.
+ *
+ * Grouping into families is what makes "did you search with Grep or with `grep`
+ * through Bash" answerable — one of the strongest signals of whether someone has
+ * learned the tool they are using.
+ *
+ * Only one field per tool is kept: the path, the command's head, the pattern,
+ * the subagent type. Never the whole tool_input — that is the transcript's job
+ * and it is enormous.
+ */
+
+export const FAMILY = {
+  read: 'read',
+  search: 'search',
+  edit: 'edit',
+  execute: 'execute',
+  delegate: 'delegate',
+  web: 'web',
+  plan: 'plan',
+  mcp: 'mcp',
+  other: 'other',
+};
+
+const BY_NAME = {
+  Read: FAMILY.read, NotebookRead: FAMILY.read,
+  Glob: FAMILY.search, Grep: FAMILY.search, LS: FAMILY.search,
+  Edit: FAMILY.edit, Write: FAMILY.edit, MultiEdit: FAMILY.edit, NotebookEdit: FAMILY.edit,
+  Bash: FAMILY.execute, BashOutput: FAMILY.execute, KillShell: FAMILY.execute,
+  Task: FAMILY.delegate, Agent: FAMILY.delegate, Workflow: FAMILY.delegate,
+  WebFetch: FAMILY.web, WebSearch: FAMILY.web,
+  ExitPlanMode: FAMILY.plan, EnterPlanMode: FAMILY.plan, TodoWrite: FAMILY.plan, Skill: FAMILY.plan,
+};
+
+/** Tools whose use means a file changed on disk. */
+const WRITERS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+export function familyOf(toolName) {
+  if (!toolName) return FAMILY.other;
+  if (toolName.startsWith('mcp__')) return FAMILY.mcp;
+  return BY_NAME[toolName] ?? FAMILY.other;
+}
+
+export function isWrite(toolName) {
+  return WRITERS.has(toolName);
+}
+
+export function isRead(toolName) {
+  return toolName === 'Read' || toolName === 'NotebookRead';
+}
+
+/**
+ * The one identifying detail worth keeping for a tool call.
+ *
+ * @returns {{target: string|null, detail: string|null}}
+ */
+export function summarise(toolName, toolInput) {
+  const input = toolInput ?? {};
+
+  if (isRead(toolName) || isWrite(toolName)) {
+    return { target: input.file_path ?? input.notebook_path ?? null, detail: null };
+  }
+  if (toolName === 'Bash') {
+    const command = typeof input.command === 'string' ? input.command : '';
+    return { target: headOf(command), detail: command.slice(0, 200) };
+  }
+  if (toolName === 'Grep' || toolName === 'Glob') {
+    return { target: input.pattern ?? null, detail: input.path ?? null };
+  }
+  if (toolName === 'Task' || toolName === 'Agent') {
+    return { target: input.subagent_type ?? 'general-purpose', detail: input.description ?? null };
+  }
+  if (toolName === 'WebFetch') {
+    return { target: hostOf(input.url), detail: null };
+  }
+  if (toolName === 'WebSearch') {
+    return { target: null, detail: typeof input.query === 'string' ? input.query.slice(0, 120) : null };
+  }
+  if (toolName === 'Skill') {
+    return { target: input.skill ?? null, detail: null };
+  }
+  return { target: null, detail: null };
+}
+
+/** The program a shell command actually runs, past env assignments and sudo. */
+export function headOf(command) {
+  if (typeof command !== 'string') return null;
+  const words = command.trim().split(/\s+/);
+  let index = 0;
+  while (index < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index]) || words[index] === 'sudo')) index += 1;
+  const head = words[index] ?? null;
+  return head ? head.split('/').pop().slice(0, 40) : null;
+}
+
+function hostOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a Bash command is doing a search tool's job.
+ *
+ * Not a style opinion: a `grep -r` through Bash returns raw bytes into context,
+ * where Grep returns a structured result. The cost difference is measurable and
+ * it is what the tool-discipline pillar scores.
+ */
+export function isSearchThroughBash(command) {
+  const head = headOf(command);
+  return ['grep', 'rg', 'ag', 'ack', 'find', 'fd'].includes(head ?? '');
+}
+
+/** Whether a Bash command is a verification step — the feedback-loop signal. */
+export function isVerification(command) {
+  if (typeof command !== 'string') return false;
+  return /\b(npm|pnpm|yarn|bun)\s+(run\s+)?(test|lint|typecheck|build|check)\b/.test(command) ||
+    /\b(pytest|jest|vitest|mocha|go\s+test|cargo\s+(test|check|build)|tsc|mvn|gradle|make)\b/.test(command) ||
+    /\bnode\s+--test\b/.test(command);
+}

package/collect/transcript.mjs

@@ -0,0 +1,128 @@
+/**
+ * Incremental transcript tail → token usage, model, cache hits, turn shape.
+ *
+ * Tokens, cost and cache efficiency are not in the hook payload; they are in the
+ * session transcript JSONL that `transcript_path` points at. Reading it whole on
+ * every event would be quadratic over a long session, so a byte offset per
+ * session is kept and only the new tail is parsed.
+ *
+ * The format is Claude Code's, not ours. Parse defensively, tolerate unknown
+ * shapes, and never let one unexpected line abort the drain.
+ *
+ * Observed shape (Claude Code 2.1.x):
+ *   {type:'assistant', timestamp, sessionId, cwd, gitBranch, requestId,
+ *    message:{ id, model, usage:{ input_tokens, output_tokens,
+ *      cache_creation_input_tokens, cache_read_input_tokens,
+ *      output_tokens_details:{ thinking_tokens } }, content:[ {type:…} ] }}
+ *   {type:'user', message:{ content: string | [{type:'tool_result', is_error}] }}
+ */
+
+import { openSync, readSync, fstatSync, closeSync, existsSync } from 'node:fs';
+import { parseLine } from '../runtime/jsonl.mjs';
+import { debug } from '../runtime/log.mjs';
+
+/** Cap one drain's read so a huge transcript cannot stall the worker. */
+const MAX_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Read everything appended since the last call.
+ *
+ * @returns {{samples: object[], errors: number, results: number, cursor: number, model: string|null}}
+ */
+export function sync(path, cursor = 0) {
+  const empty = { samples: [], errors: 0, results: 0, cursor, model: null };
+  if (!path || !existsSync(path)) return empty;
+
+  let handle;
+  try {
+    handle = openSync(path, 'r');
+    const size = fstatSync(handle).size;
+
+    // A file shorter than our cursor was rotated or replaced. Start over rather
+    // than reading from a meaningless offset.
+    let from = cursor > size ? 0 : cursor;
+    if (size === from) return { ...empty, cursor: size };
+
+    const capped = Math.min(size - from, MAX_BYTES);
+    const buffer = Buffer.alloc(capped);
+    readSync(handle, buffer, 0, capped, from);
+
+    const text = buffer.toString('utf8');
+    // Stop at the last newline: a trailing partial line is re-read next time.
+    const end = text.lastIndexOf('\n');
+    if (end === -1) return { ...empty, cursor: from };
+
+    const parsed = scan(text.slice(0, end));
+    return { ...parsed, cursor: from + Buffer.byteLength(text.slice(0, end + 1)) };
+  } catch (error) {
+    debug('transcript sync failed', path, error.message);
+    return empty;
+  } finally {
+    if (handle !== undefined) {
+      try { closeSync(handle); } catch { /* already closed */ }
+    }
+  }
+}
+
+function scan(text) {
+  const samples = [];
+  let errors = 0;
+  let results = 0;
+  let model = null;
+
+  for (const line of text.split('\n')) {
+    const entry = parseLine(line);
+    if (!entry) continue;
+
+    if (entry.type === 'assistant') {
+      const sample = sampleFrom(entry);
+      if (sample) {
+        samples.push(sample);
+        model = sample.model ?? model;
+      }
+      continue;
+    }
+
+    if (entry.type === 'user') {
+      const content = entry.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (block?.type !== 'tool_result') continue;
+        results += 1;
+        // is_error is the authoritative failure signal. The PostToolUse payload
+        // does not carry one, so tool error rate is measured here, not there.
+        if (block.is_error === true) errors += 1;
+      }
+    }
+  }
+
+  return { samples, errors, results, model };
+}
+
+function sampleFrom(entry) {
+  const message = entry.message;
+  const usage = message?.usage;
+  if (!usage) return null;
+
+  const content = Array.isArray(message.content) ? message.content : [];
+  const blocks = { text: 0, thinking: 0, tool_use: 0 };
+  for (const block of content) {
+    if (block?.type in blocks) blocks[block.type] += 1;
+  }
+
+  return {
+    id: message.id ?? entry.uuid ?? null,
+    ts: entry.timestamp ? Date.parse(entry.timestamp) : null,
+    model: message.model ?? null,
+    input: usage.input_tokens ?? 0,
+    output: usage.output_tokens ?? 0,
+    cacheRead: usage.cache_read_input_tokens ?? 0,
+    cacheWrite: usage.cache_creation_input_tokens ?? 0,
+    thinking: usage.output_tokens_details?.thinking_tokens ?? 0,
+    // Tool calls in ONE assistant message: the batching signal. Claude issuing
+    // three independent calls in one turn is one round-trip; three turns is three.
+    toolUses: blocks.tool_use,
+    sidechain: entry.isSidechain === true, // a subagent's turn, not the main thread
+    branch: entry.gitBranch ?? null,
+  };
+}

package/dashboard/api/index.mjs

@@ -0,0 +1,296 @@
+/**
+ * The API surface.
+ *
+ * Every handler returns plain data from analytics/index.mjs and formats nothing.
+ * Formatting is the browser's job; duplicating it server-side is how two views
+ * of the same number drift apart.
+ *
+ * Handlers receive { req, res, url, body, port } and return
+ * { status?, data, headers? } — or write to res themselves for streams.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as analytics from '../../analytics/index.mjs';
+import { verify } from '../../ledger/verify.mjs';
+import { height, readRange, tail } from '../../ledger/read.mjs';
+import { listDays, listSeals, readSeal } from '../../ledger/segments.mjs';
+import { usage } from '../../ledger/retention.mjs';
+import { evaluate } from '../../practices/engine.mjs';
+import * as budget from '../../practices/budget.mjs';
+import { loadConfig, saveConfig, rawConfig, setPath, resetCache } from '../../runtime/config.mjs';
+import { packageRoot, displayPath, dataDir } from '../../runtime/paths.mjs';
+import { probe } from '../../notify/index.mjs';
+import {
+  issueToken, describe as describeAuth, mode as authMode,
+  verifyPin, verifySystem, setMode, systemAvailable, MODES,
+} from '../auth.mjs';
+import { sessionCookie } from '../security.mjs';
+import { pendingCount } from '../../runtime/spool.mjs';
+import { isInstalled, installedEvents } from '../../src/settings.mjs';
+
+// ── Session ─────────────────────────────────────────────────────────────────
+
+/** What lock is on the door, so the unlock screen can render the right thing. */
+export async function unlockOptions() {
+  return { data: describeAuth() };
+}
+
+/**
+ * Perform the unlock.
+ *
+ * In `open` mode there is nothing to check — reaching this port already required
+ * a loopback Host and, for the first load, the launch token from the CLI.
+ */
+export async function unlock({ body }) {
+  const current = authMode();
+
+  if (current === 'open') {
+    return { data: { ok: true, mode: current }, headers: { 'Set-Cookie': sessionCookie(issueToken()) } };
+  }
+
+  if (current === 'system') {
+    const result = await verifySystem();
+    if (!result.ok) return { status: 401, data: { error: result.reason ?? 'not authenticated' } };
+    return { data: { ok: true, mode: current }, headers: { 'Set-Cookie': sessionCookie(issueToken()) } };
+  }
+
+  const result = verifyPin(body?.pin);
+  if (!result.ok) return { status: 401, data: { error: 'unlock failed', retryAfterMs: result.retryAfterMs } };
+  return { data: { ok: true, mode: current }, headers: { 'Set-Cookie': sessionCookie(issueToken()) } };
+}
+
+export async function logout() {
+  return { data: { ok: true }, headers: { 'Set-Cookie': sessionCookie('', { clear: true }) } };
+}
+
+/** Public: the login page needs to know whether there is a password at all. */
+export async function status() {
+  return {
+    data: {
+      version: version(),
+      auth: describeAuth(),
+      installed: isInstalled(),
+      ledger: height(),
+    },
+  };
+}
+
+// ── Metrics ─────────────────────────────────────────────────────────────────
+
+export async function overview({ url }) {
+  return { data: await analytics.overview(url.searchParams.get('range') ?? '7d') };
+}
+
+export async function sessions({ url }) {
+  return { data: await analytics.sessions(url.searchParams.get('range') ?? '7d') };
+}
+
+export async function sessionDetail({ url }) {
+  const id = url.searchParams.get('id');
+  if (!id) return { status: 400, data: { error: 'id is required' } };
+  return { data: { id, events: await analytics.sessionDetail(id) } };
+}
+
+export async function tools({ url }) {
+  const range = analytics.rangeFor(url.searchParams.get('range') ?? '7d');
+  const { merged } = await analytics.summarise(range);
+  return { data: { range, tools: merged.tools, tokens: merged.tokens, rework: merged.rework, friction: merged.friction } };
+}
+
+export async function projects({ url }) {
+  return { data: await analytics.byProject(url.searchParams.get('range') ?? '30d') };
+}
+
+export async function timeline({ url }) {
+  const range = analytics.rangeFor(url.searchParams.get('range') ?? '7d');
+  const limit = Math.min(Number(url.searchParams.get('limit') ?? 3000), 20_000);
+
+  // Downsampled server-side. The browser must never receive a million records
+  // to draw a chart that is 900 pixels wide.
+  const events = [];
+  for await (const record of readRange(range.from, range.to)) {
+    events.push({ ts: record.ts, kind: record.kind, session: record.session, project: record.project });
+    if (events.length >= limit) break;
+  }
+  return { data: { range, events, truncated: events.length >= limit } };
+}
+
+// ── Practices ───────────────────────────────────────────────────────────────
+
+export async function practices() {
+  const findings = await evaluate();
+  const state = budget.load();
+  return { data: { findings, muted: state.muted ?? [], dismissed: state.dismissed ?? {}, snoozedUntil: state.snoozedUntil ?? 0 } };
+}
+
+/** The one place the UI writes anything, and it writes coach state only. */
+export async function practiceAction({ body }) {
+  const { action, rule, ms } = body ?? {};
+  let state = budget.load();
+
+  if (action === 'mute') state = budget.mute(state, rule);
+  else if (action === 'unmute') state = budget.unmute(state, rule);
+  else if (action === 'dismiss') state = budget.dismiss(state, rule);
+  else if (action === 'snooze') state = budget.snooze(state, Math.min(Number(ms) || 3_600_000, 7 * 86_400_000));
+  else return { status: 400, data: { error: 'unknown action' } };
+
+  budget.save(state);
+  return { data: { ok: true, muted: state.muted ?? [], snoozedUntil: state.snoozedUntil ?? 0 } };
+}
+
+// ── The chain itself ────────────────────────────────────────────────────────
+
+/**
+ * Paged raw records.
+ *
+ * The dashboard must be able to show the chain, or "immutable" is a claim the
+ * user has to take on faith — and a claim taken on faith is a marketing line.
+ */
+export async function ledger({ url }) {
+  const limit = Math.min(Number(url.searchParams.get('limit') ?? 100), 1000);
+  const kind = url.searchParams.get('kind');
+  const session = url.searchParams.get('session');
+  const range = url.searchParams.get('range');
+
+  let records;
+  if (range || kind || session) {
+    const window = analytics.rangeFor(range ?? '30d');
+    records = [];
+    for await (const record of readRange(window.from, window.to)) {
+      if (kind && record.kind !== kind) continue;
+      if (session && record.session !== session) continue;
+      records.push(record);
+    }
+    records = records.slice(-limit);
+  } else {
+    records = await tail(limit);
+  }
+
+  return {
+    data: {
+      records,
+      height: height(),
+      days: listDays(),
+      seals: listSeals().map((day) => readSeal(day)).filter(Boolean),
+      usage: usage(),
+    },
+  };
+}
+
+export async function verifyChain({ url }) {
+  return { data: await verify({ full: url.searchParams.get('full') === '1' }) };
+}
+
+// ── Settings ────────────────────────────────────────────────────────────────
+
+export async function readConfig() {
+  return {
+    data: {
+      config: loadConfig(),
+      paths: { data: displayPath(dataDir) },
+      notifications: await probe(),
+      hooks: { count: installedEvents().events.length },
+      spoolPending: pendingCount(),
+      auth: { mode: authMode(), modes: MODES, system: systemAvailable() },
+    },
+  };
+}
+
+/** Change the lock. A PIN arrives here in the clear over loopback, which is the
+ *  same trust boundary the whole dashboard already sits behind. */
+export async function setAuthMode({ body }) {
+  try {
+    return { data: { ok: true, mode: setMode(body?.mode, { pin: body?.pin }) } };
+  } catch (error) {
+    return { status: 400, data: { error: error.message } };
+  }
+}
+
+/**
+ * Config writes are allowlisted by key.
+ *
+ * A generic setter would let the UI reach any path in the file, and this server
+ * is reachable from a browser. The allowlist is what keeps a bug in the client
+ * from becoming a way to repoint the tool at someone else's directory.
+ */
+const WRITABLE = new Set([
+  'privacy', 'coach.enabled', 'coach.maxPerDay', 'coach.cooldownHours',
+  'coach.channels.notification', 'coach.channels.terminal', 'coach.channels.digest',
+  'coach.injectContext', 'dashboard.port', 'dashboard.idleTimeoutMinutes',
+  'dashboard.openOnStart', 'retention.days', 'retention.gzipAfterDays',
+  'idleGapMinutes', 'track.tools', 'track.prompts', 'track.permissions',
+  'track.transcript', 'track.git',
+]);
+
+export async function writeConfig({ body }) {
+  const updates = body?.updates;
+  if (!updates || typeof updates !== 'object') return { status: 400, data: { error: 'updates required' } };
+
+  const rejected = Object.keys(updates).filter((key) => !WRITABLE.has(key));
+  if (rejected.length) return { status: 400, data: { error: 'not writable', keys: rejected } };
+
+  const next = rawConfig();
+  for (const [key, value] of Object.entries(updates)) setPath(next, key, value);
+
+  saveConfig(next);
+  resetCache();
+  return { data: { ok: true, config: loadConfig() } };
+}
+
+// ── Export ──────────────────────────────────────────────────────────────────
+
+/**
+ * The user's data, out, whole and streamed.
+ *
+ * A tracker that cannot hand back everything it collected does not deserve the
+ * collection. Streamed rather than buffered so a year of records does not have
+ * to fit in memory to leave the building.
+ */
+export async function exportData({ url, res }) {
+  const format = url.searchParams.get('format') ?? 'ndjson';
+  const range = analytics.rangeFor(url.searchParams.get('range') ?? 'all');
+
+  const types = { ndjson: 'application/x-ndjson', json: 'application/json', csv: 'text/csv' };
+  res.writeHead(200, {
+    'Content-Type': `${types[format] ?? types.ndjson}; charset=utf-8`,
+    'Content-Disposition': `attachment; filename="syndes-${range.days[0]}-to-${range.days.at(-1)}.${format}"`,
+    'Cache-Control': 'no-store',
+  });
+
+  if (format === 'csv') {
+    res.write('seq,ts,iso,kind,session,project,data\n');
+    for await (const record of readRange(range.from, range.to)) {
+      res.write([
+        record.seq, record.ts, new Date(record.ts).toISOString(), record.kind,
+        record.session ?? '', record.project ?? '', csv(JSON.stringify(record.data ?? {})),
+      ].join(',') + '\n');
+    }
+  } else if (format === 'json') {
+    res.write('[');
+    let first = true;
+    for await (const record of readRange(range.from, range.to)) {
+      res.write((first ? '' : ',') + JSON.stringify(record));
+      first = false;
+    }
+    res.write(']');
+  } else {
+    for await (const record of readRange(range.from, range.to)) {
+      res.write(`${JSON.stringify(record)}\n`);
+    }
+  }
+  res.end();
+  return undefined;
+}
+
+function csv(value) {
+  return `"${String(value).replace(/"/g, '""')}"`;
+}
+
+function version() {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+  } catch {
+    return null;
+  }
+}