container-superposition 0.1.1 → 0.1.3

package/dist/tool/utils/merge.js

@@ -0,0 +1,277 @@
+/**
+ * Merge utilities for container-superposition
+ *
+ * This module implements the formal merge strategy specification for combining
+ * devcontainer configurations, docker-compose files, and environment variables.
+ *
+ * See docs/merge-strategy.md for the complete specification.
+ */
+/**
+ * Deep merge two objects with special handling for arrays and specific fields.
+ *
+ * Merge strategy:
+ * - Objects: Recursively merged
+ * - Arrays: Concatenated and deduplicated (union strategy)
+ * - Primitives: Source overwrites target (last writer wins)
+ * - Special cases: remoteEnv (PATH handling), features, etc.
+ *
+ * @param target - Base object to merge into
+ * @param source - Object to merge from (takes precedence)
+ * @returns Merged object
+ *
+ * @example
+ * const base = { features: { "node:1": { version: "lts" } } };
+ * const overlay = { features: { "node:1": { nodeGypDependencies: true } } };
+ * const result = deepMerge(base, overlay);
+ * // Result: { features: { "node:1": { version: "lts", nodeGypDependencies: true } } }
+ */
+export function deepMerge(target, source) {
+    const output = { ...target };
+    for (const key in source) {
+        if (source[key] instanceof Object && key in target) {
+            if (Array.isArray(source[key])) {
+                // For arrays, concatenate and deduplicate
+                // Empty source arrays do not clear target arrays
+                if (source[key].length === 0) {
+                    output[key] = target[key];
+                }
+                else {
+                    output[key] = Array.isArray(target[key])
+                        ? [...new Set([...target[key], ...source[key]])]
+                        : source[key];
+                }
+            }
+            else if (key === 'remoteEnv') {
+                // Special handling for remoteEnv to merge PATH variables intelligently
+                output[key] = mergeRemoteEnv(target[key], source[key]);
+            }
+            else {
+                // Recursively merge objects
+                output[key] = deepMerge(target[key], source[key]);
+            }
+        }
+        else {
+            // Source value overwrites target (last writer wins)
+            output[key] = source[key];
+        }
+    }
+    return output;
+}
+/**
+ * Split PATH string on colons, preserving ${...} variable references.
+ *
+ * Handles environment variable references like ${containerEnv:HOME} without
+ * splitting them on the colon inside the braces.
+ *
+ * @param pathString - PATH value with colon-separated components
+ * @returns Array of path components
+ *
+ * @example
+ * splitPath("${containerEnv:HOME}/bin:${containerEnv:PATH}")
+ * // Returns: ["${containerEnv:HOME}/bin", "${containerEnv:PATH}"]
+ */
+function splitPath(pathString) {
+    const paths = [];
+    let current = '';
+    let braceDepth = 0;
+    for (let i = 0; i < pathString.length; i++) {
+        const char = pathString[i];
+        const nextChar = pathString[i + 1];
+        if (char === '$' && nextChar === '{') {
+            current += char;
+            braceDepth++;
+        }
+        else if (char === '}' && braceDepth > 0) {
+            current += char;
+            braceDepth--;
+        }
+        else if (char === ':' && braceDepth === 0) {
+            // Split here - we're not inside ${...}
+            if (current) {
+                paths.push(current);
+            }
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    // Add the last component
+    if (current) {
+        paths.push(current);
+    }
+    return paths;
+}
+/**
+ * Merge remoteEnv objects with intelligent PATH handling.
+ *
+ * For PATH variables:
+ * 1. Split on colons (preserving ${...} references)
+ * 2. Remove ${containerEnv:PATH} placeholders
+ * 3. Concatenate and deduplicate
+ * 4. Append ${containerEnv:PATH} at end
+ *
+ * For other variables:
+ * - Source overwrites target (last writer wins)
+ *
+ * @param target - Base environment variables
+ * @param source - Overlay environment variables
+ * @returns Merged environment variables
+ *
+ * @example
+ * mergeRemoteEnv(
+ *   { PATH: "/usr/local/bin:${containerEnv:PATH}", NODE_ENV: "development" },
+ *   { PATH: "${containerEnv:HOME}/.local/bin:${containerEnv:PATH}", NODE_ENV: "production" }
+ * )
+ * // Returns:
+ * // {
+ * //   PATH: "/usr/local/bin:${containerEnv:HOME}/.local/bin:${containerEnv:PATH}",
+ * //   NODE_ENV: "production"
+ * // }
+ */
+export function mergeRemoteEnv(target, source) {
+    const output = { ...target };
+    for (const key in source) {
+        if (key === 'PATH' && target[key]) {
+            // Collect PATH components from both target and source using smart split
+            const targetPaths = splitPath(target[key]).filter((p) => p && p !== '${containerEnv:PATH}');
+            const sourcePaths = splitPath(source[key]).filter((p) => p && p !== '${containerEnv:PATH}');
+            // Combine and deduplicate paths, preserving order
+            const allPaths = [...new Set([...targetPaths, ...sourcePaths])];
+            // Rebuild PATH with original ${containerEnv:PATH} at the end
+            output[key] = [...allPaths, '${containerEnv:PATH}'].join(':');
+        }
+        else {
+            // For non-PATH variables, source overwrites target
+            output[key] = source[key];
+        }
+    }
+    return output;
+}
+/**
+ * Merge space-separated package lists with deduplication.
+ *
+ * Used for apt, apk, and other package manager lists.
+ *
+ * @param existing - Current package list (space-separated)
+ * @param additional - Additional packages to merge (space-separated)
+ * @returns Merged package list (space-separated, deduplicated)
+ *
+ * @example
+ * mergePackages("curl wget", "wget jq")
+ * // Returns: "curl wget jq"
+ */
+export function mergePackages(existing, additional) {
+    // Filter out empty tokens from split to avoid leading/trailing spaces
+    const existingPackages = existing.split(' ').filter((p) => p);
+    const newPackages = additional.split(' ').filter((p) => p);
+    // Merge and deduplicate
+    const merged = [...new Set([...existingPackages, ...newPackages])];
+    return merged.join(' ');
+}
+/**
+ * Filter depends_on to only include services that exist in the final composition.
+ *
+ * Supports both Docker Compose syntaxes:
+ * - Array form: depends_on: [serviceA, serviceB]
+ * - Object form: depends_on: { serviceA: { condition: ... } }
+ *
+ * @param dependsOn - Original depends_on configuration
+ * @param existingServices - Set of service names that exist
+ * @returns Filtered depends_on (undefined if empty after filtering)
+ *
+ * @example
+ * filterDependsOn(
+ *   ["postgres", "redis", "rabbitmq"],
+ *   new Set(["postgres", "redis"])
+ * )
+ * // Returns: ["postgres", "redis"]
+ */
+export function filterDependsOn(dependsOn, existingServices) {
+    if (Array.isArray(dependsOn)) {
+        const filtered = dependsOn.filter((dep) => typeof dep === 'string' && existingServices.has(dep));
+        return filtered.length > 0 ? filtered : undefined;
+    }
+    if (dependsOn && typeof dependsOn === 'object') {
+        const filtered = Object.fromEntries(Object.entries(dependsOn).filter(([dep]) => existingServices.has(dep)));
+        return Object.keys(filtered).length > 0 ? filtered : undefined;
+    }
+    return dependsOn;
+}
+/**
+ * Apply port offset to port string or number.
+ *
+ * @param port - Port value (string or number)
+ * @param offset - Offset to apply
+ * @returns Port with offset applied
+ *
+ * @example
+ * applyPortOffset("5432:5432", 100)
+ * // Returns: "5532:5432" (only host port offset)
+ *
+ * applyPortOffset(3000, 100)
+ * // Returns: 3100
+ */
+export function applyPortOffset(port, offset) {
+    if (typeof port === 'number') {
+        return port + offset;
+    }
+    // Handle string port mappings like "5432:5432" or "127.0.0.1:5432:5432"
+    const parts = port.split(':');
+    if (parts.length >= 2) {
+        // Format: "host:container" or "ip:host:container"
+        // Offset the host port (last or second-to-last number)
+        const isThreePart = parts.length === 3;
+        const hostPortIndex = isThreePart ? 1 : 0;
+        const hostPort = parseInt(parts[hostPortIndex], 10);
+        if (!isNaN(hostPort)) {
+            parts[hostPortIndex] = String(hostPort + offset);
+            return parts.join(':');
+        }
+    }
+    // If we can't parse it, return as-is
+    return port;
+}
+/**
+ * Apply port offset to environment variable content.
+ *
+ * Finds variables matching *PORT*=number pattern and applies offset.
+ *
+ * @param envContent - Environment file content
+ * @param offset - Port offset to apply
+ * @returns Modified environment content
+ *
+ * @example
+ * applyPortOffsetToEnv("POSTGRES_PORT=5432\nAPP_NAME=myapp", 100)
+ * // Returns: "POSTGRES_PORT=5532\nAPP_NAME=myapp"
+ */
+export function applyPortOffsetToEnv(envContent, offset) {
+    const lines = envContent.split('\n');
+    const portVarPattern = /^([A-Z_]*PORT[A-Z_]*)=(\d+)$/;
+    const modifiedLines = lines.map((line) => {
+        const match = line.match(portVarPattern);
+        if (match) {
+            const [, varName, portValue] = match;
+            const newPort = parseInt(portValue, 10) + offset;
+            return `${varName}=${newPort}`;
+        }
+        return line;
+    });
+    return modifiedLines.join('\n');
+}
+/**
+ * Merge strategy metadata for documentation and testing.
+ */
+export const MERGE_STRATEGY = {
+    version: '1.0.0',
+    description: 'Formal merge strategy specification for container-superposition',
+    rules: {
+        objects: 'deep-merge',
+        arrays: 'union-deduplicate',
+        primitives: 'last-writer-wins',
+        remoteEnv: 'intelligent-PATH-merging',
+        packages: 'space-separated-union',
+        dependsOn: 'filter-to-existing-services',
+    },
+};
+//# sourceMappingURL=merge.js.map

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

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

package/dist/tool/utils/port-utils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Port utilities for normalizing and documenting ports
+ */
+import type { PortMetadata, NormalizedPort, PortsDocumentation, OverlayMetadata } from '../schema/types.js';
+/**
+ * Normalize a port entry (number or PortMetadata) to NormalizedPort format
+ */
+export declare function normalizePort(port: number | PortMetadata, offset: number, overlayId?: string): NormalizedPort;
+/**
+ * Generate connection string from template
+ */
+export declare function generateConnectionString(template: string, port: NormalizedPort, envVars?: Record<string, string>): string;
+/**
+ * Get default connection string template for common services
+ */
+export declare function getDefaultConnectionStringTemplate(service: string, protocol?: string): string | undefined;
+/**
+ * Generate URL for HTTP/HTTPS services
+ */
+export declare function generateUrl(port: NormalizedPort): string | undefined;
+/**
+ * Generate ports documentation from overlays
+ */
+export declare function generatePortsDocumentation(overlays: OverlayMetadata[], portOffset: number, envVars?: Record<string, string>): PortsDocumentation;
+/**
+ * Extract all unique ports from overlays (for offset calculation)
+ */
+export declare function extractPorts(overlays: OverlayMetadata[]): number[];
+//# sourceMappingURL=port-utils.d.ts.map

package/dist/tool/utils/port-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-utils.d.ts","sourceRoot":"","sources":["../../../tool/utils/port-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACR,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,eAAe,EAClB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,wBAAgB,aAAa,CACzB,IAAI,EAAE,MAAM,GAAG,YAAY,EAC3B,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACnB,cAAc,CAgBhB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACrC,MAAM,CAoBR;AAED;;GAEG;AACH,wBAAgB,kCAAkC,CAC9C,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAiBpB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAMpE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACtC,QAAQ,EAAE,eAAe,EAAE,EAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACrC,kBAAkB,CAgDpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAelE"}

package/dist/tool/utils/port-utils.js

@@ -0,0 +1,128 @@
+/**
+ * Port utilities for normalizing and documenting ports
+ */
+/**
+ * Normalize a port entry (number or PortMetadata) to NormalizedPort format
+ */
+export function normalizePort(port, offset, overlayId) {
+    if (typeof port === 'number') {
+        // Legacy format - just a number
+        return {
+            port,
+            actualPort: port + offset,
+            service: overlayId,
+        };
+    }
+    // Rich format - already an object
+    return {
+        ...port,
+        actualPort: port.port + offset,
+        service: port.service || overlayId,
+    };
+}
+/**
+ * Generate connection string from template
+ */
+export function generateConnectionString(template, port, envVars = {}) {
+    let result = template;
+    // Replace port placeholder
+    result = result.replace(/\{port\}/g, String(port.actualPort));
+    // Replace other placeholders from environment variables or port metadata
+    const replacements = {
+        host: 'localhost',
+        service: port.service || 'unknown',
+        path: port.path || '',
+        ...envVars,
+    };
+    for (const [key, value] of Object.entries(replacements)) {
+        const regex = new RegExp(`\\{${key}\\}`, 'g');
+        result = result.replace(regex, value);
+    }
+    return result;
+}
+/**
+ * Get default connection string template for common services
+ */
+export function getDefaultConnectionStringTemplate(service, protocol) {
+    const templates = {
+        postgres: 'postgresql://{user}:{password}@{host}:{port}/{database}',
+        postgresql: 'postgresql://{user}:{password}@{host}:{port}/{database}',
+        mysql: 'mysql://{user}:{password}@{host}:{port}/{database}',
+        mongodb: 'mongodb://{user}:{password}@{host}:{port}/{database}',
+        redis: 'redis://{host}:{port}',
+        rabbitmq: 'amqp://{user}:{password}@{host}:{port}',
+        nats: 'nats://{host}:{port}',
+    };
+    // For HTTP/HTTPS services, use URL format
+    if (protocol === 'http' || protocol === 'https') {
+        return `${protocol}://{host}:{port}{path}`;
+    }
+    return templates[service.toLowerCase()];
+}
+/**
+ * Generate URL for HTTP/HTTPS services
+ */
+export function generateUrl(port) {
+    if (port.protocol === 'http' || port.protocol === 'https') {
+        const path = port.path || '';
+        return `${port.protocol}://localhost:${port.actualPort}${path}`;
+    }
+    return undefined;
+}
+/**
+ * Generate ports documentation from overlays
+ */
+export function generatePortsDocumentation(overlays, portOffset, envVars = {}) {
+    const allPorts = [];
+    const connectionStrings = {};
+    for (const overlay of overlays) {
+        if (!overlay.ports || overlay.ports.length === 0) {
+            continue;
+        }
+        for (const portEntry of overlay.ports) {
+            const normalizedPort = normalizePort(portEntry, portOffset, overlay.id);
+            allPorts.push(normalizedPort);
+            // Generate connection string if template is provided or can be inferred
+            const template = typeof portEntry === 'object' && portEntry.connectionStringTemplate
+                ? portEntry.connectionStringTemplate
+                : getDefaultConnectionStringTemplate(normalizedPort.service || '', normalizedPort.protocol);
+            if (template) {
+                const connStr = generateConnectionString(template, normalizedPort, envVars);
+                // Use unique key for multi-port services by appending port number if service already exists
+                let key = normalizedPort.service || `port-${normalizedPort.port}`;
+                // If key already exists, make it unique by adding port number
+                if (connectionStrings[key]) {
+                    key = `${key}-${normalizedPort.port}`;
+                }
+                connectionStrings[key] = connStr;
+            }
+            // Generate URL for HTTP/HTTPS services
+            const url = generateUrl(normalizedPort);
+            if (url && normalizedPort.service) {
+                connectionStrings[`${normalizedPort.service}-url`] = url;
+            }
+        }
+    }
+    return {
+        portOffset,
+        ports: allPorts,
+        connectionStrings,
+    };
+}
+/**
+ * Extract all unique ports from overlays (for offset calculation)
+ */
+export function extractPorts(overlays) {
+    const ports = new Set();
+    for (const overlay of overlays) {
+        if (!overlay.ports) {
+            continue;
+        }
+        for (const portEntry of overlay.ports) {
+            const port = typeof portEntry === 'number' ? portEntry : portEntry.port;
+            ports.add(port);
+        }
+    }
+    return Array.from(ports).sort((a, b) => a - b);
+}
+//# sourceMappingURL=port-utils.js.map

package/dist/tool/utils/port-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-utils.js","sourceRoot":"","sources":["../../../tool/utils/port-utils.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