@yunzai-ng/core 0.1.0

package/dist/plugin/market.js

@@ -0,0 +1,700 @@
+/**
+ * 模块职责：插件市场 —— 索引获取与缓存、插件安装、卸载与更新
+ * 依赖方向：依赖 http 客户端契约、logger 契约、`plugin/tar.ts` 与 `util/fs`；
+ *          不认识插件宿主，也不认识面板 —— 安装完成后由调用方决定何时加载
+ * 生命周期：随应用装配创建一次，索引缓存驻留内存并落盘一份，随应用停机一同丢弃
+ * 注意事项：四项与安全相关的约定，修改本文件前须一并考虑：
+ *
+ *          1) **写入范围限定在插件目录之内。** 插件名先经白名单校验，再经
+ *             `joinWithin` 求值；两者任一不通过即拒绝，不做纠正后重试。
+ *          2) **先下载到临时目录，校验通过后再移入插件目录。** 中途失败时插件目录
+ *             保持原状，不会留下半个插件 —— 半个插件会在下次启动时被扫描到并加载失败。
+ *          3) **不自动执行包管理器。** 安装第三方代码的依赖等于执行其 install 脚本，
+ *             该动作须由用户在知情前提下自行发起；此处仅在返回值中标记需要安装依赖。
+ *          4) **索引为不可信输入。** 逐字段校验类型，缺字段的条目整条丢弃而非补默认值：
+ *             索引写错时应当表现为"该插件不出现在列表里"，而不是出现一个装不上的条目。
+ */
+import { execFile } from "node:child_process";
+import { cp, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isDirectory, isFile } from "../util/fs.js";
+import { extractTarGz, joinWithin, singleRoot } from "./tar.js";
+/** 合法插件名：字母或数字开头，其余可含字母、数字、点、下划线与连字符 */
+const NAME_RE = /^[a-z\d][a-z\d._-]*$/i;
+/** 安装归档的体积上限 */
+const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+/**
+ * 克隆与下载的超时毫秒
+ *
+ * 与索引请求分开取值：索引是一份几十 KB 的 JSON，超时设短便于尽快切换到下一个源；
+ * 而一次插件传输可达数十 MB，在窄带链路上按索引超时衡量会把正常的下载判为失败。
+ */
+const TRANSFER_TIMEOUT_MS = 5 * 60 * 1000;
+/** 只读本地仓库的 git 命令超时毫秒；不含网络往返，故与传输超时分开取值 */
+const GIT_LOCAL_TIMEOUT_MS = 10_000;
+/** 判定"看起来是一个插件"时接受的入口文件 */
+const ENTRY_FILES = ["index.js", "index.mjs", "index.cjs", "dist/index.js", "dist/index.mjs"];
+/** 应用镜像前缀的主机白名单 */
+const MIRRORED_HOSTS = ["github.com", "raw.githubusercontent.com", "codeload.github.com"];
+/**
+ * 校验插件名
+ *
+ * 该校验先于路径拼接执行。路径越界校验能挡住 `../`，但挡不住 `.git`、`node_modules`
+ * 这类落在目录之内却会破坏运行环境的名称，因此此处采用白名单而非黑名单。
+ * @param name 待校验的名称
+ * @returns 名称本身
+ * @throws 名称为空、含非法字符或为保留名时
+ */
+export function assertPluginName(name) {
+    if (!NAME_RE.test(name))
+        throw new Error(`插件名不合法：${name}`);
+    if (name === "node_modules" || name.startsWith("."))
+        throw new Error(`插件名为保留名：${name}`);
+    return name;
+}
+/**
+ * 比较两个版本号
+ *
+ * 仅比较点分数值段，忽略预发布标识。内核版本与 `minCore` 都由本项目自己产出，
+ * 不需要完整的 semver 语义，引入依赖的收益低于其体积。
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns a 大于 b 时为正，小于时为负，相等时为零
+ */
+export function compareVersion(a, b) {
+    const left = a.split("-")[0]?.split(".") ?? [];
+    const right = b.split("-")[0]?.split(".") ?? [];
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const x = Number.parseInt(left[i] ?? "0", 10) || 0;
+        const y = Number.parseInt(right[i] ?? "0", 10) || 0;
+        if (x !== y)
+            return x - y;
+    }
+    return 0;
+}
+/**
+ * 对白名单主机的地址应用镜像前缀
+ *
+ * 只处理白名单内的主机：镜像站点通常只代理 GitHub，把任意地址都套上前缀会让
+ * 自建源无法访问，且更难排查 —— 用户看到的会是镜像站的 404 而不是自己的地址写错。
+ * @param url 原始地址
+ * @param mirror 镜像前缀，空串表示直连
+ * @returns 应用镜像后的地址
+ */
+export function applyMirror(url, mirror) {
+    const prefix = mirror.trim().replace(/\/+$/, "");
+    if (prefix === "")
+        return url;
+    let host;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+    if (!MIRRORED_HOSTS.includes(host))
+        return url;
+    return `${prefix}/${url}`;
+}
+/**
+ * 把 git 仓库地址换算为 codeload 归档地址
+ *
+ * git 不可用时的退路。仅识别 GitHub：其归档地址可由仓库地址推导，而通用的
+ * git 服务端不存在统一的归档端点，推断得出的地址仅会导致一次无谓的失败请求。
+ * @param url 仓库地址
+ * @param branch 分支名，缺省取 HEAD
+ * @returns 归档地址；无法推导时 undefined
+ */
+export function tarballFromGit(url, branch = "HEAD") {
+    const match = /^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(url);
+    if (!match)
+        return undefined;
+    return `https://codeload.github.com/${match[1]}/${match[2]}/tar.gz/${branch}`;
+}
+/**
+ * 取一个字符串字段
+ * @param raw 记录
+ * @param key 字段名
+ * @returns 去除首尾空白后的值；类型不符或为空时 undefined
+ */
+function text(raw, key) {
+    const value = raw[key];
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/**
+ * 解析安装来源
+ * @param raw 条目中的 `install` 字段
+ * @returns 安装来源；字段缺失或类型不符时 undefined
+ */
+function parseInstall(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const record = raw;
+    const type = text(record, "type");
+    const url = text(record, "url");
+    if (url === undefined)
+        return undefined;
+    if (!/^https?:\/\//.test(url))
+        return undefined;
+    if (type !== "git" && type !== "tarball")
+        return undefined;
+    const branch = text(record, "branch");
+    return { type, url, ...(branch === undefined ? {} : { branch }) };
+}
+/**
+ * 把一条索引记录解析为条目
+ *
+ * 任一必填字段不合法即返回 undefined，由调用方整条丢弃。
+ * @param raw 索引记录
+ * @param source 该记录所属的索引地址
+ * @returns 条目；记录不合法时 undefined
+ */
+function parseEntry(raw, source) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const record = raw;
+    const name = text(record, "name");
+    if (name === undefined || !NAME_RE.test(name) || name.startsWith("."))
+        return undefined;
+    const install = parseInstall(record.install);
+    if (install === undefined)
+        return undefined;
+    const tags = Array.isArray(record.tags) ? record.tags.filter((tag) => typeof tag === "string") : [];
+    const author = text(record, "author");
+    const version = text(record, "version");
+    const homepage = text(record, "homepage");
+    const minCore = text(record, "minCore");
+    return {
+        name,
+        title: text(record, "title") ?? name,
+        description: text(record, "description") ?? "",
+        tags,
+        official: record.official === true,
+        install,
+        source,
+        ...(author === undefined ? {} : { author }),
+        ...(version === undefined ? {} : { version }),
+        ...(homepage === undefined ? {} : { homepage }),
+        ...(minCore === undefined ? {} : { minCore })
+    };
+}
+/**
+ * 解析一份索引文档
+ *
+ * 接受两种形状：`{ plugins: [...] }` 与顶层直接是数组。后者便于用户把一个手写的
+ * 数组挂到静态文件服务上作为私有源。
+ * @param raw 已解析的 JSON
+ * @param source 索引地址
+ * @returns 合法条目列表
+ * @throws 文档既不是数组也不含 `plugins` 数组时
+ */
+export function parseIndex(raw, source) {
+    const list = Array.isArray(raw)
+        ? raw
+        : typeof raw === "object" && raw !== null && Array.isArray(raw.plugins)
+            ? raw.plugins
+            : undefined;
+    if (list === undefined)
+        throw new Error("索引格式不符：期望数组或含 plugins 数组的对象");
+    const entries = [];
+    for (const item of list) {
+        const entry = parseEntry(item, source);
+        if (entry !== undefined)
+            entries.push(entry);
+    }
+    return entries;
+}
+/**
+ * 调用本机 git 执行一次命令，`MarketDeps.git` 的缺省实现
+ *
+ * 参数以数组传递，不经 shell，因此索引里的地址不会被当作命令解释。
+ * `GIT_TERMINAL_PROMPT=0` 与 `GIT_ASKPASS` 一并关闭凭据提示：市场安装发生在
+ * 无人值守的请求处理过程中，弹出的提示无人应答，只会让请求挂到超时。
+ * @param args 命令参数
+ * @param cwd 工作目录
+ * @param timeout 超时毫秒
+ * @returns 标准输出
+ * @throws 命令不存在、超时或退出码非零时
+ */
+const runGit = (args, cwd, timeout) => {
+    return new Promise((resolve, reject) => {
+        execFile("git", [...args], { cwd, timeout, env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "echo" }, windowsHide: true }, (err, stdout, stderr) => {
+            if (err)
+                reject(new Error(`git ${args[0]} 失败：${stderr.trim() || err.message}`));
+            else
+                resolve(stdout);
+        });
+    });
+};
+/**
+ * 插件市场
+ *
+ * 索引缓存同时驻留内存与磁盘：内存缓存服务于同一次运行内的反复浏览，磁盘缓存
+ * 服务于重启后的首次打开 —— 面板在无网络时也应当能列出上次看到的插件，
+ * 而不是显示一个空列表。
+ */
+export class PluginMarket {
+    /** 依赖 */
+    #deps;
+    /** 内存中的索引条目 */
+    #entries = [];
+    /** 内存索引的获取时间，0 表示尚未取到 */
+    #fetchedAt = 0;
+    /** 逐源结果，随索引一同更新 */
+    #sources = [];
+    /** 正在进行的索引获取，用于合并并发请求 */
+    #inflight;
+    /** git 可用性探测结果 */
+    #gitAvailable;
+    /** 执行 git 命令，未注入时调用本机 git */
+    #git;
+    /**
+     * @param deps 依赖
+     */
+    constructor(deps) {
+        this.#deps = deps;
+        this.#git = deps.git ?? runGit;
+    }
+    /**
+     * 列出市场中的插件
+     *
+     * 缓存未过期时不发起网络请求。安装状态每次都重新读取文件系统：用户可能在面板
+     * 之外手动删掉了插件目录，沿用缓存里的状态会让"卸载"按钮对着一个不存在的目录。
+     * @param force 忽略缓存，强制重新获取
+     * @returns 索引快照
+     */
+    async list(force = false) {
+        const settings = this.#deps.settings();
+        const fresh = this.#fetchedAt > 0 && Date.now() - this.#fetchedAt < settings.cacheTtl;
+        const cached = !force && fresh;
+        if (force || !fresh)
+            await this.#refresh(force);
+        const plugins = [];
+        for (const entry of this.#entries) {
+            plugins.push({ ...entry, installed: await this.#isInstalled(entry.name) });
+        }
+        plugins.sort((a, b) => a.name.localeCompare(b.name));
+        return { fetchedAt: this.#fetchedAt, cached, sources: [...this.#sources], plugins };
+    }
+    /**
+     * 按名称取一个条目
+     * @param name 插件名
+     * @returns 条目；索引中没有时 undefined
+     */
+    async entry(name) {
+        await this.list();
+        return this.#entries.find(item => item.name === name);
+    }
+    /**
+     * 合并并发的索引获取
+     *
+     * 面板打开时会同时请求概览与插件列表，两者都会触发获取。此处让后到者复用
+     * 同一次网络请求，而不是各发一遍。
+     * @param force 忽略磁盘缓存
+     * @returns 获取完成
+     */
+    async #refresh(force) {
+        if (this.#inflight !== undefined)
+            return this.#inflight;
+        const task = this.#fetchAll(force).finally(() => {
+            this.#inflight = undefined;
+        });
+        this.#inflight = task;
+        return task;
+    }
+    /**
+     * 逐个索引获取并合并条目
+     *
+     * 同名插件以靠前的索引为准，因此用户可以把私有源放在官方源之前来覆盖某个条目。
+     * 全部索引都失败且没有缓存可用时，条目置空但仍记录获取时间：面板据 `sources`
+     * 展示失败原因，重试由用户显式触发，避免每次刷新页面都重复请求已知不可达的地址。
+     * @param force 忽略磁盘缓存
+     */
+    async #fetchAll(force) {
+        const { sources, mirror, timeout, cacheTtl } = this.#deps.settings();
+        if (!force && this.#fetchedAt === 0) {
+            const cache = await this.#loadCache();
+            if (cache !== undefined && Date.now() - cache.fetchedAt < cacheTtl) {
+                this.#entries = cache.entries;
+                this.#fetchedAt = cache.fetchedAt;
+                this.#sources = [{ url: this.#deps.cacheFile, ok: true, count: cache.entries.length }];
+                return;
+            }
+        }
+        const results = [];
+        const merged = new Map();
+        for (const url of sources) {
+            try {
+                const raw = await this.#deps.http.get(applyMirror(url, mirror), {
+                    responseType: "json",
+                    timeout,
+                    retry: 1
+                });
+                const entries = parseIndex(raw, url);
+                for (const item of entries)
+                    if (!merged.has(item.name))
+                        merged.set(item.name, item);
+                results.push({ url, ok: true, count: entries.length });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                results.push({ url, ok: false, error, count: 0 });
+                this.#deps.logger.warn(`插件市场索引获取失败 ${url}：${error}`);
+            }
+        }
+        this.#sources = results;
+        if (merged.size === 0 && results.every(item => !item.ok)) {
+            const cache = await this.#loadCache();
+            if (cache !== undefined) {
+                this.#entries = cache.entries;
+                this.#fetchedAt = cache.fetchedAt;
+                this.#deps.logger.warn("插件市场全部索引不可达，沿用上次缓存");
+                return;
+            }
+        }
+        this.#entries = [...merged.values()];
+        this.#fetchedAt = Date.now();
+        await this.#saveCache();
+    }
+    /**
+     * 读取磁盘缓存
+     *
+     * 缓存文件按不可信输入对待并重新经 `parseIndex` 校验：文件可能被用户手工改动，
+     * 也可能是旧版本写下的、字段形状已经不同的内容。
+     * @returns 缓存内容；文件不存在或不可解析时 undefined
+     */
+    async #loadCache() {
+        try {
+            const raw = JSON.parse(await readFile(this.#deps.cacheFile, "utf8"));
+            if (typeof raw !== "object" || raw === null)
+                return undefined;
+            const record = raw;
+            if (typeof record.fetchedAt !== "number")
+                return undefined;
+            const entries = parseIndex(record.entries ?? [], this.#deps.cacheFile);
+            return { fetchedAt: record.fetchedAt, entries };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * 写入磁盘缓存
+     *
+     * 写入失败只记日志：缓存是加速手段，写不进去不应当让一次成功的索引获取失败。
+     */
+    async #saveCache() {
+        const doc = { fetchedAt: this.#fetchedAt, entries: this.#entries };
+        try {
+            await mkdir(dirname(this.#deps.cacheFile), { recursive: true });
+            await writeFile(this.#deps.cacheFile, JSON.stringify(doc, undefined, 2), "utf8");
+        }
+        catch (err) {
+            this.#deps.logger.debug(`插件市场缓存写入失败：${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * 判断插件目录下是否已存在同名目录
+     * @param name 插件名
+     * @returns 是否已安装
+     */
+    async #isInstalled(name) {
+        try {
+            return await isDirectory(joinWithin(this.#deps.pluginsDir, name));
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 安装一个插件
+     *
+     * 全过程在临时目录内完成，仅在校验通过后才移入插件目录，因此失败时插件目录
+     * 保持原状。安装完成后不加载插件：加载时机由调用方决定，面板据返回值提示用户
+     * 是否需要先安装依赖。
+     * @param name 插件名
+     * @param opts 可选参数
+     * @param opts.replace 目标已存在时先删除再安装
+     * @returns 安装结果
+     * @throws 名称不合法、索引中无此插件、内核版本不满足、目标已存在或取源失败时
+     */
+    async install(name, opts = {}) {
+        assertPluginName(name);
+        const entry = await this.entry(name);
+        if (entry === undefined)
+            throw new Error(`插件市场中没有名为 ${name} 的插件`);
+        const target = joinWithin(this.#deps.pluginsDir, name);
+        const exists = await isDirectory(target);
+        if (exists && opts.replace !== true)
+            throw new Error(`插件 ${name} 已安装，如需覆盖请先卸载`);
+        if (entry.minCore !== undefined && compareVersion(this.#deps.coreVersion, entry.minCore) < 0) {
+            throw new Error(`插件 ${name} 要求内核版本不低于 ${entry.minCore}，当前为 ${this.#deps.coreVersion}`);
+        }
+        await mkdir(this.#deps.tempDir, { recursive: true });
+        const staging = await mkdtemp(join(this.#deps.tempDir, `market-${name}-`));
+        try {
+            const { via, root } = await this.#fetch(entry, staging);
+            await this.#assertLooksLikePlugin(root, name);
+            const manifest = await this.#manifest(root);
+            const version = manifest?.version ?? entry.version ?? "0.0.0";
+            const needsDependencies = Object.keys(manifest?.dependencies ?? {}).length > 0 && !(await isDirectory(join(root, "node_modules")));
+            if (exists)
+                await rm(target, { recursive: true, force: true });
+            await mkdir(this.#deps.pluginsDir, { recursive: true });
+            await this.#move(root, target);
+            this.#deps.logger.info(`插件 ${name}@${version} 已安装至 ${target}`);
+            if (needsDependencies)
+                this.#deps.logger.warn(`插件 ${name} 声明了运行时依赖，需在其目录内自行执行包管理器安装`);
+            // 带 `.git` 的目录此后可就地拉取；归档装出来的每次更新都要整目录重下
+            return { name, dir: target, via, version, needsDependencies, updatable: via === "git" ? "pull" : "reinstall" };
+        }
+        finally {
+            await rm(staging, { recursive: true, force: true });
+        }
+    }
+    /**
+     * 卸载一个插件
+     *
+     * 只删除插件目录。配置文件与数据库另行存放，保留它们使得重新安装后原有配置仍然有效。
+     * @param name 插件名
+     * @returns 是否确实删除了目录
+     * @throws 名称不合法时
+     */
+    async remove(name) {
+        assertPluginName(name);
+        const target = joinWithin(this.#deps.pluginsDir, name);
+        if (!(await isDirectory(target)))
+            return false;
+        await rm(target, { recursive: true, force: true });
+        this.#deps.logger.info(`插件 ${name} 目录已删除：${target}`);
+        return true;
+    }
+    /**
+     * 更新一个插件：目录已是 git 仓库时就地拉取，否则退回重新安装
+     * @param name 插件名
+     * @returns 安装结果
+     * @throws 与 `install` 相同；就地拉取失败时抛出 git 的错误
+     */
+    async update(name) {
+        /*
+         * 优先就地拉取，因为重新安装会删掉目录里那份 `node_modules`
+         *
+         * 那是使用者按提示自己装的，动辄几十兆；删掉意味着每更新一次插件就要在国内网络下
+         * 重装一遍依赖，而更新的内容通常只是几行代码。就地拉取还保住目录内其他不属于仓库的
+         * 东西（插件写在安装目录下的缓存、使用者放进去的资源）—— 那些本不该放在那里，
+         * 但目录是使用者的，删它得有个理由，而「顺便」不是理由。
+         *
+         * 退回重新安装的三种情形都无从拉取：目录不是 git 仓库、本机没有 git、来源不是 git。
+         */
+        assertPluginName(name);
+        const target = joinWithin(this.#deps.pluginsDir, name);
+        const pulled = await this.#tryPull(name, target);
+        return pulled ?? this.install(name, { replace: true });
+    }
+    /**
+     * 试着就地拉取一个插件
+     * @param name 插件名
+     * @param dir 插件安装目录
+     * @returns 拉取结果；不具备就地拉取条件（无 git、目录不是仓库、来源不是 git）时 undefined
+     * @throws 拉取过程本身失败时 —— 那意味着网络或仓库状态有问题，此时退回重新安装会把一次
+     *         可修复的失败变成一次目录删除
+     */
+    async #tryPull(name, dir) {
+        /*
+         * 两处刻意的做法
+         *
+         * **`fetch` + `reset --hard` 而非 `pull`。** `pull` 会试图合并，而目录里的改动多半不是
+         * 有意维护的分叉（编辑器留下的文件、上次安装的残留）；一次合并冲突会让目录停在半新半旧
+         * 的状态，且要求使用者懂 git 才能收拾。`reset --hard` 的语义是「以远端为准」，与「更新
+         * 插件」这个动作一致。
+         *
+         * **改动先 stash 再 reset，顺序即安全性。** 那些改动有时是刻意为之（改了一处硬编码的
+         * 地址），故留一份可取回的副本并在日志里说明取回办法 —— 直接丢掉等于替使用者做了他没
+         * 同意的决定。反过来先 reset 后 stash 就是数据丢失。
+         */
+        if (!(await isDirectory(join(dir, ".git"))))
+            return undefined;
+        const entry = await this.entry(name);
+        if (entry === undefined)
+            throw new Error(`插件市场中没有名为 ${name} 的插件`);
+        if (entry.install.type !== "git")
+            return undefined;
+        if (!(await this.#hasGit()))
+            return undefined;
+        if (entry.minCore !== undefined && compareVersion(this.#deps.coreVersion, entry.minCore) < 0) {
+            throw new Error(`插件 ${name} 要求内核版本不低于 ${entry.minCore}，当前为 ${this.#deps.coreVersion}`);
+        }
+        const before = (await this.#manifest(dir))?.version;
+        const head = async () => (await this.#git(["rev-parse", "HEAD"], dir, GIT_LOCAL_TIMEOUT_MS)).trim();
+        const wasAt = await head();
+        // 使用者改过的文件先暂存。`--include-untracked` 一并收进去：新增的文件同样会被
+        // reset 之后的 checkout 撞上，而它更可能是使用者自己放的东西
+        const dirty = (await this.#git(["status", "--porcelain"], dir, GIT_LOCAL_TIMEOUT_MS)).trim() !== "";
+        if (dirty) {
+            await this.#git(["stash", "push", "--include-untracked", "-m", `yunzai-ng 更新前自动暂存 ${new Date().toISOString()}`], dir, GIT_LOCAL_TIMEOUT_MS);
+            this.#deps.logger.warn(`插件 ${name} 目录内有未提交的改动，已暂存。如需取回：在该目录执行 git stash pop`);
+        }
+        const { mirror } = this.#deps.settings();
+        const branch = entry.install.branch;
+        /*
+         * 拉取时重新指定远端地址，不沿用目录里记着的那个
+         *
+         * 镜像前缀是可改的配置项：使用者装插件时用着某个镜像，此后换了一个，而目录里的
+         * origin 仍指向旧镜像。那个镜像可能已经关站，于是"更新"永远失败，且错误信息
+         * 指向一个使用者早已不用的地址。以索引里的地址为准，镜像每次现算。
+         */
+        const url = applyMirror(entry.install.url, mirror);
+        const ref = branch ?? "HEAD";
+        await this.#git(["fetch", "--depth", "1", url, ref], dir, TRANSFER_TIMEOUT_MS);
+        await this.#git(["reset", "--hard", "FETCH_HEAD"], dir, GIT_LOCAL_TIMEOUT_MS);
+        const nowAt = await head();
+        const changed = nowAt !== wasAt;
+        const manifest = await this.#manifest(dir);
+        const version = manifest?.version ?? entry.version ?? "0.0.0";
+        const needsDependencies = Object.keys(manifest?.dependencies ?? {}).length > 0 && !(await isDirectory(join(dir, "node_modules")));
+        if (changed)
+            this.#deps.logger.info(`插件 ${name} 已就地更新至 ${version}（${wasAt.slice(0, 7)} → ${nowAt.slice(0, 7)}）`);
+        else
+            this.#deps.logger.info(`插件 ${name} 已是最新版本 ${version}`);
+        if (needsDependencies)
+            this.#deps.logger.warn(`插件 ${name} 声明了运行时依赖，需在其目录内自行执行包管理器安装`);
+        return {
+            name,
+            dir,
+            via: "pull",
+            version,
+            needsDependencies,
+            changed,
+            // 就地拉取过一次，说明目录确实是 git 仓库，此后照旧走这条路
+            updatable: "pull",
+            ...(before === undefined ? {} : { fromVersion: before })
+        };
+    }
+    /**
+     * 把插件内容取到临时目录
+     *
+     * git 优先：克隆得到的目录带 `.git`，用户此后可以自行 `git pull`，也便于切换分支。
+     * git 不可用时退回归档下载，GitHub 仓库地址可换算出 codeload 归档地址，
+     * 其余来源若只提供 git 则明确报错，而不是静默失败。
+     * @param entry 索引条目
+     * @param staging 临时目录
+     * @returns 取源方式与插件内容的根目录
+     * @throws git 与归档两条路都不可用，或归档为空时
+     */
+    async #fetch(entry, staging) {
+        const { mirror } = this.#deps.settings();
+        if (entry.install.type === "git" && (await this.#hasGit())) {
+            const dest = join(staging, "repo");
+            const args = ["clone", "--depth", "1", "--single-branch"];
+            if (entry.install.branch !== undefined)
+                args.push("--branch", entry.install.branch);
+            args.push(applyMirror(entry.install.url, mirror), dest);
+            await this.#git(args, staging, TRANSFER_TIMEOUT_MS);
+            return { via: "git", root: dest };
+        }
+        const url = entry.install.type === "tarball"
+            ? entry.install.url
+            : tarballFromGit(entry.install.url, entry.install.branch);
+        if (url === undefined)
+            throw new Error(`插件 ${entry.name} 仅提供 git 来源，而本机未安装 git`);
+        const bytes = await this.#deps.http.buffer(applyMirror(url, mirror), {
+            timeout: TRANSFER_TIMEOUT_MS,
+            retry: 1
+        });
+        if (bytes.byteLength > MAX_ARCHIVE_BYTES) {
+            throw new Error(`归档体积 ${bytes.byteLength} 字节超过上限 ${MAX_ARCHIVE_BYTES} 字节`);
+        }
+        const raw = join(staging, "raw");
+        const written = await extractTarGz(bytes, raw);
+        if (written.length === 0)
+            throw new Error(`归档 ${url} 中没有可写入的文件`);
+        const top = singleRoot(written);
+        return { via: "tarball", root: top === undefined ? raw : join(raw, top) };
+    }
+    /**
+     * 探测本机 git 可用性
+     *
+     * 结果缓存到进程结束。用户在运行期间安装 git 属于少见情形，重启即可重新探测，
+     * 不值得为此在每次安装时多执行一次子进程。
+     *
+     * **先建出临时目录再探测。** 它是这条命令的 cwd，而子进程的 cwd 不存在时
+     * execFile 报 ENOENT —— 那会被下面的 catch 记成「本机没有 git」并缓存到进程结束，
+     * 于是此后每一次安装都退回归档下载，而真实原因与 git 毫无关系。`install` 恰好在
+     * 调用本方法之前建过该目录，`update` 的就地拉取那条路没有，故不能依赖调用顺序。
+     * @returns git 是否可用
+     */
+    async #hasGit() {
+        if (this.#gitAvailable !== undefined)
+            return this.#gitAvailable;
+        try {
+            await mkdir(this.#deps.tempDir, { recursive: true });
+            await this.#git(["--version"], this.#deps.tempDir, GIT_LOCAL_TIMEOUT_MS);
+            this.#gitAvailable = true;
+        }
+        catch {
+            this.#gitAvailable = false;
+            this.#deps.logger.debug("本机未检测到 git，插件安装改用归档下载");
+        }
+        return this.#gitAvailable;
+    }
+    /**
+     * 校验取到的内容是否具备插件形态
+     *
+     * 该校验的目的是及早给出可理解的错误：地址写错时下载到的往往是一份文档仓库或
+     * 一个空目录，若不检查就移入插件目录，用户看到的会是下次启动时的一条加载失败。
+     * @param root 内容根目录
+     * @param name 插件名
+     * @throws 既无 package.json 也无入口文件时
+     */
+    async #assertLooksLikePlugin(root, name) {
+        if (await isFile(join(root, "package.json")))
+            return;
+        for (const entry of ENTRY_FILES)
+            if (await isFile(join(root, entry)))
+                return;
+        throw new Error(`取到的内容不像插件：${name} 目录内既无 package.json 也无入口文件`);
+    }
+    /**
+     * 读取 package.json 中与安装相关的字段
+     * @param root 内容根目录
+     * @returns 版本与依赖声明；无 package.json 或不可解析时 undefined
+     */
+    async #manifest(root) {
+        try {
+            const raw = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+            if (typeof raw !== "object" || raw === null)
+                return undefined;
+            const record = raw;
+            const version = typeof record.version === "string" ? record.version : undefined;
+            const dependencies = typeof record.dependencies === "object" && record.dependencies !== null
+                ? record.dependencies
+                : undefined;
+            return { ...(version === undefined ? {} : { version }), ...(dependencies === undefined ? {} : { dependencies }) };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * 把临时目录中的内容移到插件目录
+     *
+     * `rename` 在跨设备时会失败（EXDEV）—— 用户可能把临时目录配到另一个分区，
+     * 此时退回递归复制。复制成本高于改名，因此仅作为兜底而非默认路径。
+     * @param from 源目录
+     * @param to 目标目录
+     */
+    async #move(from, to) {
+        try {
+            await rename(from, to);
+        }
+        catch (err) {
+            if (err.code !== "EXDEV")
+                throw err;
+            await cp(from, to, { recursive: true });
+        }
+    }
+}
+//# sourceMappingURL=market.js.map