Cline rules

1# Cline Protobuf Development Guide
2 
3This guide outlines how to add new gRPC endpoints for communication between the webview (frontend) and the extension host (backend).
4 
5## Overview
6 
7Cline uses [Protobuf](https://protobuf.dev/) to define a strongly-typed API, ensuring efficient and type-safe communication. All definitions are in the `/proto` directory. The compiler and plugins are included as project dependencies, so no manual installation is needed.
8 
9## Key Concepts & Best Practices
10 
11-   **File Structure**: Each feature domain should have its own `.proto` file (e.g., `account.proto`, `task.proto`).
12-   **Message Design**:
13    -   For simple, single-value data, use the shared types in `proto/common.proto` (e.g., `StringRequest`, `Empty`, `Int64Request`). This promotes consistency.
14    -   For complex data structures, define custom messages within the feature's `.proto` file (see `task.proto` for examples like `NewTaskRequest`).
15-   **Naming Conventions**:
16    -   Services: `PascalCaseService` (e.g., `AccountService`).
17    -   RPCs: `camelCase` (e.g., `accountEmailIdentified`).
18    -   Messages: `PascalCase` (e.g., `StringRequest`).
19-   **Streaming**: For server-to-client streaming, use the `stream` keyword on the response type. See `subscribeToAuthCallback` in `account.proto` for an example.
20 
21---
22 
23## 4-Step Development Workflow
24 
25Here’s how to add a new RPC, using `scrollToSettings` as an example.
26 
27### 1. Define the RPC in a `.proto` File
28 
29Add your service method to the appropriate file in the `proto/` directory.
30 
31**File: `proto/ui.proto`**
32```proto
33service UiService {
34  // ... other RPCs
35  // Scrolls to a specific settings section in the settings view
36  rpc scrollToSettings(StringRequest) returns (KeyValuePair);
37}
38```
39Here, we use the common `StringRequest` and `KeyValuePair` types.
40 
41### 2. Compile Definitions
42 
43After editing a `.proto` file, regenerate the TypeScript code. From the project root, run:
44```bash
45npm run protos
46```
47This command compiles all `.proto` files and outputs the generated code to `src/generated/` and `src/shared/`. Do not edit these generated files manually.
48 
49### 3. Implement the Backend Handler
50 
51Create the RPC implementation in the backend. Handlers are located in `src/core/controller/[service-name]/`.
52 
53**File: `src/core/controller/ui/scrollToSettings.ts`**
54```typescript
55import { Controller } from ".."
56import { StringRequest, KeyValuePair } from "../../../shared/proto/common"
57 
58/**
59 * Executes a scroll to settings action
60 * @param controller The controller instance
61 * @param request The request containing the ID of the settings section to scroll to
62 * @returns KeyValuePair with action and value fields for the UI to process
63 */
64export async function scrollToSettings(controller: Controller, request: StringRequest): Promise<KeyValuePair> {
65	return KeyValuePair.create({
66		key: "scrollToSettings",
67		value: request.value || "",
68	})
69}
70```
71 
72### 4. Call the RPC from the Webview
73 
74Call the new RPC from a React component in `webview-ui/`. The generated client makes this simple.
75 
76**File: `webview-ui/src/components/browser/BrowserSettingsMenu.tsx`** (Example)
77```tsx
78import { UiServiceClient } from "../../../services/grpc"
79import { StringRequest } from "../../../../shared/proto/common"
80 
81// ... inside a React component
82const handleMenuClick = async () => {
83    try {
84        await UiServiceClient.scrollToSettings(StringRequest.create({ value: "browser" }))
85    } catch (error) {
86        console.error("Error scrolling to browser settings:", error)
87    }
88}
89```
90