@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/argent-env-write.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * argent-env-write —— **受控** env 写入器（能力包设置页契约 §11，2026-10-01）
+ *
+ * ## 为什么需要它
+ * 设置页里有相当一部分字段不是 `config.json` 键，而是**部署 env 文件**里的键
+ * （`~/.dsh/argent/verticals/<业务线>/env/*.env` 或数据目录根下的 `*.env`）：
+ * 货件表 token、门户密码、ML 应用 secret…… 此前它们**只能读**（v1 刻意只复用既有写入口），
+ * 用户要改就得手工编辑 env 文件 —— 正是"配错了看不出来"的高发区。
+ *
+ * ## 安全边界（每一条都有对应的代码判据，不是口号）
+ *   ① **白名单只来自声明**：合法键 = 设置页面板声明里的 env 字段（`<面板 id>::<字段 key>`）。
+ *      **请求体里不带任何路径**；路径由声明（`scope` + 业务线 + `envFile`）推导，
+ *      再校验"解析结果必须落在 `~/.dsh/argent/**` 内"。⇒ 任意路径/目录穿越在结构上不可能发生。
+ *   ② **默认关闭**：真写要同时满足 `--allow-write` **且** `ARGENT_ENV_WRITER=1`；
+ *      否则只做 dry-run（打印计划），退出码 3（"写入器未开启"）。
+ *   ③ **未知键/空值/非标量 ⇒ 整请求拒绝**（不部分写入）—— 免得半个面板写进去、半个没写。
+ *   ④ **写前备份**：目标文件先整份复制到 `<数据目录>/env-writeback/backup/`（0600）。
+ *   ⑤ **原子写 + 权限 0600**：临时文件（同目录）→ rename；不产生"写了一半"的 env。
+ *   ⑥ **写后读回验收**：重新解析目标文件，键值必须逐字相等；不等 ⇒ **回滚**（还原备份/删除新建）
+ *      并在审计里记 `readback: mismatch` + `rolledBack: true`。
+ *   ⑦ **审计 JSONL**：`<数据目录>/env-writeback/audit.jsonl` 每行一条（含结果、备份路径、
+ *      值长度与**掩码**）—— **绝不落明文值**。
+ *   ⑧ 密钥类（`type: password`）与普通字段一视同仁地只回掩码；日志/标准输出同样不打明文。
+ *
+ * ## 用法
+ * ```bash
+ * node scripts/argent-env-write.mjs --list [--json] [--catalog]      # 白名单（只读，随时可用）
+ * node scripts/argent-env-write.mjs --payload '{"<面板>::<字段>":"值"}' [--allow-write] [--json]
+ * echo '{"<配置目录 key>":"值"}' | node scripts/argent-env-write.mjs --stdin --catalog --allow-write
+ *
+ * `--catalog`（2026-10-09）：把**配置目录**（`configs/*.json` + `verticals/<id>/config.json`）里
+ * 声明为 `binding.kind=envfile` 且 `editable:true` 的项并进同一张白名单 —— 键就用目录 key
+ * （点分小写，与 `<面板>::<字段>` 形状天然不撞）。设置页「配置中心」走的就是这条：
+ * **同一段写入代码、同一份安全边界**，⛔ 不另写一个写入器。
+ * ```
+ * 退出码：0 成功（或 dry-run 计划可行）｜ 1 校验/读回失败 ｜ 2 用法错误 ｜ 3 写入器未开启
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, unlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import {
+  ENV_WRITER_ENV, collectEnvWriteTargets, gatherDeclaredPanels, maskSecret, resolveEnvWriteTarget,
+} from './lib/settings-panels.mjs'
+import { loadRegistryDoc } from './lib/registry.mjs'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const AUDIT_DIR = 'env-writeback'
+const AUDIT_FILE = `${AUDIT_DIR}/audit.jsonl`
+const BACKUP_DIR = `${AUDIT_DIR}/backup`
+
+const args = process.argv.slice(2)
+const has = (f) => args.includes(f)
+const val = (f, d = '') => { const i = args.indexOf(f); return i >= 0 ? String(args[i + 1] || '') : d }
+const AS_JSON = has('--json')
+
+const HOME = val('--home') || process.env.HOME || homedir()
+// `--data-dir` 是**显式人工覆盖**（优先）；其余一律走内核三级链（唯一判据，不再本地拼 ~/.dsh/argent）
+const DATA_DIR = resolve(val('--data-dir') || resolveDataDir({ env: process.env }).dir)
+const ROOT = val('--root') || REPO
+
+// ── 白名单：**只来自声明**（与设置页同一份聚合逻辑，不新建第二份键表）────────────
+function whitelist() {
+  let registryDoc = {}
+  try { registryDoc = loadRegistryDoc() } catch { registryDoc = {} }
+  const declared = gatherDeclaredPanels({ root: ROOT, registryDoc })
+  const { targets, errors } = collectEnvWriteTargets({ panels: declared.panels, dataDir: DATA_DIR })
+  return { targets, errors, declaredErrors: declared.errors }
+}
+
+/**
+ * 白名单②：**配置目录**（`configs/*.json` + `verticals/<id>/config.json`）里声明为 envfile 且
+ * `editable: true` 的项（2026-10-09，设置页批次）—— 仅 `--catalog` 时纳入。
+ *
+ * ## 为什么是"第二个来源"而不是新写一套写入器
+ * 设置页的「配置中心」由配置目录驱动（契约 §7），里面的项**天然不是** `<面板 id>::<字段 key>`
+ * 那种键（没有面板声明）。但它们的落点与安全边界与面板字段**逐条相同**：白名单只来自声明、
+ * 路径由声明推导并校验在数据目录内、备份 / 原子写 / 读回 / 回滚 / 审计一个不少。
+ * ⇒ 正确做法是把它们**并进同一张白名单表**，共用同一段写入代码；⛔ 不是再写一个写入器
+ * （那会变成第二份"合法的可写集合"，与声明漂移）。
+ *
+ * 键 = 目录 key（点分小写，与 `<面板>::<字段>` 形状天然不撞）；路径解析**复用**
+ * `resolveEnvWriteTarget()`（判据只有一份）。
+ */
+async function catalogTargets() {
+  const mod = await import(pathToFileURL(join(ROOT, 'core', 'lib', 'config-catalog.mjs')).href)
+  const reader = mod.createReader({ root: ROOT, dataDir: DATA_DIR })
+  const targets = new Map()
+  const errors = []
+  for (const item of reader.catalog().items) {
+    const w = mod.writeTargetOf(item)
+    if (!w || w.kind !== 'envfile') continue               // 只管 envfile；config.json 有它自己的写入口
+    const b = item.binding || {}
+    const t = resolveEnvWriteTarget(
+      { id: '__catalog__', title: '配置目录', vertical: b.vertical || item.vertical || '' },
+      { key: item.key, env: w.env, envFile: w.file, scope: (b.vertical || item.vertical) ? 'vertical' : 'user' },
+      { dataDir: DATA_DIR },
+    )
+    if (!t.ok) { errors.push({ panel: '__catalog__', field: item.key, code: 'env-target-unresolved', message: `${item.key} 写目标不可用：${t.error}` }); continue }
+    targets.set(item.key, {
+      panelId: '__catalog__', panelTitle: '配置目录', field: item.key, label: item.label,
+      type: item.secret === true ? 'password' : 'text', env: w.env, scope: (b.vertical || item.vertical) ? 'vertical' : 'user',
+      vertical: b.vertical || item.vertical || '', path: t.path, rel: t.rel, envFile: t.envFile,
+    })
+  }
+  return { targets, errors }
+}
+
+const stamp = () => new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)
+/** 目标 → 对外键名：面板字段是 `<面板>::<字段>`；配置目录项就是它自己的 key（见 `catalogTargets()`）。 */
+const keyOf = (t) => (t.panelId === '__catalog__' ? String(t.field) : `${t.panelId}::${t.field}`)
+const rel = (p) => (p.startsWith(DATA_DIR + '/') ? p.slice(DATA_DIR.length + 1) : p)
+
+/** env 值转义：含空白/引号/#/$ 时用双引号包起来（与 env 解析约定一致）。 */
+export function quoteEnvValue(v) {
+  const s = String(v)
+  if (!/[\s#'"\\$`]/.test(s)) return s
+  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+}
+
+/** 把 `KEY=VALUE` 写进 env 文本（有则替换那一行，无则追加；其它行**逐字保留**）。 */
+export function setEnvLine(text, key, value) {
+  const lines = String(text).split('\n')
+  const re = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=`)
+  const idx = lines.findIndex((l) => re.test(l))
+  const line = `${key}=${quoteEnvValue(value)}`
+  if (idx >= 0) {
+    lines[idx] = line
+  } else {
+    while (lines.length && lines[lines.length - 1] === '') lines.pop()
+    lines.push(line, '')
+  }
+  return lines.join('\n')
+}
+
+/** 解析 env 文本里的一个键（与 lib/settings-panels.mjs 的 parseEnvDir 同口径）。 */
+export function readEnvValue(text, key) {
+  for (const line of String(text).split('\n')) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line)
+    if (!m || m[1] !== key) continue
+    let v = m[2].trim()
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1)
+    return v
+  }
+  return undefined
+}
+
+/** 审计（**只记掩码/长度，绝不记明文**）。 */
+function audit(entry) {
+  try {
+    const dir = join(DATA_DIR, AUDIT_DIR)
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+    writeFileSync(join(DATA_DIR, AUDIT_FILE), `${JSON.stringify(entry)}\n`, { flag: 'a', mode: 0o600 })
+  } catch { /* 审计失败不阻断主流程，但会在返回值里体现（auditFailed） */ }
+}
+
+/** 解析请求体：`{key:value}` / `{writes:{…}}` / `{writes:[{key,value}]}` 三种都认。 */
+export function normalizePayload(raw) {
+  let doc = raw
+  if (typeof raw === 'string') {
+    try { doc = JSON.parse(raw) } catch { return { error: 'payload 不是合法 JSON' } }
+  }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return { error: 'payload 必须是对象' }
+  const body = doc.writes !== undefined ? doc.writes : doc
+  const out = []
+  if (Array.isArray(body)) {
+    for (const x of body) {
+      if (!x || typeof x !== 'object' || !x.key) return { error: 'writes 数组的每项必须是 {key,value}' }
+      out.push({ key: String(x.key), value: x.value })
+    }
+  } else if (body && typeof body === 'object') {
+    for (const [k, v] of Object.entries(body)) out.push({ key: k, value: v })
+  } else return { error: 'writes 必须是对象或数组' }
+  return { writes: out, actor: String(doc.actor || 'cli') }
+}
+
+function fail(code, message, extra = {}) {
+  const out = { ok: false, code, error: message, ...extra }
+  if (AS_JSON) console.log(JSON.stringify(out))
+  else { console.error(`  ❌ ${message}`); for (const d of extra.details || []) console.error(`     · ${d}`) }
+  process.exit(code)
+}
+
+// ── 主流程 ───────────────────────────────────────────────────────────
+const writeEnabled = has('--allow-write') && String(process.env[ENV_WRITER_ENV] || '').trim() === '1'
+const wl = whitelist()
+// `--catalog`：把**配置目录**里声明为 envfile 且可编辑的项并进同一张白名单（见 `catalogTargets()`）。
+const CATALOG_MODE = has('--catalog')
+const cat = CATALOG_MODE ? await catalogTargets() : { targets: new Map(), errors: [] }
+for (const [k, v] of cat.targets) wl.targets.set(k, v)
+for (const e of cat.errors) wl.errors.push(e)
+
+if (has('--list')) {
+  const list = [...wl.targets.values()].map((t) => ({
+    key: t.panelId === '__catalog__' ? t.field : `${t.panelId}::${t.field}`,
+    panel: t.panelId, label: t.label, type: t.type,
+    env: t.env, scope: t.scope, target: t.rel, exists: existsSync(t.path),
+  }))
+  if (AS_JSON) console.log(JSON.stringify({ ok: true, writer: ENV_WRITER_ENV, enabled: writeEnabled, catalog: CATALOG_MODE, count: list.length, targets: list, errors: wl.errors }, null, 2))
+  else {
+    console.log(`  可写 env 字段（白名单来自设置页声明${CATALOG_MODE ? ' + 配置目录' : ''}）：${list.length} 个；写入器 ${writeEnabled ? '已开启' : `默认关闭（${ENV_WRITER_ENV}=1）`}`)
+    for (const t of list) console.log(`    · ${t.key}  →  ${t.target}  [${t.env}]${t.exists ? '' : '（文件不存在，将新建）'}`)
+    for (const e of wl.errors) console.log(`    ⚠️ ${e.message}`)
+  }
+  process.exitCode = 0
+  // ⚠️ 不用 `process.exit()`：stdout 是管道时写入是异步的，裸退出会把输出**截断**（同日实测）。
+} else {
+
+const payloadText = has('--stdin') ? readFileSync(0, 'utf8') : val('--payload')
+if (!payloadText) fail(2, '缺少请求体：用 --payload \'{"<面板>::<字段>":"值"}\' 或 --stdin')
+const norm = normalizePayload(payloadText)
+if (norm.error) fail(2, norm.error)
+if (!norm.writes.length) fail(2, '请求体里没有任何要写的键')
+
+// ① 白名单校验（未知键/非法值 ⇒ **整请求拒绝**，不部分写入）
+const details = []
+const plan = []
+for (const w of norm.writes) {
+  const t = wl.targets.get(w.key)
+  if (!t) { details.push(`${w.key}：不在白名单里（只允许设置页声明过 env 的字段）`); continue }
+  if (w.value === null || w.value === undefined) { details.push(`${w.key}：值为空对象/未给值`); continue }
+  if (typeof w.value === 'object') { details.push(`${w.key}：值只能是字符串/布尔（收到 ${Array.isArray(w.value) ? 'array' : 'object'}）`); continue }
+  const value = typeof w.value === 'boolean' ? String(w.value) : String(w.value)
+  if (value === '' && !has('--allow-empty')) { details.push(`${w.key}：空值 = 清空该键（如确要清空，加 --allow-empty）`); continue }
+  plan.push({ ...t, value })
+}
+if (details.length) {
+  audit({ ts: new Date().toISOString(), action: 'env-write-rejected', actor: norm.actor, keys: norm.writes.map((w) => w.key), reasons: details })
+  fail(1, `拒绝写入：${details.length} 个键不合格（白名单/取值）`, { details })
+}
+
+if (!writeEnabled) {
+  // dry-run：把"打算做什么"说清楚（默认姿态；真写必须显式开关）
+  const planOut = plan.map((p) => ({ key: keyOf(p), env: p.env, target: p.rel, valueMasked: maskSecret(p.value), action: existsSync(p.path) ? 'update' : 'create' }))
+  if (AS_JSON) console.log(JSON.stringify({ ok: true, dryRun: true, enabled: false, switch: ENV_WRITER_ENV, plan: planOut }))
+  else {
+    console.log(`  ⛔ env 写入器默认关闭（需 --allow-write 且 ${ENV_WRITER_ENV}=1）⇒ 本次只做 dry-run：`)
+    for (const p of planOut) console.log(`     · ${p.action} ${p.target}  ${p.env}=${p.valueMasked}`)
+  }
+  process.exit(3)
+}
+
+// ② 逐文件：备份 → 原子写 → 读回 → （失败则回滚）
+const results = []
+const failed = []
+for (const p of plan) {
+  const entry = { ts: new Date().toISOString(), action: 'env-write', actor: norm.actor, panel: p.panelId, field: p.field, env: p.env, target: p.rel }
+  try {
+    const existed = existsSync(p.path)
+    const before = existed ? readFileSync(p.path, 'utf8') : ''
+    if (existed && readEnvValue(before, p.env) === p.value) {
+      results.push({ key: keyOf(p), env: p.env, target: p.rel, action: 'skip', note: '值未变（幂等）' })
+      audit({ ...entry, mode: 'skip', readback: 'ok' })
+      continue
+    }
+    // ④ 写前备份（整文件；新建的文件不存在 ⇒ 记 created）
+    let backupRel = ''
+    if (existed) {
+      mkdirSync(join(DATA_DIR, BACKUP_DIR), { recursive: true, mode: 0o700 })
+      const bpath = join(DATA_DIR, BACKUP_DIR, `${p.envFile}.${stamp()}-${process.pid}.env`)
+      copyFileSync(p.path, bpath)
+      try { const m = statSync(bpath).mode & 0o777; if (m !== 0o600) writeFileSync(bpath, readFileSync(bpath), { mode: 0o600 }) } catch { /* 权限收紧失败不阻断 */ }
+      backupRel = rel(bpath)
+    }
+    // ⑤ 原子写（同目录临时文件 → rename；权限 0600）
+    mkdirSync(dirname(p.path), { recursive: true, mode: 0o700 })
+    const tmp = `${p.path}.tmp-${process.pid}`
+    writeFileSync(tmp, setEnvLine(before, p.env, p.value), { mode: 0o600 })
+    renameSync(tmp, p.path)
+    // ⑥ 写后读回验收
+    const after = readFileSync(p.path, 'utf8')
+    const got = readEnvValue(after, p.env)
+    if (got !== p.value) {
+      // 回滚：有备份就还原，没有就删掉刚建的文件
+      if (existed) copyFileSync(join(DATA_DIR, backupRel), p.path)
+      else { try { unlinkSync(p.path) } catch { /* ignore */ } }
+      audit({ ...entry, mode: existed ? 'update' : 'create', backup: backupRel, readback: 'mismatch', rolledBack: true, valueMasked: maskSecret(p.value), valueLength: p.value.length })
+      failed.push({ key: keyOf(p), error: `写后读回不一致（已回滚）` })
+      continue
+    }
+    audit({ ...entry, mode: existed ? 'update' : 'create', backup: backupRel, readback: 'ok', valueMasked: maskSecret(p.value), valueLength: p.value.length })
+    results.push({ key: keyOf(p), env: p.env, target: p.rel, action: existed ? 'update' : 'create', backup: backupRel, readback: 'ok' })
+  } catch (err) {
+    audit({ ...entry, mode: 'error', error: String((err && err.message) || err) })
+    failed.push({ key: keyOf(p), error: String((err && err.message) || err) })
+  }
+}
+
+const out = { ok: failed.length === 0, audit: AUDIT_FILE, applied: results, failed }
+if (AS_JSON) console.log(JSON.stringify(out))
+else {
+  for (const r of results) console.log(`  ${r.action === 'skip' ? 'ℹ️ 跳过（值未变）' : '✅ 已写入'} ${r.target}  ${r.env}${r.backup ? `（备份 ${r.backup}）` : '（新建）'}`)
+  for (const f of failed) console.error(`  ❌ ${f.key}：${f.error}`)
+  console.log(`  审计：~/.dsh/argent/${AUDIT_FILE}`)
+}
+// 退出前**先冲刷 stdout**（管道下写入是异步的；裸 `process.exit` 会截断输出 —— 2026-10-09 实测）。
+// 退出码语义不变：0 成功 / 1 有失败。
+await new Promise(() => { process.stdout.write('', () => process.exit(failed.length ? 1 : 0)) })
+}