container-superposition 0.1.3 → 0.1.4

package/overlays/mailpit/verify.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Verification script for Mailpit overlay
+# Confirms Mailpit is running and accessible
+
+set -e
+
+echo "🔍 Verifying Mailpit overlay..."
+echo ""
+
+# Check if curl is available
+echo "1️⃣ Checking curl availability..."
+if ! command -v curl &> /dev/null; then
+    echo "   ❌ curl not found"
+    exit 1
+fi
+echo "   ✅ curl found"
+
+# Check Mailpit web UI
+echo ""
+echo "2️⃣ Checking Mailpit service..."
+MAILPIT_HOST="${MAILPIT_HOST:-mailpit}"
+MAILPIT_UI_PORT="${MAILPIT_UI_PORT:-8025}"
+MAILPIT_READY=false
+
+for i in {1..20}; do
+    if curl -sf "http://${MAILPIT_HOST}:${MAILPIT_UI_PORT}/api/v1/info" &> /dev/null; then
+        echo "   ✅ Mailpit service is ready"
+        MAILPIT_READY=true
+        break
+    fi
+    sleep 2
+done
+
+if [ "$MAILPIT_READY" = false ]; then
+    echo "   ❌ Mailpit service not ready after 40 seconds"
+    exit 1
+fi
+
+# Check Mailpit API
+echo ""
+echo "3️⃣ Checking Mailpit API..."
+if curl -sf "http://${MAILPIT_HOST}:${MAILPIT_UI_PORT}/api/v1/messages" &> /dev/null; then
+    echo "   ✅ Mailpit API is accessible"
+else
+    echo "   ❌ Mailpit API not accessible"
+    exit 1
+fi
+
+echo ""
+echo "✅ Mailpit overlay verification complete"
+echo "   Web UI: http://localhost:${MAILPIT_UI_PORT}"
+echo "   SMTP server: mailpit:1025 (from inside container)"

package/overlays/ngrok/overlay.yml

@@ -5,7 +5,8 @@ category: dev
 supports: []
 requires: []
 suggests: []
-conflicts: []
+conflicts:
+    - cloudflared
 tags:
     - dev
     - tunneling

package/overlays/python/README.md

@@ -5,67 +5,84 @@ Adds Python 3.12 with development tools, linting, and formatting.
 ## Features
 
 - **Python 3.12** with pip, setuptools, and wheel
+- **Virtual environment** (`.venv`) created automatically in the workspace root
 - **VS Code Extensions:**
     - Python (ms-python.python)
     - Pylance (ms-python.vscode-pylance)
     - Black Formatter (ms-python.black-formatter)
     - Ruff (charliermarsh.ruff)
-- **Automatic dependency installation** from:
-    - `requirements.txt`
-    - `requirements-dev.txt`
+- **Automatic dependency installation** into `.venv` from:
+    - `requirements.txt` (project production dependencies)
+    - `requirements-dev.txt` (project development dependencies)
     - `pyproject.toml` (editable install)
     - `setup.py` (legacy support)
 - **Pre-configured settings:**
+    - VS Code interpreter pointed at `.venv/bin/python`
     - Black as default formatter
     - Format on save enabled
     - Auto-organize imports
-    - PYTHONPATH set to workspace root
+    - `PYTHONPATH`, `VIRTUAL_ENV`, and `PATH` set for the venv
+- **`.gitignore`** — `.venv/`, `__pycache__/`, `*.pyc`, `.pytest_cache/`, and build artefacts added to the project root `.gitignore` automatically
 
-## Virtual Environment Philosophy
+## Virtual Environment
 
-This overlay uses **user-level pip installations** (`pip install --user`) instead of virtual environments inside the container for these reasons:
+This overlay automatically creates a `.venv` virtual environment in the workspace root on container creation and installs all dependencies into it.
 
-### Why Not venv in Container?
+### Why venv?
 
-1. **Container IS the environment** - The devcontainer already provides isolation
-2. **Simpler workflow** - No need to activate/deactivate venv
-3. **Better VS Code integration** - Python extension finds packages automatically
-4. **Fewer moving parts** - Less to go wrong
+1. **Clean isolation** — Dependencies are scoped to the project, not the system Python
+2. **Production parity** — Matches how the app runs in CI/CD and production
+3. **Tool compatibility** — Works seamlessly with pytest, mypy, ruff, and other dev tools
+4. **VS Code integration** — The Python extension is pre-configured to use `.venv/bin/python`
 
-### When to Use venv
+### How It Works
 
-Use a virtual environment if you need:
+On container creation, the setup script:
 
-- Multiple Python versions in the same container
-- Strict dependency isolation for testing
-- Exact production parity (though containers already provide this)
+1. Creates `.venv` at `${workspaceFolder}/.venv` using `python -m venv`
+2. Upgrades `pip`, `setuptools`, and `wheel` inside the venv
+3. Installs overlay default packages from `.devcontainer/requirements-overlay-python.txt`
+4. Installs project dependencies from `requirements.txt` (if present)
+5. Installs dev dependencies from `requirements-dev.txt` (if present)
+6. Installs project in editable mode if `pyproject.toml` or `setup.py` is present
 
-To create a venv manually:
+### Activating the Virtual Environment
+
+The `.venv/bin` directory is prepended to `PATH` automatically in the devcontainer, so tools like `python`, `pip`, `pytest`, and `ruff` resolve to the venv by default. You can also activate explicitly:
 
 ```bash
-python -m venv .venv
 source .venv/bin/activate
-pip install -r requirements.txt
 ```
 
-Then update VS Code settings:
+### Gitignore
 
-```json
-{
-    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
-}
+When the Python overlay is selected, the composer automatically adds Python-specific entries to the **project root** `.gitignore` (creating the file if it doesn’t exist, and never duplicating existing entries):
+
+```gitignore
+# python (container-superposition)
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.egg-info/
+dist/
+build/
 ```
 
+This happens at generation time — no container startup required.
+
 ## Automatic Setup
 
 The overlay automatically runs on container creation:
 
-1. ✅ Installs overlay packages from `.devcontainer/requirements-overlay.txt`
-2. ✅ Checks for `requirements.txt` → installs with pip
-3. ✅ Checks for `requirements-dev.txt` → installs dev dependencies
-4. ✅ Checks for `pyproject.toml` → installs project in editable mode
-5. ✅ Checks for `setup.py` → installs legacy projects
-6. ✅ Upgrades pip, setuptools, and wheel to latest
+1. ✅ Creates `.venv` virtual environment in the workspace root
+2. ✅ Upgrades pip, setuptools, and wheel inside the venv
+3. ✅ Installs overlay packages from `.devcontainer/requirements-overlay-python.txt`
+4. ✅ Checks for `requirements.txt` → installs into venv
+5. ✅ Checks for `requirements-dev.txt` → installs dev dependencies into venv
+6. ✅ Checks for `pyproject.toml` → installs project in editable mode
+7. ✅ Checks for `setup.py` → installs legacy projects in editable mode
 
 ## Customizing Overlay Packages
 
@@ -176,7 +193,7 @@ mytool = "mytool.cli:main"
 1. **Pin versions** in requirements.txt for reproducibility
 2. **Separate dev dependencies** in requirements-dev.txt
 3. **Use pyproject.toml** for modern Python projects
-4. **Add `.gitignore`** for `__pycache__`, `.pytest_cache`, etc.
+4. **Add `.gitignore`** — handled automatically by the overlay
 
 ## Troubleshooting
 
@@ -200,17 +217,16 @@ Update `devcontainer.patch.json`:
 }
 ```
 
-### Want to use venv anyway?
+### Customizing the Interpreter Path
 
-Add to your project's `.devcontainer/devcontainer.json`:
+The overlay pre-configures VS Code to use `${workspaceFolder}/.venv/bin/python`. If your venv is elsewhere, update `python.defaultInterpreterPath` in your workspace settings or `.devcontainer/custom/devcontainer.patch.json`:
 
 ```json
 {
-    "postCreateCommand": "python -m venv .venv && .venv/bin/pip install -r requirements.txt",
     "customizations": {
         "vscode": {
             "settings": {
-                "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
+                "python.defaultInterpreterPath": "${workspaceFolder}/my-custom-venv/bin/python"
             }
         }
     }

package/overlays/python/devcontainer.patch.json

@@ -26,16 +26,19 @@
                         "source.organizeImports": "explicit"
                     }
                 },
-                "python.defaultInterpreterPath": "/usr/local/bin/python",
+                "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+                "python.terminal.activateEnvironment": true,
                 "files.exclude": {
                     "**/__pycache__": true,
-                    "**/.pytest_cache": true
+                    "**/.pytest_cache": true,
+                    "**/.venv": true
                 }
             }
         }
     },
     "remoteEnv": {
-        "PATH": "${containerEnv:HOME}/.local/bin:${containerEnv:PATH}",
-        "PYTHONPATH": "${containerWorkspaceFolder}"
+        "PATH": "${containerWorkspaceFolder}/.venv/bin:${containerEnv:HOME}/.local/bin:${containerEnv:PATH}",
+        "PYTHONPATH": "${containerWorkspaceFolder}",
+        "VIRTUAL_ENV": "${containerWorkspaceFolder}/.venv"
     }
 }

package/overlays/python/setup.sh

@@ -1,47 +1,74 @@
 #!/bin/bash
-# Python setup script - Install Python packages
+# Python setup script - Create virtual environment and install dependencies
 
 set -e
 
 # Extract overlay name from script filename (setup-<overlay>.sh -> <overlay>)
 OVERLAY_NAME=$(basename "$0" | sed 's/setup-//;s/\.sh$//')
 
-echo "🐍 Setting up Python environment..."
+echo "🐍 Setting up Python virtual environment..."
+
+# Determine workspace root (script is run from workspace root via postCreateCommand)
+WORKSPACE_ROOT="${PWD}"
+VENV_DIR="${WORKSPACE_ROOT}/.venv"
+
+# Create virtual environment if it doesn't exist
+if [ ! -d "${VENV_DIR}" ]; then
+    echo "📦 Creating virtual environment at .venv..."
+    if ! command -v python3 >/dev/null 2>&1; then
+        echo "❌ python3 is not available on PATH. Please ensure python3 is installed."
+        exit 1
+    fi
+    python3 -m venv "${VENV_DIR}"
+    echo "✓ Virtual environment created"
+else
+    echo "✓ Virtual environment already exists at .venv"
+fi
+
+# Activate virtual environment
+# shellcheck source=/dev/null
+source "${VENV_DIR}/bin/activate"
+
+# Upgrade pip, setuptools, and wheel inside the venv
+echo "⬆️  Upgrading pip, setuptools, and wheel..."
+pip install --upgrade pip setuptools wheel
+echo "✓ pip, setuptools, and wheel upgraded"
 
 # Install overlay-specific packages (if requirements-overlay.txt exists)
 if [ -f ".devcontainer/requirements-overlay-${OVERLAY_NAME}.txt" ]; then
     echo "📦 Installing overlay packages from requirements-overlay-${OVERLAY_NAME}.txt..."
-    pip install --user -r .devcontainer/requirements-overlay-${OVERLAY_NAME}.txt
+    pip install -r ".devcontainer/requirements-overlay-${OVERLAY_NAME}.txt"
     echo "✓ Overlay packages installed"
 fi
 
-# Check if requirements.txt exists (project dependencies)
+# Install from root requirements.txt (project production dependencies)
 if [ -f "requirements.txt" ]; then
-    echo "📦 Found requirements.txt, installing dependencies..."
-    pip install --user -r requirements.txt
+    echo "📦 Installing dependencies from requirements.txt..."
+    pip install -r requirements.txt
     echo "✓ Dependencies installed from requirements.txt"
-elif [ -f "requirements-dev.txt" ]; then
-    echo "📦 Found requirements-dev.txt, installing dev dependencies..."
-    pip install --user -r requirements-dev.txt
+fi
+
+# Install from requirements-dev.txt (project development dependencies)
+if [ -f "requirements-dev.txt" ]; then
+    echo "📦 Installing dev dependencies from requirements-dev.txt..."
+    pip install -r requirements-dev.txt
     echo "✓ Dev dependencies installed from requirements-dev.txt"
 fi
 
-# Check if pyproject.toml exists (modern Python projects)
+# Install project in editable mode if pyproject.toml exists (modern Python projects)
 if [ -f "pyproject.toml" ]; then
-    echo "📦 Found pyproject.toml, installing project..."
-    pip install --user -e .
+    echo "📦 Found pyproject.toml, installing project in editable mode..."
+    pip install -e .
     echo "✓ Project installed in editable mode"
-fi
-
-# Check if setup.py exists (legacy Python projects)
-if [ -f "setup.py" ] && [ ! -f "pyproject.toml" ]; then
-    echo "📦 Found setup.py, installing project..."
-    pip install --user -e .
+elif [ -f "setup.py" ]; then
+    # Fallback for legacy Python projects
+    echo "📦 Found setup.py, installing project in editable mode..."
+    pip install -e .
     echo "✓ Project installed in editable mode"
 fi
 
-# Upgrade pip, setuptools, and wheel
-echo "⬆️  Upgrading pip, setuptools, and wheel..."
-pip install --user --upgrade pip setuptools wheel
-
-echo "✓ Python setup complete"
+echo ""
+echo "✓ Python virtual environment setup complete"
+echo "  Virtual environment: ${VENV_DIR}"
+echo "  Python interpreter: ${VENV_DIR}/bin/python"
+echo "  Activate manually:  source .venv/bin/activate"

package/overlays/python/verify.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Verification script for Python overlay
-# Confirms Python and pip are installed
+# Confirms Python, pip, and virtual environment are installed and functional
 
 set -e
 
@@ -28,5 +28,33 @@ else
     exit 1
 fi
 
+# Check venv module is available
+echo ""
+echo "3️⃣ Checking venv module..."
+if python3 -m venv --help &> /dev/null; then
+    echo "   ✅ venv module available"
+else
+    echo "   ❌ venv module not available"
+    exit 1
+fi
+
+# Check virtual environment was created (only if we are inside a devcontainer)
+echo ""
+echo "4️⃣ Checking virtual environment..."
+VENV_DIR="${PWD}/.venv"
+if [ -d "${VENV_DIR}" ]; then
+    if [ -f "${VENV_DIR}/bin/python" ]; then
+        VENV_PYTHON_VERSION=$("${VENV_DIR}/bin/python" --version 2>&1)
+        echo "   Virtual environment: ${VENV_DIR}"
+        echo "   Python version: ${VENV_PYTHON_VERSION}"
+        echo "   ✅ Virtual environment is functional"
+    else
+        echo "   ⚠️  Virtual environment directory exists but python not found"
+        echo "   ℹ️  Run setup script to create it: bash .devcontainer/scripts/setup-python.sh"
+    fi
+else
+    echo "   ℹ️  No .venv found — will be created on container start by setup-python.sh"
+fi
+
 echo ""
 echo "✅ Python overlay verification complete"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "container-superposition",
-    "version": "0.1.3",
+    "version": "0.1.4",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",