sdd-workflow 1.1.0

package/src/installer.js

@@ -0,0 +1,558 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const crypto = require('crypto');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+const MANIFEST_FILE = '.sdd-manifest.json';
+
+/**
+ * Install SDD workflow to target project directory.
+ * @param {string} targetDir - Absolute path to target project
+ * @param {object} options - Installation options
+ * @param {boolean} options.force - Overwrite existing files
+ * @param {boolean} options.dryRun - Preview only, don't write files
+ * @param {boolean} options.update - Incremental update: only update changed files, skip user-customized files
+ */
+async function install(targetDir, options = {}) {
+  const { force = false, dryRun = false, update = false } = options;
+
+  if (update) {
+    return updateInstall(targetDir, options);
+  }
+
+  console.log('');
+  console.log('━━━ SDD Workflow Installer ━━━');
+  console.log('');
+
+  // 1. Validate target directory
+  if (!fs.existsSync(path.join(targetDir, '.git'))) {
+    console.log('⚠️  Warning: Target directory is not a git repository.');
+    console.log('   SDD workflow works best in a git-managed project.');
+    console.log('');
+  }
+
+  // 2. Define installation targets
+  const operations = [
+    // Skills → .claude/skills/sdd-*
+    {
+      description: 'SDD Skills',
+      source: path.join(TEMPLATES_DIR, 'skills'),
+      target: path.join(targetDir, '.claude', 'skills'),
+      type: 'skills',
+    },
+    // .specify/ directory structure
+    {
+      description: 'SDD Templates & Scripts',
+      source: path.join(TEMPLATES_DIR, 'specify'),
+      target: path.join(targetDir, '.specify'),
+      type: 'specify',
+    },
+    // Team configuration
+    {
+      description: 'Team Configuration',
+      source: path.join(TEMPLATES_DIR, 'teams'),
+      target: path.join(targetDir, '.claude', 'teams'),
+      type: 'teams',
+    },
+  ];
+
+  // 3. Execute installations
+  let totalFiles = 0;
+  let skippedFiles = 0;
+  let createdDirs = 0;
+  const installedFiles = []; // track for manifest
+
+  for (const op of operations) {
+    if (!fs.existsSync(op.source)) {
+      console.log(`⚠️  Source not found: ${op.description} — skipping`);
+      continue;
+    }
+
+    console.log(`📦 Installing ${op.description}...`);
+
+    const result = copyDirectory(op.source, op.target, {
+      force,
+      dryRun,
+      installedFiles,
+      sourceBase: op.source,
+      targetBase: op.target,
+      trackSkipped: true, // also track skipped files for manifest
+    });
+
+    totalFiles += result.copied;
+    skippedFiles += result.skipped;
+    createdDirs += result.dirs;
+  }
+
+  // 4. Create empty specs directory if not exists
+  const specsDir = path.join(targetDir, '.specify', 'specs');
+  if (!fs.existsSync(specsDir) && !dryRun) {
+    fs.mkdirSync(specsDir, { recursive: true });
+  }
+
+  // 5. Create empty memory directory if not exists
+  const memoryDir = path.join(targetDir, '.specify', 'memory');
+  if (!fs.existsSync(memoryDir) && !dryRun) {
+    fs.mkdirSync(path.join(targetDir, '.specify', 'memory'), { recursive: true });
+  }
+
+  // 6. Save manifest (tracks installed file hashes for future updates)
+  if (!dryRun) {
+    saveManifest(targetDir, installedFiles);
+  }
+
+  // 7. Output results
+  console.log('');
+  console.log('━━━ Installation Complete ━━━');
+  console.log('');
+  console.log(`  Files installed: ${totalFiles}`);
+  console.log(`  Files skipped:   ${skippedFiles}`);
+  console.log(`  Directories:     ${createdDirs}`);
+  console.log('');
+
+  if (dryRun) {
+    console.log('🔍 This was a dry run. No files were actually created.');
+    console.log('   Run without --dry-run to install.');
+    return;
+  }
+
+  // 8. Print next steps
+  console.log('📋 Next Steps:');
+  console.log('');
+  console.log('  1. Open Claude Code in this project');
+  console.log('  2. Run /sdd-init to generate project constitution');
+  console.log('     (This analyzes your project and creates a tailored config)');
+  console.log('');
+  console.log('  3. Start using SDD workflow:');
+  console.log('     /sdd-specify <feature-name>    — Create specification');
+  console.log('     /sdd-testcases                 — Design test cases');
+  console.log('     /sdd-plan                      — Plan implementation');
+  console.log('     /sdd-tasks                     — Break down tasks');
+  console.log('     /sdd-implement                 — Execute development');
+  console.log('     /sdd-review                    — Quality review');
+  console.log('     /sdd-run <id> <description>    — Full auto pipeline');
+  console.log('');
+  console.log('  💡 To update SDD workflow in the future:');
+  console.log('     npx sdd-workflow --update');
+  console.log('');
+
+  // 9. Suggest CLAUDE.md additions
+  printClaudeMdSuggestions(targetDir);
+}
+
+/**
+ * Incremental update: only update files that changed in source,
+ * skip files that user has customized.
+ */
+async function updateInstall(targetDir, options = {}) {
+  const { dryRun = false } = options;
+
+  console.log('');
+  console.log('━━━ SDD Workflow Updater ━━━');
+  console.log('');
+
+  // 1. Load existing manifest
+  const manifestPath = path.join(targetDir, '.specify', MANIFEST_FILE);
+  const manifest = loadManifest(targetDir);
+
+  if (!manifest) {
+    console.log('⚠️  No manifest found. This project was installed before manifest tracking was added.');
+    console.log('');
+    console.log('   To enable smart updates, run a regular install first to create the manifest:');
+    console.log('     npx sdd-workflow              # Creates manifest without overwriting existing files');
+    console.log('');
+    console.log('   Then --update will correctly distinguish source updates from your customizations.');
+    console.log('');
+    console.log('   Falling back to conservative mode: all changed files treated as user-customized.');
+    console.log('   Use --force to overwrite everything.');
+    console.log('');
+  }
+
+  // 2. Collect all source files
+  const operations = [
+    {
+      description: 'SDD Skills',
+      source: path.join(TEMPLATES_DIR, 'skills'),
+      target: path.join(targetDir, '.claude', 'skills'),
+    },
+    {
+      description: 'SDD Templates & Scripts',
+      source: path.join(TEMPLATES_DIR, 'specify'),
+      target: path.join(targetDir, '.specify'),
+    },
+    {
+      description: 'Team Configuration',
+      source: path.join(TEMPLATES_DIR, 'teams'),
+      target: path.join(targetDir, '.claude', 'teams'),
+    },
+  ];
+
+  const stats = {
+    updated: [],    // source changed, target was original → auto-update
+    newFiles: [],   // not in target → auto-add
+    customized: [], // user modified → skip with warning
+    unchanged: [],  // source == target → skip
+    removed: [],    // in manifest but not in source → report
+  };
+
+  // 3. Compare source vs target using manifest
+  for (const op of operations) {
+    if (!fs.existsSync(op.source)) continue;
+
+    const sourceFiles = collectFiles(op.source);
+    for (const relPath of sourceFiles) {
+      const sourcePath = path.join(op.source, relPath);
+      const targetPath = path.join(op.target, relPath);
+      const sourceContent = fs.readFileSync(sourcePath);
+      const sourceHash = hashContent(sourceContent);
+
+      if (!fs.existsSync(targetPath)) {
+        // New file
+        stats.newFiles.push({ relPath: `${op.type || ''}/${relPath}`, sourcePath, targetPath, sourceContent });
+        continue;
+      }
+
+      const targetContent = fs.readFileSync(targetPath);
+      const targetHash = hashContent(targetContent);
+
+      if (sourceHash === targetHash) {
+        // Already up to date
+        stats.unchanged.push(relPath);
+        continue;
+      }
+
+      // Content differs - check if user customized
+      // Manifest records source hash from last install/update
+      const manifestEntry = manifest ? manifest.files[relPath] : null;
+
+      if (manifestEntry) {
+        if (targetHash === manifestEntry.hash) {
+          // Target matches original source → user hasn't modified → safe to update
+          stats.updated.push({ relPath, sourcePath, targetPath, sourceContent });
+        } else {
+          // Target differs from original source → user customized → skip
+          stats.customized.push({ relPath, sourcePath, targetPath, sourceContent });
+        }
+      } else {
+        // No manifest entry - conservative: treat all as customized
+        // User should run regular install first to create manifest
+        stats.customized.push({ relPath, sourcePath, targetPath, sourceContent });
+      }
+    }
+  }
+
+  // 4. Check for removed files (in manifest but not in source)
+  if (manifest) {
+    const sourceFilesSet = new Set();
+    for (const op of operations) {
+      if (!fs.existsSync(op.source)) continue;
+      for (const relPath of collectFiles(op.source)) {
+        sourceFilesSet.add(relPath);
+      }
+    }
+    for (const relPath of Object.keys(manifest.files)) {
+      if (!sourceFilesSet.has(relPath)) {
+        stats.removed.push(relPath);
+      }
+    }
+  }
+
+  // 5. Print update summary
+  console.log('📊 Update Analysis:');
+  console.log('');
+  console.log(`   ✅ Up to date:    ${stats.unchanged.length} file(s)`);
+  console.log(`   📥 Source updated: ${stats.updated.length} file(s) will be updated`);
+  console.log(`   🆕 New files:      ${stats.newFiles.length} file(s) will be added`);
+  console.log(`   ✏️  Customized:    ${stats.customized.length} file(s) skipped (user modified)`);
+  if (stats.removed.length > 0) {
+    console.log(`   🗑️  Removed in source: ${stats.removed.length} file(s) (not deleted, manual cleanup needed)`);
+  }
+  console.log('');
+
+  if (stats.updated.length === 0 && stats.newFiles.length === 0) {
+    console.log('✅ Everything is up to date. No changes needed.');
+    return;
+  }
+
+  // 6. Show details of changes
+  if (stats.updated.length > 0) {
+    console.log('📥 Files to update:');
+    for (const f of stats.updated) {
+      console.log(`   - ${f.relPath}`);
+    }
+    console.log('');
+  }
+
+  if (stats.newFiles.length > 0) {
+    console.log('🆕 New files to add:');
+    for (const f of stats.newFiles) {
+      console.log(`   - ${f.relPath}`);
+    }
+    console.log('');
+  }
+
+  if (stats.customized.length > 0) {
+    console.log('⏭️  Customized files (skipped, use --force to overwrite):');
+    for (const f of stats.customized) {
+      console.log(`   - ${f.relPath}`);
+    }
+    console.log('');
+  }
+
+  if (dryRun) {
+    console.log('🔍 This was a dry run. No files were actually updated.');
+    console.log('   Run without --dry-run to apply updates.');
+    return;
+  }
+
+  // 7. Apply updates
+  let appliedCount = 0;
+
+  for (const f of stats.updated) {
+    const parentDir = path.dirname(f.targetPath);
+    if (!fs.existsSync(parentDir)) {
+      fs.mkdirSync(parentDir, { recursive: true });
+    }
+    fs.writeFileSync(f.targetPath, f.sourceContent);
+    appliedCount++;
+  }
+
+  for (const f of stats.newFiles) {
+    const parentDir = path.dirname(f.targetPath);
+    if (!fs.existsSync(parentDir)) {
+      fs.mkdirSync(parentDir, { recursive: true });
+    }
+    fs.writeFileSync(f.targetPath, f.sourceContent);
+    appliedCount++;
+  }
+
+  // 8. Update manifest
+  const allInstalledFiles = [];
+  // Re-scan all installed files to rebuild manifest
+  for (const op of operations) {
+    if (!fs.existsSync(op.source)) continue;
+    for (const relPath of collectFiles(op.source)) {
+      const targetPath = path.join(op.target, relPath);
+      if (fs.existsSync(targetPath)) {
+        allInstalledFiles.push({
+          relPath,
+          targetPath,
+        });
+      }
+    }
+  }
+  saveManifest(targetDir, allInstalledFiles);
+
+  console.log(`✅ ${appliedCount} file(s) updated successfully.`);
+  console.log('');
+
+  if (stats.customized.length > 0) {
+    console.log('💡 To overwrite customized files, run:');
+    console.log('   npx sdd-workflow --force');
+    console.log('');
+  }
+}
+
+// ─── Manifest Management ───
+
+/**
+ * Save installation manifest for future update tracking.
+ */
+function saveManifest(targetDir, installedFiles) {
+  const manifest = {
+    version: getVersion(),
+    installedAt: new Date().toISOString(),
+    files: {},
+  };
+
+  for (const item of installedFiles) {
+    // Record SOURCE hash (not target hash) so we can detect user customizations later
+    // If source file exists, hash it; otherwise hash the target (e.g. for skipped files without source)
+    let hash;
+    if (item.sourcePath && fs.existsSync(item.sourcePath)) {
+      hash = hashContent(fs.readFileSync(item.sourcePath));
+    } else if (fs.existsSync(item.targetPath)) {
+      hash = hashContent(fs.readFileSync(item.targetPath));
+    }
+    if (hash) {
+      manifest.files[item.relPath] = {
+        hash: hash,
+        installedAt: new Date().toISOString(),
+      };
+    }
+  }
+
+  const manifestDir = path.join(targetDir, '.specify');
+  if (!fs.existsSync(manifestDir)) {
+    fs.mkdirSync(manifestDir, { recursive: true });
+  }
+
+  fs.writeFileSync(
+    path.join(manifestDir, MANIFEST_FILE),
+    JSON.stringify(manifest, null, 2)
+  );
+}
+
+/**
+ * Load existing manifest.
+ */
+function loadManifest(targetDir) {
+  const manifestPath = path.join(targetDir, '.specify', MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return null;
+
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Get package version.
+ */
+function getVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+    );
+    return pkg.version;
+  } catch (e) {
+    return 'unknown';
+  }
+}
+
+// ─── File Utilities ───
+
+/**
+ * Hash file content for comparison.
+ */
+function hashContent(content) {
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+/**
+ * Collect all files in a directory, returning relative paths.
+ */
+function collectFiles(dir) {
+  const files = [];
+  if (!fs.existsSync(dir)) return files;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      for (const subFile of collectFiles(fullPath)) {
+        files.push(path.join(entry.name, subFile));
+      }
+    } else {
+      files.push(entry.name);
+    }
+  }
+  return files;
+}
+
+/**
+ * Recursively copy a directory.
+ */
+function copyDirectory(source, target, options) {
+  const result = { copied: 0, skipped: 0, dirs: 0 };
+
+  if (!fs.existsSync(source)) return result;
+
+  const entries = fs.readdirSync(source, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!options.dryRun && !fs.existsSync(targetPath)) {
+        fs.mkdirSync(targetPath, { recursive: true });
+        result.dirs++;
+      }
+      const subResult = copyDirectory(sourcePath, targetPath, options);
+      result.copied += subResult.copied;
+      result.skipped += subResult.skipped;
+      result.dirs += subResult.dirs;
+    } else {
+      if (fs.existsSync(targetPath) && !options.force) {
+        result.skipped++;
+        // Also track skipped files for manifest (to build baseline for --update)
+        if (options.installedFiles && options.sourceBase && options.trackSkipped) {
+          const relPath = path.relative(options.sourceBase, sourcePath);
+          options.installedFiles.push({ relPath, sourcePath, targetPath });
+        }
+        continue;
+      }
+
+      if (!options.dryRun) {
+        const parentDir = path.dirname(targetPath);
+        if (!fs.existsSync(parentDir)) {
+          fs.mkdirSync(parentDir, { recursive: true });
+          result.dirs++;
+        }
+        fs.copyFileSync(sourcePath, targetPath);
+      }
+      result.copied++;
+
+      // Track for manifest
+      if (options.installedFiles && options.sourceBase) {
+        const relPath = path.relative(options.sourceBase, sourcePath);
+        options.installedFiles.push({ relPath, sourcePath, targetPath });
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Print suggestions for CLAUDE.md additions.
+ */
+function printClaudeMdSuggestions(targetDir) {
+  const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
+  const hasClaudeMd = fs.existsSync(claudeMdPath);
+
+  console.log('━━━ CLAUDE.md Suggestions ━━━');
+  console.log('');
+
+  if (hasClaudeMd) {
+    console.log('  Add the following to your existing CLAUDE.md:');
+  } else {
+    console.log('  Create a CLAUDE.md with the following content:');
+  }
+
+  console.log('');
+  console.log('  ```markdown');
+  console.log('  ## SDD Workflow');
+  console.log('');
+  console.log('  This project uses SDD (Specification-Driven Development).');
+  console.log('');
+  console.log('  ### Quick Start');
+  console.log('  1. `/sdd-init` — Initialize SDD for this project (first time only)');
+  console.log('  2. `/sdd-run <id> <description>` — Full auto pipeline (recommended)');
+  console.log('  3. Or use individual commands: /sdd-specify → /sdd-testcases → /sdd-plan → /sdd-tasks → /sdd-implement → /sdd-review');
+  console.log('');
+  console.log('  ### Document Structure');
+  console.log('  - `.specify/memory/constitution.md` — Project constitution (tech stack, principles)');
+  console.log('  - `.specify/specs/<id>-<name>/` — Feature specifications');
+  console.log('  - `.specify/templates/` — Document templates');
+  console.log('  ```');
+  console.log('');
+
+  // Check if .gitignore needs updating
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const gitignore = fs.readFileSync(gitignorePath, 'utf8');
+    if (!gitignore.includes('.specify/specs/')) {
+      console.log('  💡 Consider adding to .gitignore:');
+      console.log('     .specify/specs/     # SDD feature specs (project-specific)');
+      console.log('     .specify/memory/    # SDD project memory');
+      console.log('');
+    }
+  }
+}
+
+module.exports = { install };

package/templates/skills/sdd-constitution/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: sdd-constitution
+description: 创建或更新项目宪法（Constitution）- 定义项目的开发原则、技术栈约束和架构决策
+invocable: true
+---
+
+# SDD Constitution - 项目宪法生成器
+
+创建或更新项目宪法，定义项目的开发原则、技术栈约束和架构决策。
+
+## 执行步骤
+
+### 1. 读取模板
+读取模板文件: `.specify/templates/constitution-template.md`
+
+### 2. 收集项目信息
+
+#### 2.1 读取项目文档
+- `CLAUDE.md` - 项目配置和说明
+- `README.md` - 项目概述
+- `docs/` 目录下的相关文档
+
+#### 2.2 自动检测项目结构
+
+扫描项目根目录，自动识别技术栈和模块结构：
+
+| 检测文件 | 识别信息 |
+|----------|----------|
+| `package.json` | 前端/Node.js 技术栈、框架、依赖版本 |
+| `pom.xml` / `build.gradle` | Java/JVM 后端技术栈、框架、依赖版本 |
+| `go.mod` | Go 后端技术栈 |
+| `Cargo.toml` | Rust 技术栈 |
+| `requirements.txt` / `pyproject.toml` | Python 技术栈 |
+| `*.sln` / `*.csproj` | .NET 技术栈 |
+
+根据检测结果，分析各模块的目录结构：
+- 前端源码目录（从 `package.json` 的入口和构建配置推断）
+- 后端源码目录（从构建配置和模块结构推断）
+- 数据库相关配置（从配置文件推断）
+
+#### 2.3 提取技术栈信息
+
+从检测文件中提取：
+- 前端框架和版本（如 React/Vue/Angular/Svelte）
+- 后端框架和版本（如 Spring Boot/Express/Django/FastAPI）
+- 状态管理方案（如 MobX/Redux/Vuex/Zustand）
+- 数据库类型和版本
+- 测试框架
+- 构建工具
+
+从现有代码中分析架构模式：
+- 是否使用 DDD 分层（Domain/Application/Infrastructure）
+- 是否使用传统三层架构（Controller/Service/DAO）
+- 是否使用 Clean Architecture
+- 是否使用六边形架构（Hexagonal）
+
+### 3. 生成宪法文档
+
+基于模板和收集的信息生成宪法文档。**宪法只记录开发约束和原则**，项目基本信息和技术栈由 CLAUDE.md 承载。
+
+#### 必须包含的内容：
+1. **绝对铁律** - 不可违反的开发规则
+2. **开发原则** - 简单性原则、N+1禁令、代码质量、测试标准
+3. **架构约束** - 检测到的架构模式的分层原则、API响应格式
+4. **SDD文档职责边界** - spec/plan/tasks的What/How/When分工
+5. **SDD阶段合约与评审标准**（SDD v2 新增）
+   - 评审维度与权重
+   - 硬阈值规则
+   - 迭代规则
+6. **经验教训** - 实际开发中积累的案例
+
+#### SDD v2 评审标准模板：
+
+```markdown
+## 七、SDD 阶段合约与评审标准
+
+### 7.1 评审维度与权重
+
+| 维度 | 权重 | 硬阈值 | 评审重点 |
+|------|------|--------|----------|
+| 功能完整性 | ★★★ | ≥ 4/5 | spec 中定义的所有功能点是否实现？有无存根/TODO？ |
+| 需求一致性 | ★★★ | ≥ 4/5 | 实现是否与 spec/testcases/plan 一致？有无偏离？ |
+| 代码质量 | ★★ | ≥ 3/5 | 宪法约束遵守？N+1？命名？架构分层？ |
+| 边界处理 | ★★ | ≥ 3/5 | spec 中的边界条件和异常场景是否覆盖？ |
+| 集成完整性 | ★★ | ≥ 3/5 | 前后端对接完整？API 链路通畅？数据流闭环？ |
+
+### 7.2 硬阈值规则
+
+- 功能完整性 < 4 → 必须 ITERATE
+- 需求一致性 < 4 → 必须 ITERATE
+- 任意维度出现 HIGH 严重度问题 → 必须 ITERATE
+
+### 7.3 迭代规则
+
+- 硬阈值未达标 → 必须迭代
+- 评审问题中存在 HIGH 严重度 → 必须迭代
+- 最多迭代 3 轮，超过则暂停等待用户决策
+```
+
+### 4. 保存文档
+将生成的文档保存到: `.specify/memory/constitution.md`
+
+### 5. 确认与修改
+向用户展示生成的文档，询问是否需要修改。
+
+## 输出示例
+
+```
+✅ 项目宪法已生成: .specify/memory/constitution.md
+
+文档包含以下章节：
+- 绝对铁律
+- 开发原则（简单性、N+1禁令、代码质量、测试标准）
+- 架构约束（检测到的架构模式分层原则、API响应格式）
+- SDD文档职责边界
+- SDD阶段合约与评审标准
+- 经验教训
+
+请检查文档内容，如需修改请告诉我。
+```
+
+## 注意事项
+
+1. **首次创建**: 如果是首次创建，需要全面分析项目并生成完整文档
+2. **更新模式**: 如果文档已存在，询问用户是追加还是覆盖
+3. **技术栈自适应**: 不预设特定技术栈，根据自动检测结果生成对应约束
+4. **架构模式自适应**: 根据检测到的架构模式（DDD/三层/Clean/六边形）生成对应的分层原则
+5. **CLAUDE.md 协作**: 项目基本信息和技术栈由 CLAUDE.md 承载，宪法聚焦于开发约束和原则