provisioning/docs/src/infrastructure/workspace-infra-reference.md

Unified Workspace:Infrastructure Reference System

Version: 1.0.0 Last Updated: 2025-12-04

Overview

The Workspace:Infrastructure Reference System provides a unified notation for managing workspaces and their associated infrastructure. This system eliminates the need to specify infrastructure separately and enables convenient defaults.

Quick Start

Temporal Override (Single Command)

Use the -ws flag with workspace:infra notation:

# Use production workspace with sgoyol infrastructure for this command only
provisioning server list -ws production:sgoyol

# Use default infrastructure of active workspace
provisioning taskserv create kubernetes
```plaintext

### Persistent Activation

Activate a workspace with a default infrastructure:

```bash
# Activate librecloud workspace and set wuji as default infra
provisioning workspace activate librecloud:wuji

# Now all commands use librecloud:wuji by default
provisioning server list
```plaintext

## Notation Syntax

### Basic Format

```plaintext
workspace:infra
```plaintext

| Part | Description | Example |
|------|-------------|---------|
| `workspace` | Workspace name | `librecloud` |
| `:` | Separator | - |
| `infra` | Infrastructure name | `wuji` |

### Examples

| Notation | Workspace | Infrastructure |
|----------|-----------|-----------------|
| `librecloud:wuji` | librecloud | wuji |
| `production:sgoyol` | production | sgoyol |
| `dev:local` | dev | local |
| `librecloud` | librecloud | (from default or context) |

## Resolution Priority

When no infrastructure is explicitly specified, the system uses this priority order:

1. **Explicit `--infra` flag** (highest)

   ```bash
   provisioning server list --infra another-infra

1. PWD Detection

   cd workspace_librecloud/infra/wuji
   provisioning server list  # Auto-detects wuji
   

2. Default Infrastructure

   # If workspace has default_infra set
   provisioning server list  # Uses configured default
   

3. Error (no infra found)

   # Error: No infrastructure specified
   

Usage Patterns

Pattern 1: Temporal Override for Commands

Use -ws to override workspace:infra for a single command:

# Currently in librecloud:wuji context
provisioning server list  # Shows librecloud:wuji

# Temporary override for this command only
provisioning server list -ws production:sgoyol  # Shows production:sgoyol

# Back to original context
provisioning server list  # Shows librecloud:wuji again
```plaintext

### Pattern 2: Persistent Workspace Activation

Set a workspace as active with a default infrastructure:

```bash
# List available workspaces
provisioning workspace list

# Activate with infra notation
provisioning workspace activate production:sgoyol

# All subsequent commands use production:sgoyol
provisioning server list
provisioning taskserv create kubernetes
```plaintext

### Pattern 3: PWD-Based Inference

The system auto-detects workspace and infrastructure from your current directory:

```bash
# Your workspace structure
workspace_librecloud/
  infra/
    wuji/
      settings.ncl
    another/
      settings.ncl

# Navigation auto-detects context
cd workspace_librecloud/infra/wuji
provisioning server list  # Uses wuji automatically

cd ../another
provisioning server list  # Switches to another
```plaintext

### Pattern 4: Default Infrastructure Management

Set a workspace-specific default infrastructure:

```bash
# During activation
provisioning workspace activate librecloud:wuji

# Or explicitly after activation
provisioning workspace set-default-infra librecloud another-infra

# View current defaults
provisioning workspace list
```plaintext

## Command Reference

### Workspace Commands

```bash
# Activate workspace with infra
provisioning workspace activate workspace:infra

# Switch to different workspace
provisioning workspace switch workspace_name

# List all workspaces
provisioning workspace list

# Show active workspace
provisioning workspace active

# Set default infrastructure
provisioning workspace set-default-infra workspace_name infra_name

# Get default infrastructure
provisioning workspace get-default-infra workspace_name
```plaintext

### Common Commands with `-ws`

```bash
# Server operations
provisioning server create -ws workspace:infra
provisioning server list -ws workspace:infra
provisioning server delete name -ws workspace:infra

# Task service operations
provisioning taskserv create kubernetes -ws workspace:infra
provisioning taskserv delete kubernetes -ws workspace:infra

# Infrastructure operations
provisioning infra validate -ws workspace:infra
provisioning infra list -ws workspace:infra
```plaintext

## Features

### ✅ Unified Notation

- Single `workspace:infra` format for all references
- Works with all provisioning commands
- Backward compatible with existing workflows

### ✅ Temporal Override

- Use `-ws` flag for single-command overrides
- No permanent state changes
- Automatically reverted after command

### ✅ Persistent Defaults

- Set default infrastructure per workspace
- Eliminates repetitive `--infra` flags
- Survives across sessions

### ✅ Smart Detection

- Auto-detects workspace from directory
- Auto-detects infrastructure from PWD
- Fallback to configured defaults

### ✅ Error Handling

- Clear error messages when infra not found
- Validation of workspace and infra existence
- Helpful hints for missing configurations

## Environment Context

### TEMP_WORKSPACE Variable

The system uses `$env.TEMP_WORKSPACE` for temporal overrides:

```bash
# Set temporarily (via -ws flag automatically)
$env.TEMP_WORKSPACE = "production"

# Check current context
echo $env.TEMP_WORKSPACE

# Clear after use
hide-env TEMP_WORKSPACE
```plaintext

## Validation

### Validating Notation

```bash
# Valid notation formats
librecloud:wuji           # Standard format
production:sgoyol.v2      # With dots and hyphens
dev-01:local-test         # Multiple hyphens
prod123:infra456          # Numeric names

# Special characters
lib-cloud_01:wu-ji.v2    # Mix of all allowed chars
```plaintext

### Error Cases

```bash
# Workspace not found
provisioning workspace activate unknown:infra
# Error: Workspace 'unknown' not found in registry

# Infrastructure not found
provisioning workspace activate librecloud:unknown
# Error: Infrastructure 'unknown' not found in workspace 'librecloud'

# Empty specification
provisioning workspace activate ""
# Error: Workspace '' not found in registry
```plaintext

## Configuration

### User Configuration

Default infrastructure is stored in `~/Library/Application Support/provisioning/user_config.yaml`:

```yaml
active_workspace: "librecloud"

workspaces:
  - name: "librecloud"
    path: "/Users/you/workspaces/librecloud"
    last_used: "2025-12-04T12:00:00Z"
    default_infra: "wuji"  # Default infrastructure

  - name: "production"
    path: "/opt/workspaces/production"
    last_used: "2025-12-03T15:30:00Z"
    default_infra: "sgoyol"
```plaintext

### Workspace Schema

In `provisioning/schemas/workspace_config.ncl`:

```nickel
{
  InfraConfig = {
    current | String,  # Infrastructure context settings
    default | String | optional,  # Default infrastructure for workspace
  },
}
```plaintext

## Best Practices

### 1. Use Persistent Activation for Long Sessions

```bash
# Good: Activate at start of session
provisioning workspace activate production:sgoyol

# Then use simple commands
provisioning server list
provisioning taskserv create kubernetes
```plaintext

### 2. Use Temporal Override for Ad-Hoc Operations

```bash
# Good: Quick one-off operation
provisioning server list -ws production:other-infra

# Avoid: Repeated -ws flags
provisioning server list -ws prod:infra1
provisioning taskserv list -ws prod:infra1  # Better to activate once
```plaintext

### 3. Navigate with PWD for Context Awareness

```bash
# Good: Navigate to infrastructure directory
cd workspace_librecloud/infra/wuji
provisioning server list  # Auto-detects context

# Works well with: cd - history, terminal multiplexer panes
```plaintext

### 4. Set Meaningful Defaults

```bash
# Good: Default to production infrastructure
provisioning workspace activate production:main-infra

# Avoid: Default to dev infrastructure in production workspace
```plaintext

## Troubleshooting

### Issue: "Workspace not found in registry"

**Solution**: Register the workspace first

```bash
provisioning workspace register librecloud /path/to/workspace_librecloud
```plaintext

### Issue: "Infrastructure not found"

**Solution**: Verify infrastructure directory exists

```bash
ls workspace_librecloud/infra/  # Check available infras
provisioning workspace activate librecloud:wuji  # Use correct name
```plaintext

### Issue: Temporal override not working

**Solution**: Ensure you're using `-ws` flag correctly

```bash
# Correct
provisioning server list -ws production:sgoyol

# Incorrect (missing space)
provisioning server list-wsproduction:sgoyol

# Incorrect (ws is not a command)
provisioning -ws production:sgoyol server list
```plaintext

### Issue: PWD detection not working

**Solution**: Navigate to proper infrastructure directory

```bash
# Must be in workspace structure
cd workspace_name/infra/infra_name

# Then run command
provisioning server list
```plaintext

## Migration from Old System

### Old Way

```bash
provisioning workspace activate librecloud
provisioning --infra wuji server list
provisioning --infra wuji taskserv create kubernetes
```plaintext

### New Way

```bash
provisioning workspace activate librecloud:wuji
provisioning server list
provisioning taskserv create kubernetes
```plaintext

## Performance Notes

- **Notation parsing**: <1 ms per command
- **Workspace detection**: <5 ms from PWD
- **Workspace switching**: ~100 ms (includes platform activation)
- **Temporal override**: No additional overhead

## Backward Compatibility

All existing commands and flags continue to work:

```bash
# Old syntax still works
provisioning --infra wuji server list

# New syntax also works
provisioning server list -ws librecloud:wuji

# Mix and match
provisioning --infra other-infra server list -ws librecloud:wuji
# Uses other-infra (explicit flag takes priority)
```plaintext

## See Also

- `provisioning help workspace` - Workspace commands
- `provisioning help infra` - Infrastructure commands
- `docs/architecture/ARCHITECTURE_OVERVIEW.md` - Overall architecture
- `docs/user/WORKSPACE_SWITCHING_GUIDE.md` - Workspace switching details