docs/superpowers/specs/2026-08-11-yoresee-doc-sdk-migration-design.md

Yoresee Doc SDK Migration Design

Goal

Publish the protobuf-generated dependencies as two independent repositories under the YoreseeDoc Gitea organization and migrate the four services to consume those repositories:

• yoresee_doc_sdk_go for Go protobuf and gRPC stubs.
• yoresee_doc_sdk_node for browser ESM/Connect RPC stubs and Node.js CommonJS gRPC stubs.

The existing protobuf repository remains the single source of the .proto contract.

Scope

This is a dependency migration, not a code-generation or CI/CD redesign.

Included:

• Generate and commit Go, ESM, and CommonJS artifacts in the two SDK repos.
• Use the Gitea repositories as versioned service dependencies.
• Change service imports to the SDK package paths.
• Change the protobuf go_package to the canonical Go SDK module path.
• Add package documentation describing the generated outputs and source proto.

Explicitly unchanged:

• deploy/script/gen_proto.sh.
• Existing Dockerfiles and Docker Compose files.
• Existing local generated-code directories and their fallback generation.
• CI/CD workflow and registry setup.

The existing local generation may continue to produce unused compatibility artifacts during builds. It is intentionally left in place for this migration.

Public Package Contracts

Go

The Go SDK module path is:

git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go

Generated files live at:

yoresee_doc/v1/yoresee_doc.pb.go
yoresee_doc/v1/yoresee_doc_grpc.pb.go

The protobuf go_package is changed to:

git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go/yoresee_doc/v1;yoreseedocpb

The initial SDK release is v0.1.0. backend and collab-go pin this version instead of depending on the moving master branch.

Node.js

The package name is @yoresee-doc/sdk-node, installed from:

git+ssh://git@git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_node.git#v0.1.0

Generated output is split by runtime:

esm/yoresee_doc/v1/yoresee_doc_pb.js
esm/yoresee_doc/v1/yoresee_doc_connect.js
cjs/yoresee_doc/v1/yoresee_doc_pb.js
cjs/yoresee_doc/v1/yoresee_doc_grpc_pb.js

The package uses conditional exports and explicit esm/* and cjs/* subpaths. The cjs/ directory declares CommonJS module semantics so the root package can remain ESM-compatible.

Service import contracts are:

• frontend: @yoresee-doc/sdk-node/esm/yoresee_doc/v1/...
• collab: @yoresee-doc/sdk-node/cjs/yoresee_doc/v1/...

Runtime dependencies for both generated formats are declared by the SDK: @bufbuild/protobuf, @connectrpc/connect, @grpc/grpc-js, and google-protobuf.

Generation and Repository Boundaries

The generated files are committed to the SDK repositories because they are the published dependency artifacts. The source proto remains in the existing proto repository and is not duplicated into the SDK repositories.

Generation for this initial migration is performed from the checked-out proto source using the existing installed toolchains. The migration does not alter the existing project generation scripts. Each SDK README records the source proto commit and the generator versions used for the artifacts.

Service Migration

backend and collab-go replace local generated-package imports with the Go SDK import path and add the pinned Gitea module dependency. The services set GOPRIVATE in their build environment documentation where required by the private module.

frontend and collab add the pinned Git dependency and replace aliases or relative paths that point to local generated files with the Node SDK exports.

No service behavior or protobuf message/service definitions change.

Verification

The implementation is accepted only after all of the following checks pass:

• Go SDK generated package compiles and its module resolves at v0.1.0.
• Node SDK can be installed from the Gitea tag and both module formats load.
• backend and collab-go compile with the remote SDK dependency.
• frontend production build resolves the ESM/Connect exports.
• collab can load the CJS protobuf and gRPC exports.
• SDK repositories have clean commits pushed to master, with v0.1.0 tags.

Risks and Rollback

• Private Gitea dependencies require read access from developer and Docker/CI environments. A failed authenticated fetch is an environment issue, not a protobuf generation issue.
• The old local generation remains redundant and may continue to fail because its existing buf templates are outside this migration scope.
• Rollback consists of reverting service dependency/import changes and the protobuf go_package change; SDK repositories remain harmless additive artifacts.