@morehao/dsh-plugin-kit 0.2.1 → 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` 替换进程策略）。
 
 ## 安装
 
@@ -114,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 + 26 条离线测试（假 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/state.d.ts

@@ -0,0 +1,32 @@
+/** `$DSH_HOME`（去空白、`path.resolve`）→ 缺省 `homedir()/.dsh`。与 dsh-core 及三仓既有实现一致。 */
+declare function resolveDshHome(env?: NodeJS.ProcessEnv): string;
+interface JsonStoreOptions<T> {
+    /** 状态目录（绝对路径）。调用方用 `resolveDshHome` + 插件目录名拼。 */
+    dir: string;
+    /** 文件名，如 `'state.json'`。 */
+    file: string;
+    /** 读失败 / 缺失 / 非对象时返回的默认值（工厂函数，避免共享可变引用）。 */
+    fallback: () => T;
+    /** 写回时的文件权限位；默认 0o600（状态文件默认私有）。 */
+    mode?: number;
+    /** mkdir 的目录权限；默认 0o700。 */
+    dirMode?: number;
+    /** 测试注入：默认读真实文件。 */
+    readFile?: (path: string) => Promise<string>;
+    readFileSync?: (path: string) => string;
+}
+interface JsonStore<T> {
+    /** 状态文件的绝对路径。 */
+    readonly path: string;
+    /** 同步读：坏文件 / 缺失 / 非对象 → `fallback()`。永不抛。 */
+    read(): T;
+    /** 同步原子写（`writeFileAtomicSync`）。失败抛错。 */
+    write(value: T): void;
+    /** 异步读。 */
+    readAsync(): Promise<T>;
+    /** 异步原子写（`writeFileAtomic`）。失败抛错。 */
+    writeAsync(value: T): Promise<void>;
+}
+declare function createJsonStore<T>(options: JsonStoreOptions<T>): JsonStore<T>;
+
+export { type JsonStore, type JsonStoreOptions, createJsonStore, resolveDshHome };

package/dist/state.js

@@ -0,0 +1,186 @@
+// src/state.ts
+import { mkdirSync, promises as fsp2, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// 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;
+  }
+}
+
+// src/state.ts
+function resolveDshHome(env = process.env) {
+  const raw = env.DSH_HOME?.trim();
+  return raw !== void 0 && raw !== "" ? raw : join(homedir(), ".dsh");
+}
+function serialize(value) {
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+function coerce(text, fallback) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return fallback();
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return fallback();
+  return parsed;
+}
+var defaultReadFileSync = (target) => readFileSync(target, "utf8");
+var defaultReadFile = (target) => fsp2.readFile(target, "utf8");
+function createJsonStore(options) {
+  const file = join(options.dir, options.file);
+  const mode = options.mode ?? 384;
+  const dirMode = options.dirMode ?? 448;
+  const readFileSyncImpl = options.readFileSync ?? defaultReadFileSync;
+  const readFileImpl = options.readFile ?? defaultReadFile;
+  function read() {
+    let text;
+    try {
+      text = readFileSyncImpl(file);
+    } catch {
+      return options.fallback();
+    }
+    return coerce(text, options.fallback);
+  }
+  async function readAsync() {
+    let text;
+    try {
+      text = await readFileImpl(file);
+    } catch {
+      return options.fallback();
+    }
+    return coerce(text, options.fallback);
+  }
+  function write(value) {
+    try {
+      mkdirSync(options.dir, { recursive: true, mode: dirMode });
+    } catch {
+    }
+    writeFileAtomicSync(file, serialize(value), { mode });
+  }
+  async function writeAsync(value) {
+    try {
+      await fsp2.mkdir(options.dir, { recursive: true, mode: dirMode });
+    } catch {
+    }
+    await writeFileAtomic(file, serialize(value), { mode });
+  }
+  return { path: file, read, write, readAsync, writeAsync };
+}
+export {
+  createJsonStore,
+  resolveDshHome
+};

package/dist/update-client.d.ts

@@ -1,4 +1,5 @@
 import { UpdateView, ApplyResult } from './update.js';
+import './exec.js';
 import './profile-RKpxKDlK.js';
 
 /**

package/dist/update.d.ts

@@ -1,3 +1,4 @@
+import { ExecOptions, ExecResult } from './exec.js';
 import { I as InstallKind, H as HostRegistryPlan } from './profile-RKpxKDlK.js';
 export { P as ProfileLike } from './profile-RKpxKDlK.js';
 
@@ -43,7 +44,9 @@ interface PluginMeta {
  * - **装不上要能回退**：宿主 `installBundle` 对已装包会返回 `already-installed`，按官方
  *   更新路径先 remove 再 install；remove 之后 install 失败则尝试装回原版本。
  * - **不重写宿主进程策略**：需要 `pnpm view` 时由调用方注入 `runPnpmView`（进程/环境
- *   白名单是各插件自己的事），本包只做 registry 兜底。
+ *   白名单是各插件自己的事），本包只做 registry 兜底。为免三个插件各抄一遍「读 profile → 拼
+ *   `pnpm view` → 解析 → 校验」，本模块导出 `createPnpmViewRunner` 供直接复用（内部走 `./exec`，
+ *   环境清洗仍由调用方把握；也可注入 `exec` 替换进程策略）。
  * - 更新会把运行中的插件自己卸载，界面会一起消失：全过程落固定事件名，便于事后对账。
  */
 
@@ -109,5 +112,27 @@ interface Updater {
     isApplying(): boolean;
 }
 declare function createPluginUpdater(deps: UpdaterDeps): Updater;
+interface PnpmViewRunnerDeps {
+    /** 取宿主 `profileContext`（提供 `dir` / `packageManager`）；可抛，内部会兜。 */
+    getProfile: () => unknown;
+    /**
+     * 可注入的子进程执行器（默认 `./exec` 的 `spawnCollect`）。
+     * 各插件若要沿用自己更细的进程策略（环境白名单 / 输出上限 / 作业面板旁路），注入即可。
+     */
+    exec?: (command: string, args: string[], options?: ExecOptions) => Promise<ExecResult>;
+    /** 环境来源；默认 `process.env`，内部过 `sanitizedEnv` 清洗。 */
+    env?: NodeJS.ProcessEnv;
+    /** 单个查询超时毫秒；默认 8_000。 */
+    timeoutMs?: number;
+}
+/**
+ * 造一个 `runPnpmView`：用 profile 的包管理器在 profile 目录执行
+ * `pnpm view <spec> version --json`，继承 `.npmrc` 的镜像 / 私源 / token。
+ *
+ * 返回 `(spec) => Promise<string | null>`，与 `UpdaterDeps.runPnpmView` 兼容：
+ * 拿不到 profile.dir / 命令失败 / 输出非法 / 版本不是合法 semver → `null`（交由 registry 兜底）。
+ * 三个插件此前各自手写这段，本工厂与它们的历史行为一致。
+ */
+declare function createPnpmViewRunner(deps: PnpmViewRunnerDeps): (spec: string) => Promise<string | null>;
 
-export { type ApplyResult, HostRegistryPlan, InstallKind, type Logger, type PluginManagerLike, type PluginMeta, PluginUpdateError, type UpdateErrorCode, type UpdateView, type Updater, type UpdaterDeps, createPluginUpdater };
+export { type ApplyResult, HostRegistryPlan, InstallKind, type Logger, type PluginManagerLike, type PluginMeta, PluginUpdateError, type PnpmViewRunnerDeps, type UpdateErrorCode, type UpdateView, type Updater, type UpdaterDeps, createPluginUpdater, createPnpmViewRunner };

package/dist/update.js

@@ -1,3 +1,170 @@
+// 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;
+}
+
 // src/registry.ts
 var OFFICIAL_REGISTRY = "https://registry.npmjs.org/";
 var DEFAULT_TIMEOUT_MS = 8e3;
@@ -459,7 +626,38 @@ function createPluginUpdater(deps) {
     isApplying: () => applying
   };
 }
+function createPnpmViewRunner(deps) {
+  const timeoutMs = deps.timeoutMs ?? 8e3;
+  const run = deps.exec ?? spawnCollect;
+  const env = sanitizedEnv(deps.env ?? process.env);
+  return async (spec) => {
+    let profile;
+    try {
+      profile = normalizeProfile(deps.getProfile());
+    } catch {
+      return null;
+    }
+    if (profile === null || typeof profile.dir !== "string" || profile.dir === "") return null;
+    const command = profile.packageManager?.command ?? "pnpm";
+    const prefix = profile.packageManager?.args ?? [];
+    let result;
+    try {
+      result = await run(command, [...prefix, "view", spec, "version", "--json"], {
+        cwd: profile.dir,
+        env,
+        timeoutMs,
+        maxStdout: 64 * 1024,
+        maxStderr: 16 * 1024
+      });
+    } catch {
+      return null;
+    }
+    const version = collectVersionView(result);
+    return version !== null && parseSemver(version) !== void 0 ? version : null;
+  };
+}
 export {
   PluginUpdateError,
-  createPluginUpdater
+  createPluginUpdater,
+  createPnpmViewRunner
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morehao/dsh-plugin-kit",
-  "version": "0.2.1",
-  "description": "DeepSeek Harness 插件共用工具包：插件自更新引擎（查 npm 最新版 + 经宿主 pluginManager 重装）、headless 客户端控制器与 HTTP 小工具。零 @deepseek-ai 运行时依赖，宿主能力全部注入。",
+  "version": "0.3.0",
+  "description": "DeepSeek Harness 插件共用工具包：插件自更新引擎（查 npm 最新版 + 经宿主 pluginManager 重装）、headless 客户端控制器、HTTP 小工具，以及子进程执行 / 原子写 / JSON 状态持久化等通用底座。零 @deepseek-ai 运行时依赖，宿主能力全部注入。",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,6 +22,18 @@
       "types": "./dist/http.d.ts",
       "default": "./dist/http.js"
     },
+    "./exec": {
+      "types": "./dist/exec.d.ts",
+      "default": "./dist/exec.js"
+    },
+    "./fs": {
+      "types": "./dist/fs.d.ts",
+      "default": "./dist/fs.js"
+    },
+    "./state": {
+      "types": "./dist/state.d.ts",
+      "default": "./dist/state.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -45,7 +57,9 @@
     "typecheck": "tsc --noEmit",
     "test": "node --test \"test/*.test.mjs\"",
     "pretest": "npm run build",
-    "check": "npm run typecheck && npm run build && npm test --ignore-scripts"
+    "check": "npm run typecheck && npm run build && npm test --ignore-scripts",
+    "check:release-notes": "node scripts/smoke-release-notes.mjs",
+    "prepack": "npm run build"
   },
   "devDependencies": {
     "@types/node": "22.20.5",