@pmelab/gtd 23.2.0 → 24.1.0

package/src/testkit/Layers.ts

@@ -0,0 +1,241 @@
+// `testLayers` is the ONE layer-set builder every `@inmem` scenario and
+// `src/**/*.test.ts` unit test provides.
+//
+// gtd itself spawns no subprocess at all any more (`gtd renders; the driver
+// executes`) — a mode's `format:`/`validate:` command is emitted text, never
+// run in-process. `ScriptedCommand` below still exists for the world's own
+// fake-shell interpreter (`src/testkit/EmittedScriptRecognizer.ts`), which
+// simulates a driver running gtd's emitted scripts against the in-memory
+// worktree — a wholly separate mechanism from any gtd-internal layer.
+
+import { Effect, Layer } from "effect"
+import { isAbsolute, join } from "node:path"
+import {
+  Narrator,
+  GitService,
+  Host,
+  Workspace,
+  type WorkspaceOps,
+  CommandRunner,
+} from "../platform/index.js"
+import {
+  ConfigDiscovery,
+  ConfigService,
+  LEGACY_RC_FILES,
+  legacyRcDirs,
+  WORKFLOW_MODULE,
+  walkUp,
+} from "../workflow/index.js"
+import { fakeGitOperations } from "./FakeGitOperations.js"
+import { InMemRepo } from "./InMemRepo.js"
+
+// Read off the CLI's own port rather than imported from the composition root.
+type CommandRequirements = Layer.Layer.Success<ReturnType<CliIo["layers"]>>
+import { ToolCommands, type CliIo } from "../cli/index.js"
+
+const toError = (e: unknown): Error => (e instanceof Error ? e : new Error(String(e)))
+
+/**
+ * Keys UNDER `.git/` (never the bare `.git` FILE itself — `WorktreeState.ts`'s
+ * `worktreeGitDir` legitimately reads that one, a linked worktree's real
+ * gitdir-pointer file) have no production consumer through `Workspace` — gtd
+ * keeps no driver-scoped files inside the git dir (sessions are derived,
+ * stall is history) — so a stray read/write there FAILS/reads-absent rather
+ * than silently falling through to the worktree store, which would make it
+ * surface as a pending change (real git never reports a `.git/**` path as
+ * one). Mirrors the guard the deleted `makeInMemoryFileSystem` carried.
+ */
+const isGitDirKey = (key: string): boolean => key.startsWith(".git/")
+
+/**
+ * `Workspace` for the in-memory tier. `readSync`/`read`/`write`/`committed`
+ * take a repo-relative key ONLY (mirroring the live adapter's
+ * `assertRepoRelative` — `Workspace.ts`'s `makeWorkspaceOps`), matching how
+ * every existing scenario already seeds the fake (`repo.writeFile("gtd.config.ts",
+ * …)`, `repo.writeFile("src/a.ts", …)`). // gtd-path-exempt: illustrative fixture key, not a repo file
+ * `atPath` alone accepts an absolute
+ * path: one rooted under `root` maps to its relative key (an already-absolute
+ * content file-ref resolved via `resolvePath`); one OUTSIDE root (an ancestor
+ * `gtd.config.ts`, or a leftover rc file in home) is used as the literal key
+ * verbatim, so a test seeds it exactly as given:
+ * `repo.writeFile("/home/user/.gtdrc", …)`.
+ */
+export const makeInMemoryWorkspaceOps = (repo: InMemRepo, root: string): WorkspaceOps => {
+  const toKey = (path: string): string => {
+    if (!isAbsolute(path)) return path
+    const prefix = `${root}/`
+    return path === root ? "" : path.startsWith(prefix) ? path.slice(prefix.length) : path
+  }
+  const assertRepoRelative = (path: string): string => {
+    if (isAbsolute(path)) {
+      throw new Error(
+        `Workspace: "${path}" is an absolute path — this member takes repo-relative paths only (use "atPath" to read outside the repo)`,
+      )
+    }
+    return path
+  }
+  const readAt = (key: string): string | undefined =>
+    isGitDirKey(key) ? undefined : repo.readFile(key)
+
+  const readSync = (path: string): string | undefined => readAt(assertRepoRelative(path))
+
+  const treeOf = (ref: string): ReadonlyMap<string, string> =>
+    new Map(repo.pathsAtRef(ref).map((path) => [path, repo.fileAtRef(ref, path) ?? ""]))
+
+  return {
+    readSync,
+    read: (path) => Effect.try({ try: () => readSync(path), catch: toError }),
+    write: (path, content) =>
+      Effect.try({
+        try: () => {
+          const key = assertRepoRelative(path)
+          if (isGitDirKey(key)) {
+            throw new Error(`ENOENT: no such file or directory, open '${path}'`)
+          }
+          repo.writeFile(key, content)
+        },
+        catch: toError,
+      }),
+    committed: (path, ref = "HEAD") =>
+      Effect.try({ try: () => assertRepoRelative(path), catch: toError }).pipe(
+        Effect.map((key) =>
+          isGitDirKey(key) ? undefined : (repo.fileAtRef(ref, key) ?? undefined),
+        ),
+      ),
+    readCommittedSync: (path, ref = "HEAD") => {
+      const key = assertRepoRelative(path)
+      return isGitDirKey(key) ? undefined : (repo.fileAtRef(ref, key) ?? undefined)
+    },
+    treeSync: treeOf,
+    // No subprocess, no cache to warm — the in-memory fake reads its
+    // `InMemRepo` directly for each hash, same as `treeSync` above.
+    episodeTrees: (base, commits) =>
+      Effect.succeed(
+        new Map([...(base !== undefined ? [base] : []), ...commits].map((h) => [h, treeOf(h)])),
+      ),
+    worktreeSync: () =>
+      new Map(
+        repo
+          .pathsUnder("")
+          .filter((path) => !isGitDirKey(path))
+          .map((path) => [path, repo.readFile(path)]),
+      ),
+    atPath: (path) => readAt(toKey(path)),
+    writeAtPath: (path, content) =>
+      Effect.try({
+        try: () => {
+          const key = toKey(path)
+          if (isGitDirKey(key)) {
+            throw new Error(`ENOENT: no such file or directory, open '${path}'`)
+          }
+          repo.writeFile(key, content)
+        },
+        catch: toError,
+      }),
+  }
+}
+
+/** The in-memory counterpart to `ConfigDiscovery.Live` (`src/workflow/discovery.ts`) — shares its `LEGACY_RC_FILES`/`legacyRcDirs`/`walkUp` exactly (see `Layers.test.ts`), reading through the fake `Workspace` instead of real `fs`. */
+const makeInMemoryConfigDiscovery = (
+  repo: InMemRepo,
+  root: string,
+): Layer.Layer<ConfigDiscovery> => {
+  const workspace = makeInMemoryWorkspaceOps(repo, root)
+  return Layer.succeed(ConfigDiscovery, {
+    legacyRcFiles: (levelRoot, levelHome) =>
+      Effect.try({
+        try: () =>
+          legacyRcDirs(levelRoot, levelHome).flatMap((dir) =>
+            LEGACY_RC_FILES.map((name) => join(dir, name))
+              .filter((filepath) => workspace.atPath(filepath) !== undefined)
+              .map((path) => ({ path, owned: true })),
+          ),
+        catch: toError,
+      }),
+    workflowModule: (levelRoot, levelHome) =>
+      Effect.try({
+        try: () => {
+          for (const dir of walkUp(levelRoot, levelHome)) {
+            const filepath = join(dir, WORKFLOW_MODULE)
+            const source = workspace.atPath(filepath)
+            if (source !== undefined) return { filepath, source }
+          }
+          return undefined
+        },
+        catch: toError,
+      }),
+  })
+}
+
+/** One scripted `bash` command's canned behavior, keyed by the RENDERED command string a scenario's `Given` step declares. */
+export type ScriptedCommand =
+  | { readonly kind: "exit"; readonly status: number; readonly output: string }
+  | { readonly kind: "rewrite"; readonly file: string; readonly content: string }
+
+export interface TestWorldOptions {
+  readonly env?: Readonly<Record<string, string | undefined>>
+  readonly root?: string
+  /** Defaults to `root` — a real cwd→home chain has no natural counterpart in the fake, so a test not exercising it sees exactly one config level, same as before. */
+  readonly home?: string
+  /**
+   * Captures every narrated line — absent (the default) means the
+   * `Narrator` this builds is a no-op, exactly like a real invocation with no
+   * `--verbose`. A test asserting on narration passes its own sink here and
+   * gets every line regardless of `verbose` (see `verbose` below) — a direct
+   * Effect test has no `--verbose` flag of its own to gate on.
+   */
+  readonly narrate?: (line: string) => void
+  /** Gates `narrate` above — defaults to `true` (fires whenever a sink is given) since these tests aren't exercising `Cli.ts`'s own `--verbose` gate. `src/testkit/cliIo.ts` overrides this with the real decoded flag. */
+  readonly verbose?: boolean
+  /** Real or fake driver and tool commands — each one left out fails when called. */
+  readonly tools?: Partial<ToolCommands["Type"]>
+}
+
+const missingTool = (name: string) => () =>
+  Effect.fail(new Error(`gtd ${name}: ToolCommands has no test double wired into testLayers()`))
+
+const missingToolCommands: ToolCommands["Type"] = {
+  ui: missingTool("ui"),
+  lsp: missingTool("lsp"),
+  loop: missingTool("loop"),
+  judge: () =>
+    Promise.reject(
+      new Error("gtd judge run: ToolCommands has no test double wired into testLayers()"),
+    ),
+}
+
+/** The fine-grained `GitService` layer alone — for unit tests that need only git. */
+export const gitTestLayer = (repo: InMemRepo, root = "/repo"): Layer.Layer<GitService> =>
+  Layer.succeed(GitService, fakeGitOperations(repo, root))
+
+/** Every layer `makeProgram` needs — `CommandRequirements`'s return type here IS the guarantee: a new port added there fails this function's typecheck instead of silently under-providing. */
+export function testLayers(
+  repo: InMemRepo,
+  opts: TestWorldOptions = {},
+): Layer.Layer<CommandRequirements> {
+  const root = opts.root ?? "/repo"
+  const home = opts.home ?? root
+
+  return Layer.mergeAll(
+    gitTestLayer(repo, root),
+    Layer.succeed(Workspace, makeInMemoryWorkspaceOps(repo, root)),
+    // `realPath` is a no-op here (there is no real filesystem to resolve
+    // symlinks against): both sides of `assertRunningFromRepoRoot`'s
+    // comparison collapse to `root` when given anything, exactly like the
+    // fake's `root` "resolving" to itself before this port existed.
+    Host.layer({ root, home, env: opts.env ?? {}, realPath: () => Effect.succeed(root) }),
+    ConfigService.Live,
+    makeInMemoryConfigDiscovery(repo, root),
+    Narrator.layer(opts.narrate ?? (() => {}), opts.verbose ?? true),
+    // Drivers and tools are unit-tested in their own folders; a call reaching
+    // one of these is a test gap, not silence. A test opts into one via `tools`.
+    Layer.succeed(ToolCommands, { ...missingToolCommands, ...opts.tools }),
+    // The only `@inmem` scenarios that reach `gtd ui` refuse at a guard before
+    // its shell is touched (see `tests/integration/features/ui.feature`) — and
+    // gtd itself spawns no subprocess any more, so there is deliberately no
+    // scripted-command double to fall back on.
+    CommandRunner.layer(() =>
+      Effect.fail(new Error("gtd ui: CommandRunner has no test double wired into testLayers()")),
+    ),
+  )
+}

package/src/testkit/StrictGitOperations.ts

@@ -0,0 +1,31 @@
+import { Effect } from "effect"
+import type { GitOperations } from "../platform/index.js"
+import { TEST_DOUBLE_SENTINEL } from "./InMemRepo.js"
+
+/**
+ * A `GitOperations` Proxy: `overrides` supply the methods a test actually
+ * exercises; every other method fails loudly the moment it's called — no
+ * method list to keep in sync with `GitReaderOperations`/`GitWriterOperations`
+ * (unlike a plain object literal, which needs a case per port method).
+ * `message`, when given, replaces the default per-method wording (e.g.
+ * `Program.test.ts`'s "GitService must not be called for --version/--help").
+ */
+export const strictGitOperations = (
+  overrides: Partial<GitOperations>,
+  message?: (name: string) => string,
+): GitOperations =>
+  new Proxy(overrides, {
+    get(target, prop: string | symbol) {
+      if (typeof prop === "symbol" || prop in target) {
+        return (target as Record<string | symbol, unknown>)[prop as string]
+      }
+      const name = String(prop)
+      return () =>
+        Effect.fail(
+          new Error(
+            message?.(name) ??
+              `${name} should not have been called by this test (${TEST_DOUBLE_SENTINEL})`,
+          ),
+        )
+    },
+  }) as GitOperations

package/src/testkit/TestRepo.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest"
+import { agent, human, moveScript, read, removeScript, run } from "../flows/index.js"
+import { runsItsScript, testRepo } from "./TestRepo.js"
+
+const tiny = async (): Promise<void> => {
+  await agent("plan", "Write PLAN.md.")
+  await agent("build", `Build what PLAN.md says:\n${read("PLAN.md") ?? ""}`)
+  await run("check", "npm test > .gtd/FEEDBACK.md 2>&1 && rm .gtd/FEEDBACK.md")
+  if (read(".gtd/FEEDBACK.md") !== undefined) await agent("repair", "Make the suite pass.")
+  await human("sign-off")
+}
+
+describe("testRepo", () => {
+  it("drives a workflow module defined in the test with scripted agents until it rests", async () => {
+    const repo = testRepo({ workflow: { default: tiny } })
+    repo.write("IDEA.md", "a calculator\n")
+    const rest = await repo.drive({
+      plan: (_, r) => r.write("PLAN.md", "add two numbers\n"),
+      build: (beat, r) => {
+        expect(beat.content).toContain("add two numbers")
+        r.write("src/add.ts", "export const add = (a: number, b: number) => a + b\n")
+      },
+      check: () => undefined,
+    })
+    expect(rest).toMatchObject({ state: "sign-off", actor: "human" })
+    expect(repo.subjects()).toEqual([
+      "chore: initial commit",
+      "gtd(agent): plan → build",
+      "gtd(agent): build → check",
+      "gtd(check): check → sign-off",
+    ])
+    expect(repo.read("src/add.ts")).toContain("a + b")
+  })
+
+  it("runs a workflow given as gtd.config.ts source", async () => {
+    const repo = testRepo({
+      workflow: [
+        `import { agent, human } from "@pmelab/gtd/flows"`,
+        `export const chores = async () => { await agent("sweep", "Sweep."); await human("done") }`,
+        `export default chores`,
+      ].join("\n"),
+    })
+    await repo.start("chores")
+    const rest = await repo.drive({ sweep: (_, r) => r.write("swept", "yes\n") })
+    expect(rest.state).toBe("done")
+    expect(repo.subjects().at(-1)).toBe("gtd(agent): sweep → done")
+  })
+
+  it("runs the file operations a step's script does", async () => {
+    const tidy = async (): Promise<void> => {
+      await run("archive", moveScript("NOTES.md", "archive/NOTES.md"))
+      await run("sweep", removeScript(["scratch.txt"]))
+      await human("done")
+    }
+    const repo = testRepo({
+      workflow: { default: tidy, tidy },
+      files: { "NOTES.md": "notes\n", "scratch.txt": "x\n" },
+    })
+    await repo.start("tidy")
+    await repo.drive({ archive: runsItsScript, sweep: runsItsScript })
+    expect(repo.read("archive/NOTES.md")).toBe("notes\n")
+    expect(repo.read("NOTES.md")).toBeUndefined()
+    expect(repo.read("scratch.txt")).toBeUndefined()
+  })
+
+  it("removes a directory with everything in it, as `rm -rf` does", () => {
+    const repo = testRepo({
+      workflow: { default: tiny },
+      files: { "out/a.txt": "a\n", "out/deep/b.txt": "b\n", "outside.txt": "c\n" },
+    })
+    repo.runScript(removeScript(["out"]))
+    expect(repo.read("out/a.txt")).toBeUndefined()
+    expect(repo.read("out/deep/b.txt")).toBeUndefined()
+    expect(repo.read("outside.txt")).toBe("c\n")
+  })
+
+  it("refuses to remove an empty path rather than clear the tree", () => {
+    const repo = testRepo({ workflow: { default: tiny }, files: { "keep.txt": "k\n" } })
+    expect(() => repo.runScript(removeScript([""]))).toThrow(/refusing an empty path/)
+    expect(repo.read("keep.txt")).toBe("k\n")
+  })
+
+  it("leaves no workflow module registered once gtd returns, so tests cannot reach each other's", async () => {
+    const repo = testRepo({ workflow: { default: tiny } })
+    repo.write("IDEA.md", "x\n")
+    await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
+    const registry = (globalThis as Record<symbol, Map<string, unknown> | undefined>)[
+      Symbol.for("@pmelab/gtd/testkit:modules")
+    ]
+    expect(registry).toBeInstanceOf(Map)
+    expect(registry?.size).toBe(0)
+  })
+
+  it("refuses to fake a script it cannot run", () => {
+    const repo = testRepo({ workflow: { default: tiny } })
+    expect(() => repo.runScript("npm test\n")).toThrow(/cannot run `npm test` in memory/)
+  })
+
+  it("reads a file as committed", () => {
+    const repo = testRepo({ workflow: { default: tiny }, files: { "a.txt": "one\n" } })
+    repo.write("a.txt", "two\n")
+    repo.commit("chore: two")
+    expect(repo.show("HEAD~1", "a.txt")).toBe("one\n")
+    repo.runScript(`git show 'HEAD~1:a.txt' > 'b.txt'\n`)
+    expect(repo.read("b.txt")).toBe("one\n")
+  })
+
+  it("stops a process that never rests", async () => {
+    const loop = async (): Promise<void> => {
+      for (;;) await agent("spin", "Again.")
+    }
+    const repo = testRepo({ workflow: { default: loop } })
+    repo.write("go", "\n")
+    let n = 0
+    await expect(
+      repo.drive({ spin: (_, r) => r.write("n", `${++n}\n`) }, { maxBeats: 5 }),
+    ).rejects.toThrow(/did not rest within 5 beats/)
+  })
+})

package/src/testkit/TestRepo.ts

@@ -0,0 +1,274 @@
+import { Effect } from "effect"
+import { PassThrough } from "node:stream"
+import { runCli } from "../cli/index.js"
+import { EXIT_OK, type BeatDocument } from "../wire/index.js"
+import { makeCapturingCliIo, type CapturedCliResult } from "./cliIo.js"
+import { applyEmittedScript } from "./EmittedScriptRecognizer.js"
+import { InMemRepo } from "./InMemRepo.js"
+
+/**
+ * The repository's `gtd.config.ts`: its source, or the module itself. A module
+ * is handed to the engine through a global registry, so its functions run in
+ * this process against the same `@pmelab/gtd/flows` runtime the engine
+ * installs its context into.
+ */
+export type WorkflowModule = string | Readonly<Record<string, unknown>>
+
+export interface TestRepoOptions {
+  readonly workflow: WorkflowModule
+  /** Committed alongside the config, before any process starts. */
+  readonly files?: Readonly<Record<string, string>>
+  /** The environment gtd sees; the real `process.env` is never read. */
+  readonly env?: Readonly<Record<string, string>>
+}
+
+/** What a scripted actor does at the step it is registered for, before the beat lands. */
+export type Actor = (beat: BeatDocument, repo: TestRepo) => void | string | Promise<void | string>
+
+/**
+ * Scripted actors, keyed by full step name. At a judge step the actor returns
+ * the verdict, which is answered through `gtd judge answer`; anywhere else it
+ * edits the tree and the beat is landed.
+ */
+export type Actors = Readonly<Record<string, Actor>>
+
+export interface DriveOptions {
+  /** Fail instead of looping forever on a workflow that never rests. */
+  readonly maxBeats?: number
+}
+
+export interface TestRepo {
+  read(path: string): string | undefined
+  write(path: string, content: string): void
+  remove(path: string): void
+  /** Every pending change committed with `message`, outside any process. */
+  commit(message: string): void
+  /** `path` as committed at `ref`. */
+  show(ref: string, path: string): string | undefined
+  /**
+   * A step's script, run against the tree. Only the file operations the flows
+   * script helpers emit are understood; anything else (a test suite, a git
+   * write) throws, and the step needs an actor that stands in for it.
+   */
+  runScript(script: string): void
+  /** One in-process invocation; nothing it prints is run. */
+  gtd(...args: string[]): Promise<CapturedCliResult>
+  /** `gtd --workflow <name> [...args]`, its script applied. */
+  start(workflow: string, ...args: string[]): Promise<CapturedCliResult>
+  /** `gtd door <name> [...args]`, its script applied. */
+  door(name: string, ...args: string[]): Promise<CapturedCliResult>
+  land(): Promise<CapturedCliResult>
+  next(): Promise<BeatDocument>
+  /**
+   * Beat by beat, like a driver: a capture lands, a step with an actor runs it
+   * and lands, and the first step without one is where the process rests —
+   * returned for the test to inspect. A stall rests too. An agent turn's
+   * steering file is formatted and validated before it lands, as a driver
+   * does; a file that fails validation fails the drive.
+   */
+  drive(actors?: Actors, options?: DriveOptions): Promise<BeatDocument>
+  /** Oldest first. */
+  subjects(): readonly string[]
+}
+
+const REGISTRY = Symbol.for("@pmelab/gtd/testkit:modules")
+type Registry = Map<string, Readonly<Record<string, unknown>>>
+const registry = (): Registry => {
+  const global = globalThis as { [REGISTRY]?: Registry }
+  return (global[REGISTRY] ??= new Map())
+}
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/
+let registered = 0
+
+/** A config whose exports are module `id`'s, read off the registry when the engine loads it. */
+const moduleSource = (id: string, module: Readonly<Record<string, unknown>>): string => {
+  const lines = [
+    `const m = globalThis[Symbol.for(${JSON.stringify(REGISTRY.description)})].get(${JSON.stringify(id)})`,
+  ]
+  for (const name of Object.keys(module)) {
+    if (name === "default") lines.push(`export default m.default`)
+    else if (IDENTIFIER.test(name)) lines.push(`export const ${name} = m[${JSON.stringify(name)}]`)
+    else throw new Error(`testkit: export name "${name}" is not an identifier`)
+  }
+  return `${lines.join("\n")}\n`
+}
+
+/** An actor that runs the step's own script, for steps whose script `runScript` understands. */
+export const runsItsScript: Actor = (beat, repo) => repo.runScript(beat.content)
+
+const words = (text: string): string[] =>
+  [...text.matchAll(/'((?:[^']|'\\'')*)'/g)].map((m) => m[1]!.replaceAll("'\\''", "'"))
+
+const fileOf = (repo: InMemRepo, path: string, what: string): string => {
+  const content = repo.readFile(path)
+  if (content === undefined) throw new Error(`testkit: ${what}: ${path} does not exist`)
+  return content
+}
+
+// `InMemRepo.pathsUnder("")` is the whole tree, where a real `rm -- ''` removes nothing.
+const nonEmpty = (paths: string[]): string[] => {
+  if (paths.includes("")) throw new Error("testkit: rm: refusing an empty path")
+  return paths
+}
+
+/** The lines `runScript` understands, each with what it does to the tree. */
+const LINES: ReadonlyArray<readonly [RegExp, (repo: InMemRepo, words: string[]) => void]> = [
+  [/^$|^#!|^set [-+]e$|^mkdir -p /, () => undefined],
+  [
+    /^rm -rf -- /,
+    (repo, paths) => {
+      for (const path of nonEmpty(paths))
+        for (const file of repo.pathsUnder(path)) repo.deleteFile(file)
+    },
+  ],
+  [
+    /^rm -f -- /,
+    (repo, paths) => {
+      for (const path of paths) if (repo.readFile(path) !== undefined) repo.deleteFile(path)
+    },
+  ],
+  [
+    /^mv -- '.*' '.*'$/,
+    (repo, [from, to]) => {
+      const content = fileOf(repo, from!, "mv")
+      repo.deleteFile(from!)
+      repo.writeFile(to!, content)
+    },
+  ],
+  [
+    /^git show '.*' > '.*'$/,
+    (repo, [source, dest]) => {
+      const at = source!.indexOf(":")
+      const content = repo.fileAtRef(source!.slice(0, at), source!.slice(at + 1))
+      if (content === null) throw new Error(`testkit: git show: ${source} does not exist`)
+      repo.writeFile(dest!, content)
+    },
+  ],
+]
+
+const runLine = (repo: InMemRepo, line: string): void => {
+  const known = LINES.find(([pattern]) => pattern.test(line))
+  if (known === undefined) {
+    throw new Error(`testkit: cannot run \`${line}\` in memory — give the step an actor instead`)
+  }
+  known[1](repo, words(line))
+}
+
+const failed = (what: string, result: CapturedCliResult): Error =>
+  new Error(`${what} exited ${result.exitCode}\n${result.stderr}${result.stdout}`)
+
+export const testRepo = (options: TestRepoOptions): TestRepo => {
+  const repo = new InMemRepo()
+  const env = { ...options.env }
+  const { workflow } = options
+  const id = `module-${++registered}`
+  repo.writeFile(
+    "gtd.config.ts",
+    typeof workflow === "string" ? workflow : moduleSource(id, workflow),
+  )
+  for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content)
+  repo.commitAllWithPrefix("chore: initial commit")
+
+  // The module is registered only while gtd runs, so nothing outlives the
+  // call that loads it and no test can reach another's module.
+  const gtd = async (...args: string[]): Promise<CapturedCliResult> => {
+    const { io, result } = makeCapturingCliIo(repo, env)
+    if (typeof workflow !== "string") registry().set(id, workflow)
+    try {
+      await Effect.runPromise(runCli(["node", "gtd", ...args], io))
+    } finally {
+      registry().delete(id)
+    }
+    return result()
+  }
+
+  // `gtd judge answer` reads its verdict off stdin, so it is swapped for the call.
+  const withStdin = async <T>(stdin: string, fn: () => Promise<T>): Promise<T> => {
+    const saved = Object.getOwnPropertyDescriptor(process, "stdin")
+    const fake = new PassThrough()
+    Object.defineProperty(process, "stdin", { value: fake, configurable: true })
+    fake.end(stdin)
+    try {
+      return await fn()
+    } finally {
+      if (saved) Object.defineProperty(process, "stdin", saved)
+    }
+  }
+
+  const apply = (what: string, script: string): void => {
+    if (script.length === 0) return
+    const applied = applyEmittedScript(repo, new Map(), script)
+    if (!applied.ok) throw new Error(`${what}: its script failed — ${applied.error ?? ""}`)
+  }
+
+  /** Runs a write command, then the script its `--json=script` twin prints. */
+  const runWrite = async (args: readonly string[], stdin?: string): Promise<CapturedCliResult> => {
+    const call = (...extra: string[]) =>
+      stdin === undefined ? gtd(...args, ...extra) : withStdin(stdin, () => gtd(...args, ...extra))
+    const reported = await call()
+    if (reported.exitCode !== EXIT_OK) throw failed(`gtd ${args.join(" ")}`, reported)
+    const script = await call("--json=script")
+    apply(`gtd ${args.join(" ")}`, script.stdout)
+    return reported
+  }
+
+  // A start prints its script plainly; it has no `--json=script` twin.
+  const begin = async (args: readonly string[]): Promise<CapturedCliResult> => {
+    const result = await gtd(...args)
+    if (result.exitCode !== EXIT_OK) throw failed(`gtd ${args.join(" ")}`, result)
+    apply(`gtd ${args.join(" ")}`, result.stdout)
+    return result
+  }
+
+  const next = async (): Promise<BeatDocument> => {
+    const result = await gtd("next", "--json")
+    if (result.exitCode !== EXIT_OK) throw failed("gtd next --json", result)
+    return JSON.parse(result.stdout) as BeatDocument
+  }
+
+  /** Lands what an actor did: a judge's verdict answered, anything else validated and landed. */
+  const act = async (doc: BeatDocument, verdict: void | string): Promise<void> => {
+    if (doc.actor !== "judge") {
+      if (doc.validate !== undefined) apply(`validating ${doc.file ?? doc.state}`, doc.validate)
+      await runWrite(["land"])
+      return
+    }
+    if (typeof verdict !== "string") {
+      throw new Error(`the actor for judge step "${doc.state}" returned no verdict`)
+    }
+    await runWrite(["judge", "answer"], verdict)
+  }
+
+  const self: TestRepo = {
+    read: (path) => repo.readFile(path),
+    write: (path, content) => repo.writeFile(path, content),
+    remove: (path) => repo.deleteFile(path),
+    commit: (message) => repo.commitAllWithPrefix(message),
+    show: (ref, path) => repo.fileAtRef(ref, path) ?? undefined,
+    runScript: (script) => {
+      for (const line of script.split("\n")) runLine(repo, line.trim())
+    },
+    gtd,
+    start: (workflow, ...args) => begin(["--workflow", workflow, ...args]),
+    door: (name, ...args) => begin(["door", name, ...args]),
+    land: () => runWrite(["land"]),
+    next,
+    drive: async (actors = {}, { maxBeats = 50 } = {}) => {
+      for (let beat = 0; beat < maxBeats; beat++) {
+        const doc = await next()
+        if (doc.kind === "stalled") return doc
+        if (doc.kind === "capture") {
+          await runWrite(["land"])
+          continue
+        }
+        const actor = actors[doc.state]
+        if (actor === undefined) return doc
+        await act(doc, await actor(doc, self))
+      }
+      throw new Error(`the process did not rest within ${maxBeats} beats`)
+    },
+    subjects: () => repo.commitHistory().map(({ message }) => message.split("\n")[0] ?? ""),
+  }
+  return self
+}