deepseek-harness/docs/subsystems/boot.md

Profile management

English | 中文

The boot package group owns launcher-provided profile access and the plugin manager. Plugin Manager documents persistence, reload and package-operation behavior.

Management records

PluginEntryId identifies one Loader entry; callers obtain it from listPlugins rather than constructing a patch id.

PluginInfo carries module identity, effective enablement and fiber phase, plus a unique patchId or a readOnlyReason.

BundleInfo carries the package name, optional installed version, selected enablement, removal availability and optional resolution error.

InstallBundleOptions.enabled defaults to true. False installs without selecting the bundle layer.

ChangeResult.changed reports a disk edit independently of application: applied, restart-required, overridden or failed. message describes the result. Optional packageResult records the pnpm exit code, bounded output, truncation flag and complete diagnostic log path.

Cordis API

Generated from source by scripts/gen-cordis-catalog.ts (verified fresh by pnpm run verify-cordis-catalog in doc-sync; regenerate with pnpm run gen-cordis-catalog) — the language sides differ only in locale-specific paired document paths. Signature blocks use a ts cordis-catalog fence and keep the original source JSDoc; dispatch modes are defined in the primer, and the framework-inherited ctx API lives in cordis-api/inherited.md.

ctx.hmr — Hmr

Hot reload service with Cordis-compatible module configuration and events.

/** Serialize a caller-owned mutation with all automatic reload paths.
 * @param operation Work that must not overlap module or configuration replacement.
 * @returns The operation result after its asynchronous work completes.
 */
runExclusive<T>(operation: () => Promise<T>): Promise<T>

/** Watch a configuration path through the same queue as module replacement.
 * @param filename Absolute path, which may not exist yet.
 * @param refresh Rebuilds configuration from its current files and awaits Loader completion.
 * @returns Disposer closing this registration and waiting for its pending refresh.
 */
async watchConfig(filename: string, refresh: () => Promise<void>): Promise<() => Promise<void>>

/** Read direct module dependency URLs from the active Node loader.
 * @param url Module URL.
 * @returns Linked module URLs, or an empty list for an uncached module.
 */
async getLinked(url: string): Promise<string[]>

Source: packages/boot/hmr/src/index.ts

ctx.pluginManager — PluginManager

Manage profile files and apply their declared reload lifecycle.

/** Read current plugins, including why a row cannot be changed through the profile patch.
 * @returns Current runtime entries with persistent patch targets.
 */
@Remote async listPlugins(): Promise<PluginInfo[]>

/** Read installed bundles and bundles supplied by this dsh installation.
 * @returns Package versions, activation selections and removal availability.
 */
@Remote listBundles(): Promise<BundleInfo[]>

/** Persist a plugin entry's desired enablement and apply it on live profiles.
 * @param id Loader entry identity returned by listPlugins.
 * @param enabled Whether the plugin should run.
 * @returns Saved and runtime outcomes, including higher-priority overrides.
 */
@Remote setPluginEnabled(id: PluginEntryId, enabled: boolean): Promise<ChangeResult>

/** Select or remove a bundle layer while retaining installed dependencies.
 * @param name Bundle package name.
 * @param enabled Whether the bundle contributes its patch layer.
 * @returns Persisted and runtime outcomes.
 */
@Remote setBundleEnabled(name: string, enabled: boolean): Promise<ChangeResult>

/** Install a package using the same pnpm implementation as dsh plugin.
 * @param spec One package spec, including local paths relative to the invocation directory.
 * @param options Whether to activate the installed bundle; defaults to true.
 * @returns Package-manager diagnostics and observed activation outcome.
 */
@Remote installBundle(spec: string, options?: InstallBundleOptions): Promise<ChangeResult>

/** Unload and remove a profile-owned bundle dependency through dsh plugin's pnpm path.
 * @param name Installed dependency name.
 * @returns Removal diagnostics and the remaining profile state.
 */
@Remote removeBundle(name: string): Promise<ChangeResult>

Source: packages/boot/plugin-manager/src/index.ts

ctx.profileContext — ProfileContext

Current profile facts; scheduling and mutation belong to their callers.

Source: packages/boot/app-boot/src/profile-context.ts

hmr/* events

hmr/before-reload — waterfall

Acquire application-owned exclusion before an automatic reload.

/** Acquire application-owned exclusion before an automatic reload.
 * @mode waterfall
 * @param next Runs the remaining lock providers and reload; listeners must await it.
 */
'hmr/before-reload'(next: () => Promise<void>): Promise<void>

Source: packages/boot/hmr/src/index.ts

hmr/change — emit

A watched file has no module or configuration handler.

/** A watched file has no module or configuration handler.
 * @mode emit
 * @param url Canonical file URL.
 */
'hmr/change'(url: string): void

Source: packages/boot/hmr/src/index.ts

hmr/reload — emit

Module replacements have finished loading.

/** Module replacements have finished loading.
 * @mode emit
 * @param reloads Replaced plugins and their module locations.
 */
'hmr/reload'(reloads: Map<Plugin, Reload>): void

Source: packages/boot/hmr/src/index.ts