@pmelab/gtd 58.1.0 → 59.0.0

package/src/testkit/TestRepo.test.ts

@@ -12,7 +12,16 @@ import {
   softResetTo,
   updateRef,
 } from "../emit/index.js"
-import { agent, human, moveScript, read, removeScript, run } from "../flows/index.js"
+import {
+  agent,
+  check,
+  human,
+  moveScript,
+  read,
+  removeScript,
+  run,
+  showScript,
+} from "../flows/index.js"
 import { runsItsScript, testRepo } from "./TestRepo.js"
 
 const tiny = async (): Promise<void> => {
@@ -112,7 +121,7 @@ describe("testRepo", () => {
   it("carries the recognizer's error when a git-free fallback fails", () => {
     const repo = testRepo({ workflow: { default: tiny } })
     expect(() => repo.runScript("printf 'x' > 'y'\n")).toThrow(
-      "testkit: cannot run script in memory — give the step an actor instead\nunrecognized script block: printf 'x' > 'y'",
+      "testkit: cannot run script in memory — add a canned command for it, or give the step an actor\nunrecognized script block: printf 'x' > 'y'",
     )
   })
 
@@ -194,4 +203,111 @@ describe("testRepo", () => {
       repo.drive({ spin: (_, r) => r.write("n", `${++n}\n`) }, { maxBeats: 5 }),
     ).rejects.toThrow(/did not rest within 5 beats/)
   })
+
+  describe("canned commands", () => {
+    const checked = async (): Promise<void> => {
+      const green = await check("test", "npm test", { report: ".gtd/FEEDBACK.md" })
+      await human(green ? "sign-off" : "red")
+    }
+
+    it("runs a check's command as canned, its output the report", async () => {
+      const repo = testRepo({
+        workflow: { default: checked },
+        commands: [{ run: "npm test", exit: 1, output: "1 failing" }],
+      })
+      repo.write("go", "\n")
+      const rest = await repo.drive({ test: runsItsScript })
+      expect(rest.state).toBe("red")
+      expect(repo.read(".gtd/FEEDBACK.md")).toContain("1 failing")
+    })
+
+    it("exits 0 by default, and matches by pattern", async () => {
+      const repo = testRepo({ workflow: { default: checked }, commands: [{ run: /^npm / }] })
+      repo.write("go", "\n")
+      expect((await repo.drive({ test: runsItsScript })).state).toBe("sign-off")
+    })
+
+    it("lets a command change the tree, and takes the first match", async () => {
+      const repo = testRepo({
+        workflow: { default: checked },
+        commands: [
+          { run: "npm test", effect: (r) => r.write("ran", "first\n") },
+          { run: /npm/, exit: 1 },
+        ],
+      })
+      repo.write("go", "\n")
+      expect((await repo.drive({ test: runsItsScript })).state).toBe("sign-off")
+      expect(repo.read("ran")).toBe("first\n")
+    })
+
+    it("takes a command added later", async () => {
+      const repo = testRepo({ workflow: { default: checked } })
+      repo.command({ run: "npm test", exit: 2 })
+      repo.write("go", "\n")
+      expect((await repo.drive({ test: runsItsScript })).state).toBe("red")
+    })
+
+    it("runs a plain script line as canned", () => {
+      const repo = testRepo({
+        workflow: { default: tiny },
+        commands: [{ run: "make docs", effect: (r) => r.write("docs.html", "<p>\n") }],
+      })
+      repo.runScript("make docs\n")
+      expect(repo.read("docs.html")).toBe("<p>\n")
+    })
+
+    it("fails the drive on a command none matches, naming it", async () => {
+      const repo = testRepo({ workflow: { default: checked } })
+      repo.write("go", "\n")
+      await expect(repo.drive({ test: runsItsScript })).rejects.toThrow(
+        "no canned command matches `npm test`",
+      )
+    })
+  })
+
+  describe("history", () => {
+    it("creates and checks out a branch, refusing uncommitted changes", () => {
+      const repo = testRepo({ workflow: { default: tiny }, files: { "a.txt": "main\n" } })
+      repo.branch("feature/x")
+      repo.checkout("feature/x")
+      expect(repo.branchName()).toBe("feature/x")
+      repo.write("a.txt", "feature\n")
+      expect(() => repo.checkout("main")).toThrow("uncommitted changes")
+      repo.commit("feat: x")
+      repo.checkout("main")
+      expect(repo.branchName()).toBe("main")
+      expect(repo.read("a.txt")).toBe("main\n")
+      expect(repo.show("feature/x", "a.txt")).toBe("feature\n")
+    })
+
+    it("branches at a given ref, and refuses an existing name or a missing ref", () => {
+      const repo = testRepo({ workflow: { default: tiny }, files: { "a.txt": "one\n" } })
+      repo.write("a.txt", "two\n")
+      repo.commit("chore: two")
+      repo.branch("old", "HEAD~1")
+      expect(repo.show("old", "a.txt")).toBe("one\n")
+      expect(() => repo.branch("old")).toThrow("already exists")
+      expect(() => repo.branch("new", "nowhere")).toThrow("not a valid object name")
+    })
+
+    it("points a remote ref that a script reads by its short name", async () => {
+      const restore = async (): Promise<void> => {
+        await run("restore", showScript("origin/main", "a.txt", "a.txt"))
+        await human("done")
+      }
+      const repo = testRepo({ workflow: { default: restore }, files: { "a.txt": "base\n" } })
+      repo.ref("refs/remotes/origin/main")
+      repo.write("a.txt", "local\n")
+      repo.commit("chore: local")
+      repo.write("go", "\n")
+      await repo.drive({ restore: runsItsScript })
+      expect(repo.read("a.txt")).toBe("base\n")
+    })
+
+    it("refuses a ref outside refs/ or at nothing", () => {
+      const repo = testRepo({ workflow: { default: tiny } })
+      expect(() => repo.ref("origin/main")).toThrow("must start with refs/")
+      expect(() => repo.ref("refs/tags/v1", "nowhere")).toThrow("resolves to no commit")
+    })
+  })
 })

package/src/testkit/TestRepo.ts

@@ -8,6 +8,7 @@ import {
   InMemRepo,
   makeCapturingCliIo,
   type CapturedCliResult,
+  type CommandTable,
 } from "../twins/index.js"
 
 /**
@@ -18,8 +19,23 @@ import {
  */
 export type WorkflowModule = string | Readonly<Record<string, unknown>>
 
+/**
+ * What a command a step's script runs does in memory. `run` matches the command
+ * as the script spells it, exactly or by a pattern; the first match wins.
+ */
+export interface CannedCommand {
+  readonly run: string | RegExp
+  /** Defaults to 0. */
+  readonly exit?: number
+  readonly output?: string
+  /** What the command does to the tree, e.g. a formatter's rewrite. */
+  readonly effect?: (repo: TestRepo) => void
+}
+
 export interface TestRepoOptions {
   readonly workflow: WorkflowModule
+  /** The commands a step's script may run. A command none matches fails the script. */
+  readonly commands?: readonly CannedCommand[]
   /** Committed alongside the config, before any process starts. */
   readonly files?: Readonly<Record<string, string>>
   /** The environment gtd sees; the real `process.env` is never read, except ambient `GTD_FLAG_*` (explicit env wins). */
@@ -42,6 +58,15 @@ export interface DriveOptions {
 }
 
 export interface TestRepo {
+  /** Adds a command a step's script may run, after those `testRepo` was given. */
+  command(command: CannedCommand): void
+  /** Creates branch `name` at `ref` (HEAD by default). Outside a process only. */
+  branch(name: string, ref?: string): void
+  /** Checks branch `name` out; refuses with uncommitted changes. Outside a process only. */
+  checkout(name: string): void
+  /** Points ref `name` (`refs/remotes/origin/main`, `refs/tags/v1`) at `ref` (HEAD by default). Outside a process only. */
+  ref(name: string, ref?: string): void
+  branchName(): string
   read(path: string): string | undefined
   write(path: string, content: string): void
   remove(path: string): void
@@ -158,19 +183,21 @@ const LINES: ReadonlyArray<readonly [RegExp, (repo: InMemRepo, words: string[])
 const knownLine = (line: string) => LINES.find(([pattern]) => pattern.test(line))
 
 const cannotRun = (error: string): Error =>
-  new Error(`testkit: cannot run script in memory — give the step an actor instead\n${error}`)
+  new Error(
+    `testkit: cannot run script in memory — add a canned command for it, or give the step an actor\n${error}`,
+  )
 
 // A script with a line `LINES` lacks goes to the contract-tested recognizers
 // whole, minus the git builders: they would apply a commit/reset/update-ref in
 // memory, so any git-mutating block is refused whatever its spelling.
-const runLines = (repo: InMemRepo, script: string): void => {
+const runLines = (repo: InMemRepo, commands: CommandTable, script: string): void => {
   const lines = script.split("\n").map((line) => line.trim())
   const known = lines.map(knownLine)
   if (known.every(Boolean)) {
     known.forEach((k, i) => k![1](repo, words(lines[i]!)))
     return
   }
-  const applied = applyEmittedScript(repo, new Map(), script, { git: false })
+  const applied = applyEmittedScript(repo, commands, script, { git: false })
   if (!applied.ok) throw cannotRun(applied.error ?? "")
 }
 
@@ -189,6 +216,18 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content)
   repo.seedCommit("chore: initial commit")
 
+  const canned = [...(options.commands ?? [])]
+  const commands: CommandTable = {
+    get: (command) => {
+      const hit = canned.find(({ run }) =>
+        typeof run === "string" ? run === command : run.test(command),
+      )
+      if (hit === undefined) return undefined
+      const { exit = 0, output = "", effect } = hit
+      return { kind: "exit", status: exit, output, effect: () => effect?.(self) }
+    },
+  }
+
   // The module is registered only while gtd runs, so nothing outlives the
   // call that loads it and no test can reach another's module.
   const gtd = async (...args: string[]): Promise<CapturedCliResult> => {
@@ -217,7 +256,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
 
   const apply = (what: string, script: string): void => {
     if (script.length === 0) return
-    const applied = applyEmittedScript(repo, new Map(), script)
+    const applied = applyEmittedScript(repo, commands, script)
     if (!applied.ok) throw new Error(`${what}: its script failed — ${applied.error ?? ""}`)
   }
 
@@ -260,14 +299,26 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   }
 
   const self: TestRepo = {
+    command: (command) => {
+      canned.push(command)
+    },
+    branch: (name, ref = "HEAD") => repo.createBranch(name, ref),
+    checkout: (name) => repo.checkoutBranch(name),
+    ref: (name, ref = "HEAD") => {
+      if (!name.startsWith("refs/")) throw new Error(`testkit: ref "${name}" must start with refs/`)
+      const hash = repo.resolveRef(ref)
+      if (hash === null) throw new Error(`testkit: ref "${ref}" resolves to no commit`)
+      repo.updateRef(name, hash)
+    },
+    branchName: () => repo.branchName(),
     read: (path) => repo.readFile(path),
     write: (path, content) => repo.writeFile(path, content),
     remove: (path) => repo.deleteFile(path),
     commit: (message) => repo.seedCommit(message),
     show: (ref, path) => repo.fileAtRef(ref, path) ?? undefined,
     runScript: (script) => {
-      const flow = applyFlowScript(repo, new Map(), script)
-      if (flow === undefined) runLines(repo, script)
+      const flow = applyFlowScript(repo, commands, script)
+      if (flow === undefined) runLines(repo, commands, script)
       else if (!flow.ok) throw new Error(`testkit: ${flow.error ?? ""}`)
     },
     gtd,

package/src/testkit/index.ts

@@ -6,6 +6,7 @@ export {
   testRepo,
   type Actor,
   type Actors,
+  type CannedCommand,
   type DriveOptions,
   type TestRepo,
   type TestRepoOptions,

package/src/twins/EmittedScriptRecognizer.ts

@@ -36,7 +36,7 @@ import { refNameFault } from "../replay/index.js"
 import { renderFormat } from "../wire/index.js"
 import { applyFlowScript, rewritten } from "./FlowScripts.js"
 import type { InMemRepo } from "./InMemRepo.js"
-import type { ScriptedCommand } from "./Layers.js"
+import type { CommandTable } from "./Layers.js"
 
 export interface AppliedScriptResult {
   readonly ok: boolean
@@ -266,10 +266,7 @@ const recognizeFileExistsGuard = (repo: InMemRepo, block: string): BlockOutcome
 /** `binaryGuard`. The in-memory tier has no `$PATH`: a binary is present unless declared `missing`. */
 const BINARY_GUARD_MESSAGE_RE = /^gtd: mode "([^"]+)": "(format|validate)" command not found: (.+)$/
 
-const recognizeBinaryGuard = (
-  commands: ReadonlyMap<string, ScriptedCommand>,
-  block: string,
-): BlockOutcome | undefined => {
+const recognizeBinaryGuard = (commands: CommandTable, block: string): BlockOutcome | undefined => {
   const [binary, , message] = extractQuotedTokens(block)
   if (binary === undefined || message === undefined) return undefined
   const match = BINARY_GUARD_MESSAGE_RE.exec(message)
@@ -330,7 +327,7 @@ const expandFileVar = (text: string): string | undefined => {
  */
 const recognizeModeCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const command = expandFileVar(block) ?? block
@@ -356,7 +353,7 @@ const FAILURE_PROMPT_FOOTER = ' "$gtd_validate_out"\n  exit "$gtd_validate_statu
 
 const recognizeFailurePromptWrapper = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   if (!block.startsWith(FAILURE_PROMPT_HEADER) || !block.endsWith(FAILURE_PROMPT_FOOTER)) {
@@ -465,7 +462,7 @@ const parseModeContradictionCheck = (block: string): ParsedModeContradictionChec
  */
 const simulateModeContradictionCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   parsed: ParsedModeContradictionCheck,
 ): BlockOutcome => {
   const { mode, samplePath, sample, formatCommand, format } = parsed
@@ -502,7 +499,7 @@ const simulateModeContradictionCheck = (
  */
 const recognizeModeContradictionCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const parsed = parseModeContradictionCheck(block)
@@ -570,7 +567,7 @@ const PRESENTATION_SUBSHELL_SUFFIX = `\n) || ${PRESENTATION_FAILURE_WARNING}`
 
 const recognizePresentationSubshell = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
   git: boolean,
 ): BlockOutcome | undefined => {
@@ -595,7 +592,7 @@ const recognizePresentationSubshell = (
 /** Anything left over must be an EXACT hit in the scripted-command table — mirrors `ScriptedCommand`'s two `kind`s (`Layers.ts`). */
 const recognizeScriptedCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   block: string,
 ): BlockOutcome | undefined => {
   const scripted = commands.get(block)
@@ -607,6 +604,7 @@ const recognizeScriptedCommand = (
   if (scripted.kind === "missing") {
     return { kind: "failed", error: `sh: ${block.split(" ")[0]}: not found`, status: 127 }
   }
+  scripted.effect?.()
   if (scripted.status !== 0) {
     return { kind: "failed", error: scripted.output, status: scripted.status }
   }
@@ -693,7 +691,7 @@ const recognizeWriteLines = (repo: InMemRepo, block: string): BlockOutcome | und
 /** Every recognizer `applyEmittedScript` tries, first match wins — `recognizeScriptedCommand` stays last since it's the exact-hit fallback for anything the rest don't claim. */
 const recognizersFor = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   git: boolean,
 ): ReadonlyArray<(block: string) => BlockOutcome | undefined> => [
   (block) => recognizeSetFlags(block),
@@ -735,7 +733,7 @@ const recognizeBlock = (
  */
 export const applyEmittedScript = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
   { git = true }: { readonly git?: boolean } = {},
 ): AppliedScriptResult => {
@@ -750,7 +748,7 @@ export const applyEmittedScript = (
 
 const applyBlocks = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
   git: boolean,
 ): AppliedScriptResult => {

package/src/twins/FlowScripts.ts

@@ -15,7 +15,7 @@ import {
   writeScript,
 } from "../flows/index.js"
 import type { InMemRepo } from "./InMemRepo.js"
-import type { ScriptedCommand } from "./Layers.js"
+import type { CommandTable, ScriptedCommand } from "./Layers.js"
 
 export interface FlowScriptResult {
   readonly ok: boolean
@@ -224,7 +224,7 @@ const recognizePatch = (repo: InMemRepo, script: string): FlowScriptResult | und
 
 type PreambleOutcome = { readonly exit: boolean; readonly output: string }
 
-/** One preamble line — the closed vocabulary the bundled workflows write there. */
+/** One preamble line — the closed vocabulary workflows write there. */
 const runPreambleLine = (repo: InMemRepo, line: string): PreambleOutcome => {
   const quoted = words(line)
   if (line === "exit 0") return { exit: true, output: "" }
@@ -299,16 +299,17 @@ const parseCheck = (script: string): ParsedCheck | undefined => {
 
 const runCommand = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   command: string,
 ): { readonly status: number; readonly output: string } => {
   const scripted = commands.get(command)
   if (scripted === undefined) {
-    throw new Error(
-      `testkit: cannot run \`${command}\` in memory — script it ("the shell command … exits …")`,
-    )
+    throw new Error(`testkit: no canned command matches \`${command}\` — add one to \`commands\``)
+  }
+  if (scripted.kind === "exit") {
+    scripted.effect?.()
+    return scripted
   }
-  if (scripted.kind === "exit") return scripted
   if (scripted.kind === "missing") return { status: 127, output: `sh: ${command}: not found\n` }
   repo.writeFile(scripted.file, rewritten(repo, scripted))
   return { status: 0, output: "" }
@@ -325,7 +326,7 @@ export const rewritten = (
 
 const recognizeCheck = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
 ): FlowScriptResult | undefined => {
   const parsed = parseCheck(script)
@@ -362,7 +363,7 @@ const recognizeCheck = (
  */
 export const applyFlowScript = (
   repo: InMemRepo,
-  commands: ReadonlyMap<string, ScriptedCommand>,
+  commands: CommandTable,
   script: string,
 ): FlowScriptResult | undefined => {
   if (!script.startsWith(`${SHEBANG}\n`)) return undefined

package/src/twins/InMemRepo.ts

@@ -134,7 +134,10 @@ export class InMemRepo {
     const refHash = this.refs.get(ref)
     if (refHash !== undefined) return refHash
 
-    return this.branches.get(ref) ?? null
+    // git's own short names: `origin/main` for refs/remotes/origin/main, …
+    const short = this.refs.get(`refs/tags/${ref}`) ?? this.refs.get(`refs/remotes/${ref}`)
+    if (short !== undefined) return short
+    return this.branches.get(ref.replace(/^refs\/heads\//, "")) ?? null
   }
 
   lastCommitSubject(ref = "HEAD"): string | null {
@@ -154,6 +157,28 @@ export class InMemRepo {
     return this.currentBranch
   }
 
+  /** `git branch <name> <ref>`. */
+  createBranch(name: string, ref: string): void {
+    if (this.branches.has(name)) throw new Error(`a branch named '${name}' already exists`)
+    const hash = this.resolveRef(ref)
+    if (hash === null) throw new Error(`not a valid object name: '${ref}'`)
+    this.branches.set(name, hash)
+  }
+
+  /** `git checkout <name>`, refusing any uncommitted change rather than carrying it over. */
+  checkoutBranch(name: string): void {
+    const hash = this.branches.get(name)
+    if (hash === undefined) throw new Error(`pathspec '${name}' did not match any branch`)
+    if (this.statusPorcelain().trim() !== "") {
+      throw new Error(`cannot check out '${name}': the working tree has uncommitted changes`)
+    }
+    const tree = this.getCommit(hash)?.files ?? new Map<string, string>()
+    this.head = hash
+    this.currentBranch = name
+    this.worktree = new Map(tree)
+    this.index = new Map(tree)
+  }
+
   /** 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()]

package/src/twins/Layers.ts

@@ -169,7 +169,13 @@ 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: "exit"
+      readonly status: number
+      readonly output: string
+      /** What the command does to the tree before it exits. */
+      readonly effect?: () => void
+    }
   | {
       readonly kind: "rewrite"
       readonly file: string
@@ -180,6 +186,11 @@ export type ScriptedCommand =
   /** Keyed by the binary's name: it is not on `$PATH`. */
   | { readonly kind: "missing" }
 
+/** The scripted commands, by the exact command a script runs; a `Map` is one. */
+export interface CommandTable {
+  get(command: string): ScriptedCommand | undefined
+}
+
 export interface TestWorldOptions {
   readonly env?: Readonly<Record<string, string | undefined>>
   readonly root?: string

package/src/twins/index.ts

@@ -1,5 +1,10 @@
 export { InMemRepo } from "./InMemRepo.js"
-export { makeInMemoryWorkspaceOps, testLayers, type ScriptedCommand } from "./Layers.js"
+export {
+  makeInMemoryWorkspaceOps,
+  testLayers,
+  type CommandTable,
+  type ScriptedCommand,
+} from "./Layers.js"
 export { makeCapturingCliIo, type CapturedCliResult } from "./cliIo.js"
 export { applyEmittedScript } from "./EmittedScriptRecognizer.js"
 export { applyFlowScript } from "./FlowScripts.js"

package/src/workflow/index.ts

@@ -15,6 +15,7 @@ export {
 export { formatDiagnostic } from "./Diagnostic.js"
 export {
   resolveVars,
+  ownFlagRefusal,
   resolveStartVars,
   StartFlags,
   multilineSetting,