Align Proto

Align-Proto Workflow

You are an AI that detects proto package changes and implements new gRPC services in the SDK. Follow this workflow exactly.

Arguments

• $ARGUMENTS may contain --check-only to run in read-only mode (detect and report only, no implementation).

Interaction Contract

This skill is procedural and approval-gated. Do not collapse it into an end-to-end implementation sprint.

• Always show the todo checklist from Step 3 before making file changes.
• Update checklist status as each step completes.
• Narrate the result of each major step: selected package, current version, target version, backup status, install result, detected proto changes, proposal, validation result.
• Do not infer package/version silently unless the user provided it explicitly in the prompt.
• Default cadence: ask for package selection and target version first; after package/version are confirmed, continue through backup, dependency update/install, compare, and analysis until the Step 9 proposal. If dependency/install approval has not already been given, ask once before Step 5.
• Before Step 10 implementation, show the detailed proposal from Step 9 and ask for explicit approval.
• After the Step 9 proposal is approved, continue through implementation and validation without additional prompts. After validation, show an implementation summary and ask the user to confirm whether everything is as expected. If the user requests modifications, continue editing and re-validating, then show an updated implementation summary. Once the user confirms the result is set, clean up this run's backup files and give a separate cleanup/final summary. If validation finds new errors in touched files, keep the backup and report the blocker.
• If the selected package is not currently in packages/sdk-ts/package.json, treat it as initial onboarding:
  • Current version is none
  • Backup is skipped with a clear explanation
  • Generated proto files are treated as all-new
  • Still require the Step 5 dependency/install approval and Step 10 implementation approval
• If the user asks for --check-only, never edit files; stop after the implementation status report.

Supported Packages

Proto Source Packages

• Indexer: generated from protoV2/indexer/gen.sh, source repo path injective-indexer/api/gen/grpc/**/*.proto
• Abacus: generated from protoV2/abacus/gen.sh, source repo path injective-abacus/api/gen/grpc/points_svc/pb/**/*.proto
• TC Abacus: generated from protoV2/tcAbacus/gen.sh, source repo path injective-abacus/api/gen_tc/gen/grpc/injective_tc_abacus_rpc/pb/**/*.proto
• Platform Services: generated from protoV2/platform-services/gen.sh, source repo path platform-services/api/gen/grpc/**/*.proto

Workflow Steps

Step 0: Package Selection

Ask the user which proto package to sync:

1. indexer-proto-ts-v2 (Indexer gRPC services)
2. abacus-proto-ts-v2 (Abacus gRPC services)
3. tc-abacus-proto-ts-v2 (TC Abacus gRPC services)
4. platform-services-proto-ts-v2 (Platform services gRPC APIs, including positions/social leaderboard services)

Step 1: Initialization

• Detect the current version of the selected package in packages/sdk-ts/package.json
• Show the current version to the user

Step 2: Version Selection

• Ask: "What version should we bump to?"
• User provides target version (e.g., 1.18.7) or says "latest"
• If user says "latest", resolve it via npm view @injectivelabs/{package-name} version

Step 3: Create Todo List

Create a todo list to track progress:

• Select package version
• Backup current proto files
• Update package.json
• Install new package
• Compare proto files
• Analyze changes
• Show proposal & get approval
• Implement changes
• Validate implementation
• Cleanup backup files

Update each item as it completes.

Step 4: Backup Current Proto Files

Create backup directory: scripts/.align-proto-backup/{package-name}/{current-version}/

Copy all proto files from the package's node_modules generated directory:

• Indexer: node_modules/.pnpm/@injectivelabs+indexer-proto-ts-v2@{version}/node_modules/@injectivelabs/indexer-proto-ts-v2/generated/
• Abacus: node_modules/.pnpm/@injectivelabs+abacus-proto-ts-v2@{version}/node_modules/@injectivelabs/abacus-proto-ts-v2/generated/
• TC Abacus: node_modules/.pnpm/@injectivelabs+tc-abacus-proto-ts-v2@{version}/node_modules/@injectivelabs/tc-abacus-proto-ts-v2/generated/
• Platform Services: node_modules/.pnpm/@injectivelabs+platform-services-proto-ts-v2@{version}/node_modules/@injectivelabs/platform-services-proto-ts-v2/generated/

Step 5: Bump Package Version (PERMANENT)

Approval gate: show the exact dependency change and install command, then wait for explicit approval before editing packages/sdk-ts/package.json or running install.

Update packages/sdk-ts/package.json with the new version. This change is permanent.

Step 6: Install New Package

Run pnpm install --force in project root. The --force flag ensures all packages are properly re-linked from the pnpm store, preventing empty package directories from stale/corrupted installs. If install fails, show error and exit.

Step 7: Compare Proto Files

Compare backup vs new proto files. Detect:

• New services (new *_rpc_pb.d.ts files; platform-services may use Goa names like goagen_api_*_pb.d.ts)
• Modified services (existing files with changes) — see Step 7a for field-level audit
• Removed services (files that disappeared)

Use diff -rq for a file-level summary, then diff individual files for details. For modified services, use awk '/^export interface MessageName/,/^}/' on both versions to isolate and compare individual message definitions cleanly (raw .d.ts diffs are hard to read because messages are reordered between generator runs).

Step 7a: Field-Level Audit of Modified Services

When an existing *_rpc_pb.d.ts or platform-services goagen_api_*_pb.d.ts file is modified, do NOT assume the changes are purely additive. Check for each of these change types:

1. New/renamed/removed RPC methods — compare protobuf rpc: entries in the matching *.client.d.ts
2. New/renamed/removed message types — compare export interface declarations
3. New/renamed/removed fields on request/response messages — diff each message body individually
4. New enum values in messageType string fields — check doc comments like Type: 'a', 'b', 'c' on bidirectional/WS stream wrapper responses (e.g. TakerStreamResponse.messageType). Added values require new case arms in the corresponding WS stream handler, even when no new gRPC method was added.
5. New oneof/payload fields on stream wrappers — e.g. a new conditionalOrder?: ... sibling to existing quote?, requestAck?. These deliver payload for the new messageType value above.

For each detected change, map it to SDK-side updates:

• New field on request → add optional param to the existing fetch* / stream* method; wire onto the request builder
• New field on response → extend the SDK type interface + map it in the transformer
• Removed method/type → prune the fetch* / stream* method, transformer method, type interface(s), and spec tests
• New messageType value → add case arm in WS stream handler + new event key in the *StreamEvents interface
• Pre-existing gaps in WS stream switches (message types in proto that the SDK never handled) — flag them; offer to close while you're already editing the file

Step 8: Show Changes & Ask Which to Implement

Present detected changes. Ask which services to implement. Skip old missing services.

If --check-only: Stop here. Show implementation status report and exit.

Step 9: Generate Detailed Proposal

For each selected service:

1. Parse the proto *_rpc_pb.d.ts file (or platform-services goagen_api_*_pb.d.ts) to extract:

   • Service name from ServiceType definition
   • RPC methods (name, request type, response type)
   • Whether each method is streaming (serverStreaming: true)
   • Message interfaces with all fields

2. Categorize methods:

   • Unary RPC → implement as fetch* method
   • Server Streaming → implement as stream* method
   • Bidirectional/WS stream (e.g. TakerStream, MakerStream) → extend existing IndexerWs*Stream.ts handlers; do NOT generate a new *StreamV2.ts class

3. Find the most similar existing implementation as reference:

   • Simple query: like IndexerGrpcMetaApi
   • Paginated: like IndexerGrpcRfqApi
   • Stream-heavy: like IndexerGrpcSpotStreamV2
   • Complex nested: like IndexerGrpcDerivativesApi
   • WS bidirectional: like IndexerWsTakerStream / IndexerWsMakerStream
   • Platform services: start from packages/sdk-ts/src/client/platformServices if present; otherwise mirror the closest unary gRPC consumer pattern and keep names platform-scoped (for example PlatformServicesGrpcPositionsApi)

4. For modified services, the proposal is a surgical edit list — NOT a file-creation list. Enumerate each existing file that needs editing with the specific add/remove/rename per field. Call out breaking removals explicitly (they affect downstream consumers).

5. Show file list (or edit list), method breakdown, line estimates. Ask for approval.

Step 10: Implementation

Approval gate: do not create or edit SDK implementation files until the user explicitly approves the Step 9 proposal.

Create files in dependency order:

1. types/*.ts                                   (no dependencies)
2. transformers/*Transformer.ts                  (depends on types)
3. transformers/*StreamTransformer.ts            (depends on main transformer)
4. grpc/*Api.ts                                  (depends on types + transformers)
5. grpc/*Api.spec.ts                             (depends on API class + transformers)
6. grpc_stream/streamV2/*StreamV2.ts             (depends on stream transformer)
7. grpc_stream/streamV2/*StreamV2.spec.ts        (depends on stream class)
8. Update all index.ts exports                   (depends on all above)

Required files (all services):

• types/*.ts - TypeScript interfaces
• transformers/IndexerGrpc*Transformer.ts (or AbacusGrpc* / TcAbacusGrpc*) - Data transformation
• grpc/IndexerGrpc*Api.ts (or AbacusGrpc* / TcAbacusGrpc*) - Main API class
• grpc/IndexerGrpc*Api.spec.ts (or AbacusGrpc* / TcAbacusGrpc*) - Test file for the API class
• For platform-services wrappers, use platform-scoped folders/names if they exist (for example platformServices, PlatformServicesGrpc*Api) instead of indexer names.