dsh-plugin-guide 0.3.42 → 0.4.0

package/references/official-docs/docs/subsystems/boot.md

@@ -1,447 +0,0 @@
-# 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, fiber phase and optional display `meta`, plus a unique `patchId` or a `readOnlyReason`.
-
-`BundleInfo.official` identifies project-maintained shipped optional bundles and on-demand catalog entries independently of installation. `availability` identifies a readable installation-provided or profile package, or `missing`; on-demand catalog entries exclude undeclared transitive copies. `installed` records the profile dependency declaration. An on-demand `installTarget` carries the host-derived exact spec and version. `BundleInfo` also carries the package name, optional installed version, selected enablement, removal availability, optional resolution error, and, for a bundle the profile's own dependency supplies and the installation does not, `source`: that dependency as a spec `pnpm add` accepts. Its optional `meta` and each `BundleRowInfo.meta` contain display text or a metadata diagnostic; Clients select a language at render time.
-
-`InstallBundleOptions.saveExact` passes `--save-exact` to the shared package installer. `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, plus `timedOut` when the manager terminated a run that stopped printing. A terminated run is classified `timeout` whatever exit status the signal left behind, so installation and removal report failure instead of success and no further registry is asked. `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; `bundle` and `version` name the package a finished installation added and its manifest version; `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.
-
-## Market records
-
-[Plugin Market](../../packages/boot/plugin-market/README.md) reads index format 1, validated by [`dsh-plugin-market-index`](../../packages/util/plugin-market-index/README.md).
-
-`MarketIndexSummary` carries one configured index URL with the `title` and `description` of its last successful read and, when the last read failed, its `error`.
-
-`MarketQuery` selects one page of an index: fuzzy `text`, a `category`, `labels` that must all be present, a `MarketSort`, `offset`, `limit` up to 100, `refresh` to fetch again instead of using a cached document, and `fetchedAt` to continue the pages of one document. `MarketSearchResult` carries the index URL, `title`, optional `description`, market `metadata`, the document's `fetchedAt`, the page's `entries`, the `total` number of matches, and the `nextOffset`. Each `MarketListingEntry` adds `defaultVersion`, the version installed by default, and `installation`, the profile's status for the package name; each of its `versions` adds `install`, the exact spec and optional first registry for `installBundle`, and `compatibility`, the evaluation of its `engines.dsh` including a version exemption.
-
-## Profile reconciliation
-
-<a id="profile-reconciliation"></a>
-
-```ts type-equiv
-/** Outcome of {@link Hmr.reconcileProfile}. */
-interface ProfileReconciliation {
-  /** Diagnostics for Loader entries left inactive. */
-  warnings: string[]
-  /** Loaded modules whose files changed on disk and whose previous code keeps running until a restart. */
-  pending: PendingModule[]
-  /**
-   * Why every change waits for a restart: `module-comparison` when module caches cannot be inspected or their files
-   * compared, even when no URLs are known; `package-moved` when the runtime resolution cannot publish a moved package.
-   */
-  restartReason?: 'module-comparison' | 'package-moved'
-}
-```
-
-```ts type-equiv
-/** A changed module that loads only after a restart. */
-interface PendingModule {
-  url: string
-  /**
-   * `host-module`: the process entry point's static graph imports it. `unmanaged-plugin`: it is imported by a plugin
-   * that runs outside a traversable Loader entry. `module-comparison`: loaded modules could not be compared with disk.
-   */
-  reason: 'host-module' | 'unmanaged-plugin' | 'module-comparison'
-}
-```
-
-<!-- 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="ctxconfigeditor--configeditor"></a>
-
-### `ctx.configEditor` — `ConfigEditor`
-
-Persist complete raw configs and apply them through the normal Loader path.
-
-```ts cordis-catalog
-/** Addressable profile rows; nested Includes have independent configuration ownership.
- * @returns Active entries with unique profile patch ids.
- */
-entries(): Entry[]
-
-/** Read inherited and explicit profile values for the active entries.
- * @returns Detached layer values alongside their Loader entries.
- */
-configuration(): Array<{ entry: Entry; inherited: Record<string, unknown>; override: Record<string, unknown> }>
-
-/** Validate, persist, and reconcile a plugin's next config; ordinary fields keep normal lifecycle rules.
- * @param entry Current Loader entry, also used to detect replacement during the write.
- * @param change Derive a raw config from the current entry and its inherited layer.
- * @returns Fulfillment after Loader reconciliation completes.
- */
-async edit( entry: Entry, change: (current: Record<string, unknown>, inherited: Record<string, unknown>) => Record<string, unknown>, ): Promise<void>
-```
-
-Source: [`packages/boot/config-editor/src/index.ts`](../../packages/boot/config-editor/src/index.ts)
-
-<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[]>
-
-/**
- * Recompose the profile from its manifest and patch files, replacing running plugins whose loaded files below the
- * profile directory or its linked package targets changed on disk, and publishing its runtime resolution. Changed
- * modules are evicted and the Loader entries running them stop; app-boot's {@link recomposeProfile} then publishes the
- * resolution, applies the generation, starts the stopped entries with the current files and configuration,
- * imports entries whose import failed again, and judges activation. Afterwards the modules below the mappings the
- * recomposition dropped are evicted, so a removed or deselected package is imported afresh when it returns. Callers run
- * inside {@link runExclusive}.
- * @param requiredIds Entry ids whose inactive state is reported as a failure even when it predates this call.
- * @returns Inactive-entry diagnostics, the changed modules that load after a restart, and a profile-wide restart reason.
- * @throws The patch read, publication, preparation, apply, or activation failure of the recomposition, including a
- * replacement plugin that fails to load or start, whose previous code no longer runs.
- */
-async reconcileProfile(requiredIds: readonly string[] = []): Promise<ProfileReconciliation>
-```
-
-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 exact plugin-version exemptions saved in this profile.
- * @returns Accepted package-name@version keys with the runtime versions they may run on, and any
- * record or file problem the reader rejected, which the caller reports instead of failing.
- */
-@Remote listVersionExemptions(): { exemptions: Record<string, string[]>; warnings: string[] }
-
-/** Grant or revoke one exact plugin/runtime exemption and reevaluate live plugins.
- * @param packageVersion Exact manifest package name followed by @ and its version; never an installation spec or alias.
- * @param runtimeVersion Exact current DSH version for grants; revocation may name a previous runtime.
- * @param enabled Whether to grant rather than revoke the exemption.
- * @param acceptRisk Required true for grants after the user accepts possible crashes and data loss.
- * @returns Saved and runtime outcomes. Startup-only profiles require restart.
- */
-@Remote setVersionExemption(packageVersion: string, runtimeVersion: string, enabled: boolean, acceptRisk?: boolean): Promise<ChangeResult>
-
-/** 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, installation-provided, and offline Official catalog bundles, plus selected non-bundle names.
- * A dependency without a bundle patch is listed, as a `not-bundle` problem, only while it is selected.
- * @returns Package versions, manifest descriptions, the installable spec of profile dependencies, rows, optional
- * display metadata, 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. GitHub
- * repositories get a connection check bounded by githubConnectionTimeoutMs before pnpm starts;
- * only network failures or timeouts stop installation, while pnpm owns authentication and transport fallback. 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, whether to save an exact dependency, 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>
-
-/** Recover the result of an active installation without cancelling it.
- * @param requestId The id supplied when installation started.
- * @returns The installation's outcome after it settles, or null if no active request has that id.
- * Completed results are not retained; null establishes neither success nor cancellation.
- */
-@Remote async waitForInstall(requestId: PluginInstallRequestId): Promise<ChangeResult | null>
-
-/** 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 the Git check or 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; a selected name no
- * dependency holds is only deselected.
- * @param name Installed dependency or selected bundle 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="ctxpluginmarket--pluginmarket"></a>
-
-### `ctx.pluginMarket` — `PluginMarket`
-
-Fetches, validates, and caches configured market indexes; annotates entries with the profile's installation facts.
-
-```ts cordis-catalog
-/**
- * List the configured index sources without fetching them.
- * @returns every source in order, with the title of its last successful read and, when the last read failed, its error.
- */
-@Remote listIndexes(): MarketIndexSummary[]
-
-/**
- * Replace the configured index sources through Settings, without remounting this service.
- * `plugin-market/changed` announces the committed list. A URL already configured is kept as written, so a client can
- * add or remove sources beside one that `listIndexes` reports as unusable.
- * @param urls - index URLs in display order.
- * @throws {RemoteError} `plugin-market/invalid-index-url` for an invalid new URL or a repeated URL;
- * `plugin-market/settings-unavailable` without Settings or a profile entry.
- */
-@Remote async setIndexes(urls: string[]): Promise<void>
-
-/**
- * Return one page of the plugins of a configured index that match a query. Concurrent reads of a URL share one
- * fetch; a successful document is reused for `cacheTtlMs` unless `refresh` is set. Matching and ordering read only
- * the document; installation status and compatibility are computed for the returned page on every call.
- * @param url - a configured index URL.
- * @param query - text, filters, order, page, and whether to bypass the cached document.
- * @returns the index header, the page's plugins with each plugin's default version and installation status and each
- *   version's compatibility and install arguments, the number of matches, and the next page's offset.
- * @throws {RemoteError} `plugin-market/invalid-query`, `plugin-market/unknown-index`, `plugin-market/invalid-index-url`,
- *   `plugin-market/fetch-failed`, or `plugin-market/invalid-index`.
- */
-@Remote async search(url: string, query: MarketQuery): Promise<MarketSearchResult>
-
-/**
- * Read one plugin of a configured index, using the cached document as `search` does.
- * @param url - a configured index URL.
- * @param name - the plugin's package name.
- * @returns the plugin with its default version, installation status, and annotated versions; undefined when the
- *   index does not list it.
- * @throws {RemoteError} `plugin-market/unknown-index`, `plugin-market/invalid-index-url`, `plugin-market/fetch-failed`,
- *   or `plugin-market/invalid-index`.
- */
-async entry(url: string, name: string): Promise<MarketListingEntry | undefined>
-```
-
-Source: [`packages/boot/plugin-market/src/index.ts`](../../packages/boot/plugin-market/src/index.ts)
-
-<a id="ctxpluginregistryprobe--pluginregistryprobe"></a>
-
-### `ctx.pluginRegistryProbe` — `PluginRegistryProbe`
-
-Compares public registry responses on the Host; the Client owns the initial selection.
-
-```ts cordis-catalog
-/**
- * Race npm and npmmirror HTTPS ping responses through the Host's fetch proxy.
- * Concurrent readers share a probe; a winner cancels and awaits the other request.
- * @returns the first registry with a successful response, or null when disabled or neither responds successfully; results are cached.
- * @throws rejects when the service has been unloaded.
- */
-@Remote async fastest(): Promise<string | null>
-```
-
-Source: [`packages/client/ui-plugin-manager/src/index.ts`](../../packages/client/ui-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="app-boot-events"></a>
-
-### `app-boot/*` events
-
-<a id="app-bootconfig-reload--emit"></a>
-
-#### `app-boot/config-reload` — emit
-
-Profile patches were reconciled into the running Loader tree: every entry update settled and no new inactive entry was introduced. Carries no diff; listeners re-read Loader entries.
-
-```ts cordis-catalog
-/**
- * Profile patches were reconciled into the running Loader tree: every entry update settled and no new
- * inactive entry was introduced. Carries no diff; listeners re-read Loader entries.
- * @mode emit
- */
-'app-boot/config-reload'(): void
-```
-
-Source: [`packages/boot/app-boot/src/index.ts`](../../packages/boot/app-boot/src/index.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)
-
-<a id="plugin-market-events"></a>
-
-### `plugin-market/*` events
-
-<a id="plugin-marketchanged--emit"></a>
-
-#### `plugin-market/changed` — emit
-
-The configured index sources changed.
-
-```ts cordis-catalog
-/**
- * The configured index sources changed.
- * @mode emit
- */
-'plugin-market/changed'(): void
-```
-
-Source: [`packages/boot/plugin-market/src/types.ts`](../../packages/boot/plugin-market/src/types.ts)
-<!-- END GENERATED cordis-surface -->