@msn-control/liftoff 0.3.3 → 0.4.0

package/dist/commands.js

@@ -1,19 +1,27 @@
+import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { cp, mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { formatCommandHelp, readBooleanFlag, readListFlag, readStringFlag } from './args.js';
-import { apiStacks, listRegions, patterns, providers, searchRegions } from './catalogs.js';
-import { artifactPath, assertNewOrEmptyDirectory, deleteProjectFile, findProjectRoot, loadManifest, manifestDisplayPath, resolveProjectPath, resolveTargetRoot, validateGeneratedProject, writeArtifacts, writeProjectFile } from './file-system.js';
-import { confirmPlan, promptForCreateOptions } from './interactive.js';
+import { formatCommandHelp, formatGeneralHelp, readBooleanFlag, readListFlag, readStringFlag } from './args.js';
+import { getCodingAgent, getFrameworkDefinition, getSpecWorkflow, listRegions, patterns, providers, searchRegions } from './catalogs.js';
+import { initializeFramework } from './framework-adapters.js';
+import { validateFrameworkInstallation } from './framework-validation.js';
+import { artifactPath, assertNewOrEmptyDirectory, deleteProjectFile, findProjectRoot, loadManifest, manifestDisplayPath, resolveProjectPath, validateGeneratedProject, writeArtifacts, writeProjectFile } from './file-system.js';
+import { confirmDependencyInstallation, confirmFileReplacements, confirmPlan, confirmToolInstallation, promptForInitOptions } from './interactive.js';
+import { applyMergePreflight, assertSafeInitTarget, authorizeMergePreflight, buildMergePreflight, captureTreeState, discoverGitRoot, resolveInitTargetFromDiscovery, validateStagedTree, withStagingArea, writeStagedArtifacts } from './init-filesystem.js';
 import { renderMigrationChecklist, renderMigrationProposal, renderMigrationTasks, seedMigrationGroups } from './migrate-plan.js';
 import { buildProjectPlan, formatProjectPlan, loadConfigOptions, mergeOptions, PlanValidationError } from './planner.js';
+import { buildDependencySetupPlan, runDependencySetup } from './project-dependencies.js';
+import { formatCommand, NodeCommandRunner } from './process-runner.js';
 import { scanDefaults, scanLegacyProject } from './scan.js';
 import { hasDrift, reconcileProject } from './reconcile.js';
 import { compareSemver } from './semver.js';
-import { buildArtifacts, buildManifest } from './templates.js';
+import { buildArtifacts, buildManifest, partitionGeneratedArtifacts } from './templates.js';
+import { TerminalRenderer } from './terminal.js';
 import { liftoffVersion } from './version.js';
+import { blockingReadinessFailures, detectHostEnvironment, installRequirement, probeWorkstation, selectLiftoffRuntimeRequirements, selectWorkstationRequirements } from './workstation.js';
 export async function runCommand(parsed, context) {
     try {
         if (parsed.command && readBooleanFlag(parsed.flags, 'help')) {
@@ -31,8 +39,11 @@ export async function runCommand(parsed, context) {
                     printHelp(context.stdout);
                 }
                 return 0;
-            case 'create':
-                return await createCommand(parsed, context);
+            case 'version':
+                context.stdout.write(`Liftoff ${liftoffVersion}\n`);
+                return 0;
+            case 'init':
+                return await initCommand(parsed, context);
             case 'plan':
                 return await planCommand(parsed, context);
             case 'patterns':
@@ -68,25 +79,79 @@ export async function runCommand(parsed, context) {
         return 1;
     }
 }
-async function createCommand(parsed, context) {
-    const initial = await optionsFromParsedArgs(parsed, context.cwd, true);
-    const needsPrompts = !initial.yes && hasMissingCreateInputs(initial);
-    const options = needsPrompts ? await promptForCreateOptions(initial) : initial;
+async function initCommand(parsed, context) {
+    const runner = context.runner ?? new NodeCommandRunner();
+    const git = await discoverGitRoot(context.cwd, runner);
+    let initial = await optionsFromParsedArgs(parsed, context.cwd, true);
+    if (!initial.projectName && git.exact && git.root) {
+        initial = { ...initial, projectName: path.basename(git.root) };
+    }
+    const needsPrompts = !initial.yes && hasMissingInitInputs(initial);
+    const options = needsPrompts ? await promptForInitOptions(initial) : initial;
     const plan = buildProjectPlan(options, { requireProjectName: true });
     const confirmed = await confirmPlan(plan, options.yes);
     if (!confirmed) {
-        context.stdout.write('Generation cancelled.\n');
+        context.stdout.write('Initialization cancelled.\n');
         return 0;
     }
-    const targetRoot = resolveTargetRoot(context.cwd, plan.safeProjectName);
-    const artifacts = buildArtifacts(plan);
-    await writeArtifacts(targetRoot, artifacts);
-    const issues = await validateGeneratedProject(targetRoot);
+    const target = resolveInitTargetFromDiscovery(git, plan.safeProjectName);
+    await assertSafeInitTarget(target, target.mode === 'named-child' ? git.canonicalCwd : undefined);
+    const renderer = new TerminalRenderer({ stream: context.stdout });
+    renderer.write(renderer.banner('Initialize the project and prepare its workstation'));
+    const readiness = await ensureWorkstationReady(plan, options, context, runner, renderer);
+    if (!readiness.ready) {
+        return 1;
+    }
+    const staged = await withStagingArea(async (area) => {
+        const partition = partitionGeneratedArtifacts(buildArtifacts(plan));
+        await writeStagedArtifacts(area, partition.durable, 'liftoff');
+        await initializeFramework(area, plan, runner, { stdout: context.stdout, stderr: context.stderr });
+        await writeStagedArtifacts(area, partition.seed, 'seed');
+        await writeStagedArtifacts(area, [partition.manifest], 'liftoff');
+        await validateStagedTree(area);
+        const stagedIssues = await validateGeneratedProject(area.root);
+        if (stagedIssues.length > 0) {
+            throw new Error(`Staged project validation failed:\n${stagedIssues.join('\n')}`);
+        }
+        const preflight = await buildMergePreflight(area, target.root);
+        const interactive = options.yes !== true;
+        const authorized = await authorizeMergePreflight(preflight, options.force === true, interactive ? confirmFileReplacements : undefined);
+        if (!authorized) {
+            return {
+                status: interactive ? 'declined' : 'authorization-required'
+            };
+        }
+        return { status: 'applied', merge: await applyMergePreflight(authorized) };
+    });
+    if (staged.status === 'declined') {
+        context.stdout.write('Initialization cancelled; no destination files were changed.\n');
+        return 0;
+    }
+    if (staged.status === 'authorization-required') {
+        context.stderr.write('Existing regular-file conflicts require --force in non-interactive mode.\n');
+        return 1;
+    }
+    const issues = await validateGeneratedProject(target.root);
     if (issues.length > 0) {
-        context.stderr.write(`Generated project validation failed:\n${issues.join('\n')}\n`);
+        context.stderr.write(`Initialized project validation failed:\n${issues.join('\n')}\n`);
         return 1;
     }
-    context.stdout.write(`Created ${plan.projectName} at ${targetRoot}\n`);
+    const dependencyPhase = await handleProjectDependencies(plan, target.root, options, readiness.probes, context, runner, renderer);
+    if (!dependencyPhase.success) {
+        return 1;
+    }
+    renderer.write(renderer.status('success', `Initialized ${plan.projectName}`, target.root));
+    renderer.write(renderer.panel('Configured integrations', [
+        `${plan.specWorkflow.label} ${plan.framework.version}`,
+        ...plan.agents.map((agent) => `${agent.label}${plan.defaultAgent?.id === agent.id ? ' (default)' : ''}`)
+    ]));
+    if (readiness.deferred.length > 0) {
+        renderer.write(renderer.panel('Deferred advisory checks', readiness.deferred));
+    }
+    if (dependencyPhase.deferred.length > 0) {
+        renderer.write(renderer.panel('Deferred project dependencies', dependencyPhase.deferred));
+    }
+    renderer.write(renderer.command(`liftoff validate ${JSON.stringify(target.root)}`));
     return 0;
 }
 async function planCommand(parsed, context) {
@@ -97,8 +162,151 @@ async function planCommand(parsed, context) {
     for (const artifact of artifacts) {
         context.stdout.write(`- ${artifact.logicalName}: ${artifact.pathParts.join('/')}\n`);
     }
+    context.stdout.write('\nWorkstation requirements:\n');
+    for (const requirement of selectWorkstationRequirements(plan)) {
+        const version = requirement.exactVersion
+            ? `exactly ${requirement.exactVersion}`
+            : requirement.minimumVersion
+                ? `${requirement.minimumVersion}+`
+                : 'available';
+        context.stdout.write(`- ${requirement.definition.label}: ${version} [${requirement.severity}]\n`);
+    }
     return 0;
 }
+async function ensureWorkstationReady(plan, options, context, runner, renderer, resumeInvocation = 'liftoff init', commandCwd) {
+    const requirements = selectWorkstationRequirements(plan);
+    let probes = await probeWorkstation(requirements, runner, { cwd: commandCwd });
+    renderer.write(renderer.heading('Workstation readiness'));
+    renderer.write(renderer.table(['Requirement', 'Level', 'State', 'Detail'], probes.map((probe) => [
+        probe.requirement.definition.label,
+        probe.requirement.severity,
+        probe.state,
+        probe.detail
+    ])));
+    const actionable = probes.filter((probe) => probe.state !== 'ready');
+    const host = await detectHostEnvironment();
+    const installInstruction = (probe) => {
+        const recipe = probe.requirement.definition.install[host.platform];
+        const automatic = recipe && (host.platform !== 'linux' || recipe.manager === 'npm' || recipe.manager === 'uv');
+        if (automatic) {
+            return formatCommand(recipe.command);
+        }
+        if (host.platform === 'linux') {
+            return probe.requirement.definition.linuxRemedies[host.linuxFamily];
+        }
+        return `Install ${probe.requirement.definition.label} manually, then retry.`;
+    };
+    const authorizedInstallations = new Set();
+    if (options.installTools === true) {
+        for (const probe of actionable) {
+            authorizedInstallations.add(probe.requirement.id);
+        }
+    }
+    if (options.installTools === undefined &&
+        options.yes !== true &&
+        actionable.length > 0) {
+        for (const probe of actionable) {
+            const recipe = probe.requirement.definition.install[host.platform];
+            const automatic = recipe && (host.platform !== 'linux' || recipe.manager === 'npm' || recipe.manager === 'uv');
+            const constraint = probe.requirement.exactVersion
+                ? `required exactly ${probe.requirement.exactVersion}`
+                : probe.requirement.minimumVersion
+                    ? `required ${probe.requirement.minimumVersion} or newer`
+                    : 'required to be available';
+            const action = automatic
+                ? `Command: ${formatCommand(recipe.command)}`
+                : `Manual remedy: ${installInstruction(probe)}`;
+            const detail = [
+                `${probe.requirement.definition.label} [${probe.requirement.severity}]`,
+                `Purpose: ${probe.requirement.reasons.join('; ')}`,
+                `Requirement: ${constraint}`,
+                `Observed: ${probe.state} - ${probe.detail}`,
+                action
+            ].map((line) => `  ${line}`).join('\n');
+            if (await confirmToolInstallation(detail)) {
+                authorizedInstallations.add(probe.requirement.id);
+            }
+        }
+    }
+    if (authorizedInstallations.size > 0) {
+        const updates = new Map();
+        for (const probe of actionable) {
+            if (!authorizedInstallations.has(probe.requirement.id)) {
+                continue;
+            }
+            const installation = await installRequirement(probe.requirement, probe, {
+                authorized: true,
+                host,
+                runner,
+                cwd: commandCwd,
+                streamOptions: { stdout: context.stdout, stderr: context.stderr }
+            });
+            updates.set(probe.requirement.id, installation.probe);
+            const kind = installation.state === 'installed'
+                ? 'success'
+                : probe.requirement.severity === 'blocking'
+                    ? 'error'
+                    : 'warning';
+            renderer.write(renderer.status(kind, probe.requirement.definition.label, installation.detail));
+            if (installation.remedy) {
+                renderer.write(renderer.command(installation.remedy));
+            }
+        }
+        probes = probes.map((probe) => updates.get(probe.requirement.id) ?? probe);
+    }
+    const blockers = blockingReadinessFailures(probes);
+    if (blockers.length > 0) {
+        for (const blocker of blockers) {
+            context.stderr.write(`${blocker.requirement.definition.label}: ${blocker.detail}` +
+                `\nRemedy: ${installInstruction(blocker)}\n`);
+        }
+        context.stderr.write(options.installTools
+            ? `Open a new terminal if PATH changed, then rerun \`${resumeInvocation}\` with the same project options.\n`
+            : `Resume with \`${resumeInvocation} --install-tools\` plus the same project options after reviewing the commands.\n`);
+        return { ready: false, deferred: [], probes };
+    }
+    const deferred = [
+        ...probes
+            .filter((probe) => probe.requirement.severity === 'advisory' && probe.state !== 'ready')
+            .map((probe) => `${probe.requirement.definition.label}: ${probe.detail} Remedy: ${installInstruction(probe)}`),
+        ...probes.flatMap((probe) => probe.notices
+            .filter((notice) => notice.state !== 'ready')
+            .map((notice) => `${notice.label}: ${notice.detail}${notice.remedy ? ` Remedy: ${notice.remedy}` : ''}`))
+    ];
+    return { ready: true, deferred, probes };
+}
+async function handleProjectDependencies(plan, projectRoot, options, probes, context, runner, renderer) {
+    const dependencyPlan = buildDependencySetupPlan(plan, projectRoot, probes);
+    let installDependencies = options.installDependencies === true;
+    if (options.installDependencies === undefined &&
+        options.yes !== true &&
+        dependencyPlan.commands.length > 0) {
+        installDependencies = await confirmDependencyInstallation(dependencyPlan.commands);
+    }
+    if (!installDependencies) {
+        return {
+            success: true,
+            deferred: dependencyPlan.commands.map((command) => `${command.label}: ${command.cwd} -> ${formatCommand(command.command)}`)
+        };
+    }
+    const result = await runDependencySetup(dependencyPlan, projectRoot, runner, {
+        stdout: context.stdout,
+        stderr: context.stderr
+    });
+    if (!result.success) {
+        renderer.write(renderer.status('error', 'Project dependencies failed', `${result.failed?.label ?? 'dependency command'}: ${result.detail ?? 'unknown failure'}`));
+        renderer.write(renderer.status('info', 'Scaffold preserved', projectRoot));
+        if (result.restoredMutations.length > 0) {
+            renderer.write(renderer.warning(`Restored protected files: ${result.restoredMutations.join(', ')}`));
+        }
+        if (result.resumeCommand) {
+            renderer.write(renderer.command(result.resumeCommand));
+        }
+        return { success: false, deferred: [] };
+    }
+    renderer.write(renderer.status('success', 'Project dependencies', `${result.completed.length} command${result.completed.length === 1 ? '' : 's'} completed`));
+    return { success: true, deferred: [] };
+}
 function patternsCommand(context) {
     context.stdout.write('Patterns:\n');
     for (const pattern of patterns) {
@@ -140,29 +348,112 @@ async function validateCommand(parsed, context) {
     return 0;
 }
 const STAGING_EXCLUDES = new Set(['.git', 'node_modules', 'vendor', '.venv', 'venv', '__pycache__', 'dist', 'build', '.next']);
-async function migrateCommand(parsed, context) {
-    const sourceArg = parsed.positional[0];
-    if (!sourceArg) {
-        context.stderr.write('Usage: liftoff migrate <path-to-existing-project>\n');
-        return 1;
-    }
-    const sourceRoot = path.resolve(context.cwd, sourceArg);
-    let sourceDetails;
+async function snapshotMigrationSource(sourceRoot) {
+    const snapshot = new Map();
+    const visit = async (pathParts) => {
+        const current = path.join(sourceRoot, ...pathParts);
+        const entries = await readdir(current, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name, 'en'));
+        for (const entry of entries) {
+            const childParts = [...pathParts, entry.name];
+            const relativePath = childParts.join('/');
+            const childPath = path.join(sourceRoot, ...childParts);
+            const details = await lstat(childPath);
+            if (details.isSymbolicLink()) {
+                snapshot.set(relativePath, `symlink:${await readlink(childPath)}`);
+            }
+            else if (details.isDirectory()) {
+                snapshot.set(relativePath, 'directory');
+                await visit(childParts);
+            }
+            else if (details.isFile()) {
+                const hash = createHash('sha256').update(await readFile(childPath)).digest('hex');
+                snapshot.set(relativePath, `file:${hash}`);
+            }
+            else {
+                snapshot.set(relativePath, 'other');
+            }
+        }
+    };
+    await visit([]);
+    return snapshot;
+}
+function sourceSnapshotChanges(before, after) {
+    return [...new Set([...before.keys(), ...after.keys()])]
+        .filter((key) => before.get(key) !== after.get(key))
+        .sort();
+}
+async function withUnchangedMigrationSource(sourceRoot, operation) {
+    const before = await snapshotMigrationSource(sourceRoot);
+    const assertUnchanged = async () => {
+        const changes = sourceSnapshotChanges(before, await snapshotMigrationSource(sourceRoot));
+        if (changes.length > 0) {
+            throw new Error(`Migration source changed unexpectedly; refusing to continue:\n${changes.map((entry) => `- ${entry}`).join('\n')}`);
+        }
+    };
+    let result;
     try {
-        sourceDetails = await stat(sourceRoot);
+        result = await operation();
     }
-    catch {
-        context.stderr.write(`Source project not found: ${sourceRoot}\n`);
-        return 1;
+    catch (error) {
+        await assertUnchanged();
+        throw error;
     }
-    if (!sourceDetails.isDirectory()) {
-        context.stderr.write(`Source path is not a directory: ${sourceRoot}\n`);
-        return 1;
+    await assertUnchanged();
+    return result;
+}
+async function stageMigrationSource(area, sourceRoot) {
+    const destination = path.join(area.root, 'migration', 'legacy');
+    await cp(sourceRoot, destination, {
+        recursive: true,
+        filter: (source) => {
+            const relative = path.relative(sourceRoot, source);
+            if (!relative) {
+                return true;
+            }
+            return !relative.split(path.sep).some((part) => STAGING_EXCLUDES.has(part));
+        }
+    });
+    for (const entry of (await captureTreeState(area.root)).values()) {
+        if (entry.pathParts[0] === 'migration' &&
+            entry.pathParts[1] === 'legacy' &&
+            entry.type !== 'directory') {
+            area.origins.set(entry.pathParts.join('/'), 'seed');
+        }
     }
-    if (existsSync(path.join(sourceRoot, 'liftoff.manifest.json'))) {
-        context.stderr.write(`${sourceRoot} is already a Liftoff project. Use liftoff update instead.\n`);
-        return 1;
+}
+function migrationPlanArtifacts(plan, inventory) {
+    const groups = seedMigrationGroups(inventory, plan);
+    if (plan.specWorkflow.id === 'openspec') {
+        return {
+            artifacts: [
+                {
+                    logicalName: 'migration-proposal',
+                    category: 'seed',
+                    pathParts: ['openspec', 'changes', 'migrate-to-liftoff', 'proposal.md'],
+                    content: renderMigrationProposal(plan, inventory)
+                },
+                {
+                    logicalName: 'migration-tasks',
+                    category: 'seed',
+                    pathParts: ['openspec', 'changes', 'migrate-to-liftoff', 'tasks.md'],
+                    content: renderMigrationTasks(groups)
+                }
+            ],
+            location: 'openspec/changes/migrate-to-liftoff/ (run it with your agent workflow, e.g. /opsx:apply migrate-to-liftoff)'
+        };
     }
+    return {
+        artifacts: [{
+                logicalName: 'migration-checklist',
+                category: 'seed',
+                pathParts: ['MIGRATION.md'],
+                content: renderMigrationChecklist(plan, inventory, groups)
+            }],
+        location: 'MIGRATION.md'
+    };
+}
+async function executeMigration(parsed, context, sourceRoot) {
     const inventory = await scanLegacyProject(sourceRoot);
     const { options: defaults, provenance } = scanDefaults(inventory);
     context.stdout.write('Scan defaults (override in prompts or with flags):\n');
@@ -188,8 +479,8 @@ async function migrateCommand(parsed, context) {
     if (flagOptions.projectType === 'genai' && flagOptions.apiStack === undefined) {
         initial.apiStack = undefined;
     }
-    const needsPrompts = !initial.yes && hasMissingCreateInputs(initial);
-    const options = needsPrompts ? await promptForCreateOptions(initial) : initial;
+    const needsPrompts = !initial.yes && hasMissingInitInputs(initial);
+    const options = needsPrompts ? await promptForInitOptions(initial) : initial;
     const plan = buildProjectPlan(options, { requireProjectName: true });
     const confirmed = await confirmPlan(plan, options.yes);
     if (!confirmed) {
@@ -201,45 +492,105 @@ async function migrateCommand(parsed, context) {
     if (targetRoot === sourceRoot) {
         targetRoot = path.resolve(parentDir, `${plan.safeProjectName}-liftoff`);
     }
-    const artifacts = buildArtifacts(plan);
-    await writeArtifacts(targetRoot, artifacts);
-    const issues = await validateGeneratedProject(targetRoot);
-    if (issues.length > 0) {
-        context.stderr.write(`Generated scaffold validation failed:\n${issues.join('\n')}\n`);
+    const target = { root: targetRoot, mode: 'named-child' };
+    await assertSafeInitTarget(target, parentDir);
+    await assertNewOrEmptyDirectory(targetRoot);
+    const runner = context.runner ?? new NodeCommandRunner();
+    const renderer = new TerminalRenderer({ stream: context.stdout });
+    renderer.write(renderer.banner('Migrate into a fresh Liftoff project'));
+    const readinessRoot = await mkdtemp(path.join(os.tmpdir(), 'liftoff-migrate-readiness-'));
+    const readiness = await (async () => {
+        try {
+            return await ensureWorkstationReady(plan, options, context, runner, renderer, `liftoff migrate ${JSON.stringify(sourceRoot)}`, readinessRoot);
+        }
+        finally {
+            await rm(readinessRoot, { recursive: true, force: true });
+        }
+    })();
+    if (!readiness.ready) {
         return 1;
     }
-    const stagingRoot = path.join(targetRoot, 'migration', 'legacy');
-    await cp(sourceRoot, stagingRoot, {
-        recursive: true,
-        filter: (source) => {
-            const relative = path.relative(sourceRoot, source);
-            if (!relative) {
-                return true;
-            }
-            return !relative.split(path.sep).some((part) => STAGING_EXCLUDES.has(part));
+    const migrationPlan = migrationPlanArtifacts(plan, inventory);
+    await withStagingArea(async (area) => {
+        const partition = partitionGeneratedArtifacts(buildArtifacts(plan));
+        await writeStagedArtifacts(area, partition.durable, 'liftoff');
+        await initializeFramework(area, plan, runner, {
+            stdout: context.stdout,
+            stderr: context.stderr
+        });
+        await writeStagedArtifacts(area, partition.seed, 'seed');
+        await stageMigrationSource(area, sourceRoot);
+        await writeStagedArtifacts(area, migrationPlan.artifacts, 'seed');
+        await writeStagedArtifacts(area, [partition.manifest], 'liftoff');
+        await validateStagedTree(area);
+        const stagedIssues = await validateGeneratedProject(area.root);
+        if (stagedIssues.length > 0) {
+            throw new Error(`Staged migration project validation failed:\n${stagedIssues.join('\n')}`);
         }
+        const preflight = await buildMergePreflight(area, targetRoot);
+        const existing = preflight.entries.filter((entry) => entry.destination.type !== 'missing');
+        if (existing.length > 0) {
+            throw new Error(`Migration target must remain new or empty; --force cannot replace existing content:\n` +
+                existing.map((entry) => `- ${entry.relativePath}`).join('\n'));
+        }
+        const authorized = await authorizeMergePreflight(preflight, false);
+        if (!authorized) {
+            throw new Error('Migration target authorization failed.');
+        }
+        await applyMergePreflight(authorized, { requireEmptyTarget: true });
     });
-    const groups = seedMigrationGroups(inventory, plan);
-    let planLocation;
-    if (plan.specWorkflow.id === 'openspec') {
-        const changeDir = path.join(targetRoot, 'openspec', 'changes', 'migrate-to-liftoff');
-        await mkdir(changeDir, { recursive: true });
-        await writeFile(path.join(changeDir, 'proposal.md'), renderMigrationProposal(plan, inventory), 'utf8');
-        await writeFile(path.join(changeDir, 'tasks.md'), renderMigrationTasks(groups), 'utf8');
-        planLocation = 'openspec/changes/migrate-to-liftoff/ (run it with your agent workflow, e.g. /opsx:apply migrate-to-liftoff)';
+    const issues = await validateGeneratedProject(targetRoot);
+    if (issues.length > 0) {
+        context.stderr.write(`Migrated project validation failed:\n${issues.join('\n')}\n`);
+        return 1;
     }
-    else {
-        await writeFile(path.join(targetRoot, 'MIGRATION.md'), renderMigrationChecklist(plan, inventory, groups), 'utf8');
-        planLocation = 'MIGRATION.md';
+    const dependencyPhase = await handleProjectDependencies(plan, targetRoot, options, readiness.probes, context, runner, renderer);
+    if (!dependencyPhase.success) {
+        return 1;
+    }
+    renderer.write(renderer.status('success', `Migrated ${plan.projectName}`, targetRoot));
+    renderer.write(renderer.panel('Configured integrations', [
+        `${plan.specWorkflow.label} ${plan.framework.version}`,
+        ...plan.agents.map((agent) => `${agent.label}${plan.defaultAgent?.id === agent.id ? ' (default)' : ''}`)
+    ]));
+    if (readiness.deferred.length > 0) {
+        renderer.write(renderer.panel('Deferred advisory checks', readiness.deferred));
+    }
+    if (dependencyPhase.deferred.length > 0) {
+        renderer.write(renderer.panel('Deferred project dependencies', dependencyPhase.deferred));
     }
-    context.stdout.write(`Created ${plan.projectName} at ${targetRoot}\n\n`);
     context.stdout.write('Next steps:\n');
     context.stdout.write(`  1. Optional - preserve history: copy the .git directory from ${sourceRoot} into ${targetRoot}, then commit the migration on top (git rename detection preserves file history).\n`);
-    context.stdout.write(`  2. Execute the migration plan: ${planLocation}\n`);
+    context.stdout.write(`  2. Execute the migration plan: ${migrationPlan.location}\n`);
     context.stdout.write('  3. Verify compliance: liftoff validate && liftoff doctor\n');
     context.stdout.write(`The source project was not modified. Rolling back is deleting ${targetRoot}.\n`);
     return 0;
 }
+async function migrateCommand(parsed, context) {
+    const sourceArg = parsed.positional[0];
+    if (!sourceArg) {
+        context.stderr.write('Usage: liftoff migrate <path-to-existing-project>\n');
+        return 1;
+    }
+    const sourceRoot = path.resolve(context.cwd, sourceArg);
+    let sourceDetails;
+    try {
+        sourceDetails = await stat(sourceRoot);
+    }
+    catch {
+        context.stderr.write(`Source project not found: ${sourceRoot}\n`);
+        return 1;
+    }
+    if (!sourceDetails.isDirectory()) {
+        context.stderr.write(`Source path is not a directory: ${sourceRoot}\n`);
+        return 1;
+    }
+    if (existsSync(path.join(sourceRoot, 'liftoff.manifest.json'))) {
+        context.stderr.write(`${sourceRoot} is already a Liftoff project. Use liftoff update instead.\n`);
+        return 1;
+    }
+    return withUnchangedMigrationSource(sourceRoot, () => executeMigration(parsed, context, sourceRoot));
+}
 function summarizeEntries(entries) {
     const summary = { new: 0, missing: 0, upgrade: 0, conflict: 0, moved: 0, orphan: 0, refresh: 0, unchanged: 0 };
     for (const entry of entries) {
@@ -340,6 +691,17 @@ async function updateCommand(parsed, context) {
         context.stderr.write(`Pattern changes (${manifest.project.pattern ?? 'none'} -> ${plan.pattern?.id ?? 'none'}) are a migration, not an update. Run liftoff migrate instead.\n`);
         return 1;
     }
+    if (plan.specWorkflow.id !== manifest.project.specWorkflow) {
+        context.stderr.write(`Spec workflow changes (${manifest.project.specWorkflow} -> ${plan.specWorkflow.id}) require official framework initialization and are not supported by liftoff update.\n`);
+        return 1;
+    }
+    const configuredAgents = plan.agents.map((agent) => agent.id);
+    if (manifest.framework.state === 'initialized' && (configuredAgents.length !== manifest.project.agents.length ||
+        configuredAgents.some((agent, index) => agent !== manifest.project.agents[index]) ||
+        plan.defaultAgent?.id !== manifest.project.defaultAgent)) {
+        context.stderr.write('AI agent or default-agent changes require official framework initialization and are not supported by liftoff update. Restore liftoff.config.json to the integrations recorded in liftoff.manifest.json.\n');
+        return 1;
+    }
     const render = buildArtifacts(plan);
     const entries = await reconcileProject(manifest, render, projectRoot);
     const summary = summarizeEntries(entries);
@@ -420,7 +782,16 @@ async function updateCommand(parsed, context) {
     }
     const oldByName = new Map(manifest.artifacts.map((artifact) => [artifact.logicalName, artifact]));
     const skippedByName = new Map(skipped.map((entry) => [entry.logicalName, entry]));
-    const nextManifest = buildManifest(plan, render.filter((artifact) => artifact.logicalName !== 'manifest'));
+    const nextManifest = buildManifest(plan, render.filter((artifact) => artifact.logicalName !== 'manifest'), { frameworkState: manifest.framework.state });
+    nextManifest.framework = manifest.framework;
+    nextManifest.project.specWorkflow = manifest.project.specWorkflow;
+    nextManifest.project.agents = manifest.project.agents;
+    if (manifest.project.defaultAgent) {
+        nextManifest.project.defaultAgent = manifest.project.defaultAgent;
+    }
+    else {
+        delete nextManifest.project.defaultAgent;
+    }
     nextManifest.artifacts = nextManifest.artifacts.flatMap((artifact) => {
         // config is user-owned after create: carry the recorded entry forward untouched
         if (artifact.logicalName === 'liftoff-config') {
@@ -467,13 +838,6 @@ async function updateCommand(parsed, context) {
     context.stdout.write(`Updated: ${written.length} written, ${skipped.length} skipped, ${summary.orphan} orphan(s). Manifest recorded at ${liftoffVersion}.\n`);
     return 0;
 }
-function binaryCheck(command, args, remedy, cwd) {
-    const result = spawnSync(command, args, { cwd, encoding: 'utf8' });
-    if (result.status === 0) {
-        return { label: command, severity: 'ok', detail: (result.stdout || result.stderr).split('\n')[0].trim() };
-    }
-    return { label: command, severity: 'fail', detail: 'not found', remedy };
-}
 function versionedBinaryCheck(label, command, args, minimum, remedy) {
     const result = spawnSync(command, args, { encoding: 'utf8' });
     if (result.status !== 0) {
@@ -503,25 +867,121 @@ function pythonRuntime() {
         ];
     return candidates.find((candidate) => versionedBinaryCheck('python', candidate.command, candidate.versionArgs, [3, 12], 'install Python 3.12 or newer').severity === 'ok') ?? candidates.find((candidate) => binaryPresent(candidate.command));
 }
-function environmentLayer(apiStack) {
-    const python = pythonRuntime();
-    const runtimeChecks = apiStack === 'go-huma'
-        ? [versionedBinaryCheck('go', 'go', ['version'], [1, 23], 'install Go 1.23 or newer')]
-        : apiStack === 'node-fastify'
-            ? []
-            : [python
-                    ? versionedBinaryCheck('python', python.command, python.versionArgs, [3, 12], 'install Python 3.12 or newer')
-                    : { label: 'python', severity: 'fail', detail: 'not found', remedy: 'install Python 3.12 or newer' }];
+function doctorCheckFromProbe(probe) {
+    const severity = probe.state === 'ready'
+        ? 'ok'
+        : probe.requirement.severity === 'blocking'
+            ? 'fail'
+            : 'warn';
     return {
-        title: 'Environment',
-        checks: [
-            versionedBinaryCheck('node', 'node', ['--version'], [20, 0], 'install Node.js 20 or newer'),
-            ...runtimeChecks,
-            binaryCheck('docker', ['--version'], 'install Docker'),
-            binaryCheck('tofu', ['--version'], 'install OpenTofu')
-        ]
+        id: probe.requirement.id,
+        label: probe.requirement.id,
+        severity,
+        state: probe.state,
+        requirementSeverity: probe.requirement.severity,
+        detail: probe.detail,
+        ...(probe.remedy ? { remedy: probe.remedy } : {})
+    };
+}
+function noticeId(requirementId, label) {
+    const suffix = label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    return `${requirementId}:${suffix}`;
+}
+function workstationLayer(probes) {
+    const checks = probes.flatMap((probe) => [
+        doctorCheckFromProbe(probe),
+        ...probe.notices.map((notice) => ({
+            id: noticeId(probe.requirement.id, notice.label),
+            label: notice.label,
+            severity: notice.state === 'ready' ? 'ok' : 'warn',
+            state: notice.state,
+            requirementSeverity: 'advisory',
+            detail: notice.detail,
+            ...(notice.remedy ? { remedy: notice.remedy } : {})
+        }))
+    ]);
+    return { title: 'Environment', checks };
+}
+function workstationSelectionFromManifest(manifest) {
+    const framework = getFrameworkDefinition(manifest.project.specWorkflow);
+    return {
+        apiStack: { id: manifest.project.apiStack },
+        specWorkflow: { id: manifest.project.specWorkflow },
+        framework: { version: framework.version },
+        provider: { id: manifest.project.cloud },
+        agents: manifest.framework.state === 'initialized'
+            ? manifest.project.agents.map((id) => {
+                const agent = getCodingAgent(id);
+                if (!agent) {
+                    throw new Error(`Manifest references unknown coding agent ${id}.`);
+                }
+                return { id: agent.id, label: agent.label };
+            })
+            : []
     };
 }
+async function frameworkDoctorChecks(projectRoot, manifest) {
+    if (manifest.framework.state === 'legacy') {
+        return [{
+                id: 'framework-legacy-state',
+                label: 'framework state',
+                severity: 'warn',
+                state: 'not-observable',
+                detail: `Legacy v${manifest.artifactVersion} manifest does not prove official ${manifest.framework.adapter} initialization or configured coding agents.`,
+                remedy: 'Reinitialize the framework explicitly before recording a v3 initialized framework contract.'
+            }];
+    }
+    const expected = getFrameworkDefinition(manifest.framework.adapter);
+    const frameworkLabel = getSpecWorkflow(manifest.framework.adapter)?.label ?? manifest.framework.adapter;
+    const contract = manifest.framework.contractVersion === expected.version
+        ? {
+            id: 'framework-contract',
+            label: 'framework contract',
+            severity: 'ok',
+            state: 'ready',
+            detail: `${frameworkLabel} ${expected.version}`
+        }
+        : {
+            id: 'framework-contract',
+            label: 'framework contract',
+            severity: 'fail',
+            state: 'outdated',
+            detail: `Manifest records ${manifest.framework.contractVersion}; this Liftoff version requires ${expected.version}.`,
+            remedy: `Install ${frameworkLabel} ${expected.version} and reinitialize its integrations.`
+        };
+    const markerIssues = await validateFrameworkInstallation(projectRoot, {
+        workflow: manifest.framework.adapter,
+        agents: manifest.project.agents,
+        ...(manifest.project.defaultAgent ? { defaultAgent: manifest.project.defaultAgent } : {})
+    });
+    const markers = markerIssues.length === 0
+        ? {
+            id: 'framework-markers',
+            label: 'framework markers',
+            severity: 'ok',
+            state: 'ready',
+            detail: `${manifest.project.agents.length} selected integration${manifest.project.agents.length === 1 ? '' : 's'} verified`
+        }
+        : {
+            id: 'framework-markers',
+            label: 'framework markers',
+            severity: 'fail',
+            state: 'unhealthy',
+            detail: `${markerIssues.length} issue(s): ${markerIssues[0]}`,
+            remedy: `Run the official ${frameworkLabel} initializer for the selected integrations.`
+        };
+    return [
+        contract,
+        {
+            id: 'selected-agents',
+            label: 'selected agents',
+            severity: 'ok',
+            state: 'ready',
+            detail: manifest.project.agents.join(', ')
+        },
+        markers
+    ];
+}
 function stackProjectCheck(projectRoot, apiStack) {
     let result;
     switch (apiStack) {
@@ -564,13 +1024,13 @@ function binaryPresent(command) {
 }
 function azureCloudChecks() {
     if (!binaryPresent('az')) {
-        return [{ label: 'az', severity: 'fail', detail: 'Azure CLI not found', remedy: 'install the Azure CLI' }];
+        return [{ label: 'az', severity: 'warn', detail: 'Azure CLI not found', remedy: 'install the Azure CLI' }];
     }
     const auth = spawnSync('az', ['account', 'show', '-o', 'none', '--only-show-errors'], { encoding: 'utf8' });
     if (auth.status === 0) {
         return [{ label: 'azure auth', severity: 'ok', detail: 'authenticated' }];
     }
-    return [{ label: 'azure auth', severity: 'fail', detail: 'not authenticated', remedy: 'run az login' }];
+    return [{ label: 'azure auth', severity: 'warn', detail: 'not authenticated', remedy: 'run az login' }];
 }
 // ponytail: provider-keyed map so aws/gcp checks slot in when their adapters land
 const CLOUD_CHECKS = {
@@ -584,11 +1044,10 @@ function cloudLayer(cloud) {
 }
 async function lookupLatestPublishedVersion() {
     const registry = process.env.LIFTOFF_REGISTRY ?? 'https://registry.npmjs.org';
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2000);
     try {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 2000);
         const response = await fetch(`${registry}/@msn-control%2fliftoff/latest`, { signal: controller.signal });
-        clearTimeout(timer);
         if (!response.ok) {
             return undefined;
         }
@@ -598,6 +1057,34 @@ async function lookupLatestPublishedVersion() {
     catch {
         return undefined; // offline or unreachable: doctor stays quiet about freshness
     }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function cliLayer() {
+    const checks = [
+        { label: 'version', severity: 'ok', detail: `Liftoff ${liftoffVersion}` }
+    ];
+    const latest = await lookupLatestPublishedVersion();
+    if (!latest) {
+        return { title: 'CLI', checks };
+    }
+    if (compareSemver(latest, liftoffVersion) > 0) {
+        checks.push({
+            label: 'cli freshness',
+            severity: 'warn',
+            detail: `Liftoff ${latest} is published, this CLI is ${liftoffVersion}`,
+            remedy: `install Liftoff ${latest} from an approved registry that exposes it; where direct public npm access is permitted: npm install -g @msn-control/liftoff@${latest} --registry=https://registry.npmjs.org`
+        });
+    }
+    else {
+        checks.push({
+            label: 'cli freshness',
+            severity: 'ok',
+            detail: `running ${liftoffVersion}, latest stable ${latest}`
+        });
+    }
+    return { title: 'CLI', checks };
 }
 async function projectLayer(projectRoot, manifest) {
     const checks = [];
@@ -624,16 +1111,8 @@ async function projectLayer(projectRoot, manifest) {
     else {
         checks.push({ label: 'version', severity: 'ok', detail: `generated by ${manifest.liftoffVersion}, CLI ${liftoffVersion}` });
     }
+    checks.push(...await frameworkDoctorChecks(projectRoot, manifest));
     checks.push(stackProjectCheck(projectRoot, manifest.project.apiStack));
-    const latest = await lookupLatestPublishedVersion();
-    if (latest && compareSemver(latest, liftoffVersion) > 0) {
-        checks.push({
-            label: 'cli freshness',
-            severity: 'warn',
-            detail: `Liftoff ${latest} is published, this CLI is ${liftoffVersion}`,
-            remedy: 'npm install -g @msn-control/liftoff@latest'
-        });
-    }
     try {
         const config = await loadConfigOptions('liftoff.config.json', projectRoot);
         const plan = buildProjectPlan(config, { requireProjectName: true });
@@ -730,9 +1209,15 @@ async function doctorCommand(parsed, context) {
             manifestError = error;
         }
     }
-    const environment = environmentLayer(manifest?.project.apiStack);
+    layers.push(await cliLayer());
+    const runner = context.runner ?? new NodeCommandRunner();
+    const requirements = manifest
+        ? selectWorkstationRequirements(workstationSelectionFromManifest(manifest), { includeFramework: manifest.framework.state === 'initialized' })
+        : selectLiftoffRuntimeRequirements();
+    const probes = await probeWorkstation(requirements, runner);
+    const environment = workstationLayer(probes);
     layers.push(environment);
-    const dockerAvailable = environment.checks.some((check) => check.label === 'docker' && check.severity === 'ok');
+    const dockerAvailable = probes.some((probe) => probe.requirement.id === 'docker' && probe.state === 'ready');
     if (projectRoot) {
         if (manifestError) {
             layers.push({
@@ -817,32 +1302,35 @@ async function optionsFromParsedArgs(parsed, cwd, includeProjectName) {
         includeFrontend: readBooleanFlag(parsed.flags, 'frontend'),
         environments: readListFlag(parsed.flags, 'environments'),
         specWorkflow: readStringFlag(parsed.flags, 'spec'),
+        agents: readListFlag(parsed.flags, 'agents'),
+        defaultAgent: readStringFlag(parsed.flags, 'default-agent'),
         configPath,
-        yes: readBooleanFlag(parsed.flags, 'yes') ?? false
+        yes: readBooleanFlag(parsed.flags, 'yes') ?? false,
+        force: readBooleanFlag(parsed.flags, 'force'),
+        installTools: readBooleanFlag(parsed.flags, 'install-tools'),
+        installDependencies: readBooleanFlag(parsed.flags, 'install-dependencies')
     };
     return mergeOptions(configOptions, flagOptions);
 }
-function hasMissingCreateInputs(options) {
+function hasMissingInitInputs(options) {
     const projectType = options.projectType ?? (options.pattern ? 'genai' : options.apiStack ? 'standard' : undefined);
     const missingTypeSpecific = projectType === 'genai' ? !options.pattern : projectType === 'standard' ? !options.apiStack : true;
-    return !options.projectName || missingTypeSpecific || !options.cloud || options.includeFrontend === undefined || !options.specWorkflow || !options.environments;
+    const missingDefaultAgent = options.specWorkflow === 'spec-kit' &&
+        (options.agents?.length ?? 0) > 1 &&
+        !options.defaultAgent;
+    return !options.projectName ||
+        missingTypeSpecific ||
+        !options.cloud ||
+        options.includeFrontend === undefined ||
+        !options.specWorkflow ||
+        !options.agents ||
+        missingDefaultAgent ||
+        !options.environments;
 }
 function printHelp(stream) {
-    stream.write(`Mission Control Liftoff\n\n`);
-    stream.write(`Commands:\n`);
-    stream.write(`  create      Generate a new project\n`);
-    stream.write(`  plan        Preview generated artifacts\n`);
-    stream.write(`  patterns    List GenAI patterns\n`);
-    stream.write(`  providers   List cloud providers\n`);
-    stream.write(`  regions     List or search provider regions\n`);
-    stream.write(`  validate    Validate a generated project manifest\n`);
-    stream.write(`  update      Reconcile a project with the current templates (check by default; --apply, --force)\n`);
-    stream.write(`  migrate     Adopt an existing project: fresh scaffold + staged copy + migration plan\n`);
-    stream.write(`  doctor      Check local readiness\n`);
-    stream.write(`  dev         Print Docker Compose helper commands\n`);
-    stream.write(`  infra       Print OpenTofu helper commands\n`);
-    stream.write(`\nProject types: GenAI (Python/FastAPI/PydanticAI) or standard API\n`);
-    stream.write(`Standard API stacks: ${apiStacks.map((stack) => stack.label).join(', ')}\n`);
+    const renderer = new TerminalRenderer({ stream });
+    renderer.write(renderer.banner('Project workstation and scaffold initializer'));
+    stream.write(formatGeneralHelp(liftoffVersion));
 }
 export async function createFixtureProject(options) {
     const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'liftoff-'));
@@ -852,6 +1340,27 @@ export async function createFixtureProject(options) {
     await assertNewOrEmptyDirectory(target);
     await rm(target, { recursive: true, force: true });
     await writeArtifacts(target, buildArtifacts(plan));
+    for (const marker of [
+        ...plan.framework.baseMarkers,
+        ...plan.agents.flatMap((agent) => plan.framework.agentMarkers[agent.id])
+    ]) {
+        let content = 'fixture marker\n';
+        if (marker.join('/') === '.specify/integration.json') {
+            const installed = plan.agents.map((agent) => agent.integrationIds['spec-kit']);
+            const defaultIntegration = plan.defaultAgent?.integrationIds['spec-kit'];
+            content = `${JSON.stringify({
+                integration_state_schema: 1,
+                integration: defaultIntegration,
+                default_integration: defaultIntegration,
+                installed_integrations: installed,
+                integration_settings: {}
+            }, null, 2)}\n`;
+        }
+        else if (marker.join('/') === '.specify/init-options.json') {
+            content = '{}\n';
+        }
+        await writeProjectFile(target, marker, content);
+    }
     return target;
 }
 //# sourceMappingURL=commands.js.map