kiro-spec-engine 1.13.1 → 1.15.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.15.0] - 2026-01-30
+
+### Added
+- **.gitignore Auto-Fix for Team Collaboration**: Automatic detection and fixing of .gitignore configuration
+  - Detects old blanket `.kiro/` exclusion patterns that prevent Spec sharing
+  - Replaces with layered strategy: commit Specs, exclude personal state
+  - Integrated into `kse adopt` and `kse upgrade` flows (automatic)
+  - Standalone command: `kse doctor --fix-gitignore`
+  - Creates backup before modification (stored in `.kiro/backups/gitignore-{timestamp}`)
+  - Preserves all user rules (non-.kiro patterns)
+  - Handles different line endings (CRLF/LF) correctly
+  - 26 unit tests covering detection, transformation, backup, and integration
+
+### Technical Details
+- **GitignoreDetector**: Analyzes .gitignore status (missing, old-pattern, incomplete, compliant)
+- **GitignoreTransformer**: Applies layered exclusion strategy while preserving user rules
+- **GitignoreBackup**: Creates timestamped backups with metadata
+- **GitignoreIntegration**: Coordinates detection → backup → transform → report
+- **Layered Strategy**: Commits `.kiro/specs/` while excluding personal state (CURRENT_CONTEXT.md, environments.json, backups/, logs/)
+- **Cross-platform**: Preserves original line ending style (CRLF on Windows, LF on Unix)
+
+### Documentation
+- Updated `docs/adoption-guide.md` with .gitignore auto-fix information
+- Updated `docs/upgrade-guide.md` with .gitignore verification steps
+- Comprehensive `docs/team-collaboration-guide.md` already exists (500+ lines)
+
+## [1.14.0] - 2026-01-30
+
+### Added
+- **Environment Configuration Management**: Lightweight multi-environment configuration system
+  - Register and manage multiple environment configurations (development, staging, production, etc.)
+  - Quick environment switching with automatic file copying
+  - Automatic backup system before each switch (maintains up to 10 backups per file)
+  - Rollback capability to restore previous environment state
+  - Support for multiple configuration file mappings per environment
+  - Environment verification with custom commands (optional)
+  - Commands: `kse env list`, `kse env switch`, `kse env info`, `kse env register`, `kse env unregister`, `kse env rollback`
+  - Comprehensive user documentation in `docs/environment-management-guide.md`
+  - 66 unit tests covering all core functionality
+
+### Technical Details
+- **EnvironmentRegistry**: JSON-based persistent storage (`.kiro/environments.json`)
+- **EnvironmentManager**: Core logic for environment operations
+- **BackupSystem**: Automatic backup/restore with history management
+- **CLI Integration**: Seamless integration with existing kse commands
+- **Cross-platform**: Consistent behavior on Windows, Linux, and Mac
+
 ## [1.13.1] - 2026-01-29
 
 ### Fixed

package/bin/kiro-spec-engine.js

@@ -176,6 +176,7 @@ program
   .command('doctor')
   .description(t('cli.commands.doctor.description'))
   .option('--docs', 'Show detailed document governance diagnostics')
+  .option('--fix-gitignore', 'Check and fix .gitignore for team collaboration')
   .action((options) => {
     doctorCommand(options);
   });
@@ -460,6 +461,18 @@ workspaceCmd
     await workspaceCommand.infoWorkspace(name);
   });
 
+// Environment configuration management commands
+const envCommand = require('../lib/commands/env');
+
+const envCmd = program
+  .command('env <subcommand> [args...]')
+  .description('Manage environment configurations');
+
+envCmd.action(async (subcommand, args, options) => {
+  const exitCode = await envCommand.handleCommand([subcommand, ...args]);
+  process.exit(exitCode);
+});
+
 // 更新项目配置的辅助函数
 async function updateProjectConfig(projectName) {
   const envPath = path.join(process.cwd(), '.kiro/steering/ENVIRONMENT.md');

package/docs/adoption-guide.md

@@ -576,20 +576,27 @@ your-project/
 
 After successful adoption:
 
-1. **Create your first spec**:
+1. **Verify .gitignore configuration**:
+   The adoption process automatically checks and fixes your `.gitignore` for team collaboration. If you see a warning about .gitignore, you can manually fix it:
+   ```bash
+   kse doctor --fix-gitignore
+   ```
+   Learn more: [Team Collaboration Guide](./team-collaboration-guide.md)
+
+2. **Create your first spec**:
    ```bash
    kse create-spec 01-00-my-feature
    ```
 
-2. **Check project status**:
+3. **Check project status**:
    ```bash
    kse status
    ```
 
-3. **Read the spec workflow guide**:
+4. **Read the spec workflow guide**:
    - See `.kiro/specs/SPEC_WORKFLOW_GUIDE.md`
 
-4. **Explore Ultrawork**:
+5. **Explore Ultrawork**:
    ```bash
    kse enhance requirements .kiro/specs/01-00-my-feature/requirements.md
    ```

package/docs/environment-management-guide.md

@@ -0,0 +1,526 @@
+# Environment Configuration Management Guide
+
+## Overview
+
+The Environment Configuration Management feature provides a lightweight solution for managing multiple environment configurations (development, staging, production, etc.) within your kse projects.
+
+## Quick Start
+
+### Installation and Project Adoption
+
+**⚠️ Important**: When you install kse in a project, it automatically adopts the project and operates in autonomous mode by default. This means:
+
+- ✅ kse takes ownership of the project structure
+- ✅ AI assistants can make changes autonomously without frequent confirmations
+- ✅ Faster development workflow with less interruption
+- ✅ All changes are tracked and can be rolled back if needed
+
+**Recommended Workflow**:
+
+```bash
+# Install kse globally or in your project
+npm install -g kiro-spec-engine
+
+# Navigate to your project
+cd your-project
+
+# Check project status first (recommended)
+kse status
+
+# If issues are detected, run diagnostics
+kse doctor
+
+# Adopt the project (creates .kiro/ directory)
+kse adopt
+
+# kse is now managing your project autonomously
+```
+
+**Note**: Future versions of kse will automatically check project status after installation/upgrade and prompt for diagnostics if needed.
+
+### 1. Register an Environment
+
+Create a configuration file (e.g., `env-local.json`):
+
+```json
+{
+  "name": "local-dev",
+  "description": "Local development environment",
+  "config_files": [
+    {
+      "source": ".env.local",
+      "target": ".env"
+    },
+    {
+      "source": "config/database.local.json",
+      "target": "config/database.json"
+    }
+  ]
+}
+```
+
+Register the environment:
+
+```bash
+kse env register env-local.json
+```
+
+### 2. List Environments
+
+```bash
+kse env list
+```
+
+### 3. Switch Environments
+
+```bash
+kse env switch local-dev
+```
+
+The system automatically:
+- Creates a backup of existing target files
+- Copies source files to target locations
+- Updates the active environment
+
+### 4. View Active Environment
+
+```bash
+kse env info
+```
+
+### 5. Rollback
+
+If something goes wrong, rollback to the previous state:
+
+```bash
+kse env rollback
+```
+
+## Commands
+
+### `kse env list`
+
+List all registered environments with their status.
+
+### `kse env switch <name>`
+
+Switch to the specified environment. Creates automatic backups before switching.
+
+### `kse env info`
+
+Display details about the currently active environment.
+
+### `kse env register <config-file>`
+
+Register a new environment from a JSON configuration file.
+
+### `kse env unregister <name> --force`
+
+Remove an environment from the registry. Requires `--force` flag for confirmation.
+
+### `kse env rollback`
+
+Restore the most recent backup, reverting to the previous environment state.
+
+### `kse env verify`
+
+Verify the current environment configuration by running the verification command defined in the environment. If no verification rules are configured, reports success.
+
+### `kse env run "<command>"`
+
+Run a command in the context of the current environment. Ensures the active environment is set before executing the command.
+
+## Configuration File Format
+
+```json
+{
+  "name": "environment-name",
+  "description": "Human-readable description",
+  "config_files": [
+    {
+      "source": "path/to/source/file",
+      "target": "path/to/target/file"
+    }
+  ],
+  "verification": {
+    "command": "node verify.js",
+    "expected_output": "OK"
+  }
+}
+```
+
+### Fields
+
+- **name** (required): Unique environment name in kebab-case
+- **description** (required): Human-readable description
+- **config_files** (required): Array of source-to-target file mappings
+- **verification** (optional): Verification command and expected output
+
+## Backup System
+
+The backup system automatically:
+- Creates timestamped backups before each environment switch
+- Maintains up to 10 backups per target file
+- Stores backups in `.kiro/env-backups/`
+- Automatically cleans up old backups
+
+## Best Practices
+
+1. **Adopt projects with kse**: Run `kse adopt` to let kse manage your project autonomously, enabling faster AI-assisted development without constant confirmations
+2. **Use descriptive names**: Choose clear, descriptive names for your environments
+3. **Keep source files in version control**: Store all environment-specific configuration files in your repository
+4. **Selective .kiro/ version control**: Use layered .gitignore strategy:
+   - ✅ **DO commit**: `.kiro/specs/` (Spec documents), `.kiro/steering/CORE_PRINCIPLES.md`, `.kiro/steering/ENVIRONMENT.md`, `.kiro/steering/RULES_GUIDE.md`, `.kiro/tools/`, `.kiro/config/`
+   - ❌ **DO NOT commit**: `.kiro/steering/CURRENT_CONTEXT.md` (personal context), `.kiro/environments.json` (user-specific), `.kiro/backups/`, `.kiro/logs/`, `.kiro/reports/`
+   - **Why**: Share Spec documents and team rules, but avoid conflicts from personal state and user-specific configurations
+5. **Share environment templates**: Commit environment configuration JSON files (e.g., `env-local.json`, `env-production.json`) to your repository root or a `config/` directory, not in `.kiro/`
+6. **Test switches**: Test environment switches in a safe environment before using in production
+7. **Regular backups**: The system creates automatic backups, but consider additional backup strategies for critical configurations
+8. **Document verification**: Add verification rules to catch configuration errors early
+
+## Examples
+
+### Example 1: Simple Development/Production Setup
+
+```json
+{
+  "name": "development",
+  "description": "Local development environment",
+  "config_files": [
+    { "source": ".env.development", "target": ".env" }
+  ]
+}
+```
+
+```json
+{
+  "name": "production",
+  "description": "Production environment",
+  "config_files": [
+    { "source": ".env.production", "target": ".env" }
+  ],
+  "verification": {
+    "command": "node scripts/verify-env.js",
+    "expected_output": "production"
+  }
+}
+```
+
+### Example 2: Multiple Configuration Files
+
+```json
+{
+  "name": "staging",
+  "description": "Staging environment with database and API configs",
+  "config_files": [
+    { "source": ".env.staging", "target": ".env" },
+    { "source": "config/database.staging.json", "target": "config/database.json" },
+    { "source": "config/api.staging.json", "target": "config/api.json" }
+  ]
+}
+```
+
+## Troubleshooting
+
+### "Source file does not exist"
+
+Ensure all source files specified in your configuration exist before registering or switching environments.
+
+### "Environment already exists"
+
+Each environment must have a unique name. Use `kse env unregister <name> --force` to remove the existing environment first.
+
+### "Cannot unregister active environment"
+
+Switch to a different environment before unregistering the currently active one.
+
+### "No backups available to restore"
+
+Backups are only created during environment switches. If you haven't switched environments yet, there won't be any backups to restore.
+
+## Integration with Multi-Workspace
+
+When using kse's multi-workspace feature, each workspace maintains its own independent environment registry. This allows different projects to have different environment configurations without interference.
+
+## See Also
+
+- [Multi-Workspace Management](../README.md#multi-workspace-management)
+- [Command Reference](command-reference.md)
+
+
+## Migration Guide
+
+### Migrating from Manual Configuration Management
+
+If you're currently managing environment configurations manually (e.g., copying files, using shell scripts), here's how to migrate to kse environment management:
+
+#### Step 1: Identify Your Environments
+
+List all the environments you currently manage:
+- Development (local)
+- Staging
+- Production
+- Testing
+- etc.
+
+#### Step 2: Identify Configuration Files
+
+For each environment, identify which files need to be switched:
+- `.env` files
+- Configuration files (e.g., `config/database.json`, `config/app.json`)
+- API endpoint configurations
+- Feature flags
+- etc.
+
+#### Step 3: Create Source Files
+
+Create source files for each environment. Use a naming convention like:
+- `.env.local` → `.env`
+- `.env.staging` → `.env`
+- `.env.production` → `.env`
+- `config/database.local.json` → `config/database.json`
+
+**Example structure**:
+```
+your-project/
+├── .env.local          # Source for local environment
+├── .env.staging        # Source for staging environment
+├── .env.production     # Source for production environment
+├── config/
+│   ├── database.local.json
+│   ├── database.staging.json
+│   └── database.production.json
+```
+
+#### Step 4: Create Environment Configuration Files
+
+For each environment, create a JSON configuration file:
+
+**local-env.json**:
+```json
+{
+  "name": "local",
+  "description": "Local development environment",
+  "config_files": [
+    {
+      "source": ".env.local",
+      "target": ".env"
+    },
+    {
+      "source": "config/database.local.json",
+      "target": "config/database.json"
+    }
+  ],
+  "verification": {
+    "command": "node scripts/verify-env.js",
+    "expected_output": "Environment: local"
+  }
+}
+```
+
+**staging-env.json**:
+```json
+{
+  "name": "staging",
+  "description": "Staging environment",
+  "config_files": [
+    {
+      "source": ".env.staging",
+      "target": ".env"
+    },
+    {
+      "source": "config/database.staging.json",
+      "target": "config/database.json"
+    }
+  ],
+  "verification": {
+    "command": "node scripts/verify-env.js",
+    "expected_output": "Environment: staging"
+  }
+}
+```
+
+#### Step 5: Register Environments
+
+Register each environment with kse:
+
+```bash
+kse env register local-env.json
+kse env register staging-env.json
+kse env register production-env.json
+```
+
+#### Step 6: Verify Registration
+
+List all registered environments:
+
+```bash
+kse env list
+```
+
+#### Step 7: Test Environment Switching
+
+Switch to an environment and verify:
+
+```bash
+# Switch to local environment
+kse env switch local
+
+# Verify the switch
+kse env info
+
+# Verify configuration is correct
+kse env verify
+```
+
+#### Step 8: Update Your Workflow
+
+Replace your manual configuration management with kse commands:
+
+**Before**:
+```bash
+# Manual approach
+cp .env.local .env
+cp config/database.local.json config/database.json
+```
+
+**After**:
+```bash
+# kse approach
+kse env switch local
+```
+
+#### Step 9: Add to .gitignore
+
+Add target files to `.gitignore` to avoid committing environment-specific configurations:
+
+```gitignore
+# Environment target files (managed by kse)
+.env
+config/database.json
+config/app.json
+
+# Keep source files in version control
+!.env.local
+!.env.staging
+!.env.production
+!config/database.*.json
+```
+
+### Migrating from Other Tools
+
+#### From direnv
+
+If you're using direnv, you can migrate by:
+
+1. Keep your `.envrc` files as source files
+2. Create kse environment configurations that copy `.envrc.local` → `.envrc`
+3. Continue using direnv for environment variable loading
+4. Use kse for switching between environment configurations
+
+#### From Docker Compose
+
+If you're using Docker Compose with multiple environment files:
+
+1. Keep your `docker-compose.yml` and environment-specific files
+2. Create kse environments that switch between different compose files
+3. Use kse to manage which compose configuration is active
+
+**Example**:
+```json
+{
+  "name": "docker-local",
+  "description": "Docker local environment",
+  "config_files": [
+    {
+      "source": "docker-compose.local.yml",
+      "target": "docker-compose.override.yml"
+    },
+    {
+      "source": ".env.docker.local",
+      "target": ".env"
+    }
+  ]
+}
+```
+
+#### From Kubernetes ConfigMaps
+
+If you're using Kubernetes ConfigMaps for configuration:
+
+1. Export ConfigMaps to local files for development
+2. Create kse environments for local development
+3. Use kse for local environment switching
+4. Keep ConfigMaps for production deployments
+
+### Best Practices for Migration
+
+1. **Start Small**: Begin with one or two environments, test thoroughly, then add more
+2. **Backup First**: Create backups of your current configuration files before migration
+3. **Test Verification**: Create verification scripts to ensure environment correctness
+4. **Document**: Document your environment configurations and switching procedures
+5. **Team Communication**: Inform your team about the new workflow and provide training
+6. **Gradual Rollout**: Migrate one project at a time, learn from each migration
+
+### Common Migration Issues
+
+#### Issue: Source Files Don't Exist
+
+**Problem**: Trying to register an environment but source files are missing.
+
+**Solution**: Create source files first, then register the environment.
+
+```bash
+# Create source file
+cp .env .env.local
+
+# Register environment
+kse env register local-env.json
+```
+
+#### Issue: Target Files Already Exist
+
+**Problem**: Target files exist and you're worried about overwriting them.
+
+**Solution**: kse automatically creates backups before switching. You can also manually backup first.
+
+```bash
+# Manual backup (optional, kse does this automatically)
+cp .env .env.backup
+
+# Switch environment (creates automatic backup)
+kse env switch local
+
+# If needed, rollback
+kse env rollback
+```
+
+#### Issue: Verification Fails
+
+**Problem**: Environment verification fails after switching.
+
+**Solution**: Check the verification command and expected output. Update the environment configuration if needed.
+
+```bash
+# Check what went wrong
+kse env verify
+
+# Update environment configuration
+# Edit the JSON file and re-register
+kse env register local-env.json
+```
+
+### Migration Checklist
+
+- [ ] Identify all environments
+- [ ] Identify all configuration files
+- [ ] Create source files for each environment
+- [ ] Create environment configuration JSON files
+- [ ] Register all environments with kse
+- [ ] Test switching between environments
+- [ ] Create verification scripts (optional but recommended)
+- [ ] Update .gitignore
+- [ ] Update team documentation
+- [ ] Train team members on new workflow
+- [ ] Remove old manual scripts
+