# Proto Codegen

This repo uses [Buf](https://buf.build) to compile `.proto` files into TypeScript. Each API package runs codegen locally and commits the output — CI does **not** regenerate.

## Packages

| Package                 | Path                        | Plugin(s)                                 |
| ----------------------- | --------------------------- | ----------------------------------------- |
| `@coda/admin-api`       | `packages/admin-api/`       | `protoc-gen-es`                           |
| `@coda/search-api`      | `packages/search-api/`      | `protoc-gen-es` + `protoc-gen-connect-es` |
| `@coda/runner-api`      | `packages/runner-api/`      | `protoc-gen-es` + `protoc-gen-connect-es` |
| `@coda/datasources-api` | `packages/datasources-api/` | `protoc-gen-es`                           |
| `@coda/tools-api`       | `packages/tools-api/`       | `protoc-gen-es`                           |
| `@coda/dashboards-api`  | `packages/dashboards-api/`  | `protoc-gen-es`                           |

`protoc-gen-es` generates message types (`*_pb.ts`). `protoc-gen-connect-es` generates service descriptors (`*_connect.ts`) needed for ConnectRPC clients and servers. The admin-api and message-only packages define messages only, so they don't need the connect plugin.

## Layout

Each package follows the same structure:

```
packages/<name>-api/
  proto/           # source .proto files — edit these
    <domain>/v1/
      *.proto
  gen/             # generated TypeScript — committed, do not edit by hand
    <domain>/v1/
      *_pb.ts
      *_connect.ts   # search-api and runner-api only
  buf.yaml         # Buf module config (points to proto/)
  buf.gen.yaml     # codegen config (plugins, output dir)
```

## How to regenerate

After editing any `.proto` file, regenerate the corresponding package:

```bash
# Single package
pnpm --filter @coda/admin-api        buf:generate
pnpm --filter @coda/search-api       buf:generate
pnpm --filter @coda/runner-api       buf:generate
pnpm --filter @coda/datasources-api  buf:generate
pnpm --filter @coda/tools-api        buf:generate
pnpm --filter @coda/dashboards-api   buf:generate

# All four at once
pnpm --filter "@coda/*-api" buf:generate
```

Buf resolves plugins from the package's own `node_modules/.bin/`, so no global install is needed — just run `pnpm install` first.

After regenerating, stage both the `.proto` changes and the updated `gen/` files in the same commit.

## When to regenerate

Regenerate whenever you:

- Add, remove, or rename a message field
- Add or remove an RPC method or service
- Change a field type or option

You do **not** need to regenerate when changing TypeScript source in `src/` — that directory is handwritten and independent of codegen.

## Adding a new proto package

See [adding-a-package.md](adding-a-package.md) for the full guide. The short version: copy the `buf.yaml` / `buf.gen.yaml` from an existing API package, add the appropriate plugin devDependencies, then run `buf:generate`.