groundswell 0.0.1

package/src/core/workflow.ts

@@ -0,0 +1,302 @@
+import type {
+  WorkflowNode,
+  WorkflowStatus,
+  WorkflowEvent,
+  WorkflowObserver,
+} from '../types/index.js';
+import type { WorkflowContext, WorkflowConfig, WorkflowResult } from '../types/workflow-context.js';
+import { generateId } from '../utils/id.js';
+import { WorkflowLogger } from './logger.js';
+import { getObservedState } from '../decorators/observed-state.js';
+import { createWorkflowContext } from './workflow-context.js';
+
+/**
+ * Executor function type for functional workflows
+ */
+export type WorkflowExecutor<T = unknown> = (ctx: WorkflowContext) => Promise<T>;
+
+/**
+ * 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<T = unknown> {
+  /** Unique identifier for this workflow instance */
+  public readonly id: string;
+
+  /** Parent workflow (null for root workflows) */
+  public parent: Workflow | null = null;
+
+  /** Child workflows */
+  public children: Workflow[] = [];
+
+  /** Current execution status */
+  public status: WorkflowStatus = 'idle';
+
+  /** Logger instance for this workflow */
+  protected readonly logger: WorkflowLogger;
+
+  /** The node representation of this workflow */
+  protected readonly node: WorkflowNode;
+
+  /** Observers (only populated on root workflow) */
+  private observers: WorkflowObserver[] = [];
+
+  /** Optional executor function for functional workflows */
+  private executor?: WorkflowExecutor<T>;
+
+  /** Workflow configuration */
+  private config: WorkflowConfig;
+
+  /**
+   * 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?: string | WorkflowConfig, parentOrExecutor?: Workflow | WorkflowExecutor<T>) {
+    this.id = generateId();
+
+    // Parse overloaded arguments
+    if (typeof name === 'object' && name !== null) {
+      // Functional pattern: constructor(config, executor)
+      this.config = name;
+      this.executor = parentOrExecutor as WorkflowExecutor<T>;
+      this.parent = null;
+    } else {
+      // Class-based pattern: constructor(name, parent)
+      this.config = { name: name ?? this.constructor.name };
+      this.parent = (parentOrExecutor as Workflow) ?? null;
+    }
+
+    // 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
+   */
+  private getRootObservers(): WorkflowObserver[] {
+    if (this.parent) {
+      return this.parent.getRootObservers();
+    }
+    return this.observers;
+  }
+
+  /**
+   * Get the root workflow
+   */
+  protected getRoot(): Workflow {
+    if (this.parent) {
+      return this.parent.getRoot();
+    }
+    return this;
+  }
+
+  /**
+   * Add an observer to this workflow (must be root)
+   * @throws Error if called on non-root workflow
+   */
+  public addObserver(observer: WorkflowObserver): void {
+    if (this.parent) {
+      throw new Error('Observers can only be added to root workflows');
+    }
+    this.observers.push(observer);
+  }
+
+  /**
+   * Remove an observer from this workflow
+   */
+  public removeObserver(observer: WorkflowObserver): void {
+    const index = this.observers.indexOf(observer);
+    if (index !== -1) {
+      this.observers.splice(index, 1);
+    }
+  }
+
+  /**
+   * Attach a child workflow
+   * Called automatically in constructor when parent is provided
+   */
+  public attachChild(child: Workflow): void {
+    this.children.push(child);
+    this.node.children.push(child.node);
+
+    // Emit child attached event
+    this.emitEvent({
+      type: 'childAttached',
+      parentId: this.id,
+      child: child.node,
+    });
+  }
+
+  /**
+   * Emit an event to all root observers
+   */
+  public emitEvent(event: WorkflowEvent): void {
+    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') {
+          obs.onTreeChanged(this.getRoot().node);
+        }
+      } catch (err) {
+        console.error('Observer onEvent error:', err);
+      }
+    }
+  }
+
+  /**
+   * Capture and emit a state snapshot
+   */
+  public snapshotState(): void {
+    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) {
+        console.error('Observer onStateUpdated error:', err);
+      }
+    }
+
+    // Emit snapshot event
+    this.emitEvent({
+      type: 'stateSnapshot',
+      node: this.node,
+    });
+  }
+
+  /**
+   * Update workflow status and sync with node
+   */
+  public setStatus(status: WorkflowStatus): void {
+    this.status = status;
+    this.node.status = status;
+  }
+
+  /**
+   * Get the node representation of this workflow
+   */
+  public getNode(): WorkflowNode {
+    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
+   */
+  public async run(..._args: unknown[]): Promise<T | WorkflowResult<T>> {
+    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
+   */
+  private async runFunctional(): Promise<WorkflowResult<T>> {
+    if (!this.executor) {
+      throw new Error('No executor provided');
+    }
+
+    const startTime = Date.now();
+    this.setStatus('running');
+
+    // Create workflow context
+    const ctx = createWorkflowContext(
+      this as unknown as Parameters<typeof createWorkflowContext>[0],
+      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: {},
+          logs: [],
+        },
+      });
+
+      throw error;
+    }
+  }
+}

package/src/debugger/index.ts

@@ -0,0 +1 @@
+export { WorkflowTreeDebugger } from './tree-debugger.js';

package/src/debugger/tree-debugger.ts

@@ -0,0 +1,210 @@
+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);
+    }
+  }
+
+  // WorkflowObserver implementation
+
+  onLog(_entry: LogEntry): void {
+    // Events are forwarded through the event stream
+  }
+
+  onEvent(event: WorkflowEvent): void {
+    // Rebuild node map on structural changes
+    if (event.type === 'childAttached') {
+      this.buildNodeMap(event.child);
+    }
+
+    // Forward to event stream
+    this.events.next(event);
+  }
+
+  onStateUpdated(_node: WorkflowNode): void {
+    // State updates are available through the node
+  }
+
+  onTreeChanged(root: WorkflowNode): void {
+    this.root = root;
+    this.nodeMap.clear();
+    this.buildNodeMap(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/index.ts

@@ -0,0 +1,3 @@
+export { ObservedState, getObservedState, isFieldObserved, getFieldMetadata } from './observed-state.js';
+export { Step } from './step.js';
+export { Task } from './task.js';

package/src/decorators/observed-state.ts

@@ -0,0 +1,95 @@
+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);
+}