container-superposition 0.1.1 → 0.1.3

package/overlays/localstack/verify.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Verification script for LocalStack overlay
+# Confirms LocalStack is running and accessible
+
+set -e
+
+echo "🔍 Verifying LocalStack overlay..."
+echo ""
+
+# Check if LocalStack service is running
+echo "1️⃣ Checking LocalStack service..."
+if command -v curl &> /dev/null; then
+    # Wait up to 30 seconds for LocalStack to be ready
+    LOCALSTACK_READY=false
+    for i in {1..30}; do
+        if curl -s http://localstack:4566/_localstack/health &> /dev/null; then
+            echo "   ✅ LocalStack service is ready"
+            LOCALSTACK_READY=true
+            break
+        fi
+        sleep 1
+    done
+
+    if [ "$LOCALSTACK_READY" = false ]; then
+        echo "   ❌ LocalStack service not ready after 30 seconds"
+        exit 1
+    fi
+else
+    echo "   ⚠️  curl not found, skipping service check"
+fi
+
+# Check LocalStack health
+echo ""
+echo "2️⃣ Checking LocalStack health..."
+if command -v curl &> /dev/null; then
+    HEALTH=$(curl -s http://localstack:4566/_localstack/health)
+    if [ -n "$HEALTH" ]; then
+        echo "   ✅ LocalStack health endpoint responding"
+        echo "$HEALTH" | head -3
+    else
+        echo "   ❌ LocalStack health check failed"
+        exit 1
+    fi
+fi
+
+echo ""
+echo "✅ LocalStack overlay verification complete"

package/overlays/loki/overlay.yml

@@ -13,5 +13,10 @@ tags:
     - logs
     - loki
 ports:
-    - 3100
+    - port: 3100
+      service: loki
+      protocol: http
+      description: Loki HTTP API and query interface
+      path: /
+      onAutoForward: notify
 order: 1

package/overlays/modern-cli-tools/overlay.yml

@@ -11,3 +11,4 @@ tags:
     - cli
     - productivity
 ports: []
+minimal: true

package/overlays/mongodb/overlay.yml

@@ -13,5 +13,15 @@ tags:
     - mongodb
     - document
 ports:
-    - 27017
-    - 8081
+    - port: 27017
+      service: mongodb
+      protocol: tcp
+      description: MongoDB database connection
+      onAutoForward: notify
+      connectionStringTemplate: 'mongodb://{mongo_initdb_root_username}:{mongo_initdb_root_password}@{host}:{port}/'
+    - port: 8081
+      service: mongo-express
+      protocol: http
+      description: Mongo Express web UI
+      path: /
+      onAutoForward: openBrowser

package/overlays/mysql/overlay.yml

@@ -12,5 +12,15 @@ tags:
     - sql
     - mysql
 ports:
-    - 3306
-    - 8080
+    - port: 3306
+      service: mysql
+      protocol: tcp
+      description: MySQL database connection
+      onAutoForward: notify
+      connectionStringTemplate: 'mysql://{mysql_user}:{mysql_password}@{host}:{port}/{mysql_database}'
+    - port: 8080
+      service: phpmyadmin
+      protocol: http
+      description: phpMyAdmin web UI
+      path: /
+      onAutoForward: openBrowser

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/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/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}'