@pmelab/gtd 24.0.0 → 24.2.0

package/src/platform/CommandRunner.ts

@@ -0,0 +1,74 @@
+import { Command, CommandExecutor } from "@effect/platform"
+import { Context, Effect, Layer, Stream } from "effect"
+import { Host } from "./Host.js"
+
+/** One command run's outcome: its exit status (a signal death reported as `null`, matching `spawnSync`) and its combined output (stdout then stderr). */
+interface CommandOutcome {
+  readonly status: number | null
+  readonly output: string
+  /** `stdout`/`stderr` captured separately, alongside the merged `output` — additive, for callers (the tRPC router) that need a refusal's three fields distinct rather than flattened into one string. Optional so existing test doubles built from `{ status, output }` alone still satisfy this interface. */
+  readonly stdout?: string
+  readonly stderr?: string
+}
+
+/**
+ * The subprocess port: run one shell command in the repo root, wait for it to
+ * finish, and get its combined output back as one string (a workflow
+ * `script:` is run by the DRIVER, never by gtd — and a mode's
+ * `format:`/`validate:` command is RENDERED into the driver's script rather
+ * than spawned here). Its remaining callers are `gtd ui`'s own helpers
+ * (openssl, tailscale). `gtd ui`'s loop command is spawned by `Loop.ts`'s own
+ * port instead — it needs a per-worktree cwd, a shim-prepended `PATH`, real
+ * OS signal control while the child is still running, and never-combined
+ * stdout/stderr, none of which this port's single-shot "run to completion"
+ * shape supports.
+ */
+export class CommandRunner extends Context.Tag("CommandRunner")<
+  CommandRunner,
+  {
+    /** A SPAWN failure (no `bash`, unreadable cwd) fails the Effect; a non-zero EXIT is a value — how a mode command reports "invalid"/"broken" for the caller to interpret. */
+    readonly bash: (command: string) => Effect.Effect<CommandOutcome, Error>
+  }
+>() {
+  /** A test layer over a canned `bash` implementation — no subprocess. */
+  static readonly layer = (
+    bash: (command: string) => Effect.Effect<CommandOutcome, Error>,
+  ): Layer.Layer<CommandRunner> => Layer.succeed(CommandRunner, { bash })
+
+  static Live = Layer.effect(
+    CommandRunner,
+    Effect.gen(function* () {
+      const { root } = yield* Host
+      const executor = yield* CommandExecutor.CommandExecutor
+      return {
+        bash: (command: string) =>
+          Effect.scoped(
+            Effect.gen(function* () {
+              const process = yield* executor.start(
+                Command.make("bash", "-c", command).pipe(
+                  Command.workingDirectory(root),
+                  Command.stdout("pipe"),
+                  Command.stderr("pipe"),
+                ),
+              )
+              const collect = (stream: typeof process.stdout) =>
+                stream.pipe(Stream.decodeText(), Stream.mkString)
+              const [stdout, stderr, status] = yield* Effect.all(
+                [
+                  collect(process.stdout),
+                  collect(process.stderr),
+                  // A signal death fails process.exitCode; map to null to match spawnSync's contract.
+                  process.exitCode.pipe(
+                    Effect.map((code): number | null => code),
+                    Effect.catchAll(() => Effect.succeed(null)),
+                  ),
+                ],
+                { concurrency: "unbounded" },
+              )
+              return { status, output: `${stdout}${stderr}`, stdout, stderr }
+            }),
+          ).pipe(Effect.mapError((e) => (e instanceof Error ? e : new Error(String(e))))),
+      }
+    }),
+  )
+}

package/src/platform/Commentary.test.ts

@@ -0,0 +1,126 @@
+import { Effect } from "effect"
+import { describe, expect, it } from "vitest"
+import { GtdError, Narrator, renderFailure } from "./Commentary.js"
+import { PRESENTATION_FAILURE_WARNING } from "../emit/index.js"
+
+describe("Narrator", () => {
+  it("is a no-op writer when built with verbose: false", async () => {
+    const lines: string[] = []
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const narrator = yield* Narrator
+        yield* narrator.narrate("hello")
+      }).pipe(Effect.provide(Narrator.layer((chunk) => lines.push(chunk), false))),
+    )
+    expect(lines).toEqual([])
+  })
+
+  it("writes each narrated line, newline-terminated, when verbose: true", async () => {
+    const lines: string[] = []
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const narrator = yield* Narrator
+        yield* narrator.narrate("rest resolved: build.review.closing")
+        yield* narrator.narrate("config: module /repo/gtd.config.ts")
+      }).pipe(Effect.provide(Narrator.layer((chunk) => lines.push(chunk), true))),
+    )
+    expect(lines).toEqual([
+      "rest resolved: build.review.closing\n",
+      "config: module /repo/gtd.config.ts\n",
+    ])
+  })
+
+  it("warn writes to the sink even when verbose: false", async () => {
+    const lines: string[] = []
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const narrator = yield* Narrator
+        yield* narrator.warn("careful: something odd")
+      }).pipe(Effect.provide(Narrator.layer((chunk) => lines.push(chunk), false))),
+    )
+    expect(lines).toEqual(["careful: something odd\n"])
+  })
+
+  it("warn writes to the sink when verbose: true too", async () => {
+    const lines: string[] = []
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        const narrator = yield* Narrator
+        yield* narrator.warn("careful: something odd")
+      }).pipe(Effect.provide(Narrator.layer((chunk) => lines.push(chunk), true))),
+    )
+    expect(lines).toEqual(["careful: something odd\n"])
+  })
+})
+
+describe("GtdError", () => {
+  it("carries a message and a detail list, defaulting detail to empty", () => {
+    const bare = new GtdError("boom")
+    expect(bare.message).toBe("boom")
+    expect(bare.detail).toEqual([])
+
+    const detailed = new GtdError("boom", ["because X", "because Y"])
+    expect(detailed.message).toBe("boom")
+    expect(detailed.detail).toEqual(["because X", "because Y"])
+  })
+
+  it("is a genuine Error — every `error instanceof Error` normalization idiom still catches it", () => {
+    expect(new GtdError("boom")).toBeInstanceOf(Error)
+  })
+})
+
+describe("renderFailure", () => {
+  it("prefixes a bare message with 'gtd: '", () => {
+    expect(renderFailure(new Error("boom"))).toBe("gtd: boom")
+  })
+
+  it("does not double-prefix a message that already starts with 'gtd:'", () => {
+    expect(renderFailure(new Error("gtd: already prefixed"))).toBe("gtd: already prefixed")
+  })
+
+  it("does not double-prefix a message that already starts with 'gtd '", () => {
+    expect(renderFailure(new Error("gtd land: out of turn"))).toBe("gtd land: out of turn")
+  })
+
+  it("stringifies a non-Error thrown value", () => {
+    expect(renderFailure("just a string")).toBe("gtd: just a string")
+  })
+
+  it("prints a GtdError's detail lines, each indented two spaces, after the prefixed message", () => {
+    const error = new GtdError("gtd: bad config", ["testCommand: gtd.config.ts"])
+    expect(renderFailure(error)).toBe("gtd: bad config\n  testCommand: gtd.config.ts")
+  })
+
+  it("prints every detail line, in order, for a multi-detail GtdError", () => {
+    const error = new GtdError("boom", ["first", "second"])
+    expect(renderFailure(error)).toBe("gtd: boom\n  first\n  second")
+  })
+
+  it("a plain Error (the ~100 unmigrated sites) still renders as exactly one line", () => {
+    expect(renderFailure(new Error("plain failure"))).not.toContain("\n")
+  })
+
+  it("prints detail lines for an error shaped like GtdError but not an instance of it — duck-typed, not instanceof-checked, so src/platform/Git.ts's own equivalently-shaped error (which may not import GtdError) still renders its remediation", () => {
+    class LookalikeError extends Error {
+      readonly detail: readonly string[]
+      constructor(message: string, detail: readonly string[]) {
+        super(message)
+        this.detail = detail
+      }
+    }
+    const error = new LookalikeError("gtd: invalid ref", ["ref: some-ref"])
+    expect(error).not.toBeInstanceOf(GtdError)
+    expect(renderFailure(error)).toBe("gtd: invalid ref\n  ref: some-ref")
+  })
+})
+
+describe("the emitted script's own stderr shape stays cross-referenced here", () => {
+  // `Emit.ts`'s discarded-optional-failure warning is written by a SCRIPT gtd
+  // emits, not by gtd's own process — so it never goes through `renderFailure`
+  // — but it lands on the same commentary channel this module owns, so its
+  // wording is pinned alongside every other stderr shape rather than only in
+  // `Emit.test.ts`.
+  it("is gtd:-prefixed, matching this channel's own convention", () => {
+    expect(PRESENTATION_FAILURE_WARNING).toContain("gtd: presentation-only follow-up failed")
+  })
+})

package/src/platform/Commentary.ts

@@ -0,0 +1,92 @@
+import { Context, Effect, Layer } from "effect"
+
+/**
+ * One line of stderr commentary — `narrate` is gated entirely by how the
+ * layer was built, never by the call site; `warn` is its ungated
+ * counterpart, always written regardless of verbosity.
+ */
+export class Narrator extends Context.Tag("Narrator")<
+  Narrator,
+  {
+    readonly narrate: (line: string) => Effect.Effect<void>
+    readonly warn: (line: string) => Effect.Effect<void>
+  }
+>() {
+  /**
+   * `write` is the raw stderr sink (`CliIo.stderr` in production, so the
+   * in-memory `CliIo` used by `@inmem` e2e scenarios captures narration into
+   * the exact same buffer it already captures errors into). `verbose` gates
+   * every `narrate` line at construction time — the resulting service is a
+   * no-op writer when `false`, never a per-call check a narrating call site
+   * has to remember to make. `warn` bypasses that gate unconditionally.
+   */
+  static readonly layer = (
+    write: (chunk: string) => void,
+    verbose: boolean,
+  ): Layer.Layer<Narrator> =>
+    Layer.succeed(Narrator, {
+      narrate: (line) =>
+        Effect.sync(() => {
+          if (verbose) write(`${line}\n`)
+        }),
+      warn: (line) => Effect.sync(() => write(`${line}\n`)),
+    })
+}
+
+/**
+ * An error carrying REMEDIATION alongside its message — the offending config
+ * key and the layer it came from, a corrupted ref's name, a missing binary's
+ * resolved `$PATH`. Only two families construct one (see
+ * `src/workflow/load.ts` and `src/ui/Tls.ts`) — every other `Error` site
+ * stays a plain `Error` and renders as the single `gtd: `-prefixed line it
+ * always has.
+ */
+export class GtdError extends Error {
+  readonly detail: readonly string[]
+
+  constructor(message: string, detail: readonly string[] = []) {
+    super(message)
+    this.name = "GtdError"
+    this.detail = detail
+  }
+}
+
+/**
+ * A `GtdError` that names how gtd was INVOKED, not what it did — `Cli.ts`'s
+ * `report` maps this to `EXIT_USAGE_ERROR` alongside `SelectorUsageError`,
+ * rather than the `EXIT_RUNTIME_ERROR` every plain `GtdError` gets. `gtd ui`
+ * refusing to start on a step it cannot render is the one constructor today
+ * (see `ui/Server.ts`).
+ */
+export class GtdUsageError extends GtdError {
+  constructor(message: string, detail: readonly string[] = []) {
+    super(message, detail)
+    this.name = "GtdUsageError"
+  }
+}
+
+/**
+ * Structurally, not nominally: an error carrying a `detail: readonly
+ * string[]` — `GtdError`'s shape, matched WITHOUT an `instanceof GtdError`
+ * check, because `src/platform/Git.ts` reports a corrupted ref's remediation
+ * lines through its own equivalently-shaped local error class.
+ */
+const hasDetail = (error: unknown): error is { readonly detail: readonly string[] } =>
+  typeof error === "object" &&
+  error !== null &&
+  "detail" in error &&
+  Array.isArray((error as { detail: unknown }).detail)
+
+/**
+ * The stderr text for a CLI failure: a `gtd: ` prefix UNLESS the message
+ * already carries one, then one two-space-indented line per `GtdError`
+ * detail (none, for a plain `Error`) — unconditional, at every verbosity.
+ * Most gtd errors are authored with a `gtd:`/`gtd <cmd>:` prefix of their own,
+ * so a blind prepend would produce a doubled `gtd: gtd: …`.
+ */
+export const renderFailure = (error: unknown): string => {
+  const message = error instanceof Error ? error.message : String(error)
+  const prefixed = /^gtd[: ]/.test(message) ? message : `gtd: ${message}`
+  const detail = hasDetail(error) ? error.detail : []
+  return [prefixed, ...detail.map((line) => `  ${line}`)].join("\n")
+}

package/src/platform/Git.test.ts

@@ -0,0 +1,50 @@
+import { Cause, Effect, Exit } from "effect"
+import { describe, expect, it } from "vitest"
+import { InvalidRefError, resolvedRefOrCorrupted } from "./Git.js"
+import { gitTiers, runGitServiceContract, runGitScriptContract } from "../testkit/index.js"
+
+/**
+ * The `GitOperations` contract, run identically against both the Live and
+ * InMemory tiers (`src/testkit/GitTiers.ts`) — 20 operations × 2 tiers.
+ */
+for (const makeTier of gitTiers) {
+  const name = makeTier().name
+  describe(`GitService [${name}]`, () => {
+    runGitServiceContract(makeTier)
+  })
+}
+
+/**
+ * `resolveRef`'s own validation, unit-tested directly rather than through a
+ * real git repo — this is the rarer, defensive branch where the command
+ * SUCCEEDS but its output isn't a 40-hex-char hash: a corrupted ref, this
+ * module's own `InvalidRefError`.
+ */
+describe("resolvedRefOrCorrupted", () => {
+  it("succeeds with a genuine 40-hex-char hash", async () => {
+    const hash = "a".repeat(40)
+    const result = await Effect.runPromise(resolvedRefOrCorrupted("HEAD", hash))
+    expect(result).toBe(hash)
+  })
+
+  it("fails with an InvalidRefError naming the ref, for anything else", async () => {
+    const exit = await Effect.runPromiseExit(resolvedRefOrCorrupted("some-ref", "not-a-hash"))
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      const error = Cause.squash(exit.cause)
+      expect(error).toBeInstanceOf(InvalidRefError)
+      expect(error).toHaveProperty("message", "Invalid ref: some-ref")
+      if (error instanceof InvalidRefError) expect(error.detail).toEqual(["ref: some-ref"])
+    }
+  })
+})
+
+/**
+ * `GitScript.ts`'s bash builders, run through real `bash` against a real git
+ * repo — the Live tier only, since the in-memory fake's root has no shell to
+ * execute against. Asserts the same 9 writer postconditions as the contract
+ * above, driven via the emitted script instead of the `GitOperations` port.
+ */
+describe("GitScript", () => {
+  runGitScriptContract()
+})