@pmelab/gtd 59.0.1 → 60.0.0

package/src/testkit/TestRepo.ts

@@ -10,6 +10,7 @@ import {
   type CapturedCliResult,
   type CommandTable,
 } from "../twins/index.js"
+import { importsFrom } from "./imports.js"
 
 /**
  * The repository's `gtd.config.ts`: its source, or the module itself. A module
@@ -40,26 +41,81 @@ export interface TestRepoOptions {
   readonly files?: Readonly<Record<string, string>>
   /** The environment gtd sees; the real `process.env` is never read, except ambient `GTD_FLAG_*` (explicit env wins). */
   readonly env?: Readonly<Record<string, string>>
+  /**
+   * Modules a config given as source imports by specifier, e.g.
+   * `{ "#workflow": await import("./index.ts") }`: its `import`/`export … from
+   * "#workflow"` reads the module the test imported.
+   */
+  readonly modules?: Readonly<Record<string, Readonly<Record<string, unknown>>>>
+  /** `false` keeps the runner's `GTD_FLAG_*` out too, so gtd sees `env` alone. Defaults to `true`. */
+  readonly ambientFlags?: boolean
+}
+
+/** One answer of a {@link Verdict}. */
+export interface VerdictEntry {
+  readonly id: string
+  readonly answer: boolean | string | number
+  readonly p: number
+}
+
+/** A judge step's verdict, as {@link verdict} builds it; an actor may return it in place of a JSON string. */
+export interface Verdict {
+  readonly answers: readonly VerdictEntry[]
 }
 
 /** What a scripted actor does at the step it is registered for, before the beat lands. */
-export type Actor = (beat: BeatDocument, repo: TestRepo) => void | string | Promise<void | string>
+export type ScriptedActor = (
+  beat: BeatDocument,
+  repo: TestRepo,
+) => void | string | Verdict | Promise<void | string | Verdict>
 
 /**
  * Scripted actors, keyed by full step name. At a judge step the actor returns
  * the verdict, which is answered through `gtd judge answer`; anywhere else it
  * edits the tree and the beat is landed.
  */
-export type Actors = Readonly<Record<string, Actor>>
+export type Actors = Readonly<Record<string, ScriptedActor>>
 
 export interface DriveOptions {
   /** Fail instead of looping forever on a workflow that never rests. */
   readonly maxBeats?: number
+  /**
+   * Defaults to `true`: fail on an actor whose step no drive of this
+   * repository has reached, a check step without an actor, a human step whose
+   * actor changes nothing (the drive would repeat it), and an actor returning a
+   * verdict anywhere but at a judge step. `false` lets each of them pass.
+   */
+  readonly strict?: boolean
+  /**
+   * `"pass"`: a strict drive skips only its check for actors no drive has
+   * reached, for a harness that checks that once at its own end, as the
+   * gherkin world does at scenario end.
+   */
+  readonly unreachedActors?: "fail" | "pass"
+  /** `"run"`: a check step without an actor runs its own script, as `runsItsScript` would. */
+  readonly checks?: "run"
+}
+
+/** A commit, as `TestRepo.commits` lists it. */
+export interface TestCommit {
+  readonly hash: string
+  readonly subject: string
+  /** The full message: subject, body and trailers. */
+  readonly message: string
+  /** The trailers of the message's last paragraph, each key's values in order. */
+  readonly trailers: Readonly<Record<string, readonly string[]>>
+}
+
+export interface RunScriptOptions {
+  /** Tried before the repository's own canned commands, for this run only. */
+  readonly commands?: readonly CannedCommand[]
 }
 
 export interface TestRepo {
   /** Adds a command a step's script may run, after those `testRepo` was given. */
   command(command: CannedCommand): void
+  /** Sets (or, with `undefined`, unsets) a variable gtd sees from the next call on. */
+  setEnv(name: string, value: string | undefined): void
   /** Creates branch `name` at `ref` (HEAD by default). Outside a process only. */
   branch(name: string, ref?: string): void
   /** Checks branch `name` out; refuses with uncommitted changes. Outside a process only. */
@@ -79,12 +135,12 @@ export interface TestRepo {
    * script helpers emit are understood; anything else (a test suite, a git
    * write) throws, and the step needs an actor that stands in for it.
    */
-  runScript(script: string): void
+  runScript(script: string, options?: RunScriptOptions): void
   /** One in-process invocation; nothing it prints is run. */
   gtd(...args: string[]): Promise<CapturedCliResult>
-  /** `gtd --workflow <name> [...args]`, its script applied. */
-  start(workflow: string, ...args: string[]): Promise<CapturedCliResult>
-  /** `gtd door <name> [...args]`, its script applied. */
+  /** `gtd start <name> [...args]`, its script applied: a door of that name, or else the workflow. */
+  start(name: string, ...args: string[]): Promise<CapturedCliResult>
+  /** The same as {@link TestRepo.start}. */
   door(name: string, ...args: string[]): Promise<CapturedCliResult>
   land(): Promise<CapturedCliResult>
   next(): Promise<BeatDocument>
@@ -102,6 +158,8 @@ export interface TestRepo {
   messages(): readonly string[]
   /** Every commit's full hash, oldest first. */
   hashes(): readonly string[]
+  /** Every commit, oldest first. */
+  commits(): readonly TestCommit[]
 }
 
 const REGISTRY = Symbol.for("@pmelab/gtd/testkit:modules")
@@ -114,11 +172,12 @@ const registry = (): Registry => {
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/
 let registered = 0
 
+const lookup = (key: string): string =>
+  `globalThis[Symbol.for(${JSON.stringify(REGISTRY.description)})].get(${JSON.stringify(key)})`
+
 /** A config whose exports are module `id`'s, read off the registry when the engine loads it. */
 const moduleSource = (id: string, module: Readonly<Record<string, unknown>>): string => {
-  const lines = [
-    `const m = globalThis[Symbol.for(${JSON.stringify(REGISTRY.description)})].get(${JSON.stringify(id)})`,
-  ]
+  const lines = [`const m = ${lookup(id)}`]
   for (const name of Object.keys(module)) {
     if (name === "default") lines.push(`export default m.default`)
     else if (IDENTIFIER.test(name)) lines.push(`export const ${name} = m[${JSON.stringify(name)}]`)
@@ -128,7 +187,71 @@ const moduleSource = (id: string, module: Readonly<Record<string, unknown>>): st
 }
 
 /** An actor that runs the step's own script, for steps whose script `runScript` understands. */
-export const runsItsScript: Actor = (beat, repo) => repo.runScript(beat.content)
+export const runsItsScript: ScriptedActor = (beat, repo) => repo.runScript(beat.content)
+
+/**
+ * A judge's verdict, keyed by question id: `verdict({ ready: true })`, or with
+ * a confidence, `verdict({ ready: { answer: true, p: 0.6 } })`. `p` defaults to 0.9.
+ */
+export const verdict = (
+  answers: Readonly<
+    Record<
+      string,
+      VerdictEntry["answer"] | { readonly answer: VerdictEntry["answer"]; readonly p?: number }
+    >
+  >,
+): Verdict => ({
+  answers: Object.entries(answers).map(([id, entry]) =>
+    typeof entry === "object"
+      ? { id, answer: entry.answer, p: entry.p ?? 0.9 }
+      : { id, answer: entry, p: 0.9 },
+  ),
+})
+
+/** `actor`, at a visit whose beat content contains `text`; any other visit changes nothing. */
+export const whenPrompted =
+  (text: string, actor: ScriptedActor): ScriptedActor =>
+  (beat, repo) =>
+    beat.content.includes(text) ? actor(beat, repo) : undefined
+
+/** Each actor in order, at every visit; the first verdict any of them returns is the result. */
+export const inTurn =
+  (actors: readonly ScriptedActor[]): ScriptedActor =>
+  async (beat, repo) => {
+    let result: string | Verdict | undefined
+    for (const actor of actors) {
+      const returned = await actor(beat, repo)
+      if (result === undefined && returned !== undefined) result = returned as string | Verdict
+    }
+    return result
+  }
+
+/** At a judge step, `answer` when the pending questions (as `gtd judge` prints them) contain `text`. */
+export const verdictWhen =
+  (text: string, answer: string | Verdict): ScriptedActor =>
+  async (_, repo) => {
+    const { stdout } = await repo.gtd("judge")
+    return stdout.includes(text) ? answer : undefined
+  }
+
+const isVerdict = (value: unknown): value is Verdict =>
+  typeof value === "object" &&
+  value !== null &&
+  Array.isArray((value as { answers?: unknown }).answers)
+
+const TRAILER = /^([A-Za-z0-9][A-Za-z0-9-]*): ?(.*)$/
+
+const trailersOf = (message: string): Record<string, string[]> => {
+  const paragraphs = message.trimEnd().split(/\n\s*\n/)
+  const last = paragraphs.length > 1 ? paragraphs.at(-1)!.split("\n") : []
+  const trailers: Record<string, string[]> = {}
+  if (last.length === 0 || !last.every((line) => TRAILER.test(line))) return trailers
+  for (const line of last) {
+    const [, key, value] = TRAILER.exec(line)!
+    ;(trailers[key!] ??= []).push(value!)
+  }
+  return trailers
+}
 
 const words = (text: string): string[] =>
   [...text.matchAll(/'((?:[^']|'\\'')*)'/g)].map((m) => m[1]!.replaceAll("'\\''", "'"))
@@ -228,39 +351,112 @@ const expectedVerdict = (doc: BeatDocument): string => {
   ].join("\n")
 }
 
+const quoted = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(", ")
+
+/** Who acts at `doc`: its scripted actor, or a check's own script under `checks: "run"`. A stall has none. */
+const actorAt = (
+  doc: BeatDocument,
+  actors: Actors,
+  checks: DriveOptions["checks"],
+): { readonly scripted: boolean; readonly actor: ScriptedActor | undefined } => {
+  if (doc.kind === "stalled") return { scripted: false, actor: undefined }
+  if (Object.hasOwn(actors, doc.state)) return { scripted: true, actor: actors[doc.state] }
+  const runs = checks === "run" && doc.actor === "check"
+  return { scripted: false, actor: runs ? runsItsScript : undefined }
+}
+
+/** A strict drive's rest: refused at an unscripted check step, or with an actor no drive reached. */
+const strictRest = (
+  doc: BeatDocument,
+  actors: Actors,
+  reached: ReadonlySet<string> | undefined,
+): BeatDocument => {
+  if (doc.kind !== "stalled" && doc.actor === "check") {
+    throw new Error(
+      `strict drive: check step "${doc.state}" has no actor — script it, or drive with checks: "run"`,
+    )
+  }
+  const never =
+    reached === undefined ? [] : Object.keys(actors).filter((step) => !reached.has(step))
+  if (never.length > 0) {
+    throw new Error(
+      `strict drive: the process rests at "${doc.state}", and never reached the actors for ${quoted(never)} — script a step only for the drive that reaches it`,
+    )
+  }
+  return doc
+}
+
+const refuseVerdict = (doc: BeatDocument, returned: unknown): void => {
+  if (doc.actor !== "judge" && returned !== undefined) {
+    throw new Error(
+      `strict drive: the actor for ${doc.actor} step "${doc.state}" returned a verdict; only a judge step takes one`,
+    )
+  }
+}
+
+const refuseNothingLanded = (doc: BeatDocument, nothing: boolean): void => {
+  if (doc.actor === "human" && nothing) {
+    throw new Error(
+      `strict drive: the actor for human step "${doc.state}" changed nothing, so nothing landed and the drive would repeat the step`,
+    )
+  }
+}
+
 export const testRepo = (options: TestRepoOptions): TestRepo => {
   const repo = new InMemRepo()
-  const env = { ...options.env }
+  const env: Record<string, string | undefined> = { ...options.env }
   const { workflow } = options
   const id = `module-${++registered}`
+  const modules = Object.entries(options.modules ?? {})
+  const moduleKey = (specifier: string): string => `${id}:${specifier}`
   repo.writeFile(
     "gtd.config.ts",
-    typeof workflow === "string" ? workflow : moduleSource(id, workflow),
+    typeof workflow !== "string"
+      ? moduleSource(id, workflow)
+      : modules.length === 0
+        ? workflow
+        : importsFrom(workflow, options.modules!, (specifier) => lookup(moduleKey(specifier))),
   )
   for (const [path, content] of Object.entries(options.files ?? {})) repo.writeFile(path, content)
   repo.seedCommit("chore: initial commit")
 
   const canned = [...(options.commands ?? [])]
-  const commands: CommandTable = {
+  const table = (first: readonly CannedCommand[] = []): CommandTable => ({
     get: (command) => {
-      const hit = canned.find(({ run }) =>
+      const hit = [...first, ...canned].find(({ run }) =>
         typeof run === "string" ? run === command : run.test(command),
       )
       if (hit === undefined) return undefined
       const { exit = 0, output = "", effect } = hit
       return { kind: "exit", status: exit, output, effect: () => effect?.(self) }
     },
-  }
+  })
+  const commands = table()
+
+  // An `undefined` entry masks the ambient flag the in-memory host would add.
+  const seenEnv = (): Readonly<Record<string, string | undefined>> =>
+    options.ambientFlags === false
+      ? {
+          ...Object.fromEntries(
+            Object.keys(process.env)
+              .filter((name) => name.startsWith("GTD_FLAG_"))
+              .map((name) => [name, undefined]),
+          ),
+          ...env,
+        }
+      : env
 
-  // The module is registered only while gtd runs, so nothing outlives the
-  // call that loads it and no test can reach another's module.
+  // The modules are registered only while gtd runs, so nothing outlives the
+  // call that loads them and no test can reach another's module.
   const gtd = async (...args: string[]): Promise<CapturedCliResult> => {
-    const { io, result } = makeCapturingCliIo(repo, env)
+    const { io, result } = makeCapturingCliIo(repo, seenEnv())
     if (typeof workflow !== "string") registry().set(id, workflow)
+    for (const [specifier, module] of modules) registry().set(moduleKey(specifier), module)
     try {
       await Effect.runPromise(runCli(["node", "gtd", ...args], io))
     } finally {
       registry().delete(id)
+      for (const [specifier] of modules) registry().delete(moduleKey(specifier))
     }
     return result()
   }
@@ -299,7 +495,7 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     return reported
   }
 
-  // A start prints its script plainly; it has no `--json=script` twin.
+  // A start prints its script plainly.
   const begin = async (args: readonly string[]): Promise<CapturedCliResult> => {
     const result = await gtd(...args)
     if (result.exitCode !== EXIT_OK) throw failed(`gtd ${args.join(" ")}`, result)
@@ -314,35 +510,67 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
   }
 
   /** Lands what an actor did: a judge's verdict answered, anything else validated and landed. */
-  const act = async (doc: BeatDocument, verdict: unknown): Promise<void> => {
+  const act = async (doc: BeatDocument, returned: unknown): Promise<void> => {
     if (doc.actor !== "judge") {
       if (doc.validate !== undefined) apply(`validating ${doc.file ?? doc.state}`, doc.validate)
       await runWrite(["land"])
       return
     }
     const actor = `the actor for judge step "${doc.state}"`
-    if (verdict === undefined) {
+    if (returned === undefined) {
       throw new Error(`${actor} returned no verdict\n${expectedVerdict(doc)}`)
     }
-    if (typeof verdict !== "string") {
+    const sent = isVerdict(returned) ? JSON.stringify(returned.answers) : returned
+    if (typeof sent !== "string") {
       throw new Error(
-        `${actor} returned ${Array.isArray(verdict) ? "an array" : typeof verdict === "object" ? "an object" : `a ${typeof verdict}`}, not a JSON string — JSON.stringify it\n${expectedVerdict(doc)}`,
+        `${actor} returned ${Array.isArray(sent) ? "an array" : typeof sent === "object" ? "an object" : `a ${typeof sent}`}, not a JSON string — JSON.stringify it\n${expectedVerdict(doc)}`,
       )
     }
     await runWrite(
       ["judge", "answer"],
-      verdict,
+      sent,
       (error) =>
         new Error(
-          `${actor} sent a verdict gtd refused:\n${verdict}\n${expectedVerdict(doc)}\n${error.message}`,
+          `${actor} sent a verdict gtd refused:\n${sent}\n${expectedVerdict(doc)}\n${error.message}`,
         ),
     )
   }
 
+  // Across drives, so a later drive need not revisit a step an earlier one passed.
+  const reached = new Set<string>()
+
+  /** One beat of a drive: the beat it rests at, or `undefined` to read the next. */
+  const beat = async (
+    doc: BeatDocument,
+    actors: Actors,
+    { strict = true, checks, unreachedActors = "fail" }: DriveOptions,
+  ): Promise<BeatDocument | undefined> => {
+    if (doc.kind === "capture") {
+      await runWrite(["land"])
+      return undefined
+    }
+    const { scripted, actor } = actorAt(doc, actors, checks)
+    if (actor === undefined)
+      return strict
+        ? strictRest(doc, actors, unreachedActors === "fail" ? reached : undefined)
+        : doc
+    if (scripted) reached.add(doc.state)
+    const returned = await actor(doc, self)
+    if (strict) refuseVerdict(doc, returned)
+    const before = repo.commitHistory().length
+    await act(doc, returned)
+    if (strict) refuseNothingLanded(doc, repo.commitHistory().length === before)
+    return undefined
+  }
+
   const self: TestRepo = {
     command: (command) => {
       canned.push(command)
     },
+    setEnv: (name, value) => {
+      if (value === undefined) delete env[name]
+      else env[name] = value
+    },
     branch: (name, ref = "HEAD") => repo.createBranch(name, ref),
     checkout: (name) => repo.checkoutBranch(name),
     ref: (name, ref = "HEAD") => {
@@ -357,29 +585,25 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     remove: (path) => repo.deleteFile(path),
     commit: (message) => repo.seedCommit(message),
     show: (ref, path) => repo.fileAtRef(ref, path) ?? undefined,
-    runScript: (script) => {
-      const flow = applyFlowScript(repo, commands, script)
-      if (flow === undefined) runLines(repo, commands, script)
+    runScript: (script, { commands: first = [] } = {}) => {
+      const scriptCommands = first.length === 0 ? commands : table(first)
+      const flow = applyFlowScript(repo, scriptCommands, script)
+      if (flow === undefined) runLines(repo, scriptCommands, script)
       else if (!flow.ok) throw new Error(`testkit: ${flow.error ?? ""}`)
     },
     gtd,
-    start: (workflow, ...args) => begin(["--workflow", workflow, ...args]),
-    door: (name, ...args) => begin(["door", name, ...args]),
+    start: (name, ...args) => begin(["start", name, ...args]),
+    door: (name, ...args) => begin(["start", name, ...args]),
     land: () => runWrite(["land"]),
     next,
-    drive: async (actors = {}, { maxBeats = 50 } = {}) => {
+    drive: async (actors = {}, options = {}) => {
+      const { maxBeats = 50 } = options
       const passed: string[] = []
-      for (let beat = 0; beat < maxBeats; beat++) {
+      for (let n = 0; n < maxBeats; n++) {
         const doc = await next()
         passed.push(doc.state)
-        if (doc.kind === "stalled") return doc
-        if (doc.kind === "capture") {
-          await runWrite(["land"])
-          continue
-        }
-        const actor = actors[doc.state]
-        if (actor === undefined) return doc
-        await act(doc, await actor(doc, self))
+        const rest = await beat(doc, actors, options)
+        if (rest !== undefined) return rest
       }
       throw new Error(
         `the process did not rest within ${maxBeats} beats; it passed through:\n${passed.join(" → ")}`,
@@ -388,6 +612,13 @@ export const testRepo = (options: TestRepoOptions): TestRepo => {
     subjects: () => repo.commitHistory().map(({ message }) => message.split("\n")[0] ?? ""),
     messages: () => repo.commitHistory().map(({ message }) => message),
     hashes: () => repo.commitHistory().map(({ hash }) => hash),
+    commits: () =>
+      repo.commitHistory().map(({ hash, message }) => ({
+        hash,
+        subject: message.split("\n")[0] ?? "",
+        message,
+        trailers: trailersOf(message),
+      })),
   }
   return self
 }

package/src/testkit/imports.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest"
+import { importsFrom } from "./imports.js"
+
+const lookup = (specifier: string): string => `REG(${JSON.stringify(specifier)})`
+const mod = { default: 1, a: 2, b: 3 }
+const rewrite = (source: string): string => importsFrom(source, { "#w": mod }, lookup)
+
+describe("importsFrom", () => {
+  it("binds named, renamed, default and namespace imports", () => {
+    expect(rewrite(`import d, { a, b as c, type T } from "#w"\nimport * as ns from '#w';`)).toBe(
+      [
+        `const __testkit_module_1 = REG("#w")`,
+        `const d = __testkit_module_1["default"]`,
+        `const a = __testkit_module_1["a"]`,
+        `const c = __testkit_module_1["b"]`,
+        `const __testkit_module_2 = REG("#w")`,
+        `const ns = __testkit_module_2`,
+      ].join("\n"),
+    )
+  })
+
+  it("re-exports by name, as default, as a namespace and wholesale", () => {
+    expect(
+      rewrite(
+        `export {\n  a as default,\n  b,\n} from "#w"\nexport * as ns from "#w"\nexport * from "#w"`,
+      ),
+    ).toBe(
+      [
+        `const __testkit_module_1 = REG("#w")`,
+        `export default __testkit_module_1["a"]`,
+        `export const b = __testkit_module_1["b"]`,
+        `const __testkit_module_2 = REG("#w")`,
+        `export const ns = __testkit_module_2`,
+        `const __testkit_module_3 = REG("#w")`,
+        `export const a = __testkit_module_3["a"]`,
+        `export const b = __testkit_module_3["b"]`,
+      ].join("\n"),
+    )
+  })
+
+  it("drops type-only and bare imports, and leaves every other specifier alone", () => {
+    const other = `import { agent } from "@pmelab/gtd/flows"\nexport default agent`
+    expect(rewrite(`import type { T } from "#w"\nimport "#w"\n${other}`)).toBe(`\n\n${other}`)
+  })
+
+  it("never reads a statement across the code before it", () => {
+    const source = `export default tiny\nimport { a } from "#w"`
+    expect(rewrite(source)).toBe(
+      `export default tiny\nconst __testkit_module_1 = REG("#w")\nconst a = __testkit_module_1["a"]`,
+    )
+  })
+
+  it("refuses a name the module does not export", () => {
+    expect(() => rewrite(`import { nope } from "#w"`)).toThrow(
+      'testkit: module "#w" has no export "nope"',
+    )
+  })
+})

package/src/testkit/imports.ts

@@ -0,0 +1,102 @@
+type Module = Readonly<Record<string, unknown>>
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/
+
+// Static `import`/`export … from` and bare `import "…"` statements, each
+// starting a line. A clause holds names, `*`, commas and one brace group, and
+// breaks lines only inside the braces, so a match cannot run past its statement.
+const STATEMENT =
+  /^[ \t]*(import|export)([ \t]+type)?[ \t]+([\w$* \t,]*(?:\{[^}]*\})?[\w$* \t,]*?)\s*\bfrom\s*(["'])([^"'\n]+)\4[ \t]*;?|^[ \t]*import\s*(["'])([^"'\n]+)\6[ \t]*;?/gm
+
+interface Binding {
+  readonly name: string
+  readonly as: string
+}
+
+const bindings = (list: string): Binding[] =>
+  list
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "" && !entry.startsWith("type "))
+    .map((entry) => {
+      const [name, as] = entry.split(/\s+as\s+/)
+      return { name: name!, as: as ?? name! }
+    })
+
+const exportLine = (as: string, value: string): string =>
+  as === "default" ? `export default ${value}` : `export const ${as} = ${value}`
+
+type Read = (name: string) => string
+
+const exportLines = (module: Module, m: string, read: Read, head: string, braces?: string) => {
+  if (braces !== undefined) return bindings(braces).map((b) => exportLine(b.as, read(b.name)))
+  if (/^\*\s+as\s+/.test(head)) return [exportLine(head.replace(/^\*\s+as\s+/, ""), m)]
+  return Object.keys(module)
+    .filter((name) => name !== "default" && IDENTIFIER.test(name))
+    .map((name) => exportLine(name, read(name)))
+}
+
+const importLines = (m: string, read: Read, head: string, braces?: string): string[] => [
+  ...head
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part !== "")
+    .map((part) =>
+      part.startsWith("*")
+        ? `const ${part.replace(/^\*\s+as\s+/, "")} = ${m}`
+        : `const ${part} = ${read("default")}`,
+    ),
+  ...(braces === undefined ? [] : bindings(braces).map((b) => `const ${b.as} = ${read(b.name)}`)),
+]
+
+/**
+ * `source` with each import or re-export of a specifier in `modules` reading
+ * that module off `lookup(specifier)`, an expression evaluated when the
+ * config runs. A string config is evaluated in memory, where no resolver
+ * knows the specifier, so the binding is made by hand.
+ */
+export const importsFrom = (
+  source: string,
+  modules: Readonly<Record<string, Module>>,
+  lookup: (specifier: string) => string,
+): string => {
+  let n = 0
+  const rewrite = (kind: string, clause: string, specifier: string, module: Module): string => {
+    const m = `__testkit_module_${++n}`
+    const read: Read = (name) => {
+      if (!(name in module))
+        throw new Error(`testkit: module "${specifier}" has no export "${name}"`)
+      return `${m}[${JSON.stringify(name)}]`
+    }
+    const text = clause.trim()
+    const braces = /\{([^}]*)\}/.exec(text)?.[1]
+    const head = text
+      .replace(/\{[^}]*\}/, "")
+      .replace(/,\s*$/, "")
+      .trim()
+    const lines =
+      kind === "export"
+        ? exportLines(module, m, read, head, braces)
+        : importLines(m, read, head, braces)
+    return [`const ${m} = ${lookup(specifier)}`, ...lines].join("\n")
+  }
+  return source.replace(
+    STATEMENT,
+    (
+      statement,
+      kind: string | undefined,
+      typeOnly: string | undefined,
+      clause: string | undefined,
+      _q: string | undefined,
+      from: string | undefined,
+      _bq: string | undefined,
+      bare: string | undefined,
+    ) => {
+      const specifier = from ?? bare!
+      const module = modules[specifier]
+      if (module === undefined) return statement
+      if (typeOnly !== undefined || bare !== undefined) return ""
+      return rewrite(kind!, clause!, specifier, module)
+    },
+  )
+}

package/src/testkit/index.test.ts

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

package/src/testkit/index.ts

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