@pmelab/gtd 27.3.0 → 27.4.0

package/src/testkit/EmittedScriptRecognizer.ts

@@ -6,6 +6,7 @@
 import {
   commitAll,
   commitAsIs,
+  commitClean,
   deleteRef,
   discardPending,
   hardResetTo,
@@ -185,6 +186,17 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
     return undefined
   }
 
+  if (block.startsWith("gtd_head=$(git rev-parse --verify HEAD) || exit 1\nif [ -n ")) {
+    const [message] = extractQuotedTokens(block.slice(block.indexOf('"$gtd_head" -m ')))
+    if (message !== undefined && commitClean(message) === block) {
+      const failure = repo.commitClean(message)
+      return failure === undefined
+        ? { kind: "applied" }
+        : { kind: "failed", error: failure, status: 1 }
+    }
+    return undefined
+  }
+
   if (block.startsWith("if ! out=$(git commit --allow-empty -m ")) {
     const [message] = extractQuotedTokens(conditionLine)
     if (message !== undefined && commitAsIs(message) === block) {

package/src/testkit/FakeGitOperations.ts

@@ -77,7 +77,12 @@ const makeGitReaderOps = (repo: InMemRepo, root: string): GitReaderOperations =>
 
   changedPaths: (base?: string) => Effect.succeed(repo.changedPathsWorktree(base)),
 
+  stagedPaths: () => Effect.succeed(repo.stagedPaths()),
+
   diffPaths: (base: string, tip: string) => tryCatch(() => repo.diffPaths(base, tip)),
+
+  // The identity `GitTiers`' live tier configures; the fake commits as no one in particular.
+  authorIdent: () => Effect.succeed(Option.some({ name: "Test", email: "test@test.com" })),
 })
 
 const failOn = (output: string | undefined): void => {

package/src/testkit/GitTiers.ts

@@ -23,6 +23,7 @@ import { Narrator, GitService, Host, type GitOperations } from "../platform/inde
 import {
   commitAll,
   commitAsIs,
+  commitClean,
   softResetTo,
   mixedResetTo,
   hardResetTo,
@@ -81,6 +82,8 @@ export interface GitTierSeed {
   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
+  /** `commit.gpgSign=true` with a signer that succeeds; `git commit` and `commit-tree -S` both sign. */
+  readonly workingSigner: () => void
 }
 
 export interface GitTierObserve {
@@ -94,6 +97,8 @@ export interface GitTierObserve {
   readonly headSubject: () => string
   /** Paths HEAD's own commit touched, against its parent — not the whole tree. */
   readonly headTouchedPaths: () => ReadonlyArray<string>
+  /** True when HEAD's commit object carries a signature (`gpgsig` header). */
+  readonly headSigned: () => boolean
 }
 
 export interface GitTier {
@@ -233,6 +238,18 @@ const makeLiveTier = (initialCommit = true): GitTier => {
         gitExec("config", "gpg.format", "openpgp")
         gitExec("config", "gpg.program", "false")
       },
+      workingSigner: () => {
+        const signer = join(root, ".git/gtd-test-signer.sh")
+        // git checks `[GNUPG:] SIG_CREATED ` on stderr (--status-fd=2) and takes stdout as the signature.
+        writeFileSync(
+          signer,
+          `#!/bin/sh\ncat >/dev/null\nprintf '%s\\n' '-----BEGIN PGP SIGNATURE-----' '' 'ZHVtbXk=' '-----END PGP SIGNATURE-----'\nprintf '\\n[GNUPG:] SIG_CREATED ' >&2\n`,
+          { mode: 0o755 },
+        )
+        gitExec("config", "commit.gpgsign", "true")
+        gitExec("config", "gpg.format", "openpgp")
+        gitExec("config", "gpg.program", signer)
+      },
     },
     observe: {
       resolveRef: (ref) => gitExec("rev-parse", ref),
@@ -268,6 +285,7 @@ const makeLiveTier = (initialCommit = true): GitTier => {
         gitExec("show", "--name-only", "--pretty=format:", "HEAD")
           .split("\n")
           .filter((line) => line.length > 0),
+      headSigned: () => gitExec("cat-file", "commit", "HEAD").includes("\ngpgsig "),
     },
     runScript: (script) => {
       // One stream, as a driver's terminal shows it.
@@ -345,6 +363,9 @@ const makeInMemTier = (initialCommit = true): GitTier => {
       failingSigner: () => {
         repo.signingFails = true
       },
+      workingSigner: () => {
+        repo.signingEnabled = true
+      },
     },
     observe: {
       resolveRef: (ref) => {
@@ -369,6 +390,7 @@ const makeInMemTier = (initialCommit = true): GitTier => {
           .filter((p) => repo.fileAtRef("HEAD~1", p) !== repo.fileAtRef("HEAD", p))
           .sort()
       },
+      headSigned: () => repo.headSigned(),
     },
     runScript: (script, commands = new Map()) => {
       const { ok, status, output, error } = applyEmittedScript(repo, commands, script)
@@ -409,7 +431,9 @@ export const CONTRACT_COVERED_OPERATIONS: ReadonlySet<keyof GitOperations> = new
   "subjectHistory",
   "readFileAtRef",
   "changedPaths",
+  "stagedPaths",
   "diffPaths",
+  "authorIdent",
   "commitAllWithPrefix",
   "softResetTo",
   "commitAsIs",
@@ -481,7 +505,9 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
         g.readFileAtRef("HEAD", "second.txt"),
         g.changedPaths(),
         g.changedPaths("HEAD~1"),
+        g.stagedPaths(),
         g.diffPaths("HEAD~1", "HEAD"),
+        g.authorIdent(),
       ]),
     )
     expect(await t.observe.snapshot()).toBe(before)
@@ -1071,6 +1097,14 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
       expect(await runGit(t, (g) => g.changedPaths())).toEqual([])
     })
 
+    it("ignores an edit staged and then reverted in the worktree", async () => {
+      t.seed.commit("chore: seed", { "a.txt": "1" })
+      t.seed.writeFile("a.txt", "2")
+      t.seed.stageAll()
+      t.seed.writeFile("a.txt", "1")
+      expect(await runGit(t, (g) => g.changedPaths())).toEqual([])
+    })
+
     for (const { label, path } of PATHOLOGICAL_PATHS) {
       it(`reports an untracked path containing ${label}, verbatim`, async () => {
         t.seed.writeFile(path, "content")
@@ -1172,6 +1206,43 @@ export const runGitServiceContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe("stagedPaths", () => {
+    it("returns [] when the index matches HEAD, whatever the worktree holds", async () => {
+      t.seed.commit("chore: seed", { "a.txt": "1" })
+      t.seed.writeFile("a.txt", "2")
+      t.seed.writeFile("u.txt", "u")
+      expect(await runGit(t, (g) => g.stagedPaths())).toEqual([])
+    })
+
+    it("reports an edit staged and then reverted in the worktree", async () => {
+      t.seed.commit("chore: seed", { "a.txt": "1" })
+      t.seed.writeFile("a.txt", "2")
+      t.seed.stageAll()
+      t.seed.writeFile("a.txt", "1")
+      expect(await runGit(t, (g) => g.stagedPaths())).toEqual([{ path: "a.txt", status: "M" }])
+    })
+
+    it("reports staged additions and deletions", async () => {
+      t.seed.commit("chore: seed", { "gone.txt": "g" })
+      t.seed.deleteFile("gone.txt")
+      t.seed.writeFile("new.txt", "n")
+      t.seed.stageAll()
+      const staged = await runGit(t, (g) => g.stagedPaths())
+      expect([...staged].sort((a, b) => a.path.localeCompare(b.path))).toEqual([
+        { path: "gone.txt", status: "D" },
+        { path: "new.txt", status: "A" },
+      ])
+    })
+  })
+
+  describe("authorIdent", () => {
+    it("is the configured name and email", async () => {
+      expect(await runGit(t, (g) => g.authorIdent())).toEqual(
+        Option.some({ name: "Test", email: "test@test.com" }),
+      )
+    })
+  })
+
   describe("topLevel", () => {
     it("resolves to this tier's own root", async () => {
       expect(await runGit(t, (g) => g.topLevel())).toBe(t.root)
@@ -1286,6 +1357,93 @@ export const runGitScriptContract = (makeTier: () => GitTier): void => {
     })
   })
 
+  describe("commitClean", () => {
+    it("on a clean tree commits an empty commit with the message", () => {
+      const headBefore = t.observe.resolveRef("HEAD")
+      run(t, commitClean("gtd(human): gate → again"))
+      expect(t.observe.resolveRef("HEAD")).not.toBe(headBefore)
+      expect(t.observe.headSubject()).toBe("gtd(human): gate → again")
+      expect(t.observe.headTouchedPaths()).toEqual([])
+    })
+
+    it("a staging hook never runs: nothing touched, nothing staged, file absent", () => {
+      const headBefore = t.observe.resolveRef("HEAD")
+      t.seed.stagingHook("hooked.txt", "hooked")
+      run(t, commitClean("gtd(human): gate → again"))
+      expect(t.observe.headTouchedPaths()).toEqual([])
+      expect(t.observe.resolveRef("HEAD^")).toBe(headBefore)
+      expect(t.observe.statusPorcelain().trim()).toBe("")
+      expect(t.observe.existsPath("hooked.txt")).toBe(false)
+    })
+
+    it("a rejecting hook is never consulted", () => {
+      t.seed.rejectingHook("rejected")
+      run(t, commitClean("gtd(human): gate → again"))
+      expect(t.observe.headSubject()).toBe("gtd(human): gate → again")
+    })
+
+    it("a working signer signs the approval", () => {
+      t.seed.workingSigner()
+      run(t, commitClean("gtd(human): gate → again"))
+      expect(t.observe.headSigned()).toBe(true)
+    })
+
+    it("no signing config: the approval does not try to sign", () => {
+      run(t, commitClean("gtd(human): gate → again"))
+      expect(t.observe.headSigned()).toBe(false)
+    })
+
+    it("a failing signer fails the approval: HEAD and status unchanged", () => {
+      t.seed.failingSigner()
+      const headBefore = t.observe.resolveRef("HEAD")
+      const result = t.runScript(commitClean("gtd(human): gate → again"))
+      expect(result.ok).toBe(false)
+      expect(result.status).toBe(1)
+      expect(result.output).toContain("failed to sign")
+      expect(t.observe.resolveRef("HEAD")).toBe(headBefore)
+      expect(t.observe.statusPorcelain().trim()).toBe("")
+    })
+
+    const refused = (name: string, dirty: () => void, pending: string): void => {
+      it(`${name}: fails, HEAD unchanged, edit still pending`, () => {
+        dirty()
+        const headBefore = t.observe.resolveRef("HEAD")
+        const result = t.runScript(commitClean("gtd(human): gate → again"))
+        expect(result.ok).toBe(false)
+        expect(result.output).toContain("changed since `gtd land`")
+        expect(t.observe.resolveRef("HEAD")).toBe(headBefore)
+        expect(t.observe.statusPorcelain()).toContain(pending)
+      })
+    }
+    refused(
+      "a modified tracked file",
+      () => {
+        t.seed.commit("feat: base", { "a.txt": "1" })
+        t.seed.writeFile("a.txt", "2")
+      },
+      "a.txt",
+    )
+    refused(
+      "a staged change",
+      () => {
+        t.seed.writeFile("s.txt", "s")
+        t.seed.stageAll()
+      },
+      "s.txt",
+    )
+    refused("an untracked file", () => t.seed.writeFile("u.txt", "u"), "u.txt")
+    refused(
+      "an edit staged then reverted in the worktree",
+      () => {
+        t.seed.commit("feat: base", { "a.txt": "1" })
+        t.seed.writeFile("a.txt", "2")
+        t.seed.stageAll()
+        t.seed.writeFile("a.txt", "1")
+      },
+      "a.txt",
+    )
+  })
+
   describe("commitAsIs", () => {
     it("does NOT stage — a worktree write after staging is excluded (the squash mechanic)", () => {
       t.seed.writeFile("a.txt", "a")

package/src/testkit/InMemRepo.ts

@@ -1,5 +1,6 @@
-// Pure TypeScript, no Effect, no real filesystem/git.
+// No real filesystem/git.
 import { createHash } from "node:crypto"
+import { CHANGED_SINCE_LAND } from "../emit/index.js"
 
 /** Embedded in every value this fake reaches (see also `strictGitOperations`'s default message) so `scripts/assert-no-test-doubles.mjs` can catch a leak into the shipped bundle by string search. */
 export const TEST_DOUBLE_SENTINEL = "gtd:test-double:never-ship"
@@ -11,6 +12,7 @@ interface Commit {
   parent: string | null
   /** Creation order — the twin's stand-in for a committer date. */
   seq: number
+  readonly signed: boolean
 }
 
 function sha1(input: string): string {
@@ -270,6 +272,11 @@ export class InMemRepo {
     return diffTrees(baseTree, worktreeTree)
   }
 
+  /** The index vs HEAD — the port's `stagedPaths`. */
+  stagedPaths(): Array<{ path: string; status: string }> {
+    return diffTrees(this.treeAt(undefined), this.index)
+  }
+
   diffPaths(base: string, tip: string): string[] {
     for (const ref of [base, tip]) {
       if (this.resolveRef(ref) === null) throw new Error(`Invalid ref: ${ref}`)
@@ -346,6 +353,7 @@ export class InMemRepo {
   /** 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
+  signingEnabled = false
   /** Seeded: a pre-commit hook writing and staging this file. */
   hookStages: { readonly path: string; readonly content: string } | undefined = undefined
 
@@ -353,7 +361,14 @@ 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, seq: this.nextSeq++ }
+    const commit: Commit = {
+      hash,
+      message,
+      files: new Map(tree),
+      parent,
+      seq: this.nextSeq++,
+      signed: this.signingEnabled,
+    }
     this.commits.set(hash, commit)
     this.head = hash
     this.branches.set(this.currentBranch, hash)
@@ -378,6 +393,19 @@ export class InMemRepo {
     return undefined
   }
 
+  /** Twin of `GitScript.commitClean`: no hook runs, HEAD's tree is recorded; `undefined` on success, else the stderr text. */
+  commitClean(message: string): string | undefined {
+    if (this.head === null) return "fatal: Needed a single revision"
+    if (this.statusPorcelain().trim() !== "") return CHANGED_SINCE_LAND
+    if (this.signingFails) return "error: gpg failed to sign the data"
+    this.writeCommit(message)
+    return undefined
+  }
+
+  headSigned(): boolean {
+    return this.headCommit()?.signed === true
+  }
+
   /** 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) {
@@ -393,7 +421,14 @@ export class InMemRepo {
     const tree = new Map(this.index)
     const parent = this.head
     const hash = makeHash(message, parent, tree)
-    this.commits.set(hash, { hash, message, files: new Map(tree), parent, seq: this.nextSeq++ })
+    this.commits.set(hash, {
+      hash,
+      message,
+      files: new Map(tree),
+      parent,
+      seq: this.nextSeq++,
+      signed: false,
+    })
     const ref = `${refPrefix}/${hash}`
     this.refs.set(ref, hash)
     this.index = new Map(this.headTree())

package/src/wire/BeatDocument.test.ts

@@ -10,6 +10,7 @@ import {
   type StatusChange,
   DEMAND_BRIEFING,
   renderBeatPlain,
+  type ApprovalEntry,
   type ModelCost,
   type RenderedDemandSource,
   WIRE_SCHEMA,
@@ -34,6 +35,7 @@ interface DocumentInput {
   readonly next?: NextMatch | null
   readonly cost?: number
   readonly costByModel?: readonly ModelCost[]
+  readonly approvals?: readonly ApprovalEntry[]
 }
 
 /** `demandOf`'s own input, isolated so `documentFor` stays a flat two-call body — `session`/`validate` are only spread in when the caller actually passed one, since `demandOf`'s `prompt` variant forbids an explicit `undefined`. */
@@ -61,6 +63,7 @@ const statusInput = (
   next: input.next ?? null,
   cost: input.cost ?? 0,
   costByModel: input.costByModel ?? [],
+  approvals: input.approvals ?? [],
 })
 
 /** Builds one full `BeatDocument` in one call, mirroring the pre-split `beatFields` call shape so every golden below reads the same as before this package. */
@@ -87,6 +90,7 @@ describe("beatDocument / renderBeatJson", () => {
       workflow: "feature",
       changes: [],
       next: null,
+      approvals: [],
     })
   })
 
@@ -267,9 +271,29 @@ describe("beatDocument / renderBeatJson", () => {
       "judge",
       "skills",
       "access",
+      "approvals",
     ])
   })
 
+  it("emits approvals always, [] when none, at every kind", () => {
+    for (const kind of BEAT_KINDS) {
+      const parsed = JSON.parse(renderJsonLine({ kind })) as Record<string, unknown>
+      expect(parsed.approvals).toEqual([])
+    }
+  })
+
+  it("carries approvals verbatim, in the order given", () => {
+    const approvals = [
+      { step: "gate#1", name: "Ada", email: "ada@x.io", commit: "a".repeat(40) },
+      { step: "gate#2", name: "Bo", email: "bo@x.io", commit: "b".repeat(40) },
+    ]
+    const parsed = JSON.parse(renderJsonLine({ kind: "message", approvals })) as Record<
+      string,
+      unknown
+    >
+    expect(parsed.approvals).toEqual(approvals)
+  })
+
   it("emits access at kind prompt, null per side when unrestricted", () => {
     const bare = JSON.parse(renderJsonLine({ kind: "prompt" })) as Record<string, unknown>
     expect(bare.access).toEqual({ read: null, write: null })
@@ -377,6 +401,7 @@ describe("golden bytes", () => {
         workflow: "feature",
         changes: [],
         next: null,
+        approvals: [],
       }) + "\n",
     )
   })

package/src/wire/BeatDocument.ts

@@ -1,6 +1,6 @@
 import type { BeatKind, Demand, DemandSession } from "./Demand.js"
 import type { BeatStatus, NextMatch, StatusChange } from "./BeatStatus.js"
-import type { Actor, ModelCost, StateMode, StateName, StepAccess } from "./types.js"
+import type { Actor, ApprovalEntry, ModelCost, StateMode, StateName, StepAccess } from "./types.js"
 import { WIRE_SCHEMA } from "./constants.js"
 
 /** `gtd next --json`'s `next` key — `null` when landing would commit nothing. */
@@ -72,10 +72,11 @@ export interface BeatDocument {
   readonly judge: string | undefined
   readonly skills: readonly string[] | undefined
   readonly access: StepAccess | undefined
+  readonly approvals: readonly ApprovalEntry[]
 }
 
 /**
- * Flatten a `Demand` plus its `BeatStatus` into the single 24-key document
+ * Flatten a `Demand` plus its `BeatStatus` into the single 25-key document
  * `gtd next --json` emits — the ONLY place the two are joined. `cost`/
  * `costByModel` are omitted together, exactly when no cost was recorded
  * (`cost <= 0`).
@@ -108,6 +109,7 @@ export const beatDocument = (demand: Demand, status: BeatStatus): BeatDocument =
     judge: status.judge,
     skills,
     access,
+    approvals: status.approvals,
   }
 }
 

package/src/wire/BeatPlain.test.ts

@@ -28,6 +28,7 @@ const documentFor = (kind: BeatKind, content: string, rest: Partial<RenderedDema
     next: { target: "idle" },
     cost: 0,
     costByModel: [],
+    approvals: [],
   })
   return beatDocument(demand, status)
 }

package/src/wire/BeatStatus.test.ts

@@ -19,6 +19,7 @@ const baseInput = (overrides: Partial<RenderedDemandSource> = {}) => ({
   next: null,
   cost: 0,
   costByModel: [],
+  approvals: [],
 })
 
 describe("statusOf", () => {
@@ -47,6 +48,7 @@ describe("statusOf", () => {
       next: { target: "idle" },
       cost: 12,
       costByModel: [{ model: "opus", cost: 12 }],
+      approvals: [],
     })
     expect(status.workflow).toBe("feature")
     expect(status.idle).toBe(true)

package/src/wire/BeatStatus.ts

@@ -1,4 +1,11 @@
-import type { Actor, ModelCost, RenderedDemandSource, StateMode, StateName } from "./types.js"
+import type {
+  ApprovalEntry,
+  Actor,
+  ModelCost,
+  RenderedDemandSource,
+  StateMode,
+  StateName,
+} from "./types.js"
 
 /** One pending change — `gtd next --json`'s `changes` entries. */
 export interface StatusChange {
@@ -39,6 +46,7 @@ export interface BeatStatus {
   readonly cost: number
   readonly costByModel: readonly ModelCost[]
   readonly judge: string | undefined
+  readonly approvals: readonly ApprovalEntry[]
 }
 
 /**
@@ -57,8 +65,10 @@ export const statusOf = (input: {
   readonly next: NextMatch | null
   readonly cost: number
   readonly costByModel: readonly ModelCost[]
+  readonly approvals: readonly ApprovalEntry[]
 }): BeatStatus => {
-  const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel } = input
+  const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel, approvals } =
+    input
   return {
     idle,
     initial,
@@ -77,5 +87,6 @@ export const statusOf = (input: {
     cost,
     costByModel,
     judge: rendered.judge,
+    approvals,
   }
 }

package/src/wire/WireSchema.test.ts

@@ -86,6 +86,7 @@ const beat = (kind: BeatKind): string => {
     next: { target: "idle" },
     cost: 12,
     costByModel: [{ model: "opus", cost: 12 }],
+    approvals: [{ step: "gate#1", name: "Ada", email: "ada@x.io", commit: "a".repeat(40) }],
   })
   return renderBeatJson(beatDocument(demand, status))
 }
@@ -129,6 +130,15 @@ describe(`wire schema ${WIRE_SCHEMA}`, () => {
     })
   }
 
+  it("approvals is an additive field: present on every beat, WIRE_SCHEMA unchanged", () => {
+    expect(WIRE_SCHEMA).toBe(1)
+    for (const kind of BEAT_KINDS) {
+      expect(JSON.parse(documents[`beat-${kind}.json`]!)).toHaveProperty("approvals", [
+        { step: "gate#1", name: "Ada", email: "ada@x.io", commit: "a".repeat(40) },
+      ])
+    }
+  })
+
   describe("the shape check", () => {
     const land = JSON.parse(documents["land.json"]!) as Record<string, unknown>
     const { subject, ...rest } = land

package/src/wire/types.ts

@@ -30,6 +30,14 @@ export interface StepAccess {
   readonly write: readonly string[] | null
 }
 
+/** One approval commit of the process: `step` is the formatted `<name>#<n>`, `commit` the approving commit's hash. */
+export interface ApprovalEntry {
+  readonly step: string
+  readonly name: string
+  readonly email: string
+  readonly commit: string
+}
+
 export interface RenderedDemandSource {
   readonly state: StateName
   readonly actor: Actor

package/src/workflow/Workflow.ts

@@ -41,6 +41,7 @@ export interface StepDef {
   readonly allowEmpty?: boolean
   readonly keep?: boolean
   readonly acceptClean?: boolean
+  readonly approve?: boolean
   readonly skills?: readonly string[]
   readonly access?: StepAccess
 }