container-superposition 0.1.1 → 0.1.4

package/dist/tool/questionnaire/composer.js

@@ -6,6 +6,13 @@ import * as yaml from 'js-yaml';
 import { loadOverlaysConfig } from '../schema/overlay-loader.js';
 import { loadCustomPatches, hasCustomDirectory, getCustomScriptPaths, } from '../schema/custom-loader.js';
 import { generateReadme } from '../readme/readme-generator.js';
+import { CURRENT_MANIFEST_VERSION } from '../schema/manifest-migrations.js';
+import { getToolVersion } from '../utils/version.js';
+import { deepMerge, mergePackages, filterDependsOn, applyPortOffsetToEnv, } from '../utils/merge.js';
+import { generatePortsDocumentation } from '../utils/port-utils.js';
+import { generateServicesMarkdown, generateEnvLocalExample } from '../utils/services-export.js';
+import { appendGitignoreSection } from '../utils/gitignore.js';
+import { detectWarnings, generateTips, generateNextSteps, overlaysToServices, portsToPortInfo, } from '../utils/summary.js';
 // Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -19,92 +26,6 @@ const REPO_ROOT_CANDIDATES = [
 const REPO_ROOT = REPO_ROOT_CANDIDATES.find((candidate) => fs.existsSync(path.join(candidate, 'templates')) &&
     fs.existsSync(path.join(candidate, 'overlays'))) ?? REPO_ROOT_CANDIDATES[0];
 const TEMPLATES_DIR = path.join(REPO_ROOT, 'templates');
-const OVERLAYS_DIR = path.join(REPO_ROOT, 'overlays');
-/**
- * Deep merge two objects, with special handling for arrays
- */
-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
-                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 {
-                output[key] = deepMerge(target[key], source[key]);
-            }
-        }
-        else {
-            output[key] = source[key];
-        }
-    }
-    return output;
-}
-/**
- * Split PATH string on colons, but preserve ${...} variable references
- * e.g., "${containerEnv:HOME}/bin:${containerEnv:PATH}" -> ["${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 special handling for PATH variables
- */
-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 packages from apt-get-packages feature
  */
@@ -118,10 +39,7 @@ function mergeAptPackages(baseConfig, packages) {
     }
     else {
         const existing = baseConfig.features[featureKey].packages || '';
-        // Filter out empty tokens from split to avoid leading spaces
-        const existingPackages = existing.split(' ').filter((p) => p);
-        const newPackages = packages.split(' ').filter((p) => p);
-        const merged = [...new Set([...existingPackages, ...newPackages])].join(' ');
+        const merged = mergePackages(existing, packages);
         baseConfig.features[featureKey].packages = merged;
     }
     return baseConfig;
@@ -140,17 +58,13 @@ function mergeCrossDistroPackages(baseConfig, apt, apk) {
     // Merge apt packages
     if (apt) {
         const existing = baseConfig.features[featureKey].apt || '';
-        const existingPackages = existing.split(' ').filter((p) => p);
-        const newPackages = apt.split(' ').filter((p) => p);
-        const merged = [...new Set([...existingPackages, ...newPackages])].join(' ');
+        const merged = mergePackages(existing, apt);
         baseConfig.features[featureKey].apt = merged;
     }
     // Merge apk packages
     if (apk) {
         const existing = baseConfig.features[featureKey].apk || '';
-        const existingPackages = existing.split(' ').filter((p) => p);
-        const newPackages = apk.split(' ').filter((p) => p);
-        const merged = [...new Set([...existingPackages, ...newPackages])].join(' ');
+        const merged = mergePackages(existing, apk);
         baseConfig.features[featureKey].apk = merged;
     }
     return baseConfig;
@@ -226,12 +140,108 @@ function resolveDependencies(requestedOverlays, allOverlayDefs) {
         },
     };
 }
+/**
+ * Prepare overlays for generation by loading configuration, building requested overlay list,
+ * filtering for minimal mode, checking compatibility, and resolving dependencies.
+ * This shared logic is used by both generateManifestOnly and composeDevContainer.
+ */
+function prepareOverlaysForGeneration(answers, overlaysDir) {
+    // 1. Load overlay configuration
+    const actualOverlaysDir = overlaysDir ?? path.join(REPO_ROOT, 'overlays');
+    const indexYmlPath = path.join(actualOverlaysDir, 'index.yml');
+    const overlaysConfig = loadOverlaysConfig(actualOverlaysDir, indexYmlPath);
+    // Collect all overlay definitions
+    const allOverlayDefs = getAllOverlayDefs(overlaysConfig);
+    // Build list of requested overlays
+    const requestedOverlays = [];
+    if (answers.language && answers.language.length > 0)
+        requestedOverlays.push(...answers.language);
+    if (answers.database && answers.database.length > 0)
+        requestedOverlays.push(...answers.database);
+    if (answers.observability)
+        requestedOverlays.push(...answers.observability);
+    if (answers.playwright)
+        requestedOverlays.push('playwright');
+    if (answers.cloudTools)
+        requestedOverlays.push(...answers.cloudTools);
+    if (answers.devTools)
+        requestedOverlays.push(...answers.devTools);
+    // Filter out "minimal" overlays if --minimal flag is set
+    let filteredRequestedOverlays = requestedOverlays;
+    if (answers.minimal) {
+        const minimalExcluded = [];
+        filteredRequestedOverlays = requestedOverlays.filter((overlayId) => {
+            const overlayDef = allOverlayDefs.find((o) => o.id === overlayId);
+            if (overlayDef?.minimal === true) {
+                minimalExcluded.push(overlayId);
+                return false;
+            }
+            return true;
+        });
+        if (minimalExcluded.length > 0) {
+            console.log(chalk.dim(`   📦 Minimal mode: Excluding ${minimalExcluded.length} optional overlay(s): ${minimalExcluded.join(', ')}`));
+        }
+    }
+    // Check compatibility
+    const incompatible = [];
+    for (const overlayId of filteredRequestedOverlays) {
+        const overlayDef = allOverlayDefs.find((o) => o.id === overlayId);
+        if (overlayDef?.supports && overlayDef.supports.length > 0) {
+            if (!overlayDef.supports.includes(answers.stack)) {
+                incompatible.push(`${overlayId} (requires: ${overlayDef.supports.join(', ')})`);
+            }
+        }
+    }
+    if (incompatible.length > 0) {
+        console.log(chalk.yellow(`\n⚠️  Warning: Some overlays are not compatible with '${answers.stack}' template:`));
+        incompatible.forEach((overlay) => {
+            console.log(chalk.yellow(`   • ${overlay}`));
+        });
+        console.log(chalk.yellow(`\nThese overlays will be skipped.\n`));
+        // Filter out incompatible overlays
+        if (answers.database) {
+            answers.database = answers.database.filter((d) => !incompatible.some((i) => i.startsWith(d)));
+        }
+        if (answers.observability) {
+            answers.observability = answers.observability.filter((o) => !incompatible.some((i) => i.startsWith(o)));
+        }
+        // Update requestedOverlays after filtering
+        requestedOverlays.length = 0;
+        if (answers.language && answers.language.length > 0)
+            requestedOverlays.push(...answers.language);
+        if (answers.database && answers.database.length > 0)
+            requestedOverlays.push(...answers.database);
+        if (answers.observability)
+            requestedOverlays.push(...answers.observability);
+        if (answers.playwright)
+            requestedOverlays.push('playwright');
+        if (answers.cloudTools)
+            requestedOverlays.push(...answers.cloudTools);
+        if (answers.devTools)
+            requestedOverlays.push(...answers.devTools);
+        // Re-apply minimal filtering
+        filteredRequestedOverlays = requestedOverlays.filter((overlayId) => {
+            const overlayDef = allOverlayDefs.find((o) => o.id === overlayId);
+            return !answers.minimal || overlayDef?.minimal !== true;
+        });
+    }
+    // Resolve dependencies
+    const { overlays: resolvedOverlays, autoResolved } = resolveDependencies(filteredRequestedOverlays, allOverlayDefs);
+    return {
+        overlays: resolvedOverlays,
+        autoResolved,
+        overlaysConfig,
+    };
+}
 /**
  * Generate superposition.json manifest
  */
 function generateManifest(outputPath, answers, overlays, autoResolved, containerName) {
+    const toolVersion = getToolVersion();
     const manifest = {
-        version: '0.1.0',
+        manifestVersion: CURRENT_MANIFEST_VERSION,
+        generatedBy: toolVersion,
+        version: '0.1.0', // Legacy field for backward compatibility
         generated: new Date().toISOString(),
         baseTemplate: answers.stack,
         baseImage: answers.baseImage === 'custom' && answers.customImage
@@ -265,15 +275,74 @@ function generateManifest(outputPath, answers, overlays, autoResolved, container
         console.log(chalk.cyan(`   ℹ️  Used preset: ${answers.preset}`));
     }
 }
+/**
+ * Load and resolve imports from shared files for an overlay
+ */
+function loadImportsForOverlay(overlayName, overlaysDir) {
+    let importedConfig = {};
+    // Load overlay manifest to get imports
+    const overlayDir = path.join(overlaysDir, overlayName);
+    const manifestPath = path.join(overlayDir, 'overlay.yml');
+    if (!fs.existsSync(manifestPath)) {
+        return importedConfig;
+    }
+    try {
+        const manifestContent = fs.readFileSync(manifestPath, 'utf8');
+        const manifest = yaml.load(manifestContent);
+        if (!manifest.imports ||
+            !Array.isArray(manifest.imports) ||
+            manifest.imports.length === 0) {
+            return importedConfig;
+        }
+        // Process each import
+        for (const importPath of manifest.imports) {
+            const fullImportPath = path.join(overlaysDir, importPath);
+            if (!fs.existsSync(fullImportPath)) {
+                console.warn(chalk.yellow(`⚠️  Import not found: ${importPath} (for overlay: ${overlayName})`));
+                continue;
+            }
+            // Determine file type and merge appropriately
+            const ext = path.extname(importPath).toLowerCase();
+            if (ext === '.json') {
+                // JSON files are merged as devcontainer patches
+                const importedPatch = loadJson(fullImportPath);
+                importedConfig = deepMerge(importedConfig, importedPatch);
+            }
+            else if (ext === '.yaml' || ext === '.yml') {
+                // YAML files are loaded and merged as devcontainer patches
+                try {
+                    const yamlContent = fs.readFileSync(fullImportPath, 'utf8');
+                    const importedPatch = yaml.load(yamlContent);
+                    if (importedPatch && typeof importedPatch === 'object') {
+                        importedConfig = deepMerge(importedConfig, importedPatch);
+                    }
+                }
+                catch (error) {
+                    console.warn(chalk.yellow(`⚠️  Failed to parse YAML import: ${importPath}`));
+                }
+            }
+            // .env files are handled separately during env merging
+        }
+    }
+    catch (error) {
+        console.warn(chalk.yellow(`⚠️  Failed to load imports for overlay: ${overlayName}`));
+    }
+    return importedConfig;
+}
 /**
  * Apply an overlay to the base configuration
  */
-function applyOverlay(baseConfig, overlayName) {
-    const overlayPath = path.join(OVERLAYS_DIR, overlayName, 'devcontainer.patch.json');
+export function applyOverlay(baseConfig, overlayName, overlaysDir) {
+    const overlayPath = path.join(overlaysDir, overlayName, 'devcontainer.patch.json');
     if (!fs.existsSync(overlayPath)) {
         console.warn(chalk.yellow(`⚠️  Overlay not found: ${overlayName}`));
         return baseConfig;
     }
+    // First, load and apply any imports
+    const importedConfig = loadImportsForOverlay(overlayName, overlaysDir);
+    if (Object.keys(importedConfig).length > 0) {
+        baseConfig = deepMerge(baseConfig, importedConfig);
+    }
     const overlay = loadJson(overlayPath);
     // Special handling for apt-get packages (legacy)
     if (overlay.features?.['ghcr.io/devcontainers-extra/features/apt-get-packages:1']?.packages) {
@@ -378,20 +447,21 @@ function copyDir(src, dest) {
  * Copy additional files from overlay to output directory
  * Excludes devcontainer.patch.json and .env.example (handled separately)
  */
-function copyOverlayFiles(outputPath, overlayName, registry) {
-    const overlayPath = path.join(OVERLAYS_DIR, overlayName);
+function copyOverlayFiles(outputPath, overlayName, registry, overlaysDir) {
+    const overlayPath = path.join(overlaysDir, overlayName);
     if (!fs.existsSync(overlayPath)) {
         return;
     }
     const entries = fs.readdirSync(overlayPath);
     let copiedFiles = 0;
     for (const entry of entries) {
-        // Skip devcontainer.patch.json, .env.example, docker-compose.yml, setup.sh, verify.sh, and metadata files (handled separately)
+        // Skip devcontainer.patch.json, .env.example, docker-compose.yml, setup.sh, verify.sh, .gitignore, and metadata files (handled separately)
         if (entry === 'devcontainer.patch.json' ||
             entry === '.env.example' ||
             entry === 'docker-compose.yml' ||
             entry === 'setup.sh' ||
             entry === 'verify.sh' ||
+            entry === '.gitignore' ||
             entry === 'README.md' ||
             entry === 'overlay.yml') {
             continue;
@@ -428,10 +498,37 @@ function copyOverlayFiles(outputPath, overlayName, registry) {
 /**
  * Merge .env.example files from overlays and apply glue config
  */
-function mergeEnvExamples(outputPath, overlays, portOffset, glueConfig, presetName) {
+function mergeEnvExamples(outputPath, overlays, overlaysDir, portOffset, glueConfig, presetName) {
     const envSections = [];
     for (const overlay of overlays) {
-        const envPath = path.join(OVERLAYS_DIR, overlay, '.env.example');
+        // First, check for imports in the overlay and add any .env files from imports
+        const overlayDir = path.join(overlaysDir, overlay);
+        const manifestPath = path.join(overlayDir, 'overlay.yml');
+        if (fs.existsSync(manifestPath)) {
+            try {
+                const manifestContent = fs.readFileSync(manifestPath, 'utf8');
+                const manifest = yaml.load(manifestContent);
+                if (manifest.imports && Array.isArray(manifest.imports)) {
+                    for (const importPath of manifest.imports) {
+                        const ext = path.extname(importPath).toLowerCase();
+                        if (ext === '.env') {
+                            const fullImportPath = path.join(overlaysDir, importPath);
+                            if (fs.existsSync(fullImportPath)) {
+                                const content = fs.readFileSync(fullImportPath, 'utf-8').trim();
+                                if (content) {
+                                    envSections.push(`# Imported from ${importPath}\n${content}`);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                // Ignore errors reading manifest
+            }
+        }
+        // Then add the overlay's own .env.example
+        const envPath = path.join(overlaysDir, overlay, '.env.example');
         if (fs.existsSync(envPath)) {
             const content = fs.readFileSync(envPath, 'utf-8').trim();
             if (content) {
@@ -479,21 +576,42 @@ function mergeEnvExamples(outputPath, overlays, portOffset, glueConfig, presetNa
     return true;
 }
 /**
- * Apply port offset to environment variables in .env content
+ * Merge .gitignore files from overlays into the project root .gitignore.
+ * Writes to path.dirname(outputPath) — the project root (parent of .devcontainer/).
+ * Only appends entries not already present; safe to run multiple times.
+ * Returns true if any entries were written.
  */
-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');
+function mergeGitignoreFiles(outputPath, overlays, overlaysDir) {
+    const projectRoot = path.dirname(path.resolve(outputPath));
+    const destPath = path.join(projectRoot, '.gitignore');
+    let anyWritten = false;
+    let sectionsWritten = 0;
+    for (const overlay of overlays) {
+        const gitignorePath = path.join(overlaysDir, overlay, '.gitignore');
+        if (!fs.existsSync(gitignorePath))
+            continue;
+        const content = fs.readFileSync(gitignorePath, 'utf-8').trim();
+        if (!content)
+            continue;
+        const lines = content
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0 && !l.startsWith('#'));
+        if (lines.length === 0)
+            continue;
+        const written = appendGitignoreSection(destPath, `${overlay} (container-superposition)`, lines);
+        if (written) {
+            anyWritten = true;
+            sectionsWritten++;
+        }
+    }
+    if (anyWritten) {
+        console.log(chalk.dim(`   📄 Updated .gitignore with entries from ${sectionsWritten} overlay(s)`));
+    }
+    else {
+        console.log(chalk.dim(`   📄 .gitignore already up to date`));
+    }
+    return anyWritten;
 }
 /**
  * Apply preset glue configuration (README and port mappings)
@@ -526,7 +644,7 @@ function applyGlueConfig(outputPath, glueConfig, presetName, fileRegistry) {
 /**
  * Merge docker-compose.yml files from base and overlays into a single file
  */
-function mergeDockerComposeFiles(outputPath, baseStack, overlays, portOffset, customImage) {
+function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, portOffset, customImage) {
     const composeFiles = [];
     // Add base docker-compose if exists
     const baseComposePath = path.join(TEMPLATES_DIR, baseStack, '.devcontainer', 'docker-compose.yml');
@@ -535,7 +653,7 @@ function mergeDockerComposeFiles(outputPath, baseStack, overlays, portOffset, cu
     }
     // Add overlay docker-compose files
     for (const overlay of overlays) {
-        const overlayComposePath = path.join(OVERLAYS_DIR, overlay, 'docker-compose.yml');
+        const overlayComposePath = path.join(overlaysDir, overlay, 'docker-compose.yml');
         if (fs.existsSync(overlayComposePath)) {
             composeFiles.push(overlayComposePath);
         }
@@ -583,13 +701,17 @@ function mergeDockerComposeFiles(outputPath, baseStack, overlays, portOffset, cu
     }
     // Filter depends_on to only include services that exist
     const serviceNames = Object.keys(merged.services);
+    const serviceNameSet = new Set(serviceNames);
     for (const serviceName of serviceNames) {
         const service = merged.services[serviceName];
-        if (service.depends_on && Array.isArray(service.depends_on)) {
-            service.depends_on = service.depends_on.filter((dep) => serviceNames.includes(dep));
-            if (service.depends_on.length === 0) {
+        if (service.depends_on !== undefined) {
+            const filteredDependsOn = filterDependsOn(service.depends_on, serviceNameSet);
+            if (filteredDependsOn === undefined) {
                 delete service.depends_on;
             }
+            else {
+                service.depends_on = filteredDependsOn;
+            }
         }
     }
     // Remove empty sections
@@ -800,71 +922,61 @@ function copyCustomFiles(customConfig, outputPath, fileRegistry) {
         fileRegistry.addFile(relativeDest);
     }
 }
+/**
+ * Generate only the superposition.json manifest without creating .devcontainer files
+ * Used for team collaboration workflow where manifest is committed but .devcontainer is gitignored
+ */
+export async function generateManifestOnly(answers, overlaysDir, options = {}) {
+    // Prepare overlays using shared logic
+    const { overlays: resolvedOverlays, autoResolved } = prepareOverlaysForGeneration(answers, overlaysDir);
+    // Ensure output directory exists
+    const outputPath = answers.outputPath || '.';
+    if (!fs.existsSync(outputPath)) {
+        fs.mkdirSync(outputPath, { recursive: true });
+    }
+    // Generate manifest only
+    console.log(chalk.cyan('\n📋 Generating manifest only (team collaboration mode)...\n'));
+    generateManifest(outputPath, answers, resolvedOverlays, autoResolved, answers.containerName);
+    console.log(chalk.green(`\n✓ Manifest created: ${path.join(outputPath, 'superposition.json')}`));
+    console.log(chalk.dim('  Ready for team collaboration workflow.'));
+    console.log(chalk.dim('  Commit this manifest to your repository and let team members run "npx container-superposition regen"'));
+    // Load overlay configs to get metadata
+    const actualOverlaysDir = overlaysDir ?? path.join(REPO_ROOT, 'overlays');
+    const indexYmlPath = path.join(actualOverlaysDir, 'index.yml');
+    const overlaysConfig = loadOverlaysConfig(actualOverlaysDir, indexYmlPath);
+    const allOverlayDefs = getAllOverlayDefs(overlaysConfig);
+    const overlayMetadataMap = new Map(allOverlayDefs.map((o) => [o.id, o]));
+    const selectedOverlayMetadata = resolvedOverlays
+        .map((id) => overlayMetadataMap.get(id))
+        .filter((m) => m !== undefined);
+    // Return summary for manifest-only mode
+    const services = overlaysToServices(selectedOverlayMetadata);
+    const warnings = detectWarnings(selectedOverlayMetadata, answers);
+    const tips = generateTips(selectedOverlayMetadata, answers);
+    const nextSteps = generateNextSteps(true, options.isRegen === true);
+    return {
+        files: ['superposition.json'],
+        services,
+        ports: [],
+        warnings,
+        tips,
+        nextSteps,
+        portOffset: answers.portOffset ?? 0,
+        target: answers.target || 'local',
+        isManifestOnly: true,
+        manifestPath: path.join(outputPath, 'superposition.json'),
+    };
+}
 /**
  * Main composition logic
  */
-export async function composeDevContainer(answers) {
-    // 1. Load overlay configuration
-    const overlaysDir = path.join(REPO_ROOT, 'overlays');
-    const indexYmlPath = path.join(REPO_ROOT, 'overlays', 'index.yml');
-    const overlaysConfig = loadOverlaysConfig(overlaysDir, indexYmlPath);
-    // Collect all overlay definitions
+export async function composeDevContainer(answers, overlaysDir, options = {}) {
+    // Prepare overlays using shared logic
+    const actualOverlaysDir = overlaysDir ?? path.join(REPO_ROOT, 'overlays');
+    const { overlays: resolvedOverlays, autoResolved, overlaysConfig, } = prepareOverlaysForGeneration(answers, overlaysDir);
+    // Get all overlay definitions for later use
     const allOverlayDefs = getAllOverlayDefs(overlaysConfig);
-    // Build list of requested overlays
-    const requestedOverlays = [];
-    if (answers.language && answers.language.length > 0)
-        requestedOverlays.push(...answers.language);
-    if (answers.database && answers.database.length > 0)
-        requestedOverlays.push(...answers.database);
-    if (answers.observability)
-        requestedOverlays.push(...answers.observability);
-    if (answers.playwright)
-        requestedOverlays.push('playwright');
-    if (answers.cloudTools)
-        requestedOverlays.push(...answers.cloudTools);
-    if (answers.devTools)
-        requestedOverlays.push(...answers.devTools);
-    // Check compatibility
-    const incompatible = [];
-    for (const overlayId of requestedOverlays) {
-        const overlayDef = allOverlayDefs.find((o) => o.id === overlayId);
-        if (overlayDef?.supports && overlayDef.supports.length > 0) {
-            if (!overlayDef.supports.includes(answers.stack)) {
-                incompatible.push(`${overlayId} (requires: ${overlayDef.supports.join(', ')})`);
-            }
-        }
-    }
-    if (incompatible.length > 0) {
-        console.log(chalk.yellow(`\n⚠️  Warning: Some overlays are not compatible with '${answers.stack}' template:`));
-        incompatible.forEach((overlay) => {
-            console.log(chalk.yellow(`   • ${overlay}`));
-        });
-        console.log(chalk.yellow(`\nThese overlays will be skipped.\n`));
-        // Filter out incompatible overlays
-        if (answers.database) {
-            answers.database = answers.database.filter((d) => !incompatible.some((i) => i.startsWith(d)));
-        }
-        if (answers.observability) {
-            answers.observability = answers.observability.filter((o) => !incompatible.some((i) => i.startsWith(o)));
-        }
-        // Update requestedOverlays after filtering
-        requestedOverlays.length = 0;
-        if (answers.language && answers.language.length > 0)
-            requestedOverlays.push(...answers.language);
-        if (answers.database && answers.database.length > 0)
-            requestedOverlays.push(...answers.database);
-        if (answers.observability)
-            requestedOverlays.push(...answers.observability);
-        if (answers.playwright)
-            requestedOverlays.push('playwright');
-        if (answers.cloudTools)
-            requestedOverlays.push(...answers.cloudTools);
-        if (answers.devTools)
-            requestedOverlays.push(...answers.devTools);
-    }
-    // 2. Resolve dependencies
-    const { overlays: resolvedOverlays, autoResolved } = resolveDependencies(requestedOverlays, allOverlayDefs);
-    // 3. Determine base template path
+    // Determine base template path
     const templatePath = path.join(TEMPLATES_DIR, answers.stack, '.devcontainer');
     if (!fs.existsSync(templatePath)) {
         throw new Error(`Template not found: ${answers.stack}`);
@@ -946,7 +1058,7 @@ export async function composeDevContainer(answers) {
     // 6. Apply overlays
     for (const overlay of overlays) {
         console.log(chalk.dim(`   🔧 Applying overlay: ${chalk.cyan(overlay)}`));
-        config = applyOverlay(config, overlay);
+        config = applyOverlay(config, overlay, actualOverlaysDir);
     }
     // 7. Copy template files (docker-compose, scripts, etc.)
     const entries = fs.readdirSync(templatePath);
@@ -967,7 +1079,7 @@ export async function composeDevContainer(answers) {
     }
     // 8. Copy overlay files (docker-compose, configs, etc.)
     for (const overlay of overlays) {
-        copyOverlayFiles(outputPath, overlay, fileRegistry);
+        copyOverlayFiles(outputPath, overlay, fileRegistry, actualOverlaysDir);
     }
     // 8.5. Copy cross-distro-packages feature if used
     if (config.features?.['./features/cross-distro-packages']) {
@@ -982,11 +1094,11 @@ export async function composeDevContainer(answers) {
     // 8. Filter docker-compose dependencies based on selected overlays
     filterDockerComposeDependencies(outputPath, overlays);
     // 9. Merge runServices array in correct order
-    mergeRunServices(config, overlays);
+    mergeRunServices(config, overlays, actualOverlaysDir);
     // 11. Merge docker-compose files into single combined file
     if (answers.stack === 'compose') {
         const customImage = config._customImage;
-        mergeDockerComposeFiles(outputPath, answers.stack, overlays, answers.portOffset, customImage);
+        mergeDockerComposeFiles(outputPath, answers.stack, overlays, actualOverlaysDir, answers.portOffset, customImage);
         // Update devcontainer.json to reference the combined file
         if (config.dockerComposeFile) {
             config.dockerComposeFile = 'docker-compose.yml';
@@ -997,7 +1109,7 @@ export async function composeDevContainer(answers) {
         applyPortOffsetToDevcontainer(config, answers.portOffset);
     }
     // Merge setup scripts from overlays into postCreateCommand
-    mergeSetupScripts(config, overlays, outputPath, fileRegistry);
+    mergeSetupScripts(config, overlays, outputPath, fileRegistry, actualOverlaysDir);
     // 10. Apply custom patches from .devcontainer/custom/ (if present)
     const customPatches = loadCustomPatches(outputPath);
     if (customPatches) {
@@ -1015,6 +1127,25 @@ export async function composeDevContainer(answers) {
             delete config[key];
         }
     });
+    // Handle editor profile filtering
+    if (answers.editor === 'none' || answers.editor === 'jetbrains') {
+        // Remove VS Code customizations
+        if (config.customizations?.vscode) {
+            if (answers.editor === 'none') {
+                delete config.customizations.vscode;
+                console.log(chalk.dim(`   🎨 Editor profile 'none': Removed VS Code customizations`));
+            }
+            else if (answers.editor === 'jetbrains') {
+                // For JetBrains, remove VS Code customizations (future: could add JetBrains-specific settings)
+                delete config.customizations.vscode;
+                console.log(chalk.dim(`   🎨 Editor profile 'jetbrains': Removed VS Code customizations`));
+            }
+            // Clean up empty customizations object
+            if (config.customizations && Object.keys(config.customizations).length === 0) {
+                delete config.customizations;
+            }
+        }
+    }
     // 12. Write merged devcontainer.json
     const configPath = path.join(outputPath, 'devcontainer.json');
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
@@ -1028,7 +1159,7 @@ export async function composeDevContainer(answers) {
     generateManifest(outputPath, answers, overlays, autoResolved, answers.containerName || config.name);
     fileRegistry.addFile('superposition.json');
     // 14. Merge .env.example files from overlays and apply glue config environment variables
-    const envCreated = mergeEnvExamples(outputPath, overlays, answers.portOffset, answers.presetGlueConfig, answers.preset);
+    const envCreated = mergeEnvExamples(outputPath, overlays, actualOverlaysDir, answers.portOffset, answers.presetGlueConfig, answers.preset);
     if (envCreated) {
         fileRegistry.addFile('.env.example');
     }
@@ -1040,6 +1171,10 @@ export async function composeDevContainer(answers) {
             fileRegistry.addFile('.env.example');
         }
     }
+    // 14b. Merge .gitignore files from overlays into project root .gitignore
+    // Note: .gitignore lives at the project root (parent of outputPath), not inside outputPath,
+    // so it is intentionally NOT added to fileRegistry (cleanupStaleFiles must not touch it).
+    mergeGitignoreFiles(outputPath, overlays, actualOverlaysDir);
     // 15. Apply preset glue configuration (README and port mappings) if present
     if (answers.presetGlueConfig) {
         applyGlueConfig(outputPath, answers.presetGlueConfig, answers.preset, fileRegistry);
@@ -1050,8 +1185,84 @@ export async function composeDevContainer(answers) {
     generateReadme(answers, overlays, overlayMetadataMap, outputPath);
     fileRegistry.addFile('README.md');
     console.log(chalk.dim(`   📝 Created README.md with documentation from ${overlays.length} overlay(s)`));
-    // 17. Clean up stale files from previous runs (preserves superposition.json and .env)
+    // 17. Generate ports.json documentation
+    const portOffset = answers.portOffset ?? 0;
+    // Prepare overlay metadata for summary
+    const selectedOverlayMetadata = overlays
+        .map((id) => overlayMetadataMap.get(id))
+        .filter((m) => m !== undefined);
+    // Extract environment variables from .env.example for connection strings
+    const envPath = path.join(outputPath, '.env.example');
+    const envVars = {};
+    if (fs.existsSync(envPath)) {
+        const envContent = fs.readFileSync(envPath, 'utf8');
+        for (const line of envContent.split('\n')) {
+            const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+            if (match) {
+                envVars[match[1].toLowerCase()] = match[2];
+            }
+        }
+    }
+    const hasOverlayPorts = overlays.some((o) => overlayMetadataMap.get(o)?.ports?.length);
+    const shouldGeneratePortsDocumentation = portOffset > 0 || hasOverlayPorts;
+    let portsDoc = null;
+    if (shouldGeneratePortsDocumentation) {
+        console.log(chalk.cyan('\n📡 Generating ports documentation...'));
+        portsDoc = generatePortsDocumentation(selectedOverlayMetadata, portOffset, envVars);
+        const portsPath = path.join(outputPath, 'ports.json');
+        fs.writeFileSync(portsPath, JSON.stringify(portsDoc, null, 2) + '\n');
+        fileRegistry.addFile('ports.json');
+        console.log(chalk.dim(`   📡 Created ports.json with ${portsDoc.ports.length} port(s)`));
+        // Log summary of ports
+        if (portsDoc.ports.length > 0) {
+            console.log(chalk.dim('\n   Available services:'));
+            for (const port of portsDoc.ports) {
+                const serviceLabel = port.service || 'unknown';
+                const desc = port.description ? ` - ${port.description}` : '';
+                const proto = port.protocol ? ` (${port.protocol})` : '';
+                console.log(chalk.dim(`   • ${serviceLabel}: ${port.actualPort}${proto}${desc}`));
+            }
+        }
+    }
+    // 17b. Generate services.md reference document
+    const servicesMdContent = generateServicesMarkdown(selectedOverlayMetadata, portOffset, envVars);
+    if (servicesMdContent) {
+        const servicesMdPath = path.join(outputPath, 'services.md');
+        fs.writeFileSync(servicesMdPath, servicesMdContent);
+        fileRegistry.addFile('services.md');
+        console.log(chalk.dim(`   📋 Created services.md with service reference`));
+    }
+    // 17c. Generate env.local.example as an optional-overrides template
+    const envLocalContent = generateEnvLocalExample(selectedOverlayMetadata, actualOverlaysDir, portOffset);
+    if (envLocalContent) {
+        const envLocalPath = path.join(outputPath, 'env.local.example');
+        fs.writeFileSync(envLocalPath, envLocalContent);
+        fileRegistry.addFile('env.local.example');
+        console.log(chalk.dim(`   📄 Created env.local.example with optional overrides`));
+    }
+    // 18. Clean up stale files from previous runs (preserves superposition.json and .env)
     cleanupStaleFiles(outputPath, fileRegistry);
+    // 19. Generate and return summary
+    const files = Array.from(fileRegistry.getFiles());
+    const services = overlaysToServices(selectedOverlayMetadata);
+    const portInfos = portsDoc
+        ? portsToPortInfo(portsDoc.ports, portsDoc.connectionStrings || {})
+        : [];
+    const warnings = detectWarnings(selectedOverlayMetadata, answers);
+    const tips = generateTips(selectedOverlayMetadata, answers);
+    const nextSteps = generateNextSteps(false, options.isRegen === true);
+    return {
+        files,
+        services,
+        ports: portInfos,
+        warnings,
+        tips,
+        nextSteps,
+        portOffset: answers.portOffset ?? 0,
+        target: answers.target || 'local',
+        isManifestOnly: false,
+        manifestPath: path.join(outputPath, 'superposition.json'),
+    };
 }
 /**
  * Apply port offset to devcontainer.json forwardPorts and portsAttributes
@@ -1084,7 +1295,7 @@ function applyPortOffsetToDevcontainer(config, offset) {
 /**
  * Merge setup scripts from overlays into postCreateCommand
  */
-function mergeSetupScripts(config, overlays, outputPath, fileRegistry) {
+function mergeSetupScripts(config, overlays, outputPath, fileRegistry, overlaysDir) {
     const setupScripts = [];
     const verifyScripts = [];
     // Create scripts subfolder
@@ -1093,14 +1304,14 @@ function mergeSetupScripts(config, overlays, outputPath, fileRegistry) {
         fs.mkdirSync(scriptsDir, { recursive: true });
     }
     // Add scripts directory to registry if any scripts will be added
-    const hasScripts = overlays.some((o) => fs.existsSync(path.join(OVERLAYS_DIR, o, 'setup.sh')) ||
-        fs.existsSync(path.join(OVERLAYS_DIR, o, 'verify.sh')));
+    const hasScripts = overlays.some((o) => fs.existsSync(path.join(overlaysDir, o, 'setup.sh')) ||
+        fs.existsSync(path.join(overlaysDir, o, 'verify.sh')));
     if (hasScripts) {
         fileRegistry.addDirectory('scripts');
     }
     for (const overlay of overlays) {
         // Handle setup scripts
-        const setupPath = path.join(OVERLAYS_DIR, overlay, 'setup.sh');
+        const setupPath = path.join(overlaysDir, overlay, 'setup.sh');
         if (fs.existsSync(setupPath)) {
             // Copy setup script to scripts subdirectory
             const destPath = path.join(scriptsDir, `setup-${overlay}.sh`);
@@ -1111,7 +1322,7 @@ function mergeSetupScripts(config, overlays, outputPath, fileRegistry) {
             setupScripts.push(`bash .devcontainer/scripts/setup-${overlay}.sh`);
         }
         // Handle verify scripts
-        const verifyPath = path.join(OVERLAYS_DIR, overlay, 'verify.sh');
+        const verifyPath = path.join(overlaysDir, overlay, 'verify.sh');
         if (fs.existsSync(verifyPath)) {
             // Copy verify script to scripts subdirectory
             const destPath = path.join(scriptsDir, `verify-${overlay}.sh`);
@@ -1134,7 +1345,7 @@ function mergeSetupScripts(config, overlays, outputPath, fileRegistry) {
         // Add setup scripts
         for (let i = 0; i < setupScripts.length; i++) {
             const overlay = overlays.filter((o) => {
-                const setupPath = path.join(OVERLAYS_DIR, o, 'setup.sh');
+                const setupPath = path.join(overlaysDir, o, 'setup.sh');
                 return fs.existsSync(setupPath);
             })[i];
             config.postCreateCommand[`setup-${overlay}`] = setupScripts[i];
@@ -1153,7 +1364,7 @@ function mergeSetupScripts(config, overlays, outputPath, fileRegistry) {
         // Add verify scripts
         for (let i = 0; i < verifyScripts.length; i++) {
             const overlay = overlays.filter((o) => {
-                const verifyPath = path.join(OVERLAYS_DIR, o, 'verify.sh');
+                const verifyPath = path.join(overlaysDir, o, 'verify.sh');
                 return fs.existsSync(verifyPath);
             })[i];
             config.postStartCommand[`verify-${overlay}`] = verifyScripts[i];
@@ -1208,10 +1419,10 @@ function filterDockerComposeDependencies(outputPath, selectedOverlays) {
 /**
  * Merge runServices from all overlays in correct order
  */
-function mergeRunServices(config, overlays) {
+function mergeRunServices(config, overlays, overlaysDir) {
     const services = [];
     for (const overlay of overlays) {
-        const overlayPath = path.join(OVERLAYS_DIR, overlay, 'devcontainer.patch.json');
+        const overlayPath = path.join(overlaysDir, overlay, 'devcontainer.patch.json');
         if (fs.existsSync(overlayPath)) {
             const overlayConfig = loadJson(overlayPath);
             if (overlayConfig.runServices) {