@pmelab/gtd 26.0.0 → 26.1.0

package/src/testkit/GitTiers.ts

@@ -30,6 +30,7 @@ import {
   updateRef,
   fetchHistoryRefs,
   deleteRef,
+  shellQuote,
 } from "../emit/index.js"
 import { applyEmittedScript } from "./EmittedScriptRecognizer.js"
 import { InMemRepo } from "./InMemRepo.js"
@@ -38,8 +39,6 @@ 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. */
   readonly onDiskContent: boolean
-  /** Install a real `.git/hooks/pre-commit` and prove the `--no-verify` retry — only the Live tier has a hooks directory. */
-  readonly commitHooks: boolean
   /** `git worktree add` — sibling linked worktrees sharing one `.git`; the fake models a single worktree only. */
   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. */
@@ -48,6 +47,26 @@ export interface GitTierCapabilities {
   readonly remotes: boolean
 }
 
+// Quoted heredoc: `$`, `$(…)` and backticks in `output` reach stderr verbatim.
+const writeRejectingHook = (hooksDir: string, output: string): void => {
+  mkdirSync(hooksDir, { recursive: true })
+  writeFileSync(
+    join(hooksDir, "pre-commit"),
+    `#!/bin/sh\ncat >&2 <<'GTD_HOOK_EOF'\n${output}\nGTD_HOOK_EOF\nexit 1\n`,
+    { mode: 0o755 },
+  )
+}
+
+// `printf '%s'` keeps `content` byte-exact.
+const writeStagingHook = (hooksDir: string, path: string, content: string): void => {
+  mkdirSync(hooksDir, { recursive: true })
+  writeFileSync(
+    join(hooksDir, "pre-commit"),
+    `#!/bin/sh\nprintf '%s' ${shellQuote(content)} > ${shellQuote(path)} && git add ${shellQuote(path)}\nexit 0\n`,
+    { mode: 0o755 },
+  )
+}
+
 export interface GitTierSeed {
   readonly commit: (message: string, files?: Record<string, string>) => void
   readonly writeFile: (path: string, content: string) => void
@@ -56,6 +75,12 @@ export interface GitTierSeed {
   readonly stageAll: () => void
   readonly updateRef: (ref: string, hash: string) => void
   readonly mixedReset: (ref: string) => void
+  /** Every hooked commit fails printing `output`; `--no-verify` skips it. */
+  readonly rejectingHook: (output: string) => void
+  /** Every hooked commit first writes `content` to `path` and stages it; `--no-verify` and `commit-tree` skip it. */
+  readonly stagingHook: (path: string, content: string) => void
+  /** Every commit `git commit` signs, or `git commit-tree -S` writes, fails; plain `git commit-tree` is unaffected. */
+  readonly failingSigner: () => void
 }
 
 export interface GitTierObserve {
@@ -157,7 +182,6 @@ const makeLiveTier = (initialCommit = true): GitTier => {
     root,
     capabilities: {
       onDiskContent: true,
-      commitHooks: true,
       linkedWorktrees: true,
       directoryChainConfig: true,
       remotes: true,
@@ -193,6 +217,22 @@ const makeLiveTier = (initialCommit = true): GitTier => {
       stageAll: () => gitExec("add", "-A"),
       updateRef: (ref, hash) => gitExec("update-ref", ref, hash),
       mixedReset: (ref) => gitExec("reset", "--mixed", ref),
+      rejectingHook: (output) => {
+        const hooks = join(root, ".git/hooks")
+        gitExec("config", "core.hooksPath", hooks)
+        writeRejectingHook(hooks, output)
+      },
+      stagingHook: (path, content) => {
+        const hooks = join(root, ".git/hooks")
+        gitExec("config", "core.hooksPath", hooks)
+        writeStagingHook(hooks, path, content)
+      },
+      failingSigner: () => {
+        gitExec("config", "commit.gpgsign", "true")
+        // A global `gpg.format ssh` would otherwise sign and the case pass vacuously.
+        gitExec("config", "gpg.format", "openpgp")
+        gitExec("config", "gpg.program", "false")
+      },
     },
     observe: {
       resolveRef: (ref) => gitExec("rev-parse", ref),
@@ -258,7 +298,7 @@ const makeInMemTier = (initialCommit = true): GitTier => {
   const repo = new InMemRepo()
   if (initialCommit) {
     repo.writeFile("readme.txt", "hello")
-    repo.commitAllWithPrefix("init: first commit")
+    repo.seedCommit("init: first commit")
   }
   const gitLayer = gitTestLayer(repo, IN_MEM_ROOT)
 
@@ -275,7 +315,6 @@ const makeInMemTier = (initialCommit = true): GitTier => {
     root: IN_MEM_ROOT,
     capabilities: {
       onDiskContent: false,
-      commitHooks: false,
       linkedWorktrees: false,
       directoryChainConfig: true,
       remotes: false,
@@ -286,17 +325,26 @@ const makeInMemTier = (initialCommit = true): GitTier => {
     seed: {
       commit: (message, files = { "file.txt": message }) => {
         for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
-        repo.commitAllWithPrefix(message)
+        repo.seedCommit(message)
       },
       writeFile: (path, content) => repo.writeFile(path, content),
       deleteFile: (path) => repo.deleteFile(path),
       commitDeletion: (path, message) => {
         repo.deleteFile(path)
-        repo.commitAllWithPrefix(message)
+        repo.seedCommit(message)
       },
       stageAll: () => repo.stageAll(),
       updateRef: (ref, hash) => repo.updateRef(ref, hash),
       mixedReset: (ref) => repo.mixedResetTo(ref),
+      rejectingHook: (output) => {
+        repo.hookRejection = output
+      },
+      stagingHook: (path, content) => {
+        repo.hookStages = { path, content }
+      },
+      failingSigner: () => {
+        repo.signingFails = true
+      },
     },
     observe: {
       resolveRef: (ref) => {
@@ -727,23 +775,6 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
       const history = await runGit(t, (g) => g.commitHistory())
       expect(history[history.length - 1]?.message).toBe("gtd: grilled")
     })
-
-    it.skipIf(!capabilities.commitHooks)(
-      "retries with --no-verify when a hook blocks the empty commit",
-      async () => {
-        const hookPath = join(t.root, ".git/hooks/pre-commit")
-        writeFileSync(
-          hookPath,
-          `#!/bin/sh\necho "lint-staged prevented an empty git commit." >&2\nexit 1\n`,
-        )
-        execSync(`chmod +x "${hookPath}"`)
-        const headBefore = t.observe.resolveRef("HEAD")
-        await runGit(t, (g) => g.commitAllWithPrefix("gtd: grilled"))
-        expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore)
-        const history = await runGit(t, (g) => g.commitHistory())
-        expect(history[history.length - 1]?.message).toBe("gtd: grilled")
-      },
-    )
   })
 
   describe("commitAsIs", () => {
@@ -768,6 +799,35 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe.each([
+    ["commitAllWithPrefix", (g: GitOperations) => g.commitAllWithPrefix("gtd: building")],
+    ["commitAsIs", (g: GitOperations) => g.commitAsIs("gtd: building")],
+  ] as const)("%s seeded commit failures", (_name, commit) => {
+    it("retries with --no-verify when a hook blocks the empty commit", async () => {
+      t.seed.rejectingHook("lint-staged prevented an empty git commit.")
+      const headBefore = t.observe.resolveRef("HEAD")
+      await runGit(t, commit)
+      expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore)
+      const history = await runGit(t, (g) => g.commitHistory())
+      expect(history[history.length - 1]?.message).toBe("gtd: building")
+    })
+
+    it("fails on a hook rejection that is not the empty-commit one, leaving HEAD unchanged", async () => {
+      t.seed.rejectingHook("lint error")
+      const headBefore = t.observe.resolveRef("HEAD")
+      expect(Exit.isFailure(await runGitExit(t, commit))).toBe(true)
+      expect(t.observe.resolveRef("HEAD")).toBe(headBefore)
+    })
+
+    it("fails both attempts when the signer cannot write, leaving HEAD unchanged", async () => {
+      t.seed.rejectingHook("rejected: empty git commit")
+      t.seed.failingSigner()
+      const headBefore = t.observe.resolveRef("HEAD")
+      expect(Exit.isFailure(await runGitExit(t, commit))).toBe(true)
+      expect(t.observe.resolveRef("HEAD")).toBe(headBefore)
+    })
+  })
+
   describe("softResetTo", () => {
     it("moves HEAD back but keeps worktree changes from second commit", async () => {
       const firstHash = t.observe.resolveRef("HEAD")
@@ -824,6 +884,25 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
       expect(resolved._tag).toBe("None")
     })
 
+    it("readRefOption of <hash>^{commit} is Some for an existing commit", async () => {
+      const head = t.observe.resolveRef("HEAD")
+      const resolved = await runGit(t, (g) => g.readRefOption(`${head}^{commit}`))
+      expect(resolved._tag).toBe("Some")
+      if (resolved._tag === "Some") expect(resolved.value).toBe(head)
+    })
+
+    it("readRefOption of <hash>^{commit} is None for a 40-hex hash with no object", async () => {
+      const missing = "0123456789abcdef0123456789abcdef01234567"
+      const resolved = await runGit(t, (g) => g.readRefOption(`${missing}^{commit}`))
+      expect(resolved._tag).toBe("None")
+    })
+
+    it("readRefOption of a bare 40-hex hash with no object is Some", async () => {
+      const missing = "0123456789abcdef0123456789abcdef01234567"
+      const resolved = await runGit(t, (g) => g.readRefOption(missing))
+      expect(resolved._tag).toBe("Some")
+    })
+
     it("deleteRef removes a ref idempotently (deleting twice is a no-op)", async () => {
       const head = t.observe.resolveRef("HEAD")
       await runGit(t, (g) => g.updateRef("refs/gtd/marker", head))

package/src/testkit/InMemRepo.ts

@@ -111,6 +111,7 @@ export class InMemRepo {
 
   // fallow-ignore-next-line complexity
   resolveRef(ref: string): string | null {
+    if (ref.endsWith("^{commit}")) return this.resolveRef(ref.slice(0, -"^{commit}".length))
     if (/^[0-9a-f]{40}$/.test(ref)) {
       return this.commits.has(ref) ? ref : null
     }
@@ -335,8 +336,13 @@ export class InMemRepo {
     this.index = new Map(this.worktree)
   }
 
-  /** Commit whatever is currently staged (the index) verbatim, with no implicit staging first — mirrors `git commit --allow-empty -m <message>` after a soft reset. */
-  commitAsIs(message: string): void {
+  /** Seeded failure modes (see `GitTierSeed`): a pre-commit hook printing this and exiting 1, and a signer that cannot write. */
+  hookRejection: string | undefined = undefined
+  signingFails = false
+  /** Seeded: a pre-commit hook writing and staging this file. */
+  hookStages: { readonly path: string; readonly content: string } | undefined = undefined
+
+  private writeCommit(message: string): void {
     const tree = new Map(this.index)
     const parent = this.head
     const hash = makeHash(message, parent, tree)
@@ -346,24 +352,63 @@ export class InMemRepo {
     this.branches.set(this.currentBranch, hash)
   }
 
-  /** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
-  discardPending(): void {
-    this.index = new Map(this.worktree)
-    this.resetHard()
+  /**
+   * Twin of the emitted `git commit --allow-empty` if/case retry: a hook
+   * rejection printing "empty git commit" retries without hooks, any other
+   * rejection fails; a failing signer fails either attempt. Commits whatever is
+   * staged verbatim, like `git commit` after a soft reset.
+   */
+  commitAsIs(message: string): string | undefined {
+    if (this.hookRejection !== undefined && !this.hookRejection.includes("empty git commit")) {
+      return this.hookRejection
+    }
+    if (this.signingFails) return "error: gpg failed to sign the data"
+    if (this.hookStages !== undefined) {
+      this.worktree.set(this.hookStages.path, this.hookStages.content)
+      this.index.set(this.hookStages.path, this.hookStages.content)
+    }
+    this.writeCommit(message)
+    return undefined
   }
 
-  commitAllWithPrefix(prefix: string): void {
+  /** Setup commit: stages everything, and throws if a failure is seeded, as the Live tier's hooks and signer would. */
+  seedCommit(message: string): void {
+    if (this.hookRejection !== undefined || this.hookStages !== undefined || this.signingFails) {
+      throw new Error("seedCommit after a seeded commit failure")
+    }
     this.index = new Map(this.worktree)
+    this.writeCommit(message)
+  }
 
+  /** Twin of `GitScript.keepTurn`: no hook runs; `signingFails` fails the marker. */
+  keepTurn(refPrefix: string, message: string): string | undefined {
+    this.stageAll()
     const tree = new Map(this.index)
-    const message = prefix
     const parent = this.head
     const hash = makeHash(message, parent, tree)
+    this.commits.set(hash, { hash, message, files: new Map(tree), parent, seq: this.nextSeq++ })
+    const ref = `${refPrefix}/${hash}`
+    this.refs.set(ref, hash)
+    this.index = new Map(this.headTree())
+    if (this.signingFails) {
+      this.refs.delete(ref)
+      return "error: gpg failed to sign the data"
+    }
+    this.writeCommit(`${message}\nGtd-Kept: ${hash}`)
+    this.index = new Map(tree)
+    this.resetHard()
+    return undefined
+  }
 
-    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)
+  /** Discard every pending change, tracked or untracked: stage everything, then hard-reset (which drops the freshly-staged untracked paths too). */
+  discardPending(): void {
+    this.index = new Map(this.worktree)
+    this.resetHard()
+  }
+
+  commitAllWithPrefix(prefix: string): string | undefined {
+    this.index = new Map(this.worktree)
+    return this.commitAsIs(prefix)
   }
 
   // Git's empty-tree object SHA: used as squash base when there's no parent commit.

package/src/testkit/TestRepo.ts

@@ -169,7 +169,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     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")
+  repo.seedCommit("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.
@@ -245,7 +245,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     read: (path) => repo.readFile(path),
     write: (path, content) => repo.writeFile(path, content),
     remove: (path) => repo.deleteFile(path),
-    commit: (message) => repo.commitAllWithPrefix(message),
+    commit: (message) => repo.seedCommit(message),
     show: (ref, path) => repo.fileAtRef(ref, path) ?? undefined,
     runScript: (script) => {
       const flow = applyFlowScript(repo, new Map(), script)

package/src/workflow/Workflow.ts

@@ -39,6 +39,7 @@ export interface StepDef {
   readonly answerGate?: boolean
   readonly requireRevert?: boolean
   readonly allowEmpty?: boolean
+  readonly keep?: boolean
   readonly acceptClean?: boolean
   readonly skills?: readonly string[]
   readonly access?: StepAccess

package/src/workflow/discovery.test.ts

@@ -83,7 +83,7 @@ const inMemory = (): Tier => ({
   load: (files) => {
     const repo = new InMemRepo()
     for (const [path, content] of Object.entries(files)) repo.writeFile(path, content)
-    repo.commitAllWithPrefix("chore: init")
+    repo.seedCommit("chore: init")
     return loadWith(testLayers(repo))
   },
   dispose: () => {},

package/src/workflows/shared/text.fixture.ts

@@ -77,6 +77,7 @@ export const fixtureContext = (
   glob: () => [],
   changes: () => [],
   changesSince: unavailable,
+  kept: () => undefined,
   matches: () => false,
   sections: () => [],
   sectionBodies: () => [],