@pmelab/gtd 59.0.1 → 60.0.0

package/src/steering/SteeringFormats.test.ts

@@ -5,7 +5,7 @@ import {
   parseFootnotes,
   parseThreads,
   steeringFormatFor,
-} from "./index.js"
+} from "./internal.js"
 
 const QA_FORMAT = steeringFormatFor("qa")!
 const REVIEW_FORMAT = steeringFormatFor("review")!

package/src/steering/freeform.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { freeFormFormat } from "./freeform.js"
-import { BUILT_IN_MODE_NAMES, steeringFormatFor } from "./index.js"
+import { BUILT_IN_MODE_NAMES, steeringFormatFor } from "./internal.js"
 
 /** Applies edits back-to-front — a local copy of the file's own splice pattern, mirroring `qa.test.ts`/`review.test.ts`'s identical helper. */
 const applyEdits = (

package/src/steering/index.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest"
-import { BUILT_IN_MODE_NAMES, steeringFormatFor, unansweredQuestions, viewOf } from "./index.js"
+import * as published from "./index.js"
+import { BUILT_IN_MODE_NAMES, steeringFormatFor, unansweredQuestions, viewOf } from "./internal.js"
 
 const qa = steeringFormatFor("qa")!
 const review = steeringFormatFor("review")!
@@ -60,3 +61,28 @@ describe("viewOf", () => {
     expect(view.documentLinks[0]!.line).toBe(0)
   })
 })
+
+describe("@pmelab/gtd/steering", () => {
+  it("publishes no engine-only name, nor a duplicate of the pure text reads", () => {
+    for (const name of [
+      "FOOTNOTE_ACTION_TITLE",
+      "THREAD_REPLY_ACTION_TITLE",
+      "getParseCount",
+      "BUILT_IN_MODE_NAMES",
+      "steeringFormatOrFreeForm",
+      "viewOf",
+      "headingSections",
+      "headingSectionBodies",
+      "unansweredQuestions",
+    ]) {
+      expect(published, name).not.toHaveProperty(name)
+    }
+  })
+
+  it("publishes the pure text reads a flow also has", () => {
+    expect(published.sections("## A\n\n## B\n")).toEqual(["A", "B"])
+    expect(typeof published.threads).toBe("function")
+    expect(typeof published.openQuestions).toBe("function")
+    expect(typeof published.sectionBodies).toBe("function")
+  })
+})

package/src/steering/index.ts

@@ -1,14 +1,6 @@
-import type {
-  SteeringAction,
-  SteeringFormat,
-  SteeringLink,
-  SteeringOutlineNode,
-  SteeringPointer,
-} from "./SteeringFormat.js"
+// `@pmelab/gtd/steering`, listed name by name. gtd's own code imports
+// `./internal.js`, which adds what only the engine, the LSP and `gtd ui` use.
 export { formatFinding } from "./SteeringFormat.js"
-import { qaDescriptor } from "./qa.js"
-import { reviewDescriptor } from "./review.js"
-import { findingsDescriptor } from "./findings.js"
 export { findingEntries, FIX_BOX, NOISE_HEADING, type FindingEntry } from "./findings.js"
 export {
   ANSWER_FIX,
@@ -30,11 +22,7 @@ export { applySteeringEdits } from "./Edits.js"
 
 export type { InlineNode } from "./Inline.js"
 
-// The free-form format: the mode-less/unregistered-mode FALLBACK —
-// deliberately not a `REGISTRY` entry of its own, since it is never a mode a
-// `mode:` key names.
-import { freeFormFormat } from "./freeform.js"
-export { freeFormFormat }
+export { freeFormFormat } from "./freeform.js"
 
 export type {
   BlockListItem,
@@ -50,15 +38,7 @@ export type {
   SteeringViewThread,
 } from "./SteeringFormat.js"
 
-/** The built-in registry: mode name → its format, in registry order. The single place the built-in formats are wired into names — everything else in this module dispatches over a resolved `SteeringFormat`, never a mode-name string. */
-const REGISTRY: ReadonlyMap<string, SteeringFormat> = new Map([
-  ["qa", qaDescriptor],
-  ["review", reviewDescriptor],
-  ["findings", findingsDescriptor],
-])
-
-/** Every built-in format name, in registry order. */
-export const BUILT_IN_MODE_NAMES: readonly string[] = [...REGISTRY.keys()]
+export { openThreads, steeringFormatFor } from "./registry.js"
 
 // The two `qa` primitives the phone client itself needs: `src/web/screens/
 // Question.tsx` renders the free-text slot and derives answeredness in the
@@ -66,93 +46,15 @@ export const BUILT_IN_MODE_NAMES: readonly string[] = [...REGISTRY.keys()]
 // with — a second copy there would drift silently.
 export { FREE_TEXT_PLACEHOLDER, isAnswered } from "./qa.js"
 
-// `ModeContradiction.ts`'s round-trip check re-parses a formatted sample's
-// footnotes to prove the formatter moved none of them — the one consumer
-// outside this package that needs the footnote parser itself, not a format.
 export {
   parseFootnotes,
   parseThreads,
   parseThreadsWithFindings,
   openThreadFindings,
-  FOOTNOTE_ACTION_TITLE,
-  THREAD_REPLY_ACTION_TITLE,
 } from "./Footnotes.js"
 
-// Test-observability only: the memo-hit counter is the one way "one parse per
-// document" is assertable from outside `MarkdownTree.ts` — timing is not.
-export { getParseCount } from "./MarkdownTree.js"
-
-// A flow's `sections()` is the one caller outside this package.
-export { headingSectionBodies, headingSections } from "./MarkdownTree.js"
-
-/** The built-in `SteeringFormat` registered under `mode`'s name, or `undefined` when it isn't a built-in mode at all. The one place a bare mode-name string is ever looked up — every consumer takes the RESOLVED value this returns, never a name, so "mode is required, never inferred from a file's basename" is a type, not a rule to remember. */
-export const steeringFormatFor = (mode: string): SteeringFormat | undefined => REGISTRY.get(mode)
-
-/**
- * The ui boundary's own resolution: `mode`'s registered format, or
- * `freeFormFormat` when `mode` is absent or names nothing in `REGISTRY` —
- * never `undefined`. `resolveMode` (`SteeringMode.ts`) stays on
- * `steeringFormatFor` alone, so a workflow naming a mode nothing defines
- * still fails to compile; this fallback is deliberately reachable only from
- * `src/ui/View.ts` and `src/ui/Write.ts`, where a mode-less/unknown-mode
- * document must still render and accept a paragraph note, never refuse.
- */
-export const steeringFormatOrFreeForm = (mode: string | undefined): SteeringFormat =>
-  (mode !== undefined ? REGISTRY.get(mode) : undefined) ?? freeFormFormat
-
-/**
- * `qa`-only: every OPEN question in `content` not yet answered, as
- * `{ question, headingLine }` pairs — enough for a refusal message ("which
- * question", "where"). Semantically distinct from `validate`'s findings:
- * a document can be perfectly well-formed (zero findings) while still having
- * open questions nobody has answered, which is the whole point of the
- * answer-completeness gate this feeds. Format-parameterised like everything
- * else here: `review` (or any future format with no such concept) yields
- * `[]` rather than this being a `qa`-specific function some caller has to
- * know not to call on the wrong format.
- */
-export const unansweredQuestions = (
-  format: SteeringFormat,
-  content: string,
-): readonly { readonly question: string; readonly headingLine: number }[] =>
-  format.unansweredQuestions?.(content) ?? []
-
-/**
- * Every positional thing an editor (the LSP, in a later pass) needs for one
- * document, off ONE `viewOf` call rather than four separate ones re-deriving
- * ranges each time: `outline` and `documentLinks` are already fully resolved
- * (each node/link carries its own range — see `SteeringOutlineNode`/
- * `SteeringLink`), while `pointerAt`/`actionsAt` stay closures over `content`
- * because they need a cursor position/selection range the caller supplies
- * per request. `Lsp.ts` reads its ranges straight off `outline`/`documentLinks`.
- */
-export interface SteeringEditorView {
-  readonly outline: readonly SteeringOutlineNode[]
-  readonly documentLinks: readonly SteeringLink[]
-  readonly pointerAt: (position: {
-    readonly line: number
-    readonly character: number
-  }) => SteeringPointer | undefined
-  readonly actionsAt: (range: {
-    readonly start: { readonly line: number; readonly character: number }
-    readonly end: { readonly line: number; readonly character: number }
-  }) => readonly SteeringAction[]
-}
-
-/** Builds `format`'s `SteeringEditorView` of `content` — see `SteeringEditorView`'s own doc for why this is one value, not several. Distinct from `SteeringView` (`SteeringFormat.ts`), which is the format's own node tree the phone client renders. */
-export const viewOf = (format: SteeringFormat, content: string): SteeringEditorView => ({
-  outline: format.outline(content),
-  documentLinks: format.documentLinks ? format.documentLinks(content) : [],
-  pointerAt: (position) => format.pointerAt?.(content, position),
-  actionsAt: (range) => format.actions(content, range),
-})
-
-/** Every OPEN thread — last entry is the agent's — as `{ name, line, firstMe }` (0-based line). `[]` for a format with no thread concept. */
-export const openThreads = (
-  format: SteeringFormat,
-  content: string,
-): readonly { readonly name: string; readonly line: number; readonly firstMe: string }[] =>
-  format.openThreads?.(content) ?? []
+// The pure counterparts of `@pmelab/gtd/flows`' text reads, usable outside a replay.
+export { openQuestions, sectionBodies, sections, threads } from "./reads.js"
 
 // Line-comment `H:`/`A:` threads in changed code files: a flow's `codeThreads()`
 // and `gtd check --open-threads` are the callers outside this package.

package/src/steering/internal.ts

@@ -0,0 +1,11 @@
+// gtd's own imports of the steering formats: everything public, plus what only
+// the engine, the LSP and `gtd ui` use.
+export * from "./index.js"
+export { FOOTNOTE_ACTION_TITLE, THREAD_REPLY_ACTION_TITLE } from "./Footnotes.js"
+export { getParseCount, headingSectionBodies } from "./MarkdownTree.js"
+export {
+  BUILT_IN_MODE_NAMES,
+  steeringFormatOrFreeForm,
+  unansweredQuestions,
+  viewOf,
+} from "./registry.js"

package/src/steering/qa.test.ts

@@ -1,7 +1,12 @@
 import { describe, expect, it } from "vitest"
-import { FOOTNOTE_ACTION_TITLE, steeringFormatFor, unansweredQuestions, viewOf } from "./index.js"
+import {
+  FOOTNOTE_ACTION_TITLE,
+  steeringFormatFor,
+  unansweredQuestions,
+  viewOf,
+} from "./internal.js"
 import { FREE_TEXT_PLACEHOLDER, isAnswered, parseOpenQuestions } from "./qa.js"
-import { getParseCount } from "./index.js"
+import { getParseCount } from "./internal.js"
 
 const qa = steeringFormatFor("qa")!
 

package/src/steering/reads.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest"
+import { openQuestions, sectionBodies, sections, threads } from "./reads.js"
+
+describe("the pure text reads", () => {
+  it("sections and sectionBodies read the top-level ## headings", () => {
+    const text = "# Title\n\n## One\n\nfirst\n\n### Sub\n\n## Two\n"
+    expect(sections(text)).toEqual(["One", "Two"])
+    expect(sectionBodies(text).map((s) => s.title)).toEqual(["One", "Two"])
+    expect(sectionBodies(text)[0]!.body).toContain("## One")
+  })
+
+  it("openQuestions lists a qa document's unanswered questions with 1-based lines", () => {
+    const text = [
+      "## Open Questions",
+      "",
+      "### Which database?",
+      "",
+      "- [ ] Postgres",
+      "- [ ] SQLite",
+      "",
+    ].join("\n")
+    expect(openQuestions(text)).toEqual([{ question: "Which database?", line: 3 }])
+  })
+
+  it("threads reads a footnote thread with its 1-based line and who it waits on", () => {
+    const text = [
+      "We cache it.[^cache]",
+      "",
+      "[^cache]:",
+      "    - H: why?",
+      "    - A: because",
+      "",
+    ].join("\n")
+    expect(threads(text)).toEqual([{ name: "cache", line: 3, waitingOn: "human", faults: [] }])
+  })
+
+  it("works outside a replay", () => {
+    expect(() => sections("")).not.toThrow()
+    expect(threads("no threads here")).toEqual([])
+    expect(openQuestions("")).toEqual([])
+  })
+})

package/src/steering/reads.ts

@@ -0,0 +1,43 @@
+// The text reads `@pmelab/gtd/flows` offers inside a replay, here as plain
+// functions: the replay context answers with these, so both read alike.
+import { parseThreadsWithFindings } from "./Footnotes.js"
+import { headingSectionBodies, headingSections } from "./MarkdownTree.js"
+import { qaDescriptor } from "./qa.js"
+import { unansweredQuestions } from "./registry.js"
+
+/** The top-level `## ` heading texts of markdown `text`. */
+export const sections = (text: string): readonly string[] => headingSections(text)
+
+/** The top-level `## ` sections of markdown `text`, each with its own markdown, its heading line included. */
+export const sectionBodies = (
+  text: string,
+): readonly { readonly title: string; readonly body: string }[] => headingSectionBodies(text)
+
+/** The `qa`-format questions in `text` still unanswered, each with its heading's 1-based line. */
+export const openQuestions = (
+  text: string,
+): readonly { readonly question: string; readonly line: number }[] =>
+  unansweredQuestions(qaDescriptor, text).map((q) => ({
+    question: q.question,
+    line: q.headingLine + 1,
+  }))
+
+/** Every `H:`/`A:` footnote thread in `text`: its 1-based definition line, who it waits on (`"human"` means open) and its syntax faults. */
+export const threads = (
+  text: string,
+): readonly {
+  readonly name: string
+  readonly line: number
+  readonly waitingOn: "human" | "agent"
+  readonly faults: readonly string[]
+}[] => {
+  const { threads, findings } = parseThreadsWithFindings(text)
+  return threads.map((t) => ({
+    name: t.name,
+    line: t.line + 1,
+    waitingOn: t.waitingOn,
+    faults: findings
+      .filter((f) => f.message.startsWith(`Footnote thread "[^${t.name}]": `))
+      .map((f) => f.message),
+  }))
+}

package/src/steering/registry.ts

@@ -0,0 +1,93 @@
+import type {
+  SteeringAction,
+  SteeringFormat,
+  SteeringLink,
+  SteeringOutlineNode,
+  SteeringPointer,
+} from "./SteeringFormat.js"
+import { qaDescriptor } from "./qa.js"
+import { reviewDescriptor } from "./review.js"
+import { findingsDescriptor } from "./findings.js"
+// The free-form format: the mode-less/unregistered-mode FALLBACK —
+// deliberately not a `REGISTRY` entry of its own, since it is never a mode a
+// `mode:` key names.
+import { freeFormFormat } from "./freeform.js"
+
+/** The built-in registry: mode name → its format, in registry order. The single place the built-in formats are wired into names — everything else in this module dispatches over a resolved `SteeringFormat`, never a mode-name string. */
+const REGISTRY: ReadonlyMap<string, SteeringFormat> = new Map([
+  ["qa", qaDescriptor],
+  ["review", reviewDescriptor],
+  ["findings", findingsDescriptor],
+])
+
+/** Every built-in format name, in registry order. */
+export const BUILT_IN_MODE_NAMES: readonly string[] = [...REGISTRY.keys()]
+
+/** The built-in `SteeringFormat` registered under `mode`'s name, or `undefined` when it isn't a built-in mode at all. The one place a bare mode-name string is ever looked up — every consumer takes the RESOLVED value this returns, never a name, so "mode is required, never inferred from a file's basename" is a type, not a rule to remember. */
+export const steeringFormatFor = (mode: string): SteeringFormat | undefined => REGISTRY.get(mode)
+
+/**
+ * The ui boundary's own resolution: `mode`'s registered format, or
+ * `freeFormFormat` when `mode` is absent or names nothing in `REGISTRY` —
+ * never `undefined`. `resolveMode` (`SteeringMode.ts`) stays on
+ * `steeringFormatFor` alone, so a workflow naming a mode nothing defines
+ * still fails to compile; this fallback is deliberately reachable only from
+ * `src/ui/View.ts` and `src/ui/Write.ts`, where a mode-less/unknown-mode
+ * document must still render and accept a paragraph note, never refuse.
+ */
+export const steeringFormatOrFreeForm = (mode: string | undefined): SteeringFormat =>
+  (mode !== undefined ? REGISTRY.get(mode) : undefined) ?? freeFormFormat
+
+/**
+ * `qa`-only: every OPEN question in `content` not yet answered, as
+ * `{ question, headingLine }` pairs — enough for a refusal message ("which
+ * question", "where"). Semantically distinct from `validate`'s findings:
+ * a document can be perfectly well-formed (zero findings) while still having
+ * open questions nobody has answered, which is the whole point of the
+ * answer-completeness gate this feeds. Format-parameterised like everything
+ * else here: `review` (or any future format with no such concept) yields
+ * `[]` rather than this being a `qa`-specific function some caller has to
+ * know not to call on the wrong format.
+ */
+export const unansweredQuestions = (
+  format: SteeringFormat,
+  content: string,
+): readonly { readonly question: string; readonly headingLine: number }[] =>
+  format.unansweredQuestions?.(content) ?? []
+
+/**
+ * Every positional thing an editor (the LSP, in a later pass) needs for one
+ * document, off ONE `viewOf` call rather than four separate ones re-deriving
+ * ranges each time: `outline` and `documentLinks` are already fully resolved
+ * (each node/link carries its own range — see `SteeringOutlineNode`/
+ * `SteeringLink`), while `pointerAt`/`actionsAt` stay closures over `content`
+ * because they need a cursor position/selection range the caller supplies
+ * per request. `Lsp.ts` reads its ranges straight off `outline`/`documentLinks`.
+ */
+export interface SteeringEditorView {
+  readonly outline: readonly SteeringOutlineNode[]
+  readonly documentLinks: readonly SteeringLink[]
+  readonly pointerAt: (position: {
+    readonly line: number
+    readonly character: number
+  }) => SteeringPointer | undefined
+  readonly actionsAt: (range: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }) => readonly SteeringAction[]
+}
+
+/** Builds `format`'s `SteeringEditorView` of `content` — see `SteeringEditorView`'s own doc for why this is one value, not several. Distinct from `SteeringView` (`SteeringFormat.ts`), which is the format's own node tree the phone client renders. */
+export const viewOf = (format: SteeringFormat, content: string): SteeringEditorView => ({
+  outline: format.outline(content),
+  documentLinks: format.documentLinks ? format.documentLinks(content) : [],
+  pointerAt: (position) => format.pointerAt?.(content, position),
+  actionsAt: (range) => format.actions(content, range),
+})
+
+/** Every OPEN thread — last entry is the agent's — as `{ name, line, firstMe }` (0-based line). `[]` for a format with no thread concept. */
+export const openThreads = (
+  format: SteeringFormat,
+  content: string,
+): readonly { readonly name: string; readonly line: number; readonly firstMe: string }[] =>
+  format.openThreads?.(content) ?? []

package/src/steering/review.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest"
-import { FOOTNOTE_ACTION_TITLE, steeringFormatFor, viewOf } from "./index.js"
+import { FOOTNOTE_ACTION_TITLE, steeringFormatFor, viewOf } from "./internal.js"
 import { parseReviewDoc, unansweredNotes } from "./review.js"
-import { getParseCount } from "./index.js"
+import { getParseCount } from "./internal.js"
 
 describe("parseReviewDoc", () => {
   it("parses a well-formed review with one chunk, no explanations", () => {

package/src/step/planStart.test.ts

@@ -3,25 +3,28 @@ import { describe, expect, it } from "vitest"
 import { planStart, type StartOutcome } from "./planStart.js"
 import { InMemRepo, testLayers } from "../twins/index.js"
 import { ConfigService } from "../workflow/index.js"
+import { GtdUsageError } from "../platform/index.js"
 
-const WORKFLOW = `import { agent, human } from "@pmelab/gtd/flows"
+const WORKFLOW = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
 export default async () => {
   await human("idle", { message: "hi" })
   await agent("work", "work-prompt")
 }
 
-export const working = async () => {
-  await agent("work", "work-prompt")
-}
-
-export const reviewcheck = async () => {
-  await agent("work", "work-prompt")
-}
-
-export const defaults = { base: "" }
+export const working = workflow(
+  async () => {
+    await agent("work", "work-prompt")
+  },
+  { defaults: { base: "" } },
+)
 
-export const base = (workflow, vars) => (workflow === "reviewcheck" ? (vars.base ?? "") : undefined)
+export const reviewcheck = workflow(
+  async () => {
+    await agent("work", "work-prompt")
+  },
+  { defaults: { base: "" }, base: (_workflow, vars) => vars.base ?? "" },
+)
 `
 
 const repoAt = (): InMemRepo => {
@@ -85,15 +88,14 @@ describe("planStart", () => {
     })
   })
 
-  it("refuses an undeclared --var name", async () => {
+  it("fails an undeclared --var name as a usage error", async () => {
     const repo = repoAt()
-    const plan = await start(repo, "idle", "human", {
+    const failure = await start(repo, "idle", "human", {
       workflow: "working",
       commandLabel: "gtd test",
       vars: { nope: "x" },
-    })
-    expect(plan.kind).toBe("refusal")
-    expect(plan.kind === "refusal" && plan.message).toContain("not declared by this workflow")
+    }).catch((e: unknown) => e)
+    expect(String(failure)).toContain(`${GtdUsageError.name}: gtd test: --var name(s) not declared`)
   })
 
   describe("a workflow's diff base", () => {

package/src/step/planStart.ts

@@ -40,7 +40,7 @@ const checkOverrides = (
   varOverrides: Record<string, string>,
   declaredNames: readonly string[],
   envNames: readonly string[],
-): Effect.Effect<StartOutcome | undefined, Error> =>
+): Effect.Effect<void, GtdUsageError> =>
   Effect.gen(function* () {
     const environmentOnly = Object.keys(varOverrides).filter(
       (n) => !declaredNames.includes(n) && envNames.includes(n),
@@ -56,17 +56,18 @@ const checkOverrides = (
     }
     const undeclared = Object.keys(varOverrides).filter((n) => !declaredNames.includes(n))
     if (undeclared.length > 0) {
-      return refusal(
-        `${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(
-          ", ",
-        )} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`,
+      return yield* Effect.fail(
+        new GtdUsageError(
+          `${commandLabel}: --var name(s) not declared by this workflow: ${undeclared.join(
+            ", ",
+          )} — declared: ${declaredNames.length > 0 ? declaredNames.join(", ") : "(none)"}`,
+        ),
       )
     }
-    return undefined
   })
 
 /**
- * `gtd --workflow <name>`: start a brand NEW process on a workflow, writing an
+ * `gtd start <name>`: start a brand NEW process on a workflow, writing an
  * opening commit that names the workflow's first step and carries a
  * `Gtd-Workflow:` trailer, every process setting as a `Gtd-Var:` trailer, plus
  * a `Gtd-Review-Base:` trailer when the workflow fixes the process's diff base,
@@ -102,13 +103,12 @@ export const planStart = (
     if ("refusal" in first) return refusal(`${commandLabel}: ${first.refusal}`)
     const { firstStep } = first
 
-    const overrideRefusal = yield* checkOverrides(
+    yield* checkOverrides(
       commandLabel,
       varOverrides,
       Object.keys(workflow.vars),
       Object.keys(workflow.env),
     )
-    if (overrideRefusal !== undefined) return overrideRefusal
 
     const baseOf = workflow.def.base
     const flags = yield* StartFlags