paperlint 2.0.0

package/src/adapters/banal/xml.ts

@@ -0,0 +1,112 @@
+/**
+ * THE BANAL INPUT XML: the pdftohtml-format XML (text boxes with position, size and font per page)
+ * that paperlint writes from the domain's page layout, which is the input banal reads — PURE. No disk, no pdf.js,
+ * no process.
+ *
+ * `pdf-facts.ts` reads the PDF with pdf.js and hands this module plain data: every text item's box,
+ * size, font, fill colour and whether it is upright. This module decides which of them a page-layout
+ * tool would count, and writes them as the banal input XML, in the dialect `pdftohtml -xml` writes
+ * and banal (HotCRP's page-geometry script, see `./index.ts`) reads. banal then measures that XML exactly as it measures the XML poppler's
+ * `pdftohtml` writes — which is how paperlint gets banal's numbers without poppler (issue #61).
+ *
+ * ── WHAT MAKES THE XML EQUAL TO pdftohtml's, as far as banal can tell ─────────────
+ * Measured on 50 PDFs / 598 pages (2026-09-25): real banal on this XML gave the same page size,
+ * columns, body and reference font size, and page counts by type as real banal on real pdftohtml.
+ * It matched only with the conditions below; each gave a wrong answer when switched off.
+ *
+ *   1. ROTATED TEXT IS NOT WRITTEN. pdftohtml writes it with width 0 and banal drops zero-width
+ *      text; writing it as a horizontal box would count a rotated margin note as body text.
+ *   2. INVISIBLE TEXT (render mode 3, an OCR layer) IS NOT WRITTEN — pdftohtml does not write it.
+ *   3. LIGHT TEXT IS WRITTEN WITH ITS COLOUR, and banal drops it itself. What counts as light is
+ *      banal's decision (a watermark, grey code comments), so the colour goes into `<fontspec>`
+ *      exactly as pdftohtml writes it and no threshold is copied here.
+ *   4. SIZES AND COORDINATES AT ZOOM 3, the scale banal assumes for a modern pdftohtml. A font size
+ *      is written as `round(size × 3)` — an integer, as pdftohtml writes it — and banal applies its
+ *      own rounding to it; coordinates are written unrounded and banal rounds them to 1/8 of a
+ *      decipoint. Rounding them here would round twice.
+ *
+ * banal also has to be told which pdftohtml wrote the XML, because it asks `pdftohtml -v` and
+ * derives the zoom and a font-size correction from the answer. `./index.ts` answers that question
+ * with `XML_DIALECT` below; the dialect and the writer live together so they cannot disagree.
+ */
+import type { Fill, PageLayout, TextBox } from "../../domain/page-layout.ts";
+
+/**
+ * The pdftohtml whose XML this module writes: the zoom it writes at, and the version banal is told.
+ * banal (1.2, lines 1848-1867) picks zoom 3 and a font-size correction of 1 for any version >= 0.85;
+ * told an older version it uses 3, and every font size it reports moves.
+ */
+export const XML_DIALECT = { zoom: 3, version: "24.02.0" } as const;
+
+const BLACK = "#000000";
+
+/** Whether pdftohtml would write this box at all (conditions 1 and 2 above). */
+export const written = (b: TextBox): boolean =>
+  b.upright && b.fill.kind !== "invisible" && b.text.trim() !== "";
+
+const colourOf = (f: Fill): string => (f.kind === "rgb" ? f.hex : BLACK);
+
+/** XML-escape text and attribute values the way pdftohtml does (a newline becomes a space). */
+export function xmlEscape(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&#34;")
+    .replace(/[\r\n]/g, " ");
+}
+
+/** A number as pdftohtml's `-noroundcoord` writes it: fixed, six decimals. */
+const fixed = (n: number): string => n.toFixed(6);
+
+/**
+ * The document-wide font table. pdftohtml numbers fonts across the whole document and declares a
+ * font on the first page that uses it, before that page's text; banal keeps the table across pages.
+ */
+class FontTable {
+  private readonly ids = new Map<string, number>();
+
+  /** The id of this font, and whether this is its first use. */
+  idOf(size: number, font: string, colour: string): [number, boolean] {
+    const key = `${String(size)}|${font}|${colour}`;
+    const known = this.ids.get(key);
+    if (known !== undefined) return [known, false];
+    const id = this.ids.size;
+    this.ids.set(key, id);
+    return [id, true];
+  }
+}
+
+/** One page: its `<page>` line, the fonts it introduces, then its text lines. */
+function pageXml(p: PageLayout, n: number, fonts: FontTable): string[] {
+  const z = XML_DIALECT.zoom;
+  const specs: string[] = [];
+  const texts: string[] = [];
+  for (const b of p.boxes.filter(written)) {
+    const size = Math.round(b.size * z);
+    const colour = colourOf(b.fill);
+    const [id, fresh] = fonts.idOf(size, b.font, colour);
+    if (fresh)
+      specs.push(
+        `\t<fontspec id="${String(id)}" size="${String(size)}" family="${xmlEscape(b.font)}" color="${colour}"/>`,
+      );
+    texts.push(
+      `<text top="${fixed(b.top * z)}" left="${fixed(b.left * z)}" width="${fixed(b.width * z)}" height="${fixed(b.height * z)}" font="${String(id)}">${xmlEscape(b.text)}</text>`,
+    );
+  }
+  const head = `<page number="${String(n)}" position="absolute" top="0" left="0" height="${String(Math.round(p.heightPt * z))}" width="${String(Math.round(p.widthPt * z))}">`;
+  return [head, ...specs, ...texts, "</page>"];
+}
+
+/** The pages as `pdftohtml -xml -i -zoom 3 -noroundcoord` would write them. */
+export function pdf2xml(pages: readonly PageLayout[]): string {
+  const fonts = new FontTable();
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE pdf2xml SYSTEM "pdf2xml.dtd">',
+    `<pdf2xml producer="research-paper-pipeline (pdf.js)" version="${XML_DIALECT.version}">`,
+    ...pages.flatMap((p, i) => pageXml(p, i + 1, fonts)),
+    "</pdf2xml>",
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/src/adapters/curl/download.io.ts

@@ -0,0 +1,73 @@
+/**
+ * `Download` through `curl -fsSL`. Not Node's `fetch`: undici's `fetch` ignores `HTTPS_PROXY` unless
+ * a proxy agent is installed, and rpp's CI and the containers it runs in reach the network only
+ * through a proxy. curl reads the proxy variables itself. (A claim from documentation, not measured
+ * here — the port is what makes trying the other adapter cheap.)
+ */
+import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { firstLine } from "../../domain/text.ts";
+import type { Download } from "../../ports/download.ts";
+import type { ProcessExit, RunProcess } from "../../ports/process.ts";
+import { err, ok } from "../../domain/result.ts";
+
+/** Why a curl run did not download, in its own words; null when it exited 0. */
+export function curlFailure(r: ProcessExit): string | null {
+  if (r.kind === "exited" && r.status === 0) return null;
+  if (r.kind === "not-found") return "curl is not installed";
+  if (r.kind === "spawn-failed") return r.message;
+  if (r.kind === "timed-out") return `no answer after ${String(r.afterMs)} ms`;
+  const what =
+    r.kind === "exited" ? `curl exited ${String(r.status)}` : r.signal;
+  return firstLine(r.stderr) || what;
+}
+
+const readOrNull = (p: string): Uint8Array | null => {
+  try {
+    return readFileSync(p);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * `run` is the process port (so a test can take curl away); `env` is curl's whole environment, the
+ * proxy variables included; `tmpDir` holds the file curl writes, removed before `fetch` returns.
+ */
+export function curlDownload(o: {
+  readonly run: RunProcess;
+  readonly env: Readonly<Record<string, string>>;
+  readonly tmpDir: string;
+}): Download {
+  return {
+    fetch(url: string, timeoutMs: number) {
+      const dir = realpathSync(mkdtempSync(join(o.tmpDir, "rpp-download-")));
+      const out = join(dir, "body");
+      try {
+        const seconds = String(Math.ceil(timeoutMs / 1000));
+        const failed = curlFailure(
+          o.run.run({
+            file: "curl",
+            args: [
+              "-fsSL",
+              "--retry",
+              "2",
+              "--max-time",
+              seconds,
+              "-o",
+              out,
+              url,
+            ],
+            env: o.env,
+            timeoutMs: timeoutMs + 30_000,
+          }),
+        );
+        const bytes = failed ? null : readOrNull(out);
+        if (bytes) return ok(bytes);
+        return err({ detail: failed ?? "curl wrote no file" });
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  };
+}

package/src/adapters/curl/download.test.ts

@@ -0,0 +1,55 @@
+/**
+ * The `Download` contract against the real curl, on `file://` URLs (no network): bytes come back,
+ * the temp file is removed, and a missing curl is named as that.
+ */
+import assert from "node:assert/strict";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll as after, test } from "vitest";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import { curlDownload } from "./download.io.ts";
+import { spawnProcess } from "../node/index.ts";
+
+const root = realpathSync(mkdtempSync(join(tmpdir(), "rpp-download-test-")));
+after(() => rmSync(root, { recursive: true, force: true }));
+const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
+
+const dl = (env: Record<string, string>) => {
+  const tmp = at("dl-tmp");
+  mkdirSync(tmp, { recursive: true });
+  return { d: curlDownload({ run: spawnProcess(), env, tmpDir: tmp }), tmp };
+};
+
+test("Download: a file:// URL comes back as its bytes, and the temp file is gone", () => {
+  const src = at("served");
+  writeFileSync(src, "banal bytes");
+  const { d, tmp } = dl({ PATH: "/usr/bin:/bin" });
+  const r = d.fetch(pathToFileURL(src).href, 10_000);
+  assert.equal(r.ok && new TextDecoder().decode(r.value), "banal bytes");
+  assert.deepEqual(readdirSync(tmp), []);
+});
+
+test("Download: a URL that does not answer is a failure with curl's words", () => {
+  const { d } = dl({ PATH: "/usr/bin:/bin" });
+  const r = d.fetch(pathToFileURL(at("missing")).href, 10_000);
+  assert.equal(r.ok, false);
+  assert.ok(!r.ok && r.error.detail.length > 0);
+});
+
+test("🔴 Download: no curl on PATH is named as that, not as a failed URL", () => {
+  const empty = at("empty-bin");
+  mkdirSync(empty, { recursive: true });
+  const { d } = dl({ PATH: empty });
+  const r = d.fetch("https://example.test/banal", 10_000);
+  // Guards: a missing curl is its own diagnosis — once, it read "spawnSync curl ENOENT".
+  assert.deepEqual(!r.ok && r.error, { detail: "curl is not installed" });
+});

package/src/adapters/curl/index.ts

@@ -0,0 +1,5 @@
+/**
+ * curl, as the `Download` port. Its own adapter because curl is its own program: what changes if
+ * curl does (its flags, its exit codes, its proxy handling) changes here and nowhere else.
+ */
+export { curlDownload, curlFailure } from "./download.io.ts";

package/src/adapters/memory/index.ts

@@ -0,0 +1,131 @@
+/**
+ * In-memory adapters for the app layer's tests: every port, no disk, no processes, no network.
+ * Each one RECORDS what it was asked, so a test asserts on the calls instead of on side effects.
+ */
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { Download } from "../../ports/download.ts";
+import type { Files } from "../../ports/files.ts";
+import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
+import type { NotAPromise, Scratch, Workspace } from "../../ports/workspace.ts";
+import { err, ok } from "../../domain/result.ts";
+
+export interface ScriptedProcess extends RunProcess {
+  readonly calls: Command[];
+}
+
+/** A `RunProcess` that answers every `Command` with `script(c)` and records it. */
+export function scriptedProcess(
+  script: (c: Command) => ProcessExit,
+): ScriptedProcess {
+  const calls: Command[] = [];
+  return {
+    calls,
+    run(c) {
+      calls.push(c);
+      return script(c);
+    },
+  };
+}
+
+/** A process that exits 0 and prints `stdout`. */
+export const exitedWith = (stdout: string, status = 0): ProcessExit => ({
+  kind: "exited",
+  status,
+  stdout,
+  stderr: "",
+});
+
+export interface MemoryFiles extends Files {
+  readonly map: Map<string, Uint8Array>;
+}
+
+export function memoryFiles(
+  initial: Readonly<Record<string, string | Uint8Array>> = {},
+): MemoryFiles {
+  const bytes = (v: string | Uint8Array) =>
+    typeof v === "string" ? new TextEncoder().encode(v) : v;
+  const map = new Map(
+    Object.entries(initial).map(([k, v]) => [k, bytes(v)] as const),
+  );
+  return {
+    map,
+    isFile: (p) => map.has(p),
+    readBytes: (p) => map.get(p) ?? null,
+    writeAtomic: (p, b) => void map.set(p, b),
+  };
+}
+
+export interface MemoryWorkspace extends Workspace {
+  /** Every file written into a scratch directory, in order. */
+  readonly written: {
+    readonly name: string;
+    readonly content: string;
+    readonly mode: "read" | "exec";
+  }[];
+  /** How each `within` ended. */
+  readonly ended: ("returned" | "threw")[];
+}
+
+export function memoryWorkspace(dir = "/scratch"): MemoryWorkspace {
+  const written: MemoryWorkspace["written"] = [];
+  const ended: ("returned" | "threw")[] = [];
+  const scratch: Scratch = {
+    dir: dir as AbsolutePath,
+    write(name, content, mode) {
+      written.push({ name, content, mode });
+      return `${dir}/${name}` as AbsolutePath;
+    },
+  };
+  return {
+    written,
+    ended,
+    within<T>(_prefix: string, use: (s: Scratch) => NotAPromise<T>): T {
+      try {
+        const r = use(scratch);
+        ended.push("returned");
+        return r;
+      } catch (e) {
+        ended.push("threw");
+        throw e;
+      }
+    },
+  };
+}
+
+export interface FixedDownload extends Download {
+  readonly urls: string[];
+}
+
+/** A `Download` that returns `body` for every URL, or fails with `detail` when `body` is a failure. */
+export function fixedDownload(
+  body: string | Uint8Array | { readonly detail: string },
+): FixedDownload {
+  const urls: string[] = [];
+  return {
+    urls,
+    fetch(url) {
+      urls.push(url);
+      if (typeof body === "string") return ok(new TextEncoder().encode(body));
+      return body instanceof Uint8Array ? ok(body) : err(body);
+    },
+  };
+}
+
+/** Every generic port at once — what a test hands an adapter built over several of them. */
+export interface MemoryPorts {
+  readonly run: RunProcess;
+  readonly files: Files;
+  readonly workspace: Workspace;
+  readonly download: Download;
+}
+
+/** All four ports from in-memory parts; any part can be replaced. */
+export function memoryPorts(over: Partial<MemoryPorts> = {}): MemoryPorts {
+  return {
+    run: scriptedProcess(() => exitedWith("")),
+    files: memoryFiles(),
+    workspace: memoryWorkspace(),
+    download: fixedDownload({ detail: "no network in memory" }),
+    ...over,
+  };
+}

package/src/adapters/node/files.io.ts

@@ -0,0 +1,39 @@
+/** `Files` over `node:fs`. */
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { Files } from "../../ports/files.ts";
+
+const code = (e: unknown): unknown =>
+  e instanceof Error ? (e as NodeJS.ErrnoException).code : undefined;
+
+export const nodeFiles: Files = {
+  isFile(p: AbsolutePath): boolean {
+    return statSync(p, { throwIfNoEntry: false })?.isFile() ?? false;
+  },
+  readBytes(p: AbsolutePath): Uint8Array | null {
+    try {
+      return readFileSync(p);
+    } catch (e) {
+      if (code(e) === "ENOENT") return null;
+      throw e;
+    }
+  },
+  writeAtomic(p: AbsolutePath, bytes: Uint8Array): void {
+    const part = `${p}.part`;
+    mkdirSync(dirname(p), { recursive: true });
+    try {
+      writeFileSync(part, bytes);
+      renameSync(part, p);
+    } finally {
+      rmSync(part, { force: true });
+    }
+  },
+};

package/src/adapters/node/files.test.ts

@@ -0,0 +1,28 @@
+/** The `Files` contract against the real disk: absence is null, and writes go through `.part`. */
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll as after, test } from "vitest";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import { nodeFiles } from "./files.io.ts";
+
+const root = realpathSync(mkdtempSync(join(tmpdir(), "rpp-files-test-")));
+after(() => rmSync(root, { recursive: true, force: true }));
+const at = (...p: string[]) => join(root, ...p) as AbsolutePath;
+
+test("Files: a missing file reads as null and is not a file", () => {
+  assert.equal(nodeFiles.readBytes(at("nope")), null);
+  assert.equal(nodeFiles.isFile(at("nope")), false);
+  assert.equal(nodeFiles.isFile(at()), false);
+});
+
+test("Files: writeAtomic creates the directory and leaves no .part behind", () => {
+  const p = at("a", "b", "banal");
+  nodeFiles.writeAtomic(p, new TextEncoder().encode("x"));
+  assert.equal(
+    new TextDecoder().decode(nodeFiles.readBytes(p) ?? undefined),
+    "x",
+  );
+  assert.equal(existsSync(`${p}.part`), false);
+});

package/src/adapters/node/host.io.ts

@@ -0,0 +1,15 @@
+/**
+ * What the host knows and the environment does not say — the home, the temp directory, the cwd —
+ * read once. A composition root calls this and passes the value in; nothing below it reads the host
+ * again. Which of these a tool cares about, and what it derives from them, is that tool's adapter's
+ * business (banal's: `adapters/banal/settings.ts`).
+ */
+import { homedir, tmpdir } from "node:os";
+import type { HostDirs } from "../../domain/host.ts";
+
+export const hostDirs = (over: Partial<HostDirs> = {}): HostDirs => ({
+  home: homedir(),
+  tmp: tmpdir(),
+  cwd: process.cwd(),
+  ...over,
+});

package/src/adapters/node/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Node's implementations of the generic ports: processes, files, scratch directories. What a
+ * composition root builds and hands to the adapters that need them (banal's, for one).
+ */
+import type { Files } from "../../ports/files.ts";
+import type { RunProcess } from "../../ports/process.ts";
+import type { Workspace } from "../../ports/workspace.ts";
+import { nodeFiles } from "./files.io.ts";
+import { spawnProcess, type SpawnSync } from "./process.io.ts";
+import { tmpWorkspace } from "./workspace.io.ts";
+
+export interface NodeAdapterOptions {
+  /** Scratch directories go here. */
+  readonly tmpDir: string;
+  /** `spawnSync` or a stand-in with its shape. */
+  readonly spawn?: SpawnSync;
+}
+
+/** The node ports, built once at the root. */
+export interface NodePorts {
+  readonly run: RunProcess;
+  readonly files: Files;
+  readonly workspace: Workspace;
+}
+
+export function nodeAdapters(o: NodeAdapterOptions): NodePorts {
+  return {
+    run: spawnProcess(o.spawn),
+    files: nodeFiles,
+    workspace: tmpWorkspace(o.tmpDir),
+  };
+}
+
+export { nodeFiles } from "./files.io.ts";
+export { spawnProcess, type SpawnSync } from "./process.io.ts";
+export { hostDirs } from "./host.io.ts";

package/src/adapters/node/process.io.ts

@@ -0,0 +1,49 @@
+/**
+ * `RunProcess` over Node's `spawnSync`. The one place that reads a child's result as Node reports
+ * it — `error`, `status`, `signal`, all nullable — and turns it into a `ProcessExit`, so no caller
+ * re-derives "what happened" from three fields.
+ */
+import {
+  spawnSync,
+  type SpawnSyncOptionsWithStringEncoding,
+  type SpawnSyncReturns,
+} from "node:child_process";
+import type { Command, ProcessExit, RunProcess } from "../../ports/process.ts";
+
+/** Node's `spawnSync`, or a stand-in with its shape (a harness records the calls through one). */
+export type SpawnSync = typeof spawnSync;
+
+const errno = (r: SpawnSyncReturns<string>): string | undefined =>
+  (r.error as NodeJS.ErrnoException | undefined)?.code;
+
+/** What a finished `spawnSync` came to. ENOENT is the executable itself: `c.file` was not found. */
+export function exitOf(r: SpawnSyncReturns<string>, c: Command): ProcessExit {
+  const out = {
+    stdout: String(r.stdout ?? ""),
+    stderr: String(r.stderr ?? ""),
+  };
+  const code = errno(r);
+  if (code === "ENOENT") return { kind: "not-found", file: c.file };
+  if (code === "ETIMEDOUT")
+    return { kind: "timed-out", afterMs: c.timeoutMs, ...out };
+  if (r.error) return { kind: "spawn-failed", message: r.error.message };
+  if (r.signal) return { kind: "signalled", signal: r.signal, ...out };
+  return { kind: "exited", status: r.status ?? 1, ...out };
+}
+
+/** A `RunProcess` that runs every `Command` with `spawn` (Node's `spawnSync` by default). */
+export function spawnProcess(spawn: SpawnSync = spawnSync): RunProcess {
+  return {
+    run(c: Command): ProcessExit {
+      const opts: SpawnSyncOptionsWithStringEncoding = {
+        encoding: "utf8",
+        env: { ...c.env },
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: c.timeoutMs,
+        ...(c.maxOutputBytes ? { maxBuffer: c.maxOutputBytes } : {}),
+        ...(c.cwd ? { cwd: c.cwd } : {}),
+      };
+      return exitOf(spawn(c.file, [...c.args], opts), c);
+    },
+  };
+}

package/src/adapters/node/process.test.ts

@@ -0,0 +1,46 @@
+/**
+ * The `RunProcess` contract, against the real `spawnSync`: what each way a program can end comes
+ * back as. The only process tests allowed real I/O — the core and app tests take `ProcessExit`
+ * literals instead.
+ */
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import type { Command } from "../../ports/process.ts";
+import { spawnProcess } from "./process.io.ts";
+
+const run = spawnProcess();
+const sh = (script: string, timeoutMs = 10_000): Command => ({
+  file: "/bin/sh",
+  args: ["-c", script],
+  env: { PATH: "/usr/bin:/bin" },
+  timeoutMs,
+});
+
+test("a program that is not there is `not-found`, and names the program", () => {
+  // Guards: ENOENT is the executable itself — "perl is missing" rather than "banal failed".
+  assert.deepEqual(
+    run.run({ ...sh(""), file: "rpp-no-such-program-xyz", args: [] }),
+    { kind: "not-found", file: "rpp-no-such-program-xyz" },
+  );
+});
+
+test("an exit status, stdout and stderr come back as they were", () => {
+  assert.deepEqual(run.run(sh("echo out; echo err >&2; exit 3")), {
+    kind: "exited",
+    status: 3,
+    stdout: "out\n",
+    stderr: "err\n",
+  });
+});
+
+test("a program that outlives its time is `timed-out`, not an exit", () => {
+  const r = run.run(sh("sleep 5", 50));
+  // Guards: a hang ends, and says it hung — not "exit null".
+  assert.equal(r.kind, "timed-out");
+});
+
+test("the environment is the Command's, whole: nothing leaks in from the parent", () => {
+  const r = run.run({ ...sh('echo "[$HOME][$X]"'), env: { X: "1" } });
+  // Guards: `Command.env` is the child's entire environment — the adapter merges nothing.
+  assert.deepEqual(r.kind === "exited" && r.stdout, "[][1]\n");
+});

package/src/adapters/node/workspace.io.ts

@@ -0,0 +1,40 @@
+/**
+ * `Workspace` over a temporary directory: `mkdtemp` + `realpath` (macOS's `/var` is a symlink to
+ * `/private/var`, and a path through it is not the one a child process reports) + `rm` in `finally`.
+ */
+import {
+  chmodSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { AbsolutePath } from "../../domain/paths.ts";
+import type { NotAPromise, Scratch, Workspace } from "../../ports/workspace.ts";
+
+function scratchIn(dir: AbsolutePath): Scratch {
+  return {
+    dir,
+    write(name, content, mode): AbsolutePath {
+      const at = join(dir, name) as AbsolutePath;
+      writeFileSync(at, content);
+      if (mode === "exec") chmodSync(at, 0o755);
+      return at;
+    },
+  };
+}
+
+/** Scratch directories under `tmpDir`. */
+export function tmpWorkspace(tmpDir: string): Workspace {
+  return {
+    within<T>(prefix: string, use: (s: Scratch) => NotAPromise<T>): T {
+      const dir = realpathSync(mkdtempSync(join(tmpDir, prefix)));
+      try {
+        return use(scratchIn(dir as AbsolutePath));
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  };
+}