# Workspace Enforcement and Version Tracking Guide\n\n**Version**: 1.0.0\n**Last Updated**: 2025-10-06\n**System Version**: 2.0.5+\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Workspace Requirement](#workspace-requirement)\n3. [Version Tracking](#version-tracking)\n4. [Migration Framework](#migration-framework)\n5. [Command Reference](#command-reference)\n6. [Troubleshooting](#troubleshooting)\n7. [Best Practices](#best-practices)\n\n---\n\n## Overview\n\nThe provisioning system now enforces **mandatory workspace requirements** for all infrastructure operations. This ensures:\n\n- **Consistent Environment**: All operations run in a well-defined workspace\n- **Version Compatibility**: Workspaces track provisioning and schema versions\n- **Safe Migrations**: Automatic migration framework with backup/rollback support\n- **Configuration Isolation**: Each workspace has isolated configurations and state\n\n### Key Features\n\n- ✅ **Mandatory Workspace**: Most commands require an active workspace\n- ✅ **Version Tracking**: Workspaces track system, schema, and format versions\n- ✅ **Compatibility Checks**: Automatic validation before operations\n- ✅ **Migration Framework**: Safe upgrades with backup/restore\n- ✅ **Clear Error Messages**: Helpful guidance when workspace is missing or incompatible\n\n---\n\n## Workspace Requirement\n\n### Commands That Require Workspace\n\nAlmost all provisioning commands now require an active workspace:\n\n- **Infrastructure**: `server`, `taskserv`, `cluster`, `infra`\n- **Orchestration**: `workflow`, `batch`, `orchestrator`\n- **Development**: `module`, `layer`, `pack`\n- **Generation**: `generate`\n- **Configuration**: Most `config` commands\n- **Test**: `test` environment commands\n\n### Commands That Don't Require Workspace\n\nOnly informational and workspace management commands work without a workspace:\n\n- `help` - Help system\n- `version` - Show version information\n- `workspace` - Workspace management commands\n- `guide` / `sc` - Documentation and quick reference\n- `nu` - Start Nushell session\n- `nuinfo` - Nushell information\n\n### What Happens Without a Workspace\n\nIf you run a command without an active workspace, you'll see:\n\n```\n✗ Workspace Required\n\nNo active workspace is configured.\n\nTo get started:\n\n  1. Create a new workspace:\n     provisioning workspace init <name>\n\n  2. Or activate an existing workspace:\n     provisioning workspace activate <name>\n\n  3. List available workspaces:\n     provisioning workspace list\n```\n\n---\n\n## Version Tracking\n\n### Workspace Metadata\n\nEach workspace maintains metadata in `.provisioning/metadata.yaml`:\n\n```\nworkspace:\n  name: "my-workspace"\n  path: "/path/to/workspace"\n\nversion:\n  provisioning: "2.0.5"    # System version when created/updated\n  schema: "1.0.0"          # KCL schema version\n  workspace_format: "2.0.0" # Directory structure version\n\ncreated: "2025-10-06T12:00:00Z"\nlast_updated: "2025-10-06T13:30:00Z"\n\nmigration_history: []\n\ncompatibility:\n  min_provisioning_version: "2.0.0"\n  min_schema_version: "1.0.0"\n```\n\n### Version Components\n\n#### 1. Provisioning Version\n\n- **What**: Version of the provisioning system (CLI + libraries)\n- **Example**: `2.0.5`\n- **Purpose**: Ensures workspace is compatible with current system\n\n#### 2. Schema Version\n\n- **What**: Version of KCL schemas used in workspace\n- **Example**: `1.0.0`\n- **Purpose**: Tracks configuration schema compatibility\n\n#### 3. Workspace Format Version\n\n- **What**: Version of workspace directory structure\n- **Example**: `2.0.0`\n- **Purpose**: Ensures workspace has required directories and files\n\n### Checking Workspace Version\n\nView workspace version information:\n\n```\n# Check active workspace version\nprovisioning workspace version\n\n# Check specific workspace version\nprovisioning workspace version my-workspace\n\n# JSON output\nprovisioning workspace version --format json\n```\n\n**Example Output**:\n\n```\nWorkspace Version Information\n\nSystem:\n  Version: 2.0.5\n\nWorkspace:\n  Name: my-workspace\n  Path: /Users/user/workspaces/my-workspace\n  Version: 2.0.5\n  Schema Version: 1.0.0\n  Format Version: 2.0.0\n  Created: 2025-10-06T12:00:00Z\n  Last Updated: 2025-10-06T13:30:00Z\n\nCompatibility:\n  Compatible: true\n  Reason: version_match\n  Message: Workspace and system versions match\n\nMigrations:\n  Total: 0\n```\n\n---\n\n## Migration Framework\n\n### When Migration is Needed\n\nMigration is required when:\n\n1. **No Metadata**: Workspace created before version tracking (< 2.0.5)\n2. **Version Mismatch**: System version is newer than workspace version\n3. **Breaking Changes**: Major version update with structural changes\n\n### Compatibility Scenarios\n\n#### Scenario 1: No Metadata (Unknown Version)\n\n```\nWorkspace version is incompatible:\n  Workspace: my-workspace\n  Path: /path/to/workspace\n\nWorkspace metadata not found or corrupted\n\nThis workspace needs migration:\n\n  Run workspace migration:\n     provisioning workspace migrate my-workspace\n```\n\n#### Scenario 2: Migration Available\n\n```\nℹ Migration available: Workspace can be updated from 2.0.0 to 2.0.5\n  Run: provisioning workspace migrate my-workspace\n```\n\n#### Scenario 3: Workspace Too New\n\n```\nWorkspace version (3.0.0) is newer than system (2.0.5)\n\nWorkspace is newer than the system:\n  Workspace version: 3.0.0\n  System version: 2.0.5\n\n  Upgrade the provisioning system to use this workspace.\n```\n\n### Running Migrations\n\n#### Basic Migration\n\nMigrate active workspace to current system version:\n\n```\nprovisioning workspace migrate\n```\n\n#### Migrate Specific Workspace\n\n```\nprovisioning workspace migrate my-workspace\n```\n\n#### Migration Options\n\n```\n# Skip backup (not recommended)\nprovisioning workspace migrate --skip-backup\n\n# Force without confirmation\nprovisioning workspace migrate --force\n\n# Migrate to specific version\nprovisioning workspace migrate --target-version 2.1.0\n```\n\n### Migration Process\n\nWhen you run a migration:\n\n1. **Validation**: System validates workspace exists and needs migration\n2. **Backup**: Creates timestamped backup in `.workspace_backups/`\n3. **Confirmation**: Prompts for confirmation (unless `--force`)\n4. **Migration**: Applies migration steps sequentially\n5. **Verification**: Validates migration success\n6. **Metadata Update**: Records migration in workspace metadata\n\n**Example Migration Output**:\n\n```\nWorkspace Migration\n\nWorkspace: my-workspace\nPath: /path/to/workspace\n\nCurrent version: unknown\nTarget version: 2.0.5\n\nThis will migrate the workspace from unknown to 2.0.5\nA backup will be created before migration.\n\nContinue with migration? (y/N): y\n\nCreating backup...\n✓ Backup created: /path/.workspace_backups/my-workspace_backup_20251006_123000\n\nMigration Strategy: Initialize metadata\nDescription: Add metadata tracking to existing workspace\nFrom: unknown → To: 2.0.5\n\nMigrating workspace to version 2.0.5...\n✓ Initialize metadata completed\n\n✓ Migration completed successfully\n```\n\n### Workspace Backups\n\n#### List Backups\n\n```\n# List backups for active workspace\nprovisioning workspace list-backups\n\n# List backups for specific workspace\nprovisioning workspace list-backups my-workspace\n```\n\n**Example Output**:\n\n```\nWorkspace Backups for my-workspace\n\nname                               created                  reason         size\nmy-workspace_backup_20251006_1200  2025-10-06T12:00:00Z    pre_migration  2.3 MB\nmy-workspace_backup_20251005_1500  2025-10-05T15:00:00Z    pre_migration  2.1 MB\n```\n\n#### Restore from Backup\n\n```\n# Restore workspace from backup\nprovisioning workspace restore-backup /path/to/backup\n\n# Force restore without confirmation\nprovisioning workspace restore-backup /path/to/backup --force\n```\n\n**Restore Process**:\n\n```\nRestore Workspace from Backup\n\nBackup: /path/.workspace_backups/my-workspace_backup_20251006_1200\nOriginal path: /path/to/workspace\nCreated: 2025-10-06T12:00:00Z\nReason: pre_migration\n\n⚠ This will replace the current workspace at:\n  /path/to/workspace\n\nContinue with restore? (y/N): y\n\n✓ Workspace restored from backup\n```\n\n---\n\n## Command Reference\n\n### Workspace Version Commands\n\n```\n# Show workspace version information\nprovisioning workspace version [workspace-name] [--format table|json|yaml]\n\n# Check compatibility\nprovisioning workspace check-compatibility [workspace-name]\n\n# Migrate workspace\nprovisioning workspace migrate [workspace-name] [--skip-backup] [--force] [--target-version VERSION]\n\n# List backups\nprovisioning workspace list-backups [workspace-name]\n\n# Restore from backup\nprovisioning workspace restore-backup <backup-path> [--force]\n```\n\n### Workspace Management Commands\n\n```\n# List all workspaces\nprovisioning workspace list\n\n# Show active workspace\nprovisioning workspace active\n\n# Activate workspace\nprovisioning workspace activate <name>\n\n# Create new workspace (includes metadata initialization)\nprovisioning workspace init <name> [path]\n\n# Register existing workspace\nprovisioning workspace register <name> <path>\n\n# Remove workspace from registry\nprovisioning workspace remove <name> [--force]\n```\n\n---\n\n## Troubleshooting\n\n### Problem: "No active workspace"\n\n**Solution**: Activate or create a workspace\n\n```\n# List available workspaces\nprovisioning workspace list\n\n# Activate existing workspace\nprovisioning workspace activate my-workspace\n\n# Or create new workspace\nprovisioning workspace init new-workspace\n```\n\n### Problem: "Workspace has invalid structure"\n\n**Symptoms**: Missing directories or configuration files\n\n**Solution**: Run migration to fix structure\n\n```\nprovisioning workspace migrate my-workspace\n```\n\n### Problem: "Workspace version is incompatible"\n\n**Solution**: Run migration to upgrade workspace\n\n```\nprovisioning workspace migrate\n```\n\n### Problem: Migration Failed\n\n**Solution**: Restore from automatic backup\n\n```\n# List backups\nprovisioning workspace list-backups\n\n# Restore from most recent backup\nprovisioning workspace restore-backup /path/to/backup\n```\n\n### Problem: Can't Activate Workspace After Migration\n\n**Possible Causes**:\n\n1. Migration failed partially\n2. Workspace path changed\n3. Metadata corrupted\n\n**Solutions**:\n\n```\n# Check workspace compatibility\nprovisioning workspace check-compatibility my-workspace\n\n# If corrupted, restore from backup\nprovisioning workspace restore-backup /path/to/backup\n\n# If path changed, re-register\nprovisioning workspace remove my-workspace\nprovisioning workspace register my-workspace /new/path --activate\n```\n\n---\n\n## Best Practices\n\n### 1. Always Use Named Workspaces\n\nCreate workspaces for different environments:\n\n```\nprovisioning workspace init dev ~/workspaces/dev --activate\nprovisioning workspace init staging ~/workspaces/staging\nprovisioning workspace init production ~/workspaces/production\n```\n\n### 2. Let System Create Backups\n\nNever use `--skip-backup` for important workspaces. Backups are cheap, data loss is expensive.\n\n```\n# Good: Default with backup\nprovisioning workspace migrate\n\n# Risky: No backup\nprovisioning workspace migrate --skip-backup  # DON'T DO THIS\n```\n\n### 3. Check Compatibility Before Operations\n\nBefore major operations, verify workspace compatibility:\n\n```\nprovisioning workspace check-compatibility\n```\n\n### 4. Migrate After System Upgrades\n\nAfter upgrading the provisioning system:\n\n```\n# Check if migration available\nprovisioning workspace version\n\n# Migrate if needed\nprovisioning workspace migrate\n```\n\n### 5. Keep Backups for Safety\n\nDon't immediately delete old backups:\n\n```\n# List backups\nprovisioning workspace list-backups\n\n# Keep at least 2-3 recent backups\n```\n\n### 6. Use Version Control for Workspace Configs\n\nInitialize git in workspace directory:\n\n```\ncd ~/workspaces/my-workspace\ngit init\ngit add config/ infra/\ngit commit -m "Initial workspace configuration"\n```\n\nExclude runtime and cache directories in `.gitignore`:\n\n```\n.cache/\n.runtime/\n.provisioning/\n.workspace_backups/\n```\n\n### 7. Document Custom Migrations\n\nIf you need custom migration steps, document them:\n\n```\n# Create migration notes\necho "Custom steps for v2 to v3 migration" > MIGRATION_NOTES.md\n```\n\n---\n\n## Migration History\n\nEach migration is recorded in workspace metadata:\n\n```\nmigration_history:\n  - from_version: "unknown"\n    to_version: "2.0.5"\n    migration_type: "metadata_initialization"\n    timestamp: "2025-10-06T12:00:00Z"\n    success: true\n    notes: "Initial metadata creation"\n\n  - from_version: "2.0.5"\n    to_version: "2.1.0"\n    migration_type: "version_update"\n    timestamp: "2025-10-15T10:30:00Z"\n    success: true\n    notes: "Updated to workspace switching support"\n```\n\nView migration history:\n\n```\nprovisioning workspace version --format yaml | grep -A 10 "migration_history"\n```\n\n---\n\n## Summary\n\nThe workspace enforcement and version tracking system provides:\n\n- **Safety**: Mandatory workspace prevents accidental operations outside defined environments\n- **Compatibility**: Version tracking ensures workspace works with current system\n- **Upgradability**: Migration framework handles version transitions safely\n- **Recoverability**: Automatic backups protect against migration failures\n\n**Key Commands**:\n\n```\n# Create workspace\nprovisioning workspace init my-workspace --activate\n\n# Check version\nprovisioning workspace version\n\n# Migrate if needed\nprovisioning workspace migrate\n\n# List backups\nprovisioning workspace list-backups\n```\n\nFor more information, see:\n\n- **Workspace Switching Guide**: `docs/user/WORKSPACE_SWITCHING_GUIDE.md`\n- **Quick Reference**: `provisioning sc` or `provisioning guide quickstart`\n- **Help System**: `provisioning help workspace`\n\n---\n\n**Questions or Issues?**\n\nCheck the troubleshooting section or run:\n\n```\nprovisioning workspace check-compatibility\n```\n\nThis will provide specific guidance for your situation.
