provisioning/docs/src/infrastructure/workspaces/workspace-switching-guide.md

# Workspace Switching Guide

**Version**: 1.0.0
**Date**: 2025-10-06
**Status**: ✅ Production Ready

## Overview

The provisioning system now includes a centralized workspace management system that allows you to easily switch between multiple workspaces without
manually editing configuration files.

## Quick Start

### List Available Workspaces

```text
provisioning workspace list
```

Output:

```text
Registered Workspaces:

  ● librecloud
      Path: /Users/Akasha/project-provisioning/workspace_librecloud
      Last used: 2025-10-06T12:29:43Z

    production
      Path: /opt/workspaces/production
      Last used: 2025-10-05T10:15:30Z
```

The green ● indicates the currently active workspace.

### Check Active Workspace

```text
provisioning workspace active
```

Output:

```text
Active Workspace:
  Name: librecloud
  Path: /Users/Akasha/project-provisioning/workspace_librecloud
  Last used: 2025-10-06T12:29:43Z
```

### Switch to Another Workspace

```text
# Option 1: Using activate
provisioning workspace activate production

# Option 2: Using switch (alias)
provisioning workspace switch production
```

Output:

```text
✓ Workspace 'production' activated

Current workspace: production
Path: /opt/workspaces/production

ℹ All provisioning commands will now use this workspace
```

### Register a New Workspace

```text
# Register without activating
provisioning workspace register my-project ~/workspaces/my-project

# Register and activate immediately
provisioning workspace register my-project ~/workspaces/my-project --activate
```

### Remove Workspace from Registry

```text
# With confirmation prompt
provisioning workspace remove old-workspace

# Skip confirmation
provisioning workspace remove old-workspace --force
```

**Note**: This only removes the workspace from the registry. The workspace files are NOT deleted.

## Architecture

### Central User Configuration

All workspace information is stored in a central user configuration file:

**Location**: `~/Library/Application Support/provisioning/user_config.yaml`

**Structure**:

```text
# Active workspace (current workspace in use)
active_workspace: "librecloud"

# Known workspaces (automatically managed)
workspaces:
  - name: "librecloud"
    path: "/Users/Akasha/project-provisioning/workspace_librecloud"
    last_used: "2025-10-06T12:29:43Z"

  - name: "production"
    path: "/opt/workspaces/production"
    last_used: "2025-10-05T10:15:30Z"

# User preferences (global settings)
preferences:
  editor: "vim"
  output_format: "yaml"
  confirm_delete: true
  confirm_deploy: true
  default_log_level: "info"
  preferred_provider: "upcloud"

# Metadata
metadata:
  created: "2025-10-06T12:29:43Z"
  last_updated: "2025-10-06T13:46:16Z"
  version: "1.0.0"
```

### How It Works

1. **Workspace Registration**: When you register a workspace, it's added to the `workspaces` list in `user_config.yaml`

2. **Activation**: When you activate a workspace:
   - `active_workspace` is updated to the workspace name
   - The workspace's `last_used` timestamp is updated
   - All provisioning commands now use this workspace's configuration

3. **Configuration Loading**: The config loader reads `active_workspace` from `user_config.yaml` and loads:
   - `workspace_path/config/provisioning.yaml`
   - `workspace_path/config/providers/*.toml`
   - `workspace_path/config/platform/*.toml`
   - `workspace_path/config/kms.toml`

## Advanced Features

### User Preferences

You can set global user preferences that apply across all workspaces:

```text
# Get a preference value
provisioning workspace get-preference editor

# Set a preference value
provisioning workspace set-preference editor "code"

# View all preferences
provisioning workspace preferences
```

**Available Preferences**:

- `editor`: Default editor for config files (vim, code, nano, etc.)
- `output_format`: Default output format (yaml, json, toml)
- `confirm_delete`: Require confirmation for deletions (true/false)
- `confirm_deploy`: Require confirmation for deployments (true/false)
- `default_log_level`: Default log level (debug, info, warn, error)
- `preferred_provider`: Preferred cloud provider (aws, upcloud, local)

### Output Formats

List workspaces in different formats:

```text
# Table format (default)
provisioning workspace list

# JSON format
provisioning workspace list --format json

# YAML format
provisioning workspace list --format yaml
```

### Quiet Mode

Activate workspace without output messages:

```text
provisioning workspace activate production --quiet
```

## Workspace Requirements

For a workspace to be activated, it must have:

1. **Directory exists**: The workspace directory must exist on the filesystem

2. **Config directory**: Must have a `config/` directory

   ```bash

   workspace_name/
   └── config/
       ├── provisioning.yaml  # Required
       ├── providers/         # Optional
       ├── platform/          # Optional
       └── kms.toml           # Optional

```text

3. **Main config file**: Must have `config/provisioning.yaml`

If these requirements are not met, the activation will fail with helpful error messages:

```
✗ Workspace 'my-project' not found in registry
💡 Available workspaces:
   [list of workspaces]
💡 Register it first with: provisioning workspace register my-project <path>
```text

```
✗ Workspace is not migrated to new config system
💡 Missing: /path/to/workspace/config
💡 Run migration: provisioning workspace migrate my-project
```text

## Migration from Old System

If you have workspaces using the old context system (`ws_{name}.yaml` files), they still work but you should register them in the new system:

```
# Register existing workspace
provisioning workspace register old-workspace ~/workspaces/old-workspace

# Activate it
provisioning workspace activate old-workspace
```text

The old `ws_{name}.yaml` files are still supported for backward compatibility, but the new centralized system is recommended.

## Best Practices

### 1. **One Active Workspace at a Time**

Only one workspace can be active at a time. All provisioning commands use the active workspace's configuration.

### 2. **Use Descriptive Names**

Use clear, descriptive names for your workspaces:

```
# ✅ Good
provisioning workspace register production-us-east ~/workspaces/prod-us-east
provisioning workspace register dev-local ~/workspaces/dev

# ❌ Avoid
provisioning workspace register ws1 ~/workspaces/workspace1
provisioning workspace register temp ~/workspaces/t
```text

### 3. **Keep Workspaces Organized**

Store all workspaces in a consistent location:

```
~/workspaces/
├── production/
├── staging/
├── development/
└── testing/
```text

### 4. **Regular Cleanup**

Remove workspaces you no longer use:

```
# List workspaces to see which ones are unused
provisioning workspace list

# Remove old workspace
provisioning workspace remove old-workspace
```text

### 5. **Backup User Config**

Periodically backup your user configuration:

```
cp "~/Library/Application Support/provisioning/user_config.yaml" 
   "~/Library/Application Support/provisioning/user_config.yaml.backup"
```text

## Troubleshooting

### Workspace Not Found

**Problem**: `✗ Workspace 'name' not found in registry`

**Solution**: Register the workspace first:

```
provisioning workspace register name /path/to/workspace
```text

### Missing Configuration

**Problem**: `✗ Missing workspace configuration`

**Solution**: Ensure the workspace has a `config/provisioning.yaml` file. Run migration if needed:

```
provisioning workspace migrate name
```text

### Directory Not Found

**Problem**: `✗ Workspace directory not found: /path/to/workspace`

**Solution**:

1. Check if the workspace was moved or deleted
2. Update the path or remove from registry:

```
provisioning workspace remove name
provisioning workspace register name /new/path
```text

### Corrupted User Config

**Problem**: `Error: Failed to parse user config`

**Solution**: The system automatically creates a backup and regenerates the config. Check:

```
ls -la "~/Library/Application Support/provisioning/user_config.yaml"*
```text

Restore from backup if needed:

```
cp "~/Library/Application Support/provisioning/user_config.yaml.backup.TIMESTAMP" 
   "~/Library/Application Support/provisioning/user_config.yaml"
```text

## CLI Commands Reference

| Command | Alias | Description |
| --------- | ------- | ------------- |
| `provisioning workspace activate <name>` | - | Activate a workspace |
| `provisioning workspace switch <name>` | - | Alias for activate |
| `provisioning workspace list` | - | List all registered workspaces |
| `provisioning workspace active` | - | Show currently active workspace |
| `provisioning workspace register <name> <path>` | - | Register a new workspace |
| `provisioning workspace remove <name>` | - | Remove workspace from registry |
| `provisioning workspace preferences` | - | Show user preferences |
| `provisioning workspace set-preference <key> <value>` | - | Set a preference |
| `provisioning workspace get-preference <key>` | - | Get a preference value |

## Integration with Config System

The workspace switching system is fully integrated with the new target-based configuration system:

### Configuration Hierarchy (Priority: Low → High)

```
1. Workspace config      workspace/{name}/config/provisioning.yaml
2. Provider configs      workspace/{name}/config/providers/*.toml
3. Platform configs      workspace/{name}/config/platform/*.toml
4. User context          ~/Library/Application Support/provisioning/ws_{name}.yaml (legacy)
5. User config           ~/Library/Application Support/provisioning/user_config.yaml (new)
6. Environment variables PROVISIONING_*
```text

### Example Workflow

```
# 1. Create and activate development workspace
provisioning workspace register dev ~/workspaces/dev --activate

# 2. Work on development
provisioning server create web-dev-01
provisioning taskserv create kubernetes

# 3. Switch to production
provisioning workspace switch production

# 4. Deploy to production
provisioning server create web-prod-01
provisioning taskserv create kubernetes

# 5. Switch back to development
provisioning workspace switch dev

# All commands now use dev workspace config
```text

## Nickel Workspace Configuration

Starting with v3.7.0, workspaces use **Nickel** for type-safe, schema-validated configurations.

### Nickel Configuration Features

**Nickel Configuration** (Type-Safe):

```
{
  workspace = {
    name = "myworkspace",
    version = "1.0.0",
  },
  paths = {
    base = "/path/to/workspace",
    infra = "/path/to/workspace/infra",
    config = "/path/to/workspace/config",
  },
}
```text

### Benefits of Nickel Configuration

- ✅ **Type Safety**: Catch configuration errors at load time, not runtime
- ✅ **Schema Validation**: Required fields, value constraints, format checking
- ✅ **Lazy Evaluation**: Only computes what's needed
- ✅ **Self-Documenting**: Records provide instant documentation
- ✅ **Merging**: Powerful record merging for composition

### Viewing Workspace Configuration

```
# View your Nickel workspace configuration
provisioning workspace config show

# View in different formats
provisioning workspace config show --format=yaml    # YAML output
provisioning workspace config show --format=json    # JSON output
provisioning workspace config show --format=nickel  # Raw Nickel file

# Validate configuration
provisioning workspace config validate
# Output: ✅ Validation complete - all configs are valid

# Show configuration hierarchy
provisioning workspace config hierarchy
```text

## See Also

- **Configuration Guide**: `docs/architecture/adr/ADR-010-configuration-format-strategy.md`
- **Migration Guide**: [Nickel Migration](../architecture/adr/adr-011-nickel-migration.md)
- **From-Scratch Guide**: [From-Scratch Guide](../guides/from-scratch.md)
- **Nickel Patterns**: Nickel Language Module System

---

**Maintained By**: Infrastructure Team
**Version**: 2.0.0 (Updated for Nickel)
**Status**: ✅ Production Ready
**Last Updated**: 2025-12-03