@pmelab/gtd 21.1.0 → 22.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "21.1.0",
+  "version": "22.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

@@ -512,7 +512,10 @@ can add its own. `gtd --workflow <name>` starts any workflow by name.
 The workflow itself is a plain async TypeScript function, and the
 `gtd.config.ts` at the repository root names it: the one `gtd install` writes
 re-exports the shipped workflows from `@pmelab/gtd/workflows`, and the pieces
-they are built from are exported for yours to reuse. See
+they are built from are exported for yours to reuse. Each shipped workflow is a
+factory — `feature({ testCommand: "npm run ci" })` — whose options gtd validates
+when it loads the config: a misspelled or mistyped one fails every command,
+naming the workflow, the key and what was expected. See
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md) —
 and remember gtd evaluates that file on every command. A shared workflow package
 bundling its own `@pmelab/gtd` is checked against the running gtd and refused,

package/dist/gtd.bundle.mjs

@@ -32693,6 +32693,71 @@ const requireRevert = (edited, base) => {
 	refuse(`gtd land: require-revert: ${residue.join(", ")} still differ from ${base}~1 — the revert did not take. Run \`git checkout ${base}~1 -- ${quoted}\`, then \`gtd land\` again.`);
 };
 //#endregion
+//#region src/flows/factory.ts
+const FACTORY = Symbol.for("@pmelab/gtd/workflow-factory");
+/**
+* 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.
+*/
+const defineWorkflow = (schema, build) => {
+	const internals = {
+		schema,
+		build
+	};
+	const factory = (options) => ({
+		[FACTORY]: {
+			...internals,
+			options
+		},
+		then: () => {
+			throw new Error("a configured workflow is not a flow — compose fixFlow/reviewFlow instead");
+		}
+	});
+	return Object.assign(factory, { [FACTORY]: internals });
+};
+const internalsOf = (value) => (typeof value === "function" || typeof value === "object" && value !== null) && FACTORY in value ? value[FACTORY] : void 0;
+const isFactoryWorkflow = (value) => internalsOf(value) !== void 0;
+const segment = (key) => {
+	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.
+*/
+const configure$1 = (value, overrides = {}) => {
+	const internals = internalsOf(value);
+	if (internals === void 0) return void 0;
+	const options = {
+		...internals.options,
+		...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 !== void 0) 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)
+	};
+};
+//#endregion
 //#region src/flows/index.ts
 var flows_exports = /* @__PURE__ */ __exportAll({
 	FLOWS_PROTOCOL: () => 1,
@@ -32706,12 +32771,15 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	checkScript: () => checkScript,
 	codeChanges: () => codeChanges,
 	codeThreads: () => codeThreads,
+	configure: () => configure$1,
+	defineWorkflow: () => defineWorkflow,
 	env: () => env,
 	glob: () => glob,
 	hasThreadFor: () => hasThreadFor,
 	head: () => head,
 	human: () => human,
 	installContext: () => installContext,
+	isFactoryWorkflow: () => isFactoryWorkflow,
 	judge: () => judge,
 	moveScript: () => moveScript,
 	numeric: () => numeric,
@@ -49589,10 +49657,10 @@ const replay = async (input) => {
 };
 //#endregion
 //#region src/workflow/ConfigSchema.ts
-/** The `vars:` shape: a flat name -> scalar map (`compileVarsMap` coerces every scalar to a string). */
+/** The `vars:` shape: a flat name -> scalar map (`compileVarsMap` coerces every scalar to a string). Its names are the workflow's business, never core's. */
 const varsJsonSchema = {
 	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",
 		"number",
@@ -49602,7 +49670,7 @@ const varsJsonSchema = {
 /** The `env:` shape: environment settings, read live on every invocation and never pinned to a process. */
 const envJsonSchema = {
 	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",
 		"number",
@@ -57008,11 +57076,12 @@ const load = gen(function* () {
 		catch: (e) => new GtdError(`gtd: ${e instanceof Error ? e.message : String(e)}`)
 	});
 	const loaded = yield* try_({
-		try: () => loadWorkflows(module, shipped),
+		try: () => loadWorkflows(module, shipped, compiled),
 		catch: (e) => new GtdError(`gtd config:\n  - ${module.filepath}: ${e instanceof Error ? e.message : String(e)}`)
 	});
-	const diagnostics = report(wrongKindDiagnostics(loaded.file, compiled), [...rcOrder, module.filepath]);
+	const diagnostics = report([...loaded.diagnostics, ...wrongKindDiagnostics(loaded.settings, compiled)], [...rcOrder, module.filepath]);
 	yield* failOnErrors(diagnostics);
+	if (loaded.default === void 0) return yield* die("unreachable: a default fails to build only with an error reported");
 	const initial = yield* firstStep(loaded.default, headTree(yield* Workspace));
 	const steering = loaded.file.steering;
 	const define = (entry) => ({
@@ -57034,8 +57103,8 @@ const load = gen(function* () {
 	const resolve = (name, entry) => ({
 		name,
 		def: define(entry),
-		vars: { ...entry.file.defaults },
-		env: { ...entry.file.envDefaults }
+		vars: { ...entry.defaults },
+		env: { ...entry.envDefaults }
 	});
 	const defaultWorkflow = resolve(loaded.default.name, loaded.default);
 	return {
@@ -57056,9 +57125,9 @@ const load = gen(function* () {
 	};
 });
 /** A name under the wrong key (or under both) in a `.gtdrc` layer: each is an error at its own origin. */
-const wrongKindDiagnostics = (file, compiled) => {
-	const isEnvOnly = (key) => Object.hasOwn(file.envDefaults, key);
-	const isVarOnly = (key) => Object.hasOwn(file.defaults, key);
+const wrongKindDiagnostics = (settings, compiled) => {
+	const isEnvOnly = (key) => Object.hasOwn(settings.envDefaults, key);
+	const isVarOnly = (key) => Object.hasOwn(settings.defaults, key);
 	const error = (path, message, origin) => ({
 		severity: "error",
 		path,
@@ -57179,16 +57248,20 @@ const RESERVED_EXPORTS = /* @__PURE__ */ new Set([
 	"access",
 	"doors"
 ]);
+/** The rules every declared setting meets, whether a file's export or a factory's build. */
+const checkSettings = (defaults, envDefaults, declares) => {
+	for (const [kind, record] of [["defaults", defaults], ["envDefaults", envDefaults]]) for (const [name, setting] of Object.entries(record)) {
+		if (!isSettingName(name)) throw new Error(`${declares(kind)} ${JSON.stringify(name)}, not a valid setting name — ${SETTING_NAME_RULE}`);
+		if (typeof setting !== "string") throw new Error(`${declares(kind)} ${JSON.stringify(name)}, whose value is not a string`);
+	}
+	const both = Object.keys(defaults).filter((name) => Object.hasOwn(envDefaults, name));
+	if (both.length > 0) throw new Error(`${both.map((name) => `"${name}"`).join(", ")} declared in both "defaults" and "envDefaults" — a setting is a process setting or an environment setting, not both`);
+};
 /** A module's per-file exports: `defaults`, `envDefaults`, `steering`, `skills`, `access`, `summary`, `base`. */
 const fileFrom = (exports, origin, dependencyFiles) => {
 	const defaults = stringRecord(exports, "defaults");
 	const envDefaults = stringRecord(exports, "envDefaults");
-	for (const [exportName, record] of [["defaults", defaults], ["envDefaults", envDefaults]]) {
-		const bad = Object.keys(record).find((name) => !isSettingName(name));
-		if (bad !== void 0) throw new Error(`the "${exportName}" export declares ${JSON.stringify(bad)}, not a valid setting name — ${SETTING_NAME_RULE}`);
-	}
-	const both = Object.keys(defaults).filter((name) => Object.hasOwn(envDefaults, name));
-	if (both.length > 0) throw new Error(`${both.map((name) => `"${name}"`).join(", ")} declared in both "defaults" and "envDefaults" — a setting is a process setting or an environment setting, not both`);
+	checkSettings(defaults, envDefaults, (kind) => `the "${kind}" export declares`);
 	return {
 		defaults,
 		envDefaults,
@@ -57243,42 +57316,171 @@ const checkDoors = (declared, catalogue) => {
 };
 const namespaceOf = (exported) => typeof exported === "object" && exported !== null ? exported : {};
 /**
-* Evaluate `gtd.config.ts`. Every exported function but the reserved names is
-* a workflow named by its export. `cache` is jiti's OWN per-call module cache
-* (unrelated to the instance's `moduleCache: false`) — passing an empty object
-* in has the side effect of collecting every real file jiti resolved
-* evaluating this module, module AND every relative import it pulled in,
-* transitively.
+* Evaluate `gtd.config.ts`. Every exported function or factory workflow but
+* the reserved names is a workflow named by its export. `cache` is jiti's OWN
+* per-call module cache (unrelated to the instance's `moduleCache: false`) —
+* passing an empty object in has the side effect of collecting every real file
+* jiti resolved evaluating this module, module AND every relative import it
+* pulled in, transitively.
 */
-const loadWorkflows = (module, shipped) => {
+const loadWorkflows = (module, shipped, compiled) => {
 	const cache = {};
 	const exports = namespaceOf(jiti(shipped).evalModule(module.source, {
 		filename: module.filepath,
 		cache
 	}));
 	const file = fileFrom(exports, module.filepath, Object.keys(cache));
-	const catalogue = /* @__PURE__ */ new Map();
-	for (const [name, value] of Object.entries(exports)) {
-		if (RESERVED_EXPORTS.has(name) || typeof value !== "function") continue;
-		catalogue.set(name, {
-			flow: value,
-			file
+	const exported = Object.entries(exports).filter(([name, value]) => !RESERVED_EXPORTS.has(name) && isWorkflow(value));
+	const value = defaultExport(exports);
+	const defaultName = exported.find(([, other]) => other === value)?.[0] ?? "default";
+	const built = /* @__PURE__ */ new Map();
+	const rejections = [];
+	const declarers = declarersOf([...exported, [defaultName, value]], file, compiled);
+	for (const [name, entry] of [...exported, [defaultName, value]]) if (!built.has(entry)) built.set(entry, buildWorkflow(name, entry, file, compiled, rejections, declarers));
+	const catalogue = new Map(exported.flatMap(([name, entry]) => {
+		const workflow = built.get(entry);
+		return workflow === void 0 ? [] : [[name, workflow]];
+	}));
+	const defaultWorkflow = built.get(value);
+	return {
+		file,
+		catalogue,
+		doors: rejections.length > 0 ? /* @__PURE__ */ new Map() : checkDoors(doorsFrom(exports), catalogue),
+		default: defaultWorkflow && {
+			...defaultWorkflow,
+			name: defaultName
+		},
+		settings: mergeSettings([...built.values()].filter((w) => w !== void 0)),
+		diagnostics: nameRejections(rejections)
+	};
+};
+const isWorkflow = (value) => typeof value === "function" || isFactoryWorkflow(value);
+const defaultExport = (exports) => {
+	const value = exports.default;
+	if (value === void 0) throw new Error("no default export — export the workflow an ordinary start runs (`gtd install` scaffolds one)");
+	if (!isWorkflow(value)) throw new Error("the default export is not a function");
+	return value;
+};
+const mergeSettings = (all) => ({
+	defaults: Object.assign({}, ...all.map((s) => s.defaults)),
+	envDefaults: Object.assign({}, ...all.map((s) => s.envDefaults))
+});
+/** Each setting name, with who declares it: the file's exports, or a factory's own build. */
+const declarersOf = (exported, file, compiled) => {
+	const declarers = /* @__PURE__ */ new Map();
+	const declare = (key, who) => {
+		declarers.set(key, (declarers.get(key) ?? /* @__PURE__ */ new Set()).add(who));
+	};
+	for (const key of [...Object.keys(file.defaults), ...Object.keys(file.envDefaults)]) declare(key, file);
+	for (const [, value] of exported) {
+		const own = ownBuild(value, {
+			...compiled.rcVars,
+			...compiled.rcEnv
 		});
+		if (own?.ok) for (const key of [...Object.keys(own.build.defaults ?? {}), ...Object.keys(own.build.envDefaults ?? {})]) declare(key, value);
+	}
+	return declarers;
+};
+/**
+* A factory's build as its call alone gives it — or, when the call fails, with
+* the `.gtdrc` values for just the options it flagged, since a name the factory
+* itself rejects is its own.
+*/
+const ownBuild = (value, rc) => {
+	const bare = configure$1(value);
+	if (bare === void 0 || bare.ok) return bare;
+	const flagged = new Set(bare.issues.map((issue) => issue.path[0]));
+	return configure$1(value, Object.fromEntries(Object.entries(rc).filter(([key]) => flagged.has(key))));
+};
+/**
+* One exported workflow: a plain flow as-is, a factory validated and built.
+* `.gtdrc` `vars:`/`env:` values reach a factory as options, so the factory
+* judges them — except a name some other loaded workflow declares and this one
+* does not, which belongs to that workflow.
+*/
+const buildWorkflow = (name, value, file, compiled, rejections, declarers) => {
+	if (configure$1(value) === void 0) return {
+		flow: value,
+		file,
+		defaults: file.defaults,
+		envDefaults: file.envDefaults
+	};
+	const belongsElsewhere = (key) => {
+		const who = declarers.get(key);
+		return who !== void 0 && !who.has(value);
+	};
+	const overrides = Object.fromEntries(Object.entries({
+		...compiled.rcVars,
+		...compiled.rcEnv
+	}).filter(([key]) => !belongsElsewhere(key)));
+	const result = configure$1(value, overrides);
+	if (!result.ok) {
+		for (const issue of result.issues) rejections.push(optionDiagnostic(name, issue, overrides, file, compiled));
+		return;
 	}
-	const flow = exports.default;
-	if (flow === void 0) throw new Error("no default export — export the workflow an ordinary start runs (`gtd install` scaffolds one)");
-	if (typeof flow !== "function") throw new Error("the default export is not a function");
-	const name = [...catalogue].find(([, entry]) => entry.flow === flow)?.[0] ?? "default";
 	return {
+		flow: result.build.flow,
 		file,
-		catalogue,
-		doors: checkDoors(doorsFrom(exports), catalogue),
-		default: {
-			flow,
-			file,
-			name
-		}
+		...builtSettings(name, file, result.build)
+	};
+};
+/** A factory's settings over its file's, held to the rules a file's own exports are. */
+const builtSettings = (name, file, build) => {
+	checkSettings(build.defaults ?? {}, build.envDefaults ?? {}, (kind) => `workflow "${name}" builds ${kind}`);
+	const defaults = {
+		...file.defaults,
+		...build.defaults
+	};
+	const envDefaults = {
+		...file.envDefaults,
+		...build.envDefaults
 	};
+	checkSettings(defaults, envDefaults, (kind) => `workflow "${name}" builds ${kind}`);
+	return {
+		defaults,
+		envDefaults
+	};
+};
+/** A rejected option, reported where its value came from: the innermost `.gtdrc` that set it, else `gtd.config.ts`. */
+const optionDiagnostic = (workflow, issue, overrides, file, compiled) => {
+	const [key] = issue.path;
+	const message = `${issue.path.length > 0 ? `option "${issue.path.join(".")}"` : "options"}: ${issue.message}`;
+	if (!(typeof key === "string" && Object.hasOwn(overrides, key))) return {
+		workflow,
+		severity: "error",
+		path: issue.path,
+		message,
+		origin: file.origin
+	};
+	const kind = Object.hasOwn(compiled.rcEnv, key) ? "env" : "vars";
+	const origin = [...kind === "env" ? compiled.envKeys : compiled.varsKeys].reverse().find((entry) => entry.key === key)?.origin;
+	return {
+		workflow,
+		severity: "error",
+		path: [kind, ...issue.path],
+		message,
+		origin: origin ?? file.origin
+	};
+};
+const nameRejections = (rejections) => {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const rejection of rejections) {
+		const key = JSON.stringify([
+			rejection.origin,
+			rejection.path,
+			rejection.message
+		]);
+		const group = grouped.get(key);
+		if (group === void 0) grouped.set(key, {
+			first: rejection,
+			workflows: [rejection.workflow]
+		});
+		else group.workflows.push(rejection.workflow);
+	}
+	return [...grouped.values()].map(({ first: { workflow: _, ...diagnostic }, workflows }) => ({
+		...diagnostic,
+		message: `${workflows.length > 1 ? "workflows" : "workflow"} ${workflows.map((w) => `"${w}"`).join(", ")} ${diagnostic.message}`
+	}));
 };
 const headTree = (workspace) => {
 	let entries;