@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

package/src/commands/session-summary.js

@@ -0,0 +1,291 @@
+/**
+ * MORPH-SPEC Session Summary Command
+ *
+ * Shows a comprehensive summary of the current session including:
+ * - Phases completed
+ * - Decisions taken
+ * - Progress on tasks
+ * - Next steps
+ *
+ * Usage:
+ *   morph-spec session-summary <feature-name>
+ *   morph-spec summary <feature-name>
+ */
+
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { loadState, getFeature } from '../lib/state-manager.js';
+
+// Phase order for display
+const PHASE_ORDER = [
+  { key: 'proposal', name: 'FASE 0: PROPOSAL', emoji: '📝' },
+  { key: 'setup', name: 'FASE 1: SETUP', emoji: '⚙️' },
+  { key: 'uiux', name: 'FASE 1.5: UI/UX', emoji: '🎨', optional: true },
+  { key: 'design', name: 'FASE 2: DESIGN', emoji: '📐' },
+  { key: 'clarify', name: 'FASE 3: CLARIFY', emoji: '❓' },
+  { key: 'tasks', name: 'FASE 4: TASKS', emoji: '📋' },
+  { key: 'implement', name: 'FASE 5: IMPLEMENT', emoji: '🔨' },
+  { key: 'sync', name: 'FASE 6: SYNC', emoji: '🔄', optional: true }
+];
+
+/**
+ * Get phase index for comparison
+ */
+function getPhaseIndex(phaseKey) {
+  return PHASE_ORDER.findIndex(p => p.key === phaseKey);
+}
+
+/**
+ * Read decisions from decisions.md
+ */
+function readDecisions(featurePath) {
+  const decisionsPath = path.join(featurePath, 'decisions.md');
+  if (!fs.existsSync(decisionsPath)) return [];
+
+  try {
+    const content = fs.readFileSync(decisionsPath, 'utf-8');
+    const decisions = [];
+
+    // Parse ADR sections
+    const adrMatches = content.matchAll(/##\s+ADR[- ]?\d*:?\s*(.+?)(?=\n##|\n$|$)/gis);
+    for (const match of adrMatches) {
+      const title = match[1].split('\n')[0].trim();
+      decisions.push(title);
+    }
+
+    // Also parse simple decisions format
+    const simpleMatches = content.matchAll(/[-*]\s+\*\*(.+?)\*\*:\s*(.+)/g);
+    for (const match of simpleMatches) {
+      decisions.push(`${match[1]}: ${match[2]}`);
+    }
+
+    return decisions.slice(0, 10); // Limit to 10
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check which outputs exist
+ */
+function checkOutputs(featurePath) {
+  const outputs = [
+    { file: 'proposal.md', name: 'Proposal' },
+    { file: 'spec.md', name: 'Spec' },
+    { file: 'contracts.cs', name: 'Contracts' },
+    { file: 'ui-design-system.md', name: 'UI Design System' },
+    { file: 'ui-mockups.md', name: 'UI Mockups' },
+    { file: 'ui-components.md', name: 'UI Components' },
+    { file: 'ui-flows.md', name: 'UI Flows' },
+    { file: 'decisions.md', name: 'Decisions' },
+    { file: 'recap.md', name: 'Recap' }
+  ];
+
+  return outputs.map(o => ({
+    ...o,
+    exists: fs.existsSync(path.join(featurePath, o.file))
+  }));
+}
+
+/**
+ * Generate progress bar
+ */
+function progressBar(completed, total, width = 30) {
+  if (total === 0) return chalk.gray('[' + '░'.repeat(width) + '] 0%');
+
+  const percentage = Math.round((completed / total) * 100);
+  const filled = Math.round((completed / total) * width);
+  const empty = width - filled;
+
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+  const color = percentage === 100 ? chalk.green : percentage > 50 ? chalk.yellow : chalk.cyan;
+
+  return color(`[${bar}] ${percentage}%`);
+}
+
+/**
+ * Get next steps suggestions
+ */
+function getNextSteps(feature, currentPhaseIndex) {
+  const steps = [];
+
+  if (!feature) {
+    steps.push('Run: morph-spec state set <feature> phase proposal');
+    return steps;
+  }
+
+  const nextPhase = PHASE_ORDER[currentPhaseIndex + 1];
+
+  if (feature.tasks?.total > 0 && feature.tasks?.completed < feature.tasks?.total) {
+    steps.push(`Continue implementing tasks (${feature.tasks.completed}/${feature.tasks.total} done)`);
+  }
+
+  if (nextPhase) {
+    steps.push(`Advance to ${nextPhase.name}`);
+  }
+
+  if (feature.phase === 'implement' && feature.tasks?.completed === feature.tasks?.total) {
+    steps.push('Generate recap.md');
+    steps.push('Consider running FASE 6: SYNC to promote decisions');
+  }
+
+  return steps;
+}
+
+/**
+ * Main command handler
+ */
+export async function sessionSummaryCommand(featureName, options = {}) {
+  const featurePath = path.join(process.cwd(), '.morph/project/outputs', featureName);
+
+  // Header
+  console.log(chalk.cyan('\n╔════════════════════════════════════════════════════════════╗'));
+  console.log(chalk.cyan(`║  📊 SESSION SUMMARY: ${featureName.padEnd(35)}║`));
+  console.log(chalk.cyan('╚════════════════════════════════════════════════════════════╝\n'));
+
+  // Get feature from state
+  let feature = null;
+  try {
+    feature = getFeature(featureName);
+  } catch {
+    // State may not exist
+  }
+
+  // JSON output mode
+  if (options.json) {
+    const outputs = checkOutputs(featurePath);
+    const decisions = readDecisions(featurePath);
+    const summary = {
+      feature: featureName,
+      status: feature?.status || 'unknown',
+      phase: feature?.phase || 'unknown',
+      workflow: feature?.workflow || 'auto',
+      agents: feature?.activeAgents || [],
+      tasks: feature?.tasks || { total: 0, completed: 0 },
+      checkpoints: feature?.checkpoints || [],
+      outputs: outputs.filter(o => o.exists).map(o => o.name),
+      decisions,
+      skippedPhases: feature?.skippedPhases || []
+    };
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  // Check if feature directory exists
+  if (!fs.existsSync(featurePath)) {
+    console.log(chalk.yellow('  ⚠️  Feature directory not found'));
+    console.log(chalk.gray(`     Expected: ${featurePath}\n`));
+
+    if (feature) {
+      console.log(chalk.gray('  State exists but no outputs directory.'));
+      console.log(chalk.gray(`  Phase: ${feature.phase}`));
+    }
+    return;
+  }
+
+  // Current Status
+  const currentPhaseIndex = feature ? getPhaseIndex(feature.phase) : -1;
+
+  console.log(chalk.bold('📌 Current Status'));
+  console.log(chalk.gray('─'.repeat(50)));
+  console.log(`  Phase:    ${chalk.cyan(feature?.phase || 'unknown')}`);
+  console.log(`  Status:   ${chalk.cyan(feature?.status || 'unknown')}`);
+  console.log(`  Workflow: ${chalk.cyan(feature?.workflow || 'auto')}`);
+  console.log('');
+
+  // Phases Progress
+  console.log(chalk.bold('🔄 Phases Progress'));
+  console.log(chalk.gray('─'.repeat(50)));
+
+  for (let i = 0; i < PHASE_ORDER.length; i++) {
+    const phase = PHASE_ORDER[i];
+    let status;
+    let color;
+
+    const isSkipped = feature?.skippedPhases?.includes(phase.key);
+
+    if (isSkipped) {
+      status = 'SKIP';
+      color = chalk.gray;
+    } else if (i < currentPhaseIndex) {
+      status = '✓';
+      color = chalk.green;
+    } else if (i === currentPhaseIndex) {
+      status = '▸';
+      color = chalk.cyan;
+    } else {
+      status = ' ';
+      color = chalk.gray;
+    }
+
+    const optionalTag = phase.optional ? chalk.gray(' (optional)') : '';
+    console.log(`  ${color(status)} ${phase.emoji} ${color(phase.name)}${optionalTag}`);
+  }
+  console.log('');
+
+  // Tasks Progress
+  if (feature?.tasks && feature.tasks.total > 0) {
+    console.log(chalk.bold('📋 Tasks Progress'));
+    console.log(chalk.gray('─'.repeat(50)));
+    console.log(`  ${progressBar(feature.tasks.completed, feature.tasks.total)}`);
+    console.log(`  ${chalk.gray(`${feature.tasks.completed}/${feature.tasks.total} tasks completed`)}`);
+    console.log('');
+  }
+
+  // Active Agents
+  if (feature?.activeAgents && feature.activeAgents.length > 0) {
+    console.log(chalk.bold('🤖 Active Agents'));
+    console.log(chalk.gray('─'.repeat(50)));
+    feature.activeAgents.forEach(agent => {
+      console.log(`  • ${chalk.cyan(agent)}`);
+    });
+    console.log('');
+  }
+
+  // Outputs
+  const outputs = checkOutputs(featurePath);
+  const createdOutputs = outputs.filter(o => o.exists);
+
+  if (createdOutputs.length > 0) {
+    console.log(chalk.bold('📄 Outputs Created'));
+    console.log(chalk.gray('─'.repeat(50)));
+    createdOutputs.forEach(o => {
+      console.log(`  ${chalk.green('✓')} ${o.name}`);
+    });
+    console.log('');
+  }
+
+  // Decisions Taken
+  const decisions = readDecisions(featurePath);
+  if (decisions.length > 0) {
+    console.log(chalk.bold('🎯 Decisions Taken'));
+    console.log(chalk.gray('─'.repeat(50)));
+    decisions.forEach(d => {
+      console.log(`  • ${chalk.white(d)}`);
+    });
+    console.log('');
+  }
+
+  // Checkpoints
+  if (feature?.checkpoints && feature.checkpoints.length > 0) {
+    console.log(chalk.bold('🏁 Checkpoints'));
+    console.log(chalk.gray('─'.repeat(50)));
+    feature.checkpoints.slice(-5).forEach(cp => {
+      const date = new Date(cp.timestamp).toLocaleString();
+      console.log(`  ${chalk.gray(date)} - ${cp.note}`);
+    });
+    console.log('');
+  }
+
+  // Next Steps
+  const nextSteps = getNextSteps(feature, currentPhaseIndex);
+  if (nextSteps.length > 0) {
+    console.log(chalk.bold('➡️  Next Steps'));
+    console.log(chalk.gray('─'.repeat(50)));
+    nextSteps.forEach((step, i) => {
+      console.log(`  ${i + 1}. ${chalk.yellow(step)}`);
+    });
+    console.log('');
+  }
+}

package/src/commands/task.js

@@ -1,75 +1,78 @@
-/**
- * Task management commands
- * Wrapper for bin/task-manager.js (CommonJS) to ESM
- */
-
-import { spawn } from 'child_process';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import chalk from 'chalk';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const taskManagerPath = join(__dirname, '..', '..', 'bin', 'task-manager.js');
-
-/**
- * Execute task-manager.js with given arguments
- */
-function executeTaskManager(args) {
-  return new Promise((resolve, reject) => {
-    const child = spawn('node', [taskManagerPath, ...args], {
-      stdio: 'inherit',
-      shell: true
-    });
-
-    child.on('close', (code) => {
-      if (code === 0) {
-        resolve();
-      } else {
-        reject(new Error(`Task manager exited with code ${code}`));
-      }
-    });
-
-    child.on('error', (error) => {
-      reject(error);
-    });
-  });
-}
-
-/**
- * Complete tasks command
- */
-export async function taskDoneCommand(featureName, taskIds, options) {
-  try {
-    const args = ['done', featureName, ...taskIds];
-    await executeTaskManager(args);
-  } catch (error) {
-    console.error(chalk.red(`Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-
-/**
- * Start task command
- */
-export async function taskStartCommand(featureName, taskId, options) {
-  try {
-    const args = ['start', featureName, taskId];
-    await executeTaskManager(args);
-  } catch (error) {
-    console.error(chalk.red(`Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-
-/**
- * Get next task command
- */
-export async function taskNextCommand(featureName, options) {
-  try {
-    const args = ['next', featureName];
-    await executeTaskManager(args);
-  } catch (error) {
-    console.error(chalk.red(`Error: ${error.message}`));
-    process.exit(1);
-  }
-}
+/**
+ * Task management commands
+ * Wrapper for bin/task-manager.js (CommonJS) to ESM
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import chalk from 'chalk';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const taskManagerPath = join(__dirname, '..', '..', 'bin', 'task-manager.js');
+
+/**
+ * Execute task-manager.js with given arguments
+ */
+function executeTaskManager(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('node', [taskManagerPath, ...args], {
+      stdio: 'inherit',
+      shell: true
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Task manager exited with code ${code}`));
+      }
+    });
+
+    child.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Complete tasks command
+ */
+export async function taskDoneCommand(featureName, taskIds, options) {
+  try {
+    const args = ['done', featureName, ...taskIds];
+    if (options.skipValidation) {
+      args.push('--skip-validation');
+    }
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Start task command
+ */
+export async function taskStartCommand(featureName, taskId, options) {
+  try {
+    const args = ['start', featureName, taskId];
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Get next task command
+ */
+export async function taskNextCommand(featureName, options) {
+  try {
+    const args = ['next', featureName];
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}

package/src/commands/troubleshoot.js

@@ -0,0 +1,222 @@
+/**
+ * Troubleshoot Command
+ * Search for solutions to common problems
+ *
+ * Usage: morph-spec troubleshoot <keywords...>
+ */
+
+import { searchIndex, getCategories } from '../lib/troubleshoot-index.js';
+import { searchGrep } from '../lib/troubleshoot-grep.js';
+import chalk from 'chalk';
+
+// Severity colors and icons
+const SEVERITY_CONFIG = {
+  critical: { color: chalk.red, icon: '🔴', label: 'CRITICAL' },
+  high: { color: chalk.yellow, icon: '🟠', label: 'HIGH' },
+  medium: { color: chalk.blue, icon: '🔵', label: 'MEDIUM' },
+  low: { color: chalk.gray, icon: '⚪', label: 'LOW' }
+};
+
+/**
+ * Format a single result for display
+ * @param {Object} result - Result object
+ * @param {boolean} verbose - Show full content
+ * @returns {string} Formatted output
+ */
+function formatResult(result, verbose = false) {
+  const severity = SEVERITY_CONFIG[result.severity] || SEVERITY_CONFIG.medium;
+  const lines = [];
+
+  lines.push(chalk.gray('━'.repeat(50)));
+  lines.push('');
+  lines.push(`${severity.icon} ${severity.color.bold(severity.label)}: ${chalk.white.bold(result.title)}`);
+  lines.push('');
+
+  // File and section
+  lines.push(`${chalk.gray('📁 Arquivo:')} ${chalk.cyan(result.file)}`);
+  if (result.section) {
+    lines.push(`${chalk.gray('📂 Seção:')} ${result.section}`);
+  }
+  lines.push('');
+
+  // Cause
+  if (result.cause) {
+    lines.push(`${chalk.red('💡 Causa:')}`);
+    lines.push(`   ${result.cause}`);
+    lines.push('');
+  }
+
+  // Solution
+  if (result.solution) {
+    lines.push(`${chalk.green('✅ Solução:')}`);
+    lines.push(`   ${chalk.white(result.solution)}`);
+    lines.push('');
+  }
+
+  // Content preview (for grep results or verbose mode)
+  if (verbose && result.content) {
+    lines.push(`${chalk.gray('📝 Conteúdo:')}`);
+    const contentLines = result.content.split('\n').slice(0, 15);
+    contentLines.forEach(line => {
+      lines.push(`   ${chalk.gray(line)}`);
+    });
+    lines.push('');
+  }
+
+  // Keywords matched
+  if (result.keywords && result.keywords.length > 0) {
+    const keywords = Array.isArray(result.keywords)
+      ? result.keywords.slice(0, 5).join(', ')
+      : result.keywords;
+    lines.push(`${chalk.gray('🏷️  Keywords:')} ${chalk.dim(keywords)}`);
+  }
+
+  // Source (index or grep)
+  if (result.source === 'grep') {
+    lines.push(`${chalk.gray('🔍 Fonte:')} ${chalk.dim('Busca em arquivos (grep)')}`);
+  }
+
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Format the summary footer
+ * @param {Object} stats - Search statistics
+ * @returns {string} Formatted summary
+ */
+function formatSummary(stats) {
+  const lines = [];
+
+  lines.push(chalk.gray('━'.repeat(50)));
+  lines.push('');
+
+  if (stats.total === 0) {
+    lines.push(chalk.yellow('⚠️  Nenhum resultado encontrado no índice ou arquivos.'));
+    lines.push('');
+    lines.push(chalk.dim('💡 Dicas:'));
+    lines.push(chalk.dim('   • Tente termos mais específicos (ex: "NU1605" em vez de "error")'));
+    lines.push(chalk.dim('   • Use parte da mensagem de erro exata'));
+    lines.push(chalk.dim('   • Consulte a documentação: morph-spec read blazor-pitfalls.md'));
+  } else {
+    lines.push(`${chalk.green('✅')} Encontrado ${chalk.bold(stats.total)} resultado(s)`);
+
+    if (stats.fromIndex > 0) {
+      lines.push(`   ${chalk.dim(`• ${stats.fromIndex} do índice de problemas conhecidos`)}`);
+    }
+    if (stats.fromGrep > 0) {
+      lines.push(`   ${chalk.dim(`• ${stats.fromGrep} da busca em arquivos`)}`);
+    }
+  }
+
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * List all categories
+ */
+function listCategories() {
+  const categories = getCategories();
+
+  console.log('');
+  console.log(chalk.bold('📂 Categorias disponíveis:'));
+  console.log('');
+
+  for (const [id, category] of Object.entries(categories)) {
+    const name = typeof category === 'object' ? category.name : category;
+    const desc = typeof category === 'object' ? category.description : '';
+    console.log(`   ${chalk.cyan(id.padEnd(12))} ${name}`);
+    if (desc) {
+      console.log(`   ${' '.repeat(12)} ${chalk.dim(desc)}`);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.dim('Uso: morph-spec troubleshoot --category efcore "sua busca"'));
+  console.log('');
+}
+
+/**
+ * Main troubleshoot command
+ * @param {string[]} keywords - Search keywords
+ * @param {Object} options - Command options
+ */
+export async function troubleshootCommand(keywords, options = {}) {
+  // Handle --list-categories flag
+  if (options.listCategories) {
+    listCategories();
+    return;
+  }
+
+  // Validate keywords
+  if (!keywords || keywords.length === 0) {
+    console.log('');
+    console.log(chalk.yellow('⚠️  Por favor, forneça termos de busca.'));
+    console.log('');
+    console.log(chalk.dim('Exemplos:'));
+    console.log(chalk.dim('   morph-spec troubleshoot "blazor.web.js 404"'));
+    console.log(chalk.dim('   morph-spec troubleshoot DbContext concurrent'));
+    console.log(chalk.dim('   morph-spec troubleshoot NU1605 Azure.Identity'));
+    console.log('');
+    console.log(chalk.dim('Opções:'));
+    console.log(chalk.dim('   --category <cat>    Filtrar por categoria (blazor, efcore, azure)'));
+    console.log(chalk.dim('   --verbose, -v       Mostrar conteúdo completo'));
+    console.log(chalk.dim('   --list-categories   Listar categorias disponíveis'));
+    console.log('');
+    return;
+  }
+
+  const searchTerms = Array.isArray(keywords) ? keywords : [keywords];
+
+  console.log('');
+  console.log(`${chalk.cyan('🔍')} Buscando soluções para: ${chalk.bold(`"${searchTerms.join(' ')}"`)}`);
+  console.log('');
+
+  // Search options
+  const searchOptions = {};
+  if (options.category) {
+    searchOptions.category = options.category;
+    console.log(chalk.dim(`   Filtrando por categoria: ${options.category}`));
+    console.log('');
+  }
+
+  // Level 1: Search index
+  let indexResults = searchIndex(searchTerms, searchOptions);
+  indexResults = indexResults.map(r => ({ ...r, source: 'index' }));
+
+  // Level 2: Grep fallback (if few results)
+  let grepResults = [];
+  if (indexResults.length < 3) {
+    grepResults = searchGrep(searchTerms, searchOptions);
+    // Filter out duplicates (same file + section)
+    const indexKeys = new Set(indexResults.map(r => `${r.file}:${r.section}`));
+    grepResults = grepResults.filter(r => !indexKeys.has(`${r.file}:${r.section}`));
+  }
+
+  // Combine and limit results
+  const allResults = [...indexResults, ...grepResults].slice(0, 10);
+
+  // Display results
+  for (const result of allResults) {
+    console.log(formatResult(result, options.verbose));
+  }
+
+  // Display summary
+  console.log(formatSummary({
+    total: allResults.length,
+    fromIndex: indexResults.length,
+    fromGrep: grepResults.slice(0, 10 - indexResults.length).length
+  }));
+
+  // Hint for web search (handled by Claude Code slash command)
+  if (allResults.length === 0) {
+    console.log(chalk.dim('💡 Use /morph-troubleshoot no Claude Code para busca web em'));
+    console.log(chalk.dim('   GitHub Issues, Stack Overflow e Microsoft Learn.'));
+    console.log('');
+  }
+}
+
+export default troubleshootCommand;