@pmelab/gtd 59.0.1 → 60.1.0

package/src/workflow/pin.test.ts

@@ -0,0 +1,159 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { isBuiltin } from "node:module"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { Effect, Exit } from "effect"
+import { parseAst } from "rolldown/parseAst"
+import { afterEach, describe, expect, it } from "vitest"
+import { PIN_KEY } from "../install/index.js"
+import { InMemRepo, testLayers } from "../twins/index.js"
+import { ConfigDiscovery, ConfigService } from "./index.js"
+import { EngineCore, pin, readPin } from "./pin.js"
+
+afterEach(() => {
+  delete (globalThis as { [PIN_KEY]?: unknown })[PIN_KEY]
+})
+
+// A pin must run with nothing installed: the engine imports Node and nothing else.
+describe.each([
+  ["live", EngineCore.Live],
+  ["in memory", testLayers(new InMemRepo())],
+])("EngineCore (%s)", (_, layer) => {
+  const source = () =>
+    Effect.runPromise(
+      Effect.provide(
+        Effect.flatMap(EngineCore, (e) => e.source),
+        layer,
+      ),
+    )
+
+  it("serves an ES module importing only Node's builtins", async () => {
+    const imported = parseAst(await source()).body.flatMap((node) =>
+      "source" in node && node.source !== null && node.source !== undefined
+        ? [String(node.source.value)]
+        : [],
+    )
+    expect(imported.filter((id) => !isBuiltin(id))).toEqual([])
+  })
+})
+
+describe("EngineCore.layer", () => {
+  it("names the engine it cannot find", async () => {
+    const exit = await Effect.runPromiseExit(
+      Effect.provide(
+        Effect.flatMap(EngineCore, (e) => e.source),
+        EngineCore.layer(() => "/nowhere/gtd.core.mjs"),
+      ),
+    )
+    expect(Exit.isFailure(exit) && String(exit.cause)).toContain(
+      "no engine at /nowhere/gtd.core.mjs",
+    )
+  })
+})
+
+const CONFIG = `import { human } from "@pmelab/gtd/flows"
+import { message } from "./lib/message.js"
+
+export default async () => {
+  await human("idle", { message })
+}
+`
+
+const pinFrom = (repo: InMemRepo) =>
+  Effect.runPromise(
+    Effect.gen(function* () {
+      const module = yield* (yield* ConfigDiscovery).workflowModule("/repo", "/repo")
+      return yield* pin(module!, "/repo", "1.2.3")
+    }).pipe(Effect.provide(testLayers(repo))),
+  )
+
+describe("pin", () => {
+  it("leads with a plain header, then the workflow and the engine gzipped", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile("gtd.config.ts", CONFIG)
+    repo.writeFile("lib/message.ts", `export const message = "pinned message"\n`)
+    const bytes = await pinFrom(repo)
+
+    expect(Buffer.from(bytes).toString("latin1").split("\n")[0]).toBe("gtdpin 1 gtd 1.2.3")
+    const { format, version, source } = readPin(bytes)
+    expect({ format, version }).toEqual({ format: 1, version: "1.2.3" })
+    expect(source).toContain("pinned message")
+    expect(source.endsWith('import "node:process"\n')).toBe(true)
+  })
+
+  it("registers a workflow load runs without any config", async () => {
+    const repo = new InMemRepo()
+    repo.writeFile("gtd.config.ts", CONFIG)
+    repo.writeFile("lib/message.ts", `export const message = "pinned message"\n`)
+    const { source } = readPin(await pinFrom(repo))
+    repo.writeFile("gtd.config.ts", "")
+    repo.seedCommit("chore: init")
+
+    await import(`data:text/javascript,${encodeURIComponent(source)}`)
+    const config = await Effect.runPromise(
+      Effect.flatMap(ConfigService, (c) => c.load).pipe(Effect.provide(testLayers(repo))),
+    )
+    expect(config.defaultWorkflow.def.initial).toBe("idle")
+    expect(Object.keys(config.fingerprint).sort()).toEqual(["gtd.config.ts", "lib/message.ts"])
+  })
+
+  describe("from disk", () => {
+    let dir: string
+    afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+    const pinDir = (config: string) => {
+      writeFileSync(join(dir, "gtd.config.ts"), config)
+      return Effect.runPromiseExit(
+        pin(
+          {
+            filepath: join(dir, "gtd.config.ts"),
+            source: readFileSync(join(dir, "gtd.config.ts"), "utf8"),
+          },
+          dir,
+          "1.2.3",
+        ).pipe(Effect.provide(testLayers(new InMemRepo()))),
+      )
+    }
+
+    const pkg = (name: string, files: Record<string, string>) => {
+      const root = join(dir, "node_modules", name)
+      for (const [file, content] of Object.entries({
+        "package.json": JSON.stringify({ name, main: "index.js" }),
+        ...files,
+      })) {
+        mkdirSync(join(root, file, ".."), { recursive: true })
+        writeFileSync(join(root, file), content)
+      }
+    }
+
+    it("carries a CommonJS package", async () => {
+      dir = mkdtempSync(join(tmpdir(), "gtd-pin-"))
+      pkg("shout", { "index.js": "module.exports = (s) => s.toUpperCase() + '!pinned-cjs'" })
+      const exit = await pinDir(
+        `import shout from "shout"\nexport default async () => shout("x")\n`,
+      )
+      expect(Exit.isSuccess(exit) && readPin(exit.value).source).toContain("!pinned-cjs")
+    })
+
+    it("refuses a package node-gyp builds, naming it", async () => {
+      dir = mkdtempSync(join(tmpdir(), "gtd-pin-"))
+      pkg("sqlish", { "index.js": "module.exports = {}", "binding.gyp": "{}" })
+      const exit = await pinDir(`import "sqlish"\nexport default async () => {}\n`)
+      expect(Exit.isFailure(exit) && String(exit.cause)).toContain(
+        'package "sqlish" loads a native addon',
+      )
+    })
+
+    it("refuses a native addon, naming its package", async () => {
+      dir = mkdtempSync(join(tmpdir(), "gtd-pin-"))
+      pkg("@scope/native", {
+        "index.js": 'module.exports = require("./build/addon.node")',
+        "build/addon.node": "",
+      })
+      const exit = await pinDir(`import "@scope/native"\nexport default async () => {}\n`)
+      expect(Exit.isFailure(exit) && String(exit.cause)).toContain(
+        'package "@scope/native" loads a native addon',
+      )
+    })
+  })
+})

package/src/workflow/pin.ts

@@ -0,0 +1,72 @@
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { gunzipSync, gzipSync } from "node:zlib"
+import { Context, Effect, Layer } from "effect"
+import { GtdError } from "../platform/index.js"
+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
+
+/**
+ * The engine a pin carries, as ES module source. Live, the `gtd.core.mjs` the
+ * running gtd ships beside its own bundle.
+ */
+export class EngineCore extends Context.Service<
+  EngineCore,
+  { readonly source: Effect.Effect<string, Error> }
+>()("EngineCore") {
+  static layer = (path: () => string): Layer.Layer<EngineCore> =>
+    Layer.succeed(EngineCore, {
+      source: Effect.suspend(() => {
+        const file = path()
+        return Effect.try({
+          try: () => readFileSync(file, "utf8"),
+          catch: () => new GtdError(`gtd bundle: no engine at ${file} — build gtd first`),
+        })
+      }),
+    })
+  static Live = EngineCore.layer(() => join(ownPackage().root, "dist", "gtd.core.mjs"))
+}
+
+/**
+ * A pin: one plain-text header line a launcher reads without unpacking, then
+ * the gzipped ES module — the workflow registering itself, then the engine.
+ * Gzipped, git sees binary and diffs no source.
+ */
+export const pin = (
+  module: WorkflowModule,
+  root: string,
+  version: string,
+): Effect.Effect<Uint8Array, Error, EngineCore> =>
+  Effect.gen(function* () {
+    const core = yield* (yield* EngineCore).source
+    const workflow = yield* Effect.tryPromise({
+      try: () => pinnedWorkflowSource(module, root, version),
+      catch: (e) =>
+        new GtdError(
+          `gtd bundle: ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`,
+        ),
+    })
+    // The registration runs first; a shebang is only valid on a file's first line.
+    const source = workflow + core.replace(/^#!.*\n/, "")
+    return Buffer.concat([
+      Buffer.from(`gtdpin ${PIN_FORMAT} gtd ${version}\n`),
+      gzipSync(source, { level: 9 }),
+    ])
+  })
+
+/** 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")
+  return {
+    format: Number(header[1]),
+    version: header[2]!,
+    source: gunzipSync(bytes.subarray(end + 1)).toString("utf8"),
+  }
+}

package/src/workflow/vars.ts

@@ -3,9 +3,9 @@ import { Context } from "effect"
 const PREFIX = "GTD_"
 
 /** The live release flags as `flag_<name>` settings, provided by the CLI; absent means no flags. */
-export class StartFlags extends Context.Reference<StartFlags>()("StartFlags", {
-  defaultValue: (): Readonly<Record<string, string>> => ({}),
-}) {}
+export const StartFlags = Context.Reference<Readonly<Record<string, string>>>("StartFlags", {
+  defaultValue: () => ({}),
+})
 
 /**
  * One kind of setting, later wins: the workflow's own defaults, `--var`

package/src/workflow-kit/index.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest"
+import * as kit from "./index.js"
+
+describe("@pmelab/gtd/workflow-kit", () => {
+  it("publishes its helpers by name", () => {
+    expect(Object.keys(kit).sort()).toEqual(
+      [
+        "assertionLines",
+        "escalation",
+        "fixFindings",
+        "gate",
+        "healthy",
+        "lensEntriesOf",
+        "lensOf",
+        "lensScopes",
+        "lensesOf",
+        "qualityLap",
+        "removedAssertions",
+        "review",
+        "reviewToHandOff",
+        "untilSettled",
+      ].sort(),
+    )
+  })
+})

package/src/workflow-kit/index.ts

@@ -1,7 +1,40 @@
 // Building blocks workflows share. Policy-free: every skill list,
 // lens, prompt, step, path and threshold arrives as a parameter, so a new
 // workflow composes these without inheriting the shipped one's choices.
-export * from "./health.js"
-export * from "./quality.js"
-export * from "./scenarios.js"
-export * from "./review.js"
+export {
+  escalation,
+  gate,
+  healthy,
+  untilSettled,
+  type EscalationCount,
+  type EscalationSteps,
+  type Health,
+  type RetryVerdict,
+} from "./health.js"
+export {
+  fixFindings,
+  lensEntriesOf,
+  lensOf,
+  lensesOf,
+  lensScopes,
+  qualityLap,
+  type FindingsFix,
+  type LensEntry,
+} from "./quality.js"
+export {
+  assertionLines,
+  removedAssertions,
+  type Assertion,
+  type RemovedAssertions,
+} from "./scenarios.js"
+export {
+  review,
+  reviewToHandOff,
+  type CollectRound,
+  type HandOffPolicy,
+  type Requested,
+  type ReviewOutcome,
+  type ReviewPolicy,
+  type ReviewRisk,
+  type Verdict,
+} from "./review.js"

package/src/workflow-kit/review.ts

@@ -195,13 +195,13 @@ const converse = async (
 }
 
 /** What `finish` hands back to `review`: an outcome, or another lap at the gate. */
-type Finish =
+export type Finish =
   | ReviewOutcome
   | { readonly next: "await"; readonly reviewed: string }
   | { readonly next: "rereview"; readonly carry: string | undefined }
 
 /** What a round's routing needs from `finish`: its closing step and the ways it ends. */
-interface Round {
+export interface Round {
   readonly round: string
   readonly close: () => Promise<void>
   readonly outcome: (verdict: "signoff" | "feedback") => ReviewOutcome