@vibecheckai/cli 3.2.1 → 3.2.3

package/bin/runners/lib/cli-output.js

@@ -1,8 +1,13 @@
 /**
- * CLI Output Utilities - World-Class Consistency
- * 
- * Provides standardized JSON output, run ID generation,
- * and artifact management for all CLI commands.
+ * CLI Output Utilities - Enterprise Grade
+ * * Standardizes run lifecycle, artifact management, telemetry,
+ * * and JSON output for the Vibecheck suite.
+ * * Features:
+ * - 🛡️ Atomic file writes (no corruption on crash)
+ * - 🔄 Automatic "latest" symlinking for easy debugging
+ * - 🕵️ Deep CI/Git context extraction
+ * - 🛑 Beautiful Crash Reporting (matches UI style)
+ * - 🧹 Automatic Log Rotation
  */
 
 "use strict";
@@ -10,50 +15,151 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
+const os = require("os");
+const childProcess = require("child_process");
+const chalk = require("chalk"); // Added for premium error reporting
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONFIGURATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const CONFIG = {
+  DIR_NAME: ".vibecheck",
+  MAX_RETAINED_RUNS: 50, // Keep last 50 runs, delete older
+  WIDTH: 76,
+};
 
 // ═══════════════════════════════════════════════════════════════════════════════
 // RUN ID GENERATION
 // ═══════════════════════════════════════════════════════════════════════════════
 
 /**
- * Generate a unique run ID for tracking
+ * Generate a unique, time-sortable run ID
+ * Format: YYYY-MM-DD-HHmm-UUID
  */
 function generateRunId() {
-  return crypto.randomUUID();
+  const date = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 16);
+  const uuid = crypto.randomUUID().slice(0, 8);
+  return `${date}-${uuid}`;
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// OUTPUT DIRECTORY MANAGEMENT
+// CONTEXT GATHERING (Telemetry)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function getSystemContext() {
+  return {
+    platform: os.platform(),
+    arch: os.arch(),
+    node: process.version,
+    cpus: os.cpus().length,
+    memory: Math.round(os.totalmem() / 1024 / 1024 / 1024) + 'GB',
+    cwd: process.cwd(),
+  };
+}
+
+function getGitContext() {
+  try {
+    const commit = childProcess.execSync('git rev-parse --short HEAD', { stdio: 'pipe' }).toString().trim();
+    const branch = childProcess.execSync('git rev-parse --abbrev-ref HEAD', { stdio: 'pipe' }).toString().trim();
+    const isDirty = childProcess.execSync('git status --porcelain', { stdio: 'pipe' }).toString().trim().length > 0;
+    return { commit, branch, isDirty };
+  } catch (e) {
+    return null; // Not a git repo
+  }
+}
+
+function getCiContext() {
+  if (process.env.GITHUB_ACTIONS) return { provider: 'GitHub Actions', runId: process.env.GITHUB_RUN_ID };
+  if (process.env.GITLAB_CI) return { provider: 'GitLab CI', jobId: process.env.CI_JOB_ID };
+  if (process.env.JENKINS_URL) return { provider: 'Jenkins', buildUrl: process.env.BUILD_URL };
+  if (process.env.CI) return { provider: 'Generic CI' };
+  return { provider: null };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FILESYSTEM OPS (Atomic & Safe)
 // ═══════════════════════════════════════════════════════════════════════════════
 
 /**
- * Get run directory paths
+ * Atomic write to prevent file corruption if process dies mid-write
+ */
+function safeWriteJson(filePath, data) {
+  const tempPath = `${filePath}.tmp.${crypto.randomUUID().slice(0, 6)}`;
+  try {
+    fs.writeFileSync(tempPath, JSON.stringify(data, null, 2));
+    fs.renameSync(tempPath, filePath); // Atomic operation
+  } catch (err) {
+    try { fs.unlinkSync(tempPath); } catch (e) {} // Cleanup
+    throw err;
+  }
+}
+
+function updateSymlink(target, linkPath) {
+  try {
+    if (fs.existsSync(linkPath)) fs.unlinkSync(linkPath);
+    // 'junction' type is required for Windows to not require Admin
+    fs.symlinkSync(target, linkPath, 'junction'); 
+  } catch (e) {
+    // Ignore symlink errors (often permissions)
+  }
+}
+
+/**
+ * Cleanup old runs to save disk space (Log Rotation)
  */
+function rotateLogs(runsDir) {
+  try {
+    if (!fs.existsSync(runsDir)) return;
+    
+    const runs = fs.readdirSync(runsDir)
+      .map(name => ({ name, path: path.join(runsDir, name) }))
+      .filter(item => fs.statSync(item.path).isDirectory() && item.name !== 'latest')
+      .sort((a, b) => b.name.localeCompare(a.name)); // Newest first
+
+    if (runs.length > CONFIG.MAX_RETAINED_RUNS) {
+      const toDelete = runs.slice(CONFIG.MAX_RETAINED_RUNS);
+      toDelete.forEach(run => fs.rmSync(run.path, { recursive: true, force: true }));
+    }
+  } catch (e) {
+    // Non-blocking cleanup failure
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// OUTPUT DIRECTORY MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════════
+
 function getRunPaths(runId, projectPath = process.cwd()) {
-  const runDir = path.join(projectPath, ".vibecheck", "runs", runId);
+  const baseDir = path.join(projectPath, CONFIG.DIR_NAME);
+  const runDir = path.join(baseDir, "runs", runId);
+  const latestLink = path.join(baseDir, "runs", "latest");
   const artifactsDir = path.join(runDir, "artifacts");
   
   // Ensure directories exist
-  if (!fs.existsSync(runDir)) fs.mkdirSync(runDir, { recursive: true });
-  if (!fs.existsSync(artifactsDir)) fs.mkdirSync(artifactsDir, { recursive: true });
+  fs.mkdirSync(artifactsDir, { recursive: true });
+  
+  // Update 'latest' symlink for easy debugging
+  updateSymlink(runDir, latestLink);
   
+  // Trigger cleanup async (don't block the CLI)
+  setTimeout(() => rotateLogs(path.join(baseDir, "runs")), 100).unref();
+
   return {
     runDir,
     artifactsDir,
     manifestPath: path.join(runDir, "manifest.json"),
     commandPath: path.join(runDir, "command.json"),
+    crashPath: path.join(runDir, "crash.json"),
   };
 }
 
-/**
- * Save artifact to run directory
- */
 function saveArtifact(runId, name, data, type = "json") {
   const { artifactsDir } = getRunPaths(runId);
   const artifactPath = path.join(artifactsDir, `${name}.${type}`);
   
   if (type === "json") {
-    fs.writeFileSync(artifactPath, JSON.stringify(data, null, 2));
+    safeWriteJson(artifactPath, data);
   } else {
     fs.writeFileSync(artifactPath, data);
   }
@@ -65,9 +171,6 @@ function saveArtifact(runId, name, data, type = "json") {
 // JSON OUTPUT SCHEMA
 // ═══════════════════════════════════════════════════════════════════════════════
 
-/**
- * Create standardized JSON output
- */
 function createJsonOutput(options) {
   const {
     runId,
@@ -82,84 +185,71 @@ function createJsonOutput(options) {
     artifacts = [],
   } = options;
   
-  const output = {
-    runId,
-    command,
-    timestamp: new Date().toISOString(),
-    duration: startTime ? Date.now() - new Date(startTime).getTime() : null,
-    exitCode,
-    verdict,
-    result,
+  return {
     meta: {
-      tier,
-      version,
-      path: projectPath,
+      schemaVersion: "2.0.0",
+      generatedAt: new Date().toISOString(),
+      tool: { name: "vibecheck", version, tier },
+      system: getSystemContext(),
+      git: getGitContext(),
+      ci: getCiContext(),
+    },
+    run: {
+      id: runId,
+      command,
+      durationMs: startTime ? Date.now() - new Date(startTime).getTime() : 0,
+      exitCode,
+      verdict,
     },
+    // The actual data payload
+    data: result,
+    // Links to files created
     artifacts: artifacts.map(art => ({
       type: art.type,
-      path: path.relative(projectPath, art.path),
+      name: path.basename(art.path),
+      path: path.relative(projectPath, art.path), // Relative for portability
       description: art.description,
     })),
   };
-  
-  return output;
 }
 
-/**
- * Write JSON output to file or stdout
- */
 function writeJsonOutput(output, outputPath) {
   const jsonString = JSON.stringify(output, null, 2);
   
   if (outputPath) {
-    fs.writeFileSync(outputPath, jsonString);
+    // If output is a file, write to it
+    safeWriteJson(outputPath, output);
     return outputPath;
   } else {
-    console.log(jsonString);
+    // If stdout, we must ensure we don't break pipe consumers
+    process.stdout.write(jsonString + '\n');
     return null;
   }
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// VERDCT MAPPING
+// VERDICT MAPPING
 // ═══════════════════════════════════════════════════════════════════════════════
 
-/**
- * Map exit codes to verdict strings
- */
 function exitCodeToVerdict(exitCode) {
-  switch (exitCode) {
-    case 0: return "SHIP";
-    case 1: return "WARN";
-    case 2: return "BLOCK";
-    case 3: return "FEATURE_DENIED";
-    case 4: return "INVALID_INPUT";
-    case 5: return "INTERNAL_ERROR";
-    default: return "UNKNOWN";
-  }
-}
-
-/**
- * Map verdict to exit code
- */
-function verdictToExitCode(verdict) {
-  switch (verdict?.toUpperCase()) {
-    case "SHIP": return 0;
-    case "WARN": return 1;
-    case "BLOCK": return 2;
-    case "FEATURE_DENIED": return 3;
-    case "INVALID_INPUT": return 4;
-    case "INTERNAL_ERROR": return 5;
-    default: return 5;
-  }
+  const map = {
+    0: "SHIP",
+    1: "WARN",
+    2: "BLOCK",
+    3: "FEATURE_DENIED",
+    4: "INVALID_INPUT",
+    5: "INTERNAL_ERROR"
+  };
+  return map[exitCode] || "UNKNOWN";
 }
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// COMMAND WRAPPER
+// COMMAND WRAPPER (The Safety Net)
 // ═══════════════════════════════════════════════════════════════════════════════
 
 /**
- * Wrap a command runner with standard output handling
+ * Wrap a command runner with world-class output handling,
+ * telemetry, and crash protection.
  */
 async function withStandardOutput(commandFn, options = {}) {
   const {
@@ -168,104 +258,88 @@ async function withStandardOutput(commandFn, options = {}) {
     runId = generateRunId(),
     json = false,
     output = null,
-    ci = false,
-    verbose = false,
     tier = "free",
     version = "1.0.0",
   } = options;
   
-  // Initialize paths
   const paths = getRunPaths(runId);
   const artifacts = [];
   
+  // Artifact helper injected into the command
+  const artifactSaver = (name, data, type = 'json') => {
+    try {
+      const artifactPath = saveArtifact(runId, name, data, type);
+      artifacts.push({ type, path: artifactPath, description: name });
+      return artifactPath;
+    } catch (e) {
+      console.error(chalk.yellow(`⚠️ Warning: Failed to save artifact ${name}: ${e.message}`));
+      return null;
+    }
+  };
+
   try {
-    // Run the command
+    // Execute Command
     const result = await commandFn({
       runId,
       paths,
-      saveArtifact: (name, data, type) => {
-        const artifactPath = saveArtifact(runId, name, data, type);
-        artifacts.push({
-          type,
-          path: artifactPath,
-          description: `${name} artifact`,
-        });
-        return artifactPath;
-      },
+      saveArtifact: artifactSaver,
     });
     
-    // Extract exit code and verdict
-    const exitCode = typeof result === "number" ? result : result.exitCode || 0;
+    // Normalize Result
+    const exitCode = typeof result === "number" ? result : (result.exitCode ?? 0);
     const verdict = result.verdict || exitCodeToVerdict(exitCode);
-    
-    // Create JSON output if requested
+    const resultData = typeof result === "object" ? result : {};
+
+    const outputObj = createJsonOutput({
+      runId, command, startTime, exitCode, verdict,
+      result: resultData, tier, version, artifacts
+    });
+
+    // 1. Always save to internal history
+    safeWriteJson(paths.commandPath, outputObj);
+
+    // 2. If JSON requested by user, print/write it
     if (json) {
-      const jsonOutput = createJsonOutput({
-        runId,
-        command,
-        startTime,
-        exitCode,
-        verdict,
-        result: typeof result === "object" ? result : {},
-        tier,
-        version,
-        artifacts,
-      });
-      
-      writeJsonOutput(jsonOutput, output);
-    }
-    
-    // Save command output to run directory
-    const commandOutput = {
-      exitCode,
-      verdict,
-      result: typeof result === "object" ? result : {},
-      artifacts,
-    };
-    fs.writeFileSync(paths.commandPath, JSON.stringify(commandOutput, null, 2));
-    
-    // Update stable pointer
-    const lastPath = path.join(process.cwd(), ".vibecheck", "last", `${command}.json`);
-    if (!fs.existsSync(path.dirname(lastPath))) {
-      fs.mkdirSync(path.dirname(lastPath), { recursive: true });
+      writeJsonOutput(outputObj, output);
     }
-    fs.writeFileSync(lastPath, JSON.stringify(commandOutput, null, 2));
-    
+
     return exitCode;
+
   } catch (error) {
-    // Handle errors consistently
+    // 🛑 CRITICAL ERROR HANDLING
     const exitCode = error.exitCode || 5;
     const verdict = "INTERNAL_ERROR";
     
+    const errorData = {
+      message: error.message,
+      stack: error.stack,
+      code: error.code || 'UNKNOWN',
+    };
+
+    const outputObj = createJsonOutput({
+      runId, command, startTime, exitCode, verdict,
+      result: { error: errorData }, tier, version, artifacts
+    });
+
+    // Save crash report to disk
+    safeWriteJson(paths.crashPath, outputObj);
+    safeWriteJson(paths.commandPath, outputObj);
+
     if (json) {
-      const jsonOutput = createJsonOutput({
-        runId,
-        command,
-        startTime,
-        exitCode,
-        verdict,
-        result: {
-          error: error.message,
-          stack: error.stack,
-        },
-        tier,
-        version,
-        artifacts,
-      });
-      
-      writeJsonOutput(jsonOutput, output);
+      writeJsonOutput(outputObj, output);
+    } else {
+      // VISUAL CRASH REPORT
+      console.error('');
+      console.error(chalk.bgRed.white.bold(` 🛑 SYSTEM ALERT: INTERNAL CRASH `));
+      console.error(chalk.red('─'.repeat(CONFIG.WIDTH)));
+      console.error(`${chalk.bold('Error:')}   ${error.message}`);
+      console.error(`${chalk.bold('Run ID:')}  ${runId}`);
+      console.error(`${chalk.bold('Log:')}     ${chalk.cyan(paths.crashPath)}`);
+      console.error(chalk.red('─'.repeat(CONFIG.WIDTH)));
+      console.error('');
     }
-    
-    // Save error to run directory
-    const commandOutput = {
-      exitCode,
-      verdict,
-      error: error.message,
-      artifacts,
-    };
-    fs.writeFileSync(paths.commandPath, JSON.stringify(commandOutput, null, 2));
-    
-    throw error;
+
+    throw error; // Re-throw so the process actually exits with error
   }
 }
 
@@ -273,13 +347,10 @@ async function withStandardOutput(commandFn, options = {}) {
 // STANDARD FLAGS PARSER
 // ═══════════════════════════════════════════════════════════════════════════════
 
-/**
- * Parse standard CLI flags
- */
 function parseStandardFlags(args) {
   const flags = {
     json: false,
-    ci: false,
+    ci: !!process.env.CI, // Auto-detect CI
     path: process.cwd(),
     output: null,
     verbose: false,
@@ -287,74 +358,30 @@ function parseStandardFlags(args) {
     help: false,
     version: false,
     debug: false,
-    quiet: false,
   };
   
-  const parsed = args.filter(arg => {
-    switch (arg) {
-      case "--json":
-      case "-j":
-        flags.json = true;
-        return false;
-      case "--ci":
-        flags.ci = true;
-        return false;
-      case "--verbose":
-      case "-v":
-        flags.verbose = true;
-        return false;
-      case "--strict":
-        flags.strict = true;
-        return false;
-      case "--help":
-      case "-h":
-        flags.help = true;
-        return false;
-      case "--version":
-      case "-V":
-        flags.version = true;
-        return false;
-      case "--debug":
-      case "-d":
-        flags.debug = true;
-        return false;
-      case "--quiet":
-      case "-q":
-        flags.quiet = true;
-        return false;
-      default:
-        if (arg.startsWith("--path=")) {
-          flags.path = arg.split("=")[1];
-          return false;
-        } else if (arg.startsWith("-p")) {
-          const idx = args.indexOf(arg);
-          if (idx < args.length - 1) {
-            flags.path = args[idx + 1];
-            args.splice(idx, 2);
-            return false;
-          }
-        } else if (arg.startsWith("--output=")) {
-          flags.output = arg.split("=")[1];
-          return false;
-        } else if (arg.startsWith("-o")) {
-          const idx = args.indexOf(arg);
-          if (idx < args.length - 1) {
-            flags.output = args[idx + 1];
-            args.splice(idx, 2);
-            return false;
-          }
-        }
-        return true;
-    }
-  });
+  const parsed = [];
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === '--json' || arg === '-j') flags.json = true;
+    else if (arg === '--ci') flags.ci = true;
+    else if (arg === '--verbose' || arg === '-v') flags.verbose = true;
+    else if (arg === '--strict') flags.strict = true;
+    else if (arg === '--help' || arg === '-h') flags.help = true;
+    else if (arg === '--version' || arg === '-V') flags.version = true;
+    else if (arg === '--debug' || arg === '-d') flags.debug = true;
+    else if (arg.startsWith('--path=')) flags.path = arg.split('=')[1];
+    else if (arg === '-p' && args[i+1]) { flags.path = args[++i]; }
+    else if (arg.startsWith('--output=')) flags.output = arg.split('=')[1];
+    else if (arg === '-o' && args[i+1]) { flags.output = args[++i]; }
+    else parsed.push(arg);
+  }
   
   return { flags, parsed };
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// EXPORTS
-// ═══════════════════════════════════════════════════════════════════════════════
-
 module.exports = {
   generateRunId,
   getRunPaths,
@@ -362,7 +389,6 @@ module.exports = {
   createJsonOutput,
   writeJsonOutput,
   exitCodeToVerdict,
-  verdictToExitCode,
   withStandardOutput,
   parseStandardFlags,
-};
+};