@griffin-app/griffin-plan-executor 0.1.0

package/src/adapters/stub.ts

@@ -0,0 +1,47 @@
+import type { HttpClientAdapter, HttpRequest, HttpResponse } from "../types.js";
+
+export interface StubResponse {
+  /** URL pattern to match (string for exact, RegExp for pattern, or function for custom logic) */
+  match: string | RegExp | ((req: HttpRequest) => boolean);
+  response: HttpResponse;
+}
+
+export class StubAdapter implements HttpClientAdapter {
+  private stubs: StubResponse[] = [];
+
+  /**
+   * Add a stub response for matching requests
+   * @param stub - The stub configuration
+   * @returns this (for chaining)
+   */
+  addStub(stub: StubResponse): this {
+    this.stubs.push(stub);
+    return this;
+  }
+
+  /**
+   * Clear all configured stubs
+   */
+  clearStubs(): void {
+    this.stubs = [];
+  }
+
+  async request(req: HttpRequest): Promise<HttpResponse> {
+    for (const stub of this.stubs) {
+      if (this.matches(stub.match, req)) {
+        return stub.response;
+      }
+    }
+    throw new Error(`No stub matched request: ${req.method} ${req.url}`);
+  }
+
+  private matches(match: StubResponse["match"], req: HttpRequest): boolean {
+    if (typeof match === "string") {
+      return req.url === match;
+    }
+    if (match instanceof RegExp) {
+      return match.test(req.url);
+    }
+    return match(req);
+  }
+}

package/src/events/emitter.test.ts

@@ -0,0 +1,316 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  LocalEventEmitter,
+  DurableEventEmitter,
+  type DurableEventBusAdapter,
+} from "./emitter.js";
+import type { ExecutionEvent } from "./types.js";
+
+describe("LocalEventEmitter", () => {
+  let emitter: LocalEventEmitter;
+
+  beforeEach(() => {
+    emitter = new LocalEventEmitter();
+  });
+
+  it("should deliver events to subscribers synchronously", () => {
+    const events: ExecutionEvent[] = [];
+    emitter.subscribe((event) => events.push(event));
+
+    const testEvent: ExecutionEvent = {
+      type: "PLAN_START",
+      eventId: "123",
+      seq: 0,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      planName: "Test Plan",
+      planVersion: "1.0",
+      nodeCount: 2,
+      edgeCount: 1,
+    };
+
+    emitter.emit(testEvent);
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toEqual(testEvent);
+  });
+
+  it("should deliver events to multiple subscribers", () => {
+    const events1: ExecutionEvent[] = [];
+    const events2: ExecutionEvent[] = [];
+
+    emitter.subscribe((event) => events1.push(event));
+    emitter.subscribe((event) => events2.push(event));
+
+    const testEvent: ExecutionEvent = {
+      type: "NODE_START",
+      eventId: "456",
+      seq: 1,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      nodeId: "node-1",
+      nodeType: "endpoint",
+    };
+
+    emitter.emit(testEvent);
+
+    expect(events1).toHaveLength(1);
+    expect(events2).toHaveLength(1);
+    expect(events1[0]).toEqual(testEvent);
+    expect(events2[0]).toEqual(testEvent);
+  });
+
+  it("should allow unsubscribing", () => {
+    const events: ExecutionEvent[] = [];
+    const unsubscribe = emitter.subscribe((event) => events.push(event));
+
+    const testEvent: ExecutionEvent = {
+      type: "NODE_END",
+      eventId: "789",
+      seq: 2,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      nodeId: "node-1",
+      nodeType: "endpoint",
+      success: true,
+      duration_ms: 100,
+    };
+
+    emitter.emit(testEvent);
+    expect(events).toHaveLength(1);
+
+    unsubscribe();
+
+    emitter.emit(testEvent);
+    expect(events).toHaveLength(1); // Still 1, not 2
+  });
+
+  it("should not propagate listener errors to other listeners", () => {
+    const events: ExecutionEvent[] = [];
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    emitter.subscribe(() => {
+      throw new Error("Listener error");
+    });
+    emitter.subscribe((event) => events.push(event));
+
+    const testEvent: ExecutionEvent = {
+      type: "PLAN_END",
+      eventId: "abc",
+      seq: 3,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      success: true,
+      totalDuration_ms: 1000,
+      nodeResultCount: 2,
+      errorCount: 0,
+      errors: [],
+    };
+
+    emitter.emit(testEvent);
+
+    expect(events).toHaveLength(1);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+
+    consoleErrorSpy.mockRestore();
+  });
+});
+
+describe("DurableEventEmitter", () => {
+  let adapter: DurableEventBusAdapter;
+  let publishSpy: ReturnType<
+    typeof vi.fn<(events: ExecutionEvent[]) => Promise<void>>
+  >;
+  let emitter: DurableEventEmitter;
+
+  beforeEach(() => {
+    publishSpy = vi
+      .fn<(events: ExecutionEvent[]) => Promise<void>>()
+      .mockResolvedValue(undefined);
+    adapter = { publish: publishSpy };
+  });
+
+  afterEach(() => {
+    emitter?.destroy();
+  });
+
+  it("should batch events and flush on batch size", async () => {
+    emitter = new DurableEventEmitter(adapter, {
+      batchSize: 3,
+      flushIntervalMs: 10000,
+    });
+
+    const event1: ExecutionEvent = {
+      type: "NODE_START",
+      eventId: "1",
+      seq: 0,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      nodeId: "node-1",
+      nodeType: "endpoint",
+    };
+
+    const event2: ExecutionEvent = {
+      type: "NODE_START",
+      eventId: "2",
+      seq: 1,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      nodeId: "node-2",
+      nodeType: "wait",
+    };
+
+    const event3: ExecutionEvent = {
+      type: "NODE_START",
+      eventId: "3",
+      seq: 2,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      nodeId: "node-3",
+      nodeType: "assertion",
+    };
+
+    emitter.emit(event1);
+    emitter.emit(event2);
+    expect(publishSpy).not.toHaveBeenCalled();
+
+    emitter.emit(event3); // Should trigger auto-flush
+
+    // Wait for async flush
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(publishSpy).toHaveBeenCalledTimes(1);
+    expect(publishSpy).toHaveBeenCalledWith([event1, event2, event3]);
+  });
+
+  it("should flush on interval", async () => {
+    emitter = new DurableEventEmitter(adapter, {
+      batchSize: 100,
+      flushIntervalMs: 50,
+    });
+
+    const event: ExecutionEvent = {
+      type: "HTTP_REQUEST",
+      eventId: "1",
+      seq: 0,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      nodeId: "node-1",
+      attempt: 1,
+      method: "GET",
+      url: "https://api.example.com/test",
+      hasBody: false,
+    };
+
+    emitter.emit(event);
+
+    // Wait for interval flush
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    expect(publishSpy).toHaveBeenCalledWith([event]);
+  });
+
+  it("should flush manually when requested", async () => {
+    emitter = new DurableEventEmitter(adapter, {
+      batchSize: 100,
+      flushIntervalMs: 10000,
+    });
+
+    const event: ExecutionEvent = {
+      type: "HTTP_RESPONSE",
+      eventId: "1",
+      seq: 0,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      nodeId: "node-1",
+      attempt: 1,
+      status: 200,
+      statusText: "OK",
+      duration_ms: 100,
+      hasBody: true,
+    };
+
+    emitter.emit(event);
+    await emitter.flush();
+
+    expect(publishSpy).toHaveBeenCalledWith([event]);
+  });
+
+  it("should not emit after being destroyed", async () => {
+    emitter = new DurableEventEmitter(adapter, {
+      batchSize: 100,
+      flushIntervalMs: 50,
+    });
+
+    const consoleWarnSpy = vi
+      .spyOn(console, "warn")
+      .mockImplementation(() => {});
+
+    emitter.destroy();
+
+    const event: ExecutionEvent = {
+      type: "ERROR",
+      eventId: "1",
+      seq: 0,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      errorName: "TestError",
+      message: "Test error message",
+    };
+
+    emitter.emit(event);
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    expect(publishSpy).not.toHaveBeenCalled();
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      "Cannot emit event: emitter is destroyed",
+    );
+
+    consoleWarnSpy.mockRestore();
+  });
+
+  it("should handle publish failures gracefully", async () => {
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    publishSpy.mockRejectedValueOnce(new Error("Publish failed"));
+
+    emitter = new DurableEventEmitter(adapter, {
+      batchSize: 1,
+      flushIntervalMs: 10000,
+    });
+
+    const event: ExecutionEvent = {
+      type: "WAIT_START",
+      eventId: "1",
+      seq: 0,
+      timestamp: Date.now(),
+      planId: "plan-1",
+      executionId: "exec-1",
+      nodeId: "wait-1",
+      duration_ms: 1000,
+    };
+
+    emitter.emit(event);
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(publishSpy).toHaveBeenCalled();
+    expect(consoleErrorSpy).toHaveBeenCalled();
+
+    consoleErrorSpy.mockRestore();
+  });
+});

package/src/events/emitter.ts

@@ -0,0 +1,133 @@
+import type { ExecutionEvent } from "./types.js";
+
+/**
+ * Pluggable event emitter interface for execution observability.
+ *
+ * Implementations can be synchronous (local) or asynchronous (durable bus).
+ * The executor treats emission as best-effort and non-blocking.
+ */
+export interface ExecutionEventEmitter {
+  /**
+   * Emit a single event. May be synchronous or asynchronous depending on implementation.
+   * Errors during emission should not propagate to the executor.
+   */
+  emit(event: ExecutionEvent): void | Promise<void>;
+
+  /**
+   * Optional: flush any buffered events (for batching implementations).
+   * Called at the end of execution to ensure all events are delivered.
+   */
+  flush?(): Promise<void>;
+
+  /**
+   * Optional: cleanup resources (timers, connections, etc.).
+   */
+  destroy?(): void;
+}
+
+/**
+ * In-memory event emitter for local/development use.
+ * Events are delivered synchronously to all subscribers.
+ */
+export class LocalEventEmitter implements ExecutionEventEmitter {
+  private listeners: Array<(event: ExecutionEvent) => void> = [];
+
+  /**
+   * Subscribe to all execution events.
+   * @returns Unsubscribe function
+   */
+  subscribe(listener: (event: ExecutionEvent) => void): () => void {
+    this.listeners.push(listener);
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener);
+    };
+  }
+
+  emit(event: ExecutionEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        // Don't let listener errors break execution
+        console.error("Error in event listener:", error);
+      }
+    }
+  }
+}
+
+/**
+ * Adapter interface for durable event buses (SQS, Kafka, Redis Streams, etc.).
+ * Implementations provided by callers based on their infrastructure.
+ */
+export interface DurableEventBusAdapter {
+  /**
+   * Publish a batch of events to the durable bus.
+   * Should handle serialization, retries, and error handling internally.
+   */
+  publish(events: ExecutionEvent[]): Promise<void>;
+}
+
+/**
+ * Event emitter that batches events for efficient delivery to durable event buses.
+ * Flushes on interval and when batch size is reached.
+ */
+export class DurableEventEmitter implements ExecutionEventEmitter {
+  private buffer: ExecutionEvent[] = [];
+  private flushInterval: NodeJS.Timeout | null = null;
+  private isDestroyed = false;
+
+  constructor(
+    private adapter: DurableEventBusAdapter,
+    private options: {
+      /** Number of events to batch before auto-flushing (default: 50) */
+      batchSize?: number;
+      /** Milliseconds between auto-flushes (default: 100) */
+      flushIntervalMs?: number;
+    } = {},
+  ) {
+    const intervalMs = options.flushIntervalMs ?? 100;
+    this.flushInterval = setInterval(() => {
+      this.flush().catch((error) => {
+        console.error("Error flushing events:", error);
+      });
+    }, intervalMs);
+  }
+
+  emit(event: ExecutionEvent): void {
+    if (this.isDestroyed) {
+      console.warn("Cannot emit event: emitter is destroyed");
+      return;
+    }
+
+    this.buffer.push(event);
+
+    // Auto-flush when batch size is reached
+    if (this.buffer.length >= (this.options.batchSize ?? 50)) {
+      this.flush().catch((error) => {
+        console.error("Error auto-flushing events:", error);
+      });
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.buffer.length === 0) return;
+
+    const events = this.buffer;
+    this.buffer = [];
+
+    try {
+      await this.adapter.publish(events);
+    } catch (error) {
+      console.error("Failed to publish events:", error);
+      // Events are lost on failure - caller adapter should implement retries if needed
+    }
+  }
+
+  destroy(): void {
+    this.isDestroyed = true;
+    if (this.flushInterval) {
+      clearInterval(this.flushInterval);
+      this.flushInterval = null;
+    }
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./emitter.js";

package/src/events/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Event types for test plan execution.
+ *
+ * All events are JSON-serializable for compatibility with various event buses.
+ * Events include stable identifiers (executionId, eventId) and monotonic sequence
+ * numbers for deduplication and ordering.
+ */
+
+/** Base event envelope with correlation and ordering metadata */
+export interface BaseEvent {
+  /** Unique identifier for this specific event */
+  eventId: string;
+  /** Monotonic sequence number within this execution (0-indexed) */
+  seq: number;
+  /** Unix timestamp in milliseconds */
+  timestamp: number;
+  /** ID of the test plan being executed */
+  planId: string;
+  /** Unique identifier for this execution run */
+  executionId: string;
+}
+
+/** Plan-level events */
+export interface PlanStartEvent extends BaseEvent {
+  type: "PLAN_START";
+  planName: string;
+  planVersion: string;
+  nodeCount: number;
+  edgeCount: number;
+}
+
+export interface PlanEndEvent extends BaseEvent {
+  type: "PLAN_END";
+  success: boolean;
+  totalDuration_ms: number;
+  nodeResultCount: number;
+  errorCount: number;
+  errors: string[];
+}
+
+/** Node-level events (domain-enriched from ts-edge events) */
+export interface NodeStartEvent extends BaseEvent {
+  type: "NODE_START";
+  nodeId: string;
+  nodeType: "endpoint" | "wait" | "assertion";
+}
+
+export interface NodeEndEvent extends BaseEvent {
+  type: "NODE_END";
+  nodeId: string;
+  nodeType: "endpoint" | "wait" | "assertion";
+  success: boolean;
+  duration_ms: number;
+  error?: string;
+}
+
+/** HTTP-specific events (for endpoint nodes) */
+export interface HttpRequestEvent extends BaseEvent {
+  type: "HTTP_REQUEST";
+  nodeId: string;
+  attempt: number;
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  hasBody: boolean;
+}
+
+export interface HttpResponseEvent extends BaseEvent {
+  type: "HTTP_RESPONSE";
+  nodeId: string;
+  attempt: number;
+  status: number;
+  statusText: string;
+  duration_ms: number;
+  hasBody: boolean;
+}
+
+export interface HttpRetryEvent extends BaseEvent {
+  type: "HTTP_RETRY";
+  nodeId: string;
+  attempt: number;
+  maxAttempts: number;
+  reason: string;
+  nextRetryDelayMs?: number;
+}
+
+/** Assertion events */
+export interface AssertionResultEvent extends BaseEvent {
+  type: "ASSERTION_RESULT";
+  nodeId: string;
+  assertionIndex: number;
+  passed: boolean;
+  message: string;
+}
+
+/** Wait events */
+export interface WaitStartEvent extends BaseEvent {
+  type: "WAIT_START";
+  nodeId: string;
+  duration_ms: number;
+}
+
+/** Streaming/progress events from nodes */
+export interface NodeStreamEvent extends BaseEvent {
+  type: "NODE_STREAM";
+  nodeId: string;
+  chunk: string;
+}
+
+/** System/executor-level errors (not node failures) */
+export interface ErrorEvent extends BaseEvent {
+  type: "ERROR";
+  errorName: string;
+  message: string;
+  context?: string;
+  /** Only included in local/development mode */
+  stack?: string;
+}
+
+/** Union type of all execution events */
+export type ExecutionEvent =
+  | PlanStartEvent
+  | PlanEndEvent
+  | NodeStartEvent
+  | NodeEndEvent
+  | HttpRequestEvent
+  | HttpResponseEvent
+  | HttpRetryEvent
+  | AssertionResultEvent
+  | WaitStartEvent
+  | NodeStreamEvent
+  | ErrorEvent;