@pmelab/gtd 59.0.0 → 60.0.0

package/src/testkit/index.test.ts

@@ -0,0 +1,28 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { agent, read } from "../flows/index.js"
+import { installContext, type FlowContext, type StepRequest } from "./index.js"
+
+afterEach(() => installContext(undefined))
+
+describe("the flow-context harness", () => {
+  it("renders a prompt and records a step against an installed context", async () => {
+    const requests: StepRequest[] = []
+    installContext({
+      read: (path: string) => (path === "PLAN.md" ? "add a button" : undefined),
+      step: async (request: StepRequest) => {
+        requests.push(request)
+      },
+    } as Partial<FlowContext> as FlowContext)
+
+    await agent("build", `Build: ${read("PLAN.md")}`)
+
+    expect(requests).toEqual([
+      { kind: "agent", name: "build", prompt: "Build: add a button", options: {} },
+    ])
+  })
+
+  it("leaves a flow failing outside a replay once uninstalled", () => {
+    installContext(undefined)
+    expect(() => read("PLAN.md")).toThrow("called outside a gtd replay")
+  })
+})

package/src/testkit/index.ts

@@ -2,15 +2,27 @@
 // repository. It imports no test runner, so any runner can use it; the
 // gherkin steps are the opt-in \`@pmelab/gtd/testkit/gherkin\`.
 export {
+  inTurn,
   runsItsScript,
   testRepo,
-  type Actor,
+  verdict,
+  verdictWhen,
+  whenPrompted,
   type Actors,
   type CannedCommand,
   type DriveOptions,
+  type RunScriptOptions,
+  type ScriptedActor,
+  type TestCommit,
   type TestRepo,
   type TestRepoOptions,
+  type Verdict,
+  type VerdictEntry,
   type WorkflowModule,
 } from "./TestRepo.js"
-export { InMemRepo, type CapturedCliResult } from "../twins/index.js"
+export type { BeatDocument } from "../wire/index.js"
+export type { CapturedCliResult } from "../twins/index.js"
 export type { TestkitWorld } from "../gherkin/index.js"
+// The flow-context harness: render a prompt or stub a step synchronously,
+// against a replay context the test installs instead of the engine.
+export { installContext, type FlowContext, type StepRequest } from "../flows/internal.js"

package/src/twins/EmittedScriptRecognizer.ts

@@ -16,7 +16,6 @@ import {
   softResetTo,
   updateRef,
   binaryGuard,
-  DID_NOT_RUN_COMMENT,
   failurePromptWrapper,
   fileExistsGuard,
   PRESENTATION_FAILURE_WARNING,
@@ -31,7 +30,7 @@ import {
   formatFinding,
   steeringFormatFor,
   type SteeringFormat,
-} from "../steering/index.js"
+} from "../steering/internal.js"
 import { refNameFault } from "../replay/index.js"
 import { renderFormat } from "../wire/index.js"
 import { applyFlowScript, rewritten } from "./FlowScripts.js"
@@ -519,12 +518,8 @@ const recognizeGtdCheck = (repo: InMemRepo, block: string): BlockOutcome | undef
     const known = BUILT_IN_MODE_NAMES.join(", ")
     return { kind: "failed", error: `gtd check: unknown mode "${mode}" — known modes: ${known}` }
   }
-  // An ABSENT file has nothing to check and exits 0 — `runCheckCommand`'s own
-  // documented behavior. Validating `""` instead would report every "missing
-  // header" finding the format has, turning "the reviewer deleted the file"
-  // (a case the review-doc guard owns) into a script failure.
   const content = repo.readFile(file)
-  if (content === undefined) return { kind: "noop" }
+  if (content === undefined) return { kind: "failed", error: `gtd check: no such file: ${file}` }
   const findings = format.validate(content).map((finding) => formatFinding(file, finding))
   if (findings.length === 0) return { kind: "noop" }
   return {
@@ -552,13 +547,11 @@ const recognizeGtdUncheck = (repo: InMemRepo, block: string): BlockOutcome | und
 }
 
 /**
- * `Emit.ts`'s `combinedScript` leading comment — `gtd land`/`gtd --workflow`'s
- * whole plain-text artifact opens with this line ahead of the required
- * script, so recognizing it as a no-op (like the retry-helper function
- * definition) keeps the `@inmem` tier green.
+ * A block of nothing but comments is a no-op in `sh` too — `combinedScript`'s
+ * leading `DID_NOT_RUN_COMMENT`, and the list of paths a start commits.
  */
-const recognizeDidNotRunComment = (block: string): BlockOutcome | undefined =>
-  block === DID_NOT_RUN_COMMENT ? { kind: "noop" } : undefined
+const recognizeCommentBlock = (block: string): BlockOutcome | undefined =>
+  block.split("\n").every((line) => line.startsWith("#")) ? { kind: "noop" } : undefined
 
 /** `combinedScript`'s optional half. Reports `noop` whatever the inner result, mirroring bash's `( … ) || <warning>`. Exception: under `git: false` any unrecognized inner block fails the outer script (git or not), so the in-memory twin knowingly diverges from `sh` rather than run git unseen. */
 const PRESENTATION_FAILURE_TEXT = `${extractQuotedTokens(PRESENTATION_FAILURE_WARNING)[0]!.replace(/\\n$/, "")}\n`
@@ -695,7 +688,7 @@ const recognizersFor = (
   git: boolean,
 ): ReadonlyArray<(block: string) => BlockOutcome | undefined> => [
   (block) => recognizeSetFlags(block),
-  (block) => recognizeDidNotRunComment(block),
+  (block) => recognizeCommentBlock(block),
   (block) => recognizePrecondition(repo, block),
   (block) => recognizeFileExistsGuard(repo, block),
   (block) => recognizeBinaryGuard(commands, block),

package/src/twins/EmittedScripts.test.ts

@@ -140,8 +140,10 @@ for (const makeTier of gitTiers) {
     })
 
     describe("gtd check", () => {
-      it("passes a valid file, and an absent one", () => {
-        expect(run(script(`gtd check qa '${FILE}'`)).ok).toBe(true)
+      it("refuses an absent file, and passes a valid one", () => {
+        const absent = run(script(`gtd check qa '${FILE}'`))
+        expect(absent).toMatchObject({ ok: false, status: 1 })
+        expect(absent.output).toContain(`gtd check: no such file: ${FILE}`)
         t.seed.writeFile(FILE, "## Open Questions\n")
         expect(run(script(`gtd check qa '${FILE}'`))).toEqual({ ok: true, status: 0, output: "" })
       })

package/src/twins/InMemRepo.ts

@@ -30,6 +30,7 @@ function makeHash(message: string, parent: string | null, tree: Map<string, stri
 export class InMemRepo {
   // Data-only marker read by no code path: embeds the sentinel in every
   // instance so a leaked object still carries it.
+  // fallow-ignore-next-line unused-class-member
   readonly testDouble = TEST_DOUBLE_SENTINEL
 
   private commits: Map<string, Commit> = new Map()

package/src/wire/Land.ts

@@ -71,5 +71,5 @@ export const landProseText = (subject: string): string => renderFormat(FMT_LAND_
  */
 export const renderLandPlain = (fields: LandFields, command = "land"): string =>
   fields.subject !== null
-    ? `${landProseText(fields.subject).trimEnd()}\n(run \`gtd ${command} --json=script | sh\` to get the landing script)\n`
+    ? `${landProseText(fields.subject).trimEnd()}\n(to land it: s=$(gtd ${command} --json=script) && sh -c "$s")\n`
     : noopText(fields.state)

package/src/wire/Script.ts

@@ -0,0 +1,11 @@
+import { WIRE_SCHEMA } from "./constants.js"
+
+/** `--json` of every command that prints a script and nothing else to decide on: abandon, restore, start, door, validate, history fetch. */
+export interface ScriptFields {
+  readonly schema: number
+  readonly script: string
+}
+
+export const scriptFields = (script: string): ScriptFields => ({ schema: WIRE_SCHEMA, script })
+
+export const renderScriptJson = (fields: ScriptFields): string => JSON.stringify(fields) + "\n"

package/src/wire/WireSchema.test.ts

@@ -9,6 +9,8 @@ import {
   landFields,
   renderBeatJson,
   renderLandJson,
+  renderScriptJson,
+  scriptFields,
   statusOf,
   WIRE_SCHEMA,
   type BeatKind,
@@ -116,6 +118,7 @@ const documents: Readonly<Record<string, string>> = {
     }),
   ),
   "judge.json": JUDGE,
+  "script.json": renderScriptJson(scriptFields("git reset --mixed ...\n")),
 }
 
 describe(`wire schema ${WIRE_SCHEMA}`, () => {

package/src/wire/golden/1/script.json

@@ -0,0 +1,4 @@
+{
+  "schema": 1,
+  "script": "git reset --mixed ...\n"
+}

package/src/wire/index.ts

@@ -6,6 +6,7 @@ export * from "./BeatStatus.js"
 export * from "./BeatDocument.js"
 export * from "./BeatPlain.js"
 export * from "./Land.js"
+export * from "./Script.js"
 export * from "./Judge.js"
 export { selectPath } from "./Select.js"
 export { resolveSession } from "./Sessions.js"

package/src/workflow/SteeringFormats.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest"
 import fc from "fast-check"
 import { isSeededValidateCommand, seededValidateCommand } from "./SteeringFormats.js"
-import { BUILT_IN_MODE_NAMES } from "../steering/index.js"
+import { BUILT_IN_MODE_NAMES } from "../steering/internal.js"
 
 describe("seededValidateCommand / isSeededValidateCommand", () => {
   it("recognizes its own seeded command for every built-in mode", () => {

package/src/workflow/compile.ts

@@ -1,7 +1,7 @@
 import { seededValidateCommand } from "./SteeringFormats.js"
-import { BUILT_IN_MODE_NAMES } from "../steering/index.js"
+import { BUILT_IN_MODE_NAMES } from "../steering/internal.js"
 import type { ModeDef } from "./Workflow.js"
-import { configProblems, type GtdConfig, type UiSettings } from "../flows/index.js"
+import { configProblems, type GtdConfig, type UiSettings } from "../flows/internal.js"
 import type { Diagnostic } from "./Diagnostic.js"
 
 export interface CompiledConfig {

package/src/workflow/discovery.test.ts

@@ -22,15 +22,15 @@ interface Tier {
 
 const config = (imports: string): string =>
   [
-    'import { agent, human } from "@pmelab/gtd/flows"',
+    'import { agent, human, workflow } from "@pmelab/gtd/flows"',
     imports,
     "export default async () => {",
     '  await human("idle", { message: "go" })',
     '  await agent("working", brief)',
     "}",
-    "export const named = async () => {",
+    "export const named = workflow(async () => {",
     '  await agent("working", brief)',
-    "}",
+    "})",
     "",
   ].join("\n")