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
1this.messageBus.registerHandler('category.handlerName', async (data) => {
2  const { cwd, ...otherParams } = data;
3  const context = await this.getContext(cwd);
4  
5  // Implementation logic here
6  
7  return {
8    success: true,
9    data: {
10      // Return data
11    },
12  };
13});

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
1// ============================================================================
2// Category Handlers
3// ============================================================================
4
5type CategoryHandlerNameInput = {
6  cwd: string;
7  // other required params
8  optionalParam?: string;
9};
10
11type CategoryHandlerNameOutput = {
12  success: boolean;
13  error?: string;
14  data?: {
15    // return data shape
16  };
17};

Then add to the HandlerMap type:

typescript
1export type HandlerMap = {
2  // ... existing handlers
3  
4  // Category handlers
5  'category.handlerName': {
6    input: CategoryHandlerNameInput;
7    output: CategoryHandlerNameOutput;
8  };
9};

3. (Optional) Add to Test Script

Update scripts/test-nodebridge.ts HANDLERS object if the handler should be easily testable:

typescript
1const HANDLERS: Record<string, string> = {
2  // ... existing handlers
3  'category.handlerName': 'Description of what this handler does',
4};

4. Test the Handler

Run the test script:

bash
1bun scripts/test-nodebridge.ts category.handlerName --cwd=/path/to/dir --param=value

Or with JSON data:

bash
1bun scripts/test-nodebridge.ts category.handlerName --data='{"cwd":"/path","param":"value"}'

Example: Complete Handler Addition

nodeBridge.ts

typescript
1this.messageBus.registerHandler('utils.example', async (data) => {
2  const { cwd, name } = data;
3  try {
4    const context = await this.getContext(cwd);
5    
6    // Do something with context and params
7    const result = await someOperation(name);
8    
9    return {
10      success: true,
11      data: {
12        result,
13      },
14    };
15  } catch (error: any) {
16    return {
17      success: false,
18      error: error.message || 'Failed to execute example',
19    };
20  }
21});

nodeBridge.types.ts

typescript
1type UtilsExampleInput = {
2  cwd: string;
3  name: string;
4};
5
6type UtilsExampleOutput = {
7  success: boolean;
8  error?: string;
9  data?: {
10    result: string;
11  };
12};
13
14// In HandlerMap:
15'utils.example': {
16  input: UtilsExampleInput;
17  output: UtilsExampleOutput;
18};

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)