12 KiB
12 KiB
\nprovisioning workspace list\n\n\nOutput:\n\n\nRegistered Workspaces:\n\n ● librecloud\n Path: /Users/Akasha/project-provisioning/workspace_librecloud\n Last used: 2025-10-06T12:29:43Z\n\n production\n Path: /opt/workspaces/production\n Last used: 2025-10-05T10:15:30Z\n\n\nThe green ● indicates the currently active workspace.\n\n### Check Active Workspace\n\n\nprovisioning workspace active\n\n\nOutput:\n\n\nActive Workspace:\n Name: librecloud\n Path: /Users/Akasha/project-provisioning/workspace_librecloud\n Last used: 2025-10-06T12:29:43Z\n\n\n### Switch to Another Workspace\n\n\n# Option 1: Using activate\nprovisioning workspace activate production\n\n# Option 2: Using switch (alias)\nprovisioning workspace switch production\n\n\nOutput:\n\n\n✓ Workspace 'production' activated\n\nCurrent workspace: production\nPath: /opt/workspaces/production\n\nℹ All provisioning commands will now use this workspace\n\n\n### Register a New Workspace\n\n\n# Register without activating\nprovisioning workspace register my-project ~/workspaces/my-project\n\n# Register and activate immediately\nprovisioning workspace register my-project ~/workspaces/my-project --activate\n\n\n### Remove Workspace from Registry\n\n\n# With confirmation prompt\nprovisioning workspace remove old-workspace\n\n# Skip confirmation\nprovisioning workspace remove old-workspace --force\n\n\nNote: This only removes the workspace from the registry. The workspace files are NOT deleted.\n\n## Architecture\n\n### Central User Configuration\n\nAll workspace information is stored in a central user configuration file:\n\nLocation: ~/Library/Application Support/provisioning/user_config.yaml\n\nStructure:\n\n\n# Active workspace (current workspace in use)\nactive_workspace: "librecloud"\n\n# Known workspaces (automatically managed)\nworkspaces:\n - name: "librecloud"\n path: "/Users/Akasha/project-provisioning/workspace_librecloud"\n last_used: "2025-10-06T12:29:43Z"\n\n - name: "production"\n path: "/opt/workspaces/production"\n last_used: "2025-10-05T10:15:30Z"\n\n# User preferences (global settings)\npreferences:\n editor: "vim"\n output_format: "yaml"\n confirm_delete: true\n confirm_deploy: true\n default_log_level: "info"\n preferred_provider: "upcloud"\n\n# Metadata\nmetadata:\n created: "2025-10-06T12:29:43Z"\n last_updated: "2025-10-06T13:46:16Z"\n version: "1.0.0"\n\n\n### How It Works\n\n1. Workspace Registration: When you register a workspace, it's added to the workspaces list in user_config.yaml\n\n2. Activation: When you activate a workspace:\n - active_workspace is updated to the workspace name\n - The workspace's last_used timestamp is updated\n - All provisioning commands now use this workspace's configuration\n\n3. Configuration Loading: The config loader reads active_workspace from user_config.yaml and loads:\n - workspace_path/config/provisioning.yaml\n - workspace_path/config/providers/*.toml\n - workspace_path/config/platform/*.toml\n - workspace_path/config/kms.toml\n\n## Advanced Features\n\n### User Preferences\n\nYou can set global user preferences that apply across all workspaces:\n\n\n# Get a preference value\nprovisioning workspace get-preference editor\n\n# Set a preference value\nprovisioning workspace set-preference editor "code"\n\n# View all preferences\nprovisioning workspace preferences\n\n\nAvailable Preferences:\n\n- editor: Default editor for config files (vim, code, nano, etc.)\n- output_format: Default output format (yaml, json, toml)\n- confirm_delete: Require confirmation for deletions (true/false)\n- confirm_deploy: Require confirmation for deployments (true/false)\n- default_log_level: Default log level (debug, info, warn, error)\n- preferred_provider: Preferred cloud provider (aws, upcloud, local)\n\n### Output Formats\n\nList workspaces in different formats:\n\n\n# Table format (default)\nprovisioning workspace list\n\n# JSON format\nprovisioning workspace list --format json\n\n# YAML format\nprovisioning workspace list --format yaml\n\n\n### Quiet Mode\n\nActivate workspace without output messages:\n\n\nprovisioning workspace activate production --quiet\n\n\n## Workspace Requirements\n\nFor a workspace to be activated, it must have:\n\n1. Directory exists: The workspace directory must exist on the filesystem\n\n2. Config directory: Must have a config/ directory\n\n bash\n\n workspace_name/\n └── config/\n ├── provisioning.yaml # Required\n ├── providers/ # Optional\n ├── platform/ # Optional\n └── kms.toml # Optional\n\n\n\n3. Main config file: Must have config/provisioning.yaml\n\nIf these requirements are not met, the activation will fail with helpful error messages:\n\n\n✗ Workspace 'my-project' not found in registry\n💡 Available workspaces:\n [list of workspaces]\n💡 Register it first with: provisioning workspace register my-project <path>\n\n\n\n✗ Workspace is not migrated to new config system\n💡 Missing: /path/to/workspace/config\n💡 Run migration: provisioning workspace migrate my-project\n\n\n## Migration from Old System\n\nIf you have workspaces using the old context system (ws_{name}.yaml files), they still work but you should register them in the new system:\n\n\n# Register existing workspace\nprovisioning workspace register old-workspace ~/workspaces/old-workspace\n\n# Activate it\nprovisioning workspace activate old-workspace\n\n\nThe old ws_{name}.yaml files are still supported for backward compatibility, but the new centralized system is recommended.\n\n## Best Practices\n\n### 1. One Active Workspace at a Time\n\nOnly one workspace can be active at a time. All provisioning commands use the active workspace's configuration.\n\n### 2. Use Descriptive Names\n\nUse clear, descriptive names for your workspaces:\n\n\n# ✅ Good\nprovisioning workspace register production-us-east ~/workspaces/prod-us-east\nprovisioning workspace register dev-local ~/workspaces/dev\n\n# ❌ Avoid\nprovisioning workspace register ws1 ~/workspaces/workspace1\nprovisioning workspace register temp ~/workspaces/t\n\n\n### 3. Keep Workspaces Organized\n\nStore all workspaces in a consistent location:\n\n\n~/workspaces/\n├── production/\n├── staging/\n├── development/\n└── testing/\n\n\n### 4. Regular Cleanup\n\nRemove workspaces you no longer use:\n\n\n# List workspaces to see which ones are unused\nprovisioning workspace list\n\n# Remove old workspace\nprovisioning workspace remove old-workspace\n\n\n### 5. Backup User Config\n\nPeriodically backup your user configuration:\n\n\ncp "~/Library/Application Support/provisioning/user_config.yaml" \\n "~/Library/Application Support/provisioning/user_config.yaml.backup"\n\n\n## Troubleshooting\n\n### Workspace Not Found\n\nProblem: ✗ Workspace 'name' not found in registry\n\nSolution: Register the workspace first:\n\n\nprovisioning workspace register name /path/to/workspace\n\n\n### Missing Configuration\n\nProblem: ✗ Missing workspace configuration\n\nSolution: Ensure the workspace has a config/provisioning.yaml file. Run migration if needed:\n\n\nprovisioning workspace migrate name\n\n\n### Directory Not Found\n\nProblem: ✗ Workspace directory not found: /path/to/workspace\n\nSolution:\n\n1. Check if the workspace was moved or deleted\n2. Update the path or remove from registry:\n\n\nprovisioning workspace remove name\nprovisioning workspace register name /new/path\n\n\n### Corrupted User Config\n\nProblem: Error: Failed to parse user config\n\nSolution: The system automatically creates a backup and regenerates the config. Check:\n\n\nls -la "~/Library/Application Support/provisioning/user_config.yaml"*\n\n\nRestore from backup if needed:\n\n\ncp "~/Library/Application Support/provisioning/user_config.yaml.backup.TIMESTAMP" \\n "~/Library/Application Support/provisioning/user_config.yaml"\n\n\n## CLI Commands Reference\n\n| Command | Alias | Description |\n| --------- | ------- | ------------- |\n| provisioning workspace activate <name> | - | Activate a workspace |\n| provisioning workspace switch <name> | - | Alias for activate |\n| provisioning workspace list | - | List all registered workspaces |\n| provisioning workspace active | - | Show currently active workspace |\n| provisioning workspace register <name> <path> | - | Register a new workspace |\n| provisioning workspace remove <name> | - | Remove workspace from registry |\n| provisioning workspace preferences | - | Show user preferences |\n| provisioning workspace set-preference <key> <value> | - | Set a preference |\n| provisioning workspace get-preference <key> | - | Get a preference value |\n\n## Integration with Config System\n\nThe workspace switching system is fully integrated with the new target-based configuration system:\n\n### Configuration Hierarchy (Priority: Low → High)\n\n\n1. Workspace config workspace/{name}/config/provisioning.yaml\n2. Provider configs workspace/{name}/config/providers/*.toml\n3. Platform configs workspace/{name}/config/platform/*.toml\n4. User context ~/Library/Application Support/provisioning/ws_{name}.yaml (legacy)\n5. User config ~/Library/Application Support/provisioning/user_config.yaml (new)\n6. Environment variables PROVISIONING_*\n\n\n### Example Workflow\n\n\n# 1. Create and activate development workspace\nprovisioning workspace register dev ~/workspaces/dev --activate\n\n# 2. Work on development\nprovisioning server create web-dev-01\nprovisioning taskserv create kubernetes\n\n# 3. Switch to production\nprovisioning workspace switch production\n\n# 4. Deploy to production\nprovisioning server create web-prod-01\nprovisioning taskserv create kubernetes\n\n# 5. Switch back to development\nprovisioning workspace switch dev\n\n# All commands now use dev workspace config\n\n\n## Nickel Workspace Configuration\n\nStarting with v3.7.0, workspaces use Nickel for type-safe, schema-validated configurations.\n\n### Nickel Configuration Features\n\nNickel Configuration (Type-Safe):\n\n\n{\n workspace = {\n name = "myworkspace",\n version = "1.0.0",\n },\n paths = {\n base = "/path/to/workspace",\n infra = "/path/to/workspace/infra",\n config = "/path/to/workspace/config",\n },\n}\n\n\n### Benefits of Nickel Configuration\n\n- ✅ Type Safety: Catch configuration errors at load time, not runtime\n- ✅ Schema Validation: Required fields, value constraints, format checking\n- ✅ Lazy Evaluation: Only computes what's needed\n- ✅ Self-Documenting: Records provide instant documentation\n- ✅ Merging: Powerful record merging for composition\n\n### Viewing Workspace Configuration\n\n\n# View your Nickel workspace configuration\nprovisioning workspace config show\n\n# View in different formats\nprovisioning workspace config show --format=yaml # YAML output\nprovisioning workspace config show --format=json # JSON output\nprovisioning workspace config show --format=nickel # Raw Nickel file\n\n# Validate configuration\nprovisioning workspace config validate\n# Output: ✅ Validation complete - all configs are valid\n\n# Show configuration hierarchy\nprovisioning workspace config hierarchy\n\n\n## See Also\n\n- Configuration Guide: docs/architecture/adr/ADR-010-configuration-format-strategy.md\n- Migration Guide: Nickel Migration\n- From-Scratch Guide: From-Scratch Guide\n- Nickel Patterns: Nickel Language Module System\n\n---\n\nMaintained By: Infrastructure Team\nVersion: 2.0.0 (Updated for Nickel)\nStatus: ✅ Production Ready\nLast Updated: 2025-12-03