dsh-plugin-shop 0.1.0

package/lib/index.js

@@ -0,0 +1,725 @@
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { loadOptionalPatches, readProfileManifest, resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
+import { lt, minVersion } from "semver";
+import { fileURLToPath } from "node:url";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { z } from "zod";
+import { spawn } from "node:child_process";
+import { dump } from "js-yaml";
+/** A cached catalog younger than this is served without touching the network. */
+const FRESH_MS = 3e5;
+/** Records when the loader itself wrote the cache; the pointer's `builtAt` is
+* the catalog's build time, not the cache's fetch time. */
+const META_FILE = "index.meta.json";
+const entrySchema = z.object({
+	name: z.string(),
+	version: z.string(),
+	integrity: z.string().nullable(),
+	publishedAt: z.string().nullable(),
+	repository: z.string().nullable(),
+	license: z.string().nullable(),
+	tier: z.enum([
+		"verified",
+		"verified-stale",
+		"community"
+	]),
+	metadata: z.enum(["declared", "derived"]),
+	review: z.object({
+		reviewedVersion: z.string(),
+		reviewer: z.string(),
+		reviewCommit: z.string(),
+		notes: z.string()
+	}).optional(),
+	catalog: z.object({
+		category: z.enum([
+			"tool",
+			"provider",
+			"ui",
+			"workflow",
+			"integration",
+			"other"
+		]),
+		summary: z.object({
+			en: z.string(),
+			zh: z.string().optional()
+		}),
+		capabilities: z.array(z.string())
+	}).optional()
+});
+const dataSchema = z.object({
+	schemaVersion: z.number(),
+	plugins: z.array(entrySchema),
+	denied: z.array(z.object({
+		name: z.string(),
+		detail: z.string()
+	})).default([])
+});
+const pointerSchema = z.object({
+	schemaVersion: z.number(),
+	builtAt: z.string(),
+	count: z.number(),
+	plugins: z.object({
+		url: z.string(),
+		sha256: z.string()
+	})
+});
+const nodeFs = {
+	exists: (path) => existsSync(path),
+	read: (path) => readFileSync(path, "utf8"),
+	write: (path, data) => {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, data);
+	}
+};
+/** Resolve the pointer's data URL against the catalog base. An absolute URL —
+* any scheme, or a protocol-relative `//host/...` — would hand the pointer a
+* fetch primitive to arbitrary hosts, so it is refused loudly before any
+* fetch (§9.2). The guard is the resolved origin, not the raw string: WHATWG
+* normalization strips leading whitespace and accepts backslash spellings
+* before the string could be inspected, so only comparing the resolved URL's
+* origin to the base's closes every spelling class. */
+function resolveDataUrl(baseUrl, url) {
+	const resolved = new URL(url, baseUrl);
+	if (resolved.origin !== new URL(baseUrl).origin) throw new Error("catalog data url must be relative to the catalog base");
+	return resolved.href;
+}
+/**
+* Load the catalog snapshot: fetch the pointer, verify the data file's sha256
+* against it, cache both on disk, and serve the cached copy with `stale: true`
+* only when the transport itself failed — the fetch threw or returned a
+* non-2xx (§10). A schemaVersion higher than this build supports, a malformed
+* pointer or data file, an absolute data URL, or a sha256 mismatch — fresh or
+* cached — throws even when a cache exists; never silently degraded.
+*/
+async function loadCatalog(options) {
+	const { baseUrl, cacheDir, refresh = false, fetchImpl = fetch, now = () => /* @__PURE__ */ new Date(), fsImpl = nodeFs } = options;
+	const indexPath = join(cacheDir, "index.json");
+	const metaPath = join(cacheDir, META_FILE);
+	/** The timestamp freshness is measured from: the sidecar's fetch time when
+	* it exists and parses, else the pointer's builtAt when that parses, else
+	* null ("no usable freshness fact"). */
+	const freshnessTimeOf = (builtAt) => {
+		if (fsImpl.exists(metaPath)) try {
+			const fetchedAt = Date.parse(JSON.parse(fsImpl.read(metaPath)).fetchedAt);
+			if (!Number.isNaN(fetchedAt)) return fetchedAt;
+		} catch {}
+		const built = Date.parse(builtAt);
+		return Number.isNaN(built) ? null : built;
+	};
+	const readCached = () => {
+		try {
+			const pointer = pointerSchema.parse(JSON.parse(fsImpl.read(indexPath)));
+			if (pointer.schemaVersion > 2) throw new Error(`catalog schemaVersion ${pointer.schemaVersion} is newer than this build supports (2)`);
+			const dataPath = join(cacheDir, basename(pointer.plugins.url));
+			const dataText = fsImpl.read(dataPath);
+			const actual = createHash("sha256").update(dataText).digest("hex");
+			if (actual !== pointer.plugins.sha256) throw new Error(`cached catalog data failed integrity check: expected ${pointer.plugins.sha256}, got ${actual}`);
+			const data = dataSchema.parse(JSON.parse(dataText));
+			if (data.schemaVersion > 2) throw new Error(`catalog schemaVersion ${data.schemaVersion} is newer than this build supports (2)`);
+			return {
+				schemaVersion: pointer.schemaVersion,
+				builtAt: pointer.builtAt,
+				entries: data.plugins,
+				denied: data.denied
+			};
+		} catch {
+			return null;
+		}
+	};
+	if (!refresh && fsImpl.exists(indexPath)) {
+		const cached = readCached();
+		if (cached !== null) {
+			const fetchedAt = freshnessTimeOf(cached.builtAt);
+			if (fetchedAt !== null && now().getTime() - fetchedAt < FRESH_MS) return {
+				snapshot: cached,
+				stale: false
+			};
+		}
+	}
+	let pointerText;
+	try {
+		const response = await fetchImpl(new URL("index.json", baseUrl).href);
+		if (!response.ok) throw new Error(`catalog pointer returned ${response.status}`);
+		pointerText = await response.text();
+	} catch (error) {
+		const cached = readCached();
+		if (cached !== null) return {
+			snapshot: cached,
+			stale: true
+		};
+		throw error;
+	}
+	const pointer = pointerSchema.parse(JSON.parse(pointerText));
+	if (pointer.schemaVersion > 2) throw new Error(`catalog schemaVersion ${pointer.schemaVersion} is newer than this build supports (2)`);
+	const dataUrl = resolveDataUrl(baseUrl, pointer.plugins.url);
+	let dataText;
+	try {
+		const dataResponse = await fetchImpl(dataUrl);
+		if (!dataResponse.ok) throw new Error(`catalog data returned ${dataResponse.status}`);
+		dataText = await dataResponse.text();
+	} catch (error) {
+		const cached = readCached();
+		if (cached !== null) return {
+			snapshot: cached,
+			stale: true
+		};
+		throw error;
+	}
+	const actual = createHash("sha256").update(dataText).digest("hex");
+	if (actual !== pointer.plugins.sha256) throw new Error(`catalog data failed integrity check: expected ${pointer.plugins.sha256}, got ${actual}`);
+	const data = dataSchema.parse(JSON.parse(dataText));
+	if (data.schemaVersion > 2) throw new Error(`catalog schemaVersion ${data.schemaVersion} is newer than this build supports (2)`);
+	const snapshot = {
+		schemaVersion: pointer.schemaVersion,
+		builtAt: pointer.builtAt,
+		entries: data.plugins,
+		denied: data.denied
+	};
+	fsImpl.write(indexPath, JSON.stringify(pointer));
+	fsImpl.write(join(cacheDir, basename(pointer.plugins.url)), dataText);
+	fsImpl.write(metaPath, JSON.stringify({ fetchedAt: now().toISOString() }));
+	return {
+		snapshot,
+		stale: false
+	};
+}
+//#endregion
+//#region src/host/install.ts
+/**
+* Decide whether one install request may proceed, against the Host's own
+* snapshot (§5.3). The browser sends a name; nothing the browser says about
+* the package is trusted.
+*/
+function validateInstall(snapshot, args) {
+	const denied = snapshot.denied.find((d) => d.name === args.name);
+	if (denied !== void 0) return {
+		ok: false,
+		code: "denied",
+		detail: `dsh-plugin-shop: ${args.name} is denied: ${denied.detail}`
+	};
+	const entry = snapshot.entries.find((e) => e.name === args.name);
+	if (entry === void 0) return {
+		ok: false,
+		code: "not-in-catalog",
+		detail: `dsh-plugin-shop: ${args.name} is not in the catalog`
+	};
+	if (entry.version !== args.version) return {
+		ok: false,
+		code: "version-mismatch",
+		detail: `dsh-plugin-shop: ${args.name}@${args.version} is not the cataloged version (${entry.version})`
+	};
+	if (entry.tier !== "verified" && !args.acknowledged) return {
+		ok: false,
+		code: "needs-acknowledgement",
+		detail: entry.tier === "verified-stale" ? `dsh-plugin-shop: ${args.name} is verified-stale: a newer version than the review is current and has not been reviewed; acknowledgement is required` : `dsh-plugin-shop: ${args.name} is ${entry.tier}-tier and has not been reviewed; acknowledgement is required`
+	};
+	return { ok: true };
+}
+//#endregion
+//#region src/host/executor.ts
+/** Install executor: spawn the dsh CLI, stream its output, serialize per profile. */
+const MAX_LOG_LINES = 200;
+const MAX_LOG_BYTES = 65536;
+const profileQueues = /* @__PURE__ */ new Map();
+function chain(profile, task) {
+	const next = (profileQueues.get(profile) ?? Promise.resolve()).then(task, task);
+	profileQueues.set(profile, next.catch(() => {}));
+	return next;
+}
+/**
+* The §7.2 step-6 confirm: after a zero exit, re-read the profile manifest and
+* verify the bundle actually landed in `dsh.profile.bundles`. Exit 0 alone is
+* not success — a library-that-looked-like-a-plugin, or a stale catalog,
+* exits 0 while changing nothing (§10). The store cannot force a client
+* refresh in P1, so the detail carries the signal. A manifest that cannot be
+* read or parsed is the same outcome, naming the file: the install's result
+* is then unknown, and a bare `done` would be plausible-but-wrong. `home` is
+* the DSH_HOME the child was spawned with — the parent's own DSH_HOME may
+* differ when `env` pinned it.
+*/
+function confirmBundleActivation(profile, home, expectedName) {
+	const profileDir = resolveProfileDir(profile, home);
+	try {
+		if (readProfileManifest("dsh-plugin-shop", profileDir).dsh?.profile?.bundles?.includes(expectedName)) return null;
+		return "installed but dsh.profile.bundles did not change — the catalog may be stale; refresh it";
+	} catch {
+		return `installed but the profile manifest could not be read (${join(profileDir, "package.json")}) — the catalog may be stale; refresh it`;
+	}
+}
+/**
+* Run one `dsh plugin --profile <profile> add <spec>` and track it.
+* Never rolls back; a failure surfaces stderr verbatim plus the recovery hint
+* (§10). The store never passes build-script flags: `allowBuilds` stays the
+* user's explicit decision in the CLI (§7.2).
+* The child inherits the current environment unless `env` is given — the
+* real-install test pins DSH_HOME to a temporary directory this way.
+* When `expectedName` is given, a zero exit is confirmed against the profile
+* manifest (§7.2 step 6) before the install reports `done`.
+*/
+function startInstall(options) {
+	const { profile, spec, dshBin = "dsh", env, expectedName, onStatus } = options;
+	const installId = randomUUID();
+	const log = [];
+	let logBytes = 0;
+	let state = "running";
+	let detail;
+	const status = () => ({
+		state,
+		log: [...log],
+		...state === "done" ? { needsRestart: true } : {},
+		...detail !== void 0 ? { detail } : {}
+	});
+	const append = (line) => {
+		log.push(line);
+		logBytes += Buffer.byteLength(line);
+		while ((log.length > MAX_LOG_LINES || logBytes > MAX_LOG_BYTES) && log.length > 1) {
+			const oldest = log.shift();
+			if (oldest !== void 0) logBytes -= Buffer.byteLength(oldest);
+		}
+		onStatus?.(status());
+	};
+	return {
+		installId,
+		status,
+		finished: chain(profile, () => new Promise((resolve) => {
+			const child = spawn(dshBin, [
+				"plugin",
+				"--profile",
+				profile,
+				"add",
+				spec
+			], {
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				env: env ?? process.env
+			});
+			child.stdout.on("data", (chunk) => {
+				for (const line of chunk.toString().split("\n")) if (line !== "") append(line);
+			});
+			child.stderr.on("data", (chunk) => {
+				for (const line of chunk.toString().split("\n")) if (line !== "") append(line);
+			});
+			child.on("error", (error) => {
+				const code = error.code;
+				state = "failed";
+				detail = code === "ENOENT" ? "dsh not found on PATH — install the dsh CLI to manage profile plugins" : `dsh spawn failed: ${error.message}`;
+				onStatus?.(status());
+				resolve(status());
+			});
+			child.on("close", (exitCode) => {
+				if (state !== "running") return;
+				if (exitCode === 0) {
+					state = "done";
+					if (expectedName !== void 0) {
+						const confirmDetail = confirmBundleActivation(profile, env?.DSH_HOME, expectedName);
+						if (confirmDetail !== null) {
+							state = "failed";
+							detail = confirmDetail;
+						}
+					}
+				} else {
+					state = "failed";
+					const lastLogLine = log[log.length - 1] ?? "";
+					detail = `pnpm failed in the profile. Run: dsh plugin --profile ${profile} install — ${lastLogLine}`;
+				}
+				onStatus?.(status());
+				resolve(status());
+			});
+		}))
+	};
+}
+//#endregion
+//#region src/host/profile.ts
+/** Profile directory discovery and user-layer writes (§8: hot enable/disable). */
+/**
+* Find the profile directory that owns `startPath`.
+*
+* `baseDir` is the boot-provided profile directory (the Loader root's own
+* directory, `ctx.baseUrl`) and is authoritative when it is a profile. The
+* walk-up from `startPath` covers the case where the package is materialized
+* inside the profile's node_modules — but a `link:` install keeps the package
+* at its source location, so no ancestor of the module path is a profile at
+* all. In that case only `baseDir` can answer.
+*/
+function discoverProfile(startPath, baseDir) {
+	if (baseDir !== void 0 && isProfileDir(baseDir)) return {
+		name: basename(baseDir),
+		dir: baseDir
+	};
+	let dir = realpathNearestExisting(startPath);
+	for (;;) {
+		if (isProfileDir(dir)) return {
+			name: basename(dir),
+			dir
+		};
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	throw new Error(`dsh-plugin-shop: no profile directory found above ${startPath}`);
+}
+/** A directory is a profile when it holds the Loader root next to the bundle
+* manifest the store's own package.json declares itself part of. */
+function isProfileDir(dir) {
+	if (!existsSync(join(dir, "cordis.yml"))) return false;
+	try {
+		const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+		return Array.isArray(manifest.dsh?.profile?.bundles);
+	} catch {}
+	return false;
+}
+/** Resolve symlinks through the deepest ancestor of `startPath` that exists.
+* The leaf — the store's own module file — need not be present yet for
+* discovery to know where it lives. */
+function realpathNearestExisting(startPath) {
+	let current = startPath;
+	for (;;) try {
+		return realpathSync(current);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = dirname(current);
+		if (parent === current) return current;
+		current = parent;
+	}
+}
+/**
+* Upsert one row of the profile's user layer (`cordis.patch.yml`). Enabling
+* removes the row so the bundle default rules again; disabling writes
+* `{ id, disabled: true }` (§8: the CLI's watchUserPatches applies the change
+* hot through HMR). Existing rows for other ids are preserved verbatim.
+*/
+function setUserLayerRow(options) {
+	const file = join(options.profileDir, "cordis.patch.yml");
+	const others = (loadOptionalPatches("dsh-plugin-shop", file) ?? []).filter((row) => row.id !== options.row.id);
+	const next = options.row.disabled ? [...others, {
+		id: options.row.id,
+		disabled: true
+	}] : others;
+	const tmp = `${file}.tmp`;
+	writeFileSync(tmp, dump(next, { noRefs: true }));
+	renameSync(tmp, file);
+}
+//#endregion
+//#region src/host/index.ts
+/** StoreGateway: the Host half of dsh-plugin-shop (§5.1). */
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) {
+			if (kind === "field") initializers.unshift(_);
+			else descriptor[key] = _;
+		}
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+/** Remote-only service exposing the store Remote methods of §7.3.
+*
+* @typert service store */
+let StoreGateway = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _setEnabled_decorators;
+	let _catalog_decorators;
+	let _install_decorators;
+	let _installStatus_decorators;
+	let _outdated_decorators;
+	return class StoreGateway extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_setEnabled_decorators = [Remote("setEnabled")];
+			_catalog_decorators = [Remote("catalog")];
+			_install_decorators = [Remote("installStart")];
+			_installStatus_decorators = [Remote("installStatus")];
+			_outdated_decorators = [Remote("outdated")];
+			__esDecorate(this, null, _setEnabled_decorators, {
+				kind: "method",
+				name: "setEnabled",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "setEnabled" in obj,
+					get: (obj) => obj.setEnabled
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _catalog_decorators, {
+				kind: "method",
+				name: "catalog",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "catalog" in obj,
+					get: (obj) => obj.catalog
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _install_decorators, {
+				kind: "method",
+				name: "install",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "install" in obj,
+					get: (obj) => obj.install
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _installStatus_decorators, {
+				kind: "method",
+				name: "installStatus",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "installStatus" in obj,
+					get: (obj) => obj.installStatus
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _outdated_decorators, {
+				kind: "method",
+				name: "outdated",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "outdated" in obj,
+					get: (obj) => obj.outdated
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		options = __runInitializers(this, _instanceExtraInitializers);
+		/** The profile dsh installs into; discovered from this module's own
+		* location when the caller does not supply one. */
+		profile;
+		profileDir;
+		inventory;
+		dshBin;
+		/** The install gate runs against the last loaded snapshot, never a fresh
+		* fetch per request (§7.2: the Host's cached snapshot is the truth). */
+		/** Finished install records retained, so a poll sees the true terminal
+		* state (§8: done / needsRestart / failure detail). Oldest evicted on add. */
+		static MAX_FINISHED_INSTALLS = 32;
+		/** The install gate runs against the last loaded snapshot, never a fresh
+		* fetch per request (§7.2: the Host's cached snapshot is the truth). */
+		lastSnapshot = null;
+		/** Install records, running and finished; a poll finds one here or reports not found. */
+		installs = /* @__PURE__ */ new Map();
+		/** Every install id in insertion order, oldest first; finished-record eviction walks this from the front. */
+		installOrder = [];
+		constructor(ctx, options = {}) {
+			super(ctx, "store");
+			this.options = options;
+			this.profile = options.profile ?? discoverProfile(fileURLToPath(import.meta.url), this.bootBaseDir()).name;
+			this.profileDir = options.profileDir;
+			this.inventory = options.inventory;
+			this.dshBin = options.dshBin ?? "dsh";
+		}
+		/** The boot's Loader root directory (the active profile's `cordis.yml`
+		* directory, carried on `ctx.baseUrl`), when present. A `link:` install
+		* keeps this package at its source location, so the walk-up from
+		* `import.meta.url` finds the repo rather than a profile; `ctx.baseUrl`
+		* is the boot-provided authoritative answer. */
+		bootBaseDir() {
+			const baseUrl = this.ctx.baseUrl;
+			if (typeof baseUrl !== "string" || !baseUrl.startsWith("file:")) return void 0;
+			try {
+				return fileURLToPath(baseUrl);
+			} catch {}
+		}
+		/** The profile directory the user layer lives in — the discovered default
+		* stays lazy so `setEnabled` works in tests via the `profileDir` option
+		* without requiring a real profile above this module. */
+		profileDirResolved() {
+			if (this.profileDir !== void 0) return this.profileDir;
+			return discoverProfile(fileURLToPath(import.meta.url), this.bootBaseDir()).dir;
+		}
+		listInventory() {
+			if (this.inventory !== void 0) return this.inventory.list();
+			const inventory = this.ctx.get?.("pluginInventory");
+			if (inventory === void 0) throw new Error("dsh-plugin-shop: pluginInventory service is not mounted");
+			return inventory.list();
+		}
+		/** Enable or disable one installed plugin, hot (§8): a disable writes the
+		* row to the user layer, an enable drops it again so the bundle default
+		* rules — the CLI's watchUserPatches applies either through HMR. */
+		setEnabled(args) {
+			const entry = this.listInventory().find((entry) => entry.moduleName === args.name);
+			if (entry === void 0) return {
+				ok: false,
+				detail: `dsh-plugin-shop: ${args.name} is not installed`
+			};
+			setUserLayerRow({
+				profileDir: this.profileDirResolved(),
+				row: {
+					id: entry.entryId,
+					disabled: !args.enabled
+				}
+			});
+			return { ok: true };
+		}
+		rowConfig() {
+			if (this.options.catalogUrl !== void 0 && this.options.cacheDir !== void 0) return {
+				catalogUrl: this.options.catalogUrl,
+				cacheDir: this.options.cacheDir
+			};
+			const config = (this.ctx.loader?.entries().find((entry) => entry.options.name === "dsh-plugin-shop"))?.options.config;
+			const catalogUrl = config?.catalogUrl;
+			const cacheDir = config?.cacheDir;
+			if (typeof catalogUrl !== "string" || typeof cacheDir !== "string") throw new Error("dsh-plugin-shop: the store row is missing catalogUrl or cacheDir config");
+			return {
+				catalogUrl,
+				cacheDir
+			};
+		}
+		/** Browse the catalog (§7.3): cached snapshot, refreshed on demand. */
+		async catalog(args) {
+			const { catalogUrl, cacheDir } = this.rowConfig();
+			const { snapshot, stale } = await (this.options.loadCatalog ?? loadCatalog)({
+				baseUrl: catalogUrl,
+				cacheDir,
+				refresh: args?.refresh ?? false
+			});
+			this.lastSnapshot = snapshot;
+			return {
+				schemaVersion: snapshot.schemaVersion,
+				builtAt: snapshot.builtAt,
+				stale,
+				plugins: snapshot.entries,
+				denied: snapshot.denied
+			};
+		}
+		/**
+		* Install one cataloged version into the profile (§7.2). The four rejection
+		* paths run against this Host's snapshot before anything is spawned; only a
+		* passing request reaches the executor.
+		*/
+		async install(args) {
+			if (this.lastSnapshot === null) {
+				const { catalogUrl, cacheDir } = this.rowConfig();
+				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
+					baseUrl: catalogUrl,
+					cacheDir
+				});
+				this.lastSnapshot = snapshot;
+			}
+			const verdict = validateInstall(this.lastSnapshot, args);
+			if (!verdict.ok) return {
+				ok: false,
+				code: verdict.code,
+				detail: verdict.detail
+			};
+			const running = startInstall({
+				profile: this.profile,
+				spec: `${args.name}@${args.version}`,
+				dshBin: this.dshBin,
+				expectedName: args.name
+			});
+			this.installs.set(running.installId, running);
+			this.installOrder.push(running.installId);
+			this.evictFinishedInstalls();
+			return {
+				ok: true,
+				installId: running.installId
+			};
+		}
+		/** Bound retained finished records at MAX_FINISHED_INSTALLS, evicting the
+		* oldest finished ones (insertion order, oldest first). Running records
+		* are never evicted; an id absent from the map reports `found: false`. */
+		evictFinishedInstalls() {
+			const finishedIds = [];
+			for (const id of this.installOrder) {
+				const record = this.installs.get(id);
+				if (record !== void 0 && record.status().state !== "running") finishedIds.push(id);
+			}
+			const excess = Math.max(0, finishedIds.length - StoreGateway.MAX_FINISHED_INSTALLS);
+			for (const id of finishedIds.slice(0, excess)) this.installs.delete(id);
+		}
+		/** Poll one install's progress (§7.2); unknown ids report `found: false`. */
+		installStatus(args) {
+			const running = this.installs.get(args.installId);
+			if (running === void 0) return {
+				found: false,
+				state: "failed",
+				log: [],
+				detail: `unknown installId: ${args.installId}`
+			};
+			return {
+				found: true,
+				...running.status()
+			};
+		}
+		/** Installed plugins whose installed version is older than the catalog's (§7.3). */
+		async outdated() {
+			if (this.lastSnapshot === null) {
+				const { catalogUrl, cacheDir } = this.rowConfig();
+				const { snapshot } = await (this.options.loadCatalog ?? loadCatalog)({
+					baseUrl: catalogUrl,
+					cacheDir
+				});
+				this.lastSnapshot = snapshot;
+			}
+			const dependencies = readProfileManifest("dsh-plugin-shop", this.profileDirResolved()).dependencies ?? {};
+			const outdated = [];
+			for (const entry of this.lastSnapshot.entries) {
+				const installed = dependencies[entry.name];
+				if (installed === void 0) continue;
+				let floor;
+				if (installed === entry.version) floor = installed;
+				else try {
+					floor = minVersion(installed)?.version ?? null;
+				} catch {
+					floor = null;
+				}
+				if (floor !== null && lt(floor, entry.version)) outdated.push({
+					name: entry.name,
+					installed,
+					latest: entry.version
+				});
+			}
+			return outdated;
+		}
+	};
+})();
+//#endregion
+export { StoreGateway, StoreGateway as default };