dsh-plugin 0.1.1 → 1.1.0

package/lib/services/task-queue.js

@@ -0,0 +1,457 @@
+/**
+ * 后台安装/卸载任务队列：内存任务注册表 + 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 = [];
+    // 展示目标用 displayTarget（owner/repo）：安装 target 可能被服务端切成 npm 包名
+    // （npm 反查命中），队列恢复/待重启展示对用户保持仓库名无感知
+    const show = (task) => task.displayTarget ?? task.target;
+    for (const item of queue) {
+        const task = item.task;
+        if (task.status === 'pending') {
+            found.push({ id: task.id, target: show(task), action: task.action, status: 'pending', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES), attempts: task.attempts });
+        }
+    }
+    tasks.forEach((task) => {
+        if (task.status === 'running') {
+            found.unshift({ id: task.id, target: show(task), action: task.action, status: 'running', progress: task.progress, lines: task.lines.slice(0, MAX_TASK_LINES), attempts: task.attempts });
+        }
+    });
+    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, displayTarget: options.displayTarget, action: options.action, status: 'pending', timedOut: false, exitCode: null, progress: 0, lines: [], attempts: options.attempts ?? [] };
+    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];
+    // 记录实际执行的命令（npm 通道显示包名，git 通道显示 github: 源）：失败提 Issue 时
+    // 「已尝试的安装方式」如实展示完整命令链，作者一眼看清我们跑过什么
+    const executed = `dsh plugin --profile ${profile} ${action} ${target}`;
+    if (task && !task.attempts.includes(executed)) {
+        task.attempts.push(executed);
+    }
+    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 };
+    }
+}
+/** 从 pnpm `Ignored build scripts:` 提示行解析被拦截的构建脚本 key（name@version，逗号分隔）。 */
+function ignoredBuildKeys(output) {
+    const m = /Ignored build scripts:\s*(.+)/i.exec(output);
+    if (m === null)
+        return [];
+    return m[1]
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s !== '');
+}
+/**
+ * Run a plugin mutation with one recovery path: when `add` fails because
+ * pnpm's allowBuilds gate blocks a build script — either the git-hosted
+ * package's own `prepare` (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, key from
+ * the printed key@url hint) or a dependency's native build
+ * (`ERR_PNPM_IGNORED_BUILDS`, key = the listed name@version) — write the
+ * exact keys 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}`;
+        // git 源：pnpm 打印的 key@url 提示
+        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 v11 拦截（ERR_PNPM_IGNORED_BUILDS）：git 与 npm 源都会出现。
+        // allowBuilds 的 key 是输出里列出的 name@version（如 node-pty@1.1.0），逐个放行后重试一次；
+        // 输出解析不到时回退用目标名（插件自身构建脚本被拦的 npm 场景）。
+        if (output.includes('ERR_PNPM_IGNORED_BUILDS')) {
+            const keys = ignoredBuildKeys(output);
+            if (keys.length === 0 && !options.target.startsWith('github:'))
+                keys.push(options.target);
+            if (keys.length > 0) {
+                if (options.task) {
+                    options.task.status = 'running';
+                    options.task.exitCode = null;
+                    pushLine(options.task, `[allow build] ${keys.join(', ')}`);
+                }
+                for (const key of keys)
+                    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 };

package/lib/types/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * dsh-plugin host entry: mounts the Plugin Hub HTTP routes once the host
+ * web server service is available. The browser bundle (src/client) talks to
+ * these same-origin routes to perform real installs from inside the app.
+ */
+import { type LoaderHandle } from './services/install.ts';
+import { type WebServerService } from './http/routes.ts';
+export declare const name = "dsh-plugin";
+export interface Config {
+    /** DSH profile that owns plugin mutations. Defaults to the booted profile. */
+    profile?: string;
+}
+/** The subset of the cordis host context this plugin touches. */
+interface HostContext {
+    webServer: WebServerService;
+    /** 运行中 loader：卸载成功后主动移除条目、立即生效（宿主未提供时卸载仍需重启） */
+    loader?: LoaderHandle;
+    inject(services: string[], callback: (host: HostContext) => void): void;
+    effect(callback: () => void, label?: string): void;
+}
+/**
+ * Mount the Plugin Hub routes after the web server service becomes available.
+ * @param ctx - cordis host context.
+ * @param config - optional profile override.
+ */
+export declare function apply(ctx: HostContext, config?: Config): void;
+export {};

package/lib/types/services/install-types.d.ts

@@ -0,0 +1,69 @@
+/** 安装/卸载运行时的公共类型与常量（无依赖，供各服务模块复用）。 */
+/** 一个 pnpm 安装子进程的结果快照。 */
+export interface InstallResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    error: string | null;
+    stdout: string;
+    stderr: string;
+}
+export interface InstallTask {
+    id: number;
+    /** 操作目标：`github:<owner>/<repo>`（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
+    target: string;
+    /** 展示用目标（owner/repo）：npm 安装时 target 是包名，前端恢复用此字段显示仓库名，保持用户无感知 */
+    displayTarget?: string;
+    /** 尝试过的安装方式（npm registry 反查 + 实际执行的 CLI 命令，按先后顺序）：
+     *  失败提 Issue 时如实贴给作者，作者据此反推正确的 npm 包名（组织 scope 与 GitHub 用户名不一致时
+     *  仅凭仓库名猜不到，作者看到我们查过/试过的命令就能直接指认）。 */
+    attempts: string[];
+    action: 'add' | 'remove';
+    /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
+    status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled';
+    timedOut: boolean;
+    exitCode: number | null;
+    /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出，阶段行兜底 */
+    progress: number;
+    /** Newest output lines first (consumer shows the tail). */
+    lines: string[];
+}
+/** 子进程启动参数（复用宿主 dsh 入口，或回退到 PATH 上的 `dsh`）。 */
+export interface Invocation {
+    file: string;
+    prefixArgs: string[];
+    cwd: string;
+    useShell: boolean;
+}
+/** 排队中的变更任务及其启动参数。 */
+export interface QueueItem {
+    task: InstallTask;
+    options: {
+        action: 'add' | 'remove';
+        profile: string;
+        target: string;
+        timeoutMs?: number;
+        env?: NodeJS.ProcessEnv;
+    };
+}
+/**
+ * 安装成功但宿主尚未重启的插件（待重启后生效）。纯内存态：宿主进程一重启
+ * 它自然清空，正好等于「重启后提醒消失」的语义，无需任何重启探测。
+ */
+export interface PendingRestart {
+    /** `github:<owner>/<repo>` 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
+    target: string;
+    /** 待重启语义：install 装完等挂载生效 / uninstall 卸完等清理 loader 残留 */
+    kind: 'install' | 'uninstall';
+    /** 任务完成时刻（epoch ms） */
+    at: number;
+}
+/** Grammar of an accepted `github:<owner>/<repo>` install target. */
+export declare const REPO_RE: RegExp;
+/** Grammar of an npm package name (used for uninstall targets). */
+export declare const PACKAGE_RE: RegExp;
+/** 捕获输出上限：stdout/stderr 各保留尾部 N 字节。 */
+export declare const CAPTURE_LIMIT_BYTES: number;
+/** Max output lines kept per task (newest wins). */
+export declare const MAX_TASK_LINES = 200;
+/** Max tracked tasks; oldest finished tasks are dropped first. */
+export declare const MAX_TASKS = 50;

package/lib/types/services/install.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Install runner 的统一出口：执行真实插件变更（spawn 官方 dsh CLI 子进程）。
+ * 实现按职责拆分在同目录子模块，本文件只做公共 API 的 re-export，保持外部
+ * import 面稳定（routes.ts / index.ts 仍从 `services/install.ts` 引入）。
+ *
+ * 模块划分：
+ *  - install-types.ts  公共类型与常量
+ *  - pending-restart.ts  待重启列表内存态管理
+ *  - loader.ts          运行中 loader 的读取与卸载即时停用
+ *  - profile.ts         宿主 profile / 目标校验 / allowBuilds 写入
+ *  - task-queue.ts      任务注册表 + FIFO 队列 worker + 子进程生命周期
+ */
+export type { InstallResult, InstallTask, Invocation, PendingRestart, QueueItem } from './install-types.ts';
+export type { LoaderHandle } from './loader.ts';
+export { addPendingRestart, clearPendingRestart, listPendingRestarts } from './pending-restart.ts';
+export { dumpLoaderEntries, removeLoadedEntry } from './loader.ts';
+export { addAllowBuildsKey, githubTarget, parseAllowBuildsKey, readProfileArg, validPackageName } from './profile.ts';
+export { activeTask, cancelTask, getTask, hasQueuedTarget, hasRunningTask, runPluginMutation, startPluginMutation } from './task-queue.ts';

package/lib/types/services/installed-versions.d.ts

@@ -0,0 +1,24 @@
+export interface InstalledVersionRecord {
+    /** 安装时的目录最新 release 版本（无 release 的仓库为空串） */
+    version: string;
+    /** 安装时的仓库最近更新时间（ISO，GitHub pushed_at）；无 release 仓库的更新依据 */
+    updatedAt: string;
+    installedAt: string;
+    /** npm 优先通道反查命中的官方 npm 包名（repo → 包名映射）：目录数据可能未下发
+     *  npmPackage（组织 scope 与 GitHub 用户名不一致），客户端据此把依赖 key 匹配回仓库 */
+    npmPackage?: string;
+}
+export type InstalledVersionTable = Record<string, InstalledVersionRecord>;
+export declare function versionsFilePath(profile: string): string;
+export declare function readInstalledVersions(profile: string): InstalledVersionTable;
+/** Record the catalog signals (version + repo updated time) present at install time for one repo. */
+export declare function recordInstalledVersion(profile: string, repo: string, version: string, updatedAt: string): void;
+/**
+ * Record the npm package name resolved for a repo (npm-first install channel).
+ * Called at `/install` time so the mapping exists even before the task finishes;
+ * harmless when the repo is not (yet) installed — the client only treats a repo
+ * as installed when its dependency key actually exists.
+ */
+export declare function recordResolvedNpmPackage(profile: string, repo: string, npmPackage: string): void;
+/** Forget the recorded version for one repo (called on uninstall). */
+export declare function removeInstalledVersion(profile: string, repo: string): void;

package/lib/types/services/loader.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 运行中 loader 的读取与停用：卸载成功后对匹配条目做 live-disable，
+ * 使卸载立即生效（刷新页面不再加载已卸载的 client bundle，也无需重启）。
+ */
+/**
+ * 运行中 loader 的最小接口：卸载成功后即时移除条目用。
+ * 对应官方 `ctx.loader`（cordis-plugin-loader 的 Loader 服务）的读取面与移除面。
+ * 移除方式：对匹配条目 live-disable（`entry.update({ disabled: true })`），
+ * 而不是 `loader.remove(id)` —— disable 走 Entry.update 的 disabled 分支，不触发
+ * tree.write()（不会把运行态条目烘焙回 cordis.yml），也不依赖嵌套子树的 id 解析。
+ */
+export interface LoaderHandle {
+    /** 遍历当前插件树的全部条目（含嵌套子树）。 */
+    entries(): Iterable<{
+        id: string;
+        options: {
+            id?: string;
+            name?: string;
+            disabled?: boolean | null;
+        };
+        /** live-disable 一个条目（官方 Entry.update，force=true 覆盖初始化竞态）。 */
+        update(options: {
+            disabled: boolean | null;
+        }, create?: boolean, force?: boolean): Promise<void>;
+    }>;
+    /** 停止并移除一个条目（官方 Loader API：resolve → EntryGroup.remove → tree.write）。 */
+    remove(id: string): Promise<void>;
+}
+/** 运行中 loader 的全部条目（id + options.name），诊断用。 */
+export declare function dumpLoaderEntries(loader: LoaderHandle | undefined): Array<{
+    id: string;
+    name?: string;
+}>;
+/**
+ * 卸载成功后从运行中 loader 停用指定包的条目，使卸载立即生效（刷新页面不再
+ * 加载已卸载的 client bundle，也无需重启）。做法：按 name 扫描
+ * `loader.entries()`（含嵌套子树），对每个匹配条目
+ * `entry.update({ disabled: true })` 做 live-disable —— fiber 被 dispose，
+ * client-modules 对账后不再把它写进 `__DSH_BOOT__`，页面刷新即恢复。
+ * 返回 true = 无需重启（条目已停用，或本就没加载过）；false = 未能停用，
+ * 需登记「待重启清理」兜底。宿主关键包（@deepseek-ai/* 与本插件自身）一律跳过。
+ */
+export declare function removeLoadedEntry(loader: LoaderHandle, name: string): Promise<boolean>;