@knyazevai/dsh 0.1.5 → 0.2.2

package/lib/plugin-CjFov5EZ.js

@@ -0,0 +1,101 @@
+import { t as INSTALL_ANCHOR } from "./profile-boot-B44a52oE.js";
+import { DEFAULT_PROFILE_BUNDLES, PROFILE_TEMPLATES, initProfile, readProfileCompatibility, resolveProfileDir } from "@knyazevai/dsh-app-boot";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { runPluginCommand, runProfilePnpm, setProfileVersionExemption } from "@knyazevai/dsh-plugin-manager/operations";
+import { withFileLock } from "@knyazevai/dsh-atomic-write";
+//#region lib/types/plugin.js
+/** Profile package management and explicit, exact-version compatibility approvals. */
+function requireDesktopProfile(dir) {
+	if (!existsSync(join(dir, "package.json"))) throw new Error("Open DeepSeek Harness Desktop once to initialize its profile, then fully quit it before running dsh plugin --profile desktop.");
+}
+/** Parse only DSH-owned commands; all other arguments remain pnpm's responsibility. */
+async function versionCommand(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 argumentsIterator = rest.values();
+		for (const argument of argumentsIterator) if (argument === "--accept-risk" && command === "allow-version" && !acceptRisk) acceptRisk = true;
+		else if (argument === "--dsh-version" && runtimeVersion === void 0) runtimeVersion = argumentsIterator.next().value;
+		else if (argument.startsWith("--dsh-version=") && runtimeVersion === void 0) runtimeVersion = argument.slice(14);
+		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: dsh plugin version-exemptions");
+		let request;
+		if (command !== "version-exemptions") {
+			if (packageVersion === void 0 || runtimeVersion === void 0) throw new Error(`usage: dsh plugin ${command} <package@version> --dsh-version <exact>${command === "allow-version" ? " --accept-risk" : ""}`);
+			request = {
+				packageVersion,
+				runtimeVersion
+			};
+		}
+		if (command === "allow-version") process.stderr.write("dsh: warning: allowing incompatible plugin versions can break the application or corrupt data. Approval applies only to the exact package and DSH versions.\n");
+		const dir = resolveProfileDir(profile);
+		if (profile !== "desktop") await mkdir(dir, { recursive: true });
+		await withFileLock(join(dir, "package.json"), async () => {
+			if (profile === "desktop") requireDesktopProfile(dir);
+			else 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(`dsh: 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(`dsh: ${command === "allow-version" ? "allowed" : "revoked"} ${request.packageVersion} for DSH ${request.runtimeVersion}\n`);
+			}
+		}, { waitMs: 12e4 });
+		return 0;
+	} catch (error) {
+		process.stderr.write(`dsh: ${String(error)}\n`);
+		return 1;
+	}
+}
+/** Run package management for a profile.
+* @param profile Profile name; Desktop's reserved profile must already be initialized by the application.
+* @param args DSH exemption command or pnpm arguments relative to the invoking directory.
+* @param packageManager Installation-owned executable and environment for pnpm operations.
+* @returns Zero on success; nonzero on invalid approval or package-manager failure.
+*/
+async function runPlugin(profile, args, packageManager) {
+	if (profile === "desktop") try {
+		requireDesktopProfile(resolveProfileDir(profile));
+	} catch (error) {
+		process.stderr.write(`dsh: ${String(error)}\n`);
+		return 1;
+	}
+	const versionResult = await versionCommand(profile, args);
+	if (versionResult !== void 0) return versionResult;
+	const dir = resolveProfileDir(profile);
+	if (existsSync(join(dir, "package.json"))) for (const warning of readProfileCompatibility(dir).warnings) process.stderr.write(`dsh: warning: ${warning}\n`);
+	const context = {
+		profile,
+		dir,
+		installAnchor: INSTALL_ANCHOR,
+		cwd: process.cwd()
+	};
+	const options = {
+		...packageManager,
+		execution: "cli",
+		outputBytes: 16384,
+		lockWaitMs: 12e4,
+		lookupTimeoutMs: 12e4,
+		onOutput: (text, stream) => {
+			process[stream].write(text);
+		}
+	};
+	const result = profile === "desktop" ? await withFileLock(join(dir, "package.json"), async () => {
+		requireDesktopProfile(dir);
+		return runProfilePnpm(context, args, options);
+	}, { waitMs: 12e4 }) : await runPluginCommand(context, args, options);
+	if (result.exitCode === 127) process.stderr.write("dsh: pnpm was not found; install pnpm and make it available on PATH.\n");
+	for (const { name, version, runtimeVersion } of result.incompatible ?? []) process.stderr.write(`dsh: to accept the risk, run: dsh plugin --profile ${profile} allow-version ${name}@${version} --dsh-version ${runtimeVersion} --accept-risk\n`);
+	if (result.exitCode !== 0) process.stderr.write(`dsh: plugin command failed; diagnostics: ${result.logPath}\n`);
+	if (result.exitCode !== 0 && args.some((argument) => /^git\+|^github:|\.git(?:#|$)/.test(argument))) process.stderr.write(`dsh: 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(resolveProfileDir(profile), "pnpm-workspace.yaml")}, then re-run\n`);
+	return result.exitCode;
+}
+//#endregion
+export { runPlugin };

package/lib/profile-boot-B44a52oE.js

@@ -0,0 +1,329 @@
+import { PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, boot, createRuntimeResolution, initProfile, installFailLoud, loadOverlayPatches, loadProfile, readProfilePatches, reportSkippedBundles, resolveProfileDir } from "@knyazevai/dsh-app-boot";
+import { resolveDshHome } from "@knyazevai/dsh-home-paths";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { installProxyFromEnvironment } from "@knyazevai/dsh-http-proxy";
+import { DSH_LAUNCH_ENVIRONMENT_KEY } from "@knyazevai/dsh-launch-environment";
+import { provideCmdline } from "@knyazevai/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, 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 @knyazevai/dsh/profile-boot
+*/
+const NAME = "dsh";
+/** 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 (`$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";
+/**
+* Replace the named custom profile with a fresh copy of 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. The new profile is assembled in a `.<name>.staging-*` directory
+* under the profiles directory and moved into place; only then is any previous
+* target directory, including its dependencies and user patch, deleted. A
+* failed move restores the previous directory; when restoring also fails, it
+* stays in the staging directory. Shipped profile names, compared without
+* case, are reserved. Concurrent replacements leave one complete copy; each
+* one either succeeds or reports the concurrent recreation.
+* @param name - the profile name to create or replace.
+* @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, another process recreates the target
+*   between the two renames, or a file-system operation fails; a restore failure is an `AggregateError`
+*   that names the staging path holding the previous profile.
+*/
+function initializeProfileFromDefault(name, fromDefaultProfile, home = resolveDshHome()) {
+	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}`);
+	}
+	const shipped = Object.keys(PROFILE_TEMPLATES).find((shippedName) => shippedName.toLowerCase() === name.toLowerCase());
+	if (shipped !== void 0) throw new Error(`${NAME}: profile ${JSON.stringify(name)} names shipped profile ${JSON.stringify(shipped)} and cannot be a custom profile target; omit --from-default-profile to use it`);
+	mkdirSync(dirname(dir), { recursive: true });
+	const staging = mkdtempSync(join(dirname(dir), `.${name}.staging-`));
+	const previous = join(staging, "previous");
+	try {
+		const fresh = join(staging, "new", name);
+		initProfile(fresh, template.bundles);
+		let moved = false;
+		try {
+			renameSync(dir, previous);
+			moved = true;
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+		try {
+			renameSync(fresh, dir);
+		} catch (error) {
+			if (existsSync(dir)) {
+				rmSync(previous, {
+					recursive: true,
+					force: true
+				});
+				throw new Error(`${NAME}: profile ${JSON.stringify(name)} was recreated concurrently at ${dir}`, { cause: error });
+			}
+			if (moved) try {
+				renameSync(previous, dir);
+			} catch (restoreError) {
+				throw new AggregateError([error, restoreError], `${NAME}: profile replacement failed and ${dir} could not be restored from ${previous}`);
+			}
+			throw error;
+		}
+	} catch (error) {
+		if (!existsSync(previous)) rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	try {
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+	} catch (error) {
+		process.stderr.write(`${NAME}: replaced profile ${JSON.stringify(name)} but could not remove ${staging}: ${String(error)}\n`);
+	}
+}
+/**
+* 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 that replaces the profile before loading it.
+* @returns the loaded profile.
+* @throws when explicit initialization names an unknown template or a shipped target.
+*/
+function prepareProfile(name, userLayer = true, fromDefaultProfile) {
+	if (fromDefaultProfile !== void 0) initializeProfileFromDefault(name, fromDefaultProfile);
+	const profile = loadProfile(NAME, name, INSTALL_ANCHOR, void 0, { userLayer });
+	reportSkippedBundles(NAME, profile);
+	writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
+	return profile;
+}
+/**
+* Load `name` and compose its effective patch stack: bundle layers in
+* `dsh.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 (`$DSH_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 fromDefaultProfile - shipped template that replaces the named profile.
+* @param resolvedProfile - application-owned profile and installation.
+* @returns the profile and its patch layers.
+*/
+async function composeProfile(name, patchFiles, fromDefaultProfile, resolvedProfile) {
+	const profile = resolvedProfile?.profile ?? prepareProfile(name, true, fromDefaultProfile);
+	if (resolvedProfile !== void 0) writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG);
+	return {
+		profile,
+		resolution: await createRuntimeResolution({
+			installAnchor: resolvedProfile?.installAnchor ?? INSTALL_ANCHOR,
+			profile
+		}),
+		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 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, "dsh: profile cleanup failed");
+	})();
+	try {
+		const composed = await composeProfile(options.profile, options.patchFiles, 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: resolveDshHome(),
+			overlays: composed.overlays,
+			telemetryDisabledEnv: process.env.DSH_TELEMETRY_DISABLED
+		};
+		const ctx = await boot(NAME, rootConfig, readProfilePatches(NAME, profileContext, composed.profile), async (hostCtx) => {
+			app.current = hostCtx;
+			hostCtx.provide("profileContext", profileContext);
+			hostCtx.provide(DSH_LAUNCH_ENVIRONMENT_KEY, options.environment);
+			await hostCtx.plugin(PluginPackages, { resolution: composed.resolution });
+			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], "dsh: 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-B44a52oE.js";
+export { INSTALL_ANCHOR, PROFILE_ROOT_FILENAME, homePatchPath, initializeProfileFromDefault, prepareProfile, runProfile };

package/lib/types/args.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Commander adapter for the `dsh` 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
+ * `@knyazevai/dsh-cmdline`). Launcher flags therefore come first: the first
+ * token this parser does not recognize starts the inner arguments, so
+ * `dsh --profile tui --resume abc` boots the tui profile with `--resume abc`,
+ * and `dsh --profile web -h` prints the web app's help, not this one's.
+ *
+ * `dsh <name>` abbreviates `dsh --profile <name>`; `plugin` manages a profile's
+ * plugin dependencies by forwarding to pnpm.
+ * @module @knyazevai/dsh/args
+ */
+/** Boot a named profile and hand it the invocation's inner arguments. */
+interface ProfileInvocation {
+    mode: 'profile';
+    profile: string;
+    /** Shipped template that replaces the named 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 that replaces the named profile. */
+    fromDefaultProfile?: string | undefined;
+    /** Omit the profile's user layer and --patch overlays; print bundle layers only. */
+    defaultOnly: boolean;
+    patches: string[];
+}
+/** Print declared plugin schemas without mounting the profile. */
+interface DumpConfigSchemaInvocation {
+    mode: 'dump-config-schema';
+    profile: string;
+    /** Shipped template that replaces the named profile. */
+    fromDefaultProfile?: string | undefined;
+    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 `dsh` invocation. Help, version, and errors exit inside {@link parseDshArgs}. */
+export type DshInvocation = ProfileInvocation | DumpConfigInvocation | DumpConfigSchemaInvocation | 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`.
+ * @param manageDesktopProfile - permit Desktop's installed carrier to manage its reserved profile's plugins.
+ * @returns the resolved invocation.
+ */
+export declare function parseDshArgs(argv: readonly string[], version: string, manageDesktopProfile?: boolean): DshInvocation;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/lib/types/bin.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Command-line entry for dsh.
+ * @module @knyazevai/dsh/bin
+ */
+import type { RunProfileOptions } from './profile-boot.ts';
+/** Installation-owned dependencies supplied by a packaged CLI launcher. */
+export type RunCliOptions = Pick<RunProfileOptions, 'packageManager'> & {
+    /** Permit plugin commands for Desktop's existing profile; reserved for its installed carrier. */
+    manageDesktopProfile?: boolean;
+};
+/**
+ * Run the public dsh command-line interface.
+ * @param options - Package runtime and Desktop profile access supplied by the installation.
+ * @returns a promise that settles when the selected command mode finishes.
+ */
+export declare function runCli(options?: RunCliOptions): Promise<void>;
+//# sourceMappingURL=bin.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * Schema-dump entry: inspect the composed profile without applying its plugins.
+ * Imports and lazy schema builders execute trusted module code.
+ * @module @knyazevai/dsh/dump-config-schema
+ */
+/**
+ * Print one JSON Schema document; incomplete collection or projection sets exitCode to 1.
+ * Profile initialization writes match the YAML dump. Plugin imports may execute
+ * top-level code, but collection never applies plugins or evaluates `!!js`.
+ * During schema generation, ordinary stdout writes are redirected to stderr.
+ * @param profile - the profile name.
+ * @param patches - overlay paths, in argv order.
+ * @param fromDefaultProfile - shipped template that replaces the profile before loading it.
+ * @returns after collection and output, with diagnostics also written to stderr.
+ */
+export declare function runDumpConfigSchema(profile: string, patches: readonly string[], fromDefaultProfile?: string): Promise<void>;
+//# sourceMappingURL=dump-config-schema.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * Config-dump entry for `dsh --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 @knyazevai/dsh/dump-config
+ */
+import { type ConfigDumpLayer, type Profile } from '@knyazevai/dsh-app-boot';
+/**
+ * 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 that replaces the profile before loading it.
+ */
+export declare function runDumpConfig(profile: string, defaultOnly: boolean, patches: readonly string[], fromDefaultProfile?: string): void;
+/**
+ * Read dump layers in bundle, profile, home, then argv order without composing them.
+ * @param loaded - prepared profile and parsed bundle and profile patches.
+ * @param defaultOnly - omit profile, home, and argv layers without reading their files.
+ * @param patches - overlay paths relative to the invoking directory, in argv order.
+ * @returns the labeled layers shared by YAML and schema dumps.
+ */
+export declare function collectConfigDumpLayers(loaded: Profile, defaultOnly: boolean, patches: readonly string[]): ConfigDumpLayer[];
+//# sourceMappingURL=dump-config.d.ts.map

package/lib/types/plugin.d.ts

@@ -0,0 +1,9 @@
+import { type ProfileContext } from '@knyazevai/dsh-app-boot';
+/** Run package management for a profile.
+ * @param profile Profile name; Desktop's reserved profile must already be initialized by the application.
+ * @param args DSH exemption command or pnpm arguments relative to the invoking directory.
+ * @param packageManager Installation-owned executable and environment for pnpm operations.
+ * @returns Zero on success; nonzero on invalid approval or package-manager failure.
+ */
+export declare function runPlugin(profile: string, args: readonly string[], packageManager?: ProfileContext['packageManager']): Promise<number>;
+//# sourceMappingURL=plugin.d.ts.map

package/lib/types/process-shutdown.d.ts

@@ -0,0 +1,20 @@
+/** Bounded, escalating process shutdown for the long-lived CLI surfaces. */
+/** Maximum grace allowed for the application tree to dispose before process exit. */
+export declare const PROCESS_SHUTDOWN_TIMEOUT_MS = 5000;
+/** Process-exit controller shared by normal completion and Unix signal handlers. */
+export interface ProcessShutdown {
+    /** Start or join graceful disposal before allowing natural completion with `code`. */
+    shutdown(code: number): Promise<void>;
+    /** Start graceful disposal followed by exit, or force exit when shutdown is already running. */
+    interrupt(code: number): void;
+}
+/**
+ * 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.
+ */
+export declare function createProcessShutdown(dispose: () => Promise<void>, forceExit?: (code: number) => void, complete?: (code: number) => void, timeoutMs?: number): ProcessShutdown;
+//# sourceMappingURL=process-shutdown.d.ts.map