provisioning/config/templates/WORKSPACE_CONFIG_TEMPLATES.md

# Workspace Configuration Templates

This directory contains templates for creating new workspace configurations using the KCL SST (Single Source of Truth) pattern.

## Files

### Workspace Root

- **`kcl.mod.template`** → `{workspace}/kcl.mod`
  - Top-level KCL package definition
  - Declares dependency on `.provisioning` package

### `.provisioning/` Directory

- **`workspace-config-schema.k.template`** → `{workspace}/.provisioning/workspace_config.k`
  - Schema definitions (SST - Single Source of Truth)
  - Type-safe WorkspaceConfig schema
  - Validation rules
  - **Do not modify per-workspace** - update the template to change all workspaces

- **`workspace-config-defaults.k.template`** → `{workspace}/.provisioning/workspace_config_defaults.k`
  - Default values for all configuration sections
  - Base configuration that all workspaces inherit
  - **Do not modify per-workspace** - update the template to change all workspaces

- **`.provisioning-kcl.mod.template`** → `{workspace}/.provisioning/kcl.mod`
  - KCL package definition for `.provisioning` package
  - Package name is "provisioning"

### `config/` Directory

- **`config-kcl.mod.template`** → `{workspace}/config/kcl.mod`
  - KCL package definition for workspace config
  - Declares dependency on `provisioning` package (from `.provisioning/`)

- **`workspace-config.k.template`** → `{workspace}/config/provisioning.k`
  - Workspace-specific configuration overrides
  - Imports defaults from `.provisioning/workspace_config_defaults.k`
  - Only contains values that differ from defaults
  - **This is the only file that changes per-workspace**

## SST Pattern Architecture

```
.provisioning/
├── workspace_config.k              (Schema definitions)
├── workspace_config_defaults.k     (Default values - inherited by all)
└── kcl.mod                         (Package definition)

config/
├── provisioning.k                  (Workspace overrides - ONLY THIS CHANGES)
└── kcl.mod                         (Config package definition)

kcl.mod                             (Workspace package definition)
```

## How New Workspaces Are Created

### 1. Generate from Templates

When creating a new workspace, the provisioning system:

1. Creates `{workspace}/kcl.mod` from `kcl.mod.template`
   - Replace `{{WORKSPACE_NAME}}` with actual workspace name

2. Creates `.provisioning/` directory with:
   - `workspace_config.k` from `workspace-config-schema.k.template`
   - `workspace_config_defaults.k` from `workspace-config-defaults.k.template`
   - `kcl.mod` from `.provisioning-kcl.mod.template`

3. Creates `config/` directory with:
   - `kcl.mod` from `config-kcl.mod.template`
   - `provisioning.k` from `workspace-config.k.template`
     - Replace `{{WORKSPACE_NAME}}` with actual workspace name
     - Replace `{{WORKSPACE_PATH}}` with actual path
     - Replace `{{PROVISIONING_PATH}}` with actual provisioning path
     - Replace `{{CREATED_TIMESTAMP}}` with ISO 8601 timestamp

### 2. Verification

After generation, verify with:

```bash
cd {workspace}/config
kcl run provisioning.k
```

Output should be valid YAML with all configuration sections populated.

## Maintenance

### Updating All Workspaces

To change defaults or schema for all workspaces:

1. **Update schema**: Edit `workspace-config-schema.k.template`
2. **Update defaults**: Edit `workspace-config-defaults.k.template`
3. **Regenerate all workspaces**: Run provisioning sync command
   - This copies the templates to each workspace's `.provisioning/`

Existing workspace overrides in `config/provisioning.k` are not affected.

### Adding New Configuration Sections

1. Add schema to `workspace-config-schema.k.template`
2. Add defaults to `workspace-config-defaults.k.template`
3. New workspaces automatically inherit the new section
4. Existing workspaces get the new defaults (no action needed)

## Template Variables

- `{{WORKSPACE_NAME}}` - Name of the workspace (e.g., "librecloud")
- `{{WORKSPACE_PATH}}` - Absolute path to workspace
- `{{PROVISIONING_PATH}}` - Absolute path to provisioning system
- `{{CREATED_TIMESTAMP}}` - ISO 8601 timestamp of creation
- `{{INFRA_NAME}}` - Infrastructure name (e.g., "default")

## Example: Creating a New Workspace

```bash
# Step 1: Create workspace structure
mkdir -p my-workspace/.provisioning my-workspace/config

# Step 2: Generate from templates
provisioning workspace init my-workspace \
  --from-templates \
  --workspace-path /path/to/my-workspace \
  --provisioning-path /path/to/provisioning

# Step 3: Verify configuration
cd my-workspace/config
kcl run provisioning.k

# Step 4: Make workspace-specific overrides if needed
# Edit config/provisioning.k to override any defaults
```

## Template Extension Convention: `.template`

These workspace initialization templates use the **`.template`** extension for specific reasons:

### Why `.template` (Not `.j2`)?

- **Simple substitution only**: Just `{{variable}}` replacement, no complex logic
- **No plugin dependency**: Works without `nu_plugin_tera`, more portable
- **Semantic clarity**: Extension signals "initialization" vs "runtime rendering"
- **Appropriate complexity**: Simple initialization doesn't need Jinja2 power

**Note**: Runtime configuration templates use `.j2` (Jinja2). See `README.md` for complete conventions.

## Benefits of SST Pattern

✅ **DRY** - Schema and defaults defined once
✅ **Maintainable** - Update templates to change all workspaces
✅ **Type-safe** - Full validation against schema
✅ **Clear intent** - See exactly what's customized per-workspace
✅ **Inheritance** - New workspaces automatically get new defaults
✅ **Mergeable** - KCL `|` operator for clean overrides