speccrew 0.1.0

package/bin/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const command = process.argv[2];
+const args = process.argv.slice(3);
+const projectRoot = process.cwd();
+
+function printUsage() {
+  console.log(`
+SpecCrew - Spec-Driven Development toolkit for AI-powered IDEs
+
+Usage: speccrew <command> [options]
+
+Commands:
+  init        Initialize SpecCrew in the current project
+  update      Update SpecCrew agents and skills
+  doctor      Check environment and installation health
+  uninstall   Remove SpecCrew from the current project
+  list        List installed agents and skills
+
+Options:
+  --help      Show help
+  --version   Show version
+
+Examples:
+  speccrew init --ide qoder
+  speccrew update
+  speccrew doctor
+`);
+}
+
+switch (command) {
+  case 'init':
+    require('../lib/commands/init').run();
+    break;
+  case 'update':
+    require('../lib/commands/update').run();
+    break;
+  case 'doctor':
+    require('../lib/commands/doctor').run(projectRoot, args);
+    break;
+  case 'uninstall':
+    require('../lib/commands/uninstall').run(projectRoot, args);
+    break;
+  case 'list':
+    require('../lib/commands/list').run(projectRoot, args);
+    break;
+  case '--version':
+  case '-v':
+    const pkg = require('../package.json');
+    console.log(pkg.version);
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}

package/lib/commands/doctor.js

@@ -0,0 +1,138 @@
+const fs = require('fs');
+const path = require('path');
+const { readSpeccrewRC, getPackageVersion, getSourceRoot, isSpeccrewFile } = require('../utils');
+const { detectIDE, IDE_CONFIGS } = require('../ide-adapters');
+
+function run(projectRoot, args) {
+  console.log('SpecCrew Doctor\n');
+
+  const results = [];
+
+  // 1. Node.js 版本检查
+  const nodeVersion = process.version;
+  const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  if (majorVersion >= 16) {
+    results.push({ status: 'PASS', message: `Node.js ${nodeVersion} (>= 16.0.0)` });
+  } else {
+    results.push({ status: 'FAIL', message: `Node.js ${nodeVersion} (< 16.0.0)` });
+  }
+
+  // 2. SpecCrew 安装状态
+  const rc = readSpeccrewRC(projectRoot);
+  const version = getPackageVersion();
+  if (rc) {
+    results.push({ status: 'PASS', message: `SpecCrew v${version} installed` });
+  } else {
+    results.push({ status: 'WARN', message: 'Not initialized, run speccrew init' });
+  }
+
+  // 3. IDE 目录检查
+  const detectedIDEs = detectIDE(projectRoot);
+  if (detectedIDEs.length > 0) {
+    const ideNames = detectedIDEs.map(ide => `${ide.name} (${ide.baseDir}/)`).join(', ');
+    results.push({ status: 'PASS', message: `IDE: ${ideNames}` });
+  } else {
+    results.push({ status: 'WARN', message: 'No supported IDE detected' });
+  }
+
+  // 4. Agents 完整性检查
+  const sourceRoot = getSourceRoot();
+  const sourceAgentsDir = path.join(sourceRoot, 'agents');
+  let sourceAgentCount = 0;
+  let installedAgentCount = 0;
+  let missingAgents = [];
+
+  if (fs.existsSync(sourceAgentsDir)) {
+    const sourceAgents = fs.readdirSync(sourceAgentsDir).filter(isSpeccrewFile);
+    sourceAgentCount = sourceAgents.length;
+
+    for (const ide of detectedIDEs) {
+      const agentsDir = path.join(projectRoot, ide.agentsDir);
+      if (fs.existsSync(agentsDir)) {
+        const installed = fs.readdirSync(agentsDir).filter(isSpeccrewFile);
+        installedAgentCount = installed.length;
+
+        for (const agent of sourceAgents) {
+          const agentName = agent.replace(/\.md$/, '');
+          if (!installed.includes(agent)) {
+            missingAgents.push(agentName);
+          }
+        }
+      }
+    }
+  }
+
+  if (missingAgents.length === 0 && sourceAgentCount > 0) {
+    results.push({ status: 'PASS', message: `Agents: ${installedAgentCount}/${sourceAgentCount} installed` });
+  } else if (sourceAgentCount > 0) {
+    results.push({ status: 'WARN', message: `Agents: ${installedAgentCount}/${sourceAgentCount} installed (missing: ${missingAgents.join(', ')})` });
+  } else {
+    results.push({ status: 'WARN', message: 'Agents: source not found' });
+  }
+
+  // 5. Skills 完整性检查
+  const sourceSkillsDir = path.join(sourceRoot, 'skills');
+  let sourceSkillCount = 0;
+  let installedSkillCount = 0;
+  let missingSkills = [];
+
+  if (fs.existsSync(sourceSkillsDir)) {
+    const sourceSkills = fs.readdirSync(sourceSkillsDir).filter(isSpeccrewFile);
+    sourceSkillCount = sourceSkills.length;
+
+    for (const ide of detectedIDEs) {
+      const skillsDir = path.join(projectRoot, ide.skillsDir);
+      if (fs.existsSync(skillsDir)) {
+        const installed = fs.readdirSync(skillsDir).filter(isSpeccrewFile);
+        installedSkillCount = Math.max(installedSkillCount, installed.length);
+
+        for (const skill of sourceSkills) {
+          if (!installed.includes(skill)) {
+            missingSkills.push(skill);
+          }
+        }
+      }
+    }
+  }
+
+  if (missingSkills.length === 0 && sourceSkillCount > 0) {
+    results.push({ status: 'PASS', message: `Skills: ${installedSkillCount}/${sourceSkillCount} installed` });
+  } else if (sourceSkillCount > 0) {
+    results.push({ status: 'WARN', message: `Skills: ${installedSkillCount}/${sourceSkillCount} installed (missing: ${missingSkills.join(', ')})` });
+  } else {
+    results.push({ status: 'WARN', message: 'Skills: source not found' });
+  }
+
+  // 6. Workspace 目录检查
+  const workspaceDir = path.join(projectRoot, 'speccrew-workspace');
+  const docsDir = path.join(workspaceDir, 'docs');
+  if (fs.existsSync(workspaceDir) && fs.existsSync(docsDir)) {
+    results.push({ status: 'PASS', message: 'Workspace: speccrew-workspace/ OK' });
+  } else if (fs.existsSync(workspaceDir)) {
+    results.push({ status: 'WARN', message: 'Workspace: speccrew-workspace/ exists but docs/ missing' });
+  } else {
+    results.push({ status: 'WARN', message: 'Workspace: speccrew-workspace/ not found' });
+  }
+
+  // 输出结果
+  let passCount = 0;
+  let warnCount = 0;
+  let failCount = 0;
+
+  for (const result of results) {
+    const icon = result.status === 'PASS' ? 'PASS' : result.status === 'WARN' ? 'WARN' : 'FAIL';
+    const padding = '  ';
+    console.log(`${padding}${icon}  ${result.message}`);
+
+    if (result.status === 'PASS') passCount++;
+    else if (result.status === 'WARN') warnCount++;
+    else failCount++;
+  }
+
+  console.log('');
+  console.log(`${passCount} passed, ${warnCount} warning${warnCount !== 1 ? 's' : ''}, ${failCount} error${failCount !== 1 ? 's' : ''}`);
+
+  return failCount === 0;
+}
+
+module.exports = { run };

package/lib/commands/init.js

@@ -0,0 +1,231 @@
+const fs = require('fs');
+const path = require('path');
+const {
+  copyDirRecursive,
+  isSpeccrewFile,
+  writeSpeccrewRC,
+  getPackageVersion,
+  getSourceRoot,
+  getWorkspaceTemplatePath,
+  ensureDirectories,
+} = require('../utils');
+const { resolveIDE } = require('../ide-adapters');
+
+// 解析命令行参数
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let ide = null;
+  
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--ide' && i + 1 < args.length) {
+      ide = args[i + 1];
+      break;
+    }
+  }
+  
+  return { ide };
+}
+
+// 检查 Node.js 版本 >= 16
+function checkNodeVersion() {
+  const version = process.version;
+  const major = parseInt(version.slice(1).split('.')[0], 10);
+  if (major < 16) {
+    throw new Error(`Node.js version ${version} is not supported. Please upgrade to Node.js 16 or higher.`);
+  }
+}
+
+// 复制 agents（speccrew-* 前缀文件，总是覆盖）
+function copyAgents(sourceDir, destDir) {
+  if (!fs.existsSync(sourceDir)) return { copied: 0, skipped: 0 };
+  
+  fs.mkdirSync(destDir, { recursive: true });
+  let copied = 0, skipped = 0;
+  
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!isSpeccrewFile(entry.name)) {
+      skipped++;
+      continue;
+    }
+    
+    const srcPath = path.join(sourceDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    
+    fs.copyFileSync(srcPath, destPath);
+    copied++;
+  }
+  
+  return { copied, skipped };
+}
+
+// 复制 skills（speccrew-* 前缀目录，递归复制，总是覆盖）
+function copySkills(sourceDir, destDir) {
+  if (!fs.existsSync(sourceDir)) return { copied: 0, skipped: 0 };
+  
+  let copied = 0, skipped = 0;
+  
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!isSpeccrewFile(entry.name)) {
+      skipped++;
+      continue;
+    }
+    
+    const srcPath = path.join(sourceDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    
+    if (entry.isDirectory()) {
+      const result = copyDirRecursive(srcPath, destPath);
+      copied += result.copied;
+      skipped += result.skipped;
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      copied++;
+    }
+  }
+  
+  return { copied, skipped };
+}
+
+// 创建 workspace 目录结构
+function createWorkspaceStructure(workspaceDir) {
+  const dirs = [
+    'iterations',
+    'iteration-archives',
+    'knowledges/base/diagnosis-reports',
+    'knowledges/base/sync-state',
+    'knowledges/base/tech-debts',
+    'knowledges/bizs',
+    'knowledges/techs',
+    'docs/configs',
+    'docs/rules',
+    'docs/solutions',
+    'docs/templates',
+  ];
+  
+  ensureDirectories(workspaceDir, dirs);
+}
+
+// 复制 workspace 模板（仅复制不存在的文件）
+function copyWorkspaceTemplate(templateDir, workspaceDir) {
+  if (!fs.existsSync(templateDir)) return { copied: 0, skipped: 0 };
+  
+  const docsSourceDir = path.join(templateDir, 'docs');
+  const docsDestDir = path.join(workspaceDir, 'docs');
+  
+  if (!fs.existsSync(docsSourceDir)) return { copied: 0, skipped: 0 };
+  
+  fs.mkdirSync(docsDestDir, { recursive: true });
+  let copied = 0, skipped = 0;
+  
+  function copyIfNotExists(src, dest) {
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      
+      if (entry.isDirectory()) {
+        fs.mkdirSync(destPath, { recursive: true });
+        copyIfNotExists(srcPath, destPath);
+      } else {
+        if (!fs.existsSync(destPath)) {
+          fs.copyFileSync(srcPath, destPath);
+          copied++;
+        } else {
+          skipped++;
+        }
+      }
+    }
+  }
+  
+  copyIfNotExists(docsSourceDir, docsDestDir);
+  return { copied, skipped };
+}
+
+// 主函数
+function run() {
+  try {
+    // 1. 解析参数
+    const { ide: cliIdeArg } = parseArgs();
+    
+    // 2. 确定项目根目录
+    const projectRoot = process.cwd();
+    
+    // 3. 检查 Node.js 版本
+    checkNodeVersion();
+    
+    // 4. 解析 IDE
+    const ideConfigs = resolveIDE(projectRoot, cliIdeArg);
+    
+    // 5. 确定源文件路径
+    const sourceRoot = getSourceRoot();
+    
+    // 统计信息
+    const stats = {
+      ides: [],
+      totalAgents: 0,
+      totalSkills: 0,
+      workspaceCreated: false,
+    };
+    
+    // 6. 对每个检测到的 IDE 复制 agents 和 skills
+    for (const ideConfig of ideConfigs) {
+      const agentsSourceDir = path.join(sourceRoot, 'agents');
+      const skillsSourceDir = path.join(sourceRoot, 'skills');
+      const agentsDestDir = path.join(projectRoot, ideConfig.agentsDir);
+      const skillsDestDir = path.join(projectRoot, ideConfig.skillsDir);
+      
+      const agentsResult = copyAgents(agentsSourceDir, agentsDestDir);
+      const skillsResult = copySkills(skillsSourceDir, skillsDestDir);
+      
+      stats.ides.push({
+        name: ideConfig.name,
+        baseDir: ideConfig.baseDir,
+        agents: agentsResult.copied,
+        skills: skillsResult.copied,
+      });
+      stats.totalAgents += agentsResult.copied;
+      stats.totalSkills += skillsResult.copied;
+    }
+    
+    // 7. 创建 speccrew-workspace 目录结构
+    const workspaceDir = path.join(projectRoot, 'speccrew-workspace');
+    createWorkspaceStructure(workspaceDir);
+    stats.workspaceCreated = true;
+    
+    // 8. 复制 workspace 模板
+    const templateDir = getWorkspaceTemplatePath();
+    copyWorkspaceTemplate(templateDir, workspaceDir);
+    
+    // 9. 写入 .speccrewrc
+    const version = getPackageVersion();
+    const rcConfig = {
+      ide: ideConfigs.length === 1 ? ideConfigs[0].id : ideConfigs.map(c => c.id),
+      version: version,
+      installedAt: new Date().toISOString(),
+    };
+    writeSpeccrewRC(projectRoot, rcConfig);
+    
+    // 10. 输出安装摘要
+    console.log(`SpecCrew v${version} installed successfully!\n`);
+    
+    for (const ide of stats.ides) {
+      console.log(`IDE: ${ide.name} (${ide.baseDir}/)`);
+      console.log(`Agents: ${ide.agents} installed`);
+      console.log(`Skills: ${ide.skills} installed`);
+    }
+    
+    if (stats.workspaceCreated) {
+      console.log('Workspace: speccrew-workspace/ created');
+    }
+    
+    console.log('\nGet started: Ask your AI agent to help with your project!');
+    
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = { run };

package/lib/commands/list.js

@@ -0,0 +1,114 @@
+const fs = require('fs');
+const path = require('path');
+const { readSpeccrewRC, getPackageVersion, isSpeccrewFile } = require('../utils');
+
+function run(projectRoot, args) {
+  // 检查是否已初始化
+  const rc = readSpeccrewRC(projectRoot);
+  if (!rc) {
+    console.log('SpecCrew is not initialized in this project.');
+    console.log('Run "speccrew init" to initialize.');
+    return false;
+  }
+
+  const version = getPackageVersion();
+  const ides = rc.ide ? (Array.isArray(rc.ide) ? rc.ide : [rc.ide]) : [];
+  const ideNames = ides.map(id => {
+    const names = { qoder: 'Qoder', cursor: 'Cursor' };
+    return names[id] || id;
+  });
+  const ideDisplay = ideNames.length > 0 ? ideNames.join(', ') : 'Unknown';
+  const ideDirs = ides.map(id => {
+    const dirs = { qoder: '.qoder/', cursor: '.cursor/' };
+    return dirs[id] || `.${id}/`;
+  });
+
+  console.log(`SpecCrew v${version} | IDE: ${ideDisplay} (${ideDirs.join(', ')})\n`);
+
+  // 收集所有 agents 和 skills
+  const speccrewAgents = new Set();
+  const speccrewSkills = new Set();
+  const userAgents = new Set();
+  const userSkills = new Set();
+
+  for (const ideId of ides) {
+    const ideConfig = getIDEConfig(ideId);
+    if (!ideConfig) continue;
+
+    // 扫描 agents
+    const agentsDir = path.join(projectRoot, ideConfig.agentsDir);
+    if (fs.existsSync(agentsDir)) {
+      const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        const name = entry.name;
+        if (isSpeccrewFile(name)) {
+          speccrewAgents.add(name.replace(/\.md$/, ''));
+        } else if (!name.startsWith('.') && entry.isDirectory()) {
+          userAgents.add(`${ideConfig.agentsDir}/${name}`);
+        }
+      }
+    }
+
+    // 扫描 skills
+    const skillsDir = path.join(projectRoot, ideConfig.skillsDir);
+    if (fs.existsSync(skillsDir)) {
+      const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        const name = entry.name;
+        if (isSpeccrewFile(name)) {
+          speccrewSkills.add(name);
+        } else if (!name.startsWith('.') && entry.isDirectory()) {
+          userSkills.add(`${ideConfig.skillsDir}/${name}`);
+        }
+      }
+    }
+  }
+
+  // 输出 Agents
+  const sortedAgents = Array.from(speccrewAgents).sort();
+  console.log(`Agents (${sortedAgents.length}):`);
+  for (const agent of sortedAgents) {
+    console.log(`  ${agent}`);
+  }
+  console.log('');
+
+  // 输出 Skills
+  const sortedSkills = Array.from(speccrewSkills).sort();
+  console.log(`Skills (${sortedSkills.length}):`);
+  for (const skill of sortedSkills) {
+    console.log(`  ${skill}`);
+  }
+  console.log('');
+
+  // 输出用户自定义内容
+  const allUserDefined = [...Array.from(userAgents), ...Array.from(userSkills)].sort();
+  if (allUserDefined.length > 0) {
+    console.log('User-defined:');
+    for (const item of allUserDefined) {
+      console.log(`  ${item}`);
+    }
+  }
+
+  return true;
+}
+
+// 获取 IDE 配置（简化版，避免循环依赖）
+function getIDEConfig(ideId) {
+  const configs = {
+    qoder: {
+      name: 'Qoder',
+      baseDir: '.qoder',
+      skillsDir: '.qoder/skills',
+      agentsDir: '.qoder/agents',
+    },
+    cursor: {
+      name: 'Cursor',
+      baseDir: '.cursor',
+      skillsDir: '.cursor/skills',
+      agentsDir: '.cursor/agents',
+    },
+  };
+  return configs[ideId] || null;
+}
+
+module.exports = { run };

package/lib/commands/uninstall.js

@@ -0,0 +1,117 @@
+const fs = require('fs');
+const path = require('path');
+const { readSpeccrewRC, isSpeccrewFile, removeDirRecursive } = require('../utils');
+
+function run(projectRoot, args) {
+  // 检查是否已初始化
+  const rc = readSpeccrewRC(projectRoot);
+  if (!rc) {
+    console.log('SpecCrew is not initialized in this project.');
+    console.log('Run "speccrew init" to initialize.');
+    return false;
+  }
+
+  console.log('SpecCrew Uninstall\n');
+
+  const isAll = args.includes('--all');
+  let removedAgents = 0;
+  let removedSkills = 0;
+  const removedItems = [];
+
+  // 获取 IDE 配置
+  const ides = rc.ide ? (Array.isArray(rc.ide) ? rc.ide : [rc.ide]) : [];
+
+  // 删除每个 IDE 目录下的 speccrew-* agents 和 skills
+  for (const ideId of ides) {
+    const ideConfig = getIDEConfig(ideId);
+    if (!ideConfig) continue;
+
+    // 删除 agents
+    const agentsDir = path.join(projectRoot, ideConfig.agentsDir);
+    if (fs.existsSync(agentsDir)) {
+      const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (isSpeccrewFile(entry.name)) {
+          const fullPath = path.join(agentsDir, entry.name);
+          if (entry.isDirectory()) {
+            removeDirRecursive(fullPath);
+          } else {
+            fs.unlinkSync(fullPath);
+          }
+          removedAgents++;
+          removedItems.push(`${ideConfig.baseDir}/agents/${entry.name}`);
+        }
+      }
+    }
+
+    // 删除 skills
+    const skillsDir = path.join(projectRoot, ideConfig.skillsDir);
+    if (fs.existsSync(skillsDir)) {
+      const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (isSpeccrewFile(entry.name)) {
+          const fullPath = path.join(skillsDir, entry.name);
+          if (entry.isDirectory()) {
+            removeDirRecursive(fullPath);
+          } else {
+            fs.unlinkSync(fullPath);
+          }
+          removedSkills++;
+          removedItems.push(`${ideConfig.baseDir}/skills/${entry.name}`);
+        }
+      }
+    }
+  }
+
+  // 如果 --all，删除 workspace
+  let workspaceRemoved = false;
+  if (isAll) {
+    const workspaceDir = path.join(projectRoot, 'speccrew-workspace');
+    if (fs.existsSync(workspaceDir)) {
+      removeDirRecursive(workspaceDir);
+      workspaceRemoved = true;
+      removedItems.push('speccrew-workspace/');
+    }
+  }
+
+  // 删除 .speccrewrc
+  const rcPath = path.join(projectRoot, '.speccrewrc');
+  if (fs.existsSync(rcPath)) {
+    fs.unlinkSync(rcPath);
+    removedItems.push('.speccrewrc');
+  }
+
+  // 输出摘要
+  console.log(`Removed ${removedAgents} agent(s) and ${removedSkills} skill(s)`);
+  if (workspaceRemoved) {
+    console.log('Removed speccrew-workspace/');
+  }
+  console.log('Removed .speccrewrc');
+  console.log('\nSpecCrew has been uninstalled.');
+  if (!isAll) {
+    console.log('Workspace data preserved. Use --all to remove everything.');
+  }
+
+  return true;
+}
+
+// 获取 IDE 配置（简化版，避免循环依赖）
+function getIDEConfig(ideId) {
+  const configs = {
+    qoder: {
+      name: 'Qoder',
+      baseDir: '.qoder',
+      skillsDir: '.qoder/skills',
+      agentsDir: '.qoder/agents',
+    },
+    cursor: {
+      name: 'Cursor',
+      baseDir: '.cursor',
+      skillsDir: '.cursor/skills',
+      agentsDir: '.cursor/agents',
+    },
+  };
+  return configs[ideId] || null;
+}
+
+module.exports = { run };