dsh-plugin-update 0.1.0 → 0.1.1

package/README.md

@@ -22,7 +22,7 @@ npm install dsh-plugin-update
 包根即宿主侧入口（`package.json` 的 `exports` 只暴露包根与 `./package.json`）：
 
 - 包根（宿主侧用）：建更新能力、拼电话名、给调用方回电话名与处理器。宿主侧用标准模块写法，直接 `import`。
-- `dist/client.js`（客户端侧用）：电话名拼法、轮询时间口径、手工兜底命令形状。客户端侧用文本拼接消费（取编译后函数的声明体拼进插件主文件闭包），面板界面不进包。
+- `dist/client.js`（客户端侧用）：电话名拼法、轮询时间口径、手工兜底命令形状。客户端侧**在构建期派生取值**（把本文件打包一次，把你自己的前缀代进去，得到三个电话名与轮询间隔的常量），面板界面不进包。
 
 ## 3. 三步接入（双入口）
 
@@ -59,17 +59,54 @@ for (const [name, handler] of Object.entries(update.handlers)) {
 这一步得到该插件的一组电话名与处理器：`notes.updateStatus`、`notes.updateCheck`、`notes.updateInstall`。
 单例复用键强制含插件标识，多插件不串内存状态与锁。其余配置（官方源、目录根、超时、轮询）全可选并带默认值，默认值等于现状，不传即走现状。
 
-第 3 步：客户端侧接线（`dist/client.js` 按文本拼接消费）。
+第 3 步：客户端侧接线（构建期派生取值）。
+
+这一步的目标只有一句：**面板里不要写死电话名与轮询间隔，全部从本包派生出来**。做法是构建时把本包的客户端入口打包一次，把你的前缀代进去，在你的仓库里生成一个小文件，里面是三个电话名与轮询间隔的常量；面板直接引用这些常量。
+
+在第 2 步已有的配置上再补两处接线：
+
+```js
+// 生成出来的文件里长这样（名字随你，这里是本仓用的形状）：
+//   export const UPD_STATUS  = 'notes.updateStatus'
+//   export const UPD_CHECK   = 'notes.updateCheck'
+//   export const UPD_INSTALL = 'notes.updateInstall'
+//   export const UPD_POLL    = 1000
+//
+// 面板里这样用（宿主侧用同一套 phoneNames，两边必须同前缀）：
+host.call(UPD_STATUS, {})            // 查状态
+host.call(UPD_CHECK, {})             // 查新版
+host.call(UPD_INSTALL, { checkId, requestId })  // 装更新
+setInterval(readStatus, UPD_POLL)    // 轮询间隔
+```
+
+面板不再出现 `'notes.updateStatus'` 这样的字面量，也不再出现写死的 `1000`。以后要换前缀或换轮询间隔，只改本包的配置再重新派生一次，面板一行都不用动。
+
+派生要用的三样取值都在本包的客户端入口里，按名字取即可：
 
 ```js
-// 电话名拼法与宿主侧同一套，传入同一个前缀。
-// 下面三行是形状说明，实际消费时取 dist/client.js 里对应函数的声明体、
-// 去行首 export 后拼进插件主文件闭包，打包工具不解析 import（面板界面不进包）。
-buildClientPhoneNames('notes') // 得到 notes.updateStatus / notes.updateCheck / notes.updateInstall
-assertPollInterval(1000) // 面板轮询间隔，不得小于 250 毫秒
-manualCommand({ profileName, latestVersion, installedVersion, runningVersion, jobTargetVersion, blockedReason, sourceInstall: false, targetPackageName: 'my-notes-plugin', registryUrl: 'https://registry.npmjs.org/' })
+buildClientPhoneNames('notes')  // 电话名拼法，与宿主侧同一套（前缀 + 点 + 动作名）
+CLIENT_POLL.defaultMs           // 面板轮询间隔默认值（1 秒）
+CLIENT_POLL.minMs               // 轮询间隔下限（250 毫秒，低于它要报错而不是静默取整）
+manualCommand({ ... })          // 手工兜底命令的形状，与宿主侧同一套政策
 ```
 
+注意 `manualCommand` 一般不用你在面板里算：宿主每次回包都会带一条现成的手工命令（见第 9 节），面板拿到就展示，不要自己拼。
+
+**参考实现**：本包自带集成工具 `derive-client-values.mjs`，在你自己的插件仓库里跑一条命令即可（它的输入是包里的 `dist/client.js`，纯 JS，不需要你自己有 TypeScript）：
+
+```sh
+node node_modules/dsh-plugin-update/derive-client-values.mjs --prefix notes --out scripts/generated/updateClient.derived.js
+```
+
+生成的 `UPD_STATUS` / `UPD_CHECK` / `UPD_INSTALL` / `UPD_POLL` 就是上面那段面板示例要用的常量。以后换前缀或升级本包，重新跑一次这条命令即可。
+
+自定义项与注意点：
+
+- `--prefix` 必填，必须与宿主侧 `createHostUpdate` 传的 `prefix` 一致，否则面板调的电话名和宿主注册的电话名对不上。
+- `--out` 必填，且故意不给默认值：默认值会覆盖别人的文件，写错比报错更糟。
+- 工具用 `esbuild` 只做「打包一次」这件事（构建期使用，不引入运行期依赖）。esbuild 优先从本包自己的 `node_modules` 找，找不到再从你的仓库找；两处都没有时它会打印一句明确的安装提示，不静默失败。
+- `--dry-run` 只打印生成内容、不写文件，用来先看一眼再决定。
+
 客户端只做三件事：照前缀拼电话名、按间隔轮询查状态、装不上时展示手工兜底命令与待重启提示（见第 9、10 节）。
 `pluginId` 必填（非空字符串且不含路径分隔符），`prefix` 不传即 `wf`，新插件务必传自己的前缀。
 

package/derive-client-values.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * derive-client-values.mjs —— 从更新包生成「面板要用的取值」文件（集成文档第 3 节第 3 步的参考实现）。
+ *
+ * 为什么要有这个文件：面板里不该写死电话名（'notes.updateStatus' 这类字面量）与轮询间隔，
+ * 否则换前缀、换间隔就得改多处、还容易改漏。取值只有更新包这一个来源，
+ * 所以做法是：构建时把本包的客户端入口打包一次，把消费方自己的前缀代进去，
+ * 在消费方仓库里生成一个小文件，里面是三个电话名与轮询间隔的常量，面板直接引用这些常量。
+ *
+ * 用法（在你自己的插件仓库里跑）：
+ *   node node_modules/dsh-plugin-update/derive-client-values.mjs \
+ *     --prefix notes \
+ *     --out scripts/generated/updateClient.derived.js
+ *
+ * 参数：
+ *   --prefix <前缀>   必填。你在宿主侧 createHostUpdate 里传的那个 prefix，两处必须一致。
+ *   --out <文件路径>  必填。生成到哪里。故意不给默认值：默认值会覆盖别人的文件，写错更糟。
+ *   --package <标识>  可选。写进生成文件的封面注释，方便以后认出来是谁生成的。默认取消费方 package.json 的 name。
+ *   --dry-run         只打印要生成的内容，不写文件。
+ *
+ * 生成的形状（具体值随你的前缀）：
+ *   export const UPD_STATUS  = 'notes.updateStatus'
+ *   export const UPD_CHECK   = 'notes.updateCheck'
+ *   export const UPD_INSTALL = 'notes.updateInstall'
+ *   export const UPD_POLL    = 1000
+ *   export const UPD_POLL_MIN = 250
+ *
+ * 依赖说明：本脚本用 esbuild 只做「打包一次」这件事，不引入任何运行期依赖。
+ * esbuild 优先从本包自己的 node_modules 找；找不到再从你的仓库里找（你自己的 devDependencies 里有也行）。
+ * 两个地方都没有时打印一句明确的安装提示，不静默失败。
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PKG_DIR = dirname(fileURLToPath(import.meta.url))
+const PKG_MANIFEST = JSON.parse(readFileSync(join(PKG_DIR, 'package.json'), 'utf8'))
+
+function usage(message) {
+  if (message) console.error('错误：' + message)
+  console.error('用法：node ' + join(PKG_DIR.split(/[\\/]/).pop(), 'derive-client-values.mjs') + ' --prefix <前缀> --out <文件路径> [--package <标识>] [--dry-run]')
+  process.exit(2)
+}
+
+// ---------- 参数 ----------
+let prefix = ''
+let outFile = ''
+let consumerName = ''
+let dryRun = false
+const argv = process.argv.slice(2)
+for (let i = 0; i < argv.length; i++) {
+  const arg = argv[i]
+  if (arg === '--prefix') { prefix = argv[++i] || '' }
+  else if (arg === '--out') { outFile = argv[++i] || '' }
+  else if (arg === '--package') { consumerName = argv[++i] || '' }
+  else if (arg === '--dry-run') { dryRun = true }
+  else if (arg === '-h' || arg === '--help') { usage('') }
+  else { usage('不认识的参数 ' + arg) }
+}
+if (!prefix) usage('必须给 --prefix（要与宿主侧 createHostUpdate 的 prefix 一致）')
+if (!outFile) usage('必须给 --out（生成到哪里；故意不给默认值，免得覆盖别人的文件）')
+if (!/^[A-Za-z0-9_.-]+$/.test(prefix)) usage('--prefix 只允许字母、数字、下划线、点与短横（电话名是「前缀.动作名」，前缀里不该有别的字符）')
+if (prefix.includes('.')) usage('--prefix 不能含点：点留作前缀与动作名之间的分隔符')
+
+// ---------- 找 esbuild ----------
+function loadEsbuild() {
+  const candidates = [join(PKG_DIR, 'package.json'), join(process.cwd(), 'package.json')]
+  for (const from of candidates) {
+    if (!existsSync(from)) continue
+    try {
+      const require = createRequire(from)
+      return require('esbuild')
+    } catch {
+      // 换下一个候选位置
+    }
+  }
+  console.error('错误：找不到 esbuild（本脚本用它把客户端入口打包一次，只做构建期使用，不引入运行期依赖）。')
+  console.error('修法：在你自己的插件仓库里装一次开发依赖 ——  npm install --save-dev esbuild')
+  process.exit(1)
+}
+
+// ---------- 打包客户端入口 ----------
+const esbuild = loadEsbuild()
+const entry = join(PKG_DIR, 'src', 'client.ts')
+const sourceOfTruth = existsSync(entry) ? entry : join(PKG_DIR, 'dist', 'client.js')
+if (!existsSync(sourceOfTruth)) {
+  console.error('错误：包里既没有 src/client.ts 也没有 dist/client.js，包可能不完整（重装一次试试）。')
+  process.exit(1)
+}
+
+let built
+try {
+  built = esbuild.buildSync({
+    entryPoints: [sourceOfTruth],
+    bundle: true,
+    format: 'esm',
+    platform: 'neutral',
+    target: 'es2020',
+    write: false,
+  })
+} catch (error) {
+  console.error('错误：打包客户端入口失败：' + ((error && error.message) || error))
+  process.exit(1)
+}
+if (!built.outputFiles || built.outputFiles.length !== 1) {
+  console.error('错误：打包产物数量不对（期望恰好 1 个文件），包可能不完整。')
+  process.exit(1)
+}
+
+let body = Buffer.from(built.outputFiles[0].contents).toString('utf8').replace(/\r\n/g, '\n')
+// 注释里的路径归一：不同目录重跑时打包器会写出相对路径形态，统一成包名开头，保证消费方重跑零差异。
+body = body.replace(/^\/\/ (\.\.\/)+packages\//gm, '// packages/')
+
+// 打包器收尾会写一个模块级的 `export { ... };` 块。那个块拼进插件主文件闭包是语法错误
+// （闭包里只能是声明），所以拆掉它；被改名导出的符号在下面补回本名。
+const exportBlock = body.match(/export\s*\{([\s\S]*?)\}\s*;?\s*$/)
+const aliases = []
+if (exportBlock) {
+  for (const item of exportBlock[1].split(',')) {
+    const piece = item.trim()
+    if (!piece) continue
+    const alias = piece.match(/^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)$/)
+    if (alias && alias[1] !== alias[2]) aliases.push(alias)
+  }
+  body = body.slice(0, exportBlock.index)
+}
+body = body.replace(/\s+$/, '') + '\n'
+
+// ---------- 组装 ----------
+const who = consumerName || (function () {
+  try {
+    return JSON.parse(readFileSync(join(process.cwd(), 'package.json'), 'utf8')).name || '（未指明）'
+  } catch {
+    return '（未指明）'
+  }
+})()
+
+const header =
+  '// 由 ' + PKG_MANIFEST.name + '@' + PKG_MANIFEST.version + ' 的集成工具生成，人手不改。\n' +
+  '// 生成命令：node ' + PKG_MANIFEST.name + '/derive-client-values.mjs --prefix ' + prefix + ' --out <本文件路径>\n' +
+  '// 生成对象：' + who + '。改了前缀或想升级本包，重新跑一次这条命令即可。\n'
+
+const aliasExports = aliases.map(([local, name]) => 'export const ' + name + ' = ' + local + '\n').join('')
+
+const tail =
+  '\n// ---- 取值：从更新包的客户端入口算出本插件要用的电话名与轮询间隔 ----\n' +
+  '// 面板只该用下面这几个常量，不要再写死电话名字面量与轮询数字。\n' +
+  'const UPD_PHONE_NAMES = buildClientPhoneNames(' + JSON.stringify(prefix) + ')\n' +
+  'const UPD_POLL_MS = CLIENT_POLL.defaultMs\n' +
+  'const UPD_POLL_MIN_MS = CLIENT_POLL.minMs\n' +
+  'export const UPD_STATUS = UPD_PHONE_NAMES.updateStatus\n' +
+  'export const UPD_CHECK = UPD_PHONE_NAMES.updateCheck\n' +
+  'export const UPD_INSTALL = UPD_PHONE_NAMES.updateInstall\n' +
+  'export const UPD_POLL = UPD_POLL_MS\n' +
+  'export const UPD_POLL_MIN = UPD_POLL_MIN_MS\n'
+
+const output = header + body + aliasExports + tail
+
+if (dryRun) {
+  process.stdout.write(output)
+  process.exit(0)
+}
+
+const target = isAbsolute(outFile) ? outFile : resolve(process.cwd(), outFile)
+mkdirSync(dirname(target), { recursive: true })
+writeFileSync(target, output, 'utf8')
+console.log('已生成：' + target)
+console.log('  前缀 ' + prefix + ' → 电话名 ' + ['updateStatus', 'updateCheck', 'updateInstall'].map((a) => prefix + '.' + a).join('、') + '，轮询 ' + 1000 + ' 毫秒')
+console.log('  面板里请引用 UPD_STATUS / UPD_CHECK / UPD_INSTALL / UPD_POLL，不要再写字面量。')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-update",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "可复用的更新系统装成的 npm 包：任何 DSH 插件照文档能集成检查更新等功能（地图 #579）",
   "license": "MIT",
   "author": "王辰浩",
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "derive-client-values.mjs",
     "event-list.template.json",
     "README.md",
     "LICENSE"