container-superposition 0.1.1 → 0.1.4

package/tool/schema/overlay-manifest.schema.json

@@ -68,11 +68,58 @@
         },
         "ports": {
             "type": "array",
-            "description": "Ports used by the overlay (for offset calculation)",
+            "description": "Ports used by the overlay (for offset calculation and documentation)",
             "items": {
-                "type": "integer",
-                "minimum": 1,
-                "maximum": 65535
+                "oneOf": [
+                    {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 65535,
+                        "description": "Simple port number (legacy format)"
+                    },
+                    {
+                        "type": "object",
+                        "description": "Rich port metadata with service info and connection details",
+                        "required": ["port"],
+                        "properties": {
+                            "port": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "maximum": 65535,
+                                "description": "Port number"
+                            },
+                            "service": {
+                                "type": "string",
+                                "description": "Service name (e.g., postgres, grafana, jaeger)",
+                                "pattern": "^[a-z0-9-]+$"
+                            },
+                            "protocol": {
+                                "type": "string",
+                                "description": "Protocol type",
+                                "enum": ["http", "https", "tcp", "udp", "grpc"]
+                            },
+                            "description": {
+                                "type": "string",
+                                "description": "Human-readable description of what this port is for"
+                            },
+                            "path": {
+                                "type": "string",
+                                "description": "Default path for HTTP/HTTPS services (e.g., /, /metrics)",
+                                "pattern": "^/"
+                            },
+                            "onAutoForward": {
+                                "type": "string",
+                                "description": "VS Code port auto-forward behavior",
+                                "enum": ["notify", "openBrowser", "openPreview", "silent", "ignore"]
+                            },
+                            "connectionStringTemplate": {
+                                "type": "string",
+                                "description": "Template for connection string (e.g., postgresql://{user}:{password}@{host}:{port}/{database})"
+                            }
+                        },
+                        "additionalProperties": false
+                    }
+                ]
             },
             "default": []
         },
@@ -80,6 +127,19 @@
             "type": "integer",
             "description": "Display order within category (lower = first)",
             "minimum": 1
+        },
+        "imports": {
+            "type": "array",
+            "description": "Shared files to import from overlays/.shared/",
+            "items": {
+                "type": "string"
+            },
+            "default": []
+        },
+        "minimal": {
+            "type": "boolean",
+            "description": "Whether this overlay is excluded in minimal mode (true = extra/optional)",
+            "default": false
         }
     },
     "additionalProperties": false

package/tool/schema/superposition-manifest.schema.json

@@ -0,0 +1,104 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "Superposition Manifest",
+    "description": "Manifest file (superposition.json) generated by container-superposition to track devcontainer configuration",
+    "properties": {
+        "manifestVersion": {
+            "type": "string",
+            "description": "Schema version of the manifest (increments on breaking changes)",
+            "pattern": "^[0-9]+$"
+        },
+        "generatedBy": {
+            "type": "string",
+            "description": "Version of container-superposition that created this manifest"
+        },
+        "version": {
+            "type": "string",
+            "description": "Legacy field for backward compatibility (deprecated, use manifestVersion instead)"
+        },
+        "generated": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp when the manifest was generated"
+        },
+        "baseTemplate": {
+            "type": "string",
+            "enum": ["plain", "compose"],
+            "description": "Base devcontainer template used (plain for single image, compose for multi-service)"
+        },
+        "baseImage": {
+            "type": "string",
+            "description": "Base container image used for the devcontainer"
+        },
+        "overlays": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "description": "List of overlay IDs that were applied to create this configuration"
+        },
+        "portOffset": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Port offset applied to all service ports (optional)"
+        },
+        "preset": {
+            "type": "string",
+            "description": "ID of the preset used to generate this configuration (optional)"
+        },
+        "presetChoices": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "string"
+            },
+            "description": "User choices made within preset user-choice sections (optional)"
+        },
+        "autoResolved": {
+            "type": "object",
+            "properties": {
+                "added": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "List of overlays that were automatically added as dependencies"
+                },
+                "reason": {
+                    "type": "string",
+                    "description": "Human-readable reason why dependencies were added"
+                }
+            },
+            "required": ["added", "reason"],
+            "description": "Information about automatically resolved dependencies (optional)"
+        },
+        "containerName": {
+            "type": "string",
+            "description": "Name of the container/project from devcontainer.json (optional)"
+        },
+        "customizations": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "type": "boolean",
+                    "description": "Whether custom patches are enabled"
+                },
+                "location": {
+                    "type": "string",
+                    "description": "Path to custom patches directory relative to workspace"
+                }
+            },
+            "required": ["enabled", "location"],
+            "description": "Information about custom patches/overrides (optional)"
+        }
+    },
+    "required": [
+        "manifestVersion",
+        "generatedBy",
+        "generated",
+        "baseTemplate",
+        "baseImage",
+        "overlays"
+    ],
+    "additionalProperties": false
+}

package/overlays/presets/web-api.yml

@@ -1,109 +0,0 @@
-# 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