container-superposition 0.1.1

package/overlays/pre-commit/setup.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+# Pre-commit framework setup script
+
+set -e
+
+echo "🔍 Setting up pre-commit framework..."
+
+# Install pre-commit using pip
+pip install --user pre-commit
+
+# Add to PATH if not already there
+export PATH="$HOME/.local/bin:$PATH"
+
+# Verify installation
+if command -v pre-commit &> /dev/null; then
+    echo "✓ pre-commit installed: $(pre-commit --version)"
+else
+    echo "✗ pre-commit installation failed"
+    exit 1
+fi
+
+# Create sample .pre-commit-config.yaml if no config exists
+if [ ! -f .pre-commit-config.yaml ] && [ ! -f .pre-commit-config.yml ] && [ ! -f .pre-commit-config.json ]; then
+    cat > .pre-commit-config.yaml << 'EOF'
+# Pre-commit configuration
+# See https://pre-commit.com for more information
+# Install: pre-commit install
+# Run manually: pre-commit run --all-files
+
+repos:
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: [--safe]
+      - id: check-json
+      - id: check-toml
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: check-executables-have-shebangs
+      - id: check-shebang-scripts-are-executable
+
+  # Markdown checks
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.39.0
+    hooks:
+      - id: markdownlint
+        args: [--fix]
+
+# Language-specific hooks (uncomment as needed):
+
+# Python
+#  - repo: https://github.com/psf/black
+#    rev: 24.2.0
+#    hooks:
+#      - id: black
+#
+#  - repo: https://github.com/pycqa/isort
+#    rev: 5.13.2
+#    hooks:
+#      - id: isort
+#        args: [--profile, black]
+#
+#  - repo: https://github.com/pycqa/flake8
+#    rev: 7.0.0
+#    hooks:
+#      - id: flake8
+
+# JavaScript/TypeScript
+#  - repo: https://github.com/pre-commit/mirrors-eslint
+#    rev: v8.56.0
+#    hooks:
+#      - id: eslint
+#        files: \.[jt]sx?$
+#        types: [file]
+#        additional_dependencies:
+#          - eslint@8.56.0
+#          - typescript@5.3.3
+#
+#  - repo: https://github.com/pre-commit/mirrors-prettier
+#    rev: v3.1.0
+#    hooks:
+#      - id: prettier
+#        types_or: [javascript, jsx, ts, tsx, json, yaml, markdown]
+
+# Dockerfile
+#  - repo: https://github.com/hadolint/hadolint
+#    rev: v2.12.0
+#    hooks:
+#      - id: hadolint-docker
+
+# Shell scripts
+#  - repo: https://github.com/shellcheck-py/shellcheck-py
+#    rev: v0.9.0.6
+#    hooks:
+#      - id: shellcheck
+EOF
+    echo "✓ Sample .pre-commit-config.yaml created"
+fi
+
+# Install pre-commit hooks in git repository
+if [ -d .git ]; then
+    pre-commit install
+    echo "✓ Pre-commit hooks installed in repository"
+else
+    echo "⚠️  Not a git repository - skipping hook installation"
+    echo "   Run 'pre-commit install' manually after git init"
+fi
+
+# Run pre-commit to install hook environments
+pre-commit install-hooks 2>/dev/null || echo "⚠️  Will install hooks on first run"
+
+echo "✓ Pre-commit setup complete"
+echo ""
+echo "💡 Usage:"
+echo "  - Install hooks in repo: pre-commit install"
+echo "  - Run on all files: pre-commit run --all-files"
+echo "  - Run on changed files: pre-commit run"
+echo "  - Update hooks: pre-commit autoupdate"
+echo "  - Skip hooks on commit: git commit --no-verify"

package/overlays/presets/docs-site.yml

@@ -0,0 +1,118 @@
+# Documentation Site Preset
+# Development environment for documentation websites
+
+id: docs-site
+name: Documentation Site
+description: Documentation website development with MkDocs, quality checks, and deployment tools
+type: meta
+category: preset
+supports: [] # Works with both plain and compose
+tags: [preset, documentation, mkdocs, markdown]
+
+# Overlays to select
+selects:
+    # Always included
+    required:
+        - mkdocs
+        - pre-commit
+        - modern-cli-tools
+
+    # No user choices for this preset
+    userChoice: {}
+
+# Glue configuration
+glueConfig:
+    # Pre-configured environment variables
+    environment:
+        # MkDocs configuration
+        MKDOCS_PORT: '8000'
+        MKDOCS_STRICT: 'true'
+
+        # Documentation settings
+        DOCS_DIR: 'docs'
+        SITE_DIR: 'site'
+
+    # Suggested port mappings
+    portMappings:
+        mkdocs: 8000
+
+    # README snippet
+    readme: |
+        ## Documentation Site Stack
+
+        This devcontainer is configured for documentation development:
+
+        ### Tools
+
+        - **MkDocs**: Python-based static site generator (port 8000)
+        - **Pre-commit**: Git hooks for quality checks
+        - **Modern CLI Tools**: bat, fd, ripgrep, fzf for productivity
+
+        ### Quick Start
+
+        1. Initialize MkDocs (if not already done):
+           ```bash
+           mkdocs new .
+           ```
+
+        2. Start development server:
+           ```bash
+           mkdocs serve
+           ```
+
+        3. Access your docs at http://localhost:8000
+
+        ### Pre-commit Hooks
+
+        This preset includes pre-commit hooks for documentation quality:
+
+        - Markdown linting
+        - Trailing whitespace removal
+        - YAML validation
+        - Link checking (optional)
+
+        Install hooks:
+
+        ```bash
+        pre-commit install
+        ```
+
+        ### MkDocs Configuration
+
+        Edit `mkdocs.yml` to configure:
+
+        - Theme (Material for MkDocs recommended)
+        - Navigation structure
+        - Plugins (search, tags, etc.)
+        - Markdown extensions
+
+        Example `mkdocs.yml`:
+
+        ```yaml
+        site_name: My Documentation
+        theme:
+          name: material
+          palette:
+            primary: indigo
+        nav:
+          - Home: index.md
+          - Getting Started: getting-started.md
+        ```
+
+        ### GitHub Pages Deployment
+
+        Deploy to GitHub Pages:
+
+        ```bash
+        mkdocs gh-deploy
+        ```
+
+        This builds your site and pushes to the `gh-pages` branch.
+
+        ### Next Steps
+
+        - Choose a MkDocs theme (Material is popular)
+        - Add markdown files to `docs/` directory
+        - Configure navigation in `mkdocs.yml`
+        - Set up CI/CD for automatic deployments
+        - Add link checking to pre-commit hooks

package/overlays/presets/fullstack.yml

@@ -0,0 +1,181 @@
+# Full-Stack Application Preset
+# Complete development environment for full-stack applications
+
+id: fullstack
+name: Full-Stack Application
+description: Complete full-stack development with frontend, backend, databases, and observability
+type: meta
+category: preset
+supports: [compose] # Requires Docker Compose for services
+tags: [preset, fullstack, frontend, backend, monorepo]
+
+# Overlays to select
+selects:
+    # Always included
+    required:
+        - nodejs # Frontend (React/Vue/Angular)
+        - postgres
+        - redis
+        - minio # File uploads/storage
+        - otel-collector
+        - prometheus
+        - grafana
+        - loki
+
+    # User makes choices
+    userChoice:
+        backend:
+            id: backend
+            prompt: Select backend language/framework
+            options: [dotnet, python, go, java]
+            defaultOption: dotnet
+
+# Glue configuration
+glueConfig:
+    # Pre-configured environment variables
+    environment:
+        # Database
+        DATABASE_URL: 'postgresql://postgres:postgres@postgres:5432/myapp'
+        POSTGRES_HOST: 'postgres'
+        POSTGRES_PORT: '5432'
+        POSTGRES_DB: 'myapp'
+
+        # Redis
+        REDIS_URL: 'redis://redis:6379'
+        REDIS_HOST: 'redis'
+
+        # MinIO (S3-compatible storage)
+        MINIO_ENDPOINT: 'minio:9000'
+        MINIO_ACCESS_KEY: 'minioadmin'
+        MINIO_SECRET_KEY: 'minioadmin'
+        MINIO_BUCKET: 'uploads'
+        MINIO_USE_SSL: 'false'
+
+        # OpenTelemetry
+        OTEL_EXPORTER_OTLP_ENDPOINT: 'http://otel-collector:4317'
+        OTEL_SERVICE_NAME: 'fullstack-app'
+
+        # Application
+        FRONTEND_PORT: '3000'
+        BACKEND_PORT: '8000'
+        API_URL: 'http://localhost:8000'
+        GRAFANA_PORT: '3001'
+
+    # Suggested port mappings
+    portMappings:
+        frontend: 3000
+        backend: 8000
+        grafana: 3001
+        minio: 9000
+        minio-console: 9001
+
+    # README snippet
+    readme: |
+        ## Full-Stack Application Stack
+
+        This devcontainer provides a complete full-stack development environment:
+
+        ### Architecture
+
+        ```
+        Frontend (Node.js) ──→ Backend ──→ PostgreSQL
+             │                    │
+             └────────────────────┴──→ Redis (session/cache)
+                                  │
+                                  └──→ MinIO (file storage)
+        ```
+
+        ### Services
+
+        - **Node.js**: Frontend development (React/Vue/Angular) on port 3000
+        - **Backend**: Your chosen language/framework on port 8000
+        - **PostgreSQL**: Primary database (port 5432)
+        - **Redis**: Cache and session store (port 6379)
+        - **MinIO**: S3-compatible object storage (ports 9000, 9001)
+        - **OpenTelemetry Collector**: Telemetry aggregation
+        - **Prometheus**: Metrics (port 9090)
+        - **Grafana**: Dashboards (port 3001)
+        - **Loki**: Log aggregation (port 3100)
+
+        ### Connection Strings
+
+        ```bash
+        # PostgreSQL
+        DATABASE_URL="postgresql://postgres:postgres@postgres:5432/myapp"
+
+        # Redis
+        REDIS_URL="redis://redis:6379"
+
+        # MinIO (S3-compatible)
+        MINIO_ENDPOINT="minio:9000"
+        MINIO_ACCESS_KEY="minioadmin"
+        MINIO_SECRET_KEY="minioadmin"
+
+        # Backend API (from frontend)
+        API_URL="http://localhost:8000"
+        ```
+
+        ### Quick Start
+
+        #### Frontend Setup
+
+        ```bash
+        cd frontend/
+        npm install
+        npm run dev  # Runs on port 3000
+        ```
+
+        #### Backend Setup
+
+        Start your backend on port 8000 (varies by language).
+
+        #### MinIO Setup
+
+        1. Access MinIO Console at http://localhost:9001
+        2. Login with minioadmin/minioadmin
+        3. Create bucket named "uploads"
+        4. Configure your app to use MinIO endpoint
+
+        ### Monorepo Structure (Recommended)
+
+        ```
+        project/
+        ├── frontend/          # React/Vue/Angular app
+        ├── backend/           # API server
+        ├── shared/            # Shared types/models
+        ├── .devcontainer/     # This devcontainer
+        └── docker-compose.yml
+        ```
+
+        ### File Upload Example
+
+        Your backend can upload files to MinIO:
+
+        ```javascript
+        // Node.js example
+        const Minio = require('minio');
+        const minioClient = new Minio.Client({
+          endPoint: 'minio',
+          port: 9000,
+          useSSL: false,
+          accessKey: 'minioadmin',
+          secretKey: 'minioadmin'
+        });
+
+        await minioClient.putObject('uploads', 'file.jpg', stream);
+        ```
+
+        ### Observability
+
+        - **Metrics**: Grafana at http://localhost:3001
+        - **Traces**: Add OTEL SDK to frontend and backend
+        - **Logs**: Forwarded to Loki, viewable in Grafana
+
+        ### Next Steps
+
+        - Set up frontend build pipeline
+        - Implement API endpoints in backend
+        - Configure database migrations
+        - Add authentication/authorization
+        - Set up shared TypeScript types between frontend and backend
+        - Create custom Grafana dashboards

package/overlays/presets/microservice.yml

@@ -0,0 +1,118 @@
+# Microservice Stack Preset
+# Development environment for microservices architecture
+
+id: microservice
+name: Microservice Stack
+description: Microservices development with messaging, distributed tracing, and monitoring
+type: meta
+category: preset
+supports: [compose] # Requires Docker Compose for services
+tags: [preset, microservice, messaging, distributed, tracing]
+
+# Overlays to select
+selects:
+    # Always included
+    required:
+        - otel-collector
+        - jaeger
+        - prometheus
+        - grafana
+
+    # User makes choices
+    userChoice:
+        language:
+            id: language
+            prompt: Select service language/framework
+            options: [dotnet, nodejs, python, go, java]
+            defaultOption: nodejs
+
+        messaging:
+            id: messaging
+            prompt: Select message broker
+            options: [rabbitmq, redpanda, nats]
+            defaultOption: rabbitmq
+
+# Glue configuration - integration helpers
+glueConfig:
+    # Pre-configured environment variables
+    environment:
+        # OpenTelemetry configuration
+        OTEL_EXPORTER_OTLP_ENDPOINT: 'http://otel-collector:4317'
+        OTEL_SERVICE_NAME: 'microservice'
+        OTEL_METRICS_EXPORTER: 'otlp'
+        OTEL_TRACES_EXPORTER: 'otlp'
+        OTEL_LOGS_EXPORTER: 'otlp'
+
+        # Jaeger configuration
+        JAEGER_ENDPOINT: 'http://jaeger:14268/api/traces'
+
+        # Messaging URLs (will vary based on choice)
+        # RabbitMQ: amqp://rabbitmq:5672
+        # Redpanda: kafka://redpanda:9092
+        # NATS: nats://nats:4222
+
+    # Suggested port mappings
+    portMappings:
+        service: 8080
+        grafana: 3000
+        prometheus: 9090
+        jaeger: 16686
+
+    # README snippet
+    readme: |
+        ## Microservice Stack
+
+        This devcontainer is configured for microservices development:
+
+        ### Services
+
+        - **Message Broker**: Async communication between services
+        - **OpenTelemetry Collector**: Distributed tracing collection (ports 4317, 4318)
+        - **Jaeger**: Distributed tracing UI (port 16686)
+        - **Prometheus**: Metrics storage (port 9090)
+        - **Grafana**: Unified observability dashboard (port 3000)
+
+        ### Connection Strings
+
+        Depending on your message broker choice:
+
+        ```bash
+        # RabbitMQ
+        RABBITMQ_URL="amqp://rabbitmq:5672"
+
+        # Redpanda (Kafka-compatible)
+        KAFKA_BROKERS="redpanda:9092"
+
+        # NATS
+        NATS_URL="nats://nats:4222"
+        ```
+
+        OpenTelemetry:
+
+        ```bash
+        OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
+        JAEGER_ENDPOINT="http://jaeger:14268/api/traces"
+        ```
+
+        ### Quick Start
+
+        1. Develop your microservice on port 8080
+        2. Publish/subscribe to messages via your chosen broker
+        3. View distributed traces in Jaeger at http://localhost:16686
+        4. Monitor metrics in Grafana at http://localhost:3000
+
+        ### Distributed Tracing
+
+        This stack is pre-configured for distributed tracing:
+
+        - Add OpenTelemetry SDK to your service
+        - Traces automatically flow: Service → OTEL Collector → Jaeger
+        - View service dependencies and latencies in Jaeger UI
+
+        ### Next Steps
+
+        - Implement health check endpoints
+        - Add OpenTelemetry instrumentation
+        - Configure circuit breakers and retries
+        - Set up service discovery (if needed)
+        - Create service-specific Grafana dashboards

package/overlays/presets/web-api.yml

@@ -0,0 +1,109 @@
+# Web API Stack Preset
+# Complete environment for REST/GraphQL API development
+
+id: web-api
+name: Web API Stack
+description: Complete REST/GraphQL API development environment with database, cache, and observability
+type: meta
+category: preset
+supports: [compose] # Requires Docker Compose for services
+tags: [preset, api, web, backend, observability]
+
+# Overlays to select
+selects:
+    # Always included
+    required:
+        - postgres
+        - redis
+        - otel-collector
+        - prometheus
+        - grafana
+        - loki
+
+    # User makes choices
+    userChoice:
+        language:
+            id: language
+            prompt: Select API language/framework
+            options: [dotnet, nodejs, python, go, java]
+            defaultOption: nodejs
+
+# Glue configuration - integration helpers
+glueConfig:
+    # Pre-configured environment variables
+    environment:
+        # Database connection
+        DATABASE_URL: 'postgresql://postgres:postgres@postgres:5432/myapp'
+        POSTGRES_HOST: 'postgres'
+        POSTGRES_PORT: '5432'
+        POSTGRES_DB: 'myapp'
+        POSTGRES_USER: 'postgres'
+        POSTGRES_PASSWORD: 'postgres'
+
+        # Redis connection
+        REDIS_URL: 'redis://redis:6379'
+        REDIS_HOST: 'redis'
+        REDIS_PORT: '6379'
+
+        # OpenTelemetry configuration
+        OTEL_EXPORTER_OTLP_ENDPOINT: 'http://otel-collector:4317'
+        OTEL_SERVICE_NAME: 'api-service'
+        OTEL_METRICS_EXPORTER: 'otlp'
+        OTEL_TRACES_EXPORTER: 'otlp'
+        OTEL_LOGS_EXPORTER: 'otlp'
+
+    # Suggested port mappings
+    portMappings:
+        api: 8000
+        grafana: 3000
+        prometheus: 9090
+
+    # README snippet to add to generated devcontainer
+    readme: |
+        ## Web API Stack
+
+        This devcontainer is configured with a complete API development stack:
+
+        ### Services
+
+        - **PostgreSQL**: Primary database (port 5432)
+        - **Redis**: Cache and session store (port 6379)
+        - **OpenTelemetry Collector**: Telemetry aggregation (ports 4317, 4318)
+        - **Prometheus**: Metrics storage (port 9090)
+        - **Grafana**: Observability dashboard (port 3000)
+        - **Loki**: Log aggregation (port 3100)
+
+        ### Connection Strings
+
+        ```bash
+        # PostgreSQL
+        DATABASE_URL="postgresql://postgres:postgres@postgres:5432/myapp"
+
+        # Redis
+        REDIS_URL="redis://redis:6379"
+
+        # OpenTelemetry
+        OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
+        ```
+
+        ### Quick Start
+
+        1. Start your API on port 8000 (configured in this preset)
+        2. Access Grafana at http://localhost:3000 (admin/admin)
+        3. View metrics in Prometheus at http://localhost:9090
+        4. Check logs in Loki via Grafana
+
+        ### Health Checks
+
+        All services include health checks. Verify with:
+
+        ```bash
+        docker-compose ps
+        ```
+
+        ### Next Steps
+
+        - Configure your API to use the DATABASE_URL and REDIS_URL
+        - Add OpenTelemetry SDK to your application
+        - Create custom Grafana dashboards for your API metrics
+        - Set up log forwarding to Loki

package/overlays/prometheus/.env.example

@@ -0,0 +1,5 @@
+# Prometheus version
+PROMETHEUS_VERSION=latest
+
+# Prometheus port
+PROMETHEUS_PORT=9090