@pmelab/gtd 63.0.0 → 64.1.0

package/src/testkit/TestRepo.test.ts

@@ -61,7 +61,7 @@ describe("testRepo", () => {
     expect(repo.subjects()).toEqual([
       "chore: initial commit",
       "gtd(agent): plan → build",
-      "gtd(check): pin → build",
+      "gtd(check): gtd:pin → build",
       "gtd(agent): build → check",
       "gtd(check): check → sign-off",
     ])

package/src/testkit/TestRepo.ts

@@ -1,5 +1,4 @@
 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 {
@@ -450,8 +449,8 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
 
   // The modules are registered only while gtd runs, so nothing outlives the
   // call that loads them and no test can reach another's module.
-  const gtd = async (...args: string[]): Promise<CapturedCliResult> => {
-    const { io, result } = makeCapturingCliIo(repo, seenEnv())
+  const gtdWithStdin = async (stdin: string, ...args: string[]): Promise<CapturedCliResult> => {
+    const { io, result } = makeCapturingCliIo(repo, seenEnv(), {}, stdin)
     if (typeof workflow !== "string") registry().set(id, workflow)
     for (const [specifier, module] of modules) registry().set(moduleKey(specifier), module)
     try {
@@ -462,19 +461,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     }
     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 gtd = (...args: string[]): Promise<CapturedCliResult> => gtdWithStdin("", ...args)
 
   const apply = (what: string, script: string): void => {
     if (script.length === 0) return
@@ -488,8 +475,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     stdin?: string,
     refused: (error: Error) => Error = (error) => error,
   ): Promise<CapturedCliResult> => {
-    const call = (...extra: string[]) =>
-      stdin === undefined ? gtd(...args, ...extra) : withStdin(stdin, () => gtd(...args, ...extra))
+    const call = (...extra: string[]) => gtdWithStdin(stdin ?? "", ...args, ...extra)
     const reported = await call()
     if (reported.exitCode !== EXIT_OK) throw refused(failed(`gtd ${args.join(" ")}`, reported))
     const script = await call("--json=script")

package/src/twins/EmittedScriptRecognizer.ts

@@ -32,6 +32,7 @@ import {
 import {
   BUILT_IN_MODE_NAMES,
   formatFinding,
+  formatFromSpec,
   steeringFormatFor,
   type SteeringFormat,
 } from "../steering/internal.js"
@@ -538,13 +539,14 @@ const recognizeModeContradictionCheck = (
 
 const GTD_CHECK_RE = /^gtd check (\S+) (.+)$/
 
-/** `gtd check <mode> <file>` — a non-empty findings array fails the script, mirroring a real invocation's non-zero exit under `set -e`. */
+/** `gtd check <mode> <file> [--spec <json>]` — a non-empty findings array fails the script, mirroring a real invocation's non-zero exit under `set -e`. */
 const recognizeGtdCheck = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
   const match = GTD_CHECK_RE.exec(block)
   if (!match) return undefined
   const mode = match[1]!
-  const [file] = extractQuotedTokens(match[2]!)
-  const format = steeringFormatFor(mode)
+  const [file, spec] = extractQuotedTokens(match[2]!)
+  const declared = / --spec '/.test(match[2]!)
+  const format = declared && spec !== undefined ? formatFromSpec(spec) : steeringFormatFor(mode)
   if (format === undefined || file === undefined) {
     const known = BUILT_IN_MODE_NAMES.join(", ")
     return { kind: "failed", error: `gtd check: unknown mode "${mode}" — known modes: ${known}` }

package/src/twins/EmittedScripts.test.ts

@@ -16,6 +16,8 @@ import {
 import { Effect } from "effect"
 import { ScriptSurface } from "../emit/index.js"
 import { GitService } from "../platform/index.js"
+import { listFormat } from "../steering/index.js"
+import { declaredValidateCommand } from "../workflow/index.js"
 import { gitTiers, type GitTier, type ScriptedCommand } from "./index.js"
 
 // Every case runs through real `sh` — with this build's `gtd` on PATH — and
@@ -158,6 +160,23 @@ for (const makeTier of gitTiers) {
           ),
         )
       })
+
+      it("checks a declared format from the spec on its command line", () => {
+        const ids = listFormat({
+          name: "ids",
+          item: { id: /^A-\d+$/, separator: ":", example: "A-1" },
+          ids: { unique: true },
+        })
+        const check = declaredValidateCommand("ids", ids.spec).replace('"$GTD_FILE"', `'${FILE}'`)
+        t.seed.writeFile(FILE, "- A-1: it's\n")
+        expect(run(script(check))).toEqual({ ok: true, status: 0, output: "" })
+        t.seed.writeFile(FILE, "- A-1: a\n- A-1: b\n")
+        const result = run(script(check))
+        expect(result).toMatchObject({ ok: false, status: 1 })
+        expect(result.output).toBe(
+          `gtd check: ${FILE} is not valid under mode "ids" (1 finding(s)):\n${FILE}:2: duplicate ID A-1 — first on line 1\n`,
+        )
+      })
     })
 
     it("gtd uncheck clears a review file's ticks", () => {

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",
+    )
+  })
+})