@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/file-system/file-manager.js

@@ -0,0 +1,223 @@
+/**
+ * FileManager Service
+ *
+ * Provides safe file system operations with error handling and logging.
+ * All file operations throughout the CLI should use this service for consistency and testability.
+ */
+import fs from 'fs-extra';
+import { dirname } from 'node:path';
+import { FileSystemError } from '../../utils/errors.js';
+/**
+ * FileManager service for all file system operations
+ *
+ * Abstracts file system operations behind a consistent interface with
+ * comprehensive error handling and logging. All methods use async/await
+ * for consistency.
+ */
+export class FileManager {
+    /**
+     * Logger instance for file operations
+     */
+    logger;
+    /**
+     * Create a new FileManager instance
+     *
+     * @param logger - Pino logger instance for logging file operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:file-system' })
+     * const fileManager = new FileManager(logger)
+     */
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Create a directory (and parent directories if needed)
+     *
+     * Uses ensureDir which is idempotent - safe to call if directory already exists.
+     *
+     * @param path - Path to the directory to create
+     * @throws {FileSystemError} If directory cannot be created (permission denied, invalid path, etc.)
+     * @example
+     * await fileManager.createDirectory('docs/epics')
+     */
+    async createDirectory(path) {
+        this.logger.info('Creating directory: %s', path);
+        try {
+            await fs.ensureDir(path);
+            this.logger.info('Directory created successfully: %s', path);
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error('Error creating directory %s: %O', path, err);
+            throw new FileSystemError(`Failed to create directory: ${path}: ${err.message}`, {
+                operation: 'createDirectory',
+                originalError: err.message,
+                path,
+            });
+        }
+    }
+    /**
+     * Check if a file or directory exists
+     *
+     * @param path - Path to check for existence
+     * @returns True if path exists, false otherwise
+     * @example
+     * const exists = await fileManager.fileExists('docs/prd.md')
+     * if (!exists) {
+     *   throw new Error('PRD not found')
+     * }
+     */
+    async fileExists(path) {
+        this.logger.debug('Checking file existence: %s', path);
+        try {
+            const exists = await fs.pathExists(path);
+            this.logger.debug('File existence check result for %s: %s', path, exists);
+            return exists;
+        }
+        catch (error) {
+            // pathExists should not throw, but handle defensively
+            const err = error;
+            this.logger.error('Error checking file existence %s: %O', path, err);
+            return false;
+        }
+    }
+    /**
+     * List files in a directory matching an optional pattern
+     *
+     * @param directory - Directory to list files from
+     * @param pattern - Optional glob pattern to filter files (e.g., '*.md', 'STORY-*.md')
+     * @returns Array of file paths matching the pattern
+     * @throws {FileSystemError} If directory cannot be read
+     * @example
+     * const storyFiles = await fileManager.listFiles('docs/stories', 'STORY-*.md')
+     */
+    async listFiles(directory, pattern) {
+        this.logger.info('Listing files in directory: %s with pattern: %s', directory, pattern ?? 'none');
+        try {
+            const files = await fs.readdir(directory);
+            // Filter files by pattern if provided
+            const filteredFiles = pattern ? files.filter((file) => this.matchesPattern(file, pattern)) : files;
+            const filePaths = filteredFiles.map((file) => `${directory}/${file}`);
+            this.logger.info('Found %d files in directory: %s', filePaths.length, directory);
+            return filePaths;
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error('Error listing files in directory %s: %O', directory, err);
+            throw new FileSystemError(`Failed to list files in directory: ${directory}: ${err.message}`, {
+                directory,
+                operation: 'listFiles',
+                originalError: err.message,
+                pattern,
+            });
+        }
+    }
+    /**
+     * Move a file from source to destination
+     *
+     * Creates destination directory if it doesn't exist.
+     * Overwrites destination file if it exists.
+     *
+     * @param source - Source file path
+     * @param dest - Destination file path
+     * @throws {FileSystemError} If file cannot be moved (source not found, permission denied, etc.)
+     * @example
+     * await fileManager.moveFile('docs/stories/1.1-story.md', 'docs/qa/stories/1.1-story.md')
+     */
+    async moveFile(source, dest) {
+        this.logger.info('Moving file from %s to %s', source, dest);
+        try {
+            // Ensure destination directory exists
+            await fs.ensureDir(dirname(dest));
+            // Move file with overwrite
+            await fs.move(source, dest, { overwrite: true });
+            this.logger.info('File moved successfully from %s to %s', source, dest);
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error('Error moving file from %s to %s: %O', source, dest, err);
+            throw new FileSystemError(`Failed to move file from ${source} to ${dest}: ${err.message}`, {
+                dest,
+                operation: 'moveFile',
+                originalError: err.message,
+                source,
+            });
+        }
+    }
+    /**
+     * Read file contents as UTF-8 string
+     *
+     * @param path - Path to the file to read
+     * @returns File content as string
+     * @throws {FileSystemError} If file cannot be read (not found, permission denied, etc.)
+     * @example
+     * const content = await fileManager.readFile('docs/prd.md')
+     */
+    async readFile(path) {
+        this.logger.info('Reading file: %s', path);
+        try {
+            const content = await fs.readFile(path, 'utf8');
+            this.logger.info('File read successfully: %s', path);
+            return content;
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error('Error reading file %s: %O', path, err);
+            throw new FileSystemError(`Failed to read file: ${path}: ${err.message}`, {
+                operation: 'readFile',
+                originalError: err.message,
+                path,
+            });
+        }
+    }
+    /**
+     * Write content to file as UTF-8
+     *
+     * Creates parent directories if they don't exist.
+     * Overwrites existing file if present.
+     *
+     * @param path - Path to the file to write
+     * @param content - Content to write to file
+     * @throws {FileSystemError} If file cannot be written (permission denied, invalid path, etc.)
+     * @example
+     * await fileManager.writeFile('docs/epics/epic-1.md', epicContent)
+     */
+    async writeFile(path, content) {
+        this.logger.info('Writing file: %s', path);
+        try {
+            // Ensure parent directory exists
+            await fs.ensureDir(dirname(path));
+            // Write file with UTF-8 encoding
+            await fs.writeFile(path, content, 'utf8');
+            this.logger.info('File written successfully: %s', path);
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error('Error writing file %s: %O', path, err);
+            throw new FileSystemError(`Failed to write file: ${path}: ${err.message}`, {
+                operation: 'writeFile',
+                originalError: err.message,
+                path,
+            });
+        }
+    }
+    /**
+     * Match a file name against a simple glob pattern
+     *
+     * Supports * wildcard only (e.g., 'STORY-*.md', '*.txt')
+     *
+     * @param fileName - File name to check
+     * @param pattern - Glob pattern with * wildcards
+     * @returns True if file matches pattern
+     * @private
+     */
+    matchesPattern(fileName, pattern) {
+        // Convert glob pattern to regex
+        // Escape special regex characters except *
+        const regexPattern = pattern
+            .replaceAll(/[.+?^${}()|[\]\\]/g, String.raw `\$&`) // Escape special chars
+            .replaceAll('*', '.*'); // Convert * to .*
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(fileName);
+    }
+}

package/dist/services/file-system/glob-matcher.d.ts

@@ -0,0 +1,75 @@
+/**
+ * GlobMatcher Service
+ *
+ * Provides glob pattern matching functionality with wildcard support.
+ * Enables flexible file pattern matching for story and epic file selection.
+ */
+import type pino from 'pino';
+import { FileManager } from './file-manager.js';
+/**
+ * GlobMatcher service for file pattern matching
+ *
+ * Expands glob patterns (with * and ? wildcards) to lists of matching files.
+ * All results are filtered to existing files only and sorted alphabetically.
+ *
+ * @example
+ * const globMatcher = new GlobMatcher(fileManager, logger)
+ * const files = await globMatcher.expandPattern('docs/stories/AUTH-*.md')
+ * // Returns: ['docs/stories/AUTH-1.md', 'docs/stories/AUTH-2.md']
+ */
+export declare class GlobMatcher {
+    /**
+     * FileManager instance for file existence checks
+     */
+    private readonly fileManager;
+    /**
+     * Logger instance for glob operations
+     */
+    private readonly logger;
+    /**
+     * Create a new GlobMatcher instance
+     *
+     * @param fileManager - FileManager instance for file operations
+     * @param logger - Pino logger instance for logging glob operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:file-system:glob-matcher' })
+     * const fileManager = new FileManager(logger)
+     * const globMatcher = new GlobMatcher(fileManager, logger)
+     */
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Expand glob pattern to list of matching file paths
+     *
+     * Supports wildcards:
+     * - * matches zero or more characters (e.g., AUTH-* matches AUTH-1.md, AUTH-feature.md)
+     * - ? matches exactly one character (e.g., file?.txt matches file1.txt, fileA.txt)
+     * - ** matches directories recursively (e.g., docs/** /AUTH-* matches files in any subdirectory)
+     *
+     * Results are filtered to only include existing files and sorted alphabetically (case-insensitive).
+     *
+     * @param pattern - Glob pattern with wildcards (* and ?)
+     * @returns Array of matching file paths, sorted alphabetically (empty array if no matches)
+     * @throws {FileSystemError} If pattern expansion fails
+     * @example
+     * // Simple wildcard
+     * const files = await globMatcher.expandPattern('docs/stories/*.md')
+     *
+     * // Multiple wildcards
+     * const files = await globMatcher.expandPattern('docs/* /AUTH-*.md')
+     *
+     * // Question mark wildcard
+     * const files = await globMatcher.expandPattern('file?.txt')
+     */
+    expandPattern(pattern: string): Promise<string[]>;
+    /**
+     * Filter paths to only include existing files
+     *
+     * Uses FileManager to check file existence for each path.
+     * This provides a double-check beyond fast-glob's results.
+     *
+     * @param paths - Array of file paths to filter
+     * @returns Array of paths that exist
+     * @private
+     */
+    private filterExisting;
+}

package/dist/services/file-system/glob-matcher.js

@@ -0,0 +1,126 @@
+/**
+ * GlobMatcher Service
+ *
+ * Provides glob pattern matching functionality with wildcard support.
+ * Enables flexible file pattern matching for story and epic file selection.
+ */
+import fg from 'fast-glob';
+import { FileSystemError } from '../../utils/errors.js';
+/**
+ * GlobMatcher service for file pattern matching
+ *
+ * Expands glob patterns (with * and ? wildcards) to lists of matching files.
+ * All results are filtered to existing files only and sorted alphabetically.
+ *
+ * @example
+ * const globMatcher = new GlobMatcher(fileManager, logger)
+ * const files = await globMatcher.expandPattern('docs/stories/AUTH-*.md')
+ * // Returns: ['docs/stories/AUTH-1.md', 'docs/stories/AUTH-2.md']
+ */
+export class GlobMatcher {
+    /**
+     * FileManager instance for file existence checks
+     */
+    fileManager;
+    /**
+     * Logger instance for glob operations
+     */
+    logger;
+    /**
+     * Create a new GlobMatcher instance
+     *
+     * @param fileManager - FileManager instance for file operations
+     * @param logger - Pino logger instance for logging glob operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:file-system:glob-matcher' })
+     * const fileManager = new FileManager(logger)
+     * const globMatcher = new GlobMatcher(fileManager, logger)
+     */
+    constructor(fileManager, logger) {
+        this.fileManager = fileManager;
+        this.logger = logger;
+    }
+    /**
+     * Expand glob pattern to list of matching file paths
+     *
+     * Supports wildcards:
+     * - * matches zero or more characters (e.g., AUTH-* matches AUTH-1.md, AUTH-feature.md)
+     * - ? matches exactly one character (e.g., file?.txt matches file1.txt, fileA.txt)
+     * - ** matches directories recursively (e.g., docs/** /AUTH-* matches files in any subdirectory)
+     *
+     * Results are filtered to only include existing files and sorted alphabetically (case-insensitive).
+     *
+     * @param pattern - Glob pattern with wildcards (* and ?)
+     * @returns Array of matching file paths, sorted alphabetically (empty array if no matches)
+     * @throws {FileSystemError} If pattern expansion fails
+     * @example
+     * // Simple wildcard
+     * const files = await globMatcher.expandPattern('docs/stories/*.md')
+     *
+     * // Multiple wildcards
+     * const files = await globMatcher.expandPattern('docs/* /AUTH-*.md')
+     *
+     * // Question mark wildcard
+     * const files = await globMatcher.expandPattern('file?.txt')
+     */
+    async expandPattern(pattern) {
+        this.logger.debug({ operation: 'expandPattern', pattern }, 'Expanding glob pattern');
+        // Validate pattern is not empty
+        if (!pattern || pattern.trim().length === 0) {
+            this.logger.error({ operation: 'expandPattern', pattern }, 'Empty glob pattern provided');
+            throw new FileSystemError('Glob pattern cannot be empty', {
+                operation: 'expandPattern',
+                pattern,
+            });
+        }
+        try {
+            // Expand glob pattern using fast-glob
+            const matches = await fg(pattern, {
+                absolute: false, // Return relative paths
+                dot: false, // Don't match dotfiles
+                ignore: ['node_modules/**', '.git/**', 'dist/**', 'coverage/**'], // Ignore common directories
+                onlyFiles: true, // Only return files, not directories
+            });
+            this.logger.debug({ matchCount: matches.length, operation: 'expandPattern', pattern }, 'Fast-glob expansion complete');
+            // Filter to only existing files (double-check with FileManager)
+            const existing = await this.filterExisting(matches);
+            // Sort alphabetically (case-insensitive)
+            const sorted = existing.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+            this.logger.info({ existingCount: sorted.length, matchCount: matches.length, operation: 'expandPattern', pattern }, 'Glob pattern expansion complete');
+            return sorted;
+        }
+        catch (error) {
+            const err = error;
+            // Check if it's already a FileSystemError
+            if (err instanceof FileSystemError) {
+                throw err;
+            }
+            this.logger.error({ error: err.message, operation: 'expandPattern', pattern, stack: err.stack }, 'Error expanding glob pattern');
+            throw new FileSystemError(`Failed to expand glob pattern: ${pattern}: ${err.message}`, {
+                operation: 'expandPattern',
+                originalError: err.message,
+                pattern,
+            });
+        }
+    }
+    /**
+     * Filter paths to only include existing files
+     *
+     * Uses FileManager to check file existence for each path.
+     * This provides a double-check beyond fast-glob's results.
+     *
+     * @param paths - Array of file paths to filter
+     * @returns Array of paths that exist
+     * @private
+     */
+    async filterExisting(paths) {
+        this.logger.debug({ operation: 'filterExisting', pathCount: paths.length }, 'Filtering to existing files');
+        const checks = await Promise.all(paths.map(async (path) => ({
+            exists: await this.fileManager.fileExists(path),
+            path,
+        })));
+        const existing = checks.filter((check) => check.exists).map((check) => check.path);
+        this.logger.debug({ existingCount: existing.length, operation: 'filterExisting', pathCount: paths.length }, 'File existence filtering complete');
+        return existing;
+    }
+}

package/dist/services/file-system/path-resolver.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 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 type pino from 'pino';
+import { FileManager } from './file-manager.js';
+/**
+ * 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 declare class PathResolver {
+    /**
+     * Cached configuration to avoid repeated file reads
+     */
+    private cachedConfig;
+    /**
+     * Cached resolved paths
+     */
+    private cachedPaths;
+    /**
+     * FileManager instance for file operations
+     */
+    private readonly fileManager;
+    /**
+     * Logger instance for path resolution operations
+     */
+    private readonly logger;
+    /**
+     * Project root directory (current working directory)
+     */
+    private readonly 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: FileManager, logger: pino.Logger);
+    /**
+     * 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(): string[];
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
+    /**
+     * 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
+     */
+    private findConfigFile;
+    /**
+     * 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
+     */
+    private getResolvedPaths;
+    /**
+     * 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
+     */
+    private loadConfig;
+    /**
+     * 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
+     */
+    private validateConfig;
+    /**
+     * 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
+     */
+    private validateDirectorySync;
+}