@nathapp/nax 0.50.3 → 0.51.0

package/src/logging/formatter.ts

@@ -1,355 +0,0 @@
-/**
- * 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,
-  };
-}

package/src/logging/index.ts

@@ -1,22 +0,0 @@
-/**
- * Logging formatter module
- *
- * Provides human-friendly log formatting with multiple verbosity levels
- */
-
-export {
-  formatLogEntry,
-  formatRunSummary,
-  formatTimestamp,
-  formatDuration,
-  formatCost,
-  type FormattedEntry,
-} from "./formatter.js";
-export {
-  EMOJI,
-  type VerbosityMode,
-  type FormatterOptions,
-  type RunSummary,
-  type StoryStartData,
-  type StageResultData,
-} from "./types.js";

package/src/logging/types.ts

@@ -1,93 +0,0 @@
-/**
- * Logging formatter types for human-readable output
- */
-
-import type { LogEntry } from "../logger/types.js";
-
-/**
- * Verbosity mode for log formatting
- */
-export type VerbosityMode = "quiet" | "normal" | "verbose" | "json";
-
-/**
- * Emoji indicators for different log events
- */
-export const EMOJI = {
-  // Status indicators
-  success: "✓",
-  failure: "✗",
-  warning: "⚠",
-  info: "ℹ",
-  skip: "⊘",
-
-  // Stage/process indicators
-  routing: "🎯",
-  execution: "⚙️",
-  review: "🔍",
-  tdd: "🔄",
-  agent: "🤖",
-  cost: "💰",
-  duration: "⏱️",
-
-  // Story progress
-  storyStart: "▶",
-  storyComplete: "●",
-  retry: "↻",
-} as const;
-
-/**
- * Run summary statistics
- */
-export interface RunSummary {
-  /** Total stories in run */
-  total: number;
-  /** Stories that passed */
-  passed: number;
-  /** Stories that failed */
-  failed: number;
-  /** Stories that were skipped */
-  skipped: number;
-  /** Total run duration in milliseconds */
-  durationMs: number;
-  /** Total cost in dollars */
-  totalCost: number;
-  /** Run start timestamp */
-  startedAt: string;
-  /** Run completion timestamp */
-  completedAt?: string;
-}
-
-/**
- * Story start event data
- */
-export interface StoryStartData {
-  storyId: string;
-  title: string;
-  complexity?: string;
-  modelTier?: string;
-  attempt?: number;
-}
-
-/**
- * Stage result event data
- */
-export interface StageResultData {
-  stage: string;
-  success: boolean;
-  action?: "continue" | "skip" | "fail" | "escalate" | "pause";
-  reason?: string;
-  cost?: number;
-  durationMs?: number;
-}
-
-/**
- * Formatter options
- */
-export interface FormatterOptions {
-  /** Verbosity mode */
-  mode: VerbosityMode;
-  /** Whether to use color/emoji (default: true) */
-  useColor?: boolean;
-  /** Timezone for timestamp formatting (default: system timezone) */
-  timezone?: string;
-}

package/src/metrics/aggregator.ts

@@ -1,191 +0,0 @@
-/**
- * Metrics Aggregator
- *
- * Calculates aggregate metrics across all runs.
- */
-
-import type { AggregateMetrics, RunMetrics, StoryMetrics } from "./types";
-
-/**
- * Calculate aggregate metrics across all runs.
- *
- * Analyzes historical data to compute:
- * - Overall success rates
- * - Per-model efficiency
- * - Complexity prediction accuracy
- * - Cost statistics
- *
- * @param runs - Array of all historical run metrics
- * @returns Aggregate metrics
- *
- * @example
- * ```ts
- * const runs = await loadRunMetrics(workdir);
- * const aggregate = calculateAggregateMetrics(runs);
- * console.log(`First pass rate: ${(aggregate.firstPassRate * 100).toFixed(1)}%`);
- * console.log(`Avg cost per story: $${aggregate.avgCostPerStory.toFixed(4)}`);
- * ```
- */
-export function calculateAggregateMetrics(runs: RunMetrics[]): AggregateMetrics {
-  if (runs.length === 0) {
-    return {
-      totalRuns: 0,
-      totalCost: 0,
-      totalStories: 0,
-      firstPassRate: 0,
-      escalationRate: 0,
-      avgCostPerStory: 0,
-      avgCostPerFeature: 0,
-      modelEfficiency: {},
-      complexityAccuracy: {},
-    };
-  }
-
-  // Flatten all story metrics
-  const allStories: StoryMetrics[] = runs.flatMap((run) => run.stories);
-
-  const totalRuns = runs.length;
-  const totalCost = runs.reduce((sum, run) => sum + run.totalCost, 0);
-  const totalStories = allStories.length;
-
-  // Calculate first pass rate
-  const firstPassSuccesses = allStories.filter((s) => s.firstPassSuccess).length;
-  const firstPassRate = totalStories > 0 ? firstPassSuccesses / totalStories : 0;
-
-  // Calculate escalation rate (stories that needed more than 1 attempt)
-  const escalatedStories = allStories.filter((s) => s.attempts > 1).length;
-  const escalationRate = totalStories > 0 ? escalatedStories / totalStories : 0;
-
-  // Average costs
-  const avgCostPerStory = totalStories > 0 ? totalCost / totalStories : 0;
-  const avgCostPerFeature = totalRuns > 0 ? totalCost / totalRuns : 0;
-
-  // Per-model efficiency
-  const modelStats = new Map<
-    string,
-    {
-      attempts: number;
-      successes: number;
-      totalCost: number;
-    }
-  >();
-
-  for (const story of allStories) {
-    const modelKey = story.modelUsed;
-    const existing = modelStats.get(modelKey) || {
-      attempts: 0,
-      successes: 0,
-      totalCost: 0,
-    };
-
-    modelStats.set(modelKey, {
-      attempts: existing.attempts + story.attempts,
-      successes: existing.successes + (story.success ? 1 : 0),
-      totalCost: existing.totalCost + story.cost,
-    });
-  }
-
-  const modelEfficiency: AggregateMetrics["modelEfficiency"] = {};
-  for (const [modelKey, stats] of modelStats) {
-    const passRate = stats.attempts > 0 ? stats.successes / stats.attempts : 0;
-    const avgCost = stats.successes > 0 ? stats.totalCost / stats.successes : 0;
-
-    modelEfficiency[modelKey] = {
-      attempts: stats.attempts,
-      successes: stats.successes,
-      passRate,
-      avgCost,
-      totalCost: stats.totalCost,
-    };
-  }
-
-  // Complexity prediction accuracy
-  const complexityStats = new Map<
-    string,
-    {
-      predicted: number;
-      tierCounts: Map<string, number>;
-      mismatches: number;
-    }
-  >();
-
-  for (const story of allStories) {
-    // Use initialComplexity (first-classify prediction) when available; fall back to complexity
-    const complexity = story.initialComplexity ?? story.complexity;
-    const existing = complexityStats.get(complexity) || {
-      predicted: 0,
-      tierCounts: new Map<string, number>(),
-      mismatches: 0,
-    };
-
-    existing.predicted += 1;
-
-    // Track which tier was actually used
-    const finalTier = story.finalTier;
-    existing.tierCounts.set(finalTier, (existing.tierCounts.get(finalTier) || 0) + 1);
-
-    // Count as mismatch if escalated (initial tier != final tier)
-    if (story.modelTier !== story.finalTier) {
-      existing.mismatches += 1;
-    }
-
-    complexityStats.set(complexity, existing);
-  }
-
-  const complexityAccuracy: AggregateMetrics["complexityAccuracy"] = {};
-  for (const [complexity, stats] of complexityStats) {
-    // Find most common final tier
-    let maxCount = 0;
-    let mostCommonTier = "unknown";
-    for (const [tier, count] of stats.tierCounts) {
-      if (count > maxCount) {
-        maxCount = count;
-        mostCommonTier = tier;
-      }
-    }
-
-    const mismatchRate = stats.predicted > 0 ? stats.mismatches / stats.predicted : 0;
-
-    complexityAccuracy[complexity] = {
-      predicted: stats.predicted,
-      actualTierUsed: mostCommonTier,
-      mismatchRate,
-    };
-  }
-
-  return {
-    totalRuns,
-    totalCost,
-    totalStories,
-    firstPassRate,
-    escalationRate,
-    avgCostPerStory,
-    avgCostPerFeature,
-    modelEfficiency,
-    complexityAccuracy,
-  };
-}
-
-/**
- * Get the last run metrics from the list.
- *
- * @param runs - Array of all run metrics
- * @returns Most recent run, or null if no runs
- *
- * @example
- * ```ts
- * const runs = await loadRunMetrics(workdir);
- * const lastRun = getLastRun(runs);
- * if (lastRun) {
- *   console.log(`Last run: ${lastRun.feature} (${lastRun.storiesCompleted}/${lastRun.totalStories} stories)`);
- * }
- * ```
- */
-export function getLastRun(runs: RunMetrics[]): RunMetrics | null {
-  if (runs.length === 0) {
-    return null;
-  }
-
-  // Runs are appended chronologically, so last element is most recent
-  return runs[runs.length - 1];
-}

package/src/metrics/index.ts

@@ -1,14 +0,0 @@
-/**
- * Metrics Tracking
- *
- * Per-story and per-run cost tracking for data-driven routing optimization.
- */
-
-export type { StoryMetrics, RunMetrics, AggregateMetrics } from "./types";
-export {
-  collectStoryMetrics,
-  collectBatchMetrics,
-  saveRunMetrics,
-  loadRunMetrics,
-} from "./tracker";
-export { calculateAggregateMetrics, getLastRun } from "./aggregator";