scene-capability-engine 3.0.0

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
+

package/docs/examples/add-export-command/design.md

@@ -0,0 +1,194 @@
+# Export Command - Design
+
+> Technical design for kse export command
+
+---
+
+**Version**: 1.42.0  
+**Last Updated**: 2026-02-11
+
+---
+
+## Architecture
+
+**Pattern:** Command Pattern  
+**CLI Framework:** Commander.js  
+**Markdown Processing:** marked library  
+**File I/O:** Node.js fs/promises
+
+---
+
+## Component Design
+
+### ExportCommand
+**File:** `lib/commands/export.command.js`
+
+**Responsibilities:**
+- Parse command arguments
+- Validate inputs
+- Orchestrate export process
+- Display results
+
+**Methods:**
+```javascript
+class ExportCommand {
+  async execute(specName, options) {
+    // 1. Validate Spec exists
+    // 2. Load Spec data
+    // 3. Format based on options.format
+    // 4. Write to file
+    // 5. Display success message
+  }
+}
+```
+
+---
+
+### ExportService
+**File:** `lib/services/export.service.js`
+
+**Responsibilities:**
+- Load Spec files
+- Format data for export
+- Generate output files
+
+**Methods:**
+```javascript
+class ExportService {
+  async loadSpec(specName) {
+    // Read requirements.md, design.md, tasks.md
+    // Return { requirements, design, tasks, metadata }
+  }
+
+  async exportAsJSON(specData, outputPath) {
+    // Format as JSON
+    // Write to file
+  }
+
+  async exportAsMarkdown(specData, outputPath) {
+    // Combine all documents
+    // Add TOC
+    // Write to file
+  }
+
+  async exportAsHTML(specData, outputPath) {
+    // Convert Markdown to HTML
+    // Add styling
+    // Write to file
+  }
+}
+```
+
+---
+
+## Command Registration
+
+**File:** `bin/kiro-spec-engine.js`
+
+```javascript
+program
+  .command('export <spec-name>')
+  .description('Export Spec in various formats')
+  .option('-f, --format <format>', 'Output format (json|md|html)', 'md')
+  .option('-o, --output <path>', 'Output file path')
+  .option('--include-meta', 'Include metadata', true)
+  .action(async (specName, options) => {
+    const command = new ExportCommand();
+    await command.execute(specName, options);
+  });
+```
+
+---
+
+## Output Formats
+
+### JSON Format
+```json
+{
+  "name": "01-00-feature-name",
+  "metadata": {
+    "created": "2026-01-23T10:00:00Z",
+    "version": "1.0.0"
+  },
+  "requirements": "# Requirements\n...",
+  "design": "# Design\n...",
+  "tasks": "# Tasks\n..."
+}
+```
+
+### Markdown Format
+```markdown
+# Spec: 01-00-feature-name
+
+**Exported:** 2026-01-23  
+**Version:** 1.0.0
+
+## Table of Contents
+- [Requirements](#requirements)
+- [Design](#design)
+- [Tasks](#tasks)
+
+---
+
+## Requirements
+[Content from requirements.md]
+
+---
+
+## Design
+[Content from design.md]
+
+---
+
+## Tasks
+[Content from tasks.md]
+```
+
+### HTML Format
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Spec: 01-00-feature-name</title>
+  <style>/* Styling */</style>
+</head>
+<body>
+  <h1>Spec: 01-00-feature-name</h1>
+  <!-- Converted Markdown content -->
+</body>
+</html>
+```
+
+---
+
+## Error Handling
+
+```javascript
+// Spec not found
+throw new Error(`Spec "${specName}" not found in .kiro/specs/`);
+
+// Invalid format
+throw new Error(`Invalid format "${format}". Use: json, md, or html`);
+
+// File write error
+throw new Error(`Failed to write export file: ${error.message}`);
+```
+
+---
+
+## Requirements Traceability
+
+| Requirement | Component | Method |
+|-------------|-----------|--------|
+| US-1 | ExportService | exportAsJSON() |
+| US-2 | ExportService | exportAsMarkdown() |
+| US-3 | ExportService | exportAsHTML() |
+| FR-1 | ExportCommand | execute() |
+| FR-2 | ExportService | exportAsJSON() |
+| FR-3 | ExportService | exportAsMarkdown() |
+| FR-4 | ExportService | exportAsHTML() |
+
+---
+
+**Version**: 1.42.0  
+**Last Updated**: 2026-02-11