@nathapp/nax 0.50.3 → 0.51.2

package/src/pipeline/event-bus.ts

@@ -1,297 +0,0 @@
-// RE-ARCH: keep
-/**
- * Pipeline Event Bus (ADR-005, Phase 1)
- *
- * Typed publish/subscribe event bus for pipeline lifecycle events.
- * Replaces 20+ scattered fireHook() calls and 5+ getReporters() calls
- * with a single wiring point. Subscribers are registered once at startup.
- *
- * Phase 1: bus is created and exported. Existing hook/reporter calls
- * are NOT replaced until Phase 3 (subscriber consolidation).
- *
- * Design principles:
- * - Synchronous publish (fire-and-forget) — subscribers run async but bus
- *   does not await them, matching current fireHook() behavior
- * - Typed events via discriminated union
- * - Error isolation: one subscriber failure doesn't break others
- * - Zero dependencies on pipeline internals
- */
-
-import { getLogger } from "../logger";
-import type { UserStory } from "../prd";
-import type { VerifyResult } from "../verification/orchestrator-types";
-
-// ---------------------------------------------------------------------------
-// Event types
-// ---------------------------------------------------------------------------
-
-export interface StoryStartedEvent {
-  type: "story:started";
-  storyId: string;
-  story: UserStory;
-  workdir: string;
-  /** Optional: passed by executor for hook subscriber */
-  modelTier?: string;
-  agent?: string;
-  iteration?: number;
-}
-
-export interface StoryCompletedEvent {
-  type: "story:completed";
-  storyId: string;
-  story: UserStory;
-  passed: boolean;
-  runElapsedMs: number;
-  /** Optional: passed by executor/stage for hook/reporter subscribers */
-  cost?: number;
-  modelTier?: string;
-  testStrategy?: string;
-}
-
-export interface StoryFailedEvent {
-  type: "story:failed";
-  storyId: string;
-  story: UserStory;
-  reason: string;
-  countsTowardEscalation: boolean;
-  /** Optional: passed by executor for interaction subscriber */
-  feature?: string;
-  attempts?: number;
-}
-
-export interface VerifyCompletedEvent {
-  type: "verify:completed";
-  storyId: string;
-  result: VerifyResult;
-}
-
-export interface RectifyStartedEvent {
-  type: "rectify:started";
-  storyId: string;
-  attempt: number;
-  testOutput: string;
-}
-
-export interface RectifyCompletedEvent {
-  type: "rectify:completed";
-  storyId: string;
-  attempt: number;
-  fixed: boolean;
-}
-
-export interface AutofixStartedEvent {
-  type: "autofix:started";
-  storyId: string;
-  command: string;
-}
-
-export interface AutofixCompletedEvent {
-  type: "autofix:completed";
-  storyId: string;
-  fixed: boolean;
-}
-
-export interface RegressionDetectedEvent {
-  type: "regression:detected";
-  storyId: string;
-  failedTests: number;
-}
-
-export interface RunCompletedEvent {
-  type: "run:completed";
-  totalStories: number;
-  passedStories: number;
-  failedStories: number;
-  durationMs: number;
-  totalCost?: number;
-}
-
-export interface HumanReviewRequestedEvent {
-  type: "human-review:requested";
-  storyId: string;
-  reason: string;
-  feature?: string;
-  attempts?: number;
-}
-
-export interface RunStartedEvent {
-  type: "run:started";
-  feature: string;
-  totalStories: number;
-  workdir: string;
-}
-
-export interface RunPausedEvent {
-  type: "run:paused";
-  reason: string;
-  storyId?: string;
-  cost: number;
-}
-
-export interface StoryPausedEvent {
-  type: "story:paused";
-  storyId: string;
-  reason: string;
-  cost: number;
-}
-
-export interface StoryDecomposedEvent {
-  type: "story:decomposed";
-  storyId: string;
-  story: UserStory;
-  subStoryCount: number;
-}
-
-export interface RunResumedEvent {
-  type: "run:resumed";
-  feature: string;
-}
-
-export interface RunErroredEvent {
-  type: "run:errored";
-  reason: string;
-  feature?: string;
-}
-
-/** Discriminated union of all pipeline events. */
-export type PipelineEvent =
-  | StoryStartedEvent
-  | StoryCompletedEvent
-  | StoryFailedEvent
-  | VerifyCompletedEvent
-  | RectifyStartedEvent
-  | RectifyCompletedEvent
-  | AutofixStartedEvent
-  | AutofixCompletedEvent
-  | RegressionDetectedEvent
-  | RunCompletedEvent
-  | HumanReviewRequestedEvent
-  | RunStartedEvent
-  | RunPausedEvent
-  | StoryPausedEvent
-  | RunResumedEvent
-  | RunErroredEvent
-  | StoryDecomposedEvent;
-
-export type PipelineEventType = PipelineEvent["type"];
-
-// ---------------------------------------------------------------------------
-// Subscriber types
-// ---------------------------------------------------------------------------
-
-export type EventSubscriber<T extends PipelineEvent = PipelineEvent> = (event: T) => void | Promise<void>;
-
-type SubscriberMap = Map<string, EventSubscriber[]>;
-
-// ---------------------------------------------------------------------------
-// Bus implementation
-// ---------------------------------------------------------------------------
-
-export class PipelineEventBus {
-  private readonly subscribers: SubscriberMap = new Map();
-
-  /**
-   * Subscribe to a specific event type.
-   *
-   * @returns Unsubscribe function
-   */
-  on<T extends PipelineEventType>(
-    eventType: T,
-    subscriber: EventSubscriber<Extract<PipelineEvent, { type: T }>>,
-  ): () => void {
-    const list = this.subscribers.get(eventType) ?? [];
-    list.push(subscriber as EventSubscriber);
-    this.subscribers.set(eventType, list);
-
-    return () => {
-      const current = this.subscribers.get(eventType) ?? [];
-      this.subscribers.set(
-        eventType,
-        current.filter((s) => s !== subscriber),
-      );
-    };
-  }
-
-  /**
-   * Subscribe to all events.
-   *
-   * @returns Unsubscribe function
-   */
-  onAll(subscriber: EventSubscriber): () => void {
-    const list = this.subscribers.get("*") ?? [];
-    list.push(subscriber);
-    this.subscribers.set("*", list);
-
-    return () => {
-      const current = this.subscribers.get("*") ?? [];
-      this.subscribers.set(
-        "*",
-        current.filter((s) => s !== subscriber),
-      );
-    };
-  }
-
-  /**
-   * Publish an event to all matching subscribers.
-   *
-   * Fire-and-forget: async subscribers are not awaited.
-   * Subscriber errors are caught and logged — one failure doesn't block others.
-   */
-  emit(event: PipelineEvent): void {
-    const logger = getLogger();
-
-    const specific = this.subscribers.get(event.type) ?? [];
-    const all = this.subscribers.get("*") ?? [];
-    const targets = [...specific, ...all];
-
-    for (const sub of targets) {
-      try {
-        const result = sub(event);
-        if (result instanceof Promise) {
-          result.catch((err) => {
-            logger.warn("event-bus", `Subscriber error on ${event.type}`, { error: String(err) });
-          });
-        }
-      } catch (err) {
-        logger.warn("event-bus", `Subscriber threw on ${event.type}`, { error: String(err) });
-      }
-    }
-  }
-
-  /**
-   * Publish an event and await all async subscribers.
-   *
-   * Use this when you need to ensure subscribers have completed before proceeding
-   * (e.g., for interaction subscribers that block on human input).
-   */
-  async emitAsync(event: PipelineEvent): Promise<void> {
-    const logger = getLogger();
-
-    const specific = this.subscribers.get(event.type) ?? [];
-    const all = this.subscribers.get("*") ?? [];
-    const targets = [...specific, ...all];
-
-    await Promise.allSettled(
-      targets.map(async (sub) => {
-        try {
-          await sub(event);
-        } catch (err) {
-          logger.warn("event-bus", `Subscriber error on ${event.type}`, { error: String(err) });
-        }
-      }),
-    );
-  }
-
-  /** Remove all subscribers (useful in tests). */
-  clear(): void {
-    this.subscribers.clear();
-  }
-
-  /** Number of subscribers for a given event type. */
-  subscriberCount(eventType: PipelineEventType | "*"): number {
-    return (this.subscribers.get(eventType) ?? []).length;
-  }
-}
-
-/** Singleton pipeline event bus instance. */
-export const pipelineEventBus = new PipelineEventBus();

package/src/pipeline/events.ts

@@ -1,130 +0,0 @@
-/**
- * Pipeline Event Emitter
- *
- * Typed event emitter for TUI integration. Emits lifecycle events during
- * pipeline execution so the TUI can display real-time progress.
- */
-
-import { EventEmitter } from "node:events";
-import type { UserStory } from "../prd/types";
-import type { RoutingResult, StageResult } from "./types";
-
-/**
- * Summary of a completed run.
- */
-export interface RunSummary {
-  /** Total number of stories processed */
-  storiesProcessed: number;
-  /** Number of stories completed successfully */
-  storiesCompleted: number;
-  /** Number of stories failed */
-  storiesFailed: number;
-  /** Number of stories skipped */
-  storiesSkipped: number;
-  /** Total cost in USD */
-  totalCost: number;
-  /** Total duration in milliseconds */
-  durationMs: number;
-}
-
-/**
- * Pipeline event types matching v0.6 spec.
- *
- * Events:
- * - story:start — Story execution begins
- * - story:complete — Story execution ends (success/fail/skip)
- * - story:escalate — Story escalated to higher tier
- * - stage:enter — Pipeline stage starts
- * - stage:exit — Pipeline stage finishes
- * - run:complete — Full run completes
- */
-export interface PipelineEvents {
-  "story:start": (story: UserStory, routing: RoutingResult) => void;
-  "story:complete": (story: UserStory, result: StageResult) => void;
-  "story:escalate": (story: UserStory, fromTier: string, toTier: string) => void;
-  "stage:enter": (stage: string, story: UserStory) => void;
-  "stage:exit": (stage: string, result: StageResult) => void;
-  "run:complete": (summary: RunSummary) => void;
-}
-
-/**
- * Typed event emitter for pipeline events.
- *
- * Wraps Node.js EventEmitter with TypeScript types for pipeline lifecycle
- * events. The TUI subscribes to these events to update UI state in real-time.
- *
- * @example
- * ```ts
- * const emitter = new PipelineEventEmitter();
- *
- * emitter.on('story:start', (story, routing) => {
- *   // Handle story start: ${story.id} with ${routing.modelTier}
- * });
- *
- * emitter.on('story:complete', (story, result) => {
- *   // Handle story completion: ${story.id} - ${result.action}
- * });
- *
- * // In pipeline runner:
- * emitter.emit('story:start', story, routing);
- * ```
- */
-export class PipelineEventEmitter {
-  private emitter = new EventEmitter();
-
-  /**
-   * Subscribe to a pipeline event.
-   *
-   * @param event - Event name
-   * @param listener - Event handler
-   */
-  on<E extends keyof PipelineEvents>(event: E, listener: PipelineEvents[E]): void {
-    this.emitter.on(event, listener as (...args: unknown[]) => void);
-  }
-
-  /**
-   * Subscribe to an event once (auto-unsubscribe after first emission).
-   *
-   * @param event - Event name
-   * @param listener - Event handler
-   */
-  once<E extends keyof PipelineEvents>(event: E, listener: PipelineEvents[E]): void {
-    this.emitter.once(event, listener as (...args: unknown[]) => void);
-  }
-
-  /**
-   * Unsubscribe from an event.
-   *
-   * @param event - Event name
-   * @param listener - Event handler to remove
-   */
-  off<E extends keyof PipelineEvents>(event: E, listener: PipelineEvents[E]): void {
-    this.emitter.off(event, listener as (...args: unknown[]) => void);
-  }
-
-  /**
-   * Emit a pipeline event.
-   *
-   * Called internally by the pipeline runner. External code should only
-   * subscribe to events, not emit them.
-   *
-   * @param event - Event name
-   * @param args - Event arguments
-   */
-  emit<E extends keyof PipelineEvents>(event: E, ...args: Parameters<PipelineEvents[E]>): void {
-    this.emitter.emit(event, ...args);
-  }
-
-  /**
-   * Remove all listeners for a specific event or all events.
-   *
-   * @param event - Optional event name (if not provided, removes all listeners)
-   */
-  removeAllListeners(event?: keyof PipelineEvents): void {
-    if (event) {
-      this.emitter.removeAllListeners(event);
-    } else {
-      this.emitter.removeAllListeners();
-    }
-  }
-}

package/src/pipeline/index.ts

@@ -1,19 +0,0 @@
-/**
- * Pipeline Module
- *
- * Composable stage-based execution pipeline.
- */
-
-export type {
-  PipelineContext,
-  PipelineStage,
-  StageResult,
-  StageAction,
-  RoutingResult,
-} from "./types";
-
-export { runPipeline } from "./runner";
-export type { PipelineRunResult } from "./runner";
-
-export { PipelineEventEmitter } from "./events";
-export type { PipelineEvents, RunSummary } from "./events";

package/src/pipeline/runner.ts

@@ -1,149 +0,0 @@
-/**
- * Pipeline Runner
- *
- * Executes a sequence of pipeline stages, handling stage results and
- * controlling the flow (continue/skip/fail/escalate/pause/retry).
- */
-
-import { getLogger } from "../logger";
-import { errorMessage } from "../utils/errors";
-import type { PipelineEventEmitter } from "./events";
-import type { PipelineContext, PipelineStage, StageResult } from "./types";
-
-/**
- * Pipeline execution result.
- */
-export interface PipelineRunResult {
-  /** Whether the pipeline completed successfully (reached the end) */
-  success: boolean;
-  /** Final action taken */
-  finalAction: "complete" | "skip" | "decomposed" | "fail" | "escalate" | "pause";
-  /** Reason for non-complete outcomes */
-  reason?: string;
-  /** Number of sub-stories created (only set when finalAction === "decomposed") */
-  subStoryCount?: number;
-  /** Stage where the pipeline stopped (if not completed) */
-  stoppedAtStage?: string;
-  /** Updated context after pipeline execution */
-  context: PipelineContext;
-}
-
-/** Maximum number of retries per stage to prevent infinite loops. */
-export const MAX_STAGE_RETRIES = 5;
-
-/**
- * Run a pipeline of stages against a context.
- *
- * Supports a `retry` action that jumps back to a named stage (used by
- * rectify/autofix stages). Retry count per target stage is tracked;
- * exceeding MAX_STAGE_RETRIES converts to a `fail`.
- *
- * **Context Mutation:** This function mutates the input context in-place.
- */
-export async function runPipeline(
-  stages: PipelineStage[],
-  context: PipelineContext,
-  eventEmitter?: PipelineEventEmitter,
-): Promise<PipelineRunResult> {
-  const logger = getLogger();
-  const retryCountMap = new Map<string, number>();
-  let i = 0;
-
-  while (i < stages.length) {
-    const stage = stages[i];
-
-    // Skip disabled stages
-    if (!stage.enabled(context)) {
-      const reason = stage.skipReason?.(context) ?? "disabled";
-      logger.debug("pipeline", `Stage "${stage.name}" skipped (${reason})`);
-      i++;
-      continue;
-    }
-
-    eventEmitter?.emit("stage:enter", stage.name, context.story);
-
-    let result: StageResult;
-    try {
-      result = await stage.execute(context);
-    } catch (error) {
-      const failResult: StageResult = {
-        action: "fail",
-        reason: `Stage "${stage.name}" threw error: ${errorMessage(error)}`,
-      };
-      eventEmitter?.emit("stage:exit", stage.name, failResult);
-      return { success: false, finalAction: "fail", reason: failResult.reason, stoppedAtStage: stage.name, context };
-    }
-
-    eventEmitter?.emit("stage:exit", stage.name, result);
-
-    switch (result.action) {
-      case "continue":
-        i++;
-        continue;
-
-      case "skip":
-        return { success: false, finalAction: "skip", reason: result.reason, stoppedAtStage: stage.name, context };
-
-      case "decomposed":
-        return {
-          success: false,
-          finalAction: "decomposed",
-          reason: result.reason,
-          subStoryCount: result.subStoryCount,
-          stoppedAtStage: stage.name,
-          context,
-        };
-
-      case "fail":
-        return { success: false, finalAction: "fail", reason: result.reason, stoppedAtStage: stage.name, context };
-
-      case "escalate":
-        return {
-          success: false,
-          finalAction: "escalate",
-          reason: result.reason ?? "Stage requested escalation to higher tier",
-          stoppedAtStage: stage.name,
-          context,
-        };
-
-      case "pause":
-        return { success: false, finalAction: "pause", reason: result.reason, stoppedAtStage: stage.name, context };
-
-      case "retry": {
-        const retries = (retryCountMap.get(result.fromStage) ?? 0) + 1;
-        if (retries > MAX_STAGE_RETRIES) {
-          logger.warn("pipeline", `Stage retry limit reached for "${result.fromStage}" (max ${MAX_STAGE_RETRIES})`);
-          return {
-            success: false,
-            finalAction: "fail",
-            reason: `Stage "${stage.name}" exceeded max retries (${MAX_STAGE_RETRIES}) for "${result.fromStage}"`,
-            stoppedAtStage: stage.name,
-            context,
-          };
-        }
-        retryCountMap.set(result.fromStage, retries);
-        const targetIndex = stages.findIndex((s) => s.name === result.fromStage);
-        if (targetIndex === -1) {
-          logger.warn("pipeline", `Retry target stage "${result.fromStage}" not found — escalating`);
-          return {
-            success: false,
-            finalAction: "escalate",
-            reason: `Retry target stage "${result.fromStage}" not found`,
-            stoppedAtStage: stage.name,
-            context,
-          };
-        }
-        logger.debug("pipeline", `Retrying from stage "${result.fromStage}" (attempt ${retries}/${MAX_STAGE_RETRIES})`);
-        i = targetIndex;
-        continue;
-      }
-
-      default: {
-        const _exhaustive: never = result;
-        throw new Error(`Unknown stage action: ${JSON.stringify(_exhaustive)}`);
-      }
-    }
-  }
-
-  return { success: true, finalAction: "complete", context };
-}