@pmelab/gtd 20.1.0 → 20.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "20.1.0",
+  "version": "20.3.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -72,6 +72,8 @@
     "*": "oxfmt --no-error-on-unmatched-pattern --write"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
     "@effect/language-service": "^0.72.0",
     "@radix-ui/colors": "^3.0.0",
     "@semantic-release/exec": "^7.1.0",

package/src/flows/runtime.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  FLOWS_PROTOCOL,
+  FlowsProtocolError,
+  head,
+  installContext,
+  protocolMismatch,
+  type FlowContext,
+} from "./runtime.js"
+
+afterEach(() => installContext(undefined))
+
+const context = { head: () => "h1" } as unknown as FlowContext
+const globals = globalThis as Record<symbol, unknown>
+const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
+const PROTOCOL_KEY = Symbol.for("@pmelab/gtd/flow-protocol")
+
+describe("the flows protocol handshake", () => {
+  it("reads the context when the engine installed the facade's protocol", () => {
+    installContext(context)
+    expect(head()).toBe("h1")
+  })
+
+  it("tells a newer engine to have the workflow's package upgraded", () => {
+    installContext(context)
+    globals[PROTOCOL_KEY] = FLOWS_PROTOCOL + 1
+    expect(() => head()).toThrow(FlowsProtocolError)
+    expect(() => head()).toThrow(
+      `gtd: the workflow speaks flows protocol ${FLOWS_PROTOCOL}, but the engine installed protocol ${FLOWS_PROTOCOL + 1} — upgrade the @pmelab/gtd the workflow imports`,
+    )
+    expect(protocolMismatch()).toBeInstanceOf(FlowsProtocolError)
+  })
+
+  it("tells an older engine to be upgraded", () => {
+    installContext(context)
+    globals[PROTOCOL_KEY] = FLOWS_PROTOCOL - 1
+    expect(() => head()).toThrow(
+      `engine installed protocol ${FLOWS_PROTOCOL - 1} — upgrade the gtd that runs it`,
+    )
+  })
+
+  // Must go red once FLOWS_PROTOCOL passes 1: a pre-handshake engine is v1.
+  it("accepts an engine that installs no protocol number", () => {
+    delete globals[PROTOCOL_KEY]
+    globals[CONTEXT_KEY] = context
+    expect(head()).toBe("h1")
+  })
+
+  it("keeps the outside-a-replay error when nothing is installed", () => {
+    expect(() => head()).toThrow(
+      new Error("gtd: a workflow step or helper was called outside a gtd replay"),
+    )
+  })
+})

package/src/flows/runtime.ts

@@ -159,20 +159,66 @@ export interface FlowContext {
   readonly accessFor: (localName: string, file?: string) => AccessDef
 }
 
-const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
+/**
+ * Bump only when the installed `FlowContext` object changes shape or semantics;
+ * type-only authoring-API changes don't count. A bump past 1 must keep v1
+ * members working or move the context to a new symbol key — pre-handshake
+ * facades never read the protocol.
+ */
+export const FLOWS_PROTOCOL = 1
+
+export class FlowsProtocolError extends Error {
+  constructor(engine: number, flows: number) {
+    const upgrade =
+      engine < flows
+        ? "upgrade the gtd that runs it"
+        : "upgrade the @pmelab/gtd the workflow imports"
+    super(
+      `gtd: the workflow speaks flows protocol ${flows}, but the engine installed protocol ${engine} — ${upgrade}`,
+    )
+    this.name = "FlowsProtocolError"
+  }
+}
 
-type ContextHolder = { [CONTEXT_KEY]?: FlowContext | undefined }
+const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
+// Separate from the context so a facade older than the protocol still reads
+// the context it expects.
+const PROTOCOL_KEY = Symbol.for("@pmelab/gtd/flow-protocol")
+// The first mismatch, kept for the engine: workflow code may catch what ctx()
+// throws, and the refusal must still win.
+const MISMATCH_KEY = Symbol.for("@pmelab/gtd/flow-protocol-mismatch")
+
+type ContextHolder = {
+  [CONTEXT_KEY]?: FlowContext | undefined
+  [PROTOCOL_KEY]?: number | undefined
+  [MISMATCH_KEY]?: Error | undefined
+}
 
-/** Engine-only: install the replay context a flow run reads. */
+/** Engine-only. */
 export const installContext = (context: FlowContext | undefined): void => {
-  ;(globalThis as ContextHolder)[CONTEXT_KEY] = context
+  const holder = globalThis as ContextHolder
+  holder[CONTEXT_KEY] = context
+  holder[PROTOCOL_KEY] = FLOWS_PROTOCOL
+  holder[MISMATCH_KEY] = undefined
 }
 
+/** Engine-only: the mismatch a facade copy hit during this replay, if any. */
+export const protocolMismatch = (): Error | undefined => (globalThis as ContextHolder)[MISMATCH_KEY]
+
 const ctx = (): FlowContext => {
-  const context = (globalThis as ContextHolder)[CONTEXT_KEY]
+  const holder = globalThis as ContextHolder
+  const context = holder[CONTEXT_KEY]
   if (context === undefined) {
     throw new Error("gtd: a workflow step or helper was called outside a gtd replay")
   }
+  // An engine older than the handshake installs no number but the context
+  // protocol 1 describes.
+  const protocol = holder[PROTOCOL_KEY] ?? 1
+  if (protocol !== FLOWS_PROTOCOL) {
+    const error = new FlowsProtocolError(protocol, FLOWS_PROTOCOL)
+    holder[MISMATCH_KEY] ??= error
+    throw error
+  }
   return context
 }