@pmelab/gtd 60.1.0 → 61.0.0

package/src/twins/PinBeats.ts

@@ -0,0 +1,33 @@
+import { Effect } from "effect"
+import { runCli } from "../cli/index.js"
+import type { PinMark } from "../wire/index.js"
+import { makeCapturingCliIo } from "./cliIo.js"
+import { applyEmittedScript } from "./EmittedScriptRecognizer.js"
+import type { InMemRepo } from "./InMemRepo.js"
+
+const gtd = async (repo: InMemRepo, ...args: string[]) => {
+  const { io, result } = makeCapturingCliIo(repo)
+  await Effect.runPromise(runCli(["node", "gtd.js", ...args], io))
+  return result()
+}
+
+const apply = (repo: InMemRepo, script: string): void => {
+  const outcome = applyEmittedScript(repo, new Map(), script)
+  if (!outcome.ok) throw new Error(outcome.error)
+}
+
+/**
+ * Takes the pending pin or unpin beat — `mark` alone when given — the way a
+ * driver does: its script, then its landing. Whether it took one.
+ */
+export const takePinBeat = async (repo: InMemRepo, mark?: PinMark): Promise<boolean> => {
+  const next = await gtd(repo, "next", "--json")
+  if (next.exitCode !== 0) return false
+  const beat = JSON.parse(next.stdout) as { readonly pin?: PinMark; readonly content: string }
+  if (beat.pin === undefined || (mark !== undefined && beat.pin !== mark)) return false
+  apply(repo, beat.content)
+  const land = await gtd(repo, "land", "--json")
+  if (land.exitCode !== 0) throw new Error(`gtd land exited ${land.exitCode}: ${land.stderr}`)
+  apply(repo, (JSON.parse(land.stdout) as { readonly script: string }).script)
+  return true
+}

package/src/twins/index.ts

@@ -11,3 +11,4 @@ export { applyFlowScript } from "./FlowScripts.js"
 export { gitTiers, runGitServiceContract, runGitScriptContract, type GitTier } from "./GitTiers.js"
 export { strictGitOperations } from "./StrictGitOperations.js"
 export { fakeGitOperations } from "./FakeGitOperations.js"
+export { takePinBeat } from "./PinBeats.js"

package/src/wire/BeatDocument.ts

@@ -1,6 +1,14 @@
 import type { BeatKind, Demand, DemandSession } from "./Demand.js"
 import type { BeatStatus, NextMatch, StatusChange } from "./BeatStatus.js"
-import type { Actor, ApprovalEntry, ModelCost, StateMode, StateName, StepAccess } from "./types.js"
+import type {
+  Actor,
+  ApprovalEntry,
+  ModelCost,
+  PinMark,
+  StateMode,
+  StateName,
+  StepAccess,
+} from "./types.js"
 import { WIRE_SCHEMA } from "./constants.js"
 
 /** `gtd next --json`'s `next` key — `null` when landing would commit nothing. */
@@ -27,20 +35,30 @@ const dispatchFieldsOf = (
   readonly validate: string | undefined
   readonly skills: readonly string[] | undefined
   readonly access: StepAccess | undefined
+  readonly pin: PinMark | undefined
 } => {
+  const none = {
+    session: undefined,
+    validate: undefined,
+    skills: undefined,
+    access: undefined,
+    pin: undefined,
+  }
   switch (demand.kind) {
     case "prompt":
       return {
+        ...none,
         session: demand.session,
         validate: demand.validate,
         skills: demand.skills,
         access: demand.access,
       }
+    case "script":
+      return { ...none, pin: demand.pin }
     case "capture":
     case "message":
-    case "script":
     case "stalled":
-      return { session: undefined, validate: undefined, skills: undefined, access: undefined }
+      return none
     default:
       return assertNeverDemand(demand)
   }
@@ -57,6 +75,8 @@ export interface BeatDocument {
   readonly model: string | undefined
   readonly system: string | undefined
   readonly validate: string | undefined
+  /** On a pin or unpin beat only: what its script does to `.gtd/process.gtdpin`. */
+  readonly pin: PinMark | undefined
   readonly log: string
   readonly state: StateName
   readonly actor: Actor
@@ -76,13 +96,13 @@ export interface BeatDocument {
 }
 
 /**
- * Flatten a `Demand` plus its `BeatStatus` into the single 25-key document
+ * Flatten a `Demand` plus its `BeatStatus` into the single 26-key document
  * `gtd next --json` emits — the ONLY place the two are joined. `cost`/
  * `costByModel` are omitted together, exactly when no cost was recorded
  * (`cost <= 0`).
  */
 export const beatDocument = (demand: Demand, status: BeatStatus): BeatDocument => {
-  const { session, validate, skills, access } = dispatchFieldsOf(demand)
+  const { session, validate, skills, access, pin } = dispatchFieldsOf(demand)
   const hasCost = status.cost > 0
   return {
     schema: WIRE_SCHEMA,
@@ -94,6 +114,7 @@ export const beatDocument = (demand: Demand, status: BeatStatus): BeatDocument =
     model: status.model,
     system: status.system,
     validate,
+    pin,
     log: status.log,
     state: status.state,
     actor: status.actor,

package/src/wire/Demand.ts

@@ -1,4 +1,11 @@
-import type { Actor, ContentKind, RenderedDemandSource, StateName, StepAccess } from "./types.js"
+import type {
+  Actor,
+  ContentKind,
+  PinMark,
+  RenderedDemandSource,
+  StateName,
+  StepAccess,
+} from "./types.js"
 
 /** The whole beat vocabulary a driver acts on — what to DO with a rest, not merely whether dispatching it is safe. */
 export type BeatKind = "capture" | "message" | "script" | "prompt" | "stalled"
@@ -72,7 +79,7 @@ export interface DemandSession {
 export type Demand =
   | { readonly kind: "capture"; readonly content: string }
   | { readonly kind: "message"; readonly content: string }
-  | { readonly kind: "script"; readonly content: string }
+  | { readonly kind: "script"; readonly content: string; readonly pin?: PinMark }
   | { readonly kind: "stalled"; readonly content: string }
   | {
       readonly kind: "prompt"
@@ -91,7 +98,10 @@ export type Demand =
  * any other kind.
  */
 export const demandOf = (input: {
-  readonly rendered: Pick<RenderedDemandSource, "actor" | "content" | "state" | "skills" | "access">
+  readonly rendered: Pick<
+    RenderedDemandSource,
+    "actor" | "content" | "state" | "skills" | "access" | "pin"
+  >
   readonly kind: BeatKind
   readonly session?: DemandSession
   readonly validate?: string
@@ -102,7 +112,7 @@ export const demandOf = (input: {
   const skills =
     rendered.skills !== undefined && rendered.skills.length > 0 ? rendered.skills : undefined
   const access = rendered.access ?? { read: null, write: null }
-  return kind === "prompt"
-    ? { kind, content, session, validate, skills, access }
-    : { kind, content }
+  if (kind === "prompt") return { kind, content, session, validate, skills, access }
+  if (kind === "script" && rendered.pin !== undefined) return { kind, content, pin: rendered.pin }
+  return { kind, content }
 }

package/src/wire/constants.ts

@@ -20,3 +20,6 @@ export const renderFormat = (fmt: string, ...args: readonly string[]): string =>
 /** The first line of the landing refusal for a turn that wrote outside its `write` access — a stable marker drivers and tests grep for. */
 export const ACCESS_REFUSAL =
   "gtd land: this turn wrote outside its write access — revert these paths, then run `gtd land` again:"
+
+/** Where a process keeps its pin: the engine and workflow it runs on, as `gtd bundle` prints them. */
+export const PIN_PATH = ".gtd/process.gtdpin"

package/src/wire/types.ts

@@ -10,6 +10,9 @@ export type StateName = string
 /** The three content kinds a state can carry — exactly one per state. */
 export type ContentKind = "script" | "prompt" | "message"
 
+/** What a pin or unpin beat does to the pin; a driver may do it its own way instead of running the script. */
+export type PinMark = "add" | "remove"
+
 /** The name of a steering-file mode. Not a closed vocabulary: the valid set derives from the active definition (`BUILT_IN_MODES` plus whatever `modes:` declares). */
 export type StateMode = string
 
@@ -51,4 +54,5 @@ export interface RenderedDemandSource {
   readonly judge?: string
   readonly skills?: readonly string[]
   readonly access?: StepAccess
+  readonly pin?: PinMark
 }