kiro-spec-engine 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-01-23
+
+### Added
+- **User Documentation**: Comprehensive guides for adoption and upgrade workflows
+  - `docs/adoption-guide.md`: Complete guide for adopting existing projects
+  - `docs/upgrade-guide.md`: Complete guide for upgrading project versions
+  - Step-by-step instructions with examples
+  - Troubleshooting sections for common issues
+  - Best practices and recommendations
+
+### Enhanced
+- Improved documentation structure for better user experience
+- Added practical examples for all adoption modes
+- Added detailed upgrade scenarios with migration examples
+
+## [1.2.1] - 2026-01-23
+
+### Added
+- **Validation System**: Comprehensive project validation
+  - `validateProjectStructure()`: Check required files and directories
+  - `validateVersionFile()`: Verify version.json structure
+  - `validateDependencies()`: Check Node.js and Python versions
+  - `validateProject()`: Complete project validation
+- **Automatic Version Checking**: Detect version mismatches
+  - VersionChecker class for automatic version detection
+  - Warning display when project version differs from installed kse
+  - `--no-version-check` flag to suppress warnings
+  - `kse version-info` command for detailed version information
+- **Enhanced Testing**: Added tests for validation and version checking
+  - 7 new unit tests for validation system
+  - 4 new unit tests for version checker
+  - Total: 25 tests passing
+
+### Enhanced
+- CLI now checks for version mismatches before command execution
+- Better error messages for validation failures
+- Improved user experience with version information display
+
 ## [1.2.0] - 2026-01-23
 
 ### Added

package/bin/kiro-spec-engine.js

@@ -11,6 +11,7 @@ const doctorCommand = require('../lib/commands/doctor');
 const adoptCommand = require('../lib/commands/adopt');
 const upgradeCommand = require('../lib/commands/upgrade');
 const rollbackCommand = require('../lib/commands/rollback');
+const VersionChecker = require('../lib/version/version-checker');
 
 const i18n = getI18n();
 const t = (key, params) => i18n.t(key, params);
@@ -18,6 +19,19 @@ const t = (key, params) => i18n.t(key, params);
 // Read version from package.json
 const packageJson = require('../package.json');
 
+// Create version checker instance
+const versionChecker = new VersionChecker();
+
+// Helper function to check version before command execution
+async function checkVersionBeforeCommand(options = {}) {
+  const projectPath = process.cwd();
+  const noVersionCheck = options.noVersionCheck || false;
+  
+  if (!noVersionCheck) {
+    await versionChecker.checkVersion(projectPath, { noVersionCheck });
+  }
+}
+
 const program = new Command();
 
 // 版本和基本信息
@@ -27,7 +41,8 @@ program
   .version(packageJson.version, '-v, --version', 'Display version number')
   .option('-l, --lang <locale>', 'Set language (en/zh)', (locale) => {
     i18n.setLocale(locale);
-  });
+  })
+  .option('--no-version-check', 'Suppress version mismatch warnings');
 
 // 初始化项目命令
 program
@@ -240,6 +255,15 @@ program
     }
   });
 
+// 版本信息命令
+program
+  .command('version-info')
+  .description('Display detailed version information')
+  .action(async () => {
+    const projectPath = process.cwd();
+    await versionChecker.displayVersionInfo(projectPath);
+  });
+
 // 更新项目配置的辅助函数
 async function updateProjectConfig(projectName) {
   const envPath = path.join(process.cwd(), '.kiro/steering/ENVIRONMENT.md');

package/lib/utils/validation.js

@@ -0,0 +1,306 @@
+/**
+ * Validation Utilities
+ * 
+ * Provides validation functions for project structure, version files,
+ * and dependencies. Used for post-operation validation.
+ */
+
+const path = require('path');
+const { pathExists, readJSON } = require('./fs-utils');
+const { spawn } = require('child_process');
+
+/**
+ * Validates project structure
+ * Checks if all required files and directories exist
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Promise<ValidationResult>}
+ */
+async function validateProjectStructure(projectPath) {
+  const errors = [];
+  const warnings = [];
+  
+  try {
+    const kiroPath = path.join(projectPath, '.kiro');
+    
+    // Check if .kiro/ directory exists
+    const kiroExists = await pathExists(kiroPath);
+    if (!kiroExists) {
+      errors.push('.kiro/ directory not found');
+      return { success: false, errors, warnings };
+    }
+    
+    // Check required directories
+    const requiredDirs = [
+      { path: 'specs', required: false },
+      { path: 'steering', required: true },
+      { path: 'tools', required: true },
+      { path: 'backups', required: false }
+    ];
+    
+    for (const dir of requiredDirs) {
+      const dirPath = path.join(kiroPath, dir.path);
+      const exists = await pathExists(dirPath);
+      
+      if (!exists) {
+        if (dir.required) {
+          errors.push(`Required directory not found: ${dir.path}/`);
+        } else {
+          warnings.push(`Optional directory not found: ${dir.path}/`);
+        }
+      }
+    }
+    
+    // Check required steering files
+    const requiredSteeringFiles = [
+      { path: 'steering/CORE_PRINCIPLES.md', required: true },
+      { path: 'steering/ENVIRONMENT.md', required: true },
+      { path: 'steering/CURRENT_CONTEXT.md', required: true },
+      { path: 'steering/RULES_GUIDE.md', required: true }
+    ];
+    
+    for (const file of requiredSteeringFiles) {
+      const filePath = path.join(kiroPath, file.path);
+      const exists = await pathExists(filePath);
+      
+      if (!exists) {
+        if (file.required) {
+          errors.push(`Required file not found: ${file.path}`);
+        } else {
+          warnings.push(`Optional file not found: ${file.path}`);
+        }
+      }
+    }
+    
+    // Check required tool files
+    const requiredToolFiles = [
+      { path: 'tools/ultrawork_enhancer.py', required: true }
+    ];
+    
+    for (const file of requiredToolFiles) {
+      const filePath = path.join(kiroPath, file.path);
+      const exists = await pathExists(filePath);
+      
+      if (!exists) {
+        if (file.required) {
+          warnings.push(`Tool file not found: ${file.path}`);
+        }
+      }
+    }
+    
+    return {
+      success: errors.length === 0,
+      errors,
+      warnings
+    };
+  } catch (error) {
+    errors.push(`Validation failed: ${error.message}`);
+    return { success: false, errors, warnings };
+  }
+}
+
+/**
+ * Validates version.json file structure
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Promise<ValidationResult>}
+ */
+async function validateVersionFile(projectPath) {
+  const errors = [];
+  const warnings = [];
+  
+  try {
+    const versionPath = path.join(projectPath, '.kiro', 'version.json');
+    
+    // Check if version.json exists
+    const exists = await pathExists(versionPath);
+    if (!exists) {
+      errors.push('version.json not found');
+      return { success: false, errors, warnings };
+    }
+    
+    // Read and validate structure
+    const versionInfo = await readJSON(versionPath);
+    
+    // Check required fields
+    const requiredFields = [
+      'kse-version',
+      'template-version',
+      'created',
+      'last-upgraded',
+      'upgrade-history'
+    ];
+    
+    for (const field of requiredFields) {
+      if (!(field in versionInfo)) {
+        errors.push(`Missing required field in version.json: ${field}`);
+      }
+    }
+    
+    // Validate field types
+    if (versionInfo['kse-version'] && typeof versionInfo['kse-version'] !== 'string') {
+      errors.push('kse-version must be a string');
+    }
+    
+    if (versionInfo['template-version'] && typeof versionInfo['template-version'] !== 'string') {
+      errors.push('template-version must be a string');
+    }
+    
+    if (versionInfo['upgrade-history'] && !Array.isArray(versionInfo['upgrade-history'])) {
+      errors.push('upgrade-history must be an array');
+    }
+    
+    // Validate upgrade history entries
+    if (Array.isArray(versionInfo['upgrade-history'])) {
+      versionInfo['upgrade-history'].forEach((entry, index) => {
+        if (!entry.from || !entry.to || !entry.date || typeof entry.success !== 'boolean') {
+          warnings.push(`Invalid upgrade history entry at index ${index}`);
+        }
+      });
+    }
+    
+    return {
+      success: errors.length === 0,
+      errors,
+      warnings
+    };
+  } catch (error) {
+    errors.push(`Failed to validate version.json: ${error.message}`);
+    return { success: false, errors, warnings };
+  }
+}
+
+/**
+ * Validates dependencies (Node.js and Python versions)
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Promise<ValidationResult>}
+ */
+async function validateDependencies(projectPath) {
+  const errors = [];
+  const warnings = [];
+  
+  try {
+    // Check Node.js version
+    const nodeVersion = process.version;
+    const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0]);
+    
+    if (nodeMajor < 16) {
+      errors.push(`Node.js version ${nodeVersion} is not supported. Requires Node.js 16+`);
+    }
+    
+    // Check Python version (if Ultrawork tools are present)
+    const toolPath = path.join(projectPath, '.kiro/tools/ultrawork_enhancer.py');
+    const toolExists = await pathExists(toolPath);
+    
+    if (toolExists) {
+      try {
+        const pythonVersion = await checkPythonVersion();
+        
+        if (!pythonVersion) {
+          warnings.push('Python not found. Ultrawork tools require Python 3.8+');
+        } else {
+          const [major, minor] = pythonVersion.split('.').map(Number);
+          
+          if (major < 3 || (major === 3 && minor < 8)) {
+            warnings.push(`Python ${pythonVersion} found. Ultrawork tools require Python 3.8+`);
+          }
+        }
+      } catch (error) {
+        warnings.push('Could not check Python version');
+      }
+    }
+    
+    return {
+      success: errors.length === 0,
+      errors,
+      warnings
+    };
+  } catch (error) {
+    errors.push(`Failed to validate dependencies: ${error.message}`);
+    return { success: false, errors, warnings };
+  }
+}
+
+/**
+ * Checks Python version
+ * 
+ * @returns {Promise<string|null>} - Python version string or null if not found
+ */
+function checkPythonVersion() {
+  return new Promise((resolve) => {
+    const python = spawn('python', ['--version']);
+    let output = '';
+    
+    python.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+    
+    python.stderr.on('data', (data) => {
+      output += data.toString();
+    });
+    
+    python.on('close', (code) => {
+      if (code === 0 && output) {
+        // Extract version number from "Python 3.x.x"
+        const match = output.match(/Python (\d+\.\d+\.\d+)/);
+        if (match) {
+          resolve(match[1]);
+        } else {
+          resolve(null);
+        }
+      } else {
+        resolve(null);
+      }
+    });
+    
+    python.on('error', () => {
+      resolve(null);
+    });
+    
+    // Timeout after 5 seconds
+    setTimeout(() => {
+      python.kill();
+      resolve(null);
+    }, 5000);
+  });
+}
+
+/**
+ * Validates complete project (structure + version + dependencies)
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @returns {Promise<ValidationResult>}
+ */
+async function validateProject(projectPath) {
+  const allErrors = [];
+  const allWarnings = [];
+  
+  // Run all validations
+  const structureResult = await validateProjectStructure(projectPath);
+  const versionResult = await validateVersionFile(projectPath);
+  const depsResult = await validateDependencies(projectPath);
+  
+  // Combine results
+  allErrors.push(...structureResult.errors);
+  allErrors.push(...versionResult.errors);
+  allErrors.push(...depsResult.errors);
+  
+  allWarnings.push(...structureResult.warnings);
+  allWarnings.push(...versionResult.warnings);
+  allWarnings.push(...depsResult.warnings);
+  
+  return {
+    success: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings
+  };
+}
+
+module.exports = {
+  validateProjectStructure,
+  validateVersionFile,
+  validateDependencies,
+  validateProject,
+  checkPythonVersion
+};

package/lib/version/version-checker.js

@@ -0,0 +1,156 @@
+/**
+ * Version Checker
+ * 
+ * Automatically detects version mismatches between project and installed kse.
+ * Displays warnings and upgrade suggestions.
+ */
+
+const chalk = require('chalk');
+const VersionManager = require('./version-manager');
+
+class VersionChecker {
+  constructor() {
+    this.versionManager = new VersionManager();
+    this.suppressWarnings = false;
+  }
+
+  /**
+   * Checks for version mismatch and displays warning if needed
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {Object} options - Check options
+   * @param {boolean} options.noVersionCheck - Suppress warnings
+   * @returns {Promise<VersionCheckResult>}
+   */
+  async checkVersion(projectPath, options = {}) {
+    const { noVersionCheck = false } = options;
+    
+    if (noVersionCheck || this.suppressWarnings) {
+      return { mismatch: false, shouldUpgrade: false };
+    }
+    
+    try {
+      // Read project version
+      const projectVersionInfo = await this.versionManager.readVersion(projectPath);
+      
+      if (!projectVersionInfo) {
+        // No version.json - project might not be initialized
+        return { mismatch: false, shouldUpgrade: false };
+      }
+      
+      const projectVersion = projectVersionInfo['kse-version'];
+      
+      // Get current kse version
+      const packageJson = require('../../package.json');
+      const kseVersion = packageJson.version;
+      
+      // Check if upgrade is needed
+      const needsUpgrade = this.versionManager.needsUpgrade(projectVersion, kseVersion);
+      
+      if (needsUpgrade) {
+        this.displayWarning(projectVersion, kseVersion);
+      }
+      
+      return {
+        mismatch: needsUpgrade,
+        shouldUpgrade: needsUpgrade,
+        projectVersion,
+        kseVersion
+      };
+    } catch (error) {
+      // Silently fail - don't block commands if version check fails
+      return { mismatch: false, shouldUpgrade: false, error: error.message };
+    }
+  }
+
+  /**
+   * Displays version mismatch warning
+   * 
+   * @param {string} projectVersion - Project version
+   * @param {string} kseVersion - Current kse version
+   */
+  displayWarning(projectVersion, kseVersion) {
+    console.log();
+    console.log(chalk.yellow('⚠️  Version Mismatch Detected'));
+    console.log(chalk.gray('  Project initialized with kse'), chalk.cyan(`v${projectVersion}`));
+    console.log(chalk.gray('  Current kse version:'), chalk.cyan(`v${kseVersion}`));
+    console.log();
+    console.log(chalk.blue('💡 Tip:'), chalk.gray('Run'), chalk.cyan('kse upgrade'), chalk.gray('to update project templates'));
+    console.log(chalk.gray('  Or use'), chalk.cyan('--no-version-check'), chalk.gray('to suppress this warning'));
+    console.log();
+  }
+
+  /**
+   * Checks version and displays detailed information
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<void>}
+   */
+  async displayVersionInfo(projectPath) {
+    try {
+      const projectVersionInfo = await this.versionManager.readVersion(projectPath);
+      
+      if (!projectVersionInfo) {
+        console.log(chalk.yellow('⚠️  No version information found'));
+        console.log(chalk.gray('  This project may not be initialized with kse'));
+        console.log(chalk.gray('  Run'), chalk.cyan('kse adopt'), chalk.gray('to adopt this project'));
+        return;
+      }
+      
+      const packageJson = require('../../package.json');
+      const kseVersion = packageJson.version;
+      
+      console.log(chalk.blue('📦 Version Information'));
+      console.log();
+      console.log(chalk.gray('Project:'));
+      console.log(`  kse version: ${chalk.cyan(projectVersionInfo['kse-version'])}`);
+      console.log(`  Template version: ${chalk.cyan(projectVersionInfo['template-version'])}`);
+      console.log(`  Created: ${chalk.gray(new Date(projectVersionInfo.created).toLocaleString())}`);
+      console.log(`  Last upgraded: ${chalk.gray(new Date(projectVersionInfo['last-upgraded']).toLocaleString())}`);
+      
+      console.log();
+      console.log(chalk.gray('Installed:'));
+      console.log(`  kse version: ${chalk.cyan(kseVersion)}`);
+      
+      if (projectVersionInfo['upgrade-history'].length > 0) {
+        console.log();
+        console.log(chalk.gray('Upgrade History:'));
+        projectVersionInfo['upgrade-history'].forEach((entry, index) => {
+          const icon = entry.success ? chalk.green('✅') : chalk.red('❌');
+          const date = new Date(entry.date).toLocaleString();
+          console.log(`  ${icon} ${entry.from} → ${entry.to} (${date})`);
+          if (entry.error) {
+            console.log(`     ${chalk.red('Error:')} ${entry.error}`);
+          }
+        });
+      }
+      
+      console.log();
+      
+      const needsUpgrade = this.versionManager.needsUpgrade(
+        projectVersionInfo['kse-version'],
+        kseVersion
+      );
+      
+      if (needsUpgrade) {
+        console.log(chalk.yellow('⚠️  Upgrade available'));
+        console.log(chalk.gray('  Run'), chalk.cyan('kse upgrade'), chalk.gray('to update to'), chalk.cyan(`v${kseVersion}`));
+      } else {
+        console.log(chalk.green('✅ Project is up to date'));
+      }
+    } catch (error) {
+      console.log(chalk.red('❌ Error:'), error.message);
+    }
+  }
+
+  /**
+   * Suppresses version check warnings
+   * 
+   * @param {boolean} suppress - Whether to suppress warnings
+   */
+  setSuppressWarnings(suppress) {
+    this.suppressWarnings = suppress;
+  }
+}
+
+module.exports = VersionChecker;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Kiro Spec Engine - A spec-driven development engine with steering rules and quality enhancement powered by Ultrawork spirit",
   "main": "index.js",
   "bin": {