@pmelab/gtd 59.0.1 → 60.0.0

package/src/edge/Edge.test.ts

@@ -105,8 +105,8 @@ const land = async (repo: InMemRepo, files: Files = {}): Promise<string> => {
 
 const enter = async (repo: InMemRepo, workflow: string, ...vars: string[]): Promise<string> => {
   const flags = vars.flatMap((v) => ["--var", v])
-  const { stdout, stderr, exitCode } = await cli(repo, "--workflow", workflow, ...flags)
-  if (exitCode !== 0) throw new Error(`gtd --workflow exited ${exitCode}: ${stderr}`)
+  const { stdout, stderr, exitCode } = await cli(repo, "start", workflow, ...flags)
+  if (exitCode !== 0) throw new Error(`gtd start exited ${exitCode}: ${stderr}`)
   return applied(repo, stdout)
 }
 
@@ -117,26 +117,26 @@ const commit = (repo: InMemRepo, spec: CommitSpec, files: Files = {}): string =>
   return headOf(repo)
 }
 
-const LINEAR = `import { agent, human } from "@pmelab/gtd/flows"
+const LINEAR = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+const defaults = { base: "", reviewer: "nobody" }
+const base = (workflow, vars) => (workflow === "review" ? (vars.base ?? "") : undefined)
+
+export default workflow(async () => {
   await human("idle", { message: "idle-message" })
   await agent("building", "build-prompt")
   await agent("checking", "check-prompt")
-}
+}, { defaults, base })
 
-export const side = async () => {
+export const side = workflow(async () => {
   await agent("fixing", "fix-prompt")
   await agent("tidying", "tidy-prompt", { allowEmpty: true })
-}
+}, { defaults, base })
 
-export const review = async () => {
+export const review = workflow(async () => {
   await agent("fixing", "fix-prompt")
-}
+}, { defaults, base })
 
-export const defaults = { base: "", reviewer: "nobody" }
-
-export const base = (workflow, vars) => (workflow === "review" ? (vars.base ?? "") : undefined)
 `
 
 describe("currentRun", () => {
@@ -220,18 +220,18 @@ describe("currentRun", () => {
   })
 
   it("a workflow starting at the default's initial step still opens its own episode, not the empty tree", async () => {
-    const STARTS_AT_INITIAL = `import { agent, human } from "@pmelab/gtd/flows"
+    const STARTS_AT_INITIAL = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
 export default async () => {
   await human("idle", { message: "idle-message" })
   await agent("building", "build-prompt")
 }
 
-export const again = async () => {
+export const again = workflow(async () => {
   await human("idle", { message: "idle-message" })
   await agent("fixing", "fix-prompt")
   await agent("tidying", "tidy-prompt", { allowEmpty: true })
-}
+})
 `
     const repo = repoWith(STARTS_AT_INITIAL)
     const before = headOf(repo)
@@ -539,9 +539,10 @@ describe("summaryRun", () => {
 })
 
 describe("process marks", () => {
-  const SUMMARISED = `${LINEAR}
-export const summary = (it) => it.marks.map((m) => m.name + "=" + m.value).join("|")
-`
+  const SUMMARISED = LINEAR.replace(
+    "export default",
+    `const summary = (it) => it.marks.map((m) => m.name + "=" + m.value).join("|")\n\nexport default`,
+  ).replaceAll("{ defaults, base }", "{ defaults, base, summary }")
   const opening = (marks: readonly Mark[]): CommitSpec => ({
     actor: "human",
     from: "idle",
@@ -609,17 +610,18 @@ const withTipMessage = (repo: InMemRepo, edit: (message: string) => string): Git
 }
 
 describe("summaryFor", () => {
-  const SUMMARISED_FLOW = `import { agent, human, mark } from "@pmelab/gtd/flows"
+  const SUMMARISED_FLOW = `import { agent, human, mark, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+const summary = (it) => JSON.stringify(it)
+
+export default workflow(async () => {
   await human("idle", { message: "idle-message" })
   mark("risk-tier", "high")
   await agent("building", "build-prompt")
   await human("gate", { message: "gate-message" })
   await agent("checking", "check-prompt")
-}
+}, { summary })
 
-export const summary = (it) => JSON.stringify(it)
 `
   const landCost = async (repo: InMemRepo, files: Files, cost: number, model: string) => {
     write(repo, files)
@@ -678,7 +680,7 @@ export const summary = (it) => JSON.stringify(it)
   it("returns no prompt, not a failure, when an edited config no longer exports a summary", async () => {
     const { repo } = await finished()
     const run = await provide(summaryRun, repo)
-    repo.writeFile("gtd.config.ts", SUMMARISED_FLOW.replace(/export const summary.*\n/, ""))
+    repo.writeFile("gtd.config.ts", SUMMARISED_FLOW.replace(", { summary })", ")"))
     expect(await provide(summaryFor(run), repo)).toEqual({ prompt: undefined })
   })
 
@@ -773,24 +775,24 @@ export default async () => {
 })
 
 describe("reviewBaseFor", () => {
-  const LOOP = `import { agent, head, human, read } from "@pmelab/gtd/flows"
+  const LOOP = `import { agent, head, human, read, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+const defaults = { base: "" }
+const base = (workflow, vars) => (workflow === "review" ? (vars.base ?? "") : undefined)
+
+export default workflow(async () => {
   await human("idle")
   while (read("DONE") === undefined) {
     const base = head()
     await human("checkpoint", { base })
     await agent("building", "build-prompt", { base })
   }
-}
+}, { defaults, base })
 
-export const review = async () => {
+export const review = workflow(async () => {
   await agent("fixing", "fix-prompt")
-}
-
-export const defaults = { base: "" }
+}, { defaults, base })
 
-export const base = (workflow, vars) => (workflow === "review" ? (vars.base ?? "") : undefined)
 `
 
   it("is the process's diff base at a step that names no base", async () => {
@@ -906,17 +908,18 @@ export default async () => {
 })
 
 describe("vars", () => {
-  const VARS = `import { agent, human } from "@pmelab/gtd/flows"
+  const VARS = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+const defaults = { deployTarget: "npm test", reviewer: "nobody" }
+
+export default workflow(async () => {
   await human("idle")
-}
+}, { defaults })
 
-export const side = async () => {
+export const side = workflow(async () => {
   await agent("working", "w")
-}
+}, { defaults })
 
-export const defaults = { deployTarget: "npm test", reviewer: "nobody" }
 `
   const seeded = () => repoWith(VARS)
 
@@ -960,17 +963,18 @@ export const defaults = { deployTarget: "npm test", reviewer: "nobody" }
 })
 
 describe("StartFlags", () => {
-  const FLAGGED = `import { agent, human } from "@pmelab/gtd/flows"
+  const FLAGGED = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+const defaults = { flag_risk_tier: "0", other: "x" }
+
+export default workflow(async () => {
   await human("idle")
-}
+}, { defaults })
 
-export const side = async () => {
+export const side = workflow(async () => {
   await agent("working", "w")
-}
+}, { defaults })
 
-export const defaults = { flag_risk_tier: "0", other: "x" }
 `
   const withFlags = <A>(
     eff: Effect.Effect<A, Error, RestRequirements>,
@@ -1004,15 +1008,16 @@ export const defaults = { flag_risk_tier: "0", other: "x" }
 })
 
 describe("environment settings", () => {
-  const ENVV = `import { agent, human } from "@pmelab/gtd/flows"
+  const ENVV = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+const defaults = { floor: "0.7" }
+const envDefaults = { testCommand: "npm test" }
+
+export default workflow(async () => {
   await human("idle")
   await agent("working", "w")
-}
+}, { defaults, envDefaults })
 
-export const defaults = { floor: "0.7" }
-export const envDefaults = { testCommand: "npm test" }
 `
   const seeded = () => repoWith(ENVV)
 
@@ -1119,18 +1124,21 @@ describe("noProcessUnderway / restIsIdle", () => {
 })
 
 describe("judge rests", () => {
-  const JUDGED = (budget: string) => `import { human, judge, read } from "@pmelab/gtd/flows"
+  const JUDGED = (
+    budget: string,
+  ) => `import { human, judge, read, workflow } from "@pmelab/gtd/flows"
 
-export default async () => {
+const defaults = { judgeBudgetBytes: ${JSON.stringify(budget)} }
+
+export default workflow(async () => {
     await human("idle")
     await judge("verdict", {
       questions: [{ id: "q", primitive: "noul", instructions: "i", criteria: "c" }],
       evidence: { log: read("LOG.md") ?? "" },
       message: "judge-message",
     })
-  }
+  }, { defaults })
 
-export const defaults = { judgeBudgetBytes: ${JSON.stringify(budget)} }
 `
   const LOG = Array.from({ length: 10 }, (_, i) => `line ${i} of the log`).join("\n") + "\n"
 
@@ -1315,17 +1323,17 @@ export default async () => {
     expect(landing.spec.branch).toBeUndefined()
   })
 
-  it("a --workflow process's entry is its opening commit", async () => {
-    const repo = repoWith(`import { agent, human } from "@pmelab/gtd/flows"
+  it("a gtd start process's entry is its opening commit", async () => {
+    const repo = repoWith(`import { agent, human, workflow } from "@pmelab/gtd/flows"
 
 export default async () => {
   await human("idle")
   await agent("building", "build-prompt")
 }
 
-export const side = async () => {
+export const side = workflow(async () => {
   await agent("fixing", "fix-prompt")
-}
+})
 `)
     const opening = await enter(repo, "side")
     repo.writeFile("a.txt", "a\n")

package/src/edge/Edge.ts

@@ -83,14 +83,14 @@ interface EpisodeLocation {
   readonly legacyOpening: boolean
   /** The commit replay starts reading from, or -1 for the empty tree before history. */
   readonly baseIndex: number
-  /** The process's first commit — a `--workflow` process's opening commit, else the one after the base. */
+  /** The process's first commit — a `gtd start` process's opening commit, else the one after the base. */
   readonly processStart: number
 }
 
 /**
  * Where the episode HEAD belongs to begins, read off subjects alone. Walking
  * back from HEAD: a bare `gtd(human): <step>` commit with no `Gtd-Step` is what
- * `gtd --workflow` writes — no landing ever produces one — and opens an
+ * `gtd start` writes — no landing ever produces one — and opens an
  * episode as its first commit (its `Gtd-Workflow` trailer names the workflow;
  * a legacy `--entry` opening has none); a commit that is not a gtd step commit, or one
  * entering the flow's first step (a finished episode), bounds the episode
@@ -1039,7 +1039,7 @@ type EndedOutcome = Extract<ReplayOutcome, { kind: "ended" }>
 type UnendedOutcome = Exclude<ReplayOutcome, { kind: "ended" }>
 
 /**
- * Whether `gtd --workflow <name>` can start a process here: the workflow must
+ * Whether `gtd start <name>` can start a process here: the workflow must
  * reach a step from the tree the opening commit would capture. That step is
  * what the opening commit's subject names.
  */

package/src/flows/factory.test.ts

@@ -86,6 +86,20 @@ describe("defineWorkflow", () => {
     })
   })
 
+  it("hands on the skills, access, steering and summary a build carries", () => {
+    const carried = {
+      flow,
+      skills: (vars: Readonly<Record<string, string>>) => ({ work: [vars.skill ?? "x"] }),
+      access: { work: { write: ["out/**"] } },
+      steering: { ".gtd/PLAN.md": "qa" },
+      summary: () => "done",
+    }
+    expect(configure(defineWorkflow(greetingSchema, () => carried))).toEqual({
+      ok: true,
+      build: carried,
+    })
+  })
+
   it("throws when a call's result is awaited as if it were a flow", async () => {
     await expect(Promise.resolve(greeter() as unknown as PromiseLike<void>)).rejects.toThrow(
       /not a flow/,

package/src/flows/factory.ts

@@ -1,20 +1,37 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec"
-import type { Flow, WorkflowBase, WorkflowDoors } from "./runtime.js"
+import type {
+  AccessExport,
+  Flow,
+  SkillsExport,
+  Steering,
+  Summary,
+  WorkflowBase,
+  WorkflowDoors,
+} from "./runtime.js"
 
 // Registered, so a factory made by any copy of this file is recognised by the
 // engine's copy — the same reason the replay context is.
 const FACTORY = Symbol.for("@pmelab/gtd/workflow-factory")
 
+/** What a `defineWorkflow` build returns; `workflow(flow, options)` takes the same keys but `flow`. */
 export interface WorkflowBuild {
   readonly flow: Flow
-  /** Process settings this workflow declares, over its file's `defaults` export. */
+  /** Process settings this workflow declares. */
   readonly defaults?: Readonly<Record<string, string>> | undefined
-  /** Environment settings this workflow declares, over its file's `envDefaults` export. */
+  /** Environment settings this workflow declares. */
   readonly envDefaults?: Readonly<Record<string, string>> | undefined
-  /** Doors onto this workflow. Two workflows building the same door is a load error unless the config's `doors` export declares that name; a declared door always wins. */
+  /** Doors onto this workflow. Two workflows building the same door build none unless one is exported under the door's name. */
   readonly doors?: WorkflowDoors | undefined
-  /** This workflow's diff base; the config's `base` export wins when it answers, `undefined` falls through to this. */
+  /** This workflow's diff base. */
   readonly base?: WorkflowBase | undefined
+  /** This workflow's scope skill lists; a `config.skills` entry wins over the same scope here. */
+  readonly skills?: SkillsExport | undefined
+  /** This workflow's scope access; a `config.access` entry wins over the same scope here. */
+  readonly access?: AccessExport | undefined
+  /** This workflow's steering files, path -> mode. */
+  readonly steering?: Steering | undefined
+  /** `gtd summary`'s prompt for this workflow. */
+  readonly summary?: Summary | undefined
 }
 
 interface FactoryInternals {

package/src/flows/helpers.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it } from "vitest"
+import { check } from "./helpers.js"
+import { installContext, type FlowContext, type StepRequest } from "./internal.js"
+
+afterEach(() => installContext(undefined))
+
+const recording = () => {
+  const requests: StepRequest[] = []
+  installContext({
+    step: async (request: StepRequest) => {
+      requests.push(request)
+    },
+    head: () => "abcdef1234",
+    changes: () => [],
+    matches: (path: string, pattern: string) => path === pattern,
+  } as unknown as FlowContext)
+  return requests
+}
+
+describe("check()", () => {
+  it("takes the report positionally and renders a run step", async () => {
+    const requests = recording()
+    expect(await check("suite", "npm test", ".gtd/FEEDBACK.md", { label: "Tests" })).toBe(true)
+    expect(requests).toHaveLength(1)
+    expect(requests[0]).toMatchObject({ kind: "run", name: "suite", options: { label: "Tests" } })
+  })
+
+  it("refuses the removed options form, which an untyped config can still write", async () => {
+    recording()
+    const removed = check as unknown as (n: string, c: string, o: object) => Promise<boolean>
+    await expect(removed("suite", "npm test", { report: ".gtd/FEEDBACK.md" })).rejects.toThrow(
+      'gtd: check("suite"): the report path is the third argument — check(name, command, report, options?)',
+    )
+  })
+})

package/src/flows/helpers.ts

@@ -9,8 +9,8 @@ import {
   read,
   refuse,
   run,
+  settings,
   threads,
-  vars,
   type Change,
   type JudgeAnswer,
   type Judgment,
@@ -33,9 +33,8 @@ export const numeric = (value: string | undefined, fallback: number): number =>
 /** Whether the last step added or rewrote `path`. */
 export const wrote = (path: string): boolean => changes(path).some((c) => c.status !== "deleted")
 
+/** `check()`'s options beside its report path. */
 export interface CheckOptions {
-  /** Where a failing run leaves its output. */
-  readonly report: string
   readonly label?: string | undefined
   /** Paths removed before the command runs. */
   readonly sweep?: readonly string[] | undefined
@@ -45,17 +44,27 @@ export interface CheckOptions {
   readonly preamble?: readonly string[] | undefined
 }
 
+export type Check = (
+  name: string,
+  command: string,
+  /** Where a failing run leaves its output. */
+  report: string,
+  options?: CheckOptions,
+) => Promise<boolean>
+
 /**
  * A step that runs `command` through the driver and keeps its outcome in the
  * tree: a failure writes `report`, a pass removes it. Resolves `true` when the
  * command passed.
  */
-export const check = async (
-  name: string,
-  command: string,
-  options: CheckOptions,
-): Promise<boolean> => {
-  const { report, label, sweep, sweepOnGreen, preamble } = options
+export const check: Check = async (name, command, report, options = {}) => {
+  // A config is evaluated without a type check, so the removed form must fail loudly.
+  if (typeof report !== "string") {
+    throw new Error(
+      `gtd: check("${name}"): the report path is the third argument — check(name, command, report, options?)`,
+    )
+  }
+  const { label, sweep, sweepOnGreen, preamble } = options
   await run(
     name,
     checkScript(command, { report, stamp: head().slice(0, 7), sweep, sweepOnGreen, preamble }),
@@ -220,7 +229,7 @@ export const judgeDiffShape = async (
 
   const minP =
     options.minP ??
-    (vars.judgeShapeMinP === undefined ? 0.7 : numeric(vars.judgeShapeMinP, Infinity))
+    (settings.judgeShapeMinP === undefined ? 0.7 : numeric(settings.judgeShapeMinP, Infinity))
   const judgment = await judge(name, {
     questions: [
       {

package/src/flows/index.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest"
+import * as published from "./index.js"
+
+describe("@pmelab/gtd/flows", () => {
+  it("publishes exactly the authoring surface, no engine-only name among it", () => {
+    expect(Object.keys(published).sort()).toEqual(
+      [
+        "FLOWS_PROTOCOL",
+        "FlowsProtocolError",
+        "accessFor",
+        "agent",
+        "answered",
+        "applyScript",
+        "changes",
+        "changesSince",
+        "check",
+        "checkScript",
+        "codeChanges",
+        "codeThreads",
+        "defineConfig",
+        "defineWorkflow",
+        "displayPath",
+        "envSettings",
+        "envSettingsOf",
+        "glob",
+        "hasThreadFor",
+        "head",
+        "human",
+        "judge",
+        "judgeDiffShape",
+        "kept",
+        "mark",
+        "matches",
+        "moveScript",
+        "numeric",
+        "openQuestions",
+        "quote",
+        "read",
+        "refuse",
+        "removeScript",
+        "requireAnswers",
+        "requireProgress",
+        "requireReplies",
+        "requireRevert",
+        "requireThreadsClosed",
+        "restart",
+        "restoreScript",
+        "revertScript",
+        "run",
+        "scope",
+        "seamGate",
+        "sectionBodies",
+        "sections",
+        "settings",
+        "settingsOf",
+        "showScript",
+        "skillsFor",
+        "start",
+        "threads",
+        "workflow",
+        "writeScript",
+        "wrote",
+      ].sort(),
+    )
+  })
+})

package/src/flows/index.ts

@@ -1,5 +1,109 @@
-export * from "./runtime.js"
-export * from "./helpers.js"
-export * from "./scripts.js"
-export * from "./factory.js"
-export * from "./config.js"
+// `@pmelab/gtd/flows`: the authoring surface, listed name by name. gtd's own
+// code imports `./internal.js`, which adds what the engine needs.
+
+export {
+  accessFor,
+  agent,
+  changes,
+  changesSince,
+  codeThreads,
+  envSettings,
+  envSettingsOf,
+  FLOWS_PROTOCOL,
+  FlowsProtocolError,
+  glob,
+  head,
+  human,
+  judge,
+  kept,
+  mark,
+  matches,
+  openQuestions,
+  read,
+  refuse,
+  restart,
+  run,
+  scope,
+  sectionBodies,
+  sections,
+  settings,
+  settingsOf,
+  skillsFor,
+  start,
+  threads,
+  workflow,
+  type AccessDef,
+  type AccessExport,
+  type AgentOptions,
+  type Change,
+  type Changes,
+  type CodeThreadInfo,
+  type Door,
+  type Flow,
+  type Human,
+  type HumanOptions,
+  type JudgeAnswer,
+  type JudgePrimitive,
+  type JudgeQuestion,
+  type JudgeQuestionInput,
+  type JudgeSpec,
+  type Judgment,
+  type KeptTip,
+  type Mark,
+  type ModeName,
+  type OpenQuestion,
+  type RunOptions,
+  type ScopeAccess,
+  type ScopeOptions,
+  type Section,
+  type Settings,
+  type SkillsExport,
+  type Steering,
+  type SteeringOptions,
+  type Summary,
+  type SummaryContext,
+  type ThreadInfo,
+  type WorkflowBase,
+  type WorkflowDoors,
+  type WorkflowOptions,
+} from "./runtime.js"
+export {
+  answered,
+  check,
+  codeChanges,
+  displayPath,
+  hasThreadFor,
+  judgeDiffShape,
+  numeric,
+  requireAnswers,
+  requireProgress,
+  requireReplies,
+  requireRevert,
+  requireThreadsClosed,
+  seamGate,
+  wrote,
+  type Check,
+  type CheckOptions,
+  type DiffShape,
+  type DiffShapeOptions,
+  type DiffShapeResult,
+} from "./helpers.js"
+export {
+  applyScript,
+  checkScript,
+  moveScript,
+  quote,
+  removeScript,
+  restoreScript,
+  revertScript,
+  showScript,
+  writeScript,
+  type CheckScriptOptions,
+} from "./scripts.js"
+export {
+  defineWorkflow,
+  type ConfiguredWorkflow,
+  type WorkflowBuild,
+  type WorkflowFactory,
+} from "./factory.js"
+export { defineConfig, type GtdConfig, type ModeCommands, type UiSettings } from "./config.js"

package/src/flows/internal.ts

@@ -0,0 +1,7 @@
+// gtd's own imports of the flows facade: everything public, plus what only the
+// engine uses.
+export * from "./index.js"
+export { installContext, protocolMismatch, type FlowContext, type StepRequest } from "./runtime.js"
+export { markedOptions } from "./runtime.js"
+export { configure, isFactoryWorkflow, type OptionIssue } from "./factory.js"
+export { configProblems } from "./config.js"