@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/utils/logger.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Logger Utility
+ *
+ * Provides centralized logging configuration using Pino.
+ * Supports structured JSON logging in production and pretty printing in development.
+ */
+import pino from 'pino';
+/**
+ * Log levels supported by the logger
+ */
+export type LogLevel = 'debug' | 'error' | 'fatal' | 'info' | 'silent' | 'trace' | 'warn';
+/**
+ * Logger configuration options
+ */
+export interface LoggerOptions {
+    /**
+     * Minimum log level
+     */
+    level?: LogLevel;
+    /**
+     * Logger namespace (e.g., 'services:parser')
+     */
+    namespace?: string;
+    /**
+     * Enable pretty printing for development
+     */
+    pretty?: boolean;
+}
+/**
+ * Create a logger instance with the specified configuration
+ *
+ * @param options - Logger configuration options
+ * @returns Configured Pino logger instance
+ * @example
+ * const logger = createLogger({ namespace: 'services:parser', level: 'info' })
+ * logger.info('Parsing PRD file')
+ */
+export declare function createLogger(options?: LoggerOptions): pino.Logger<never, boolean>;
+/**
+ * Create a child logger with additional context
+ *
+ * @param parent - Parent logger instance
+ * @param context - Additional context to include in logs
+ * @returns Child logger with merged context
+ * @example
+ * const baseLogger = createLogger({ namespace: 'services' })
+ * const childLogger = createChildLogger(baseLogger, { epic: 'epic-1' })
+ * childLogger.info('Processing epic') // Will include epic context
+ */
+export declare function createChildLogger(parent: pino.Logger, context: Record<string, unknown>): pino.Logger<never, boolean>;
+/**
+ * Generate a correlation ID for tracking a single command invocation
+ *
+ * @returns Correlation ID in format: req-{timestamp}-{random}
+ * @example
+ * const correlationId = generateCorrelationId()
+ * // Returns: 'req-1234567890-0.5'
+ */
+export declare function generateCorrelationId(): string;
+/**
+ * Default logger instance for general use
+ */
+export declare const logger: pino.Logger<never, boolean>;

package/dist/utils/logger.js

@@ -0,0 +1,78 @@
+/**
+ * Logger Utility
+ *
+ * Provides centralized logging configuration using Pino.
+ * Supports structured JSON logging in production and pretty printing in development.
+ */
+import pino from 'pino';
+import pretty from 'pino-pretty';
+/**
+ * Get the log level from environment variable or default
+ *
+ * @param defaultLevel - Default log level to use if LOG_LEVEL is not set
+ * @returns Valid log level
+ */
+function getLogLevel(defaultLevel = 'info') {
+    const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+    const validLevels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent'];
+    if (envLevel && validLevels.includes(envLevel)) {
+        return envLevel;
+    }
+    return defaultLevel;
+}
+/**
+ * Create a logger instance with the specified configuration
+ *
+ * @param options - Logger configuration options
+ * @returns Configured Pino logger instance
+ * @example
+ * const logger = createLogger({ namespace: 'services:parser', level: 'info' })
+ * logger.info('Parsing PRD file')
+ */
+export function createLogger(options = {}) {
+    const { level, namespace, pretty: enablePretty = process.env.NODE_ENV !== 'production' } = options;
+    // Use LOG_LEVEL environment variable if no explicit level is provided
+    const effectiveLevel = level || getLogLevel('info');
+    const baseConfig = {
+        level: effectiveLevel,
+        name: namespace,
+    };
+    if (enablePretty) {
+        const stream = pretty({
+            colorize: true,
+            ignore: 'pid,hostname',
+            translateTime: 'HH:MM:ss',
+        });
+        return pino(baseConfig, stream);
+    }
+    return pino(baseConfig);
+}
+/**
+ * Create a child logger with additional context
+ *
+ * @param parent - Parent logger instance
+ * @param context - Additional context to include in logs
+ * @returns Child logger with merged context
+ * @example
+ * const baseLogger = createLogger({ namespace: 'services' })
+ * const childLogger = createChildLogger(baseLogger, { epic: 'epic-1' })
+ * childLogger.info('Processing epic') // Will include epic context
+ */
+export function createChildLogger(parent, context) {
+    return parent.child(context);
+}
+/**
+ * Generate a correlation ID for tracking a single command invocation
+ *
+ * @returns Correlation ID in format: req-{timestamp}-{random}
+ * @example
+ * const correlationId = generateCorrelationId()
+ * // Returns: 'req-1234567890-0.5'
+ */
+export function generateCorrelationId() {
+    return `req-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+/**
+ * Default logger instance for general use
+ */
+export const logger = createLogger({ namespace: 'bmad-workflow' });

package/dist/utils/progress.d.ts

@@ -0,0 +1,104 @@
+import { Ora } from 'ora';
+/**
+ * Create a simple spinner for single operations
+ *
+ * @param text - Initial text to display with spinner
+ * @returns Ora spinner instance
+ *
+ * @example
+ * ```typescript
+ * const spinner = createSpinner('Loading data...')
+ * spinner.start()
+ * // ... do work
+ * spinner.succeed('Data loaded successfully')
+ * ```
+ */
+export declare const createSpinner: (text: string) => Ora;
+/**
+ * Pipeline status for multi-line progress display
+ */
+export interface PipelineProgressStatus {
+    completed: number;
+    creating: number;
+    developing: number;
+    queued: number;
+    workers: number;
+}
+/**
+ * Multi-step progress tracker for workflows with multiple phases
+ *
+ * Manages a sequence of steps with progress indication, automatically
+ * handling spinner lifecycle and step transitions.
+ *
+ * @example
+ * ```typescript
+ * const progress = new MultiStepProgress(['Parse PRD', 'Create epics', 'Validate'])
+ * progress.start(0) // Start first step
+ * // ... do work
+ * progress.start(1) // Move to second step
+ * // ... do work
+ * progress.succeed('All steps completed')
+ * ```
+ */
+export declare class MultiStepProgress {
+    private currentStep;
+    private pipelineMode;
+    private spinner;
+    private steps;
+    /**
+     * Create a new multi-step progress tracker
+     *
+     * @param steps - Array of step descriptions
+     */
+    constructor(steps: string[]);
+    /**
+     * Enable pipeline mode for multi-line progress display
+     */
+    enablePipelineMode(): void;
+    /**
+     * Mark the current workflow as failed
+     *
+     * @param errorText - Optional error message
+     */
+    fail(errorText?: string): void;
+    /**
+     * Get the current step index
+     *
+     * @returns Current step index, or -1 if no step is active
+     */
+    getCurrentStep(): number;
+    /**
+     * Get total number of steps
+     *
+     * @returns Total number of steps
+     */
+    getTotalSteps(): number;
+    /**
+     * Start a specific step in the workflow
+     *
+     * @param stepIndex - Zero-based index of the step to start
+     */
+    start(stepIndex: number): void;
+    /**
+     * Stop the spinner without marking success or failure
+     */
+    stop(): void;
+    /**
+     * Mark the current workflow as successful
+     *
+     * @param finalText - Optional final success message
+     */
+    succeed(finalText?: string): void;
+    /**
+     * Update the text of the current step
+     *
+     * @param text - New text to display
+     */
+    update(text: string): void;
+    /**
+     * Update pipeline status with color-coded multi-line display
+     *
+     * @param status - Current pipeline status
+     */
+    updatePipelineStatus(status: PipelineProgressStatus): void;
+}

package/dist/utils/progress.js

@@ -0,0 +1,161 @@
+import ora from 'ora';
+/**
+ * Create a simple spinner for single operations
+ *
+ * @param text - Initial text to display with spinner
+ * @returns Ora spinner instance
+ *
+ * @example
+ * ```typescript
+ * const spinner = createSpinner('Loading data...')
+ * spinner.start()
+ * // ... do work
+ * spinner.succeed('Data loaded successfully')
+ * ```
+ */
+export const createSpinner = (text) => ora({
+    color: 'cyan',
+    text,
+});
+/**
+ * Multi-step progress tracker for workflows with multiple phases
+ *
+ * Manages a sequence of steps with progress indication, automatically
+ * handling spinner lifecycle and step transitions.
+ *
+ * @example
+ * ```typescript
+ * const progress = new MultiStepProgress(['Parse PRD', 'Create epics', 'Validate'])
+ * progress.start(0) // Start first step
+ * // ... do work
+ * progress.start(1) // Move to second step
+ * // ... do work
+ * progress.succeed('All steps completed')
+ * ```
+ */
+export class MultiStepProgress {
+    currentStep = -1;
+    pipelineMode = false;
+    spinner = null;
+    steps;
+    /**
+     * Create a new multi-step progress tracker
+     *
+     * @param steps - Array of step descriptions
+     */
+    constructor(steps) {
+        this.steps = steps;
+    }
+    /**
+     * Enable pipeline mode for multi-line progress display
+     */
+    enablePipelineMode() {
+        this.pipelineMode = true;
+    }
+    /**
+     * Mark the current workflow as failed
+     *
+     * @param errorText - Optional error message
+     */
+    fail(errorText) {
+        if (this.spinner) {
+            this.spinner.fail(errorText || 'Workflow failed');
+            this.spinner = null;
+        }
+    }
+    /**
+     * Get the current step index
+     *
+     * @returns Current step index, or -1 if no step is active
+     */
+    getCurrentStep() {
+        return this.currentStep;
+    }
+    /**
+     * Get total number of steps
+     *
+     * @returns Total number of steps
+     */
+    getTotalSteps() {
+        return this.steps.length;
+    }
+    /**
+     * Start a specific step in the workflow
+     *
+     * @param stepIndex - Zero-based index of the step to start
+     */
+    start(stepIndex) {
+        // Stop previous spinner if exists
+        if (this.spinner) {
+            this.spinner.stop();
+        }
+        if (stepIndex < 0 || stepIndex >= this.steps.length) {
+            throw new Error(`Invalid step index: ${stepIndex}`);
+        }
+        this.currentStep = stepIndex;
+        const stepText = `[${stepIndex + 1}/${this.steps.length}] ${this.steps[stepIndex]}`;
+        this.spinner = ora({
+            color: 'cyan',
+            text: stepText,
+        });
+        this.spinner.start();
+    }
+    /**
+     * Stop the spinner without marking success or failure
+     */
+    stop() {
+        if (this.spinner) {
+            this.spinner.stop();
+            this.spinner = null;
+        }
+    }
+    /**
+     * Mark the current workflow as successful
+     *
+     * @param finalText - Optional final success message
+     */
+    succeed(finalText) {
+        if (this.spinner) {
+            this.spinner.succeed(finalText || 'All steps completed');
+            this.spinner = null;
+        }
+    }
+    /**
+     * Update the text of the current step
+     *
+     * @param text - New text to display
+     */
+    update(text) {
+        if (this.spinner) {
+            this.spinner.text = text;
+        }
+    }
+    /**
+     * Update pipeline status with color-coded multi-line display
+     *
+     * @param status - Current pipeline status
+     */
+    updatePipelineStatus(status) {
+        if (!this.spinner || !this.pipelineMode) {
+            return;
+        }
+        const lines = [];
+        // Phase 1: Story Creation (cyan)
+        if (status.creating > 0) {
+            lines.push(`  ✓ Creating: ${status.creating}`);
+        }
+        // Phase 2: Queue (yellow)
+        if (status.queued > 0) {
+            lines.push(`  ⏳ Queued: ${status.queued}`);
+        }
+        // Phase 3: Development (blue) with worker count
+        if (status.developing > 0 || status.workers > 0) {
+            lines.push(`  🔄 Developing: ${status.developing} (Workers: ${status.workers})`);
+        }
+        // Phase 4: Completed (green)
+        if (status.completed > 0) {
+            lines.push(`  ✅ Completed: ${status.completed}`);
+        }
+        this.spinner.text = lines.length > 0 ? lines.join('\n') : 'Pipeline running...';
+    }
+}

package/dist/utils/retry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Retry Strategy Utility
+ *
+ * Provides configurable retry logic with exponential backoff for handling
+ * transient failures gracefully.
+ */
+import type pino from 'pino';
+/**
+ * Options for configuring retry behavior
+ */
+export interface RetryOptions {
+    /**
+     * Initial backoff delay in milliseconds
+     * @default 1000 (1 second)
+     */
+    backoffMs?: number;
+    /**
+     * Backoff multiplier for exponential backoff
+     * @default 2 (doubles each retry)
+     */
+    backoffMultiplier?: number;
+    /**
+     * Predicate function to determine if error is retryable
+     * Returns true if the error should trigger a retry
+     * @default () => true (all errors are retryable)
+     */
+    isRetryable?: (error: Error) => boolean;
+    /**
+     * Logger instance for retry logging
+     * If not provided, a default logger will be created
+     */
+    logger?: pino.Logger;
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+}
+/**
+ * Retry strategy implementation with configurable exponential backoff
+ *
+ * Automatically retries failed operations with increasing delays between attempts.
+ * Supports custom predicates to determine if errors are retryable.
+ *
+ * @example
+ * const retry = new RetryStrategy({ maxRetries: 3, backoffMs: 1000 })
+ * const result = await retry.execute(async () => {
+ *   // operation that might fail transiently
+ * })
+ */
+export declare class RetryStrategy {
+    private readonly backoffMs;
+    private readonly backoffMultiplier;
+    private readonly isRetryable;
+    private readonly logger;
+    private readonly maxRetries;
+    /**
+     * Create a new RetryStrategy
+     *
+     * @param options - Configuration options for retry behavior
+     * @example
+     * const retry = new RetryStrategy({
+     *   maxRetries: 3,
+     *   backoffMs: 1000,
+     *   isRetryable: (error) => error.message.includes('timeout')
+     * })
+     */
+    constructor(options?: RetryOptions);
+    /**
+     * Execute an async operation with retry logic
+     *
+     * Attempts to execute the operation, retrying on failure with exponential backoff
+     * if the error is determined to be retryable.
+     *
+     * @param operation - Async function to execute
+     * @returns Promise resolving to the operation result
+     * @throws Error if all retry attempts are exhausted
+     * @example
+     * const result = await retry.execute(async () => {
+     *   return await fetchData()
+     * })
+     */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Calculate exponential backoff delay
+     *
+     * @param attempt - Current attempt number (1-indexed)
+     * @returns Delay in milliseconds
+     * @private
+     */
+    private calculateBackoff;
+    /**
+     * Delay execution for specified milliseconds
+     *
+     * @param ms - Milliseconds to delay
+     * @returns Promise that resolves after delay
+     * @private
+     */
+    private delay;
+}
+/**
+ * Helper function to create a retry predicate for Claude CLI errors
+ *
+ * Returns true if the error represents a transient failure that should be retried.
+ * Specifically checks for timeout (exit code 124) and killed (exit code 137) errors.
+ *
+ * @param error - Error to check
+ * @returns True if error is retryable
+ * @example
+ * const retry = new RetryStrategy({
+ *   isRetryable: isClaudeCliRetryable
+ * })
+ */
+export declare function isClaudeCliRetryable(error: Error): boolean;

package/dist/utils/retry.js

@@ -0,0 +1,160 @@
+/**
+ * Retry Strategy Utility
+ *
+ * Provides configurable retry logic with exponential backoff for handling
+ * transient failures gracefully.
+ */
+import { createLogger } from './logger.js';
+/**
+ * Retry strategy implementation with configurable exponential backoff
+ *
+ * Automatically retries failed operations with increasing delays between attempts.
+ * Supports custom predicates to determine if errors are retryable.
+ *
+ * @example
+ * const retry = new RetryStrategy({ maxRetries: 3, backoffMs: 1000 })
+ * const result = await retry.execute(async () => {
+ *   // operation that might fail transiently
+ * })
+ */
+export class RetryStrategy {
+    backoffMs;
+    backoffMultiplier;
+    isRetryable;
+    logger;
+    maxRetries;
+    /**
+     * Create a new RetryStrategy
+     *
+     * @param options - Configuration options for retry behavior
+     * @example
+     * const retry = new RetryStrategy({
+     *   maxRetries: 3,
+     *   backoffMs: 1000,
+     *   isRetryable: (error) => error.message.includes('timeout')
+     * })
+     */
+    constructor(options = {}) {
+        this.maxRetries = options.maxRetries ?? 3;
+        this.backoffMs = options.backoffMs ?? 1000;
+        this.backoffMultiplier = options.backoffMultiplier ?? 2;
+        this.isRetryable = options.isRetryable ?? (() => true);
+        this.logger = options.logger ?? createLogger({ namespace: 'utils:retry' });
+    }
+    /**
+     * Execute an async operation with retry logic
+     *
+     * Attempts to execute the operation, retrying on failure with exponential backoff
+     * if the error is determined to be retryable.
+     *
+     * @param operation - Async function to execute
+     * @returns Promise resolving to the operation result
+     * @throws Error if all retry attempts are exhausted
+     * @example
+     * const result = await retry.execute(async () => {
+     *   return await fetchData()
+     * })
+     */
+    async execute(operation) {
+        let lastError;
+        let attempt = 0;
+        // Retry loop must be sequential to respect retry delays and attempt ordering
+        while (attempt <= this.maxRetries) {
+            try {
+                // Attempt the operation
+                // eslint-disable-next-line no-await-in-loop -- sequential retry attempts required
+                const result = await operation();
+                // Success - log if this was a retry
+                if (attempt > 0) {
+                    this.logger.info({
+                        attempt,
+                        maxRetries: this.maxRetries,
+                    }, 'Operation succeeded after retry');
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                attempt++;
+                // Check if we should retry
+                if (attempt > this.maxRetries) {
+                    // Exhausted all retries
+                    this.logger.error({
+                        attempt: attempt - 1,
+                        errorMessage: lastError.message,
+                        maxRetries: this.maxRetries,
+                    }, 'Operation failed after exhausting all retries');
+                    throw lastError;
+                }
+                // Check if error is retryable
+                if (!this.isRetryable(lastError)) {
+                    this.logger.warn({
+                        attempt: attempt - 1,
+                        errorMessage: lastError.message,
+                    }, 'Operation failed with non-retryable error');
+                    throw lastError;
+                }
+                // Calculate backoff delay
+                const delay = this.calculateBackoff(attempt);
+                this.logger.warn({
+                    attempt,
+                    delayMs: delay,
+                    errorMessage: lastError.message,
+                    maxRetries: this.maxRetries,
+                }, 'Operation failed, retrying after delay');
+                // Wait before retrying - must be sequential to enforce retry delay
+                // eslint-disable-next-line no-await-in-loop -- retry delay must be sequential
+                await this.delay(delay);
+            }
+        }
+        // This should never be reached, but TypeScript needs it
+        throw lastError || new Error('Operation failed without error');
+    }
+    /**
+     * Calculate exponential backoff delay
+     *
+     * @param attempt - Current attempt number (1-indexed)
+     * @returns Delay in milliseconds
+     * @private
+     */
+    calculateBackoff(attempt) {
+        // Exponential backoff: backoffMs * (multiplier ^ (attempt - 1))
+        // For default values (1000ms, multiplier 2): 1s, 2s, 4s, 8s...
+        return this.backoffMs * this.backoffMultiplier ** (attempt - 1);
+    }
+    /**
+     * Delay execution for specified milliseconds
+     *
+     * @param ms - Milliseconds to delay
+     * @returns Promise that resolves after delay
+     * @private
+     */
+    async delay(ms) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        });
+    }
+}
+/**
+ * Helper function to create a retry predicate for Claude CLI errors
+ *
+ * Returns true if the error represents a transient failure that should be retried.
+ * Specifically checks for timeout (exit code 124) and killed (exit code 137) errors.
+ *
+ * @param error - Error to check
+ * @returns True if error is retryable
+ * @example
+ * const retry = new RetryStrategy({
+ *   isRetryable: isClaudeCliRetryable
+ * })
+ */
+export function isClaudeCliRetryable(error) {
+    // Check if error has exitCode property (AgentError)
+    const exitCode = error.context?.exitCode;
+    if (exitCode !== undefined) {
+        // Retry on timeout (124) or killed (137)
+        return exitCode === 124 || exitCode === 137;
+    }
+    // Default to not retryable if we can't determine exit code
+    return false;
+}