@nathapp/nax 0.50.2 → 0.51.0

package/src/interaction/types.ts

@@ -1,170 +0,0 @@
-/**
- * Interaction System Types (v0.15.0)
- *
- * Interactive pipeline core for user prompts, decision gates, and pause/resume.
- */
-
-/** Interaction request types */
-export type InteractionType = "confirm" | "choose" | "input" | "review" | "notify" | "webhook";
-
-/** Pipeline stage where interaction occurs */
-export type InteractionStage = "pre-flight" | "execution" | "review" | "merge" | "cost" | "custom";
-
-/** Fallback behavior when interaction times out */
-export type InteractionFallback = "continue" | "skip" | "escalate" | "abort";
-
-/** Interaction request — sent to plugin */
-export interface InteractionRequest {
-  /** Unique request ID (e.g., 'ix-US003-review-1') */
-  id: string;
-  /** Type of interaction */
-  type: InteractionType;
-  /** Feature name */
-  featureName: string;
-  /** Story ID (optional, for story-level interactions) */
-  storyId?: string;
-  /** Pipeline stage */
-  stage: InteractionStage;
-  /** Human-readable question/summary */
-  summary: string;
-  /** Longer context/details (optional) */
-  detail?: string;
-  /** Options for choose type */
-  options?: Array<{ key: string; label: string; description?: string }>;
-  /** Timeout in milliseconds (optional) */
-  timeout?: number;
-  /** Fallback behavior on timeout */
-  fallback: InteractionFallback;
-  /** Arbitrary metadata */
-  metadata?: Record<string, unknown>;
-  /** Creation timestamp */
-  createdAt: number;
-}
-
-/** Interaction response action */
-export type InteractionAction = "approve" | "reject" | "choose" | "input" | "skip" | "abort";
-
-/** Interaction response — returned from plugin */
-export interface InteractionResponse {
-  /** Request ID this response is for */
-  requestId: string;
-  /** Action taken */
-  action: InteractionAction;
-  /** Value (for choose/input types) */
-  value?: string;
-  /** Who responded (user, system, timeout, etc.) */
-  respondedBy?: string;
-  /** Response timestamp */
-  respondedAt: number;
-}
-
-/** Interaction plugin interface */
-export interface InteractionPlugin {
-  /** Plugin name */
-  name: string;
-  /** Send interaction request to user */
-  send(request: InteractionRequest): Promise<void>;
-  /** Receive interaction response from user (blocking) */
-  receive(requestId: string, timeout?: number): Promise<InteractionResponse>;
-  /** Cancel a pending interaction (optional) */
-  cancel?(requestId: string): Promise<void>;
-  /** Initialize plugin with config (optional) */
-  init?(config: Record<string, unknown>): Promise<void>;
-  /** Teardown plugin (optional) */
-  destroy?(): Promise<void>;
-}
-
-/** Built-in trigger names */
-export type TriggerName =
-  | "security-review" // abort (red) — critical security issues found
-  | "cost-exceeded" // abort (red) — cost limit exceeded
-  | "merge-conflict" // abort (red) — merge conflict detected
-  | "cost-warning" // escalate (yellow) — approaching cost limit
-  | "max-retries" // skip (yellow) — max retries reached
-  | "pre-merge" // escalate (yellow) — before merging to main
-  | "human-review" // skip (yellow) — human review required on max retries / critical failure
-  | "story-oversized" // continue (yellow) — story has too many acceptance criteria
-  | "story-ambiguity" // continue (green) — story requirements unclear
-  | "review-gate"; // continue (green) — code review checkpoint
-
-/** Trigger configuration */
-export interface TriggerConfig {
-  /** Whether trigger is enabled */
-  enabled: boolean;
-  /** Override default fallback behavior */
-  fallback?: InteractionFallback;
-  /** Override default timeout (ms) */
-  timeout?: number;
-  /** Custom summary template (supports {{variable}} syntax) */
-  summary?: string;
-  /** Custom detail template */
-  detail?: string;
-}
-
-/** Safety tier for triggers */
-export type TriggerSafety = "red" | "yellow" | "green";
-
-/** Built-in trigger metadata */
-export interface TriggerMetadata {
-  /** Default fallback behavior */
-  defaultFallback: InteractionFallback;
-  /** Safety tier */
-  safety: TriggerSafety;
-  /** Default summary */
-  defaultSummary: string;
-}
-
-/** Map of built-in triggers to their metadata */
-export const TRIGGER_METADATA: Record<TriggerName, TriggerMetadata> = {
-  "security-review": {
-    defaultFallback: "abort",
-    safety: "red",
-    defaultSummary: "Security review failed — abort execution?",
-  },
-  "cost-exceeded": {
-    defaultFallback: "abort",
-    safety: "red",
-    defaultSummary: "Cost limit exceeded ({{cost}} USD) — abort execution?",
-  },
-  "merge-conflict": {
-    defaultFallback: "abort",
-    safety: "red",
-    defaultSummary: "Merge conflict detected in {{storyId}} — abort execution?",
-  },
-  "cost-warning": {
-    defaultFallback: "escalate",
-    safety: "yellow",
-    defaultSummary: "Cost warning: {{cost}} USD / {{limit}} USD — escalate to higher tier?",
-  },
-  "max-retries": {
-    defaultFallback: "skip",
-    safety: "yellow",
-    defaultSummary: "Max retries reached for {{storyId}} — skip story?",
-  },
-  "pre-merge": {
-    defaultFallback: "escalate",
-    safety: "yellow",
-    defaultSummary: "Pre-merge checkpoint for {{storyId}} — proceed with merge?",
-  },
-  "human-review": {
-    defaultFallback: "skip",
-    safety: "yellow",
-    defaultSummary: "Human review required for story {{storyId}} — skip and continue?",
-  },
-  "story-oversized": {
-    defaultFallback: "continue",
-    safety: "yellow",
-    defaultSummary:
-      "Story {{storyId}} is oversized ({{criteriaCount}} acceptance criteria) — decompose into smaller stories?",
-  },
-  "story-ambiguity": {
-    defaultFallback: "continue",
-    safety: "green",
-    defaultSummary: "Story {{storyId}} requirements unclear — continue with best effort?",
-  },
-  "review-gate": {
-    defaultFallback: "continue",
-    safety: "green",
-    defaultSummary: "Code review checkpoint for {{storyId}} — proceed?",
-  },
-};

package/src/logger/formatters.ts

@@ -1,84 +0,0 @@
-import chalk from "chalk";
-import type { LogEntry } from "./types.js";
-
-/**
- * Format log entry for human-readable console output with chalk colors
- *
- * @param entry - The log entry to format
- * @returns Chalk-formatted console string
- *
- * @example
- * ```typescript
- * const entry: LogEntry = {
- *   timestamp: "2026-02-20T10:30:00.123Z",
- *   level: "info",
- *   stage: "routing",
- *   storyId: "user-auth-001",
- *   message: "Classified as simple task",
- *   data: { complexity: "simple", model: "claude-sonnet-4-5" }
- * };
- * console.log(formatConsole(entry));
- * // [10:30:00] [routing] [user-auth-001] Classified as simple task
- * ```
- */
-export function formatConsole(entry: LogEntry): string {
-  const timestamp = new Date(entry.timestamp).toLocaleTimeString("en-US", {
-    hour12: false,
-  });
-
-  // Level-specific color coding
-  let levelColor: (text: string) => string;
-  switch (entry.level) {
-    case "error":
-      levelColor = chalk.red;
-      break;
-    case "warn":
-      levelColor = chalk.yellow;
-      break;
-    case "info":
-      levelColor = chalk.blue;
-      break;
-    case "debug":
-      levelColor = chalk.gray;
-      break;
-  }
-
-  // Build base message with timestamp, stage, and optional storyId
-  const parts = [chalk.gray(`[${timestamp}]`), levelColor(`[${entry.stage}]`)];
-
-  if (entry.storyId) {
-    parts.push(chalk.cyan(`[${entry.storyId}]`));
-  }
-
-  parts.push(entry.message);
-
-  // Append data if present (pretty-printed on next line)
-  let output = parts.join(" ");
-  if (entry.data && Object.keys(entry.data).length > 0) {
-    output += `\n${chalk.gray(JSON.stringify(entry.data, null, 2))}`;
-  }
-
-  return output;
-}
-
-/**
- * Format log entry as JSON Lines (JSONL) for machine-readable file output
- *
- * @param entry - The log entry to format
- * @returns Single-line JSON string
- *
- * @example
- * ```typescript
- * const entry: LogEntry = {
- *   timestamp: "2026-02-20T10:30:00.123Z",
- *   level: "info",
- *   stage: "routing",
- *   message: "Task classified"
- * };
- * console.log(formatJsonl(entry));
- * // {"timestamp":"2026-02-20T10:30:00.123Z","level":"info","stage":"routing","message":"Task classified"}
- * ```
- */
-export function formatJsonl(entry: LogEntry): string {
-  return JSON.stringify(entry);
-}

package/src/logger/index.ts

@@ -1,16 +0,0 @@
-/**
- * Structured logging module for nax
- *
- * Provides level-gated console output and JSONL file logging for all stages.
- *
- * @module logger
- */
-
-export { Logger, initLogger, getLogger, getSafeLogger, resetLogger } from "./logger.js";
-export { formatConsole, formatJsonl } from "./formatters.js";
-export type {
-  LogLevel,
-  LogEntry,
-  LoggerOptions,
-  StoryLogger,
-} from "./types.js";

package/src/logger/logger.ts

@@ -1,296 +0,0 @@
-import { appendFileSync, mkdirSync } 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) {
-        mkdirSync(dir, { recursive: true });
-      }
-    } 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 {
-      appendFileSync(this.filePath, `${formatJsonl(entry)}\n`);
-    } 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

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