@pmelab/gtd 24.2.0 → 24.4.0

package/src/testkit/GitTiers.ts

@@ -5,11 +5,13 @@ import {
   writeFileSync,
   existsSync,
   readFileSync,
+  readdirSync,
   realpathSync,
+  statSync,
 } from "node:fs"
-import { join, dirname, basename } from "node:path"
+import { join, dirname, basename, sep } from "node:path"
 import { tmpdir } from "node:os"
-import { execSync, execFileSync } from "node:child_process"
+import { execFileSync, execSync, spawnSync } from "node:child_process"
 // Imported directly (not just from *.test.ts) — a leak of this module into
 // the shipped CLI bundle would try to inline `vitest` and fail the build
 // loudly (`deps.alwaysBundle` in `tsdown.config.ts`), a guard alongside the
@@ -26,10 +28,12 @@ import {
   hardResetTo,
   discardPending,
   updateRef,
+  fetchHistoryRefs,
   deleteRef,
 } from "../emit/index.js"
+import { applyEmittedScript } from "./EmittedScriptRecognizer.js"
 import { InMemRepo } from "./InMemRepo.js"
-import { gitTestLayer } from "./Layers.js"
+import { gitTestLayer, type ScriptedCommand } from "./Layers.js"
 
 export interface GitTierCapabilities {
   /** Assert file BYTES on disk, not just index/HEAD state (`hardResetTo`) — only the Live tier has a real working-tree file to read back. */
@@ -40,6 +44,8 @@ export interface GitTierCapabilities {
   readonly linkedWorktrees: boolean
   /** A cwd→home directory chain for config discovery — both tiers walk it through `Workspace`/`Host` now, so this is `true` for either. */
   readonly directoryChainConfig: boolean
+  /** Fetch from another repository — only the Live tier has a remote to reach. */
+  readonly remotes: boolean
 }
 
 export interface GitTierSeed {
@@ -58,6 +64,11 @@ export interface GitTierObserve {
   readonly refExists: (ref: string) => boolean
   readonly readWorktreeFile: (path: string) => string
   readonly existsPath: (path: string) => boolean
+  /** Everything git keeps on disk; equal snapshots mean nothing was written. Settles git's racy-index stat refresh first. */
+  readonly snapshot: () => Promise<string>
+  readonly headSubject: () => string
+  /** Paths HEAD's own commit touched, against its parent — not the whole tree. */
+  readonly headTouchedPaths: () => ReadonlyArray<string>
 }
 
 export interface GitTier {
@@ -73,6 +84,15 @@ export interface GitTier {
   readonly emptyRepo: () => GitTier
   readonly seed: GitTierSeed
   readonly observe: GitTierObserve
+  /**
+   * Runs a script gtd hands a driver: real `sh` on Live, the in-memory twin on
+   * InMemory. `commands` declares what each program a check runs does — Live
+   * runs the real thing, so a contract case passes only when the two agree.
+   */
+  readonly runScript: (
+    script: string,
+    commands?: ReadonlyMap<string, ScriptedCommand>,
+  ) => { readonly ok: boolean; readonly status: number; readonly output: string }
   readonly dispose: () => void
 }
 
@@ -88,6 +108,18 @@ const makeLiveTier = (initialCommit = true): GitTier => {
   // symlink to `/private/tmp` — `git` reports the resolved path).
   const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-git-tier-")))
   const gitExec = (...args: string[]) => gitExecIn(root, ...args)
+  // Distinct, increasing committer dates, so ref ordering by tip date is deterministic.
+  let tick = 0
+  const commitEnv = () => ({
+    ...process.env,
+    GIT_COMMITTER_DATE: new Date(Date.UTC(2024, 0, 1, 0, 0, ++tick)).toISOString(),
+  })
+  const gitCommit = (message: string, allowEmpty = false) =>
+    execFileSync("git", ["commit", ...(allowEmpty ? ["--allow-empty"] : []), "-m", message], {
+      cwd: root,
+      env: commitEnv(),
+      stdio: "pipe",
+    })
   gitExec("init")
   gitExec(`config user.email "test@test.com"`)
   gitExec(`config user.name "Test"`)
@@ -95,7 +127,7 @@ const makeLiveTier = (initialCommit = true): GitTier => {
   if (initialCommit) {
     writeFileSync(join(root, "readme.txt"), "hello")
     gitExec("add", "-A")
-    gitExec(`commit -m "init: first commit"`)
+    gitCommit("init: first commit")
   }
 
   const provide = <A>(eff: Effect.Effect<A, Error, GitService | Narrator>): Promise<A> =>
@@ -128,6 +160,7 @@ const makeLiveTier = (initialCommit = true): GitTier => {
       commitHooks: true,
       linkedWorktrees: true,
       directoryChainConfig: true,
+      remotes: true,
     },
     provide,
     provideExit,
@@ -142,7 +175,7 @@ const makeLiveTier = (initialCommit = true): GitTier => {
         // --allow-empty: a caller passing `files: {}` (no prior staged
         // change either) means a deliberate empty commit — the state-entry
         // shape many test seeders rely on.
-        gitExec(`commit --allow-empty -m "${message}"`)
+        gitCommit(message, true)
       },
       writeFile: (path, content) => {
         mkdirSync(dirname(join(root, path)), { recursive: true })
@@ -174,11 +207,51 @@ const makeLiveTier = (initialCommit = true): GitTier => {
       },
       readWorktreeFile: (path) => readFileSync(join(root, path), "utf8"),
       existsPath: (path) => existsSync(join(root, path)),
+      snapshot: async () => {
+        // A tracked file's mtime in the same second as the index makes the next
+        // `git status` rewrite the index — git's own racy-git refresh, not a write
+        // of ours. Let the clock pass it before taking the baseline.
+        gitExec("status", "--porcelain")
+        await new Promise((r) => setTimeout(r, 1100))
+        gitExec("status", "--porcelain")
+        const gitDir = join(root, ".git")
+        const files = readdirSync(gitDir, { recursive: true, withFileTypes: true })
+          .filter((entry) => entry.isFile())
+          .map((entry) => join(entry.parentPath, entry.name))
+          .filter((path) => !path.includes(`${sep}gtd-cache${sep}`))
+          .sort()
+          .map((path) => `${path}:${statSync(path).size}:${statSync(path).mtimeMs}`)
+        return JSON.stringify({ files, status: gitExec("status", "--porcelain", "-uall") })
+      },
+      headSubject: () => gitExec("log", "-1", "--pretty=%s"),
+      headTouchedPaths: () =>
+        gitExec("show", "--name-only", "--pretty=format:", "HEAD")
+          .split("\n")
+          .filter((line) => line.length > 0),
+    },
+    runScript: (script) => {
+      // One stream, as a driver's terminal shows it.
+      const result = spawnSync("sh", ["-c", `exec 2>&1\n${script}`], {
+        cwd: root,
+        encoding: "utf8",
+        env: { ...process.env, PATH: `${gtdShimDir()}:${process.env["PATH"] ?? ""}` },
+      })
+      return { ok: result.status === 0, status: result.status ?? 1, output: result.stdout }
     },
     dispose: () => rmSync(root, { recursive: true, force: true }),
   }
 }
 
+/** A dir whose `gtd` runs this build's bundle, so a script's bare `gtd` is the code under test. */
+let shimDir: string | undefined
+const gtdShimDir = (): string => {
+  if (shimDir !== undefined) return shimDir
+  shimDir = mkdtempSync(join(tmpdir(), "gtd-tier-shim-"))
+  const bundle = join(import.meta.dirname, "../../dist/gtd.bundle.mjs")
+  writeFileSync(join(shimDir, "gtd"), `#!/bin/sh\nexec node "${bundle}" "$@"\n`, { mode: 0o755 })
+  return shimDir
+}
+
 const IN_MEM_ROOT = "/repo"
 
 const makeInMemTier = (initialCommit = true): GitTier => {
@@ -205,6 +278,7 @@ const makeInMemTier = (initialCommit = true): GitTier => {
       commitHooks: false,
       linkedWorktrees: false,
       directoryChainConfig: true,
+      remotes: false,
     },
     provide,
     provideExit,
@@ -239,6 +313,19 @@ const makeInMemTier = (initialCommit = true): GitTier => {
         return content
       },
       existsPath: (path) => repo.hasPath(path),
+      snapshot: async () => repo.snapshot(),
+      headSubject: () => repo.lastCommitSubject() ?? "",
+      headTouchedPaths: () => {
+        const paths = new Set([...repo.pathsAtRef("HEAD~1"), ...repo.pathsAtRef("HEAD")])
+        return [...paths]
+          .filter((p) => repo.fileAtRef("HEAD~1", p) !== repo.fileAtRef("HEAD", p))
+          .sort()
+      },
+    },
+    runScript: (script, commands = new Map()) => {
+      const { ok, status, output, error } = applyEmittedScript(repo, commands, script)
+      if (error?.startsWith("unrecognized script block:") === true) throw new Error(error)
+      return { ok, status, output }
     },
     dispose: () => {},
   }
@@ -259,6 +346,8 @@ const runGitExit = <A>(
 export const CONTRACT_COVERED_OPERATIONS: ReadonlySet<keyof GitOperations> = new Set([
   "lastCommitSubject",
   "lastCommitMessage",
+  "currentBranch",
+  "listRefs",
   "hasCommits",
   "resolveRef",
   "readRefOption",
@@ -321,6 +410,36 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
     t.dispose()
   })
 
+  it("no reader writes to the repository", async () => {
+    t.seed.commit("feat: second", { "second.txt": "two" })
+    t.seed.writeFile("dirty.txt", "dirty")
+    const before = await t.observe.snapshot()
+    await runGit(t, (g) =>
+      Effect.all([
+        g.lastCommitSubject(),
+        g.lastCommitMessage(),
+        g.hasCommits(),
+        g.resolveRef("HEAD"),
+        g.readRefOption("refs/gtd/none"),
+        g.isAncestor("HEAD~1", "HEAD"),
+        g.mergeBase("HEAD~1", "HEAD"),
+        g.defaultBranch(),
+        g.topLevel(),
+        g.gitDir(),
+        g.gitCommonDir(),
+        g.commitHistory(),
+        g.subjectHistory(10, 0),
+        g.readFileAtRef("HEAD", "second.txt"),
+        g.changedPaths(),
+        g.changedPaths("HEAD~1"),
+      ]),
+    )
+    expect(await t.observe.snapshot()).toBe(before)
+    // The negative control: a snapshot that saw nothing would pass the above vacuously.
+    await runGit(t, (g) => g.updateRef("refs/gtd/marker", t.observe.resolveRef("HEAD")))
+    expect(await t.observe.snapshot()).not.toBe(before)
+  })
+
   describe("resolveRef", () => {
     it("resolves HEAD to a 40-char hash", async () => {
       const hash = await runGit(t, (g) => g.resolveRef("HEAD"))
@@ -367,6 +486,73 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe("lastCommitMessage with a ref", () => {
+    it("reads the given ref's full message, not HEAD's", async () => {
+      t.seed.commit("feat: first\n\nGtd-Branch: one")
+      t.seed.commit("feat: second", { "extra.txt": "extra" })
+      const message = await runGit(t, (g) => g.lastCommitMessage("HEAD~1"))
+      expect(message).toBe("feat: first\n\nGtd-Branch: one")
+    })
+  })
+
+  describe("currentBranch", () => {
+    it("is the checked-out branch's name", async () => {
+      const branch = await runGit(t, (g) => g.currentBranch())
+      expect(Option.isSome(branch)).toBe(true)
+    })
+
+    it.skipIf(!capabilities.onDiskContent)(
+      "is none on a detached HEAD, never a failure",
+      async () => {
+        gitExecIn(t.root, "checkout", "--detach", "HEAD")
+        const branch = await runGit(t, (g) => g.currentBranch())
+        expect(Option.isNone(branch)).toBe(true)
+      },
+    )
+  })
+
+  describe("listRefs", () => {
+    it("is [] when no ref lives under the prefix", async () => {
+      const refs = await runGit(t, (g) => g.listRefs("refs/gtd/history/"))
+      expect(refs).toEqual([])
+    })
+
+    it("lists {ref, hash, date} for refs under the prefix only, newest tip first", async () => {
+      const first = t.observe.resolveRef("HEAD")
+      t.seed.commit("feat: second", { "second.txt": "2" })
+      const second = t.observe.resolveRef("HEAD")
+      t.seed.updateRef("refs/gtd/history/old", first)
+      t.seed.updateRef("refs/gtd/history/new", second)
+      t.seed.updateRef("refs/gtd/other/elsewhere", second)
+      const refs = await runGit(t, (g) => g.listRefs("refs/gtd/history/"))
+      expect(refs.map((r) => [r.ref, r.hash])).toEqual([
+        ["refs/gtd/history/new", second],
+        ["refs/gtd/history/old", first],
+      ])
+      for (const r of refs) expect(r.date.length).toBeGreaterThan(0)
+    })
+
+    it("reports the date as ISO 8601 strict", async () => {
+      t.seed.updateRef("refs/gtd/history/x", t.observe.resolveRef("HEAD"))
+      const [entry] = await runGit(t, (g) => g.listRefs("refs/gtd/history/"))
+      expect(entry?.date).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$/)
+    })
+  })
+
+  describe("history reachable only from a retained ref", () => {
+    it("commitHistory and readFileAtRef read it after HEAD moved off those commits", async () => {
+      t.seed.commit("feat: second", { "kept.txt": "kept" })
+      const tip = t.observe.resolveRef("HEAD")
+      t.seed.updateRef("refs/gtd/history/tip", tip)
+      t.seed.mixedReset("HEAD~1")
+      expect(t.observe.resolveRef("HEAD")).not.toBe(tip)
+      const history = await runGit(t, (g) => g.commitHistory(undefined, "refs/gtd/history/tip"))
+      expect(history.map((c) => c.message)).toEqual(["init: first commit", "feat: second"])
+      const content = await runGit(t, (g) => g.readFileAtRef("refs/gtd/history/tip", "kept.txt"))
+      expect(content).toBe("kept")
+    })
+  })
+
   describe("hasCommits", () => {
     it("returns false in an empty repo", async () => {
       const empty = t.emptyRepo()
@@ -916,35 +1102,20 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
 }
 
 /**
- * Runs a `GitScript.ts` builder's output through a REAL shell against `t.root`
- * — the same execution model the eventual driver uses (`bash -c <script>`),
- * so a builder that's syntactically fine but semantically wrong (a missing
- * `&&`, a misquoted path) fails here exactly as it would in production.
+ * The SAME writer postconditions `runGitServiceContract` asserts against
+ * `GitOperations`, asserted here against `GitScript.ts`'s builders as a driver
+ * runs them: real `sh` on Live, the in-memory twin on InMemory.
  */
-const execScript = (t: GitTier, script: string): void => {
-  execFileSync("bash", ["-c", script], { cwd: t.root, stdio: "pipe" })
+const run = (t: GitTier, script: string): void => {
+  const result = t.runScript(script)
+  if (!result.ok) throw new Error(`script failed on ${t.name}: ${result.output}`)
 }
 
-/** Names touched by HEAD's own commit — `git show`'s diff against its parent, not the whole tree. */
-const headTouchedPaths = (t: GitTier): ReadonlyArray<string> =>
-  gitExecIn(t.root, "show", "--name-only", "--pretty=format:", "HEAD")
-    .split("\n")
-    .filter((line) => line.length > 0)
-
-const headSubject = (t: GitTier): string => gitExecIn(t.root, "log", "-1", "--pretty=%s")
-
-/**
- * The SAME 9 writer postconditions `runGitServiceContract` asserts against
- * `GitOperations`, asserted here against `GitScript.ts`'s bash builders
- * instead — driven through real `bash` against a real repo (`makeLiveTier`),
- * never the in-memory fake, since a fake root (`/repo`) has no shell to run
- * against.
- */
-export const runGitScriptContract = (): void => {
+export const runGitScriptContract = (makeTier: () => GitTier): void => {
   let t: GitTier
 
   beforeEach(() => {
-    t = makeLiveTier()
+    t = makeTier()
   })
 
   afterEach(() => {
@@ -955,18 +1126,18 @@ export const runGitScriptContract = (): void => {
     it("stages (git add -A) before committing — a new untracked file lands in the commit", () => {
       t.seed.writeFile("new.ts", "export const x = 1")
       const headBefore = t.observe.resolveRef("HEAD")
-      execScript(t, commitAll("gtd: building"))
+      run(t, commitAll("gtd: building"))
       expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore)
-      expect(headSubject(t)).toBe("gtd: building")
-      expect(headTouchedPaths(t)).toEqual(["new.ts"])
+      expect(t.observe.headSubject()).toBe("gtd: building")
+      expect(t.observe.headTouchedPaths()).toEqual(["new.ts"])
       expect(t.observe.statusPorcelain().trim()).toBe("")
     })
 
     it("commits even on a clean tree (--allow-empty), never 'nothing to commit'", () => {
       const headBefore = t.observe.resolveRef("HEAD")
-      execScript(t, commitAll("gtd: grilled"))
+      run(t, commitAll("gtd: grilled"))
       expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore)
-      expect(headSubject(t)).toBe("gtd: grilled")
+      expect(t.observe.headSubject()).toBe("gtd: grilled")
     })
   })
 
@@ -975,16 +1146,16 @@ export const runGitScriptContract = (): void => {
       t.seed.writeFile("a.txt", "a")
       t.seed.stageAll()
       t.seed.writeFile("b.txt", "b")
-      execScript(t, commitAsIs("feat: squash"))
-      expect(headSubject(t)).toBe("feat: squash")
-      expect(headTouchedPaths(t)).toEqual(["a.txt"])
+      run(t, commitAsIs("feat: squash"))
+      expect(t.observe.headSubject()).toBe("feat: squash")
+      expect(t.observe.headTouchedPaths()).toEqual(["a.txt"])
     })
 
     it("commits even on a clean index (--allow-empty), never 'nothing to commit'", () => {
       const headBefore = t.observe.resolveRef("HEAD")
-      execScript(t, commitAsIs("gtd: empty squash"))
+      run(t, commitAsIs("gtd: empty squash"))
       expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore)
-      expect(headSubject(t)).toBe("gtd: empty squash")
+      expect(t.observe.headSubject()).toBe("gtd: empty squash")
     })
   })
 
@@ -992,7 +1163,7 @@ export const runGitScriptContract = (): void => {
     it("moves HEAD back but keeps worktree changes from the second commit", () => {
       const firstHash = t.observe.resolveRef("HEAD")
       t.seed.commit("feat: second", { "second.txt": "second content" })
-      execScript(t, softResetTo(firstHash))
+      run(t, softResetTo(firstHash))
       expect(t.observe.resolveRef("HEAD")).toBe(firstHash)
       expect(t.observe.statusPorcelain()).toContain("second.txt")
     })
@@ -1002,7 +1173,7 @@ export const runGitScriptContract = (): void => {
     it("moves HEAD, index, and working tree content back to the target ref", () => {
       const firstHash = t.observe.resolveRef("HEAD")
       t.seed.commit("feat: second", { "readme.txt": "modified content" })
-      execScript(t, hardResetTo(firstHash))
+      run(t, hardResetTo(firstHash))
       expect(t.observe.resolveRef("HEAD")).toBe(firstHash)
       expect(t.observe.statusPorcelain()).toBe("")
       expect(t.observe.readWorktreeFile("readme.txt")).toBe("hello")
@@ -1013,7 +1184,7 @@ export const runGitScriptContract = (): void => {
     it("moves HEAD and index, leaving the working tree untouched", () => {
       const firstHash = t.observe.resolveRef("HEAD")
       t.seed.commit("feat: second", { "second.txt": "second content" })
-      execScript(t, mixedResetTo(firstHash))
+      run(t, mixedResetTo(firstHash))
       expect(t.observe.resolveRef("HEAD")).toBe(firstHash)
       expect(t.observe.statusPorcelain()).toContain("second.txt")
     })
@@ -1023,7 +1194,7 @@ export const runGitScriptContract = (): void => {
     it("drops both tracked modifications and untracked files", () => {
       t.seed.writeFile("readme.txt", "modified")
       t.seed.writeFile("untracked.txt", "new")
-      execScript(t, discardPending())
+      run(t, discardPending())
       expect(t.observe.statusPorcelain()).toBe("")
     })
   })
@@ -1031,22 +1202,73 @@ export const runGitScriptContract = (): void => {
   describe("updateRef / deleteRef", () => {
     it("updateRef points a ref at a commit", () => {
       const head = t.observe.resolveRef("HEAD")
-      execScript(t, updateRef("refs/gtd/marker", head))
+      run(t, updateRef("refs/gtd/marker", head))
       expect(t.observe.refExists("refs/gtd/marker")).toBe(true)
       expect(t.observe.resolveRef("refs/gtd/marker")).toBe(head)
     })
 
+    it("updateRef with HEAD points the ref at the commit just made", () => {
+      run(t, commitAll("feat: just made"))
+      run(t, updateRef("refs/gtd/history/x", "HEAD"))
+      expect(t.observe.resolveRef("refs/gtd/history/x")).toBe(t.observe.resolveRef("HEAD"))
+    })
+
     it("deleteRef removes an existing ref, and tolerates deleting it again", () => {
       const head = t.observe.resolveRef("HEAD")
-      execScript(t, updateRef("refs/gtd/marker", head))
-      execScript(t, deleteRef("refs/gtd/marker"))
-      execScript(t, deleteRef("refs/gtd/marker"))
+      run(t, updateRef("refs/gtd/marker", head))
+      run(t, deleteRef("refs/gtd/marker"))
+      run(t, deleteRef("refs/gtd/marker"))
       expect(t.observe.refExists("refs/gtd/marker")).toBe(false)
     })
 
     it("deleteRef tolerates a ref that was never created", () => {
-      expect(() => execScript(t, deleteRef("refs/gtd/never-created"))).not.toThrow()
+      expect(() => run(t, deleteRef("refs/gtd/never-created"))).not.toThrow()
       expect(t.observe.refExists("refs/gtd/never-created")).toBe(false)
     })
   })
+
+  describe("fetchHistoryRefs", () => {
+    it("pulls every refs/gtd/history/* from a bare remote and prints the count", (ctx) => {
+      if (!t.capabilities.remotes) ctx.skip()
+      const bare = realpathSync(mkdtempSync(join(tmpdir(), "gtd-git-tier-bare-")))
+      try {
+        gitExecIn(bare, "init", "-q", "--bare")
+        gitExecIn(t.root, "remote", "add", "origin", bare)
+        const head = t.observe.resolveRef("HEAD")
+        gitExecIn(t.root, "push", "-q", "origin", `${head}:refs/gtd/history/one`)
+        gitExecIn(t.root, "push", "-q", "origin", `${head}:refs/gtd/history/two`)
+        gitExecIn(t.root, "push", "-q", "origin", `${head}:refs/gtd/other/skip`)
+        const out = execFileSync("bash", ["-c", fetchHistoryRefs("origin")], {
+          cwd: t.root,
+          encoding: "utf8",
+        })
+        expect(t.observe.refExists("refs/gtd/history/one")).toBe(true)
+        expect(t.observe.refExists("refs/gtd/history/two")).toBe(true)
+        expect(t.observe.refExists("refs/gtd/other/skip")).toBe(false)
+        expect(out.trim()).toBe("2 history refs arrived")
+      } finally {
+        rmSync(bare, { recursive: true, force: true })
+      }
+    })
+
+    it("fails loudly when a local history ref conflicts with the remote's", (ctx) => {
+      if (!t.capabilities.remotes) ctx.skip()
+      const bare = realpathSync(mkdtempSync(join(tmpdir(), "gtd-git-tier-bare-")))
+      try {
+        gitExecIn(bare, "init", "-q", "--bare")
+        gitExecIn(t.root, "remote", "add", "origin", bare)
+        const first = t.observe.resolveRef("HEAD")
+        t.seed.commit("feat: second", { "second.txt": "x" })
+        const second = t.observe.resolveRef("HEAD")
+        gitExecIn(t.root, "push", "-q", "origin", `${first}:refs/gtd/history/one`)
+        t.seed.updateRef("refs/gtd/history/one", second)
+        expect(() =>
+          execFileSync("bash", ["-c", fetchHistoryRefs("origin")], { cwd: t.root, stdio: "pipe" }),
+        ).toThrow()
+        expect(t.observe.resolveRef("refs/gtd/history/one")).toBe(second)
+      } finally {
+        rmSync(bare, { recursive: true, force: true })
+      }
+    })
+  })
 }

package/src/testkit/InMemRepo.ts

@@ -9,6 +9,8 @@ interface Commit {
   message: string
   files: Map<string, string> // full tree snapshot (path → UTF-8 content)
   parent: string | null
+  /** Creation order — the twin's stand-in for a committer date. */
+  seq: number
 }
 
 function sha1(input: string): string {
@@ -35,6 +37,7 @@ export class InMemRepo {
   private currentBranch: string = "main"
   private worktree: Map<string, string> = new Map()
   private index: Map<string, string> = new Map()
+  private nextSeq = 1
 
   private getCommit(hash: string): Commit | null {
     return this.commits.get(hash) ?? null
@@ -112,10 +115,11 @@ export class InMemRepo {
       return this.commits.has(ref) ? ref : null
     }
 
-    const tildeMatch = /^(HEAD|[0-9a-f]{40})(~(\d+))?$/.exec(ref)
+    const tildeMatch = /^(HEAD|[0-9a-f]{40})(~(\d+)|\^)?$/.exec(ref)
     if (tildeMatch) {
       const base = tildeMatch[1]!
-      const steps = tildeMatch[3] !== undefined ? parseInt(tildeMatch[3], 10) : 0
+      const steps =
+        tildeMatch[3] !== undefined ? parseInt(tildeMatch[3], 10) : tildeMatch[2] === "^" ? 1 : 0
       let cur: string | null = base === "HEAD" ? this.head : this.commits.has(base) ? base : null
       for (let i = 0; i < steps; i++) {
         if (cur === null) return null
@@ -137,10 +141,27 @@ export class InMemRepo {
     return c.message.split("\n")[0] ?? null
   }
 
-  lastCommitMessage(): string | null {
-    const c = this.headCommit()
-    if (!c) return null
-    return c.message
+  lastCommitMessage(ref?: string): string | null {
+    const hash = ref === undefined ? this.head : this.resolveRef(ref)
+    const c = hash === null ? null : this.getCommit(hash)
+    return c === null ? null : c.message
+  }
+
+  branchName(): string {
+    return this.currentBranch
+  }
+
+  /** Refs under `prefix`, newest tip first; the commit sequence number stands in for the committer date. */
+  listRefs(prefix: string): Array<{ ref: string; hash: string; date: string }> {
+    return [...this.refs.entries()]
+      .filter(([ref]) => ref.startsWith(prefix))
+      .map(([ref, hash]) => ({ ref, hash, seq: this.getCommit(hash)?.seq ?? 0 }))
+      .sort((a, b) => b.seq - a.seq)
+      .map(({ ref, hash, seq }) => ({
+        ref,
+        hash,
+        date: new Date(seq * 1000).toISOString().replace(/\.\d{3}Z$/, "Z"),
+      }))
   }
 
   /**
@@ -277,6 +298,38 @@ export class InMemRepo {
       .sort()
   }
 
+  /** Everything git would keep on disk, serialized — two snapshots compare equal exactly when nothing was written. */
+  snapshot(): string {
+    const sorted = (m: Map<string, string>) =>
+      [...m.entries()].sort(([a], [b]) => a.localeCompare(b))
+    return JSON.stringify({
+      head: this.head,
+      branch: this.currentBranch,
+      commits: [...this.commits.keys()].sort(),
+      branches: sorted(this.branches),
+      refs: sorted(this.refs),
+      index: sorted(this.index),
+      worktree: sorted(this.worktree),
+    })
+  }
+
+  /** Every ref name under `prefix` (`refs/…`), sorted — `git for-each-ref <prefix>`. */
+  refNamesUnder(prefix: string): ReadonlyArray<string> {
+    return [...this.refs.keys()].filter((ref) => ref.startsWith(prefix)).sort()
+  }
+
+  /** Whether `path` is in the index — what `git diff <commit> -- <path>` compares against the worktree. */
+  isTracked(path: string): boolean {
+    return this.index.has(path)
+  }
+
+  /** `git add <path>` — the index takes `path` as the worktree has it, or drops it. */
+  stage(path: string): void {
+    const content = this.worktree.get(path)
+    if (content === undefined) this.index.delete(path)
+    else this.index.set(path, content)
+  }
+
   /** `git add -A` — the index becomes exactly the current worktree. */
   stageAll(): void {
     this.index = new Map(this.worktree)
@@ -287,7 +340,7 @@ export class InMemRepo {
     const tree = new Map(this.index)
     const parent = this.head
     const hash = makeHash(message, parent, tree)
-    const commit: Commit = { hash, message, files: new Map(tree), parent }
+    const commit: Commit = { hash, message, files: new Map(tree), parent, seq: this.nextSeq++ }
     this.commits.set(hash, commit)
     this.head = hash
     this.branches.set(this.currentBranch, hash)
@@ -307,7 +360,7 @@ export class InMemRepo {
     const parent = this.head
     const hash = makeHash(message, parent, tree)
 
-    const commit: Commit = { hash, message, files: new Map(tree), parent }
+    const commit: Commit = { hash, message, files: new Map(tree), parent, seq: this.nextSeq++ }
     this.commits.set(hash, commit)
     this.head = hash
     this.branches.set(this.currentBranch, hash)

package/src/testkit/Layers.ts

@@ -158,7 +158,7 @@ const makeInMemoryConfigDiscovery = (
           for (const dir of walkUp(levelRoot, levelHome)) {
             const filepath = join(dir, WORKFLOW_MODULE)
             const source = workspace.atPath(filepath)
-            if (source !== undefined) return { filepath, source }
+            if (source !== undefined) return { filepath, source, read: workspace.atPath }
           }
           return undefined
         },
@@ -170,7 +170,15 @@ const makeInMemoryConfigDiscovery = (
 /** 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 }
+  | {
+      readonly kind: "rewrite"
+      readonly file: string
+      readonly content: string
+      /** Adds `content` to the file's end instead of replacing it. */
+      readonly append?: boolean
+    }
+  /** Keyed by the binary's name: it is not on `$PATH`. */
+  | { readonly kind: "missing" }
 
 export interface TestWorldOptions {
   readonly env?: Readonly<Record<string, string | undefined>>

package/src/testkit/TestRepo.ts

@@ -4,6 +4,7 @@ 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 { applyFlowScript } from "./FlowScripts.js"
 import { InMemRepo } from "./InMemRepo.js"
 
 /**
@@ -247,7 +248,9 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     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())
+      const flow = applyFlowScript(repo, new Map(), script)
+      if (flow === undefined) for (const line of script.split("\n")) runLine(repo, line.trim())
+      else if (!flow.ok) throw new Error(`testkit: ${flow.error ?? ""}`)
     },
     gtd,
     start: (workflow, ...args) => begin(["--workflow", workflow, ...args]),