@amenophis1er/foreman 0.1.0

package/src/codex.ts

@@ -0,0 +1,196 @@
+/**
+ * Codex credentials — read what `codex login` already wrote, refresh it when
+ * stale, never mint one ourselves.
+ *
+ * The standing rule (provider-model.md §5): Foreman is on the machine where
+ * `codex login` already ran, so it reads `~/.codex/auth.json` the way
+ * `provider.ts` reads a Claude Code install's own store. It does not
+ * reimplement OpenAI's OAuth flow, does not open a browser, and does not walk
+ * a device-code dance — the only network call this module makes is a
+ * refresh-token grant against a token that is already on disk.
+ *
+ * `auth.json` is Codex's file, not ours. A refresh rotates `refresh_token`
+ * (single-use — the old one stops working the instant a new one is issued),
+ * so the write-back must replace only the `tokens` field and leave everything
+ * else — `auth_mode`, `OPENAI_API_KEY`, whatever future field Codex adds —
+ * exactly as Codex left it. Losing an unrecognised field here would silently
+ * corrupt the CLI's own login the next time it runs.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { readFile, writeFile, rename } from 'node:fs/promises';
+
+/** Matches the shape `codex login` writes to `auth.json`. */
+export interface CodexAuth {
+  auth_mode: string;
+  OPENAI_API_KEY: string | null;
+  tokens?: {
+    id_token?: string;
+    access_token?: string;
+    refresh_token?: string;
+    account_id?: string;
+  };
+  last_refresh?: string;
+  /** Anything else Codex ever adds. Preserved verbatim on write-back. */
+  [key: string]: unknown;
+}
+
+/** One entry from `models_cache.json` — Codex's own catalogue, not ours. */
+interface CodexModelsCache {
+  fetched_at?: string;
+  etag?: string;
+  client_version?: string;
+  models?: Array<{ slug?: string; [key: string]: unknown }>;
+}
+
+const TOKEN_URL = 'https://auth.openai.com/oauth/token';
+const CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann';
+
+/** Default staleness window: refresh proactively rather than on first 401. */
+const DEFAULT_MAX_AGE_MS = 25 * 60 * 1000;
+
+/** The Codex CLI's home: `CODEX_HOME`, then `~/.codex`. */
+export function codexHome(override?: string): string {
+  const raw = (override ?? process.env.CODEX_HOME ?? '').trim();
+  return raw ? raw : path.join(os.homedir(), '.codex');
+}
+
+/**
+ * Reads and parses `auth.json`. Null covers every ordinary "not usable" case
+ * — no install, no login, a file mid-write, a shape we don't recognise — on
+ * purpose: a missing Codex install is a fact about the machine, not an error
+ * to surface with a stack trace. Never includes file contents in what it
+ * throws or logs, since that file holds live tokens.
+ */
+export async function readCodexAuth(home: string): Promise<CodexAuth | null> {
+  const file = path.join(home, 'auth.json');
+  let raw: string;
+  try {
+    raw = await readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const auth = parsed as CodexAuth;
+  // Usable means: something we can actually authenticate a request with.
+  if (!auth.OPENAI_API_KEY && !auth.tokens?.access_token) return null;
+  return auth;
+}
+
+/** Whether `auth.json`'s `last_refresh` is old enough to refresh proactively. */
+export function isStale(auth: CodexAuth, maxAgeMs = DEFAULT_MAX_AGE_MS): boolean {
+  const last = auth.last_refresh ? Date.parse(auth.last_refresh) : NaN;
+  if (Number.isNaN(last)) return true; // no timestamp we trust — treat as stale
+  return Date.now() - last >= maxAgeMs;
+}
+
+type FetchLike = typeof fetch;
+
+/**
+ * Refreshes an OAuth-mode login and persists the rotated refresh token.
+ *
+ * Returns null on any failure — no network, no refresh token to send, a
+ * non-2xx response, an unparsable body — rather than throwing, matching every
+ * other function here: a refresh failure means "fall back to what's on disk
+ * (or fail preflight)", not a crash.
+ *
+ * The write-back is tmp-file + rename (atomic on the same filesystem, which a
+ * sibling temp file always is) and starts from the file's *current* on-disk
+ * content re-read fresh, not the `auth` passed in — so a field Codex itself
+ * changed between our read and our refresh isn't clobbered by a stale copy.
+ * Only `tokens` and `last_refresh` are touched.
+ */
+export async function refreshCodexAuth(
+  home: string,
+  auth: CodexAuth,
+  fetchImpl: FetchLike = fetch,
+): Promise<CodexAuth | null> {
+  const refreshToken = auth.tokens?.refresh_token;
+  if (!refreshToken) return null;
+
+  let body: { access_token?: string; id_token?: string; refresh_token?: string };
+  try {
+    const res = await fetchImpl(TOKEN_URL, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        client_id: CLIENT_ID,
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+      }),
+    });
+    if (!res.ok) return null;
+    body = (await res.json()) as typeof body;
+  } catch {
+    return null;
+  }
+  if (!body.access_token) return null;
+
+  const file = path.join(home, 'auth.json');
+  // Re-read the file on disk rather than trusting the caller's copy: this is
+  // the only place we write, so it's the only place that can silently drop a
+  // field Codex wrote in the meantime.
+  const current = (await readCodexAuth(home)) ?? auth;
+  const updated: CodexAuth = {
+    ...current,
+    tokens: {
+      ...current.tokens,
+      access_token: body.access_token,
+      id_token: body.id_token ?? current.tokens?.id_token,
+      // The refresh token Codex returns is single-use; if the response omits
+      // one (shouldn't happen, but the API is someone else's), keep the old
+      // one rather than nulling out the only credential we could refresh with
+      // next time.
+      refresh_token: body.refresh_token ?? current.tokens?.refresh_token,
+    },
+    last_refresh: new Date().toISOString(),
+  };
+
+  const tmp = path.join(home, `.auth.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  try {
+    await writeFile(tmp, JSON.stringify(updated, null, 2));
+    await rename(tmp, file);
+  } catch {
+    return null;
+  }
+  return updated;
+}
+
+/**
+ * Model ids from `models_cache.json` — Codex's own list, so the picker never
+ * drifts from what the install actually has. Empty array (never a throw) if
+ * the file is absent, unparsable, or shaped differently than expected: an
+ * empty picker is an ordinary state, a crashed preflight is not.
+ */
+export async function codexModels(home: string): Promise<string[]> {
+  const file = path.join(home, 'models_cache.json');
+  let raw: string;
+  try {
+    raw = await readFile(file, 'utf8');
+  } catch {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw) as CodexModelsCache;
+    const models = parsed.models;
+    if (!Array.isArray(models)) return [];
+    return models
+      // Codex marks internal entries `visibility: "hide"` — `gpt-reserve` and
+      // `codex-auto-review` on a current install. They are real ids the API
+      // would accept, which is exactly why they must not reach a picker: an
+      // operator choosing one has picked something the product never meant to
+      // offer. Anything without an explicit visibility is shown.
+      .filter((m) => m.visibility !== 'hide')
+      .map((m) => m.slug)
+      .filter((slug): slug is string => typeof slug === 'string' && slug.length > 0);
+  } catch {
+    return [];
+  }
+}

package/src/cost-basis.test.ts

@@ -0,0 +1,76 @@
+/**
+ * The cost basis, and the boolean it replaced.
+ *
+ * These are the rules that decide whether a dollar cap may kill a run and
+ * whether someone is told they are spending nothing. Both have been wrong in
+ * production before — a real mission was interrupted at "125% of budget" over
+ * Anthropic prices applied to Ollama tokens — so they are pinned here rather
+ * than left to the call sites that read them.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { combineBasis, costBasisOf, isPriced } from './types.js';
+
+test('a recorded basis is returned as written', () => {
+  assert.equal(costBasisOf({ costBasis: 'free' }), 'free');
+  assert.equal(costBasisOf({ costBasis: 'unpriced' }), 'unpriced');
+  assert.equal(costBasisOf({ costBasis: 'priced' }), 'priced');
+});
+
+test('a run recorded before the split still answers, and errs toward spend', () => {
+  // `metered: false` meant "not priceable", which covered both free and
+  // unpriced. It cannot be split after the fact, so it reads as unpriced:
+  // telling someone a paid run was free is the error that costs money.
+  assert.equal(costBasisOf({ metered: false }), 'unpriced');
+  assert.equal(costBasisOf({ metered: true }), 'priced');
+  // Neither field: the old default was metered, and every run recorded that
+  // way was a Claude Code one.
+  assert.equal(costBasisOf({}), 'priced');
+});
+
+test('costBasis wins over a stale metered boolean', () => {
+  // Both are written together, but a record round-tripped through older code
+  // could disagree. The richer field is the one that means something.
+  assert.equal(costBasisOf({ costBasis: 'free', metered: true }), 'free');
+  assert.equal(costBasisOf({ costBasis: 'priced', metered: false }), 'priced');
+});
+
+test('only a priced run may show or enforce dollars', () => {
+  assert.equal(isPriced({ costBasis: 'priced' }), true);
+  assert.equal(isPriced({ costBasis: 'free' }), false);
+  assert.equal(isPriced({ costBasis: 'unpriced' }), false);
+});
+
+test('free and unpriced are distinct, which is the whole point', () => {
+  // The regression this file exists to prevent: a local model and an OpenAI
+  // key collapsing to one state and rendering identically.
+  assert.notEqual(costBasisOf({ costBasis: 'free' }), costBasisOf({ costBasis: 'unpriced' }));
+  // ...while still agreeing about the only thing enforcement asks them.
+  assert.equal(isPriced({ costBasis: 'free' }), isPriced({ costBasis: 'unpriced' }));
+});
+
+test('a mixed run is priced if any role bills real dollars', () => {
+  // A Claude director delegating to local workers still spends real money on
+  // its own turns; leaving that uncapped is worse than overstating it.
+  assert.equal(combineBasis('priced', 'free'), 'priced');
+  assert.equal(combineBasis('free', 'priced'), 'priced');
+  assert.equal(combineBasis('priced', 'unpriced'), 'priced');
+});
+
+test('a mixed run is never called free when part of it is not', () => {
+  assert.equal(combineBasis('free', 'unpriced'), 'unpriced');
+  assert.equal(combineBasis('unpriced', 'free'), 'unpriced');
+});
+
+test('only two free roles make a free run', () => {
+  assert.equal(combineBasis('free', 'free'), 'free');
+});
+
+test('combining is order-independent', () => {
+  const all = ['priced', 'free', 'unpriced'] as const;
+  for (const a of all) {
+    for (const b of all) {
+      assert.equal(combineBasis(a, b), combineBasis(b, a), `${a}+${b} must not depend on role order`);
+    }
+  }
+});

package/src/deck.test.ts

@@ -0,0 +1,402 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdir, mkdtemp, rm, symlink, unlink, utimes, writeFile } from 'node:fs/promises';
+import { captureBaseline, deckFor, handleDeckRoute, loadBaseline, readArtifact, type Deck, type DeckFile } from './deck.js';
+
+// Every test gets its own folder under os.tmpdir(), which is not inside a git
+// work tree, so the "no git" cases really exercise the snapshot path.
+async function tmp(prefix = 'foreman-deck-'): Promise<string> {
+  return mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+function git(cwd: string, ...args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile('git', [
+      // A hermetic identity: no dependency on the developer's global config,
+      // and no signing so CI machines without a key can commit.
+      '-c', 'user.name=t', '-c', 'user.email=t@example.com', '-c', 'commit.gpgsign=false',
+      ...args,
+    ], { cwd, env: { ...process.env, GIT_CONFIG_NOSYSTEM: '1' } }, (err, stdout, stderr) => {
+      if (err) reject(new Error(stderr || err.message));
+      else resolve(stdout);
+    });
+  });
+}
+
+async function touch(file: string, whenMs: number): Promise<void> {
+  await utimes(file, whenMs / 1000, whenMs / 1000);
+}
+
+const byPath = (deck: Deck): Record<string, DeckFile> =>
+  Object.fromEntries(deck.files.map((f) => [f.path, f]));
+
+// ---------------------------------------------------------------------------
+// git baseline
+// ---------------------------------------------------------------------------
+
+test('git folder: modified, added and deleted files are attributed; a pre-dirty file is flagged preexisting', async () => {
+  const folder = await tmp();
+  try {
+    await git(folder, 'init', '-q');
+    await writeFile(path.join(folder, 'a.txt'), 'one\ntwo\nthree\n');
+    await writeFile(path.join(folder, 'c.txt'), 'gone\nsoon\n');
+    await writeFile(path.join(folder, 'dirty.txt'), 'clean\n');
+    await git(folder, 'add', '.');
+    await git(folder, 'commit', '-q', '-m', 'base');
+    // Dirtied before the run starts: the run must not be blamed for it.
+    await writeFile(path.join(folder, 'dirty.txt'), 'dirty before\n');
+
+    const runId = '1788635675338-e8e5a4a8';
+    const baseline = await captureBaseline(folder, runId);
+    assert.equal(baseline.kind, 'git');
+    if (baseline.kind !== 'git') throw new Error('unreachable');
+    assert.match(baseline.head ?? '', /^[0-9a-f]{40}$/);
+    assert.deepEqual(baseline.dirty, ['dirty.txt']);
+    assert.deepEqual(await loadBaseline(folder, runId), baseline);
+
+    // The run's work.
+    await writeFile(path.join(folder, 'a.txt'), 'one\n2\nthree\nfour\n');
+    await writeFile(path.join(folder, 'b.txt'), 'new file\nsecond line\n');
+    await unlink(path.join(folder, 'c.txt'));
+    await writeFile(path.join(folder, 'dirty.txt'), 'dirty before\nand during\n');
+    await writeFile(path.join(folder, 'bin.dat'), Buffer.from([0, 1, 2, 3, 0, 255]));
+
+    const deck = await deckFor(folder, runId);
+    assert.equal(deck.baseline.kind, 'git');
+    assert.equal(deck.baseline.head, baseline.head);
+    const f = byPath(deck);
+
+    assert.equal(f['a.txt'].status, 'modified');
+    assert.equal(f['a.txt'].additions, 2);
+    assert.equal(f['a.txt'].deletions, 1);
+    assert.match(f['a.txt'].diff ?? '', /^-two$/m);
+    assert.match(f['a.txt'].diff ?? '', /^\+2$/m);
+    assert.equal(f['a.txt'].preexisting, undefined);
+
+    assert.equal(f['b.txt'].status, 'added');
+    assert.equal(f['b.txt'].additions, 2);
+    assert.equal(f['b.txt'].deletions, 0);
+    assert.match(f['b.txt'].diff ?? '', /^\+new file$/m);
+
+    assert.equal(f['c.txt'].status, 'deleted');
+    assert.equal(f['c.txt'].deletions, 2);
+    assert.match(f['c.txt'].diff ?? '', /^-gone$/m);
+
+    assert.equal(f['dirty.txt'].status, 'modified');
+    assert.equal(f['dirty.txt'].preexisting, true);
+    assert.match(deck.note ?? '', /preexisting/);
+
+    assert.equal(f['bin.dat'].status, 'added');
+    assert.equal(f['bin.dat'].binary, true);
+    assert.equal(f['bin.dat'].diff, undefined);
+
+    assert.equal(deck.totals.files, 5);
+    // dirty.txt is diffed against HEAD, so its pre-run edit is counted too —
+    // that is precisely what the preexisting flag warns about.
+    assert.equal(deck.totals.additions, 2 + 2 + 2);
+    assert.equal(deck.totals.deletions, 1 + 2 + 1);
+    // The baseline lives under .foreman/work, which git never sees as a change.
+    assert.ok(!Object.keys(f).some((p) => p.startsWith('.foreman/')), 'baseline leaked into the diff');
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+  }
+});
+
+test('git folder with no commits yet: every tracked and untracked file is added', async () => {
+  const folder = await tmp();
+  try {
+    await git(folder, 'init', '-q');
+    const baseline = await captureBaseline(folder, 'r1');
+    assert.equal(baseline.kind, 'git');
+    if (baseline.kind === 'git') assert.equal(baseline.head, null);
+    await writeFile(path.join(folder, 'x.txt'), 'x\n');
+    await git(folder, 'add', 'x.txt');
+    await writeFile(path.join(folder, 'y.txt'), 'y\n');
+    const deck = await deckFor(folder, 'r1');
+    const f = byPath(deck);
+    assert.equal(f['x.txt'].status, 'added');
+    assert.equal(f['y.txt'].status, 'added');
+    assert.equal(f['y.txt'].additions, 1);
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// snapshot baseline
+// ---------------------------------------------------------------------------
+
+test('snapshot folder: statuses from hashes, real diffs from the kept copies, big files skipped', async () => {
+  const folder = await tmp();
+  try {
+    await writeFile(path.join(folder, 'keep.txt'), 'same\n');
+    await writeFile(path.join(folder, 'mod.txt'), 'alpha\nbeta\ngamma\n');
+    await writeFile(path.join(folder, 'del.txt'), 'bye\nbye\nbye\n');
+    await writeFile(path.join(folder, 'huge-before.bin'), Buffer.alloc(2 * 1024 * 1024 + 1, 1));
+    await mkdir(path.join(folder, 'node_modules', 'dep'), { recursive: true });
+    await writeFile(path.join(folder, 'node_modules', 'dep', 'index.js'), 'ignored\n');
+
+    const baseline = await captureBaseline(folder, 'snap');
+    assert.equal(baseline.kind, 'snapshot');
+    if (baseline.kind !== 'snapshot') throw new Error('unreachable');
+    assert.deepEqual(Object.keys(baseline.files).sort(), ['del.txt', 'keep.txt', 'mod.txt']);
+
+    await writeFile(path.join(folder, 'mod.txt'), 'alpha\nBETA\ngamma\ndelta\n');
+    await writeFile(path.join(folder, 'new.txt'), 'n1\nn2\n');
+    await unlink(path.join(folder, 'del.txt'));
+    await writeFile(path.join(folder, 'huge-after.bin'), Buffer.alloc(3 * 1024 * 1024, 2));
+    // Touched but unchanged: must not show up.
+    await touch(path.join(folder, 'keep.txt'), Date.now() + 5_000);
+
+    const deck = await deckFor(folder, 'snap');
+    assert.equal(deck.baseline.kind, 'snapshot');
+    assert.equal(deck.baseline.at, baseline.at);
+    const f = byPath(deck);
+    assert.deepEqual(Object.keys(f).sort(), ['del.txt', 'mod.txt', 'new.txt']);
+
+    assert.equal(f['mod.txt'].status, 'modified');
+    assert.equal(f['mod.txt'].additions, 2);
+    assert.equal(f['mod.txt'].deletions, 1);
+    assert.match(f['mod.txt'].diff ?? '', /^-beta$/m);
+    assert.match(f['mod.txt'].diff ?? '', /^\+BETA$/m);
+    assert.match(f['mod.txt'].diff ?? '', /^@@ -1,3 \+1,4 @@$/m);
+
+    assert.equal(f['new.txt'].status, 'added');
+    const body = (f['new.txt'].diff ?? '').split('\n').filter((l) => !/^(---|\+\+\+|@@)/.test(l));
+    assert.equal(body.length, 2);
+    assert.ok(body.every((l) => l.startsWith('+')), `not all additions: ${body}`);
+
+    assert.equal(f['del.txt'].status, 'deleted');
+    assert.equal(f['del.txt'].deletions, 3);
+    assert.match(f['del.txt'].diff ?? '', /^-bye$/m);
+
+    assert.deepEqual(deck.totals, { files: 3, additions: 4, deletions: 4 });
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+  }
+});
+
+test('snapshot: a long diff is capped at 400 lines and flagged', async () => {
+  const folder = await tmp();
+  try {
+    await writeFile(path.join(folder, 'long.txt'), 'x\n');
+    await captureBaseline(folder, 'cap');
+    const lines = Array.from({ length: 1000 }, (_, i) => `line ${i}`).join('\n') + '\n';
+    await writeFile(path.join(folder, 'long.txt'), lines);
+    const deck = await deckFor(folder, 'cap');
+    const f = byPath(deck)['long.txt'];
+    assert.equal(f.truncated, true);
+    assert.equal((f.diff ?? '').split('\n').length, 400);
+    assert.equal(f.additions, 1000); // counts are for the whole change, not the shown part
+    assert.equal(f.deletions, 1);
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// artifacts
+// ---------------------------------------------------------------------------
+
+test('artifacts: screenshots and work-dir files always, report-like files only when newer than the baseline', async () => {
+  const folder = await tmp();
+  try {
+    await writeFile(path.join(folder, 'before.md'), '# old\n');
+    const baseline = await captureBaseline(folder, 'art');
+    // Pin mtimes on both sides of the baseline so the test does not depend
+    // on filesystem timestamp granularity.
+    await touch(path.join(folder, 'before.md'), baseline.at - 10_000);
+    await mkdir(path.join(folder, 'screenshots'));
+    await writeFile(path.join(folder, 'screenshots', 'x.png'), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+    await writeFile(path.join(folder, '.foreman', 'work', 'http.log'), 'GET / 200\n');
+    await writeFile(path.join(folder, '.foreman', 'work', '.gitignore'), '*\n');
+    await writeFile(path.join(folder, 'notes.md'), '# notes\n');
+    await writeFile(path.join(folder, 'report.pdf'), '%PDF-1.4\n');
+    await writeFile(path.join(folder, 'code.ts'), 'export {};\n'); // not an artifact extension
+    for (const rel of ['screenshots/x.png', '.foreman/work/http.log', 'notes.md', 'report.pdf', 'code.ts']) {
+      await touch(path.join(folder, rel), baseline.at + 10_000);
+    }
+
+    const deck = await deckFor(folder, 'art');
+    const kinds = Object.fromEntries(deck.artifacts.map((a) => [a.path, a.kind]));
+    assert.deepEqual(kinds, {
+      'screenshots/x.png': 'image',
+      '.foreman/work/http.log': 'text',
+      'notes.md': 'text',
+      'report.pdf': 'pdf',
+    });
+    const png = deck.artifacts.find((a) => a.path === 'screenshots/x.png');
+    assert.equal(png?.size, 4);
+    // Newest first.
+    const times = deck.artifacts.map((a) => a.mtimeMs);
+    assert.deepEqual(times, [...times].sort((a, b) => b - a));
+    // notes.md is also a change; the deck reports both views of it.
+    assert.equal(byPath(deck)['notes.md']?.status, 'added');
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+  }
+});
+
+test('no baseline: kind none with the note, artifacts still listed', async () => {
+  const folder = await tmp();
+  try {
+    await mkdir(path.join(folder, 'screenshots'));
+    await writeFile(path.join(folder, 'screenshots', 'shot.jpg'), 'jpg');
+    await writeFile(path.join(folder, 'README.md'), '# not an artifact without a baseline\n');
+    const deck = await deckFor(folder, 'never-started');
+    assert.equal(deck.baseline.kind, 'none');
+    assert.deepEqual(deck.files, []);
+    assert.equal(deck.note, 'No baseline was recorded when this run started, so changes cannot be attributed to it.');
+    assert.deepEqual(deck.artifacts.map((a) => a.path), ['screenshots/shot.jpg']);
+    assert.equal(deck.artifacts[0].kind, 'image');
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// readArtifact
+// ---------------------------------------------------------------------------
+
+test('readArtifact stays inside the folder and reports mime and size', async () => {
+  const folder = await tmp();
+  const outside = await tmp('foreman-deck-outside-');
+  try {
+    await mkdir(path.join(folder, 'screenshots'));
+    await writeFile(path.join(folder, 'screenshots', 'a.png'), Buffer.alloc(10));
+    await writeFile(path.join(folder, 'page.html'), '<script>alert(1)</script>');
+    await writeFile(path.join(outside, 'secret.txt'), 'nope');
+    await symlink(path.join(outside, 'secret.txt'), path.join(folder, 'link.txt'));
+    await symlink(outside, path.join(folder, 'linkdir'));
+
+    assert.equal(await readArtifact(folder, '../etc/passwd'), null);
+    assert.equal(await readArtifact(folder, '/etc/passwd'), null);
+    assert.equal(await readArtifact(folder, 'screenshots/../../etc/passwd'), null);
+    assert.equal(await readArtifact(folder, 'link.txt'), null);
+    assert.equal(await readArtifact(folder, 'linkdir/secret.txt'), null);
+    assert.equal(await readArtifact(folder, 'screenshots'), null); // a directory
+    assert.equal(await readArtifact(folder, 'missing.png'), null);
+    assert.equal(await readArtifact(folder, ''), null);
+
+    const png = await readArtifact(folder, 'screenshots/a.png');
+    assert.ok(png);
+    assert.equal(png.mime, 'image/png');
+    assert.equal(png.size, 10);
+    assert.equal(png.absPath, path.join(await import('node:fs/promises').then((m) => m.realpath(folder)), 'screenshots', 'a.png'));
+
+    const html = await readArtifact(folder, 'page.html');
+    assert.ok(html);
+    assert.match(html.mime, /^text\/plain/); // never rendered as a document
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// handleDeckRoute
+// ---------------------------------------------------------------------------
+
+test('handleDeckRoute: matches only its two routes, 404s unknown runs and bad paths, streams real artifacts', async () => {
+  const folder = await tmp();
+  const runs: Record<string, { folder: string }> = { 'run-1': { folder } };
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const handled = await handleDeckRoute(req, res, url, async (id) => runs[id] ?? null);
+    // A status no deck response ever uses, so the test can see "fell through".
+    if (!handled) { res.writeHead(418); res.end(); }
+  });
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
+  const port = (server.address() as { port: number }).port;
+  const get = (p: string) => fetch(`http://127.0.0.1:${port}${p}`);
+  try {
+    await mkdir(path.join(folder, 'screenshots'));
+    await writeFile(path.join(folder, 'screenshots', 'a.png'), Buffer.from('pngbytes'));
+    await captureBaseline(folder, 'run-1');
+    await writeFile(path.join(folder, 'made.txt'), 'hello\n');
+
+    assert.equal((await get('/runs/run-1/events')).status, 418);
+    assert.equal((await get('/runs')).status, 418);
+    assert.equal((await get('/runs/nope/deck')).status, 404);
+    assert.equal((await get('/runs/run%2F..%2F1/deck')).status, 404); // fails the id regex
+    assert.equal((await get('/runs/run-1/artifact')).status, 404);
+    assert.equal((await get('/runs/run-1/artifact?path=..%2F..%2Fetc%2Fpasswd')).status, 404);
+    assert.equal((await get('/runs/run-1/artifact?path=missing.png')).status, 404);
+
+    const deckRes = await get('/runs/run-1/deck');
+    assert.equal(deckRes.status, 200);
+    assert.match(deckRes.headers.get('content-type') ?? '', /application\/json/);
+    const deck = await deckRes.json();
+    assert.equal(deck.runId, 'run-1');
+    assert.equal(deck.baseline.kind, 'snapshot');
+    assert.equal(deck.files[0].path, 'made.txt');
+    // made.txt is newer than the baseline and has an artifact extension, so
+    // it is listed alongside the screenshot.
+    assert.deepEqual(deck.artifacts.map((a: { path: string }) => a.path).sort(), ['made.txt', 'screenshots/a.png']);
+
+    const art = await get('/runs/run-1/artifact?path=screenshots%2Fa.png');
+    assert.equal(art.status, 200);
+    assert.equal(art.headers.get('content-type'), 'image/png');
+    assert.equal(art.headers.get('cache-control'), 'no-store');
+    assert.match(art.headers.get('content-disposition') ?? '', /^inline; filename="a\.png"$/);
+    assert.equal(Buffer.from(await art.arrayBuffer()).toString(), 'pngbytes');
+
+    const post = await fetch(`http://127.0.0.1:${port}/runs/run-1/deck`, { method: 'POST' });
+    assert.equal(post.status, 405);
+  } finally {
+    await new Promise<void>((r) => server.close(() => r()));
+    await rm(folder, { recursive: true, force: true });
+  }
+});
+
+test('readArtifact: code reads as text, unknown extensions are sniffed, binaries download', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'deck-mime-'));
+  await writeFile(path.join(dir, 'page.yml'), 'a: 1\n');
+  await writeFile(path.join(dir, 'notes.weird'), 'plain words, no extension anyone knows\n');
+  await writeFile(path.join(dir, 'blob.bin'), Buffer.from([0x89, 0x00, 0x01, 0x02]));
+  const yml = await readArtifact(dir, 'page.yml');
+  const weird = await readArtifact(dir, 'notes.weird');
+  const bin = await readArtifact(dir, 'blob.bin');
+  assert.match(yml?.mime ?? '', /^text\/plain/);
+  assert.match(weird?.mime ?? '', /^text\/plain/);
+  assert.equal(bin?.mime, 'application/octet-stream');
+});
+
+test('preview route: real types inside a CSP sandbox, still jailed', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'deck-preview-'));
+  await writeFile(path.join(dir, 'index.html'), '<!doctype html><link rel="stylesheet" href="styles.css"><script src="app.js"></script>');
+  await writeFile(path.join(dir, 'styles.css'), 'body{margin:0}');
+  await writeFile(path.join(dir, 'app.js'), 'fetch("data.json")');
+  const server = http.createServer((req, res) => {
+    void handleDeckRoute(req, res, new URL(req.url ?? '/', 'http://x'), async (id) => id === 'run-1' ? { folder: dir } : null)
+      .then((handled) => { if (!handled) { res.statusCode = 404; res.end(); } });
+  });
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
+  const port = (server.address() as { port: number }).port;
+  try {
+    const html = await fetch(`http://127.0.0.1:${port}/runs/run-1/preview/index.html`);
+    assert.equal(html.status, 200);
+    assert.match(html.headers.get('content-type') ?? '', /^text\/html/);
+    assert.match(html.headers.get('content-security-policy') ?? '', /\bsandbox allow-scripts\b/);
+    assert.doesNotMatch(html.headers.get('content-security-policy') ?? '', /allow-same-origin/);
+    const css = await fetch(`http://127.0.0.1:${port}/runs/run-1/preview/styles.css`);
+    assert.match(css.headers.get('content-type') ?? '', /^text\/css/);
+    const js = await fetch(`http://127.0.0.1:${port}/runs/run-1/preview/app.js`);
+    assert.match(js.headers.get('content-type') ?? '', /javascript/);
+    assert.equal(js.headers.get('access-control-allow-origin'), '*');
+    // The plain artifact route is unchanged: HTML there is still text, never a document.
+    const raw = await fetch(`http://127.0.0.1:${port}/runs/run-1/artifact?path=index.html`);
+    assert.match(raw.headers.get('content-type') ?? '', /^text\/plain/);
+    // Jail holds on the preview path too.
+    const out = await fetch(`http://127.0.0.1:${port}/runs/run-1/preview/..%2F..%2Fetc%2Fpasswd`);
+    assert.equal(out.status, 404);
+    const bare = await fetch(`http://127.0.0.1:${port}/runs/run-1/preview`);
+    assert.equal(bare.status, 404);
+  } finally {
+    server.close();
+  }
+});