@pmelab/gtd 63.0.0 → 64.0.0

package/src/twins/Host.test.ts

@@ -0,0 +1,151 @@
+import { realpathSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { isAbsolute } from "node:path"
+import { PassThrough } from "node:stream"
+import { Effect, Layer } from "effect"
+import { describe, expect, it } from "vitest"
+import { Host, nodeStdio, type HostOps, type NodeProcess, type Stdio } from "../platform/index.js"
+import { InMemRepo, inMemoryHost, makeCapturingCliIo } from "./index.js"
+
+type Env = Readonly<Record<string, string | undefined>>
+
+const root = realpathSync(process.cwd())
+
+const fakeProcess = (stdin: string | Buffer[], argv = ["node"]) => {
+  const input = new PassThrough()
+  for (const chunk of typeof stdin === "string" ? [stdin] : stdin) input.write(chunk)
+  input.end()
+  const out = { stdout: "", stderr: "" }
+  const sink = (name: keyof typeof out) => ({
+    write: (chunk: string | Uint8Array, done?: () => void) => {
+      out[name] += Buffer.from(chunk).toString("utf8")
+      done?.()
+      return true
+    },
+  })
+  const proc = {
+    argv,
+    execPath: "/usr/bin/node",
+    pid: 7,
+    getuid: () => 501,
+    stdin: input,
+    stdout: sink("stdout"),
+    stderr: sink("stderr"),
+    exitCode: undefined,
+  } as unknown as NodeProcess
+  return { proc, out }
+}
+
+// The core reaches the machine through `Host`: Node's process live, nothing real in memory.
+describe.each([
+  [
+    "live",
+    (env: Env, stdin: string | Buffer[]) =>
+      Host.layer({ root, home: root, env }, fakeProcess(stdin).proc),
+  ],
+  [
+    "in memory",
+    (env: Env, stdin: string | Buffer[]) =>
+      Layer.succeed(
+        Host,
+        inMemoryHost(
+          root,
+          root,
+          env,
+          typeof stdin === "string" ? stdin : Buffer.concat(stdin).toString("utf8"),
+        ),
+      ),
+  ],
+])("Host (%s)", (_, layer) => {
+  const run = <A>(
+    f: (host: HostOps) => A | Effect.Effect<A, Error>,
+    env: Env = {},
+    stdin: string | Buffer[] = "",
+  ): Promise<A> =>
+    Effect.runPromise(
+      Effect.flatMap(Host, (host) => {
+        const result = f(host)
+        return Effect.isEffect(result) ? result : Effect.succeed(result)
+      }).pipe(Effect.provide(layer(env, stdin))),
+    )
+
+  it("puts scratch files under TMPDIR when it is set", async () => {
+    expect(await run((host) => host.scratchDir, { TMPDIR: "/fixture-scratch" })).toBe(
+      "/fixture-scratch",
+    )
+  })
+
+  it("falls back to an absolute scratch dir when TMPDIR is unset or empty", async () => {
+    expect(isAbsolute(await run((host) => host.scratchDir))).toBe(true)
+    expect(await run((host) => host.scratchDir, { TMPDIR: "" })).toBe(
+      await run((host) => host.scratchDir),
+    )
+  })
+
+  it("reads stdin to its end as UTF-8, a character split across chunks included", async () => {
+    const bytes = Buffer.from("verdict: ✓\n")
+    const split = [bytes.subarray(0, 10), bytes.subarray(10)]
+    expect(await run((host) => host.stdin, {}, split)).toBe("verdict: ✓\n")
+    expect(await run((host) => host.stdin)).toBe("")
+  })
+
+  it("resolves the repository root to itself", async () => {
+    expect(await run((host) => host.realPath(root))).toBe(root)
+  })
+
+  it("names gtd off PATH when no script runs it, and has a process id", async () => {
+    const [self, pid] = await run((host) => [host.self, host.pid] as const)
+    expect(self).toEqual(["gtd"])
+    expect(Number.isInteger(pid)).toBe(true)
+  })
+})
+
+describe("Host (live) alone", () => {
+  const host = (proc: NodeProcess, env: Env = {}): Promise<HostOps> =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        return yield* Host
+      }).pipe(Effect.provide(Host.layer({ root, home: root, env }, proc))),
+    )
+
+  it("falls back to node:os's tmpdir()", async () => {
+    expect((await host(fakeProcess("").proc)).scratchDir).toBe(tmpdir())
+  })
+
+  it("runs itself again as its script under the running runtime", async () => {
+    const { proc } = fakeProcess("", ["node", "/opt/gtd/gtd.js", "lsp"])
+    const live = await host(proc)
+    expect([live.self, live.pid, live.uid]).toEqual([["/usr/bin/node", "/opt/gtd/gtd.js"], 7, 501])
+  })
+})
+
+// `runCli` writes through `Stdio` before any layer exists: Node's process live, a capture in memory.
+describe.each([
+  [
+    "live",
+    () => {
+      const { proc, out } = fakeProcess("")
+      return {
+        stdio: nodeStdio(proc),
+        seen: () => ({ ...out, exitCode: proc.exitCode }),
+      }
+    },
+  ],
+  [
+    "in memory",
+    () => {
+      const { io, result } = makeCapturingCliIo(new InMemRepo())
+      return { stdio: io as Stdio, seen: () => result() }
+    },
+  ],
+])("Stdio (%s)", (_, make) => {
+  it("writes stdout text and bytes, stderr, and exits with the code", () => {
+    const { stdio, seen } = make()
+    stdio.stdout("artifact")
+    stdio.stdout(new TextEncoder().encode(" bytes ✓"))
+    stdio.stderr("narration")
+    stdio.exit(3)
+    const { stdout, stderr, exitCode } = seen()
+    expect([stdout, stderr, exitCode]).toEqual(["artifact bytes ✓", "narration", 3])
+  })
+})

package/src/twins/Layers.test.ts

@@ -2,7 +2,7 @@ import { Effect } from "effect"
 import { describe, expect, it } from "vitest"
 import { ConfigDiscovery, LEGACY_RC_FILES, walkUp } from "../workflow/index.js"
 import { InMemRepo } from "./index.js"
-import { ambientFlagEnv, testLayers } from "./Layers.js"
+import { ambientFlagEnv, inMemPath, testLayers } from "./Layers.js"
 import { Host } from "../platform/index.js"
 
 // The in-memory `ConfigDiscovery` counterpart walks the SAME root→home chain
@@ -40,7 +40,7 @@ describe("the in-memory ConfigDiscovery counterpart", () => {
     seed(repo, ROOT, LEGACY_RC_FILES[1]!, "{}\n")
     seed(repo, ABOVE_HOME, LEGACY_RC_FILES[0]!, "never-walked: true\n")
     const found = (await runDiscovery(repo, (d) => d.legacyRcFiles(ROOT, HOME))).map((f) => f.path)
-    expect(walkUp(ROOT, HOME)).toEqual([ROOT, MIDDLE, HOME])
+    expect(walkUp(inMemPath, ROOT, HOME)).toEqual([ROOT, MIDDLE, HOME])
     expect(found).toEqual([
       `${ROOT}/${LEGACY_RC_FILES[0]}`,
       `${ROOT}/${LEGACY_RC_FILES[1]}`,

package/src/twins/Layers.ts

@@ -8,12 +8,13 @@
 // 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 { Effect, Layer, Path } from "effect"
 import {
   Narrator,
   GitService,
   Host,
+  type HostOps,
+  scratchDirOf,
   Workspace,
   type WorkspaceOps,
   CommandRunner,
@@ -48,6 +49,10 @@ const toError = (e: unknown): Error => (e instanceof Error ? e : new Error(Strin
  */
 const isGitDirKey = (key: string): boolean => key.startsWith(".git/")
 
+// The in-memory tier's `Path`: Effect's own POSIX one, which needs no Node.
+export const inMemPath = Effect.runSync(Effect.provide(Path.Path, Path.layer))
+const paths = inMemPath
+
 /**
  * `Workspace` for the in-memory tier. `readSync`/`read`/`write`/`committed`
  * take a repo-relative key ONLY (mirroring the live adapter's
@@ -63,12 +68,12 @@ const isGitDirKey = (key: string): boolean => key.startsWith(".git/")
  */
 export const makeInMemoryWorkspaceOps = (repo: InMemRepo, root: string): WorkspaceOps => {
   const toKey = (path: string): string => {
-    if (!isAbsolute(path)) return path
+    if (!paths.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)) {
+    if (paths.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)`,
       )
@@ -146,8 +151,8 @@ const makeInMemoryConfigDiscovery = (
     legacyRcFiles: (levelRoot, levelHome) =>
       Effect.try({
         try: () =>
-          legacyRcDirs(levelRoot, levelHome).flatMap((dir) =>
-            LEGACY_RC_FILES.map((name) => join(dir, name))
+          legacyRcDirs(paths, levelRoot, levelHome).flatMap((dir) =>
+            LEGACY_RC_FILES.map((name) => paths.join(dir, name))
               .filter((filepath) => workspace.atPath(filepath) !== undefined)
               .map((path) => ({ path, owned: true })),
           ),
@@ -156,8 +161,8 @@ const makeInMemoryConfigDiscovery = (
     workflowModule: (levelRoot, levelHome) =>
       Effect.try({
         try: () => {
-          for (const dir of walkUp(levelRoot, levelHome)) {
-            const filepath = join(dir, WORKFLOW_MODULE)
+          for (const dir of walkUp(paths, levelRoot, levelHome)) {
+            const filepath = paths.join(dir, WORKFLOW_MODULE)
             const source = workspace.atPath(filepath)
             if (source !== undefined) return { filepath, source, read: workspace.atPath }
           }
@@ -214,6 +219,8 @@ export interface TestWorldOptions {
   readonly verbose?: boolean
   /** Real or fake driver and tool commands — each one left out fails when called. */
   readonly tools?: Partial<ToolCommands["Service"]>
+  /** What gtd reads on stdin; empty by default, like a closed pipe. */
+  readonly stdin?: string
 }
 
 const missingTool = (name: string) => () =>
@@ -247,6 +254,33 @@ export const ambientFlagEnv = (
     ),
   )
 
+/** Where the in-memory host's scratch files go when `TMPDIR` is unset. */
+export const IN_MEMORY_SCRATCH = "/scratch"
+export const IN_MEMORY_PID = 4242
+
+/**
+ * The in-memory `Host`: nothing read off the real process or `node:os`.
+ * `realPath` is a no-op (there is no real filesystem to resolve symlinks
+ * against), so both sides of `assertRunningFromRepoRoot`'s comparison
+ * collapse to `root`.
+ */
+export const inMemoryHost = (
+  root: string,
+  home: string,
+  env: Readonly<Record<string, string | undefined>>,
+  stdin = "",
+): HostOps => ({
+  root,
+  home,
+  env,
+  scratchDir: scratchDirOf(env, IN_MEMORY_SCRATCH),
+  realPath: () => Effect.succeed(root),
+  pid: IN_MEMORY_PID,
+  uid: undefined,
+  self: ["gtd"],
+  stdin: Effect.succeed(stdin),
+})
+
 /** 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,
@@ -258,20 +292,12 @@ export function testLayers(
   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: { ...ambientFlagEnv(), ...opts.env },
-      realPath: () => Effect.succeed(root),
-    }),
+    Layer.succeed(Host, inMemoryHost(root, home, { ...ambientFlagEnv(), ...opts.env }, opts.stdin)),
     ConfigService.Live,
     makeInMemoryConfigDiscovery(repo, root),
     Layer.succeed(EngineCore, { source: Effect.succeed(IN_MEMORY_ENGINE) }),
     Narrator.layer(opts.narrate ?? (() => {}), opts.verbose ?? true),
+    Path.layer,
     // 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 }),

package/src/twins/Path.test.ts

@@ -0,0 +1,52 @@
+import { Effect, Layer, Path } from "effect"
+import { describe, expect, it } from "vitest"
+import { NodeServices } from "../platform/index.js"
+import { InMemRepo, testLayers } from "./index.js"
+
+// The core reaches paths through `Path`: Node's live, Effect's own POSIX one in memory.
+describe.each([
+  ["live", NodeServices.layer as Layer.Layer<Path.Path>],
+  ["in memory", testLayers(new InMemRepo())],
+])("Path (%s)", (_, layer) => {
+  const run = <A>(f: (path: Path.Path) => A | Effect.Effect<A, unknown>): Promise<A> =>
+    Effect.runPromise(
+      Effect.flatMap(Path.Path, (path) => {
+        const result = f(path)
+        return Effect.isEffect(result) ? result : Effect.succeed(result)
+      }).pipe(Effect.provide(layer)),
+    )
+
+  it("joins, splits and relates paths", async () => {
+    expect(
+      await run((path) => [
+        path.sep,
+        path.join("/repo", ".gtd", "../gtd.config.ts"),
+        path.dirname("/repo/.gtd/TODO.md"),
+        path.dirname("/"),
+        path.resolve("/repo", "lib/flow.ts"),
+        path.resolve("/repo", "/elsewhere"),
+        path.relative("/repo", "/repo/lib/flow.ts"),
+        path.relative("/repo", "/home/.gtdrc"),
+        path.isAbsolute("/repo"),
+        path.isAbsolute("lib/flow.ts"),
+      ]),
+    ).toEqual([
+      "/",
+      "/repo/gtd.config.ts",
+      "/repo/.gtd",
+      "/",
+      "/repo/lib/flow.ts",
+      "/elsewhere",
+      "lib/flow.ts",
+      "../home/.gtdrc",
+      true,
+      false,
+    ])
+  })
+
+  it("converts a path to a file URL and back", async () => {
+    const url = await run((path) => path.toFileUrl("/repo/a b.ts"))
+    expect(url.href).toBe("file:///repo/a%20b.ts")
+    expect(await run((path) => path.fromFileUrl(url))).toBe("/repo/a b.ts")
+  })
+})

package/src/twins/SyncIo.test.ts

@@ -0,0 +1,153 @@
+import { execFileSync } from "node:child_process"
+import { mkdtempSync, realpathSync, rmSync, symlinkSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { nodeSyncIo, type SyncIo } from "../platform/index.js"
+import { InMemRepo, inMemorySyncIo } from "./index.js"
+
+interface Tier {
+  readonly io: SyncIo
+  /** A git repository, empty until `commit`. */
+  readonly root: string
+  readonly uid: number | undefined
+  readonly symlink: (path: string, target: string) => void
+  /** Commits `files`, repository-relative, as the only change. */
+  readonly commit: (files: Record<string, string>) => void
+}
+
+const cleanups: (() => void)[] = []
+afterEach(() => cleanups.splice(0).forEach((cleanup) => cleanup()))
+
+const liveTier = (): Tier => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-sync-io-")))
+  cleanups.push(() => rmSync(root, { recursive: true, force: true }))
+  const git = (...args: string[]) => execFileSync("git", args, { cwd: root, stdio: "ignore" })
+  git("init", "-q")
+  return {
+    io: nodeSyncIo,
+    root,
+    uid: process.getuid?.(),
+    symlink: (path, target) => symlinkSync(target, path),
+    commit: (files) => {
+      for (const [path, content] of Object.entries(files))
+        nodeSyncIo.writeText(join(root, path), content)
+      git("add", "-A")
+      git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "c")
+    },
+  }
+}
+
+const inMemTier = (): Tier => {
+  const repo = new InMemRepo()
+  const root = "/repo"
+  const io = inMemorySyncIo({ repo, root, uid: 501 })
+  io.makeDirectory(root)
+  return {
+    io,
+    root,
+    uid: 501,
+    symlink: io.symlink,
+    commit: (files) => {
+      for (const [path, content] of Object.entries(files)) {
+        io.writeText(`${root}/${path}`, content)
+        repo.writeFile(path, content)
+      }
+      repo.seedCommit("c")
+    },
+  }
+}
+
+describe.each([
+  ["live", liveTier],
+  ["in memory", inMemTier],
+])("SyncIo (%s)", (_, makeTier) => {
+  it("reads absence as a value and a directory as a fault", () => {
+    const { io, root } = makeTier()
+    io.writeText(`${root}/file`, "x")
+
+    expect(io.readText(`${root}/missing`)).toBeUndefined()
+    expect(io.readFile(`${root}/file/below`)).toBeUndefined()
+    expect(() => io.readText(root)).toThrow()
+  })
+
+  it("writes text and reads it back as text and bytes", () => {
+    const { io, root } = makeTier()
+    io.makeDirectory(`${root}/a/b`)
+    io.makeDirectory(`${root}/a/b`)
+    io.writeText(`${root}/a/b/f`, "\uFEFFhéllo")
+
+    expect(io.readText(`${root}/a/b/f`)).toBe("\uFEFFhéllo")
+    expect(new Uint8Array(io.readFile(`${root}/a/b/f`)!)).toEqual(
+      new TextEncoder().encode("\uFEFFhéllo"),
+    )
+    expect(() => io.writeText(`${root}/none/f`, "x")).toThrow()
+  })
+
+  it("renames a file over another, and over a symlink rather than through it", () => {
+    const { io, root, symlink } = makeTier()
+    io.writeText(`${root}/from`, "new")
+    io.writeText(`${root}/to`, "old")
+    io.rename(`${root}/from`, `${root}/to`)
+    io.writeText(`${root}/other`, "moved")
+    symlink(`${root}/link`, "to")
+    io.rename(`${root}/other`, `${root}/link`)
+
+    expect(io.readText(`${root}/from`)).toBeUndefined()
+    expect(io.readText(`${root}/to`)).toBe("new")
+    expect(io.lstat(`${root}/link`)?.type).toBe("file")
+    expect(io.readText(`${root}/link`)).toBe("moved")
+  })
+
+  it("stats through a symlink, lstats the link itself, and resolves real paths", () => {
+    const { io, root, uid, symlink } = makeTier()
+    io.makeDirectory(`${root}/dir`)
+    io.writeText(`${root}/dir/f`, "x")
+    symlink(`${root}/link`, "dir")
+    symlink(`${root}/dangling`, "nowhere")
+
+    expect(io.stat(`${root}/dir/f`)).toEqual({ type: "file", uid })
+    expect(io.stat(`${root}/link`)).toEqual({ type: "directory", uid })
+    expect(io.lstat(`${root}/link`)).toEqual({ type: "symlink", uid })
+    expect(io.lstat(`${root}/missing`)).toBeUndefined()
+    expect(io.stat(`${root}/dangling`)).toBeUndefined()
+    expect(io.readLink(`${root}/link`)).toBe("dir")
+    expect(io.realPath(`${root}/link/f`)).toBe(`${root}/dir/f`)
+    expect(io.readText(`${root}/link/f`)).toBe("x")
+    expect(() => io.realPath(`${root}/dangling`)).toThrow()
+  })
+
+  it("reads committed content through git", () => {
+    const { io, root, commit } = makeTier()
+    commit({ "a.txt": "committed\n" })
+
+    expect(io.git(root, ["show", "HEAD:a.txt"])).toBe("committed\n")
+    expect(new Uint8Array(io.gitBytes(root, ["show", "HEAD:a.txt"]))).toEqual(
+      new TextEncoder().encode("committed\n"),
+    )
+    expect(io.git(root, ["rev-parse", "--show-object-format"])).toBe("sha1\n")
+    expect(io.git(root, ["rev-parse", "HEAD"])).toMatch(/^[0-9a-f]{40}\n$/)
+    expect(() => io.git(root, ["show", "HEAD:missing"])).toThrow()
+    expect(() => io.gitBytes(root, ["show", "HEAD:missing"])).toThrow()
+  })
+
+  it("hashes like git and the standard test vectors", () => {
+    const { io } = makeTier()
+    const million = "a".repeat(1_000_000)
+
+    expect(io.hash("sha1", "blob 5\0", new TextEncoder().encode("hello"))).toBe(
+      "b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0",
+    )
+    expect(io.hash("sha1", "")).toBe("da39a3ee5e6b4b0d3255bfef95601890afd80709")
+    expect(io.hash("sha1", million)).toBe("34aa973cd4c4daa4f61eeb2bdbad27316534016f")
+    expect(io.hash("sha256", "abc")).toBe(
+      "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+    )
+    expect(io.hash("sha256", "a".repeat(55), "a".repeat(9))).toBe(
+      "ffe054fe7ae0cb6dc65c3af9b61d5209f439851db43d0ba5997337df154668eb",
+    )
+    expect(io.hash("sha256", million)).toBe(
+      "cdc76e5c9914fb9281a1c7e284d73e67f1809a48a497200e046d39ccc7112cd0",
+    )
+  })
+})

package/src/twins/SyncIo.ts

@@ -0,0 +1,159 @@
+import { pureHash, type FileInfo, type SyncIo } from "../platform/index.js"
+import type { InMemRepo } from "./InMemRepo.js"
+
+const MAX_LINKS = 40
+
+const fault = (code: string, op: string, path: string): Error =>
+  Object.assign(new Error(`${code}: ${op} '${path}'`), { code })
+
+const parentOf = (path: string): string => path.slice(0, path.lastIndexOf("/")) || "/"
+
+const joined = (dir: string, name: string): string => (dir === "/" ? `/${name}` : `${dir}/${name}`)
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder("utf-8", { ignoreBOM: true })
+
+export interface InMemorySyncIo extends SyncIo {
+  readonly symlink: (path: string, target: string) => void
+}
+
+/**
+ * A POSIX file system in memory, absolute paths only. Its git answers the
+ * reads gtd makes from `repo`, rooted at `root`.
+ */
+export const inMemorySyncIo = (
+  opts: { readonly repo?: InMemRepo; readonly root?: string; readonly uid?: number } = {},
+): InMemorySyncIo => {
+  const files = new Map<string, Uint8Array>()
+  const links = new Map<string, string>()
+  const dirs = new Set<string>(["/"])
+
+  /** `path` with every symlink resolved, the last component's only when `followLast`. */
+  const resolve = (path: string, followLast: boolean): string => {
+    let pending = path.split("/").filter((part) => part.length > 0)
+    let at = "/"
+    let hops = 0
+    while (pending.length > 0) {
+      const [name, ...rest] = pending as [string, ...string[]]
+      pending = rest
+      if (name === ".") continue
+      if (name === "..") {
+        at = parentOf(at)
+        continue
+      }
+      const next = joined(at, name)
+      const target = links.get(next)
+      if (target === undefined || (rest.length === 0 && !followLast)) {
+        at = next
+        continue
+      }
+      if (++hops > MAX_LINKS) throw fault("ELOOP", "resolve", path)
+      if (target.startsWith("/")) at = "/"
+      pending = [...target.split("/").filter((part) => part.length > 0), ...rest]
+    }
+    return at
+  }
+
+  const typeOf = (path: string): FileInfo["type"] | undefined =>
+    links.has(path)
+      ? "symlink"
+      : files.has(path)
+        ? "file"
+        : dirs.has(path)
+          ? "directory"
+          : undefined
+
+  const parentExists = (path: string): boolean =>
+    typeOf(resolve(parentOf(path), true)) === "directory"
+
+  const info = (path: string): FileInfo | undefined => {
+    const type = typeOf(path)
+    return type === undefined ? undefined : { type, uid: opts.uid }
+  }
+
+  const readFile = (path: string): Uint8Array | undefined => {
+    const real = resolve(path, true)
+    if (dirs.has(real)) throw fault("EISDIR", "read", path)
+    return files.get(real)
+  }
+
+  const writeFile = (path: string, content: Uint8Array): void => {
+    const real = resolve(path, true)
+    if (!parentExists(real)) throw fault("ENOENT", "open", path)
+    if (dirs.has(real)) throw fault("EISDIR", "open", path)
+    files.set(real, content)
+  }
+
+  const makeDirectory = (path: string): void => {
+    const real = resolve(path, true)
+    const type = typeOf(real)
+    if (type === "directory") return
+    if (type !== undefined) throw fault("EEXIST", "mkdir", path)
+    makeDirectory(parentOf(real))
+    dirs.add(real)
+  }
+
+  const show = (repo: InMemRepo, spec: string): string => {
+    const colon = spec.indexOf(":")
+    const content = repo.fileAtRef(spec.slice(0, colon), spec.slice(colon + 1))
+    if (content === null) throw new Error(`fatal: invalid object name '${spec}'`)
+    return content
+  }
+
+  const revParse = (repo: InMemRepo, arg: string): string => {
+    if (arg === "--show-object-format") return "sha1\n"
+    const hash = repo.resolveRef(arg)
+    if (hash === null) throw new Error(`fatal: ambiguous argument '${arg}'`)
+    return `${hash}\n`
+  }
+
+  const git = (cwd: string, args: readonly string[]): string => {
+    const { repo, root } = opts
+    if (repo === undefined || resolve(cwd, true) !== root) {
+      throw new Error(`fatal: not a git repository: ${cwd}`)
+    }
+    const [command, arg, ...rest] = args
+    if (arg === undefined || rest.length > 0 || (command !== "show" && command !== "rev-parse")) {
+      throw new Error(`in-memory git: unsupported \`git ${args.join(" ")}\``)
+    }
+    return command === "show" ? show(repo, arg) : revParse(repo, arg)
+  }
+
+  return {
+    readFile,
+    readText: (path) => {
+      const bytes = readFile(path)
+      return bytes === undefined ? undefined : decoder.decode(bytes)
+    },
+    writeText: (path, content) => writeFile(path, encoder.encode(content)),
+    makeDirectory,
+    rename: (from, to) => {
+      const source = resolve(from, false)
+      const target = resolve(to, false)
+      const bytes = files.get(source)
+      if (bytes === undefined) throw fault("ENOENT", "rename", from)
+      if (!parentExists(target)) throw fault("ENOENT", "rename", to)
+      links.delete(target)
+      files.set(target, bytes)
+      files.delete(source)
+    },
+    stat: (path) => info(resolve(path, true)),
+    lstat: (path) => info(resolve(path, false)),
+    readLink: (path) => {
+      const target = links.get(resolve(path, false))
+      if (target === undefined) throw fault("EINVAL", "readlink", path)
+      return target
+    },
+    realPath: (path) => {
+      const real = resolve(path, true)
+      if (typeOf(real) === undefined) throw fault("ENOENT", "realpath", path)
+      return real
+    },
+    git,
+    gitBytes: (cwd, args) => encoder.encode(git(cwd, args)),
+    hash: pureHash,
+    symlink: (path, target) => {
+      links.set(resolve(path, false), target)
+    },
+  }
+}

package/src/twins/cliIo.ts

@@ -14,6 +14,7 @@ export const makeCapturingCliIo = (
   repo: InMemRepo,
   env: Readonly<Record<string, string | undefined>> = {},
   tools: Partial<ToolCommands["Service"]> = {},
+  stdin = "",
 ): { readonly io: CliIo; readonly result: () => CapturedCliResult } => {
   let stdout: Buffer = Buffer.alloc(0)
   let stderr = ""
@@ -32,7 +33,13 @@ export const makeCapturingCliIo = (
     // errors into — narration lands in the exact same buffer, exactly like a
     // real invocation's narration and remediation share one fd.
     layers: (verbose) =>
-      testLayers(repo, { env, narrate: (line) => (stderr += line), verbose, tools }),
+      testLayers(repo, {
+        env,
+        narrate: (line) => (stderr += line),
+        verbose,
+        tools,
+        stdin,
+      }),
   }
   return {
     io,