container-superposition 0.1.6 → 0.1.7

package/docs/specs/004-doctor-fix/spec.md

@@ -0,0 +1,70 @@
+# Feature Specification: `doctor --fix` — Interactive Auto-Repair
+
+**Feature Branch**: `004-doctor-fix`
+**Created**: 2026-03-19
+**Status**: Final
+**Input**: GitHub issue: Implement `doctor --fix` — interactive auto-repair for environment issues
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/004-doctor-fix/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: APPROVED
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Summary
+
+The `doctor` command validates the environment. The `--fix` path was a placeholder. This spec
+describes the full implementation of an interactive, safe, deterministic auto-repair flow for
+common environment issues.
+
+## Initial Auto-Fix Scope
+
+| #   | Issue class                                                   | Automation condition                                              |
+| --- | ------------------------------------------------------------- | ----------------------------------------------------------------- |
+| 1   | Stale or legacy `superposition.json` metadata                 | Always supported (manifest migration)                             |
+| 2   | Derived `.devcontainer/` drift or missing generated artifacts | Supported when a valid manifest is present (regeneration)         |
+| 3   | Unsupported Node runtime                                      | Supported only when `nvm`, `fnm`, or `volta` is already available |
+| 4   | Docker / Compose tooling drift                                | Supported only when a known safe host repair command is available |
+
+## Outcome Vocabulary
+
+Every finding evaluated by the fix flow resolves to exactly one of:
+
+- **`fixed`** — tool changed the environment and targeted re-check now passes
+- **`already compliant`** — fix path found no change was needed
+- **`skipped`** — not attempted because an earlier failure or prerequisite blocked it
+- **`requires manual action`** — issue remains; automation is unsafe or unavailable
+
+## Data Model
+
+### `DiagnosticFinding`
+
+Fields: `id`, `category`, `name`, `status`, `message`, `details?`, `fixEligibility`, `remediationKey?`, `recheckScope`
+
+### `RemediationAction`
+
+Fields: `key`, `findingId`, `safetyClass`, `executionKind`, `preconditions`, `plannedChanges`, `manualFallback`
+
+### `FixExecution`
+
+Fields: `findingId`, `remediationKey`, `attempted`, `outcome`, `reason`, `commands?`, `changedFiles?`, `backupPath?`, `rechecked`
+
+### `FixRun`
+
+Fields: `outputPath`, `requestedJson`, `initialFindings`, `executions`, `finalFindings`, `summary`, `exitDisposition`
+
+## CLI Contract
+
+- `doctor` without `--fix` — no change to current diagnostics behavior
+- `doctor --fix` — diagnose → remediate in stable order → re-check → print summary
+- `doctor --fix --json` — same flow, machine-readable JSON output
+
+## Remediation Ordering
+
+Prerequisites before dependents:
+
+1. Stale manifest migration (must complete before regeneration)
+2. Missing artifacts / devcontainer drift (regeneration from manifest)
+3. Node version fix (only if version manager available)
+4. Docker tooling fix (only if repair command available)

package/docs/specs/005-cuda-overlay/spec.md

@@ -0,0 +1,101 @@
+# Feature Specification: CUDA (NVIDIA GPU) Overlay
+
+**Feature Branch**: `copilot/add-cuda-overlay-for-gpu`
+**Created**: 2026-03-22
+**Status**: Final
+**Input**: Add a `cuda` overlay to enable NVIDIA GPU-accelerated workloads inside a dev container.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/005-cuda-overlay/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Approved
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - GPU passthrough for ML/inference workloads (Priority: P1)
+
+A developer wants to run NVIDIA GPU-accelerated workloads (ML training, inference, CUDA compute) inside a dev container without manually configuring Docker runtime flags.
+
+**Why this priority**: GPU-accelerated dev containers require specific Docker runtime flags (`--gpus=all`) and VS Code devcontainer host requirements (`gpu: true`) that must be set correctly for the container to access the GPU. Without the overlay, users must add these manually and correctly every time.
+
+**Independent Test**: Select the `cuda` overlay, rebuild the container, and confirm that `nvidia-smi` exits 0 and reports the GPU correctly.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects the `cuda` overlay, **When** the devcontainer is built, **Then** `devcontainer.json` includes `"runArgs": ["--gpus=all"]` and `"hostRequirements": {"gpu": true}`.
+2. **Given** the NVIDIA Container Toolkit is installed on the host, **When** the devcontainer starts, **Then** `nvidia-smi` is accessible inside the container.
+3. **Given** the container is running, **When** `setup.sh` executes, **Then** it reports whether `nvidia-smi` is available and prints a helpful message if it is not.
+
+---
+
+### User Story 2 - Conflict enforcement between cuda and rocm (Priority: P1)
+
+A user selects both `cuda` and `rocm` and expects the tool to report a conflict, because only one GPU compute framework can be active at a time.
+
+**Why this priority**: CUDA (NVIDIA) and ROCm (AMD) are mutually exclusive GPU compute frameworks. Allowing both would produce an incoherent configuration.
+
+**Independent Test**: Attempt to generate a devcontainer with both `cuda` and `rocm` selected and confirm the tool surfaces a conflict and blocks generation.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects both `cuda` and `rocm`, **When** they run `container-superposition init`, **Then** the tool reports a conflict and prevents generation.
+2. **Given** `cuda` lists `rocm` in `conflicts`, **When** `rocm` is added in the future, **Then** `rocm` must also list `cuda` in its `conflicts` (bidirectional enforcement). Note: `rocm` does not exist yet; when it is added the reciprocal conflict must be declared in `overlays/rocm/overlay.yml`.
+
+---
+
+## Design
+
+### overlay.yml
+
+```yaml
+id: cuda
+name: CUDA (NVIDIA GPU)
+description: NVIDIA CUDA libraries and GPU passthrough for containerized ML/inference workloads
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - rocm
+tags:
+    - gpu
+    - cuda
+    - nvidia
+    - ml
+    - inference
+ports: []
+```
+
+### devcontainer.patch.json
+
+Set `runArgs` for GPU passthrough and `hostRequirements` to signal GPU need:
+
+```json
+{
+    "runArgs": ["--gpus=all"],
+    "hostRequirements": { "gpu": true }
+}
+```
+
+### setup.sh
+
+- Check whether `nvidia-smi` is reachable inside the container.
+- Print a helpful message if it is not (host driver / toolkit not configured).
+
+### verify.sh
+
+- Assert `nvidia-smi` exits 0 (used by the `doctor` command).
+
+### README.md
+
+- Clear prerequisites section (host drivers, NVIDIA Container Toolkit).
+- Troubleshooting tips for common failure modes.
+- Note that the overlay does not replace or install host drivers.
+
+## Out of Scope
+
+- Installing or replacing host NVIDIA drivers.
+- Guaranteeing version alignment between CUDA user-space libraries and the host kernel module.
+- ROCm (AMD GPU) support — tracked separately.

package/docs/specs/006-rocm-overlay/spec.md

@@ -0,0 +1,109 @@
+# Feature Specification: ROCm (AMD GPU) Overlay
+
+**Feature Branch**: `copilot/add-rocm-overlay`
+**Created**: 2026-03-22
+**Status**: Accepted
+**Input**: Add a `rocm` overlay to enable AMD GPU-accelerated workloads inside a dev container.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/006-rocm-overlay/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Approved
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Overview
+
+Add a `rocm` overlay to enable AMD GPU-accelerated workloads inside a dev container using the ROCm open software platform.
+
+> **Note:** ROCm-in-container is a supported but more fragile path than CUDA. It depends heavily on the host kernel version, AMD driver stack, specific device support, and container runtime configuration. Treat this as a separate supported profile — not a drop-in equivalent of CUDA.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - AMD GPU passthrough for ML/inference workloads (Priority: P1)
+
+1. **Given** a user selects the `rocm` overlay, **When** the devcontainer is built, **Then** `devcontainer.json` includes `"runArgs": ["--device=/dev/kfd", "--device=/dev/dri", "--group-add=video", "--group-add=render"]`.
+2. **Given** the AMD GPU drivers and ROCm runtime are installed on the host, **When** the devcontainer starts, **Then** `rocm-smi` is accessible inside the container.
+3. **Given** the container is running, **When** `setup.sh` executes, **Then** it reports whether `rocm-smi` is available and prints a helpful message if it is not.
+4. **Given** `rocm-smi` is not available, **When** `verify.sh` executes, **Then** it exits 1 for the `doctor` command.
+
+---
+
+## Prerequisites (host-side — out of scope for this overlay)
+
+1. Supported AMD GPU hardware (RDNA 2+, most CDNA — check [ROCm hardware support matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html))
+2. AMD GPU drivers (`amdgpu`) installed on the host
+3. ROCm runtime installed on the host (or the container image bundles it)
+4. User added to the `render` and `video` groups, or appropriate device permissions set
+5. `/dev/kfd` and `/dev/dri` devices accessible in the container
+
+## Design
+
+### overlay.yml
+
+```yaml
+id: rocm
+name: ROCm (AMD GPU)
+description: AMD ROCm libraries and GPU passthrough for containerized ML/inference workloads
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - cuda
+tags:
+    - dev
+    - gpu
+    - rocm
+    - amd
+    - ml
+    - inference
+ports: []
+```
+
+### devcontainer.patch.json
+
+Set `runArgs` for AMD GPU device passthrough:
+
+```json
+{
+    "runArgs": ["--device=/dev/kfd", "--device=/dev/dri", "--group-add=video", "--group-add=render"]
+}
+```
+
+- `/dev/kfd` — AMD Kernel Fusion Driver; required for ROCm compute
+- `/dev/dri` — Direct Rendering Infrastructure; gives access to GPU render nodes
+- `--group-add=video` and `--group-add=render` — add the container user to the groups that own the GPU device nodes
+
+### setup.sh
+
+- Check whether `rocm-smi` or `rocminfo` is reachable inside the container.
+- Print a helpful message if neither is found (host driver / ROCm not configured).
+
+### verify.sh
+
+- Assert `rocm-smi` exits 0 (used by the `doctor` command).
+
+### README.md
+
+Must include:
+
+- Prominent prerequisites section
+- Known limitations (kernel version coupling, device node names may vary)
+- ROCm framework wheels (PyTorch ROCm, TensorFlow ROCm)
+- Troubleshooting section
+- Link to ROCm compatibility matrix
+- Clear note that this overlay does not replace host drivers
+
+## Relationship to CUDA Overlay
+
+- `cuda` and `rocm` must list each other in `conflicts` (bidirectional, per project rules)
+- The `cuda` overlay already declares `rocm` in its `conflicts`
+- CUDA is considered the primary GPU path; ROCm is a supported secondary path
+
+## Known Constraints and Caveats
+
+- ROCm version support is tightly coupled to kernel and driver versions
+- Device node names (`/dev/dri/renderD128`) may differ per host
+- Some frameworks publish separate ROCm wheels
+- Less forgiving than CUDA during setup — detailed troubleshooting is essential

package/overlays/.shared/README.md

@@ -1,43 +1,102 @@
-# 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
+│   └── 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/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 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
 ```
 
-## Benefits
+**Rules:**
+
+- All paths must begin with `.shared/`
+- Paths are relative to `overlays/`
+- Imports are applied in declaration order, then the overlay's own `devcontainer.patch.json` (overlay wins on conflict)
+
+## 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/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

package/overlays/alertmanager/verify.sh

@@ -6,19 +6,18 @@ echo "🔍 Verifying Alertmanager installation..."
 # Track overall success
 ALL_CHECKS_PASSED=true
 
-# Check if Alertmanager service is running
-if docker ps --format '{{.Names}}' | grep -q alertmanager; then
-    echo "✓ Alertmanager service is running"
+# Check if Alertmanager API is accessible (primary health signal).
+# docker ps is used for info only — it may not be accessible in all setups.
+if curl -s -o /dev/null -w "%{http_code}" http://alertmanager:9093/-/healthy 2>/dev/null | grep -q "200"; then
+    echo "✓ Alertmanager API is accessible"
 else
-    echo "✗ Alertmanager service is not running"
+    echo "✗ Alertmanager API not responding (http://alertmanager:9093/-/healthy)"
     ALL_CHECKS_PASSED=false
 fi
 
-# Check if Alertmanager API is accessible
-if curl -s -o /dev/null -w "%{http_code}" http://alertmanager:9093/-/healthy 2>/dev/null | grep -q "200"; then
-    echo "✓ Alertmanager API is accessible"
-else
-    echo "⚠️ Alertmanager API not responding yet (may still be starting)"
+# Informational: check via docker ps if available.
+if docker ps --format '{{.Names}}' 2>/dev/null | grep -q alertmanager; then
+    echo "✓ Alertmanager container visible in docker ps"
 fi
 
 # Final result

package/overlays/all/README.md

@@ -0,0 +1,43 @@
+# Meta Overlay
+
+Internal testing overlay that activates **all available overlays** at once. Used to verify that the full overlay catalogue can be composed without errors.
+
+> **Not shown in the interactive questionnaire.** Use it directly in a `superposition.yml` or test script.
+
+## Purpose
+
+The `all` overlay exists to make CI/integration testing straightforward: selecting it expands to every non-preset, non-hidden overlay in the live registry, exercising the full composition pipeline in one pass.
+
+```yaml
+# superposition.yml
+stack: compose
+containerName: meta-test
+overlays:
+    - all
+outputPath: .devcontainer
+```
+
+## How expansion works
+
+There is no `requires` list in `overlays/all/overlay.yml`. Instead, the dependency resolver in
+`resolveDependencies()` detects the special `all` overlay ID and replaces it with the full live
+overlay registry (excluding hidden and preset overlays) at resolution time. This means:
+
+- New overlays are automatically included the moment they are added to the catalogue — no manual
+  update to this file is needed.
+- The expansion is driven by the live registry, not a hard-coded list.
+
+## Conflicts
+
+Some overlays expanded from `all` are mutually exclusive at runtime:
+
+| Conflict                           | Details                                                 |
+| ---------------------------------- | ------------------------------------------------------- |
+| `docker-in-docker` ↔ `docker-sock` | Two different Docker access strategies — cannot coexist |
+
+The composer will emit warnings for these conflicts. They are expected and do not block the build. The intent is to test patch composition, not to produce a runnable container.
+
+## References
+
+- [Overlay authoring guide](../../docs/creating-overlays.md)
+- [All overlays](../../docs/overlays.md)

package/overlays/all/devcontainer.patch.json

@@ -0,0 +1,6 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {},
+    "customizations": {},
+    "forwardPorts": []
+}

package/overlays/all/overlay.yml

@@ -0,0 +1,14 @@
+id: all
+name: All Overlays
+description: Internal testing overlay that activates all available overlays to verify the full build
+category: dev
+hidden: true
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - internal
+    - testing
+    - all
+ports: []

package/overlays/amp/setup.sh

@@ -3,6 +3,11 @@
 
 set -e
 
+# Source shared setup utilities (provides load_nvm)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+load_nvm
+
 echo "📦 Installing Sourcegraph Amp CLI..."
 
 # Install @sourcegraph/amp globally

package/overlays/bun/setup.sh

@@ -34,7 +34,7 @@ if ! command -v bun &> /dev/null; then
     BUN_URL="https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}/bun-linux-${BUN_ARCH}.zip"
     
     echo "   Downloading Bun version ${BUN_VERSION} for ${ARCH}..."
-    if ! wget "${BUN_URL}" -O /tmp/bun.zip 2>&1; then
+    if ! wget -q "${BUN_URL}" -O /tmp/bun.zip; then
         echo "   ❌ Failed to download Bun from ${BUN_URL}"
         exit 1
     fi
@@ -61,6 +61,15 @@ fi
 export BUN_INSTALL="$HOME/.bun"
 export PATH="$BUN_INSTALL/bin:$PATH"
 
+# Persist PATH so verify script (and interactive shells) can find bun
+for _shell_rc in "$HOME/.bashrc" "$HOME/.profile"; do
+    if [ -f "$_shell_rc" ] && ! grep -q 'BUN_INSTALL' "$_shell_rc" 2>/dev/null; then
+        echo 'export BUN_INSTALL="$HOME/.bun"' >> "$_shell_rc"
+        echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> "$_shell_rc"
+    fi
+done
+unset _shell_rc
+
 # Verify installation
 if command -v bun &> /dev/null; then
     INSTALLED_VERSION=$(bun --version)