@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/commands/prd/validate.js

@@ -0,0 +1,302 @@
+/**
+ * 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 { Args, 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 { PrdParser } from '../../services/parsers/prd-parser.js';
+import * as Colors from '../../utils/colors.js';
+import { createLogger } from '../../utils/logger.js';
+/**
+ * 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: Args.string({
+            description: 'Path to PRD markdown file to validate',
+            required: true,
+        }),
+    };
+    static description = 'Validate PRD and preview epic/story extraction for workflow';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> docs/PRD-feature.md',
+        '<%= config.bin %> <%= command.id %> docs/PRD-feature.md --json',
+        '<%= config.bin %> <%= command.id %> ./my-prd.md -j',
+    ];
+    static flags = {
+        json: Flags.boolean({
+            char: 'j',
+            default: false,
+            description: 'Output validation results as JSON',
+        }),
+    };
+    /**
+     * EpicParser instance for parsing story content
+     */
+    epicParser;
+    /**
+     * FileManager instance for file operations
+     */
+    fileManager;
+    /**
+     * Logger instance
+     */
+    logger = createLogger({ namespace: 'bmad-workflow:commands:prd:validate' });
+    /**
+     * PathResolver instance for resolving paths
+     */
+    pathResolver;
+    /**
+     * PrdParser instance for parsing PRD content
+     */
+    prdParser;
+    /**
+     * Run the validation command
+     */
+    async run() {
+        const { args, flags } = await this.parse(PrdValidate);
+        // Initialize services
+        this.initializeServices();
+        try {
+            // Step 1: Validate PRD file exists and read content
+            this.logger.info({ prdFile: args.prdFile }, 'Starting PRD validation');
+            const prdExists = await this.fileManager.fileExists(args.prdFile);
+            if (!prdExists) {
+                this.error(Colors.error(`PRD file not found: ${args.prdFile}`));
+            }
+            const prdContent = await this.fileManager.readFile(args.prdFile);
+            this.logger.debug({ contentLength: prdContent.length }, 'PRD content loaded');
+            // Step 2: Parse epics from PRD
+            let epics;
+            try {
+                epics = this.prdParser.parseEpics(prdContent, args.prdFile);
+            }
+            catch (error) {
+                const err = error;
+                this.logger.error({ error: err }, 'Failed to parse epics from PRD');
+                this.error(Colors.error(`Failed to parse PRD: ${err.message}`));
+            }
+            this.logger.info({ epicCount: epics.length }, 'Epics parsed from PRD');
+            // Step 3: Validate each epic (check for existing files, count stories)
+            const validationResults = await Promise.all(epics.map(async (epic) => this.validateEpic(epic)));
+            // Step 4: Calculate summary
+            const summary = this.calculateSummary(validationResults);
+            // Step 5: Build output
+            const output = {
+                epics: validationResults,
+                prdFile: relative(process.cwd(), args.prdFile) || args.prdFile,
+                summary,
+            };
+            // Step 6: Display results
+            if (flags.json) {
+                this.outputJson(output);
+            }
+            else {
+                this.outputTable(output);
+            }
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error({ error: err }, 'PRD validation failed');
+            this.error(Colors.error(`Validation failed: ${err.message}`));
+        }
+    }
+    /**
+     * Calculate summary statistics from validation results
+     *
+     * @param results - Array of epic validation results
+     * @returns Summary statistics
+     */
+    calculateSummary(results) {
+        const existingEpics = results.filter((r) => r.status === 'exists').length;
+        const pendingEpics = results.filter((r) => r.status === 'pending').length;
+        const totalStories = results.reduce((sum, r) => sum + r.stories, 0);
+        return {
+            existingEpics,
+            pendingEpics,
+            totalEpics: results.length,
+            totalStories,
+        };
+    }
+    /**
+     * 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
+     */
+    async findEpicFile(epicNumber) {
+        try {
+            const epicDir = this.pathResolver.getEpicDir();
+            const files = await this.fileManager.listFiles(epicDir, '*.md');
+            // Look for files matching epic number patterns
+            const patterns = [
+                new RegExp(`^epic-${epicNumber}-`, 'i'),
+                new RegExp(`-epic-${epicNumber}\\.md$`, 'i'),
+                new RegExp(`-epic-${epicNumber}-`, 'i'),
+            ];
+            for (const file of files) {
+                const filename = file.split('/').pop() || file;
+                for (const pattern of patterns) {
+                    if (pattern.test(filename)) {
+                        this.logger.debug({ epicNumber, file }, 'Epic file found');
+                        return file;
+                    }
+                }
+            }
+            this.logger.debug({ epicNumber }, 'No epic file found');
+            return null;
+        }
+        catch {
+            // Directory might not exist yet
+            this.logger.debug({ epicNumber }, 'Epic directory not found or empty');
+            return null;
+        }
+    }
+    /**
+     * Initialize service instances
+     */
+    initializeServices() {
+        this.fileManager = new FileManager(this.logger);
+        this.pathResolver = new PathResolver(this.fileManager, this.logger);
+        this.prdParser = new PrdParser(this.logger);
+        this.epicParser = new EpicParser(this.logger);
+    }
+    /**
+     * Output validation results as JSON
+     *
+     * @param output - Complete validation output
+     */
+    outputJson(output) {
+        this.log(JSON.stringify(output, null, 2));
+    }
+    /**
+     * Output validation results as formatted table
+     *
+     * @param output - Complete validation output
+     */
+    outputTable(output) {
+        // Header
+        this.log('');
+        this.log(Colors.bold('╔════════════════════════════════════════════════════════════════╗'));
+        this.log(Colors.bold('║                    PRD Validation Summary                      ║'));
+        this.log(Colors.bold('╚════════════════════════════════════════════════════════════════╝'));
+        this.log('');
+        this.log(Colors.info(`PRD: ${output.prdFile}`));
+        this.log('');
+        // Create table
+        const table = new Table({
+            colWidths: [10, 40, 10, 30],
+            head: [
+                Colors.bold(Colors.highlight('Epic #')),
+                Colors.bold(Colors.highlight('Title')),
+                Colors.bold(Colors.highlight('Stories')),
+                Colors.bold(Colors.highlight('Status')),
+            ],
+            wordWrap: true,
+        });
+        // Add rows
+        for (const epic of output.epics) {
+            const statusDisplay = epic.status === 'exists' ? Colors.success('✓ Exists') : Colors.warning('○ Pending');
+            const storiesDisplay = epic.status === 'exists' ? epic.stories.toString() : Colors.dim('-');
+            table.push([epic.number.toString(), this.truncateText(epic.title, 38), storiesDisplay, statusDisplay]);
+        }
+        this.log(table.toString());
+        this.log('');
+        // Summary section
+        this.log(Colors.bold('Summary:'));
+        this.log(`  Epics:   ${output.summary.totalEpics} total (${output.summary.existingEpics} existing, ${output.summary.pendingEpics} pending)`);
+        this.log(`  Stories: ${output.summary.totalStories} found in existing epic files`);
+        this.log('');
+        // Warnings
+        if (output.summary.pendingEpics > 0) {
+            this.log(Colors.warning(`⚠ ${output.summary.pendingEpics} epic file(s) not found - would be created by workflow`));
+        }
+        // Success indicator
+        if (output.summary.pendingEpics === 0 && output.summary.totalStories > 0) {
+            this.log(Colors.success('✓ All epic files exist and contain stories'));
+        }
+        this.log('');
+    }
+    /**
+     * Truncate text with ellipsis if too long
+     *
+     * @param text - Text to truncate
+     * @param maxLength - Maximum length
+     * @returns Truncated text
+     */
+    truncateText(text, maxLength) {
+        if (text.length <= maxLength) {
+            return text;
+        }
+        return text.slice(0, maxLength - 3) + '...';
+    }
+    /**
+     * 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
+     */
+    async validateEpic(epic) {
+        this.logger.debug({ epic }, 'Validating epic');
+        // Try to find existing epic file
+        const epicFile = await this.findEpicFile(epic.number);
+        if (!epicFile) {
+            return {
+                epicFile: null,
+                number: epic.number,
+                status: 'pending',
+                stories: 0,
+                title: epic.title,
+            };
+        }
+        // Epic file exists - try to count stories
+        let storyCount = 0;
+        try {
+            const epicContent = await this.fileManager.readFile(epicFile);
+            const stories = this.epicParser.parseStories(epicContent, epicFile);
+            storyCount = stories.length;
+            this.logger.debug({ epicFile, storyCount }, 'Stories counted in epic');
+        }
+        catch (error) {
+            // Epic file exists but couldn't parse stories (maybe no Stories section yet)
+            this.logger.warn({ epicFile, error }, 'Could not parse stories from epic file');
+            storyCount = 0;
+        }
+        return {
+            epicFile: relative(process.cwd(), epicFile) || epicFile,
+            number: epic.number,
+            status: 'exists',
+            stories: storyCount,
+            title: epic.title,
+        };
+    }
+}

package/dist/commands/stories/create.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Stories Create Command
+ *
+ * Automatically generates story markdown files from an epic using parallel Claude AI agent execution.
+ * Creates story files with configurable concurrency and batch processing.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow stories create docs/epics/epic-1-foundation.md
+ * bmad-workflow stories create epic.md --parallel 10
+ * bmad-workflow stories create epic.md --start 3
+ * bmad-workflow stories create epic.md --reference docs/architecture.md
+ * ```
+ */
+import { Command } from '@oclif/core';
+/**
+ * Stories Create Command
+ *
+ * Creates story files from epic using Claude AI agents with parallel processing.
+ */
+export default class StoriesCreateCommand extends Command {
+    static args: {
+        'epic-path': import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        interval: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        parallel: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        prefix: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        reference: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        start: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        agent: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        cwd: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        provider: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        task: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private agentRunner;
+    private batchProcessor;
+    private epicParser;
+    private fileManager;
+    private fileScaffolder;
+    private logger;
+    private pathResolver;
+    /**
+     * Run the command
+     */
+    run(): Promise<void>;
+    /**
+     * Build Claude CLI prompt for story creation
+     */
+    private buildClaudePrompt;
+    /**
+     * Check for existing story files across all story directories
+     *
+     * Checks docs/stories, docs/qa/stories, and docs/done/stories to prevent
+     * recreating stories that have been moved for QA or marked as done.
+     */
+    private checkExistingStories;
+    /**
+     * Create stories in parallel batches
+     */
+    private createStoriesInParallel;
+    /**
+     * Create a single story file
+     */
+    private createStory;
+    /**
+     * Display summary report
+     */
+    private displaySummaryReport;
+    /**
+     * Filter stories by start number
+     */
+    private filterStoriesByStart;
+    /**
+     * Generate story filename from story metadata
+     */
+    private generateStoryFilename;
+    /**
+     * Initialize service dependencies
+     */
+    private initializeServices;
+    /**
+     * Parse epic file and extract stories
+     */
+    private parseEpicStories;
+    /**
+     * Validate parallel flag value
+     */
+    private validateParallelFlag;
+}