@nathapp/nax 0.18.1

package/src/logger/logger.ts

@@ -0,0 +1,298 @@
+import { appendFileSync } from "node:fs";
+import { type FormatterOptions, type VerbosityMode, formatLogEntry } from "../logging/index.js";
+import { formatConsole, formatJsonl } from "./formatters.js";
+import type { LogEntry, LogLevel, LoggerOptions, StoryLogger } from "./types.js";
+
+/**
+ * Severity ordering for log levels (lower number = more severe)
+ */
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+};
+
+/**
+ * Singleton logger instance
+ */
+let instance: Logger | null = null;
+
+/**
+ * Structured logger with level gating and dual output (console + JSONL file)
+ *
+ * @example
+ * ```typescript
+ * // Initialize logger (usually in CLI entry point)
+ * initLogger({ level: "info", filePath: "nax/features/auth/runs/run-123.jsonl" });
+ *
+ * // Use logger throughout application
+ * const logger = getLogger();
+ * logger.info("routing", "Task classified", { complexity: "simple" });
+ *
+ * // Story-scoped logger
+ * const storyLogger = logger.withStory("user-auth-001");
+ * storyLogger.info("agent.start", "Starting agent session");
+ * ```
+ */
+export class Logger {
+  private readonly level: LogLevel;
+  private readonly filePath?: string;
+  private readonly useChalk: boolean;
+  private readonly formatterMode?: VerbosityMode;
+  private readonly headless: boolean;
+
+  constructor(options: LoggerOptions) {
+    this.level = options.level;
+    this.filePath = options.filePath;
+    this.useChalk = options.useChalk ?? true;
+    this.formatterMode = options.formatterMode;
+    this.headless = options.headless ?? false;
+
+    // Ensure parent directory exists if file path provided
+    if (this.filePath) {
+      this.initFileDirectory();
+    }
+  }
+
+  /**
+   * Create parent directory for log file if it doesn't exist
+   */
+  private initFileDirectory(): void {
+    if (!this.filePath) return;
+
+    try {
+      const dir = this.filePath.substring(0, this.filePath.lastIndexOf("/"));
+      if (dir) {
+        Bun.spawnSync(["mkdir", "-p", dir]);
+      }
+    } catch (error) {
+      console.error(`[logger] Failed to create log directory: ${error}`);
+    }
+  }
+
+  /**
+   * Check if a log level should be displayed on console
+   */
+  private shouldLog(level: LogLevel): boolean {
+    return LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[this.level];
+  }
+
+  /**
+   * Internal log method — writes to console (if level permits) and file (always)
+   */
+  private log(level: LogLevel, stage: string, message: string, data?: Record<string, unknown>, storyId?: string): void {
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      stage,
+      message,
+      ...(storyId && { storyId }),
+      ...(data && { data }),
+    };
+
+    // Console output (level-gated)
+    if (this.shouldLog(level)) {
+      let consoleOutput: string | null = null;
+
+      // Use formatter in headless mode if mode is specified
+      if (this.headless && this.formatterMode) {
+        const formatterOptions: FormatterOptions = {
+          mode: this.formatterMode,
+          useColor: this.useChalk,
+        };
+        const formatted = formatLogEntry(entry, formatterOptions);
+        if (formatted.shouldDisplay) {
+          consoleOutput = formatted.output;
+        }
+        // If formatter says not to display, consoleOutput stays null
+      } else {
+        // Default console formatting (existing behavior)
+        consoleOutput = this.useChalk ? formatConsole(entry) : this.formatPlainConsole(entry);
+      }
+
+      // Only log if we have output to display
+      if (consoleOutput !== null) {
+        console.log(consoleOutput);
+      }
+    }
+
+    // File output (always write all levels)
+    if (this.filePath) {
+      this.writeToFile(entry);
+    }
+  }
+
+  /**
+   * Plain console format (no chalk) — used when useChalk is false
+   */
+  private formatPlainConsole(entry: LogEntry): string {
+    const timestamp = new Date(entry.timestamp).toLocaleTimeString("en-US", {
+      hour12: false,
+    });
+    const parts = [`[${timestamp}]`, `[${entry.stage}]`];
+    if (entry.storyId) {
+      parts.push(`[${entry.storyId}]`);
+    }
+    parts.push(entry.message);
+    let output = parts.join(" ");
+    if (entry.data && Object.keys(entry.data).length > 0) {
+      output += `\n${JSON.stringify(entry.data, null, 2)}`;
+    }
+    return output;
+  }
+
+  /**
+   * Write JSONL line to file (synchronous append)
+   */
+  private writeToFile(entry: LogEntry): void {
+    if (!this.filePath) return;
+
+    try {
+      const line = `${formatJsonl(entry)}\n`;
+      // Use Node.js fs for simple synchronous append
+      appendFileSync(this.filePath, line, "utf8");
+    } catch (error) {
+      console.error(`[logger] Failed to write to log file: ${error}`);
+    }
+  }
+
+  /**
+   * Log an error message
+   */
+  error(stage: string, message: string, data?: Record<string, unknown>): void {
+    this.log("error", stage, message, data);
+  }
+
+  /**
+   * Log a warning message
+   */
+  warn(stage: string, message: string, data?: Record<string, unknown>): void {
+    this.log("warn", stage, message, data);
+  }
+
+  /**
+   * Log an info message
+   */
+  info(stage: string, message: string, data?: Record<string, unknown>): void {
+    this.log("info", stage, message, data);
+  }
+
+  /**
+   * Log a debug message
+   */
+  debug(stage: string, message: string, data?: Record<string, unknown>): void {
+    this.log("debug", stage, message, data);
+  }
+
+  /**
+   * Create a story-scoped logger that auto-injects storyId
+   *
+   * @param storyId - Story identifier to inject into all log calls
+   * @returns StoryLogger instance
+   *
+   * @example
+   * ```typescript
+   * const logger = getLogger();
+   * const storyLogger = logger.withStory("user-auth-001");
+   * storyLogger.info("agent.start", "Starting agent"); // storyId auto-added
+   * ```
+   */
+  withStory(storyId: string): StoryLogger {
+    return {
+      error: (stage: string, message: string, data?: Record<string, unknown>) =>
+        this.log("error", stage, message, data, storyId),
+      warn: (stage: string, message: string, data?: Record<string, unknown>) =>
+        this.log("warn", stage, message, data, storyId),
+      info: (stage: string, message: string, data?: Record<string, unknown>) =>
+        this.log("info", stage, message, data, storyId),
+      debug: (stage: string, message: string, data?: Record<string, unknown>) =>
+        this.log("debug", stage, message, data, storyId),
+    };
+  }
+
+  /**
+   * Close logger (cleanup method for shutdown)
+   * Note: Bun.write handles file operations automatically, no manual cleanup needed
+   */
+  close(): void {
+    // No-op: Bun handles file operations internally
+  }
+}
+
+/**
+ * Initialize the singleton logger instance
+ *
+ * @param options - Logger configuration options
+ * @throws Error if logger is already initialized
+ *
+ * @example
+ * ```typescript
+ * initLogger({
+ *   level: "info",
+ *   filePath: "nax/features/auth/runs/2026-02-20T10-30-00Z.jsonl"
+ * });
+ * ```
+ */
+export function initLogger(options: LoggerOptions): Logger {
+  if (instance) {
+    throw new Error("Logger already initialized. Call getLogger() to access existing instance.");
+  }
+  instance = new Logger(options);
+  return instance;
+}
+
+/**
+ * Get the singleton logger instance
+ *
+ * @throws Error if logger has not been initialized
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = getLogger();
+ * logger.info("routing", "Task classified");
+ * ```
+ */
+/**
+ * No-op logger for tests/environments where logger isn't initialized
+ */
+const noopLogger: Logger = new Logger({ level: "error", useChalk: false, headless: false });
+
+export function getLogger(): Logger {
+  if (!instance) {
+    return noopLogger;
+  }
+  return instance;
+}
+
+/**
+ * Safely get logger instance, returns null if not initialized
+ *
+ * @returns Logger instance or null if not initialized
+ *
+ * @example
+ * ```typescript
+ * const logger = getSafeLogger();
+ * logger?.info("routing", "Task classified");
+ * ```
+ */
+export function getSafeLogger(): Logger | null {
+  try {
+    const logger = getLogger();
+    return logger === noopLogger ? null : logger;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reset logger singleton (for testing only)
+ * @internal
+ */
+export function resetLogger(): void {
+  if (instance) {
+    instance.close();
+  }
+  instance = null;
+}

package/src/logger/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Log level type — ordered from most to least severe
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+
+/**
+ * Structured log entry format
+ */
+export interface LogEntry {
+  /** ISO timestamp when log was created */
+  timestamp: string;
+  /** Severity level */
+  level: LogLevel;
+  /** Pipeline stage or module name */
+  stage: string;
+  /** Optional story identifier for context */
+  storyId?: string;
+  /** Human-readable message */
+  message: string;
+  /** Optional structured metadata */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Logger initialization options
+ */
+export interface LoggerOptions {
+  /** Minimum log level for console output (file gets all levels) */
+  level: LogLevel;
+  /** Optional path to JSONL log file */
+  filePath?: string;
+  /** Whether to use chalk for console formatting (default: true) */
+  useChalk?: boolean;
+  /** Formatter verbosity mode for console output (default: uses formatConsole) */
+  formatterMode?: "quiet" | "normal" | "verbose" | "json";
+  /** Whether running in headless mode (enables formatter) */
+  headless?: boolean;
+}
+
+/**
+ * Story-scoped logger that auto-injects storyId into all log calls
+ */
+export interface StoryLogger {
+  error(stage: string, message: string, data?: Record<string, unknown>): void;
+  warn(stage: string, message: string, data?: Record<string, unknown>): void;
+  info(stage: string, message: string, data?: Record<string, unknown>): void;
+  debug(stage: string, message: string, data?: Record<string, unknown>): void;
+}

package/src/logging/formatter.ts

@@ -0,0 +1,355 @@
+/**
+ * Human-friendly logging formatter with verbosity levels
+ *
+ * Transforms JSONL log entries into readable output with emoji indicators
+ * and supports multiple verbosity modes: quiet, normal, verbose, json
+ */
+
+import chalk from "chalk";
+import type { LogEntry } from "../logger/types.js";
+import { EMOJI, type FormatterOptions, type RunSummary } from "./types.js";
+
+/**
+ * Formatted output entry
+ */
+export interface FormattedEntry {
+  /** Formatted string ready for console output */
+  output: string;
+  /** Whether this entry should be shown in the current verbosity mode */
+  shouldDisplay: boolean;
+}
+
+/**
+ * Format a timestamp to local timezone HH:MM:SS
+ */
+export function formatTimestamp(isoTimestamp: string): string {
+  const date = new Date(isoTimestamp);
+  return date.toLocaleTimeString("en-US", {
+    hour12: false,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+}
+
+/**
+ * Format duration in milliseconds to human-readable format
+ */
+export function formatDuration(durationMs: number): string {
+  if (durationMs < 1000) {
+    return `${durationMs}ms`;
+  }
+  if (durationMs < 60000) {
+    return `${(durationMs / 1000).toFixed(1)}s`;
+  }
+  const minutes = Math.floor(durationMs / 60000);
+  const seconds = Math.floor((durationMs % 60000) / 1000);
+  return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * Format cost in dollars
+ */
+export function formatCost(cost: number): string {
+  return `$${cost.toFixed(4)}`;
+}
+
+/**
+ * Get emoji for stage name
+ */
+function getStageEmoji(stage: string): string {
+  if (stage.includes("routing")) return EMOJI.routing;
+  if (stage.includes("execution") || stage.includes("agent")) return EMOJI.execution;
+  if (stage.includes("review")) return EMOJI.review;
+  if (stage.includes("tdd")) return EMOJI.tdd;
+  return EMOJI.info;
+}
+
+/**
+ * Check if entry should be displayed based on verbosity mode
+ */
+function shouldDisplay(entry: LogEntry, mode: string): boolean {
+  if (mode === "json") return true;
+  if (mode === "quiet") {
+    // Only show critical events: run start/end, story pass/fail
+    return (
+      entry.stage === "run.start" ||
+      entry.stage === "run.end" ||
+      entry.stage === "story.complete" ||
+      entry.level === "error"
+    );
+  }
+  if (mode === "verbose") return true;
+
+  // Normal mode: filter out debug logs
+  return entry.level !== "debug";
+}
+
+/**
+ * Format a log entry for human-readable output
+ *
+ * Supports different verbosity modes and styling options
+ */
+export function formatLogEntry(entry: LogEntry, options: FormatterOptions): FormattedEntry {
+  const { mode, useColor = true } = options;
+
+  // JSON mode: pass through raw JSONL
+  if (mode === "json") {
+    return {
+      output: JSON.stringify(entry),
+      shouldDisplay: true,
+    };
+  }
+
+  // Check if should display based on mode
+  if (!shouldDisplay(entry, mode)) {
+    return {
+      output: "",
+      shouldDisplay: false,
+    };
+  }
+
+  const timestamp = formatTimestamp(entry.timestamp);
+  const colorize = useColor ? chalk : createNoopChalk();
+
+  // Handle special stages with custom formatting
+  if (entry.stage === "run.start") {
+    return formatRunStart(entry, colorize, timestamp, mode);
+  }
+
+  if (entry.stage === "story.start" || entry.stage === "iteration.start") {
+    return formatStoryStart(entry, colorize, timestamp, mode);
+  }
+
+  if (entry.stage === "story.complete" || entry.stage === "agent.complete") {
+    return formatStoryComplete(entry, colorize, timestamp, mode);
+  }
+
+  if (entry.stage.includes("tdd") && entry.message.startsWith("→ Session:")) {
+    return formatTDDSession(entry, colorize, timestamp, mode);
+  }
+
+  // Default formatting for other entries
+  return formatDefault(entry, colorize, timestamp, mode);
+}
+
+/**
+ * Format run start event
+ */
+function formatRunStart(entry: LogEntry, c: ChalkLike, timestamp: string, mode: string): FormattedEntry {
+  const data = entry.data as Record<string, unknown>;
+  const lines: string[] = [];
+
+  lines.push("");
+  lines.push(c.bold(c.blue("═".repeat(60))));
+  lines.push(c.bold(c.blue(`  ${EMOJI.storyStart} NAX RUN STARTED`)));
+  lines.push(c.blue("═".repeat(60)));
+  lines.push(`  ${c.gray("Time:")}     ${timestamp}`);
+  lines.push(`  ${c.gray("Feature:")}  ${c.cyan(String(data.feature || "unknown"))}`);
+  lines.push(`  ${c.gray("Run ID:")}   ${c.dim(String(data.runId || "unknown"))}`);
+  lines.push(`  ${c.gray("Workdir:")}  ${c.dim(String(data.workdir || "."))}`);
+  lines.push(c.blue("═".repeat(60)));
+  lines.push("");
+
+  return {
+    output: lines.join("\n"),
+    shouldDisplay: true,
+  };
+}
+
+/**
+ * Format story start event
+ */
+function formatStoryStart(entry: LogEntry, c: ChalkLike, timestamp: string, mode: string): FormattedEntry {
+  const data = entry.data as Record<string, unknown>;
+  const storyId = String(data.storyId || entry.storyId || "unknown");
+  const title = String(data.storyTitle || data.title || "Untitled story");
+  const complexity = typeof data.complexity === "string" ? data.complexity : "unknown";
+  const tier = typeof data.modelTier === "string" ? data.modelTier : "unknown";
+  const attempt = typeof data.attempt === "number" ? data.attempt : 1;
+
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(c.bold(`${EMOJI.storyStart} ${c.cyan(storyId)}: ${title}`));
+
+  if (mode === "verbose") {
+    lines.push(`  ${c.gray("├─")} Complexity: ${c.yellow(complexity)}`);
+    lines.push(`  ${c.gray("├─")} Tier: ${c.magenta(tier)}`);
+    if (attempt > 1) {
+      lines.push(`  ${c.gray("└─")} Attempt: ${c.yellow(`#${attempt}`)} ${EMOJI.retry}`);
+    } else {
+      lines.push(`  ${c.gray("└─")} Status: ${c.green("starting")}`);
+    }
+  } else {
+    const metadata = [complexity, tier];
+    if (attempt > 1) metadata.push(`attempt #${attempt} ${EMOJI.retry}`);
+    lines.push(`  ${c.gray(metadata.join(" • "))}`);
+  }
+
+  return {
+    output: lines.join("\n"),
+    shouldDisplay: true,
+  };
+}
+
+/**
+ * Format story completion event
+ */
+function formatStoryComplete(entry: LogEntry, c: ChalkLike, timestamp: string, mode: string): FormattedEntry {
+  const data = entry.data as Record<string, unknown>;
+  const storyId = String(data.storyId || entry.storyId || "unknown");
+  const success = data.success ?? true;
+  const cost =
+    typeof data.cost === "number" ? data.cost : typeof data.estimatedCost === "number" ? data.estimatedCost : 0;
+  const duration = typeof data.durationMs === "number" ? data.durationMs : 0;
+  const action = data.finalAction || data.action;
+
+  const emoji = success ? EMOJI.success : action === "escalate" ? EMOJI.retry : EMOJI.failure;
+  const statusColor = success ? c.green : action === "escalate" ? c.yellow : c.red;
+  const status = success ? "PASSED" : action === "escalate" ? "ESCALATED" : "FAILED";
+
+  const lines: string[] = [];
+  lines.push(statusColor(`  ${emoji} ${c.bold(storyId)}: ${status}`));
+
+  if (mode === "verbose" || mode === "normal") {
+    const metadata: string[] = [];
+    if (cost > 0) metadata.push(`${EMOJI.cost} ${formatCost(cost)}`);
+    if (duration > 0) metadata.push(`${EMOJI.duration} ${formatDuration(duration)}`);
+    if (metadata.length > 0) {
+      lines.push(`     ${c.gray(metadata.join("  "))}`);
+    }
+  }
+
+  if (mode === "verbose" && data.reason) {
+    lines.push(`     ${c.gray(`Reason: ${data.reason}`)}`);
+  }
+
+  lines.push("");
+
+  return {
+    output: lines.join("\n"),
+    shouldDisplay: true,
+  };
+}
+
+/**
+ * Format TDD session start
+ */
+function formatTDDSession(entry: LogEntry, c: ChalkLike, timestamp: string, mode: string): FormattedEntry {
+  if (mode === "quiet") {
+    return { output: "", shouldDisplay: false };
+  }
+
+  const data = entry.data as Record<string, unknown>;
+  const role = typeof data.role === "string" ? data.role : "unknown";
+  const roleLabel = role.replace(/-/g, " ").replace(/\b\w/g, (l: string) => l.toUpperCase());
+
+  return {
+    output: `  ${c.gray("│")}  ${EMOJI.tdd} ${c.cyan(roleLabel)}`,
+    shouldDisplay: true,
+  };
+}
+
+/**
+ * Format default log entry
+ */
+function formatDefault(entry: LogEntry, c: ChalkLike, timestamp: string, mode: string): FormattedEntry {
+  const levelEmoji = entry.level === "error" ? EMOJI.failure : entry.level === "warn" ? EMOJI.warning : EMOJI.info;
+  const levelColor = entry.level === "error" ? c.red : entry.level === "warn" ? c.yellow : c.gray;
+  const stageEmoji = getStageEmoji(entry.stage);
+
+  const parts = [c.gray(`[${timestamp}]`), levelColor(`${levelEmoji} ${entry.stage}`)];
+
+  if (entry.storyId) {
+    parts.push(c.dim(`[${entry.storyId}]`));
+  }
+
+  parts.push(entry.message);
+
+  let output = parts.join(" ");
+
+  // Include data in verbose mode
+  if (mode === "verbose" && entry.data && Object.keys(entry.data).length > 0) {
+    output += `\n${c.gray(JSON.stringify(entry.data, null, 2))}`;
+  }
+
+  return {
+    output,
+    shouldDisplay: true,
+  };
+}
+
+/**
+ * Format run summary footer
+ */
+export function formatRunSummary(summary: RunSummary, options: FormatterOptions): string {
+  const { mode, useColor = true } = options;
+
+  if (mode === "json") {
+    return JSON.stringify(summary);
+  }
+
+  const c = useColor ? chalk : createNoopChalk();
+  const lines: string[] = [];
+
+  lines.push("");
+  lines.push(c.blue("═".repeat(60)));
+  lines.push(c.bold(c.blue(`  ${EMOJI.storyComplete} RUN SUMMARY`)));
+  lines.push(c.blue("═".repeat(60)));
+
+  const successRate = summary.total > 0 ? ((summary.passed / summary.total) * 100).toFixed(1) : "0.0";
+  const statusColor = summary.failed === 0 ? c.green : summary.passed > summary.failed ? c.yellow : c.red;
+
+  lines.push(`  ${c.gray("Total:")}    ${c.bold(summary.total.toString())}`);
+  lines.push(`  ${c.green(`${EMOJI.success} Passed:`)}  ${c.bold(summary.passed.toString())}`);
+
+  if (summary.failed > 0) {
+    lines.push(`  ${c.red(`${EMOJI.failure} Failed:`)}  ${c.bold(summary.failed.toString())}`);
+  }
+
+  if (summary.skipped > 0) {
+    lines.push(`  ${c.yellow(`${EMOJI.skip} Skipped:`)} ${c.bold(summary.skipped.toString())}`);
+  }
+
+  lines.push(`  ${c.gray("Success:")}  ${statusColor(c.bold(`${successRate}%`))}`);
+  lines.push(c.blue("─".repeat(60)));
+  lines.push(`  ${EMOJI.duration} Duration: ${c.bold(formatDuration(summary.durationMs))}`);
+  lines.push(`  ${EMOJI.cost} Cost:     ${c.bold(formatCost(summary.totalCost))}`);
+  lines.push(c.blue("═".repeat(60)));
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/**
+ * Chalk-like interface for no-op mode (no colors)
+ */
+interface ChalkLike {
+  bold: (s: string) => string;
+  dim: (s: string) => string;
+  gray: (s: string) => string;
+  red: (s: string) => string;
+  green: (s: string) => string;
+  yellow: (s: string) => string;
+  blue: (s: string) => string;
+  magenta: (s: string) => string;
+  cyan: (s: string) => string;
+}
+
+/**
+ * Create a no-op chalk instance (returns strings unchanged)
+ */
+function createNoopChalk(): ChalkLike {
+  const noop = (s: string) => s;
+  return {
+    bold: noop,
+    dim: noop,
+    gray: noop,
+    red: noop,
+    green: noop,
+    yellow: noop,
+    blue: noop,
+    magenta: noop,
+    cyan: noop,
+  };
+}