container-superposition 0.1.6 → 0.1.8

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"
+        }
+    }
 }

package/overlays/modern-cli-tools/setup.sh

@@ -1,94 +1,44 @@
 #!/bin/bash
 # Modern CLI tools setup script
+# jq, ripgrep, fd, bat are installed via cross-distro-packages devcontainer feature.
+# This script installs yq (not in standard repos), creates Debian symlinks, and configures tools.
 
 set -e
 
 echo "🚀 Setting up modern CLI tools..."
 
-# Update package list
-sudo apt-get update -qq
-
-# Install jq (JSON processor)
-echo "📦 Installing jq..."
-sudo apt-get install -y jq
-if command -v jq &> /dev/null; then
-    echo "✓ jq installed: $(jq --version)"
-else
-    echo "✗ jq installation failed"
-    exit 1
-fi
-
-# Install yq (YAML processor)
+# Install yq (YAML processor — not in standard distro repos)
 echo "📦 Installing yq..."
-YQ_VERSION="4.52.2"
+YQ_VERSION="${YQ_VERSION:-4.52.2}"
 ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64)  YQ_ARCH="amd64" ;;
+    aarch64|arm64) YQ_ARCH="arm64" ;;
+    *) echo "⚠️  Unsupported architecture: $ARCH, defaulting to amd64"; YQ_ARCH="amd64" ;;
+esac
 
-# SHA256 checksums for yq v4.52.2
-if [ "$ARCH" = "x86_64" ]; then
-    YQ_ARCH="amd64"
-    YQ_CHECKSUM="a74bd266990339e0c48a2103534aef692abf99f19390d12c2b0ce6830385c459"
-elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
-    YQ_ARCH="arm64"
-    YQ_CHECKSUM="c82856ac30da522f50dcdd4f53065487b5a2927e9b87ff637956900986f1f7c2"
-else
-    echo "⚠️  Unsupported architecture: $ARCH, defaulting to amd64"
-    YQ_ARCH="amd64"
-    YQ_CHECKSUM="a74bd266990339e0c48a2103534aef692abf99f19390d12c2b0ce6830385c459"
-fi
-
-curl -L "https://github.com/mikefarah/yq/releases/download/v${YQ_VERSION}/yq_linux_${YQ_ARCH}" \
+curl -fsSL "https://github.com/mikefarah/yq/releases/download/v${YQ_VERSION}/yq_linux_${YQ_ARCH}" \
     -o /tmp/yq
+sudo install -m 0755 /tmp/yq /usr/local/bin/yq
+rm /tmp/yq
 
-# Verify checksum
-echo "🔐 Verifying yq checksum..."
-echo "${YQ_CHECKSUM}  /tmp/yq" | sha256sum -c - || {
-    echo "✗ yq checksum verification failed"
-    rm /tmp/yq
-    exit 1
-}
-
-sudo mv /tmp/yq /usr/local/bin/yq
-sudo chmod +x /usr/local/bin/yq
-
-if command -v yq &> /dev/null; then
+if command -v yq &>/dev/null; then
     echo "✓ yq installed: $(yq --version)"
 else
     echo "✗ yq installation failed"
     exit 1
 fi
 
-# Install ripgrep (fast grep alternative)
-echo "📦 Installing ripgrep..."
-sudo apt-get install -y ripgrep
-if command -v rg &> /dev/null; then
-    echo "✓ ripgrep installed: $(rg --version | head -n 1)"
-else
-    echo "✗ ripgrep installation failed"
-    exit 1
+# Create fd symlink — Debian installs the binary as 'fdfind'
+if command -v fdfind &>/dev/null && ! command -v fd &>/dev/null; then
+    sudo ln -sf "$(which fdfind)" /usr/local/bin/fd
+    echo "✓ fd symlink created (fdfind → fd)"
 fi
 
-# Install fd (fast find alternative)
-echo "📦 Installing fd..."
-sudo apt-get install -y fd-find
-# Create symlink for 'fd' command (package installs as 'fdfind' on Debian)
-sudo ln -sf $(which fdfind) /usr/local/bin/fd
-if command -v fd &> /dev/null; then
-    echo "✓ fd installed: $(fd --version)"
-else
-    echo "✗ fd installation failed"
-    exit 1
-fi
-
-# Install bat (better cat with syntax highlighting)
-echo "📦 Installing bat..."
-sudo apt-get install -y bat
-# Create symlink for 'bat' command (package installs as 'batcat' on Debian)
-sudo ln -sf $(which batcat) /usr/local/bin/bat
-if command -v bat &> /dev/null; then
-    echo "✓ bat installed: $(bat --version)"
-else
-    echo "✗ bat installation failed"
-    exit 1
+# Create bat symlink — Debian installs the binary as 'batcat'
+if command -v batcat &>/dev/null && ! command -v bat &>/dev/null; then
+    sudo ln -sf "$(which batcat)" /usr/local/bin/bat
+    echo "✓ bat symlink created (batcat → bat)"
 fi
 
 # Configure bat

package/overlays/mongodb/devcontainer.patch.json

@@ -1,11 +1,5 @@
 {
     "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
-    "features": {
-        "./features/cross-distro-packages": {
-            "apt": "mongodb-mongosh",
-            "apk": "mongodb-tools"
-        }
-    },
     "customizations": {
         "vscode": {
             "extensions": ["mongodb.mongodb-vscode"]

package/overlays/mongodb/setup.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# MongoDB setup script - Install mongosh client
+
+set -e
+
+echo "📦 Installing mongosh client..."
+
+# 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 — `mongodb-tools` does not include mongosh on Alpine.
+    # Install mongosh from the MongoDB community package (available on Alpine 3.17+).
+    apk add --no-cache mongodb-mongosh 2>/dev/null || {
+        echo "⚠️  mongosh package not found in Alpine repos; falling back to npm install"
+        apk add --no-cache nodejs npm
+        npm install -g mongosh
+    }
+elif command -v apt-get >/dev/null 2>&1; then
+    # Debian/Ubuntu — install prerequisites first, then add the MongoDB repo.
+    # MongoDB doesn't publish a trixie/sid repo yet; fall back to bookworm.
+    CODENAME=$(. /etc/os-release && echo "${VERSION_CODENAME:-bookworm}")
+    case "$CODENAME" in
+        trixie | sid | testing) CODENAME="bookworm" ;;
+    esac
+
+    # Single lock acquisition: install prereqs, add repo, update, install mongosh.
+    # curl and gnupg must be present before add_apt_repo runs them.
+    acquire_apt_lock
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get update -qq
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get install -y -qq --no-install-recommends curl gnupg ca-certificates
+    release_apt_lock
+
+    add_apt_repo \
+        "https://www.mongodb.org/static/pgp/server-8.0.asc" \
+        "/usr/share/keyrings/mongodb-server.gpg" \
+        "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server.gpg ] https://repo.mongodb.org/apt/debian ${CODENAME}/mongodb-org/8.0 main" \
+        "/etc/apt/sources.list.d/mongodb-org.list"
+
+    acquire_apt_lock
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get update -qq
+    sudo DEBIAN_FRONTEND=noninteractive TERM=dumb apt-get install -y -qq --no-install-recommends mongodb-mongosh
+    sudo apt-get clean
+    sudo rm -rf /var/lib/apt/lists/*
+    release_apt_lock
+else
+    echo "⚠️  Unsupported package manager, skipping mongosh installation"
+    exit 0
+fi
+
+if command -v mongosh >/dev/null 2>&1; then
+    echo "✓ mongosh installed: $(mongosh --version)"
+else
+    echo "✗ mongosh installation failed"
+    exit 1
+fi
+
+echo "✓ mongodb setup complete"

package/overlays/mysql/verify.sh

@@ -21,8 +21,9 @@ fi
 echo ""
 echo "2️⃣ Checking MySQL service..."
 MYSQL_READY=false
-for i in {1..15}; do
-    if mysql -h mysql -P 3306 -u root -prootpassword -e "SELECT 1" &> /dev/null; then
+for i in {1..90}; do
+    # MYSQL_PWD avoids interactive prompt; </dev/null prevents TTY queries.
+    if MYSQL_PWD=rootpassword mysql -h mysql -P 3306 -u root -e "SELECT 1" </dev/null &>/dev/null; then
         echo "   ✅ MySQL service is ready"
         MYSQL_READY=true
         break
@@ -31,7 +32,7 @@ for i in {1..15}; do
 done
 
 if [ "$MYSQL_READY" = false ]; then
-    echo "   ❌ MySQL service not ready after 15 seconds"
+    echo "   ❌ MySQL service not ready after 90 seconds"
     exit 1
 fi
 

package/overlays/nats/.env.example

@@ -1,5 +1,5 @@
 # NATS Configuration
-NATS_VERSION=latest
+NATS_VERSION=2
 NATS_CLIENT_PORT=4222
 NATS_HTTP_PORT=8222
 NATS_CLUSTER_PORT=6222

package/overlays/nats/README.md

@@ -39,7 +39,7 @@ cp .env.example .env
 
 ```bash
 # NATS Configuration
-NATS_VERSION=latest
+NATS_VERSION=2
 NATS_CLIENT_PORT=4222
 NATS_HTTP_PORT=8222
 NATS_CLUSTER_PORT=6222

package/overlays/nats/docker-compose.yml

@@ -2,7 +2,7 @@ version: '3.8'
 
 services:
     nats:
-        image: nats:${NATS_VERSION:-latest}-alpine
+        image: nats:${NATS_VERSION:-2}-alpine
         restart: unless-stopped
         command:
             - '--jetstream'

package/overlays/ngrok/setup.sh

@@ -8,16 +8,19 @@ echo "🌐 Setting up ngrok..."
 # Install ngrok using official apt repository (provides signed packages)
 echo "📦 Installing ngrok from official repository..."
 
-# Add ngrok's GPG key and repository
-curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
-    | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
+# Source shared setup utilities
+# shellcheck source=setup-utils.sh
+source "$(dirname "${BASH_SOURCE[0]}")/setup-utils.sh"
 
+# Add ngrok GPG key and repository
+# Note: ngrok uses .asc (armored) format, piped directly to trusted.gpg.d (no --dearmor needed)
+curl -fsSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
+    | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
 echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
-    | sudo tee /etc/apt/sources.list.d/ngrok.list
+    | sudo tee /etc/apt/sources.list.d/ngrok.list >/dev/null
 
 # Update and install
-sudo apt-get update -qq
-sudo apt-get install -y ngrok
+apt_install ngrok
 
 # Verify installation
 if command -v ngrok &> /dev/null; then

package/overlays/nodejs/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
+
 # Extract overlay name from script filename (setup-<overlay>.sh -> <overlay>)
 OVERLAY_NAME=$(basename "$0" | sed 's/setup-//;s/\.sh$//')
 

package/overlays/ollama/.env.example

@@ -0,0 +1,14 @@
+# Ollama Configuration
+
+# Path to the Ollama data directory on the host machine.
+# Defaults to ~/.ollama — models downloaded there are available without re-pull.
+# Override to use a different directory, e.g. an external drive:
+# OLLAMA_MODELS_PATH=/Volumes/BigDrive/ollama
+# Windows users: set this explicitly, e.g. OLLAMA_MODELS_PATH=C:/Users/you/.ollama
+OLLAMA_MODELS_PATH=~/.ollama
+
+# Ollama image version (defaults to latest)
+OLLAMA_VERSION=latest
+
+# Host port for the Ollama API (defaults to 11434)
+OLLAMA_PORT=11434