@pmelab/gtd 59.0.1 → 60.0.0

package/src/cli/Program.ts

@@ -70,7 +70,7 @@ import {
   unansweredQuestions,
   formatFinding,
   type SteeringFormat,
-} from "../steering/index.js"
+} from "../steering/internal.js"
 import {
   resolveMode,
   validateScriptFor,
@@ -91,7 +91,10 @@ import {
 import { renderBriefing, WORKFLOWS_REPO } from "../install/index.js"
 import { ToolCommands, type SelfGtd } from "./ToolCommands.js"
 import {
+  normalizeScriptNewline,
   SelectorUsageError,
+  writeJson,
+  writeScript,
   writeSelection,
   type ArtifactOut,
   type CommandRequirements,
@@ -139,13 +142,11 @@ export type Command =
     }
   | {
       readonly kind: "start"
-      readonly actor: string
-      readonly workflow: string
+      /** A door or a workflow; absent lists both. */
+      readonly name?: string
+      readonly args: readonly string[]
       readonly vars: Readonly<Record<string, string>>
-      readonly label: string
     }
-  | { readonly kind: "door"; readonly name?: string; readonly args: readonly string[] }
-  | { readonly kind: "doors" }
   | { readonly kind: "abandon" }
   | { readonly kind: "restore" }
   | { readonly kind: "next" }
@@ -159,7 +160,7 @@ export type Command =
       readonly openThreads?: boolean
     }
   | { readonly kind: "uncheck"; readonly file: string }
-  | { readonly kind: "install" }
+  | { readonly kind: "guide" }
   | { readonly kind: "summary" }
   | { readonly kind: "base" }
   | { readonly kind: "judge" }
@@ -211,7 +212,7 @@ const runLspCommand = (): Effect.Effect<void, Error, ToolCommands> =>
  * gtd ships no workflow, so where no `gtd.config.ts` governs it says where to
  * get one; it writes nothing.
  */
-const runInstallCommand = (
+const runGuideCommand = (
   out: ArtifactOut,
 ): Effect.Effect<void, Error, GitService | Host | ConfigDiscovery | Narrator> =>
   Effect.gen(function* () {
@@ -223,7 +224,7 @@ const runInstallCommand = (
     if ((yield* host.realPath(topLevel.right)) !== (yield* host.realPath(host.root))) return
     if ((yield* (yield* ConfigDiscovery).workflowModule(host.root, host.home)) !== undefined) return
     yield* (yield* Narrator).warn(
-      `gtd install: no ${WORKFLOW_MODULE} governs here, and gtd ships no workflow — get one from ${WORKFLOWS_REPO} or write your own (step 2 of the briefing above)`,
+      `gtd guide: no ${WORKFLOW_MODULE} governs here, and gtd ships no workflow — get one from ${WORKFLOWS_REPO} or write your own (step 2 of the briefing above)`,
     )
   })
 
@@ -244,20 +245,10 @@ interface LandResult {
   readonly idle: boolean
 }
 
-/**
- * Exactly one trailing newline — duplicated from `Cli.ts`'s own
- * `normalizeTrailingNewline` rather than imported, to avoid a circular value
- * dependency (`Cli.ts` already depends on this module). `LandResult.script`
- * must carry its own trailing newline because it's embedded verbatim inside
- * the `--json` document, never re-normalized at its tail.
- */
-const normalizeScriptNewline = (script: string): string =>
-  script.length === 0 ? script : `${script.replace(/\n+$/, "")}\n`
-
 /**
  * `combinedScript`, narrowed to accept only an already-guarded
  * `RunnableScript` for `required` — the one boundary `ScriptSurface`'s brand
- * exists to protect: `gtd land`/`gtd --workflow`'s emitted script. Every OTHER
+ * exists to protect: `gtd land`/`gtd start`'s emitted script. Every OTHER
  * `combinedScript` call (`abandon`/`restore`/steering validate, below) builds
  * from `emitScripts` directly and keeps the unbranded signature — those
  * paths land no guard-gated git write for a brand to protect.
@@ -425,6 +416,20 @@ const readStdin = (): Effect.Effect<string, Error> =>
     catch: (e) => (e instanceof Error ? e : new Error(String(e))),
   })
 
+/** A stdin that is no judgment is the caller's mistake, a usage error like `gtd judge answer`'s. */
+const judgmentShape = (input: string): Effect.Effect<void, GtdUsageError> => {
+  let doc: unknown
+  try {
+    doc = JSON.parse(input)
+  } catch {
+    return Effect.fail(new GtdUsageError("gtd judge run: stdin is not valid JSON"))
+  }
+  const questions = (doc as { questions?: unknown } | null)?.questions
+  return Array.isArray(questions)
+    ? Effect.void
+    : Effect.fail(new GtdUsageError('gtd judge run: stdin has no "questions" array'))
+}
+
 /** Stdout is written once, after the answerer resolves — a rejection leaves it empty. */
 const runJudgeRunCommand = (
   command: Extract<Command, { kind: "judgeRun" }>,
@@ -435,6 +440,7 @@ const runJudgeRunCommand = (
     const tools = yield* ToolCommands
     yield* refuseLegacyRc
     const input = yield* readStdin()
+    yield* judgmentShape(input)
     const verdict = yield* Effect.tryPromise({
       try: () =>
         tools.judge({
@@ -556,10 +562,10 @@ const runLandCommand = (
  * `base` renders to something that is not an ancestor of (and differs from)
  * HEAD.
  */
-const runStartCommand = (
-  actor: string,
+const startWorkflow = (
   workflow: string,
   varOverrides: Record<string, string>,
+  json: JsonMode,
   out: ArtifactOut,
   commandLabel: string,
 ): Effect.Effect<void, Error, CommandRequirements> =>
@@ -572,7 +578,7 @@ const runStartCommand = (
           ? `startable: ${config.workflowNames.join(", ")}`
           : "this config exports no workflow besides its default, which an ordinary start runs"
       return yield* Effect.fail(
-        new GtdUsageError(`gtd --workflow: unknown workflow "${workflow}" — ${startable}`),
+        new GtdUsageError(`${commandLabel}: unknown workflow "${workflow}" — ${startable}`),
       )
     }
     const rest = yield* restAt(undefined, varOverrides)
@@ -582,7 +588,7 @@ const runStartCommand = (
         state: rest.state,
         idle: noProcessUnderway(rest),
       },
-      actor,
+      "human",
       {
         workflow: resolved,
         first: started,
@@ -594,7 +600,11 @@ const runStartCommand = (
     if (plan.kind === "refusal") {
       return yield* Effect.fail(new Error(plan.message))
     }
-    out.write(listingCommitted(landingScript(ScriptSurface.render(plan.steps)), rest.changes))
+    yield* writeScript(
+      json,
+      out,
+      listingCommitted(landingScript(ScriptSurface.render(plan.steps)), rest.changes),
+    )
   })
 
 /**
@@ -618,40 +628,23 @@ const doorSynopsis = (name: string, door: Door): string =>
     ...(door.args ?? []).map((arg) => (arg.optional === true ? `[${arg.name}]` : `<${arg.name}>`)),
   ].join(" ")
 
-const noSuchDoor = (name: string | undefined, doors: ReadonlyMap<string, Door>): GtdUsageError => {
-  const listing =
-    doors.size > 0
-      ? `doors: ${[...doors].map(([n, d]) => doorSynopsis(n, d)).join(", ")}`
-      : "this config has no doors"
-  return new GtdUsageError(
-    name === undefined
-      ? `gtd door: missing door name — ${listing}`
-      : `gtd door: unknown door "${name}" — ${listing}`,
-  )
-}
-
-/**
- * `gtd door <name> [args…]`: `gtd --workflow` with the door's workflow and the
- * process settings its `vars` derive from the positional args. A wrong name or
- * arity is a usage error naming what would have worked.
- */
-const runDoorCommand = (
-  name: string | undefined,
+/** A door's start: its args mapped to process settings, `extra` (`--var`) pinned on top. */
+const startThroughDoor = (
+  name: string,
+  door: Door,
   args: readonly string[],
+  extra: Readonly<Record<string, string>>,
+  json: JsonMode,
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
-    const config = yield* (yield* ConfigService).load
-    const door = name === undefined ? undefined : config.doors.get(name)
-    if (name === undefined || door === undefined) {
-      return yield* Effect.fail(noSuchDoor(name, config.doors))
-    }
+    const label = `gtd start ${name}`
     const declared = door.args ?? []
     const required = declared.filter((arg) => arg.optional !== true).length
     if (args.length < required || args.length > declared.length) {
       return yield* Effect.fail(
         new GtdUsageError(
-          `gtd door ${name}: ${args.length < required ? "missing" : "too many"} arguments — usage: gtd door ${doorSynopsis(name, door)}`,
+          `${label}: ${args.length < required ? "missing" : "too many"} arguments — usage: gtd start ${doorSynopsis(name, door)}`,
         ),
       )
     }
@@ -661,35 +654,81 @@ const runDoorCommand = (
     })
     const vars = yield* Effect.try({
       try: () => door.vars?.(named) ?? {},
-      catch: (e) => new Error(`gtd door ${name}: ${e instanceof Error ? e.message : String(e)}`),
+      catch: (e) => new Error(`${label}: ${e instanceof Error ? e.message : String(e)}`),
     })
-    yield* runStartCommand("human", door.workflow, { ...vars }, out, `gtd door ${name}`)
+    yield* startWorkflow(door.workflow, { ...vars, ...extra }, json, out, label)
   })
 
-/** `gtd doors`: every door and its args, sorted by name — plain lines, or one JSON array. */
-const runDoorsCommand = (
+/**
+ * `gtd start <name> [args…]`: a door when `<name>` is one — so a door shadows
+ * the workflow it shares a name with — else a workflow, which takes no args.
+ * No name lists both.
+ */
+const runStartCommand = (
+  command: Extract<Command, { kind: "start" }>,
   json: JsonMode,
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
+    const { name, args, vars } = command
+    if (name === undefined) return yield* runStartListCommand(json, out)
+    const label = `gtd start ${name}`
     const config = yield* (yield* ConfigService).load
+    const door = config.doors.get(name)
+    if (door !== undefined) {
+      return yield* startThroughDoor(name, door, args, vars, json, out)
+    }
+    if (config.workflowNamed(name) === undefined) {
+      return yield* Effect.fail(
+        new GtdUsageError(
+          `${label}: no workflow or door is named "${name}" — run \`gtd start\` to list them`,
+        ),
+      )
+    }
+    if (args.length > 0) {
+      return yield* Effect.fail(
+        new GtdUsageError(
+          `${label}: too many arguments — a workflow takes none, only --var <name>=<value>; got: ${args.join(", ")}`,
+        ),
+      )
+    }
+    yield* startWorkflow(name, { ...vars }, json, out, label)
+  })
+
+/**
+ * Bare `gtd start`: every workflow startable by name, then every door — plain
+ * lines, or one JSON array. A workflow a door shadows is left out: its name
+ * opens the door.
+ */
+const runStartListCommand = (
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, CommandRequirements> =>
+  Effect.gen(function* () {
+    const config = yield* (yield* ConfigService).load
+    const workflows = [...config.workflowNames].filter((name) => !config.doors.has(name)).sort()
     const doors = [...config.doors]
-    if (json.kind === "off") {
-      if (doors.length === 0) {
-        yield* (yield* Narrator).warn(
-          "gtd doors: this config has no doors — a workflow factory's `doors` option or the config's `doors` export adds one",
-        )
-      }
-      out.write(doors.map(([n, d]) => `${doorSynopsis(n, d)} → ${d.workflow}\n`).join(""))
-      return
+    const document = [
+      ...workflows.map((name) => ({ kind: "workflow", name })),
+      ...doors.map(([name, door]) => ({
+        kind: "door",
+        name,
+        workflow: door.workflow,
+        args: (door.args ?? []).map((arg) => ({ name: arg.name, optional: arg.optional === true })),
+      })),
+    ]
+    if (yield* writeJson(json, out, document)) return
+    if (document.length === 0) {
+      yield* (yield* Narrator).warn(
+        "gtd start: this config exports no workflow besides its default, which an ordinary start runs, and no door",
+      )
     }
-    const document = doors.map(([n, d]) => ({
-      name: n,
-      workflow: d.workflow,
-      args: (d.args ?? []).map((arg) => ({ name: arg.name, optional: arg.optional === true })),
-    }))
-    if (json.kind === "document") out.write(`${JSON.stringify(document)}\n`)
-    else yield* writeSelection(out, document, json.path)
+    out.write(
+      [
+        ...workflows.map((name) => `workflow ${name}\n`),
+        ...doors.map(([n, d]) => `door ${doorSynopsis(n, d)} → ${d.workflow}\n`),
+      ].join(""),
+    )
   })
 
 /**
@@ -705,7 +744,10 @@ const runDoorsCommand = (
  * Idempotent at the initial state. The one refusal is a process whose first
  * commit is the repository's root commit: nothing earlier to rewind to.
  */
-const runAbandonCommand = (out: ArtifactOut): Effect.Effect<void, Error, CommandRequirements> =>
+const runAbandonCommand = (
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
     const git = yield* GitService
     const config = yield* (yield* ConfigService).load
@@ -716,8 +758,7 @@ const runAbandonCommand = (out: ArtifactOut): Effect.Effect<void, Error, Command
       const required = emitScripts([
         { kind: "outcome", command: abandonNoopOutcome(initial) },
       ]).required
-      out.write(combinedScript(required, ""))
-      return
+      return yield* writeScript(json, out, combinedScript(required, ""))
     }
     const restState = run.trace[run.trace.length - 1]!.state
 
@@ -738,7 +779,7 @@ const runAbandonCommand = (out: ArtifactOut): Effect.Effect<void, Error, Command
       { kind: "outcome", command: abandonedOutcome(restState, run.startParentHash, initial) },
     ]
     const required = emitScripts(steps).required
-    out.write(combinedScript(required, ""))
+    yield* writeScript(json, out, combinedScript(required, ""))
   })
 
 /**
@@ -748,7 +789,10 @@ const runAbandonCommand = (out: ArtifactOut): Effect.Effect<void, Error, Command
  * refuses on a dirty working tree, no retained history, or HEAD having
  * advanced past the retained tip with commits that would be lost.
  */
-const runRestoreCommand = (out: ArtifactOut): Effect.Effect<void, Error, CommandRequirements> =>
+const runRestoreCommand = (
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
     const git = yield* GitService
 
@@ -790,7 +834,7 @@ const runRestoreCommand = (out: ArtifactOut): Effect.Effect<void, Error, Command
       { kind: "outcome", command: restoredOutcome(tip, after.state) },
     ]
     const required = emitScripts(steps).required
-    out.write(combinedScript(required, ""))
+    yield* writeScript(json, out, combinedScript(required, ""))
   })
 
 /**
@@ -890,14 +934,18 @@ const runNextCommand = (
   })
 
 /** Emits the format-then-validate script for the driver to run; reads no file and executes nothing itself. The verdict lives in that script's future exit code, which prints the complete fix prompt rather than bare findings. */
-const runValidateCommand = (out: ArtifactOut): Effect.Effect<void, Error, CommandRequirements> =>
+const runValidateCommand = (
+  json: JsonMode,
+  out: ArtifactOut,
+): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
     const rest = yield* currentRest
-    const resolved = yield* resolveValidateScript(rest)
-    out.write(
-      resolved !== undefined && resolved.script.length > 0
-        ? `${resolved.script}\n`
-        : `nothing to validate at "${rest.state}"\n`,
+    const script = (yield* resolveValidateScript(rest))?.script ?? ""
+    yield* writeScript(
+      json,
+      out,
+      script,
+      script.length > 0 ? `${script}\n` : `nothing to validate at "${rest.state}"\n`,
     )
   })
 
@@ -906,8 +954,10 @@ const runValidateCommand = (out: ArtifactOut): Effect.Effect<void, Error, Comman
  * Resolves no workflow state and reads no config — this is what a seeded
  * `validate:` command invokes as a leaf step, and it formats nothing.
  *
- * An absent file exits 0, like `gtd validate`. Findings ride the failing
- * Effect's message, so the shared refusal path reports them on stderr.
+ * An unknown mode is a usage error; an absent file is a refusal (the emitted
+ * validate script guards on the file's presence before it calls this).
+ * Findings ride the failing Effect's message, so the shared refusal path
+ * reports them on stderr.
  */
 const runCheckCommand = (
   mode: string,
@@ -919,7 +969,7 @@ const runCheckCommand = (
     const format = steeringFormatFor(mode)
     if (format === undefined) {
       return yield* Effect.fail(
-        new Error(
+        new GtdUsageError(
           `gtd check: unknown mode "${mode}" — known modes: ${BUILT_IN_MODE_NAMES.join(", ")}`,
         ),
       )
@@ -953,12 +1003,8 @@ const runCheckCommand = (
       return yield* runOpenQuestionsCheckCommand(format, file)
     }
 
-    const workspace = yield* Workspace
-    const content = workspace.atPath(file)
-    const errors =
-      content !== undefined
-        ? format.validate(content).map((finding) => formatFinding(file, finding))
-        : []
+    const content = yield* existingFile(file)
+    const errors = format.validate(content).map((finding) => formatFinding(file, finding))
 
     if (errors.length === 0) return
 
@@ -970,6 +1016,14 @@ const runCheckCommand = (
     )
   })
 
+const existingFile = (file: string): Effect.Effect<string, Error, Workspace> =>
+  Effect.flatMap(Workspace, (workspace) => {
+    const content = workspace.atPath(file)
+    return content === undefined
+      ? Effect.fail(new Error(`gtd check: no such file: ${file}`))
+      : Effect.succeed(content)
+  })
+
 /**
  * The bare `gtd check --open-threads`: code-comment threads in the files the
  * current process changed. The one `check` form that reads process state; no
@@ -997,18 +1051,13 @@ const runCodeThreadsCheckCommand = (): Effect.Effect<void, Error, CommandRequire
     return yield* Effect.fail(new Error(lines.join("\n")))
   })
 
-/** Prints one `file:line: [^name]: <first H entry>` line per open thread; a missing file fails, like `--open-questions`. */
+/** Prints one `file:line: [^name]: <first H entry>` line per open thread. */
 const runOpenThreadsCheckCommand = (
   format: SteeringFormat,
   file: string,
 ): Effect.Effect<void, Error, Workspace> =>
   Effect.gen(function* () {
-    const workspace = yield* Workspace
-    const content = workspace.atPath(file)
-    if (content === undefined) {
-      return yield* Effect.fail(new Error(`gtd check: ${file} does not exist`))
-    }
-
+    const content = yield* existingFile(file)
     const errors = openThreads(format, content).map(
       (t) => `${file}:${t.line + 1}: [^${t.name}]: ${t.firstMe}`,
     )
@@ -1021,20 +1070,14 @@ const runOpenThreadsCheckCommand = (
 
 /**
  * Runs the SAME `unansweredQuestions` predicate a flow's `openQuestions()`
- * reads, so the gate script and the flow's own check stay in sync. A missing
- * file is a non-zero exit here, unlike the structural path above.
+ * reads, so the gate script and the flow's own check stay in sync.
  */
 const runOpenQuestionsCheckCommand = (
   format: SteeringFormat,
   file: string,
 ): Effect.Effect<void, Error, Workspace> =>
   Effect.gen(function* () {
-    const workspace = yield* Workspace
-    const content = workspace.atPath(file)
-    if (content === undefined) {
-      return yield* Effect.fail(new Error(`gtd check: ${file} does not exist`))
-    }
-
+    const content = yield* existingFile(file)
     const errors = unansweredQuestions(format, content).map(
       (q) => `${file}:${q.headingLine + 1}: ${q.question}`,
     )
@@ -1208,7 +1251,7 @@ const assertRepositoryHasCommits = (git: GitOperations): Effect.Effect<void, Err
 export const needsOf = (kind: Command["kind"]): Needs => {
   switch (kind) {
     case "lsp":
-    case "install":
+    case "guide":
     case "judgeRun":
     case "strays":
       return "none"
@@ -1225,7 +1268,7 @@ export const standaloneKinds = (): readonly Command["kind"][] => [
   "lsp",
   "check",
   "uncheck",
-  "install",
+  "guide",
   "judgeRun",
   "strays",
 ]
@@ -1266,19 +1309,15 @@ const dispatchVoidCommand = (
         out,
       )
     case "start":
-      return runStartCommand(command.actor, command.workflow, command.vars, out, command.label)
-    case "door":
-      return runDoorCommand(command.name, command.args, out)
-    case "doors":
-      return runDoorsCommand(json, out)
+      return runStartCommand(command, json, out)
     case "abandon":
-      return runAbandonCommand(out)
+      return runAbandonCommand(json, out)
     case "restore":
-      return runRestoreCommand(out)
+      return runRestoreCommand(json, out)
     case "next":
       return runNextCommand(json, out)
     case "validate":
-      return runValidateCommand(out)
+      return runValidateCommand(json, out)
     case "check":
       if (command.mode === undefined || command.file === undefined) {
         return runCodeThreadsCheckCommand()
@@ -1291,8 +1330,8 @@ const dispatchVoidCommand = (
       )
     case "uncheck":
       return runUncheckCommand(command.file)
-    case "install":
-      return runInstallCommand(out)
+    case "guide":
+      return runGuideCommand(out)
     case "summary":
       return runSummaryCommand(out)
     case "base":
@@ -1312,7 +1351,7 @@ const dispatchVoidCommand = (
     case "historyJudges":
       return runHistoryJudgesCommand(command.refs, command.vars, command.jsonl, json, out)
     case "historyFetch":
-      return runHistoryFetchCommand(command.remote, out)
+      return runHistoryFetchCommand(command.remote, json, out)
   }
 }