@pmelab/gtd 23.2.0 → 24.1.0

package/src/platform/WorktreeState.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Coverage for `src/platform/WorktreeState.ts`'s `worktreeGitDir`/`loopLogPath`: an
+ * in-memory group pinning the `.git` resolution table (D1's own words in
+ * gtd#169), and a real-git group proving the resolver is byte-identical to
+ * `git rev-parse --git-dir` — including under a `GIT_DIR`/`GIT_WORK_TREE`
+ * pointed at an unrelated repo, the env-immunity property a driver's own
+ * `env -u` scrub is expected to provide.
+ */
+
+import { join } from "node:path"
+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 { InMemRepo, testLayers } from "../testkit/index.js"
+
+const provide = <A>(
+  eff: Effect.Effect<A, never, Host | Workspace>,
+  repo: InMemRepo,
+  opts: {
+    readonly root?: string
+    readonly env?: Readonly<Record<string, string | undefined>>
+  } = {},
+): Promise<A> => Effect.runPromise(eff.pipe(Effect.provide(testLayers(repo, opts))))
+
+describe("worktreeGitDir / loopLogPath [in-memory]", () => {
+  it("falls back to .git when the worktree has no .git entry at all", async () => {
+    const repo = new InMemRepo()
+    expect(await provide(worktreeGitDir, repo)).toBe(".git")
+    expect(await provide(loopLogPath, repo)).toBe(".git/gtd-loop.log")
+  })
+
+  it("follows an absolute gitdir: pointer (a linked worktree)", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile(".git", "gitdir: /abs/path\n")
+    expect(await provide(worktreeGitDir, repo)).toBe("/abs/path")
+    expect(await provide(loopLogPath, repo)).toBe(join("/abs/path", "gtd-loop.log"))
+  })
+
+  it("resolves a relative gitdir: pointer against the worktree root", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile(".git", "gitdir: ../shared/worktrees/x\n")
+    expect(await provide(worktreeGitDir, repo)).toBe(join("/repo", "../shared/worktrees/x"))
+  })
+
+  it("falls back to .git when the .git file has no gitdir: line", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile(".git", "not a gitdir pointer\n")
+    expect(await provide(worktreeGitDir, repo)).toBe(".git")
+  })
+
+  it("GTD_LOOP_LOG wins verbatim, even over a gitdir: pointer", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile(".git", "gitdir: /abs/path\n")
+    expect(
+      await provide(loopLogPath, repo, { env: { GTD_LOOP_LOG: "/elsewhere/custom.log" } }),
+    ).toBe("/elsewhere/custom.log")
+  })
+
+  it("treats an empty GTD_LOOP_LOG as unset", async () => {
+    const repo = new InMemRepo()
+    expect(await provide(loopLogPath, repo, { env: { GTD_LOOP_LOG: "" } })).toBe(
+      ".git/gtd-loop.log",
+    )
+  })
+
+  it("an absolute GIT_DIR names the git dir for the log path, even over a gitdir: pointer", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile(".git", "gitdir: /abs/pointer-path\n")
+    expect(await provide(loopLogPath, repo, { env: { GIT_DIR: "/elsewhere/gitdir" } })).toBe(
+      join("/elsewhere/gitdir", "gtd-loop.log"),
+    )
+  })
+
+  it("a relative GIT_DIR is joined against the repo root", async () => {
+    const repo = new InMemRepo()
+    expect(
+      await provide(loopLogPath, repo, { root: "/repo", env: { GIT_DIR: "../shared/gitdir" } }),
+    ).toBe(join("/repo", "../shared/gitdir", "gtd-loop.log"))
+  })
+
+  it("treats an empty GIT_DIR as unset, falling through to the pointer read", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile(".git", "gitdir: /abs/pointer-path\n")
+    expect(await provide(loopLogPath, repo, { env: { GIT_DIR: "" } })).toBe(
+      join("/abs/pointer-path", "gtd-loop.log"),
+    )
+  })
+
+  it("GTD_LOOP_LOG still wins verbatim over GIT_DIR", async () => {
+    const repo = new InMemRepo()
+    expect(
+      await provide(loopLogPath, repo, {
+        env: { GTD_LOOP_LOG: "/elsewhere/custom.log", GIT_DIR: "/elsewhere/gitdir" },
+      }),
+    ).toBe("/elsewhere/custom.log")
+  })
+
+  it("falls back to the literal .git when GIT_DIR is unset and the fake filesystem has no .git entry", async () => {
+    const repo = new InMemRepo()
+    expect(await provide(loopLogPath, repo)).toBe(".git/gtd-loop.log")
+  })
+})
+
+describe("worktreeGitDir [real git]", () => {
+  const gitExecIn = (dir: string, ...args: string[]): string =>
+    execSync(`git ${args.join(" ")}`, { cwd: dir, encoding: "utf8", stdio: "pipe" }).trim()
+
+  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 workspaceLayer = Workspace.Live.pipe(Layer.provide(Layer.merge(hostLayer, gitLayer)))
+    return Effect.runPromise(
+      worktreeGitDir.pipe(Effect.provide(Layer.mergeAll(hostLayer, workspaceLayer))),
+    )
+  }
+
+  it("matches git rev-parse --git-dir in the main repo and in a linked worktree", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-worktree-state-")))
+    gitExecIn(root, "init", "-q")
+    gitExecIn(root, "config", "user.email", "test@test.com")
+    gitExecIn(root, "config", "user.name", "Test")
+    gitExecIn(root, "config", "commit.gpgsign", "false")
+    gitExecIn(root, "commit", "--allow-empty", "-q", "-m", "init")
+
+    expect(await runIn(root)).toBe(gitExecIn(root, "rev-parse", "--git-dir"))
+
+    const siblingDir = `${root}-sibling`
+    gitExecIn(root, "worktree", "add", "-q", "-b", "sibling", siblingDir, "HEAD")
+    expect(await runIn(siblingDir)).toBe(gitExecIn(siblingDir, "rev-parse", "--git-dir"))
+  })
+
+  it("is immune to a GIT_DIR/GIT_WORK_TREE pointed at a third, unrelated repo", async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-worktree-state-")))
+    gitExecIn(root, "init", "-q")
+    gitExecIn(root, "config", "user.email", "test@test.com")
+    gitExecIn(root, "config", "user.name", "Test")
+    gitExecIn(root, "config", "commit.gpgsign", "false")
+    gitExecIn(root, "commit", "--allow-empty", "-q", "-m", "init")
+    const expected = await runIn(root)
+
+    const other = realpathSync(mkdtempSync(join(tmpdir(), "gtd-worktree-state-other-")))
+    gitExecIn(other, "init", "-q", "--bare")
+
+    const savedGitDir = process.env.GIT_DIR
+    const savedWorkTree = process.env.GIT_WORK_TREE
+    try {
+      process.env.GIT_DIR = other
+      process.env.GIT_WORK_TREE = root
+      expect(await runIn(root)).toBe(expected)
+    } finally {
+      if (savedGitDir === undefined) delete process.env.GIT_DIR
+      else process.env.GIT_DIR = savedGitDir
+      if (savedWorkTree === undefined) delete process.env.GIT_WORK_TREE
+      else process.env.GIT_WORK_TREE = savedWorkTree
+    }
+  })
+})

package/src/platform/WorktreeState.ts

@@ -0,0 +1,50 @@
+import { isAbsolute, join } from "node:path"
+import { Effect } from "effect"
+import { Host } from "./Host.js"
+import { Workspace } from "./Workspace.js"
+
+const GITDIR_POINTER = /^gitdir:\s*(.+)$/m
+
+/**
+ * The worktree's own git dir, resolved via the filesystem rather than a `git`
+ * subprocess — byte-identical to `git rev-parse --git-dir`. Never fails: a
+ * read failure or a `.git` file with no `gitdir:` line both fall back to
+ * `".git"`, which is also correct for the in-memory test tier.
+ */
+export const worktreeGitDir: Effect.Effect<string, never, Host | Workspace> = Effect.gen(
+  function* () {
+    const { root } = yield* Host
+    const workspace = yield* Workspace
+    const content = yield* workspace
+      .read(".git")
+      .pipe(Effect.catchAll(() => Effect.succeed(undefined)))
+    const pointer = content === undefined ? null : GITDIR_POINTER.exec(content)
+    if (pointer === null) return ".git"
+    const gitdir = pointer[1]!.trim()
+    return isAbsolute(gitdir) ? gitdir : join(root, gitdir)
+  },
+)
+
+/**
+ * The per-worktree loop log path `gtd next --json` reports as `log`.
+ * Precedence: `$GTD_LOOP_LOG` verbatim, then `$GIT_DIR` (so the log follows
+ * wherever git subprocesses actually write), else `worktreeGitDir`. `$GIT_DIR`
+ * is honored rather than guarded against on purpose — an inherited (not
+ * deliberately set) `GIT_DIR` will move the log path too, so a caller that
+ * doesn't want that (e.g. the e2e suite) must scrub it before invoking gtd.
+ * Advisory only — gtd neither creates nor truncates the file.
+ */
+export const loopLogPath: Effect.Effect<string, never, Host | Workspace> = Effect.gen(function* () {
+  const { root, env } = yield* Host
+  const override = env.GTD_LOOP_LOG
+  if (override !== undefined && override !== "") return override
+
+  const gitDirEnv = env.GIT_DIR
+  if (gitDirEnv !== undefined && gitDirEnv !== "") {
+    const gitDir = isAbsolute(gitDirEnv) ? gitDirEnv : join(root, gitDirEnv)
+    return join(gitDir, "gtd-loop.log")
+  }
+
+  const gitDir = yield* worktreeGitDir
+  return join(gitDir, "gtd-loop.log")
+})

package/src/platform/index.ts

@@ -0,0 +1,22 @@
+/**
+ * gtd's two ports onto its environment: `Workspace` (repo file content —
+ * working-tree reads/writes plus the read-at-ref path) and `Host` (root,
+ * 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
+ * code is synchronous, non-Effect code that cannot `yield*` — replay's flow
+ * reads are that exception, and use the `*Sync` members.
+ */
+export { Workspace, type WorkspaceOps } from "./Workspace.js"
+export { Host, type HostOps } from "./Host.js"
+export {
+  GitService,
+  type GitOperations,
+  type GitReaderOperations,
+  type GitWriterOperations,
+} from "./Git.js"
+export { Narrator, GtdError, GtdUsageError, renderFailure } from "./Commentary.js"
+export { CommandRunner } from "./CommandRunner.js"
+export { loopLogPath } from "./WorktreeState.js"
+export { HISTORY_REF, readRetainedHistory, restorability } from "./RetainedHistory.js"

package/src/replay/Access.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest"
+import { accessShapeFault, foldAccess } from "./Access.js"
+
+describe("foldAccess", () => {
+  it("adds the steering file to each restricted side, after the scope globs", () => {
+    expect(foldAccess({ read: ["docs/**"], write: ["src/**"] }, ".gtd/X.md", [])).toEqual({
+      read: ["docs/**", ".gtd/X.md"],
+      write: ["src/**", ".gtd/X.md"],
+    })
+  })
+
+  it("adds the paths of waiting code threads after the steering file", () => {
+    expect(foldAccess({ write: [] }, ".gtd/X.md", ["src/a.ts"])).toEqual({
+      read: null,
+      write: [".gtd/X.md", "src/a.ts"],
+    })
+  })
+
+  it("dedupes against scope globs and across additions", () => {
+    expect(foldAccess({ write: ["src/a.ts", ".gtd/X.md"] }, ".gtd/X.md", ["src/a.ts"])).toEqual({
+      read: null,
+      write: ["src/a.ts", ".gtd/X.md"],
+    })
+  })
+
+  it("leaves an unrestricted side null, whatever is added", () => {
+    expect(foldAccess({}, ".gtd/X.md", ["src/a.ts"])).toEqual({ read: null, write: null })
+    expect(foldAccess(undefined, ".gtd/X.md", [])).toEqual({ read: null, write: null })
+  })
+
+  it("adds nothing for a missing file", () => {
+    expect(foldAccess({ read: ["a"], write: ["b"] }, undefined, [])).toEqual({
+      read: ["a"],
+      write: ["b"],
+    })
+  })
+})
+
+describe("accessShapeFault", () => {
+  it("accepts {} and either side alone", () => {
+    expect(accessShapeFault({})).toBeUndefined()
+    expect(accessShapeFault({ read: [] })).toBeUndefined()
+    expect(accessShapeFault({ write: ["a/**"] })).toBeUndefined()
+  })
+
+  it("names what is wrong", () => {
+    expect(accessShapeFault("x")).toContain("must be an object")
+    expect(accessShapeFault(["a"])).toContain("must be an object")
+    expect(accessShapeFault({ write: "a" })).toContain("access.write must be an array")
+    expect(accessShapeFault({ read: [1] })).toContain("access.read must be an array")
+    expect(accessShapeFault({ exec: [] })).toContain('unknown access key "exec"')
+  })
+})

package/src/replay/Access.ts

@@ -0,0 +1,46 @@
+import type { AccessDef, ScopeAccess } from "../flows/index.js"
+
+const UNRESTRICTED: ScopeAccess = {}
+
+const withExtras = (
+  globs: readonly string[] | undefined,
+  extras: readonly string[],
+): readonly string[] | null => (globs === undefined ? null : [...new Set([...globs, ...extras])])
+
+/**
+ * Fold a step's own paths into a scope's access: each restricted side gets the
+ * steering `file`, then the code threads waiting on the agent. An unrestricted
+ * side stays `null`.
+ */
+export const foldAccess = (
+  scopeAccess: ScopeAccess | undefined,
+  file: string | undefined,
+  threadPaths: readonly string[],
+): AccessDef => {
+  const access = scopeAccess ?? UNRESTRICTED
+  const extras = [...(file === undefined ? [] : [file]), ...threadPaths]
+  return { read: withExtras(access.read, extras), write: withExtras(access.write, extras) }
+}
+
+/** The shape fault of a `scope()` `access` value, or `undefined` when well-formed. */
+export const accessShapeFault = (value: unknown): string | undefined => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return "access must be an object of { read?, write? } glob arrays"
+  }
+  for (const [side, globs] of Object.entries(value)) {
+    if (side !== "read" && side !== "write") return `unknown access key "${side}"`
+    if (globs === undefined) continue
+    if (!Array.isArray(globs) || globs.some((g) => typeof g !== "string")) {
+      return `access.${side} must be an array of glob strings`
+    }
+  }
+  return undefined
+}
+
+const sameGlobs = (a: readonly string[] | undefined, b: readonly string[] | undefined): boolean =>
+  a === undefined || b === undefined
+    ? a === b
+    : a.length === b.length && a.every((g, i) => g === b[i])
+
+export const sameAccess = (a: ScopeAccess | undefined, b: ScopeAccess | undefined): boolean =>
+  sameGlobs(a?.read, b?.read) && sameGlobs(a?.write, b?.write)

package/src/replay/Format.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest"
+import { formatFault } from "./Format.js"
+
+describe("the history format", () => {
+  it("accepts a history entirely in the current format", () => {
+    expect(formatFault([{ hash: "a".repeat(40), format: 1 }])).toBeUndefined()
+    expect(formatFault([])).toBeUndefined()
+  })
+
+  it("names the first foreign commit, the found and readable formats, and what to do", () => {
+    const fault = formatFault([
+      { hash: "a".repeat(40), format: 1 },
+      { hash: "b".repeat(40), format: 2 },
+      { hash: "c".repeat(40), format: 3 },
+    ])
+    expect(fault).toBe(
+      "gtd: commit bbbbbbb is written in history format 2, but this gtd reads format 1 — run a gtd release that reads format 2 to continue this process",
+    )
+  })
+})

package/src/replay/Format.ts

@@ -0,0 +1,14 @@
+// Bump only when what replay reads back out of git changes incompatibly — the
+// package version must not stand in for it, since most majors leave history
+// untouched. A bump that keeps reading the previous format widens the check below.
+export const HISTORY_FORMAT = 1
+
+const short = (hash: string): string => hash.slice(0, 7)
+
+export const formatFault = (
+  commits: readonly { readonly hash: string; readonly format: number }[],
+): string | undefined => {
+  const foreign = commits.find((c) => c.format !== HISTORY_FORMAT)
+  if (foreign === undefined) return undefined
+  return `gtd: commit ${short(foreign.hash)} is written in history format ${foreign.format}, but this gtd reads format ${HISTORY_FORMAT} — run a gtd release that reads format ${foreign.format} to continue this process`
+}