Align docs with StyleGuide and add CLAUDE.md

- Rename 16 kebab-case docs to PascalCase per StyleGuide - Move per-language client design docs from docs/ to clients/<lang>/ alongside their READMEs - Add ## Related Documentation sections to 15 docs that lacked one - Fix sentence-case violations in H3 headings (StyleGuide rule) - Update cross-references in gateway.md, client READMEs, scripts, and generate-proto.ps1 helpers to follow the new paths - Add CLAUDE.md with build/test commands, the source-update verification matrix, the parity-first contract, and pointers to MXAccess and Galaxy Repository analysis sources Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-30 10:19:22 -04:00
parent 133c83029b
commit 51a9dadf62
45 changed files with 522 additions and 134 deletions
@@ -0,0 +1,396 @@
+# Client Libraries Implementation Plan
+
+This plan implements the official gRPC clients after the gateway and worker
+first slice is stable enough to generate contracts and run smoke tests.
+
+Primary designs:
+
+- `docs/ClientLibrariesDesign.md`
+- `clients/dotnet/DotnetClientDesign.md`
+- `clients/go/GoClientDesign.md`
+- `clients/rust/RustClientDesign.md`
+- `clients/python/PythonClientDesign.md`
+- `clients/java/JavaClientDesign.md`
+- `docs/ToolchainLinks.md`
+
+## Shared Milestone: client-contracts-and-fixtures
+
+Goal: make client implementations consistent across languages.
+
+### Issue: Publish Stable Client Proto Generation Inputs
+
+Labels: `area:contracts`, `type:feature`, `priority:p0`
+
+Deliverables:
+
+- finalized v1 `.proto` files,
+- Buf config if used,
+- generation documentation for all languages,
+- generated-code output directories,
+- golden protobuf payload fixtures.
+
+Acceptance criteria:
+
+- C#, Go, Rust, Python, and Java generated code can be regenerated,
+- generated code is not hand-edited,
+- protocol version is visible to clients.
+
+### Issue: Create Cross-Language Client Behavior Fixtures
+
+Labels: `area:tests`, `type:test`, `priority:p0`
+
+Deliverables:
+
+- JSON fixtures for command replies,
+- JSON fixtures for event stream samples,
+- value conversion fixtures,
+- status conversion fixtures,
+- auth error fixtures,
+- timeout/cancel expected behavior notes.
+
+Acceptance criteria:
+
+- every language can use the same fixture set,
+- fixtures include raw fallback values,
+- fixtures include MXAccess status arrays and HRESULT.
+
+## Milestone: clients-dotnet
+
+Goal: implement the .NET 10 C# client library, test CLI, and tests.
+
+### Issue: Scaffold .NET Client Projects
+
+Labels: `area:client-dotnet`, `type:infra`, `priority:p0`
+
+Deliverables:
+
+- `clients/dotnet/MxGateway.Client`,
+- `clients/dotnet/MxGateway.Client.Cli`,
+- `clients/dotnet/MxGateway.Client.Tests`,
+- optional integration test project,
+- generated protobuf setup.
+
+Acceptance criteria:
+
+- `dotnet build` succeeds,
+- generated gRPC client code compiles,
+- empty tests run.
+
+### Issue: Implement .NET GatewayClient And Session
+
+Labels: `area:client-dotnet`, `type:feature`, `priority:p0`
+
+Deliverables:
+
+- `MxGatewayClientOptions`,
+- `MxGatewayClient`,
+- `MxGatewaySession`,
+- raw `OpenSession`, `CloseSession`, `Invoke`, `StreamEvents`,
+- helpers for `Register`, `AddItem`, `AddItem2`, `Advise`, `Write`.
+
+Acceptance criteria:
+
+- API key metadata is attached,
+- cancellation token flows to every call,
+- raw replies remain accessible,
+- session close is explicit and idempotent.
+
+Tests:
+
+- fake gRPC service,
+- helper request construction,
+- cancellation.
+
+### Issue: Implement .NET Values, Status, Errors, And CLI
+
+Labels: `area:client-dotnet`, `type:feature`, `priority:p1`
+
+Deliverables:
+
+- `MxValue` helper conversions,
+- status proxy helpers,
+- typed exceptions,
+- `EnsureProtocolSuccess`,
+- `EnsureMxAccessSuccess`,
+- CLI commands: version, ping, open-session, close-session, register,
+  add-item, advise, stream-events, write, write2, smoke,
+- JSON CLI output.
+
+Acceptance criteria:
+
+- scalar and array conversions pass fixtures,
+- status arrays are preserved,
+- API keys are redacted,
+- smoke command closes session in `finally`.
+
+## Milestone: clients-go
+
+Goal: implement the Go module, test CLI, and tests.
+
+### Issue: Scaffold Go Module
+
+Labels: `area:client-go`, `type:infra`, `priority:p0`
+
+Deliverables:
+
+- `clients/go/go.mod`,
+- generated protobuf package,
+- `mxgateway` package,
+- `cmd/mxgw-go`,
+- unit test structure.
+
+Acceptance criteria:
+
+- `go test ./...` runs,
+- generated code compiles,
+- module path is stable.
+
+### Issue: Implement Go Client, Session, Values, Errors, And CLI
+
+Labels: `area:client-go`, `type:feature`, `priority:p0`
+
+Deliverables:
+
+- `Dial(ctx, Options)`,
+- auth interceptors,
+- TLS/plaintext setup,
+- `Client.OpenSession`,
+- `Session` helpers,
+- event channel receive loop,
+- value conversion helpers,
+- typed errors with `errors.As`,
+- CLI commands and JSON output.
+
+Acceptance criteria:
+
+- auth metadata on unary and streams,
+- context cancellation stops calls,
+- event channel closes exactly once,
+- raw protobuf access remains available,
+- fixture conversions pass,
+- CLI redacts API key.
+
+Tests:
+
+- `bufconn` fake service,
+- auth metadata,
+- stream cancellation,
+- conversion fixtures,
+- CLI parser/output.
+
+## Milestone: clients-rust
+
+Goal: implement the Rust `tonic` client crate, test CLI, and tests.
+
+### Issue: Scaffold Rust Workspace
+
+Labels: `area:client-rust`, `type:infra`, `priority:p0`
+
+Deliverables:
+
+- `clients/rust/Cargo.toml`,
+- client crate,
+- CLI crate,
+- `build.rs` protobuf generation,
+- generated module organization.
+
+Acceptance criteria:
+
+- `cargo test` runs,
+- generated code compiles,
+- MSVC linker works.
+
+### Issue: Implement Rust Client, Session, Values, Errors, And CLI
+
+Labels: `area:client-rust`, `type:feature`, `priority:p0`
+
+Deliverables:
+
+- `ClientOptions`,
+- `GatewayClient::connect`,
+- auth interceptor,
+- TLS/plaintext channel,
+- session helpers,
+- event stream as `Stream<Item = Result<MxEvent, Error>>`,
+- `thiserror` error model,
+- conversion helpers,
+- `clap` CLI,
+- JSON output with `serde_json`.
+
+Acceptance criteria:
+
+- metadata includes bearer key,
+- dropped stream cancels underlying stream,
+- raw generated client remains reachable where needed,
+- fixture tests pass,
+- command errors keep raw reply,
+- API key is redacted from debug output.
+
+Tests:
+
+- fake tonic server,
+- auth tests,
+- stream order/cancel,
+- conversion fixtures,
+- CLI parser/output.
+
+## Milestone: clients-python
+
+Goal: implement the async Python client package, test CLI, and tests.
+
+### Issue: Scaffold Python Package
+
+Labels: `area:client-python`, `type:infra`, `priority:p0`
+
+Deliverables:
+
+- `clients/python/pyproject.toml`,
+- `src/mxgateway`,
+- generated protobuf modules,
+- `src/mxgateway_cli`,
+- `tests`.
+
+Acceptance criteria:
+
+- package installs editable,
+- generated stubs import,
+- `pytest` runs.
+
+### Issue: Implement Python Async Client, Values, Errors, And CLI
+
+Labels: `area:client-python`, `type:feature`, `priority:p0`
+
+Deliverables:
+
+- async `GatewayClient`,
+- async `Session`,
+- auth metadata helper,
+- TLS/plaintext setup,
+- async event iterator,
+- method helpers,
+- value conversion helpers,
+- typed exceptions,
+- `click` or `typer` CLI,
+- JSON output.
+
+Acceptance criteria:
+
+- API key metadata included,
+- async cancellation cancels stream/call,
+- raw protobuf replies available,
+- fixture conversions pass,
+- secrets redacted.
+
+Tests:
+
+- fake async stub tests,
+- metadata tests,
+- cancellation tests,
+- conversion fixtures,
+- CLI parser/output.
+
+## Milestone: clients-java
+
+Goal: implement Java client library, CLI, and tests.
+
+### Issue: Scaffold Java Gradle Build
+
+Labels: `area:client-java`, `type:infra`, `priority:p0`
+
+Deliverables:
+
+- `clients/java/settings.gradle`,
+- `mxgateway-client` project,
+- `mxgateway-cli` project,
+- protobuf/gRPC Gradle generation,
+- JUnit test setup.
+
+Acceptance criteria:
+
+- `gradle test` runs,
+- generated code compiles,
+- Java 21 toolchain used.
+
+### Issue: Implement Java Client, Session, Values, Errors, And CLI
+
+Labels: `area:client-java`, `type:feature`, `priority:p0`
+
+Deliverables:
+
+- `MxGatewayClientOptions`,
+- `MxGatewayClient`,
+- `MxGatewaySession`,
+- auth interceptor,
+- plaintext/TLS channels,
+- blocking and async event stream options,
+- method helpers,
+- value conversion helpers,
+- typed exceptions,
+- `picocli` CLI,
+- JSON output.
+
+Acceptance criteria:
+
+- unary and streaming calls carry auth metadata,
+- deadlines are applied,
+- stream cancellation works,
+- raw generated messages are accessible,
+- fixture tests pass,
+- CLI redacts secrets.
+
+Tests:
+
+- in-process gRPC tests,
+- auth interceptor,
+- stream cancellation,
+- conversion fixtures,
+- CLI parser/output.
+
+## Milestone: integration-and-parity
+
+Goal: prove clients can talk to the gateway consistently.
+
+### Issue: Cross-Language Smoke Test Matrix
+
+Labels: `area:tests`, `type:test`, `priority:p1`
+
+Deliverables:
+
+- common smoke script or documented commands,
+- each client runs open/register/add/advise/stream/close,
+- JSON output comparison,
+- optional write test.
+
+Acceptance criteria:
+
+- each client has equivalent smoke behavior,
+- each client skips integration unless `MXGATEWAY_INTEGRATION=1`,
+- failed smoke output includes endpoint, language, and redacted auth context.
+
+### Issue: Client Packaging Documentation
+
+Labels: `area:docs`, `type:docs`, `priority:p2`
+
+Deliverables:
+
+- install instructions per client,
+- generation instructions,
+- CLI usage examples,
+- TLS/API key examples,
+- integration test instructions.
+
+Acceptance criteria:
+
+- new developer can build each client from a clean checkout using
+  `docs/ToolchainLinks.md`,
+- generated code command is documented for every language.
+
+
+## Related Documentation
+
+- [Implementation Plan Index](./ImplementationPlanIndex.md)
+- [Client Libraries Detailed Design](./ClientLibrariesDesign.md)
+- [Client Proto Generation](./ClientProtoGeneration.md)
+- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
+- [Client Packaging](./ClientPackaging.md)
+- [Cross-Language Smoke Matrix](./CrossLanguageSmokeMatrix.md)