@pmelab/gtd 61.0.0 → 62.1.0

package/src/platform/PinFile.ts

@@ -0,0 +1,61 @@
+import { execFileSync } from "node:child_process"
+import { existsSync, readFileSync } from "node:fs"
+import { registerHooks } from "node:module"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+
+/** A process's pin as the launcher found it: the file's bytes and where its engine runs from. */
+export interface FoundPin {
+  readonly path: string
+  readonly bytes: Uint8Array
+}
+
+/**
+ * Where the launcher looks for a pin: the worktree's copy, else HEAD's — so
+ * the landing after an unpin beat deleted the file still runs on the pin.
+ */
+export type PinFile = () => FoundPin | undefined
+
+// `cwd`, as the engine's own root is: gtd runs only at the worktree root, and
+// a relocated `$GIT_DIR` leaves no `.git` to walk up to. A file that cannot be
+// read counts as no pin, so the launcher refuses it rather than crashing.
+export const livePinFile =
+  (cwd: string, path: string): PinFile =>
+  () => {
+    const file = join(cwd, path)
+    if (existsSync(file)) {
+      try {
+        return { path: file, bytes: readFileSync(file) }
+      } catch {
+        return { path: file, bytes: new Uint8Array() }
+      }
+    }
+    try {
+      const bytes = execFileSync("git", ["show", `HEAD:${path}`], {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+      return { path: file, bytes }
+    } catch {
+      return undefined
+    }
+  }
+
+/**
+ * Runs a pin's module as this process's main program. Node refuses an unknown
+ * extension, so a load hook serves the unpacked source under the pin's own
+ * URL — `import.meta.url` stays a file in the repository.
+ */
+export const runPinModule = async (path: string, source: string): Promise<void> => {
+  const url = pathToFileURL(path).href
+  // A pin read from HEAD has no file behind its URL, which Node's own resolve refuses.
+  registerHooks({
+    resolve: (specifier, context, nextResolve) =>
+      specifier === url ? { url, shortCircuit: true } : nextResolve(specifier, context),
+    load: (requested, context, nextLoad) =>
+      requested === url
+        ? { format: "module", source, shortCircuit: true }
+        : nextLoad(requested, context),
+  })
+  await import(url)
+}

package/src/platform/index.ts

@@ -29,3 +29,4 @@ export {
   readRetainedHistory,
   restorability,
 } from "./RetainedHistory.js"
+export { livePinFile, runPinModule, type PinFile } from "./PinFile.js"

package/src/replay/Trailers.test.ts

@@ -60,43 +60,6 @@ describe("the commit-message codec", () => {
     expect(parseCommitMessage(one).vars).toEqual({ a: "1", b: "2", c: "" })
   })
 
-  it("writes Gtd-Config trailers sorted by path, after Gtd-Var, and reads paths with spaces back", () => {
-    const message = formatCommitMessage({
-      actor: "human",
-      to: "x",
-      vars: { a: "1" },
-      config: { "lib/my flow.ts": "0123456789abcdef", "gtd.config.ts": "deadbeefdeadbeef" },
-    })
-    expect(message).toBe(
-      "gtd(human): x\n\nGtd-Var: a=1\nGtd-Config: deadbeefdeadbeef gtd.config.ts\nGtd-Config: 0123456789abcdef lib/my flow.ts\nGtd-Format: 2",
-    )
-    expect(parseCommitMessage(message).config).toEqual({
-      "gtd.config.ts": "deadbeefdeadbeef",
-      "lib/my flow.ts": "0123456789abcdef",
-    })
-  })
-
-  it("round-trips a Gtd-Config path that git or the trailer syntax would alter", () => {
-    const config = {
-      " lead.ts": "0123456789abcdef",
-      "trail.ts ": "0123456789abcdef",
-      '"q.ts': "0123456789abcdef",
-    }
-    const message = formatCommitMessage({ actor: "human", to: "x", config })
-    expect(message).toContain('Gtd-Config: 0123456789abcdef " lead.ts"')
-    expect(parseCommitMessage(message).config).toEqual(config)
-  })
-
-  it("ignores a Gtd-Config trailer without a 16-digit hex hash, without a path, or with a control character in its path", () => {
-    const read = (value: string) =>
-      parseCommitMessage(`gtd(human): x\n\nGtd-Config: ${value}`).config
-    expect(read("zzzzzzzzzzzzzzzz gtd.config.ts")).toEqual({})
-    expect(read("deadbeef gtd.config.ts")).toEqual({})
-    expect(read("deadbeefdeadbeef")).toEqual({})
-    expect(read("deadbeefdeadbeef a\x1b]0;x\x07.ts")).toEqual({})
-    expect(read('deadbeefdeadbeef "a\\u001b.ts"')).toEqual({})
-  })
-
   it("round-trips Gtd-Branch and Gtd-Version, after Gtd-Judge and before Gtd-Format", () => {
     const message = formatCommitMessage({
       actor: "agent",

package/src/replay/Trailers.ts

@@ -83,8 +83,6 @@ export interface CommitMessage {
   /** `Gtd-Mark`, in order; a malformed or control-character line is skipped. */
   readonly marks: readonly Mark[]
   readonly vars: Readonly<Record<string, string>>
-  /** Written only on a process's first commit. */
-  readonly config: Readonly<Record<string, string>>
   readonly reviewBase: string | undefined
   readonly cost: readonly CostEntry[]
   /** Written only on a process's finishing landing. */
@@ -120,20 +118,10 @@ const parseJson = (raw: string): unknown => {
 const TRAILER_RE = /^(Gtd-[A-Za-z-]+):[ \t]*(.*?)[ \t]*$/gm
 const COST_RE = /^([0-9]+(?:\.[0-9]+)?)(?:[ \t]+(.+))?$/
 const VAR_RE = /^([^=\s]+)=(.*)$/
-const CONFIG_RE = /^([0-9a-f]{16}) (.+)$/
-// A path git's message cleanup or the trailer syntax would alter travels as a
-// JSON string. A control character is refused on read: history written by
-// someone else must never put escape sequences on a terminal.
+// A control character is refused on read: history written by someone else
+// must never put escape sequences on a terminal.
 // eslint-disable-next-line no-control-regex -- the control range IS the point
 const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/
-const encodePath = (path: string): string =>
-  path.trim() !== path || path.startsWith('"') || CONTROL_CHARACTER.test(path)
-    ? JSON.stringify(path)
-    : path
-const decodePath = (raw: string): string | undefined => {
-  const path = raw.startsWith('"') ? parseJson(raw) : raw
-  return typeof path === "string" && path !== "" && !CONTROL_CHARACTER.test(path) ? path : undefined
-}
 const decodeApproval = (raw: string): Approval | undefined => {
   const parsed = parseJson(raw)
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
@@ -168,7 +156,6 @@ interface Trailers {
   readonly judge: JudgeVerdict[]
   readonly marks: Mark[]
   readonly vars: Record<string, string>
-  readonly config: Record<string, string>
   readonly cost: CostEntry[]
   format: number | undefined
 }
@@ -193,11 +180,6 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
     const kv = VAR_RE.exec(value)
     if (kv !== null) into.vars[kv[1]!] = kv[2]!
   },
-  "Gtd-Config": (value, into) => {
-    const entry = CONFIG_RE.exec(value)
-    const path = entry === null ? undefined : decodePath(entry[2]!)
-    if (path !== undefined) into.config[path] = entry![1]!
-  },
   "Gtd-Review-Base": (value, into) => {
     into.reviewBase ??= value.split(/\s/)[0]
   },
@@ -242,7 +224,6 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     judge: [],
     marks: [],
     vars: {},
-    config: {},
     cost: [],
     format: undefined,
   }
@@ -262,7 +243,6 @@ export interface CommitSpec {
   readonly workflow?: string
   readonly reviewBase?: string
   readonly vars?: Readonly<Record<string, string>>
-  readonly config?: Readonly<Record<string, string>>
   readonly cost?: { readonly cost: number; readonly model?: string }
   readonly judge?: readonly JudgeVerdict[]
   /** Written after `Gtd-Judge`, before `Gtd-Approved`. */
@@ -290,7 +270,6 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     ...trailer("Workflow", spec.workflow),
     ...trailer("Review-Base", spec.reviewBase),
     ...sortedEntries(spec.vars).map(([name, value]) => `Gtd-Var: ${name}=${value}`),
-    ...sortedEntries(spec.config).map(([path, hash]) => `Gtd-Config: ${hash} ${encodePath(path)}`),
     ...trailer("Cost", costValue(spec.cost)),
     ...(spec.judge ?? []).map((verdict) => `Gtd-Judge: ${JSON.stringify(verdict)}`),
     ...(spec.marks ?? []).map((m) => `Gtd-Mark: ${m.name}=${m.value}`),

package/src/step/planStart.test.ts

@@ -56,7 +56,6 @@ const start = (
         first: startRefusal === undefined ? { firstStep: "work" } : { refusal: startRefusal },
         commandLabel: req.commandLabel,
         vars: req.vars,
-        config: {},
       })
     }).pipe(Effect.provide(testLayers(repo))),
   )

package/src/step/planStart.ts

@@ -7,7 +7,6 @@ import {
   ownFlagRefusal,
   resolveStartVars,
   StartFlags,
-  type ConfigFingerprint,
   type ResolvedWorkflow,
 } from "../workflow/index.js"
 import { formatCommitMessage, formatSubject } from "../replay/index.js"
@@ -70,8 +69,7 @@ const checkOverrides = (
  * `gtd start <name>`: start a brand NEW process on a workflow, writing an
  * opening commit that names the workflow's first step and carries a
  * `Gtd-Workflow:` trailer, every process setting as a `Gtd-Var:` trailer, plus
- * a `Gtd-Review-Base:` trailer when the workflow fixes the process's diff base,
- * and a `Gtd-Config:` trailer per config file.
+ * and a `Gtd-Review-Base:` trailer when the workflow fixes the process's diff base.
  * All validation is a REFUSAL, not an Effect failure.
  */
 export const planStart = (
@@ -83,7 +81,6 @@ export const planStart = (
     readonly first: { readonly firstStep: string } | { readonly refusal: string }
     readonly commandLabel: string
     readonly vars: Record<string, string>
-    readonly config: ConfigFingerprint
   },
 ): Effect.Effect<
   StartOutcome,
@@ -136,7 +133,6 @@ export const planStart = (
       workflow: name,
       ...(base !== undefined ? { reviewBase: base } : {}),
       vars,
-      config: start.config,
     })
     const steps: readonly LandStep[] = [
       { kind: "gitWrite", write: { kind: "commitAll", message } },

package/src/twins/EmittedScriptRecognizer.ts

@@ -26,6 +26,7 @@ import {
   modeContradictionSkipNotice,
   OUTCOME_MARKER,
   pinScript,
+  repinScript,
   unpinScript,
 } from "../emit/index.js"
 import {
@@ -272,9 +273,9 @@ const recognizeGitBuilders = (repo: InMemRepo, block: string): BlockOutcome | un
 /** What the in-memory `gtd bundle` prints: a pin header, and no engine behind it. */
 const IN_MEMORY_PIN = "gtdpin 1 gtd in-memory\n"
 
-/** A pin or unpin beat's script. */
+/** A pin or unpin beat's script, or `gtd repin`'s. */
 const recognizePinScripts = (repo: InMemRepo, block: string): BlockOutcome | undefined => {
-  if (block === pinScript(PIN_PATH)) {
+  if (block === pinScript(PIN_PATH) || block === repinScript(PIN_PATH)) {
     repo.writeFile(PIN_PATH, IN_MEMORY_PIN)
     return { kind: "applied" }
   }

package/src/twins/PinFile.test.ts

@@ -0,0 +1,107 @@
+import { execFileSync } from "node:child_process"
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { livePinFile, type PinFile } from "../platform/index.js"
+import { InMemRepo } from "./index.js"
+import { inMemPinFile } from "./PinFile.js"
+
+const PIN = ".gtd/process.gtdpin"
+
+interface Tier {
+  readonly root: string
+  /** The pin a launcher starting at the root finds. */
+  readonly pinFile: () => PinFile
+  readonly write: (path: string, content: string) => void
+  readonly remove: (path: string) => void
+  readonly commit: () => void
+}
+
+const liveTier = (): Tier => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gtd-pinfile-")))
+  cleanups.push(() => rmSync(root, { recursive: true, force: true }))
+  const git = (...args: string[]) => execFileSync("git", args, { cwd: root, stdio: "ignore" })
+  git("init", "-q")
+  return {
+    root,
+    pinFile: () => livePinFile(root, PIN),
+    write: (path, content) => {
+      mkdirSync(dirname(join(root, path)), { recursive: true })
+      writeFileSync(join(root, path), content)
+    },
+    remove: (path) => rmSync(join(root, path)),
+    commit: () => {
+      git("add", "-A")
+      git("-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "c")
+    },
+  }
+}
+
+const inMemTier = (): Tier => {
+  const repo = new InMemRepo()
+  const root = "/repo"
+  return {
+    root,
+    pinFile: () => inMemPinFile(repo, root, PIN),
+    write: (path, content) => repo.writeFile(path, content),
+    remove: (path) => repo.deleteFile(path),
+    commit: () => repo.seedCommit("c"),
+  }
+}
+
+const cleanups: (() => void)[] = []
+afterEach(() => cleanups.splice(0).forEach((cleanup) => cleanup()))
+
+const text = (pinFile: PinFile) => {
+  const found = pinFile()
+  return found && { path: found.path, content: Buffer.from(found.bytes).toString() }
+}
+
+describe.each([
+  ["live", liveTier],
+  ["in-memory", inMemTier],
+])("PinFile contract: %s", (_, make) => {
+  it("finds nothing without a pin", () => {
+    const tier = make()
+    tier.write("README.md", "x")
+    tier.commit()
+    expect(text(tier.pinFile())).toBeUndefined()
+  })
+
+  it("finds the worktree's pin, committed or not", () => {
+    const tier = make()
+    tier.write(PIN, "pinned")
+    expect(text(tier.pinFile())).toEqual({ path: join(tier.root, PIN), content: "pinned" })
+  })
+
+  it("prefers the worktree's pin over HEAD's", () => {
+    const tier = make()
+    tier.write(PIN, "committed")
+    tier.commit()
+    tier.write(PIN, "rewritten")
+    expect(text(tier.pinFile())?.content).toBe("rewritten")
+  })
+
+  it("falls back to HEAD's pin once the worktree's is deleted", () => {
+    const tier = make()
+    tier.write(PIN, "committed")
+    tier.commit()
+    tier.remove(PIN)
+    expect(text(tier.pinFile())).toEqual({ path: join(tier.root, PIN), content: "committed" })
+  })
+})
+
+describe("livePinFile", () => {
+  it("reads an unreadable pin as no pin's bytes", () => {
+    const tier = liveTier()
+    tier.write(`${PIN}/inside`, "x")
+    expect(text(tier.pinFile())).toEqual({ path: join(tier.root, PIN), content: "" })
+  })
+
+  it("finds nothing outside a repository", () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "gtd-pinfile-")))
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }))
+    expect(livePinFile(dir, PIN)()).toBeUndefined()
+  })
+})

package/src/twins/PinFile.ts

@@ -0,0 +1,12 @@
+import { join } from "node:path"
+import type { PinFile } from "../platform/index.js"
+import type { InMemRepo } from "./InMemRepo.js"
+
+export const inMemPinFile =
+  (repo: InMemRepo, root: string, path: string): PinFile =>
+  () => {
+    const content = repo.readFile(path) ?? repo.fileAtRef("HEAD", path) ?? undefined
+    return content === undefined
+      ? undefined
+      : { path: join(root, path), bytes: Buffer.from(content) }
+  }

package/src/twins/index.ts

@@ -12,3 +12,4 @@ export { gitTiers, runGitServiceContract, runGitScriptContract, type GitTier } f
 export { strictGitOperations } from "./StrictGitOperations.js"
 export { fakeGitOperations } from "./FakeGitOperations.js"
 export { takePinBeat } from "./PinBeats.js"
+export { inMemPinFile } from "./PinFile.js"

package/src/workflow/fingerprint.ts

@@ -7,12 +7,12 @@ export type ConfigFingerprint = Readonly<Record<string, string>>
 
 const HASH_LENGTH = 16
 
-// A path the trailer cannot carry printably is never recorded, so it can never
+// A path with a control character is never recorded, so it can never
 // reach a terminal from history.
 // eslint-disable-next-line no-control-regex -- the control range IS the point
 const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f]/
 
-export const contentHash = (content: string | Buffer): string =>
+const contentHash = (content: string | Buffer): string =>
   createHash("sha256").update(content).digest("hex").slice(0, HASH_LENGTH)
 
 const realOr = (path: string): string => {

package/src/workflow/index.ts

@@ -33,5 +33,5 @@ export {
   type StateMode,
   type StateName,
 } from "./Workflow.js"
-export { changedConfigFiles, contentHash, type ConfigFingerprint } from "./fingerprint.js"
-export { EngineCore, pin, readPin } from "./pin.js"
+export type { ConfigFingerprint } from "./fingerprint.js"
+export { EngineCore, pin, pinHeader, PIN_FORMAT, readPin } from "./pin.js"

package/src/workflow/load.ts

@@ -17,7 +17,7 @@ import { Host, Workspace, type WorkspaceOps } from "../platform/index.js"
 import { compileConfig, type CompiledConfig } from "./compile.js"
 import { SETTING_NAME_RULE, isSettingName } from "./vars.js"
 import { ConfigDiscovery, WORKFLOW_MODULE, type WorkflowModule } from "./discovery.js"
-import { configFingerprint, type ConfigFingerprint } from "./fingerprint.js"
+import { changedConfigFiles, configFingerprint, type ConfigFingerprint } from "./fingerprint.js"
 import { PIN_KEY } from "../install/index.js"
 import {
   dedupeDiagnostics,
@@ -50,6 +50,8 @@ export interface ConfigOperations {
   readonly warnings: readonly Diagnostic[]
   /** The content hash of every file `gtd.config.ts`'s evaluation touched — itself plus any relative import — by path relative to the root. */
   readonly fingerprint: ConfigFingerprint
+  /** Inside a pin, the files it was bundled from that differ on disk now. */
+  readonly drift: readonly string[]
 }
 
 // Everything lives in `message` (not `GtdError.detail`) — `renderFailure`
@@ -204,6 +206,17 @@ export const load: Effect.Effect<
     fingerprint:
       pinned?.fingerprint ??
       configFingerprint(loaded.file.dependencyFiles, host.root, module.read ?? readFromDisk),
+    drift:
+      pinned === undefined
+        ? []
+        : changedConfigFiles(
+            pinned.fingerprint,
+            configFingerprint(
+              Object.keys(pinned.fingerprint).map((file) => resolvePath(host.root, file)),
+              host.root,
+              readFromDisk,
+            ),
+          ),
   }
 })
 

package/src/workflow/pin.ts

@@ -7,7 +7,7 @@ import { ownPackage, pinnedWorkflowSource } from "./load.js"
 import type { WorkflowModule } from "./discovery.js"
 
 /** Bumped when a launcher could no longer run an older pin the same way. */
-const PIN_FORMAT = 1
+export const PIN_FORMAT = 1
 
 /**
  * The engine a pin carries, as ES module source. Live, the `gtd.core.mjs` the
@@ -57,16 +57,24 @@ export const pin = (
     ])
   })
 
+/** A pin's header line, read without unpacking it; undefined when the bytes are no pin. */
+export const pinHeader = (
+  bytes: Uint8Array,
+): { readonly format: number; readonly version: string } | undefined => {
+  const end = bytes.indexOf(0x0a)
+  const header =
+    end < 0 ? null : /^gtdpin (\d+) gtd (\S+)$/.exec(Buffer.from(bytes.subarray(0, end)).toString())
+  return header === null ? undefined : { format: Number(header[1]), version: header[2]! }
+}
+
 /** A pin's header and module source. */
 export const readPin = (
   bytes: Uint8Array,
 ): { readonly format: number; readonly version: string; readonly source: string } => {
-  const end = bytes.indexOf(0x0a)
-  const header = /^gtdpin (\d+) gtd (\S+)$/.exec(Buffer.from(bytes.subarray(0, end)).toString())
-  if (end < 0 || header === null) throw new Error("not a gtd pin")
+  const header = pinHeader(bytes)
+  if (header === undefined) throw new Error("not a gtd pin")
   return {
-    format: Number(header[1]),
-    version: header[2]!,
-    source: gunzipSync(bytes.subarray(end + 1)).toString("utf8"),
+    ...header,
+    source: gunzipSync(bytes.subarray(bytes.indexOf(0x0a) + 1)).toString("utf8"),
   }
 }