@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/utils/errors.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Error Handling Utilities
+ *
+ * Provides custom error classes with standardized error codes and context.
+ * All errors extend BaseError for consistent handling across the CLI.
+ */
+import type pino from 'pino';
+/**
+ * Error code constants for different error categories
+ */
+export declare const ERR_VALIDATION = "ERR_VALIDATION";
+export declare const ERR_PARSER = "ERR_PARSER";
+export declare const ERR_FILE_SYSTEM = "ERR_FILE_SYSTEM";
+export declare const ERR_AGENT = "ERR_AGENT";
+export declare const ERR_CONFIG = "ERR_CONFIG";
+/**
+ * Type for error codes
+ */
+export type ErrorCode = typeof ERR_AGENT | typeof ERR_CONFIG | typeof ERR_FILE_SYSTEM | typeof ERR_PARSER | typeof ERR_VALIDATION;
+/**
+ * Context object for additional error information
+ */
+export interface ErrorContext {
+    [key: string]: unknown;
+}
+/**
+ * Base error class with error codes and context
+ *
+ * All custom errors should extend this class for consistent handling.
+ */
+export declare class BaseError extends Error {
+    /**
+     * Error code for categorization
+     */
+    readonly code: ErrorCode;
+    /**
+     * Additional context information
+     */
+    readonly context?: ErrorContext;
+    /**
+     * Actionable suggestion for resolving the error
+     */
+    readonly suggestion?: string;
+    /**
+     * Create a new BaseError
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for categorization
+     * @param context - Additional context information
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new BaseError('Operation failed', 'ERR_VALIDATION', { field: 'email' }, 'Provide a valid email address')
+     */
+    constructor(message: string, code: ErrorCode, context?: ErrorContext, suggestion?: string);
+    /**
+     * Convert error to JSON for logging
+     *
+     * @returns JSON representation of the error
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Validation error for input validation failures
+ *
+ * Used when user input or configuration is invalid.
+ */
+export declare class ValidationError extends BaseError {
+    /**
+     * Create a new ValidationError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., field name, validation rule)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new ValidationError('Email is required', { field: 'email', value: '' }, 'Provide a valid email address in the format: user@example.com')
+     */
+    constructor(message: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * File system error for file operation failures
+ *
+ * Used when file operations (read, write, move) fail.
+ */
+export declare class FileSystemError extends BaseError {
+    /**
+     * Create a new FileSystemError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., file path, operation type)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new FileSystemError('File not found', { filePath: '/path/to/file.md' }, "Check that you're in the project root directory and the path is correct.")
+     */
+    constructor(message: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * Agent error for Claude CLI execution failures
+ *
+ * Used when spawning or executing Claude CLI processes fails.
+ */
+export declare class AgentError extends BaseError {
+    /**
+     * Create a new AgentError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., exit code, stderr, agent type)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new AgentError('Agent execution failed', { exitCode: 1, stderr: 'Error output' }, 'Ensure Claude CLI is installed and accessible in your PATH.')
+     */
+    constructor(message: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * Configuration error for config validation failures
+ *
+ * Used when configuration files are invalid or missing required fields.
+ */
+export declare class ConfigurationError extends BaseError {
+    /**
+     * Create a new ConfigurationError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., config field, expected value, actual value)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new ConfigurationError('Invalid field "prdFile"', { field: 'prdFile', expectedType: 'string', actualType: 'number' }, "Field 'prdFile' expects string, got number. Example: 'docs/prd.md'")
+     */
+    constructor(message: string, context?: ErrorContext, suggestion?: string);
+    /**
+     * Get example value for common config fields
+     * @param field - Config field name
+     * @param type - Expected type
+     * @returns Example value
+     */
+    private static getExampleValue;
+}
+/**
+ * Parser error for markdown parsing failures
+ *
+ * Used when parsing PRD, epic, or story files fails.
+ */
+export declare class ParserError extends BaseError {
+    /**
+     * Create a new ParserError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., file path, line number, problematic line content)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new ParserError('Invalid epic format at line 42', { filePath: 'prd.md', line: 42, lineContent: '## Epic A: Title' }, "Expected format: '## Epic 1: Title'")
+     */
+    constructor(message: string, context?: ErrorContext, suggestion?: string);
+}
+/**
+ * Handle fatal errors by logging and exiting the process
+ *
+ * This function should be used for unrecoverable errors that require
+ * the CLI to exit immediately. It logs the error with full context
+ * and exits with code 1.
+ *
+ * @param error - The error to handle
+ * @param logger - Logger instance for error logging
+ * @example
+ * try {
+ *   // critical operation
+ * } catch (error) {
+ *   handleFatalError(error as Error, logger)
+ * }
+ */
+export declare function handleFatalError(error: Error, logger: pino.Logger): never;

package/dist/utils/errors.js

@@ -0,0 +1,233 @@
+/**
+ * Error Handling Utilities
+ *
+ * Provides custom error classes with standardized error codes and context.
+ * All errors extend BaseError for consistent handling across the CLI.
+ */
+/**
+ * Error code constants for different error categories
+ */
+export const ERR_VALIDATION = 'ERR_VALIDATION';
+export const ERR_PARSER = 'ERR_PARSER';
+export const ERR_FILE_SYSTEM = 'ERR_FILE_SYSTEM';
+export const ERR_AGENT = 'ERR_AGENT';
+export const ERR_CONFIG = 'ERR_CONFIG';
+/**
+ * Base error class with error codes and context
+ *
+ * All custom errors should extend this class for consistent handling.
+ */
+export class BaseError extends Error {
+    /**
+     * Error code for categorization
+     */
+    code;
+    /**
+     * Additional context information
+     */
+    context;
+    /**
+     * Actionable suggestion for resolving the error
+     */
+    suggestion;
+    /**
+     * Create a new BaseError
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for categorization
+     * @param context - Additional context information
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new BaseError('Operation failed', 'ERR_VALIDATION', { field: 'email' }, 'Provide a valid email address')
+     */
+    constructor(message, code, context, suggestion) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.context = context;
+        this.suggestion = suggestion;
+        // Maintain proper stack trace (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Convert error to JSON for logging
+     *
+     * @returns JSON representation of the error
+     */
+    toJSON() {
+        return {
+            code: this.code,
+            context: this.context,
+            message: this.message,
+            name: this.name,
+            stack: this.stack,
+            suggestion: this.suggestion,
+        };
+    }
+}
+/**
+ * Validation error for input validation failures
+ *
+ * Used when user input or configuration is invalid.
+ */
+export class ValidationError extends BaseError {
+    /**
+     * Create a new ValidationError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., field name, validation rule)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new ValidationError('Email is required', { field: 'email', value: '' }, 'Provide a valid email address in the format: user@example.com')
+     */
+    constructor(message, context, suggestion) {
+        super(message, ERR_VALIDATION, context, suggestion || 'Check that all required fields are provided and have valid values.');
+    }
+}
+/**
+ * File system error for file operation failures
+ *
+ * Used when file operations (read, write, move) fail.
+ */
+export class FileSystemError extends BaseError {
+    /**
+     * Create a new FileSystemError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., file path, operation type)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new FileSystemError('File not found', { filePath: '/path/to/file.md' }, "Check that you're in the project root directory and the path is correct.")
+     */
+    constructor(message, context, suggestion) {
+        const defaultSuggestion = context?.filePath
+            ? `Check that you're in the project root directory and the path '${context.filePath}' is correct.`
+            : "Check that you're in the project root directory and the path is correct.";
+        super(message, ERR_FILE_SYSTEM, context, suggestion || defaultSuggestion);
+    }
+}
+/**
+ * Agent error for Claude CLI execution failures
+ *
+ * Used when spawning or executing Claude CLI processes fails.
+ */
+export class AgentError extends BaseError {
+    /**
+     * Create a new AgentError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., exit code, stderr, agent type)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new AgentError('Agent execution failed', { exitCode: 1, stderr: 'Error output' }, 'Ensure Claude CLI is installed and accessible in your PATH.')
+     */
+    constructor(message, context, suggestion) {
+        super(message, ERR_AGENT, context, suggestion || 'Ensure Claude CLI is installed and accessible in your PATH. Run "claude --version" to verify.');
+    }
+}
+/**
+ * Configuration error for config validation failures
+ *
+ * Used when configuration files are invalid or missing required fields.
+ */
+export class ConfigurationError extends BaseError {
+    /**
+     * Create a new ConfigurationError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., config field, expected value, actual value)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new ConfigurationError('Invalid field "prdFile"', { field: 'prdFile', expectedType: 'string', actualType: 'number' }, "Field 'prdFile' expects string, got number. Example: 'docs/prd.md'")
+     */
+    constructor(message, context, suggestion) {
+        let defaultSuggestion = 'Check your .bmad-core/core-config.yaml file for missing or invalid configuration fields.';
+        // Build specific suggestion based on context
+        if (context?.field && context?.expectedType && context?.actualType) {
+            defaultSuggestion = `Field '${context.field}' expects ${context.expectedType}, got ${context.actualType}. Example: ${ConfigurationError.getExampleValue(context.field, context.expectedType)}`;
+        }
+        else if (context?.field) {
+            defaultSuggestion = `Check the '${context.field}' field in your configuration file.`;
+        }
+        super(message, ERR_CONFIG, context, suggestion || defaultSuggestion);
+    }
+    /**
+     * Get example value for common config fields
+     * @param field - Config field name
+     * @param type - Expected type
+     * @returns Example value
+     */
+    static getExampleValue(field, type) {
+        const examples = {
+            epicDir: "'docs/epics'",
+            prdFile: "'docs/prd.md'",
+            prdSharded: 'true',
+            storyDir: "'docs/stories'",
+        };
+        return examples[field] || `<${type} value>`;
+    }
+}
+/**
+ * Parser error for markdown parsing failures
+ *
+ * Used when parsing PRD, epic, or story files fails.
+ */
+export class ParserError extends BaseError {
+    /**
+     * Create a new ParserError
+     *
+     * @param message - Human-readable error message
+     * @param context - Additional context (e.g., file path, line number, problematic line content)
+     * @param suggestion - Actionable suggestion for resolving the error
+     * @example
+     * throw new ParserError('Invalid epic format at line 42', { filePath: 'prd.md', line: 42, lineContent: '## Epic A: Title' }, "Expected format: '## Epic 1: Title'")
+     */
+    constructor(message, context, suggestion) {
+        let defaultSuggestion = 'Check the file format and ensure it follows the expected markdown structure.';
+        // Build specific suggestion based on context
+        if (context?.lineContent && context?.line) {
+            defaultSuggestion = `Problem at line ${context.line}: "${context.lineContent}". Check the expected format for this section.`;
+        }
+        else if (context?.line) {
+            defaultSuggestion = `Problem at line ${context.line}. Check the expected format for this section.`;
+        }
+        super(message, ERR_PARSER, context, suggestion || defaultSuggestion);
+    }
+}
+/**
+ * Handle fatal errors by logging and exiting the process
+ *
+ * This function should be used for unrecoverable errors that require
+ * the CLI to exit immediately. It logs the error with full context
+ * and exits with code 1.
+ *
+ * @param error - The error to handle
+ * @param logger - Logger instance for error logging
+ * @example
+ * try {
+ *   // critical operation
+ * } catch (error) {
+ *   handleFatalError(error as Error, logger)
+ * }
+ */
+export function handleFatalError(error, logger) {
+    // Log the error with full context
+    if (error instanceof BaseError) {
+        logger.fatal({
+            context: error.context,
+            errorCode: error.code,
+            errorMessage: error.message,
+            stack: error.stack,
+        }, 'Fatal error occurred');
+    }
+    else {
+        logger.fatal({
+            errorMessage: error.message,
+            stack: error.stack,
+        }, 'Fatal error occurred');
+    }
+    // Exit with error code
+    process.exit(1);
+}

package/dist/utils/formatters.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Format data as a table with headers and rows
+ *
+ * @param headers - Array of column header strings
+ * @param rows - Array of row data, where each row is an array of cell values
+ * @returns Formatted table string
+ *
+ * @example
+ * ```typescript
+ * const table = formatTable(
+ *   ['Name', 'Status'],
+ *   [['Epic 1', 'Done'], ['Epic 2', 'In Progress']]
+ * )
+ * console.log(table)
+ * ```
+ */
+export declare const formatTable: (headers: string[], rows: string[][]) => string;
+/**
+ * Format an array of items as a list
+ *
+ * @param items - Array of items to format
+ * @param ordered - Whether to use numbered list (default: false)
+ * @returns Formatted list string
+ *
+ * @example
+ * ```typescript
+ * formatList(['Item 1', 'Item 2'], false) // • Item 1\n• Item 2
+ * formatList(['Item 1', 'Item 2'], true)  // 1. Item 1\n2. Item 2
+ * ```
+ */
+export declare const formatList: (items: string[], ordered?: boolean) => string;
+/**
+ * Format content in a bordered box with optional title
+ *
+ * @param title - Title to display at top of box
+ * @param content - Content to display inside box
+ * @returns Formatted box string
+ *
+ * @example
+ * ```typescript
+ * const box = formatBox('Summary', 'Total: 5 items\nSuccess: 4\nFailed: 1')
+ * console.log(box)
+ * ```
+ */
+export declare const formatBox: (title: string, content: string) => string;
+/**
+ * Format seconds as a human-readable countdown string
+ *
+ * @param seconds - Number of seconds to format
+ * @returns Formatted time string (e.g., "2m 30s", "45s", "1h 25m")
+ *
+ * @example
+ * ```typescript
+ * formatCountdown(0)     // "0s"
+ * formatCountdown(45)    // "45s"
+ * formatCountdown(90)    // "1m 30s"
+ * formatCountdown(3600)  // "1h 0m"
+ * formatCountdown(3665)  // "1h 1m"
+ * ```
+ */
+export declare const formatCountdown: (seconds: number) => string;
+/**
+ * Format a duration in milliseconds as a human-readable string
+ *
+ * @param milliseconds - Duration in milliseconds
+ * @returns Formatted duration string
+ */
+export declare const formatDuration: (milliseconds: number) => string;
+/**
+ * Format bytes as a human-readable string
+ *
+ * @param bytes - Number of bytes to format
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Formatted byte string (e.g., "1.50 MB", "256.00 KB")
+ *
+ * @example
+ * ```typescript
+ * formatBytes(1024)           // "1.00 KB"
+ * formatBytes(1048576)        // "1.00 MB"
+ * formatBytes(1536, 0)        // "2 KB"
+ * formatBytes(1536000, 2)     // "1.46 MB"
+ * ```
+ */
+export declare const formatBytes: (bytes: number, decimals?: number) => string;

package/dist/utils/formatters.js

@@ -0,0 +1,162 @@
+/**
+ * Format data as a table with headers and rows
+ *
+ * @param headers - Array of column header strings
+ * @param rows - Array of row data, where each row is an array of cell values
+ * @returns Formatted table string
+ *
+ * @example
+ * ```typescript
+ * const table = formatTable(
+ *   ['Name', 'Status'],
+ *   [['Epic 1', 'Done'], ['Epic 2', 'In Progress']]
+ * )
+ * console.log(table)
+ * ```
+ */
+export const formatTable = (headers, rows) => {
+    if (headers.length === 0) {
+        return '';
+    }
+    // Calculate column widths
+    const columnWidths = headers.map((header, i) => {
+        const maxRowWidth = Math.max(...rows.map((row) => (row[i] || '').length));
+        return Math.max(header.length, maxRowWidth);
+    });
+    // Create separator line
+    const separator = columnWidths.map((width) => '─'.repeat(width + 2)).join('┼');
+    // Format header
+    const headerRow = headers.map((header, i) => ` ${header.padEnd(columnWidths[i])} `).join('│');
+    // Format rows
+    const formattedRows = rows.map((row) => row.map((cell, i) => ` ${(cell || '').padEnd(columnWidths[i])} `).join('│'));
+    // Assemble table
+    return [
+        '┌' + separator.replaceAll('┼', '┬') + '┐',
+        '│' + headerRow + '│',
+        '├' + separator + '┤',
+        ...formattedRows.map((row) => '│' + row + '│'),
+        '└' + separator.replaceAll('┼', '┴') + '┘',
+    ].join('\n');
+};
+/**
+ * Format an array of items as a list
+ *
+ * @param items - Array of items to format
+ * @param ordered - Whether to use numbered list (default: false)
+ * @returns Formatted list string
+ *
+ * @example
+ * ```typescript
+ * formatList(['Item 1', 'Item 2'], false) // • Item 1\n• Item 2
+ * formatList(['Item 1', 'Item 2'], true)  // 1. Item 1\n2. Item 2
+ * ```
+ */
+export const formatList = (items, ordered = false) => {
+    if (items.length === 0) {
+        return '';
+    }
+    return items
+        .map((item, index) => {
+        const prefix = ordered ? `${index + 1}. ` : '• ';
+        return `${prefix}${item}`;
+    })
+        .join('\n');
+};
+/**
+ * Format content in a bordered box with optional title
+ *
+ * @param title - Title to display at top of box
+ * @param content - Content to display inside box
+ * @returns Formatted box string
+ *
+ * @example
+ * ```typescript
+ * const box = formatBox('Summary', 'Total: 5 items\nSuccess: 4\nFailed: 1')
+ * console.log(box)
+ * ```
+ */
+export const formatBox = (title, content) => {
+    const lines = content.split('\n');
+    const maxLength = Math.max(title.length + 2, ...lines.map((line) => line.length));
+    const topBorder = '┏' + '━'.repeat(maxLength + 2) + '┓';
+    const titleLine = title ? `┃ ${title.padEnd(maxLength)} ┃` : '';
+    const separator = title ? '┣' + '━'.repeat(maxLength + 2) + '┫' : '';
+    const contentLines = lines.map((line) => `┃ ${line.padEnd(maxLength)} ┃`);
+    const bottomBorder = '┗' + '━'.repeat(maxLength + 2) + '┛';
+    const parts = [topBorder];
+    if (titleLine)
+        parts.push(titleLine);
+    if (separator)
+        parts.push(separator);
+    parts.push(...contentLines, bottomBorder);
+    return parts.join('\n');
+};
+/**
+ * Format seconds as a human-readable countdown string
+ *
+ * @param seconds - Number of seconds to format
+ * @returns Formatted time string (e.g., "2m 30s", "45s", "1h 25m")
+ *
+ * @example
+ * ```typescript
+ * formatCountdown(0)     // "0s"
+ * formatCountdown(45)    // "45s"
+ * formatCountdown(90)    // "1m 30s"
+ * formatCountdown(3600)  // "1h 0m"
+ * formatCountdown(3665)  // "1h 1m"
+ * ```
+ */
+export const formatCountdown = (seconds) => {
+    if (seconds < 0) {
+        return '0s';
+    }
+    if (seconds === 0) {
+        return '0s';
+    }
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const secs = seconds % 60;
+    if (hours > 0) {
+        return `${hours}h ${minutes}m`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m ${secs}s`;
+    }
+    return `${secs}s`;
+};
+/**
+ * Format a duration in milliseconds as a human-readable string
+ *
+ * @param milliseconds - Duration in milliseconds
+ * @returns Formatted duration string
+ */
+export const formatDuration = (milliseconds) => {
+    const seconds = Math.floor(milliseconds / 1000);
+    return formatCountdown(seconds);
+};
+/**
+ * Format bytes as a human-readable string
+ *
+ * @param bytes - Number of bytes to format
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Formatted byte string (e.g., "1.50 MB", "256.00 KB")
+ *
+ * @example
+ * ```typescript
+ * formatBytes(1024)           // "1.00 KB"
+ * formatBytes(1048576)        // "1.00 MB"
+ * formatBytes(1536, 0)        // "2 KB"
+ * formatBytes(1536000, 2)     // "1.46 MB"
+ * ```
+ */
+export const formatBytes = (bytes, decimals = 2) => {
+    if (bytes === 0) {
+        return '0 Bytes';
+    }
+    const k = 1024;
+    const dm = Math.max(decimals, 0);
+    const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    const value = bytes / k ** i;
+    return `${value.toFixed(dm)} ${sizes[i]}`;
+};