container-superposition 0.1.3 → 0.1.5

package/dist/scripts/init.js

@@ -14,9 +14,14 @@ import { listCommand } from '../tool/commands/list.js';
 import { explainCommand } from '../tool/commands/explain.js';
 import { planCommand } from '../tool/commands/plan.js';
 import { doctorCommand } from '../tool/commands/doctor.js';
+import { adoptCommand } from '../tool/commands/adopt.js';
+import { hashCommand } from '../tool/commands/hash.js';
 import { getIncompatibleOverlays, DEPLOYMENT_TARGETS } from '../tool/schema/deployment-targets.js';
 import { migrateManifest, needsMigration, detectManifestVersion, isVersionSupported, CURRENT_MANIFEST_VERSION, SUPPORTED_MANIFEST_VERSIONS, } from '../tool/schema/manifest-migrations.js';
 import { getToolVersion } from '../tool/utils/version.js';
+import { printSummary } from '../tool/utils/summary.js';
+import { buildAnswersFromProjectConfig, loadProjectConfig, writeProjectConfigCustomizations, } from '../tool/schema/project-config.js';
+import { isInsideGitRepo, createBackup, ensureBackupPatternsInGitignore, } from '../tool/utils/backup.js';
 // Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -62,10 +67,104 @@ function loadPresetDefinition(presetId) {
     const content = fs.readFileSync(presetPath, 'utf8');
     return yaml.load(content);
 }
+function categorizeOverlayIds(overlayIds, config) {
+    const language = [];
+    const database = [];
+    const observability = [];
+    const cloudTools = [];
+    const devTools = [];
+    const overlayMap = new Map(config.overlays.map((o) => [o.id, o]));
+    for (const id of overlayIds) {
+        const overlay = overlayMap.get(id);
+        if (!overlay)
+            continue;
+        switch (overlay.category) {
+            case 'language':
+                language.push(id);
+                break;
+            case 'database':
+                database.push(id);
+                break;
+            case 'observability':
+                observability.push(id);
+                break;
+            case 'cloud':
+                cloudTools.push(id);
+                break;
+            case 'dev':
+                devTools.push(id);
+                break;
+        }
+    }
+    return { language, database, observability, cloudTools, devTools };
+}
+function mergeUnique(left, right) {
+    const merged = [...(left ?? []), ...(right ?? [])];
+    return merged.length > 0 ? [...new Set(merged)] : undefined;
+}
+function expandPresetWithDefaults(presetId, stack, providedChoices = {}) {
+    const preset = loadPresetDefinition(presetId);
+    if (!preset) {
+        throw new Error(`Preset definition not found for ${presetId}`);
+    }
+    const overlays = [...preset.selects.required];
+    const choices = {};
+    if (preset.selects.userChoice) {
+        for (const [key, choice] of Object.entries(preset.selects.userChoice)) {
+            const selectedOption = providedChoices[key] ?? choice.defaultOption;
+            if (!selectedOption || !choice.options.includes(selectedOption)) {
+                const valid = choice.options.join(', ');
+                throw new Error(`Preset choice '${key}' must be one of: ${valid}`);
+            }
+            overlays.push(selectedOption);
+            choices[key] = selectedOption;
+        }
+    }
+    if (preset.parameters) {
+        for (const [key, param] of Object.entries(preset.parameters)) {
+            const selectedId = providedChoices[key] ?? param.default;
+            const selectedOption = param.options.find((option) => option.id === selectedId);
+            if (!selectedOption) {
+                const valid = param.options.map((option) => option.id).join(', ');
+                throw new Error(`Preset parameter '${key}' must be one of: ${valid}`);
+            }
+            overlays.push(...selectedOption.overlays);
+            choices[key] = selectedId;
+        }
+    }
+    const uniqueOverlays = [...new Set(overlays)];
+    let resolvedGlueConfig = preset.glueConfig;
+    if (resolvedGlueConfig?.environment) {
+        const resolvedEnv = {};
+        for (const [envKey, envValue] of Object.entries(resolvedGlueConfig.environment)) {
+            resolvedEnv[envKey] = envValue.replace(/\{\{parameters\.(\w+)\.id\}\}/g, (_match, paramKey) => choices[paramKey] ?? _match);
+        }
+        resolvedGlueConfig = { ...resolvedGlueConfig, environment: resolvedEnv };
+    }
+    return { overlays: uniqueOverlays, choices, glueConfig: resolvedGlueConfig };
+}
+function applyPresetSelections(answers) {
+    if (!answers.preset) {
+        return answers;
+    }
+    const expansion = expandPresetWithDefaults(answers.preset, answers.stack ?? 'plain', answers.presetChoices ?? {});
+    const categories = categorizeOverlayIds(expansion.overlays, loadOverlaysConfigWrapper());
+    return {
+        ...answers,
+        language: mergeUnique(categories.language, answers.language),
+        database: mergeUnique(categories.database, answers.database),
+        observability: mergeUnique(categories.observability, answers.observability),
+        cloudTools: mergeUnique(categories.cloudTools, answers.cloudTools),
+        devTools: mergeUnique(categories.devTools, answers.devTools),
+        playwright: answers.playwright ?? expansion.overlays.includes('playwright'),
+        presetChoices: Object.keys(expansion.choices).length > 0 ? expansion.choices : undefined,
+        presetGlueConfig: expansion.glueConfig,
+    };
+}
 /**
  * Expand a preset into a list of overlay IDs with user choices resolved
  */
-async function expandPreset(presetId, stack) {
+async function expandPreset(presetId, stack, preProvidedChoices = {}) {
     const preset = loadPresetDefinition(presetId);
     if (!preset) {
         return { overlays: [], choices: {} };
@@ -73,23 +172,82 @@ async function expandPreset(presetId, stack) {
     console.log(chalk.cyan(`\n📦 Expanding preset: ${preset.name}\n`));
     const overlays = [...preset.selects.required];
     const choices = {};
-    // Handle user choices
+    // Handle user choices (single overlay per option)
     if (preset.selects.userChoice) {
         for (const [key, choice] of Object.entries(preset.selects.userChoice)) {
-            const selectedOption = (await select({
-                message: choice.prompt,
-                choices: choice.options.map((opt) => ({
-                    name: opt,
-                    value: opt,
-                })),
-                default: choice.defaultOption,
-            }));
-            overlays.push(selectedOption);
-            choices[key] = selectedOption;
+            const preProvidedValue = preProvidedChoices[key];
+            if (preProvidedValue !== undefined) {
+                // Validate the pre-provided value
+                if (!choice.options.includes(preProvidedValue)) {
+                    const valid = choice.options.join(', ');
+                    throw new Error(`Invalid value '${preProvidedValue}' for preset choice '${key}'. Valid options: ${valid}`);
+                }
+                console.log(chalk.dim(`✓ ${key}: ${preProvidedValue} (from CLI)`));
+                overlays.push(preProvidedValue);
+                choices[key] = preProvidedValue;
+            }
+            else {
+                const selectedOption = (await select({
+                    message: choice.prompt,
+                    choices: choice.options.map((opt) => ({
+                        name: opt,
+                        value: opt,
+                    })),
+                    default: choice.defaultOption,
+                }));
+                overlays.push(selectedOption);
+                choices[key] = selectedOption;
+            }
+        }
+    }
+    // Handle parameterized slots (multiple overlays per option)
+    if (preset.parameters) {
+        for (const [key, param] of Object.entries(preset.parameters)) {
+            const preProvidedValue = preProvidedChoices[key];
+            let selectedId;
+            if (preProvidedValue !== undefined) {
+                // Validate the pre-provided value
+                const validOption = param.options.find((o) => o.id === preProvidedValue);
+                if (!validOption) {
+                    const valid = param.options.map((o) => o.id).join(', ');
+                    throw new Error(`Invalid value '${preProvidedValue}' for preset parameter '${key}'. Valid options: ${valid}`);
+                }
+                console.log(chalk.dim(`✓ ${key}: ${preProvidedValue} (from CLI)`));
+                selectedId = preProvidedValue;
+            }
+            else {
+                const description = param.description || `Select ${key}`;
+                selectedId = (await select({
+                    message: description,
+                    choices: param.options.map((opt) => ({
+                        name: opt.description ? `${opt.id} - ${opt.description}` : opt.id,
+                        value: opt.id,
+                    })),
+                    default: param.default,
+                }));
+            }
+            // Add overlays for the selected option
+            const selectedOption = param.options.find((o) => o.id === selectedId);
+            if (selectedOption) {
+                overlays.push(...selectedOption.overlays);
+            }
+            choices[key] = selectedId;
         }
     }
-    console.log(chalk.dim(`✓ Preset will include: ${overlays.join(', ')}\n`));
-    return { overlays, choices, glueConfig: preset.glueConfig };
+    // Deduplicate overlays
+    const uniqueOverlays = [...new Set(overlays)];
+    console.log(chalk.dim(`✓ Preset will include: ${uniqueOverlays.join(', ')}\n`));
+    // Apply template substitution to glueConfig.environment values.
+    // Replaces {{parameters.<key>.id}} with the selected choice for <key>.
+    let resolvedGlueConfig = preset.glueConfig;
+    if (resolvedGlueConfig?.environment) {
+        const resolvedEnv = {};
+        for (const [envKey, envValue] of Object.entries(resolvedGlueConfig.environment)) {
+            resolvedEnv[envKey] = envValue.replace(/\{\{parameters\.(\w+)\.id\}\}/g, (_match, paramKey) => choices[paramKey] ?? _match);
+        }
+        resolvedGlueConfig = { ...resolvedGlueConfig, environment: resolvedEnv };
+    }
+    return { overlays: uniqueOverlays, choices, glueConfig: resolvedGlueConfig };
 }
 /**
  * Search for manifest file in multiple locations
@@ -112,6 +270,16 @@ function findManifestFile(manifestPath) {
     }
     return null;
 }
+function findDefaultRegenManifest(outputPath = './.devcontainer') {
+    const manifestSearchPaths = ['superposition.json', path.join(outputPath, 'superposition.json')];
+    for (const searchPath of manifestSearchPaths) {
+        const resolvedPath = path.resolve(searchPath);
+        if (fs.existsSync(resolvedPath)) {
+            return resolvedPath;
+        }
+    }
+    return null;
+}
 /**
  * Load and validate manifest file
  */
@@ -158,116 +326,6 @@ function loadManifest(manifestPath) {
         return null;
     }
 }
-/**
- * Create timestamped backup of existing devcontainer and manifest
- */
-async function createBackup(outputPath, backupDir) {
-    // Check for devcontainer files to backup
-    const devcontainerJsonPath = path.join(outputPath, 'devcontainer.json');
-    const dockerComposePath = path.join(outputPath, 'docker-compose.yml');
-    const devcontainerSubdir = path.join(outputPath, '.devcontainer');
-    const manifestPath = path.join(outputPath, 'superposition.json');
-    // Determine what exists
-    const hasDevcontainerJson = fs.existsSync(devcontainerJsonPath);
-    const hasDockerCompose = fs.existsSync(dockerComposePath);
-    const hasDevcontainerSubdir = fs.existsSync(devcontainerSubdir) && fs.statSync(devcontainerSubdir).isDirectory();
-    const hasManifest = fs.existsSync(manifestPath);
-    if (!hasDevcontainerJson && !hasDockerCompose && !hasDevcontainerSubdir && !hasManifest) {
-        return null; // Nothing to backup
-    }
-    // Create timestamp
-    const timestamp = new Date()
-        .toISOString()
-        .replace(/:/g, '-')
-        .replace(/\..+/, '')
-        .replace('T', '-');
-    // Determine backup location - create next to outputPath, not inside it
-    const resolvedOutputPath = path.resolve(outputPath);
-    const outputParentDir = path.dirname(resolvedOutputPath);
-    const outputBaseName = path.basename(resolvedOutputPath);
-    const backupBaseName = outputBaseName === '.devcontainer' ? '.devcontainer' : outputBaseName;
-    const backupPath = backupDir
-        ? path.resolve(backupDir)
-        : path.join(outputParentDir, `${backupBaseName}.backup-${timestamp}`);
-    // Create backup directory
-    fs.mkdirSync(backupPath, { recursive: true });
-    // Backup files and directories
-    if (hasDevcontainerJson) {
-        fs.copyFileSync(devcontainerJsonPath, path.join(backupPath, 'devcontainer.json'));
-    }
-    if (hasDockerCompose) {
-        fs.copyFileSync(dockerComposePath, path.join(backupPath, 'docker-compose.yml'));
-    }
-    if (hasDevcontainerSubdir) {
-        const destDir = path.join(backupPath, '.devcontainer');
-        await copyDirectory(devcontainerSubdir, destDir);
-    }
-    if (hasManifest) {
-        fs.copyFileSync(manifestPath, path.join(backupPath, 'superposition.json'));
-    }
-    // Also backup other common devcontainer files
-    const otherFiles = ['.env', '.env.example', '.gitignore', 'features', 'scripts'];
-    for (const file of otherFiles) {
-        const srcPath = path.join(outputPath, file);
-        if (fs.existsSync(srcPath)) {
-            const destPath = path.join(backupPath, file);
-            if (fs.statSync(srcPath).isDirectory()) {
-                await copyDirectory(srcPath, destPath);
-            }
-            else {
-                fs.copyFileSync(srcPath, destPath);
-            }
-        }
-    }
-    return backupPath;
-}
-/**
- * Recursively copy directory
- */
-async function copyDirectory(src, dest) {
-    fs.mkdirSync(dest, { recursive: true });
-    const entries = fs.readdirSync(src, { withFileTypes: true });
-    for (const entry of entries) {
-        const srcPath = path.join(src, entry.name);
-        const destPath = path.join(dest, entry.name);
-        if (entry.isDirectory()) {
-            await copyDirectory(srcPath, destPath);
-        }
-        else {
-            fs.copyFileSync(srcPath, destPath);
-        }
-    }
-}
-/**
- * Ensure backup patterns are in .gitignore
- */
-async function ensureBackupPatternsInGitignore(outputPath) {
-    // Write to the parent directory's .gitignore (project root), not inside outputPath
-    const resolvedOutputPath = path.resolve(outputPath);
-    const projectRoot = path.dirname(resolvedOutputPath);
-    const gitignorePath = path.join(projectRoot, '.gitignore');
-    const backupPatterns = [
-        '',
-        '# Container Superposition backups',
-        '.devcontainer.backup-*/',
-        '*.backup-*',
-        'superposition.json.backup-*',
-    ].join('\n');
-    if (!fs.existsSync(gitignorePath)) {
-        // Create new .gitignore with backup patterns
-        await fs.promises.writeFile(gitignorePath, backupPatterns + '\n');
-        console.log(chalk.dim('   📝 Created .gitignore with backup patterns'));
-    }
-    else {
-        // Check if patterns already exist
-        const content = await fs.promises.readFile(gitignorePath, 'utf-8');
-        if (!content.includes('Container Superposition backups')) {
-            // Append patterns
-            await fs.promises.appendFile(gitignorePath, '\n' + backupPatterns + '\n');
-            console.log(chalk.dim('   📝 Updated .gitignore with backup patterns'));
-        }
-    }
-}
 /**
  * Build checkbox choices for overlay selection with optional pre-selection
  */
@@ -297,7 +355,7 @@ function buildOverlayChoices(config, stack, categoryList, preselected) {
 /**
  * Interactive questionnaire with modern checkbox selections
  */
-async function runQuestionnaire(manifest, manifestDir) {
+async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetChoices, defaultAnswers) {
     const config = loadOverlaysConfigWrapper();
     // Pretty banner
     console.log('\n' +
@@ -331,32 +389,50 @@ async function runQuestionnaire(manifest, manifestDir) {
     try {
         // Question 0: Optional preset selection
         let usePreset = false;
-        let selectedPresetId = manifest?.preset;
-        let presetChoices = manifest?.presetChoices || {};
+        // CLI preset takes precedence over manifest preset
+        let selectedPresetId = cliPresetId || manifest?.preset;
+        // CLI preset choices merged with manifest choices (CLI takes precedence)
+        let presetChoices = {
+            ...(manifest?.presetChoices || {}),
+            ...(cliPresetChoices || {}),
+        };
         let presetGlueConfig;
         const presetOverlaysFiltered = config.overlays.filter((o) => o.category === 'preset');
         let presetOverlays = [];
         if (presetOverlaysFiltered.length > 0) {
-            const defaultPreset = manifest?.preset || 'custom';
-            const presetChoice = (await select({
-                message: 'Start from a preset or build custom?',
-                choices: [
-                    {
-                        name: 'Custom (select overlays manually)',
-                        value: 'custom',
-                        description: 'Choose individual overlays yourself',
-                    },
-                    ...presetOverlaysFiltered.map((p) => ({
-                        name: p.name,
-                        value: p.id,
-                        description: p.description,
-                    })),
-                ],
-                default: defaultPreset,
-            }));
-            if (presetChoice !== 'custom') {
+            // If a preset was pre-selected via CLI or manifest, skip the prompt
+            if (selectedPresetId) {
                 usePreset = true;
-                selectedPresetId = presetChoice;
+                console.log(chalk.cyan(`\n📦 Using preset: ${selectedPresetId}\n`));
+            }
+            else {
+                const defaultPreset = 'custom';
+                const presetChoice = (await select({
+                    message: 'Start from a preset or build custom?',
+                    choices: [
+                        {
+                            name: 'Custom (select overlays manually)',
+                            value: 'custom',
+                            description: 'Choose individual overlays yourself',
+                        },
+                        ...presetOverlaysFiltered.map((p) => ({
+                            name: p.name,
+                            value: p.id,
+                            description: p.description,
+                        })),
+                    ],
+                    default: defaultPreset,
+                }));
+                if (presetChoice !== 'custom') {
+                    usePreset = true;
+                    selectedPresetId = presetChoice;
+                }
+                else {
+                    // User chose custom - discard any pre-provided preset choices so the
+                    // manifest cannot end up with presetChoices but no preset.
+                    presetChoices = {};
+                    selectedPresetId = undefined;
+                }
             }
         }
         // Question 1: Base template
@@ -367,11 +443,11 @@ async function runQuestionnaire(manifest, manifestDir) {
                 value: t.id,
                 description: t.description,
             })),
-            default: manifest?.baseTemplate,
+            default: manifest?.baseTemplate || defaultAnswers?.stack,
         }));
-        // If using preset, expand it now
+        // If using preset, expand it now (pass pre-provided choices to skip those prompts)
         if (usePreset && selectedPresetId) {
-            const expansion = await expandPreset(selectedPresetId, stack);
+            const expansion = await expandPreset(selectedPresetId, stack, presetChoices);
             if (!expansion.overlays || expansion.overlays.length === 0) {
                 // Preset failed to expand (e.g., missing or invalid preset definition).
                 // Treat this as "no preset" so the manifest does not incorrectly record one.
@@ -392,7 +468,15 @@ async function runQuestionnaire(manifest, manifestDir) {
         // Check if manifest has a custom image or a known base image
         const knownBaseImageIds = config.base_images.map((img) => img.id);
         const manifestBaseImageIsKnown = manifest?.baseImage && knownBaseImageIds.includes(manifest.baseImage);
-        const manifestDefaultBaseImage = manifestBaseImageIsKnown ? manifest.baseImage : 'custom';
+        const manifestDefaultBaseImage = manifestBaseImageIsKnown
+            ? manifest.baseImage
+            : manifest?.baseImage
+                ? 'custom'
+                : undefined;
+        const defaultBaseImage = manifestDefaultBaseImage ||
+            (defaultAnswers?.baseImage === 'custom' && defaultAnswers.customImage
+                ? 'custom'
+                : defaultAnswers?.baseImage);
         const baseImage = (await select({
             message: 'Select base image:',
             choices: config.base_images.map((img) => ({
@@ -400,16 +484,17 @@ async function runQuestionnaire(manifest, manifestDir) {
                 value: img.id,
                 description: img.description,
             })),
-            default: manifestDefaultBaseImage,
+            default: defaultBaseImage,
         }));
         // Question 2a: If custom, ask for image name
         let customImage;
         if (baseImage === 'custom') {
             // If manifest has a custom image, use it as default
             const manifestCustomImage = !manifestBaseImageIsKnown && manifest?.baseImage ? manifest.baseImage : undefined;
+            const defaultCustomImage = manifestCustomImage || defaultAnswers?.customImage;
             customImage = await input({
                 message: 'Enter custom Docker image (e.g., ubuntu:22.04):',
-                default: manifestCustomImage,
+                default: defaultCustomImage,
                 validate: (value) => {
                     if (!value || value.trim() === '') {
                         return 'Image name is required';
@@ -525,7 +610,15 @@ async function runQuestionnaire(manifest, manifestDir) {
         else {
             // Custom mode: Normal overlay selection
             console.log(chalk.dim('\n💡 Select overlays: Space to toggle, ↑/↓ to navigate, Enter to confirm\n'));
-            const choices = buildOverlayChoices(config, stack, categoryList, []);
+            const preselectedDefaults = [
+                ...(defaultAnswers?.language ?? []),
+                ...(defaultAnswers?.database ?? []),
+                ...(defaultAnswers?.observability ?? []),
+                ...(defaultAnswers?.cloudTools ?? []),
+                ...(defaultAnswers?.devTools ?? []),
+                ...(defaultAnswers?.playwright ? ['playwright'] : []),
+            ];
+            const choices = buildOverlayChoices(config, stack, categoryList, preselectedDefaults);
             userSelection = await checkbox({
                 message: 'Select overlays to include:',
                 choices,
@@ -602,11 +695,11 @@ async function runQuestionnaire(manifest, manifestDir) {
         // Question 4: Container name
         const containerName = await input({
             message: 'Container/project name (optional):',
-            default: manifest?.containerName || '',
+            default: manifest?.containerName || defaultAnswers?.containerName || '',
         });
         // Question 5: Output path
         // If manifest provided, default to its location; otherwise use ./.devcontainer
-        const defaultOutput = manifestDir || './.devcontainer';
+        const defaultOutput = manifestDir || defaultAnswers?.outputPath || './.devcontainer';
         const outputPath = await input({
             message: 'Output path:',
             default: defaultOutput,
@@ -614,7 +707,11 @@ async function runQuestionnaire(manifest, manifestDir) {
         // Question 6: Port offset (optional, for running multiple instances)
         const portOffsetInput = await input({
             message: 'Port offset (leave empty for default ports, e.g., 100 to avoid conflicts):',
-            default: manifest?.portOffset ? String(manifest.portOffset) : '',
+            default: manifest?.portOffset !== undefined
+                ? String(manifest.portOffset)
+                : defaultAnswers?.portOffset !== undefined
+                    ? String(defaultAnswers.portOffset)
+                    : '',
         });
         const portOffset = portOffsetInput ? parseInt(portOffsetInput, 10) : undefined;
         // Parse selected overlays into categories
@@ -709,7 +806,10 @@ async function runQuestionnaire(manifest, manifestDir) {
             observability,
             outputPath,
             portOffset,
-            target,
+            target: target ?? defaultAnswers?.target,
+            minimal: defaultAnswers?.minimal,
+            editor: defaultAnswers?.editor,
+            customizations: defaultAnswers?.customizations,
         };
     }
     catch (error) {
@@ -879,9 +979,10 @@ async function parseCliArgs() {
     program
         .command('init', { isDefault: true })
         .description('Initialize a new devcontainer configuration')
+        .option('--from-project', 'Load configuration from the repository project file')
         .option('--from-manifest <path>', 'Load configuration from existing superposition.json manifest')
-        .option('--no-interactive', 'Use manifest values directly without questionnaire (requires --from-manifest)')
-        .option('--no-backup', 'Skip creating backup before regeneration')
+        .option('--no-interactive', 'Use persisted input values directly without questionnaire')
+        .option('--backup', 'Force or suppress backup; default is --no-backup inside a git repo, --backup outside')
         .option('--backup-dir <path>', 'Custom backup directory location')
         .option('--stack <type>', 'Base template: plain, compose')
         .option('--language <list>', 'Comma-separated language overlays: dotnet, nodejs, python, mkdocs, java, go, rust, bun, powershell')
@@ -896,47 +997,34 @@ async function parseCliArgs() {
         .option('--editor <profile>', 'Editor profile: vscode (default), jetbrains, none', 'vscode')
         .option('-o, --output <path>', 'Output path (default: ./.devcontainer)')
         .option('--write-manifest-only', 'Generate only superposition.json manifest without creating .devcontainer/ files')
-        .action((options) => {
+        .option('--preset <id>', 'Start from a preset (e.g., web-api, microservice)')
+        .option('--preset-param <value>', 'Set a preset parameter value (format: key=value, can be repeated)', (value, previous) => previous.concat([value]), [])
+        .action((options, command) => {
         // Store options for main() to process
-        initOptions = options;
+        initOptions = {
+            ...options,
+            commandName: 'init',
+            _targetSource: command.getOptionValueSource('target'),
+            _editorSource: command.getOptionValueSource('editor'),
+        };
     });
     // Regen command
     program
         .command('regen')
-        .description('Regenerate devcontainer from existing superposition.json manifest')
+        .description('Regenerate devcontainer from a project file or existing superposition.json manifest')
+        .option('--from-project', 'Load configuration from the repository project file')
+        .option('--from-manifest <path>', 'Load configuration from existing superposition.json manifest')
         .option('-o, --output <path>', 'Output path (default: ./.devcontainer)')
-        .option('--no-backup', 'Skip creating backup before regeneration')
+        .option('--backup', 'Force or suppress backup; default is --no-backup inside a git repo, --backup outside')
         .option('--backup-dir <path>', 'Custom backup directory location')
         .option('--minimal', 'Minimal mode - exclude optional/nice-to-have features and extensions')
         .option('--editor <profile>', 'Editor profile: vscode (default), jetbrains, none', 'vscode')
-        .action((options) => {
-        const outputPath = options.output || './.devcontainer';
-        // Look for manifest in multiple locations for team workflow:
-        // 1. Current directory (./superposition.json) - team workflow
-        // 2. Output directory (e.g., ./.devcontainer/superposition.json) - legacy
-        const manifestSearchPaths = [
-            'superposition.json',
-            path.join(outputPath, 'superposition.json'),
-        ];
-        let manifestPath = null;
-        for (const searchPath of manifestSearchPaths) {
-            if (fs.existsSync(searchPath)) {
-                manifestPath = searchPath;
-                break;
-            }
-        }
-        if (!manifestPath) {
-            console.error(chalk.red(`✗ Error: No manifest found`));
-            console.error(chalk.gray('  Searched for: ./superposition.json, ' +
-                path.join(outputPath, 'superposition.json')));
-            console.error(chalk.gray('  Run "container-superposition init --write-manifest-only" to create a manifest'));
-            process.exit(1);
-        }
-        // Store options for main() to process
+        .action((options, command) => {
         initOptions = {
             ...options,
-            fromManifest: manifestPath,
+            commandName: 'regen',
             interactive: false,
+            _editorSource: command.getOptionValueSource('editor'),
         };
     });
     // List command
@@ -966,9 +1054,15 @@ async function parseCliArgs() {
     program
         .command('plan')
         .description('Preview what will be generated before creating devcontainer')
-        .option('--stack <type>', 'Base template: plain, compose', 'compose')
+        .option('--stack <type>', 'Base template: plain, compose')
         .option('--overlays <list>', 'Comma-separated list of overlay IDs')
+        .option('--from-manifest <path>', 'Load stack and overlays from an existing superposition.json manifest')
         .option('--port-offset <number>', 'Add offset to all exposed ports', (val) => parseInt(val, 10), 0)
+        .option('-o, --output <path>', 'Compare against existing config at this path (default: ./.devcontainer)')
+        .option('--diff', 'Compare planned output vs existing configuration')
+        .option('--diff-format <format>', 'Diff output format: color (default), json', 'color')
+        .option('--diff-context <lines>', 'Context lines in diff output', (val) => parseInt(val, 10), 3)
+        .option('--verbose', 'Explain why each overlay was included in the resolved plan')
         .option('--json', 'Output as JSON for scripting')
         .action(async (options) => {
         const overlaysConfig = loadOverlaysConfigWrapper();
@@ -986,6 +1080,39 @@ async function parseCliArgs() {
         const overlaysConfig = loadOverlaysConfigWrapper();
         await doctorCommand(overlaysConfig, OVERLAYS_DIR, options);
     });
+    // Adopt command
+    program
+        .command('adopt')
+        .description('Analyse an existing .devcontainer/ and suggest an equivalent overlay-based configuration')
+        .option('-d, --dir <path>', 'Path to the existing .devcontainer directory (default: ./.devcontainer)')
+        .option('--dry-run', 'Print analysis and suggested command only; no files written')
+        .option('--force', 'Overwrite existing superposition.json if present')
+        .option('--backup', 'Force backup creation even when inside a git repo (default: backup only outside git repos)')
+        .option('--no-backup', 'Disable backup creation even when it would normally be performed')
+        .option('--backup-dir <path>', 'Custom backup directory location')
+        .option('--json', 'Output as JSON for scripting')
+        .action(async (options) => {
+        const overlaysConfig = loadOverlaysConfigWrapper();
+        await adoptCommand(overlaysConfig, OVERLAYS_DIR, options);
+        process.exit(0);
+    });
+    // Hash command
+    program
+        .command('hash')
+        .description('Compute a deterministic fingerprint for a given configuration')
+        .option('--stack <type>', 'Base template: plain, compose')
+        .option('--overlays <list>', 'Comma-separated list of overlay IDs')
+        .option('--preset <id>', 'Preset ID (optional)')
+        .option('--base <image>', 'Base image / distro variant (e.g. bookworm, alpine)')
+        .option('--manifest <path>', 'Path to superposition.json manifest')
+        .option('-o, --output <path>', 'Directory to write hash file (used with --write)')
+        .option('--write', 'Write hash to .devcontainer/superposition.hash')
+        .option('--json', 'Output as JSON for scripting')
+        .action(async (options) => {
+        const overlaysConfig = loadOverlaysConfigWrapper();
+        await hashCommand(overlaysConfig, OVERLAYS_DIR, options);
+        process.exit(0);
+    });
     await program.parseAsync(process.argv);
     // If init or regen command was run, return the options
     if (!initOptions) {
@@ -996,6 +1123,34 @@ async function parseCliArgs() {
     if (Object.keys(initOptions).length === 0) {
         return null;
     }
+    const hasSourceFlags = Number(Boolean(initOptions.fromProject)) + Number(Boolean(initOptions.fromManifest));
+    if (hasSourceFlags > 1) {
+        console.error(chalk.red('✗ Error: --from-project and --from-manifest cannot be used together'));
+        process.exit(1);
+    }
+    const sourceSelectionConflicts = [
+        'stack',
+        'language',
+        'database',
+        'observability',
+        'playwright',
+        'cloudTools',
+        'devTools',
+        'portOffset',
+        'preset',
+    ];
+    const hasPresetParams = Array.isArray(initOptions.presetParam) && initOptions.presetParam.length > 0;
+    const conflictingSelectionFlags = sourceSelectionConflicts.filter((key) => initOptions[key] !== undefined && initOptions[key] !== false);
+    if ((initOptions.fromProject || initOptions.fromManifest) &&
+        (conflictingSelectionFlags.length > 0 || hasPresetParams)) {
+        const conflicts = [...conflictingSelectionFlags.map((key) => `--${key}`)];
+        if (hasPresetParams) {
+            conflicts.push('--preset-param');
+        }
+        console.error(chalk.red(`✗ Error: Persisted input sources cannot be combined with clean-generation selection flags: ${conflicts.join(', ')}`));
+        console.error(chalk.dim('  Choose either a persisted input source (--from-project or --from-manifest) or direct selection flags for that run.'));
+        process.exit(1);
+    }
     const config = {};
     if (initOptions.stack)
         config.stack = initOptions.stack;
@@ -1027,13 +1182,13 @@ async function parseCliArgs() {
     if (initOptions.portOffset) {
         config.portOffset = parseInt(initOptions.portOffset, 10);
     }
-    if (initOptions.target) {
+    if (initOptions.target && initOptions._targetSource !== 'default') {
         config.target = initOptions.target;
     }
     if (initOptions.minimal) {
         config.minimal = true;
     }
-    if (initOptions.editor) {
+    if (initOptions.editor && initOptions._editorSource !== 'default') {
         const editorLower = initOptions.editor.toLowerCase();
         if (['vscode', 'jetbrains', 'none'].includes(editorLower)) {
             config.editor = editorLower;
@@ -1045,10 +1200,42 @@ async function parseCliArgs() {
     }
     if (initOptions.output)
         config.outputPath = initOptions.output;
+    // Handle --preset flag
+    if (initOptions.preset) {
+        config.preset = initOptions.preset;
+    }
+    // Handle --preset-param flags (can be repeated)
+    if (initOptions.presetParam && initOptions.presetParam.length > 0) {
+        if (!initOptions.preset) {
+            console.warn(chalk.yellow('⚠️  Ignoring --preset-param because no --preset was provided. ' +
+                'Preset parameters only apply when a preset is selected (e.g., --preset web-api --preset-param broker=nats).'));
+        }
+        else {
+            const presetChoices = {};
+            for (const param of initOptions.presetParam) {
+                const eqIdx = param.indexOf('=');
+                if (eqIdx > 0) {
+                    const key = param.slice(0, eqIdx).trim();
+                    const value = param.slice(eqIdx + 1).trim();
+                    if (key) {
+                        presetChoices[key] = value;
+                    }
+                }
+                else {
+                    console.warn(chalk.yellow(`⚠️  Invalid --preset-param format: "${param}". Expected "key=value" (e.g., --preset-param broker=nats).`));
+                }
+            }
+            if (Object.keys(presetChoices).length > 0) {
+                config.presetChoices = presetChoices;
+            }
+        }
+    }
     return {
+        commandName: initOptions.commandName,
         config,
         manifestPath: initOptions.fromManifest,
-        noBackup: initOptions.backup === false, // Commander creates options.backup = false for --no-backup
+        fromProject: initOptions.fromProject === true,
+        backupOverride: initOptions.backup, // undefined = auto-detect; true = --backup; false = --no-backup
         backupDir: initOptions.backupDir,
         noInteractive: initOptions.interactive === false, // Commander creates options.interactive = false for --no-interactive
         writeManifestOnly: initOptions.writeManifestOnly === true,
@@ -1057,17 +1244,34 @@ async function parseCliArgs() {
 async function main() {
     try {
         const cliArgs = await parseCliArgs();
-        // Validate --no-interactive requires --from-manifest
-        if (cliArgs?.noInteractive && !cliArgs?.manifestPath) {
-            console.error(chalk.red('✗ Error: --no-interactive requires --from-manifest'));
-            console.error(chalk.dim('  Use both flags together: --from-manifest <path> --no-interactive'));
-            process.exit(1);
+        let projectConfig = undefined;
+        let projectConfigAnswers;
+        if (!cliArgs?.manifestPath) {
+            projectConfig =
+                loadProjectConfig(loadOverlaysConfigWrapper(), process.cwd()) ?? undefined;
+            if (projectConfig) {
+                projectConfigAnswers = applyPresetSelections(buildAnswersFromProjectConfig(projectConfig.selection));
+            }
         }
         let manifest;
         let manifestDir;
-        let shouldBackup = true;
         let backupDir;
         let useManifestOnly = false;
+        let useProjectOnly = false;
+        if (cliArgs?.commandName === 'regen' && !cliArgs.manifestPath && !cliArgs.fromProject) {
+            if (projectConfigAnswers) {
+                useProjectOnly = true;
+            }
+            else {
+                const discoveredManifestPath = findDefaultRegenManifest(cliArgs?.config?.outputPath || './.devcontainer');
+                if (!discoveredManifestPath) {
+                    console.error(chalk.red('✗ Error: No project file or manifest found'));
+                    console.error(chalk.gray('  Looked for .superposition.yml or superposition.yml in the repository root, and superposition.json in common manifest locations.'));
+                    process.exit(1);
+                }
+                cliArgs.manifestPath = discoveredManifestPath;
+            }
+        }
         // Handle manifest loading
         if (cliArgs?.manifestPath) {
             const manifestPath = findManifestFile(cliArgs.manifestPath);
@@ -1082,10 +1286,7 @@ async function main() {
                 process.exit(1);
             }
             manifest = loadedManifest;
-            // Check for backup and interaction options
-            if (cliArgs.noBackup) {
-                shouldBackup = false;
-            }
+            // Check for interaction options
             if (cliArgs.backupDir) {
                 backupDir = cliArgs.backupDir;
             }
@@ -1093,22 +1294,72 @@ async function main() {
                 useManifestOnly = true;
             }
         }
+        if (cliArgs?.fromProject) {
+            if (!projectConfigAnswers || !projectConfig) {
+                console.error(chalk.red('✗ Could not find project file'));
+                console.error(chalk.red('  Searched for: .superposition.yml, superposition.yml'));
+                process.exit(1);
+            }
+            useProjectOnly = cliArgs.noInteractive || cliArgs.commandName === 'regen';
+        }
+        // Validate --no-interactive requires a persisted input source
+        if (cliArgs?.noInteractive && !cliArgs?.manifestPath && !projectConfigAnswers) {
+            console.error(chalk.red('✗ Error: --no-interactive requires persisted input'));
+            console.error(chalk.dim('  Use --from-project, --from-manifest <path>, or run from a repository with .superposition.yml or superposition.yml'));
+            process.exit(1);
+        }
+        // Determine whether to create a backup:
+        //   --backup      → always backup
+        //   --no-backup   → never backup
+        //   (neither)     → backup only when NOT inside a git repository
+        //                   (git already tracks history, so backups are redundant)
+        const resolvedOutputPath = cliArgs?.config?.outputPath ||
+            projectConfigAnswers?.outputPath ||
+            manifestDir ||
+            './.devcontainer';
+        const backupCheckPath = path.resolve(resolvedOutputPath);
+        const inGitRepo = isInsideGitRepo(backupCheckPath);
+        let shouldBackup;
+        if (cliArgs?.backupOverride === true) {
+            shouldBackup = true;
+        }
+        else if (cliArgs?.backupOverride === false) {
+            shouldBackup = false;
+        }
+        else {
+            // Auto-detect based on git presence
+            shouldBackup = !inGitRepo;
+            if (!shouldBackup) {
+                console.log(chalk.dim('ℹ  Skipping backup — git repo detected (use --backup to force one)\n'));
+            }
+        }
+        const isReplayMode = cliArgs?.commandName === 'regen' || useManifestOnly || useProjectOnly;
         // Create backup if needed
-        if (shouldBackup && manifest) {
-            // Output path is the directory containing the manifest
-            const outputPath = manifestDir || './.devcontainer';
+        let actualBackupPath;
+        if (shouldBackup && isReplayMode) {
+            const outputPath = resolvedOutputPath;
             const backupPath = await createBackup(outputPath, backupDir);
             if (backupPath) {
+                actualBackupPath = backupPath;
                 console.log(chalk.green(`✓ Backup created: ${backupPath}\n`));
-                await ensureBackupPatternsInGitignore(outputPath);
+                ensureBackupPatternsInGitignore(outputPath);
             }
         }
         // Build answers based on mode
         let answers;
-        // Check if there are CLI overrides beyond just output path
+        // Check if there are CLI overrides beyond just output path and preset flags
+        // Preset/presetChoices alone don't constitute "CLI overrides" that bypass interactive mode
         const hasCliOverrides = cliArgs &&
             Object.keys(cliArgs.config).some((key) => key !== 'outputPath' &&
+                key !== 'preset' &&
+                key !== 'presetChoices' &&
+                !(key === 'target' && cliArgs.config.target === 'local') &&
+                !(key === 'editor' && cliArgs.config.editor === 'vscode') &&
                 cliArgs.config[key] !== undefined);
+        const hasAnyCliConfig = cliArgs &&
+            Object.entries(cliArgs.config).some(([key, value]) => value !== undefined &&
+                !(key === 'target' && value === 'local') &&
+                !(key === 'editor' && value === 'vscode'));
         if (useManifestOnly && manifest && !hasCliOverrides) {
             // Mode 1: Manifest-only (--from-manifest --no-interactive, no CLI overrides)
             const manifestAnswers = buildAnswersFromManifest(manifest, manifestDir);
@@ -1128,19 +1379,44 @@ async function main() {
                         : '') +
                     chalk.gray(`  Output: ${answers.outputPath}`), { padding: 1, borderColor: 'cyan', borderStyle: 'round', margin: 1 }));
         }
-        else if (cliArgs && (cliArgs.config.stack || hasCliOverrides)) {
+        else if (useProjectOnly && projectConfigAnswers && !hasCliOverrides) {
+            const projectFileName = projectConfig?.file.fileName ?? '.superposition.yml';
+            answers = mergeAnswers(projectConfigAnswers, {
+                outputPath: cliArgs?.config?.outputPath ||
+                    projectConfigAnswers.outputPath ||
+                    './.devcontainer',
+                minimal: cliArgs?.config?.minimal,
+                editor: cliArgs?.config?.editor,
+            });
+            console.log('\n' +
+                boxen(chalk.bold.cyan('Regenerating from Project File (No Interactive)\n\n') +
+                    chalk.white('Configuration:\n') +
+                    chalk.gray(`  Project file: ${projectFileName}\n`) +
+                    chalk.gray(`  Output: ${answers.outputPath}`), {
+                    padding: 1,
+                    borderColor: 'cyan',
+                    borderStyle: 'round',
+                    margin: 1,
+                }));
+        }
+        else if ((cliArgs && (cliArgs.config.stack || hasCliOverrides)) ||
+            (projectConfigAnswers && (cliArgs?.noInteractive || hasAnyCliConfig))) {
             // Mode 2: CLI-based (with optional manifest defaults)
             // This includes regen with --minimal or --editor flags
             const cliAnswers = buildAnswersFromCliArgs(cliArgs.config);
             const manifestAnswers = manifest
                 ? buildAnswersFromManifest(manifest, manifestDir)
                 : undefined;
-            answers = mergeAnswers(manifestAnswers, cliAnswers, {
-                outputPath: cliAnswers.outputPath || './.devcontainer',
+            answers = mergeAnswers(projectConfigAnswers, manifestAnswers, cliAnswers, {
+                outputPath: cliAnswers.outputPath || projectConfigAnswers?.outputPath || './.devcontainer',
             });
             const modeLabel = useManifestOnly && hasCliOverrides
                 ? 'Regenerating from Manifest with Overrides'
-                : 'Running in CLI mode';
+                : useProjectOnly && projectConfigAnswers
+                    ? 'Regenerating from Project File with Overrides'
+                    : projectConfigAnswers && !manifest
+                        ? 'Running from Project Config'
+                        : 'Running in CLI mode';
             console.log('\n' +
                 boxen(chalk.bold(modeLabel), {
                     padding: 0.5,
@@ -1148,7 +1424,7 @@ async function main() {
                     borderStyle: 'round',
                 }));
             // Show what's being overridden
-            if (useManifestOnly && hasCliOverrides) {
+            if ((useManifestOnly || useProjectOnly) && hasCliOverrides) {
                 const overrides = [];
                 if (cliAnswers.minimal)
                     overrides.push('minimal mode');
@@ -1160,9 +1436,16 @@ async function main() {
             }
         }
         else {
-            // Mode 3: Interactive (with optional manifest pre-population)
-            const interactiveAnswers = await runQuestionnaire(manifest, manifestDir);
-            answers = mergeAnswers(interactiveAnswers);
+            // Mode 3: Interactive (with optional manifest pre-population and CLI preset pre-selection)
+            const interactiveAnswers = await runQuestionnaire(manifest, manifestDir, cliArgs?.config.preset || projectConfigAnswers?.preset, cliArgs?.config.presetChoices || projectConfigAnswers?.presetChoices, projectConfigAnswers);
+            answers = mergeAnswers(projectConfigAnswers, interactiveAnswers);
+        }
+        if (!manifest && projectConfig?.selection.customizations) {
+            const materializedOutputPath = path.resolve(answers.outputPath);
+            if (!fs.existsSync(materializedOutputPath)) {
+                fs.mkdirSync(materializedOutputPath, { recursive: true });
+            }
+            writeProjectConfigCustomizations(materializedOutputPath, projectConfig.selection.customizations);
         }
         // Show configuration summary
         const summaryLines = [
@@ -1182,6 +1465,9 @@ async function main() {
         if (answers.cloudTools && answers.cloudTools.length > 0) {
             summaryLines.push(chalk.cyan('Cloud tools:     ') + chalk.white(answers.cloudTools.join(', ')));
         }
+        if (projectConfig?.file && !manifest) {
+            summaryLines.push(chalk.cyan('Project config:  ') + chalk.white(projectConfig.file.fileName));
+        }
         summaryLines.push(chalk.cyan('Output:          ') + chalk.white(answers.outputPath));
         console.log('\n' +
             boxen(summaryLines.join('\n'), {
@@ -1200,40 +1486,28 @@ async function main() {
             color: 'cyan',
         }).start();
         try {
+            let summary;
             if (isManifestOnly) {
-                await generateManifestOnly(answers);
+                summary = await generateManifestOnly(answers, undefined, {
+                    isRegen: isReplayMode,
+                });
                 spinner.succeed(chalk.green('Manifest created successfully!'));
             }
             else {
-                await composeDevContainer(answers);
+                summary = await composeDevContainer(answers, undefined, { isRegen: isReplayMode });
                 spinner.succeed(chalk.green('DevContainer created successfully!'));
             }
+            // Update summary with backup path and regen status
+            if (actualBackupPath) {
+                summary.backupPath = actualBackupPath;
+            }
+            // Print comprehensive summary
+            printSummary(summary);
         }
         catch (error) {
             spinner.fail(chalk.red(isManifestOnly ? 'Failed to create manifest' : 'Failed to create devcontainer'));
             throw error;
         }
-        // Success message
-        const successMessage = isManifestOnly
-            ? chalk.bold.green('✓ Manifest Created!\n\n') +
-                chalk.white('Next steps:\n') +
-                chalk.gray('  1. Review the generated superposition.json file\n') +
-                chalk.gray('  2. Commit it to your repository\n') +
-                chalk.gray('  3. Team members can run "npx container-superposition regen"\n\n') +
-                chalk.dim('Team workflow: commit manifest, .gitignore .devcontainer/, customize with .devcontainer/custom/')
-            : chalk.bold.green('✓ Setup Complete!\n\n') +
-                chalk.white('Next steps:\n') +
-                chalk.gray('  1. Review the generated .devcontainer/ folder\n') +
-                chalk.gray("  2. Customize as needed (it's just normal JSON!)\n") +
-                chalk.gray('  3. Open in VS Code and rebuild container\n\n') +
-                chalk.dim('The generated configuration is fully editable and independent of this tool.');
-        console.log('\n' +
-            boxen(successMessage, {
-                padding: 1,
-                borderColor: 'green',
-                borderStyle: 'double',
-                margin: 1,
-            }));
     }
     catch (error) {
         console.error('\n' +