container-superposition 0.1.6 → 0.1.8

package/docs/specs/010-compose-env-materialization/spec.md

@@ -0,0 +1,130 @@
+# Feature Specification: Compose Env Materialization and Env Template Naming
+
+**Feature Branch**: `codex/compose-env-materialization`
+**Created**: 2026-03-29
+**Status**: Implementing
+**Input**: User request
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/010-compose-env-materialization/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Pending
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 — Compose env values materialize into .devcontainer/.env (Priority: P1)
+
+A developer sets concrete env values in `superposition.yml` on a `compose` stack and expects
+them to be written to `.devcontainer/.env` (not embedded in `docker-compose.yml`) so that
+secrets are not committed to source control inside generated YAML.
+
+**Why this priority**: Embedding resolved values directly in `docker-compose.yml` would expose
+secrets or host-specific values in generated files that are typically committed to source control.
+Materializing them into `.devcontainer/.env` keeps generated config template-only.
+
+**Independent Test**: Set `env: {SECRET_KEY: supersecret}` on a compose-stack project, run
+`regen`, and confirm: (a) `docker-compose.yml` contains
+`services.devcontainer.environment.SECRET_KEY: ${SECRET_KEY}`, (b) `.devcontainer/.env` contains
+`SECRET_KEY=supersecret`, and (c) the literal value `supersecret` does not appear in
+`docker-compose.yml`.
+
+**Acceptance Scenarios**:
+
+1. **Given** `env: {API_KEY: abc123}` on a compose stack, **When** generation runs, **Then** `docker-compose.yml` has `API_KEY: ${API_KEY}` and `.devcontainer/.env` has `API_KEY=abc123`.
+2. **Given** `env: {NAME: ${NAME:-default}}`, **When** generation runs with a root `.env` that sets `NAME=prod`, **Then** `.devcontainer/.env` receives `NAME=prod`.
+3. **Given** `env: {NAME: ${NAME}}` and no root `.env` entry for `NAME`, **When** generation runs, **Then** `.devcontainer/.env` does not include `NAME=` and Docker Compose shell fallback still works.
+
+---
+
+### User Story 2 — Configure env template entries with clearly named project-file field (Priority: P1)
+
+A developer updates their `superposition.yml` to use `customizations.envTemplate` (instead of
+the previously named `customizations.environment`) and expects the generated `.env.example`
+content to be identical to what the old field produced.
+
+**Why this priority**: The existing `environment` key is misleading — it writes to `.env.example`
+(a template), not to the runtime container environment. Renaming it clarifies intent and prevents
+confusion with the new `env:` field.
+
+**Independent Test**: Replace `customizations.environment` with `customizations.envTemplate` in a
+project file, run `regen`, and confirm the generated `.env.example` is byte-for-byte identical to
+the output produced with the old key.
+
+**Acceptance Scenarios**:
+
+1. **Given** `customizations.envTemplate: {FOO: bar}`, **When** generation runs, **Then** `.devcontainer/.env.example` contains `FOO=bar`.
+2. **Given** `customizations.environment: {FOO: bar}` (deprecated alias), **When** generation runs, **Then** `.devcontainer/.env.example` still contains `FOO=bar` (backward-compatible).
+3. **Given** a project file using `environment`, **When** it is read by the project loader, **Then** a deprecation warning is emitted directing users to rename the key.
+
+---
+
+### User Story 3 — remoteEnv wiring for compose env entries (Priority: P2)
+
+A developer on a compose stack expects that compose-targeted env variables are also accessible
+via `${containerEnv:KEY}` in `devcontainer.json → remoteEnv` so VS Code settings and
+extensions can reference them.
+
+**Why this priority**: Without a `remoteEnv` entry, VS Code extensions that read `process.env`
+at startup may not see the variable, even though the container process will.
+
+**Independent Test**: Set a compose-stack env variable, run `regen`, and confirm
+`devcontainer.json → remoteEnv` includes `KEY: ${containerEnv:KEY}` alongside the
+`docker-compose.yml` entry.
+
+**Acceptance Scenarios**:
+
+1. **Given** `env: {DB_URL: postgres://localhost/dev}` on a compose stack, **When** generation runs, **Then** `devcontainer.json` contains `remoteEnv.DB_URL: ${containerEnv:DB_URL}`.
+
+---
+
+## Overview
+
+Refine project-file environment semantics so compose-based projects do not
+embed resolved env values directly in generated `docker-compose.yml` or
+`devcontainer.json`.
+
+At the same time, rename the project-file field
+`customizations.environment` to `customizations.envTemplate` to make its
+purpose explicit: it writes template variables to `.env.example`, not runtime
+container environment.
+
+## Behavior
+
+### `env:` on `stack: compose`
+
+For compose-targeted project env entries:
+
+1. Materialize concrete values into `.devcontainer/.env`
+2. Write `docker-compose.yml -> services.devcontainer.environment.KEY: ${KEY}`
+3. Write `devcontainer.json -> remoteEnv.KEY: ${containerEnv:KEY}`
+
+This keeps generated config free of resolved secret values while still making
+the variables available inside the devcontainer.
+
+### Value Resolution
+
+- literals are written as-is to `.devcontainer/.env`
+- `${NAME}` resolves from the repository root `.env` when present
+- `${NAME:-default}` resolves from the repository root `.env`, otherwise uses
+  the inline default
+- unresolved `${NAME}` values are omitted from `.devcontainer/.env` so shell
+  environment fallback remains possible
+
+### `env:` on `stack: plain`
+
+No change: values still land directly in `devcontainer.json -> remoteEnv`.
+
+## `customizations.envTemplate`
+
+- `customizations.envTemplate` is the canonical project-file field for values
+  that should be written to `.env.example`
+- `customizations.environment` is retained as a deprecated backward-compatible
+  alias
+- serializers should emit `envTemplate`
+
+## Non-Goals
+
+- no change to `.devcontainer/custom/environment.env`
+- no support for targeting arbitrary compose sidecar services from `env:`

package/docs/specs/011-overlay-parameters/spec.md

@@ -0,0 +1,235 @@
+# Feature Specification: Overlay Parameters with Safe Substitution
+
+**Feature Branch**: `011-overlay-parameters`
+**Created**: 2026-03-30
+**Status**: Final
+**Input**: Issue — Introduce overlay parameters with safe, namespaced substitution — no conflicts with Docker/shell/VS Code
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/011-overlay-parameters/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: APPROVED
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Summary
+
+Add first-class **parameters** to overlays so users can configure environment-specific values
+(credentials, database names, ports, paths) without forking overlays or hand-editing generated
+files.
+
+Parameters use the `{{cs.PARAM_NAME}}` substitution syntax, which does not collide with Docker
+Compose (`${VAR}`), shell (`$VAR`, `${VAR}`), VS Code (`${localWorkspaceFolder}`), or GitHub
+Actions (`${{ }}`).
+
+This is **parameter substitution only** — no loops, no conditionals, no embedded logic.
+If `string.replace()` can't do it, it doesn't belong here.
+
+---
+
+## Design
+
+### Syntax
+
+```
+{{cs.PARAM_NAME}}
+```
+
+- **Safe**: does not collide with `${VAR}` (Docker/shell), `${env:VAR}` (VS Code), or `${{ }}` (GitHub Actions)
+- **Consistent**: extends the existing `{{parameters.<key>.id}}` preset convention
+- **Explicit**: clearly owned by container-superposition
+- **Simple**: resolved by a single `string.replace()` regex, no parser needed
+
+### Overlay parameter declarations (`overlay.yml`)
+
+Overlays declare parameters in `overlay.yml`:
+
+```yaml
+id: postgres
+name: PostgreSQL
+category: database
+parameters:
+    POSTGRES_DB:
+        description: Database name
+        default: app
+    POSTGRES_USER:
+        description: Database user
+        default: postgres
+    POSTGRES_PASSWORD:
+        description: Database password
+        default: postgres
+        sensitive: true
+    POSTGRES_PORT:
+        description: Host-mapped port
+        default: '5432'
+```
+
+Fields:
+
+- `description` (required) — human-readable explanation shown in interactive prompts
+- `default` (optional) — default value; absence marks the parameter as _required_
+- `sensitive` (optional, boolean) — indicates secrets; hidden in interactive prompts and redacted from plan output
+
+### Usage in overlay files
+
+Overlay patches and compose files reference parameters using `{{cs.PARAM_NAME}}`:
+
+```json
+{
+    "remoteEnv": {
+        "DATABASE_URL": "postgres://{{cs.POSTGRES_USER}}:{{cs.POSTGRES_PASSWORD}}@postgres:5432/{{cs.POSTGRES_DB}}"
+    }
+}
+```
+
+```yaml
+# docker-compose.yml — generation-time substitution coexists with Docker runtime substitution
+services:
+    postgres:
+        environment:
+            POSTGRES_DB: '{{cs.POSTGRES_DB}}'
+            POSTGRES_USER: '{{cs.POSTGRES_USER}}'
+            POSTGRES_PASSWORD: '{{cs.POSTGRES_PASSWORD}}'
+        ports:
+            - '${POSTGRES_PORT:-{{cs.POSTGRES_PORT}}}:5432'
+```
+
+### Parameters in `superposition.yml`
+
+```yaml
+overlays:
+    - postgres
+    - redis
+
+parameters:
+    POSTGRES_DB: myapp
+    POSTGRES_USER: veggerby
+    REDIS_PORT: '6380'
+```
+
+### Resolution order (highest wins)
+
+1. CLI overrides (`--param POSTGRES_DB=foo`)
+2. Project file (`superposition.yml` `parameters:` section)
+3. Overlay defaults (`overlay.yml` `parameters[KEY].default`)
+
+### Validation rules
+
+| Condition                                                  | Behaviour                             |
+| ---------------------------------------------------------- | ------------------------------------- |
+| Missing required parameter (no default, no value supplied) | **Hard error** before generation      |
+| Unknown parameter (not declared by any selected overlay)   | **Warning** (proceed)                 |
+| Unresolved `{{cs.*}}` in final output                      | **Hard error** (catch-all safety net) |
+
+### Pass-through guarantee
+
+The substitution engine MUST NOT touch:
+
+- Docker Compose expressions: `${VAR}`, `${VAR:-default}`, `$VAR`
+- VS Code/devcontainer variables: `${localWorkspaceFolder}`, `${containerWorkspaceFolder}`, `${env:VAR}`
+- GitHub Actions expressions: `${{ github.* }}`
+- Shell variables in scripts: `$FOO`, `${FOO}`, `${FOO:-default}`
+
+Only tokens matching exactly `{{cs.[A-Z0-9_]+}}` are substituted.
+
+---
+
+## Implementation Scope
+
+### Types (`tool/schema/types.ts`)
+
+```typescript
+export interface OverlayParameterDefinition {
+    description: string;
+    default?: string;
+    sensitive?: boolean;
+}
+```
+
+Add to `OverlayMetadata`:
+
+```typescript
+parameters?: Record<string, OverlayParameterDefinition>;
+```
+
+Add to `ProjectConfigSelection`:
+
+```typescript
+parameters?: Record<string, string>;
+```
+
+Add to `QuestionnaireAnswers`:
+
+```typescript
+overlayParameters?: Record<string, string>;
+```
+
+### Parameter engine (`tool/utils/parameters.ts`)
+
+- `collectOverlayParameters(overlayIds, allOverlayDefs)` — collect all declared parameters from selected overlays with their defaults
+- `resolveParameters(declared, supplied)` — apply resolution order, return resolved map and errors
+- `substituteParameters(content, resolved)` — replace `{{cs.KEY}}` tokens in a string
+- `validateFinalContent(content)` — error if any `{{cs.*}}` remain after substitution
+
+### Composer (`tool/questionnaire/composer.ts`)
+
+After all overlay files are read and before they are written to disk:
+
+1. Collect parameter declarations from selected overlays
+2. Merge with `answers.overlayParameters` values
+3. Validate — error on missing required parameters
+4. Apply substitution to all file content strings (devcontainer.json, docker-compose.yml, .env.example, scripts)
+5. Validate — error on any unresolved `{{cs.*}}` tokens remaining in output
+
+### Project config (`tool/schema/project-config.ts`)
+
+Parse `parameters:` YAML map as `Record<string, string>` (string values only).
+Propagate to `selection.parameters` → `answers.overlayParameters`.
+
+### Init (`scripts/init.ts`)
+
+When overlay declares parameters, interactive questionnaire prompts for values.
+Sensitive parameters use masked input. Pre-filled with defaults.
+
+---
+
+## Non-goals
+
+- Conditional logic (`{{if ...}}`)
+- Loops or iteration
+- Programmable overlays or JS execution
+- Dynamic file generation
+- Templating engine integration (Handlebars, Jinja, EJS, etc.)
+
+---
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 — Postgres with custom database name (P1)
+
+A user scaffolds a compose stack with the postgres overlay and wants their database named `myapp`
+instead of the default `devdb`.
+
+**Acceptance scenarios**:
+
+1. **Given** a `superposition.yml` with `parameters: { POSTGRES_DB: myapp }`, **When** generation runs, **Then** the generated `.devcontainer/docker-compose.yml` and `remoteEnv` in `devcontainer.json` reference `myapp` instead of `devdb`.
+2. **Given** an overlay with a required parameter (no default), **When** generation is run without providing the parameter value, **Then** the tool exits with a clear error message before writing any files.
+3. **Given** generated files contain no `{{cs.*}}` tokens, **When** output is validated, **Then** no error is raised and Docker Compose `${VAR}` expressions are preserved unmodified.
+4. **Given** a user runs `init` interactively with the postgres overlay, **When** the questionnaire reaches parameters, **Then** the user is prompted for each declared parameter with the default pre-filled.
+
+### User Story 2 — Sensitive parameter (P2)
+
+A user provides a database password via parameter. The password must not appear in plan output in cleartext.
+
+**Acceptance scenarios**:
+
+1. **Given** a parameter has `sensitive: true`, **When** the plan command shows parameter values, **Then** the value is displayed as `***`.
+2. **Given** a parameter has `sensitive: true`, **When** the interactive questionnaire prompts for it, **Then** the input is masked.
+
+### User Story 3 — Unknown parameter warning (P3)
+
+A user adds a parameter in `superposition.yml` that is not declared by any selected overlay.
+
+**Acceptance scenarios**:
+
+1. **Given** `parameters: { UNKNOWN_PARAM: foo }` in `superposition.yml`, **When** generation runs, **Then** a warning is printed but generation succeeds.

package/overlays/.shared/README.md

@@ -1,43 +1,127 @@
-# Shared Overlay Configurations
+# Shared Overlay Fragments
 
-This directory contains shared configuration fragments that can be imported by multiple overlays to reduce duplication and ensure consistency.
+This directory contains reusable configuration fragments that can be imported by multiple overlays to reduce duplication and ensure consistency.
 
 ## Structure
 
 ```
 .shared/
-├── otel/               # OpenTelemetry configurations
-├── compose/            # Docker Compose patterns (healthchecks, etc.)
-└── vscode/             # VS Code extension sets
+├── otel/                              # OpenTelemetry configurations
+│   ├── instrumentation.env            # OTEL SDK env vars for instrumentation
+│   └── otel-base-config.yaml          # Base OTEL collector pipeline config
+├── compose/                           # Docker Compose patterns
+│   ├── nvidia-gpu-devcontainer.yml    # NVIDIA GPU passthrough for the devcontainer service
+│   └── common-healthchecks.md         # Standard healthcheck patterns (reference — not importable)
+└── vscode/                            # VS Code extension sets
+    └── recommended-extensions.json    # Commonly recommended extensions (devcontainer patch)
 ```
 
+## Fragment Catalogue
+
+### `otel/instrumentation.env`
+
+**Purpose:** Common OpenTelemetry SDK environment variables for services that send telemetry to an OTEL collector.
+
+**Provides:**
+
+- `OTEL_SERVICE_NAME` — service identifier
+- `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP collector endpoint
+- `OTEL_EXPORTER_OTLP_PROTOCOL` — transport protocol (grpc)
+- `OTEL_RESOURCE_ATTRIBUTES` — deployment metadata
+- `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_EXPORTER` — trace configuration
+- `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` — metrics and log exporters
+
+**Imported by:** `otel-collector`, `prometheus`, `jaeger`
+
+**Merge type:** `.env` — appended to `.env.example` with a `# from .shared/otel/instrumentation.env` comment
+
+---
+
+### `otel/otel-base-config.yaml`
+
+**Purpose:** Base OpenTelemetry Collector receiver and pipeline configuration — OTLP receivers, batch processor, and logging exporter.
+
+**Merge type:** `.yaml` — deep-merged into `devcontainer.json` patch
+
+---
+
+### `compose/nvidia-gpu-devcontainer.yml`
+
+**Purpose:** Adds the `deploy.resources.reservations.devices` block to the `devcontainer` service, giving the devcontainer itself direct NVIDIA GPU access. This enables GPU-accelerated tooling (`torch`, `tensorflow`, CUDA CLIs, `nvidia-smi`) to work directly in the dev environment.
+
+**Format:** Docker Compose service fragment (services.devcontainer only).
+
+**Merge type:** `compose_imports:` — deep-merged into the final `docker-compose.yml` before the overlay's own `docker-compose.yml`.
+
+**Imported by:** `ollama`
+
+**Prerequisites:** NVIDIA Container Toolkit must be installed on the host.
+
+---
+
+### `compose/common-healthchecks.md`
+
+**Purpose:** Reference library of standard Docker Compose healthcheck patterns for common services (HTTP, PostgreSQL, Redis, MongoDB, MySQL).
+
+**Note:** This is a `.md` file (documentation only) — it cannot be imported via `overlay.yml` `imports:`. Copy the relevant pattern directly into your overlay's `docker-compose.yml`.
+
+---
+
+### `vscode/recommended-extensions.json`
+
+**Purpose:** A curated set of VS Code extensions commonly useful across many overlays (spell checking, error lens, GitLens, EditorConfig, Prettier, Docker, YAML, Markdown).
+
+**Format:** Valid devcontainer patch — `customizations.vscode.extensions` array.
+
+**Merge type:** `.json` — deep-merged into `devcontainer.json` patch
+
+---
+
 ## Usage
 
-Overlays can import shared files by adding them to the `imports` field in `overlay.yml`:
+Reference shared devcontainer fragments in `overlay.yml` via the `imports` field:
 
 ```yaml
-id: prometheus
+id: my-overlay
 imports:
-    - .shared/otel/otel-base-config.yaml
-    - .shared/compose/common-healthchecks.yml
+    - .shared/otel/instrumentation.env
+    - .shared/vscode/recommended-extensions.json
+```
+
+Reference shared docker-compose fragments via the `compose_imports` field:
+
+```yaml
+id: my-overlay
+compose_imports:
+    - .shared/compose/nvidia-gpu-devcontainer.yml
 ```
 
-## Benefits
+**Rules:**
+
+- All paths must begin with `.shared/`
+- Paths are relative to `overlays/`
+- `imports` fragments are applied in declaration order, then the overlay's own `devcontainer.patch.json` (overlay wins on conflict)
+- `compose_imports` fragments are deep-merged into `docker-compose.yml` before the overlay's own `docker-compose.yml` (overlay wins on conflict)
+- `compose_imports` files must be `.yml` or `.yaml`
+
+## Creating New Fragments
+
+1. Choose the right subdirectory (`otel/`, `compose/`, `vscode/`, or create a new one with a clear name)
+2. Use a descriptive file name — one concern per file
+3. For `.json` and `.yaml` fragments, ensure the content is valid devcontainer patch format
+4. Add a comment at the top explaining what the fragment does
+5. Update this README with the new fragment's details and which overlays import it
 
-- **DRY (Don't Repeat Yourself)**: Common patterns defined once
-- **Consistency**: All overlays using the same shared config stay in sync
-- **Maintainability**: Update shared config once, all overlays benefit
-- **Best Practices**: Shared configs embody proven patterns
+## Downstream Impact
 
-## Creating Shared Configs
+Any change to a shared fragment affects every overlay that imports it. Before editing:
 
-1. Identify common patterns across overlays
-2. Extract to appropriate `.shared/` subdirectory
-3. Update overlays to import the shared file
-4. Test that imports work correctly
+- Check the "Imported by" section above for the fragment you're modifying
+- Run `npm test` and `container-superposition doctor` after changes
+- Consider whether the change should apply to all importers, or whether specific overlays need to be updated
 
 ## Import Resolution
 
 - Imports are resolved relative to the `overlays/` directory
-- Shared files are merged into the overlay during composition
-- Files are applied in the order they are listed
+- Path traversal (`../`, absolute paths, non-`.shared/` prefixes) is rejected at composition time
+- Missing or unsupported file types cause generation to fail with a message naming the overlay and the bad reference

package/overlays/.shared/compose/common-healthchecks.md

@@ -0,0 +1,60 @@
+# Common Docker Compose Healthcheck Patterns
+
+Reference library of standard healthcheck patterns for common services. This is a **documentation file only** — it cannot be imported via `overlay.yml` `imports:` because it is not a devcontainer patch.
+
+Copy the relevant pattern directly into your overlay's `docker-compose.yml`.
+
+## HTTP
+
+```yaml
+healthcheck:
+    test: ['CMD-SHELL', 'curl -f http://localhost:${PORT}/health || exit 1']
+    interval: 30s
+    timeout: 10s
+    retries: 3
+    start_period: 40s
+```
+
+## PostgreSQL
+
+```yaml
+healthcheck:
+    test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
+    interval: 10s
+    timeout: 5s
+    retries: 5
+    start_period: 10s
+```
+
+## Redis
+
+```yaml
+healthcheck:
+    test: ['CMD', 'redis-cli', 'ping']
+    interval: 10s
+    timeout: 5s
+    retries: 5
+    start_period: 10s
+```
+
+## MongoDB
+
+```yaml
+healthcheck:
+    test: ['CMD', 'mongosh', '--eval', "db.adminCommand('ping')"]
+    interval: 10s
+    timeout: 5s
+    retries: 5
+    start_period: 10s
+```
+
+## MySQL
+
+```yaml
+healthcheck:
+    test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost']
+    interval: 10s
+    timeout: 5s
+    retries: 5
+    start_period: 10s
+```

package/overlays/.shared/compose/nvidia-gpu-devcontainer.yml

@@ -0,0 +1,22 @@
+# Shared Docker Compose fragment: NVIDIA GPU passthrough for the devcontainer service.
+#
+# Adds the deploy.resources.reservations.devices block to the devcontainer service so
+# GPU-accelerated tooling (torch, tensorflow, CUDA CLIs, etc.) works directly in the
+# dev environment alongside any GPU-enabled sidecar services.
+#
+# Requirements: NVIDIA Container Toolkit must be installed on the host.
+#   https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
+#
+# Used by: ollama
+# Import via compose_imports in overlay.yml:
+#   compose_imports:
+#     - .shared/compose/nvidia-gpu-devcontainer.yml
+services:
+    devcontainer:
+        deploy:
+            resources:
+                reservations:
+                    devices:
+                        - driver: nvidia
+                          count: all
+                          capabilities: [gpu]

package/overlays/.shared/vscode/recommended-extensions.json

@@ -1,14 +1,18 @@
 {
-    "description": "Commonly recommended VS Code extensions across overlays",
-    "extensions": {
-        "productivity": [
-            "streetsidesoftware.code-spell-checker",
-            "usernamehw.errorlens",
-            "eamodio.gitlens"
-        ],
-        "formatting": ["editorconfig.editorconfig", "esbenp.prettier-vscode"],
-        "docker": ["ms-azuretools.vscode-docker"],
-        "yaml": ["redhat.vscode-yaml"],
-        "markdown": ["yzhang.markdown-all-in-one", "davidanson.vscode-markdownlint"]
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "streetsidesoftware.code-spell-checker",
+                "usernamehw.errorlens",
+                "eamodio.gitlens",
+                "editorconfig.editorconfig",
+                "esbenp.prettier-vscode",
+                "ms-azuretools.vscode-docker",
+                "redhat.vscode-yaml",
+                "yzhang.markdown-all-in-one",
+                "davidanson.vscode-markdownlint"
+            ]
+        }
     }
 }

package/overlays/alertmanager/setup.sh

@@ -5,26 +5,11 @@ set -e
 
 echo "🔧 Setting up Alertmanager integration..."
 
-# Determine workspace root dynamically to support both /workspaces/* and /workspace layouts
-WORKSPACE_ROOT="${LOCAL_WORKSPACE_FOLDER:-$PWD}"
+# Resolve the .devcontainer directory relative to this script.
+# Scripts live at .devcontainer/scripts/, so .. is always .devcontainer/.
+DEVCONTAINER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd .. && pwd)"
 
-# If the current root does not contain a .devcontainer, try common devcontainer locations
-if [ ! -d "$WORKSPACE_ROOT/.devcontainer" ]; then
-    # Try to detect a workspace under /workspaces (compose templates)
-    if [ -d "/workspaces" ]; then
-        FIRST_WORKSPACE_DIR="$(find /workspaces -maxdepth 1 -mindepth 1 -type d 2>/dev/null | head -n 1)"
-        if [ -n "$FIRST_WORKSPACE_DIR" ] && [ -d "$FIRST_WORKSPACE_DIR/.devcontainer" ]; then
-            WORKSPACE_ROOT="$FIRST_WORKSPACE_DIR"
-        fi
-    fi
-fi
-
-# Fallback to /workspace if it exists and contains a .devcontainer (non-compose setups)
-if [ ! -d "$WORKSPACE_ROOT/.devcontainer" ] && [ -d "/workspace/.devcontainer" ]; then
-    WORKSPACE_ROOT="/workspace"
-fi
-
-PROMETHEUS_CONFIG="$WORKSPACE_ROOT/.devcontainer/prometheus-prometheus.yml"
+PROMETHEUS_CONFIG="$DEVCONTAINER_DIR/prometheus-prometheus.yml"
 
 # Check if Prometheus config exists
 if [ -f "$PROMETHEUS_CONFIG" ]; then