@morehao/dsh-plugin-kit 0.1.0 → 0.3.0

package/README.md

@@ -1,12 +1,15 @@
 # @morehao/dsh-plugin-kit
 
-DeepSeek Harness（dsh）插件共用的工具包。当前提供三件事：
+DeepSeek Harness（dsh）插件共用的工具包。当前提供这些能力：
 
 - **插件自更新引擎**（`./update`）：查 npm 最新版 → 判断能不能一键更新 → 经宿主 `pluginManager` 重装自己。
 - **headless 客户端控制器**（`./update/client`）：检查/更新的状态机与单飞，UI 由各插件自己渲染。
 - **HTTP 小工具**（`./http`）：自定义头鉴权、`no-store` JSON、有上限的 JSON body。
+- **子进程执行**（`./exec`）：argv 直传（不经 shell）、环境白名单、超时/取消、输出上限，外加 `pnpm view` 版本解析。
+- **原子写**（`./fs`）：`writeFileAtomicSync` / `writeFileAtomic`，杜绝「半个文件」。
+- **JSON 状态持久化**（`./state`）：`$DSH_HOME` 解析 + `<home>/<plugin>/*.json` 读写（读 fail-open、写抛错）。
 
-设计约束：**零 `@deepseek-ai/*` 运行时依赖**，宿主能力（`pluginManager` / `profileContext`）全部由调用方注入；进程相关的策略（比如用哪个包管理器查版本）也由插件自己决定，本包不替你 spawn。
+设计约束：**零 `@deepseek-ai/*` 运行时依赖**，宿主能力（`pluginManager` / `profileContext`）全部由调用方注入。进程策略由调用方把握：`./update` 常驻能力不主动 spawn，需要 `pnpm view` 时由调用方注入 `runPnpmView`；也可直接用 `./exec`（或 `createPnpmViewRunner`，默认走 `./exec`、可注入 `exec` 替换进程策略）。
 
 ## 安装
 
@@ -14,16 +17,34 @@ DeepSeek Harness（dsh）插件共用的工具包。当前提供三件事：
 npm install @morehao/dsh-plugin-kit
 ```
 
+## 能力边界：哪些复用宿主、哪些必须自建
+
+自更新这件事在宿主（`@deepseek-ai/dsh-plugin-manager`）里已有大半能力，本包的原则是**能复用就复用**：
+
+| 能力 | 来源 | 说明 |
+|---|---|---|
+| 安装 / 卸载 | **复用宿主** | apply 全程走 `pluginManager.installBundle` / `removeBundle`；`already-installed → remove → install` 就是宿主既定的更新流程，`applied/restart-required/overridden` 也直接来自宿主结果。 |
+| registry 列表（镜像 / 私源 / token） | **复用宿主** | `resolved` 由宿主跑 `pnpm config get registry` 解析，本包不自己读 `.npmrc`。 |
+| registry **排序 / 回退** | **复用宿主（注入）** | 优先用调用方注入的宿主原生 `registryPlan`（`@deepseek-ai/dsh-plugin-manager/registry`），与 `installBundle`/`inspect` 内部同一份源码、含私有源「只问它自己、不回退公有源」语义。本包不直接 import（保持零 `@deepseek-ai/*` 运行时依赖），由插件侧注入。未注入时用内置 `resolveRegistryPlan` 兜底（`resolved → registry → fallback` 宽松顺序，fail-open）。 |
+| 查最新版 | **必须自建** | 宿主 `inspect()` 对「已装包」直接返回 `already-installed`，不会去问 registry；插件查的正是「我自己这个已装包」，必然被拦截。故只能走 `pnpm view`（`runPnpmView`，复用 profile 的包管理器）或 registry `/latest`。 |
+| 安装形态判定 | **必须自建** | 宿主未暴露「本包以什么 spec 声明」；本包读 `<profile.dir>/package.json` 识别 `link:/file:/workspace:` 以拒绝把开发链接覆盖成 npm 版。 |
+
+一句话：**装/卸、registry 取数与排序都复用宿主（排序原生能力通过注入复用）；查版本、判形态因宿主 API 缺口而自建；不注入原生 `registryPlan` 时才回落到内置兜底顺序。**
+
 ## 一键更新（host）
 
 ```ts
 import { createPluginUpdater } from '@morehao/dsh-plugin-kit/update';
+// 宿主原生 registry 排序（与 installBundle/inspect 同一份），由插件侧注入、本包不直接依赖
+import { registryPlan as hostRegistryPlan } from '@deepseek-ai/dsh-plugin-manager/registry';
 
 const updater = createPluginUpdater({
   meta: { name: pkg.name, version: pkg.version, ...(pkg.repository ? { repository: repoUrl(pkg.repository) } : {}) },
   getPluginManager: () => ctx.get('pluginManager'),
   getProfile: () => ctx.get('profileContext'),
   getProfileName: () => ctx.get('profileContext')?.name,
+  // 可选但推荐：注入宿主原生 registryPlan，使「查版本的 registry 顺序」与宿主安装完全一致
+  registryPlan: hostRegistryPlan,
   // 可选：用 profile 的包管理器查版本（继承 .npmrc 的镜像 / 私源 / token）
   runPnpmView: async (spec) => {
     const profile = ctx.get('profileContext');
@@ -96,15 +117,79 @@ const body = await readJsonBody(request, { maxBytes: 512 * 1024 });
 sendJson(response, 200, { ok: true });
 ```
 
+## 子进程执行（`./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 兜底）。
+
 ## 版本与兼容
 
 - Node `^22.20.0 || >=24.0.0`，纯 ESM。
-- `./update` 与 `./http` 走 host 侧；`./update/client` 只含状态机，不 import node 内置模块（客户端产物只允许 react）。
+- `./update`、`./http`、`./exec`、`./fs`、`./state` 走 host 侧；`./update/client` 只含状态机，不 import node 内置模块（客户端产物只允许 react）。
 - 宿主服务形状按结构化类型处理（`PluginManagerLike` / `ProfileLike`），宿主版本变化不会把插件一起拖下去。
 
 ## 开发
 
 ```bash
 npm install
-npm run check   # typecheck + build + 24 条离线测试（假 fetch / 假 pluginManager，不联网、不真装）
+npm run check   # typecheck + build + 49 条离线测试（假 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/index.d.ts

@@ -1,43 +1,15 @@
-export { D as DetectDeps, I as InstallKind, a as InstallKindResult, P as ProfileLike, c as classifyInstallSpec, d as detectInstallKind, n as normalizeProfile, r as readDeclaredSpec } from './profile-C-eyP5F6.js';
+export { D as DEFAULT_CACHE_TTL_MS, a as DEFAULT_TIMEOUT_MS, b as DetectDeps, H as HostRegistryPlan, I as InstallKind, c as InstallKindResult, O as OFFICIAL_REGISTRY, P as ProfileLike, R as RegistriesLike, d as classifyInstallSpec, e as detectInstallKind, f as encodePackageName, m as manualCommand, n as normalizeProfile, g as normalizeRegistry, r as readDeclaredSpec, h as registryPlan, i as resolveRegistryPlan } from './profile-RKpxKDlK.js';
 
-/**
- * semver 解析与比较（只做插件更新需要的部分）。
- *
- * 不引 semver 依赖：更新判定宁可不升级也不要误升，所以非法版本一律返回 undefined，
- * 由调用方按「不更新」处理。支持 `v1.2.3` / `1.2.3-beta.1` / `1.2.3+build`。
- */
+/** 保留旧接口形状：核心三段 + 预发布标识（字符串数组）。 */
 interface Semver {
     core: [number, number, number];
     prerelease: string[];
 }
+/** 解析成 `Semver`；非法（含空串 / `1.2` / `1.2.3.4` / 非版本串）返回 undefined。 */
 declare function parseSemver(value: unknown): Semver | undefined;
 /** `candidate` 是否严格新于 `current`；任一方不是合法 semver 都返回 false。 */
 declare function isNewerVersion(current: unknown, candidate: unknown): boolean;
 /** 比较两个版本：负数 / 0 / 正数；任一方非法返回 undefined。 */
 declare function compareVersions(left: unknown, right: unknown): number | undefined;
 
-/**
- * npm registry 约定：把包名拼成 `/latest` 端点，并按宿主给出的 registry 优先级发请求。
- *
- * 宿主 `pluginManager.registries()` 会把 profile 的镜像 / 私源 / token 计划交出来；
- * 拿不到就退回官方 registry。这里只做纯函数（不含网络），网络在 `latest.ts`。
- */
-declare const OFFICIAL_REGISTRY = "https://registry.npmjs.org/";
-declare const DEFAULT_TIMEOUT_MS = 8000;
-declare const DEFAULT_CACHE_TTL_MS: number;
-/** 宿主 registry 计划的形状（字段都当可选处理，宿主版本差异不该让我们崩）。 */
-interface RegistriesLike {
-    resolved?: unknown;
-    registry?: unknown;
-    fallbackRegistries?: unknown;
-}
-/** npm 包名转 registry 路径：`@scope/name` → `@scope%2Fname`（保留 @，斜杠编码）。 */
-declare function encodePackageName(name: string): string;
-/** registry 归一成 `https://host/` 形式；非法（非 http(s) / 解析失败）返回 null。 */
-declare function normalizeRegistry(value: unknown): string | null;
-/** 由宿主的 registries() 结果拼出要问的 registry 顺序：resolved → registry → fallback，去重。 */
-declare function registryPlan(registries: unknown): string[];
-/** 手动更新命令：`dsh plugin --profile <name> add <pkg>@latest`。 */
-declare function manualCommand(packageName: string, profileName?: string | null): string;
-
-export { DEFAULT_CACHE_TTL_MS, DEFAULT_TIMEOUT_MS, OFFICIAL_REGISTRY, type RegistriesLike, type Semver, compareVersions, encodePackageName, isNewerVersion, manualCommand, normalizeRegistry, parseSemver, registryPlan };
+export { type Semver, compareVersions, isNewerVersion, parseSemver };

package/dist/index.js

@@ -1,59 +1,29 @@
 // src/semver.ts
-var SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+import semver from "semver";
 function parseSemver(value) {
   const text = String(value ?? "").trim();
-  const match = SEMVER.exec(text);
-  if (match === null) return void 0;
-  const major = Number(match[1]);
-  const minor = Number(match[2]);
-  const patch = Number(match[3]);
-  if (!Number.isSafeInteger(major) || !Number.isSafeInteger(minor) || !Number.isSafeInteger(patch)) return void 0;
-  return { core: [major, minor, patch], prerelease: match[4] === void 0 ? [] : match[4].split(".") };
-}
-function comparePrerelease(left, right) {
-  if (left.length === 0 || right.length === 0) {
-    return left.length === right.length ? 0 : left.length === 0 ? 1 : -1;
-  }
-  const length = Math.max(left.length, right.length);
-  for (let index = 0; index < length; index += 1) {
-    const a = left[index];
-    const b = right[index];
-    if (a === void 0 || b === void 0) return a === b ? 0 : a === void 0 ? -1 : 1;
-    if (a === b) continue;
-    const aNumeric = /^\d+$/.test(a);
-    const bNumeric = /^\d+$/.test(b);
-    if (aNumeric && bNumeric) {
-      const an = BigInt(a);
-      const bn = BigInt(b);
-      if (an !== bn) return an > bn ? 1 : -1;
-      continue;
-    }
-    if (aNumeric !== bNumeric) return aNumeric ? -1 : 1;
-    return a > b ? 1 : -1;
-  }
-  return 0;
+  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))
+  };
 }
 function isNewerVersion(current, candidate) {
   const a = parseSemver(current);
   const b = parseSemver(candidate);
   if (a === void 0 || b === void 0) return false;
-  for (let index = 0; index < 3; index += 1) {
-    const left = a.core[index] ?? 0;
-    const right = b.core[index] ?? 0;
-    if (right !== left) return right > left;
-  }
-  return comparePrerelease(b.prerelease, a.prerelease) > 0;
+  const left = String(current).trim();
+  const right = String(candidate).trim();
+  return semver.gt(right, left);
 }
 function compareVersions(left, right) {
   const a = parseSemver(left);
   const b = parseSemver(right);
   if (a === void 0 || b === void 0) return void 0;
-  for (let index = 0; index < 3; index += 1) {
-    const an = a.core[index] ?? 0;
-    const bn = b.core[index] ?? 0;
-    if (an !== bn) return an > bn ? 1 : -1;
-  }
-  return comparePrerelease(a.prerelease, b.prerelease);
+  return semver.compare(String(left).trim(), String(right).trim());
 }
 
 // src/registry.ts
@@ -96,6 +66,36 @@ function registryPlan(registries) {
   if (ordered.length === 0) ordered.push(OFFICIAL_REGISTRY);
   return ordered;
 }
+function planFromHost(hostPlan, registries) {
+  if (registries === null || typeof registries !== "object") return null;
+  const ordered = [];
+  const push = (value) => {
+    const normalized = normalizeRegistry(value);
+    if (normalized !== null && !ordered.includes(normalized)) ordered.push(normalized);
+  };
+  let result;
+  try {
+    result = hostPlan(void 0, registries);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(result)) return null;
+  for (const entry of result) {
+    if (entry === null) {
+      push(registries.resolved);
+      continue;
+    }
+    push(entry);
+  }
+  return ordered.length === 0 ? null : ordered;
+}
+function resolveRegistryPlan(registries, hostPlan) {
+  if (typeof hostPlan === "function") {
+    const fromHost = planFromHost(hostPlan, registries);
+    if (fromHost !== null) return fromHost;
+  }
+  return registryPlan(registries);
+}
 function manualCommand(packageName, profileName) {
   const spec = `${packageName}@latest`;
   return typeof profileName === "string" && profileName !== "" ? `dsh plugin --profile ${profileName} add ${spec}` : `dsh plugin add ${spec}`;
@@ -175,5 +175,6 @@ export {
   normalizeRegistry,
   parseSemver,
   readDeclaredSpec,
-  registryPlan
+  registryPlan,
+  resolveRegistryPlan
 };