@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/mcp/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * MCP Gateway Type Definitions
+ *
+ * Shared interfaces for MCP gateway services (health checker, config manager, credential manager).
+ * These types define the contracts that Story 2.4 and Epic 1 services will implement.
+ */
+/**
+ * Health status of a single component
+ */
+export type HealthStatus = 'disabled' | 'healthy' | 'offline' | 'unhealthy';
+/**
+ * Health status for an individual MCP server
+ */
+export interface ServerHealthStatus {
+    error: null | string;
+    latency: null | number;
+    name: string;
+    status: HealthStatus;
+    useCase?: string;
+}
+/**
+ * Gateway-level health status
+ */
+export interface GatewayHealthStatus {
+    latency: null | number;
+    status: HealthStatus;
+    url: string;
+}
+/**
+ * Complete health report for the MCP gateway and all servers
+ */
+export interface HealthReport {
+    gateway: GatewayHealthStatus;
+    servers: ServerHealthStatus[];
+}
+/**
+ * Credential entry with masked value
+ */
+export interface CredentialEntry {
+    configured: boolean;
+    key: string;
+    requiredByPreset: boolean;
+}
+/**
+ * MCP server configuration entry
+ */
+export interface McpServerConfig {
+    apiKeyRequired?: boolean;
+    enabled: boolean;
+    name: string;
+    useCase?: string;
+}
+/**
+ * Server template as defined in server-templates/*.yaml
+ */
+export interface ServerTemplate {
+    api_key_required: boolean;
+    args?: string[];
+    command?: string;
+    enabled: boolean;
+    env?: Record<string, string>;
+    health_check: {
+        command: string;
+        method: 'http' | 'tool_call';
+        timeout: number;
+    };
+    layer?: 'direct' | 'gateway';
+    name: string;
+    transport: 'sse' | 'stdio';
+    url?: string;
+    use_case: string;
+}
+/**
+ * Interface contract for McpHealthChecker (Story 2.4)
+ */
+export interface IHealthChecker {
+    checkAll(): Promise<HealthReport>;
+}
+/**
+ * Interface contract for McpConfigManager (Epic 1)
+ */
+export interface IConfigManager {
+    addServer(template: ServerTemplate): void;
+    applyPreset(presetName: string): void;
+    getEnabledServers(): McpServerConfig[];
+    getGatewayUrl(): string;
+    getPresetName(): string;
+    removeServer(name: string): boolean;
+}
+/**
+ * Interface contract for McpCredentialManager (Epic 1)
+ */
+export interface ICredentialManager {
+    get(key: string): string | null;
+    list(): CredentialEntry[];
+    remove(key: string): boolean;
+    resolve(key: string): string | null;
+    set(key: string, value: string): void;
+}

package/dist/mcp/types.js

@@ -0,0 +1,7 @@
+/**
+ * MCP Gateway Type Definitions
+ *
+ * Shared interfaces for MCP gateway services (health checker, config manager, credential manager).
+ * These types define the contracts that Story 2.4 and Epic 1 services will implement.
+ */
+export {};

package/dist/mcp/utils/docker-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Docker Availability Detection Utilities
+ *
+ * Provides functions to check Docker availability, resolve the gateway
+ * compose file path, and format Docker errors into user-friendly messages.
+ */
+/**
+ * Result of Docker availability check
+ */
+export interface DockerAvailabilityResult {
+    available: boolean;
+    error?: string;
+    reason?: 'daemon-not-running' | 'not-installed';
+}
+/**
+ * Check if Docker is available and the daemon is running
+ *
+ * Executes `docker info` to verify both installation and daemon status.
+ *
+ * @returns DockerAvailabilityResult with availability status and error details
+ */
+export declare function isDockerAvailable(): DockerAvailabilityResult;
+/**
+ * Resolve the path to the Docker Compose gateway file
+ *
+ * The compose file is expected at src/mcp/infrastructure/docker-compose.gateway.yml
+ * relative to the CLI package root.
+ *
+ * @returns Absolute path to docker-compose.gateway.yml
+ */
+export declare function getDockerComposeFilePath(): string;
+/**
+ * Check if the Docker Compose gateway file exists
+ *
+ * @returns true if the compose file exists at the expected path
+ */
+export declare function dockerComposeFileExists(): boolean;
+/**
+ * Format a Docker error into a user-friendly message with troubleshooting hints
+ *
+ * @param result - Docker availability check result
+ * @returns Formatted error message string
+ */
+export declare function formatDockerError(result: DockerAvailabilityResult): string;
+/**
+ * Default gateway health endpoint URL
+ */
+export declare const DEFAULT_GATEWAY_URL = "http://localhost:8080";
+/**
+ * Default health check poll interval in milliseconds
+ */
+export declare const HEALTH_CHECK_INTERVAL_MS = 2000;
+/**
+ * Default health check timeout in milliseconds
+ */
+export declare const HEALTH_CHECK_TIMEOUT_MS = 30000;

package/dist/mcp/utils/docker-utils.js

@@ -0,0 +1,108 @@
+/**
+ * Docker Availability Detection Utilities
+ *
+ * Provides functions to check Docker availability, resolve the gateway
+ * compose file path, and format Docker errors into user-friendly messages.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'mcp:utils:docker' });
+/**
+ * Check if Docker is available and the daemon is running
+ *
+ * Executes `docker info` to verify both installation and daemon status.
+ *
+ * @returns DockerAvailabilityResult with availability status and error details
+ */
+export function isDockerAvailable() {
+    try {
+        execSync('docker info', { stdio: 'pipe', timeout: 10_000 });
+        logger.debug('Docker is available');
+        return { available: true };
+    }
+    catch (error) {
+        const err = error;
+        const stderr = err.stderr ? err.stderr.toString() : err.message;
+        if (stderr.includes('command not found') || stderr.includes('not recognized') || stderr.includes('ENOENT')) {
+            logger.warn('Docker is not installed');
+            return {
+                available: false,
+                error: stderr,
+                reason: 'not-installed',
+            };
+        }
+        logger.warn('Docker daemon is not running');
+        return {
+            available: false,
+            error: stderr,
+            reason: 'daemon-not-running',
+        };
+    }
+}
+/**
+ * Resolve the path to the Docker Compose gateway file
+ *
+ * The compose file is expected at src/mcp/infrastructure/docker-compose.gateway.yml
+ * relative to the CLI package root.
+ *
+ * @returns Absolute path to docker-compose.gateway.yml
+ */
+export function getDockerComposeFilePath() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    // From src/mcp/utils/ → src/mcp/infrastructure/
+    const composePath = resolve(currentDir, '..', 'infrastructure', 'docker-compose.gateway.yml');
+    logger.debug('Resolved Docker Compose file path: %s', composePath);
+    return composePath;
+}
+/**
+ * Check if the Docker Compose gateway file exists
+ *
+ * @returns true if the compose file exists at the expected path
+ */
+export function dockerComposeFileExists() {
+    const composePath = getDockerComposeFilePath();
+    return existsSync(composePath);
+}
+/**
+ * Format a Docker error into a user-friendly message with troubleshooting hints
+ *
+ * @param result - Docker availability check result
+ * @returns Formatted error message string
+ */
+export function formatDockerError(result) {
+    if (result.reason === 'not-installed') {
+        return [
+            'Docker is not installed on this system.',
+            '',
+            'To install Docker:',
+            '  macOS:   brew install --cask docker',
+            '  Linux:   https://docs.docker.com/engine/install/',
+            '  Windows: https://docs.docker.com/desktop/install/windows-install/',
+        ].join('\n');
+    }
+    if (result.reason === 'daemon-not-running') {
+        return [
+            'Docker daemon is not running.',
+            '',
+            'To start Docker:',
+            '  macOS/Windows: Open the Docker Desktop application',
+            '  Linux:         sudo systemctl start docker',
+        ].join('\n');
+    }
+    return `Docker error: ${result.error || 'Unknown error'}`;
+}
+/**
+ * Default gateway health endpoint URL
+ */
+export const DEFAULT_GATEWAY_URL = 'http://localhost:8080';
+/**
+ * Default health check poll interval in milliseconds
+ */
+export const HEALTH_CHECK_INTERVAL_MS = 2000;
+/**
+ * Default health check timeout in milliseconds
+ */
+export const HEALTH_CHECK_TIMEOUT_MS = 30_000;

package/dist/mcp/utils/template-loader.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Server Template Loader
+ *
+ * Loads and validates MCP server template YAML files from the
+ * src/mcp/server-templates/ directory.
+ */
+import type { ServerTemplate } from '../types.js';
+/**
+ * List all available server template names by scanning the server-templates directory
+ *
+ * @returns Array of template names (without .yaml extension)
+ */
+export declare function listAvailableTemplates(): string[];
+/**
+ * Load and parse a server template by name
+ *
+ * @param name - Server template name (e.g., 'context7', 'exa')
+ * @returns Parsed ServerTemplate object
+ * @throws Error if template not found, with available templates listed
+ */
+export declare function loadServerTemplate(name: string): ServerTemplate;

package/dist/mcp/utils/template-loader.js

@@ -0,0 +1,60 @@
+/**
+ * Server Template Loader
+ *
+ * Loads and validates MCP server template YAML files from the
+ * src/mcp/server-templates/ directory.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger({ namespace: 'mcp:utils:template-loader' });
+/**
+ * Resolve the absolute path to the server-templates directory
+ */
+function getTemplatesDir() {
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    return resolve(currentDir, '..', 'server-templates');
+}
+/**
+ * List all available server template names by scanning the server-templates directory
+ *
+ * @returns Array of template names (without .yaml extension)
+ */
+export function listAvailableTemplates() {
+    const templatesDir = getTemplatesDir();
+    logger.debug('Scanning templates directory: %s', templatesDir);
+    if (!existsSync(templatesDir)) {
+        logger.warn('Templates directory not found: %s', templatesDir);
+        return [];
+    }
+    const files = readdirSync(templatesDir);
+    return files
+        .filter((f) => f.endsWith('.yaml') && !f.startsWith('__'))
+        .map((f) => f.replace('.yaml', ''))
+        .sort();
+}
+/**
+ * Load and parse a server template by name
+ *
+ * @param name - Server template name (e.g., 'context7', 'exa')
+ * @returns Parsed ServerTemplate object
+ * @throws Error if template not found, with available templates listed
+ */
+export function loadServerTemplate(name) {
+    const templatesDir = getTemplatesDir();
+    const templatePath = resolve(templatesDir, `${name}.yaml`);
+    logger.debug('Loading template: %s from %s', name, templatePath);
+    if (!existsSync(templatePath)) {
+        const available = listAvailableTemplates();
+        throw new Error(`Server template '${name}' not found. Available templates: ${available.join(', ')}`);
+    }
+    const content = readFileSync(templatePath, 'utf8');
+    const parsed = yaml.load(content);
+    if (!parsed || typeof parsed !== 'object' || !parsed.name) {
+        throw new Error(`Invalid server template format in '${name}.yaml': missing required 'name' field`);
+    }
+    logger.info('Loaded template: %s (transport=%s, api_key_required=%s)', parsed.name, parsed.transport, parsed.api_key_required);
+    return parsed;
+}

package/dist/models/agent-options.d.ts

@@ -2,7 +2,7 @@ import type { AgentResult } from './agent-result.js';
 /**
  * Available BMAD agent types
  */
-export type AgentType = 'analyst' | 'architect' | 'dev' | 'pm' | 'prd-fixer' | 'quick-flow-solo-dev' | 'sm' | 'tea' | 'tech-writer' | 'ux-designer';
+export type AgentType = 'analyst' | 'architect' | 'dev' | 'pm' | 'prd-fixer' | 'qa' | 'quick-flow-solo-dev' | 'sm' | 'tea' | 'tech-writer' | 'ux-designer';
 /**
  * Agent options without prompt and callbacks (used internally)
  */
@@ -23,6 +23,10 @@ export interface AgentOptions {
      * The type of agent to execute
      */
     agentType: AgentType;
+    /**
+     * Working directory for the agent process
+     */
+    cwd?: string;
     /**
      * Additional CLI flags to pass to the Claude executable
      */
@@ -50,6 +54,11 @@ export interface AgentOptions {
      * File references to include in the agent execution
      */
     references?: string[];
+    /**
+     * System prompt to append via --append-system-prompt (Claude only).
+     * Used to enforce output format constraints (e.g., YAML-only output).
+     */
+    systemPrompt?: string;
     /**
      * Timeout in milliseconds (default: 1800000ms = 30 minutes)
      */

package/dist/models/index.d.ts

@@ -6,5 +6,6 @@ export * from './agent-result.js';
 export * from './phase-result.js';
 export * from './provider.js';
 export * from './story.js';
+export * from './workflow-callbacks.js';
 export * from './workflow-config.js';
 export * from './workflow-result.js';

package/dist/models/index.js

@@ -6,5 +6,6 @@ export * from './agent-result.js';
 export * from './phase-result.js';
 export * from './provider.js';
 export * from './story.js';
+export * from './workflow-callbacks.js';
 export * from './workflow-config.js';
 export * from './workflow-result.js';

package/dist/models/workflow-callbacks.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Workflow Callbacks
+ *
+ * Interfaces for lifecycle event callbacks that consumers can register
+ * to observe workflow execution without coupling to orchestration internals.
+ *
+ * Callbacks are fire-and-forget (synchronous but non-blocking) and errors
+ * in callbacks do not interrupt workflow execution.
+ */
+/**
+ * Context for phase lifecycle events
+ *
+ * Provided when a workflow phase (epic, story, dev, qa) starts or completes.
+ */
+export interface PhaseContext {
+    /**
+     * Phase name: 'epic' | 'story' | 'dev' | 'qa'
+     */
+    phaseName: string;
+    /**
+     * Phase start timestamp (epoch ms)
+     */
+    startTime: number;
+    /**
+     * Phase end timestamp (epoch ms, only in onPhaseComplete)
+     */
+    endTime?: number;
+    /**
+     * Phase duration in milliseconds (only in onPhaseComplete)
+     */
+    duration?: number;
+    /**
+     * Total items to process in this phase
+     */
+    itemCount: number;
+    /**
+     * Number of successfully processed items (only in onPhaseComplete)
+     */
+    successCount?: number;
+    /**
+     * Number of failed items (only in onPhaseComplete)
+     */
+    failureCount?: number;
+    /**
+     * Whether the phase was skipped
+     */
+    skipped?: boolean;
+    /**
+     * Additional metadata specific to the phase
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Context for layer/batch lifecycle events
+ *
+ * Provided when a batch of items starts or completes processing.
+ * Layers represent groups of items processed in parallel.
+ */
+export interface LayerContext {
+    /**
+     * Phase this layer belongs to
+     */
+    phaseName: string;
+    /**
+     * Zero-based layer index within the phase
+     */
+    layerIndex: number;
+    /**
+     * Total number of layers in the phase
+     */
+    totalLayers: number;
+    /**
+     * Number of items (spawns) in this layer
+     */
+    spawnCount: number;
+    /**
+     * Whether items in this layer are processed in parallel
+     */
+    parallel: boolean;
+    /**
+     * Layer start timestamp (epoch ms)
+     */
+    startTime: number;
+    /**
+     * Layer end timestamp (epoch ms, only in onLayerComplete)
+     */
+    endTime?: number;
+    /**
+     * Layer duration in milliseconds (only in onLayerComplete)
+     */
+    duration?: number;
+    /**
+     * Number of successful spawns (only in onLayerComplete)
+     */
+    successCount?: number;
+    /**
+     * Number of failed spawns (only in onLayerComplete)
+     */
+    failureCount?: number;
+}
+/**
+ * Context for spawn (agent execution) lifecycle events
+ *
+ * Provided when an individual agent execution starts, completes, or produces output.
+ */
+export interface SpawnContext {
+    /**
+     * Unique identifier for this spawn
+     */
+    spawnId: string;
+    /**
+     * Phase this spawn belongs to
+     */
+    phaseName: string;
+    /**
+     * Type of agent being spawned: 'architect' | 'sm' | 'dev' | 'qa'
+     */
+    agentType: string;
+    /**
+     * Item identifier (epic number, story number, etc.)
+     */
+    itemId: string;
+    /**
+     * Item title or description
+     */
+    itemTitle?: string;
+    /**
+     * Output file path (if applicable)
+     */
+    outputPath?: string;
+    /**
+     * The prompt sent to the agent
+     */
+    prompt?: string;
+    /**
+     * Spawn start timestamp (epoch ms)
+     */
+    startTime: number;
+    /**
+     * Spawn end timestamp (epoch ms, only in onSpawnComplete)
+     */
+    endTime?: number;
+    /**
+     * Spawn duration in milliseconds (only in onSpawnComplete)
+     */
+    duration?: number;
+    /**
+     * Whether the spawn succeeded (only in onSpawnComplete)
+     */
+    success?: boolean;
+    /**
+     * Agent output text (only in onSpawnComplete or onSpawnOutput)
+     */
+    output?: string;
+    /**
+     * Error message if spawn failed (only in onSpawnComplete)
+     */
+    error?: string;
+    /**
+     * Worker ID for pipelined execution
+     */
+    workerId?: number;
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Context for error events
+ *
+ * Provided when an error occurs during workflow execution.
+ */
+export interface ErrorContext {
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Phase where the error occurred (if applicable)
+     */
+    phaseName?: string;
+    /**
+     * Spawn ID where the error occurred (if applicable)
+     */
+    spawnId?: string;
+    /**
+     * Item identifier related to the error (if applicable)
+     */
+    itemId?: string;
+    /**
+     * Error stack trace (if available)
+     */
+    stack?: string;
+    /**
+     * Original error object
+     */
+    error?: Error;
+    /**
+     * Timestamp when error occurred (epoch ms)
+     */
+    timestamp: number;
+    /**
+     * Whether the error is recoverable (workflow can continue)
+     */
+    recoverable: boolean;
+    /**
+     * Additional context about the error
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Workflow lifecycle callbacks
+ *
+ * Optional callback functions that consumers can register to observe
+ * workflow execution events. All callbacks are wrapped in try-catch
+ * to prevent errors from interrupting workflow execution.
+ */
+export interface WorkflowCallbacks {
+    /**
+     * Called when a phase starts execution
+     */
+    onPhaseStart?: (context: PhaseContext) => void;
+    /**
+     * Called when a phase completes execution
+     */
+    onPhaseComplete?: (context: PhaseContext) => void;
+    /**
+     * Called when a batch/layer starts processing
+     */
+    onLayerStart?: (context: LayerContext) => void;
+    /**
+     * Called when a batch/layer completes processing
+     */
+    onLayerComplete?: (context: LayerContext) => void;
+    /**
+     * Called when an agent spawn starts
+     */
+    onSpawnStart?: (context: SpawnContext) => void;
+    /**
+     * Called when an agent spawn completes
+     */
+    onSpawnComplete?: (context: SpawnContext) => void;
+    /**
+     * Called when an agent produces streaming output
+     */
+    onSpawnOutput?: (context: SpawnContext, output: string) => void;
+    /**
+     * Called when an error occurs
+     */
+    onError?: (context: ErrorContext) => void;
+}

package/dist/models/workflow-callbacks.js

@@ -0,0 +1,10 @@
+/**
+ * Workflow Callbacks
+ *
+ * Interfaces for lifecycle event callbacks that consumers can register
+ * to observe workflow execution without coupling to orchestration internals.
+ *
+ * Callbacks are fire-and-forget (synchronous but non-blocking) and errors
+ * in callbacks do not interrupt workflow execution.
+ */
+export {};