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

package/lib/types/profile.d.ts

@@ -7,24 +7,22 @@
  * `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml`
  * (the user's own patch layer, applied after every bundle layer). Bundles are
  * npm packages whose manifest declares
- * `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the tree is
- * composed by applying each bundle's patch list in `dsh.profile.bundles` order over
- * an empty entry list, then the profile's own patches, then any launcher
- * layers (`--patch` files and flag-derived patches).
+ * `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` (one file, or an
+ * ordered list of files); the tree is composed by applying each bundle's patch
+ * lists in `dsh.profile.bundles` order over an empty entry list, then the
+ * profile's own patches, then any launcher layers (`--patch` files and
+ * flag-derived patches).
  *
  * Module resolution is two-anchor by construction: a bundle name resolves
  * first from the dsh installation (the launcher's own package), then from the
  * profile directory. Pnpm-managed entries in the profile's `node_modules`
- * resolve first. Dsh-owned links add packages carried only by selected
- * bundles, while `$DSH_HOME/profiles/node_modules` supplies the installation
- * dependency closure through Node's ordinary parent-walk. Plain Node uses
- * symlinks for that shared fallback; packaged executables use ESM proxies so
- * external plugins retain the installation's module instances.
+ * resolve first. The runtime resolution supplies packages carried by the
+ * installation and selected bundles to Node's ESM and CommonJS resolvers.
  * @module @deepseek-ai/dsh-app-boot/profile
  */
 import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader';
 import { type PatchOptions } from '@deepseek-ai/cordis-plugin-include';
-import type { DshPackageManifest } from '@deepseek-ai/dsh-package-manifest';
+import type { DshBundleManifest, 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). */
@@ -36,15 +34,31 @@ export interface ProfileTemplate {
 }
 /** Package metadata accepted by the profile reader; local profiles need no published identity. */
 export type ProfileManifest = Partial<DshPackageManifest>;
+/**
+ * The patch files a bundle declares, as written: one file for a string
+ * `patch`, the listed files in order for an array.
+ * @param bundle - the bundle's `dsh.bundle` declaration, as read from package.json.
+ * @returns the package-relative patch file paths in application order.
+ * @throws {Error} when `patch` is neither a string nor a list of strings.
+ */
+export declare function bundlePatchFiles(bundle: DshBundleManifest): string[];
+/**
+ * Resolve a bundle declaration to its ordered absolute patch files.
+ * @param packageDir - absolute directory of the bundle package.
+ * @param bundle - the bundle's `dsh.bundle` declaration, as read from package.json.
+ * @returns the absolute patch file paths in application order.
+ * @throws {Error} when `patch` is neither a string nor a list of strings.
+ */
+export declare function bundlePatchPaths(packageDir: string, bundle: DshBundleManifest): string[];
 /** One resolved bundle layer of a profile. */
 export interface ProfileLayer {
     /** The bundle's package name, as listed in `dsh.profile.bundles`. */
     packageName: string;
     /** Absolute directory of the resolved bundle package. */
     packageDir: string;
-    /** Absolute path of the bundle's patch file. */
-    patchPath: string;
-    /** The parsed patch list. */
+    /** Absolute paths of the bundle's patch files, in application order. */
+    patchPaths: readonly string[];
+    /** The parsed patch lists of every file, concatenated in application order. */
     patches: PatchOptions[];
 }
 /** A loaded profile: resolved bundle layers plus the user's own patch layer. */
@@ -60,8 +74,8 @@ export interface Profile {
     /** The profile's own patches; empty when the file is absent. */
     patches: PatchOptions[];
 }
-/** One package selected by the profile module-fallback rules. */
-export interface ProfileResolutionEntry {
+/** One package the runtime resolution supplies at the interception layer. */
+export interface RuntimeResolutionEntry {
     /** Bare package name. */
     readonly name: string;
     /** Package directory selected by the existing dependency traversal. */
@@ -70,22 +84,32 @@ export interface ProfileResolutionEntry {
     readonly version: string | undefined;
     /** Manifest whose dependency edge selected this package. */
     readonly declarer: string;
-    /** Whether every profile or only the active profile receives this fallback. */
+    /** Whether every profile or only the active profile receives this entry. */
     readonly scope: 'installation' | 'profile';
 }
-/** Complete immutable fallback table for one profile launch. */
-export interface ProfileResolutionGeneration {
-    /** Directory containing every profile and the shared fallback position. */
+/**
+ * A profile node_modules entry linked to a directory outside the shared profiles tree and the active profile.
+ * Importers below `realPath` use Node's real ancestor chain, with peer mappings read at each node_modules position.
+ */
+export interface LinkedRoot {
+    /** Package name of the profile `node_modules` entry, including its scope. */
+    readonly name: string;
+    /** Real directory outside the shared profiles tree and active profile; a package.json is optional. */
+    readonly realPath: string;
+}
+/** Complete immutable package table for one profile launch. */
+export interface RuntimeResolution {
+    /** Directory containing every profile; its node_modules is the interception layer. */
     readonly profilesDir: string;
-    /** Active profile directory, when bundle-only fallbacks were included. */
+    /** Active profile directory, when profile-scope entries were included. */
     readonly profileDir: string | undefined;
-    /** Profile-declared packages already installed before the fallback position. */
+    /** Profile-declared packages installed in the profile's own node_modules. */
     readonly localPackageNames: readonly string[];
-    /** Installation entries followed by bundle-only entries in precedence order. */
-    readonly entries: readonly ProfileResolutionEntry[];
+    /** Installation-scope entries followed by profile-scope entries in precedence order. */
+    readonly entries: readonly RuntimeResolutionEntry[];
+    /** Active profile links to external directories, sorted by name. */
+    readonly linkedRoots: readonly LinkedRoot[];
 }
-/** Startup backend selection for one computed profile resolution generation. */
-export type ProfileResolutionMode = 'link' | 'dual' | 'runtime';
 /**
  * Resolve a profile's directory under the Harness home.
  * @param name - the profile name (`dsh --profile <name>`).
@@ -112,52 +136,36 @@ export declare const OPTIONAL_BUNDLES: readonly string[];
  * @param bundles - the initial `dsh.profile.bundles` layer list.
  */
 export declare function initProfile(dir: string, bundles: readonly string[]): void;
-/** Inputs for {@link healProfilesModuleFallback}. */
-export interface ProfileModuleFallbackOptions {
+/**
+ * Remove the package projections a link-backend launch left in a profile.
+ * Only symlinks under the profile's `node_modules` whose target lies inside
+ * `<profile>/.dsh-module-fallback/node_modules` are unlinked, then that directory is removed;
+ * pnpm-installed packages and every other symlink stay. A profile without the directory is untouched.
+ * @param dir - the profile directory.
+ */
+export declare function removeLinkProjections(dir: string): void;
+/** Inputs for {@link createRuntimeResolution}. */
+export interface RuntimeResolutionOptions {
     /** Absolute package.json path of the running dsh installation. */
     installAnchor: string;
     /** Loaded profile whose selected bundles may carry profile-local plugins. */
     profile?: Profile;
     /** Harness home; defaults to {@link resolveDshHome}. */
     home?: string;
-    /** Whether to materialize the computed generation; defaults to true. */
-    materialize?: boolean;
 }
 /**
- * Maintain module fallbacks for one profile launch. The shared
- * `$DSH_HOME/profiles/node_modules` mirrors the dsh installation dependency
- * closure. Plain Node writes symlinks; a packaged executable writes ESM
- * proxies under a cross-process lock because operating-system links cannot
- * enter pkg's virtual filesystem. Missing packages carried only by selected
- * bundles are linked through a profile-owned directory into that profile's
- * `node_modules`; pnpm-managed entries remain authoritative, and another
- * profile's links cannot change its resolution.
+ * Compute the runtime resolution without writing module-resolution files.
  * @param options - installation anchor, optional loaded profile, and Harness home.
- * @returns the computed fallback generation after optional materialization.
- */
-export declare function healProfilesModuleFallback(options: ProfileModuleFallbackOptions): Promise<ProfileResolutionGeneration>;
-/**
- * Compute a profile resolution generation without materializing links or proxies.
- * @param options - installation anchor, profile, and optional Harness home.
- * @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.
+ * @returns the complete immutable runtime resolution.
  */
-export declare function healIsolatedProfileModuleFallback(options: {
-    installAnchor: string;
-    profile: Profile;
-}): void;
+export declare function createRuntimeResolution(options: RuntimeResolutionOptions): Promise<RuntimeResolution>;
 /**
- * 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.
+ * Identify selected bundles that did not produce a loaded layer.
+ * @param profile - loaded profile, when present.
+ * @param manifest - its parsed manifest, when present.
+ * @returns selected bundle names missing from the loaded layers, for resolution and diagnostics.
  */
-export declare function unlinkProfileModuleFallback(profileDir: string): void;
+export declare function skippedProfileBundles(profile: Profile | undefined, manifest: ProfileManifest | undefined): ReadonlySet<string>;
 /**
  * Read a profile's manifest.
  * @param binName - the diagnostic prefix on the thrown error.
@@ -188,20 +196,20 @@ export declare function resolveBundleDir(binName: string, packageName: string, i
  * Load an already initialized profile directory without resolving it through
  * the shared Harness home. This is used by application-owned profiles whose
  * package project and lifecycle belong to that application.
+ * Unreadable bundles are reported on stderr and skipped without changing the manifest.
  * @param binName - the diagnostic prefix on thrown errors.
  * @param dir - absolute profile package directory.
  * @param installAnchor - absolute path of the owning dsh app's package.json.
  * @param options - `userLayer: false` skips reading `cordis.patch.yml`.
- * @returns the resolved bundle layers and optional user patch layer.
+ * @returns the successfully loaded bundle layers and optional user patch layer.
  */
 export declare function loadProfileDirectory(binName: string, dir: string, installAnchor: string, options?: {
     userLayer?: boolean;
 }): Profile;
 /**
  * Load a profile: resolve every `dsh.profile.bundles` entry to its patch
- * layer and parse the profile's own patch file. A listed bundle without a
- * `dsh.bundle` manifest fails loud — naming a bundle-less package as a layer
- * is a misconfiguration, not "no patches".
+ * layer and parse the profile's own patch file. Unreadable bundles are reported
+ * on stderr and skipped; profile manifest and user patch errors still throw.
  * @param binName - the diagnostic prefix on thrown errors.
  * @param name - the profile name.
  * @param installAnchor - absolute path of the dsh app's package.json (first resolution anchor).