ultra-dex 1.7.3 → 2.2.0

package/lib/commands/init.js

@@ -0,0 +1,337 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs/promises';
+import path from 'path';
+
+import { QUICK_START_TEMPLATE } from '../templates/quick-start.js';
+import { CONTEXT_TEMPLATE } from '../templates/context.js';
+import { validateProjectName, validateSafePath } from '../utils/validation.js';
+import { ASSETS_ROOT, ROOT_FALLBACK } from '../config/paths.js';
+import { githubBlobUrl, githubWebUrl } from '../config/urls.js';
+import { copyWithFallback, listWithFallback, readWithFallback } from '../utils/fallback.js';
+
+export function registerInitCommand(program) {
+  program
+    .command('init')
+    .description('Initialize a new Ultra-Dex project')
+    .option('-n, --name <name>', 'Project name')
+    .option('-d, --dir <directory>', 'Output directory', '.')
+    .option('--preview', 'Preview files without creating them')
+    .action(async (options) => {
+      console.log(chalk.cyan(program.banner));
+      console.log(chalk.bold('\nWelcome to Ultra-Dex! Let\'s plan your SaaS.\n'));
+
+      if (options.preview) {
+        console.log('\n📋 Files that would be created:\n');
+        console.log('  QUICK-START.md');
+        console.log('  CONTEXT.md');
+        console.log('  IMPLEMENTATION-PLAN.md');
+        console.log('  docs/CHECKLIST.md');
+        console.log('  docs/AI-PROMPTS.md');
+        console.log('\nRun without --preview to create files.');
+        return;
+      }
+
+      const dirValidation = validateSafePath(options.dir, 'Output directory');
+      if (dirValidation !== true) {
+        console.log(chalk.red(dirValidation));
+        process.exit(1);
+      }
+
+      const answers = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'projectName',
+          message: 'What\'s your project name?',
+          default: options.name || 'my-saas',
+          validate: validateProjectName,
+        },
+        {
+          type: 'input',
+          name: 'ideaWhat',
+          message: 'What are you building? (1 sentence)',
+          validate: (input) => input.length > 0 || 'Please describe your idea',
+        },
+        {
+          type: 'input',
+          name: 'ideaFor',
+          message: 'Who is it for?',
+          validate: (input) => input.length > 0 || 'Please specify your target users',
+        },
+        {
+          type: 'input',
+          name: 'problem1',
+          message: 'Problem #1 you\'re solving:',
+          default: '',
+        },
+        {
+          type: 'input',
+          name: 'problem2',
+          message: 'Problem #2 you\'re solving:',
+          default: '',
+        },
+        {
+          type: 'input',
+          name: 'problem3',
+          message: 'Problem #3 you\'re solving:',
+          default: '',
+        },
+        {
+          type: 'input',
+          name: 'feature1',
+          message: 'Critical production feature:',
+          default: '',
+        },
+        {
+          type: 'list',
+          name: 'frontend',
+          message: 'Frontend framework:',
+          choices: ['Next.js', 'Remix', 'SvelteKit', 'Nuxt', 'Other'],
+        },
+        {
+          type: 'list',
+          name: 'database',
+          message: 'Database:',
+          choices: ['PostgreSQL', 'Supabase', 'MongoDB', 'PlanetScale', 'Other'],
+        },
+        {
+          type: 'list',
+          name: 'auth',
+          message: 'Authentication:',
+          choices: ['NextAuth', 'Clerk', 'Auth0', 'Supabase Auth', 'Other'],
+        },
+        {
+          type: 'list',
+          name: 'payments',
+          message: 'Payments:',
+          choices: ['Stripe', 'Lemonsqueezy', 'Paddle', 'None (free)', 'Other'],
+        },
+        {
+          type: 'list',
+          name: 'hosting',
+          message: 'Hosting:',
+          choices: ['Vercel', 'Railway', 'Fly.io', 'AWS', 'Other'],
+        },
+        {
+          type: 'confirm',
+          name: 'includeCursorRules',
+          message: 'Include cursor-rules for AI assistants? (Cursor, Copilot)',
+          default: true,
+        },
+        {
+          type: 'confirm',
+          name: 'includeFullTemplate',
+          message: 'Copy full 34-section template locally?',
+          default: false,
+        },
+        {
+          type: 'confirm',
+          name: 'includeDocs',
+          message: 'Copy VERIFICATION.md & AGENT-INSTRUCTIONS.md to docs/?',
+          default: true,
+        },
+        {
+          type: 'confirm',
+          name: 'includeAgents',
+          message: 'Include AI agent prompts? (.agents/ folder)',
+          default: true,
+        },
+      ]);
+
+      const spinner = ora('Creating project files...').start();
+
+      try {
+        const outputDir = path.resolve(options.dir, answers.projectName);
+
+        await fs.mkdir(outputDir, { recursive: true });
+        await fs.mkdir(path.join(outputDir, 'docs'), { recursive: true });
+
+        const replacements = {
+          '{{PROJECT_NAME}}': answers.projectName,
+          '{{DATE}}': new Date().toISOString().split('T')[0],
+          '{{IDEA_WHAT}}': answers.ideaWhat,
+          '{{IDEA_FOR}}': answers.ideaFor,
+          '{{PROBLEM_1}}': answers.problem1 || 'Problem 1',
+          '{{PROBLEM_2}}': answers.problem2 || 'Problem 2',
+          '{{PROBLEM_3}}': answers.problem3 || 'Problem 3',
+          '{{FEATURE_1}}': answers.feature1 || 'Core feature',
+          '{{FRONTEND}}': answers.frontend,
+          '{{DATABASE}}': answers.database,
+          '{{AUTH}}': answers.auth,
+          '{{PAYMENTS}}': answers.payments,
+          '{{HOSTING}}': answers.hosting,
+        };
+
+        let quickStart = QUICK_START_TEMPLATE;
+        let context = CONTEXT_TEMPLATE;
+
+        for (const [key, value] of Object.entries(replacements)) {
+          quickStart = quickStart.replace(new RegExp(key, 'g'), value);
+          context = context.replace(new RegExp(key, 'g'), value);
+        }
+
+        await fs.writeFile(path.join(outputDir, 'QUICK-START.md'), quickStart);
+        await fs.writeFile(path.join(outputDir, 'CONTEXT.md'), context);
+
+        const planContent = `# ${answers.projectName} - Implementation Plan
+
+> Generated with Ultra-Dex CLI
+
+## Overview
+
+${answers.ideaWhat} for ${answers.ideaFor}.
+
+---
+
+## Next Steps
+
+1. Open QUICK-START.md and complete the remaining sections
+2. Copy sections from the full Ultra-Dex template as needed
+3. Use the TaskFlow example as reference
+4. Start building!
+
+## Resources
+
+- [Full Template](${githubBlobUrl('@%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md')})
+- [TaskFlow Example](${githubBlobUrl('@%20Ultra%20DeX/Saas%20plan/Examples/TaskFlow-Complete.md')})
+- [Methodology](${githubBlobUrl('@%20Ultra%20DeX/Saas%20plan/03-METHODOLOGY.md')})
+`;
+
+        await fs.writeFile(path.join(outputDir, 'IMPLEMENTATION-PLAN.md'), planContent);
+
+        if (answers.includeCursorRules) {
+          const rulesDir = path.join(outputDir, '.cursor', 'rules');
+          await fs.mkdir(rulesDir, { recursive: true });
+
+          const cursorRulesPath = path.join(ASSETS_ROOT, 'cursor-rules');
+          const fallbackRulesPath = path.join(ROOT_FALLBACK, 'cursor-rules');
+          try {
+            const ruleFiles = await listWithFallback(cursorRulesPath, fallbackRulesPath);
+            const sourcePath = ruleFiles ? cursorRulesPath : fallbackRulesPath;
+            for (const file of ruleFiles.filter(f => f.endsWith('.mdc'))) {
+              await copyWithFallback(
+                path.join(sourcePath, file),
+                null,
+                path.join(rulesDir, file)
+              );
+            }
+
+            const coreRulePath = path.join(sourcePath, '00-ultra-dex-core.mdc');
+            try {
+              const coreContent = await readWithFallback(coreRulePath, null, 'utf-8');
+              const dotGithub = path.join(outputDir, '.github');
+              await fs.mkdir(dotGithub, { recursive: true });
+              await fs.writeFile(path.join(dotGithub, 'copilot-instructions.md'), coreContent);
+            } catch {
+              // Core rule not available - skip Copilot setup
+            }
+          } catch {
+            console.log(chalk.red('\n  ❌ Cursor rules not found in assets or repo.'));
+            console.log(chalk.cyan('  Fetch: npx ultra-dex fetch --rules'));
+          }
+        }
+
+        if (answers.includeFullTemplate) {
+          const templatePath = path.join(ASSETS_ROOT, 'saas-plan', '04-Imp-Template.md');
+          const fallbackTemplatePath = path.join(ROOT_FALLBACK, '@ Ultra DeX', 'Saas plan', '04-Imp-Template.md');
+          try {
+            await copyWithFallback(templatePath, fallbackTemplatePath, path.join(outputDir, 'docs', 'MASTER-PLAN.md'));
+          } catch {
+            console.log(chalk.red('\n  ❌ Full template not found in assets or repo.'));
+            console.log(chalk.cyan('  Fetch: npx ultra-dex fetch --docs'));
+          }
+        }
+
+        if (answers.includeDocs) {
+          const verificationPath = path.join(ASSETS_ROOT, 'docs', 'VERIFICATION.md');
+          const agentPath = path.join(ASSETS_ROOT, 'agents', 'AGENT-INSTRUCTIONS.md');
+          const fallbackVerificationPath = path.join(ROOT_FALLBACK, 'docs', 'VERIFICATION.md');
+          const fallbackAgentPath = path.join(ROOT_FALLBACK, 'agents', 'AGENT-INSTRUCTIONS.md');
+          try {
+            await copyWithFallback(verificationPath, fallbackVerificationPath, path.join(outputDir, 'docs', 'CHECKLIST.md'));
+            await copyWithFallback(agentPath, fallbackAgentPath, path.join(outputDir, 'docs', 'AI-PROMPTS.md'));
+          } catch {
+            console.log(chalk.red('\n  ❌ Docs not found in assets or repo.'));
+            console.log(chalk.cyan('  Fetch: npx ultra-dex fetch --docs'));
+          }
+        }
+
+        if (answers.includeAgents) {
+          const agentsDir = path.join(outputDir, '.agents');
+          await fs.mkdir(agentsDir, { recursive: true });
+
+          const agentsSourcePath = path.join(ASSETS_ROOT, 'agents');
+          const fallbackAgentsPath = path.join(ROOT_FALLBACK, 'agents');
+          try {
+            const tiers = ['1-leadership', '2-development', '3-security', '4-devops', '5-quality', '6-specialist'];
+            let sourceRoot = agentsSourcePath;
+            try {
+              await fs.access(agentsSourcePath);
+            } catch {
+              sourceRoot = fallbackAgentsPath;
+            }
+
+            for (const tier of tiers) {
+              const tierDir = path.join(agentsDir, tier);
+              await fs.mkdir(tierDir, { recursive: true });
+
+              const tierPath = path.join(sourceRoot, tier);
+              const tierFiles = await fs.readdir(tierPath);
+              for (const file of tierFiles.filter(f => f.endsWith('.md'))) {
+                await fs.copyFile(
+                  path.join(tierPath, file),
+                  path.join(tierDir, file)
+                );
+              }
+            }
+
+            await fs.copyFile(
+              path.join(sourceRoot, '00-AGENT_INDEX.md'),
+              path.join(agentsDir, '00-AGENT_INDEX.md')
+            );
+            await fs.copyFile(
+              path.join(sourceRoot, 'README.md'),
+              path.join(agentsDir, 'README.md')
+            );
+          } catch {
+            console.log(chalk.red('\n  ❌ Agent prompts not found in assets or repo.'));
+            console.log(chalk.cyan('  Fetch: npx ultra-dex fetch --agents'));
+          }
+        }
+
+        spinner.succeed(chalk.green('Project created successfully!'));
+
+        console.log('\n' + chalk.bold('Files created:'));
+        console.log(chalk.gray(`  ${outputDir}/`));
+        console.log(chalk.gray('  ├── QUICK-START.md'));
+        console.log(chalk.gray('  ├── CONTEXT.md'));
+        console.log(chalk.gray('  ├── IMPLEMENTATION-PLAN.md'));
+        if (answers.includeFullTemplate) {
+          console.log(chalk.gray('  ├── docs/MASTER-PLAN.md (34 sections)'));
+        }
+        if (answers.includeDocs) {
+          console.log(chalk.gray('  ├── docs/CHECKLIST.md'));
+          console.log(chalk.gray('  ├── docs/AI-PROMPTS.md'));
+        }
+        if (answers.includeCursorRules) {
+          console.log(chalk.gray('  ├── .cursor/rules/ (11 AI rule files)'));
+        }
+        if (answers.includeAgents) {
+          console.log(chalk.gray('  └── .agents/ (15 AI agent prompts in 6 tiers)'));
+        }
+
+        console.log('\n' + chalk.bold('Next steps:'));
+        console.log(chalk.cyan(`  1. cd ${answers.projectName}`));
+        console.log(chalk.cyan('  2. Open QUICK-START.md and complete it'));
+        console.log(chalk.cyan('  3. Start building! 🚀'));
+
+        console.log('\n' + chalk.gray('Full Ultra-Dex repo:'));
+        console.log(chalk.blue(`  ${githubWebUrl()}`));
+      } catch (error) {
+        spinner.fail(chalk.red('Failed to create project'));
+        console.error(error);
+        process.exit(1);
+      }
+    });
+}

package/lib/commands/placeholders.js

@@ -0,0 +1,11 @@
+import chalk from 'chalk';
+
+// Note: build, review, and align commands are now in separate files:
+// - build.js (registerBuildCommand)
+// - review.js (registerReviewCommand)
+// The align command is a simplified version of review
+
+export function registerPlaceholderCommands(program) {
+  // Placeholder for future commands
+  // All v2 commands have been implemented in their own files
+}

package/lib/commands/review.js

@@ -0,0 +1,287 @@
+/**
+ * ultra-dex review command
+ * Reviews code against the implementation plan using AI
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import fs from 'fs/promises';
+import path from 'path';
+import { createProvider, getDefaultProvider, checkConfiguredProviders } from '../providers/index.js';
+import { SYSTEM_PROMPT, generateReviewPrompt } from '../templates/prompts/review-code.js';
+
+// File patterns to scan
+const CODE_PATTERNS = {
+  database: ['**/prisma/schema.prisma', '**/schema.sql', '**/migrations/**', '**/models/**'],
+  api: ['**/api/**', '**/routes/**', '**/controllers/**', '**/src/app/api/**'],
+  auth: ['**/auth/**', '**/middleware/**', '**/*auth*', '**/*session*'],
+  frontend: ['**/components/**', '**/pages/**', '**/app/**', '**/src/app/**'],
+  testing: ['**/*.test.*', '**/*.spec.*', '**/tests/**', '**/__tests__/**'],
+  config: ['package.json', 'tsconfig.json', '.env.example', 'next.config.*'],
+};
+
+async function readFileSafe(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function getDirectoryStructure(dir, depth = 3, prefix = '') {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  let structure = '';
+
+  for (const entry of entries) {
+    // Skip common non-essential directories
+    if (['node_modules', '.git', '.next', 'dist', 'build', '.ultra-dex'].includes(entry.name)) {
+      continue;
+    }
+
+    const entryPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      structure += `${prefix}📁 ${entry.name}/\n`;
+      if (depth > 1) {
+        structure += await getDirectoryStructure(entryPath, depth - 1, prefix + '  ');
+      }
+    } else {
+      structure += `${prefix}📄 ${entry.name}\n`;
+    }
+  }
+
+  return structure;
+}
+
+async function findKeyFiles(dir) {
+  const keyFiles = [];
+  const patterns = [
+    'package.json',
+    'prisma/schema.prisma',
+    'src/app/api',
+    'app/api',
+    'middleware.ts',
+    'middleware.js',
+    'auth.ts',
+    'auth.js',
+  ];
+
+  for (const pattern of patterns) {
+    const filePath = path.join(dir, pattern);
+    if (await fileExists(filePath)) {
+      try {
+        const stat = await fs.stat(filePath);
+        if (stat.isFile()) {
+          const content = await fs.readFile(filePath, 'utf-8');
+          keyFiles.push({ path: pattern, content: content.slice(0, 3000) });
+        }
+      } catch {
+        // Skip files we can't read
+      }
+    }
+  }
+
+  return keyFiles;
+}
+
+export function registerReviewCommand(program) {
+  program
+    .command('review')
+    .description('Review code against the implementation plan')
+    .option('-d, --dir <directory>', 'Directory to review', '.')
+    .option('-p, --provider <provider>', 'AI provider (claude, openai, gemini)')
+    .option('-k, --key <apiKey>', 'API key')
+    .option('--quick', 'Quick review without AI (checks file structure only)')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      console.log(chalk.cyan('\n🔍 Ultra-Dex Code Review\n'));
+
+      const reviewDir = path.resolve(options.dir);
+
+      // Check for plan
+      const planPath = path.join(reviewDir, 'IMPLEMENTATION-PLAN.md');
+      const plan = await readFileSafe(planPath);
+
+      if (!plan) {
+        console.log(chalk.yellow('⚠️  No IMPLEMENTATION-PLAN.md found.\n'));
+        console.log(chalk.white('Run one of these first:'));
+        console.log(chalk.gray('  npx ultra-dex init'));
+        console.log(chalk.gray('  npx ultra-dex generate\n'));
+        return;
+      }
+
+      // Get directory structure
+      const spinner = ora('Scanning codebase...').start();
+      const structure = await getDirectoryStructure(reviewDir);
+      const keyFiles = await findKeyFiles(reviewDir);
+      spinner.succeed('Codebase scanned');
+
+      if (options.quick) {
+        // Quick review - just check structure
+        console.log(chalk.white('\n📁 Project Structure:\n'));
+        console.log(chalk.gray(structure));
+
+        // Quick checks
+        const checks = [
+          { name: 'IMPLEMENTATION-PLAN.md', path: 'IMPLEMENTATION-PLAN.md' },
+          { name: 'CONTEXT.md', path: 'CONTEXT.md' },
+          { name: 'package.json', path: 'package.json' },
+          { name: 'Database schema', path: 'prisma/schema.prisma' },
+          { name: 'API routes', path: 'src/app/api' },
+          { name: 'Tests', path: 'tests' },
+        ];
+
+        console.log(chalk.white('\n📋 Quick Checks:\n'));
+        for (const check of checks) {
+          const exists = await fileExists(path.join(reviewDir, check.path));
+          const icon = exists ? chalk.green('✅') : chalk.red('❌');
+          console.log(`  ${icon} ${check.name}`);
+        }
+
+        console.log(chalk.cyan('\n💡 For full AI-powered review, run without --quick\n'));
+        return;
+      }
+
+      // Full AI review
+      const configured = checkConfiguredProviders();
+      const hasProvider = configured.some(p => p.configured) || options.key;
+
+      if (!hasProvider) {
+        console.log(chalk.yellow('\n⚠️  No AI provider configured for full review.\n'));
+        console.log(chalk.white('Options:'));
+        console.log(chalk.gray('  1. Set API key: export ANTHROPIC_API_KEY=your-key'));
+        console.log(chalk.gray('  2. Use --quick for structure-only review'));
+        console.log(chalk.gray('  3. Use --key option: npx ultra-dex review --key sk-...\n'));
+        return;
+      }
+
+      const providerId = options.provider || getDefaultProvider();
+      console.log(chalk.gray(`Using provider: ${providerId}\n`));
+
+      let provider;
+      try {
+        provider = createProvider(providerId, {
+          apiKey: options.key,
+          maxTokens: 4000,
+        });
+      } catch (err) {
+        console.log(chalk.red(`Error: ${err.message}`));
+        return;
+      }
+
+      // Build file summary
+      const filesSummary = keyFiles.map(f => `### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``).join('\n\n');
+
+      spinner.start('Analyzing code against plan...');
+
+      try {
+        const result = await provider.generate(
+          SYSTEM_PROMPT,
+          generateReviewPrompt(plan.slice(0, 15000), structure, filesSummary)
+        );
+
+        spinner.succeed('Analysis complete');
+
+        // Parse the result
+        let report;
+        try {
+          // Try to extract JSON from the response
+          const jsonMatch = result.content.match(/\{[\s\S]*\}/);
+          if (jsonMatch) {
+            report = JSON.parse(jsonMatch[0]);
+          } else {
+            report = { raw: result.content };
+          }
+        } catch {
+          report = { raw: result.content };
+        }
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+          return;
+        }
+
+        // Display formatted report
+        console.log(chalk.white('\n' + '═'.repeat(60)));
+        console.log(chalk.bold.cyan('  ULTRA-DEX CODE REVIEW REPORT'));
+        console.log(chalk.white('═'.repeat(60) + '\n'));
+
+        if (report.alignmentScore !== undefined) {
+          const score = report.alignmentScore;
+          const color = score >= 80 ? chalk.green : score >= 60 ? chalk.yellow : chalk.red;
+          console.log(chalk.white('  Alignment Score: ') + color.bold(`${score}/100`));
+          console.log();
+        }
+
+        if (report.summary) {
+          console.log(chalk.white('  Summary:'));
+          console.log(chalk.gray(`  ${report.summary}\n`));
+        }
+
+        if (report.sections) {
+          console.log(chalk.white('  Section Scores:\n'));
+          for (const [section, data] of Object.entries(report.sections)) {
+            const icon = data.status === 'aligned' ? '✅' :
+                         data.status === 'deviated' ? '⚠️' : '❌';
+            const scoreColor = data.score >= 80 ? chalk.green :
+                              data.score >= 60 ? chalk.yellow : chalk.red;
+            console.log(`    ${icon} ${section.padEnd(12)} ${scoreColor(`${data.score}%`)} - ${data.notes || ''}`);
+          }
+          console.log();
+        }
+
+        if (report.criticalIssues?.length) {
+          console.log(chalk.red.bold('  ⚠️  Critical Issues:\n'));
+          report.criticalIssues.forEach((issue, i) => {
+            console.log(chalk.red(`    ${i + 1}. ${issue}`));
+          });
+          console.log();
+        }
+
+        if (report.suggestions?.length) {
+          console.log(chalk.yellow('  💡 Suggestions:\n'));
+          report.suggestions.forEach((suggestion, i) => {
+            console.log(chalk.gray(`    ${i + 1}. ${suggestion}`));
+          });
+          console.log();
+        }
+
+        if (report.nextSteps?.length) {
+          console.log(chalk.cyan('  📋 Next Steps:\n'));
+          report.nextSteps.forEach((step, i) => {
+            console.log(chalk.white(`    ${i + 1}. ${step}`));
+          });
+          console.log();
+        }
+
+        // If we couldn't parse, show raw
+        if (report.raw) {
+          console.log(chalk.white('  Analysis:\n'));
+          console.log(chalk.gray(report.raw));
+        }
+
+        console.log(chalk.white('═'.repeat(60) + '\n'));
+
+        // Cost info
+        const cost = provider.estimateCost(result.usage.inputTokens, result.usage.outputTokens);
+        console.log(chalk.gray(`  Tokens: ${result.usage.inputTokens} in / ${result.usage.outputTokens} out`));
+        console.log(chalk.gray(`  Cost: ~$${cost.total.toFixed(4)}\n`));
+
+      } catch (err) {
+        spinner.fail('Review failed');
+        console.log(chalk.red(`\nError: ${err.message}`));
+      }
+    });
+}
+
+export default { registerReviewCommand };

package/lib/commands/serve.js

@@ -0,0 +1,56 @@
+import chalk from 'chalk';
+import fs from 'fs/promises';
+import http from 'http';
+import { validateSafePath } from '../utils/validation.js';
+
+async function readFileSafe(filePath, label) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return { label, content };
+  } catch {
+    return { label, content: '' };
+  }
+}
+
+export function registerServeCommand(program) {
+  program
+    .command('serve')
+    .description('Serve Ultra-Dex context over HTTP (MCP-compatible)')
+    .option('-p, --port <port>', 'Port to listen on', '3001')
+    .action(async (options) => {
+      const port = Number.parseInt(options.port, 10);
+      if (Number.isNaN(port)) {
+        console.log(chalk.red('Invalid port. Use a numeric value.'));
+        process.exit(1);
+      }
+
+      const server = http.createServer(async (req, res) => {
+        if (!req.url || req.url === '/') {
+          res.writeHead(200, { 'Content-Type': 'text/plain' });
+          res.end('Ultra-Dex MCP Server\n');
+          return;
+        }
+
+        if (req.url === '/context') {
+          const [context, plan, quickStart] = await Promise.all([
+            readFileSafe('CONTEXT.md', 'CONTEXT.md'),
+            readFileSafe('IMPLEMENTATION-PLAN.md', 'IMPLEMENTATION-PLAN.md'),
+            readFileSafe('QUICK-START.md', 'QUICK-START.md'),
+          ]);
+
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ files: [context, plan, quickStart] }));
+          return;
+        }
+
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+      });
+
+      server.listen(port, () => {
+        console.log(chalk.green(`\n✅ Ultra-Dex MCP server running on http://localhost:${port}`));
+        console.log(chalk.gray('  GET /context -> CONTEXT.md, IMPLEMENTATION-PLAN.md, QUICK-START.md'));
+        console.log(chalk.gray('  GET / -> health check\n'));
+      });
+    });
+}