container-superposition 0.1.7 → 0.1.9

package/dist/tool/questionnaire/composer.js

@@ -12,20 +12,311 @@ import { deepMerge, mergePackages, filterDependsOn, applyPortOffsetToEnv, } from
 import { generatePortsDocumentation } from '../utils/port-utils.js';
 import { generateServicesMarkdown, generateEnvLocalExample } from '../utils/services-export.js';
 import { appendGitignoreSection } from '../utils/gitignore.js';
+import { getTargetRule, resolveTargetFilePath, removeStaleTargetArtifacts, } from '../schema/target-rules.js';
+import { collectOverlayParameters, resolveParameters, substituteParameters, substituteParametersInObject, findUnresolvedTokens, redactSensitiveValues, } from '../utils/parameters.js';
 import { detectWarnings, generateTips, generateNextSteps, overlaysToServices, portsToPortInfo, } from '../utils/summary.js';
+import { resolveRepoPath } from '../utils/paths.js';
 // Get __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-// Resolve REPO_ROOT that works in both source and compiled output
-// When running from TypeScript sources (e.g. ts-node), __dirname is "<root>/tool/questionnaire"
-// When running from compiled JS in "dist/tool/questionnaire", __dirname is "<root>/dist/tool/questionnaire"
-const REPO_ROOT_CANDIDATES = [
-    path.join(__dirname, '..', '..'), // From source: tool/questionnaire -> root
-    path.join(__dirname, '..', '..', '..'), // From dist: dist/tool/questionnaire -> root
-];
-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');
+// Anchor for resolving the top-level templates directory.
+// In source layout: <repo>/tool/questionnaire -> anchor becomes <repo>/tool.
+//   path.basename('tool') === 'tool', so we go one level up to reach <repo>.
+// In compiled layout: <repo>/dist/tool/questionnaire -> anchor becomes <repo>/dist/tool.
+//   path.basename('tool') === 'tool', so we go one level up to <repo>/dist,
+//   then resolveRepoPath walks further up to find templates/ at the repo root.
+// NOTE: This check relies on the source directory being named 'tool'. If that changes,
+// update this constant accordingly.
+const TEMPLATES_ANCHOR_BASE = path.join(__dirname, '..', '..');
+const TEMPLATES_ANCHOR = path.basename(TEMPLATES_ANCHOR_BASE) === 'tool'
+    ? path.dirname(TEMPLATES_ANCHOR_BASE)
+    : TEMPLATES_ANCHOR_BASE;
+const TEMPLATES_DIR = resolveRepoPath('templates', TEMPLATES_ANCHOR);
+const REPO_ROOT = path.dirname(TEMPLATES_DIR);
+// ─── JetBrains support ────────────────────────────────────────────────────
+/**
+ * Language overlays that have a defined JetBrains backend mapping.
+ * Used both in getJetBrainsBackend() and in the language filter for
+ * generateJetBrainsArtifacts() — kept in one place for consistency.
+ */
+const JETBRAINS_SUPPORTED_LANGUAGES = new Set([
+    'nodejs',
+    'bun',
+    'python',
+    'mkdocs',
+    'go',
+    'dotnet',
+    'java',
+    'rust',
+]);
+/**
+ * Map a language overlay ID to the appropriate JetBrains backend identifier.
+ * Falls back to 'IntelliJIdea' when the language is unknown or unspecified.
+ *
+ * When multiple language overlays are selected, the first match in the
+ * provided array determines the backend; the array order reflects the user's
+ * selection order.
+ */
+function getJetBrainsBackend(languageOverlays) {
+    for (const lang of languageOverlays) {
+        switch (lang) {
+            case 'nodejs':
+            case 'bun':
+                return 'WebStorm';
+            case 'python':
+            case 'mkdocs':
+                return 'PyCharm';
+            case 'go':
+                return 'GoLand';
+            case 'dotnet':
+                return 'Rider';
+            case 'rust':
+                return 'RustRover';
+            case 'java':
+                return 'IntelliJIdea';
+        }
+    }
+    return 'IntelliJIdea';
+}
+/**
+ * Generate the content of .idea/.gitignore for a JetBrains project.
+ * Marks shared settings (run configurations, code style) as tracked and
+ * excludes user-local entries (workspace.xml, shelf/).
+ */
+function generateIdeaGitignore() {
+    return `# Default ignored files
+/shelf/
+/workspace.xml
+
+# Editor-based HTTP Client requests
+/httpRequests/
+
+# Datasource local storage
+/dataSources/
+/dataSources.local.xml
+`;
+}
+/**
+ * Generate a JetBrains run configuration XML for the given language overlay.
+ * Returns an object with the filename and XML content, or null when no
+ * configuration is defined for the supplied language.
+ */
+function generateRunConfiguration(lang) {
+    switch (lang) {
+        case 'nodejs':
+        case 'bun': {
+            const manager = lang === 'bun' ? 'bun' : 'npm';
+            const runScript = lang === 'bun' ? 'bun run dev' : 'npm run dev';
+            return {
+                filename: `${manager}_dev.xml`,
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="${runScript}" type="js.build_tools.npm" factoryName="npm">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="dev" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'mkdocs': {
+            return {
+                filename: 'mkdocs_serve.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="MkDocs: mkdocs serve" type="PythonConfigurationType" factoryName="Python">
+    <module name="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHONUNBUFFERED" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="SDK_NAME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="IS_MODULE_SDK" value="false" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="SCRIPT_NAME" value="-m" />
+    <option name="MODULE_MODE" value="true" />
+    <option name="PARAMETERS" value="mkdocs serve" />
+    <option name="SHOW_COMMAND_LINE" value="false" />
+    <option name="EMULATE_TERMINAL" value="false" />
+    <option name="REDIRECT_INPUT" value="false" />
+    <option name="INPUT_FILE" value="" />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'python': {
+            return {
+                filename: 'python_main.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Python: main.py" type="PythonConfigurationType" factoryName="Python">
+    <module name="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="PYTHONUNBUFFERED" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="SDK_NAME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="IS_MODULE_SDK" value="false" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/main.py" />
+    <option name="PARAMETERS" value="" />
+    <option name="SHOW_COMMAND_LINE" value="false" />
+    <option name="EMULATE_TERMINAL" value="false" />
+    <option name="MODULE_MODE" value="false" />
+    <option name="REDIRECT_INPUT" value="false" />
+    <option name="INPUT_FILE" value="" />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'go': {
+            return {
+                filename: 'go_run.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Go: run ./..." type="GoApplicationRunConfiguration" factoryName="Go Application">
+    <module name="" />
+    <working_directory value="$PROJECT_DIR$" />
+    <parameters value="" />
+    <kind value="PACKAGE" />
+    <package value="./..." />
+    <directory value="$PROJECT_DIR$" />
+    <filePath value="$PROJECT_DIR$" />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'dotnet': {
+            return {
+                filename: 'dotnet_run.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name=".NET: dotnet run" type="DotNetRunConfiguration" factoryName="Run">
+    <option name="EXE_PATH" value="" />
+    <option name="PROGRAM_PARAMETERS" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="PASS_PARENT_ENVS" value="1" />
+    <option name="USE_EXTERNAL_CONSOLE" value="0" />
+    <option name="RUNTIME_ARGUMENTS" value="" />
+    <option name="PROJECT_PATH" value="$PROJECT_DIR$" />
+    <option name="TARGET_FRAMEWORK_ID" value="" />
+    <option name="RUNTIME_ID" value="" />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'java': {
+            return {
+                filename: 'java_run.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Java: Application" type="Application" factoryName="Application">
+    <option name="MAIN_CLASS_NAME" value="Main" />
+    <module name="" />
+    <option name="VM_PARAMETERS" value="" />
+    <option name="PROGRAM_PARAMETERS" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="ALTERNATIVE_JRE_PATH_ENABLED" value="false" />
+    <option name="ENABLE_SWING_INSPECTOR" value="false" />
+    <option name="ENV_VARIABLES" />
+    <option name="PASS_PARENT_ENVS" value="true" />
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>
+`,
+            };
+        }
+        case 'rust': {
+            return {
+                filename: 'rust_run.xml',
+                content: `<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Rust: cargo run" type="CargoCommandRunConfiguration" factoryName="Cargo Command">
+    <option name="command" value="run" />
+    <option name="workingDirectory" value="$PROJECT_DIR$" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>
+`,
+            };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Generate JetBrains IDE artifacts (.idea/.gitignore and run configurations)
+ * into the project root directory (parent of outputPath).
+ *
+ * Returns a list of project-root-relative paths that were written so the
+ * caller can register them and report what was generated.
+ */
+function generateJetBrainsArtifacts(projectRoot, languageOverlays) {
+    const ideaDir = path.join(projectRoot, '.idea');
+    const runConfigsDir = path.join(ideaDir, 'runConfigurations');
+    const written = [];
+    // Ensure directories exist
+    if (!fs.existsSync(ideaDir)) {
+        fs.mkdirSync(ideaDir, { recursive: true });
+    }
+    if (!fs.existsSync(runConfigsDir)) {
+        fs.mkdirSync(runConfigsDir, { recursive: true });
+    }
+    // Write .idea/.gitignore (only if not already present)
+    const gitignorePath = path.join(ideaDir, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, generateIdeaGitignore());
+        written.push('.idea/.gitignore');
+    }
+    // Write run configurations for each recognised language overlay
+    const generated = [];
+    const skipped = [];
+    for (const lang of languageOverlays) {
+        const runConfig = generateRunConfiguration(lang);
+        if (!runConfig)
+            continue;
+        const xmlPath = path.join(runConfigsDir, runConfig.filename);
+        if (!fs.existsSync(xmlPath)) {
+            fs.writeFileSync(xmlPath, runConfig.content);
+            written.push(`.idea/runConfigurations/${runConfig.filename}`);
+            generated.push(lang);
+        }
+        else {
+            skipped.push(runConfig.filename);
+        }
+    }
+    if (generated.length > 0) {
+        console.log(chalk.dim(`   💡 Generated JetBrains run configuration(s) for: ${generated.join(', ')}`));
+    }
+    if (skipped.length > 0) {
+        console.log(chalk.dim(`   ⏭️  Skipped existing JetBrains run configuration(s): ${skipped.join(', ')}`));
+    }
+    if (languageOverlays.length === 0) {
+        console.log(chalk.dim(`   ℹ️  No language overlays selected — no JetBrains run configurations generated`));
+    }
+    return written;
+}
+// ─── End JetBrains support ────────────────────────────────────────────────
 /**
  * Merge packages from apt-get-packages feature
  */
@@ -249,7 +540,7 @@ function prepareOverlaysForGeneration(answers, overlaysDir) {
 /**
  * Generate superposition.json manifest
  */
-function generateManifest(outputPath, answers, overlays, autoResolved, containerName) {
+function generateManifest(outputPath, answers, overlays, autoResolved, containerName, effectiveTarget) {
     const toolVersion = getToolVersion();
     const manifest = {
         manifestVersion: CURRENT_MANIFEST_VERSION,
@@ -265,7 +556,14 @@ function generateManifest(outputPath, answers, overlays, autoResolved, container
         preset: answers.preset,
         presetChoices: answers.presetChoices,
         containerName,
+        target: effectiveTarget ?? answers.target ?? 'local',
     };
+    if (answers.minimal) {
+        manifest.minimal = true;
+    }
+    if (answers.editor && answers.editor !== 'vscode') {
+        manifest.editor = answers.editor;
+    }
     if (autoResolved.added.length > 0) {
         manifest.autoResolved = autoResolved;
     }
@@ -308,7 +606,7 @@ function validateImportPath(importPath, overlaysDir) {
 /**
  * Load and resolve imports from shared files for an overlay
  */
-function loadImportsForOverlay(overlayName, overlaysDir) {
+function loadImportsForOverlay(overlayName, overlaysDir, silent = false) {
     let importedConfig = {};
     // Load overlay manifest to get imports
     const overlayDir = path.join(overlaysDir, overlayName);
@@ -340,14 +638,16 @@ function loadImportsForOverlay(overlayName, overlaysDir) {
             const ext = path.extname(importPath).toLowerCase();
             if (ext === '.json') {
                 // JSON files are merged as devcontainer patches
-                console.log(chalk.dim(`   📎 Applying shared import: ${importPath}`));
+                if (!silent)
+                    console.log(chalk.dim(`   📎 Applying shared import: ${importPath}`));
                 const importedPatch = loadJson(fullImportPath);
                 importedConfig = deepMerge(importedConfig, importedPatch);
             }
             else if (ext === '.yaml' || ext === '.yml') {
                 // YAML files are loaded and merged as devcontainer patches
                 try {
-                    console.log(chalk.dim(`   📎 Applying shared import: ${importPath}`));
+                    if (!silent)
+                        console.log(chalk.dim(`   📎 Applying shared import: ${importPath}`));
                     const yamlContent = fs.readFileSync(fullImportPath, 'utf8');
                     const importedPatch = yaml.load(yamlContent);
                     if (importedPatch && typeof importedPatch === 'object') {
@@ -360,7 +660,8 @@ function loadImportsForOverlay(overlayName, overlaysDir) {
             }
             else if (ext === '.env') {
                 // .env files are handled separately during env merging — skip here
-                console.log(chalk.dim(`   📎 Shared .env import noted: ${importPath}`));
+                if (!silent)
+                    console.log(chalk.dim(`   📎 Shared .env import noted: ${importPath}`));
             }
             else {
                 // FR-007: Unsupported file types are errors
@@ -381,14 +682,16 @@ function loadImportsForOverlay(overlayName, overlaysDir) {
 /**
  * Apply an overlay to the base configuration
  */
-export function applyOverlay(baseConfig, overlayName, overlaysDir) {
+export function applyOverlay(baseConfig, overlayName, overlaysDir, options = {}) {
+    const { silent = false } = options;
     const overlayPath = path.join(overlaysDir, overlayName, 'devcontainer.patch.json');
     if (!fs.existsSync(overlayPath)) {
-        console.warn(chalk.yellow(`⚠️  Overlay not found: ${overlayName}`));
+        if (!silent)
+            console.warn(chalk.yellow(`⚠️  Overlay not found: ${overlayName}`));
         return baseConfig;
     }
     // First, load and apply any imports
-    const importedConfig = loadImportsForOverlay(overlayName, overlaysDir);
+    const importedConfig = loadImportsForOverlay(overlayName, overlaysDir, silent);
     if (Object.keys(importedConfig).length > 0) {
         baseConfig = deepMerge(baseConfig, importedConfig);
     }
@@ -430,8 +733,36 @@ class FileRegistry {
     }
 }
 /**
- * Clean up stale files from previous runs
- * Removes anything not in the registry (except preserved files like superposition.json)
+ * Recursively remove stale files within a registered subdirectory.
+ * Called for directories that ARE in the registry but may contain files from
+ * a previous run that are no longer part of the current generation (e.g.
+ * scripts/setup-rabbitmq.sh after rabbitmq was removed from the project).
+ * Returns the number of files removed.
+ */
+function cleanupStaleDirFiles(dirPath, prefix, expectedFiles) {
+    let removed = 0;
+    const entries = fs.readdirSync(dirPath);
+    for (const entry of entries) {
+        const entryPath = path.join(dirPath, entry);
+        const stat = fs.statSync(entryPath);
+        if (stat.isDirectory()) {
+            removed += cleanupStaleDirFiles(entryPath, `${prefix}${entry}/`, expectedFiles);
+        }
+        else {
+            const registryKey = `${prefix}${entry}`;
+            if (!expectedFiles.has(registryKey)) {
+                fs.unlinkSync(entryPath);
+                removed++;
+            }
+        }
+    }
+    return removed;
+}
+/**
+ * Clean up stale files from previous runs.
+ * Removes anything not in the registry (except preserved files like superposition.json).
+ * Also recurses into registered subdirectories to remove individual stale files within
+ * them — e.g. scripts/setup-rabbitmq.sh after rabbitmq is removed from the project.
  */
 function cleanupStaleFiles(outputPath, registry) {
     if (!fs.existsSync(outputPath)) {
@@ -455,11 +786,16 @@ function cleanupStaleFiles(outputPath, registry) {
             if (preservedDirs.has(entry)) {
                 continue;
             }
-            // Remove directory if not in registry
             if (!expectedDirs.has(entry)) {
+                // Remove directory entirely — nothing inside belongs to this run
                 fs.rmSync(entryPath, { recursive: true, force: true });
                 removedCount++;
             }
+            else {
+                // Directory is still expected, but individual files inside it may be stale
+                // (e.g. scripts/setup-rabbitmq.sh after rabbitmq was removed)
+                removedCount += cleanupStaleDirFiles(entryPath, `${entry}/`, expectedFiles);
+            }
         }
         else {
             // Remove file if not in registry
@@ -492,6 +828,23 @@ function copyDir(src, dest) {
         }
     }
 }
+/**
+ * Recursively register every file inside a directory in the FileRegistry.
+ * Used after copyDir() to ensure cleanup logic doesn't delete the copied contents.
+ */
+function registerDirContents(registry, dirPath, prefix) {
+    if (!fs.existsSync(dirPath))
+        return;
+    for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+        const rel = `${prefix}${entry.name}`;
+        if (entry.isDirectory()) {
+            registerDirContents(registry, path.join(dirPath, entry.name), `${rel}/`);
+        }
+        else {
+            registry.addFile(rel);
+        }
+    }
+}
 /**
  * Copy additional files from overlay to output directory
  * Excludes devcontainer.patch.json and .env.example (handled separately)
@@ -534,6 +887,9 @@ function copyOverlayFiles(outputPath, overlayName, registry, overlaysDir) {
             const destPath = path.join(outputPath, destDirName);
             copyDir(srcPath, destPath);
             registry.addDirectory(destDirName);
+            // Register every file inside the copied directory so that
+            // cleanupStaleDirFiles does not delete them during the same run.
+            registerDirContents(registry, destPath, `${destDirName}/`);
             copiedFiles++;
         }
     }
@@ -541,6 +897,164 @@ function copyOverlayFiles(outputPath, overlayName, registry, overlaysDir) {
         console.log(chalk.dim(`   📋 Copied ${copiedFiles} file(s) from ${chalk.cyan(overlayName)}`));
     }
 }
+const PROJECT_ENV_REFERENCE_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}/g;
+function parseSimpleEnvFile(content) {
+    const env = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const match = trimmed.match(/^([^=]+)=(.*)$/);
+        if (!match) {
+            continue;
+        }
+        env[match[1].trim()] = match[2].trim();
+    }
+    return env;
+}
+function loadEnvFileIfExists(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    return parseSimpleEnvFile(fs.readFileSync(filePath, 'utf8'));
+}
+function resolveProjectEnvTarget(entry, stack) {
+    const target = entry.target ?? 'auto';
+    if (target === 'remoteEnv') {
+        return 'remoteEnv';
+    }
+    if (target === 'composeEnv') {
+        if (stack !== 'compose') {
+            throw new Error('Project env target "composeEnv" requires stack: compose because no docker-compose.yml is generated for plain stacks');
+        }
+        return 'composeEnv';
+    }
+    return stack === 'compose' ? 'composeEnv' : 'remoteEnv';
+}
+function resolveRootEnvReferences(value, rootEnv) {
+    return value.replace(PROJECT_ENV_REFERENCE_PATTERN, (match, name) => {
+        if (rootEnv[name] !== undefined) {
+            return rootEnv[name];
+        }
+        const defaultMatch = match.match(/^\$\{[A-Za-z_][A-Za-z0-9_]*:-([^}]*)\}$/);
+        return defaultMatch ? defaultMatch[1] : match;
+    });
+}
+function hasUnresolvedProjectEnvReference(value) {
+    PROJECT_ENV_REFERENCE_PATTERN.lastIndex = 0;
+    const result = PROJECT_ENV_REFERENCE_PATTERN.test(value);
+    PROJECT_ENV_REFERENCE_PATTERN.lastIndex = 0;
+    return result;
+}
+function buildResolvedProjectRemoteEnvEntries(projectEnv, stack, rootEnv) {
+    const entries = {};
+    for (const [key, entry] of Object.entries(projectEnv ?? {})) {
+        if (resolveProjectEnvTarget(entry, stack) !== 'remoteEnv') {
+            continue;
+        }
+        entries[key] = resolveRootEnvReferences(entry.value, rootEnv ?? {});
+    }
+    return entries;
+}
+function buildComposeProjectEnvInterpolationEntries(projectEnv, stack) {
+    const entries = {};
+    for (const [key, entry] of Object.entries(projectEnv ?? {})) {
+        if (resolveProjectEnvTarget(entry, stack) !== 'composeEnv') {
+            continue;
+        }
+        entries[key] = `\${${key}}`;
+    }
+    return entries;
+}
+function buildComposeProjectRemoteEnvRefs(projectEnv, stack) {
+    const entries = {};
+    for (const [key, entry] of Object.entries(projectEnv ?? {})) {
+        if (resolveProjectEnvTarget(entry, stack) !== 'composeEnv') {
+            continue;
+        }
+        entries[key] = `\${containerEnv:${key}}`;
+    }
+    return entries;
+}
+function materializeComposeProjectEnvValues(projectEnv, stack, rootEnv) {
+    const entries = {};
+    for (const [key, entry] of Object.entries(projectEnv ?? {})) {
+        if (resolveProjectEnvTarget(entry, stack) !== 'composeEnv') {
+            continue;
+        }
+        const resolvedValue = resolveRootEnvReferences(entry.value, rootEnv);
+        // Leave unresolved variables to shell/docker-compose fallback instead of
+        // persisting placeholder syntax into .devcontainer/.env.
+        if (hasUnresolvedProjectEnvReference(resolvedValue)) {
+            continue;
+        }
+        entries[key] = resolvedValue;
+    }
+    return entries;
+}
+function applyProjectEnvToDevcontainer(config, projectEnv, stack, rootEnv) {
+    const remoteEnv = {
+        ...buildResolvedProjectRemoteEnvEntries(projectEnv, stack, rootEnv),
+        ...buildComposeProjectRemoteEnvRefs(projectEnv, stack),
+    };
+    if (Object.keys(remoteEnv).length === 0) {
+        return config;
+    }
+    console.log(chalk.dim(`   🌱 Applying project env to remoteEnv`));
+    return deepMerge(config, { remoteEnv });
+}
+function mergeComposeEnvFile(outputPath, entries) {
+    if (Object.keys(entries).length === 0) {
+        return false;
+    }
+    const envPath = path.join(outputPath, '.env');
+    const originalContent = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
+    const lines = originalContent === '' ? [] : originalContent.replace(/\n$/, '').split('\n');
+    const indexByKey = new Map();
+    lines.forEach((line, index) => {
+        const match = line.match(/^([^#=\s][^=]*)=(.*)$/);
+        if (match) {
+            indexByKey.set(match[1].trim(), index);
+        }
+    });
+    let changed = false;
+    let insertedSpacer = false;
+    for (const [key, value] of Object.entries(entries)) {
+        const rendered = `${key}=${value}`;
+        const existingIndex = indexByKey.get(key);
+        if (existingIndex !== undefined) {
+            if (lines[existingIndex] !== rendered) {
+                lines[existingIndex] = rendered;
+                changed = true;
+            }
+            continue;
+        }
+        if (lines.length > 0 && !insertedSpacer && lines[lines.length - 1] !== '') {
+            lines.push('');
+            insertedSpacer = true;
+        }
+        lines.push(rendered);
+        indexByKey.set(key, lines.length - 1);
+        changed = true;
+    }
+    if (!changed && originalContent !== '') {
+        return false;
+    }
+    fs.writeFileSync(envPath, `${lines.join('\n')}\n`);
+    return true;
+}
+function materializeComposeProjectEnvFile(outputPath, projectEnv, stack, rootEnv) {
+    if (stack !== 'compose') {
+        return false;
+    }
+    const materializedEntries = materializeComposeProjectEnvValues(projectEnv, stack, rootEnv);
+    if (!mergeComposeEnvFile(outputPath, materializedEntries)) {
+        return false;
+    }
+    console.log(chalk.dim(`   🔁 Materialized ${Object.keys(materializedEntries).length} project env value(s) into .devcontainer/.env for docker-compose`));
+    return true;
+}
 /**
  * Merge .env.example files from all selected overlays
  */
@@ -813,15 +1327,48 @@ function resolveDockerComposePortConflicts(services) {
 /**
  * Merge docker-compose.yml files from base and overlays into a single file
  */
-function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, portOffset, customImage) {
+function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, portOffset, customImage, projectEnv) {
     const composeFiles = [];
     // Add base docker-compose if exists
     const baseComposePath = path.join(TEMPLATES_DIR, baseStack, '.devcontainer', 'docker-compose.yml');
     if (fs.existsSync(baseComposePath)) {
         composeFiles.push(baseComposePath);
     }
-    // Add overlay docker-compose files
+    // Add overlay docker-compose files, interleaving any compose_imports before each overlay's own file
     for (const overlay of overlays) {
+        // First load any compose_imports for this overlay (shared fragments applied before own file)
+        const manifestPath = path.join(overlaysDir, overlay, 'overlay.yml');
+        if (fs.existsSync(manifestPath)) {
+            try {
+                const manifestContent = fs.readFileSync(manifestPath, 'utf8');
+                const manifest = yaml.load(manifestContent);
+                if (manifest.compose_imports && Array.isArray(manifest.compose_imports)) {
+                    for (const importPath of manifest.compose_imports) {
+                        const traversalError = validateImportPath(importPath, overlaysDir);
+                        if (traversalError) {
+                            throw new Error(`compose_import path traversal rejected in overlay '${overlay}': ${traversalError}`);
+                        }
+                        const fullImportPath = path.join(overlaysDir, importPath);
+                        if (!fs.existsSync(fullImportPath)) {
+                            throw new Error(`compose_import not found: '${importPath}' (referenced by overlay: ${overlay})`);
+                        }
+                        const ext = path.extname(importPath).toLowerCase();
+                        if (ext !== '.yml' && ext !== '.yaml') {
+                            throw new Error(`compose_import must be a .yml or .yaml file: '${importPath}' (overlay: ${overlay})`);
+                        }
+                        console.log(chalk.dim(`   📎 Applying shared compose fragment: ${importPath}`));
+                        composeFiles.push(fullImportPath);
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    throw error;
+                }
+                // Non-Error throwables are unexpected; wrap and re-throw so compose_imports failures always fail fast
+                throw new Error(`Unexpected error loading compose_imports for overlay '${overlay}': ${String(error)}`);
+            }
+        }
         const overlayComposePath = path.join(overlaysDir, overlay, 'docker-compose.yml');
         if (fs.existsSync(overlayComposePath)) {
             composeFiles.push(overlayComposePath);
@@ -859,6 +1406,11 @@ function mergeDockerComposeFiles(outputPath, baseStack, overlays, overlaysDir, p
     }
     // Ensure devcontainer service has an image
     if (merged.services.devcontainer) {
+        const composeEnv = buildComposeProjectEnvInterpolationEntries(projectEnv, baseStack);
+        if (Object.keys(composeEnv).length > 0) {
+            merged.services.devcontainer.environment = deepMerge(merged.services.devcontainer.environment ?? {}, composeEnv);
+            console.log(chalk.dim(`   🌱 Applying project env to docker-compose devcontainer service`));
+        }
         if (customImage) {
             // Apply custom base image if specified
             merged.services.devcontainer.image = customImage;
@@ -1228,17 +1780,60 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
         }
     }
     const overlays = orderedOverlays;
-    // 5. Create output directory and file registry for cleanup
+    // 5b. Resolve overlay parameters ({{cs.KEY}} substitution)
+    // Collect parameter declarations from all selected overlays
+    const declaredParams = collectOverlayParameters(overlays, allOverlayDefs);
+    const { values: resolvedParams, missingRequired, unknownSupplied, } = resolveParameters(declaredParams, answers.overlayParameters ?? {});
+    if (missingRequired.length > 0) {
+        throw new Error(`Missing required overlay parameters: ${missingRequired.join(', ')}. ` +
+            `Provide values in superposition.yml under the parameters: section, ` +
+            `or via --param KEY=VALUE on the command line.`);
+    }
+    if (unknownSupplied.length > 0) {
+        console.warn(chalk.yellow(`   ⚠️  Unknown overlay parameters (not declared by any selected overlay): ${unknownSupplied.join(', ')}`));
+    }
+    const hasResolvedParams = Object.keys(resolvedParams).length > 0;
+    // Log resolved parameter values (sensitive values are redacted)
+    if (hasResolvedParams) {
+        const displayValues = redactSensitiveValues(resolvedParams, declaredParams);
+        console.log(chalk.dim(`   ⚙️  Overlay parameters:`));
+        for (const [k, v] of Object.entries(displayValues)) {
+            console.log(chalk.dim(`      ${k}=${v}`));
+        }
+    }
     const outputPath = path.resolve(answers.outputPath);
+    const projectRoot = path.dirname(outputPath);
     const fileRegistry = new FileRegistry();
+    const rootEnv = loadEnvFileIfExists(path.join(projectRoot, '.env'));
     if (!fs.existsSync(outputPath)) {
         fs.mkdirSync(outputPath, { recursive: true });
     }
+    // 5a. Remove stale project-root artifacts from a previous target run
+    const manifestPath_existing = path.join(outputPath, 'superposition.json');
+    let manifestTarget;
+    if (fs.existsSync(manifestPath_existing)) {
+        try {
+            const existingManifest = JSON.parse(fs.readFileSync(manifestPath_existing, 'utf-8'));
+            manifestTarget = existingManifest.target;
+        }
+        catch {
+            // If manifest is unreadable, skip stale cleanup gracefully
+        }
+    }
+    // When answers.target is undefined (e.g. regen without --target), fall back to the
+    // target recorded in the existing manifest so the correct artifacts are reproduced.
+    const activeTarget = answers.target ?? manifestTarget ?? 'local';
+    const previousTarget = manifestTarget ?? 'local';
+    if (previousTarget !== activeTarget) {
+        removeStaleTargetArtifacts(previousTarget, activeTarget, projectRoot);
+        console.log(chalk.dim(`   🧹 Removed stale target artifacts for previous target '${previousTarget}'`));
+    }
     // 6. Apply overlays
     for (const overlay of overlays) {
         console.log(chalk.dim(`   🔧 Applying overlay: ${chalk.cyan(overlay)}`));
         config = applyOverlay(config, overlay, actualOverlaysDir);
     }
+    config = applyProjectEnvToDevcontainer(config, answers.projectEnv, answers.stack, rootEnv);
     // 7. Copy template files (docker-compose, scripts, etc.)
     const entries = fs.readdirSync(templatePath);
     for (const entry of entries) {
@@ -1262,11 +1857,19 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
     }
     // 8.5. Copy cross-distro-packages feature if used
     if (config.features?.['./features/cross-distro-packages']) {
-        const featuresDir = path.join(outputPath, 'features', 'cross-distro-packages');
-        const sourceFeatureDir = path.join(REPO_ROOT, 'features', 'cross-distro-packages');
+        const featureName = 'cross-distro-packages';
+        const featuresDir = path.join(outputPath, 'features', featureName);
+        const sourceFeatureDir = path.join(REPO_ROOT, 'features', featureName);
         if (fs.existsSync(sourceFeatureDir)) {
             copyDir(sourceFeatureDir, featuresDir);
             fileRegistry.addDirectory('features');
+            // Register every file inside the feature so cleanupStaleDirFiles
+            // does not remove them when it recurses into the 'features' directory.
+            for (const f of fs.readdirSync(sourceFeatureDir)) {
+                if (fs.statSync(path.join(sourceFeatureDir, f)).isFile()) {
+                    fileRegistry.addFile(`features/${featureName}/${f}`);
+                }
+            }
             console.log(chalk.dim(`   📦 Copied cross-distro-packages feature`));
         }
     }
@@ -1278,11 +1881,22 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
     let composePortRemappings = [];
     if (answers.stack === 'compose') {
         const customImage = config._customImage;
-        composePortRemappings = mergeDockerComposeFiles(outputPath, answers.stack, overlays, actualOverlaysDir, answers.portOffset, customImage);
+        composePortRemappings = mergeDockerComposeFiles(outputPath, answers.stack, overlays, actualOverlaysDir, answers.portOffset, customImage, answers.projectEnv);
         // Update devcontainer.json to reference the combined file
         if (config.dockerComposeFile) {
             config.dockerComposeFile = 'docker-compose.yml';
         }
+        // Apply parameter substitution to the merged docker-compose.yml
+        if (hasResolvedParams) {
+            const composePath = path.join(outputPath, 'docker-compose.yml');
+            if (fs.existsSync(composePath)) {
+                const original = fs.readFileSync(composePath, 'utf8');
+                const substituted = substituteParameters(original, resolvedParams);
+                if (substituted !== original) {
+                    fs.writeFileSync(composePath, substituted);
+                }
+            }
+        }
     }
     // Apply port offset to devcontainer.json if specified
     if (answers.portOffset) {
@@ -1311,24 +1925,62 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
     if (answers.editor === 'none' || answers.editor === 'jetbrains') {
         // Remove VS Code customizations
         if (config.customizations?.vscode) {
-            if (answers.editor === 'none') {
-                delete config.customizations.vscode;
-                console.log(chalk.dim(`   🎨 Editor profile 'none': Removed VS Code customizations`));
-            }
-            else if (answers.editor === 'jetbrains') {
-                // For JetBrains, remove VS Code customizations (future: could add JetBrains-specific settings)
-                delete config.customizations.vscode;
-                console.log(chalk.dim(`   🎨 Editor profile 'jetbrains': Removed VS Code customizations`));
-            }
+            delete config.customizations.vscode;
+            const profileLabel = answers.editor === 'none' ? 'none' : 'jetbrains';
+            console.log(chalk.dim(`   🎨 Editor profile '${profileLabel}': Removed VS Code customizations`));
             // Clean up empty customizations object
             if (config.customizations && Object.keys(config.customizations).length === 0) {
                 delete config.customizations;
             }
         }
     }
+    // Add JetBrains-specific devcontainer.json customizations and generate .idea/ artifacts
+    if (answers.editor === 'jetbrains') {
+        const selectedLanguages = answers.language ?? [];
+        const languageOverlays = selectedLanguages.filter((lang) => JETBRAINS_SUPPORTED_LANGUAGES.has(lang));
+        if (languageOverlays.length === 0 && selectedLanguages.length > 0) {
+            const selectedLabel = selectedLanguages.join(', ');
+            console.log(chalk.yellow(`   ⚠️  No supported JetBrains language overlays selected (selected: ${selectedLabel})`));
+        }
+        const backend = getJetBrainsBackend(languageOverlays);
+        // Add customizations.jetbrains block to devcontainer.json
+        if (!config.customizations) {
+            config.customizations = {};
+        }
+        config.customizations.jetbrains = { backend };
+        console.log(chalk.dim(`   🧠 Editor profile 'jetbrains': Set backend to '${backend}'`));
+        // Generate .idea/ artifacts in the project root
+        console.log(chalk.cyan('\n💡 Generating JetBrains project artifacts...'));
+        const jetbrainsFiles = generateJetBrainsArtifacts(projectRoot, languageOverlays);
+        for (const relPath of jetbrainsFiles) {
+            console.log(chalk.dim(`   📄 Created ${relPath} at project root`));
+        }
+    }
+    // 11b. Apply target-specific devcontainer.json patch
+    const targetRule = getTargetRule(activeTarget);
+    const overlayMetadataMapForTarget = new Map(allOverlayDefs.map((o) => [o.id, o]));
+    const targetCtx = {
+        overlays,
+        overlayMetadata: overlayMetadataMapForTarget,
+        portOffset: answers.portOffset ?? 0,
+        stack: answers.stack,
+        outputPath,
+        projectRoot,
+    };
+    const targetPatch = targetRule.devcontainerPatch(targetCtx);
+    if (Object.keys(targetPatch).length > 0) {
+        config = deepMerge(config, targetPatch);
+        console.log(chalk.dim(`   🎯 Applied ${activeTarget} target patch to devcontainer.json`));
+    }
     // 12. Write merged devcontainer.json
+    // Apply parameter substitution to the config object (before JSON.stringify) so that
+    // any JSON-special characters in parameter values are properly escaped by JSON.stringify.
     const configPath = path.join(outputPath, 'devcontainer.json');
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+    const finalConfig = hasResolvedParams
+        ? substituteParametersInObject(config, resolvedParams)
+        : config;
+    const devcontainerContent = JSON.stringify(finalConfig, null, 2) + '\n';
+    fs.writeFileSync(configPath, devcontainerContent);
     fileRegistry.addFile('devcontainer.json');
     console.log(chalk.dim(`   📝 Wrote devcontainer.json`));
     // Apply custom docker-compose patch (after writing base docker-compose.yml)
@@ -1336,13 +1988,39 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
         applyCustomDockerComposePatch(outputPath, customPatches);
     }
     // 13. Generate superposition.json manifest
-    generateManifest(outputPath, answers, overlays, autoResolved, answers.containerName || config.name);
+    generateManifest(outputPath, answers, overlays, autoResolved, answers.containerName || config.name, activeTarget);
     fileRegistry.addFile('superposition.json');
     // 14. Merge .env.example files from overlays and apply glue config environment variables
     const envCreated = mergeEnvExamples(outputPath, overlays, actualOverlaysDir, answers.portOffset, answers.presetGlueConfig, answers.preset);
     if (envCreated) {
         fileRegistry.addFile('.env.example');
     }
+    // Apply parameter substitution to .env.example
+    // This must happen after mergeEnvExamples but before any consumer of .env reads it,
+    // because mergeEnvExamples may have written {{cs.*}} tokens into .env.example.
+    // We also regenerate .env (the port-offset copy) from the substituted content so that
+    // applyPortOffsetToEnv can correctly match numeric port values that were previously
+    // hidden behind {{cs.POSTGRES_PORT}} tokens.
+    if (hasResolvedParams) {
+        const envExamplePath = path.join(outputPath, '.env.example');
+        if (fs.existsSync(envExamplePath)) {
+            const original = fs.readFileSync(envExamplePath, 'utf8');
+            const substituted = substituteParameters(original, resolvedParams);
+            if (substituted !== original) {
+                fs.writeFileSync(envExamplePath, substituted);
+                // Regenerate .env from the substituted content when a port offset is active.
+                // mergeEnvExamples already wrote .env from the pre-substitution content, so
+                // the port offset was applied to unresolved tokens (e.g. {{cs.POSTGRES_PORT}})
+                // that had no numeric value to match — we must regenerate .env now that the
+                // tokens have been replaced with real numeric port values.
+                if (answers.portOffset) {
+                    const envPath = path.join(outputPath, '.env');
+                    const offsetContent = applyPortOffsetToEnv(substituted, answers.portOffset);
+                    fs.writeFileSync(envPath, offsetContent);
+                }
+            }
+        }
+    }
     // Apply custom environment variables (after .env.example is created)
     if (customPatches) {
         const customEnvCreated = applyCustomEnvironment(outputPath, customPatches);
@@ -1351,6 +2029,7 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
             fileRegistry.addFile('.env.example');
         }
     }
+    materializeComposeProjectEnvFile(outputPath, answers.projectEnv, answers.stack, rootEnv);
     // 14b. Merge .gitignore files from overlays into project root .gitignore
     // Note: .gitignore lives at the project root (parent of outputPath), not inside outputPath,
     // so it is intentionally NOT added to fileRegistry (cleanupStaleFiles must not touch it).
@@ -1429,12 +2108,63 @@ export async function composeDevContainer(answers, overlaysDir, options = {}) {
     const envLocalContent = generateEnvLocalExample(selectedOverlayMetadata, actualOverlaysDir, portOffset);
     if (envLocalContent) {
         const envLocalPath = path.join(outputPath, 'env.local.example');
-        fs.writeFileSync(envLocalPath, envLocalContent);
+        const finalEnvLocalContent = hasResolvedParams
+            ? substituteParameters(envLocalContent, resolvedParams)
+            : envLocalContent;
+        fs.writeFileSync(envLocalPath, finalEnvLocalContent);
         fileRegistry.addFile('env.local.example');
         console.log(chalk.dim(`   📄 Created env.local.example with optional overrides`));
     }
+    // 17d. Generate target-specific workspace artifacts and guidance
+    if (activeTarget !== 'local') {
+        console.log(chalk.cyan(`\n🎯 Generating ${activeTarget} target artifacts...`));
+        const targetFiles = targetRule.generateFiles(targetCtx);
+        for (const [key, content] of targetFiles) {
+            const absPath = resolveTargetFilePath(key, outputPath, projectRoot);
+            fs.writeFileSync(absPath, content);
+            if (key.startsWith('../')) {
+                // Project-root file: log but do NOT add to fileRegistry
+                // (fileRegistry only tracks outputPath-relative files)
+                console.log(chalk.dim(`   📄 Created ${path.basename(absPath)} at project root`));
+            }
+            else {
+                fileRegistry.addFile(key);
+                console.log(chalk.dim(`   📄 Created ${key} in .devcontainer/`));
+            }
+        }
+    }
     // 18. Clean up stale files from previous runs (preserves superposition.json and .env)
     cleanupStaleFiles(outputPath, fileRegistry);
+    // 18b. Validate that no unresolved {{cs.*}} tokens remain in any generated file.
+    // Run unconditionally — an overlay author could accidentally ship {{cs.*}} tokens
+    // in files that don't have a matching parameters declaration, and we must catch those
+    // regardless of whether any parameters were resolved in this run.
+    // Only text-like files (not binaries) are scanned; skip missing files gracefully.
+    const BINARY_EXTENSIONS = new Set(['.png', '.jpg', '.gif', '.ico', '.woff', '.woff2', '.ttf']);
+    {
+        const allGeneratedFiles = Array.from(fileRegistry.getFiles());
+        const unresolvedByFile = {};
+        for (const relFile of allGeneratedFiles) {
+            const ext = path.extname(relFile).toLowerCase();
+            if (BINARY_EXTENSIONS.has(ext))
+                continue;
+            const absPath = path.join(outputPath, relFile);
+            if (!fs.existsSync(absPath))
+                continue;
+            const content = fs.readFileSync(absPath, 'utf8');
+            const unresolved = findUnresolvedTokens(content);
+            if (unresolved.length > 0) {
+                unresolvedByFile[relFile] = [...new Set(unresolved)];
+            }
+        }
+        if (Object.keys(unresolvedByFile).length > 0) {
+            const details = Object.entries(unresolvedByFile)
+                .map(([file, tokens]) => `${file}: ${tokens.join(', ')}`)
+                .join('; ');
+            throw new Error(`Unresolved {{cs.*}} parameter tokens remain in generated files: ${details}. ` +
+                `Declare these parameters in the overlay's overlay.yml and provide values in your project file (superposition.yml).`);
+        }
+    }
     // 19. Generate and return summary
     const files = Array.from(fileRegistry.getFiles());
     const services = overlaysToServices(selectedOverlayMetadata);
@@ -1491,15 +2221,14 @@ function applyPortOffsetToDevcontainer(config, offset) {
 function mergeSetupScripts(config, overlays, outputPath, fileRegistry, overlaysDir) {
     const setupScripts = [];
     const verifyScripts = [];
-    // Create scripts subfolder
     const scriptsDir = path.join(outputPath, 'scripts');
-    if (!fs.existsSync(scriptsDir)) {
-        fs.mkdirSync(scriptsDir, { recursive: true });
-    }
-    // Add scripts directory to registry if any scripts will be added
+    // Only create the scripts directory (and register it) if at least one overlay needs it
     const hasScripts = overlays.some((o) => fs.existsSync(path.join(overlaysDir, o, 'setup.sh')) ||
         fs.existsSync(path.join(overlaysDir, o, 'verify.sh')));
     if (hasScripts) {
+        if (!fs.existsSync(scriptsDir)) {
+            fs.mkdirSync(scriptsDir, { recursive: true });
+        }
         fileRegistry.addDirectory('scripts');
         // Emit shared setup utilities so overlay scripts can source them
         const setupUtilsSrc = path.join(TEMPLATES_DIR, 'scripts', 'setup-utils.sh');
@@ -1627,7 +2356,11 @@ function mergeRunServices(config, overlays, overlaysDir) {
         if (fs.existsSync(overlayPath)) {
             const overlayConfig = loadJson(overlayPath);
             if (overlayConfig.runServices) {
-                const order = overlayConfig._serviceOrder || 0;
+                const manifestPath = path.join(overlaysDir, overlay, 'overlay.yml');
+                const manifest = fs.existsSync(manifestPath)
+                    ? yaml.load(fs.readFileSync(manifestPath, 'utf8'))
+                    : null;
+                const order = manifest?.serviceOrder ?? 0;
                 for (const service of overlayConfig.runServices) {
                     services.push({ name: service, order });
                 }