container-superposition 0.1.5 → 0.1.7

package/overlays/rocm/README.md

@@ -0,0 +1,227 @@
+# ROCm (AMD GPU) Overlay
+
+Enables AMD GPU passthrough for containerized ML, inference, and ROCm compute workloads.
+
+> ⚠️ **ROCm-in-container is more fragile 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.
+
+## Features
+
+- **AMD GPU passthrough** - Device flags added to container `runArgs` so host AMD GPUs are accessible
+- **Group membership** - `--group-add=video` and `--group-add=render` ensure the container user can access GPU device nodes
+- **Setup check** - `setup.sh` verifies `rocm-smi` / `rocminfo` on container start and prints actionable guidance when GPU access is unavailable
+- **Doctor integration** - `verify.sh` asserts `rocm-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 AMD GPU** — RDNA 2+ or most CDNA GPUs. Check the [ROCm hardware compatibility matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html) before proceeding.
+2. **AMD GPU drivers (`amdgpu`)** — Install the driver package for your Linux distribution:
+    ```bash
+    # Example for Ubuntu — use amdgpu-install from AMD's repository
+    # https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/amdgpu-install.html
+    sudo apt-get install amdgpu-dkms
+    ```
+3. **ROCm runtime** — Install on the host (or use a container image that bundles it):
+    ```bash
+    # Example for Ubuntu
+    sudo apt-get install rocm
+    ```
+4. **Group membership** — Add your user to the `render` and `video` groups:
+    ```bash
+    sudo usermod -aG render,video $USER
+    # Log out and back in (or reboot) for group changes to take effect
+    ```
+5. **Device nodes** — Verify `/dev/kfd` and `/dev/dri` exist on the host:
+    ```bash
+    ls -la /dev/kfd /dev/dri/
+    ```
+
+> ⚠️ **This overlay cannot install or replace host drivers.** Version alignment between the ROCm 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:
+
+```json
+{
+    "runArgs": ["--device=/dev/kfd", "--device=/dev/dri", "--group-add=video", "--group-add=render"]
+}
+```
+
+| Flag                 | Purpose                                                           |
+| -------------------- | ----------------------------------------------------------------- |
+| `--device=/dev/kfd`  | AMD Kernel Fusion Driver; required for ROCm compute               |
+| `--device=/dev/dri`  | Direct Rendering Infrastructure; gives access to GPU render nodes |
+| `--group-add=video`  | Adds the container user to the `video` group (owns `/dev/dri`)    |
+| `--group-add=render` | Adds the container user to the `render` group (owns `/dev/kfd`)   |
+
+The container image itself must include ROCm user-space libraries (e.g., `libamdhip64`) to use ROCm APIs. See [Base Image](#base-image) below.
+
+## Base Image
+
+For ROCm workloads you typically want a ROCm-capable base image. Popular choices:
+
+| Image                   | Use case                             |
+| ----------------------- | ------------------------------------ |
+| `rocm/dev-ubuntu-22.04` | Ubuntu 22.04 with ROCm pre-installed |
+| `rocm/dev-ubuntu-24.04` | Ubuntu 24.04 with ROCm pre-installed |
+| `rocm/pytorch`          | PyTorch with ROCm support            |
+| `rocm/tensorflow`       | TensorFlow with ROCm support         |
+
+Browse all official ROCm images at [hub.docker.com/u/rocm](https://hub.docker.com/u/rocm).
+
+To use a ROCm image, set the `image` field in your `.devcontainer/devcontainer.json` (for plain stack) or configure the appropriate service's `image` in your compose-based devcontainer setup (for compose stack).
+
+## Common Commands
+
+### Check GPU availability
+
+```bash
+# Show GPU product name and status
+rocm-smi --showproductname
+
+# Show all GPU information
+rocm-smi
+
+# Show GPU utilisation
+rocm-smi --showuse
+
+# List all HSA (Heterogeneous System Architecture) agents
+rocminfo
+```
+
+### Discover device nodes
+
+```bash
+# List DRI render nodes on the host
+ls -la /dev/dri/
+
+# Show GPU device details
+rocm-smi --showbus
+```
+
+### Query ROCm version
+
+```bash
+# ROCm version
+cat /opt/rocm/.info/version 2>/dev/null || rocminfo | grep -i 'rocm\|version' | head -n5
+```
+
+### Python / PyTorch ROCm smoke test
+
+```python
+import torch
+print(torch.cuda.is_available())        # True (ROCm uses the CUDA compatibility layer)
+print(torch.cuda.get_device_name(0))    # e.g. "AMD Radeon RX 7900 XTX"
+```
+
+> **Note:** PyTorch ROCm uses `torch.cuda` APIs via the HIP/CUDA compatibility layer. Install the ROCm-specific PyTorch wheel:
+>
+> ```bash
+> pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.0
+> ```
+>
+> Find the correct wheel URL at [pytorch.org/get-started/locally](https://pytorch.org/get-started/locally/).
+
+### TensorFlow ROCm smoke test
+
+```python
+import tensorflow as tf
+print(tf.config.list_physical_devices('GPU'))
+```
+
+> Install the ROCm-specific TensorFlow wheel from [tensorflow/rocm releases](https://github.com/ROCm/tensorflow-upstream/releases).
+
+## Use Cases
+
+- **Model inference** — Run LLM or CV model inference with AMD GPU acceleration
+- **Training** — Train deep learning models without leaving the dev container
+- **ROCm compute** — General-purpose GPU programming with HIP (AMD's CUDA-compatible API)
+- **Jupyter notebooks** — GPU-accelerated data science with Jupyter (combine with the `jupyter` overlay)
+
+**Integrates well with:**
+
+- `python` — Python runtime for ML workloads
+- `jupyter` — Interactive GPU notebooks
+
+## Troubleshooting
+
+### `rocm-smi: command not found`
+
+The container image does not include the ROCm tools. Either:
+
+1. Switch to a ROCm base image (e.g., `rocm/dev-ubuntu-22.04`)
+2. Install ROCm tools inside the image:
+    ```bash
+    sudo apt-get install rocm-smi-lib rocminfo
+    ```
+
+### `No AMD GPU detected` / `/dev/kfd not found`
+
+The GPU device nodes are not accessible inside the container. Work through this checklist:
+
+1. Verify device nodes exist on the **host**:
+    ```bash
+    ls -la /dev/kfd /dev/dri/
+    ```
+2. Verify the `amdgpu` kernel module is loaded on the host:
+    ```bash
+    lsmod | grep amdgpu
+    ```
+3. Rebuild the dev container after confirming device nodes exist.
+
+### `Permission denied on /dev/kfd`
+
+The container user is not in the correct groups. Verify:
+
+```bash
+# Inside the container, check current groups
+id
+
+# On the host, add user to groups and re-login
+sudo usermod -aG render,video $USER
+```
+
+### `ROCm version mismatch`
+
+The ROCm user-space library version inside the image does not match the host kernel module version. Solutions:
+
+- Use a container image whose ROCm version matches the host ROCm installation
+- Check the host ROCm version: `cat /opt/rocm/.info/version`
+- Use the corresponding `rocm/dev-*` image tag
+
+### `--device` flag not recognised
+
+Ensure your Docker version is 19.03+ and the Docker daemon can access the host device nodes.
+
+### GPU not visible in GitHub Codespaces / cloud dev environments
+
+Cloud hosted dev environments (GitHub Codespaces, Gitpod) typically do not provide AMD GPU passthrough. Use a GPU-enabled cloud VM with AMD GPU support and run VS Code Remote SSH.
+
+## Known Limitations
+
+- ROCm version support is tightly coupled to the host kernel version and AMD driver stack
+- Device node names (`/dev/dri/renderD128`) may differ between hosts; the `--device=/dev/dri` flag passes the entire directory
+- Not all AMD GPU architectures are supported — always consult the [ROCm compatibility matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html)
+- Some frameworks (PyTorch, TensorFlow) require separate ROCm-specific wheels — see [Common Commands](#common-commands)
+- ROCm setup is generally less forgiving than CUDA; when in doubt, test `rocm-smi` on the host first
+
+## Security Considerations
+
+`--device=/dev/kfd` and `--device=/dev/dri` grant the container access to the GPU device nodes. This is appropriate for development but should not be used in untrusted or multi-tenant environments.
+
+## References
+
+- [ROCm documentation](https://rocm.docs.amd.com/)
+- [ROCm hardware compatibility matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html)
+- [ROCm installation guide (Linux)](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/)
+- [ROCm Docker images (hub.docker.com/u/rocm)](https://hub.docker.com/u/rocm)
+- [PyTorch ROCm wheels](https://pytorch.org/get-started/locally/)
+- [TensorFlow ROCm releases](https://github.com/ROCm/tensorflow-upstream/releases)
+
+**Related Overlays:**
+
+- `python` — Python runtime for ML workloads
+- `jupyter` — GPU-accelerated interactive notebooks
+- `cuda` — NVIDIA GPU passthrough (conflicts with `rocm`)

package/overlays/rocm/devcontainer.patch.json

@@ -0,0 +1,4 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "runArgs": ["--device=/dev/kfd", "--device=/dev/dri", "--group-add=video", "--group-add=render"]
+}

package/overlays/rocm/overlay.yml

@@ -0,0 +1,17 @@
+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: []

package/overlays/rocm/setup.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# ROCm overlay setup script
+# Checks that rocm-smi / rocminfo is reachable inside the container and prints
+# a helpful message when the host is not configured for AMD GPU passthrough.
+
+set -e
+
+echo "🖥️  Setting up ROCm (AMD GPU) overlay..."
+
+if rocm-smi --showproductname >/dev/null 2>&1; then
+    gpu_name="$(rocm-smi --showproductname 2>/dev/null | grep -i 'card\|gpu\|product' | head -n1)"
+    if [ -z "$gpu_name" ]; then
+        gpu_name="AMD GPU detected"
+    fi
+    echo "✓ rocm-smi found: $gpu_name"
+    echo "✓ ROCm overlay is ready"
+elif rocminfo >/dev/null 2>&1; then
+    gpu_name="$(rocminfo 2>/dev/null | grep 'Marketing Name' | head -n1 | sed 's/.*: *//')"
+    if [ -z "$gpu_name" ]; then
+        gpu_name="AMD GPU detected"
+    fi
+    echo "✓ rocminfo found: $gpu_name"
+    echo "✓ ROCm overlay is ready"
+else
+    echo ""
+    echo "⚠️  Neither rocm-smi nor rocminfo is functioning inside the container."
+    echo ""
+    echo "   AMD GPU passthrough requires the following on the host:"
+    echo "   1. A supported AMD GPU (RDNA 2+ or CDNA — check the compatibility matrix:"
+    echo "      https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html)"
+    echo "   2. AMD GPU drivers (amdgpu) installed on the host"
+    echo "   3. ROCm runtime installed on the host (or bundled in the container image)"
+    echo "   4. Your user added to the 'render' and 'video' groups:"
+    echo "      sudo usermod -aG render,video \$USER"
+    echo "   5. /dev/kfd and /dev/dri devices accessible in the container"
+    echo ""
+    echo "   This overlay adds the following to the container's runArgs:"
+    echo "     --device=/dev/kfd  --device=/dev/dri"
+    echo "     --group-add=video  --group-add=render"
+    echo "   but it cannot install or replace host drivers."
+    echo ""
+    echo "   Once the host is configured, rebuild the dev container."
+    echo ""
+    echo "ℹ️  ROCm overlay setup complete (rocm-smi not functioning on this host)"
+fi

package/overlays/rocm/verify.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Verification script for ROCm overlay
+# Asserts rocm-smi exits 0 (used by the doctor command)
+
+# Don't exit on error - we want to report all failures
+ALL_CHECKS_PASSED=true
+
+echo "🔍 Verifying ROCm (AMD GPU) overlay..."
+echo ""
+
+echo "1️⃣ Checking rocm-smi..."
+if command -v rocm-smi &> /dev/null; then
+    if rocm-smi --showproductname 2>/dev/null; then
+        echo "   ✅ rocm-smi is available and AMD GPU is accessible"
+    elif rocm-smi 2>/dev/null; then
+        echo "   ✅ rocm-smi is available and AMD GPU is accessible"
+    else
+        echo "   ❌ rocm-smi is installed but failed to query GPU information"
+        echo ""
+        echo "   Possible causes:"
+        echo "   - AMD GPU driver (amdgpu) is not loaded on the host"
+        echo "   - /dev/kfd or /dev/dri is not accessible in this container"
+        echo "   - Container user is not in the 'render' or 'video' group"
+        echo "   - ROCm version mismatch between container image and host kernel"
+        echo ""
+        echo "   Resolve the above issues and retry the ROCm overlay verification."
+        ALL_CHECKS_PASSED=false
+    fi
+else
+    echo "   ❌ rocm-smi not found"
+    echo ""
+    echo "   Ensure the host has:"
+    echo "   - AMD GPU drivers (amdgpu) installed"
+    echo "   - ROCm runtime installed on the host or bundled in the container image"
+    echo "   - /dev/kfd and /dev/dri accessible in the container"
+    echo "   - Container user in the 'render' and 'video' groups"
+    ALL_CHECKS_PASSED=false
+fi
+
+echo ""
+if [ "$ALL_CHECKS_PASSED" = true ]; then
+    echo "✅ ROCm overlay verification complete"
+    exit 0
+else
+    echo "❌ ROCm overlay verification failed"
+    exit 1
+fi

package/overlays/rust/setup.sh

@@ -3,34 +3,27 @@
 
 set -e
 
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+export CARGO_TERM_COLOR=never
+
 echo "🔧 Setting up Rust development environment..."
 
 # Install common Rust components and tools
-echo "📦 Installing Rust components..."
-
-# rustfmt (Code formatter)
-rustup component add rustfmt || echo "⚠️ rustfmt already installed"
-
-# clippy (Linter)
-rustup component add clippy || echo "⚠️ clippy already installed"
-
-# rust-src (Source code for standard library)
-rustup component add rust-src || echo "⚠️ rust-src already installed"
+run_spinner "rustfmt component"    rustup component add rustfmt
+run_spinner "clippy component"     rustup component add clippy
+run_spinner "rust-src component"   rustup component add rust-src
 
 # Install common cargo tools
 echo "📦 Installing cargo tools..."
-
-# cargo-watch (Auto-rebuild on file changes)
-cargo install cargo-watch || echo "⚠️ cargo-watch already installed"
-
-# cargo-edit (Manage dependencies from CLI)
-cargo install cargo-edit || echo "⚠️ cargo-edit already installed"
+run_spinner "cargo-watch" cargo install --quiet cargo-watch
+run_spinner "cargo-edit"  cargo install --quiet cargo-edit
 
 # Install project dependencies if Cargo.toml exists
 if [ -f "Cargo.toml" ]; then
     echo "📦 Rust project detected, building dependencies..."
-    cargo fetch || echo "⚠️ cargo fetch failed"
-    cargo build || echo "⚠️ cargo build failed or skipped"
+    run_spinner "cargo fetch" cargo fetch
 fi
 
 echo "✓ Rust setup complete"

package/overlays/spec-kit/setup.sh

@@ -3,6 +3,10 @@
 
 set -e
 
+# Source shared setup utilities (provides run_spinner)
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
 echo "📦 Installing prerequisites for spec-kit..."
 
 # Ensure uv tool bin directory is always on PATH (uv puts shims here regardless
@@ -21,11 +25,11 @@ echo "📦 Installing specify-cli..."
 # Pin to a uv-managed Python (avoids broken system Python 3.13 on Debian trixie
 # where stdlib modules like shutil/os can be missing due to Debian's split packages)
 UV_PYTHON_VERSION="3.12"
-echo "  Ensuring uv-managed Python ${UV_PYTHON_VERSION} is available..."
-uv python install "${UV_PYTHON_VERSION}"
+run_spinner "Python ${UV_PYTHON_VERSION} (uv)"  uv python install --quiet "${UV_PYTHON_VERSION}"
 
 # Install specify-cli using the uv-managed Python, not the system interpreter
-uv tool install specify-cli --from git+https://github.com/github/spec-kit.git \
+run_spinner "specify-cli"  uv tool install --quiet specify-cli \
+    --from git+https://github.com/github/spec-kit.git \
     --python "${UV_PYTHON_VERSION}"
 
 # Verify — use the full path as a fallback in case the shim dir is not yet in PATH

package/overlays/sqlite/setup.sh

@@ -5,20 +5,20 @@ set -e
 
 echo "🔧 Setting up SQLite tools..."
 
-# Install litecli via pip if Python is available
-if command -v pip &> /dev/null || command -v pip3 &> /dev/null; then
-    echo "📦 Installing litecli..."
-    if command -v pip3 &> /dev/null; then
-        pip3 install --user litecli || echo "⚠️  litecli installation failed, continuing..."
-    else
-        pip install --user litecli || echo "⚠️  litecli installation failed, continuing..."
-    fi
-    
-    # Add to PATH if not already there
-    if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
-        echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
-        export PATH="$HOME/.local/bin:$PATH"
-    fi
+# Install litecli via pipx (avoids --user conflicts inside virtualenvs)
+if command -v pipx &> /dev/null; then
+    echo "📦 Installing litecli via pipx..."
+    pipx install litecli || echo "⚠️  litecli installation failed, continuing..."
+elif command -v pip3 &> /dev/null; then
+    echo "📦 Installing litecli via pip3..."
+    pip3 install litecli 2>/dev/null || \
+        pip3 install --break-system-packages litecli || \
+        echo "⚠️  litecli installation failed, continuing..."
+elif command -v pip &> /dev/null; then
+    echo "📦 Installing litecli via pip..."
+    pip install litecli 2>/dev/null || \
+        pip install --break-system-packages litecli || \
+        echo "⚠️  litecli installation failed, continuing..."
 else
     echo "⚠️  Python/pip not found, skipping litecli installation"
     echo "   Install Python overlay for enhanced SQLite CLI (litecli)"

package/overlays/sqlserver/docker-compose.yml

@@ -18,12 +18,12 @@ services:
             test:
                 [
                     'CMD-SHELL',
-                    "/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P '${MSSQL_SA_PASSWORD:-YourStrong@Passw0rd}' -Q 'SELECT 1' || exit 1",
+                    "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P '${MSSQL_SA_PASSWORD:-YourStrong@Passw0rd}' -Q 'SELECT 1' -No || exit 1",
                 ]
             interval: 10s
             timeout: 5s
-            retries: 5
-            start_period: 30s
+            retries: 10
+            start_period: 60s
 
 volumes:
     sqlserver-data:

package/overlays/sqlserver/verify.sh

@@ -10,10 +10,27 @@ echo ""
 # Check if SQL Server service is running
 echo "1️⃣ Checking SQL Server service..."
 SQLSERVER_READY=false
-for i in {1..30}; do
-    # Try to connect using docker exec (sqlcmd is in the container, not necessarily in dev container)
-    if docker exec $(docker ps -qf "name=sqlserver") /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'YourStrong@Passw0rd' -Q "SELECT 1" &> /dev/null; then
-        echo "   ✅ SQL Server service is ready"
+MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:-YourStrong@Passw0rd}"
+MSSQL_HOST="${MSSQL_HOST:-sqlserver}"
+MSSQL_PORT="${MSSQL_PORT:-1433}"
+
+for i in {1..60}; do
+    # Primary: sqlcmd via docker exec when Docker socket is available
+    if command -v docker &>/dev/null; then
+        CONTAINER=$(docker ps -qf "ancestor=mcr.microsoft.com/mssql/server" 2>/dev/null | head -1)
+        if [ -n "$CONTAINER" ] && \
+           docker exec "$CONTAINER" /opt/mssql-tools18/bin/sqlcmd \
+               -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -Q "SELECT 1" -No &>/dev/null 2>&1; then
+            echo "   ✅ SQL Server service is ready"
+            SQLSERVER_READY=true
+            break
+        fi
+    fi
+    # Fallback: TCP connectivity check (no Docker socket available)
+    if bash -c "echo > /dev/tcp/${MSSQL_HOST}/${MSSQL_PORT}" 2>/dev/null; then
+        # Port is open — allow a brief settle time for full SQL Server initialisation
+        sleep 15
+        echo "   ✅ SQL Server port ${MSSQL_PORT} is accepting connections"
         SQLSERVER_READY=true
         break
     fi
@@ -21,7 +38,7 @@ for i in {1..30}; do
 done
 
 if [ "$SQLSERVER_READY" = false ]; then
-    echo "   ❌ SQL Server service not ready after 60 seconds"
+    echo "   ❌ SQL Server service not ready after 120 seconds"
     echo "   ⚠️  SQL Server can take 30-60 seconds to start"
     exit 1
 fi

package/overlays/tempo/verify.sh

@@ -6,19 +6,25 @@ echo "🔍 Verifying Tempo installation..."
 # Track overall success
 ALL_CHECKS_PASSED=true
 
-# Check if Tempo service is running
-if docker ps --format '{{.Names}}' | grep -q tempo; then
-    echo "✓ Tempo service is running"
-else
-    echo "✗ Tempo service is not running"
+# Wait for Tempo /ready endpoint (primary health signal).
+# docker ps is informational only — not reliably accessible in all devcontainers.
+TEMPO_READY=false
+for i in {1..40}; do
+    if curl -s -o /dev/null -w "%{http_code}" http://tempo:3200/ready 2>/dev/null | grep -q "200"; then
+        echo "✓ Tempo HTTP API is accessible"
+        TEMPO_READY=true
+        break
+    fi
+    sleep 3
+done
+if [ "$TEMPO_READY" = false ]; then
+    echo "✗ Tempo /ready endpoint not responding after 120 s (http://tempo:3200/ready)"
     ALL_CHECKS_PASSED=false
 fi
 
-# Check if Tempo HTTP API is accessible
-if curl -s -o /dev/null -w "%{http_code}" http://tempo:3200/ready 2>/dev/null | grep -q "200"; then
-    echo "✓ Tempo HTTP API is accessible"
-else
-    echo "⚠️ Tempo HTTP 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 tempo; then
+    echo "✓ Tempo container visible in docker ps"
 fi
 
 # Final result

package/overlays/tilt/devcontainer.patch.json

@@ -12,6 +12,5 @@
             "label": "Tilt UI",
             "onAutoForward": "openBrowser"
         }
-    },
-    "postCreateCommand": "bash .devcontainer/scripts/setup-tilt.sh"
+    }
 }

package/overlays/tilt/setup.sh

@@ -5,13 +5,23 @@ set -e
 
 echo "🔧 Setting up Tilt..."
 
-# Install Tilt
-echo "📦 Installing Tilt..."
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
 
-curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash
+TILT_VERSION="${TILT_VERSION:-0.37.0}"
+detect_arch
+TILT_ARCH="$CS_ARCH"
+# tilt uses x86_64 for amd64 in its tarball names
+[ "$TILT_ARCH" = "amd64" ] && TILT_ARCH="x86_64"
+
+echo "📦 Installing Tilt v${TILT_VERSION} for linux.${TILT_ARCH}..."
+install_binary_from_tar \
+    "https://github.com/tilt-dev/tilt/releases/download/v${TILT_VERSION}/tilt.${TILT_VERSION}.linux.${TILT_ARCH}.tar.gz" \
+    "tilt"
 
 # Verify installation
-if command -v tilt &> /dev/null; then
+if command -v tilt &>/dev/null; then
     echo "✅ Tilt installed successfully"
     tilt version
 else

package/overlays/windsurf-cli/setup.sh

@@ -5,15 +5,38 @@ set -e
 
 echo "📦 Installing Codeium Windsurf CLI..."
 
-# Install windsurf globally via npm
-npm install -g @codeium/windsurf-cli
+# Windsurf CLI is distributed as a binary release from GitHub, not via npm
+ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64)  ARCH_TAG="x86_64" ;;
+    aarch64|arm64) ARCH_TAG="aarch64" ;;
+    *) echo "⚠️  Unsupported architecture: $ARCH, skipping windsurf-cli installation"; exit 0 ;;
+esac
+
+WINDSURF_VERSION=$(curl -fsSL https://api.github.com/repos/codeium-ai/windsurf-cli/releases/latest 2>/dev/null | grep '"tag_name"' | head -1 | sed 's/.*"tag_name": *"\([^"]*\)".*/\1/')
+
+if [ -z "$WINDSURF_VERSION" ]; then
+    echo "⚠️  Could not determine latest windsurf-cli version, trying known stable"
+    WINDSURF_VERSION="v0.1.0"
+fi
+
+echo "  Downloading windsurf-cli ${WINDSURF_VERSION} for ${ARCH_TAG}..."
+DOWNLOAD_URL="https://github.com/codeium-ai/windsurf-cli/releases/download/${WINDSURF_VERSION}/windsurf-linux-${ARCH_TAG}"
+
+if curl -fsSL --head "$DOWNLOAD_URL" >/dev/null 2>&1; then
+    curl -fsSL "$DOWNLOAD_URL" -o /tmp/windsurf
+    sudo install -m 0755 /tmp/windsurf /usr/local/bin/windsurf
+    rm -f /tmp/windsurf
+else
+    echo "⚠️  windsurf-cli binary not available for this platform — skipping"
+    exit 0
+fi
 
 # Verify installation
 if command -v windsurf &>/dev/null; then
     echo "✓ Windsurf CLI installed successfully: $(windsurf --version 2>/dev/null || echo 'installed')"
 else
-    echo "✗ Windsurf CLI installation failed"
-    exit 1
+    echo "⚠️  windsurf-cli not found after install — may need a shell restart"
 fi
 
 echo "✓ windsurf-cli setup complete"

package/overlays/windsurf-cli/verify.sh

@@ -5,10 +5,20 @@ set -e
 
 echo "🔍 Verifying windsurf-cli overlay setup..."
 
-# Check if windsurf CLI is installed
+# windsurf-cli is a best-effort install — it is skipped on unsupported platforms
+# (arm64 Linux). Exit 0 gracefully when it was intentionally not installed.
 if ! command -v windsurf &>/dev/null; then
-    echo "✗ windsurf CLI is not installed or not in PATH"
-    exit 1
+    ARCH=$(uname -m)
+    case "$ARCH" in
+        aarch64|arm64)
+            echo "ℹ️  windsurf-cli skipped (not available for $ARCH)"
+            exit 0
+            ;;
+        *)
+            echo "✗ windsurf CLI is not installed or not in PATH"
+            exit 1
+            ;;
+    esac
 fi
 
 echo "✓ windsurf CLI is installed: $(windsurf --version 2>/dev/null || echo 'installed')"