@yunzai-ng/core 0.1.1 → 0.3.0

package/src/plugin/pm.ts

@@ -0,0 +1,163 @@
+/**
+ * 模块职责：在一个插件目录里执行包管理器 —— 装依赖与跑 npm script
+ * 依赖方向：只依赖 node 内置模块；不认识市场、不认识插件宿主
+ * 生命周期：无状态
+ * 注意事项：**脚本名是要拼进命令行的，故必须先过白名单。** Windows 上 node 拒绝不经 shell
+ *          执行 `.cmd`（CVE-2024-27980 之后的行为），而 `pnpm` / `npm` 在 Windows 上正是
+ *          `.cmd`，因此这里只能带 `shell` 执行；一旦带了 shell，参数就是被解释的字符串，
+ *          索引里一个 `build && curl …` 就是任意命令执行。目录路径不进命令行（走 `cwd`），
+ *          于是唯一的可变部分就是脚本名 —— 它由 {@link assertScriptName} 挡住。
+ *
+ *          **装依赖要不要带 devDependencies 由调用方决定，本模块不猜。** 从源码装的插件
+ *          要跑 `build`，而编译器（typescript）在 devDependencies 里 —— 那时 `--prod`
+ *          装出来的目录跑 `build` 必然失败，报的还是「找不到 tsc」这种离原因很远的错。
+ */
+import { execFile } from "node:child_process"
+
+/**
+ * 包管理器候选，按优先级
+ *
+ * pnpm 在前：本项目各插件的 lock 文件都是 pnpm 的，装出来的布局与插件作者测过的一致。
+ * npm 兜底，随 node 一起装。不认 yarn —— berry 缺省不建 `node_modules`（PnP 模式），
+ * 那时 `import()` 插件入口会失败，而失败原因与包管理器的关系很难看出来。
+ */
+export const PACKAGE_MANAGERS: readonly string[] = ["pnpm", "npm"]
+
+/**
+ * 装依赖的超时毫秒
+ *
+ * 比任何网络请求都长：国内网络下一次冷装依赖十分钟并不罕见，而超时的后果是留下一个
+ * 装了一半的 `node_modules` —— 那比等下去更难收拾。
+ */
+export const INSTALL_TIMEOUT_MS = 15 * 60 * 1000
+
+/**
+ * 跑一个 script 的超时毫秒
+ *
+ * 与装依赖同一量级，且理由相同：`build` 只要几秒，但装后脚本可能在下载一个
+ * 上百兆的运行时（renderer-puppeteer 的 `install:browser` 拉的是 Chromium）。
+ */
+export const SCRIPT_TIMEOUT_MS = 15 * 60 * 1000
+
+/**
+ * 合法的 npm script 名
+ *
+ * 字母或数字开头，其余可含字母、数字、冒号、点、下划线与连字符 —— 冒号是为了
+ * `install:browser` 这类分段名。**刻意不含空格、引号与任何 shell 元字符**：
+ * 理由见文件头，这一条正则是那道边界本身。
+ */
+const SCRIPT_NAME_RE = /^[a-z\d][a-z\d:._-]*$/i
+
+/**
+ * 一个 script 名是否合法
+ *
+ * 与 {@link assertScriptName} 同一判据，两种形态：解析索引时要的是「不合法就丢弃这一条」，
+ * 而真要执行前要的是「不合法就抛」。共用一条正则，免得日后只改一处。
+ * @param name 待判定的名称
+ * @returns 是否合法
+ */
+export function isScriptName(name: string): boolean {
+  return SCRIPT_NAME_RE.test(name)
+}
+
+/**
+ * 校验一个 script 名
+ *
+ * 执行前的最后一道闸：即便索引解析时已筛过，`runPm` 也可能被别处直接调用。
+ * @param name 待校验的名称
+ * @returns 名称本身
+ * @throws 名称为空或含白名单之外的字符时
+ */
+export function assertScriptName(name: string): string {
+  if (!isScriptName(name)) throw new Error(`script 名不合法：${name}`)
+  return name
+}
+
+/** 一次包管理器动作 */
+export type PmTask =
+  | {
+      /** 装依赖 */
+      readonly kind: "install"
+      /** 是否连 devDependencies 一起装 */
+      readonly dev: boolean
+    }
+  | {
+      /** 跑一个 script */
+      readonly kind: "run"
+      /** script 名，须已过 {@link assertScriptName} */
+      readonly script: string
+    }
+
+/**
+ * 执行一次包管理器动作的函数形态
+ *
+ * 抽成类型是为了让测试替换它。这条路的正确性几乎全在**下发了什么** —— 要不要带
+ * devDependencies、跑的是哪个 script、失败之后还继不继续 —— 而真实的包管理器
+ * 只能告诉你「最后目录里有 node_modules」，上述任一条错掉同样可能得到一个看着
+ * 对的目录，直到某个插件在加载时报出一条与原因无关的错。故留这道缝。
+ * @param task 动作
+ * @param cwd 插件目录
+ * @param timeout 超时毫秒
+ * @returns 实际用的是哪个包管理器
+ */
+export type PmRunner = (task: PmTask, cwd: string, timeout: number) => Promise<string>
+
+/**
+ * 把一次动作译成某个包管理器的实参
+ *
+ * `--prod` / `--omit=dev` 两家的写法不同，故按包管理器分别给。
+ * @param pm 包管理器
+ * @param task 动作
+ * @returns 实参
+ */
+function argsOf(pm: string, task: PmTask): string[] {
+  if (task.kind === "run") return ["run", task.script]
+  if (task.dev) return ["install"]
+  return pm === "pnpm" ? ["install", "--prod"] : ["install", "--omit=dev"]
+}
+
+/**
+ * 依次尝试各包管理器，`MarketDeps.pm` 的缺省实现
+ *
+ * 不加 `--ignore-scripts`：插件可能依赖原生模块（sqlite、sharp），install 脚本正是它们
+ * 编译或下载预编译产物的地方，禁掉会装出一份 `import` 即报错的 `node_modules`，而报错
+ * 指向缺少 `.node` 文件，离「我禁了脚本」很远。既然已明说要装，就该装成能用的。
+ *
+ * 两家都失败时把各自的原因都带上：只报最后一个（npm 的）会让「机器上压根没有 pnpm」
+ * 与「pnpm 装到一半失败」看起来一样。
+ * @param task 动作
+ * @param cwd 插件目录
+ * @param timeout 超时毫秒
+ * @returns 实际用的是哪个包管理器
+ * @throws 全部候选都不可用或都失败时
+ */
+export const runPm: PmRunner = async (task, cwd, timeout) => {
+  if (task.kind === "run") assertScriptName(task.script)
+  const errors: string[] = []
+  for (const pm of PACKAGE_MANAGERS) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        execFile(
+          pm,
+          argsOf(pm, task),
+          {
+            cwd,
+            timeout,
+            env: { ...process.env },
+            windowsHide: true,
+            // 理由见文件头：Windows 上 pnpm/npm 是 .cmd，不经 shell 起不来
+            shell: process.platform === "win32"
+          },
+          (err, _stdout, stderr) => {
+            if (err) reject(new Error(stderr.trim() || err.message))
+            else resolve()
+          }
+        )
+      })
+      return pm
+    } catch (err) {
+      errors.push(`${pm}：${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+  throw new Error(`包管理器均不可用或执行失败 —— ${errors.join("；")}`)
+}

package/src/server/api.test.ts

@@ -123,6 +123,8 @@ interface Spies {
     install: ReturnType<typeof vi.fn>
     /** 更新 */
     update: ReturnType<typeof vi.fn>
+    /** 单独重跑装依赖与装后步骤 */
+    setup: ReturnType<typeof vi.fn>
     /** 卸载 */
     remove: ReturnType<typeof vi.fn>
   }
@@ -262,6 +264,15 @@ describe("面板 API", () => {
           version: "2.0.0",
           needsDependencies: false
         })),
+        setup: vi.fn(async (name: string) => ({
+          name,
+          dir: join(dir, "plugins", name),
+          version: "1.0.0",
+          needsDependencies: false,
+          installedDeps: true,
+          packageManager: "pnpm",
+          ranScripts: ["build"]
+        })),
         remove: vi.fn(async (name: string) => name === "demo")
       },
       accounts: {
@@ -721,12 +732,71 @@ describe("面板 API", () => {
     it("安装后默认立即加载，并把本次加载的插件名带回来", async () => {
       const res = await call("POST", "market/install", { name: "fresh" })
       expect(res.statusCode).toBe(200)
-      expect(spies.market.install).toHaveBeenCalledWith("fresh")
+      expect(spies.market.install).toHaveBeenCalledWith("fresh", { dependencies: true })
       expect(spies.plugins.loadAll).toHaveBeenCalled()
       expect(res.json().loaded).toEqual(["fresh"])
       expect(res.json().version).toBe("1.0.0")
     })
 
+    /*
+     * 缺省装依赖，这一条只能由用例固定
+     *
+     * 缺省若翻回 false，表现是「装完却跑不起来」重新成为常态，而那条「请自行执行
+     * pnpm install」的提示对着的是一个多数人不会去开的终端 —— 从接口的返回值上
+     * 看不出缺省变过，故此处钉住。
+     */
+    it("装依赖缺省为真，显式传 false 才不装", async () => {
+      await call("POST", "market/install", { name: "fresh", dependencies: false })
+      expect(spies.market.install).toHaveBeenLastCalledWith("fresh", { dependencies: false })
+
+      await call("POST", "market/demo/update", { dependencies: false })
+      expect(spies.market.update).toHaveBeenLastCalledWith("demo", { dependencies: false })
+    })
+
+    /*
+     * 装后步骤失败时不许加载
+     *
+     * `build` 挂了就没有 `dist/`，此时加载只会再报一条「找不到模块」—— 两条错误里
+     * 后一条更显眼而更没用，使用者会去查模块解析，而真正的原因在上一条里。
+     */
+    it("装后步骤失败时不加载，原因原样带回", async () => {
+      spies.market.install.mockResolvedValueOnce({
+        name: "fresh",
+        dir: join(dir, "plugins", "fresh"),
+        via: "git",
+        version: "1.0.0",
+        needsDependencies: false,
+        installedDeps: true,
+        packageManager: "pnpm",
+        ranScripts: [],
+        setupError: "build：tsc 退出码 2"
+      })
+      const res = await call("POST", "market/install", { name: "fresh" })
+      expect(res.statusCode).toBe(200)
+      expect(spies.plugins.loadAll).not.toHaveBeenCalled()
+      expect(res.json().loaded).toEqual([])
+      expect(String(res.json().setupError)).toContain("tsc 退出码 2")
+    })
+
+    it("单独重跑装依赖与编译：先卸载再跑，跑完才加载", async () => {
+      const res = await call("POST", "market/demo/setup", {})
+      expect(res.statusCode).toBe(200)
+      expect(spies.market.setup).toHaveBeenCalledWith("demo")
+      // 顺序即正确性：build 会覆盖 dist，旧模块还在内存里就会响应刚被覆盖掉的代码
+      expect(spies.plugins.unload.mock.invocationCallOrder[0]).toBeLessThan(
+        spies.market.setup.mock.invocationCallOrder[0] ?? 0
+      )
+      expect(res.json().ranScripts).toEqual(["build"])
+      expect(res.json().loaded).toEqual(["fresh"])
+    })
+
+    it("重跑装依赖失败时回 400", async () => {
+      spies.market.setup.mockRejectedValueOnce(new Error("插件目录 无名 不存在"))
+      const res = await call("POST", "market/无名/setup", {})
+      expect(res.statusCode).toBe(400)
+      expect(String(res.json().error)).toContain("不存在")
+    })
+
     it("load 为 false 时只落盘不加载", async () => {
       const res = await call("POST", "market/install", { name: "fresh", load: false })
       expect(res.statusCode).toBe(200)
@@ -747,7 +817,7 @@ describe("面板 API", () => {
       const res = await call("POST", "market/demo/update", {})
       expect(res.statusCode).toBe(200)
       expect(spies.plugins.unload).toHaveBeenCalledWith("demo")
-      expect(spies.market.update).toHaveBeenCalledWith("demo")
+      expect(spies.market.update).toHaveBeenCalledWith("demo", { dependencies: true })
       expect(res.json().unloaded).toBe(true)
       expect(res.json().version).toBe("2.0.0")
     })

package/src/server/api.ts

@@ -554,20 +554,32 @@ export function createApiRoutes(deps: ApiDeps): ApiSurface {
    * @param name 插件名
    * @param load 安装后是否立即加载
    * @param replace 目标已存在时是否覆盖
+   * @param dependencies 是否顺带装依赖并跑索引声明的装后步骤
    * @returns 安装结果，附本次加载成功的插件名
    * @throws 安装失败时以 400 结束请求
    */
   const installFromMarket = async (
     name: string,
     load: boolean,
-    replace: boolean
+    replace: boolean,
+    dependencies: boolean
   ): Promise<Record<string, unknown>> => {
     const instance = market()
     let unloaded = false
     try {
       if (replace && deps.plugins.get(name) !== undefined) unloaded = await deps.plugins.unload(name)
-      const result = replace ? await instance.update(name) : await instance.install(name)
-      const loaded = load ? [...(await deps.plugins.loadAll()).loaded] : []
+      const result = replace
+        ? await instance.update(name, { dependencies })
+        : await instance.install(name, { dependencies })
+      /*
+       * 缺依赖或装后步骤失败时不加载
+       *
+       * 两者都注定让加载失败，而报出来的错离原因很远：缺依赖报的是「找不到某个包」，
+       * 缺产物（`build` 挂了）报的是「找不到 dist/index.js」。两条错误里后一条更
+       * 显眼而更没用 —— 使用者会去查那个文件为什么不在，而真正该看的是上一条。
+       */
+      const skip = result.setupError !== undefined || result.dependencyError !== undefined || result.needsDependencies
+      const loaded = load && !skip ? [...(await deps.plugins.loadAll()).loaded] : []
       return { ...result, unloaded, loaded }
     } catch (err) {
       throw fail(400, err instanceof Error ? err.message : String(err))
@@ -580,18 +592,66 @@ export function createApiRoutes(deps: ApiDeps): ApiSurface {
 
   add("POST", "market/refresh", () => market().list(true))
 
+  /*
+   * 装依赖缺省为真
+   *
+   * 与面板商店那侧一致。缺省关掉会让「装完却跑不起来」成为常态，而那条提示（「请到
+   * 目录内自行执行 pnpm install」）对着的是一个多数人不会去开的终端。请求方仍可显式
+   * 传 false —— 离线部署、或依赖已随镜像预置好时用得上。
+   */
   add("POST", "market/install", async req => {
     requireWritable()
     const body = objectOf(req.body)
     const name = requireString(body, "name")
-    return installFromMarket(name, optionalBoolean(body, "load") ?? true, false)
+    return installFromMarket(
+      name,
+      optionalBoolean(body, "load") ?? true,
+      false,
+      optionalBoolean(body, "dependencies") ?? true
+    )
   })
 
   add("POST", "market/:name/update", async req => {
     requireWritable()
     const name = req.params.name ?? ""
     const body = req.body === undefined ? {} : objectOf(req.body)
-    return installFromMarket(name, optionalBoolean(body, "load") ?? true, true)
+    return installFromMarket(
+      name,
+      optionalBoolean(body, "load") ?? true,
+      true,
+      optionalBoolean(body, "dependencies") ?? true
+    )
+  })
+
+  /*
+   * 单独重跑装依赖与装后步骤，不重新取源
+   *
+   * 三种情形要用到：手工放进插件目录的插件（没有安装动作可挂）、装的时候这一步失败过、
+   * 以及使用者自己 `git pull` 过而产物已旧。与安装那条路共用 `PluginMarket.setup()`，
+   * 故「装什么、跑什么」只有一处定义。
+   */
+  add("POST", "market/:name/setup", async req => {
+    requireWritable()
+    const name = req.params.name ?? ""
+    const body = req.body === undefined ? {} : objectOf(req.body)
+    const load = optionalBoolean(body, "load") ?? true
+    /*
+     * 先卸载，再跑 —— 次序有意义
+     *
+     * `build` 会覆盖 `dist/`，而旧模块此刻还在内存里、它注册的命令仍在响应。跑完再卸载
+     * 意味着中间有一段时间里「磁盘上是新代码、正在响应的是旧代码」，那种不一致比一次
+     * 失败的重载难查得多。
+     */
+    const unloaded = deps.plugins.get(name) === undefined ? false : await deps.plugins.unload(name)
+    try {
+      const result = await market().setup(name)
+      // 判据与 installFromMarket 一致：缺依赖或缺产物时加载注定失败，见那里的注释
+      const skip = result.setupError !== undefined || result.needsDependencies
+      const loaded = load && !skip ? [...(await deps.plugins.loadAll()).loaded] : []
+      return { ...result, unloaded, loaded }
+    } catch (err) {
+      throw fail(400, err instanceof Error ? err.message : String(err))
+    }
   })
 
   add("DELETE", "market/:name", async req => {

package/src/server/browse.test.ts

@@ -123,16 +123,24 @@ describe("目录浏览", () => {
     }
   })
 
-  it("超过 1000 项时截断并标明", async () => {
-    await Promise.all(
-      Array.from({ length: 1005 }, (_, i) => writeFile(join(dir, `f${String(i).padStart(4, "0")}.txt`), "1"))
-    )
-    const out = await listing(dir)
-    expect(out.entries.length).toBe(1000)
-    expect(out.truncated).toBe(true)
-    // 先排序再截断，故截到的必是排序后的前 1000 项
-    expect(out.entries[0]?.name).toBe("f0000.txt")
-  })
+  // 单独给 30 秒而非用 5 秒的缺省值：这一条要建 1005 个真实文件才能触到上限，
+  // 而 MAX_ENTRIES 是模块常量、无从在测试里调小。本机上光是写文件就要 0.8~1.3 秒
+  // 且波动六成，CI runner 的磁盘更慢 —— 在 ubuntu 上曾耗时 9.5 秒而超时。
+  // 试过把写入分批（64、16 个一组）反而更慢，故仍一次性并发。
+  it(
+    "超过 1000 项时截断并标明",
+    async () => {
+      await Promise.all(
+        Array.from({ length: 1005 }, (_, i) => writeFile(join(dir, `f${String(i).padStart(4, "0")}.txt`), "1"))
+      )
+      const out = await listing(dir)
+      expect(out.entries.length).toBe(1000)
+      expect(out.truncated).toBe(true)
+      // 先排序再截断，故截到的必是排序后的前 1000 项
+      expect(out.entries[0]?.name).toBe("f0000.txt")
+    },
+    30_000
+  )
 
   it("未超上限时 truncated 为假", async () => {
     await writeFile(join(dir, "one.txt"), "1")

package/src/server/browse.ts

@@ -156,7 +156,16 @@ async function isDirEntry(dir: string, entry: Dirent, windows: boolean): Promise
 }
 
 /**
- * 排序：目录在前，同类按名称（`localeCompare` + `numeric`，故 `f2` 在 `f10` 之前）
+ * 排序用的比较器
+ *
+ * 提到模块级而非在比较函数里写 `localeCompare(name, "zh-Hans-CN", { numeric: true })`：
+ * 带 options 的 `localeCompare` 每次调用都新建一个 collator，而排序会调用它上万次
+ * （1000 项约一万次比较）。实测同一批 1005 个名字，逐次新建 21~28 ms，复用则不足 1 ms。
+ */
+const COLLATOR = new Intl.Collator("zh-Hans-CN", { numeric: true })
+
+/**
+ * 排序：目录在前，同类按名称（`numeric` 故 `f2` 在 `f10` 之前）
  *
  * **中文名排在英文名之前不是缺陷** —— CLDR 的中文规则把汉字整块提到拉丁字母之前。
  * 要改成「英文在前」得在此处显式加一层「是否以 ASCII 起头」的比较键，而不是换 locale。
@@ -166,7 +175,7 @@ async function isDirEntry(dir: string, entry: Dirent, windows: boolean): Promise
  */
 function compareEntries(a: BrowseEntry, b: BrowseEntry): number {
   if (a.dir !== b.dir) return a.dir ? -1 : 1
-  return a.name.localeCompare(b.name, "zh-Hans-CN", { numeric: true })
+  return COLLATOR.compare(a.name, b.name)
 }
 
 /**