kiro-spec-engine 1.0.0

package/bin/kiro-spec-engine.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const fs = require('fs-extra');
+const path = require('path');
+const { spawn } = require('child_process');
+const { getI18n } = require('../lib/i18n');
+const doctorCommand = require('../lib/commands/doctor');
+
+const i18n = getI18n();
+const t = (key, params) => i18n.t(key, params);
+
+// Read version from package.json
+const packageJson = require('../package.json');
+
+const program = new Command();
+
+// 版本和基本信息
+program
+  .name(t('cli.name'))
+  .description(t('cli.description'))
+  .version(packageJson.version, '-v, --version', 'Display version number')
+  .option('-l, --lang <locale>', 'Set language (en/zh)', (locale) => {
+    i18n.setLocale(locale);
+  });
+
+// 初始化项目命令
+program
+  .command('init [project-name]')
+  .description(t('cli.commands.init.description'))
+  .option('-f, --force', t('cli.commands.init.forceOption'))
+  .action(async (projectName, options) => {
+    console.log(chalk.red('🔥') + ' ' + t('cli.commands.init.description'));
+    console.log();
+
+    // 获取项目名称
+    if (!projectName) {
+      const answers = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'projectName',
+          message: t('cli.commands.init.projectNamePrompt'),
+          default: path.basename(process.cwd())
+        }
+      ]);
+      projectName = answers.projectName;
+    }
+
+    // 检查是否已存在 .kiro 目录
+    const kiroDir = path.join(process.cwd(), '.kiro');
+    if (fs.existsSync(kiroDir) && !options.force) {
+      console.log(chalk.yellow(t('cli.commands.init.alreadyExists')));
+      const { overwrite } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'overwrite',
+          message: t('cli.commands.init.overwritePrompt'),
+          default: false
+        }
+      ]);
+      if (!overwrite) {
+        console.log(t('cli.commands.init.cancelled'));
+        return;
+      }
+    }
+
+    try {
+      // 复制模板文件
+      const templateDir = path.join(__dirname, '../template');
+      await fs.copy(templateDir, process.cwd(), { overwrite: true });
+
+      // 更新项目配置
+      await updateProjectConfig(projectName);
+
+      console.log();
+      console.log(chalk.green(t('cli.commands.init.success')));
+      console.log();
+      console.log(chalk.blue(t('cli.commands.init.nextSteps')));
+      console.log('  1. ' + t('cli.commands.init.step1'));
+      console.log('  2. ' + t('cli.commands.init.step2'));
+      console.log('  3. ' + t('cli.commands.init.step3'));
+      console.log();
+      console.log(chalk.red('🔥') + ' ' + t('cli.commands.init.startJourney'));
+    } catch (error) {
+      console.error(chalk.red(t('cli.commands.init.error')), error.message);
+      process.exit(1);
+    }
+  });
+
+// 增强文档命令
+program
+  .command('enhance <stage> <file>')
+  .description('Enhance document quality with Ultrawork spirit')
+  .option('-r, --requirements <file>', 'Requirements file (needed for design stage)')
+  .action(async (stage, file, options) => {
+    console.log(chalk.red('🔥') + ` Starting ${stage} stage Ultrawork enhancement...`);
+    
+    // 检查 Python 和工具是否可用
+    const toolPath = path.join(process.cwd(), '.kiro/tools/ultrawork_enhancer.py');
+    if (!fs.existsSync(toolPath)) {
+      console.error(chalk.red('❌ Ultrawork tool not found. Please run: kiro-spec-engine init'));
+      process.exit(1);
+    }
+
+    // 构建 Python 命令
+    let args = [toolPath, stage, file];
+    if (stage === 'design' && options.requirements) {
+      args.push(options.requirements);
+    }
+
+    // 执行 Python 工具
+    const python = spawn('python', args, { stdio: 'inherit' });
+    
+    python.on('close', (code) => {
+      if (code === 0) {
+        console.log(chalk.green('✅ Ultrawork enhancement completed!'));
+      } else {
+        console.error(chalk.red('❌ Enhancement failed with code:'), code);
+        process.exit(code);
+      }
+    });
+
+    python.on('error', (error) => {
+      console.error(chalk.red('❌ Error running Python tool:'), error.message);
+      console.log(chalk.yellow('💡 Make sure Python 3.8+ is installed and in PATH'));
+      process.exit(1);
+    });
+  });
+
+// 创建 Spec 命令
+program
+  .command('create-spec <spec-name>')
+  .description('Create a new spec directory')
+  .action(async (specName) => {
+    const specPath = path.join(process.cwd(), '.kiro/specs', specName);
+    
+    try {
+      await fs.ensureDir(specPath);
+      console.log(chalk.green('✅ Created spec directory:'), specPath);
+      console.log();
+      console.log(chalk.blue('📋 Next steps:'));
+      console.log('  1. Create requirements.md in the spec directory');
+      console.log('  2. Enhance with: ' + chalk.cyan(`kiro-spec-engine enhance requirements ${specPath}/requirements.md`));
+    } catch (error) {
+      console.error(chalk.red('❌ Error creating spec:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// 系统诊断命令
+program
+  .command('doctor')
+  .description(t('cli.commands.doctor.description'))
+  .action(() => {
+    doctorCommand();
+  });
+
+// 状态检查命令
+program
+  .command('status')
+  .description('Check project status and available specs')
+  .action(async () => {
+    const kiroDir = path.join(process.cwd(), '.kiro');
+    
+    if (!fs.existsSync(kiroDir)) {
+      console.log(chalk.yellow('⚠️  No Kiro Spec Engine project found in current directory'));
+      console.log('Run: ' + chalk.cyan('kiro-spec-engine init') + ' to initialize');
+      return;
+    }
+
+    console.log(chalk.red('🔥') + ' Kiro Spec Engine Project Status');
+    console.log();
+
+    // 检查工具状态
+    const toolPath = path.join(kiroDir, 'tools/ultrawork_enhancer.py');
+    const toolStatus = fs.existsSync(toolPath) ? chalk.green('✅ Available') : chalk.red('❌ Missing');
+    console.log('Ultrawork Tool:', toolStatus);
+
+    // 列出 Specs
+    const specsDir = path.join(kiroDir, 'specs');
+    if (fs.existsSync(specsDir)) {
+      const specs = fs.readdirSync(specsDir).filter(item => 
+        fs.statSync(path.join(specsDir, item)).isDirectory()
+      );
+      
+      console.log();
+      console.log(chalk.blue('📋 Available Specs:'));
+      if (specs.length === 0) {
+        console.log('  No specs found');
+      } else {
+        specs.forEach(spec => {
+          const specPath = path.join(specsDir, spec);
+          const hasReq = fs.existsSync(path.join(specPath, 'requirements.md'));
+          const hasDesign = fs.existsSync(path.join(specPath, 'design.md'));
+          const hasTasks = fs.existsSync(path.join(specPath, 'tasks.md'));
+          
+          console.log(`  ${spec}:`);
+          console.log(`    Requirements: ${hasReq ? chalk.green('✅') : chalk.gray('⚪')}`);
+          console.log(`    Design: ${hasDesign ? chalk.green('✅') : chalk.gray('⚪')}`);
+          console.log(`    Tasks: ${hasTasks ? chalk.green('✅') : chalk.gray('⚪')}`);
+        });
+      }
+    }
+  });
+
+// 更新项目配置的辅助函数
+async function updateProjectConfig(projectName) {
+  const envPath = path.join(process.cwd(), '.kiro/steering/ENVIRONMENT.md');
+  const contextPath = path.join(process.cwd(), '.kiro/steering/CURRENT_CONTEXT.md');
+
+  // 更新 ENVIRONMENT.md
+  if (fs.existsSync(envPath)) {
+    let content = await fs.readFile(envPath, 'utf8');
+    content = content.replace(/\[请修改为你的项目名称\]/g, projectName);
+    await fs.writeFile(envPath, content);
+  }
+
+  // 更新 CURRENT_CONTEXT.md
+  if (fs.existsSync(contextPath)) {
+    let content = await fs.readFile(contextPath, 'utf8');
+    content = content.replace(/新项目/g, projectName);
+    await fs.writeFile(contextPath, content);
+  }
+}
+
+// 解析命令行参数
+program.parse();

package/lib/commands/doctor.js

@@ -0,0 +1,59 @@
+const chalk = require('chalk');
+const pythonChecker = require('../python-checker');
+const { getI18n } = require('../i18n');
+
+/**
+ * CLI Doctor Command Component
+ * 
+ * Verifies system requirements and provides diagnostics.
+ * Checks Node.js version and Python availability.
+ * 
+ * Requirements: 7.5
+ */
+function doctorCommand() {
+  const i18n = getI18n();
+  
+  console.log(chalk.red('🔥') + ' ' + i18n.t('cli.commands.doctor.title'));
+  console.log();
+  console.log(i18n.t('cli.commands.doctor.checking'));
+  console.log();
+  
+  // Check Node.js version
+  const nodeVersion = process.version;
+  const nodeStatus = chalk.green('✓');
+  console.log(`${nodeStatus} ${i18n.t('cli.commands.doctor.nodejs')}: ${chalk.cyan(nodeVersion)}`);
+  
+  // Check Python availability
+  const pythonStatus = pythonChecker.checkPython();
+  
+  if (pythonStatus.available) {
+    const pythonOk = chalk.green('✓');
+    console.log(`${pythonOk} ${i18n.t('cli.commands.doctor.python')}: ${chalk.cyan(pythonStatus.version)}`);
+  } else {
+    const pythonFail = chalk.red('✗');
+    console.log(`${pythonFail} ${i18n.t('cli.commands.doctor.python')}: ${chalk.yellow(pythonStatus.message)}`);
+    console.log();
+    console.log(chalk.yellow(i18n.t('cli.commands.doctor.python_note')));
+    console.log();
+    console.log(chalk.blue(i18n.t('python.install_header')));
+    console.log(pythonChecker.getInstallInstructions());
+  }
+  
+  console.log();
+  console.log(chalk.blue('─'.repeat(60)));
+  console.log();
+  
+  // Summary
+  if (pythonStatus.available) {
+    console.log(chalk.green('✅ ' + i18n.t('cli.commands.doctor.all_good')));
+    console.log(i18n.t('cli.commands.doctor.ready'));
+  } else {
+    console.log(chalk.yellow('⚠️  ' + i18n.t('cli.commands.doctor.python_missing')));
+    console.log(i18n.t('cli.commands.doctor.basic_features'));
+    console.log(i18n.t('cli.commands.doctor.ultrawork_unavailable'));
+  }
+  
+  console.log();
+}
+
+module.exports = doctorCommand;

package/lib/i18n.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+
+class I18n {
+  constructor() {
+    this.locale = this.detectLocale();
+    this.messages = this.loadMessages(this.locale);
+  }
+
+  detectLocale() {
+    // 优先级: 环境变量 > 系统语言 > 默认英文
+    const envLocale = process.env.KIRO_LANG || process.env.LANG;
+    
+    if (envLocale) {
+      if (envLocale.startsWith('zh')) return 'zh';
+      if (envLocale.startsWith('en')) return 'en';
+    }
+
+    // 检测系统语言
+    const systemLocale = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (systemLocale.startsWith('zh')) return 'zh';
+    
+    return 'en'; // 默认英文
+  }
+
+  loadMessages(locale) {
+    try {
+      const messagesPath = path.join(__dirname, '../locales', `${locale}.json`);
+      return JSON.parse(fs.readFileSync(messagesPath, 'utf8'));
+    } catch (error) {
+      // 如果加载失败，回退到英文
+      const fallbackPath = path.join(__dirname, '../locales', 'en.json');
+      return JSON.parse(fs.readFileSync(fallbackPath, 'utf8'));
+    }
+  }
+
+  t(key, params = {}) {
+    const keys = key.split('.');
+    let value = this.messages;
+
+    for (const k of keys) {
+      if (value && typeof value === 'object') {
+        value = value[k];
+      } else {
+        return key; // 如果找不到，返回 key 本身
+      }
+    }
+
+    // 替换参数
+    if (typeof value === 'string') {
+      return value.replace(/\{(\w+)\}/g, (match, param) => {
+        return params[param] !== undefined ? params[param] : match;
+      });
+    }
+
+    return value || key;
+  }
+
+  setLocale(locale) {
+    this.locale = locale;
+    this.messages = this.loadMessages(locale);
+  }
+
+  getLocale() {
+    return this.locale;
+  }
+}
+
+// 单例模式
+let instance = null;
+
+function getI18n() {
+  if (!instance) {
+    instance = new I18n();
+  }
+  return instance;
+}
+
+module.exports = { getI18n, I18n };

package/lib/python-checker.js

@@ -0,0 +1,209 @@
+const { execSync } = require('child_process');
+const { getI18n } = require('./i18n');
+
+/**
+ * Python Dependency Detection Component
+ * 
+ * Detects Python availability and provides user guidance for installation.
+ * Supports Windows, Linux, and macOS platforms.
+ * 
+ * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5
+ */
+class PythonChecker {
+  constructor() {
+    this.minMajor = 3;
+    this.minMinor = 8;
+  }
+
+  /**
+   * Check if Python is available and meets version requirements
+   * 
+   * @returns {Object} { available: boolean, version: string|null, message: string }
+   * 
+   * Requirements:
+   * - 3.1: Verify Python availability before executing Python code
+   * - 3.4: Detect Python 3.8 or higher
+   * - 3.5: Inform user of minimum required version when too old
+   */
+  checkPython() {
+    const i18n = getI18n();
+    
+    try {
+      // Try to execute python --version
+      const versionOutput = execSync('python --version', { 
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      
+      const parsed = this.parseVersion(versionOutput);
+      
+      if (!parsed) {
+        return {
+          available: false,
+          version: versionOutput,
+          message: i18n.t('python.malformed_version', { version: versionOutput })
+        };
+      }
+      
+      const { major, minor, patch } = parsed;
+      const meetsRequirement = this.meetsVersionRequirement(major, minor);
+      
+      if (meetsRequirement) {
+        return {
+          available: true,
+          version: `Python ${major}.${minor}.${patch}`,
+          message: i18n.t('python.available', { version: `${major}.${minor}.${patch}` })
+        };
+      } else {
+        return {
+          available: false,
+          version: `Python ${major}.${minor}.${patch}`,
+          message: i18n.t('python.version_too_old', { 
+            version: `${major}.${minor}.${patch}`, 
+            required: `${this.minMajor}.${this.minMinor}+` 
+          })
+        };
+      }
+    } catch (error) {
+      // Python not found or command failed
+      return {
+        available: false,
+        version: null,
+        message: i18n.t('python.not_found')
+      };
+    }
+  }
+
+  /**
+   * Parse Python version string to extract version numbers
+   * 
+   * @param {string} versionString - Python version output (e.g., "Python 3.10.0")
+   * @returns {Object|null} { major, minor, patch, meetsRequirement } or null if parsing fails
+   * 
+   * Requirements:
+   * - 3.4: Extract version numbers for comparison
+   */
+  parseVersion(versionString) {
+    if (!versionString || typeof versionString !== 'string') {
+      return null;
+    }
+    
+    // Match pattern: Python X.Y.Z
+    const versionMatch = versionString.match(/Python\s+(\d+)\.(\d+)\.(\d+)/i);
+    
+    if (!versionMatch) {
+      return null;
+    }
+    
+    const major = parseInt(versionMatch[1], 10);
+    const minor = parseInt(versionMatch[2], 10);
+    const patch = parseInt(versionMatch[3], 10);
+    
+    if (isNaN(major) || isNaN(minor) || isNaN(patch)) {
+      return null;
+    }
+    
+    return {
+      major,
+      minor,
+      patch,
+      meetsRequirement: this.meetsVersionRequirement(major, minor)
+    };
+  }
+
+  /**
+   * Check if version meets minimum requirement (3.8+)
+   * 
+   * @param {number} major - Major version number
+   * @param {number} minor - Minor version number
+   * @returns {boolean} True if version meets requirement
+   */
+  meetsVersionRequirement(major, minor) {
+    if (major > this.minMajor) {
+      return true;
+    }
+    if (major === this.minMajor && minor >= this.minMinor) {
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get installation instructions for the current OS
+   * 
+   * @returns {string} OS-specific installation instructions
+   * 
+   * Requirements:
+   * - 3.3: Provide installation instructions for user's operating system
+   */
+  getInstallInstructions() {
+    const i18n = getI18n();
+    const platform = process.platform;
+    
+    // Map platform to locale key
+    const platformKey = this.getPlatformKey(platform);
+    
+    // Try to get platform-specific instructions
+    const instructions = i18n.t(`python.install.${platformKey}`);
+    
+    // If translation not found (returns key), use default
+    if (instructions === `python.install.${platformKey}`) {
+      return i18n.t('python.install.default');
+    }
+    
+    return instructions;
+  }
+
+  /**
+   * Map Node.js platform identifier to locale key
+   * 
+   * @param {string} platform - process.platform value
+   * @returns {string} Platform key for locale lookup
+   */
+  getPlatformKey(platform) {
+    switch (platform) {
+      case 'win32':
+        return 'windows';
+      case 'darwin':
+        return 'macos';
+      case 'linux':
+        return 'linux';
+      default:
+        return 'default';
+    }
+  }
+
+  /**
+   * Get friendly error message when Python is not available
+   * 
+   * @returns {string} User-friendly error message with installation guidance
+   * 
+   * Requirements:
+   * - 3.2: Display friendly error message in user's language
+   * - 3.3: Provide installation instructions
+   */
+  getErrorMessage() {
+    const i18n = getI18n();
+    const status = this.checkPython();
+    
+    if (status.available) {
+      return null; // No error
+    }
+    
+    const errorLines = [
+      i18n.t('python.error_header'),
+      '',
+      status.message,
+      '',
+      i18n.t('python.install_header'),
+      this.getInstallInstructions(),
+      '',
+      i18n.t('python.help_footer')
+    ];
+    
+    return errorLines.join('\n');
+  }
+}
+
+// Export singleton instance
+module.exports = new PythonChecker();

package/locales/en.json

@@ -0,0 +1,114 @@
+{
+  "cli": {
+    "name": "kiro-spec-engine",
+    "description": "🔥 Kiro Spec Engine - Spec-driven development with steering rules",
+    "commands": {
+      "init": {
+        "description": "Initialize a new Kiro Ultrawork project",
+        "projectNamePrompt": "Enter project name:",
+        "forceOption": "Force initialization even if .kiro directory exists",
+        "alreadyExists": "⚠️  .kiro directory already exists",
+        "overwritePrompt": "Do you want to overwrite it?",
+        "cancelled": "Initialization cancelled.",
+        "success": "🎉 Kiro Ultrawork project initialized successfully!",
+        "nextSteps": "📋 Next steps:",
+        "step1": "Create your first spec: mkdir .kiro/specs/01-00-your-feature",
+        "step2": "Write basic requirements.md",
+        "step3": "Enhance with Ultrawork: kiro-spec-engine enhance requirements .kiro/specs/01-00-your-feature/requirements.md",
+        "startJourney": "🔥 Start your Ultrawork journey!",
+        "error": "❌ Error initializing project:"
+      },
+      "enhance": {
+        "description": "Enhance document quality with Ultrawork spirit",
+        "starting": "🔥 Starting {stage} stage Ultrawork enhancement...",
+        "toolNotFound": "❌ Ultrawork tool not found. Please run: kiro-spec-engine init",
+        "completed": "✅ Ultrawork enhancement completed!",
+        "failed": "❌ Enhancement failed with code:",
+        "pythonError": "❌ Error running Python tool:",
+        "pythonTip": "💡 Make sure Python 3.8+ is installed and in PATH"
+      },
+      "createSpec": {
+        "description": "Create a new spec directory",
+        "success": "✅ Created spec directory:",
+        "nextSteps": "📋 Next steps:",
+        "step1": "Create requirements.md in the spec directory",
+        "step2": "Enhance with: kiro-spec-engine enhance requirements {specPath}/requirements.md",
+        "error": "❌ Error creating spec:"
+      },
+      "status": {
+        "description": "Check project status and available specs",
+        "noProject": "⚠️  No Kiro Ultrawork project found in current directory",
+        "initTip": "Run: kiro-spec-engine init to initialize",
+        "title": "🔥 Kiro Ultrawork Project Status",
+        "toolStatus": "Ultrawork Tool:",
+        "available": "✅ Available",
+        "missing": "❌ Missing",
+        "specsTitle": "📋 Available Specs:",
+        "noSpecs": "No specs found",
+        "requirements": "Requirements:",
+        "design": "Design:",
+        "tasks": "Tasks:"
+      },
+      "doctor": {
+        "description": "Check system requirements and diagnostics",
+        "title": "System Diagnostics",
+        "checking": "Checking system requirements...",
+        "nodejs": "Node.js",
+        "python": "Python",
+        "python_note": "Note: Python is required for Ultrawork quality enhancement features.",
+        "all_good": "All system requirements are met!",
+        "ready": "You're ready to use all Kiro Spec Engine features including Ultrawork enhancements.",
+        "python_missing": "Python is not available",
+        "basic_features": "Basic CLI features (init, status, create-spec) will work normally.",
+        "ultrawork_unavailable": "Ultrawork enhancement features require Python 3.8 or higher."
+      }
+    }
+  },
+  "ultrawork": {
+    "spirit": {
+      "title": "🔥 Ultrawork Spirit",
+      "subtitle": "Like Sisyphus pushing the boulder up the mountain",
+      "principles": {
+        "relentless": "Never give up, relentless effort",
+        "excellence": "Pursue professional-grade quality",
+        "improvement": "Continuous improvement and optimization",
+        "completion": "Perfect completion of every task"
+      }
+    },
+    "quality": {
+      "scoring": "Quality Scoring: {score}/10",
+      "professional": "✅ Document has reached professional standards!",
+      "improving": "🔄 Round {iteration} improvement: {improvements}",
+      "noImprovements": "⚠️ No more improvements identified, stopping iteration",
+      "scoreNotImproved": "⚠️ Quality score not improved, stopping iteration"
+    },
+    "stages": {
+      "requirements": "Requirements",
+      "design": "Design", 
+      "tasks": "Tasks"
+    }
+  },
+  "messages": {
+    "success": "✅ Success",
+    "error": "❌ Error",
+    "warning": "⚠️ Warning",
+    "info": "💡 Info",
+    "processing": "🔄 Processing",
+    "completed": "🎉 Completed"
+  },
+  "python": {
+    "available": "Python {version} is available",
+    "not_found": "Python is not installed or not found in PATH",
+    "version_too_old": "Python {version} is installed, but version {required} or higher is required",
+    "malformed_version": "Unable to parse Python version: {version}",
+    "error_header": "✗ Python is required for Ultrawork quality enhancement features",
+    "install_header": "Installation instructions:",
+    "help_footer": "For more help, visit: https://github.com/USERNAME/kiro-spec-engine#python-setup",
+    "install": {
+      "windows": "Windows:\n1. Download Python from https://www.python.org/downloads/\n2. Run the installer and check 'Add Python to PATH'\n3. Restart your terminal and run: python --version",
+      "macos": "macOS:\n1. Install Homebrew if not already installed: /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n2. Install Python: brew install python\n3. Verify installation: python3 --version",
+      "linux": "Linux:\n1. Ubuntu/Debian: sudo apt-get update && sudo apt-get install python3 python3-pip\n2. Fedora/RHEL: sudo dnf install python3 python3-pip\n3. Verify installation: python3 --version",
+      "default": "Please visit https://www.python.org/downloads/ to download and install Python 3.8 or higher for your operating system."
+    }
+  }
+}