@pmelab/gtd 59.0.1 → 60.1.0

package/src/platform/Git.ts

@@ -1,5 +1,5 @@
-import { Command, CommandExecutor } from "@effect/platform"
 import { Context, Effect, Layer, Option, Stream } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/process"
 import { Host } from "./Host.js"
 
 export interface GitReaderOperations {
@@ -80,7 +80,7 @@ export interface GitReaderOperations {
     skip: number,
     head?: string,
   ) => Effect.Effect<ReadonlyArray<{ readonly hash: string; readonly subject: string }>, Error>
-  /** Fails when the path doesn't exist at `ref` — a caller expecting that (e.g. the review sign-off gate) handles it with an explicit `catchAll`. */
+  /** Fails when the path doesn't exist at `ref` — a caller expecting that (e.g. the review sign-off gate) handles it with an explicit `catch`. */
   readonly readFileAtRef: (ref: string, path: string) => Effect.Effect<string, Error>
   /**
    * Pending working-tree changes vs `base` (default `HEAD`), as
@@ -216,7 +216,7 @@ const blobsAtRef = (
   paths: ReadonlyArray<string>,
 ): Effect.Effect<Map<string, string>, Error> =>
   exec("git", "ls-tree", "-r", "-z", ref, "--", ...paths).pipe(
-    Effect.catchAll(() => Effect.succeed("")),
+    Effect.catch(() => Effect.succeed("")),
     Effect.map((out) => {
       const blobs = new Map<string, string>()
       for (const entry of splitNul(out)) {
@@ -256,7 +256,7 @@ const hashObjects = (
             .map((oid, i) => [paths[i] ?? "", oid.trim()] as const),
         ),
     ),
-    Effect.catchAll(() => Effect.succeed(new Map<string, string>())),
+    Effect.catch(() => Effect.succeed(new Map<string, string>())),
   )
 
 /**
@@ -287,25 +287,28 @@ const classifyUntracked = (
 
 /**
  * Run a command and return its stdout — FAILING on a non-zero exit code with
- * the command line and stderr in the error message. `Command.string` alone
- * silently ignores exit codes, which used to make gtd report success on
- * rejected commits and lose files whose quoted paths broke a swallowed
- * `git add`. Callers that expect a probe to fail handle it with an explicit
- * `catchAll`.
+ * the command line and stderr in the error message. Ignoring exit codes
+ * used to make gtd report success on rejected commits and lose files whose
+ * quoted paths broke a swallowed `git add`. Callers that expect a probe to
+ * fail handle it with an explicit `catch`.
  */
 const run = (
   root: string,
   ...args: [string, ...Array<string>]
-): Effect.Effect<string, Error, CommandExecutor.CommandExecutor> =>
+): Effect.Effect<string, Error, ChildProcessSpawner.ChildProcessSpawner> =>
   Effect.scoped(
     Effect.gen(function* () {
-      const executor = yield* CommandExecutor.CommandExecutor
-      const process = yield* executor.start(
-        Command.make(...args).pipe(
-          Command.workingDirectory(root),
-          Command.stdout("pipe"),
-          Command.stderr("pipe"),
-        ),
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+      const [command, ...rest] = args
+      const process = yield* spawner.spawn(
+        // Not detached: the spawner SIGTERMs a detached child's whole group once it
+        // exits, which would kill a git hook's background job.
+        ChildProcess.make(command, rest, {
+          cwd: root,
+          stdout: "pipe",
+          stderr: "pipe",
+          detached: false,
+        }),
       )
       const collect = (stream: typeof process.stdout) =>
         stream.pipe(Stream.decodeText(), Stream.mkString)
@@ -353,11 +356,12 @@ export const resolvedRefOrCorrupted = (
     ? Effect.succeed(hash)
     : Effect.fail(new InvalidRefError(`Invalid ref: ${ref}`, [`ref: ${ref}`]))
 
-const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): GitOperations => {
+const makeGitImpl = (
+  spawner: ChildProcessSpawner.ChildProcessSpawner["Service"],
+  root: string,
+): GitOperations => {
   const exec = (...args: [string, ...Array<string>]) =>
-    run(root, ...args).pipe(
-      Effect.provide(Layer.succeed(CommandExecutor.CommandExecutor, executor)),
-    )
+    run(root, ...args).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner))
 
   return {
     lastCommitSubject: (ref = "HEAD") =>
@@ -374,7 +378,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
       exec("git", "symbolic-ref", "--quiet", "--short", "HEAD").pipe(
         Effect.map((s) => s.trim()),
         Effect.map((name) => Option.some(name)),
-        Effect.catchAll(() => Effect.succeed(Option.none<string>())),
+        Effect.catch(() => Effect.succeed(Option.none<string>())),
       ),
 
     listRefs: (prefix: string) =>
@@ -399,7 +403,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
     hasCommits: () =>
       exec("git", "rev-parse", "--verify", "HEAD").pipe(
         Effect.map(() => true),
-        Effect.catchAll(() => Effect.succeed(false)),
+        Effect.catch(() => Effect.succeed(false)),
       ),
 
     readFileAtRef: (ref: string, path: string) => exec("git", "show", `${ref}:${path}`),
@@ -427,7 +431,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
             ? Option.none()
             : Option.some({ name: match[1]!, email: match[2]! })
         }),
-        Effect.catchAll(() => Effect.succeed(Option.none())),
+        Effect.catch(() => Effect.succeed(Option.none())),
       ),
 
     changedPaths: (base?: string) =>
@@ -436,7 +440,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
         // Tolerates the empty-repo case (no HEAD), where the diff has no ref
         // to compare against and reports no tracked changes.
         const nameStatusOut = yield* exec("git", "diff", "--name-status", "-z", ref).pipe(
-          Effect.catchAll(() => Effect.succeed("")),
+          Effect.catch(() => Effect.succeed("")),
         )
         const trackedPaths = parseNameStatus(splitNul(nameStatusOut))
 
@@ -469,7 +473,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
 
     stagedPaths: () =>
       exec("git", "diff", "--cached", "--name-status", "--no-renames", "-z", "HEAD").pipe(
-        Effect.catchAll(() => Effect.succeed("")),
+        Effect.catch(() => Effect.succeed("")),
         Effect.map((out) => parseNameStatus(splitNul(out))),
       ),
 
@@ -482,26 +486,26 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
     readRefOption: (ref: string) =>
       exec("git", "rev-parse", "--verify", "--quiet", ref).pipe(
         Effect.map((s) => Option.some(s.trim())),
-        Effect.catchAll(() => Effect.succeed(Option.none<string>())),
+        Effect.catch(() => Effect.succeed(Option.none<string>())),
       ),
 
     isAncestor: (a: string, b: string) =>
       run(root, "git", "merge-base", "--is-ancestor", a, b).pipe(
-        Effect.provide(Layer.succeed(CommandExecutor.CommandExecutor, executor)),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
         Effect.map(() => true),
-        Effect.catchAll(() => Effect.succeed(false)),
+        Effect.catch(() => Effect.succeed(false)),
       ),
 
     mergeBase: (a: string, b: string) =>
       exec("git", "merge-base", a, b).pipe(
         Effect.map((s) => Option.some(s.trim())),
-        Effect.catchAll(() => Effect.succeed(Option.none<string>())),
+        Effect.catch(() => Effect.succeed(Option.none<string>())),
       ),
 
     defaultBranch: () =>
       exec("git", "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD").pipe(
         Effect.map((s) => s.trim()),
-        Effect.catchAll(() => Effect.succeed("")),
+        Effect.catch(() => Effect.succeed("")),
         Effect.map((name) => (name === "" ? "main" : name)),
       ),
 
@@ -546,7 +550,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
             }),
         ),
         // Empty repo (no HEAD) makes `git log` fail; treat as no commits.
-        Effect.catchAll(() =>
+        Effect.catch(() =>
           Effect.succeed(
             [] as ReadonlyArray<{
               readonly hash: string
@@ -582,7 +586,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
         ),
         // Empty repo (no HEAD), or an unresolvable `head`, makes `git log`
         // fail; treat as no commits — the same fold `commitHistory` applies.
-        Effect.catchAll(() =>
+        Effect.catch(() =>
           Effect.succeed([] as ReadonlyArray<{ readonly hash: string; readonly subject: string }>),
         ),
       )
@@ -592,7 +596,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
       Effect.gen(function* () {
         yield* exec("git", "add", "-A")
         yield* exec("git", "commit", "--allow-empty", "-m", prefix).pipe(
-          Effect.catchAll((error) =>
+          Effect.catch((error) =>
             // Hooks like lint-staged block empty commits even with --allow-empty.
             // gtd's workflow commits have nothing for code-quality hooks to validate,
             // so retry without the pre-commit hook when that guard fires.
@@ -608,7 +612,7 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
     commitAsIs: (message: string) =>
       exec("git", "commit", "--allow-empty", "-m", message)
         .pipe(
-          Effect.catchAll((error) =>
+          Effect.catch((error) =>
             error.message.includes("empty git commit")
               ? exec("git", "commit", "--allow-empty", "--no-verify", "-m", message)
               : Effect.fail(error),
@@ -634,11 +638,11 @@ const makeGitImpl = (executor: CommandExecutor.CommandExecutor, root: string): G
 }
 
 const makeLiveEffect = Effect.gen(function* () {
-  const executor = yield* CommandExecutor.CommandExecutor
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
   const { root } = yield* Host
-  return makeGitImpl(executor, root)
+  return makeGitImpl(spawner, root)
 })
 
-export class GitService extends Context.Tag("GitService")<GitService, GitOperations>() {
+export class GitService extends Context.Service<GitService, GitOperations>()("GitService") {
   static Live = Layer.effect(GitService, makeLiveEffect)
 }

package/src/platform/Host.ts

@@ -36,7 +36,7 @@ const makeHostOps = (opts: HostOpsInput): HostOps => ({
     ((path: string) => Effect.try({ try: () => realpathSync(path), catch: toError })),
 })
 
-export class Host extends Context.Tag("Host")<Host, HostOps>() {
+export class Host extends Context.Service<Host, HostOps>()("Host") {
   static layer = (opts: HostOpsInput): Layer.Layer<Host> => Layer.succeed(Host, makeHostOps(opts))
   static Live = Host.layer({ root: process.cwd(), home: homedir(), env: process.env })
 }

package/src/platform/NodeServices.ts

@@ -0,0 +1,11 @@
+import { NodeChildProcessSpawner, NodeFileSystem, NodePath } from "@effect/platform-node-shared"
+import { Layer } from "effect"
+
+// Not `@effect/platform-node`'s own: that package requires a redis peer, which
+// every install of gtd would then pull in.
+export const layer = Layer.provideMerge(
+  NodeChildProcessSpawner.layer,
+  Layer.mergeAll(NodeFileSystem.layer, NodePath.layer),
+)
+
+export type NodeServices = Layer.Success<typeof layer>

package/src/platform/Workspace.test.ts

@@ -13,8 +13,7 @@ import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { afterEach, describe, expect, it, vi } from "vitest"
 import { Effect, Layer } from "effect"
-import { NodeContext } from "@effect/platform-node"
-import { GitService, Host, Workspace, type WorkspaceOps } from "./index.js"
+import { GitService, Host, Workspace, type WorkspaceOps, NodeServices } from "./index.js"
 import { InMemRepo, makeInMemoryWorkspaceOps } from "../twins/index.js"
 
 // `execFileSync` is a named export of the built-in `node:child_process` ESM
@@ -54,7 +53,7 @@ const makeLiveTier = (): WorkspaceTier => {
   gitExecIn(root, "config", "commit.gpgsign", "false")
 
   const hostLayer = Host.layer({ root, home: root, env: {} })
-  const gitLayer = GitService.Live.pipe(Layer.provide(Layer.merge(hostLayer, NodeContext.layer)))
+  const gitLayer = GitService.Live.pipe(Layer.provide(Layer.merge(hostLayer, NodeServices.layer)))
   const workspaceLayer = Workspace.Live.pipe(Layer.provide(Layer.merge(hostLayer, gitLayer)))
 
   return {
@@ -275,7 +274,7 @@ describe("Workspace [Live] worktreeSync", () => {
                 Host.layer({ root, home: root, env: {} }),
                 GitService.Live.pipe(
                   Layer.provide(
-                    Layer.merge(Host.layer({ root, home: root, env: {} }), NodeContext.layer),
+                    Layer.merge(Host.layer({ root, home: root, env: {} }), NodeServices.layer),
                   ),
                 ),
               ),
@@ -361,7 +360,7 @@ const makeLiveEpisodeTier = () => {
   git("config", "commit.gpgsign", "false")
 
   const hostLayer = Host.layer({ root, home: root, env: {} })
-  const gitLayer = GitService.Live.pipe(Layer.provide(Layer.merge(hostLayer, NodeContext.layer)))
+  const gitLayer = GitService.Live.pipe(Layer.provide(Layer.merge(hostLayer, NodeServices.layer)))
   const workspaceLayer = Workspace.Live.pipe(Layer.provide(Layer.merge(hostLayer, gitLayer)))
   const ops = (): Promise<WorkspaceOps> =>
     Effect.runPromise(

package/src/platform/Workspace.ts

@@ -600,7 +600,7 @@ const makeWorkspaceOps = (
     committed: (path, ref = "HEAD") =>
       Effect.try({ try: () => assertRepoRelative(path), catch: toError }).pipe(
         Effect.flatMap((relPath) =>
-          git.readFileAtRef(ref, relPath).pipe(Effect.catchAll(() => Effect.succeed(undefined))),
+          git.readFileAtRef(ref, relPath).pipe(Effect.catch(() => Effect.succeed(undefined))),
         ),
       ),
     readCommittedSync,
@@ -610,7 +610,7 @@ const makeWorkspaceOps = (
   }
 }
 
-export class Workspace extends Context.Tag("Workspace")<Workspace, WorkspaceOps>() {
+export class Workspace extends Context.Service<Workspace, WorkspaceOps>()("Workspace") {
   static Live = Layer.effect(
     Workspace,
     Effect.gen(function* () {
@@ -624,7 +624,7 @@ export class Workspace extends Context.Tag("Workspace")<Workspace, WorkspaceOps>
       // like a full-disk failure does.
       const commonDir = yield* git
         .gitCommonDir()
-        .pipe(Effect.catchAll(() => Effect.succeed(undefined)))
+        .pipe(Effect.catch(() => Effect.succeed(undefined)))
       return makeWorkspaceOps(root, git, commonDir)
     }),
   )

package/src/platform/WorktreeState.test.ts

@@ -12,10 +12,9 @@ import { mkdtempSync, realpathSync } from "node:fs"
 import { execSync } from "node:child_process"
 import { tmpdir } from "node:os"
 import { Effect, Layer } from "effect"
-import { NodeContext } from "@effect/platform-node"
 import { describe, expect, it } from "vitest"
 import { loopLogPath, worktreeGitDir } from "./WorktreeState.js"
-import { GitService, Host, Workspace } from "./index.js"
+import { GitService, Host, Workspace, NodeServices } from "./index.js"
 import { InMemRepo, testLayers } from "../twins/index.js"
 
 const provide = <A>(
@@ -112,7 +111,7 @@ describe("worktreeGitDir [real git]", () => {
 
   const runIn = (root: string) => {
     const hostLayer = Host.layer({ root, home: root, env: {} })
-    const gitLayer = GitService.Live.pipe(Layer.provide(Layer.merge(hostLayer, NodeContext.layer)))
+    const gitLayer = GitService.Live.pipe(Layer.provide(Layer.merge(hostLayer, NodeServices.layer)))
     const workspaceLayer = Workspace.Live.pipe(Layer.provide(Layer.merge(hostLayer, gitLayer)))
     return Effect.runPromise(
       worktreeGitDir.pipe(Effect.provide(Layer.mergeAll(hostLayer, workspaceLayer))),

package/src/platform/WorktreeState.ts

@@ -17,7 +17,7 @@ export const worktreeGitDir: Effect.Effect<string, never, Host | Workspace> = Ef
     const workspace = yield* Workspace
     const content = yield* workspace
       .read(".git")
-      .pipe(Effect.catchAll(() => Effect.succeed(undefined)))
+      .pipe(Effect.catch(() => Effect.succeed(undefined)))
     const pointer = content === undefined ? null : GITDIR_POINTER.exec(content)
     if (pointer === null) return ".git"
     const gitdir = pointer[1]!.trim()

package/src/platform/index.ts

@@ -4,7 +4,7 @@
  * home, env, scratch). `GitService` moved in alongside `Workspace` since
  * `committed` IS `git.readFileAtRef` — one module owns every read.
  *
- * Seam rule, stated once: a seam is a `Context.Tag` unless the consuming
+ * Seam rule, stated once: a seam is a `Context.Service` unless the consuming
  * code is synchronous, non-Effect code that cannot `yield*` — replay's flow
  * reads are that exception, and use the `*Sync` members.
  */
@@ -19,6 +19,7 @@ export {
 } from "./Git.js"
 export { Narrator, GtdError, GtdUsageError, renderFailure } from "./Commentary.js"
 export { CommandRunner } from "./CommandRunner.js"
+export * as NodeServices from "./NodeServices.js"
 export { loopLogPath } from "./WorktreeState.js"
 export {
   HISTORY_REF,

package/src/replay/Replay.test.ts

@@ -702,7 +702,7 @@ describe("replay: keep", () => {
   it("rejects keep together with allowEmpty", async () => {
     const flow: Flow = async () => {
       await human("idle")
-      await agent("naive", "p", { keep: true, allowEmpty: true })
+      await agent("naive", "p", { keep: true, allowEmpty: true } as never)
     }
     const h = new History().land("human", "idle", 1, "naive", {})
     const outcome = await replayOf(flow, h)
@@ -1166,6 +1166,17 @@ describe("human({ approve })", () => {
     }
   })
 
+  it.each([
+    ["human", async () => human("gate", { mode: "qa" } as never)],
+    ["agent", async () => agent("gate", "p", { mode: "qa" } as never)],
+    ["run", async () => run("gate", "true", { mode: "qa" } as never)],
+  ] as const)("refuses a %s step's mode without a file", async (kind, flow) => {
+    expect(await replayOf(flow, new History())).toEqual({
+      kind: "failed",
+      message: `gtd: step "gate": mode requires file in ${kind}() options — name the steering file the mode checks`,
+    })
+  })
+
   describe("refuses mode and file", () => {
     const tail =
       "in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing"
@@ -1189,7 +1200,7 @@ describe("human({ approve })", () => {
       for (const options of [
         { approve: true, label: "x" },
         { approve: true, base: "start" },
-        { approve: false, mode: "review" },
+        { approve: false, mode: "review", file: ".gtd/REVIEW.md" },
         { approve: true, mode: undefined },
       ]) {
         expect((await outcomeOf(options)).kind).toBe("rest")

package/src/replay/Replay.ts

@@ -11,14 +11,13 @@ import {
   type StepRequest,
   type Flow,
   type Mark,
-} from "../flows/index.js"
+} from "../flows/internal.js"
 import {
-  headingSectionBodies,
-  headingSections,
-  steeringFormatFor,
+  openQuestions,
   parseCodeThreads,
-  parseThreadsWithFindings,
-  unansweredQuestions,
+  sectionBodies,
+  sections,
+  threads,
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
 import { globMatches } from "../wire/index.js"
@@ -291,6 +290,13 @@ const approveConflict = (step: ReachedStep): string | undefined => {
   return `gtd: step "${step.name}": approve cannot be combined with ${keys.join(", ")} in human() options — an approval records exactly the judged tree, and a steering file is rewritten on landing`
 }
 
+// A mode names how a steering file is checked; with no file there is nothing to check.
+const modeWithoutFile = (step: ReachedStep): string | undefined => {
+  const options = step.request.options
+  if (options.mode === undefined || options.file !== undefined) return undefined
+  return `gtd: step "${step.name}": mode requires file in ${step.kind}() options — name the steering file the mode checks`
+}
+
 export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   const commits: readonly ParsedCommit[] = input.episode.commits.map((c) => ({
     ...c,
@@ -524,7 +530,8 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
         message: `gtd: commit ${short(expected.hash)} names "${expected.name}" as the next step, but replay reached "${step.name}" — ${DIVERGED}`,
       }
     }
-    const error = unknownOptions(step) ?? approveConflict(step) ?? checkIdentity(step)
+    const error =
+      unknownOptions(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step)
     return error === undefined ? undefined : { kind: "failed", message: error }
   }
 
@@ -604,7 +611,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     const name = scoped(request.name)
     if (request.options.keep === true) {
       // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.
-      if (request.options.allowEmpty === true) {
+      if ((request.options as { readonly allowEmpty?: unknown }).allowEmpty === true) {
         return `gtd: step "${name}": keep: true cannot be combined with allowEmpty — a turn that changes nothing has nothing to keep`
       }
       // "/" would let one step's ref directory collide with another step's ref (git refuses `a` and `a/b` together).
@@ -667,28 +674,10 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     changes: () => changesBetween(previousPosition.tree, position.tree),
     changesSince,
     matches: globMatches,
-    sections: (text) => headingSections(text),
-    sectionBodies: (text) => headingSectionBodies(text),
-    openQuestions: (text) => {
-      const qa = steeringFormatFor("qa")
-      return qa === undefined
-        ? []
-        : unansweredQuestions(qa, text).map((q) => ({
-            question: q.question,
-            line: q.headingLine + 1,
-          }))
-    },
-    threads: (text) => {
-      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),
-      }))
-    },
+    sections,
+    sectionBodies,
+    openQuestions,
+    threads,
     codeThreads: () =>
       changesBetween(
         treeAt(input.start) ?? input.startTree ?? input.episode.base.tree,

package/src/replay/judgeDiffShape.test.ts

@@ -6,7 +6,7 @@ import {
   type FlowContext,
   type JudgeAnswer,
   type StepRequest,
-} from "../flows/index.js"
+} from "../flows/internal.js"
 import { toRequest } from "../judges/index.js"
 import { globMatches } from "../wire/index.js"
 

package/src/steering/Footnotes.test.ts

@@ -697,7 +697,7 @@ describe("case-insensitive definition matching", () => {
   })
 })
 
-import { freeFormFormat, getParseCount, steeringFormatFor } from "./index.js"
+import { freeFormFormat, getParseCount, steeringFormatFor } from "./internal.js"
 
 const qaDescriptor = steeringFormatFor("qa")!
 const reviewDescriptor = steeringFormatFor("review")!

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")
+  })
+})