@pmelab/gtd 24.0.0 → 24.1.0

package/dist/flows.mjs

@@ -0,0 +1,525 @@
+import { t as __exportAll } from "./chunks/rolldown-runtime-8H4AJuhK.mjs";
+//#region src/flows/runtime.ts
+/**
+* Bump only when the installed `FlowContext` object changes shape or semantics;
+* type-only authoring-API changes don't count. A bump past 1 must keep v1
+* members working or move the context to a new symbol key — pre-handshake
+* facades never read the protocol.
+*/
+const FLOWS_PROTOCOL = 1;
+var FlowsProtocolError = class extends Error {
+	constructor(engine, flows) {
+		super(`gtd: the workflow speaks flows protocol ${flows}, but the engine installed protocol ${engine} — ${engine < flows ? "upgrade the gtd that runs it" : "upgrade the @pmelab/gtd the workflow imports"}`);
+		this.name = "FlowsProtocolError";
+	}
+};
+const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context");
+const PROTOCOL_KEY = Symbol.for("@pmelab/gtd/flow-protocol");
+const MISMATCH_KEY = Symbol.for("@pmelab/gtd/flow-protocol-mismatch");
+/** Engine-only. */
+const installContext = (context) => {
+	const holder = globalThis;
+	holder[CONTEXT_KEY] = context;
+	holder[PROTOCOL_KEY] = 1;
+	holder[MISMATCH_KEY] = void 0;
+};
+/** Engine-only: the mismatch a facade copy hit during this replay, if any. */
+const protocolMismatch = () => globalThis[MISMATCH_KEY];
+const ctx = () => {
+	const holder = globalThis;
+	const context = holder[CONTEXT_KEY];
+	if (context === void 0) throw new Error("gtd: a workflow step or helper was called outside a gtd replay");
+	const protocol = holder[PROTOCOL_KEY] ?? 1;
+	if (protocol !== 1) {
+		const error = new FlowsProtocolError(protocol, 1);
+		holder[MISMATCH_KEY] ??= error;
+		throw error;
+	}
+	return context;
+};
+/** An agent turn: `prompt` is emitted, the driver lands the diff. */
+const agent = (name, prompt, options = {}) => ctx().step({
+	kind: "agent",
+	name,
+	prompt,
+	options
+});
+/** A human gate: the process rests until a person lands a turn. */
+const human = (name, options = {}) => ctx().step({
+	kind: "human",
+	name,
+	options
+});
+/** A check: `body` runs at the edge and its effect on the tree is committed. */
+const run = (name, body, options = {}) => ctx().step({
+	kind: "run",
+	name,
+	body,
+	options
+});
+/** A judge gate: resolves to what the judge answered, for the flow to decide on. */
+const judge = (name, spec) => {
+	const { questions, evidence, ...options } = spec;
+	return ctx().step({
+		kind: "judge",
+		name,
+		questions,
+		evidence,
+		options
+	});
+};
+/** End the episode from any depth. The next episode starts the flow afresh. */
+const restart = () => ctx().step({ kind: "restart" });
+/** Refuse the pending turn: nothing lands, the process stays where it rests. */
+const refuse = (message) => ctx().refuse(message);
+/**
+* Run `fn` inside a scope: `scope("build", fn)` prefixes every step name with
+* `build.` (also their memory scope); an object may add the model and system
+* prompt its agent steps run with.
+*/
+const scope = async (scope, fn) => {
+	const context = ctx();
+	context.pushScope(typeof scope === "string" ? { name: scope } : scope);
+	try {
+		return await fn();
+	} finally {
+		context.popScope();
+	}
+};
+const read = (path) => ctx().read(path);
+/** Every path in the tree matching `pattern` (`*` stays within a segment, `**` crosses them). */
+const glob = (pattern) => ctx().glob(pattern);
+const toChanges = (list) => Object.freeze(Object.assign([...list], {
+	paths: list.map((c) => c.path),
+	get: (path) => list.find((c) => c.path === path)
+}));
+/** What the last step changed, optionally only the paths matching a glob. */
+const changes = (pattern) => {
+	const context = ctx();
+	const all = context.changes();
+	return toChanges(pattern === void 0 ? all : all.filter((c) => context.matches(c.path, pattern)));
+};
+/**
+* Every change from the tree at `hash` to the tree replay stands on — this
+* package's own range, when `hash` is captured at its first step. `hash` must
+* be the episode's base or one of its commits; anything else fails the step.
+*/
+const changesSince = (hash, pattern) => {
+	const context = ctx();
+	const all = context.changesSince(hash);
+	return toChanges(pattern === void 0 ? all : all.filter((c) => context.matches(c.path, pattern)));
+};
+/** The commit the process stands on at this point of the flow. */
+const head = () => ctx().head();
+/** The process's diff base: the commit before it began, or the base `gtd --workflow` fixed. */
+const start = () => ctx().start();
+/** The skill list `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. */
+const skillsFor = (localName) => ctx().skillsFor(localName);
+/** The folded access `localName` (scoped from here, same as `agent()`) resolves to — for a prompt preamble. */
+const accessFor = (localName, file) => ctx().accessFor(localName, file);
+const settingsProxy = (read) => new Proxy({}, {
+	get: (_target, key) => typeof key === "string" ? read()[key] : void 0,
+	has: (_target, key) => typeof key === "string" && key in read(),
+	ownKeys: () => Object.keys(read()),
+	getOwnPropertyDescriptor: (_target, key) => typeof key === "string" && key in read() ? {
+		enumerable: true,
+		configurable: true,
+		value: read()[key]
+	} : void 0
+});
+/** The process settings: pinned at process start, so flow code may branch on them. */
+const vars = settingsProxy(() => ctx().vars);
+/**
+* The environment settings: resolved live on every invocation. Flow code must
+* read them only where they cannot change the next step (step options, script
+* bodies) — replay cannot enforce this.
+*/
+const env = settingsProxy(() => ctx().env);
+/** The top-level `## ` heading texts of markdown `text`. */
+const sections = (text) => ctx().sections(text);
+/** The top-level `## ` sections of markdown `text`, each with its own markdown. */
+const sectionBodies = (text) => ctx().sectionBodies(text);
+/** Every `H:`/`A:` thread (a footnote) in `text`. */
+const threads = (text) => ctx().threads(text);
+/** Every `H:`/`A:` thread in line comments of the files changed since the process's diff base. */
+const codeThreads = () => ctx().codeThreads();
+/** The qa-format questions in `text` that are still unanswered. */
+const openQuestions = (text) => ctx().openQuestions(text);
+//#endregion
+//#region src/flows/scripts.ts
+/** POSIX single-quoting: `value` survives the shell as one word, verbatim. */
+const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+const removal = (paths) => paths.length === 0 ? [] : [`rm -rf -- ${paths.map(quote).join(" ")}`];
+/**
+* Run `command` and keep its outcome in the tree: on failure its output (or
+* a note that there was none) lands in `report`, on success `report` goes.
+*/
+const checkScript = (command, options) => {
+	const report = quote(options.report);
+	const output = quote(`${options.report}.output`);
+	return [
+		"#!/usr/bin/env sh",
+		"set +e",
+		...options.preamble ?? [],
+		...removal(options.sweep ?? []),
+		`mkdir -p "$(dirname ${report})"`,
+		"(",
+		command,
+		`) > ${output} 2>&1`,
+		"code=$?",
+		"if [ \"$code\" -ne 0 ]; then",
+		`  if [ -s ${output} ]; then`,
+		`    mv ${output} ${report}`,
+		"  else",
+		`    rm -f ${output}`,
+		`    printf 'the test command failed with exit code %s and produced no output.' "$code" > ${report}`,
+		"  fi",
+		`  printf '\\n<!-- gtd check %s -->\\n' ${quote(options.stamp)} >> ${report}`,
+		"else",
+		`  rm -f ${output} ${report}`,
+		...removal(options.sweepOnGreen ?? []).map((line) => `  ${line}`),
+		"fi",
+		""
+	].join("\n");
+};
+/**
+* Reverse-apply `commit`'s changes to the working tree. A failure — the
+* patch no longer applies — writes `failure` and git's error to `report`,
+* since a failed revert and one with nothing to undo both leave the tree clean.
+*/
+const revertScript = (commit, report, failure) => {
+	const range = `${quote(`${commit}^`)} ${quote(commit)}`;
+	const error = quote(`${report}.output`);
+	return [
+		"#!/usr/bin/env sh",
+		"set +e",
+		`if ! git diff --quiet ${range} --; then`,
+		`  mkdir -p "$(dirname ${quote(report)})"`,
+		`  git diff --binary ${range} -- | git apply -R 2> ${error}`,
+		"  code=$?",
+		"  if [ \"$code\" -ne 0 ]; then",
+		"    {",
+		`      printf '%s\\n\\n' ${quote(failure)}`,
+		`      if [ -s ${error} ]; then cat ${error}; else printf 'Reverting it exited %s and produced no output.\\n' "$code"; fi`,
+		`    } > ${quote(report)}`,
+		"  fi",
+		`  rm -f ${error}`,
+		"fi",
+		""
+	].join("\n");
+};
+/**
+* Undo the edits one commit made to `paths`: each goes back to its content
+* before `commit` — or away, when `commit` added it — but only while it is
+* still exactly as `commit` left it. A path changed since is left alone.
+*/
+const restoreScript = (commit, paths, source) => {
+	const unchanged = (path) => `git diff --quiet ${quote(commit)} -- ${quote(path)}`;
+	return [
+		"#!/usr/bin/env sh",
+		"set +e",
+		...paths.restore.map((path) => `${unchanged(path)} && git restore --source=${quote(source ?? `${commit}~1`)} --worktree -- ${quote(path)}`),
+		...paths.remove.map((path) => `${unchanged(path)} && rm -f -- ${quote(path)}`),
+		""
+	].join("\n");
+};
+/** Remove `paths` from the working tree; absent ones are fine. */
+const removeScript = (paths) => [
+	"#!/usr/bin/env sh",
+	...removal(paths),
+	""
+].join("\n");
+/** Move `from` to `to`, creating `to`'s directory. */
+const moveScript = (from, to) => [
+	"#!/usr/bin/env sh",
+	"set -e",
+	`mkdir -p "$(dirname ${quote(to)})"`,
+	`mv -- ${quote(from)} ${quote(to)}`,
+	""
+].join("\n");
+//#endregion
+//#region src/flows/helpers.ts
+/** Whether a judge answered `expected` at a probability of at least `minP`. */
+const answered = (answer, expected, minP) => answer !== void 0 && answer.answer === expected && answer.p >= minP;
+/** A numeric var, or `fallback` when it is unset, blank or not a finite number. */
+const numeric = (value, fallback) => {
+	const n = Number(value);
+	return value === void 0 || value.trim() === "" || !Number.isFinite(n) ? fallback : n;
+};
+/** Whether the last step added or rewrote `path`. */
+const wrote = (path) => changes(path).some((c) => c.status !== "deleted");
+/**
+* A step that runs `command` through the driver and keeps its outcome in the
+* tree: a failure writes `report`, a pass removes it. Resolves `true` when the
+* command passed.
+*/
+const check = async (name, command, options) => {
+	const { report, label, sweep, sweepOnGreen, preamble } = options;
+	await run(name, checkScript(command, {
+		report,
+		stamp: head().slice(0, 7),
+		sweep,
+		sweepOnGreen,
+		preamble
+	}), { label });
+	return !wrote(report);
+};
+const isCode = (path) => path !== ".gtd" && !path.startsWith(".gtd/");
+/** The last step's changes outside `.gtd/`. */
+const codeChanges = () => changes().filter((c) => isCode(c.path));
+/** Refuse a turn whose only change deletes `file` — unless it says it found nothing to do. */
+const requireProgress = (file) => {
+	const change = changes().get(file);
+	if (change?.status !== "deleted") return;
+	if (codeChanges().length > 0) return;
+	if ((change.before ?? "").trim().startsWith("NOTHING ACTIONABLE")) return;
+	refuse(`gtd land: feedback-progress: ${file} was deleted without addressing its instructions — implement the changes it lists (then delete it), don't just remove the file.`);
+};
+/** Refuse a turn that leaves a question in `file` unanswered. An untouched tree is silence, and allowed. */
+const requireAnswers = (file) => {
+	if (changes().length === 0) return;
+	const open = openQuestions(read(file) ?? "");
+	if (open.length === 0) return;
+	const list = open.map((q) => `  - ${file}:${q.line}: ${q.question}`).join("\n");
+	refuse(`gtd land: answer-completeness: ${open.length} open question(s) in ${file} not answered — tick exactly one option per question, or delete a question you don't want to answer. To accept the plan as-is instead, revert everything and re-run:\n${list}`);
+};
+/** Footnote threads in `file` waiting on `waitingOn`, plus any with a syntax fault — a fault refuses both ways. */
+const threadLines = (file, waitingOn) => threads(read(file) ?? "").filter((t) => t.waitingOn === waitingOn || t.faults.length > 0).flatMap((t) => [`  - ${file}:${t.line}: [^${t.name}]`, ...t.faults.map((fault) => `    ${fault}`)]);
+/** Code threads waiting on `waitingOn`, plus any with a syntax fault — a fault refuses both ways. */
+const codeThreadLines = (waitingOn) => codeThreads().filter((t) => t.waitingOn === waitingOn || t.faults.length > 0).flatMap((t) => [`  - ${t.path}:${t.line}: ${t.first}`, ...t.faults.map((fault) => `    ${fault}`)]);
+const countOf = (lines) => lines.filter((line) => line.startsWith("  - ")).length;
+/** Whether a thread waits on `waitingOn`: one in footnote file `file`, or any code thread in the process's changed files. */
+const hasThreadFor = (waitingOn, file) => file !== void 0 && threads(read(file) ?? "").some((t) => t.waitingOn === waitingOn) || codeThreads().some((t) => t.waitingOn === waitingOn);
+/** Refuse any landing while a thread in `file` or a code thread in a changed file waits on the human (its last entry is the agent's), or has a syntax fault. */
+const requireThreadsClosed = (file) => {
+	const open = [...threadLines(file, "human"), ...codeThreadLines("human")];
+	if (open.length === 0) return;
+	refuse(`gtd land: open-threads: ${countOf(open)} thread(s) in ${file} or code comments wait on you — reply with a conclusion, or delete the thread:\n${open.join("\n")}`);
+};
+/** Refuse an agent turn that leaves a thread in `file`, or a code thread in a changed file, waiting on the agent (its last entry is `H:`) or with a syntax fault. */
+const requireReplies = (file) => {
+	const open = [...threadLines(file, "agent"), ...codeThreadLines("agent")];
+	if (open.length === 0) return;
+	refuse(`gtd land: unanswered-threads: ${countOf(open)} thread(s) in ${file} or code comments still wait on the agent — append one "- A:" reply to each (one "A:" comment line, same token and indentation, directly below a code thread's last line), or fold a concluded thread and delete it:\n${open.join("\n")}`);
+};
+/** Refuse a turn that did not undo the code edits `edited` recorded, back to their content before `base`. */
+const requireRevert = (edited, base) => {
+	const residue = edited.filter((c) => read(c.path) !== c.before).map((c) => c.path);
+	if (residue.length === 0) return;
+	const quoted = residue.map((path) => `'${path.replace(/'/g, "'\\''")}'`).join(" ");
+	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 = (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/config.ts
+const CONFIG_KEYS = [
+	"modes",
+	"ui",
+	"skills",
+	"access"
+];
+const MODE_KEYS = ["format", "validate"];
+const UI_KEYS = [
+	"port",
+	"host",
+	"cert",
+	"key",
+	"format"
+];
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isStringArray = (v) => Array.isArray(v) && v.every((entry) => typeof entry === "string");
+const unknownKeys = (value, known, path) => Object.keys(value).filter((key) => !known.includes(key)).map((key) => ({
+	path: [...path, key],
+	message: "is not a known key"
+}));
+const recordOf = (value, path, shape, entry) => isRecord(value) ? Object.entries(value).flatMap(([key, v]) => entry(v, [...path, key])) : [{
+	path,
+	message: `must be an object of ${shape}`
+}];
+const modeProblems = (value, path) => {
+	if (path.at(-1) === "") return [{
+		path,
+		message: "is a mode without a name"
+	}];
+	if (!isRecord(value)) return [{
+		path,
+		message: "must be an object with \"format\" and/or \"validate\""
+	}];
+	return [...unknownKeys(value, MODE_KEYS, path), ...MODE_KEYS.flatMap((key) => {
+		const command = value[key];
+		return command === void 0 || typeof command === "string" && command.trim() !== "" ? [] : [{
+			path: [...path, key],
+			message: "must be a non-empty shell command"
+		}];
+	})];
+};
+const uiProblems = (value, path) => {
+	if (!isRecord(value)) return [{
+		path,
+		message: "must be an object"
+	}];
+	return [...unknownKeys(value, UI_KEYS, path), ...UI_KEYS.flatMap((key) => {
+		const v = value[key];
+		if (v === void 0) return [];
+		return (key === "port" ? Number.isInteger(v) : typeof v === "string") ? [] : [{
+			path: [...path, key],
+			message: key === "port" ? "must be an integer" : "must be a string"
+		}];
+	})];
+};
+const accessProblems = (value, path) => {
+	if (!isRecord(value)) return [{
+		path,
+		message: "must be an object of { read?, write? } glob arrays"
+	}];
+	return [...unknownKeys(value, ["read", "write"], path), ...["read", "write"].flatMap((side) => value[side] === void 0 || isStringArray(value[side]) ? [] : [{
+		path: [...path, side],
+		message: "must be an array of glob strings"
+	}])];
+};
+/** Every way `value` is not a `GtdConfig`; an unknown key is one, so a removed key fails loudly. */
+const configProblems = (value) => {
+	if (!isRecord(value)) return [{
+		path: [],
+		message: "must be an object"
+	}];
+	return [
+		...unknownKeys(value, CONFIG_KEYS, []),
+		...value.modes === void 0 ? [] : recordOf(value.modes, ["modes"], "modes", modeProblems),
+		...value.ui === void 0 ? [] : uiProblems(value.ui, ["ui"]),
+		...value.skills === void 0 ? [] : recordOf(value.skills, ["skills"], "skill-name arrays", (v, path) => isStringArray(v) ? [] : [{
+			path,
+			message: "must be an array of skill names"
+		}]),
+		...value.access === void 0 ? [] : recordOf(value.access, ["access"], "scope access", accessProblems)
+	];
+};
+const formatConfigProblem = ({ path, message }) => `${["config", ...path].join(".")}: ${message}`;
+/**
+* Type and check the `config` export. Not generic on purpose: a literal argument
+* then gets TypeScript's excess-property check at every depth, so an unknown key
+* is a type error — and it throws at runtime too.
+*/
+const defineConfig = (config) => {
+	const problems = configProblems(config);
+	if (problems.length > 0) throw new Error(problems.map(formatConfigProblem).join("; "));
+	return config;
+};
+//#endregion
+//#region src/flows/index.ts
+var flows_exports = /* @__PURE__ */ __exportAll({
+	FLOWS_PROTOCOL: () => 1,
+	FlowsProtocolError: () => FlowsProtocolError,
+	accessFor: () => accessFor,
+	agent: () => agent,
+	answered: () => answered,
+	changes: () => changes,
+	changesSince: () => changesSince,
+	check: () => check,
+	checkScript: () => checkScript,
+	codeChanges: () => codeChanges,
+	codeThreads: () => codeThreads,
+	configProblems: () => configProblems,
+	configure: () => configure,
+	defineConfig: () => defineConfig,
+	defineWorkflow: () => defineWorkflow,
+	env: () => env,
+	glob: () => glob,
+	hasThreadFor: () => hasThreadFor,
+	head: () => head,
+	human: () => human,
+	installContext: () => installContext,
+	isFactoryWorkflow: () => isFactoryWorkflow,
+	judge: () => judge,
+	moveScript: () => moveScript,
+	numeric: () => numeric,
+	openQuestions: () => openQuestions,
+	protocolMismatch: () => protocolMismatch,
+	quote: () => quote,
+	read: () => read,
+	refuse: () => refuse,
+	removeScript: () => removeScript,
+	requireAnswers: () => requireAnswers,
+	requireProgress: () => requireProgress,
+	requireReplies: () => requireReplies,
+	requireRevert: () => requireRevert,
+	requireThreadsClosed: () => requireThreadsClosed,
+	restart: () => restart,
+	restoreScript: () => restoreScript,
+	revertScript: () => revertScript,
+	run: () => run,
+	scope: () => scope,
+	sectionBodies: () => sectionBodies,
+	sections: () => sections,
+	skillsFor: () => skillsFor,
+	start: () => start,
+	threads: () => threads,
+	vars: () => vars,
+	wrote: () => wrote
+});
+//#endregion
+export { FLOWS_PROTOCOL, FlowsProtocolError, accessFor, agent, answered, changes, changesSince, check, checkScript, codeChanges, codeThreads, configProblems, configure, defineConfig, defineWorkflow, env, glob, hasThreadFor, head, human, installContext, isFactoryWorkflow, judge, moveScript, numeric, openQuestions, protocolMismatch, quote, read, refuse, removeScript, requireAnswers, requireProgress, requireReplies, requireRevert, requireThreadsClosed, restart, restoreScript, revertScript, run, scope, sectionBodies, sections, skillsFor, start, flows_exports as t, threads, vars, wrote };