container-superposition 0.1.6 → 0.1.7

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/

package/overlays/keycloak/docker-compose.yml

@@ -15,18 +15,20 @@ services:
             KC_HTTP_PORT: 8180
             KC_HOSTNAME_STRICT: 'false'
             KC_HTTP_ENABLED: 'true'
+            KC_HEALTH_ENABLED: 'true'
         ports:
             - '${KEYCLOAK_PORT:-8180}:8180'
         depends_on:
-            - postgres
+            postgres:
+                condition: service_healthy
         networks:
             - devnet
         healthcheck:
-            test: ['CMD-SHELL', 'curl -sf http://localhost:8180/health/ready || exit 1']
+            test: ['CMD-SHELL', 'curl -sf http://localhost:9000/health/ready || exit 1']
             interval: 15s
             timeout: 10s
-            retries: 10
-            start_period: 60s
+            retries: 15
+            start_period: 90s
 
 networks:
     devnet:

package/overlays/keycloak/verify.sh

@@ -20,10 +20,11 @@ echo ""
 echo "2️⃣ Checking Keycloak service..."
 KEYCLOAK_HOST="${KEYCLOAK_HOST:-keycloak}"
 KEYCLOAK_PORT="${KEYCLOAK_PORT:-8180}"
+KEYCLOAK_MGMT_PORT="${KEYCLOAK_MGMT_PORT:-9000}"
 KEYCLOAK_READY=false
 
-for i in {1..40}; do
-    if curl -sf "http://${KEYCLOAK_HOST}:${KEYCLOAK_PORT}/health/ready" &> /dev/null; then
+for i in {1..80}; do
+    if curl -sf "http://${KEYCLOAK_HOST}:${KEYCLOAK_MGMT_PORT}/health/ready" &> /dev/null; then
         echo "   ✅ Keycloak service is ready"
         KEYCLOAK_READY=true
         break
@@ -32,7 +33,7 @@ for i in {1..40}; do
 done
 
 if [ "$KEYCLOAK_READY" = false ]; then
-    echo "   ❌ Keycloak service not ready after 2 minutes"
+    echo "   ❌ Keycloak service not ready after 4 minutes"
     echo "   ℹ️  Keycloak can take a while to start on first run"
     exit 1
 fi

package/overlays/kind/devcontainer.patch.json

@@ -5,6 +5,5 @@
             "apt": "curl",
             "apk": "curl"
         }
-    },
-    "postCreateCommand": "bash .devcontainer/scripts/setup-kind.sh"
+    }
 }

package/overlays/kind/setup.sh

@@ -5,28 +5,19 @@ set -e
 
 echo "🔧 Setting up kind (Kubernetes in Docker)..."
 
-# Detect architecture
-ARCH=$(uname -m)
-case $ARCH in
-    x86_64)
-        KIND_ARCH="amd64"
-        ;;
-    aarch64|arm64)
-        KIND_ARCH="arm64"
-        ;;
-    *)
-        echo "❌ Unsupported architecture: $ARCH"
-        exit 1
-        ;;
-esac
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
+detect_arch
 
 # Install kind
 KIND_VERSION="${KIND_VERSION:-v0.22.0}"
 echo "📦 Installing kind ${KIND_VERSION}..."
 
-curl -Lo /tmp/kind "https://kind.sigs.k8s.io/dl/${KIND_VERSION}/kind-linux-${KIND_ARCH}"
-chmod +x /tmp/kind
-sudo mv /tmp/kind /usr/local/bin/kind
+install_binary \
+    "https://kind.sigs.k8s.io/dl/${KIND_VERSION}/kind-linux-${CS_ARCH}" \
+    "kind"
 
 # Verify installation
 if command -v kind &> /dev/null; then

package/overlays/minio/setup.sh

@@ -7,25 +7,17 @@ echo "🔧 Setting up MinIO client..."
 
 # Install MinIO client (mc)
 echo "📦 Installing MinIO client (mc)..."
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
+
 if ! command -v mc &> /dev/null; then
-    # Pin to a specific version for security and reproducibility
-    MC_VERSION="RELEASE.2024-11-17T19-35-25Z"
-    MC_URL="https://dl.min.io/client/mc/release/linux-amd64/archive/mc.${MC_VERSION}"
-    MC_CHECKSUM="27e18faeabd9a0c8066e3b4aadb13a2c0ae4dac09a1e24defe34c99a11b59e26"
-    
-    echo "   Downloading MinIO client version ${MC_VERSION}..."
-    wget -q "${MC_URL}" -O /tmp/mc
-    
-    # Verify checksum
-    echo "   Verifying checksum..."
-    echo "${MC_CHECKSUM}  /tmp/mc" | sha256sum -c - || {
-        echo "   ❌ Checksum verification failed!"
-        rm -f /tmp/mc
-        exit 1
-    }
-    
-    sudo install /tmp/mc /usr/local/bin/
-    rm /tmp/mc
+    MC_VERSION="${MC_VERSION:-RELEASE.2024-11-17T19-35-25Z}"
+    detect_arch
+    echo "   Downloading MinIO client version ${MC_VERSION} for ${CS_ARCH}..."
+    install_binary \
+        "https://dl.min.io/client/mc/release/linux-${CS_ARCH}/archive/mc.${MC_VERSION}" \
+        "mc"
     echo "   ✅ MinIO client installed (${MC_VERSION})"
 else
     echo "   ✅ MinIO client already installed"

package/overlays/mkdocs/overlay.yml

@@ -6,7 +6,8 @@ supports: []
 requires:
     - python
 suggests: []
-conflicts: []
+conflicts:
+    - mkdocs2
 tags:
     - documentation
     - mkdocs

package/overlays/mkdocs2/README.md

@@ -0,0 +1,135 @@
+# MkDocs 2 Overlay
+
+MkDocs 2.0 pre-release from [encode/mkdocs](https://github.com/encode/mkdocs) — a smart, simple website design tool by Tom Christie.
+
+> **Pre-release notice:** MkDocs 2.0 is installed from the `encode/mkdocs` git repository. There is no PyPI release yet. This is a complete rewrite of the original MkDocs project — it is **not** backward-compatible with MkDocs 1.x.
+
+## Features
+
+- **MkDocs 2.0** — complete rewrite with modern architecture
+- **TOML configuration** — uses `mkdocs.toml` instead of `mkdocs.yml`
+- **Built-in theming** — custom theme system (does not use Material for MkDocs)
+- **GitHub Flavored Markdown** — native GFM support
+- **pymdown-extensions** — extended Markdown syntax included
+- **Python dependency** — automatically includes the Python overlay (required)
+- **VS Code Extensions:**
+    - Markdown All in One
+    - Markdown Lint
+    - Markdown Mermaid
+- **Port forwarding:** 8000 (MkDocs dev server, auto-opens in browser)
+
+## How It Works
+
+The overlay's `setup.sh` script installs MkDocs 2.0 directly from the
+[encode/mkdocs](https://github.com/encode/mkdocs) GitHub repository via
+`pip install git+https://github.com/encode/mkdocs.git` into the workspace
+virtual environment (`.venv`) created by the Python overlay.
+
+## Dependencies
+
+- Requires: **python** overlay (automatically selected)
+- Conflicts: **mkdocs** overlay — only one MkDocs variant can be active at a time
+
+## Quick Start
+
+### New Documentation Site
+
+```bash
+# Create a README.md and start the dev server
+echo "# My Docs" > README.md
+mkdocs serve
+# Opens at http://localhost:8000
+```
+
+### Build Static Site
+
+```bash
+mkdocs build
+```
+
+## Configuration
+
+MkDocs 2.0 uses `mkdocs.toml` (not the 1.x `mkdocs.yml`):
+
+```toml
+[mkdocs]
+nav = [
+    {path = "README.md", title = "Introduction"},
+    {path = "guide.md", title = "Guide"},
+    {path = "CREDITS.md", title = "Credits"},
+]
+
+[loaders]
+theme = "pkg://mkdocs/default"
+docs = "dir://docs"
+
+[context]
+title = "Documentation"
+favicon = "📘"
+```
+
+### Page Structure
+
+Use either `README.md` or `index.md` for the homepage. Place additional pages in a `docs/` directory:
+
+```
+my-project/
+├── mkdocs.toml
+├── README.md
+├── docs/
+│   ├── guide.md
+│   └── reference.md
+└── site/           # Built output (git-ignored)
+```
+
+## Key Differences from MkDocs 1.x
+
+| Feature        | MkDocs 1.x (`mkdocs` overlay) | MkDocs 2.0 (`mkdocs2` overlay) |
+| -------------- | ----------------------------- | ------------------------------ |
+| Config file    | `mkdocs.yml`                  | `mkdocs.toml`                  |
+| Theme          | Material for MkDocs           | Built-in themes                |
+| Plugin system  | `mkdocs-plugins` ecosystem    | New architecture               |
+| Install source | PyPI / devcontainer feature   | `encode/mkdocs` git repo       |
+| Markdown       | Standard + extensions         | GitHub Flavored Markdown       |
+| Status         | Stable (1.6.1)                | Pre-release (2.0)              |
+
+## Common Commands
+
+```bash
+# Start live-reloading dev server
+mkdocs serve
+
+# Build static site
+mkdocs build
+
+# Serve on a different port
+mkdocs serve --dev-addr 0.0.0.0:8001
+```
+
+## Troubleshooting
+
+### `mkdocs: command not found`
+
+The Python virtual environment may not be activated. Activate it manually:
+
+```bash
+source .venv/bin/activate
+mkdocs --version
+```
+
+### Port 8000 already in use
+
+Use a different port: `mkdocs serve --dev-addr 0.0.0.0:8001`
+
+## References
+
+- [encode/mkdocs on GitHub](https://github.com/encode/mkdocs)
+- [MkDocs 2.0 writing guide](https://github.com/encode/mkdocs/blob/main/docs/writing.md)
+- [MkDocs 2.0 navigation docs](https://github.com/encode/mkdocs/blob/main/docs/navigation.md)
+- [MkDocs 2.0 styling docs](https://github.com/encode/mkdocs/blob/main/docs/styling.md)
+
+**Related Overlays:**
+
+- `python` — required Python runtime
+- `mkdocs` — legacy MkDocs 1.x overlay (conflicts with this overlay)
+- `pandoc` — convert Markdown to PDF

package/overlays/mkdocs2/devcontainer.patch.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "yzhang.markdown-all-in-one",
+                "DavidAnson.vscode-markdownlint",
+                "bierner.markdown-mermaid"
+            ]
+        }
+    },
+    "forwardPorts": [8000],
+    "portsAttributes": {
+        "8000": {
+            "label": "MkDocs Server",
+            "onAutoForward": "openBrowser"
+        }
+    }
+}

package/overlays/mkdocs2/overlay.yml

@@ -0,0 +1,17 @@
+id: mkdocs2
+name: MkDocs 2
+description: MkDocs 2.0 pre-release (encode/mkdocs) — smart, simple website design tool
+category: dev
+supports: []
+requires:
+    - python
+suggests: []
+conflicts:
+    - mkdocs
+tags:
+    - dev
+    - documentation
+    - mkdocs
+    - python
+ports:
+    - 8000

package/overlays/mkdocs2/setup.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# mkdocs2 setup script — install MkDocs 2.0 pre-release from encode/mkdocs
+
+set -e
+
+echo "📚 Setting up MkDocs 2.0 (encode/mkdocs)..."
+
+# Always install into the workspace virtual environment.
+# The Python overlay is declared as a hard dependency (requires: [python]) so
+# its setup script should have run first; but if the .venv doesn't exist yet
+# (e.g., ordering edge-case) we create it here so this script is self-contained.
+VENV_DIR="${PWD}/.venv"
+
+# Helper: validate that the venv's Python interpreter is actually executable.
+venv_is_valid() {
+    "${VENV_DIR}/bin/python" -c "import sys" &>/dev/null
+}
+
+if [ -d "${VENV_DIR}" ]; then
+    if venv_is_valid; then
+        echo "  Using virtual environment: ${VENV_DIR}"
+    else
+        echo "⚠️  Existing .venv is invalid (stale interpreter or broken site-packages), recreating..."
+        rm -rf "${VENV_DIR}"
+    fi
+else
+    # Also handle the case where the directory listing showed site-packages exists
+    # but venv_is_valid failed — this handles partial/corrupted venvs
+    : # nothing to do, venv doesn't exist yet
+fi
+
+# If the venv directory exists but python fails with EEXIST on site-packages,
+# it is a leftover from a previous interrupted run — recreate it.
+if [ -d "${VENV_DIR}" ] && ! "${VENV_DIR}/bin/python" -m pip --version &>/dev/null; then
+    echo "⚠️  Existing .venv has broken pip, recreating..."
+    rm -rf "${VENV_DIR}"
+fi
+
+if [ ! -d "${VENV_DIR}" ]; then
+    echo "📦 Creating virtual environment at .venv..."
+    if ! command -v python3 &>/dev/null; then
+        echo "❌ python3 is not available. Please ensure the python overlay is included."
+        exit 1
+    fi
+    python3 -m venv "${VENV_DIR}"
+    echo "✓ Virtual environment created"
+fi
+
+# Use the venv's Python directly to invoke pip — this is more robust than
+# calling the pip wrapper script, whose shebang can point to a stale path.
+PYTHON="${VENV_DIR}/bin/python"
+
+echo "📦 Installing MkDocs 2.0 from encode/mkdocs..."
+"${PYTHON}" -m pip install -q --no-cache-dir \
+    "mkdocs @ git+https://github.com/encode/mkdocs.git"
+
+MKDOCS_BIN="${VENV_DIR}/bin/mkdocs"
+if [ -x "${MKDOCS_BIN}" ]; then
+    echo "✓ $( "${MKDOCS_BIN}" --version 2>/dev/null || echo 'mkdocs 2.0' )"
+else
+    echo "✗ mkdocs not found in ${VENV_DIR}/bin after installation"
+    exit 1
+fi
+
+echo "✅ MkDocs 2.0 setup complete"
+echo "ℹ️  Start dev server: mkdocs serve"
+echo "ℹ️  Build static site:  mkdocs build"

package/overlays/mkdocs2/verify.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# mkdocs2 overlay verification script
+
+echo "🔍 Verifying MkDocs 2.0 overlay setup..."
+
+ALL_CHECKS_PASSED=true
+
+# mkdocs may be installed inside .venv (Python overlay) or on the system PATH
+MKDOCS_BIN="mkdocs"
+if [ -f "${PWD}/.venv/bin/mkdocs" ]; then
+    MKDOCS_BIN="${PWD}/.venv/bin/mkdocs"
+fi
+
+# Check mkdocs is available
+if ! command -v "${MKDOCS_BIN}" &>/dev/null && [ ! -x "${MKDOCS_BIN}" ]; then
+    echo "✗ mkdocs not found"
+    ALL_CHECKS_PASSED=false
+else
+    VERSION=$("${MKDOCS_BIN}" --version 2>/dev/null || echo "unknown")
+    echo "✓ mkdocs is installed: ${VERSION}"
+fi
+
+if [ "${ALL_CHECKS_PASSED}" = true ]; then
+    echo ""
+    echo "✅ MkDocs 2.0 overlay verification complete!"
+    echo ""
+    echo "💡 Tips:"
+    echo "  - Start dev server:    mkdocs serve"
+    echo "  - Build static site:   mkdocs build"
+    echo "  - New project:         mkdocs new ."
+else
+    echo ""
+    echo "✗ MkDocs 2.0 overlay verification failed"
+    exit 1
+fi

package/overlays/modern-cli-tools/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": "jq ripgrep fd-find bat",
+            "apk": "jq ripgrep fd bat"
+        }
+    }
 }