@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/mcp/response-formatter.ts

@@ -0,0 +1,797 @@
+/**
+ * Bootspring MCP Response Formatter
+ * Creates well-structured, human-friendly tool responses
+ *
+ * @package bootspring
+ * @module mcp/response-formatter
+ */
+
+import type { MCPToolResult, MCPContent } from '../types/mcp';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Success response options
+ */
+export interface SuccessOptions {
+  summary?: string | undefined;
+  data?: unknown;
+  hints?: string[] | undefined;
+  meta?: Record<string, unknown> | undefined;
+}
+
+/**
+ * List response options
+ */
+export interface ListOptions<T> {
+  title: string;
+  items: T[];
+  formatter?: ((item: T, index: number) => string) | undefined;
+  emptyMessage?: string | undefined;
+  hints?: string[] | undefined;
+}
+
+/**
+ * Agent data for display
+ */
+export interface AgentData {
+  name: string;
+  category?: string | undefined;
+  description: string;
+  expertise: string[];
+  systemPrompt?: string | undefined;
+}
+
+/**
+ * Skill data for display
+ */
+export interface SkillData {
+  name: string;
+  description: string;
+  tags?: string[] | undefined;
+}
+
+/**
+ * Todo item for display
+ */
+export interface TodoItem {
+  text: string;
+  status?: string | undefined;
+}
+
+/**
+ * Quality gate results
+ */
+export interface QualityGateResults {
+  name?: string | undefined;
+  gate?: string | undefined;
+  status: 'pass' | 'fail';
+  passed: number;
+  failed: number;
+  skipped?: number | undefined;
+  results: QualityCheckResult[];
+}
+
+/**
+ * Individual quality check result
+ */
+export interface QualityCheckResult {
+  name: string;
+  status: 'pass' | 'fail' | 'skip';
+  message?: string | undefined;
+}
+
+/**
+ * Context validation result
+ */
+export interface ContextValidationResult {
+  valid: boolean;
+  errors?: string[] | undefined;
+  warnings?: string[] | undefined;
+  suggestions?: string[] | undefined;
+}
+
+/**
+ * Project context for display
+ */
+export interface ProjectContextDisplay {
+  project?: {
+    name?: string | undefined;
+    version?: string | undefined;
+  } | undefined;
+  stack?: {
+    framework?: string | undefined;
+    language?: string | undefined;
+    database?: string | undefined;
+  } | undefined;
+  plugins?: Record<string, unknown> | undefined;
+}
+
+/**
+ * Orchestrator status
+ */
+export interface OrchestratorStatus {
+  currentPhase?: string | undefined;
+  availableAgents?: number | undefined;
+  activeWorkflow?: string | undefined;
+  activeWorkflowSignalProgress?: {
+    completedSignals: unknown[];
+    totalSignals: number;
+  } | undefined;
+  recentSuggestions?: Array<{ text?: string | undefined } | string> | undefined;
+}
+
+/**
+ * PRD data for display
+ */
+export interface PRDData {
+  name: string;
+  stories: Array<{
+    title: string;
+    status: string;
+  }>;
+}
+
+/**
+ * Progress info
+ */
+export interface ProgressInfo {
+  completed: number;
+  total: number;
+  percentage: number;
+}
+
+/**
+ * Assist response
+ */
+export interface AssistResponseData {
+  confidenceTier?: 'high' | 'medium' | 'low' | 'very_low' | undefined;
+  understood?: {
+    intent?: string | undefined;
+    confidence?: number | undefined;
+    description?: string | undefined;
+  } | undefined;
+  primarySuggestion?: {
+    message: string;
+  } | undefined;
+  clarificationNeeded?: boolean | undefined;
+  clarificationQuestion?: string | undefined;
+  clarificationOptions?: string[] | undefined;
+  suggestions?: Array<{ message: string }> | undefined;
+  memoryInsight?: {
+    message: string;
+    recommendation: string;
+  } | undefined;
+  recommendedTool?: {
+    name: string;
+    args: Record<string, unknown>;
+    reason: string;
+  } | undefined;
+}
+
+/**
+ * Intent detection result
+ */
+export interface IntentDetectionData {
+  intent?: string | undefined;
+  intentDescription?: string | undefined;
+  intentConfidence?: number | undefined;
+  matches?: Array<{
+    category: string;
+    keywordCount: number;
+  }> | undefined;
+  suggestedAgents?: string[] | undefined;
+  proactiveSuggestions?: Array<{ message: string }> | undefined;
+}
+
+/**
+ * Extended MCP tool result with metadata
+ */
+export interface MCPToolResultWithMeta extends MCPToolResult {
+  _meta?: Record<string, unknown> | undefined;
+}
+
+// =============================================================================
+// Functions
+// =============================================================================
+
+/**
+ * Format a success response with structured output
+ */
+export function success(options: SuccessOptions): MCPToolResultWithMeta {
+  const { summary, data, hints = [], meta = {} } = options;
+  const sections: string[] = [];
+
+  // Summary section
+  if (summary) {
+    sections.push(`\u2713 ${summary}`);
+  }
+
+  // Data section
+  if (data !== undefined && data !== null) {
+    if (typeof data === 'string') {
+      sections.push(data);
+    } else {
+      sections.push(JSON.stringify(data, null, 2));
+    }
+  }
+
+  // Hints section
+  if (hints && hints.length > 0) {
+    sections.push('\n\ud83d\udca1 Hints:');
+    hints.forEach(hint => sections.push(`  \u2022 ${hint}`));
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }],
+    _meta: meta
+  };
+}
+
+/**
+ * Format an error response
+ */
+export function error(message: string, suggestions: string[] = []): MCPToolResult {
+  const sections: string[] = [`\u2717 Error: ${message}`];
+
+  if (suggestions.length > 0) {
+    sections.push('\n\ud83d\udca1 Suggestions:');
+    suggestions.forEach(s => sections.push(`  \u2022 ${s}`));
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }],
+    isError: true
+  };
+}
+
+/**
+ * Format a warning response
+ */
+export function warning(message: string, suggestions: string[] = []): MCPToolResult {
+  const sections: string[] = [`\u26a0\ufe0f Warning: ${message}`];
+
+  if (suggestions.length > 0) {
+    sections.push('\n\ud83d\udca1 Suggestions:');
+    suggestions.forEach(s => sections.push(`  \u2022 ${s}`));
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format a list response with items
+ */
+export function list<T>(options: ListOptions<T>): MCPToolResult {
+  const { title, items, formatter, emptyMessage = 'No items found', hints = [] } = options;
+  const sections: string[] = [];
+
+  sections.push(`\ud83d\udccb ${title}`);
+  sections.push(`   ${items.length} item(s)\n`);
+
+  if (items.length === 0) {
+    sections.push(`   ${emptyMessage}`);
+  } else {
+    items.forEach((item, index) => {
+      const formatted = formatter ? formatter(item, index) : String(item);
+      sections.push(formatted);
+    });
+  }
+
+  if (hints && hints.length > 0) {
+    sections.push('\n\ud83d\udca1 Hints:');
+    hints.forEach(hint => sections.push(`  \u2022 ${hint}`));
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format agent details for display
+ */
+export function agentDetails(id: string, agent: AgentData): MCPToolResult {
+  const sections: string[] = [
+    `\ud83e\udd16 Agent: ${agent.name}`,
+    `   ID: ${id}`,
+    `   Category: ${agent.category ?? 'General'}`,
+    '',
+    agent.description,
+    '',
+    '\ud83d\udcda Expertise:',
+    ...agent.expertise.map(e => `   \u2022 ${e}`),
+    ''
+  ];
+
+  if (agent.systemPrompt) {
+    sections.push('\ud83d\udcdd System Prompt Available: Yes');
+  }
+
+  sections.push(
+    '',
+    '\ud83d\udca1 Usage:',
+    '   Invoke this agent with a topic to get specialized assistance'
+  );
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format skill details for display
+ */
+export function skillDetails(id: string, skill: SkillData, content: string | null = null): MCPToolResult {
+  const sections: string[] = [
+    `\ud83d\udcd6 Skill: ${skill.name}`,
+    `   ID: ${id}`,
+    '',
+    skill.description,
+    ''
+  ];
+
+  if (skill.tags && skill.tags.length > 0) {
+    sections.push(`\ud83c\udff7\ufe0f  Tags: ${skill.tags.join(', ')}`);
+    sections.push('');
+  }
+
+  if (content) {
+    sections.push('---', '', content);
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format todo list for display
+ */
+export function todoList(pending: TodoItem[], completed: TodoItem[]): MCPToolResult {
+  const sections: string[] = [
+    '\ud83d\udccb Project Todo List',
+    ''
+  ];
+
+  sections.push(`\u23f3 Pending (${pending.length}):`);
+  if (pending.length === 0) {
+    sections.push('   No pending tasks! \ud83c\udf89');
+  } else {
+    pending.forEach((t, i) => {
+      sections.push(`   ${i}. [ ] ${t.text}`);
+    });
+  }
+
+  sections.push('');
+  sections.push(`\u2705 Completed (${completed.length}):`);
+  if (completed.length === 0) {
+    sections.push('   No completed tasks yet');
+  } else {
+    completed.slice(0, 5).forEach(t => {
+      sections.push(`   [x] ${t.text}`);
+    });
+    if (completed.length > 5) {
+      sections.push(`   ... and ${completed.length - 5} more`);
+    }
+  }
+
+  sections.push(
+    '',
+    '\ud83d\udca1 Actions:',
+    '   \u2022 Add: bootspring_todo action=add text="your task"',
+    '   \u2022 Complete: bootspring_todo action=done index=0',
+    '   \u2022 Remove: bootspring_todo action=remove index=0'
+  );
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format quality gate results
+ */
+export function qualityResults(results: QualityGateResults): MCPToolResult {
+  const statusIcon = results.status === 'pass' ? '\u2705' : '\u274c';
+  const sections: string[] = [
+    `${statusIcon} Quality Gate: ${results.name ?? results.gate ?? 'Unknown'}`,
+    `   Status: ${results.status.toUpperCase()}`,
+    `   Passed: ${results.passed} | Failed: ${results.failed} | Skipped: ${results.skipped ?? 0}`,
+    ''
+  ];
+
+  sections.push('\ud83d\udcca Check Results:');
+  for (const check of results.results) {
+    const icon = check.status === 'pass'
+      ? '\u2713'
+      : check.status === 'fail'
+        ? '\u2717'
+        : '\u25cb';
+    sections.push(`   ${icon} ${check.name}: ${check.status}`);
+    if (check.status === 'fail' && check.message) {
+      const shortMessage = check.message.split('\n')[0]?.slice(0, 60) ?? '';
+      sections.push(`      ${shortMessage}...`);
+    }
+  }
+
+  if (results.status === 'fail') {
+    sections.push(
+      '',
+      '\ud83d\udca1 Next Steps:',
+      '   \u2022 Fix the failing checks and re-run the gate',
+      '   \u2022 Use --skip <check> to skip specific checks if needed'
+    );
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format context validation results
+ */
+export function contextValidation(validation: ContextValidationResult): MCPToolResult {
+  const statusIcon = validation.valid ? '\u2705' : '\u26a0\ufe0f';
+  const sections: string[] = [
+    `${statusIcon} Project Validation`,
+    `   Valid: ${validation.valid}`,
+    ''
+  ];
+
+  if (validation.errors && validation.errors.length > 0) {
+    sections.push('\u274c Errors:');
+    validation.errors.forEach(e => sections.push(`   \u2022 ${e}`));
+    sections.push('');
+  }
+
+  if (validation.warnings && validation.warnings.length > 0) {
+    sections.push('\u26a0\ufe0f  Warnings:');
+    validation.warnings.forEach(w => sections.push(`   \u2022 ${w}`));
+    sections.push('');
+  }
+
+  if (validation.suggestions && validation.suggestions.length > 0) {
+    sections.push('\ud83d\udca1 Suggestions:');
+    validation.suggestions.forEach(s => sections.push(`   \u2022 ${s}`));
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format project context summary
+ */
+export function contextSummary(ctx: ProjectContextDisplay): MCPToolResult {
+  const sections: string[] = [
+    `\ud83d\udcc1 Project: ${ctx.project?.name ?? 'Unknown'}`,
+    `   Version: ${ctx.project?.version ?? 'N/A'}`,
+    ''
+  ];
+
+  if (ctx.stack) {
+    sections.push('\ud83d\udee0\ufe0f  Tech Stack:');
+    if (ctx.stack.framework) sections.push(`   Framework: ${ctx.stack.framework}`);
+    if (ctx.stack.language) sections.push(`   Language: ${ctx.stack.language}`);
+    if (ctx.stack.database) sections.push(`   Database: ${ctx.stack.database}`);
+    sections.push('');
+  }
+
+  if (ctx.plugins && Object.keys(ctx.plugins).length > 0) {
+    sections.push('\ud83d\udd0c Active Plugins:');
+    Object.keys(ctx.plugins).forEach(p => {
+      sections.push(`   \u2022 ${p}`);
+    });
+    sections.push('');
+  }
+
+  sections.push(
+    '\ud83d\udca1 Commands:',
+    '   \u2022 bootspring_context action=validate - Check project health',
+    '   \u2022 bootspring_generate - Regenerate CLAUDE.md',
+    '   \u2022 bootspring_agent action=list - See available agents'
+  );
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format orchestrator status
+ */
+export function orchestratorStatus(status: OrchestratorStatus): MCPToolResult {
+  const sections: string[] = [
+    '\ud83c\udfaf Orchestrator Status',
+    '',
+    `   Phase: ${status.currentPhase ?? 'Unknown'}`,
+    `   Available Agents: ${status.availableAgents ?? 0}`,
+    `   Active Workflow: ${status.activeWorkflow ?? 'None'}`,
+    ''
+  ];
+
+  if (status.activeWorkflowSignalProgress) {
+    sections.push(
+      `   Checkpoint Signals: ${status.activeWorkflowSignalProgress.completedSignals.length}/${status.activeWorkflowSignalProgress.totalSignals}`,
+      ''
+    );
+  }
+
+  if (status.recentSuggestions && status.recentSuggestions.length > 0) {
+    sections.push('\ud83d\udca1 Recent Suggestions:');
+    status.recentSuggestions.forEach(s => {
+      const text = typeof s === 'string' ? s : s.text ?? '';
+      sections.push(`   \u2022 ${text}`);
+    });
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format PRD/loop status
+ */
+export function loopStatus(prd: PRDData, progress: ProgressInfo): MCPToolResult {
+  const sections: string[] = [
+    `\ud83d\udccb PRD: ${prd.name}`,
+    '',
+    `   Progress: ${progress.completed}/${progress.total} stories (${Math.round(progress.percentage)}%)`,
+    ''
+  ];
+
+  const progressBar = generateProgressBar(progress.percentage);
+  sections.push(`   ${progressBar}`);
+  sections.push('');
+
+  sections.push('\ud83d\udcd6 Stories:');
+  prd.stories.forEach(s => {
+    const icon = s.status === 'complete'
+      ? '\u2705'
+      : s.status === 'in-progress'
+        ? '\ud83d\udd04'
+        : '\u23f3';
+    sections.push(`   ${icon} ${s.title} (${s.status})`);
+  });
+
+  sections.push(
+    '',
+    '\ud83d\udca1 Actions:',
+    '   \u2022 bootspring_loop action=next - Get next story to work on',
+    '   \u2022 bootspring_loop action=complete storyId=X - Mark story complete'
+  );
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Generate a simple progress bar
+ */
+export function generateProgressBar(percentage: number): string {
+  const width = 20;
+  const filled = Math.round((percentage / 100) * width);
+  const empty = width - filled;
+  return '[' + '\u2588'.repeat(filled) + '\u2591'.repeat(empty) + '] ' + Math.round(percentage) + '%';
+}
+
+/**
+ * Format assist response (proactive suggestions)
+ */
+export function assistResponse(response: AssistResponseData): MCPToolResult {
+  const sections: string[] = [];
+  const confidenceIcon: Record<string, string> = {
+    high: '\ud83c\udfaf',
+    medium: '\ud83d\udcad',
+    low: '\ud83e\udd14',
+    very_low: '\u2753'
+  };
+
+  // Header
+  sections.push(`${confidenceIcon[response.confidenceTier ?? 'medium'] ?? '\ud83d\udcad'} Understanding Your Request`);
+  sections.push('');
+
+  // What we understood
+  if (response.understood) {
+    sections.push(`**Intent**: ${response.understood.intent ?? 'Unknown'}`);
+    sections.push(`**Confidence**: ${((response.understood.confidence ?? 0) * 100).toFixed(0)}%`);
+    if (response.understood.description) {
+      sections.push(`**Action**: ${response.understood.description}`);
+    }
+    sections.push('');
+  }
+
+  // Primary suggestion
+  if (response.primarySuggestion) {
+    sections.push('### Recommended Action');
+    sections.push(`${response.primarySuggestion.message}`);
+    sections.push('');
+  }
+
+  // Clarification needed
+  if (response.clarificationNeeded) {
+    sections.push('### Need More Info');
+    sections.push(response.clarificationQuestion ?? '');
+    if (response.clarificationOptions && response.clarificationOptions.length > 0) {
+      sections.push('');
+      sections.push('Options:');
+      response.clarificationOptions.forEach(opt => {
+        sections.push(`  \u2022 ${opt}`);
+      });
+    }
+    sections.push('');
+  }
+
+  // Other suggestions
+  if (response.suggestions && response.suggestions.length > 0) {
+    sections.push('### Other Options');
+    response.suggestions.forEach((s, i) => {
+      sections.push(`${i + 1}. ${s.message}`);
+    });
+    sections.push('');
+  }
+
+  // Memory insight
+  if (response.memoryInsight) {
+    sections.push('### From Experience');
+    sections.push(`\ud83d\udca1 ${response.memoryInsight.message}`);
+    sections.push(`Recommendation: **${response.memoryInsight.recommendation}**`);
+    sections.push('');
+  }
+
+  // Tool call
+  if (response.recommendedTool) {
+    sections.push('### Tool to Use');
+    sections.push('```json');
+    sections.push(JSON.stringify({
+      tool: response.recommendedTool.name,
+      args: response.recommendedTool.args
+    }, null, 2));
+    sections.push('```');
+    sections.push(`*${response.recommendedTool.reason}*`);
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format intent detection results
+ */
+export function intentDetection(detection: IntentDetectionData): MCPToolResult {
+  const sections: string[] = [
+    '\ud83e\udde0 Intent Analysis',
+    ''
+  ];
+
+  if (detection.intent) {
+    sections.push(`**Primary Intent**: ${detection.intent}`);
+    sections.push(`**Description**: ${detection.intentDescription ?? 'N/A'}`);
+    sections.push(`**Confidence**: ${((detection.intentConfidence ?? 0) * 100).toFixed(0)}%`);
+    sections.push('');
+  }
+
+  if (detection.matches && detection.matches.length > 0) {
+    sections.push('\ud83d\udcc2 Matched Categories:');
+    detection.matches.forEach(m => {
+      sections.push(`  \u2022 ${m.category} (${m.keywordCount} keywords)`);
+    });
+    sections.push('');
+  }
+
+  if (detection.suggestedAgents && detection.suggestedAgents.length > 0) {
+    sections.push('\ud83e\udd16 Suggested Agents:');
+    detection.suggestedAgents.forEach(a => {
+      sections.push(`  \u2022 ${a}`);
+    });
+    sections.push('');
+  }
+
+  if (detection.proactiveSuggestions && detection.proactiveSuggestions.length > 0) {
+    sections.push('\ud83d\udca1 Proactive Suggestions:');
+    detection.proactiveSuggestions.forEach(s => {
+      sections.push(`  \u2022 ${s.message}`);
+    });
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}
+
+/**
+ * Format capabilities list for showing what bootspring can do
+ */
+export function capabilitiesList(_capabilities: unknown): MCPToolResult {
+  const sections: string[] = [
+    '\ud83d\ude80 What Bootspring Can Do',
+    '',
+    '**Natural Language Understanding**',
+    '  "Help me add authentication"',
+    '  "Why is my API slow?"',
+    '  "Deploy to production"',
+    '',
+    '**Expert Agents**',
+    '  \u2022 database-expert - Schema design, queries, migrations',
+    '  \u2022 security-expert - Auth, vulnerabilities, best practices',
+    '  \u2022 frontend-expert - React, components, styling',
+    '  \u2022 performance-expert - Optimization, caching, profiling',
+    '  \u2022 And more...',
+    '',
+    '**Workflows**',
+    '  \u2022 Feature development',
+    '  \u2022 Security audit',
+    '  \u2022 Performance optimization',
+    '  \u2022 Launch preparation',
+    '',
+    '**Quality Gates**',
+    '  \u2022 Pre-commit checks',
+    '  \u2022 Test validation',
+    '  \u2022 Security scanning',
+    '',
+    '**Skills & Patterns**',
+    '  \u2022 Code patterns for auth, payments, API',
+    '  \u2022 Best practices and examples',
+    '',
+    '\ud83d\udca1 Try: bootspring_assist message="help me with..."'
+  ];
+
+  return {
+    content: [{
+      type: 'text',
+      text: sections.join('\n')
+    }]
+  };
+}