@pmelab/gtd 58.2.0 → 59.0.1

package/src/workflow/load.ts

@@ -50,7 +50,7 @@ export interface ConfigOperations {
 // prints `message` verbatim and would print a duplicated `detail` twice.
 const configError = (diagnostics: readonly Diagnostic[]): GtdError =>
   new GtdError(
-    `gtd config:\n${diagnostics
+    `gtd: config:\n${diagnostics
       .filter((d) => d.severity === "error")
       .map((d) => `  - ${formatDiagnostic(d)}`)
       .join("\n")}`,
@@ -84,7 +84,7 @@ export const refuseLegacyRc: Effect.Effect<void, GtdError, Host | ConfigDiscover
     return yield* Effect.fail(
       new GtdError(
         [
-          "gtd config:",
+          "gtd: config:",
           ...found.map((file) => `  - ${file}: no longer read — delete it`),
           "  gtd 23 removed the .gtdrc files; move each key they set:",
           "    vars    → an option of the workflow factory in gtd.config.ts, or its `defaults` export",
@@ -115,7 +115,7 @@ export const load: Effect.Effect<
     const missing: Diagnostic = {
       severity: "error",
       path: [],
-      message: `no workflows configured: no ${WORKFLOW_MODULE} here or above — run \`gtd install\` to scaffold one`,
+      message: `no workflows configured: no ${WORKFLOW_MODULE} here or above — gtd ships no workflow; \`gtd install\` says where to get one`,
       origin: host.root,
     }
     return yield* Effect.fail(configError([missing]))
@@ -129,7 +129,7 @@ export const load: Effect.Effect<
     try: () => loadWorkflows(module, shipped),
     catch: (e) =>
       new GtdError(
-        `gtd config:\n  - ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`,
+        `gtd: config:\n  - ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`,
       ),
   })
   const compiled = loaded.config
@@ -885,7 +885,7 @@ const replayToFirstStep = (
         outcome.kind === "failed" || outcome.kind === "refused"
           ? outcome.message.replace(/^gtd: /, "")
           : "the default entry must begin at a step — that step is where a finished process waits"
-      return Effect.fail(new GtdError(`gtd config:\n  - ${loaded.file.origin}: ${problem}`))
+      return Effect.fail(new GtdError(`gtd: config:\n  - ${loaded.file.origin}: ${problem}`))
     },
   )
 
@@ -912,7 +912,7 @@ const firstStep = (
     if (reads.length > 0) {
       return yield* Effect.fail(
         new GtdError(
-          `gtd config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start reads ${reads.join(" and ")} — that step is where a finished process waits, so it must not depend on a setting`,
+          `gtd: config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start reads ${reads.join(" and ")} — that step is where a finished process waits, so it must not depend on a setting`,
         ),
       )
     }
@@ -923,7 +923,7 @@ const firstStep = (
     if (atHead === name) return name
     return yield* Effect.fail(
       new GtdError(
-        `gtd config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start depends on the repository's files ("${name}" without them, "${atHead}" at HEAD) — that step is where a finished process waits, so it must not change as files do`,
+        `gtd: config:\n  - ${loaded.file.origin}: the flow's first step on an ordinary start depends on the repository's files ("${name}" without them, "${atHead}" at HEAD) — that step is where a finished process waits, so it must not change as files do`,
       ),
     )
   })

package/src/workflow/skills.test.ts

@@ -17,24 +17,24 @@ describe("resolveScopeSkills", () => {
     const message = await failure(() => {
       throw new Error("boom")
     })
-    expect(message).toContain(`gtd config:\n  - ${FILE}: boom`)
+    expect(message).toContain(`gtd: config:\n  - ${FILE}: boom`)
   })
 
   it("rejects a non-object return", async () => {
     expect(await failure(() => ["a"])).toContain(
-      `gtd config:\n  - ${FILE}: skills export must return an object of scope -> skill names`,
+      `gtd: config:\n  - ${FILE}: skills export must return an object of scope -> skill names`,
     )
   })
 
   it("rejects a non-array value", async () => {
     expect(await failure(() => ({ a: "x" }))).toContain(
-      `gtd config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
+      `gtd: config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
     )
   })
 
   it("rejects a non-string entry", async () => {
     expect(await failure(() => ({ a: ["x", 1] }))).toContain(
-      `gtd config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
+      `gtd: config:\n  - ${FILE}: skills export: "a" must be an array of skill names`,
     )
   })
 
@@ -80,7 +80,7 @@ describe("resolveScopeAccess", () => {
 
   it("rejects a malformed export with the file", async () => {
     expect(message(await run({ access: () => ["a"] }))).toContain(
-      `gtd config:\n  - ${FILE}: access export must return an object`,
+      `gtd: config:\n  - ${FILE}: access export must return an object`,
     )
     expect(message(await run({ access: () => ({ a: { write: "x" } }) }))).toContain(
       `${FILE}: access export: "a": access.write must be an array`,

package/src/workflow/skills.ts

@@ -7,7 +7,7 @@ import type { Diagnostic } from "./Diagnostic.js"
 import { failOnErrors } from "./load.js"
 
 const fail = (origin: string, message: string): GtdError =>
-  new GtdError(`gtd config:\n  - ${origin}: ${message}`)
+  new GtdError(`gtd: config:\n  - ${origin}: ${message}`)
 
 const checkShape = (value: unknown): Record<string, readonly string[]> => {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {

package/src/workflow/vars.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { resolveStartVars, resolveVars } from "./vars.js"
+import { ownFlagRefusal, resolveStartVars, resolveVars } from "./vars.js"
 
 describe("resolveVars — GTD_FLAG_* belongs to feature flags", () => {
   it.each(["flag_x", "FLAG_X", "Flag_x"])("%s keeps its default with GTD_FLAG_X set", (name) => {
@@ -30,9 +30,36 @@ describe("resolveStartVars", () => {
     })
   })
 
-  it("GTD_FLAG_X never overrides, while GTD_<NAME> still does for other names", () => {
+  it("GTD_FLAG_X never overrides one of gtd's own flags, while GTD_<NAME> still does for other names", () => {
     expect(
-      resolveStartVars({ flag_x: "0", a: "1" }, {}, {}, { GTD_FLAG_X: "1", GTD_A: "2" }),
+      resolveStartVars(
+        { flag_x: "0", a: "1" },
+        { flag_x: "0" },
+        {},
+        { GTD_FLAG_X: "1", GTD_A: "2" },
+      ),
     ).toEqual({ flag_x: "0", a: "2" })
   })
+
+  it("pins a workflow's own flag from GTD_FLAG_<NAME>, below --var", () => {
+    expect(resolveStartVars({ flag_own: "0" }, {}, {}, { GTD_FLAG_OWN: "true" })).toEqual({
+      flag_own: "1",
+    })
+    expect(
+      resolveStartVars({ flag_own: "0" }, {}, { flag_own: "0" }, { GTD_FLAG_OWN: "1" }),
+    ).toEqual({
+      flag_own: "0",
+    })
+    expect(resolveStartVars({ flag_own: "1" }, {}, {}, {})).toEqual({ flag_own: "1" })
+  })
+})
+
+describe("ownFlagRefusal", () => {
+  it("refuses a workflow's own flag set to anything but 1, 0, true or false", () => {
+    expect(ownFlagRefusal({ flag_own: "0" }, {}, { GTD_FLAG_OWN: "yes" })).toBe(
+      "GTD_FLAG_OWN must be 1, 0, true or false",
+    )
+    expect(ownFlagRefusal({ flag_own: "0" }, {}, { GTD_FLAG_OWN: "TRUE" })).toBeUndefined()
+    expect(ownFlagRefusal({ flag_x: "0" }, { flag_x: "1" }, { GTD_FLAG_X: "yes" })).toBeUndefined()
+  })
 })

package/src/workflow/vars.ts

@@ -29,10 +29,38 @@ export const resolveVars = (
   return merged
 }
 
+const FLAG_VALUES: Readonly<Record<string, string>> = { "0": "0", false: "0", "1": "1", true: "1" }
+
+const flagVariable = (setting: string): string =>
+  `GTD_FLAG_${setting.slice("flag_".length).toUpperCase()}`
+
+/** The `flag_<name>` settings a workflow declares that gtd's own flags lack: the workflow's own release flags. */
+const ownFlags = (
+  workflowVars: Readonly<Record<string, string>>,
+  flags: Readonly<Record<string, string>>,
+): string[] =>
+  Object.keys(workflowVars).filter(
+    (name) => name.startsWith("flag_") && !Object.hasOwn(flags, name),
+  )
+
+/** Why a workflow's own release flag cannot start, if one is set to anything but 1, 0, true or false. */
+export const ownFlagRefusal = (
+  workflowVars: Readonly<Record<string, string>>,
+  flags: Readonly<Record<string, string>>,
+  env: Readonly<Record<string, string | undefined>>,
+): string | undefined => {
+  const bad = ownFlags(workflowVars, flags).find((name) => {
+    const raw = env[flagVariable(name)] ?? ""
+    return raw !== "" && !Object.hasOwn(FLAG_VALUES, raw.toLowerCase())
+  })
+  return bad === undefined ? undefined : `${flagVariable(bad)} must be 1, 0, true or false`
+}
+
 /**
  * `resolveVars` for a process being STARTED: `flags` land between the workflow
- * defaults and `--var`, for already-declared names only. A running process never
- * calls this — it replays its pinned record.
+ * defaults and `--var`, for already-declared names only, and so does
+ * `GTD_FLAG_<NAME>` for a `flag_<name>` the workflow declares itself. A running
+ * process never calls this — it replays its pinned record.
  */
 export const resolveStartVars = (
   workflowVars: Readonly<Record<string, string>>,
@@ -43,6 +71,10 @@ export const resolveStartVars = (
   const declared = Object.fromEntries(
     Object.entries(flags).filter(([name]) => Object.hasOwn(workflowVars, name)),
   )
+  for (const name of ownFlags(workflowVars, flags)) {
+    const value = FLAG_VALUES[(env[flagVariable(name)] ?? "").toLowerCase()]
+    if (value !== undefined) declared[name] = value
+  }
   return resolveVars({ ...workflowVars, ...declared }, entryVars, env)
 }
 

package/src/workflow-kit/index.ts

@@ -1,4 +1,4 @@
-// Building blocks the shipped workflows share. Policy-free: every skill list,
+// 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"