cardbuddy 0.11.0 → 0.12.1

package/dist/init.js

@@ -0,0 +1,425 @@
+/**
+ * `cardbuddy init` —— 生成「立刻能开发调试」的卡片工程最小实例。
+ *
+ * 产出（全部增量、幂等；已存在的文件一律保留，除非 --force）：
+ *   src/cards/                卡片目录骨架（后端与编辑器的约定落点）
+ *   src/cards/helloCard/      示例卡（schema.json + data.json，构建期已过校验）—— 起服务即有卡可看
+ *   skills/                   随包发布的技能库全量释放：/__validate、/__sync、/__save、切图上传
+ *                             与 AI 的 skill_read / skill_exec 都按「项目根 skills/ 优先」解析，
+ *                             释放后既跑得快也写得了（FinMall 凭据落在项目内，不进 node_modules）
+ *   tools/link-skills.mjs     把 skills/ 链到 Codex / Claude / WorkBuddy 等 AI 工具的项目级技能目录
+ *   .env.cb                   共享配置模板（端口 / 远端基址 / AI 网关占位；密钥写 .env.cb.local）
+ *   package.json              声明 cardbuddy 依赖与 dev / preview / link:skills 脚本
+ *   .gitignore                私密层与产物不入库
+ *   README.md                 上手说明
+ *
+ * 与仓库的 `npm run gen:demo` 的关系：本命令即其替代品，且更强 —— 它随 npm 包发布，
+ * 消费者 `npx cardbuddy init` 即可，无需检出 dsl-card 仓库，版本也天然与所装 cardbuddy 一致。
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import chalk from 'chalk'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/** 示例卡（与 build.mjs 的 SAMPLE_CARD 一致；构建期由 scaffold_card.mjs 生成并过校验） */
+const SAMPLE_CARD_ID = 'helloCard'
+
+/** 模板 .env.cb：只放非机密的共享配置，密钥类一律注释占位（个人覆盖写 .env.cb.local） */
+const ENV_TEMPLATE = `# CardBuddy 本地开发服务配置（共享层，可入库）
+# 个人机密（AI_API_KEY / FinMall 凭据等）请写 .env.cb.local，它覆盖本文件且不入库。
+
+# cardbuddy 本地服务端口（单一真值；编辑器前端也读它）
+FINMALL_CARD_PORT=8787
+
+# FinMall 远端站点基址（资源代理回源 / 同步 / 保存 / 切图上传用）
+FINMALL_BASE_URL=https://uat-pkg.finmall.com
+FINMALL_APP_ID=100001
+FINMALL_WORKSPACE_ID=dev
+# 远端编辑器 Web 访问别名（站点下挂载路径）
+FINMALL_EDITOR_PATH=/ubomp-h5-sub
+# Chrome 远程调试端口（复用已登录的 FinMall 会话）
+FINMALL_CDP_PORT=9222
+
+# ---- AI 开发助手（自带网关，OpenAI 兼容 /chat/completions）----
+# AI_BASE_URL=https://your-gateway/openai/v1
+# AI_API_KEY=            # 建议写在 .env.cb.local
+# AI_MODEL=
+# 免确认执行策略：none=逐次审批 / skill=只免技能脚本 / all=技能脚本+本地命令都免（默认）
+# AI_AUTO_APPROVE=all
+# 本地命令执行（默认开；写 0 关闭 shell_exec 注册）
+# AI_ALLOW_SHELL=1
+# 单次输出上限：留空=自动（被 400 拒绝时自动减半重试）
+# AI_MAX_TOKENS=
+`
+
+/** .gitignore 应包含的条目（缺哪条补哪条，不重写既有内容） */
+const GITIGNORE_ENTRIES = [
+  'node_modules/',
+  '.env.cb.local',
+  '.env.local',
+  '.env.finmall.local',
+  '.cache/',
+  '.local/',
+  'skills/*/.local/',
+  '.DS_Store',
+]
+
+/** 复制排除名单：私密凭据、依赖与缓存一律不释放到用户项目 */
+const SKIP_DIRS = new Set(['node_modules', '__pycache__', '.git', '.local', '.cache', '.history'])
+const SKIP_FILES = new Set(['.DS_Store', 'Thumbs.db'])
+
+function isSkipped(name, isDir) {
+  if (isDir) return SKIP_DIRS.has(name)
+  return SKIP_FILES.has(name) || name.endsWith('.pyc')
+}
+
+/**
+ * 递归复制目录，跳过已存在的文件（force 时覆盖）。
+ * @returns {{ copied: number, skipped: number, bytes: number }}
+ */
+function copyTree(src, dest, { force = false, dryRun = false }) {
+  const stat = { copied: 0, skipped: 0, bytes: 0 }
+  const walk = (s, d) => {
+    if (!dryRun) fs.mkdirSync(d, { recursive: true })
+    for (const entry of fs.readdirSync(s, { withFileTypes: true })) {
+      if (isSkipped(entry.name, entry.isDirectory())) continue
+      const sp = path.join(s, entry.name)
+      const dp = path.join(d, entry.name)
+      if (entry.isDirectory()) {
+        walk(sp, dp)
+      } else if (entry.isFile()) {
+        if (fs.existsSync(dp) && !force) {
+          stat.skipped++
+          continue
+        }
+        const size = fs.statSync(sp).size
+        if (!dryRun) {
+          fs.mkdirSync(path.dirname(dp), { recursive: true })
+          fs.copyFileSync(sp, dp)
+        }
+        stat.copied++
+        stat.bytes += size
+      }
+    }
+  }
+  walk(src, dest)
+  return stat
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  return `${(n / 1024 / 1024).toFixed(2)} MB`
+}
+
+/** 写文件（存在则跳过，force 覆盖）；返回 'written' | 'skipped' | 'planned' */
+function writeFileSafe(file, content, { force = false, dryRun = false }) {
+  if (fs.existsSync(file) && !force) return 'skipped'
+  if (dryRun) return 'planned'
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, content, 'utf8')
+  return 'written'
+}
+
+/** 本包版本：用于生成工程的 devDependencies 范围（发布态/源码态都是 <pkg>/package.json） */
+function ownVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8')).version || '*'
+  } catch {
+    return '*'
+  }
+}
+
+function projectReadme(projectName, version) {
+  return `# ${projectName}
+
+CardBuddy 卡片开发最小实例，由 \`cardbuddy init\` 生成。
+本地开发服务由 [\`cardbuddy\`](https://www.npmjs.com/package/cardbuddy) 提供（本工程已声明依赖 \`^${version}\`）。
+
+## 立刻开始
+
+\`\`\`bash
+npm install
+npm run preview      # 起本地服务(8787) + 托管内置编辑器前端 + 自动开浏览器
+\`\`\`
+
+浏览器打开后即能看到示例卡 \`helloCard\`（\`src/cards/helloCard/\`）——改它的
+\`schema.json\` 或 \`data.json\`，编辑器会热更新。
+
+只想跑后端服务、用线上编辑器时：
+
+\`\`\`bash
+npm run dev          # 等价于 npx cardbuddy
+\`\`\`
+
+然后在线上编辑器 **设置 → 本地开发服务** 里打开开关、填 \`http://127.0.0.1:8787\`
+（须与 \`.env.cb\` 的 \`FINMALL_CARD_PORT\` 一致）。
+
+## 目录约定
+
+\`\`\`
+src/cards/<cardId>/
+  ├── schema.json     卡片结构定义（唯一真值）
+  ├── data.json       运行时数据（可由 schema 的 dictionary 派生）
+  └── <cardId>.png    列表缩略图（可选）
+skills/               AI 协作技能库（校验 / 同步 / 建卡管线脚本 + 工作流文档）
+.env.cb               共享配置（端口、远端基址、AI 网关占位）
+.env.cb.local         个人机密覆盖层（AI_API_KEY 等；已被 .gitignore 忽略）
+\`\`\`
+
+## 常用本地端点（\`http://127.0.0.1:8787\`）
+
+| 端点 | 用途 |
+| --- | --- |
+| \`GET /__cards\` | 卡片列表 |
+| \`GET /__card/:id\` | 读单卡 schema/data |
+| \`POST /__card/:id\` | 写卡片（带历史快照） |
+| \`GET /__validate/:id\` | 契约校验（跑 \`skills/\` 里的 Python 校验器） |
+| \`GET /__render-status/:id\` | SSR 渲染自检（绑定错误 / 组件分布 / 运行时异常） |
+| \`POST /__ai/chat\` | AI 开发助手（需在 \`.env.cb.local\` 配 AI_BASE_URL / AI_API_KEY / AI_MODEL） |
+
+## 让 AI 工具看到 skills/
+
+\`\`\`bash
+npm run link:skills   # 交互式选择 Codex / Claude / WorkBuddy 等，建立项目级技能软链
+\`\`\`
+
+## FinMall 远端能力（可选）
+
+同步 / 保存 / 切图上传需要已登录的 FinMall 会话与 \`playwright\`
+（cardbuddy 的 optionalDependency，装包时默认会装）。凭据只落在本机
+\`skills/finmall-session-navigator/.local/credentials.json\`，已被 .gitignore 忽略。
+`
+}
+
+function projectPackageJson(projectName, version) {
+  return (
+    JSON.stringify(
+      {
+        name: projectName,
+        version: '0.1.0',
+        private: true,
+        description: 'CardBuddy 卡片开发最小实例：本地服务 + 内置编辑器预览 + AI 协作技能库。',
+        scripts: {
+          dev: 'cardbuddy',
+          start: 'cardbuddy',
+          preview: 'cardbuddy --preview',
+          'link:skills': 'node tools/link-skills.mjs',
+        },
+        devDependencies: {
+          cardbuddy: `^${version}`,
+        },
+      },
+      null,
+      2
+    ) + '\n'
+  )
+}
+
+/**
+ * 技能库源：发布态为包内快照 dist/vendored/skills；源码态回退仓库 skills/。
+ * @param {ReturnType<import('./config.js').loadConfig>} config
+ * @returns {string|null}
+ */
+export function resolveSkillsSource(config) {
+  const candidates = [
+    config.vendoredSkillsDir,
+    // 源码态（node packages/cardbuddy/src/cli.js）：上三级即仓库根 → <repo>/skills
+    path.resolve(__dirname, '..', '..', '..', 'skills'),
+  ]
+  for (const dir of candidates) {
+    if (dir && fs.existsSync(path.join(dir, 'dsl-card-generator'))) return dir
+  }
+  return null
+}
+
+/**
+ * 示例卡源目录：优先包内 templates（构建期生成 + 过校验）；源码态没有 dist 时，
+ * 现场用技能库的 scaffold_card.mjs 生成一份到临时目录（同一套产物，零漂移）。
+ * @returns {string|null} 含 schema.json / data.json 的目录
+ */
+function resolveSampleCardSource(config, skillsSrc) {
+  const candidates = [
+    path.join(config.vendorRoot || '', 'templates', SAMPLE_CARD_ID),
+    path.resolve(__dirname, 'vendored', 'templates', SAMPLE_CARD_ID),
+  ]
+  for (const dir of candidates) {
+    if (dir && fs.existsSync(path.join(dir, 'schema.json'))) return dir
+  }
+  if (!skillsSrc) return null
+  const scaffold = path.join(skillsSrc, 'dsl-card-generator', 'scripts', 'scaffold_card.mjs')
+  if (!fs.existsSync(scaffold)) return null
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cardbuddy-sample-'))
+  try {
+    execFileSync(
+      process.execPath,
+      [scaffold, '--intent', 'detail', '--id', SAMPLE_CARD_ID, '--name', '示例卡片', '--out', tmp, '--force'],
+      { stdio: 'pipe' }
+    )
+  } catch {
+    return null
+  }
+  const made = path.join(tmp, SAMPLE_CARD_ID)
+  return fs.existsSync(path.join(made, 'schema.json')) ? made : null
+}
+
+/** link-skills.mjs 源：包内快照 tools/ 优先，源码态回退仓库 tools/ */
+function resolveLinkSkillsSource(config) {
+  const candidates = [
+    path.join(config.vendorRoot || '', 'tools', 'link-skills.mjs'),
+    path.resolve(__dirname, 'vendored', 'tools', 'link-skills.mjs'),
+    path.resolve(__dirname, '..', '..', '..', 'tools', 'link-skills.mjs'),
+  ]
+  for (const f of candidates) if (f && fs.existsSync(f)) return f
+  return null
+}
+
+/**
+ * 执行初始化。
+ * @param {object} opts
+ * @param {string} [opts.targetDir='.'] 目标工程根
+ * @param {boolean} [opts.force] 覆盖已存在文件
+ * @param {boolean} [opts.dryRun] 只报告不落盘
+ * @param {boolean} [opts.skipSkills] 不释放技能库
+ * @param {boolean} [opts.skipSample] 不生成示例卡
+ * @param {ReturnType<import('./config.js').loadConfig>} opts.config
+ * @param {(msg: string) => void} [opts.log]
+ * @returns {Promise<number>} 进程退出码
+ */
+export async function runInit({
+  targetDir = '.',
+  force = false,
+  dryRun = false,
+  skipSkills = false,
+  skipSample = false,
+  config,
+  log = (m) => console.log(m),
+}) {
+  const target = path.resolve(targetDir)
+  const tag = chalk.magenta('▌ ') + chalk.magenta.bold('cardbuddy init') + ' '
+  const say = (msg) => log(tag + msg)
+  const ok = (msg) => say(chalk.green(`• ${msg}`))
+  const dim = (msg) => say(chalk.dim(`• ${msg}`))
+  const opts = { force, dryRun }
+
+  if (dryRun) say(chalk.yellow('（dry-run：只报告将要做的事，不落盘）'))
+  if (!fs.existsSync(target)) {
+    if (!dryRun) fs.mkdirSync(target, { recursive: true })
+    say(`${dryRun ? '将创建' : '已创建'}目录 ${target}`)
+  } else if (!fs.statSync(target).isDirectory()) {
+    log(chalk.red(`✖ 目标不是目录：${target}`))
+    return 1
+  }
+  say(`目标工程根：${target}`)
+
+  const projectName = path.basename(target) || 'cardbuddy-project'
+
+  // 1) 卡片目录骨架
+  const cardsDir = path.join(target, 'src', 'cards')
+  const cardsExisted = fs.existsSync(cardsDir)
+  if (!dryRun) fs.mkdirSync(cardsDir, { recursive: true })
+  writeFileSafe(path.join(cardsDir, '.gitkeep'), '', { force: false, dryRun })
+  cardsExisted ? dim('src/cards/ 已存在（跳过）') : ok('已建 src/cards/')
+
+  // 2) 释放技能库
+  const skillsSrc = skipSkills ? null : resolveSkillsSource(config)
+  if (skipSkills) {
+    dim('跳过技能库释放（--no-skills）')
+  } else if (!skillsSrc) {
+    log(chalk.red('✖ 找不到可释放的技能库：包内 dist/vendored/skills 缺失（包安装不完整？）'))
+    return 1
+  } else {
+    const dest = path.join(target, 'skills')
+    if (path.resolve(skillsSrc) === path.resolve(dest)) {
+      dim(`技能库源与目标同路径，跳过释放（${skillsSrc}）`)
+    } else {
+      const stat = copyTree(skillsSrc, dest, opts)
+      const names = fs
+        .readdirSync(skillsSrc, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !isSkipped(e.name, true))
+        .map((e) => e.name)
+      ok(
+        `${dryRun ? '将释放' : '已释放'}技能库 ${names.length} 个 skill → skills/ ` +
+          chalk.dim(`（新增 ${stat.copied} 文件 / ${fmtBytes(stat.bytes)}，保留已存在 ${stat.skipped} 个${force ? '，--force 覆盖' : ''}）`)
+      )
+      if (names.length) say(chalk.dim(`  ${names.join('、')}`))
+    }
+  }
+
+  // 3) 示例卡（起服务即有卡可看，不必先会写 schema）
+  if (skipSample) {
+    dim('跳过示例卡（--no-sample）')
+  } else {
+    const sampleSrc = resolveSampleCardSource(config, skillsSrc || resolveSkillsSource(config))
+    if (!sampleSrc) {
+      say(chalk.yellow('• 未能生成示例卡（技能库缺失？）—— 可稍后手动放 src/cards/<id>/schema.json'))
+    } else {
+      const dest = path.join(cardsDir, SAMPLE_CARD_ID)
+      if (fs.existsSync(dest) && !force) {
+        dim(`示例卡 src/cards/${SAMPLE_CARD_ID}/ 已存在（跳过，--force 可覆盖）`)
+      } else {
+        const stat = copyTree(sampleSrc, dest, { force: true, dryRun })
+        ok(`${dryRun ? '将生成' : '已生成'}示例卡 src/cards/${SAMPLE_CARD_ID}/（${stat.copied} 文件，已过 schema 校验）`)
+      }
+    }
+  }
+
+  // 4) .env.cb 模板
+  const envState = writeFileSafe(path.join(target, '.env.cb'), ENV_TEMPLATE, opts)
+  envState === 'skipped'
+    ? dim('.env.cb 已存在（跳过，--force 可覆盖）')
+    : ok(`${dryRun ? '将生成' : '已生成'} .env.cb 模板（端口 / 远端基址 / AI 网关占位）`)
+  if (!fs.existsSync(path.join(target, '.env.cb.local'))) {
+    dim('私密配置请另建 .env.cb.local（AI_API_KEY 等；已被 .gitignore 忽略）')
+  }
+
+  // 5) package.json（声明 cardbuddy 依赖 + 启动脚本）
+  const version = ownVersion()
+  const pkgState = writeFileSafe(path.join(target, 'package.json'), projectPackageJson(projectName, version), opts)
+  pkgState === 'skipped'
+    ? dim('package.json 已存在（跳过，--force 可覆盖）')
+    : ok(`${dryRun ? '将生成' : '已生成'} package.json（cardbuddy ^${version} + dev / preview / link:skills 脚本）`)
+
+  // 6) tools/link-skills.mjs（把 skills/ 链给 AI 工具）
+  const linkSrc = resolveLinkSkillsSource(config)
+  if (linkSrc) {
+    const dest = path.join(target, 'tools', 'link-skills.mjs')
+    const st = writeFileSafe(dest, fs.readFileSync(linkSrc, 'utf8'), opts)
+    st === 'skipped' ? dim('tools/link-skills.mjs 已存在（跳过）') : ok(`${dryRun ? '将释放' : '已释放'} tools/link-skills.mjs（npm run link:skills 用）`)
+  }
+
+  // 7) .gitignore 补齐（只追加缺失条目，不重写既有内容）
+  const giFile = path.join(target, '.gitignore')
+  const existing = fs.existsSync(giFile) ? fs.readFileSync(giFile, 'utf8') : ''
+  const existingLines = new Set(existing.split('\n').map((l) => l.trim()))
+  const missing = GITIGNORE_ENTRIES.filter((e) => !existingLines.has(e))
+  if (missing.length) {
+    const block =
+      (existing && !existing.endsWith('\n') ? '\n' : '') +
+      (existing ? '' : '# CardBuddy\n') +
+      missing.join('\n') +
+      '\n'
+    if (!dryRun) fs.appendFileSync(giFile, block, 'utf8')
+    ok(`${dryRun ? '将补' : '已补'} .gitignore：${missing.join('、')}`)
+  } else {
+    dim('.gitignore 无需补充')
+  }
+
+  // 8) README.md
+  const readmeState = writeFileSafe(path.join(target, 'README.md'), projectReadme(projectName, version), opts)
+  readmeState === 'skipped' ? dim('README.md 已存在（跳过）') : ok(`${dryRun ? '将生成' : '已生成'} README.md（上手说明）`)
+
+  // 收尾
+  const hasNodeModules = fs.existsSync(path.join(target, 'node_modules', 'cardbuddy'))
+  log('')
+  log(tag + chalk.green(dryRun ? 'dry-run 完成（未落盘）' : '初始化完成'))
+  log(tag + chalk.dim('下一步：'))
+  log(tag + chalk.dim(`  1) cd ${target}`))
+  log(tag + chalk.dim(`  2) ${hasNodeModules ? 'npm run preview' : 'npm install && npm run preview'}   # 本地服务 + 内置编辑器，自动开浏览器`))
+  log(tag + chalk.dim('  3) 改 src/cards/helloCard/schema.json 看热更新；AI 助手密钥写 .env.cb.local'))
+  return 0
+}