@morehao/dsh-plugin-kit 0.1.0 → 0.3.0

package/dist/profile-RKpxKDlK.d.ts

@@ -0,0 +1,117 @@
+/**
+ * npm registry 约定：把包名拼成 `/latest` 端点，并按宿主给出的 registry 优先级发请求。
+ *
+ * **registry 列表与排序都优先复用宿主原生能力**（`@deepseek-ai/dsh-plugin-manager/registry` 的
+ * `registryPlan(requested, configured)`，与 `installBundle` / `inspect` 内部用的是同一份源码）。
+ * 但本包坚持**零 `@deepseek-ai/*` 运行时依赖**（见 package.json / update.ts），所以不直接 import，
+ * 而是让调用方把原生函数**注入**进来（见 `HostRegistryPlan` / `LatestDeps.registryPlan`）：
+ *
+ *   - 注入了 → 用宿主原生排序（含私有源「只问它自己、不回退公有源」的语义，与安装完全一致）；
+ *   - 没注入 / 调用抛错 / 结果不可用 → 退回本模块内置的 `registryPlan` 兜底（见下）。
+ *
+ * 为什么查最新版不复用 `pluginManager.inspect()`：`inspect(spec)` 在 registry 分支里先判
+ * 「该包是否已在 profile 依赖中」，命中即返回 `already-installed`，**根本不会去问 registry**。
+ * 而插件自更新要查的恰恰是「我自己这个已装包有没有新版」，必然命中该拦截。所以查 latest
+ * 只能另走 `pnpm view`（见 `latest.ts` 的 `runPnpmView`）或 registry `/latest`，`inspect` 不可替代。
+ */
+declare const OFFICIAL_REGISTRY = "https://registry.npmjs.org/";
+declare const DEFAULT_TIMEOUT_MS = 8000;
+declare const DEFAULT_CACHE_TTL_MS: number;
+/**
+ * 宿主 `pluginManager.registries()` 的返回形状（对齐 @deepseek-ai/dsh-plugin-manager）。
+ *
+ * 设计取舍：字段都按可选 + unknown 收。宿主版本差异或字段改名时，内置兜底 `registryPlan` 用
+ * `normalizeRegistry` 逐个校验，非法项直接跳过并最终退到官方源，**绝不因形状不符而抛错**
+ * （fail-open：宁可退化到官方源，也不让自更新检查因宿主形状变化而崩）。
+ */
+interface RegistriesLike {
+    /** pnpm 在 profile 内解析出的实际 registry（继承 .npmrc），非空时最优先。 */
+    resolved?: unknown;
+    /** 配置里显式的 registry（可能为 null，表示「pnpm 自身配置的源」）。 */
+    registry?: unknown;
+    /** 回退源；宿主默认含 npmmirror。 */
+    fallbackRegistries?: unknown;
+}
+/**
+ * 宿主原生 `registryPlan` 的注入形状，对齐 `@deepseek-ai/dsh-plugin-manager/registry`。
+ *
+ * 调用方（各插件）自己 `import { registryPlan } from '@deepseek-ai/dsh-plugin-manager/registry'`
+ * 后注入本包，即可让「查最新版的 registry 顺序」与宿主安装使用**完全一致**的排序与私有源语义。
+ *
+ * 入参/返回：
+ * - `requested`：首位要问的 registry；`undefined` 表示交给宿主按 configured 首项决定。
+ * - `configured`：`registries()` 的返回值（resolved / registry / fallbackRegistries）。
+ * - 返回：依次要问的 registry 数组，**元素可能为 `null`**（表示 pnpm 自身配置的源）；宿主实现
+ *   在入参非法时会**抛错**，所以本包调用处已包 try/catch 兜底。
+ */
+type HostRegistryPlan = (requested: string | undefined, configured: RegistriesLike) => Array<string | null>;
+/** 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()` 的结果收敛成「查 latest 时要依次试的 registry 顺序」：
+ * `resolved → registry → fallback`，去重；全非法/缺失时退到官方 registry，**绝不抛**。
+ *
+ * 这是**注入不到宿主原生 `registryPlan` 时的简化兜底**，不是宿主安装计划的等价物：它不区分
+ * 公有/私有源。因此若 `resolved` 是私有源而其上查不到本包（镜像未同步），兜底会继续去问
+ * fallback / 官方源拿 latest；而宿主真正安装时可能只问私有源并失败。差异只影响「能否查到版本」，
+ * 不影响实际安装走哪条路。想与宿主机安装完全对齐，请注入原生 `registryPlan`（见 `HostRegistryPlan`）。
+ */
+declare function registryPlan(registries: unknown): string[];
+/**
+ * 解析「查 latest 时要依次试的 registry 顺序」：
+ * **优先用宿主原生 `registryPlan`**（注入且成功时，排序/私有源语义与宿主机安装完全一致），
+ * 否则退回内置 `registryPlan` 兜底（fail-open，保证查询永远有一条可走的路）。
+ *
+ * @param registries 宿主 `registries()` 的返回值（任意形状，内部按 unknown 校验）。
+ * @param hostPlan  可选的宿主原生 `registryPlan`（由调用方从 dsh-plugin-manager/registry 注入）。
+ */
+declare function resolveRegistryPlan(registries: unknown, hostPlan?: HostRegistryPlan): string[];
+/** 手动更新命令：`dsh plugin --profile <name> add <pkg>@latest`。 */
+declare function manualCommand(packageName: string, profileName?: string | null): string;
+
+/**
+ * profile 读取：判断本插件是以什么形态装进当前 profile。
+ *
+ * 一键更新最危险的场景是「开发用的本地链接」：profile 里写的是 `link:/path/to/repo`，
+ * 一旦用 registry 重装，本地的 link 会被换成 npm 版，开发流就被悄悄改掉了。所以
+ * 更新前先读 `<profile.dir>/package.json` 的依赖声明，link: / file: / workspace: 一律
+ * 关闭一键更新，只给手动命令。
+ */
+type InstallKind = 'registry' | 'link' | 'file' | 'workspace' | 'unknown';
+interface ProfileLike {
+    name?: string;
+    dir?: string;
+    home?: string;
+    packageManager?: {
+        command?: string;
+        args?: string[];
+    };
+}
+interface InstallKindResult {
+    kind: InstallKind;
+    /** profile package.json 里声明的原始 spec（读不到就是 undefined）。 */
+    spec?: string;
+    /** 说明来源，便于日志与界面提示。 */
+    source?: string;
+}
+/** 把宿主 `profileContext`（任意形状）收敛成只含我们关心的字段；拿不到返回 null。 */
+declare function normalizeProfile(value: unknown): ProfileLike | null;
+/** `dependencies` 里声明的 spec 决定安装形态；`npm:` 别名仍按 registry 处理。 */
+declare function classifyInstallSpec(spec: unknown): InstallKind;
+interface DetectDeps {
+    profile: ProfileLike | null;
+    packageName: string;
+    /** 测试注入；默认读真实文件。 */
+    readFile?: (path: string) => Promise<string>;
+    readJson?: (path: string) => Promise<unknown>;
+}
+/** 读 profile 的 package.json，返回本插件声明的 spec（找不到返回 undefined）。 */
+declare function readDeclaredSpec(deps: DetectDeps): Promise<{
+    spec?: string;
+    source?: string;
+}>;
+declare function detectInstallKind(deps: DetectDeps): Promise<InstallKindResult>;
+
+export { DEFAULT_CACHE_TTL_MS as D, type HostRegistryPlan as H, type InstallKind as I, OFFICIAL_REGISTRY as O, type ProfileLike as P, type RegistriesLike as R, DEFAULT_TIMEOUT_MS as a, type DetectDeps as b, type InstallKindResult as c, classifyInstallSpec as d, detectInstallKind as e, encodePackageName as f, normalizeRegistry as g, registryPlan as h, resolveRegistryPlan as i, manualCommand as m, normalizeProfile as n, readDeclaredSpec as r };

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,5 +1,6 @@
 import { UpdateView, ApplyResult } from './update.js';
-import './profile-C-eyP5F6.js';
+import './exec.js';
+import './profile-RKpxKDlK.js';
 
 /**
  * 客户端侧 headless 控制器（不依赖 React、不 import node 内置模块）。

package/dist/update.d.ts

@@ -1,5 +1,26 @@
-import { I as InstallKind } from './profile-C-eyP5F6.js';
-export { P as ProfileLike } from './profile-C-eyP5F6.js';
+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';
+
+/**
+ * 查 npm 上某个包的最新版本。
+ *
+ * 顺序（可配置）：
+ *   1. 调用方注入的 `runPnpmView`（让插件用自己 profile 的包管理器查，继承 .npmrc 的
+ *      镜像 / 私源 / token；宿主内裸 fetch 读不到这些配置）。**这是复用宿主包管理器**：
+ *      查询在 profile 目录、profile 的 packageManager 环境下执行，与宿主安装同源。
+ *   2. 宿主 `pluginManager.registries()` 给出的 registry 列表，依次问 `<base><pkg>/latest`；
+ *      排序**优先用调用方注入的宿主原生 `registryPlan`**（与安装完全一致），未注入则内置兜底
+ *      （见 `registry.ts` 的 `resolveRegistryPlan`）；
+ *   3. 都没有就用官方 registry。
+ *
+ * **为什么不用宿主的 `pluginManager.inspect()` 查最新版**：`inspect()` 在 registry 分支会先判
+ * 「该包是否已在 profile 依赖中」，命中即返回 `already-installed`，不会真正去问 registry。
+ * 插件自更新要查的正是「我自己这个已装包」，必然命中该拦截，所以此处只能走 `pnpm view` / `/latest`。
+ *
+ * 全部失败返回 null（不抛）：调用方用它标记 `checkFailed`，界面照常可用。注意「查不到」≠「宿主缺失」，
+ * 而是网络 / registry / 包管理器任一环节不可用时的运行时降级。
+ */
 
 type Logger = (event: string, detail?: Record<string, unknown>) => void;
 interface PluginMeta {
@@ -13,13 +34,19 @@ interface PluginMeta {
  *
  * 设计约束（三个 DSH 插件共用这份逻辑）：
  * - **零 `@deepseek-ai/*` 运行时依赖**：pluginManager / profileContext 都由调用方用
- *   `ctx.get(...)` 惰性取，拿不到就退化成「只检查 + 手动命令」。
+ *   `ctx.get(...)` 惰性取。本包定位就是 DSH 插件，宿主必然在；但 `installBundle` 是
+ *   可选/远程能力，取不到只是「当前部署未暴露该能力」，退化成「只检查 + 手动命令」。
+ * - **复用优先**：registry 顺序优先用调用方注入的宿主原生 `registryPlan`（与宿主安装完全一致，
+ *   含私有源语义），未注入则内置兜底（见 `registry.ts` 的 `resolveRegistryPlan`）；查最新版走
+ *   `pnpm view` / registry `/latest`（`inspect()` 对已装包返回 already-installed，不可替代）。
  * - **不自作主张升级**：只有 registry 明确给出合法且严格更新的版本才允许安装；
  *   `link:` / `file:` / `workspace:` 安装一律禁止一键更新（会把开发链接换成 npm 版）。
  * - **装不上要能回退**：宿主 `installBundle` 对已装包会返回 `already-installed`，按官方
  *   更新路径先 remove 再 install；remove 之后 install 失败则尝试装回原版本。
  * - **不重写宿主进程策略**：需要 `pnpm view` 时由调用方注入 `runPnpmView`（进程/环境
- *   白名单是各插件自己的事），本包只做 registry 兜底。
+ *   白名单是各插件自己的事），本包只做 registry 兜底。为免三个插件各抄一遍「读 profile → 拼
+ *   `pnpm view` → 解析 → 校验」，本模块导出 `createPnpmViewRunner` 供直接复用（内部走 `./exec`，
+ *   环境清洗仍由调用方把握；也可注入 `exec` 替换进程策略）。
  * - 更新会把运行中的插件自己卸载，界面会一起消失：全过程落固定事件名，便于事后对账。
  */
 
@@ -63,6 +90,8 @@ interface UpdaterDeps {
     getProfileName?: () => string | null;
     fetchImpl?: typeof fetch;
     runPnpmView?: (spec: string) => Promise<string | null>;
+    /** 可选：注入宿主原生 `registryPlan`（dsh-plugin-manager/registry），让查版本的 registry 顺序与安装一致。 */
+    registryPlan?: HostRegistryPlan;
     readFile?: (path: string) => Promise<string>;
     logger?: Logger;
     now?: () => number;
@@ -83,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, 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 };