dsh-plugin 0.1.0 → 1.0.0

package/lib/services/preflight.js

@@ -0,0 +1,94 @@
+/**
+ * 安装前预检：对 `github:` 源的插件，检查其分发（codeload tarball）里是否
+ * 真的包含 package.json 声明的入口文件（main / exports["."].default）。
+ * git 分发常不提交构建产物（lib/ 等），这类残缺包装完会让宿主重启加载插件树时
+ * ERR_MODULE_NOT_FOUND 直接崩溃 —— 预检在动手安装前就把它们拦下，避免白装一次。
+ * npm 包信任 registry 的完整性，直接放行；任何无法预检的情况也放行，交给装后
+ * 校验（verifyInstalledEntry）兜底，保证预检自身失败不会卡死安装流程。
+ */
+import { execFile } from 'node:child_process';
+import { createWriteStream, mkdtempSync, rmSync } from 'node:fs';
+import { get } from 'node:https';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function preflightTarget(target) {
+    const m = /^github:([^/]+)\/([^/]+)$/.exec(target);
+    if (m === null)
+        return { ok: true, missing: null };
+    const [, owner, repo] = m;
+    let commit = '';
+    try {
+        const { stdout } = await execFileAsync('git', ['ls-remote', `https://github.com/${owner}/${repo}.git`, 'HEAD']);
+        commit = stdout.split(/\s+/)[0] ?? '';
+    }
+    catch {
+        return { ok: true, missing: null };
+    }
+    if (!commit)
+        return { ok: true, missing: null };
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-preflight-'));
+    try {
+        const tar = join(dir, 'pkg.tar.gz');
+        await download(`https://codeload.github.com/${owner}/${repo}/tar.gz/${commit}`, tar);
+        const meta = await readTarJson(tar, 'package/package.json');
+        if (meta === null)
+            return { ok: true, missing: null };
+        const dot = meta.exports?.['.'];
+        const resolved = typeof dot === 'string'
+            ? dot
+            : dot !== null && typeof dot === 'object'
+                ? dot.default
+                : undefined;
+        const entry = typeof resolved === 'string' ? resolved : typeof meta.main === 'string' ? meta.main : 'index.js';
+        const inTar = await hasTarEntry(tar, `package/${entry}`);
+        return { ok: inTar, missing: inTar ? null : entry };
+    }
+    catch {
+        return { ok: true, missing: null };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+function download(url, dest) {
+    return new Promise((resolve, reject) => {
+        get(url, (res) => {
+            if (res.statusCode === 301 || res.statusCode === 302 || res.statusCode === 303) {
+                res.resume();
+                if (res.headers.location) {
+                    void download(res.headers.location, dest).then(resolve, reject);
+                    return;
+                }
+            }
+            if (res.statusCode !== 200) {
+                res.resume();
+                reject(new Error(`download failed: HTTP ${res.statusCode ?? '?'}`));
+                return;
+            }
+            void pipeline(res, createWriteStream(dest)).then(resolve, reject);
+        }).on('error', reject);
+    });
+}
+/** 从 tarball 提取并解析一个 JSON 文件；文件不存在或解析失败返回 null。 */
+async function readTarJson(tar, entry) {
+    try {
+        const { stdout } = await execFileAsync('tar', ['-xzOf', tar, entry], { maxBuffer: 4 * 1024 * 1024 });
+        return JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/** 检查 tarball 内是否存在指定 entry。 */
+async function hasTarEntry(tar, entry) {
+    try {
+        const { stdout } = await execFileAsync('tar', ['-tzf', tar, entry], { maxBuffer: 1024 * 1024 });
+        return stdout.split(/\r?\n/).some((line) => line === entry);
+    }
+    catch {
+        return false;
+    }
+}

package/lib/services/profile.js

@@ -0,0 +1,88 @@
+/**
+ * 宿主 profile 与目标校验工具：解析当前 profile、目录定位、安装目标语法校验，
+ * 以及 pnpm allowBuilds 白名单的写入（失败恢复路径）。
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { PACKAGE_RE, REPO_RE } from './install-types.js';
+/** Resolve the active profile from the booted CLI args, falling back to `web`. */
+export function readProfileArg(fallback = 'web') {
+    const index = process.argv.indexOf('--profile');
+    const candidate = index >= 0 ? process.argv[index + 1] : undefined;
+    return candidate !== undefined && !candidate.startsWith('-') ? candidate : fallback;
+}
+/** Resolve a profile directory (`DSH_HOME` or `~/.dsh`). */
+export function profileDirectory(profile) {
+    return join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', profile);
+}
+/** Build a safe `github:<owner>/<repo>` target, or null when the repo is unsafe. */
+export function githubTarget(repo) {
+    if (typeof repo !== 'string' || !REPO_RE.test(repo))
+        return null;
+    return `github:${repo}`;
+}
+/** Validate an npm package name (uninstall target grammar). */
+export function validPackageName(name) {
+    return typeof name === 'string' && PACKAGE_RE.test(name);
+}
+/**
+ * The exact `allowBuilds` key pnpm printed in its
+ * `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` hint. For `github:` installs pnpm
+ * matches against `name@<resolved fetch URL>` — the URL it actually fetches,
+ * e.g. `https://codeload.github.com/<owner>/<repo>/tar.gz/<commit>` — not the
+ * `git+ssh://`/branch spec. A bare name or a `git+` spec does not match, so
+ * the only reliable key is the one pnpm prints verbatim. Null when absent.
+ */
+export function parseAllowBuildsKey(output) {
+    const m = /^[ \t]*(\S+@\S+):[ \t]*true[ \t]*$/m.exec(output);
+    return m === null ? null : m[1].trim();
+}
+/** Quote a YAML block-mapping key when a plain scalar would be invalid. */
+function quoteYamlKey(key) {
+    if (/^[-?:,[\]{}#&*!|>'"%@`]/.test(key) || /:(\s|$)/.test(key)) {
+        return `'${key.replace(/'/g, "''")}'`;
+    }
+    return key;
+}
+/**
+ * Add one `allowBuilds` entry to the profile's pnpm-workspace.yaml, merging
+ * with existing entries and leaving the rest of the yaml intact. Broken
+ * placeholder entries (pnpm's failed-install bug writes a literal
+ * `set this to true or false` value) are dropped on rewrite.
+ */
+export function addAllowBuildsKey(profile, key) {
+    const file = join(profileDirectory(profile), 'pnpm-workspace.yaml');
+    let yaml = '';
+    try {
+        yaml = readFileSync(file, 'utf8');
+    }
+    catch { /* created below */ }
+    const eol = /\r\n/.test(yaml) ? '\r\n' : '\n';
+    const blockRe = /allowBuilds:[ \t]*\r?\n((?:[ \t]+[^\r\n]*\r?\n?)*)/g;
+    const map = new Map();
+    for (const match of Array.from(yaml.matchAll(blockRe))) {
+        for (const line of match[1].split(/\r?\n/)) {
+            const m = /^[ \t]+(\S.*?)\s*:\s*(true|false)?\s*$/.exec(line);
+            if (m === null || m[1] === '')
+                continue;
+            let k = m[1];
+            if (k.length >= 2 && ((k[0] === "'" && k[k.length - 1] === "'") || (k[0] === '"' && k[k.length - 1] === '"'))) {
+                k = k.slice(1, -1);
+            }
+            map.set(k, m[2] ?? 'true');
+        }
+    }
+    map.set(key, 'true');
+    const block = Array.from(map).map(([k, v]) => `  ${quoteYamlKey(k)}: ${v}`).join(eol);
+    const blockText = `allowBuilds:${eol}${block}${eol}`;
+    let next;
+    if (/allowBuilds:[ \t]*\r?\n/.test(yaml)) {
+        let seen = 0;
+        next = yaml.replace(blockRe, () => (seen++ === 0 ? blockText : ''));
+    }
+    else {
+        next = `${yaml.replace(/\r?\n?$/, eol)}${blockText}`;
+    }
+    writeFileSync(file, next);
+}

package/lib/services/progress.js

@@ -0,0 +1,50 @@
+/**
+ * Pure progress-estimation helpers shared by the install runner.
+ *
+ * The dsh CLI wraps pnpm, which refreshes its `Progress: …` line in place
+ * with carriage returns, so raw output arrives as a stream of partial
+ * fragments. These helpers normalize one fragment into a clean terminal
+ * line and map it onto a 0-100 estimate; keeping them free of I/O makes the
+ * estimation logic directly unit-testable (see tests/progress.test.ts).
+ */
+/** Strip the `[out]` / `[err]` source prefix and ANSI escape sequences. */
+export function cleanLine(raw) {
+    return raw.replace(/^\[(?:err|out)\]\s*/, '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').trim();
+}
+/**
+ * Estimate 0-100 progress from one CLI output line. pnpm emits
+ * `Progress: resolved N, reused X, downloaded Y, added Z` during the fetch
+ * phase; resolution/install phase lines bump the estimate towards done.
+ */
+export function estimateProgress(line) {
+    const progress = line.match(/Progress:\s*(.+)/);
+    if (progress) {
+        let resolved = 0;
+        let handled = 0;
+        for (const part of progress[1].split(',')) {
+            // pnpm emits `label count` tokens, e.g. `resolved 100, reused 40`
+            const [label, raw] = part.trim().split(/\s+/);
+            const value = Number(raw);
+            if (label === 'resolved')
+                resolved = value;
+            else if (label === 'reused' || label === 'downloaded' || label === 'added' || label === 'imported') {
+                handled += value;
+            }
+        }
+        // pnpm 的 resolved 是"解析出的包数"，reused/downloaded/added 是"已处理的包数"，
+        // 两者几乎总是相等，比值没有进度区分度（一出现就贴满 100%）。
+        // fetch 阶段只占安装总时长的一小部分（git 依赖之后还要 clone + 跑 prepare 构建），
+        // 因此按已处理量在低区间（8-30）缓步推进，把中段留给真正的安装/构建阶段。
+        if (resolved > 0 && handled > 0) {
+            return Math.min(30, 8 + Math.round((handled / resolved) * 20));
+        }
+        return resolved > 0 ? 8 : 0;
+    }
+    if (/^dependencies:|^Packages:/i.test(line))
+        return 85;
+    if (/^Running\b|prepare|build scripts/i.test(line))
+        return 60;
+    if (/^Done in\b/i.test(line))
+        return 96;
+    return 0;
+}

package/lib/services/task-queue.js

@@ -0,0 +1,417 @@
+/**
+ * 后台安装/卸载任务队列：内存任务注册表 + FIFO 串行 worker + 子进程生命周期管理。
+ * 每个任务一次 `dsh plugin --profile <profile> <action> <target>` 子进程，
+ * 输出流式收集到任务上；卸载成功时尝试从运行中 loader 即时停用（见 loader.ts）。
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.js';
+import { cleanLine, estimateProgress } from './progress.js';
+import { removeLoadedEntry } from './loader.js';
+import { addPendingRestart, clearPendingRestart } from './pending-restart.js';
+import { addAllowBuildsKey, parseAllowBuildsKey, profileDirectory } from './profile.js';
+/** In-memory task registry, keyed by task id. */
+const tasks = new Map();
+let nextTaskId = 1;
+/** Pending tasks awaiting their turn (FIFO). The queue worker runs at most one mutation at a time. */
+const queue = [];
+/** Child processes of currently running tasks (for cancel). */
+const runningChildren = new Map();
+/** Snapshot of a task (keeps the live object untouched by consumers). */
+export function getTask(id) {
+    const task = tasks.get(id);
+    if (!task)
+        return undefined;
+    return { ...task, lines: task.lines.slice(0, MAX_TASK_LINES) };
+}
+/** All non-terminal tasks in queue order (running first, then pending). Lets the client resume a queue after a page reload. */
+export function activeTask() {
+    const found = [];
+    for (const item of queue) {
+        const task = item.task;
+        if (task.status === 'pending') {
+            found.push({ id: task.id, target: task.target, action: task.action, status: 'pending', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES) });
+        }
+    }
+    tasks.forEach((task) => {
+        if (task.status === 'running') {
+            found.unshift({ id: task.id, target: task.target, action: task.action, status: 'running', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES) });
+        }
+    });
+    return found;
+}
+/**
+ * True while a mutation child process is still alive. The concurrent slot is
+ * keyed off the live child set rather than task.status: cancelling a running
+ * task flips its status immediately, but the child may still be shutting down
+ * (the close event lands later) — the slot must stay held until then, otherwise
+ * a new task would start while the old pnpm still runs in the same profile dir.
+ */
+export function hasRunningTask() {
+    return runningChildren.size > 0;
+}
+/** Whether the target already has a non-terminal task in the queue (install/uninstall dedupe). */
+export function hasQueuedTarget(target) {
+    return queue.some((it) => it.task.target === target && (it.task.status === 'pending' || it.task.status === 'running'));
+}
+/**
+ * Cancel a queued or running task.
+ * - pending: removed from the queue immediately (never spawned).
+ * - running: kills the child process; the queue worker then picks the next one.
+ * Returns false when the task is unknown or already finished.
+ */
+export function cancelTask(id) {
+    const task = tasks.get(id);
+    if (!task)
+        return false;
+    if (task.status === 'pending') {
+        const index = queue.findIndex((it) => it.task === task);
+        if (index >= 0)
+            queue.splice(index, 1);
+        task.status = 'cancelled';
+        pushLine(task, '[cancelled]');
+        return true;
+    }
+    if (task.status === 'running') {
+        task.status = 'cancelled';
+        pushLine(task, '[cancelled]');
+        const child = runningChildren.get(id);
+        if (child)
+            stopChild(child);
+        return true;
+    }
+    return false;
+}
+function pushLine(task, line) {
+    const text = cleanLine(line);
+    // pnpm 的 `Progress:` 行用 \r 原地刷新同一行：内容一变化就追加，
+    // 日志像终端一样实时滚动（downloaded 0→1→2…）；内容与最新一条完全相同则跳过，
+    // 避免同一进度反复刷新时无意义的重复堆积
+    if (text !== task.lines[0]) {
+        task.lines.unshift(text);
+        if (task.lines.length > MAX_TASK_LINES)
+            task.lines.length = MAX_TASK_LINES;
+    }
+    const estimate = estimateProgress(text);
+    if (estimate > 0) {
+        task.progress = Math.max(task.progress, estimate);
+    }
+    else if (task.status === 'running' && task.progress < 85) {
+        // 兜底：行无解析格式也随输出量推进，保证进度条始终在动（不会卡在 0）
+        task.progress = Math.max(task.progress, 6 + Math.min(79, task.lines.length * 2));
+    }
+}
+function cliInvocation() {
+    const entry = process.argv[1];
+    if (entry !== undefined && /[\\/](?:bin\.(?:js|ts)|dsh)$/.test(entry)) {
+        const absoluteEntry = resolve(entry);
+        return {
+            file: process.execPath,
+            prefixArgs: [...process.execArgv, absoluteEntry],
+            cwd: dirname(absoluteEntry),
+            useShell: false,
+        };
+    }
+    return { file: 'dsh', prefixArgs: [], cwd: process.cwd(), useShell: process.platform === 'win32' };
+}
+function stopChild(child) {
+    if (process.platform === 'win32' && child.pid !== undefined) {
+        const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore' });
+        killer.once('error', () => child.kill('SIGKILL'));
+        return;
+    }
+    if (child.pid !== undefined) {
+        // POSIX：dsh 内部会 fork pnpm，只杀 dsh 会让 pnpm 变成孤儿继续攥着管道，
+        // close 事件永不到来、队列卡死。detached 让子进程成为进程组组长，
+        // 对整组 SIGKILL 才能把 dsh + pnpm（及后代）一起清掉，close 随即触发。
+        try {
+            process.kill(-child.pid, 'SIGKILL');
+            return;
+        }
+        catch { /* 进程已退出：忽略 */ }
+    }
+    child.kill('SIGKILL');
+}
+/**
+ * Enqueue a plugin mutation and return its task. Tasks run strictly serially:
+ * the queue worker starts the next one only after the previous finishes.
+ * Progress is visible through `getTask(id)` / `activeTask()` until done.
+ */
+export function startPluginMutation(options) {
+    const task = { id: nextTaskId, target: options.target, action: options.action, status: 'pending', timedOut: false, exitCode: null, progress: 0, lines: [] };
+    nextTaskId = nextTaskId >= Number.MAX_SAFE_INTEGER ? 1 : nextTaskId + 1;
+    tasks.set(task.id, task);
+    if (tasks.size > MAX_TASKS) {
+        let removed = false;
+        tasks.forEach((candidate, id) => {
+            if (!removed && candidate.status !== 'running' && candidate.status !== 'pending') {
+                tasks.delete(id);
+                removed = true;
+            }
+        });
+    }
+    queue.push({ task, options: { ...options } });
+    pumpQueue();
+    return task;
+}
+/** Queue worker: at most one mutation runs at a time; pick the next pending task when the slot frees up. */
+function pumpQueue() {
+    if (hasRunningTask())
+        return;
+    const item = queue.find((it) => it.task.status === 'pending');
+    if (!item)
+        return;
+    const { task, options } = item;
+    task.status = 'running';
+    void runPluginMutation({ ...options, task }).finally(() => {
+        runningChildren.delete(task.id);
+        // 已终态的任务移出队列：既防 queue 数组无限增长（内存泄漏），也让下一轮 pump 干净
+        const idx = queue.findIndex((it) => it.task === task);
+        if (idx >= 0)
+            queue.splice(idx, 1);
+        pumpQueue();
+    });
+}
+/**
+ * Run one `dsh plugin --profile <profile> <action> <target>` spawn, stream
+ * its output onto the tracked task and resolve with the captured result.
+ * Never rejects; failures surface through the result / task state.
+ */
+function spawnMutation(options) {
+    const { action, profile, target, timeoutMs = 5 * 60 * 1000, env, task, displayTarget, uninstallLoader } = options;
+    const invocation = cliInvocation();
+    const args = [...invocation.prefixArgs, 'plugin', '--profile', profile, action, target];
+    return new Promise((resolvePromise) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        let child;
+        try {
+            child = spawn(invocation.file, args, {
+                cwd: invocation.cwd,
+                env,
+                shell: invocation.useShell,
+                // detached 使子进程成为独立进程组组长：取消时能整组清理（见 stopChild），
+                // 且宿主进程崩溃后安装任务不会被连带误杀
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            if (task) {
+                task.status = 'failed';
+                task.exitCode = null;
+                pushLine(task, `[error] ${error instanceof Error ? error.message : String(error)}`);
+            }
+            resolvePromise({
+                exitCode: null,
+                timedOut: false,
+                error: error instanceof Error ? error.message : String(error),
+                stdout,
+                stderr,
+            });
+            return;
+        }
+        if (task)
+            runningChildren.set(task.id, child);
+        // 兜底定时器句柄：整段超时 / exit 后 close 宽限 / 强制收尾
+        let timer;
+        let progressTimer;
+        let exitWatch;
+        let forceSettle;
+        // 唯一收尾入口：close / error / 兜底超时 三者只放行一次，
+        // 保证 runPluginMutation 必然 resolve、队列 worker 必然继续推进
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (progressTimer !== undefined)
+                clearInterval(progressTimer);
+            if (exitWatch !== undefined)
+                clearTimeout(exitWatch);
+            if (forceSettle !== undefined)
+                clearTimeout(forceSettle);
+            if (task)
+                runningChildren.delete(task.id);
+            resolvePromise(result);
+        };
+        timer = setTimeout(() => {
+            timedOut = true;
+            stopChild(child);
+        }, timeoutMs);
+        // 时间兜底：即使 CLI 静默不吐进度行，进度条也单调推进，不会卡在 0
+        progressTimer = setInterval(() => {
+            if (task && task.status === 'running' && task.progress < 85)
+                task.progress += 1;
+        }, 500);
+        const collect = (kind, chunk) => {
+            const text = chunk.toString();
+            if (kind === 'stdout')
+                stdout = (stdout + text).slice(-CAPTURE_LIMIT_BYTES);
+            else
+                stderr = (stderr + text).slice(-CAPTURE_LIMIT_BYTES);
+            if (task) {
+                // 原生透传 pnpm 输出：stdout/stderr 原样入日志，不做格式化，保证报错信息完整可见
+                for (const line of text.split(/\r?\n|\r/)) {
+                    if (line.trim() !== '')
+                        pushLine(task, line.trimEnd());
+                }
+            }
+        };
+        child.stdout?.on('data', (chunk) => collect('stdout', chunk));
+        child.stderr?.on('data', (chunk) => collect('stderr', chunk));
+        child.once('exit', () => {
+            // dsh 内部会 fork pnpm：pnpm 退出后仍攥着 stdout/stderr 管道时，
+            // close 事件永不到来（历史队列卡死根因——取消路径曾因此卡死，用整组 SIGKILL 解决；
+            // 自然失败路径没有兜底）。exit 后给 close 一段宽限，未按时触发则整组清理强制结束，
+            // 保证任务必然进入终态、后续排队任务自动启动。
+            exitWatch = setTimeout(() => {
+                if (settled)
+                    return;
+                if (task && task.status !== 'cancelled')
+                    pushLine(task, '[stale pipe] force closing child');
+                stopChild(child);
+                // 清理后极端情况下 close 仍未触发（kill 失败）：再兜底强制收尾
+                forceSettle = setTimeout(() => {
+                    if (settled)
+                        return;
+                    if (task && task.status !== 'cancelled') {
+                        task.status = 'failed';
+                        task.exitCode = null;
+                        task.timedOut = true;
+                        pushLine(task, '[timed out]');
+                    }
+                    settle({ exitCode: null, timedOut: true, error: 'child failed to close', stdout, stderr });
+                }, 5_000);
+            }, 3_000);
+        });
+        child.once('error', (error) => {
+            if (task && task.status !== 'cancelled') {
+                task.status = 'failed';
+                task.exitCode = null;
+                pushLine(task, `[error] ${error.message}`);
+            }
+            settle({ exitCode: null, timedOut: false, error: error.message, stdout, stderr });
+        });
+        child.once('close', async (code) => {
+            try {
+                if (task) {
+                    task.exitCode = code;
+                    task.timedOut = timedOut;
+                    if (task.status !== 'cancelled') {
+                        task.status = timedOut || code !== 0 ? 'failed' : 'done';
+                        if (task.status === 'done') {
+                            task.progress = 100;
+                            if (action === 'remove' && uninstallLoader) {
+                                // 卸载成功 → 主动从运行中 loader 移除该包条目，立即生效、无需重启；
+                                // 移除失败（或从未加载过但 loader 不可用）才登记「待重启清理」兜底
+                                const removed = await removeLoadedEntry(uninstallLoader, target);
+                                if (removed)
+                                    clearPendingRestart(displayTarget ?? target);
+                                else
+                                    addPendingRestart(displayTarget ?? target, 'uninstall');
+                            }
+                            else {
+                                // 安装成功（或卸载但无 loader 引用）→ 登记待重启：
+                                // 插件要宿主重启才会挂载/卸载干净，重启前一直提醒；展示目标用 displayTarget（owner/repo）
+                                addPendingRestart(displayTarget ?? target, action === 'add' ? 'install' : 'uninstall');
+                            }
+                        }
+                        pushLine(task, timedOut ? '[timed out]' : `[exit ${code ?? '?'}]`);
+                    }
+                }
+            }
+            finally {
+                settle({ exitCode: code, timedOut, error: null, stdout, stderr });
+            }
+        });
+    });
+}
+/**
+ * 安装后校验已装包的入口文件（package.json 的 main / exports["."].default）是否真实存在。
+ * git: 分发常不提交构建产物（lib/ 等），pnpm 装完没有报错，但宿主重启加载插件树时会
+ * ERR_MODULE_NOT_FOUND 直接崩溃、网页打不开 —— 这里在登记「待重启」前就把这类残缺包拦下。
+ * 返回 { name, missing }：name 为空表示无法定位目标包（跳过校验）；missing 为缺失的入口路径。
+ */
+export function verifyInstalledEntry(profile, target) {
+    let profilePkg = null;
+    try {
+        profilePkg = JSON.parse(readFileSync(join(profileDirectory(profile), 'package.json'), 'utf8'));
+    }
+    catch {
+        return { name: null, missing: null };
+    }
+    const deps = (profilePkg?.dependencies ?? {});
+    // target 自身是依赖名（npm 包），或通过 github: specifier 反查依赖名
+    const name = deps[target] !== undefined ? target : Object.keys(deps).find((k) => deps[k] === target);
+    if (!name)
+        return { name: null, missing: null };
+    const pkgDir = join(profileDirectory(profile), 'node_modules', name);
+    let entry = null;
+    try {
+        const meta = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+        const dot = meta.exports?.['.'];
+        const resolved = typeof dot === 'string' ? dot
+            : dot !== null && typeof dot === 'object'
+                ? dot.default
+                : undefined;
+        entry = typeof resolved === 'string' ? resolved : typeof meta.main === 'string' ? meta.main : 'index.js';
+    }
+    catch {
+        return { name, missing: null };
+    }
+    try {
+        return { name, missing: statSync(join(pkgDir, entry)).isFile() ? null : entry };
+    }
+    catch {
+        return { name, missing: entry };
+    }
+}
+/**
+ * Run a plugin mutation with one recovery path: when `add` fails because a
+ * git-hosted package's `prepare` script is blocked by pnpm's allowBuilds
+ * gate (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`), read the exact allowlist
+ * key pnpm printed, write it into the profile's pnpm-workspace.yaml, and
+ * retry once. Other failures fall through to the single-spawn result.
+ */
+export async function runPluginMutation(options) {
+    const result = await spawnMutation(options);
+    if (options.action === 'add' && result.exitCode !== 0 && !result.timedOut) {
+        const output = `${result.stderr}\n${result.stdout}`;
+        if (output.includes('ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED')) {
+            const key = parseAllowBuildsKey(output);
+            if (key !== null) {
+                if (options.task) {
+                    // First attempt already marked the task failed; reset it so the
+                    // retry streams progress as a running task again.
+                    options.task.status = 'running';
+                    options.task.exitCode = null;
+                    pushLine(options.task, `[allow build] ${key}`);
+                }
+                addAllowBuildsKey(options.profile, key);
+                return spawnMutation(options);
+            }
+        }
+    }
+    // pnpm 安装本身成功，但目标包入口文件缺失（git 分发缺构建产物）→ 判为失败：
+    // 撤销刚登记的待重启，避免用户重启时宿主加载残缺包直接崩溃
+    if (options.action === 'add' && result.exitCode === 0 && !result.timedOut) {
+        const verified = verifyInstalledEntry(options.profile, options.target);
+        if (verified.name !== null && verified.missing !== null) {
+            clearPendingRestart(options.displayTarget ?? options.target);
+            const detail = `[packaging] ${verified.name}: entry file missing: ${verified.missing} (git distribution lacks build output — install the npm version or report to the author)`;
+            if (options.task && options.task.status !== 'cancelled') {
+                options.task.status = 'failed';
+                options.task.exitCode = null;
+                options.task.progress = 0;
+                pushLine(options.task, detail);
+            }
+            return { exitCode: 1, timedOut: false, error: `entry file missing: ${verified.missing}`, stdout: result.stdout, stderr: `${result.stderr}\n${detail}` };
+        }
+    }
+    return result;
+}

package/lib/types/http/routes.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { readProfileArg, type LoaderHandle } from '../services/install.ts';
+export interface WebRoute {
+    kind: 'exact';
+    path: string;
+    handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;
+}
+/** The subset of the host web-server service this plugin touches. */
+export interface WebServerService {
+    register(route: WebRoute): () => void;
+}
+/** Read non-official dependencies installed into one profile. */
+export declare function readInstalled(profile: string): Record<string, string>;
+/**
+ * Register the Plugin Hub API on the host web server and return a disposer.
+ * @param webServer - DSH web server service.
+ * @param profile - profile that owns plugin mutations.
+ * @param loader - running loader (optional): lets uninstall remove the entry
+ *   immediately so the page survives a refresh without a host restart.
+ */
+export declare function mountPluginHubRoutes(webServer: WebServerService, profile: string, loader?: LoaderHandle): () => void;
+/** Profile resolution shared with the client route docs. */
+export { readProfileArg };