container-superposition 0.1.1 → 0.1.4

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/overlays/rabbitmq/overlay.yml

@@ -14,5 +14,15 @@ tags:
     - rabbitmq
     - amqp
 ports:
-    - 5672
-    - 15672
+    - port: 5672
+      service: rabbitmq
+      protocol: tcp
+      description: RabbitMQ AMQP connection
+      onAutoForward: notify
+      connectionStringTemplate: 'amqp://{rabbitmq_user}:{rabbitmq_password}@{host}:{port}{rabbitmq_vhost}'
+    - port: 15672
+      service: rabbitmq
+      protocol: http
+      description: RabbitMQ management UI
+      path: /
+      onAutoForward: openBrowser

package/overlays/redis/overlay.yml

@@ -12,4 +12,9 @@ tags:
     - cache
     - redis
 ports:
-    - 6379
+    - port: 6379
+      service: redis
+      protocol: tcp
+      description: Redis server connection
+      onAutoForward: notify
+      connectionStringTemplate: 'redis://{host}:{port}'

package/overlays/tilt/README.md

@@ -0,0 +1,259 @@
+# Tilt Overlay
+
+Live update and orchestration for Kubernetes development with real-time feedback.
+
+## Features
+
+- **Tilt** - Smart rebuilds and live updates for Kubernetes
+- **Web UI** - Browser-based dashboard on port 10350
+- **Live Updates** - See code changes instantly in K8s
+- **Smart Builds** - Only rebuild what changed
+- **Resource Orchestration** - Manage complex K8s workflows
+- **Multi-service Support** - Handle microservices architectures
+
+## How It Works
+
+This overlay installs Tilt, a development tool that orchestrates your Kubernetes development workflow. Tilt watches your code, automatically rebuilds containers, and updates your Kubernetes cluster when files change.
+
+**Suggested overlays:**
+
+- `kind` - Local Kubernetes cluster
+- `kubectl-helm` - Kubernetes CLI and Helm
+
+**Conflicts:**
+
+- `skaffold` - Alternative K8s build orchestration tool
+
+## Installation
+
+Tilt is installed automatically during devcontainer creation via `setup.sh`:
+
+- Downloads and installs latest Tilt CLI
+- Installs to `/usr/local/bin/tilt`
+- Web UI accessible on port 10350
+
+## Common Commands
+
+### Starting Tilt
+
+```bash
+# Start Tilt with Tiltfile in current directory
+tilt up
+
+# Start Tilt in specific directory
+tilt up --file ./services/api/Tiltfile
+
+# Start without opening browser
+tilt up --hud=false
+
+# Run in CI mode (no interactive UI)
+tilt ci
+```
+
+### Managing Resources
+
+```bash
+# List resources
+tilt get uiresources
+
+# Trigger manual build
+tilt trigger <resource-name>
+
+# Disable a resource
+tilt disable <resource-name>
+
+# Enable a resource
+tilt enable <resource-name>
+```
+
+### Logs and Debugging
+
+```bash
+# View logs
+tilt logs <resource-name>
+
+# Get resource status
+tilt get uiresources <resource-name>
+
+# Dump snapshot for debugging
+tilt dump engine
+```
+
+## Tiltfile Configuration
+
+Create a `Tiltfile` in your project root:
+
+### Basic Example
+
+```python
+# Build Docker image
+docker_build('myapp', '.')
+
+# Deploy to Kubernetes
+k8s_yaml('k8s/deployment.yaml')
+
+# Forward port
+k8s_resource('myapp', port_forwards=8000)
+```
+
+### Live Update Example
+
+```python
+# Build with live update (no rebuild for code changes)
+docker_build('myapp', '.',
+  live_update=[
+    sync('./src', '/app/src'),
+    run('npm install', trigger=['package.json']),
+    restart_container(),
+  ]
+)
+
+k8s_yaml('k8s/deployment.yaml')
+k8s_resource('myapp', port_forwards=8000)
+```
+
+### Multi-Service Example
+
+```python
+# API service
+docker_build('api', './services/api')
+k8s_yaml('./services/api/k8s.yaml')
+k8s_resource('api', port_forwards=3000)
+
+# Frontend service
+docker_build('frontend', './services/frontend')
+k8s_yaml('./services/frontend/k8s.yaml')
+k8s_resource('frontend', port_forwards=8080)
+
+# Database (no rebuild needed)
+k8s_yaml('./infra/postgres.yaml')
+k8s_resource('postgres', port_forwards=5432)
+```
+
+### Custom Buttons
+
+```python
+# Add custom actions to UI
+local_resource(
+  'db-migrate',
+  'kubectl exec -it deploy/api -- npm run migrate',
+  trigger_mode=TRIGGER_MODE_MANUAL,
+  auto_init=False
+)
+```
+
+## Use Cases
+
+- **Microservices development** - Manage multiple services with dependencies
+- **Rapid iteration** - See changes instantly without manual rebuilds
+- **Team development** - Standardize local development workflow
+- **Complex K8s apps** - Orchestrate multi-tier applications
+- **Learning Kubernetes** - Simplified K8s development experience
+
+**Integrates well with:**
+
+- `kind` or `k3d` - Local Kubernetes clusters
+- `kubectl-helm` - Kubernetes CLI and Helm
+- `nodejs`, `python`, `dotnet` - Application development
+- `docker-in-docker` - Docker builds
+
+## Web UI
+
+Access Tilt's web dashboard:
+
+- **URL**: http://localhost:10350
+- **Features**:
+    - Real-time resource status
+    - Build logs and errors
+    - Resource dependencies graph
+    - Manual trigger buttons
+    - Performance metrics
+
+The UI auto-opens when you run `tilt up`.
+
+## Benefits vs Skaffold
+
+| Feature            | Tilt                     | Skaffold              |
+| ------------------ | ------------------------ | --------------------- |
+| **UI**             | ✅ Rich web UI           | ⚠️ CLI only           |
+| **Live Updates**   | ✅ Sophisticated         | ⚠️ Basic              |
+| **Configuration**  | ✅ Programmable (Python) | ⚠️ Declarative (YAML) |
+| **Flexibility**    | ✅ Very flexible         | ⚠️ More opinionated   |
+| **Learning Curve** | ⚠️ Steeper               | ✅ Gentler            |
+| **CI Integration** | ✅ Good                  | ✅ Excellent          |
+
+**When to use Tilt:**
+
+- Need rich UI and debugging tools
+- Want programmable configuration
+- Developing complex microservices
+- Value rapid feedback loops
+
+**When to use Skaffold:**
+
+- Prefer declarative configuration
+- Focus on CI/CD pipelines
+- Want simpler tool
+- Need Google Cloud integration
+
+## Troubleshooting
+
+### Tilt Can't Find Kubernetes
+
+Ensure you have a K8s cluster:
+
+```bash
+# Create kind cluster
+kind create cluster --name dev
+
+# Verify kubectl works
+kubectl cluster-info
+```
+
+### Build Failures
+
+Check build logs in Tilt UI or:
+
+```bash
+tilt logs <resource-name>
+```
+
+### Port Already in Use
+
+Change Tilt UI port:
+
+```bash
+# In Tiltfile
+config.define_string('ui-port', args=False, usage='Tilt UI port')
+cfg = config.parse()
+tilt_port = cfg.get('ui-port', '10350')
+```
+
+Or use port offset when generating devcontainer.
+
+### Live Update Not Working
+
+Ensure your Tiltfile has `live_update` configuration:
+
+```python
+docker_build('myapp', '.',
+  live_update=[
+    sync('./src', '/app/src'),
+    restart_container(),
+  ]
+)
+```
+
+## References
+
+- [Tilt Documentation](https://docs.tilt.dev/)
+- [Tilt Getting Started](https://docs.tilt.dev/tutorial.html)
+- [Tiltfile API Reference](https://docs.tilt.dev/api.html)
+- [Tilt Examples](https://github.com/tilt-dev/tilt-example-html)
+
+**Related Overlays:**
+
+- `kind` - Local Kubernetes cluster (suggested)
+- `kubectl-helm` - Kubernetes CLI and Helm (suggested)
+- `skaffold` - Alternative K8s build tool (conflicts)
+- `docker-in-docker` - Docker builds

package/overlays/tilt/devcontainer.patch.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "curl",
+            "apk": "curl"
+        }
+    },
+    "forwardPorts": [10350],
+    "portsAttributes": {
+        "10350": {
+            "label": "Tilt UI",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "postCreateCommand": "bash .devcontainer/scripts/setup-tilt.sh"
+}

package/overlays/tilt/overlay.yml

@@ -0,0 +1,19 @@
+id: tilt
+name: Tilt
+description: Live update and orchestration for Kubernetes development
+category: dev
+supports: []
+requires: []
+suggests:
+    - kind
+    - kubectl-helm
+conflicts:
+    - skaffold
+tags:
+    - dev
+    - kubernetes
+    - k8s
+    - development
+    - live-reload
+ports:
+    - 10350

package/overlays/tilt/setup.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Setup script for Tilt
+
+set -e
+
+echo "🔧 Setting up Tilt..."
+
+# Install Tilt
+echo "📦 Installing Tilt..."
+
+curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash
+
+# Verify installation
+if command -v tilt &> /dev/null; then
+    echo "✅ Tilt installed successfully"
+    tilt version
+else
+    echo "❌ Tilt installation failed"
+    exit 1
+fi
+
+echo "✅ Tilt setup complete"
+echo ""
+echo "ℹ️  To start Tilt, run:"
+echo "   tilt up"

package/overlays/tilt/verify.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Verification script for Tilt overlay
+# Confirms Tilt is installed
+
+set -e
+
+echo "🔍 Verifying Tilt overlay..."
+echo ""
+
+# Check Tilt is installed
+echo "1️⃣ Checking Tilt installation..."
+if command -v tilt &> /dev/null; then
+    tilt version
+    echo "   ✅ Tilt is installed"
+else
+    echo "   ❌ Tilt is not installed"
+    exit 1
+fi
+
+echo ""
+echo "✅ Tilt overlay verification complete"
+echo ""
+echo "ℹ️  To start Tilt, run:"
+echo "   tilt up"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "container-superposition",
-    "version": "0.1.1",
+    "version": "0.1.4",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",
@@ -14,7 +14,9 @@
         "test": "vitest run",
         "test:watch": "vitest",
         "test:smoke": "bash scripts/test.sh",
-        "docs:generate": "tsx docs/generate-docs.ts",
+        "docs:generate": "tsx docs/generate-docs.ts && prettier --write docs/overlays.md",
+        "lint": "tsc --noEmit && npm run format:check",
+        "lint:fix": "npm run format",
         "format": "prettier --write \"**/*.{ts,js,json,md,yaml,yml}\"",
         "format:check": "prettier --check \"**/*.{ts,js,json,md,yaml,yml}\"",
         "clean": "rm -rf dist",
@@ -53,15 +55,15 @@
     "dependencies": {
         "@inquirer/checkbox": "^5.0.4",
         "@inquirer/prompts": "^8.2.0",
-        "boxen": "^7.1.1",
+        "boxen": "^8.0.1",
         "chalk": "^5.6.2",
-        "commander": "^12.1.0",
+        "commander": "^14.0.3",
         "js-yaml": "^4.1.1",
-        "ora": "^8.2.0"
+        "ora": "^9.3.0"
     },
     "devDependencies": {
         "@types/js-yaml": "^4.0.9",
-        "@types/node": "^20.19.33",
+        "@types/node": "^25.2.3",
         "@vitest/ui": "^4.0.18",
         "prettier": "^3.4.2",
         "tsx": "^4.7.0",

package/tool/README.md

@@ -103,6 +103,7 @@ This makes the questionnaire more engaging and the output easier to scan.
 | `--cloud-tools <list>`   | Cloud tools: `aws-cli`, `azure-cli`, `gcloud`, `kubectl-helm`, `terraform`, `pulumi`                                                                                  | `--cloud-tools aws-cli,kubectl-helm`        |
 | `--dev-tools <list>`     | Development tools: `docker-in-docker`, `docker-sock`, `playwright`, `codex`, `git-helpers`, `pre-commit`, `commitlint`, `just`, `direnv`, `modern-cli-tools`, `ngrok` | `--dev-tools docker-in-docker,playwright`   |
 | `--port-offset <number>` | Add offset to all exposed ports (e.g., 100 makes Grafana 3100)                                                                                                        | `--port-offset 100`                         |
+| `--target <environment>` | Deployment target: local, codespaces, gitpod, devpod (validates compatibility)                                                                                        | `--target codespaces`                       |
 | `-o`, `--output <path>`  | Output directory (default: `./.devcontainer`)                                                                                                                         | `-o ./custom-path`                          |
 | `-h`, `--help`           | Show help                                                                                                                                                             | `--help`                                    |
 
@@ -121,21 +122,16 @@ After running the tool, you'll have:
 ```
 .devcontainer/
 ├── devcontainer.json                  # Main configuration (editable!)
-├── docker-compose.yml                 # Base compose file (if using compose template)
+├── docker-compose.yml                 # Combined compose file with selected services
 ├── .env.example                       # Environment variables from selected overlays
 ├── scripts/
 │   └── post_create.sh                 # Post-creation scripts
-├── docker-compose.postgres.yml        # (if postgres selected)
-├── docker-compose.redis.yml           # (if redis selected)
-├── docker-compose.otel-collector.yml  # (if otel-collector selected)
-├── docker-compose.jaeger.yml          # (if jaeger selected)
-├── docker-compose.prometheus.yml      # (if prometheus selected)
-├── docker-compose.grafana.yml         # (if grafana selected)
-├── docker-compose.loki.yml            # (if loki selected)
-├── otel-collector-config.yaml         # (if otel-collector selected)
-├── prometheus.yml                     # (if prometheus selected)
-├── grafana-datasources.yml            # (if grafana selected)
-└── loki-config.yaml                   # (if loki selected)
+├── otel-collector-config-otel-collector.yaml  # (if otel-collector selected)
+├── prometheus-prometheus.yml                  # (if prometheus selected)
+├── grafana-datasources-grafana.yml            # (if grafana selected)
+├── dashboard-provider-grafana.yml             # (if grafana selected)
+├── dashboards-grafana/                        # (if grafana selected)
+└── loki-config-loki.yaml                      # (if loki selected)
 ```
 
 All `.env.example` files from selected overlays are automatically merged into a single file with all relevant environment variables.
@@ -192,17 +188,17 @@ Each overlay is a composable package that can include:
 ```
 overlays/postgres/
 ├── devcontainer.patch.json    # Features, env vars, ports (merged into devcontainer.json)
-├── docker-compose.yml         # Service definition (copied as docker-compose.{overlay}.yml)
+├── docker-compose.yml         # Service definition (merged into output docker-compose.yml)
 ├── .env.example               # Environment variables (merged into combined .env.example)
-└── [additional files]         # Config files, scripts, directories (copied as-is)
+└── [additional files]         # Copied with overlay suffix to avoid filename conflicts
 ```
 
 The tool intelligently handles each file type:
 
 - **devcontainer.patch.json** - Deep-merged into devcontainer.json (arrays concatenated, objects merged)
-- **docker-compose.yml** - Copied as `docker-compose.{overlay}.yml` and referenced in devcontainer.json
+- **docker-compose.yml** - Merged with base compose into one output `docker-compose.yml`
 - **.env.example** - Content merged into combined `.env.example` in output
-- **Other files/directories** - Copied as-is to output (e.g., `otel-collector.yml`, `config/redis.conf`)
+- **Other files/directories** - Copied with an overlay suffix (e.g., `prometheus-prometheus.yml`, `dashboards-grafana/`)
 
 This allows overlays to provide complete, self-contained configurations including any necessary config files.