@yunzai-ng/core 0.1.1 → 0.3.0

package/src/http/client.test.ts

@@ -15,7 +15,7 @@ import { readFile, rm } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest"
-import { AbortError } from "../util/defer.js"
+import { AbortError, sleep } from "../util/defer.js"
 import { HttpError, createHttpClient, sanitizeHeaders, sanitizeUrl, type ManagedHttpClient } from "./client.js"
 
 /** 服务器实例 */
@@ -566,3 +566,77 @@ describe("脱敏", () => {
     expect(err.url).not.toContain("ABCDEFGHIJKLMNOP")
   })
 })
+
+describe("close 不被在途请求拖住", () => {
+  // 用 3 秒而非线上那个 15 秒：被测的是「close 不等在途请求」，请求超时具体多长与此无关，
+  // 而用例本身要等它最终落地（见下），15 秒会让这一个用例占满 CI 的耐心
+  it(
+    "在途请求远未超时，close 仍在宽限内返回",
+    async () => {
+      const http = makeClient()
+      // 服务端永不响应。undici 的 close() 是优雅关闭，会一直等在途请求跑完 —— 若不掐断，
+      // 停机就要陪着这个请求等满它的超时（国内网络下拉 GitHub 索引正是此情形）
+      const pending = http.get(`${base}/slow`, { timeout: 3000 })
+      // 等 socket 真的建立起来，否则关的是一个还没有在途请求的空池子，用例就测不到东西
+      await sleep(80)
+
+      const started = Date.now()
+      await http.close()
+      const spent = Date.now() - started
+
+      // 宽限 500ms，留足余量判定；关键是它远小于那个 3 秒
+      expect(spent).toBeLessThan(1500)
+
+      // destroy() 释放的是连接池，它并不代拒那个已经发出的 Promise —— 后者仍按自己的超时落地。
+      // 此处等它结束只为不把一个悬空的 Promise 留给下一个用例，不是在断言时序
+      await expect(pending).rejects.toThrow()
+    },
+    15_000
+  )
+})
+
+describe("默认信号", () => {
+  it("extend 带的信号一触发，经它发出的请求随之中止", async () => {
+    const http = makeClient()
+    const abort = new AbortController()
+    // 插件上下文正是这样拿到自己的 http：extend({ signal: 卸载信号 })
+    const scoped = http.extend({ signal: abort.signal })
+    const pending = scoped.get(`${base}/slow`, { timeout: 5000 })
+    setTimeout(() => abort.abort(), 30)
+
+    await expect(pending).rejects.toBeInstanceOf(AbortError)
+  })
+
+  it("默认信号与单次请求的信号是并集，任一触发即中止", async () => {
+    const http = makeClient()
+    const outer = new AbortController()
+    const scoped = http.extend({ signal: outer.signal })
+    const inner = new AbortController()
+    // 只触发单次请求那一个：合并不能把调用方自己的信号吃掉
+    const pending = scoped.get(`${base}/slow`, { signal: inner.signal, timeout: 5000 })
+    setTimeout(() => inner.abort(), 30)
+
+    await expect(pending).rejects.toBeInstanceOf(AbortError)
+  })
+
+  it("默认信号已经中止时，请求不再发出", async () => {
+    const http = makeClient()
+    const abort = new AbortController()
+    abort.abort()
+    const scoped = http.extend({ signal: abort.signal })
+
+    // 插件已卸载之后才被调用的代码路径：不该再打出一个注定没人接收的请求
+    await expect(scoped.get(`${base}/json`)).rejects.toBeInstanceOf(AbortError)
+  })
+
+  it("根客户端不受派生客户端的信号影响", async () => {
+    const http = makeClient()
+    const abort = new AbortController()
+    const scoped = http.extend({ signal: abort.signal })
+    abort.abort()
+
+    // 一个插件被卸载不能让内核自己的请求跟着废掉 —— 两者共享连接池，但信号必须各自独立
+    await expect(scoped.get(`${base}/json`)).rejects.toBeInstanceOf(AbortError)
+    await expect(http.get(`${base}/json`)).resolves.toMatchObject({ ok: true })
+  })
+})

package/src/http/client.ts

@@ -53,6 +53,13 @@ const RETRY_STATUSES: readonly number[] = [408, 429, 500, 502, 503, 504]
 /** 重试等待的上限（毫秒）：`Retry-After` 说等一小时也不真等 */
 const MAX_RETRY_DELAY = 30_000
 
+/**
+ * `close()` 等待在途请求的宽限（毫秒）
+ *
+ * 取一个小值：够正在收尾的响应写完，又不至于让使用者在停机时干等。
+ */
+const CLOSE_GRACE_MS = 500
+
 /** 查询串里需要打码的键（小写比对） */
 const SECRET_QUERY_KEYS: readonly string[] = [
   "authkey",
@@ -208,6 +215,22 @@ export function sanitizeHeaders(headers: Record<string, string>): Record<string,
   return safe
 }
 
+/**
+ * 合并两个中止信号
+ *
+ * 用于把「客户端默认信号」（如插件的卸载信号）与「单次请求的信号」并成一个：
+ * 任一触发即中止。两者都缺省时返回 undefined，此时不给 undici 传 signal。
+ * @param a 一个信号
+ * @param b 另一个信号
+ * @returns 合并后的信号；都没有时 undefined
+ */
+function mergeSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined {
+  const list = [a, b].filter((s): s is AbortSignal => s !== undefined)
+  if (list.length === 0) return undefined
+  if (list.length === 1) return list[0]
+  return AbortSignal.any(list)
+}
+
 /**
  * 归一化重试选项
  * @param input 数字（次数）或完整选项
@@ -530,7 +553,7 @@ export function createHttpClient(opts: HttpClientOptions = {}): ManagedHttpClien
         proxy: proxyChoice,
         redirections: follow ? MAX_REDIRECTIONS : 0,
         throwOnError: options.throwOnError ?? true,
-        signal: options.signal
+        signal: mergeSignals(defaults.signal, options.signal)
       }
     }
 
@@ -758,9 +781,23 @@ export function createHttpClient(opts: HttpClientOptions = {}): ManagedHttpClien
       close: async (): Promise<void> => {
         closed = true
         dispatchers.clear()
-        const closing = [...agents.values()].map(agent => agent.close().catch(() => undefined))
+        const pool = [...agents.values()]
         agents.clear()
-        await Promise.all(closing)
+
+        // 先给一小段宽限让正在收尾的请求写完，到点未完的一律掐断。
+        // undici 的 close() 是优雅关闭 —— 它会一直等在途请求跑完，于是一个 15 秒超时的
+        // 请求能把停机拖满 15 秒。停机走到这一步时插件已卸载、服务器已关闭，还在途的
+        // 必然是没人接收结果的孤儿请求，等它们没有意义。
+        const graceful = Promise.all(pool.map(agent => agent.close().catch(() => undefined)))
+        const timer = new Promise<"timeout">(res => {
+          const t = setTimeout(() => res("timeout"), CLOSE_GRACE_MS)
+          // unref：这个定时器自己不该成为进程退不出的原因
+          t.unref()
+        })
+        if ((await Promise.race([graceful.then(() => "done" as const), timer])) === "timeout") {
+          logger?.debug(`连接池未在 ${CLOSE_GRACE_MS}ms 内关闭，中止在途请求`)
+          await Promise.all(pool.map(agent => agent.destroy().catch(() => undefined)))
+        }
       }
     }
     return client

package/src/index.ts

@@ -29,6 +29,7 @@ export * from "./plugin/events.js"
 export * from "./plugin/services.js"
 export * from "./plugin/discover.js"
 export * from "./plugin/market.js"
+export * from "./plugin/pm.js"
 export * from "./plugin/tar.js"
 
 /* ────────────────────────────── 消息 ────────────────────────────── */

package/src/platform/paths.test.ts

@@ -0,0 +1,166 @@
+/**
+ * 模块职责：主目录探测顺序的测试
+ * 依赖方向：测试文件，依赖 platform/paths.ts
+ * 生命周期：每个用例一个临时目录，用后即弃
+ * 注意事项：本文件固定的是「数据放在哪里」这一条 —— 它错了的表现不是报错，而是
+ *          使用者的配置、账号与历史记录**看起来凭空消失**（实则仍在旧位置）。
+ *          因此这里既覆盖「新装落在当前目录」，也覆盖「既有安装不被静默搬家」。
+ *
+ *          用 `process.chdir` 而非注入一个 cwd 参数：被测对象正是「读取进程工作目录」
+ *          这一行为，参数化会把它测成一个纯函数，那样恰好绕过了要测的东西。
+ *          vitest 的 forks 池令每个测试文件独占一个进程，chdir 不会波及其他文件。
+ */
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { legacyInstance, resolvePaths } from "./paths.js"
+
+/** 进入用例前的工作目录与环境变量，用后还原 */
+let origin: string
+let env: NodeJS.ProcessEnv
+/** 本用例的临时根目录 */
+let base: string
+
+/**
+ * 推出 `defaultHome()` 在本平台会给出的位置
+ *
+ * 仅 Windows 与 Linux 可经环境变量改写；macOS 固定在 `~/Library`，无从在测试中挪动，
+ * 故相应用例在该平台上跳过。
+ * @param root 充当 `LOCALAPPDATA` / `XDG_DATA_HOME` 的目录
+ * @returns 系统默认位置；本平台无法改写时 undefined
+ */
+function legacyHomeFor(root: string): string | undefined {
+  if (process.platform === "win32") return join(root, "YunzaiNG")
+  if (process.platform === "linux") return join(root, "yunzai-ng")
+  return undefined
+}
+
+beforeEach(async () => {
+  origin = process.cwd()
+  env = { ...process.env }
+  base = await mkdtemp(join(tmpdir(), "yzng-paths-"))
+  // 三者都会参与探测，逐一清掉，否则用例会读到开发机上真实的取值
+  delete process.env["YZNG_HOME"]
+  delete process.env["LOCALAPPDATA"]
+  delete process.env["XDG_DATA_HOME"]
+})
+
+afterEach(() => {
+  process.chdir(origin)
+  process.env = env
+})
+
+describe("主目录探测", () => {
+  it("什么都不给时落在当前目录", async () => {
+    const dir = join(base, "新装")
+    await mkdir(dir)
+    process.chdir(dir)
+
+    // resolve 而非直接比较：macOS 的 /var 是 /private/var 的符号链接，
+    // mkdtemp 给出前者而 cwd 给出后者
+    expect(resolvePaths().home).toBe(resolve(process.cwd()))
+    expect(resolvePaths().config).toBe(join(resolve(process.cwd()), "config"))
+  })
+
+  it("显式参数为相对路径时按当前目录解析", async () => {
+    process.chdir(base)
+    const got = resolvePaths({ home: "./实例甲" }).home
+
+    expect(got).toBe(join(resolve(base), "实例甲"))
+  })
+
+  it("YZNG_HOME 压过当前目录", async () => {
+    const other = join(base, "另一处")
+    await mkdir(other)
+    process.chdir(base)
+    process.env["YZNG_HOME"] = other
+
+    expect(resolvePaths().home).toBe(resolve(other))
+  })
+
+  it("显式参数压过 YZNG_HOME", async () => {
+    const a = join(base, "参数")
+    const b = join(base, "环境变量")
+    await mkdir(a)
+    await mkdir(b)
+    process.chdir(base)
+    process.env["YZNG_HOME"] = b
+
+    expect(resolvePaths({ home: a }).home).toBe(resolve(a))
+  })
+
+  it("便携标记压过当前目录", async () => {
+    const install = join(base, "便携根")
+    // runtime 传 <install>/node_modules/@yunzai-ng/core，与真实安装的层级一致：
+    // findPortableRoot 自该处上溯三级才回到 install
+    const runtime = join(install, "node_modules", "@yunzai-ng", "core")
+    await mkdir(runtime, { recursive: true })
+    await writeFile(join(install, ".portable"), "")
+    const cwd = join(base, "别处")
+    await mkdir(cwd)
+    process.chdir(cwd)
+
+    expect(resolvePaths({ runtime }).home).toBe(resolve(install))
+  })
+})
+
+describe("旧默认位置上的实例", () => {
+  /** 在 `dir` 下造出一个看起来已在用的实例 */
+  const makeInstance = async (dir: string): Promise<void> => {
+    await mkdir(join(dir, "config"), { recursive: true })
+    await writeFile(join(dir, "config", "core.yaml"), "server:\n  port: 2536\n")
+  }
+
+  /**
+   * 把系统默认位置指到临时目录下
+   * @returns 系统默认位置；本平台无法改写时 undefined
+   */
+  const pointLegacyAt = (): string | undefined => {
+    const root = join(base, "系统默认位置")
+    const legacy = legacyHomeFor(root)
+    if (legacy === undefined) return undefined
+    if (process.platform === "win32") process.env["LOCALAPPDATA"] = root
+    else process.env["XDG_DATA_HOME"] = root
+    return legacy
+  }
+
+  it.skipIf(legacyHomeFor("x") === undefined)("旧位置有实例也不影响主目录 —— 不做静默回落", async () => {
+    const legacy = pointLegacyAt()
+    if (legacy === undefined) return
+    await makeInstance(legacy)
+    const cwd = join(base, "空目录")
+    await mkdir(cwd)
+    process.chdir(cwd)
+
+    // 回落会让「默认在当前目录」在任何装过旧版的机器上都不成立
+    expect(resolvePaths().home).toBe(resolve(cwd))
+  })
+
+  it.skipIf(legacyHomeFor("x") === undefined)("legacyInstance 报出旧实例，供 CLI 提示", async () => {
+    const legacy = pointLegacyAt()
+    if (legacy === undefined) return
+    await makeInstance(legacy)
+    const cwd = join(base, "新家")
+    await mkdir(cwd)
+
+    expect(legacyInstance(cwd)).toBe(legacy)
+  })
+
+  it.skipIf(legacyHomeFor("x") === undefined)("旧位置没有实例时不提示", async () => {
+    const legacy = pointLegacyAt()
+    if (legacy === undefined) return
+    // 目录存在但没有 config/：这是"随手建过一个空目录"，不是一个实例
+    await mkdir(legacy, { recursive: true })
+
+    expect(legacyInstance(join(base, "新家"))).toBeUndefined()
+  })
+
+  it.skipIf(legacyHomeFor("x") === undefined)("本次用的就是旧位置时不提示 —— 没有可搬的家", async () => {
+    const legacy = pointLegacyAt()
+    if (legacy === undefined) return
+    await makeInstance(legacy)
+
+    expect(legacyInstance(legacy)).toBeUndefined()
+  })
+})

package/src/platform/paths.ts

@@ -2,13 +2,18 @@
  * 模块职责：确定并创建运行时目录布局
  * 依赖方向：依赖 util/fs、platform/detect
  * 生命周期：启动时解析一次，之后只读
- * 注意事项：全程不使用 `process.cwd()` —— 以 Windows 服务、开机自启或 pm2 启动时
- *          工作目录并非项目目录。启动时把八个目录一次性定死成绝对路径，
- *          其余模块只准通过 `app.paths` 取。
+ * 注意事项：优先级：显式参数 > `YZNG_HOME` > 便携模式标记 > 当前目录。
+ *          启动时把八个目录一次性定死成绝对路径，其余模块只准通过 `app.paths` 取。
  *
- *          优先级：显式参数 > `YZNG_HOME` 环境变量 > 便携模式标记 > 系统默认位置。
- *          便携模式（安装目录下有 `.portable` 文件）让 ZIP 解压即用、
- *          换机拷走整个文件夹就能迁移 —— Windows 用户最常见的诉求。
+ *          **默认落在当前目录**：解压或克隆到一个文件夹、在其中 `yzng init`，数据就在
+ *          眼前，拷走整个文件夹即完成迁移。代价是本模块必须读 `process.cwd()`，而以
+ *          Windows 服务、开机自启或 pm2 启动时工作目录并非项目目录 —— 那些场景必须
+ *          显式给出 `YZNG_HOME` 或启动器的工作目录，否则数据会落在启动器所在之处。
+ *
+ *          0.1.1 及更早的默认位置是系统目录（Windows 的 `%LOCALAPPDATA%\YunzaiNG` 等）。
+ *          此处**不**为其保留静默回落 —— 那会使「默认在当前目录」在任何装过旧版的机器上
+ *          都不成立。改由 {@link legacyInstance} 把旧实例报给 CLI 显式提示：换目录应当是
+ *          使用者看得见的一步，而不是内核悄悄替他挑一个。
  */
 import { homedir } from "node:os"
 import { dirname, isAbsolute, join, resolve } from "node:path"
@@ -63,6 +68,8 @@ function findPortableRoot(runtimeDir: string): string | undefined {
 
 /**
  * 系统默认的数据根目录
+ *
+ * 已不再是缺省取值，仅由 {@link legacyInstance} 用于查找旧实例，见文件头第 3 条。
  * @returns 绝对路径
  */
 function defaultHome(): string {
@@ -85,6 +92,44 @@ function defaultHome(): string {
   return join(home, APP_DIR_NAME_UNIX)
 }
 
+/**
+ * 判断一个目录里是否已有实例
+ *
+ * 以 `config/` 是否存在为准：`ensurePaths` 建的七个目录中只有它必定装着文件
+ * （`ConfigStore` 会把缺省配置落盘），而空的 `data/`、`logs/` 无从区分
+ * 「一个实例」与「随手建的空目录」。
+ * @param dir 待判断的目录
+ * @returns 是否已有实例
+ */
+function hasInstance(dir: string): boolean {
+  return existsSync(join(dir, "config"))
+}
+
+/**
+ * 未显式指定、也无便携标记时的主目录
+ *
+ * 见文件头第 2、3 条。
+ * @returns 绝对路径
+ */
+function autoHome(): string {
+  return process.cwd()
+}
+
+/**
+ * 0.1.1 及更早的默认位置上是否还留着一个实例
+ *
+ * 供 CLI 提示使用：默认位置自 0.2.0 起改为当前目录，装过旧版的机器上那个实例仍在原处，
+ * 而使用者多半以为「配置全没了」。内核只负责报出位置，是否搬家由使用者决定 ——
+ * 自动迁移会在两个目录都有内容时无从判断该以谁为准。
+ * @param home 本次实际使用的主目录
+ * @returns 旧实例所在目录；不存在、或恰好就是本次所用的目录时 undefined
+ */
+export function legacyInstance(home: string): string | undefined {
+  const legacy = defaultHome()
+  if (resolve(legacy) === resolve(home)) return undefined
+  return hasInstance(legacy) ? legacy : undefined
+}
+
 /**
  * 解析目录布局
  *
@@ -97,7 +142,7 @@ export function resolvePaths(opts: ResolvePathsOptions = {}): RuntimePaths {
   const runtime = opts.runtime ? resolve(opts.runtime) : detectRuntimeDir()
 
   const explicit = opts.home ?? process.env.YZNG_HOME
-  const home = explicit ? resolve(process.cwd(), explicit) : (findPortableRoot(runtime) ?? defaultHome())
+  const home = explicit ? resolve(process.cwd(), explicit) : (findPortableRoot(runtime) ?? autoHome())
 
   return Object.freeze({
     home,

package/src/plugin/context.test.ts

@@ -19,7 +19,7 @@ import type {
 } from "@yunzai-ng/types"
 import { createEventBus } from "./events.js"
 import { createServiceRegistry } from "./services.js"
-import { createPluginContext } from "./context.js"
+import { createPluginContext, splitRenderArgs } from "./context.js"
 import { DisposalRegistry } from "../util/dispose.js"
 import { fakeAppView, fakeHttp, fakeLogger, recordingHooks } from "../testing/fake.js"
 
@@ -318,6 +318,34 @@ describe("ctx.render", () => {
 
     await expect(ctx.render("t")).rejects.toThrow(/没有产出图片/)
   })
+
+  it("页面声明的 tailwind 传到渲染请求上", async () => {
+    const { ctx, recorded } = setup()
+    await ctx.render({ name: "card", html: "<html></html>", tailwind: true })
+    expect(recorded.renders[0]).toMatchObject({ template: "card", html: "<html></html>", tailwind: true })
+  })
+})
+
+describe("splitRenderArgs", () => {
+  it("字符串通路不带 html 与 tailwind", () => {
+    expect(splitRenderArgs("t", { uid: 1 })).toEqual({ template: "t", data: { uid: 1 }, opts: {} })
+  })
+
+  it("页面未声明 tailwind 时不写入该键", () => {
+    // 显式的 undefined 会盖掉渲染器一侧的缺省判定，故必须是"键不存在"而非"值为 undefined"
+    const call = splitRenderArgs({ name: "p", html: "<i>" })
+    expect("tailwind" in call.opts).toBe(false)
+  })
+
+  it("页面声明 false 时同样传下去", () => {
+    // false 是一次明确的"不要编译"，不可与未声明混为一谈
+    expect(splitRenderArgs({ name: "p", html: "<i>", tailwind: false }).opts).toEqual({ tailwind: false })
+  })
+
+  it("调用点覆盖页面声明", () => {
+    const call = splitRenderArgs({ name: "p", html: "<i>", tailwind: true }, { tailwind: false })
+    expect(call.opts).toEqual({ tailwind: false })
+  })
 })
 
 describe("ctx.sql", () => {

package/src/plugin/context.ts

@@ -276,6 +276,9 @@ export interface RenderCall {
  * `render()` 有两种形态：`render(page, opts)` 与 `render(template, data, opts)`。
  * 以第一参是否为字符串判别 —— `RenderablePage` 是对象，二者不可能混淆。
  * 判别只做这一处，两个调用点（`ctx.render` 与 `e.render`）共用同一份语义。
+ *
+ * 页面上的 `tailwind` 声明在此并入选项，且**调用点显式给出者优先**：声明是模板的常态，
+ * 而调用点是对某一次渲染的临时覆盖，后者压过前者才合乎「越局部越优先」。
  * @param first 页面或模板相对路径
  * @param second 模板数据（字符串通路）或渲染选项（TSX 通路）
  * @param third 渲染选项（字符串通路）
@@ -289,7 +292,15 @@ export function splitRenderArgs(
   if (typeof first === "string") {
     return { template: first, data: (second as Record<string, unknown> | undefined) ?? {}, opts: third ?? {} }
   }
-  return { template: first.name, data: {}, html: first.html, opts: (second as RenderOptions | undefined) ?? {} }
+  const given = (second as RenderOptions | undefined) ?? {}
+  return {
+    template: first.name,
+    data: {},
+    html: first.html,
+    // 展开顺序即优先级：页面声明在前，调用点在后覆盖之。
+    // 页面未声明时不写入该键 —— 显式的 undefined 会盖掉渲染器一侧的缺省判定
+    opts: first.tailwind === undefined ? given : { tailwind: first.tailwind, ...given }
+  }
 }
 
 /**
@@ -346,7 +357,12 @@ class Context implements PluginContext<unknown> {
     this.kv = deps.kv
     this.config = deps.config
     this.app = deps.app
-    this.http = deps.http
+    // 把卸载信号并进 HTTP 客户端的默认值：插件卸载后它发出的请求随即中止，
+    // 不必依赖每个插件作者都记得手动传 `ctx.signal`。忘记传就漏一个，
+    // 而漏掉的表现是「插件已卸载，它的请求还在跑」——
+    // 停机时那些孤儿请求还会把关闭连接池的一步拖满整个超时。
+    // extend() 与根客户端共享连接池，只是多一层默认值，没有额外开销。
+    this.http = deps.http.extend({ signal: deps.signal })
     this.signal = deps.signal
   }