ultra-dex 1.7.3 → 2.2.0

package/lib/templates/quick-start.js

@@ -0,0 +1,43 @@
+export const QUICK_START_TEMPLATE = `# {{PROJECT_NAME}} - Quick Start
+
+## 1. Your Idea (2 sentences max)
+
+**What:** {{IDEA_WHAT}}
+**For whom:** {{IDEA_FOR}}
+
+## 2. The Problem (3 bullets)
+
+- {{PROBLEM_1}}
+- {{PROBLEM_2}}
+- {{PROBLEM_3}}
+
+## 3. Core Production Features (5 max)
+
+| Feature | Priority | Justification |
+|---------|----------|---------------|
+| {{FEATURE_1}} | P0 | |
+| | P0 | |
+| | P1 | |
+| | P1 | |
+| | P2 | |
+
+## 4. Tech Stack
+
+| Layer | Your Choice |
+|-------|-------------|
+| Frontend | {{FRONTEND}} |
+| Database | {{DATABASE}} |
+| Auth | {{AUTH}} |
+| Payments | {{PAYMENTS}} |
+| Hosting | {{HOSTING}} |
+
+## 5. First 3 Tasks
+
+1. [ ] Set up project with chosen stack
+2. [ ] Implement core feature #1
+3. [ ] Deploy to staging
+
+---
+
+**Next:** Fill out the full implementation plan using the Ultra-Dex template.
+`;

package/lib/utils/build-helpers.js

@@ -0,0 +1,257 @@
+/**
+ * Build Command Utilities
+ * Helpers for the AI-assisted build workflow
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Load implementation plan from current directory
+ * @param {string} dir - Directory to search
+ * @returns {Promise<{content: string, path: string}|null>}
+ */
+export async function loadImplementationPlan(dir = '.') {
+  const possibleNames = [
+    'IMPLEMENTATION-PLAN.md',
+    'implementation-plan.md',
+    'PLAN.md',
+    'plan.md',
+  ];
+
+  for (const name of possibleNames) {
+    const filePath = path.join(dir, name);
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      return { content, path: filePath };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Load context file
+ * @param {string} dir - Directory to search
+ * @returns {Promise<string|null>}
+ */
+export async function loadContext(dir = '.') {
+  const possibleNames = ['CONTEXT.md', 'context.md'];
+  
+  for (const name of possibleNames) {
+    try {
+      return await fs.readFile(path.join(dir, name), 'utf-8');
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract tasks from implementation plan
+ * @param {string} planContent - Implementation plan content
+ * @returns {Array<{id: string, title: string, section: number, status: string}>}
+ */
+export function extractTasks(planContent) {
+  const tasks = [];
+  
+  // Match task patterns: - [ ] Task name or - [x] Task name
+  const taskRegex = /- \[([ x])\]\s*(.+?)(?=\n|$)/gi;
+  let match;
+  let currentSection = 0;
+  
+  // Track current section
+  const lines = planContent.split('\n');
+  let lineIndex = 0;
+  
+  for (const line of lines) {
+    const sectionMatch = line.match(/## SECTION (\d+):/i);
+    if (sectionMatch) {
+      currentSection = parseInt(sectionMatch[1], 10);
+    }
+    
+    const taskMatch = line.match(/- \[([ x])\]\s*(.+)/i);
+    if (taskMatch) {
+      tasks.push({
+        id: `task-${tasks.length + 1}`,
+        title: taskMatch[2].trim(),
+        section: currentSection,
+        status: taskMatch[1] === 'x' ? 'complete' : 'pending',
+        line: lineIndex,
+      });
+    }
+    lineIndex++;
+  }
+  
+  return tasks;
+}
+
+/**
+ * Extract atomic tasks (4-9 hour tasks) from Section 16
+ * @param {string} planContent - Implementation plan content
+ * @returns {Array<{id: string, title: string, estimate: string, dependencies: string[]}>}
+ */
+export function extractAtomicTasks(planContent) {
+  const tasks = [];
+  
+  // Find Section 16 content
+  const section16Match = planContent.match(/## SECTION 16:.*?(?=## SECTION 17:|$)/is);
+  if (!section16Match) return tasks;
+  
+  const section16 = section16Match[0];
+  
+  // Match task patterns with estimates
+  // e.g., "1. Setup project structure (4h)" or "- [ ] Configure database (6-8h)"
+  const taskPatterns = [
+    /(?:^|\n)\d+\.\s*(.+?)\s*\((\d+(?:-\d+)?h?)\)/gi,
+    /- \[[ x]\]\s*(.+?)\s*\((\d+(?:-\d+)?h?)\)/gi,
+    /\|\s*(.+?)\s*\|\s*(\d+(?:-\d+)?\s*h(?:ours?)?)\s*\|/gi,
+  ];
+  
+  for (const pattern of taskPatterns) {
+    let match;
+    while ((match = pattern.exec(section16)) !== null) {
+      tasks.push({
+        id: `atomic-${tasks.length + 1}`,
+        title: match[1].trim(),
+        estimate: match[2].trim(),
+        dependencies: [],
+      });
+    }
+  }
+  
+  return tasks;
+}
+
+/**
+ * Get pending tasks only
+ * @param {Array} tasks - All tasks
+ * @returns {Array} Pending tasks
+ */
+export function getPendingTasks(tasks) {
+  return tasks.filter(t => t.status === 'pending');
+}
+
+/**
+ * Group tasks by section
+ * @param {Array} tasks - All tasks
+ * @returns {Map<number, Array>} Tasks grouped by section number
+ */
+export function groupTasksBySection(tasks) {
+  const grouped = new Map();
+  
+  for (const task of tasks) {
+    if (!grouped.has(task.section)) {
+      grouped.set(task.section, []);
+    }
+    grouped.get(task.section).push(task);
+  }
+  
+  return grouped;
+}
+
+/**
+ * Format context for AI agent
+ * @param {Object} options
+ * @returns {string} Formatted context
+ */
+export function formatAgentContext({ plan, context, task, section }) {
+  let formatted = `# Project Context\n\n`;
+  
+  if (context) {
+    formatted += `## Overview\n\n${context}\n\n`;
+  }
+  
+  if (task) {
+    formatted += `## Current Task\n\n**${task.title}**\n`;
+    if (task.estimate) {
+      formatted += `- Estimated time: ${task.estimate}\n`;
+    }
+    if (task.section) {
+      formatted += `- From Section ${task.section}\n`;
+    }
+    formatted += '\n';
+  }
+  
+  if (section && plan) {
+    const sectionContent = extractSection(plan, section);
+    if (sectionContent) {
+      formatted += `## Relevant Section\n\n${sectionContent}\n\n`;
+    }
+  }
+  
+  formatted += `## Instructions\n\n`;
+  formatted += `1. Focus on completing the current task\n`;
+  formatted += `2. Follow the implementation plan specifications\n`;
+  formatted += `3. Write production-ready code with tests\n`;
+  formatted += `4. Document any deviations from the plan\n`;
+  
+  return formatted;
+}
+
+/**
+ * Extract a specific section from the plan
+ * @param {string} planContent - Full plan content
+ * @param {number} sectionNum - Section number (1-34)
+ * @returns {string|null}
+ */
+export function extractSection(planContent, sectionNum) {
+  const nextSection = sectionNum < 34 ? `## SECTION ${sectionNum + 1}:` : '═══════════════';
+  const regex = new RegExp(`(## SECTION ${sectionNum}:.*?)(?=${nextSection}|$)`, 'is');
+  const match = planContent.match(regex);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Get section titles
+ */
+export const SECTION_TITLES = {
+  1: 'High-Level Summary',
+  2: 'Core Features',
+  3: 'User Stories',
+  4: 'User Personas',
+  5: 'Competitive Analysis',
+  6: 'Screen Map',
+  7: 'Wireframes',
+  8: 'Design System',
+  9: 'UI/UX Specifications',
+  10: 'Data Model',
+  11: 'API Blueprint',
+  12: 'System Architecture',
+  13: 'Authentication & Authorization',
+  14: 'Payment Integration',
+  15: 'Tech Stack',
+  16: 'Implementation Plan',
+  17: 'Timeline',
+  18: 'Risk Assessment',
+  19: 'Deployment Plan',
+  20: 'Testing Strategy',
+  21: 'Security Guidelines',
+  22: 'Performance Requirements',
+  23: 'Monitoring & Logging',
+  24: 'Maintenance Plan',
+  25: 'Documentation',
+  26: 'Analytics',
+  27: 'Error Handling',
+  28: 'Legal & Compliance',
+  29: 'SEO',
+  30: 'Internationalization',
+  31: 'Accessibility',
+  32: 'Feature Flags',
+  33: 'AI/ML Integration',
+  34: 'Future Roadmap',
+};
+
+export default {
+  loadImplementationPlan,
+  loadContext,
+  extractTasks,
+  extractAtomicTasks,
+  getPendingTasks,
+  groupTasksBySection,
+  formatAgentContext,
+  extractSection,
+  SECTION_TITLES,
+};

package/lib/utils/fallback.js

@@ -0,0 +1,36 @@
+import fs from 'fs/promises';
+
+export async function readWithFallback(primaryPath, fallbackPath, encoding = 'utf-8') {
+  try {
+    return await fs.readFile(primaryPath, encoding);
+  } catch (primaryError) {
+    if (!fallbackPath) {
+      throw primaryError;
+    }
+    return await fs.readFile(fallbackPath, encoding);
+  }
+}
+
+export async function copyWithFallback(primaryPath, fallbackPath, destinationPath) {
+  try {
+    await fs.copyFile(primaryPath, destinationPath);
+    return 'primary';
+  } catch (primaryError) {
+    if (!fallbackPath) {
+      throw primaryError;
+    }
+    await fs.copyFile(fallbackPath, destinationPath);
+    return 'fallback';
+  }
+}
+
+export async function listWithFallback(primaryPath, fallbackPath) {
+  try {
+    return await fs.readdir(primaryPath);
+  } catch (primaryError) {
+    if (!fallbackPath) {
+      throw primaryError;
+    }
+    return await fs.readdir(fallbackPath);
+  }
+}

package/lib/utils/files.js

@@ -0,0 +1,67 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function readFileSafe(filePath, label = '') {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return { label, content };
+  } catch (err) {
+    return { label, content: '' };
+  }
+}
+
+export async function pathExists(targetPath, type = 'file') {
+  try {
+    const stats = await fs.stat(targetPath);
+    if (type === 'file') return stats.isFile();
+    if (type === 'dir') return stats.isDirectory();
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export async function copyWithFallback({ primary, fallback, destination, onPrimaryMissing }) {
+  try {
+    await fs.copyFile(primary, destination);
+    return 'primary';
+  } catch (primaryError) {
+    if (onPrimaryMissing) {
+      onPrimaryMissing(primaryError);
+    }
+    if (!fallback) {
+      throw primaryError;
+    }
+    await fs.copyFile(fallback, destination);
+    return 'fallback';
+  }
+}
+
+export async function readWithFallback({ primary, fallback, encoding = 'utf-8' }) {
+  try {
+    return await fs.readFile(primary, encoding);
+  } catch (primaryError) {
+    if (!fallback) {
+      throw primaryError;
+    }
+    return await fs.readFile(fallback, encoding);
+  }
+}
+
+export function resolveAssetPath(basePath, relativePath) {
+  return path.join(basePath, relativePath);
+}
+
+export async function copyDirectory(srcDir, destDir) {
+  await fs.mkdir(destDir, { recursive: true });
+  const entries = await fs.readdir(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(srcPath, destPath);
+    } else if (entry.isFile()) {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}

package/lib/utils/network.js

@@ -0,0 +1,18 @@
+export async function fetchWithRetry(url, options = {}, retries = 2, delayMs = 400) {
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const response = await fetch(url, options);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      return response;
+    } catch (err) {
+      lastError = err;
+      if (attempt < retries) {
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+  throw lastError;
+}

package/lib/utils/output.js

@@ -0,0 +1,20 @@
+import chalk from 'chalk';
+
+export function printError(message, err) {
+  console.log(chalk.red(message));
+  if (err?.message) {
+    console.log(chalk.gray(`  → ${err.message}`));
+  }
+}
+
+export function printWarning(message) {
+  console.log(chalk.yellow(message));
+}
+
+export function printInfo(message) {
+  console.log(chalk.cyan(message));
+}
+
+export function printSuccess(message) {
+  console.log(chalk.green(message));
+}

package/lib/utils/parser.js

@@ -0,0 +1,155 @@
+/**
+ * Parser Utility
+ * Parses AI responses into structured output
+ */
+
+/**
+ * Extract project name from implementation plan
+ * @param {string} content - Generated implementation plan
+ * @returns {string} Project name
+ */
+export function extractProjectName(content) {
+  // Try to find PROJECT: line
+  const projectMatch = content.match(/PROJECT:\s*(.+)/i);
+  if (projectMatch) {
+    return projectMatch[1].trim();
+  }
+  
+  // Try to find product name in Section 1
+  const productMatch = content.match(/Product Vision.*?:\s*(.+?)(?:\.|$)/im);
+  if (productMatch) {
+    return productMatch[1].trim().slice(0, 50);
+  }
+  
+  return 'My SaaS Project';
+}
+
+/**
+ * Extract summary from implementation plan
+ * @param {string} content - Generated implementation plan
+ * @returns {string} Brief summary
+ */
+export function extractSummary(content) {
+  // Find Section 1.1 or Problem Statement
+  const visionMatch = content.match(/### 1\.1 Product Vision.*?\n(.+?)(?=\n###|\n##|$)/is);
+  if (visionMatch) {
+    return visionMatch[1].trim().slice(0, 200);
+  }
+  
+  const problemMatch = content.match(/### 1\.2 Problem Statement.*?\n(.+?)(?=\n###|\n##|$)/is);
+  if (problemMatch) {
+    return problemMatch[1].trim().slice(0, 200);
+  }
+  
+  return 'A SaaS application';
+}
+
+/**
+ * Extract tech stack from implementation plan
+ * @param {string} content - Generated implementation plan
+ * @returns {Object} Tech stack details
+ */
+export function extractTechStack(content) {
+  const defaults = {
+    frontend: 'Next.js + TypeScript',
+    backend: 'Next.js API Routes',
+    database: 'PostgreSQL + Prisma',
+    auth: 'NextAuth.js',
+    payments: 'Stripe',
+    hosting: 'Vercel',
+  };
+  
+  // Try to find tech stack section
+  const stackSection = content.match(/## SECTION 15.*?(?=## SECTION 16|$)/is);
+  if (!stackSection) return defaults;
+  
+  const text = stackSection[0];
+  
+  // Extract each layer
+  const frontendMatch = text.match(/Frontend.*?:\s*(.+?)(?=\n|$)/i);
+  const backendMatch = text.match(/Backend.*?:\s*(.+?)(?=\n|$)/i);
+  const databaseMatch = text.match(/Database.*?:\s*(.+?)(?=\n|$)/i);
+  
+  return {
+    frontend: frontendMatch?.[1]?.trim() || defaults.frontend,
+    backend: backendMatch?.[1]?.trim() || defaults.backend,
+    database: databaseMatch?.[1]?.trim() || defaults.database,
+    auth: defaults.auth,
+    payments: defaults.payments,
+    hosting: defaults.hosting,
+  };
+}
+
+/**
+ * Validate implementation plan completeness
+ * @param {string} content - Generated implementation plan
+ * @returns {{complete: boolean, missingSections: number[], percentage: number}}
+ */
+export function validateCompleteness(content) {
+  const missingSections = [];
+  
+  for (let i = 1; i <= 34; i++) {
+    const regex = new RegExp(`## SECTION ${i}:`, 'i');
+    if (!regex.test(content)) {
+      missingSections.push(i);
+    }
+  }
+  
+  const percentage = Math.round(((34 - missingSections.length) / 34) * 100);
+  
+  return {
+    complete: missingSections.length === 0,
+    missingSections,
+    percentage,
+  };
+}
+
+/**
+ * Split content into sections
+ * @param {string} content - Generated implementation plan
+ * @returns {Map<number, string>} Map of section number to content
+ */
+export function splitIntoSections(content) {
+  const sections = new Map();
+  
+  for (let i = 1; i <= 34; i++) {
+    const nextSection = i < 34 ? `## SECTION ${i + 1}:` : '═══════════════';
+    const regex = new RegExp(`(## SECTION ${i}:.*?)(?=${nextSection}|$)`, 'is');
+    const match = content.match(regex);
+    
+    if (match) {
+      sections.set(i, match[1].trim());
+    }
+  }
+  
+  return sections;
+}
+
+/**
+ * Format token usage for display
+ * @param {{inputTokens: number, outputTokens: number}} usage
+ * @returns {string}
+ */
+export function formatUsage(usage) {
+  const total = usage.inputTokens + usage.outputTokens;
+  return `${total.toLocaleString()} tokens (${usage.inputTokens.toLocaleString()} in / ${usage.outputTokens.toLocaleString()} out)`;
+}
+
+/**
+ * Format cost for display
+ * @param {{input: number, output: number, total: number}} cost
+ * @returns {string}
+ */
+export function formatCost(cost) {
+  return `$${cost.total.toFixed(4)} (input: $${cost.input.toFixed(4)}, output: $${cost.output.toFixed(4)})`;
+}
+
+export default {
+  extractProjectName,
+  extractSummary,
+  extractTechStack,
+  validateCompleteness,
+  splitIntoSections,
+  formatUsage,
+  formatCost,
+};

package/lib/utils/prompt-builder.js

@@ -0,0 +1,93 @@
+/**
+ * Prompt Builder Utility
+ * Assembles prompts for the AI providers
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { USER_PROMPT_TEMPLATE, QUICK_START_PROMPT, CONTEXT_PROMPT } from '../templates/prompts/section-prompts.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Load the system prompt from file
+ * @returns {Promise<string>}
+ */
+export async function loadSystemPrompt() {
+  const promptPath = path.join(__dirname, '../templates/prompts/system-prompt.md');
+  try {
+    return await fs.readFile(promptPath, 'utf-8');
+  } catch {
+    // Fallback embedded prompt if file not found
+    return `You are an expert SaaS architect. Generate a comprehensive 34-section implementation plan.
+Be specific, production-ready, and thorough. Include code examples, time estimates, and realistic constraints.`;
+  }
+}
+
+/**
+ * Build the user prompt for implementation plan generation
+ * @param {string} idea - The user's SaaS idea
+ * @returns {string}
+ */
+export function buildImplementationPrompt(idea) {
+  return USER_PROMPT_TEMPLATE.replace(/\{\{IDEA\}\}/g, idea);
+}
+
+/**
+ * Build the prompt for QUICK-START.md generation
+ * @returns {string}
+ */
+export function buildQuickStartPrompt() {
+  return QUICK_START_PROMPT;
+}
+
+/**
+ * Build the prompt for CONTEXT.md generation
+ * @returns {string}
+ */
+export function buildContextPrompt() {
+  return CONTEXT_PROMPT;
+}
+
+/**
+ * Estimate token count for a string (rough approximation)
+ * @param {string} text - Text to estimate
+ * @returns {number} Estimated token count
+ */
+export function estimateTokens(text) {
+  // Rough approximation: ~4 characters per token
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Calculate estimated cost for generation
+ * @param {Object} provider - AI provider instance
+ * @param {string} idea - User's idea
+ * @returns {{inputTokens: number, outputTokens: number, cost: Object}}
+ */
+export function estimateGenerationCost(provider, idea) {
+  // Estimate input: system prompt (~600 tokens) + user prompt (~2000 tokens) + idea
+  const inputTokens = 2600 + estimateTokens(idea);
+  
+  // Estimate output: ~40,000 tokens for full 34-section plan
+  const outputTokens = 40000;
+  
+  const cost = provider.estimateCost(inputTokens, outputTokens);
+  
+  return {
+    inputTokens,
+    outputTokens,
+    cost,
+  };
+}
+
+export default {
+  loadSystemPrompt,
+  buildImplementationPrompt,
+  buildQuickStartPrompt,
+  buildContextPrompt,
+  estimateTokens,
+  estimateGenerationCost,
+};