@deepseek-ai/dsh 0.1.6-alpha.1 → 0.1.6-alpha.2

package/lib/{profile-boot-CuwbWsnH.js → profile-boot-BNu17Y9U.js}

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, boot, composeEntries, createProfileResolutionGeneration, healProfilesModuleFallback, initProfile, installFailLoud, loadOptionalPatches, loadOverlayPatches, loadProfile, resolveProfileDir, watchUserPatches } from "@deepseek-ai/dsh-app-boot";
-import { dirname, join, resolve } from "node:path";
+import { PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, boot, createProfileResolutionGeneration, healIsolatedProfileModuleFallback, healProfilesModuleFallback, initProfile, installFailLoud, loadOverlayPatches, loadProfile, readProfilePatches, resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import { dirname, join, resolve } from "node:path";
 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";
@@ -75,8 +75,7 @@ function createProcessShutdown(dispose, forceExit = (code) => {
 * 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, apply its selected patch-reload
-* lifecycle, and wire fail-loud plus bounded shutdown.
+* 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
@@ -118,8 +117,6 @@ function homePatchPath() {
 }
 /** 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 session-telemetry row id the DSH_TELEMETRY_DISABLED switch targets. */
-const TELEMETRY_ROW_ID = "session-telemetry-otel";
 /** 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
@@ -130,7 +127,7 @@ const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tre
 const PROFILE_ROOT_FILENAME = "cordis.yml";
 /**
 * Initialize a missing profile from one shipped template. This copies only
-* the template's bundle list and patch-reload policy; local state from the
+* 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.
@@ -157,7 +154,7 @@ function initializeProfileFromDefault(name, fromDefaultProfile, home = resolveDs
 		throw new Error(`${NAME}: profile directory ${dir} already exists; choose an unused profile name`);
 	}
 	try {
-		initProfile(dir, template.bundles, template.patchReload);
+		initProfile(dir, template.bundles);
 	} catch (error) {
 		try {
 			rmSync(dir, {
@@ -171,24 +168,6 @@ function initializeProfileFromDefault(name, fromDefaultProfile, home = resolveDs
 	}
 }
 /**
-* Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
-* value (including `'0'`/`'false'`) disables: a privacy switch prefers
-* off-by-mistake over on-by-mistake. A composition without the telemetry row
-* exports nothing, so the switch is then trivially satisfied and no patch is
-* generated — custom profiles need not mount telemetry to run with the
-* switch set.
-* @param disabledEnv - the raw `DSH_TELEMETRY_DISABLED` value (`undefined` when unset).
-* @param hasRow - whether the composition carries the telemetry row.
-* @returns the disable patch, or `undefined` when no hard-disable patch is required.
-*/
-function resolveTelemetryPatch(disabledEnv, hasRow) {
-	if ((disabledEnv ?? "") === "" || !hasRow) return void 0;
-	return {
-		id: TELEMETRY_ROW_ID,
-		disabled: true
-	};
-}
-/**
 * 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
@@ -209,15 +188,6 @@ function prepareProfile(name, userLayer = true, fromDefaultProfile) {
 	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 (a base-backed profile gets the base bundle's
@@ -227,131 +197,108 @@ function allPatches(composed) {
 * 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) {
-	const profile = prepareProfile(name, true, fromDefaultProfile);
+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: INSTALL_ANCHOR,
+		installAnchor: resolvedProfile?.installAnchor ?? INSTALL_ANCHOR,
 		profile
 	};
-	const resolution = resolutionMode === "runtime" ? await createProfileResolutionGeneration(resolutionOptions) : await healProfilesModuleFallback(resolutionOptions);
-	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];
-	const telemetryPatch = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, rows.has(TELEMETRY_ROW_ID));
-	if (telemetryPatch !== void 0) composedOverlays.push(telemetryPatch);
+	if (resolvedProfile !== void 0 && resolutionMode !== "runtime") healIsolatedProfileModuleFallback(resolvedProfile);
 	return {
 		profile,
-		resolution,
-		bundlePatches,
-		homePatches,
-		overlays: composedOverlays
+		resolution: resolutionMode === "runtime" || resolvedProfile !== void 0 ? await createProfileResolutionGeneration(resolutionOptions) : await healProfilesModuleFallback(resolutionOptions),
+		overlays: patchFiles.flatMap((file) => loadOverlayPatches(NAME, resolve(file)))
 	};
 }
 /**
-* 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.
+* @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 ?? "link";
-	const composed = await composeProfile(options.profile, options.patchFiles, resolutionMode, options.fromDefaultProfile);
+	const resolutionMode = process.pkg !== void 0 ? "runtime" : options.resolutionMode ?? "runtime";
 	const app = {};
-	const appReady = createAppReady();
-	const shutdown = createProcessShutdown(async () => {
-		await app.current?.fiber.dispose();
-		await disposeProxy();
-	});
-	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)), async (hostCtx) => {
-		app.current = hostCtx;
-		hostCtx.provide(DSH_LAUNCH_ENVIRONMENT_KEY, options.environment);
-		await hostCtx.plugin(PluginPackages, resolutionMode === "link" ? {} : {
-			generation: composed.resolution,
-			behavior: resolutionMode === "dual" ? "verify" : "enforce"
+	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, 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);
 		});
-		provideCmdline(hostCtx, {
-			args: options.args,
-			exit: (code) => void shutdown.shutdown(code),
-			ready: appReady.service
+		process.on("SIGINT", () => {
+			interrupt(130);
 		});
-	});
-	app.current = ctx;
-	if (composed.profile.patchReload === "live" && !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: "@deepseek-ai/cordis-plugin-timer" });
-			await ctx.loader.create({
-				name: "@deepseek-ai/cordis-plugin-hmr",
-				config: { root: [] }
-			});
-			await ctx.loader.await();
-		}
-		await watchUserPatches(ctx, {
-			binName: NAME,
-			filename: composed.profile.patchPath,
-			compose: composeLive
+		installFailLoud(NAME, process, async () => {
+			await app.current?.fiber.dispose();
 		});
-		await watchUserPatches(ctx, {
-			binName: NAME,
-			filename: homePatchPath(),
-			compose: composeLive
+		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, resolutionMode === "link" ? {} : {
+				generation: composed.resolution,
+				behavior: resolutionMode === "dual" ? "verify" : "enforce"
+			});
+			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) {
-		suppressShutdownError(ctx, signalShutdown.signal, error);
+		try {
+			await dispose();
+		} catch (cleanupError) {
+			throw new AggregateError([error, cleanupError], "dsh: profile startup and cleanup failed");
+		}
+		throw error;
 	}
-	if (!signalShutdown.signal.aborted && ctx.fiber.state === 2 && ctx.get("loader") !== void 0) appReady.commit();
-	return {
-		ctx,
-		shutdown
-	};
 }
 //#endregion
-export { prepareProfile as a, initializeProfileFromDefault as i, PROFILE_ROOT_FILENAME as n, resolveTelemetryPatch as o, homePatchPath as r, runProfile as s, INSTALL_ANCHOR as t };
+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-BNu17Y9U.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 `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[];
+}
+/** 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 | 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.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+/**
+ * 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,7 @@
+/** Run package management for a profile.
+ * @param profile Profile name.
+ * @param args Pnpm arguments relative to the invoking directory.
+ * @returns Pnpm exit code.
+ */
+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,92 @@
+/**
+ * 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, type ProfileResolutionMode } 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'];
+    /** Module fallback backend; defaults to runtime. Plain Node callers may override it; pkg executables always use runtime. */
+    resolutionMode?: ProfileResolutionMode;
+}
+/**
+ * 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