@morehao/dsh-plugin-kit 0.3.0 → 0.3.1

package/README.md

@@ -4,10 +4,12 @@ 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`）全部由调用方注入。进程策略由调用方把握：`./update` 常驻能力不主动 spawn，需要 `pnpm view` 时由调用方注入 `runPnpmView`；也可直接用 `./exec`（或 `createPnpmViewRunner`，默认走 `./exec`、可注入 `exec` 替换进程策略）。
 
@@ -110,11 +112,23 @@ 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`）
@@ -181,15 +195,48 @@ const updater = createPluginUpdater({ meta, getPluginManager: () => ctx.get('plu
 
 拿不到 `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`、`./exec`、`./fs`、`./state` 走 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 + 49 条离线测试（假 fetch / 假 pluginManager / 假 exec，不联网、不真装）
+npm run check   # typecheck + build + 67 条离线测试（假 fetch / 假 pluginManager / 假 exec，不联网、不真装）
 ```

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 };

package/dist/http.js

@@ -43,8 +43,48 @@ async function readJsonBody(request, options = {}) {
   }
   return value;
 }
+function createRouteHandler(options) {
+  const maxBodyBytes = options.maxBodyBytes ?? 512 * 1024;
+  const logger = options.logger ?? (() => {
+  });
+  const prefix = options.prefix;
+  return async (rawRequest, rawResponse) => {
+    const request = rawRequest;
+    const response = rawResponse;
+    if (!hasHeader(request, options.header)) {
+      sendJson(response, 403, { ok: false, code: "FORBIDDEN", message: `\u7F3A\u5C11 ${options.header}: 1 \u5934` });
+      return;
+    }
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+    const pathname = url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) || "/" : url.pathname;
+    const method = (request.method ?? "GET").toUpperCase();
+    try {
+      const body = method === "GET" || method === "HEAD" ? {} : await readJsonBody(request, { maxBytes: maxBodyBytes });
+      const result = await options.dispatch({ request, url, method, pathname, body });
+      if (response.writableEnded !== true) {
+        sendJson(response, 200, result === void 0 ? { ok: true } : { ok: true, ...result });
+      }
+    } catch (error) {
+      if (response.writableEnded === true) return;
+      const mapped = options.onError?.(error);
+      if (mapped !== void 0) {
+        sendJson(response, mapped.status, {
+          ok: false,
+          ...mapped.code === void 0 ? {} : { code: mapped.code },
+          message: mapped.message,
+          ...mapped.extra === void 0 ? {} : mapped.extra
+        });
+        return;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      logger("route.error", { method, pathname, message });
+      sendJson(response, 500, { ok: false, code: "INTERNAL", message });
+    }
+  };
+}
 export {
   HttpError,
+  createRouteHandler,
   hasHeader,
   readJsonBody,
   sendJson

package/dist/meta.d.ts

@@ -0,0 +1,28 @@
+interface PluginMetaInfo {
+    name: string;
+    version: string;
+    /** 规范化后的 `https://github.com/owner/repo`；解析不了则缺省。 */
+    repository?: string;
+    /** `owner/repo` 短名；解析不了为 null。 */
+    repo: string | null;
+}
+interface ReadFileSyncLike {
+    (path: string | URL): string;
+}
+interface CreatePluginMetaOptions {
+    /** `new URL('../package.json', import.meta.url)` 这类导入地址。 */
+    pkgUrl: URL | string;
+    defaultName?: string;
+    /** 注入读文件（测试/奇特环境）；默认 `node:fs` readFileSync。 */
+    readFileSync?: ReadFileSyncLike;
+}
+/** 读一次 package.json，产出插件身份；读失败用 defaultName + `0.0.0` 兜底。 */
+declare function createPluginMeta(options: CreatePluginMetaOptions): PluginMetaInfo;
+interface ReadInstalledVersionOptions {
+    pkgUrl: URL | string;
+    readFileSync?: ReadFileSyncLike;
+}
+/** 每次重读 package.json 的 version（更新插件后同进程能读到新值）；失败 → ''。 */
+declare function readInstalledVersion(options: ReadInstalledVersionOptions): string;
+
+export { type CreatePluginMetaOptions, type PluginMetaInfo, type ReadFileSyncLike, type ReadInstalledVersionOptions, createPluginMeta, readInstalledVersion };

package/dist/meta.js

@@ -0,0 +1,82 @@
+// src/meta.ts
+import { readFileSync as fsReadFileSync } from "fs";
+
+// src/semver.ts
+import semver from "semver";
+
+// src/github.ts
+var GITHUB_HOST = "github.com";
+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;
+}
+
+// src/meta.ts
+function defaultReadFileSync(path) {
+  return fsReadFileSync(path, "utf8");
+}
+function createPluginMeta(options) {
+  const readFileSync = options.readFileSync ?? defaultReadFileSync;
+  const fallbackName = options.defaultName ?? "";
+  try {
+    const parsed = JSON.parse(readFileSync(options.pkgUrl));
+    if (parsed === null || typeof parsed !== "object") {
+      return { name: fallbackName, version: "0.0.0", repo: null };
+    }
+    const pkg = parsed;
+    const rawRepo = typeof pkg.repository === "string" ? pkg.repository : pkg.repository !== null && typeof pkg.repository === "object" ? pkg.repository.url : void 0;
+    const repository = normalizeRepositoryUrl(rawRepo);
+    const repo = repoSlug(repository);
+    return {
+      name: typeof pkg.name === "string" && pkg.name !== "" ? pkg.name : fallbackName,
+      version: typeof pkg.version === "string" && pkg.version !== "" ? pkg.version : "0.0.0",
+      ...repository === void 0 ? {} : { repository },
+      repo
+    };
+  } catch {
+    return { name: fallbackName, version: "0.0.0", repo: null };
+  }
+}
+function readInstalledVersion(options) {
+  const readFileSync = options.readFileSync ?? defaultReadFileSync;
+  try {
+    const parsed = JSON.parse(readFileSync(options.pkgUrl));
+    if (parsed !== null && typeof parsed === "object") {
+      const version = parsed.version;
+      if (typeof version === "string") return version.trim();
+    }
+    return "";
+  } catch {
+    return "";
+  }
+}
+export {
+  createPluginMeta,
+  readInstalledVersion
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morehao/dsh-plugin-kit",
-  "version": "0.3.0",
-  "description": "DeepSeek Harness 插件共用工具包：插件自更新引擎（查 npm 最新版 + 经宿主 pluginManager 重装）、headless 客户端控制器、HTTP 小工具，以及子进程执行 / 原子写 / JSON 状态持久化等通用底座。零 @deepseek-ai 运行时依赖，宿主能力全部注入。",
+  "version": "0.3.1",
+  "description": "DeepSeek Harness 插件共用工具包：插件自更新引擎、headless 客户端控制器、HTTP 小工具与路由 dispatcher、子进程执行、原子写、JSON 状态持久化，以及 GitHub Release 读取与插件身份元数据等通用底座。零 @deepseek-ai 运行时依赖，宿主能力全部注入。",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,6 +34,14 @@
       "types": "./dist/state.d.ts",
       "default": "./dist/state.js"
     },
+    "./github": {
+      "types": "./dist/github.d.ts",
+      "default": "./dist/github.js"
+    },
+    "./meta": {
+      "types": "./dist/meta.d.ts",
+      "default": "./dist/meta.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [