@pmelab/gtd 59.0.1 → 60.1.0

package/src/cli/History.ts

@@ -3,7 +3,13 @@ import { historyTrail } from "../edge/index.js"
 import { combinedScript, fetchHistoryRefs } from "../emit/index.js"
 import { GitService, Narrator, PROCESS_HISTORY_PREFIX } from "../platform/index.js"
 import { parseCommitMessage } from "../replay/index.js"
-import { writeJson, type ArtifactOut, type CommandRequirements, type JsonMode } from "./Output.js"
+import {
+  writeJson,
+  writeScript,
+  type ArtifactOut,
+  type CommandRequirements,
+  type JsonMode,
+} from "./Output.js"
 
 export interface HistoryEntry {
   readonly ref: string
@@ -138,8 +144,7 @@ export const runHistoryShowCommand = (
 /** Prints the script and never runs git: gtd's promise that it only decides and prints. */
 export const runHistoryFetchCommand = (
   remote: string,
+  json: JsonMode,
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> =>
-  Effect.sync(() => {
-    out.write(`${combinedScript(fetchHistoryRefs(remote), "")}\n`)
-  })
+  writeScript(json, out, `${combinedScript(fetchHistoryRefs(remote), "")}\n`)

package/src/cli/Judges.ts

@@ -2,7 +2,7 @@ import { Effect, Option } from "effect"
 import { answered, numeric } from "../flows/index.js"
 import { GitService } from "../platform/index.js"
 import { parseCommitMessage, type JudgeVerdict } from "../replay/index.js"
-import { headingSectionBodies } from "../steering/index.js"
+import { headingSectionBodies } from "../steering/internal.js"
 import { selectHistoryEntries, type HistoryEntry } from "./History.js"
 import { printable } from "./Metrics.js"
 import { writeJson, type ArtifactOut, type CommandRequirements, type JsonMode } from "./Output.js"

package/src/cli/Output.test.ts

@@ -0,0 +1,35 @@
+import { Effect, Exit } from "effect"
+import { describe, expect, it } from "vitest"
+import { WIRE_SCHEMA } from "../wire/index.js"
+import { writeScript, type JsonMode } from "./Output.js"
+
+const run = (json: JsonMode, script: string, plain?: string) => {
+  let written = ""
+  const out = { write: (chunk: string | Uint8Array) => (written += String(chunk)), flush: () => {} }
+  const exit = Effect.runSyncExit(writeScript(json, out, script, plain))
+  return { exit, written }
+}
+
+describe("writeScript", () => {
+  it("plain prints the script, or the plain text when given", () => {
+    expect(run({ kind: "off" }, "git reset\n").written).toBe("git reset\n")
+    expect(run({ kind: "off" }, "", "nothing to do\n").written).toBe("nothing to do\n")
+  })
+
+  it("--json prints { schema, script }, the script ending in exactly one newline", () => {
+    expect(JSON.parse(run({ kind: "document" }, "git reset\n\n").written)).toEqual({
+      schema: WIRE_SCHEMA,
+      script: "git reset\n",
+    })
+    expect(JSON.parse(run({ kind: "document" }, "", "nothing\n").written)).toEqual({
+      schema: WIRE_SCHEMA,
+      script: "",
+    })
+  })
+
+  it("--json=script prints the script alone; an unknown path fails", () => {
+    expect(run({ kind: "select", path: "script" }, "git reset").written).toBe("git reset\n\n")
+    expect(run({ kind: "select", path: "schema" }, "x").written).toBe(`${WIRE_SCHEMA}\n`)
+    expect(Exit.isFailure(run({ kind: "select", path: "nope" }, "x").exit)).toBe(true)
+  })
+})

package/src/cli/Output.ts

@@ -1,7 +1,13 @@
 import { Effect } from "effect"
 import { CommandRunner, GitService, Host, Narrator, Workspace } from "../platform/index.js"
-import { selectPath, type EXIT_OK, type EXIT_STRAYS_FOUND } from "../wire/index.js"
-import { ConfigDiscovery, ConfigService } from "../workflow/index.js"
+import {
+  renderScriptJson,
+  scriptFields,
+  selectPath,
+  type EXIT_OK,
+  type EXIT_STRAYS_FOUND,
+} from "../wire/index.js"
+import { ConfigDiscovery, ConfigService, EngineCore } from "../workflow/index.js"
 import type { ToolCommands } from "./ToolCommands.js"
 
 /**
@@ -53,7 +59,7 @@ export type JsonMode =
  * reach stdout.
  */
 export interface ArtifactOut {
-  readonly write: (chunk: string) => void
+  readonly write: (chunk: string | Uint8Array) => void
   readonly flush: () => void
 }
 
@@ -61,6 +67,7 @@ export type CommandRequirements =
   | GitService
   | ConfigService
   | ConfigDiscovery
+  | EngineCore
   | Workspace
   | Host
   | Narrator
@@ -81,3 +88,27 @@ export const writeJson = (
     else yield* writeSelection(out, document, json.path)
     return true
   })
+
+/** Exactly one trailing newline: a script embedded in a `--json` document is never re-normalized at its tail. */
+export const normalizeScriptNewline = (script: string): string =>
+  script.length === 0 ? script : `${script.replace(/\n+$/, "")}\n`
+
+/**
+ * A script-printing command's output: the script itself (or `plain`, when
+ * there is none to run), `{ schema, script }` under `--json`, or one field.
+ */
+export const writeScript = (
+  json: JsonMode,
+  out: ArtifactOut,
+  script: string,
+  plain: string = script,
+): Effect.Effect<void, Error> =>
+  Effect.gen(function* () {
+    if (json.kind === "off") {
+      out.write(plain)
+      return
+    }
+    const fields = scriptFields(normalizeScriptNewline(script))
+    if (json.kind === "document") out.write(renderScriptJson(fields))
+    else yield* writeSelection(out, fields, json.path)
+  })

package/src/cli/Program.test.ts

@@ -81,25 +81,26 @@ const seedIdle = (): InMemRepo => {
   return repo
 }
 
-describe("gtd --workflow <name> — a custom workflow's named workflow", () => {
-  const WORKFLOW = `import { agent, human } from "@pmelab/gtd/flows"
+describe("gtd start <name> — a custom workflow's named workflow", () => {
+  const WORKFLOW = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
 export default async () => {
   await human("idle", { message: "hi" })
   await agent("working", "go")
 }
 
-export const hotfix = async () => {
-  await agent("working", "go")
-}
-
-export const defaults = { greeting: "hello" }
+export const hotfix = workflow(
+  async () => {
+    await agent("working", "go")
+  },
+  { defaults: { greeting: "hello" } },
+)
 `
 
   it("the happy path emits the opening commit's script — gtd itself writes nothing", async () => {
     const repo = seed(WORKFLOW)
     const before = repo.commitHistory().length
-    const { stdout, exitCode } = await run(repo, "--workflow", "hotfix")
+    const { stdout, exitCode } = await run(repo, "start", "hotfix")
     expect(exitCode).toBe(0)
     expect(stdout).toContain(
       commitAll(
@@ -109,21 +110,20 @@ export const defaults = { greeting: "hello" }
     expect(repo.commitHistory()).toHaveLength(before)
   })
 
-  it("an unknown workflow is a usage error (exit 2) listing every startable name", async () => {
+  it("an unknown name is a usage error (exit 2) pointing at the list", async () => {
     const repo = seed(WORKFLOW)
     const before = repo.commitHistory().length
-    const { exitCode, stderr } = await run(repo, "--workflow", "bogus")
+    const { exitCode, stderr } = await run(repo, "start", "bogus")
     expect(exitCode).toBe(2)
     expect(repo.commitHistory()).toHaveLength(before)
-    expect(stderr).toContain('unknown workflow "bogus"')
-    expect(stderr).toContain("startable: hotfix")
+    expect(stderr).toContain('no workflow or door is named "bogus" — run `gtd start` to list them')
   })
 
   it("lists the paths its script commits as comments a path cannot break out of", async () => {
     const repo = seed(WORKFLOW)
     repo.writeFile("NOTE.md", "a note\n")
     repo.writeFile("evil\nrm -rf x", "")
-    const { stdout, exitCode } = await run(repo, "--workflow", "hotfix")
+    const { stdout, exitCode } = await run(repo, "start", "hotfix")
     expect(exitCode).toBe(0)
     expect(stdout).toContain("# commits every change in the working tree (git add -A):\n")
     expect(stdout).toContain("#   A NOTE.md\n")
@@ -134,9 +134,9 @@ export const defaults = { greeting: "hello" }
 
   it("`default` is not startable by name", async () => {
     const repo = seed(WORKFLOW)
-    const { exitCode, stderr } = await run(repo, "--workflow", "default")
+    const { exitCode, stderr } = await run(repo, "start", "default")
     expect(exitCode).toBe(2)
-    expect(stderr).toContain('unknown workflow "default"')
+    expect(stderr).toContain('no workflow or door is named "default"')
   })
 
   it("--entry is an ordinary unknown flag", async () => {
@@ -149,17 +149,18 @@ export const defaults = { greeting: "hello" }
     const repo = seed(WORKFLOW)
     await landTurn(repo, { ".gtd/TODO.md": "sketch\n" })
     const before = repo.commitHistory().length
-    const { exitCode, stderr } = await run(repo, "--workflow", "hotfix")
+    const { exitCode, stderr } = await run(repo, "start", "hotfix")
     expect(exitCode).toBe(1)
     expect(repo.commitHistory()).toHaveLength(before)
     expect(stderr).toContain("already underway")
   })
 
-  it("an undeclared --var name refuses, listing the declared names", async () => {
+  it("an undeclared --var name is a usage error (exit 2), listing the declared names", async () => {
     const repo = seed(WORKFLOW)
     const before = repo.commitHistory().length
-    const { exitCode, stderr } = await run(repo, "--workflow", "hotfix", "--var", "bogus=1")
-    expect(exitCode).toBe(1)
+    const { exitCode, stderr, stdout } = await run(repo, "start", "hotfix", "--var", "bogus=1")
+    expect(exitCode).toBe(2)
+    expect(stdout).toBe("")
     expect(repo.commitHistory()).toHaveLength(before)
     expect(stderr).toContain("bogus")
     expect(stderr).toContain("greeting")
@@ -168,7 +169,7 @@ export const defaults = { greeting: "hello" }
   it("a declared --var override renders as a Gtd-Var trailer in the emitted commit script", async () => {
     const repo = seed(WORKFLOW)
     const before = repo.commitHistory().length
-    const { exitCode, stdout } = await run(repo, "--workflow", "hotfix", "--var", "greeting=world")
+    const { exitCode, stdout } = await run(repo, "start", "hotfix", "--var", "greeting=world")
     expect(exitCode).toBe(0)
     expect(stdout).toContain("Gtd-Var: greeting=world")
     expect(repo.commitHistory()).toHaveLength(before)
@@ -178,7 +179,7 @@ export const defaults = { greeting: "hello" }
     const repo = seed(WORKFLOW)
     repo.writeFile("scratch.txt", "uncommitted\n")
     const before = repo.commitHistory().length
-    const { exitCode, stdout } = await run(repo, "--workflow", "hotfix")
+    const { exitCode, stdout } = await run(repo, "start", "hotfix")
     expect(exitCode).toBe(0)
     expect(stdout.length).toBeGreaterThan(0)
     expect(repo.commitHistory()).toHaveLength(before)
@@ -186,7 +187,7 @@ export const defaults = { greeting: "hello" }
 
   it("applying the start script opens the workflow's episode at its first step", async () => {
     const repo = seed(WORKFLOW)
-    const { stdout } = await run(repo, "--workflow", "hotfix")
+    const { stdout } = await run(repo, "start", "hotfix")
     expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
     expect(repo.lastCommitSubject()).toBe("gtd(human): working")
     const next = JSON.parse((await run(repo, "next", "--json")).stdout) as Record<string, unknown>
@@ -197,7 +198,7 @@ export const defaults = { greeting: "hello" }
 
   it("a pinned workflow the config no longer defines is refused with the abandon advice", async () => {
     const repo = seed(WORKFLOW)
-    const { stdout } = await run(repo, "--workflow", "hotfix")
+    const { stdout } = await run(repo, "start", "hotfix")
     applyEmittedScript(repo, new Map(), stdout)
     repo.writeFile("gtd.config.ts", WORKFLOW.replace("export const hotfix", "const hotfix"))
     const { exitCode, stderr } = await run(repo, "next")
@@ -207,18 +208,16 @@ export const defaults = { greeting: "hello" }
   })
 })
 
-describe("gtd install", () => {
+describe("gtd guide", () => {
   it("where no gtd.config.ts governs, prints the briefing and warns where to get a workflow — writing nothing", async () => {
     const repo = new InMemRepo()
     repo.writeFile("README.md", "# test project\n")
     repo.seedCommit("chore: init")
     const before = repo.snapshot()
-    const { stdout, stderr, exitCode } = await run(repo, "install")
+    const { stdout, stderr, exitCode } = await run(repo, "guide")
     expect(exitCode).toBe(0)
     expect(stdout).toMatch(/Make sure a .gtd\.config\.ts. governs the repository/)
-    expect(stderr).toContain(
-      "gtd install: no gtd.config.ts governs here, and gtd ships no workflow",
-    )
+    expect(stderr).toContain("gtd guide: no gtd.config.ts governs here, and gtd ships no workflow")
     expect(stderr).toContain(WORKFLOWS_REPO)
     expect(repo.hasPath("gtd.config.ts")).toBe(false)
     expect(repo.snapshot()).toBe(before)
@@ -226,42 +225,35 @@ describe("gtd install", () => {
 
   it("where a gtd.config.ts governs, prints the briefing alone", async () => {
     const repo = seedIdle()
-    const { stdout, stderr, exitCode } = await run(repo, "install")
+    const { stdout, stderr, exitCode } = await run(repo, "guide")
     expect(exitCode).toBe(0)
     expect(stdout).toMatch(/Make sure a .gtd\.config\.ts. governs the repository/)
     expect(stderr).not.toContain(WORKFLOWS_REPO)
   })
 })
 
-describe("gtd --workflow <name> — a workflow that fixes its diff base", () => {
-  const WORKFLOW = `import { human } from "@pmelab/gtd/flows"
+describe("gtd start <name> — a workflow that fixes its diff base", () => {
+  const WORKFLOW = `import { human, workflow } from "@pmelab/gtd/flows"
 
 export default async () => {
   await human("idle", { message: "hi" })
 }
 
-export const review = async () => {
-  await human("checking", { message: "check" })
-}
-
-export const defaults = { reviewBase: "" }
-
-export const base = (workflow, vars) => (workflow === "review" ? vars.reviewBase : undefined)
+export const review = workflow(
+  async () => {
+    await human("checking", { message: "check" })
+  },
+  { defaults: { reviewBase: "" }, base: (_workflow, vars) => vars.reviewBase },
+)
 `
 
-  it("--workflow review --var reviewBase=<base> emits a script anchoring the process to that base", async () => {
+  it("start review --var reviewBase=<base> emits a script anchoring the process to that base", async () => {
     const repo = seed(WORKFLOW)
     const base = repo.commitHistory().at(-1)!.hash
     repo.writeFile("scratch.txt", "more work\n")
     repo.seedCommit("chore: more work")
     const before = repo.commitHistory().length
-    const { stdout, exitCode } = await run(
-      repo,
-      "--workflow",
-      "review",
-      "--var",
-      `reviewBase=${base}`,
-    )
+    const { stdout, exitCode } = await run(repo, "start", "review", "--var", `reviewBase=${base}`)
     expect(exitCode).toBe(0)
     expect(stdout).toContain("gtd(human): checking")
     expect(stdout).toContain("Gtd-Workflow: review")
@@ -453,7 +445,7 @@ export default async () => {
 })
 
 describe("gtd next --json — stall detection (attempt commits)", () => {
-  const WORKFLOW = `import { agent, human, run } from "@pmelab/gtd/flows"
+  const WORKFLOW = `import { agent, human, run, workflow } from "@pmelab/gtd/flows"
 
 const work = async () => {
   await agent("working", "do the work described in NOTE.md")
@@ -465,7 +457,7 @@ export default async () => {
   await work()
 }
 
-export const resume = work
+export const resume = workflow(work)
 `
 
   const atWorking = async (): Promise<InMemRepo> => {
@@ -502,7 +494,7 @@ export const resume = work
 
   it("a clean-tree entry commit resting at a prompt step is NOT a stall — the actor differs (human entered, agent acts)", async () => {
     const repo = seed(WORKFLOW)
-    const { stdout: entry } = await run(repo, "--workflow", "resume")
+    const { stdout: entry } = await run(repo, "start", "resume")
     expect(applyEmittedScript(repo, new Map(), entry).ok).toBe(true)
     const { stdout, exitCode } = await run(repo, "next", "--json")
     expect(exitCode).toBe(0)
@@ -1001,18 +993,19 @@ describe("gtd check <mode> <file>", () => {
     )
   })
 
-  it("an absent file exits 0 with no output", async () => {
+  it("an absent file is a refusal (exit 1) naming it", async () => {
     const repo = bareRepo()
-    const { stdout, exitCode } = await run(repo, "check", "qa", ".gtd/TODO.md")
-    expect(exitCode).toBe(0)
+    const { stdout, stderr, exitCode } = await run(repo, "check", "qa", ".gtd/TODO.md")
+    expect(exitCode).toBe(1)
     expect(stdout).toBe("")
+    expect(stderr).toContain("gtd check: no such file: .gtd/TODO.md")
   })
 
-  it("an unknown mode is a usage-style error naming the known modes", async () => {
+  it("an unknown mode is a usage error (exit 2) naming the known modes", async () => {
     const repo = bareRepo()
     repo.writeFile("TODO.md", validQaDoc)
     const { stderr, exitCode } = await run(repo, "check", "bogus", "TODO.md")
-    expect(exitCode).toBe(1)
+    expect(exitCode).toBe(2)
     expect(stderr).toContain('unknown mode "bogus"')
     expect(stderr).toContain("qa")
     expect(stderr).toContain("review")
@@ -1244,13 +1237,6 @@ describe("gtd check <mode> <file> --open-questions", () => {
     expect(stderr).toContain(".gtd/TODO.md")
   })
 
-  it("check without the flag is unchanged: an absent file still exits 0 with no output", async () => {
-    const repo = bareRepo()
-    const { stdout, exitCode } = await run(repo, "check", "qa", ".gtd/TODO.md")
-    expect(exitCode).toBe(0)
-    expect(stdout).toBe("")
-  })
-
   it("--json is out of scope for check --open-questions too — a usage error, never a JSON envelope", async () => {
     const repo = bareRepo()
     repo.writeFile(".gtd/TODO.md", docWithUnanswered)
@@ -1277,7 +1263,7 @@ describe("gtd check <mode> <file> --open-questions", () => {
       "--open-questions",
       ".gtd/TODO.md",
     )
-    expect(exitCode).not.toBe(0)
+    expect(exitCode).toBe(2)
     expect(stderr).toContain('unknown mode "bogus"')
     expect(stderr).toContain("qa")
     expect(stderr).toContain("review")
@@ -1718,16 +1704,15 @@ describe("runCommand — refuses in a repository with no commits", () => {
     lsp: { kind: "lsp" },
     ui: { kind: "ui", selfSigned: false, dev: false },
     land: { kind: "land" },
-    start: { kind: "start", actor: "human", workflow: "feature", vars: {}, label: "" },
-    door: { kind: "door", name: "fix", args: [] },
-    doors: { kind: "doors" },
+    start: { kind: "start", name: "fix", args: [], vars: {} },
     abandon: { kind: "abandon" },
     restore: { kind: "restore" },
     next: { kind: "next" },
     validate: { kind: "validate" },
     check: { kind: "check", mode: "qa", file: ".gtd/TODO.md" },
     uncheck: { kind: "uncheck", file: ".gtd/REVIEW.md" },
-    install: { kind: "install" },
+    guide: { kind: "guide" },
+    bundle: { kind: "bundle" },
     summary: { kind: "summary" },
     base: { kind: "base" },
     judge: { kind: "judge" },
@@ -1748,13 +1733,12 @@ describe("runCommand — refuses in a repository with no commits", () => {
   const NO_COMMITS_MESSAGE =
     "gtd: the repository has no commits yet — make an initial commit, then run gtd again"
 
-  it("derives exactly the eighteen non-standalone kinds — a canary for the table-driven cases below", () => {
+  it("derives exactly the seventeen non-standalone kinds — a canary for the table-driven cases below", () => {
     expect(stateKinds.sort()).toEqual(
       [
         "abandon",
         "base",
-        "door",
-        "doors",
+        "bundle",
         "start",
         "land",
         "next",
@@ -1779,7 +1763,10 @@ describe("runCommand — refuses in a repository with no commits", () => {
       const repo = new InMemRepo()
       const before = repo.commitHistory().length
       const written: string[] = []
-      const out = { write: (chunk: string) => written.push(chunk), flush: () => {} }
+      const out = {
+        write: (chunk: string | Uint8Array) => written.push(String(chunk)),
+        flush: () => {},
+      }
 
       const exit = await Effect.runPromiseExit(
         runCommand(commandFor[kind], { kind: "off" }, out).pipe(Effect.provide(testLayers(repo))),
@@ -1798,7 +1785,10 @@ describe("runCommand — refuses in a repository with no commits", () => {
   it("a repository with a commit passes the guard and dispatches normally", async () => {
     const repo = seedIdle()
     const written: string[] = []
-    const out = { write: (chunk: string) => written.push(chunk), flush: () => {} }
+    const out = {
+      write: (chunk: string | Uint8Array) => written.push(String(chunk)),
+      flush: () => {},
+    }
 
     const exit = await Effect.runPromiseExit(
       runCommand({ kind: "next" }, { kind: "off" }, out).pipe(Effect.provide(testLayers(repo))),
@@ -1830,16 +1820,19 @@ describe("runCommand — refuses in a repository with no commits", () => {
 })
 
 describe("gtd summary", () => {
-  const SUMMARY_WORKFLOW = `import { agent, human } from "@pmelab/gtd/flows"
+  const SUMMARY_WORKFLOW = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+export default workflow(
+  async () => {
     await human("idle", { message: "hi" })
     await agent("working", "go")
     await human("reviewing", { message: "check it" })
     await agent("polishing", "polish")
-  }
-
-export const summary = (c) => \`entry=\${c.entryCommit} tip=\${c.processTip} humans=\${c.humanCommits.length}\`
+  },
+  {
+    summary: (c) => \`entry=\${c.entryCommit} tip=\${c.processTip} humans=\${c.humanCommits.length}\`,
+  },
+)
 `
 
   const reviewed = async (): Promise<InMemRepo> => {
@@ -2105,7 +2098,7 @@ describe("gtd next/land --json=<path> — the select branch", () => {
     )
     expect(Exit.isFailure(exit)).toBe(true)
     if (Exit.isFailure(exit)) {
-      const failure = Cause.failureOption(exit.cause)
+      const failure = Cause.findErrorOption(exit.cause)
       expect(failure._tag).toBe("Some")
       if (failure._tag === "Some") {
         expect(failure.value).toBeInstanceOf(SelectorUsageError)
@@ -2131,14 +2124,15 @@ describe("gtd judge / gtd judge answer", () => {
   const QUESTION = `{ id: "q1", primitive: "noul", instructions: "i", criteria: "c" }`
 
   const judgeWorkflow = (evidence: string, then: string, vars = "{}"): string =>
-    `import { agent, human, judge, read } from "@pmelab/gtd/flows"
+    `import { agent, human, judge, read, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+export default workflow(
+  async () => {
     await judge("idle", { questions: [${QUESTION}], evidence: ${evidence} })
     await ${then}
-  }
-
-export const defaults = ${vars}
+  },
+  { defaults: ${vars} },
+)
 `
 
   const seededRepo = (): InMemRepo =>
@@ -2311,8 +2305,8 @@ export const defaults = ${vars}
 describe("runCommand — the repository-root guard's messages", () => {
   const guarded = async (
     override: (
-      git: Context.Tag.Service<GitService>,
-      host: Context.Tag.Service<Host>,
+      git: Context.Service.Shape<typeof GitService>,
+      host: Context.Service.Shape<typeof Host>,
     ) => Effect.Effect<unknown, Error, CommandRequirements>,
   ): Promise<string> => {
     const exit = await Effect.runPromiseExit(