kiro-spec-engine 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **Project Adoption System**: Intelligent project adoption with three modes
+  - Fresh adoption: Create complete .kiro/ structure from scratch
+  - Partial adoption: Add missing components to existing .kiro/
+  - Full adoption: Upgrade existing complete .kiro/ to current version
+- **Version Upgrade System**: Smooth version migration with migration scripts
+  - Incremental upgrades through intermediate versions
+  - Migration script support for breaking changes
+  - Automatic backup before upgrades
+- **Backup and Rollback System**: Safe operations with automatic backups
+  - Automatic backup creation before destructive operations
+  - Backup validation and integrity checking
+  - Easy rollback to previous states
+- **New CLI Commands**:
+  - `kse adopt`: Adopt existing projects into Kiro Spec Engine
+  - `kse upgrade`: Upgrade project to newer version
+  - `kse rollback`: Restore project from backup
+- **Core Components**:
+  - DetectionEngine: Analyzes project structure and determines adoption strategy
+  - AdoptionStrategy: Implements fresh, partial, and full adoption modes
+  - MigrationEngine: Plans and executes version upgrades
+  - BackupSystem: Creates, manages, and restores backups
+
+### Enhanced
+- Version management with upgrade history tracking
+- File system utilities with backup support
+- Project structure detection (Node.js, Python, mixed)
+- Conflict detection and resolution
+
+### Infrastructure
+- Created lib/adoption/ directory for adoption strategies
+- Created lib/upgrade/ directory for migration engine
+- Created lib/backup/ directory for backup system
+- Created lib/commands/ directory for CLI commands
+- Migration script template and loader system
+
+### Documentation
+- Comprehensive adoption and upgrade system design
+- Migration script interface documentation
+- User guides for adoption, upgrade, and rollback workflows
+
 ## [1.1.0] - 2026-01-23
 
 ### Added

package/README.md

@@ -83,12 +83,32 @@ kse enhance requirements .kiro/specs/01-00-user-authentication/requirements.md
 # Initialize project
 kse init [project-name]
 
+# Adopt existing project
+kse adopt                    # Interactive adoption
+kse adopt --auto             # Skip confirmations
+kse adopt --dry-run          # Show what would change
+kse adopt --mode fresh       # Force specific mode
+
+# Upgrade project version
+kse upgrade                  # Interactive upgrade
+kse upgrade --auto           # Skip confirmations
+kse upgrade --dry-run        # Show upgrade plan
+kse upgrade --to 1.2.0       # Upgrade to specific version
+
+# Rollback to previous state
+kse rollback                 # Interactive rollback
+kse rollback --auto          # Skip confirmations
+kse rollback --backup <id>   # Restore specific backup
+
 # Check project status
 kse status
 
 # Create new spec
 kse create-spec <spec-name>
 
+# System diagnostics
+kse doctor
+
 # Set language
 kse --lang zh <command>  # Chinese
 kse --lang en <command>  # English (default)
@@ -143,6 +163,74 @@ kse enhance design .kiro/specs/01-00-user-auth/design.md --requirements .kiro/sp
 - **Ultrawork Motivation**: Provide Sisyphus spirit motivation and suggestions
 - **Next Steps Guidance**: Suggest specific execution strategies
 
+## 🔄 Project Adoption and Upgrade
+
+### Adopting Existing Projects
+
+KSE can intelligently adopt existing projects with three modes:
+
+**Fresh Adoption** (no `.kiro/` directory):
+```bash
+kse adopt
+# Creates complete .kiro/ structure from scratch
+```
+
+**Partial Adoption** (`.kiro/` exists but incomplete):
+```bash
+kse adopt
+# Preserves existing specs/ and steering/
+# Adds missing components
+```
+
+**Full Adoption** (complete `.kiro/` from older version):
+```bash
+kse adopt
+# Upgrades components to current version
+# Preserves all user content
+# Creates backup before changes
+```
+
+### Upgrading to New Versions
+
+When a new version of KSE is released:
+
+```bash
+# Check current version
+kse --version
+
+# Upgrade to latest version
+kse upgrade
+
+# Upgrade to specific version
+kse upgrade --to 1.2.0
+
+# Preview upgrade plan
+kse upgrade --dry-run
+```
+
+**Incremental Upgrades**: KSE automatically handles version gaps by upgrading through intermediate versions (e.g., 1.0.0 → 1.1.0 → 1.2.0).
+
+### Rollback and Safety
+
+All destructive operations create automatic backups:
+
+```bash
+# List available backups
+kse rollback
+
+# Restore from specific backup
+kse rollback --backup adopt-2026-01-23-100000
+
+# Quick rollback (interactive)
+kse rollback
+```
+
+**Safety Features**:
+- ✅ Automatic backup before adoption/upgrade
+- ✅ Backup validation and integrity checking
+- ✅ Easy rollback to previous states
+- ✅ Dry-run mode to preview changes
+
 ## 🛠️ Project Structure
 
 After initialization, your project will have:

package/README.zh.md

@@ -83,12 +83,32 @@ kse enhance requirements .kiro/specs/01-00-user-authentication/requirements.md
 # 初始化项目
 kse init [项目名称]
 
+# 接管现有项目
+kse adopt                    # 交互式接管
+kse adopt --auto             # 跳过确认
+kse adopt --dry-run          # 显示将要改变的内容
+kse adopt --mode fresh       # 强制指定模式
+
+# 升级项目版本
+kse upgrade                  # 交互式升级
+kse upgrade --auto           # 跳过确认
+kse upgrade --dry-run        # 显示升级计划
+kse upgrade --to 1.2.0       # 升级到指定版本
+
+# 回滚到之前的状态
+kse rollback                 # 交互式回滚
+kse rollback --auto          # 跳过确认
+kse rollback --backup <id>   # 恢复指定备份
+
 # 检查项目状态
 kse status
 
 # 创建新 Spec
 kse create-spec <spec-名称>
 
+# 系统诊断
+kse doctor
+
 # 设置语言
 kse --lang zh <命令>  # 中文
 kse --lang en <命令>  # 英文
@@ -143,6 +163,74 @@ kse enhance design .kiro/specs/01-00-user-auth/design.md --requirements .kiro/sp
 - **Ultrawork 激励**：提供 Sisyphus 精神激励和建议
 - **下一步指导**：建议具体的执行策略
 
+## � 项目接管和升级
+
+### 接管现有项目
+
+KSE 可以智能接管现有项目，支持三种模式：
+
+**全新接管**（无 `.kiro/` 目录）：
+```bash
+kse adopt
+# 从头创建完整的 .kiro/ 结构
+```
+
+**部分接管**（`.kiro/` 存在但不完整）：
+```bash
+kse adopt
+# 保留现有的 specs/ 和 steering/
+# 添加缺失的组件
+```
+
+**完整接管**（来自旧版本的完整 `.kiro/`）：
+```bash
+kse adopt
+# 将组件升级到当前版本
+# 保留所有用户内容
+# 更改前创建备份
+```
+
+### 升级到新版本
+
+当 KSE 发布新版本时：
+
+```bash
+# 检查当前版本
+kse --version
+
+# 升级到最新版本
+kse upgrade
+
+# 升级到指定版本
+kse upgrade --to 1.2.0
+
+# 预览升级计划
+kse upgrade --dry-run
+```
+
+**渐进式升级**：KSE 自动处理版本差距，通过中间版本升级（例如 1.0.0 → 1.1.0 → 1.2.0）。
+
+### 回滚和安全性
+
+所有破坏性操作都会自动创建备份：
+
+```bash
+# 列出可用备份
+kse rollback
+
+# 从指定备份恢复
+kse rollback --backup adopt-2026-01-23-100000
+
+# 快速回滚（交互式）
+kse rollback
+```
+
+**安全特性**：
+- ✅ 接管/升级前自动备份
+- ✅ 备份验证和完整性检查
+- ✅ 轻松回滚到之前的状态
+- ✅ 预览模式查看更改
+
 ## 🛠️ 项目结构
 
 初始化后，你的项目将包含：

package/bin/kiro-spec-engine.js

@@ -8,6 +8,10 @@ const path = require('path');
 const { spawn } = require('child_process');
 const { getI18n } = require('../lib/i18n');
 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);
@@ -15,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();
 
 // 版本和基本信息
@@ -24,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
@@ -157,6 +175,38 @@ program
     doctorCommand();
   });
 
+// 项目接管命令
+program
+  .command('adopt')
+  .description('Adopt existing project into Kiro Spec Engine')
+  .option('--auto', 'Skip confirmations (use with caution)')
+  .option('--dry-run', 'Show what would change without making changes')
+  .option('--mode <mode>', 'Force specific adoption mode (fresh/partial/full)')
+  .action((options) => {
+    adoptCommand(options);
+  });
+
+// 项目升级命令
+program
+  .command('upgrade')
+  .description('Upgrade project to newer version')
+  .option('--auto', 'Skip confirmations (use with caution)')
+  .option('--dry-run', 'Show upgrade plan without making changes')
+  .option('--to <version>', 'Target version (default: current kse version)')
+  .action((options) => {
+    upgradeCommand(options);
+  });
+
+// 回滚命令
+program
+  .command('rollback')
+  .description('Restore project from backup')
+  .option('--auto', 'Skip confirmations (use with caution)')
+  .option('--backup <id>', 'Specific backup ID to restore')
+  .action((options) => {
+    rollbackCommand(options);
+  });
+
 // 状态检查命令
 program
   .command('status')
@@ -205,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');