container-superposition 0.1.3 → 0.1.4

package/dist/scripts/init.js

@@ -2,6 +2,7 @@
 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';
@@ -17,6 +18,8 @@ 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);
@@ -65,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: {} };
@@ -73,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;
+            }
+        }
+    }
+    // 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`));
+    return { overlays: uniqueOverlays, choices, glueConfig: preset.glueConfig };
 }
 /**
  * Search for manifest file in multiple locations
@@ -158,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
  */
@@ -241,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'));
     }
 }
 /**
@@ -297,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' +
@@ -331,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
@@ -369,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.
@@ -881,7 +962,7 @@ async function parseCliArgs() {
         .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')
@@ -896,6 +977,8 @@ 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')
+        .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;
@@ -905,7 +988,7 @@ 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')
@@ -969,6 +1052,10 @@ async function parseCliArgs() {
         .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) => {
         const overlaysConfig = loadOverlaysConfigWrapper();
@@ -1045,10 +1132,40 @@ 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 {
         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,
@@ -1065,7 +1182,6 @@ async function main() {
         }
         let manifest;
         let manifestDir;
-        let shouldBackup = true;
         let backupDir;
         let useManifestOnly = false;
         // Handle manifest loading
@@ -1082,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;
             }
@@ -1093,21 +1206,48 @@ 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;
-        // Check if there are CLI overrides beyond just output path
+        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)
@@ -1160,8 +1300,8 @@ async function main() {
             }
         }
         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
@@ -1200,40 +1340,26 @@ async function main() {
             color: 'cyan',
         }).start();
         try {
+            let summary;
             if (isManifestOnly) {
-                await generateManifestOnly(answers);
+                summary = await generateManifestOnly(answers, undefined, { isRegen });
                 spinner.succeed(chalk.green('Manifest created successfully!'));
             }
             else {
-                await composeDevContainer(answers);
+                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(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' +