@pmelab/gtd 59.0.0 → 60.0.0

package/src/gherkin/messages.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest"
+import { agent, human, workflow } from "../flows/index.js"
+import { testRepo } from "../testkit/index.js"
+import {
+  assertContains,
+  assertLacks,
+  assertRestsAt,
+  refusedWith,
+  restDescription,
+} from "./messages.js"
+
+const flow = async (): Promise<void> => {
+  await agent("plan", "Write PLAN.md.\nKeep it short.\n3\n4\n5\n6\n7")
+  await human("sign-off")
+}
+
+const thrown = async (fn: () => unknown): Promise<string> => {
+  try {
+    await fn()
+  } catch (error) {
+    return (error as Error).message
+  }
+  throw new Error("did not throw")
+}
+
+describe("restDescription", () => {
+  it("names the step, its kind and actor, the content's head, the last commits and the unused actors", async () => {
+    const repo = testRepo({ workflow: { default: flow } })
+    repo.write("go", "\n")
+    await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
+    expect(
+      await restDescription(
+        () => repo,
+        [
+          { step: "repair", origin: "scenario" },
+          { step: "ready", origin: "Background" },
+        ],
+      ),
+    ).toBe(
+      [
+        "where the process rests:",
+        '  step "sign-off" (message, human)',
+        "  content:",
+        "    | sign-off",
+        "  last commits:",
+        "    chore: initial commit",
+        "    gtd(agent): plan → sign-off",
+        '  actors never used: "repair" (scenario), "ready" (Background)',
+      ].join("\n"),
+    )
+  })
+
+  it("cuts long content to its first lines", async () => {
+    const repo = testRepo({ workflow: { default: flow } })
+    repo.write("go", "\n")
+    const description = await restDescription(() => repo, [])
+    expect(description).toContain('step "plan" (prompt, agent)')
+    expect(description).toContain("    | 5\n    | … 2 more lines")
+    expect(description).not.toContain("actors never used")
+  })
+
+  it("says why the rest is unknown instead of throwing", async () => {
+    const description = await restDescription(() => {
+      throw new Error("no gtd config")
+    }, [])
+    expect(description).toBe("where the process rests:\n  unknown — no gtd config")
+  })
+})
+
+describe("refusedWith", () => {
+  it("says nothing was refused when the attempt succeeds", async () => {
+    expect(await thrown(() => refusedWith(Promise.resolve(), "nope"))).toBe(
+      'expected a refusal with "nope", but nothing was refused',
+    )
+  })
+
+  it("prints the refusal it got when the text is missing", async () => {
+    expect(await thrown(() => refusedWith(Promise.reject(new Error("other")), "nope"))).toBe(
+      'expected a refusal with "nope", but it was refused with:\nother',
+    )
+  })
+
+  it("passes on a refusal carrying the text", async () => {
+    await refusedWith(Promise.reject(new Error("a nope b")), "nope")
+  })
+})
+
+describe("contains", () => {
+  it("prints the text looked for and what was there", async () => {
+    expect(await thrown(() => assertContains('"a.md"', "x", "y\n"))).toBe(
+      '"a.md" does not contain "x"; it holds:\ny\n',
+    )
+    expect(await thrown(() => assertLacks('"a.md"', "y", "y\n"))).toBe(
+      '"a.md" contains "y"; it holds:\ny\n',
+    )
+  })
+
+  it("says a missing file does not exist", async () => {
+    expect(await thrown(() => assertContains('"a.md"', "x", undefined))).toBe(
+      '"a.md" does not exist, so it cannot contain "x"',
+    )
+    expect(await thrown(() => assertLacks('"a.md"', "x", undefined))).toBe('"a.md" does not exist')
+  })
+})
+
+describe("assertRestsAt", () => {
+  it("fails on a stall at the step, pointing to the stall assertion", async () => {
+    const repo = testRepo({ workflow: { default: flow, flow: workflow(flow) } })
+    await repo.start("flow")
+    const stall = await repo.drive({ plan: () => undefined })
+    expect(stall.kind).toBe("stalled")
+    expect(await thrown(() => assertRestsAt(stall, "plan"))).toBe(
+      'expected a rest at "plan", but the process stalls at "plan" — assert a stall with: the process stalls at "plan"',
+    )
+  })
+
+  it("passes at a rest at the step, and fails at another", async () => {
+    const repo = testRepo({ workflow: { default: flow } })
+    repo.write("go", "\n")
+    const rest = await repo.drive({ plan: (_, r) => r.write("PLAN.md", "p\n") })
+    assertRestsAt(rest, "sign-off")
+    expect(await thrown(() => assertRestsAt(rest, "plan"))).toContain("sign-off")
+  })
+})

package/src/gherkin/messages.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert"
+import type { BeatDocument, TestRepo } from "../testkit/index.js"
+
+const CONTENT_LINES = 5
+const SUBJECTS = 5
+
+const reason = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+const beatLines = async (repo: TestRepo): Promise<string[]> => {
+  try {
+    const beat = await repo.next()
+    const content = beat.content.trimEnd().split("\n")
+    const more = content.length - CONTENT_LINES
+    return [
+      `step "${beat.state}" (${beat.kind}, ${beat.actor}${beat.idle ? ", idle" : ""})`,
+      "content:",
+      ...content.slice(0, CONTENT_LINES).map((line) => `  | ${line}`),
+      ...(more > 0 ? [`  | … ${more} more lines`] : []),
+    ]
+  } catch (error) {
+    return [`unknown — gtd next failed: ${reason(error)}`]
+  }
+}
+
+/** A scripted step no drive reached, and whether a Background or the scenario scripted it. */
+export interface Unreached {
+  readonly step: string
+  readonly origin: "Background" | "scenario"
+}
+
+export const unreachedList = (steps: readonly Unreached[]): string =>
+  steps.map(({ step, origin }) => `"${step}" (${origin})`).join(", ")
+
+/** Where the process rests, for a failed outcome to end with. Never throws: it describes a failure. */
+export const restDescription = async (
+  repo: () => TestRepo,
+  neverUsed: readonly Unreached[],
+): Promise<string> => {
+  let lines: string[]
+  try {
+    const r = repo()
+    lines = [
+      ...(await beatLines(r)),
+      "last commits:",
+      ...r
+        .subjects()
+        .slice(-SUBJECTS)
+        .map((subject) => `  ${subject}`),
+    ]
+  } catch (error) {
+    lines = [`unknown — ${reason(error)}`]
+  }
+  if (neverUsed.length > 0) lines.push(`actors never used: ${unreachedList(neverUsed)}`)
+  return ["where the process rests:", ...lines.map((line) => `  ${line}`)].join("\n")
+}
+
+/** Both sides of a failed `contains`: the text looked for, and what was there. */
+const containsFailure = (
+  where: string,
+  text: string,
+  content: string | undefined,
+  expected: boolean,
+): string =>
+  content === undefined
+    ? `${where} does not exist${expected ? `, so it cannot contain "${text}"` : ""}`
+    : `${where} ${expected ? "does not contain" : "contains"} "${text}"; it holds:\n${content}`
+
+/** What `attempt` was refused with; fails when it was not refused at all. */
+export const refusal = async (attempt: Promise<unknown>, expectation: string): Promise<string> => {
+  try {
+    await attempt
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+  assert.fail(`expected a refusal ${expectation}, but nothing was refused`)
+}
+
+export const refusedWith = async (attempt: Promise<unknown>, message: string): Promise<void> => {
+  const got = await refusal(attempt, `with "${message}"`)
+  if (!got.includes(message))
+    assert.fail(`expected a refusal with "${message}", but it was refused with:\n${got}`)
+}
+
+export const assertContains = (where: string, text: string, content: string | undefined): void => {
+  if (content === undefined || !content.includes(text))
+    assert.fail(containsFailure(where, text, content, true))
+}
+
+export const assertLacks = (where: string, text: string, content: string | undefined): void => {
+  if (content === undefined || content.includes(text))
+    assert.fail(containsFailure(where, text, content, false))
+}
+
+/** A rest at `step`; a stall there is no rest, so it points to the step that asserts one. */
+export const assertRestsAt = (beat: BeatDocument, step: string): void => {
+  if (beat.kind === "stalled")
+    assert.fail(
+      `expected a rest at "${step}", but the process stalls at "${beat.state}" — assert a stall with: the process stalls at "${beat.state}"`,
+    )
+  assert.strictEqual(beat.state, step)
+}

package/src/gherkin/more-steps.feature

@@ -0,0 +1,170 @@
+@inmem
+Feature: steps for checks, stalls, beat fields, commit bodies and the environment
+
+  Background:
+    Given a gtd config with:
+      """
+      import { agent, check, envSettings, human, scope, settings, workflow } from "@pmelab/gtd/flows"
+
+      const defaults = { title: "untitled" }
+      const envDefaults = { greeting: "hi" }
+
+      export const tested = workflow(async () => {
+        await scope({ name: "build", skills: ["tdd", "review"] }, async () => {
+          await agent("plan", "Plan.", { model: "smart" })
+        })
+        const green = await check("test", "npm test", ".gtd/FEEDBACK.md")
+        await agent(green ? "ship" : "repair", `Say ${envSettings.greeting} to ${settings.title}.`)
+        await human("done")
+      }, { defaults, envDefaults })
+
+      export default tested
+      """
+
+  Scenario: the resting step's fields are read by name
+    When gtd starts workflow "tested"
+    Then the process rests at "build.plan"
+    And the resting step's model is "smart"
+    And the resting step's idle is "false"
+    And the resting step's skills includes "review"
+    And the resting step's content includes "Plan"
+
+  Scenario: a quoted argument keeps its spaces
+    Given step "build.plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And check step "test" passes
+    When gtd starts workflow "tested" with "--var 'title=a calculator'"
+    And the process is driven
+    Then the resting step's content contains "Say hi to a calculator."
+
+  Scenario: an agent step that changes nothing stalls
+    Given step "build.plan" changes nothing
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process stalls at "build.plan"
+
+  Scenario: a passing check step goes on, and a variable changed mid-process is seen from then on
+    Given step "build.plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And check step "test" passes
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process rests at "ship"
+    And the resting step's content contains "Say hi to untitled."
+    Given from now on the environment variable "GTD_GREETING" is "hello"
+    Then the resting step's content contains "Say hello to untitled."
+
+  Scenario: a failing check step writes its report
+    Given the environment variable "GTD_GREETING" is "hey"
+    And step "build.plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And check step "test" fails with:
+      """
+      1 test failing
+      """
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process rests at "repair"
+    And ".gtd/FEEDBACK.md" contains "1 test failing"
+    And the resting step's content contains "Say hey to untitled."
+
+  Scenario: a check step scripted at a step that is no check refuses the drive
+    Given check step "build.plan" passes
+    When gtd starts workflow "tested"
+    Then driving the process is refused with 'step "build.plan" is no check step; its actor is agent'
+
+  Scenario: commit bodies are read whole, every commit of a subject at once
+    Given the working tree is committed with the message:
+      """
+      chore: seed
+
+      Seeded by hand.
+
+      Refs: #1
+      """
+    And step "build.plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And check step "test" passes
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the last commit body contains "Gtd-Step: test#1"
+    And the commit "gtd(agent): build.plan → test" has a body containing "Gtd-Step: build.plan#1"
+    And the commit "chore: seed" has a body containing "Seeded by hand."
+    And no commit body contains "never written"
+
+  Scenario: a canned command matched by pattern, a branch at a ref, and a file as committed there
+    Given a file "a.txt" with:
+      """
+      one
+      """
+    And the working tree is committed as "chore: one"
+    And a file "a.txt" with:
+      """
+      two
+      """
+    And the working tree is committed as "chore: two"
+    And a branch "old" at "HEAD~1"
+    And the command matching "^npm (test|run)" exits 1 with:
+      """
+      red
+      """
+    And step "build.plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "test" runs its script
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process rests at "repair"
+    And "a.txt" as committed at "old" contains "one"
+    And ".gtd/FEEDBACK.md" contains "red"
+
+  Scenario: text is appended to a file, and a step overwrites one only if it exists
+    Given a file "NOTES.md" with:
+      """
+      first
+      """
+    And text is appended to "NOTES.md":
+      """
+      second
+      """
+    And step "build.plan" overwrites "PLAN.md", if it exists, with:
+      """
+      never written
+      """
+    And step "build.plan" overwrites "NOTES.md", if it exists, with:
+      """
+      rewritten
+      """
+    And step "test" runs its script
+    And the command "npm test" exits 0
+    When gtd starts workflow "tested"
+    And the process is driven
+    Then the process rests at "ship"
+    And "NOTES.md" contains "rewritten"
+    And "PLAN.md" does not exist
+
+  Scenario: a config given as source imports a module the scenario names
+    Given the module "src/gherkin/tiny.fixture.ts" is importable as "#workflow"
+    And a gtd config with:
+      """
+      export { tiny, tiny as default } from "#workflow"
+      """
+    And a file "IDEA.md" with:
+      """
+      a calculator
+      """
+    And step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    When the process is driven
+    Then the process rests at "sign-off"

package/src/gherkin/scenario-end.feature

@@ -0,0 +1,101 @@
+@inmem
+Feature: a scenario's scripted steps must be reached by its end, not by every drive
+
+  Background:
+    Given a gtd config with:
+      """
+      import { agent, human, workflow } from "@pmelab/gtd/flows"
+
+      export const shipping = workflow(async () => {
+        await agent("plan", "Write PLAN.md.")
+        await human("sign-off")
+        await agent("ship", "Ship it.")
+        await human("done")
+      })
+
+      export default shipping
+      """
+    And step "ship" writes "SHIPPED.md" with:
+      """
+      shipped
+      """
+
+  Scenario: an actor the Background scripts, reached only by the second drive, passes
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    When gtd starts workflow "shipping"
+    And the process is driven
+    Then the process rests at "sign-off"
+    Given step "sign-off" writes "SIGNED.md" with:
+      """
+      signed
+      """
+    When the process is driven
+    Then the process rests at "done"
+    And "SHIPPED.md" contains "shipped"
+
+  Scenario: an actor the Background scripts may go unreached in a scenario another scenario reaches it in
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    When gtd starts workflow "shipping"
+    And the process is driven
+    Then the process rests at "sign-off"
+
+  @fails
+  Scenario: an actor the scenario scripts that no drive reaches fails it at its end
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "done" writes "DONE.md" with:
+      """
+      done
+      """
+    When gtd starts workflow "shipping"
+    And the process is driven
+    Then the process rests at "sign-off"
+
+  @fails
+  Scenario: a lenient drive leaves an actor no drive reaches to fail the scenario at its end
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "done" writes "DONE.md" with:
+      """
+      done
+      """
+    When gtd starts workflow "shipping"
+    And the process is driven leniently
+    Then the process rests at "sign-off"
+
+  Scenario: a refused drive excuses the actors it was handed
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "sign-off" changes nothing
+    And step "done" writes "DONE.md" with:
+      """
+      done
+      """
+    When gtd starts workflow "shipping"
+    Then driving the process is refused with 'the actor for human step "sign-off" changed nothing'
+
+  @fails
+  Scenario: an actor scripted after a refused drive, and reached by no later one, fails the scenario
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "sign-off" changes nothing
+    When gtd starts workflow "shipping"
+    Then driving the process is refused with 'the actor for human step "sign-off" changed nothing'
+    Given step "done" writes "DONE.md" with:
+      """
+      done
+      """

package/src/gherkin/testkit.feature

@@ -7,9 +7,9 @@ Feature: testkit drives any workflow against the real engine
   Background:
     Given a gtd config with:
       """
-      import { agent, human, judge, read, refuse, run } from "@pmelab/gtd/flows"
+      import { agent, human, judge, read, refuse, run, workflow } from "@pmelab/gtd/flows"
 
-      export const tiny = async () => {
+      export const tiny = workflow(async () => {
         await agent("plan", "Write PLAN.md.")
         await run("check", "npm test > .gtd/FEEDBACK.md 2>&1 && rm .gtd/FEEDBACK.md")
         if (read(".gtd/FEEDBACK.md") !== undefined) await agent("repair", "Make the suite pass.")
@@ -18,11 +18,11 @@ Feature: testkit drives any workflow against the real engine
           evidence: { plan: read("PLAN.md") ?? "" },
         })
         await human(answers.ready?.answer === "yes" ? "ship" : "rework")
-      }
+      })
 
-      export const picky = async () => {
+      export const picky = workflow(async () => {
         refuse("gtd: picky refuses every start")
-      }
+      })
 
       export default tiny
       """
@@ -83,9 +83,12 @@ Feature: testkit drives any workflow against the real engine
     And "PLAN.md" contains "add two numbers"
 
   Scenario: a judge step with queued actions refuses the drive
-    Given step "plan" changes nothing
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
     And step "check" changes nothing
-    And step "ready" is prompted with "never seen"
+    And step "ready" changes nothing
     And judge step "ready" answers:
       """
       [{ "id": "ready", "answer": true, "p": 0.9 }]
@@ -98,6 +101,79 @@ Feature: testkit drives any workflow against the real engine
     When gtd starts workflow "tiny"
     Then driving the process is refused with 'was not prompted with "Write a poem"'
 
+  Scenario: a step only asserted to be prompted is where the drive rests, and nothing lands there
+    Given step "plan" is prompted with "Write PLAN.md."
+    When gtd starts workflow "tiny"
+    And the process is driven
+    Then the process rests at "plan"
+    And the last commit subject is "gtd(human): plan"
+
+  Scenario: a prompt asserted beside a script is checked at every visit, before the step acts
+    Given step "check" is prompted with "npm test"
+    And step "check" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test failing
+      """
+    And step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    When gtd starts workflow "tiny"
+    And the process is driven
+    Then the process rests at "repair"
+
+  @fails
+  Scenario: a prompt asserted at a step no drive reaches fails the scenario at its end
+    Given step "plan" changes nothing
+    And step "repair" is prompted with "Make the suite pass."
+    When gtd starts workflow "tiny"
+    And the process is driven
+    Then the process stalls at "plan"
+
+  Scenario: a human step scripted to change nothing refuses the drive instead of repeating it
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "check" changes nothing
+    And judge step "ready" answers:
+      """
+      [{ "id": "ready", "answer": true, "p": 0.9 }]
+      """
+    And step "ship" changes nothing
+    When gtd starts workflow "tiny"
+    Then driving the process is refused with 'the actor for human step "ship" changed nothing'
+
+  Scenario: a lenient drive rests at an unscripted check step
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    When gtd starts workflow "tiny"
+    And the process is driven leniently
+    Then the process rests at "check"
+    And the resting step's content contains "npm test"
+
+  Scenario: a step scripted for a later drive counts once any drive reached it
+    Given step "plan" writes "PLAN.md" with:
+      """
+      add two numbers
+      """
+    And step "check" writes ".gtd/FEEDBACK.md" with:
+      """
+      1 test failing
+      """
+    When gtd starts workflow "tiny"
+    And the process is driven
+    Then the process rests at "repair"
+    Given step "repair" deletes ".gtd/FEEDBACK.md"
+    And judge step "ready" answers:
+      """
+      [{ "id": "ready", "answer": false, "p": 0.9 }]
+      """
+    When the process is driven
+    Then the process rests at "rework"
+
   Scenario: a start the workflow refuses is reported with its message
     Then starting workflow "picky" with "--var mode=bad" is refused with "picky refuses every start"
 

package/src/install/Install.test.ts

@@ -164,8 +164,8 @@ describe("renderBriefing", () => {
 
   it("contains the door invocation, exec'ing the loop", () => {
     const briefing = renderBriefing()
-    expect(briefing).toContain('gtd door "$@"')
-    expect(briefing).toContain("gtd doors")
+    expect(briefing).toContain('gtd start "$@"')
+    expect(briefing).toMatch(/bare `gtd start` lists/i)
     expect(briefing).toMatch(/exec.{0,20}GTD_BUILD/s)
   })
 
@@ -418,19 +418,19 @@ describe("DOOR_COMMAND", () => {
 
   it("cds to the repository root before any gtd call", () => {
     const cdIndex = DOOR_COMMAND.indexOf('cd "$(git rev-parse --show-toplevel)"')
-    const gtdIndex = DOOR_COMMAND.indexOf("gtd door")
+    const gtdIndex = DOOR_COMMAND.indexOf("gtd start")
     expect(cdIndex).toBeGreaterThan(-1)
     expect(gtdIndex).toBeGreaterThan(cdIndex)
   })
 
-  it("hands every argument to gtd door", () => {
-    expect(DOOR_COMMAND).toContain('gtd door "$@"')
+  it("hands every argument to gtd start", () => {
+    expect(DOOR_COMMAND).toContain('gtd start "$@"')
   })
 
   it("captures the emitted script via command substitution, never a pipe into sh", () => {
-    expect(DOOR_COMMAND).toContain('script="$(gtd door "$@")"')
+    expect(DOOR_COMMAND).toContain('script="$(gtd start "$@")"')
     expect(DOOR_COMMAND).toContain('sh -c "$script"')
-    expect(DOOR_COMMAND).not.toMatch(/gtd door[^\n]*\|\s*sh/)
+    expect(DOOR_COMMAND).not.toMatch(/gtd start[^\n]*\|\s*sh/)
   })
 
   it("prints usage to stderr and exits 2 when no name is given", () => {