groundswell 0.0.2 → 0.0.3

package/dist/core/workflow.js

@@ -0,0 +1,464 @@
+import { generateId } from '../utils/id.js';
+import { WorkflowLogger } from './logger.js';
+import { getObservedState } from '../decorators/observed-state.js';
+import { createWorkflowContext } from './workflow-context.js';
+/**
+ * Base class for all workflows
+ * Supports both class-based (subclass with run()) and functional (executor) patterns
+ *
+ * @example Class-based pattern:
+ * ```ts
+ * class MyWorkflow extends Workflow {
+ *   async run() {
+ *     this.setStatus('running');
+ *     // workflow logic
+ *     this.setStatus('completed');
+ *   }
+ * }
+ * ```
+ *
+ * @example Functional pattern:
+ * ```ts
+ * const workflow = new Workflow({ name: 'MyWorkflow' }, async (ctx) => {
+ *   await ctx.step('step1', async () => {
+ *     // step logic
+ *   });
+ * });
+ * await workflow.run();
+ * ```
+ */
+export class Workflow {
+    /** Unique identifier for this workflow instance */
+    id;
+    /** Parent workflow (null for root workflows) */
+    parent = null;
+    /** Child workflows */
+    children = [];
+    /** Current execution status */
+    status = 'idle';
+    /** Logger instance for this workflow */
+    logger;
+    /** The node representation of this workflow */
+    node;
+    /** Observers (only populated on root workflow) */
+    observers = [];
+    /** Optional executor function for functional workflows */
+    executor;
+    /** Workflow configuration */
+    config;
+    /**
+     * Create a new workflow instance
+     *
+     * @overload Class-based pattern
+     * @param name Human-readable name (defaults to class name)
+     * @param parent Optional parent workflow
+     *
+     * @overload Functional pattern
+     * @param config Workflow configuration
+     * @param executor Executor function
+     */
+    constructor(name, parentOrExecutor) {
+        this.id = generateId();
+        // Parse overloaded arguments
+        if (typeof name === 'object' && name !== null) {
+            // Functional pattern: constructor(config, executor)
+            this.config = name;
+            this.executor = parentOrExecutor;
+            this.parent = null;
+        }
+        else {
+            // Class-based pattern: constructor(name, parent)
+            this.config = { name: name ?? this.constructor.name };
+            this.parent = parentOrExecutor ?? null;
+        }
+        // Validate workflow name (after config is normalized)
+        if (typeof this.config.name === 'string') {
+            const trimmedName = this.config.name.trim();
+            if (trimmedName.length === 0) {
+                throw new Error('Workflow name cannot be empty or whitespace only');
+            }
+            if (this.config.name.length > 100) {
+                throw new Error('Workflow name cannot exceed 100 characters');
+            }
+        }
+        // Create the node representation
+        this.node = {
+            id: this.id,
+            name: this.config.name ?? this.constructor.name,
+            parent: this.parent?.node ?? null,
+            children: [],
+            status: 'idle',
+            logs: [],
+            events: [],
+            stateSnapshot: null,
+        };
+        // Create logger with root observers
+        this.logger = new WorkflowLogger(this.node, this.getRootObservers());
+        // Attach to parent if provided
+        if (this.parent) {
+            this.parent.attachChild(this);
+        }
+    }
+    /**
+     * Get observers from the root workflow
+     * Traverses up the tree to find the root
+     * Uses cycle detection to prevent infinite loops from circular parent-child relationships
+     */
+    getRootObservers() {
+        const visited = new Set();
+        let root = this;
+        let current = this;
+        while (current) {
+            if (visited.has(current)) {
+                throw new Error('Circular parent-child relationship detected');
+            }
+            visited.add(current);
+            root = current;
+            current = current.parent;
+        }
+        return root.observers;
+    }
+    /**
+     * Check if this workflow is a descendant of the given ancestor workflow.
+     *
+     * Traverses the parent chain upward looking for the ancestor reference.
+     * Uses a visited Set to detect cycles during traversal. This method provides
+     * a convenient way to check workflow hierarchy relationships without manually
+     * traversing the parent chain.
+     *
+     * @warning This method reveals workflow hierarchy information. If your
+     * application exposes workflows via an API, ensure you implement proper
+     * access control to prevent unauthorized topology discovery. Note that
+     * the `parent` and `children` properties are already public, so this
+     * method does not expose any new information beyond what is currently
+     * accessible.
+     *
+     * **Time Complexity**: O(d) where d is the depth of the hierarchy
+     * **Space Complexity**: O(d) for the visited Set in worst case (cycle detection)
+     *
+     * @example Check if a workflow belongs to a specific hierarchy
+     * ```typescript
+     * const root = new Workflow('root');
+     * const child = new Workflow('child', { parent: root });
+     *
+     * if (child.isDescendantOf(root)) {
+     *   console.log('Child is in root hierarchy');
+     * }
+     * ```
+     *
+     * @example Validate before attaching to prevent circular references
+     * ```typescript
+     * if (!newChild.isDescendantOf(parent)) {
+     *   parent.attachChild(newChild);
+     * } else {
+     *   throw new Error('Would create circular reference');
+     * }
+     * ```
+     *
+     * @example Check for ancestor relationship in conditional logic
+     * ```typescript
+     * const isInProductionBranch = workflow.isDescendantOf(productionRoot);
+     * if (isInProductionBranch) {
+     *   // Apply production-specific logic
+     * }
+     * ```
+     *
+     * @param ancestor - The potential ancestor workflow to check
+     * @returns true if ancestor is found in parent chain, false otherwise
+     * @throws {Error} If a cycle is detected during traversal (indicates corrupted tree structure)
+     */
+    isDescendantOf(ancestor) {
+        const visited = new Set();
+        let current = this.parent;
+        while (current !== null) {
+            if (visited.has(current)) {
+                throw new Error('Circular parent-child relationship detected');
+            }
+            visited.add(current);
+            if (current === ancestor) {
+                return true;
+            }
+            current = current.parent;
+        }
+        return false;
+    }
+    /**
+     * Get the root workflow
+     * Uses cycle detection to prevent infinite loops from circular parent-child relationships
+     */
+    getRoot() {
+        const visited = new Set();
+        let root = this;
+        let current = this;
+        while (current) {
+            if (visited.has(current)) {
+                throw new Error('Circular parent-child relationship detected');
+            }
+            visited.add(current);
+            root = current;
+            current = current.parent;
+        }
+        return root;
+    }
+    /**
+     * Add an observer to this workflow (must be root)
+     * @throws Error if called on non-root workflow
+     */
+    addObserver(observer) {
+        if (this.parent) {
+            throw new Error('Observers can only be added to root workflows');
+        }
+        this.observers.push(observer);
+    }
+    /**
+     * Remove an observer from this workflow
+     */
+    removeObserver(observer) {
+        const index = this.observers.indexOf(observer);
+        if (index !== -1) {
+            this.observers.splice(index, 1);
+        }
+    }
+    /**
+     * Attach a child workflow to this parent workflow.
+     *
+     * Validates that the child can be attached by checking:
+     * 1. Child is not already attached to this parent workflow
+     * 2. Child does not have a different parent (enforces single-parent invariant)
+     * 3. Child is not an ancestor of this parent (prevents circular references)
+     *
+     * **Structural Changes:**
+     * - Adds child to this.children array (workflow tree)
+     * - Adds child.node to this.node.children array (node tree)
+     * - Sets child.parent = this (workflow tree)
+     * - Sets child.node.parent = this.node (node tree)
+     * - Emits childAttached event to notify observers
+     *
+     * **Invariants Maintained:**
+     * - Single-parent rule: A workflow can only have one parent
+     * - 1:1 tree mirror: workflow tree and node tree stay synchronized
+     * - No cycles: A workflow cannot be its own ancestor
+     *
+     * **Cycle Detection:**
+     * - Uses isDescendantOf() helper with Set-based cycle detection
+     * - Throws immediately if circular reference would be created
+     *
+     * @param child - The child workflow to attach
+     * @throws {Error} If the child is already attached to this workflow
+     * @throws {Error} If the child already has a different parent (use detachChild() first for reparenting)
+     * @throws {Error} If the child is an ancestor of this parent (would create circular reference)
+     *
+     * @example
+     * ```ts
+     * const parent = new Workflow('Parent');
+     * const child = new Workflow('Child');
+     * parent.attachChild(child);
+     * // child.parent === parent
+     * // parent.children.includes(child) === true
+     * ```
+     *
+     * @example Reparenting workflow
+     * ```ts
+     * const parent1 = new Workflow('Parent1');
+     * const parent2 = new Workflow('Parent2');
+     * const child = new Workflow('Child', parent1); // Attached to parent1
+     *
+     * // Later, move child to parent2
+     * parent1.detachChild(child);
+     * parent2.attachChild(child);
+     * // child.parent === parent2
+     * ```
+     *
+     * @see detachChild - For detaching children (enables reparenting)
+     * @see isDescendantOf - Private helper for circular reference detection
+     */
+    attachChild(child) {
+        if (this.children.includes(child)) {
+            throw new Error('Child already attached to this workflow');
+        }
+        // Check if child already has a different parent
+        if (child.parent !== null && child.parent !== this) {
+            const errorMessage = `Child '${child.node.name}' already has a parent '${child.parent.node.name}'. ` +
+                `A workflow can only have one parent. ` +
+                `Use detachChild() on '${child.parent.node.name}' first if you need to reparent.`;
+            console.error(errorMessage);
+            throw new Error(errorMessage);
+        }
+        // Check if child is an ancestor (would create circular reference)
+        if (this.isDescendantOf(child)) {
+            const errorMessage = `Cannot attach child '${child.node.name}' - it is an ancestor of '${this.node.name}'. ` +
+                `This would create a circular reference.`;
+            console.error(errorMessage);
+            throw new Error(errorMessage);
+        }
+        // Update child's parent if it's currently null
+        if (child.parent === null) {
+            child.parent = this;
+            child.node.parent = this.node; // Maintain 1:1 mirror between workflow tree and node tree
+        }
+        this.children.push(child);
+        this.node.children.push(child.node);
+        // Emit child attached event
+        this.emitEvent({
+            type: 'childAttached',
+            parentId: this.id,
+            child: child.node,
+        });
+    }
+    /**
+     * Detach a child workflow from this parent workflow.
+     *
+     * Removes the child from both the workflow tree (this.children) and
+     * the node tree (this.node.children), clears the child's parent reference,
+     * and emits a childDetached event to notify observers.
+     *
+     * This enables reparenting workflows: oldParent.detachChild(child); newParent.attachChild(child);
+     *
+     * @param child - The child workflow to detach
+     * @throws {Error} If the child is not attached to this parent workflow
+     *
+     * @example
+     * ```ts
+     * const parent = new Workflow('Parent');
+     * const child = new Workflow('Child', parent);
+     *
+     * // Later, reparent to a different parent
+     * parent.detachChild(child);
+     * newParent.attachChild(child);
+     * ```
+     */
+    detachChild(child) {
+        // Validate child is actually attached
+        const index = this.children.indexOf(child);
+        if (index === -1) {
+            throw new Error(`Child '${child.node.name}' is not attached to workflow '${this.node.name}'`);
+        }
+        // Remove from workflow tree (this.children array)
+        this.children.splice(index, 1);
+        // Remove from node tree (this.node.children array)
+        const nodeIndex = this.node.children.indexOf(child.node);
+        if (nodeIndex !== -1) {
+            this.node.children.splice(nodeIndex, 1);
+        }
+        // Clear child's parent reference (both workflow tree and node tree)
+        child.parent = null;
+        child.node.parent = null; // Maintain 1:1 mirror between workflow tree and node tree
+        // Emit childDetached event
+        this.emitEvent({
+            type: 'childDetached',
+            parentId: this.id,
+            childId: child.id,
+        });
+    }
+    /**
+     * Emit an event to all root observers
+     */
+    emitEvent(event) {
+        this.node.events.push(event);
+        const observers = this.getRootObservers();
+        for (const obs of observers) {
+            try {
+                obs.onEvent(event);
+                // Also notify tree changed for tree update events
+                if (event.type === 'treeUpdated' || event.type === 'childAttached' || event.type === 'childDetached') {
+                    obs.onTreeChanged(this.getRoot().node);
+                }
+            }
+            catch (err) {
+                this.logger.error('Observer onEvent error', { error: err, eventType: event.type });
+            }
+        }
+    }
+    /**
+     * Capture and emit a state snapshot
+     */
+    snapshotState() {
+        const snapshot = getObservedState(this);
+        this.node.stateSnapshot = snapshot;
+        // Notify observers
+        const observers = this.getRootObservers();
+        for (const obs of observers) {
+            try {
+                obs.onStateUpdated(this.node);
+            }
+            catch (err) {
+                this.logger.error('Observer onStateUpdated error', { error: err, nodeId: this.node.id });
+            }
+        }
+        // Emit snapshot event
+        this.emitEvent({
+            type: 'stateSnapshot',
+            node: this.node,
+        });
+        // Emit treeUpdated event to trigger tree debugger rebuild
+        this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
+    }
+    /**
+     * Update workflow status and sync with node
+     */
+    setStatus(status) {
+        this.status = status;
+        this.node.status = status;
+        this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
+    }
+    /**
+     * Get the node representation of this workflow
+     */
+    getNode() {
+        return this.node;
+    }
+    /**
+     * Run the workflow
+     *
+     * For functional workflows (created with executor), runs the executor function.
+     * For class-based workflows (subclasses), this should be overridden.
+     *
+     * @returns Workflow result
+     */
+    async run(..._args) {
+        if (this.executor) {
+            return this.runFunctional();
+        }
+        // Class-based workflows must override this method
+        throw new Error('Workflow.run() must be overridden in subclass or provide executor in constructor');
+    }
+    /**
+     * Run a functional workflow with context
+     */
+    async runFunctional() {
+        if (!this.executor) {
+            throw new Error('No executor provided');
+        }
+        const startTime = Date.now();
+        this.setStatus('running');
+        // Create workflow context
+        const ctx = createWorkflowContext(this, this.parent?.id, this.config.enableReflection ? { enabled: true } : undefined);
+        try {
+            const result = await this.executor(ctx);
+            this.setStatus('completed');
+            return {
+                data: result,
+                node: this.node,
+                duration: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            this.setStatus('failed');
+            // Emit error event
+            this.emitEvent({
+                type: 'error',
+                node: this.node,
+                error: {
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                    original: error,
+                    workflowId: this.id,
+                    stack: error instanceof Error ? error.stack : undefined,
+                    state: getObservedState(this),
+                    logs: [...this.node.logs],
+                },
+            });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=workflow.js.map

package/dist/core/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/core/workflow.ts"],"names":[],"mappings":"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"}

package/dist/debugger/index.d.ts

@@ -0,0 +1,2 @@
+export { WorkflowTreeDebugger } from './tree-debugger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/debugger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/debugger/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/{src/debugger/index.ts → dist/debugger/index.js}

@@ -1 +1,2 @@
 export { WorkflowTreeDebugger } from './tree-debugger.js';
+//# sourceMappingURL=index.js.map

package/dist/debugger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/debugger/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,71 @@
+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;
+    /**
+     * Create a tree debugger attached to a workflow
+     * @param workflow The root workflow to debug
+     */
+    constructor(workflow: Workflow);
+    /**
+     * 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;
+    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;
+}
+//# 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;AAapD;;;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;;;OAGG;gBACS,QAAQ,EAAE,QAAQ;IAW9B;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAuB1B,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAI7B,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IA2BnC,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;CAarB"}