@pmelab/gtd 21.1.0 → 22.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "21.1.0",
+  "version": "22.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {
@@ -134,6 +134,7 @@
   "dependencies": {
     "@effect/platform": "^0.94.2",
     "@effect/platform-node": "^0.104.1",
+    "@standard-schema/spec": "^1.1.0",
     "@trpc/server": "^11.18.0",
     "effect": "^3.19.15",
     "jiti": "^2.7.0",

package/schema.json

@@ -5,7 +5,7 @@
   "properties": {
     "vars": {
       "type": "object",
-      "description": "Flat name -> scalar map merged into the workflow's process settings (defaults), pinned for the whole process at its start. Scalars are coerced to strings.",
+      "description": "Flat name -> scalar map merged into the workflow's process settings (defaults), pinned for the whole process at its start. A workflow built by a factory receives these entries as options and validates them itself. Scalars are coerced to strings.",
       "additionalProperties": {
         "type": [
           "string",
@@ -16,7 +16,7 @@
     },
     "env": {
       "type": "object",
-      "description": "Flat name -> scalar map merged into the workflow's environment settings (envDefaults) — values that change how a step runs on this machine, like the test command or a model hint. Read fresh on every gtd call, never pinned to a process. GTD_<NAME> environment variables override these entries. Scalars are coerced to strings.",
+      "description": "Flat name -> scalar map merged into the workflow's environment settings (envDefaults) — values that change how a step runs on this machine. A workflow built by a factory receives these entries as options and validates them itself. Read fresh on every gtd call, never pinned to a process. GTD_<NAME> environment variables override these entries. Scalars are coerced to strings.",
       "additionalProperties": {
         "type": [
           "string",

package/src/flows/factory.test.ts

@@ -0,0 +1,94 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import { describe, expect, it } from "vitest"
+import { configure, defineWorkflow, isFactoryWorkflow } from "./factory.js"
+
+// A hand-written Standard Schema: `{ greeting?: string }`, unknown keys rejected.
+const greetingSchema: StandardSchemaV1<{ greeting?: string }> = {
+  "~standard": {
+    version: 1,
+    vendor: "test",
+    validate: (value) => {
+      const issues: StandardSchemaV1.Issue[] = []
+      for (const [key, v] of Object.entries(value as object)) {
+        if (key !== "greeting") issues.push({ message: "is unexpected", path: [key] })
+        else if (typeof v !== "string") issues.push({ message: "Expected string", path: [{ key }] })
+      }
+      return issues.length > 0 ? { issues } : { value: value as { greeting?: string } }
+    },
+  },
+}
+
+const flow = async (): Promise<void> => {}
+const greeter = defineWorkflow(greetingSchema, (options) => ({
+  flow,
+  defaults: { greeting: options.greeting ?? "hello" },
+}))
+
+describe("defineWorkflow", () => {
+  it("marks the factory and a call's result as factory workflows, a plain flow not", () => {
+    expect(isFactoryWorkflow(greeter)).toBe(true)
+    expect(isFactoryWorkflow(greeter({ greeting: "hi" }))).toBe(true)
+    expect(isFactoryWorkflow(flow)).toBe(false)
+    expect(configure(flow)).toBeUndefined()
+  })
+
+  it("builds the factory itself with no options", () => {
+    expect(configure(greeter)).toEqual({
+      ok: true,
+      build: { flow, defaults: { greeting: "hello" } },
+    })
+  })
+
+  it("builds a call's result from the options it was called with", () => {
+    expect(configure(greeter({ greeting: "hi" }))).toEqual({
+      ok: true,
+      build: { flow, defaults: { greeting: "hi" } },
+    })
+  })
+
+  it("lays overrides over the options a call was given", () => {
+    expect(configure(greeter({ greeting: "hi" }), { greeting: "hey" })).toEqual({
+      ok: true,
+      build: { flow, defaults: { greeting: "hey" } },
+    })
+  })
+
+  it("reports every issue with its key path, path segments flattened", () => {
+    const bad = greeter({ greeting: 1 } as never)
+    expect(configure(bad, { greting: "x" })).toEqual({
+      ok: false,
+      issues: [
+        { path: ["greeting"], message: "Expected string" },
+        { path: ["greting"], message: "is unexpected" },
+      ],
+    })
+  })
+
+  it("refuses a schema that validates asynchronously", () => {
+    const asyncSchema: StandardSchemaV1<object> = {
+      "~standard": {
+        version: 1,
+        vendor: "test",
+        validate: async (value) => ({ value: value as object }),
+      },
+    }
+    const result = configure(defineWorkflow(asyncSchema, () => ({ flow })))
+    expect(result).toMatchObject({ ok: false, issues: [{ path: [] }] })
+  })
+
+  it("treats a schema failing with no issues as a rejection", () => {
+    const empty: StandardSchemaV1<object> = {
+      "~standard": { version: 1, vendor: "test", validate: () => ({ issues: [] }) },
+    }
+    expect(configure(defineWorkflow(empty, () => ({ flow })))).toMatchObject({
+      ok: false,
+      issues: [{ path: [] }],
+    })
+  })
+
+  it("throws when a call's result is awaited as if it were a flow", async () => {
+    await expect(Promise.resolve(greeter() as unknown as PromiseLike<void>)).rejects.toThrow(
+      /not a flow/,
+    )
+  })
+})

package/src/flows/factory.ts

@@ -0,0 +1,116 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import type { Flow } from "./runtime.js"
+
+// Registered, so a factory made by any copy of this file is recognised by the
+// engine's copy — the same reason the replay context is.
+const FACTORY = Symbol.for("@pmelab/gtd/workflow-factory")
+
+export interface WorkflowBuild {
+  readonly flow: Flow
+  /** Process settings this workflow declares, over its file's `defaults` export. */
+  readonly defaults?: Readonly<Record<string, string>> | undefined
+  /** Environment settings this workflow declares, over its file's `envDefaults` export. */
+  readonly envDefaults?: Readonly<Record<string, string>> | undefined
+}
+
+interface FactoryInternals {
+  readonly schema: StandardSchemaV1
+  readonly build: (options: never) => WorkflowBuild
+}
+
+/**
+ * A factory call's result. Nothing is validated yet: gtd validates the options
+ * when it loads the config, so a bad one is reported like any other config
+ * finding instead of throwing out of `gtd.config.ts`.
+ */
+export interface ConfiguredWorkflow {
+  readonly [FACTORY]: FactoryInternals & { readonly options: unknown }
+  readonly then: () => never
+}
+
+export type WorkflowFactory<Options> = ({} extends Options
+  ? (options?: Options) => ConfiguredWorkflow
+  : (options: Options) => ConfiguredWorkflow) & { readonly [FACTORY]: FactoryInternals }
+
+/**
+ * Define a workflow configured by options. `schema` is any Standard Schema
+ * (https://standardschema.dev); it should reject unknown keys, so a removed or
+ * misspelled option fails at load. Exported from `gtd.config.ts`, the factory
+ * itself and a call's result are both workflows.
+ */
+export const defineWorkflow = <S extends StandardSchemaV1>(
+  schema: S,
+  build: (options: StandardSchemaV1.InferOutput<S>) => WorkflowBuild,
+): WorkflowFactory<StandardSchemaV1.InferInput<S>> => {
+  const internals: FactoryInternals = { schema, build }
+  const factory = (options?: unknown): ConfiguredWorkflow => ({
+    [FACTORY]: { ...internals, options },
+    // A factory call used to be a flow; awaiting one in a composed flow must fail, not no-op.
+    // oxlint-disable-next-line unicorn/no-thenable -- awaiting a call must fail
+    then: () => {
+      throw new Error("a configured workflow is not a flow — compose fixFlow/reviewFlow instead")
+    },
+  })
+  return Object.assign(factory, { [FACTORY]: internals }) as never
+}
+
+export interface OptionIssue {
+  readonly path: readonly (string | number)[]
+  readonly message: string
+}
+
+export type Configured =
+  | { readonly ok: true; readonly build: WorkflowBuild }
+  | { readonly ok: false; readonly issues: readonly OptionIssue[] }
+
+const internalsOf = (
+  value: unknown,
+): (FactoryInternals & { readonly options?: unknown }) | undefined =>
+  (typeof value === "function" || (typeof value === "object" && value !== null)) && FACTORY in value
+    ? (value as { readonly [FACTORY]: FactoryInternals & { readonly options?: unknown } })[FACTORY]
+    : undefined
+
+export const isFactoryWorkflow = (value: unknown): boolean => internalsOf(value) !== undefined
+
+const segment = (key: PropertyKey | StandardSchemaV1.PathSegment): string | number => {
+  const raw = typeof key === "object" ? key.key : key
+  return typeof raw === "number" ? raw : String(raw)
+}
+
+/**
+ * Validate a factory workflow's options — those it was called with, `overrides`
+ * on top — and build it. `undefined` for an export that is no factory workflow.
+ */
+export const configure = (
+  value: unknown,
+  overrides: Readonly<Record<string, unknown>> = {},
+): Configured | undefined => {
+  const internals = internalsOf(value)
+  if (internals === undefined) return undefined
+  const options = { ...(internals.options as object), ...overrides }
+  const result = internals.schema["~standard"].validate(options)
+  if (result instanceof Promise) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: [],
+          message: "the options schema validates asynchronously — gtd needs a synchronous one",
+        },
+      ],
+    }
+  }
+  if (result.issues !== undefined) {
+    return {
+      ok: false,
+      issues:
+        result.issues.length === 0
+          ? [{ path: [], message: "the options schema rejected them without saying why" }]
+          : result.issues.map((issue) => ({
+              path: (issue.path ?? []).map(segment),
+              message: issue.message,
+            })),
+    }
+  }
+  return { ok: true, build: internals.build(result.value as never) }
+}

package/src/flows/index.ts

@@ -1,3 +1,4 @@
 export * from "./runtime.js"
 export * from "./helpers.js"
 export * from "./scripts.js"
+export * from "./factory.js"

package/src/workflows/bundled.ts

@@ -17,6 +17,7 @@ import { architecture, design } from "./planning.js"
 import type { FrozenScenarios } from "./scenarios.js"
 import { buildTail, type ReviewOutcome } from "./review.js"
 import { ARCHITECTURE, FEEDBACK, REQUIREMENTS, REVIEW } from "./steps.js"
+import { shipped } from "./options.js"
 import * as t from "./text.js"
 
 // gtd's bundled workflows. Any change to the tree starts a process:
@@ -25,13 +26,15 @@ import * as t from "./text.js"
 // the quality lap → human review, which signs off (the episode ends back at
 // `idle`) or sends a full re-plan lap. `feature` is that ordinary start;
 // `gtd --workflow fix` and `gtd --workflow review --var reviewBase=<commitish>`
-// enter the same build tail further in.
+// enter the same build tail further in. Each of the three is a factory over
+// the settings in `./vars.ts`; its flow is exported too, for composing.
 //
 // Every part is exported for other workflows to compose; see the modules
 // re-exported below.
 
 export { threads, type ThreadInfo } from "../flows/index.js"
 export { defaults, envDefaults } from "./vars.js"
+export { ShippedOptions } from "./options.js"
 export { skills } from "./skills.js"
 export { access } from "./access.js"
 export { agentWithSkills } from "./text.js"
@@ -107,18 +110,20 @@ export const ordinaryStart = async (): Promise<void> => {
 }
 
 /** Repair a red baseline through the build tail, as its own reviewed commit. */
-export const fix = async (): Promise<void> => {
+export const fixFlow = async (): Promise<void> => {
   if (await baseline("fix-precheck")) return
   return afterTail(await buildTail(true, start()))
 }
 
 /** Pure review of everything since `reviewBase`. */
-export const review = async (): Promise<void> => {
+export const reviewFlow = async (): Promise<void> => {
   await gate("review-gate", t.reviewGateBlockedMessage())
   return afterTail(await buildTail(false, start()))
 }
 
-export const feature = ordinaryStart
+export const feature = shipped(ordinaryStart)
+export const fix = shipped(fixFlow)
+export const review = shipped(reviewFlow)
 
 export default feature
 

package/src/workflows/options.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest"
+import { configure } from "../flows/index.js"
+import * as workflows from "./index.js"
+
+const { defaults, envDefaults, feature, fix, review, ShippedOptions } = workflows
+
+describe("the shipped workflow factories", () => {
+  it("take exactly the settings the shipped workflows declare as options", () => {
+    expect(Object.keys(ShippedOptions.fields).sort()).toEqual(
+      [...Object.keys(defaults), ...Object.keys(envDefaults)].sort(),
+    )
+  })
+
+  it("lay each option over the shipped setting of its own kind", () => {
+    const result = configure(feature({ qualityReviews: "correctness", testCommand: "npm run ci" }))
+    expect(result).toMatchObject({
+      ok: true,
+      build: {
+        defaults: { ...defaults, qualityReviews: "correctness" },
+        envDefaults: { ...envDefaults, testCommand: "npm run ci" },
+      },
+    })
+  })
+
+  it("build the shipped settings unchanged with no options", () => {
+    for (const factory of [feature, fix, review]) {
+      expect(configure(factory)).toMatchObject({ ok: true, build: { defaults, envDefaults } })
+    }
+  })
+
+  it("reject a misspelled option, at the type level and at load, naming the known ones", () => {
+    // @ts-expect-error — `testComand` is no option
+    const configured = feature({ testComand: "npm test" })
+    const result = configure(configured)
+    expect(result).toMatchObject({ ok: false, issues: [{ path: ["testComand"] }] })
+    expect(result?.ok === false && result.issues[0]?.message).toMatch(
+      /^is unexpected, expected: .*"testCommand"/,
+    )
+  })
+
+  it("reject a removed option at the type level and at load", () => {
+    // @ts-expect-error — `model` was never (or is no longer) an option
+    const result = configure(review({ model: "smart" }))
+    expect(result).toMatchObject({ ok: false, issues: [{ path: ["model"] }] })
+  })
+
+  it("reject a value of the wrong type at the type level and at load", () => {
+    // @ts-expect-error — settings are strings
+    const result = configure(fix({ judgeBudgetBytes: 65536 }))
+    expect(result).toMatchObject({ ok: false, issues: [{ path: ["judgeBudgetBytes"] }] })
+  })
+})

package/src/workflows/options.ts

@@ -0,0 +1,38 @@
+import { Schema } from "effect"
+import { defineWorkflow, type Flow, type WorkflowFactory } from "../flows/index.js"
+import { defaults, envDefaults } from "./vars.js"
+
+const setting = Schema.optionalWith(Schema.String, { exact: true })
+
+export const ShippedOptions = Schema.Struct({
+  reviewBase: setting,
+  judgeBudgetBytes: setting,
+  judgeIdenticalMinP: setting,
+  reviewNoteActionable: setting,
+  qualityReviews: setting,
+  testCommand: setting,
+  fastTestCommand: setting,
+  plannerModel: setting,
+  coderModel: setting,
+})
+
+export type ShippedOptions = Schema.Schema.Encoded<typeof ShippedOptions>
+
+const over = (
+  base: Readonly<Record<string, string>>,
+  options: Readonly<Record<string, string>>,
+): Record<string, string> => ({
+  ...base,
+  ...Object.fromEntries(Object.entries(options).filter(([name]) => Object.hasOwn(base, name))),
+})
+
+/** A shipped flow as a factory: its options override the settings it declares, each in its own kind. */
+export const shipped = (flow: Flow): WorkflowFactory<ShippedOptions> =>
+  defineWorkflow(
+    Schema.standardSchemaV1(ShippedOptions, { onExcessProperty: "error", errors: "all" }),
+    (options) => ({
+      flow,
+      defaults: over(defaults, options),
+      envDefaults: over(envDefaults, options),
+    }),
+  )