container-superposition 0.1.5 → 0.1.7

package/overlays/cuda/README.md

@@ -0,0 +1,179 @@
+# CUDA (NVIDIA GPU) Overlay
+
+Enables NVIDIA GPU passthrough for containerized ML, inference, and CUDA compute workloads.
+
+## Features
+
+- **GPU passthrough** - `--gpus=all` added to container `runArgs` so all host GPUs are available
+- **VS Code devcontainer GPU hint** - `hostRequirements.gpu = true` signals that a GPU is needed
+- **Setup check** - `setup.sh` verifies `nvidia-smi` on container start and prints actionable guidance when GPU access is unavailable
+- **Doctor integration** - `verify.sh` asserts `nvidia-smi` exits 0 for `container-superposition doctor` checks
+
+## Prerequisites (host-side — out of scope for this overlay)
+
+This overlay configures the _container_ side of GPU passthrough. The host must be prepared independently:
+
+1. **Supported NVIDIA GPU** — Pascal (GTX 10xx) or newer recommended
+2. **NVIDIA drivers** — Install the appropriate driver for your OS from [https://www.nvidia.com/drivers](https://www.nvidia.com/drivers)
+3. **NVIDIA Container Toolkit** — Install and configure following the [official guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html):
+    ```bash
+    # Example for Ubuntu
+    curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
+    curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
+      sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
+      sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
+    sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
+    ```
+4. **Configure the Docker runtime** — Run once after installing the toolkit:
+    ```bash
+    sudo nvidia-ctk runtime configure --runtime=docker
+    sudo systemctl restart docker
+    ```
+
+> ⚠️ **This overlay cannot install or replace host drivers.** Version alignment between the CUDA user-space libraries inside the container and the host kernel module is the user's responsibility.
+
+## How It Works
+
+The overlay patches `devcontainer.json` with two settings:
+
+```json
+{
+    "runArgs": ["--gpus=all"],
+    "hostRequirements": {
+        "gpu": true
+    }
+}
+```
+
+- **`runArgs: ["--gpus=all"]`** — Passes all host GPUs into the container via the NVIDIA Container Runtime.
+- **`hostRequirements.gpu: true`** — Tells VS Code that the host must have a GPU. VS Code will warn the user when opening the repo if no GPU is detected.
+
+The container image itself does **not** need to be an official NVIDIA CUDA image for the passthrough to work; however, CUDA libraries (e.g., `libcuda.so`) must exist inside the image to use CUDA APIs. See [Base Image](#base-image) below.
+
+## Base Image
+
+For GPU workloads you typically want a CUDA-capable base image. Popular choices:
+
+| Image                                     | Use case                    |
+| ----------------------------------------- | --------------------------- |
+| `nvidia/cuda:12.x.x-runtime-ubuntu22.04`  | Runtime-only (inference)    |
+| `nvidia/cuda:12.x.x-devel-ubuntu22.04`    | Full toolkit (compilation)  |
+| `nvcr.io/nvidia/pytorch:24.xx-py3`        | PyTorch + CUDA pre-built    |
+| `nvcr.io/nvidia/tensorflow:24.xx-tf2-py3` | TensorFlow + CUDA pre-built |
+
+Browse all tags at [hub.docker.com/r/nvidia/cuda](https://hub.docker.com/r/nvidia/cuda) and [catalog.ngc.nvidia.com](https://catalog.ngc.nvidia.com).
+
+To use a CUDA image, set the `image` field in your `.devcontainer/devcontainer.json` (for plain stack) or configure the appropriate service's `image` (or its `build`/`dockerfile`) in your compose-based devcontainer setup (for compose stack).
+
+## Common Commands
+
+### Check GPU availability
+
+```bash
+# List GPUs and driver version
+nvidia-smi
+
+# Compact GPU list
+nvidia-smi -L
+
+# Watch GPU utilisation (refreshes every second)
+nvidia-smi dmon -s u
+```
+
+### Query CUDA version
+
+```bash
+# CUDA runtime version (requires libcuda / nvidia-smi)
+nvidia-smi | grep "CUDA Version"
+
+# CUDA toolkit version (if nvcc is installed in the image)
+nvcc --version
+```
+
+### Python / PyTorch smoke test
+
+```python
+import torch
+print(torch.cuda.is_available())        # True
+print(torch.cuda.get_device_name(0))    # e.g. "NVIDIA GeForce RTX 4090"
+```
+
+### TensorFlow smoke test
+
+```python
+import tensorflow as tf
+print(tf.config.list_physical_devices('GPU'))
+```
+
+## Use Cases
+
+- **Model inference** — Run LLM or CV model inference with GPU acceleration
+- **Training** — Train deep learning models without leaving the dev container
+- **CUDA compute** — General-purpose GPU programming with CUDA C/C++ or PyCUDA
+- **Jupyter notebooks** — GPU-accelerated data science with Jupyter (combine with the `jupyter` overlay)
+- **CI parity** — Reproduce GPU CI failures locally inside the same container image
+
+**Integrates well with:**
+
+- `python` — Python runtime for ML workloads
+- `jupyter` — Interactive GPU notebooks
+
+## Troubleshooting
+
+### `nvidia-smi: command not found`
+
+The container cannot see the GPU. Work through this checklist:
+
+1. Verify host drivers: `nvidia-smi` should work on the _host_ before it works inside the container.
+2. Verify NVIDIA Container Toolkit is installed: `nvidia-ctk --version`.
+3. Verify Docker is configured to use the NVIDIA runtime:
+    ```bash
+    docker info | grep -i runtime
+    # Should list: nvidia
+    ```
+4. Rebuild the dev container after configuring the toolkit.
+
+### `Failed to initialize NVML: Driver/library version mismatch`
+
+The CUDA user-space library version inside the image does not match the host kernel module. Solutions:
+
+- Use a container image whose CUDA version matches (or is older than) the driver's supported CUDA version (`nvidia-smi` shows the maximum supported CUDA version on the host).
+- Update the host NVIDIA driver.
+
+### `--gpus` flag not recognised by Docker
+
+Your Docker version is older than 19.03 or the NVIDIA runtime is not configured as the default. Run:
+
+```bash
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+Or pass the runtime explicitly (not needed if the overlay's `runArgs` is picked up):
+
+```bash
+docker run --runtime=nvidia --gpus all nvidia/cuda:12.0-base nvidia-smi
+```
+
+### GPU not visible in GitHub Codespaces / cloud dev environments
+
+Cloud hosted dev environments (GitHub Codespaces, Gitpod) typically do not provide GPU pass-through. Use a GPU-enabled cloud VM (AWS p-instances, GCP A100, Azure NCv3) and run VS Code Remote SSH or a self-hosted Codespace runner with GPU support.
+
+## Security Considerations
+
+`--gpus=all` grants the container access to all host GPUs. This is appropriate for development but should not be used in untrusted or multi-tenant environments without additional isolation.
+
+## References
+
+- [NVIDIA Container Toolkit — install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
+- [NVIDIA CUDA Docker images](https://hub.docker.com/r/nvidia/cuda)
+- [NVIDIA NGC catalogue](https://catalog.ngc.nvidia.com)
+- [devcontainer spec — hostRequirements](https://containers.dev/implementors/json_reference/#general-properties)
+
+**Related Overlays:**
+
+- `python` — Python runtime for ML workloads
+- `jupyter` — GPU-accelerated interactive notebooks
+- `docker-in-docker` / `docker-sock` — Build GPU-enabled container images from within the dev container
+
+> 🔜 **ROCm (AMD GPU)** support is tracked in a separate overlay (`rocm`). When that overlay is added it must declare `cuda` in its `conflicts` to satisfy the bidirectional conflict requirement.

package/overlays/cuda/devcontainer.patch.json

@@ -0,0 +1,7 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runArgs": ["--gpus=all"],
+    "hostRequirements": {
+        "gpu": true
+    }
+}

package/overlays/cuda/overlay.yml

@@ -0,0 +1,17 @@
+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:
+    - dev
+    - gpu
+    - cuda
+    - nvidia
+    - ml
+    - inference
+ports: []

package/overlays/cuda/setup.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# CUDA overlay setup script
+# Checks that nvidia-smi is reachable inside the container and prints
+# a helpful message when the host is not configured for GPU passthrough.
+
+set -e
+
+echo "🖥️  Setting up CUDA (NVIDIA GPU) overlay..."
+
+if nvidia-smi -L >/dev/null 2>&1; then
+    echo "✓ nvidia-smi found: $(nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null | head -n1 || nvidia-smi -L 2>/dev/null | head -n1 || echo 'GPU detected')"
+    echo "✓ CUDA overlay is ready"
+else
+    echo ""
+    echo "⚠️  nvidia-smi is installed but failed to run inside the container."
+    echo ""
+    echo "   GPU passthrough requires the following on the host:"
+    echo "   1. A supported NVIDIA GPU"
+    echo "   2. NVIDIA drivers installed on the host"
+    echo "   3. NVIDIA Container Toolkit installed and configured:"
+    echo "      https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html"
+    echo "   4. Docker configured to use the NVIDIA runtime:"
+    echo "      nvidia-ctk runtime configure --runtime=docker"
+    echo ""
+    echo "   This overlay adds '--gpus=all' to the container's runArgs and sets"
+    echo "   hostRequirements.gpu = true in devcontainer.json, but it cannot"
+    echo "   install or replace host drivers."
+    echo ""
+    echo "   Once the host is configured, rebuild the dev container."
+    echo ""
+    echo "ℹ️  CUDA overlay setup complete (nvidia-smi not functioning on this host)"
+fi

package/overlays/cuda/verify.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Verification script for CUDA overlay
+# Asserts nvidia-smi exits 0 (used by the doctor command)
+
+set -e
+
+echo "🔍 Verifying CUDA (NVIDIA GPU) overlay..."
+echo ""
+
+echo "1️⃣ Checking nvidia-smi..."
+if command -v nvidia-smi &> /dev/null; then
+    if nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv,noheader 2>/dev/null; then
+        echo "   ✅ nvidia-smi is available and GPU is accessible"
+    elif nvidia-smi -L; then
+        echo "   ✅ nvidia-smi is available and GPU is accessible"
+    else
+        echo "   ❌ nvidia-smi is installed but failed to query GPU information"
+        echo ""
+        echo "   Possible causes:"
+        echo "   - NVIDIA driver is not loaded or mismatched with the container CUDA version"
+        echo "   - Insufficient permissions to access the GPU from this container"
+        echo "   - NVIDIA Container Toolkit / runtime is misconfigured"
+        echo ""
+        echo "   Resolve the above issues and retry the CUDA overlay verification."
+        exit 1
+    fi
+else
+    echo "   ❌ nvidia-smi not found"
+    echo ""
+    echo "   Ensure the host has:"
+    echo "   - NVIDIA drivers installed"
+    echo "   - NVIDIA Container Toolkit installed and configured"
+    echo "   - Docker runtime configured for NVIDIA (nvidia-ctk runtime configure)"
+    exit 1
+fi
+
+echo ""
+echo "✅ CUDA overlay verification complete"

package/overlays/devcontainer-cli/README.md

@@ -0,0 +1,50 @@
+# Dev Container CLI Overlay
+
+Installs the [official devcontainer CLI](https://github.com/devcontainers/cli) (`@devcontainers/cli`) for building, running, and testing devcontainer configurations from the command line.
+
+Useful for projects that generate or verify devcontainer configurations programmatically — including container-superposition itself.
+
+## Features
+
+- **`devcontainer` CLI** — Build, run, and test devcontainer configurations from the command line
+- **Node.js LTS** — Required runtime (included if not already present)
+- **VS Code Extension:** Dev Containers (ms-vscode-remote.remote-containers)
+
+## How It Works
+
+The setup script installs `@devcontainers/cli` as a global npm package. Node.js LTS is included via a devcontainer feature if not already available in the environment.
+
+## Common Commands
+
+```bash
+# Build a devcontainer image
+devcontainer build --workspace-folder .
+
+# Start a devcontainer
+devcontainer up --workspace-folder .
+
+# Run a command inside the devcontainer
+devcontainer exec --workspace-folder . -- bash -c "echo hello"
+
+# Check the CLI version
+devcontainer --version
+```
+
+## Use Cases
+
+- **CI/CD validation** — Build and test devcontainer configurations in pipelines
+- **Container-superposition development** — Verify generated `.devcontainer/` outputs actually build
+- **Toolchain testing** — Ensure devcontainer features and overlays compose correctly
+
+## Requires Docker
+
+The devcontainer CLI needs a Docker daemon to build containers. Pair with one of:
+
+- [`docker-sock`](../docker-sock/README.md) — bind-mount host Docker socket (simpler, works everywhere)
+- [`docker-in-docker`](../docker-in-docker/README.md) — isolated Docker daemon (better for nested containers)
+
+## References
+
+- [devcontainers/cli on GitHub](https://github.com/devcontainers/cli)
+- [Dev Containers specification](https://containers.dev/)
+- [devcontainer CLI npm package](https://www.npmjs.com/package/@devcontainers/cli)

package/overlays/devcontainer-cli/devcontainer.patch.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "ghcr.io/devcontainers/features/node:1": {
+            "version": "lts"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["ms-vscode-remote.remote-containers"]
+        }
+    }
+}

package/overlays/devcontainer-cli/overlay.yml

@@ -0,0 +1,16 @@
+id: devcontainer-cli
+name: Dev Container CLI
+description: Official devcontainer CLI for building and testing devcontainer configurations
+category: dev
+supports: []
+requires: []
+suggests:
+    - docker-sock
+    - docker-in-docker
+conflicts: []
+tags:
+    - dev
+    - devcontainer
+    - cli
+    - testing
+ports: []

package/overlays/devcontainer-cli/setup.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Dev Container CLI setup script - Install @devcontainers/cli globally
+
+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 @devcontainers/cli..."
+npm install -g @devcontainers/cli
+
+echo "✓ devcontainer CLI installed: $(devcontainer --version)"

package/overlays/direnv/devcontainer.patch.json

@@ -1,5 +1,11 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "direnv",
+            "apk": "direnv"
+        }
+    },
     "remoteEnv": {
         "DIRENV_LOG_FORMAT": ""
     }

package/overlays/direnv/setup.sh

@@ -5,15 +5,11 @@ set -e
 
 echo "🔐 Setting up direnv..."
 
-# Install direnv from package manager
-sudo apt-get update -qq
-sudo apt-get install -y direnv
-
-# Verify installation
+# Verify installation (installed via cross-distro-packages feature)
 if command -v direnv &> /dev/null; then
     echo "✓ direnv installed: $(direnv version)"
 else
-    echo "✗ direnv installation failed"
+    echo "✗ direnv not found — check cross-distro-packages feature"
     exit 1
 fi
 
@@ -80,6 +76,11 @@ EOF
     echo "✓ .envrc pre-allowed (run 'direnv deny' to disable)"
 fi
 
+# Ensure any pre-existing .envrc is also allowed (idempotent re-runs)
+if [ -f .envrc ]; then
+    direnv allow .envrc 2>/dev/null || true
+fi
+
 # Create sample .env file if it doesn't exist
 if [ ! -f .env ] && [ ! -f .env.example ]; then
     cat > .env.example << 'EOF'

package/overlays/dotnet/setup.sh

@@ -3,6 +3,15 @@
 
 set -e
 
+# Source shared setup utilities (provides run_spinner)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+# Suppress the .NET SDK first-run welcome banner and telemetry noise
+export DOTNET_NOLOGO=1
+export DOTNET_CLI_TELEMETRY_OPTOUT=1
+export DOTNET_SKIP_FIRST_TIME_EXPERIENCE=1
+
 # Extract overlay name from script filename (setup-<overlay>.sh -> <overlay>)
 OVERLAY_NAME=$(basename "$0" | sed 's/setup-//;s/\.sh$//')
 
@@ -21,20 +30,18 @@ if [ -f ".devcontainer/global-tools-${OVERLAY_NAME}.txt" ]; then
         if [[ "$line" =~ ^(.+)::(.+)$ ]]; then
             tool="${BASH_REMATCH[1]}"
             version="${BASH_REMATCH[2]}"
-            echo "  Installing $tool version $version..."
-            dotnet tool install --global "$tool" --version "$version" || echo "  ⚠️  $tool already installed or failed"
+            run_spinner "$tool@$version" dotnet tool install --global "$tool" --version "$version" || true
         else
             tool="$line"
-            echo "  Installing $tool..."
-            dotnet tool install --global "$tool" || echo "  ⚠️  $tool already installed or failed"
+            run_spinner "$tool" dotnet tool install --global "$tool" || true
         fi
     done < ".devcontainer/global-tools-${OVERLAY_NAME}.txt"
 else
     # Fallback to hardcoded list
     echo "📦 Installing default .NET global tools..."
-    dotnet tool install --global dotnet-ef || echo "dotnet-ef already installed"
-    dotnet tool install --global dotnet-format || echo "dotnet-format already installed"
-    dotnet tool install --global dotnet-outdated-tool || echo "dotnet-outdated-tool already installed"
+    run_spinner "dotnet-ef" dotnet tool install --global dotnet-ef || true
+    run_spinner "dotnet-format" dotnet tool install --global dotnet-format || true
+    run_spinner "dotnet-outdated-tool" dotnet tool install --global dotnet-outdated-tool || true
 fi
 
 # Verify installations

package/overlays/duckdb/devcontainer.patch.json

@@ -5,6 +5,5 @@
             "apt": "wget unzip",
             "apk": "wget unzip"
         }
-    },
-    "postCreateCommand": "bash .devcontainer/scripts/setup-duckdb.sh"
+    }
 }

package/overlays/gcloud/devcontainer.patch.json

@@ -1,11 +1,5 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
-    "features": {
-        "ghcr.io/devcontainers/features/google-cloud-cli:1": {
-            "version": "latest",
-            "installGkeGcloudAuthPlugin": true
-        }
-    },
     "customizations": {
         "vscode": {
             "extensions": ["googlecloudtools.cloudcode"]

package/overlays/gcloud/setup.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Google Cloud CLI setup script
+
+set -e
+
+echo "☁️  Setting up Google Cloud CLI..."
+
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+if command -v apk >/dev/null 2>&1; then
+    # Alpine Linux — no official gcloud apt repo; install via tarball
+    apk add --no-cache python3 curl
+    curl -sSL https://sdk.cloud.google.com | CLOUDSDK_CORE_DISABLE_PROMPTS=1 bash -s -- --disable-prompts --install-dir=/usr/local
+    ln -sf /usr/local/google-cloud-sdk/bin/gcloud /usr/local/bin/gcloud
+    ln -sf /usr/local/google-cloud-sdk/bin/gsutil /usr/local/bin/gsutil
+elif command -v apt-get >/dev/null 2>&1; then
+    # Debian/Ubuntu — add Google Cloud apt repo using modern signed-by method
+    # The Google Cloud key is already in binary (non-armored) format — write directly.
+    sudo mkdir -p /usr/share/keyrings /etc/apt/sources.list.d
+    curl -fsSL "https://packages.cloud.google.com/apt/doc/apt-key.gpg" \
+        | sudo tee /usr/share/keyrings/cloud.google.gpg >/dev/null
+    echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
+        | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list >/dev/null
+
+    # Single lock acquisition: install prereqs + add repo + install gcloud in one pass
+    acquire_apt_lock
+    # Pass env vars explicitly — sudo strips them by default.
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get update -qq
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get install -y -qq --no-install-recommends apt-transport-https ca-certificates gnupg curl
+    # apt index already fresh — install gcloud packages without a second apt-get update
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get install -y -qq --no-install-recommends \
+        google-cloud-cli \
+        google-cloud-cli-gke-gcloud-auth-plugin
+    sudo apt-get clean
+    sudo rm -rf /var/lib/apt/lists/*
+    release_apt_lock
+else
+    echo "⚠️  Unsupported package manager, skipping gcloud installation"
+    exit 0
+fi
+
+if command -v gcloud >/dev/null 2>&1; then
+    echo "✓ gcloud installed: $(gcloud --version | head -1)"
+else
+    echo "✗ gcloud installation failed"
+    exit 1
+fi
+
+echo "✓ gcloud setup complete"

package/overlays/gemini-cli/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 Google Gemini CLI..."
 
 # Install @google/gemini-cli globally

package/overlays/git-helpers/devcontainer.patch.json

@@ -6,7 +6,8 @@
             "version": "os-provided"
         },
         "ghcr.io/devcontainers/features/git-lfs:1": {
-            "version": "latest"
+            "version": "latest",
+            "autoPull": false
         },
         "ghcr.io/devcontainers/features/github-cli:1": {
             "version": "latest"

package/overlays/go/setup.sh

@@ -3,25 +3,26 @@
 
 set -e
 
-echo "🔧 Setting up Go development environment..."
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
 
-# Install common Go tools
+echo "🔧 Setting up Go development environment..."
 echo "📦 Installing Go development tools..."
 
-# gopls (Language Server)
-go install golang.org/x/tools/gopls@latest || echo "⚠️ gopls installation failed"
-
-# delve (Debugger)
-go install github.com/go-delve/delve/cmd/dlv@latest || echo "⚠️ delve installation failed"
+run_spinner "gopls (language server)"   go install golang.org/x/tools/gopls@latest
+run_spinner "delve (debugger)"          go install github.com/go-delve/delve/cmd/dlv@latest
 
-# golangci-lint (Linter) - install via go install for security
-go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest || echo "⚠️ golangci-lint installation failed"
-
-# gofumpt (Formatter)
-go install mvdan.cc/gofumpt@latest || echo "⚠️ gofumpt installation failed"
+# golangci-lint — use official installer to avoid gold linker issues on arm64
+if ! command -v golangci-lint &>/dev/null; then
+    run_spinner "golangci-lint" \
+        bash -c 'curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b "$(go env GOPATH)/bin"'
+else
+    echo "  ℹ️  golangci-lint already installed: $(golangci-lint version --short 2>/dev/null || true)"
+fi
 
-# staticcheck (Static analyzer)
-go install honnef.co/go/tools/cmd/staticcheck@latest || echo "⚠️ staticcheck installation failed"
+run_spinner "gofumpt (formatter)"      go install mvdan.cc/gofumpt@latest
+run_spinner "staticcheck (analyzer)"   go install honnef.co/go/tools/cmd/staticcheck@latest
 
 # Install project dependencies if go.mod exists
 if [ -f "go.mod" ]; then

package/overlays/jaeger/overlay.yml

@@ -30,3 +30,5 @@ ports:
       description: Jaeger HTTP receiver
       onAutoForward: ignore
 order: 1
+imports:
+    - .shared/otel/instrumentation.env

package/overlays/just/setup.sh

@@ -9,31 +9,19 @@ echo "⚡ Setting up just task runner..."
 JUST_VERSION="1.25.2"
 ARCH=$(uname -m)
 
-# SHA256 checksums for just v1.25.2
-if [ "$ARCH" = "x86_64" ]; then
-    ARCH="x86_64"
-    CHECKSUM="6804798c3744fd1ce563840ee9fe14ae53c74b3cc7b8536da3f87751d7f85501"
-elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
+if [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
     ARCH="aarch64"
-    CHECKSUM="f287a95846131ce8de65181b0b1ec0a0b7db4f6f8d393b3b548f70fcb5a4b0ee"
+elif [ "$ARCH" = "x86_64" ]; then
+    ARCH="x86_64"
 else
-    echo "⚠️  Unsupported architecture: $ARCH"
+    echo "⚠️  Unsupported architecture: $ARCH, falling back to x86_64"
     ARCH="x86_64"
-    CHECKSUM="6804798c3744fd1ce563840ee9fe14ae53c74b3cc7b8536da3f87751d7f85501"
 fi
 
 echo "📦 Downloading just v${JUST_VERSION} for ${ARCH}..."
-curl -L "https://github.com/casey/just/releases/download/${JUST_VERSION}/just-${JUST_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" \
+curl -fsSL "https://github.com/casey/just/releases/download/${JUST_VERSION}/just-${JUST_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" \
     -o /tmp/just.tar.gz
 
-# Verify checksum
-echo "🔐 Verifying checksum..."
-echo "${CHECKSUM}  /tmp/just.tar.gz" | sha256sum -c - || {
-    echo "✗ Checksum verification failed"
-    rm /tmp/just.tar.gz
-    exit 1
-}
-
 # Extract and install
 tar -xzf /tmp/just.tar.gz -C /tmp
 sudo mv /tmp/just /usr/local/bin/