cardbuddy 0.6.0

package/dist/server-core/cardValidate.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFile, execFileSync } from 'node:child_process'
+
+/**
+ * 契约校验端点（L0 闭环之一）。
+ *
+ * - GET /__validate/<id>  ：单卡校验，返回 { id, ok, errors, warnings, durationMs }
+ * - GET /__validate       ：全量校验，逐卡跑 Python 校验器，汇总返回
+ *
+ * 实现：子进程调用 `skills/dsl-card-generator/scripts/validate_schema.py --json`。
+ * Python 解释器解析顺序：`DSL_PYTHON` → `python3` → `python`，都不存在时返回
+ * **503 {error:'python-not-found'}** 而非 500，让 Agent / CI 能区分「环境没装」和「卡片有问题」。
+ *
+ * @param {{ root: string }} opts
+ */
+
+/** 校验脚本在仓库根下的固定相对路径（导出供 MCP 复用） */
+export function scriptPath(root) {
+  return path.join(
+    root,
+    'skills',
+    'dsl-card-generator',
+    'scripts',
+    'validate_schema.py',
+  )
+}
+
+/** 解析可用的 python 解释器；找不到返回 null（导出供 MCP 复用） */
+export function resolvePython() {
+  if (process.env.DSL_PYTHON) return process.env.DSL_PYTHON
+  for (const cmd of ['python3', 'python']) {
+    try {
+      execFileSync(cmd, ['--version'], { stdio: 'ignore', timeout: 5000 })
+      return cmd
+    } catch {
+      /* 该命令不可用，试下一个 */
+    }
+  }
+  return null
+}
+
+/**
+ * 跑一次 Python 校验器，返回结构化结果。
+ * @returns {Promise<{ok:boolean, errors:string[], warnings:string[], durationMs:number, toolError?:string}>}
+ */
+export function validateCard(python, pyScript, schemaPath, { checkData = true, timeout = 8000 } = {}) {
+  return new Promise((resolve) => {
+    const args = [pyScript, schemaPath, '--json']
+    if (!checkData) args.push('--no-data')
+    execFile(python, args, { timeout, maxBuffer: 8 * 1024 * 1024, windowsHide: true }, (err, stdout) => {
+      if (err && err.code === 'ENOENT') {
+        return resolve({ ok: false, errors: [`python interpreter not found: ${python}`], warnings: [], toolError: 'python-not-found' })
+      }
+      const raw = (stdout || '').trim()
+      if (!raw) {
+        const reason = err && err.killed ? 'timeout' : err ? String(err.message) : 'empty output'
+        return resolve({ ok: false, errors: [`validator produced no output (${reason})`], warnings: [], toolError: err && err.killed ? 'timeout' : 'no-output' })
+      }
+      try {
+        const parsed = JSON.parse(raw)
+        return resolve({
+          ok: !!parsed.ok,
+          errors: parsed.errors || [],
+          warnings: parsed.warnings || [],
+          durationMs: parsed.durationMs || 0,
+        })
+      } catch (e) {
+        return resolve({ ok: false, errors: [`failed to parse validator output: ${e.message}`, raw.slice(0, 500)], warnings: [], toolError: 'parse-error' })
+      }
+    })
+  })
+}
+
+export function createValidateMiddleware({ root }) {
+  const pyScript = scriptPath(root)
+  return async function validateMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const m = pathname.match(/^\/__validate(?:\/([^/]+))?$/)
+    if (!m) return next()
+    const id = m[1] // undefined => 全量
+
+    const python = resolvePython()
+    if (!python) {
+      res.statusCode = 503
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({
+        error: 'python-not-found',
+        message: '未找到 python3/python，请在 PATH 中安装 Python 或设置 DSL_PYTHON 环境变量',
+      }))
+    }
+
+    const noData = /[?&]no-data\b/.test(req.url || '')
+
+    try {
+      if (!id) {
+        const cardsDir = path.join(root, 'src', 'cards')
+        const results = []
+        if (fs.existsSync(cardsDir)) {
+          for (const cid of fs.readdirSync(cardsDir).sort()) {
+            const dir = path.join(cardsDir, cid)
+            if (!fs.statSync(dir).isDirectory()) continue
+            const sp = path.join(dir, 'schema.json')
+            if (!fs.existsSync(sp)) continue
+            const r = await validateCard(python, pyScript, sp, { checkData: !noData })
+            results.push({ id: cid, ...r })
+          }
+        }
+        const allOk = results.length > 0 && results.every((r) => r.ok)
+        res.statusCode = 200
+        res.setHeader('Content-Type', 'application/json')
+        res.setHeader('Cache-Control', 'no-store')
+        return res.end(JSON.stringify({ ok: allOk, count: results.length, cards: results }))
+      }
+
+      const dir = path.join(root, 'src', 'cards', id)
+      const sp = path.join(dir, 'schema.json')
+      if (!fs.existsSync(sp)) {
+        res.statusCode = 404
+        res.setHeader('Content-Type', 'application/json')
+        return res.end(JSON.stringify({ error: 'card not found', id }))
+      }
+      const r = await validateCard(python, pyScript, sp, { checkData: !noData })
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify({ id, ...r }))
+    } catch (e) {
+      res.statusCode = 500
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'validate failed', message: String(e && e.message) }))
+    }
+  }
+}

package/dist/server-core/index.js

@@ -0,0 +1,82 @@
+/**
+ * server/core —— 卡片后端中间件的「单一真相」与统一装配入口。
+ *
+ * 设计：
+ *   - 每个端点都是独立 `(req, res, next)` 中间件工厂（见同目录各文件），与 Express / Vite
+ *     中间件容器解耦，因此可被两处复用：
+ *       1) Vite 插件（server/cardServer.js，编辑器内核开发 same-origin 路径）；
+ *       2) 独立本地开发服务（packages/cardbuddy，公网静态编辑器指向本机路径）。
+ *   - mountCoreMiddlewares(app, opts) 把全部中间件挂到任意 Connect 风格容器（Vite 的
+ *     server.middlewares 或 connect 实例皆可），两处共用、改一处两处同步。
+ *
+ * 注意：renderStatus / nodeModels 需要活着的 vite 实例做 ssrLoadModule，故 mountCoreMiddlewares
+ * 接收 viteServer 参数透传；无 SSR 需求的场景可传 null（这两个端点会返回明确错误）。
+ */
+import { createSyncMiddleware, createPreviewMiddleware, createLoginCredentialsMiddleware } from './cardSync.js'
+import { createCardFilesMiddleware } from './cardFiles.js'
+import { createSaveMiddleware } from './cardSave.js'
+import { createImportMetaMiddleware } from './cardImportMeta.js'
+import { createHistoryMiddleware } from './cardHistory.js'
+import { createValidateMiddleware } from './cardValidate.js'
+import { createRenderStatusMiddleware } from './renderStatus.js'
+import { createScreenshotMiddleware } from './screenshot.js'
+import { createBboxMiddleware } from './bbox.js'
+import { createNodeModelsMiddleware } from './nodeModels.js'
+import { createAssetProxyMiddleware } from './assetProxy.js'
+import { createSliceStaticMiddleware } from './sliceStatic.js'
+import { createCardImageMiddleware } from './cardImage.js'
+import { createOpenFolderMiddleware } from './cardOpenFolder.js'
+import { buildDataFromSchema } from './buildDataFromSchema.js'
+
+export {
+  createSyncMiddleware,
+  createPreviewMiddleware,
+  createLoginCredentialsMiddleware,
+  createCardFilesMiddleware,
+  createSaveMiddleware,
+  createImportMetaMiddleware,
+  createHistoryMiddleware,
+  createValidateMiddleware,
+  createRenderStatusMiddleware,
+  createScreenshotMiddleware,
+  createBboxMiddleware,
+  createNodeModelsMiddleware,
+  createAssetProxyMiddleware,
+  createSliceStaticMiddleware,
+  createCardImageMiddleware,
+  createOpenFolderMiddleware,
+  buildDataFromSchema,
+}
+
+/**
+ * 把全部卡片中间件挂到 Connect 风格容器（需实现 .use(mw)）。
+ * @param {{ use: (mw: Function) => void }} app
+ * @param {{ root: string, viteServer?: import('vite').ViteDevServer | null, upstream?: string }} opts
+ *   - upstream：FinMall 远端站点基址（来自 FINMALL_BASE_URL），资源代理回源用；空串表示不回源。
+ */
+export function mountCoreMiddlewares(app, { root, viteServer = null, upstream = '' }) {
+  app.use(createSyncMiddleware({ root }))
+  app.use(createPreviewMiddleware({ root }))
+  app.use(createLoginCredentialsMiddleware({ root }))
+  app.use(createCardFilesMiddleware({ root }))
+  app.use(createSaveMiddleware({ root }))
+  app.use(createHistoryMiddleware({ root }))
+  app.use(createValidateMiddleware({ root }))
+  app.use(createRenderStatusMiddleware({ root, viteServer }))
+  app.use(createNodeModelsMiddleware({ root, viteServer }))
+  app.use(createImportMetaMiddleware({ root }))
+  app.use(createScreenshotMiddleware({ root }))
+  // 渲染几何度量（UI 还原度对拍 P0）：/__bbox/<id> 输出逐元素 bbox，供 fidelity_report.mjs 与设计稿 spec 对拍。
+  app.use(createBboxMiddleware({ root }))
+  // 在系统文件管理器中打开当前卡片本地目录（编辑器顶栏「打开目录」按钮触发，跨平台由后端完成）
+  app.use(createOpenFolderMiddleware({ root }))
+  // 卡片预览图静态服务：/__card-image/<id> → src/cards/<id>/<id>.<ext>（编辑器网格预览缩略图用，
+  // 复用本地静态服务，避免实时无头截图）。
+  app.use(createCardImageMiddleware({ root }))
+  // 本地切图静态服务：/slices/* → src/slices/*（与 dsl-card-generator 约定对齐）。
+  // 必须在资源代理之前挂载，避免被 /minio 等代理前缀误吞。
+  app.use(createSliceStaticMiddleware({ root }))
+  // 资源代理：由 8787（cardbuddy）统一提供，Vite 彻底零后端插件。
+  // upstream 空串时中间件仍会注册，但 /minio 等请求只会走占位图兜底，不会崩溃。
+  app.use(createAssetProxyMiddleware({ root, upstream }))
+}

package/dist/server-core/logger.js

@@ -0,0 +1,241 @@
+/**
+ * server/core/logger.js
+ * 后台服务统一日志美化（时间戳 + 级别色 + 框线 + 自动脱敏）。
+ *
+ * 设计目标
+ *  - 可读性：时间戳、级别标签、对齐框线；
+ *  - 安全性：redact() 对 schema / data / 远端响应体等大段正文只给规模概览，
+ *    绝不 dump 卡片正文；Error 只附 message + 简短 stack；
+ *  - 双消费方：① server/core 内兄弟引用 './logger.js'；
+ *              ② skills/finmall-card-sync/scripts/*.mjs 经 '../../../server/core/logger.js' 借用；
+ *    build 把 server/core 整体复制到 dist/server-core，兄弟引用在发布态仍成立。
+ *
+ * 颜色原语基于 chalk（零配置、自动探测 TTY / FORCE_COLOR / CI / NO_COLOR /
+ * TERM，支持真彩 level 3，无能力时优雅降级到 level 0 原样输出）。等级色直接取
+ * 项目设计 Token 的 RGB（design/深浅主题配色规范手册.md 深色变体），经
+ * chalk.rgb 走真彩(38;2)；这既让终端日志与品牌色一致，又绕开部分终端“烂 8 色调色板”
+ * 把多级日志压成“纯色”的问题。早期的手写 ANSI + IS_TTY 朴素探测已废弃
+ * （旧逻辑在 IDE 集成终端 / 管道 / CI 下会整屏去色）。
+ * 其余逻辑：脱敏 fmt、CJK 宽度对齐、box/rule 维持原样，便于被 skill 跨目录 import。
+ */
+
+// ——————————————————————————————————————————————
+// 颜色（chalk：能力探测 + 真彩 + 优雅降级全托管，无需手写 IS_TTY/NO_COLOR）
+// ——————————————————————————————————————————————
+import chalk from 'chalk';
+
+// 等级 → 设计 Token RGB（取自 design/深浅主题配色规范手册.md 深色变体；
+// 终端编辑器外壳为深色主题）。走 chalk.rgb 真彩(38;2)，能力不够时 chalk 自动
+// 降级到最近 8/256 色或 level 0 原样，无需手写探测，也绕开部分终端“烂 8 色调色板”
+// 把多级日志压成“纯色”的问题。
+const PALETTE = {
+  info: [107, 131, 247], // 主色 deep #6B83F7
+  ok: [52, 211, 153], // 成功 deep #34D399
+  warn: [251, 191, 36], // 警告 amber #FBBF24
+  error: [248, 113, 113], // 错误 red   #F87171
+  gray: [148, 163, 184], // 时间戳 slate #94A3B8
+  dim: [100, 116, 139], // 弱化 slate #64748B
+};
+
+function rgbOf(color) {
+  return PALETTE[color] || PALETTE.gray;
+}
+
+/** 给文本上色：chalk.level=0 时自动原样返回，其余按 Token RGB 渲染 */
+export function paint(color, s) {
+  const [r, g, b] = rgbOf(color);
+  return chalk.rgb(r, g, b)(s);
+}
+function paintBold(color, s) {
+  const [r, g, b] = rgbOf(color);
+  return chalk.bold(chalk.rgb(r, g, b)(s));
+}
+
+// ——————————————————————————————————————————————
+// 显示宽度（CJK / 全角计 2，保证框线对齐）
+// ——————————————————————————————————————————————
+function isWideCode(cp) {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0x303e) || // CJK 部首 / 康熙
+    (cp >= 0x3041 && cp <= 0x33ff) || // 假名 / CJK 符号
+    (cp >= 0x3400 && cp <= 0x4dbf) || // CJK 扩展 A
+    (cp >= 0x4e00 && cp <= 0x9fff) || // CJK 统一
+    (cp >= 0xa000 && cp <= 0xa4cf) || // 彝文
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul 音节
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK 兼容
+    (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK 兼容形式
+    (cp >= 0xff00 && cp <= 0xff60) || // 全角 ASCII
+    (cp >= 0xffe0 && cp <= 0xffe6) // 全角符号
+  );
+}
+
+/** 文本在终端的显示宽度（中文 / 全角按 2 计），用于框线对齐 */
+export function dispWidth(str) {
+  let w = 0;
+  const s = String(str);
+  for (const ch of s) {
+    w += isWideCode(ch.codePointAt(0)) ? 2 : 1;
+  }
+  return w;
+}
+
+function stripAnsi(s) {
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+// ——————————————————————————————————————————————
+// 大小格式化
+// ——————————————————————————————————————————————
+/** 字节数 → 人类可读（B / KB / MB） */
+export function fmtBytes(n) {
+  if (n == null || Number.isNaN(n)) return '-';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+// ——————————————————————————————————————————————
+// 紧凑化：把任意值格式化为单行日志安全表示（自动脱敏大段正文）
+// ——————————————————————————————————————————————
+// 这些键出现时不展开内容，只给规模概览，杜绝卡片 schema / data / 响应体刷屏。
+const BULKY_KEYS = new Set([
+  'schema', 'data', 'response', 'verified', 'raw', 'payload', 'body',
+  'dictionary', 'view', 'inputParams', 'schemaValue', 'summary',
+  'components', 'children', 'nodes',
+]);
+
+const MAX_INLINE = 160; // 字符串超过该长度截断
+const MAX_KEYS = 8; // 对象最多展开键数
+const MAX_ITEMS = 8; // 数组最多展开元素数
+
+function brief(v) {
+  if (Array.isArray(v)) return `Array(${v.length})`;
+  if (v && typeof v === 'object') return `Object(${Object.keys(v).length})`;
+  if (typeof v === 'string') return `str(${v.length})`;
+  return typeof v;
+}
+
+/** 把任意值格式化成单行、紧凑、已脱敏的日志表示 */
+export function fmt(v, depth = 0) {
+  if (v == null) return 'null';
+  if (v instanceof Error) return `${v.name}: ${v.message}`;
+  if (typeof v === 'string') {
+    return v.length > MAX_INLINE ? `${v.slice(0, MAX_INLINE)}…(${v.length})` : v;
+  }
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (typeof v === 'function') return `ƒ${v.name || 'anonymous'}`;
+  if (depth >= 3) return brief(v);
+  try {
+    if (Array.isArray(v)) {
+      if (v.length === 0) return '[]';
+      if (v.length > MAX_ITEMS) return `[Array(${v.length}) 首=${fmt(v[0], depth + 1)}]`;
+      return '[' + v.map((x) => fmt(x, depth + 1)).join(', ') + ']';
+    }
+    const keys = Object.keys(v);
+    if (keys.length === 0) return '{}';
+    const parts = [];
+    let truncated = false;
+    for (const k of keys) {
+      if (parts.length >= MAX_KEYS) {
+        truncated = true;
+        break;
+      }
+      const val = v[k];
+      if (BULKY_KEYS.has(k) && (Array.isArray(val) || (val && typeof val === 'object'))) {
+        parts.push(`${k}:«${brief(val)} 已脱敏»`);
+      } else {
+        parts.push(`${k}:${fmt(val, depth + 1)}`);
+      }
+    }
+    const tail = truncated ? ` …(+${keys.length - parts.length})` : '';
+    return `{${parts.join(', ')}${tail}}`;
+  } catch {
+    return String(v);
+  }
+}
+
+// ——————————————————————————————————————————————
+// 框线
+// ——————————————————————————————————————————————
+const COLOR_OF = { info: 'blue', ok: 'green', warn: 'yellow', error: 'red' };
+const TAG_OF = { info: 'INFO', ok: 'OK  ', warn: 'WARN', error: 'ERR ' };
+
+function padLine(content, width, color) {
+  const cw = dispWidth(stripAnsi(content));
+  const pad = Math.max(0, width - cw);
+  return paint(color, '│ ') + content + ' '.repeat(pad) + paint(color, ' │');
+}
+
+/** 生成一个对齐的美化框（标题 + 多行内容） */
+export function box({ title = '', lines = [], level = 'info' }) {
+  const color = COLOR_OF[level] || 'blue';
+  const rows = [];
+  if (title) rows.push(title);
+  for (const l of lines) rows.push(l);
+  let width = 0;
+  for (const r of rows) width = Math.max(width, dispWidth(stripAnsi(r)));
+  width = Math.max(width, 24);
+  const top = paint(color, '┌' + '─'.repeat(width + 2) + '┐');
+  const mid = paint(color, '├' + '─'.repeat(width + 2) + '┤');
+  const bot = paint(color, '└' + '─'.repeat(width + 2) + '┘');
+  const out = [top];
+  if (title) out.push(padLine(paintBold(color, title), width, color));
+  if (title && lines.length) out.push(mid);
+  for (const l of lines) out.push(padLine(l, width, color));
+  out.push(bot);
+  return out.join('\n');
+}
+
+/** 分隔线（可选标签，便于在长日志中分段） */
+export function rule(label = '', level = 'info') {
+  const color = COLOR_OF[level] || 'blue';
+  const total = 56;
+  if (!label) return paint(color, '─'.repeat(total));
+  const left = `─ ${label} `;
+  const right = '─'.repeat(Math.max(2, total - dispWidth(left)));
+  return paint(color, left + right);
+}
+
+// ——————————————————————————————————————————————
+// 主 API
+// ——————————————————————————————————————————————
+function stamp() {
+  // 本地时间 HH:MM:SS.mmm
+  const d = new Date();
+  const p = (n, w = 2) => String(n).padStart(w, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`;
+}
+
+function emit(level, msg, args) {
+  const color = COLOR_OF[level] || 'blue';
+  const head = `${paint('gray', stamp())} ${paintBold(color, TAG_OF[level] || 'INFO')}`;
+  const parts = [head, msg, ...args.map((a) => fmt(a))];
+  let extra = '';
+  if (level === 'error') {
+    const err = args.find((a) => a instanceof Error);
+    if (err && err.stack) {
+      const st = err.stack.split('\n').slice(1, 3).join('\n      ').trim();
+      if (st) extra = '\n      ' + paint('dim', st);
+    }
+  }
+  const stream = level === 'error' || level === 'warn' ? process.stderr : process.stdout;
+  stream.write(parts.join(' ') + extra + '\n');
+}
+
+/** 统一日志对象：log.info / ok / warn / error / box / rule */
+export const log = {
+  info: (msg, ...a) => emit('info', msg, a),
+  ok: (msg, ...a) => emit('ok', msg, a),
+  warn: (msg, ...a) => emit('warn', msg, a),
+  error: (msg, ...a) => emit('error', msg, a),
+  box: (opts) => {
+    process.stdout.write(box(opts) + '\n');
+  },
+  rule: (label, level = 'info') => {
+    const stream = level === 'error' || level === 'warn' ? process.stderr : process.stdout;
+    stream.write(rule(label, level) + '\n');
+  },
+};
+
+export default log;

package/dist/server-core/nodeModels.js

@@ -0,0 +1,52 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * 节点 Property 树模型暴露端点（Task #5）。
+ *
+ * - GET /__node-models/<id>  → ssrLoadModule toPreview 后返回该卡的「可序列化 Property
+ *   树模型森林」(buildModelView)，供 AI / skill / MCP 直接读取每个节点的可编辑字段结构，
+ *   无需解析原始 DSL + component-meta。
+ *
+ * 与 /__render-status 一致：复用 dev server 的 vite 实例做 ssrLoadModule（HMR 友好，
+ * 改 preview/runtime 免重启）；首次请求有编译冷启动属正常。
+ */
+
+/**
+ * 产出单卡模型森林。纯函数、无 HTTP，便于复用。
+ * @param {import('vite').ViteDevServer} viteServer 含 ssrLoadModule 的 vite 实例
+ * @param {string} id 卡片 id
+ * @param {string} dir 卡片目录（含 schema.json）
+ */
+export async function nodeModelsFor(viteServer, id, dir) {
+  const schema = JSON.parse(fs.readFileSync(path.join(dir, 'schema.json'), 'utf8'))
+  const { buildModelView } = await viteServer.ssrLoadModule('/runtime/toPreview.js')
+  const model = buildModelView(schema)
+  return { id, model }
+}
+
+export function createNodeModelsMiddleware({ root, viteServer }) {
+  return async function nodeModelsMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const m = pathname.match(/^\/__node-models\/([^/]+)$/)
+    if (!m) return next()
+    const id = decodeURIComponent(m[1])
+    const dir = path.join(root, 'src', 'cards', id)
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+      res.statusCode = 404
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'card not found', id }))
+    }
+    try {
+      const out = await nodeModelsFor(viteServer, id, dir)
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.setHeader('Cache-Control', 'no-store')
+      return res.end(JSON.stringify(out))
+    } catch (e) {
+      res.statusCode = 500
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(JSON.stringify({ error: 'node-models failed', id, message: String(e && e.message) }))
+    }
+  }
+}