container-superposition 0.1.1 → 0.1.4

package/dist/scripts/init.js

@@ -2,14 +2,24 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import boxen from 'boxen';
 import ora from 'ora';
 import { select, checkbox, input } from '@inquirer/prompts';
 import yaml from 'js-yaml';
-import { composeDevContainer } from '../tool/questionnaire/composer.js';
+import { composeDevContainer, generateManifestOnly } from '../tool/questionnaire/composer.js';
 import { loadOverlaysConfig } from '../tool/schema/overlay-loader.js';
+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 { 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 { appendGitignoreSection } from '../tool/utils/gitignore.js';
 // Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,8 +42,8 @@ const OVERLAYS_CONFIG_CANDIDATES = [
 const OVERLAYS_CONFIG_PATH = OVERLAYS_CONFIG_CANDIDATES.find((candidate) => fs.existsSync(candidate)) ??
     OVERLAYS_CONFIG_CANDIDATES[0];
 const PRESETS_DIR_CANDIDATES = [
-    path.join(__dirname, '..', 'overlays', 'presets'),
-    path.join(__dirname, '..', '..', 'overlays', 'presets'),
+    path.join(__dirname, '..', 'overlays', '.presets'),
+    path.join(__dirname, '..', '..', 'overlays', '.presets'),
 ];
 const PRESETS_DIR = PRESETS_DIR_CANDIDATES.find((candidate) => fs.existsSync(candidate)) ??
     PRESETS_DIR_CANDIDATES[0];
@@ -58,7 +68,7 @@ function loadPresetDefinition(presetId) {
 /**
  * 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: {} };
@@ -66,23 +76,72 @@ 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;
+            }
         }
     }
-    console.log(chalk.dim(`✓ Preset will include: ${overlays.join(', ')}\n`));
-    return { overlays, choices, glueConfig: preset.glueConfig };
+    // 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;
+        }
+    }
+    // Deduplicate overlays
+    const uniqueOverlays = [...new Set(overlays)];
+    console.log(chalk.dim(`✓ Preset will include: ${uniqueOverlays.join(', ')}\n`));
+    return { overlays: uniqueOverlays, choices, glueConfig: preset.glueConfig };
 }
 /**
  * Search for manifest file in multiple locations
@@ -111,10 +170,29 @@ function findManifestFile(manifestPath) {
 function loadManifest(manifestPath) {
     try {
         const content = fs.readFileSync(manifestPath, 'utf-8');
-        const manifest = JSON.parse(content);
+        const rawManifest = JSON.parse(content);
+        // Detect manifest version
+        const detectedVersion = detectManifestVersion(rawManifest);
+        // Check if version is supported
+        if (!isVersionSupported(detectedVersion)) {
+            console.error(chalk.red(`✗ Manifest version ${detectedVersion} is not supported.\n` +
+                `  This tool supports versions: ${SUPPORTED_MANIFEST_VERSIONS.join(', ')}\n` +
+                `  Please upgrade your tool or regenerate the manifest.`));
+            return null;
+        }
+        // Migrate if needed
+        let manifest;
+        if (needsMigration(rawManifest)) {
+            const oldVersion = rawManifest.manifestVersion || rawManifest.version || 'legacy';
+            console.log(chalk.cyan(`ℹ️  Migrating manifest from version ${oldVersion} to ${CURRENT_MANIFEST_VERSION}...`));
+            manifest = migrateManifest(rawManifest);
+        }
+        else {
+            manifest = rawManifest;
+        }
         // Basic validation
-        if (!manifest.version || !manifest.baseTemplate) {
-            console.error(chalk.red('✗ Invalid manifest format: missing required fields (version, baseTemplate)'));
+        if (!manifest.baseTemplate) {
+            console.error(chalk.red('✗ Invalid manifest format: missing required field "baseTemplate"'));
             return null;
         }
         if (!Array.isArray(manifest.overlays)) {
@@ -125,10 +203,6 @@ function loadManifest(manifestPath) {
             console.error(chalk.red('✗ Invalid manifest format: all "overlays" entries must be strings'));
             return null;
         }
-        // Version check (warn if different, but continue)
-        if (manifest.version !== '0.1.0') {
-            console.warn(chalk.yellow(`⚠️  Manifest version ${manifest.version} may not be fully compatible with this tool`));
-        }
         return manifest;
     }
     catch (error) {
@@ -136,6 +210,32 @@ function loadManifest(manifestPath) {
         return null;
     }
 }
+/**
+ * Detect whether a directory (or any of its parents) is inside a git repository.
+ * First tries `git rev-parse --git-dir`; if git is unavailable, falls back to
+ * walking up the directory tree looking for a `.git` entry.
+ */
+function isInsideGitRepo(dirPath) {
+    try {
+        execSync('git rev-parse --git-dir', { cwd: dirPath, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        // git command failed (not a repo) or git is not installed — walk up looking for .git
+        let current = path.resolve(dirPath);
+        while (true) {
+            if (fs.existsSync(path.join(current, '.git'))) {
+                return true;
+            }
+            const parent = path.dirname(current);
+            if (parent === current) {
+                break; // reached filesystem root
+            }
+            current = parent;
+        }
+        return false;
+    }
+}
 /**
  * Create timestamped backup of existing devcontainer and manifest
  */
@@ -219,31 +319,16 @@ async function copyDirectory(src, dest) {
 /**
  * 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);
+function ensureBackupPatternsInGitignore(outputPath) {
+    const projectRoot = path.dirname(path.resolve(outputPath));
     const gitignorePath = path.join(projectRoot, '.gitignore');
-    const backupPatterns = [
-        '',
-        '# Container Superposition backups',
+    const written = appendGitignoreSection(gitignorePath, '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'));
-        }
+    ]);
+    if (written) {
+        console.log(chalk.dim('   📝 Updated .gitignore with backup patterns'));
     }
 }
 /**
@@ -275,7 +360,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) {
     const config = loadOverlaysConfigWrapper();
     // Pretty banner
     console.log('\n' +
@@ -309,32 +394,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
@@ -347,9 +450,9 @@ async function runQuestionnaire(manifest, manifestDir) {
             })),
             default: manifest?.baseTemplate,
         }));
-        // 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.
@@ -603,6 +706,73 @@ async function runQuestionnaire(manifest, manifestDir) {
         const devTools = selectedOverlays.filter((o) => overlayMap.get(o)?.category === 'dev');
         const database = selectedOverlays.filter((o) => overlayMap.get(o)?.category === 'database');
         const playwright = selectedOverlays.includes('playwright');
+        // Check for deployment target compatibility
+        let target;
+        // Check if any incompatible overlays selected
+        const incompatibleOverlays = getIncompatibleOverlays(selectedOverlays, undefined);
+        if (incompatibleOverlays.length > 0) {
+            console.log(chalk.yellow('\n⚠️  Deployment Target Compatibility Check:\n'));
+            console.log(chalk.gray('Some selected overlays may not work in all environments.'));
+            console.log();
+            // Show incompatibilities
+            for (const { overlay, alternatives } of incompatibleOverlays) {
+                const overlayMeta = allOverlaysMap.get(overlay);
+                console.log(chalk.yellow(`   • ${overlayMeta?.name || overlay}`));
+                console.log(chalk.gray(`     Not compatible with: ${DEPLOYMENT_TARGETS.codespaces.name}, ${DEPLOYMENT_TARGETS.gitpod.name}`));
+                if (alternatives.length > 0) {
+                    const altNames = alternatives
+                        .map((id) => allOverlaysMap.get(id)?.name || id)
+                        .join(', ');
+                    console.log(chalk.cyan(`     Alternatives: ${altNames}`));
+                }
+                console.log();
+            }
+            const targetChoice = (await select({
+                message: 'Which environment are you targeting?',
+                choices: [
+                    {
+                        name: '🖥️  Local Development (Docker Desktop)',
+                        value: 'local',
+                        description: 'Running on your local machine - supports all overlays',
+                    },
+                    {
+                        name: '☁️  GitHub Codespaces',
+                        value: 'codespaces',
+                        description: 'Cloud development - may require docker-in-docker',
+                    },
+                    {
+                        name: '🌐 Gitpod',
+                        value: 'gitpod',
+                        description: 'Cloud development - may require docker-in-docker',
+                    },
+                    {
+                        name: '📦 DevPod',
+                        value: 'devpod',
+                        description: 'Client-only dev environments',
+                    },
+                ],
+                default: 'local',
+            }));
+            target = targetChoice;
+            // Show specific incompatibilities for selected target
+            if (target !== 'local') {
+                const targetIncompatible = getIncompatibleOverlays(selectedOverlays, target);
+                if (targetIncompatible.length > 0) {
+                    console.log(chalk.yellow(`\n⚠️  Warning: Some overlays won't work in ${DEPLOYMENT_TARGETS[target].name}:\n`));
+                    for (const { overlay, alternatives } of targetIncompatible) {
+                        const overlayMeta = allOverlaysMap.get(overlay);
+                        console.log(chalk.red(`   ✗ ${overlayMeta?.name || overlay}`));
+                        if (alternatives.length > 0) {
+                            const altNames = alternatives
+                                .map((id) => allOverlaysMap.get(id)?.name || id)
+                                .join(', ');
+                            console.log(chalk.cyan(`     → Recommended: ${altNames}`));
+                        }
+                    }
+                    console.log();
+                }
+            }
+        }
         return {
             stack,
             baseImage,
@@ -620,6 +790,7 @@ async function runQuestionnaire(manifest, manifestDir) {
             observability,
             outputPath,
             portOffset,
+            target,
         };
     }
     catch (error) {
@@ -724,6 +895,12 @@ function buildAnswersFromCliArgs(config) {
         answers.preset = config.preset;
     if (config.presetChoices)
         answers.presetChoices = config.presetChoices;
+    if (config.target)
+        answers.target = config.target;
+    if (config.minimal !== undefined)
+        answers.minimal = config.minimal;
+    if (config.editor)
+        answers.editor = config.editor;
     return answers;
 }
 /**
@@ -768,157 +945,6 @@ function mergeAnswers(...partials) {
     }
     return merged;
 }
-/**
- * List available overlays command
- */
-async function listOverlays(options) {
-    try {
-        const overlaysConfig = loadOverlaysConfigWrapper();
-        const category = options.category?.toLowerCase();
-        console.log('\n' +
-            boxen(chalk.bold('Available Overlays'), {
-                padding: 0.5,
-                borderColor: 'cyan',
-                borderStyle: 'round',
-            }));
-        const categories = [
-            { name: 'language', title: '📚 Language & Framework' },
-            { name: 'database', title: '🗄️  Database & Messaging' },
-            { name: 'observability', title: '📊 Observability' },
-            { name: 'cloud', title: '☁️  Cloud Tools' },
-            { name: 'dev', title: '🔧 Dev Tools' },
-            { name: 'preset', title: '🎯 Presets' },
-        ];
-        for (const cat of categories) {
-            if (category && cat.name !== category)
-                continue;
-            const overlays = overlaysConfig.overlays.filter((o) => o.category === cat.name);
-            if (overlays.length === 0)
-                continue;
-            console.log(`\n${chalk.bold(cat.title)}`);
-            for (const overlay of overlays) {
-                console.log(`  ${chalk.cyan(overlay.id.padEnd(20))} ${chalk.gray(overlay.description)}`);
-            }
-        }
-        console.log(chalk.dim(`\n💡 Use "container-superposition init --language nodejs,python --database postgres" to compose overlays\n`));
-        process.exit(0);
-    }
-    catch (error) {
-        console.error(chalk.red('✗ Error listing overlays:'), error);
-        process.exit(1);
-    }
-}
-/**
- * Doctor command - check environment and validate configuration
- */
-async function runDoctor(options) {
-    try {
-        const outputPath = options.output || './.devcontainer';
-        console.log('\n' +
-            boxen(chalk.bold('Environment Check'), {
-                padding: 0.5,
-                borderColor: 'cyan',
-                borderStyle: 'round',
-            }));
-        const checks = [];
-        // Helper function for semantic version comparison
-        const isVersionAtLeast = (current, required) => {
-            const parse = (v) => {
-                const parts = v.split('.');
-                const major = parseInt(parts[0] ?? '0', 10) || 0;
-                const minor = parseInt(parts[1] ?? '0', 10) || 0;
-                const patch = parseInt(parts[2] ?? '0', 10) || 0;
-                return [major, minor, patch];
-            };
-            const [cMajor, cMinor, cPatch] = parse(current);
-            const [rMajor, rMinor, rPatch] = parse(required);
-            if (cMajor !== rMajor) {
-                return cMajor > rMajor;
-            }
-            if (cMinor !== rMinor) {
-                return cMinor > rMinor;
-            }
-            return cPatch >= rPatch;
-        };
-        // Check Node.js version
-        const nodeVersion = process.version;
-        const requiredVersion = '20.0.0';
-        const versionMatch = nodeVersion.match(/^v(\d+\.\d+\.\d+)/);
-        const currentVersion = versionMatch ? versionMatch[1] : '0.0.0';
-        const nodeOk = isVersionAtLeast(currentVersion, requiredVersion);
-        checks.push({
-            name: 'Node.js version',
-            status: nodeOk,
-            message: nodeOk
-                ? `${nodeVersion} ✓`
-                : `${nodeVersion} (requires >= ${requiredVersion})`,
-        });
-        // Check if Docker is available
-        let dockerOk = false;
-        try {
-            const { execSync } = await import('child_process');
-            execSync('docker --version', { stdio: 'ignore' });
-            dockerOk = true;
-        }
-        catch {
-            dockerOk = false;
-        }
-        checks.push({
-            name: 'Docker',
-            status: dockerOk,
-            message: dockerOk ? 'Available ✓' : 'Not found (required for devcontainers)',
-        });
-        // Check if devcontainer exists
-        const devcontainerExists = fs.existsSync(outputPath);
-        checks.push({
-            name: 'Devcontainer path',
-            status: devcontainerExists,
-            message: devcontainerExists
-                ? `${outputPath} exists ✓`
-                : `${outputPath} not found (run init first)`,
-        });
-        // Check if manifest exists
-        if (devcontainerExists) {
-            const manifestPath = path.join(outputPath, 'superposition.json');
-            const manifestExists = fs.existsSync(manifestPath);
-            checks.push({
-                name: 'Manifest',
-                status: manifestExists,
-                message: manifestExists
-                    ? 'superposition.json found ✓'
-                    : 'superposition.json missing (manual edit or old version)',
-            });
-            // Check devcontainer.json
-            const devcontainerJsonPath = path.join(outputPath, 'devcontainer.json');
-            const devcontainerJsonExists = fs.existsSync(devcontainerJsonPath);
-            checks.push({
-                name: 'DevContainer config',
-                status: devcontainerJsonExists,
-                message: devcontainerJsonExists
-                    ? 'devcontainer.json found ✓'
-                    : 'devcontainer.json missing',
-            });
-        }
-        console.log('');
-        for (const check of checks) {
-            const icon = check.status ? chalk.green('✓') : chalk.red('✗');
-            console.log(`  ${icon} ${chalk.white(check.name)}: ${chalk.gray(check.message)}`);
-        }
-        const allPassed = checks.every((c) => c.status);
-        if (allPassed) {
-            console.log(chalk.green('\n✓ All checks passed!\n'));
-            process.exit(0);
-        }
-        else {
-            console.log(chalk.yellow('\n⚠ Some checks failed. See above for details.\n'));
-            process.exit(1);
-        }
-    }
-    catch (error) {
-        console.error(chalk.red('✗ Error running doctor:'), error);
-        process.exit(1);
-    }
-}
 /**
  * Parse CLI arguments
  */
@@ -929,14 +955,14 @@ async function parseCliArgs() {
     program
         .name('container-superposition')
         .description('Composable devcontainer scaffolds')
-        .version('0.1.0');
+        .version(getToolVersion());
     // Init command (default)
     program
         .command('init', { isDefault: true })
         .description('Initialize a new devcontainer configuration')
         .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('--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')
@@ -946,7 +972,13 @@ async function parseCliArgs() {
         .option('--cloud-tools <list>', 'Comma-separated: aws-cli, azure-cli, gcloud, kubectl-helm, terraform, pulumi')
         .option('--dev-tools <list>', 'Comma-separated: docker-in-docker, docker-sock, playwright, codex, git-helpers, pre-commit, commitlint, just, direnv, modern-cli-tools, ngrok')
         .option('--port-offset <number>', 'Add offset to all exposed ports (e.g., 100 makes Grafana 3100 instead of 3000)')
+        .option('--target <environment>', 'Deployment target: local, codespaces, gitpod, devpod (optimizes for environment)', 'local')
+        .option('--minimal', 'Minimal mode - exclude optional/nice-to-have features and extensions')
+        .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')
+        .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) => {
         // Store options for main() to process
         initOptions = options;
@@ -956,14 +988,31 @@ async function parseCliArgs() {
         .command('regen')
         .description('Regenerate devcontainer 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';
-        const manifestPath = path.join(outputPath, 'superposition.json');
-        if (!fs.existsSync(manifestPath)) {
-            console.error(chalk.red(`✗ Error: No manifest found at ${manifestPath}`));
-            console.error(chalk.gray('  Run "container-superposition init" first to create a configuration'));
+        // 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
@@ -978,16 +1027,51 @@ async function parseCliArgs() {
         .command('list')
         .description('List available overlays and presets')
         .option('--category <type>', 'Filter by category: language, database, observability, cloud, dev, preset')
+        .option('--tags <list>', 'Filter by tags (comma-separated)')
+        .option('--supports <stack>', 'Filter by stack support: plain, compose')
+        .option('--json', 'Output as JSON for scripting')
+        .action(async (options) => {
+        const overlaysConfig = loadOverlaysConfigWrapper();
+        await listCommand(overlaysConfig, options);
+        process.exit(0);
+    });
+    // Explain command
+    program
+        .command('explain <overlay>')
+        .description('Show detailed information about an overlay')
+        .option('--json', 'Output as JSON for scripting')
+        .action(async (overlayId, options) => {
+        const overlaysConfig = loadOverlaysConfigWrapper();
+        await explainCommand(overlaysConfig, OVERLAYS_DIR, overlayId, options);
+        process.exit(0);
+    });
+    // Plan command
+    program
+        .command('plan')
+        .description('Preview what will be generated before creating devcontainer')
+        .option('--stack <type>', 'Base template: plain, compose', 'compose')
+        .option('--overlays <list>', 'Comma-separated list of overlay IDs')
+        .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('--json', 'Output as JSON for scripting')
         .action(async (options) => {
-        await listOverlays(options);
+        const overlaysConfig = loadOverlaysConfigWrapper();
+        await planCommand(overlaysConfig, OVERLAYS_DIR, options);
+        process.exit(0);
     });
     // Doctor command
     program
         .command('doctor')
         .description('Check environment and validate configuration')
         .option('-o, --output <path>', 'Devcontainer path to validate (default: ./.devcontainer)')
+        .option('--fix', 'Apply automatic fixes where possible')
+        .option('--json', 'Output as JSON for scripting')
         .action(async (options) => {
-        await runDoctor(options);
+        const overlaysConfig = loadOverlaysConfigWrapper();
+        await doctorCommand(overlaysConfig, OVERLAYS_DIR, options);
     });
     await program.parseAsync(process.argv);
     // If init or regen command was run, return the options
@@ -1030,14 +1114,61 @@ async function parseCliArgs() {
     if (initOptions.portOffset) {
         config.portOffset = parseInt(initOptions.portOffset, 10);
     }
+    if (initOptions.target) {
+        config.target = initOptions.target;
+    }
+    if (initOptions.minimal) {
+        config.minimal = true;
+    }
+    if (initOptions.editor) {
+        const editorLower = initOptions.editor.toLowerCase();
+        if (['vscode', 'jetbrains', 'none'].includes(editorLower)) {
+            config.editor = editorLower;
+        }
+        else {
+            console.warn(chalk.yellow(`⚠️  Invalid editor profile: ${initOptions.editor}, using default (vscode)`));
+            config.editor = 'vscode';
+        }
+    }
     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 {
         config,
         manifestPath: initOptions.fromManifest,
-        noBackup: initOptions.backup === false, // Commander creates options.backup = false for --no-backup
+        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,
     };
 }
 async function main() {
@@ -1051,7 +1182,6 @@ async function main() {
         }
         let manifest;
         let manifestDir;
-        let shouldBackup = true;
         let backupDir;
         let useManifestOnly = false;
         // Handle manifest loading
@@ -1068,10 +1198,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;
             }
@@ -1079,20 +1206,51 @@ async function main() {
                 useManifestOnly = true;
             }
         }
+        // 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 backupCheckPath = path.resolve(cliArgs?.config?.outputPath || manifestDir || './.devcontainer');
+        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'));
+            }
+        }
         // Create backup if needed
+        let actualBackupPath;
         if (shouldBackup && manifest) {
             // Output path is the directory containing the manifest
             const outputPath = manifestDir || './.devcontainer';
             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;
-        if (useManifestOnly && manifest) {
-            // Mode 1: Manifest-only (--from-manifest --no-interactive)
+        const isRegen = !!manifest;
+        // 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' &&
+                cliArgs.config[key] !== undefined);
+        if (useManifestOnly && manifest && !hasCliOverrides) {
+            // Mode 1: Manifest-only (--from-manifest --no-interactive, no CLI overrides)
             const manifestAnswers = buildAnswersFromManifest(manifest, manifestDir);
             answers = mergeAnswers(manifestAnswers);
             console.log('\n' +
@@ -1110,8 +1268,9 @@ async function main() {
                         : '') +
                     chalk.gray(`  Output: ${answers.outputPath}`), { padding: 1, borderColor: 'cyan', borderStyle: 'round', margin: 1 }));
         }
-        else if (cliArgs && cliArgs.config.stack) {
+        else if (cliArgs && (cliArgs.config.stack || hasCliOverrides)) {
             // 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)
@@ -1119,16 +1278,30 @@ async function main() {
             answers = mergeAnswers(manifestAnswers, cliAnswers, {
                 outputPath: cliAnswers.outputPath || './.devcontainer',
             });
+            const modeLabel = useManifestOnly && hasCliOverrides
+                ? 'Regenerating from Manifest with Overrides'
+                : 'Running in CLI mode';
             console.log('\n' +
-                boxen(chalk.bold('Running in CLI mode'), {
+                boxen(chalk.bold(modeLabel), {
                     padding: 0.5,
                     borderColor: 'blue',
                     borderStyle: 'round',
                 }));
+            // Show what's being overridden
+            if (useManifestOnly && hasCliOverrides) {
+                const overrides = [];
+                if (cliAnswers.minimal)
+                    overrides.push('minimal mode');
+                if (cliAnswers.editor)
+                    overrides.push(`editor: ${cliAnswers.editor}`);
+                if (overrides.length > 0) {
+                    console.log(chalk.dim(`   Overrides: ${overrides.join(', ')}`));
+                }
+            }
         }
         else {
-            // Mode 3: Interactive (with optional manifest pre-population)
-            const interactiveAnswers = await runQuestionnaire(manifest, manifestDir);
+            // Mode 3: Interactive (with optional manifest pre-population and CLI preset pre-selection)
+            const interactiveAnswers = await runQuestionnaire(manifest, manifestDir, cliArgs?.config.preset, cliArgs?.config.presetChoices);
             answers = mergeAnswers(interactiveAnswers);
         }
         // Show configuration summary
@@ -1157,27 +1330,36 @@ async function main() {
                 borderStyle: 'round',
                 margin: { top: 0, bottom: 1 },
             }));
+        // Check if we're in manifest-only mode
+        const isManifestOnly = cliArgs?.writeManifestOnly === true;
         // Generate with spinner
         const spinner = ora({
-            text: chalk.cyan('Generating devcontainer configuration...'),
+            text: isManifestOnly
+                ? chalk.cyan('Generating manifest file...')
+                : chalk.cyan('Generating devcontainer configuration...'),
             color: 'cyan',
         }).start();
         try {
-            await composeDevContainer(answers);
-            spinner.succeed(chalk.green('DevContainer created successfully!'));
+            let summary;
+            if (isManifestOnly) {
+                summary = await generateManifestOnly(answers, undefined, { isRegen });
+                spinner.succeed(chalk.green('Manifest created successfully!'));
+            }
+            else {
+                summary = await composeDevContainer(answers, undefined, { isRegen });
+                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('Failed to create devcontainer'));
+            spinner.fail(chalk.red(isManifestOnly ? 'Failed to create manifest' : 'Failed to create devcontainer'));
             throw error;
         }
-        // Success message
-        console.log('\n' +
-            boxen(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.'), { padding: 1, borderColor: 'green', borderStyle: 'double', margin: 1 }));
     }
     catch (error) {
         console.error('\n' +