@dsh-workbench/core 1.1.4 → 1.1.5

package/dist/host/index.js

@@ -1,8 +1,8 @@
-import path, { basename, dirname, join, resolve } from "node:path";
+import path, { basename, delimiter, dirname, join, resolve } from "node:path";
 import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc.js";
 import { createHash, randomUUID } from "node:crypto";
-import fs, { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import fs, { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import writeFileAtomic from "write-file-atomic";
@@ -142,7 +142,9 @@ var NEED_KEYS = [
 	"commands",
 	"version",
 	"sources",
-	"secret"
+	"secret",
+	"install",
+	"docs"
 ];
 var SOURCE_KEYS = [
 	"kind",
@@ -203,7 +205,7 @@ function sourcesProblemsOf(raw, at, allowed) {
 	if (raw === void 0) return [];
 	if (!Array.isArray(raw)) return [`${at}.sources 要是数组`];
 	if (raw.length === 0) return [`${at}.sources 是空数组 —— 不代装就整条删掉`];
-	if (allowed.length === 0) return [`${at} 这种需要不支持 sources —— 它没有「从哪装」这回事`];
+	if (allowed.length === 0) return [`${at} 这种需要不支持 sources —— 要代装就写 install（一条命令）`];
 	const errors = [];
 	raw.forEach((source, index) => {
 		const one = sourceProblemsOf(source, `${at}.sources[${index}]`);
@@ -222,11 +224,40 @@ function commonProblemsOf(raw, at) {
 	if (raw["id"] !== void 0 && text$3(raw["id"]) === "") errors.push(`${at}.id 是空串`);
 	return errors;
 }
+function binInstallProblemsOf(raw, at) {
+	if (raw === void 0) return [];
+	if (!isRecord$1(raw)) return [`${at}.install 要是对象`];
+	const errors = [];
+	for (const key of Object.keys(raw)) if (![
+		"kind",
+		"line",
+		"platforms",
+		"package",
+		"registryEnv",
+		"registryDefault"
+	].includes(key)) errors.push(`${at}.install 有不认识的字段 ${key}`);
+	const kind = text$3(raw["kind"]);
+	if (kind !== "command" && kind !== "npm") errors.push(`${at}.install.kind 只认 command（一条命令）或 npm（一个包，装进隔离运行时）`);
+	if (kind === "command" && text$3(raw["line"]) === "") errors.push(`${at}.install.line 没写 —— 要一条能直接粘进终端的命令`);
+	if (kind === "npm" && text$3(raw["package"]) === "") errors.push(`${at}.install.package 没写 —— 这个命令由哪个 npm 包提供`);
+	if (raw["registryDefault"] !== void 0 && !REGISTRY_PATTERN.test(text$3(raw["registryDefault"]))) errors.push(`${at}.install.registryDefault 要是 http(s):// 或 file:// 的源地址`);
+	if (raw["platforms"] !== void 0) {
+		if (!Array.isArray(raw["platforms"]) || raw["platforms"].length === 0) errors.push(`${at}.install.platforms 要是非空数组`);
+		else if (raw["platforms"].some((one) => ![
+			"darwin",
+			"linux",
+			"win32"
+		].includes(text$3(one)))) errors.push(`${at}.install.platforms 只认 darwin / linux / win32`);
+	}
+	return errors;
+}
 function perKindProblemsOf(kind, raw, at) {
 	const errors = [];
 	if (kind === "bin" || kind === "lib" || kind === "env") {
 		if (text$3(raw["name"]) === "") errors.push(`${at}.name 没写`);
 	}
+	if (kind === "bin") errors.push(...binInstallProblemsOf(raw["install"], at));
+	if (raw["docs"] !== void 0 && text$3(raw["docs"]) === "") errors.push(`${at}.docs 是空串`);
 	if (kind === "extension") {
 		if (text$3(raw["runtime"]) === "") errors.push(`${at}.runtime 没写 —— 扩展属于哪个运行时（如 opencli）`);
 		if (text$3(raw["name"]) === "") errors.push(`${at}.name 没写`);
@@ -1100,7 +1131,7 @@ var PHASES = [
 	"ready",
 	"error"
 ];
-function asRecord$6(value) {
+function asRecord$7(value) {
 	return typeof value === "object" && value !== null ? value : void 0;
 }
 function textOf$5(value, max) {
@@ -1114,7 +1145,7 @@ function atOf(value) {
 	return Math.trunc(value);
 }
 function errorOf(raw) {
-	const record = asRecord$6(raw);
+	const record = asRecord$7(raw);
 	if (record === void 0) return void 0;
 	const code = textOf$5(record["code"], 120);
 	const message = textOf$5(record["message"], PANEL_STATE_MAX_TEXT);
@@ -1131,7 +1162,7 @@ function errorOf(raw) {
 *   或一条都认不出（`unit` / `route` / `phase` / `at` 缺一）时 `ok: false` + 中文原因；认不出的单条静默跳过。
 */
 function parseCardsReport(payload) {
-	const record = asRecord$6(payload);
+	const record = asRecord$7(payload);
 	if (record === void 0) return {
 		ok: false,
 		message: "请求体要是一个对象"
@@ -1148,7 +1179,7 @@ function parseCardsReport(payload) {
 	};
 	const cards = [];
 	for (const item of raw.slice(0, 32)) {
-		const card = asRecord$6(item);
+		const card = asRecord$7(item);
 		if (card === void 0) continue;
 		const unit = textOf$5(card["unit"], 200);
 		const route = textOf$5(card["route"], 400);
@@ -1182,7 +1213,7 @@ function parseCardsReport(payload) {
 * @returns `workspace` / `unit` / `reason` 都不能空，缺一给 `ok: false` + 中文原因；`at` 缺省或不合法时取当前时间。
 */
 function parseCrashReport(payload) {
-	const record = asRecord$6(payload);
+	const record = asRecord$7(payload);
 	if (record === void 0) return {
 		ok: false,
 		message: "请求体要是一个对象"
@@ -1343,7 +1374,7 @@ var TARGET_CODE = {
 	name: "workbench/no-name",
 	requestId: "workbench/no-request-id"
 };
-function asRecord$5(value) {
+function asRecord$6(value) {
 	return typeof value === "object" && value !== null ? value : {};
 }
 function stringsOf$3(value) {
@@ -1386,7 +1417,7 @@ function requestOf$1(action, value) {
 	};
 }
 function parseProvisionBody(body) {
-	const raw = asRecord$5(body);
+	const raw = asRecord$6(body);
 	const action = raw.action;
 	if (typeof action !== "string" || !PROVISION_ACTIONS.includes(action)) return {
 		ok: false,
@@ -1426,6 +1457,7 @@ var WorkbenchDataError = class extends Error {
 	hint;
 	project;
 	helpUrl;
+	failure;
 	constructor(code, message, extra = {}) {
 		super(message);
 		this.name = "WorkbenchDataError";
@@ -1434,6 +1466,7 @@ var WorkbenchDataError = class extends Error {
 		if (extra.hint !== void 0) this.hint = extra.hint;
 		if (extra.project !== void 0) this.project = extra.project;
 		if (extra.helpUrl !== void 0) this.helpUrl = extra.helpUrl;
+		if (extra.failure !== void 0) this.failure = extra.failure;
 	}
 };
 //#endregion
@@ -1481,7 +1514,8 @@ function toErrorPayload(error) {
 			...data.detail === void 0 ? {} : { detail: data.detail },
 			...data.hint === void 0 ? {} : { hint: data.hint },
 			...data.helpUrl === void 0 ? {} : { helpUrl: data.helpUrl },
-			...data.project === void 0 ? {} : { project: data.project }
+			...data.project === void 0 ? {} : { project: data.project },
+			...data.failure === void 0 ? {} : { failure: data.failure }
 		};
 	}
 	return {
@@ -2231,7 +2265,10 @@ function tokenFamilyOf(name) {
 	return cut === -1 ? rest : rest.slice(0, cut);
 }
 //#endregion
-//#region ../shared/dist/host/tool-approval.js
+//#region ../shared/dist/contract/approval.js
+/**
+* agent 自己那句"这次想干什么"的参数名：插件命令族必填，审批屏把它画在详情座里，不进标题。
+*/
 var APPROVAL_NOTE_ARG = "approval_note";
 function oneLine(text) {
 	return text.replace(/\s+/g, " ").trim();
@@ -2295,10 +2332,11 @@ async function approvalFor(call, context = {}) {
 		reason: facts.blocked
 	};
 	if (context.skipAsk === true) return void 0;
+	const note = context.declaredNote === true && verdict.noteInDetail !== true ? approvalNoteOf(call) : void 0;
 	return {
 		kind: "ask",
 		reason: verdict.reason,
-		displayReason: compose(facts, verdict, context.declaredNote === true ? approvalNoteOf(call) : void 0)
+		displayReason: compose(facts, verdict, note)
 	};
 }
 //#endregion
@@ -2518,6 +2556,188 @@ function backgroundLine(command, argv) {
 	].join(" ");
 }
 //#endregion
+//#region ../shared/dist/host/install-failure.js
+var TARGET_FLAGS = [
+	"--prefix",
+	"--cache",
+	"--dir",
+	"--store-dir"
+];
+var INSTALL_VERBS = /^\s*npm\s+(i|install|add)\b/;
+var NPM_PATH = /^npm (?:error|ERR!) path (.+)$/m;
+function commandTokens(command) {
+	const tokens = [];
+	const token = /'([^']*)'|"([^"]*)"|(\S+)/g;
+	for (let match = token.exec(command); match !== null; match = token.exec(command)) tokens.push(match[1] ?? match[2] ?? match[3] ?? "");
+	return tokens;
+}
+function installTargets(command) {
+	const tokens = commandTokens(command);
+	const targets = [];
+	for (let index = 0; index < tokens.length - 1; index += 1) if (TARGET_FLAGS.includes(tokens[index] ?? "")) targets.push(tokens[index + 1] ?? "");
+	return targets.filter((target) => target !== "");
+}
+function failurePathIn(output) {
+	const path = NPM_PATH.exec(output)?.[1]?.trim();
+	return path === void 0 || path === "" ? void 0 : path;
+}
+function nearestDir(path) {
+	let at = path;
+	for (;;) {
+		const here = () => {
+			try {
+				return statSync(at).isDirectory();
+			} catch {
+				return false;
+			}
+		};
+		if (here()) return at;
+		const up = dirname(at);
+		if (up === at) return void 0;
+		at = up;
+	}
+}
+function writeStateOf(dir) {
+	try {
+		accessSync(dir, constants.W_OK);
+		return "ok";
+	} catch (error) {
+		return error.code === "EACCES" ? "denied" : "unknown";
+	}
+}
+function dirFacts(dir) {
+	try {
+		const stats = statSync(dir);
+		return {
+			mode: (stats.mode & 511).toString(8),
+			owner: {
+				uid: stats.uid,
+				gid: stats.gid
+			},
+			writable: writeStateOf(dir) === "ok"
+		};
+	} catch {
+		return;
+	}
+}
+function currentUser() {
+	return {
+		uid: process.getuid?.() ?? -1,
+		gid: process.getgid?.() ?? -1
+	};
+}
+function classifyInstallFailure(output) {
+	const text = output.toLowerCase();
+	if (/enospc|no space left/.test(text)) return "disk-full";
+	if (/eacces|eperm|permission denied|operation not permitted|access is denied/.test(text)) return "permission";
+	return "unknown";
+}
+function installFailureOf(facts) {
+	const kind = facts.kind ?? classifyInstallFailure(facts.output);
+	const path = facts.path;
+	const base = {
+		command: facts.command,
+		exitCode: facts.exitCode,
+		output: facts.output,
+		...path === void 0 ? {} : { path },
+		...facts.mode === void 0 ? {} : { mode: facts.mode },
+		...facts.owner === void 0 ? {} : { owner: facts.owner },
+		current: facts.current
+	};
+	if (kind === "disk-full") return {
+		...base,
+		kind,
+		fix: path === void 0 ? { kind: "handoff" } : {
+			kind: "space",
+			path
+		}
+	};
+	if (kind === "permission" && path !== void 0) {
+		const owner = facts.owner;
+		if (owner !== void 0 && owner.uid !== facts.current.uid && facts.current.uid >= 0) return {
+			...base,
+			kind,
+			fix: {
+				kind: "chown",
+				path,
+				uid: facts.current.uid,
+				gid: facts.current.gid
+			}
+		};
+		if (facts.writable === false) return {
+			...base,
+			kind,
+			fix: {
+				kind: "chmod",
+				path
+			}
+		};
+		if (facts.writable === true) return {
+			...base,
+			kind: "sandbox",
+			fix: { kind: "handoff" }
+		};
+	}
+	return {
+		...base,
+		kind,
+		fix: { kind: "handoff" }
+	};
+}
+function diagnoseInstallFailure(input) {
+	const current = currentUser();
+	const candidates = [
+		failurePathIn(input.output),
+		...installTargets(input.command),
+		input.fallback
+	].filter((path) => path !== void 0 && path !== "");
+	for (const candidate of candidates) {
+		const dir = nearestDir(candidate);
+		if (dir === void 0) continue;
+		const facts = dirFacts(dir);
+		if (facts === void 0) continue;
+		return installFailureOf({
+			command: input.command,
+			exitCode: input.exitCode,
+			output: input.output,
+			path: dir,
+			mode: facts.mode,
+			owner: facts.owner,
+			writable: facts.writable,
+			current
+		});
+	}
+	return installFailureOf({
+		command: input.command,
+		exitCode: input.exitCode,
+		output: input.output,
+		current
+	});
+}
+function installWriteProblem(input) {
+	if (!INSTALL_VERBS.test(input.command)) return void 0;
+	const current = currentUser();
+	const candidates = [...installTargets(input.command), input.fallback].filter((path) => path !== void 0 && path !== "");
+	for (const candidate of candidates) {
+		const dir = nearestDir(candidate);
+		if (dir === void 0) continue;
+		if (writeStateOf(dir) !== "denied") continue;
+		const facts = dirFacts(dir);
+		if (facts === void 0) continue;
+		return installFailureOf({
+			command: input.command,
+			exitCode: null,
+			output: "",
+			kind: "permission",
+			path: dir,
+			mode: facts.mode,
+			owner: facts.owner,
+			writable: facts.writable,
+			current
+		});
+	}
+}
+//#endregion
 //#region ../shared/dist/host/paths.js
 function isolatedRoot() {
 	return `${workbenchRoot()}/opencli`;
@@ -2531,6 +2751,46 @@ function vendorPluginsDir() {
 function libsPrefix() {
 	return `${isolatedRoot()}/libs`;
 }
+var OPENCLI_NPM_PACKAGE = "@jackwener/opencli";
+function toolchainOpencliDir() {
+	return `${isolatedRoot()}/toolchain/node_modules/${OPENCLI_NPM_PACKAGE}`;
+}
+function libsBinDir() {
+	return `${libsPrefix()}/node_modules/.bin`;
+}
+/**
+* 把隔离运行时的共用依赖 bin 目录放到 PATH 最前面（可执行文件都从这儿找）。
+* @param env 改哪份环境（默认当前进程）。
+* @returns 真的插进去了就 `true`；已经在里面就 `false`。
+*/
+function ensureLibsBinOnPath(env = process.env) {
+	const dir = libsBinDir();
+	const parts = (env.PATH ?? "").split(delimiter).filter((one) => one !== "");
+	if (parts.includes(dir)) return false;
+	env.PATH = [dir, ...parts].join(delimiter);
+	return true;
+}
+//#endregion
+//#region ../shared/dist/host/runtime-links.js
+/**
+* 让共用依赖也能 import opencli：把隔离运行时里那份 opencli 链接到 libs 的 node_modules。
+* 跑在 libs 里的命令（比如 opencli-workflow 带的 gitops）会按包名找 @jackwener/opencli，
+* 找不到就起不来 —— 它不在 libs 的依赖里，是运行时提供的那一份。
+* @returns 这次真的建了链接就 `true`；已经有了、或运行时那份还没装，就是 `false`。
+*/
+function ensureLibsOpencliPeer() {
+	const link = `${libsPrefix()}/node_modules/${OPENCLI_NPM_PACKAGE}`;
+	if (existsSync(link)) return false;
+	const target = toolchainOpencliDir();
+	if (!existsSync(target)) return false;
+	try {
+		mkdirSync(dirname(link), { recursive: true });
+		symlinkSync(target, link);
+		return true;
+	} catch {
+		return false;
+	}
+}
 //#endregion
 //#region ../shared/dist/host/adapters.js
 var WORKBENCH_ADAPTERS = "workbenchAdapters";
@@ -4066,7 +4326,7 @@ function registryFailure(change) {
 //#endregion
 //#region ../shared/dist/host/plugin.js
 var OPENCLI_MANIFEST_FILE = "opencli-plugin.json";
-function asRecord$4(value) {
+function asRecord$5(value) {
 	return typeof value === "object" && value !== null ? value : void 0;
 }
 function isCommandFile(name) {
@@ -4078,7 +4338,7 @@ function pluginManifestOf(dir) {
 	try {
 		const parsed = JSON.parse(readFileSync(join(dir, OPENCLI_MANIFEST_FILE), "utf8"));
 		if (Array.isArray(parsed)) return void 0;
-		return asRecord$4(parsed);
+		return asRecord$5(parsed);
 	} catch {
 		return;
 	}
@@ -4685,20 +4945,20 @@ var MARKET_INDEX_README_LINES = [
 var NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 var GIT_COMMIT = /^[0-9a-f]{40}$/;
 var MAX_ICON_CHARS = 32768;
-function asRecord$3(value) {
+function asRecord$4(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 }
-function asText$3(value) {
+function asText$4(value) {
 	return typeof value === "string" ? value.trim() : "";
 }
 function asTextArray(value) {
 	return Array.isArray(value) ? value.flatMap((item) => typeof item === "string" && item.trim() !== "" ? [item.trim()] : []) : [];
 }
 function asLocalized(value) {
-	const record = asRecord$3(value);
+	const record = asRecord$4(value);
 	if (record === void 0) return void 0;
-	const zh = asText$3(record["zh"]);
-	const en = asText$3(record["en"]);
+	const zh = asText$4(record["zh"]);
+	const en = asText$4(record["en"]);
 	return zh === "" && en === "" ? void 0 : {
 		...zh === "" ? {} : { zh },
 		...en === "" ? {} : { en }
@@ -4715,19 +4975,19 @@ function compareSemver(left, right) {
 	return compareVersions(left, right);
 }
 function sourceOf(raw, at) {
-	const record = asRecord$3(raw);
+	const record = asRecord$4(raw);
 	if (record === void 0) return problem("source", "source 必须是一个对象", at);
 	if (record["type"] === "npm") {
 		const registry = record["registry"];
-		if (registry !== void 0 && asText$3(registry) === "") return problem("source", "npm source 的 registry 必须是非空字符串", at);
+		if (registry !== void 0 && asText$4(registry) === "") return problem("source", "npm source 的 registry 必须是非空字符串", at);
 		return {
 			type: "npm",
-			...registry === void 0 ? {} : { registry: asText$3(registry) }
+			...registry === void 0 ? {} : { registry: asText$4(registry) }
 		};
 	}
 	if (record["type"] === "git") {
-		const url = asText$3(record["url"]);
-		const commit = asText$3(record["commit"]);
+		const url = asText$4(record["url"]);
+		const commit = asText$4(record["commit"]);
 		if (url === "") return problem("source", "git source 缺 url", at);
 		if (!GIT_COMMIT.test(commit)) return problem("git-commit", `git source 的 commit 必须是 40 位小写 SHA（现在是 ${JSON.stringify(commit)}）`, at);
 		const path = record["path"];
@@ -4735,22 +4995,22 @@ function sourceOf(raw, at) {
 			type: "git",
 			url,
 			commit,
-			...path === void 0 || asText$3(path) === "" ? {} : { path: asText$3(path) }
+			...path === void 0 || asText$4(path) === "" ? {} : { path: asText$4(path) }
 		};
 	}
 	return problem("source", "source.type 只能是 npm 或 git", at);
 }
 function versionOf(raw, at) {
-	const record = asRecord$3(raw);
+	const record = asRecord$4(raw);
 	if (record === void 0) return problem("version", "版本必须是一个对象", at);
-	const version = asText$3(record["version"]);
+	const version = asText$4(record["version"]);
 	if (!isValidVersion(version)) return problem("version", `版本号不是合法 SemVer：${JSON.stringify(version)}`, at);
 	const source = sourceOf(record["source"], `${at}.source`);
 	if ("kind" in source) return source;
 	const timestamp = record["publishTimestamp"];
 	if (timestamp !== void 0 && (!Number.isInteger(timestamp) || timestamp < 0)) return problem("timestamp", "publishTimestamp 必须是 Unix 秒整数", at);
-	const engines = asRecord$3(record["engines"]);
-	const dsh = engines === void 0 ? "" : asText$3(engines["dsh"]);
+	const engines = asRecord$4(record["engines"]);
+	const dsh = engines === void 0 ? "" : asText$4(engines["dsh"]);
 	return {
 		version,
 		source,
@@ -4788,14 +5048,14 @@ function ownerProblem(owner) {
 	if (owner.length > MAX_OWNER_CHARS) return problem("owner", "owner 超过 200 字");
 }
 function metadataOf(raw) {
-	const record = asRecord$3(raw);
+	const record = asRecord$4(raw);
 	if (record === void 0) return void 0;
 	const workbench = record["workbench"] === true;
-	const unit = asText$3(record["unit"]);
-	const category = asText$3(record["category"]);
+	const unit = asText$4(record["unit"]);
+	const category = asText$4(record["category"]);
 	const labels = asTextArray(record["labels"]);
 	const keywords = asTextArray(record["keywords"]);
-	const sortKeysRecord = asRecord$3(record["sortKeys"]);
+	const sortKeysRecord = asRecord$4(record["sortKeys"]);
 	const sortKeys = sortKeysRecord === void 0 ? void 0 : Object.fromEntries(Object.entries(sortKeysRecord).flatMap(([key, value]) => typeof value === "string" || typeof value === "number" ? [[key, value]] : []));
 	return {
 		...workbench ? { workbench: true } : {},
@@ -4807,26 +5067,26 @@ function metadataOf(raw) {
 	};
 }
 function entryOf$1(raw, at) {
-	const record = asRecord$3(raw);
+	const record = asRecord$4(raw);
 	if (record === void 0) return problem("plugin", "插件条目必须是对象", at);
-	const name = asText$3(record["name"]);
+	const name = asText$4(record["name"]);
 	if (name === "" || name.length > 214 || !NPM_NAME.test(name)) return problem("name", `不是合法 npm 包名：${JSON.stringify(name)}`, at);
 	const versions = versionsOf$1(record["versions"], `${at}.versions`);
 	if ("kind" in versions) return versions;
-	const icon = asText$3(record["icon"]);
+	const icon = asText$4(record["icon"]);
 	if (icon !== "") {
 		const badIcon = iconProblem(icon);
 		if (badIcon !== void 0) return badIcon;
 	}
 	const title = asLocalized(record["title"]);
 	const description = asLocalized(record["description"]);
-	const author = asText$3(record["author"]);
-	const owner = asText$3(record["owner"]);
+	const author = asText$4(record["author"]);
+	const owner = asText$4(record["owner"]);
 	if (owner !== "") {
 		const badOwner = ownerProblem(owner);
 		if (badOwner !== void 0) return badOwner;
 	}
-	const homepage = asText$3(record["homepage"]);
+	const homepage = asText$4(record["homepage"]);
 	const metadata = metadataOf(record["metadata"]);
 	if (metadata?.unit !== void 0 && !UNIT_ID.test(metadata.unit)) return problem("unit", `metadata.unit 只能是小写字母开头的 a-z0-9-（现在是 ${JSON.stringify(metadata.unit)}）`, at);
 	return {
@@ -4842,7 +5102,7 @@ function entryOf$1(raw, at) {
 	};
 }
 function parseMarketIndex(raw) {
-	const record = asRecord$3(raw);
+	const record = asRecord$4(raw);
 	if (record === void 0) return {
 		ok: false,
 		problems: [problem("not-object", "索引必须是一个 JSON 对象")]
@@ -4878,7 +5138,7 @@ function parseMarketIndex(raw) {
 	};
 	const title = asLocalized(record["title"]);
 	const description = asLocalized(record["description"]);
-	const metadata = asRecord$3(record["metadata"]);
+	const metadata = asRecord$4(record["metadata"]);
 	return {
 		ok: true,
 		index: {
@@ -4932,15 +5192,15 @@ function marketSourceKey(source) {
 	return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
 }
 function parseSourceConfig(raw) {
-	const record = asRecord$3(raw);
+	const record = asRecord$4(raw);
 	if (record === void 0) return {
 		ok: false,
 		problem: problem("source", "索引源必须是对象")
 	};
-	const id = asText$3(record["id"]);
-	const label = asText$3(record["label"]);
+	const id = asText$4(record["id"]);
+	const label = asText$4(record["label"]);
 	const kind = record["kind"];
-	const url = asText$3(record["url"]);
+	const url = asText$4(record["url"]);
 	if (id === "") return {
 		ok: false,
 		problem: problem("source", "索引源缺 id")
@@ -4973,9 +5233,9 @@ function parseSourceConfig(raw) {
 		ok: false,
 		problem: problem("source", "git 地址不合格（只收 https / ssh / scp 形式，且不能带凭据）")
 	};
-	const ref = asText$3(record["ref"]);
-	const path = asText$3(record["path"]);
-	const localPath = asText$3(record["localPath"]);
+	const ref = asText$4(record["ref"]);
+	const path = asText$4(record["path"]);
+	const localPath = asText$4(record["localPath"]);
 	const policy = record["policy"];
 	if (policy !== void 0 && policy !== "artifacts-in-repo" && policy !== "catalog-only") return {
 		ok: false,
@@ -5285,6 +5545,72 @@ function normalizeWhitespace(rows) {
 	return out.join("\n").replace(/\n+$/, "");
 }
 //#endregion
+//#region ../shared/dist/host/installed-sources.js
+var FILE_NAME = ".dsh-workbench-sources.json";
+var FILE_VERSION = 1;
+function asRecord$3(value) {
+	return typeof value === "object" && value !== null ? value : void 0;
+}
+function asText$3(value) {
+	return typeof value === "string" ? value.trim() : "";
+}
+function installedSourcesFile(profileDir) {
+	return path.join(profileDir, FILE_NAME);
+}
+function readInstalledSources(profileDir) {
+	if (profileDir === null) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(fs.readFileSync(installedSourcesFile(profileDir), "utf8"));
+	} catch {
+		return {};
+	}
+	const packages = asRecord$3(asRecord$3(parsed)?.packages);
+	if (packages === void 0) return {};
+	const found = {};
+	for (const [pkg, value] of Object.entries(packages)) {
+		const record = asRecord$3(value);
+		if (record === void 0) continue;
+		const version = asText$3(record.version);
+		const registry = asText$3(record.registry);
+		if (pkg === "" || version === "" || registry === "") continue;
+		found[pkg] = {
+			version,
+			registry
+		};
+	}
+	return found;
+}
+function packageSourceOf(profileDir, pkg) {
+	return readInstalledSources(profileDir)[pkg];
+}
+function writeInstalledSources(profileDir, sources) {
+	const file = installedSourcesFile(profileDir);
+	const temp = `${file}.tmp`;
+	const text = `${JSON.stringify({
+		version: FILE_VERSION,
+		packages: sources
+	}, null, 2)}\n`;
+	fs.writeFileSync(temp, text, { mode: 384 });
+	fs.renameSync(temp, file);
+}
+function rememberPackageSource(profileDir, pkg, source) {
+	const trimmed = pkg.trim();
+	if (trimmed === "" || source.version.trim() === "" || source.registry.trim() === "") return;
+	const all = { ...readInstalledSources(profileDir) };
+	all[trimmed] = {
+		version: source.version.trim(),
+		registry: source.registry.trim()
+	};
+	writeInstalledSources(profileDir, all);
+}
+function forgetPackageSource(profileDir, pkg) {
+	const all = { ...readInstalledSources(profileDir) };
+	if (all[pkg] === void 0) return;
+	delete all[pkg];
+	writeInstalledSources(profileDir, all);
+}
+//#endregion
 //#region ../shared/dist/contract/protocol/dsh-plugins.js
 var DSH_PLUGINS_ROUTE = "dsh-plugins";
 //#endregion
@@ -5483,8 +5809,10 @@ function moduleVersionsHandler(ctx, shell, running, selfUpdate) {
 		const force = param(search, "force") === "1";
 		const fallback = (await manager.registries())?.resolved ?? void 0;
 		const modules = await Promise.all(found.map(async (module) => {
-			const registry = module.registry ?? fallback;
-			const latest = shell === void 0 || registry === void 0 ? void 0 : await supply.latestVersion({
+			const local = module.local === true;
+			const fromRegistry = module.fromRegistry !== false;
+			const registry = fromRegistry ? module.registry ?? fallback : void 0;
+			const latest = local || !fromRegistry || shell === void 0 || registry === void 0 ? void 0 : await supply.latestVersion({
 				shell,
 				name: module.pkg,
 				registry,
@@ -5516,7 +5844,10 @@ function moduleVersionsHandler(ctx, shell, running, selfUpdate) {
 				...title === void 0 ? {} : { title },
 				...latest === void 0 ? {} : { latest },
 				...latestBlocked === void 0 ? {} : { latestBlocked },
-				...module.local === true ? { local: true } : {},
+				...local ? {
+					local: true,
+					latestUnavailable: "local"
+				} : latest !== void 0 ? {} : { latestUnavailable: !fromRegistry ? "not-registry" : registry === void 0 ? "no-registry" : "probe-failed" },
 				...refused === void 0 ? {} : { refused }
 			};
 		}));
@@ -11708,6 +12039,22 @@ function registerRecordTools(ctx, store) {
 	];
 }
 //#endregion
+//#region src/modules/panels/model/market-install-error.ts
+var INSTALL_PROBLEM = {
+	permission: "没有写入权限",
+	"disk-full": "磁盘满了",
+	sandbox: "被系统拦住了",
+	unknown: "命令失败"
+};
+function installError(failure) {
+	const tail = tailLines(failure.output, 6);
+	const stamp = failure.exitCode === null ? "" : `（退出码 ${failure.exitCode}）`;
+	return new WorkbenchDataError("install-failed", `${INSTALL_PROBLEM[failure.kind]}${stamp}${tail === "" ? "" : `：${tail}`}`, {
+		detail: failure.output,
+		failure
+	});
+}
+//#endregion
 //#region src/modules/panels/model/market-dependency.ts
 var DEPENDENCY_KINDS = ["extension", "lib"];
 function dependencyId(kind, name) {
@@ -11929,7 +12276,8 @@ async function settle(deps, spec, options, change) {
 		kind: "unknown",
 		pkg
 	};
-	await deps.rememberSource(deps.manager, pkg, options?.registry);
+	const registry = options?.registry ?? (module.kind === "module" ? module.registry : void 0);
+	await deps.rememberSource(deps.manager, pkg, registry, module.kind === "module" ? module.version : void 0);
 	return {
 		change,
 		module,
@@ -12117,6 +12465,110 @@ async function updateModuleBundle(unit, deps) {
 	};
 }
 //#endregion
+//#region src/modules/panels/model/market-registry.ts
+async function rememberInstalledSource(deps, manager, pkg, registry, version) {
+	const { registries, profileDir, logger } = deps;
+	const wanted = registry?.trim() ?? "";
+	if (wanted === "") return;
+	if (profileDir !== void 0 && profileDir !== null && version !== void 0 && version.trim() !== "") try {
+		rememberPackageSource(profileDir, pkg, {
+			version,
+			registry: wanted
+		});
+	} catch (error) {
+		logger?.warn?.(`[dsh-workbench] 记 ${pkg} 这次的来源失败：${String(error)}`);
+	}
+	if (registries === void 0) return;
+	const scope = scopeOf$2(pkg);
+	if (scope === null) return;
+	const known = await manager.registries().catch(() => null);
+	if (known !== null && sameRegistry(known.resolved, wanted)) return;
+	try {
+		const added = registries.remember([{
+			scope,
+			registry: wanted
+		}]);
+		if (added.length > 0) logger?.info?.(`[dsh-workbench] 把 ${added.join("、")} 记进 profile 的 .npmrc（卸载只认 pnpm 的配置）`);
+	} catch (error) {
+		logger?.warn?.(`[dsh-workbench] 记这个 scope 的源失败：${String(error)}`);
+	}
+}
+async function retryAfterRegistryFix(deps, manager, pkg, change) {
+	const { registries, logger } = deps;
+	if (registries === void 0 || !registryFailure(change)) return change;
+	const known = await manager.registries().catch(() => null);
+	const missing = registries.sources().filter((entry) => !sameRegistry(entry.registry, known?.resolved ?? null));
+	if (missing.length === 0) return change;
+	let added;
+	try {
+		added = registries.remember(missing);
+	} catch (error) {
+		logger?.warn?.(`[dsh-workbench] 卸 ${pkg} 撞上源，但补配置失败：${String(error)}`);
+		return change;
+	}
+	if (added.length === 0) return change;
+	logger?.warn?.(`[dsh-workbench] 卸 ${pkg} 撞上源：补 ${added.join("、")} 后重试一次`);
+	return await manager.remove(pkg).catch(() => null) ?? change;
+}
+//#endregion
+//#region src/modules/panels/model/market-remove.ts
+var chain = Promise.resolve();
+function serialized(operation) {
+	const run = chain.then(operation, operation);
+	chain = run.then(() => void 0, () => void 0);
+	return run;
+}
+function forgetSource(options) {
+	const dir = options.profileDir;
+	if (dir === void 0 || dir === null) return;
+	try {
+		forgetPackageSource(dir, options.pkg);
+	} catch (error) {
+		options.logger?.warn?.(`[dsh-workbench] 清 ${options.pkg} 的来源记录失败：${String(error)}`);
+	}
+}
+function swapScopeFor(options) {
+	const dir = options.profileDir;
+	const notebook = options.registryFix.registries;
+	if (dir === void 0 || dir === null || notebook?.swapScope === void 0) return void 0;
+	const source = packageSourceOf(dir, options.pkg);
+	const scope = scopeOf$2(options.pkg);
+	if (source === void 0 || scope === null) return void 0;
+	try {
+		return notebook.swapScope(scope, source.registry);
+	} catch (error) {
+		options.logger?.warn?.(`[dsh-workbench] 临时把 ${scope} 指到 ${source.registry} 失败，卸载照走：${String(error)}`);
+		return;
+	}
+}
+async function removeOnce(options) {
+	const { manager, pkg, registryFix, logger } = options;
+	const first = await manager.remove(pkg);
+	if (first === null) throw new Error("插件管理器回的卸载结果看不懂。");
+	const settled = await retryAfterRegistryFix(registryFix, manager, pkg, first);
+	if (settled.application !== "failed" && settled.application !== "cancelled") {
+		forgetSource(options);
+		return settled;
+	}
+	const put = await manager.setEnabled?.(pkg, true);
+	logger?.warn?.(`[dsh-workbench] ${pkg} 没卸成（${settled.errorCode ?? settled.application}）—— 已把它那一行放回名单，别让一次失败留在"装着但关着"`);
+	return put ?? settled;
+}
+function removeDshBundle(options) {
+	return serialized(async () => {
+		const restore = swapScopeFor(options);
+		try {
+			return await removeOnce(options);
+		} finally {
+			try {
+				restore?.();
+			} catch (error) {
+				options.logger?.warn?.(`[dsh-workbench] 还原 .npmrc 失败：${String(error)}`);
+			}
+		}
+	});
+}
+//#endregion
 //#region src/modules/panels/model/market-dependency-update.ts
 async function updateDependencyRow(target, deps) {
 	if (target.conflict !== void 0) throw new Error(`这一行有两份来源，先统一声明再更新：${target.conflict}`);
@@ -12489,42 +12941,6 @@ function createEnvDropper(options) {
 	};
 }
 //#endregion
-//#region src/modules/panels/model/market-registry.ts
-async function rememberInstalledSource(deps, manager, pkg, registry) {
-	const { registries, logger } = deps;
-	if (registries === void 0 || registry === void 0) return;
-	const scope = scopeOf$2(pkg);
-	if (scope === null) return;
-	const known = await manager.registries().catch(() => null);
-	if (known !== null && sameRegistry(known.resolved, registry)) return;
-	try {
-		const added = registries.remember([{
-			scope,
-			registry
-		}]);
-		if (added.length > 0) logger?.info?.(`[dsh-workbench] 把 ${added.join("、")} 记进 profile 的 .npmrc（卸载只认 pnpm 的配置）`);
-	} catch (error) {
-		logger?.warn?.(`[dsh-workbench] 记这个 scope 的源失败：${String(error)}`);
-	}
-}
-async function retryAfterRegistryFix(deps, manager, pkg, change) {
-	const { registries, logger } = deps;
-	if (registries === void 0 || !registryFailure(change)) return change;
-	const known = await manager.registries().catch(() => null);
-	const missing = registries.sources().filter((entry) => !sameRegistry(entry.registry, known?.resolved ?? null));
-	if (missing.length === 0) return change;
-	let added;
-	try {
-		added = registries.remember(missing);
-	} catch (error) {
-		logger?.warn?.(`[dsh-workbench] 卸 ${pkg} 撞上源，但补配置失败：${String(error)}`);
-		return change;
-	}
-	if (added.length === 0) return change;
-	logger?.warn?.(`[dsh-workbench] 卸 ${pkg} 撞上源：补 ${added.join("、")} 后重试一次`);
-	return await manager.remove(pkg).catch(() => null) ?? change;
-}
-//#endregion
 //#region src/modules/panels/model/market-restart.ts
 function restartLogLine(change) {
 	if (change === null || change === void 0 || change.application !== "restart-required") return;
@@ -12534,7 +12950,7 @@ function restartLogLine(change) {
 //#endregion
 //#region src/modules/panels/model/market.ts
 function createMarketService(options) {
-	const { manifests, manifestsNow, probe, shell, logger, supply: supplyOption, onInstalled, onUninstalled, isReleased, bundles, installed, modules, workbench, registries, ledger, references, dshHome, profileName } = options;
+	const { manifests, manifestsNow, probe, shell, logger, supply: supplyOption, onInstalled, onUninstalled, isReleased, bundles, installed, modules, workbench, registries, profileDir, ledger, references, dshHome, profileName } = options;
 	const supply = supplyOption ?? requireSupply();
 	const command = options.command ?? "opencli";
 	const catalog = () => manifestsNow?.() ?? manifests;
@@ -12573,11 +12989,18 @@ function createMarketService(options) {
 	}
 	async function run(line, optional = false) {
 		if (shell === void 0) throw new Error("没有执行缝（shell 服务不可用），装 / 卸做不了。");
+		const blocked = installWriteProblem({
+			command: line,
+			fallback: isolatedRoot()
+		});
+		if (blocked !== void 0) throw installError(blocked);
 		const result = await runShell(shell, line, { timeoutMs: INSTALL_TIMEOUT_MS });
-		if (result.exitCode !== 0 && !optional) {
-			const tail = tailLines(result.stderr || result.stdout, 6);
-			throw new Error(`命令失败（退出码 ${result.exitCode}）${tail === "" ? "" : `：${tail}`}`);
-		}
+		if (result.exitCode !== 0 && !optional) throw installError(diagnoseInstallFailure({
+			command: line,
+			exitCode: result.exitCode,
+			output: result.stderr || result.stdout,
+			fallback: isolatedRoot()
+		}));
 	}
 	async function runAll(commands) {
 		for (const step of commands) await run(step.line, step.optional === true);
@@ -12662,26 +13085,24 @@ function createMarketService(options) {
 	}
 	const registryFix = {
 		...registries === void 0 ? {} : { registries },
+		...profileDir === void 0 || profileDir === null ? {} : { profileDir },
 		...logger === void 0 ? {} : { logger }
 	};
-	async function removeInstalledBundle(manager, pkg) {
-		const first = await manager.remove(pkg);
-		if (first === null) throw new Error("插件管理器回的卸载结果看不懂。");
-		const settled = await retryAfterRegistryFix(registryFix, manager, pkg, first);
-		if (settled.application !== "failed" && settled.application !== "cancelled") return settled;
-		const put = await manager.setEnabled?.(pkg, true);
-		logger?.warn?.(`[dsh-workbench] ${pkg} 没卸成（${settled.errorCode ?? settled.application}）—— 已把它那一行放回名单，别让一次失败留在"装着但关着"`);
-		return put ?? settled;
-	}
 	function routeDeps(manager) {
 		return {
 			manager,
 			command,
 			supply,
 			runAll,
-			rememberSource: (manager, pkg, registry) => rememberInstalledSource(registryFix, manager, pkg, registry),
+			rememberSource: (manager, pkg, registry, version) => rememberInstalledSource(registryFix, manager, pkg, registry, version),
 			supplyAfter,
-			remove: (pkg) => removeInstalledBundle(manager, pkg),
+			remove: (pkg) => removeDshBundle({
+				manager,
+				pkg,
+				profileDir,
+				registryFix,
+				...logger === void 0 ? {} : { logger }
+			}),
 			...shell === void 0 ? {} : { shell },
 			...installed === void 0 ? {} : { installed },
 			...ledger === void 0 ? {} : { ledger },
@@ -12716,7 +13137,7 @@ function createMarketService(options) {
 			return snapshot();
 		},
 		async install(unit) {
-			const absent = (await capabilityOf(unit, true)).needs.filter((state) => state.status === "missing" && (state.kind === "extension" || state.kind === "lib"));
+			const absent = (await capabilityOf(unit, true)).needs.filter((state) => state.status === "missing" && (state.kind === "extension" || state.kind === "lib" || state.kind === "bin"));
 			if (absent.length === 0) {
 				onInstalled?.(unit);
 				return entryOf(unit, true);
@@ -12728,6 +13149,8 @@ function createMarketService(options) {
 				}
 				if (state.command === void 0) throw new Error(`没有可执行的安装命令（${state.detail}）`);
 				await run(state.command);
+				ensureLibsOpencliPeer();
+				ensureLibsBinOnPath();
 			}
 			await probeSharing({
 				action: "install",
@@ -12813,7 +13236,13 @@ function createMarketService(options) {
 			const unit = module.kind === "module" ? module.unit : void 0;
 			const manifest = unit === void 0 ? void 0 : catalog().find((item) => item.id === unit);
 			const before = unit === void 0 ? void 0 : await capabilityOf(unit, true);
-			const change = await removeInstalledBundle(manager, pkg);
+			const change = await removeDshBundle({
+				manager,
+				pkg,
+				profileDir,
+				registryFix,
+				...logger === void 0 ? {} : { logger }
+			});
 			if (change.application !== "applied" || unit === void 0) return {
 				change,
 				keptFor: []
@@ -15342,6 +15771,7 @@ var OWNED = [{
 			modules: () => supply.profileModules(profileDir),
 			workbench: (pkg) => supply.readProfilePackage(profileDir, pkg),
 			registries: supply.createRegistryNotebook(profileDir),
+			profileDir,
 			ledger,
 			references: () => {
 				const gaps = supply.declarationGaps(profileDir);
@@ -16878,6 +17308,8 @@ async function apply(ctx, config) {
 	}
 	if (shell === void 0) ctx.logger?.warn?.("[dsh-workbench] 没有 shell 服务：需要执行缝的套件会降级");
 	else {
+		ensureLibsOpencliPeer();
+		if (ensureLibsBinOnPath() && ctx.logger?.info !== void 0) ctx.logger.info("[dsh-workbench] PATH 前插共用依赖的 bin 目录：装了的包，命令直接可用");
 		adapters.probe.registerPreflight({
 			routes,
 			ctx,