@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/argent-setup-check.mjs

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+/**
+ * argent-setup-check —— **安装后 setup 的只读自检入口**（0.6.0 W4）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 它回答的问题（一句话）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 「装上 bundle 之后，那四件副作用到底补齐了没有？」——**只读**读状态文件
+ * （`<数据目录>/setup-state.json`）**并且**实地探测一遍（venv 能不能跑、数据目录在不在、
+ * 凭据槽位在不在、定时器声明与当前宿主是否匹配），逐条给 ✅/❌ 与**怎么修**。
+ *
+ * ## 为什么"读状态文件 + 实地探测"两件都要做
+ *   · 只看状态文件 ⇒ 它可能停在上一轮（venv 事后被删/被换、凭据被清空）；
+ *   · 只探测 ⇒ 分不清"缺件"与"探测证据不足"（超时/文件不可读），会把不确定说成故障。
+ * 故：**探测为准，状态文件用于解释"为什么缺"与给出修法**。
+ *
+ * ## 退出码（照仓库既有的三态惯例）
+ *   · `0` = 全绿；
+ *   · `1` = 有红（确定的缺件）；
+ *   · `2` = **证据不足**（探测超时 / 拿不到状态文件 / 找不到插件包 / 数据目录判据不可用）
+ *          —— ⛔ 不把"不知道"说成"坏了"。
+ *
+ * ## 纪律
+ *   · **零写入**：本脚本一个字节都不写（连状态文件都不写；补建走宿主启动期或安装器）；
+ *   · **零网络**；⛔ **不打印任何凭据值**（只报槽位名在不在）；
+ *   · 判据全部来自插件包内的 `src/argent-setup.mjs`（⛔ 不在这里重写第二份），
+ *     数据目录仍走内核唯一判据（`core/lib/argent-datadir.mjs`）。
+ *
+ * 用法：
+ *   node scripts/argent-setup-check.mjs [--data-dir <目录>] [--state-only] [--json]
+ *                                       [--engine <插件包根>] [--scope-dir <dsh scope>]
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+const HERE = fileURLToPath(new URL('.', import.meta.url))
+const REPO = resolve(HERE, '..')
+
+/** 参数解析（未知参数 ⇒ 用法错误，退出 2）。 */
+export function parseArgs(argv = process.argv.slice(2)) {
+  const out = { dataDir: '', dshHome: '', engine: '', scopeDir: '', stateOnly: false, json: false, help: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--data-dir') { out.dataDir = String(argv[++i] || ''); continue }
+    if (a === '--dsh-home') { out.dshHome = String(argv[++i] || ''); continue }
+    if (a === '--engine') { out.engine = String(argv[++i] || ''); continue }
+    if (a === '--scope-dir') { out.scopeDir = String(argv[++i] || ''); continue }
+    if (a === '--state-only') { out.stateOnly = true; continue }
+    if (a === '--json') { out.json = true; continue }
+    if (a === '-h' || a === '--help') { out.help = true; continue }
+    return { ...out, error: `未知参数：${a}` }
+  }
+  return out
+}
+
+/**
+ * 找插件包里的判据实现（⛔ 不复制第二份）。
+ * 落点顺序：显式 `--engine` / `ARGENT_CORE_DIR` → 本仓库 → 安装克隆 → 各 profile 的 `node_modules`。
+ * 找不到 ⇒ 调用方按**证据不足**（exit 2）处置，而不是猜一个。
+ */
+export function engineCandidates({ env = process.env, home = homedir(), repo = REPO } = {}) {
+  const out = []
+  const push = (p) => { if (p && !out.includes(p)) out.push(p) }
+  push(env.ARGENT_CORE_DIR)
+  push(join(repo, 'plugins', 'argent-core', 'src', 'argent-setup.mjs'))
+  const dshHome = env.DSH_HOME || join(home, '.dsh')
+  for (const clone of [env.ARGENT_DISH_HOME, join(home, '.argent-dsh'), join(home, 'Code', 'argent-dsh')]) {
+    if (clone) push(join(clone, 'plugins', 'argent-core', 'src', 'argent-setup.mjs'))
+  }
+  const profile = env.DSH_PROFILE || 'web'
+  push(join(dshHome, 'profiles', profile, 'node_modules', '@whyshu', 'argent-core', 'src', 'argent-setup.mjs'))
+  // 其它 profile（不知名 ⇒ 扫一遍目录名，只读）
+  try {
+    for (const p of readdirSync(join(dshHome, 'profiles'))) {
+      push(join(dshHome, 'profiles', p, 'node_modules', '@whyshu', 'argent-core', 'src', 'argent-setup.mjs'))
+    }
+  } catch { /* 没有 profiles 目录 */ }
+  return out
+}
+
+/** dsh 作用域候选（判"原生排程在不在"）。 */
+export function scopeDirCandidates({ env = process.env, home = homedir() } = {}) {
+  const out = []
+  const dshHome = env.DSH_HOME || join(home, '.dsh')
+  if (env.DSH_SCOPE) out.push(env.DSH_SCOPE)
+  const profile = env.DSH_PROFILE || 'web'
+  out.push(join(dshHome, 'profiles', profile, 'node_modules', '@deepseek-ai'))
+  return out.filter(Boolean)
+}
+
+/** 逐条判据 → `{ id, ok, detail, fix }`；`ok === null` = 证据不足。 */
+export function buildChecks({ engine, dataDir, state, scopeDirs = [], stateOnly = false, probe = null, dshHome = '',
+  /** L1 判据（`scripts/lib/schedule-mechanism.mjs#detectScheduleMechanism()`）的现算结果；✅ 由 `main()` 注入 */
+  scheduleLive = null }) {
+  const checks = []
+  const venvDir = engine.venvDirOf(dataDir)
+  const venvPython = engine.venvLayout(venvDir).python
+
+  // ① 数据目录骨架（判据分档：**没有状态文件** ⇒ 这份安装压根没跑过 setup ⇒ 证据不足，⛔ 不刷红）
+  {
+    const missing = engine.REQUIRED_SUBDIRS.filter((s) => !existsSync(join(dataDir, s.name))).map((s) => s.name)
+    checks.push({
+      id: 'data-dir',
+      ok: missing.length === 0 ? true : (state ? false : null),
+      detail: missing.length === 0
+        ? `数据目录骨架齐（${dataDir}；${engine.REQUIRED_SUBDIRS.length} 项）`
+        : (state
+          ? `数据目录骨架缺 ${missing.join('/')}（${dataDir}）——状态文件说建过，但目录不在`
+          : `证据不足：骨架缺 ${missing.join('/')}，且没有状态文件 ⇒ 这份安装没跑过 setup（未安装）`),
+      fix: missing.length ? ['重跑宿主让插件补齐（启动期幂等 setup 会建）', '或手动：mkdir -p ' + missing.map((m) => join(dataDir, m)).join(' ')] : [],
+    })
+  }
+
+  // ② 状态文件（形状）
+  // ⚠️ 三态：**有文件且形状对** ⇒ 绿；**有这个文件但读不出形状** ⇒ 红（坏文件是真故障）；
+  //    **没有这个文件** ⇒ 证据不足（这份安装没跑过 setup —— 说它"坏"是冤枉，说它"好"是撒谎）。
+  {
+    const has = existsSync(engine.stateFile(dataDir))
+    checks.push({
+      id: 'state-file',
+      ok: state ? true : (has ? false : null),
+      detail: state
+        ? `状态文件在位（${engine.stateFile(dataDir)}；version=${state.version}；at=${state.at}）`
+        : (has
+          ? `状态文件在但**形状不认识**（${engine.stateFile(dataDir)}）——版本或字段对不上这份契约`
+          : `证据不足：没有状态文件（${engine.stateFile(dataDir)}）⇒ 这份安装没跑过安装后 setup`),
+      fix: state ? [] : ['重启宿主（插件启动期会写一次）', '或重跑安装器：node install-argent.mjs'],
+    })
+  }
+
+  // ③ Python 运行时（探测；state-only 时只看状态文件）
+  {
+    let verdict = null
+    if (!stateOnly) {
+      verdict = (probe || engine.probeVenv)(venvPython)
+    }
+    const step = state && state.steps ? state.steps['python-runtime'] : null
+    if (verdict) {
+      if (verdict.state === 'ready') {
+        checks.push({ id: 'python-runtime', ok: true, detail: `venv 可跑（${venvPython}；${engine.VENV_PKGS.join(' / ')} 可 import）`, fix: [] })
+      } else if (verdict.state === 'timeout') {
+        checks.push({
+          id: 'python-runtime',
+          ok: null,
+          detail: `证据不足：${verdict.reason}（${venvPython}）——⛔ 不判红`,
+          fix: ['重跑一次（机器忙时探测可能超时）', '仍超时再查：该解释器是否卡在 NFS/被杀软扫描'],
+        })
+      } else if (!state) {
+        // 没有状态文件 ⇒ 不知道这份安装的 venv 应不应该在（可能压根没装过）⇒ 证据不足
+        const at = verdict.path || venvPython
+        // 探测已经**读到了版本**时把它写进结论（差在版本上而不写版本号 = 现场要多跑一次才知道差多少）
+        const ver = verdict.foundVersion ? `（实测 ${verdict.foundVersion}）` : ''
+        checks.push({
+          id: 'python-runtime',
+          ok: null,
+          detail: `证据不足：${verdict.reason}${ver}（${at}），且没有状态文件 ⇒ 无法判断这份安装是否该有它`,
+          fix: ['重跑安装器补齐运行时：node install-argent.mjs --venv-only', '或重启宿主让插件后台补建'],
+        })
+      } else {
+        const repair = step && step.repair && Array.isArray(step.repair.lines) ? step.repair.lines : engine.repairHint({ dataDir }).lines
+        const at = verdict.path || venvPython
+        const ver = verdict.foundVersion ? `（实测 ${verdict.foundVersion}）` : ''
+        checks.push({ id: 'python-runtime', ok: false, detail: `${verdict.reason}${ver}：${at}`, fix: repair })
+      }
+    } else if (step) {
+      checks.push({
+        id: 'python-runtime',
+        ok: step.ok === true ? true : (step.ok === false ? false : null),
+        detail: `（--state-only）状态文件记：${step.detail}`,
+        fix: step.repair && Array.isArray(step.repair.lines) ? step.repair.lines : [],
+      })
+    } else {
+      checks.push({ id: 'python-runtime', ok: null, detail: '（--state-only）状态文件里没有这一步的记录', fix: ['重启宿主或重跑安装器'] })
+    }
+  }
+
+  // ④ 凭据槽位（只读键名）
+  {
+    // 凭据文件落点：显式 `--dsh-home` → 状态文件里记的宿主 home（插件写进去的那个）→ 环境/默认。
+    // ⛔ 绝不"猜"到另一个实例的凭据文件上（那会把别的实例的状态当成本机结论）。
+    const home = dshHome || (state && state.host && state.host.dshHome) || process.env.DSH_HOME || join(homedir(), '.dsh')
+    const file = join(home, '.credentials.yaml')
+    const names = engine.DEFAULT_CREDENTIAL_NAMES
+    if (!state) {
+      // ⛔ 没有状态文件 = 这份安装压根没跑过 setup ⇒ 凭据缺失不是"新故障"，
+      //    报成"证据不足"（否则全新目录会同时刷 4 条红，把真正的红灯埋掉）
+      checks.push({
+        id: 'credential-slots',
+        ok: null,
+        detail: `证据不足：没有状态文件，不知道这份安装声明了哪些槽位（当前看 ${file}）`,
+        fix: ['重启宿主（插件启动期会写一次状态）'],
+      })
+    } else {
+      const slots = engine.credentialSlotNames(file)
+      const missing = names.filter((n) => !slots.names.includes(n))
+      checks.push({
+        id: 'credential-slots',
+        ok: missing.length === 0,
+        detail: missing.length === 0
+          ? `凭据槽位齐（${names.join(' ')}；只读键名）`
+          : `凭据槽位缺：${missing.join(' ')}（${file}；${slots.reason}）——⛔ 这里不读值、也不代写`,
+        fix: missing.length ? ['在宿主里登录/填 Key（设置页 → Argent），或让安装器写入槽位', '自查：dsh credentials list'] : [],
+      })
+    }
+  }
+
+  // ⑤ 定时器（**唯一判据**在 L1：scripts/lib/schedule-mechanism.mjs；本处只做"状态文件 vs 现算"对账）
+  {
+    const step = state && state.steps ? state.steps.timer : null
+    // ⛔ 不再自己 `existsSync(join(d,'dsh-schedule'))` 粗判（那是第二份判据）——
+    //   判据走 L1 的同一份实现（声明面 = 注册表 `schedule.mechanism`，证据 = 原生包 / 已装计划任务）。
+    const live = scheduleLive || {
+      state: 'unknown', declared: 'unknown',
+      reason: '调用方没给现算判据（buildChecks 的 scheduleLive 缺省为空）', next: [],
+    }
+    if (!step) {
+      checks.push({
+        id: 'timer', ok: null,
+        detail: `（状态文件里没有定时器声明这一步）｜当前判据：${live.state}（${live.reason}）`,
+        fix: ['重启宿主让插件写一次声明', '或直接看判据：node scripts/argent-schedule.mjs mechanism'],
+      })
+    } else {
+      const recorded = String(step.mechanism || 'unknown')
+      // 判据（三态，⛔ 别把"缺证据"当"故障"）：
+      //   · 判据判红（`conflict`）⇒ 红；
+      //   · 现算给出**确定性**结论（native/activation-shim/none）却与状态文件记录不符 ⇒ 红（宿主/组合变了，需重启重写）；
+      //   · 现算 `unknown`（证据不足）∧ 状态文件**已有**记录 ⇒ **黄**：`ok=true` 但 `unknown=true`
+      //     （进不了"全绿"的结论行，但**不把已装好的机器判成坏的** —— 这正是 F1 的 npx 形态）；
+      //   · 现算 `unknown` ∧ 状态文件**没有**记录 ⇒ 证据不足（`ok=null` ⇒ 退出码 2）；
+      //   · 其余 ⇒ 绿。
+      const definite = ['native', 'activation-shim', 'none'].includes(live.state)
+      let okCode = null
+      let unknownFlag = false
+      let detail = ''
+      if (live.state === 'conflict') {
+        okCode = false
+        detail = `❌ 两个调度者同时在：${live.reason}`
+      } else if (definite && recorded !== live.state) {
+        okCode = false
+        detail = `状态文件记 ${recorded}，现算 ${live.state}（${live.reason}）⇒ 不一致（多半是宿主/组合变了，需重启重写）`
+      } else if (live.state === 'unknown') {
+        // 现算证据不足 ⇒ 与状态文件的记录**无法对账**（`unknown` 记录本身也等于"没记"）⇒ **黄**，⛔ 不判红。
+        okCode = true
+        unknownFlag = true
+        detail = `⚠️ 现算证据不足（${live.reason}）⇒ 沿用状态文件记录 ${recorded === 'unknown' ? '（记录也是 unknown）' : recorded}；⛔ 别顺手装 cron：${(live.next || [])[0] || ''}`
+      } else {
+        okCode = true
+        detail = `定时机制与判据一致（${live.state}｜声明 ${live.declared}）—— ${live.reason}`
+      }
+      checks.push({
+        id: 'timer', ok: okCode, ...(unknownFlag ? { unknown: true } : {}), detail,
+        fix: okCode === true ? [] : [
+          ...(live.state === 'conflict' ? ['二选一：关垫片（`bash scripts/flow-timers.sh uninstall --flow <flow>`）或关原生（会话内 `schedule_delete`）'] : []),
+          ...(live.state === 'unknown' ? (live.next || []) : []),
+          '自查：`node scripts/argent-schedule.mjs mechanism`（同一份判据）',
+        ].slice(0, 4),
+      })
+    }
+  }
+
+  return checks
+}
+
+/** 三态退出码：全绿 0 / 有红 1 / 证据不足（且无红）2。 */
+export function exitCodeOf(checks) {
+  if (checks.some((c) => c.ok === false)) return 1
+  if (checks.some((c) => c.ok === null)) return 2
+  return 0
+}
+
+async function main() {
+  const args = parseArgs()
+  if (args.error) {
+    console.error(`argent-setup-check: ✗ ${args.error}`)
+    console.log('用法：node scripts/argent-setup-check.mjs [--data-dir <目录>] [--dsh-home <宿主 home>] [--state-only] [--json]')
+    process.exit(2)
+  }
+  if (args.help) {
+    console.log('用法：node scripts/argent-setup-check.mjs [--data-dir <目录>] [--dsh-home <宿主 home>] [--state-only] [--json] [--engine <插件包根>] [--scope-dir <dsh scope>]')
+    process.exit(0)
+  }
+
+  // 判据实现（插件包内）——找不到 ⇒ 证据不足，⛔ 不猜
+  // ⚠️ 显式 `--engine` ⇒ 只认它：找不到就**响亮失败**（⛔ 不许悄悄退回自动探测 ——
+  //    "我明明指定了"必须是真话，否则测的是另一个副本而没有任何提示）
+  const explicitEngine = args.engine ? [join(args.engine, 'src', 'argent-setup.mjs')] : []
+  const enginePath = (explicitEngine.length ? explicitEngine : [...engineCandidates(), args.engine].filter(Boolean))
+    .find((p) => { try { return existsSync(p) } catch { return false } })
+  if (!enginePath) {
+    console.error('argent-setup-check: 证据不足 —— 找不到插件包内的判据实现（plugins/argent-core/src/argent-setup.mjs）')
+    console.error('  修法：--engine <仓库或克隆路径>，或设置 ARGENT_CORE_DIR')
+    process.exit(2)
+  }
+  let engine
+  try {
+    engine = await import(pathToFileURL(enginePath).href)
+  } catch (error) {
+    console.error(`argent-setup-check: 证据不足 —— 判据实现加载失败（${enginePath}）：${String((error && error.message) || error)}`)
+    process.exit(2)
+  }
+
+  // 数据目录：显式 → 内核唯一判据（⛔ 不自己拼第二份链）
+  let dataDir = args.dataDir
+  if (!dataDir) {
+    const kernelCands = [
+      join(REPO, 'core', 'lib', 'argent-datadir.mjs'),
+      join(process.env.ARGENT_DSH_REPO || '', 'core', 'lib', 'argent-datadir.mjs'),
+      join(process.env.ARGENT_DISH_HOME || join(homedir(), '.argent-dsh'), 'core', 'lib', 'argent-datadir.mjs'),
+      join(homedir(), 'Code', 'argent-dsh', 'core', 'lib', 'argent-datadir.mjs'),
+    ].filter(Boolean)
+    let kernel = null
+    for (const p of kernelCands) {
+      if (!existsSync(p)) continue
+      try {
+        const mod = await import(pathToFileURL(p).href)
+        if (mod && typeof mod.resolveDataDir === 'function') { kernel = mod; break }
+      } catch { /* 试下一个 */ }
+    }
+    if (!kernel) {
+      console.error('argent-setup-check: 证据不足 —— 内核数据目录判据取不到（core/lib/argent-datadir.mjs）')
+      console.error('  修法：--data-dir <你的数据目录>，或确认安装克隆里有 core/')
+      process.exit(2)
+    }
+    dataDir = kernel.resolveDataDir({ env: process.env }).dir
+  }
+
+  const state = engine.readSetupState(dataDir)
+  const scopeDirs = args.scopeDir ? [args.scopeDir] : scopeDirCandidates()
+  // ⑤ 定时机制的**现算判据**（唯一实现 = L1 schedule-mechanism；本文件不写第二份）
+  const dshHome = args.dshHome || process.env.DSH_HOME || join(homedir(), '.dsh')
+  const profile = process.env.DSH_PROFILE || 'web'
+  let scheduleLive = null
+  for (const p of [join(REPO, 'scripts', 'lib', 'schedule-mechanism.mjs'),
+    join(process.env.ARGENT_DSH_REPO || '', 'scripts', 'lib', 'schedule-mechanism.mjs'),
+    join(process.env.ARGENT_DISH_HOME || join(homedir(), '.argent-dsh'), 'scripts', 'lib', 'schedule-mechanism.mjs')].filter(Boolean)) {
+    if (!existsSync(p)) continue
+    try {
+      const mod = await import(pathToFileURL(p).href)
+      scheduleLive = await mod.detectScheduleMechanism({ dshHome, profile, repo: REPO, scopeDirs: scopeDirs.length ? scopeDirs : null })
+      break
+    } catch (error) {
+      scheduleLive = { state: 'unknown', declared: 'unknown', reason: `L1 判据加载/运行失败（${p}）：${String((error && error.message) || error).slice(0, 120)}`, next: [] }
+    }
+  }
+  if (!scheduleLive) scheduleLive = { state: 'unknown', declared: 'unknown', reason: '找不到 L1 判据模块（scripts/lib/schedule-mechanism.mjs）', next: ['确认安装克隆/仓库里有 scripts/lib/schedule-mechanism.mjs（同步面 scripts/）'] }
+  const checks = buildChecks({ engine, dataDir, state, scopeDirs, stateOnly: args.stateOnly, dshHome: args.dshHome, scheduleLive })
+  const code = exitCodeOf(checks)
+
+  if (args.json) {
+    console.log(JSON.stringify({ dataDir, engine: enginePath, exit: code, checks }, null, 2))
+  } else {
+    console.log(`\n安装后 setup 自检（只读）—— 数据目录：${dataDir}`)
+    for (const c of checks) {
+      const mark = c.ok === true ? '✅' : (c.ok === false ? '❌' : '❔')
+      console.log(`  ${mark} [${c.id}] ${c.detail}`)
+      if (c.ok !== true && c.fix.length) for (const f of c.fix) console.log(`       修法：${f}`)
+    }
+    const red = checks.filter((c) => c.ok === false).length
+    const unknown = checks.filter((c) => c.ok === null).length
+    console.log(`\n  结论：${code === 0 ? '全绿' : code === 1 ? `${red} 条红` : '证据不足（不判红）'}`
+      + `${unknown ? `；${unknown} 条证据不足` : ''}（退出码 ${code}）\n`)
+  }
+  process.exit(code)
+}
+
+if (isDirectRun(import.meta.url)) main()