@pmelab/gtd 27.7.1 → 27.9.0

package/src/replay/Replay.test.ts

@@ -15,6 +15,7 @@ import {
   restart,
   run,
   scope,
+  slice,
   threads,
   type Flow,
   type ScopeAccess,
@@ -1210,3 +1211,171 @@ describe("human({ approve })", () => {
     expect(outcome.kind).toBe("rest")
   })
 })
+
+describe("slice()", () => {
+  const spansOf = (o: ReplayOutcome) => (o as { slices: unknown }).slices
+
+  it("records enteredAt and leftAt as the commit replay stood on", async () => {
+    const wf = async () => {
+      await human("a")
+      await slice("refactor", async () => {
+        await human("b")
+      })
+      await human("c")
+    }
+    const h = new History().land("human", "a", 1, "b").land("human", "b", 1, "c")
+    const outcome = await replayOf(wf, h)
+    expect(outcome).toMatchObject({ kind: "rest" })
+    expect(spansOf(outcome)).toEqual([
+      { name: "refactor", enteredAt: hashOf(1), leftAt: hashOf(2) },
+    ])
+  })
+
+  it("an ended outcome carries every span of the episode that just ended", async () => {
+    const wf = async () => {
+      await slice("one", async () => {
+        await human("a")
+      })
+      await slice("two", async () => {
+        await human("b")
+      })
+    }
+    const h = new History().land("human", "a", 1, "b").land("human", "b", 1, "done")
+    const outcome = await replayOf(wf, h)
+    expect(outcome).toMatchObject({ kind: "ended", via: "return" })
+    expect(spansOf(outcome)).toEqual([
+      { name: "one", enteredAt: hashOf(0), leftAt: hashOf(1) },
+      { name: "two", enteredAt: hashOf(1), leftAt: hashOf(2) },
+    ])
+  })
+
+  it("restart() inside a slice ends via restart with that span's leftAt undefined", async () => {
+    const wf = async () => {
+      await human("a")
+      await slice("risky", async () => {
+        await human("b")
+        await restart()
+      })
+    }
+    const h = new History().land("human", "a", 1, "b").land("human", "b", 1, "done")
+    const outcome = await replayOf(wf, h)
+    expect(outcome).toMatchObject({ kind: "ended", via: "restart" })
+    expect(spansOf(outcome)).toEqual([{ name: "risky", enteredAt: hashOf(1), leftAt: undefined }])
+  })
+
+  it("keeps leftAt undefined when the process rests inside the slice", async () => {
+    const wf = async () => {
+      await slice("refactor", async () => {
+        await human("a")
+      })
+    }
+    const outcome = await replayOf(wf, new History())
+    expect(spansOf(outcome)).toEqual([
+      { name: "refactor", enteredAt: hashOf(0), leftAt: undefined },
+    ])
+  })
+
+  it("records enteredAt === leftAt for a slice that landed no commit", async () => {
+    const wf = async () => {
+      await human("a")
+      await slice("empty", async () => undefined)
+      await human("b")
+    }
+    const h = new History().land("human", "a", 1, "b")
+    expect(spansOf(await replayOf(wf, h))).toEqual([
+      { name: "empty", enteredAt: hashOf(1), leftAt: hashOf(1) },
+    ])
+  })
+
+  it("prefixes no step name and ignores an enclosing scope", async () => {
+    const wf = async () => {
+      await scope("build", async () => {
+        await slice("refactor", async () => {
+          await human("gate")
+        })
+      })
+    }
+    const outcome = await replayOf(wf, new History())
+    expect(outcome).toMatchObject({ kind: "rest", rest: { name: "build.gate" } })
+    expect((spansOf(outcome) as { name: string }[])[0]!.name).toBe("refactor")
+  })
+
+  const failed = async (wf: Flow) => {
+    const outcome = await replayOf(wf, new History())
+    expect(outcome.kind).toBe("failed")
+    return (outcome as { message: string }).message
+  }
+
+  it.each(["Refactor", "step_1", "v2.api", ""])("refuses the name %j", async (name) => {
+    expect(await failed(async () => slice(name, async () => human("a")))).toBe(
+      `gtd: slice "${name}": name must match /^[a-z][a-z0-9-]*$/`,
+    )
+  })
+
+  it("accepts refactor-2", async () => {
+    const outcome = await replayOf(
+      async () => slice("refactor-2", async () => human("a")),
+      new History(),
+    )
+    expect(outcome.kind).toBe("rest")
+  })
+
+  it("refuses the reserved name main", async () => {
+    expect(await failed(async () => slice("main", async () => human("a")))).toBe(
+      'gtd: slice "main" is reserved for the implicit slice',
+    )
+  })
+
+  it("refuses nesting, also through scope()", async () => {
+    const message = 'gtd: slice "inner" is entered inside slice "outer" — slices do not nest'
+    expect(
+      await failed(async () => slice("outer", async () => slice("inner", async () => human("a")))),
+    ).toBe(message)
+    expect(
+      await failed(async () =>
+        slice("outer", async () => scope("s", async () => slice("inner", async () => human("a")))),
+      ),
+    ).toBe(message)
+  })
+
+  it("checks the name rule before main and nesting", async () => {
+    expect(
+      await failed(async () => slice("outer", async () => slice("Main", async () => human("a")))),
+    ).toBe('gtd: slice "Main": name must match /^[a-z][a-z0-9-]*$/')
+  })
+
+  it("lets a flow that caught an error from a slice enter another", async () => {
+    const wf = async () => {
+      try {
+        await slice("a", async () => {
+          throw new Error("boom")
+        })
+      } catch {}
+      await slice("b", async () => human("x"))
+    }
+    expect(await replayOf(wf, new History())).toMatchObject({ kind: "rest" })
+  })
+
+  it("refuses a non-string name", async () => {
+    expect(
+      await failed(async () => slice(undefined as unknown as string, async () => human("a"))),
+    ).toContain("name must match")
+  })
+
+  it("refuses a name entered twice, sequentially and from a loop", async () => {
+    const message =
+      'gtd: slice "again" is entered twice in this episode — a loop must sit inside its slice'
+    expect(
+      await failed(async () => {
+        await slice("again", async () => undefined)
+        await slice("again", async () => human("a"))
+      }),
+    ).toBe(message)
+    expect(
+      await failed(async () => {
+        for (let i = 0; i < 2; i++) await slice("again", async () => undefined)
+        await human("a")
+      }),
+    ).toBe(message)
+  })
+})

package/src/replay/Replay.ts

@@ -23,6 +23,7 @@ import {
 import { accessShapeFault, foldAccess, sameAccess } from "./Access.js"
 import { globMatches } from "../wire/index.js"
 import { refNameFault } from "./RefName.js"
+import { IMPLICIT_SLICE, SLICE_NAME, type SliceSpan } from "./Slices.js"
 import { diffTrees, isEmptyDiff, type TreeView } from "./Tree.js"
 import {
   formatStepId,
@@ -117,6 +118,7 @@ export type ReplayOutcome =
       readonly landed: ReachedStep | undefined
       /** Marks the flow made after the pending turn's step resolved; [] without a pending turn. */
       readonly marks: readonly Mark[]
+      readonly slices: readonly SliceSpan[]
     }
   | {
       readonly kind: "ended"
@@ -124,6 +126,8 @@ export type ReplayOutcome =
       readonly trace: readonly ReachedStep[]
       readonly landed: ReachedStep | undefined
       readonly marks: readonly Mark[]
+      /** Spans of the episode that just ended; a restart() inside a slice leaves its leftAt undefined. */
+      readonly slices: readonly SliceSpan[]
     }
   | { readonly kind: "divergence"; readonly message: string }
   | { readonly kind: "refused"; readonly message: string }
@@ -297,6 +301,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
   >()
   let landed: ReachedStep | undefined
   const marks: Mark[] = []
+  const slices: { name: string; enteredAt: string; leftAt: string | undefined }[] = []
   let outcome: ReplayOutcome | undefined
   let signal: (() => void) | undefined
   const settled = new Promise<void>((resolve) => {
@@ -558,7 +563,14 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
     const commit = commits[cursor]
     if (commit !== undefined) return consumeCommit(step, commit)
     if (input.pending === undefined || pendingUsed) {
-      return finish({ kind: "rest", rest: step, trace, landed, marks })
+      return finish({
+        kind: "rest",
+        rest: step,
+        trace,
+        landed,
+        marks,
+        slices: slices.map((s) => ({ ...s })),
+      })
     }
     return landPending(step, input.pending)
   }
@@ -603,7 +615,7 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
           kind: "divergence",
           message: `gtd: the flow ended, but commit ${short(commits[cursor]!.hash)} continues the episode — ${DIVERGED}`,
         }
-      : { kind: "ended", via, trace, landed, marks }
+      : { kind: "ended", via, trace, landed, marks, slices: slices.map((s) => ({ ...s })) }
 
   const changesSince = (hash: string): readonly Change[] => {
     const tree = treeAt(hash)
@@ -630,6 +642,34 @@ export const replay = async (input: ReplayInput): Promise<ReplayOutcome> => {
       scopes.pop()
       scopeCallIds.pop()
     },
+    enterSlice: (name) => {
+      if (outcome !== undefined) return
+      const fail = (message: string): never => {
+        void finish({ kind: "failed", message })
+        throw new Stop()
+      }
+      if (typeof name !== "string" || !SLICE_NAME.test(name)) {
+        fail(`gtd: slice "${name}": name must match ${SLICE_NAME}`)
+      }
+      if (name === IMPLICIT_SLICE) {
+        fail(`gtd: slice "${IMPLICIT_SLICE}" is reserved for the implicit slice`)
+      }
+      const open = slices.find((s) => s.leftAt === undefined)
+      if (open !== undefined) {
+        fail(`gtd: slice "${name}" is entered inside slice "${open.name}" — slices do not nest`)
+      }
+      if (slices.some((s) => s.name === name)) {
+        fail(
+          `gtd: slice "${name}" is entered twice in this episode — a loop must sit inside its slice`,
+        )
+      }
+      slices.push({ name, enteredAt: position.hash, leftAt: undefined })
+    },
+    leaveSlice: () => {
+      if (outcome !== undefined) return
+      const open = slices.find((s) => s.leftAt === undefined)
+      if (open !== undefined) open.leftAt = position.hash
+    },
     read: (path) => position.tree.read(path),
     glob: (pattern) => position.tree.paths().filter((path) => globMatches(path, pattern)),
     changes: () => changesBetween(previousPosition.tree, position.tree),

package/src/replay/Slices.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest"
+import { sliceRanges, type SliceSpan } from "./Slices.js"
+
+const span = (name: string, enteredAt: string, leftAt?: string): SliceSpan => ({
+  name,
+  enteredAt,
+  leftAt,
+})
+const running = { base: "B", tip: "T" }
+
+describe("sliceRanges", () => {
+  it("two adjacent spans: first from episode.base to its leftAt, second from there to episode.tip", () => {
+    expect(sliceRanges([span("a", "B", "c2"), span("b", "c2", "T")], running)).toEqual([
+      { name: "a", base: "B", tip: "c2", open: false },
+      { name: "b", base: "c2", tip: "T", open: true },
+    ])
+  })
+
+  it("a leading gap folds into the first range via episode.base", () => {
+    expect(sliceRanges([span("a", "c1", "c2")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("an inner gap folds into the next range: its base is the previous leftAt", () => {
+    expect(sliceRanges([span("a", "B", "c1"), span("b", "c3", "T")], running)).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+  })
+
+  it("a trailing gap folds back: the last range's tip is the episode tip, and it stays open", () => {
+    expect(sliceRanges([span("a", "B", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("drops a closed empty span, first, middle and last, its neighbours absorbing the gap", () => {
+    expect(sliceRanges([span("e", "B", "B"), span("a", "B", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+    expect(
+      sliceRanges([span("a", "B", "c1"), span("e", "c2", "c2"), span("b", "c2", "c4")], running),
+    ).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+    expect(sliceRanges([span("a", "B", "c1"), span("e", "c1", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("no spans, and only empty closed spans, each yield one open main range over the whole episode", () => {
+    const main = [{ name: "main", base: "B", tip: "T", open: true }]
+    expect(sliceRanges([], running)).toEqual(main)
+    expect(sliceRanges([span("e", "c1", "c1")], running)).toEqual(main)
+  })
+
+  it("an unleft empty span is kept and open", () => {
+    expect(sliceRanges([span("a", "B", "c1"), span("b", "c1")], running)).toEqual([
+      { name: "a", base: "B", tip: "c1", open: false },
+      { name: "b", base: "c1", tip: "T", open: true },
+    ])
+    expect(sliceRanges([span("b", "T")], running)).toEqual([
+      { name: "b", base: "B", tip: "T", open: true },
+    ])
+  })
+
+  it("rejects a pending turn's empty hash", () => {
+    expect(() => sliceRanges([span("a", "", "c1")], running)).toThrow("not a commit")
+    expect(() => sliceRanges([span("a", "c1", "")], running)).toThrow("not a commit")
+  })
+})

package/src/replay/Slices.ts

@@ -0,0 +1,45 @@
+export const IMPLICIT_SLICE = "main"
+
+/** Same shape as mark()'s name rule; kept local so @pmelab/gtd/flows publishes no regex. */
+export const SLICE_NAME = /^[a-z][a-z0-9-]*$/
+
+/** One slice() call as replay saw it. Hashes are the commit replay stood on; "" is a pending turn. */
+export interface SliceSpan {
+  readonly name: string
+  readonly enteredAt: string
+  /** undefined: the flow never left it — the process rests inside, or restart() fired inside. */
+  readonly leftAt: string | undefined
+}
+
+export interface SliceRange {
+  readonly name: string
+  /** Exclusive: the range is base..tip in git's sense. */
+  readonly base: string
+  readonly tip: string
+  /** The tip can still move: only the last range, since a rest is never past the episode's end. */
+  readonly open: boolean
+}
+
+/**
+ * Folds boundaries into ranges: each kept span's base is the previous kept
+ * span's `leftAt`, so a gap before a span belongs to it, and the last span
+ * runs to the episode tip. A closed span that landed nothing is dropped.
+ */
+export const sliceRanges = (
+  spans: readonly SliceSpan[],
+  episode: { readonly base: string; readonly tip: string },
+): readonly SliceRange[] => {
+  if (spans.some((s) => s.enteredAt === "" || s.leftAt === "")) {
+    throw new Error('sliceRanges: a pending turn\'s "" hash is not a commit')
+  }
+  const kept = spans.filter((s) => s.leftAt === undefined || s.enteredAt !== s.leftAt)
+  if (kept.length === 0) {
+    return [{ name: IMPLICIT_SLICE, base: episode.base, tip: episode.tip, open: true }]
+  }
+  return kept.map((s, i) => ({
+    name: s.name,
+    base: i === 0 ? episode.base : (kept[i - 1]!.leftAt ?? episode.base),
+    tip: i === kept.length - 1 ? episode.tip : (s.leftAt ?? episode.tip),
+    open: i === kept.length - 1,
+  }))
+}

package/src/replay/Trailers.test.ts

@@ -115,6 +115,17 @@ describe("the commit-message codec", () => {
     expect(parsed.version).toBe("1.2.3")
   })
 
+  it("reads a Gtd-Version carrying control bytes as unknown, and keeps spaces and parens", () => {
+    const withVersion = (value: string) =>
+      formatCommitMessage({ actor: "a", to: "b" }).replace(
+        "Gtd-Format: 1",
+        `Gtd-Version: ${value}\nGtd-Format: 1`,
+      )
+    expect(parseCommitMessage(withVersion("1.0\u001b]0;x\u0007")).version).toBeUndefined()
+    expect(parseCommitMessage(withVersion("1.0\u009b")).version).toBeUndefined()
+    expect(parseCommitMessage(withVersion("0.0.1 (dev)")).version).toBe("0.0.1 (dev)")
+  })
+
   it("omits Gtd-Branch and Gtd-Version when unset, and reads them as undefined", () => {
     const message = formatCommitMessage({ actor: "agent", to: "idle" })
     expect(message).not.toContain("Gtd-Branch")

package/src/replay/Trailers.ts

@@ -196,7 +196,9 @@ const TRAILER_READERS: Readonly<Record<string, (value: string, into: Trailers) =
     if (value !== "") into.branch ??= value
   },
   "Gtd-Version": (value, into) => {
-    if (value !== "") into.version ??= value
+    // Untrusted (fetched history): control bytes would reach the terminal; a rejected value reads as unknown.
+    // eslint-disable-next-line no-control-regex
+    if (value !== "" && !/[\u0000-\u001f\u007f-\u009f]/.test(value)) into.version ??= value
   },
   "Gtd-Kept": (value, into) => {
     if (HASH_RE.test(value)) into.kept ??= value

package/src/replay/index.ts

@@ -12,3 +12,4 @@ export {
 export { accessShapeFault, foldAccess } from "./Access.js"
 export { formatFault } from "./Format.js"
 export { refNameFault } from "./RefName.js"
+export { sliceRanges } from "./Slices.js"

package/src/wire/Slices.ts

@@ -0,0 +1,25 @@
+import { WIRE_SCHEMA } from "./constants.js"
+
+export interface SliceEntry {
+  readonly name: string
+  /** Full hash, exclusive: git's base..tip. */
+  readonly base: string
+  /** Full hash, inclusive; HEAD's hash for the open slice. */
+  readonly tip: string
+  /** false only for the last slice of an underway process. */
+  readonly closed: boolean
+}
+
+export interface SlicesDocument {
+  readonly schema: number
+  readonly slices: readonly SliceEntry[]
+}
+
+/** The ONLY place `gtd slices --json`'s shape is built; copies exactly the four fields, in order. */
+export const slicesDocument = (slices: readonly SliceEntry[]): SlicesDocument => ({
+  schema: WIRE_SCHEMA,
+  slices: slices.map(({ name, base, tip, closed }) => ({ name, base, tip, closed })),
+})
+
+export const renderSlicesJson = (document: SlicesDocument): string =>
+  JSON.stringify(document) + "\n"

package/src/wire/WireSchema.test.ts

@@ -9,6 +9,8 @@ import {
   landFields,
   renderBeatJson,
   renderLandJson,
+  renderSlicesJson,
+  slicesDocument,
   statusOf,
   WIRE_SCHEMA,
   type BeatKind,
@@ -116,6 +118,9 @@ const documents: Readonly<Record<string, string>> = {
     }),
   ),
   "judge.json": JUDGE,
+  "slices.json": renderSlicesJson(
+    slicesDocument([{ name: "build", base: "a".repeat(40), tip: "b".repeat(40), closed: true }]),
+  ),
 }
 
 describe(`wire schema ${WIRE_SCHEMA}`, () => {
@@ -139,6 +144,19 @@ describe(`wire schema ${WIRE_SCHEMA}`, () => {
     }
   })
 
+  describe("slicesDocument", () => {
+    it("stamps WIRE_SCHEMA and drops any field beyond the four", () => {
+      const doc = slicesDocument([
+        { name: "n", base: "b", tip: "t", closed: false, extra: 1 } as never,
+      ])
+      expect(doc).toEqual({
+        schema: WIRE_SCHEMA,
+        slices: [{ name: "n", base: "b", tip: "t", closed: false }],
+      })
+      expect(Object.keys(doc.slices[0]!)).toEqual(["name", "base", "tip", "closed"])
+    })
+  })
+
   describe("the shape check", () => {
     const land = JSON.parse(documents["land.json"]!) as Record<string, unknown>
     const { subject, ...rest } = land

package/src/wire/golden/1/slices.json

@@ -0,0 +1,11 @@
+{
+  "schema": 1,
+  "slices": [
+    {
+      "name": "build",
+      "base": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "tip": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "closed": true
+    }
+  ]
+}

package/src/wire/index.ts

@@ -10,3 +10,4 @@ export * from "./Judge.js"
 export { selectPath } from "./Select.js"
 export { resolveSession } from "./Sessions.js"
 export { globMatches } from "./Glob.js"
+export * from "./Slices.js"