container-superposition 0.1.1 → 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/dist/tool/utils/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility functions for version management
+ */
+/**
+ * Get the current tool version from package.json
+ * Works in both source (TypeScript) and compiled (JavaScript) contexts
+ */
+export declare function getToolVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/tool/utils/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../tool/utils/version.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAmBvC"}

package/dist/tool/utils/version.js

@@ -0,0 +1,32 @@
+/**
+ * Utility functions for version management
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+// Get __dirname equivalent in ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Get the current tool version from package.json
+ * Works in both source (TypeScript) and compiled (JavaScript) contexts
+ */
+export function getToolVersion() {
+    try {
+        // Try multiple paths to handle different execution contexts
+        const packageJsonCandidates = [
+            // From tool/utils/ (source)
+            path.join(__dirname, '..', '..', 'package.json'),
+            // From dist/tool/utils/ (compiled)
+            path.join(__dirname, '..', '..', '..', 'package.json'),
+        ];
+        const packageJsonPath = packageJsonCandidates.find((candidate) => fs.existsSync(candidate)) ??
+            packageJsonCandidates[0];
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        return packageJson.version || 'unknown';
+    }
+    catch (error) {
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=version.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../tool/utils/version.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,kCAAkC;AAClC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC1B,IAAI,CAAC;QACD,4DAA4D;QAC5D,MAAM,qBAAqB,GAAG;YAC1B,4BAA4B;YAC5B,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;YAChD,mCAAmC;YACnC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;SACzD,CAAC;QAEF,MAAM,eAAe,GACjB,qBAAqB,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YACnE,qBAAqB,CAAC,CAAC,CAAC,CAAC;QAE7B,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1E,OAAO,WAAW,CAAC,OAAO,IAAI,SAAS,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,OAAO,SAAS,CAAC;IACrB,CAAC;AACL,CAAC"}

package/docs/architecture.md

@@ -74,29 +74,33 @@ scripts/
 5. **Merge .env.example** files from all selected overlays
 6. **Write merged configuration** to output path
 
-### Deep Merge Logic
-
-```typescript
-function deepMerge(base, overlay) {
-  for each key in overlay:
-    if key exists in base and both are objects:
-      if both are arrays:
-        concatenate and deduplicate
-      else:
-        recursively merge
-    else:
-      use overlay value
-  return merged
-}
-```
+### Merge Strategy
+
+Container-superposition uses a **formal, deterministic merge strategy** for combining configurations from base templates and overlays.
+
+**Core principles:**
+
+- **Deterministic**: Same inputs always produce same output
+- **Deep merge**: Objects are recursively merged, not replaced
+- **Union by default**: Arrays and collections are merged (unioned), not replaced
+- **Last writer wins**: For conflicting primitive values
+
+**Key behaviors:**
+
+- **Objects**: Recursively merged
+- **Arrays**: Concatenated and deduplicated (union strategy)
+- **Features**: Deep merged by feature key
+- **remoteEnv**: Intelligent PATH variable merging
+- **Package lists**: Space-separated strings merged with deduplication
+- **depends_on**: Filtered to only existing services
+
+For the complete specification with examples, see **[Merge Strategy Specification](merge-strategy.md)**.
 
-Special handling:
+Implementation details:
 
-- **Arrays**: Concatenate and deduplicate (ports, packages)
-- **apt-get packages**: Merge space-separated lists
-- **Features**: Deep merge feature configs
-- **Environment variables**: Merge key-value pairs
-- **Port attributes**: Merge labeled port configurations
+- Merge utilities: `tool/utils/merge.ts`
+- Integration: `tool/questionnaire/composer.ts`
+- Tests: `tool/__tests__/merge-strategy.test.ts`
 
 ### File Handling per Overlay
 

package/docs/deployment-targets.md

@@ -0,0 +1,150 @@
+# Deployment Target Support
+
+Container Superposition validates overlay compatibility with different deployment environments using the `--target` flag.
+
+## Quick Start
+
+```bash
+# Specify deployment target
+npx container-superposition init --target codespaces
+npx container-superposition init --target gitpod
+npx container-superposition init --target local  # default
+
+# With specific configuration
+npx container-superposition init \
+    --stack compose \
+    --language nodejs \
+    --database postgres \
+    --dev-tools docker-in-docker \
+    --target codespaces
+```
+
+## Supported Deployment Targets
+
+| Target         | Description                       | Docker Support | Auto Port Forward |
+| -------------- | --------------------------------- | -------------- | ----------------- |
+| **local**      | Local machine with Docker Desktop | ✅ Host Docker | No                |
+| **codespaces** | GitHub Codespaces (cloud IDE)     | ⚠️ DinD only   | Yes               |
+| **gitpod**     | Gitpod workspaces                 | ⚠️ DinD only   | Yes               |
+| **devpod**     | DevPod client-only environments   | ✅ Host Docker | No                |
+
+## How It Works
+
+### Interactive Mode
+
+If you select incompatible overlays (e.g., `docker-sock` for Codespaces), the tool will:
+
+- Show which overlays won't work in your target environment
+- Suggest compatible alternatives
+- Let you choose your deployment target with informed guidance
+
+**Example interaction:**
+
+```
+⚠️  Deployment Target Compatibility Check:
+
+Some selected overlays may not work in all environments.
+
+• Docker (host socket)
+  Not compatible with: GitHub Codespaces, Gitpod
+  Alternatives: Docker-in-Docker
+
+Which environment are you targeting?
+❯ 🖥️  Local Development (Docker Desktop)
+  ☁️  GitHub Codespaces
+  🌐 Gitpod
+  📦 DevPod
+```
+
+### CLI Mode
+
+The target validates your selection and generates the configuration:
+
+- Incompatibilities are allowed (you know what you're doing)
+- Generated documentation notes any compatibility issues
+
+## Example Configurations
+
+### Optimized for GitHub Codespaces
+
+```bash
+npx container-superposition init \
+    --stack compose \
+    --language nodejs \
+    --database postgres \
+    --dev-tools docker-in-docker \
+    --target codespaces
+```
+
+### Local Development
+
+```bash
+npx container-superposition init \
+    --stack compose \
+    --language nodejs \
+    --database postgres \
+    --dev-tools docker-sock \
+    --target local
+```
+
+## Key Compatibility Rules
+
+- ⚠️ **docker-sock** requires host Docker → Use in `local` or `devpod` only
+- ✅ **docker-in-docker** works everywhere → Recommended for `codespaces` and `gitpod`
+- 🔄 Cloud targets auto-forward ports → No manual forwarding needed
+
+## Environment Differences
+
+Different environments have different capabilities:
+
+### Codespaces/Gitpod
+
+- **No access to host Docker daemon** - Must use docker-in-docker
+- **Auto-forward ports** - Ports are automatically accessible
+- **Cloud-based** - Resources may be constrained
+
+### Local
+
+- **Full access to host Docker** - Can use docker-sock for better performance
+- **Faster builds** - Shared cache with host
+- **Manual port forwarding** - Need to expose ports explicitly
+
+### DevPod
+
+- **Client-managed** - Runs on your infrastructure
+- **Can access host Docker** - Depending on setup
+- **Flexible** - Configure based on your needs
+
+## Why Deployment Targets?
+
+The target system ensures you get warnings about incompatibilities before deploying. This prevents:
+
+- Wasted time debugging environment-specific issues
+- Confusion about why overlays don't work in cloud IDEs
+- Having to manually research compatibility
+
+## Configuration
+
+Target configurations are stored in `overlays/.registry/deployment-targets.yml`. To add a new target, simply add an entry to this file:
+
+```yaml
+- id: new-target
+  name: New Target
+  description: Description of the target
+  incompatibleOverlays:
+      - docker-sock
+  recommendations:
+      docker-sock:
+          - docker-in-docker
+  portForwarding:
+      defaultBehavior: notify
+      autoForward: true
+  constraints:
+      hasHostDocker: false
+      supportsPrivileged: true
+```
+
+## See Also
+
+- [Discovery Commands](discovery-commands.md) - Explore overlays before generating
+- [Overlays Documentation](overlays.md) - Complete overlay reference