@nathapp/nax 0.18.1

package/src/interaction/state.ts

@@ -0,0 +1,171 @@
+/**
+ * State Persistence for Pause/Resume (v0.15.0 US-003)
+ *
+ * Serializes run state when pausing, loads state when resuming.
+ */
+
+import * as path from "node:path";
+import type { InteractionRequest, InteractionResponse } from "./types";
+
+/** Serialized run state for pause/resume */
+export interface RunState {
+  /** Feature name */
+  feature: string;
+  /** PRD path */
+  prdPath: string;
+  /** Current iteration number */
+  iteration: number;
+  /** Accumulated cost (USD) */
+  totalCost: number;
+  /** Stories completed */
+  storiesCompleted: number;
+  /** Pending interactions */
+  pendingInteractions: InteractionRequest[];
+  /** Completed interactions */
+  completedInteractions: Array<{
+    request: InteractionRequest;
+    response: InteractionResponse;
+  }>;
+  /** Pause timestamp */
+  pausedAt: number;
+  /** Pause reason */
+  pauseReason: string;
+  /** Current story ID (if paused mid-story) */
+  currentStoryId?: string;
+  /** Current tier */
+  currentTier?: string;
+  /** Current model */
+  currentModel?: string;
+  /** Arbitrary metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Serialize run state to JSON file
+ */
+export async function serializeRunState(state: RunState, featureDir: string): Promise<string> {
+  const stateFile = path.join(featureDir, "run-state.json");
+  const json = JSON.stringify(state, null, 2);
+  await Bun.write(stateFile, json);
+  return stateFile;
+}
+
+/**
+ * Deserialize run state from JSON file
+ */
+export async function deserializeRunState(featureDir: string): Promise<RunState | null> {
+  const stateFile = path.join(featureDir, "run-state.json");
+  try {
+    const file = Bun.file(stateFile);
+    const exists = await file.exists();
+    if (!exists) {
+      return null;
+    }
+    const json = await file.text();
+    const state = JSON.parse(json) as RunState;
+    return state;
+  } catch (err) {
+    // Corrupted or invalid state file
+    return null;
+  }
+}
+
+/**
+ * Delete run state file (after successful resume)
+ */
+export async function clearRunState(featureDir: string): Promise<void> {
+  const stateFile = path.join(featureDir, "run-state.json");
+  try {
+    await Bun.write(stateFile, ""); // truncate
+    // Note: Bun doesn't have fs.unlink, so we truncate instead
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Save a pending interaction to the interactions directory
+ */
+export async function savePendingInteraction(request: InteractionRequest, featureDir: string): Promise<string> {
+  const interactionsDir = path.join(featureDir, "interactions");
+  // Ensure directory exists
+  await Bun.write(path.join(interactionsDir, ".gitkeep"), "");
+
+  const filename = `${request.id}.json`;
+  const filePath = path.join(interactionsDir, filename);
+  const json = JSON.stringify(request, null, 2);
+  await Bun.write(filePath, json);
+  return filePath;
+}
+
+/**
+ * Load a pending interaction from the interactions directory
+ */
+export async function loadPendingInteraction(
+  requestId: string,
+  featureDir: string,
+): Promise<InteractionRequest | null> {
+  const interactionsDir = path.join(featureDir, "interactions");
+  const filename = `${requestId}.json`;
+  const filePath = path.join(interactionsDir, filename);
+
+  try {
+    const file = Bun.file(filePath);
+    const exists = await file.exists();
+    if (!exists) {
+      return null;
+    }
+    const json = await file.text();
+    const request = JSON.parse(json) as InteractionRequest;
+    return request;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Delete a pending interaction file (after response received)
+ */
+export async function deletePendingInteraction(requestId: string, featureDir: string): Promise<void> {
+  const interactionsDir = path.join(featureDir, "interactions");
+  const filename = `${requestId}.json`;
+  const filePath = path.join(interactionsDir, filename);
+
+  try {
+    await Bun.write(filePath, ""); // truncate
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * List all pending interaction IDs
+ */
+export async function listPendingInteractions(featureDir: string): Promise<string[]> {
+  const interactionsDir = path.join(featureDir, "interactions");
+
+  try {
+    const dir = Bun.file(interactionsDir);
+    const exists = await dir.exists();
+    if (!exists) {
+      return [];
+    }
+
+    // Use Bun.spawn to list files
+    const proc = Bun.spawn(["ls", interactionsDir], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+
+    const files = output
+      .split("\n")
+      .filter((f) => f.endsWith(".json") && f !== ".gitkeep")
+      .map((f) => f.replace(".json", ""));
+
+    return files;
+  } catch {
+    return [];
+  }
+}

package/src/interaction/triggers.ts

@@ -0,0 +1,229 @@
+/**
+ * Built-in Triggers Integration (v0.15.0 US-004)
+ *
+ * Wires 8 built-in triggers into the runner loop and hooks system.
+ */
+
+import type { NaxConfig } from "../config";
+import type { InteractionChain } from "./chain";
+import type { InteractionFallback, InteractionRequest, InteractionResponse, TriggerName } from "./types";
+import { TRIGGER_METADATA } from "./types";
+
+/** Trigger context data for template substitution */
+export interface TriggerContext {
+  featureName: string;
+  storyId?: string;
+  cost?: number;
+  limit?: number;
+  tier?: string;
+  model?: string;
+  iteration?: number;
+  reason?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Check if a trigger is enabled in config
+ */
+export function isTriggerEnabled(trigger: TriggerName, config: NaxConfig): boolean {
+  const triggerConfig = config.interaction?.triggers?.[trigger];
+  if (triggerConfig === undefined) return false;
+  if (typeof triggerConfig === "boolean") return triggerConfig;
+  return triggerConfig.enabled;
+}
+
+/**
+ * Get trigger configuration (fallback, timeout)
+ */
+function getTriggerConfig(trigger: TriggerName, config: NaxConfig): { fallback: InteractionFallback; timeout: number } {
+  const metadata = TRIGGER_METADATA[trigger];
+  const triggerConfig = config.interaction?.triggers?.[trigger];
+  const defaults = config.interaction?.defaults ?? {
+    timeout: 600000,
+    fallback: "escalate" as InteractionFallback,
+  };
+
+  let fallback: InteractionFallback = metadata.defaultFallback;
+  let timeout = defaults.timeout;
+
+  if (typeof triggerConfig === "object") {
+    if (triggerConfig.fallback) {
+      fallback = triggerConfig.fallback as InteractionFallback;
+    }
+    if (triggerConfig.timeout) {
+      timeout = triggerConfig.timeout;
+    }
+  }
+
+  return { fallback, timeout };
+}
+
+/**
+ * Substitute {{variable}} placeholders in a template string
+ */
+function substituteTemplate(template: string, context: TriggerContext): string {
+  let result = template;
+  for (const [key, value] of Object.entries(context)) {
+    if (value !== undefined) {
+      result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), String(value));
+    }
+  }
+  return result;
+}
+
+/**
+ * Create an interaction request for a built-in trigger
+ */
+export function createTriggerRequest(
+  trigger: TriggerName,
+  context: TriggerContext,
+  config: NaxConfig,
+): InteractionRequest {
+  const metadata = TRIGGER_METADATA[trigger];
+  const { fallback, timeout } = getTriggerConfig(trigger, config);
+
+  const summary = substituteTemplate(metadata.defaultSummary, context);
+  const id = `trigger-${trigger}-${Date.now()}`;
+
+  return {
+    id,
+    type: "confirm",
+    featureName: context.featureName,
+    storyId: context.storyId,
+    stage: "custom",
+    summary,
+    fallback,
+    timeout,
+    createdAt: Date.now(),
+    metadata: {
+      trigger,
+      safety: metadata.safety,
+    },
+  };
+}
+
+/**
+ * Execute a trigger and return response
+ */
+export async function executeTrigger(
+  trigger: TriggerName,
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<InteractionResponse> {
+  const request = createTriggerRequest(trigger, context, config);
+  const response = await chain.prompt(request);
+  return response;
+}
+
+/**
+ * Check security-review trigger (abort on critical issues)
+ */
+export async function checkSecurityReview(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<boolean> {
+  if (!isTriggerEnabled("security-review", config)) return true;
+
+  const response = await executeTrigger("security-review", context, config, chain);
+  return response.action !== "abort";
+}
+
+/**
+ * Check cost-exceeded trigger (abort on limit exceeded)
+ */
+export async function checkCostExceeded(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<boolean> {
+  if (!isTriggerEnabled("cost-exceeded", config)) return true;
+
+  const response = await executeTrigger("cost-exceeded", context, config, chain);
+  return response.action !== "abort";
+}
+
+/**
+ * Check merge-conflict trigger (abort on conflict)
+ */
+export async function checkMergeConflict(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<boolean> {
+  if (!isTriggerEnabled("merge-conflict", config)) return true;
+
+  const response = await executeTrigger("merge-conflict", context, config, chain);
+  return response.action !== "abort";
+}
+
+/**
+ * Check cost-warning trigger (escalate on approaching limit)
+ */
+export async function checkCostWarning(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<"continue" | "escalate"> {
+  if (!isTriggerEnabled("cost-warning", config)) return "continue";
+
+  const response = await executeTrigger("cost-warning", context, config, chain);
+  return response.action === "approve" ? "escalate" : "continue";
+}
+
+/**
+ * Check max-retries trigger (skip story on max retries)
+ */
+export async function checkMaxRetries(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<"continue" | "skip"> {
+  if (!isTriggerEnabled("max-retries", config)) return "continue";
+
+  const response = await executeTrigger("max-retries", context, config, chain);
+  return response.action === "skip" ? "skip" : "continue";
+}
+
+/**
+ * Check pre-merge trigger (escalate before merging)
+ */
+export async function checkPreMerge(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<boolean> {
+  if (!isTriggerEnabled("pre-merge", config)) return true;
+
+  const response = await executeTrigger("pre-merge", context, config, chain);
+  return response.action === "approve";
+}
+
+/**
+ * Check story-ambiguity trigger (continue with best effort)
+ */
+export async function checkStoryAmbiguity(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<boolean> {
+  if (!isTriggerEnabled("story-ambiguity", config)) return true;
+
+  const response = await executeTrigger("story-ambiguity", context, config, chain);
+  return response.action === "approve";
+}
+
+/**
+ * Check review-gate trigger (proceed with review)
+ */
+export async function checkReviewGate(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<boolean> {
+  if (!isTriggerEnabled("review-gate", config)) return true;
+
+  const response = await executeTrigger("review-gate", context, config, chain);
+  return response.action === "approve";
+}

package/src/interaction/types.ts

@@ -0,0 +1,163 @@
+/**
+ * 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-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-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

@@ -0,0 +1,84 @@
+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

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