@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/file-system/path-resolver.js

@@ -0,0 +1,400 @@
+/**
+ * PathResolver Service
+ *
+ * Resolves and validates file paths from core-config.yaml configuration.
+ * All commands use this service to get correct directories for epics, stories, and PRD files.
+ */
+import fs from 'fs-extra';
+import { load as yamlLoad } from 'js-yaml';
+import { dirname, resolve } from 'node:path';
+import { ConfigurationError, FileSystemError } from '../../utils/errors.js';
+/**
+ * Configuration file path relative to project root
+ */
+const CONFIG_FILE_PATH = '.bmad-core/core-config.yaml';
+/**
+ * PathResolver service for resolving and validating file paths
+ *
+ * Loads configuration from .bmad-core/core-config.yaml and provides methods
+ * to get correct directories for epics, stories, QA, and PRD files. All paths
+ * are resolved relative to the project root and validated for existence.
+ */
+export class PathResolver {
+    /**
+     * Cached configuration to avoid repeated file reads
+     */
+    cachedConfig = null;
+    /**
+     * Cached resolved paths
+     */
+    cachedPaths = null;
+    /**
+     * FileManager instance for file operations
+     */
+    fileManager;
+    /**
+     * Logger instance for path resolution operations
+     */
+    logger;
+    /**
+     * Project root directory (current working directory)
+     */
+    projectRoot;
+    /**
+     * Create a new PathResolver instance
+     *
+     * @param fileManager - FileManager instance for file operations
+     * @param logger - Pino logger instance for logging path operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:path-resolver' })
+     * const fileManager = new FileManager(logger)
+     * const pathResolver = new PathResolver(fileManager, logger)
+     */
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+        this.projectRoot = process.cwd();
+        this.logger.debug('PathResolver initialized with project root: %s', this.projectRoot);
+    }
+    /**
+     * Get all story directories for existence checks
+     *
+     * Returns an array of all story directories to check when determining
+     * if a story already exists. This includes:
+     * - docs/stories (dev stories)
+     * - docs/qa/stories (QA stories)
+     * - docs/done/stories (completed stories)
+     *
+     * @returns Array of absolute paths to story directories
+     * @example
+     * const allDirs = pathResolver.getAllStoryDirs()
+     * // Returns: ['/path/to/project/docs/stories', '/path/to/project/docs/qa/stories', '/path/to/project/docs/done/stories']
+     */
+    getAllStoryDirs() {
+        const paths = this.getResolvedPaths();
+        const dirs = [paths.storyDir, paths.qaStoryDir, paths.doneStoryDir];
+        this.logger.debug('Getting all story directories: %O', dirs);
+        return dirs;
+    }
+    /**
+     * Get the configuration file path
+     *
+     * Returns the absolute path to .bmad-core/core-config.yaml
+     *
+     * @returns Absolute path to configuration file
+     * @example
+     * const configPath = pathResolver.getConfigPath()
+     * // Returns: '/path/to/project/.bmad-core/core-config.yaml'
+     */
+    getConfigPath() {
+        const configPath = resolve(this.projectRoot, CONFIG_FILE_PATH);
+        this.logger.debug('Getting config path: %s', configPath);
+        return configPath;
+    }
+    /**
+     * Get the Done story directory path
+     *
+     * Returns the docs/done/stories directory for completed stories.
+     *
+     * @returns Absolute path to Done story directory
+     * @example
+     * const doneStoryDir = pathResolver.getDoneStoryDir()
+     * // Returns: '/path/to/project/docs/done/stories'
+     */
+    getDoneStoryDir() {
+        const paths = this.getResolvedPaths();
+        this.logger.debug('Getting Done story directory: %s', paths.doneStoryDir);
+        return paths.doneStoryDir;
+    }
+    /**
+     * Get the epic directory path
+     *
+     * Derives epic directory from story location or explicit configuration.
+     * By convention, epics are in docs/epics if stories are in docs/stories.
+     *
+     * @returns Absolute path to epic directory
+     * @throws {FileSystemError} If epic directory does not exist
+     * @example
+     * const epicDir = pathResolver.getEpicDir()
+     * // Returns: '/path/to/project/docs/epics'
+     */
+    getEpicDir() {
+        const paths = this.getResolvedPaths();
+        this.logger.debug('Getting epic directory: %s', paths.epicDir);
+        return paths.epicDir;
+    }
+    /**
+     * Get the PRD file path
+     *
+     * Returns the configured PRD file path from core-config.yaml.
+     *
+     * @returns Absolute path to PRD file
+     * @example
+     * const prdFile = pathResolver.getPrdFile()
+     * // Returns: '/path/to/project/docs/prd.md'
+     */
+    getPrdFile() {
+        const paths = this.getResolvedPaths();
+        this.logger.debug('Getting PRD file: %s', paths.prdFile);
+        return paths.prdFile;
+    }
+    /**
+     * Get the QA story directory path
+     *
+     * Returns the configured QA location plus /stories subdirectory.
+     *
+     * @returns Absolute path to QA story directory
+     * @throws {FileSystemError} If QA story directory does not exist
+     * @example
+     * const qaStoryDir = pathResolver.getQaStoryDir()
+     * // Returns: '/path/to/project/docs/qa/stories'
+     */
+    getQaStoryDir() {
+        const paths = this.getResolvedPaths();
+        this.logger.debug('Getting QA story directory: %s', paths.qaStoryDir);
+        return paths.qaStoryDir;
+    }
+    /**
+     * Get the story directory path
+     *
+     * Returns the configured story location from core-config.yaml.
+     *
+     * @returns Absolute path to story directory
+     * @throws {FileSystemError} If story directory does not exist
+     * @example
+     * const storyDir = pathResolver.getStoryDir()
+     * // Returns: '/path/to/project/docs/stories'
+     */
+    getStoryDir() {
+        const paths = this.getResolvedPaths();
+        this.logger.debug('Getting story directory: %s', paths.storyDir);
+        return paths.storyDir;
+    }
+    /**
+     * Find configuration file by searching up the directory tree
+     *
+     * Searches for .bmad-core/core-config.yaml starting from project root
+     * and walking up to 5 parent directories.
+     *
+     * @returns Path to found config file, or null if not found
+     */
+    findConfigFile() {
+        const MAX_LEVELS = 5;
+        let currentDir = this.projectRoot;
+        for (let i = 0; i <= MAX_LEVELS; i++) {
+            const configPath = resolve(currentDir, CONFIG_FILE_PATH);
+            this.logger.debug('Searching for config at level %d: %s', i, configPath);
+            if (fs.existsSync(configPath)) {
+                this.logger.info('Found configuration file at: %s', configPath);
+                return configPath;
+            }
+            const parentDir = dirname(currentDir);
+            // Stop if we've reached the filesystem root
+            if (parentDir === currentDir) {
+                break;
+            }
+            currentDir = parentDir;
+        }
+        return null;
+    }
+    /**
+     * Get resolved paths (with caching)
+     *
+     * Loads configuration and resolves all paths on first access,
+     * then returns cached paths on subsequent calls.
+     *
+     * @returns Resolved paths structure
+     */
+    getResolvedPaths() {
+        if (this.cachedPaths) {
+            return this.cachedPaths;
+        }
+        const config = this.loadConfig();
+        // Resolve story directory
+        const storyDir = resolve(this.projectRoot, config.devStoryLocation);
+        // Derive epic directory from story directory
+        // Convention: if stories are in docs/stories, epics are in docs/epics
+        const epicDir = resolve(this.projectRoot, config.devStoryLocation.replace('stories', 'epics'));
+        // Resolve QA story directory
+        const qaLocation = config.qa?.qaLocation || 'docs/qa';
+        const qaStoryDir = resolve(this.projectRoot, qaLocation, 'stories');
+        // Resolve Done story directory
+        const doneStoryDir = resolve(this.projectRoot, 'docs/done/stories');
+        // Resolve PRD file
+        const prdFile = resolve(this.projectRoot, config.prd?.prdFile || 'docs/prd.md');
+        // Validate directories exist
+        this.validateDirectorySync(storyDir, 'story directory');
+        this.validateDirectorySync(epicDir, 'epic directory');
+        this.validateDirectorySync(qaStoryDir, 'QA story directory');
+        // Note: doneStoryDir is optional, don't validate it
+        // Stories may not have been moved to done yet
+        this.cachedPaths = {
+            doneStoryDir,
+            epicDir,
+            prdFile,
+            qaStoryDir,
+            storyDir,
+        };
+        this.logger.info({
+            doneStoryDir,
+            epicDir,
+            prdFile,
+            qaStoryDir,
+            storyDir,
+        }, 'Paths resolved successfully');
+        return this.cachedPaths;
+    }
+    /**
+     * Load configuration from .bmad-core/core-config.yaml
+     *
+     * Reads and parses YAML configuration file, validates structure,
+     * and caches the result for subsequent calls. Searches up to 5 parent
+     * directories to find the config file.
+     *
+     * @returns Parsed and validated configuration
+     * @throws {FileSystemError} If configuration file is missing
+     * @throws {ConfigurationError} If configuration structure is invalid
+     */
+    loadConfig() {
+        if (this.cachedConfig) {
+            this.logger.debug('Using cached configuration');
+            return this.cachedConfig;
+        }
+        const configPath = this.findConfigFile();
+        if (!configPath) {
+            const searchStart = resolve(this.projectRoot, CONFIG_FILE_PATH);
+            this.logger.error('Configuration file not found after searching up to 5 parent directories');
+            throw new FileSystemError(`Configuration file not found: ${searchStart} (searched up to 5 parent directories)`, {
+                configPath: searchStart,
+                operation: 'loadConfig',
+            });
+        }
+        this.logger.info('Loading configuration from: %s', configPath);
+        try {
+            // Read configuration file
+            const content = fs.readFileSync(configPath, 'utf8');
+            this.logger.debug('Configuration file read successfully');
+            // Parse YAML
+            const config = yamlLoad(content);
+            // Validate required fields
+            this.validateConfig(config);
+            this.cachedConfig = config;
+            this.logger.info('Configuration loaded and validated successfully');
+            return config;
+        }
+        catch (error) {
+            if (error instanceof FileSystemError || error instanceof ConfigurationError) {
+                throw error;
+            }
+            const err = error;
+            this.logger.error('Error loading configuration: %O', err);
+            throw new ConfigurationError(`Failed to load configuration: ${err.message}`, {
+                configPath,
+                originalError: err.message,
+            });
+        }
+    }
+    /**
+     * Validate configuration structure
+     *
+     * Checks that all required fields are present and have correct types.
+     *
+     * @param config - Configuration object to validate
+     * @throws {ConfigurationError} If configuration is invalid
+     */
+    validateConfig(config) {
+        if (!config || typeof config !== 'object') {
+            throw new ConfigurationError('Configuration must be an object', {
+                actualType: typeof config,
+            });
+        }
+        const cfg = config;
+        // Validate required field: devStoryLocation
+        if (!cfg.devStoryLocation || typeof cfg.devStoryLocation !== 'string') {
+            throw new ConfigurationError('Missing or invalid required field: devStoryLocation', {
+                field: 'devStoryLocation',
+                value: cfg.devStoryLocation,
+            });
+        }
+        // Validate optional prd field
+        if (cfg.prd) {
+            if (typeof cfg.prd !== 'object') {
+                throw new ConfigurationError('Invalid prd field: must be an object', {
+                    field: 'prd',
+                    value: cfg.prd,
+                });
+            }
+            const prd = cfg.prd;
+            if (prd.prdFile && typeof prd.prdFile !== 'string') {
+                throw new ConfigurationError('Invalid prd.prdFile field: must be a string', {
+                    field: 'prd.prdFile',
+                    value: prd.prdFile,
+                });
+            }
+        }
+        // Validate optional qa field
+        if (cfg.qa) {
+            if (typeof cfg.qa !== 'object') {
+                throw new ConfigurationError('Invalid qa field: must be an object', {
+                    field: 'qa',
+                    value: cfg.qa,
+                });
+            }
+            const qa = cfg.qa;
+            if (qa.qaLocation && typeof qa.qaLocation !== 'string') {
+                throw new ConfigurationError('Invalid qa.qaLocation field: must be a string', {
+                    field: 'qa.qaLocation',
+                    value: qa.qaLocation,
+                });
+            }
+        }
+        this.logger.debug('Configuration validation passed');
+    }
+    /**
+     * Validate that a directory exists (synchronous)
+     *
+     * Checks directory existence and throws error if not found.
+     * Uses synchronous fs check for initialization validation.
+     *
+     * @param dirPath - Absolute path to directory
+     * @param name - Human-readable directory name for error messages
+     * @throws {FileSystemError} If directory does not exist
+     */
+    validateDirectorySync(dirPath, name) {
+        this.logger.debug('Validating directory: %s (%s)', dirPath, name);
+        try {
+            if (!fs.existsSync(dirPath)) {
+                this.logger.error('Directory does not exist: %s (%s)', dirPath, name);
+                throw new FileSystemError(`${name} does not exist: ${dirPath}`, {
+                    dirPath,
+                    name,
+                    operation: 'validateDirectory',
+                });
+            }
+            // Check if it's actually a directory
+            const stats = fs.statSync(dirPath);
+            if (!stats.isDirectory()) {
+                this.logger.error('Path is not a directory: %s (%s)', dirPath, name);
+                throw new FileSystemError(`${name} is not a directory: ${dirPath}`, {
+                    dirPath,
+                    name,
+                    operation: 'validateDirectory',
+                });
+            }
+            this.logger.debug('Directory validation passed: %s (%s)', dirPath, name);
+        }
+        catch (error) {
+            if (error instanceof FileSystemError) {
+                throw error;
+            }
+            const err = error;
+            this.logger.error('Error validating directory %s (%s): %O', dirPath, name, err);
+            throw new FileSystemError(`Failed to validate ${name}: ${err.message}`, {
+                dirPath,
+                name,
+                operation: 'validateDirectory',
+                originalError: err.message,
+            });
+        }
+    }
+}

package/dist/services/logging/workflow-logger.d.ts

@@ -0,0 +1,232 @@
+/**
+ * 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 type { Logger } from 'pino';
+import type { AgentOptions, AgentResult, WorkflowConfig, WorkflowResult } from '../../models/index.js';
+export interface LogEntry {
+    action: string;
+    details: Record<string, unknown>;
+    level: 'debug' | 'error' | 'info' | 'warn';
+    phase: 'dev' | 'epic' | 'story' | 'workflow';
+    timestamp: string;
+}
+export interface PromptLogEntry {
+    agentType: string;
+    itemIdentifier: string;
+    phase: 'dev' | 'epic' | 'story';
+    prompt: string;
+    promptLength: number;
+    references: string[];
+    timeout: number;
+    timestamp: string;
+}
+export interface ResponseLogEntry {
+    agentType: string;
+    duration: number;
+    errors: string;
+    exitCode: number;
+    itemIdentifier: string;
+    output: string;
+    outputLength: number;
+    phase: 'dev' | 'epic' | 'story';
+    success: boolean;
+    timestamp: string;
+}
+export interface ExecutionPlan {
+    epicsExisting: number;
+    epicsToCreate: number;
+    estimatedDuration: string;
+    storiesExisting: number;
+    storiesToCreate: number;
+    storiesToDevelop: number;
+}
+export interface PipelineState {
+    activeWorkers: number;
+    storiesCompleted: number;
+    storiesCreating: number;
+    storiesDeveloping: number;
+    storiesQueued: number;
+}
+export interface WorkflowLogFile {
+    configuration: WorkflowConfig;
+    errors: Array<{
+        error: string;
+        identifier: string;
+        phase: string;
+        stack?: string;
+        timestamp: string;
+    }>;
+    executionPlan: ExecutionPlan;
+    metadata: {
+        duration?: number;
+        endTime?: string;
+        startTime: string;
+        status: 'completed' | 'failed' | 'running';
+        workflowId: string;
+    };
+    pipeline?: PipelineState;
+    prompts: PromptLogEntry[];
+    responses: ResponseLogEntry[];
+    summary: {
+        completed: {
+            developments: number;
+            epics: number;
+            stories: number;
+        };
+        failed: {
+            developments: number;
+            epics: number;
+            stories: number;
+        };
+        pending: {
+            developments: number;
+            epics: number;
+            stories: number;
+        };
+    };
+    timeline: LogEntry[];
+}
+export declare class WorkflowLogger {
+    private readonly logger;
+    private readonly logsDir;
+    private logFile;
+    private logFilePath;
+    private workflowId;
+    constructor(logger: Logger, logsDir?: string);
+    /**
+     * 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(): string;
+    /**
+     * Get log file path
+     */
+    getLogFilePath(): string;
+    /**
+     * Get current pipeline state
+     */
+    getPipelineState(): PipelineState | undefined;
+    /**
+     * Get workflow ID
+     */
+    getWorkflowId(): string;
+    /**
+     * Initialize workflow log with configuration
+     */
+    initialize(config: WorkflowConfig): Promise<void>;
+    /**
+     * Initialize pipeline state tracking
+     */
+    initializePipelineState(): void;
+    /**
+     * Log phase completion
+     */
+    logPhaseComplete(phase: 'dev' | 'epic' | 'story', successCount: number, failureCount: number, duration: number): Promise<void>;
+    /**
+     * Log phase start
+     */
+    logPhaseStart(phase: 'dev' | 'epic' | 'story', details: Record<string, unknown>): Promise<void>;
+    /**
+     * Log a prompt being sent to Claude
+     */
+    logPrompt(phase: 'dev' | 'epic' | 'story', itemIdentifier: string, prompt: string, options: AgentOptions): Promise<void>;
+    /**
+     * Log a response received from Claude
+     */
+    logResponse(phase: 'dev' | 'epic' | 'story', itemIdentifier: string, result: AgentResult): Promise<void>;
+    /**
+     * Log story development completed in pipeline mode
+     */
+    logStoryCompleted(storyIdentifier: string, duration: number, success: boolean): Promise<void>;
+    /**
+     * Log story created in pipeline mode
+     */
+    logStoryCreated(storyIdentifier: string): Promise<void>;
+    /**
+     * Log story development started in pipeline mode
+     */
+    logStoryDeveloping(storyIdentifier: string, workerId: number): Promise<void>;
+    /**
+     * Log story queued for development in pipeline mode
+     */
+    logStoryQueued(storyIdentifier: string, queuePosition?: number): Promise<void>;
+    /**
+     * 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
+     */
+    logVerboseTransition(storyNumber: string, storyTitle: string, state: 'COMPLETED' | 'CREATING' | 'DEVELOPING' | 'FAILED' | 'QUEUED', details?: Record<string, unknown>): Promise<void>;
+    /**
+     * Log workflow completion
+     */
+    logWorkflowComplete(result: WorkflowResult): Promise<void>;
+    /**
+     * Set execution plan
+     */
+    setExecutionPlan(plan: ExecutionPlan): Promise<void>;
+    /**
+     * Update active worker count in pipeline mode
+     */
+    updateActiveWorkers(count: number): Promise<void>;
+    /**
+     * Add a timeline entry
+     */
+    private addLogEntry;
+    /**
+     * Build markdown summary content
+     */
+    private buildMarkdownSummary;
+    /**
+     * Format duration in human-readable format
+     */
+    private formatDuration;
+    /**
+     * Format time as HH:MM:SS
+     *
+     * @param date - Date to format
+     * @returns Formatted time string
+     * @private
+     */
+    private formatTime;
+    /**
+     * Generate human-readable markdown summary
+     */
+    private generateMarkdownSummary;
+    /**
+     * Generate unique workflow ID
+     */
+    private generateWorkflowId;
+    /**
+     * Log an error
+     */
+    private logError;
+    /**
+     * Pad a number to a specific width with spaces
+     *
+     * @param num - Number to pad
+     * @param width - Target width
+     * @returns Padded string
+     * @private
+     */
+    private padNumber;
+    /**
+     * Write log file to disk
+     */
+    private writeLogFile;
+}