container-superposition 0.1.6 → 0.1.7

package/dist/tool/commands/doctor.js

@@ -8,9 +8,76 @@ import { execSync } from 'child_process';
 import chalk from 'chalk';
 import boxen from 'boxen';
 import { loadOverlayManifest } from '../schema/overlay-loader.js';
-import { detectManifestVersion, isVersionSupported, needsMigration, CURRENT_MANIFEST_VERSION, } from '../schema/manifest-migrations.js';
+import { detectManifestVersion, isVersionSupported, needsMigration, migrateManifest, CURRENT_MANIFEST_VERSION, } from '../schema/manifest-migrations.js';
 import { MERGE_STRATEGY } from '../utils/merge.js';
 import { extractPorts } from '../utils/port-utils.js';
+import { composeDevContainer } from '../questionnaire/composer.js';
+import { loadProjectConfig } from '../schema/project-config.js';
+// ─── Remediation registry ─────────────────────────────────────────────────
+const REMEDIATION_REGISTRY = new Map([
+    [
+        'manifest-migration',
+        {
+            key: 'manifest-migration',
+            findingId: 'manifest-version',
+            safetyClass: 'safe-unattended',
+            executionKind: 'manifest-migration',
+            preconditions: ['superposition.json must exist and be parseable'],
+            plannedChanges: [
+                'Migrate superposition.json to current schema version',
+                'Create timestamped backup of the original manifest',
+            ],
+            manualFallback: [
+                'Run "container-superposition regen" to regenerate with the current schema',
+            ],
+        },
+    ],
+    [
+        'devcontainer-regeneration',
+        {
+            key: 'devcontainer-regeneration',
+            findingId: 'devcontainer-config',
+            safetyClass: 'safe-unattended',
+            executionKind: 'regeneration',
+            preconditions: ['Valid superposition.json manifest must be present'],
+            plannedChanges: ['Regenerate devcontainer.json from superposition.json'],
+            manualFallback: ['Run "container-superposition regen --output <path>" to regenerate'],
+        },
+    ],
+    [
+        'node-version-fix',
+        {
+            key: 'node-version-fix',
+            findingId: 'nodejs-version',
+            safetyClass: 'safe-unattended',
+            executionKind: 'shell-command',
+            preconditions: ['nvm, fnm, or volta must be installed'],
+            plannedChanges: ['Use version manager to install and activate Node.js >= 20'],
+            manualFallback: [
+                'Install Node.js >= 20 from https://nodejs.org/',
+                'Or with nvm:   nvm install 20 && nvm use 20',
+                'Or with fnm:   fnm install 20 && fnm use 20',
+                'Or with volta: volta install node@20',
+            ],
+        },
+    ],
+    [
+        'docker-repair',
+        {
+            key: 'docker-repair',
+            findingId: 'docker-daemon',
+            safetyClass: 'requires-manual-action',
+            executionKind: 'no-op',
+            preconditions: [],
+            plannedChanges: [],
+            manualFallback: [
+                'Linux:   sudo systemctl start docker',
+                'macOS:   open -a Docker',
+                'Windows: Start Docker Desktop from the Start menu',
+            ],
+        },
+    ],
+]);
 /**
  * Semantic version comparison helper
  */
@@ -41,36 +108,76 @@ function checkNodeVersion() {
     const versionMatch = nodeVersion.match(/^v(\d+\.\d+\.\d+)/);
     const currentVersion = versionMatch ? versionMatch[1] : '0.0.0';
     const ok = isVersionAtLeast(currentVersion, requiredVersion);
+    if (ok) {
+        return {
+            name: 'Node.js version',
+            status: 'pass',
+            message: `${nodeVersion} (>= ${requiredVersion} required)`,
+            fixEligibility: 'not-applicable',
+        };
+    }
+    // Determine if a version manager is available for auto-fix
+    const hasVersionManager = detectVersionManager() !== null;
     return {
         name: 'Node.js version',
-        status: ok ? 'pass' : 'fail',
-        message: ok
-            ? `${nodeVersion} (>= ${requiredVersion} required)`
-            : `${nodeVersion} - requires >= ${requiredVersion}`,
-        details: ok
-            ? undefined
-            : [
-                'Update Node.js to version 20 or later',
-                'Visit https://nodejs.org/ to download the latest version',
-            ],
+        status: 'fail',
+        message: `${nodeVersion} - requires >= ${requiredVersion}`,
+        details: [
+            'Update Node.js to version 20 or later',
+            'Visit https://nodejs.org/ to download the latest version',
+        ],
+        fixEligibility: hasVersionManager ? 'automatic' : 'manual-only',
+        remediationKey: hasVersionManager ? 'node-version-fix' : undefined,
+        fixable: hasVersionManager,
     };
 }
+/**
+ * Detect which Node.js version manager is available.
+ * Returns the manager name or null if none found.
+ */
+function detectVersionManager() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+    // nvm installs a shell function, not a binary — check the script file
+    const nvmScript = path.join(home, '.nvm', 'nvm.sh');
+    if (fs.existsSync(nvmScript)) {
+        return 'nvm';
+    }
+    for (const cmd of ['fnm', 'volta']) {
+        try {
+            execSync(`${cmd} --version`, {
+                stdio: 'ignore',
+                timeout: 3000,
+            });
+            return cmd;
+        }
+        catch {
+            // not available
+        }
+    }
+    return null;
+}
 /**
  * Check if Docker daemon is accessible
  */
 function checkDocker() {
     try {
         // Use 'docker info' to verify daemon connectivity, not just CLI presence
-        execSync('docker info', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
+        execSync('docker info', {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 5000,
+        });
         // Get version for display
         const version = execSync('docker --version', {
             encoding: 'utf8',
             stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 5000,
         });
         return {
             name: 'Docker daemon',
             status: 'pass',
             message: version.trim(),
+            fixEligibility: 'not-applicable',
         };
     }
     catch {
@@ -83,6 +190,8 @@ function checkDocker() {
                 'Install Docker Desktop or Docker Engine',
                 'Ensure Docker daemon is running',
             ],
+            fixEligibility: 'manual-only',
+            remediationKey: 'docker-repair',
         };
     }
 }
@@ -95,6 +204,7 @@ function checkDockerCompose() {
         const version = execSync('docker compose version', {
             encoding: 'utf8',
             stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 5000,
         });
         const versionMatch = version.match(/v?(\d+\.\d+\.\d+)/);
         const currentVersion = versionMatch ? versionMatch[1] : '0.0.0';
@@ -104,6 +214,7 @@ function checkDockerCompose() {
                 name: 'Docker Compose',
                 status: 'pass',
                 message: `v${currentVersion} (v2 required)`,
+                fixEligibility: 'not-applicable',
             };
         }
         else {
@@ -115,6 +226,7 @@ function checkDockerCompose() {
                     'Docker Compose v2 is recommended for compose-based templates',
                     'Update Docker Desktop or install docker-compose-plugin',
                 ],
+                fixEligibility: 'manual-only',
             };
         }
     }
@@ -124,6 +236,7 @@ function checkDockerCompose() {
             const version = execSync('docker-compose --version', {
                 encoding: 'utf8',
                 stdio: ['pipe', 'pipe', 'ignore'],
+                timeout: 5000,
             });
             return {
                 name: 'Docker Compose',
@@ -133,6 +246,7 @@ function checkDockerCompose() {
                     'Docker Compose v1 detected',
                     'Consider upgrading to v2: docker compose (not docker-compose)',
                 ],
+                fixEligibility: 'manual-only',
             };
         }
         catch {
@@ -145,6 +259,7 @@ function checkDockerCompose() {
                     'Install Docker Desktop (includes Compose v2)',
                     'Or install docker-compose-plugin',
                 ],
+                fixEligibility: 'manual-only',
             };
         }
     }
@@ -152,10 +267,10 @@ function checkDockerCompose() {
 /**
  * Run environment checks
  */
-function checkEnvironment(outputPath) {
+function checkEnvironment(outputPath, explicitManifestPath) {
     const results = [checkNodeVersion(), checkDocker()];
     // Only check Docker Compose if using compose stack
-    const baseTemplate = getBaseTemplateFromManifest(outputPath);
+    const baseTemplate = getBaseTemplateFromManifest(outputPath, explicitManifestPath);
     if (baseTemplate === 'compose') {
         results.push(checkDockerCompose());
     }
@@ -164,8 +279,8 @@ function checkEnvironment(outputPath) {
 /**
  * Get base template from manifest if it exists
  */
-function getBaseTemplateFromManifest(outputPath) {
-    const manifestPath = path.join(outputPath, 'superposition.json');
+function getBaseTemplateFromManifest(outputPath, explicitManifestPath) {
+    const manifestPath = explicitManifestPath ?? path.join(outputPath, 'superposition.json');
     if (!fs.existsSync(manifestPath)) {
         return undefined;
     }
@@ -258,9 +373,21 @@ function validateOverlayManifest(overlayDir, overlayId) {
     // Validate imports if present
     if (manifest.imports && manifest.imports.length > 0) {
         const overlaysDir = path.dirname(overlayDir);
+        const sharedBase = path.resolve(overlaysDir, '.shared');
         const missingImports = [];
         const invalidImports = [];
+        const traversalImports = [];
         for (const importPath of manifest.imports) {
+            // FR-006: Check for path traversal
+            if (!importPath.startsWith('.shared/')) {
+                traversalImports.push(`${importPath} (must begin with '.shared/')`);
+                continue;
+            }
+            const resolved = path.resolve(overlaysDir, importPath);
+            if (!resolved.startsWith(sharedBase + path.sep) && resolved !== sharedBase) {
+                traversalImports.push(`${importPath} (resolves outside '.shared/' directory)`);
+                continue;
+            }
             const fullImportPath = path.join(overlaysDir, importPath);
             if (!fs.existsSync(fullImportPath)) {
                 missingImports.push(importPath);
@@ -272,8 +399,11 @@ function validateOverlayManifest(overlayDir, overlayId) {
                 invalidImports.push(`${importPath} (unsupported type: ${ext})`);
             }
         }
-        if (missingImports.length > 0 || invalidImports.length > 0) {
+        if (traversalImports.length > 0 || missingImports.length > 0 || invalidImports.length > 0) {
             const details = [];
+            if (traversalImports.length > 0) {
+                details.push(`Path traversal rejected: ${traversalImports.join(', ')}`);
+            }
             if (missingImports.length > 0) {
                 details.push(`Missing imports: ${missingImports.join(', ')}`);
             }
@@ -403,11 +533,11 @@ function checkPorts(overlaysConfig, manifestPath) {
 /**
  * Check manifest compatibility
  */
-function checkManifest(outputPath) {
+function checkManifest(outputPath, explicitManifestPath) {
     const results = [];
-    const manifestPath = path.join(outputPath, 'superposition.json');
-    // Check if output path exists
-    if (!fs.existsSync(outputPath)) {
+    const manifestPath = explicitManifestPath ?? path.join(outputPath, 'superposition.json');
+    // Check if output path exists (skip when manifest is explicitly provided; the dir may not exist yet)
+    if (!explicitManifestPath && !fs.existsSync(outputPath)) {
         return [
             {
                 name: 'Devcontainer directory',
@@ -463,6 +593,9 @@ function checkManifest(outputPath) {
                 ? `Schema version ${manifest.manifestVersion} (tool ${manifest.generatedBy || 'unknown'})`
                 : `Legacy format (tool ${manifest.version || 'unknown'})`,
             details: versionDetails,
+            fixEligibility: needsUpdate && supported ? 'automatic' : 'not-applicable',
+            remediationKey: needsUpdate && supported ? 'manifest-migration' : undefined,
+            fixable: needsUpdate && supported,
         });
         // Check for required fields
         if (!manifest.baseTemplate) {
@@ -470,6 +603,7 @@ function checkManifest(outputPath) {
                 name: 'Manifest base template',
                 status: 'fail',
                 message: 'Missing baseTemplate field',
+                fixEligibility: 'manual-only',
             });
         }
         // Check devcontainer.json exists
@@ -480,6 +614,9 @@ function checkManifest(outputPath) {
                 status: 'fail',
                 message: 'devcontainer.json not found',
                 details: ['Devcontainer configuration file is missing or corrupted'],
+                fixEligibility: 'automatic',
+                remediationKey: 'devcontainer-regeneration',
+                fixable: true,
             });
         }
         else {
@@ -491,6 +628,7 @@ function checkManifest(outputPath) {
                     name: 'DevContainer config',
                     status: 'pass',
                     message: 'devcontainer.json valid',
+                    fixEligibility: 'not-applicable',
                 });
             }
             catch {
@@ -498,6 +636,9 @@ function checkManifest(outputPath) {
                     name: 'DevContainer config',
                     status: 'fail',
                     message: 'devcontainer.json has invalid JSON',
+                    fixEligibility: 'automatic',
+                    remediationKey: 'devcontainer-regeneration',
+                    fixable: true,
                 });
             }
         }
@@ -508,6 +649,7 @@ function checkManifest(outputPath) {
             status: 'fail',
             message: 'Invalid JSON in superposition.json',
             details: [`Parse error: ${error instanceof Error ? error.message : String(error)}`],
+            fixEligibility: 'manual-only',
         });
     }
     return results;
@@ -787,33 +929,740 @@ function formatAsText(report) {
     return lines.join('\n');
 }
 /**
- * Apply automatic fixes
- */
-async function applyFixes(report, outputPath) {
-    console.log(chalk.bold('\nApplying fixes...\n'));
-    const fixableChecks = [
-        ...report.environment,
-        ...report.overlays,
-        ...report.manifest,
-        ...report.merge,
-        ...report.ports,
-    ].filter((c) => c.fixable);
-    if (fixableChecks.length === 0) {
-        console.log(chalk.yellow('No automatic fixes available.'));
-        return;
-    }
-    for (const check of fixableChecks) {
-        console.log(`  ${chalk.cyan('→')} Fixing: ${check.name}...`);
-        // Currently, we don't have any auto-fixable issues
-        // This is a placeholder for future fix implementations
-        console.log(`    ${chalk.dim('Manual intervention required')}`);
+ * Convert a report section + category into DiagnosticFinding objects.
+ */
+function checksToFindings(checks, category, recheckScope) {
+    return checks.map((c) => {
+        const id = c.name
+            .toLowerCase()
+            .replace(/\s+/g, '-')
+            .replace(/[^a-z0-9-]/g, '');
+        return {
+            id,
+            category,
+            name: c.name,
+            status: c.status,
+            message: c.message,
+            details: c.details,
+            fixEligibility: c.fixEligibility ?? 'not-applicable',
+            remediationKey: c.remediationKey,
+            recheckScope,
+        };
+    });
+}
+/**
+ * Convert a full DoctorReport into a flat DiagnosticFinding array.
+ */
+function reportToFindings(report) {
+    return [
+        ...checksToFindings(report.environment, 'environment', 'environment'),
+        ...checksToFindings(report.overlays, 'overlay', 'full'),
+        ...checksToFindings(report.manifest, 'manifest', 'manifest'),
+        ...checksToFindings(report.merge, 'merge', 'devcontainer'),
+        ...checksToFindings(report.ports, 'ports', 'environment'),
+    ];
+}
+/**
+ * Order findings for remediation: manifest migration must come before regeneration.
+ */
+function orderFindingsForRemediation(findings) {
+    const PRIORITY = {
+        'manifest-migration': 1,
+        'devcontainer-regeneration': 2,
+        'node-version-fix': 3,
+        'docker-repair': 4,
+    };
+    return [...findings].sort((a, b) => {
+        const pa = PRIORITY[a.remediationKey ?? ''] ?? 99;
+        const pb = PRIORITY[b.remediationKey ?? ''] ?? 99;
+        return pa - pb;
+    });
+}
+/**
+ * Atomically write a JSON file (write to .tmp then rename).
+ * On Windows, rename fails if the destination already exists; delete it first.
+ */
+function atomicWriteJson(filePath, data) {
+    const tmpPath = filePath + '.tmp';
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    // Windows requires the destination to be absent before renaming.
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+    fs.renameSync(tmpPath, filePath);
+}
+/**
+ * Create a timestamped backup of a file and return the backup path.
+ */
+function backupFile(filePath) {
+    const timestamp = new Date()
+        .toISOString()
+        .replace(/[:.]/g, '-')
+        .replace('T', '-')
+        .replace('Z', '');
+    const backupPath = `${filePath}.backup-${timestamp}`;
+    fs.copyFileSync(filePath, backupPath);
+    return backupPath;
+}
+/**
+ * Build QuestionnaireAnswers from a SuperpositionManifest using overlaysConfig
+ * for category resolution.  Used by the devcontainer-regeneration fix.
+ */
+function buildAnswersFromManifest(manifest, manifestDir, overlaysConfig) {
+    const knownBaseImageIds = ['bookworm', 'trixie', 'alpine', 'ubuntu', 'custom'];
+    const isKnownBaseImage = knownBaseImageIds.includes(manifest.baseImage);
+    const language = [];
+    const database = [];
+    const observability = [];
+    const cloudTools = [];
+    const devTools = [];
+    const overlayMap = new Map(overlaysConfig.overlays.map((o) => [o.id, o]));
+    for (const id of manifest.overlays) {
+        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 {
+        stack: manifest.baseTemplate,
+        baseImage: isKnownBaseImage ? manifest.baseImage : 'custom',
+        customImage: isKnownBaseImage ? undefined : manifest.baseImage,
+        containerName: manifest.containerName,
+        preset: manifest.preset,
+        presetChoices: manifest.presetChoices,
+        language,
+        database,
+        observability,
+        cloudTools,
+        devTools,
+        needsDocker: manifest.baseTemplate === 'compose',
+        playwright: devTools.includes('playwright'),
+        outputPath: manifestDir,
+        portOffset: manifest.portOffset,
+    };
+}
+/**
+ * Execute manifest migration fix (Class 1).
+ */
+function executeManifestMigration(outputPath, explicitManifestPath) {
+    const manifestPath = explicitManifestPath ?? path.join(outputPath, 'superposition.json');
+    if (!fs.existsSync(manifestPath)) {
+        return {
+            findingId: 'manifest-version',
+            remediationKey: 'manifest-migration',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: 'superposition.json not found — cannot migrate',
+            rechecked: false,
+        };
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        return {
+            findingId: 'manifest-version',
+            remediationKey: 'manifest-migration',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: `Cannot parse superposition.json: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    if (!needsMigration(manifest)) {
+        return {
+            findingId: 'manifest-version',
+            remediationKey: 'manifest-migration',
+            attempted: false,
+            outcome: 'already-compliant',
+            reason: 'Manifest is already at the current schema version',
+            rechecked: true,
+        };
+    }
+    let backupPath;
+    try {
+        backupPath = backupFile(manifestPath);
+    }
+    catch (err) {
+        return {
+            findingId: 'manifest-version',
+            remediationKey: 'manifest-migration',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: `Failed to create backup: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    try {
+        const migrated = migrateManifest(manifest);
+        atomicWriteJson(manifestPath, migrated);
+    }
+    catch (err) {
+        // Restore backup on failure
+        try {
+            fs.copyFileSync(backupPath, manifestPath);
+        }
+        catch {
+            // best effort
+        }
+        return {
+            findingId: 'manifest-version',
+            remediationKey: 'manifest-migration',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Migration failed: ${err instanceof Error ? err.message : String(err)}`,
+            backupPath,
+            rechecked: false,
+        };
+    }
+    // Re-check
+    try {
+        const updated = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const stillNeeds = needsMigration(updated);
+        return {
+            findingId: 'manifest-version',
+            remediationKey: 'manifest-migration',
+            attempted: true,
+            outcome: stillNeeds ? 'requires-manual-action' : 'fixed',
+            reason: stillNeeds
+                ? 'Migration wrote file but schema still reports outdated'
+                : 'Manifest migrated to current schema version',
+            changedFiles: [manifestPath],
+            backupPath,
+            rechecked: true,
+        };
+    }
+    catch {
+        return {
+            findingId: 'manifest-version',
+            remediationKey: 'manifest-migration',
+            attempted: true,
+            outcome: 'fixed',
+            reason: 'Manifest migrated (re-check skipped — parse error after write)',
+            changedFiles: [manifestPath],
+            backupPath,
+            rechecked: false,
+        };
+    }
+}
+/**
+ * Execute devcontainer regeneration fix (Class 2).
+ * @param silent When true, suppresses console output during regeneration (for --json mode).
+ */
+async function executeRegeneration(outputPath, overlaysConfig, overlaysDir, silent = false, explicitManifestPath) {
+    const manifestPath = explicitManifestPath ?? path.join(outputPath, 'superposition.json');
+    if (!fs.existsSync(manifestPath)) {
+        return {
+            findingId: 'devcontainer-config',
+            remediationKey: 'devcontainer-regeneration',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: 'No superposition.json found — run "container-superposition init" first',
+            rechecked: false,
+        };
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        return {
+            findingId: 'devcontainer-config',
+            remediationKey: 'devcontainer-regeneration',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: `Cannot parse superposition.json: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    if (!manifest.baseTemplate) {
+        return {
+            findingId: 'devcontainer-config',
+            remediationKey: 'devcontainer-regeneration',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: 'Manifest is missing required baseTemplate field — cannot regenerate',
+            rechecked: false,
+        };
+    }
+    const answers = buildAnswersFromManifest(manifest, outputPath, overlaysConfig);
+    // Suppress console output during regeneration when in JSON mode
+    const originalLog = console.log;
+    if (silent) {
+        console.log = () => { };
+    }
+    try {
+        await composeDevContainer(answers, overlaysDir, { isRegen: true });
+    }
+    catch (err) {
+        if (silent) {
+            console.log = originalLog;
+        }
+        return {
+            findingId: 'devcontainer-config',
+            remediationKey: 'devcontainer-regeneration',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Regeneration failed: ${err instanceof Error ? err.message : String(err)}`,
+            rechecked: false,
+        };
+    }
+    finally {
+        if (silent) {
+            console.log = originalLog;
+        }
+    }
+    // Re-check
+    const devcontainerPath = path.join(outputPath, 'devcontainer.json');
+    const exists = fs.existsSync(devcontainerPath);
+    let validJson = false;
+    if (exists) {
+        try {
+            JSON.parse(fs.readFileSync(devcontainerPath, 'utf8'));
+            validJson = true;
+        }
+        catch {
+            // invalid JSON
+        }
+    }
+    return {
+        findingId: 'devcontainer-config',
+        remediationKey: 'devcontainer-regeneration',
+        attempted: true,
+        outcome: exists && validJson ? 'fixed' : 'requires-manual-action',
+        reason: exists && validJson
+            ? 'devcontainer.json regenerated from superposition.json'
+            : 'Regeneration ran but devcontainer.json is still missing or invalid',
+        changedFiles: exists ? [devcontainerPath] : [],
+        rechecked: true,
+    };
+}
+/**
+ * Execute Node.js version fix (Class 3).
+ */
+function executeNodeVersionFix() {
+    const manager = detectVersionManager();
+    if (!manager) {
+        return {
+            findingId: 'nodejs-version',
+            remediationKey: 'node-version-fix',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: 'No version manager (nvm, fnm, or volta) found',
+            rechecked: false,
+        };
+    }
+    let fixCmd;
+    switch (manager) {
+        case 'nvm': {
+            const nvmScript = path.join(process.env.HOME ?? process.env.USERPROFILE ?? '', '.nvm', 'nvm.sh');
+            fixCmd = `source "${nvmScript}" && nvm install 20 && nvm use 20`;
+            break;
+        }
+        case 'fnm':
+            fixCmd = 'fnm install 20 && fnm use 20';
+            break;
+        case 'volta':
+            fixCmd = 'volta install node@20';
+            break;
+    }
+    // nvm and fnm only update the child shell's PATH — `doctor` won't see the change.
+    // Treat these as "installed; open a new shell" rather than attempting a re-check
+    // that will always fail in the current process.
+    // volta persists via its shim mechanism and can be verified immediately.
+    if (manager === 'nvm' || manager === 'fnm') {
+        const runCmd = manager === 'nvm' ? `bash -lc '${fixCmd}'` : `sh -lc '${fixCmd}'`;
+        try {
+            execSync(runCmd, { stdio: 'pipe', timeout: 60_000 });
+        }
+        catch (err) {
+            return {
+                findingId: 'nodejs-version',
+                remediationKey: 'node-version-fix',
+                attempted: true,
+                outcome: 'requires-manual-action',
+                reason: `Fix command failed: ${err instanceof Error ? err.message : String(err)}`,
+                commands: [fixCmd],
+                rechecked: false,
+            };
+        }
+        return {
+            findingId: 'nodejs-version',
+            remediationKey: 'node-version-fix',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Node.js 20 installed via ${manager}. Open a new shell (or run \`${fixCmd}\`) to activate it — the current process cannot pick up the PATH change.`,
+            commands: [fixCmd],
+            rechecked: false,
+        };
+    }
+    // volta: shim persists across processes — attempt + re-check is reliable.
+    try {
+        execSync(`sh -lc '${fixCmd}'`, { stdio: 'pipe', timeout: 60_000 });
+    }
+    catch (err) {
+        return {
+            findingId: 'nodejs-version',
+            remediationKey: 'node-version-fix',
+            attempted: true,
+            outcome: 'requires-manual-action',
+            reason: `Fix command failed: ${err instanceof Error ? err.message : String(err)}`,
+            commands: [fixCmd],
+            rechecked: false,
+        };
+    }
+    // Re-check (volta updates shim; new processes see the updated Node)
+    try {
+        const version = execSync('sh -lc "node --version"', {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 10_000,
+        });
+        const match = version.trim().match(/^v(\d+)/);
+        const major = match ? parseInt(match[1], 10) : 0;
+        if (major >= 20) {
+            return {
+                findingId: 'nodejs-version',
+                remediationKey: 'node-version-fix',
+                attempted: true,
+                outcome: 'fixed',
+                reason: `Node.js ${version.trim()} activated via volta`,
+                commands: [fixCmd],
+                rechecked: true,
+            };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return {
+        findingId: 'nodejs-version',
+        remediationKey: 'node-version-fix',
+        attempted: true,
+        outcome: 'requires-manual-action',
+        reason: `volta ran but node --version still reports < 20. Open a new shell and run: ${fixCmd}`,
+        commands: [fixCmd],
+        rechecked: true,
+    };
+}
+/**
+ * Execute a single remediation action and return its execution record.
+ */
+async function executeSingleFix(finding, outputPath, overlaysConfig, overlaysDir, silent = false, explicitManifestPath) {
+    switch (finding.remediationKey) {
+        case 'manifest-migration':
+            return executeManifestMigration(outputPath, explicitManifestPath);
+        case 'devcontainer-regeneration':
+            return executeRegeneration(outputPath, overlaysConfig, overlaysDir, silent, explicitManifestPath);
+        case 'node-version-fix':
+            return executeNodeVersionFix();
+        case 'docker-repair': {
+            return {
+                findingId: finding.id,
+                remediationKey: 'docker-repair',
+                attempted: false,
+                outcome: 'requires-manual-action',
+                reason: 'Docker daemon repair requires manual intervention',
+                rechecked: false,
+            };
+        }
+        default:
+            return {
+                findingId: finding.id,
+                remediationKey: finding.remediationKey ?? 'unknown',
+                attempted: false,
+                outcome: 'requires-manual-action',
+                reason: `No remediation handler registered for key "${finding.remediationKey}"`,
+                rechecked: false,
+            };
+    }
+}
+/**
+ * Build the FixOutcomeSummary from a list of executions.
+ */
+function buildOutcomeSummary(executions) {
+    const counts = {
+        fixed: 0,
+        alreadyCompliant: 0,
+        skipped: 0,
+        requiresManualAction: 0,
+    };
+    for (const ex of executions) {
+        switch (ex.outcome) {
+            case 'fixed':
+                counts.fixed++;
+                break;
+            case 'already-compliant':
+                counts.alreadyCompliant++;
+                break;
+            case 'skipped':
+                counts.skipped++;
+                break;
+            case 'requires-manual-action':
+                counts.requiresManualAction++;
+                break;
+        }
+    }
+    return { ...counts, total: executions.length };
+}
+/**
+ * Determine the exit disposition from summary and final findings.
+ */
+function determineExitDisposition(summary, finalFindings) {
+    // Any failing finding (regardless of fix eligibility) is an unresolved failure.
+    const unresolvedFailures = finalFindings.filter((f) => f.status === 'fail');
+    if (unresolvedFailures.length > 0) {
+        return 'unresolved-failures';
+    }
+    if (summary.requiresManualAction > 0 || summary.skipped > 0) {
+        return 'repaired-with-warnings';
+    }
+    return 'success';
+}
+/**
+ * Run the full fix flow: diagnose → narrate → remediate → re-check → summarise.
+ */
+async function executeFixRun(report, outputPath, overlaysConfig, overlaysDir, requestedJson, explicitManifestPath) {
+    const initialFindings = reportToFindings(report);
+    // Separate automatic and manual-only fixable findings
+    const autoFixable = initialFindings.filter((f) => f.fixEligibility === 'automatic' && f.status !== 'pass');
+    const manualOnly = initialFindings.filter((f) => f.fixEligibility === 'manual-only' && f.status !== 'pass');
+    // Order automatic fixes: prerequisites before dependents
+    const orderedAuto = orderFindingsForRemediation(autoFixable);
+    const executions = [];
+    let manifestMigrationFailed = false;
+    for (const finding of orderedAuto) {
+        // Dependency ordering: skip regeneration if manifest migration failed
+        if (finding.remediationKey === 'devcontainer-regeneration' && manifestMigrationFailed) {
+            executions.push({
+                findingId: finding.id,
+                remediationKey: 'devcontainer-regeneration',
+                attempted: false,
+                outcome: 'skipped',
+                reason: 'Skipped because manifest migration did not succeed',
+                rechecked: false,
+            });
+            continue;
+        }
+        // Narrate planned change (text mode)
+        if (!requestedJson) {
+            const action = REMEDIATION_REGISTRY.get(finding.remediationKey ?? '');
+            console.log(`\n  ${chalk.cyan('→')} Planning fix for: ${chalk.white(finding.name)}`);
+            if (action) {
+                for (const change of action.plannedChanges) {
+                    console.log(`    ${chalk.dim('·')} ${chalk.dim(change)}`);
+                }
+            }
+        }
+        const execution = await executeSingleFix(finding, outputPath, overlaysConfig, overlaysDir, requestedJson, explicitManifestPath);
+        executions.push(execution);
+        if (finding.remediationKey === 'manifest-migration' &&
+            execution.outcome !== 'fixed' &&
+            execution.outcome !== 'already-compliant') {
+            manifestMigrationFailed = true;
+        }
+    }
+    // Add manual-only findings as requires-manual-action
+    for (const finding of manualOnly) {
+        const action = REMEDIATION_REGISTRY.get(finding.remediationKey ?? '');
+        executions.push({
+            findingId: finding.id,
+            remediationKey: finding.remediationKey ?? 'manual',
+            attempted: false,
+            outcome: 'requires-manual-action',
+            reason: action
+                ? action.manualFallback.join(' | ')
+                : 'No automatic fix available for this issue',
+            rechecked: false,
+        });
+    }
+    // Re-run checks to get final state
+    const envChecks = checkEnvironment(outputPath, explicitManifestPath);
+    const manifestChecks = checkManifest(outputPath, explicitManifestPath);
+    const mergeChecks = checkMergeStrategy(outputPath);
+    const overlayChecks = checkOverlays(overlaysDir);
+    const finalManifestPath = explicitManifestPath ?? path.join(outputPath, 'superposition.json');
+    const portChecks = checkPorts(overlaysConfig, finalManifestPath);
+    const finalFindings = [
+        ...checksToFindings(envChecks, 'environment', 'environment'),
+        ...checksToFindings(manifestChecks, 'manifest', 'manifest'),
+        ...checksToFindings(mergeChecks, 'merge', 'devcontainer'),
+        ...checksToFindings(overlayChecks, 'overlay', 'full'),
+        ...checksToFindings(portChecks, 'ports', 'environment'),
+    ];
+    const summary = buildOutcomeSummary(executions);
+    const exitDisposition = determineExitDisposition(summary, finalFindings);
+    return {
+        outputPath,
+        requestedJson,
+        initialFindings,
+        executions,
+        finalFindings,
+        summary,
+        exitDisposition,
+    };
+}
+/**
+ * Format the fix run result as user-readable text.
+ */
+function formatFixRunText(fixRun) {
+    const lines = [];
+    const hasIssues = fixRun.finalFindings.some((f) => f.status === 'warn' || f.status === 'fail');
+    if (fixRun.executions.length === 0 && !hasIssues) {
+        lines.push(chalk.green('\n✓ No remediation needed — all checked items are already compliant.'));
+        return lines.join('\n');
+    }
+    if (fixRun.executions.length === 0 && hasIssues) {
+        lines.push(chalk.yellow('\n⚠ No automatic remediation available. Review the findings above for manual action.'));
+        return lines.join('\n');
+    }
+    lines.push(chalk.bold('\nRemediation Summary:'));
+    for (const ex of fixRun.executions) {
+        const finding = fixRun.initialFindings.find((f) => f.id === ex.findingId);
+        const name = finding?.name ?? ex.findingId;
+        let icon;
+        let outcomeLabel;
+        switch (ex.outcome) {
+            case 'fixed':
+                icon = chalk.green('✓');
+                outcomeLabel = chalk.green('fixed');
+                break;
+            case 'already-compliant':
+                icon = chalk.green('✓');
+                outcomeLabel = chalk.green('already compliant');
+                break;
+            case 'skipped':
+                icon = chalk.yellow('→');
+                outcomeLabel = chalk.yellow('skipped');
+                break;
+            default:
+                icon = chalk.red('✗');
+                outcomeLabel = chalk.red('requires manual action');
+        }
+        lines.push(`  ${icon} ${chalk.white(name)}: ${outcomeLabel}`);
+        lines.push(`    ${chalk.dim('Reason:')} ${chalk.dim(ex.reason)}`);
+        if (ex.changedFiles && ex.changedFiles.length > 0) {
+            lines.push(`    ${chalk.dim('Changed:')} ${chalk.dim(ex.changedFiles.join(', '))}`);
+        }
+        if (ex.backupPath) {
+            lines.push(`    ${chalk.dim('Backup:')}  ${chalk.dim(ex.backupPath)}`);
+        }
+        // Show manual fallback for requires-manual-action
+        if (ex.outcome === 'requires-manual-action') {
+            const action = REMEDIATION_REGISTRY.get(ex.remediationKey);
+            if (action && action.manualFallback.length > 0) {
+                lines.push(`    ${chalk.dim('Manual steps:')}`);
+                for (const step of action.manualFallback) {
+                    lines.push(`      ${chalk.dim('·')} ${chalk.dim(step)}`);
+                }
+            }
+        }
+    }
+    // Overall disposition
+    lines.push('');
+    const { summary, exitDisposition } = fixRun;
+    lines.push(chalk.bold('Fix Run Result:'));
+    if (summary.fixed > 0) {
+        lines.push(`  ${chalk.green('✓')} ${summary.fixed} fixed`);
+    }
+    if (summary.alreadyCompliant > 0) {
+        lines.push(`  ${chalk.green('✓')} ${summary.alreadyCompliant} already compliant`);
+    }
+    if (summary.skipped > 0) {
+        lines.push(`  ${chalk.yellow('→')} ${summary.skipped} skipped`);
+    }
+    if (summary.requiresManualAction > 0) {
+        lines.push(`  ${chalk.red('✗')} ${summary.requiresManualAction} require manual action`);
+    }
+    const dispositionColour = exitDisposition === 'success'
+        ? chalk.green
+        : exitDisposition === 'repaired-with-warnings'
+            ? chalk.yellow
+            : chalk.red;
+    lines.push(`\n  ${dispositionColour('Exit status:')} ${dispositionColour(exitDisposition)}`);
+    return lines.join('\n');
 }
 /**
  * Doctor command implementation
  */
 export async function doctorCommand(overlaysConfig, overlaysDir, options) {
-    const outputPath = options.output || './.devcontainer';
+    // ── Validate mutually exclusive source flags ───────────────────────────
+    if (options.fromManifest && options.fromProject) {
+        console.error(chalk.red('✗ Error: --from-manifest and --from-project cannot be used together'));
+        process.exit(1);
+    }
+    // ── Resolve working directory (--project-root) ────────────────────────
+    const workingDir = options.projectRoot ? path.resolve(options.projectRoot) : process.cwd();
+    if (options.projectRoot) {
+        if (!fs.existsSync(workingDir)) {
+            console.error(chalk.red(`✗ Project root not found: ${workingDir}`));
+            process.exit(1);
+        }
+        if (!fs.statSync(workingDir).isDirectory()) {
+            console.error(chalk.red(`✗ Project root is not a directory: ${workingDir}`));
+            process.exit(1);
+        }
+    }
+    // ── Resolve outputPath and optional explicit manifest path ─────────────
+    let outputPath;
+    let explicitManifestPath;
+    if (options.fromManifest) {
+        // Resolve manifest path (absolute or relative to workingDir)
+        const resolvedManifest = path.resolve(workingDir, options.fromManifest);
+        if (!fs.existsSync(resolvedManifest)) {
+            console.error(chalk.red(`✗ Could not find manifest file: ${resolvedManifest}`));
+            process.exit(1);
+        }
+        explicitManifestPath = resolvedManifest;
+        // Derive outputPath from manifest's own outputPath field, relative to manifest's directory
+        try {
+            const raw = JSON.parse(fs.readFileSync(resolvedManifest, 'utf8'));
+            const manifestOutputPath = typeof raw.outputPath === 'string' ? raw.outputPath : '.devcontainer';
+            outputPath = path.resolve(path.dirname(resolvedManifest), manifestOutputPath);
+        }
+        catch {
+            // If the manifest is unparseable, use its directory as outputPath
+            outputPath = path.dirname(resolvedManifest);
+        }
+    }
+    else if (options.fromProject) {
+        // Load the repository project file (superposition.yml / .superposition.yml)
+        let projectConfig;
+        try {
+            projectConfig = loadProjectConfig(overlaysConfig, workingDir);
+        }
+        catch (err) {
+            console.error(chalk.red(`✗ Failed to load project config: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+        if (!projectConfig) {
+            console.error(chalk.red('✗ Could not find project file'));
+            console.error(chalk.gray('  Searched for: .superposition.yml, superposition.yml'));
+            console.error(chalk.gray('  Use --from-project in a repository that has a project config file, or use --from-manifest <path> instead'));
+            process.exit(1);
+        }
+        outputPath = path.resolve(workingDir, projectConfig.selection.outputPath || '.devcontainer');
+    }
+    else {
+        outputPath = path.resolve(workingDir, options.output || './.devcontainer');
+    }
     if (!options.json) {
         console.log('\n' +
             boxen(chalk.bold('🔍 Running diagnostics...'), {
@@ -823,40 +1672,54 @@ export async function doctorCommand(overlaysConfig, overlaysDir, options) {
             }));
     }
     // Run all checks
-    const environmentChecks = checkEnvironment(outputPath);
+    const environmentChecks = checkEnvironment(outputPath, explicitManifestPath);
     const overlayChecks = checkOverlays(overlaysDir);
-    const manifestChecks = checkManifest(outputPath);
+    const manifestChecks = checkManifest(outputPath, explicitManifestPath);
     const mergeChecks = checkMergeStrategy(outputPath);
-    const manifestPath = path.join(outputPath, 'superposition.json');
+    const manifestPath = explicitManifestPath ?? path.join(outputPath, 'superposition.json');
     const portChecks = checkPorts(overlaysConfig, manifestPath);
     // Generate report
     const report = generateReport(environmentChecks, overlayChecks, manifestChecks, mergeChecks, portChecks);
-    // Output results
-    if (options.json) {
-        console.log(JSON.stringify(report, null, 2));
-    }
-    else {
-        console.log(formatAsText(report));
-    }
-    // Apply fixes if requested
-    if (options.fix && !options.json) {
-        await applyFixes(report, outputPath);
-    }
-    // Exit with appropriate code
-    const hasErrors = report.summary.errors > 0;
-    const hasWarnings = report.summary.warnings > 0;
-    if (!options.json) {
-        console.log(''); // Empty line at end
-    }
-    // Exit with error if there are critical failures
-    if (hasErrors) {
-        process.exit(1);
-    }
-    else if (hasWarnings && !options.json) {
-        process.exit(0); // Warnings don't fail the command
+    if (options.fix) {
+        // ── Fix flow ──────────────────────────────────────────────────────────
+        if (!options.json) {
+            // Print diagnostic findings first (as normal)
+            console.log(formatAsText(report));
+        }
+        const fixRun = await executeFixRun(report, outputPath, overlaysConfig, overlaysDir, options.json ?? false, explicitManifestPath);
+        if (options.json) {
+            console.log(JSON.stringify(fixRun, null, 2));
+        }
+        else {
+            console.log(formatFixRunText(fixRun));
+            console.log('');
+        }
+        if (fixRun.exitDisposition === 'unresolved-failures') {
+            process.exit(1);
+        }
+        else {
+            process.exit(0);
+        }
     }
     else {
-        process.exit(0);
+        // ── Normal diagnostic output (unchanged) ─────────────────────────────
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(formatAsText(report));
+        }
+        // Exit with appropriate code
+        const hasErrors = report.summary.errors > 0;
+        if (!options.json) {
+            console.log(''); // Empty line at end
+        }
+        if (hasErrors) {
+            process.exit(1);
+        }
+        else {
+            process.exit(0);
+        }
     }
 }
 //# sourceMappingURL=doctor.js.map