@pmelab/gtd 59.0.0 → 60.0.0

package/src/step/planStart.test.ts

@@ -3,25 +3,28 @@ import { describe, expect, it } from "vitest"
 import { planStart, type StartOutcome } from "./planStart.js"
 import { InMemRepo, testLayers } from "../twins/index.js"
 import { ConfigService } from "../workflow/index.js"
+import { GtdUsageError } from "../platform/index.js"
 
-const WORKFLOW = `import { agent, human } from "@pmelab/gtd/flows"
+const WORKFLOW = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
 export default async () => {
   await human("idle", { message: "hi" })
   await agent("work", "work-prompt")
 }
 
-export const working = async () => {
-  await agent("work", "work-prompt")
-}
-
-export const reviewcheck = async () => {
-  await agent("work", "work-prompt")
-}
-
-export const defaults = { base: "" }
+export const working = workflow(
+  async () => {
+    await agent("work", "work-prompt")
+  },
+  { defaults: { base: "" } },
+)
 
-export const base = (workflow, vars) => (workflow === "reviewcheck" ? (vars.base ?? "") : undefined)
+export const reviewcheck = workflow(
+  async () => {
+    await agent("work", "work-prompt")
+  },
+  { defaults: { base: "" }, base: (_workflow, vars) => vars.base ?? "" },
+)
 `
 
 const repoAt = (): InMemRepo => {
@@ -85,15 +88,14 @@ describe("planStart", () => {
     })
   })
 
-  it("refuses an undeclared --var name", async () => {
+  it("fails an undeclared --var name as a usage error", async () => {
     const repo = repoAt()
-    const plan = await start(repo, "idle", "human", {
+    const failure = await start(repo, "idle", "human", {
       workflow: "working",
       commandLabel: "gtd test",
       vars: { nope: "x" },
-    })
-    expect(plan.kind).toBe("refusal")
-    expect(plan.kind === "refusal" && plan.message).toContain("not declared by this workflow")
+    }).catch((e: unknown) => e)
+    expect(String(failure)).toContain(`${GtdUsageError.name}: gtd test: --var name(s) not declared`)
   })
 
   describe("a workflow's diff base", () => {

package/src/step/planStart.ts

@@ -40,7 +40,7 @@ const checkOverrides = (
   varOverrides: Record<string, string>,
   declaredNames: readonly string[],
   envNames: readonly string[],
-): Effect.Effect<StartOutcome | undefined, Error> =>
+): Effect.Effect<void, GtdUsageError> =>
   Effect.gen(function* () {
     const environmentOnly = Object.keys(varOverrides).filter(
       (n) => !declaredNames.includes(n) && envNames.includes(n),
@@ -56,17 +56,18 @@ const checkOverrides = (
     }
     const undeclared = Object.keys(varOverrides).filter((n) => !declaredNames.includes(n))
     if (undeclared.length > 0) {
-      return refusal(
-        `${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(
-          ", ",
-        )} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`,
+      return yield* Effect.fail(
+        new GtdUsageError(
+          `${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(
+            ", ",
+          )} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`,
+        ),
       )
     }
-    return undefined
   })
 
 /**
- * `gtd --workflow <name>`: start a brand NEW process on a workflow, writing an
+ * `gtd start <name>`: start a brand NEW process on a workflow, writing an
  * opening commit that names the workflow's first step and carries a
  * `Gtd-Workflow:` trailer, every process setting as a `Gtd-Var:` trailer, plus
  * a `Gtd-Review-Base:` trailer when the workflow fixes the process's diff base,
@@ -102,13 +103,12 @@ export const planStart = (
     if ("refusal" in first) return refusal(`${commandLabel}: ${first.refusal}`)
     const { firstStep } = first
 
-    const overrideRefusal = yield* checkOverrides(
+    yield* checkOverrides(
       commandLabel,
       varOverrides,
       Object.keys(workflow.vars),
       Object.keys(workflow.env),
     )
-    if (overrideRefusal !== undefined) return overrideRefusal
 
     const baseOf = workflow.def.base
     const flags = yield* StartFlags

package/src/testkit/TestRepo.test.ts

@@ -15,14 +15,27 @@ import {
 import {
   agent,
   check,
+  envSettings as env,
   human,
+  judge,
   moveScript,
   read,
   removeScript,
   run,
   showScript,
+  settings as vars,
+  workflow,
 } from "../flows/index.js"
-import { runsItsScript, testRepo } from "./TestRepo.js"
+import {
+  inTurn,
+  runsItsScript,
+  testRepo,
+  verdict,
+  verdictWhen,
+  whenPrompted,
+  type ScriptedActor,
+  type TestRepo,
+} from "./TestRepo.js"
 
 const tiny = async (): Promise<void> => {
   await agent("plan", "Write PLAN.md.")
@@ -57,8 +70,8 @@ describe("testRepo", () => {
   it("runs a workflow given as gtd.config.ts source", async () => {
     const repo = testRepo({
       workflow: [
-        `import { agent, human } from "@pmelab/gtd/flows"`,
-        `export const chores = async () => { await agent("sweep", "Sweep."); await human("done") }`,
+        `import { agent, human, workflow } from "@pmelab/gtd/flows"`,
+        `export const chores = workflow(async () => { await agent("sweep", "Sweep."); await human("done") })`,
         `export default chores`,
       ].join("\n"),
     })
@@ -75,7 +88,7 @@ describe("testRepo", () => {
       await human("done")
     }
     const repo = testRepo({
-      workflow: { default: tidy, tidy },
+      workflow: { default: tidy, tidy: workflow(tidy) },
       files: { "NOTES.md": "notes\n", "scratch.txt": "x\n" },
     })
     await repo.start("tidy")
@@ -201,12 +214,56 @@ describe("testRepo", () => {
     let n = 0
     await expect(
       repo.drive({ spin: (_, r) => r.write("n", `${++n}\n`) }, { maxBeats: 5 }),
-    ).rejects.toThrow(/did not rest within 5 beats/)
+    ).rejects.toThrow(
+      "did not rest within 5 beats; it passed through:\nspin → spin → spin → spin → spin",
+    )
+  })
+
+  describe("judge verdicts", () => {
+    const judged = async (): Promise<void> => {
+      await agent("plan", "Plan.")
+      const { answers } = await judge("ready", {
+        questions: [{ id: "ready", primitive: "noul", instructions: "Ready?", criteria: "" }],
+        evidence: { plan: "p" },
+      })
+      await human(answers.ready?.answer === "yes" ? "ship" : "rework")
+    }
+    const plan: ScriptedActor = (_, r) => r.write("PLAN.md", "p\n")
+    const template =
+      'expected a JSON array, one entry per question — answer a boolean for a noul, a string for a choice, a number for a score; p between 0 and 1:\n[{ "id": "ready", "answer": true, "p": 0.9 }]'
+
+    it("echoes a refused verdict and the shape it should have", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      const error = await repo
+        .drive({ plan, ready: () => '{"ready": true}' })
+        .catch((e: Error) => e)
+      expect((error as Error).message).toContain(
+        `the actor for judge step "ready" sent a verdict gtd refused:\n{"ready": true}\n${template}\ngtd judge answer exited 2\n`,
+      )
+    })
+
+    it("says an actor returned an object rather than no verdict", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      const actor = (() => [{ id: "ready", answer: true, p: 0.9 }]) as unknown as ScriptedActor
+      await expect(repo.drive({ plan, ready: actor })).rejects.toThrow(
+        `the actor for judge step "ready" returned an array, not a JSON string — JSON.stringify it\n${template}`,
+      )
+    })
+
+    it("says an actor returned nothing", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      await expect(repo.drive({ plan, ready: () => undefined })).rejects.toThrow(
+        `the actor for judge step "ready" returned no verdict\n${template}`,
+      )
+    })
   })
 
   describe("canned commands", () => {
     const checked = async (): Promise<void> => {
-      const green = await check("test", "npm test", { report: ".gtd/FEEDBACK.md" })
+      const green = await check("test", "npm test", ".gtd/FEEDBACK.md")
       await human(green ? "sign-off" : "red")
     }
 
@@ -310,4 +367,230 @@ describe("testRepo", () => {
       expect(() => repo.ref("refs/tags/v1", "nowhere")).toThrow("resolves to no commit")
     })
   })
+
+  describe("modules a config imports", () => {
+    it("serves a specifier the config's source imports, read off the module the test imported", async () => {
+      const shipped = { tiny, chores: tiny }
+      const repo = testRepo({
+        workflow: [
+          `import { workflow } from "@pmelab/gtd/flows"`,
+          `import tidy, * as all from "#workflow"`,
+          `export { chores } from "#workflow"`,
+          `export const both = all.tiny === tidy ? workflow(() => tidy()) : undefined`,
+          `export default tidy`,
+        ].join("\n"),
+        modules: { "#workflow": { ...shipped, default: tiny } },
+      })
+      await repo.start("both")
+      expect((await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })).state).toBe("build")
+      expect(repo.read("gtd.config.ts")).not.toContain('from "#workflow"')
+    })
+  })
+
+  describe("strict drives", () => {
+    const signOff = async (): Promise<void> => {
+      await agent("plan", "Plan.")
+      await human("sign-off")
+      await agent("ship", "Ship.")
+    }
+    const plan: ScriptedActor = (_, r) => r.write("PLAN.md", "p\n")
+
+    it("fails on an actor whose step the drive never reached", async () => {
+      const repo = testRepo({ workflow: { default: signOff } })
+      repo.write("go", "\n")
+      await expect(repo.drive({ plan, ship: () => undefined })).rejects.toThrow(
+        'strict drive: the process rests at "sign-off", and never reached the actors for "ship"',
+      )
+    })
+
+    it("leaves only the unreached-actor check out with unreachedActors: pass", async () => {
+      const repo = testRepo({ workflow: { default: signOff } })
+      repo.write("go", "\n")
+      expect(
+        (await repo.drive({ plan, ship: () => undefined }, { unreachedActors: "pass" })).state,
+      ).toBe("sign-off")
+    })
+
+    it("lets the same drive rest when it is not strict", async () => {
+      const repo = testRepo({ workflow: { default: signOff } })
+      repo.write("go", "\n")
+      expect((await repo.drive({ plan, ship: () => undefined }, { strict: false })).state).toBe(
+        "sign-off",
+      )
+    })
+
+    it("counts a step an earlier drive reached as reached", async () => {
+      const twice = async (): Promise<void> => {
+        await signOff()
+        await human("done")
+      }
+      const repo = testRepo({ workflow: { default: twice } })
+      repo.write("go", "\n")
+      const actors: Record<string, ScriptedActor> = { plan }
+      expect((await repo.drive(actors)).state).toBe("sign-off")
+      repo.write("signed", "\n")
+      await repo.land()
+      actors["ship"] = (_, r) => r.write("shipped", "\n")
+      expect((await repo.drive(actors)).state).toBe("done")
+    })
+
+    it("fails on a human step whose actor changes nothing, instead of repeating it", async () => {
+      const repo = testRepo({ workflow: { default: signOff } })
+      repo.write("go", "\n")
+      await expect(repo.drive({ plan, "sign-off": () => undefined })).rejects.toThrow(
+        'strict drive: the actor for human step "sign-off" changed nothing, so nothing landed',
+      )
+    })
+
+    it("fails on a verdict returned at a step that is no judge", async () => {
+      const repo = testRepo({ workflow: { default: signOff } })
+      repo.write("go", "\n")
+      await expect(repo.drive({ plan: (beat, r) => (plan(beat, r), "[]") })).rejects.toThrow(
+        'the actor for agent step "plan" returned a verdict',
+      )
+    })
+
+    it("fails on a check step without an actor, unless checks run themselves", async () => {
+      const checked = async (): Promise<void> => {
+        const green = await check("test", "npm test", ".gtd/FEEDBACK.md")
+        await human(green ? "sign-off" : "red")
+      }
+      const strictRepo = testRepo({ workflow: { default: checked } })
+      strictRepo.write("go", "\n")
+      await expect(strictRepo.drive({})).rejects.toThrow(
+        'strict drive: check step "test" has no actor',
+      )
+      const repo = testRepo({
+        workflow: { default: checked },
+        commands: [{ run: "npm test", exit: 1, output: "1 failing" }],
+      })
+      repo.write("go", "\n")
+      expect((await repo.drive({}, { checks: "run" })).state).toBe("red")
+      expect(repo.read(".gtd/FEEDBACK.md")).toContain("1 failing")
+    })
+  })
+
+  describe("actor helpers", () => {
+    const judged = async (): Promise<void> => {
+      await agent("plan", "Plan.")
+      const { answers } = await judge("ready", {
+        questions: [{ id: "ready", primitive: "noul", instructions: "Ready?", criteria: "" }],
+        evidence: { plan: "p" },
+      })
+      await human(answers.ready?.answer === "yes" ? "ship" : "rework")
+    }
+    const plan: ScriptedActor = (_, r) => r.write("PLAN.md", "p\n")
+
+    it("builds a verdict keyed by question id, p defaulting to 0.9", () => {
+      expect(verdict({ ready: true, tier: { answer: "low", p: 0.6 } })).toEqual({
+        answers: [
+          { id: "ready", answer: true, p: 0.9 },
+          { id: "tier", answer: "low", p: 0.6 },
+        ],
+      })
+    })
+
+    it("answers a judge with a verdict object", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      expect((await repo.drive({ plan, ready: () => verdict({ ready: false }) })).state).toBe(
+        "rework",
+      )
+    })
+
+    it("answers by what the pending questions contain", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      const ready = inTurn([
+        verdictWhen("Unrelated?", verdict({ ready: false })),
+        verdictWhen("Ready?", verdict({ ready: true })),
+      ])
+      expect((await repo.drive({ plan, ready })).state).toBe("ship")
+    })
+
+    it("runs an actor only at a visit prompted with the text, and every actor in turn", async () => {
+      const repo = testRepo({ workflow: { default: judged } })
+      repo.write("go", "\n")
+      const seen: string[] = []
+      await repo.drive({
+        plan: inTurn([
+          whenPrompted("Plan.", plan),
+          whenPrompted("Something else.", () => {
+            seen.push("else")
+          }),
+          () => {
+            seen.push("always")
+          },
+        ]),
+      })
+      expect(repo.read("PLAN.md")).toBe("p\n")
+      expect(seen).toEqual(["always"])
+    })
+
+    it("runs a script with commands of its own before the canned ones", () => {
+      const repo = testRepo({ workflow: { default: tiny }, commands: [{ run: /.*/, exit: 1 }] })
+      repo.runScript("make docs\n", {
+        commands: [{ run: "make docs", effect: (r) => r.write("docs.html", "<p>\n") }],
+      })
+      expect(repo.read("docs.html")).toBe("<p>\n")
+    })
+  })
+
+  describe("commits and the environment", () => {
+    it("lists every commit with its subject, message and trailers", async () => {
+      const repo = testRepo({ workflow: { default: tiny } })
+      repo.write("IDEA.md", "x\n")
+      repo.commit("feat: x\n\nA body.\n\nRefs: #1\nRefs: #2")
+      const [initial, feat] = repo.commits()
+      expect(initial).toMatchObject({ subject: "chore: initial commit", trailers: {} })
+      expect(feat).toEqual({
+        hash: repo.hashes()[1],
+        subject: "feat: x",
+        message: repo.messages()[1],
+        trailers: { Refs: ["#1", "#2"] },
+      })
+      await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
+      expect(repo.commits().at(-1)!.trailers["Gtd-Step"]).toEqual(["plan#1"])
+    })
+
+    const greeter = {
+      default: workflow(
+        async (): Promise<void> => {
+          await agent("wake", "Wake up.")
+          await agent("greet", `Say ${env["greeting"]}, flag ${vars["flag_probe"]}.`)
+        },
+        { envDefaults: { greeting: "hi" }, defaults: { flag_probe: "0" } },
+      ),
+    }
+    const greet = async (repo: TestRepo): Promise<string> => {
+      const rest = await repo.drive({ wake: (_, r) => r.write("awake", "\n") })
+      return rest.content
+    }
+
+    it("changes a variable gtd sees from the next call on", async () => {
+      const repo = testRepo({ workflow: greeter })
+      repo.write("go", "\n")
+      expect(await greet(repo)).toContain("Say hi")
+      repo.setEnv("GTD_GREETING", "hello")
+      expect((await repo.next()).content).toContain("Say hello")
+      repo.setEnv("GTD_GREETING", undefined)
+      expect((await repo.next()).content).toContain("Say hi")
+    })
+
+    it("keeps the runner's GTD_FLAG_* out when ambient flags are off", async () => {
+      const saved = process.env["GTD_FLAG_PROBE"]
+      process.env["GTD_FLAG_PROBE"] = "1"
+      try {
+        const ambient = testRepo({ workflow: greeter })
+        ambient.write("go", "\n")
+        expect(await greet(ambient)).toContain("flag 1")
+        const isolated = testRepo({ workflow: greeter, ambientFlags: false })
+        isolated.write("go", "\n")
+        expect(await greet(isolated)).toContain("flag 0")
+      } finally {
+        if (saved === undefined) delete process.env["GTD_FLAG_PROBE"]
+        else process.env["GTD_FLAG_PROBE"] = saved
+      }
+    })
+  })
 })