@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/scope-pointer.mjs

@@ -0,0 +1,164 @@
+/**
+ * scope-pointer —— "默认入口指向哪棵 dsh 树"的**唯一真源**（P5，2026-09-29）
+ *
+ * 为什么要有它：升级会重建全局 bin 链接（`/opt/homebrew/bin/dsh`），而 LaunchAgent 又跟着
+ * 那个链接走 ⇒ 升级失败时服务被 KeepAlive 无限重启进坏版本，操作者（agent）自己也跑在那棵树里，
+ * 没有立足点自救。把"默认入口"变成**一个可原子改写的指针文件**后：
+ *   · 切换版本 = 改指针（不需要 sudo、不需要动 plist）；
+ *   · 失败熔断 = 把指针改回上一棵 known-good 树（见 dsh-web-launch.mjs）；
+ *   · 救援面/实验面各自用独立入口，互不干扰。
+ *
+ * 布局：`<DSH_HOME>/argent/base/current-scope`（单行：目标树绝对路径）
+ *       `<DSH_HOME>/argent/base/scope-history.jsonl`（每次切换追加审计）
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const POINTER_REL = join('argent', 'base', 'current-scope')
+export const HISTORY_REL = join('argent', 'base', 'scope-history.jsonl')
+
+export const dshHome = (env = process.env) => env.DSH_HOME || join(env.HOME || homedir(), '.dsh')
+export const pointerPath = (env = process.env) => join(dshHome(env), POINTER_REL)
+export const historyPath = (env = process.env) => join(dshHome(env), HISTORY_REL)
+
+/**
+ * 校验一棵树**能不能跑**：
+ *   ① 有 `dsh/lib/bin.js`；
+ *   ② 路径里必须含 `node_modules` —— Node 解析裸包名（`@deepseek-ai/dsh-app-boot` 等）
+ *      要靠 `node_modules` 这一层；放在普通目录里的整树备份**跑不起来**
+ *      （2026-09-29 实测：`~/.dsh/argent/backup/.../scope` 直接 `node scope/dsh/lib/bin.js`
+ *      报 `ERR_MODULE_NOT_FOUND`）。把这条并进"能不能当默认入口"的判据，避免把指针
+ *      指到一棵起不来的树上。
+ */
+export function looksLikeScope(dir) {
+  if (!dir || !existsSync(dir)) return false
+  let real = dir
+  try { real = realpathSync(dir) } catch { /* 用原路径判断 */ }
+  if (!real.split('/').includes('node_modules')) return false
+  return existsSync(join(dir, 'dsh', 'lib', 'bin.js')) || existsSync(join(dir, 'dsh', 'lib', 'bin.mjs'))
+}
+
+/** 只判断"有没有 dsh 入口"（不含布局约束）—— 用于给备份树提示"需要搬家才能用"。 */
+export function hasDshEntry(dir) {
+  if (!dir || !existsSync(dir)) return false
+  return existsSync(join(dir, 'dsh', 'lib', 'bin.js')) || existsSync(join(dir, 'dsh', 'lib', 'bin.mjs'))
+}
+
+/** 读指针（不存在或指向不存在的树 ⇒ null）。 */
+export function readPointer(env = process.env) {
+  const p = pointerPath(env)
+  if (!existsSync(p)) return null
+  const v = readFileSync(p, 'utf8').trim()
+  return v || null
+}
+
+/**
+ * 原子写指针 + 记审计。
+ * @param {string} scopeDir 目标树（必须是 `<...>/lib/node_modules/@deepseek-ai` 形态）
+ * @param {{env?: object, reason?: string, previous?: string|null, force?: boolean}} [opts]
+ */
+export function writePointer(scopeDir, opts = {}) {
+  const env = opts.env || process.env
+  if (!opts.force && !looksLikeScope(scopeDir)) {
+    throw new Error(`目标不像 dsh 安装树（缺 dsh/lib/bin.js）：${scopeDir}`)
+  }
+  const p = pointerPath(env)
+  mkdirSync(dirname(p), { recursive: true })
+  const tmp = `${p}.tmp-${process.pid}`
+  writeFileSync(tmp, `${scopeDir}\n`)
+  renameSync(tmp, p)                       // 原子替换：读者永远看到完整内容
+  const previous = opts.previous !== undefined ? opts.previous : null
+  try {
+    appendFileSync(historyPath(env), `${JSON.stringify({
+      at: new Date().toISOString(), scopeDir, previous, reason: opts.reason || '',
+    })}\n`)
+  } catch { /* 审计写不进去不该拦住切换本身 */ }
+  return p
+}
+
+/** 最近 N 条切换记录（排查用）。 */
+export function readHistory(env = process.env, limit = 20) {
+  const p = historyPath(env)
+  if (!existsSync(p)) return []
+  return readFileSync(p, 'utf8').split('\n').filter(Boolean).slice(-limit).map((l) => {
+    try { return JSON.parse(l) } catch { return { raw: l } }
+  })
+}
+
+/**
+ * 熔断状态：记录启动失败并在连续失败达阈值时**建议**回退目标。
+ * 事件文件：`<DSH_HOME>/argent/base/launch-failures.jsonl`
+ */
+export const failuresPath = (env = process.env) => join(dshHome(env), 'argent', 'base', 'launch-failures.jsonl')
+
+export function recordFailure(env, info) {
+  const p = failuresPath(env)
+  mkdirSync(dirname(p), { recursive: true })
+  appendFileSync(p, `${JSON.stringify({ at: new Date().toISOString(), ...info })}\n`)
+  return p
+}
+
+/**
+ * 连续失败计数：从最新往回数，遇到 `ok: true` 或超过 `windowMs` 即停。
+ * @returns {{count: number, lastAt: string|null}}
+ */
+export function consecutiveFailures(env = process.env, { windowMs = 10 * 60 * 1000, now = Date.now() } = {}) {
+  const p = failuresPath(env)
+  if (!existsSync(p)) return { count: 0, lastAt: null }
+  const lines = readFileSync(p, 'utf8').split('\n').filter(Boolean)
+  let count = 0
+  let lastAt = null
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    let e
+    try { e = JSON.parse(lines[i]) } catch { continue }
+    const t = Date.parse(e.at || '')
+    if (!Number.isFinite(t) || now - t > windowMs) break
+    if (e.ok === true) break
+    if (e.ok === false) { count += 1; lastAt = e.at || lastAt }
+  }
+  return { count, lastAt }
+}
+
+/** 找到该树的"上一棵 known-good"：取审计里最近一次不同的 scopeDir（可被显式覆盖）。 */
+export function previousScope(env = process.env, current = null) {
+  const hist = readHistory(env, 100).reverse()
+  for (const h of hist) {
+    if (!h.scopeDir || h.scopeDir === current) continue
+    if (looksLikeScope(h.scopeDir)) return h.scopeDir
+  }
+  return null
+}
+
+
+/**
+ * 「已熔断」标记（P5，2026-09-29）。
+ *
+ * 为什么需要它：plist 里是 `KeepAlive: true` —— 启动器即使放弃并 `exit 78`，launchd 也**照样再拉起**，
+ * 于是"停止自动重试"只是一句话（实测撞了 18 次）。真正的停止有两层：
+ *   ① 放弃时 `launchctl bootout` 掉这个 job（launchd 不再拉起）；
+ *   ② 落一个标记文件：万一有人/别的机制再把它拉起来，启动器**直接拒绝启动**并打印恢复指引 ——
+ *      否则"回退目标也起不来"的坏状态会被无限重演。
+ * 解除：人在确认修好后 `--reset-fuse`（或走 `dsh-restore.sh --to`，人工还原本身即"我已介入"的信号）。
+ */
+export const FUSED_REL = join('argent', 'base', 'fused.json')
+export const fusedPath = (env = process.env) => join(dshHome(env), FUSED_REL)
+
+export function readFused(env = process.env) {
+  const p = fusedPath(env)
+  if (!existsSync(p)) return null
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return { raw: true } }
+}
+
+export function writeFused(env, info) {
+  const p = fusedPath(env)
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, `${JSON.stringify({ at: new Date().toISOString(), ...info }, null, 2)}\n`)
+  return p
+}
+
+export function clearFused(env = process.env) {
+  const p = fusedPath(env)
+  if (!existsSync(p)) return false
+  try { rmSync(p); return true } catch { return false }
+}