@stolyarovmn/dsh-ui-registry-aggregator 0.4.13

package/lib/core.js

@@ -0,0 +1,1241 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import ipaddr from "ipaddr.js";
+import { Agent } from "undici";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_PLUGINS = 2_000;
+const DEFAULT_MAX_REDIRECTS = 3;
+const EVIDENCE_CACHE_TTL_MS = 10 * 60 * 1000;
+const METADATA_CACHE_TTL_MS = 30 * 60 * 1000;
+const npmDownloadCache = new Map();
+const npmManifestCache = new Map();
+const githubManifestCache = new Map();
+const githubStatsCache = new Map();
+const browseDiscoveryCache = new Map();
+const BROWSE_DISCOVERY_TTL_MS = 2 * 60 * 1000;
+
+function cachedEvidence(cache, key) {
+	const entry = cache.get(key);
+	if (!entry) return undefined;
+	if (entry.expiresAt <= Date.now()) {
+		cache.delete(key);
+		return undefined;
+	}
+	return entry.value;
+}
+
+function cacheEvidence(cache, key, value, ttlMs = EVIDENCE_CACHE_TTL_MS) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return;
+	cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+}
+
+export const SOURCE_TYPES = Object.freeze([
+	"dsh-plugin-shop",
+	"dshplugin-app",
+	"npm",
+	"github",
+	"custom-json",
+	"corporate",
+]);
+
+export const NPM_DISCOVERY_KEYWORDS = Object.freeze([
+	"dsh-plugin",
+	"deepseek-harness",
+	"deepseek-harness-plugin",
+	"dsh-plugins",
+]);
+
+export const GITHUB_DISCOVERY_TOPICS = Object.freeze([
+	"dsh-plugin",
+	"deepseek-harness-plugin",
+	"dsh-plugins",
+]);
+
+// "dsh-plugin" alone is heavily polluted by repositories using DSH for unrelated
+// acronyms. Require DeepSeek Harness context unless the repository uses the
+// unambiguous deepseek-harness-plugin topic.
+export const GITHUB_DISCOVERY_QUERIES = Object.freeze([
+	"topic:deepseek-harness topic:dsh-plugin",
+	"topic:deepseek-harness-plugin",
+	"topic:deepseek-harness topic:dsh-plugins",
+]);
+
+function text(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function finiteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isoDate(value) {
+	const raw = text(value);
+	if (!raw) return undefined;
+	const timestamp = Date.parse(raw);
+	return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : undefined;
+}
+
+function latestIsoDate(left, right) {
+	const values = [left, right].filter(Boolean);
+	if (!values.length) return undefined;
+	return values.sort((a, b) => Date.parse(b) - Date.parse(a))[0];
+}
+
+function cachedValue(cache, key) {
+	const entry = cache.get(key);
+	if (!entry) return undefined;
+	if (entry.expiresAt <= Date.now()) {
+		cache.delete(key);
+		return undefined;
+	}
+	return entry.value;
+}
+
+function cacheValue(cache, key, value, ttlMs = METADATA_CACHE_TTL_MS) {
+	cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+}
+
+export function releaseChannel(version) {
+	const value = text(version);
+	if (!value) return undefined;
+	const prerelease = value.match(/^[0-9]+\.[0-9]+\.[0-9]+-([^+]+)/u)?.[1]?.toLowerCase();
+	if (!prerelease) return /^[0-9]+\.[0-9]+\.[0-9]+(?:\+.+)?$/u.test(value) ? "stable" : undefined;
+	if (/(?:^|[.-])alpha(?:[.-]|$)|(?:^|[.-])a(?:[.-]|$)/u.test(prerelease)) return "alpha";
+	if (/(?:^|[.-])beta(?:[.-]|$)|(?:^|[.-])b(?:[.-]|$)/u.test(prerelease)) return "beta";
+	if (/(?:^|[.-])rc(?:[.-]|$)/u.test(prerelease)) return "rc";
+	return "prerelease";
+}
+
+const TAG_ALIASES = new Map([
+	["web-gui", "ui"],
+	["client-plugin", "ui"],
+	["dsh-plugin-ui", "ui"],
+	["dsh-ui", "ui"],
+	["dsh-plugin-theme", "theme"],
+	["dsh-plugin-provider", "provider"],
+	["dsh-plugin-workflow", "workflow"],
+	["dsh-plugin-integration", "integration"],
+	["dsh-plugin-tool", "tool"],
+	["dsh-plugin-automation", "automation"],
+	["dsh-plugin-schedule", "schedule"],
+	["dsh-plugin-scheduler", "scheduler"],
+	["dsh-skill", "skill"],
+	["dsh-plugin-bundle", "bundle"],
+	["dsh-plugin-desktop", "desktop"],
+]);
+
+export const FILTER_TAGS = Object.freeze([
+	"ui", "theme", "provider", "workflow", "integration", "tool",
+	"automation", "schedule", "scheduler", "skill", "bundle", "desktop",
+]);
+const DISPLAY_TAGS = new Set(FILTER_TAGS);
+
+function tagValues(value) {
+	if (Array.isArray(value)) return value.flatMap(tagValues);
+	if (typeof value !== "string") return [];
+	return value.split(/[\s,]+/u).map((item) => item.trim().toLowerCase()).filter(Boolean);
+}
+
+function normalizeTags(record) {
+	const raw = [
+		...tagValues(record.tags),
+		...tagValues(record.keywords),
+		...tagValues(record.topics),
+		...tagValues(record.category),
+		...tagValues(record.dsh?.catalog?.category),
+	];
+	const tags = [];
+	for (const token of raw) {
+		const mapped = TAG_ALIASES.get(token) ?? token;
+		if (DISPLAY_TAGS.has(mapped) && !tags.includes(mapped)) tags.push(mapped);
+	}
+	return tags.slice(0, 8);
+}
+
+export function normalizeSource(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const id = text(value.id);
+	const type = text(value.type);
+	const url = text(value.url);
+	if (!id || id.length > 64 || !/^[a-z0-9][a-z0-9._~-]*$/i.test(id) || !type || !SOURCE_TYPES.includes(type)) return undefined;
+	if (url && url.length > 2_048) return undefined;
+	return {
+		id,
+		name: (text(value.name) ?? id).slice(0, 120),
+		type,
+		...(url ? { url } : {}),
+		enabled: value.enabled !== false,
+	};
+}
+
+export function canonicalRepository(value) {
+	const raw = text(value);
+	if (!raw) return undefined;
+	let normalized = raw.replace(/^git\+/, "").replace(/^git@github\.com:/i, "https://github.com/");
+	try {
+		const url = new URL(normalized);
+		url.hash = "";
+		url.search = "";
+		normalized = url.toString();
+	} catch {
+		return raw.replace(/\.git$/i, "").replace(/\/$/, "").toLowerCase();
+	}
+	return normalized.replace(/\.git$/i, "").replace(/\/$/, "").toLowerCase();
+}
+
+function safeInstallSpec(type, value) {
+	const spec = text(value);
+	if (!spec || spec.length > 500 || /[\s;&|`$<>"'%!^()]/u.test(spec)) return undefined;
+	if (type === "npm") {
+		return /^(?:@[a-z0-9][a-z0-9._~-]*\/[a-z0-9][a-z0-9._~-]*|[a-z0-9][a-z0-9._~-]*)(?:@[a-z0-9][a-z0-9._+~-]*)?$/i.test(spec) ? spec : undefined;
+	}
+	try {
+		const url = new URL(spec.replace(/^git\+/, ""));
+		return url.protocol === "https:" && !url.username && !url.password ? spec : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function normalizeInstall(record, packageName, repository, version) {
+	const raw = record.install;
+	if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+		const type = raw.type === "npm" || raw.type === "git" ? raw.type : undefined;
+		const spec = type ? safeInstallSpec(type, raw.spec) : undefined;
+		if (type && spec) return { type, spec };
+	}
+	const explicit = text(raw);
+	if (explicit) {
+		const type = /^(?:git\+|https?:\/\/|ssh:|git:)/i.test(explicit) ? "git" : "npm";
+		const spec = safeInstallSpec(type, explicit);
+		if (spec) return { type, spec };
+	}
+	if (packageName) {
+		const spec = safeInstallSpec("npm", version ? `${packageName}@${version}` : packageName);
+		if (spec) return { type: "npm", spec };
+	}
+	if (repository) {
+		const spec = safeInstallSpec("git", repository);
+		if (spec) return { type: "git", spec };
+	}
+	return undefined;
+}
+
+function sourceAttribution(source) {
+	return {
+		id: source.id,
+		name: source.name,
+		type: source.type,
+		...(source.url ? { url: source.url } : {}),
+	};
+}
+
+export function normalizePlugin(record, source) {
+	if (!record || typeof record !== "object" || Array.isArray(record)) return undefined;
+	const identityInput = record.identity && typeof record.identity === "object" ? record.identity : {};
+	const packageName = (text(identityInput.package) ?? text(record.package) ?? text(record.packageName) ?? text(record.npm))?.slice(0, 214);
+	const repository = canonicalRepository(text(identityInput.repository ?? record.repository ?? record.repo)?.slice(0, 2_048));
+	const sourceSpecificId = (text(record.id) ?? text(record.slug) ?? text(record.name))?.slice(0, 200);
+	const name = (text(record.name) ?? packageName ?? repository?.split("/").pop() ?? sourceSpecificId)?.slice(0, 200);
+	if (!name || (!packageName && !repository && !sourceSpecificId)) return undefined;
+	const version = (text(record.version) ?? text(record.latestVersion))?.slice(0, 100);
+	const description = (text(record.description) ?? text(record.summary))?.slice(0, 4_000);
+	const install = normalizeInstall(record, packageName, repository, version);
+	const verified = typeof record.evidence?.verified === "boolean" ? record.evidence.verified
+		: typeof record.verified === "boolean" ? record.verified : undefined;
+	const stars = finiteNumber(record.evidence?.stars) ?? finiteNumber(record.stars) ?? finiteNumber(record.stargazers_count);
+	const downloads30d = finiteNumber(record.evidence?.downloads30d) ?? finiteNumber(record.downloads30d) ?? finiteNumber(record.downloads);
+	const rating = finiteNumber(record.evidence?.rating) ?? finiteNumber(record.rating);
+	const ratingCount = finiteNumber(record.evidence?.ratingCount) ?? finiteNumber(record.ratingCount) ?? finiteNumber(record.reviews);
+	const compatibility = text(record.evidence?.compatibility) ?? text(record.compatibility);
+	const dshCompatibility = text(record.evidence?.dshCompatibility) ?? text(record.dshCompatibility);
+	const releasedAt = isoDate(record.evidence?.releasedAt ?? record.releasedAt ?? record.publishedAt ?? record.date ?? record.updated);
+	const repositoryUpdatedAt = isoDate(record.evidence?.repositoryUpdatedAt ?? record.repositoryUpdatedAt ?? record.pushed_at ?? record.updated_at);
+	const maintenanceScore = finiteNumber(record.evidence?.maintenanceScore) ?? finiteNumber(record.maintenanceScore);
+	const installability = ["bundle", "not-bundle", "unknown"].includes(record.evidence?.installability) ? record.evidence.installability
+		: ["bundle", "not-bundle", "unknown"].includes(record.installability) ? record.installability : undefined;
+	const channel = text(record.evidence?.releaseChannel) ?? releaseChannel(version);
+	const tags = normalizeTags(record);
+	return {
+		identity: {
+			...(packageName ? { package: packageName } : {}),
+			...(repository ? { repository } : {}),
+			fallback: `${source.id}:${sourceSpecificId ?? name}`,
+		},
+		name,
+		...(description ? { description } : {}),
+		...(version ? { version } : {}),
+		versions: version ? [version] : [],
+		tags,
+		...(install ? { install } : {}),
+		sources: [sourceAttribution(source)],
+		...((verified !== undefined || stars !== undefined || downloads30d !== undefined || rating !== undefined || ratingCount !== undefined || compatibility || dshCompatibility || releasedAt || repositoryUpdatedAt || maintenanceScore !== undefined || installability || channel) ? {
+			evidence: {
+				...(verified !== undefined ? { verified } : {}),
+				...(stars !== undefined ? { stars } : {}),
+				...(downloads30d !== undefined ? { downloads30d } : {}),
+				...(rating !== undefined ? { rating } : {}),
+				...(ratingCount !== undefined ? { ratingCount } : {}),
+				...(compatibility ? { compatibility } : {}),
+				...(dshCompatibility ? { dshCompatibility } : {}),
+				...(releasedAt ? { releasedAt } : {}),
+				...(repositoryUpdatedAt ? { repositoryUpdatedAt } : {}),
+				...(maintenanceScore !== undefined ? { maintenanceScore } : {}),
+				...(installability ? { installability } : {}),
+				...(channel ? { releaseChannel: channel } : {}),
+			},
+		} : {}),
+	};
+}
+
+export function pluginIdentity(plugin) {
+	if (plugin.identity?.package) return `npm:${plugin.identity.package.toLowerCase()}`;
+	if (plugin.identity?.repository) return `git:${canonicalRepository(plugin.identity.repository)}`;
+	return `source:${plugin.identity?.fallback ?? plugin.name.toLowerCase()}`;
+}
+
+function preferInstall(current, incoming) {
+	if (!current) return incoming;
+	if (!incoming) return current;
+	if (current.type !== "npm" && incoming.type === "npm") return incoming;
+	return current;
+}
+
+function mergeEvidence(left, right) {
+	if (!left && !right) return undefined;
+	const stars = Math.max(left?.stars ?? -Infinity, right?.stars ?? -Infinity);
+	const downloads30d = Math.max(left?.downloads30d ?? -Infinity, right?.downloads30d ?? -Infinity);
+	const ratingSource = (right?.ratingCount ?? -1) > (left?.ratingCount ?? -1) ? right : left;
+	return {
+		...((left?.verified === true || right?.verified === true) ? { verified: true } : {}),
+		...(Number.isFinite(stars) ? { stars } : {}),
+		...(Number.isFinite(downloads30d) ? { downloads30d } : {}),
+		...(ratingSource?.rating !== undefined ? { rating: ratingSource.rating } : {}),
+		...(ratingSource?.ratingCount !== undefined ? { ratingCount: ratingSource.ratingCount } : {}),
+		...(left?.compatibility || right?.compatibility ? { compatibility: left?.compatibility ?? right?.compatibility } : {}),
+		...(left?.dshCompatibility || right?.dshCompatibility ? { dshCompatibility: left?.dshCompatibility ?? right?.dshCompatibility } : {}),
+		...(latestIsoDate(left?.releasedAt, right?.releasedAt) ? { releasedAt: latestIsoDate(left?.releasedAt, right?.releasedAt) } : {}),
+		...(latestIsoDate(left?.repositoryUpdatedAt, right?.repositoryUpdatedAt) ? { repositoryUpdatedAt: latestIsoDate(left?.repositoryUpdatedAt, right?.repositoryUpdatedAt) } : {}),
+		...(Math.max(left?.maintenanceScore ?? -Infinity, right?.maintenanceScore ?? -Infinity) > -Infinity ? { maintenanceScore: Math.max(left?.maintenanceScore ?? -Infinity, right?.maintenanceScore ?? -Infinity) } : {}),
+		...(left?.releaseChannel || right?.releaseChannel ? { releaseChannel: left?.releaseChannel ?? right?.releaseChannel } : {}),
+		...((left?.installability === "bundle" || right?.installability === "bundle")
+			? { installability: "bundle" }
+			: (left?.installability === "not-bundle" || right?.installability === "not-bundle")
+				? { installability: "not-bundle" }
+				: (left?.installability === "unknown" || right?.installability === "unknown")
+					? { installability: "unknown" } : {}),
+	};
+}
+
+function identityAliases(plugin) {
+	const aliases = [];
+	if (plugin.identity?.package) aliases.push(`npm:${plugin.identity.package.toLowerCase()}`);
+	if (plugin.identity?.repository) aliases.push(`git:${canonicalRepository(plugin.identity.repository)}`);
+	if (aliases.length === 0) aliases.push(`source:${plugin.identity?.fallback ?? plugin.name.toLowerCase()}`);
+	return aliases;
+}
+
+function clonePlugin(plugin) {
+	return { ...plugin, sources: [...plugin.sources], versions: [...(plugin.versions ?? [])], tags: [...(plugin.tags ?? [])] };
+}
+
+function mergePluginRecords(current, plugin) {
+	const sources = new Map(current.sources.map((source) => [source.id, source]));
+	for (const source of plugin.sources) sources.set(source.id, source);
+	return {
+		...current,
+		identity: {
+			...(current.identity ?? {}),
+			...(plugin.identity?.package && !current.identity?.package ? { package: plugin.identity.package } : {}),
+			...(plugin.identity?.repository && !current.identity?.repository ? { repository: plugin.identity.repository } : {}),
+		},
+		name: current.name || plugin.name,
+		description: (plugin.description?.length ?? 0) > (current.description?.length ?? 0) ? plugin.description : current.description,
+		version: current.version ?? plugin.version,
+		versions: [...new Set([...(current.versions ?? []), ...(plugin.versions ?? [])])],
+		tags: [...new Set([...(current.tags ?? []), ...(plugin.tags ?? [])])].slice(0, 8),
+		install: preferInstall(current.install, plugin.install),
+		sources: [...sources.values()],
+		evidence: mergeEvidence(current.evidence, plugin.evidence),
+	};
+}
+
+export function dedupePlugins(plugins) {
+	const aliases = new Map();
+	const records = new Set();
+	for (const plugin of plugins) {
+		const keys = identityAliases(plugin);
+		const matches = [...new Set(keys.map((key) => aliases.get(key)).filter(Boolean))];
+		let target;
+		if (matches.length === 0) {
+			target = { plugin: clonePlugin(plugin), aliases: new Set(keys) };
+			records.add(target);
+		} else {
+			target = matches[0];
+			target.plugin = mergePluginRecords(target.plugin, plugin);
+			for (const other of matches.slice(1)) {
+				target.plugin = mergePluginRecords(target.plugin, other.plugin);
+				for (const key of other.aliases) target.aliases.add(key);
+				records.delete(other);
+			}
+			for (const key of keys) target.aliases.add(key);
+		}
+		for (const key of identityAliases(target.plugin)) target.aliases.add(key);
+		for (const key of target.aliases) aliases.set(key, target);
+	}
+	return [...records].map((record) => record.plugin).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function searchPlugins(plugins, query) {
+	const needle = text(query)?.toLowerCase();
+	if (!needle) return plugins;
+	return plugins.filter((plugin) => [
+		plugin.name,
+		plugin.description,
+		plugin.identity?.package,
+		plugin.identity?.repository,
+		...(plugin.tags ?? []),
+		plugin.evidence?.releaseChannel,
+		...(plugin.sources ?? []).flatMap((source) => [source.name, source.type]),
+	].some((value) => typeof value === "string" && value.toLowerCase().includes(needle)));
+}
+
+export function isPrivateAddress(address) {
+	try {
+		const parsed = ipaddr.process(address);
+		return parsed.range() !== "unicast";
+	} catch {
+		return true;
+	}
+}
+
+function abortable(promise, signal) {
+	if (signal.aborted) return Promise.reject(signal.reason ?? new Error("source request aborted"));
+	return new Promise((resolve, reject) => {
+		const abort = () => reject(signal.reason ?? new Error("source request aborted"));
+		signal.addEventListener("abort", abort, { once: true });
+		promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+
+async function assertSafeUrl(url, resolveHost, signal, authenticated, allowPrivateNetwork) {
+	if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error("only http(s) catalog URLs are supported");
+	if (url.username || url.password) throw new Error("credentials in source URLs are not allowed");
+	if (authenticated && url.protocol !== "https:") throw new Error("authenticated sources require HTTPS");
+	const hostname = url.hostname.replace(/^\[|\]$/g, "");
+	if (hostname === "localhost" || hostname.endsWith(".localhost")) throw new Error("private network destinations are blocked");
+	const resolved = await abortable(Promise.resolve(resolveHost(hostname)), signal);
+	const addresses = resolved.map((row) => typeof row === "string" ? { address: row, family: isIP(row) } : row)
+		.filter((row) => typeof row?.address === "string" && (row.family === 4 || row.family === 6));
+	if (!addresses.length) throw new Error("source hostname resolved to no usable address");
+	if (!allowPrivateNetwork && addresses.some((row) => isPrivateAddress(row.address))) throw new Error("private network destinations are blocked");
+	return addresses[0];
+}
+
+async function defaultResolveHost(hostname) {
+	if (isIP(hostname)) return [{ address: hostname, family: isIP(hostname) }];
+	return dnsLookup(hostname, { all: true, verbatim: true });
+}
+
+function pinnedDispatcher(address, factory) {
+	if (factory) return factory(address);
+	return new Agent({ connect: { lookup(_hostname, options, callback) {
+		if (options?.all) callback(null, [address]);
+		else callback(null, address.address, address.family);
+	} } });
+}
+
+async function readResponseBytes(response, maxBytes) {
+	const declared = Number(response.headers.get("content-length"));
+	if (Number.isFinite(declared) && declared > maxBytes) throw new Error(`catalog response exceeds ${maxBytes} bytes`);
+	if (!response.body?.getReader) {
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		if (bytes.byteLength > maxBytes) throw new Error(`catalog response exceeds ${maxBytes} bytes`);
+		return bytes;
+	}
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > maxBytes) {
+			await reader.cancel();
+			throw new Error(`catalog response exceeds ${maxBytes} bytes`);
+		}
+		chunks.push(value);
+	}
+	const joined = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) { joined.set(chunk, offset); offset += chunk.byteLength; }
+	return joined;
+}
+
+export async function fetchJson(urlInput, source, options = {}) {
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	if (typeof fetchImpl !== "function") throw new Error("Host fetch is unavailable");
+	const resolveHost = options.resolveHost ?? defaultResolveHost;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const maxBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+	const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+	const authToken = text(options.authToken);
+	let url = new URL(urlInput);
+	const headers = { accept: "application/json", "user-agent": "dsh-plugin-sources/0.2", ...(authToken ? { authorization: `Bearer ${authToken}` } : {}) };
+	const controller = new AbortController();
+	let timedOut = false;
+	const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+	const forwardAbort = () => controller.abort(options.signal?.reason);
+	options.signal?.addEventListener("abort", forwardAbort, { once: true });
+	try {
+		for (let redirects = 0; redirects <= maxRedirects; redirects++) {
+			let dispatcher;
+			try {
+				const address = await assertSafeUrl(url, resolveHost, controller.signal, Boolean(authToken), options.allowPrivateNetwork === true);
+				dispatcher = options.fetchImpl && !options.dispatcherFactory ? undefined : pinnedDispatcher(address, options.dispatcherFactory);
+				let response;
+				try {
+					response = await fetchImpl(url, { method: "GET", headers, redirect: "manual", signal: controller.signal, dispatcher });
+				} catch (error) {
+					if (timedOut) throw new Error("source request timed out");
+					if (options.signal?.aborted) throw new Error("source request aborted");
+					throw new Error(`source request failed: ${String(error?.message ?? error)}`);
+				}
+				if ([301, 302, 303, 307, 308].includes(response.status)) {
+					const location = response.headers.get("location");
+					await response.body?.cancel?.();
+					if (!location) throw new Error(`source redirect ${response.status} has no Location header`);
+					if (redirects === maxRedirects) throw new Error("source redirected too many times");
+					const next = new URL(location, url);
+					if (authToken && next.origin !== url.origin) throw new Error("authenticated source cannot redirect to another origin");
+					url = next;
+					continue;
+				}
+				if (!response.ok) {
+					await response.body?.cancel?.();
+					throw new Error(`source returned HTTP ${response.status}`);
+				}
+				let bytes;
+				try {
+					bytes = await readResponseBytes(response, maxBytes);
+				} catch (error) {
+					if (timedOut) throw new Error("source request timed out");
+					if (options.signal?.aborted) throw new Error("source request aborted");
+					throw error;
+				}
+				try {
+					return JSON.parse(new TextDecoder().decode(bytes));
+				} catch {
+					throw new Error("source returned malformed JSON");
+				}
+			} finally {
+				await dispatcher?.close?.();
+			}
+		}
+		throw new Error("source redirected too many times");
+	} catch (error) {
+		if (timedOut) throw new Error("source request timed out");
+		if (options.signal?.aborted) throw new Error("source request aborted");
+		throw error;
+	} finally {
+		clearTimeout(timer);
+		options.signal?.removeEventListener("abort", forwardAbort);
+	}
+}
+
+function catalogRows(manifest) {
+	if (Array.isArray(manifest)) return manifest;
+	if (manifest && typeof manifest === "object") {
+		for (const key of ["plugins", "items", "results"]) if (Array.isArray(manifest[key])) return manifest[key];
+	}
+	throw new Error("catalog JSON must be an array or contain plugins/items/results");
+}
+
+function normalizeCatalog(manifest, source, maxPlugins) {
+	return catalogRows(manifest).slice(0, maxPlugins).map((row) => normalizePlugin(row, source)).filter(Boolean);
+}
+
+function npmKeywords(entry) {
+	const value = entry?.package?.keywords;
+	if (Array.isArray(value)) return value.map((keyword) => String(keyword).toLowerCase());
+	if (typeof value === "string") return value.split(/[\s,]+/u).map((keyword) => keyword.toLowerCase()).filter(Boolean);
+	return [];
+}
+
+function npmEntryIsDshPlugin(entry) {
+	const keywords = new Set(npmKeywords(entry));
+	return NPM_DISCOVERY_KEYWORDS.some((keyword) => keywords.has(keyword));
+}
+
+function npmRows(manifest, { requireDiscoveryKeyword = false } = {}) {
+	if (!manifest || !Array.isArray(manifest.objects)) throw new Error("npm search returned an invalid response");
+	return manifest.objects.filter((entry) => !requireDiscoveryKeyword || npmEntryIsDshPlugin(entry)).map((entry) => {
+		const pkg = entry?.package ?? {};
+		const links = pkg.links ?? {};
+		return {
+			id: pkg.name,
+			name: pkg.name,
+			description: pkg.description,
+			version: pkg.version,
+			package: pkg.name,
+			repository: links.repository,
+			keywords: pkg.keywords,
+			install: { type: "npm", spec: pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name },
+			evidence: {
+				verified: entry?.flags?.unstable === false,
+				...(typeof entry?.downloads?.monthly === "number" ? { downloads30d: entry.downloads.monthly } : {}),
+				...(isoDate(pkg.date ?? entry?.updated) ? { releasedAt: isoDate(pkg.date ?? entry?.updated) } : {}),
+				...(typeof entry?.score?.detail?.maintenance === "number" ? { maintenanceScore: entry.score.detail.maintenance } : {}),
+			},
+		};
+	});
+}
+
+function exactNpmPackageName(value) {
+	const needle = text(value);
+	if (!needle) return undefined;
+	const valid = /^(?:@[a-z0-9][a-z0-9._~-]*\/[a-z0-9][a-z0-9._~-]*|[a-z0-9][a-z0-9._~-]*)$/i.test(needle);
+	if (!valid) return undefined;
+	// A one-word search such as "schedule" is a discovery query, not a useful
+	// exact-registry probe. Scoped names and package-style hyphenated names are.
+	return needle.startsWith("@") || needle.includes("-") ? needle : undefined;
+}
+
+function npmRegistryBase(sourceUrl) {
+	const url = new URL(sourceUrl ?? "https://registry.npmjs.org");
+	if (/\/-\/v1\/search\/?$/u.test(url.pathname)) url.pathname = url.pathname.replace(/\/-\/v1\/search\/?$/u, "/");
+	if (!url.pathname.endsWith("/")) url.pathname += "/";
+	url.search = "";
+	url.hash = "";
+	return url;
+}
+
+function encodedNpmPackageName(packageName) {
+	return packageName.startsWith("@")
+		? `@${encodeURIComponent(packageName.slice(1).split("/")[0])}%2F${encodeURIComponent(packageName.split("/")[1] ?? "")}`
+		: encodeURIComponent(packageName);
+}
+
+function npmPackumentUrl(source, packageName) {
+	const base = npmRegistryBase(source?.url);
+	return new URL(encodedNpmPackageName(packageName), base);
+}
+
+function latestManifestFromPackument(packument, packageName) {
+	if (!packument || typeof packument !== "object" || Array.isArray(packument)) throw new Error("npm packument returned an invalid response");
+	if (text(packument.name) && text(packument.version)) return packument;
+	const latest = text(packument?.["dist-tags"]?.latest);
+	const manifest = latest ? packument?.versions?.[latest] : undefined;
+	if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new Error("npm packument has no latest manifest");
+	return manifest;
+}
+
+function npmLatestRow(packument, packageName) {
+	const manifest = latestManifestFromPackument(packument, packageName);
+	const name = text(manifest.name) ?? text(packument?.name) ?? packageName;
+	const version = text(manifest.version);
+	if (!name || !version) throw new Error("npm latest manifest is missing name/version");
+	const repository = typeof manifest.repository === "string" ? manifest.repository : text(manifest.repository?.url);
+	const explicit = text(manifest?.peerDependencies?.["@deepseek-ai/dsh"])
+		?? text(manifest?.engines?.dsh)
+		?? text(manifest?.dsh?.compatibility);
+	return {
+		id: name,
+		name,
+		description: manifest.description,
+		version,
+		package: name,
+		...(repository ? { repository } : {}),
+		keywords: manifest.keywords,
+		install: { type: "npm", spec: `${name}@${version}` },
+		evidence: {
+			...manifestInstallability(manifest),
+			...(explicit ? { dshCompatibility: explicit } : {}),
+			...(isoDate(manifest.date ?? manifest.publishedAt) ? { releasedAt: isoDate(manifest.date ?? manifest.publishedAt) } : {}),
+		},
+	};
+}
+
+function githubRows(manifest) {
+	if (!manifest || !Array.isArray(manifest.items)) throw new Error("GitHub search returned an invalid response");
+	return manifest.items.map((repo) => ({
+		id: String(repo.id ?? repo.full_name ?? repo.name),
+		name: repo.name ?? repo.full_name,
+		description: repo.description,
+		repository: repo.html_url ?? repo.clone_url,
+		topics: repo.topics,
+		install: (repo.clone_url ?? repo.html_url) ? { type: "git", spec: repo.clone_url ?? repo.html_url } : undefined,
+		evidence: {
+			stars: repo.stargazers_count,
+			...(isoDate(repo.pushed_at ?? repo.updated_at) ? { repositoryUpdatedAt: isoDate(repo.pushed_at ?? repo.updated_at) } : {}),
+		},
+	}));
+}
+
+export function createAdapter(sourceInput, options = {}) {
+	const source = normalizeSource(sourceInput);
+	if (!source) throw new Error("invalid plugin source configuration");
+	const maxPlugins = options.maxPlugins ?? DEFAULT_MAX_PLUGINS;
+	const authToken = options.authToken ?? options.resolveAuthToken?.(source);
+	const allowPrivateNetwork = options.allowPrivateNetwork === true || options.resolveAllowPrivateNetwork?.(source) === true;
+	const requestOptions = { ...options, ...(authToken ? { authToken } : {}), allowPrivateNetwork };
+	const request = (url) => fetchJson(url, source, requestOptions);
+	const customList = async () => {
+		if (!source.url) throw new Error(`${source.type} source requires a catalog URL`);
+		return normalizeCatalog(await request(source.url), source, maxPlugins);
+	};
+	let list;
+	let search;
+	if (["custom-json", "corporate", "dsh-plugin-shop", "dshplugin-app"].includes(source.type)) {
+		list = customList;
+		search = async (query) => searchPlugins(await customList(), query);
+	} else if (source.type === "npm") {
+		search = async (query = "") => {
+			const base = source.url && /\/-\/v1\/search\/?$/u.test(new URL(source.url).pathname)
+				? source.url
+				: new URL("-/v1/search", npmRegistryBase(source.url)).toString();
+			const size = String(Math.min(maxPlugins, 250));
+			const needle = text(query);
+			const exactName = exactNpmPackageName(needle);
+			const keywordBatches = NPM_DISCOVERY_KEYWORDS.map(async (keyword) => {
+				const url = new URL(base);
+				url.searchParams.set("text", [`keywords:${keyword}`, needle].filter(Boolean).join(" "));
+				url.searchParams.set("size", size);
+				return normalizeCatalog(npmRows(await request(url)), source, maxPlugins);
+			});
+			const rawQueryBatch = needle ? [async () => {
+				const url = new URL(base);
+				url.searchParams.set("text", needle);
+				url.searchParams.set("size", size);
+				return normalizeCatalog(npmRows(await request(url), { requireDiscoveryKeyword: true }), source, maxPlugins);
+			}] : [];
+			const exactBatch = exactName ? [async () => {
+				try {
+					return normalizeCatalog([npmLatestRow(await request(npmPackumentUrl(source, exactName)), exactName)], source, 1);
+				} catch (error) {
+					if (/HTTP 404|status 404|Not Found/i.test(String(error?.message ?? error))) return [];
+					throw error;
+				}
+			}] : [];
+			const batches = await Promise.all([...keywordBatches, ...rawQueryBatch.map((load) => load()), ...exactBatch.map((load) => load())]);
+			return searchPlugins(dedupePlugins(batches.flat()), query).slice(0, maxPlugins);
+		};
+		list = () => search("");
+	} else if (source.type === "github") {
+		search = async (query = "") => {
+			const base = source.url ?? "https://api.github.com/search/repositories";
+			const perPage = String(Math.min(maxPlugins, 100));
+			const batches = await Promise.all(GITHUB_DISCOVERY_QUERIES.map(async (discoveryQuery) => {
+				const url = new URL(base);
+				url.searchParams.set("q", [discoveryQuery, text(query)].filter(Boolean).join(" "));
+				url.searchParams.set("per_page", perPage);
+				return normalizeCatalog(githubRows(await request(url)), source, maxPlugins);
+			}));
+			return searchPlugins(dedupePlugins(batches.flat()), query).slice(0, maxPlugins);
+		};
+		list = () => search("");
+	}
+	return {
+		source,
+		async health() {
+			const started = Date.now();
+			try {
+				let plugins = await list();
+				if ((source.type === "npm" || source.type === "github") && shouldVerifyRegistryBundles(options)) {
+					plugins = await enrichInstallability(plugins, options);
+					plugins = plugins.filter((plugin) => plugin.evidence?.installability === "bundle");
+				}
+				return { ok: true, latencyMs: Date.now() - started, count: plugins.length };
+			} catch (error) {
+				return { ok: false, latencyMs: Date.now() - started, error: String(error?.message ?? error) };
+			}
+		},
+		list,
+		search,
+		async get(id) { return (await list()).find((plugin) => pluginIdentity(plugin) === id || plugin.name === id); },
+	};
+}
+
+function validatedSources(sourceInputs, options) {
+	const maxSources = options.maxSources ?? 20;
+	if (!Array.isArray(sourceInputs) || sourceInputs.length > maxSources) throw new Error(`at most ${maxSources} plugin sources are allowed`);
+	const sources = sourceInputs.map(normalizeSource);
+	if (sources.some((source) => !source)) throw new Error("invalid plugin source configuration");
+	if (new Set(sources.map((source) => source.id)).size !== sources.length) throw new Error("plugin source ids must be unique");
+	return sources;
+}
+
+async function mapConcurrent(items, concurrency, worker) {
+	const output = new Array(items.length);
+	let cursor = 0;
+	async function run() {
+		while (true) {
+			const index = cursor++;
+			if (index >= items.length) return;
+			output[index] = await worker(items[index], index);
+		}
+	}
+	await Promise.all(Array.from({ length: Math.min(Math.max(1, concurrency), items.length) }, run));
+	return output;
+}
+
+export async function healthSources(sourceInputs, options = {}) {
+	const sources = validatedSources(sourceInputs, options);
+	return mapConcurrent(sources, options.concurrency ?? 4, async (source) => ({
+		source: sourceAttribution(source),
+		health: source.enabled ? await createAdapter(source, options).health() : { ok: false, disabled: true },
+	}));
+}
+
+async function enrichNpmDownloads(plugins, options = {}) {
+	const packages = [...new Set(plugins.map((plugin) => plugin.identity?.package).filter(Boolean))].slice(0, options.maxEvidencePackages ?? 100);
+	if (!packages.length || options.enrichDownloads === false) return plugins;
+	const source = { id: "npm-downloads", name: "npm downloads", type: "npm", enabled: true };
+	const requestOptions = { ...options, authToken: undefined, allowPrivateNetwork: false };
+	const counts = new Map();
+	const pending = [];
+	for (const name of packages) {
+		const cached = cachedEvidence(npmDownloadCache, name);
+		if (cached === undefined) pending.push(name);
+		else counts.set(name, cached);
+	}
+
+	// npm's downloads API supports bulk point queries for unscoped packages,
+	// but scoped packages are not supported in bulk queries. Query each scoped
+	// package separately instead of letting one invalid bulk request zero the
+	// whole result set.
+	const unscoped = pending.filter((name) => !name.startsWith("@"));
+	const scoped = pending.filter((name) => name.startsWith("@"));
+	const tasks = [];
+	for (let index = 0; index < unscoped.length; index += 64) tasks.push(unscoped.slice(index, index + 64));
+	for (const name of scoped) tasks.push([name]);
+
+	await mapConcurrent(tasks, Math.min(options.concurrency ?? 4, 6), async (chunk) => {
+		try {
+			const encoded = chunk.map((name) => encodeURIComponent(name)).join(",");
+			const value = await fetchJson(`https://api.npmjs.org/downloads/point/last-month/${encoded}`, source, requestOptions);
+			if (chunk.length === 1 && typeof value?.downloads === "number") {
+				counts.set(chunk[0], value.downloads);
+				cacheEvidence(npmDownloadCache, chunk[0], value.downloads);
+				return;
+			}
+			for (const name of chunk) {
+				const downloads = value?.[name]?.downloads;
+				if (typeof downloads !== "number") continue;
+				counts.set(name, downloads);
+				cacheEvidence(npmDownloadCache, name, downloads);
+			}
+		} catch {
+			// Popularity metadata is best-effort and must never hide catalog results.
+		}
+	});
+	return plugins.map((plugin) => {
+		const downloads30d = counts.get(plugin.identity?.package);
+		if (downloads30d === undefined) return plugin;
+		return { ...plugin, evidence: mergeEvidence(plugin.evidence, { downloads30d }) };
+	});
+}
+
+function freshnessTimestamp(plugin) {
+	return Date.parse(plugin.evidence?.releasedAt ?? plugin.evidence?.repositoryUpdatedAt ?? "") || 0;
+}
+
+function percentileScores(plugins, metric) {
+	const ranked = plugins.map((plugin, index) => ({ plugin, index, value: Number(metric(plugin)) || 0 }))
+		.sort((a, b) => a.value - b.value || a.index - b.index);
+	const scores = new Map();
+	const denominator = Math.max(1, ranked.length - 1);
+	let cursor = 0;
+	while (cursor < ranked.length) {
+		let end = cursor + 1;
+		while (end < ranked.length && ranked[end].value === ranked[cursor].value) end++;
+		const averageRank = ((cursor + end - 1) / 2) / denominator;
+		for (let index = cursor; index < end; index++) scores.set(ranked[index].plugin, averageRank);
+		cursor = end;
+	}
+	return scores;
+}
+
+function compositeScores(plugins, leftMetric, rightMetric) {
+	const left = percentileScores(plugins, leftMetric);
+	const right = percentileScores(plugins, rightMetric);
+	const scores = new Map();
+	for (const plugin of plugins) scores.set(plugin, ((left.get(plugin) ?? 0) + (right.get(plugin) ?? 0)) / 2);
+	return scores;
+}
+
+
+function manifestInstallability(manifest) {
+	const bundlePatch = text(manifest?.dsh?.bundle?.patch);
+	return {
+		installability: bundlePatch ? "bundle" : "not-bundle",
+		...(bundlePatch ? { bundlePatch } : {}),
+	};
+}
+
+function githubRepositoryParts(repository) {
+	const canonical = canonicalRepository(repository);
+	if (!canonical) return undefined;
+	try {
+		const url = new URL(canonical);
+		if (url.hostname.toLowerCase() !== "github.com") return undefined;
+		const parts = url.pathname.replace(/^\/+|\/+$/g, "").split("/");
+		if (parts.length !== 2 || !parts[0] || !parts[1]) return undefined;
+		return { owner: parts[0], repo: parts[1].replace(/\.git$/i, "") };
+	} catch {
+		return undefined;
+	}
+}
+
+export async function githubRepositoryStats(repositories, options = {}) {
+	const values = Array.isArray(repositories) ? repositories : [];
+	if (values.length > 20) throw new RangeError("at most 20 GitHub repositories can be resolved at once");
+	const source = { id: "github", name: "GitHub", type: "github", enabled: true };
+	const authToken = options.authToken ?? options.resolveAuthToken?.(source);
+	const requestOptions = { ...options, ...(authToken ? { authToken } : {}), allowPrivateNetwork: false };
+	const normalized = [...new Set(values.map((repository) => canonicalRepository(repository)).filter(Boolean))];
+	const rows = await mapConcurrent(normalized, Math.min(3, Math.max(1, normalized.length)), async (repository) => {
+		const parts = githubRepositoryParts(repository);
+		if (!parts) return undefined;
+		const key = `${parts.owner.toLowerCase()}/${parts.repo.toLowerCase()}`;
+		const cached = cachedValue(githubStatsCache, key);
+		if (cached !== undefined) return { repository, ...cached };
+		try {
+			const value = await fetchJson(
+				`https://api.github.com/repos/${encodeURIComponent(parts.owner)}/${encodeURIComponent(parts.repo)}`,
+				source,
+				requestOptions,
+			);
+			const stats = {
+				...(finiteNumber(value?.stargazers_count) !== undefined ? { stars: finiteNumber(value.stargazers_count) } : {}),
+				...(isoDate(value?.pushed_at ?? value?.updated_at) ? { repositoryUpdatedAt: isoDate(value.pushed_at ?? value.updated_at) } : {}),
+			};
+			cacheValue(githubStatsCache, key, stats);
+			return { repository, ...stats };
+		} catch {
+			return { repository };
+		}
+	});
+	return rows.filter(Boolean);
+}
+
+export async function githubPluginDetails(repository, options = {}) {
+	const parts = githubRepositoryParts(repository);
+	if (!parts) return { installability: "unknown" };
+	const cacheKey = `${parts.owner.toLowerCase()}/${parts.repo.toLowerCase()}`;
+	const cached = cachedValue(githubManifestCache, cacheKey);
+	if (cached !== undefined) return cached;
+
+	const source = { id: "github-manifest", name: "GitHub manifest", type: "github", enabled: true };
+	const requestOptions = { ...options, authToken: undefined, allowPrivateNetwork: false };
+	const rawUrl = `https://raw.githubusercontent.com/${encodeURIComponent(parts.owner)}/${encodeURIComponent(parts.repo)}/HEAD/package.json`;
+	let details;
+	try {
+		const manifest = await fetchJson(rawUrl, source, requestOptions);
+		details = {
+			...manifestInstallability(manifest),
+			...(text(manifest?.name) ? { packageName: text(manifest.name) } : {}),
+			...(text(manifest?.version) ? { version: text(manifest.version) } : {}),
+			...(manifest?.private === true ? { private: true } : {}),
+			...(text(manifest?.peerDependencies?.["@deepseek-ai/dsh"]) ? { dshCompatibility: text(manifest.peerDependencies["@deepseek-ai/dsh"]) } : {}),
+		};
+	} catch (error) {
+		const message = String(error?.message ?? error);
+		details = /HTTP 404|status 404|Not Found/i.test(message)
+			? { installability: "not-bundle", reason: "No root package.json" }
+			: { installability: "unknown", reason: message };
+	}
+	cacheValue(githubManifestCache, cacheKey, details);
+	return details;
+}
+
+function shouldVerifyRegistryBundles(options = {}) {
+	return options.verifyInstallability === true
+		|| (options.verifyInstallability !== false && options.fetchImpl === undefined);
+}
+
+function requiresRegistryVerification(plugin) {
+	return (plugin.sources ?? []).some((source) => source.type === "npm" || source.type === "github");
+}
+
+async function enrichInstallability(plugins, options = {}) {
+	if (!shouldVerifyRegistryBundles(options) || plugins.length === 0) return plugins;
+	const verificationConcurrency = Math.min(Math.max(1, options.verificationConcurrency ?? 12), 16);
+
+	return mapConcurrent(plugins, verificationConcurrency, async (plugin) => {
+		if (plugin.evidence?.installability === "bundle" || plugin.evidence?.installability === "not-bundle") return plugin;
+		let details;
+		try {
+			if (plugin.identity?.package && plugin.version) {
+				details = await npmPluginDetails(plugin.identity.package, plugin.version, options);
+			} else if (plugin.identity?.repository && plugin.sources?.some((source) => source.type === "github")) {
+				details = await githubPluginDetails(plugin.identity.repository, options);
+			} else {
+				return plugin;
+			}
+		} catch {
+			details = { installability: "unknown" };
+		}
+		return { ...plugin, evidence: mergeEvidence(plugin.evidence, { installability: details?.installability ?? "unknown" }) };
+	});
+}
+
+export async function npmPluginDetails(packageName, version, options = {}) {
+	const name = text(packageName);
+	const requestedVersion = text(version);
+	if (!name || !requestedVersion || !safeInstallSpec("npm", `${name}@${requestedVersion}`)) throw new Error("invalid npm package details request");
+	const cacheKey = `${name}@${requestedVersion}`;
+	const cached = cachedValue(npmManifestCache, cacheKey);
+	if (cached !== undefined) return cached;
+
+	const source = { id: "npm-manifest", name: "npm registry", type: "npm", enabled: true };
+	const requestOptions = { ...options, authToken: undefined, allowPrivateNetwork: false };
+	const encodedName = name.startsWith("@")
+		? `@${encodeURIComponent(name.slice(1).split("/")[0])}%2F${encodeURIComponent(name.split("/")[1] ?? "")}`
+		: encodeURIComponent(name);
+	const manifest = await fetchJson(`https://registry.npmjs.org/${encodedName}/${encodeURIComponent(requestedVersion)}`, source, requestOptions);
+	const explicit = text(manifest?.peerDependencies?.["@deepseek-ai/dsh"])
+		?? text(manifest?.engines?.dsh)
+		?? text(manifest?.dsh?.compatibility);
+	const peerEntries = Object.entries(manifest?.peerDependencies ?? {})
+		.filter(([dependency, range]) => dependency.startsWith("@deepseek-ai/dsh-") && typeof range === "string")
+		.map(([dependency, range]) => ({ dependency, range }));
+	const details = {
+		...manifestInstallability(manifest),
+		...(explicit ? { dshCompatibility: explicit } : {}),
+		...(peerEntries.length ? { dshPeers: peerEntries.slice(0, 12) } : {}),
+		...(manifest?.deprecated ? { deprecated: String(manifest.deprecated) } : {}),
+		...(manifest?.private === true ? { private: true } : {}),
+	};
+	cacheValue(npmManifestCache, cacheKey, details);
+	return details;
+}
+
+
+function applyBrowseFilters(plugins, options) {
+	let filtered = plugins;
+	const freshnessDays = Number(options.freshnessDays) || 0;
+	if (freshnessDays > 0) {
+		const cutoff = Date.now() - freshnessDays * 86_400_000;
+		filtered = filtered.filter((plugin) => freshnessTimestamp(plugin) >= cutoff);
+	}
+	const tag = text(options.tag)?.toLowerCase();
+	if (tag && FILTER_TAGS.includes(tag)) filtered = filtered.filter((plugin) => plugin.tags?.includes(tag));
+	const dshMetadata = options.dshMetadata ?? "any";
+	if (dshMetadata === "declared") filtered = filtered.filter((plugin) => Boolean(plugin.evidence?.dshCompatibility));
+	else if (dshMetadata === "unknown") filtered = filtered.filter((plugin) => !plugin.evidence?.dshCompatibility);
+	return filtered;
+}
+
+const SORT_KEYS = ["stars", "downloads", "freshness", "name"];
+
+function normalizedSorts(options = {}) {
+	const input = Array.isArray(options.sorts) ? options.sorts : [];
+	const seen = new Set();
+	const normalized = [];
+	for (const item of input) {
+		const key = text(item?.key);
+		const direction = item?.direction === "asc" ? "asc" : item?.direction === "desc" ? "desc" : undefined;
+		if (!SORT_KEYS.includes(key) || !direction || seen.has(key)) continue;
+		seen.add(key);
+		normalized.push({ key, direction });
+		if (normalized.length >= SORT_KEYS.length) break;
+	}
+	if (normalized.length) return normalized;
+
+	// Accept the 0.3.x single-sort payload during upgrades.
+	const legacy = options.sort;
+	if (legacy === "stars") return [{ key: "stars", direction: "desc" }];
+	if (legacy === "downloads") return [{ key: "downloads", direction: "desc" }];
+	if (legacy === "freshness") return [{ key: "freshness", direction: "desc" }];
+	if (legacy === "name") return [{ key: "name", direction: "asc" }];
+	if (legacy === "stars-downloads") return [{ key: "stars", direction: "desc" }, { key: "downloads", direction: "desc" }];
+	if (legacy === "downloads-freshness") return [{ key: "downloads", direction: "desc" }, { key: "freshness", direction: "desc" }];
+	return [];
+}
+
+function compareSortValue(a, b, key) {
+	if (key === "stars") return (a.evidence?.stars ?? 0) - (b.evidence?.stars ?? 0);
+	if (key === "downloads") return (a.evidence?.downloads30d ?? 0) - (b.evidence?.downloads30d ?? 0);
+	if (key === "freshness") return freshnessTimestamp(a) - freshnessTimestamp(b);
+	if (key === "name") return a.name.localeCompare(b.name);
+	return 0;
+}
+
+function sortPlugins(plugins, sorts) {
+	if (!Array.isArray(sorts) || sorts.length === 0) return plugins;
+	return [...plugins].sort((a, b) => {
+		for (const criterion of sorts) {
+			const compared = compareSortValue(a, b, criterion.key);
+			if (compared !== 0) return criterion.direction === "asc" ? compared : -compared;
+		}
+		return a.name.localeCompare(b.name);
+	});
+}
+
+
+function sourceDiscoveryQuery(source, query) {
+	return source.type === "npm" || source.type === "github" ? "" : query;
+}
+
+function discoveryCacheKey(sources, query) {
+	return JSON.stringify({
+		sources: sources.map((source) => ({ id: source.id, name: source.name, type: source.type, url: source.url ?? "", enabled: source.enabled !== false })),
+		query: sources.some((source) => source.type !== "npm" && source.type !== "github")
+			? String(query ?? "").trim().toLowerCase()
+			: "",
+	});
+}
+
+function cachedDiscoveryRows(key, refreshRevision = 0) {
+	const entry = browseDiscoveryCache.get(key);
+	if (!entry) return undefined;
+	if (entry.expiresAt <= Date.now()) {
+		browseDiscoveryCache.delete(key);
+		return undefined;
+	}
+	if ((entry.refreshRevision ?? 0) < refreshRevision) return undefined;
+	return entry.rows;
+}
+
+function cacheDiscoveryRows(key, rows, refreshRevision = 0) {
+	browseDiscoveryCache.set(key, { rows, refreshRevision, expiresAt: Date.now() + BROWSE_DISCOVERY_TTL_MS });
+}
+
+
+function registrySearchVariants(query) {
+	const needle = text(query)?.toLowerCase();
+	if (!needle) return [];
+	const variants = [needle];
+	const unscoped = needle.startsWith("@") && needle.includes("/") ? needle.slice(needle.indexOf("/") + 1) : needle;
+	if (unscoped !== needle) variants.push(unscoped);
+
+	let shortened = unscoped;
+	for (const prefix of ["dsh-client-ui-", "dsh-ui-", "dsh-plugin-"]) {
+		if (shortened.startsWith(prefix) && shortened.length > prefix.length) {
+			shortened = shortened.slice(prefix.length);
+			variants.push(shortened);
+			break;
+		}
+	}
+	if (shortened.startsWith("dsh-") && shortened.length > 4) variants.push(shortened.slice(4));
+	const parts = shortened.split("-").filter(Boolean);
+	if (parts.length >= 2) variants.push(parts.slice(-2).join("-"));
+	return [...new Set(variants.filter((value) => value.length >= 3))].slice(0, 3);
+}
+
+function searchPluginsWithVariants(plugins, query) {
+	const variants = registrySearchVariants(query);
+	if (!variants.length) return plugins;
+	const matches = new Set();
+	for (const variant of variants) {
+		for (const plugin of searchPlugins(plugins, variant)) matches.add(plugin);
+	}
+	return [...matches];
+}
+
+function queryDiscoveryCacheKey(sources, query) {
+	return `query:${JSON.stringify({
+		sources: sources.map((source) => ({ id: source.id, type: source.type, url: source.url ?? "", enabled: source.enabled !== false })),
+		query: String(query ?? "").trim().toLowerCase(),
+	})}`;
+}
+
+async function queryRegistrySources(sources, query, options, refreshRevision, useDiscoveryCache) {
+	const registrySources = sources.filter((source) => source.type === "npm" || source.type === "github");
+	if (!registrySources.length || !text(query)) return [];
+	const cacheKey = queryDiscoveryCacheKey(registrySources, query);
+	const cached = useDiscoveryCache ? cachedDiscoveryRows(cacheKey, refreshRevision) : undefined;
+	if (cached) return cached;
+
+	const variants = registrySearchVariants(query);
+	const rows = await mapConcurrent(registrySources, options.concurrency ?? 4, async (source) => {
+		const started = Date.now();
+		try {
+			const sourceVariants = source.type === "github" ? variants : variants.slice(0, 1);
+			const batches = await mapConcurrent(sourceVariants, Math.min(2, sourceVariants.length || 1), async (variant) => {
+				try { return await createAdapter(source, options).search(variant); }
+				catch { return []; }
+			});
+			return { source: sourceAttribution(source), health: { ok: true, latencyMs: Date.now() - started }, plugins: dedupePlugins(batches.flat()) };
+		} catch (error) {
+			return { source: sourceAttribution(source), health: { ok: false, latencyMs: Date.now() - started, error: String(error?.message ?? error) }, plugins: [] };
+		}
+	});
+	if (useDiscoveryCache) cacheDiscoveryRows(cacheKey, rows, refreshRevision);
+	return rows;
+}
+
+export async function browseSources(sourceInputs, query = "", options = {}) {
+	const enabled = validatedSources(sourceInputs, options).filter((source) => source.enabled);
+	const refreshRevision = Number.isInteger(options.refreshRevision) && options.refreshRevision >= 0 ? options.refreshRevision : 0;
+	const useDiscoveryCache = options.cacheDiscovery === true || (options.cacheDiscovery !== false && options.fetchImpl === undefined);
+	const cacheKey = discoveryCacheKey(enabled, query);
+	let rows = useDiscoveryCache ? cachedDiscoveryRows(cacheKey, refreshRevision) : undefined;
+	if (!rows) {
+		rows = await mapConcurrent(enabled, options.concurrency ?? 4, async (source) => {
+			const started = Date.now();
+			try {
+				const plugins = await createAdapter(source, options).search(sourceDiscoveryQuery(source, query));
+				return { source: sourceAttribution(source), health: { ok: true, latencyMs: Date.now() - started, count: plugins.length }, plugins };
+			} catch (error) {
+				return { source: sourceAttribution(source), health: { ok: false, latencyMs: Date.now() - started, error: String(error?.message ?? error) }, plugins: [] };
+			}
+		});
+		if (useDiscoveryCache) cacheDiscoveryRows(cacheKey, rows, refreshRevision);
+	}
+
+	let discovered = dedupePlugins(rows.flatMap((row) => row.plugins));
+
+	// Canonical discovery is intentionally query-independent and therefore can be
+	// truncated by registry ranking. Merge query-specific registry discovery back in
+	// so low-ranked but relevant plugins are still reachable.
+	const queryRows = await queryRegistrySources(enabled, query, options, refreshRevision, useDiscoveryCache);
+	discovered = dedupePlugins([...discovered, ...queryRows.flatMap((row) => row.plugins)]);
+
+	let matched = searchPluginsWithVariants(discovered, query).slice(0, options.maxTotalPlugins ?? 5_000);
+	if (options.stableOnly === true) matched = matched.filter((plugin) => plugin.evidence?.releaseChannel === "stable");
+	matched = applyBrowseFilters(matched, options);
+
+	// npm/GitHub search results are discovery candidates, not installable plugins.
+	// DSH activates a profile layer only for packages declaring dsh.bundle.patch,
+	// so verify the complete candidate set before totals, paging, or rendering.
+	if (shouldVerifyRegistryBundles(options)) {
+		matched = await enrichInstallability(matched, options);
+		matched = matched.filter((plugin) => !requiresRegistryVerification(plugin) || plugin.evidence?.installability === "bundle");
+	}
+
+	const requestedPageSize = Number(options.pageSize);
+	const pageSize = [20, 50, 100].includes(requestedPageSize) ? requestedPageSize : 20;
+	const total = matched.length;
+	const pageCount = Math.max(1, Math.ceil(total / pageSize));
+	const requestedPage = Number.isInteger(options.page) && options.page > 0 ? options.page : 1;
+	const page = Math.min(requestedPage, pageCount);
+	const sorts = normalizedSorts(options);
+
+	// Download ordering needs real download evidence before the page is sliced.
+	// The npm bulk endpoint plus the evidence cache keeps subsequent sorts/pages fast.
+	if (sorts.some((criterion) => criterion.key === "downloads")) {
+		matched = await enrichNpmDownloads(matched, { ...options, maxEvidencePackages: Math.min(matched.length, 1000) });
+	}
+
+	matched = sortPlugins(matched, sorts);
+
+	const offset = (page - 1) * pageSize;
+	let plugins = matched.slice(offset, offset + pageSize);
+	// When downloads are not a sort criterion, enrich only the visible page.
+	if (!sorts.some((criterion) => criterion.key === "downloads")) {
+		plugins = await enrichNpmDownloads(plugins, { ...options, maxEvidencePackages: pageSize });
+	}
+	return {
+		plugins,
+		total,
+		page,
+		pageSize,
+		pageCount,
+		sources: rows.map(({ source, health }) => ({ ...source, health })),
+		generatedAt: new Date().toISOString(),
+	};
+}