@deepseek-ai/dsh-plugin-manager 0.1.6-alpha.2 → 0.1.7-alpha.2

package/lib/types/index.js

@@ -37,19 +37,23 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import z from '@deepseek-ai/schemastery';
 import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol';
 import { pluginEntryId, readPluginInventory } from '@deepseek-ai/dsh-host-plugin-inventory';
-import { readProfileManifest, resolveBundleDir, loadOverlayPatches, composeEntries, reconcileProfilePatches, readProfilePatches, OPTIONAL_BUNDLES, } from '@deepseek-ai/dsh-app-boot';
-import { bundleManifest, runProfilePnpm, saveManifest, viewProfilePackage } from "./operations.js";
+import { readPluginMeta, readProfileManifest, resolveBundleDir, loadOverlayPatches, composeEntries, reconcileProfilePatches, readProfilePatches, OPTIONAL_BUNDLES, bundlePatchPaths, } from '@deepseek-ai/dsh-app-boot';
+import { bundleManifest, readProfileRegistry, registryArguments, runProfilePnpm, saveManifest, viewProfilePackage } from "./operations.js";
 import { classifyInstallFailure } from "./install-failure.js";
 import { InvalidInstallSpecError, parseInstallSpec } from "./install-spec.js";
+import { attributeFailure, normalizeRegistry, NPMMIRROR_REGISTRY, registryPlan } from "./registry.js";
 import { writePluginEnabled } from "./patch.js";
 import { ManagementFailure } from "./failure.js";
 import { approveBuilds, readPendingBuilds } from "./build-approval.js";
 export { classifyInstallFailure } from "./install-failure.js";
 export { InvalidInstallSpecError, parseInstallSpec } from "./install-spec.js";
+/** An http(s) URL, as pnpm's `--registry` takes it. */
+const REGISTRY_URL = /^https?:\/\/\S+$/;
 const protectedModules = new Set([
     '@deepseek-ai/dsh-plugin-manager', '@deepseek-ai/cordis-plugin-loader',
     '@deepseek-ai/cordis-plugin-include', '@deepseek-ai/dsh-api-gateway',
@@ -88,7 +92,7 @@ function stringField(manifest, field) {
     return typeof value === 'string' ? value : undefined;
 }
 /** What a package manifest says about the package: identity, one-liner, and whether it is a bundle. */
-function inspectionOf(kind, manifest) {
+function inspectionOf(kind, manifest, registry) {
     const dsh = manifest.dsh;
     const declared = typeof dsh === 'object' && dsh !== null ? dsh : undefined;
     const bundle = declared !== undefined && typeof declared.bundle === 'object' && declared.bundle !== null;
@@ -96,7 +100,7 @@ function inspectionOf(kind, manifest) {
     const version = stringField(manifest, 'version');
     const description = stringField(manifest, 'description');
     return {
-        status: 'accepted', kind, bundle,
+        status: 'accepted', kind, bundle, registry,
         ...name === undefined ? {} : { name },
         ...version === undefined ? {} : { version },
         ...description === undefined || description === '' ? {} : { description },
@@ -105,16 +109,45 @@ function inspectionOf(kind, manifest) {
 function refused(problem, reason) {
     return { status: 'refused', problem, reason };
 }
+/** The refusal `pnpm view --json` prints on stdout, `{ error: { code, message } }`, as one log line; empty for anything else. */
+function printedError(printed) {
+    let parsed;
+    try {
+        parsed = JSON.parse(printed || 'null');
+    }
+    catch {
+        return ''; /* not JSON: nothing pnpm printed as a refusal */
+    }
+    const error = typeof parsed === 'object' && parsed !== null ? parsed.error : undefined;
+    if (typeof error !== 'object' || error === null)
+        return '';
+    const { code, message } = error;
+    return [code, message].filter((part) => typeof part === 'string').join('  ');
+}
+/** The spec's form, for deciding whether a failed attempt was the registry's; a form the parser refuses has no host of its own. */
+function parsedForRegistry(spec) {
+    try {
+        return parseInstallSpec(spec);
+    }
+    catch (error) {
+        /* v8 ignore next -- parseInstallSpec throws nothing but its own refusal */
+        if (!(error instanceof InvalidInstallSpecError))
+            throw error;
+        return { kind: 'registry', spec, name: spec };
+    }
+}
 /** Manage profile files and apply their declared reload lifecycle. */
 let PluginManager = (() => {
     let _classSuper = TypertRemoteService;
     let _instanceExtraInitializers = [];
     let _listPlugins_decorators;
     let _listBundles_decorators;
+    let _registries_decorators;
     let _inspect_decorators;
     let _setPluginEnabled_decorators;
     let _setBundleEnabled_decorators;
     let _installBundle_decorators;
+    let _waitForInstall_decorators;
     let _cancelInstall_decorators;
     let _removeBundle_decorators;
     return class PluginManager extends _classSuper {
@@ -122,18 +155,22 @@ let PluginManager = (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
             _listPlugins_decorators = [Remote];
             _listBundles_decorators = [Remote];
+            _registries_decorators = [Remote];
             _inspect_decorators = [Remote];
             _setPluginEnabled_decorators = [Remote];
             _setBundleEnabled_decorators = [Remote];
             _installBundle_decorators = [Remote];
+            _waitForInstall_decorators = [Remote];
             _cancelInstall_decorators = [Remote];
             _removeBundle_decorators = [Remote];
             __esDecorate(this, null, _listPlugins_decorators, { kind: "method", name: "listPlugins", static: false, private: false, access: { has: obj => "listPlugins" in obj, get: obj => obj.listPlugins }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _listBundles_decorators, { kind: "method", name: "listBundles", static: false, private: false, access: { has: obj => "listBundles" in obj, get: obj => obj.listBundles }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _registries_decorators, { kind: "method", name: "registries", static: false, private: false, access: { has: obj => "registries" in obj, get: obj => obj.registries }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _inspect_decorators, { kind: "method", name: "inspect", static: false, private: false, access: { has: obj => "inspect" in obj, get: obj => obj.inspect }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setPluginEnabled_decorators, { kind: "method", name: "setPluginEnabled", static: false, private: false, access: { has: obj => "setPluginEnabled" in obj, get: obj => obj.setPluginEnabled }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setBundleEnabled_decorators, { kind: "method", name: "setBundleEnabled", static: false, private: false, access: { has: obj => "setBundleEnabled" in obj, get: obj => obj.setBundleEnabled }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _installBundle_decorators, { kind: "method", name: "installBundle", static: false, private: false, access: { has: obj => "installBundle" in obj, get: obj => obj.installBundle }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _waitForInstall_decorators, { kind: "method", name: "waitForInstall", static: false, private: false, access: { has: obj => "waitForInstall" in obj, get: obj => obj.waitForInstall }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _cancelInstall_decorators, { kind: "method", name: "cancelInstall", static: false, private: false, access: { has: obj => "cancelInstall" in obj, get: obj => obj.cancelInstall }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _removeBundle_decorators, { kind: "method", name: "removeBundle", static: false, private: false, access: { has: obj => "removeBundle" in obj, get: obj => obj.removeBundle }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
@@ -144,14 +181,19 @@ let PluginManager = (() => {
             outputBytes: z.number().step(1).min(1).default(16384),
             lockWaitMs: z.number().step(1).min(0).default(120000),
             inspectTimeoutMs: z.number().step(1).min(1000).default(20000),
+            registry: z.string().pattern(REGISTRY_URL),
+            fallbackRegistries: z.array(z.string().pattern(REGISTRY_URL)).default([NPMMIRROR_REGISTRY]),
         });
-        ownerEntryId = __runInitializers(this, _instanceExtraInitializers);
+        /** Management bundles remain protected if their files become unreadable. */
+        managementBundles = (__runInitializers(this, _instanceExtraInitializers), new Set());
+        ownerEntryId;
         packageOperations = new Set();
         profile;
         outputBytes;
         lockWaitMs;
         inspectTimeoutMs;
         pnpmCommand;
+        configuredRegistries;
         ownerContext;
         abort = new AbortController();
         /** Installations by request id, from their call until it settles. */
@@ -161,10 +203,16 @@ let PluginManager = (() => {
             this.ownerEntryId = ctx.fiber.entry?.id;
             this.ownerContext = ctx;
             this.profile = ctx.profileContext;
+            for (const name of this.profile.startedBundles)
+                this.protectsManager(name);
             this.outputBytes = config.outputBytes;
             this.lockWaitMs = config.lockWaitMs;
             this.inspectTimeoutMs = config.inspectTimeoutMs;
             this.pnpmCommand = config.pnpmCommand;
+            this.configuredRegistries = {
+                registry: config.registry === undefined ? null : normalizeRegistry(config.registry),
+                fallbackRegistries: config.fallbackRegistries.map(normalizeRegistry),
+            };
             ctx.effect(() => async () => {
                 this.abort.abort();
                 await Promise.allSettled([...this.packageOperations]);
@@ -192,8 +240,8 @@ let PluginManager = (() => {
         }
         /** 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.
+         * @returns Package versions, manifest descriptions, rows, optional display metadata, activation selections,
+         * whether the installation offers the bundle, and removal availability.
          */
         listBundles() {
             const manifest = readProfileManifest('dsh', this.profile.dir);
@@ -207,34 +255,51 @@ let PluginManager = (() => {
                 const optional = OPTIONAL_BUNDLES.includes(name);
                 const removable = installed && !Object.hasOwn(installation.dependencies ?? {}, name);
                 const enabled = selected.includes(name);
+                const readOnlyReason = this.protectsManager(name) ? 'management-required' : undefined;
                 try {
                     const info = bundleManifest(name, this.profile.dir, this.profile.installAnchor);
                     if (info === undefined) {
                         if (enabled)
-                            bundles.push({ name, enabled, installed, optional, removable, error: { code: 'not-bundle' }, rows: [], overrides: [] });
+                            bundles.push({ name, enabled, installed, optional, removable: removable && readOnlyReason === undefined,
+                                ...(readOnlyReason === undefined ? {} : { readOnlyReason }), error: { code: 'not-bundle' }, rows: [], overrides: [] });
                         continue;
                     }
-                    const readOnlyReason = this.protectsManager(name) ? 'management-required' : undefined;
+                    const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir);
+                    const meta = readPluginMeta(info.name ?? name, pathToFileURL(join(dir, 'package.json')).href);
                     bundles.push({ name, ...(info.version === undefined ? {} : { version: info.version }),
                         ...(info.description === undefined || info.description === '' ? {} : { description: info.description }),
+                        ...meta === undefined ? {} : { meta },
                         enabled, installed, optional, removable: removable && readOnlyReason === undefined,
                         ...(readOnlyReason === undefined ? {} : { readOnlyReason }),
                         ...this.declaredRows(name, info) });
                 }
                 catch (error) {
                     if (enabled || installed) {
-                        bundles.push({ name, enabled, installed, optional, removable, error: managementError(error), rows: [], overrides: [] });
+                        bundles.push({ name, enabled, installed, optional, removable: removable && readOnlyReason === undefined,
+                            ...(readOnlyReason === undefined ? {} : { readOnlyReason }), error: managementError(error), rows: [], overrides: [] });
                     }
                 }
             }
             return Promise.resolve(bundles);
         }
+        /** 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.
+         */
+        async registries() {
+            return {
+                ...this.configuredRegistries, fallbackRegistries: [...this.configuredRegistries.fallbackRegistries],
+                resolved: await readProfileRegistry(this.profile.dir, {
+                    ...this.profile.packageManager ?? { command: this.pnpmCommand }, timeoutMs: this.inspectTimeoutMs,
+                }),
+            };
+        }
         /** 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.
          */
-        async inspect(spec, signal) {
+        async inspect(spec, options, signal) {
             let parsed;
             try {
                 parsed = parseInstallSpec(spec);
@@ -250,12 +315,14 @@ let PluginManager = (() => {
             const known = new Set([
                 ...manifest.dsh?.profile?.bundles ?? [], ...Object.keys(manifest.dependencies ?? {}), ...Object.keys(installation.dependencies ?? {}),
             ]);
+            const plan = registryPlan(options?.registry, await this.registries());
+            const registry = plan[0];
             switch (parsed.kind) {
-                case 'git': return { status: 'accepted', kind: 'git', bundle: null };
+                case 'git': return { status: 'accepted', kind: 'git', bundle: null, registry, host: parsed.host };
                 case 'tarball':
                     if (parsed.path !== undefined && !existsSync(parsed.path))
                         return refused('not-a-package', 'the tarball does not exist');
-                    return { status: 'accepted', kind: 'tarball', bundle: null };
+                    return { status: 'accepted', kind: 'tarball', bundle: null, registry, ...parsed.host === undefined ? {} : { host: parsed.host } };
                 case 'path': {
                     if (!existsSync(parsed.path))
                         return refused('not-a-package', 'the path does not exist');
@@ -266,7 +333,7 @@ let PluginManager = (() => {
                     catch (error) {
                         return refused('not-a-package', `no readable package.json at the path: ${messageOf(error)}`);
                     }
-                    const inspection = inspectionOf('path', read);
+                    const inspection = inspectionOf('path', read, registry);
                     if (inspection.name === undefined)
                         return refused('not-a-package', 'the package.json names no package');
                     if (known.has(inspection.name))
@@ -278,36 +345,48 @@ let PluginManager = (() => {
                 case 'registry': {
                     if (known.has(parsed.name))
                         return refused('already-installed', `${parsed.name} is already installed`);
-                    const view = await viewProfilePackage(this.profile.dir, spec.trim(), {
-                        ...this.profile.packageManager ?? { command: this.pnpmCommand },
-                        timeoutMs: this.inspectTimeoutMs, ...signal === undefined ? {} : { signal },
-                    });
-                    const log = `${view.stderr}${view.cause === undefined ? '' : `${messageOf(view.cause)}\n`}`.trim();
-                    if (view.exitCode !== 0 || view.cause !== undefined || view.timedOut) {
-                        const kind = classifyInstallFailure({ log, timedOut: view.timedOut, ...view.cause === undefined ? {} : { cause: view.cause } });
-                        const reason = log || view.stdout.trim() || `pnpm view exited with ${String(view.exitCode)}`;
-                        if (kind === 'not-found' || kind === 'no-matching-version')
-                            return refused('not-found', reason);
-                        if (kind === 'network')
-                            return refused('network', reason);
-                        return refused('unknown', view.timedOut ? `pnpm view timed out after ${String(this.inspectTimeoutMs)}ms` : reason);
-                    }
-                    let answer;
-                    try {
-                        answer = JSON.parse(view.stdout.replace(ANSI_SEQUENCE, '').trim() || 'null');
-                    }
-                    catch (error) {
-                        return refused('unknown', `unreadable pnpm view output: ${messageOf(error)}`);
+                    const registries = [];
+                    const refusedBy = (problem, reason) => ({ status: 'refused', problem, reason, registries });
+                    for (const current of plan) {
+                        registries.push(current);
+                        const view = await viewProfilePackage(this.profile.dir, spec.trim(), {
+                            ...this.profile.packageManager ?? { command: this.pnpmCommand },
+                            timeoutMs: this.inspectTimeoutMs, ...signal === undefined ? {} : { signal }, registry: current,
+                        });
+                        const printed = view.stdout.replace(ANSI_SEQUENCE, '').trim();
+                        if (view.exitCode !== 0 || view.cause !== undefined || view.timedOut) {
+                            // pnpm prints a refusal as `{ error: { code, message } }` on stdout, with nothing on stderr.
+                            const log = [view.stderr.trim(), printedError(printed), view.cause === undefined ? '' : messageOf(view.cause)].filter(Boolean).join('\n');
+                            const kind = classifyInstallFailure({ log, timedOut: view.timedOut, ...view.cause === undefined ? {} : { cause: view.cause } });
+                            // A lookup the caller dropped is not carried to the next registry.
+                            if (registries.length < plan.length && signal?.aborted !== true && attributeFailure(kind, log, parsed) === 'registry')
+                                continue;
+                            const reason = view.timedOut ? `pnpm view timed out after ${String(this.inspectTimeoutMs)}ms` : log || printed || `pnpm view exited with ${String(view.exitCode)}`;
+                            if (kind === 'not-found' || kind === 'no-matching-version')
+                                return refusedBy('not-found', reason);
+                            if (kind === 'network' || kind === 'timeout')
+                                return refusedBy('network', reason);
+                            return refusedBy('unknown', reason);
+                        }
+                        let answer;
+                        try {
+                            answer = JSON.parse(printed || 'null');
+                        }
+                        catch (error) {
+                            return refusedBy('unknown', `unreadable pnpm view output: ${messageOf(error)}`);
+                        }
+                        // A range answers one object per matching version, oldest first.
+                        const latest = Array.isArray(answer) ? answer.at(-1) : answer;
+                        if (typeof latest !== 'object' || latest === null)
+                            return refusedBy('unknown', 'pnpm view answered no package');
+                        const inspection = inspectionOf('registry', latest, current);
+                        const named = inspection.name === undefined ? { ...inspection, name: parsed.name } : inspection;
+                        if (!named.bundle)
+                            return refusedBy('not-a-bundle', `${named.name} declares no dsh.bundle`);
+                        return named;
                     }
-                    // A range answers one object per matching version, oldest first.
-                    const latest = Array.isArray(answer) ? answer.at(-1) : answer;
-                    if (typeof latest !== 'object' || latest === null)
-                        return refused('unknown', 'pnpm view answered no package');
-                    const inspection = inspectionOf('registry', latest);
-                    const named = inspection.name === undefined ? { ...inspection, name: parsed.name } : inspection;
-                    if (!named.bundle)
-                        return refused('not-a-bundle', `${named.name} declares no dsh.bundle`);
-                    return named;
+                    /* v8 ignore next -- the plan is never empty: every attempt returns or continues to the next */
+                    throw new Error('no registry was asked');
                 }
             }
         }
@@ -345,19 +424,19 @@ let PluginManager = (() => {
          * 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, and
-         * the pending build scripts to allow for this profile before pnpm runs.
-         * @returns Package-manager diagnostics and observed activation outcome.
+         * @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.
          */
         installBundle(spec, options) {
             const requestId = options?.requestId;
-            const control = { abort: new AbortController(), phase: 'installing', settled: Promise.resolve() };
+            const control = { abort: new AbortController(), phase: 'installing', result: Promise.resolve(null) };
             const stopped = () => control.abort.signal.aborted;
             if (requestId !== undefined)
                 this.installs.set(requestId, control);
-            const announce = (phase) => {
+            const announce = (phase, attempt) => {
                 if (requestId !== undefined)
-                    this.ownerContext.emit('plugin-manager/install-state', { requestId, phase });
+                    this.ownerContext.emit('plugin-manager/install-state', { requestId, phase, ...attempt === undefined ? {} : { attempt } });
             };
             const result = this.change(async (result) => {
                 if (spec.trim() === '' || spec.startsWith('-'))
@@ -370,13 +449,41 @@ let PluginManager = (() => {
                 }
                 const files = await this.readRestoredFiles();
                 const before = readProfileManifest('dsh', this.profile.dir).dependencies ?? {};
-                announce('installing');
+                const plan = registryPlan(options?.registry, await this.registries());
                 let name;
                 try {
-                    result.packageResult = await this.runPnpm(['add', spec], control.abort.signal, requestId);
-                    if (stopped())
-                        throw new InstallCancelledError();
-                    if (result.packageResult.exitCode !== 0) {
+                    // The last run is the result's; the registries asked stay listed whatever the outcome.
+                    let run;
+                    result.registries = [];
+                    for (const [index, registry] of plan.entries()) {
+                        if (index > 0)
+                            await this.restoreFiles(files);
+                        // A stop that landed while the files went back, or before the first run, starts no run with a dead signal.
+                        if (stopped())
+                            throw new InstallCancelledError();
+                        result.registries.push(registry);
+                        announce('installing', { registry, index: index + 1, total: plan.length });
+                        run = await this.runPnpm(['add', spec, ...registryArguments(registry)], control.abort.signal, requestId);
+                        result.packageResult = run;
+                        if (stopped())
+                            throw new InstallCancelledError();
+                        /* v8 ignore next 2 -- runPnpm classifies every failed run, so kind is never absent here */
+                        if (run.exitCode === 0 || run.kind === undefined)
+                            break;
+                        const failedAt = attributeFailure(run.kind, run.output, parsedForRegistry(spec));
+                        // What the last failed run could not reach; a later run that succeeds leaves nothing to say.
+                        delete result.failedAt;
+                        if (failedAt !== 'other')
+                            result.failedAt = failedAt;
+                        if (failedAt !== 'registry' || index === plan.length - 1)
+                            break;
+                    }
+                    /* v8 ignore next -- the plan is never empty, so a run always settled */
+                    if (run === undefined)
+                        throw new Error('no registry was asked');
+                    if (run.exitCode === 0)
+                        delete result.failedAt;
+                    if (run.exitCode !== 0) {
                         // pnpm-workspace.yaml is not restored, so the names pnpm left undecided there can be offered for approval.
                         try {
                             result.pendingBuilds = await readPendingBuilds(this.profile.dir);
@@ -384,7 +491,7 @@ let PluginManager = (() => {
                         catch (error) {
                             this.ownerContext.logger.warn('Could not read pending build approvals after pnpm failed', error);
                         }
-                        throw new Error(result.packageResult.output);
+                        throw new Error(run.output);
                     }
                     const after = readProfileManifest('dsh', this.profile.dir).dependencies ?? {};
                     const installed = Object.keys(after).filter(name => before[name] !== after[name]);
@@ -397,9 +504,10 @@ let PluginManager = (() => {
                     name = target;
                     const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir);
                     const manifest = bundleManifest(name, this.profile.dir, this.profile.installAnchor);
-                    if (manifest?.dsh?.bundle?.patch === undefined)
+                    if (manifest?.dsh?.bundle === undefined)
                         throw new ManagementFailure('not-bundle');
-                    loadOverlayPatches('dsh', join(dir, manifest.dsh.bundle.patch));
+                    for (const file of bundlePatchPaths(dir, manifest.dsh.bundle))
+                        loadOverlayPatches('dsh', file);
                 }
                 catch (error) {
                     // pnpm has exited by now, so the files it rewrote go back as they were.
@@ -420,11 +528,18 @@ let PluginManager = (() => {
                         result.warnings = await this.reload();
                 });
             }, { stage: 'install', target: spec, enabled: options?.enabled !== false }, 'install');
-            /* v8 ignore next -- change() folds every failure into its result; only a lock or disposal error rejects */
-            control.settled = result.then(() => undefined, () => undefined);
+            control.result = result;
             return result.finally(() => { if (requestId !== undefined)
                 this.installs.delete(requestId); });
         }
+        /** 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.
+         */
+        async waitForInstall(requestId) {
+            return this.installs.get(requestId)?.result ?? 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 pnpm exited and the files are restored, `too-late` once the bundle is being
@@ -438,7 +553,8 @@ let PluginManager = (() => {
                 return { status: 'too-late' };
             this.ownerContext.emit('plugin-manager/install-state', { requestId, phase: 'cancelling' });
             control.abort.abort();
-            await control.settled;
+            /* v8 ignore next -- change() folds every failure into its result; only a lock or disposal error rejects */
+            await control.result.then(() => undefined, () => undefined);
             return { status: 'cancelled' };
         }
         /** Unload and remove a profile-owned bundle dependency through dsh plugin's pnpm path.
@@ -452,8 +568,8 @@ let PluginManager = (() => {
                     if (bundle === undefined || !bundle.removable)
                         throw new ManagementFailure('not-removable');
                     if (this.ownerContext.get('hmr') === undefined && (this.profile.startedBundles.includes(name)
-                        || this.bundleRows(name).some(row => [...this.ctx.loader.entries()]
-                            .some(entry => entry.options.id === row.id && entry.fiber !== undefined)))) {
+                        || (bundle.error === undefined && this.bundleRows(name).some(row => [...this.ctx.loader.entries()]
+                            .some(entry => entry.options.id === row.id && entry.fiber !== undefined))))) {
                         throw new ManagementFailure('stop-profile');
                     }
                     const contributions = bundle.error === undefined ? this.bundleRows(name) : [];
@@ -473,25 +589,32 @@ let PluginManager = (() => {
         }
         /** The rows a bundle's patch inserts and the existing rows it changes; an unreadable patch throws. */
         declaredRows(name, info) {
-            const patch = info.dsh?.bundle?.patch;
+            const bundle = info.dsh?.bundle;
             /* v8 ignore next -- bundleManifest answers only manifests that declare a patch */
-            if (patch === undefined)
+            if (bundle === undefined)
                 return { rows: [], overrides: [] };
             const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir);
-            const patches = loadOverlayPatches('dsh', join(dir, patch));
+            const patches = bundlePatchPaths(dir, bundle).flatMap(file => loadOverlayPatches('dsh', file));
             // One entry per row id: the Loader keeps a single entry for an id, whichever layer declared it last.
             const live = new Map();
             for (const entry of this.ctx.loader.entries()) {
                 /* v8 ignore next -- the Loader gives every entry an id before it is listed */
                 if (typeof entry.options.id === 'string')
-                    live.set(entry.options.id, pluginEntryId(entry.id));
+                    live.set(entry.options.id, {
+                        entryId: pluginEntryId(entry.id), baseUrl: entry.parent.tree.ctx.baseUrl,
+                    });
             }
             const rows = [];
+            const packages = this.ctx.get('pluginPackages');
             for (const row of flatten(composeEntries([patches.filter(item => item.insert !== undefined)]))) {
                 if (typeof row.id !== 'string' || typeof row.name !== 'string')
                     continue;
-                const entryId = live.get(row.id);
-                rows.push({ rowId: row.id, moduleName: row.name, ...entryId === undefined ? {} : { entryId } });
+                const active = live.get(row.id);
+                const entryId = active?.entryId;
+                const base = active?.baseUrl ?? pathToFileURL(join(dir, 'package.json')).href;
+                const meta = packages?.metaOf(row.name, base);
+                rows.push({ rowId: row.id, moduleName: row.name,
+                    ...entryId === undefined ? {} : { entryId }, ...meta === undefined ? {} : { meta } });
             }
             const declared = new Set(rows.map(row => row.rowId));
             const overrides = [...new Set(patches.flatMap(item => item.insert === undefined && typeof item.id === 'string' && !declared.has(item.id) ? [item.id] : []))];
@@ -551,6 +674,8 @@ let PluginManager = (() => {
             if ((enabled || !previous.includes(name)) && bundleManifest(name, this.profile.dir, this.profile.installAnchor) === undefined) {
                 throw new ManagementFailure('not-bundle');
             }
+            if (enabled)
+                this.bundleRows(name);
             if (!enabled && previous.includes(name)) {
                 if (this.protectsManager(name))
                     throw new ManagementFailure('management-required');
@@ -560,16 +685,31 @@ let PluginManager = (() => {
                 return;
             manifest.dsh = { ...manifest.dsh, profile: { ...manifest.dsh?.profile, bundles } };
             await saveManifest(this.profile.dir, manifest);
+            if (enabled)
+                this.protectsManager(name);
         }
         bundleRows(name) {
             const info = bundleManifest(name, this.profile.dir, this.profile.installAnchor);
             if (info?.dsh?.bundle === undefined)
                 return [];
             const dir = resolveBundleDir('dsh', name, this.profile.installAnchor, this.profile.dir);
-            return flatten(composeEntries([loadOverlayPatches('dsh', join(dir, info.dsh.bundle.patch))]));
+            return flatten(composeEntries([bundlePatchPaths(dir, info.dsh.bundle).flatMap(file => loadOverlayPatches('dsh', file))]));
         }
         protectsManager(name) {
-            return this.bundleRows(name).some(row => protectedModules.has(row.name) || `include:${row.id}` === this.ownerEntryId);
+            if (this.managementBundles.has(name))
+                return true;
+            let rows;
+            try {
+                rows = this.bundleRows(name);
+            }
+            catch (_error) {
+                // Unreadable bundles contribute no new rows; listBundles reports their diagnostics.
+                return false;
+            }
+            const protectedBundle = rows.some(row => protectedModules.has(row.name) || `include:${row.id}` === this.ownerEntryId);
+            if (protectedBundle)
+                this.managementBundles.add(name);
+            return protectedBundle;
         }
         configure(operation) {
             const hmr = this.ownerContext.get('hmr');

package/lib/types/install-failure.js

@@ -12,7 +12,7 @@ const LOG_KINDS = [
     ['disk-full', /\bENOSPC\b|no space left on device/i],
     ['permission', /\bEACCES\b|\bEPERM\b|permission denied/i],
     ['integrity', /ERR_PNPM_TARBALL_INTEGRITY|ERR_PNPM_BAD_TARBALL_SIZE|\bEINTEGRITY\b/],
-    ['network', /\bENOTFOUND\b|\bECONNRESET\b|\bETIMEDOUT\b|\bECONNREFUSED\b|\bEAI_AGAIN\b|ERR_PNPM_META_FETCH_FAIL|ERR_PNPM_FETCH_5\d\d|ERR_PNPM_FETCH_TIMEOUT|socket hang up|Could not resolve host|unable to access/],
+    ['network', /\bENOTFOUND\b|\bECONNRESET\b|\bETIMEDOUT\b|\bECONNREFUSED\b|\bEAI_AGAIN\b|ERR_PNPM_META_FETCH_FAIL|ERR_PNPM_FETCH_5\d\d|ERR_PNPM_FETCH_TIMEOUT|\bFETCH_ERROR\b|socket hang up|Could not resolve host|unable to access/],
 ];
 /**
  * Classify a failed run.

package/lib/types/install-spec.d.ts

@@ -3,7 +3,11 @@
  * takes, and for a registry name whether it is one the registry can accept.
  * @module @deepseek-ai/dsh-plugin-manager/install-spec
  */
-/** One spec read into its form and the parts an inspection needs. */
+/**
+ * One spec read into its form and the parts an inspection needs. A git spec
+ * and a tarball URL carry the `host` pnpm fetches them from, which no registry
+ * stands in for; only their dependencies come from the registry.
+ */
 export type ParsedInstallSpec = {
     readonly kind: 'registry';
     readonly spec: string;
@@ -17,9 +21,11 @@ export type ParsedInstallSpec = {
     readonly kind: 'tarball';
     readonly spec: string;
     readonly path?: string;
+    readonly host?: string;
 } | {
     readonly kind: 'git';
     readonly spec: string;
+    readonly host: string;
 };
 /** A spec neither pnpm nor the registry would take; `reason` is what the person reads. */
 export declare class InvalidInstallSpecError extends Error {

package/lib/types/install-spec.js

@@ -8,6 +8,10 @@ import { isAbsolute } from 'node:path';
 const GIT_SHORTHAND = /^(?:github|gitlab|bitbucket|gist):/i;
 const GIT_URL = /^git(?:\+[a-z]+)?:\/\/|^git@[^:]+:/i;
 const HOSTED_REPOSITORY_URL = /^https?:\/\/[^/]+\/[^/]+\/[^/#]+(?:\.git)?(?:#.*)?$/i;
+/** The hosts pnpm's shorthands stand for. */
+const GIT_SHORTHAND_HOSTS = {
+    github: 'github.com', gitlab: 'gitlab.com', bitbucket: 'bitbucket.org', gist: 'gist.github.com',
+};
 /** A tarball, on disk or over HTTP. */
 const TARBALL_SPEC = /\.(?:tgz|tar\.gz)(?:#.*)?$/i;
 /** An npm package name: lowercase URL-safe segments, an optional scope, no leading dot or underscore. */
@@ -31,6 +35,16 @@ export class InvalidInstallSpecError extends Error {
 function invalid(spec, reason) {
     return new InvalidInstallSpecError(spec, reason);
 }
+/** The host a git spec is cloned from: the shorthand's host, the scp-like user@host, or the URL's host with its port. */
+function gitHost(spec) {
+    const shorthand = /^([a-z]+):/i.exec(spec)?.[1]?.toLowerCase();
+    if (shorthand !== undefined && Object.hasOwn(GIT_SHORTHAND_HOSTS, shorthand))
+        return GIT_SHORTHAND_HOSTS[shorthand];
+    const scp = /^git@([^:]+):/i.exec(spec)?.[1];
+    if (scp !== undefined)
+        return scp.toLowerCase();
+    return new URL(spec.replace(/^git\+/i, '')).host;
+}
 /**
  * Read a spec into its form. A path must be absolute: the Host's working
  * directory means nothing to the person typing into a browser, and a
@@ -54,10 +68,10 @@ export function parseInstallSpec(raw) {
         throw invalid(spec, 'a local path must be absolute');
     const git = GIT_SHORTHAND.test(spec) || GIT_URL.test(spec) || HOSTED_REPOSITORY_URL.test(spec);
     if (git && !TARBALL_SPEC.test(spec))
-        return { kind: 'git', spec };
+        return { kind: 'git', spec, host: gitHost(spec) };
     if (/^https?:\/\//i.test(spec)) {
         if (TARBALL_SPEC.test(spec))
-            return { kind: 'tarball', spec };
+            return { kind: 'tarball', spec, host: new URL(spec).host };
         throw invalid(spec, 'a URL must point at a git repository or a tarball');
     }
     const at = spec.indexOf('@', 1);