container-superposition 0.1.3 → 0.1.4

package/dist/tool/utils/summary.js

@@ -0,0 +1,260 @@
+/**
+ * Summary utilities for post-generation output
+ */
+import chalk from 'chalk';
+import boxen from 'boxen';
+import { generateUrl } from './port-utils.js';
+/**
+ * Detect warnings based on selected overlays and configuration
+ */
+export function detectWarnings(overlays, answers) {
+    const warnings = [];
+    // Check for docker-sock security warning
+    const hasDockerSock = overlays.some((o) => o.id === 'docker-sock');
+    if (hasDockerSock) {
+        warnings.push('docker-sock overlay provides root access to host Docker daemon\n  Use only for trusted code. Consider docker-in-docker for isolation.');
+    }
+    // Check for target mismatch
+    const target = answers.target || 'local';
+    if (hasDockerSock && target === 'codespaces') {
+        warnings.push('docker-sock may not work in GitHub Codespaces\n  Consider using docker-in-docker instead.');
+    }
+    // Check for high port count
+    const portCount = overlays.reduce((count, o) => count + (o.ports?.length || 0), 0);
+    const hasHighPortCountWarning = portCount > 10;
+    if (hasHighPortCountWarning) {
+        warnings.push(`High port count (${portCount} ports) may cause conflicts\n  Consider using --port-offset to avoid conflicts with other projects.`);
+    }
+    // Check for no port offset with multiple services
+    const hasServices = overlays.some((o) => o.category === 'database' || o.category === 'observability');
+    if (!hasHighPortCountWarning &&
+        hasServices &&
+        (!answers.portOffset || answers.portOffset === 0)) {
+        warnings.push('Running multiple devcontainers simultaneously may cause port conflicts\n  Use --port-offset 100 (or higher) to avoid conflicts.');
+    }
+    return warnings;
+}
+/**
+ * Generate helpful tips based on configuration
+ */
+export function generateTips(overlays, answers) {
+    const tips = [];
+    // Suggest committing manifest
+    if (!answers.preset) {
+        tips.push('Commit superposition.json to enable team regeneration');
+    }
+    // Suggest customization directory
+    const hasCustomDir = overlays.length > 3;
+    if (hasCustomDir) {
+        tips.push('Preserve customizations in .devcontainer/custom/');
+    }
+    // Suggest regen command
+    tips.push('Regenerate anytime: npx container-superposition regen');
+    return tips;
+}
+/**
+ * Generate next steps based on mode
+ */
+export function generateNextSteps(isManifestOnly, isRegen) {
+    if (isManifestOnly) {
+        return [
+            'Review the generated superposition.json file',
+            'Commit it to your repository',
+            'Team members can run "npx container-superposition regen"',
+        ];
+    }
+    if (isRegen) {
+        return [
+            'Rebuild container:\n     Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → "Dev Containers: Rebuild Container"',
+            'Test changes manually',
+            'Review any customizations in .devcontainer/custom/',
+        ];
+    }
+    return [
+        'Customize environment:\n     cp .devcontainer/.env.example .devcontainer/.env',
+        'Open in VS Code:\n     code .',
+        'Reopen in Container:\n     Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → "Dev Containers: Reopen in Container"',
+        'Verify setup:\n     npx container-superposition doctor',
+    ];
+}
+/**
+ * Convert overlay metadata to service info
+ */
+export function overlaysToServices(overlays) {
+    return overlays.map((overlay) => {
+        // Extract version from name if present (e.g., "PostgreSQL 16" -> version: "16")
+        const versionMatch = overlay.name.match(/\d+(?:\.\d+)?/);
+        const version = versionMatch ? versionMatch[0] : undefined;
+        return {
+            name: overlay.name,
+            category: overlay.category,
+            version,
+        };
+    });
+}
+/**
+ * Convert normalized ports to port info with URLs
+ */
+export function portsToPortInfo(ports, connectionStrings) {
+    return ports.map((port) => {
+        const service = port.service || 'unknown';
+        const url = generateUrl(port);
+        // Try to find connection string for this service
+        let connectionString;
+        if (connectionStrings[service]) {
+            connectionString = connectionStrings[service];
+        }
+        else if (connectionStrings[`${service}-url`]) {
+            connectionString = connectionStrings[`${service}-url`];
+        }
+        return {
+            service,
+            port: port.port,
+            actualPort: port.actualPort,
+            url,
+            connectionString,
+        };
+    });
+}
+/**
+ * Format and print generation summary.
+ *
+ * @param summary The generation summary to render.
+ * @param quiet   When true, suppresses all console output. This parameter is
+ *                reserved for callers (for example, CLI commands or tests)
+ *                that need to generate a summary object but handle user
+ *                messaging themselves.
+ */
+export function printSummary(summary, quiet = false) {
+    // If quiet mode is enabled, skip printing while still allowing callers
+    // to invoke this function consistently. See the JSDoc for intended usage.
+    if (quiet) {
+        return;
+    }
+    const lines = [];
+    // Header
+    const title = summary.isManifestOnly
+        ? '📋 Manifest Generated'
+        : summary.backupPath
+            ? '🔄 DevContainer Regenerated'
+            : '✨ DevContainer Generated';
+    lines.push(chalk.bold.green(title));
+    lines.push('');
+    // Backup notification (for regen)
+    if (summary.backupPath) {
+        lines.push(chalk.yellow(`Backup created: ${summary.backupPath}`));
+        lines.push('');
+    }
+    // Files created (manifest-only shows just manifest)
+    if (summary.isManifestOnly) {
+        lines.push(chalk.white('Manifest:'));
+        lines.push(chalk.gray(`  ${summary.manifestPath || 'superposition.json'}`));
+        lines.push('');
+    }
+    else {
+        lines.push(chalk.white('Files created:'));
+        for (const file of summary.files.slice(0, 8)) {
+            lines.push(chalk.gray(`  ${file}`));
+        }
+        if (summary.files.length > 8) {
+            lines.push(chalk.gray(`  ... and ${summary.files.length - 8} more`));
+        }
+        lines.push('');
+    }
+    // Services included
+    if (summary.services.length > 0) {
+        lines.push(chalk.white('Services included:'));
+        const displayServices = summary.services.slice(0, 10);
+        for (const service of displayServices) {
+            const versionStr = service.version ? ` ${service.version}` : '';
+            const categoryStr = chalk.dim(` (${service.category})`);
+            lines.push(chalk.green(`  ✓ ${service.name}${versionStr}`) + categoryStr);
+        }
+        if (summary.services.length > 10) {
+            lines.push(chalk.gray(`  ... and ${summary.services.length - 10} more`));
+        }
+        lines.push('');
+    }
+    // Port mappings and service URLs
+    if (summary.ports.length > 0) {
+        lines.push(chalk.white('🌐 Service Access'));
+        lines.push('');
+        // Group by HTTP services and database services
+        const httpPorts = summary.ports.filter((p) => p.url);
+        const dbPorts = summary.ports.filter((p) => p.connectionString && !p.url);
+        // Show application/HTTP services first
+        if (httpPorts.length > 0) {
+            for (const port of httpPorts) {
+                const label = port.service.charAt(0).toUpperCase() + port.service.slice(1);
+                lines.push(chalk.cyan(`  ${label}:`));
+                lines.push(chalk.gray(`    ${port.url}`));
+            }
+            lines.push('');
+        }
+        // Show database/infrastructure services
+        if (dbPorts.length > 0) {
+            lines.push(chalk.white('  Infrastructure:'));
+            for (const port of dbPorts) {
+                const label = port.service.charAt(0).toUpperCase() + port.service.slice(1);
+                lines.push(chalk.cyan(`    ${label}:`));
+                lines.push(chalk.gray(`      ${port.connectionString}`));
+            }
+            lines.push('');
+        }
+        // Port offset info
+        if (summary.portOffset > 0) {
+            lines.push(chalk.dim(`  Port offset: ${summary.portOffset}`));
+        }
+        else {
+            lines.push(chalk.dim('  Port offset: 0 (use --port-offset to avoid conflicts)'));
+        }
+        lines.push('');
+    }
+    // Warnings
+    if (summary.warnings.length > 0) {
+        lines.push(chalk.yellow('⚠️  Warnings'));
+        lines.push('');
+        for (const warning of summary.warnings) {
+            const warningLines = warning.split('\n');
+            lines.push(chalk.yellow(`  • ${warningLines[0]}`));
+            for (let i = 1; i < warningLines.length; i++) {
+                lines.push(chalk.dim(`    ${warningLines[i]}`));
+            }
+        }
+        lines.push('');
+    }
+    // Tips
+    if (summary.tips.length > 0) {
+        lines.push(chalk.cyan('💡 Tips'));
+        lines.push('');
+        for (const tip of summary.tips) {
+            lines.push(chalk.gray(`  • ${tip}`));
+        }
+        lines.push('');
+    }
+    // Next steps
+    lines.push(chalk.white('📝 Next Steps'));
+    lines.push('');
+    for (let i = 0; i < summary.nextSteps.length; i++) {
+        const step = summary.nextSteps[i];
+        const stepLines = step.split('\n');
+        lines.push(chalk.gray(`  ${i + 1}. ${stepLines[0]}`));
+        for (let j = 1; j < stepLines.length; j++) {
+            lines.push(chalk.dim(`     ${stepLines[j]}`));
+        }
+    }
+    // Footer
+    if (!summary.isManifestOnly) {
+        lines.push('');
+        lines.push(chalk.dim(`Generated in .devcontainer/ • Manifest: ${summary.manifestPath || 'superposition.json'}`));
+    }
+    // Print with boxen
+    console.log('\n' +
+        boxen(lines.join('\n'), {
+            padding: 1,
+            borderColor: 'green',
+            borderStyle: 'round',
+            margin: 1,
+        }));
+}
+//# sourceMappingURL=summary.js.map

package/dist/tool/utils/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../../tool/utils/summary.ts"],"names":[],"mappings":"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"}

package/docs/overlays.md

@@ -442,6 +442,16 @@ Infrastructure as Code with HCL (includes tflint)
 
 ## Dev Tool Overlays
 
+### Cloudflared (`cloudflared`)
+
+Cloudflare Tunnel for securely exposing local services to the internet
+
+| Property      | Value                                     |
+| ------------- | ----------------------------------------- |
+| **Category**  | dev                                       |
+| **Conflicts** | `ngrok`                                   |
+| **Tags**      | `dev`, `tunneling`, `proxy`, `cloudflare` |
+
 ### Codex (`codex`)
 
 OpenAI Codex CLI for AI-powered code generation and assistance
@@ -501,6 +511,15 @@ Git LFS, GitHub CLI, GPG/SSH support for secure Git operations
 | **Category** | dev                                    |
 | **Tags**     | `dev`, `git`, `security`, `ssh`, `gpg` |
 
+### gRPC Tools (`grpc-tools`)
+
+Protocol Buffers compiler, Buf, and grpcurl for gRPC development
+
+| Property     | Value                            |
+| ------------ | -------------------------------- |
+| **Category** | dev                              |
+| **Tags**     | `dev`, `grpc`, `protobuf`, `api` |
+
 ### Just Task Runner (`just`)
 
 Fast, simple command runner (Rust-based alternative to Make)
@@ -510,6 +529,29 @@ Fast, simple command runner (Rust-based alternative to Make)
 | **Category** | dev                          |
 | **Tags**     | `dev`, `automation`, `tasks` |
 
+### Keycloak (`keycloak`)
+
+Open-source identity and access management (OIDC/OAuth2)
+
+| Property     | Value                                       |
+| ------------ | ------------------------------------------- |
+| **Category** | dev                                         |
+| **Supports** | compose                                     |
+| **Requires** | `postgres`                                  |
+| **Tags**     | `dev`, `auth`, `oidc`, `oauth2`, `identity` |
+| **Ports**    | [object Object]                             |
+
+### Mailpit (`mailpit`)
+
+Email testing tool with web UI and SMTP server
+
+| Property     | Value                             |
+| ------------ | --------------------------------- |
+| **Category** | dev                               |
+| **Supports** | compose                           |
+| **Tags**     | `dev`, `email`, `smtp`, `testing` |
+| **Ports**    | [object Object], [object Object]  |
+
 ### Modern CLI Tools (`modern-cli-tools`)
 
 jq, yq, ripgrep, fd, bat - Essential modern command-line tools
@@ -523,11 +565,12 @@ jq, yq, ripgrep, fd, bat - Essential modern command-line tools
 
 Secure tunneling for webhook testing and external access
 
-| Property     | Value                          |
-| ------------ | ------------------------------ |
-| **Category** | dev                            |
-| **Tags**     | `dev`, `tunneling`, `webhooks` |
-| **Ports**    | 4040                           |
+| Property      | Value                          |
+| ------------- | ------------------------------ |
+| **Category**  | dev                            |
+| **Conflicts** | `cloudflared`                  |
+| **Tags**      | `dev`, `tunneling`, `webhooks` |
+| **Ports**     | 4040                           |
 
 ### OpenAPI Tools (`openapi-tools`)
 

package/overlays/.presets/microservice.yml

@@ -26,11 +26,35 @@ selects:
             options: [dotnet, nodejs, python, go, java]
             defaultOption: nodejs
 
-        messaging:
-            id: messaging
-            prompt: Select message broker
-            options: [rabbitmq, redpanda, nats]
-            defaultOption: rabbitmq
+# Parameterized slots
+parameters:
+    broker:
+        description: 'Message broker'
+        default: rabbitmq
+        options:
+            - id: rabbitmq
+              overlays: [rabbitmq]
+              description: 'RabbitMQ AMQP message broker'
+            - id: nats
+              overlays: [nats]
+              description: 'NATS lightweight messaging'
+            - id: redpanda
+              overlays: [redpanda]
+              description: 'Redpanda Kafka-compatible streaming'
+            - id: none
+              overlays: []
+              description: 'No message broker'
+
+    observability:
+        description: 'Observability stack level'
+        default: standard
+        options:
+            - id: standard
+              overlays: []
+              description: 'Standard (Jaeger + Prometheus + Grafana, already included)'
+            - id: full
+              overlays: [loki]
+              description: 'Full stack - adds Loki for log aggregation'
 
 # Glue configuration - integration helpers
 glueConfig:
@@ -66,11 +90,12 @@ glueConfig:
 
         ### Services
 
-        - **Message Broker**: Async communication between services
+        - **Message Broker**: Async communication between services (RabbitMQ/NATS/Redpanda based on your choice)
         - **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)
+        - **Loki** _(full observability only)_: Log aggregation (port 3100)
 
         ### Connection Strings
 
@@ -100,6 +125,7 @@ glueConfig:
         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
+        5. _(Full observability)_ Query logs in Loki via Grafana at http://localhost:3000
 
         ### Distributed Tracing
 

package/overlays/.presets/web-api.yml

@@ -12,13 +12,7 @@ tags: [preset, api, web, backend, observability]
 # Overlays to select
 selects:
     # Always included
-    required:
-        - postgres
-        - redis
-        - otel-collector
-        - prometheus
-        - grafana
-        - loki
+    required: []
 
     # User makes choices
     userChoice:
@@ -28,31 +22,70 @@ selects:
             options: [dotnet, nodejs, python, go, java]
             defaultOption: nodejs
 
+# Parameterized slots - users can customize these without micro-managing individual overlays
+parameters:
+    database:
+        description: 'Primary data store'
+        default: postgres
+        options:
+            - id: postgres
+              overlays: [postgres]
+              description: 'PostgreSQL relational database'
+            - id: mongodb
+              overlays: [mongodb]
+              description: 'MongoDB document database'
+            - id: mysql
+              overlays: [mysql]
+              description: 'MySQL relational database'
+            - id: none
+              overlays: []
+              description: 'No database (manage separately)'
+
+    cache:
+        description: 'In-memory cache'
+        default: redis
+        options:
+            - id: redis
+              overlays: [redis]
+              description: 'Redis cache and session store'
+            - id: none
+              overlays: []
+              description: 'No cache'
+
+    broker:
+        description: 'Message broker (optional)'
+        default: none
+        options:
+            - id: rabbitmq
+              overlays: [rabbitmq]
+              description: 'RabbitMQ AMQP message broker'
+            - id: nats
+              overlays: [nats]
+              description: 'NATS lightweight messaging'
+            - id: redpanda
+              overlays: [redpanda]
+              description: 'Redpanda Kafka-compatible streaming'
+            - id: none
+              overlays: []
+              description: 'No message broker'
+
+    observability:
+        description: 'Monitoring and observability stack'
+        default: standard
+        options:
+            - id: minimal
+              overlays: []
+              description: 'No observability tools'
+            - id: standard
+              overlays: [prometheus, grafana]
+              description: 'Metrics and dashboards'
+            - id: full
+              overlays: [otel-collector, prometheus, grafana, loki]
+              description: 'Full stack - metrics, logs, and traces'
+
 # 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
+    # Suggested port mappings (actual ports depend on chosen overlays)
     portMappings:
         api: 8000
         grafana: 3000
@@ -62,40 +95,28 @@ glueConfig:
     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)
+        This devcontainer is configured for web API development. The exact services depend
+        on the parameters you chose (database, cache, broker, observability).
 
         ### Connection Strings
 
-        ```bash
-        # PostgreSQL
-        DATABASE_URL="postgresql://postgres:postgres@postgres:5432/myapp"
-
-        # Redis
-        REDIS_URL="redis://redis:6379"
+        Connection strings for each service are defined in `.devcontainer/.env.example`.
+        Copy that file to `.env` and adjust values as needed:
 
-        # OpenTelemetry
-        OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
+        ```bash
+        cd .devcontainer
+        cp .env.example .env
         ```
 
         ### 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
+        1. Start your API (default suggested port: 8000)
+        2. Access Grafana at http://localhost:3000 (admin/admin) — if observability was enabled
+        3. View metrics in Prometheus at http://localhost:9090 — if observability was enabled
 
         ### Health Checks
 
-        All services include health checks. Verify with:
+        Verify all services are running:
 
         ```bash
         docker-compose ps
@@ -103,7 +124,6 @@ glueConfig:
 
         ### Next Steps
 
-        - Configure your API to use the DATABASE_URL and REDIS_URL
-        - Add OpenTelemetry SDK to your application
+        - Configure your API to use the connection strings from `.env`
+        - Add OpenTelemetry SDK to your application (if full observability was selected)
         - Create custom Grafana dashboards for your API metrics
-        - Set up log forwarding to Loki