container-superposition 0.1.5 → 0.1.7

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)

package/overlays/bun/verify.sh

@@ -7,10 +7,15 @@ echo "🔍 Verifying Bun overlay..."
 echo ""
 
 # Check Bun is installed
+# The verify script runs in a non-interactive shell that may not have ~/.bun/bin on PATH.
 echo "1️⃣ Checking Bun..."
-if command -v bun &> /dev/null; then
+BUN_BIN="${BUN_INSTALL:-$HOME/.bun}/bin/bun"
+if command -v bun &>/dev/null; then
     bun --version
     echo "   ✅ Bun found"
+elif [ -x "$BUN_BIN" ]; then
+    "$BUN_BIN" --version
+    echo "   ✅ Bun found (at $BUN_BIN)"
 else
     echo "   ❌ Bun not found"
     exit 1

package/overlays/claude-code/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 Anthropic Claude Code CLI..."
 
 # Install @anthropic-ai/claude-code globally

package/overlays/cloudflared/setup.sh

@@ -13,18 +13,15 @@ echo "📦 Installing cloudflared..."
 # Check https://github.com/cloudflare/cloudflared/releases for newer versions
 CF_VERSION="${CLOUDFLARED_VERSION:-2025.2.1}"
 
-# Detect architecture
-ARCH=$(uname -m)
-case "$ARCH" in
-    x86_64) CF_ARCH="amd64" ;;
-    aarch64 | arm64) CF_ARCH="arm64" ;;
-    *) echo "   ⚠️  Unsupported architecture: $ARCH" ; CF_ARCH="amd64" ;;
-esac
-
-CF_URL="https://github.com/cloudflare/cloudflared/releases/download/${CF_VERSION}/cloudflared-linux-${CF_ARCH}"
-curl -sSL "$CF_URL" -o /tmp/cloudflared
-sudo install -m 755 /tmp/cloudflared /usr/local/bin/cloudflared
-rm -f /tmp/cloudflared
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch amd64
+
+install_binary \
+    "https://github.com/cloudflare/cloudflared/releases/download/${CF_VERSION}/cloudflared-linux-${CS_ARCH}" \
+    "cloudflared" "755"
 
 # Verify installation
 if command -v cloudflared &> /dev/null; then

package/overlays/codex/README.md

@@ -5,6 +5,7 @@ Adds OpenAI Codex CLI with a persistent `.codex` folder for configurations.
 ## Features
 
 - **OpenAI Codex CLI** - AI-powered code generation and assistance from the command line
+- **Bubblewrap** - Linux sandbox dependency installed as `bwrap` for Codex
 - **Codex directory** - Creates `$HOME/.codex` for persistent configurations
 
 ## What is OpenAI Codex CLI?
@@ -26,8 +27,9 @@ The OpenAI Codex CLI (`@openai/codex`) provides command-line access to OpenAI's
 
 This overlay:
 
-1. Installs OpenAI Codex CLI globally via npm (`npm install -g @openai/codex`)
-2. Creates the `$HOME/.codex` directory for persistent configurations
+1. Installs the Linux `bubblewrap` package so `bwrap` is available for Codex sandboxing
+2. Installs OpenAI Codex CLI globally via npm (`npm install -g @openai/codex`)
+3. Creates the `$HOME/.codex` directory for persistent configurations
 
 **After setup:**
 
@@ -39,12 +41,13 @@ This overlay:
 After setup, run the verification script to ensure proper installation:
 
 ```bash
-bash .devcontainer/verify-codex.sh
+bash .devcontainer/scripts/verify-codex.sh
 ```
 
 This will check:
 
 - Codex CLI is installed and in PATH
+- `bwrap` is installed and in PATH
 - `.codex` directory exists
 
 ## Troubleshooting
@@ -90,7 +93,7 @@ codex explain "what does this regex do: /^[a-zA-Z0-9]+$/"
 codex complete "function fibonacci(n) {"
 ```
 
-For full documentation, visit: [OpenAI Codex CLI Documentation](https://github.com/openai/openai-codex-cli)
+For full documentation, visit: [OpenAI Codex CLI Documentation](https://github.com/openai/codex)
 
 ## Optional: Persistent .codex Mount
 
@@ -104,7 +107,7 @@ Then add this mount to your `devcontainer.json`:
 
 ```json
 "mounts": [
-  "source=${localEnv:HOME}${localEnv:USERPROFILE}/.codex,target=${containerEnv:HOME}/.codex,type=bind,consistency=cached"
+  "source=${localEnv:HOME}${localEnv:USERPROFILE}/.codex,target=/home/vscode/.codex,type=bind,consistency=cached"
 ]
 ```
 
@@ -124,5 +127,5 @@ This allows you to:
 
 ## Additional Resources
 
-- [OpenAI Codex CLI](https://github.com/openai/openai-codex-cli)
+- [OpenAI Codex CLI](https://github.com/openai/codex)
 - [OpenAI Platform](https://platform.openai.com/)

package/overlays/codex/devcontainer.patch.json

@@ -1,3 +1,9 @@
 {
-    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "bubblewrap",
+            "apk": "bubblewrap"
+        }
+    }
 }

package/overlays/codex/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 OpenAI Codex CLI..."
 
 # Install @openai/codex globally

package/overlays/codex/verify.sh

@@ -5,6 +5,14 @@ set -e
 
 echo "🔍 Verifying Codex overlay setup..."
 
+# Check if bubblewrap is installed for Codex sandboxing on Linux
+if ! command -v bwrap &> /dev/null; then
+    echo "✗ bubblewrap is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ bubblewrap is installed: $(bwrap --version 2>/dev/null | head -n 1 || echo 'installed')"
+
 # Check if codex CLI is installed
 if ! command -v codex &> /dev/null; then
     echo "✗ codex CLI is not installed or not in PATH"

package/overlays/commitlint/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 "📝 Setting up commitlint..."
 
 # Install commitlint and conventional commits config globally