dsh-vibe-math 2.3.11 → 2.3.13

package/installer.js

@@ -1,28 +1,36 @@
 // dsh-vibe-math merged bundle installer — VERSIONED AUTO-UPDATE.
 // When this bundle is installed (e.g. `dsh plugin add dsh-vibe-math` or from the
-// dsh-market), this plugin copies ALL THREE agent presets out of the package into
-// the DSH preset root, so the user immediately gets three presets in the picker:
+// dsh-market), this plugin copies ALL FOUR agent presets out of the package into
+// the DSH preset root, so the user immediately gets four presets in the picker:
 //   vibe-math-v2/  (probability-driven architecture)
 //   vibe-math-v3/  (THIRD-generation: paper-style Markdown knowledge base +
 //                   planner-agent scheduling + universal theory/method library)
 //   vibe-math-v4/  (FOURTH-generation: persistent self-organizing resident
 //                   subagents — message bus / meetings / unanimous-consensus
 //                   verification / per-resident libraries)
+//   vibe-math-v5/  (FIFTH-generation: research institute — academician who
+//                   assigns work, permanent researchers who vote, temp workers,
+//                   group chat + meetings + m-vote consensus)
 //
 // (vibe-math-v1 — the classic pipeline — was removed at v2.0.0; this bundle now
-//  ships v2/v3/v4 only.)
+//  ships v2/v3/v4/v5.)
 //
 // UPDATE POLICY (state recorded in <presetRoot>/.vibe-math-installed.json):
-//   - baseline (no state file — e.g. upgrading from an installer that predates
-//     this mechanism): every existing owned file is refreshed to the current
-//     package version and recorded as package-owned (user policy: auto-update
-//     old installs; any manual edits made before this baseline are overwritten
-//     once — from then on edits are protected).
-//   - upgrade (recorded version != current package.json version): every owned
-//     file that is byte-identical to the previously installed copy (i.e. NOT
-//     user-edited since) is overwritten with the new version; user-edited files
-//     are preserved and reported via the logger.
-//   - same version: no-op (idempotent). Missing files are ALWAYS restored.
+//   - FORCE-REPLACE ON VERSION CHANGE. When the recorded version differs from this package's
+//     version — or there is no record at all (an install made by an older installer) — every
+//     managed file is overwritten with the shipped bytes. This is deliberately NOT conditional on
+//     the file being unmodified. Two reasons:
+//       · a preset assembled from two different versions (the old policy updated a file's
+//         neighbours and kept the file the user had touched) is exactly the state that fails to
+//         mount or misbehaves subtly, and the user has no way to see that from the outside;
+//       · editing a shipped preset in place is not the supported way to customize one — DSH
+//         provides a real one (copy the preset: the picker's copy action, or a new directory
+//         under <presetRoot>), which leaves the managed set updatable.
+//   - Nothing is destroyed silently: before a file whose bytes are not what the installer last
+//     wrote is replaced, the user's copy is kept under
+//     <presetRoot>/.vibe-math-backup/<fromVersion>/<preset>/<file> and named in the log.
+//   - same version: no-op (idempotent) — restarting DSH never rewrites a file or churns the
+//     preset's generation stamp. Missing files are ALWAYS restored, at any version.
 //   - force a full refresh at any time: delete the preset dirs and restart DSH.
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, unlinkSync, rmdirSync } from 'node:fs'
 import { createRequire } from 'node:module'
@@ -33,7 +41,10 @@ import { fileURLToPath } from 'node:url'
 
 export const name = 'vibe-math-preset-installer'
 
-const PRESETS = [
+// Exported so the shipped policy suite can prove the managed list still covers what each preset
+// needs at runtime (a file present in the preset directory but missing here is copied by nobody,
+// and the installed preset then cannot mount).
+export const PRESETS = [
   {
     src: 'vibe-math-v2',
     dst: 'vibe-math-v2',
@@ -59,9 +70,34 @@ const PRESETS = [
 ]
 
 const STATE_FILE = '.vibe-math-installed.json'
+// where a replaced user edit is preserved; a leading dot keeps DSH's preset discovery from ever
+// treating it as a preset directory (ids must match [a-z0-9][a-z0-9-]*)
+const BACKUP_DIR = '.vibe-math-backup'
 
 function sha256(buf) { return createHash('sha256').update(buf).digest('hex') }
 
+/**
+ * Preserve one file that is about to be replaced by the shipped version, under
+ * `<presetRoot>/.vibe-math-backup/<fromVersion>/<preset>/<file>`.
+ *
+ * Returns `'written'` (a copy was made now), `'kept'` (a copy for this version was already there —
+ * the earliest edit is the one worth keeping, and a re-run must not overwrite it with an
+ * already-replaced file) or `'failed'`. A caller must not report `'kept'` as a failure: the user's
+ * bytes are preserved, just from an earlier run.
+ */
+function backupReplacedFile(presetRoot, fromVersion, presetDir, fileName, buf) {
+  try {
+    const dir = join(presetRoot, BACKUP_DIR, String(fromVersion || 'unversioned'), presetDir)
+    const dst = join(dir, fileName)
+    if (existsSync(dst)) return 'kept' // the earliest copy for this version is the one worth keeping
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(dst, buf)
+    return 'written'
+  } catch (e) {
+    return 'failed' // a backup failure must never stop the update; it is reported by the caller
+  }
+}
+
 function readState(path) {
   try {
     const raw = readFileSync(path, 'utf8')
@@ -99,22 +135,160 @@ function detectDshVersion() {
   return undefined
 }
 
+/**
+ * Minimal semver-range matcher for the host requirement.
+ *
+ * WHY THIS EXISTS: the DSH requirement a host is judged against lives in `package.json`
+ * (`engines.dsh` / `dsh.engines.dsh`) — the same declaration dsh-market shows on a plugin's card.
+ * Judging the host by a *second* source (the `dsh.compatibility.dshReleases` map) let the two
+ * disagree: the card could say "compatible" while this self-check warned, or the reverse. So the
+ * range is evaluated here, and the map remains only a fallback for manifests that declare no range.
+ *
+ * Supported: `*`, exact, `^`, `~`, `>=`, `>`, `<=`, `<`, whitespace-separated sets, `||`
+ * alternatives — everything the ecosystem publishes (see `dshmarket`'s own
+ * `^0.1.0-rc.7 || ^0.1.1-rc.2 || ^0.1.2-alpha.2` shape). Anything else returns null = unknown
+ * (reported, never asserted), never a silent "incompatible".
+ *
+ * PRERELEASE RULE (npm's, applied per comparator SET — one `||` alternative is one set): a version
+ * carrying a prerelease tag satisfies a set only when at least one comparator in that set shares its
+ * [major, minor, patch] tuple AND carries a prerelease of its own. This is why
+ * `>=0.1.2-rc.1 <0.2.0` does NOT match `0.1.5-rc.2`, and why this package declares explicit
+ * per-tuple branches instead. Callers pass `includePrerelease: true` for host checks because every
+ * published DSH release line is itself a prerelease.
+ */
+export function satisfiesDshRange(version, range, options = {}) {
+  const v = parseSemver(version)
+  if (v === null || typeof range !== 'string' || range.trim() === '') return null
+  const versionHasPre = v.pre.length > 0
+  let sawUnknown = false
+  for (const set of range.split('||')) {
+    const parts = set.trim().split(/\s+/).filter((p) => p !== '')
+    if (parts.length === 0) return true // an empty alternative is `*`
+    const parsed = parts.map(comparator)
+    if (parsed.some((p) => p === null)) { sawUnknown = true; continue }
+    if (versionHasPre && options.includePrerelease !== true) {
+      const admitted = parsed.some((p) => p.target !== null && p.target.pre.length > 0 &&
+        p.target.major === v.major && p.target.minor === v.minor && p.target.patch === v.patch)
+      if (!admitted) continue
+    }    if (parsed.every((p) => matchesComparator(v, p))) return true
+  }
+  return sawUnknown ? null : false
+}
+
+function parseSemver(value) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(String(value == null ? '' : value).trim())
+  if (m === null) return null
+  const pre = m[4] === undefined ? [] : m[4].split('.')
+  for (const id of pre) if (/^\d+$/.test(id) && id.length > 1 && id[0] === '0') return null
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre }
+}
+
+function compareSemver(a, b) {
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1
+  if (a.pre.length === 0 && b.pre.length === 0) return 0
+  if (a.pre.length === 0) return 1  // a release outranks its prereleases
+  if (b.pre.length === 0) return -1
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    const x = a.pre[i], y = b.pre[i]
+    if (x === undefined) return -1
+    if (y === undefined) return 1
+    const xn = /^\d+$/.test(x), yn = /^\d+$/.test(y)
+    if (xn && yn) { const d = Number(x) - Number(y); if (d !== 0) return d < 0 ? -1 : 1; continue }
+    if (xn !== yn) return xn ? -1 : 1 // numeric identifiers sort below alphanumeric ones
+    if (x !== y) return x < y ? -1 : 1
+  }
+  return 0
+}
+
+/** One comparator such as `^0.1.0-rc.7`. Returns null when the target is not a version. */
+function comparator(part) {
+  const p = part.trim()
+  // `*`, `x`, `X` and an empty token mean "any version" (npm: still not a prerelease unless the
+  // caller opts into includePrerelease — the set-level gate below is what enforces that).
+  if (p === '' || p === '*' || p === 'x' || p === 'X') return { op: 'any', target: null }
+  const m = /^(\^|~|>=|<=|>|<)?(.*)$/.exec(p)
+  const op = m === null || m[1] === undefined ? '' : m[1]
+  const target = parseSemver(m === null ? '' : m[2])
+  return target === null ? null : { op, target }
+}
+
+function matchesComparator(v, { op, target }) {
+  if (op === 'any') return true
+  const c = compareSemver(v, target)
+  switch (op) {
+    case '': return c === 0
+    case '>=': return c >= 0
+    case '>': return c > 0
+    case '<=': return c <= 0
+    case '<': return c < 0
+    case '^': {
+      const upper = target.major > 0
+        ? { major: target.major + 1, minor: 0, patch: 0, pre: [ '0' ] }
+        : target.minor > 0
+          ? { major: 0, minor: target.minor + 1, patch: 0, pre: [ '0' ] }
+          : { major: 0, minor: 0, patch: target.patch + 1, pre: [ '0' ] }
+      return c >= 0 && compareSemver(v, upper) < 0
+    }
+    case '~': {
+      const upper = { major: target.major, minor: target.minor + 1, patch: 0, pre: [ '0' ] }
+      return c >= 0 && compareSemver(v, upper) < 0
+    }
+    default: return false
+  }
+}
+
+/**
+ * The host verdict for a DSH version against a package manifest.
+ * Prefers the declared range (`engines.dsh`, then `dsh.engines.dsh`); falls back to the
+ * `dsh.compatibility.dshReleases` map so packages that declare only that keep working.
+ */
+export function dshVersionVerdict(version, manifest) {
+  const pkg = manifest && typeof manifest === 'object' ? manifest : {}
+  const declared = (pkg.engines && typeof pkg.engines.dsh === 'string' && pkg.engines.dsh.trim() !== '')
+    ? pkg.engines.dsh
+    : (pkg.dsh && pkg.dsh.engines && typeof pkg.dsh.engines.dsh === 'string' && pkg.dsh.engines.dsh.trim() !== '')
+      ? pkg.dsh.engines.dsh
+      : null
+  if (declared !== null) {
+    // includePrerelease: the whole published DSH line is prerelease builds.
+    const sat = satisfiesDshRange(version, declared, { includePrerelease: true })
+    return {
+      basis: 'engines',
+      requirement: declared,
+      status: sat === true ? 'compatible' : sat === false ? 'incompatible' : 'unknown',
+    }
+  }
+  const rel = (pkg.dsh && pkg.dsh.compatibility && pkg.dsh.compatibility.dshReleases) || {}
+  const status = rel[version]
+  if (status === 'compatible' || status === 'incompatible') {
+    return { basis: 'dshReleases', requirement: null, status }
+  }
+  return { basis: 'dshReleases', requirement: null, status: status === 'unknown' ? 'unknown' : 'undeclared' }
+}
+
 async function checkHostCapabilities(ctx, logger) {
   const problems = []
   // 1) DSH version compatibility (best-effort, only when the version is detectable).
-  //    Declared under package.json dsh.compatibility.dshReleases (per the DSH STORE contract):
-  //    each full DSH release maps to 'compatible' | 'incompatible' | 'unknown'. A version that is
-  //    absent or 'unknown' is a soft warning; 'incompatible' is a hard "please use X" message.
-  let dshRel = {}
-  try { const m = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8')); dshRel = (m.dsh && m.dsh.compatibility && m.dsh.compatibility.dshReleases) || {} } catch (e) {}
+  //    The AUTHORITATIVE source is the declared range `engines.dsh` / `dsh.engines.dsh` — the same
+  //    field dsh-market renders on the plugin card, so the two verdicts cannot disagree. The
+  //    `dsh.compatibility.dshReleases` map is the fallback for manifests without a range.
+  let manifest = {}
+  try { manifest = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8')) } catch (e) {}
+  const dshRel = (manifest.dsh && manifest.dsh.compatibility && manifest.dsh.compatibility.dshReleases) || {}
   const supported = Object.keys(dshRel).sort()
   const dshVersion = detectDshVersion()
   if (dshVersion) {
-    const status = dshRel[dshVersion]
-    if (status === 'incompatible') {
-      problems.push('当前 DSH 版本 v' + dshVersion + ' 被本包声明为 incompatible；请使用 ' + supported.join(' / ') + '。')
-    } else if (status === undefined || status === 'unknown') {
+    const verdict = dshVersionVerdict(dshVersion, manifest)
+    if (verdict.status === 'incompatible') {
+      problems.push(verdict.basis === 'engines'
+        ? '当前 DSH 版本 v' + dshVersion + ' 不满足本包声明的宿主版本要求（engines.dsh = ' + verdict.requirement + '）。'
+        : '当前 DSH 版本 v' + dshVersion + ' 被本包声明为 incompatible；请使用 ' + supported.join(' / ') + '。')
+    } else if (verdict.status === 'undeclared' || (verdict.status === 'unknown' && verdict.basis === 'dshReleases')) {
       problems.push('当前 DSH 版本 v' + dshVersion + ' 尚未被本包声明为兼容（dshReleases 仅声明 ' + supported.join(' / ') + '）；建议使用 ' + supported.join(' / ') + '，或将该版本在 dshReleases 中标注后再自行验证。')
+    } else if (verdict.status === 'unknown' && verdict.basis === 'engines') {
+      problems.push('当前 DSH 版本 v' + dshVersion + ' 无法与 engines.dsh 的范围比对（声明值 ' + verdict.requirement + ' 不是本安装器能解析的范围）；请按该范围自行确认。')
     }
   }
   // 2) capability self-check (the authoritative mounting gate; also covers hosts whose version
@@ -209,11 +383,23 @@ export async function apply(ctx) {
     const state = readState(stateFile)
     const prevFiles = (state && state.files) || {}
     const isUpgrade = state !== null && pkgVersion !== '' && state.version !== pkgVersion
-    const isBaseline = state === null // no recorded history → refresh everything (user policy: auto-update old installs)
+    const isBaseline = state === null // no recorded history → refresh everything
+    // A version change (or a first sighting) REPLACES the managed files; only a same-version boot
+    // leaves the working tree alone. See UPDATE POLICY at the top of this file.
+    const refresh = isBaseline || isUpgrade
+    const fromVersion = (state && state.version) || '(unversioned)'
+    if (pkgVersion === '') {
+      // Without a version there is nothing to compare against, so this run must NOT replace
+      // anything (a wrong guess would overwrite files for no reason); it still restores missing
+      // ones and keeps the previously recorded version, so the next readable run reports the
+      // right "from" version.
+      logger?.warn?.('[dsh-vibe-math] 读不到本包版本（package.json 缺失或损坏）：本次不做版本比对，只补回缺失的 preset 文件。')
+    }
 
     const nextFiles = {}
-    let installed = 0, updated = 0, kept = 0
-    const keptList = []
+    let installed = 0, updated = 0, kept = 0, backedUp = 0
+    const replacedEdits = []
+    const backupFailures = []
 
     for (const p of PRESETS) {
       const srcDir = join(here, p.src)
@@ -234,32 +420,35 @@ export async function apply(ctx) {
           nextFiles[key] = { hash: curHash, provenance: 'package' }
           continue
         }
-        const destHash = sha256(readFileSync(d))
-        if (isBaseline) {
-          // no recorded history: refresh to the current package (one-time; edits
-          // made before this mechanism are overwritten, later edits are protected)
-          if (destHash === curHash) { nextFiles[key] = { hash: curHash, provenance: 'package' } }
-          else { writeFileSync(d, cur); updated += 1; nextFiles[key] = { hash: curHash, provenance: 'package' } }
-          continue
-        }
+        const destBuf = readFileSync(d)
+        const destHash = sha256(destBuf)
         const prev = prevFiles[key]
         const prevRec = (prev && typeof prev === 'object') ? prev : { hash: prev, provenance: 'package' }
-        const prevProv = (prevRec.provenance === 'user') ? 'user' : 'package' // 未知来源按包文件处理
-        if (prevProv === 'package' && destHash === prevRec.hash) {
-          // 包文件且未被改动 → 可安全升级（内容相同则跳过写入）
-          if (destHash !== curHash) { writeFileSync(d, cur); updated += 1 }
+        if (destHash === curHash) {
+          // already the shipped bytes: never rewrite, so the file's mtime (which keys the preset's
+          // DSH generation) stays put
           nextFiles[key] = { hash: curHash, provenance: 'package' }
-        } else if (prevProv === 'user') {
-          // 用户持有 → 永不覆盖
-          kept += 1
-          if (isUpgrade) keptList.push(key + ' (用户持有)')
-          nextFiles[key] = { hash: destHash, provenance: 'user' }
-        } else {
-          // 包文件但自上次安装后已被用户改动
+          continue
+        }
+        if (!refresh) {
+          // same version: nothing is being updated, so a file that differs from the package is left
+          // exactly as it is. The recorded hash stays "what this installer last wrote" (or unknown),
+          // so the drift is still recognised — and backed up — at the next version change.
           kept += 1
-          if (isUpgrade) keptList.push(key + ' (已修改)')
-          nextFiles[key] = { hash: destHash, provenance: 'user' }
+          nextFiles[key] = typeof prevRec.hash === 'string' ? { hash: prevRec.hash, provenance: 'package' } : { provenance: 'package' }
+          continue
+        }
+        // replacing: preserve the user's bytes when they are not what this installer last wrote
+        // (a legacy state without a hash cannot tell, so it backs the file up rather than risk it)
+        if (typeof prevRec.hash !== 'string' || destHash !== prevRec.hash) {
+          const backupResult = backupReplacedFile(presetRoot, fromVersion, p.dst, f, destBuf)
+          if (backupResult === 'failed') backupFailures.push(key)
+          else backedUp += 1
+          replacedEdits.push(key)
         }
+        writeFileSync(d, cur)
+        updated += 1
+        nextFiles[key] = { hash: curHash, provenance: 'package' }
       }
     }
 
@@ -293,22 +482,38 @@ export async function apply(ctx) {
       if (dirEmpty && existsSync(dir)) { try { rmdirSync(dir); removedDirs.push(dir) } catch (e) {} }
     }
 
-    writeState(stateFile, { version: pkgVersion, files: nextFiles, updatedAt: Date.now() })
+    writeState(stateFile, { version: pkgVersion || (state && state.version) || '', files: nextFiles, updatedAt: Date.now() })
 
     if (removedFiles > 0 || removedDirs.length > 0) {
       logger?.info?.('[dsh-vibe-math] preset cleanup: removed ' + removedFiles + ' file(s) from ' + removedDirs.length + ' stale preset dir(s) (' + removedDirs.map(d => d.split(/[\\/]/).pop()).join(', ') + ') that are no longer shipped.')
     }
 
     if (isUpgrade) {
-      logger?.info?.('[dsh-vibe-math] preset auto-update: version ' + (state.version || '(none)') + ' → ' + pkgVersion +
-        ' — 新增 ' + installed + ' 个文件，更新 ' + updated + ' 个文件' +
-        (kept > 0 ? '，保留 ' + kept + ' 个未覆盖文件（' + keptList.join('; ') + '）' : '') +
-        '。新版本 preset 将在新会话生效。')
+      logger?.info?.('[dsh-vibe-math] preset auto-update: version ' + fromVersion + ' → ' + pkgVersion +
+        ' — 新增 ' + installed + ' 个文件，更新 ' + updated + ' 个文件。' +
+        (replacedEdits.length > 0
+          ? '其中 ' + replacedEdits.length + ' 个文件与上一次安装的字节不同（被改过），已按版本一致化覆盖' +
+            (backupFailures.length === 0
+              ? '，原文备份在 ' + join(presetRoot, BACKUP_DIR, String(fromVersion)) + '：' + replacedEdits.join(', ')
+              : '；这 ' + backupFailures.length + ' 个文件**备份失败**（原文未保留）：' + backupFailures.join(', ')) +
+            '。要自定义 preset，请复制一份而不是改这几个文件——被管理的文件在下一次版本变更时一定会被替换。'
+          : '') +
+        '新版本 preset 将在新会话生效。')
     } else if (isBaseline) {
       logger?.info?.('[dsh-vibe-math] preset baseline: refreshed ' + (installed + updated) + ' file(s) to v' + pkgVersion +
-        ' — 已启用自动更新（后续版本升级将自动替换未被手动修改的 preset 文件）。')
+        (replacedEdits.length > 0
+          ? '，其中 ' + replacedEdits.length + ' 个原有文件与随包版本不同' +
+            (backupFailures.length === 0 ? '，原文已备份在 ' + join(presetRoot, BACKUP_DIR, String(fromVersion))
+              : '，但有 ' + backupFailures.length + ' 个备份失败（原文未保留）：' + backupFailures.join(', '))
+          : '') +
+        ' — 已启用版本化自动更新（后续版本变更会直接替换被管理的 preset 文件）。')
     } else if (installed > 0) {
       logger?.info?.('[dsh-vibe-math] restored ' + installed + ' missing preset file(s)')
+    } else if (kept > 0) {
+      // same version, and some managed file on disk differs from the package: reported, never
+      // rewritten mid-version (it is replaced, with a backup, at the next version change)
+      logger?.info?.('[dsh-vibe-math] preset files untouched (v' + pkgVersion + ' unchanged): ' + kept +
+        ' file(s) differ from the shipped copy; they will be replaced on the next version change (原件会先备份)')
     }
     await checkHostCapabilities(ctx, logger)
   } catch (err) {