cc-devflow 4.2.0 → 4.3.0

package/.claude/scripts/delta-parser.ts

@@ -474,6 +474,95 @@ function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+// ============================================================================
+// Version Bump
+// ============================================================================
+
+function bumpVersion(currentVersion: string, deltaBlocks: DeltaBlock[]): string {
+  const [major, minor, patch] = currentVersion.split('.').map(Number);
+
+  // REMOVED → MAJOR +1 (破坏性变更)
+  if (deltaBlocks.some(b => b.type === 'REMOVED')) {
+    return `${major + 1}.0.0`;
+  }
+
+  // ADDED → MINOR +1 (新功能)
+  if (deltaBlocks.some(b => b.type === 'ADDED')) {
+    return `${major}.${minor + 1}.0`;
+  }
+
+  // MODIFIED/RENAMED → PATCH +1 (修复/改进)
+  return `${major}.${minor}.${patch + 1}`;
+}
+
+// ============================================================================
+// Merge to Project-Level spec.md
+// ============================================================================
+
+export function mergeDeltaToMainSpec(
+  mainSpecPath: string,
+  deltaSpecPath: string
+): { success: boolean; newVersion: string; error?: string } {
+  const fs = require('fs');
+
+  try {
+    // 读取文件
+    const mainSpecContent = fs.readFileSync(mainSpecPath, 'utf-8');
+    const deltaSpecContent = fs.readFileSync(deltaSpecPath, 'utf-8');
+
+    // 解析 frontmatter
+    const { metadata: mainMeta, body: mainBody } = extractYamlFrontmatter(mainSpecContent);
+    const { metadata: deltaMeta } = extractYamlFrontmatter(deltaSpecContent);
+
+    // 验证模块匹配
+    if (mainMeta.module !== deltaMeta.module) {
+      return {
+        success: false,
+        newVersion: mainMeta.version || '1.0.0',
+        error: `Module mismatch: main=${mainMeta.module}, delta=${deltaMeta.module}`
+      };
+    }
+
+    // 解析 Delta blocks
+    const deltaBlocks = parseDelta(deltaSpecContent);
+
+    if (deltaBlocks.length === 0) {
+      return {
+        success: false,
+        newVersion: mainMeta.version || '1.0.0',
+        error: 'No delta blocks found'
+      };
+    }
+
+    // 应用 Delta
+    const result = applyDelta(mainSpecContent, deltaBlocks);
+
+    // 更新版本号和时间戳
+    const newVersion = bumpVersion(mainMeta.version || '1.0.0', deltaBlocks);
+    const updatedMeta = {
+      ...mainMeta,
+      version: newVersion,
+      updated_at: new Date().toISOString()
+    };
+
+    // 重新组装 frontmatter
+    const yamlLines = Object.entries(updatedMeta).map(([k, v]) => `${k}: "${v}"`);
+    const newContent = `---\n${yamlLines.join('\n')}\n---\n${result.split('---\n')[2] || result}`;
+
+    // 写回文件
+    fs.writeFileSync(mainSpecPath, newContent, 'utf-8');
+
+    return { success: true, newVersion };
+
+  } catch (error) {
+    return {
+      success: false,
+      newVersion: '',
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
 // ============================================================================
 // CLI Interface
 // ============================================================================
@@ -485,8 +574,9 @@ if (require.main === module) {
   if (args.length < 1) {
     console.error('Usage: delta-parser.ts <command> [args]');
     console.error('Commands:');
-    console.error('  parse <delta-file>           Parse delta file and output JSON');
-    console.error('  apply <prd-file> <delta-file> Apply delta to PRD and output result');
+    console.error('  parse <delta-file>              Parse delta file and output JSON');
+    console.error('  apply <prd-file> <delta-file>   Apply delta to PRD and output result');
+    console.error('  merge <main-spec> <delta-spec>  Merge delta to project-level spec.md');
     process.exit(1);
   }
 
@@ -520,6 +610,26 @@ if (require.main === module) {
       break;
     }
 
+    case 'merge': {
+      const mainSpecPath = args[1];
+      const deltaSpecPath = args[2];
+      if (!mainSpecPath || !deltaSpecPath) {
+        console.error('Error: main-spec and delta-spec required');
+        process.exit(1);
+      }
+
+      const result = mergeDeltaToMainSpec(mainSpecPath, deltaSpecPath);
+
+      if (result.success) {
+        console.log(`✅ Delta merged successfully`);
+        console.log(`📦 New version: ${result.newVersion}`);
+      } else {
+        console.error(`❌ Merge failed: ${result.error}`);
+        process.exit(1);
+      }
+      break;
+    }
+
     default:
       console.error(`Unknown command: ${command}`);
       process.exit(1);

package/.claude/scripts/export-openspec.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * [INPUT]: 依赖 CC-DevFlow spec.md 文件路径
+ * [OUTPUT]: 生成 OpenSpec 格式的 spec.md (纯 Requirements，无 CC-DevFlow 元数据)
+ * [POS]: OpenSpec 互操作层，被 /flow:export-openspec 命令调用
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 解析 CC-DevFlow spec.md 格式
+ */
+function parseDevFlowSpec(content) {
+  const lines = content.split('\n');
+  const result = {
+    moduleName: '',
+    purpose: '',
+    requirements: []
+  };
+
+  let inFrontmatter = false;
+  let currentSection = null;
+  let currentRequirement = null;
+  let currentScenario = null;
+  let buffer = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // 跳过 YAML frontmatter
+    if (line === '---') {
+      inFrontmatter = !inFrontmatter;
+      continue;
+    }
+    if (inFrontmatter) {
+      continue;
+    }
+
+    // # Module Name
+    if (line.startsWith('# ') && !result.moduleName) {
+      result.moduleName = line.substring(2).trim();
+      continue;
+    }
+
+    // ## Purpose
+    if (line.startsWith('## Purpose')) {
+      currentSection = 'purpose';
+      buffer = [];
+      continue;
+    }
+
+    // ## Requirements
+    if (line.startsWith('## Requirements')) {
+      if (currentSection === 'purpose') {
+        result.purpose = buffer.join('\n').trim();
+      }
+      currentSection = 'requirements';
+      buffer = [];
+      continue;
+    }
+
+    // ## Design (停止解析，OpenSpec 不需要)
+    if (line.startsWith('## Design') || line.startsWith('## Tasks') || line.startsWith('## Verification')) {
+      if (currentRequirement) {
+        result.requirements.push(currentRequirement);
+        currentRequirement = null;
+      }
+      break;
+    }
+
+    // ### Requirement: Name
+    if (line.startsWith('### Requirement:')) {
+      if (currentRequirement) {
+        result.requirements.push(currentRequirement);
+      }
+      currentRequirement = {
+        name: line.substring(16).trim(),
+        description: '',
+        scenarios: []
+      };
+      currentScenario = null;
+      buffer = [];
+      continue;
+    }
+
+    // #### Scenario: Case
+    if (line.startsWith('#### Scenario:')) {
+      if (currentRequirement && buffer.length > 0) {
+        currentRequirement.description = buffer.join('\n').trim();
+        buffer = [];
+      }
+      currentScenario = {
+        name: line.substring(14).trim(),
+        steps: []
+      };
+      continue;
+    }
+
+    // BDD steps
+    if (currentScenario && (line.startsWith('- GIVEN') || line.startsWith('- WHEN') || line.startsWith('- THEN') || line.startsWith('- AND'))) {
+      currentScenario.steps.push(line.substring(2).trim());
+      continue;
+    }
+
+    // 收集内容
+    if (currentSection === 'purpose' && line.trim()) {
+      buffer.push(line);
+    } else if (currentRequirement && !currentScenario && line.trim() && !line.startsWith('[NEEDS CLARIFICATION')) {
+      buffer.push(line);
+    }
+
+    // 场景结束
+    if (currentScenario && line.trim() === '' && currentScenario.steps.length > 0) {
+      currentRequirement.scenarios.push(currentScenario);
+      currentScenario = null;
+    }
+  }
+
+  // 处理最后的 requirement
+  if (currentRequirement) {
+    if (currentScenario && currentScenario.steps.length > 0) {
+      currentRequirement.scenarios.push(currentScenario);
+    }
+    if (buffer.length > 0) {
+      currentRequirement.description = buffer.join('\n').trim();
+    }
+    result.requirements.push(currentRequirement);
+  }
+
+  return result;
+}
+
+/**
+ * 转换为 OpenSpec 格式
+ */
+function convertToOpenSpec(devflowData) {
+  let output = `# ${devflowData.moduleName}
+
+## Purpose
+
+${devflowData.purpose}
+
+## Requirements
+
+`;
+
+  // 转换 Requirements
+  for (const req of devflowData.requirements) {
+    output += `### Requirement: ${req.name}\n`;
+
+    if (req.description) {
+      output += `${req.description}\n\n`;
+    }
+
+    // 转换 Scenarios
+    for (const scenario of req.scenarios) {
+      output += `#### Scenario: ${scenario.name}\n`;
+      for (const step of scenario.steps) {
+        output += `- ${step}\n`;
+      }
+      output += '\n';
+    }
+  }
+
+  return output;
+}
+
+/**
+ * 主函数
+ */
+function exportOpenSpec(devflowSpecPath, outputPath) {
+  // 读取 CC-DevFlow spec.md
+  if (!fs.existsSync(devflowSpecPath)) {
+    throw new Error(`DevFlow spec.md not found: ${devflowSpecPath}`);
+  }
+
+  const content = fs.readFileSync(devflowSpecPath, 'utf-8');
+
+  // 解析 CC-DevFlow spec
+  const devflowData = parseDevFlowSpec(content);
+
+  // 转换为 OpenSpec 格式
+  const openspecContent = convertToOpenSpec(devflowData);
+
+  // 写入输出文件
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  fs.writeFileSync(outputPath, openspecContent, 'utf-8');
+
+  return {
+    success: true,
+    outputPath,
+    requirementsCount: devflowData.requirements.length
+  };
+}
+
+// CLI 接口
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.error('Usage: export-openspec.js <devflow-spec-path> <output-path>');
+    process.exit(1);
+  }
+
+  const [devflowSpecPath, outputPath] = args;
+
+  try {
+    const result = exportOpenSpec(devflowSpecPath, outputPath);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error('Error:', error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { exportOpenSpec, parseDevFlowSpec, convertToOpenSpec };

package/.claude/scripts/import-openspec.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * [INPUT]: 依赖 OpenSpec spec.md 文件路径，依赖 REQ-ID
+ * [OUTPUT]: 生成 CC-DevFlow 格式的 spec.md，自动补充 TDD 任务
+ * [POS]: OpenSpec 互操作层，被 /flow:import-openspec 命令调用
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 解析 OpenSpec spec.md 格式
+ *
+ * OpenSpec 格式:
+ * # Module Name
+ * ## Purpose
+ * ## Requirements
+ * ### Requirement: Name
+ * #### Scenario: Case
+ * - GIVEN ...
+ * - WHEN ...
+ * - THEN ...
+ */
+function parseOpenSpecMarkdown(content) {
+  const lines = content.split('\n');
+  const result = {
+    moduleName: '',
+    purpose: '',
+    requirements: []
+  };
+
+  let currentSection = null;
+  let currentRequirement = null;
+  let currentScenario = null;
+  let buffer = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // # Module Name
+    if (line.startsWith('# ') && !result.moduleName) {
+      result.moduleName = line.substring(2).trim();
+      continue;
+    }
+
+    // ## Purpose
+    if (line.startsWith('## Purpose')) {
+      currentSection = 'purpose';
+      buffer = [];
+      continue;
+    }
+
+    // ## Requirements
+    if (line.startsWith('## Requirements')) {
+      if (currentSection === 'purpose') {
+        result.purpose = buffer.join('\n').trim();
+      }
+      currentSection = 'requirements';
+      buffer = [];
+      continue;
+    }
+
+    // ### Requirement: Name
+    if (line.startsWith('### Requirement:')) {
+      if (currentRequirement) {
+        result.requirements.push(currentRequirement);
+      }
+      currentRequirement = {
+        name: line.substring(16).trim(),
+        description: '',
+        scenarios: []
+      };
+      currentScenario = null;
+      buffer = [];
+      continue;
+    }
+
+    // #### Scenario: Case
+    if (line.startsWith('#### Scenario:')) {
+      if (currentRequirement && buffer.length > 0) {
+        currentRequirement.description = buffer.join('\n').trim();
+        buffer = [];
+      }
+      currentScenario = {
+        name: line.substring(14).trim(),
+        steps: []
+      };
+      continue;
+    }
+
+    // BDD steps (GIVEN/WHEN/THEN)
+    if (currentScenario && (line.startsWith('- GIVEN') || line.startsWith('- WHEN') || line.startsWith('- THEN') || line.startsWith('- AND'))) {
+      currentScenario.steps.push(line.substring(2).trim());
+      continue;
+    }
+
+    // 收集内容
+    if (currentSection === 'purpose' && line.trim()) {
+      buffer.push(line);
+    } else if (currentRequirement && !currentScenario && line.trim()) {
+      buffer.push(line);
+    }
+
+    // 场景结束
+    if (currentScenario && line.trim() === '' && currentScenario.steps.length > 0) {
+      currentRequirement.scenarios.push(currentScenario);
+      currentScenario = null;
+    }
+  }
+
+  // 处理最后的 requirement
+  if (currentRequirement) {
+    if (currentScenario && currentScenario.steps.length > 0) {
+      currentRequirement.scenarios.push(currentScenario);
+    }
+    result.requirements.push(currentRequirement);
+  }
+
+  return result;
+}
+
+/**
+ * 转换为 CC-DevFlow spec.md 格式
+ */
+function convertToDevFlowSpec(openspecData, reqId, title) {
+  const now = new Date().toISOString();
+
+  let output = `---
+req_id: "${reqId}"
+title: "${title}"
+created_at: "${now}"
+updated_at: "${now}"
+version: "1.0.0"
+status: "draft"
+source: "openspec"
+---
+
+# ${openspecData.moduleName}
+
+## Purpose
+
+${openspecData.purpose}
+
+## Requirements
+
+`;
+
+  // 转换 Requirements
+  for (const req of openspecData.requirements) {
+    output += `### Requirement: ${req.name}\n\n`;
+
+    if (req.description) {
+      output += `${req.description}\n\n`;
+    }
+
+    // 转换 Scenarios (BDD 格式)
+    for (const scenario of req.scenarios) {
+      output += `#### Scenario: ${scenario.name}\n\n`;
+      for (const step of scenario.steps) {
+        output += `- ${step}\n`;
+      }
+      output += '\n';
+    }
+  }
+
+  // 添加 Design 部分 (空白，待填充)
+  output += `## Design
+
+[NEEDS CLARIFICATION: 技术实现方案]
+
+### Architecture
+
+[NEEDS CLARIFICATION: 架构设计]
+
+### Data Model
+
+[NEEDS CLARIFICATION: 数据模型]
+
+### API Design
+
+[NEEDS CLARIFICATION: API 设计]
+
+## Tasks
+
+`;
+
+  // 自动生成 TDD 任务
+  let taskId = 1;
+  for (const req of openspecData.requirements) {
+    const featureName = req.name;
+
+    // TEST 任务
+    output += `- [ ] T${String(taskId).padStart(3, '0')} [TEST] ${featureName} - 测试\n`;
+    const testTaskId = taskId;
+    taskId++;
+
+    // IMPL 任务
+    output += `- [ ] T${String(taskId).padStart(3, '0')} [IMPL] ${featureName} - 实现 (dependsOn:T${String(testTaskId).padStart(3, '0')})\n`;
+    taskId++;
+  }
+
+  output += `
+## Verification
+
+`;
+
+  // 生成验收标准
+  for (const req of openspecData.requirements) {
+    output += `- [ ] ${req.name}\n`;
+    for (const scenario of req.scenarios) {
+      output += `  - [ ] ${scenario.name}\n`;
+    }
+  }
+
+  return output;
+}
+
+/**
+ * 主函数
+ */
+function importOpenSpec(openspecPath, reqId, title, outputPath) {
+  // 读取 OpenSpec 文件
+  if (!fs.existsSync(openspecPath)) {
+    throw new Error(`OpenSpec file not found: ${openspecPath}`);
+  }
+
+  const content = fs.readFileSync(openspecPath, 'utf-8');
+
+  // 解析 OpenSpec
+  const openspecData = parseOpenSpecMarkdown(content);
+
+  // 转换为 CC-DevFlow 格式
+  const devflowSpec = convertToDevFlowSpec(openspecData, reqId, title);
+
+  // 写入输出文件
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  fs.writeFileSync(outputPath, devflowSpec, 'utf-8');
+
+  return {
+    success: true,
+    outputPath,
+    requirementsCount: openspecData.requirements.length,
+    tasksCount: openspecData.requirements.length * 2 // TEST + IMPL
+  };
+}
+
+// CLI 接口
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length < 4) {
+    console.error('Usage: import-openspec.js <openspec-path> <req-id> <title> <output-path>');
+    process.exit(1);
+  }
+
+  const [openspecPath, reqId, title, outputPath] = args;
+
+  try {
+    const result = importOpenSpec(openspecPath, reqId, title, outputPath);
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error('Error:', error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { importOpenSpec, parseOpenSpecMarkdown, convertToDevFlowSpec };