dsh-m 0.0.2 → 0.1.0

package/lib/core/dsh-cli.js

@@ -0,0 +1,212 @@
+/**
+ * Spawn `dsh plugin`。与 skillhub 同款关键约束：
+ * - 不经 agent 的沙箱 shell（它写不了 profile 目录）；
+ * - 在 dsh web 宿主进程内时，用 `node <自身 entry> plugin ...` 重入自身；
+ * - 目标串白名单校验；超时对进程组发 SIGTERM；只保留末 256KB 输出；
+ * - prepare 被拦 → 写 dangerouslyAllowAllBuilds 重试（明确报告，DESIGN.md §3 基线 4）。
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { installTimeoutMs, WEB_PROFILE, webProfileDir } from './env.js';
+const TARGET_RE = /^[A-Za-z0-9@:./_#+-]+$/;
+export function webProfileName() {
+    return WEB_PROFILE;
+}
+export function isSafePluginTarget(target) {
+    return TARGET_RE.test(target);
+}
+export function nodeExecutable(argv0 = process.argv0, execPath = process.execPath) {
+    if (argv0 !== undefined && argv0 !== '' && isAbsolute(argv0) && existsSync(argv0))
+        return argv0;
+    return execPath;
+}
+/** 宿主进程内时重入自身 entry（skillhub 同款）；否则退回 PATH 上的 dsh。 */
+export function dshArgv(input = {}) {
+    const argv = input.argv ?? process.argv;
+    const execArgv = input.execArgv ?? process.execArgv;
+    const execPath = input.execPath ?? process.execPath;
+    const argv0 = input.argv0 ?? process.argv0;
+    const platform = input.platform ?? process.platform;
+    const node = nodeExecutable(argv0, execPath);
+    const entry = argv[1];
+    if (entry !== undefined && /[\\/](?:bin\.(?:js|ts)|dsh)$/.test(entry)) {
+        const abs = resolve(entry);
+        return { file: node, args: [...execArgv, abs], cwd: dirname(abs), viaShell: false };
+    }
+    return { file: 'dsh', args: [], cwd: undefined, viaShell: platform === 'win32' };
+}
+/** pnpm 9 需要 -w 于 workspace 根；其他主版本在非 workspace 下拒绝 -w。 */
+export function pluginArgsFor(profileDirectory, pluginArgs) {
+    const args = [...pluginArgs];
+    if (args[0] !== 'add' && args[0] !== 'remove')
+        return args;
+    if (!existsSync(join(profileDirectory, 'pnpm-workspace.yaml')))
+        return args;
+    return [args[0], '-w', ...args.slice(1)];
+}
+export function isPrepareBlocked(text) {
+    return /needs to execute build scripts|allowBuilds|ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED|ERR_PNPM_IGNORED_BUILDS/i.test(text);
+}
+export function withDangerouslyAllowAllBuilds(yaml) {
+    if (/(?:^|\n)dangerouslyAllowAllBuilds:\s*true\s*(?:\n|$)/.test(yaml))
+        return yaml;
+    if (/(?:^|\n)dangerouslyAllowAllBuilds:\s*/m.test(yaml)) {
+        return yaml.replace(/^dangerouslyAllowAllBuilds:\s*.*$/m, 'dangerouslyAllowAllBuilds: true');
+    }
+    if (yaml.trim() === '')
+        return 'dangerouslyAllowAllBuilds: true\n';
+    return `${yaml.replace(/\s*$/u, '\n')}\ndangerouslyAllowAllBuilds: true\n`;
+}
+/** 基线 §17.4：放行构建脚本前必须能被明确报告（返回值带 usedAllowAllBuilds）。 */
+function writeDangerouslyAllowAllBuilds(profileDirectory) {
+    const file = join(profileDirectory, 'pnpm-workspace.yaml');
+    let yaml = '';
+    try {
+        yaml = readFileSync(file, 'utf8');
+    }
+    catch {
+        /* created below */
+    }
+    const next = withDangerouslyAllowAllBuilds(yaml);
+    if (next === yaml)
+        return false;
+    mkdirSync(profileDirectory, { recursive: true });
+    writeFileSync(file, next);
+    return true;
+}
+export function rewritePnpmError(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    if (isPrepareBlocked(text)) {
+        return new Error('该插件需要执行构建脚本（prepare），pnpm 默认拦截。dsh-m 已写入 profile 的 dangerouslyAllowAllBuilds 并重试；若仍失败请检查 web profile 是否可写。');
+    }
+    if (/ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF/.test(text)) {
+        return new Error('当前 profile 的 node_modules 由不同主版本的 pnpm 生成，安装前需要先重建依赖。');
+    }
+    return err instanceof Error ? err : new Error(text);
+}
+export async function runCommand(command, args, options) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env, CI: 'true' },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: options.viaShell === true,
+            detached: options.detached === true && process.platform !== 'win32',
+        });
+        let out = '';
+        let settled = false;
+        const finish = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+            if (err)
+                reject(err);
+            else
+                resolvePromise(out);
+        };
+        const killChild = () => {
+            if (process.platform !== 'win32' && child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                    return;
+                }
+                catch {
+                    /* fall through */
+                }
+            }
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                /* already gone */
+            }
+        };
+        const timer = setTimeout(() => {
+            killChild();
+            finish(new Error(`命令超时 ${options.timeoutMs}ms`));
+        }, options.timeoutMs);
+        const onAbort = () => {
+            killChild();
+            finish(new Error('命令已取消'));
+        };
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        child.stdout?.on('data', (chunk) => {
+            out = (out + chunk.toString()).slice(-256 * 1024);
+        });
+        child.stderr?.on('data', (chunk) => {
+            out = (out + chunk.toString()).slice(-256 * 1024);
+        });
+        child.on('error', (err) => finish(err));
+        child.on('close', (code) => {
+            if (code === 0)
+                finish();
+            else
+                finish(new Error(`命令失败 (exit ${code}): ${out.trim().slice(-800) || 'no output'}`));
+        });
+    });
+}
+export async function runDshPlugin(profile, pluginArgs, deps = {}) {
+    if (profile !== WEB_PROFILE)
+        throw new Error('仅支持 web profile');
+    const target = pluginArgs[pluginArgs.length - 1] ?? '';
+    if (!isSafePluginTarget(target))
+        throw new Error(`拒绝不安全的安装目标: ${target}`);
+    const argv = (deps.dshArgv ?? dshArgv)();
+    const prepared = pluginArgsFor(deps.profileDir ?? webProfileDir(), pluginArgs);
+    const run = deps.runCommand ?? runCommand;
+    return run(argv.file, [...argv.args, 'plugin', '--profile', profile, ...prepared], {
+        cwd: argv.cwd,
+        timeoutMs: deps.timeoutMs ?? installTimeoutMs(),
+        env: { CI: 'true' },
+        viaShell: argv.viaShell,
+        detached: process.platform !== 'win32',
+    });
+}
+/**
+ * 安装。返回 usedAllowAllBuilds 供 UI 明确报告「该插件执行了构建脚本」。
+ * source 形如：`pkg@1.2.3`（npm 精确锁定）或 `github:owner/repo#sha`（锁 SHA）。
+ */
+export async function addDshPlugin(source, deps = {}) {
+    const run = deps.runDshPlugin ?? runDshPlugin;
+    const allowAllBuilds = deps.allowAllBuilds ?? writeDangerouslyAllowAllBuilds;
+    const retryAfterPrepare = async () => {
+        const changed = allowAllBuilds(deps.profileDir ?? webProfileDir());
+        try {
+            return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: true };
+        }
+        catch (retryErr) {
+            throw rewritePnpmError(retryErr);
+        }
+    };
+    try {
+        return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: false };
+    }
+    catch (err) {
+        const text = err instanceof Error ? err.message : String(err);
+        if (text.includes('ERR_PNPM_PUBLIC_HOIST_PATTERN_DIFF')) {
+            await run(WEB_PROFILE, ['install', '--no-frozen-lockfile']);
+            try {
+                return { output: await run(WEB_PROFILE, ['add', source]), usedAllowAllBuilds: false };
+            }
+            catch (retryErr) {
+                if (!isPrepareBlocked(retryErr instanceof Error ? retryErr.message : String(retryErr))) {
+                    throw rewritePnpmError(retryErr);
+                }
+                return retryAfterPrepare();
+            }
+        }
+        if (!isPrepareBlocked(text))
+            throw rewritePnpmError(err);
+        return retryAfterPrepare();
+    }
+}
+/** 卸载（转发 pnpm remove；调用方须先做 live-disable）。 */
+export async function removeDshPlugin(pkg, deps = {}) {
+    if (!isSafePluginTarget(pkg))
+        throw new Error(`无效插件包名: ${pkg}`);
+    const run = deps.runDshPlugin ?? runDshPlugin;
+    return run(WEB_PROFILE, ['remove', pkg]);
+}

package/lib/core/env.js

@@ -0,0 +1,18 @@
+/** 路径与环境约定（DESIGN.md §11：profile 是唯一事实源） */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const WEB_PROFILE = 'web';
+export function dshHome() {
+    return process.env.DSH_HOME || join(homedir(), '.dsh');
+}
+export function webProfileDir() {
+    return join(dshHome(), 'profiles', WEB_PROFILE);
+}
+/** registry 缓存目录（可被 DSHM_CACHE_DIR 覆盖，便于测试） */
+export function cacheDir() {
+    return process.env.DSHM_CACHE_DIR || join(dshHome(), 'dshm', 'cache');
+}
+/** 安装类操作的超时（毫秒） */
+export function installTimeoutMs() {
+    return Number(process.env.DSHM_INSTALL_TIMEOUT_MS) || 15 * 60 * 1000;
+}

package/lib/core/httpx.js

@@ -0,0 +1,94 @@
+/**
+ * 安全基线 §17.1：仅 HTTPS（loopback http 例外）+ 响应大小上限 + 超时。
+ * skillhub 的缺口（无统一体积上限）在这里补齐。
+ */
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const MAX_DEFAULT = 2 * 1024 * 1024; // 2MB：registry/npm metadata 足够
+export function assertSafeUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new HttpError(400, `无效 URL: ${raw}`);
+    }
+    if (url.protocol === 'https:')
+        return url;
+    if (url.protocol === 'http:' && ['127.0.0.1', 'localhost', '::1'].includes(url.hostname)) {
+        return url; // 本地 registry 覆盖调试用（DESIGN.md §2.1）
+    }
+    throw new HttpError(400, `仅允许 HTTPS: ${raw}`);
+}
+async function readCapped(res, maxBytes) {
+    const declared = Number(res.headers.get('content-length') || 0);
+    if (declared > maxBytes)
+        throw new HttpError(502, `响应过大: ${declared} > ${maxBytes}`);
+    const reader = res.body?.getReader();
+    if (!reader)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            throw new HttpError(502, `响应超过上限 ${maxBytes} 字节`);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+export async function fetchJsonLimited(url, opts = {}) {
+    assertSafeUrl(url);
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 20_000),
+        headers: { accept: 'application/json', 'user-agent': 'dsh-m (personal marketplace)', ...opts.headers },
+        redirect: 'follow',
+    });
+    if (!res.ok)
+        throw new HttpError(res.status, `HTTP ${res.status}: ${url}`);
+    const buf = await readCapped(res, opts.maxBytes ?? MAX_DEFAULT);
+    try {
+        return JSON.parse(buf.toString('utf8'));
+    }
+    catch (err) {
+        throw new HttpError(502, `响应不是合法 JSON: ${url}`);
+    }
+}
+export async function fetchTextLimited(url, opts = {}) {
+    assertSafeUrl(url);
+    const res = await fetch(url, {
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 20_000),
+        headers: { 'user-agent': 'dsh-m (personal marketplace)', ...opts.headers },
+        redirect: 'follow',
+    });
+    if (!res.ok)
+        throw new HttpError(res.status, `HTTP ${res.status}: ${url}`);
+    const buf = await readCapped(res, opts.maxBytes ?? MAX_DEFAULT);
+    return buf.toString('utf8');
+}
+/** 可达性探测（icon/homepage 校验用）：2xx 即可达。 */
+export async function isReachable(url, timeoutMs = 8000) {
+    try {
+        assertSafeUrl(url);
+        const res = await fetch(url, {
+            method: 'HEAD',
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { 'user-agent': 'dsh-m (personal marketplace)' },
+            redirect: 'follow',
+        });
+        return res.ok || res.status === 405; // 有的站点拒绝 HEAD，视为可达
+    }
+    catch {
+        return false;
+    }
+}

package/lib/core/installed.js

@@ -0,0 +1,121 @@
+/**
+ * 已装插件识别（DESIGN.md §3）：profile 的 package.json 是唯一事实源，
+ * 不引入额外状态文件。移植自 skillhub installed-plugins.ts（去 README 暂缓）。
+ */
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { isSafePluginTarget, removeDshPlugin } from './dsh-cli.js';
+import { webProfileDir } from './env.js';
+const PKG_NAME_RE = /^(@[A-Za-z0-9-*~][A-Za-z0-9-*._~]*\/)?[A-Za-z0-9-._~]+$/;
+export function isSafePkgName(raw) {
+    const name = String(raw || '').trim();
+    if (!name || name.length > 214)
+        return false;
+    if (!PKG_NAME_RE.test(name))
+        return false;
+    return !name.split('/').some((part) => part === '' || part === '.' || part.startsWith('.') || part.startsWith('_') || part.includes('..'));
+}
+export function parseSpecSource(spec) {
+    const raw = String(spec || '').trim();
+    if (raw.startsWith('link:'))
+        return 'link';
+    if (raw.startsWith('file:'))
+        return 'file';
+    if (raw.startsWith('github:') || /^https:\/\/github\.com\//i.test(raw))
+        return 'github';
+    if (raw)
+        return 'npm';
+    return 'unknown';
+}
+/** 解析依赖的包目录：普通依赖限制在 profile node_modules 内；link:/file: 仅接受绝对路径。 */
+export function resolvePluginDir(profileDir, pkg, spec) {
+    if (!isSafePkgName(pkg))
+        return null;
+    const source = parseSpecSource(spec);
+    if (source === 'link' || source === 'file') {
+        const target = String(spec).slice(spec.indexOf(':') + 1).trim();
+        if (!target.startsWith('/') || target.includes('\0'))
+            return null;
+        return resolve(target);
+    }
+    return join(resolve(profileDir), 'node_modules', pkg);
+}
+export async function readPkgJson(dir) {
+    try {
+        const raw = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8'));
+        return raw && typeof raw === 'object' ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readProfileDeps(profileDir) {
+    try {
+        const raw = JSON.parse(await readFile(join(profileDir, 'package.json'), 'utf8'));
+        if (!raw || typeof raw !== 'object' || !raw.dependencies || typeof raw.dependencies !== 'object')
+            return {};
+        const out = {};
+        for (const [name, spec] of Object.entries(raw.dependencies)) {
+            if (typeof spec === 'string' && spec !== '')
+                out[name] = spec;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function sanitizePkgJson(raw, fallbackName) {
+    return {
+        name: typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim().slice(0, 200) : fallbackName,
+        version: typeof raw.version === 'string' ? raw.version.trim().slice(0, 64) : '',
+        description: typeof raw.description === 'string' ? raw.description.trim().slice(0, 500) : '',
+        homepage: typeof raw.homepage === 'string' && /^https?:\/\//i.test(raw.homepage) ? raw.homepage.slice(0, 300) : '',
+        path: '',
+    };
+}
+/** 枚举 web profile 已安装插件（只读）。 */
+export async function listInstalledPlugins(profileDir = webProfileDir()) {
+    const root = resolve(profileDir);
+    const deps = await readProfileDeps(root);
+    const items = [];
+    let others = 0;
+    for (const pkg of Object.keys(deps).sort()) {
+        const spec = deps[pkg];
+        const dir = resolvePluginDir(root, pkg, spec);
+        const raw = dir ? await readPkgJson(dir) : null;
+        if (!raw || !('dsh' in raw)) {
+            others += 1;
+            continue;
+        }
+        const info = sanitizePkgJson(raw, pkg);
+        items.push({
+            pkg,
+            name: info.name,
+            version: info.version,
+            description: info.description,
+            homepage: info.homepage,
+            spec,
+            source: parseSpecSource(spec),
+            dsh: true,
+            path: dir,
+        });
+    }
+    return { items, others, profileDir: root };
+}
+/** 从 web profile 卸载已安装的 dsh 插件。pkg 必须来自 profile 依赖（先 live-disable，见 market.ts）。 */
+export async function removeInstalledPlugin(pkg, profileDir = webProfileDir(), deps = {}) {
+    const key = String(pkg || '').trim();
+    if (!isSafePkgName(key) || !isSafePluginTarget(key))
+        throw new Error(`无效插件包名: ${pkg}`);
+    const root = resolve(profileDir);
+    const listed = await readProfileDeps(root);
+    if (!(key in listed))
+        throw new Error(`web profile 未安装该插件: ${key}`);
+    const dir = resolvePluginDir(root, key, listed[key]);
+    const raw = dir ? await readPkgJson(dir) : null;
+    if (!raw || !('dsh' in raw))
+        throw new Error(`不是 dsh 插件: ${key}`);
+    await removeDshPlugin(key, deps);
+    return { pkg: key };
+}

package/lib/core/live-plugin.js

@@ -0,0 +1,42 @@
+/**
+ * 卸载前先让 loader 里的 live fiber 下线，否则 client-modules 仍列出该包，
+ * 浏览器请求 /plugins/<name>/client.js 会 404。移植自 skillhub live-plugin.ts。
+ */
+let boundHost;
+export function bindLoaderHost(host) {
+    boundHost = host;
+}
+export function loaderHost() {
+    return boundHost;
+}
+export async function setLivePluginDisabled(pkg, disabled, host = boundHost) {
+    const name = String(pkg || '').trim();
+    const entries = host?.loader?.entries;
+    if (!name || typeof entries !== 'function')
+        return false;
+    let found = false;
+    for (const entry of entries.call(host.loader)) {
+        if (!entry || entry.options?.name !== name)
+            continue;
+        if (typeof entry.update !== 'function')
+            continue;
+        found = (await flipEntry(entry, disabled)) || found;
+    }
+    return found;
+}
+async function flipEntry(entry, disabled) {
+    const flag = disabled ? true : null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            await entry.update({ disabled: flag }, false, true);
+        }
+        catch {
+            return false;
+        }
+        const live = entry.fiber !== undefined;
+        if (live !== disabled)
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+    return true;
+}

package/lib/core/market.js

@@ -0,0 +1,193 @@
+/**
+ * 市场编排层：registry × profile × 最新版本 → 市场列表 / 已装列表 / outdated /
+ * 安装 / 卸载 / 升级。安装语义见 DESIGN.md §3（npm 精确锁定、GitHub 锁 SHA）。
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { addDshPlugin } from './dsh-cli.js';
+import { dshHome, webProfileDir } from './env.js';
+import { listInstalledPlugins, readProfileDeps, removeInstalledPlugin, } from './installed.js';
+import { setLivePluginDisabled } from './live-plugin.js';
+import { loadRegistry } from './registry.js';
+import { githubHeadSha, isNewerVersion, npmLatest } from './versions.js';
+function matchInstalledByEntry(entry, installed) {
+    return installed.find((it) => {
+        if (entry.npm && it.pkg === entry.npm)
+            return true;
+        if (entry.npm && it.name === entry.npm)
+            return true;
+        if (entry.github && it.source === 'github') {
+            const m = /^github:([^#]+)/.exec(it.spec);
+            if (m && m[1] === entry.github)
+                return true;
+        }
+        return false;
+    });
+}
+export async function listMarket(cfg = {}, opts = {}) {
+    const [loaded, installed] = await Promise.all([
+        loadRegistry(cfg, opts),
+        listInstalledPlugins(),
+    ]);
+    const timeoutMs = cfg.timeoutMs ?? 20_000;
+    const items = [];
+    for (const entry of loaded.registry.plugins) {
+        const inst = matchInstalledByEntry(entry, installed.items);
+        const item = {
+            ...entry,
+            installed: Boolean(inst),
+            outdated: false,
+        };
+        if (inst) {
+            item.installedPkg = inst.pkg;
+            item.installedVersion = inst.version;
+        }
+        try {
+            if (entry.source === 'npm' && entry.npm) {
+                const latest = await npmLatest(entry.npm, timeoutMs);
+                item.latestVersion = latest.version;
+                if (inst?.version && isNewerVersion(latest.version, inst.version))
+                    item.outdated = true;
+            }
+            else if (entry.github) {
+                const sha = await githubHeadSha(entry.github, timeoutMs);
+                item.latestSha = sha;
+                if (inst && !inst.spec.includes(sha))
+                    item.outdated = true;
+            }
+        }
+        catch (err) {
+            item.latestError = err instanceof Error ? err.message : String(err);
+        }
+        items.push(item);
+    }
+    return {
+        items,
+        registrySource: loaded.source,
+        registryFetchedAt: loaded.fetchedAt,
+        registryErrors: loaded.errors,
+    };
+}
+export async function listInstalledWithMeta(cfg = {}) {
+    const [{ items: installed, others, profileDir }, loaded] = await Promise.all([
+        listInstalledPlugins(),
+        loadRegistry(cfg),
+    ]);
+    const timeoutMs = cfg.timeoutMs ?? 20_000;
+    const items = [];
+    for (const it of installed) {
+        const entry = loaded.registry.plugins.find((e) => matchInstalledByEntry(e, [it]));
+        const item = { ...it, outdated: false };
+        if (entry)
+            item.registryId = entry.id;
+        try {
+            if (!entry && it.source === 'npm') {
+                const latest = await npmLatest(it.pkg, timeoutMs);
+                item.latestVersion = latest.version;
+                item.outdated = isNewerVersion(latest.version, it.version);
+            }
+            else if (entry?.source === 'npm' && entry.npm) {
+                const latest = await npmLatest(entry.npm, timeoutMs);
+                item.latestVersion = latest.version;
+                item.outdated = isNewerVersion(latest.version, it.version);
+            }
+            else if (it.source === 'github') {
+                const m = /^github:([^#]+)/.exec(it.spec);
+                if (m) {
+                    const sha = await githubHeadSha(m[1], timeoutMs);
+                    item.outdated = !it.spec.includes(sha);
+                }
+            }
+        }
+        catch {
+            /* 查询失败不阻塞列表，outdated 维持 false */
+        }
+        items.push(item);
+    }
+    return { items, others, profileDir };
+}
+/** 从 registry 收录条目安装（npm → 精确锁定最新版；github → 锁 HEAD SHA）。 */
+export async function installFromRegistry(id, cfg = {}, opts = {}) {
+    const { registry } = await loadRegistry(cfg);
+    const entry = registry.plugins.find((e) => e.id === id);
+    if (!entry)
+        throw new Error(`registry 中没有该条目: ${id}`);
+    return installEntry(entry, cfg, opts);
+}
+export async function installEntry(entry, cfg = {}, opts = {}) {
+    const timeoutMs = cfg.timeoutMs ?? 20_000;
+    if (entry.source === 'npm' && entry.npm) {
+        const version = opts.version && /^\d+\.\d+\.\d+/.test(opts.version) ? opts.version : (await npmLatest(entry.npm, timeoutMs)).version;
+        const spec = `${entry.npm}@${version}`;
+        const res = await addDshPlugin(spec);
+        // 安装后校验：落盘版本必须与意图一致（tarball 完整性由 pnpm 按 lock integrity 保证）
+        const deps = await readProfileDeps(webProfileDir());
+        const specInProfile = deps[entry.npm];
+        if (specInProfile === undefined)
+            throw new Error(`安装后未在 profile 依赖中找到 ${entry.npm}`);
+        return {
+            id: entry.id,
+            pkg: entry.npm,
+            spec,
+            version,
+            usedAllowAllBuilds: res.usedAllowAllBuilds,
+            needsRestart: true,
+            output: res.output.slice(-800),
+        };
+    }
+    if (entry.github) {
+        const sha = await githubHeadSha(entry.github, timeoutMs);
+        const spec = `github:${entry.github}#${sha}`;
+        const res = await addDshPlugin(spec);
+        const deps = await readProfileDeps(webProfileDir());
+        const pkgKey = Object.keys(deps).find((k) => deps[k] === spec || deps[k].startsWith(`github:${entry.github}#`));
+        if (!pkgKey)
+            throw new Error(`安装后未在 profile 依赖中找到 ${entry.github}`);
+        return {
+            id: entry.id,
+            pkg: pkgKey,
+            spec,
+            sha,
+            usedAllowAllBuilds: res.usedAllowAllBuilds,
+            needsRestart: true,
+            output: res.output.slice(-800),
+        };
+    }
+    throw new Error(`条目 ${entry.id} 缺少可安装来源`);
+}
+/** 卸载：live-disable → pnpm remove → 报告疑似残留（DESIGN.md §3：删包不删数据）。 */
+export async function uninstallPlugin(pkg, _cfg = {}) {
+    const liveDisabled = await setLivePluginDisabled(pkg, true);
+    await removeInstalledPlugin(pkg);
+    return { pkg, liveDisabled, needsRestart: true, leftovers: leftoverCandidates(pkg) };
+}
+/** 升级 = 按最新重新安装（npm 拉最新精确版；github 重新锁 HEAD）。 */
+export async function upgradePlugin(pkg, cfg = {}) {
+    const { registry } = await loadRegistry(cfg);
+    const { items: installed } = await listInstalledPlugins();
+    const target = installed.find((it) => it.pkg === pkg);
+    if (!target)
+        throw new Error(`web profile 未安装该插件: ${pkg}`);
+    const entry = registry.plugins.find((e) => matchInstalledByEntry(e, [target]));
+    if (!entry)
+        throw new Error(`「${pkg}」不是经 dsh-m 收录的插件；直接升级请用 dsh plugin update 或先在 registry 收录它`);
+    const result = await installEntry(entry, cfg);
+    return { ...result, fromVersion: target.version };
+}
+/** 变更互斥：安装/卸载/升级串行执行（skillhub install-lock 同款思路）。 */
+let mutationTail = Promise.resolve();
+export function withMutationLock(task) {
+    const next = mutationTail.then(task, task);
+    mutationTail = next.catch(() => undefined);
+    return next;
+}
+/** 疑似残留路径（存在才列出）：删包不删数据，只报告。 */
+export function leftoverCandidates(pkg) {
+    const home = dshHome();
+    const candidates = [
+        join(home, `${pkg}.json`),
+        join(home, pkg),
+        join(home, `${pkg.replace(/^@[^/]+\//, '')}.json`),
+    ];
+    return candidates.filter((p) => existsSync(p));
+}