container-superposition 0.1.1 → 0.1.4

package/overlays/nats/overlay.yml

@@ -14,5 +14,15 @@ tags:
     - nats
     - jetstream
 ports:
-    - 4222
-    - 8222
+    - port: 4222
+      service: nats
+      protocol: tcp
+      description: NATS client connection
+      onAutoForward: notify
+      connectionStringTemplate: 'nats://{host}:{port}'
+    - port: 8222
+      service: nats
+      protocol: http
+      description: NATS monitoring/stats endpoint
+      path: /
+      onAutoForward: ignore

package/overlays/ngrok/overlay.yml

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

package/overlays/openapi-tools/README.md

@@ -0,0 +1,243 @@
+# OpenAPI Tools Overlay
+
+OpenAPI/Swagger tooling for API development, documentation, and validation.
+
+## Features
+
+- **swagger-cli** - OpenAPI/Swagger validation
+- **spectral** - OpenAPI linting with customizable rules
+- **redocly** - Documentation generation and API bundling
+- **npm-based** - Easy to install and update
+
+## How It Works
+
+This overlay installs OpenAPI development tools as global npm packages. These tools help you create, validate, lint, and document APIs using the OpenAPI Specification (formerly Swagger).
+
+**Suggested overlays:**
+
+- `nodejs` - Node.js runtime for running OpenAPI tools
+
+## Installation
+
+OpenAPI tools are installed automatically during devcontainer creation via `setup.sh`:
+
+- `@apidevtools/swagger-cli` - OpenAPI validation
+- `@stoplight/spectral-cli` - OpenAPI linting
+- `@redocly/cli` - Documentation and bundling
+
+## Common Commands
+
+### Validation
+
+```bash
+# Validate OpenAPI specification
+swagger-cli validate openapi.yaml
+
+# Validate with detailed output
+swagger-cli validate openapi.yaml --debug
+
+# Bundle multiple files into one
+swagger-cli bundle openapi.yaml --outfile bundled.yaml --type yaml
+```
+
+### Linting
+
+```bash
+# Lint OpenAPI spec with spectral
+spectral lint openapi.yaml
+
+# Use custom ruleset
+spectral lint openapi.yaml --ruleset .spectral.yaml
+
+# Output as JSON
+spectral lint openapi.yaml --format json
+```
+
+### Redocly CLI
+
+```bash
+# Lint with redocly
+redocly lint openapi.yaml
+
+# Bundle specification
+redocly bundle openapi.yaml -o bundled.yaml
+
+# Build documentation
+redocly build-docs openapi.yaml
+
+# Preview documentation locally
+redocly preview-docs openapi.yaml
+```
+
+## Configuration
+
+### Spectral Ruleset
+
+Create `.spectral.yaml` for custom linting rules:
+
+```yaml
+extends: [[spectral:oas, all]]
+
+rules:
+    operation-description: error
+    operation-tags: error
+    operation-operationId: error
+
+    # Custom rules
+    my-custom-rule:
+        description: Ensure all operations have examples
+        given: $.paths[*][*].responses[*].content[*]
+        severity: warn
+        then:
+            field: example
+            function: truthy
+```
+
+### Redocly Configuration
+
+Create `redocly.yaml`:
+
+```yaml
+apis:
+    main:
+        root: ./openapi.yaml
+
+lint:
+    extends:
+        - recommended
+
+    rules:
+        operation-description: error
+        operation-tags: error
+```
+
+## Use Cases
+
+- **API design** - Design and validate OpenAPI specifications
+- **Documentation** - Generate beautiful API documentation
+- **Quality assurance** - Lint APIs for best practices
+- **Code generation** - Validate specs before code generation
+- **CI/CD** - Automated API validation in pipelines
+
+**Integrates well with:**
+
+- `nodejs` - Node.js runtime (suggested)
+- Any REST API framework (Express, FastAPI, ASP.NET Core, etc.)
+- `docker-in-docker` or `docker-sock` - For containerized API testing
+
+## OpenAPI Specification Basics
+
+### Minimal Example
+
+```yaml
+openapi: 3.0.0
+info:
+    title: My API
+    version: 1.0.0
+    description: API description
+
+servers:
+    - url: http://localhost:3000
+      description: Development server
+
+paths:
+    /users:
+        get:
+            summary: Get all users
+            operationId: getUsers
+            tags:
+                - users
+            responses:
+                '200':
+                    description: Successful response
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    $ref: '#/components/schemas/User'
+
+components:
+    schemas:
+        User:
+            type: object
+            required:
+                - id
+                - name
+            properties:
+                id:
+                    type: integer
+                name:
+                    type: string
+                email:
+                    type: string
+                    format: email
+```
+
+## Workflow
+
+### Development Workflow
+
+1. **Design**: Create OpenAPI spec (YAML or JSON)
+2. **Validate**: `swagger-cli validate openapi.yaml`
+3. **Lint**: `spectral lint openapi.yaml`
+4. **Preview**: `redocly preview-docs openapi.yaml`
+5. **Iterate**: Fix issues and repeat
+
+### CI/CD Integration
+
+```bash
+# In CI pipeline
+swagger-cli validate openapi.yaml
+spectral lint openapi.yaml --fail-severity warn
+redocly lint openapi.yaml
+```
+
+## Troubleshooting
+
+### swagger-cli Not Found
+
+Ensure Node.js and npm are installed:
+
+```bash
+node --version
+npm --version
+```
+
+Reinstall if needed:
+
+```bash
+npm install -g @apidevtools/swagger-cli
+```
+
+### Validation Errors
+
+Common OpenAPI errors:
+
+- **Missing required fields**: Add `info`, `paths`, `openapi` version
+- **Invalid references**: Ensure `$ref` paths are correct
+- **Schema errors**: Validate against OpenAPI 3.0/3.1 schema
+
+### Spectral Errors
+
+```bash
+# Run with debugging
+spectral lint openapi.yaml --verbose
+
+# Ignore specific rules
+spectral lint openapi.yaml --ignore-unknown-format
+```
+
+## References
+
+- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
+- [Swagger CLI Documentation](https://github.com/APIDevTools/swagger-cli)
+- [Spectral Documentation](https://stoplight.io/open-source/spectral)
+- [Redocly CLI Documentation](https://redocly.com/docs/cli/)
+- [OpenAPI Examples](https://github.com/OAI/OpenAPI-Specification/tree/main/examples)
+
+**Related Overlays:**
+
+- `nodejs` - Node.js runtime (suggested)
+- `python` - For OpenAPI code generation with frameworks
+- `dotnet` - For ASP.NET Core OpenAPI integration

package/overlays/openapi-tools/devcontainer.patch.json

@@ -0,0 +1,10 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "curl",
+            "apk": "curl"
+        }
+    },
+    "postCreateCommand": "bash .devcontainer/scripts/setup-openapi-tools.sh"
+}

package/overlays/openapi-tools/overlay.yml

@@ -0,0 +1,16 @@
+id: openapi-tools
+name: OpenAPI Tools
+description: OpenAPI/Swagger tooling for API development and documentation
+category: dev
+supports: []
+requires: []
+suggests:
+    - nodejs
+conflicts: []
+tags:
+    - dev
+    - openapi
+    - swagger
+    - api
+    - documentation
+ports: []

package/overlays/openapi-tools/setup.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Setup script for OpenAPI Tools
+
+set -e
+
+echo "🔧 Setting up OpenAPI Tools..."
+
+# Install OpenAPI tools globally via npm
+echo "📦 Installing OpenAPI tools..."
+
+# Install swagger-cli (OpenAPI validation)
+npm install -g @apidevtools/swagger-cli || echo "⚠️ swagger-cli already installed or failed"
+
+# Install spectral (OpenAPI linting)
+npm install -g @stoplight/spectral-cli || echo "⚠️ spectral already installed or failed"
+
+# Install redocly CLI (documentation and bundling)
+npm install -g @redocly/cli || echo "⚠️ redocly already installed or failed"
+
+# Verify installations
+echo ""
+echo "✅ OpenAPI tools setup complete"
+echo ""
+echo "Installed tools:"
+
+if command -v swagger-cli &> /dev/null; then
+    echo "  ✓ swagger-cli (OpenAPI validation)"
+    swagger-cli --version
+fi
+
+if command -v spectral &> /dev/null; then
+    echo "  ✓ spectral (OpenAPI linting)"
+    spectral --version
+fi
+
+if command -v redocly &> /dev/null; then
+    echo "  ✓ redocly (documentation and bundling)"
+    redocly --version
+fi
+
+echo ""
+echo "ℹ️  Usage examples:"
+echo "   swagger-cli validate openapi.yaml"
+echo "   spectral lint openapi.yaml"
+echo "   redocly lint openapi.yaml"

package/overlays/openapi-tools/verify.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Verification script for OpenAPI Tools overlay
+# Confirms OpenAPI tools are installed
+
+set -e
+
+echo "🔍 Verifying OpenAPI Tools overlay..."
+echo ""
+
+ALL_CHECKS_PASSED=true
+
+# Check swagger-cli
+echo "1️⃣ Checking swagger-cli..."
+if command -v swagger-cli &> /dev/null; then
+    swagger-cli --version
+    echo "   ✅ swagger-cli is installed"
+else
+    echo "   ❌ swagger-cli is not installed"
+    ALL_CHECKS_PASSED=false
+fi
+
+# Check spectral
+echo ""
+echo "2️⃣ Checking spectral..."
+if command -v spectral &> /dev/null; then
+    spectral --version
+    echo "   ✅ spectral is installed"
+else
+    echo "   ❌ spectral is not installed"
+    ALL_CHECKS_PASSED=false
+fi
+
+# Check redocly
+echo ""
+echo "3️⃣ Checking redocly..."
+if command -v redocly &> /dev/null; then
+    redocly --version
+    echo "   ✅ redocly is installed"
+else
+    echo "   ❌ redocly is not installed"
+    ALL_CHECKS_PASSED=false
+fi
+
+echo ""
+if [ "$ALL_CHECKS_PASSED" = true ]; then
+    echo "✅ OpenAPI Tools overlay verification complete"
+    exit 0
+else
+    echo "⚠️ Some OpenAPI tools are missing"
+    exit 1
+fi

package/overlays/otel-collector/overlay.yml.example

@@ -0,0 +1,26 @@
+# Example: OpenTelemetry Collector with shared config
+# This demonstrates the imports feature
+
+id: otel-collector
+name: OpenTelemetry Collector
+description: Telemetry data collection and export
+category: observability
+supports:
+    - compose
+requires: []
+suggests:
+    - jaeger
+    - prometheus
+conflicts: []
+tags:
+    - observability
+    - telemetry
+    - opentelemetry
+ports:
+    - 4317
+    - 4318
+    - 8888
+    - 8889
+order: 2
+imports:
+    - .shared/otel/instrumentation.env

package/overlays/postgres/overlay.yml

@@ -12,4 +12,9 @@ tags:
     - sql
     - postgres
 ports:
-    - 5432
+    - port: 5432
+      service: postgres
+      protocol: tcp
+      description: PostgreSQL database connection
+      onAutoForward: notify
+      connectionStringTemplate: 'postgresql://{postgres_user}:{postgres_password}@{host}:{port}/{postgres_db}'

package/overlays/prometheus/overlay.yml

@@ -13,5 +13,10 @@ tags:
     - metrics
     - prometheus
 ports:
-    - 9090
+    - port: 9090
+      service: prometheus
+      protocol: http
+      description: Prometheus web UI and API
+      path: /
+      onAutoForward: openBrowser
 order: 1

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