@hyperdrive.bot/bmad-workflow 1.0.26 → 1.0.27

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

@@ -35,6 +35,7 @@ export default class EpicsCreate extends Command {
         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, import("@oclif/core/interfaces").CustomOptions>;
+        stream: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         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>;
         model: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/lock/acquire.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lock Acquire Command
+ *
+ * Acquires exclusive ownership of a story file via a git-committed `.lock` file.
+ * Prevents parallel agents from working on the same story simultaneously.
+ *
+ * Flow: validate → git pull → check existing lock → create .lock → git add+commit+push
+ *
+ * @example
+ * ```bash
+ * bmad-workflow lock acquire --story docs/qa/stories/X.md --agent pirlo --session 550e8400
+ * ```
+ */
+import { Command } from '@oclif/core';
+export default class LockAcquireCommand extends Command {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        agent: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        session: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'stale-threshold': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        story: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private gitOps;
+    private lockService;
+    private logger;
+    private pushConflictHandler;
+    run(): Promise<void>;
+    /**
+     * Clean up a lock file from disk and git state after failure
+     */
+    private cleanupLockFile;
+    /**
+     * Output failure message in JSON or human-readable format, then exit 1
+     */
+    private fail;
+    /**
+     * Get current git branch name
+     */
+    private getCurrentBranch;
+    private initServices;
+    /**
+     * Parse duration string (e.g., '2h', '30m', '1d') to milliseconds
+     */
+    private parseDuration;
+    /**
+     * Output success message in JSON or human-readable format
+     */
+    private succeed;
+}

package/dist/commands/lock/acquire.js

@@ -0,0 +1,193 @@
+/**
+ * Lock Acquire Command
+ *
+ * Acquires exclusive ownership of a story file via a git-committed `.lock` file.
+ * Prevents parallel agents from working on the same story simultaneously.
+ *
+ * Flow: validate → git pull → check existing lock → create .lock → git add+commit+push
+ *
+ * @example
+ * ```bash
+ * bmad-workflow lock acquire --story docs/qa/stories/X.md --agent pirlo --session 550e8400
+ * ```
+ */
+import { execSync } from 'node:child_process';
+import { Command, Flags } from '@oclif/core';
+import fs from 'fs-extra';
+import { LockConflictError } from '../../models/lock.js';
+import { FileManager } from '../../services/file-system/file-manager.js';
+import { GlobMatcher } from '../../services/file-system/glob-matcher.js';
+import { GitOps } from '../../services/git/git-ops.js';
+import { PushConflictHandler } from '../../services/git/push-conflict-handler.js';
+import { LockService } from '../../services/lock/lock-service.js';
+import { createLogger } from '../../utils/logger.js';
+const DURATION_MULTIPLIERS = {
+    d: 86_400_000,
+    h: 3_600_000,
+    m: 60_000,
+    s: 1000,
+};
+export default class LockAcquireCommand extends Command {
+    static description = 'Acquire a lock on a story file';
+    static examples = [
+        {
+            command: '<%= config.bin %> lock acquire --story docs/qa/stories/X.md --agent pirlo --session 550e8400-e29b-41d4-a716-446655440000',
+            description: 'Acquire lock on a story for the pirlo agent',
+        },
+    ];
+    static flags = {
+        agent: Flags.string({ description: 'Agent name claiming the lock', required: true }),
+        json: Flags.boolean({ description: 'Output as JSON' }),
+        session: Flags.string({ description: 'Session UUID', required: true }),
+        'stale-threshold': Flags.string({
+            default: '2h',
+            description: 'Duration before lock is stale (e.g., 2h, 30m, 1d)',
+        }),
+        story: Flags.string({ description: 'Path to story file', required: true }),
+    };
+    gitOps;
+    lockService;
+    logger;
+    pushConflictHandler;
+    async run() {
+        this.initServices();
+        const { flags } = await this.parse(LockAcquireCommand);
+        const cwd = process.cwd();
+        const lockFilePath = flags.story + '.lock';
+        // AC 3: Validate story file exists
+        const storyExists = await fs.pathExists(flags.story);
+        if (!storyExists) {
+            return this.fail(flags, 'Story file not found: ' + flags.story);
+        }
+        // AC 4: Parse stale threshold
+        const thresholdMs = this.parseDuration(flags['stale-threshold']);
+        if (thresholdMs === null) {
+            return this.fail(flags, 'Invalid duration format: ' + flags['stale-threshold'] + ', expected e.g. 2h, 30m, 1d');
+        }
+        // AC 2: Pull latest and check existing lock
+        try {
+            this.gitOps.pull(cwd);
+        }
+        catch {
+            this.logger.warn('git pull failed — proceeding with local state');
+        }
+        const locked = await this.lockService.isLocked(flags.story);
+        if (locked) {
+            const stale = await this.lockService.isStale(flags.story, thresholdMs);
+            if (!stale) {
+                const lockInfo = await this.lockService.getLockInfo(flags.story);
+                if (lockInfo) {
+                    return this.fail(flags, `Lock already held by ${lockInfo.agent_name} since ${lockInfo.started_at}`);
+                }
+            }
+            // AC 4: Stale lock — release and proceed
+            this.logger.info('Removing stale lock');
+            await this.lockService.release(flags.story);
+        }
+        // AC 1, 5, 6: Acquire lock with cleanup on failure
+        let lockFileCreated = false;
+        try {
+            const branch = this.getCurrentBranch(cwd);
+            await this.lockService.acquire(flags.story, flags.agent, flags.session, branch);
+            lockFileCreated = true;
+            this.gitOps.add(lockFilePath, cwd);
+            this.gitOps.commit('acquire: ' + flags.story + ' (' + flags.agent + ')', cwd);
+            const pushResult = this.gitOps.push(cwd);
+            if (!pushResult.success) {
+                if (pushResult.isNonFastForward) {
+                    // AC 5: Handle race condition via PushConflictHandler
+                    this.pushConflictHandler.handleConflict(flags.story, lockFilePath, cwd);
+                    // If handleConflict returns (didn't throw), push succeeded on retry
+                }
+                else {
+                    throw new Error('Git push failed: ' + (pushResult.stderr || 'unknown error'));
+                }
+            }
+        }
+        catch (error) {
+            // AC 6: Cleanup — no partial lock files remain
+            if (lockFileCreated) {
+                this.cleanupLockFile(lockFilePath, cwd);
+            }
+            if (error instanceof LockConflictError) {
+                return this.fail(flags, `Lock claimed by ${error.lockContent.agent_name} during race — backing off`);
+            }
+            return this.fail(flags, error.message);
+        }
+        // AC 7, 8: Success output
+        this.succeed(flags);
+    }
+    /**
+     * Clean up a lock file from disk and git state after failure
+     */
+    cleanupLockFile(lockFilePath, cwd) {
+        try {
+            fs.removeSync(lockFilePath);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            this.gitOps.remove(lockFilePath, cwd);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    /**
+     * Output failure message in JSON or human-readable format, then exit 1
+     */
+    fail(flags, message) {
+        if (flags.json) {
+            this.log(JSON.stringify({ error: message, story: flags.story, success: false }));
+            this.exit(1);
+        }
+        this.error(message, { exit: 1 });
+    }
+    /**
+     * Get current git branch name
+     */
+    getCurrentBranch(cwd) {
+        try {
+            return execSync('git branch --show-current', { cwd, encoding: 'utf8' }).trim() || 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    initServices() {
+        this.logger = createLogger({ namespace: 'commands:lock:acquire' });
+        const fileManager = new FileManager(this.logger);
+        const globMatcher = new GlobMatcher(fileManager, this.logger);
+        this.lockService = new LockService(fileManager, globMatcher, this.logger);
+        this.gitOps = new GitOps();
+        this.pushConflictHandler = new PushConflictHandler(this.gitOps);
+    }
+    /**
+     * Parse duration string (e.g., '2h', '30m', '1d') to milliseconds
+     */
+    parseDuration(duration) {
+        const match = /^(\d+)(h|m|d|s)$/.exec(duration);
+        if (!match)
+            return null;
+        const [, value, unit] = match;
+        return Number.parseInt(value, 10) * DURATION_MULTIPLIERS[unit];
+    }
+    /**
+     * Output success message in JSON or human-readable format
+     */
+    succeed(flags) {
+        if (flags.json) {
+            this.log(JSON.stringify({
+                agent: flags.agent,
+                session: flags.session,
+                story: flags.story,
+                success: true,
+                timestamp: new Date().toISOString(),
+            }));
+        }
+        else {
+            this.log('✓ Lock acquired: ' + flags.story + ' (agent: ' + flags.agent + ', session: ' + flags.session + ')');
+        }
+    }
+}

package/dist/commands/lock/cleanup.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Lock Cleanup Command
+ *
+ * Finds and removes all stale story locks in a single git commit+push.
+ * Supports dry-run mode, custom stale thresholds, and JSON output.
+ *
+ * Flow: parse flags → git pull → find stale locks → (dry-run | delete+commit+push) → output
+ *
+ * @example
+ * ```bash
+ * bmad-workflow lock cleanup
+ * bmad-workflow lock cleanup --stale-threshold 30m --dry-run
+ * bmad-workflow lock cleanup --json
+ * ```
+ */
+import { Command } from '@oclif/core';
+export default class LockCleanupCommand extends Command {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'stale-threshold': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private cleanupService;
+    private gitOps;
+    private lockService;
+    private logger;
+    run(): Promise<void>;
+    private initServices;
+    /**
+     * Check if a lock's started_at is older than threshold
+     */
+    private isOverThreshold;
+}

package/dist/commands/lock/cleanup.js

@@ -0,0 +1,148 @@
+/**
+ * Lock Cleanup Command
+ *
+ * Finds and removes all stale story locks in a single git commit+push.
+ * Supports dry-run mode, custom stale thresholds, and JSON output.
+ *
+ * Flow: parse flags → git pull → find stale locks → (dry-run | delete+commit+push) → output
+ *
+ * @example
+ * ```bash
+ * bmad-workflow lock cleanup
+ * bmad-workflow lock cleanup --stale-threshold 30m --dry-run
+ * bmad-workflow lock cleanup --json
+ * ```
+ */
+import { Command, Flags } from '@oclif/core';
+import { FileManager } from '../../services/file-system/file-manager.js';
+import { GlobMatcher } from '../../services/file-system/glob-matcher.js';
+import { GitOps } from '../../services/git/git-ops.js';
+import { LockCleanupService } from '../../services/lock/lock-cleanup.js';
+import { LockService } from '../../services/lock/lock-service.js';
+import { parseDuration } from '../../utils/duration.js';
+import { createLogger } from '../../utils/logger.js';
+/** Default directory to scan for lock files */
+const STORIES_DIR = 'docs';
+export default class LockCleanupCommand extends Command {
+    static description = 'Remove all stale story locks in a single commit';
+    static examples = [
+        {
+            command: '<%= config.bin %> lock cleanup',
+            description: 'Remove all stale locks (default 2h threshold)',
+        },
+        {
+            command: '<%= config.bin %> lock cleanup --stale-threshold 30m --dry-run',
+            description: 'Preview locks that would be cleaned with 30m threshold',
+        },
+        {
+            command: '<%= config.bin %> lock cleanup --json',
+            description: 'Output cleanup results as JSON',
+        },
+    ];
+    static flags = {
+        'dry-run': Flags.boolean({ description: 'Show what would be cleaned without acting' }),
+        json: Flags.boolean({ description: 'Output as JSON' }),
+        'stale-threshold': Flags.string({
+            default: '2h',
+            description: 'Duration before lock is stale (e.g., 2h, 30m, 1d)',
+        }),
+    };
+    cleanupService;
+    gitOps;
+    lockService;
+    logger;
+    async run() {
+        this.initServices();
+        const { flags } = await this.parse(LockCleanupCommand);
+        // AC 4: Parse stale threshold — exit 1 on invalid format
+        let thresholdMs;
+        try {
+            thresholdMs = parseDuration(flags['stale-threshold']);
+        }
+        catch {
+            const msg = `Invalid duration format: ${flags['stale-threshold']}, expected e.g. 2h, 30m, 1d`;
+            if (flags.json) {
+                this.log(JSON.stringify({ error: msg, removed: 0 }));
+            }
+            this.error(msg, { exit: 1 });
+        }
+        // AC 7: Pull latest before scanning
+        const cwd = process.cwd();
+        try {
+            this.gitOps.pull(cwd);
+        }
+        catch {
+            this.logger.warn('git pull failed — proceeding with local state');
+        }
+        // Find stale locks with metadata for output
+        const allLocks = await this.lockService.list(STORIES_DIR);
+        const staleLocks = allLocks.filter((entry) => entry.isStale || this.isOverThreshold(entry.lock.started_at, thresholdMs));
+        // Also check for locks that list() skipped (malformed) — use findStaleLocks for completeness
+        const staleLockPaths = await this.lockService.findStaleLocks(STORIES_DIR, thresholdMs);
+        // Build lock details from the metadata we have
+        const lockDetails = staleLocks.map((entry) => ({
+            agent: entry.lock.agent_name,
+            started_at: entry.lock.started_at,
+            story: entry.storyPath,
+        }));
+        // If findStaleLocks found more than list() (malformed locks), count them
+        const totalStaleCount = Math.max(staleLockPaths.length, staleLocks.length);
+        // AC 1, 5, 6: No stale locks
+        if (totalStaleCount === 0) {
+            if (flags.json) {
+                if (flags['dry-run']) {
+                    this.log(JSON.stringify({ dry_run: true, locks: [], would_remove: 0 }));
+                }
+                else {
+                    this.log(JSON.stringify({ locks: [], removed: 0 }));
+                }
+            }
+            else {
+                this.log('No stale locks found');
+            }
+            return;
+        }
+        // AC 5, 9: Dry-run mode — list but don't act
+        if (flags['dry-run']) {
+            if (flags.json) {
+                this.log(JSON.stringify({ dry_run: true, locks: lockDetails, would_remove: totalStaleCount }));
+            }
+            else {
+                this.log(`Would remove ${totalStaleCount} stale lock(s):`);
+                for (const detail of lockDetails) {
+                    this.log(`  ${detail.story} — agent: ${detail.agent}, started_at: ${detail.started_at}`);
+                }
+            }
+            return;
+        }
+        // AC 2: Batch cleanup with single commit+push via LockCleanupService
+        const result = await this.cleanupService.cleanupStaleLocks(thresholdMs, cwd);
+        // AC 8: Output
+        if (flags.json) {
+            this.log(JSON.stringify({ locks: lockDetails, removed: result.cleaned }));
+        }
+        else {
+            this.log(`✓ Cleaned up ${result.cleaned} stale lock(s):`);
+            for (const detail of lockDetails) {
+                this.log(`  ${detail.story} — agent: ${detail.agent}`);
+            }
+        }
+    }
+    initServices() {
+        this.logger = createLogger({ namespace: 'commands:lock:cleanup' });
+        const fileManager = new FileManager(this.logger);
+        const globMatcher = new GlobMatcher(fileManager, this.logger);
+        this.lockService = new LockService(fileManager, globMatcher, this.logger);
+        this.gitOps = new GitOps();
+        this.cleanupService = new LockCleanupService(this.lockService, this.gitOps, this.logger, STORIES_DIR);
+    }
+    /**
+     * Check if a lock's started_at is older than threshold
+     */
+    isOverThreshold(startedAt, thresholdMs) {
+        const ts = new Date(startedAt).getTime();
+        if (Number.isNaN(ts))
+            return true;
+        return ts + thresholdMs < Date.now();
+    }
+}

package/dist/commands/lock/list.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lock List Command
+ *
+ * Lists all current locks across all story directories.
+ * Displays results in a table or JSON format.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow lock list
+ * bmad-workflow lock list --stale-only
+ * bmad-workflow lock list --json
+ * ```
+ */
+import { Command } from '@oclif/core';
+export default class LockListCommand extends Command {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'stale-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    private lockService;
+    private logger;
+    private pathResolver;
+    run(): Promise<void>;
+    private initServices;
+    private truncate;
+}

package/dist/commands/lock/list.js

@@ -0,0 +1,123 @@
+/**
+ * Lock List Command
+ *
+ * Lists all current locks across all story directories.
+ * Displays results in a table or JSON format.
+ *
+ * @example
+ * ```bash
+ * bmad-workflow lock list
+ * bmad-workflow lock list --stale-only
+ * bmad-workflow lock list --json
+ * ```
+ */
+import { execSync } from 'node:child_process';
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { FileManager } from '../../services/file-system/file-manager.js';
+import { GlobMatcher } from '../../services/file-system/glob-matcher.js';
+import { PathResolver } from '../../services/file-system/path-resolver.js';
+import { LockService } from '../../services/lock/lock-service.js';
+import { createLogger } from '../../utils/logger.js';
+export default class LockListCommand extends Command {
+    static description = 'List all current story locks';
+    static examples = [
+        {
+            command: '<%= config.bin %> lock list',
+            description: 'List all locks across story directories',
+        },
+        {
+            command: '<%= config.bin %> lock list --stale-only',
+            description: 'Show only stale locks',
+        },
+        {
+            command: '<%= config.bin %> lock list --json',
+            description: 'Output all locks as JSON',
+        },
+    ];
+    static flags = {
+        json: Flags.boolean({ description: 'Output as JSON' }),
+        'stale-only': Flags.boolean({ description: 'Show only stale locks' }),
+    };
+    lockService;
+    logger;
+    pathResolver;
+    async run() {
+        this.initServices();
+        const { flags } = await this.parse(LockListCommand);
+        // AC 9: Pull latest before reading lock state
+        try {
+            execSync('git pull --ff-only', { cwd: process.cwd(), stdio: 'pipe' });
+        }
+        catch {
+            this.logger.warn('git pull failed — proceeding with local state');
+        }
+        // Get all story directories
+        const allDirs = this.pathResolver.getAllStoryDirs();
+        // Get all locks with stale status
+        let locks = await this.lockService.listLocks(allDirs);
+        // AC 6: Filter stale-only if requested
+        if (flags['stale-only']) {
+            locks = locks.filter((l) => l.stale);
+        }
+        // AC 8: No locks found
+        if (locks.length === 0) {
+            if (flags.json) {
+                this.log(JSON.stringify({ locks: [] }, null, 2));
+            }
+            else {
+                this.log(chalk.yellow('No locks found'));
+            }
+            return;
+        }
+        // AC 7: JSON output
+        if (flags.json) {
+            const output = {
+                locks: locks.map((l) => ({
+                    agent: l.agent_name,
+                    branch: l.branch,
+                    session: l.agent_session_id,
+                    stale: l.stale,
+                    started_at: l.started_at,
+                    story: l.story_file,
+                })),
+            };
+            this.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        // AC 5: Table output
+        this.log('');
+        this.log(chalk.cyan.bold('Story'.padEnd(40)) +
+            chalk.cyan.bold('Agent'.padEnd(20)) +
+            chalk.cyan.bold('Session'.padEnd(38)) +
+            chalk.cyan.bold('Started At'.padEnd(24)) +
+            chalk.cyan.bold('Branch'.padEnd(20)) +
+            chalk.cyan.bold('Stale'));
+        this.log(chalk.gray('─'.repeat(150)));
+        for (const lock of locks) {
+            const staleLabel = lock.stale ? chalk.red('yes') : chalk.green('no');
+            const story = this.truncate(lock.story_file, 38);
+            const agent = this.truncate(lock.agent_name, 18);
+            const branch = this.truncate(lock.branch, 18);
+            this.log(story.padEnd(40) +
+                agent.padEnd(20) +
+                lock.agent_session_id.padEnd(38) +
+                lock.started_at.padEnd(24) +
+                branch.padEnd(20) +
+                staleLabel);
+        }
+        this.log('');
+        this.log(chalk.white(`Found ${locks.length} lock(s)`));
+        this.log('');
+    }
+    initServices() {
+        this.logger = createLogger({ namespace: 'commands:lock:list' });
+        const fileManager = new FileManager(this.logger);
+        const globMatcher = new GlobMatcher(fileManager, this.logger);
+        this.pathResolver = new PathResolver(fileManager, this.logger);
+        this.lockService = new LockService(fileManager, globMatcher, this.logger);
+    }
+    truncate(str, maxLength) {
+        return str.length > maxLength ? str.slice(0, maxLength - 3) + '...' : str;
+    }
+}

package/dist/commands/lock/release.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Lock Release Command
+ *
+ * Releases an existing lock on a story file by deleting the `.lock` file,
+ * committing the removal, and pushing to remote.
+ *
+ * Flow: git pull → validate lock exists → delete .lock → git add+commit+push
+ *
+ * @example
+ * ```bash
+ * bmad-workflow lock release --story docs/qa/stories/X.md
+ * ```
+ */
+import { Command } from '@oclif/core';
+export default class LockReleaseCommand extends Command {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        story: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private gitOps;
+    private lockService;
+    private logger;
+    run(): Promise<void>;
+    /**
+     * Output failure message in JSON or human-readable format, then exit 1
+     */
+    private fail;
+    private initServices;
+    /**
+     * Output idempotent success when lock was already released by another agent (AC 4)
+     */
+    private succeedAlreadyReleased;
+    /**
+     * Output success message in JSON or human-readable format
+     */
+    private succeed;
+}