ultra-dex 1.7.3 → 2.2.0

package/lib/commands/suggest.js

@@ -0,0 +1,126 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { AGENTS } from './agents.js';
+
+export function registerSuggestCommand(program) {
+  program
+    .command('suggest')
+    .description('Get AI agent suggestions for your task')
+    .action(async () => {
+      console.log(chalk.cyan('\n🤖 Ultra-Dex Agent Suggester\n'));
+
+      const answers = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'taskType',
+          message: 'What are you trying to build?',
+          choices: [
+            'New feature from scratch',
+            'Authentication system',
+            'Payment integration',
+            'Database changes',
+            'Bug fix',
+            'Performance optimization',
+            'Deployment/DevOps',
+            'API endpoint',
+            'UI component',
+            'Testing',
+          ],
+        },
+        {
+          type: 'input',
+          name: 'description',
+          message: 'Briefly describe your task:',
+          default: '',
+        },
+      ]);
+
+      console.log(chalk.bold('\n💡 Suggested Agent Workflow:\n'));
+
+      let suggestedAgents = [];
+      let reasoning = '';
+
+      switch (answers.taskType) {
+        case 'New feature from scratch':
+          suggestedAgents = ['@Planner', '@CTO', '@Database', '@Backend', '@Frontend', '@Testing', '@Reviewer', '@DevOps'];
+          reasoning = 'Complete feature requires planning, architecture, implementation, testing, and deployment';
+          break;
+
+        case 'Authentication system':
+          suggestedAgents = ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Security', '@DevOps'];
+          reasoning = 'Auth requires research (providers), security review, and full-stack implementation';
+          break;
+
+        case 'Payment integration':
+          suggestedAgents = ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Testing', '@Security', '@DevOps'];
+          reasoning = 'Payments need provider research, webhook handling, testing, and security audit';
+          break;
+
+        case 'Database changes':
+          suggestedAgents = ['@Planner', '@CTO', '@Database', '@Backend', '@Testing'];
+          reasoning = 'Schema changes need planning, architecture review, migration, and testing';
+          break;
+
+        case 'Bug fix':
+          suggestedAgents = ['@Debugger', '@Testing', '@Reviewer'];
+          reasoning = 'Debug issue, add test to prevent regression, review fix';
+          break;
+
+        case 'Performance optimization':
+          suggestedAgents = ['@Performance', '@Backend', '@Frontend', '@Database', '@Testing'];
+          reasoning = 'Identify bottlenecks, optimize code/queries, verify improvements';
+          break;
+
+        case 'Deployment/DevOps':
+          suggestedAgents = ['@DevOps', '@CTO', '@Security'];
+          reasoning = 'Infrastructure setup with security review';
+          break;
+
+        case 'API endpoint':
+          suggestedAgents = ['@Backend', '@Database', '@Testing', '@Reviewer'];
+          reasoning = 'Implement endpoint, add tests, review code quality';
+          break;
+
+        case 'UI component':
+          suggestedAgents = ['@Frontend', '@Reviewer'];
+          reasoning = 'Build component, review for quality and accessibility';
+          break;
+
+        case 'Testing':
+          suggestedAgents = ['@Testing', '@Reviewer'];
+          reasoning = 'Write tests, review coverage';
+          break;
+
+        default:
+          suggestedAgents = ['@Planner', '@CTO'];
+          reasoning = 'Start with planning and architecture review';
+      }
+
+      console.log(chalk.gray(reasoning + '\n'));
+
+      suggestedAgents.forEach((agent, i) => {
+        const agentName = agent.replace('@', '').toLowerCase();
+        const agentInfo = AGENTS.find(a => a.name === agentName);
+        const arrow = i < suggestedAgents.length - 1 ? '  →' : '';
+        console.log(chalk.cyan(`  ${i + 1}. ${agent}`) + chalk.gray(` - ${agentInfo?.description || ''}`) + arrow);
+      });
+
+      console.log(chalk.bold('\n📚 Next Steps:\n'));
+      console.log(chalk.gray(`  1. Start with ${suggestedAgents[0]} to plan the task`));
+      console.log(chalk.gray('  2. Hand off to each agent in sequence'));
+      console.log(chalk.gray('  3. Use "ultra-dex agent <name>" to see full prompts\n'));
+
+      console.log(chalk.bold('🔗 Related Workflows:\n'));
+      if (answers.taskType === 'Authentication system') {
+        console.log(chalk.blue('  ultra-dex workflow auth'));
+        console.log(chalk.blue('  ultra-dex workflow supabase\n'));
+      } else if (answers.taskType === 'Payment integration') {
+        console.log(chalk.blue('  ultra-dex workflow payments\n'));
+      } else if (answers.taskType === 'Deployment/DevOps') {
+        console.log(chalk.blue('  ultra-dex workflow vercel'));
+        console.log(chalk.blue('  ultra-dex workflow cicd\n'));
+      } else {
+        console.log(chalk.gray('  Use "ultra-dex workflow <feature>" to see examples\n'));
+      }
+    });
+}

package/lib/commands/validate.js

@@ -0,0 +1,140 @@
+import chalk from 'chalk';
+import fs from 'fs/promises';
+import path from 'path';
+import { validateSafePath } from '../utils/validation.js';
+
+export function registerValidateCommand(program) {
+  program
+    .command('validate')
+    .description('Validate project structure against Ultra-Dex standards')
+    .option('-d, --dir <directory>', 'Project directory to validate', '.')
+    .action(async (options) => {
+      console.log(chalk.cyan('\n✅ Ultra-Dex Structure Validator\n'));
+
+      const dirValidation = validateSafePath(options.dir, 'Project directory');
+      if (dirValidation !== true) {
+        console.log(chalk.red(dirValidation));
+        process.exit(1);
+      }
+
+      const projectDir = path.resolve(options.dir);
+      let passed = 0;
+      let failed = 0;
+      const warnings = [];
+
+      async function checkExists(itemPath, type = 'file') {
+        try {
+          const stats = await fs.stat(path.join(projectDir, itemPath));
+          if (type === 'file' && stats.isFile()) return true;
+          if (type === 'dir' && stats.isDirectory()) return true;
+          return false;
+        } catch {
+          return false;
+        }
+      }
+
+      console.log(chalk.bold('Checking required files...\n'));
+
+      const coreFiles = [
+        { path: 'QUICK-START.md', required: true },
+        { path: 'IMPLEMENTATION-PLAN.md', required: true },
+        { path: 'CONTEXT.md', required: false },
+        { path: 'README.md', required: false },
+      ];
+
+      for (const file of coreFiles) {
+        const exists = await checkExists(file.path);
+        if (exists) {
+          passed++;
+          console.log(chalk.green(`  ✅ ${file.path}`));
+        } else if (file.required) {
+          failed++;
+          console.log(chalk.red(`  ❌ ${file.path} (required)`));
+        } else {
+          warnings.push(file.path);
+          console.log(chalk.yellow(`  ⚠️  ${file.path} (recommended)`));
+        }
+      }
+
+      console.log(chalk.bold('\nChecking directory structure...\n'));
+
+      const directories = [
+        { path: 'docs', required: false },
+        { path: '.agents', required: false },
+        { path: '.cursor/rules', required: false },
+      ];
+
+      for (const dir of directories) {
+        const exists = await checkExists(dir.path, 'dir');
+        if (exists) {
+          passed++;
+          console.log(chalk.green(`  ✅ ${dir.path}/`));
+        } else {
+          warnings.push(dir.path);
+          console.log(chalk.yellow(`  ⚠️  ${dir.path}/ (optional)`));
+        }
+      }
+
+      console.log(chalk.bold('\nValidating content quality...\n'));
+
+      try {
+        const quickStart = await fs.readFile(path.join(projectDir, 'QUICK-START.md'), 'utf-8');
+
+        const sections = ['idea', 'problem', 'feature', 'tech stack', 'tasks'];
+        let sectionsFound = 0;
+
+        sections.forEach(section => {
+          if (quickStart.toLowerCase().includes(section)) {
+            sectionsFound++;
+          }
+        });
+
+        if (sectionsFound >= 4) {
+          passed++;
+          console.log(chalk.green(`  ✅ QUICK-START.md has ${sectionsFound}/${sections.length} key sections`));
+        } else {
+          failed++;
+          console.log(chalk.red(`  ❌ QUICK-START.md missing key sections (${sectionsFound}/${sections.length})`));
+        }
+      } catch {
+        console.log(chalk.gray('  ⊘  Could not validate QUICK-START.md content'));
+      }
+
+      try {
+        const implPlan = await fs.readFile(path.join(projectDir, 'IMPLEMENTATION-PLAN.md'), 'utf-8');
+
+        if (implPlan.length > 500) {
+          passed++;
+          console.log(chalk.green('  ✅ IMPLEMENTATION-PLAN.md has substantial content'));
+        } else {
+          warnings.push('IMPLEMENTATION-PLAN.md needs more detail');
+          console.log(chalk.yellow(`  ⚠️  IMPLEMENTATION-PLAN.md is sparse (${implPlan.length} chars)`));
+        }
+      } catch {
+        console.log(chalk.gray('  ⊘  Could not validate IMPLEMENTATION-PLAN.md content'));
+      }
+
+      console.log('\n' + chalk.bold('─'.repeat(50)));
+      console.log(chalk.bold('\nValidation Summary:\n'));
+      console.log(chalk.green(`  ✅ Passed: ${passed}`));
+      console.log(chalk.red(`  ❌ Failed: ${failed}`));
+      console.log(chalk.yellow(`  ⚠️  Warnings: ${warnings.length}`));
+
+      if (failed === 0) {
+        console.log(chalk.bold.green('\n✅ VALIDATION PASSED\n'));
+        console.log(chalk.gray('Your project structure follows Ultra-Dex standards.'));
+      } else {
+        console.log(chalk.bold.yellow('\n⚠️  VALIDATION INCOMPLETE\n'));
+        console.log(chalk.gray('Fix required files to meet Ultra-Dex standards.'));
+      }
+
+      if (warnings.length > 0) {
+        console.log(chalk.bold('\n💡 Recommendations:\n'));
+        warnings.slice(0, 3).forEach(w => {
+          console.log(chalk.cyan(`  → Consider adding ${w}`));
+        });
+      }
+
+      console.log('\n' + chalk.gray('Run "ultra-dex init" to set up a proper Ultra-Dex project.\n'));
+    });
+}

package/lib/commands/workflows.js

@@ -0,0 +1,185 @@
+import chalk from 'chalk';
+import { githubBlobUrl } from '../config/urls.js';
+
+export const WORKFLOWS = {
+  auth: {
+    name: 'Authentication',
+    agents: ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Security', '@DevOps'],
+    description: 'Complete authentication with email/password and OAuth',
+    example: 'supabase',
+  },
+  supabase: {
+    name: 'Supabase Authentication Setup',
+    agents: ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Security', '@DevOps'],
+    description: 'Set up Supabase auth with RLS policies',
+    steps: [
+      '1. Create Supabase project and get API keys',
+      '2. Set up database schema with RLS policies',
+      '3. Configure authentication providers (email + Google OAuth)',
+      '4. Implement backend auth middleware',
+      '5. Build frontend auth UI components',
+      '6. Test authentication flow',
+    ],
+  },
+  payments: {
+    name: 'Payment Integration (Stripe)',
+    agents: ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@Frontend', '@Testing', '@Security', '@DevOps'],
+    description: 'Integrate Stripe for subscriptions and one-time payments',
+    steps: [
+      '1. Create Stripe account and get API keys',
+      '2. Design subscription/payment schema',
+      '3. Implement Stripe Checkout API',
+      '4. Handle webhooks for payment events',
+      '5. Build payment UI with checkout flow',
+      '6. Test with Stripe test cards',
+    ],
+  },
+  deployment: {
+    name: 'Deployment Pipeline',
+    agents: ['@Planner', '@CTO', '@Frontend', '@DevOps'],
+    description: 'Deploy to Vercel with staging and production environments',
+    example: 'vercel',
+  },
+  vercel: {
+    name: 'Vercel Deployment Pipeline',
+    agents: ['@Planner', '@CTO', '@Frontend', '@DevOps'],
+    description: 'Deploy Next.js app to Vercel',
+    steps: [
+      '1. Set up Vercel project and link Git repository',
+      '2. Configure environment variables for staging/production',
+      '3. Set up custom domain',
+      '4. Configure preview deployments for PRs',
+      '5. Set up deployment protection rules',
+      '6. Test deployment pipeline',
+    ],
+  },
+  cicd: {
+    name: 'GitHub Actions CI/CD',
+    agents: ['@Planner', '@CTO', '@Testing', '@DevOps'],
+    description: 'Automated testing and deployment with GitHub Actions',
+    steps: [
+      '1. Create workflow file for CI (tests + lint)',
+      '2. Add build verification job',
+      '3. Add deployment job for production',
+      '4. Configure secrets for deployment',
+      '5. Add status badges to README',
+      '6. Test workflow on PR',
+    ],
+  },
+  database: {
+    name: 'Database Migration',
+    agents: ['@Planner', '@CTO', '@Database', '@Backend', '@Testing'],
+    description: 'Database schema migration and data sync',
+    steps: [
+      '1. Design new schema changes',
+      '2. Write migration scripts',
+      '3. Test migrations in staging',
+      '4. Back up production database',
+      '5. Run migrations in production',
+      '6. Verify data integrity',
+    ],
+  },
+  email: {
+    name: 'Email Notification System',
+    agents: ['@Planner', '@Research', '@CTO', '@Backend', '@Frontend', '@Testing'],
+    description: 'Transactional emails with templates',
+    steps: [
+      '1. Choose email service (Resend, SendGrid)',
+      '2. Set up email templates',
+      '3. Implement email API endpoints',
+      '4. Add email queue for async sending',
+      '5. Test email delivery',
+      '6. Monitor deliverability',
+    ],
+  },
+  realtime: {
+    name: 'Real-Time Features',
+    agents: ['@Planner', '@CTO', '@Backend', '@Frontend', '@Testing'],
+    description: 'Live notifications with WebSockets',
+    steps: [
+      '1. Choose WebSocket library (Socket.io, Pusher)',
+      '2. Set up WebSocket server',
+      '3. Implement event broadcasting',
+      '4. Build frontend listeners',
+      '5. Test real-time updates',
+      '6. Handle reconnection logic',
+    ],
+  },
+  sentry: {
+    name: 'Sentry Error Tracking',
+    agents: ['@Planner', '@Research', '@CTO', '@Backend', '@Frontend', '@DevOps'],
+    description: 'Error monitoring with Sentry',
+    steps: [
+      '1. Create Sentry account and project',
+      '2. Install Sentry SDKs for frontend and backend',
+      '3. Configure error boundaries for React',
+      '4. Set up source maps for debugging',
+      '5. Configure alerts and notifications',
+      '6. Test error capture in development',
+    ],
+  },
+  shopify: {
+    name: 'Shopify Product Integration',
+    agents: ['@Planner', '@Research', '@CTO', '@Database', '@Backend', '@DevOps'],
+    description: 'Sync products from Shopify store',
+    steps: [
+      '1. Create Shopify Partner account and development store',
+      '2. Set up Shopify app with Admin API access',
+      '3. Design database schema for products',
+      '4. Build product sync endpoint',
+      '5. Implement webhook handlers for product updates',
+      '6. Schedule full product sync (cron job)',
+    ],
+  },
+  analytics: {
+    name: 'PostHog Analytics Integration',
+    agents: ['@Planner', '@Research', '@CTO', '@Backend', '@Frontend', '@DevOps'],
+    description: 'Track user behavior with PostHog',
+    steps: [
+      '1. Create PostHog account and project',
+      '2. Install PostHog SDKs for frontend and backend',
+      '3. Set up core event tracking (signup, login, feature usage)',
+      '4. Create conversion funnel dashboard',
+      '5. Set up feature flags (optional)',
+      '6. Configure user identification',
+    ],
+  },
+};
+
+export function registerWorkflowCommand(program) {
+  program
+    .command('workflow <feature>')
+    .description('Show workflow for common features (auth, payments, deployment, etc.)')
+    .action((feature) => {
+      const workflow = WORKFLOWS[feature.toLowerCase()];
+
+      if (!workflow) {
+        console.log(chalk.red(`\n❌ Workflow "${feature}" not found.\n`));
+        console.log(chalk.gray('Available workflows:'));
+        Object.keys(WORKFLOWS).forEach(key => {
+          console.log(chalk.cyan(`  - ${key}`) + chalk.gray(` (${WORKFLOWS[key].name})`));
+        });
+        console.log('\n' + chalk.gray('Usage: ultra-dex workflow <feature>\n'));
+        process.exit(1);
+      }
+
+      console.log(chalk.bold(`\n📋 ${workflow.name} Workflow\n`));
+      console.log(chalk.gray(workflow.description));
+
+      console.log(chalk.bold('\n🤖 Agents Involved:\n'));
+      workflow.agents.forEach((agent, i) => {
+        console.log(chalk.cyan(`  ${i + 1}. ${agent}`));
+      });
+
+      if (workflow.steps) {
+        console.log(chalk.bold('\n📝 Implementation Steps:\n'));
+        workflow.steps.forEach(step => {
+          console.log(chalk.gray(`  ${step}`));
+        });
+      }
+
+      console.log(chalk.bold('\n📚 Full Example:\n'));
+      console.log(chalk.blue(`  ${githubBlobUrl('guides/ADVANCED-WORKFLOWS.md')}`));
+      console.log(chalk.gray(`  (Search for "Example: ${workflow.name}")\n`));
+    });
+}

package/lib/config/paths.js

@@ -0,0 +1,9 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const ASSETS_ROOT = path.resolve(__dirname, '../../assets');
+export const ROOT_FALLBACK = path.resolve(__dirname, '../../../');
+export const LIVE_TEMPLATES_ROOT = path.join(ASSETS_ROOT, 'live-templates');

package/lib/config/urls.js

@@ -0,0 +1,16 @@
+export const GITHUB_REPO = 'Srujan0798/Ultra-Dex';
+export const GITHUB_WEB_BASE = `https://github.com/${GITHUB_REPO}`;
+export const GITHUB_RAW_BASE = `https://raw.githubusercontent.com/${GITHUB_REPO}/main`;
+
+export function githubBlobUrl(pathname) {
+  return `${GITHUB_WEB_BASE}/blob/main/${pathname}`;
+}
+
+export function githubTreeUrl(pathname) {
+  return `${GITHUB_WEB_BASE}/tree/main/${pathname}`;
+}
+
+export function githubWebUrl(pathname = '') {
+  if (!pathname) return GITHUB_WEB_BASE;
+  return `${GITHUB_WEB_BASE}/${pathname}`;
+}

package/lib/providers/base.js

@@ -0,0 +1,82 @@
+/**
+ * Base AI Provider Interface
+ * All providers (Claude, OpenAI, Gemini) must implement this interface
+ */
+
+export class BaseProvider {
+  constructor(apiKey, options = {}) {
+    if (new.target === BaseProvider) {
+      throw new Error('BaseProvider is abstract and cannot be instantiated directly');
+    }
+    this.apiKey = apiKey;
+    this.model = options.model || this.getDefaultModel();
+    this.maxTokens = options.maxTokens || 8192;
+  }
+
+  /**
+   * Get the default model for this provider
+   * @returns {string} Default model identifier
+   */
+  getDefaultModel() {
+    throw new Error('getDefaultModel() must be implemented by subclass');
+  }
+
+  /**
+   * Get available models for this provider
+   * @returns {Array<{id: string, name: string, maxTokens: number}>}
+   */
+  getAvailableModels() {
+    throw new Error('getAvailableModels() must be implemented by subclass');
+  }
+
+  /**
+   * Estimate the cost for a given number of tokens
+   * @param {number} inputTokens - Number of input tokens
+   * @param {number} outputTokens - Number of output tokens
+   * @returns {{input: number, output: number, total: number}} Cost in USD
+   */
+  estimateCost(inputTokens, outputTokens) {
+    throw new Error('estimateCost() must be implemented by subclass');
+  }
+
+  /**
+   * Generate a completion from the AI model
+   * @param {string} systemPrompt - System instructions
+   * @param {string} userPrompt - User message/request
+   * @param {Object} options - Additional options
+   * @returns {Promise<{content: string, usage: {inputTokens: number, outputTokens: number}}>}
+   */
+  async generate(systemPrompt, userPrompt, options = {}) {
+    throw new Error('generate() must be implemented by subclass');
+  }
+
+  /**
+   * Generate a completion with streaming support
+   * @param {string} systemPrompt - System instructions
+   * @param {string} userPrompt - User message/request
+   * @param {Function} onChunk - Callback for each chunk: (text: string) => void
+   * @param {Object} options - Additional options
+   * @returns {Promise<{content: string, usage: {inputTokens: number, outputTokens: number}}>}
+   */
+  async generateStream(systemPrompt, userPrompt, onChunk, options = {}) {
+    throw new Error('generateStream() must be implemented by subclass');
+  }
+
+  /**
+   * Validate that the API key is configured and working
+   * @returns {Promise<boolean>}
+   */
+  async validateApiKey() {
+    throw new Error('validateApiKey() must be implemented by subclass');
+  }
+
+  /**
+   * Get the provider name
+   * @returns {string}
+   */
+  getName() {
+    throw new Error('getName() must be implemented by subclass');
+  }
+}
+
+export default BaseProvider;