@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/logging/workflow-logger.js

@@ -0,0 +1,552 @@
+/**
+ * WorkflowLogger Service
+ *
+ * Comprehensive logging for workflow executions including:
+ * - Execution metadata and configuration
+ * - Prompts sent to Claude agents
+ * - Responses received from agents
+ * - Execution timeline and state
+ * - Success/failure tracking
+ */
+import fs from 'fs-extra';
+import path from 'node:path';
+export class WorkflowLogger {
+    logger;
+    logsDir;
+    logFile;
+    logFilePath;
+    workflowId;
+    constructor(logger, logsDir = '.bmad-core/logs') {
+        this.logger = logger;
+        this.logsDir = logsDir;
+        this.workflowId = this.generateWorkflowId();
+        this.logFilePath = path.join(this.logsDir, `workflow-${this.workflowId}.json`);
+        this.logFile = {
+            configuration: {},
+            errors: [],
+            executionPlan: {
+                epicsExisting: 0,
+                epicsToCreate: 0,
+                estimatedDuration: '0m',
+                storiesExisting: 0,
+                storiesToCreate: 0,
+                storiesToDevelop: 0,
+            },
+            metadata: {
+                startTime: new Date().toISOString(),
+                status: 'running',
+                workflowId: this.workflowId,
+            },
+            prompts: [],
+            responses: [],
+            summary: {
+                completed: { developments: 0, epics: 0, stories: 0 },
+                failed: { developments: 0, epics: 0, stories: 0 },
+                pending: { developments: 0, epics: 0, stories: 0 },
+            },
+            timeline: [],
+        };
+    }
+    /**
+     * Generate pipeline summary table for concurrent phases
+     *
+     * Creates a formatted table showing the status of each phase in the pipeline,
+     * including pending, in progress, completed, and failed counts.
+     *
+     * @returns Formatted summary table string
+     */
+    generatePipelineSummaryTable() {
+        if (!this.logFile.pipeline) {
+            return '';
+        }
+        const { pipeline, summary } = this.logFile;
+        const table = [];
+        table.push('╔═══════════════════════╦═══════════╦═════════════╦═══════════╦═════════╗', '║ Phase                 ║ Pending   ║ In Progress ║ Completed ║ Failed  ║', '╠═══════════════════════╬═══════════╬═════════════╬═══════════╬═════════╣');
+        // Story Creation row
+        const storyCreationPending = 0; // Not tracked separately
+        const storyCreationInProgress = pipeline.storiesCreating;
+        const storyCreationCompleted = summary.completed.stories;
+        const storyCreationFailed = summary.failed.stories;
+        table.push(`║ Story Creation        ║ ${this.padNumber(storyCreationPending, 9)} ║ ${this.padNumber(storyCreationInProgress, 11)} ║ ${this.padNumber(storyCreationCompleted, 9)} ║ ${this.padNumber(storyCreationFailed, 7)} ║`);
+        // Story Queue row
+        const storyQueuePending = 0; // Not tracked separately
+        const storyQueueInProgress = pipeline.storiesQueued;
+        const storyQueueCompleted = 0; // Stories leave queue when picked up
+        const storyQueueFailed = 0; // Queue doesn't track failures
+        table.push(`║ Story Queue           ║ ${this.padNumber(storyQueuePending, 9)} ║ ${this.padNumber(storyQueueInProgress, 11)} ║ ${this.padNumber(storyQueueCompleted, 9)} ║ ${this.padNumber(storyQueueFailed, 7)} ║`);
+        // Development row (with worker count)
+        const devPending = 0; // Not tracked separately
+        const devInProgress = pipeline.storiesDeveloping;
+        const devCompleted = summary.completed.developments;
+        const devFailed = summary.failed.developments;
+        table.push(`║ Development (${pipeline.activeWorkers}/${pipeline.activeWorkers} workers) ║ ${this.padNumber(devPending, 9)} ║ ${this.padNumber(devInProgress, 11)} ║ ${this.padNumber(devCompleted, 9)} ║ ${this.padNumber(devFailed, 7)} ║`);
+        // Overall row
+        const overallPending = storyCreationPending + storyQueuePending + devPending;
+        const overallInProgress = storyCreationInProgress + storyQueueInProgress + devInProgress;
+        const overallCompleted = pipeline.storiesCompleted;
+        const overallFailed = storyCreationFailed + storyQueueFailed + devFailed;
+        table.push('╠═══════════════════════╬═══════════╬═════════════╬═══════════╬═════════╣', `║ Overall               ║ ${this.padNumber(overallPending, 9)} ║ ${this.padNumber(overallInProgress, 11)} ║ ${this.padNumber(overallCompleted, 9)} ║ ${this.padNumber(overallFailed, 7)} ║`, '╚═══════════════════════╩═══════════╩═════════════╩═══════════╩═════════╝');
+        return table.join('\n');
+    }
+    /**
+     * Get log file path
+     */
+    getLogFilePath() {
+        return this.logFilePath;
+    }
+    /**
+     * Get current pipeline state
+     */
+    getPipelineState() {
+        return this.logFile.pipeline ? { ...this.logFile.pipeline } : undefined;
+    }
+    /**
+     * Get workflow ID
+     */
+    getWorkflowId() {
+        return this.workflowId;
+    }
+    /**
+     * Initialize workflow log with configuration
+     */
+    async initialize(config) {
+        this.logFile.configuration = config;
+        // Ensure logs directory exists
+        await fs.ensureDir(this.logsDir);
+        this.addLogEntry('workflow', 'initialization', {
+            config,
+            logFile: this.logFilePath,
+            workflowId: this.workflowId,
+        });
+        await this.writeLogFile();
+        this.logger.info({
+            logFile: this.logFilePath,
+            workflowId: this.workflowId,
+        }, 'Workflow log initialized');
+    }
+    /**
+     * Initialize pipeline state tracking
+     */
+    initializePipelineState() {
+        this.logFile.pipeline = {
+            activeWorkers: 0,
+            storiesCompleted: 0,
+            storiesCreating: 0,
+            storiesDeveloping: 0,
+            storiesQueued: 0,
+        };
+    }
+    /**
+     * Log phase completion
+     */
+    async logPhaseComplete(phase, successCount, failureCount, duration) {
+        // Update summary
+        switch (phase) {
+            case 'dev': {
+                this.logFile.summary.completed.developments = successCount;
+                this.logFile.summary.failed.developments = failureCount;
+                break;
+            }
+            case 'epic': {
+                this.logFile.summary.completed.epics = successCount;
+                this.logFile.summary.failed.epics = failureCount;
+                break;
+            }
+            case 'story': {
+                this.logFile.summary.completed.stories = successCount;
+                this.logFile.summary.failed.stories = failureCount;
+                break;
+            }
+            // No default
+        }
+        const logDetails = {
+            duration,
+            failed: failureCount,
+            success: successCount,
+        };
+        // Include pipeline state if available
+        if (this.logFile.pipeline) {
+            logDetails.pipelineState = { ...this.logFile.pipeline };
+        }
+        this.addLogEntry(phase, 'phase-complete', logDetails);
+        await this.writeLogFile();
+    }
+    /**
+     * Log phase start
+     */
+    async logPhaseStart(phase, details) {
+        this.addLogEntry(phase, 'phase-start', details);
+        await this.writeLogFile();
+    }
+    /**
+     * Log a prompt being sent to Claude
+     */
+    async logPrompt(phase, itemIdentifier, prompt, options) {
+        const entry = {
+            agentType: options.agentType,
+            itemIdentifier,
+            phase,
+            prompt,
+            promptLength: prompt.length,
+            references: options.references || [],
+            timeout: options.timeout || 1_800_000,
+            timestamp: new Date().toISOString(),
+        };
+        this.logFile.prompts.push(entry);
+        this.addLogEntry(phase, 'prompt-sent', {
+            agentType: options.agentType,
+            identifier: itemIdentifier,
+            promptLength: prompt.length,
+        });
+        await this.writeLogFile();
+    }
+    /**
+     * Log a response received from Claude
+     */
+    async logResponse(phase, itemIdentifier, result) {
+        const entry = {
+            agentType: result.agentType,
+            duration: result.duration,
+            errors: result.errors,
+            exitCode: result.exitCode,
+            itemIdentifier,
+            output: result.output,
+            outputLength: result.output.length,
+            phase,
+            success: result.success,
+            timestamp: new Date().toISOString(),
+        };
+        this.logFile.responses.push(entry);
+        this.addLogEntry(phase, result.success ? 'response-success' : 'response-failure', {
+            agentType: result.agentType,
+            duration: result.duration,
+            exitCode: result.exitCode,
+            identifier: itemIdentifier,
+            outputLength: result.output.length,
+            success: result.success,
+        });
+        if (!result.success) {
+            this.logError(phase, itemIdentifier, result.errors);
+        }
+        await this.writeLogFile();
+    }
+    /**
+     * Log story development completed in pipeline mode
+     */
+    async logStoryCompleted(storyIdentifier, duration, success) {
+        if (!this.logFile.pipeline) {
+            this.initializePipelineState();
+        }
+        this.logFile.pipeline.storiesCompleted++;
+        if (this.logFile.pipeline.storiesDeveloping > 0) {
+            this.logFile.pipeline.storiesDeveloping--;
+        }
+        this.addLogEntry('dev', success ? 'story-completed' : 'story-failed', {
+            duration,
+            identifier: storyIdentifier,
+            pipelineState: { ...this.logFile.pipeline },
+            success,
+        });
+        await this.writeLogFile();
+    }
+    /**
+     * Log story created in pipeline mode
+     */
+    async logStoryCreated(storyIdentifier) {
+        if (!this.logFile.pipeline) {
+            this.initializePipelineState();
+        }
+        this.logFile.pipeline.storiesCreating++;
+        this.addLogEntry('story', 'story-created', {
+            identifier: storyIdentifier,
+            pipelineState: { ...this.logFile.pipeline },
+        });
+        await this.writeLogFile();
+    }
+    /**
+     * Log story development started in pipeline mode
+     */
+    async logStoryDeveloping(storyIdentifier, workerId) {
+        if (!this.logFile.pipeline) {
+            this.initializePipelineState();
+        }
+        this.logFile.pipeline.storiesDeveloping++;
+        if (this.logFile.pipeline.storiesQueued > 0) {
+            this.logFile.pipeline.storiesQueued--;
+        }
+        this.addLogEntry('dev', 'story-developing', {
+            identifier: storyIdentifier,
+            pipelineState: { ...this.logFile.pipeline },
+            workerId,
+        });
+        await this.writeLogFile();
+    }
+    /**
+     * Log story queued for development in pipeline mode
+     */
+    async logStoryQueued(storyIdentifier, queuePosition) {
+        if (!this.logFile.pipeline) {
+            this.initializePipelineState();
+        }
+        this.logFile.pipeline.storiesQueued++;
+        if (this.logFile.pipeline.storiesCreating > 0) {
+            this.logFile.pipeline.storiesCreating--;
+        }
+        this.addLogEntry('story', 'story-queued', {
+            identifier: storyIdentifier,
+            pipelineState: { ...this.logFile.pipeline },
+            queuePosition,
+        });
+        await this.writeLogFile();
+    }
+    /**
+     * Log verbose story transition with timestamp
+     *
+     * Formats transition as: [HH:MM:SS] Story X.Y 'Title' → STATE
+     *
+     * @param storyNumber - Story number (e.g., "1.1")
+     * @param storyTitle - Story title
+     * @param state - New state (CREATING, QUEUED, DEVELOPING, COMPLETED, FAILED)
+     * @param details - Optional additional details
+     */
+    async logVerboseTransition(storyNumber, storyTitle, state, details) {
+        const timestamp = this.formatTime(new Date());
+        const baseMessage = `[${timestamp}] Story ${storyNumber} '${storyTitle}' → ${state}`;
+        let fullMessage = baseMessage;
+        if (details) {
+            if (details.position !== undefined) {
+                fullMessage += ` (position: ${details.position})`;
+            }
+            if (details.workerId !== undefined) {
+                fullMessage += ` (worker: ${details.workerId})`;
+            }
+            if (details.duration !== undefined) {
+                fullMessage += ` (duration: ${this.formatDuration(details.duration)})`;
+            }
+        }
+        this.logger.debug(fullMessage);
+        // Also add to timeline for permanent record
+        this.addLogEntry('story', 'verbose-transition', {
+            state,
+            storyNumber,
+            storyTitle,
+            timestamp: new Date().toISOString(),
+            ...details,
+        });
+        await this.writeLogFile();
+    }
+    /**
+     * Log workflow completion
+     */
+    async logWorkflowComplete(result) {
+        const endTime = new Date().toISOString();
+        const startTime = new Date(this.logFile.metadata.startTime);
+        const duration = Date.now() - startTime.getTime();
+        this.logFile.metadata.endTime = endTime;
+        this.logFile.metadata.duration = duration;
+        this.logFile.metadata.status = result.overallSuccess ? 'completed' : 'failed';
+        this.addLogEntry('workflow', 'workflow-complete', {
+            duration,
+            overallSuccess: result.overallSuccess,
+            totalFailures: result.totalFailures,
+            totalFilesProcessed: result.totalFilesProcessed,
+        });
+        await this.writeLogFile();
+        // Generate human-readable summary
+        await this.generateMarkdownSummary();
+    }
+    /**
+     * Set execution plan
+     */
+    async setExecutionPlan(plan) {
+        this.logFile.executionPlan = plan;
+        this.addLogEntry('workflow', 'execution-plan', {
+            plan,
+        });
+        await this.writeLogFile();
+    }
+    /**
+     * Update active worker count in pipeline mode
+     */
+    async updateActiveWorkers(count) {
+        if (!this.logFile.pipeline) {
+            this.initializePipelineState();
+        }
+        this.logFile.pipeline.activeWorkers = count;
+        this.addLogEntry('dev', 'workers-updated', {
+            activeWorkers: count,
+            pipelineState: { ...this.logFile.pipeline },
+        });
+        await this.writeLogFile();
+    }
+    /**
+     * Add a timeline entry
+     */
+    addLogEntry(phase, action, details) {
+        this.logFile.timeline.push({
+            action,
+            details,
+            level: 'info',
+            phase,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Build markdown summary content
+     */
+    buildMarkdownSummary() {
+        const { configuration, errors, executionPlan, metadata, prompts, responses, summary } = this.logFile;
+        let md = `# Workflow Execution Log\n\n`;
+        // Metadata
+        md += `## Metadata\n\n`;
+        md += `- **Workflow ID:** ${metadata.workflowId}\n`;
+        md += `- **Start Time:** ${metadata.startTime}\n`;
+        md += `- **End Time:** ${metadata.endTime || 'N/A'}\n`;
+        md += `- **Duration:** ${this.formatDuration(metadata.duration || 0)}\n`;
+        md += `- **Status:** ${metadata.status}\n\n`;
+        // Configuration
+        md += `## Configuration\n\n`;
+        md += `\`\`\`json\n${JSON.stringify(configuration, null, 2)}\n\`\`\`\n\n`;
+        // Execution Plan
+        md += `## Execution Plan\n\n`;
+        md += `| Item | To Create | Existing | To Develop |\n`;
+        md += `|------|-----------|----------|------------|\n`;
+        md += `| Epics | ${executionPlan.epicsToCreate} | ${executionPlan.epicsExisting} | - |\n`;
+        md += `| Stories | ${executionPlan.storiesToCreate} | ${executionPlan.storiesExisting} | ${executionPlan.storiesToDevelop} |\n`;
+        md += `\nEstimated Duration: ${executionPlan.estimatedDuration}\n\n`;
+        // Summary
+        md += `## Execution Summary\n\n`;
+        md += `| Phase | Completed | Failed | Pending |\n`;
+        md += `|-------|-----------|--------|----------|\n`;
+        md += `| Epics | ${summary.completed.epics} | ${summary.failed.epics} | ${summary.pending.epics} |\n`;
+        md += `| Stories | ${summary.completed.stories} | ${summary.failed.stories} | ${summary.pending.stories} |\n`;
+        md += `| Development | ${summary.completed.developments} | ${summary.failed.developments} | ${summary.pending.developments} |\n\n`;
+        // Errors
+        if (errors.length > 0) {
+            md += `## Errors (${errors.length})\n\n`;
+            for (const error of errors) {
+                md += `### ${error.phase} - ${error.identifier}\n\n`;
+                md += `- **Time:** ${error.timestamp}\n`;
+                md += `- **Error:** ${error.error}\n\n`;
+            }
+        }
+        // Prompts and Responses
+        md += `## Prompts Sent (${prompts.length})\n\n`;
+        for (const [index, prompt] of prompts.entries()) {
+            md += `### ${index + 1}. ${prompt.phase.toUpperCase()} - ${prompt.itemIdentifier}\n\n`;
+            md += `- **Agent:** ${prompt.agentType}\n`;
+            md += `- **Time:** ${prompt.timestamp}\n`;
+            md += `- **Prompt Length:** ${prompt.promptLength} characters\n`;
+            md += `- **Timeout:** ${prompt.timeout}ms\n\n`;
+            md += `<details>\n<summary>View Prompt</summary>\n\n`;
+            md += `\`\`\`\n${prompt.prompt}\n\`\`\`\n\n`;
+            md += `</details>\n\n`;
+        }
+        md += `## Responses Received (${responses.length})\n\n`;
+        for (const [index, response] of responses.entries()) {
+            md += `### ${index + 1}. ${response.phase.toUpperCase()} - ${response.itemIdentifier}\n\n`;
+            md += `- **Agent:** ${response.agentType}\n`;
+            md += `- **Time:** ${response.timestamp}\n`;
+            md += `- **Success:** ${response.success ? '✓' : '✗'}\n`;
+            md += `- **Duration:** ${this.formatDuration(response.duration)}\n`;
+            md += `- **Exit Code:** ${response.exitCode}\n`;
+            md += `- **Output Length:** ${response.outputLength} characters\n\n`;
+            if (response.success) {
+                md += `<details>\n<summary>View Output</summary>\n\n`;
+                md += `\`\`\`\n${response.output.slice(0, 5000)}${response.outputLength > 5000 ? '\n... (truncated)' : ''}\n\`\`\`\n\n`;
+                md += `</details>\n\n`;
+            }
+            else {
+                md += `**Errors:**\n\`\`\`\n${response.errors}\n\`\`\`\n\n`;
+            }
+        }
+        return md;
+    }
+    /**
+     * Format duration in human-readable format
+     */
+    formatDuration(ms) {
+        if (ms < 1000)
+            return `${ms}ms`;
+        if (ms < 60_000)
+            return `${(ms / 1000).toFixed(1)}s`;
+        if (ms < 3_600_000)
+            return `${(ms / 60_000).toFixed(1)}m`;
+        return `${(ms / 3_600_000).toFixed(1)}h`;
+    }
+    /**
+     * Format time as HH:MM:SS
+     *
+     * @param date - Date to format
+     * @returns Formatted time string
+     * @private
+     */
+    formatTime(date) {
+        const hours = String(date.getHours()).padStart(2, '0');
+        const minutes = String(date.getMinutes()).padStart(2, '0');
+        const seconds = String(date.getSeconds()).padStart(2, '0');
+        return `${hours}:${minutes}:${seconds}`;
+    }
+    /**
+     * Generate human-readable markdown summary
+     */
+    async generateMarkdownSummary() {
+        const markdownPath = this.logFilePath.replace('.json', '.md');
+        const markdown = this.buildMarkdownSummary();
+        try {
+            await fs.writeFile(markdownPath, markdown, 'utf8');
+            this.logger.info({ markdownPath }, 'Generated workflow summary markdown');
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Failed to write markdown summary');
+        }
+    }
+    /**
+     * Generate unique workflow ID
+     */
+    generateWorkflowId() {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).slice(2, 9);
+        return `${timestamp}-${random}`;
+    }
+    /**
+     * Log an error
+     */
+    logError(phase, identifier, error, stack) {
+        this.logFile.errors.push({
+            error,
+            identifier,
+            phase,
+            stack,
+            timestamp: new Date().toISOString(),
+        });
+        this.addLogEntry(phase, 'error', {
+            error,
+            identifier,
+        });
+    }
+    /**
+     * Pad a number to a specific width with spaces
+     *
+     * @param num - Number to pad
+     * @param width - Target width
+     * @returns Padded string
+     * @private
+     */
+    padNumber(num, width) {
+        const str = num.toString();
+        const padding = ' '.repeat(Math.max(0, width - str.length));
+        return padding + str;
+    }
+    /**
+     * Write log file to disk
+     */
+    async writeLogFile() {
+        try {
+            await fs.writeFile(this.logFilePath, JSON.stringify(this.logFile, null, 2), 'utf8');
+        }
+        catch (error) {
+            this.logger.error({ error: error.message }, 'Failed to write workflow log file');
+        }
+    }
+}

package/dist/services/orchestration/batch-processor.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Batch Processor Service
+ *
+ * Handles parallel execution of tasks with configurable concurrency,
+ * intervals between batches, and partial failure handling.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'batch' })
+ * const processor = new BatchProcessor(5, 1000, logger)
+ * const results = await processor.processBatch(items, async (item) => {
+ *   return await someAsyncOperation(item)
+ * }, (info) => {
+ *   console.log(`Processing batch ${info.currentBatch}/${info.totalBatches}`)
+ * })
+ * ```
+ */
+import type pino from 'pino';
+/**
+ * Configuration options for BatchProcessor
+ */
+export interface BatchProcessorOptions {
+    intervalMs: number;
+    maxConcurrency: number;
+}
+/**
+ * Processor function type for batch processing
+ */
+export type ProcessorFunction<TItem, TResult> = (item: TItem) => Promise<TResult>;
+/**
+ * Progress information for batch processing
+ */
+export interface ProgressInfo {
+    completedItems: number;
+    currentBatch: number;
+    currentItem: number;
+    totalBatches: number;
+    totalItems: number;
+}
+/**
+ * Progress callback type
+ */
+export type ProgressCallback = (info: ProgressInfo) => void;
+/**
+ * Result of processing a single item
+ */
+export interface BatchResult<TResult> {
+    error?: Error;
+    result?: TResult;
+    success: boolean;
+}
+/**
+ * BatchProcessor - Handles parallel batch processing with configurable concurrency
+ *
+ * Processes items in batches with configurable concurrency limits and intervals
+ * between batches. Continues processing even if individual items fail, collecting
+ * both successes and failures.
+ *
+ * @example
+ * const processor = new BatchProcessor(5, 1000, logger)
+ * const results = await processor.processBatch(items, async (item) => {
+ *   return await processItem(item)
+ * })
+ */
+export declare class BatchProcessor {
+    private readonly intervalMs;
+    private readonly logger;
+    private readonly maxConcurrency;
+    /**
+     * Create a new BatchProcessor instance
+     *
+     * @param maxConcurrency - Maximum number of concurrent operations (must be positive)
+     * @param intervalMs - Milliseconds to wait between batches (must be non-negative)
+     * @param logger - Logger instance for structured logging
+     * @throws {ValidationError} If maxConcurrency is not positive or intervalMs is negative
+     */
+    constructor(maxConcurrency: number, intervalMs: number, logger: pino.Logger);
+    /**
+     * Process items in parallel batches with partial failure handling
+     *
+     * Divides items into batches of size maxConcurrency, processes each batch
+     * with Promise.allSettled, waits intervalMs between batches, and collects
+     * all results including both successes and failures.
+     *
+     * @param items - Array of items to process
+     * @param processor - Async function to process each item
+     * @param onProgress - Optional callback for progress updates
+     * @returns Array of BatchResult objects in original item order
+     *
+     * @example
+     * const results = await processor.processBatch(items, async (item) => {
+     *   return await processItem(item)
+     * }, (info) => {
+     *   console.log(`Batch ${info.currentBatch}/${info.totalBatches}`)
+     * })
+     */
+    processBatch<TItem, TResult>(items: TItem[], processor: ProcessorFunction<TItem, TResult>, onProgress?: ProgressCallback): Promise<Array<BatchResult<TResult>>>;
+    /**
+     * Delay execution for specified milliseconds
+     *
+     * @param ms - Milliseconds to wait
+     * @returns Promise that resolves after delay
+     */
+    private delay;
+    /**
+     * Split array into batches of specified size
+     *
+     * @param items - Array of items to split
+     * @param batchSize - Maximum items per batch
+     * @returns Array of batches
+     */
+    private splitIntoBatches;
+}