@msn-control/liftoff 0.1.2 → 0.2.0

package/README.md

@@ -19,6 +19,18 @@ liftoff help
 liftoff create
 ```
 
+## Contract conventions
+
+Generated projects contain persistent files that outlive any CLI release. The following rules are the compatibility contract, enforced by `tests/contract.test.ts` where possible:
+
+- **Manifest schema**: `liftoff.manifest.json` uses `artifactVersion` 2 — the first supported schema version — recording the generating CLI version (`liftoffVersion`) and a `sha256:`-prefixed `contentHash` per artifact. Readers accept every supported version and reject others with a remedy; writers always write the latest version.
+- **Append-only identifiers**: artifact `logicalName`s and catalog ids (patterns, providers, environments, spec workflows) are never renamed or removed, only added. The contract test snapshots the logical-name sets.
+- **Deterministic rendering**: artifact content depends only on the project plan and the template code — no timestamps, randomness, or environment leakage. Verified by a double-render byte-equality test.
+- **Reserved namespaces**: `.liftoff/` in generated projects is reserved for future CLI-managed state; no new CLI-managed root-level files beyond `liftoff.config.json` and `liftoff.manifest.json`. `liftoff.config.json` is written once at generation and never machine-written afterwards.
+- **Portable paths**: machine-readable files store OS-neutral path-part arrays, never joined path strings.
+- **Exit codes**: 0 = success or clean check, 1 = failure, 2 = a check mode found drift.
+- **Machine output**: every `--json` output carries a top-level numeric `schemaVersion`.
+
 ## Development
 
 Repository-local commands are for contributors working from a Mission Control checkout. Run package commands from the repository root:

package/dist/commands.d.ts

@@ -5,4 +5,16 @@ export interface CommandContext {
     stderr: NodeJS.WritableStream;
 }
 export declare function runCommand(parsed: ParsedArgs, context: CommandContext): Promise<number>;
+interface DoctorCheck {
+    label: string;
+    severity: 'ok' | 'warn' | 'fail' | 'skipped';
+    detail: string;
+    remedy?: string;
+}
+interface DoctorLayer {
+    title: string;
+    checks: DoctorCheck[];
+}
+export declare function doctorExitCode(layers: DoctorLayer[]): number;
 export declare function createFixtureProject(options: ProjectOptions): Promise<string>;
+export {};

package/dist/commands.js

@@ -1,13 +1,19 @@
 import { spawnSync } from 'node:child_process';
-import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { cp, mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { readBooleanFlag, readListFlag, readStringFlag } from './args.js';
 import { approvedStack, listRegions, patterns, providers, searchRegions } from './catalogs.js';
-import { artifactPath, assertNewOrEmptyDirectory, resolveTargetRoot, validateGeneratedProject, writeArtifacts } from './file-system.js';
+import { artifactPath, assertNewOrEmptyDirectory, deleteProjectFile, findProjectRoot, loadManifest, manifestDisplayPath, resolveTargetRoot, validateGeneratedProject, writeArtifacts, writeProjectFile } from './file-system.js';
 import { confirmPlan, promptForCreateOptions } from './interactive.js';
+import { renderMigrationChecklist, renderMigrationProposal, renderMigrationTasks, seedMigrationGroups } from './migrate-plan.js';
 import { buildProjectPlan, formatProjectPlan, loadConfigOptions, mergeOptions, PlanValidationError } from './planner.js';
-import { buildArtifacts } from './templates.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 { liftoffVersion } from './version.js';
 export async function runCommand(parsed, context) {
     try {
         switch (parsed.command) {
@@ -28,8 +34,12 @@ export async function runCommand(parsed, context) {
                 return regionsCommand(parsed, context);
             case 'validate':
                 return await validateCommand(parsed, context);
+            case 'update':
+                return await updateCommand(parsed, context);
+            case 'migrate':
+                return await migrateCommand(parsed, context);
             case 'doctor':
-                return doctorCommand(parsed, context);
+                return await doctorCommand(parsed, context);
             case 'dev':
                 return helperCommand(parsed, context, 'docker compose');
             case 'infra':
@@ -108,8 +118,10 @@ function regionsCommand(parsed, context) {
     return 0;
 }
 async function validateCommand(parsed, context) {
-    const project = parsed.positional[0] ?? readStringFlag(parsed.flags, 'project') ?? '.';
-    const projectRoot = path.resolve(context.cwd, project);
+    const explicit = parsed.positional[0] ?? readStringFlag(parsed.flags, 'project');
+    const projectRoot = explicit
+        ? path.resolve(context.cwd, explicit)
+        : (await findProjectRoot(context.cwd)) ?? context.cwd;
     const issues = await validateGeneratedProject(projectRoot);
     if (issues.length > 0) {
         context.stderr.write(`${issues.join('\n')}\n`);
@@ -118,35 +130,504 @@ async function validateCommand(parsed, context) {
     context.stdout.write('Generated project manifest is valid.\n');
     return 0;
 }
-function doctorCommand(parsed, context) {
-    const checks = [
-        ['node', ['--version']],
-        ['python3', ['--version']],
-        ['docker', ['--version']],
-        ['tofu', ['--version']]
-    ];
-    let failed = false;
-    for (const [command, args] of checks) {
-        const result = spawnSync(command, args, { encoding: 'utf8' });
-        if (result.status === 0) {
-            context.stdout.write(`[ok] ${command}: ${(result.stdout || result.stderr).split('\n')[0]}\n`);
+const STAGING_EXCLUDES = new Set(['.git', 'node_modules', '.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;
+    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;
+    }
+    const inventory = await scanLegacyProject(sourceRoot);
+    const { options: defaults, provenance } = scanDefaults(inventory);
+    context.stdout.write('Scan defaults (override in prompts or with flags):\n');
+    for (const item of provenance) {
+        context.stdout.write(`  - ${item.field}: ${item.value}  (detected: ${item.evidence})\n`);
+    }
+    context.stdout.write('\n');
+    const flagOptions = await optionsFromParsedArgs(parsed, context.cwd, false);
+    const initial = mergeOptions(defaults, flagOptions);
+    const needsPrompts = !initial.yes && hasMissingCreateInputs(initial);
+    const options = needsPrompts ? await promptForCreateOptions(initial) : initial;
+    const plan = buildProjectPlan(options, { requireProjectName: true });
+    const confirmed = await confirmPlan(plan, options.yes);
+    if (!confirmed) {
+        context.stdout.write('Migration cancelled.\n');
+        return 0;
+    }
+    const parentDir = path.dirname(sourceRoot);
+    let targetRoot = path.resolve(parentDir, plan.safeProjectName);
+    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`);
+        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 groups = seedMigrationGroups(inventory);
+    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)';
+    }
+    else {
+        await writeFile(path.join(targetRoot, 'MIGRATION.md'), renderMigrationChecklist(plan, inventory, groups), 'utf8');
+        planLocation = 'MIGRATION.md';
+    }
+    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('  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;
+}
+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) {
+        if (entry.status === 'unchanged') {
+            if (entry.refreshHash) {
+                summary.refresh += 1;
+            }
+            else {
+                summary.unchanged += 1;
+            }
+            continue;
+        }
+        if (entry.status === 'moved' && !entry.cleanMove) {
+            summary.conflict += 1;
+            continue;
+        }
+        summary[entry.status] += 1;
+    }
+    return summary;
+}
+function entryMarker(entry) {
+    switch (entry.status) {
+        case 'new':
+        case 'missing':
+            return '+';
+        case 'upgrade':
+            return '~';
+        case 'conflict':
+            return '!';
+        case 'moved':
+            return entry.cleanMove ? '>' : '!';
+        case 'orphan':
+            return '-';
+        default:
+            return '~';
+    }
+}
+function entryDisplay(entry) {
+    if (entry.status === 'moved' && entry.previousPathParts) {
+        return `${manifestDisplayPath(entry.previousPathParts)} => ${manifestDisplayPath(entry.pathParts)}`;
+    }
+    return manifestDisplayPath(entry.pathParts);
+}
+function isDirtyGitWorktree(projectRoot) {
+    if (!existsSync(path.join(projectRoot, '.git'))) {
+        return false;
+    }
+    const result = spawnSync('git', ['status', '--porcelain'], { cwd: projectRoot, encoding: 'utf8' });
+    return result.status === 0 && result.stdout.trim().length > 0;
+}
+async function updateCommand(parsed, context) {
+    const apply = readBooleanFlag(parsed.flags, 'apply') ?? false;
+    const force = readBooleanFlag(parsed.flags, 'force') ?? false;
+    const jsonMode = readBooleanFlag(parsed.flags, 'json') ?? false;
+    if (force && !apply) {
+        context.stderr.write('--force requires --apply.\n');
+        return 1;
+    }
+    const explicit = parsed.positional[0] ?? readStringFlag(parsed.flags, 'project');
+    const projectRoot = explicit ? path.resolve(context.cwd, explicit) : await findProjectRoot(context.cwd);
+    if (!projectRoot) {
+        context.stderr.write(`No liftoff.manifest.json found in ${context.cwd} or any parent directory.\n`);
+        return 1;
+    }
+    const manifest = await loadManifest(projectRoot);
+    if (compareSemver(manifest.liftoffVersion, liftoffVersion) > 0) {
+        context.stderr.write(`This project was written by Liftoff ${manifest.liftoffVersion}, which is newer than this CLI (${liftoffVersion}). Upgrade the CLI first.\n`);
+        return 1;
+    }
+    const config = await loadConfigOptions('liftoff.config.json', projectRoot);
+    if (config.pattern && config.pattern !== manifest.project.pattern) {
+        context.stderr.write(`Pattern changes (${manifest.project.pattern} -> ${config.pattern}) are a migration, not an update. Run liftoff migrate instead.\n`);
+        return 1;
+    }
+    const plan = buildProjectPlan(config, { requireProjectName: true });
+    const render = buildArtifacts(plan);
+    const entries = await reconcileProject(manifest, render, projectRoot);
+    const summary = summarizeEntries(entries);
+    const drift = hasDrift(entries);
+    const visible = entries.filter((entry) => entry.status !== 'unchanged' || entry.refreshHash);
+    if (!apply) {
+        if (jsonMode) {
+            context.stdout.write(`${JSON.stringify({
+                schemaVersion: 1,
+                mode: 'check',
+                cliVersion: liftoffVersion,
+                projectVersion: manifest.liftoffVersion,
+                entries: visible.map((entry) => ({
+                    logicalName: entry.logicalName,
+                    status: entry.status,
+                    path: manifestDisplayPath(entry.pathParts),
+                    previousPath: entry.previousPathParts ? manifestDisplayPath(entry.previousPathParts) : undefined,
+                    reason: entry.reason
+                })),
+                summary
+            }, null, 2)}\n`);
+            return drift ? 2 : 0;
+        }
+        context.stdout.write(`Liftoff ${liftoffVersion} - project generated by ${manifest.liftoffVersion}\n\n`);
+        if (!drift) {
+            context.stdout.write(`No drift: ${summary.unchanged} artifacts match the current templates and configuration.\n`);
+            return 0;
+        }
+        for (const entry of visible) {
+            context.stdout.write(`  ${entryMarker(entry)} ${entryDisplay(entry)}  ${entry.reason}\n`);
+        }
+        const toWrite = summary.new + summary.missing + summary.upgrade + summary.moved + summary.refresh;
+        context.stdout.write(`\n  ${toWrite} to write, ${summary.conflict} conflict(s), ${summary.orphan} orphan(s), ${summary.unchanged} unchanged\n`);
+        context.stdout.write('  Run `liftoff update --apply` to apply the safe changes.\n');
+        return 2;
+    }
+    if (isDirtyGitWorktree(projectRoot)) {
+        context.stdout.write('Hint: the project worktree has uncommitted changes - consider committing before applying.\n');
+    }
+    const written = [];
+    const skipped = [];
+    for (const entry of entries) {
+        switch (entry.status) {
+            case 'new':
+            case 'missing':
+            case 'upgrade':
+                await writeProjectFile(projectRoot, entry.pathParts, entry.rendered.content);
+                written.push(entry);
+                break;
+            case 'moved':
+                if (entry.cleanMove || force) {
+                    await writeProjectFile(projectRoot, entry.pathParts, entry.rendered.content);
+                    await deleteProjectFile(projectRoot, entry.previousPathParts);
+                    written.push(entry);
+                }
+                else {
+                    skipped.push(entry);
+                }
+                break;
+            case 'conflict':
+                if (force) {
+                    await writeProjectFile(projectRoot, entry.pathParts, entry.rendered.content);
+                    written.push(entry);
+                }
+                else {
+                    skipped.push(entry);
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    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'));
+    nextManifest.artifacts = nextManifest.artifacts.map((artifact) => {
+        // config is user-owned after create: carry the recorded entry forward untouched
+        if (artifact.logicalName === 'liftoff-config') {
+            return oldByName.get('liftoff-config') ?? artifact;
+        }
+        if (!skippedByName.has(artifact.logicalName)) {
+            return artifact;
+        }
+        const previous = oldByName.get(artifact.logicalName);
+        return { ...artifact, pathParts: previous.pathParts, contentHash: previous.contentHash };
+    });
+    for (const entry of entries) {
+        if (entry.status === 'orphan') {
+            nextManifest.artifacts.push(oldByName.get(entry.logicalName));
+        }
+    }
+    await writeProjectFile(projectRoot, ['liftoff.manifest.json'], `${JSON.stringify(nextManifest, null, 2)}\n`);
+    if (jsonMode) {
+        context.stdout.write(`${JSON.stringify({
+            schemaVersion: 1,
+            mode: 'apply',
+            cliVersion: liftoffVersion,
+            projectVersion: manifest.liftoffVersion,
+            written: written.map((entry) => manifestDisplayPath(entry.pathParts)),
+            skipped: skipped.map((entry) => ({ path: manifestDisplayPath(entry.pathParts), reason: entry.reason })),
+            summary
+        }, null, 2)}\n`);
+        return 0;
+    }
+    for (const entry of written) {
+        context.stdout.write(`  wrote ${entryDisplay(entry)}\n`);
+    }
+    for (const entry of skipped) {
+        context.stdout.write(`  skipped ${entryDisplay(entry)}  ${entry.reason}${force ? '' : ' (use --apply --force to overwrite)'}\n`);
+    }
+    for (const entry of entries) {
+        if (entry.status === 'orphan') {
+            context.stdout.write(`  orphan ${entryDisplay(entry)}  ${entry.reason}\n`);
+        }
+    }
+    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) {
+    const result = spawnSync(command, args, { 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 environmentLayer() {
+    return {
+        title: 'Environment',
+        checks: [
+            binaryCheck('node', ['--version'], 'install Node.js 20 or newer'),
+            binaryCheck('python3', ['--version'], 'install Python 3'),
+            binaryCheck('docker', ['--version'], 'install Docker'),
+            binaryCheck('tofu', ['--version'], 'install OpenTofu')
+        ]
+    };
+}
+function binaryPresent(command) {
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    return spawnSync(probe, [command], { encoding: 'utf8' }).status === 0;
+}
+function azureCloudChecks() {
+    if (!binaryPresent('az')) {
+        return [{ label: 'az', severity: 'fail', 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' }];
+}
+// ponytail: provider-keyed map so aws/gcp checks slot in when their adapters land
+const CLOUD_CHECKS = {
+    azure: azureCloudChecks
+};
+function cloudLayer(cloud) {
+    const checks = CLOUD_CHECKS[cloud]
+        ? CLOUD_CHECKS[cloud]()
+        : [{ label: cloud, severity: 'skipped', detail: `${cloud} provider checks are not available yet` }];
+    return { title: `Cloud - ${cloud}`, checks };
+}
+async function lookupLatestPublishedVersion() {
+    const registry = process.env.LIFTOFF_REGISTRY ?? 'https://registry.npmjs.org';
+    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;
+        }
+        const data = (await response.json());
+        return data.version;
+    }
+    catch {
+        return undefined; // offline or unreachable: doctor stays quiet about freshness
+    }
+}
+async function projectLayer(projectRoot, manifest) {
+    const checks = [];
+    const issues = await validateGeneratedProject(projectRoot);
+    if (issues.length > 0) {
+        checks.push({
+            label: 'manifest',
+            severity: 'fail',
+            detail: `${issues.length} issue(s): ${issues[0]}${issues.length > 1 ? ' ...' : ''}`,
+            remedy: 'restore missing artifacts or run liftoff update --apply'
+        });
+    }
+    else {
+        checks.push({ label: 'manifest', severity: 'ok', detail: `valid, ${manifest.artifacts.length} artifacts present` });
+    }
+    if (compareSemver(manifest.liftoffVersion, liftoffVersion) > 0) {
+        checks.push({
+            label: 'version',
+            severity: 'warn',
+            detail: `project written by Liftoff ${manifest.liftoffVersion}, CLI is ${liftoffVersion}`,
+            remedy: 'upgrade the CLI: npm install -g @msn-control/liftoff@latest'
+        });
+    }
+    else {
+        checks.push({ label: 'version', severity: 'ok', detail: `generated by ${manifest.liftoffVersion}, CLI ${liftoffVersion}` });
+    }
+    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 });
+        const render = buildArtifacts(plan);
+        const entries = await reconcileProject(manifest, render, projectRoot);
+        const driftCount = entries.filter((entry) => entry.status !== 'unchanged' || entry.refreshHash).length;
+        if (driftCount > 0) {
+            checks.push({
+                label: 'scaffold drift',
+                severity: 'warn',
+                detail: `${driftCount} update(s) available`,
+                remedy: 'run liftoff update'
+            });
+        }
+        else {
+            checks.push({ label: 'scaffold drift', severity: 'ok', detail: 'project matches the current templates' });
+        }
+    }
+    catch (error) {
+        checks.push({
+            label: 'scaffold drift',
+            severity: 'fail',
+            detail: `liftoff.config.json could not be evaluated: ${error.message.split('\n')[0]}`,
+            remedy: 'repair liftoff.config.json'
+        });
+    }
+    return { title: 'Project', checks };
+}
+async function runtimeLayer(projectRoot, dockerAvailable) {
+    const checks = [];
+    if (existsSync(path.join(projectRoot, '.env.example'))) {
+        if (existsSync(path.join(projectRoot, '.env'))) {
+            checks.push({ label: '.env', severity: 'ok', detail: 'present' });
         }
         else {
-            failed = true;
-            context.stdout.write(`[missing] ${command}\n`);
+            checks.push({ label: '.env', severity: 'fail', detail: 'missing', remedy: 'copy .env.example to .env' });
         }
     }
-    if (readStringFlag(parsed.flags, 'cloud') === 'azure') {
-        const result = spawnSync('az', ['account', 'show'], { encoding: 'utf8' });
+    else {
+        checks.push({ label: '.env', severity: 'skipped', detail: 'no .env.example in this project' });
+    }
+    if (!existsSync(path.join(projectRoot, 'docker-compose.yml'))) {
+        checks.push({ label: 'compose', severity: 'skipped', detail: 'no docker-compose.yml in this project' });
+    }
+    else if (!dockerAvailable) {
+        checks.push({ label: 'compose', severity: 'skipped', detail: 'docker is not installed, compose config not checked' });
+    }
+    else {
+        const result = spawnSync('docker', ['compose', 'config', '-q'], { cwd: projectRoot, encoding: 'utf8' });
         if (result.status === 0) {
-            context.stdout.write('[ok] azure: authenticated\n');
+            checks.push({ label: 'compose', severity: 'ok', detail: 'docker compose config is valid' });
         }
         else {
-            failed = true;
-            context.stdout.write('[missing] azure: run az login\n');
+            checks.push({
+                label: 'compose',
+                severity: 'fail',
+                detail: (result.stderr || 'docker compose config failed').split('\n')[0],
+                remedy: 'fix docker-compose.yml'
+            });
+        }
+    }
+    return { title: 'Runtime', checks };
+}
+const severityMarker = {
+    ok: '[ok]',
+    warn: '[warn]',
+    fail: '[fail]',
+    skipped: '[skip]'
+};
+function renderDoctorLayers(layers, stream) {
+    for (const layer of layers) {
+        stream.write(`${layer.title}\n`);
+        for (const check of layer.checks) {
+            const remedy = check.remedy ? ` - ${check.remedy}` : '';
+            stream.write(`  ${severityMarker[check.severity].padEnd(6)} ${check.label}: ${check.detail}${remedy}\n`);
+        }
+    }
+}
+export function doctorExitCode(layers) {
+    return layers.some((layer) => layer.checks.some((check) => check.severity === 'fail')) ? 1 : 0;
+}
+async function doctorCommand(parsed, context) {
+    const jsonMode = readBooleanFlag(parsed.flags, 'json') ?? false;
+    const cloudOverride = readStringFlag(parsed.flags, 'cloud');
+    const layers = [];
+    const environment = environmentLayer();
+    layers.push(environment);
+    const dockerAvailable = environment.checks.some((check) => check.label === 'docker' && check.severity === 'ok');
+    const projectRoot = await findProjectRoot(context.cwd);
+    if (projectRoot) {
+        let manifest;
+        try {
+            manifest = await loadManifest(projectRoot);
+        }
+        catch (error) {
+            layers.push({
+                title: 'Project',
+                checks: [{ label: 'manifest', severity: 'fail', detail: error.message, remedy: 'regenerate the project or use a matching CLI version' }]
+            });
+        }
+        if (manifest) {
+            layers.push(await projectLayer(projectRoot, manifest));
+            layers.push(await runtimeLayer(projectRoot, dockerAvailable));
+            const cloud = cloudOverride ?? manifest.project.cloud;
+            const cloudChecks = cloudLayer(cloud);
+            const pattern = patterns.find((candidate) => candidate.id === manifest.project.pattern);
+            if (pattern?.worker && cloud === 'azure') {
+                cloudChecks.checks.push(binaryPresent('func')
+                    ? { label: 'functions tooling', severity: 'ok', detail: 'Azure Functions Core Tools installed' }
+                    : { label: 'functions tooling', severity: 'warn', detail: 'Azure Functions Core Tools not found', remedy: 'npm install -g azure-functions-core-tools@4' });
+            }
+            layers.push(cloudChecks);
         }
     }
-    return failed ? 1 : 0;
+    else if (cloudOverride) {
+        layers.push(cloudLayer(cloudOverride));
+    }
+    const failures = layers.reduce((count, layer) => count + layer.checks.filter((check) => check.severity === 'fail').length, 0);
+    const warnings = layers.reduce((count, layer) => count + layer.checks.filter((check) => check.severity === 'warn').length, 0);
+    if (jsonMode) {
+        context.stdout.write(`${JSON.stringify({ schemaVersion: 1, layers, summary: { failures, warnings } }, null, 2)}\n`);
+    }
+    else {
+        renderDoctorLayers(layers, context.stdout);
+        context.stdout.write(`${failures} failure(s), ${warnings} warning(s)\n`);
+    }
+    return doctorExitCode(layers);
 }
 function helperCommand(parsed, context, tool) {
     const command = parsed.command === 'dev' ? buildDevCommand(parsed) : buildInfraCommand(parsed);
@@ -210,6 +691,8 @@ function printHelp(stream) {
     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`);