@animus-ui/cli 0.1.11

package/dist/index.mjs

@@ -0,0 +1,754 @@
+import { AnimusConfigError, assertKnownOptionKeys, buildPathAliasesJson, contentHash, createExcludeMatcher, readTsconfigAliasPairs, resolveMode, runStructuralSelfCheck } from "@animus-ui/extract/pipeline";
+import { parseArgs } from "node:util";
+import { CLI_COMMIT_ARTIFACT, CLI_LOCK_ARTIFACT, ExtractionSession, MANIFEST_ARTIFACT, SESSION_ASSETS_DIR, STYLES_ARTIFACT, SYSTEM_PROPS_ARTIFACT, collectSessionAssets, getAnalyzedHashes, getManifestJson, getSessionArtifactDir, getSharedCss, getSharedSystemProps, startTurbopackWatcher, verifyCommitRecord } from "@animus-ui/extract/session";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "fs";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+import { pathToFileURL } from "url";
+//#region src/writer.ts
+/**
+* Deterministic fixed-path artifact writer (design D3): raw payload bytes —
+* no session envelope, no per-invocation identity — staged into a private
+* subdirectory, VERIFIED there, then renamed into place with `commit.json`
+* LAST carrying content hashes of every payload (asset files included), so
+* a reader holding only the record and the payload bytes can verify set
+* completeness and consistency — and a publication that cannot verify
+* never replaces the previous generation. A single-writer advisory lock
+* fails loud instead of last-writer-wins; the lock never outlives the
+* invocation, so repeated identical builds are byte-identical trees.
+*/
+const STYLES_FILE = STYLES_ARTIFACT;
+const SYSTEM_PROPS_FILE = SYSTEM_PROPS_ARTIFACT;
+const MANIFEST_FILE = MANIFEST_ARTIFACT;
+const COMMIT_FILE = CLI_COMMIT_ARTIFACT;
+const LOCK_FILE = CLI_LOCK_ARTIFACT;
+const ASSETS_DIR = SESSION_ASSETS_DIR;
+/** Publication rejected by the pre-swap consistency check: the staged set
+*  did not verify, and the previous generation was left untouched. */
+var PublishInconsistencyError = class extends Error {
+	constructor(failures) {
+		super(`Staged publication failed its consistency check:\n  - ${failures.join("\n  - ")}`);
+		this.failures = failures;
+		this.name = "PublishInconsistencyError";
+	}
+};
+/** Take the single-writer advisory lock, failing loud on a live holder.
+*  Returns a release function. */
+function acquireLock(outDir) {
+	mkdirSync(outDir, { recursive: true });
+	const lockPath = join(outDir, LOCK_FILE);
+	try {
+		writeFileSync(lockPath, JSON.stringify({
+			pid: process.pid,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString()
+		}), { flag: "wx" });
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		let holder = {};
+		try {
+			holder = JSON.parse(readFileSync(lockPath, "utf-8"));
+		} catch {}
+		if (typeof holder.pid === "number" && isProcessAlive(holder.pid)) throw new AnimusConfigError(`Another animus process (pid ${holder.pid}, started ${holder.startedAt ?? "unknown"}) owns ${outDir} — wait for it or pass --out-dir to write elsewhere.`);
+		console.error(`[animus] Replacing stale lock left by dead pid ${holder.pid ?? "?"}`);
+		rmSync(lockPath, { force: true });
+		try {
+			writeFileSync(lockPath, JSON.stringify({
+				pid: process.pid,
+				startedAt: (/* @__PURE__ */ new Date()).toISOString()
+			}), { flag: "wx" });
+		} catch (retryError) {
+			if (retryError.code !== "EEXIST") throw retryError;
+			throw new AnimusConfigError(`Another animus process re-acquired ${outDir} while a stale lock was being replaced — wait for it or pass --out-dir.`);
+		}
+	}
+	return () => {
+		rmSync(lockPath, { force: true });
+	};
+}
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Asset names under `assets/` that outDir's current commit record
+*  published, or empty when no record is readable. */
+function publishedAssetNames(outDir) {
+	try {
+		const record = JSON.parse(readFileSync(join(outDir, COMMIT_FILE), "utf-8"));
+		return new Set(Object.keys(record.payloads ?? {}).filter((name) => name.startsWith(`${ASSETS_DIR}/`)).map((name) => name.slice(ASSETS_DIR.length + 1)));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+/**
+* Publish the payload set. The set is STAGED into a private subdirectory,
+* verified there (recompute-and-compare, the same check
+* `verifyPublishedSet` runs), and only a verified set is renamed into
+* place: payloads first, asset files next, the commit record LAST. A set
+* that cannot verify throws `PublishInconsistencyError` with the previous
+* generation untouched — "keeping last-good artifacts" must be literally
+* true for the watch loop's rejection path. The record carries only
+* content-derived data (asset entries sorted by name) so the full tree is
+* byte-identical across identical-input runs.
+*/
+function publishArtifacts(outDir, payloads) {
+	mkdirSync(outDir, { recursive: true });
+	const previouslyPublishedAssets = publishedAssetNames(outDir);
+	const staging = join(outDir, `.staging-${process.pid}`);
+	rmSync(staging, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(staging, { recursive: true });
+	try {
+		const namedPayloads = [
+			[STYLES_FILE, payloads.stylesCss],
+			[SYSTEM_PROPS_FILE, payloads.systemPropsJs],
+			[MANIFEST_FILE, payloads.manifestJson]
+		];
+		const record = {
+			schema: 1,
+			payloads: {}
+		};
+		for (const [name, text] of namedPayloads) {
+			writeFileSync(join(staging, name), text);
+			record.payloads[name] = { hash: contentHash(text) };
+		}
+		const assets = payloads.assets ?? [];
+		if (assets.length > 0) {
+			mkdirSync(join(staging, ASSETS_DIR), { recursive: true });
+			for (const { name, bytes } of assets) {
+				writeFileSync(join(staging, ASSETS_DIR, name), bytes);
+				record.payloads[`${ASSETS_DIR}/${name}`] = { hash: contentHash(bytes) };
+			}
+		}
+		writeFileSync(join(staging, COMMIT_FILE), JSON.stringify(record, null, 2) + "\n");
+		const failures = verifyPublishedSet(staging);
+		if (failures.length > 0) throw new PublishInconsistencyError(failures);
+		for (const [name] of namedPayloads) renameSync(join(staging, name), join(outDir, name));
+		const publishedAssetsDir = join(outDir, ASSETS_DIR);
+		if (assets.length > 0) {
+			mkdirSync(publishedAssetsDir, { recursive: true });
+			for (const { name } of assets) renameSync(join(staging, ASSETS_DIR, name), join(publishedAssetsDir, name));
+		}
+		const expectedNames = new Set(assets.map((asset) => asset.name));
+		for (const name of previouslyPublishedAssets) {
+			if (expectedNames.has(name)) continue;
+			try {
+				unlinkSync(join(publishedAssetsDir, name));
+			} catch {}
+		}
+		renameSync(join(staging, COMMIT_FILE), join(outDir, COMMIT_FILE));
+		return record;
+	} finally {
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** The documented consistency check — the session-shared implementation
+*  (published-set.ts): recompute every payload hash raw-bytes and compare
+*  against the commit record. Returns failure lines (empty = consistent). */
+function verifyPublishedSet(outDir) {
+	return verifyCommitRecord(outDir);
+}
+//#endregion
+//#region src/build.ts
+/**
+* `animus build` — one-shot extraction over the SAME drive loop every
+* driver uses (`ExtractionSession`; NS1/NS4: no second composition), then
+* export of the raw payloads to the fixed-path deterministic artifact
+* contract (design D3) via the CLI writer. The one-shot session tree is
+* removed after export — no session-dir accumulation per CI run.
+*
+* Failure policy (design D5): silent-empty success is impossible —
+* system-load failure, zero discovered files, and structural emptiness are
+* fatal in EVERY mode, independent of `strict`.
+*
+* The preflight, session construction, and shared-state publication steps
+* are exported helpers: `animus watch` (watch.ts) runs the same checks and
+* the same writer path per publication instead of forking them.
+*/
+/** Thrown for failures whose exit class is "extraction failure" (1). */
+var ExtractionFailure = class extends Error {};
+/** Thrown for failures whose exit class is "config/usage error" (2). */
+var UsageFailure = class extends Error {};
+/** Thrown for failures whose exit class is "engine/environment" (3). */
+var EnvironmentFailure = class extends Error {};
+/** The CLI's one stderr prefix convention (stdout stays machine-only) —
+*  shared with watch.ts. */
+const err = (...parts) => console.error("[animus]", ...parts);
+/** Preflight shared by build and watch: root and system-module existence
+*  are usage errors (exit 2) decided before any engine work; a missing
+*  platform binary is an environment failure (exit 3) surfaced with the
+*  loader's own remediation text. */
+async function runPreflight(config) {
+	const { root, options } = config;
+	if (!existsSync(root)) throw new UsageFailure(`Root directory not found: ${root}`);
+	const systemPath = resolve(root, options.system);
+	if (!existsSync(systemPath)) throw new UsageFailure(`System module not found: ${systemPath} (from \`system: ${options.system}\` against root ${root})`);
+	try {
+		await import("@animus-ui/extract");
+	} catch (error) {
+		throw new EnvironmentFailure(`Extraction engine failed to load: ${String(error)}`);
+	}
+}
+/** The one CLI session shape: self-ingestion guard applied (an outDir
+*  inside the root is force-excluded from discovery, loudly), driver label
+*  and root authority set, tsconfig `paths` harvested as the alias source
+*  (no live bundler config exists for this driver). */
+function createCliSession(config) {
+	const { root, outDir, options } = config;
+	const session = new ExtractionSession(options);
+	const relOut = relative(root, outDir);
+	if (!relOut.startsWith("..") && !config.excludePatterns.some((p) => relOut.includes(p) || p === relOut)) {
+		const anchored = `${relOut.split("\\").join("/")}/**`;
+		session.structuralExclude = [anchored];
+		err(`outDir ${relOut} is inside the root — auto-excluded from discovery (pattern '${anchored}')`);
+	}
+	session.driverLabel = "animus";
+	session.rootDir = root;
+	const builtAliases = buildPathAliasesJson(readTsconfigAliasPairs(root), root);
+	if (builtAliases) session.pathAliasesJson = builtAliases.json;
+	return session;
+}
+/**
+* Publish the session's shared-state payloads through the deterministic
+* CLI writer (design D3) — the SINGLE publication path for build and every
+* watch cycle. Zero analyzed files, an unreadable manifest, and structural
+* emptiness throw ExtractionFailure (silent-empty success is impossible);
+* a post-publish consistency failure throws EnvironmentFailure.
+*/
+function publishSharedPayloads(config, session) {
+	const { root, outDir, options } = config;
+	const fileCount = getAnalyzedHashes()?.size ?? 0;
+	if (fileCount === 0) throw new ExtractionFailure(`Discovery found zero source files under ${root} (exclusions: ${config.excludePatterns.join(", ")})`);
+	const manifestJson = getManifestJson() ?? "";
+	const stylesCss = getSharedCss();
+	const systemPropsJs = getSharedSystemProps();
+	let componentCount = session.lastComponentCount ?? -1;
+	if (componentCount < 0) try {
+		componentCount = Object.keys(JSON.parse(manifestJson).components ?? {}).length;
+	} catch {
+		throw new ExtractionFailure("Analysis published no readable manifest");
+	}
+	const failures = runStructuralSelfCheck({
+		componentCount,
+		variableCss: stylesCss,
+		globalCss: "",
+		componentCss: "",
+		assembledCss: stylesCss,
+		layers: options.layers,
+		externalOutcomes: session.lastExternalOutcomes
+	});
+	if (failures.length > 0) throw new ExtractionFailure(`Structural self-check failed:\n  - ${failures.join("\n  - ")}`);
+	const assets = collectSessionAssets(session.sessionDir);
+	try {
+		publishArtifacts(outDir, {
+			stylesCss,
+			systemPropsJs,
+			manifestJson,
+			assets
+		});
+	} catch (error) {
+		if (error instanceof PublishInconsistencyError) throw new EnvironmentFailure(error.message);
+		throw error;
+	}
+	return {
+		componentCount,
+		fileCount
+	};
+}
+/** Discovery-outcome report (stderr): per-specifier accounting plus
+*  dead-pattern visibility — a user exclusion that matched nothing is
+*  named instead of silently inert. */
+function reportDiscoveryOutcomes(config, session) {
+	for (const { specifier, outcome, fileCount: files } of session.lastExternalOutcomes) err(`include '${specifier}': ${outcome}${outcome === "resolved" ? ` (${files} files)` : ""}`);
+	const stats = session.getExcludeStats();
+	for (const pattern of config.options.exclude ?? []) if ((stats.get(pattern) ?? 0) === 0) err(`exclude pattern '${pattern}' matched nothing`);
+}
+async function runBuild(config) {
+	const { outDir } = config;
+	await runPreflight(config);
+	const release = acquireLock(outDir);
+	let session = null;
+	try {
+		session = createCliSession(config);
+		try {
+			await session.runFullPipeline();
+		} catch (error) {
+			throw new ExtractionFailure(String(error));
+		}
+		const { componentCount, fileCount } = publishSharedPayloads(config, session);
+		reportDiscoveryOutcomes(config, session);
+		err(`build complete: ${componentCount} components from ${fileCount} files → ${outDir}`);
+		return {
+			outDir,
+			componentCount,
+			fileCount
+		};
+	} finally {
+		release();
+		const dir = session?.sessionDir ?? getSessionArtifactDir();
+		if (dir) rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/config.ts
+/**
+* CLI config resolution — the third driver over the shared option core
+* (shared-driver-config): documented precedence flags > config file >
+* defaults, one root authority, explicit emission mode (the CLI never
+* sniffs NODE_ENV), and a fully inspectable resolved projection for
+* `--print-config`.
+*/
+/** Config filenames probed in order under the config-search root. */
+const CONFIG_FILENAMES = [
+	"animus.config.json",
+	"animus.config.mjs",
+	"animus.config.js",
+	"animus.config.ts"
+];
+async function loadConfigFile(path) {
+	if (path.endsWith(".json")) try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch (error) {
+		throw new AnimusConfigError(`Failed to parse ${path}: ${String(error)}`);
+	}
+	try {
+		const mod = await import(pathToFileURL(path).href);
+		const value = mod.default ?? mod;
+		if (typeof value !== "object" || value === null) throw new AnimusConfigError(`${path} must default-export a config object`);
+		return value;
+	} catch (error) {
+		if (error instanceof AnimusConfigError) throw error;
+		const code = error.code;
+		if (path.endsWith(".ts") && code === "ERR_UNKNOWN_FILE_EXTENSION") throw new AnimusConfigError(`${path}: this Node runtime cannot evaluate TypeScript config files (native type stripping requires Node >= 23.6 unflagged; the supported floor for .ts configs). Use animus.config.mjs or animus.config.json instead.`);
+		throw new AnimusConfigError(`Failed to load config ${path}: ${String(error)}`);
+	}
+}
+/**
+* Resolve the effective CLI configuration. Precedence: flags > config file
+* > documented defaults. Scalar flags override; `--exclude` values merge
+* (exclusion semantics are merge-only by contract).
+*/
+async function resolveCliConfig(flags, cwd) {
+	const flagRoot = flags.root ? resolve(cwd, flags.root) : null;
+	let configFile = null;
+	if (flags.config) {
+		configFile = resolve(cwd, flags.config);
+		if (!existsSync(configFile)) throw new AnimusConfigError(`Config file not found: ${configFile}`);
+	} else for (const name of CONFIG_FILENAMES) {
+		const candidate = resolve(flagRoot ?? cwd, name);
+		if (existsSync(candidate)) {
+			configFile = candidate;
+			break;
+		}
+	}
+	const raw = configFile ? await loadConfigFile(configFile) : {};
+	assertKnownOptionKeys(raw);
+	const fileRoot = raw["root"];
+	const configDir = configFile ? dirname(configFile) : cwd;
+	const effectiveRoot = flagRoot ?? (typeof fileRoot === "string" ? resolve(configDir, fileRoot) : configFile ? configDir : cwd);
+	const provenance = {};
+	const pick = (key, flagValue) => {
+		if (flagValue !== void 0) {
+			provenance[key] = "explicit";
+			return flagValue;
+		}
+		const fileValue = raw[key];
+		if (fileValue !== void 0) {
+			provenance[key] = "explicit";
+			return fileValue;
+		}
+		provenance[key] = "default";
+	};
+	const system = pick("system", flags.system);
+	if (typeof system !== "string" || system.length === 0) throw new AnimusConfigError("Missing required option `system` — pass --system ./src/ds.ts or set \"system\" in animus.config.");
+	const exclude = [...Array.isArray(raw["exclude"]) ? raw["exclude"] : [], ...flags.exclude ?? []];
+	if (exclude.length > 0) provenance["exclude"] = "explicit";
+	else provenance["exclude"] = "default";
+	if (flags.mode !== void 0 && flags.mode !== "development" && flags.mode !== "production") throw new AnimusConfigError(`Invalid --mode "${flags.mode}" — expected "development" or "production".`);
+	const resolvedMode = resolveMode(flags.mode ?? raw["mode"], () => "production");
+	provenance["mode"] = resolvedMode.provenance;
+	const cliNamespace = raw["cli"] ?? {};
+	if (cliNamespace.outDir !== void 0 && typeof cliNamespace.outDir !== "string") throw new AnimusConfigError(`Invalid value for "cli.outDir" — expected a string path, got ${JSON.stringify(cliNamespace.outDir)}.`);
+	const outDirSetting = flags.outDir ?? cliNamespace.outDir ?? ".animus";
+	const outDir = isAbsolute(outDirSetting) ? outDirSetting : resolve(effectiveRoot, outDirSetting);
+	provenance["outDir"] = flags.outDir !== void 0 || cliNamespace.outDir !== void 0 ? "explicit" : "driver-default";
+	const options = {
+		system,
+		exclude: exclude.length > 0 ? exclude : void 0,
+		extensions: pick("extensions", void 0),
+		strict: pick("strict", flags.strict),
+		verbose: pick("verbose", flags.verbose),
+		prefix: pick("prefix", void 0),
+		targets: pick("targets", flags.targets),
+		minify: pick("minify", void 0),
+		staticCss: pick("staticCss", void 0),
+		layers: pick("layers", void 0),
+		mode: resolvedMode.mode
+	};
+	const excludePatterns = createExcludeMatcher(options.exclude).patterns;
+	return {
+		driver: "cli",
+		root: effectiveRoot,
+		configFile,
+		options,
+		outDir,
+		excludePatterns,
+		mode: resolvedMode.mode,
+		provenance
+	};
+}
+/** The `--print-config` projection: everything effective, nothing hidden. */
+function projectResolvedConfig(config) {
+	return {
+		driver: config.driver,
+		root: config.root,
+		configFile: config.configFile,
+		outDir: config.outDir,
+		mode: config.mode,
+		system: config.options.system,
+		strict: config.options.strict ?? false,
+		verbose: config.options.verbose ?? false,
+		targets: config.options.targets ?? null,
+		minify: config.options.minify ?? null,
+		prefix: config.options.prefix ?? null,
+		layers: config.options.layers ?? null,
+		exclude: config.excludePatterns,
+		provenance: config.provenance
+	};
+}
+//#endregion
+//#region src/watch.ts
+/**
+* `animus watch` — the session's watcher loop as a long-lived foreground
+* process (openspec: standalone-extraction-cli, design D5 watch half).
+*
+* Contract:
+* - Readiness is an explicit observable event distinct from idle: ONE
+*   structured stderr `watch ready` line after the first complete,
+*   consistent publication (plus the session status artifact's additive
+*   monotonic `ready` field, schema-bumped compatibly).
+* - Mid-run failures keep last-good output and report per-cycle on stderr;
+*   every publication goes through the SAME deterministic CLI writer as
+*   `animus build` (design D3) and the advisory lock is held for the
+*   watch's lifetime.
+* - Watch-capability degradation is loud and names roots: a persistent
+*   stderr warning per unwatched root at every publication, and
+*   `--fail-on-degraded` for orchestrators that would rather die (exit 3).
+* - The process stays alive on purpose: the session watcher unrefs every
+*   handle (it must never hold a plugin host's process open), so the CLI
+*   holds its own ref'd keepalive. SIGINT exits 130, SIGTERM 143, both
+*   releasing the lock and removing the session tree — a watch keeps its
+*   session tree alive WHILE RUNNING (transform consumers may exist) and
+*   removes it on clean shutdown, unlike build's publish-then-remove.
+*
+* COORDINATION: `external-source-watch-ingestion` owns watch-ingestion
+* semantics — this verb consumes `startTurbopackWatcher` and
+* `handleWatchUpdate` as-is (the per-cycle wrapper below only observes
+* cycle boundaries to drive publication policy; it forks no ingestion
+* behavior).
+*/
+/** Signal exit conventions (128 + signal number) plus the degraded-exit
+*  class: watch capability loss is an environment failure (taxonomy 3). */
+const EXIT_SIGINT = 130;
+const EXIT_SIGTERM = 143;
+const EXIT_DEGRADED = 3;
+/**
+* The degradation list for one publication — every root whose edits the
+* watch will NOT observe, with the reason. Sources:
+* - the project root itself when the platform watcher could not start
+*   (recursive fs.watch unavailable / registration failed — the session
+*   degrades to no-watch with a warning and returns no handle);
+* - external roots resolved through node_modules (documented unwatchable —
+*   the orchestrator never registers them; its own guardrail-G2 comment on
+*   `openExternalWatcher`'s early return);
+* - external roots whose watcher failed after registration (the session's
+*   sticky `external-watch:` diagnostics, which carry the reason).
+*/
+function collectDegradedRoots(inputs) {
+	const seen = /* @__PURE__ */ new Set();
+	const degraded = [];
+	const add = (root, reason) => {
+		if (seen.has(root)) return;
+		seen.add(root);
+		degraded.push({
+			root,
+			reason
+		});
+	};
+	if (!inputs.projectWatchActive) add(inputs.projectRoot, "platform watcher unavailable — NO source edits will be observed; restart the watch after changes");
+	for (const root of inputs.externalWatchRoots) if (root.split(/[\\/]/).includes("node_modules")) add(root, "resolved through node_modules (documented unwatchable) — edits in this package require a restart");
+	const stickyPrefix = "external-watch:";
+	for (const [key, message] of inputs.stickyDiagnostics) {
+		if (!key.startsWith(stickyPrefix)) continue;
+		add(key.slice(15), message);
+	}
+	return degraded;
+}
+/** One persistent stderr warning per unwatched root (design D5: loud,
+*  names the root and the consequence, repeated at every publication —
+*  never a one-shot). */
+function formatDegradedRootLine(entry) {
+	return `watch degraded root=${entry.root} — ${entry.reason}`;
+}
+/** Composite key of the shared payload set — the cycle-level dedupe gate
+*  (a no-op analysis republishes nothing; disk bytes stay untouched). */
+function currentPayloadKey() {
+	return [
+		contentHash(getManifestJson() ?? ""),
+		contentHash(getSharedCss()),
+		contentHash(getSharedSystemProps())
+	].join(":");
+}
+/**
+* Run the watch loop. Resolves with the process exit code on shutdown
+* (130 SIGINT / 143 SIGTERM / 3 --fail-on-degraded trip). Startup
+* failures — preflight, first pipeline, first publication — THROW with
+* the same taxonomy as build: readiness is a contract (NS3), so a
+* supervisor either observes the ready event or observes a nonzero exit,
+* never a silent hang with no first publication.
+*/
+async function runWatch(config, flags) {
+	const { outDir, root } = config;
+	await runPreflight(config);
+	const release = acquireLock(outDir);
+	let session;
+	let firstPublication;
+	try {
+		session = createCliSession(config);
+		try {
+			await session.runFullPipeline();
+		} catch (error) {
+			throw new ExtractionFailure(String(error));
+		}
+		firstPublication = publishSharedPayloads(config, session);
+		reportDiscoveryOutcomes(config, session);
+	} catch (error) {
+		release();
+		const dir = session?.sessionDir ?? getSessionArtifactDir();
+		if (dir) rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	let publications = 1;
+	let lastPublishedKey = currentPayloadKey();
+	return new Promise((resolvePromise) => {
+		let settled = false;
+		let watcher = null;
+		const keepalive = setInterval(() => {}, 2 ** 30);
+		const shutdown = (code, reason) => {
+			if (settled) return;
+			settled = true;
+			process.removeListener("SIGINT", onSigint);
+			process.removeListener("SIGTERM", onSigterm);
+			watcher?.close();
+			(async () => {
+				try {
+					await Promise.race([watcher?.settle() ?? Promise.resolve(), new Promise((res) => setTimeout(res, 1e4).unref?.())]);
+				} catch {}
+				try {
+					rmSync(session.sessionDir, {
+						recursive: true,
+						force: true
+					});
+				} catch {}
+				release();
+				clearInterval(keepalive);
+				err(`watch shutdown reason=${reason} publications=${publications}`);
+				resolvePromise(code);
+			})();
+		};
+		const onSigint = () => shutdown(EXIT_SIGINT, "SIGINT");
+		const onSigterm = () => shutdown(EXIT_SIGTERM, "SIGTERM");
+		process.on("SIGINT", onSigint);
+		process.on("SIGTERM", onSigterm);
+		/** Print the per-publication degradation warnings. Returns true when
+		*  --fail-on-degraded tripped (shutdown already initiated). */
+		const reportDegradation = () => {
+			const degraded = collectDegradedRoots({
+				projectRoot: root,
+				projectWatchActive: watcher !== null && !watcher.died,
+				externalWatchRoots: session.externalWatchRoots,
+				stickyDiagnostics: session.stickyDiagnostics
+			});
+			for (const entry of degraded) err(formatDegradedRootLine(entry));
+			if (degraded.length > 0 && flags.failOnDegraded) {
+				err(`watch degraded and --fail-on-degraded is set — exiting ${EXIT_DEGRADED}`);
+				shutdown(EXIT_DEGRADED, "fail-on-degraded");
+				return true;
+			}
+			return false;
+		};
+		const baseHandleWatchUpdate = session.handleWatchUpdate.bind(session);
+		session.handleWatchUpdate = async (changes) => {
+			if (settled) return;
+			try {
+				await baseHandleWatchUpdate(changes);
+			} catch (error) {
+				if (settled) return;
+				err(`watch cycle failed — keeping last-good artifacts in ${outDir}: ${String(error)}`);
+				return;
+			}
+			if (settled) return;
+			const key = currentPayloadKey();
+			if (key === lastPublishedKey) return;
+			let outcome;
+			try {
+				outcome = publishSharedPayloads(config, session);
+			} catch (error) {
+				err(`watch cycle publication rejected — keeping last-good artifacts in ${outDir}: ${String(error)}`);
+				return;
+			}
+			lastPublishedKey = key;
+			publications += 1;
+			err(`watch republished components=${outcome.componentCount} files=${outcome.fileCount} outDir=${outDir}`);
+			reportDegradation();
+		};
+		watcher = startTurbopackWatcher(session, root);
+		if (watcher) watcher.onDied = () => {
+			if (!settled) reportDegradation();
+		};
+		if (reportDegradation()) return;
+		err(`watch ready components=${firstPublication.componentCount} files=${firstPublication.fileCount} outDir=${outDir}`);
+	});
+}
+//#endregion
+//#region src/index.ts
+/**
+* `animus` — the standalone extraction CLI (openspec:
+* standalone-extraction-cli).
+*
+* Contract (design D5): stdout carries machine output ONLY (today: the
+* `--print-config` JSON projection); every human-facing line goes to
+* stderr. Exit taxonomy: 0 success · 1 extraction/strict failure · 2
+* config/usage error · 3 engine/environment failure.
+*
+* UNSTABLE MODULE SURFACE: the package's programmatic exports (`main`,
+* `exitCodeFor`, the EXIT_* constants) exist for the repo's own lanes and
+* tests; the supported consumer surface is the `animus` binary. The module
+* API may change without semver ceremony until a consumer contract ships
+* (standalone-extraction-cli inc 07).
+*/
+const EXIT_OK = 0;
+const EXIT_EXTRACTION = 1;
+const EXIT_USAGE = 2;
+const EXIT_ENVIRONMENT = 3;
+const USAGE = `animus — standalone Animus extraction
+
+Usage:
+  animus build [options]      One-shot extraction to the artifact directory
+  animus watch [options]      Long-lived watch: republish on change; ready,
+                              per-cycle failures, and degradation on stderr
+  animus print-config [opts]  Print the fully resolved configuration (JSON)
+
+Options:
+  --system <path>     SystemInstance module (required unless configured)
+  --root <path>       Root every relative input resolves against
+  --config <path>     Explicit config file (default: animus.config.* in root)
+  --out-dir <path>    Artifact directory (default: <root>/.animus)
+  --exclude <glob>    Additional exclusion (repeatable; MERGES with defaults)
+  --mode <m>          'development' | 'production' (default: production)
+  --targets <query>   Browserslist query for CSS lowering
+  --strict            Escalate extraction warnings to failures
+  --fail-on-degraded  watch only: exit 3 instead of running with unwatched
+                      roots (degradation is otherwise reported and tolerated)
+  --verbose           Verbose logging (stderr)
+  --print-config      Alias of the print-config command
+  --help              This text
+
+Exit codes: 0 success · 1 extraction failure · 2 config error · 3 engine failure
+Watch shutdown: SIGINT exits 130, SIGTERM 143 (lock released, last-good kept)
+`;
+/** Classify an error into the documented exit taxonomy. ExtractionFailure
+*  and unclassified errors deliberately share the extraction exit class —
+*  an unknown throw during a build IS a failed extraction to a supervisor. */
+function exitCodeFor(error) {
+	if (error instanceof UsageFailure || error instanceof AnimusConfigError) return 2;
+	if (error instanceof EnvironmentFailure) return 3;
+	return 1;
+}
+async function main(argv = process.argv.slice(2)) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			allowPositionals: true,
+			options: {
+				system: { type: "string" },
+				root: { type: "string" },
+				config: { type: "string" },
+				"out-dir": { type: "string" },
+				exclude: {
+					type: "string",
+					multiple: true
+				},
+				mode: { type: "string" },
+				targets: { type: "string" },
+				strict: { type: "boolean" },
+				verbose: { type: "boolean" },
+				"fail-on-degraded": { type: "boolean" },
+				"print-config": { type: "boolean" },
+				help: { type: "boolean" }
+			}
+		});
+	} catch (error) {
+		console.error(`[animus] ${String(error.message)}`);
+		console.error(USAGE);
+		process.exitCode = 2;
+		return;
+	}
+	const { values, positionals } = parsed;
+	if (values.help || positionals.length === 0) {
+		console.error(USAGE);
+		process.exitCode = positionals.length === 0 && !values.help ? 2 : 0;
+		return;
+	}
+	const command = positionals[0];
+	const flags = {
+		system: values.system,
+		root: values.root,
+		config: values.config,
+		outDir: values["out-dir"],
+		strict: values.strict,
+		verbose: values.verbose,
+		mode: values.mode,
+		targets: values.targets,
+		exclude: values.exclude
+	};
+	try {
+		const config = await resolveCliConfig(flags, process.cwd());
+		if (command === "print-config" || values["print-config"]) {
+			console.log(JSON.stringify(projectResolvedConfig(config), null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (command === "build") {
+			await runBuild(config);
+			process.exitCode = 0;
+			return;
+		}
+		if (command === "watch") {
+			process.exitCode = await runWatch(config, { failOnDegraded: values["fail-on-degraded"] === true });
+			return;
+		}
+		console.error(`[animus] Unknown command '${command}'`);
+		console.error(USAGE);
+		process.exitCode = 2;
+	} catch (error) {
+		console.error(`[animus] ${String(error.message ?? error)}`);
+		process.exitCode = exitCodeFor(error);
+	}
+}
+//#endregion
+export { EXIT_ENVIRONMENT, EXIT_EXTRACTION, EXIT_OK, EXIT_USAGE, exitCodeFor, main };