kiro-spec-engine 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -7,21 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.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`)
+- **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
+- 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/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,9 @@ 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 i18n = getI18n();
 const t = (key, params) => i18n.t(key, params);
@@ -157,6 +160,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')