cardbuddy 0.7.0 → 0.9.0

package/dist/preview-editor/index.html

@@ -8,8 +8,8 @@
     <link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon-16-Cg6Nrosk.png" />
     <link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon-32-B_1744sp.png" />
     <link rel="apple-touch-icon" sizes="180x180" href="/assets/apple-touch-icon-BQcES9QK.png" />
-    <script type="module" crossorigin src="/assets/index-BlscexDE.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-dlbSPb5W.css">
+    <script type="module" crossorigin src="/assets/index-DnpHHKWl.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CrcrVs4F.css">
   </head>
   <body>
     <div id="app"></div>

package/dist/server-core/codeBridge.js

@@ -0,0 +1,359 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { log } from './logger.js'
+
+/**
+ * 外部编辑器代码桥（VSCode / DSL_EDITOR_CMD 指定的任意编辑器，如 cursor）。
+ *
+ * 闭环：
+ *   1) 前端 POST /__code-bridge { code, label } → 后端在 os.tmpdir()/cardbuddy-code-bridge/
+ *      下写 <session>.js 并拉起编辑器，返回 { id, file }；
+ *   2) 后端 chokidar 单文件监听：保存事件防抖 + 内容哈希去重（忽略服务端自写回声），
+ *      有实质变化经 SSE 推 code-bridge-changed { id }（内容走 GET 拉取，避免大 payload）；
+ *   3) 前端 GET /__code-bridge/<id> 取回代码写回 CodeJar（updateCode 不触发 onUpdate，断回声环）；
+ *   4) 会话结束 = 前端 DELETE（面板关闭 / 手动断开 / 组件卸载）或心跳 TTL 兜底
+ *      （前端 5s 心跳，20s 无心跳即删文件，覆盖关浏览器 / 崩溃）；启动时清扫 >24h 残留。
+ *
+ * 「关闭」语义说明：VSCode CLI 把文件交给已运行实例后立即返回，标签页关闭事件不装扩展
+ * 拿不到，故清除时机取「会话结束 + TTL」，而非 VSCode 关标签瞬间。
+ *
+ * 安全：与其余 /__ 端点同信任级（仅 127.0.0.1 + 可选 DSL_DEV_TOKEN）；临时文件名由服务端
+ * 生成（hex 白名单），用户代码内容不进入命令行；DSL_EDITOR_CMD 为开发者自配环境变量，
+ * 按 shell 语义执行（文档注明）。
+ */
+
+export const BRIDGE_DIR_NAME = 'cardbuddy-code-bridge'
+export const SESSION_ID_RE = /^[a-f0-9]{8}$/
+export const HEARTBEAT_TTL_MS = 20000
+const REAP_INTERVAL_MS = 5000
+const WATCH_DEBOUNCE_MS = 150
+const STALE_FILE_MS = 24 * 60 * 60 * 1000
+const MAX_BODY = 2 * 1024 * 1024
+
+/** 桥接临时目录：os.tmpdir() 下独立子目录，不污染仓库 */
+export function bridgeDir() {
+  return path.join(os.tmpdir(), BRIDGE_DIR_NAME)
+}
+
+/** 回写归一：Windows 编辑器可能以 CRLF 落盘，schema 代码串统一 LF，避免无谓 churn */
+export function normalizeEol(s) {
+  if (s == null) return ''
+  return String(s).replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+}
+
+export function hashContent(s) {
+  return crypto.createHash('sha1').update(String(s), 'utf8').digest('hex')
+}
+
+/**
+ * 编辑器拉起方式（纯函数，便于单测）：
+ * - DSL_EDITOR_CMD 优先：整串按 shell 语义执行 + 追加带引号文件路径（支持 cursor / 自定义命令带参数）；
+ * - 否则平台默认 VSCode：mac 走 `open -a`；linux 直接 `code`；win 走 shell 语义的 `code "<file>"`
+ *   （PATH 里的 code 是 code.cmd，裸 spawn 执行不了 .cmd；而 ComSpec + 参数数组会被 node 的
+ *   Windows 引号转义与 cmd /s /c 剥首尾引号规则叠加拆坏，实测命令变成 '\"code\"' 报 9009）；
+ * - 返回 null 表示平台不支持（由 resolveEditorChain 继续降级 vscode:// 协议）。
+ */
+export function resolveEditorSpec(file, env = process.env, platform = process.platform) {
+  const custom = String(env.DSL_EDITOR_CMD || '').trim()
+  if (custom) return { kind: 'custom', command: `${custom} "${file}"`, shell: true }
+  if (platform === 'darwin') {
+    return { kind: 'vscode', cmd: 'open', args: ['-a', 'Visual Studio Code', file], shell: false }
+  }
+  if (platform === 'win32') {
+    return { kind: 'vscode', command: `code "${file}"`, shell: true }
+  }
+  if (platform === 'linux') {
+    return { kind: 'vscode', cmd: 'code', args: [file], shell: false }
+  }
+  return null
+}
+
+/** VSCode 未安装 / CLI 缺失时的协议兜底（安装器默认注册 vscode:// 处理器） */
+export function resolveProtocolSpec(file, env = process.env, platform = process.platform) {
+  const url = 'vscode://file/' + String(file).split(path.sep).join('/')
+  if (platform === 'darwin') return { cmd: 'open', args: [url], shell: false }
+  if (platform === 'win32') {
+    return { command: `start "" "${url}"`, shell: true }
+  }
+  if (platform === 'linux') return { cmd: 'xdg-open', args: [url], shell: false }
+  return null
+}
+
+/**
+ * 拉起方式降级链（跨平台兼容的核心）：
+ * - DSL_EDITOR_CMD 自定义 → 单级；
+ * - win：`code "<file>"`（shell 语义）→ vscode:// 协议；
+ * - mac：`open -a "Visual Studio Code"` → `code` CLI（App 被改名/移动但装过 CLI 时兜一层）→ vscode:// 协议；
+ * - linux：`code` → xdg-open vscode://；
+ * 任一级 spawn ENOENT 或非 0 退出即尝试下一级。
+ */
+export function resolveEditorChain(file, env = process.env, platform = process.platform) {
+  const custom = String(env.DSL_EDITOR_CMD || '').trim()
+  if (custom) return [{ tag: 'custom', spec: { command: `${custom} "${file}"`, shell: true } }]
+  const chain = []
+  const primary = resolveEditorSpec(file, env, platform)
+  if (primary) chain.push({ tag: primary.kind, spec: primary })
+  if (platform === 'darwin') chain.push({ tag: 'vscode-cli', spec: { command: `code "${file}"`, shell: true } })
+  const proto = resolveProtocolSpec(file, env, platform)
+  if (proto) chain.push({ tag: 'protocol', spec: proto })
+  return chain
+}
+
+function launchEditor(file) {
+  const chain = resolveEditorChain(file)
+  const attempt = (i) => {
+    if (i >= chain.length) return false
+    const { tag, spec } = chain[i]
+    const next = () => {
+      if (i + 1 >= chain.length) return false
+      if (!attempt(i + 1)) return false
+      log.ok('代码桥降级下一级拉起方式', { from: tag, to: chain[i + 1].tag, file })
+      return true
+    }
+    try {
+      const child = spec.shell
+        ? spawn(spec.command, { shell: true, stdio: 'ignore' })
+        : spawn(spec.cmd, spec.args, { shell: false, stdio: 'ignore' })
+      let handed = false
+      const fail = (detail) => {
+        if (handed) return
+        handed = true
+        log.warn(`代码桥拉起编辑器失败（${tag}）`, detail)
+        next()
+      }
+      child.on('error', (e) => fail({ message: String(e.message) }))
+      // shell 语义下 spawn 本身不会 ENOENT（shell 一定在），内部命令缺失只体现在退出码上
+      child.on('exit', (code) => {
+        if (code === 0 || code === null) return
+        fail({ code })
+      })
+      return true
+    } catch (e) {
+      log.warn(`代码桥拉起编辑器异常（${tag}）`, e)
+      return next()
+    }
+  }
+  return attempt(0)
+}
+
+/** 启动清扫：删除 >24h 的残留临时文件（会话表在内存，跨重启即孤儿） */
+export function sweepStaleFiles(now = Date.now()) {
+  const dir = bridgeDir()
+  let removed = 0
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    for (const name of fs.readdirSync(dir)) {
+      if (!SESSION_ID_RE.test(name.replace(/\.js$/, ''))) continue
+      const full = path.join(dir, name)
+      try {
+        const st = fs.statSync(full)
+        if (now - st.mtimeMs > STALE_FILE_MS) {
+          fs.rmSync(full, { force: true })
+          removed++
+        }
+      } catch (_) { /* 忽略单文件竞态 */ }
+    }
+  } catch (e) {
+    log.warn('代码桥启动清扫失败', { message: String(e.message) })
+  }
+  return removed
+}
+
+/**
+ * 默认单文件监听（fs.watch + rename 重挂兜底原子保存）。
+ * cardbuddy 会注入 chokidar 版 watchFile（更稳）；本兜底保证中间件零额外依赖，
+ * 使 server/core 可被根仓库（无 chokidar 依赖）直接 import / 单测。
+ */
+export function defaultWatchFile(file, onChange) {
+  let watcher = null
+  let rearmTimer = null
+  let closed = false
+  const arm = () => {
+    if (closed) return
+    try {
+      watcher = fs.watch(file, (event) => {
+        onChange()
+        // 原子保存（临时文件改名覆盖）会让旧 inode 失效：重挂监听
+        if (event === 'rename') rearm()
+      })
+      watcher.on('error', () => rearm())
+    } catch (_) {
+      rearm()
+    }
+  }
+  const rearm = () => {
+    if (closed) return
+    try {
+      watcher && watcher.close()
+    } catch (_) { /* ignore */ }
+    if (rearmTimer) clearTimeout(rearmTimer)
+    rearmTimer = setTimeout(arm, 120)
+  }
+  arm()
+  return {
+    close() {
+      closed = true
+      if (rearmTimer) clearTimeout(rearmTimer)
+      try {
+        watcher && watcher.close()
+      } catch (_) { /* ignore */ }
+    },
+  }
+}
+
+/**
+ * @param {{ root?: string, notify?: (data: object, event?: string) => void, watchFile?: (file: string, cb: () => void) => { close: () => void } }} opts
+ *   - watchFile：单文件监听能力注入（cardbuddy 注入 chokidar 版）；缺省用 fs.watch 兜底。
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
+ */
+export function createCodeBridgeMiddleware({ notify = null, watchFile = null } = {}) {
+  /** @type {Map<string, {id:string,file:string,label:string,lastHash:string,lastHeartbeat:number,watcher:object|null,timer:object|null}>} */
+  const sessions = new Map()
+  const swept = sweepStaleFiles()
+  if (swept) log.ok('代码桥清扫残留临时文件', { removed: swept })
+
+  const push = (data, event) => {
+    if (typeof notify === 'function') notify(data, event)
+  }
+
+  function closeSession(id, reason) {
+    const s = sessions.get(id)
+    if (!s) return false
+    sessions.delete(id)
+    if (s.timer) clearTimeout(s.timer)
+    try { s.watcher && s.watcher.close() } catch (_) { /* ignore */ }
+    try { fs.rmSync(s.file, { force: true }) } catch (e) {
+      log.warn('代码桥删除临时文件失败', { file: s.file, message: String(e.message) })
+    }
+    push({ id, reason }, 'code-bridge-closed')
+    log.ok('代码桥会话结束', { id, reason, file: s.file })
+    return true
+  }
+
+  const reaper = setInterval(() => {
+    const now = Date.now()
+    for (const [id, s] of sessions) {
+      if (now - s.lastHeartbeat > HEARTBEAT_TTL_MS) closeSession(id, 'ttl')
+    }
+  }, REAP_INTERVAL_MS)
+  reaper.unref && reaper.unref()
+
+  function onFileChange(session) {
+    if (session.timer) clearTimeout(session.timer)
+    session.timer = setTimeout(() => {
+      session.timer = null
+      let raw
+      try {
+        raw = fs.readFileSync(session.file, 'utf8')
+      } catch (_) {
+        return // 文件被外部删除：等 TTL / 前端断开收尾
+      }
+      const hash = hashContent(normalizeEol(raw))
+      if (hash === session.lastHash) return // 服务端自写回声 / 无实质变化
+      session.lastHash = hash
+      push({ id: session.id }, 'code-bridge-changed')
+    }, WATCH_DEBOUNCE_MS)
+  }
+
+  function openSession(code, label) {
+    const id = crypto.randomBytes(4).toString('hex')
+    const file = path.join(bridgeDir(), `${id}.js`)
+    const text = normalizeEol(code == null ? '' : code)
+    fs.mkdirSync(bridgeDir(), { recursive: true })
+    fs.writeFileSync(file, text, 'utf8')
+    const session = {
+      id,
+      file,
+      label: String(label || ''),
+      lastHash: hashContent(text),
+      lastHeartbeat: Date.now(),
+      watcher: null,
+      timer: null,
+    }
+    const watch = typeof watchFile === 'function' ? watchFile : defaultWatchFile
+    session.watcher = watch(file, () => onFileChange(session))
+    sessions.set(id, session)
+    const launched = launchEditor(file)
+    log.ok('代码桥会话建立', { id, file, label: session.label, launched })
+    return { id, file, launched }
+  }
+
+  const sendJson = (res, status, payload) => {
+    res.statusCode = status
+    res.setHeader('Content-Type', 'application/json')
+    res.setHeader('Cache-Control', 'no-store')
+    res.end(JSON.stringify(payload))
+  }
+
+  const readBody = (req, limit = MAX_BODY) =>
+    new Promise((resolve, reject) => {
+      let body = ''
+      req.on('data', (c) => {
+        body += c
+        if (body.length > limit) {
+          reject(new Error('body too large'))
+          req.destroy()
+        }
+      })
+      req.on('end', () => resolve(body))
+      req.on('error', reject)
+    })
+
+  return async function codeBridgeMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const method = (req.method || 'GET').toUpperCase()
+    if (!pathname.startsWith('/__code-bridge')) return next()
+
+    // POST /__code-bridge —— 建立会话
+    if (pathname === '/__code-bridge' && method === 'POST') {
+      let payload
+      try {
+        payload = JSON.parse((await readBody(req)) || '{}')
+      } catch (_) {
+        return sendJson(res, 400, { ok: false, error: 'invalid json' })
+      }
+      try {
+        const opened = openSession(payload.code, payload.label)
+        return sendJson(res, 200, { ok: true, ...opened })
+      } catch (e) {
+        log.error('代码桥建立会话失败', e)
+        return sendJson(res, 500, { ok: false, error: String(e.message) })
+      }
+    }
+
+    // 其余端点：/__code-bridge/<id>[/heartbeat]
+    const m = pathname.match(/^\/__code-bridge\/([a-f0-9]{8})(\/heartbeat)?$/)
+    if (!m) return sendJson(res, 404, { ok: false, error: 'unknown bridge route' })
+    const [, id, isHeartbeat] = m
+    const session = sessions.get(id)
+
+    if (isHeartbeat && method === 'POST') {
+      if (!session) return sendJson(res, 404, { ok: false, error: 'session not found', id })
+      session.lastHeartbeat = Date.now()
+      return sendJson(res, 200, { ok: true, id })
+    }
+
+    if (!isHeartbeat && method === 'GET') {
+      if (!session) return sendJson(res, 404, { ok: false, error: 'session not found', id })
+      let raw = ''
+      try {
+        raw = fs.readFileSync(session.file, 'utf8')
+      } catch (e) {
+        return sendJson(res, 410, { ok: false, error: 'temp file gone', id })
+      }
+      session.lastHeartbeat = Date.now()
+      const code = normalizeEol(raw)
+      return sendJson(res, 200, { ok: true, id, code, hash: hashContent(code) })
+    }
+
+    if (!isHeartbeat && method === 'DELETE') {
+      const closed = closeSession(id, 'client')
+      return sendJson(res, closed ? 200 : 404, { ok: closed, id })
+    }
+
+    return sendJson(res, 405, { ok: false, error: 'method not allowed' })
+  }
+}

package/dist/server-core/index.js

@@ -27,6 +27,16 @@ import { createAssetProxyMiddleware } from './assetProxy.js'
 import { createSliceStaticMiddleware } from './sliceStatic.js'
 import { createCardImageMiddleware } from './cardImage.js'
 import { createOpenFolderMiddleware } from './cardOpenFolder.js'
+import { createCodeBridgeMiddleware } from './codeBridge.js'
+import {
+  createLogMiddleware,
+  installLogMirror,
+  subscribeLog,
+  pushLogText,
+  getLogSnapshot,
+  clearLogBuffer,
+  logStreamEnabled,
+} from './logStream.js'
 import { buildDataFromSchema } from './buildDataFromSchema.js'
 
 export {
@@ -47,16 +57,26 @@ export {
   createSliceStaticMiddleware,
   createCardImageMiddleware,
   createOpenFolderMiddleware,
+  createCodeBridgeMiddleware,
+  createLogMiddleware,
+  installLogMirror,
+  subscribeLog,
+  pushLogText,
+  getLogSnapshot,
+  clearLogBuffer,
+  logStreamEnabled,
   buildDataFromSchema,
 }
 
 /**
  * 把全部卡片中间件挂到 Connect 风格容器（需实现 .use(mw)）。
  * @param {{ use: (mw: Function) => void }} app
- * @param {{ root: string, viteServer?: import('vite').ViteDevServer | null, upstream?: string }} opts
+ * @param {{ root: string, viteServer?: import('vite').ViteDevServer | null, upstream?: string, notify?: (data: object, event?: string) => void, watchFile?: (file: string, cb: () => void) => { close: () => void } }} opts
  *   - upstream：FinMall 远端站点基址（来自 FINMALL_BASE_URL），资源代理回源用；空串表示不回源。
+ *   - notify：SSE 推送入口（cardbuddy 的 /__events hub）；代码桥经它推 bridge 事件，缺省时静默降级。
+ *   - watchFile：代码桥单文件监听能力注入（chokidar 版）；缺省代码桥用 fs.watch 兜底。
  */
-export function mountCoreMiddlewares(app, { root, viteServer = null, upstream = '' }) {
+export function mountCoreMiddlewares(app, { root, viteServer = null, upstream = '', notify = null, watchFile = null }) {
   app.use(createSyncMiddleware({ root }))
   app.use(createPreviewMiddleware({ root }))
   app.use(createLoginCredentialsMiddleware({ root }))
@@ -76,6 +96,11 @@ export function mountCoreMiddlewares(app, { root, viteServer = null, upstream =
   app.use(createBboxMiddleware({ root }))
   // 在系统文件管理器中打开当前卡片本地目录（编辑器顶栏「打开目录」按钮触发，跨平台由后端完成）
   app.use(createOpenFolderMiddleware({ root }))
+  // 外部编辑器代码桥（VSCode / DSL_EDITOR_CMD）：临时 js + 保存回写 + 会话 TTL 清理
+  app.use(createCodeBridgeMiddleware({ root, notify, watchFile }))
+  // 服务日志流（编辑器底部「服务日志」面板）：GET /__logs 取历史 / 断线补漏，
+  // POST /__logs/ingest 供外部进程（启动器）注入；实时推送由 SSE hub 侧订阅完成。
+  app.use(createLogMiddleware())
   // 卡片预览图静态服务：/__card-image/<id> → src/cards/<id>/<id>.<ext>（编辑器网格预览缩略图用，
   // 复用本地静态服务，避免实时无头截图）。
   app.use(createCardImageMiddleware({ root }))