dsh-plugin-update 0.1.2 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 给 DSH 插件加「检查更新 / 安装更新」能力的 npm 包。宿主侧一段接线，面板侧构建期派生取值，装不上时给用户一条可复制的手工命令。
 
-要求 Node 22 或更高，零运行时依赖。当前版本 `0.1.2`。
+要求 Node 22 或更高，零运行时依赖。当前版本 `0.2.0`。
 
 装上它你会拿到三样东西：
 
@@ -16,6 +16,9 @@
 npm install dsh-plugin-update
 ```
 
+把本包装成**你自己插件的依赖**即可（推荐）；老式的「把本包 vendor 进插件目录」也照旧可用。
+两种形态下，包都按**包名**在自己的 `node_modules` 链上找你的插件包——找到它，才能推出「插件装在哪、正在跑的是哪一版」。
+
 包还没公开发布时先用本地路径代替（例如 `npm install ../dsh-plugin-update`）。
 
 ## 2. 三步接入
@@ -51,6 +54,16 @@ for (const [name, handler] of Object.entries(update.handlers)) {
 `pluginId` 必填（非空字符串，不含路径分隔符）。单例复用键强制含插件标识，多插件不串内存状态与锁。
 除 `pluginId` 之外的配置都可选并带默认值，不传即走默认（见第 3 节）。
 
+接线的第二个参数除 `{ ctx, logCtx }` 外还能给 `pluginManager`（显式交宿主管理器实例）与 `readerOverrides`。
+平时不用管；只有自动解析对不上目标包时（hoisted、多副本、开发态链接）才用得上它的 `targetPackageDir`：
+
+```js
+createHostUpdate(
+  { ctx, logCtx, readerOverrides: { targetPackageDir: '/abs/path/to/node_modules/my-notes-plugin' } },
+  { pluginId: 'my-notes-plugin', prefix: 'notes', targetPackageName: 'my-notes-plugin' }
+)
+```
+
 ### 第 3 步：面板侧接线（构建期派生）
 
 目标只有一句：**面板里不要写死电话名与轮询间隔**。构建时用包内工具生成一个小文件：
@@ -82,13 +95,16 @@ setInterval(readStatus, UPD_POLL)                // 轮询
 
 宿主种类与安装出口都由本包自己探测和选择，**升级依赖即可，宿主侧与面板侧都不用改代码**：
 
-1. 依赖版本提到 `^0.1.2`。
+1. 依赖版本提到 `^0.2.0`。
 2. 重新装 / 发一版你自己的插件，让新依赖进当前使用范围（运行时用的是 `node_modules` 里那份）。
 3. 如果你自己接过一版宿主安装出口，把它删掉——它会挡在本包的路由前面。
 
 两处例外必须动代码（它们把自动探测挡住了）：显式传了 `readerOverrides.environmentKind`；显式传了与真实使用范围不符的 `profileDir` / `profileName`。
 
-`targetPackageName` 建议就是你自己的包名：使用范围目录按「装好的包住在 `<范围>/node_modules/<目标包名>`」反推，对不上时要自己传 `profileDir`。
+`targetPackageName` 建议就是你自己的包名：使用范围目录按「装好的包住在 `<范围>/node_modules/<目标包名>`」反推。
+
+`0.2.0` 起目标包**按包名解析**（清单直解 → 入口反查 → `node_modules` 步行 → 自锚定兜底），`exports` 没导出 `.` 与 `./package.json` 的包也能命中。
+`0.1.x` 只能在本包被 vendor 进插件目录时找到目标包；以依赖形态安装时一键升级会永远不可用（面板显示假的 `installation-changed`）。
 
 ## 3. 配置
 
@@ -160,7 +176,7 @@ const update = createHostUpdate(
 
 | 原因 | 中文含义 | 用户该做什么 |
 |---|---|---|
-| `unknown-profile` | 使用范围认不出（名字非法或目录不存在） | 检查使用范围名是否含特殊字符、目录是否还在；这种情形不给手工命令 |
+| `unknown-profile` | 使用范围或目标包认不出（名字非法、目录不存在、按包名找不到你的插件包） | 检查使用范围名与目录是否还在；插件以依赖形态接入却在别的 `node_modules` 树里（hoisted、多副本、开发态链接）时，让集成方传 `readerOverrides.targetPackageDir`；这种情形不给手工命令 |
 | `source-install` | 当前是从源码装的，不是按版本号装的 | 这种情形不给手工命令；想走更新先按版本号重装一次 |
 | `invalid-installation` | 已装的包不完整（名字对不上、版本非法、入口文件缺失） | 重装当前版本，修好已装目录再查更新 |
 | `installation-changed` | 安装位置在使用中途变了（换了目录或换了包） | 重新打开宿主再查一次；还出现就重装 |
@@ -213,6 +229,8 @@ dsh plugin --profile my-web add --save-exact my-notes-plugin@1.2.3 --registry=ht
 9. 第三方 Desktop 自动装失败但命令能装：检查桌面当前激活的使用范围是不是插件所在的那一个；对不上时自动装一定诚实失败，复制第 5.3 节的命令手工执行。
 10. 官方桌面版（使用范围名 `desktop`）装不上：看任务里的 `message`，形如 `install-failed: <宿主原话>`，里面带着宿主的错误码（例如 `operation-error`）。`message` 可能带详情，**匹配请匹配前缀错误码，不要整串相等**；日志里这条路的路由是 `desktop-manager`。
 11. 还定位不到：打开调试日志，按插件标识过滤 `host.call`、`host.call.fail`、`update.install.exec` 三个事件，看 `pluginId` 与 `route`、`exitCode` 字段；日志里不记命令与路径原文。
+12. 以依赖形态接入后一直显示「安装位置在使用中途变了」（`installation-changed`）：`0.1.x` 的已知缺陷（拿「本包自己住在哪」推断目标包位置，依赖形态下恒失败）；升到 `0.2.0` 即修复。
+13. 报 `unknown-profile` 但使用范围名与目录都没问题：本包按包名找不到你的插件包。让集成方传 `readerOverrides.targetPackageDir`，或把本包装成插件包的依赖（别装到别的 `node_modules` 树里）。
 
 ## 7. 接入自检清单
 
@@ -248,8 +266,14 @@ checkEventCounts(manifest)                                        // 计数与
 `kind` 分三类只为计数检查服务：`resident` 常驻、`ondemand` 按需、`selfmon` 自监控。空模板见包内的 `event-list.template.json`。
 清单要以**对象**传入：字符串或数组会被拦下并给出中文说明，不静默修补。
 
+**宿主侧工具**：
+
+```js
+resolveTargetPackage(name, { targetPackageDir })  // 按包名解析你的插件包；找不到返回 null（自己搭读取器或写测试时用）
+```
+
 ## 9. 兼容与稳定性
 
 这些形状稳定，可以放心依赖：三个电话名与入参回参、快照六字段、任务公开形状、配置只经函数入参注入、安装配方五键、日志事件字段基线（三个事件各带必填 `pluginId`）、历史落盘路径。
 
-向后兼容的扩展：新增可选配置键、新增宿主种类与路由取值。调用方不认新取值时按普通宿主处理即可，不会因此报错。
+向后兼容的扩展：新增可选配置键、新增可选 `readerOverrides`（如 `targetPackageDir`）、新增宿主种类与路由取值。调用方不认新取值时按普通宿主处理即可，不会因此报错。

package/dist/host.js

@@ -1,8 +1,7 @@
 // AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/host.ts
 import { realpath } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { sep } from "node:path";
 import {
   DEFAULT_CONFIRMATION_TTL_MS,
   DEFAULT_CHECK_TIMEOUT_MS,
@@ -13,10 +12,10 @@ import {
 import { manualCommand } from "./commands.js";
 import { validVersion } from "./service.js";
 import { createUpdateDiskPorts, createUpdateExecutor } from "./store.js";
-import { containingPackage, createUpdateReader, defaultHomeDir, resolveProfileName } from "./reader.js";
+import { createUpdateReader, defaultHomeDir, resolveProfileName, resolveTargetPackage } from "./reader.js";
 import { buildPhoneName, buildPhoneNames as buildPhoneNames2, resolveUpdateConfig as resolveUpdateConfig2 } from "./config.js";
 import { parseEventListManifest, checkEventFields, checkEventCounts } from "./gate.js";
-import { containingPackage as containingPackage2, defaultHomeDir as defaultHomeDir2, profileNameValid, registrySpec } from "./reader.js";
+import { containingPackage, defaultHomeDir as defaultHomeDir2, profileNameValid, registrySpec, resolveTargetPackage as resolveTargetPackage2 } from "./reader.js";
 import { createUpdateDiskPorts as createUpdateDiskPorts2, createUpdateExecutor as createUpdateExecutor2, pathsForUpdate, resolveCliEntry } from "./store.js";
 let sharedReader = null;
 let sharedReaderKey = "";
@@ -71,10 +70,11 @@ function hash8(s) {
     return "00000000";
   }
 }
-async function inferProfileDir(loaded, homeDirDefault, targetPackageName) {
+async function tryInferProfileDir(targetDir, targetPackageName) {
   try {
-    const dir = loaded && loaded.directory ? String(loaded.directory) : "";
-    const marker = `${sep}node_modules${sep}${targetPackageName}`;
+    const dir = String(targetDir || "");
+    if (!dir) return null;
+    const marker = `${sep}node_modules${sep}${String(targetPackageName || "").split("/").join(sep)}`;
     const at = dir.lastIndexOf(marker);
     if (at > 0) {
       const candidate = dir.slice(0, at);
@@ -86,24 +86,38 @@ async function inferProfileDir(loaded, homeDirDefault, targetPackageName) {
     }
   } catch {
   }
-  return join(homeDirDefault, "profiles", "web");
+  return null;
+}
+function unknownProfile() {
+  return Object.assign(new Error("unknown-profile"), { code: "unknown-profile" });
 }
 async function getSharedReader(pluginId, config, overrides = {}) {
   const env = overrides.env ?? process.env;
   const osHome = overrides.osHome ?? homedir();
   const homeDirDefault = defaultHomeDir(env, osHome);
   const targetPackageName = overrides.targetPackageName ?? config.targetPackageName;
-  const loaded = await containingPackage(fileURLToPath(import.meta.url), targetPackageName).catch(() => null);
+  const explicitTargetDir = typeof overrides.targetPackageDir === "string" && overrides.targetPackageDir ? String(overrides.targetPackageDir) : "";
+  const loaded = await resolveTargetPackage(targetPackageName, explicitTargetDir ? { targetPackageDir: explicitTargetDir } : {}).catch(
+    () => null
+  );
   const runningVersion = overrides.runningVersion ?? (loaded && validVersion(loaded.manifest.version) ? String(loaded.manifest.version) : null);
-  if (!runningVersion) throw Object.assign(new Error("unknown-profile"), { code: "unknown-profile" });
-  const profileDirInput = overrides.profileDir ?? await inferProfileDir(loaded, homeDirDefault, targetPackageName);
+  if (!runningVersion) throw unknownProfile();
+  let profileDirInput;
+  if (overrides.profileDir) {
+    profileDirInput = String(overrides.profileDir);
+  } else {
+    const anchorDir = (loaded && loaded.directory ? String(loaded.directory) : "") || explicitTargetDir;
+    const inferred = anchorDir ? await tryInferProfileDir(anchorDir, targetPackageName) : null;
+    if (!inferred) throw unknownProfile();
+    profileDirInput = inferred;
+  }
   const homeDirInput = overrides.homeDir ?? config.homeDir ?? homeDirDefault;
   const environmentKind = overrides.environmentKind ?? detectEnvironmentKind(overrides.ctx, resolveProfileName(overrides.profileName, profileDirInput));
   const checkTimeoutMs = overrides.checkTimeoutMs ?? config.checkTimeoutMs;
   const confirmationTtlMs = overrides.confirmationTtlMs ?? config.confirmationTtlMs;
   const installTimeoutMs = overrides.installTimeoutMs ?? config.installTimeoutMs;
   const registryUrl = overrides.registryUrl ?? config.registryUrl;
-  const key = `${pluginId}\0${config.prefix}\0${runningVersion}\0${profileDirInput}\0${overrides.profileName ?? ""}\0${homeDirInput}\0${overrides.runInstall ? "exec" : ""}\0${environmentKind}\0${targetPackageName}`;
+  const key = `${pluginId}\0${config.prefix}\0${runningVersion}\0${profileDirInput}\0${overrides.profileName ?? ""}\0${homeDirInput}\0${overrides.runInstall ? "exec" : ""}\0${environmentKind}\0${targetPackageName}\0${explicitTargetDir}`;
   if (sharedReader && sharedReaderKey === key) return sharedReader;
   const disk = overrides.readJob && overrides.writeJob ? null : createUpdateDiskPorts(homeDirInput, pluginId, profileDirInput);
   const defaultRun = createUpdateExecutor({
@@ -129,6 +143,7 @@ async function getSharedReader(pluginId, config, overrides = {}) {
     pluginId,
     profileName: overrides.profileName ?? void 0,
     homeDir: overrides.homeDir,
+    targetPackageDir: explicitTargetDir || void 0,
     env,
     osHome,
     fetchImpl: overrides.fetchImpl,
@@ -278,7 +293,7 @@ export {
   buildPhoneNames2 as buildPhoneNames,
   checkEventCounts,
   checkEventFields,
-  containingPackage2 as containingPackage,
+  containingPackage,
   createHostUpdate,
   createUpdateDiskPorts2 as createUpdateDiskPorts,
   createUpdateExecutor2 as createUpdateExecutor,
@@ -289,5 +304,6 @@ export {
   profileNameValid,
   registrySpec,
   resolveCliEntry,
+  resolveTargetPackage2 as resolveTargetPackage,
   resolveUpdateConfig2 as resolveUpdateConfig
 };

package/dist/reader.js

@@ -1,6 +1,7 @@
 // AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/reader.ts
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, realpath, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -37,6 +38,56 @@ async function containingPackage(filename, name) {
     directory = parent;
   }
 }
+async function packageAtIfNamed(directory, name) {
+  try {
+    const pkg = await packageAt(directory);
+    if (pkg.manifest && pkg.manifest.name === name) return pkg;
+  } catch {
+  }
+  return null;
+}
+async function resolveTargetPackage(targetName, opts = {}) {
+  const name = String(targetName || "");
+  if (!name) return null;
+  if (opts.targetPackageDir) return packageAtIfNamed(resolve(String(opts.targetPackageDir)), name);
+  const base = import.meta.url;
+  let req = null;
+  try {
+    req = createRequire(base);
+  } catch {
+    req = null;
+  }
+  if (req) {
+    try {
+      const pkg = await packageAtIfNamed(dirname(req.resolve(`${name}/package.json`)), name);
+      if (pkg) return pkg;
+    } catch {
+    }
+    try {
+      const entry = req.resolve(name);
+      const pkg = await containingPackage(entry, name);
+      if (pkg) return pkg;
+    } catch {
+    }
+  }
+  try {
+    let dir = dirname(fileURLToPath(base));
+    while (true) {
+      const pkg = await packageAtIfNamed(join(dir, "node_modules", name), name);
+      if (pkg) return pkg;
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+  }
+  try {
+    const pkg = await containingPackage(fileURLToPath(base), name);
+    if (pkg) return pkg;
+  } catch {
+  }
+  return null;
+}
 function resolveProfileName(profileName, profileDir) {
   return profileName ?? basename(profileDir);
 }
@@ -102,7 +153,10 @@ function createUpdateReader(options) {
   const environmentKind = options.environmentKind ?? "cli";
   const targetPackageName = options.targetPackageName ?? "dsh-mattpocock-skills-deck";
   const registryUrl = options.registryUrl ?? "https://registry.npmjs.org/";
-  const loadedPackage = containingPackage(fileURLToPath(import.meta.url), targetPackageName).catch(() => null);
+  const loadedPackage = resolveTargetPackage(
+    targetPackageName,
+    options.targetPackageDir ? { targetPackageDir: options.targetPackageDir } : {}
+  ).catch(() => null);
   let boundIdentity;
   async function readInstalledReal() {
     const result = {
@@ -148,6 +202,7 @@ function createUpdateReader(options) {
     result.installedVersion = typeof installed.manifest.version === "string" ? installed.manifest.version : null;
     result.packageValid = await validPackage(installed, targetPackageName);
     const loaded = await loadedPackage;
+    const loadedUnresolvable = loaded === null;
     const identity = `${homeDir}\0${profileDir}\0${profileName}\0${pluginId}`;
     const sameLoadedPackage = loaded?.directory === installed.directory && loaded?.manifest.version === installed.manifest.version;
     if (boundIdentity === void 0 && sameLoadedPackage && result.packageValid) boundIdentity = identity;
@@ -158,6 +213,7 @@ function createUpdateReader(options) {
       result.installationKey = null;
     }
     if (boundIdentity !== void 0 && boundIdentity !== identity) result.blockedReason = "installation-changed";
+    else if (loadedUnresolvable) result.blockedReason = "unknown-profile";
     else if (!sameLoadedPackage && boundIdentity === void 0) result.blockedReason = "installation-changed";
     else if (!result.packageValid) result.blockedReason = "invalid-installation";
     else if (result.sourceInstall) result.blockedReason = "source-install";
@@ -193,5 +249,6 @@ export {
   defaultHomeDir,
   profileNameValid,
   registrySpec,
-  resolveProfileName
+  resolveProfileName,
+  resolveTargetPackage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-update",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "可复用的更新系统装成的 npm 包：任何 DSH 插件照文档能集成检查更新等功能（地图 #579）",
   "license": "MIT",
   "author": "王辰浩",