@pmelab/gtd 25.0.0 → 26.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "25.0.0",
+  "version": "26.0.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -28,6 +28,8 @@ Or run without installing (prefix every `gtd` below with `npx`) — see
 for the settings most projects tune. A process setting's value is committed to
 Git history; keep secrets in an environment setting (see
 [Settings](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#settings)).
+`GTD_FLAG_<NAME>` variables toggle experimental features — see
+[Feature flags](https://github.com/pmelab/gtd/blob/main/docs/configuration.md#feature-flags).
 
 Also install all three skill sources the bundled workflow names in its prompts —
 none is optional. See

package/dist/gtd.bundle.mjs

@@ -20957,6 +20957,26 @@ const restorability = (git, headHash, tipHash) => gen(function* () {
 	};
 });
 //#endregion
+//#region src/flags/index.ts
+const FLAGS$1 = [];
+const BOOL = {
+	"": false,
+	"0": false,
+	false: false,
+	"1": true,
+	true: true
+};
+const resolveFlags = (env, registry = FLAGS$1) => {
+	const out = {};
+	for (const { name } of registry) {
+		const variable = `GTD_FLAG_${name.toUpperCase()}`;
+		const key = (env[variable] ?? "").toLowerCase();
+		if (!Object.hasOwn(BOOL, key)) throw new Error(`${variable} must be 1, 0, true or false`);
+		out[name] = BOOL[key];
+	}
+	return out;
+};
+//#endregion
 //#region src/install/Version.ts
 const _require = createRequire(import.meta.url);
 const findPackageJson = (fromUrl) => {
@@ -38131,7 +38151,9 @@ const resolveVars = (workflowVars, entryVars, env) => {
 		...entryVars
 	};
 	for (const name of Object.keys(merged)) {
-		const value = env[PREFIX + name.toUpperCase()];
+		const key = PREFIX + name.toUpperCase();
+		if (key.startsWith("GTD_FLAG_")) continue;
+		const value = env[key];
 		if (value !== void 0) merged[name] = value;
 	}
 	return merged;
@@ -42051,7 +42073,10 @@ const runCli = (argv, io) => {
 		io.exit(2);
 	});
 	const out = bufferedArtifactOut(io);
-	return runCommand(plan.command, plan.json, out).pipe(map$4(() => {
+	return flatMap$4(Host, ({ env }) => try_({
+		try: () => resolveFlags(env, io.flags),
+		catch: (e) => new GtdError(e.message)
+	})).pipe(flatMap$4(() => runCommand(plan.command, plan.json, out)), map$4(() => {
 		out.flush();
 		io.exit(0);
 	}), provide$1(io.layers(plan.verbose)), sandbox, catchAll((cause) => isInterruptedOnly(cause) ? failCause$2(cause) : report(io, plan.json.kind !== "off")(cause)));

package/dist/testkit.mjs

@@ -6085,6 +6085,26 @@ const restorability = (git, headHash, tipHash) => gen(function* () {
 	};
 });
 //#endregion
+//#region src/flags/index.ts
+const FLAGS$1 = [];
+const BOOL = {
+	"": false,
+	"0": false,
+	false: false,
+	"1": true,
+	true: true
+};
+const resolveFlags = (env, registry = FLAGS$1) => {
+	const out = {};
+	for (const { name } of registry) {
+		const variable = `GTD_FLAG_${name.toUpperCase()}`;
+		const key = (env[variable] ?? "").toLowerCase();
+		if (!Object.hasOwn(BOOL, key)) throw new Error(`${variable} must be 1, 0, true or false`);
+		out[name] = BOOL[key];
+	}
+	return out;
+};
+//#endregion
 //#region src/install/Version.ts
 const _require = createRequire(import.meta.url);
 const findPackageJson = (fromUrl) => {
@@ -7408,7 +7428,9 @@ const resolveVars = (workflowVars, entryVars, env) => {
 		...entryVars
 	};
 	for (const name of Object.keys(merged)) {
-		const value = env[PREFIX + name.toUpperCase()];
+		const key = PREFIX + name.toUpperCase();
+		if (key.startsWith("GTD_FLAG_")) continue;
+		const value = env[key];
 		if (value !== void 0) merged[name] = value;
 	}
 	return merged;
@@ -11303,7 +11325,10 @@ const runCli = (argv, io) => {
 		io.exit(2);
 	});
 	const out = bufferedArtifactOut(io);
-	return runCommand$1(plan.command, plan.json, out).pipe(map$4(() => {
+	return flatMap$4(Host, ({ env }) => try_({
+		try: () => resolveFlags(env, io.flags),
+		catch: (e) => new GtdError(e.message)
+	})).pipe(flatMap$4(() => runCommand$1(plan.command, plan.json, out)), map$4(() => {
 		out.flush();
 		io.exit(0);
 	}), provide$2(io.layers(plan.verbose)), sandbox, catchAll$1((cause) => isInterruptedOnly(cause) ? failCause$4(cause) : report(io, plan.json.kind !== "off")(cause)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "25.0.0",
+  "version": "26.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": {
@@ -69,6 +69,7 @@
     "src/cli/",
     "src/edge/",
     "src/emit/",
+    "src/flags/",
     "src/install/",
     "src/platform/",
     "src/replay/",

package/src/cli/Cli.test.ts

@@ -23,6 +23,7 @@ import {
   ToolCommands,
 } from "./index.js"
 import { EXIT_CODES, EXIT_RUNTIME_ERROR, EXIT_USAGE_ERROR } from "../wire/index.js"
+import { Host } from "../platform/index.js"
 import { type CommandRequirements } from "./Cli.js"
 import { InMemRepo, testLayers } from "../testkit/index.js"
 import { CONFIG_SCAFFOLD } from "../install/index.js"
@@ -1164,6 +1165,30 @@ describe("runCli — layers() is never invoked for output/usage plans", () => {
   })
 })
 
+describe("runCli — a garbled GTD_FLAG_* value", () => {
+  it("exits 1 naming the variable", async () => {
+    const { io, captured } = capturingIo(
+      () =>
+        Layer.succeed(Host, {
+          root: "/",
+          home: "/",
+          scratchDir: "/",
+          realPath: (p: string) => Effect.succeed(p),
+          env: { GTD_FLAG_BETA: "ture" },
+        }) as unknown as Layer.Layer<CommandRequirements>,
+    )
+    await Effect.runPromise(
+      runCli(["node", "gtd.js", "next"], {
+        ...io,
+        flags: [{ name: "beta", owner: "pmelab", expiry: "2099-01-01", kind: "ops" }],
+      }),
+    )
+    expect(captured().exitCode).toBe(1)
+    expect(captured().stdout).toBe("")
+    expect(captured().stderr).toContain("GTD_FLAG_BETA")
+  })
+})
+
 describe("runCli — exit codes", () => {
   it("output plan: exit is never called (success) — --help and --version still exit 0", async () => {
     const { io, captured } = capturingIo(throwingLayers)

package/src/cli/Cli.ts

@@ -1,6 +1,7 @@
 import { NodeContext } from "@effect/platform-node"
 import { Cause, Effect, Either, Layer } from "effect"
 import {
+  GtdError,
   GtdUsageError,
   Narrator,
   renderFailure,
@@ -9,6 +10,7 @@ import {
   Workspace,
   CommandRunner,
 } from "../platform/index.js"
+import { resolveFlags, type FlagDeclaration } from "../flags/index.js"
 import { GTD_VERSION } from "../install/index.js"
 import {
   ConfigDiscovery,
@@ -1270,6 +1272,8 @@ export interface CliIo {
    * writer when `false`.
    */
   readonly layers: (verbose: boolean) => Layer.Layer<CommandRequirements>
+  /** Test seam: the shipped registry is empty, so a garbled-value test cannot reach the failure path without injecting one. Drop it when the first real flag ships. */
+  readonly flags?: readonly FlagDeclaration[]
 }
 
 // The one write-to-stderr primitive nodeCliIo uses for both `stderr` (errors)
@@ -1403,7 +1407,14 @@ export const runCli = (argv: readonly string[], io: CliIo): Effect.Effect<void,
   }
 
   const out = bufferedArtifactOut(io)
-  return runCommand(plan.command, plan.json, out).pipe(
+  return Effect.flatMap(Host, ({ env }) =>
+    Effect.try({
+      // Validate only: the result is discarded so a garbled value fails before any command runs.
+      try: () => resolveFlags(env, io.flags),
+      catch: (e) => new GtdError((e as Error).message),
+    }),
+  ).pipe(
+    Effect.flatMap(() => runCommand(plan.command, plan.json, out)),
     // `flush()` fires here, on success, BEFORE `io.exit` — the one point
     // where the whole buffered artifact is known-complete and safe to hand
     // to stdout (a failure discards the buffer instead — see

package/src/flags/index.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest"
+import { FLAGS, resolveFlags, type FlagDeclaration, type Flags } from "./index.js"
+
+const registry = [
+  { name: "alpha", owner: "pmelab", expiry: "2020-01-01", kind: "release" },
+  { name: "new_review", owner: "pmelab", expiry: "2099-01-01", kind: "ops" },
+] as const satisfies readonly FlagDeclaration[]
+
+describe("resolveFlags", () => {
+  it.each(["1", "true", "TRUE", "True"])("%s turns a flag on", (value) => {
+    expect(resolveFlags({ GTD_FLAG_ALPHA: value }, registry).alpha).toBe(true)
+  })
+
+  it.each(["0", "false", "FALSE"])("%s turns a flag off", (value) => {
+    expect(resolveFlags({ GTD_FLAG_ALPHA: value }, registry).alpha).toBe(false)
+  })
+
+  it("reads unset and empty as off, with every declared flag a key", () => {
+    expect(resolveFlags({ GTD_FLAG_NEW_REVIEW: "" }, registry)).toEqual({
+      alpha: false,
+      new_review: false,
+    })
+  })
+
+  it.each(["ture", "constructor", "__proto__", "toString"])(
+    "throws naming the variable, not the value %s",
+    (value) => {
+      expect(() => resolveFlags({ GTD_FLAG_NEW_REVIEW: value }, registry)).toThrow(
+        /^GTD_FLAG_NEW_REVIEW must be 1, 0, true or false$/,
+      )
+    },
+  )
+
+  it("reports the first garbled flag in registry order", () => {
+    expect(() => resolveFlags({ GTD_FLAG_NEW_REVIEW: "x", GTD_FLAG_ALPHA: "y" }, registry)).toThrow(
+      /^GTD_FLAG_ALPHA /,
+    )
+  })
+
+  it("ignores an undeclared GTD_FLAG_* key with a garbled value", () => {
+    expect(() => resolveFlags({ GTD_FLAG_NOPE: "ture" }, registry)).not.toThrow()
+  })
+
+  it("resolves a flag past its expiry like any other", () => {
+    expect(registry[0].expiry < new Date().toISOString().slice(0, 10)).toBe(true)
+    expect(resolveFlags({ GTD_FLAG_ALPHA: "1" }, registry).alpha).toBe(true)
+    expect(resolveFlags({ GTD_FLAG_ALPHA: "0" }, registry).alpha).toBe(false)
+    expect(resolveFlags({}, registry).alpha).toBe(false)
+  })
+
+  it("Flags<R> rejects a misspelt name", () => {
+    const flags: Flags<typeof registry> = resolveFlags({}, registry)
+    // @ts-expect-error misspelt flag name
+    void flags.alpah
+  })
+})
+
+describe("FLAGS", () => {
+  it("declares settable, unique variable names", () => {
+    // Vacuous while FLAGS is empty; guards the first declared flag.
+    const names = (FLAGS as readonly FlagDeclaration[]).map(({ name }) => {
+      expect(name).toMatch(/^[a-z][a-z0-9_]*$/)
+      return name
+    })
+    expect(new Set(names).size).toBe(names.length)
+  })
+})

package/src/flags/index.ts

@@ -0,0 +1,39 @@
+// A flag may change how a step runs, never which step comes next: flags are not recorded in
+// history, so replay must not read them. No lint rule enforces this.
+
+export type FlagKind = "release" | "ops" | "experiment"
+
+export interface FlagDeclaration {
+  readonly name: string
+  readonly owner: string
+  /** ISO `YYYY-MM-DD`; never enforced at runtime. */
+  readonly expiry: string
+  readonly kind: FlagKind
+}
+
+// fallow-ignore-next-line unused-export
+export const FLAGS = [] as const satisfies readonly FlagDeclaration[]
+
+/** A misspelt name is a compile error. */
+export type Flags<R extends readonly FlagDeclaration[] = typeof FLAGS> = {
+  readonly [N in R[number]["name"]]: boolean
+}
+
+const BOOL: Record<string, boolean> = { "": false, "0": false, false: false, "1": true, true: true }
+
+export const resolveFlags = <const R extends readonly FlagDeclaration[] = typeof FLAGS>(
+  env: Readonly<Record<string, string | undefined>>,
+  registry: R = FLAGS as unknown as R,
+): Flags<R> => {
+  const out: Record<string, boolean> = {}
+  for (const { name } of registry) {
+    const variable = `GTD_FLAG_${name.toUpperCase()}`
+    const raw = env[variable] ?? ""
+    const key = raw.toLowerCase()
+    if (!Object.hasOwn(BOOL, key)) {
+      throw new Error(`${variable} must be 1, 0, true or false`)
+    }
+    out[name] = BOOL[key]!
+  }
+  return out as Flags<R>
+}

package/src/workflow/vars.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest"
+import { 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) => {
+    expect(resolveVars({ [name]: "off" }, {}, { GTD_FLAG_X: "on" })).toEqual({ [name]: "off" })
+  })
+
+  it.each([
+    ["flags", "GTD_FLAGS"],
+    ["flagship", "GTD_FLAGSHIP"],
+    ["my_flag_x", "GTD_MY_FLAG_X"],
+  ])("%s still takes %s", (name, key) => {
+    expect(resolveVars({ [name]: "off" }, {}, { [key]: "on" })).toEqual({ [name]: "on" })
+  })
+})

package/src/workflow/vars.ts

@@ -13,7 +13,10 @@ export const resolveVars = (
 ): Record<string, string> => {
   const merged = { ...workflowVars, ...entryVars }
   for (const name of Object.keys(merged)) {
-    const value = env[PREFIX + name.toUpperCase()]
+    const key = PREFIX + name.toUpperCase()
+    // GTD_FLAG_* belongs to feature flags; a flag_* setting loses its env override.
+    if (key.startsWith("GTD_FLAG_")) continue
+    const value = env[key]
     if (value !== undefined) merged[name] = value
   }
   return merged