container-superposition 0.1.4 → 0.1.6

package/dist/scripts/init.js

@@ -2,7 +2,6 @@
 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';
@@ -15,11 +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 { appendGitignoreSection } from '../tool/utils/gitignore.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);
@@ -65,6 +67,100 @@ 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
  */
@@ -141,7 +237,17 @@ async function expandPreset(presetId, stack, preProvidedChoices = {}) {
     // Deduplicate overlays
     const uniqueOverlays = [...new Set(overlays)];
     console.log(chalk.dim(`✓ Preset will include: ${uniqueOverlays.join(', ')}\n`));
-    return { overlays: uniqueOverlays, choices, glueConfig: preset.glueConfig };
+    // 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
@@ -164,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
  */
@@ -210,127 +326,6 @@ 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
- */
-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
- */
-function ensureBackupPatternsInGitignore(outputPath) {
-    const projectRoot = path.dirname(path.resolve(outputPath));
-    const gitignorePath = path.join(projectRoot, '.gitignore');
-    const written = appendGitignoreSection(gitignorePath, 'container-superposition backups', [
-        '.devcontainer.backup-*/',
-        '*.backup-*',
-        'superposition.json.backup-*',
-    ]);
-    if (written) {
-        console.log(chalk.dim('   📝 Updated .gitignore with backup patterns'));
-    }
-}
 /**
  * Build checkbox choices for overlay selection with optional pre-selection
  */
@@ -360,7 +355,7 @@ function buildOverlayChoices(config, stack, categoryList, preselected) {
 /**
  * Interactive questionnaire with modern checkbox selections
  */
-async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetChoices) {
+async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetChoices, defaultAnswers) {
     const config = loadOverlaysConfigWrapper();
     // Pretty banner
     console.log('\n' +
@@ -448,7 +443,7 @@ async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetCho
                 value: t.id,
                 description: t.description,
             })),
-            default: manifest?.baseTemplate,
+            default: manifest?.baseTemplate || defaultAnswers?.stack,
         }));
         // If using preset, expand it now (pass pre-provided choices to skip those prompts)
         if (usePreset && selectedPresetId) {
@@ -473,7 +468,15 @@ async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetCho
         // 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) => ({
@@ -481,16 +484,17 @@ async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetCho
                 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';
@@ -606,7 +610,15 @@ async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetCho
         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,
@@ -683,11 +695,11 @@ async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetCho
         // 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,
@@ -695,7 +707,11 @@ async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetCho
         // 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
@@ -790,7 +806,10 @@ async function runQuestionnaire(manifest, manifestDir, cliPresetId, cliPresetCho
             observability,
             outputPath,
             portOffset,
-            target,
+            target: target ?? defaultAnswers?.target,
+            minimal: defaultAnswers?.minimal,
+            editor: defaultAnswers?.editor,
+            customizations: defaultAnswers?.customizations,
         };
     }
     catch (error) {
@@ -960,8 +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('--project-root <path>', 'Run project-file and manifest discovery relative to a different repository root')
         .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-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')
@@ -979,47 +1000,33 @@ async function parseCliArgs() {
         .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) => {
+        .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('--project-root <path>', 'Run project-file and manifest discovery relative to a different repository root')
+        .option('--from-manifest <path>', 'Load configuration from existing superposition.json manifest')
         .option('-o, --output <path>', 'Output path (default: ./.devcontainer)')
         .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
@@ -1049,13 +1056,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();
@@ -1073,6 +1082,40 @@ 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('--project-file', 'Also write a repository-root project config (.superposition.yml or existing project file)')
+        .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) {
@@ -1083,6 +1126,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;
@@ -1114,13 +1185,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;
@@ -1163,8 +1234,11 @@ async function parseCliArgs() {
         }
     }
     return {
+        commandName: initOptions.commandName,
         config,
         manifestPath: initOptions.fromManifest,
+        fromProject: initOptions.fromProject === true,
+        projectRoot: initOptions.projectRoot,
         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
@@ -1174,16 +1248,47 @@ 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);
+        const initialCwd = process.cwd();
+        if (cliArgs?.projectRoot) {
+            const resolvedProjectRoot = path.resolve(initialCwd, cliArgs.projectRoot);
+            if (!fs.existsSync(resolvedProjectRoot)) {
+                console.error(chalk.red(`✗ Project root not found: ${resolvedProjectRoot}`));
+                process.exit(1);
+            }
+            if (!fs.statSync(resolvedProjectRoot).isDirectory()) {
+                console.error(chalk.red(`✗ Project root is not a directory: ${resolvedProjectRoot}`));
+                process.exit(1);
+            }
+            process.chdir(resolvedProjectRoot);
+        }
+        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 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);
@@ -1206,12 +1311,30 @@ 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 backupCheckPath = path.resolve(cliArgs?.config?.outputPath || manifestDir || './.devcontainer');
+        const resolvedOutputPath = cliArgs?.config?.outputPath ||
+            projectConfigAnswers?.outputPath ||
+            manifestDir ||
+            './.devcontainer';
+        const backupCheckPath = path.resolve(resolvedOutputPath);
         const inGitRepo = isInsideGitRepo(backupCheckPath);
         let shouldBackup;
         if (cliArgs?.backupOverride === true) {
@@ -1227,11 +1350,11 @@ async function main() {
                 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
         let actualBackupPath;
-        if (shouldBackup && manifest) {
-            // Output path is the directory containing the manifest
-            const outputPath = manifestDir || './.devcontainer';
+        if (shouldBackup && isReplayMode) {
+            const outputPath = resolvedOutputPath;
             const backupPath = await createBackup(outputPath, backupDir);
             if (backupPath) {
                 actualBackupPath = backupPath;
@@ -1241,14 +1364,19 @@ async function main() {
         }
         // Build answers based on mode
         let answers;
-        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' &&
+                !(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);
@@ -1268,19 +1396,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,
@@ -1288,7 +1441,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');
@@ -1301,8 +1454,15 @@ async function main() {
         }
         else {
             // 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);
+            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 = [
@@ -1322,6 +1482,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'), {
@@ -1342,11 +1505,13 @@ async function main() {
         try {
             let summary;
             if (isManifestOnly) {
-                summary = await generateManifestOnly(answers, undefined, { isRegen });
+                summary = await generateManifestOnly(answers, undefined, {
+                    isRegen: isReplayMode,
+                });
                 spinner.succeed(chalk.green('Manifest created successfully!'));
             }
             else {
-                summary = await composeDevContainer(answers, undefined, { isRegen });
+                summary = await composeDevContainer(answers, undefined, { isRegen: isReplayMode });
                 spinner.succeed(chalk.green('DevContainer created successfully!'));
             }
             // Update summary with backup path and regen status