bmad-elsabro 1.0.0

package/docs/developer/contributing.md

@@ -0,0 +1,831 @@
+# Contributing to BMAD Studio
+
+Developer guide for contributing to BMAD Studio, the Electron desktop application for BMAD Method.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20.0.0 or higher
+- Git
+- Code editor (VS Code recommended)
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/bmad-code-org/BMAD-METHOD.git
+cd BMAD-METHOD
+
+# Install dependencies
+npm install
+
+# Start development environment
+npm run electron:dev
+```
+
+The app will launch with hot reload enabled. Changes to renderer code refresh automatically. Main process changes require restart.
+
+## Development Workflow
+
+### Branch Strategy
+
+- `main` — Production-ready code
+- `develop` — Integration branch for features
+- `feature/*` — New features
+- `fix/*` — Bug fixes
+- `docs/*` — Documentation updates
+
+### Making Changes
+
+1. **Create feature branch**
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/my-feature
+```
+
+2. **Make changes following code standards** (see below)
+
+3. **Test your changes**
+
+```bash
+npm test                    # Run all tests
+npm run test:coverage       # Check coverage
+npm run lint                # Check code style
+npm run format:check        # Check formatting
+```
+
+4. **Commit with conventional commits**
+
+```bash
+git add .
+git commit -m "feat(workflow): add drag-and-drop reordering"
+```
+
+5. **Push and create pull request**
+
+```bash
+git push origin feature/my-feature
+```
+
+Then create PR on GitHub targeting `develop` branch.
+
+### Commit Message Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat` — New feature
+- `fix` — Bug fix
+- `docs` — Documentation only
+- `style` — Code style (formatting, no logic change)
+- `refactor` — Code refactoring
+- `perf` — Performance improvement
+- `test` — Adding/updating tests
+- `chore` — Build process, dependencies
+
+**Scopes:**
+- `main` — Main process code
+- `renderer` — Renderer process code
+- `ipc` — IPC communication
+- `services` — Core services
+- `components` — React components
+- `workflow` — Workflow system
+- `token` — Token tracking
+- `test` — Test infrastructure
+
+**Examples:**
+
+```bash
+feat(workflow): add Party Mode multi-agent coordination
+fix(token): correct budget alert threshold calculation
+docs(api): update IPC handler documentation
+refactor(components): extract common TokenDisplay component
+```
+
+## Code Standards
+
+### TypeScript
+
+#### Type Safety
+
+Always use explicit types. Avoid `any` except when absolutely necessary.
+
+**Good:**
+```typescript
+interface WorkflowStep {
+  id: string;
+  name: string;
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+function loadWorkflow(id: string): Promise<WorkflowDefinition> {
+  // implementation
+}
+```
+
+**Bad:**
+```typescript
+function loadWorkflow(id: any): any {
+  // implementation
+}
+```
+
+#### Strict Mode
+
+All TypeScript configs use strict mode:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true
+  }
+}
+```
+
+#### Naming Conventions
+
+- **Interfaces/Types**: PascalCase (e.g., `WorkflowDefinition`)
+- **Functions/Variables**: camelCase (e.g., `loadWorkflow`)
+- **Components**: PascalCase (e.g., `ChatPanel`)
+- **Constants**: SCREAMING_SNAKE_CASE (e.g., `MAX_TOKEN_BUDGET`)
+- **Files**: kebab-case (e.g., `token-tracker.ts`)
+
+### React
+
+#### Functional Components
+
+Use functional components with hooks, not class components.
+
+**Good:**
+```typescript
+export function ChatPanel({ agentId }: ChatPanelProps) {
+  const [messages, setMessages] = useState<Message[]>([]);
+
+  useEffect(() => {
+    loadMessages(agentId);
+  }, [agentId]);
+
+  return (
+    <div className="chat-panel">
+      {/* content */}
+    </div>
+  );
+}
+```
+
+**Bad:**
+```typescript
+class ChatPanel extends React.Component {
+  // Don't use class components
+}
+```
+
+#### Props Interface
+
+Always define props interface before component:
+
+```typescript
+interface ChatPanelProps {
+  agentId?: string;
+  onMessage?: (message: string) => void;
+  className?: string;
+}
+
+export function ChatPanel(props: ChatPanelProps) {
+  // implementation
+}
+```
+
+#### Hooks Rules
+
+Follow React hooks rules:
+
+1. **Call hooks at top level** (not in loops/conditions)
+2. **Use dependency arrays correctly** in `useEffect`
+3. **Clean up side effects** in `useEffect` return
+4. **Extract custom hooks** for reusable logic
+
+**Good:**
+```typescript
+useEffect(() => {
+  const subscription = subscribeToMessages(onMessage);
+
+  return () => {
+    subscription.unsubscribe();
+  };
+}, [onMessage]);
+```
+
+#### Component Organization
+
+Structure components consistently:
+
+```typescript
+// 1. Imports
+import { useState, useEffect } from 'react';
+import type { WorkflowDefinition } from '@/types';
+
+// 2. Types/Interfaces
+interface MyComponentProps {
+  // props
+}
+
+// 3. Component
+export function MyComponent({ prop1, prop2 }: MyComponentProps) {
+  // 4. Hooks
+  const [state, setState] = useState<string>('');
+
+  // 5. Effects
+  useEffect(() => {
+    // side effects
+  }, []);
+
+  // 6. Event handlers
+  const handleClick = () => {
+    // handler logic
+  };
+
+  // 7. Render helpers
+  const renderItem = (item: Item) => {
+    // render logic
+  };
+
+  // 8. Return JSX
+  return (
+    <div className="my-component">
+      {/* JSX */}
+    </div>
+  );
+}
+```
+
+### Styling
+
+#### TailwindCSS
+
+Use TailwindCSS utility classes for all styling.
+
+**Good:**
+```typescript
+<div className="flex items-center justify-between p-4 bg-gray-100 dark:bg-gray-800">
+  <h2 className="text-xl font-bold">Title</h2>
+</div>
+```
+
+**Bad:**
+```typescript
+<div style={{ display: 'flex', padding: '16px' }}>
+  <h2 style={{ fontSize: '20px' }}>Title</h2>
+</div>
+```
+
+#### Dark Mode
+
+Always support dark mode with `dark:` prefix:
+
+```typescript
+<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
+  Content
+</div>
+```
+
+#### Custom Styles
+
+For complex styling, create `.module.css` file:
+
+```typescript
+// Sidebar.module.css
+.sidebar {
+  @apply flex flex-col w-64 bg-white dark:bg-gray-900;
+}
+
+.sidebarCollapsed {
+  @apply w-16;
+}
+
+// Sidebar.tsx
+import styles from './Sidebar.module.css';
+
+export function Sidebar({ collapsed }: Props) {
+  return (
+    <div className={collapsed ? styles.sidebarCollapsed : styles.sidebar}>
+      {/* content */}
+    </div>
+  );
+}
+```
+
+### IPC Communication
+
+#### Handler Pattern
+
+Create dedicated handler files in `electron/ipc/`:
+
+```typescript
+// electron/ipc/my-handler.ts
+import { ipcMain } from 'electron';
+
+export function setupMyHandlers(): void {
+  ipcMain.handle('my:action', async (_event, data) => {
+    try {
+      // Validate input
+      if (!data || typeof data.param !== 'string') {
+        throw new Error('Invalid parameters');
+      }
+
+      // Perform action
+      const result = await doSomething(data.param);
+
+      return { success: true, result };
+    } catch (error) {
+      return {
+        success: false,
+        error: (error as Error).message
+      };
+    }
+  });
+}
+```
+
+Register in `main.ts`:
+
+```typescript
+import { setupMyHandlers } from './ipc/my-handler';
+
+function setupIpcHandlers(): void {
+  setupMyHandlers();
+  // other handlers...
+}
+```
+
+#### Preload Exposure
+
+Expose APIs in `preload.ts`:
+
+```typescript
+import { contextBridge, ipcRenderer } from 'electron';
+
+contextBridge.exposeInMainWorld('electronAPI', {
+  my: {
+    action: (param: string) => ipcRenderer.invoke('my:action', { param })
+  }
+});
+```
+
+Add types in `renderer/types/electron-api.d.ts`:
+
+```typescript
+interface ElectronAPI {
+  my: {
+    action: (param: string) => Promise<{ success: boolean; result?: any; error?: string }>;
+  };
+}
+```
+
+#### Security
+
+- ✅ **Always validate input** in IPC handlers
+- ✅ **Use `contextBridge.exposeInMainWorld`** in preload
+- ✅ **Return structured responses** (`{ success, data?, error? }`)
+- ❌ **Never pass functions** through IPC
+- ❌ **Never use `nodeIntegration: true`**
+- ❌ **Never disable `contextIsolation`**
+
+### Services
+
+#### Service Pattern
+
+Create services in `electron/services/`:
+
+```typescript
+// electron/services/my-service.ts
+
+interface MyServiceOptions {
+  option1: string;
+  option2?: number;
+}
+
+export class MyService {
+  private state: Map<string, any>;
+
+  constructor(private options: MyServiceOptions) {
+    this.state = new Map();
+  }
+
+  async doSomething(param: string): Promise<Result> {
+    // Validate
+    if (!param) {
+      throw new Error('Parameter required');
+    }
+
+    // Process
+    const result = await this.processInternal(param);
+
+    // Update state
+    this.state.set(param, result);
+
+    return result;
+  }
+
+  private async processInternal(param: string): Promise<Result> {
+    // Internal implementation
+  }
+}
+
+// Export singleton instance
+export const myService = new MyService({
+  option1: 'default'
+});
+```
+
+#### Dependency Injection
+
+Use constructor injection for dependencies:
+
+```typescript
+export class WorkflowEngine {
+  constructor(
+    private tokenTracker: TokenTracker,
+    private storage: WorkflowStorage
+  ) {}
+
+  async execute(workflowId: string): Promise<Result> {
+    const workflow = await this.storage.load(workflowId);
+    const tokens = this.tokenTracker.getCurrentUsage();
+    // ...
+  }
+}
+```
+
+### Testing
+
+#### Unit Tests
+
+Write unit tests for all services and utilities:
+
+```typescript
+// token-tracker.test.ts
+import { TokenTracker } from '../services/token-tracker';
+
+describe('TokenTracker', () => {
+  let tracker: TokenTracker;
+
+  beforeEach(() => {
+    tracker = new TokenTracker();
+  });
+
+  afterEach(() => {
+    tracker.reset();
+  });
+
+  test('tracks token usage', async () => {
+    await tracker.track({
+      tokensUsed: 100,
+      mode: 'balanced'
+    });
+
+    expect(tracker.getCurrentUsage()).toBe(100);
+  });
+
+  test('calculates stats correctly', async () => {
+    await tracker.track({ tokensUsed: 100, mode: 'balanced' });
+    await tracker.track({ tokensUsed: 50, mode: 'ultra-save' });
+
+    const stats = await tracker.getStats('day');
+    expect(stats.totalTokens).toBe(150);
+  });
+});
+```
+
+#### Component Tests
+
+Test React components with React Testing Library:
+
+```typescript
+// ChatPanel.test.tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ChatPanel } from './ChatPanel';
+
+describe('ChatPanel', () => {
+  test('renders messages', () => {
+    render(<ChatPanel agentId="pm" />);
+    expect(screen.getByRole('list')).toBeInTheDocument();
+  });
+
+  test('sends message on submit', async () => {
+    const onMessage = jest.fn();
+    render(<ChatPanel onMessage={onMessage} />);
+
+    const input = screen.getByPlaceholderText('Type message...');
+    fireEvent.change(input, { target: { value: 'Hello' } });
+
+    const button = screen.getByText('Send');
+    fireEvent.click(button);
+
+    expect(onMessage).toHaveBeenCalledWith('Hello');
+  });
+});
+```
+
+#### Test Coverage
+
+Maintain >80% code coverage:
+
+```bash
+npm run test:coverage
+```
+
+Coverage reports in `coverage/` directory.
+
+### Documentation
+
+#### Code Comments
+
+Use JSDoc for functions and classes:
+
+```typescript
+/**
+ * Load workflow definition from disk.
+ *
+ * @param id - Workflow identifier (e.g., 'create-prd')
+ * @returns Promise resolving to workflow definition
+ * @throws Error if workflow not found
+ *
+ * @example
+ * ```typescript
+ * const workflow = await loadWorkflow('create-prd');
+ * console.log(workflow.name);
+ * ```
+ */
+export async function loadWorkflow(id: string): Promise<WorkflowDefinition> {
+  // implementation
+}
+```
+
+#### Inline Comments
+
+Use inline comments for complex logic:
+
+```typescript
+// Calculate token usage with mode multiplier
+// Ultra-save mode: 0.6x tokens (40% reduction)
+// Balanced mode: 1.0x tokens (baseline)
+// Power mode: 1.2x tokens (20% increase for accuracy)
+const adjustedTokens = baseTokens * MODE_MULTIPLIERS[mode];
+```
+
+#### README Updates
+
+Update relevant READMEs when adding features:
+
+- Project README for user-facing features
+- Component READMEs for new component libraries
+- Service READMEs for new services
+
+## Performance Guidelines
+
+### Renderer Process
+
+#### Virtualization
+
+Use virtualized lists for large data sets:
+
+```typescript
+import { FixedSizeList } from 'react-window';
+
+function FileList({ files }: Props) {
+  const Row = ({ index, style }: any) => (
+    <div style={style}>
+      {files[index].name}
+    </div>
+  );
+
+  return (
+    <FixedSizeList
+      height={600}
+      itemCount={files.length}
+      itemSize={35}
+    >
+      {Row}
+    </FixedSizeList>
+  );
+}
+```
+
+#### Code Splitting
+
+Use React.lazy for large components:
+
+```typescript
+import { lazy, Suspense } from 'react';
+
+const WorkflowEditor = lazy(() => import('./components/WorkflowEditor'));
+
+function App() {
+  return (
+    <Suspense fallback={<LoadingSpinner />}>
+      <WorkflowEditor />
+    </Suspense>
+  );
+}
+```
+
+#### Memoization
+
+Memoize expensive computations:
+
+```typescript
+import { useMemo } from 'react';
+
+function WorkflowStats({ workflow }: Props) {
+  const stats = useMemo(() => {
+    return calculateComplexStats(workflow);
+  }, [workflow]);
+
+  return <div>{stats.totalSteps}</div>;
+}
+```
+
+### Main Process
+
+#### Async Operations
+
+Never block the main thread:
+
+```typescript
+// Good: Async file operations
+const content = await fs.readFile(path, 'utf-8');
+
+// Bad: Sync operations
+const content = fs.readFileSync(path, 'utf-8');
+```
+
+#### Streaming
+
+Stream large files instead of loading into memory:
+
+```typescript
+import { createReadStream } from 'fs';
+
+async function processLargeFile(path: string): Promise<void> {
+  const stream = createReadStream(path, { encoding: 'utf-8' });
+
+  for await (const chunk of stream) {
+    await processChunk(chunk);
+  }
+}
+```
+
+## Debugging
+
+### Renderer Process
+
+Use Chrome DevTools (auto-opens in development):
+
+- **Console** — Log messages, errors
+- **Sources** — Set breakpoints, step through code
+- **React DevTools** — Inspect component tree
+
+### Main Process
+
+Use VS Code debugger:
+
+1. Create `.vscode/launch.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Electron Main",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "electron:start"],
+      "port": 9229,
+      "skipFiles": ["<node_internals>/**"]
+    }
+  ]
+}
+```
+
+2. Set breakpoints in `.ts` files
+3. Press F5 to start debugging
+
+### IPC Debugging
+
+Log IPC calls for debugging:
+
+```typescript
+// In preload.ts (temporary debugging)
+contextBridge.exposeInMainWorld('electronAPI', {
+  workflow: {
+    load: (id: string) => {
+      console.log('[IPC] workflow:load', id);
+      return ipcRenderer.invoke('workflow:load', id);
+    }
+  }
+});
+```
+
+## Common Tasks
+
+### Adding a New Component
+
+1. Create component file: `renderer/components/MyComponent.tsx`
+2. Define props interface
+3. Implement component with TypeScript and TailwindCSS
+4. Add tests: `renderer/components/MyComponent.test.tsx`
+5. Export from parent component or `App.tsx`
+6. Document in API reference if public API
+
+### Adding an IPC Handler
+
+1. Create handler: `electron/ipc/my-handler.ts`
+2. Export setup function: `setupMyHandlers()`
+3. Register in `electron/main.ts` → `setupIpcHandlers()`
+4. Expose in `electron/preload.ts`
+5. Add types in `renderer/types/electron-api.d.ts`
+6. Document in API reference
+
+### Adding a Service
+
+1. Create service: `electron/services/my-service.ts`
+2. Export class or functions with types
+3. Add unit tests: `test/services/my-service.test.ts`
+4. Use in IPC handlers or other services
+5. Document in API reference
+
+### Updating Dependencies
+
+```bash
+# Check for updates
+npm outdated
+
+# Update specific package
+npm update package-name
+
+# Update all (carefully)
+npm update
+
+# Test thoroughly after updates
+npm test
+npm run electron:dev
+```
+
+## Pull Request Process
+
+1. **Ensure all tests pass**
+
+```bash
+npm test
+npm run lint
+npm run format:check
+```
+
+2. **Update documentation** if needed
+
+3. **Create descriptive PR**
+
+Title: Follow conventional commits format
+Description: Explain what, why, and how
+
+4. **Request review** from maintainers
+
+5. **Address feedback** promptly
+
+6. **Squash commits** before merge (if requested)
+
+## Getting Help
+
+- 💬 [Discord](https://discord.gg/gk8jAdXWmj) — Real-time help
+- 📝 [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) — Bug reports, features
+- 💡 [Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions) — Questions, ideas
+
+## Code of Conduct
+
+Be respectful, inclusive, and collaborative. See [CODE_OF_CONDUCT.md](../../CODE_OF_CONDUCT.md) for details.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+## Next Steps
+
+- [Architecture Guide](./architecture.md) — Understand system design
+- [API Reference](./api-reference.md) — API documentation
+- [User Guide](../user-guide/) — End-user documentation