memory-eternal 0.9.17 → 0.10.0

package/lib/config-sync.js

@@ -0,0 +1,90 @@
+// 配置同步（共享文件协议）：让「独立 Web 页」也能保存配置。
+//
+// 背景：独立 web server 进程里没有 DSH 的 settings 服务，`ctx.settings.update` 不存在，
+// 所以它的 /config 过去只能只读 —— 用户点保存永远没反应（issue #12 的另一半）。
+// 方案：独立端把改动写进 `memory-eternal-config.pending.json`，DSH 宿主激活时与运行期
+// 轮询该文件，用 settings.update 应用后删除。DSH 没运行时改动留在文件里，下次启动生效。
+import fs from 'node:fs'
+import path from 'node:path'
+import { configFilePath } from './capture-run.js'
+
+/** 待应用配置文件的路径（与共享配置文件同目录）。 */
+export function pendingConfigPath(env = process.env) {
+  return String(configFilePath(env)).replace(/\.json$/i, '.pending.json')
+}
+
+/** 读待应用改动；文件不存在/损坏都返回 null（不影响主流程）。 */
+export function readPendingConfig(env = process.env) {
+  try {
+    const data = JSON.parse(fs.readFileSync(pendingConfigPath(env), 'utf8'))
+    if (!data || typeof data.patch !== 'object' || data.patch === null || Array.isArray(data.patch)) return null
+    return { at: Number(data.at) || 0, tries: Number(data.tries) || 0, patch: data.patch }
+  } catch { return null }
+}
+
+/** 原子写入待应用改动（tmp + rename），返回写入内容。 */
+export function writePendingConfig(env, patch, now = Date.now(), tries = 0) {
+  const file = pendingConfigPath(env)
+  const data = tries > 0 ? { at: now, tries, patch } : { at: now, patch }
+  const tmp = file + '.' + process.pid + '.tmp'
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8')
+  fs.renameSync(tmp, file)
+  return data
+}
+
+/** 删除待应用文件；不存在也算成功。 */
+export function clearPendingConfig(env = process.env) {
+  try { fs.unlinkSync(pendingConfigPath(env)); return true } catch { return false }
+}
+
+/**
+ * 监听待应用文件的变化（毫秒级触发），用于把「独立页保存 → DSH 应用」从 5 秒轮询
+ * 提升到准即时。监听失败（平台/权限）时退化为不监听 —— 仍有 5 秒轮询兜底。
+ * @returns {() => void} 停止监听
+ */
+export function watchPendingConfig(env, onChange, { debounceMs = 60 } = {}) {
+  const file = pendingConfigPath(env)
+  let timer = null
+  let watcher = null
+  const fire = () => {
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => { try { onChange() } catch { /* 回调异常不影响监听 */ } }, debounceMs)
+  }
+  try {
+    // 监听**文件本身**而不是父目录：
+    // 父目录被删除 / 重命名时（临时 HOME、清理脚本、测试收尾），Windows 上 libuv 会断言崩溃
+    // （`Assertion failed: !_wcsnicmp(filename, dir, dirlen), src\win\fs-event.c`），
+    // 而监听文件时目录消失只会得到 ENOENT，不会带崩进程。也顺带免掉了按文件名过滤。
+    watcher = fs.watch(file, () => fire())
+    if (typeof watcher.unref === 'function') watcher.unref()
+  } catch { return () => {} }
+  return () => {
+    if (timer) clearTimeout(timer)
+    try { watcher.close() } catch { /* 已关闭 */ }
+  }
+}
+
+/**
+ * 取出并应用一次待应用改动：apply(patch) 成功后删除文件；失败保留（下轮重试）。
+ * @returns {Promise<object|null>} 应用成功的 patch，没有待应用项时返回 null
+ */
+export async function drainPendingConfig(env, apply, maxTries = 5) {
+  const pending = readPendingConfig(env)
+  if (!pending) return null
+  try {
+    await apply(pending.patch)
+  } catch (error) {
+    const tries = (pending.tries || 0) + 1
+    if (tries >= maxTries) {
+      // 连续失败（多半是值不合法）：放弃并删掉，否则会每 5 秒无限重试
+      clearPendingConfig(env)
+      const dropped = new Error('待应用配置连续失败 ' + tries + ' 次已放弃：' + String((error && error.message) || error))
+      dropped.dropped = true
+      throw dropped
+    }
+    writePendingConfig(env, pending.patch, pending.at, tries)
+    throw error
+  }
+  clearPendingConfig(env)
+  return pending.patch
+}

package/lib/db.js

@@ -26,6 +26,19 @@ export function getDb(root) {
   return db
 }
 
+/**
+ * 建表。
+ *
+ * 存储模型（v0.10「两套存储体系」）：
+ *   cards       = **主库 / 正常区**：物理上只存 approved。召回、检索、图谱、去重、
+ *                 导出这些读路径**不再需要写 `WHERE status='approved'`** —— 查主库即安全。
+ *   quarantine  = **隔离区 / 异常区**：pending（待审）/ rejected（驳回）/ deleted（回收站）。
+ *                 审核中心与回收站的唯一数据源；除审核操作外无人读它。
+ *
+ * 这样做的原因：v0.9 及以前是「一张表 + status 列」，安全性依赖每一处 SQL 都记得加
+ * 状态条件。审计发现三处漏了（去重池把新知识追加进待审卡、readCard 直读未审核正文、
+ * /card 接口无状态校验）—— 只要有人再漏一处就会重演。物理分表后，漏写 `WHERE` 也不泄漏。
+ */
 function initTables(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS config (
@@ -35,14 +48,14 @@ function initTables(db) {
     );
 
     CREATE TABLE IF NOT EXISTS cards (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      id INTEGER PRIMARY KEY,
       path TEXT UNIQUE NOT NULL,
       kind TEXT NOT NULL DEFAULT 'knowledge',
       title TEXT NOT NULL DEFAULT '',
       tags TEXT DEFAULT '[]',
       body TEXT NOT NULL DEFAULT '',
       summary TEXT DEFAULT '',
-      status TEXT NOT NULL DEFAULT 'pending',
+      status TEXT NOT NULL DEFAULT 'approved',
       source TEXT DEFAULT '',
       submitted_by TEXT DEFAULT '',
       severity TEXT DEFAULT 'info',
@@ -56,13 +69,43 @@ function initTables(db) {
     CREATE INDEX IF NOT EXISTS idx_cards_kind ON cards(kind);
     CREATE INDEX IF NOT EXISTS idx_cards_deleted ON cards(deleted_at);
 
+    -- 隔离区：结构与主库一致，另加 quarantined_at（进隔离区的时间）与 quarantine_reason
+    CREATE TABLE IF NOT EXISTS quarantine (
+      id INTEGER PRIMARY KEY,
+      path TEXT UNIQUE NOT NULL,
+      kind TEXT NOT NULL DEFAULT 'knowledge',
+      title TEXT NOT NULL DEFAULT '',
+      tags TEXT DEFAULT '[]',
+      body TEXT NOT NULL DEFAULT '',
+      summary TEXT DEFAULT '',
+      status TEXT NOT NULL DEFAULT 'pending',
+      source TEXT DEFAULT '',
+      submitted_by TEXT DEFAULT '',
+      severity TEXT DEFAULT 'info',
+      reason TEXT DEFAULT '',
+      created_at TEXT DEFAULT (datetime('now')),
+      updated_at TEXT DEFAULT (datetime('now')),
+      deleted_at TEXT,
+      quarantined_at TEXT DEFAULT (datetime('now')),
+      quarantine_reason TEXT DEFAULT ''
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_quarantine_status ON quarantine(status);
+    CREATE INDEX IF NOT EXISTS idx_quarantine_kind ON quarantine(kind);
+    CREATE INDEX IF NOT EXISTS idx_quarantine_deleted ON quarantine(deleted_at);
+
+    -- 更新记录：card_id 指向 cards.id **或** quarantine.id（两表共享 id 空间）。
+    -- 因此这里**不能**建外键：SQLite 的外键只认一张父表，卡被搬进隔离区时 FK 校验会直接失败
+    -- （实测 FOREIGN KEY constraint failed）。永久删除卡片时由 deleteCard 手工清理更新记录。
     CREATE TABLE IF NOT EXISTS card_updates (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
-      card_id INTEGER NOT NULL REFERENCES cards(id) ON DELETE CASCADE,
+      card_id INTEGER NOT NULL,
       content TEXT NOT NULL,
       created_at TEXT DEFAULT (datetime('now'))
     );
 
+    CREATE INDEX IF NOT EXISTS idx_card_updates_card ON card_updates(card_id);
+
     CREATE TABLE IF NOT EXISTS feedback (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       query TEXT NOT NULL,
@@ -81,7 +124,111 @@ function initTables(db) {
       reason TEXT DEFAULT '',
       created_at TEXT DEFAULT (datetime('now'))
     );
+
+    -- 卡片 id 发号器（两张表**共用**）。
+    --
+    -- 为什么不用 AUTOINCREMENT：cards 与 quarantine 是两张 AUTOINCREMENT 表，各有一份
+    -- sqlite_sequence 计数器，且都从 1 开始 —— 于是两张表会同时出现 id=1，而卡需要在
+    -- 两表间搬家并保留 id，必然撞 UNIQUE constraint failed。实测确认：
+    -- 共享 id 空间 + 双 AUTOINCREMENT 在 SQLite 里无法自洽。
+    -- 改为「显式发号 + 单一持久计数器」：id 全库唯一、单调递增、删除后也不复用，
+    -- 而且任何一次 renumber 都是显式 error，不会静默串记录。
+    CREATE TABLE IF NOT EXISTS card_sequence (
+      name TEXT PRIMARY KEY,
+      seq INTEGER NOT NULL
+    );
   `)
+  // 种子：取两表最大 id（老库升级时把已有卡都覆盖进去）；没有则从 0 起
+  db.prepare(`INSERT INTO card_sequence (name, seq) VALUES ('card', 0) ON CONFLICT(name) DO NOTHING`).run()
+  db.prepare(`UPDATE card_sequence SET seq = (
+      SELECT MAX(m) FROM (SELECT MAX(id) m FROM cards UNION ALL SELECT MAX(id) FROM quarantine)
+    ) WHERE name = 'card' AND seq < (
+      SELECT MAX(m) FROM (SELECT MAX(id) m FROM cards UNION ALL SELECT MAX(id) FROM quarantine)
+    )`).run()
+  migrateToQuarantine(db)
+}
+
+/** 分配一个新的卡片 id（跨两张表唯一、单调递增）。 */
+export function nextCardId(db) {
+  db.prepare("UPDATE card_sequence SET seq = seq + 1 WHERE name = 'card'").run()
+  const row = db.prepare("SELECT seq FROM card_sequence WHERE name = 'card'").get()
+  if (!row) throw new Error('card_sequence 未初始化')
+  return row.seq
+}
+
+/** 主库里的每一个 status 常量：只有它算「正常区」。 */
+export const MAIN_STATUS = 'approved'
+/** 隔离区里的三个 status 常量。 */
+export const QUARANTINE_STATUSES = ['pending', 'rejected', 'deleted']
+/** 状态 → 它应该待在哪张表。 */
+export function tableForStatus(status) {
+  return String(status) === MAIN_STATUS ? 'cards' : 'quarantine'
+}
+
+/**
+ * 迁移到两套存储（幂等，可重复执行，每次 getDb 都会跑一遍）：
+ * 把主库里所有非 approved 的行搬进隔离区，并带上它们的 card_updates。
+ *
+ * 关键性质：**绝不删除任何内容**，只换表。老版本代码回滚后看不到隔离区（审核队列会
+ * 显示为空），但数据还在同一个 .db 文件里，升级回来即恢复。
+ */
+export function migrateToQuarantine(db) {
+  let pending = []
+  try {
+    pending = db.prepare("SELECT id, path FROM cards WHERE status <> ?").all(MAIN_STATUS)
+  } catch { return 0 }
+  if (!pending.length) return 0
+
+  // 老库的 card_updates 有指向 cards(id) 的外键：把卡搬走时 FK 会拒绝删除主库行。
+  // 迁移期间**临时关掉外键校验**（SQLite 允许 PRAGMA foreign_keys 在无事务时切换），
+  // 搬完立刻恢复 —— 之后建表/写入仍受外键保护。
+  let fkWasOn = false
+  try {
+    fkWasOn = db.prepare('PRAGMA foreign_keys').get().foreign_keys === 1
+    if (fkWasOn) db.exec('PRAGMA foreign_keys = OFF')
+  } catch { fkWasOn = false }
+
+  const insertQuarantine = db.prepare(`
+    INSERT OR IGNORE INTO quarantine
+      (id, path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, deleted_at, quarantined_at, quarantine_reason)
+    SELECT id, path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, deleted_at, datetime('now'), '迁移：主库只保留 approved'
+    FROM cards WHERE id = ?
+  `)
+  const dropFromMain = db.prepare('DELETE FROM cards WHERE id = ?')
+
+  let moved = 0
+  for (const row of pending) {
+    try {
+      db.exec('BEGIN')
+      const info = insertQuarantine.run(row.id)
+      // card_updates 按 card_id 关联，id 不变 → 更新记录跟着卡一起走，无需改写
+      if (info.changes) moved++
+      dropFromMain.run(row.id)
+      db.exec('COMMIT')
+    } catch (e) {
+      try { db.exec('ROLLBACK') } catch { /* 已回滚 */ }
+      process.stderr.write(`[memory-eternal] 隔离迁移失败（${row.path}）：${e?.message || e}\n`)
+    }
+  }
+  if (fkWasOn) { try { db.exec('PRAGMA foreign_keys = ON') } catch { /* 恢复失败：下次 getDb 会再设一次 */ } }
+  if (moved) process.stderr.write(`[memory-eternal] 已把 ${moved} 张未审核卡搬进隔离区（主库只留 approved）\n`)
+  return moved
+}
+
+/**
+ * 一致性不变量：主库只能有 approved。
+ * 供测试与「用量/今日」体检使用 —— 正常永远是 0，非 0 说明有代码绕过写入闸门。
+ */
+export function checkMainStoreInvariant(root) {
+  const db = getDb(root)
+  try {
+    const bad = db.prepare('SELECT status, COUNT(*) n FROM cards WHERE status <> ? GROUP BY status').all(MAIN_STATUS)
+    const total = db.prepare('SELECT COUNT(*) n FROM cards').get().n
+    const quarantined = db.prepare('SELECT status, COUNT(*) n FROM quarantine GROUP BY status').all()
+    return { ok: bad.length === 0, violations: bad, mainTotal: total, quarantine: quarantined }
+  } catch (e) {
+    return { ok: false, violations: [], mainTotal: 0, quarantine: [], error: String(e?.message || e) }
+  }
 }
 
 /**

package/lib/sse.js

@@ -0,0 +1,51 @@
+// SSE 推送中心：把「配置/卡片变更」即时推给所有已打开的页面（不必手动刷新）。
+// 两个宿主（DSH 内嵌 + 独立 web）共用同一套实现；纯逻辑，便于单测（注入假 res）。
+export function createHub({ heartbeatMs = 25000 } = {}) {
+  const clients = new Set()
+  let timer = null
+  const send = (res, chunk) => {
+    try { res.write(chunk); return true } catch { return false }
+  }
+  const drop = (res) => {
+    clients.delete(res)
+    try { res.end() } catch { /* 已断开 */ }
+  }
+  const ensureTimer = () => {
+    if (timer || !(heartbeatMs > 0)) return
+    timer = setInterval(() => {
+      for (const res of [...clients]) if (!send(res, ': ping\n\n')) drop(res)
+    }, heartbeatMs)
+    if (typeof timer.unref === 'function') timer.unref()
+  }
+  return {
+    /** 接入一个连接（保持长连接，不要 end）。 */
+    add(res) {
+      try {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream; charset=utf-8',
+          'Cache-Control': 'no-store',
+          Connection: 'keep-alive',
+          'X-Accel-Buffering': 'no',
+        })
+      } catch { return false }
+      if (!send(res, 'retry: 3000\n\n')) return false
+      clients.add(res)
+      ensureTimer()
+      const onClose = () => drop(res)
+      try { res.on('close', onClose); res.on('error', onClose) } catch { /* 某些响应对象没有 on */ }
+      return true
+    },
+    /** 广播事件（event: <name>，data: JSON）。返回当前连接数。 */
+    broadcast(event, data) {
+      const chunk = 'event: ' + event + '\ndata: ' + JSON.stringify(data === undefined ? {} : data) + '\n\n'
+      for (const res of [...clients]) if (!send(res, chunk)) drop(res)
+      return clients.size
+    },
+    get size() { return clients.size },
+    close() {
+      if (timer) clearInterval(timer)
+      timer = null
+      for (const res of [...clients]) drop(res)
+    },
+  }
+}