kiro-spec-engine 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -7,21 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-01-23
+
 ### Added
-- Initial project structure
-- CLI implementation with Node.js
-- Ultrawork quality enhancement tool (Python)
-- Multi-language support (English and Chinese)
-- Project initialization command (`kse init`)
-- Spec creation command (`kse create-spec`)
-- Status checking command (`kse status`)
-- Document enhancement command (`kse enhance`)
+- Version management system for project adoption and upgrades
+- VersionManager class for tracking project versions
+- Compatibility matrix for version compatibility checking
+- Upgrade path calculation for incremental upgrades
+- Safe file system utilities with atomic operations
+- Path validation to prevent path traversal attacks
+- Project structure for future adoption/upgrade features
+
+### Infrastructure
+- Added semver dependency for version comparison
+- Created lib/version/ directory for version management
+- Created lib/utils/ directory for shared utilities
+- Prepared foundation for kse adopt and kse upgrade commands
 
 ### Documentation
-- README.md (English)
-- README.zh.md (Chinese)
-- CONTRIBUTING.md
-- LICENSE (MIT)
+- Created spec 02-00-project-adoption-and-upgrade
+- Comprehensive design for project adoption system
+- Detailed requirements for smooth upgrade experience
 
 ## [1.0.0] - 2026-01-23
 

package/lib/utils/fs-utils.js

@@ -0,0 +1,274 @@
+/**
+ * File System Utilities
+ * 
+ * Provides safe, atomic file operations for the adoption/upgrade system.
+ * Implements path validation, atomic writes, and error handling.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Validates that a file path is within the project directory
+ * Prevents path traversal attacks
+ * 
+ * @param {string} projectPath - Absolute path to project root
+ * @param {string} filePath - Relative or absolute file path to validate
+ * @returns {string} - Validated absolute path
+ * @throws {Error} - If path traversal is detected
+ */
+function validatePath(projectPath, filePath) {
+  const resolvedProject = path.resolve(projectPath);
+  const resolvedFile = path.resolve(projectPath, filePath);
+  
+  if (!resolvedFile.startsWith(resolvedProject)) {
+    throw new Error(`Path traversal detected: ${filePath} is outside project directory`);
+  }
+  
+  return resolvedFile;
+}
+
+/**
+ * Atomically writes content to a file
+ * Uses temp file + rename for atomicity
+ * 
+ * @param {string} filePath - Absolute path to target file
+ * @param {string} content - Content to write
+ * @returns {Promise<void>}
+ */
+async function atomicWrite(filePath, content) {
+  const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).substr(2, 9)}`;
+  
+  try {
+    // Write to temp file
+    await fs.writeFile(tempPath, content, 'utf8');
+    
+    // Atomic rename (on most systems)
+    await fs.rename(tempPath, filePath);
+  } catch (error) {
+    // Clean up temp file if it exists
+    try {
+      await fs.unlink(tempPath);
+    } catch (cleanupError) {
+      // Ignore cleanup errors
+    }
+    
+    throw new Error(`Failed to write file atomically: ${error.message}`);
+  }
+}
+
+/**
+ * Safely copies a file with error handling
+ * Creates parent directories if needed
+ * 
+ * @param {string} sourcePath - Absolute path to source file
+ * @param {string} destPath - Absolute path to destination file
+ * @param {Object} options - Copy options
+ * @param {boolean} options.overwrite - Whether to overwrite existing file (default: false)
+ * @returns {Promise<void>}
+ */
+async function safeCopy(sourcePath, destPath, options = {}) {
+  const { overwrite = false } = options;
+  
+  try {
+    // Check if source exists
+    const sourceExists = await fs.pathExists(sourcePath);
+    if (!sourceExists) {
+      throw new Error(`Source file does not exist: ${sourcePath}`);
+    }
+    
+    // Check if destination exists
+    const destExists = await fs.pathExists(destPath);
+    if (destExists && !overwrite) {
+      throw new Error(`Destination file already exists: ${destPath}`);
+    }
+    
+    // Ensure parent directory exists
+    const parentDir = path.dirname(destPath);
+    await fs.ensureDir(parentDir);
+    
+    // Copy file
+    await fs.copy(sourcePath, destPath, { overwrite });
+  } catch (error) {
+    throw new Error(`Failed to copy file: ${error.message}`);
+  }
+}
+
+/**
+ * Recursively creates a directory
+ * Safe to call even if directory already exists
+ * 
+ * @param {string} dirPath - Absolute path to directory
+ * @returns {Promise<void>}
+ */
+async function ensureDirectory(dirPath) {
+  try {
+    await fs.ensureDir(dirPath);
+  } catch (error) {
+    throw new Error(`Failed to create directory: ${error.message}`);
+  }
+}
+
+/**
+ * Recursively copies a directory
+ * 
+ * @param {string} sourceDir - Absolute path to source directory
+ * @param {string} destDir - Absolute path to destination directory
+ * @param {Object} options - Copy options
+ * @param {boolean} options.overwrite - Whether to overwrite existing files (default: false)
+ * @param {Function} options.filter - Filter function (path) => boolean
+ * @returns {Promise<void>}
+ */
+async function copyDirectory(sourceDir, destDir, options = {}) {
+  const { overwrite = false, filter = null } = options;
+  
+  try {
+    await fs.copy(sourceDir, destDir, {
+      overwrite,
+      filter: filter || (() => true)
+    });
+  } catch (error) {
+    throw new Error(`Failed to copy directory: ${error.message}`);
+  }
+}
+
+/**
+ * Checks if a path exists
+ * 
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(filePath) {
+  return fs.pathExists(filePath);
+}
+
+/**
+ * Reads a JSON file safely
+ * 
+ * @param {string} filePath - Absolute path to JSON file
+ * @returns {Promise<Object>} - Parsed JSON object
+ * @throws {Error} - If file doesn't exist or JSON is invalid
+ */
+async function readJSON(filePath) {
+  try {
+    return await fs.readJSON(filePath);
+  } catch (error) {
+    throw new Error(`Failed to read JSON file: ${error.message}`);
+  }
+}
+
+/**
+ * Writes a JSON file atomically
+ * 
+ * @param {string} filePath - Absolute path to JSON file
+ * @param {Object} data - Data to write
+ * @param {Object} options - Write options
+ * @param {number} options.spaces - Number of spaces for indentation (default: 2)
+ * @returns {Promise<void>}
+ */
+async function writeJSON(filePath, data, options = {}) {
+  const { spaces = 2 } = options;
+  const content = JSON.stringify(data, null, spaces);
+  await atomicWrite(filePath, content);
+}
+
+/**
+ * Removes a file or directory
+ * 
+ * @param {string} targetPath - Path to remove
+ * @returns {Promise<void>}
+ */
+async function remove(targetPath) {
+  try {
+    await fs.remove(targetPath);
+  } catch (error) {
+    throw new Error(`Failed to remove path: ${error.message}`);
+  }
+}
+
+/**
+ * Gets file stats
+ * 
+ * @param {string} filePath - Path to file
+ * @returns {Promise<fs.Stats>}
+ */
+async function getStats(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch (error) {
+    throw new Error(`Failed to get file stats: ${error.message}`);
+  }
+}
+
+/**
+ * Lists files in a directory
+ * 
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<string[]>} - Array of file names
+ */
+async function listFiles(dirPath) {
+  try {
+    return await fs.readdir(dirPath);
+  } catch (error) {
+    throw new Error(`Failed to list directory: ${error.message}`);
+  }
+}
+
+/**
+ * Recursively lists all files in a directory
+ * 
+ * @param {string} dirPath - Path to directory
+ * @param {string[]} fileList - Accumulator for recursive calls
+ * @returns {Promise<string[]>} - Array of absolute file paths
+ */
+async function listFilesRecursive(dirPath, fileList = []) {
+  const files = await fs.readdir(dirPath);
+  
+  for (const file of files) {
+    const filePath = path.join(dirPath, file);
+    const stat = await fs.stat(filePath);
+    
+    if (stat.isDirectory()) {
+      await listFilesRecursive(filePath, fileList);
+    } else {
+      fileList.push(filePath);
+    }
+  }
+  
+  return fileList;
+}
+
+/**
+ * Calculates total size of a directory
+ * 
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<number>} - Total size in bytes
+ */
+async function getDirectorySize(dirPath) {
+  const files = await listFilesRecursive(dirPath);
+  let totalSize = 0;
+  
+  for (const file of files) {
+    const stats = await fs.stat(file);
+    totalSize += stats.size;
+  }
+  
+  return totalSize;
+}
+
+module.exports = {
+  validatePath,
+  atomicWrite,
+  safeCopy,
+  ensureDirectory,
+  copyDirectory,
+  pathExists,
+  readJSON,
+  writeJSON,
+  remove,
+  getStats,
+  listFiles,
+  listFilesRecursive,
+  getDirectorySize
+};

package/lib/version/version-manager.js

@@ -0,0 +1,287 @@
+/**
+ * Version Manager
+ * 
+ * Manages version tracking, compatibility checking, and upgrade path calculation
+ * for the kiro-spec-engine project adoption and upgrade system.
+ */
+
+const path = require('path');
+const semver = require('semver');
+const { readJSON, writeJSON, pathExists } = require('../utils/fs-utils');
+
+/**
+ * Compatibility matrix defining which versions can work together
+ * Format: { version: { compatible: [versions], breaking: boolean } }
+ */
+const COMPATIBILITY_MATRIX = {
+  '1.0.0': { compatible: ['1.0.0', '1.1.0', '1.2.0'], breaking: false },
+  '1.1.0': { compatible: ['1.0.0', '1.1.0', '1.2.0'], breaking: false },
+  '1.2.0': { compatible: ['1.0.0', '1.1.0', '1.2.0'], breaking: false },
+  '2.0.0': { compatible: ['2.0.0'], breaking: true, migration: 'required' }
+};
+
+class VersionManager {
+  constructor() {
+    this.versionFileName = 'version.json';
+  }
+
+  /**
+   * Gets the path to version.json in a project
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {string} - Absolute path to version.json
+   */
+  getVersionFilePath(projectPath) {
+    return path.join(projectPath, '.kiro', this.versionFileName);
+  }
+
+  /**
+   * Reads version information from project
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<VersionInfo|null>} - Version info or null if not found
+   */
+  async readVersion(projectPath) {
+    const versionPath = this.getVersionFilePath(projectPath);
+    
+    try {
+      const exists = await pathExists(versionPath);
+      if (!exists) {
+        return null;
+      }
+      
+      const versionInfo = await readJSON(versionPath);
+      
+      // Validate structure
+      if (!this.isValidVersionInfo(versionInfo)) {
+        throw new Error('Invalid version.json structure');
+      }
+      
+      return versionInfo;
+    } catch (error) {
+      throw new Error(`Failed to read version file: ${error.message}`);
+    }
+  }
+
+  /**
+   * Writes version information to project
+   * 
+   * @param {string} projectPath - Absolute path to project root
+   * @param {VersionInfo} versionInfo - Version information to write
+   * @returns {Promise<void>}
+   */
+  async writeVersion(projectPath, versionInfo) {
+    const versionPath = this.getVersionFilePath(projectPath);
+    
+    try {
+      // Validate structure before writing
+      if (!this.isValidVersionInfo(versionInfo)) {
+        throw new Error('Invalid version info structure');
+      }
+      
+      await writeJSON(versionPath, versionInfo, { spaces: 2 });
+    } catch (error) {
+      throw new Error(`Failed to write version file: ${error.message}`);
+    }
+  }
+
+  /**
+   * Creates initial version info for a new project
+   * 
+   * @param {string} kseVersion - Current kse version
+   * @param {string} templateVersion - Template version (default: same as kse)
+   * @returns {VersionInfo}
+   */
+  createVersionInfo(kseVersion, templateVersion = null) {
+    const now = new Date().toISOString();
+    
+    return {
+      'kse-version': kseVersion,
+      'template-version': templateVersion || kseVersion,
+      'created': now,
+      'last-upgraded': now,
+      'upgrade-history': []
+    };
+  }
+
+  /**
+   * Validates version info structure
+   * 
+   * @param {Object} versionInfo - Version info to validate
+   * @returns {boolean}
+   */
+  isValidVersionInfo(versionInfo) {
+    if (!versionInfo || typeof versionInfo !== 'object') {
+      return false;
+    }
+    
+    const requiredFields = [
+      'kse-version',
+      'template-version',
+      'created',
+      'last-upgraded',
+      'upgrade-history'
+    ];
+    
+    for (const field of requiredFields) {
+      if (!(field in versionInfo)) {
+        return false;
+      }
+    }
+    
+    // Validate upgrade-history is an array
+    if (!Array.isArray(versionInfo['upgrade-history'])) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Checks if upgrade is needed
+   * 
+   * @param {string} projectVersion - Current project version
+   * @param {string} kseVersion - Installed kse version
+   * @returns {boolean}
+   */
+  needsUpgrade(projectVersion, kseVersion) {
+    if (!projectVersion || !kseVersion) {
+      return false;
+    }
+    
+    try {
+      // Use semver for comparison
+      return semver.lt(projectVersion, kseVersion);
+    } catch (error) {
+      // If semver comparison fails, do string comparison
+      return projectVersion !== kseVersion;
+    }
+  }
+
+  /**
+   * Checks compatibility between versions
+   * 
+   * @param {string} fromVersion - Source version
+   * @param {string} toVersion - Target version
+   * @returns {CompatibilityResult}
+   */
+  checkCompatibility(fromVersion, toVersion) {
+    // If versions are the same, always compatible
+    if (fromVersion === toVersion) {
+      return {
+        compatible: true,
+        breaking: false,
+        migration: 'none'
+      };
+    }
+    
+    // Check compatibility matrix
+    const fromInfo = COMPATIBILITY_MATRIX[fromVersion];
+    
+    if (!fromInfo) {
+      // Unknown version - assume incompatible
+      return {
+        compatible: false,
+        breaking: true,
+        migration: 'unknown',
+        message: `Unknown source version: ${fromVersion}`
+      };
+    }
+    
+    const isCompatible = fromInfo.compatible.includes(toVersion);
+    
+    return {
+      compatible: isCompatible,
+      breaking: !isCompatible || fromInfo.breaking,
+      migration: !isCompatible ? 'required' : 'none'
+    };
+  }
+
+  /**
+   * Calculates upgrade path for version gap
+   * Returns array of intermediate versions to upgrade through
+   * 
+   * @param {string} fromVersion - Current version
+   * @param {string} toVersion - Target version
+   * @returns {string[]} - Array of versions in upgrade order (including from and to)
+   */
+  calculateUpgradePath(fromVersion, toVersion) {
+    // If same version, no upgrade needed
+    if (fromVersion === toVersion) {
+      return [fromVersion];
+    }
+    
+    // Get all versions from compatibility matrix
+    const allVersions = Object.keys(COMPATIBILITY_MATRIX).sort((a, b) => {
+      try {
+        return semver.compare(a, b);
+      } catch (error) {
+        return a.localeCompare(b);
+      }
+    });
+    
+    // Find indices
+    const fromIndex = allVersions.indexOf(fromVersion);
+    const toIndex = allVersions.indexOf(toVersion);
+    
+    if (fromIndex === -1) {
+      throw new Error(`Unknown source version: ${fromVersion}`);
+    }
+    
+    if (toIndex === -1) {
+      throw new Error(`Unknown target version: ${toVersion}`);
+    }
+    
+    if (fromIndex > toIndex) {
+      throw new Error('Cannot downgrade versions');
+    }
+    
+    // Return all versions from source to target (inclusive)
+    return allVersions.slice(fromIndex, toIndex + 1);
+  }
+
+  /**
+   * Adds an upgrade entry to version history
+   * 
+   * @param {VersionInfo} versionInfo - Current version info
+   * @param {string} fromVersion - Version upgraded from
+   * @param {string} toVersion - Version upgraded to
+   * @param {boolean} success - Whether upgrade succeeded
+   * @param {string} error - Error message if failed
+   * @returns {VersionInfo} - Updated version info
+   */
+  addUpgradeHistory(versionInfo, fromVersion, toVersion, success, error = null) {
+    const entry = {
+      from: fromVersion,
+      to: toVersion,
+      date: new Date().toISOString(),
+      success
+    };
+    
+    if (error) {
+      entry.error = error;
+    }
+    
+    versionInfo['upgrade-history'].push(entry);
+    
+    // Update version and last-upgraded if successful
+    if (success) {
+      versionInfo['kse-version'] = toVersion;
+      versionInfo['template-version'] = toVersion;
+      versionInfo['last-upgraded'] = entry.date;
+    }
+    
+    return versionInfo;
+  }
+
+  /**
+   * Gets the compatibility matrix
+   * 
+   * @returns {Object} - Compatibility matrix
+   */
+  getCompatibilityMatrix() {
+    return { ...COMPATIBILITY_MATRIX };
+  }
+}
+
+module.exports = VersionManager;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Kiro Spec Engine - A spec-driven development engine with steering rules and quality enhancement powered by Ultrawork spirit",
   "main": "index.js",
   "bin": {
@@ -69,7 +69,8 @@
     "commander": "^9.0.0",
     "fs-extra": "^10.0.0",
     "inquirer": "^8.2.0",
-    "path": "^0.12.7"
+    "path": "^0.12.7",
+    "semver": "^7.5.4"
   },
   "devDependencies": {
     "fast-check": "^4.5.3",