@civilization/dsh 0.0.0-stage → 0.1.7-rc.2

package/lib/profile-boot-BZ2ZjNWi.js

@@ -0,0 +1,298 @@
+import { PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, boot, createRuntimeResolution, initProfile, installFailLoud, loadOverlayPatches, loadProfile, readProfilePatches, reportSkippedBundles, resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
+import { resolveDshHome } from "@deepseek-ai/dsh-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 "@deepseek-ai/dsh-http-proxy";
+import { DSH_LAUNCH_ENVIRONMENT_KEY } from "@deepseek-ai/dsh-launch-environment";
+import { provideCmdline } from "@deepseek-ai/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 @deepseek-ai/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";
+/**
+* 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 = 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}`);
+	}
+	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 });
+	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 for a missing 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-BZ2ZjNWi.js";
+export { INSTALL_ANCHOR, PROFILE_ROOT_FILENAME, homePatchPath, initializeProfileFromDefault, prepareProfile, runProfile };

package/lib/types/args.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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
+ * `@deepseek-ai/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 @deepseek-ai/dsh/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[];
+}
+/** Print declared plugin schemas without mounting the profile. */
+interface DumpConfigSchemaInvocation {
+    mode: 'dump-config-schema';
+    profile: string;
+    /** Shipped template used once to initialize a missing 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`.
+ * @returns the resolved invocation.
+ */
+export declare function parseDshArgs(argv: readonly string[], version: string): DshInvocation;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/lib/types/bin.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Command-line entry for dsh.
+ * @module @deepseek-ai/dsh/bin
+ */
+/**
+ * Run the public dsh 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-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 @deepseek-ai/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 used once to initialize a missing profile.
+ * @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 @deepseek-ai/dsh/dump-config
+ */
+import { type ConfigDumpLayer, type Profile } from '@deepseek-ai/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 used once to initialize a missing profile.
+ */
+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,7 @@
+/** Run package management for a profile.
+ * @param profile Profile name.
+ * @param args DSH exemption command or pnpm arguments relative to the invoking directory.
+ * @returns Zero on success; nonzero on invalid approval or package-manager failure.
+ */
+export declare function runPlugin(profile: string, args: readonly string[]): 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

package/lib/types/profile-boot.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 @deepseek-ai/dsh/profile-boot
+ */
+import { type Context } from '@deepseek-ai/cordis';
+import { type ProfileContext, type Profile } from '@deepseek-ai/dsh-app-boot';
+import { type LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment';
+import { type ProcessShutdown } from './process-shutdown.ts';
+/**
+ * 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.
+ */
+export declare function homePatchPath(): string;
+/** Absolute path of this dsh installation's package.json (both anchors: src/ and lib/ sit one level under apps/cli). */
+export declare const INSTALL_ANCHOR: string;
+/** Root config filename inside a profile directory. */
+export declare 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.
+ */
+export declare function initializeProfileFromDefault(name: string, fromDefaultProfile: string, home?: string): void;
+/**
+ * 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.
+ */
+export declare function prepareProfile(name: string, userLayer?: boolean, fromDefaultProfile?: string): Profile;
+/** An application-owned profile and its independent installation fallback. */
+export interface ResolvedProfileRuntime {
+    /** Profile already loaded from the application's own directory. */
+    profile: Profile;
+    /** Absolute package.json path of the application's dsh installation. */
+    installAnchor: string;
+}
+/** Options for {@link runProfile}. */
+export interface RunProfileOptions {
+    /** This run's frozen environment snapshot, provided before any entry mounts. */
+    environment: LaunchEnvironmentSnapshot;
+    /** The profile name to boot. */
+    profile: string;
+    /** Loaded application profile; bypasses named profile initialization when supplied. */
+    resolvedProfile?: ResolvedProfileRuntime | undefined;
+    /** Shipped template used once to initialize a missing profile. */
+    fromDefaultProfile?: string | undefined;
+    /** `--patch` overlay paths, in argv order. */
+    patchFiles: readonly string[];
+    /** The invocation's inner arguments, handed to the tree through `ctx.cmdlineArgs`. */
+    args: readonly string[];
+    /** Application-owned package runtime, scoped to plugin package operations. */
+    packageManager?: ProfileContext['packageManager'];
+}
+/**
+ * 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.
+ */
+export declare function runProfile(options: RunProfileOptions): Promise<{
+    ctx: Context;
+    shutdown: ProcessShutdown;
+}>;
+//# sourceMappingURL=profile-boot.d.ts.map

package/lib/types/startup-diagnostics.d.ts

@@ -0,0 +1,19 @@
+/** Save original startup diagnostics while keeping the terminal report concise. */
+import type { StartupError } from '@deepseek-ai/dsh-app-boot';
+/** Launcher-owned context; no environment values or plugin configurations are collected. */
+interface StartupDiagnosticContext {
+    home: string;
+    version: string;
+    profile: string;
+}
+/**
+ * Print the startup summary and save a private, uniquely named report under DSH_HOME/logs.
+ * Failed writes print the complete report to stderr instead of claiming a saved path.
+ * @param error - startup audit failure retaining plugin metadata and original errors.
+ * @param context - resolved Harness home, application version, and selected profile.
+ * @param write - terminal output sink; awaited before returning, defaults to stderr.
+ * @returns after saving or printing the report and completing terminal writes.
+ */
+export declare function reportStartupFailure(error: StartupError, context: StartupDiagnosticContext, write?: (text: string) => void | Promise<void>): Promise<void>;
+export {};
+//# sourceMappingURL=startup-diagnostics.d.ts.map