@pmelab/gtd 24.2.0 → 24.3.0

package/src/cli/Output.ts

@@ -0,0 +1,68 @@
+import { Effect } from "effect"
+import { CommandRunner, GitService, Host, Narrator, Workspace } from "../platform/index.js"
+import { selectPath } from "../wire/index.js"
+import { ConfigDiscovery, ConfigService } from "../workflow/index.js"
+import type { ToolCommands } from "./ToolCommands.js"
+
+/**
+ * A command-level failure that should exit like a CLI usage error (2), not a
+ * generic runtime failure (1): an unknown `--json=<path>` selector, or a
+ * `gtd judge answer` verdict that fails to decode — malformed JSON on stdin,
+ * or one naming a question id the pending judgment never asked. Both are
+ * caller-input errors per `docs/cli.md`'s exit-code table, not a refusal
+ * about the resolved rest's own state.
+ */
+export class SelectorUsageError extends Error {}
+
+/** The `--json=<path>` select branch, shared by the emitting commands so none drift on the unknown-selector message. `absent` writes nothing and lets the caller's success path continue. */
+export const writeSelection = (
+  out: ArtifactOut,
+  fields: unknown,
+  path: string,
+): Effect.Effect<void, Error> =>
+  Effect.gen(function* () {
+    const selection = selectPath(fields, path)
+    if (selection.kind === "value") {
+      out.write(`${selection.text}\n`)
+    } else if (selection.kind === "unknown") {
+      return yield* Effect.fail(
+        new SelectorUsageError(
+          `gtd: unknown --json selector "${selection.path}" — see \`gtd --help\``,
+        ),
+      )
+    }
+  })
+
+/**
+ * `--json`'s three shapes: absent, bare (the whole document), or `--json=<path>`
+ * (one reduced value). See `src/wire/Select.ts` for how `select` is later resolved.
+ */
+export type JsonMode =
+  | { readonly kind: "off" }
+  | { readonly kind: "document" }
+  | { readonly kind: "select"; readonly path: string }
+
+/**
+ * The all-or-nothing stdout buffer every `run*Command` handler writes
+ * through instead of `io.stdout` directly. `flush()` is called exactly once,
+ * by `runCli`, after the command's Effect succeeds; on any failure `flush()`
+ * is never reached, so the buffer is simply discarded and nothing reaches
+ * `io.stdout`. `ui` is the one handler that calls `flush()` itself,
+ * ahead of blocking on `Effect.never` — since it blocks forever, `runCli`'s
+ * own flush-on-success would otherwise never fire and its output would never
+ * reach stdout.
+ */
+export interface ArtifactOut {
+  readonly write: (chunk: string) => void
+  readonly flush: () => void
+}
+
+export type CommandRequirements =
+  | GitService
+  | ConfigService
+  | ConfigDiscovery
+  | Workspace
+  | Host
+  | Narrator
+  | CommandRunner
+  | ToolCommands

package/src/cli/Program.test.ts

@@ -1697,6 +1697,9 @@ describe("runCommand — refuses in a repository with no commits", () => {
     judge: { kind: "judge" },
     judgeAnswer: { kind: "judgeAnswer" },
     judgeRun: { kind: "judgeRun", provider: "fixed" },
+    historyList: { kind: "historyList" },
+    historyShow: { kind: "historyShow", ref: "x" },
+    historyFetch: { kind: "historyFetch", remote: "origin" },
   }
 
   const stateKinds = (Object.keys(commandFor) as Command["kind"][]).filter(
@@ -1706,7 +1709,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"
 
-  it("derives exactly the thirteen non-standalone kinds — a canary for the table-driven cases below", () => {
+  it("derives exactly the sixteen non-standalone kinds — a canary for the table-driven cases below", () => {
     expect(stateKinds.sort()).toEqual(
       [
         "abandon",
@@ -1722,6 +1725,9 @@ describe("runCommand — refuses in a repository with no commits", () => {
         "ui",
         "judge",
         "judgeAnswer",
+        "historyList",
+        "historyShow",
+        "historyFetch",
       ].sort(),
     )
   })

package/src/cli/Program.ts

@@ -1,6 +1,5 @@
 import { Effect, Option, Schema } from "effect"
 import {
-  CommandRunner,
   GtdUsageError,
   Narrator,
   GitService,
@@ -89,6 +88,20 @@ import {
 } from "../emit/index.js"
 import { CONFIG_SCAFFOLD, renderBriefing } from "../install/index.js"
 import { ToolCommands, type SelfGtd } from "./ToolCommands.js"
+import {
+  SelectorUsageError,
+  writeSelection,
+  type ArtifactOut,
+  type CommandRequirements,
+  type JsonMode,
+} from "./Output.js"
+export {
+  SelectorUsageError,
+  type ArtifactOut,
+  type CommandRequirements,
+  type JsonMode,
+} from "./Output.js"
+import { runHistoryFetchCommand, runHistoryListCommand, runHistoryShowCommand } from "./History.js"
 
 /**
  * `Edge.ts`'s `Rest` is module-private (`.gtd/packages/05-step-core.md`
@@ -98,35 +111,6 @@ import { ToolCommands, type SelfGtd } from "./ToolCommands.js"
  */
 type Rest = Effect.Effect.Success<typeof currentRest>
 
-/**
- * A command-level failure that should exit like a CLI usage error (2), not a
- * generic runtime failure (1): an unknown `--json=<path>` selector, or a
- * `gtd judge answer` verdict that fails to decode — malformed JSON on stdin,
- * or one naming a question id the pending judgment never asked. Both are
- * caller-input errors per `docs/cli.md`'s exit-code table, not a refusal
- * about the resolved rest's own state.
- */
-export class SelectorUsageError extends Error {}
-
-/** The `--json=<path>` select branch, shared by all three emitting commands so none drift on the unknown-selector message. `absent` writes nothing and lets the caller's success path continue. */
-const writeSelection = (
-  out: ArtifactOut,
-  fields: unknown,
-  path: string,
-): Effect.Effect<void, Error> =>
-  Effect.gen(function* () {
-    const selection = selectPath(fields, path)
-    if (selection.kind === "value") {
-      out.write(`${selection.text}\n`)
-    } else if (selection.kind === "unknown") {
-      return yield* Effect.fail(
-        new SelectorUsageError(
-          `gtd: unknown --json selector "${selection.path}" — see \`gtd --help\``,
-        ),
-      )
-    }
-  })
-
 export type Command =
   | { readonly kind: "lsp" }
   | {
@@ -174,6 +158,9 @@ export type Command =
   | { readonly kind: "base" }
   | { readonly kind: "judge" }
   | { readonly kind: "judgeAnswer" }
+  | { readonly kind: "historyList" }
+  | { readonly kind: "historyShow"; readonly ref: string }
+  | { readonly kind: "historyFetch"; readonly remote: string }
   | {
       readonly kind: "judgeRun"
       readonly provider?: "fixed" | "jev" | "llm"
@@ -181,15 +168,6 @@ export type Command =
       readonly model?: string
     }
 
-/**
- * `--json`'s three shapes: absent, bare (the whole document), or `--json=<path>`
- * (one reduced value). See `src/wire/Select.ts` for how `select` is later resolved.
- */
-export type JsonMode =
-  | { readonly kind: "off" }
-  | { readonly kind: "document" }
-  | { readonly kind: "select"; readonly path: string }
-
 /**
  * What a command kind needs before it may run. `pure`/`removed` never reach
  * `io.layers()` at all (they resolve to `output`/`usage` plans). `state`
@@ -199,31 +177,6 @@ export type JsonMode =
  */
 export type Needs = "pure" | "removed" | "none" | "fs" | "state"
 
-/**
- * The all-or-nothing stdout buffer every `run*Command` handler writes
- * through instead of `io.stdout` directly. `flush()` is called exactly once,
- * by `runCli`, after the command's Effect succeeds; on any failure `flush()`
- * is never reached, so the buffer is simply discarded and nothing reaches
- * `io.stdout`. `ui` is the one handler that calls `flush()` itself,
- * ahead of blocking on `Effect.never` — since it blocks forever, `runCli`'s
- * own flush-on-success would otherwise never fire and its output would never
- * reach stdout.
- */
-export interface ArtifactOut {
-  readonly write: (chunk: string) => void
-  readonly flush: () => void
-}
-
-export type CommandRequirements =
-  | GitService
-  | ConfigService
-  | ConfigDiscovery
-  | Workspace
-  | Host
-  | Narrator
-  | CommandRunner
-  | ToolCommands
-
 const selfGtd = (): SelfGtd => {
   const script = process.argv[1]
   return script === undefined ? ["gtd"] : [process.execPath, script]
@@ -1289,6 +1242,12 @@ const dispatchVoidCommand = (
       return runJudgeAnswerCommand(json, out)
     case "judgeRun":
       return runJudgeRunCommand(command, out)
+    case "historyList":
+      return runHistoryListCommand(json, out)
+    case "historyShow":
+      return runHistoryShowCommand(command.ref, json, out)
+    case "historyFetch":
+      return runHistoryFetchCommand(command.remote, out)
   }
 }
 

package/src/edge/Edge.test.ts

@@ -1,9 +1,11 @@
-import { Effect, Exit } from "effect"
+import { Effect, Exit, Option } from "effect"
 import { describe, expect, it } from "vitest"
 import { runCli } from "../cli/index.js"
 import {
   currentRest,
+  closedRunAt,
   currentRun,
+  historyTrail,
   noProcessUnderway,
   renderRest,
   restAt,
@@ -16,6 +18,8 @@ import {
   UNATTRIBUTED_MODEL,
   type RestRequirements,
 } from "./Edge.js"
+import { GTD_VERSION } from "../install/index.js"
+import { processHistoryRef } from "../platform/index.js"
 import { GitService, Workspace, type GitOperations, type WorkspaceOps } from "../platform/index.js"
 import { formatCommitMessage, type CommitSpec } from "../replay/index.js"
 import {
@@ -1014,3 +1018,254 @@ describe("the pending working tree is read at most once per restAt, and never st
     expect(calls()).toBe(2)
   })
 })
+
+describe("closedRunAt", () => {
+  it("is the run summaryRun reads when HEAD is the tip", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    const tip = await land(repo, { "c.txt": "c\n" })
+    expect(await provide(closedRunAt(tip), repo)).toEqual(await provide(summaryRun, repo))
+  })
+
+  it("resolves the closed run with HEAD elsewhere", async () => {
+    const repo = repoWith(LINEAR)
+    const building = await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    const tip = await land(repo, { "c.txt": "c\n" })
+    const closed = await provide(closedRunAt(tip), repo)
+    repo.writeFile("d.txt", "d\n")
+    repo.commitAllWithPrefix("chore: unrelated")
+    const later = await provide(closedRunAt(tip), repo)
+    expect(later).toEqual(closed)
+    expect(later.closingHash).toBe(tip)
+    expect(later.startHash).toBe(building)
+  })
+})
+
+describe("finishing landings keep history", () => {
+  const landingOf = async (repo: InMemRepo, git?: GitOperations) => {
+    const rest = await provide(currentRest, repo)
+    const eff = snapshotFromRest(rest)
+    const snapshot = await (git === undefined ? provide(eff, repo) : provideWithGit(eff, git, repo))
+    const landing = snapshot.landing
+    if (landing.kind !== "commit") throw new Error(`expected commit, got ${landing.kind}`)
+    return landing
+  }
+
+  it("flow return: keeps refs/gtd/history/<startHash>, records version and branch", async () => {
+    const repo = repoWith(LINEAR)
+    const building = await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    repo.writeFile("c.txt", "c\n")
+    const landing = await landingOf(repo)
+    expect(landing.to).toBe("idle")
+    expect(landing.keepHistory).toBe(processHistoryRef(building))
+    expect(landing.spec.version).toBe(GTD_VERSION)
+    expect(landing.spec.branch).toBe(repo.branchName())
+  })
+
+  it("restart() is a finish too", async () => {
+    const repo = repoWith(`import { agent, human, restart } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await agent("building", "build-prompt")
+  await restart()
+}
+`)
+    const building = await land(repo, { "a.txt": "a\n" })
+    repo.writeFile("b.txt", "b\n")
+    const landing = await landingOf(repo)
+    expect(landing.to).toBe("idle")
+    expect(landing.keepHistory).toBe(processHistoryRef(building))
+  })
+
+  it("starting landings and mid-process landings carry no keepHistory and no new trailers", async () => {
+    const repo = repoWith(LINEAR)
+    repo.writeFile("a.txt", "a\n")
+    const starting = await landingOf(repo)
+    expect(starting.to).toBe("building")
+    expect(starting.keepHistory).toBeUndefined()
+    expect(starting.spec.version).toBeUndefined()
+    expect(starting.spec.branch).toBeUndefined()
+    await land(repo, { "a.txt": "a\n" })
+    repo.writeFile("b.txt", "b\n")
+    const mid = await landingOf(repo)
+    expect(mid.to).toBe("checking")
+    expect(mid.keepHistory).toBeUndefined()
+    expect(mid.spec.version).toBeUndefined()
+    expect(mid.spec.branch).toBeUndefined()
+  })
+
+  it("detached HEAD keeps history but records no branch", async () => {
+    const repo = repoWith(LINEAR)
+    const building = await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    repo.writeFile("c.txt", "c\n")
+    const detached: GitOperations = {
+      ...fakeGitOperations(repo),
+      currentBranch: () => Effect.succeed(Option.none()),
+    }
+    const landing = await landingOf(repo, detached)
+    expect(landing.keepHistory).toBe(processHistoryRef(building))
+    expect(landing.spec.version).toBe(GTD_VERSION)
+    expect(landing.spec.branch).toBeUndefined()
+  })
+
+  it("a --workflow process's entry is its opening commit", async () => {
+    const repo = repoWith(`import { agent, human } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await agent("building", "build-prompt")
+}
+
+export const side = async () => {
+  await agent("fixing", "fix-prompt")
+}
+`)
+    const opening = await enter(repo, "side")
+    repo.writeFile("a.txt", "a\n")
+    const landing = await landingOf(repo)
+    expect(landing.to).toBe("idle")
+    expect(landing.keepHistory).toBe(processHistoryRef(opening))
+  })
+
+  it("the landing script overwrites an existing ref with its own commit", async () => {
+    const repo = repoWith(LINEAR)
+    const building = await land(repo, { "a.txt": "a\n" })
+    await land(repo, { "b.txt": "b\n" })
+    const ref = processHistoryRef(building)
+    repo.updateRef(ref, building)
+    const tip = await land(repo, { "c.txt": "c\n" })
+    expect(repo.resolveRef(ref)).toBe(tip)
+  })
+})
+
+describe("historyTrail", () => {
+  const finished = async (config = LINEAR) => {
+    const repo = repoWith(config)
+    const building = await land(repo, { "a.txt": "a\n" })
+    const checking = await land(repo, { "b.txt": "b\n" })
+    const tip = await land(repo, { "c.txt": "c\n" })
+    return { repo, building, checking, tip }
+  }
+
+  it("replays every commit of the closed run, with HEAD elsewhere", async () => {
+    const { repo, building, checking, tip } = await finished()
+    repo.writeFile("d.txt", "d\n")
+    repo.commitAllWithPrefix("chore: unrelated")
+    const trail = await provide(historyTrail(tip), repo)
+    expect(trail.tip).toBe(tip)
+    expect(trail.ended).toBe("return")
+    expect(trail.steps.map((s) => s.hash)).toEqual([building, checking, tip])
+    expect(trail.steps[2]).toMatchObject({
+      subject: "gtd(agent): checking → idle",
+      actor: "agent",
+      from: "checking",
+      to: "idle",
+      verdicts: [],
+    })
+    expect(trail.steps[0]).toMatchObject({ actor: "human", to: "building" })
+  })
+
+  it("a restart() ends the trail as restart", async () => {
+    const repo = repoWith(`import { agent, human, restart } from "@pmelab/gtd/flows"
+
+export default async () => {
+  await human("idle")
+  await agent("building", "build-prompt")
+  await restart()
+}
+`)
+    await land(repo, { "a.txt": "a\n" })
+    const tip = await land(repo, { "b.txt": "b\n" })
+    expect((await provide(historyTrail(tip), repo)).ended).toBe("restart")
+  })
+
+  it("carries each judge verdict on the commit that recorded it", async () => {
+    const repo = repoWith(LINEAR)
+    await land(repo, { "a.txt": "a\n" })
+    const verdictCommit = commit(
+      repo,
+      {
+        actor: "agent",
+        from: "building",
+        to: "checking",
+        step: { name: "building", occurrence: 1 },
+        judge: [{ id: "q", answer: "yes", p: 0.9 }],
+      },
+      { "b.txt": "b\n" },
+    )
+    const tip = await land(repo, { "c.txt": "c\n" })
+    const trail = await provide(historyTrail(tip), repo)
+    expect(trail.steps.find((s) => s.hash === verdictCommit)?.verdicts).toEqual([
+      { id: "q", answer: "yes", p: 0.9 },
+    ])
+    expect(trail.steps.filter((s) => s.verdicts.length > 0)).toHaveLength(1)
+  })
+
+  it("records the version and warns about none while they match", async () => {
+    const { repo, tip } = await finished()
+    const trail = await provide(historyTrail(tip), repo)
+    expect(trail.version).toEqual({ recorded: GTD_VERSION, running: GTD_VERSION })
+    expect(trail.versionWarning).toBeUndefined()
+  })
+
+  const withTipMessage = (repo: InMemRepo, edit: (message: string) => string): GitOperations => {
+    const real = fakeGitOperations(repo)
+    return {
+      ...real,
+      lastCommitMessage: (ref) => Effect.map(real.lastCommitMessage(ref), edit),
+    }
+  }
+
+  it("warns, never refuses, when the recorded version differs", async () => {
+    const { repo, tip } = await finished()
+    const git = withTipMessage(repo, (m) =>
+      m.replace(`Gtd-Version: ${GTD_VERSION}`, "Gtd-Version: 0.0.1"),
+    )
+    const trail = await Effect.runPromise(
+      historyTrail(tip).pipe(
+        Effect.provideService(GitService, git),
+        Effect.provide(testLayers(repo, {})),
+      ),
+    )
+    expect(trail.version.recorded).toBe("0.0.1")
+    expect(trail.versionWarning).toContain("0.0.1")
+    expect(trail.versionWarning).toContain(GTD_VERSION)
+  })
+
+  it("a missing recorded version counts as different", async () => {
+    const { repo, tip } = await finished()
+    const git = withTipMessage(repo, (m) => m.replace(/Gtd-Version: .*\n?/, ""))
+    const trail = await Effect.runPromise(
+      historyTrail(tip).pipe(
+        Effect.provideService(GitService, git),
+        Effect.provide(testLayers(repo, {})),
+      ),
+    )
+    expect(trail.version.recorded).toBeUndefined()
+    expect(trail.versionWarning).toContain(GTD_VERSION)
+  })
+
+  it("refuses naming the config file that differs at the tip", async () => {
+    const { repo, tip } = await finished()
+    repo.writeFile("gtd.config.ts", `${LINEAR}\n// edited\n`)
+    repo.commitAllWithPrefix("chore: edit config")
+    const exit = await provideExit(historyTrail(tip), repo)
+    expect(Exit.isFailure(exit)).toBe(true)
+    expect(String(Exit.isFailure(exit) && exit.cause)).toContain("gtd.config.ts")
+  })
+
+  it("refuses naming a config file missing from the tip", async () => {
+    const { repo, tip } = await finished()
+    repo.writeFile("gtd.config.ts", `import "./extra.ts"\n${LINEAR}`)
+    repo.writeFile("extra.ts", "export {}\n")
+    repo.commitAllWithPrefix("chore: split config")
+    const exit = await provideExit(historyTrail(tip), repo)
+    expect(Exit.isFailure(exit)).toBe(true)
+    expect(String(Exit.isFailure(exit) && exit.cause)).toContain("gtd.config.ts")
+  })
+})