@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/check-config-catalog.mjs

@@ -0,0 +1,677 @@
+#!/usr/bin/env node
+/**
+ * check-config-catalog.mjs —— **配置地基的四道门禁**（2026-10-09）
+ *
+ * 契约：`docs/Argent-宿主适配契约.md` §7（配置目录 + 通用读取器 + 四道门禁 + 分类树）。
+ * 读取器（**唯一实现**）：`core/lib/config-catalog.mjs`；本文件只做**扫描与判定**，
+ * ⛔ 不另写一份解析链、不另写一份声明校验（全部调读取器的 `validate()`）。
+ *
+ * ## 四道门禁（逐条都可单独跑：`--gate 1|2|3|4`）
+ *
+ * | # | 名称 | 判据 | 假绿防线（本门禁自己也要能被反证） |
+ * |---|---|---|---|
+ * | ① | **双向对账** | (a) 代码里 `cfg.get('k')` / `require('k')` 一类**字面量读**的 key 必须已声明；(b) **每个非 server 声明**都必须有"被读"证据（字面量读 **或** `binding` 指向的 env 名/文件/字段在代码里**真被引用**）；(c) 声明形状合法、key 与环境变量名**一一对应**（不得两个 key 归一成同名 env，否则进程 env 覆盖会串项） | 扫描面必须 >0 文件；`--selftest` 注入"读了没声明 / 声明了没人读 / 两个 key 归一撞名"三种假象，**必须逐条变红** |
+ * | ② | **敏感不出门** | `secret: true` 的项：`describe()` 载荷里**没有值**（也没有长度/默认值）；`require()` 报错文本里没有值；目录文件里没有 `example/sample/value` 这类真实样例字段、没有非空 `default`；**用诱饵值**（`DECOY-<随机>`）真写进各种来源后，载荷 + 报错 + 全仓库文本里都搜不到它 | 诱饵值必须**先证明能被读到**（`get()` 拿得到）⇒ 才说明"搜不到"不是因为它根本没生效 |
+ * | ③ | **必须项可解析** | `required: true` 的项在**空环境**（`env={}` + 空数据目录 + 无 default）下调用 `require()` 必须抛 `ConfigMissingError`，且消息里**点名 key** + **给出可执行落点** + **列出已试来源**；同时：真机上所有 required 项必须能解析（否则装机就是断的） | required 项数必须 >0（否则这条门禁是空跑）；夹具里放一个"故意配不齐"的 required 项，断言报错**真的指路** |
+ * | ④ | **新增即生效** | 在夹具目录里**加一条新声明**（不改读取器、不改任何 UI 代码）⇒ 它必须出现在 `describe()` 载荷里，且 `get()/sourceOf()` 立刻可用；删掉文件 ⇒ 立刻消失（缓存不得留残影） | 断言"夹具新项"与"真仓库原项"**同时**在载荷里（证明是增量而不是替换） |
+ *
+ * ## 用法
+ *   node scripts/check-config-catalog.mjs                 # 只报告，**恒 exit 0**
+ *   node scripts/check-config-catalog.mjs --strict        # 任一门禁红 ⇒ exit 1（CI / 手动）
+ *   node scripts/check-config-catalog.mjs --json          # 机器可读（含树/载荷摘要）
+ *   node scripts/check-config-catalog.mjs --list          # 按分类打印所有可配项（人读；secret 只显示已配置态）
+ *   node scripts/check-config-catalog.mjs --describe      # 打**脱敏载荷**（= 设置页拿到的形状）
+ *   node scripts/check-config-catalog.mjs --gate 3        # 只跑第 3 道
+ *   node scripts/check-config-catalog.mjs --selftest      # 只跑"门禁自证"（注入假象必须变红）
+ *   node scripts/check-config-catalog.mjs --root <dir> --data-dir <dir>   # 夹具（只读）
+ *
+ * ## 纪律
+ *   · **只读**：不改任何配置、不写数据目录、不联网；
+ *   · 门禁脚本自身**不含业务词**（`vertical-lint` 会扫 `scripts/`）：分类树、key、归属
+ *     一律从目录文件**读**出来，⛔ 不在这里硬编码任何业务线/能力名；
+ *   · secret 项在**任何**输出路径上都只呈现"已配置/未配置 + 来源"。
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  LAYERS, RESOLUTION_ORDER, SOURCES, createReader, envNameOf, validateCatalog,
+} from '../core/lib/config-catalog.mjs'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+const argOf = (name, dflt = null) => {
+  const i = argv.indexOf(name)
+  return i >= 0 ? argv[i + 1] ?? dflt : dflt
+}
+const STRICT = has('--strict')
+const JSON_OUT = has('--json')
+const root = resolve(argOf('--root', REPO))
+const dataDir = argOf('--data-dir', null)
+const onlyGate = argOf('--gate', null)
+
+const problems = []
+const notes = []
+const red = (gate, msg) => problems.push({ gate, msg })
+
+// ══════════════════════════════════════════════════════════════════════════
+// 扫描面：代码里"真被读"的证据
+// ══════════════════════════════════════════════════════════════════════════
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '__pycache__', 'dist', 'attic', 'vendor', 'archive', 'backups'])
+const CODE_RE = /\.(mjs|js|cjs|py|sh|rb)$/
+
+function walk(dir, out = [], depth = 0) {
+  if (depth > 8) return out
+  let entries = []
+  try { entries = readdirSync(dir) } catch { return out }
+  for (const e of entries) {
+    if (SKIP_DIRS.has(e) || e.startsWith('.')) continue
+    const p = join(dir, e)
+    let st
+    try { st = statSync(p) } catch { continue }
+    if (st.isDirectory()) walk(p, out, depth + 1)
+    else out.push(p)
+  }
+  return out
+}
+
+/** 剥注释（JS 行/块、Python/Shell `#`）——防"注释里提了一句"被当成读取证据。 */
+function stripComments(text, file) {
+  if (/\.(py|sh|rb)$/.test(file)) return text.replace(/^[ \t]*#.*$/gm, '')
+  let out = ''
+  let i = 0
+  let state = 'code'
+  const n = text.length
+  while (i < n) {
+    const c = text[i]
+    const c2 = text[i + 1]
+    const esc = i > 0 && text[i - 1] === '\\'
+    if (state === 'code') {
+      if (c === '/' && c2 === '/' && !esc) { state = 'line'; i += 2; continue }
+      if (c === '/' && c2 === '*' && !esc) { state = 'block'; i += 2; continue }
+      if (c === "'" || c === '"' || c === '`') { state = c; out += c; i++; continue }
+      out += c; i++; continue
+    }
+    if (state === 'line') { if (c === '\n') { state = 'code'; out += c } i++; continue }
+    if (state === 'block') { if (c === '*' && c2 === '/') { state = 'code'; i += 2; continue } if (c === '\n') out += c; i++; continue }
+    // 字符串**保留**（env 名/字段名正是字符串字面量）
+    if (c === state && !esc) { state = 'code' }
+    out += c; i++
+  }
+  return out
+}
+
+/** 扫描面：仓库里所有代码文件（剥注释后拼接），并统计"每行"。 */
+export function scanSources() {
+  const hits = new Map()   // token → [{file,line}]
+  const files = []
+  for (const top of ['core', 'scripts', 'plugins', 'verticals', 'configs']) {
+    const p = join(root, top)
+    if (existsSync(p)) walk(p, files)
+  }
+  if (existsSync(join(root, 'install-argent.mjs'))) files.push(join(root, 'install-argent.mjs'))
+  let scanned = 0
+  for (const f of files) {
+    if (!CODE_RE.test(f)) continue
+    const rel = relative(root, f)
+    // configs/ 自己是声明面，不是"读它的代码"；tests 允许写夹具
+    if (rel.startsWith('configs/')) continue
+    let text = ''
+    try { text = readFileSync(f, 'utf8') } catch { continue }
+    scanned++
+    const stripped = stripComments(text, f)
+    stripped.split('\n').forEach((line, idx) => {
+      for (const m of line.matchAll(/[A-Za-z_][A-Za-z0-9_.$-]*/g)) {
+        const tok = m[0]
+        if (tok.length < 3) continue
+        if (!hits.has(tok)) hits.set(tok, [])
+        const arr = hits.get(tok)
+        if (arr.length < 5) arr.push({ file: rel, line: idx + 1 })
+      }
+    })
+  }
+  return { hits, scanned }
+}
+
+/** 读取器 API 的**字面量调用**扫描（`cfg.get('k')` 一类；`--reader-alias` 可扩展别名）。 */
+export const READER_CALL_RE = /\b(?:config|cfg|catalog|reader)\s*\.\s*(?:get|require|sourceOf|isConfigured)\s*\(\s*(['"])([a-z][a-z0-9_]*(?:\.[a-z0-9_]+)+)\1/g
+export const READER_FN_RE = /\b(?:requireKey|configGet)\s*\(\s*(['"])([a-z][a-z0-9_]*(?:\.[a-z0-9_]+)+)\1/g
+
+function literalReads() {
+  const out = []
+  for (const top of ['core', 'scripts', 'plugins', 'verticals']) {
+    const p = join(root, top)
+    if (!existsSync(p)) continue
+    for (const f of walk(p)) {
+      if (!CODE_RE.test(f)) continue
+      const rel = relative(root, f)
+      let text = ''
+      try { text = readFileSync(f, 'utf8') } catch { continue }
+      const stripped = stripComments(text, f)
+      for (const re of [READER_CALL_RE, READER_FN_RE]) {
+        re.lastIndex = 0
+        let m
+        while ((m = re.exec(stripped)) !== null) {
+          out.push({ key: m[2], file: rel, line: stripped.slice(0, m.index).split('\n').length })
+        }
+      }
+    }
+  }
+  return out
+}
+
+/** 一项声明的"被读证据"候选 token（**一个都不命中 = 孤儿声明**）。 */
+export function evidenceTokens(item) {
+  const b = item.binding || {}
+  const toks = []
+  if (b.env) toks.push(String(b.env))
+  if (b.file) toks.push(String(b.file))
+  if (b.field) {
+    toks.push(String(b.field))
+    const leaf = String(b.field).split('.').pop()
+    if (leaf) toks.push(leaf)
+  }
+  if (b.special) toks.push({ dataDir: 'ARGENT_DATA_DIR', dshHome: 'DSH_HOME', dataDirSource: 'ARGENT_DATA_DIR' }[b.special] || '')
+  if (b.kind === 'env') toks.push(envNameOf(item.key))
+  return [...new Set(toks.filter(Boolean))]
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 门禁 ① —— 双向对账
+// ══════════════════════════════════════════════════════════════════════════
+
+export function gateReconcile(reader, scan, opts = {}) {
+  const out = []
+  const cat = reader.catalog()
+  // ①-0 声明形状（读取器实现，⛔ 门禁不另写一份）
+  for (const p of validateCatalog(cat)) out.push({ kind: 'declaration', msg: p })
+
+  const items = cat.items
+  const keys = new Set(items.map((it) => it.key))
+
+  // ①-a 代码读了但没声明
+  const reads = opts.reads || literalReads()
+  for (const r of reads) {
+    if (!keys.has(r.key)) out.push({ kind: 'read-undeclared', msg: `${r.file}:${r.line} 读了未声明的 key \`${r.key}\` ⇒ 先在 configs/ 或 verticals/<id>/config.json 里声明它` })
+  }
+
+  // ①-b 声明了但没人读（每个非 server 项必须有证据）
+  const hits = scan.hits
+  let evidenced = 0
+  let serverPending = 0
+  for (const it of items) {
+    if (String(it.source) === 'server') {
+      serverPending++
+      if (it.binding) out.push({ kind: 'server-binding', msg: `${it.key} source=server（预留）却声明了 binding ⇒ 本批不读服务端，声明会让人以为能读到` })
+      continue
+    }
+    const literal = reads.filter((r) => r.key === it.key)
+    const toks = evidenceTokens(it)
+    const found = toks.filter((t) => hits.has(t))
+    if (literal.length) { evidenced++; continue }
+    if (found.length) { evidenced++; continue }
+    out.push({
+      kind: 'orphan-declaration',
+      msg: `${it.key} 声明了但**没有任何读取证据**（候选 token：${toks.join(' / ') || '（空）'}）`
+        + ` —— 要么让调用方改用读取器（\`cfg.get('${it.key}')\`），要么把 binding 改对；孤儿声明会骗页面`,
+    })
+  }
+  if (!items.length) out.push({ kind: 'vacuous', msg: '配置目录里一项都没有 ⇒ 这道门禁等于空跑' })
+  if (!evidenced) out.push({ kind: 'vacuous', msg: '没有任何声明带读取证据 ⇒ 这道门禁等于空跑' })
+  if (!reads.length) {
+    out.push({
+      kind: 'vacuity-note',
+      msg: '还没有调用方改用读取器（字面量读 = 0）⇒ ①-a「读了必须已声明」这半目前是**空跑**；本批以 ①-b'
+        + '「声明必须有读取证据（binding 指向的 env 名 / 文件 / 字段在代码里真被引用）」为准。'
+        + '迁移期把调用方逐个换到读取器后这半自动生效（门禁自证里已证明它**能**判红）。',
+    })
+  }
+  if (!serverPending) out.push({ kind: 'vacuity-note', msg: '没有任何 source=server 的预留声明（`server` 来源没被用上；至少留一条演示"上云后接什么"）' })
+
+  // ①-c key ↔ 环境变量名一一对应
+  const env = new Map()
+  for (const it of items) {
+    const n = String((it.binding && it.binding.env) || envNameOf(it.key))
+    if (env.has(n) && env.get(n) !== it.key) {
+      out.push({ kind: 'env-collision', msg: `\`${it.key}\` 与 \`${env.get(n)}\` 归一成同一个环境变量名 ${n} ⇒ 进程 env 覆盖会串项` })
+    } else env.set(n, it.key)
+  }
+
+  // ①-d 层级枚举必须自洽（防止有人悄悄改了链）
+  if (RESOLUTION_ORDER[RESOLUTION_ORDER.length - 1] !== 'default') out.push({ kind: 'chain', msg: '解析链最后一级必须是 default' })
+  for (const l of RESOLUTION_ORDER) if (!LAYERS.includes(l)) out.push({ kind: 'chain', msg: `解析链里的 ${l} 不是合法层级` })
+  for (const s of SOURCES) if (!LAYERS.includes(s)) out.push({ kind: 'chain', msg: `source 枚举里的 ${s} 不是合法层级` })
+
+  return {
+    problems: out,
+    stats: {
+      items: items.length,
+      evidenced,
+      serverPending,
+      literalReads: reads.length,
+      scannedFiles: scan.scanned,
+      catalogFiles: cat.files.length,
+      envNames: env.size,
+    },
+  }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 门禁 ② —— 敏感不出门
+// ══════════════════════════════════════════════════════════════════════════
+
+const luhnish = () => `DECOY-${Math.random().toString(36).slice(2, 10)}-${Date.now().toString(36)}`
+
+/**
+ * @param {object} reader 读取器
+ * @param {{ decoy?: string, probeEnv?: object, repoText?: string }} [opts]
+ *   `probeEnv` 用来把诱饵值"真喂进去"（默认用每项自己的进程 env 名）。
+ */
+export function gateSecret(reader, opts = {}) {
+  const out = []
+  const decoy = opts.decoy || luhnish()
+  const secrets = reader.all({ secret: true })
+  if (!secrets.length) out.push({ kind: 'vacuous', msg: '目录里没有任何 secret 项 ⇒ 这道门禁等于空跑' })
+
+  // ②-a 载荷里不得有 secret 的值（连长度/默认值都不给）
+  const payload = JSON.stringify(reader.describe())
+  if (payload.includes(decoy)) out.push({ kind: 'payload-leak', msg: `describe() 载荷里出现了诱饵值` })
+  for (const it of secrets) {
+    const view = reader.describe().items.find((x) => x.key === it.key)
+    if (!view) { out.push({ kind: 'missing-in-payload', msg: `${it.key} 是 secret 却没有出现在载荷里（页面会漏掉它）` }); continue }
+    if (Object.prototype.hasOwnProperty.call(view, 'value') && view.value !== undefined && view.value !== null && view.value !== '') {
+      out.push({ kind: 'secret-value-in-payload', msg: `${it.key} 的载荷里带了 value ⇒ 必须删掉（secret 只回已配置/未配置）` })
+    }
+    if (Object.prototype.hasOwnProperty.call(view, 'default') && view.default) {
+      out.push({ kind: 'secret-default-in-payload', msg: `${it.key} 的载荷里带了非空 default` })
+    }
+  }
+
+  // ②-b 声明文件里不得有真实样例/非空 default
+  for (const it of secrets) {
+    const raw = JSON.stringify(it)
+    for (const bad of ['"example"', '"sample"', '"value"', '"secretValue"']) {
+      if (raw.includes(bad)) out.push({ kind: 'declaration-leak', msg: `${it._file}:${it.key} 声明里出现 ${bad}` })
+    }
+    if (it.default !== undefined && it.default !== null && String(it.default) !== '') {
+      out.push({ kind: 'declaration-leak', msg: `${it._file}:${it.key} secret 项带了非空 default` })
+    }
+  }
+
+  // ②-c 诱饵值：先证明"能被读到"，再断言"搜不到"
+  const probeEnv = opts.probeEnv || Object.fromEntries(
+    secrets.map((it) => [String((it.binding && it.binding.env) || envNameOf(it.key)), decoy]),
+  )
+  const probeReader = opts.probeReader || createReader({
+    root: reader.catalog().root, env: probeEnv, dataDir: opts.dataDir || reader.dataDir(),
+  })
+  let readable = 0
+  for (const it of secrets) {
+    const got = probeReader.get(it.key)
+    if (got === decoy) readable++
+    else if (String(it.source) === 'server') continue
+    else if (it.binding && it.binding.kind !== 'env') continue   // 非 env 层：诱饵喂不进去（如实跳过）
+    else out.push({ kind: 'decoy-not-readable', msg: `${it.key} 的诱饵值没被读到 ⇒ 后面的"搜不到"证明不了任何事` })
+  }
+  if (readable === 0) out.push({ kind: 'vacuous', msg: '诱饵值一个都没被读到 ⇒ 这道门禁的"搜不到"是假绿' })
+  const probePayload = JSON.stringify(probeReader.describe())
+  if (probePayload.includes(decoy)) out.push({ kind: 'payload-leak', msg: '诱饵值经进程 env 生效后，仍然出现在 describe() 载荷里' })
+
+  // ②-d 报错文本里不得带值
+  for (const it of secrets) {
+    try {
+      probeReader.require(it.key === secrets[0].key ? it.key : it.key)
+    } catch (e) {
+      if (String(e.message).includes(decoy)) out.push({ kind: 'error-leak', msg: `${it.key} 的缺配置报错里带了值` })
+    }
+  }
+
+  // ②-e 全仓库文本里不得出现诱饵值（目录/文档/测试输出都不许）
+  const repoText = opts.repoText !== undefined ? opts.repoText : readRepoText(reader.catalog().root)
+  if (repoText.includes(decoy)) out.push({ kind: 'repo-leak', msg: `仓库文本里出现了诱饵值（谁把密钥写进仓库了？）` })
+
+  return { problems: out, stats: { secrets: secrets.length, decoyReadable: readable, decoy } }
+}
+
+function readRepoText(root) {
+  const parts = []
+  for (const top of ['configs', 'verticals', 'scripts', 'core', 'docs']) {
+    const p = join(root, top)
+    if (!existsSync(p)) continue
+    for (const f of walk(p)) {
+      if (!/\.(json|md|mjs|js|py|sh|yml|yaml|txt)$/.test(f)) continue
+      try { parts.push(readFileSync(f, 'utf8')) } catch { /* 忽略不可读 */ }
+    }
+  }
+  return parts.join('\n')
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 门禁 ③ —— 必须项可解析
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 空环境读取器：`env={}` + 空数据目录（无 env 文件、无 config.json）。 */
+export function emptyReader(rootDir, tmpBase) {
+  const dir = join(tmpBase, 'empty-data-dir')
+  mkdirSync(dir, { recursive: true })
+  return createReader({ root: rootDir, env: {}, dataDir: dir, home: dir })
+}
+
+export function gateRequired(reader, opts = {}) {
+  const out = []
+  const required = reader.all().filter((it) => it.required === true)
+  if (!required.length) out.push({ kind: 'vacuous', msg: '目录里没有任何 required 项 ⇒ 这道门禁等于空跑' })
+
+  // ③-a 真机上必须能解析（否则装机就是断的）
+  for (const it of reader.all().filter((x) => x.required === true)) {
+    const s = reader.sourceOf(it.key)
+    if (s.layer === 'missing') {
+      out.push({ kind: 'required-unresolved', msg: `${it.key}（必须项）**在真机上解析不到**：${(s.tried || []).join('；') || '五级链全未命中'}` })
+    } else if (s.layer === 'default') {
+      out.push({ kind: 'required-from-default', msg: `${it.key} 是必须项却只靠 default 兜底（等于没配也能跑 ⇒ 要么去掉 required，要么去掉 default）` })
+    }
+  }
+
+  // ③-b 空环境下必须给出**可执行**报错
+  const tmpBase = opts.tmpBase || mkdtempSync(join(tmpdir(), 'cfg-gate3-'))
+  const empty = emptyReader(reader.catalog().root, tmpBase)
+  for (const it of empty.all().filter((x) => x.required === true)) {
+    let err = null
+    try { empty.require(it.key) } catch (e) { err = e }
+    if (!err) { out.push({ kind: 'required-no-error', msg: `${it.key} 在空环境下没报错（必须项缺失必须响亮失败）` }); continue }
+    if (err.code !== 'CONFIG_MISSING') out.push({ kind: 'required-wrong-error', msg: `${it.key} 的报错 code=${err.code}（期望 CONFIG_MISSING）` })
+    const msg = String(err.message || '')
+    if (!msg.includes(it.key)) out.push({ kind: 'required-msg-nokey', msg: `${it.key} 的报错里没点名 key` })
+    if (!/去哪里配/.test(msg)) out.push({ kind: 'required-msg-nowhere', msg: `${it.key} 的报错里没有"去哪里配"一节` })
+    if (!/已尝试的来源/.test(msg)) out.push({ kind: 'required-msg-notried', msg: `${it.key} 的报错里没有列出已试来源` })
+    // "可执行"的最低标准：至少给一条具体的落点（域名/环境变量/路径）
+    if (!/[\w.-]+\.env|config\.json|进程环境变量\s+[A-Z]|[A-Z]{3,}_[A-Z0-9_]+/.test(msg)) {
+      out.push({ kind: 'required-msg-unactionable', msg: `${it.key} 的报错里没有一条可照做的落点（env 名 / 文件 / 字段）` })
+    }
+    if (it.secret === true && msg.includes(String(empty.get(it.key) ?? '\u0000'))) {
+      out.push({ kind: 'error-leak', msg: `${it.key} 的报错里带了值` })
+    }
+  }
+  return { problems: out, stats: { required: required.length } }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 门禁 ④ —— 新增即生效（加一条假配置，不改任何代码）
+// ══════════════════════════════════════════════════════════════════════════
+
+export const FAKE_KEY = 'fixture.extensibility.probe'
+
+/**
+ * 在夹具根里造一份"真仓库目录 + 一条新声明"，断言新声明**不改读取器/不改 UI 代码**就进载荷。
+ * @returns {{problems: Array, evidence: object}}
+ */
+export function gateExtensible(reader, opts = {}) {
+  const out = []
+  const base = opts.tmpBase || mkdtempSync(join(tmpdir(), 'cfg-gate4-'))
+  const fixRoot = join(base, 'fixture-root')
+  mkdirSync(join(fixRoot, 'configs'), { recursive: true })
+  // 夹具 = 真目录文件（**逐字节复制**）＋ 一条新声明 ⇒ 证明是"增量"而不是"另起一套"
+  const cat = reader.catalog()
+  for (const rel of cat.files) {
+    const src = join(cat.root, rel)
+    const dst = join(fixRoot, rel)
+    mkdirSync(dirname(dst), { recursive: true })
+    writeFileSync(dst, readFileSync(src))
+  }
+  const before = reader.describe().items.length
+  const newItem = {
+    key: FAKE_KEY,
+    label: '夹具新增项',
+    category: '夹具分类',
+    type: 'int',
+    source: 'json',
+    secret: false,
+    required: false,
+    default: 7,
+    capability: null,
+    vertical: null,
+    editable: true,
+    help: '门禁 ④ 的夹具：加一条声明就必须出现在载荷里，不改读取器、不改 UI。',
+    binding: { kind: 'json', file: 'config.json', field: 'fixtureProbe' },
+  }
+  const fixCatalog = join(fixRoot, 'configs', 'zz-fixture.json')
+  writeFileSync(fixCatalog, JSON.stringify({ domain: 'fixture', order: 999, items: [newItem], entries: [{ id: 'fixture.entry', label: '夹具入口', category: '夹具分类', kind: 'action', implemented: false }] }, null, 2))
+
+  const fixReader = createReader({ root: fixRoot, env: {}, dataDir: join(base, 'fix-data') })
+  mkdirSync(join(base, 'fix-data'), { recursive: true })
+  const payload = fixReader.describe()
+  const mine = payload.items.find((x) => x.key === FAKE_KEY)
+  const stillThere = payload.items.find((x) => x.key === cat.items[0].key)
+  if (!mine) out.push({ kind: 'not-in-payload', msg: `夹具新增的 ${FAKE_KEY} 没有出现在 describe() 载荷里 ⇒ "加声明即生效"不成立` })
+  else {
+    if (mine.category !== '夹具分类') out.push({ kind: 'category-lost', msg: `${FAKE_KEY} 的分类没进载荷（页面无法归类）` })
+    if (mine.value !== 7) out.push({ kind: 'value-wrong', msg: `${FAKE_KEY} 的默认值没被解析（得到 ${JSON.stringify(mine.value)}）` })
+    if (mine.resolvedFrom.layer !== 'default') out.push({ kind: 'layer-wrong', msg: `${FAKE_KEY} 的来源层应是 default（得到 ${mine.resolvedFrom.layer}）` })
+  }
+  if (!stillThere) out.push({ kind: 'replaced-not-added', msg: `夹具把原仓库的项挤掉了（${cat.items[0].key} 不在载荷里）⇒ 证明的不是"增量生效"` })
+  if (!payload.entries.some((e) => e.id === 'fixture.entry')) out.push({ kind: 'entry-not-in-payload', msg: '夹具新增的**入口**（检查更新那类）没有出现在载荷 entries 里' })
+  if (payload.items.length !== before + 1) out.push({ kind: 'count-wrong', msg: `载荷条数应为 ${before + 1}，实际 ${payload.items.length}` })
+
+  const afterAdd = payload.items.length
+  // 缓存失效：删掉夹具文件后必须立刻消失（页面不会看到残影）
+  rmSync(fixCatalog)
+  const after = fixReader.describe()
+  if (after.items.some((x) => x.key === FAKE_KEY)) out.push({ kind: 'stale-cache', msg: '删掉目录文件后该项仍在载荷里 ⇒ 缓存没失效' })
+
+  if (!opts.keep) rmSync(base, { recursive: true, force: true })
+  return { problems: out, evidence: { before, afterAdd, afterDelete: after.items.length, fixtureFile: 'configs/zz-fixture.json', key: FAKE_KEY } }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 门禁自证 —— 注入假象必须变红（一个永远返回 [] 的判定器也能"全绿"）
+// ══════════════════════════════════════════════════════════════════════════
+
+export function selfTest(reader, opts = {}) {
+  const out = []
+  const tmpBase = opts.tmpBase || mkdtempSync(join(tmpdir(), 'cfg-selftest-'))
+  const cat = reader.catalog()
+  const fixRoot = join(tmpBase, 'selftest-root')
+  mkdirSync(join(fixRoot, 'configs'), { recursive: true })
+  for (const rel of cat.files) {
+    const dst = join(fixRoot, rel)
+    mkdirSync(dirname(dst), { recursive: true })
+    writeFileSync(dst, readFileSync(join(cat.root, rel)))
+  }
+  // 夹具里放一个 required 且**故意配不齐**的项 + 一个 normal 项（供各门禁注入用）
+  const broken = {
+    key: 'fixture.selftest.broken',
+    label: '夹具缺配置项',
+    category: '夹具分类',
+    type: 'string',
+    source: 'envfile',
+    secret: false,
+    required: true,
+    capability: null,
+    vertical: null,
+    editable: false,
+    help: '门禁自证夹具：空环境下必须给出可执行报错。',
+    binding: { kind: 'envfile', file: 'fixture-selftest.env', env: 'FIXTURE_SELFTEST_BROKEN', vertical: null },
+  }
+  const dupA = { ...broken, key: 'fixture.selftest.a', required: false, binding: { kind: 'env', env: 'FIXTURE_SAME_NAME' } }
+  const dupB = { ...broken, key: 'fixture.selftest.b', required: false, binding: { kind: 'env', env: 'FIXTURE_SAME_NAME' } }
+  const fixFile = join(fixRoot, 'configs', 'zz-selftest.json')
+  const write = (items) => writeFileSync(fixFile, JSON.stringify({ domain: 'fixture', items }, null, 2))
+  write([broken])
+
+  const scanFor = (root, reads) => {
+    const hits = new Map()
+    for (const tok of (reads || []).map((r) => r.token).filter(Boolean)) {
+      if (!hits.has(tok)) hits.set(tok, [{ file: 'fixture.mjs', line: 1 }])
+    }
+    return { hits, scanned: 1 }
+  }
+
+  const r1 = createReader({ root: fixRoot, env: {}, dataDir: join(tmpBase, 'd') })
+  mkdirSync(join(tmpBase, 'd'), { recursive: true })
+
+  // ①-a 读了没声明
+  const g1a = gateReconcile(r1, scanFor(fixRoot), { reads: [{ key: 'fixture.selftest.read_but_undeclared', file: 'x.mjs', line: 3 }] })
+  if (!g1a.problems.some((p) => p.kind === 'read-undeclared')) out.push({ kind: 'selftest', msg: '①-a 注入"读了未声明的 key"却没有变红' })
+
+  // ①-b 声明了没人读（把 binding 指到一个代码里根本不存在的 env 名）
+  write([{ ...broken, required: false, binding: { kind: 'env', env: 'FIXTURE_NOBODY_READS_THIS_9f3a' } }])
+  const g1b = gateReconcile(createReader({ root: fixRoot, env: {}, dataDir: join(tmpBase, 'd') }), scanFor(fixRoot))
+  if (!g1b.problems.some((p) => p.kind === 'orphan-declaration')) out.push({ kind: 'selftest', msg: '①-b 注入"声明了没人读"却没有变红' })
+
+  // ①-c 两个 key 归一撞名
+  write([dupA, dupB])
+  const g1c = gateReconcile(createReader({ root: fixRoot, env: {}, dataDir: join(tmpBase, 'd') }), scanFor(fixRoot))
+  if (!g1c.problems.some((p) => p.kind === 'env-collision')) out.push({ kind: 'selftest', msg: '①-c 注入"两个 key 归一成同名 env"却没有变红' })
+
+  // ①-d server 项带 binding
+  write([{ ...broken, required: false, source: 'server', binding: { kind: 'json', file: 'config.json', field: 'x' } }])
+  const g1d = gateReconcile(createReader({ root: fixRoot, env: {}, dataDir: join(tmpBase, 'd') }), scanFor(fixRoot))
+  if (!g1d.problems.some((p) => p.kind === 'server-binding')) out.push({ kind: 'selftest', msg: '①-d 注入"server 项带 binding"却没有变红' })
+
+  // ② 诱饵值真的会漏（故意让 secret 项带上 value）
+  const leaky = { ...broken, required: false, secret: true, type: 'string', source: 'env', binding: { kind: 'env', env: 'FIXTURE_SELFTEST_SECRET' } }
+  write([leaky])
+  const r2 = createReader({ root: fixRoot, env: { FIXTURE_SELFTEST_SECRET: 'DECOY-LEAK-CHECK' }, dataDir: join(tmpBase, 'd') })
+  const payload2 = r2.describe()
+  const view2 = payload2.items.find((x) => x.key === leaky.key)
+  if (Object.prototype.hasOwnProperty.call(view2, 'value')) out.push({ kind: 'selftest', msg: '② secret 项的载荷里居然有 value 字段（说明"不回值"不是读取器保证的）' })
+  const g2 = gateSecret(r2, { decoy: 'DECOY-LEAK-CHECK', repoText: 'DECOY-LEAK-CHECK' })
+  if (!g2.problems.some((p) => p.kind === 'repo-leak')) out.push({ kind: 'selftest', msg: '② 注入"仓库里出现诱饵值"却没有变红' })
+
+  // ③ 必须项在空环境下没报错（把 required 项改成有 default ⇒ 报"靠 default 兜底"）
+  write([{ ...broken, default: 'x' }])
+  const g3 = gateRequired(createReader({ root: fixRoot, env: {}, dataDir: join(tmpBase, 'd') }), { tmpBase })
+  if (!g3.problems.some((p) => p.kind === 'required-from-default')) out.push({ kind: 'selftest', msg: '③ 注入"必须项靠 default 兜底"却没有变红' })
+  // ③ 报错不可执行（binding 与 source 都指不出落点）
+  write([{ ...broken, binding: null, source: 'machine' }])
+  const g3b = gateRequired(createReader({ root: fixRoot, env: {}, dataDir: join(tmpBase, 'd') }), { tmpBase })
+  if (!g3b.problems.length) out.push({ kind: 'selftest', msg: '③ 注入"缺 binding 的必须项"却没有变红' })
+
+  // ④ 新增项不进载荷（把声明写成非法形状，读出来就该报错或缺席）
+  write([{ ...broken, required: false, key: 'BadKey' }])
+  const g4 = gateReconcile(createReader({ root: fixRoot, env: {}, dataDir: join(tmpBase, 'd') }), scanFor(fixRoot))
+  if (!g4.problems.some((p) => p.kind === 'declaration')) out.push({ kind: 'selftest', msg: '④ 注入非法 key 形状却没有变红' })
+
+  if (!opts.keep) rmSync(tmpBase, { recursive: true, force: true })
+  return { problems: out }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 主流程
+// ══════════════════════════════════════════════════════════════════════════
+
+const wantGate = (n) => !onlyGate || String(onlyGate).split(',').map((x) => x.trim()).includes(String(n))
+
+function main() {
+  if (has('--selftest')) {
+    const r = createReader({ root, env: process.env, ...(dataDir ? { dataDir } : {}) })
+    const st = selfTest(r)
+    const okAll = st.problems.length === 0
+    console.log(`门禁自证：${okAll ? '✅ 注入的六类假象全部被判红（门禁不是空壳）' : `❌ ${st.problems.length} 条自证失败`}`)
+    for (const p of st.problems) console.log(`  ❌ [${p.kind}] ${p.msg}`)
+    process.exit(okAll ? 0 : 1)
+  }
+
+  const reader = createReader({ root, env: process.env, ...(dataDir ? { dataDir } : {}) })
+  const scan = scanSources()
+  const results = {}
+
+  if (wantGate(1)) {
+    const r = gateReconcile(reader, scan)
+    results['①双向对账'] = r
+    for (const p of r.problems) {
+      if (p.kind === 'vacuity-note') { notes.push(`①提示：${p.msg}`); continue }
+      red(1, `[${p.kind}] ${p.msg}`)
+    }
+    notes.push(`①扫描面：${r.stats.scannedFiles} 个代码文件、${r.stats.items} 条声明（有证据 ${r.stats.evidenced}、预留 server ${r.stats.serverPending}）、字面量读 ${r.stats.literalReads} 处`)
+  }
+  if (wantGate(2)) {
+    const r = gateSecret(reader, dataDir ? { dataDir } : {})
+    results['②敏感不出门'] = r
+    for (const p of r.problems) red(2, `[${p.kind}] ${p.msg}`)
+    notes.push(`②诱饵值：${r.stats.secrets} 个 secret 项，其中 ${r.stats.decoyReadable} 个真被诱饵值读到（"搜不到"才有意义）`)
+  }
+  if (wantGate(3)) {
+    const r = gateRequired(reader)
+    results['③必须项可解析'] = r
+    for (const p of r.problems) red(3, `[${p.kind}] ${p.msg}`)
+    notes.push(`③必须项：${r.stats.required} 条 required 声明`)
+  }
+  if (wantGate(4)) {
+    const r = gateExtensible(reader)
+    results['④新增即生效'] = r
+    for (const p of r.problems) red(4, `[${p.kind}] ${p.msg}`)
+    notes.push(`④夹具：先 ${r.evidence.before} 项 → 加一条声明后 ${r.evidence.afterAdd} 项 → 删掉后 ${r.evidence.afterDelete} 项（全程未改读取器/UI 代码）`)
+  }
+
+  const payload = reader.describe()
+  const tree = payload.categories.map((c) => ({ 分类: c.id, 项数: c.items, 密钥项: c.secrets, 已配置: c.configured, 必须项: c.required, 能力: c.capabilities }))
+  const out = {
+    ok: problems.length === 0,
+    gates: Object.fromEntries(Object.entries(results).map(([k, v]) => [k, { problems: v.problems, stats: v.stats }])),
+    problems,
+    notes,
+    tree,
+    entries: payload.entries,
+    items: payload.items.length,
+    catalogFiles: payload.catalogFiles,
+  }
+
+  // ⚠️ 这里一律用 `process.exitCode`，**不用** `process.exit()`（2026-10-09 实测事故）：
+  //    stdout 是管道时写入是异步的，`process.exit()` 会在冲刷前终止进程 ⇒ 输出被**截断在 64 KiB**
+  //    （管道缓冲区大小）。载荷在设置页批次里长到 80 KB 就当场命中：`--describe | JSON.parse` 报
+  //    "Expected double-quoted property name"，而重定向到文件却正常（文件写入是同步的）——
+  //    这正是"看着是绿的、消费方拿到半截"的静默降级形态。
+  //    `process.exitCode` + 自然退出 = 先冲刷再退出，退出码语义**逐字不变**。
+  if (JSON_OUT) { console.log(JSON.stringify(out, null, 2)); process.exitCode = STRICT && problems.length ? 1 : 0; return }
+
+  if (has('--list')) {
+    console.log(`配置目录：${payload.catalogFiles.length} 个文件 / ${payload.items.length} 项（分类 ${tree.length} 个）`)
+    for (const c of payload.categories) {
+      console.log(`\n【${c.id}】 ${c.items} 项（密钥 ${c.secrets} / 已配置 ${c.configured}${c.capabilities.length ? ` / 能力 ${c.capabilities.join(',')}` : ''}）`)
+      for (const it of payload.items.filter((x) => x.category === c.id)) {
+        const state = it.secret
+          ? (it.configured ? '已配置' : '未配置')
+          : (it.configured ? JSON.stringify(it.value) : (it.resolvable ? `默认 ${JSON.stringify(it.value)}` : '未配置'))
+        console.log(`  ${it.key.padEnd(34)} ${it.label.padEnd(20)} [${it.type}] ${String(it.declaredSource).padEnd(8)} ${state} ← ${it.resolvedFrom.layer}`)
+      }
+    }
+    if (payload.entries.length) {
+      console.log('\n【入口声明】（本批**只声明不实现**）')
+      for (const e of payload.entries) console.log(`  ${e.id.padEnd(28)} ${e.label.padEnd(16)} implemented=${e.implemented} — ${e.help}`)
+    }
+    process.exitCode = 0
+    return
+  }
+
+  if (has('--describe')) {
+    console.log(JSON.stringify(payload, null, 2))
+    process.exitCode = 0     // 同上：载荷可达数十 KB，必须让 stdout 冲刷完再退
+    return
+  }
+
+  console.log(`配置目录门禁（root=${root}｜数据目录=${payload.dataDir}）`)
+  console.log(`  目录文件 ${payload.catalogFiles.length} 个、声明 ${payload.items.length} 项、入口 ${payload.entries.length} 条`)
+  for (const n of notes) console.log(`  · ${n}`)
+  console.log('')
+  console.log('  分类树（页面按它分节）：')
+  for (const c of tree) console.log(`    ${c.分类.padEnd(14)} ${String(c.项数).padStart(3)} 项  密钥 ${c.密钥项}  已配置 ${c.已配置}  必须 ${c.必须项}`)
+  console.log('')
+  if (problems.length) {
+    console.log(`结果：❌ ${problems.length} 条问题`)
+    for (const p of problems) console.log(`  ❌ [门禁 ${p.gate}] ${p.msg}`)
+  } else {
+    console.log('结果：✅ 四道门禁全绿（双向对账 / 敏感不出门 / 必须项可解析 / 新增即生效）')
+  }
+  process.exitCode = STRICT && problems.length ? 1 : 0
+}
+
+if (isDirectRun(import.meta.url)) main()