pi-web-ui 0.85.0 → 0.86.2

package/dist/server/plugin-grants.js

@@ -0,0 +1,281 @@
+/**
+ * plugin-grants —— 插件目录授权表（issue #146）。
+ *
+ * 插件服务端跑的是全权 Node 代码，宿主只能在「自己提供的 API」上做闸门
+ * （见 server/plugins.ts 的 registerAgentTool / route / host.fs）。当插件要碰
+ * **工作区之外**的目录时，宿主弹确认框问用户；用户同意后可以选「记住」——
+ * 记住的东西就落在这个文件里：`<dataDir>/plugin-grants.json`
+ * （`{ grants: { <pluginId>: [绝对目录…] } }`），设置面板可随时撤销。
+ *
+ * 为什么单独一个文件而不是塞进 client-state.json：授权是**安全语义**的持久化
+ * 状态，与 UI 偏好/最近项目是两回事 —— 用户清 UI 状态、迁移设置预设时不该
+ * 连带丢（或带上）一份授权；文件独立后也能被运维一眼看懂、手改、审计。
+ *
+ * 三条设计取舍（都有意为之，改动前请先读）：
+ *
+ * 1. **父目录授权覆盖子目录**：`has()` 命中目录本身或其任一祖先。
+ *    理由：目录授权天然是「子树授权」—— 用户批准 `/proj` 时的心理模型就是
+ *    「这个项目目录随你用」，若还要求逐个 `/proj/src`、`/proj/docs` 再弹十次
+ *    确认，用户只会一路盲点「同意」，闸门形同虚设（安全上反而更糟）。反之
+ *    **不成立**：只授权了 `/proj/a` 时访问 `/proj` 必须再问 —— 祖先目录里
+ *    还躺着用户没打算交出去的东西。判定按路径分段边界做（`/proj` 不覆盖
+ *    `/project`），不做字符串前缀匹配。
+ *
+ * 2. **坏文件不覆盖**：读失败 / JSON 坏 / 形状不对一律当作空表（绝不抛给调用方，
+ *    也绝不在读路径上回写）。因为「读不出来」与「确实是空的」在故障态下无法
+ *    区分，若读失败就写一份空表回去，等于用一次磁盘抖动**静默清空用户全部授权**
+ *    （或更糟：把手工修了一半的文件冲掉）。只有真正发生变更的写操作
+ *    （grant / revoke 命中）才重写文件，此时以内存里的净化为准。
+ *
+ * 3. **文件 I/O 全部 best-effort**：磁盘错误不能让 server 崩（与
+ *    server/client-state.ts 同风格）。写失败 = 这次授权没落盘，下次再问用户；
+ *    内存态仍然生效，本次会话可用。
+ *
+ * 路径归一：一律 `resolve()` 成绝对路径再存；相对路径直接拒绝（相对谁是个隐藏
+ * 上下文，落盘后换个 cwd 就读出另一个目录，等于埋雷）。win32 上比较时忽略大小写
+ * 与尾部分隔符（Windows 文件系统不区分大小写），但**存储保持用户写入时的形式**
+ * （不 lowerCase），否则设置面板里 `C:\Users\Foo` 会显示成 `c:\users\foo`。
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+/** 合法插件 id（与 server/plugins.ts 的 ID_RE 一致，防路径穿越）。 */
+const ID_RE = /^[A-Za-z0-9_-]+$/;
+/** 去掉尾部分隔符（保留根：「C:\」/「/」不能退化）。 */
+function stripTrailingSep(p) {
+    let out = p;
+    for (;;) {
+        if (out.length <= 1)
+            return out;
+        const last = out[out.length - 1];
+        if (last !== "/" && last !== "\\")
+            return out;
+        const trimmed = out.slice(0, -1);
+        // 「C:\」→「C:」在 win32 上语义完全不同（后者是「C 盘当前目录」），不能削。
+        if (/^[A-Za-z]:$/.test(trimmed))
+            return out;
+        out = trimmed;
+    }
+}
+/** 比较用键：win32 折大小写（文件系统不区分大小写）；尾部分隔符统一去掉
+ *  （`C:\a\` 与 `C:\a` 是同一目录，手改文件很容易多写一个斜杠）。 */
+function pathKey(p) {
+    const s = stripTrailingSep(p);
+    return process.platform === "win32" ? s.toLowerCase() : s;
+}
+/** 路径归一：绝对化 + 去尾分隔符；非法（空 / 非字符串 / 含 NUL / 相对 / 盘符怪）→ null。
+ *  存储的也是这个形式（用户写入形式的绝对化版本）。 */
+export function normalizeGrantPath(p) {
+    if (typeof p !== "string")
+        return null;
+    const raw = p.trim();
+    if (!raw || raw.includes("\0"))
+        return null;
+    // 相对路径一律拒绝：授权必须是「明确的绝对目录」，不做 cwd 相对解析。
+    // 顺带干掉 win32 上的怪盘符形式（"C:relative"、"1:\x" 都是 isAbsolute=false）。
+    if (!isAbsolute(raw))
+        return null;
+    let abs;
+    try {
+        abs = resolve(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isAbsolute(abs))
+        return null;
+    return stripTrailingSep(abs);
+}
+/** target 是否落在 ancestor 自身或它的子树上（按分段边界，不做裸前缀匹配：
+ *  `/proj` 不能覆盖 `/project`）。两边都须是 pathKey() 归一后的形式。 */
+function isSameOrInside(targetKey, ancestorKey) {
+    if (targetKey === ancestorKey)
+        return true;
+    const prefix = ancestorKey.endsWith(sep) ? ancestorKey : ancestorKey + sep;
+    return targetKey.startsWith(prefix);
+}
+/** 原子写：临时文件 + rename（同 server/plugin-catalog.ts 的写法；本文件不 import
+ *  它，避免为一个 3 行函数制造模块耦合）。 */
+function atomicWriteJson(filePath, data) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+    renameSync(tmp, filePath);
+}
+/** 读文件并净化为内存表：任何异常（不存在 / 权限 / JSON 坏 / 形状不对）→ 空表。
+ *  条目逐个过 normalizeGrantPath（顺手兼容手工写入的相对路径、重复项、坏 id）。 */
+function readGrantsFile(filePath) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    const grants = raw && typeof raw === "object" && !Array.isArray(raw) ? raw.grants : undefined;
+    if (!grants || typeof grants !== "object" || Array.isArray(grants))
+        return {};
+    const out = {};
+    for (const [id, paths] of Object.entries(grants)) {
+        if (!ID_RE.test(id) || !Array.isArray(paths))
+            continue;
+        const seen = new Set();
+        const list = [];
+        for (const p of paths) {
+            if (typeof p !== "string")
+                continue;
+            const norm = normalizeGrantPath(p);
+            if (!norm)
+                continue;
+            const key = pathKey(norm);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            list.push(norm);
+        }
+        if (list.length > 0)
+            out[id] = list;
+    }
+    return out;
+}
+/**
+ * 插件目录授权表。全局共享（不是 per-client）：授权是「这台机器上的这套插件
+ * 配置允许它访问哪些目录」，任何浏览器/标签页看到的都该是同一份。
+ */
+export class PluginGrantsStore {
+    dataDir;
+    /** 内存缓存 = 上次读盘结果（含净化）。null = 尚未读 / 已被 invalidate。 */
+    cache = null;
+    /** @param dataDir 数据目录；授权文件固定为 `<dataDir>/plugin-grants.json`。 */
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    /** 授权文件路径（测试 / 排障 / 审计用）。 */
+    get filePath() {
+        return resolve(this.dataDir, "plugin-grants.json");
+    }
+    load() {
+        if (!this.cache)
+            this.cache = readGrantsFile(this.filePath);
+        return this.cache;
+    }
+    /** 落盘（best-effort）：失败只丢持久化，不影响本次会话的内存态。 */
+    save() {
+        try {
+            atomicWriteJson(this.filePath, { grants: this.load() });
+        }
+        catch {
+            // best effort —— 磁盘故障不能弄崩 server
+        }
+    }
+    /** 全部授权，按插件聚合（设置面板展示用；路径保持写入时的形式）。
+     *  按 pluginId 排序，保证界面顺序稳定（与本文件里的插入顺序无关）。 */
+    list() {
+        const all = this.load();
+        return Object.keys(all)
+            .sort()
+            .map((pluginId) => ({ pluginId, paths: [...all[pluginId]] }));
+    }
+    /** 单个插件的授权目录（副本；不存在或 id 非法 → 空数组）。 */
+    get(pluginId) {
+        if (!ID_RE.test(pluginId))
+            return [];
+        return [...(this.load()[pluginId] ?? [])];
+    }
+    /**
+     * 是否已授权：命中目录本身，**或它的任一祖先目录已被授权**（见文件头取舍 1）。
+     * 纯字符串判定，不碰磁盘（目录可能还不存在，也可能已被删 —— 授权表是
+     * 「用户批准过」，不是「磁盘现状」）。
+     */
+    has(pluginId, dir) {
+        if (!ID_RE.test(pluginId))
+            return false;
+        const target = normalizeGrantPath(dir);
+        if (!target)
+            return false;
+        const list = this.load()[pluginId];
+        if (!list || list.length === 0)
+            return false;
+        const targetKey = pathKey(target);
+        for (const granted of list) {
+            if (isSameOrInside(targetKey, pathKey(granted)))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * 记一条授权（幂等：同一目录不重复）。返回是否**新增**。
+     *
+     * 幂等按归一后的同一目录判（win32 大小写 / 尾部分隔符等价形式算同一个）。
+     * 注意：父目录已授权时再显式 grant 子目录仍然会记下（返回 true）——
+     * 授权表是「用户知情过什么」的记录，显式批准过的子目录值得留痕，之后撤销
+     * 父目录时它不会莫名其妙一起消失（has 侧照样被父目录短路，不产生额外询问）。
+     */
+    grant(pluginId, dir) {
+        if (!ID_RE.test(pluginId))
+            return false;
+        const norm = normalizeGrantPath(dir);
+        if (!norm)
+            return false;
+        const all = this.load();
+        const list = all[pluginId] ?? [];
+        const key = pathKey(norm);
+        if (list.some((p) => pathKey(p) === key))
+            return false;
+        all[pluginId] = [...list, norm];
+        this.save();
+        return true;
+    }
+    /**
+     * 撤销授权，三种粒度，返回删除的条数：
+     *   - `revoke()`                    清空整张表
+     *   - `revoke(pluginId)`            清掉该插件全部
+     *   - `revoke(pluginId, dir)`       只清该目录（按归一后的同一目录精确匹配，
+     *                                   不连带删除它下面的授权条目）
+     * 只给 dir 不给 pluginId 是非法用法（不知道删谁的）→ 0，不动表。
+     * 无变化时**不写盘**：坏文件/空表不该被一次空撤销顺手覆盖（见取舍 2）。
+     */
+    revoke(pluginId, dir) {
+        const all = this.load();
+        if (pluginId === undefined) {
+            if (dir !== undefined)
+                return 0; // 非法用法：只给目录无法定位插件
+            let total = 0;
+            for (const list of Object.values(all))
+                total += list.length;
+            if (total === 0)
+                return 0;
+            for (const id of Object.keys(all))
+                delete all[id];
+            this.save();
+            return total;
+        }
+        if (!ID_RE.test(pluginId))
+            return 0;
+        const list = all[pluginId];
+        if (!list || list.length === 0)
+            return 0;
+        if (dir === undefined) {
+            delete all[pluginId];
+            this.save();
+            return list.length;
+        }
+        const norm = normalizeGrantPath(dir);
+        if (!norm)
+            return 0;
+        const key = pathKey(norm);
+        const next = list.filter((p) => pathKey(p) !== key);
+        const removed = list.length - next.length;
+        if (removed === 0)
+            return 0;
+        if (next.length > 0)
+            all[pluginId] = next;
+        else
+            delete all[pluginId];
+        this.save();
+        return removed;
+    }
+    /** 磁盘文件变化（多进程 / 用户手改）后重读：丢缓存，下次访问重新读盘。 */
+    reload() {
+        this.cache = null;
+    }
+}

package/dist/server/plugin-installer.js

@@ -0,0 +1,238 @@
+/**
+ * plugin-installer — 插件的后台安装作业（安装 / 更新 / 卸载）。
+ *
+ * 设置面板里的插件操作原本开一个**可见终端 tab** 跑 CLI：过程看得见，但每次操作
+ * 都切主视图 + 关掉设置弹窗 —— 连装几个插件就是「装一个、重开设置、再导航回市场」
+ * （issue #152）。这里把同一件事搬到服务端后台：
+ *
+ *   - 真正执行者仍是 CLI（`pi-web-ui install|uninstall`，bin/pi-web-ui.mjs）——
+ *     单一实现，界面与终端行为永不漂移（`--build` 之类新选项自动同步）；
+ *   - 输出按行回传（`plugin_job` 的 log 段），结束时回 `done`（成功与否 + 输出尾部），
+ *     前端就地显示，弹窗不关；
+ *   - 完成后由调用方（index.ts）重扫插件 + 重推市场列表；
+ *   - **同一时刻只跑一个作业**：安装要动 `<dataDir>/plugins/<id>`，两个作业写同一
+ *     目录必出半装状态，所以第二个请求直接被拒（提示等它结束）；
+ *   - 看门狗：超时杀掉整棵进程树，绝不留一个卡死的 install 占着锁。
+ *
+ * 它不决定「谁能装」：managed 实例与 tabs 闸门在 index.ts 的 dispatch 上做（见
+ * managed.ts 的「服务端拒绝，客户端只是隐藏」）；这里只兜一层，防止别的调用路径绕过。
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pick } from "./i18n.js";
+import { isValidSource } from "./plugin-catalog.js";
+import { killPidTree } from "./process-utils.js";
+/** 插件 id 字符集（与 server/plugins.ts、plugin-catalog.ts 一致，防路径穿越）。 */
+const ID_RE = /^[A-Za-z0-9_-]+$/;
+/** 单个作业的墙钟上限（clone + 依赖安装 + 编译都可能很慢，给足 15 分钟）。 */
+const DEFAULT_TIMEOUT_MS = 15 * 60_000;
+/** 回传给前端的输出尾部上限（失败时展开排障用，别把整个 build 日志塞进消息）。 */
+const MAX_OUTPUT_CHARS = 8000;
+/** 单行上限：某些工具会吐超长单行（进度条），截断后再回传。 */
+const MAX_LINE_CHARS = 2000;
+/** 纯函数：把作业规格翻成 CLI argv（含安全校验），便于单测。
+ *  返回 `{ args }` 或 `{ error }`（文案按 lang 本地化）。 */
+export function buildPluginJobArgs(spec, dataDir, lang) {
+    const l = lang?.() ?? "en";
+    const id = String(spec?.id ?? "").trim();
+    if (!ID_RE.test(id))
+        return {
+            error: pick(l, `非法插件 id "${id}"（仅限字母数字-_）`, `Invalid plugin id "${id}" (letters/digits/-/_ only)`, "plugininstaller.id.invalid", { id }),
+        };
+    if (spec.action === "uninstall")
+        return { args: ["uninstall", id, "--data-dir", dataDir] };
+    const source = String(spec?.source ?? "").trim();
+    if (!isValidSource(source))
+        return {
+            error: pick(l, "安装源需为 owner/repo 或 owner/repo/子目录（本地路径请用命令行安装）", "Install source must be owner/repo or owner/repo/subdir (local paths are CLI-only)", "plugininstaller.source.invalid"),
+        };
+    const args = ["install", source, "--name", id, "--data-dir", dataDir];
+    if (spec.action === "update")
+        args.push("--force");
+    if (spec.build)
+        args.push("--build");
+    return { args };
+}
+export class PluginInstaller {
+    deps;
+    child = null;
+    currentJobId = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 正在跑的作业 id（null = 空闲）。 */
+    get busyJobId() {
+        return this.currentJobId;
+    }
+    /** 启动一个作业；返回 `{ ok: true }` 或 `{ error }`（拒绝原因，已本地化）。 */
+    start(spec, hooks) {
+        const l = hooks.lang?.() ?? "en";
+        if (this.deps.managed)
+            return {
+                ok: false,
+                error: pick(l, "本实例由部署方托管（PI_WEB_MANAGED=1）：插件安装/更新由部署流程负责，界面不提供入口。", "This instance is managed (PI_WEB_MANAGED=1): plugin installs are handled by whoever deploys it.", "plugininstaller.managed"),
+            };
+        const built = buildPluginJobArgs(spec, this.deps.dataDir, hooks.lang);
+        if ("error" in built)
+            return { ok: false, error: built.error };
+        if (this.child)
+            return {
+                ok: false,
+                error: pick(l, "已有一个插件作业在运行，等它结束（或取消）后再试。", "Another plugin job is already running — wait for it (or cancel it) and try again.", "plugininstaller.busy"),
+            };
+        const binPath = join(this.deps.pkgRoot, "bin", "pi-web-ui.mjs");
+        if (!existsSync(binPath))
+            return {
+                ok: false,
+                error: pick(l, `找不到 pi-web-ui 命令行入口（${binPath}），无法执行插件操作。`, `pi-web-ui CLI not found at ${binPath} — cannot run the plugin operation.`, "plugininstaller.cli.missing", { path: binPath }),
+            };
+        const { jobId, action, id: pluginId } = spec;
+        const emit = (msg) => {
+            try {
+                hooks.emit(msg);
+            }
+            catch {
+                /* socket 已死：作业继续跑，只是没人看进度 */
+            }
+        };
+        const child = spawn(process.execPath, [binPath, ...built.args], {
+            windowsHide: true,
+            // POSIX 下自成进程组：取消/看门狗要杀的是整棵树，killPidTree 用 -pid
+            // 干活需要这一点（与 plugin-project.ts 同一写法）。缺了它，Linux/macOS
+            // 上 kill(-pid) 指向不存在的组而静默失败，作业杀不掉、锁一直占着
+            // （CI 的 busy 单测在 Linux 上 5 秒超时，Windows 走 taskkill 不受影响）。
+            detached: process.platform !== "win32",
+            env: { ...process.env, PI_WEB_DATA_DIR: this.deps.dataDir, NO_COLOR: "1" },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        this.child = child;
+        this.currentJobId = jobId;
+        let tail = "";
+        let pending = "";
+        let finished = false;
+        let cancelled = false;
+        let timedOut = false;
+        const pushLine = (raw) => {
+            const line = raw.replace(/\r$/, "");
+            if (!line.trim())
+                return;
+            tail = (tail + line + "\n").slice(-MAX_OUTPUT_CHARS);
+            emit({ type: "plugin_job", jobId, action, pluginId, phase: "log", line: line.slice(0, MAX_LINE_CHARS) });
+        };
+        const onChunk = (chunk) => {
+            pending += chunk.toString();
+            let idx;
+            while ((idx = pending.indexOf("\n")) >= 0) {
+                pushLine(pending.slice(0, idx));
+                pending = pending.slice(idx + 1);
+            }
+            while (pending.length > MAX_LINE_CHARS) {
+                pushLine(pending.slice(0, MAX_LINE_CHARS));
+                pending = pending.slice(MAX_LINE_CHARS);
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            this.killTree(child);
+        }, Math.max(1000, Number(this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS)));
+        const finish = (ok, error) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            if (pending.trim())
+                pushLine(pending);
+            pending = "";
+            this.child = null;
+            this.currentJobId = null;
+            const out = tail;
+            emit({
+                type: "plugin_job",
+                jobId,
+                action,
+                pluginId,
+                phase: "done",
+                ok,
+                ...(error ? { error } : {}),
+                output: out,
+            });
+            void Promise.resolve(hooks.done(ok, { error, output: out })).catch(() => {
+                /* 后处理（重扫/重推）失败不该影响已经结束的作业本身 */
+            });
+        };
+        child.stdout?.on("data", onChunk);
+        child.stderr?.on("data", onChunk);
+        child.on("error", (err) => finish(false, err.message));
+        child.on("close", (code) => {
+            if (cancelled)
+                return finish(false, pick(l, "作业已取消", "Job cancelled", "plugininstaller.cancelled"));
+            if (timedOut)
+                return finish(false, pick(l, `作业超时（${Math.round(Math.max(1000, Number(this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS)) / 60000)} 分钟）已终止`, `Job timed out after ${Math.round(Math.max(1000, Number(this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS)) / 60000)} min and was killed`, "plugininstaller.timeout"));
+            finish(code === 0, code === 0 ? undefined : `exit code ${code}`);
+        });
+        emit({ type: "plugin_job", jobId, action, pluginId, phase: "start" });
+        // cancel 需要拿到 cancelled 标志：挂在实例上由 cancel() 设置。
+        this.cancelFlags.set(jobId, () => {
+            cancelled = true;
+        });
+        return { ok: true };
+    }
+    /** cancel 时置位的标志（jobId → setter），作业结束后清理。 */
+    cancelFlags = new Map();
+    /**
+     * 同步跑一个作业并等它结束（目录同步的自动安装用，见 plugin-catalog-sync.ts）。
+     *
+     * 与 start() 同一条路径、同一把锁：只是把「结束后 resolve」包成 Promise。若已有
+     * 别的作业在跑，会直接返回拒绝原因（不排队）——安装器不是队列，调用方自己决定重试。
+     */
+    run(spec, opts) {
+        return new Promise((resolve) => {
+            const started = this.start(spec, {
+                lang: opts?.lang,
+                emit: (msg) => {
+                    if (msg.type === "plugin_job" && msg.phase === "log" && msg.line)
+                        opts?.onLine?.(msg.line);
+                },
+                done: (ok, info) => resolve({ ok, ...(info.error ? { error: info.error } : {}), output: info.output }),
+            });
+            if (!started.ok)
+                resolve({ ok: false, error: started.error, output: "" });
+        });
+    }
+    /** 取消指定作业（杀掉整棵进程树）。返回是否命中。 */
+    cancel(jobId) {
+        if (!this.currentJobId || this.currentJobId !== jobId || !this.child)
+            return false;
+        this.cancelFlags.get(jobId)?.();
+        this.killTree(this.child);
+        return true;
+    }
+    /** 杀进程树：Windows 走 taskkill /T，POSIX 走进程组（见 process-utils）。 */
+    killTree(child) {
+        const pid = child.pid;
+        if (!pid)
+            return;
+        try {
+            killPidTree(pid);
+        }
+        catch {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* 已经退出了 */
+            }
+        }
+    }
+    /** 关机：杀掉在跑的作业（不留孤儿 install 进程）。 */
+    dispose() {
+        const child = this.child;
+        if (child) {
+            this.cancelFlags.forEach((f) => f());
+            this.killTree(child);
+        }
+        this.child = null;
+        this.currentJobId = null;
+    }
+}