bmad-elsabro 1.0.0

package/docs/developer/api-reference.md

@@ -0,0 +1,945 @@
+# BMAD Studio API Reference
+
+Complete API reference for BMAD Studio developers covering IPC handlers, services, and component APIs.
+
+## IPC API
+
+All IPC communication happens through the `window.electronAPI` object exposed by the preload script.
+
+### Type Definitions
+
+Located in `renderer/types/electron-api.d.ts`:
+
+```typescript
+interface ElectronAPI {
+  // Config
+  config: {
+    get: (key?: string) => Promise<any>;
+    set: (key: string, value: any) => Promise<{ success: boolean }>;
+  };
+
+  // File Operations
+  file: {
+    read: (path: string) => Promise<{ success: boolean; content?: string; error?: string }>;
+    write: (path: string, content: string) => Promise<{ success: boolean; error?: string }>;
+    list: (path: string) => Promise<{ success: boolean; files?: string[]; error?: string }>;
+  };
+
+  // Terminal
+  terminal: {
+    execute: (command: string) => Promise<{ success: boolean; output?: string; error?: string }>;
+    kill: (pid: number) => Promise<{ success: boolean }>;
+  };
+
+  // Token Operations
+  token: {
+    track: (data: TokenUsageData) => Promise<{ success: boolean }>;
+    getStats: (timeRange?: string) => Promise<TokenStats>;
+    setMode: (mode: 'ultra-save' | 'balanced' | 'power') => Promise<{ success: boolean }>;
+    setBudget: (amount: number) => Promise<{ success: boolean }>;
+  };
+
+  // Workflow Operations
+  workflow: {
+    load: (id: string) => Promise<WorkflowDefinition>;
+    save: (workflow: WorkflowDefinition) => Promise<{ success: boolean }>;
+    execute: (id: string, params?: any) => Promise<WorkflowResult>;
+    list: () => Promise<WorkflowDefinition[]>;
+  };
+
+  // Party Mode
+  party: {
+    start: () => Promise<{ sessionId: string }>;
+    addAgent: (agentId: string) => Promise<{ success: boolean }>;
+    removeAgent: (agentId: string) => Promise<{ success: boolean }>;
+    sendMessage: (message: string) => Promise<{ responses: AgentResponse[] }>;
+  };
+}
+```
+
+### Config API
+
+#### config.get()
+
+Retrieve configuration value(s).
+
+**Signature:**
+```typescript
+config.get(key?: string): Promise<any>
+```
+
+**Parameters:**
+- `key` (optional) — Configuration key to retrieve. If omitted, returns entire config.
+
+**Returns:**
+Promise resolving to configuration value or entire config object.
+
+**Example:**
+```typescript
+// Get entire config
+const config = await window.electronAPI.config.get();
+
+// Get specific key
+const workflowPath = await window.electronAPI.config.get('paths.workflows');
+```
+
+#### config.set()
+
+Update configuration value.
+
+**Signature:**
+```typescript
+config.set(key: string, value: any): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+- `key` — Configuration key to update
+- `value` — New value (any JSON-serializable type)
+
+**Returns:**
+Promise resolving to success status.
+
+**Example:**
+```typescript
+await window.electronAPI.config.set('theme', 'dark');
+await window.electronAPI.config.set('token.budget', 100000);
+```
+
+### File API
+
+#### file.read()
+
+Read file contents from disk.
+
+**Signature:**
+```typescript
+file.read(path: string): Promise<{ success: boolean; content?: string; error?: string }>
+```
+
+**Parameters:**
+- `path` — Absolute file path
+
+**Returns:**
+Promise with file contents or error.
+
+**Example:**
+```typescript
+const result = await window.electronAPI.file.read('/path/to/workflow.yaml');
+if (result.success) {
+  console.log(result.content);
+} else {
+  console.error(result.error);
+}
+```
+
+#### file.write()
+
+Write contents to file.
+
+**Signature:**
+```typescript
+file.write(path: string, content: string): Promise<{ success: boolean; error?: string }>
+```
+
+**Parameters:**
+- `path` — Absolute file path
+- `content` — File contents to write
+
+**Returns:**
+Promise with success status or error.
+
+**Example:**
+```typescript
+const yaml = generateWorkflowYAML(workflow);
+const result = await window.electronAPI.file.write('/path/to/workflow.yaml', yaml);
+```
+
+#### file.list()
+
+List files in directory.
+
+**Signature:**
+```typescript
+file.list(path: string): Promise<{ success: boolean; files?: string[]; error?: string }>
+```
+
+**Parameters:**
+- `path` — Directory path
+
+**Returns:**
+Promise with array of file names or error.
+
+**Example:**
+```typescript
+const result = await window.electronAPI.file.list('.bmad/workflows');
+if (result.success) {
+  result.files.forEach(file => console.log(file));
+}
+```
+
+### Terminal API
+
+#### terminal.execute()
+
+Execute shell command.
+
+**Signature:**
+```typescript
+terminal.execute(command: string): Promise<{ success: boolean; output?: string; error?: string }>
+```
+
+**Parameters:**
+- `command` — Shell command to execute
+
+**Returns:**
+Promise with command output or error.
+
+**Security:** Commands are executed in user's shell environment with project directory as cwd.
+
+**Example:**
+```typescript
+const result = await window.electronAPI.terminal.execute('npm test');
+if (result.success) {
+  console.log(result.output);
+}
+```
+
+#### terminal.kill()
+
+Kill running process by PID.
+
+**Signature:**
+```typescript
+terminal.kill(pid: number): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+- `pid` — Process ID to terminate
+
+**Returns:**
+Promise with success status.
+
+**Example:**
+```typescript
+await window.electronAPI.terminal.kill(12345);
+```
+
+### Token API
+
+#### token.track()
+
+Record token usage for analytics.
+
+**Signature:**
+```typescript
+token.track(data: TokenUsageData): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+```typescript
+interface TokenUsageData {
+  tokensUsed: number;
+  mode: 'ultra-save' | 'balanced' | 'power';
+  workflowId?: string;
+  agentId?: string;
+  cost?: number;
+}
+```
+
+**Returns:**
+Promise with success status.
+
+**Example:**
+```typescript
+await window.electronAPI.token.track({
+  tokensUsed: 1500,
+  mode: 'balanced',
+  workflowId: 'create-prd',
+  agentId: 'pm',
+  cost: 0.045
+});
+```
+
+#### token.getStats()
+
+Retrieve token usage statistics.
+
+**Signature:**
+```typescript
+token.getStats(timeRange?: string): Promise<TokenStats>
+```
+
+**Parameters:**
+- `timeRange` (optional) — Time range: 'day', 'week', 'month', 'all'. Default: 'week'
+
+**Returns:**
+```typescript
+interface TokenStats {
+  totalTokens: number;
+  totalCost: number;
+  byMode: {
+    'ultra-save': number;
+    'balanced': number;
+    'power': number;
+  };
+  byWorkflow: Record<string, number>;
+  byAgent: Record<string, number>;
+  timeline: Array<{ timestamp: number; tokens: number }>;
+}
+```
+
+**Example:**
+```typescript
+const stats = await window.electronAPI.token.getStats('month');
+console.log(`Total tokens this month: ${stats.totalTokens}`);
+```
+
+#### token.setMode()
+
+Change token efficiency mode.
+
+**Signature:**
+```typescript
+token.setMode(mode: 'ultra-save' | 'balanced' | 'power'): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+- `mode` — Efficiency mode to activate
+
+**Mode Characteristics:**
+- **ultra-save**: 40% token reduction, aggressive caching, slower responses
+- **balanced**: Moderate caching, good balance of speed and cost
+- **power**: Minimal caching, best accuracy, highest cost
+
+**Example:**
+```typescript
+await window.electronAPI.token.setMode('ultra-save');
+```
+
+#### token.setBudget()
+
+Set token budget threshold.
+
+**Signature:**
+```typescript
+token.setBudget(amount: number): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+- `amount` — Token budget (positive integer)
+
+**Returns:**
+Promise with success status.
+
+**Note:** Alerts trigger at 80% and 100% of budget.
+
+**Example:**
+```typescript
+await window.electronAPI.token.setBudget(50000); // 50k tokens
+```
+
+### Workflow API
+
+#### workflow.load()
+
+Load workflow definition.
+
+**Signature:**
+```typescript
+workflow.load(id: string): Promise<WorkflowDefinition>
+```
+
+**Parameters:**
+- `id` — Workflow identifier (e.g., 'create-prd', 'dev-story')
+
+**Returns:**
+```typescript
+interface WorkflowDefinition {
+  id: string;
+  name: string;
+  description: string;
+  agent: string;
+  steps: WorkflowStep[];
+  dependencies?: string[];
+}
+
+interface WorkflowStep {
+  id: string;
+  name: string;
+  action: string;
+  params?: Record<string, any>;
+  nextSteps?: string[];
+}
+```
+
+**Example:**
+```typescript
+const workflow = await window.electronAPI.workflow.load('create-prd');
+console.log(workflow.name); // "Create Product Requirements Document"
+```
+
+#### workflow.save()
+
+Save workflow definition.
+
+**Signature:**
+```typescript
+workflow.save(workflow: WorkflowDefinition): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+- `workflow` — Complete workflow definition
+
+**Returns:**
+Promise with success status.
+
+**Example:**
+```typescript
+const updatedWorkflow = { ...workflow, steps: [...workflow.steps, newStep] };
+await window.electronAPI.workflow.save(updatedWorkflow);
+```
+
+#### workflow.execute()
+
+Execute workflow.
+
+**Signature:**
+```typescript
+workflow.execute(id: string, params?: any): Promise<WorkflowResult>
+```
+
+**Parameters:**
+- `id` — Workflow identifier
+- `params` (optional) — Workflow parameters
+
+**Returns:**
+```typescript
+interface WorkflowResult {
+  success: boolean;
+  output?: any;
+  error?: string;
+  tokensUsed?: number;
+  duration?: number;
+}
+```
+
+**Example:**
+```typescript
+const result = await window.electronAPI.workflow.execute('create-prd', {
+  projectName: 'My App',
+  targetUsers: 'developers'
+});
+```
+
+#### workflow.list()
+
+List all available workflows.
+
+**Signature:**
+```typescript
+workflow.list(): Promise<WorkflowDefinition[]>
+```
+
+**Returns:**
+Array of all workflow definitions.
+
+**Example:**
+```typescript
+const workflows = await window.electronAPI.workflow.list();
+workflows.forEach(wf => console.log(wf.name));
+```
+
+### Party Mode API
+
+#### party.start()
+
+Initialize Party Mode session.
+
+**Signature:**
+```typescript
+party.start(): Promise<{ sessionId: string }>
+```
+
+**Returns:**
+Promise with unique session identifier.
+
+**Example:**
+```typescript
+const { sessionId } = await window.electronAPI.party.start();
+console.log(`Party started: ${sessionId}`);
+```
+
+#### party.addAgent()
+
+Add agent to Party Mode session.
+
+**Signature:**
+```typescript
+party.addAgent(agentId: string): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+- `agentId` — Agent identifier (e.g., 'pm', 'architect', 'developer')
+
+**Returns:**
+Promise with success status.
+
+**Example:**
+```typescript
+await window.electronAPI.party.addAgent('pm');
+await window.electronAPI.party.addAgent('architect');
+```
+
+#### party.removeAgent()
+
+Remove agent from Party Mode session.
+
+**Signature:**
+```typescript
+party.removeAgent(agentId: string): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+- `agentId` — Agent identifier to remove
+
+**Returns:**
+Promise with success status.
+
+**Example:**
+```typescript
+await window.electronAPI.party.removeAgent('pm');
+```
+
+#### party.sendMessage()
+
+Send message to all agents in party.
+
+**Signature:**
+```typescript
+party.sendMessage(message: string): Promise<{ responses: AgentResponse[] }>
+```
+
+**Parameters:**
+- `message` — Message to send to all agents
+
+**Returns:**
+```typescript
+interface AgentResponse {
+  agentId: string;
+  agentName: string;
+  response: string;
+  tokensUsed: number;
+}
+```
+
+**Example:**
+```typescript
+const { responses } = await window.electronAPI.party.sendMessage(
+  'What architecture would you recommend for this project?'
+);
+
+responses.forEach(r => {
+  console.log(`${r.agentName}: ${r.response}`);
+});
+```
+
+## Services API
+
+Core services in `electron/services/`.
+
+### TokenTracker
+
+Tracks token usage across the application.
+
+**Location:** `electron/services/token-tracker.ts`
+
+#### Methods
+
+##### track()
+
+Record token usage event.
+
+```typescript
+track(data: {
+  tokensUsed: number;
+  mode: TokenMode;
+  workflowId?: string;
+  agentId?: string;
+  cost?: number;
+}): Promise<void>
+```
+
+##### getStats()
+
+Retrieve usage statistics.
+
+```typescript
+getStats(timeRange: TimeRange): Promise<TokenStats>
+```
+
+##### getCurrentUsage()
+
+Get current session usage.
+
+```typescript
+getCurrentUsage(): number
+```
+
+### TokenCache
+
+LRU cache for AI responses.
+
+**Location:** `electron/services/token-cache.ts`
+
+#### Methods
+
+##### get()
+
+Retrieve cached response.
+
+```typescript
+get(key: string): string | null
+```
+
+##### set()
+
+Store response in cache.
+
+```typescript
+set(key: string, value: string, ttl?: number): void
+```
+
+##### clear()
+
+Clear entire cache.
+
+```typescript
+clear(): void
+```
+
+##### invalidate()
+
+Invalidate specific keys.
+
+```typescript
+invalidate(pattern: string): void
+```
+
+### ProjectDetector
+
+Auto-detects project type and characteristics.
+
+**Location:** `electron/services/project-detector.ts`
+
+#### Methods
+
+##### detect()
+
+Analyze project structure.
+
+```typescript
+detect(projectPath: string): Promise<ProjectInfo>
+```
+
+**Returns:**
+```typescript
+interface ProjectInfo {
+  type: 'react' | 'vue' | 'angular' | 'node' | 'python' | 'unknown';
+  framework?: string;
+  packageManager: 'npm' | 'yarn' | 'pnpm' | 'none';
+  hasTests: boolean;
+  testFramework?: string;
+  size: 'small' | 'medium' | 'large' | 'enterprise';
+  fileCount: number;
+  dependencies: string[];
+}
+```
+
+### LegacyMigrator
+
+Migrates legacy BMAD projects to new format.
+
+**Location:** `electron/services/legacy-migrator.ts`
+
+#### Methods
+
+##### analyze()
+
+Analyze legacy project.
+
+```typescript
+analyze(projectPath: string): Promise<MigrationReport>
+```
+
+##### migrate()
+
+Perform migration.
+
+```typescript
+migrate(
+  projectPath: string,
+  options?: MigrationOptions
+): Promise<MigrationResult>
+```
+
+**Returns:**
+```typescript
+interface MigrationResult {
+  success: boolean;
+  filesModified: string[];
+  filesCreated: string[];
+  errors?: string[];
+  backupPath: string;
+}
+```
+
+### AITestGenerator
+
+Generates tests using AI.
+
+**Location:** `electron/services/ai-test-generator.ts`
+
+#### Methods
+
+##### generateTest()
+
+Generate test for code file.
+
+```typescript
+generateTest(
+  filePath: string,
+  options?: TestGenerationOptions
+): Promise<GeneratedTest>
+```
+
+**Options:**
+```typescript
+interface TestGenerationOptions {
+  framework: 'jest' | 'mocha' | 'vitest';
+  coverage: 'unit' | 'integration' | 'e2e';
+  style: 'minimal' | 'comprehensive';
+}
+```
+
+### PartyCoordinator
+
+Coordinates multi-agent Party Mode sessions.
+
+**Location:** `electron/services/party-coordinator.ts`
+
+#### Methods
+
+##### createSession()
+
+Create new party session.
+
+```typescript
+createSession(): string
+```
+
+##### addAgent()
+
+Add agent to session.
+
+```typescript
+addAgent(sessionId: string, agentId: string): void
+```
+
+##### broadcast()
+
+Send message to all agents.
+
+```typescript
+broadcast(
+  sessionId: string,
+  message: string
+): Promise<AgentResponse[]>
+```
+
+### WorkflowRouter
+
+Routes workflow execution based on project complexity.
+
+**Location:** `electron/services/workflow-router.ts`
+
+#### Methods
+
+##### route()
+
+Determine appropriate workflow.
+
+```typescript
+route(
+  projectInfo: ProjectInfo,
+  intent: string
+): WorkflowRecommendation
+```
+
+**Returns:**
+```typescript
+interface WorkflowRecommendation {
+  workflowId: string;
+  reason: string;
+  alternatives?: string[];
+  estimatedTime?: number;
+  estimatedTokens?: number;
+}
+```
+
+## Component Props
+
+### ChatPanel
+
+```typescript
+interface ChatPanelProps {
+  agentId?: string;
+  onAgentChange?: (agentId: string) => void;
+  showTokenUsage?: boolean;
+}
+```
+
+### WorkflowEditor
+
+```typescript
+interface WorkflowEditorProps {
+  workflowId?: string;
+  onSave?: (workflow: WorkflowDefinition) => void;
+  readonly?: boolean;
+}
+```
+
+### Terminal
+
+```typescript
+interface TerminalProps {
+  initialCommand?: string;
+  cwd?: string;
+  onCommandExecute?: (command: string) => void;
+}
+```
+
+### TokenMonitor
+
+```typescript
+interface TokenMonitorProps {
+  mode?: TokenMode;
+  budget?: number;
+  onModeChange?: (mode: TokenMode) => void;
+  onBudgetChange?: (budget: number) => void;
+}
+```
+
+### TestCenter
+
+```typescript
+interface TestCenterProps {
+  projectPath?: string;
+  onTestGenerate?: (filePath: string) => void;
+  onTestRun?: (results: TestResults) => void;
+}
+```
+
+## Custom Hooks
+
+### useConfig
+
+Access application configuration.
+
+```typescript
+function useConfig(): {
+  config: Config;
+  get: (key: string) => any;
+  set: (key: string, value: any) => Promise<void>;
+  loading: boolean;
+}
+```
+
+### useTokenTracking
+
+Access token tracking state.
+
+```typescript
+function useTokenTracking(): {
+  currentUsage: number;
+  mode: TokenMode;
+  budget: number;
+  stats: TokenStats;
+  setMode: (mode: TokenMode) => void;
+  setBudget: (budget: number) => void;
+}
+```
+
+### useWorkflow
+
+Load and manage workflow state.
+
+```typescript
+function useWorkflow(workflowId: string): {
+  workflow: WorkflowDefinition | null;
+  loading: boolean;
+  error: Error | null;
+  execute: (params?: any) => Promise<WorkflowResult>;
+  save: (workflow: WorkflowDefinition) => Promise<void>;
+}
+```
+
+### usePartyMode
+
+Manage Party Mode session.
+
+```typescript
+function usePartyMode(): {
+  sessionId: string | null;
+  agents: string[];
+  start: () => Promise<void>;
+  addAgent: (agentId: string) => Promise<void>;
+  removeAgent: (agentId: string) => Promise<void>;
+  sendMessage: (message: string) => Promise<AgentResponse[]>;
+}
+```
+
+## Error Handling
+
+All IPC methods return results with `success` boolean and optional `error` string:
+
+```typescript
+const result = await window.electronAPI.file.read('/path/to/file');
+if (!result.success) {
+  console.error('Failed to read file:', result.error);
+  return;
+}
+// Use result.content
+```
+
+For services, use try-catch:
+
+```typescript
+try {
+  const projectInfo = await projectDetector.detect('/path/to/project');
+  console.log(projectInfo);
+} catch (error) {
+  console.error('Detection failed:', error.message);
+}
+```
+
+## TypeScript Support
+
+All APIs are fully typed. Import types from:
+
+```typescript
+// Renderer types
+import type { WorkflowDefinition, TokenStats } from '@/types';
+
+// Electron API types (auto-available via window.electronAPI)
+declare global {
+  interface Window {
+    electronAPI: ElectronAPI;
+  }
+}
+```
+
+## Next Steps
+
+- [Architecture Guide](./architecture.md) — Understand system design
+- [Contributing Guide](./contributing.md) — Development workflow
+- [User Guide](../user-guide/) — End-user documentation