@pmelab/gtd 64.3.0 → 66.0.0

package/src/platform/RetainedHistory.ts

@@ -4,6 +4,9 @@ import type { GitOperations } from "./Git.js"
 /** Per-worktree (`refs/worktree/gtd/*`) so linked worktrees sharing one `.git` don't clobber each other's retained history. */
 export const HISTORY_REF = "refs/worktree/gtd/history"
 
+/** Set by an abandon that left `gtd/<b>` for `<b>`: only then does restore recreate `gtd/<b>`. */
+export const RESUME_BRANCH_REF = "refs/worktree/gtd/history-branch"
+
 /** One ref per finished process, kept past the branch's deletion; distinct from the per-worktree `HISTORY_REF`. */
 export const PROCESS_HISTORY_PREFIX = "refs/gtd/history/"
 

package/src/platform/SyncIo.ts

@@ -4,6 +4,8 @@ export interface FileInfo {
   readonly type: "file" | "directory" | "symlink" | "other"
   /** `undefined` where the platform has no POSIX user ids. */
   readonly uid: number | undefined
+  /** Any execute bit set; `undefined` where the platform has none. */
+  readonly executable?: boolean
 }
 
 /**

package/src/platform/Workspace.test.ts

@@ -1,4 +1,5 @@
 import {
+  chmodSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
@@ -38,6 +39,7 @@ interface WorkspaceTier {
   readonly root: string
   readonly writeWorking: (path: string, content: string) => void
   readonly commit: (path: string, content: string) => void
+  readonly chmod: (path: string, executable: boolean) => void
   readonly provide: <A>(eff: Effect.Effect<A, Error, Workspace>) => Promise<A>
   readonly dispose: () => void
 }
@@ -70,6 +72,7 @@ const makeLiveTier = (): WorkspaceTier => {
       gitExecIn(root, "add", "-A")
       gitExecIn(root, "commit", "-m", `commit ${path}`)
     },
+    chmod: (path, executable) => chmodSync(join(root, path), executable ? 0o755 : 0o644),
     provide: (eff) => Effect.runPromise(eff.pipe(Effect.provide(workspaceLayer))),
     dispose: () => rmSync(root, { recursive: true, force: true }),
   }
@@ -86,6 +89,7 @@ const makeInMemTier = (): WorkspaceTier => {
       repo.writeFile(path, content)
       repo.seedCommit(`commit ${path}`)
     },
+    chmod: (path, executable) => repo.setExecutable(path, executable),
     provide: (eff) =>
       Effect.runPromise(eff.pipe(Effect.provide(Layer.succeed(Workspace, workspaceOps)))),
     dispose: () => {},
@@ -232,6 +236,39 @@ for (const { name, make } of tiers) {
       await expect(attempt).rejects.toThrow(/repo-relative paths only/)
     })
 
+    it("modeSync reports committed and working-tree modes, kept across an overwrite", async () => {
+      t = make()
+      t.commit("a.sh", "echo\n")
+      t.chmod("a.sh", true)
+      const modes = await t.provide(
+        Effect.gen(function* () {
+          const workspace = yield* Workspace
+          const committed = workspace.modeSync("HEAD").get("a.sh")
+          const chmodded = workspace.modeSync(undefined).get("a.sh")
+          t.writeWorking("a.sh", "echo 2\n")
+          return [committed, chmodded, workspace.modeSync(undefined).get("a.sh")]
+        }),
+      )
+      expect(modes).toEqual(["100644", "100755", "100755"])
+    })
+
+    it.runIf(name === "Live")(
+      "modeSync reads only the owner execute bit, as git does",
+      async () => {
+        t = make()
+        t.commit("a.sh", "echo\n")
+        t.writeWorking("a.sh", "echo 2\n")
+        chmodSync(join(t.root, "a.sh"), 0o654)
+        const mode = await t.provide(
+          Effect.gen(function* () {
+            return (yield* Workspace).modeSync(undefined).get("a.sh")
+          }),
+        )
+        gitExecIn(t.root, "add", "a.sh")
+        expect(mode).toBe(gitExecIn(t.root, "ls-files", "-s", "a.sh").split(" ")[0])
+      },
+    )
+
     it("atPath reads an absolute path INSIDE root, the same content readSync's relative form sees", async () => {
       t = make()
       t.writeWorking("nested/a.txt", "inside\n")

package/src/platform/Workspace.ts

@@ -150,6 +150,16 @@ const applyRawDiff = (tree: Map<string, string>, entries: readonly RawDiffEntry[
   }
 }
 
+/** `git ls-tree -r -z --full-tree <ref>`'s output, parsed into `path → mode`. */
+const parseLsTreeModes = (out: string): Map<string, string> => {
+  const modes = new Map<string, string>()
+  for (const record of out.split("\0")) {
+    const tab = record.indexOf("\t")
+    if (tab !== -1) modes.set(record.slice(tab + 1), record.slice(0, tab).split(" ")[0]!)
+  }
+  return modes
+}
+
 /** `git ls-tree -r -z --full-tree <ref>`'s output, parsed into `path → blob id`. */
 const parseLsTree = (out: string): Map<string, string> => {
   const entries = new Map<string, string>()
@@ -227,6 +237,8 @@ export interface WorkspaceOps {
    * reader compares contents instead.
    */
   readonly worktreeSync: () => ReadonlyMap<string, string | undefined>
+  /** Every path's git file mode (`100644`, `100755`, …) at `ref`, or in the working tree as `git add -A` would store it when `ref` is `undefined`. */
+  readonly modeSync: (ref: string | undefined) => ReadonlyMap<string, string>
   /**
    * `hash → (path → blob id)` for `base` (when given) and every one of
    * `commits`, in ONE call regardless of how many commits that is: a single
@@ -528,6 +540,29 @@ const makeWorkspaceOps = (
     return new Map([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
   }
 
+  const modeSync = (ref: string | undefined): ReadonlyMap<string, string> => {
+    const modes = parseLsTreeModes(gitSync(["ls-tree", "-r", "-z", "--full-tree", ref ?? "HEAD"]))
+    if (ref !== undefined) return modes
+    const status = gitSync([
+      "status",
+      "--porcelain=v1",
+      "-z",
+      "--untracked-files=all",
+      "--no-renames",
+      "--ignore-submodules=none",
+    ])
+    for (const record of status.split("\0")) {
+      if (record.length < 4) continue
+      const path = record.slice(3).replace(/\/$/, "")
+      const stat = io.lstat(paths.join(root, path))
+      if (stat === undefined) modes.delete(path)
+      else if (stat.type === "symlink") modes.set(path, "120000")
+      else if (stat.type === "directory") modes.set(path, "160000")
+      else modes.set(path, stat.executable === true ? "100755" : "100644")
+    }
+    return modes
+  }
+
   /** A submodule's (or embedded repository's) checked-out commit — what `git add` records for it. */
   const gitlinkOf = (path: string): string | undefined => {
     try {
@@ -547,6 +582,7 @@ const makeWorkspaceOps = (
   return {
     treeSync,
     worktreeSync,
+    modeSync,
     episodeTrees,
     readSync,
     read: (path) => Effect.try({ try: () => readSync(path), catch: toError }),

package/src/platform/index.ts

@@ -31,6 +31,7 @@ export * as NodeServices from "./NodeServices.js"
 export { loopLogPath } from "./WorktreeState.js"
 export {
   HISTORY_REF,
+  RESUME_BRANCH_REF,
   keptRef,
   processHistoryRef,
   PROCESS_HISTORY_PREFIX,

package/src/replay/Replay.test.ts

@@ -15,6 +15,7 @@ import {
   refuse,
   restart,
   run,
+  ship,
   scope,
   threads,
   type Flow,
@@ -647,6 +648,14 @@ describe("replay", () => {
     expect(outcome.kind === "failed" && outcome.message).toContain("shell script string")
   })
 
+  it("fails a ship step with an empty message", async () => {
+    const wf = async () => {
+      await ship("shipping", "  ")
+    }
+    const outcome = await replayOf(wf, new History())
+    expect(outcome.kind === "failed" && outcome.message).toContain("non-empty commit message")
+  })
+
   it("fails a flow that awaits something other than a step", async () => {
     const waiting = async () => {
       await new Promise((resolve) => setTimeout(resolve, 50))

package/src/replay/Replay.ts

@@ -20,7 +20,7 @@ import {
   threads,
 } from "../steering/index.js"
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
-import { globMatches, PIN_PATH } from "../wire/index.js"
+import { globMatches, PIN_PATH, RUN_FAILED_PATH } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
 import { diffTrees, isEmptyDiff, withoutPath, type TreeView } from "./Tree.js"
 import {
@@ -60,6 +60,8 @@ export interface Episode {
 export interface PendingTurn {
   readonly tree: TreeView
   readonly verdicts?: readonly JudgeVerdict[]
+  /** What a pending ship step resolves to: a stand-in hash when it will ship, the real one exists only once it landed. */
+  readonly shipped?: string
 }
 
 export interface ReplayInput {
@@ -90,7 +92,13 @@ export type StepKind = Exclude<StepRequest["kind"], "restart">
 type Actor = "agent" | "human" | "check" | "judge"
 
 const actorOfKind = (kind: StepKind): Actor =>
-  kind === "run" ? "check" : kind === "agent" ? "agent" : kind === "human" ? "human" : "judge"
+  kind === "run" || kind === "ship"
+    ? "check"
+    : kind === "agent"
+      ? "agent"
+      : kind === "human"
+        ? "human"
+        : "judge"
 
 /** One step replay reached, completed or not. */
 export interface ReachedStep {
@@ -314,12 +322,53 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // The option keys each step accepts. A gtd.config.ts is evaluated without a
 // type check, so a misspelt key would otherwise be silently ignored.
 const KNOWN_OPTIONS: Readonly<Record<StepKind, ReadonlySet<string>>> = {
-  agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
+  agent: new Set([
+    ...STEERING_OPTIONS,
+    "model",
+    "system",
+    "allowEmpty",
+    "keep",
+    "validate",
+    "cap",
+    "exhausted",
+    "correction",
+  ]),
   human: new Set([...STEERING_OPTIONS, "message", "acceptClean", "approve"]),
-  run: new Set(STEERING_OPTIONS),
+  run: new Set([...STEERING_OPTIONS, "onFail"]),
+  ship: new Set(["label", "base"]),
   judge: new Set([...STEERING_OPTIONS, "message"]),
 }
 
+const validatorOptionFault = (
+  name: string,
+  options: Extract<StepRequest, { kind: "agent" }>["options"],
+): string | undefined => {
+  const { validate, cap, exhausted, correction } = options
+  const prefix = `gtd: step "${name}": `
+  const notFunction = Object.entries({ validate, exhausted, correction }).find(
+    ([, value]) => value !== undefined && typeof value !== "function",
+  )
+  if (notFunction !== undefined)
+    return `${prefix}${notFunction[0]} must be a function in agent() options`
+  if (cap !== undefined && !(Number.isInteger(cap) && cap > 0)) {
+    return `${prefix}cap must be a positive integer in agent() options`
+  }
+  if (validate !== undefined && options.keep === true) {
+    return `${prefix}validate cannot be combined with keep: true — a kept turn is set aside, so there is no landed result to validate`
+  }
+  return undefined
+}
+
+const restsOnFail = (step: ReachedStep): boolean =>
+  step.request.kind === "run" && step.request.options.onFail === "rest"
+
+const onFailFault = (step: ReachedStep): string | undefined =>
+  step.request.kind === "run" &&
+  step.request.options.onFail !== undefined &&
+  step.request.options.onFail !== "rest"
+    ? `gtd: step "${step.name}": onFail must be "rest" in run() options`
+    : undefined
+
 const unknownOptions = (step: ReachedStep): string | undefined => {
   const unknown = Object.keys(step.request.options).filter(
     (key) => !KNOWN_OPTIONS[step.kind].has(key),
@@ -454,12 +503,13 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
   const scoped = (name: string): string =>
     [...scopes.flatMap((s) => (s.name === undefined ? [] : [s.name])), name].join(".")
 
-  const isAttemptAt = (commit: ParsedCommit, name: string): boolean =>
+  const isAttemptAt = (commit: ParsedCommit, step: ReachedStep): boolean =>
     commit.parsed.step === undefined &&
     commit.parsed.parsed !== undefined &&
     commit.parsed.parsed.from === undefined &&
-    commit.parsed.parsed.to === name &&
-    isEmptyDiff(diffTrees(position.tree, commit.tree))
+    commit.parsed.parsed.to === step.name &&
+    (isEmptyDiff(diffTrees(position.tree, commit.tree)) ||
+      (restsOnFail(step) && commit.tree.read(RUN_FAILED_PATH) !== undefined))
 
   const advance = (next: Position): void => {
     previousPosition = position
@@ -469,13 +519,16 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
   const replyFor = (
     request: Exclude<StepRequest, { kind: "restart" }>,
     verdicts: readonly JudgeVerdict[],
+    shipped: string | undefined,
   ): unknown =>
     request.kind === "judge"
       ? {
           answers: answersFrom(verdicts, request.questions),
           truncated: judgeCuts.get(request) ?? [],
         }
-      : undefined
+      : request.kind === "ship"
+        ? shipped
+        : undefined
 
   const judgeCuts = new WeakMap<object, readonly string[]>()
 
@@ -636,7 +689,11 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
       )
     }
     const error =
-      unknownOptions(step) ?? approveConflict(step) ?? modeWithoutFile(step) ?? checkIdentity(step)
+      unknownOptions(step) ??
+      onFailFault(step) ??
+      approveConflict(step) ??
+      modeWithoutFile(step) ??
+      checkIdentity(step)
     return error === undefined ? undefined : { kind: "failed", message: error }
   }
 
@@ -670,7 +727,7 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
     expectNextOf(commit)
     skipPins()
     noteKept(step, commit)
-    return replyFor(step.request, commit.parsed.judge)
+    return replyFor(step.request, commit.parsed.judge, commit.parsed.shipped)
   }
 
   // A turn that ends a pinned process names the unpin, which is no step.
@@ -699,11 +756,15 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
       keptTips.set(step.name, { hash: "", before: position.tree, after: pending.tree })
     }
     advance({ hash: "", tree: keeping ? position.tree : pending.tree })
-    return replyFor(step.request, pending.verdicts ?? [])
+    return replyFor(step.request, pending.verdicts ?? [], pending.shipped)
   }
 
   const answer = (step: ReachedStep): unknown => {
-    while (cursor < commits.length && isAttemptAt(commits[cursor]!, step.name)) {
+    while (cursor < commits.length && isAttemptAt(commits[cursor]!, step)) {
+      // An attempt that recorded a failure carries its tree; an empty one changes nothing.
+      if (!isEmptyDiff(diffTrees(position.tree, commits[cursor]!.tree))) {
+        advance({ hash: commits[cursor]!.hash, tree: commits[cursor]!.tree })
+      }
       cursor++
       skipPins()
     }
@@ -718,19 +779,34 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
         marks,
       })
     }
+    if (restsOnFail(step) && input.pending.tree.read(RUN_FAILED_PATH) !== undefined) {
+      return finish({ kind: "rest", rest: step, trace, landed, marks })
+    }
     return landPending(step, input.pending)
   }
 
+  const bodyFault = (request: Exclude<StepRequest, { kind: "restart" | "agent" }>) => {
+    if (
+      request.kind === "ship" &&
+      (typeof request.message !== "string" || request.message.trim() === "")
+    ) {
+      return `gtd: step "${scoped(request.name)}": a ship() message is a non-empty commit message`
+    }
+    if (request.kind === "run" && typeof request.body !== "string") {
+      return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`
+    }
+    return undefined
+  }
+
   // gtd.config.ts is loaded without a type check.
   const requestFault = (request: Exclude<StepRequest, { kind: "restart" }>): string | undefined => {
     if (scoped(request.name).startsWith(ENGINE_PREFIX)) {
       return `gtd: step "${scoped(request.name)}": the "${ENGINE_PREFIX}" prefix is reserved for gtd's own beats — rename the step`
     }
-    if (request.kind === "run" && typeof request.body !== "string") {
-      return `gtd: step "${scoped(request.name)}": a run() body is a shell script string — decide in flow code, then render the script (see checkScript and friends)`
-    }
-    if (request.kind !== "agent") return undefined
+    if (request.kind !== "agent") return bodyFault(request)
     const name = scoped(request.name)
+    const optionFault = validatorOptionFault(name, request.options)
+    if (optionFault !== undefined) return optionFault
     if (request.options.keep === true) {
       // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.
       if ((request.options as { readonly allowEmpty?: unknown }).allowEmpty === true) {

package/src/replay/Trailers.ts

@@ -118,6 +118,10 @@ export interface CommitMessage {
   readonly pin: PinChange | undefined
   /** `Gtd-Anchor`, on a repin's commit: replay sets aside every commit after this one; a non-hash value is skipped. */
   readonly anchor: string | undefined
+  /** `Gtd-Shipped`, on a ship step's landing: the commit it put on the user's branch. */
+  readonly shipped: string | undefined
+  /** `Gtd-Tip`, on a shipped commit: the process commit whose tree it carries. */
+  readonly tip: string | undefined
   readonly format: number
 }
 
@@ -178,6 +182,8 @@ interface Trailers {
   approved: Approval | undefined
   pin: PinChange | undefined
   anchor: string | undefined
+  shipped: string | undefined
+  tip: string | undefined
   readonly judge: JudgeVerdict[]
   readonly marks: Mark[]
   readonly vars: Record<string, string>
@@ -228,6 +234,12 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
   "Gtd-Anchor": (value, into) => {
     if (HASH_RE.test(value)) into.anchor ??= value
   },
+  "Gtd-Shipped": (value, into) => {
+    if (HASH_RE.test(value)) into.shipped ??= value
+  },
+  "Gtd-Tip": (value, into) => {
+    if (HASH_RE.test(value)) into.tip ??= value
+  },
   "Gtd-Format": (value, into) => {
     if (FORMAT_RE.test(value)) into.format ??= Number(value)
   },
@@ -250,6 +262,8 @@ export const parseCommitMessage = (message: string): CommitMessage => {
     approved: undefined,
     pin: undefined,
     anchor: undefined,
+    shipped: undefined,
+    tip: undefined,
     judge: [],
     marks: [],
     vars: {},
@@ -282,6 +296,8 @@ export interface CommitSpec {
   readonly anchor?: string
   readonly branch?: string
   readonly version?: string
+  /** Written after `Gtd-Format`: a landing recording a ship an earlier, hook-rejected attempt already made. */
+  readonly shipped?: string
 }
 
 const sortedEntries = (record: Readonly<Record<string, string>> = {}): [string, string][] =>
@@ -309,6 +325,7 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     ...trailer("Branch", spec.branch),
     ...trailer("Version", spec.version),
     `Gtd-Format: ${HISTORY_FORMAT}`,
+    ...trailer("Shipped", spec.shipped),
   ]
   const subject = formatSubject(spec.actor, spec.to, spec.from)
   return `${subject}\n\n${lines.join("\n")}`

package/src/replay/Tree.ts

@@ -8,6 +8,8 @@ export interface TreeView {
   readonly paths: () => readonly string[]
   readonly read: (path: string) => string | undefined
   readonly id?: (path: string) => string | undefined
+  /** Git file mode; when both sides give one, a differing mode is a modification even with equal content. */
+  readonly mode?: (path: string) => string | undefined
 }
 
 export const treeFromRecord = (files: Readonly<Record<string, string>>): TreeView => ({
@@ -24,6 +26,9 @@ export interface TreeDiff {
 export const diffTrees = (before: TreeView, after: TreeView): TreeDiff => {
   // Blob ids only compare against blob ids; otherwise fall back to contents.
   const same = (path: string): boolean => {
+    if (before.mode !== undefined && after.mode !== undefined) {
+      if (before.mode(path) !== after.mode(path)) return false
+    }
     const a = before.id?.(path)
     const b = after.id?.(path)
     return a !== undefined && b !== undefined ? a === b : before.read(path) === after.read(path)

package/src/replay/index.ts

@@ -6,7 +6,7 @@ export {
   type ReachedStep,
   type ReplayOutcome,
 } from "./Replay.js"
-export { treeFromRecord, type TreeView } from "./Tree.js"
+export { diffTrees, treeFromRecord, type TreeView } from "./Tree.js"
 export {
   formatCommitMessage,
   formatStepId,

package/src/steering/FORMATS.md

@@ -17,7 +17,9 @@ read them.
   pointer is a hunk the human has read. A chunk's `Tick exactly one:` list is
   its decision. A `## Findings` or `## Walkthrough` heading groups the `###`
   chunks under it; a walkthrough chunk takes no decision. Any other `##` is a
-  chunk of its own.
+  chunk of its own. Under `## Findings` a location is a plain list item
+  (`- ./path`, `- ./path#start-end`) with no checkbox; a `- [ ]`/`- [x]` pointer
+  there is an error.
 - **`findings`**: the finding gate's file. `## ` entries, those under a
   `# Dropped as noise` heading being the noise; each holds exactly one
   `- [ ] fix` box. A ticked box fixes the finding; text below the box is the

package/src/steering/SteeringFormat.ts

@@ -17,6 +17,11 @@ export interface SteeringEdit {
 export interface SteeringAction {
   readonly title: string
   readonly edits: readonly SteeringEdit[]
+  /** A range the editor selects once the edits apply; absent means no reveal. */
+  readonly select?: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }
 }
 
 /** A go-to-definition target. `path` absent means "this same document" (a footnote jump); `character` defaults to 0. */
@@ -105,6 +110,12 @@ export interface SteeringViewThread {
   readonly waitingOn: "human" | "agent"
 }
 
+/** One labelled part of a node's drafted comment. */
+export interface SteeringViewSection {
+  readonly label: string
+  readonly body: readonly SteeringViewNode[]
+}
+
 /**
  * One node of a format's `view`: a generic container/item tree, the SAME
  * shape for every format. Deliberately never a closed per-format union — a
@@ -140,6 +151,8 @@ export interface SteeringViewNode {
    * (question); absent wherever `detail` itself is absent.
    */
   readonly detailInline?: readonly InlineNode[]
+  /** A review finding's drafted PR comment as labelled sections (What / Impact / Fix), when it has one. */
+  readonly comment?: readonly SteeringViewSection[]
   /** A file path this node points at, when it has one (a `review` hunk). */
   readonly path?: string
   /** A 1-based line in `path` this node points at, when it has one. */

package/src/steering/fixtures/review/sectioned.md

@@ -12,7 +12,7 @@ The parser keeps a lone `\r` as content.
 
 In the code:
 
-- [x] ./src/parse.ts#30-31 — where it is kept
+- ./src/parse.ts#30-31 — where it is kept
 
 Tick exactly one:
 

package/src/steering/fixtures/review/sectioned.read.json

@@ -62,7 +62,6 @@
           "path": "./src/parse.ts",
           "line": 30,
           "endLine": 31,
-          "checked": true,
           "detail": "where it is kept",
           "anchor": {
             "kind": "hunk",

package/src/steering/index.ts

@@ -47,6 +47,7 @@ export type {
   SteeringPointer,
   SteeringView,
   SteeringViewNode,
+  SteeringViewSection,
   SteeringViewThread,
 } from "./SteeringFormat.js"