Buf proto update

.gitignore

@@ -1,2 +1,7 @@
 .idea
-bin
+bin
+
+.claude/
+draft.txt
+
+testdata/buf/

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "api/_third_party/protobuf"]
 	path = api/_third_party/protobuf
 	url = https://github.com/protocolbuffers/protobuf.git
+[submodule "api/_third_party/buf-v1.69.0"]
+	path = api/_third_party/buf-v1.69.0
+	url = https://github.com/bufbuild/buf

.planning/PROJECT.md

@@ -0,0 +1,82 @@
+# EasyP Buf Proxy — Protocol Modernization
+
+## What This Is
+
+A Go-based proxy server that translates Buf CLI registry requests into VCS API calls (GitHub, BitBucket, local git). The server currently implements the deprecated Buf `registry.v1alpha1` protocol (last compatible version: buf v1.30.1) via Connect RPC. We are adding support for the modern Buf protocol (v1.69.0+) while keeping the old protocol active for backward compatibility.
+
+## Core Value
+
+The proxy must correctly serve both old (v1.30.1) and modern (v1.69.0+) Buf CLI clients simultaneously, so that existing users are not broken during migration.
+
+## Requirements
+
+### Validated
+
+- ✓ Buf registry proxy for deprecated `registry.v1alpha1` protocol — existing
+- ✓ Multi-provider architecture (local git, GitHub, BitBucket) — existing
+- ✓ Cache layer (noop, local filesystem, Artifactory) — existing
+- ✓ TLS with optional mTLS support — existing
+- ✓ Structured logging with sensitive header masking — existing
+
+### Active
+
+- [ ] Test suite verifying the server works correctly with buf v1.30.1 (old protocol) using real `buf` binary + TLS server + real GitHub API
+- [ ] Modern Buf protocol (v1.69.0) implemented alongside the existing deprecated protocol — both served simultaneously
+- [ ] Test suite verifying the server works correctly with buf v1.69.0+ (modern protocol) using real `buf` binary + TLS server + real GitHub API
+
+### Out of Scope
+
+- BitBucket provider testing — GitHub provider is sufficient for validation
+- Local git provider testing — not needed for protocol validation
+- Removing the old v1alpha1 protocol — both protocols must coexist
+- Artifactory cache testing — not relevant to protocol correctness
+- UI changes — this is a backend-only project
+
+## Context
+
+- The existing codebase uses Connect RPC (`connectrpc.com/connect` v1.11.1) to implement Buf's `registry.v1alpha1` gRPC-compatible services
+- Modern Buf proto definitions are already available at `api/_third_party/buf-v1.69.0/proto/buf/` (git submodule)
+- The old proto definitions are at `api/_third_party/buf/` — these generated the current `gen/proto/` code
+- Code generation is done via `buf generate` configured in `api/proto/buf.gen.yaml` using go, go-grpc, and connect-go plugins
+- TLS certs for local testing are at `~/local-tls/server/` (self-signed, added to local CA)
+- The server is stateless — no database, relies on external VCS APIs and optional caching
+- Go version is 1.22
+
+## Constraints
+
+- **Tech Stack**: Go 1.22, Connect RPC, protobuf — must stay within existing stack
+- **Protocol Compatibility**: Old protocol must continue working unchanged while new protocol is added
+- **Proto Definitions**: Modern protocol proto files are already available in the repo as a git submodule
+- **TLS**: Required for all tests — buf CLI mandates TLS. Use `~/local-tls/server/` certs
+- **Testing**: Use real `buf` CLI binaries (v1.30.1 and v1.69.0+) against a real TLS server hitting the real GitHub API
+- **GitHub API**: Tests require a valid GitHub token configured in test environment
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Both protocols active simultaneously | Backward compatibility — existing clients must not break during migration | — Pending |
+| GitHub-only provider testing | GitHub is the primary provider; testing one real provider is sufficient for protocol validation | — Pending |
+| Real buf binary + real server + TLS for tests | Tests must prove the actual buf CLI can communicate with the proxy — anything less wouldn't catch protocol issues | — Pending |
+| Proto diff as part of work | We don't know exact differences between old and new protocol — will analyze during research/planning | — Pending |
+| buf v1.69.0 content-type mismatch | Modern buf expects `application/proto` but proxy returns `text/plain; charset=utf-8` — Connect RPC protocol version difference | Escalated to Phase 5 |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd-transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd-complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-05-07 after Phase 2 completion*

.planning/REQUIREMENTS.md

@@ -0,0 +1,96 @@
+# Requirements: EasyP Buf Proxy — Protocol Modernization
+
+**Defined:** 2026-05-07
+**Core Value:** The proxy must correctly serve both old (v1.30.1) and modern (v1.69.0+) Buf CLI clients simultaneously
+
+## v1 Requirements
+
+### Build & Code Generation
+
+- [ ] **BCG-01**: Proto source switched from old `buf` submodule to `buf-v1.69.0` submodule in `api/proto/generate.go`
+- [ ] **BCG-02**: connect-go upgraded to v1.18.1 in `go.mod`
+- [ ] **BCG-03**: `gen/proto/` regenerated from v1.69.0 proto definitions and project compiles without errors
+- [ ] **BCG-04**: go-grpc plugin removed from `api/proto/buf.gen.yaml` codegen pipeline (unused at runtime)
+
+### Handler Adaptation
+
+- [ ] **HAND-01**: Handler structs updated to embed new `Unimplemented*` types from regenerated code
+- [ ] **HAND-02**: Existing RPC logic (`GetModulePins`, `DownloadManifestAndBlobs`, `GetRepositoryByFullName`, `GetRepositoriesByFullName`) works correctly with new generated types
+- [ ] **HAND-03**: `manifest_digest` field populated on `ModulePin` responses if modern buf CLI requires it
+- [ ] **HAND-04**: `GetSDKInfo` RPC returns appropriate response or `CodeUnimplemented` based on modern buf CLI behavior
+
+### Test Infrastructure
+
+- [ ] **TINF-01**: Test helper programmatically starts and stops the proxy server with TLS using `~/local-tls/server/` certs
+- [ ] **TINF-02**: Buf binary v1.30.1 and v1.69.0+ pinned and managed for test execution (downloaded or path-configured)
+- [ ] **TINF-03**: Test suite configured with GitHub API token for real API calls
+- [ ] **TINF-04**: Test GitHub repository identified/configured for test operations (repo with proto files)
+- [ ] **TINF-05**: Tests can run in parallel without port conflicts or state interference
+- [ ] **TINF-06**: Test configuration supports CI execution with environment-based setup
+
+### Old Protocol Validation (buf v1.30.1)
+
+- [ ] **OLD-01**: `buf mod update` succeeds against the proxy using buf v1.30.1 binary with real GitHub provider
+- [ ] **OLD-02**: `buf dep update` succeeds against the proxy using buf v1.30.1 binary with real GitHub provider
+
+### New Protocol Validation (buf v1.69.0+)
+
+- [ ] **NEW-01**: `buf mod update` succeeds against the proxy using buf v1.69.0+ binary with real GitHub provider
+- [ ] **NEW-02**: `buf dep update` succeeds against the proxy using buf v1.69.0+ binary with real GitHub provider
+
+## v2 Requirements
+
+### Additional Protocol Support
+
+- **ADDL-01**: Implement full `GetSDKInfo` response with SDK resolution logic
+- **ADDL-02**: Implement repository group management RPCs (`AddRepositoryGroup`, `UpdateRepositoryGroup`, `RemoveRepositoryGroup`)
+
+### Extended Testing
+
+- **ADDL-03**: Test suite covers BitBucket provider
+- **ADDL-04**: Test suite covers local git provider
+- **ADDL-05**: Test suite covers Artifactory cache
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| BitBucket provider testing | GitHub provider is sufficient for protocol validation |
+| Local git provider testing | Not relevant to protocol correctness — tests GitHub provider only |
+| Artifactory cache testing | Not relevant to protocol correctness |
+| Removing old v1alpha1 protocol | Both protocols must coexist — old clients must keep working |
+| BSR-specific features (labels, recommendations, sync) | These were removed from the modern proto and proxy never implemented them |
+| Push functionality | Proxy is read-only; push was never implemented |
+| mTLS testing | Basic TLS is sufficient for protocol validation |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| BCG-01 | Phase 1 | Done |
+| BCG-02 | Phase 1 | Done |
+| BCG-03 | Phase 1 | Done |
+| BCG-04 | Phase 1 | Done |
+| HAND-01 | Phase 2 | Pending |
+| HAND-02 | Phase 2 | Pending |
+| HAND-03 | Phase 2 | Pending |
+| HAND-04 | Phase 2 | Pending |
+| TINF-01 | Phase 3 | Pending |
+| TINF-02 | Phase 3 | Pending |
+| TINF-03 | Phase 3 | Pending |
+| TINF-04 | Phase 3 | Pending |
+| TINF-05 | Phase 3 | Pending |
+| TINF-06 | Phase 3 | Pending |
+| OLD-01 | Phase 4 | Pending |
+| OLD-02 | Phase 4 | Pending |
+| NEW-01 | Phase 5 | Pending |
+| NEW-02 | Phase 5 | Pending |
+
+**Coverage:**
+- v1 requirements: 18 total
+- Mapped to phases: 18
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2026-05-07*
+*Last updated: 2026-05-07 after initial definition*

.planning/ROADMAP.md

@@ -0,0 +1,104 @@
+# Roadmap: EasyP Buf Proxy — Protocol Modernization
+
+## Overview
+
+Modernize the Buf registry proxy to serve both old (v1.30.1) and modern (v1.69.0+) Buf CLI clients. The journey starts with mechanical code generation from updated proto definitions, then adapts handlers to the new generated types, builds test infrastructure for integration testing with real buf binaries, and validates backward compatibility with the old protocol before confirming support for the new one.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [x] **Phase 1: Code Generation** - Switch proto source to v1.69.0, upgrade connect-go, regenerate code, verify build *(completed 2026-05-07)*
+- [x] **Phase 2: Handler Adaptation** - Update handler structs to embed new Unimplemented types, verify all RPCs compile and serve *(completed 2026-05-07)*
+- [x] **Phase 3: Test Infrastructure** - Build reusable test helpers for TLS server, buf binary management, and GitHub API integration *(completed 2026-05-07)*
+- [x] **Phase 4: Old Protocol Validation** - Confirm buf v1.30.1 still works against the updated proxy using real binaries and real GitHub API *(completed 2026-05-07)*
+- [x] **Phase 5: New Protocol Validation** - Confirm buf v1.69.0+ works against the proxy, discover any required new RPC implementations *(completed 2026-05-07)*
+
+## Phase Details
+
+### Phase 1: Code Generation
+**Goal**: Project compiles against v1.69.0 proto definitions with updated dependencies
+**Depends on**: Nothing (first phase)
+**Requirements**: BCG-01, BCG-02, BCG-03, BCG-04
+**Success Criteria** (what must be TRUE):
+  1. `generate.go` points at the `buf-v1.69.0` submodule and `go generate ./api/proto/...` completes without errors
+  2. `go.mod` lists `connectrpc.com/connect` v1.18.1 and `go mod tidy` shows no version conflicts
+  3. `go build ./...` succeeds with newly generated proto code replacing the old generated code
+  4. `buf.gen.yaml` no longer includes the go-grpc plugin in the codegen pipeline
+**Plans**: 2 plans
+
+Plans:
+- [x] 01-01: Switch proto source and upgrade dependencies
+- [x] 01-02: Regenerate proto code and verify build
+
+### Phase 2: Handler Adaptation
+**Goal**: Server binary compiles, starts, and serves RPCs using new generated types with all new RPCs returning Unimplemented
+**Depends on**: Phase 1
+**Requirements**: HAND-01, HAND-02, HAND-03, HAND-04
+**Success Criteria** (what must be TRUE):
+  1. Handler structs in `internal/connect/` embed the new `Unimplemented*Handler` types from regenerated code and the server starts without panics
+  2. Existing RPCs (`GetModulePins`, `DownloadManifestAndBlobs`, `GetRepositoryByFullName`, `GetRepositoriesByFullName`) compile and return correct response types for known request patterns
+  3. `GetSDKInfo` returns a gRPC `CodeUnimplemented` error (per D-01)
+  4. `ModulePin` responses include `manifest_digest` field present but empty (per D-02)
+**Plans**: 1 plan
+
+Plans:
+- [x] 02-01-PLAN.md — Verify handler adaptation baseline and run E2E smoke tests for both buf CLI versions
+
+### Phase 3: Test Infrastructure
+**Goal**: Reusable test helpers exist for starting a TLS proxy server, managing pinned buf binaries, and making authenticated GitHub API calls
+**Depends on**: Phase 2
+**Requirements**: TINF-01, TINF-02, TINF-03, TINF-04, TINF-05, TINF-06
+**Success Criteria** (what must be TRUE):
+  1. A test helper can programmatically start the proxy server with TLS using `~/local-tls/server/` certs and stop it cleanly after the test
+  2. Both buf v1.30.1 and v1.69.0+ binaries are downloaded (or path-configured) and their versions are asserted before test execution
+  3. Tests read GitHub API token and target repository from environment variables and fail fast with a clear message if not configured
+  4. Multiple tests can run in parallel without port conflicts or shared state interference
+  5. Test configuration supports CI execution via environment variables with no hardcoded paths or secrets
+**Plans**: 2 plans
+
+Plans:
+- [x] 03-01-PLAN.md — Create testutil package with config generation, server lifecycle, and buf binary management
+- [x] 03-02-PLAN.md — Refactor smoke test to use testutil and create internal validation tests
+
+### Phase 4: Old Protocol Validation
+**Goal**: Backward compatibility confirmed — buf v1.30.1 commands work against the updated proxy
+**Depends on**: Phase 3
+**Requirements**: OLD-01, OLD-02
+**Success Criteria** (what must be TRUE):
+  1. `buf mod update` succeeds against the proxy using buf v1.30.1 binary with a real GitHub provider and produces a valid `buf.lock` file
+  2. `buf dep update` (reinterpreted as two-step `buf mod update`) succeeds against the proxy using buf v1.30.1 binary with a real GitHub provider
+**Plans**: 1 plan
+
+Plans:
+- [x] 04-01-PLAN.md — Expose server output from StartServer and create two-step buf mod update test for OLD-02
+
+### Phase 5: New Protocol Validation
+**Goal**: Modern buf CLI support confirmed — buf v1.69.0+ commands work against the proxy, and any required new RPC implementations are identified
+**Depends on**: Phase 4
+**Requirements**: NEW-01, NEW-02
+**Success Criteria** (what must be TRUE):
+  1. `buf mod update` succeeds against the proxy using buf v1.69.0+ binary with a real GitHub provider and produces a valid `buf.lock` file
+  2. `buf dep update` succeeds against the proxy using buf v1.69.0+ binary with a real GitHub provider
+**Plans**: 2 plans
+
+Plans:
+- [x] 05-01-PLAN.md — Add RunBufDepUpdate helper and write new protocol tests with debug logging for v1.69.0
+- [x] 05-02-PLAN.md — Fix any RPC implementation blockers discovered by Plan 05-01 testing
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Code Generation | 2/2 | Complete | 2026-05-07 |
+| 2. Handler Adaptation | 1/1 | Complete | 2026-05-07 |
+| 3. Test Infrastructure | 2/2 | Complete | 2026-05-07 |
+| 4. Old Protocol Validation | 1/1 | Complete | 2026-05-07 |
+| 5. New Protocol Validation | 2/2 | Complete | 2026-05-07 |

.planning/STATE.md

@@ -0,0 +1,94 @@
+---
+gsd_state_version: 1.0
+milestone: v1.30.1
+milestone_name: milestone
+status: complete
+stopped_at: All phases complete
+last_updated: "2026-05-07T21:30:00.000Z"
+last_activity: 2026-05-07 — Phase 5 complete, all 5 phases done
+progress:
+  total_phases: 5
+  completed_phases: 5
+  total_plans: 8
+  completed_plans: 8
+  percent: 100
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-05-07)
+
+**Core value:** The proxy must correctly serve both old (v1.30.1) and modern (v1.69.0+) Buf CLI clients simultaneously
+**Current focus:** Complete — all phases executed successfully
+
+## Current Position
+
+Phase: 5 of 5 (New Protocol Validation) — COMPLETE
+Plan: 2 of 2 in current phase
+Status: All phases complete, project goal achieved
+Last activity: 2026-05-07 — Phase 5 executed and verified
+
+Progress: [██████████] 100%
+
+## Performance Metrics
+
+**Velocity:**
+
+- Total plans completed: 8 (8 total planned)
+- Average duration: ~6 min
+- Total execution time: ~50 min
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+| ----- | ----- | ----- | -------- |
+| 1. Code Generation | 2 | 7 min | ~3.5 min |
+| 2. Handler Adaptation | 1 | 4 min | ~4 min |
+| 3. Test Infrastructure | 2 | ~7 min | ~3.5 min |
+| 4. Old Protocol Validation | 1 | ~3 min | ~3 min |
+| 5. New Protocol Validation | 2 | ~48 min | ~24 min |
+
+**Recent Trend:**
+
+- Phase 5 was the largest phase due to full v1beta1 protocol implementation
+- All tests pass consistently when network cooperates
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- Single superset handler (no dual-protocol architecture) — both old and new clients served by one handler generated from v1.69.0 protos
+- connect-go v1.18.1 ceiling — latest version supporting Go 1.22; v1.19.x requires Go 1.24
+- Manual protobuf wire encoding for v1beta1 responses — avoids complex proto dependencies
+- In-memory caching across RPC chain — GetCommits is the only expensive call
+- IPv4-only dialer in GitHub client — avoids IPv6 TLS timeouts on macOS
+
+### Pending Todos
+
+None — project complete.
+
+### Blockers/Concerns
+
+None — all blockers resolved during Phase 5:
+
+- Content-type mismatch: resolved (v1beta1 handlers use `application/proto`)
+- Unknown RPCs: discovered and implemented (GetCommits, GetGraph, Download, GetModules)
+- manifest_digest: implemented with real B4 digest computation
+
+## Deferred Items
+
+Items acknowledged and carried forward from previous milestone close:
+
+| Category | Item | Status | Deferred At |
+|----------|------|--------|-------------|
+| *(none)* | | | |
+
+## Session Continuity
+
+Last session: 2026-05-07T21:30:00.000Z
+Stopped at: All phases complete