@pmelab/gtd 24.0.0 → 24.1.0

package/dist/chunks/wire-DA7q2ikx.mjs

@@ -0,0 +1,473 @@
+import { createHash, randomUUID } from "node:crypto";
+//#region src/wire/constants.ts
+/**
+* The top-level `schema` of every JSON document a driver reads. Bumped only
+* when a field is removed or renamed — never for an added one — and never tied
+* to the package version, since a driver can be installed apart from gtd.
+*/
+const WIRE_SCHEMA = 1;
+/** The bucket a cost with no `--model` tag is grouped under, kept distinct so a mixed history still totals correctly. */
+const UNATTRIBUTED_MODEL = "unspecified";
+/** The plain-text twin of `OutcomeScript.ts`'s `printfLine`. Lives here so `src/wire/`'s encoders reach it without importing out of the leaf. */
+const renderFormat = (fmt, ...args) => {
+	let i = 0;
+	return fmt.replace(/%s/g, () => args[i++] ?? "");
+};
+/** The first line of the landing refusal for a turn that wrote outside its `write` access — a stable marker drivers and tests grep for. */
+const ACCESS_REFUSAL = "gtd land: this turn wrote outside its write access — revert these paths, then run `gtd land` again:";
+//#endregion
+//#region src/wire/ExitCodes.ts
+const EXIT_OK = 0;
+/** Something failed that was never a matter of how gtd was invoked — a refusal or an unexpected error. */
+const EXIT_RUNTIME_ERROR = 1;
+/** gtd was invoked wrong — an unknown option/command, bad arity, a scope violation, a decode failure. */
+const EXIT_USAGE_ERROR = 2;
+const EXIT_SIGINT = 130;
+const EXIT_SIGTERM = 143;
+/** Frozen: adding a code is a driver-protocol break, the same as removing a wire field. */
+const EXIT_CODES = /* @__PURE__ */ new Set([
+	0,
+	1,
+	2,
+	130,
+	143
+]);
+//#endregion
+//#region src/wire/Demand.ts
+/**
+* `BeatKind`'s own member list, as a value — the ONE place the five kinds are
+* enumerated. Every test that needs to loop "every kind" (the JSON document,
+* `DEMAND_BRIEFING`, the plain header) imports this instead of re-typing its
+* own `as const satisfies readonly BeatKind[]` literal, so the type and the
+* loop can never drift apart.
+*/
+const BEAT_KINDS = [
+	"capture",
+	"message",
+	"script",
+	"prompt",
+	"stalled"
+];
+/**
+* The beat kind for a rest, in precedence order:
+*
+* 1. `stalled` — `Edge.ts`'s `stalledAt` verdict, passed in as a plain
+*    boolean (this module never resolves it itself). `stalledAt` already
+*    requires a clean tree, so this can never collide with `capture` below.
+* 2. `capture` — a `message` rest with a DIRTY tree: the human already
+*    acted; a driver lands it immediately.
+* 3. Otherwise, the content kind verbatim (`script`/`prompt`, or `message`
+*    on a clean tree).
+*/
+const beatKindOf = (input) => {
+	if (input.stalled) return "stalled";
+	if (input.contentKind === "message" && input.dirty) return "capture";
+	return input.contentKind;
+};
+/**
+* The `stalled` beat's own content: a diagnosis naming the stuck step and
+* the ways out. The first line is shaped so a stderr grep for
+* `stalled at "<state>"` stays a stable substring (see
+* `tests/integration/features/driver-doc.feature`).
+*/
+const stallDiagnosis = (state, actor) => `stalled at "${state}": the last gtd(${actor}): ${state} turn landed an empty attempt, the tree is clean, and another dispatch would repeat it.\n\nTwo ways out:\n  - sharpen the step's prompt so the turn has something concrete to author\n  - pass allowEmpty: true to the step, so an empty turn completes it and the\n    flow decides what follows — finishing, or an escalation step after N\n    empty turns\n`;
+/**
+* Assemble one `Demand` — the ONLY place a rest's resolved content becomes
+* `Demand.content` (`stallDiagnosis` at `kind === "stalled"`, the rendered
+* content otherwise), and the only place `session`/`validate`/`skills`/`access` are
+* attached, which the `prompt` variant's own type makes impossible to do at
+* any other kind.
+*/
+const demandOf = (input) => {
+	const { rendered, kind, session, validate } = input;
+	const content = kind === "stalled" ? stallDiagnosis(rendered.state, rendered.actor) : rendered.content;
+	const skills = rendered.skills !== void 0 && rendered.skills.length > 0 ? rendered.skills : void 0;
+	const access = rendered.access ?? {
+		read: null,
+		write: null
+	};
+	return kind === "prompt" ? {
+		kind,
+		content,
+		session,
+		validate,
+		skills,
+		access
+	} : {
+		kind,
+		content
+	};
+};
+//#endregion
+//#region src/wire/BeatStatus.ts
+/**
+* Assemble one `BeatStatus`. `system` is omitted (not just falsy) when its
+* rendered value is the empty string, unlike `model`: an empty
+* `--system-prompt ""` would silently delete the harness's own default
+* instead of failing loudly.
+*/
+const statusOf = (input) => {
+	const { rendered, idle, initial, workflow, log, changes, next, cost, costByModel } = input;
+	return {
+		idle,
+		initial,
+		model: rendered.model,
+		system: rendered.system !== void 0 && rendered.system !== "" ? rendered.system : void 0,
+		log,
+		state: rendered.state,
+		actor: rendered.actor,
+		workflow,
+		label: rendered.label,
+		memory: rendered.memory,
+		file: rendered.file,
+		mode: rendered.mode,
+		changes,
+		next,
+		cost,
+		costByModel,
+		judge: rendered.judge
+	};
+};
+//#endregion
+//#region src/wire/BeatDocument.ts
+/** `gtd next --json`'s `next` key — `null` when landing would commit nothing. */
+const nextField = (next) => next === null ? null : { target: next.target };
+/** Unreachable in a well-typed call — used as the `default` arm of an exhaustive switch over `Demand["kind"]`, so a future `BeatKind` member that isn't handled fails `tsc`, not just review. */
+const assertNeverDemand = (demand) => {
+	throw new Error(`unreachable demand: ${JSON.stringify(demand)}`);
+};
+/**
+* The ONE exhaustive switch translating a `Demand` into its wire
+* `session`/`validate`/`skills`/`access` set — only the `prompt` variant carries
+* any of them, and every other member is listed explicitly (not a
+* `default:` fallthrough) so adding a sixth `BeatKind` without adding its
+* case here fails `tsc` at the `assertNeverDemand` call, not silently
+* falling through to "no session."
+*/
+const dispatchFieldsOf = (demand) => {
+	switch (demand.kind) {
+		case "prompt": return {
+			session: demand.session,
+			validate: demand.validate,
+			skills: demand.skills,
+			access: demand.access
+		};
+		case "capture":
+		case "message":
+		case "script":
+		case "stalled": return {
+			session: void 0,
+			validate: void 0,
+			skills: void 0,
+			access: void 0
+		};
+		default: return assertNeverDemand(demand);
+	}
+};
+/**
+* Flatten a `Demand` plus its `BeatStatus` into the single 24-key document
+* `gtd next --json` emits — the ONLY place the two are joined. `cost`/
+* `costByModel` are omitted together, exactly when no cost was recorded
+* (`cost <= 0`).
+*/
+const beatDocument = (demand, status) => {
+	const { session, validate, skills, access } = dispatchFieldsOf(demand);
+	const hasCost = status.cost > 0;
+	return {
+		schema: 1,
+		kind: demand.kind,
+		content: demand.content,
+		idle: status.idle,
+		initial: status.initial,
+		session,
+		model: status.model,
+		system: status.system,
+		validate,
+		log: status.log,
+		state: status.state,
+		actor: status.actor,
+		workflow: status.workflow,
+		label: status.label,
+		memory: status.memory,
+		file: status.file,
+		mode: status.mode,
+		changes: status.changes,
+		next: nextField(status.next),
+		cost: hasCost ? status.cost : void 0,
+		costByModel: hasCost ? status.costByModel : void 0,
+		judge: status.judge,
+		skills,
+		access
+	};
+};
+const renderBeatJson = (document) => JSON.stringify(document) + "\n";
+//#endregion
+//#region src/wire/BeatPlain.ts
+/**
+* True when the per-model breakdown adds information beyond the `Cost:`
+* total: more than one model, or a single model that carries an actual
+* `--model` tag (a lone `unspecified` bucket just restates the total, so
+* it's suppressed).
+*/
+const breakdownIsInformative = (byModel) => byModel.length > 1 || byModel.length === 1 && byModel[0].model !== "unspecified";
+const costStatusLines = (cost, byModel) => {
+	if (cost <= 0) return [];
+	const lines = [`Cost: ${cost}`];
+	if (breakdownIsInformative(byModel)) for (const m of byModel) lines.push(`  ${m.model}: ${m.cost}`);
+	return lines;
+};
+const pendingStatusLines = (statusChanges) => statusChanges.length === 0 ? ["Pending: (clean)"] : ["Pending:", ...statusChanges.map((c) => `  ${c.status} ${c.path}`)];
+const nextStatusLine = (next) => next === null ? "Next: (nothing would land)" : `Next: → ${next.target}`;
+/** Builds `{[key]: value}` for each entry whose value isn't `undefined` — the shared "omit absent optional fields" shape the header uses. */
+const definedFields = (entries) => {
+	const result = {};
+	for (const [key, value] of entries) if (value !== void 0) result[key] = value;
+	return result;
+};
+/**
+* The header block's own lines — `State:`/`Awaits:`/`Workflow:`/optional `Label:`/
+* `Model:`/`Memory:`/`File:`/`Mode:`/`Cost:`(+breakdown)/`Pending:`/`Next:`,
+* in that order. Used by `renderBeatPlain`'s header-showing kinds below.
+*/
+const beatHeaderLines = (document) => {
+	const optional = definedFields([
+		["Label", document.label],
+		["Model", document.model],
+		["Memory", document.memory],
+		["File", document.file],
+		["Mode", document.mode]
+	]);
+	return [
+		`State: ${document.state}`,
+		`Awaits: ${document.actor}`,
+		`Workflow: ${document.workflow}`,
+		...Object.entries(optional).map(([key, value]) => `${key}: ${value}`),
+		...costStatusLines(document.cost ?? 0, document.costByModel ?? []),
+		...pendingStatusLines(document.changes),
+		nextStatusLine(document.next)
+	];
+};
+/**
+* One entry per `BeatKind`, typed as `Record<BeatKind, DemandBriefing>` so
+* the object literal itself is exhaustive: adding or removing a `BeatKind`
+* member without updating this map fails `tsc`, the same guarantee
+* `dispatchFieldsOf`'s switch (`BeatDocument.ts`) gives the JSON side. Exported
+* so the one cross-cutting exhaustiveness test (`BeatDocument.test.ts`) can
+* assert against it directly, rather than re-deriving it from
+* `renderBeatPlain`'s output. Replaces the old `renderBeatPlain`'s hand-written
+* `if (kind === "script") … if (kind === "capture") …` pair.
+*/
+const DEMAND_BRIEFING = {
+	capture: {
+		instructionLine: "The edit is already made — run `gtd land` to land it.",
+		suppressHeader: false
+	},
+	message: {
+		instructionLine: void 0,
+		suppressHeader: false
+	},
+	script: {
+		instructionLine: "Run this script:",
+		suppressHeader: false
+	},
+	stalled: {
+		instructionLine: void 0,
+		suppressHeader: false
+	},
+	prompt: {
+		instructionLine: void 0,
+		suppressHeader: true
+	}
+};
+/**
+* The self-validation instruction appended to a `prompt` beat's plain output
+* only — a structured (`--json`) driver runs the `validate` field
+* itself instead. Advisory either way: `gtd land` refuses a turn whose
+* steering file is invalid regardless of whether this was followed.
+*/
+const selfValidateInstruction = (command, file) => `\nBefore finishing your turn, run \`${command}\` — it checks ${file} — and fix every violation it reports until it exits cleanly. Do not finish while it still reports violations.\n`;
+/**
+* `gtd next`'s plain-text encoding, driven by `DEMAND_BRIEFING`. At
+* `kind === "prompt"` the status header is suppressed and only `content`
+* plus the self-validation instruction is emitted — those bytes ARE the
+* agent's input, so gtd's own bookkeeping (state name, edges, pending
+* changes) must not be prefixed onto it. Every other kind gets the header
+* plus its instruction line, since its plain output is read by a human or
+* driver, never an agent. `selfValidateCommand` is already resolved; this
+* function never resolves it itself.
+*/
+const renderBeatPlain = (document, selfValidateCommand) => {
+	const content = document.content.endsWith("\n") ? document.content : document.content + "\n";
+	const briefing = DEMAND_BRIEFING[document.kind];
+	if (briefing.suppressHeader) return selfValidateCommand !== void 0 && document.file !== void 0 ? content + selfValidateInstruction(selfValidateCommand, document.file) : content;
+	const body = beatHeaderLines(document).join("\n") + "\n\n" + content;
+	return briefing.instructionLine !== void 0 ? `${briefing.instructionLine}\n` + body : body;
+};
+//#endregion
+//#region src/wire/Land.ts
+/** Assembles one `gtd land` result's fields in `LandFields`' declared order — the ONLY place `gtd land --json`'s wire shape is built. */
+const landFields = (input) => ({
+	schema: 1,
+	script: input.script,
+	settled: input.settled,
+	idle: input.idle,
+	state: input.state,
+	subject: input.subject,
+	cost: input.cost,
+	model: input.model
+});
+const renderLandJson = (fields) => JSON.stringify(fields) + "\n";
+const FMT_NOOP = "nothing to do at \"%s\"\n";
+const FMT_LAND_PROSE = "commit everything with this message: %s\n";
+/** `nothing to do at "<state>"` — a no-op step's plain-text line, and the text a print-only script's own `printf` carries. */
+const noopText = (state) => renderFormat(FMT_NOOP, state);
+/** `commit everything with this message: <subject>` — plain `gtd land`'s own stdout at a pending diff (no script); `--json` keeps emitting the script itself, unaffected. */
+const landProseText = (subject) => renderFormat(FMT_LAND_PROSE, subject);
+/**
+* `gtd land`'s plain-text encoding — names the commit subject at a real
+* landing and points at `--json=script`, since the script itself is
+* unreachable from plain output; prints the existing no-op note otherwise.
+* `command` names the invocation to point at — `"land"` by default, but
+* `gtd judge answer` (the only other caller of `planLanding`/`landFields`)
+* passes its own two-word name so the hint stays runnable verbatim.
+*/
+const renderLandPlain = (fields, command = "land") => fields.subject !== null ? `${landProseText(fields.subject).trimEnd()}\n(run \`gtd ${command} --json=script | sh\` to get the landing script)\n` : noopText(fields.state);
+//#endregion
+//#region src/wire/Judge.ts
+const judgeJson = (state, questions) => JSON.stringify({
+	schema: 1,
+	state,
+	questions
+});
+//#endregion
+//#region src/wire/Select.ts
+/**
+* Renders a fully-walked leaf value: scalars/booleans stringify directly,
+* arrays become one `JSON.stringify` per entry, newline-joined.
+* `selectPath`'s loop already returns `absent` for `undefined`/`null` after
+* every segment (including the last), so neither ever reaches here.
+*/
+const toSelection = (value) => {
+	if (Array.isArray(value)) return {
+		kind: "value",
+		text: value.map((entry) => JSON.stringify(entry)).join("\n")
+	};
+	if (typeof value === "object") return {
+		kind: "value",
+		text: JSON.stringify(value)
+	};
+	return {
+		kind: "value",
+		text: String(value)
+	};
+};
+/** A segment that resolves to no key at all (missing from an object, out-of-range or non-numeric against an array) — distinct from a present key holding `undefined`. */
+const NOT_FOUND = Symbol("not-found");
+/** An all-digits segment (`"0"`, `"12"`) — the only shape an array segment resolves against. */
+const ARRAY_INDEX = /^\d+$/;
+/**
+* One step of the walk: looks `segment` up on `current`, or reports
+* `NOT_FOUND` for a key that was never there (a primitive has no keys).
+* Against an array, only an all-digits segment resolves — an in-range index
+* (`skills.0` reads the first declared skill), never a non-index own key
+* (`length`/`map`/every other inherited array member stays `NOT_FOUND`).
+* Against an object, presence is an OWN-property test
+* (`Object.prototype.hasOwnProperty`), never the `in` operator — `in` walks
+* the prototype chain, so it would resolve inherited members
+* (`constructor`, `toString`, `hasOwnProperty`, `valueOf`, ...) as real
+* document fields.
+*/
+const resolveSegment = (current, segment) => {
+	if (Array.isArray(current)) return ARRAY_INDEX.test(segment) && Number(segment) < current.length ? current[Number(segment)] : NOT_FOUND;
+	if (typeof current === "object" && current !== null) {
+		const record = current;
+		return Object.prototype.hasOwnProperty.call(record, segment) ? record[segment] : NOT_FOUND;
+	}
+	return NOT_FOUND;
+};
+/**
+* Walks `fields` by dotted key path. Never throws — any unwalkable shape
+* (a primitive mid-path, an out-of-range or non-numeric array segment)
+* degrades to `unknown`, and a present-but-`undefined` value anywhere along
+* the path short-circuits the whole remaining path to `absent` rather than
+* reporting a key that was never actually missing.
+*/
+const selectPath = (fields, path) => {
+	try {
+		let current = fields;
+		for (const segment of path.split(".")) {
+			current = resolveSegment(current, segment);
+			if (current === NOT_FOUND) return {
+				kind: "unknown",
+				path
+			};
+			if (current === void 0 || current === null) return { kind: "absent" };
+		}
+		return toSelection(current);
+	} catch {
+		return {
+			kind: "unknown",
+			path
+		};
+	}
+};
+//#endregion
+//#region src/wire/Sessions.ts
+/** Fixed forever — every derived session id descends from this one constant. */
+const GTD_SESSION_NAMESPACE = "ca4be249-805e-41c1-8b6a-75a11c011e25";
+const toBytes = (uuid) => Buffer.from(uuid.replace(/-/g, ""), "hex");
+const toUuidString = (bytes) => {
+	const hex = bytes.toString("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+};
+/**
+* UUIDv5 (RFC 4122 §4.3), hand-rolled over `node:crypto`'s SHA-1 rather than
+* a dependency — correctness is checked against the RFC's own DNS-namespace
+* test vector in `Sessions.test.ts`.
+*/
+const uuidv5 = (namespace, name) => {
+	const bytes = createHash("sha1").update(toBytes(namespace)).update(name, "utf8").digest().subarray(0, 16);
+	bytes[6] = bytes[6] & 15 | 80;
+	bytes[8] = bytes[8] & 63 | 128;
+	return toUuidString(bytes);
+};
+/**
+* Resolves a `prompt` rest's session id: with no `memoryKey` there's no
+* history to derive a stable id from, so it mints an ephemeral one and forces
+* `resume: false`; otherwise the id is deterministic (`uuidv5`) and `resume`
+* is passed through as given.
+*/
+const resolveSession = (memoryKey, resume, mint = randomUUID) => memoryKey === void 0 ? {
+	sessionId: mint(),
+	resume: false
+} : {
+	sessionId: uuidv5(GTD_SESSION_NAMESPACE, memoryKey),
+	resume
+};
+//#endregion
+//#region src/wire/Glob.ts
+const ESCAPE_RE = /[.+^${}()|[\]\\?]/g;
+const compile = (glob) => {
+	let pattern = "^";
+	let i = 0;
+	while (i < glob.length) {
+		const char = glob[i];
+		if (char !== "*") {
+			pattern += char.replace(ESCAPE_RE, "\\$&");
+			i += 1;
+		} else if (glob[i + 1] !== "*") {
+			pattern += "[^/]*";
+			i += 1;
+		} else if (glob[i + 2] === "/") {
+			pattern += "(?:.*/)?";
+			i += 3;
+		} else {
+			pattern += ".*";
+			i += 2;
+		}
+	}
+	return new RegExp(`${pattern}$`);
+};
+const globMatches = (path, glob) => compile(glob).test(path);
+//#endregion
+export { EXIT_SIGTERM as C, WIRE_SCHEMA as D, UNATTRIBUTED_MODEL as E, renderFormat as O, EXIT_SIGINT as S, ACCESS_REFUSAL as T, demandOf as _, landFields as a, EXIT_OK as b, renderLandJson as c, renderBeatPlain as d, beatDocument as f, beatKindOf as g, BEAT_KINDS as h, judgeJson as i, renderLandPlain as l, statusOf as m, resolveSession as n, landProseText as o, renderBeatJson as p, selectPath as r, noopText as s, globMatches as t, DEMAND_BRIEFING as u, stallDiagnosis as v, EXIT_USAGE_ERROR as w, EXIT_RUNTIME_ERROR as x, EXIT_CODES as y };