@hyperdrive.bot/bmad-workflow 1.0.21 → 1.0.23

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

@@ -0,0 +1,234 @@
+/**
+ * AssetResolver Service
+ *
+ * Resolves agents, templates, and config through a three-level chain:
+ * 1. CLI flags (highest priority)
+ * 2. .bmad-workflow.yaml config file
+ * 3. Bundled defaults (shipped inside npm package)
+ *
+ * This enables the CLI to work both standalone (zero-config) and
+ * in existing BMAD setups with .bmad-core/.
+ */
+import fs from 'fs-extra';
+import { load as yamlLoad } from 'js-yaml';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDuration } from '../../utils/duration.js';
+/**
+ * Valid AI provider names
+ */
+const VALID_PROVIDERS = ['claude', 'gemini', 'opencode'];
+/**
+ * AssetResolver resolves asset paths using a three-level resolution chain.
+ */
+export class AssetResolver {
+    bundledPath;
+    config;
+    flags;
+    /**
+     * Create a new AssetResolver
+     *
+     * @param flags - CLI flag overrides for agent selection
+     */
+    constructor(flags = {}) {
+        this.flags = flags;
+        this.bundledPath = this.computeBundledPath();
+        this.config = this.loadConfigFile();
+    }
+    /**
+     * Resolve an agent file path.
+     *
+     * Resolution order: CLI flag → config file → bundled default
+     *
+     * @param role - Agent role (dev, sm, qa)
+     * @param flagValue - Optional CLI flag override
+     * @returns Resolved asset with path and source
+     */
+    resolveAgent(role, flagValue) {
+        // Level 1: CLI flag
+        const flag = flagValue || this.getFlagForRole(role);
+        if (flag) {
+            return { path: this.resolveAgentValue(flag), source: 'flag' };
+        }
+        // Level 2: Config file
+        const configKey = `${role}_agent`;
+        const configValue = this.config?.[configKey];
+        if (configValue) {
+            return { path: this.resolveAgentValue(configValue), source: 'config' };
+        }
+        // Level 3: Bundled default
+        return {
+            path: join(this.bundledPath, 'agents', `${role}.md`),
+            source: 'bundled',
+        };
+    }
+    /**
+     * Resolve a template file path.
+     *
+     * Checks bmad_path config directory first, falls back to bundled.
+     *
+     * @param name - Template filename (e.g., 'epic-tmpl.yaml')
+     * @returns Resolved asset with path and source
+     */
+    resolveTemplate(name) {
+        // Config bmad_path override (resolved relative to project root)
+        if (this.config?.bmad_path) {
+            const local = join(process.cwd(), this.config.bmad_path, 'templates', name);
+            if (fs.existsSync(local)) {
+                return { path: local, source: 'config' };
+            }
+        }
+        // Bundled default
+        return {
+            path: join(this.bundledPath, 'templates', name),
+            source: 'bundled',
+        };
+    }
+    /**
+     * Resolve the config file path.
+     *
+     * Returns the absolute path to the bundled default-config.yaml.
+     * Callers (PathResolver) decide whether to prefer local .bmad-core/ over this.
+     *
+     * @returns Absolute path to bundled config file
+     */
+    resolveConfig() {
+        return join(this.bundledPath, 'config', 'default-config.yaml');
+    }
+    /**
+     * Extract execution defaults from the loaded config file.
+     *
+     * Parses and validates: parallel, timeout, provider, model, qa_enabled, pipeline.
+     * Invalid values are silently ignored (field omitted from result).
+     *
+     * @returns Parsed execution defaults, or empty object if no config file
+     */
+    getExecutionDefaults() {
+        if (!this.config)
+            return {};
+        const defaults = {};
+        // parallel — must be positive integer
+        if (this.config.parallel !== undefined) {
+            const val = Number(this.config.parallel);
+            if (Number.isInteger(val) && val > 0) {
+                defaults.parallel = val;
+            }
+            else {
+                console.warn(`[bmad-workflow] Ignoring invalid config value parallel: ${this.config.parallel} (expected positive integer)`);
+            }
+        }
+        // timeout — human-readable string or number, converted to ms
+        if (this.config.timeout !== undefined) {
+            try {
+                defaults.timeout = parseDuration(this.config.timeout);
+            }
+            catch {
+                console.warn(`[bmad-workflow] Ignoring invalid config value timeout: ${this.config.timeout}`);
+            }
+        }
+        // provider — must be one of valid providers
+        if (this.config.provider !== undefined) {
+            const val = String(this.config.provider);
+            if (VALID_PROVIDERS.includes(val)) {
+                defaults.provider = val;
+            }
+            else {
+                console.warn(`[bmad-workflow] Ignoring invalid config value provider: ${val} (expected: ${VALID_PROVIDERS.join(', ')})`);
+            }
+        }
+        // model — any non-empty string
+        if (this.config.model !== undefined && typeof this.config.model === 'string' && this.config.model.trim()) {
+            defaults.model = this.config.model.trim();
+        }
+        // qa_enabled — must be boolean
+        if (this.config.qa_enabled !== undefined) {
+            if (typeof this.config.qa_enabled === 'boolean') {
+                defaults.qa_enabled = this.config.qa_enabled;
+            }
+            else {
+                console.warn(`[bmad-workflow] Ignoring invalid config value qa_enabled: ${this.config.qa_enabled} (expected boolean)`);
+            }
+        }
+        // pipeline — must be boolean
+        if (this.config.pipeline !== undefined) {
+            if (typeof this.config.pipeline === 'boolean') {
+                defaults.pipeline = this.config.pipeline;
+            }
+            else {
+                console.warn(`[bmad-workflow] Ignoring invalid config value pipeline: ${this.config.pipeline} (expected boolean)`);
+            }
+        }
+        return defaults;
+    }
+    /**
+     * Compute the bundled assets root path.
+     *
+     * From compiled dist/services/file-system/asset-resolver.js,
+     * the assets directory is three levels up: ../../.. → <pkg>/assets/
+     *
+     * @returns Absolute path to bundled assets directory
+     */
+    computeBundledPath() {
+        // Support both ESM (__dirname equivalent) and compiled contexts
+        try {
+            const currentFile = fileURLToPath(import.meta.url);
+            const currentDir = dirname(currentFile);
+            return join(currentDir, '..', '..', '..', 'assets');
+        }
+        catch {
+            // Fallback for environments where import.meta.url is not available
+            return join(__dirname, '..', '..', 'assets');
+        }
+    }
+    /**
+     * Get CLI flag value for a given role.
+     */
+    getFlagForRole(role) {
+        const map = {
+            dev: this.flags.devAgent,
+            qa: this.flags.qaAgent,
+            sm: this.flags.smAgent,
+        };
+        return map[role];
+    }
+    /**
+     * Load .bmad-workflow.yaml from project root (if exists).
+     *
+     * @returns Parsed config or null if file absent
+     */
+    loadConfigFile() {
+        const configPath = join(process.cwd(), '.bmad-workflow.yaml');
+        if (!fs.existsSync(configPath))
+            return null;
+        try {
+            const content = fs.readFileSync(configPath, 'utf8');
+            return yamlLoad(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Resolve an agent value — could be a built-in name or a file path.
+     *
+     * Built-in names (no path separators, no .md extension) map to bundled agents.
+     * File paths are resolved relative to project root.
+     *
+     * @param value - Agent name or file path
+     * @returns Absolute path to agent file
+     */
+    resolveAgentValue(value) {
+        // Built-in name (no path separators, no extension)
+        if (!value.includes('/') && !value.endsWith('.md')) {
+            // Check bmad_path first (resolved relative to project root)
+            if (this.config?.bmad_path) {
+                const local = join(process.cwd(), this.config.bmad_path, 'agents', `${value}.md`);
+                if (fs.existsSync(local))
+                    return local;
+            }
+            return join(this.bundledPath, 'agents', `${value}.md`);
+        }
+        // File path — resolve relative to project root
+        return resolve(value);
+    }
+}

package/dist/services/file-system/file-manager.d.ts

@@ -37,6 +37,19 @@ export declare class FileManager {
      * await fileManager.createDirectory('docs/epics')
      */
     createDirectory(path: string): Promise<void>;
+    /**
+     * Copy a file from source to destination
+     *
+     * Creates parent directories if they don't exist.
+     * Overwrites destination file if it exists.
+     *
+     * @param source - Source file path
+     * @param dest - Destination file path
+     * @throws {FileSystemError} If file cannot be copied (source not found, permission denied, etc.)
+     * @example
+     * await fileManager.copyFile('assets/agents/dev.md', '.bmad-core/agents/dev.md')
+     */
+    copyFile(source: string, dest: string): Promise<void>;
     /**
      * Check if a file or directory exists
      *

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

@@ -56,6 +56,38 @@ export class FileManager {
             });
         }
     }
+    /**
+     * Copy a file from source to destination
+     *
+     * Creates parent directories if they don't exist.
+     * Overwrites destination file if it exists.
+     *
+     * @param source - Source file path
+     * @param dest - Destination file path
+     * @throws {FileSystemError} If file cannot be copied (source not found, permission denied, etc.)
+     * @example
+     * await fileManager.copyFile('assets/agents/dev.md', '.bmad-core/agents/dev.md')
+     */
+    async copyFile(source, dest) {
+        this.logger.info('Copying file from %s to %s', source, dest);
+        try {
+            // Ensure destination directory exists
+            await fs.ensureDir(dirname(dest));
+            // Copy file
+            await fs.copy(source, dest, { overwrite: true });
+            this.logger.info('File copied successfully from %s to %s', source, dest);
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error('Error copying file from %s to %s: %O', source, dest, err);
+            throw new FileSystemError(`Failed to copy file from ${source} to ${dest}: ${err.message}`, {
+                dest,
+                operation: 'copyFile',
+                originalError: err.message,
+                source,
+            });
+        }
+    }
     /**
      * Check if a file or directory exists
      *

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

@@ -6,6 +6,7 @@
  */
 import type pino from 'pino';
 import type { ReviewConfig } from '../validation/config-validator.js';
+import { AssetResolver } from './asset-resolver.js';
 import { FileManager } from './file-manager.js';
 /**
  * PathResolver service for resolving and validating file paths
@@ -15,10 +16,18 @@ import { FileManager } from './file-manager.js';
  * are resolved relative to the project root and validated for existence.
  */
 export declare class PathResolver {
+    /**
+     * AssetResolver for bundled asset fallback
+     */
+    private readonly assetResolver;
     /**
      * Cached configuration to avoid repeated file reads
      */
     private cachedConfig;
+    /**
+     * Cached path to the configuration file (local or bundled)
+     */
+    private cachedConfigPath;
     /**
      * Cached resolved paths
      */
@@ -40,12 +49,13 @@ export declare class PathResolver {
      *
      * @param fileManager - FileManager instance for file operations
      * @param logger - Pino logger instance for logging path operations
+     * @param assetResolver - Optional AssetResolver instance (DI for testability)
      * @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);
+    constructor(fileManager: FileManager, logger: pino.Logger, assetResolver?: AssetResolver);
     /**
      * Get all story directories for existence checks
      *
@@ -170,6 +180,17 @@ export declare class PathResolver {
      * @throws {ConfigurationError} If configuration structure is invalid
      */
     private loadConfig;
+    /**
+     * Read, parse, and validate a config file at the given path.
+     *
+     * Sets cachedConfig and cachedConfigPath on success.
+     * Applies hardcoded defaults for missing fields.
+     *
+     * @param configPath - Absolute path to YAML config file
+     * @returns Parsed and validated configuration
+     * @throws {ConfigurationError} If configuration structure is invalid
+     */
+    private readAndParseConfig;
     /**
      * Validate configuration structure
      *

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

@@ -8,6 +8,7 @@ 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';
+import { AssetResolver } from './asset-resolver.js';
 /**
  * Configuration file path relative to project root
  */
@@ -20,10 +21,18 @@ const CONFIG_FILE_PATH = '.bmad-core/core-config.yaml';
  * are resolved relative to the project root and validated for existence.
  */
 export class PathResolver {
+    /**
+     * AssetResolver for bundled asset fallback
+     */
+    assetResolver;
     /**
      * Cached configuration to avoid repeated file reads
      */
     cachedConfig = null;
+    /**
+     * Cached path to the configuration file (local or bundled)
+     */
+    cachedConfigPath = null;
     /**
      * Cached resolved paths
      */
@@ -45,14 +54,16 @@ export class PathResolver {
      *
      * @param fileManager - FileManager instance for file operations
      * @param logger - Pino logger instance for logging path operations
+     * @param assetResolver - Optional AssetResolver instance (DI for testability)
      * @example
      * const logger = createLogger({ namespace: 'services:path-resolver' })
      * const fileManager = new FileManager(logger)
      * const pathResolver = new PathResolver(fileManager, logger)
      */
-    constructor(fileManager, logger) {
+    constructor(fileManager, logger, assetResolver) {
         this.fileManager = fileManager;
         this.logger = logger;
+        this.assetResolver = assetResolver || new AssetResolver({});
         this.projectRoot = process.cwd();
         this.logger.debug('PathResolver initialized with project root: %s', this.projectRoot);
     }
@@ -87,7 +98,11 @@ export class PathResolver {
      * // Returns: '/path/to/project/.bmad-core/core-config.yaml'
      */
     getConfigPath() {
-        const configPath = resolve(this.projectRoot, CONFIG_FILE_PATH);
+        // Trigger config load if not yet loaded (populates cachedConfigPath)
+        if (!this.cachedConfigPath) {
+            this.loadConfig();
+        }
+        const configPath = this.cachedConfigPath;
         this.logger.debug('Getting config path: %s', configPath);
         return configPath;
     }
@@ -274,23 +289,35 @@ export class PathResolver {
         }
         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',
-            });
+            // Fallback to bundled default config via AssetResolver
+            const bundledPath = this.assetResolver.resolveConfig();
+            this.logger.info('No local config found, falling back to bundled default: %s', bundledPath);
+            return this.readAndParseConfig(bundledPath);
         }
         this.logger.info('Loading configuration from: %s', configPath);
+        return this.readAndParseConfig(configPath);
+    }
+    /**
+     * Read, parse, and validate a config file at the given path.
+     *
+     * Sets cachedConfig and cachedConfigPath on success.
+     * Applies hardcoded defaults for missing fields.
+     *
+     * @param configPath - Absolute path to YAML config file
+     * @returns Parsed and validated configuration
+     * @throws {ConfigurationError} If configuration structure is invalid
+     */
+    readAndParseConfig(configPath) {
         try {
             // Read configuration file
             const content = fs.readFileSync(configPath, 'utf8');
-            this.logger.debug('Configuration file read successfully');
+            this.logger.debug('Configuration file read successfully from: %s', configPath);
             // Parse YAML
             const config = yamlLoad(content);
             // Validate required fields
             this.validateConfig(config);
             this.cachedConfig = config;
+            this.cachedConfigPath = configPath;
             this.logger.info('Configuration loaded and validated successfully');
             return config;
         }

package/dist/services/orchestration/dependency-graph-executor.js

@@ -308,6 +308,7 @@ Use the file at the path above to document:
             // Execute agent
             const result = await this.agentRunner.runAgent(fullPrompt, {
                 agentType,
+                cwd: this.cwd,
                 model: this.model,
                 references: task.targetFiles, // Pass target files as references
                 timeout: task.estimatedMinutes * 60 * 1000 * 1.5, // 1.5x estimated time as buffer

package/dist/services/orchestration/workflow-orchestrator.d.ts

@@ -47,6 +47,7 @@ import type pino from 'pino';
 import type { InputDetectionResult, WorkflowCallbacks, WorkflowConfig, WorkflowResult } from '../../models/index.js';
 import type { AIProviderRunner } from '../agents/agent-runner.js';
 import type { WorkflowLogger } from '../logging/workflow-logger.js';
+import { AssetResolver } from '../file-system/asset-resolver.js';
 import { FileManager } from '../file-system/file-manager.js';
 import { PathResolver } from '../file-system/path-resolver.js';
 import { EpicParser } from '../parsers/epic-parser.js';
@@ -79,6 +80,8 @@ export interface InputDetector {
 export interface WorkflowOrchestratorConfig {
     /** Service to execute AI agents (Claude or Gemini) */
     agentRunner: AIProviderRunner;
+    /** Optional AssetResolver for three-level path resolution (CLI flag → config → bundled) */
+    assetResolver?: AssetResolver;
     /** Service to handle parallel batch processing */
     batchProcessor: BatchProcessor;
     /** Service to parse epic files and extract stories */
@@ -147,6 +150,7 @@ export interface StoryPromptOptions {
  */
 export declare class WorkflowOrchestrator {
     private readonly agentRunner;
+    private readonly assetResolver;
     private readonly batchProcessor;
     private readonly callbacks?;
     private readonly epicParser;
@@ -730,6 +734,13 @@ export declare class WorkflowOrchestrator {
      * @private
      */
     private sleep;
+    /**
+     * Parse the `### Dev Context` section from a story file's content.
+     *
+     * Returns sidecar reference paths and an optional deploy target string.
+     * If the section is missing or empty, returns empty arrays / undefined (backward compatible).
+     */
+    private parseDevContext;
     /**
      * Update story status in file
      *