@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/services/mcp/mcp-credential-manager.js

@@ -0,0 +1,124 @@
+/**
+ * MCP Credential Manager
+ *
+ * Manages API key credentials for MCP servers.
+ * Resolution chain: environment variable > stored credential file.
+ * Stores credentials at ~/.bmad/credentials/.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import yaml from 'js-yaml';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'services:mcp:credential-manager' });
+const CREDENTIALS_DIR = join(homedir(), '.bmad', 'credentials');
+const CREDENTIALS_FILE = join(CREDENTIALS_DIR, 'mcp-keys.yaml');
+export class McpCredentialManager {
+    credentialsPath;
+    store;
+    constructor(credentialsPath) {
+        this.credentialsPath = credentialsPath || CREDENTIALS_FILE;
+        this.store = this.loadStore();
+    }
+    /**
+     * Get a credential value from the stored file (not env vars).
+     *
+     * @returns The stored credential value, or null if not found
+     */
+    get(key) {
+        const value = this.store.keys[key];
+        if (value) {
+            logger.debug('Credential %s found in store', key);
+            return value;
+        }
+        logger.debug('Credential %s not found in store', key);
+        return null;
+    }
+    /**
+     * List all known credential entries with their configuration status
+     */
+    list() {
+        const allKeys = Object.keys(this.store.keys);
+        const knownKeys = new Set(['EXA_API_KEY', 'APIFY_TOKEN', ...allKeys]);
+        return [...knownKeys].map((key) => ({
+            configured: this.resolve(key) !== null,
+            key,
+            requiredByPreset: false,
+        }));
+    }
+    /**
+     * Resolve a credential key value.
+     * Resolution chain: environment variable > stored credential file.
+     *
+     * @returns The credential value, or null if not found anywhere
+     */
+    resolve(key) {
+        // 1. Check environment variable
+        const envValue = process.env[key];
+        if (envValue) {
+            logger.debug('Credential %s resolved from environment', key);
+            return envValue;
+        }
+        // 2. Check stored credentials
+        const storedValue = this.store.keys[key];
+        if (storedValue) {
+            logger.debug('Credential %s resolved from stored credentials', key);
+            return storedValue;
+        }
+        logger.debug('Credential %s not found', key);
+        return null;
+    }
+    /**
+     * Remove a credential from the store.
+     *
+     * @returns true if the key was found and removed, false if not found
+     */
+    remove(key) {
+        if (this.store.keys[key] !== undefined) {
+            logger.info('Removing credential: %s', key);
+            delete this.store.keys[key];
+            this.saveStore();
+            return true;
+        }
+        logger.debug('Credential %s not found for removal', key);
+        return false;
+    }
+    /**
+     * Store a credential key-value pair
+     */
+    set(key, value) {
+        logger.info('Storing credential: %s', key);
+        this.store.keys[key] = value;
+        this.saveStore();
+    }
+    /**
+     * Load the credential store from disk
+     */
+    loadStore() {
+        try {
+            if (existsSync(this.credentialsPath)) {
+                const content = readFileSync(this.credentialsPath, 'utf8');
+                const parsed = yaml.load(content);
+                if (parsed && typeof parsed === 'object' && parsed.keys) {
+                    return parsed;
+                }
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to load credentials from %s: %s', this.credentialsPath, error.message);
+        }
+        return { keys: {} };
+    }
+    /**
+     * Save the credential store to disk
+     */
+    saveStore() {
+        const dir = dirname(this.credentialsPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const content = yaml.dump(this.store, { sortKeys: true });
+        writeFileSync(this.credentialsPath, content, { encoding: 'utf8', mode: 0o600 });
+        logger.info('Credentials saved to %s', this.credentialsPath);
+    }
+}

package/dist/services/mcp/mcp-health-checker.d.ts

@@ -0,0 +1,56 @@
+/**
+ * MCP Health Checker Service
+ *
+ * Verifies gateway availability and individual MCP server health using
+ * template-defined check methods (tool_call or http) with configurable timeouts.
+ *
+ * Consumed by: mcp status command (Story 2.1), mcp credential validate (Story 2.3),
+ * and McpContextInjector (Epic 3, Story 3.1).
+ */
+import type { GatewayHealthStatus, HealthReport, IHealthChecker } from '../../mcp/types.js';
+import type { McpServerWithHealthCheck, ServerHealthStatus } from './types/health-types.js';
+/**
+ * Interface for the config manager dependency.
+ * Uses McpServerWithHealthCheck (extended type with healthCheck field)
+ * instead of the base McpServerConfig.
+ */
+export interface IHealthCheckerConfigManager {
+    getEnabledServers(): McpServerWithHealthCheck[];
+    getGatewayUrl(): string;
+}
+/**
+ * McpHealthChecker verifies gateway and individual MCP server health.
+ *
+ * - Gateway is checked first; if offline, all servers are reported as offline
+ * - Per-server checks run in parallel via Promise.allSettled
+ * - Supports tool_call and http check strategies per server template config
+ */
+export declare class McpHealthChecker implements IHealthChecker {
+    private readonly configManager;
+    private readonly gatewayUrl;
+    constructor(configManager: IHealthCheckerConfigManager);
+    /**
+     * Check gateway health by hitting its /health endpoint
+     *
+     * @returns Gateway health status with latency measurement
+     */
+    checkGateway(): Promise<GatewayHealthStatus>;
+    /**
+     * Check an individual MCP server's health using its template-configured method
+     *
+     * @param server - Server configuration with health check settings
+     * @returns Server health result with status, latency, and optional error
+     */
+    checkServer(server: McpServerWithHealthCheck): Promise<ServerHealthStatus>;
+    /**
+     * Check health of the gateway and all configured servers.
+     *
+     * If the gateway is offline, all servers are immediately reported as offline
+     * without making individual server health checks.
+     *
+     * Enabled servers are checked in parallel via Promise.allSettled.
+     *
+     * @returns Complete health report for gateway and all servers
+     */
+    checkAll(): Promise<HealthReport>;
+}

package/dist/services/mcp/mcp-health-checker.js

@@ -0,0 +1,162 @@
+/**
+ * MCP Health Checker Service
+ *
+ * Verifies gateway availability and individual MCP server health using
+ * template-defined check methods (tool_call or http) with configurable timeouts.
+ *
+ * Consumed by: mcp status command (Story 2.1), mcp credential validate (Story 2.3),
+ * and McpContextInjector (Epic 3, Story 3.1).
+ */
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'services:mcp:health-checker' });
+/** Gateway health check timeout in milliseconds */
+const GATEWAY_TIMEOUT_MS = 10_000;
+/**
+ * McpHealthChecker verifies gateway and individual MCP server health.
+ *
+ * - Gateway is checked first; if offline, all servers are reported as offline
+ * - Per-server checks run in parallel via Promise.allSettled
+ * - Supports tool_call and http check strategies per server template config
+ */
+export class McpHealthChecker {
+    configManager;
+    gatewayUrl;
+    constructor(configManager) {
+        this.configManager = configManager;
+        this.gatewayUrl = configManager.getGatewayUrl();
+        logger.debug('McpHealthChecker initialized with gateway: %s', this.gatewayUrl);
+    }
+    /**
+     * Check gateway health by hitting its /health endpoint
+     *
+     * @returns Gateway health status with latency measurement
+     */
+    async checkGateway() {
+        const url = `${this.gatewayUrl}/health`;
+        logger.debug('Checking gateway health at %s', url);
+        const start = Date.now();
+        try {
+            const response = await fetch(url, { signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS) });
+            const latency = Date.now() - start;
+            if (response.ok) {
+                logger.debug('Gateway is healthy (latency: %dms)', latency);
+                return { status: 'healthy', latency, url: this.gatewayUrl };
+            }
+            logger.warn('Gateway returned non-ok status: %d', response.status);
+            return { status: 'unhealthy', latency, url: this.gatewayUrl };
+        }
+        catch (error) {
+            logger.warn('Gateway health check failed: %s', error.message);
+            return { status: 'offline', latency: null, url: this.gatewayUrl };
+        }
+    }
+    /**
+     * Check an individual MCP server's health using its template-configured method
+     *
+     * @param server - Server configuration with health check settings
+     * @returns Server health result with status, latency, and optional error
+     */
+    async checkServer(server) {
+        const { healthCheck, name } = server;
+        logger.debug('Checking server "%s" via %s method (timeout: %dms)', name, healthCheck.method, healthCheck.timeout);
+        const start = Date.now();
+        try {
+            let response;
+            if (healthCheck.method === 'tool_call') {
+                response = await fetch(this.gatewayUrl, {
+                    body: JSON.stringify({
+                        method: 'tools/call',
+                        params: { name: healthCheck.command },
+                    }),
+                    headers: { 'Content-Type': 'application/json' },
+                    method: 'POST',
+                    signal: AbortSignal.timeout(healthCheck.timeout),
+                });
+            }
+            else {
+                // http method
+                response = await fetch(healthCheck.url, {
+                    signal: AbortSignal.timeout(healthCheck.timeout),
+                });
+            }
+            const latency = Date.now() - start;
+            if (response.ok) {
+                logger.debug('Server "%s" is healthy (latency: %dms)', name, latency);
+                return { name, status: 'healthy', latency, error: null, useCase: server.useCase };
+            }
+            const errorMsg = `HTTP ${response.status}`;
+            logger.warn('Server "%s" returned non-ok: %s', name, errorMsg);
+            return { name, status: 'unhealthy', latency, error: errorMsg, useCase: server.useCase };
+        }
+        catch (error) {
+            const err = error;
+            if (err.name === 'AbortError' || err.name === 'TimeoutError') {
+                const msg = `Health check timed out after ${healthCheck.timeout}ms`;
+                logger.warn('Server "%s" timed out', name);
+                return { name, status: 'offline', latency: null, error: msg, useCase: server.useCase };
+            }
+            logger.warn('Server "%s" health check failed: %s', name, err.message);
+            return { name, status: 'offline', latency: null, error: err.message, useCase: server.useCase };
+        }
+    }
+    /**
+     * Check health of the gateway and all configured servers.
+     *
+     * If the gateway is offline, all servers are immediately reported as offline
+     * without making individual server health checks.
+     *
+     * Enabled servers are checked in parallel via Promise.allSettled.
+     *
+     * @returns Complete health report for gateway and all servers
+     */
+    async checkAll() {
+        logger.info('Starting health check for gateway and all servers');
+        const gateway = await this.checkGateway();
+        // Short-circuit: if gateway is offline, skip individual server checks
+        if (gateway.status === 'offline') {
+            logger.warn('Gateway is offline — marking all servers as offline');
+            const servers = this.configManager.getEnabledServers();
+            return {
+                gateway,
+                servers: servers.map((s) => ({
+                    error: 'Gateway is offline',
+                    latency: null,
+                    name: s.name,
+                    status: 'offline',
+                    useCase: s.useCase,
+                })),
+            };
+        }
+        const allServers = this.configManager.getEnabledServers();
+        // Separate enabled from disabled servers
+        const enabledServers = allServers.filter((s) => s.enabled);
+        const disabledServers = allServers.filter((s) => !s.enabled);
+        // Check enabled servers in parallel
+        const settledResults = await Promise.allSettled(enabledServers.map((s) => this.checkServer(s)));
+        const serverResults = settledResults.map((result, index) => {
+            if (result.status === 'fulfilled') {
+                return result.value;
+            }
+            // Rejected promise — unexpected error
+            const server = enabledServers[index];
+            return {
+                error: result.reason.message,
+                latency: null,
+                name: server.name,
+                status: 'unhealthy',
+                useCase: server.useCase,
+            };
+        });
+        // Add disabled servers to the report
+        const disabledResults = disabledServers.map((s) => ({
+            error: null,
+            latency: null,
+            name: s.name,
+            status: 'disabled',
+            useCase: s.useCase,
+        }));
+        const servers = [...serverResults, ...disabledResults];
+        logger.info('Health check complete: gateway=%s, servers=%d', gateway.status, servers.length);
+        return { gateway, servers };
+    }
+}

package/dist/services/mcp/types/health-types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Health Check Type Definitions
+ *
+ * Types for the MCP health check system, extending the base types from src/mcp/types.ts
+ * with additional configuration types needed by McpHealthChecker.
+ */
+export type { GatewayHealthStatus, HealthReport, HealthStatus, ServerHealthStatus } from '../../../mcp/types.js';
+/**
+ * Health check configuration for an MCP server template
+ */
+export interface HealthCheckConfig {
+    /** Tool name to invoke (for tool_call method) */
+    command?: string;
+    /** Check strategy: invoke a tool via the gateway, or make a direct HTTP request */
+    method: 'http' | 'tool_call';
+    /** Timeout in milliseconds */
+    timeout: number;
+    /** Direct URL to check (for http method) */
+    url?: string;
+}
+/**
+ * Extended MCP server configuration including health check settings.
+ * This represents a server entry as loaded from preset/template YAML files,
+ * with all fields the health checker needs to perform checks.
+ */
+export interface McpServerWithHealthCheck {
+    enabled: boolean;
+    healthCheck: HealthCheckConfig;
+    name: string;
+    useCase?: string;
+}

package/dist/services/mcp/types/health-types.js

@@ -0,0 +1,7 @@
+/**
+ * Health Check Type Definitions
+ *
+ * Types for the MCP health check system, extending the base types from src/mcp/types.ts
+ * with additional configuration types needed by McpHealthChecker.
+ */
+export {};

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

@@ -301,7 +301,7 @@ Use the file at the path above to document:
                 }
             }
             // Map agent type to valid values
-            const validAgentTypes = ['analyst', 'architect', 'dev', 'pm', 'prd-fixer', 'quick-flow-solo-dev', 'sm', 'tea', 'tech-writer', 'ux-designer'];
+            const validAgentTypes = ['analyst', 'architect', 'dev', 'pm', 'prd-fixer', 'qa', 'quick-flow-solo-dev', 'sm', 'tea', 'tech-writer', 'ux-designer'];
             const agentType = validAgentTypes.includes(task.agentType)
                 ? task.agentType
                 : 'dev';

package/dist/services/orchestration/task-decomposition-service.d.ts

@@ -57,7 +57,8 @@ export declare class TaskDecompositionService {
      */
     private parseTaskGraph;
     /**
-     * Validate YAML and ask Claude to fix it if invalid
+     * Validate YAML and ask Claude to fix it if invalid.
+     * Retries up to 2 times with escalating strictness.
      */
     private validateAndFixYaml;
     /**

package/dist/services/orchestration/task-decomposition-service.js

@@ -39,12 +39,31 @@ export class TaskDecompositionService {
         const prompt = this.buildDecompositionPrompt(options, targetFiles, sessionDir);
         this.logger.debug({ promptLength: prompt.length }, 'Built decomposition prompt');
         // Execute Claude agent to generate task graph
+        this.logger.info('Sending goal to AI agent for decomposition (this may take 2-5 minutes)...');
+        const startTime = Date.now();
         const result = await this.agentRunner.runAgent(prompt, {
             agentType: (options.agent ?? 'architect'),
+            cwd: options.cwd,
+            // Disable tools and session persistence for YAML-only generation.
+            // The subprocess doesn't need to read files or create sessions —
+            // it just needs to produce a structured YAML task graph.
+            flags: ['--tools', '""', '--no-session-persistence'],
             model: options.model,
             references: options.contextFiles,
+            systemPrompt: [
+                'You are a structured YAML generator for task decomposition.',
+                'Your ENTIRE response must be valid YAML — nothing else.',
+                'Start directly with "masterPrompt: |" on the first line.',
+                'Do NOT use markdown code fences (```yaml or ```).',
+                'Do NOT write any prose, summaries, commentary, or explanations.',
+                'The YAML must contain a "masterPrompt:" string key and a "tasks:" array.',
+                'Each task in the array must have: id, title, description, estimatedMinutes, dependencies, parallelizable, agentType, prompt, outputFile.',
+                'Failure to output pure YAML will cause a fatal parsing error.',
+            ].join('\n'),
             timeout: options.taskTimeout ?? 600_000, // 10 min default for planning
         });
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+        this.logger.info({ duration: `${elapsed}s`, outputLength: result.output.length }, 'AI agent response received');
         if (!result.success) {
             throw new Error(`Failed to decompose goal: ${result.errors}`);
         }
@@ -472,28 +491,42 @@ ${options.perFile ? '5. **CRITICAL**: Create one task per file (per-file mode is
         }
     }
     /**
-     * Validate YAML and ask Claude to fix it if invalid
+     * Validate YAML and ask Claude to fix it if invalid.
+     * Retries up to 2 times with escalating strictness.
      */
     async validateAndFixYaml(output, options, sessionDir) {
         this.logger.debug('Validating YAML output');
+        // First check: does the output even look like YAML?
+        const trimmed = output.trim();
+        const looksLikeYaml = trimmed.startsWith('masterPrompt:') || trimmed.startsWith('tasks:');
+        if (!looksLikeYaml) {
+            this.logger.warn('Output does not look like YAML (missing masterPrompt: or tasks: at start). Will attempt extraction and fix.');
+        }
         // Try to extract and parse the YAML
         try {
             const yamlContent = this.extractYaml(output);
-            yaml.load(yamlContent); // Just validate, don't use the result yet
-            this.logger.info('YAML validation passed');
+            const parsed = yaml.load(yamlContent);
+            // Validate structure, not just syntax
+            if (!parsed || !parsed.tasks || !Array.isArray(parsed.tasks) || parsed.tasks.length === 0) {
+                throw new Error('YAML parsed but missing required "tasks" array with at least one task');
+            }
+            this.logger.info({ taskCount: parsed.tasks.length }, 'YAML validation passed');
             return output; // YAML is valid, return as-is
         }
         catch (error) {
-            this.logger.warn({ error: error.message }, 'YAML validation failed, asking Claude to fix it');
-            // YAML is invalid, ask Claude to fix it
-            const fixPrompt = `FIX THIS YAML - OUTPUT ONLY THE FIXED YAML, NOTHING ELSE.
+            this.logger.warn({ error: error.message }, 'YAML validation failed, attempting fix (attempt 1/2)');
+            // Attempt up to 2 fix rounds
+            let lastError = error;
+            for (let attempt = 1; attempt <= 2; attempt++) {
+                const fixPrompt = attempt === 1
+                    ? `FIX THIS YAML - OUTPUT ONLY THE FIXED YAML, NOTHING ELSE.
 
 **CRITICAL: Your response must be PURE YAML only. Start directly with "masterPrompt: |"**
 - Do NOT write any explanation
 - Do NOT use markdown code fences
 - Do NOT say "Here's the fixed YAML" or anything similar
 
-ERROR TO FIX: ${error.message}
+ERROR TO FIX: ${lastError.message}
 
 YAML TO FIX:
 ${output}
@@ -502,40 +535,61 @@ RULES:
 - Use 2 spaces for indentation
 - Quote strings with special characters
 - Ensure valid YAML syntax
+- MUST have "masterPrompt:" key AND "tasks:" array with task objects
 
-YOUR RESPONSE MUST START WITH "masterPrompt: |" - NO OTHER TEXT ALLOWED!`;
-            this.logger.info('Asking Claude to fix YAML errors');
-            const fixResult = await this.agentRunner.runAgent(fixPrompt, {
-                agentType: 'architect',
-                model: options.model,
-                timeout: 60_000, // 1 minute for fix
-            });
-            if (!fixResult.success) {
-                throw new Error(`Failed to fix YAML: ${fixResult.errors}`);
-            }
-            // Validate the fixed YAML
-            try {
-                const fixedYaml = this.extractYaml(fixResult.output);
-                yaml.load(fixedYaml); // Validate the fix
-                this.logger.info('Claude successfully fixed the YAML');
-                // Save the fixed YAML for reference
+YOUR RESPONSE MUST START WITH "masterPrompt: |" - NO OTHER TEXT ALLOWED!`
+                    : `YOU FAILED TO PRODUCE VALID YAML. THIS IS YOUR LAST CHANCE.
+
+RULES:
+1. Output ONLY valid YAML
+2. First line MUST be: masterPrompt: |
+3. MUST include tasks: array with id, title, description, estimatedMinutes, dependencies, parallelizable, agentType, prompt, outputFile
+4. NO markdown, NO prose, NO code fences
+5. Previous error: ${lastError.message}
+
+ORIGINAL GOAL: ${options.goal}
+
+Produce the task decomposition as PURE YAML. START NOW:`;
+                this.logger.info({ attempt }, `Asking Claude to fix YAML (attempt ${attempt}/2)`);
+                const fixResult = await this.agentRunner.runAgent(fixPrompt, {
+                    agentType: 'architect',
+                    flags: ['--tools', '""', '--no-session-persistence'],
+                    model: options.model,
+                    systemPrompt: 'You are a YAML generator. Output ONLY valid YAML. No prose. No markdown. Start with "masterPrompt: |".',
+                    timeout: 120_000, // 2 minutes for fix
+                });
+                if (!fixResult.success) {
+                    lastError = new Error(`Fix attempt ${attempt} failed: ${fixResult.errors}`);
+                    continue;
+                }
                 try {
-                    const fixedYamlPath = `${sessionDir}/fixed-yaml.txt`;
-                    await this.fileManager.writeFile(fixedYamlPath, fixResult.output);
-                    this.logger.debug({ fixedYamlPath }, 'Saved fixed YAML');
+                    const fixedYaml = this.extractYaml(fixResult.output);
+                    const parsed = yaml.load(fixedYaml);
+                    if (!parsed || !parsed.tasks || !Array.isArray(parsed.tasks) || parsed.tasks.length === 0) {
+                        throw new Error('Fixed YAML still missing required "tasks" array');
+                    }
+                    this.logger.info({ attempt, taskCount: parsed.tasks.length }, 'YAML fix succeeded');
+                    // Save the fixed YAML for reference
+                    try {
+                        const fixedYamlPath = `${sessionDir}/fixed-yaml-attempt-${attempt}.txt`;
+                        await this.fileManager.writeFile(fixedYamlPath, fixResult.output);
+                    }
+                    catch {
+                        // Ignore save errors
+                    }
+                    return fixResult.output;
                 }
-                catch {
-                    // Ignore save errors
+                catch (fixError) {
+                    lastError = fixError;
+                    this.logger.warn({ attempt, error: lastError.message }, `YAML fix attempt ${attempt} produced invalid output`);
                 }
-                return fixResult.output;
-            }
-            catch (fixError) {
-                this.logger.error({ error: fixError.message }, 'Claude failed to fix YAML properly');
-                throw new Error(`Claude could not fix the YAML errors.\n` +
-                    `Original error: ${error.message}\n` +
-                    `Fix attempt error: ${fixError.message}\n\n` +
-                    `Raw output saved to: ${sessionDir}/raw-claude-output.txt`);
             }
+            // All attempts failed
+            this.logger.error({ error: lastError.message }, 'All YAML fix attempts failed');
+            throw new Error(`Could not produce valid YAML after 2 fix attempts.\n` +
+                `Last error: ${lastError.message}\n\n` +
+                `Raw output saved to: ${sessionDir}/raw-claude-output.txt\n` +
+                `TIP: Try running with --verbose to see the raw output, or check the session directory.`);
         }
     }
     /**