Cursor rule

1---
2description: Protocol Buffer File Rules
3globs: ["**/*.proto"]
4alwaysApply: false
5---
6 
7 
8# Protocol Buffer File Rules
9 
10> **⚠️ XRP Protocol Buffers DEPRECATED**
11>
12> **Status**: `proto/rippleapi/` is **DEPRECATED** and no longer used.
13>
14> **Reason**: XRP functionality migrated to native Go implementation. gRPC server (`apps/xrpl-grpc-server/`) has been replaced with native xrpl-go libraries.
15 
16## Overview
17 
18Rules for modifying Protocol Buffer files (`*.proto`) in go-crypto-wallet.
19 
20## Applicable Directories
21 
22| Directory | Description | Status |
23|-----------|-------------|--------|
24| `proto/rippleapi/` | Ripple API definitions | ❌ DEPRECATED |
25 
26## Verification Commands
27 
28| Command | Purpose | Required |
29|---------|---------|----------|
30| `make proto-lint` | Lint proto files (buf only, requires PROTO_TOOL=buf) | When buf supports Edition 2024 |
31| `make proto-breaking` | Check for breaking changes | Recommended |
32 
33## Prohibited Actions
34 
35**NEVER use `protoc` command directly.** Always use Make targets for code generation.
36 
37```bash
38# ❌ PROHIBITED - Never run protoc directly
39protoc --go_out=... proto/*.proto
40 
41# ✅ CORRECT - Always use Make targets
42make proto      # Go only
43make proto-ts   # TypeScript only
44make proto-all  # Both
45```
46 
47## Code Generation [DEPRECATED for XRP]
48 
49> **⚠️ Note**: Proto generation commands no longer needed for XRP.
50 
51| Command | Purpose | XRP Status |
52|---------|---------|------------|
53| `make proto` | Generate Go code from proto files | ⚠️ No longer generates XRP |
54| `make proto-ts` | Generate TypeScript code from proto files | ❌ XRP TypeScript deprecated |
55| `make proto-all` | Generate all proto files (Go + TypeScript) | ⚠️ XRP not included |
56| `make proto-fmt` | Format proto files | ⚠️ XRP protos deprecated |
57| `make clean-pb` | Clean all generated protobuf files | ⚠️ XRP files no longer generated |
58 
59### Generation Workflow
60 
61```bash
62# 1. Edit proto files
63# proto/rippleapi/*.proto
64 
65# 2. Format
66make proto-fmt
67 
68# 3. Check breaking changes (optional)
69make proto-breaking
70 
71# 4. Generate code
72make proto      # Go only
73make proto-ts   # TypeScript only
74make proto-all  # Both Go and TypeScript
75 
76# 5. Verify build
77make check-build
78```
79 
80## Buf Configuration
81 
82This project uses [Buf](https://buf.build/) for proto management.
83 
84### Configuration Files
85 
86| File | Description |
87|------|-------------|
88| `buf.yaml` | Module configuration and lint rules |
89| `buf.gen.yaml` | Code generation configuration |
90 
91### Lint Rules
92 
93Using BASIC ruleset with exceptions for backward compatibility:
94 
95```yaml
96lint:
97  use:
98    - BASIC
99  except:
100    - ENUM_VALUE_PREFIX
101    - ENUM_ZERO_VALUE_SUFFIX
102    - FIELD_LOWER_SNAKE_CASE
103    - PACKAGE_DIRECTORY_MATCH
104    - PACKAGE_SAME_DIRECTORY
105    - DIRECTORY_SAME_PACKAGE
106```
107 
108## Proto File Structure
109 
110```protobuf
111syntax = "proto3";
112 
113package rippleapi;
114 
115option go_package = "github.com/hiromaily/go-crypto-wallet/internal/infrastructure/api/xrp/xrp";
116 
117// Service definitions
118service AccountService {
119  rpc GetAccountInfo(GetAccountInfoRequest) returns (GetAccountInfoResponse);
120}
121 
122// Message definitions
123message GetAccountInfoRequest {
124  string address = 1;
125}
126```
127 
128## Auto-Generated Files
129 
130**DO NOT EDIT** generated files:
131 
132- `internal/infrastructure/api/xrp/xrp/*.pb.go`
133 
134These are regenerated by `make proto`.
135 
136## Best Practices
137 
138### Naming
139 
140- Use lowercase snake_case for field names
141- Use PascalCase for message and service names
142- Use UPPER_SNAKE_CASE for enum values
143 
144### Versioning
145 
146- Maintain backward compatibility
147- Use `make breaking-proto` to detect breaking changes
148- Consider field deprecation before removal
149 
150### Field Numbers
151 
152- Never reuse field numbers
153- Reserve removed field numbers
154 
155```protobuf
156message Example {
157  reserved 1, 2;  // Previously used field numbers
158  reserved "old_field";  // Previously used field names
159}
160```
161 
162## Quick Checklist
163 
164- [ ] `make proto-fmt` passes
165- [ ] `make proto-breaking` passes (no unintended breaking changes)
166- [ ] Field numbers are not reused
167- [ ] Backward compatibility maintained
168- [ ] Code regenerated after changes (`make proto` or `make proto-all`)
169- [ ] `make check-build` passes after generation
170 
171## Related Documentation
172 
173- @buf.yaml - Buf configuration
174- @buf.gen.yaml - Code generation configuration
175- @proto/rippleapi/ - Proto source files
176 
177## Related Skills
178 
179- `go-development` - Go verification after generation
180