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

package/lib/types/index.d.ts

@@ -5,18 +5,21 @@
  * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.
  * @module @deepseek-ai/dsh-app-boot
  */
-import { Context } from '@deepseek-ai/cordis';
+import { Context, type FiberState } from '@deepseek-ai/cordis';
 import { type Entry } from '@deepseek-ai/cordis-plugin-loader';
 import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { type LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment';
+export { readProfilePatches, resolveTelemetryPatch, type ProfileContext, type ProfilePnpmInvocation } from './profile-context.ts';
+export { sanitizeProfile } from './profile-sanitize.ts';
+export { readProfilePlugins, reconcileProfilePlugins, writeProfileBundles, type ProfilePluginLocation, type ProfilePluginDependency, type ProfilePluginInventory, type ProfilePluginReconciliation, } from './profile-plugins.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** Harness-home path resolver available to Loader `!!js` config expressions. */
         dshHomePath?: typeof dshHomePath;
     }
 }
-export { composeEntries, createProfileResolutionGeneration, DEFAULT_PROFILE_BUNDLES, DEFAULT_PROFILE_PATCH_RELOAD, healProfilesModuleFallback, initProfile, loadProfile, loadProfileDirectory, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PROFILES_DIR, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest, type Profile, type ProfileLayer, type ProfileManifest, type ProfileModuleFallbackOptions, type ProfileResolutionEntry, type ProfileResolutionGeneration, type ProfileResolutionMode, type ProfileTemplate, } from './profile.ts';
+export { composeEntries, createProfileResolutionGeneration, DEFAULT_PROFILE_BUNDLES, OPTIONAL_BUNDLES, healProfilesModuleFallback, healIsolatedProfileModuleFallback, unlinkProfileModuleFallback, initProfile, loadProfile, loadProfileDirectory, PROFILE_PATCH_FILENAME, PROFILE_TEMPLATES, PROFILES_DIR, readProfileManifest, resolveBundleDir, resolveProfileDir, writeProfileManifest, type Profile, type ProfileLayer, type ProfileManifest, type ProfileModuleFallbackOptions, type ProfileResolutionEntry, type ProfileResolutionGeneration, type ProfileResolutionMode, type ProfileTemplate, } from './profile.ts';
 export { PluginPackages, type PluginPackage, type PluginPackagesConfig, } from './profile-resolution/service.ts';
 /**
  * Resolve the config to boot. Replay swaps a `cordis.yml` basename for
@@ -48,29 +51,14 @@ export declare function loadEnv(binName: string, dir?: string, warn?: (line: str
  * @throws when either file declares a bootstrap-only variable, except {@link HOME_LAYER_PROXY_NAMES} in the Harness-home file.
  */
 export declare function loadLayeredEnv(binName: string, cwd?: string, warn?: (line: string) => void): LaunchEnvironmentSnapshot;
-/** Options for live user patch-layer reconciliation. */
-export interface UserPatchWatchOptions {
-    /** Diagnostic prefix used by {@link loadOptionalPatches}. */
-    binName: string;
-    /** Absolute path of the watched patch file (a profile's `cordis.patch.yml`). */
-    filename: string;
-    /**
-     * Compose the full patch list for a fresh user-layer generation —
-     * the same composition the app booted with, so a reload can interleave the
-     * new user patches between app-owned layers (bundle layers below,
-     * overlays above). Identity when omitted: the user layer
-     * is the whole patch list.
-     */
-    compose?: (userPatches: PatchOptions[]) => PatchOptions[];
-}
-/**
- * Watch the user patch layer and reapply it to the boot Include without rollback.
- * @param ctx - settled app context containing the root Include and an active HMR service.
- * @param options - diagnostic, file, and patch-composition inputs.
- * @returns an asynchronous disposer after the exact-path watcher is ready.
- * @throws when HMR or the root Include is absent, watcher setup fails, or initial path resolution fails.
+/** Apply one complete patch generation and wait for Loader activation diagnostics.
+ * @param ctx Booted root context.
+ * @param patches Complete ordered patch list.
+ * @param binName Diagnostic prefix.
+ * @param requiredIds Explicit enablement targets whose existing failures also reject reconciliation.
+ * @returns Diagnostics for unchanged pre-existing inactive entries; new or changed failures reject.
  */
-export declare function watchUserPatches(ctx: Context, options: UserPatchWatchOptions): Promise<() => Promise<void>>;
+export declare function reconcileProfilePatches(ctx: Context, patches: PatchOptions[], binName: string, requiredIds?: readonly string[]): Promise<string[]>;
 /**
  * Load an optional patch-list file: a top-level YAML array of loader patch
  * entries (`@deepseek-ai/cordis-plugin-include`'s `PatchOptions`): id-targeted config
@@ -196,19 +184,63 @@ export declare const FAIL_LOUD_RELEASE_TIMEOUT_MS = 2000;
  * @returns the uninstaller that removes the rejection handler.
  */
 export declare function installFailLoud(binName: string, proc?: FailLoudProcess, release?: () => Promise<void> | void): () => void;
+interface InactiveEntry {
+    /** Loader entry used to identify the bootstrap Include and required ids. */
+    entry: Entry;
+    /** Activation errors and missing services remain distinct for presentation. */
+    outcome: {
+        kind: 'failed';
+        error: unknown;
+        phase?: string;
+    } | {
+        kind: 'pending';
+        missing: string[];
+    };
+}
+/** Inactive plugin metadata without retaining its Context or Fiber. */
+interface StartupEntryDiagnostic {
+    id: string;
+    module: string;
+    required: boolean;
+    fiberState: FiberState | undefined;
+    outcome: InactiveEntry['outcome'];
+}
+/** Startup warning or error arguments, including import errors with no Fiber. */
+interface StartupLogRecord {
+    ts: number;
+    name: string;
+    type: string;
+    args: readonly unknown[];
+}
+/** Startup audit failure with non-enumerable metadata and original failures as its cause. */
+export declare class StartupError extends Error {
+    readonly entries: readonly StartupEntryDiagnostic[];
+    /** Root configuration and startup logs, attached by boot after disposal. */
+    startup?: {
+        configurationPath: string;
+        messages: readonly StartupLogRecord[];
+    };
+    /**
+     * @param message - concise terminal diagnostic.
+     * @param entries - inactive plugin metadata and original failure values.
+     */
+    constructor(message: string, entries: readonly StartupEntryDiagnostic[]);
+}
 /**
  * Apply DSH startup policy to a settled Loader tree.
  *
  * Inactive entries from the global required list reject startup. Other
- * inactive entries produce one warning and leave successful siblings running.
+ * inactive entries join that failure diagnostic, or produce one warning when
+ * no required entry failed and leave successful siblings running.
  * Required ids absent from the tree, and disabled required entries, are ignored.
  * A throwing disabled expression is an entry failure, not a disabled entry.
  * The bootstrap Include must activate so unreadable or invalid root config is fatal.
  * @param ctx - the settled context whose Loader entries to audit.
- * @param binName - the diagnostic prefix on optional-entry warnings.
+ * @param binName - the prefix on startup diagnostics.
  * @param warn - sink for optional-entry warnings.
  * @returns after optional warnings if required startup checks pass.
- * @throws when the bootstrap Include or a required entry is inactive or its disabled expression throws.
+ * @throws {@link StartupError} when the bootstrap Include or a required entry is inactive or its disabled expression throws;
+ * its message includes optional failures too.
  */
 export declare function auditStartupEntries(ctx: Context, binName: string, warn?: (line: string) => void): Promise<void>;
 /**
@@ -236,7 +268,8 @@ export declare function auditStartupEntries(ctx: Context, binName: string, warn?
  * complete plugin set.
  * @returns the root context after the initial startup audit, or as soon as a
  * surface disposed the tree while startup was still in flight.
- * @throws a labelled error after disposing the partial context — `host
+ * @throws {@link StartupError} for an inactive required entry, including all inactive plugins in its message;
+ * otherwise a labelled error after disposing the partial context — `host
  * preparation failed` when `prepare` threw before any config-tree entry
  * mounted, `plugin tree failed to load` afterwards. Cyclic causes terminate
  * diagnostic traversal without replacing the original cause.

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

@@ -0,0 +1,51 @@
+import { type Profile } from './profile.ts';
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include';
+/** Application-owned package manager executable; environment applies only to package operations. */
+export interface ProfilePnpmInvocation {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+/** Current profile facts; scheduling and mutation belong to their callers. */
+export interface ProfileContext {
+    readonly name: string;
+    /** Packaged applications supply their bundled runtime instead of a PATH executable. */
+    readonly packageManager?: ProfilePnpmInvocation;
+    readonly dir: string;
+    readonly patchPath: string;
+    readonly installAnchor: string;
+    readonly cwd: string;
+    readonly home: string;
+    /** Bundle packages used to start this process, before any persisted edits. */
+    readonly startedBundles: readonly string[];
+    /** Parsed command-line overlays, applied above profile and home patches. */
+    readonly overlays: readonly PatchOptions[];
+    /** Launch-time DSH_TELEMETRY_DISABLED value; any non-empty value opts out. */
+    readonly telemetryDisabledEnv: string | undefined;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Present only in a profile launched by dsh. */
+        profileContext: ProfileContext;
+    }
+}
+/**
+ * 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.
+ */
+export declare function resolveTelemetryPatch(disabledEnv: string | undefined, hasRow: boolean): PatchOptions | undefined;
+/** Read current bundle and user layers with the launch-time overlays.
+ * @param binName Diagnostic prefix for malformed or missing configuration.
+ * @param context Data supplied by the profile launcher.
+ * @param initialProfile Already loaded startup profile; omitted reads the current files.
+ * @returns Detached ordered patches; this function does not update the Loader.
+ */
+export declare function readProfilePatches(binName: string, context: ProfileContext, initialProfile?: Profile): PatchOptions[];
+//# sourceMappingURL=profile-context.d.ts.map

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

@@ -0,0 +1,60 @@
+/** Installed profile dependencies and their bundle activation after package-manager operations. */
+import { type ProfileManifest } from './profile.ts';
+/** Profile directory and installation used by the shared bundle resolver. */
+export interface ProfilePluginLocation {
+    /** Diagnostic prefix for profile manifest failures. */
+    readonly binName: string;
+    /** Profile package directory managed by pnpm. */
+    readonly profileDir: string;
+    /** Absolute package.json path of the owning dsh installation. */
+    readonly installAnchor: string;
+}
+/** One dependency under its package-manager key, including npm aliases. */
+export interface ProfilePluginDependency {
+    /** Dependency key used in package.json and the bundle list. */
+    readonly name: string;
+    /** Installed version, or the dependency spec when installed metadata is unavailable. */
+    readonly version: string;
+    /** Whether the package selected by the bundle resolver declares a patch. */
+    readonly bundle: boolean;
+    /** Whether the dependency appears in the profile's active bundle list. */
+    readonly enabled: boolean;
+}
+/** Profile manifest and dependencies in manifest order. */
+export interface ProfilePluginInventory {
+    readonly manifest: ProfileManifest;
+    readonly dependencies: readonly ProfilePluginDependency[];
+}
+/** Result of reconciling bundle activation after a successful package operation. */
+export interface ProfilePluginReconciliation {
+    readonly plugins: ProfilePluginInventory;
+    /** Newly added ordinary dependencies, for optional caller-owned diagnostics. */
+    readonly addedPlainDependencies: readonly string[];
+}
+/**
+ * Read installed versions and bundle declarations without requiring loadable plugin code.
+ * Missing or unreadable installed metadata leaves the dependency visible for repair or removal.
+ * @param location - profile and installation resolution inputs.
+ * @returns dependency records in package.json order and the profile manifest.
+ */
+export declare function readProfilePlugins(location: ProfilePluginLocation): ProfilePluginInventory;
+/**
+ * Write a bundle list while preserving the supplied profile's other metadata.
+ * @param profileDir - directory whose package.json is updated.
+ * @param manifest - current profile manifest, read after the package operation when applicable.
+ * @param bundles - ordered active bundle names, including any template entries.
+ * @returns the written manifest.
+ */
+export declare function writeProfileBundles(profileDir: string, manifest: ProfileManifest, bundles: readonly string[]): ProfileManifest;
+/**
+ * Reconcile installed bundle declarations after a successful package-manager operation.
+ * Dependency-managed entries disappear when removed or when their package loses its declaration;
+ * template entries retain their order and duplicates. New bundle dependencies activate automatically.
+ * @param options - location, inventory captured before pnpm, and whether explicitly disabled bundles remain disabled.
+ * @returns updated inventory and newly added ordinary dependencies for caller-owned warnings.
+ */
+export declare function reconcileProfilePlugins(options: ProfilePluginLocation & {
+    readonly before: ProfilePluginInventory;
+    readonly preserveDisabled: boolean;
+}): ProfilePluginReconciliation;
+//# sourceMappingURL=profile-plugins.d.ts.map

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

@@ -0,0 +1,13 @@
+/** Filesystem recovery for callers that own profile shutdown and write exclusion. */
+/**
+ * Back up the profile patch and retain only the caller's recovery bundles.
+ * The caller must stop the profile and exclude concurrent profile writes.
+ * Installed packages and other manifest fields are preserved; patches are never parsed.
+ * Failures propagate and may leave completed changes in place for a retry.
+ * @param binName - Diagnostic prefix for invalid profile manifests.
+ * @param profileDir - Profile directory to recover without loading its plugins.
+ * @param bundles - Ordered bundles to enable after recovery.
+ * @returns Backup path with a Unix millisecond timestamp and optional collision ordinal, or undefined if absent.
+ */
+export declare function sanitizeProfile(binName: string, profileDir: string, bundles: readonly string[]): string | undefined;
+//# sourceMappingURL=profile-sanitize.d.ts.map

package/lib/types/profile.d.ts

@@ -24,7 +24,7 @@
  */
 import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader';
 import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
-import type { DshPackageManifest, ProfilePatchReload } from '@deepseek-ai/dsh-package-manifest';
+import type { DshPackageManifest } from '@deepseek-ai/dsh-package-manifest';
 /** Directory under the Harness home holding every profile. */
 export declare const PROFILES_DIR = "profiles";
 /** The user patch layer inside a profile directory (hot-reloaded on long-lived surfaces). */
@@ -33,8 +33,6 @@ export declare const PROFILE_PATCH_FILENAME = "cordis.patch.yml";
 export interface ProfileTemplate {
     /** Ordered bundle layer list. */
     bundles: readonly string[];
-    /** User patch-file lifecycle for the generated profile. */
-    patchReload: ProfilePatchReload;
 }
 /** Package metadata accepted by the profile reader; local profiles need no published identity. */
 export type ProfileManifest = Partial<DshPackageManifest>;
@@ -61,8 +59,6 @@ export interface Profile {
     patchPath: string;
     /** The profile's own patches; empty when the file is absent. */
     patches: PatchOptions[];
-    /** Whether the launcher watches user patch files after boot. */
-    patchReload: ProfilePatchReload;
 }
 /** One package selected by the profile module-fallback rules. */
 export interface ProfileResolutionEntry {
@@ -101,17 +97,21 @@ export declare function resolveProfileDir(name: string, home?: string): string;
 export declare const PROFILE_TEMPLATES: Record<string, ProfileTemplate>;
 /** The bundle list a `dsh plugin` init uses for a name with no shipped template. */
 export declare const DEFAULT_PROFILE_BUNDLES: readonly string[];
-/** Custom profiles retain the historical live patch-file behavior. */
-export declare const DEFAULT_PROFILE_PATCH_RELOAD: ProfilePatchReload;
+/**
+ * The bundles the dsh installation ships for a person to switch on: each a
+ * runtime dependency of the installation that declares `dsh.bundle.patch`,
+ * selected by no shipped template, and offered switched off by the plugin
+ * manager ([rationale](../../../../.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md)).
+ */
+export declare const OPTIONAL_BUNDLES: readonly string[];
 /**
  * Initialize a profile directory: manifest, empty user patch layer, and the
  * pnpm settings out-of-tree plugins need. Existing files are never touched,
  * so re-running is a no-op on an initialized profile.
  * @param dir - the profile directory from {@link resolveProfileDir}.
  * @param bundles - the initial `dsh.profile.bundles` layer list.
- * @param patchReload - user patch-file lifecycle; custom profiles default to live reload.
  */
-export declare function initProfile(dir: string, bundles: readonly string[], patchReload?: ProfilePatchReload): void;
+export declare function initProfile(dir: string, bundles: readonly string[]): void;
 /** Inputs for {@link healProfilesModuleFallback}. */
 export interface ProfileModuleFallbackOptions {
     /** Absolute package.json path of the running dsh installation. */
@@ -142,6 +142,22 @@ export declare function healProfilesModuleFallback(options: ProfileModuleFallbac
  * @returns the complete immutable generation.
  */
 export declare function createProfileResolutionGeneration(options: Omit<ProfileModuleFallbackOptions, 'materialize'>): Promise<ProfileResolutionGeneration>;
+/**
+ * Supply an application-owned profile with filesystem packages from its installation and selected bundles.
+ * All fallback links belong to the profile; no shared Harness-home directory is written.
+ * Existing pnpm-managed packages remain authoritative. The caller serializes profile mutations.
+ * @param options - owning installation package.json and the loaded application profile.
+ */
+export declare function healIsolatedProfileModuleFallback(options: {
+    installAnchor: string;
+    profile: Profile;
+}): void;
+/**
+ * Detach this profile's fallback links before a package-manager mutation.
+ * Installed packages and links replaced by pnpm remain untouched; the next profile launch restores fallbacks.
+ * @param profileDir - profile directory whose package mutation is serialized by the caller.
+ */
+export declare function unlinkProfileModuleFallback(profileDir: string): void;
 /**
  * Read a profile's manifest.
  * @param binName - the diagnostic prefix on the thrown error.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-app-boot",
   "description": "Shared boot glue for the app bins: .env loading, fail-loud Loader guards, snapshot-aware config resolution, and the Loader boot sequence",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,38 +32,30 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "chokidar": "4.0.3",
     "js-yaml": "^4.2.0",
     "node-addon-require-builtin": "^0.1.6",
     "resolve.exports": "^2.0.3",
-    "@deepseek-ai/dsh-atomic-write": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-package-manifest": "^0.1.6-alpha.1"
+    "@deepseek-ai/dsh-atomic-write": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-package-manifest": "^0.1.6-alpha.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis-plugin-group": "^1.0.2",
-    "@deepseek-ai/cordis-plugin-hmr": "^1.0.17",
     "@deepseek-ai/cordis-plugin-include": "^1.0.7",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-home-paths": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2"
-  },
-  "peerDependenciesMeta": {
-    "@deepseek-ai/cordis-plugin-hmr": {
-      "optional": true
-    }
+    "@deepseek-ai/dsh-launch-environment": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.6-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@deepseek-ai/cordis-plugin-group": "^1.0.2",
-    "@deepseek-ai/cordis-plugin-hmr": "^1.0.17",
     "@deepseek-ai/cordis-plugin-include": "^1.0.7",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
     "@deepseek-ai/cordis-plugin-timer": "^1.1.4",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-home-paths": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-launch-environment": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.6-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2"
   }
 }

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

@@ -1,13 +0,0 @@
-import { type ChokidarOptions } from 'chokidar';
-import type { Context } from '@deepseek-ai/cordis';
-/**
- * Watch one patch path, including missing parents, and serialize refresh callbacks.
- * @param ctx Context that owns watcher disposal and receives refresh failures.
- * @param filename Absolute patch-file path.
- * @param options Deployment watcher options inherited from the HMR configuration.
- * @param refresh Callback for additions, changes, and removals.
- * @returns A disposer that closes the watcher and drains its current refresh.
- * @throws When path resolution, watcher startup, or effect registration fails.
- */
-export declare function watchConfig(ctx: Context, filename: string, options: ChokidarOptions, refresh: () => Promise<void> | void): Promise<() => Promise<void>>;
-//# sourceMappingURL=watch-config.d.ts.map