scrum-skills 0.3.2 → 0.3.3

package/bin/scrum-skills.mjs

@@ -1,191 +1,204 @@
-#!/usr/bin/env node
-/**
- * scrum-skills CLI（零依赖，node >= 18）
- * 命令:
- *   scrum-skills init [dir] [--force]  初始化敏捷开发文件到目标文件夹（默认当前目录）
- *                                      拷贝 .agents/skills/、AGENTS.md、tools/validate.mjs，建 agile/ 三文件骨架
- *                                      已存在 AGENTS.md 时拒绝，--force 覆盖（备份为 AGENTS.md.bak）
- *   scrum-skills update [dir] [--dry-run]  更新已初始化项目里的 skill 文件（.agents/、AGENTS.md、tools/validate.mjs）
- *                                      只刷新框架文件，绝不碰 agile/ 数据
- *                                      除 AGENTS.md 外一律无条件整篇覆盖、不备份
- *                                      AGENTS.md 覆盖前备份为 <时间戳>.bak 并提示用 agent 合并
- *                                      内容相同的不动；--dry-run 只报告不写入
- *   scrum-skills serve [dir] [port]    启动可视化 server（默认当前目录，端口 4173）
- *   scrum-skills validate [dir]        校验敏捷数据（默认当前目录）
- */
-import { cpSync, mkdirSync, existsSync, writeFileSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve, dirname, basename } from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url));
-const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version;
-const HELP = `用法:
-  scrum-skills init [dir] [--force]      初始化敏捷开发文件到目标文件夹（默认当前目录）
-  scrum-skills update [dir] [--dry-run]  更新已初始化项目的 skill 框架文件（不碰 agile/ 数据）
-  scrum-skills serve [dir] [port]        启动可视化 server（默认当前目录，端口 4173）
-  scrum-skills validate [dir]            校验敏捷数据（默认当前目录）
-  scrum-skills help                      显示本帮助
-  scrum-skills -v / --version            显示版本号
-
-scsk 是 scrum-skills 的等价简写，如: scsk serve`;
-
-const [cmd, ...args] = process.argv.slice(2);
-const fail = msg => { console.error(`✘ ${msg}`); process.exit(1); };
-
-/**
- * 备份一个即将被覆盖的文件，返回备份路径。
- * 名字带时间戳：老做法固定叫 `*.bak`，第二次 update 就把上一次的备份顶掉了，
- * 而 AGENTS.md 几乎一定会被本地改过，备份互相覆盖等于没备份。
- */
-function backupFile(file) {
-  const d = new Date();
-  const pad = n => String(n).padStart(2, '0');
-  const stamp = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
-  let target = `${file}.${stamp}.bak`;
-  for (let i = 2; existsSync(target); i += 1) target = `${file}.${stamp}-${i}.bak`;
-  cpSync(file, target);
-  return target;
-}
-function init() {
-  const force = args.includes('--force');
-  const dir = resolve(args.find(a => !a.startsWith('--')) || process.cwd());
-  if (!existsSync(dir)) fail(`目录不存在: ${dir}`);
-
-  const agentsMd = join(dir, 'AGENTS.md');
-  if (existsSync(agentsMd) && !force)
-    fail(`目标目录已有 AGENTS.md。确认覆盖请加 --force（旧文件会先备份成 AGENTS.md.<时间戳>.bak）`);
-  const backed = existsSync(agentsMd) ? backupFile(agentsMd) : null;
-  if (backed) console.log(`· 已把现有 AGENTS.md 备份为 ${basename(backed)}`);
-
-  cpSync(join(PKG_ROOT, '.agents'), join(dir, '.agents'), { recursive: true, force: true });
-  writeFileSync(agentsMd, readFileSync(join(PKG_ROOT, 'templates/AGENTS.md'), 'utf8'));
-
-  mkdirSync(join(dir, 'tools'), { recursive: true });
-  cpSync(join(PKG_ROOT, 'tools/validate.mjs'), join(dir, 'tools/validate.mjs'));
-  // 交付说明的写入工具：纪律要求「写之前先看 git」，工具得跟着装过去
-  cpSync(join(PKG_ROOT, 'tools/last-change.mjs'), join(dir, 'tools/last-change.mjs'));
-
-  // 数据骨架：schema v3（已有文件不覆盖，避免踩坏真实数据）
-  mkdirSync(join(dir, 'agile'), { recursive: true });
-  const skeleton = {
-    'backlog.json': { schemaVersion: 3, epics: [], stories: [] },
-    'sprints.json': { schemaVersion: 3, sprints: [], milestones: [] },
-    'journal.json': { schemaVersion: 3, journals: [] },
-    // 测试资产：页面空状态也认这个文件，先给空壳，agent 收口时往里加用例
-    'tests.json': { schemaVersion: 3, suites: [], runs: [] },
-  };
-  const created = [];
-  for (const [name, body] of Object.entries(skeleton)) {
-    const p = join(dir, 'agile', name);
-    if (existsSync(p)) continue;
-    writeFileSync(p, JSON.stringify(body, null, 2) + '\n');
-    created.push(`agile/${name}`);
-  }
-
-  console.log(`✔ 已初始化到 ${dir}
-  - .agents/skills/      四个敏捷 skill（planning / sprint / tdd / report）
-  - AGENTS.md            agent 入口纪律文件${backed ? `（旧文件已备份为 ${basename(backed)}）` : ''}
-  - tools/validate.mjs   数据校验脚本
-  - agile/ 数据骨架${created.length ? `（新建 ${created.join('、')}）` : '（已存在，未覆盖）'}
-
-下一步:
-  1. 在目标项目里让 AI 读 AGENTS.md，用 scrum-planning 建第一个 story
-  2. 每次改动后运行: node tools/validate.mjs
-  3. 看板: 在目标项目目录下运行 scrum-skills serve，打开 http://localhost:4173`);
-}
-
-function walkFiles(dir, base = '') {
-  const out = [];
-  for (const name of readdirSync(dir)) {
-    const abs = join(dir, name);
-    const rel = base ? `${base}/${name}` : name;
-    if (statSync(abs).isDirectory()) out.push(...walkFiles(abs, rel));
-    else out.push({ abs, rel });
-  }
-  return out;
-}
-
-/** 收集要更新的框架文件：相对路径 → 源绝对路径 */
-function frameworkFiles() {
-  const out = [];
-  for (const f of walkFiles(join(PKG_ROOT, '.agents')))
-    out.push({ rel: `.agents/${f.rel}`, src: f.abs });
-  out.push({ rel: 'AGENTS.md', src: join(PKG_ROOT, 'templates/AGENTS.md') });
-  out.push({ rel: 'tools/validate.mjs', src: join(PKG_ROOT, 'tools/validate.mjs') });
-  out.push({ rel: 'tools/last-change.mjs', src: join(PKG_ROOT, 'tools/last-change.mjs') });
-  return out;
-}
-
-function update() {
-  const dryRun = args.includes('--dry-run');
-  const dir = resolve(args.find(a => !a.startsWith('--')) || process.cwd());
-  if (!existsSync(dir)) fail(`目录不存在: ${dir}`);
-  if (!existsSync(join(dir, '.agents')) && !existsSync(join(dir, 'AGENTS.md')))
-    fail(`${dir} 未初始化（找不到 .agents/ 与 AGENTS.md）。请先运行: scrum-skills init`);
-
-  const added = [], changed = [], same = [];
-  // 只有 AGENTS.md 是「会被本地改」的文件：覆盖前留备份，其余框架文件一律直覆盖
-  let agentsBackup = null;
-  for (const { rel, src } of frameworkFiles()) {
-    const dest = join(dir, rel);
-    const srcText = readFileSync(src, 'utf8');
-    if (!existsSync(dest)) { added.push(rel); if (!dryRun) {
-      mkdirSync(dirname(dest), { recursive: true });
-      writeFileSync(dest, srcText);
-    } continue; }
-    if (readFileSync(dest, 'utf8') === srcText) { same.push(rel); continue; }
-    changed.push(rel);
-    if (dryRun) continue;
-    // 备份只给 AGENTS.md：项目特有纪律都写在里面，整篇覆盖会直接抹掉
-    if (rel === 'AGENTS.md') agentsBackup = basename(backupFile(dest));
-    writeFileSync(dest, srcText);
-  }
-
-  const verb = dryRun ? '（dry-run，未写入）' : '';
-  const agentsChanged = changed.includes('AGENTS.md');
-  const tail = agentsBackup
-    ? `提示: 框架文件整篇覆盖，只有 AGENTS.md 留了备份。
-你在 AGENTS.md 里的本地改动都在这份备份里，让 agent 助手（CodeBuddy / Claude Code 等）合并回来即可，直接说：
-  「对比 AGENTS.md 与 ${agentsBackup}，把我的本地改动合并回来」
-确认合并无误后再删掉备份。其余框架文件（.agents/、tools/）没有备份，也不需要合并。`
-    : dryRun && agentsChanged
-      ? '提示: 正式执行时只有 AGENTS.md 会先备份再覆盖（→ AGENTS.md.<yyyyMMdd-HHmmss>.bak，可据它让 agent 合并本地改动），其余框架文件直接覆盖、不留备份。'
-      : changed.length
-        ? '其余框架文件（.agents/、tools/）为整篇覆盖、不留备份，无需合并；AGENTS.md 已是最新。'
-        : '已是最新，无需操作。';
-  console.log(`✔ skill 框架文件更新完成${verb} — ${dir}
-  - 新增 ${added.length} 个${added.length ? `: ${added.join(', ')}` : ''}
-  - 更新 ${changed.length} 个${changed.length ? `: ${changed.join(', ')}` : ''}
-  - 未变 ${same.length} 个
-  - agile/ 数据目录未做任何改动
-  - 备份策略: 只有 AGENTS.md 覆盖前备份${agentsBackup ? `（→ ${agentsBackup}）` : ''}，其余文件直接覆盖
-
-${tail}`);
-}
-
-function runTool(script, needPort) {
-  const positional = args.filter(a => !a.startsWith('--'));
-  const dir = resolve(positional[0] || process.cwd());
-  if (!existsSync(dir)) fail(`目录不存在: ${dir}`);
-  const port = needPort ? (positional[1] || '4173') : null;
-  const r = spawnSync(process.execPath,
-    [join(PKG_ROOT, 'tools', script), dir, ...(port ? [port] : [])],
-    { stdio: 'inherit' });
-  process.exit(r.status ?? 1);
-}
-
-switch (cmd) {
-  case 'init': init(); break;
-  case 'update': update(); break;
-  case 'serve': runTool('serve.mjs', true); break;
-  case 'validate': runTool('validate.mjs', false); break;
-  case 'help': case '-h': case '--help': case undefined:
-    console.log(HELP); break;
-  case '-v': case '--version': case 'version':
-    console.log(VERSION); break;
-  default:
-    console.error(`未知命令: ${cmd}\n`);
-    console.log(HELP);
-    process.exit(1);
-}
+#!/usr/bin/env node
+/**
+ * scrum-skills CLI（零依赖，node >= 18）
+ * 命令:
+ *   scrum-skills init [dir] [--force]  初始化敏捷开发文件到目标文件夹（默认当前目录）
+ *                                      拷贝 .agents/skills/、AGENTS.md、tools/validate.mjs，建 agile/ 三文件骨架
+ *                                      已存在 AGENTS.md 时拒绝，--force 覆盖（备份为 AGENTS.md.bak）
+ *   scrum-skills update [dir] [--dry-run]  更新已初始化项目里的 skill 文件（.agents/、AGENTS.md、tools/validate.mjs）
+ *                                      只刷新框架文件，绝不碰 agile/ 数据
+ *                                      除 AGENTS.md 外一律无条件整篇覆盖、不备份
+ *                                      AGENTS.md 覆盖前备份为 <时间戳>.bak 并提示用 agent 合并
+ *                                      内容相同的不动；--dry-run 只报告不写入
+ *   scrum-skills serve [dir] [port]    启动可视化 server（默认当前目录，端口 4173）
+ *   scrum-skills validate [dir]        校验敏捷数据（默认当前目录）
+ */
+import { cpSync, mkdirSync, existsSync, writeFileSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, dirname, basename } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version;
+const HELP = `用法:
+  scrum-skills init [dir] [--force]      初始化敏捷开发文件到目标文件夹（默认当前目录）
+  scrum-skills update [dir] [--dry-run]  更新已初始化项目的 skill 框架文件（不碰 agile/ 数据）
+  scrum-skills serve [dir] [port]        启动可视化 server（默认当前目录，端口 4173）
+  scrum-skills validate [dir]            校验敏捷数据（默认当前目录）
+  scrum-skills help                      显示本帮助
+  scrum-skills -v / --version            显示版本号
+
+scsk 是 scrum-skills 的等价简写，如: scsk serve`;
+
+const [cmd, ...args] = process.argv.slice(2);
+const fail = msg => { console.error(`✘ ${msg}`); process.exit(1); };
+
+/**
+ * 备份一个即将被覆盖的文件，返回备份路径。
+ * 名字带时间戳：老做法固定叫 `*.bak`，第二次 update 就把上一次的备份顶掉了，
+ * 而 AGENTS.md 几乎一定会被本地改过，备份互相覆盖等于没备份。
+ */
+function backupFile(file) {
+  const d = new Date();
+  const pad = n => String(n).padStart(2, '0');
+  const stamp = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  let target = `${file}.${stamp}.bak`;
+  for (let i = 2; existsSync(target); i += 1) target = `${file}.${stamp}-${i}.bak`;
+  cpSync(file, target);
+  return target;
+}
+function init() {
+  const force = args.includes('--force');
+  const dir = resolve(args.find(a => !a.startsWith('--')) || process.cwd());
+  if (!existsSync(dir)) fail(`目录不存在: ${dir}`);
+
+  const agentsMd = join(dir, 'AGENTS.md');
+  if (existsSync(agentsMd) && !force)
+    fail(`目标目录已有 AGENTS.md。确认覆盖请加 --force（旧文件会先备份成 AGENTS.md.<时间戳>.bak）`);
+  const backed = existsSync(agentsMd) ? backupFile(agentsMd) : null;
+  if (backed) console.log(`· 已把现有 AGENTS.md 备份为 ${basename(backed)}`);
+
+  cpSync(join(PKG_ROOT, '.agents'), join(dir, '.agents'), { recursive: true, force: true });
+  writeFileSync(agentsMd, readFileSync(join(PKG_ROOT, 'templates/AGENTS.md'), 'utf8'));
+
+  mkdirSync(join(dir, 'tools'), { recursive: true });
+  cpSync(join(PKG_ROOT, 'tools/validate.mjs'), join(dir, 'tools/validate.mjs'));
+  // 交付说明的写入工具：纪律要求「写之前先看 git」，工具得跟着装过去
+  cpSync(join(PKG_ROOT, 'tools/last-change.mjs'), join(dir, 'tools/last-change.mjs'));
+  // 架构图例：入库工具 + 出图质检（上游 self_check 的 Node 移植版，不带 Python）
+  cpSync(join(PKG_ROOT, 'tools/diagram.mjs'), join(dir, 'tools/diagram.mjs'));
+  cpSync(join(PKG_ROOT, 'tools/diagram-lint.mjs'), join(dir, 'tools/diagram-lint.mjs'));
+  // 老图导入摘要（顶替上游 drawio / mermaid / excalidraw 三个 Python 提取脚本）
+  cpSync(join(PKG_ROOT, 'tools/diagram-import.mjs'), join(dir, 'tools/diagram-import.mjs'));
+
+  // 数据骨架：schema v3（已有文件不覆盖，避免踩坏真实数据）
+  mkdirSync(join(dir, 'agile'), { recursive: true });
+  const skeleton = {
+    'backlog.json': { schemaVersion: 3, epics: [], stories: [] },
+    'sprints.json': { schemaVersion: 3, sprints: [], milestones: [] },
+    'journal.json': { schemaVersion: 3, journals: [] },
+    // 测试资产：页面空状态也认这个文件，先给空壳，agent 收口时往里加用例
+    'tests.json': { schemaVersion: 3, suites: [], runs: [] },
+    // 架构图例：索引与产物分开（产物在 agile/diagrams/，由 tools/diagram.mjs 登记）
+    'diagrams.json': { schemaVersion: 3, diagrams: [] },
+  };
+  const created = [];
+  for (const [name, body] of Object.entries(skeleton)) {
+    const p = join(dir, 'agile', name);
+    if (existsSync(p)) continue;
+    writeFileSync(p, JSON.stringify(body, null, 2) + '\n');
+    created.push(`agile/${name}`);
+  }
+
+  console.log(`✔ 已初始化到 ${dir}
+  - .agents/skills/      四个敏捷 skill（planning / sprint / tdd / report）
+                        + 内置 diagram-design（画架构图/时序图/ER 图，无需另装、不依赖 Python）
+  - AGENTS.md            agent 入口纪律文件${backed ? `（旧文件已备份为 ${basename(backed)}）` : ''}
+  - tools/validate.mjs   数据校验脚本
+  - tools/diagram.mjs    架构图例入库（质检 → 落盘 → 建索引 → 校验回滚）
+  - tools/diagram-import.mjs  老图导入摘要（mermaid / drawio / excalidraw）
+  - agile/ 数据骨架${created.length ? `（新建 ${created.join('、')}）` : '（已存在，未覆盖）'}
+
+下一步:
+  1. 在目标项目里让 AI 读 AGENTS.md，用 scrum-planning 建第一个 story
+  2. 每次改动后运行: node tools/validate.mjs
+  3. 看板: 在目标项目目录下运行 scrum-skills serve，打开 http://localhost:4173`);
+}
+
+function walkFiles(dir, base = '') {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const abs = join(dir, name);
+    const rel = base ? `${base}/${name}` : name;
+    if (statSync(abs).isDirectory()) out.push(...walkFiles(abs, rel));
+    else out.push({ abs, rel });
+  }
+  return out;
+}
+
+/** 收集要更新的框架文件：相对路径 → 源绝对路径 */
+function frameworkFiles() {
+  const out = [];
+  for (const f of walkFiles(join(PKG_ROOT, '.agents')))
+    out.push({ rel: `.agents/${f.rel}`, src: f.abs });
+  out.push({ rel: 'AGENTS.md', src: join(PKG_ROOT, 'templates/AGENTS.md') });
+  out.push({ rel: 'tools/validate.mjs', src: join(PKG_ROOT, 'tools/validate.mjs') });
+  out.push({ rel: 'tools/last-change.mjs', src: join(PKG_ROOT, 'tools/last-change.mjs') });
+  out.push({ rel: 'tools/diagram.mjs', src: join(PKG_ROOT, 'tools/diagram.mjs') });
+  out.push({ rel: 'tools/diagram-lint.mjs', src: join(PKG_ROOT, 'tools/diagram-lint.mjs') });
+  out.push({ rel: 'tools/diagram-import.mjs', src: join(PKG_ROOT, 'tools/diagram-import.mjs') });
+  return out;
+}
+
+function update() {
+  const dryRun = args.includes('--dry-run');
+  const dir = resolve(args.find(a => !a.startsWith('--')) || process.cwd());
+  if (!existsSync(dir)) fail(`目录不存在: ${dir}`);
+  if (!existsSync(join(dir, '.agents')) && !existsSync(join(dir, 'AGENTS.md')))
+    fail(`${dir} 未初始化（找不到 .agents/ 与 AGENTS.md）。请先运行: scrum-skills init`);
+
+  const added = [], changed = [], same = [];
+  // 只有 AGENTS.md 是「会被本地改」的文件：覆盖前留备份，其余框架文件一律直覆盖
+  let agentsBackup = null;
+  for (const { rel, src } of frameworkFiles()) {
+    const dest = join(dir, rel);
+    const srcText = readFileSync(src, 'utf8');
+    if (!existsSync(dest)) { added.push(rel); if (!dryRun) {
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, srcText);
+    } continue; }
+    if (readFileSync(dest, 'utf8') === srcText) { same.push(rel); continue; }
+    changed.push(rel);
+    if (dryRun) continue;
+    // 备份只给 AGENTS.md：项目特有纪律都写在里面，整篇覆盖会直接抹掉
+    if (rel === 'AGENTS.md') agentsBackup = basename(backupFile(dest));
+    writeFileSync(dest, srcText);
+  }
+
+  const verb = dryRun ? '（dry-run，未写入）' : '';
+  const agentsChanged = changed.includes('AGENTS.md');
+  const tail = agentsBackup
+    ? `提示: 框架文件整篇覆盖，只有 AGENTS.md 留了备份。
+你在 AGENTS.md 里的本地改动都在这份备份里，让 agent 助手（CodeBuddy / Claude Code 等）合并回来即可，直接说：
+  「对比 AGENTS.md 与 ${agentsBackup}，把我的本地改动合并回来」
+确认合并无误后再删掉备份。其余框架文件（.agents/、tools/）没有备份，也不需要合并。`
+    : dryRun && agentsChanged
+      ? '提示: 正式执行时只有 AGENTS.md 会先备份再覆盖（→ AGENTS.md.<yyyyMMdd-HHmmss>.bak，可据它让 agent 合并本地改动），其余框架文件直接覆盖、不留备份。'
+      : changed.length
+        ? '其余框架文件（.agents/、tools/）为整篇覆盖、不留备份，无需合并；AGENTS.md 已是最新。'
+        : '已是最新，无需操作。';
+  console.log(`✔ skill 框架文件更新完成${verb} — ${dir}
+  - 新增 ${added.length} 个${added.length ? `: ${added.join(', ')}` : ''}
+  - 更新 ${changed.length} 个${changed.length ? `: ${changed.join(', ')}` : ''}
+  - 未变 ${same.length} 个
+  - agile/ 数据目录未做任何改动
+  - 备份策略: 只有 AGENTS.md 覆盖前备份${agentsBackup ? `（→ ${agentsBackup}）` : ''}，其余文件直接覆盖
+
+${tail}`);
+}
+
+function runTool(script, needPort) {
+  const positional = args.filter(a => !a.startsWith('--'));
+  const dir = resolve(positional[0] || process.cwd());
+  if (!existsSync(dir)) fail(`目录不存在: ${dir}`);
+  const port = needPort ? (positional[1] || '4173') : null;
+  const r = spawnSync(process.execPath,
+    [join(PKG_ROOT, 'tools', script), dir, ...(port ? [port] : [])],
+    { stdio: 'inherit' });
+  process.exit(r.status ?? 1);
+}
+
+switch (cmd) {
+  case 'init': init(); break;
+  case 'update': update(); break;
+  case 'serve': runTool('serve.mjs', true); break;
+  case 'validate': runTool('validate.mjs', false); break;
+  case 'help': case '-h': case '--help': case undefined:
+    console.log(HELP); break;
+  case '-v': case '--version': case 'version':
+    console.log(VERSION); break;
+  default:
+    console.error(`未知命令: ${cmd}\n`);
+    console.log(HELP);
+    process.exit(1);
+}