@pmelab/gtd 24.1.0 → 24.3.0

package/src/replay/Trailers.ts

@@ -72,6 +72,9 @@ export interface CommitMessage {
   readonly config: Readonly<Record<string, string>>
   readonly reviewBase: string | undefined
   readonly cost: readonly CostEntry[]
+  /** Written only on a process's finishing landing. */
+  readonly branch: string | undefined
+  readonly version: string | undefined
   readonly format: number
 }
 
@@ -116,6 +119,8 @@ interface Trailers {
   step: StepId | undefined
   workflow: string | undefined
   reviewBase: string | undefined
+  branch: string | undefined
+  version: string | undefined
   readonly judge: JudgeVerdict[]
   readonly vars: Record<string, string>
   readonly config: Record<string, string>
@@ -146,6 +151,12 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Review-Base": (value, into) => {
     into.reviewBase ??= value.split(/\s/)[0]
   },
+  "Gtd-Branch": (value, into) => {
+    if (value !== "") into.branch ??= value
+  },
+  "Gtd-Version": (value, into) => {
+    if (value !== "") into.version ??= value
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -162,6 +173,8 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     step: undefined,
     workflow: undefined,
     reviewBase: undefined,
+    branch: undefined,
+    version: undefined,
     judge: [],
     vars: {},
     config: {},
@@ -187,6 +200,8 @@ export interface CommitSpec {
   readonly config?: Readonly<Record<string, string>>
   readonly cost?: { readonly cost: number; readonly model?: string }
   readonly judge?: readonly JudgeVerdict[]
+  readonly branch?: string
+  readonly version?: string
 }
 
 const sortedEntries = (record: Readonly<Record<string, string>> = {}): [string, string][] =>
@@ -207,6 +222,8 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     )
   }
   for (const verdict of spec.judge ?? []) lines.push(`Gtd-Judge: ${JSON.stringify(verdict)}`)
+  if (spec.branch !== undefined) lines.push(`Gtd-Branch: ${spec.branch}`)
+  if (spec.version !== undefined) lines.push(`Gtd-Version: ${spec.version}`)
   lines.push(`Gtd-Format: ${HISTORY_FORMAT}`)
   const subject = formatSubject(spec.actor, spec.to, spec.from)
   return `${subject}\n\n${lines.join("\n")}`

package/src/step/LandStep.ts

@@ -6,7 +6,9 @@ import type { StateName } from "../workflow/index.js"
  * that module, which is what makes writing a live git call inside the core
  * impossible rather than merely discouraged.
  */
-export type GitWrite = { readonly kind: "commitAll"; readonly message: string }
+export type GitWrite =
+  | { readonly kind: "commitAll"; readonly message: string }
+  | { readonly kind: "updateRef"; readonly ref: string; readonly target: "HEAD" }
 
 /** A landed step's trailing report, rendered by `GitScript.ts` into a `printf` line. */
 export type Outcome =

package/src/step/RepoSnapshot.ts

@@ -11,7 +11,13 @@ export type Landing =
   | { readonly kind: "noop"; readonly settled: boolean }
   /** An empty agent turn: recorded, but the process stays at the step. */
   | { readonly kind: "attempt"; readonly subject: string }
-  | { readonly kind: "commit"; readonly to: StateName; readonly spec: CommitSpec }
+  | {
+      readonly kind: "commit"
+      readonly to: StateName
+      readonly spec: CommitSpec
+      /** The full history ref a finishing landing points at its own commit. */
+      readonly keepHistory?: string
+    }
 
 /**
  * Everything `planStep` needs, already resolved

package/src/step/planStart.test.ts

@@ -108,7 +108,8 @@ describe("planStart", () => {
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: {} })
       if (plan.kind !== "start") throw new Error(`expected start, got ${JSON.stringify(plan)}`)
       const write = plan.steps.find((s) => s.kind === "gitWrite")
-      if (write?.kind !== "gitWrite") throw new Error("expected a gitWrite step")
+      if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
+        throw new Error("expected a gitWrite step")
       expect(write.write.message).toContain(`Gtd-Review-Base: ${fork}`)
     })
 
@@ -124,7 +125,8 @@ describe("planStart", () => {
       const plan = await start(repo, "idle", "human", { ...REVIEW, vars: { base: "other" } })
       if (plan.kind !== "start") throw new Error(`expected start, got ${JSON.stringify(plan)}`)
       const write = plan.steps.find((s) => s.kind === "gitWrite")
-      if (write?.kind !== "gitWrite") throw new Error("expected a gitWrite step")
+      if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
+        throw new Error("expected a gitWrite step")
       expect(write.write.message).toContain(`Gtd-Review-Base: ${fork}`)
     })
 
@@ -189,7 +191,8 @@ describe("planStart", () => {
     })
     if (plan.kind !== "start") throw new Error(`expected start, got ${plan.kind}`)
     const write = plan.steps.find((s) => s.kind === "gitWrite")
-    if (write?.kind !== "gitWrite") throw new Error("expected a gitWrite step")
+    if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
+      throw new Error("expected a gitWrite step")
     expect(write.write.message).toBe(
       "gtd(human): work\n\nGtd-Workflow: working\nGtd-Var: base=main\nGtd-Format: 1",
     )

package/src/step/planStep.test.ts

@@ -92,7 +92,8 @@ describe("planStep — commit", () => {
     })
     if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
     const write = outcome.steps.find((step) => step.kind === "gitWrite")
-    if (write?.kind !== "gitWrite") throw new Error("expected a git write")
+    if (write?.kind !== "gitWrite" || write.write.kind !== "commitAll")
+      throw new Error("expected a git write")
     const trailers = write.write.message.split("\n").slice(2)
     expect(trailers[0]).toBe("Gtd-Step: a#1")
     expect(trailers[1]).toBe("Gtd-Cost: 1.5 m")
@@ -102,3 +103,30 @@ describe("planStep — commit", () => {
     expect(trailers).toHaveLength(5)
   })
 })
+
+describe("planStep — keepHistory", () => {
+  it("writes the history ref right after the commit, before the outcome", () => {
+    const s = snapshot({
+      state: "building",
+      stepDef: {},
+      landing: { ...commitTo("building", "done"), keepHistory: "refs/gtd/history/abc" },
+    })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(outcome.steps.map((step) => step.kind)).toEqual(["gitWrite", "gitWrite", "outcome"])
+    expect(outcome.steps[0]).toMatchObject({ write: { kind: "commitAll" } })
+    expect(outcome.steps[1]).toEqual({
+      kind: "gitWrite",
+      write: { kind: "updateRef", ref: "refs/gtd/history/abc", target: "HEAD" },
+    })
+  })
+
+  it("without keepHistory no updateRef is emitted", () => {
+    const s = snapshot({ state: "building", stepDef: {}, landing: commitTo("building", "done") })
+    const outcome = planStep(s)
+    if (outcome.kind !== "commit") throw new Error(`expected commit, got ${outcome.kind}`)
+    expect(
+      outcome.steps.some((step) => step.kind === "gitWrite" && step.write.kind === "updateRef"),
+    ).toBe(false)
+  })
+})

package/src/step/planStep.ts

@@ -83,6 +83,14 @@ export const planStep = (
     steps: [
       ...uncheckStep(snapshot),
       { kind: "gitWrite", write: { kind: "commitAll", message } },
+      ...(landing.keepHistory !== undefined
+        ? [
+            {
+              kind: "gitWrite",
+              write: { kind: "updateRef", ref: landing.keepHistory, target: "HEAD" },
+            } as const,
+          ]
+        : []),
       outcome,
     ],
   }

package/src/testkit/EmittedScriptRecognizer.ts

@@ -143,7 +143,7 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
   // quoted argument.
   const conditionLine = conditionStatement(block)
 
-  if (block.startsWith("git add -A &&\n")) {
+  if (block.startsWith("git add -A || exit 1\n")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAll(message) === block) {
       repo.commitAllWithPrefix(message)

package/src/testkit/FakeGitOperations.ts

@@ -16,11 +16,15 @@ const makeGitReaderOps = (repo: InMemRepo, root: string): GitReaderOperations =>
     return subject !== null ? Effect.succeed(subject) : Effect.fail(new Error("No commits"))
   },
 
-  lastCommitMessage: () => {
-    const message = repo.lastCommitMessage()
+  lastCommitMessage: (ref?: string) => {
+    const message = repo.lastCommitMessage(ref)
     return message !== null ? Effect.succeed(message) : Effect.fail(new Error("No commits"))
   },
 
+  currentBranch: () => Effect.succeed(Option.some(repo.branchName())),
+
+  listRefs: (prefix: string) => Effect.succeed(repo.listRefs(prefix)),
+
   resolveRef: (ref: string) => {
     const hash = repo.resolveRef(ref)
     return hash !== null

package/src/testkit/GitTiers.ts

@@ -26,6 +26,7 @@ import {
   hardResetTo,
   discardPending,
   updateRef,
+  fetchHistoryRefs,
   deleteRef,
 } from "../emit/index.js"
 import { InMemRepo } from "./InMemRepo.js"
@@ -88,6 +89,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 +108,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> =>
@@ -142,7 +155,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 })
@@ -259,6 +272,8 @@ const runGitExit = <A>(
 export const CONTRACT_COVERED_OPERATIONS: ReadonlySet<keyof GitOperations> = new Set([
   "lastCommitSubject",
   "lastCommitMessage",
+  "currentBranch",
+  "listRefs",
   "hasCommits",
   "resolveRef",
   "readRefOption",
@@ -367,6 +382,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()
@@ -1036,6 +1118,12 @@ export const runGitScriptContract = (): void => {
       expect(t.observe.resolveRef("refs/gtd/marker")).toBe(head)
     })
 
+    it("updateRef with HEAD points the ref at the commit just made", () => {
+      execScript(t, commitAll("feat: just made"))
+      execScript(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))
@@ -1049,4 +1137,47 @@ export const runGitScriptContract = (): void => {
       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", () => {
+      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", () => {
+      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
@@ -137,10 +140,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"),
+      }))
   }
 
   /**
@@ -287,7 +307,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 +327,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)