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

package/lib/index.js

@@ -2,11 +2,12 @@ import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { mkdir, mkdtemp, open, readFile, rm } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import z from "@deepseek-ai/schemastery";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { pluginEntryId, readPluginInventory } from "@deepseek-ai/dsh-host-plugin-inventory";
-import { OPTIONAL_BUNDLES, composeEntries, loadOptionalPatches, loadOverlayPatches, readProfileManifest, readProfilePatches, reconcileProfilePatches, resolveBundleDir, resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
+import { OPTIONAL_BUNDLES, bundlePatchPaths, composeEntries, loadOptionalPatches, loadOverlayPatches, readPluginMeta, readProfileManifest, readProfilePatches, reconcileProfilePatches, resolveBundleDir, resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
 import { execa } from "execa";
 import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
 import { isAlias, isMap, isNode, isScalar, isSeq, parseDocument, visit } from "yaml";
@@ -55,7 +56,7 @@ async function reconcile(before, dir, anchor, options) {
 			options.onOutput?.(`dsh: warning: ${name} declares no dsh.bundle — installed as a plain dependency, not a profile layer\n`, "stderr");
 			continue;
 		}
-		loadOverlayPatches("dsh", join(resolveBundleDir("dsh", name, anchor, dir), metadata.dsh.bundle.patch));
+		for (const file of bundlePatchPaths(resolveBundleDir("dsh", name, anchor, dir), metadata.dsh.bundle)) loadOverlayPatches("dsh", file);
 		if (!bundles.includes(name)) bundles.push(name);
 	}
 	if (JSON.stringify(previous) === JSON.stringify(bundles)) return;
@@ -151,11 +152,49 @@ async function runProfilePnpm(context, args, options) {
 	};
 }
 /**
+* Read the registry pnpm's own configuration names in the profile: its `.npmrc` chain and workspace settings,
+* as `pnpm config get registry` resolves them.
+* @param dir Profile directory.
+* @param options The pnpm executable and the time bound.
+* @returns The registry URL as pnpm printed it, or null when pnpm did not answer with one.
+*/
+async function readProfileRegistry(dir, options) {
+	const result = await execa(options.command ?? "pnpm", [
+		...options.args ?? [],
+		"config",
+		"get",
+		"registry"
+	], {
+		cwd: dir,
+		env: {
+			...scrubbedParentEnv(),
+			...options.env
+		},
+		extendEnv: false,
+		reject: false,
+		stdin: "ignore",
+		timeout: options.timeoutMs
+	});
+	const answer = result.exitCode === 0 ? result.stdout.trim().replace(/^[\s\S]*\n/, "").trim() : "";
+	return /^https?:\/\/\S+$/.test(answer) ? answer : null;
+}
+/**
+* The argument that sends one pnpm command to a registry.
+* @param registry - the registry, or null for the one pnpm's own configuration names.
+* @returns `--registry=<url>` for a URL; nothing for null.
+*/
+function registryArguments(registry) {
+	return registry === null ? [] : [`--registry=${registry}`];
+}
+/**
 * Ask the registry what a spec names through `pnpm view`, run in the profile
-* directory so the registry, proxy, and authentication settings of an install apply.
+* directory so the registry, proxy, and authentication settings of an install
+* apply. The lookup makes one request without pnpm's own retries: a registry
+* that does not answer is reported within `timeoutMs`, and the registries
+* configured after it are the retry.
 * @param dir Profile directory.
 * @param spec One registry spec: a package name with an optional range.
-* @param options Cancellation and the time bound.
+* @param options The registry, cancellation, and the time bound.
 * @returns pnpm's exit, output, and how the lookup ended.
 */
 async function viewProfilePackage(dir, spec, options) {
@@ -167,7 +206,9 @@ async function viewProfilePackage(dir, spec, options) {
 		"version",
 		"description",
 		"dsh",
-		"--json"
+		"--json",
+		...registryArguments(options.registry ?? null),
+		"--config.fetch-retries=0"
 	], {
 		cwd: dir,
 		env: {
@@ -205,7 +246,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.
@@ -229,6 +270,13 @@ function classifyInstallFailure(facts) {
 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. */
@@ -252,6 +300,14 @@ var InvalidInstallSpecError = class 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 !== void 0 && Object.hasOwn(GIT_SHORTHAND_HOSTS, shorthand)) return GIT_SHORTHAND_HOSTS[shorthand];
+	const scp = /^git@([^:]+):/i.exec(spec)?.[1];
+	if (scp !== void 0) 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
@@ -280,12 +336,14 @@ function parseInstallSpec(raw) {
 	if (/^\.{1,2}(?:[\\/]|$)/.test(spec)) throw invalid(spec, "a local path must be absolute");
 	if ((GIT_SHORTHAND.test(spec) || GIT_URL.test(spec) || HOSTED_REPOSITORY_URL.test(spec)) && !TARBALL_SPEC.test(spec)) return {
 		kind: "git",
-		spec
+		spec,
+		host: gitHost(spec)
 	};
 	if (/^https?:\/\//i.test(spec)) {
 		if (TARBALL_SPEC.test(spec)) return {
 			kind: "tarball",
-			spec
+			spec,
+			host: new URL(spec).host
 		};
 		throw invalid(spec, "a URL must point at a git repository or a tarball");
 	}
@@ -305,6 +363,82 @@ function parseInstallSpec(raw) {
 		range
 	};
 }
+/** Public npmmirror URL shared by the fallback configuration and public-registry comparison. */
+const NPMMIRROR_REGISTRY = "https://registry.npmmirror.com/";
+/**
+* Parse a registry URL into the form pnpm compares registries in: lower-case host, trailing slash.
+* @param url - the registry as configured or requested.
+* @returns the normalized URL.
+* @throws {Error} for anything but an http(s) URL.
+*/
+function normalizeRegistry(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {}
+	if (parsed === void 0 || parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`a registry must be an http(s) URL: ${url}`);
+	if (!parsed.pathname.endsWith("/")) parsed.pathname += "/";
+	return parsed.href;
+}
+/**
+* The registries one operation asks, first to last.
+*
+* The configured set is the configured first registry and the fallbacks; a
+* requested registry is asked first when it is one of them, alone otherwise,
+* so a private registry never falls through to a public one. pnpm's own
+* registry (`null`) belongs to the set only when what it names is known to
+* be public: npm's own registry or one of the configured fallbacks. While it
+* names anything else, or is unknown, it is asked alone, and a public
+* registry asked instead never falls back into it. A registry pnpm's own
+* configuration already names is asked once.
+* @param requested - the caller's registry; undefined defers to the configured first one.
+* @param configured - the configured first registry, the fallbacks after it, and what pnpm's own configuration names.
+* @returns the registries to ask, in order; never empty.
+*/
+function registryPlan(requested, configured) {
+	const own = configured.resolved === null ? null : normalizeRegistry(configured.resolved);
+	const fallbacks = configured.fallbackRegistries.map(normalizeRegistry);
+	const ownIsPublic = own !== null && (own === "https://registry.npmjs.org/" || fallbacks.includes(own));
+	const keyOf = (registry) => registry === null ? own : normalizeRegistry(registry);
+	const known = [];
+	const keys = [];
+	for (const registry of [configured.registry, ...configured.fallbackRegistries]) {
+		if (registry === null && !ownIsPublic) continue;
+		const key = keyOf(registry);
+		if (keys.includes(key)) continue;
+		known.push(registry === null ? null : normalizeRegistry(registry));
+		keys.push(key);
+	}
+	const first = requested === void 0 ? configured.registry : requested;
+	const firstKey = keyOf(first);
+	const normalizedFirst = first === null ? null : normalizeRegistry(first);
+	if ((first === null || firstKey === own) && !ownIsPublic) return [normalizedFirst];
+	if (!keys.includes(firstKey)) return [normalizedFirst];
+	return [normalizedFirst, ...known.filter((_registry, index) => keys[index] !== firstKey)];
+}
+/** The failures after which another registry can answer differently: this one was unreachable, or its copy may be stale. */
+const NEXT_REGISTRY_KINDS = new Set([
+	"network",
+	"timeout",
+	"not-found",
+	"no-matching-version"
+]);
+/** A line of pnpm or git output that reports a failure, as opposed to a warning or progress line. */
+const ERROR_LINE = /ERR_|ERROR|\berror\b|fatal:|Could not resolve|unable to access|ssh:|\bE[A-Z]{4,}\b/;
+/**
+* What a failed attempt could not reach or get an answer from.
+* @param kind - how the attempt failed.
+* @param log - what the attempt printed.
+* @param spec - the spec the attempt installed.
+* @returns `registry` for a failure another registry can change; `spec-host` when an error line names the host a git
+* or tarball spec is fetched from, which no registry stands in for; `other` for a failure neither explains.
+*/
+function attributeFailure(kind, log, spec) {
+	if (!NEXT_REGISTRY_KINDS.has(kind)) return "other";
+	const host = spec.kind === "git" || spec.kind === "tarball" ? spec.host?.toLowerCase() : void 0;
+	if (host === void 0) return "registry";
+	return log.split("\n").some((line) => ERROR_LINE.test(line) && line.toLowerCase().includes(host)) ? "spec-host" : "registry";
+}
 //#endregion
 //#region lib/types/patch.js
 /** Comment-preserving profile plugin enablement edits. */
@@ -443,6 +577,8 @@ var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializ
 	if (target) Object.defineProperty(target, contextIn.name, descriptor);
 	done = true;
 };
+/** 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",
@@ -493,7 +629,7 @@ function stringField(manifest, field) {
 	return typeof value === "string" ? value : void 0;
 }
 /** 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 : void 0;
 	const bundle = declared !== void 0 && typeof declared.bundle === "object" && declared.bundle !== null;
@@ -504,6 +640,7 @@ function inspectionOf(kind, manifest) {
 		status: "accepted",
 		kind,
 		bundle,
+		registry,
 		...name === void 0 ? {} : { name },
 		...version === void 0 ? {} : { version },
 		...description === void 0 || description === "" ? {} : { description }
@@ -516,16 +653,45 @@ function refused(problem, reason) {
 		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 "";
+	}
+	const error = typeof parsed === "object" && parsed !== null ? parsed.error : void 0;
+	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 {
@@ -533,10 +699,12 @@ 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, {
@@ -561,6 +729,17 @@ let PluginManager = (() => {
 				},
 				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",
@@ -605,6 +784,17 @@ let PluginManager = (() => {
 				},
 				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",
@@ -639,15 +829,20 @@ let PluginManager = (() => {
 			pnpmCommand: z.string().default("pnpm"),
 			outputBytes: z.number().step(1).min(1).default(16384),
 			lockWaitMs: z.number().step(1).min(0).default(12e4),
-			inspectTimeoutMs: z.number().step(1).min(1e3).default(2e4)
+			inspectTimeoutMs: z.number().step(1).min(1e3).default(2e4),
+			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), /* @__PURE__ */ new Set());
+		ownerEntryId;
 		packageOperations = /* @__PURE__ */ new Set();
 		profile;
 		outputBytes;
 		lockWaitMs;
 		inspectTimeoutMs;
 		pnpmCommand;
+		configuredRegistries;
 		ownerContext;
 		abort = new AbortController();
 		/** Installations by request id, from their call until it settles. */
@@ -657,10 +852,15 @@ 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 === void 0 ? null : normalizeRegistry(config.registry),
+				fallbackRegistries: config.fallbackRegistries.map(normalizeRegistry)
+			};
 			ctx.effect(() => async () => {
 				this.abort.abort();
 				await Promise.allSettled([...this.packageOperations]);
@@ -691,8 +891,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);
@@ -710,6 +910,7 @@ 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" : void 0;
 				try {
 					const info = bundleManifest(name, this.profile.dir, this.profile.installAnchor);
 					if (info === void 0) {
@@ -718,18 +919,21 @@ let PluginManager = (() => {
 							enabled,
 							installed,
 							optional,
-							removable,
+							removable: removable && readOnlyReason === void 0,
+							...readOnlyReason === void 0 ? {} : { readOnlyReason },
 							error: { code: "not-bundle" },
 							rows: [],
 							overrides: []
 						});
 						continue;
 					}
-					const readOnlyReason = this.protectsManager(name) ? "management-required" : void 0;
+					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 === void 0 ? {} : { version: info.version },
 						...info.description === void 0 || info.description === "" ? {} : { description: info.description },
+						...meta === void 0 ? {} : { meta },
 						enabled,
 						installed,
 						optional,
@@ -743,7 +947,8 @@ let PluginManager = (() => {
 						enabled,
 						installed,
 						optional,
-						removable,
+						removable: removable && readOnlyReason === void 0,
+						...readOnlyReason === void 0 ? {} : { readOnlyReason },
 						error: managementError(error),
 						rows: [],
 						overrides: []
@@ -752,12 +957,26 @@ let PluginManager = (() => {
 			}
 			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);
@@ -773,18 +992,24 @@ let PluginManager = (() => {
 				...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
+					bundle: null,
+					registry,
+					host: parsed.host
 				};
 				case "tarball":
 					if (parsed.path !== void 0 && !existsSync(parsed.path)) return refused("not-a-package", "the tarball does not exist");
 					return {
 						status: "accepted",
 						kind: "tarball",
-						bundle: null
+						bundle: null,
+						registry,
+						...parsed.host === void 0 ? {} : { host: parsed.host }
 					};
 				case "path": {
 					if (!existsSync(parsed.path)) return refused("not-a-package", "the path does not exist");
@@ -794,7 +1019,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 === void 0) return refused("not-a-package", "the package.json names no package");
 					if (known.has(inspection.name)) return refused("already-installed", `${inspection.name} is already installed`);
 					if (!inspection.bundle) return refused("not-a-bundle", `${inspection.name} declares no dsh.bundle`);
@@ -802,38 +1027,57 @@ 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 === void 0 ? {} : { signal }
+					const registries = [];
+					const refusedBy = (problem, reason) => ({
+						status: "refused",
+						problem,
+						reason,
+						registries
 					});
-					const log = `${view.stderr}${view.cause === void 0 ? "" : `${messageOf(view.cause)}\n`}`.trim();
-					if (view.exitCode !== 0 || view.cause !== void 0 || view.timedOut) {
-						const kind = classifyInstallFailure({
-							log,
-							timedOut: view.timedOut,
-							...view.cause === void 0 ? {} : { cause: view.cause }
+					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 === void 0 ? {} : { signal },
+							registry: current
 						});
-						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 printed = view.stdout.replace(ANSI_SEQUENCE, "").trim();
+						if (view.exitCode !== 0 || view.cause !== void 0 || view.timedOut) {
+							const log = [
+								view.stderr.trim(),
+								printedError(printed),
+								view.cause === void 0 ? "" : messageOf(view.cause)
+							].filter(Boolean).join("\n");
+							const kind = classifyInstallFailure({
+								log,
+								timedOut: view.timedOut,
+								...view.cause === void 0 ? {} : { cause: view.cause }
+							});
+							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)}`);
+						}
+						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 === void 0 ? {
+							...inspection,
+							name: parsed.name
+						} : inspection;
+						if (!named.bundle) return refusedBy("not-a-bundle", `${named.name} declares no dsh.bundle`);
+						return named;
 					}
-					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 === void 0 ? {
-						...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");
 				}
 			}
 		}
@@ -876,23 +1120,24 @@ 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()
+				result: Promise.resolve(null)
 			};
 			const stopped = () => control.abort.signal.aborted;
 			if (requestId !== void 0) this.installs.set(requestId, control);
-			const announce = (phase) => {
+			const announce = (phase, attempt) => {
 				if (requestId !== void 0) this.ownerContext.emit("plugin-manager/install-state", {
 					requestId,
-					phase
+					phase,
+					...attempt === void 0 ? {} : { attempt }
 				});
 			};
 			const result = this.change(async (result) => {
@@ -904,18 +1149,44 @@ 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) {
+					let run;
+					result.registries = [];
+					for (const [index, registry] of plan.entries()) {
+						if (index > 0) await this.restoreFiles(files);
+						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 === void 0) break;
+						const failedAt = attributeFailure(run.kind, run.output, parsedForRegistry(spec));
+						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 === void 0) throw new Error("no registry was asked");
+					if (run.exitCode === 0) delete result.failedAt;
+					if (run.exitCode !== 0) {
 						try {
 							result.pendingBuilds = await readPendingBuilds(this.profile.dir);
 						} 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]);
@@ -925,8 +1196,8 @@ 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 === void 0) throw new ManagementFailure("not-bundle");
-					loadOverlayPatches("dsh", join(dir, manifest.dsh.bundle.patch));
+					if (manifest?.dsh?.bundle === void 0) throw new ManagementFailure("not-bundle");
+					for (const file of bundlePatchPaths(dir, manifest.dsh.bundle)) loadOverlayPatches("dsh", file);
 				} catch (error) {
 					await this.restoreFiles(files);
 					throw error;
@@ -946,12 +1217,19 @@ let PluginManager = (() => {
 				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(() => void 0, () => void 0);
+			control.result = result;
 			return result.finally(() => {
 				if (requestId !== void 0) 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
@@ -966,7 +1244,8 @@ let PluginManager = (() => {
 				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(() => void 0, () => void 0);
 			return { status: "cancelled" };
 		}
 		/** Unload and remove a profile-owned bundle dependency through dsh plugin's pnpm path.
@@ -978,7 +1257,7 @@ let PluginManager = (() => {
 				await this.configure(async () => {
 					const bundle = (await this.listBundles()).find((item) => item.name === name);
 					if (bundle === void 0 || !bundle.removable) throw new ManagementFailure("not-removable");
-					if (this.ownerContext.get("hmr") === void 0 && (this.profile.startedBundles.includes(name) || this.bundleRows(name).some((row) => [...this.ctx.loader.entries()].some((entry) => entry.options.id === row.id && entry.fiber !== void 0)))) throw new ManagementFailure("stop-profile");
+					if (this.ownerContext.get("hmr") === void 0 && (this.profile.startedBundles.includes(name) || bundle.error === void 0 && this.bundleRows(name).some((row) => [...this.ctx.loader.entries()].some((entry) => entry.options.id === row.id && entry.fiber !== void 0)))) throw new ManagementFailure("stop-profile");
 					const contributions = bundle.error === void 0 ? this.bundleRows(name) : [];
 					if (bundle.enabled) {
 						await this.selectBundle(name, false);
@@ -995,25 +1274,34 @@ 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 === void 0) return {
+			if (bundle === void 0) return {
 				rows: [],
 				overrides: []
 			};
-			const patches = loadOverlayPatches("dsh", join(resolveBundleDir("dsh", name, this.profile.installAnchor, this.profile.dir), patch));
+			const dir = resolveBundleDir("dsh", name, this.profile.installAnchor, this.profile.dir);
+			const patches = bundlePatchPaths(dir, bundle).flatMap((file) => loadOverlayPatches("dsh", file));
 			const live = /* @__PURE__ */ 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));
+			if (typeof entry.options.id === "string") 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 !== void 0)]))) {
 				if (typeof row.id !== "string" || typeof row.name !== "string") continue;
-				const entryId = live.get(row.id);
+				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 === void 0 ? {} : { entryId }
+					...entryId === void 0 ? {} : { entryId },
+					...meta === void 0 ? {} : { meta }
 				});
 			}
 			const declared = new Set(rows.map((row) => row.rowId));
@@ -1097,6 +1385,7 @@ let PluginManager = (() => {
 			const manifest = readProfileManifest("dsh", this.profile.dir);
 			const previous = manifest.dsh?.profile?.bundles ?? [];
 			if ((enabled || !previous.includes(name)) && bundleManifest(name, this.profile.dir, this.profile.installAnchor) === void 0) throw new ManagementFailure("not-bundle");
+			if (enabled) this.bundleRows(name);
 			if (!enabled && previous.includes(name)) {
 				if (this.protectsManager(name)) throw new ManagementFailure("management-required");
 			}
@@ -1110,14 +1399,24 @@ let PluginManager = (() => {
 				}
 			};
 			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 === void 0) return [];
-			return flatten(composeEntries([loadOverlayPatches("dsh", join(resolveBundleDir("dsh", name, this.profile.installAnchor, this.profile.dir), info.dsh.bundle.patch))]));
+			return flatten(composeEntries([bundlePatchPaths(resolveBundleDir("dsh", name, this.profile.installAnchor, this.profile.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) {
+				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");