@illumiarq/lumis 1.2.10 → 1.3.0

package/dist/cli.js

@@ -1,192 +1,568 @@
+#!/usr/bin/env node
 /**
- * Host CLI entrypoint and command dispatcher.
+ * @illumiarq/lumis — extended CLI entry point.
  *
- * Commands are declared in a registry and resolved by longest prefix match,
- * enabling subcommands with free-form trailing arguments (e.g. `intent <text>`).
+ * Intercepts LumiARQ-specific commands (serve / build / preview) and
+ * delegates everything else to the base @lumiarq/lumis runCli().
  */
-import { executeIntentCommand } from './commands/intent.command.js';
-import { executeIrRebuildCommand } from './commands/ir-rebuild.command.js';
-import { executeIrShowCommand } from './commands/ir-show.command.js';
-import { executeMakeCommand } from './commands/make.command.js';
-import { executeCommandsListCommand, executeCommandsRunCommand } from './commands/commands.command.js';
-import { executeDoctorCommand } from './commands/doctor.command.js';
-import { executeInitCommand } from './commands/init.command.js';
-import { executeUseCommand } from './commands/use.command.js';
-import { ansi } from './output/ansi.js';
-import { executePackDetectCommand, executePackListCommand } from './commands/pack.command.js';
-import { executeRuntimeRunCommand, executeRuntimeTranscriptsListCommand, executeRuntimeTranscriptsPruneCommand, executeRuntimeTranscriptsShowCommand, } from './commands/runtime.command.js';
-import { createCommandContext } from './commands/runtime.js';
-import { executeTinkerCommand } from './commands/tinker.command.js';
-import { executeTinkerEvalCommand } from './commands/tinker-eval.command.js';
-import { runInteractiveLauncher } from './launcher.js';
-import { pathToFileURL } from 'node:url';
-const COMMANDS = [
-    { path: ['use'], description: 'Set preferred AI runtime', handler: executeUseCommand },
-    { path: ['pack', 'list'], description: 'List built-in packs', handler: executePackListCommand },
-    { path: ['pack', 'detect'], description: 'Detect best pack for project', handler: executePackDetectCommand },
-    { path: ['commands', 'list'], description: 'List pack and project commands', handler: executeCommandsListCommand },
-    { path: ['commands', 'run'], description: 'Run a pack or project command', handler: executeCommandsRunCommand },
-    { path: ['doctor'], description: 'Run Lumis diagnostics for this project', handler: executeDoctorCommand },
-    { path: ['init'], description: 'Initialize Lumis in this project', handler: executeInitCommand },
-    { path: ['make'], description: 'Create artifacts from intent', handler: executeMakeCommand },
-    { path: ['intent'], description: 'Parse and inspect intent', handler: executeIntentCommand },
-    { path: ['ir', 'show'], description: 'Show current IR', handler: executeIrShowCommand },
-    { path: ['ir', 'rebuild'], description: 'Rebuild project IR', handler: executeIrRebuildCommand },
-    { path: ['runtime', 'run'], description: 'Run runtime profile tasks', handler: executeRuntimeRunCommand },
-    { path: ['runtime', 'transcripts', 'list'], description: 'List runtime transcripts', handler: executeRuntimeTranscriptsListCommand },
-    { path: ['runtime', 'transcripts', 'show'], description: 'Show runtime transcript details', handler: executeRuntimeTranscriptsShowCommand },
-    { path: ['runtime', 'transcripts', 'prune'], description: 'Prune runtime transcripts', handler: executeRuntimeTranscriptsPruneCommand },
-    { path: ['tinker', 'eval'], description: 'Run Tinker evaluation harness', handler: executeTinkerEvalCommand },
-    { path: ['tinker'], description: 'Run interactive tinker mode', handler: executeTinkerCommand },
-];
-function createTraceListener() {
-    if (process.env.LUMIS_TRACE !== '1') {
-        return undefined;
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ui, writeError, writeLine } from './console.js';
+import { readStorageRoot } from './paths.js';
+import { serveApp } from './commands/serve.js';
+import { buildApp } from './commands/build.js';
+import { buildVercelFunction } from './commands/build-vercel-fn.js';
+import { previewApp } from './commands/preview.js';
+import { showInfo } from './commands/info.js';
+import { listModules } from './commands/module-list.js';
+import { generateKeys, rotateKeys } from './commands/keys.js';
+import { enableMaintenanceMode, disableMaintenanceMode } from './commands/maintenance.js';
+import { cacheConfig, cacheRoutes, cacheSearchIndex, cacheViews, checkRoutes, clearConfigCache, clearOptimizationCaches, clearRouteCache, clearSearchIndex, clearViews, installAuth, listRoutes, makeLayout, makePage, optimizeForProduction, publishConfig, publishStubs, runDatabaseCommand, scheduleList, scheduleRun, showResolvedConfig, workerList, workerStart, } from './commands/app-commands.js';
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+async function main() {
+    if (argv.includes('--help') || cmd === 'help') {
+        return renderCombinedHelp();
+    }
+    // ── LumiARQ-specific commands ──────────────────────────────────────────────
+    if (cmd === 'serve') {
+        const port = parsePort(argv);
+        const host = parseHost(argv);
+        return serveApp({ ...(port !== undefined ? { port } : {}), ...(host ? { host } : {}) });
+    }
+    if (cmd === 'preview') {
+        const port = parsePort(argv);
+        const target = parsePreviewTarget(argv);
+        return previewApp({ ...(port !== undefined ? { port } : {}), ...(target ? { target } : {}) });
+    }
+    if (cmd === 'build') {
+        const target = parseTarget(argv);
+        return buildApp(target !== undefined ? { target } : {});
+    }
+    if (cmd === 'build:vercel') {
+        return buildApp({ target: 'vercel' });
+    }
+    if (cmd === 'build:vercel-fn') {
+        return buildVercelFunction();
+    }
+    if (cmd === 'info') {
+        return showInfo();
+    }
+    if (cmd === 'health') {
+        runHealthPreChecks();
+        const { runCli } = await import('@lumiarq/lumis');
+        return runCli(['doctor', ...argv.slice(1)]);
+    }
+    if (cmd === 'doctor') {
+        runHealthPreChecks();
+        const { runCli } = await import('@lumiarq/lumis');
+        return runCli(argv);
+    }
+    if (cmd === 'module:list') {
+        return listModules();
+    }
+    if (cmd === 'test') {
+        return runTest(argv.slice(1));
+    }
+    if (cmd === 'prettier:sync') {
+        return syncPrettierConfig();
+    }
+    if (cmd === 'key:generate') {
+        return generateKeys();
+    }
+    if (cmd === 'key:rotate') {
+        return rotateKeys();
+    }
+    if (cmd === 'config:show') {
+        const configName = argv[1];
+        if (!configName) {
+            writeError(ui.fail('Usage: lumis config:show <name> [--json]'));
+            return 1;
+        }
+        return showResolvedConfig(configName);
+    }
+    if (cmd === 'config:cache') {
+        return cacheConfig();
+    }
+    if (cmd === 'config:clear') {
+        return clearConfigCache();
+    }
+    if (cmd?.startsWith('db:')) {
+        return await runDatabaseCommand(cmd, argv.slice(1));
+    }
+    if (cmd === 'route:list') {
+        return listRoutes();
+    }
+    if (cmd === 'route:check') {
+        return checkRoutes();
+    }
+    if (cmd === 'route:cache') {
+        return cacheRoutes();
+    }
+    if (cmd === 'make:page') {
+        return makePage(argv[1] ?? '', process.cwd(), argv.includes('--force'));
+    }
+    if (cmd === 'make:layout') {
+        return makeLayout(argv[1] ?? '', process.cwd(), argv.includes('--force'));
+    }
+    if (cmd === 'route:clear') {
+        return clearRouteCache();
+    }
+    if (cmd === 'view:cache') {
+        return cacheViews();
+    }
+    if (cmd === 'view:clear') {
+        return clearViews();
+    }
+    if (cmd === 'search:index') {
+        return cacheSearchIndex();
+    }
+    if (cmd === 'search:clear') {
+        return clearSearchIndex();
     }
-    return async (event) => {
-        const payload = {
-            type: event.type,
-            name: event.name,
-            status: event.status,
-            ...(event.message ? { message: event.message } : {}),
-            ...(event.context ? { context: event.context } : {}),
-        };
-        process.stderr.write(`[lumis-trace] ${JSON.stringify(payload)}\n`);
-    };
+    if (cmd === 'optimize') {
+        return optimizeForProduction();
+    }
+    if (cmd === 'optimize:clear') {
+        return clearOptimizationCaches();
+    }
+    if (cmd === 'down') {
+        const message = parseStringFlag(argv, '--message');
+        const secret = parseStringFlag(argv, '--secret');
+        const allowedIps = parseRepeatedFlag(argv, '--allow');
+        return enableMaintenanceMode({
+            ...(message ? { message } : {}),
+            ...(secret ? { secret } : {}),
+            ...(allowedIps.length > 0 ? { allowedIps } : {}),
+        });
+    }
+    if (cmd === 'up') {
+        return disableMaintenanceMode();
+    }
+    if (cmd === 'stub:publish') {
+        return publishStubs({ all: argv.includes('--all'), iam: argv.includes('--iam') });
+    }
+    if (cmd === 'auth:install') {
+        const uiFramework = parseStringFlag(argv, '--ui');
+        return installAuth({
+            iam: argv.includes('--iam'),
+            ...(uiFramework ? { ui: uiFramework } : {}),
+        });
+    }
+    if (cmd === 'publish') {
+        const subCmd = argv[1];
+        if (subCmd === 'config') {
+            const configName = argv[2] ?? 'list';
+            return publishConfig(configName, argv.includes('--force'));
+        }
+        if (subCmd === 'stub' || subCmd === 'stubs') {
+            return publishStubs({ all: argv.includes('--all'), iam: argv.includes('--iam') });
+        }
+        writeError(ui.fail(`Unknown publish subcommand: "${subCmd}". Try: publish config <name>`));
+        return 1;
+    }
+    if (cmd === 'worker:start') {
+        return workerStart(argv.includes('--dev'));
+    }
+    if (cmd === 'worker:list') {
+        return workerList();
+    }
+    if (cmd === 'schedule:list') {
+        return scheduleList();
+    }
+    if (cmd === 'schedule:run') {
+        return scheduleRun(argv[1] ?? '');
+    }
+    const projectCommandExit = await runProjectCommandDirect(argv);
+    if (projectCommandExit !== null) {
+        return projectCommandExit;
+    }
+    // ── Delegate to base @lumiarq/lumis (lazy import avoids auto-run side effect)
+    const { runCli } = await import('@lumiarq/lumis');
+    return runCli(argv);
 }
-async function emitTrace(onTrace, event) {
-    if (!onTrace)
-        return;
-    await onTrace(event);
+async function renderCombinedHelp() {
+    renderWrapperHelp();
+    writeLine(ui.section('Base Lumis Commands'));
+    const { runCli } = await import('@lumiarq/lumis');
+    return runCli(['--help']);
 }
-function formatUsage() {
-    const lines = [
-        ansi.label('Core CLI'),
-        `  ${ansi.dim('Prompt -> Plan -> Confirm -> Execute -> Verified Result')}`,
-        '',
-        `${ansi.bold('Usage')}:`,
-        `  ${ansi.cyan('lumis --help')}`,
-    ];
-    for (const command of COMMANDS) {
-        lines.push(`  ${ansi.cyan(`lumis ${command.path.join(' ')}`)}  ${ansi.dim(`# ${command.description}`)}`);
-    }
-    return `${lines.join('\n')}\n`;
+function renderWrapperHelp() {
+    writeLine();
+    writeLine(ui.section('LumiARQ CLI'));
+    writeLine(`  ${ui.dim('Wrapper commands are shown first; core Lumis commands remain available underneath.')}`);
+    writeLine();
+    writeLine(`  ${ui.bold('Runtime')}`);
+    writeLine('    lumis serve [--port|-p <port>] [--host|-H <host>]');
+    writeLine('    lumis build [--target|--to|--t|-t <node|static|cloudflare|vercel>]');
+    writeLine('    lumis build:vercel');
+    writeLine('    lumis preview [--target|--to|--t|-t <node|static|cloudflare>]');
+    writeLine();
+    writeLine(`  ${ui.bold('App')}`);
+    writeLine('    lumis info');
+    writeLine('    lumis health');
+    writeLine('    lumis module:list');
+    writeLine('    lumis config:show <name>');
+    writeLine('    lumis config:cache | config:clear');
+    writeLine('    lumis route:list | route:check | route:cache | route:clear');
+    writeLine('    lumis make:page <route> [--force]');
+    writeLine('    lumis make:layout <route> [--force]');
+    writeLine('    lumis view:cache | view:clear');
+    writeLine('    lumis search:index | search:clear');
+    writeLine('    lumis optimize | optimize:clear');
+    writeLine('    lumis key:generate | key:rotate');
+    writeLine('    lumis down [--message <text>] [--secret <token>] [--allow <ip>]');
+    writeLine('    lumis up');
+    writeLine('    lumis auth:install [--iam] [--ui react]');
+    writeLine('    lumis stub:publish [--all|--iam]');
+    writeLine();
+    writeLine(`  ${ui.bold('Database')}`);
+    writeLine('    lumis db:generate | db:migrate');
+    writeLine('    lumis db:ping        — verify DB connection and diagnose failures');
+    writeLine('    lumis db:seed');
+    writeLine('    lumis db:fresh       — migrate + seed (destructive)');
+    writeLine('    lumis db:reset       — drop all tables + migrate');
+    writeLine('    lumis db:studio      — open drizzle-kit studio');
+    writeLine();
+    writeLine(`  ${ui.bold('Config')}`);
+    writeLine('    lumis publish config <name>  — mail | queue | cache | storage | session | security | logging | auth');
+    writeLine('    lumis publish config all     — publish every config file');
+    writeLine('    lumis publish config list    — show available configs');
+    writeLine();
+    writeLine(`  ${ui.bold('Workers & Scheduling')}`);
+    writeLine('    lumis worker:start [--dev]   — start background worker process');
+    writeLine('    lumis worker:list            — list registered workers + scheduled jobs');
+    writeLine('    lumis schedule:list          — list all cron jobs');
+    writeLine('    lumis schedule:run <name>    — run a specific cron job immediately');
+    writeLine();
+    writeLine(`  ${ui.bold('Core Lumis')}`);
+    writeLine('    lumis doctor | init | make | intent | ir:* | runtime:* | tinker');
+    writeLine();
+    writeLine(`  ${ui.bold('Project Commands')}`);
+    writeLine('    lumis <your:command>          — run projectCommands entries directly');
+    writeLine('    lumis commands run project <name>');
+    writeLine();
 }
-/**
- * Resolve command using longest prefix semantics.
- *
- * Example:
- * - argv: ['intent', 'create', 'record']
- * - match: ['intent'] with args ['create', 'record']
- *
- * @param argv - Raw command tokens after the executable name.
- * @returns Matched command and trailing arguments, or null when no command matches.
- */
-function matchCommand(argv) {
-    const matches = COMMANDS.filter((command) => {
-        if (command.path.length > argv.length) {
-            return false;
-        }
-        return command.path.every((segment, index) => segment === argv[index]);
-    }).sort((left, right) => right.path.length - left.path.length);
-    const command = matches[0];
-    if (!command) {
+const BASE_COMMAND_ROOTS = new Set([
+    'use',
+    'pack',
+    'commands',
+    'doctor',
+    'init',
+    'make',
+    'intent',
+    'ir',
+    'runtime',
+    'tinker',
+]);
+async function runProjectCommandDirect(args) {
+    const candidate = args[0];
+    if (!candidate) {
+        return null;
+    }
+    if (BASE_COMMAND_ROOTS.has(candidate)) {
+        return null;
+    }
+    const { runCli } = await import('@lumiarq/lumis');
+    let stdout = '';
+    let stderr = '';
+    const listExit = await runCli(['commands', 'list', '--json'], {
+        write: (chunk) => {
+            stdout += chunk;
+        },
+        writeError: (chunk) => {
+            stderr += chunk;
+        },
+    });
+    if (listExit !== 0 || stderr.trim().length > 0) {
+        return null;
+    }
+    let commands = [];
+    try {
+        commands = JSON.parse(stdout);
+    }
+    catch {
         return null;
     }
-    return {
-        command,
-        args: argv.slice(command.path.length),
-    };
+    const exists = commands.some((entry) => entry.source === 'project' && entry.name === candidate);
+    if (!exists) {
+        return null;
+    }
+    return runCli(['commands', 'run', 'project', candidate, ...args.slice(1)]);
 }
-/**
- * Execute the host CLI command flow.
- *
- * @param argv - CLI arguments excluding the node/script prefix.
- * @param options - Optional execution overrides for project root and output writers.
- * @returns Exit code (0 success, non-zero failure).
- */
-export async function runCli(argv, options = {}) {
-    const write = options.write ?? ((message) => process.stdout.write(message));
-    const writeError = options.writeError ?? ((message) => process.stderr.write(message));
-    const onTrace = createTraceListener();
-    const stdin = options.stdin ?? process.stdin;
-    const stdout = options.stdout ?? process.stdout;
-    const interactiveMode = options.interactiveMode ?? 'auto';
-    const shouldRunInteractiveMenu = argv.length === 0 &&
-        !argv.includes('--help') &&
-        (interactiveMode === 'on' ||
-            (interactiveMode === 'auto' && process.env.CI !== 'true' && process.env.LUMIS_NO_TUI !== '1' && stdin.isTTY && stdout.isTTY));
-    if (shouldRunInteractiveMenu) {
-        await emitTrace(onTrace, {
-            type: 'command-dispatch',
-            status: 'start',
-            name: 'interactive-launcher',
-            context: { mode: interactiveMode },
-        });
-        const launcherResult = await runInteractiveLauncher({
-            projectRoot: options.projectRoot ?? process.cwd(),
-            write,
-            stdin,
-            stdout,
-        });
-        if (launcherResult.kind === 'exit') {
-            await emitTrace(onTrace, {
-                type: 'command-dispatch',
-                status: launcherResult.code === 0 ? 'success' : 'failure',
-                name: 'interactive-launcher',
-                context: { exitCode: launcherResult.code },
+async function runTest(extraArgs) {
+    const cwd = process.cwd();
+    const { execSync } = await import('node:child_process');
+    // Prefer flat pkg/vitest.config.ts; fall back to legacy pkg/vitest/config.ts
+    const flatConfig = join(cwd, 'pkg', 'vitest.config.ts');
+    const subdirConfig = join(cwd, 'pkg', 'vitest', 'config.ts');
+    const configPath = existsSync(flatConfig)
+        ? flatConfig
+        : existsSync(subdirConfig)
+            ? subdirConfig
+            : null;
+    const configFlag = configPath ? ['--config', configPath] : [];
+    const vitestArgs = ['vitest', 'run', ...configFlag, ...extraArgs].join(' ');
+    try {
+        execSync(`pnpm exec ${vitestArgs}`, { stdio: 'inherit', cwd });
+        return 0;
+    }
+    catch {
+        return 1;
+    }
+}
+async function syncPrettierConfig() {
+    const cwd = process.cwd();
+    const { writeFileSync } = await import('node:fs');
+    const { pathToFileURL } = await import('node:url');
+    const srcPath = join(cwd, 'pkg', 'prettier.config.ts');
+    if (!existsSync(srcPath)) {
+        writeError(ui.fail('pkg/prettier.config.ts not found. Create it first.\n'));
+        return 1;
+    }
+    let config;
+    try {
+        const mod = await import(pathToFileURL(srcPath).href);
+        config = mod.default ?? mod;
+    }
+    catch (e) {
+        writeError(ui.fail(`Failed to load pkg/prettier.config.ts: ${String(e)}\n`));
+        return 1;
+    }
+    const out = [
+        '// Auto-generated by lumis prettier:sync — edit pkg/prettier.config.ts instead.',
+        '// Run `lumis prettier:sync` to regenerate after changing pkg/prettier.config.ts.',
+        "/** @type {import('prettier').Config} */",
+        `export default ${JSON.stringify(config, null, 2)};`,
+        '',
+    ].join('\n');
+    writeFileSync(join(cwd, 'prettier.config.mjs'), out, 'utf8');
+    writeLine(ui.ok('prettier.config.mjs generated from pkg/prettier.config.ts'));
+    return 0;
+}
+function runHealthPreChecks() {
+    const cwd = process.cwd();
+    const checks = [];
+    // Required bootstrap files
+    checks.push({
+        label: 'bootstrap/entry.ts present',
+        pass: existsSync(join(cwd, 'bootstrap', 'entry.ts')),
+        fix: 'bootstrap/entry.ts is missing — this is the HTTP server entrypoint.',
+    });
+    checks.push({
+        label: 'bootstrap/providers.ts present',
+        pass: existsSync(join(cwd, 'bootstrap', 'providers.ts')),
+        fix: "bootstrap/providers.ts is missing — service container won't boot.",
+    });
+    checks.push({
+        label: 'src/config/app.ts present',
+        pass: existsSync(join(cwd, 'src', 'config', 'app.ts')),
+        fix: 'src/config/app.ts is missing — run: lumis publish config app',
+    });
+    checks.push({
+        label: '@types/node installed',
+        pass: existsSync(join(cwd, 'node_modules', '@types', 'node')) ||
+            existsSync(join(cwd, '..', 'node_modules', '@types', 'node')),
+        fix: 'Install @types/node: pnpm add -D @types/node',
+    });
+    checks.push({
+        label: 'drizzle config uses canonical pkg path',
+        pass: !existsSync(join(cwd, 'drizzle.config.ts')) ||
+            existsSync(join(cwd, 'pkg', 'drizzle.config.ts')) ||
+            existsSync(join(cwd, 'pkg', 'drizzle', 'config.ts')), // legacy subdir — migrate to flat
+        fix: 'Move Drizzle config to pkg/drizzle.config.ts. No root shim needed — lumis db:* reads pkg/ directly.',
+    });
+    checks.push({
+        label: 'vitest config uses canonical pkg path',
+        pass: !existsSync(join(cwd, 'vitest.config.ts')) ||
+            existsSync(join(cwd, 'pkg', 'vitest.config.ts')) ||
+            existsSync(join(cwd, 'pkg', 'vitest', 'config.ts')), // legacy subdir — migrate to flat
+        fix: 'Move Vitest config to pkg/vitest.config.ts. No root shim needed — lumis test reads pkg/ directly.',
+    });
+    checks.push({
+        label: 'lumis config uses canonical pkg path',
+        pass: (!existsSync(join(cwd, 'lumis.config.ts')) && !existsSync(join(cwd, 'lumis.config.json'))) ||
+            existsSync(join(cwd, 'pkg', 'lumis.config.ts')) ||
+            existsSync(join(cwd, 'pkg', 'lumis', 'config.ts')), // legacy subdir — migrate to flat
+        fix: 'Move lumis config to pkg/lumis.config.ts and remove the root lumis.config.* file.',
+    });
+    checks.push({
+        label: 'prettier config uses canonical pkg path',
+        pass: !existsSync(join(cwd, '.prettierrc')) || existsSync(join(cwd, 'pkg', 'prettier.config.ts')),
+        fix: 'Create pkg/prettier.config.ts and run `lumis prettier:sync` to generate prettier.config.mjs. Then delete .prettierrc.',
+    });
+    // Warn if queue driver isn't stub but worker.ts is missing
+    const queueConfigPath = existsSync(join(cwd, 'src', 'config', 'queue.ts'))
+        ? join(cwd, 'src', 'config', 'queue.ts')
+        : join(cwd, 'config', 'queue.ts'); // legacy fallback
+    if (existsSync(queueConfigPath)) {
+        const queueSrc = readFileSync(queueConfigPath, 'utf8');
+        const usesBullmq = queueSrc.includes("'bullmq'") || queueSrc.includes('"bullmq"');
+        if (usesBullmq) {
+            checks.push({
+                label: 'bootstrap/worker.ts present (queue driver: bullmq)',
+                pass: existsSync(join(cwd, 'bootstrap', 'worker.ts')),
+                fix: "Queue driver is 'bullmq' but bootstrap/worker.ts is missing. Create it to process queued jobs.",
             });
-            return launcherResult.code;
         }
-        argv = launcherResult.argv;
-    }
-    if (argv.includes('--help') || argv.length === 0) {
-        await emitTrace(onTrace, {
-            type: 'command-dispatch',
-            status: 'info',
-            name: 'help',
-            context: { argvLength: argv.length },
-        });
-        write(formatUsage());
-        return 0;
     }
-    const matched = matchCommand(argv);
-    if (!matched) {
-        await emitTrace(onTrace, {
-            type: 'command-dispatch',
-            status: 'failure',
-            name: 'unknown-command',
-            message: argv.join(' '),
+    // Vercel deployment hygiene (Phase 0)
+    const vercelJsonPath = join(cwd, 'vercel.json');
+    if (existsSync(vercelJsonPath)) {
+        let vercelRaw = '';
+        try {
+            vercelRaw = readFileSync(vercelJsonPath, 'utf8');
+        }
+        catch {
+            vercelRaw = '';
+        }
+        const usesLegacyRoutes = vercelRaw.includes('"routes"') &&
+            vercelRaw.includes('"handle"') &&
+            vercelRaw.includes('filesystem');
+        checks.push({
+            label: 'vercel.json uses rewrites (not legacy routes + filesystem)',
+            pass: !usesLegacyRoutes && vercelRaw.includes('"rewrites"'),
+            fix: 'Replace deprecated routes/handle:filesystem with rewrites → /api/index. See lumiarq-vercel-deployment-fix skill.',
+        });
+        checks.push({
+            label: 'vercel.json installCommand pins pnpm',
+            pass: vercelRaw.includes('"installCommand"') && vercelRaw.includes('pnpm'),
+            fix: 'Add installCommand: "corepack enable && pnpm install --frozen-lockfile" to vercel.json.',
+        });
+        checks.push({
+            label: 'vercel.json bundles framework cache for serverless',
+            pass: vercelRaw.includes('"includeFiles"') && vercelRaw.includes('src/storage/framework/cache'),
+            fix: 'Add functions.api/index.js.includeFiles: "src/storage/framework/cache/**" so route/view caches ship with the function.',
         });
-        writeError(`${ansi.fail(`Unknown command: ${argv.join(' ')}`)}\n`);
-        write(formatUsage());
-        return 1;
     }
-    await emitTrace(onTrace, {
-        type: 'command-dispatch',
-        status: 'start',
-        name: matched.command.path.join(' '),
-        context: { args: matched.args },
+    checks.push({
+        label: 'api/index.js present (run pnpm run build:vercel first)',
+        pass: existsSync(join(cwd, 'api', 'index.js')),
+        fix: 'Run pnpm run build:vercel locally — Vercel requires api/index.js as the serverless entry.',
     });
-    const context = await createCommandContext({
-        argv,
-        commandPath: matched.command.path,
-        commandArgs: matched.args,
-        projectRoot: options.projectRoot ?? process.cwd(),
-        write,
-        writeError,
-        ...(onTrace ? { onTrace } : {}),
+    // Route loader cache path checks (Wave 2 canonical layout)
+    const storageRoot = readStorageRoot(cwd);
+    const routesLoader = join(cwd, storageRoot, 'framework', 'cache', 'routes.loader.ts');
+    const staleRootStorageLoader = join(cwd, 'storage', 'framework', 'cache', 'routes.loader.ts');
+    if (storageRoot !== 'storage' && existsSync(staleRootStorageLoader)) {
+        checks.push({
+            label: 'no stale root storage/ cache (use configured storage root)',
+            pass: false,
+            fix: `Remove storage/framework/cache — lumis should write to ${storageRoot}/framework/cache only.`,
+        });
+    }
+    const bootstrapRoutesLoader = join(cwd, 'bootstrap', 'cache', 'routes.loader.ts');
+    checks.push({
+        label: 'route loader cache path is canonical',
+        pass: !(existsSync(routesLoader) && existsSync(bootstrapRoutesLoader)),
+        fix: `Duplicate route cache detected. Keep only ${storageRoot}/framework/cache/routes.loader.ts and remove bootstrap/cache/routes.loader.ts`,
     });
-    return matched.command.handler(context);
+    // Stale route loader warning
+    if (existsSync(routesLoader)) {
+        const loaderMtime = statSync(routesLoader).mtimeMs;
+        const routesRoot = join(cwd, 'src', 'modules');
+        let stale = false;
+        if (existsSync(routesRoot)) {
+            const stack = [routesRoot];
+            while (stack.length > 0) {
+                const dir = stack.pop();
+                for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                    if (entry.isDirectory()) {
+                        stack.push(join(dir, entry.name));
+                        continue;
+                    }
+                    if (/\/http\/routes\/.+\.(ts|js)$/.test(join(dir, entry.name))) {
+                        if (statSync(join(dir, entry.name)).mtimeMs > loaderMtime) {
+                            stale = true;
+                            break;
+                        }
+                    }
+                }
+                if (stale)
+                    break;
+            }
+        }
+        checks.push({
+            label: 'route cache is fresh',
+            pass: !stale,
+            fix: 'Route files have changed since last cache. Run: lumis route:cache',
+        });
+    }
+    const warnings = checks.filter((c) => !c.pass);
+    if (warnings.length > 0) {
+        writeLine();
+        writeLine(ui.section('Health Pre-checks'));
+        for (const w of warnings) {
+            writeLine(`  ${ui.warn(w.label)}`);
+            if (w.fix)
+                writeLine(`    ${ui.dim(w.fix)}`);
+        }
+        writeLine();
+    }
+}
+function parsePort(args) {
+    const idx = args.findIndex((a) => a === '--port' || a === '-p');
+    const inline = args.find((a) => a.startsWith('--port='));
+    const raw = inline ? inline.split('=')[1] : idx !== -1 ? args[idx + 1] : undefined;
+    if (raw)
+        return parseInt(raw, 10);
+    return undefined;
+}
+function parseHost(args) {
+    const idx = args.findIndex((a) => a === '--host' || a === '-H');
+    const inline = args.find((a) => a.startsWith('--host='));
+    if (inline)
+        return inline.split('=')[1];
+    if (idx !== -1)
+        return args[idx + 1];
+    return undefined;
+}
+function parseTarget(args) {
+    const idx = args.findIndex((a) => a === '--target' || a === '--to' || a === '--t' || a === '-t');
+    const inline = args.find((a) => a.startsWith('--target=') || a.startsWith('--to=') || a.startsWith('--t='));
+    if (inline) {
+        const val = inline.slice(inline.indexOf('=') + 1);
+        if (val === 'node' || val === 'static' || val === 'cloudflare' || val === 'vercel')
+            return val;
+    }
+    if (idx !== -1) {
+        const val = args[idx + 1];
+        if (val === 'node' || val === 'static' || val === 'cloudflare' || val === 'vercel')
+            return val;
+    }
+    return undefined;
 }
-function isMainModule() {
-    const argv1 = process.argv[1];
-    if (!argv1) {
-        return false;
+function parsePreviewTarget(args) {
+    const target = parseTarget(args);
+    if (target === 'vercel') {
+        writeError(ui.fail('`preview` does not support target "vercel". Use: lumis build --target vercel'));
+        return undefined;
+    }
+    return target;
+}
+function parseStringFlag(args, flag) {
+    const index = args.findIndex((value) => value === flag);
+    const inline = args.find((value) => value.startsWith(`${flag}=`));
+    if (inline) {
+        return inline.slice(flag.length + 1);
+    }
+    if (index !== -1) {
+        return args[index + 1];
     }
-    return import.meta.url === pathToFileURL(argv1).href;
+    return undefined;
 }
-if (isMainModule()) {
-    void runCli(process.argv.slice(2));
+function parseRepeatedFlag(args, flag) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === flag && args[index + 1]) {
+            values.push(args[index + 1]);
+        }
+        if (token?.startsWith(`${flag}=`)) {
+            values.push(token.slice(flag.length + 1));
+        }
+    }
+    return values;
 }
+main().then((code) => process.exit(code));
 //# sourceMappingURL=cli.js.map