groundswell 0.0.2 → 1.0.0

package/src/debugger/tree-debugger.ts

@@ -1,255 +0,0 @@
-import type {
-  WorkflowNode,
-  WorkflowEvent,
-  WorkflowObserver,
-  LogEntry,
-} from '../types/index.js';
-import { Observable } from '../utils/observable.js';
-import type { Workflow } from '../core/workflow.js';
-
-/**
- * Status symbols for tree visualization
- */
-const STATUS_SYMBOLS: Record<string, string> = {
-  idle: '○',
-  running: '◐',
-  completed: '✓',
-  failed: '✗',
-  cancelled: '⊘',
-};
-
-/**
- * Tree debugger for real-time workflow visualization
- * Implements WorkflowObserver to receive all events
- */
-export class WorkflowTreeDebugger implements WorkflowObserver {
-  /** Root node of the workflow tree */
-  private root: WorkflowNode;
-
-  /** Observable stream of workflow events */
-  public readonly events: Observable<WorkflowEvent>;
-
-  /** Node lookup map for quick access */
-  private nodeMap: Map<string, WorkflowNode> = new Map();
-
-  /**
-   * Create a tree debugger attached to a workflow
-   * @param workflow The root workflow to debug
-   */
-  constructor(workflow: Workflow) {
-    this.root = workflow.getNode();
-    this.events = new Observable<WorkflowEvent>();
-
-    // Build initial node map
-    this.buildNodeMap(this.root);
-
-    // Register as observer on the workflow
-    workflow.addObserver(this);
-  }
-
-  /**
-   * Build node lookup map recursively
-   */
-  private buildNodeMap(node: WorkflowNode): void {
-    this.nodeMap.set(node.id, node);
-    for (const child of node.children) {
-      this.buildNodeMap(child);
-    }
-  }
-
-  /**
-   * Remove entire subtree from node map using BFS traversal
-   * O(k) complexity where k = number of nodes in subtree
-   * Uses iterative BFS to avoid stack overflow on deep trees
-   */
-  private removeSubtreeNodes(nodeId: string): void {
-    const node = this.nodeMap.get(nodeId);
-    if (!node) return;  // Already removed or never existed
-
-    // BFS traversal to collect all descendant IDs
-    const toRemove: string[] = [];
-    const queue: WorkflowNode[] = [node];
-
-    while (queue.length > 0) {
-      const current = queue.shift()!;
-      toRemove.push(current.id);
-      // Add children to queue for BFS traversal
-      queue.push(...current.children);
-    }
-
-    // Batch delete all collected keys (atomic update)
-    for (const id of toRemove) {
-      this.nodeMap.delete(id);
-    }
-  }
-
-  // WorkflowObserver implementation
-
-  onLog(_entry: LogEntry): void {
-    // Events are forwarded through the event stream
-  }
-
-  onEvent(event: WorkflowEvent): void {
-    // Handle structural events with incremental updates
-    switch (event.type) {
-      case 'childAttached':
-        // Keep existing logic - already optimal O(k)
-        this.buildNodeMap(event.child);
-        break;
-
-      case 'childDetached':
-        // NEW: Incremental subtree removal
-        this.removeSubtreeNodes(event.childId);
-        break;
-
-      case 'treeUpdated':
-        // NEW: Update root reference only
-        this.root = event.root;
-        break;
-
-      default:
-        // Non-structural events - no map update needed
-        break;
-    }
-
-    // Always forward to event stream (existing behavior)
-    this.events.next(event);
-  }
-
-  onStateUpdated(_node: WorkflowNode): void {
-    // State updates are available through the node
-  }
-
-  onTreeChanged(root: WorkflowNode): void {
-    // All tree changes now handled incrementally in onEvent()
-    // Just update root reference if different
-    if (this.root !== root) {
-      this.root = root;
-    }
-  }
-
-  // Public API
-
-  /**
-   * Get the current tree root
-   */
-  getTree(): WorkflowNode {
-    return this.root;
-  }
-
-  /**
-   * Get a node by ID
-   */
-  getNode(id: string): WorkflowNode | undefined {
-    return this.nodeMap.get(id);
-  }
-
-  /**
-   * Render tree as ASCII string
-   * @param node Starting node (defaults to root)
-   */
-  toTreeString(node?: WorkflowNode): string {
-    return this.renderTree(node ?? this.root, '', true, true);
-  }
-
-  /**
-   * Recursive tree rendering
-   */
-  private renderTree(
-    node: WorkflowNode,
-    prefix: string,
-    isLast: boolean,
-    isRoot: boolean
-  ): string {
-    let result = '';
-
-    // Status symbol and color indicator
-    const statusSymbol = STATUS_SYMBOLS[node.status] || '?';
-    const nodeInfo = `${statusSymbol} ${node.name} [${node.status}]`;
-
-    if (isRoot) {
-      result += nodeInfo + '\n';
-    } else {
-      const connector = isLast ? '└── ' : '├── ';
-      result += prefix + connector + nodeInfo + '\n';
-    }
-
-    // Render children
-    const childCount = node.children.length;
-    node.children.forEach((child, index) => {
-      const isLastChild = index === childCount - 1;
-      const childPrefix = isRoot ? '' : prefix + (isLast ? '    ' : '│   ');
-      result += this.renderTree(child, childPrefix, isLastChild, false);
-    });
-
-    return result;
-  }
-
-  /**
-   * Render logs as formatted string
-   * @param node Starting node (defaults to root, includes descendants)
-   */
-  toLogString(node?: WorkflowNode): string {
-    const logs = this.collectLogs(node ?? this.root);
-
-    // Sort by timestamp
-    logs.sort((a, b) => a.timestamp - b.timestamp);
-
-    return logs
-      .map((log) => {
-        const time = new Date(log.timestamp).toISOString();
-        const level = log.level.toUpperCase().padEnd(5);
-        const nodeRef = this.nodeMap.get(log.workflowId);
-        const nodeName = nodeRef?.name ?? log.workflowId;
-        return `[${time}] ${level} [${nodeName}] ${log.message}`;
-      })
-      .join('\n');
-  }
-
-  /**
-   * Collect all logs from a node and its descendants
-   */
-  private collectLogs(node: WorkflowNode): LogEntry[] {
-    const logs: LogEntry[] = [...node.logs];
-
-    for (const child of node.children) {
-      logs.push(...this.collectLogs(child));
-    }
-
-    return logs;
-  }
-
-  /**
-   * Get summary statistics for the tree
-   */
-  getStats(): {
-    totalNodes: number;
-    byStatus: Record<string, number>;
-    totalLogs: number;
-    totalEvents: number;
-  } {
-    const stats = {
-      totalNodes: 0,
-      byStatus: {} as Record<string, number>,
-      totalLogs: 0,
-      totalEvents: 0,
-    };
-
-    this.collectStats(this.root, stats);
-    return stats;
-  }
-
-  private collectStats(
-    node: WorkflowNode,
-    stats: ReturnType<typeof this.getStats>
-  ): void {
-    stats.totalNodes++;
-    stats.byStatus[node.status] = (stats.byStatus[node.status] || 0) + 1;
-    stats.totalLogs += node.logs.length;
-    stats.totalEvents += node.events.length;
-
-    for (const child of node.children) {
-      this.collectStats(child, stats);
-    }
-  }
-}

package/src/decorators/observed-state.ts

@@ -1,95 +0,0 @@
-import type { StateFieldMetadata, SerializedWorkflowState } from '../types/index.js';
-
-/**
- * WeakMap storing field metadata keyed by class prototype
- * Structure: Map<propertyKey, StateFieldMetadata>
- */
-const OBSERVED_STATE_FIELDS = new WeakMap<object, Map<string, StateFieldMetadata>>();
-
-/**
- * @ObservedState decorator
- * Marks a class field for inclusion in state snapshots
- *
- * @example
- * class MyWorkflow extends Workflow {
- *   @ObservedState()
- *   currentStep!: string;
- *
- *   @ObservedState({ redact: true })
- *   sensitiveData!: string;
- *
- *   @ObservedState({ hidden: true })
- *   internalState!: object;
- * }
- */
-export function ObservedState(meta: StateFieldMetadata = {}) {
-  return function (
-    _value: undefined,
-    context: ClassFieldDecoratorContext
-  ): void {
-    const propertyKey = String(context.name);
-
-    // Use addInitializer to register field when class is instantiated
-    context.addInitializer(function (this: unknown) {
-      const instance = this as object;
-      const proto = Object.getPrototypeOf(instance);
-      let map = OBSERVED_STATE_FIELDS.get(proto);
-      if (!map) {
-        map = new Map();
-        OBSERVED_STATE_FIELDS.set(proto, map);
-      }
-      map.set(propertyKey, meta);
-    });
-  };
-}
-
-/**
- * Get all observed state from an object instance
- * Applies hidden and redact transformations
- */
-export function getObservedState(obj: object): SerializedWorkflowState {
-  const proto = Object.getPrototypeOf(obj);
-  const map = OBSERVED_STATE_FIELDS.get(proto);
-
-  if (!map) {
-    return {};
-  }
-
-  const result: SerializedWorkflowState = {};
-
-  for (const [key, meta] of map) {
-    // Skip hidden fields
-    if (meta.hidden) {
-      continue;
-    }
-
-    let value = (obj as Record<string, unknown>)[key];
-
-    // Redact sensitive fields
-    if (meta.redact) {
-      value = '***';
-    }
-
-    result[key] = value;
-  }
-
-  return result;
-}
-
-/**
- * Check if a field is observed on an object
- */
-export function isFieldObserved(obj: object, fieldName: string): boolean {
-  const proto = Object.getPrototypeOf(obj);
-  const map = OBSERVED_STATE_FIELDS.get(proto);
-  return map?.has(fieldName) ?? false;
-}
-
-/**
- * Get metadata for a specific field
- */
-export function getFieldMetadata(obj: object, fieldName: string): StateFieldMetadata | undefined {
-  const proto = Object.getPrototypeOf(obj);
-  const map = OBSERVED_STATE_FIELDS.get(proto);
-  return map?.get(fieldName);
-}

package/src/decorators/step.ts

@@ -1,139 +0,0 @@
-import type { StepOptions, WorkflowError, WorkflowNode, LogEntry, WorkflowEvent } from '../types/index.js';
-import { getObservedState } from './observed-state.js';
-import { runInContext, type AgentExecutionContext } from '../core/context.js';
-import { generateId } from '../utils/id.js';
-
-// Type for workflow-like objects that @Step can decorate methods on
-interface WorkflowLike {
-  id: string;
-  node: WorkflowNode;
-  logger: {
-    info(message: string, data?: unknown): void;
-  };
-  emitEvent(event: WorkflowEvent): void;
-  snapshotState(): void;
-}
-
-/**
- * @Step decorator
- * Wraps a method to emit step events, handle errors, and optionally snapshot state
- *
- * @example
- * class MyWorkflow extends Workflow {
- *   @Step({ snapshotState: true, trackTiming: true })
- *   async processData() {
- *     // ... step logic
- *   }
- * }
- */
-export function Step(opts: StepOptions = {}) {
-  return function <This, Args extends unknown[], Return>(
-    originalMethod: (this: This, ...args: Args) => Promise<Return>,
-    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>
-  ) {
-    const methodName = String(context.name);
-
-    // CRITICAL: Use regular function, not arrow function, to preserve 'this'
-    async function stepWrapper(this: This, ...args: Args): Promise<Return> {
-      // Cast to WorkflowLike for type safety when accessing workflow properties
-      const wf = this as unknown as WorkflowLike;
-      const stepName = opts.name ?? methodName;
-      const startTime = Date.now();
-
-      // Log start if requested
-      if (opts.logStart) {
-        wf.logger.info(`STEP START: ${stepName}`);
-      }
-
-      // Emit step start event
-      wf.emitEvent({
-        type: 'stepStart',
-        node: wf.node,
-        step: stepName,
-      });
-
-      // Create step node for hierarchy tracking
-      const stepNode: WorkflowNode = {
-        id: generateId(),
-        name: stepName,
-        parent: wf.node,
-        children: [],
-        status: 'running',
-        logs: [],
-        events: [],
-        stateSnapshot: null,
-      };
-
-      // Create execution context for agent/prompt operations within this step
-      const executionContext: AgentExecutionContext = {
-        workflowNode: stepNode,
-        emitEvent: (event: WorkflowEvent) => {
-          stepNode.events.push(event);
-          wf.emitEvent(event);
-        },
-        workflowId: wf.id,
-      };
-
-      try {
-        // Execute the original method within the execution context
-        // This allows Agent.prompt() calls to automatically capture events
-        const result = await runInContext(executionContext, async () => {
-          return originalMethod.call(this, ...args);
-        });
-
-        // Update step node status
-        stepNode.status = 'completed';
-
-        // Snapshot state if requested
-        if (opts.snapshotState) {
-          wf.snapshotState();
-        }
-
-        // Calculate duration and emit end event
-        const duration = Date.now() - startTime;
-        if (opts.trackTiming !== false) {
-          wf.emitEvent({
-            type: 'stepEnd',
-            node: wf.node,
-            step: stepName,
-            duration,
-          });
-        }
-
-        // Log finish if requested
-        if (opts.logFinish) {
-          wf.logger.info(`STEP END: ${stepName} (${duration}ms)`);
-        }
-
-        return result;
-      } catch (err: unknown) {
-        // Update step node status
-        stepNode.status = 'failed';
-        // Create rich error with context
-        const error = err as Error;
-        const snap = getObservedState(this as object);
-
-        const workflowError: WorkflowError = {
-          message: error?.message ?? 'Unknown error',
-          original: err,
-          workflowId: wf.id,
-          stack: error?.stack,
-          state: snap,
-          logs: [...wf.node.logs] as LogEntry[],
-        };
-
-        // Emit error event
-        wf.emitEvent({
-          type: 'error',
-          node: wf.node,
-          error: workflowError,
-        });
-
-        // Re-throw the enriched error
-        throw workflowError;
-      }
-    }
-
-    return stepWrapper;
-  };
-}

package/src/decorators/task.ts

@@ -1,159 +0,0 @@
-import type { TaskOptions, WorkflowNode, WorkflowEvent, WorkflowError, SerializedWorkflowState } from '../types/index.js';
-import { mergeWorkflowErrors } from '../utils/workflow-error-utils.js';
-
-// Type for workflow-like objects
-interface WorkflowLike {
-  id: string;
-  node: WorkflowNode;
-  emitEvent(event: WorkflowEvent): void;
-  attachChild(child: WorkflowLike): void;
-}
-
-// Minimal Workflow type for checking if something is a workflow
-interface WorkflowClass {
-  id: string;
-  parent: WorkflowLike | null;
-  run(...args: unknown[]): Promise<unknown>;
-}
-
-/**
- * @Task decorator
- * Wraps a method that returns child workflow(s), automatically attaching them
- *
- * @example
- * class ParentWorkflow extends Workflow {
- *   @Task({ concurrent: true })
- *   async createChildren(): Promise<ChildWorkflow[]> {
- *     return [
- *       new ChildWorkflow('child1', this),
- *       new ChildWorkflow('child2', this),
- *     ];
- *   }
- * }
- *
- * @example Non-workflow return (silently skipped)
- * class MyWorkflow extends Workflow {
- *   @Task()
- *   async returnsString(): Promise<string> {
- *     return 'not a workflow';  // Returned as-is, not attached
- *   }
- * }
- *
- * @example Mixed return (only workflows attached)
- * class MyWorkflow extends Workflow {
- *   @Task()
- *   async mixedReturn(): Promise<(Workflow | string)[]> {
- *     return [
- *       new ChildWorkflow('child1', this),  // Attached
- *       'some string',                       // Skipped
- *       new ChildWorkflow('child2', this),  // Attached
- *     ];
- *   }
- * }
- *
- * Validation Behavior
- *
- * The decorator uses lenient validation for return values:
- * - Workflow objects (with 'id' property) are automatically attached
- * - Non-workflow objects are silently skipped (not attached)
- * - The original return value is always preserved
- *
- * This lenient approach enables:
- * - Duck-typing: Works with workflow-like objects, not just Workflow instances
- * - Flexible signatures: Methods can return any type without breaking
- * - Graceful handling: Edge cases (null, undefined, primitives) don't throw errors
- */
-export function Task(opts: TaskOptions = {}) {
-  return function <This, Args extends unknown[], Return>(
-    originalMethod: (this: This, ...args: Args) => Promise<Return>,
-    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return>>
-  ) {
-    const methodName = String(context.name);
-
-    // CRITICAL: Use regular function, not arrow function
-    async function taskWrapper(this: This, ...args: Args): Promise<Return> {
-      // Cast to WorkflowLike for type safety when accessing workflow properties
-      const wf = this as unknown as WorkflowLike;
-      const taskName = opts.name ?? methodName;
-
-      // Emit task start event
-      wf.emitEvent({
-        type: 'taskStart',
-        node: wf.node,
-        task: taskName,
-      });
-
-      // Execute the original method
-      const result = await originalMethod.call(this, ...args);
-
-      // Process returned workflows
-      const workflows = Array.isArray(result) ? result : [result];
-
-      for (const workflow of workflows) {
-        // Type guard to check if it's a workflow
-        if (workflow && typeof workflow === 'object' && 'id' in workflow) {
-          const childWf = workflow as WorkflowClass;
-
-          // Only attach if not already attached (parent not set by constructor)
-          if (!childWf.parent) {
-            childWf.parent = wf;
-            wf.attachChild(childWf as unknown as WorkflowLike);
-          }
-        }
-      }
-
-      // If concurrent option is set and we have multiple workflows, run them in parallel
-      if (opts.concurrent && Array.isArray(result)) {
-        const runnable = workflows.filter(
-          (w): w is WorkflowClass =>
-            w && typeof w === 'object' && 'run' in w && typeof w.run === 'function'
-        );
-
-        if (runnable.length > 0) {
-          const results = await Promise.allSettled(runnable.map((w) => w.run()));
-
-          const rejected = results.filter(
-            (r): r is PromiseRejectedResult => r.status === 'rejected'
-          );
-
-          if (rejected.length > 0) {
-            // Check if error merge strategy is enabled
-            if (opts.errorMergeStrategy?.enabled) {
-              // Extract WorkflowError objects from rejected promises
-              const errors = rejected.map((r) => r.reason as WorkflowError);
-
-              // Merge errors using custom combine() or default merger
-              const mergedError = opts.errorMergeStrategy?.combine
-                ? opts.errorMergeStrategy.combine(errors)
-                : mergeWorkflowErrors(errors, taskName, wf.id, runnable.length);
-
-              // Emit error event with merged error
-              wf.emitEvent({
-                type: 'error',
-                node: wf.node,
-                error: mergedError,
-              });
-
-              // Throw merged error
-              throw mergedError;
-            }
-
-            // Backward compatibility: throw first error
-            throw rejected[0].reason;
-          }
-        }
-      }
-
-      // Emit task end event
-      wf.emitEvent({
-        type: 'taskEnd',
-        node: wf.node,
-        task: taskName,
-      });
-
-      return result;
-    }
-
-    return taskWrapper;
-  };
-}

package/src/examples/tdd-orchestrator.ts

@@ -1,65 +0,0 @@
-import { Workflow } from '../core/workflow.js';
-import { Step } from '../decorators/step.js';
-import { Task } from '../decorators/task.js';
-import { ObservedState } from '../decorators/observed-state.js';
-import { TestCycleWorkflow } from './test-cycle-workflow.js';
-
-/**
- * Example parent workflow demonstrating TDD orchestration
- */
-export class TDDOrchestrator extends Workflow {
-  @ObservedState()
-  cycleCount: number = 0;
-
-  @ObservedState()
-  maxCycles: number = 3;
-
-  @ObservedState({ redact: true })
-  apiKey: string = 'secret-key';
-
-  @Step({ logStart: true, logFinish: true })
-  async setupEnvironment(): Promise<void> {
-    this.logger.info('Setting up TDD environment');
-    // Simulate environment setup
-    await this.delay(50);
-    this.logger.debug('Environment ready');
-  }
-
-  @Task()
-  async runCycle(): Promise<TestCycleWorkflow> {
-    this.cycleCount++;
-    this.logger.info(`Starting cycle ${this.cycleCount}/${this.maxCycles}`);
-    return new TestCycleWorkflow(`Cycle-${this.cycleCount}`, this);
-  }
-
-  async run(): Promise<void> {
-    this.setStatus('running');
-    this.logger.info('TDD Orchestrator starting');
-
-    try {
-      await this.setupEnvironment();
-
-      while (this.cycleCount < this.maxCycles) {
-        try {
-          const cycle = await this.runCycle();
-          await cycle.run();
-          this.logger.info(`Cycle ${this.cycleCount} completed successfully`);
-        } catch (error) {
-          this.logger.warn(`Cycle ${this.cycleCount} failed, continuing...`);
-          // In real implementation, analyze error and potentially restart
-        }
-      }
-
-      this.setStatus('completed');
-      this.logger.info('TDD Orchestrator completed all cycles');
-    } catch (error) {
-      this.setStatus('failed');
-      this.logger.error('TDD Orchestrator failed', { error });
-      throw error;
-    }
-  }
-
-  private delay(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-}