@morehao/dsh-plugin-kit 0.2.1 → 0.3.1

package/README.md

@@ -1,12 +1,17 @@
 # @morehao/dsh-plugin-kit
 
-DeepSeek Harness（dsh）插件共用的工具包。当前提供三件事：
+DeepSeek Harness（dsh）插件共用的工具包。当前提供这些能力：
 
 - **插件自更新引擎**（`./update`）：查 npm 最新版 → 判断能不能一键更新 → 经宿主 `pluginManager` 重装自己。
 - **headless 客户端控制器**（`./update/client`）：检查/更新的状态机与单飞，UI 由各插件自己渲染。
-- **HTTP 小工具**（`./http`）：自定义头鉴权、`no-store` JSON、有上限的 JSON body。
+- **HTTP 小工具**（`./http`）：自定义头鉴权、`no-store` JSON、有上限的 JSON body，以及薄路由 dispatcher（`createRouteHandler`）。
+- **子进程执行**（`./exec`）：argv 直传（不经 shell）、环境白名单、超时/取消、输出上限，外加 `pnpm view` 版本解析。
+- **原子写**（`./fs`）：`writeFileAtomicSync` / `writeFileAtomic`，杜绝「半个文件」。
+- **JSON 状态持久化**（`./state`）：`$DSH_HOME` 解析 + `<home>/<plugin>/*.json` 读写（读 fail-open、写抛错）。
+- **GitHub 工具**（`./github`）：仓库地址规范化 + Release 正文读取（带 TTL 缓存）。
+- **插件身份**（`./meta`）：从自家 `package.json` 读 name / version / repository。
 
-设计约束：**零 `@deepseek-ai/*` 运行时依赖**，宿主能力（`pluginManager` / `profileContext`）全部由调用方注入；进程相关的策略（比如用哪个包管理器查版本）也由插件自己决定，本包不替你 spawn。
+设计约束：**零 `@deepseek-ai/*` 运行时依赖**，宿主能力（`pluginManager` / `profileContext`）全部由调用方注入。进程策略由调用方把握：`./update` 常驻能力不主动 spawn，需要 `pnpm view` 时由调用方注入 `runPnpmView`；也可直接用 `./exec`（或 `createPnpmViewRunner`，默认走 `./exec`、可注入 `exec` 替换进程策略）。
 
 ## 安装
 
@@ -107,22 +112,131 @@ await controller.apply();
 ## HTTP 小工具
 
 ```ts
-import { hasHeader, readJsonBody, sendJson } from '@morehao/dsh-plugin-kit/http';
+import { hasHeader, readJsonBody, sendJson, createRouteHandler } from '@morehao/dsh-plugin-kit/http';
 
 if (!hasHeader(request, 'x-my-plugin')) return sendJson(response, 403, { ok: false, code: 'FORBIDDEN' });
 const body = await readJsonBody(request, { maxBytes: 512 * 1024 });
 sendJson(response, 200, { ok: true });
+
+// 薄路由 dispatcher：统一 鉴权 → 剥前缀 → 读 body → 包 {ok:true} → 错误兜底。
+// 不做路由表 DSL / 错误码翻译——matchRoute 与错误码映射留在你的 dispatch / onError 里。
+const handler = createRouteHandler({
+  prefix: '/api/morehao/my-plugin',
+  header: 'x-dsh-my-plugin',
+  dispatch: async ({ method, pathname, body }) => {
+    if (method === 'GET' && pathname === '/state') return { state: getState() };
+    throw Object.assign(new Error('not found'), { code: 'NOT_FOUND' });
+  },
+  onError: (error) => ({ status: error.code === 'NOT_FOUND' ? 404 : 500, code: error.code, message: error.message }),
+});
+```
+
+## 子进程执行（`./exec`）
+
+argv 直传、不经 shell；超时/取消先 SIGTERM、宽限后 SIGKILL；输出有上限且保留尾部；`spawn` 失败**不 reject**，落到 `error` 字段。
+
+```ts
+import { spawnCollect, sanitizedEnv, collectVersionView } from '@morehao/dsh-plugin-kit/exec';
+
+const result = await spawnCollect('git', ['rev-parse', 'HEAD'], {
+  cwd: repo,
+  env: sanitizedEnv(process.env),      // 只放行 PATH/HOME/代理/证书/locale/git 身份等白名单
+  timeoutMs: 8_000,
+});
+// { code, signal, stdout, stderr, output, timedOut, aborted, durationMs, error? }
+
+// 从 `pnpm view <spec> version --json` 的输出里取版本串（单值或数组取尾；非法 → null）
+const version = collectVersionView({ code: result.code, stdout: result.stdout });
+```
+
+## 原子写（`./fs`）
+
+同目录临时文件 → fsync → rename → fsync(父目录)；Windows rename 有界重试；失败清理临时文件，原文件在 rename 前不被截断。
+
+```ts
+import { writeFileAtomicSync, writeFileAtomic } from '@morehao/dsh-plugin-kit/fs';
+
+writeFileAtomicSync('/path/state.json', `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+await writeFileAtomic('/path/state.json', content);  // 同语义异步版
+```
+
+`mode` 省略时沿用已有文件权限，新文件走 `defaultMode`（默认 `0o644`）。
+
+## JSON 状态持久化（`./state`）
+
+`$DSH_HOME` 解析 + `<home>/<plugin>/*.json` 读写。**读 fail-open**（缺失/坏 JSON/非对象 → `fallback()`，永不抛）；**写抛错**（写通常是一次事务，静默吞掉会掩盖数据丢失，需要「尽力而为」的调用方自行 try/catch）。
+
+```ts
+import { resolveDshHome, createJsonStore } from '@morehao/dsh-plugin-kit/state';
+
+const store = createJsonStore({
+  dir: `${resolveDshHome()}/my-plugin`,   // $DSH_HOME → ~/.dsh
+  file: 'state.json',
+  fallback: () => ({ lastSeenVersion: '' }), // 工厂函数，避免共享可变引用
+});
+const state = store.read();               // 坏文件也返回 fallback
+store.write({ lastSeenVersion: '0.3.0' }); // 原子写
 ```
 
+## 复用 `pnpm view` 查版本（`./update`）
+
+三仓此前各手写一遍的「读 profile → 拼 `pnpm view` → 解析 → 校验」，收敛为一个工厂：
+
+```ts
+import { createPnpmViewRunner, createPluginUpdater } from '@morehao/dsh-plugin-kit/update';
+
+const runPnpmView = createPnpmViewRunner({
+  getProfile: () => ctx.get('profileContext'),
+  // 可选：注入自定义 exec 以沿用本插件更细的进程策略；默认走 ./exec
+  // exec: myExecCapture,
+});
+const updater = createPluginUpdater({ meta, getPluginManager: () => ctx.get('pluginManager'), runPnpmView });
+```
+
+拿不到 `profile.dir` / 命令失败 / 输出非法 / 版本不是合法 semver → 返回 `null`（交由 registry 兜底）。
+
+## GitHub 工具（`./github`）
+
+仓库地址规范化 + Release 正文读取（收敛各插件重复的正则与拉取逻辑）：
+
+```ts
+import { normalizeRepositoryUrl, repoSlug, createReleaseReader } from '@morehao/dsh-plugin-kit/github';
+
+normalizeRepositoryUrl('git@github.com:o/r.git');   // → 'https://github.com/o/r'
+repoSlug('https://github.com/o/r');                  // → 'o/r'
+
+const reader = createReleaseReader({ repo: 'o/r' }); // ttlMs / failureTtlMs / timeoutMs / fetchImpl 可注入
+const info = await reader.release('1.2.3');          // { version, body, htmlUrl, name } | null
+// 拉 https://api.github.com/repos/o/r/releases/tags/v1.2.3；成功与失败都做 TTL 缓存，失败 → null（不抛）
+```
+
+本模块只依赖 `./semver`，**不 import 任何 node 内置**。
+
+## 插件身份（`./meta`）
+
+从自家 `package.json` 读出 name / version / repository（收敛三仓的 `PLUGIN_META` / `readPluginInfo`）：
+
+```ts
+import { createPluginMeta, readInstalledVersion } from '@morehao/dsh-plugin-kit/meta';
+
+const pkgUrl = new URL('../package.json', import.meta.url); // 层级由插件自己给
+const meta = createPluginMeta({ pkgUrl, defaultName: '@you/plugin' });
+// { name, version, repository?: 'https://github.com/o/r', repo: 'o/r' | null }
+
+readInstalledVersion({ pkgUrl }); // 每次重读（更新后同进程读到新值）；失败 → ''
+```
+
+只在 host 侧使用（含 `node:fs`），不被 `./update/client` 引用。
+
 ## 版本与兼容
 
 - Node `^22.20.0 || >=24.0.0`，纯 ESM。
-- `./update` 与 `./http` 走 host 侧；`./update/client` 只含状态机，不 import node 内置模块（客户端产物只允许 react）。
+- `./update`、`./http`、`./exec`、`./fs`、`./state`、`./github`、`./meta` 走 host 侧；`./update/client` 只含状态机，不 import node 内置模块（客户端产物只允许 react）。
 - 宿主服务形状按结构化类型处理（`PluginManagerLike` / `ProfileLike`），宿主版本变化不会把插件一起拖下去。
 
 ## 开发
 
 ```bash
 npm install
-npm run check   # typecheck + build + 26 条离线测试（假 fetch / 假 pluginManager，不联网、不真装）
+npm run check   # typecheck + build + 67 条离线测试（假 fetch / 假 pluginManager / 假 exec，不联网、不真装）
 ```

package/dist/exec.d.ts

@@ -0,0 +1,52 @@
+interface ExecResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    /** stdout + stderr 交错合并后的结果（同 dsh-commands 的 `output`）。 */
+    output: string;
+    timedOut: boolean;
+    aborted: boolean;
+    durationMs: number;
+    /** spawn 本身失败（ENOENT / EACCES 等）时带出；此时 `code === null` 且不 reject。 */
+    error?: Error;
+}
+/**
+ * 从 `process.env` 里挑出白名单键 + 调用方额外给的键，拼成子进程环境。
+ * 空字符串视为未设置（避免把 `KEY=` 传给子进程，部分工具会当成空值处理）。
+ */
+declare function sanitizedEnv(source?: NodeJS.ProcessEnv, extra?: Record<string, string | undefined>): Record<string, string>;
+interface ExecOptions {
+    cwd?: string;
+    /** 省略时继承 `process.env`；要清洗时先过 `sanitizedEnv` 再传进来。 */
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    /** 超时毫秒；默认 10_000。传 0 / Infinity / 非正数表示不设超时。 */
+    timeoutMs?: number;
+    /** SIGTERM 之后到 SIGKILL 的宽限；默认 2_000。 */
+    abortGraceMs?: number;
+    /** stdout 上限（保留尾部）；默认 1 MiB。 */
+    maxStdout?: number;
+    /** stderr 上限（保留尾部）；默认 1 MiB。 */
+    maxStderr?: number;
+    /** 合并 `output` 的上限（保留尾部）；默认 = maxStdout + maxStderr。 */
+    maxOutput?: number;
+    /** 写入子进程 stdin（写完即关闭）；省略则 stdin = 'ignore'。 */
+    input?: string;
+    /** 原始分片旁路（去 ANSI 由调用方决定）；回调抛错会被吞，不影响采集。 */
+    onData?: (text: string, channel: 'stdout' | 'stderr') => void;
+}
+/**
+ * 执行一次命令并收集输出。永不 reject：进程级失败落到 `error` 字段。
+ */
+declare function spawnCollect(command: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
+/**
+ * 从 `pnpm view <spec> version --json` 的 stdout 取版本字符串。
+ * - 成功：可能返回单值或数组（多版本时 pnpm 给数组），取最后一个非空字符串；
+ * - 空输出 / 非 JSON / 取不到字符串 → null。
+ *
+ * **不在这里做 semver 合法性校验**（避免 `./exec` 依赖 `./semver`），由调用方用 `parseSemver` 判定。
+ */
+declare function collectVersionView(result: Pick<ExecResult, 'code' | 'stdout'>): string | null;
+
+export { type ExecOptions, type ExecResult, collectVersionView, sanitizedEnv, spawnCollect };

package/dist/exec.js

@@ -0,0 +1,171 @@
+// src/exec.ts
+import { spawn } from "child_process";
+var ENV_KEYS = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "GIT_AUTHOR_NAME",
+  "GIT_AUTHOR_EMAIL",
+  "GIT_COMMITTER_NAME",
+  "GIT_COMMITTER_EMAIL",
+  "GIT_CONFIG_GLOBAL",
+  "GIT_SSH_COMMAND"
+];
+var PROXY_KEYS = [
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "ALL_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "all_proxy"
+];
+function sanitizedEnv(source = process.env, extra = {}) {
+  const env = {};
+  for (const key of [...ENV_KEYS, ...PROXY_KEYS]) {
+    const value = source[key];
+    if (typeof value === "string" && value !== "") env[key] = value;
+  }
+  for (const [key, value] of Object.entries(extra)) {
+    if (typeof value === "string" && value !== "") env[key] = value;
+  }
+  return env;
+}
+function keepTail(text, limit) {
+  if (!Number.isFinite(limit) || limit <= 0 || text.length <= limit) return text;
+  return text.slice(text.length - limit);
+}
+async function spawnCollect(command, args = [], options = {}) {
+  const started = Date.now();
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const abortGraceMs = options.abortGraceMs ?? 2e3;
+  const maxStdout = options.maxStdout ?? 1024 * 1024;
+  const maxStderr = options.maxStderr ?? 1024 * 1024;
+  const maxOutput = options.maxOutput ?? maxStdout + maxStderr;
+  let stdout = "";
+  let stderr = "";
+  let output = "";
+  let timedOut = false;
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        stdio: [options.input === void 0 ? "ignore" : "pipe", "pipe", "pipe"],
+        windowsHide: true
+      });
+    } catch (error) {
+      resolve(failureResult(error, started, options.signal?.aborted === true));
+      return;
+    }
+    if (options.input !== void 0) {
+      child.stdin?.on("error", () => void 0);
+      child.stdin?.end(options.input);
+    }
+    let settled = false;
+    let timer;
+    let hardKill;
+    const killTree = (signal) => {
+      try {
+        child.kill(signal);
+      } catch {
+      }
+    };
+    const softKill = () => {
+      killTree("SIGTERM");
+      hardKill = setTimeout(() => killTree("SIGKILL"), abortGraceMs);
+      hardKill.unref?.();
+    };
+    const onAbort = () => softKill();
+    const finish = (code, signal, error) => {
+      if (settled) return;
+      settled = true;
+      if (timer !== void 0) clearTimeout(timer);
+      if (hardKill !== void 0) clearTimeout(hardKill);
+      options.signal?.removeEventListener("abort", onAbort);
+      resolve({
+        code,
+        signal,
+        stdout,
+        stderr,
+        output,
+        timedOut,
+        aborted: options.signal?.aborted === true,
+        durationMs: Date.now() - started,
+        ...error === void 0 ? {} : { error }
+      });
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout = keepTail(stdout + chunk, maxStdout);
+      output = keepTail(output + chunk, maxOutput);
+      try {
+        options.onData?.(chunk, "stdout");
+      } catch {
+      }
+    });
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      stderr = keepTail(stderr + chunk, maxStderr);
+      output = keepTail(output + chunk, maxOutput);
+      try {
+        options.onData?.(chunk, "stderr");
+      } catch {
+      }
+    });
+    if (options.signal?.aborted === true) onAbort();
+    else options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        softKill();
+      }, timeoutMs);
+    }
+    child.on("error", (error) => finish(null, null, error));
+    child.on("close", (code, signalName) => finish(code, signalName));
+  });
+}
+function failureResult(error, started, aborted) {
+  const err = error instanceof Error ? error : new Error(String(error));
+  return {
+    code: null,
+    signal: null,
+    stdout: "",
+    stderr: "",
+    output: err.message,
+    timedOut: false,
+    aborted,
+    durationMs: Date.now() - started,
+    error: err
+  };
+}
+function collectVersionView(result) {
+  if (result.code !== 0) return null;
+  const text = result.stdout.trim();
+  if (text === "") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const value = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+export {
+  collectVersionView,
+  sanitizedEnv,
+  spawnCollect
+};

package/dist/fs.d.ts

@@ -0,0 +1,12 @@
+interface WriteFileAtomicOptions {
+    /** 目标权限位；省略时沿用已有文件权限，新文件用 `defaultMode`。 */
+    mode?: number;
+    /** 新文件默认权限位；已有文件仍沿用其原权限。默认 0o644。 */
+    defaultMode?: number;
+}
+/** 同步原子整文件替换（`mkdir → open('wx') → write → fsync → rename → fsync(dir)`）。 */
+declare function writeFileAtomicSync(file: string, content: string, options?: WriteFileAtomicOptions): void;
+/** 异步原子整文件替换，语义与同步版一致（`fs/promises`）。 */
+declare function writeFileAtomic(file: string, content: string, options?: WriteFileAtomicOptions): Promise<void>;
+
+export { type WriteFileAtomicOptions, writeFileAtomic, writeFileAtomicSync };

package/dist/fs.js

@@ -0,0 +1,119 @@
+// src/fs.ts
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+import { randomBytes } from "crypto";
+var WINDOWS_TRANSIENT_RENAME = /* @__PURE__ */ new Set(["EACCES", "EBUSY", "EPERM"]);
+var RENAME_RETRY_DELAYS_MS = [20, 40, 80, 160, 200, 200, 200, 200];
+function resolveMode(file, options) {
+  if (typeof options.mode === "number") return options.mode;
+  try {
+    return fs.statSync(file).mode & 511;
+  } catch {
+    return options.defaultMode ?? 420;
+  }
+}
+function tempPath(dir, base) {
+  return path.join(dir, `.${base}.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}.tmp`);
+}
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function renameWithRetrySync(from, to) {
+  if (process.platform !== "win32") {
+    fs.renameSync(from, to);
+    return;
+  }
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      fs.renameSync(from, to);
+      return;
+    } catch (error) {
+      const code = error?.code;
+      if (code === void 0 || !WINDOWS_TRANSIENT_RENAME.has(code) || attempt >= RENAME_RETRY_DELAYS_MS.length) throw error;
+      sleepSync(RENAME_RETRY_DELAYS_MS[attempt]);
+    }
+  }
+}
+function fsyncDirSync(dir) {
+  if (process.platform === "win32") return;
+  try {
+    const dirFd = fs.openSync(dir, "r");
+    try {
+      fs.fsyncSync(dirFd);
+    } finally {
+      fs.closeSync(dirFd);
+    }
+  } catch {
+  }
+}
+function writeFileAtomicSync(file, content, options = {}) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const mode = resolveMode(file, options);
+  const tmp = tempPath(dir, path.basename(file));
+  let fd = null;
+  try {
+    fd = fs.openSync(tmp, "wx", mode);
+    fs.writeFileSync(fd, content, "utf8");
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    renameWithRetrySync(tmp, file);
+    fsyncDirSync(dir);
+  } catch (error) {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+      }
+    }
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+    }
+    throw error;
+  }
+}
+async function writeFileAtomic(file, content, options = {}) {
+  const dir = path.dirname(file);
+  await fsp.mkdir(dir, { recursive: true });
+  const mode = resolveMode(file, options);
+  const tmp = tempPath(dir, path.basename(file));
+  let handle = null;
+  try {
+    handle = await fsp.open(tmp, "wx", mode);
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await fsp.rename(tmp, file);
+    if (process.platform !== "win32") {
+      try {
+        const dirFd = await fsp.open(dir, "r");
+        try {
+          await dirFd.sync();
+        } finally {
+          await dirFd.close();
+        }
+      } catch {
+      }
+    }
+  } catch (error) {
+    if (handle !== null) {
+      try {
+        await handle.close();
+      } catch {
+      }
+    }
+    try {
+      await fsp.rm(tmp, { force: true });
+    } catch {
+    }
+    throw error;
+  }
+}
+export {
+  writeFileAtomic,
+  writeFileAtomicSync
+};

package/dist/github.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `git+https://github.com/o/r.git` / `git@github.com:o/r.git` / `https://github.com/o/r`
+ * → `https://github.com/o/r`。非 GitHub / 解析失败 → undefined。
+ */
+declare function normalizeRepositoryUrl(value: unknown): string | undefined;
+/** 从仓库地址（或 `owner/repo` 短名）取 `owner/repo`；拿不到返回 null。 */
+declare function repoSlug(value: unknown): string | null;
+interface ReleaseInfo {
+    version: string;
+    body: string;
+    htmlUrl: string | null;
+    name: string | null;
+}
+interface ReleaseReaderDeps {
+    /** `owner/repo`。 */
+    repo: string;
+    fetchImpl?: typeof fetch;
+    /** 成功缓存 TTL；默认 10 分钟。 */
+    ttlMs?: number;
+    /** 失败短缓存 TTL；默认 = ttlMs（与既有实现一致，失败也缓存 10 分钟）。 */
+    failureTtlMs?: number;
+    /** 单次请求超时；默认 8s。 */
+    timeoutMs?: number;
+    now?: () => number;
+}
+interface ReleaseReader {
+    /** 拉某版本 Release 正文；无 repo / 网络 / 404 / 超时 / 非法版本 → null（不抛）。 */
+    release(version: string): Promise<ReleaseInfo | null>;
+}
+declare function createReleaseReader(deps: ReleaseReaderDeps): ReleaseReader;
+
+export { type ReleaseInfo, type ReleaseReader, type ReleaseReaderDeps, createReleaseReader, normalizeRepositoryUrl, repoSlug };

package/dist/github.js

@@ -0,0 +1,90 @@
+// src/semver.ts
+import semver from "semver";
+function parseSemver(value) {
+  const text = String(value ?? "").trim();
+  if (text === "") return void 0;
+  const parsed = semver.parse(text);
+  if (parsed === null) return void 0;
+  return {
+    core: [parsed.major, parsed.minor, parsed.patch],
+    // semver 会把纯数字预发布段解析为 number，这里统一转回字符串以保持旧契约。
+    prerelease: parsed.prerelease.map((part) => String(part))
+  };
+}
+
+// src/github.ts
+var GITHUB_HOST = "github.com";
+var DEFAULT_TIMEOUT_MS = 8e3;
+var DEFAULT_TTL_MS = 10 * 60 * 1e3;
+function normalizeRepositoryUrl(value) {
+  if (typeof value !== "string") return void 0;
+  let url = value.trim();
+  if (url === "") return void 0;
+  url = url.replace(/^git\+/i, "");
+  const ssh = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/i.exec(url);
+  if (ssh !== null) url = `https://github.com/${ssh[1]}/${ssh[2]}`;
+  url = url.replace(/\.git$/i, "");
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return void 0;
+    if (parsed.hostname.toLowerCase() !== GITHUB_HOST) return void 0;
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    if (pathname === "") return void 0;
+    return `https://github.com${pathname}`;
+  } catch {
+    return void 0;
+  }
+}
+function repoSlug(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  if (text === "") return null;
+  if (/^[\w.-]+\/[\w.-]+$/.test(text)) return text;
+  const normalized = normalizeRepositoryUrl(text);
+  if (normalized === void 0) return null;
+  const pathname = normalized.slice(`https://github.com/`.length);
+  return pathname === "" ? null : pathname;
+}
+function createReleaseReader(deps) {
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  const ttlMs = deps.ttlMs ?? DEFAULT_TTL_MS;
+  const failureTtlMs = deps.failureTtlMs ?? ttlMs;
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const now = deps.now ?? Date.now;
+  const repo = deps.repo.trim();
+  const cache = /* @__PURE__ */ new Map();
+  async function release(version) {
+    const target = String(version ?? "").trim();
+    if (repo === "" || parseSemver(target) === void 0) return null;
+    const cached = cache.get(target);
+    if (cached !== void 0 && now() < cached.expiresAt) return cached.value;
+    const tag = `v${target.replace(/^v/, "")}`;
+    try {
+      const response = await fetchImpl(`https://api.github.com/repos/${repo}/releases/tags/${tag}`, {
+        headers: { accept: "application/vnd.github+json" },
+        redirect: "error",
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      const value = response.ok ? await response.json().then((raw) => {
+        const release2 = raw ?? {};
+        return {
+          version: target,
+          body: typeof release2.body === "string" ? release2.body : "",
+          htmlUrl: typeof release2.html_url === "string" ? release2.html_url : null,
+          name: typeof release2.name === "string" ? release2.name : null
+        };
+      }) : null;
+      cache.set(target, { value, expiresAt: now() + ttlMs });
+      return value;
+    } catch {
+      cache.set(target, { value: null, expiresAt: now() + failureTtlMs });
+      return null;
+    }
+  }
+  return { release };
+}
+export {
+  createReleaseReader,
+  normalizeRepositoryUrl,
+  repoSlug
+};

package/dist/http.d.ts

@@ -24,5 +24,38 @@ interface ReadJsonOptions {
 }
 /** 读一个 JSON 对象 body；超过上限抛 PAYLOAD_TOO_LARGE，非对象/非法 JSON 抛 INVALID_JSON。 */
 declare function readJsonBody(request: AsyncIterable<Uint8Array | string>, options?: ReadJsonOptions): Promise<Record<string, unknown>>;
+interface RouteContext {
+    request: RequestLike & AsyncIterable<Uint8Array | string>;
+    url: URL;
+    /** 大写方法名。 */
+    method: string;
+    /** 已剥掉 prefix 的 pathname（`/state` 之类）。 */
+    pathname: string;
+    /** 已解析的 JSON body（超出上限/非法会先抛 HttpError）；无 body 时空对象。 */
+    body: Record<string, unknown>;
+}
+/** 把插件自己的错误（IpcError / ServiceError …）映射成 HTTP 响应；返回 undefined 走默认 500。 */
+type RouteErrorMapper = (error: unknown) => {
+    status: number;
+    code?: string;
+    message: string;
+    extra?: Record<string, unknown>;
+} | undefined;
+interface CreateRouteHandlerOptions {
+    /** 路由前缀，如 `/api/morehao/xxx`。 */
+    prefix: string;
+    /** 鉴权头名；要求值 `1`（跨源预检顺带挡 CSRF）。 */
+    header: string;
+    /** 业务 dispatch：返回结果对象（包成 `{ok:true,...}`）或自行写完响应（返回 void）。 */
+    dispatch: (ctx: RouteContext) => Promise<Record<string, unknown> | void>;
+    /** body 上限；默认 512 KiB。 */
+    maxBodyBytes?: number;
+    /** 错误映射；缺省 500 INTERNAL。 */
+    onError?: RouteErrorMapper;
+    logger?: (event: string, data?: Record<string, unknown>) => void;
+}
+type RouteHandler = (request: unknown, response: unknown) => Promise<void>;
+/** 造一个宿主的 request 处理器：统一鉴权 / body / 响应 / 错误兜底。 */
+declare function createRouteHandler(options: CreateRouteHandlerOptions): RouteHandler;
 
-export { HttpError, type HttpErrorCode, type ReadJsonOptions, type RequestLike, type ResponseLike, hasHeader, readJsonBody, sendJson };
+export { type CreateRouteHandlerOptions, HttpError, type HttpErrorCode, type ReadJsonOptions, type RequestLike, type ResponseLike, type RouteContext, type RouteErrorMapper, type RouteHandler, createRouteHandler, hasHeader, readJsonBody, sendJson };