spectater 0.0.0-stage → 0.2.0

package/src/server.js

@@ -0,0 +1,291 @@
+import { execFile } from 'node:child_process';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { feedback, feedbackMarkdown } from './storage.js';
+import { watchChange } from './watch.js';
+
+const assets = new Map([
+  ['/app.js', ['../web/app.js', 'text/javascript']],
+  ['/theme.js', ['../web/theme.js', 'text/javascript']],
+  ['/style.css', ['../web/style.css', 'text/css']],
+  ['/favicon.svg', ['../web/favicon.svg', 'image/svg+xml']],
+]);
+const shell = await readFile(new URL('../web/index.html', import.meta.url), 'utf8');
+const headers = {
+  'Content-Security-Policy':
+    "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'Referrer-Policy': 'no-referrer',
+  'Cache-Control': 'no-store',
+};
+export const MAX_WAIT_MS = 3_600_000;
+
+async function readJson(request) {
+  let bytes = 0;
+  const chunks = [];
+  for await (const chunk of request) {
+    bytes += chunk.length;
+    if (bytes > 65536) {
+      const error = new Error('Request exceeds 64 KiB.');
+      error.statusCode = 413;
+      throw error;
+    }
+    chunks.push(chunk);
+  }
+  const input = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+  if (!input || typeof input !== 'object' || Array.isArray(input))
+    throw new Error('Expected a JSON object.');
+  return input;
+}
+
+/**
+ * Serves one review to the browser (capability in the URL fragment) and to agent commands
+ * (`/agent/*`, same capability). `onIdle` fires after `idleTimeout` ms with no browser stream
+ * and no waiting agent; `onStop` fires after an agent stop request is answered.
+ */
+export async function startServer(review, options = {}) {
+  const { watch = true, idleTimeout = 0, onIdle = () => {}, onStop = () => {} } = options;
+  const capability = randomBytes(32).toString('hex');
+  const route = `/review/${encodeURIComponent(review.view().change)}`;
+  let origin;
+  let watchStatus = { automatic: false };
+  let watcher,
+    stopping = false,
+    watcherTask = Promise.resolve(),
+    waiter = null,
+    idleTimer;
+  const clients = new Set();
+  const broadcast = (event) => {
+    for (const client of clients) {
+      if (client.destroyed || client.writableLength > 65536) {
+        clients.delete(client);
+        client.destroy();
+      } else client.write(`${JSON.stringify(event)}\n`);
+    }
+  };
+  const touch = () => {
+    clearTimeout(idleTimer);
+    if (!stopping && idleTimeout > 0 && !clients.size && !waiter)
+      idleTimer = setTimeout(onIdle, idleTimeout);
+  };
+  const presence = () => {
+    broadcast({ type: 'presence', listeners: waiter ? 1 : 0 });
+    touch();
+  };
+  const finishWait = (target, result) => {
+    if (!target || waiter !== target) return;
+    waiter = null;
+    clearTimeout(target.timer);
+    if (!target.response.destroyed) target.response.end(JSON.stringify(result));
+    presence();
+  };
+  const deliver = async (target) => {
+    try {
+      const batch = await review.deliver();
+      if (batch) finishWait(target, { status: 'batch', batch });
+      else if (review.state.endedAt) finishWait(target, { status: 'ended' });
+    } catch (error) {
+      finishWait(target, { status: 'error', error: error.message });
+    }
+  };
+  const reportWatch = (event) => {
+    watchStatus = { automatic: event.automatic, watchError: event.error };
+    broadcast(event);
+  };
+  const syncWatcher = () => {
+    watcherTask = watcherTask
+      .then(async () => {
+        if (stopping) return;
+        if (review.state.endedAt) {
+          await watcher?.close();
+          watcher = undefined;
+          reportWatch({ type: 'watch', automatic: false });
+        } else if (!watcher && watch) watcher = await watchChange(review, reportWatch);
+      })
+      .catch((error) => reportWatch({ type: 'watch', automatic: false, error: error.message }));
+    return watcherTask;
+  };
+  const refresh = () => (watcher ? watcher.retry() : review.refresh());
+  const unsubscribe = review.subscribe((event) => {
+    if (['refresh', 'activity', 'lifecycle'].includes(event.type)) broadcast(event);
+    if (event.type === 'lifecycle') {
+      void syncWatcher();
+      // Re-check through deliver so a final Send & End batch reaches the waiter before ended.
+      if (event.ended && waiter) void deliver(waiter);
+    }
+    if (event.type === 'batch' && waiter) void deliver(waiter);
+  });
+
+  const agent = {
+    status: () => ({
+      status: 'active',
+      url,
+      ended: Boolean(review.state.endedAt),
+      listening: Boolean(waiter),
+    }),
+    refresh: async () => ({ status: 'refreshed', revision: (await refresh()).revision }),
+    end: async () => {
+      await review.mutate({ action: 'end', revision: review.state.revision });
+      return { status: 'ended' };
+    },
+    resume: async () => {
+      await review.mutate({ action: 'resume', revision: review.state.revision });
+      return { status: 'resumed' };
+    },
+    reply: async (input) => ({
+      status: 'recorded',
+      ...(await review.recordActivity(input.batch, input)),
+    }),
+    stop: () => {
+      setImmediate(onStop);
+      return { status: 'stopping' };
+    },
+  };
+
+  function wait(input, response) {
+    const timeout = input.timeout ?? 540_000;
+    if (!Number.isInteger(timeout) || timeout < 0 || timeout > MAX_WAIT_MS)
+      throw new Error(`timeout must be 0–${MAX_WAIT_MS} ms.`);
+    if (waiter && !input.takeover) return { status: 'listener_active' };
+    finishWait(waiter, { status: 'listener_replaced' });
+    response.writeHead(200, { ...headers, 'Content-Type': 'application/json; charset=utf-8' });
+    const target = { response };
+    waiter = target;
+    presence();
+    response.once('close', () => finishWait(target, { status: 'disconnected' }));
+    // Queued feedback wins over a zero timeout, so the timer starts after the first delivery check.
+    void deliver(target).then(() => {
+      if (waiter === target)
+        target.timer = setTimeout(() => finishWait(target, { status: 'timeout' }), timeout);
+    });
+  }
+
+  const server = http.createServer(async (request, response) => {
+    const send = (code, data, type = 'application/json') => {
+      response.writeHead(code, { ...headers, 'Content-Type': `${type}; charset=utf-8` });
+      response.end(type === 'application/json' ? JSON.stringify(data) : data);
+    };
+    try {
+      if (request.headers.host !== new URL(origin).host)
+        return send(403, { error: 'Invalid Host.' });
+      if (request.headers.origin && request.headers.origin !== origin)
+        return send(403, { error: 'Foreign origin refused.' });
+      if (request.headers['sec-fetch-site'] === 'cross-site')
+        return send(403, { error: 'Cross-site request refused.' });
+      const url = new URL(request.url, origin);
+      if (url.search) return send(404, { error: 'Unknown route.' });
+      if (request.method === 'GET' && url.pathname === route) return send(200, shell, 'text/html');
+      if (request.method === 'GET' && assets.has(url.pathname)) {
+        const [file, type] = assets.get(url.pathname);
+        return send(
+          200,
+          await readFile(fileURLToPath(new URL(file, import.meta.url)), 'utf8'),
+          type,
+        );
+      }
+      const token = request.headers.authorization || '';
+      const expected = `Bearer ${capability}`;
+      if (
+        token.length !== expected.length ||
+        !timingSafeEqual(Buffer.from(token), Buffer.from(expected))
+      )
+        return send(403, { error: 'Review capability required. Reopen the printed URL.' });
+      if (request.method === 'GET' && url.pathname === `${route}/events`) {
+        response.writeHead(200, {
+          ...headers,
+          'Content-Type': 'application/x-ndjson; charset=utf-8',
+        });
+        response.write(
+          `${JSON.stringify({ type: 'ready', revision: review.state.revision, listeners: waiter ? 1 : 0, ...watchStatus })}\n`,
+        );
+        clients.add(response);
+        touch();
+        response.once('close', () => {
+          clients.delete(response);
+          touch();
+        });
+        return;
+      }
+      if (request.method === 'GET' && url.pathname === `${route}/state`)
+        return send(200, { ...review.view(), ...watchStatus });
+      const comparison =
+        url.pathname.startsWith(`${route}/changes/`) &&
+        url.pathname.slice(`${route}/changes/`.length);
+      if (request.method === 'GET' && comparison && /^[a-f0-9]{24}$/.test(comparison))
+        return send(200, await review.compare(comparison));
+      const batchMatch =
+        url.pathname.startsWith(`${route}/batch/`) && url.pathname.slice(`${route}/batch/`.length);
+      if (request.method === 'GET' && batchMatch && /^[a-f0-9-]{36}$/.test(batchMatch))
+        return send(200, { markdown: feedbackMarkdown(feedback(review.state, batchMatch)) });
+      const operation = url.pathname.startsWith('/agent/') && url.pathname.slice('/agent/'.length);
+      const browserMutation = [`${route}/refresh`, `${route}/action`].includes(url.pathname);
+      if (
+        request.method !== 'POST' ||
+        !(browserMutation || operation === 'wait' || Object.hasOwn(agent, operation))
+      )
+        return send(404, { error: 'Unknown route.' });
+      if (
+        (browserMutation && request.headers.origin !== origin) ||
+        request.headers['content-type'] !== 'application/json'
+      )
+        return send(403, { error: 'Mutation requires this review origin and JSON.' });
+      const input = await readJson(request);
+      if (operation === 'wait') {
+        const refused = wait(input, response);
+        if (refused) send(200, refused);
+        return;
+      }
+      if (operation) return send(200, await agent[operation](input));
+      if (url.pathname.endsWith('/refresh'))
+        return send(200, { ...(await refresh()), ...watchStatus });
+      return send(200, await review.mutate(input));
+    } catch (error) {
+      if (response.headersSent) return;
+      send(error.statusCode || (/conflict/i.test(error.message) ? 409 : 400), {
+        error: error.message,
+      });
+    }
+  });
+  server.requestTimeout = 20000;
+  server.headersTimeout = 10000;
+  server.maxConnections = 32;
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  origin = `http://127.0.0.1:${server.address().port}`;
+  const url = `${origin}${route}#${capability}`;
+  await syncWatcher();
+  touch();
+  return {
+    url,
+    origin,
+    route,
+    async close() {
+      stopping = true;
+      clearTimeout(idleTimer);
+      unsubscribe();
+      finishWait(waiter, { status: 'stopped' });
+      await new Promise((resolve) => setImmediate(resolve));
+      await watcherTask;
+      await watcher?.close();
+      for (const client of clients) client.end();
+      clients.clear();
+      server.closeAllConnections();
+      await new Promise((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+      await review.close();
+    },
+  };
+}
+
+const openers = { darwin: 'open', linux: 'xdg-open' };
+export async function openBrowser(url, run = promisify(execFile), platform = process.platform) {
+  if (!openers[platform]) throw new Error('Automatic opening supports macOS and Linux only.');
+  await run(openers[platform], [url], { timeout: 10000, maxBuffer: 65536 });
+}

package/src/storage.js

@@ -0,0 +1,381 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, link, lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { hash, within } from './discovery.js';
+import { readFileLimited, readLimited } from './files.js';
+
+export function stateDirectory() {
+  if (process.env.SPECTATER_STATE_DIR) return path.resolve(process.env.SPECTATER_STATE_DIR);
+  if (process.platform === 'darwin')
+    return path.join(os.homedir(), 'Library', 'Application Support', 'SpecTater');
+  return path.join(
+    process.env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'),
+    'spectater',
+  );
+}
+
+export async function privateDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const stat = await lstat(directory);
+  if (
+    !stat.isDirectory() ||
+    stat.isSymbolicLink() ||
+    (process.getuid && stat.uid !== process.getuid())
+  )
+    throw new Error('Review storage must be an owned private directory.');
+  if (process.platform === 'win32')
+    throw new Error(
+      'Private Windows storage is not verified; this release supports macOS/Linux permissions only.',
+    );
+  if ((await realpath(directory)) !== path.resolve(directory))
+    throw new Error('Review storage must not use symlinked directories.');
+  await chmod(directory, 0o700);
+}
+
+function validate(state, id) {
+  if (
+    state?.formatVersion !== 1 ||
+    state.reviewId !== id ||
+    !Number.isSafeInteger(state.revision) ||
+    state.revision < 0 ||
+    !Array.isArray(state.comments) ||
+    !Array.isArray(state.batches) ||
+    !state.snapshots ||
+    !Array.isArray(state.documentIds) ||
+    typeof state.root !== 'string' ||
+    typeof state.changeRoot !== 'string' ||
+    typeof state.schemaName !== 'string'
+  )
+    throw new Error('Invalid or unsupported review state; preserve it and restore a valid copy.');
+  if (
+    state.endedAt !== undefined &&
+    (typeof state.endedAt !== 'string' || !Number.isFinite(Date.parse(state.endedAt)))
+  )
+    throw new Error('Corrupt review completion metadata.');
+  if (
+    state.endRequestedAt !== undefined &&
+    (typeof state.endRequestedAt !== 'string' || !Number.isFinite(Date.parse(state.endRequestedAt)))
+  )
+    throw new Error('Corrupt review completion metadata.');
+  for (const [key, snapshot] of Object.entries(state.snapshots)) {
+    if (
+      typeof snapshot.source !== 'string' ||
+      snapshot.hash !== hash(Buffer.from(snapshot.source)) ||
+      key !== snapshot.hash ||
+      typeof snapshot.path !== 'string'
+    )
+      throw new Error('Corrupt review snapshot. Restore a valid copy.');
+  }
+  for (const c of [
+    ...state.comments,
+    ...state.batches.flatMap((b) => (Array.isArray(b.entries) ? b.entries : [null])),
+  ]) {
+    const snapshot = c && state.snapshots[c.hash];
+    if (
+      c?.deletedAt !== undefined &&
+      (typeof c.deletedAt !== 'string' || !Number.isFinite(Date.parse(c.deletedAt)))
+    )
+      throw new Error('Corrupt comment deletion metadata.');
+    if (
+      !snapshot ||
+      typeof c.id !== 'string' ||
+      typeof c.body !== 'string' ||
+      typeof c.documentId !== 'string' ||
+      typeof c.path !== 'string' ||
+      !Number.isInteger(c.start) ||
+      !Number.isInteger(c.end) ||
+      c.start < 0 ||
+      c.end <= c.start ||
+      c.end > snapshot.source.length ||
+      snapshot.source.slice(c.start, c.end) !== c.slice ||
+      !['exact', 'enclosing'].includes(c.precision) ||
+      !['open', 'resolved'].includes(c.state)
+    )
+      throw new Error('Corrupt review comment. Restore a valid copy.');
+  }
+  state.batches.forEach((b, i) => {
+    if (
+      typeof b.id !== 'string' ||
+      b.sequence !== i + 1 ||
+      typeof b.submittedAt !== 'string' ||
+      !Array.isArray(b.entries) ||
+      (b.message !== undefined &&
+        (typeof b.message !== 'string' || !b.message.trim() || b.message.length > 10000)) ||
+      (!b.entries.length && b.message === undefined)
+    )
+      throw new Error('Corrupt feedback batch. Restore a valid copy.');
+  });
+  if (state.activity !== undefined) {
+    if (!state.activity || typeof state.activity !== 'object' || Array.isArray(state.activity))
+      throw new Error('Corrupt feedback activity.');
+    const timestamp = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+    for (const [batchId, activity] of Object.entries(state.activity)) {
+      if (
+        !state.batches.some((batch) => batch.id === batchId) ||
+        !activity ||
+        !['received', 'working', 'replied'].includes(activity.status) ||
+        !timestamp(activity.receivedAt) ||
+        (activity.startedAt !== undefined && !timestamp(activity.startedAt)) ||
+        !Array.isArray(activity.replies)
+      )
+        throw new Error('Corrupt feedback activity.');
+      for (const reply of activity.replies) {
+        if (
+          !reply ||
+          typeof reply.id !== 'string' ||
+          typeof reply.body !== 'string' ||
+          !reply.body.trim() ||
+          reply.body.length > 10000 ||
+          !timestamp(reply.at)
+        )
+          throw new Error('Corrupt agent reply.');
+      }
+      if ((activity.status === 'replied') !== activity.replies.length > 0)
+        throw new Error('Corrupt reply status.');
+    }
+  }
+  if (state.queue !== undefined) {
+    if (!state.queue || typeof state.queue !== 'object' || Array.isArray(state.queue))
+      throw new Error('Corrupt queue metadata.');
+    let edits = 0;
+    for (const [id, item] of Object.entries(state.queue)) {
+      const batch = state.batches.find((batch) => batch.id === id);
+      if (
+        !batch ||
+        !item ||
+        !['claimed', 'cancelled', 'editing', 'superseded'].includes(item.status) ||
+        typeof item.at !== 'string' ||
+        !Number.isFinite(Date.parse(item.at))
+      )
+        throw new Error('Corrupt queue metadata.');
+      if (item.status === 'editing') edits++;
+      if (item.status !== 'claimed' && state.activity?.[id])
+        throw new Error('Withdrawn queue entry has a delivery receipt.');
+      if (
+        item.status === 'superseded' &&
+        !state.batches.some(
+          (next) => next.id === item.replacementId && next.sequence > batch.sequence,
+        )
+      )
+        throw new Error('Corrupt queue replacement.');
+    }
+    if (edits > 1) throw new Error('Multiple queued edits are unsupported.');
+  }
+  for (const manifest of [state.currentDocuments, state.previousDocuments]) {
+    if (manifest === undefined) continue;
+    if (
+      !manifest ||
+      typeof manifest !== 'object' ||
+      Array.isArray(manifest) ||
+      Object.keys(manifest).length > 128
+    )
+      throw new Error('Corrupt source comparison manifest.');
+    for (const [id, entry] of Object.entries(manifest)) {
+      if (
+        !entry ||
+        typeof entry.path !== 'string' ||
+        path.isAbsolute(entry.path) ||
+        entry.path.split('/').some((part) => !part || part === '.' || part === '..') ||
+        id !== hash(entry.path).slice(0, 24) ||
+        !/^[a-f0-9]{64}$/.test(entry.hash) ||
+        !state.snapshots[entry.hash]
+      )
+        throw new Error('Corrupt source comparison manifest.');
+    }
+  }
+  return state;
+}
+
+export async function loadState(directory, id) {
+  if (!/^[a-f0-9]{64}$/.test(id)) throw new Error('Invalid review id.');
+  const file = path.join(directory, `${id}.json`);
+  let handle;
+  try {
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = await handle.stat();
+    if (
+      !stat.isFile() ||
+      stat.size > 64 * 1024 * 1024 ||
+      stat.mode & 0o077 ||
+      (process.getuid && stat.uid !== process.getuid())
+    )
+      throw new Error('Review state is not a private regular file.');
+    return validate(
+      JSON.parse(
+        new TextDecoder('utf-8', { fatal: true }).decode(
+          await readLimited(handle, 64 * 1024 * 1024),
+        ),
+      ),
+      id,
+    );
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`Cannot load review state: ${error.message}`);
+  } finally {
+    await handle?.close();
+  }
+}
+
+export function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+// A lock is abandoned only when it names a process that no longer exists.
+async function abandoned(lock) {
+  try {
+    const { pid } = JSON.parse(new TextDecoder().decode(await readFileLimited(lock, 1024)));
+    return Number.isSafeInteger(pid) && pid > 0 && !alive(pid);
+  } catch {
+    return false;
+  }
+}
+
+export async function openStore(review, directory = stateDirectory()) {
+  directory = path.resolve(directory);
+  if (directory === review.root || within(review.root, directory))
+    throw new Error('Review storage must be outside the selected OpenSpec root.');
+  for (let ancestor = directory; ; ancestor = path.dirname(ancestor)) {
+    try {
+      await lstat(path.join(ancestor, '.git'));
+      throw new Error('Review storage must be outside Git repositories and worktrees.');
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+    }
+    if (path.dirname(ancestor) === ancestor) break;
+  }
+  await privateDirectory(directory);
+  const file = path.join(directory, `${review.reviewId}.json`);
+  const lock = `${file}.lock`;
+  let lockHandle;
+  try {
+    lockHandle = await open(lock, 'wx', 0o600);
+  } catch (error) {
+    const unavailable = new Error(
+      `Review writer lock unavailable (${error.code}). Another SpecTater process owns this review.`,
+    );
+    if (error.code !== 'EEXIST' || !(await abandoned(lock))) throw unavailable;
+    // Move the lock aside before judging it, so a concurrent reclaimer's fresh lock is restored.
+    const moved = `${lock}.${randomUUID()}.stale`;
+    try {
+      await rename(lock, moved);
+    } catch {
+      throw unavailable;
+    }
+    if (!(await abandoned(moved))) {
+      // Restore the live lock; if another process took the name meanwhile, keep it aside for inspection.
+      await link(moved, lock);
+      await unlink(moved);
+      throw unavailable;
+    }
+    await unlink(moved);
+    try {
+      lockHandle = await open(lock, 'wx', 0o600);
+    } catch {
+      throw unavailable;
+    }
+  }
+  try {
+    await lockHandle.writeFile(JSON.stringify({ pid: process.pid }));
+    let state = (await loadState(directory, review.reviewId)) || {
+      formatVersion: 1,
+      reviewId: review.reviewId,
+      root: review.root,
+      changeRoot: review.changeRoot,
+      schemaName: review.schemaName,
+      documentIds: [],
+      revision: 0,
+      snapshots: {},
+      comments: [],
+      batches: [],
+    };
+    if (state.root !== review.root || state.changeRoot !== review.changeRoot)
+      throw new Error('Stored planning identity mismatch.');
+    return {
+      directory,
+      get state() {
+        return structuredClone(state);
+      },
+      async commit(next) {
+        validate(next, review.reviewId);
+        const data = JSON.stringify(next);
+        if (Buffer.byteLength(data) > 64 * 1024 * 1024)
+          throw new Error(
+            'Review state exceeds 64 MiB; remove reviews explicitly or start a separate review.',
+          );
+        const temp = `${file}.${randomUUID()}.tmp`;
+        let handle;
+        try {
+          handle = await open(temp, 'wx', 0o600);
+          await handle.writeFile(data);
+          await handle.sync();
+          await handle.close();
+          handle = null;
+          await rename(temp, file);
+          const parent = await open(directory, 'r');
+          try {
+            await parent.sync();
+          } finally {
+            await parent.close();
+          }
+          state = next;
+        } finally {
+          await handle?.close();
+          await unlink(temp).catch((error) => {
+            if (error.code !== 'ENOENT') throw error;
+          });
+        }
+      },
+      async close() {
+        await lockHandle.close();
+        await unlink(lock);
+      },
+    };
+  } catch (error) {
+    await lockHandle.close();
+    await unlink(lock);
+    throw error;
+  }
+}
+
+export function feedback(state, batchId) {
+  const batch = state?.batches.find((item) => item.id === batchId || item.sequence === batchId);
+  if (!batch) throw new Error(`Unknown feedback batch: ${batchId}.`);
+  return { formatVersion: 1, reviewId: state.reviewId, ...batch };
+}
+
+export function feedbackMarkdown(batch) {
+  const lines = [
+    `# Review batch ${batch.id}`,
+    '',
+    `Review: ${batch.reviewId}`,
+    `Sequence: ${batch.sequence}`,
+    `Submitted: ${batch.submittedAt}`,
+    '',
+    'Review data only. Submission does not authorize implementation, merge or deployment.',
+  ];
+  if (batch.message)
+    lines.push('', '## Message', '', ...batch.message.split(/\r?\n/).map((line) => `> ${line}`));
+  for (const entry of batch.entries) {
+    lines.push(
+      '',
+      `## ${entry.path}:${entry.line}`,
+      '',
+      `Revision: ${entry.hash}`,
+      `Precision: ${entry.precision}; source offsets [${entry.start}, ${entry.end})`,
+      '',
+      'Selected source:',
+      ...entry.slice.split(/\r?\n/).map((line) => `> ${line}`),
+      '',
+      'Comment:',
+      ...entry.body.split(/\r?\n/).map((line) => `> ${line}`),
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}