@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/help-formatter.js

@@ -0,0 +1,413 @@
+/**
+ * Vibecheck CLI Help Formatter - World-Class Help System
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * Provides consistent, beautiful, and informative help text across all commands.
+ * Features:
+ * - Consistent visual formatting
+ * - Rich examples with explanations
+ * - Tier badges and upgrade hints
+ * - Related commands section
+ * - Shell completion hints
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+
+"use strict";
+
+const { ansi, colors, icons, BOX, WIDTH } = require("./terminal-ui");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const HELP_WIDTH = 76;
+const INDENT = "  ";
+const SECTION_INDENT = "    ";
+
+// Tier badges
+const TIER_BADGES = {
+  free: `${ansi.green}[FREE]${ansi.reset}`,
+  starter: `${ansi.cyan}[STARTER]${ansi.reset}`,
+  pro: `${ansi.magenta}[PRO]${ansi.reset}`,
+  enterprise: `${ansi.yellow}[ENTERPRISE]${ansi.reset}`,
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP SECTION BUILDERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Format a section header
+ */
+function formatSectionHeader(title, icon = "") {
+  const iconStr = icon ? `${icon} ` : "";
+  return `\n${INDENT}${ansi.bold}${iconStr}${title}${ansi.reset}\n`;
+}
+
+/**
+ * Format a description paragraph
+ */
+function formatDescription(text) {
+  if (!text) return "";
+  const lines = wrapText(text, HELP_WIDTH - 4);
+  return lines.map(line => `${INDENT}${ansi.dim}${line}${ansi.reset}`).join("\n") + "\n";
+}
+
+/**
+ * Format a usage line
+ */
+function formatUsage(command, args = "", options = "[options]") {
+  const parts = [`vibecheck ${command}`];
+  if (args) parts.push(args);
+  if (options) parts.push(options);
+  return `${INDENT}${ansi.cyan}${parts.join(" ")}${ansi.reset}`;
+}
+
+/**
+ * Format aliases
+ */
+function formatAliases(aliases) {
+  if (!aliases || aliases.length === 0) return "";
+  return `${INDENT}${ansi.dim}Aliases: ${aliases.join(", ")}${ansi.reset}\n`;
+}
+
+/**
+ * Format an option/flag
+ */
+function formatOption(flag, description, meta = {}) {
+  const { tier, default: defaultVal, required, short } = meta;
+  
+  let flagStr = `${colors.accent}${flag}${ansi.reset}`;
+  if (short) {
+    flagStr = `${colors.accent}${short}${ansi.reset}, ${flagStr}`;
+  }
+  
+  let line = `${SECTION_INDENT}${flagStr.padEnd(28)}`;
+  line += description;
+  
+  if (tier && tier !== "free") {
+    line += ` ${TIER_BADGES[tier]}`;
+  }
+  if (defaultVal !== undefined) {
+    line += ` ${ansi.dim}(default: ${defaultVal})${ansi.reset}`;
+  }
+  if (required) {
+    line += ` ${ansi.yellow}(required)${ansi.reset}`;
+  }
+  
+  return line;
+}
+
+/**
+ * Format a group of options
+ */
+function formatOptionGroup(title, options) {
+  const lines = [formatSectionHeader(title)];
+  for (const opt of options) {
+    lines.push(formatOption(opt.flag, opt.description, opt));
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Format an example
+ */
+function formatExample(command, description, explanation = "") {
+  let result = `${SECTION_INDENT}${ansi.dim}#${ansi.reset} ${description}\n`;
+  result += `${SECTION_INDENT}${ansi.cyan}${command}${ansi.reset}`;
+  if (explanation) {
+    result += `\n${SECTION_INDENT}${ansi.dim}${explanation}${ansi.reset}`;
+  }
+  return result;
+}
+
+/**
+ * Format examples section
+ */
+function formatExamples(examples) {
+  const lines = [formatSectionHeader("EXAMPLES", "💡")];
+  for (let i = 0; i < examples.length; i++) {
+    const ex = examples[i];
+    lines.push(formatExample(ex.command, ex.description, ex.explanation));
+    if (i < examples.length - 1) lines.push(""); // spacing between examples
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Format related commands
+ */
+function formatRelated(commands) {
+  if (!commands || commands.length === 0) return "";
+  
+  const lines = [formatSectionHeader("RELATED COMMANDS", "🔗")];
+  for (const cmd of commands) {
+    const tierBadge = cmd.tier && cmd.tier !== "free" ? ` ${TIER_BADGES[cmd.tier]}` : "";
+    lines.push(`${SECTION_INDENT}${ansi.cyan}vibecheck ${cmd.name}${ansi.reset}${tierBadge}`);
+    lines.push(`${SECTION_INDENT}${ansi.dim}${cmd.description}${ansi.reset}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Format workflow section (multi-step guide)
+ */
+function formatWorkflow(steps) {
+  if (!steps || steps.length === 0) return "";
+  
+  const lines = [formatSectionHeader("WORKFLOW", "📋")];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const num = `${i + 1}.`;
+    lines.push(`${SECTION_INDENT}${ansi.bold}${num}${ansi.reset} ${step.title}`);
+    lines.push(`${SECTION_INDENT}   ${ansi.cyan}${step.command}${ansi.reset}`);
+    if (step.note) {
+      lines.push(`${SECTION_INDENT}   ${ansi.dim}${step.note}${ansi.reset}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Format output section (what the command produces)
+ */
+function formatOutput(outputs) {
+  if (!outputs || outputs.length === 0) return "";
+  
+  const lines = [formatSectionHeader("OUTPUT", "📄")];
+  for (const out of outputs) {
+    lines.push(`${SECTION_INDENT}${ansi.cyan}${out.path}${ansi.reset}`);
+    lines.push(`${SECTION_INDENT}${ansi.dim}${out.description}${ansi.reset}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Format environment variables section
+ */
+function formatEnvVars(vars) {
+  if (!vars || vars.length === 0) return "";
+  
+  const lines = [formatSectionHeader("ENVIRONMENT VARIABLES", "🌍")];
+  for (const v of vars) {
+    lines.push(`${SECTION_INDENT}${ansi.yellow}${v.name}${ansi.reset}`);
+    lines.push(`${SECTION_INDENT}${ansi.dim}${v.description}${ansi.reset}`);
+    if (v.default) {
+      lines.push(`${SECTION_INDENT}${ansi.dim}Default: ${v.default}${ansi.reset}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Format footer with links and hints
+ */
+function formatFooter(command, options = {}) {
+  const { docsUrl, tier, upgradeHint } = options;
+  
+  const lines = ["", `${INDENT}${ansi.dim}${"─".repeat(HELP_WIDTH - 4)}${ansi.reset}`];
+  
+  // Tier info
+  if (tier && tier !== "free") {
+    lines.push(`${INDENT}${ansi.dim}This command requires ${TIER_BADGES[tier]} tier or higher.${ansi.reset}`);
+    if (upgradeHint) {
+      lines.push(`${INDENT}${ansi.dim}${upgradeHint}${ansi.reset}`);
+    }
+  }
+  
+  // Docs link
+  if (docsUrl) {
+    lines.push(`${INDENT}${ansi.dim}Documentation: ${ansi.underline}${docsUrl}${ansi.reset}`);
+  }
+  
+  // Global help hint
+  lines.push(`${INDENT}${ansi.dim}Run 'vibecheck --help' for all commands.${ansi.reset}`);
+  lines.push("");
+  
+  return lines.join("\n");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UTILITY FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Wrap text to fit within width
+ */
+function wrapText(text, width) {
+  const words = text.split(/\s+/);
+  const lines = [];
+  let currentLine = "";
+  
+  for (const word of words) {
+    if (currentLine.length + word.length + 1 > width) {
+      if (currentLine) lines.push(currentLine);
+      currentLine = word;
+    } else {
+      currentLine = currentLine ? `${currentLine} ${word}` : word;
+    }
+  }
+  if (currentLine) lines.push(currentLine);
+  
+  return lines;
+}
+
+/**
+ * Strip ANSI codes for length calculation
+ */
+function stripAnsi(str) {
+  return str.replace(/\x1b\[\d+m/g, "").replace(/\x1b\[38;2;\d+;\d+;\d+m/g, "");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN HELP BUILDER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Build complete help text for a command
+ * 
+ * @param {object} config - Help configuration
+ * @param {string} config.name - Command name
+ * @param {string[]} config.aliases - Command aliases
+ * @param {string} config.description - Short description
+ * @param {string} config.longDescription - Detailed description
+ * @param {string} config.tier - Required tier (free, starter, pro)
+ * @param {string} config.usage - Usage pattern (e.g., "[path] [options]")
+ * @param {object[]} config.options - Array of option definitions
+ * @param {object[]} config.examples - Array of example definitions
+ * @param {object[]} config.related - Array of related command definitions
+ * @param {object[]} config.workflow - Array of workflow steps
+ * @param {object[]} config.outputs - Array of output file definitions
+ * @param {object[]} config.envVars - Array of environment variable definitions
+ * @param {string} config.docsUrl - Documentation URL
+ * @param {function} config.banner - Optional banner function
+ * @returns {string} Complete formatted help text
+ */
+function buildHelp(config) {
+  const parts = [];
+  
+  // Banner (optional)
+  if (config.banner) {
+    parts.push(config.banner());
+  }
+  
+  // Usage
+  parts.push(formatSectionHeader("USAGE"));
+  parts.push(formatUsage(config.name, config.usage || "[options]"));
+  parts.push("");
+  
+  // Aliases
+  if (config.aliases && config.aliases.length > 0) {
+    parts.push(formatAliases(config.aliases));
+  }
+  
+  // Description
+  if (config.longDescription || config.description) {
+    parts.push(formatSectionHeader("DESCRIPTION"));
+    parts.push(formatDescription(config.longDescription || config.description));
+  }
+  
+  // Options (grouped)
+  if (config.options && config.options.length > 0) {
+    // Group options by category
+    const groups = {};
+    for (const opt of config.options) {
+      const group = opt.group || "OPTIONS";
+      if (!groups[group]) groups[group] = [];
+      groups[group].push(opt);
+    }
+    
+    for (const [groupName, groupOpts] of Object.entries(groups)) {
+      parts.push(formatOptionGroup(groupName, groupOpts));
+    }
+  }
+  
+  // Examples
+  if (config.examples && config.examples.length > 0) {
+    parts.push(formatExamples(config.examples));
+  }
+  
+  // Workflow
+  if (config.workflow && config.workflow.length > 0) {
+    parts.push(formatWorkflow(config.workflow));
+  }
+  
+  // Output
+  if (config.outputs && config.outputs.length > 0) {
+    parts.push(formatOutput(config.outputs));
+  }
+  
+  // Environment variables
+  if (config.envVars && config.envVars.length > 0) {
+    parts.push(formatEnvVars(config.envVars));
+  }
+  
+  // Related commands
+  if (config.related && config.related.length > 0) {
+    parts.push(formatRelated(config.related));
+  }
+  
+  // Footer
+  parts.push(formatFooter(config.name, {
+    tier: config.tier,
+    docsUrl: config.docsUrl,
+    upgradeHint: config.tier !== "free" ? "Upgrade at: https://vibecheckai.dev/pricing" : null,
+  }));
+  
+  return parts.join("\n");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// QUICK HELPERS FOR COMMON PATTERNS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Global options that apply to most commands
+ */
+const GLOBAL_OPTIONS = [
+  { flag: "--help, -h", description: "Show this help", group: "GLOBAL OPTIONS" },
+  { flag: "--json", description: "Output as JSON (machine-readable)", group: "GLOBAL OPTIONS" },
+  { flag: "--quiet, -q", description: "Suppress non-essential output", group: "GLOBAL OPTIONS" },
+  { flag: "--verbose", description: "Show detailed output", group: "GLOBAL OPTIONS" },
+  { flag: "--no-banner", description: "Hide the banner", group: "GLOBAL OPTIONS" },
+  { flag: "--ci", description: "CI mode (implies --quiet --no-banner)", group: "GLOBAL OPTIONS" },
+  { flag: "--path, -p <dir>", description: "Run in specified directory", group: "GLOBAL OPTIONS" },
+  { flag: "--offline", description: "Run in offline mode (no API)", group: "GLOBAL OPTIONS" },
+];
+
+/**
+ * Add global options to a command's options array
+ */
+function withGlobalOptions(options) {
+  return [...options, ...GLOBAL_OPTIONS];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  buildHelp,
+  formatSectionHeader,
+  formatDescription,
+  formatUsage,
+  formatAliases,
+  formatOption,
+  formatOptionGroup,
+  formatExample,
+  formatExamples,
+  formatRelated,
+  formatWorkflow,
+  formatOutput,
+  formatEnvVars,
+  formatFooter,
+  wrapText,
+  stripAnsi,
+  withGlobalOptions,
+  GLOBAL_OPTIONS,
+  TIER_BADGES,
+  HELP_WIDTH,
+};