add-nodebridge-handler

# Add NodeBridge Handler ## Overview This skill guides the process of adding a new message handler to the NodeBridge system, which enables communication between the UI layer and the Node.js backend. ## Steps ### 1. Add Handler Implementation in `src/nodeBridge.ts` Locate the `registerHandlers()` method in the `NodeHandlerRegistry` class and add your handler: ```typescript this.messageBus.registerHandler('category.handlerName', async (data) => { const { cwd, ...otherParams } = data; const context = await this.getContext(cwd); // Implementation logic here return { success: true, data: { // Return data }, }; }); ``` **Handler Naming Convention:** - Use dot notation: `category.action` (e.g., `git.status`, `session.send`, `utils.getPaths`) - Categories: `config`, `git`, `mcp`, `models`, `outputStyles`, `project`, `projects`, `providers`, `session`, `sessions`, `slashCommand`, `status`, `utils` **Common Patterns:** - Always get context via `await this.getContext(cwd)` - Return `{ success: true, data: {...} }` for success - Return `{ success: false, error: 'message' }` for errors - Wrap in try/catch for error handling ### 2. Add Type Definitions in `src/nodeBridge.types.ts` Add input and output types near the relevant section: ```typescript // ============================================================================ // Category Handlers // ============================================================================ type CategoryHandlerNameInput = { cwd: string; // other required params optionalParam?: string; }; type CategoryHandlerNameOutput = { success: boolean; error?: string; data?: { // return data shape }; }; ``` Then add to the `HandlerMap` type: ```typescript export type HandlerMap = { // ... existing handlers // Category handlers 'category.handlerName': { input: CategoryHandlerNameInput; output: CategoryHandlerNameOutput; }; }; ``` ### 3. (Optional) Add to Test Script Update `scripts/test-nodebridge.ts` HANDLERS object if the handler should be easily testable: ```typescript const HANDLERS: Record<string, string> = { // ... existing handlers 'category.handlerName': 'Description of what this handler does', }; ``` ### 4. Test the Handler Run the test script: ```bash bun scripts/test-nodebridge.ts category.handlerName --cwd=/path/to/dir --param=value ``` Or with JSON data: ```bash bun scripts/test-nodebridge.ts category.handlerName --data='{"cwd":"/path","param":"value"}' ``` ## Example: Complete Handler Addition ### nodeBridge.ts ```typescript this.messageBus.registerHandler('utils.example', async (data) => { const { cwd, name } = data; try { const context = await this.getContext(cwd); // Do something with context and params const result = await someOperation(name); return { success: true, data: { result, }, }; } catch (error: any) { return { success: false, error: error.message || 'Failed to execute example', }; } }); ``` ### nodeBridge.types.ts ```typescript type UtilsExampleInput = { cwd: string; name: string; }; type UtilsExampleOutput = { success: boolean; error?: string; data?: { result: string; }; }; // In HandlerMap: 'utils.example': { input: UtilsExampleInput; output: UtilsExampleOutput; }; ``` ## Notes - Handlers are async functions that receive `data` parameter - Use `this.getContext(cwd)` to get the Context instance (cached per cwd) - Context provides access to: `config`, `paths`, `mcpManager`, `productName`, `version`, etc. - For long-running operations, consider using abort controllers (see `git.clone` pattern) - For operations that emit progress, use `this.messageBus.emitEvent()` (see `git.commit.output` pattern)