@yunzai-ng/core 0.1.0

package/dist/plugin/market.d.ts

@@ -0,0 +1,264 @@
+import type { HttpClient, Logger } from "@yunzai-ng/types";
+/** 安装来源 */
+export interface MarketInstallSpec {
+    /** 取源方式 */
+    readonly type: "git" | "tarball";
+    /** 仓库地址或归档地址 */
+    readonly url: string;
+    /** git 分支，缺省由远端决定 */
+    readonly branch?: string;
+}
+/** 索引中的一个插件条目 */
+export interface MarketEntry {
+    /** 插件名，同时是安装目录名与配置文件名 */
+    readonly name: string;
+    /** 展示标题 */
+    readonly title: string;
+    /** 一句话说明 */
+    readonly description: string;
+    /** 作者 */
+    readonly author?: string;
+    /** 索引声明的版本 */
+    readonly version?: string;
+    /** 项目主页 */
+    readonly homepage?: string;
+    /** 分类标签 */
+    readonly tags: readonly string[];
+    /** 是否为官方维护 */
+    readonly official: boolean;
+    /** 要求的最低内核版本 */
+    readonly minCore?: string;
+    /** 安装来源 */
+    readonly install: MarketInstallSpec;
+    /** 该条目来自哪个索引地址 */
+    readonly source: string;
+}
+/** 附带本地安装状态的条目 */
+export interface MarketListing extends MarketEntry {
+    /** 插件目录下是否已存在同名目录 */
+    readonly installed: boolean;
+}
+/** 一次索引获取的结果 */
+export interface MarketSourceResult {
+    /** 索引地址 */
+    readonly url: string;
+    /** 是否取到并解析成功 */
+    readonly ok: boolean;
+    /** 失败原因 */
+    readonly error?: string;
+    /** 该索引贡献的条目数 */
+    readonly count: number;
+}
+/** 索引快照 */
+export interface MarketSnapshot {
+    /** 获取时间戳 */
+    readonly fetchedAt: number;
+    /** 是否来自缓存而非本次网络请求 */
+    readonly cached: boolean;
+    /** 逐个索引的获取结果 */
+    readonly sources: readonly MarketSourceResult[];
+    /** 合并去重后的条目，按名称排序 */
+    readonly plugins: readonly MarketListing[];
+}
+/**
+ * 一次安装的取源方式
+ *
+ * `pull` 是更新独有的一种：目录已是一个 git 仓库，就地拉取而非重新下载。
+ * 与 `git` 分开记录，因为两者对使用者的可见后果不同 —— `pull` 保住了
+ * `node_modules` 与目录内的其他文件，`git` 是一份全新的目录。
+ */
+export type InstallVia = MarketInstallSpec["type"] | "pull";
+/** 一次安装的结果 */
+export interface InstallResult {
+    /** 插件名 */
+    readonly name: string;
+    /** 安装目录 */
+    readonly dir: string;
+    /** 取源方式 */
+    readonly via: InstallVia;
+    /** package.json 中声明的版本；无 package.json 时为索引声明的版本 */
+    readonly version: string;
+    /** 是否声明了运行时依赖且尚未安装 */
+    readonly needsDependencies: boolean;
+    /**
+     * 就地拉取时的旧版本号，仅 `via` 为 `pull` 时存在
+     *
+     * 供面板显示「1.0.0 → 1.1.0」。重新安装那条路上没有它：旧目录已被删除，
+     * 而在删除之前去读一遍它的 package.json 只为显示一个数字，不值得多一次失败点。
+     */
+    readonly fromVersion?: string;
+    /**
+     * 就地拉取时是否确实有新提交
+     *
+     * `false` 表示已是最新。面板据此说「已是最新版本」而非「已更新」——
+     * 后者会让使用者以为拉到了东西，转而去找那个并不存在的变化。
+     */
+    readonly changed?: boolean;
+    /**
+     * 此后的更新会走哪条路
+     *
+     * 由 `via` 纯推导：git 克隆与就地拉取都留下 `.git`，故此后可 `fetch` + `reset`，
+     * 那条路**保住包目录里的 `node_modules`**；归档装出来的目录没有 `.git`，每次更新都是
+     * 整目录重下重装，依赖跟着重装一遍。
+     *
+     * 这个差别在装完的那一刻不可见，却决定此后每一次更新的代价（依赖动辄几十兆），
+     * 故在装完就说出来 —— 而不是等使用者问「为什么我的更新比别人慢」。
+     */
+    readonly updatable: "pull" | "reinstall";
+}
+/** 市场行为的可配置项，由内核配置提供 */
+export interface MarketSettings {
+    /** 索引地址列表，靠前者优先 */
+    readonly sources: readonly string[];
+    /** 镜像前缀，为空表示直连 */
+    readonly mirror: string;
+    /** 索引缓存生存期毫秒 */
+    readonly cacheTtl: number;
+    /** 单次网络请求超时毫秒 */
+    readonly timeout: number;
+}
+/**
+ * 执行一次 git 命令的函数形态
+ *
+ * 抽成类型是为了让测试替换它。就地拉取那条路的正确性几乎全在**命令序列**上 ——
+ * `stash` 必须先于 `reset --hard`（次序反了就是数据丢失）、必须是 `fetch` 而非
+ * `pull`、`fetch` 的地址必须每次现算。这些都不是真网络测得出来的：一次真实的拉取
+ * 只告诉你"最后目录对了"，而上述任一条错掉都仍可能得到一个对的目录，直到某个
+ * 使用者的改动被无声吃掉。故留这道缝，用例据此逐条钉住实际下发的参数。
+ * @param args 命令参数
+ * @param cwd 工作目录
+ * @param timeout 超时毫秒
+ * @returns 标准输出
+ */
+export type GitRunner = (args: readonly string[], cwd: string, timeout: number) => Promise<string>;
+/** 构造插件市场所需的依赖 */
+export interface MarketDeps {
+    /** HTTP 客户端 */
+    readonly http: HttpClient;
+    /** 日志器 */
+    readonly logger: Logger;
+    /** 插件安装目录 */
+    readonly pluginsDir: string;
+    /** 临时目录，下载与解包在此完成 */
+    readonly tempDir: string;
+    /** 索引缓存文件路径 */
+    readonly cacheFile: string;
+    /** 读取当前配置 */
+    readonly settings: () => MarketSettings;
+    /** 当前内核版本，用于 `minCore` 判定 */
+    readonly coreVersion: string;
+    /** 执行 git 命令，缺省调用本机的 git */
+    readonly git?: GitRunner;
+}
+/**
+ * 校验插件名
+ *
+ * 该校验先于路径拼接执行。路径越界校验能挡住 `../`，但挡不住 `.git`、`node_modules`
+ * 这类落在目录之内却会破坏运行环境的名称，因此此处采用白名单而非黑名单。
+ * @param name 待校验的名称
+ * @returns 名称本身
+ * @throws 名称为空、含非法字符或为保留名时
+ */
+export declare function assertPluginName(name: string): string;
+/**
+ * 比较两个版本号
+ *
+ * 仅比较点分数值段，忽略预发布标识。内核版本与 `minCore` 都由本项目自己产出，
+ * 不需要完整的 semver 语义，引入依赖的收益低于其体积。
+ * @param a 左操作数
+ * @param b 右操作数
+ * @returns a 大于 b 时为正，小于时为负，相等时为零
+ */
+export declare function compareVersion(a: string, b: string): number;
+/**
+ * 对白名单主机的地址应用镜像前缀
+ *
+ * 只处理白名单内的主机：镜像站点通常只代理 GitHub，把任意地址都套上前缀会让
+ * 自建源无法访问，且更难排查 —— 用户看到的会是镜像站的 404 而不是自己的地址写错。
+ * @param url 原始地址
+ * @param mirror 镜像前缀，空串表示直连
+ * @returns 应用镜像后的地址
+ */
+export declare function applyMirror(url: string, mirror: string): string;
+/**
+ * 把 git 仓库地址换算为 codeload 归档地址
+ *
+ * git 不可用时的退路。仅识别 GitHub：其归档地址可由仓库地址推导，而通用的
+ * git 服务端不存在统一的归档端点，推断得出的地址仅会导致一次无谓的失败请求。
+ * @param url 仓库地址
+ * @param branch 分支名，缺省取 HEAD
+ * @returns 归档地址；无法推导时 undefined
+ */
+export declare function tarballFromGit(url: string, branch?: string): string | undefined;
+/**
+ * 解析一份索引文档
+ *
+ * 接受两种形状：`{ plugins: [...] }` 与顶层直接是数组。后者便于用户把一个手写的
+ * 数组挂到静态文件服务上作为私有源。
+ * @param raw 已解析的 JSON
+ * @param source 索引地址
+ * @returns 合法条目列表
+ * @throws 文档既不是数组也不含 `plugins` 数组时
+ */
+export declare function parseIndex(raw: unknown, source: string): MarketEntry[];
+/**
+ * 插件市场
+ *
+ * 索引缓存同时驻留内存与磁盘：内存缓存服务于同一次运行内的反复浏览，磁盘缓存
+ * 服务于重启后的首次打开 —— 面板在无网络时也应当能列出上次看到的插件，
+ * 而不是显示一个空列表。
+ */
+export declare class PluginMarket {
+    #private;
+    /**
+     * @param deps 依赖
+     */
+    constructor(deps: MarketDeps);
+    /**
+     * 列出市场中的插件
+     *
+     * 缓存未过期时不发起网络请求。安装状态每次都重新读取文件系统：用户可能在面板
+     * 之外手动删掉了插件目录，沿用缓存里的状态会让"卸载"按钮对着一个不存在的目录。
+     * @param force 忽略缓存，强制重新获取
+     * @returns 索引快照
+     */
+    list(force?: boolean): Promise<MarketSnapshot>;
+    /**
+     * 按名称取一个条目
+     * @param name 插件名
+     * @returns 条目；索引中没有时 undefined
+     */
+    entry(name: string): Promise<MarketEntry | undefined>;
+    /**
+     * 安装一个插件
+     *
+     * 全过程在临时目录内完成，仅在校验通过后才移入插件目录，因此失败时插件目录
+     * 保持原状。安装完成后不加载插件：加载时机由调用方决定，面板据返回值提示用户
+     * 是否需要先安装依赖。
+     * @param name 插件名
+     * @param opts 可选参数
+     * @param opts.replace 目标已存在时先删除再安装
+     * @returns 安装结果
+     * @throws 名称不合法、索引中无此插件、内核版本不满足、目标已存在或取源失败时
+     */
+    install(name: string, opts?: {
+        replace?: boolean;
+    }): Promise<InstallResult>;
+    /**
+     * 卸载一个插件
+     *
+     * 只删除插件目录。配置文件与数据库另行存放，保留它们使得重新安装后原有配置仍然有效。
+     * @param name 插件名
+     * @returns 是否确实删除了目录
+     * @throws 名称不合法时
+     */
+    remove(name: string): Promise<boolean>;
+    /**
+     * 更新一个插件：目录已是 git 仓库时就地拉取，否则退回重新安装
+     * @param name 插件名
+     * @returns 安装结果
+     * @throws 与 `install` 相同；就地拉取失败时抛出 git 的错误
+     */
+    update(name: string): Promise<InstallResult>;
+}
+//# sourceMappingURL=market.d.ts.map

package/dist/plugin/market.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"market.d.ts","sourceRoot":"","sources":["../../src/plugin/market.ts"],"names":[],"mappings":"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"}