M7: Verified Swift/C#/TypeScript codegen with minimal connect+GetStatus examples #206

New Issue

2026-07-28T14:04:55Z

KofTwentyTwo commented

2026-07-28 14:04:55 +00:00

(Migrated from github.com)

Context

Story for milestone M7. Read docs/STORY-WORKFLOW.md first — it defines the process, gates, and patterns; this issue defines only the specific work.

crates/nuncio-proto/proto/README.md already documents, in prose, the exact protoc/Grpc.Tools/ts-proto/connect-es invocations a Swift, C#, or TypeScript client would need to generate stubs from nuncio/v1/nuncio.proto, plus the loopback-address, bearer-token, and Subscribe streaming contract every client must honor (README lines 23-117). None of those three commands have ever actually been run and checked in against this repo — the instructions are unverified prose. Since M7 is the gate that lets separate front-end repos (Swift/macOS, C#/WinUI, TypeScript/MCP bridge — see roadmap Phase 5) start building against this contract, this story turns "here's a command that should work" into "here's proof it works, plus a minimal working example."

Goal

For each of Swift (grpc-swift), C# (Grpc.Tools), and TypeScript (ts-proto or connect-es): actually run the documented codegen against proto/nuncio/v1/nuncio.proto, commit the generated stubs (or a documented regeneration script if the generated output is large/gitignored, matching that ecosystem's convention), and write a minimal example program that dials 127.0.0.1:9420, attaches an authorization: Bearer <token> header, calls System/GetStatus, and prints the response. This is explicitly verification and documentation work, not Rust engine work — none of it touches nunciod, the wire contract, or anything gated by cargo verify in the three non-Rust languages; say so plainly in the PR rather than implying otherwise.

Files to touch / patterns to mirror

crates/nuncio-proto/proto/README.md — expand each language section (Swift lines 53-69, C# lines 71-88, TypeScript lines 90-117) with the actual verified command transcript and a link to its example.
New directory crates/nuncio-proto/examples/swift/ — generated grpc-swift stubs (or a generate.sh if grpc-swift's convention is to gitignore generated code and regenerate on build) + a GetStatusExample.swift (or minimal SwiftPM package) that connects and prints the response.
New directory crates/nuncio-proto/examples/csharp/ — a minimal .csproj referencing nuncio.proto via the documented <Protobuf Include=...> MSBuild item, plus a Program.cs doing the same connect+GetStatus call.
New directory crates/nuncio-proto/examples/typescript/ — a package.json pinning the chosen generator (ts-proto or connect-es/buf), generated output (or a buf.gen.yaml + regeneration script), and an index.ts doing the same call.
These three directories are not Cargo crates and are not added to the workspace members list in the root Cargo.toml — they must not affect cargo build --workspace or cargo verify at all.

Implementation steps

Pick concrete, pinned toolchain versions for each language (a Swift toolchain + grpc-swift/grpc-swift-protobuf version; a .NET SDK + Grpc.Tools/Grpc.Net.Client NuGet version; a Node version + ts-proto or @bufbuild/protoc-gen-es/@connectrpc/protoc-gen-connect-es version) and record them in the README.
Swift: run the protoc --swift_out=... --grpc-swift_out=... --proto_path=. nuncio/v1/nuncio.proto command from README lines 58-63 against the real .proto file; capture the exact command and its output in the PR body; commit the generated .swift files (or the regeneration script, if the grpc-swift convention for the toolchain version chosen is SwiftPM build-plugin codegen rather than committed output — verify which applies for the pinned version and document the choice). Write GetStatusExample.swift: build a GRPCChannelPool/ClientTransport to 127.0.0.1:9420 (plaintext, per README's documented "never TLS-wrapped" contract), attach authorization: Bearer <token> as a call header (token read from an environment variable in the example, since no cross-language OS-keyring reader ships with this repo — say this explicitly, do not fabricate a working keyring integration), call GetStatus, print engine_status/version.
C#: create the minimal .csproj with the <Protobuf Include="nuncio/v1/nuncio.proto" GrpcServices="Client" ProtoRoot="nuncio/v1" /> item from README lines 79-82, referencing nuncio.proto via a relative path/link back into crates/nuncio-proto/proto/; run dotnet build and capture the transcript proving MSBuild's Grpc.Tools integration actually generated the client; write Program.cs doing the same connect+bearer-token+GetStatus+print sequence (token from an environment variable, same caveat as above).
TypeScript: run either the ts-proto or buf generate command from README lines 100-111 against the real .proto; commit the generated output (or the buf.gen.yaml + a npm run generate script, whichever matches the chosen generator's convention) and capture the transcript; write index.ts doing the same call over @grpc/grpc-js or the Connect transport, printing the response.
Update proto/README.md: under each language's existing section, add a short "Verified" subsection with the exact commands run, the toolchain versions, and a link to the corresponding examples/<lang>/ directory.
Confirm none of this perturbs the Rust workspace: cargo verify must still be green with zero changes to its output, proving these new directories are inert from Cargo's perspective.

Acceptance criteria

crates/nuncio-proto/examples/swift/, examples/csharp/, and examples/typescript/ each exist, each contains generated stubs (or a documented, checked-in regeneration script) plus a minimal GetStatus-calling example program.
crates/nuncio-proto/proto/README.md documents, per language, the exact command(s) actually run (with real output/version numbers, not paraphrased), matching what's committed under examples/.
The PR body pastes the real terminal transcripts for all three codegen runs (protoc/dotnet build/ts-proto or buf) — evidence the commands were executed, not just written down.
Each example explicitly documents that the bearer token is read from an environment variable for demo purposes, and that a real client still needs its own way to read the daemon's OS-keyring grpc-bearer-token entry (per README's existing "What you need before generating anything" section) — no fabricated keyring integration.
cargo verify green and unaffected (fmt + clippy -D warnings all-targets + test-all), 0 ignored — these new directories add zero Rust code and are not workspace members.

Definition of done & process

Follow docs/STORY-WORKFLOW.md for the parts that do touch Rust (none of the wire contract, but the workspace-inertness check above): no fabricated data; comment convention (intent-only, no story/GH/phase refs) in any .rs/.proto touched; branch story/m7-s2-codegen-verification off dev; PR to dev with both the cargo verify output and the three codegen transcripts pasted as evidence; the PO reviews before the issue is closed. Note explicitly in the PR description that the Swift/C#/TypeScript portions are verification/documentation deliverables, not gated by cargo test-all — say what was actually run and observed, matching the anti-fabrication rule even outside Rust.

Dependencies / notes

Not a [PROTO] story — reads nuncio.proto and descriptor.bin but does not modify them, so it can run in parallel with any proto-touching story. Depends on nothing else in M7. Requires local availability of a Swift toolchain, a .NET SDK, and Node — if any of these three is genuinely unavailable to the assigned contributor's environment, report that honestly as BLOCKED for that one language rather than fabricating its transcript; do not skip silently. Size M.

## Context Story for milestone M7. **Read [`docs/STORY-WORKFLOW.md`](https://github.com/KofTwentyTwo/nuncio/blob/dev/docs/STORY-WORKFLOW.md) first** — it defines the process, gates, and patterns; this issue defines only the specific work. `crates/nuncio-proto/proto/README.md` already documents, in prose, the exact `protoc`/`Grpc.Tools`/`ts-proto`/`connect-es` invocations a Swift, C#, or TypeScript client would need to generate stubs from `nuncio/v1/nuncio.proto`, plus the loopback-address, bearer-token, and `Subscribe` streaming contract every client must honor (README lines 23-117). None of those three commands have ever actually been run and checked in against this repo — the instructions are unverified prose. Since M7 is the gate that lets separate front-end repos (Swift/macOS, C#/WinUI, TypeScript/MCP bridge — see roadmap Phase 5) start building against this contract, this story turns "here's a command that should work" into "here's proof it works, plus a minimal working example." ## Goal For each of Swift (grpc-swift), C# (Grpc.Tools), and TypeScript (ts-proto or connect-es): actually run the documented codegen against `proto/nuncio/v1/nuncio.proto`, commit the generated stubs (or a documented regeneration script if the generated output is large/gitignored, matching that ecosystem's convention), and write a minimal example program that dials `127.0.0.1:9420`, attaches an `authorization: Bearer <token>` header, calls `System/GetStatus`, and prints the response. This is explicitly **verification and documentation work, not Rust engine work** — none of it touches `nunciod`, the wire contract, or anything gated by `cargo verify` in the three non-Rust languages; say so plainly in the PR rather than implying otherwise. ## Files to touch / patterns to mirror - `crates/nuncio-proto/proto/README.md` — expand each language section (Swift lines 53-69, C# lines 71-88, TypeScript lines 90-117) with the actual verified command transcript and a link to its example. - New directory `crates/nuncio-proto/examples/swift/` — generated grpc-swift stubs (or a `generate.sh` if grpc-swift's convention is to gitignore generated code and regenerate on build) + a `GetStatusExample.swift` (or minimal SwiftPM package) that connects and prints the response. - New directory `crates/nuncio-proto/examples/csharp/` — a minimal `.csproj` referencing `nuncio.proto` via the documented `<Protobuf Include=...>` MSBuild item, plus a `Program.cs` doing the same connect+GetStatus call. - New directory `crates/nuncio-proto/examples/typescript/` — a `package.json` pinning the chosen generator (`ts-proto` or `connect-es`/`buf`), generated output (or a `buf.gen.yaml` + regeneration script), and an `index.ts` doing the same call. - These three directories are **not** Cargo crates and are **not** added to the workspace `members` list in the root `Cargo.toml` — they must not affect `cargo build --workspace` or `cargo verify` at all. ## Implementation steps 1. Pick concrete, pinned toolchain versions for each language (a Swift toolchain + grpc-swift/grpc-swift-protobuf version; a .NET SDK + `Grpc.Tools`/`Grpc.Net.Client` NuGet version; a Node version + `ts-proto` or `@bufbuild/protoc-gen-es`/`@connectrpc/protoc-gen-connect-es` version) and record them in the README. 2. Swift: run the `protoc --swift_out=... --grpc-swift_out=... --proto_path=. nuncio/v1/nuncio.proto` command from README lines 58-63 against the real `.proto` file; capture the exact command and its output in the PR body; commit the generated `.swift` files (or the regeneration script, if the grpc-swift convention for the toolchain version chosen is SwiftPM build-plugin codegen rather than committed output — verify which applies for the pinned version and document the choice). Write `GetStatusExample.swift`: build a `GRPCChannelPool`/`ClientTransport` to `127.0.0.1:9420` (plaintext, per README's documented "never TLS-wrapped" contract), attach `authorization: Bearer <token>` as a call header (token read from an environment variable in the example, since no cross-language OS-keyring reader ships with this repo — say this explicitly, do not fabricate a working keyring integration), call `GetStatus`, print `engine_status`/`version`. 3. C#: create the minimal `.csproj` with the `<Protobuf Include="nuncio/v1/nuncio.proto" GrpcServices="Client" ProtoRoot="nuncio/v1" />` item from README lines 79-82, referencing `nuncio.proto` via a relative path/link back into `crates/nuncio-proto/proto/`; run `dotnet build` and capture the transcript proving MSBuild's `Grpc.Tools` integration actually generated the client; write `Program.cs` doing the same connect+bearer-token+GetStatus+print sequence (token from an environment variable, same caveat as above). 4. TypeScript: run either the `ts-proto` or `buf generate` command from README lines 100-111 against the real `.proto`; commit the generated output (or the `buf.gen.yaml` + a `npm run generate` script, whichever matches the chosen generator's convention) and capture the transcript; write `index.ts` doing the same call over `@grpc/grpc-js` or the Connect transport, printing the response. 5. Update `proto/README.md`: under each language's existing section, add a short "Verified" subsection with the exact commands run, the toolchain versions, and a link to the corresponding `examples/<lang>/` directory. 6. Confirm none of this perturbs the Rust workspace: `cargo verify` must still be green with zero changes to its output, proving these new directories are inert from Cargo's perspective. ## Acceptance criteria - [ ] `crates/nuncio-proto/examples/swift/`, `examples/csharp/`, and `examples/typescript/` each exist, each contains generated stubs (or a documented, checked-in regeneration script) plus a minimal `GetStatus`-calling example program. - [ ] `crates/nuncio-proto/proto/README.md` documents, per language, the exact command(s) actually run (with real output/version numbers, not paraphrased), matching what's committed under `examples/`. - [ ] The PR body pastes the real terminal transcripts for all three codegen runs (protoc/dotnet build/ts-proto or buf) — evidence the commands were executed, not just written down. - [ ] Each example explicitly documents that the bearer token is read from an environment variable for demo purposes, and that a real client still needs its own way to read the daemon's OS-keyring `grpc-bearer-token` entry (per README's existing "What you need before generating anything" section) — no fabricated keyring integration. - [ ] `cargo verify` green and unaffected (fmt + clippy `-D warnings` all-targets + test-all), 0 ignored — these new directories add zero Rust code and are not workspace members. ## Definition of done & process Follow [`docs/STORY-WORKFLOW.md`](https://github.com/KofTwentyTwo/nuncio/blob/dev/docs/STORY-WORKFLOW.md) for the parts that do touch Rust (none of the wire contract, but the workspace-inertness check above): no fabricated data; comment convention (intent-only, no story/GH/phase refs) in any `.rs`/`.proto` touched; branch `story/m7-s2-codegen-verification` off `dev`; PR to `dev` with both the `cargo verify` output and the three codegen transcripts pasted as evidence; the PO reviews before the issue is closed. Note explicitly in the PR description that the Swift/C#/TypeScript portions are verification/documentation deliverables, not gated by `cargo test-all` — say what was actually run and observed, matching the anti-fabrication rule even outside Rust. ## Dependencies / notes Not a `[PROTO]` story — reads `nuncio.proto` and `descriptor.bin` but does not modify them, so it can run in parallel with any proto-touching story. Depends on nothing else in M7. Requires local availability of a Swift toolchain, a .NET SDK, and Node — if any of these three is genuinely unavailable to the assigned contributor's environment, report that honestly as BLOCKED for that one language rather than fabricating its transcript; do not skip silently. Size M.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/nuncio#206