@monotykamary/dsh 0.1.0-rc.10

package/lib/plugin-D0jZWziz.js

@@ -0,0 +1,129 @@
+import { t as INSTALL_ANCHOR } from "./profile-boot-CCBe1Ijy.js";
+import { existsSync } from "node:fs";
+import { DEFAULT_PROFILE_BUNDLES, PROFILE_TEMPLATES, initProfile, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest } from "@monotykamary/dsh-app-boot";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region lib/types/plugin.js
+/**
+* `dsh plugin --profile <name> <args...>` — profile plugin management as a
+* thin pnpm forwarder: initialize the profile on first use, run
+* `pnpm <args...>` in the profile directory, then reconcile the
+* `dsh.profile.bundles` layer list against the installed state (a dependency
+* resolving to a package that declares `dsh.bundle` joins the layer stack; a
+* removed or bundle-less dependency leaves it). Reconciling by installed
+* state, not by dependency diff, means `update` activates a package that
+* gained its `dsh.bundle` declaration in a newer version.
+* @module @monotykamary/dsh/plugin
+*/
+const NAME = "dsh";
+/**
+* Whether a resolved dependency exports a profile patch, i.e. is a bundle.
+* @param packageName - the dependency's package name.
+* @param profileDir - the profile directory (resolution anchor).
+* @returns true when the package manifest declares `dsh.bundle`.
+*/
+function exportsPatch(packageName, profileDir) {
+	let dir;
+	try {
+		dir = resolveBundleDir(NAME, packageName, INSTALL_ANCHOR, profileDir);
+	} catch {
+		return false;
+	}
+	return readProfileManifest(NAME, dir).dsh?.bundle?.patch !== void 0;
+}
+/**
+* Reconcile `dsh.profile.bundles` against the installed state: pnpm has
+* already written the real installed names (so a git/path/tarball/alias spec
+* on the command line reconciles by its true package name) and materialized
+* the packages. A dependency that resolves to a `dsh.bundle`-declaring
+* package joins the layer stack (appended in dependency order); a
+* dependency-listed name that no longer does — removed, or the installed
+* version dropped the declaration — leaves it. In-box bundles from the
+* profile template are not dependencies and are never touched. Warns once
+* per newly-added bundle-less dependency (a plain library is fine; the
+* warning is orientation).
+*/
+function reconcilePlugins(before, profileDir) {
+	const after = readProfileManifest(NAME, profileDir);
+	const beforeDeps = new Set(Object.keys(before.dependencies ?? {}));
+	const dependencies = Object.keys(after.dependencies ?? {});
+	const plugins = after.dsh?.profile?.bundles ?? [];
+	let changed = false;
+	for (const packageName of dependencies) {
+		const isBundle = exportsPatch(packageName, profileDir);
+		if (isBundle && !plugins.includes(packageName)) {
+			plugins.push(packageName);
+			changed = true;
+		} else if (!isBundle && !beforeDeps.has(packageName)) process.stderr.write(`${NAME}: warning: ${packageName} declares no dsh.bundle — installed as a plain dependency, not a profile layer (a later update that gains one activates it automatically)
+`);
+	}
+	const dependencySet = new Set(dependencies);
+	for (const packageName of [...plugins]) {
+		const wasDependency = beforeDeps.has(packageName) || dependencySet.has(packageName);
+		const stillBundle = dependencySet.has(packageName) && exportsPatch(packageName, profileDir);
+		if (wasDependency && !stillBundle) {
+			plugins.splice(plugins.indexOf(packageName), 1);
+			changed = true;
+		}
+	}
+	if (!changed) return;
+	after.dsh = {
+		...after.dsh,
+		profile: {
+			...after.dsh?.profile,
+			bundles: plugins
+		}
+	};
+	writeProfileManifest(profileDir, after);
+}
+/**
+* Rewrite relative filesystem specs against the user's invoking directory.
+* pnpm runs with cwd = the profile directory, so a bare `.` or `../plugin`
+* (or their `file:`/`link:` forms) would silently resolve inside the profile
+* — `add .` from a plugin checkout would self-link the profile. Absolute
+* specs, registry names, and every other pnpm argument pass through
+* untouched.
+* @param argument - one pnpm argument, verbatim from argv.
+* @param cwd - the directory `dsh` was invoked from.
+* @returns the argument with a relative path spec anchored to `cwd`.
+*/
+function anchorPathSpec(argument, cwd) {
+	const match = /^(?<prefix>(?:file|link):)?(?<path>\.{1,2}(?:[/\\].*)?)$/.exec(argument);
+	if (match?.groups?.path === void 0) return argument;
+	return `${match.groups.prefix ?? ""}${resolve(cwd, match.groups.path)}`;
+}
+/**
+* Run one `dsh plugin` invocation: init if needed, forward to pnpm, reconcile.
+* @param profile - the profile name.
+* @param args - pnpm arguments with relative path specs anchored to the invoking directory.
+* @returns the pnpm exit code.
+*/
+function runPlugin(profile, args) {
+	const dir = resolveProfileDir(profile);
+	if (!existsSync(join(dir, "package.json"))) {
+		initProfile(dir, PROFILE_TEMPLATES[profile] ?? DEFAULT_PROFILE_BUNDLES);
+		process.stderr.write(`${NAME}: initialized profile ${profile} at ${dir}\n`);
+	}
+	const before = readProfileManifest(NAME, dir);
+	const result = spawnSync("pnpm", args.map((argument) => anchorPathSpec(argument, process.cwd())), {
+		cwd: dir,
+		stdio: "inherit",
+		shell: process.platform === "win32"
+	});
+	if (result.error !== void 0) {
+		if (result.error.code === "ENOENT") {
+			process.stderr.write(`${NAME}: pnpm not found on PATH — install pnpm to manage profile plugins\n`);
+			return 127;
+		}
+		throw result.error;
+	}
+	const exitCode = result.status ?? 1;
+	if (exitCode === 0) reconcilePlugins(before, dir);
+	else {
+		process.stderr.write(`${NAME}: pnpm failed in profile directory ${dir}\n`);
+		if (args.some((argument) => /^git\+|^github:|\.git(?:#|$)/.test(argument))) process.stderr.write(`${NAME}: git-hosted plugins build on install via their prepare script, which pnpm blocks until allowed — add the exact key pnpm printed above under allowBuilds in ${join(dir, "pnpm-workspace.yaml")}, then re-run\n`);
+	}
+	return exitCode;
+}
+//#endregion
+export { runPlugin };

package/lib/plugin-cfFEyTiM.js

@@ -0,0 +1,129 @@
+import { t as INSTALL_ANCHOR } from "./profile-boot-hvAsNaX6.js";
+import { existsSync } from "node:fs";
+import { DEFAULT_PROFILE_BUNDLES, PROFILE_TEMPLATES, initProfile, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest } from "@monotykamary/dsh-app-boot";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region lib/types/plugin.js
+/**
+* `dsh plugin --profile <name> <args...>` — profile plugin management as a
+* thin pnpm forwarder: initialize the profile on first use, run
+* `pnpm <args...>` in the profile directory, then reconcile the
+* `dsh.profile.bundles` layer list against the installed state (a dependency
+* resolving to a package that declares `dsh.bundle` joins the layer stack; a
+* removed or bundle-less dependency leaves it). Reconciling by installed
+* state, not by dependency diff, means `update` activates a package that
+* gained its `dsh.bundle` declaration in a newer version.
+* @module @monotykamary/dsh/plugin
+*/
+const NAME = "dsh";
+/**
+* Whether a resolved dependency exports a profile patch, i.e. is a bundle.
+* @param packageName - the dependency's package name.
+* @param profileDir - the profile directory (resolution anchor).
+* @returns true when the package manifest declares `dsh.bundle`.
+*/
+function exportsPatch(packageName, profileDir) {
+	let dir;
+	try {
+		dir = resolveBundleDir(NAME, packageName, INSTALL_ANCHOR, profileDir);
+	} catch {
+		return false;
+	}
+	return readProfileManifest(NAME, dir).dsh?.bundle?.patch !== void 0;
+}
+/**
+* Reconcile `dsh.profile.bundles` against the installed state: pnpm has
+* already written the real installed names (so a git/path/tarball/alias spec
+* on the command line reconciles by its true package name) and materialized
+* the packages. A dependency that resolves to a `dsh.bundle`-declaring
+* package joins the layer stack (appended in dependency order); a
+* dependency-listed name that no longer does — removed, or the installed
+* version dropped the declaration — leaves it. In-box bundles from the
+* profile template are not dependencies and are never touched. Warns once
+* per newly-added bundle-less dependency (a plain library is fine; the
+* warning is orientation).
+*/
+function reconcilePlugins(before, profileDir) {
+	const after = readProfileManifest(NAME, profileDir);
+	const beforeDeps = new Set(Object.keys(before.dependencies ?? {}));
+	const dependencies = Object.keys(after.dependencies ?? {});
+	const plugins = after.dsh?.profile?.bundles ?? [];
+	let changed = false;
+	for (const packageName of dependencies) {
+		const isBundle = exportsPatch(packageName, profileDir);
+		if (isBundle && !plugins.includes(packageName)) {
+			plugins.push(packageName);
+			changed = true;
+		} else if (!isBundle && !beforeDeps.has(packageName)) process.stderr.write(`${NAME}: warning: ${packageName} declares no dsh.bundle — installed as a plain dependency, not a profile layer (a later update that gains one activates it automatically)
+`);
+	}
+	const dependencySet = new Set(dependencies);
+	for (const packageName of [...plugins]) {
+		const wasDependency = beforeDeps.has(packageName) || dependencySet.has(packageName);
+		const stillBundle = dependencySet.has(packageName) && exportsPatch(packageName, profileDir);
+		if (wasDependency && !stillBundle) {
+			plugins.splice(plugins.indexOf(packageName), 1);
+			changed = true;
+		}
+	}
+	if (!changed) return;
+	after.dsh = {
+		...after.dsh,
+		profile: {
+			...after.dsh?.profile,
+			bundles: plugins
+		}
+	};
+	writeProfileManifest(profileDir, after);
+}
+/**
+* Rewrite relative filesystem specs against the user's invoking directory.
+* pnpm runs with cwd = the profile directory, so a bare `.` or `../plugin`
+* (or their `file:`/`link:` forms) would silently resolve inside the profile
+* — `add .` from a plugin checkout would self-link the profile. Absolute
+* specs, registry names, and every other pnpm argument pass through
+* untouched.
+* @param argument - one pnpm argument, verbatim from argv.
+* @param cwd - the directory `dsh` was invoked from.
+* @returns the argument with a relative path spec anchored to `cwd`.
+*/
+function anchorPathSpec(argument, cwd) {
+	const match = /^(?<prefix>(?:file|link):)?(?<path>\.{1,2}(?:[/\\].*)?)$/.exec(argument);
+	if (match?.groups?.path === void 0) return argument;
+	return `${match.groups.prefix ?? ""}${resolve(cwd, match.groups.path)}`;
+}
+/**
+* Run one `dsh plugin` invocation: init if needed, forward to pnpm, reconcile.
+* @param profile - the profile name.
+* @param args - pnpm arguments with relative path specs anchored to the invoking directory.
+* @returns the pnpm exit code.
+*/
+function runPlugin(profile, args) {
+	const dir = resolveProfileDir(profile);
+	if (!existsSync(join(dir, "package.json"))) {
+		initProfile(dir, PROFILE_TEMPLATES[profile] ?? DEFAULT_PROFILE_BUNDLES);
+		process.stderr.write(`${NAME}: initialized profile ${profile} at ${dir}\n`);
+	}
+	const before = readProfileManifest(NAME, dir);
+	const result = spawnSync("pnpm", args.map((argument) => anchorPathSpec(argument, process.cwd())), {
+		cwd: dir,
+		stdio: "inherit",
+		shell: process.platform === "win32"
+	});
+	if (result.error !== void 0) {
+		if (result.error.code === "ENOENT") {
+			process.stderr.write(`${NAME}: pnpm not found on PATH — install pnpm to manage profile plugins\n`);
+			return 127;
+		}
+		throw result.error;
+	}
+	const exitCode = result.status ?? 1;
+	if (exitCode === 0) reconcilePlugins(before, dir);
+	else {
+		process.stderr.write(`${NAME}: pnpm failed in profile directory ${dir}\n`);
+		if (args.some((argument) => /^git\+|^github:|\.git(?:#|$)/.test(argument))) process.stderr.write(`${NAME}: git-hosted plugins build on install via their prepare script, which pnpm blocks until allowed — add the exact key pnpm printed above under allowBuilds in ${join(dir, "pnpm-workspace.yaml")}, then re-run\n`);
+	}
+	return exitCode;
+}
+//#endregion
+export { runPlugin };

package/lib/plugin-vw4XdVuN.js

@@ -0,0 +1,129 @@
+import { t as INSTALL_ANCHOR } from "./profile-boot-CXPZgDex.js";
+import { existsSync } from "node:fs";
+import { DEFAULT_PROFILE_BUNDLES, PROFILE_TEMPLATES, initProfile, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest } from "@monotykamary/dsh-app-boot";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region lib/types/plugin.js
+/**
+* `dsh plugin --profile <name> <args...>` — profile plugin management as a
+* thin pnpm forwarder: initialize the profile on first use, run
+* `pnpm <args...>` in the profile directory, then reconcile the
+* `dsh.profile.bundles` layer list against the installed state (a dependency
+* resolving to a package that declares `dsh.bundle` joins the layer stack; a
+* removed or bundle-less dependency leaves it). Reconciling by installed
+* state, not by dependency diff, means `update` activates a package that
+* gained its `dsh.bundle` declaration in a newer version.
+* @module @monotykamary/dsh/plugin
+*/
+const NAME = "dsh";
+/**
+* Whether a resolved dependency exports a profile patch, i.e. is a bundle.
+* @param packageName - the dependency's package name.
+* @param profileDir - the profile directory (resolution anchor).
+* @returns true when the package manifest declares `dsh.bundle`.
+*/
+function exportsPatch(packageName, profileDir) {
+	let dir;
+	try {
+		dir = resolveBundleDir(NAME, packageName, INSTALL_ANCHOR, profileDir);
+	} catch {
+		return false;
+	}
+	return readProfileManifest(NAME, dir).dsh?.bundle?.patch !== void 0;
+}
+/**
+* Reconcile `dsh.profile.bundles` against the installed state: pnpm has
+* already written the real installed names (so a git/path/tarball/alias spec
+* on the command line reconciles by its true package name) and materialized
+* the packages. A dependency that resolves to a `dsh.bundle`-declaring
+* package joins the layer stack (appended in dependency order); a
+* dependency-listed name that no longer does — removed, or the installed
+* version dropped the declaration — leaves it. In-box bundles from the
+* profile template are not dependencies and are never touched. Warns once
+* per newly-added bundle-less dependency (a plain library is fine; the
+* warning is orientation).
+*/
+function reconcilePlugins(before, profileDir) {
+	const after = readProfileManifest(NAME, profileDir);
+	const beforeDeps = new Set(Object.keys(before.dependencies ?? {}));
+	const dependencies = Object.keys(after.dependencies ?? {});
+	const plugins = after.dsh?.profile?.bundles ?? [];
+	let changed = false;
+	for (const packageName of dependencies) {
+		const isBundle = exportsPatch(packageName, profileDir);
+		if (isBundle && !plugins.includes(packageName)) {
+			plugins.push(packageName);
+			changed = true;
+		} else if (!isBundle && !beforeDeps.has(packageName)) process.stderr.write(`${NAME}: warning: ${packageName} declares no dsh.bundle — installed as a plain dependency, not a profile layer (a later update that gains one activates it automatically)
+`);
+	}
+	const dependencySet = new Set(dependencies);
+	for (const packageName of [...plugins]) {
+		const wasDependency = beforeDeps.has(packageName) || dependencySet.has(packageName);
+		const stillBundle = dependencySet.has(packageName) && exportsPatch(packageName, profileDir);
+		if (wasDependency && !stillBundle) {
+			plugins.splice(plugins.indexOf(packageName), 1);
+			changed = true;
+		}
+	}
+	if (!changed) return;
+	after.dsh = {
+		...after.dsh,
+		profile: {
+			...after.dsh?.profile,
+			bundles: plugins
+		}
+	};
+	writeProfileManifest(profileDir, after);
+}
+/**
+* Rewrite relative filesystem specs against the user's invoking directory.
+* pnpm runs with cwd = the profile directory, so a bare `.` or `../plugin`
+* (or their `file:`/`link:` forms) would silently resolve inside the profile
+* — `add .` from a plugin checkout would self-link the profile. Absolute
+* specs, registry names, and every other pnpm argument pass through
+* untouched.
+* @param argument - one pnpm argument, verbatim from argv.
+* @param cwd - the directory `dsh` was invoked from.
+* @returns the argument with a relative path spec anchored to `cwd`.
+*/
+function anchorPathSpec(argument, cwd) {
+	const match = /^(?<prefix>(?:file|link):)?(?<path>\.{1,2}(?:[/\\].*)?)$/.exec(argument);
+	if (match?.groups?.path === void 0) return argument;
+	return `${match.groups.prefix ?? ""}${resolve(cwd, match.groups.path)}`;
+}
+/**
+* Run one `dsh plugin` invocation: init if needed, forward to pnpm, reconcile.
+* @param profile - the profile name.
+* @param args - pnpm arguments with relative path specs anchored to the invoking directory.
+* @returns the pnpm exit code.
+*/
+function runPlugin(profile, args) {
+	const dir = resolveProfileDir(profile);
+	if (!existsSync(join(dir, "package.json"))) {
+		initProfile(dir, PROFILE_TEMPLATES[profile] ?? DEFAULT_PROFILE_BUNDLES);
+		process.stderr.write(`${NAME}: initialized profile ${profile} at ${dir}\n`);
+	}
+	const before = readProfileManifest(NAME, dir);
+	const result = spawnSync("pnpm", args.map((argument) => anchorPathSpec(argument, process.cwd())), {
+		cwd: dir,
+		stdio: "inherit",
+		shell: process.platform === "win32"
+	});
+	if (result.error !== void 0) {
+		if (result.error.code === "ENOENT") {
+			process.stderr.write(`${NAME}: pnpm not found on PATH — install pnpm to manage profile plugins\n`);
+			return 127;
+		}
+		throw result.error;
+	}
+	const exitCode = result.status ?? 1;
+	if (exitCode === 0) reconcilePlugins(before, dir);
+	else {
+		process.stderr.write(`${NAME}: pnpm failed in profile directory ${dir}\n`);
+		if (args.some((argument) => /^git\+|^github:|\.git(?:#|$)/.test(argument))) process.stderr.write(`${NAME}: git-hosted plugins build on install via their prepare script, which pnpm blocks until allowed — add the exact key pnpm printed above under allowBuilds in ${join(dir, "pnpm-workspace.yaml")}, then re-run\n`);
+	}
+	return exitCode;
+}
+//#endregion
+export { runPlugin };

package/lib/profile-boot-B45utNE5.js

@@ -0,0 +1,2 @@
+import { a as runProfile } from "./profile-boot-CCBe1Ijy.js";
+export { runProfile };

package/lib/profile-boot-B9SlvOjV.js

@@ -0,0 +1,2 @@
+import { a as runProfile } from "./profile-boot-CXPZgDex.js";
+export { runProfile };

package/lib/profile-boot-CCBe1Ijy.js

@@ -0,0 +1,261 @@
+import { writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { PROFILE_PATCH_FILENAME, boot, composeEntries, healProfilesModuleFallback, installFailLoud, loadOptionalPatches, loadOverlayPatches, loadProfile, watchUserPatches } from "@monotykamary/dsh-app-boot";
+import { join, resolve } from "node:path";
+import { resolveDshHome } from "@monotykamary/dsh-home-paths";
+import { DSH_LAUNCH_ENVIRONMENT_KEY } from "@monotykamary/dsh-launch-environment";
+import { provideCmdline } from "@monotykamary/dsh-cmdline";
+//#region lib/types/process-shutdown.js
+/** Bounded, escalating process shutdown for the long-lived CLI surfaces. */
+/** Maximum grace allowed for the application tree to dispose before process exit. */
+const PROCESS_SHUTDOWN_TIMEOUT_MS = 5e3;
+/**
+* Create one process-exit controller around an application disposer.
+* @param dispose - Whole-application teardown that resolves at quiescence.
+* @param forceExit - Function that exits the process immediately, replaceable by tests.
+* @param complete - Function that records the natural completion code, replaceable by tests.
+* @param timeoutMs - Grace before forced exit, replaceable by tests.
+* @returns A controller whose normal calls coalesce and whose repeated signal call escalates.
+*/
+function createProcessShutdown(dispose, forceExit = (code) => {
+	process.exit(code);
+}, complete = (code) => {
+	process.exitCode = code;
+}, timeoutMs = PROCESS_SHUTDOWN_TIMEOUT_MS) {
+	let pending;
+	let timeout;
+	let completed = false;
+	let forceExited = false;
+	const clearExitTimeout = () => {
+		/* v8 ignore else -- shutdown() arms the timer before any asynchronous exit path can run. */
+		if (timeout !== void 0) clearTimeout(timeout);
+	};
+	const forceExitOnce = (code) => {
+		if (forceExited) return;
+		forceExited = true;
+		clearExitTimeout();
+		forceExit(code);
+	};
+	const completeOnce = (code) => {
+		if (completed || forceExited) return;
+		completed = true;
+		clearExitTimeout();
+		complete(code);
+	};
+	const start = (code, forceAfterDispose) => {
+		if (pending !== void 0) return pending;
+		timeout = setTimeout(() => {
+			forceExitOnce(code);
+		}, timeoutMs);
+		pending = Promise.resolve().then(dispose).then(() => {
+			if (forceAfterDispose) forceExitOnce(code);
+			else completeOnce(code);
+		}, () => {
+			forceExitOnce(code);
+		});
+		return pending;
+	};
+	return {
+		shutdown(code) {
+			return start(code, false);
+		},
+		interrupt(code) {
+			if (pending !== void 0) {
+				forceExitOnce(code);
+				return;
+			}
+			start(code, true);
+		}
+	};
+}
+//#endregion
+//#region lib/types/profile-boot.js
+/**
+* Shared profile boot for every `dsh` surface: resolve the profile, stack its
+* patch layers (bundle layers in `dsh.profile.bundles` order, the profile's
+* own `cordis.patch.yml`, `--patch` overlays), mount the
+* tree over the profile's empty root config, keep the profile patch layer
+* live, and wire fail-loud plus bounded shutdown.
+*
+* App flags are not the launcher's business: the invocation's inner arguments
+* are provided to the tree through `ctx.cmdlineArgs`, where any injected app
+* plugin may read the same immutable snapshot.
+* @module @monotykamary/dsh/profile-boot
+*/
+/** Shipped agent-preset root: beside this app's own config, in both source and built layouts. */
+const SHIPPED_PRESET_ROOT = fileURLToPath(new URL("../config/agent-presets/", import.meta.url));
+const NAME = "dsh";
+/**
+* The home-level user patch layer (`$DSH_HOME/cordis.patch.yml`), applied
+* over every profile's own layer. Resolved per call, not at module load:
+* `$DSH_HOME` may be set by the test or launcher after import.
+* @returns the absolute patch-file path.
+*/
+function homePatchPath() {
+	return join(resolveDshHome(), PROFILE_PATCH_FILENAME);
+}
+/** Absolute path of this dsh installation's package.json (both anchors: src/ and lib/ sit one level under apps/cli). */
+const INSTALL_ANCHOR = fileURLToPath(new URL("../package.json", import.meta.url));
+/** The empty root entry list every profile tree patches over. */
+const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tree is composed as patches:
+# each bundle in package.json's dsh.profile.bundles, then cordis.patch.yml, then any
+# --patch overlays. Edit cordis.patch.yml, not this file.
+[]
+`;
+/** Root config filename inside a profile directory. */
+const PROFILE_ROOT_FILENAME = "cordis.yml";
+/**
+* Load a resolved profile for `name`: heal the shared module fallback, then
+* (re)write the empty root config. The root is always rewritten: the whole
+* composition is patch layers, and the vendored Loader's tree write-back (a
+* plugin self-disposing persists the current tree) can bake composed rows
+* into this file — which would duplicate every bundle insert on the next
+* boot. The file exists on disk only because the Loader needs a real include
+* root to anchor `baseUrl` at the profile directory (the config dump anchors
+* on the same file, so both compose over the identical base).
+* @param name - the profile name.
+* @param userLayer - `false` skips parsing `cordis.patch.yml` (the default dump).
+* @returns the loaded profile.
+*/
+function prepareProfile(name, userLayer = true) {
+	healProfilesModuleFallback(INSTALL_ANCHOR);
+	const profile = loadProfile(NAME, name, INSTALL_ANCHOR, void 0, { userLayer });
+	writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
+	return profile;
+}
+/** The full patch stack of one composed profile, in application order. */
+function allPatches(composed) {
+	return [
+		...composed.bundlePatches,
+		...composed.profile.patches,
+		...composed.homePatches,
+		...composed.overlays
+	];
+}
+/**
+* Load `name` and compose its effective patch stack: bundle layers in
+* `dsh.profile.bundles` order (the base bundle gates the shell stacks by
+* platform on its own rows), the profile's user layer, the home-level user
+* layer (`$DSH_HOME/cordis.patch.yml` — machine-local preferences that apply
+* to every profile, so it outranks the per-profile layer), and `--patch`
+* overlays.
+* @param name - the profile name.
+* @param patchFiles - `--patch` overlay paths, in argv order.
+* @returns the profile, its patch layers, and the composed row index.
+*/
+function composeProfile(name, patchFiles) {
+	const profile = prepareProfile(name);
+	const homePatches = loadOptionalPatches(NAME, homePatchPath()) ?? [];
+	const overlays = patchFiles.flatMap((file) => loadOverlayPatches(NAME, resolve(file)));
+	const bundlePatches = profile.layers.flatMap((layer) => layer.patches);
+	const rows = /* @__PURE__ */ new Map();
+	for (const row of composeEntries([
+		bundlePatches,
+		profile.patches,
+		homePatches,
+		overlays
+	])) if (typeof row.id === "string") rows.set(row.id, row);
+	const composedOverlays = [...overlays];
+	if (rows.has("agent-presets")) composedOverlays.push({
+		id: "agent-presets",
+		config: {
+			...rows.get("agent-presets")?.config ?? {},
+			roots: [{
+				path: SHIPPED_PRESET_ROOT,
+				trust: "system"
+			}]
+		}
+	});
+	return {
+		profile,
+		bundlePatches,
+		homePatches,
+		overlays: composedOverlays,
+		rows
+	};
+}
+/**
+* Re-throw a watcher-setup failure unless a shutdown already owns the tree:
+* a signal aborted this invocation, or an app requested exit (`ctx.appExit`
+* from a fast one-shot) and the root's disposal rejected the in-flight setup
+* await. Either way the failure describes a tree that is exiting as asked,
+* not a broken watch.
+* @param ctx - the booted root context.
+* @param signal - this invocation's signal-shutdown fact.
+* @param error - the setup failure.
+*/
+function suppressShutdownError(ctx, signal, error) {
+	if (signal.aborted) return;
+	if (ctx.fiber.state !== 2 || ctx.get("loader") === void 0) return;
+	throw error;
+}
+/**
+* Boot one profile invocation end to end and leave process lifetime to the
+* mounted plugins (or to a one-shot runner the composition mounts).
+* @param options - environment snapshot, profile name, overlays, and the booted app's own arguments.
+* @returns the settled root context and the shutdown controller.
+*/
+async function runProfile(options) {
+	const composed = composeProfile(options.profile, options.patchFiles);
+	const app = {};
+	const shutdown = createProcessShutdown(async () => {
+		await app.current?.fiber.dispose();
+	});
+	const signalShutdown = new AbortController();
+	const interrupt = (code) => {
+		signalShutdown.abort();
+		shutdown.interrupt(code);
+	};
+	process.on("SIGTERM", () => {
+		interrupt(0);
+	});
+	process.on("SIGINT", () => {
+		interrupt(130);
+	});
+	installFailLoud(NAME, process, async () => {
+		await app.current?.fiber.dispose();
+	});
+	const rootConfig = join(composed.profile.dir, PROFILE_ROOT_FILENAME);
+	const composeLive = () => structuredClone([
+		...composed.bundlePatches,
+		...loadOptionalPatches(NAME, composed.profile.patchPath) ?? [],
+		...loadOptionalPatches(NAME, homePatchPath()) ?? [],
+		...composed.overlays
+	]);
+	const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), (hostCtx) => {
+		app.current = hostCtx;
+		hostCtx.provide(DSH_LAUNCH_ENVIRONMENT_KEY, options.environment);
+		provideCmdline(hostCtx, {
+			args: options.args,
+			exit: (code) => void shutdown.shutdown(code)
+		});
+	});
+	app.current = ctx;
+	if (!signalShutdown.signal.aborted && ctx.fiber.state === 2 && ctx.get("loader") !== void 0) try {
+		if (ctx.get("hmr") === void 0) {
+			if (ctx.get("timer") === void 0) await ctx.loader.create({ name: "@monotykamary/cordis-plugin-timer" });
+			await ctx.loader.create({
+				name: "@monotykamary/cordis-plugin-hmr",
+				config: { root: [] }
+			});
+		}
+		await watchUserPatches(ctx, {
+			binName: NAME,
+			filename: composed.profile.patchPath,
+			compose: composeLive
+		});
+		await watchUserPatches(ctx, {
+			binName: NAME,
+			filename: homePatchPath(),
+			compose: composeLive
+		});
+	} catch (error) {
+		suppressShutdownError(ctx, signalShutdown.signal, error);
+	}
+	return {
+		ctx,
+		shutdown
+	};
+}
+//#endregion
+export { runProfile as a, prepareProfile as i, PROFILE_ROOT_FILENAME as n, homePatchPath as r, INSTALL_ANCHOR as t };