@junghanacs/entwurf 0.22.0 → 0.23.1

package/scripts/herdr-plugin-activate.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * herdr-plugin-activate — the forward half of a Herdr-plugin activation (#116 M3-b2).
+ *
+ * WHAT IT TAKES, AND WHY THAT IS ALL. Exactly a subset of `{pi, claude-code}`, and nothing else: no
+ * path, no command, no backend name this lane has not agreed to support. The stable runtime address
+ * is DERIVED here from XDG and handed down; the Pi and Claude writers accept a named root only when
+ * it is that same derived one. A verb that took a directory would be a way to point every pi session
+ * and every Claude MCP call at an executable of the caller's choosing.
+ *
+ * WHICH BACKENDS is M3-b3's question. This verb does not read Herdr's integration status; it is
+ * handed the answer. That keeps `H ∩ P` in one place — the profile leaf — instead of two.
+ *
+ * ADD-ONLY. A reinstall reconciles what is already active and adds what is newly requested. A
+ * backend absent from THIS request is retained, because a harness leaving Herdr's integration list
+ * is not a request to tear down wiring the operator still uses. Removal is the explicit verb.
+ *
+ * THE LEDGER IS WRITTEN BEFORE THE MUTATION, NOT AFTER. Each selected component is recorded
+ * `pending` before anything is touched and checkpointed `active` the moment its writer returns, so a
+ * run that dies halfway leaves a record of exactly how far it got. A transaction that only writes
+ * its result at the end is not retryable — it is re-runnable until the first partial failure.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	ACTIVATABLE_BACKENDS,
+	ActivationError,
+	certifyArtifactForForward,
+	certifyPhaseForForward,
+	certifyRootsAgainstLedger,
+	componentStates,
+	ledgerBody,
+	planActivation,
+	readCertifiedLedger,
+	resolveActivationLayout,
+	resolveComponentRoots,
+	resolveEntwurfDataRoot,
+	writeLedger,
+} from "./herdr-activation.mjs";
+import {
+	artifactCompleteness,
+	readCertifiedJournal,
+	resolveRuntimeLayout,
+	verifyInstalledRuntime,
+} from "./herdr-runtime.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function run(command, args, env) {
+	return spawnSync(command, args, { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+/** The only input: a subset of P, parsed from argv and refused if it is anything else. */
+export function parseBackends(argv) {
+	const requested = [];
+	for (const arg of argv) {
+		if (!ACTIVATABLE_BACKENDS.includes(arg)) {
+			throw new ActivationError(
+				"activation-backend-outside-p",
+				`${JSON.stringify(arg)} — this verb takes a subset of ${JSON.stringify(ACTIVATABLE_BACKENDS)} and nothing else`,
+			);
+		}
+		if (!requested.includes(arg)) requested.push(arg);
+	}
+	if (requested.length === 0) {
+		throw new ActivationError("activation-backend-outside-p", "name at least one backend to activate");
+	}
+	return ACTIVATABLE_BACKENDS.filter((b) => requested.includes(b));
+}
+
+/** One line naming an artifact by its own anchor — the commit for a checkout, the spec for npm. */
+export function describeArtifact(identity) {
+	return identity.kind === "npm"
+		? `npm ${identity.name}@${identity.version}`
+		: `${identity.repository}@${identity.commit.slice(0, 12)} (${identity.packageName}@${identity.packageVersion})`;
+}
+
+export function activate(env, requested) {
+	const activation = resolveActivationLayout(env);
+	const runtime = resolveRuntimeLayout(env);
+	const roots = resolveComponentRoots(env);
+
+	// 1. the runtime must be certified ready AND actually be a runtime on disk.
+	const journal = readCertifiedJournal(runtime);
+	if (journal === null || journal.phase !== "runtime-ready") {
+		throw new ActivationError(
+			"activation-runtime-not-ready",
+			`${runtime.activeDir} has no certified runtime-ready journal behind it`,
+		);
+	}
+	// The EXACT name AND version the journal certifies, not merely "a usable tree of that name": a
+	// runtime the journal says is 0.21.0 while the disk holds something else is two different answers
+	// to the question the wiring is about to be pointed at.
+	try {
+		verifyInstalledRuntime(runtime.activeDir, artifactCompleteness(journal.artifactIdentity));
+	} catch (err) {
+		throw new ActivationError("activation-runtime-not-ready", `${err.code ?? "unknown"}: ${err.detail ?? err.message}`);
+	}
+	const current = journal.artifactIdentity;
+
+	// 2. the existing ledger, and the roots it was recorded against.
+	const ledger = readCertifiedLedger(activation);
+	certifyRootsAgainstLedger(ledger, roots, runtime.activeDir);
+	certifyPhaseForForward(ledger, requested);
+	// 2b. WHICH ARTIFACT this ledger is about. The root is stable and the bytes under it are not, so
+	// a reinstall can legally replace the artifact — but only from a settled ledger, with every
+	// component active and every activated backend still in the request. Everything up to the single
+	// checkpoint below is zero-write, so a refusal here leaves the previous ledger byte-identical.
+	const disposition = certifyArtifactForForward(ledger, current, requested);
+	const plan = planActivation({ ledger, requested });
+	const selected = [...plan.reconcile, ...plan.add];
+
+	// 3. preflight EVERY selected component before the first byte.
+	const preflights = [];
+	if (selected.includes("claude-code")) {
+		preflights.push([
+			"claude-code",
+			// The mode rides the ARGV, because that is what the state owner reads. The env var is the
+			// installer script's channel; passing only that preflights the DEFAULT mode and then
+			// installs the plugin one — a green check of work nobody is going to do.
+			run(
+				"python3",
+				[
+					path.join(PACKAGE_ROOT, "scripts", "meta-bridge-state.py"),
+					"preflight-install",
+					"--repo",
+					PACKAGE_ROOT,
+					"--plugin-runtime",
+					runtime.activeDir,
+				],
+				{ ...env, ENTWURF_PLUGIN_RUNTIME: runtime.activeDir },
+			),
+		]);
+	}
+	if (selected.includes("pi")) {
+		const agentSettings = path.join(roots.piAgentDir.path, "settings.json");
+		const dataRoot = resolveEntwurfDataRoot(env);
+		// BOTH halves. The user-scope citizen is a package registration and a provider key with
+		// SEPARATE ownership records, and a foreign or corrupt package state refuses independently —
+		// preflighting only the provider would let the first ledger write land on a host the package
+		// writer was always going to refuse.
+		preflights.push([
+			"pi-package",
+			run(
+				"python3",
+				[
+					path.join(PACKAGE_ROOT, "scripts", "register-pi-package.py"),
+					agentSettings,
+					PACKAGE_ROOT,
+					"--scope",
+					"user",
+					"--state",
+					path.join(dataRoot, "pi-package", "install-state.json"),
+					"--preflight",
+				],
+				env,
+			),
+		]);
+		preflights.push([
+			"pi-provider",
+			run(
+				"python3",
+				[
+					path.join(PACKAGE_ROOT, "scripts", "register-pi-provider.py"),
+					"install",
+					agentSettings,
+					PACKAGE_ROOT,
+					"--scope",
+					"user",
+					"--state",
+					path.join(
+						env.XDG_DATA_HOME ?? path.join(env.HOME, ".local", "share"),
+						"entwurf",
+						"pi-provider",
+						"install-state.json",
+					),
+					"--plugin-runtime",
+					runtime.activeDir,
+					"--preflight",
+				],
+				env,
+			),
+		]);
+	}
+	const refused = preflights.filter(([, r]) => r.status !== 0);
+	if (refused.length > 0) {
+		for (const [name, r] of refused) {
+			process.stderr.write(`  ${name}: ${(r.stderr || r.stdout || "").trim().split("\n").pop()}\n`);
+		}
+		throw new ActivationError(
+			"activation-preflight-refused",
+			`${refused.map(([n]) => n).join(", ")} — zero bytes changed`,
+		);
+	}
+
+	// 4. record the intention, THEN mutate, checkpointing each component as it lands.
+	//
+	// ON A REBIND this write is the whole checkpoint, and it is ONE `writeLedger`: the new artifact
+	// identity and the `activating` phase land together. A crash before it leaves the old ledger
+	// intact — old identity, phase `active`, nothing half-said. A crash after it leaves a ledger that
+	// already names the new artifact with its components `pending`, which the SAME verb resumes.
+	// Splitting the identity and the phase across two writes would open a window in which the ledger
+	// claims the new artifact while still saying the old transaction finished.
+	//
+	// Every selected component is `pending` in that case, including ones already active: they are
+	// being re-pointed at a different artifact, and a run that left them labelled `active` would be
+	// claiming work it has not redone.
+	const states = componentStates(ledger);
+	for (const backend of selected) {
+		if (disposition === "rebind" || states[backend] !== "active") states[backend] = "pending";
+	}
+	const checkpoint = (phase) =>
+		writeLedger(
+			activation,
+			ledgerBody({ phase, runtimeRoot: runtime.activeDir, artifactIdentity: current, roots, states }),
+		);
+	checkpoint("activating");
+
+	for (const backend of selected) {
+		const r =
+			backend === "pi"
+				? run(
+						"bash",
+						[path.join(PACKAGE_ROOT, "run.sh"), "install-user-scope", "--plugin-runtime", runtime.activeDir],
+						env,
+					)
+				: run("bash", [path.join(PACKAGE_ROOT, "scripts", "meta-bridge-install.sh")], {
+						...env,
+						ENTWURF_PLUGIN_RUNTIME: runtime.activeDir,
+					});
+		if (r.status !== 0) {
+			process.stderr.write(`${(r.stderr || r.stdout || "").trim()}\n`);
+			throw new ActivationError(
+				"activation-component-failed",
+				`${backend} — the ledger records how far this got and is the retry authority`,
+			);
+		}
+		states[backend] = "active";
+		checkpoint("activating");
+	}
+	checkpoint("active");
+
+	process.stdout.write(
+		`[herdr-plugin-activate] active: ${Object.keys(states).join(", ")} (runtime ${runtime.activeDir}, ` +
+			`artifact ${describeArtifact(current)}, ${disposition}, ` +
+			`pi=${roots.piAgentDir.source}, claude=${roots.claudeConfigDir.source}` +
+			`${plan.retained.length > 0 ? `, retained ${plan.retained.join(",")}` : ""})\n`,
+	);
+	return 0;
+}
+
+function sameFile(a, b) {
+	try {
+		return fs.realpathSync(a) === fs.realpathSync(b);
+	} catch {
+		return false;
+	}
+}
+
+if (process.argv[1] && sameFile(process.argv[1], fileURLToPath(import.meta.url))) {
+	try {
+		process.exit(activate(process.env, parseBackends(process.argv.slice(2))));
+	} catch (err) {
+		process.stderr.write(`[herdr-plugin-activate] ${err.code ?? "activation-failed"}: ${err.detail ?? err.message}\n`);
+		process.exit(1);
+	}
+}

package/scripts/herdr-plugin-deactivate.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * herdr-plugin-deactivate — the explicit teardown of a Herdr-plugin activation (#116 M3-b2).
+ *
+ * This is the verb Herdr will never call. `herdr plugin uninstall` removes its managed checkout and
+ * has no cleanup hook, so the harness wiring and the stable runtime are RETAINED, not cleaned — and
+ * the operator needs one command, shipped in the package rather than in the deleted checkout, that
+ * takes them back.
+ *
+ * EVERY IMPORT IS STATIC AND AT THE TOP. This process deletes the runtime it is executing from.
+ * Measured on Linux: already-loaded modules and open descriptors survive that, but a lazy `import()`
+ * afterwards fails with ERR_MODULE_NOT_FOUND — which would strand a host with its runtime gone, its
+ * ledger unretired, and nothing left to run the rest. So nothing here is loaded late, and the gate
+ * asserts there is no dynamic import to defer.
+ *
+ * PREFLIGHT EVERY AUTHORITY, THEN MUTATE. The ledger, the resolved roots, and BOTH component
+ * inverses are asked read-only first. Only when all of them are green does the first byte change.
+ * A component that then fails stops the run with the runtime and the ledger intact, because the
+ * ledger is the retry authority and a teardown that deletes its own record of what is left is one
+ * nobody can resume.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	certifyPhaseForInverse,
+	certifyRootsAgainstLedger,
+	componentStates,
+	ledgerBody,
+	piStatePaths,
+	planDeactivation,
+	readCertifiedLedger,
+	resolveActivationLayout,
+	resolveComponentRoots,
+	writeLedger,
+} from "./herdr-activation.mjs";
+import { removeOwnedRuntime, resolveRuntimeLayout } from "./herdr-runtime.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function run(command, args, env) {
+	return spawnSync(command, args, { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function fail(code, detail) {
+	process.stderr.write(`[herdr-plugin-deactivate] ${code}: ${detail}\n`);
+	process.exit(1);
+}
+
+export function deactivate(env) {
+	const activation = resolveActivationLayout(env);
+	const runtime = resolveRuntimeLayout(env);
+	const roots = resolveComponentRoots(env);
+
+	const ledger = readCertifiedLedger(activation);
+	if (ledger === null) {
+		process.stdout.write("[herdr-plugin-deactivate] no certified activation ledger — nothing to undo\n");
+		return 0;
+	}
+	certifyRootsAgainstLedger(ledger, roots, runtime.activeDir);
+	certifyPhaseForInverse(ledger);
+	// On a RETRY the plan is what is LEFT: a component already recorded `removed` is skipped, because
+	// its inverse has no ownership state to be admitted by any more and re-running it is a permanent
+	// refusal — which is exactly how a half-finished teardown used to become unfinishable.
+	const steps = planDeactivation(ledger);
+	const states = componentStates(ledger);
+	const piState = piStatePaths(env);
+
+	// ── PREFLIGHT: every remaining authority, zero writes ────────────────────
+	const preflights = [];
+	if (steps.includes("claude-code")) {
+		preflights.push([
+			"claude-code",
+			run(
+				"python3",
+				[path.join(PACKAGE_ROOT, "scripts", "meta-bridge-state.py"), "preflight-uninstall", "--repo", PACKAGE_ROOT],
+				env,
+			),
+		]);
+	}
+	if (steps.includes("pi")) {
+		const agentSettings = path.join(roots.piAgentDir.path, "settings.json");
+		preflights.push([
+			"pi-package",
+			run(
+				"python3",
+				[
+					path.join(PACKAGE_ROOT, "scripts", "register-pi-package.py"),
+					agentSettings,
+					PACKAGE_ROOT,
+					"--scope",
+					"user",
+					"--state",
+					piState.packageState,
+					"--remove",
+					"--preflight",
+				],
+				env,
+			),
+		]);
+		preflights.push([
+			"pi-provider",
+			run(
+				"python3",
+				[
+					path.join(PACKAGE_ROOT, "scripts", "register-pi-provider.py"),
+					"remove",
+					agentSettings,
+					PACKAGE_ROOT,
+					"--scope",
+					"user",
+					"--state",
+					piState.providerState,
+					"--preflight",
+				],
+				env,
+			),
+		]);
+	}
+	const refused = preflights.filter(([, r]) => r.status !== 0);
+	if (refused.length > 0) {
+		for (const [name, r] of refused) {
+			process.stderr.write(`  ${name}: ${(r.stderr || r.stdout || "").trim().split("\n").pop()}\n`);
+		}
+		fail("deactivate-preflight-refused", `${refused.map(([n]) => n).join(", ")} — zero bytes changed`);
+	}
+	process.stdout.write(
+		`[herdr-plugin-deactivate] preflight-all ok (${preflights.length === 0 ? "nothing left to undo" : preflights.map(([n]) => n).join(", ")})\n`,
+	);
+
+	// ── MUTATE: retry authority is written BEFORE each step, checkpointed after ──
+	// The identity is carried through the teardown unchanged, from the ledger's own record. A
+	// teardown does not re-decide which artifact it was: it removes what the ledger says was
+	// activated, so rewriting that field mid-inverse could only ever make the record less true.
+	const checkpoint = () =>
+		writeLedger(
+			activation,
+			ledgerBody({
+				phase: "deactivating",
+				runtimeRoot: runtime.activeDir,
+				artifactIdentity: ledger.artifactIdentity,
+				roots,
+				states,
+			}),
+		);
+	checkpoint();
+
+	const done = [];
+	for (const step of steps) {
+		if (step === "claude-code" || step === "pi") {
+			const verb = step === "pi" ? "remove-user-scope" : "uninstall-meta-bridge";
+			const r = run("bash", [path.join(PACKAGE_ROOT, "run.sh"), verb], env);
+			if (r.status !== 0) {
+				process.stderr.write(`${(r.stderr || r.stdout || "").trim()}\n`);
+				fail(
+					"deactivate-component-failed",
+					`${step} inverse failed — runtime and ledger preserved as retry authority (${done.length} component(s) already removed and recorded)`,
+				);
+			}
+			states[step] = "removed";
+			checkpoint();
+			done.push(step);
+		} else if (step === "runtime") {
+			// Past this line the code that wrote this file is gone from disk. Everything below is
+			// already loaded; nothing is imported.
+			removeOwnedRuntime({ env });
+			done.push(step);
+		} else if (step === "ledger") {
+			fs.rmSync(activation.ledgerPath, { force: true });
+			done.push(step);
+		}
+	}
+	process.stdout.write(`[herdr-plugin-deactivate] done: ${done.join(" -> ")}\n`);
+	return 0;
+}
+
+function sameFile(a, b) {
+	try {
+		return fs.realpathSync(a) === fs.realpathSync(b);
+	} catch {
+		return false;
+	}
+}
+
+if (process.argv[1] && sameFile(process.argv[1], fileURLToPath(import.meta.url))) {
+	try {
+		process.exit(deactivate(process.env));
+	} catch (err) {
+		fail(err.code ?? "deactivate-failed", err.detail ?? err.message);
+	}
+}