@qilin-agent/cli 0.0.0-stage → 3.1.3

package/lib/plugin-BQ1sn-63.js

@@ -0,0 +1,239 @@
+import { t as INSTALL_ANCHOR } from "./profile-boot-DSy6PUHQ.js";
+import { DEFAULT_PROFILE_BUNDLES, EngineNameCollisionError, PROFILE_TEMPLATES, doctorPluginPackage, initProfile, readProfileCompatibility, readProfileManifest, readProfilePluginRows, reconcileProfileBundles, resolveBundleDir, resolveProfileDir, setProfileVersionExemption } from "@qilin-agent/app-boot";
+import { mkdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { withFileLock } from "@qilin-agent/atomic-write";
+import { refusedInstallSpecs } from "@qilin-agent/plugin-manager/operations";
+//#region lib/types/plugin.js
+/**
+* `qilin plugin [--profile <name>] <args...>` — profile plugin management.
+*
+* `list` and `doctor` are the launcher's own verbs and never mutate anything:
+* `list` prints the profile's bundle layers, and `doctor` reports one plugin
+* package's DSH-era compatibility. `version-exemptions`, `allow-version`, and
+* `revoke-version` read and write the profile's own `compatibility.json` under
+* its file lock and never become pnpm arguments. Every other argument list
+* forwards to pnpm in the profile directory: refuse the packages it names that
+* the running runtime version rejects, initialize the profile on first use, run
+* `pnpm <args...>`, then reconcile the `qilin.profile.bundles` layer list
+* against the installed state (a dependency resolving to a package that
+* declares `qilin.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 `qilin.bundle`
+* declaration in a newer version. A profile that installed an upstream DSH-era
+* engine package is refused before any layer changes, with the removal command
+* in the diagnostic.
+* @module @qilin-agent/cli/plugin
+*/
+const NAME = "qilin";
+/** Bound on waiting for the profile write lock an exemption command shares with the manager. */
+const LOCK_WAIT_MS = 12e4;
+/** Bound on the pre-install registry lookup that reads a named package's peers. */
+const LOOKUP_TIMEOUT_MS = 12e4;
+/**
+* Print one profile's plugin layers in activation order.
+* @param profile - the profile name, used to recognize its shipped template layers.
+* @param dir - the profile directory.
+* @returns the process exit code.
+*/
+function listPlugins(profile, dir) {
+	const rows = readProfilePluginRows(NAME, dir, INSTALL_ANCHOR, [...PROFILE_TEMPLATES[profile]?.bundles ?? []]);
+	if (rows.length === 0) {
+		process.stdout.write(`${NAME}: profile ${profile} lists no plugin layers\n`);
+		return 0;
+	}
+	for (const row of rows) {
+		const locked = row.removable ? "" : "  (shipped)";
+		process.stdout.write(`${String(row.layer)}\t${row.name}@${row.version ?? "not installed"}\t${row.source}${locked}\n`);
+	}
+	return 0;
+}
+/**
+* Resolve one doctor target: an existing package directory, or a package name
+* installed in the profile.
+* @param profile - the profile name, named in the failure diagnostic.
+* @param profileDir - the profile directory.
+* @param target - the argument as written.
+* @returns the absolute package directory.
+* @throws when neither a directory nor an installed package matches.
+*/
+function resolveDoctorTarget(profile, profileDir, target) {
+	const directory = resolve(target);
+	if (existsSync(join(directory, "package.json"))) return directory;
+	try {
+		return resolveBundleDir(NAME, target, INSTALL_ANCHOR, profileDir);
+	} catch (_notInstalled) {
+		throw new Error(`${NAME}: ${JSON.stringify(target)} is neither a package directory nor an installed package in profile ${profile}`);
+	}
+}
+/**
+* Report one plugin package's DSH-era compatibility.
+* @param profile - the profile name a package-name target resolves within.
+* @param profileDir - the profile directory.
+* @param target - the package name or directory from the command line.
+* @returns 1 when the report found a blocking problem, otherwise 0.
+*/
+function doctorPlugin(profile, profileDir, target) {
+	const report = doctorPluginPackage(NAME, resolveDoctorTarget(profile, profileDir, target), INSTALL_ANCHOR);
+	process.stdout.write(`${report.name}\t${report.verdict}\t${report.dir}\n`);
+	for (const finding of report.findings) process.stdout.write(`  ${finding.severity}\t${finding.check}\t${finding.message}\n`);
+	if (report.findings.length === 0) process.stdout.write("  no compatibility findings\n");
+	return report.verdict === "unusable" ? 1 : 0;
+}
+/**
+* Parse and run the launcher's exact-version exemption commands.
+*
+* Only these three verbs are the launcher's; every other argument list stays
+* pnpm's. `--accept-risk` is the operator's acknowledgement that the waived
+* version may crash the application or corrupt data, and a grant may name only
+* the running runtime version, so an approval can never be pre-granted for a
+* future one. Revocation may name a historical runtime, because withdrawing an
+* approval after an upgrade must stay possible.
+* @param profile - the profile name whose compatibility file is read or written.
+* @param args - the subcommand and its arguments, verbatim from argv.
+* @returns the process exit code, or undefined when the arguments are pnpm's.
+*/
+async function exemptionCommand(profile, args) {
+	const [command, ...rest] = args;
+	if (command !== "allow-version" && command !== "revoke-version" && command !== "version-exemptions") return void 0;
+	try {
+		let packageVersion;
+		let runtimeVersion;
+		let acceptRisk = false;
+		const remaining = rest.values();
+		for (const argument of remaining) if (argument === "--accept-risk" && command === "allow-version" && !acceptRisk) acceptRisk = true;
+		else if (argument === "--qilin-version" && runtimeVersion === void 0) runtimeVersion = remaining.next().value;
+		else if (argument.startsWith("--qilin-version=") && runtimeVersion === void 0) runtimeVersion = argument.slice(16);
+		else if (!argument.startsWith("-") && packageVersion === void 0) packageVersion = argument;
+		else throw new Error(`unexpected argument ${JSON.stringify(argument)}`);
+		if (command === "version-exemptions" && rest.length > 0) throw new Error(`usage: ${NAME} plugin version-exemptions`);
+		let request;
+		if (command !== "version-exemptions") {
+			if (packageVersion === void 0 || runtimeVersion === void 0) throw new Error(`usage: ${NAME} plugin ${command} <package@version> --qilin-version <exact>${command === "allow-version" ? " --accept-risk" : ""}`);
+			request = {
+				packageVersion,
+				runtimeVersion
+			};
+		}
+		if (command === "allow-version") process.stderr.write(`${NAME}: warning: allowing incompatible plugin versions can break the application or corrupt data. Approval applies only to the exact package and ${NAME} versions.\n`);
+		const dir = resolveProfileDir(profile);
+		await mkdir(dir, { recursive: true });
+		await withFileLock(join(dir, "package.json"), async () => {
+			if (!existsSync(join(dir, "package.json"))) initProfile(dir, PROFILE_TEMPLATES[profile]?.bundles ?? DEFAULT_PROFILE_BUNDLES);
+			if (request === void 0) {
+				const { exemptions, warnings } = readProfileCompatibility(dir);
+				for (const warning of warnings) process.stderr.write(`${NAME}: warning: ${warning}\n`);
+				process.stdout.write(JSON.stringify(exemptions, void 0, 2) + "\n");
+			} else {
+				await setProfileVersionExemption(dir, request.packageVersion, request.runtimeVersion, command === "allow-version", acceptRisk);
+				process.stdout.write(`${NAME}: ${command === "allow-version" ? "allowed" : "revoked"} ${request.packageVersion} for ${NAME} ${request.runtimeVersion}\n`);
+			}
+		}, { waitMs: LOCK_WAIT_MS });
+		return 0;
+	} catch (error) {
+		process.stderr.write(`${NAME}: ${String(error)}\n`);
+		return 1;
+	}
+}
+/**
+* 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 `qilin` 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)}`;
+}
+/**
+* Refuse an install command that names a package the running runtime version
+* rejects, before pnpm writes anything.
+*
+* The check reads the named manifests without installing them, so a rejected
+* package never lands on disk and the version already in use keeps working. The
+* post-install and startup checks still judge what a path or registry lookup
+* cannot: a git or tarball spec, and a bundle component whose peers need the
+* installed tree.
+* @param profile - the profile name the operation runs against.
+* @param dir - the profile directory.
+* @param args - pnpm arguments, before relative path anchoring.
+* @returns the process exit code when the command was refused, otherwise undefined.
+*/
+async function refuseIncompatibleInstall(profile, dir, args) {
+	const refused = await refusedInstallSpecs({
+		profile,
+		dir,
+		installAnchor: INSTALL_ANCHOR,
+		cwd: process.cwd()
+	}, args, {
+		execution: "cli",
+		lookupTimeoutMs: LOOKUP_TIMEOUT_MS
+	});
+	if (refused.warnings.length === 0) return void 0;
+	process.stderr.write(`\n${NAME}: installation rejected: ${refused.warnings.join("\n")}\n${NAME}: nothing was installed.\n`);
+	for (const { name, version, runtimeVersion } of refused.incompatible) process.stderr.write(`${NAME}: to accept the risk, run: ${NAME} plugin --profile ${profile} allow-version ${name}@${version} --qilin-version ${runtimeVersion} --accept-risk\n`);
+	return 1;
+}
+/**
+* Run one `qilin plugin` invocation: report or list, grant or revoke one
+* exact-version exemption, or forward to pnpm and reconcile.
+* @param profile - the profile name.
+* @param args - the subcommand and its arguments, or pnpm arguments with relative path specs anchored to the invoking directory.
+* @returns the process exit code, or 1 when a report, an exemption, or the reconcile refused the profile.
+*/
+async function runPlugin(profile, args) {
+	const dir = resolveProfileDir(profile);
+	if (args[0] === "list") return listPlugins(profile, dir);
+	if (args[0] === "doctor") try {
+		return doctorPlugin(profile, dir, args[1]);
+	} catch (error) {
+		process.stderr.write(`${error.message}\n`);
+		return 1;
+	}
+	const exemption = await exemptionCommand(profile, args);
+	if (exemption !== void 0) return exemption;
+	const refused = await refuseIncompatibleInstall(profile, dir, args);
+	if (refused !== void 0) return refused;
+	if (!existsSync(join(dir, "package.json"))) {
+		const template = PROFILE_TEMPLATES[profile];
+		initProfile(dir, template?.bundles ?? DEFAULT_PROFILE_BUNDLES);
+		process.stderr.write(`${NAME}: initialized profile ${profile} at ${dir}\n`);
+	}
+	for (const warning of readProfileCompatibility(dir).warnings) process.stderr.write(`${NAME}: warning: ${warning}\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) try {
+		reconcileProfileBundles(NAME, before, dir, INSTALL_ANCHOR);
+	} catch (error) {
+		if (!(error instanceof EngineNameCollisionError)) throw error;
+		process.stderr.write(`${error.message}\n`);
+		return 1;
+	}
+	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-DSy6PUHQ.js

@@ -0,0 +1,315 @@
+import { PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, QILIN_LAUNCH_PROFILE_KEY, boot, createProfileResolutionGeneration, healIsolatedProfileModuleFallback, healProfilesModuleFallback, initProfile, installFailLoud, loadOverlayPatches, loadProfile, loadProfileDirectory, readProfilePatches, resolveProfileDir } from "@qilin-agent/app-boot";
+import { resolveQilinHome } from "@qilin-agent/home-paths";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { installProxyFromEnvironment } from "@qilin-agent/http-proxy";
+import { QILIN_LAUNCH_ENVIRONMENT_KEY } from "@qilin-agent/launch-environment";
+import { provideCmdline } from "@qilin-agent/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 `qilin` surface: resolve the profile, stack its
+* patch layers (bundle layers in `qilin.profile.bundles` order, the profile's
+* own `cordis.patch.yml`, `--patch` overlays, the telemetry switch), mount the
+* tree over the profile's empty root config, 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 @qilin-agent/cli/profile-boot
+*/
+const NAME = "qilin";
+/** Launcher-owned readiness signal committed only after boot and host setup succeed. */
+function createAppReady() {
+	let ready = false;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		service: { onReady(listener) {
+			if (ready) {
+				listener();
+				return () => {};
+			}
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		} },
+		commit() {
+			if (ready) return;
+			ready = true;
+			for (const listener of [...listeners]) listener();
+			listeners.clear();
+		}
+	};
+}
+/**
+* The home-level user patch layer (`$QILIN_HOME/cordis.patch.yml`), applied
+* over every profile's own layer. Resolved per call, not at module load:
+* `$QILIN_HOME` may be set by the test or launcher after import.
+* @returns the absolute patch-file path.
+*/
+function homePatchPath() {
+	return join(resolveQilinHome(), PROFILE_PATCH_FILENAME);
+}
+/** Absolute path of this qilin 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 = `# qilin profile root — an empty entry list. The tree is composed as patches:
+# each bundle in package.json's qilin.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";
+/**
+* Initialize a missing profile from one shipped template. This copies only
+* the template's bundle list; local state from the
+* same-named shipped profile is not read, and no inheritance metadata is
+* persisted. Shipped profile names are reserved, and the target directory is
+* claimed exclusively so existing or concurrent state is never reused.
+* @param name - the new profile name.
+* @param fromDefaultProfile - shipped profile template to copy.
+* @param home - Harness home containing the profile directory.
+* @throws when the template is unknown, the target name is shipped, or the target directory exists.
+*/
+function initializeProfileFromDefault(name, fromDefaultProfile, home = resolveQilinHome()) {
+	const dir = resolveProfileDir(name, home);
+	const template = Object.hasOwn(PROFILE_TEMPLATES, fromDefaultProfile) ? PROFILE_TEMPLATES[fromDefaultProfile] : void 0;
+	if (template === void 0) {
+		const expected = Object.keys(PROFILE_TEMPLATES).sort().map((value) => JSON.stringify(value)).join(", ");
+		throw new Error(`${NAME}: unknown default profile ${JSON.stringify(fromDefaultProfile)}; expected one of ${expected}`);
+	}
+	if (Object.hasOwn(PROFILE_TEMPLATES, name)) throw new Error(`${NAME}: profile ${JSON.stringify(name)} is shipped and cannot be a custom profile target; omit --from-default-profile to use it`);
+	mkdirSync(dirname(dir), { recursive: true });
+	try {
+		mkdirSync(dir);
+	} catch (error) {
+		if (error.code !== "EEXIST") throw error;
+		const manifestPath = join(dir, "package.json");
+		if (existsSync(manifestPath)) throw new Error(`${NAME}: profile ${JSON.stringify(name)} already exists at ${manifestPath}; omit --from-default-profile to use it`);
+		throw new Error(`${NAME}: profile directory ${dir} already exists; choose an unused profile name`);
+	}
+	try {
+		initProfile(dir, template.bundles);
+	} catch (error) {
+		try {
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch (cleanupError) {
+			throw new AggregateError([error, cleanupError], `${NAME}: profile initialization failed and ${dir} could not be removed`);
+		}
+		throw error;
+	}
+}
+/**
+* Load a resolved profile for `name` and (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).
+* @param fromDefaultProfile - shipped template used once to initialize a missing profile.
+* @returns the loaded profile.
+* @throws when explicit initialization names an unknown template or an existing profile.
+*/
+function prepareProfile(name, userLayer = true, fromDefaultProfile) {
+	if (fromDefaultProfile !== void 0) initializeProfileFromDefault(name, fromDefaultProfile);
+	const profile = loadProfile(NAME, name, INSTALL_ANCHOR, void 0, { userLayer });
+	writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
+	return profile;
+}
+/**
+* Load `name` and compose its effective patch stack: bundle layers in
+* `qilin.profile.bundles` order (a base-backed profile gets the base bundle's
+* platform-gated shell rows), the profile's user layer, the home-level user
+* layer (`$QILIN_HOME/cordis.patch.yml` — machine-local preferences that apply
+* to every profile, so it outranks the per-profile layer), `--patch` overlays,
+* then the telemetry switch.
+* @param name - the profile name.
+* @param patchFiles - `--patch` overlay paths, in argv order.
+* @param resolutionMode - runtime lookup, disk links, or dual verification of both.
+* @param fromDefaultProfile - shipped template for a missing named profile.
+* @param resolvedProfile - application-owned profile and installation.
+* @returns the profile and its patch layers.
+*/
+async function composeProfile(name, patchFiles, resolutionMode, fromDefaultProfile, resolvedProfile) {
+	const profile = resolvedProfile?.profile ?? prepareProfile(name, true, fromDefaultProfile);
+	if (resolvedProfile !== void 0) writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
+	const resolutionOptions = {
+		installAnchor: resolvedProfile?.installAnchor ?? INSTALL_ANCHOR,
+		profile
+	};
+	if (resolvedProfile !== void 0 && resolutionMode !== "runtime") healIsolatedProfileModuleFallback(resolvedProfile);
+	return {
+		profile,
+		resolution: resolutionMode === "runtime" || resolvedProfile !== void 0 ? await createProfileResolutionGeneration(resolutionOptions) : await healProfilesModuleFallback(resolutionOptions),
+		overlays: patchFiles.flatMap((file) => loadOverlayPatches(NAME, resolve(file)))
+	};
+}
+/**
+* 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.
+* @throws after disposing startup resources; cleanup failures retain the original error.
+*/
+async function runProfile(options) {
+	const disposeProxy = await installProxyFromEnvironment(options.environment, (message) => {
+		process.stderr.write(`${NAME}: ${message}\n`);
+	});
+	const resolutionMode = process.pkg !== void 0 ? "runtime" : options.resolutionMode ?? "runtime";
+	const app = {};
+	let disposal;
+	const dispose = () => disposal ??= (async () => {
+		const failures = [];
+		for (const release of [() => app.current?.fiber.dispose(), disposeProxy]) try {
+			await release();
+		} catch (error) {
+			failures.push(error);
+		}
+		if (failures.length === 1) throw failures[0];
+		if (failures.length > 1) throw new AggregateError(failures, "qilin: profile cleanup failed");
+	})();
+	try {
+		const composed = await composeProfile(options.profile, options.patchFiles, resolutionMode, options.fromDefaultProfile, options.resolvedProfile);
+		const appReady = createAppReady();
+		const shutdown = createProcessShutdown(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 profileContext = {
+			name: options.profile,
+			...options.packageManager === void 0 ? {} : { packageManager: options.packageManager },
+			dir: composed.profile.dir,
+			patchPath: composed.profile.patchPath,
+			installAnchor: options.resolvedProfile?.installAnchor ?? INSTALL_ANCHOR,
+			startedBundles: composed.profile.layers.map((layer) => layer.packageName),
+			cwd: process.cwd(),
+			home: resolveQilinHome(),
+			overlays: composed.overlays,
+			telemetryDisabledEnv: process.env.QILIN_TELEMETRY_DISABLED
+		};
+		const ctx = await boot(NAME, rootConfig, readProfilePatches(NAME, profileContext, composed.profile), async (hostCtx) => {
+			app.current = hostCtx;
+			hostCtx.provide(QILIN_LAUNCH_PROFILE_KEY, {
+				name: composed.profile.name,
+				dir: composed.profile.dir,
+				home: resolveQilinHome(),
+				installAnchor: profileContext.installAnchor,
+				builtInBundles: [...PROFILE_TEMPLATES[options.profile]?.bundles ?? []]
+			});
+			hostCtx.provide("profileContext", profileContext);
+			hostCtx.provide(QILIN_LAUNCH_ENVIRONMENT_KEY, options.environment);
+			await hostCtx.plugin(PluginPackages, resolutionMode === "link" ? {} : {
+				generation: composed.resolution,
+				behavior: resolutionMode === "dual" ? "verify" : "enforce",
+				recompute: async () => createProfileResolutionGeneration({
+					installAnchor: profileContext.installAnchor,
+					profile: options.resolvedProfile === void 0 ? loadProfile(NAME, options.profile, profileContext.installAnchor) : loadProfileDirectory(NAME, options.resolvedProfile.profile.dir, profileContext.installAnchor)
+				})
+			});
+			provideCmdline(hostCtx, {
+				args: options.args,
+				exit: (code) => void shutdown.shutdown(code),
+				ready: appReady.service
+			});
+		});
+		app.current = ctx;
+		if (!signalShutdown.signal.aborted && ctx.fiber.state === 2 && ctx.get("loader") !== void 0) appReady.commit();
+		return {
+			ctx,
+			shutdown
+		};
+	} catch (error) {
+		try {
+			await dispose();
+		} catch (cleanupError) {
+			throw new AggregateError([error, cleanupError], "qilin: profile startup and cleanup failed");
+		}
+		throw error;
+	}
+}
+//#endregion
+export { prepareProfile as a, initializeProfileFromDefault as i, PROFILE_ROOT_FILENAME as n, runProfile as o, homePatchPath as r, INSTALL_ANCHOR as t };

package/lib/profile-boot.js

@@ -0,0 +1,2 @@
+import { a as prepareProfile, i as initializeProfileFromDefault, n as PROFILE_ROOT_FILENAME, o as runProfile, r as homePatchPath, t as INSTALL_ANCHOR } from "./profile-boot-DSy6PUHQ.js";
+export { INSTALL_ANCHOR, PROFILE_ROOT_FILENAME, homePatchPath, initializeProfileFromDefault, prepareProfile, runProfile };

package/lib/types/args.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Commander adapter for the `qilin` command line.
+ *
+ * The launcher parses only what it owns — which profile to boot, which extra
+ * patch overlays to apply, and the config dumps — and hands **everything after
+ * its own flags** to the booted tree verbatim, where injected app plugins parse
+ * their own flag families and print their own `--help` (see
+ * `@qilin-agent/cmdline`). Launcher flags therefore come first: the first
+ * token this parser does not recognize starts the inner arguments, so
+ * `qilin --profile tui --resume abc` boots the tui profile with `--resume abc`,
+ * and `qilin --profile web -h` prints the web app's help, not this one's.
+ *
+ * `qilin <name>` abbreviates `qilin --profile <name>`; `plugin` manages a profile's
+ * plugin dependencies by forwarding to pnpm.
+ * @module @qilin-agent/cli/args
+ */
+/** Boot a named profile and hand it the invocation's inner arguments. */
+interface ProfileInvocation {
+    mode: 'profile';
+    profile: string;
+    /** Shipped template used once to initialize a missing profile. */
+    fromDefaultProfile?: string | undefined;
+    /** Extra patch-list overlays applied after the profile's own layer, in argv order. */
+    patches: string[];
+    /** Everything after the launcher's own flags, verbatim, for injected app plugins. */
+    args: string[];
+}
+/** Print a composed profile tree and exit without booting. */
+interface DumpConfigInvocation {
+    mode: 'dump-config';
+    profile: string;
+    /** Shipped template used once to initialize a missing profile. */
+    fromDefaultProfile?: string | undefined;
+    /** Omit the profile's user layer and --patch overlays; print bundle layers only. */
+    defaultOnly: boolean;
+    patches: string[];
+}
+/** Manage a profile's plugins: forward `args` to pnpm inside the profile directory. */
+interface PluginInvocation {
+    mode: 'plugin';
+    profile: string;
+    /** Raw pnpm arguments, verbatim. */
+    args: string[];
+}
+/** The resolved `qilin` invocation. Help, version, and errors exit inside {@link parseQilinArgs}. */
+export type QilinInvocation = ProfileInvocation | DumpConfigInvocation | PluginInvocation;
+/**
+ * Resolve argv into one invocation, or print and exit for help, version, or an
+ * error.
+ * @param argv - arguments after the Node binary and script.
+ * @param version - version string printed by `--version`.
+ * @returns the resolved invocation.
+ */
+export declare function parseQilinArgs(argv: readonly string[], version: string): QilinInvocation;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/lib/types/bin.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Command-line entry for qilin.
+ * @module @qilin-agent/cli/bin
+ */
+/**
+ * Run the public qilin command-line interface.
+ * @returns a promise that settles when the selected command mode finishes.
+ */
+export declare function runCli(): Promise<void>;
+//# sourceMappingURL=bin.d.ts.map

package/lib/types/dump-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Config-dump entry for `qilin --profile <name> --dump-config`: compose the
+ * profile's patch layers through the include plugin's patch algorithm without
+ * booting or evaluating `!!js`, with one source layer per bundle, the
+ * profile's own patch file, and each `--patch` overlay.
+ * @module @qilin-agent/cli/dump-config
+ */
+/**
+ * Print a profile composition with comments naming each source file and patch layer.
+ * @param profile - the profile name.
+ * @param defaultOnly - omit the profile's user layer and `--patch` overlays
+ * (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
+ * never parsed).
+ * @param patches - `--patch` overlay paths, in argv order.
+ * @param fromDefaultProfile - shipped template used once to initialize a missing profile.
+ */
+export declare function runDumpConfig(profile: string, defaultOnly: boolean, patches: readonly string[], fromDefaultProfile?: string): void;
+//# sourceMappingURL=dump-config.d.ts.map

package/lib/types/plugin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `qilin plugin [--profile <name>] <args...>` — profile plugin management.
+ *
+ * `list` and `doctor` are the launcher's own verbs and never mutate anything:
+ * `list` prints the profile's bundle layers, and `doctor` reports one plugin
+ * package's DSH-era compatibility. `version-exemptions`, `allow-version`, and
+ * `revoke-version` read and write the profile's own `compatibility.json` under
+ * its file lock and never become pnpm arguments. Every other argument list
+ * forwards to pnpm in the profile directory: refuse the packages it names that
+ * the running runtime version rejects, initialize the profile on first use, run
+ * `pnpm <args...>`, then reconcile the `qilin.profile.bundles` layer list
+ * against the installed state (a dependency resolving to a package that
+ * declares `qilin.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 `qilin.bundle`
+ * declaration in a newer version. A profile that installed an upstream DSH-era
+ * engine package is refused before any layer changes, with the removal command
+ * in the diagnostic.
+ * @module @qilin-agent/cli/plugin
+ */
+/**
+ * Run one `qilin plugin` invocation: report or list, grant or revoke one
+ * exact-version exemption, or forward to pnpm and reconcile.
+ * @param profile - the profile name.
+ * @param args - the subcommand and its arguments, or pnpm arguments with relative path specs anchored to the invoking directory.
+ * @returns the process exit code, or 1 when a report, an exemption, or the reconcile refused the profile.
+ */
+export declare function runPlugin(profile: string, args: readonly string[]): Promise<number>;
+//# sourceMappingURL=plugin.d.ts.map