groundswell 0.0.2 → 1.0.0

package/dist/debugger/tree-debugger.d.ts

@@ -0,0 +1,240 @@
+import type { WorkflowNode, WorkflowEvent, WorkflowObserver, LogEntry } from '../types/index.js';
+import { Observable } from '../utils/observable.js';
+import type { Workflow } from '../core/workflow.js';
+/**
+ * Tree debugger for real-time workflow visualization
+ * Implements WorkflowObserver to receive all events
+ */
+export declare class WorkflowTreeDebugger implements WorkflowObserver {
+    /** Root node of the workflow tree */
+    private root;
+    /** Observable stream of workflow events */
+    readonly events: Observable<WorkflowEvent>;
+    /** Node lookup map for quick access */
+    private nodeMap;
+    /** Event history for persistence (only when persistEvents is true) */
+    private eventHistory;
+    /** Whether to persist events to memory */
+    private persistEvents;
+    /** Maximum event history size (optional, for memory management) */
+    private maxEventHistorySize?;
+    /**
+     * Create a tree debugger attached to a workflow
+     * @param workflow The root workflow to debug
+     * @param options Configuration options
+     * @param options.persistEvents Whether to accumulate event history (default: false)
+     * @param options.maxEventHistorySize Maximum number of events to keep (optional, FIFO eviction)
+     *
+     * @example
+     * ```typescript
+     * // Without persistence (default)
+     * const debugger = new WorkflowTreeDebugger(workflow);
+     *
+     * // With persistence enabled
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     *
+     * // With persistence and size limit
+     * const debugger = new WorkflowTreeDebugger(workflow, {
+     *   persistEvents: true,
+     *   maxEventHistorySize: 10000,
+     * });
+     * ```
+     */
+    constructor(workflow: Workflow, options?: {
+        persistEvents?: boolean;
+        maxEventHistorySize?: number;
+    });
+    /**
+     * Build node lookup map recursively
+     */
+    private buildNodeMap;
+    /**
+     * 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;
+    onLog(_entry: LogEntry): void;
+    /**
+     * Handle workflow events from observer interface
+     * Captures events for history if persistence enabled, handles structural updates, forwards to stream
+     *
+     * @param event - The workflow event to handle
+     */
+    onEvent(event: WorkflowEvent): void;
+    onStateUpdated(_node: WorkflowNode): void;
+    onTreeChanged(root: WorkflowNode): void;
+    /**
+     * Get the current tree root
+     */
+    getTree(): WorkflowNode;
+    /**
+     * Get a node by ID
+     */
+    getNode(id: string): WorkflowNode | undefined;
+    /**
+     * Render tree as ASCII string
+     * @param node Starting node (defaults to root)
+     */
+    toTreeString(node?: WorkflowNode): string;
+    /**
+     * Recursive tree rendering
+     */
+    private renderTree;
+    /**
+     * Render logs as formatted string
+     * @param node Starting node (defaults to root, includes descendants)
+     */
+    toLogString(node?: WorkflowNode): string;
+    /**
+     * Collect all logs from a node and its descendants
+     */
+    private collectLogs;
+    /**
+     * Get summary statistics for the tree
+     */
+    getStats(): {
+        totalNodes: number;
+        byStatus: Record<string, number>;
+        totalLogs: number;
+        totalEvents: number;
+    };
+    private collectStats;
+    /**
+     * Get the accumulated event history
+     * Returns a copy to prevent external modification
+     *
+     * @returns Copy of event history array, or empty array if persistence disabled
+     *
+     * @example
+     * ```typescript
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * const events = debugger.getEventHistory();
+     * console.log(`Captured ${events.length} events`);
+     * ```
+     */
+    getEventHistory(): WorkflowEvent[];
+    /**
+     * Serialize a WorkflowEvent to JSON-safe format
+     * Extracts only primitive fields to avoid circular references in WorkflowNode objects
+     *
+     * **Strategy:**
+     * - Extract nodeId and nodeName from WorkflowNode references
+     * - Skip WorkflowNode.parent, WorkflowNode.children (circular refs)
+     * - Skip WorkflowError.original (could be circular)
+     * - Add timestamp for chronological ordering
+     *
+     * **Circular Reference Handling:**
+     * - WorkflowNode has bidirectional links (parent ↔ children)
+     * - WorkflowNode.events[] contains WorkflowEvents that reference WorkflowNodes
+     * - JSON.stringify would throw TypeError without selective extraction
+     *
+     * @param event - The workflow event to serialize
+     * @returns JSON-safe object with primitive fields only
+     *
+     * @example
+     * ```typescript
+     * const event: WorkflowEvent = {
+     *   type: 'stateSnapshot',
+     *   node: { id: 'wf-123', name: 'MyWorkflow', ... }
+     * };
+     * const serialized = serializeEvent(event);
+     * // { type: 'stateSnapshot', timestamp: 1234567890, nodeId: 'wf-123', nodeName: 'MyWorkflow', stateSnapshot: {...} }
+     * ```
+     */
+    private serializeEvent;
+    /**
+     * Save event history to a JSON file
+     * Serializes events to avoid circular references and writes to disk
+     *
+     * **Serialization Strategy:**
+     * - Uses serializeEvent() to extract primitive fields only
+     * - Avoids circular references in WorkflowNode objects
+     * - Adds timestamp for chronological ordering
+     *
+     * **Error Handling:**
+     * - Throws descriptive errors for file system issues
+     * - Does not modify internal event history on failure
+     *
+     * @param path - File path to write event history
+     * @throws {Error} If file cannot be written (permission denied, disk full, etc.)
+     * @throws {Error} If event persistence is not enabled
+     *
+     * @example
+     * ```typescript
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * await debugger.saveEventHistory('./workflow-execution.json');
+     * ```
+     */
+    saveEventHistory(path: string): Promise<void>;
+    /**
+     * Load event history from a JSON file
+     * Static method that can be called without instantiating WorkflowTreeDebugger
+     *
+     * **Error Handling:**
+     * - Throws descriptive errors for file system issues
+     * - Throws descriptive errors for invalid JSON
+     *
+     * @param path - File path to read event history from
+     * @returns Parsed event array (unknown[] - caller should validate structure)
+     * @throws {Error} If file does not exist
+     * @throws {Error} If file cannot be read (permission denied, etc.)
+     * @throws {Error} If file contains invalid JSON
+     *
+     * @example
+     * ```typescript
+     * const events = await WorkflowTreeDebugger.loadEventHistory('./workflow-execution.json');
+     *
+     * // Use with WorkflowEventReplayer
+     * const replayer = new WorkflowEventReplayer();
+     * const tree = replayer.replay(events as WorkflowEvent[]);
+     * ```
+     */
+    static loadEventHistory(path: string): Promise<unknown[]>;
+    /**
+     * Replay workflow execution from saved event history file.
+     *
+     * This is a convenience method that combines loadEventHistory and
+     * WorkflowEventReplayer.replay() for one-call restoration of workflow trees.
+     *
+     * **Use Case**: Time-travel debugging - reconstruct workflow tree from saved events
+     * to inspect execution after completion without requiring the live workflow instance.
+     *
+     * **Workflow**:
+     * 1. Load events from file using loadEventHistory()
+     * 2. Create WorkflowEventReplayer instance
+     * 3. Replay events and return reconstructed tree
+     *
+     * **Error Handling**:
+     * - Throws descriptive errors for file operations (delegated to loadEventHistory)
+     * - Wraps replay errors with file path context
+     *
+     * **Returns**: Read-only WorkflowNode tree (no live workflow attached)
+     *
+     * @param path - File path to saved event history JSON file
+     * @returns Reconstructed workflow tree root node
+     * @throws {Error} If file cannot be read or parsed
+     * @throws {Error} If events cannot be replayed (empty events, no root established)
+     *
+     * @example
+     * ```typescript
+     * // Save event history during execution
+     * const debugger = new WorkflowTreeDebugger(workflow, { persistEvents: true });
+     * await workflow.run();
+     * await debugger.saveEventHistory('./workflow-events.json');
+     *
+     * // Later, replay the events to reconstruct the tree
+     * const tree = await WorkflowTreeDebugger.replay('./workflow-events.json');
+     * console.log(`Restored tree with ${tree.children.length} children`);
+     *
+     * // Use debugger instance to inspect the reconstructed tree
+     * const debugInstance = new WorkflowTreeDebugger({ getNode: () => tree });
+     * console.log(debugInstance.toTreeString(tree));
+     * console.log(debugInstance.getStats());
+     * ```
+     */
+    static replay(path: string): Promise<WorkflowNode>;
+}
+//# sourceMappingURL=tree-debugger.d.ts.map

package/dist/debugger/tree-debugger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-debugger.d.ts","sourceRoot":"","sources":["../../src/debugger/tree-debugger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,QAAQ,EACT,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAepD;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,qCAAqC;IACrC,OAAO,CAAC,IAAI,CAAe;IAE3B,2CAA2C;IAC3C,SAAgB,MAAM,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;IAElD,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAAwC;IAEvD,sEAAsE;IACtE,OAAO,CAAC,YAAY,CAAuB;IAE3C,0CAA0C;IAC1C,OAAO,CAAC,aAAa,CAAkB;IAEvC,mEAAmE;IACnE,OAAO,CAAC,mBAAmB,CAAC,CAAS;IAErC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBAED,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE;IAqBrE;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAI7B;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAuCnC,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAIzC,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAUvC;;OAEG;IACH,OAAO,IAAI,YAAY;IAIvB;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI7C;;;OAGG;IACH,YAAY,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM;IAIzC;;OAEG;IACH,OAAO,CAAC,UAAU;IA8BlB;;;OAGG;IACH,WAAW,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM;IAiBxC;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB;IAYD,OAAO,CAAC,YAAY;IAkBpB;;;;;;;;;;;;;OAaG;IACH,eAAe,IAAI,aAAa,EAAE;IAQlC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,cAAc;IAiLtB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACU,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IA2C/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;WACU,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAkBzD"}