dsh-plugin-shop 0.9.0 → 0.9.1-beta.0

package/lib/index.js

@@ -180,11 +180,20 @@ function httpOrigin(baseUrl, fetchImpl) {
 * Pure — bytes in, a path-to-bytes map out. It handles exactly what `npm
 * pack` emits and refuses everything else loudly, because the alternative to
 * a small strict reader is a fourth runtime dependency (design §4). */
-/** Bytes up to the first NUL, as ASCII. Tar pads its fixed-width text fields
-* with NULs, so a plain toString would carry them into the path. */
+/** Bytes up to the first NUL, one character for each byte. Tar pads its
+* fixed-width text fields with NULs, so a plain toString would carry them into
+* the path.
+*
+* `latin1`, not `ascii`: a name is bytes, and `ascii` drops the high bit of
+* every one, so a name written in UTF-8 came back as a different string (`é`,
+* C3 A9, as `C)`) that could be another file's name. One character for each
+* byte is lossless and is the same string for a name that is ASCII, which is
+* every name the npm transport reads. A caller that wants the characters of a
+* UTF-8 name decodes `Buffer.from(name, 'latin1')`, or looks a name up as
+* `Buffer.from(wanted, 'utf8').toString('latin1')`. */
 function cstring(field) {
 	const end = field.indexOf(0);
-	return field.subarray(0, end === -1 ? field.length : end).toString("ascii");
+	return field.subarray(0, end === -1 ? field.length : end).toString("latin1");
 }
 /** Tar sizes are octal text, NUL- or space-terminated. An unparseable size
 * would desynchronise every subsequent header, so it throws rather than
@@ -206,13 +215,20 @@ function assertContained(path) {
 /**
 * Parse an uncompressed tar archive into path → bytes.
 *
-* Directory entries and every non-regular type (symlinks, pax and GNU
-* extension headers) are skipped: npm packs regular files under `package/`,
-* and a catalog tarball that needs anything else is not one we published.
+* Directory entries and the type flags that carry no file are skipped: npm
+* packs regular files under `package/`, and a catalog tarball that needs
+* anything else is not one we published. A pax (`x`) or GNU (`L`) header is not
+* a file either, but it NAMES the next one: a path too long or too wide for a
+* ustar header arrives this way, and skipping the header without reading it
+* left its file under a truncated name, reported missing from an archive that
+* ships it ({@link pathFromPax}).
+* Each path is spelled by its bytes, one character each ({@link cstring}).
 */
 function readTar(buffer) {
 	const files = /* @__PURE__ */ new Map();
 	let offset = 0;
+	/** The name a pax or GNU header gives the header after it. */
+	let extendedPath = null;
 	while (offset + 512 <= buffer.length) {
 		const header = buffer.subarray(offset, offset + 512);
 		if (header.every((byte) => byte === 0)) break;
@@ -220,13 +236,49 @@ function readTar(buffer) {
 		const prefix = cstring(header.subarray(345, 500));
 		const size = parseOctal(header.subarray(124, 136));
 		const typeflag = String.fromCharCode(header[156] ?? 0);
-		const path = prefix === "" ? name : `${prefix}/${name}`;
-		offset += 512;
-		if (typeflag === "0" || typeflag === "\0") files.set(assertContained(path), buffer.subarray(offset, offset + size));
-		offset += Math.ceil(size / 512) * 512;
+		const data = buffer.subarray(offset + 512, offset + 512 + size);
+		offset += 512 + Math.ceil(size / 512) * 512;
+		if (typeflag === "x") {
+			extendedPath = pathFromPax(data) ?? extendedPath;
+			continue;
+		}
+		if (typeflag === "L") {
+			extendedPath = cstring(data);
+			continue;
+		}
+		const path = extendedPath ?? (prefix === "" ? name : `${prefix}/${name}`);
+		extendedPath = null;
+		if (typeflag === "0" || typeflag === "\0") files.set(assertContained(path), data);
 	}
 	return files;
 }
+/**
+* The `path` record of a pax extended header, in the reader's spelling, or null
+* where the header names none.
+*
+* A pax record is `<length> <key>=<value>\n`, where `<length>` counts the whole
+* record in bytes, its own digits included. The value is UTF-8 text, and the
+* reader spells a name one character for each byte.
+*/
+function pathFromPax(data) {
+	let at = 0;
+	while (at < data.length) {
+		const space = data.indexOf(32, at);
+		if (space === -1) return null;
+		const length = Number.parseInt(data.subarray(at, space).toString("latin1"), 10);
+		if (!Number.isSafeInteger(length) || length <= 0 || at + length > data.length) return null;
+		const record = data.subarray(at, at + length);
+		const equals = record.indexOf(61, space - at);
+		if (equals !== -1) {
+			if (record.subarray(space - at + 1, equals).toString("utf8") === "path") {
+				const end = record[record.length - 1] === 10 ? record.length - 1 : record.length;
+				return record.subarray(equals + 1, end).toString("latin1");
+			}
+		}
+		at += length;
+	}
+	return null;
+}
 //#endregion
 //#region src/host/npm-origin.ts
 /** The npm transport (design §2, §3): the catalog as a package.
@@ -520,6 +572,45 @@ function holderLabel(spec, name) {
 	if (spec.trim() === "") return "\"\"";
 	return spec.length > HOLDER_SPEC_CAP ? `${spec.slice(0, 79)}…` : spec;
 }
+//#endregion
+//#region src/shared/npm-name.ts
+/**
+* The npm package-name grammar a catalogue row's `name` must satisfy.
+*
+* ONE definition, read in three places: the Host's entry schema
+* (`host/catalog.ts`), the registry's gate (`registry/scripts/src/gate.ts`)
+* and `emit`'s last-line invariant. The dependency can only point this way —
+* the package's tsconfig pins `rootDir: "src"`, so the registry reaches in
+* and nothing here can reach out (the same reason `shop-like.ts` lives here).
+*
+* Why it is narrower than npm's own rule: `validate-npm-package-name` accepts
+* a scope beginning with `_` or `.` — `@_iluxury/dsh-routerai-price-watcher`
+* is valid for a NEW publication — while this grammar requires the scope's
+* first character to be a letter or digit. That was a deliberate argv-safety
+* choice when the rule lived only in the client: the name becomes half of an
+* install spec, and everything this excludes is shell punctuation. It stopped
+* being merely a client rule the moment a catalogue shipped, because the
+* clients parse the WHOLE data file as one zod object: a single name outside
+* this grammar costs every listing, not one. On 2026-10-30
+* `@_iluxury/dsh-routerai-price-watcher` did exactly that — valid on npm, no
+* gate rule to catch it, and every 0.8.0+ shop answered 「暂时无法读取目录」
+* for a 21,493-row catalogue. The gate now admits only what this parses.
+*
+* The narrow side is therefore the WIRE CONTRACT, frozen by the installed
+* base: widening it in a client release also widens the gate, because this is
+* one constant, and the catalogue would then carry names every older client
+* still refuses. Do not widen it without a way to know which client versions
+* are installed; npm's per-version download counts cannot answer that (the
+* measurement is in `emit.ts`'s `peers` comment).
+*
+* @module shared/npm-name
+*/
+/**
+* An optional `@scope/`, then a name starting with a letter or digit and
+* continuing in lowercase letters, digits, `.`, `_` or `-`. No uppercase, no
+* leading dot or underscore on either segment, and no shell punctuation.
+*/
+const CATALOG_NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 /** A cached catalog younger than this is served without touching the network. */
 const FRESH_MS = 3e5;
 /** How long a probe may take before the race gives up on that origin. Long
@@ -550,9 +641,6 @@ async function withCommitBudget(id, what, start) {
 		clearTimeout(timer);
 	}
 }
-/** npm's package-name grammar. The value becomes half of an install spec, so
-* aliases and shell punctuation must not reach the CLI. */
-const NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 /** Canonical SemVer 2.0.0, including legal prerelease/build metadata. */
 const NPM_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
 /** The repository binding used to build a GitHub install spec. */
@@ -653,10 +741,11 @@ const entrySchema = z.object({
 	unpackedSize: z.number().int().nonnegative().optional(),
 	installSize: z.number().int().nonnegative().optional(),
 	archived: z.boolean().optional(),
-	forked: z.boolean().optional()
+	forked: z.boolean().optional(),
+	icon: z.string().regex(/^[0-9a-f]{64}$/).optional()
 }).superRefine((entry, ctx) => {
 	if (entry.source === "npm") {
-		if (!NPM_NAME.test(entry.name)) ctx.addIssue({
+		if (!CATALOG_NPM_NAME.test(entry.name)) ctx.addIssue({
 			code: "custom",
 			path: ["name"],
 			message: `npm entry name ${JSON.stringify(entry.name)} is outside npm package-name grammar`
@@ -734,6 +823,10 @@ const pointerSchema = z.object({
 	stars: z.object({
 		url: z.string(),
 		sha256: z.string()
+	}).optional(),
+	icons: z.object({
+		url: z.string(),
+		sha256: z.string()
 	}).optional()
 });
 const nodeFs$1 = {
@@ -757,6 +850,34 @@ function parseStarsText(text) {
 		return {};
 	}
 }
+/** The longest a data URL holding MAX_CATALOG_ICON_BYTES can be: the base64
+* alphabet is 4 characters per 3 bytes, and the prefix is the longest of the
+* four media types' spellings. */
+const MAX_ICON_DATA_URL_LENGTH = 26 + Math.ceil(32768 / 3) * 4;
+/** The four types a catalogue icon can have (design §6.1); nothing else
+* reaches an `img.src`. */
+const ICON_DATA_URL = /^data:image\/(?:svg\+xml|png|jpeg|webp);base64,[A-Za-z0-9+/]+={0,2}$/;
+/**
+* Read and verify an icons sidecar; ANY irregularity degrades to no icons —
+* icons are presentation, and they never cost the reader the catalog (§7).
+* The checks are the grammar the build writes: a 64-hex sha256 keying a
+* `data:` URL of the four types, each within the per-icon bound.
+*/
+function parseIconsText(text) {
+	try {
+		const parsed = JSON.parse(text);
+		if (typeof parsed.icons !== "object" || parsed.icons === null || Array.isArray(parsed.icons)) return {};
+		const out = Object.create(null);
+		for (const [key, value] of Object.entries(parsed.icons)) {
+			if (!/^[0-9a-f]{64}$/.test(key)) return {};
+			if (typeof value !== "string" || value.length > MAX_ICON_DATA_URL_LENGTH || !ICON_DATA_URL.test(value)) return {};
+			out[key] = value;
+		}
+		return out;
+	} catch {
+		return {};
+	}
+}
 /**
 * 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`
@@ -806,13 +927,19 @@ async function loadCatalog(options) {
 			const starsText = fsImpl.read(cachePath(cacheDir, pointer.stars.url, "stars"));
 			if (createHash("sha256").update(starsText).digest("hex") === pointer.stars.sha256) stars = parseStarsText(starsText);
 		} catch {}
+		let icons = {};
+		if (pointer.icons !== void 0) try {
+			const iconsText = fsImpl.read(cachePath(cacheDir, pointer.icons.url, "icons"));
+			if (createHash("sha256").update(iconsText).digest("hex") === pointer.icons.sha256) icons = parseIconsText(iconsText);
+		} catch {}
 		return {
 			schemaVersion: pointer.schemaVersion,
 			builtAt: pointer.builtAt,
 			entries: data.plugins,
 			denied: data.denied,
 			notAShop: data.notAShop,
-			stars
+			stars,
+			icons
 		};
 	};
 	if (!refresh && fsImpl.exists(indexPath)) {
@@ -879,13 +1006,26 @@ async function loadCatalog(options) {
 			}
 		} catch {}
 	}
+	let icons = {};
+	if (pointer.icons !== void 0) {
+		const sidecar = pointer.icons;
+		try {
+			const iconsCachePath = cachePath(cacheDir, sidecar.url, "icons");
+			const iconsText = await withCommitBudget(handle.id, `serve ${sidecar.url}`, (signal) => handle.file(sidecar.url, signal));
+			if (createHash("sha256").update(iconsText).digest("hex") === sidecar.sha256) {
+				icons = parseIconsText(iconsText);
+				fsImpl.write(iconsCachePath, iconsText);
+			}
+		} catch {}
+	}
 	const snapshot = {
 		schemaVersion: pointer.schemaVersion,
 		builtAt: pointer.builtAt,
 		entries: data.plugins,
 		denied: data.denied,
 		notAShop: data.notAShop,
-		stars
+		stars,
+		icons
 	};
 	try {
 		fsImpl.write(dataCachePath, dataText);
@@ -1020,7 +1160,7 @@ function validateInstall(snapshot, args, installedSpec) {
 	if (denied !== void 0) return {
 		ok: false,
 		code: "denied",
-		detail: `dsh-plugin-shop: ${args.name} is denied: ${denied.detail}`
+		detail: `dsh-plugin-shop: installation of ${args.name} is blocked: ${denied.detail}`
 	};
 	let entry;
 	if (args.source === void 0) {
@@ -1028,7 +1168,7 @@ function validateInstall(snapshot, args, installedSpec) {
 		if (named.length > 1) return {
 			ok: false,
 			code: "ambiguous-identity",
-			detail: `dsh-plugin-shop: the catalog holds ${named.length} entries named ${args.name}, and this request does not say which one; refresh the shop and try again`
+			detail: `dsh-plugin-shop: the catalog has ${named.length} plugins named ${args.name}. Refresh the shop and select the one you want to install.`
 		};
 		entry = named[0];
 	} else {
@@ -1053,7 +1193,7 @@ function validateInstall(snapshot, args, installedSpec) {
 	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})`
+		detail: `dsh-plugin-shop: you requested ${args.name}@${args.version}, but the catalog lists ${entry.version}. Refresh the shop and try again.`
 	};
 	if (installedSpec !== void 0) {
 		const verdict = specVerdict(entry, installedSpec);
@@ -1062,14 +1202,14 @@ function validateInstall(snapshot, args, installedSpec) {
 			return {
 				ok: false,
 				code: "name-taken",
-				detail: `${verdict === "unknown" ? `dsh-plugin-shop: ${args.name} is already installed from ${holder}, which the shop cannot identify as any catalog entry.` : `dsh-plugin-shop: ${args.name} is already installed from ${holder}.`} A profile holds one dependency per name, so installing this one would overwrite it and the plugin you have would be gone. Uninstall it first if you mean to switch.`
+				detail: `${verdict === "unknown" ? `dsh-plugin-shop: ${args.name} is already installed from ${holder}. The shop could not match it to a catalog entry.` : `dsh-plugin-shop: ${args.name} is already installed from ${holder}.`} Installing this plugin would replace it, since a profile can hold only one plugin of each name. To switch, uninstall the existing plugin first.`
 			};
 		}
 	}
 	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`
+		detail: entry.tier === "verified-stale" ? `dsh-plugin-shop: a different version of ${args.name} was reviewed. The current version has not been reviewed. Confirm the installation to continue.` : `dsh-plugin-shop: ${args.name} is a community plugin and has not been reviewed. Confirm the installation to continue.`
 	};
 	return {
 		ok: true,
@@ -1632,11 +1772,11 @@ function createBoundedLog() {
 */
 function activationFailureDetail(args) {
 	const { expectedName, profile, before, after } = args;
-	if (Object.hasOwn(after, expectedName)) return `${expectedName} is a dependency of the profile but is not in dsh.profile.bundles, so dsh did not activate it as a profile layer and the shop has nothing to mount.`;
-	if (before === null) return `${expectedName} is in neither dsh.profile.bundles nor the profile's dependencies, and the profile manifest could not be read before the install, so what the install changed is unknown — compare the profile's package.json against what you expected before retrying.`;
+	if (Object.hasOwn(after, expectedName)) return `${expectedName} is installed as a profile dependency, but is not listed in dsh.profile.bundles. dsh has not enabled it as a plugin, so the shop cannot load it.`;
+	if (before === null) return `${expectedName} is missing from both dsh.profile.bundles and the profile dependencies. The shop could not read the profile before installation, so it cannot tell what changed. Check the profile's package.json before trying again.`;
 	const added = Object.keys(after).filter((name) => !Object.hasOwn(before, name)).sort();
-	if (added.length > 0) return `${expectedName} is not in the profile's dependencies — the install added ${added.join(", ")} instead. Remove it with: dsh plugin --profile ${profile} remove ${added[0]}`;
-	return `${expectedName} is in neither dsh.profile.bundles nor the profile's dependencies, and the install added nothing — if the entry is new the catalog may be behind; refresh it and retry.`;
+	if (added.length > 0) return `${expectedName} is not in the profile dependencies. The install added ${added.join(", ")} instead. To remove ${added[0]}, run: dsh plugin --profile ${profile} remove ${added[0]}`;
+	return `${expectedName} is missing from both dsh.profile.bundles and the profile dependencies. Nothing was added. If this plugin was recently published, the catalog may be out of date. Refresh it and try again.`;
 }
 /** 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
@@ -1663,7 +1803,7 @@ function confirmBundleActivation(profile, home, expectedName, before) {
 			after
 		});
 	} catch {
-		return `installed but the profile manifest could not be read (${join(profileDir, "package.json")}) — the install's result is unknown; check that file.`;
+		return `Could not confirm the installation because the profile manifest could not be read (${join(profileDir, "package.json")}). Check that file before trying again.`;
 	}
 }
 /** The uninstall mirror of §7.2 step 6: after a zero exit, re-read the profile
@@ -1673,9 +1813,9 @@ function confirmBundleRemoval(profile, home, expectedName) {
 	const profileDir = resolveProfileDir(profile, home);
 	try {
 		if (!readProfileManifest("dsh-plugin-shop", profileDir).dsh?.profile?.bundles?.includes(expectedName)) return null;
-		return "removed but dsh.profile.bundles did not change — re-run the uninstall";
+		return "The uninstall command finished, but the plugin is still listed in dsh.profile.bundles. Try uninstalling it again.";
 	} catch {
-		return `removed but the profile manifest could not be read (${join(profileDir, "package.json")}) — re-run the uninstall`;
+		return `Could not confirm the uninstall because the profile manifest could not be read (${join(profileDir, "package.json")}). Check that file and try again.`;
 	}
 }
 /** Lines a failed install's log tends to END on, none of which tell the user
@@ -1783,7 +1923,7 @@ const NATIVE_ALLOCATION_ABORT = /^memory allocation of \d+ bytes failed$/;
 function nativeAllocationAbortDetail(usable) {
 	const abort = usable.find((line) => NATIVE_ALLOCATION_ABORT.test(line.trim()));
 	if (abort === void 0) return null;
-	return `pnpm crashed: its native binary ran out of memory (${abort.trim()}), which is not caused by this plugin. pnpm 12 before 12.7.0 has a known bug that exhausts memory when many packages share a missing peer, which every dsh profile has, because dsh keeps peers uninstalled (autoInstallPeers: false; pnpm/pnpm#15362). Upgrade pnpm to 12.7.0 or later, or use pnpm 11, then install again. If your pnpm is already 12.7.0 or later, report the line above to pnpm.`;
+	return `pnpm ran out of memory (${abort.trim()}). pnpm 12 versions before 12.7.0 have a known memory bug with shared missing peer dependencies (pnpm/pnpm#15362). Upgrade pnpm to 12.7.0 or later, or use pnpm 11, then install again. If your pnpm is already 12.7.0 or later, report the line above to pnpm.`;
 }
 /**
 * The one log line worth putting in front of the user, plus the recovery hint.
@@ -1825,13 +1965,13 @@ function installFailureDetail(profile, log, hint = `pnpm failed in the profile.
 * 2026-09-02 as "Update failed / dsh not found on PATH" on a working install.
 */
 function spawnFailureDetail(code, message, dshBin, platform) {
-	if (platform === "win32" && (code === "ENOENT" || code === "EINVAL")) return `the shop could not locate the dsh CLI to run (${dshBin}): on Windows npm installs it as a .cmd shim, which cannot be spawned directly, so the shop runs the ${DSH_PACKAGE} package's own entry through node instead — and that entry was not found. Check that \`dsh --version\` works in a terminal, then reinstall the CLI if it does not.`;
-	if (code === "ENOENT") return "dsh not found on PATH — install the dsh CLI to manage profile plugins";
-	return `dsh spawn failed: ${message}`;
+	if (platform === "win32" && (code === "ENOENT" || code === "EINVAL")) return `The shop could not find the dsh CLI entry file (${DSH_PACKAGE}, command: ${dshBin}). On Windows, the shop needs this file because it cannot run the .cmd launcher directly. Check that \`dsh --version\` works in a terminal, then reinstall the CLI if it does not.`;
+	if (code === "ENOENT") return "dsh was not found on PATH. Install the dsh CLI or add it to PATH, then try again.";
+	return `Could not start dsh: ${message}`;
 }
 /** The failure detail for a command stopped by the shop's deadline. */
 function installTimeoutDetail(profile, timeoutMs) {
-	return `dsh-plugin-shop: the command did not finish within ${Math.max(1, Math.round(timeoutMs / 1e3))}s and was stopped. Run it yourself to see what it is waiting on: dsh plugin --profile ${profile} install`;
+	return `dsh-plugin-shop: the command did not finish within ${Math.max(1, Math.round(timeoutMs / 1e3))}s and was stopped. To check the error and retry, run: dsh plugin --profile ${profile} install`;
 }
 /** The real kill. Exported for the tests that inject a RECORDING `KillFns`:
 * a recorder that only records asserts that a kill was requested and leaves
@@ -4253,33 +4393,33 @@ function thrownTail(message, desktop) {
 /** What each management code means, in dsh 0.1.7-rc.2's own terms (the
 * implementation plan of 2026-09-27, Task 2, records where each is raised). */
 const CODE_SENTENCE = {
-	"unknown-plugin": "dsh lists no plugin entry by that id",
-	"invalid-spec": "dsh could not read the install spec",
-	"ambiguous-install": "dsh could not tell which package the install added",
+	"unknown-plugin": "dsh could not find a plugin with that ID",
+	"invalid-spec": "dsh could not read the package name or install source",
+	"ambiguous-install": "dsh could not identify the installed package",
 	"not-bundle": "the package is not a dsh bundle",
 	"not-removable": "dsh does not allow removing this bundle",
-	"stop-profile": "the bundle is running and this dsh cannot unload it live, so the profile has to be stopped first",
+	"stop-profile": "this bundle is still running; stop dsh for this profile before removing it",
 	"bundle-in-use": "the bundle was switched off, but some of its plugins are still running",
-	"stale-approval": "a build approval names a package pnpm no longer holds",
+	"stale-approval": "the build approval refers to a package that pnpm no longer lists",
 	"management-required": "the plugin belongs to dsh itself",
-	unaddressable: "the plugin is not a row of the profile's own patch, so dsh cannot address it",
-	"operation-error": "dsh hit an unexpected error",
-	"already-installed": "this dsh updates no installed package in place: uninstall it, then install it again"
+	unaddressable: "the plugin is not defined in this profile's configuration, so dsh cannot change it here",
+	"operation-error": "dsh encountered an unexpected error",
+	"already-installed": "this version of dsh cannot update an installed package directly; uninstall it, then install it again"
 };
 /** What each classified pnpm failure was, as dsh classifies it. */
 const KIND_SENTENCE = {
 	"pnpm-missing": "pnpm could not be started",
-	timeout: "pnpm did not finish within dsh's own time bound",
-	"not-found": "no such package was found",
-	"no-matching-version": "no version matching the requested one was found",
-	network: "the network failed",
+	timeout: "pnpm took too long to finish",
+	"not-found": "the package could not be found",
+	"no-matching-version": "the requested version could not be found",
+	network: "the network request failed",
 	"disk-full": "the disk is full",
 	permission: "permission was denied",
 	integrity: "the downloaded package failed its integrity check"
 };
 const WHERE = {
 	registry: " at the registry",
-	"spec-host": " at the host the package is fetched from"
+	"spec-host": " while connecting to the package source"
 };
 /** An own-property read of one of the three tables above. They are object
 * literals, so a bare index read answers for Object.prototype, and a code of
@@ -4306,10 +4446,10 @@ function restorationSentence(output) {
 * so its restoration line is passed on. Without one, an install or update
 * says what dsh's own pre-check says, and an uninstall says nothing of it. */
 function versionRefusalDetail(context, change) {
-	const refused = change.incompatible.map((issue) => `${issue.name}@${issue.version} declares ${Object.entries(issue.peers).map(([peer, range]) => `${peer} ${range}`).join(", ")}, which dsh ${issue.runtimeVersion} does not satisfy`);
+	const refused = change.incompatible.map((issue) => `${issue.name}@${issue.version} requires ${Object.entries(issue.peers).map(([peer, range]) => `${peer} ${range}`).join(", ")}, which dsh ${issue.runtimeVersion} does not satisfy`);
 	const restored = restorationSentence(change.output) ?? (context.operation === "uninstall" || change.truncated ? null : "Nothing was installed.");
 	const base = `dsh-plugin-shop: dsh refused the ${context.operation}: ${refused.join("; ")}.${restored === null ? "" : ` ${restored}`}`;
-	if (context.desktop) return `${base} dsh's CLI, which grants version exemptions, does not manage the desktop profile, and this shop grants none.`;
+	if (context.desktop) return `${base} Version exemptions are not available here: the dsh CLI cannot manage desktop profiles, and the shop cannot grant them.`;
 	const commands = change.incompatible.map((issue) => allowVersionCommand(context.profile, issue)).filter((command) => command !== null);
 	if (commands.length === 0) return base;
 	return `${base} To accept the risk of crashes or data loss for ${commands.length === 1 ? "this exact version" : "these exact versions"}, run: ${commands.join("; ")} - then ${context.operation} again.`;
@@ -4334,9 +4474,9 @@ function codeReason(change, code) {
 * Add plugin dialog refuses a name the profile already holds, so it cannot
 * rerun an update, and with no name listed it offers no such button. */
 function desktopBuildsDetail(context, change, held) {
-	const base = `dsh-plugin-shop: pnpm is holding the build scripts of ${held}, which it blocks by default, and this shop never allows them.`;
+	const base = `dsh-plugin-shop: pnpm blocked build scripts for ${held}. These scripts need approval, which the shop cannot grant.`;
 	if (context.operation !== "install" || change.pendingBuilds.length === 0) return base;
-	return `${base} dsh's Plugins page offers "Allow these scripts and retry" when an install it runs stops on them.`;
+	return `${base} Try installing from dsh's Plugins page. If these scripts block the install there, use "Allow these scripts and retry" to approve them.`;
 }
 /** What a `cancelled` answer means, for every reader: the shop's deadline
 * asked dsh to stop the operation, and dsh answers `cancelled` only once its
@@ -4349,7 +4489,7 @@ function desktopBuildsDetail(context, change, held) {
 * update. */
 function cancelledDetail(context) {
 	const seconds = Math.max(1, Math.round(context.timeoutMs / 1e3));
-	return `dsh-plugin-shop: the ${context.operation} did not finish within ${seconds}s, so the shop cancelled it. dsh stopped it, restored the profile's package.json and pnpm-lock.yaml, and installed nothing. Try the ${context.operation} again from the shop.`;
+	return `dsh-plugin-shop: the ${context.operation} did not finish within ${seconds}s, so the shop cancelled it. dsh restored the profile's package.json and pnpm-lock.yaml. Nothing was installed. Try the ${context.operation} again from the shop.`;
 }
 /** A `ChangeResult` as the shop's terminal install record: design
 * 2026-09-26-plugin-manager-delegation, section 5, read by the first rule
@@ -4395,12 +4535,12 @@ function outcomeByRule(change, context) {
 			};
 			return {
 				state: "failed",
-				detail: `dsh-plugin-shop: pnpm is holding the build scripts of ${held}, which it blocks by default: run \`pnpm approve-builds\` in the profile directory to allow them, then ${context.operation} again.`
+				detail: `dsh-plugin-shop: pnpm blocked build scripts for ${held}. To review and allow them, run \`pnpm approve-builds\` in the profile directory, then ${context.operation} again.`
 			};
 		}
 		if (change.kind === "timeout" && change.failedAt === "spec-host") return {
 			state: "failed",
-			detail: `dsh-plugin-shop: the ${context.operation} failed at the host the package is fetched from: dsh checks that a GitHub repository is reachable before pnpm runs, and that check did not finish within its bound (5 s by default), so pnpm never ran.`
+			detail: `dsh-plugin-shop: the ${context.operation} stopped because the GitHub connection check timed out (5 s by default). pnpm has not run. Check your connection to GitHub and try again.`
 		};
 		const sentence = lookup(KIND_SENTENCE, change.kind);
 		if (sentence !== void 0) {
@@ -4433,7 +4573,7 @@ function outcomeByRule(change, context) {
 		activation: "restart"
 	};
 	if (change.application === "applied" || change.application === "overridden") {
-		const note = change.application === "overridden" ? { detail: "Saved, but a higher-priority layer (the home or invocation patch) decides whether it runs." } : {};
+		const note = change.application === "overridden" ? { detail: "Saved, but a home or startup configuration overrides this setting and controls whether the plugin runs." } : {};
 		if (context.operation !== "uninstall" && context.alreadyImported && !(change.application === "applied" && context.reconcilesRunningPlugins)) return {
 			state: "done",
 			activation: "restart",
@@ -4452,7 +4592,7 @@ function outcomeByRule(change, context) {
 	}
 	return {
 		state: "failed",
-		detail: `dsh-plugin-shop: dsh answered the ${context.operation} with "${change.application ?? "nothing"}", which this shop does not know how to read.`
+		detail: `dsh-plugin-shop: could not confirm the ${context.operation}. dsh returned an unrecognized status: "${change.application ?? "nothing"}".`
 	};
 }
 //#endregion
@@ -4565,7 +4705,7 @@ function startManagerOperation(options) {
 		} catch (error) {
 			settled = {
 				state: "failed",
-				detail: `dsh-plugin-shop: the shop could not read dsh's answer: ${messageOf(error)}`
+				detail: `dsh-plugin-shop: could not read the result from dsh: ${messageOf(error)}`
 			};
 			state = "failed";
 			return status();
@@ -4579,7 +4719,7 @@ function startManagerOperation(options) {
 		} catch (error) {
 			result = {
 				state: "failed",
-				detail: `dsh-plugin-shop: the shop could not check what dsh installed: ${messageOf(error)}`
+				detail: `dsh-plugin-shop: could not verify the installed plugin: ${messageOf(error)}`
 			};
 		}
 		settled = result;
@@ -4741,17 +4881,17 @@ var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializ
 * service and to set an override that the platform check, being checked ahead
 * of the systemd one, could never reach. */
 const RESTART_BLOCKED_DETAIL = {
-	desktop: "dsh-plugin-shop: the desktop profile is managed by the DeepSeek Harness desktop app, and dsh refuses to restart it from here; restart the app to apply the change",
-	"from-default-profile": "dsh-plugin-shop: restart is not supported when dsh was launched with --from-default-profile; from dsh 0.2.1 a restart would recreate the profile from its template and delete every plugin installed in it, this shop included. Restart dsh manually without that flag to apply the change",
-	windows: "dsh-plugin-shop: restart is not supported on Windows yet; restart dsh manually to apply the change",
-	systemd: "dsh-plugin-shop: restart is disabled because this process is a systemd service — a restart would kill the takeover helper along with the unit, and the service would not come back. Set allowRestart: true in the shop row config to override.",
-	"port-zero": "dsh-plugin-shop: restart is not supported when dsh was launched with --port 0; restart dsh manually"
+	desktop: "dsh-plugin-shop: this profile is managed by the DeepSeek Harness desktop app. Restart the app to apply the change.",
+	"from-default-profile": "dsh-plugin-shop: dsh was started with --from-default-profile. In dsh 0.2.1 and later, restarting with this flag recreates the profile from its template and deletes all installed plugins, including the shop. Restart dsh manually without this flag.",
+	windows: "dsh-plugin-shop: restarting from the shop is not supported on Windows yet. Quit dsh and start it again to apply the change.",
+	systemd: "dsh-plugin-shop: dsh is managed by systemd. Restart the service manually; restarting from the shop could stop the service without bringing it back. To allow restarts from the shop, set allowRestart: true in the shop configuration.",
+	"port-zero": "dsh-plugin-shop: dsh was started with --port 0. Its port will change after a restart. Restart dsh manually and open the new address."
 };
 /** Why the shop changes nothing in the desktop profile, for every mutation
 * that spawns dsh's CLI: install, uninstall and self-update. dsh refuses
 * the profile before any of them would run (`isDesktopProfile`), and the
 * failure that surfaced instead read "pnpm failed in the profile". */
-const DESKTOP_PROFILE_DETAIL = "dsh-plugin-shop: the desktop profile is managed by the DeepSeek Harness desktop app, and dsh refuses to change it from the command line the shop runs; add and remove its plugins from the app instead";
+const DESKTOP_PROFILE_DETAIL = "dsh-plugin-shop: this profile is managed by the DeepSeek Harness desktop app. The shop cannot change it through the command line. Add or remove plugins from the app.";
 /** Why a switch through dsh's `pluginManager` waits for an operation this
 * gateway started: dsh holds its profile lock for a whole install or removal
 * (`change()` wraps pnpm) and makes any other change wait for it up to its
@@ -4760,14 +4900,14 @@ const DESKTOP_PROFILE_DETAIL = "dsh-plugin-shop: the desktop profile is managed
 * The shop's own row writer takes no dsh lock, so what it writes alone (the
 * CLI path's switch, and switching a deselected package off) is not
 * refused. */
-const switchWhileBusyDetail = (name) => `dsh-plugin-shop: an install, update or uninstall is still running in this profile, and dsh holds the profile until it ends; switch ${name} after it finishes.`;
+const switchWhileBusyDetail = (name) => `dsh-plugin-shop: an install, update or uninstall is still running in this profile. Wait for it to finish before changing the enabled state of ${name}.`;
 /** The line a record gains when dsh's plugin manager refuses an update in
 * place and the shop continues it through dsh's CLI (design
 * 2026-10-19-dsh-021-readiness §2): what dsh refused, and the command that
 * runs instead. It names a `dsh plugin` command, so it never reaches a
 * desktop reader: the continuation does not run in that profile. */
 function cliFallbackLine(profile, spec) {
-	return `dsh-plugin-shop: dsh's plugin manager updates no installed package in place (already-installed); running \`dsh plugin --profile ${profile} add ${spec}\` instead`;
+	return `dsh-plugin-shop: dsh's plugin manager cannot update this package directly (already-installed). Continuing with: \`dsh plugin --profile ${profile} add ${spec}\``;
 }
 /** How many bytes a release tarball may be at the integrity check. The
 * registry already refuses to publish a tarball over 32 MiB, so 64 MiB is
@@ -4787,10 +4927,10 @@ async function verifyTarballSha256(fetchTarball, url, recordedSha256, maxBytes =
 	try {
 		response = await fetchTarball(url);
 	} catch (error) {
-		return `dsh-plugin-shop: the release tarball could not be fetched (network failure: ${error.message}); refusing to install`;
+		return `dsh-plugin-shop: could not download the release archive. Installation stopped. Network error: ${error.message}`;
 	}
-	if (!response.ok) return `dsh-plugin-shop: the release tarball could not be fetched (HTTP ${response.status}); refusing to install`;
-	if (response.body === null) return "dsh-plugin-shop: the release tarball has no readable body; refusing to install";
+	if (!response.ok) return `dsh-plugin-shop: could not download the release archive (HTTP ${response.status}). Installation stopped.`;
+	if (response.body === null) return "dsh-plugin-shop: the release archive response was empty or unreadable. Installation stopped.";
 	const hash = createHash("sha256");
 	let bytes = 0;
 	const reader = response.body.getReader();
@@ -4803,14 +4943,14 @@ async function verifyTarballSha256(fetchTarball, url, recordedSha256, maxBytes =
 				try {
 					await reader.cancel();
 				} catch {}
-				return `dsh-plugin-shop: the release tarball exceeds the size cap (${maxBytes} bytes); refusing to install`;
+				return `dsh-plugin-shop: the release archive exceeds the size limit (${maxBytes} bytes). Installation stopped.`;
 			}
 			hash.update(value);
 		}
 	} catch (error) {
-		return `dsh-plugin-shop: the release tarball download failed (${error.message}); refusing to install`;
+		return `dsh-plugin-shop: the release archive download failed. Installation stopped. Error: ${error.message}`;
 	}
-	if (hash.digest("hex") !== recordedSha256) return "dsh-plugin-shop: the release tarball failed sha256 verification against the catalog record; refusing to install";
+	if (hash.digest("hex") !== recordedSha256) return "dsh-plugin-shop: the release archive does not match the catalog checksum (SHA-256). Installation stopped.";
 	return null;
 }
 /** An own-property read of a dependency map parsed from the profile manifest.
@@ -5381,7 +5521,7 @@ let ShopGateway = (() => {
 		async setEnabled(args) {
 			if (args.name === "dsh-plugin-shop" || args.name.startsWith("@deepseek-ai/")) return {
 				ok: false,
-				detail: `dsh-plugin-shop: ${args.name} is part of the harness chain and cannot be toggled from the shop`
+				detail: `dsh-plugin-shop: ${args.name} is part of dsh itself and cannot be enabled or disabled from the shop.`
 			};
 			const manager = this.pluginManager();
 			const profileDir = this.profileDirResolved();
@@ -5399,12 +5539,12 @@ let ShopGateway = (() => {
 			} catch (error) {
 				return {
 					ok: false,
-					detail: `dsh-plugin-shop: ${args.name} has a bundle patch that could not be read: ${String(error)}`
+					detail: `dsh-plugin-shop: could not read the plugin configuration for ${args.name}: ${String(error)}`
 				};
 			}
 			if (owned.length === 0) return {
 				ok: false,
-				detail: `dsh-plugin-shop: ${args.name} contributes no plugin entries, so there is nothing to enable or disable`
+				detail: `dsh-plugin-shop: ${args.name} has no plugin entries to enable or disable.`
 			};
 			const selected = this.runningProfileBundles(profileDir);
 			if (selected !== null && !selected.includes(args.name)) return this.setDeselectedEnabled(args.name, args.enabled, profileDir, owned, manager);
@@ -5412,7 +5552,7 @@ let ShopGateway = (() => {
 			const live = (await this.listInventory()).filter((entry) => ownsEntryId(ownedSet, entry.entryId));
 			if (live.length === 0) return {
 				ok: false,
-				detail: `dsh-plugin-shop: ${args.name} is installed but its entries are not in the running plugin tree; restart dsh to compose them`
+				detail: `dsh-plugin-shop: ${args.name} is installed but has not been loaded. Restart dsh to load it.`
 			};
 			if (manager !== null) {
 				if (this.hasRunningCommand()) return {
@@ -5508,7 +5648,7 @@ let ShopGateway = (() => {
 			}
 			if (manager === null) return {
 				ok: false,
-				detail: `dsh-plugin-shop: ${name} is installed but switched off at the bundle level: dsh.profile.bundles in ${join(profileDir, "package.json")} does not list it, so dsh composes none of it, and a restart will not change that. This dsh has no pluginManager service to select it again: add "${name}" back to that list and restart dsh, or uninstall it and install it again from the shop.`
+				detail: `dsh-plugin-shop: ${name} is installed but disabled. It is missing from dsh.profile.bundles in ${join(profileDir, "package.json")}, so restarting alone will not enable it. This version of dsh cannot enable the bundle from the shop. Add "${name}" back to that list and restart dsh, or uninstall it and install it again from the shop.`
 			};
 			if (this.hasRunningCommand()) return {
 				ok: false,
@@ -5520,7 +5660,7 @@ let ShopGateway = (() => {
 			} catch (error) {
 				return {
 					ok: false,
-					detail: `dsh-plugin-shop: dsh could not select ${name} again${thrownTail(messageOf(error), isDesktopProfile(this.profile))}`
+					detail: `dsh-plugin-shop: dsh could not enable ${name} again${thrownTail(messageOf(error), isDesktopProfile(this.profile))}`
 				};
 			}
 			const { change, failure } = this.readManagerAnswer(raw, {
@@ -5579,7 +5719,7 @@ let ShopGateway = (() => {
 			}
 			if (change.application === "overridden") return {
 				change,
-				failure: `dsh-plugin-shop: dsh saved ${words.request}, but a home or invocation patch, which outranks the profile's own, keeps it ${words.stays}.`
+				failure: `dsh-plugin-shop: dsh saved ${words.request}, but a home or startup configuration overrides it. The plugin remains ${words.stays}.`
 			};
 			if (change.application === "applied" || change.application === "restart-required") return {
 				change,
@@ -5587,7 +5727,7 @@ let ShopGateway = (() => {
 			};
 			return {
 				change,
-				failure: `dsh-plugin-shop: dsh answered ${words.request} with "${change.application ?? "nothing"}", which this shop does not know how to read.`
+				failure: `dsh-plugin-shop: could not confirm ${words.request}. dsh returned an unrecognized status: "${change.application ?? "nothing"}".`
 			};
 		}
 		rowConfig() {
@@ -5756,6 +5896,7 @@ let ShopGateway = (() => {
 				denied: snapshot.denied,
 				notAShop: snapshot.notAShop ?? [],
 				stars: snapshot.stars,
+				icons: snapshot.icons ?? {},
 				incompatible,
 				incompatibleHarness
 			};
@@ -5915,14 +6056,14 @@ let ShopGateway = (() => {
 				packageName: name,
 				dependencies: Object.keys(this.profileDependenciesOrNone() ?? {})
 			});
-			if (clash !== null) return `dsh-plugin-shop: ${name} declares the loader entry id "${clash.id}", which ${clash.holder} already declares. dsh refuses to load a plugin tree holding a duplicate entry id, so the profile would not start.` + undo;
+			if (clash !== null) return `dsh-plugin-shop: ${name} and ${clash.holder} use the same plugin entry ID, "${clash.id}". dsh cannot start this profile while both plugins are installed.` + undo;
 			switch (patchDeclarationHazard(declaredBundlePatch({
 				profileDir: this.profileDirResolved(),
 				packageName: name
 			}), harness.patchLists)) {
 				case null: return null;
-				case "list-unsupported": return `dsh-plugin-shop: ${name} lists its bundle patch as several files, which dsh reads from 0.1.7 on; this dsh${harness.dshVersion === null ? "" : ` (${harness.dshVersion})`} reads one and would not start with it installed.` + undo;
-				case "malformed": return `dsh-plugin-shop: ${name} declares its bundle patch as neither a file path nor a list of them, which dsh refuses to load, so the profile would not start.` + undo;
+				case "list-unsupported": return `dsh-plugin-shop: ${name} uses multiple configuration files, which require dsh 0.1.7 or later. Your dsh${harness.dshVersion === null ? "" : ` (${harness.dshVersion})`} only supports one file and cannot start with this plugin installed.` + undo;
+				case "malformed": return `dsh-plugin-shop: ${name} has an invalid bundle patch declaration; it must be a file path or a list of paths. dsh cannot start this profile with the plugin installed.` + undo;
 			}
 		}
 		/** Remember a github entry's pinned commit: the manifest records only
@@ -6030,7 +6171,7 @@ let ShopGateway = (() => {
 				found: false,
 				state: "failed",
 				log: [],
-				detail: `unknown installId: ${args.installId}`
+				detail: `The installation record (${args.installId}) is no longer available. Refresh the shop to check whether the plugin was installed.`
 			};
 			return {
 				found: true,
@@ -6238,7 +6379,7 @@ let ShopGateway = (() => {
 			if (this.committedRestart !== null) return this.committedRestart;
 			if (this.hasRunningCommand()) return {
 				ok: false,
-				detail: "dsh-plugin-shop: an install is still running in this profile; a restart now would boot the new dsh against a half-written profile. Wait for it to finish and try again."
+				detail: "dsh-plugin-shop: an install is still running in this profile. Wait for it to finish before restarting so the configuration can be saved completely."
 			};
 			const blocked = this.staticRestartBlock();
 			if (blocked !== null) return {
@@ -6266,7 +6407,7 @@ let ShopGateway = (() => {
 			} catch (error) {
 				return {
 					ok: false,
-					detail: `dsh-plugin-shop: restart could not be started: ${error.message}`
+					detail: `dsh-plugin-shop: could not start the restart process: ${error.message}`
 				};
 			}
 			this.committedRestart = {