@auto-engineer/pipeline 0.0.1

package/src/config/pipeline-config.ts

@@ -0,0 +1,32 @@
+import type { Pipeline } from '../builder/define';
+import { adaptHandlers } from '../plugins/handler-adapter';
+import { PluginLoader } from '../plugins/plugin-loader';
+import type { CommandHandlerWithMetadata } from '../server/pipeline-server';
+
+export interface PipelineConfig {
+  plugins: string[];
+  pipeline: Pipeline;
+}
+
+export interface LoadedPipelineConfig {
+  handlers: CommandHandlerWithMetadata[];
+  pipeline: Pipeline;
+}
+
+export function pipelineConfig(config: PipelineConfig): PipelineConfig {
+  return config;
+}
+
+export async function loadPipelineConfig(
+  config: PipelineConfig,
+  workspaceRoot?: string,
+): Promise<LoadedPipelineConfig> {
+  const loader = new PluginLoader(workspaceRoot);
+  const pluginHandlers = await loader.loadPlugins(config.plugins);
+  const handlers = adaptHandlers(pluginHandlers);
+
+  return {
+    handlers,
+    pipeline: config.pipeline,
+  };
+}

package/src/core/descriptors.specs.ts

@@ -0,0 +1,28 @@
+import type { KeyExtractor, PipelineDescriptor } from './descriptors';
+import type { Event } from './types';
+
+describe('PipelineDescriptor', () => {
+  it('should create PipelineDescriptor', () => {
+    const descriptor: PipelineDescriptor = {
+      name: 'test-pipeline',
+      version: '1.0.0',
+      keys: new Map(),
+      handlers: [],
+    };
+    expect(descriptor.name).toBe('test-pipeline');
+  });
+
+  it('should store key extractors', () => {
+    type SliceEvent = Event & { data: { slicePath?: string } };
+    const extractor: KeyExtractor = (e) => (e as SliceEvent).data.slicePath ?? '';
+    const keys = new Map<string, KeyExtractor>();
+    keys.set('bySlice', extractor);
+
+    const descriptor: PipelineDescriptor = {
+      name: 'test',
+      keys,
+      handlers: [],
+    };
+    expect(descriptor.keys.get('bySlice')).toBe(extractor);
+  });
+});

package/src/core/descriptors.ts

@@ -0,0 +1,99 @@
+import type { Event } from '@auto-engineer/message-bus';
+import type { PipelineContext } from '../runtime/context';
+import type { CommandDispatch } from './types';
+
+export type KeyExtractor = (event: Event) => string;
+
+export type EventPredicate = (event: Event) => boolean;
+
+export interface EmitHandlerDescriptor {
+  type: 'emit';
+  eventType: string;
+  predicate?: EventPredicate;
+  commands: CommandDispatch[];
+}
+
+export interface SuccessContext<T = unknown> {
+  results: T[];
+  duration: number;
+  triggerEvent: Event;
+}
+
+export interface FailureContext<T = unknown> {
+  failures: Array<{ key: string; error: unknown }>;
+  successes: T[];
+  triggerEvent: Event;
+}
+
+export interface GatherEventConfig<T = unknown> {
+  eventType: string;
+  dataFactory: (context: T) => Record<string, unknown>;
+}
+
+export interface RunAwaitHandlerDescriptor {
+  type: 'run-await';
+  eventType: string;
+  predicate?: EventPredicate;
+  commands: CommandDispatch[] | ((event: Event) => CommandDispatch[]);
+  awaitConfig: {
+    keyName: string;
+    key: KeyExtractor;
+    timeout?: number;
+  };
+  onSuccess?: GatherEventConfig<SuccessContext>;
+  onFailure?: GatherEventConfig<FailureContext>;
+}
+
+export interface ForEachPhasedDescriptor {
+  type: 'foreach-phased';
+  eventType: string;
+  predicate?: EventPredicate;
+  itemsSelector: (event: Event) => unknown[];
+  phases: readonly string[];
+  classifier: (item: unknown) => string;
+  stopOnFailure: boolean;
+  emitFactory: (item: unknown, phase: string, event: Event) => CommandDispatch;
+  completion: {
+    successEvent: string;
+    failureEvent: string;
+    itemKey: KeyExtractor;
+  };
+}
+
+export interface CustomHandlerDescriptor {
+  type: 'custom';
+  eventType: string;
+  predicate?: EventPredicate;
+  handler: (event: Event, ctx: PipelineContext) => void | Promise<void>;
+  declaredEmits?: string[];
+}
+
+type SettledSendFunction = (commandType: string, data: unknown) => void;
+
+export type SettledHandler = (
+  events: Record<string, Event[]>,
+  send: SettledSendFunction,
+) => void | { persist: boolean };
+
+export interface SettledHandlerDescriptor {
+  type: 'settled';
+  commandTypes: readonly string[];
+  handler: SettledHandler;
+  dispatches?: readonly string[];
+}
+
+export type EventHandlerDescriptor =
+  | EmitHandlerDescriptor
+  | RunAwaitHandlerDescriptor
+  | ForEachPhasedDescriptor
+  | CustomHandlerDescriptor;
+
+export type HandlerDescriptor = EventHandlerDescriptor | SettledHandlerDescriptor;
+
+export interface PipelineDescriptor {
+  name: string;
+  version?: string;
+  description?: string;
+  keys: Map<string, KeyExtractor>;
+  handlers: HandlerDescriptor[];
+}

package/src/core/types.specs.ts

@@ -0,0 +1,44 @@
+import { type Command, type CommandDispatch, dispatch, type Event } from './types';
+
+describe('Core Types', () => {
+  it('should re-export Command and Event from message-bus', () => {
+    const cmd: Command = { type: 'Test', data: {} };
+    const evt: Event = { type: 'TestDone', data: {} };
+
+    expect(cmd.type).toBe('Test');
+    expect(evt.type).toBe('TestDone');
+  });
+});
+
+describe('CommandDispatch', () => {
+  it('should create CommandDispatch with static data', () => {
+    const cmd: CommandDispatch = {
+      commandType: 'CheckTests',
+      data: { targetDirectory: './src', scope: 'slice' },
+    };
+    expect(cmd).toEqual({
+      commandType: 'CheckTests',
+      data: { targetDirectory: './src', scope: 'slice' },
+    });
+  });
+
+  it('should create CommandDispatch with data factory', () => {
+    const cmd: CommandDispatch = {
+      commandType: 'ImplementSlice',
+      data: (e: Event) => ({ slicePath: e.data.path }),
+    };
+    const event: Event = { type: 'SliceGenerated', data: { path: './slice' } };
+    const resolved = typeof cmd.data === 'function' ? cmd.data(event) : cmd.data;
+    expect(resolved).toEqual({ slicePath: './slice' });
+  });
+});
+
+describe('dispatch()', () => {
+  it('should create CommandDispatch via dispatch()', () => {
+    const cmd = dispatch('CheckTests', { targetDirectory: './src' });
+    expect(cmd).toEqual({
+      commandType: 'CheckTests',
+      data: { targetDirectory: './src' },
+    });
+  });
+});

package/src/core/types.ts

@@ -0,0 +1,16 @@
+import type { Event } from '@auto-engineer/message-bus';
+
+export type { Command, Event } from '@auto-engineer/message-bus';
+
+export type DataRecord = Record<string, unknown>;
+
+export type DataOrFactory<D extends DataRecord = DataRecord> = D | ((event: Event) => D);
+
+export interface CommandDispatch<D extends DataRecord = DataRecord> {
+  commandType: string;
+  data: DataOrFactory<D>;
+}
+
+export function dispatch<D extends DataRecord>(commandType: string, data: DataOrFactory<D>): CommandDispatch<D> {
+  return { commandType, data };
+}

package/src/graph/types.specs.ts

@@ -0,0 +1,176 @@
+import { define } from '../builder/define';
+import type { GraphIR } from './types';
+
+describe('GraphIR type', () => {
+  it('should define GraphIR with nodes and edges', () => {
+    const graph: GraphIR = {
+      nodes: [
+        { id: 'evt:Start', type: 'event', label: 'Start' },
+        { id: 'cmd:Process', type: 'command', label: 'Process' },
+      ],
+      edges: [{ from: 'evt:Start', to: 'cmd:Process', label: 'triggers' }],
+    };
+    expect(graph.nodes).toHaveLength(2);
+  });
+});
+
+describe('Pipeline.toGraph()', () => {
+  it('should extract graph from emit handler', () => {
+    const pipeline = define('test').on('Start').emit('Process', {}).build();
+
+    const graph = pipeline.toGraph();
+    expect(graph.nodes.some((n) => n.id === 'evt:Start')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'cmd:Process')).toBe(true);
+  });
+
+  it('should include edges from event to commands', () => {
+    const pipeline = define('test').on('Start').emit('Process', {}).build();
+
+    const graph = pipeline.toGraph();
+    expect(graph.edges.some((e) => e.from === 'evt:Start' && e.to === 'cmd:Process')).toBe(true);
+  });
+
+  it('should extract graph from run-await handler', () => {
+    const pipeline = define('test')
+      .on('BatchReady')
+      .run([{ commandType: 'ProcessItem', data: {} }])
+      .awaitAll('byItem', () => 'key')
+      .onSuccess('BatchComplete', () => ({}))
+      .onFailure('BatchFailed', () => ({}))
+      .build();
+
+    const graph = pipeline.toGraph();
+    expect(graph.nodes.some((n) => n.id === 'evt:BatchReady')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'cmd:ProcessItem')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'evt:BatchComplete')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'evt:BatchFailed')).toBe(true);
+  });
+
+  it('should extract graph from run-await handler with command factory', () => {
+    type BatchEvent = { data: { items: Array<{ id: string }> } };
+    const pipeline = define('test')
+      .on('BatchReady')
+      .run((e: BatchEvent) => e.data.items.map((item) => ({ commandType: 'ProcessItem', data: { id: item.id } })))
+      .awaitAll('byItem', () => 'key')
+      .build();
+
+    const graph = pipeline.toGraph();
+    expect(graph.nodes.some((n) => n.id === 'evt:BatchReady')).toBe(true);
+    expect(graph.nodes).toHaveLength(1);
+    expect(graph.edges).toHaveLength(0);
+  });
+
+  it('should extract graph from foreach-phased handler', () => {
+    const pipeline = define('test')
+      .on('ItemsReady')
+      .forEach(() => [])
+      .groupInto(['phase1'], () => 'phase1')
+      .process('ProcessItem', () => ({}))
+      .onComplete({ success: 'AllDone', failure: 'SomeFailed', itemKey: () => '' })
+      .build();
+
+    const graph = pipeline.toGraph();
+    expect(graph.nodes.some((n) => n.id === 'evt:ItemsReady')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'cmd:ProcessItem')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'evt:AllDone')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'evt:SomeFailed')).toBe(true);
+  });
+
+  it('should include edges from command to onComplete success/failure events', () => {
+    const pipeline = define('test')
+      .on('ItemsReady')
+      .forEach(() => [])
+      .groupInto(['phase1'], () => 'phase1')
+      .process('ProcessItem', () => ({}))
+      .onComplete({ success: 'AllDone', failure: 'SomeFailed', itemKey: () => '' })
+      .build();
+
+    const graph = pipeline.toGraph();
+    const hasSuccessEdge = graph.edges.some((e) => e.from === 'cmd:ProcessItem' && e.to === 'evt:AllDone');
+    const hasFailureEdge = graph.edges.some((e) => e.from === 'cmd:ProcessItem' && e.to === 'evt:SomeFailed');
+    expect(hasSuccessEdge).toBe(true);
+    expect(hasFailureEdge).toBe(true);
+  });
+
+  it('should extract graph from custom handler using declaredEmits', () => {
+    const pipeline = define('test')
+      .on('CustomEvent')
+      .handle(async () => {}, { emits: ['EventA', 'EventB'] })
+      .build();
+
+    const graph = pipeline.toGraph();
+    expect(graph.nodes.some((n) => n.id === 'evt:CustomEvent')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'evt:EventA')).toBe(true);
+    expect(graph.nodes.some((n) => n.id === 'evt:EventB')).toBe(true);
+  });
+
+  it('should extract graph from custom handler without declaredEmits', () => {
+    const pipeline = define('test')
+      .on('CustomEvent')
+      .handle(async () => {})
+      .build();
+
+    const graph = pipeline.toGraph();
+    expect(graph.nodes.some((n) => n.id === 'evt:CustomEvent')).toBe(true);
+    expect(graph.nodes).toHaveLength(1);
+  });
+
+  it('should handle multiple handlers in pipeline', () => {
+    const pipeline = define('test').on('Start').emit('ProcessA', {}).on('ProcessADone').emit('ProcessB', {}).build();
+
+    const graph = pipeline.toGraph();
+    expect(graph.nodes).toHaveLength(4);
+    expect(graph.edges).toHaveLength(2);
+  });
+
+  it('should deduplicate nodes with same id', () => {
+    const pipeline = define('test').on('Start').emit('Process', {}).on('Start').emit('OtherProcess', {}).build();
+
+    const graph = pipeline.toGraph();
+    const startNodes = graph.nodes.filter((n) => n.id === 'evt:Start');
+    expect(startNodes).toHaveLength(1);
+  });
+
+  it('should create settled node with type settled', () => {
+    const pipeline = define('test')
+      .on('Start')
+      .emit('CheckA', {})
+      .settled(['CheckA'])
+      .dispatch({ dispatches: [] }, () => {})
+      .build();
+
+    const graph = pipeline.toGraph();
+    const settledNode = graph.nodes.find((n) => n.id.startsWith('settled:'));
+    expect(settledNode).toBeDefined();
+    expect(settledNode?.type).toBe('settled');
+  });
+
+  it('should mark edges from settled nodes to dispatched commands as backLink', () => {
+    const pipeline = define('test')
+      .on('Start')
+      .emit('CheckA', {})
+      .settled(['CheckA'])
+      .dispatch({ dispatches: ['RetryCommand'] }, () => {})
+      .build();
+
+    const graph = pipeline.toGraph();
+    const backEdge = graph.edges.find((e) => e.from.startsWith('settled:') && e.to === 'cmd:RetryCommand');
+    expect(backEdge).toBeDefined();
+    expect(backEdge?.backLink).toBe(true);
+  });
+
+  it('should not mark forward edges as backLink', () => {
+    const pipeline = define('test')
+      .on('Start')
+      .emit('CheckA', {})
+      .settled(['CheckA'])
+      .dispatch({ dispatches: ['RetryCommand'] }, () => {})
+      .build();
+
+    const graph = pipeline.toGraph();
+    const forwardEdges = graph.edges.filter((e) => !e.from.startsWith('settled:'));
+    for (const edge of forwardEdges) {
+      expect(edge.backLink).not.toBe(true);
+    }
+  });
+});

package/src/graph/types.ts

@@ -0,0 +1,19 @@
+export type NodeType = 'event' | 'command' | 'settled';
+
+export interface GraphNode {
+  id: string;
+  type: NodeType;
+  label: string;
+}
+
+export interface GraphEdge {
+  from: string;
+  to: string;
+  label?: string;
+  backLink?: boolean;
+}
+
+export interface GraphIR {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+export type {
+  CompletionConfig,
+  EmitChain,
+  ForEachBuilder,
+  GatherBuilder,
+  GatherChain,
+  HandleChain,
+  HandleOptions,
+  PhasedBuilder,
+  PhasedChain,
+  PhasedTerminal,
+  Pipeline,
+  PipelineBuilder,
+  RunBuilder,
+  TriggerBuilder,
+} from './builder/define';
+export { define } from './builder/define';
+export type {
+  CustomHandlerDescriptor,
+  EmitHandlerDescriptor,
+  EventPredicate,
+  FailureContext,
+  ForEachPhasedDescriptor,
+  GatherEventConfig,
+  HandlerDescriptor,
+  KeyExtractor,
+  PipelineDescriptor,
+  RunAwaitHandlerDescriptor,
+  SuccessContext,
+} from './core/descriptors';
+export type { Command, CommandDispatch, Event } from './core/types';
+export { dispatch } from './core/types';
+
+export type { GraphEdge, GraphIR, GraphNode, NodeType } from './graph/types';
+export type { EventLoggerOptions, LogEntry } from './logging/event-logger';
+export { EventLogger } from './logging/event-logger';
+
+export { AwaitTracker } from './runtime/await-tracker';
+export type { PipelineContext, RuntimeConfig } from './runtime/context';
+export { EventCommandMapper } from './runtime/event-command-map';
+export { PhasedExecutor } from './runtime/phased-executor';
+export { PipelineRuntime } from './runtime/pipeline-runtime';
+export { SettledTracker } from './runtime/settled-tracker';
+export type { CommandHandlerWithMetadata, PipelineServerConfig } from './server/pipeline-server';
+export { PipelineServer } from './server/pipeline-server';
+export { SSEManager } from './server/sse-manager';
+export type { SnapshotDiff, SnapshotResult } from './testing/snapshot-compare';
+export {
+  compareEventSequence,
+  containsSubsequence,
+  findMissingEvents,
+  findUnexpectedEvents,
+  formatSnapshotDiff,
+} from './testing/snapshot-compare';

package/src/logging/event-logger.specs.ts

@@ -0,0 +1,100 @@
+import type { Event } from '@auto-engineer/message-bus';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { EventLogger } from './event-logger';
+
+describe('EventLogger', () => {
+  let logger: EventLogger;
+
+  beforeEach(() => {
+    logger = new EventLogger();
+  });
+
+  describe('logging', () => {
+    it('should log events', () => {
+      const event: Event = { type: 'TestEvent', data: { foo: 'bar' } };
+      logger.log(event);
+      expect(logger.getEntries()).toHaveLength(1);
+      expect(logger.getEntries()[0].event).toEqual(event);
+    });
+
+    it('should add timestamp to entries', () => {
+      const event: Event = { type: 'TestEvent', data: {} };
+      logger.log(event);
+      const entry = logger.getEntries()[0];
+      expect(entry.timestamp).toBeDefined();
+      expect(new Date(entry.timestamp).getTime()).toBeLessThanOrEqual(Date.now());
+    });
+
+    it('should extract correlationId', () => {
+      const event: Event = { type: 'TestEvent', correlationId: 'c1', data: {} };
+      logger.log(event);
+      expect(logger.getEntries()[0].correlationId).toBe('c1');
+    });
+
+    it('should call onLog callback', () => {
+      const logged: Event[] = [];
+      logger = new EventLogger({
+        onLog: (entry) => logged.push(entry.event),
+      });
+
+      logger.log({ type: 'E1', data: {} });
+      logger.log({ type: 'E2', data: {} });
+
+      expect(logged).toHaveLength(2);
+      expect(logged.map((e) => e.type)).toEqual(['E1', 'E2']);
+    });
+  });
+
+  describe('queries', () => {
+    it('should filter by correlationId', () => {
+      logger.log({ type: 'E1', correlationId: 'c1', data: {} });
+      logger.log({ type: 'E2', correlationId: 'c2', data: {} });
+      logger.log({ type: 'E3', correlationId: 'c1', data: {} });
+
+      const c1Events = logger.getEntriesByCorrelationId('c1');
+      expect(c1Events).toHaveLength(2);
+      expect(c1Events.map((e) => e.event.type)).toEqual(['E1', 'E3']);
+    });
+
+    it('should return event types', () => {
+      logger.log({ type: 'A', data: {} });
+      logger.log({ type: 'B', data: {} });
+      logger.log({ type: 'C', data: {} });
+
+      expect(logger.getEventTypes()).toEqual(['A', 'B', 'C']);
+    });
+
+    it('should preserve event type order', () => {
+      logger.log({ type: 'Started', data: {} });
+      logger.log({ type: 'Processing', data: {} });
+      logger.log({ type: 'Completed', data: {} });
+
+      expect(logger.getEventTypes()).toEqual(['Started', 'Processing', 'Completed']);
+    });
+  });
+
+  describe('management', () => {
+    it('should clear entries', () => {
+      logger.log({ type: 'E1', data: {} });
+      logger.log({ type: 'E2', data: {} });
+
+      logger.clear();
+
+      expect(logger.getEntries()).toHaveLength(0);
+    });
+
+    it('should serialize to JSON', () => {
+      logger.log({ type: 'E1', data: { x: 1 } });
+      const json = logger.toJSON();
+      expect(json).toHaveLength(1);
+      expect(json[0].event.type).toBe('E1');
+    });
+
+    it('should return copy of entries', () => {
+      logger.log({ type: 'E1', data: {} });
+      const entries = logger.getEntries();
+      entries.push({ timestamp: '', event: { type: 'Fake', data: {} } });
+      expect(logger.getEntries()).toHaveLength(1);
+    });
+  });
+});

package/src/logging/event-logger.ts

@@ -0,0 +1,50 @@
+import type { Event } from '@auto-engineer/message-bus';
+
+export interface LogEntry {
+  timestamp: string;
+  event: Event;
+  correlationId?: string;
+}
+
+export interface EventLoggerOptions {
+  onLog?: (entry: LogEntry) => void;
+}
+
+export class EventLogger {
+  private entries: LogEntry[] = [];
+  private readonly onLog?: (entry: LogEntry) => void;
+
+  constructor(options?: EventLoggerOptions) {
+    this.onLog = options?.onLog;
+  }
+
+  log(event: Event): void {
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      event,
+      correlationId: event.correlationId,
+    };
+    this.entries.push(entry);
+    this.onLog?.(entry);
+  }
+
+  getEntries(): LogEntry[] {
+    return [...this.entries];
+  }
+
+  getEntriesByCorrelationId(correlationId: string): LogEntry[] {
+    return this.entries.filter((e) => e.correlationId === correlationId);
+  }
+
+  getEventTypes(): string[] {
+    return this.entries.map((e) => e.event.type);
+  }
+
+  clear(): void {
+    this.entries = [];
+  }
+
+  toJSON(): LogEntry[] {
+    return this.getEntries();
+  }
+}