@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/commands/epics/list.js

@@ -0,0 +1,280 @@
+/**
+ * Epics List Command
+ *
+ * Lists all epic files with their metadata in a formatted table.
+ * Scans docs/epics/ directory for epic files and displays:
+ * - Epic number
+ * - Epic title
+ * - Story count
+ * - File path
+ *
+ * Supports JSON output mode for machine-readable consumption.
+ *
+ * @example
+ * ```bash
+ * # Display epics in table format
+ * bmad-workflow epics list
+ *
+ * # Output as JSON
+ * bmad-workflow epics list --json
+ * ```
+ */
+import { Command, Flags } from '@oclif/core';
+import Table from 'cli-table3';
+import { relative } from 'node:path';
+import { FileManager } from '../../services/file-system/file-manager.js';
+import { PathResolver } from '../../services/file-system/path-resolver.js';
+import { EpicParser } from '../../services/parsers/epic-parser.js';
+import * as Colors from '../../utils/colors.js';
+import { createLogger } from '../../utils/logger.js';
+/**
+ * Epics List Command
+ *
+ * Lists all epic files with metadata in table or JSON format.
+ */
+export default class EpicsList extends Command {
+    /**
+     * Command description
+     */
+    static description = 'List all epics with metadata from docs/epics/ directory';
+    /**
+     * Command examples
+     */
+    static examples = ['<%= config.bin %> <%= command.id %>', '<%= config.bin %> <%= command.id %> --json'];
+    /**
+     * Command flags
+     */
+    static flags = {
+        json: Flags.boolean({
+            char: 'j',
+            default: false,
+            description: 'Output as JSON array',
+        }),
+    };
+    /**
+     * Logger instance
+     */
+    logger = createLogger({ namespace: 'bmad-workflow:commands:epics:list' });
+    /**
+     * EpicParser instance
+     */
+    epicParser = new EpicParser(this.logger);
+    /**
+     * FileManager instance
+     */
+    fileManager = new FileManager(this.logger);
+    /**
+     * PathResolver instance
+     */
+    pathResolver = new PathResolver(this.fileManager, this.logger);
+    /**
+     * Run the command
+     */
+    async run() {
+        const { flags } = await this.parse(EpicsList);
+        try {
+            // Discover epic files
+            const epicMetadata = await this.discoverEpics();
+            // Sort by epic number
+            epicMetadata.sort((a, b) => a.number - b.number);
+            // Output in requested format
+            if (flags.json) {
+                this.outputJson(epicMetadata);
+            }
+            else {
+                this.outputTable(epicMetadata);
+            }
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err }, 'Failed to list epics');
+            this.error(Colors.error(`Failed to list epics: ${err.message}`));
+        }
+    }
+    /**
+     * Discover epic files and extract metadata
+     *
+     * @returns Array of epic metadata objects
+     */
+    async discoverEpics() {
+        this.logger.info('Discovering epic files');
+        // Get epic directory path
+        const epicDir = this.pathResolver.getEpicDir();
+        this.logger.debug({ epicDir }, 'Epic directory resolved');
+        // Read directory contents
+        const files = await this.fileManager.listFiles(epicDir, '*.md');
+        this.logger.debug({ fileCount: files.length }, 'Epic files discovered');
+        // Filter files matching epic pattern
+        const epicFiles = files.filter((file) => this.isEpicFile(file));
+        this.logger.debug({ epicFileCount: epicFiles.length }, 'Epic files filtered');
+        if (epicFiles.length === 0) {
+            this.logger.warn('No epic files found');
+            this.warn(Colors.warning('No epic files found in epic directory'));
+            return [];
+        }
+        // Parse each epic file to extract metadata
+        const epicMetadata = await Promise.all(epicFiles.map(async (epicFile) => {
+            try {
+                return await this.parseEpicMetadata(epicFile);
+            }
+            catch (error) {
+                // Handle parsing errors gracefully
+                const err = error;
+                this.logger.error({ epicFile, error: err }, 'Failed to parse epic file');
+                // Extract epic number from filename
+                const epicNumber = this.extractEpicNumber(epicFile);
+                const relativePath = relative(process.cwd(), epicFile);
+                return {
+                    filePath: relativePath,
+                    number: epicNumber,
+                    storyCount: 0,
+                    title: 'Parse Error',
+                };
+            }
+        }));
+        this.logger.info({ epicCount: epicMetadata.length }, 'Epic metadata extracted');
+        return epicMetadata;
+    }
+    /**
+     * Extract epic number from filename
+     *
+     * @param filePath - Epic file path
+     * @returns Epic number
+     */
+    extractEpicNumber(filePath) {
+        const filename = filePath.split('/').pop() || filePath;
+        const match = filename.match(/epic-(\d+)-/i);
+        if (match && match[1]) {
+            return Number.parseInt(match[1], 10);
+        }
+        // Fallback to 0 if pattern doesn't match
+        this.logger.warn({ filename }, 'Could not extract epic number from filename');
+        return 0;
+    }
+    /**
+     * Extract epic title from content
+     *
+     * Looks for first # heading in content, or derives from filename.
+     *
+     * @param content - Epic file content
+     * @param filePath - Epic file path (for fallback title)
+     * @returns Epic title
+     */
+    extractEpicTitle(content, filePath) {
+        // Look for first # heading
+        const headingPattern = /^#\s+(.+?)$/m;
+        const match = content.match(headingPattern);
+        if (match && match[1]) {
+            return match[1].trim();
+        }
+        // Fallback: derive from filename
+        const filename = filePath.split('/').pop() || filePath;
+        const titlePart = filename
+            .replace(/^epic-\d+-/i, '') // Remove epic-N- prefix
+            .replace(/\.md$/, '') // Remove .md extension
+            // eslint-disable-next-line unicorn/prefer-string-replace-all
+            .replace(/-/g, ' ') // Replace all dashes with spaces
+            .split(' ')
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) // Title case
+            .join(' ');
+        this.logger.debug({ filename, title: titlePart }, 'Title derived from filename');
+        return titlePart;
+    }
+    /**
+     * Check if a file is an epic file
+     *
+     * @param filePath - File path to check
+     * @returns True if file matches epic pattern
+     */
+    isEpicFile(filePath) {
+        const filename = filePath.split('/').pop() || filePath;
+        // Pattern: epic-{n}-*.md or EPIC-{n}-*.md
+        const epicPattern = /^epic-\d+-.+\.md$/i;
+        return epicPattern.test(filename);
+    }
+    /**
+     * Output epic metadata as JSON
+     *
+     * @param epicMetadata - Array of epic metadata
+     */
+    outputJson(epicMetadata) {
+        const output = JSON.stringify(epicMetadata, null, 2);
+        this.log(output);
+    }
+    /**
+     * Output epic metadata as formatted table
+     *
+     * @param epicMetadata - Array of epic metadata
+     */
+    outputTable(epicMetadata) {
+        if (epicMetadata.length === 0) {
+            this.log(Colors.warning('No epics found'));
+            return;
+        }
+        // Create table
+        const table = new Table({
+            colWidths: [10, 50, 10, 50],
+            head: [
+                Colors.bold(Colors.highlight('Epic #')),
+                Colors.bold(Colors.highlight('Title')),
+                Colors.bold(Colors.highlight('Stories')),
+                Colors.bold(Colors.highlight('File Path')),
+            ],
+            wordWrap: true,
+        });
+        // Add rows
+        for (const epic of epicMetadata) {
+            table.push([
+                epic.number.toString(),
+                this.truncateTitle(epic.title, 48),
+                epic.storyCount.toString(),
+                epic.filePath,
+            ]);
+        }
+        // Display table
+        this.log(table.toString());
+        // Display summary
+        const totalStories = epicMetadata.reduce((sum, epic) => sum + epic.storyCount, 0);
+        const summary = `Found ${epicMetadata.length} epics with ${totalStories} total stories`;
+        this.log('');
+        this.log(Colors.success(summary));
+    }
+    /**
+     * Parse epic file to extract metadata
+     *
+     * @param epicFile - Path to epic file
+     * @returns Epic metadata
+     */
+    async parseEpicMetadata(epicFile) {
+        this.logger.debug({ epicFile }, 'Parsing epic metadata');
+        // Read file content
+        const content = await this.fileManager.readFile(epicFile);
+        // Extract epic number from filename
+        const epicNumber = this.extractEpicNumber(epicFile);
+        // Parse stories from content
+        const stories = this.epicParser.parseStories(content, epicFile);
+        // Extract title from first heading
+        const title = this.extractEpicTitle(content, epicFile);
+        // Build relative path
+        const relativePath = relative(process.cwd(), epicFile);
+        return {
+            filePath: relativePath,
+            number: epicNumber,
+            storyCount: stories.length,
+            title,
+        };
+    }
+    /**
+     * Truncate title if too long
+     *
+     * @param title - Title to truncate
+     * @param maxLength - Maximum length
+     * @returns Truncated title with ellipsis if needed
+     */
+    truncateTitle(title, maxLength) {
+        if (title.length <= maxLength) {
+            return title;
+        }
+        return title.slice(0, maxLength - 3) + '...';
+    }
+}

package/dist/commands/hello/index.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class Hello extends Command {
+    static args: {
+        person: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        from: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/hello/index.js

@@ -0,0 +1,34 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { createLogger, generateCorrelationId } from '../../utils/logger.js';
+export default class Hello extends Command {
+    static args = {
+        person: Args.string({ description: 'Person to say hello to', required: true }),
+    };
+    static description = 'Say hello';
+    static examples = [
+        `<%= config.bin %> <%= command.id %> friend --from oclif
+hello friend from oclif! (./src/commands/hello/index.ts)
+`,
+    ];
+    static flags = {
+        from: Flags.string({ char: 'f', description: 'Who is saying hello', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Hello);
+        // Create logger with command context
+        const logger = createLogger({ namespace: 'commands:hello' });
+        const correlationId = generateCorrelationId();
+        // Log command execution with context
+        logger.info({
+            command: 'hello',
+            correlationId,
+            from: flags.from,
+            person: args.person,
+        }, 'Executing hello command');
+        // Demonstrate different log levels
+        logger.debug({ correlationId }, 'Debug: Command arguments parsed successfully');
+        logger.info({ correlationId }, `Greeting ${args.person} from ${flags.from}`);
+        this.log(`hello ${args.person} from ${flags.from}! (./src/commands/hello/index.ts)`);
+        logger.info({ correlationId }, 'Hello command completed successfully');
+    }
+}

package/dist/commands/hello/world.d.ts

@@ -0,0 +1,8 @@
+import { Command } from '@oclif/core';
+export default class World extends Command {
+    static args: {};
+    static description: string;
+    static examples: string[];
+    static flags: {};
+    run(): Promise<void>;
+}

package/dist/commands/hello/world.js

@@ -0,0 +1,24 @@
+import { Command } from '@oclif/core';
+import { createLogger, generateCorrelationId } from '../../utils/logger.js';
+export default class World extends Command {
+    static args = {};
+    static description = 'Say hello world';
+    static examples = [
+        `<%= config.bin %> <%= command.id %>
+hello world! (./src/commands/hello/world.ts)
+`,
+    ];
+    static flags = {};
+    async run() {
+        // Create logger with command context
+        const logger = createLogger({ namespace: 'commands:hello:world' });
+        const correlationId = generateCorrelationId();
+        // Log command execution
+        logger.info({
+            command: 'hello:world',
+            correlationId,
+        }, 'Executing hello world command');
+        this.log('hello world! (./src/commands/hello/world.ts)');
+        logger.info({ correlationId }, 'Hello world command completed');
+    }
+}

package/dist/commands/prd/fix.d.ts

@@ -0,0 +1,39 @@
+/**
+ * PRD Fix Command
+ *
+ * Uses AI to automatically reformat a PRD file to match the expected
+ * epic/story structure for workflow processing.
+ *
+ * @example
+ * ```bash
+ * # Fix PRD format
+ * bmad-workflow prd fix docs/PRD-feature.md
+ *
+ * # Fix with architecture reference for context
+ * bmad-workflow prd fix docs/PRD-feature.md --reference docs/architecture.md
+ * ```
+ */
+import { Command } from '@oclif/core';
+/**
+ * PRD Fix Command
+ *
+ * Reformats a PRD file to match expected epic/story patterns using AI.
+ */
+export default class PrdFix extends Command {
+    static args: {
+        prdFile: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        provider: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        reference: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private fileManager;
+    private logger;
+    private prdFixer;
+    private prdParser;
+    run(): Promise<void>;
+    private initializeServices;
+    private validateFixedContent;
+}

package/dist/commands/prd/fix.js

@@ -0,0 +1,140 @@
+/**
+ * PRD Fix Command
+ *
+ * Uses AI to automatically reformat a PRD file to match the expected
+ * epic/story structure for workflow processing.
+ *
+ * @example
+ * ```bash
+ * # Fix PRD format
+ * bmad-workflow prd fix docs/PRD-feature.md
+ *
+ * # Fix with architecture reference for context
+ * bmad-workflow prd fix docs/PRD-feature.md --reference docs/architecture.md
+ * ```
+ */
+import { Args, Command, Flags } from '@oclif/core';
+import { relative } from 'node:path';
+import { createAgentRunner, isProviderSupported } from '../../services/agents/agent-runner-factory.js';
+import { FileManager } from '../../services/file-system/file-manager.js';
+import { PrdFixer } from '../../services/parsers/prd-fixer.js';
+import { PrdParser } from '../../services/parsers/prd-parser.js';
+import * as Colors from '../../utils/colors.js';
+import { createLogger } from '../../utils/logger.js';
+/**
+ * PRD Fix Command
+ *
+ * Reformats a PRD file to match expected epic/story patterns using AI.
+ */
+export default class PrdFix extends Command {
+    static args = {
+        prdFile: Args.string({
+            description: 'Path to PRD markdown file to fix',
+            required: true,
+        }),
+    };
+    static description = 'Fix PRD format using AI to match expected epic/story structure';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> docs/PRD-feature.md',
+        '<%= config.bin %> <%= command.id %> docs/PRD-feature.md --reference docs/architecture.md',
+        '<%= config.bin %> <%= command.id %> docs/PRD-feature.md --provider gemini',
+    ];
+    static flags = {
+        provider: Flags.string({
+            default: 'claude',
+            description: 'AI provider to use (claude or gemini)',
+            options: ['claude', 'gemini'],
+        }),
+        reference: Flags.string({
+            description: 'Reference files for context (can be used multiple times)',
+            multiple: true,
+        }),
+    };
+    fileManager;
+    logger = createLogger({ namespace: 'bmad-workflow:commands:prd:fix' });
+    prdFixer;
+    prdParser;
+    async run() {
+        const { args, flags } = await this.parse(PrdFix);
+        // Validate provider
+        if (!isProviderSupported(flags.provider)) {
+            this.error(`Unsupported provider: ${flags.provider}. Use 'claude' or 'gemini'.`, { exit: 1 });
+        }
+        // Initialize services
+        this.initializeServices(flags.provider);
+        const prdPath = args.prdFile;
+        const relativePath = relative(process.cwd(), prdPath) || prdPath;
+        try {
+            // Check if file exists
+            const exists = await this.fileManager.fileExists(prdPath);
+            if (!exists) {
+                this.error(Colors.error(`PRD file not found: ${prdPath}`), { exit: 1 });
+            }
+            // Read the PRD content
+            const originalContent = await this.fileManager.readFile(prdPath);
+            // First, check if the PRD already parses correctly
+            this.log(Colors.info(`\nAnalyzing PRD: ${relativePath}`));
+            let needsFix = false;
+            try {
+                const epics = this.prdParser.parseEpics(originalContent, prdPath);
+                this.log(Colors.success(`\n✓ PRD already valid - found ${epics.length} epic(s)`));
+                this.log(Colors.dim('  No changes needed.\n'));
+                // Show the epics found
+                for (const epic of epics) {
+                    this.log(Colors.dim(`  • Epic ${epic.number}: ${epic.title}`));
+                }
+                this.log('');
+                return;
+            }
+            catch {
+                needsFix = true;
+                this.log(Colors.warning('\n⚠ PRD format issues detected - attempting auto-fix...'));
+            }
+            if (needsFix) {
+                // Attempt to fix the PRD
+                const references = flags.reference || [];
+                if (references.length > 0) {
+                    this.log(Colors.dim(`  Using ${references.length} reference file(s) for context`));
+                }
+                this.log(Colors.info('  Running AI fixer...'));
+                const result = await this.prdFixer.fixPrd(prdPath, originalContent, references);
+                if (result.fixed) {
+                    this.log(Colors.success('\n✓ PRD fixed successfully!'));
+                    this.log(Colors.dim(`  Backup saved to: ${relativePath}.bak`));
+                    // Validate the fixed content
+                    this.validateFixedContent(result.content, prdPath);
+                }
+                else {
+                    this.log(Colors.error('\n✗ Failed to fix PRD'));
+                    this.log(Colors.error(`  Error: ${result.error}\n`));
+                    this.error('PRD fix failed', { exit: 1 });
+                }
+            }
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err.message, prdPath }, 'PRD fix command failed');
+            this.error(Colors.error(`Fix failed: ${err.message}`), { exit: 1 });
+        }
+    }
+    initializeServices(provider) {
+        this.fileManager = new FileManager(this.logger);
+        this.prdParser = new PrdParser(this.logger);
+        const agentRunner = createAgentRunner(provider, this.logger);
+        this.prdFixer = new PrdFixer(agentRunner, this.fileManager, this.logger);
+    }
+    validateFixedContent(content, prdPath) {
+        try {
+            const epics = this.prdParser.parseEpics(content, prdPath);
+            this.log(Colors.success(`  Found ${epics.length} epic(s) after fix:\n`));
+            for (const epic of epics) {
+                this.log(Colors.dim(`  • Epic ${epic.number}: ${epic.title}`));
+            }
+            this.log('');
+        }
+        catch {
+            this.log(Colors.warning('\n⚠ Fixed file still has parsing issues.'));
+            this.log(Colors.dim('  You may need to manually review the PRD.\n'));
+        }
+    }
+}

package/dist/commands/prd/validate.d.ts

@@ -0,0 +1,112 @@
+/**
+ * PRD Validate Command
+ *
+ * Validates a PRD file and previews the epic/story extraction that would
+ * occur during a workflow run. This is a dry-run inspection tool that:
+ * - Parses the PRD to extract epic definitions
+ * - Checks for existing epic files
+ * - Counts stories in existing epic files
+ * - Reports what would be generated by the workflow command
+ *
+ * @example
+ * ```bash
+ * # Validate PRD and show extraction preview
+ * bmad-workflow prd validate docs/PRD-feature.md
+ *
+ * # Output as JSON for scripting
+ * bmad-workflow prd validate docs/PRD-feature.md --json
+ * ```
+ */
+import { Command } from '@oclif/core';
+/**
+ * PRD Validate Command
+ *
+ * Parses a PRD file and reports what epics and stories would be
+ * extracted by the workflow command.
+ */
+export default class PrdValidate extends Command {
+    static args: {
+        prdFile: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    /**
+     * EpicParser instance for parsing story content
+     */
+    private epicParser;
+    /**
+     * FileManager instance for file operations
+     */
+    private fileManager;
+    /**
+     * Logger instance
+     */
+    private logger;
+    /**
+     * PathResolver instance for resolving paths
+     */
+    private pathResolver;
+    /**
+     * PrdParser instance for parsing PRD content
+     */
+    private prdParser;
+    /**
+     * Run the validation command
+     */
+    run(): Promise<void>;
+    /**
+     * Calculate summary statistics from validation results
+     *
+     * @param results - Array of epic validation results
+     * @returns Summary statistics
+     */
+    private calculateSummary;
+    /**
+     * Find epic file matching the epic number
+     *
+     * Searches the epics directory for files matching pattern:
+     * - epic-{N}-*.md
+     * - *-epic-{N}.md
+     * - *-epic-{N}-*.md
+     *
+     * @param epicNumber - Epic number to search for
+     * @returns Path to epic file if found, null otherwise
+     */
+    private findEpicFile;
+    /**
+     * Initialize service instances
+     */
+    private initializeServices;
+    /**
+     * Output validation results as JSON
+     *
+     * @param output - Complete validation output
+     */
+    private outputJson;
+    /**
+     * Output validation results as formatted table
+     *
+     * @param output - Complete validation output
+     */
+    private outputTable;
+    /**
+     * Truncate text with ellipsis if too long
+     *
+     * @param text - Text to truncate
+     * @param maxLength - Maximum length
+     * @returns Truncated text
+     */
+    private truncateText;
+    /**
+     * Validate a single epic
+     *
+     * Checks if the epic file exists and counts stories if it does.
+     *
+     * @param epic - Epic information from PRD
+     * @returns Validation result for the epic
+     */
+    private validateEpic;
+}