container-superposition 0.1.5 → 0.1.6

package/dist/tool/commands/adopt.js

@@ -12,11 +12,21 @@ import boxen from 'boxen';
 import yaml from 'js-yaml';
 import { confirm } from '@inquirer/prompts';
 import { CURRENT_MANIFEST_VERSION } from '../schema/manifest-migrations.js';
+import { findProjectConfig, writeProjectConfig } from '../schema/project-config.js';
+import { applyOverlay } from '../questionnaire/composer.js';
+import { deepMerge } from '../utils/merge.js';
 import { getToolVersion } from '../utils/version.js';
 import { isInsideGitRepo, createBackup, ensureBackupPatternsInGitignore } from '../utils/backup.js';
 // Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const REPO_ROOT_CANDIDATES = [
+    path.join(__dirname, '..', '..'),
+    path.join(__dirname, '..', '..', '..'),
+];
+const REPO_ROOT = REPO_ROOT_CANDIDATES.find((candidate) => fs.existsSync(path.join(candidate, 'templates')) &&
+    fs.existsSync(path.join(candidate, 'overlays'))) ?? REPO_ROOT_CANDIDATES[0];
+const TEMPLATES_DIR = path.join(REPO_ROOT, 'templates');
 /**
  * Strip the version suffix from a devcontainer feature URI so that prefix
  * matching works regardless of pinned version.
@@ -118,6 +128,16 @@ export function buildDetectionTables(overlaysDir, overlaysConfig) {
                     const lc = extId.toLowerCase();
                     const score = extensionMatchScore(overlay.id, lc);
                     const existing = extensionToOverlayScored[lc];
+                    if (score === SCORE_NO_MATCH) {
+                        if (!existing) {
+                            extensionToOverlayScored[lc] = { overlayId: overlay.id, score };
+                        }
+                        else if (existing.score === SCORE_NO_MATCH &&
+                            existing.overlayId !== overlay.id) {
+                            delete extensionToOverlayScored[lc];
+                        }
+                        continue;
+                    }
                     if (!existing || score > existing.score) {
                         extensionToOverlayScored[lc] = { overlayId: overlay.id, score };
                     }
@@ -260,6 +280,18 @@ function analyseDockerCompose(composePaths, tables) {
         }
         for (const [serviceName, serviceDef] of Object.entries(parsed?.services ?? {})) {
             const image = serviceDef?.image ?? '';
+            const volumes = Array.isArray(serviceDef?.volumes)
+                ? serviceDef.volumes
+                : [];
+            if (volumes.some((volume) => typeof volume === 'string' &&
+                volume.includes('/var/run/docker.sock:/var/run/docker-host.sock'))) {
+                detections.push({
+                    source: `service: ${serviceName} (docker socket mount)`,
+                    overlayId: 'docker-sock',
+                    confidence: 'heuristic',
+                    sourceType: 'service',
+                });
+            }
             if (!image)
                 continue;
             const overlayId = matchImage(image, tables);
@@ -315,6 +347,205 @@ function analyseRemoteEnv(devcontainer, tables) {
     }
     return { detections, unmatchedRemoteEnv };
 }
+function normalizeCommandMap(commands) {
+    if (typeof commands === 'string') {
+        return { entries: { default: commands }, isString: true };
+    }
+    if (!commands || typeof commands !== 'object' || Array.isArray(commands)) {
+        return null;
+    }
+    const entries = {};
+    for (const [key, value] of Object.entries(commands)) {
+        if (typeof value === 'string') {
+            entries[key] = value;
+        }
+    }
+    return Object.keys(entries).length > 0 ? { entries, isString: false } : null;
+}
+function findOverlayIdsInCommandMap(commands, overlaysConfig) {
+    const normalized = normalizeCommandMap(commands);
+    if (!normalized) {
+        return [];
+    }
+    const knownOverlays = new Set(overlaysConfig.overlays.map((overlay) => overlay.id));
+    const detections = new Map();
+    for (const [key, value] of Object.entries(normalized.entries)) {
+        const patterns = [
+            key.match(/^(?:setup|verify)-([a-z0-9-]+)$/i),
+            value.match(/(?:^|\/)(?:setup|verify)-([a-z0-9-]+)\.sh\b/i),
+        ];
+        for (const match of patterns) {
+            const overlayId = match?.[1];
+            if (!overlayId || !knownOverlays.has(overlayId) || detections.has(overlayId)) {
+                continue;
+            }
+            detections.set(overlayId, {
+                source: `command: ${key}`,
+                overlayId,
+                confidence: 'heuristic',
+                sourceType: 'script',
+            });
+        }
+    }
+    return Array.from(detections.values());
+}
+function analyseCommands(devcontainer, overlaysConfig) {
+    return {
+        detections: [
+            ...findOverlayIdsInCommandMap(devcontainer.postCreateCommand, overlaysConfig),
+            ...findOverlayIdsInCommandMap(devcontainer.postStartCommand, overlaysConfig),
+        ],
+    };
+}
+function loadJsonFile(filePath, fallback) {
+    if (!fs.existsSync(filePath)) {
+        return fallback;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+function loadYamlFile(filePath, fallback) {
+    if (!fs.existsSync(filePath)) {
+        return fallback;
+    }
+    try {
+        return yaml.load(fs.readFileSync(filePath, 'utf8')) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+function inferBaseImageSelection(devcontainer, composePaths, overlaysConfig, stack) {
+    let image;
+    if (stack === 'compose') {
+        for (const composePath of composePaths) {
+            const compose = loadYamlFile(composePath, {});
+            const composeImage = compose?.services?.devcontainer?.image;
+            if (typeof composeImage === 'string' && composeImage.trim() !== '') {
+                image = composeImage.trim();
+                break;
+            }
+        }
+    }
+    else if (typeof devcontainer?.image === 'string' && devcontainer.image.trim() !== '') {
+        image = devcontainer.image.trim();
+    }
+    if (!image) {
+        return { baseImage: 'bookworm' };
+    }
+    const matchedBaseImage = overlaysConfig.base_images.find((entry) => entry.image === image);
+    if (matchedBaseImage && matchedBaseImage.id !== 'custom') {
+        return { baseImage: matchedBaseImage.id };
+    }
+    return { baseImage: 'custom', customImage: image };
+}
+function addGeneratedOverlayCommands(config, overlayIds, overlaysDir) {
+    const nextConfig = { ...config };
+    const setupOverlays = overlayIds.filter((overlayId) => fs.existsSync(path.join(overlaysDir, overlayId, 'setup.sh')));
+    const verifyOverlays = overlayIds.filter((overlayId) => fs.existsSync(path.join(overlaysDir, overlayId, 'verify.sh')));
+    if (setupOverlays.length > 0) {
+        const postCreate = nextConfig.postCreateCommand &&
+            typeof nextConfig.postCreateCommand === 'object' &&
+            !Array.isArray(nextConfig.postCreateCommand)
+            ? { ...nextConfig.postCreateCommand }
+            : {};
+        for (const overlayId of setupOverlays) {
+            postCreate[`setup-${overlayId}`] = `bash .devcontainer/scripts/setup-${overlayId}.sh`;
+        }
+        nextConfig.postCreateCommand = postCreate;
+    }
+    if (verifyOverlays.length > 0) {
+        const postStart = nextConfig.postStartCommand &&
+            typeof nextConfig.postStartCommand === 'object' &&
+            !Array.isArray(nextConfig.postStartCommand)
+            ? { ...nextConfig.postStartCommand }
+            : {};
+        for (const overlayId of verifyOverlays) {
+            postStart[`verify-${overlayId}`] = `bash .devcontainer/scripts/verify-${overlayId}.sh`;
+        }
+        nextConfig.postStartCommand = postStart;
+    }
+    return nextConfig;
+}
+function buildExpectedDevcontainerConfig(stack, overlayIds, overlaysDir) {
+    const templatePath = path.join(TEMPLATES_DIR, stack, '.devcontainer', 'devcontainer.json');
+    let config = loadJsonFile(templatePath, {});
+    for (const overlayId of overlayIds) {
+        config = applyOverlay(config, overlayId, overlaysDir);
+    }
+    return addGeneratedOverlayCommands(config, overlayIds, overlaysDir);
+}
+function buildExpectedComposeConfig(overlayIds, overlaysDir, baseImageSelection, overlaysConfig) {
+    const templatePath = path.join(TEMPLATES_DIR, 'compose', '.devcontainer', 'docker-compose.yml');
+    let composeConfig = loadYamlFile(templatePath, {});
+    for (const overlayId of overlayIds) {
+        const overlayComposePath = path.join(overlaysDir, overlayId, 'docker-compose.yml');
+        if (!fs.existsSync(overlayComposePath)) {
+            continue;
+        }
+        composeConfig = deepMerge(composeConfig, loadYamlFile(overlayComposePath, {}));
+    }
+    const image = baseImageSelection.baseImage === 'custom'
+        ? baseImageSelection.customImage
+        : overlaysConfig.base_images.find((entry) => entry.id === baseImageSelection.baseImage)
+            ?.image;
+    if (image) {
+        composeConfig = {
+            ...composeConfig,
+            services: {
+                ...(composeConfig.services ?? {}),
+                devcontainer: {
+                    ...(composeConfig.services?.devcontainer ?? {}),
+                    image,
+                },
+            },
+        };
+    }
+    return composeConfig;
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function subtractDefaults(actual, expected) {
+    if (actual === undefined) {
+        return undefined;
+    }
+    if (expected === undefined) {
+        return deepClone(actual);
+    }
+    if (Array.isArray(actual)) {
+        if (!Array.isArray(expected)) {
+            return deepClone(actual);
+        }
+        const filtered = actual.filter((item) => !expected.some((expectedItem) => JSON.stringify(expectedItem) === JSON.stringify(item)));
+        return filtered.length > 0 ? filtered : undefined;
+    }
+    if (isPlainObject(actual)) {
+        if (!isPlainObject(expected)) {
+            return deepClone(actual);
+        }
+        const result = {};
+        for (const [key, value] of Object.entries(actual)) {
+            const diff = subtractDefaults(value, expected[key]);
+            if (diff !== undefined &&
+                (!isPlainObject(diff) ||
+                    Object.keys(diff).length > 0 ||
+                    expected[key] === undefined) &&
+                (!Array.isArray(diff) || diff.length > 0)) {
+                result[key] = diff;
+            }
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    return actual === expected ? undefined : actual;
+}
 /**
  * Deduplicate: keep one entry per overlayId, preferring `exact` over `heuristic`.
  */
@@ -380,68 +611,123 @@ function buildSuggestedCommand(overlayIds, stack, overlaysConfig) {
         parts.push(`--overlays ${other.join(',')}`);
     return parts.join(' ');
 }
-function buildCustomDevcontainerPatch(devcontainer, unmatchedFeatures, unmatchedExtensions, unmatchedRemoteEnv) {
-    const patch = {};
-    if (Object.keys(unmatchedFeatures).length > 0) {
-        patch.features = unmatchedFeatures;
-    }
-    // Preserve all customizations, merging unmatched extensions into vscode.extensions.
-    // Other customizations fields (e.g. vscode.settings, jetbrains, ...) are carried through
-    // verbatim so the migration is lossless.
-    const originalCustomizations = devcontainer.customizations && typeof devcontainer.customizations === 'object'
-        ? devcontainer.customizations
-        : null;
-    if (unmatchedExtensions.length > 0 || originalCustomizations) {
-        const customizationsPatch = originalCustomizations
-            ? { ...originalCustomizations }
-            : {};
-        if (unmatchedExtensions.length > 0) {
-            const originalVscode = originalCustomizations?.vscode && typeof originalCustomizations.vscode === 'object'
-                ? { ...originalCustomizations.vscode }
-                : {};
-            const originalExtensions = Array.isArray(originalVscode.extensions)
-                ? originalVscode.extensions
-                : [];
-            // Order: existing extensions first so load order is preserved, then new unmatched ones
-            const mergedExtensions = Array.from(new Set([...originalExtensions, ...unmatchedExtensions]));
-            customizationsPatch.vscode = {
-                ...originalVscode,
-                extensions: mergedExtensions,
-            };
-        }
-        if (Object.keys(customizationsPatch).length > 0) {
-            patch.customizations = customizationsPatch;
+function categorizeOverlayIds(overlayIds, overlaysConfig) {
+    const selection = {};
+    for (const id of overlayIds) {
+        const overlay = overlaysConfig.overlays.find((entry) => entry.id === id);
+        if (!overlay)
+            continue;
+        switch (overlay.category) {
+            case 'language':
+                selection.language = [...(selection.language ?? []), id];
+                break;
+            case 'database':
+                selection.database = [...(selection.database ?? []), id];
+                break;
+            case 'observability':
+                selection.observability = [...(selection.observability ?? []), id];
+                break;
+            case 'cloud':
+                selection.cloudTools = [...(selection.cloudTools ?? []), id];
+                break;
+            case 'dev':
+                selection.devTools = [...(selection.devTools ?? []), id];
+                break;
         }
     }
+    return selection;
+}
+function toProjectRelativePath(targetPath, projectRoot) {
+    const relativePath = path.relative(projectRoot, targetPath).split(path.sep).join('/');
+    if (relativePath === '' || relativePath === '.') {
+        return './';
+    }
+    if (relativePath.startsWith('./') || relativePath.startsWith('../')) {
+        return relativePath;
+    }
+    return `./${relativePath}`;
+}
+function buildProjectConfigSelection(analysis, overlaysConfig, projectRoot, absoluteDir, devcontainer) {
+    const composePaths = resolveComposePaths(devcontainer, absoluteDir);
+    const baseImageSelection = inferBaseImageSelection(devcontainer, composePaths, overlaysConfig, analysis.suggestedStack);
+    const selection = {
+        stack: analysis.suggestedStack,
+        baseImage: baseImageSelection.baseImage,
+        customImage: baseImageSelection.customImage,
+        outputPath: toProjectRelativePath(absoluteDir, projectRoot),
+        containerName: typeof devcontainer?.name === 'string' && devcontainer.name.trim() !== ''
+            ? devcontainer.name.trim()
+            : undefined,
+        ...categorizeOverlayIds(analysis.suggestedOverlays, overlaysConfig),
+    };
+    if (analysis.customDevcontainerPatch || analysis.customComposePatch) {
+        selection.customizations = {
+            devcontainerPatch: analysis.customDevcontainerPatch ?? undefined,
+            dockerComposePatch: analysis.customComposePatch ?? undefined,
+        };
+    }
+    return selection;
+}
+function buildCustomDevcontainerPatch(devcontainer, expectedConfig) {
+    const candidatePatch = {};
+    if (devcontainer.features) {
+        candidatePatch.features = devcontainer.features;
+    }
+    if (devcontainer.customizations) {
+        candidatePatch.customizations = devcontainer.customizations;
+    }
     if (Array.isArray(devcontainer.mounts) && devcontainer.mounts.length > 0) {
-        patch.mounts = devcontainer.mounts;
+        candidatePatch.mounts = devcontainer.mounts;
     }
-    if (devcontainer.remoteUser && devcontainer.remoteUser !== 'vscode') {
-        patch.remoteUser = devcontainer.remoteUser;
+    if (devcontainer.remoteUser) {
+        candidatePatch.remoteUser = devcontainer.remoteUser;
     }
-    // Lifecycle commands — included as-is; the user should review the custom/
-    // patch and remove anything that is already handled by overlay setup scripts.
     if (devcontainer.postCreateCommand) {
-        patch.postCreateCommand = devcontainer.postCreateCommand;
+        candidatePatch.postCreateCommand = devcontainer.postCreateCommand;
     }
     if (devcontainer.postStartCommand) {
-        patch.postStartCommand = devcontainer.postStartCommand;
+        candidatePatch.postStartCommand = devcontainer.postStartCommand;
+    }
+    if (devcontainer.remoteEnv) {
+        candidatePatch.remoteEnv = devcontainer.remoteEnv;
+    }
+    const expectedPatch = {};
+    if (expectedConfig.features) {
+        expectedPatch.features = expectedConfig.features;
     }
-    // Preserve remoteEnv keys not matched to any overlay so the migration is lossless.
-    if (Object.keys(unmatchedRemoteEnv).length > 0) {
-        patch.remoteEnv = unmatchedRemoteEnv;
+    if (expectedConfig.customizations) {
+        expectedPatch.customizations = expectedConfig.customizations;
     }
-    return Object.keys(patch).length > 0 ? patch : null;
+    if (expectedConfig.mounts) {
+        expectedPatch.mounts = expectedConfig.mounts;
+    }
+    if (expectedConfig.remoteUser) {
+        expectedPatch.remoteUser = expectedConfig.remoteUser;
+    }
+    if (expectedConfig.postCreateCommand) {
+        expectedPatch.postCreateCommand = expectedConfig.postCreateCommand;
+    }
+    if (expectedConfig.postStartCommand) {
+        expectedPatch.postStartCommand = expectedConfig.postStartCommand;
+    }
+    if (expectedConfig.remoteEnv) {
+        expectedPatch.remoteEnv = expectedConfig.remoteEnv;
+    }
+    const patch = subtractDefaults(candidatePatch, expectedPatch);
+    return patch && Object.keys(patch).length > 0 ? patch : null;
 }
-function buildCustomComposePatch(unmatchedServices) {
+function buildCustomComposePatch(unmatchedServices, expectedCompose) {
     if (Object.keys(unmatchedServices).length === 0)
         return null;
-    return { services: unmatchedServices };
+    const candidatePatch = { services: unmatchedServices };
+    const expectedPatch = { services: expectedCompose.services ?? {} };
+    const patch = subtractDefaults(candidatePatch, expectedPatch);
+    return patch?.services && Object.keys(patch.services).length > 0 ? patch : null;
 }
 // ---------------------------------------------------------------------------
 // Full analysis
 // ---------------------------------------------------------------------------
-export function analyseDevcontainer(dir, overlaysConfig, tables) {
+export function analyseDevcontainer(dir, overlaysConfig, tables, overlaysDir) {
     const devcontainerPath = path.join(dir, 'devcontainer.json');
     let devcontainer = {};
     if (fs.existsSync(devcontainerPath)) {
@@ -457,11 +743,13 @@ export function analyseDevcontainer(dir, overlaysConfig, tables) {
     const composeResult = analyseDockerCompose(composePaths, tables);
     const extensionResult = analyseExtensions(devcontainer, tables);
     const remoteEnvResult = analyseRemoteEnv(devcontainer, tables);
+    const commandResult = analyseCommands(devcontainer, overlaysConfig);
     const detections = deduplicateDetections([
         ...featureResult.detections,
         ...composeResult.detections,
         ...extensionResult.detections,
         ...remoteEnvResult.detections,
+        ...commandResult.detections,
     ]);
     const hasDockerCompose = composePaths.length > 0;
     const hasServiceSignals = detections.some((d) => d.sourceType === 'service');
@@ -469,41 +757,65 @@ export function analyseDevcontainer(dir, overlaysConfig, tables) {
     const knownIds = new Set(overlaysConfig.overlays.map((o) => o.id));
     const suggestedOverlays = [...new Set(detections.map((d) => d.overlayId))].filter((id) => knownIds.has(id));
     const suggestedCommand = buildSuggestedCommand(suggestedOverlays, suggestedStack, overlaysConfig);
-    // Unmatched item descriptions for display / JSON
+    const baseImageSelection = inferBaseImageSelection(devcontainer, composePaths, overlaysConfig, suggestedStack);
+    const expectedDevcontainerConfig = buildExpectedDevcontainerConfig(suggestedStack, suggestedOverlays, overlaysDir);
+    const expectedComposeConfig = suggestedStack === 'compose'
+        ? buildExpectedComposeConfig(suggestedOverlays, overlaysDir, baseImageSelection, overlaysConfig)
+        : {};
+    const customDevcontainerPatch = buildCustomDevcontainerPatch(devcontainer, expectedDevcontainerConfig);
+    const customComposePatch = buildCustomComposePatch(composeResult.unmatchedServices, expectedComposeConfig);
     const unmatchedItems = [];
-    for (const fid of Object.keys(featureResult.unmatchedFeatures)) {
+    for (const featureId of Object.keys(customDevcontainerPatch?.features ?? {})) {
         unmatchedItems.push({
-            source: fid,
+            source: featureId,
             reason: 'No overlay covers this feature — preserve in custom/devcontainer.patch.json',
         });
     }
-    for (const [name, def] of Object.entries(composeResult.unmatchedServices)) {
-        const image = def?.image ?? '(no image)';
-        unmatchedItems.push({
-            source: `service: ${name} (image: ${image})`,
-            reason: 'No overlay covers this service — preserve in custom/docker-compose.patch.yml',
-        });
-    }
-    for (const extId of extensionResult.unmatchedExtensions) {
+    const preservedExtensions = customDevcontainerPatch?.customizations?.vscode?.extensions ?? [];
+    for (const extensionId of preservedExtensions) {
         unmatchedItems.push({
-            source: `extension: ${extId}`,
+            source: `extension: ${extensionId}`,
             reason: 'No overlay installs this extension — preserve in custom/devcontainer.patch.json',
         });
     }
-    if (Array.isArray(devcontainer.mounts) && devcontainer.mounts.length > 0) {
+    if (Array.isArray(customDevcontainerPatch?.mounts) &&
+        customDevcontainerPatch.mounts.length > 0) {
         unmatchedItems.push({
-            source: `mounts (${devcontainer.mounts.length} mount(s))`,
+            source: `mounts (${customDevcontainerPatch.mounts.length} mount(s))`,
             reason: 'Custom mounts are not managed by overlays — preserve in custom/devcontainer.patch.json',
         });
     }
-    if (devcontainer.remoteUser && devcontainer.remoteUser !== 'vscode') {
+    if (customDevcontainerPatch?.remoteUser) {
         unmatchedItems.push({
-            source: `remoteUser: ${devcontainer.remoteUser}`,
+            source: `remoteUser: ${customDevcontainerPatch.remoteUser}`,
             reason: 'Custom remote user — preserve in custom/devcontainer.patch.json',
         });
     }
-    const customDevcontainerPatch = buildCustomDevcontainerPatch(devcontainer, featureResult.unmatchedFeatures, extensionResult.unmatchedExtensions, remoteEnvResult.unmatchedRemoteEnv);
-    const customComposePatch = buildCustomComposePatch(composeResult.unmatchedServices);
+    for (const [key] of Object.entries(customDevcontainerPatch?.remoteEnv ?? {})) {
+        unmatchedItems.push({
+            source: `remoteEnv: ${key}`,
+            reason: 'Custom environment variable — preserve in custom/devcontainer.patch.json',
+        });
+    }
+    for (const [key] of Object.entries(normalizeCommandMap(customDevcontainerPatch?.postCreateCommand)?.entries ?? {})) {
+        unmatchedItems.push({
+            source: `postCreateCommand: ${key}`,
+            reason: 'Custom lifecycle command — preserve in custom/devcontainer.patch.json',
+        });
+    }
+    for (const [key] of Object.entries(normalizeCommandMap(customDevcontainerPatch?.postStartCommand)?.entries ?? {})) {
+        unmatchedItems.push({
+            source: `postStartCommand: ${key}`,
+            reason: 'Custom lifecycle command — preserve in custom/devcontainer.patch.json',
+        });
+    }
+    for (const [serviceName, serviceDef] of Object.entries(customComposePatch?.services ?? {})) {
+        const image = serviceDef?.image ?? '(no image)';
+        unmatchedItems.push({
+            source: `service: ${serviceName} (image: ${image})`,
+            reason: 'No overlay covers this service — preserve in custom/docker-compose.patch.yml',
+        });
+    }
     return {
         detections,
         unmatchedItems,
@@ -570,7 +882,7 @@ export async function adoptCommand(overlaysConfig, overlaysDir, options) {
     // Build detection tables dynamically from the overlay registry
     const tables = buildDetectionTables(overlaysDir, overlaysConfig);
     // ── Analyse ────────────────────────────────────────────────────────────
-    const analysis = analyseDevcontainer(absoluteDir, overlaysConfig, tables);
+    const analysis = analyseDevcontainer(absoluteDir, overlaysConfig, tables, overlaysDir);
     // ── JSON output (no decoration) ────────────────────────────────────────
     if (options.json) {
         console.log(JSON.stringify({
@@ -641,16 +953,27 @@ export async function adoptCommand(overlaysConfig, overlaysDir, options) {
         return;
     }
     // ── Guard: existing files ──────────────────────────────────────────────
-    // superposition.json goes to the project root (parent of .devcontainer/) so it
-    // can be committed alongside application code, matching the team workflow pattern.
+    // superposition.json and optional project config go to the project root
+    // (parent of .devcontainer/) so they can be committed alongside app code.
     const projectRoot = path.dirname(absoluteDir);
     const manifestPath = path.join(projectRoot, 'superposition.json');
     const customDir = path.join(absoluteDir, 'custom');
     const customPatchPath = path.join(customDir, 'devcontainer.patch.json');
     const customComposePath = path.join(customDir, 'docker-compose.patch.yml');
+    const discoveredProjectFiles = options.projectFile ? findProjectConfig(projectRoot) : [];
+    if (discoveredProjectFiles.length > 1) {
+        console.error(chalk.red(`✗ Found both supported project config files in ${projectRoot}. Keep only one before using --project-file.`));
+        process.exit(1);
+    }
+    const projectFilePath = options.projectFile
+        ? (discoveredProjectFiles[0]?.path ?? path.join(projectRoot, '.superposition.yml'))
+        : null;
     const existingFiles = [];
     if (fs.existsSync(manifestPath))
         existingFiles.push(path.relative(process.cwd(), manifestPath));
+    if (projectFilePath && fs.existsSync(projectFilePath)) {
+        existingFiles.push(path.relative(process.cwd(), projectFilePath));
+    }
     if (analysis.customDevcontainerPatch && fs.existsSync(customPatchPath))
         existingFiles.push(path.relative(process.cwd(), customPatchPath));
     if (analysis.customComposePatch && fs.existsSync(customComposePath))
@@ -664,10 +987,13 @@ export async function adoptCommand(overlaysConfig, overlaysDir, options) {
     }
     // ── Prompt ────────────────────────────────────────────────────────────
     const hasCustomFiles = analysis.customDevcontainerPatch || analysis.customComposePatch;
+    const projectSelection = projectFilePath
+        ? buildProjectConfigSelection(analysis, overlaysConfig, projectRoot, absoluteDir, devcontainer)
+        : null;
     let confirmed;
     try {
         confirmed = await confirm({
-            message: `Generate superposition.json${hasCustomFiles ? ' and custom/ patch files' : ''} from these suggestions?`,
+            message: `Generate superposition.json${projectFilePath ? ', project config' : ''}${hasCustomFiles ? ', and custom/ patch files' : ''} from these suggestions?`,
             default: true,
         });
     }
@@ -715,6 +1041,7 @@ export async function adoptCommand(overlaysConfig, overlaysDir, options) {
         baseTemplate: analysis.suggestedStack,
         baseImage: 'bookworm',
         overlays: analysis.suggestedOverlays,
+        containerName: projectSelection?.containerName,
     };
     try {
         fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
@@ -724,6 +1051,16 @@ export async function adoptCommand(overlaysConfig, overlaysDir, options) {
         console.error(chalk.red('✗ Failed to write superposition.json:'), err);
         process.exit(1);
     }
+    if (projectFilePath && projectSelection) {
+        try {
+            writeProjectConfig(projectFilePath, projectSelection);
+            console.log(chalk.green(`✓ Written ${path.relative(process.cwd(), projectFilePath)}`));
+        }
+        catch (err) {
+            console.error(chalk.red('✗ Failed to write project config:'), err);
+            process.exit(1);
+        }
+    }
     // ── Write custom patches ───────────────────────────────────────────────
     if (hasCustomFiles) {
         try {