@pmelab/gtd 59.0.0 → 59.0.1

package/src/cli/Help.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest"
+import { closest, definition, wrap } from "./Help.js"
+
+describe("wrap", () => {
+  it("fills lines up to the width, never past it", () => {
+    expect(wrap("aaa bbb ccc ddd", 7)).toEqual(["aaa bbb", "ccc ddd"])
+  })
+
+  it("keeps a code span on one line", () => {
+    expect(wrap("run `gtd help land` now", 12)).toEqual(["run", "`gtd help land`", "now"])
+  })
+
+  it("keeps an indented example paragraph verbatim", () => {
+    expect(wrap('text\n\n  s=$(x) && sh -c "$s"', 4)).toEqual([
+      "text",
+      "",
+      '  s=$(x) && sh -c "$s"',
+    ])
+  })
+})
+
+describe("definition", () => {
+  it("puts a short term beside its description", () => {
+    expect(definition("next", "Print it", 10)).toEqual(["  next    Print it"])
+  })
+
+  it("gives a term too wide for the column a line of its own", () => {
+    expect(definition("a-very-long-term", "Text", 10)).toEqual([
+      "  a-very-long-term",
+      "          Text",
+    ])
+  })
+})
+
+describe("closest", () => {
+  const commands = ["next", "land", "history", "help"]
+
+  it("finds a dropped letter and a swapped pair", () => {
+    expect(closest("nxt", commands)).toBe("next")
+    expect(closest("lnad", commands)).toBe("land")
+    expect(closest("histroy", commands)).toBe("history")
+  })
+
+  it("suggests nothing for a word unlike every candidate", () => {
+    expect(closest("frobnicate", commands)).toBeUndefined()
+  })
+})

package/src/cli/Help.ts

@@ -0,0 +1,70 @@
+const HELP_WIDTH = 80
+
+/**
+ * Word-wraps prose to `width` columns, every line prefixed by `indent`.
+ * Paragraphs are separated by a blank line; a paragraph whose lines start
+ * with two spaces is an example and is kept verbatim (indented, not wrapped).
+ */
+const wrapParagraph = (paragraph: string, width: number, indent: string): string[] => {
+  const lines: string[] = []
+  let line = ""
+  // A `code span` is one word: a command split across lines can't be copied.
+  for (const word of paragraph.match(/\S*`[^`]*`\S*|\S+/g) ?? []) {
+    if (line !== "" && indent.length + line.length + 1 + word.length > width) {
+      lines.push(indent + line)
+      line = word
+    } else {
+      line = line === "" ? word : `${line} ${word}`
+    }
+  }
+  if (line !== "") lines.push(indent + line)
+  return lines
+}
+
+export const wrap = (text: string, width = HELP_WIDTH, indent = ""): string[] =>
+  text
+    .split("\n\n")
+    .flatMap((paragraph, i) => [
+      ...(i > 0 ? [""] : []),
+      ...(paragraph.startsWith("  ")
+        ? paragraph.split("\n").map((l) => indent + l)
+        : wrapParagraph(paragraph, width, indent)),
+    ])
+
+/** `term` and `description` side by side, the description wrapped into the column after `column`; a term too wide for it gets a line of its own. */
+export const definition = (term: string, description: string, column: number): string[] => {
+  const cell = `  ${term}`
+  const body = wrap(description, HELP_WIDTH, " ".repeat(column))
+  if (cell.length + 1 >= column) return [cell, ...body]
+  const [first = "", ...rest] = body
+  return [cell.padEnd(column) + first.trimStart(), ...rest]
+}
+
+/** Optimal-string-alignment distance: Levenshtein plus adjacent transpositions, so `nxet` is one edit from `next`. */
+const distance = (a: string, b: string): number => {
+  const d: number[][] = Array.from({ length: a.length + 1 }, (_, i) =>
+    Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+  )
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      let best = Math.min(d[i - 1]![j]! + 1, d[i]![j - 1]! + 1, d[i - 1]![j - 1]! + cost)
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        best = Math.min(best, d[i - 2]![j - 2]! + 1)
+      }
+      d[i]![j] = best
+    }
+  }
+  return d[a.length]![b.length]!
+}
+
+/** The candidate closest to `word`, when it is a plausible typo of it: at most one edit per three characters, and at least one. */
+export const closest = (word: string, candidates: readonly string[]): string | undefined => {
+  const limit = Math.max(1, Math.floor(word.length / 3))
+  let best: { readonly name: string; readonly d: number } | undefined
+  for (const name of candidates) {
+    const d = distance(word, name)
+    if (d <= limit && (best === undefined || d < best.d)) best = { name, d }
+  }
+  return best?.name
+}

package/src/cli/Program.test.ts

@@ -4,7 +4,7 @@
  * e2e tier observes. Argv parsing is pinned in `src/cli/Cli.test.ts`.
  */
 
-import { Cause, Effect, Exit } from "effect"
+import { Cause, Context, Effect, Exit } from "effect"
 import { PassThrough } from "node:stream"
 import { afterEach, describe, expect, it, vi } from "vitest"
 
@@ -17,7 +17,7 @@ vi.mock("node:os", async (importOriginal) => ({
 
 import { runCli, type Command } from "./index.js"
 import { EXIT_USAGE_ERROR, stallDiagnosis, noopText, WIRE_SCHEMA } from "../wire/index.js"
-import { needsOf, runCommand, SelectorUsageError } from "./Program.js"
+import { needsOf, runCommand, SelectorUsageError, type CommandRequirements } from "./Program.js"
 import { InMemRepo, makeCapturingCliIo, testLayers, applyEmittedScript } from "../twins/index.js"
 import {
   commitAll,
@@ -26,7 +26,7 @@ import {
   noteOutcome,
   restoredOutcome,
 } from "../emit/index.js"
-import { HISTORY_REF } from "../platform/index.js"
+import { GitService, HISTORY_REF, Host } from "../platform/index.js"
 import { contentHash } from "../workflow/index.js"
 import { WORKFLOWS_REPO } from "../install/index.js"
 
@@ -119,6 +119,19 @@ export const defaults = { greeting: "hello" }
     expect(stderr).toContain("startable: hotfix")
   })
 
+  it("lists the paths its script commits as comments a path cannot break out of", async () => {
+    const repo = seed(WORKFLOW)
+    repo.writeFile("NOTE.md", "a note\n")
+    repo.writeFile("evil\nrm -rf x", "")
+    const { stdout, exitCode } = await run(repo, "--workflow", "hotfix")
+    expect(exitCode).toBe(0)
+    expect(stdout).toContain("# commits every change in the working tree (git add -A):\n")
+    expect(stdout).toContain("#   A NOTE.md\n")
+    expect(stdout).toContain("evil?rm -rf x")
+    expect(stdout).not.toMatch(/^rm -rf x/m)
+    expect(applyEmittedScript(repo, new Map(), stdout).ok).toBe(true)
+  })
+
   it("`default` is not startable by name", async () => {
     const repo = seed(WORKFLOW)
     const { exitCode, stderr } = await run(repo, "--workflow", "default")
@@ -1733,7 +1746,7 @@ describe("runCommand — refuses in a repository with no commits", () => {
   )
 
   const NO_COMMITS_MESSAGE =
-    "gtd requires a repository with at least one commit — make an initial commit, then run gtd again"
+    "gtd: the repository has no commits yet — make an initial commit, then run gtd again"
 
   it("derives exactly the eighteen non-standalone kinds — a canary for the table-driven cases below", () => {
     expect(stateKinds.sort()).toEqual(
@@ -2294,3 +2307,53 @@ export const defaults = ${vars}
     expect(repo.lastCommitMessage()).not.toContain("Gtd-Payload:")
   })
 })
+
+describe("runCommand — the repository-root guard's messages", () => {
+  const guarded = async (
+    override: (
+      git: Context.Tag.Service<GitService>,
+      host: Context.Tag.Service<Host>,
+    ) => Effect.Effect<unknown, Error, CommandRequirements>,
+  ): Promise<string> => {
+    const exit = await Effect.runPromiseExit(
+      Effect.gen(function* () {
+        return yield* override(yield* GitService, yield* Host)
+      }).pipe(Effect.provide(testLayers(seedIdle()))),
+    )
+    return Exit.isFailure(exit) ? (Cause.squash(exit.cause) as Error).message : ""
+  }
+  const out = { write: () => {}, flush: () => {} }
+  const next = runCommand({ kind: "next" }, { kind: "off" }, out)
+
+  it("outside a git repository says so instead of quoting git", async () => {
+    const message = await guarded((git) =>
+      next.pipe(
+        Effect.provideService(GitService, {
+          ...git,
+          topLevel: () =>
+            Effect.fail(
+              new Error(
+                "git rev-parse --show-toplevel failed (exit 128): fatal: not a git repository (or any of the parent directories): .git",
+              ),
+            ),
+        }),
+      ),
+    )
+    expect(message).toBe("gtd: not a git repository — run gtd inside one (`git init` makes one)")
+  })
+
+  it("from a subdirectory names the root to cd to", async () => {
+    const message = await guarded((_git, host) =>
+      next.pipe(
+        Effect.provideService(Host, {
+          ...host,
+          root: "/repo/my sub",
+          realPath: (path: string) => Effect.succeed(path),
+        }),
+      ),
+    )
+    expect(message).toBe(
+      "gtd: run gtd from the repository root — cd /repo (the current directory is /repo/my sub)",
+    )
+  })
+})

package/src/cli/Program.ts

@@ -33,6 +33,7 @@ import {
   landFields,
   noopText,
   renderBeatJson,
+  DEMAND_BRIEFING,
   renderBeatPlain,
   renderLandJson,
   renderLandPlain,
@@ -143,7 +144,7 @@ export type Command =
       readonly vars: Readonly<Record<string, string>>
       readonly label: string
     }
-  | { readonly kind: "door"; readonly name: string; readonly args: readonly string[] }
+  | { readonly kind: "door"; readonly name?: string; readonly args: readonly string[] }
   | { readonly kind: "doors" }
   | { readonly kind: "abandon" }
   | { readonly kind: "restore" }
@@ -566,10 +567,12 @@ const runStartCommand = (
     const config = yield* (yield* ConfigService).load
     const resolved = config.workflowNamed(workflow)
     if (resolved === undefined) {
+      const startable =
+        config.workflowNames.length > 0
+          ? `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: ${config.workflowNames.join(", ")}`,
-        ),
+        new GtdUsageError(`gtd --workflow: unknown workflow "${workflow}" — ${startable}`),
       )
     }
     const rest = yield* restAt(undefined, varOverrides)
@@ -591,35 +594,57 @@ const runStartCommand = (
     if (plan.kind === "refusal") {
       return yield* Effect.fail(new Error(plan.message))
     }
-    out.write(landingScript(ScriptSurface.render(plan.steps)))
+    out.write(listingCommitted(landingScript(ScriptSurface.render(plan.steps)), rest.changes))
   })
 
+/**
+ * A start commits the whole tree (`git add -A`), so its script says up front
+ * which paths that is. Comment lines only: control characters are masked so a
+ * path can never end the comment and become a command.
+ */
+const listingCommitted = (script: string, changes: readonly PendingChange[]): string => {
+  if (changes.length === 0) return script
+  const listing = [
+    "# commits every change in the working tree (git add -A):",
+    ...changes.map((change) => `#   ${change.status} ${change.path.replace(/\p{Cc}/gu, "?")}`),
+  ].join("\n")
+  const at = script.indexOf("\n\n")
+  return at === -1 ? script : `${script.slice(0, at)}\n\n${listing}${script.slice(at)}`
+}
+
 const doorSynopsis = (name: string, door: Door): string =>
   [
     name,
     ...(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,
+  name: string | undefined,
   args: readonly string[],
   out: ArtifactOut,
 ): Effect.Effect<void, Error, CommandRequirements> =>
   Effect.gen(function* () {
     const config = yield* (yield* ConfigService).load
-    const door = config.doors.get(name)
-    if (door === undefined) {
-      const known = [...config.doors]
-      return yield* Effect.fail(
-        new GtdUsageError(
-          `gtd door: unknown door "${name}" — doors: ${known.map(([n, d]) => doorSynopsis(n, d)).join(", ")}`,
-        ),
-      )
+    const door = name === undefined ? undefined : config.doors.get(name)
+    if (name === undefined || door === undefined) {
+      return yield* Effect.fail(noSuchDoor(name, config.doors))
     }
     const declared = door.args ?? []
     const required = declared.filter((arg) => arg.optional !== true).length
@@ -650,6 +675,11 @@ const runDoorsCommand = (
     const config = yield* (yield* ConfigService).load
     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
     }
@@ -849,6 +879,12 @@ const runNextCommand = (
       const validateCommand = emitsValidatablePrompt(rendered)
         ? selfValidateCommand(rest.def, rest.state, rendered.mode!, rendered.file!)
         : undefined
+      if (DEMAND_BRIEFING[fields.kind].suppressHeader) {
+        // A prompt's stdout is the agent's input, so its header goes to stderr;
+        // rendered as a header-showing kind to reuse the one header layout.
+        const shown = renderBeatPlain({ ...fields, kind: "message" })
+        yield* narrator.warn(shown.slice(0, shown.indexOf("\n\n")))
+      }
       out.write(renderBeatPlain(fields, validateCommand))
     }
   })
@@ -1125,19 +1161,30 @@ const runUiCliCommand = (
  */
 const assertRunningFromRepoRoot = (git: GitOperations, host: HostOps): Effect.Effect<void, Error> =>
   Effect.gen(function* () {
-    const topLevel = yield* git.topLevel()
+    const topLevel = yield* git
+      .topLevel()
+      .pipe(
+        Effect.mapError((e) =>
+          /not a git repository/.test(e.message)
+            ? new Error("gtd: not a git repository — run gtd inside one (`git init` makes one)")
+            : e,
+        ),
+      )
     const topReal = yield* host.realPath(topLevel)
     const cwdReal = yield* host.realPath(host.root)
     if (topReal !== cwdReal) {
       return yield* Effect.fail(
         new Error(
-          `gtd must be run from the repository root (${topLevel}); ` +
-            `the current directory is ${host.root}`,
+          `gtd: run gtd from the repository root — cd ${shellWord(topLevel)} ` +
+            `(the current directory is ${host.root})`,
         ),
       )
     }
   })
 
+const shellWord = (path: string): string =>
+  /^[\w@%+=:,./-]+$/.test(path) ? path : `'${path.replace(/'/g, "'\\''")}'`
+
 /** A command that derives workflow state needs at least one commit too — a commitless repository has no HEAD to resolve a `Rest` at. */
 const assertRepositoryHasCommits = (git: GitOperations): Effect.Effect<void, Error> =>
   Effect.gen(function* () {
@@ -1145,7 +1192,7 @@ const assertRepositoryHasCommits = (git: GitOperations): Effect.Effect<void, Err
     if (!hasCommits) {
       return yield* Effect.fail(
         new Error(
-          "gtd requires a repository with at least one commit — make an initial commit, then run gtd again",
+          "gtd: the repository has no commits yet — make an initial commit, then run gtd again",
         ),
       )
     }

package/src/edge/Edge.ts

@@ -995,7 +995,7 @@ export const restAt = (
     if (stepDef.mode !== undefined && def.modes[stepDef.mode] === undefined) {
       return yield* Effect.fail(
         new Error(
-          `gtd config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`,
+          `gtd: config: step "${step.name}": mode "${stepDef.mode}" is not a mode this workflow knows (${knownModes(def).join(", ")})`,
         ),
       )
     }

package/src/emit/Emit.test.ts

@@ -359,7 +359,7 @@ describe("real repo — an assembled script end to end", () => {
 describe("combinedScript — the plain-text write commands' single pasteable script", () => {
   it("DID_NOT_RUN_COMMENT points the reader at sh, not bash", () => {
     expect(DID_NOT_RUN_COMMENT).toBe(
-      "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn",
+      "# gtd emitted this and did NOT run it — run it with `sh` to apply it",
     )
     expect(DID_NOT_RUN_COMMENT).not.toContain("bash")
   })

package/src/emit/Emit.ts

@@ -112,7 +112,7 @@ export const emitScripts = (
 
 /** Exported so `src/twins/EmittedScriptRecognizer.ts` can recognize these by exact string comparison. `printf`, not `echo`, avoids shell-specific backslash-escape quirks. */
 export const DID_NOT_RUN_COMMENT =
-  "# gtd emitted this and did NOT run it — pipe it into `sh` to land the turn"
+  "# gtd emitted this and did NOT run it — run it with `sh` to apply it"
 
 export const PRESENTATION_ONLY_COMMENT = "# presentation only — safe to skip"
 

package/src/flows/factory.ts

@@ -52,7 +52,9 @@ export const defineWorkflow = <S extends StandardSchemaV1>(
     // A factory call used to be a flow; awaiting one in a composed flow must fail, not no-op.
     // oxlint-disable-next-line unicorn/no-thenable -- awaiting a call must fail
     then: () => {
-      throw new Error("a configured workflow is not a flow — compose fixFlow/reviewFlow instead")
+      throw new Error(
+        "a configured workflow is not a flow — await the flow functions it is built from instead",
+      )
     },
   })
   return Object.assign(factory, { [FACTORY]: internals }) as never