Files
deepseek-harness/docs/subsystems/boot.md
T
Yichen Jiang cb2750019a fix(plugin-manager): read pnpm's own registry, its stdout refusals, and lay failures where they belong
Review of #4539. A refusal pnpm view prints as JSON on stdout was read
as unknown, so no registry was ever asked after a dead one; stderr and
stdout are now read alike, and a lookup killed at its bound is a
network refusal. pnpm's own registry joins the fallback plan only once
pnpm config get registry names npm's own or a configured fallback, so
a company registry in .npmrc is never followed by a public one, and a
registry pnpm already names is asked once. The Host lays each failure
at the registry or the spec's own host, reading the host off error
lines only, and reports it as ChangeResult.failedAt; a stop that lands
between attempts is cancelled, not failed. The package publishes its
registry rule through ./registry so the dialog plans with the Host's
own function, starts from the registry the Host asks first until one
is remembered, tags that one as the default, labels pnpm's own by the
host it names, and words and offers a change of registry from the
Host's attribution. ERR_PNPM_NO_OFFLINE_META is no longer a network
failure.
2026-09-18 17:03:04 +08:00

233 lines
10 KiB
Markdown

# Profile management
English | [中文](boot.zh.md)
The [boot package group](../../packages/boot/README.md) owns launcher-provided profile access and the plugin manager. [Plugin Manager](../../packages/boot/plugin-manager/README.md) 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. `approvedBuilds` grants persistent script permission to the supplied pending package names before installation. `registry` names the registry asked first; absent, the configured one.
`PluginRegistries` carries the configured first registry, `null` for the one pnpm's own configuration names, the fallbacks asked after it, and `resolved`, the URL pnpm's own configuration names or `null` while unread. `InspectOptions.registry` names the registry a lookup asks first.
`ChangeResult.changed` reports a disk edit independently of `application`: `applied`, `restart-required`, `overridden` or `failed`. Optional `error` carries a localizable code and external diagnostic. `packageResult` records the pnpm exit code, bounded output, truncation flag and complete diagnostic log path. `pendingBuilds` lists undecided packages across the profile; `approvedBuilds` records the names granted permission by this operation; `registries` lists the registries an installation asked, in order; `failedAt` says whether the last failed run could not reach the registry it asked or the host a git or tarball spec is fetched from.
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
<a id="cordis-surface"></a>
## 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](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
<a id="ctxhmr--hmr"></a>
### `ctx.hmr` — `Hmr`
Hot reload service with Cordis-compatible module configuration and events.
```ts cordis-catalog
/** 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`](../../packages/boot/hmr/src/index.ts)
<a id="ctxpluginmanager--pluginmanager"></a>
### `ctx.pluginManager` — `PluginManager`
Manage profile files and apply their declared reload lifecycle.
```ts cordis-catalog
/** 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 the profile's installed bundles, the bundles this dsh installation supplies, and the selected names that are not bundles.
* A dependency without a bundle patch is listed, as a `not-bundle` problem, only while it is selected.
* @returns Package versions, one-liners, rows, activation selections, whether the installation offers the
* bundle, and removal availability.
*/
@Remote listBundles(): Promise<BundleInfo[]>
/** Read the registries this manager asks: the configured first one, its fallbacks in order, and what pnpm's own configuration names.
* @returns The registries in pnpm's comparison form; null is the one pnpm's own configuration names, `resolved` as pnpm reads it now.
*/
@Remote async registries(): Promise<PluginRegistries>
/** Read what a spec names before installing it.
* @param spec One package spec: a registry name, an absolute path, a git address, or a tarball.
* @param options The registry asked first.
* @param signal Ends a registry lookup early.
* @returns The package the spec names, or why it is refused.
*/
@Remote async inspect(spec: string, options?: InspectOptions, signal?: AbortSignal): Promise<PluginSpecInspection>
/** 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. A run
* that fails, is cancelled, or adds a package without a bundle patch restores
* `package.json` and `pnpm-lock.yaml` as they were; downloaded files can stay.
* @param spec One package spec, including local paths relative to the invocation directory.
* @param options Whether to activate the installed bundle (defaults to true), the request id a cancellation names,
* the pending build scripts to allow for this profile before pnpm runs, and the registry asked first.
* @returns Package-manager diagnostics, the registries asked, and the observed activation outcome.
*/
@Remote installBundle(spec: string, options?: InstallBundleOptions): Promise<ChangeResult>
/** Stop an installation this manager owns and wait until its files are back.
* @param requestId The id the installation was started with.
* @returns `cancelled` once pnpm exited and the files are restored, `too-late` once the bundle is being
* applied, `not-running` for any other id.
*/
@Remote async cancelInstall(requestId: PluginInstallRequestId): Promise<PluginInstallCancellation>
/** 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`](../../packages/boot/plugin-manager/src/index.ts)
<a id="ctxprofilecontext--profilecontext"></a>
### `ctx.profileContext` — `ProfileContext`
Current profile facts; scheduling and mutation belong to their callers.
Source: [`packages/boot/app-boot/src/profile-context.ts`](../../packages/boot/app-boot/src/profile-context.ts)
<a id="hmr-events"></a>
### `hmr/*` events
<a id="hmrchange--emit"></a>
#### `hmr/change` — emit
A watched file has no module or configuration handler.
```ts cordis-catalog
/** 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`](../../packages/boot/hmr/src/index.ts)
<a id="hmrreload--emit"></a>
#### `hmr/reload` — emit
Module replacements have finished loading.
```ts cordis-catalog
/** 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`](../../packages/boot/hmr/src/index.ts)
<a id="plugin-manager-events"></a>
### `plugin-manager/*` events
<a id="plugin-managerchanged--emit"></a>
#### `plugin-manager/changed` — emit
The profile's plugins, bundles, or composition changed: a manager operation completed. A patch generation applied outside the manager, by HMR's watcher after a CLI or hand edit, announces nothing here.
```ts cordis-catalog
/**
* The profile's plugins, bundles, or composition changed: a manager
* operation completed. A patch generation applied outside the manager,
* by HMR's watcher after a CLI or hand edit, announces nothing here.
* @mode emit
* @param change - what changed.
*/
'plugin-manager/changed'(change: PluginChange): void
```
Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
<a id="plugin-managerinstall-log--emit"></a>
#### `plugin-manager/install-log` — emit
One chunk of a pnpm run's output, streamed as the run produces it.
```ts cordis-catalog
/**
* One chunk of a pnpm run's output, streamed as the run produces it.
* @mode emit
* @param chunk - the chunk and the run it belongs to.
*/
'plugin-manager/install-log'(chunk: PluginInstallLogChunk): void
```
Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
<a id="plugin-managerinstall-state--emit"></a>
#### `plugin-manager/install-state` — emit
An installation moved between its Host phases. `installing` is announced once per registry the installation asks, with the attempt's registry and position; `cancelling` and `applying` once.
```ts cordis-catalog
/**
* An installation moved between its Host phases. `installing` is announced once per registry the
* installation asks, with the attempt's registry and position; `cancelling` and `applying` once.
* @mode emit
* @param progress - the installation's request id and phase, with the attempt while installing.
*/
'plugin-manager/install-state'(progress: PluginInstallProgress): void
```
Source: [`packages/boot/plugin-manager/src/types.ts`](../../packages/boot/plugin-manager/src/types.ts)
<!-- END GENERATED cordis-surface -->