dsh-plugin-resolver 0.1.1 → 0.1.2

package/README.md

@@ -56,12 +56,12 @@ flowchart LR
 要求 **DSH `>=0.2.0-rc.2 <0.3.0`**（已在 `engines.dsh` 声明）。纯 JS、无构建、无 install 脚本，三种方式都不需要 `allowBuilds` 授权：
 
 ```sh
-# npm（已发布 0.1.1；profile 名以你的 DSH 安装为准）
+# npm（已发布 0.1.2；profile 名以你的 DSH 安装为准）
 dsh plugin --profile <profile> add dsh-plugin-resolver
 # GitHub 源码安装（建议锁 commit）
 dsh plugin --profile <profile> add github:sakikoTGW/dsh-plugin-resolver#<commit>
 # tarball
-npm pack && dsh plugin --profile <profile> add ./dsh-plugin-resolver-0.1.1.tgz
+npm pack && dsh plugin --profile <profile> add ./dsh-plugin-resolver-0.1.2.tgz
 ```
 
 装完（宿主重启后最稳）直接说：
@@ -115,6 +115,20 @@ install spec: dsh-better-sidebar@0.28.0
 - **GitHub-only**：检出到 `$DSH_HOME/plugin-sources/<owner>__<repo>`，缺构建产物且声明了 `build` 时执行 `pnpm install` + `pnpm run build`，随后 `installBundle('link:<pkgDir>')`，已构建的检出直接复用；
 - **显式 spec**（`github:` / `link:` / `file:` / `https:`）：原样交给插件管理器。
 
+## 重启判定
+
+`plugin_install` 不再无条件要求重启；安装前后会比较：
+
+- `pluginManager.listBundles()` 的 bundle 集合
+- 已安装包运行时文件的 hash（排除 README / docs / 版本号）
+
+结果：
+
+- 无变化 / 仅版本号变化 / 管理器已就地应用 → `restart: not required`
+- bundle 新增、运行时代码变化、client 半变化 → `restart: required — <原因>`
+
+本插件自身的 `logic/` 改动可以按 mtime 热加载，不需要重启；新增 bundle 或宿主壳变化仍然必须重启。
+
 ## 结构：稳定壳 + 可热加载逻辑
 
 ```
@@ -150,7 +164,7 @@ node test/ablation.mjs    # 消融测试（无副作用）
 ## 测试与 CI
 
 ```sh
-npm test        # = selftest(19) + harness(10)
+npm test        # = selftest(25) + harness(10)
 npm run bench   # 基准
 npm run ablate  # 消融
 ```
@@ -163,7 +177,7 @@ npm run ablate  # 消融
 ## 已知限制
 
 - 兼容性以 npm 元数据里的 peer / `engines.dsh` 为准，宿主启动预检另有判断时以宿主为准；
-- **替换已加载插件**仍需要重启宿主（loader 模块缓存 + 打包宿主无 Node 内部 loader），插件会如实报 `restart-required`；
+- **替换已加载插件**仍需要重启宿主（loader 模块缓存 + 打包宿主无 Node 内部 loader）；`plugin_install` 会先比较安装前后的 bundle 集合与运行时文件 hash，只有真正变化时才报 `restart-required`；
 - 同名歧义不猜，需要调用方给 `owner=` 或完整 spec；
 - 目录是社区维护的第三方列表，插件只保证"按声明来源装对版本"，不做安全审计；
 - GitHub 源码构建依赖宿主环境里的 `pnpm`（PATH 或 `DSH_PNPM_PATH`）与 `tar`，大仓库首次构建较慢。

package/logic/api.js

@@ -15,7 +15,7 @@
 const __v = new URL(import.meta.url).searchParams.get('v') ?? ''
 const __q = (name) => `./${name}${__v === '' ? '' : `?v=${encodeURIComponent(__v)}`}`
 const { baseName, loadCatalog, searchCatalog } = await import(__q('catalog.js'))
-const { installGithubSource, installRegistry, verifyInstall } = await import(__q('install.js'))
+const { installGithubSource, installRegistry, verifyInstall, capturePackageRuntime, decideRestart } = await import(__q('install.js'))
 const { resolveTarget } = await import(__q('resolve.js'))
 const { oneLine, stars } = await import(__q('util.js'))
 
@@ -122,6 +122,16 @@ export async function pluginInstall(ctx, manager, options, args) {
     let packageName = plan.name
     let steps = []
     let application = 'unknown'
+    let beforeRuntime = null
+    let bundlesBefore = []
+    if (plan.kind === 'npm' && typeof plan.name === 'string' && plan.name !== '') {
+      beforeRuntime = await capturePackageRuntime(plan.name).catch(() => null)
+    }
+    try {
+      bundlesBefore = (await manager.listBundles()).map((bundle) => bundle.name)
+    } catch {
+      bundlesBefore = []
+    }
 
     if (plan.kind === 'github') {
       const result = await installGithubSource(manager, plan, {
@@ -140,10 +150,11 @@ export async function pluginInstall(ctx, manager, options, args) {
       if (steps.length > 0) lines.push(`steps: ${steps.join(' → ')}`)
     } else {
       const { summary } = await installRegistry(manager, plan)
-      application = summary.application
+      const alreadyInstalled = /already-installed/i.test(summary.error ?? '')
+      application = alreadyInstalled ? 'applied' : summary.application
       if (packageName === null && summary.bundle) packageName = summary.bundle
-      lines.push(`install: ${summary.application} (${summary.stage})`)
-      if (summary.error) lines.push(`error: ${summary.error}`)
+      lines.push(alreadyInstalled ? 'install: already installed (no change)' : `install: ${summary.application} (${summary.stage})`)
+      if (summary.error && !alreadyInstalled) lines.push(`error: ${summary.error}`)
       if (summary.pendingBuilds.length > 0) {
         lines.push(`pending build scripts (needs approval): ${summary.pendingBuilds.join(', ')}`)
       }
@@ -163,14 +174,26 @@ export async function pluginInstall(ctx, manager, options, args) {
         lines.push(`- bundle: ${health.bundle.name}@${health.bundle.version ?? '?'} enabled=${health.bundle.enabled}`)
       }
       lines.push(`- package: ${packageName}${health.hasClient ? ` (client half via ${health.clientSource})` : ' (host-only)'}`)
-      const next = []
-      if (application === 'restart-required') {
-        next.push('restart DSH fully: replacing an already-mounted plugin cannot be hot-swapped safely')
+      let afterRuntime = null
+      let bundlesAfter = []
+      try {
+        afterRuntime = await capturePackageRuntime(packageName)
+        bundlesAfter = (await manager.listBundles()).map((bundle) => bundle.name)
+      } catch {
+        // keep the manager's own restart decision
       }
+      const restart = decideRestart({ before: beforeRuntime, after: afterRuntime, bundlesBefore, bundlesAfter, managerApplication: application })
+      lines.push('', `restart: ${restart.required ? 'required' : 'not required'} — ${restart.reason}`)
+      if (application === 'restart-required' && !restart.required) {
+        lines.push('- note: manager requested a restart, but runtime files are unchanged')
+      }
+      if (!restart.required && restart.versionChanged) lines.push('- version label updates after the next restart')
+      const next = []
+      if (restart.required) next.push(`restart DSH fully: ${restart.reason}`)
       if (health.entry?.fiberPhase === 'failed') next.push('host half failed to load; inspect the harness log for the error')
-      if (health.hasClient && application !== 'restart-required') next.push('client half exists: refresh the GUI (Ctrl+R) to load it')
-      if (health.entry?.fiberPhase === 'active' && !health.hasClient && application !== 'restart-required') {
-        next.push('host-only: no GUI refresh required')
+      if (restart.clientChanged) next.push('client half changed: refresh the GUI (Ctrl+R) to load it')
+      if (health.entry?.fiberPhase === 'active' && !health.hasClient && !restart.required && !restart.codeChanged) {
+        next.push('host-only: no restart or GUI refresh required')
       }
       if (next.length > 0) lines.push('', `next: ${next.join('; ')}`)
     }

package/logic/install.js

@@ -17,6 +17,7 @@ const { registryBase } = await import(__q('resolve.js'))
 
 import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import path from 'node:path'
 
 /** Longest a source install may run before the tool reports a timeout. */
@@ -95,21 +96,138 @@ export async function installRegistry(manager, plan) {
  * @returns {Promise<any | undefined>}
  */
 export async function installedManifest(packageName) {
-  const candidates = []
-  if (process.env.DSH_PROFILE_DIR) candidates.push(process.env.DSH_PROFILE_DIR)
-  const home = process.env.DSH_HOME && process.env.DSH_HOME !== '' ? process.env.DSH_HOME : null
+  const packageDir = await installedPackageDir(packageName)
+  if (packageDir === undefined) return undefined
+  try {
+    return JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/** Candidate profile directories, most specific first. */
+function profileDirs() {
+  const dirs = []
+  if (process.env.DSH_PROFILE_DIR) dirs.push(process.env.DSH_PROFILE_DIR)
+  const home = process.env.DSH_HOME && process.env.DSH_HOME !== '' ? process.env.DSH_HOME : dshHome()
   if (home) {
-    const profile = process.env.DSH_PROFILE && process.env.DSH_PROFILE !== '' ? process.env.DSH_PROFILE : 'web'
-    candidates.push(path.join(home, 'profiles', profile))
+    const profile = process.env.DSH_PROFILE && process.env.DSH_PROFILE !== '' ? process.env.DSH_PROFILE : 'desktop'
+    for (const name of [profile, 'desktop', 'web']) dirs.push(path.join(home, 'profiles', name))
+  }
+  return [...new Set(dirs)]
+}
+
+/**
+ * Locate an installed package directory without assuming one profile layout.
+ * @param {string} packageName
+ * @returns {Promise<string | undefined>}
+ */
+export async function installedPackageDir(packageName) {
+  for (const profileDir of profileDirs()) {
+    const candidate = path.join(profileDir, 'node_modules', packageName)
+    if (existsSync(path.join(candidate, 'package.json'))) return candidate
   }
-  for (const profileDir of candidates) {
+  return undefined
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+/** Runtime files that decide whether the loaded code actually changed. */
+async function hashRuntimeFiles(dir) {
+  const files = []
+  async function walk(current) {
+    let entries
     try {
-      return JSON.parse(await readFile(path.join(profileDir, 'node_modules', packageName, 'package.json'), 'utf8'))
+      entries = await readdir(current, { withFileTypes: true })
     } catch {
-      // try the next candidate
+      return
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === 'test' || entry.name === 'tests' || entry.name === 'fixtures' || entry.name === 'examples' || entry.name === '.git' || entry.name === '.github') continue
+      if (/^(license|notice|readme)/i.test(entry.name)) continue
+      const abs = path.join(current, entry.name)
+      if (entry.isDirectory()) {
+        await walk(abs)
+        continue
+      }
+      if (!entry.isFile()) continue
+      const ext = path.extname(entry.name).toLowerCase()
+      if (ext === '.md' || ext === '.markdown' || ext === '.map' || ext === '.d.ts' || ext === '.pdb') continue
+      if (entry.name === 'package.json') continue
+      try {
+        files.push(`${path.relative(dir, abs).split(path.sep).join('/')}:${sha256(await readFile(abs))}`)
+      } catch {
+        // unreadable runtime file: treating it as absent is safer than crashing
+      }
     }
   }
-  return undefined
+  await walk(dir)
+  files.sort()
+  return files
+}
+
+/**
+ * Snapshot the installed package's runtime identity. README/docs and the
+ * version field are excluded: those changes do not alter loaded code.
+ * @param {string} packageName
+ * @returns {Promise<{version: string, hash: string, clientHash: string, hasClient: boolean, dir: string} | null>}
+ */
+export async function capturePackageRuntime(packageName) {
+  const dir = await installedPackageDir(packageName)
+  if (dir === undefined) return null
+  try {
+    const manifest = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8'))
+    const files = await hashRuntimeFiles(dir)
+    const meta = {
+      main: manifest.main ?? null,
+      exports: manifest.exports ?? null,
+      dsh: manifest.dsh ?? null,
+      dependencies: manifest.dependencies ?? {},
+      peerDependencies: manifest.peerDependencies ?? {},
+    }
+    const clientFiles = files.filter((line) => /(^|[/\\])[^/\\]*client[^/\\]*\.(?:js|mjs|cjs|ts):/i.test(line))
+    return {
+      version: String(manifest.version ?? ''),
+      hash: sha256(`${JSON.stringify(meta)}\n${files.join('\n')}`),
+      clientHash: sha256(clientFiles.join('\n')),
+      hasClient: Boolean(manifest.dsh?.client),
+      dir,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Decide whether install results really require a restart. Bundle additions and
+ * changed runtime/client files do; no-op reinstall and metadata-only version
+ * bumps do not. A manager-applied in-place change needs no restart either.
+ * @param {{before: any, after: any, bundlesBefore: string[], bundlesAfter: string[], managerApplication: string}} input
+ */
+export function decideRestart({ before, after, bundlesBefore, bundlesAfter, managerApplication }) {
+  const beforeNames = new Set(bundlesBefore ?? [])
+  const afterNames = new Set(bundlesAfter ?? [])
+  const added = [...afterNames].filter((name) => !beforeNames.has(name))
+  const removed = [...beforeNames].filter((name) => !afterNames.has(name))
+  if (added.length > 0 || removed.length > 0) {
+    return { required: true, reason: `bundle set changed (${[...added, ...removed].join(', ')})`, bundleChanged: true, codeChanged: true, clientChanged: false, versionChanged: false }
+  }
+  if (!before || !after) {
+    const required = managerApplication === 'restart-required'
+    return { required, reason: required ? 'manager requested a restart (no runtime snapshot)' : 'manager applied it in place', bundleChanged: false, codeChanged: false, clientChanged: false, versionChanged: false }
+  }
+  const versionChanged = before.version !== after.version
+  const codeChanged = before.hash !== after.hash
+  const clientChanged = Boolean(before.hasClient && after.hasClient && before.clientHash !== after.clientHash)
+  if (!codeChanged) {
+    return { required: false, reason: versionChanged ? 'runtime files are unchanged (version label only)' : 'runtime files are unchanged', bundleChanged: false, codeChanged: false, clientChanged: false, versionChanged }
+  }
+  if (managerApplication === 'applied') {
+    return { required: false, reason: 'manager applied the change in place', bundleChanged: false, codeChanged: true, clientChanged, versionChanged }
+  }
+  return { required: true, reason: clientChanged ? 'client half changed' : 'runtime code changed', bundleChanged: false, codeChanged: true, clientChanged, versionChanged }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-resolver",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Agent-facing DSH plugin resolver: search the catalog, pick a version the running DSH accepts, install (registry or GitHub-source build), and verify - no trial and error.",
   "type": "module",
   "main": "index.js",