@hyperdrive.bot/bmad-workflow 1.0.16 → 1.0.18

package/dist/models/workflow-callbacks.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Workflow Callbacks
+ *
+ * Interfaces for lifecycle event callbacks that consumers can register
+ * to observe workflow execution without coupling to orchestration internals.
+ *
+ * Callbacks are fire-and-forget (synchronous but non-blocking) and errors
+ * in callbacks do not interrupt workflow execution.
+ */
+/**
+ * Context for phase lifecycle events
+ *
+ * Provided when a workflow phase (epic, story, dev, qa) starts or completes.
+ */
+export interface PhaseContext {
+    /**
+     * Phase name: 'epic' | 'story' | 'dev' | 'qa'
+     */
+    phaseName: string;
+    /**
+     * Phase start timestamp (epoch ms)
+     */
+    startTime: number;
+    /**
+     * Phase end timestamp (epoch ms, only in onPhaseComplete)
+     */
+    endTime?: number;
+    /**
+     * Phase duration in milliseconds (only in onPhaseComplete)
+     */
+    duration?: number;
+    /**
+     * Total items to process in this phase
+     */
+    itemCount: number;
+    /**
+     * Number of successfully processed items (only in onPhaseComplete)
+     */
+    successCount?: number;
+    /**
+     * Number of failed items (only in onPhaseComplete)
+     */
+    failureCount?: number;
+    /**
+     * Whether the phase was skipped
+     */
+    skipped?: boolean;
+    /**
+     * Additional metadata specific to the phase
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Context for layer/batch lifecycle events
+ *
+ * Provided when a batch of items starts or completes processing.
+ * Layers represent groups of items processed in parallel.
+ */
+export interface LayerContext {
+    /**
+     * Phase this layer belongs to
+     */
+    phaseName: string;
+    /**
+     * Zero-based layer index within the phase
+     */
+    layerIndex: number;
+    /**
+     * Total number of layers in the phase
+     */
+    totalLayers: number;
+    /**
+     * Number of items (spawns) in this layer
+     */
+    spawnCount: number;
+    /**
+     * Whether items in this layer are processed in parallel
+     */
+    parallel: boolean;
+    /**
+     * Layer start timestamp (epoch ms)
+     */
+    startTime: number;
+    /**
+     * Layer end timestamp (epoch ms, only in onLayerComplete)
+     */
+    endTime?: number;
+    /**
+     * Layer duration in milliseconds (only in onLayerComplete)
+     */
+    duration?: number;
+    /**
+     * Number of successful spawns (only in onLayerComplete)
+     */
+    successCount?: number;
+    /**
+     * Number of failed spawns (only in onLayerComplete)
+     */
+    failureCount?: number;
+}
+/**
+ * Context for spawn (agent execution) lifecycle events
+ *
+ * Provided when an individual agent execution starts, completes, or produces output.
+ */
+export interface SpawnContext {
+    /**
+     * Unique identifier for this spawn
+     */
+    spawnId: string;
+    /**
+     * Phase this spawn belongs to
+     */
+    phaseName: string;
+    /**
+     * Type of agent being spawned: 'architect' | 'sm' | 'dev' | 'qa'
+     */
+    agentType: string;
+    /**
+     * Item identifier (epic number, story number, etc.)
+     */
+    itemId: string;
+    /**
+     * Item title or description
+     */
+    itemTitle?: string;
+    /**
+     * Output file path (if applicable)
+     */
+    outputPath?: string;
+    /**
+     * The prompt sent to the agent
+     */
+    prompt?: string;
+    /**
+     * Spawn start timestamp (epoch ms)
+     */
+    startTime: number;
+    /**
+     * Spawn end timestamp (epoch ms, only in onSpawnComplete)
+     */
+    endTime?: number;
+    /**
+     * Spawn duration in milliseconds (only in onSpawnComplete)
+     */
+    duration?: number;
+    /**
+     * Whether the spawn succeeded (only in onSpawnComplete)
+     */
+    success?: boolean;
+    /**
+     * Agent output text (only in onSpawnComplete or onSpawnOutput)
+     */
+    output?: string;
+    /**
+     * Error message if spawn failed (only in onSpawnComplete)
+     */
+    error?: string;
+    /**
+     * Worker ID for pipelined execution
+     */
+    workerId?: number;
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Context for error events
+ *
+ * Provided when an error occurs during workflow execution.
+ */
+export interface ErrorContext {
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Phase where the error occurred (if applicable)
+     */
+    phaseName?: string;
+    /**
+     * Spawn ID where the error occurred (if applicable)
+     */
+    spawnId?: string;
+    /**
+     * Item identifier related to the error (if applicable)
+     */
+    itemId?: string;
+    /**
+     * Error stack trace (if available)
+     */
+    stack?: string;
+    /**
+     * Original error object
+     */
+    error?: Error;
+    /**
+     * Timestamp when error occurred (epoch ms)
+     */
+    timestamp: number;
+    /**
+     * Whether the error is recoverable (workflow can continue)
+     */
+    recoverable: boolean;
+    /**
+     * Additional context about the error
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Workflow lifecycle callbacks
+ *
+ * Optional callback functions that consumers can register to observe
+ * workflow execution events. All callbacks are wrapped in try-catch
+ * to prevent errors from interrupting workflow execution.
+ */
+export interface WorkflowCallbacks {
+    /**
+     * Called when a phase starts execution
+     */
+    onPhaseStart?: (context: PhaseContext) => void;
+    /**
+     * Called when a phase completes execution
+     */
+    onPhaseComplete?: (context: PhaseContext) => void;
+    /**
+     * Called when a batch/layer starts processing
+     */
+    onLayerStart?: (context: LayerContext) => void;
+    /**
+     * Called when a batch/layer completes processing
+     */
+    onLayerComplete?: (context: LayerContext) => void;
+    /**
+     * Called when an agent spawn starts
+     */
+    onSpawnStart?: (context: SpawnContext) => void;
+    /**
+     * Called when an agent spawn completes
+     */
+    onSpawnComplete?: (context: SpawnContext) => void;
+    /**
+     * Called when an agent produces streaming output
+     */
+    onSpawnOutput?: (context: SpawnContext, output: string) => void;
+    /**
+     * Called when an error occurs
+     */
+    onError?: (context: ErrorContext) => void;
+}

package/dist/models/workflow-callbacks.js

@@ -0,0 +1,10 @@
+/**
+ * Workflow Callbacks
+ *
+ * Interfaces for lifecycle event callbacks that consumers can register
+ * to observe workflow execution without coupling to orchestration internals.
+ *
+ * Callbacks are fire-and-forget (synchronous but non-blocking) and errors
+ * in callbacks do not interrupt workflow execution.
+ */
+export {};

package/dist/services/WorkflowReporter.d.ts

@@ -0,0 +1,165 @@
+/**
+ * WorkflowReporter
+ *
+ * Real-time progress visualization for multi-layer parallel workflow execution
+ * using listr2. Implements the WorkflowCallbacks interface to observe workflow
+ * lifecycle events without coupling to orchestration internals.
+ *
+ * Features:
+ * - Top-level phase task groups with emoji-annotated titles
+ * - Nested concurrent task groups for parallel spawn layers
+ * - Live status updates for spawn transitions (queued → running → completed/failed)
+ * - Collapsible layer summaries on completion
+ */
+import type { WorkflowCallbacks } from '../models/workflow-callbacks.js';
+/**
+ * Configuration options for WorkflowReporter
+ */
+export interface WorkflowReporterOptions {
+    /**
+     * Maximum terminal width for output formatting (default: 80)
+     */
+    maxWidth?: number;
+    /**
+     * Disable color output
+     */
+    noColor?: boolean;
+    /**
+     * Force non-TTY mode (use simple renderer)
+     * When true or when process.stdout.isTTY is false, disables spinners
+     * and uses plain-text output without ANSI escape codes
+     */
+    nonTTY?: boolean;
+    /**
+     * Enable verbose output mode (show spawn output inline in real-time)
+     * When enabled, spawn outputs are streamed with visual delimiters
+     */
+    verbose?: boolean;
+}
+/**
+ * Summary data for the final dashboard display
+ */
+export interface DashboardSummary {
+    /** Number of failed spawns */
+    failedCount: number;
+    /** Number of successful spawns */
+    passedCount: number;
+    /** Per-phase breakdown */
+    phases: Array<{
+        duration: number;
+        failed: number;
+        name: string;
+        passed: number;
+    }>;
+    /** Absolute path to the session report file */
+    sessionReportPath?: string;
+    /** Total duration in milliseconds */
+    totalDuration: number;
+    /** Total number of spawns across all phases */
+    totalSpawns: number;
+}
+/**
+ * WorkflowReporter provides real-time structured progress visualization
+ * of multi-layer parallel execution using listr2.
+ *
+ * Usage:
+ * ```typescript
+ * const reporter = new WorkflowReporter({ verbose: false })
+ * orchestrator.setCallbacks(reporter.getCallbacks())
+ * // ... workflow execution ...
+ * reporter.dispose()
+ * ```
+ */
+export declare class WorkflowReporter {
+    private currentPhaseIndex;
+    private currentPhaseName;
+    private disposed;
+    private readonly options;
+    private phaseOrder;
+    private phases;
+    private listrInstance;
+    private listrPromise;
+    private phaseTransitionChain;
+    private phaseTaskResolver;
+    private phaseTaskOutput;
+    private phaseTaskTitle;
+    private currentTaskPhase;
+    private pendingTitle;
+    private pendingOutput;
+    private tickerInterval;
+    private tickerFrame;
+    private static readonly SPINNER_FRAMES;
+    constructor(options?: WorkflowReporterOptions);
+    /**
+     * Display final boxed dashboard with workflow summary (AC: #4)
+     */
+    displayFinalDashboard(summary: DashboardSummary): void;
+    /**
+     * Dispose of resources and clean up listr2 instance
+     */
+    dispose(): void;
+    /**
+     * Get the workflow callbacks interface for registering with orchestrator
+     */
+    getCallbacks(): WorkflowCallbacks;
+    /**
+     * Get the configured max width for output formatting
+     */
+    getMaxWidth(): number;
+    /**
+     * Check if reporter has been disposed
+     */
+    isDisposed(): boolean;
+    /**
+     * Check if reporter is in TTY mode
+     */
+    isTTYMode(): boolean;
+    /**
+     * Check if reporter is in verbose mode
+     */
+    isVerboseMode(): boolean;
+    /**
+     * Wait for all listr2 tasks to complete (called after orchestrator finishes)
+     */
+    waitForCompletion(): Promise<void>;
+    /**
+     * Clean up the current listr2 instance — resolve pending tasks and wait for
+     * the renderer to finish so the next phase gets a clean terminal.
+     */
+    private cleanupCurrentListr;
+    /**
+     * Create a new listr2 instance for a phase. The phase gets a single top-level
+     * task with a spinner. Spawn progress is piped as task output (shown below the
+     * spinner line). The task resolves when handlePhaseComplete fires.
+     *
+     * Phase transitions are chained: old instance is fully cleaned up before the
+     * new one starts rendering, preventing two renderers fighting over stdout.
+     */
+    private createPhaseListr;
+    /**
+     * Display a phase banner. In verbose mode, shows a full formatBox banner.
+     * In non-verbose TTY mode, the listr2 spinner is the only display (no banner).
+     * In non-TTY mode, shows a plain-text header.
+     */
+    private displayPhaseBanner;
+    private displayPlainTextDashboard;
+    private displayRichDashboard;
+    private handlePhaseStart;
+    private handlePhaseComplete;
+    private handleLayerStart;
+    private handleLayerComplete;
+    private handleSpawnStart;
+    /**
+     * Live-tick the phase title — rotates through running spawns with elapsed time.
+     * Called every 2s by the ticker interval AND once immediately on spawn start.
+     */
+    private stopTicker;
+    /**
+     * Build and render all spawn lines with per-item spinners + elapsed time.
+     * Called every second by the ticker interval AND once on spawn start/complete.
+     */
+    private tickSpawns;
+    private handleSpawnComplete;
+    private handleSpawnOutput;
+    private handleError;
+}