@chatcode/chatcode-cli-test 1.0.47 → 3.0.1

package/lib/profile-boot-DNB5by4u.js

@@ -0,0 +1,307 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PluginPackages, boot, createProfileResolutionGeneration, healIsolatedProfileModuleFallback, healProfilesModuleFallback, initProfile, installFailLoud, loadOverlayPatches, loadProfile, readProfilePatches, resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
+import { resolveChatCodeCliHome } 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";
+//#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 ChatCode CLI 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 @chatcode/chatcode-cli/profile-boot
+*/
+const NAME = "ChatCode CLI";
+/** 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 (`$CHATCODE_CLI_HOME/cordis.patch.yml`), applied
+* over every profile's own layer. Resolved per call, not at module load:
+* `$CHATCODE_CLI_HOME` may be set by the test or launcher after import.
+* @returns the absolute patch-file path.
+*/
+function homePatchPath() {
+	return join(resolveChatCodeCliHome(), PROFILE_PATCH_FILENAME);
+}
+/** Absolute path of this ChatCode CLI 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 = `# ChatCode CLI 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 = resolveChatCodeCliHome()) {
+	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, {
+		pluginCommand: "chatcode-cli",
+		userLayer
+	});
+	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 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, "ChatCode CLI: 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: resolveChatCodeCliHome(),
+			overlays: composed.overlays,
+			telemetryDisabledEnv: process.env.CHATCODE_CLI_TELEMETRY_DISABLED ?? 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) {
+		try {
+			await dispose();
+		} catch (cleanupError) {
+			throw new AggregateError([error, cleanupError], "ChatCode CLI: 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-DNB5by4u.js";
+export { INSTALL_ANCHOR, PROFILE_ROOT_FILENAME, homePatchPath, initializeProfileFromDefault, prepareProfile, runProfile };

package/lib/types/args.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Commander adapter for the ChatCode CLI launcher.
+ *
+ * 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
+ * `chatcode-cli --profile cli --resume abc` boots the cli profile with
+ * `--resume abc`, and `chatcode-cli --profile web -h` prints the web app's
+ * help, not this one's.
+ *
+ * `chatcode-cli <name>` abbreviates `chatcode-cli --profile <name>`; `plugin`
+ * manages a profile's plugin dependencies by forwarding to pnpm. A bare
+ * public launcher boots `$CHATCODE_CLI_DEFAULT_PROFILE`, then legacy
+ * `$DSH_DEFAULT_PROFILE`, else the builtin `cli` profile.
+ * @module @chatcode/chatcode-cli/args
+ */
+/** Environment variables controlling the bare-launcher default profile. */
+export declare const DEFAULT_PROFILE_ENV = "CHATCODE_CLI_DEFAULT_PROFILE";
+export declare const LEGACY_DEFAULT_PROFILE_ENV = "DSH_DEFAULT_PROFILE";
+/** Builtin profile selected by a bare `chatcode-cli` or `cco` invocation. */
+export declare const BUILTIN_DEFAULT_PROFILE = "cli";
+/** Resolve the bare-launcher profile with canonical-before-legacy precedence. */
+export declare function resolveDefaultProfile(env?: Record<string, string | undefined>): string;
+/** 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[];
+}
+/** Plan or explicitly apply a copy-only migration from legacy user directories. */
+interface MigrationInvocation {
+    mode: 'migrate';
+    apply: boolean;
+    json: boolean;
+}
+/** The resolved ChatCode CLI invocation. Help, version, and errors exit during parsing. */
+export type ChatCodeCliInvocation = ProfileInvocation | DumpConfigInvocation | PluginInvocation | MigrationInvocation;
+/** @deprecated Use {@link ChatCodeCliInvocation}. */
+export type DshInvocation = ChatCodeCliInvocation;
+/**
+ * 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 parseChatCodeCliArgs(argv: readonly string[], version: string): ChatCodeCliInvocation;
+/** @deprecated Use {@link parseChatCodeCliArgs}. */
+export declare const parseDshArgs: typeof parseChatCodeCliArgs;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/lib/types/bin.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * Command-line entry for ChatCode CLI and its compatibility aliases.
+ * @module @chatcode/chatcode-cli/bin
+ */
+/**
+ * Set the canonical process identity shared by all launcher aliases.
+ */
+export declare function initializeProcessIdentity(): void;
+/**
+ * Run the public ChatCode CLI 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/home-migration.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Copy-only migration from the legacy ~/.dsh tree into ChatCode CLI home.
+ * @module @chatcode/chatcode-cli/home-migration
+ */
+export declare const HOME_MIGRATION_VERSION = 1;
+export declare const LEGACY_HOME_DIRECTORY = ".dsh";
+export declare const LEGACY_TUI_HOME_DIRECTORY = ".dsh-tui";
+export declare const MIGRATION_RECORD_DIRECTORY = "migration/chatcode-cli-home-v1";
+export type MigrationEntryAction = 'copy-file' | 'create-directory' | 'skip-existing' | 'exclude-transient' | 'skip-unsafe' | 'skip-unreadable';
+export interface HomeMigrationEntry {
+    relativePath: string;
+    action: MigrationEntryAction;
+    kind: 'file' | 'directory' | 'symlink' | 'other';
+    reason?: string;
+    size?: number;
+    mtimeMs?: number;
+    /** SHA-256 of a readable source file, used to detect same-size content changes. */
+    fingerprint?: string;
+}
+export interface HomeMigrationPlan {
+    version: typeof HOME_MIGRATION_VERSION;
+    source: string;
+    destination: string;
+    sourceExists: boolean;
+    entries: HomeMigrationEntry[];
+    conflicts: string[];
+    excluded: string[];
+    planId: string;
+}
+export interface HomeMigrationResult {
+    plan: HomeMigrationPlan;
+    copied: string[];
+    createdDirectories: string[];
+    skipped: Array<{
+        relativePath: string;
+        reason: string;
+    }>;
+    recordPath?: string;
+}
+export interface HomeMigrationRoots {
+    source: string;
+    destination: string;
+    tuiSource: string;
+    tuiDestination: string;
+}
+/** Classify state that must never be migrated because it is runtime-local or transient. */
+export declare function isTransientMigrationPath(relativePath: string, kind: HomeMigrationEntry['kind']): boolean;
+/** Resolve the fixed legacy source and the canonical migration destination. */
+export declare function resolveHomeMigrationRoots(env?: Record<string, string | undefined>): HomeMigrationRoots;
+/** Find legacy trees with durable entries that are still absent from the canonical home. */
+export declare function detectPendingHomeMigrations(roots: HomeMigrationRoots): Promise<HomeMigrationPlan[]>;
+/** Inspect both trees and return a deterministic, side-effect-free migration plan. */
+export declare function planHomeMigration(source: string, destination: string): Promise<HomeMigrationPlan>;
+/** Apply exactly one reviewed plan without overwriting destinations or removing legacy data. */
+export declare function applyHomeMigration(plan: HomeMigrationPlan): Promise<HomeMigrationResult>;
+/** Human-readable review output shared by dry-run and apply. */
+export declare function formatHomeMigrationPlan(plan: HomeMigrationPlan): string;
+//# sourceMappingURL=home-migration.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 ChatCode CLI 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 @chatcode/chatcode-cli/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 (`$CHATCODE_CLI_HOME/cordis.patch.yml`), applied
+ * over every profile's own layer. Resolved per call, not at module load:
+ * `$CHATCODE_CLI_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 ChatCode CLI 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