kiro-spec-engine 1.1.0 → 1.2.1

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.1.0",
+  "version": "1.2.1",
   "description": "Kiro Spec Engine - A spec-driven development engine with steering rules and quality enhancement powered by Ultrawork spirit",
   "main": "index.js",
   "bin": {