feat(ts): protobuf-es runtime mode for TS client/server (native messages + sebuf transport)

[hishamank]

What

Adds an opt-in ts_runtime=protobuf-es mode to protoc-gen-ts-client and protoc-gen-ts-server. In this mode, message types + JSON codec come from Buf's native protoc-gen-es (*_pb.ts), and sebuf generates only the HTTP transport on top — routing every request/response through create/toJson/fromJson(..., { ignoreUnknownFields: true }). This mirrors how Go uses protoc-gen-go + protoc-gen-go-http.

The existing hand-rolled mode stays the default — no behavior change unless ts_runtime=protobuf-es is passed.

Why

sebuf's Go output uses the language's native protobuf runtime, so it can't drift from protojson. The TS output hand-rolls message types with no codec, so it can silently disagree with the wire — e.g. a server omits zero-values per protojson, but the hand-rolled TS types declare them present, so resp.list.map(...) throws on an empty list. This brings TS into the native-runtime tier. It is not adopting Connect — sebuf keeps its own HTTP transport (paths, headers, ValidationError); only the message layer goes native.

How it works

• New ts_runtime=protobuf-es plugin option (invalid values fail loudly).
• es-mode skips emitting the hand-rolled type modules (protoc-gen-es owns them) but still emits the shared errors.ts.
• Messages import <Msg>Schema (value) + <Msg> (type) from ./<proto>_pb.js.
• The @bufbuild/protobuf import lists only the symbols actually used: each es-mode emission site records the helpers it prints (MessageInitShape/fromJson per method, create/toJson only when a body or response is encoded), so the import mirrors real usage and compiles under noUnusedLocals.
• Client: MessageInitShape<typeof ReqSchema> params; body: JSON.stringify(toJson(ReqSchema, create(ReqSchema, req))); fromJson(ResSchema, await resp.json(), { ignoreUnknownFields: true }).
• Server: fromJson request decode; toJson(create(ResSchema, result)) response encode; handler takes branded <Req>, returns MessageInitShape<...>.
• Unary and server-streaming (SSE) supported.

Review fixes (second round of commits)

A review pass found two real issues in the first iteration; both are fixed on this branch:

1. Latent hand-rolled @bufbuild/protobuf import (fixed in 8c1e4c1). The runtime-symbol import list was originally derived by regex-scanning the generated body, and the scan ran in both modes. An RPC literally named Create renders async create(, which matched \bcreate\b and injected import { create } from "@bufbuild/protobuf" into hand-rolled output — a package hand-rolled consumers don't install. A field named create in an es-mode GET method had the mirror problem: an unused import that fails noUnusedLocals. The body scan is now deleted; each es-mode emission site records exactly the helpers it prints, and NeedProtobufES is a no-op outside es mode as a structural invariant. Regression tests cover both failure modes (runtime_symbols_test.go in both generators), and all pre-existing goldens are byte-identical under the new tracking.
2. es output was never machine-typechecked (fixed in 96b33c9). The es goldens' typecheck was a manual verification, and it turned out the checked-in golden tree didn't actually compile: the fixtures' *_pb.ts import ./sebuf/http/annotations_pb.js, which was never checked in (TS2307). New TestTSClientGenESGoldenTypecheck / TestTSServerGenESGoldenTypecheck run tsc --noEmit (strict nodenext + noUnusedLocals, via the ported tscommon/typecheck harness) over testdata/golden/es against the real @bufbuild/protobuf package, skipping cleanly when the toolchain is absent. The missing annotations_pb.ts goldens are now checked in. This is also the machine guard for ESQualifiedName drift: a symbol-name divergence from protoc-gen-es now fails CI with a TS2724: no exported member error instead of surfacing in a consumer build (verified by fault injection).

Also documented (5854efd): URL path/query params do not route through the codec (only bodies and SSE events do — by design, URL params have no protojson form), and MessageInitShape makes all request fields optional, so a missing path param compiles and only surfaces as a runtime "undefined" URL segment.

Tests / verification

• go test ./..., gofmt, vet, staticcheck all green.
• Hand-rolled default mode is byte-identical (all pre-existing goldens unchanged; new golden coverage lives under testdata/golden/es/).
• es goldens are typechecked in CI (tsc --noEmit, strict nodenext, noUnusedLocals) against the real @bufbuild/protobuf package — no longer a manual claim.
• Regression tests assert hand-rolled output never imports @bufbuild/protobuf (RPC named Create) and that es-mode imports only the runtime symbols actually used (GET method with a field named create).
• Wire-conformance test proves: omitted zero-values are materialized on decode (scalars → 0/""/false, lists → []), and unknown fields don't throw (ignoreUnknownFields) — but do throw without the flag.
• Golden es tests cover unary POST, GET, and server-streaming (SSE); a non-enum GET fixture and enum-param rejection are asserted.

Known limitations (documented in docs/client-generation.md)

• Enum path/query parameters are not yet supported in es-mode (protobuf-es enums are numeric; string↔enum conversion isn't implemented). The generator fails loudly at generation time rather than emitting uncompilable code.
• RPC I/O should be top-level messages (nested names reconciled via ESQualifiedName, verified against @bufbuild/protoc-gen-es@2.12.1; the es golden typecheck catches drift on other versions).
• URL parameters bypass the codec (string-coerced from the init shape) and path params are not compile-time required under MessageInitShape — see docs.

Base

Targets feat/ts-modules-oneof-integration (the merged #199 + #200 result) since the es transport reuses that modules-layout import machinery. Rebase onto main once those land.

🤖 Generated with Claude Code