stacklok / stacklok/mecatl

Add a generated gRPC API reference

Open
#712 5 comments 0 reactions 1 assignee View on GitHub

@Sanskarzz is already working on this.

Since Sep 17, 2026.

documentation good first issue
Dominant language
Go
Stars
152
Forks
16
Avg merge
14h 48m
Merged PRs (30d)
536

Description

Summary

Add a deterministic, generated gRPC schema reference for Mecatl's ordinary public API while keeping the existing handwritten guide focused on behavior and operational semantics.

This issue was narrowed after the recent TypeScript SDK and documentation work. The HTTP/OpenAPI portion is now tracked separately in #1706.

Scope

  • Generate a Docusaurus-compatible Markdown reference from:
    • contracts/proto/mecatl/v1/harness.proto (HarnessService)
    • contracts/proto/mecatl/v1/schedule.proto (ScheduleService)
  • Use a pinned Buf-compatible documentation plugin rather than a custom protobuf parser.
  • Write the committed generated page to user-docs/reference/grpc-schema.md.
  • Cover both services, every RPC, the messages and enums used by them, field comments, and unary/server-streaming/bidirectional-streaming directions.
  • Add a dedicated regeneration command, task docs:grpc-ref, and include it in task docs.
  • Add a non-mutating CI freshness check that fails when the committed page differs from regenerated output.
  • Link the generated schema reference from user-docs/reference/grpc-api.md and user-docs/building/deployment/grpc-http.md.
  • Clearly mark the page as generated and identify the proto files as its source.

Acceptance criteria

  • task docs:grpc-ref deterministically regenerates user-docs/reference/grpc-schema.md from the two protobuf contracts.
  • The generated page includes HarnessService, ScheduleService, every RPC, their streaming directions, and the messages/enums they use.
  • The existing handwritten gRPC guide remains the canonical home for authentication, error behavior, lifecycle guidance, and other semantics not encoded in protobuf descriptors.
  • The handwritten gRPC and transport pages link to the generated schema reference.
  • CI fails with a clear message when the generated page is stale.
  • task docs and task site:build pass.

Non-goals

  • HTTP, OpenAPI, or SSE documentation; see #1706.
  • Replacing or substantially rewriting the existing handwritten gRPC guide.
  • Changing protobuf or runtime behavior.
  • Generating client bindings.
  • Documenting the privileged LocalSessionContextService or the driver protocol under contracts/proto/mecatl/driver/v1.
  • Generating authentication rules or exhaustive status-code behavior that is not represented in the protobuf descriptors.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.