@pmelab/gtd 59.0.1 → 60.0.0

package/src/flows/runtime.test.ts

@@ -1,13 +1,29 @@
-import { afterEach, describe, expect, it } from "vitest"
+import { afterEach, describe, expect, expectTypeOf, it } from "vitest"
 import {
   FLOWS_PROTOCOL,
   FlowsProtocolError,
+  envSettings,
+  envSettingsOf,
   head,
+  human,
   installContext,
+  markedOptions,
+  judge,
   kept,
   mark,
   protocolMismatch,
+  settings,
+  settingsOf,
+  workflow,
   type FlowContext,
+  type AgentOptions,
+  type HumanOptions,
+  type Judgment,
+  type ModeName,
+  type RunOptions,
+  type Settings,
+  type SteeringOptions,
+  type StepRequest,
 } from "./runtime.js"
 
 afterEach(() => installContext(undefined))
@@ -127,3 +143,178 @@ describe("kept()", () => {
     expect(FLOWS_PROTOCOL).toBe(1)
   })
 })
+
+/** A context that records every step request and resolves it with `reply`. */
+const recording = (reply: unknown = undefined) => {
+  const requests: StepRequest[] = []
+  installContext({
+    step: async (request: StepRequest) => {
+      requests.push(request)
+      return reply
+    },
+    vars: { greeting: "hi" },
+    env: { testCommand: "npm test" },
+  } as unknown as FlowContext)
+  return requests
+}
+
+describe("human()", () => {
+  it("takes its message positionally, the rest as options", async () => {
+    const requests = recording()
+    await human("gate", "Sign off.", { acceptClean: true })
+    await human("plain", { message: "As before." })
+    await human("bare")
+    expect(requests.map((r) => (r.kind === "human" ? r.options : undefined))).toEqual([
+      { acceptClean: true, message: "Sign off." },
+      { message: "As before." },
+      {},
+    ])
+  })
+
+  it("types the positional form without a message option", () => {
+    expectTypeOf(human).toBeCallableWith("gate", "Sign off.")
+    expectTypeOf(human).toBeCallableWith("gate", { message: "m" } satisfies HumanOptions)
+    // @ts-expect-error -- the message is positional in this form
+    void (() => human("gate", "m", { message: "twice" }))
+  })
+})
+
+describe("judge()", () => {
+  const question = { id: "ok", instructions: "Is it?", criteria: "yes or no" } as const
+
+  it("hands a yesno question on as noul, and passes file, mode and base through", async () => {
+    const requests = recording({ answers: {}, truncated: [] })
+    await judge("judging", {
+      questions: [{ ...question, primitive: "yesno" }],
+      evidence: { a: "b" },
+      file: ".gtd/J.md",
+      mode: "qa",
+      base: "abc",
+      label: "Judging",
+    })
+    expect(requests).toEqual([
+      {
+        kind: "judge",
+        name: "judging",
+        questions: [{ ...question, primitive: "noul" }],
+        evidence: { a: "b" },
+        options: { file: ".gtd/J.md", mode: "qa", base: "abc", label: "Judging" },
+      },
+    ])
+  })
+
+  it("keys the answers by the question ids: a literal id allows only itself, a computed one any key", () => {
+    const judged = () =>
+      judge("j", {
+        questions: [
+          { ...question, primitive: "noul" },
+          { ...question, id: "shape", primitive: "choice" },
+        ],
+        evidence: {},
+      })
+    expectTypeOf(judged).returns.resolves.toEqualTypeOf<Judgment<"ok" | "shape">>()
+    expectTypeOf<Judgment<"ok">["answers"]>().toHaveProperty("ok")
+    // @ts-expect-error -- "nope" is no question's id
+    void ((j: Judgment<"ok">) => j.answers.nope)
+    const computed = (j: Judgment, id: string) => j.answers[id]
+    expectTypeOf(computed).returns.toEqualTypeOf<
+      { readonly answer: string; readonly p: number } | undefined
+    >()
+    const ids = ["a", "b"].map(
+      (i) => ({ ...question, id: `standard-${i}`, primitive: "noul" }) as const,
+    )
+    const judgedComputed = () => judge("k", { questions: ids, evidence: {} })
+    expectTypeOf(judgedComputed).returns.resolves.toEqualTypeOf<Judgment<`standard-${string}`>>()
+    expectTypeOf<Judgment<"ok">>().toMatchTypeOf<Judgment>()
+  })
+})
+
+describe("settings", () => {
+  it("read the replay's process and environment settings", () => {
+    recording()
+    expect(settings.greeting).toBe("hi")
+    expect(envSettings.testCommand).toBe("npm test")
+  })
+
+  it("settingsOf() types the declared names, reading the same settings", () => {
+    const defaults = { greeting: "hello" }
+    const envDefaults = { testCommand: "npm test" }
+    const typed = settingsOf(defaults)
+    const typedEnv = envSettingsOf(envDefaults)
+    recording()
+    expect(typed.greeting).toBe("hi")
+    expect(typedEnv.testCommand).toBe("npm test")
+    expectTypeOf(typed.greeting).toEqualTypeOf<string>()
+    expectTypeOf(typed).toEqualTypeOf<Settings<"greeting">>()
+    // @ts-expect-error -- not a declared name
+    void typed.greting
+  })
+
+  it("can be taken outside a replay, read inside one", () => {
+    expect(() => settingsOf({ a: "" })).not.toThrow()
+  })
+})
+
+describe("workflow()", () => {
+  it("returns a new marked flow that runs the one it is given, which stays unmarked", async () => {
+    let ran = 0
+    const flow = async function feature(): Promise<void> {
+      ran++
+    }
+    const marked = workflow(flow, { defaults: { a: "1" } })
+    expect(marked).not.toBe(flow)
+    expect(marked.name).toBe("feature")
+    expect(markedOptions(flow)).toBeUndefined()
+    expect(markedOptions(marked)).toEqual({ defaults: { a: "1" } })
+    await marked()
+    expect(ran).toBe(1)
+    expect(markedOptions(workflow(async () => {}))).toEqual({})
+    expect(markedOptions({})).toBeUndefined()
+  })
+
+  it("re-wraps a marked flow with the options it is given, the old ones not inherited", () => {
+    const library = workflow(async () => {}, { defaults: { a: "1" }, summary: () => "s" })
+    const mine = workflow(library, { envDefaults: { b: "2" } })
+    expect(markedOptions(mine)).toEqual({ envDefaults: { b: "2" } })
+    expect(markedOptions(library)).toEqual({ defaults: { a: "1" }, summary: expect.any(Function) })
+  })
+
+  it("takes a factory build's options, its flow aside", () => {
+    expectTypeOf(workflow).toBeCallableWith(async () => {}, {
+      defaults: { a: "1" },
+      envDefaults: { b: "2" },
+      steering: { ".gtd/A.md": "qa" },
+      skills: { build: ["x"] },
+      access: () => ({ build: { write: [] } }),
+      doors: { hot: { args: [{ name: "x" }] } },
+      base: () => undefined,
+      summary: () => "s",
+    })
+    // @ts-expect-error -- the flow is the first argument
+    void (() => workflow(async () => {}, { flow: async () => {} }))
+  })
+})
+
+describe("step options", () => {
+  it("reject the combinations replay refuses", () => {
+    expectTypeOf<{ file: ".gtd/A.md"; mode: "qa" }>().toMatchTypeOf<RunOptions>()
+    expectTypeOf<{ file: string | undefined }>().toMatchTypeOf<RunOptions>()
+    // @ts-expect-error -- mode requires file
+    expectTypeOf<{ mode: "qa" }>().toMatchTypeOf<RunOptions>()
+    expectTypeOf<{ approve: true; message: "m" }>().toMatchTypeOf<HumanOptions>()
+    // @ts-expect-error -- approve excludes file
+    expectTypeOf<{ approve: true; file: ".gtd/A.md" }>().toMatchTypeOf<HumanOptions>()
+    expectTypeOf<{ keep: true; allowEmpty: false }>().toMatchTypeOf<AgentOptions>()
+    // @ts-expect-error -- keep excludes allowEmpty
+    expectTypeOf<{ keep: true; allowEmpty: true }>().toMatchTypeOf<AgentOptions>()
+  })
+})
+
+describe("mode", () => {
+  it("names the built-in modes and still takes any string", () => {
+    expectTypeOf<"qa">().toMatchTypeOf<ModeName>()
+    expectTypeOf<string>().toMatchTypeOf<ModeName>()
+    expectTypeOf<ModeName>().toMatchTypeOf<string>()
+    expectTypeOf<SteeringOptions["mode"]>().toEqualTypeOf<ModeName | undefined>()
+  })
+})

package/src/flows/runtime.ts

@@ -3,52 +3,87 @@
 // a registered symbol, not a module-local variable, so a copy of this file
 // loaded through a user's `gtd.config.ts` (jiti) and the copy bundled into the
 // gtd binary drive the same replay.
+import type { WorkflowBuild } from "./factory.js"
 
-/** A steering-file declaration shared by the steps that rest on one. */
-export interface SteeringOptions {
-  /** The steering file — a repository path under `.gtd/`. */
-  readonly file?: string | undefined
-  /** The steering file's mode — a built-in name or a `modes:` entry. Requires `file`. */
-  readonly mode?: string | undefined
+/** A steering-file mode: a built-in format's name or a `config.modes` entry. */
+export type ModeName = "qa" | "review" | "findings" | (string & {})
+
+interface SteeringCommon {
   /** Display name for drivers and viewers. */
   readonly label?: string | undefined
   /** The commit this step reviews changes since — what `gtd base` prints while it rests here. */
   readonly base?: string | undefined
 }
 
-export interface AgentOptions extends SteeringOptions {
+/** A step's steering file: none, or a file with an optional mode. */
+type SteeringFile =
+  | {
+      /** The steering file — a repository path under `.gtd/`. */
+      readonly file?: string | undefined
+      readonly mode?: undefined
+    }
+  | {
+      readonly file: string
+      /** The steering file's mode — a built-in name or a `modes:` entry. Requires `file`. */
+      readonly mode: ModeName
+    }
+
+/** A steering-file declaration shared by the steps that rest on one. `mode` requires `file`. */
+export type SteeringOptions = SteeringCommon & SteeringFile
+
+interface AgentCommon {
   readonly model?: string | undefined
   readonly system?: string | undefined
-  /**
-   * A turn that changes nothing completes the step. Without this an empty turn
-   * is an attempt: recorded, but the process stays at the step (a stall).
-   */
-  readonly allowEmpty?: boolean | undefined
-  /**
-   * Set the turn aside: its tip goes to `refs/gtd/kept/<entry>/<step>/<hash>` and the
-   * branch stays where it was, a marker commit recording that the step ran.
-   * The step's full name must be usable as a git ref component.
-   */
-  readonly keep?: boolean | undefined
 }
 
-export interface HumanOptions extends SteeringOptions {
+export type AgentOptions = SteeringOptions &
+  AgentCommon &
+  (
+    | {
+        /**
+         * A turn that changes nothing completes the step. Without this an empty turn
+         * is an attempt: recorded, but the process stays at the step (a stall).
+         */
+        readonly allowEmpty?: boolean | undefined
+        readonly keep?: false | undefined
+      }
+    | {
+        /**
+         * Set the turn aside: its tip goes to `refs/gtd/kept/<entry>/<step>/<hash>` and the
+         * branch stays where it was, a marker commit recording that the step ran.
+         * The step's full name must be usable as a git ref component. Excludes `allowEmpty`.
+         */
+        readonly keep: true
+        readonly allowEmpty?: false | undefined
+      }
+  )
+
+interface HumanCommon {
   readonly message?: string | undefined
   /**
    * A landing that changes nothing completes the gate — accepting as-is.
    * Without this a clean landing is a no-op: the gate waits for a change.
    */
   readonly acceptClean?: boolean | undefined
-  /**
-   * A sign-off gate: only a clean landing completes it, and that commit
-   * carries `Gtd-Approved: {"step":"<step>#<n>","name":"<name>","email":"<email>"}`.
-   * A dirty landing is refused. Implies `acceptClean`. Cannot be combined with
-   * `mode` or `file`: an approval records exactly the judged tree.
-   */
-  readonly approve?: boolean | undefined
 }
 
-export interface RunOptions extends SteeringOptions {}
+export type HumanOptions = HumanCommon &
+  (
+    | (SteeringOptions & { readonly approve?: false | undefined })
+    | (SteeringCommon & {
+        /**
+         * A sign-off gate: only a clean landing completes it, and that commit
+         * carries `Gtd-Approved: {"step":"<step>#<n>","name":"<name>","email":"<email>"}`.
+         * A dirty landing is refused. Implies `acceptClean`. Excludes `mode` and
+         * `file`: an approval records exactly the judged tree.
+         */
+        readonly approve: true
+        readonly file?: undefined
+        readonly mode?: undefined
+      })
+  )
+
+export type RunOptions = SteeringOptions
 
 export type JudgePrimitive = "noul" | "choice" | "score"
 
@@ -59,24 +94,36 @@ export interface JudgeQuestion {
   readonly criteria: string
 }
 
-export interface JudgeSpec {
-  readonly questions: readonly JudgeQuestion[]
-  /** What the judge sees. The `judgeBudgetBytes` budget is split evenly across the keys; a value over its share keeps its end. */
-  readonly evidence: Readonly<Record<string, string>>
-  /** The human-facing message a driver unaware of judge gates shows. */
-  readonly message?: string | undefined
-  readonly label?: string | undefined
+/** A question as `judge()` takes it: `"yesno"` is another name for `"noul"`. */
+export interface JudgeQuestionInput<Id extends string = string> extends Omit<
+  JudgeQuestion,
+  "id" | "primitive"
+> {
+  readonly id: Id
+  readonly primitive: JudgePrimitive | "yesno"
 }
 
+export type JudgeSpec<Q extends readonly JudgeQuestionInput[] = readonly JudgeQuestion[]> =
+  SteeringOptions & {
+    readonly questions: Q
+    /** What the judge sees. The `judgeBudgetBytes` budget is split evenly across the keys; a value over its share keeps its end. */
+    readonly evidence: Readonly<Record<string, string>>
+    /** The human-facing message a driver unaware of judge gates shows. */
+    readonly message?: string | undefined
+  }
+
 /** One recorded answer. A `noul`'s boolean reads as `"yes"`/`"no"`, a `score` as its decimal string. */
 export interface JudgeAnswer {
   readonly answer: string
   readonly p: number
 }
 
-export interface Judgment {
-  /** Every question's answer, `undefined` when the turn landed without a verdict for it. */
-  readonly answers: Readonly<Record<string, JudgeAnswer | undefined>>
+export interface Judgment<Id extends string = string> {
+  /**
+   * Every question's answer, `undefined` when the turn landed without a verdict for it.
+   * Keyed by the question ids: literal ids allow only themselves, a computed id reads as any string.
+   */
+  readonly answers: Readonly<Record<Id, JudgeAnswer | undefined>>
   /** The evidence keys the budget cut. */
   readonly truncated: readonly string[]
 }
@@ -102,6 +149,22 @@ export interface ScopeAccess {
   readonly write?: readonly string[] | undefined
 }
 
+/** A workflow's `access` option: scope full name -> access, or a function of the process settings returning that. */
+export type AccessExport =
+  | Readonly<Record<string, ScopeAccess>>
+  | ((vars: Settings) => Readonly<Record<string, ScopeAccess>>)
+
+/** A workflow's `skills` option: scope full name -> skill names, or a function of the process settings returning that. */
+export type SkillsExport =
+  | Readonly<Record<string, readonly string[]>>
+  | ((vars: Settings) => Readonly<Record<string, readonly string[]>>)
+
+/** A workflow's `steering` option: steering file path -> its mode. */
+export type Steering = Readonly<Record<string, ModeName>>
+
+/** Settings as flow code reads them; `K` narrows to the names a workflow declares. */
+export type Settings<K extends string = string> = Readonly<Record<K, string>>
+
 /** A resolved access: `null` is an unrestricted side. */
 export interface AccessDef {
   readonly read: readonly string[] | null
@@ -247,18 +310,51 @@ const ctx = (): FlowContext => {
 export const agent = (name: string, prompt: string, options: AgentOptions = {}): Promise<void> =>
   ctx().step({ kind: "agent", name, prompt, options }) as Promise<void>
 
+// `Omit` over a union collapses it; this keeps each member's own rules.
+type OmitEach<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
+
+export interface Human {
+  /** `message` is what the person sees, so `options` take none. */
+  (name: string, message: string, options?: OmitEach<HumanOptions, "message">): Promise<void>
+  (name: string, options?: HumanOptions): Promise<void>
+}
+
 /** A human gate: the process rests until a person lands a turn. */
-export const human = (name: string, options: HumanOptions = {}): Promise<void> =>
-  ctx().step({ kind: "human", name, options }) as Promise<void>
+export const human: Human = (
+  name: string,
+  messageOrOptions?: string | HumanOptions,
+  options?: OmitEach<HumanOptions, "message">,
+): Promise<void> =>
+  ctx().step({
+    kind: "human",
+    name,
+    options:
+      typeof messageOrOptions === "string"
+        ? { ...options, message: messageOrOptions }
+        : (messageOrOptions ?? {}),
+  }) as Promise<void>
 
 /** A check: `body` runs at the edge and its effect on the tree is committed. */
 export const run = (name: string, body: string, options: RunOptions = {}): Promise<void> =>
   ctx().step({ kind: "run", name, body, options }) as Promise<void>
 
 /** A judge gate: resolves to what the judge answered, for the flow to decide on. */
-export const judge = (name: string, spec: JudgeSpec): Promise<Judgment> => {
+export const judge = <const Q extends readonly JudgeQuestionInput[] = readonly JudgeQuestion[]>(
+  name: string,
+  spec: JudgeSpec<Q>,
+): Promise<Judgment<Q[number]["id"]>> => {
   const { questions, evidence, ...options } = spec
-  return ctx().step({ kind: "judge", name, questions, evidence, options }) as Promise<Judgment>
+  // Normalized here, so the engine and every driver only ever see `noul`.
+  const canonical = questions.map((q) =>
+    q.primitive === "yesno" ? { ...q, primitive: "noul" as const } : (q as JudgeQuestion),
+  )
+  return ctx().step({
+    kind: "judge",
+    name,
+    questions: canonical,
+    evidence,
+    options,
+  }) as Promise<Judgment<Q[number]["id"]>>
 }
 
 /** End the episode from any depth. The next episode starts the flow afresh. */
@@ -380,7 +476,7 @@ export const mark = (name: string, value: string): void => {
 /** The commit the process stands on at this point of the flow. */
 export const head = (): string => ctx().head()
 
-/** The process's diff base: the commit before it began, or the base `gtd --workflow` fixed. */
+/** The process's diff base: the commit before it began, or the base `gtd start` fixed. */
 export const start = (): string => ctx().start()
 
 /** The skill list `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. */
@@ -407,14 +503,28 @@ const settingsProxy = (
   )
 
 /** The process settings: pinned at process start, so flow code may branch on them. */
-export const vars: Readonly<Record<string, string>> = settingsProxy(() => ctx().vars)
+export const settings: Settings = settingsProxy(() => ctx().vars)
 
 /**
  * The environment settings: resolved live on every invocation. Flow code must
  * read them only where they cannot change the next step (step options, script
  * bodies) — replay cannot enforce this.
  */
-export const env: Readonly<Record<string, string>> = settingsProxy(() => ctx().env)
+export const envSettings: Settings = settingsProxy(() => ctx().env)
+
+/**
+ * `settings`, typed by the names `declared` holds — pass the workflow's
+ * `defaults`. Every declared name resolves to a string, so none reads as
+ * possibly `undefined`, and a misspelled one is a type error.
+ */
+export const settingsOf = <D extends Readonly<Record<string, string>>>(
+  _declared: D,
+): Settings<keyof D & string> => settings as Settings<keyof D & string>
+
+/** `envSettings`, typed by the names `declared` holds — pass the workflow's `envDefaults`. */
+export const envSettingsOf = <D extends Readonly<Record<string, string>>>(
+  _declared: D,
+): Settings<keyof D & string> => envSettings as Settings<keyof D & string>
 
 // ── Text utilities ──────────────────────────────────────────────────────────
 
@@ -472,6 +582,33 @@ export const openQuestions = (text: string): readonly OpenQuestion[] => ctx().op
 /** A workflow's one flow. */
 export type Flow = () => Promise<void>
 
+// Registered, like the replay context: any copy of this file marks for the engine's.
+const MARKED = Symbol.for("@pmelab/gtd/workflow")
+
+/** What `workflow(flow, options)` takes: a factory build's keys but `flow`. */
+export type WorkflowOptions = Omit<WorkflowBuild, "flow">
+
+/**
+ * Make `flow` a workflow: exported from `gtd.config.ts`, it is startable by its
+ * export name. An exported function not passed through this is a plain helper.
+ * `options` are the ones a `defineWorkflow` build returns, checked the same way.
+ * Returns a new function that runs `flow`, leaving `flow` itself untouched, so
+ * an already-marked flow can be wrapped again: like a build, the options given
+ * are the whole set — the wrapped flow's own are not inherited.
+ */
+export const workflow = (flow: Flow, options: WorkflowOptions = {}): Flow => {
+  const marked: Flow = () => flow()
+  Object.defineProperty(marked, "name", { value: flow.name })
+  Object.defineProperty(marked, MARKED, { value: { ...options } })
+  return marked
+}
+
+/** The options `value` was marked with, or `undefined` when it went through no `workflow()`. */
+export const markedOptions = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === "function" && MARKED in value
+    ? (value as unknown as Record<symbol, Readonly<Record<string, unknown>>>)[MARKED]
+    : undefined
+
 export interface SummaryContext {
   readonly entryCommit: string
   readonly processBase: string
@@ -485,23 +622,23 @@ export interface SummaryContext {
   readonly env: Readonly<Record<string, string>>
 }
 
-/** `gtd summary`'s prompt — a workflow module's optional `summary` export. */
+/** `gtd summary`'s prompt — a workflow's optional `summary` option. */
 export type Summary = (context: SummaryContext) => string
 
 /**
- * A workflow file's optional `base` export: the commitish that fixes the diff
- * base of a process `gtd --workflow <workflow>` starts, or `undefined` for
- * none. Runs when the process is started, with the vars `--var` sets.
+ * A workflow's optional `base` option: the commitish that fixes the diff base
+ * of a process `gtd start <workflow>` starts, or `undefined` for none. Runs
+ * when the process is started, with the settings `--var` sets.
  */
 export type WorkflowBase = (
   workflow: string,
   vars: Readonly<Record<string, string>>,
 ) => string | undefined
 
-/** A named shortcut: `gtd door <name> [args…]` starts `workflow` with the positional args mapped to process settings. */
+/** A named shortcut: `gtd start <name> [args…]` starts `workflow` with the positional args mapped to process settings. */
 export interface Door {
   readonly workflow: string
-  /** Static, so `gtd doors --json` can list them. */
+  /** Static, so `gtd start --json` can list them. */
   readonly args?: readonly { readonly name: string; readonly optional?: boolean }[]
   /** A pure function of the args: no git runs at declaration time. */
   readonly vars?: (
@@ -509,8 +646,5 @@ export interface Door {
   ) => Readonly<Record<string, string>>
 }
 
-/** A workflow module's reserved `doors` export. */
-export type Doors = Readonly<Record<string, Door>>
-
-/** Doors a workflow factory declares on itself: each starts whatever name the config exports the workflow under. */
+/** Doors a workflow declares on itself: each starts whatever name the config exports the workflow under. */
 export type WorkflowDoors = Readonly<Record<string, Omit<Door, "workflow">>>

package/src/gherkin/git-control.feature

@@ -9,17 +9,17 @@ Feature: a scenario controls the commands and the history a workflow sees
   Background:
     Given a gtd config with:
       """
-      import { check, human, run, showScript } from "@pmelab/gtd/flows"
+      import { check, human, run, showScript, workflow } from "@pmelab/gtd/flows"
 
-      export const tested = async () => {
-        const green = await check("test", "npm test", { report: ".gtd/FEEDBACK.md" })
+      export const tested = workflow(async () => {
+        const green = await check("test", "npm test", ".gtd/FEEDBACK.md")
         await human(green ? "sign-off" : "red")
-      }
+      })
 
-      export const restored = async () => {
+      export const restored = workflow(async () => {
         await run("restore", showScript("origin/main", "a.txt", "a.txt"))
         await human("done")
-      }
+      })
 
       export default tested
       """