Skip to content

Commit 051d69b

Browse files
szokeasaurusrexszokeasaurusrex
committed
meta: Add Cursor rules
Add some basic Cursor rules to the repo.
1 parent 4b40a70 commit 051d69b

5 files changed

Lines changed: 379 additions & 0 deletions

File tree

‎.cursor/rules/cicd-patterns.mdc‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
description: CI/CD workflow patterns and conventions for sentry-cli
3+
globs: .github/workflows/**/*
4+
alwaysApply: false
5+
---
6+
7+
# CI/CD Workflow Guidelines
8+
9+
## Reusable Workflow Pattern
10+
11+
- Main `ci.yml` calls separate workflows (`lint.yml`, `test.yml`, etc.)
12+
- Extract actual logic into separate workflows that `ci.yml` calls
13+
- Use `uses: ./.github/workflows/workflow-name.yml` pattern
14+
15+
## Required Checks Pattern
16+
17+
- All workflows must pass before merge via "Check required jobs" pattern
18+
- Update the `required` job dependencies when adding new workflows
19+
- Branch protection relies on this "Check required jobs" validation
20+
21+
## Test Matrix Requirements
22+
23+
- Test matrix should cover primary platforms (Ubuntu, macOS, Windows)
24+
- Consider impact on binary distribution pipeline
25+
- Cross-platform testing is essential
26+
27+
## Branch Protection
28+
29+
- Main branches (`master`, `1.x`, `release/**`) are protected
30+
- Merge strategy: Primarily squash merging, some rebase merging allowed
31+
- Restrict pushes to protected branches (force use of PRs)
32+
33+
## Adding New Workflows
34+
35+
When adding new CI checks:
36+
37+
1. Create separate reusable workflow file
38+
2. Call it from main `ci.yml`
39+
3. Add to `required` job dependencies
40+
4. Test across platform matrix
41+
42+
## Specific Workflows
43+
44+
- `lint.yml`: Rustfmt, Clippy, cross-platform
45+
- `test.yml`: Rust tests with feature matrix
46+
- `test_node.yml`: JavaScript/Node.js tests
47+
- `swift-test.yml`: Apple catalog parsing tests
48+
49+
## Release Process
50+
51+
- Uses `.craft.yml` for release automation
52+
- Platform-specific binary builds
53+
- npm package publishing coordination
54+
- Docker image releases (edge/latest tags)
55+
56+
## Environment Variables in CI
57+
58+
- `RUSTFLAGS: -Dwarnings` enforced in CI
59+
- Feature flag testing: `-Funstable-mobile-app`
60+
- Cross-platform matrix: Ubuntu 24.04, macOS 14, Windows 2022

‎.cursor/rules/javascript-development.mdc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
description: JavaScript/TypeScript development patterns for sentry-cli npm wrapper
3+
globs: js/**/*,scripts/**/*,package.json,*.js
4+
alwaysApply: false
5+
---
6+
7+
# JavaScript Development Guidelines
8+
9+
## Code Organization
10+
11+
- Maintain compatibility with existing npm package structure
12+
- Update TypeScript definitions in `js/index.d.ts` if needed
13+
- Consider impact on installation flow in `scripts/install.js`
14+
- Test across different Node.js versions
15+
16+
## Installation & Distribution
17+
18+
- Multiple distribution methods: npm, direct binary, package managers
19+
- Installation logic in `scripts/install.js` handles platform detection
20+
- Consider offline/air-gapped environments
21+
- Binary management via `npm-binary-distributions/`
22+
23+
## Development Commands
24+
25+
```bash
26+
# JavaScript workflow
27+
npm test
28+
npm run fix
29+
npm run check:types
30+
```
31+
32+
## Code Quality
33+
34+
- Uses ESLint, Prettier, and Jest
35+
- Follow existing patterns for error handling
36+
- Maintain backward compatibility
37+
38+
## TypeScript Support
39+
40+
- Type definitions maintained in `js/index.d.ts`
41+
- Sync with Rust CLI interface changes
42+
- Consider backward compatibility for JS API

‎.cursor/rules/rule-management.mdc‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
description: Instructions for maintaining and updating Cursor rules for sentry-cli
3+
alwaysApply: true
4+
---
5+
6+
# Rule Management Guidelines
7+
8+
## Proactive Rule Updates
9+
10+
When conversations include new context that could be **generally applicable** to sentry-cli development, you should update the relevant rule files in `.cursor/rules/`.
11+
12+
### What to Capture
13+
14+
- **Development patterns** that emerge during problem-solving
15+
- **Best practices** discovered or discussed
16+
- **Common pitfalls** and how to avoid them
17+
- **Workflow improvements** that benefit the team
18+
- **Architecture decisions** that affect future development
19+
- **Tool configurations** or setup requirements
20+
- **Testing strategies** and patterns
21+
22+
### What NOT to Capture
23+
24+
- **Task-specific information** (one-time fixes, specific bug solutions)
25+
- **Temporary workarounds** or experimental approaches
26+
- **Personal preferences** that don't reflect team standards
27+
- **Implementation details** for specific features
28+
29+
## Update Strategy
30+
31+
1. **Identify the appropriate rule file**:
32+
33+
- `sentry-cli-project.mdc` - General project context
34+
- `rust-development.mdc` - Rust-specific patterns
35+
- `javascript-development.mdc` - JS/TS patterns
36+
- `cicd-patterns.mdc` - CI/CD workflows
37+
38+
2. **Update incrementally**: Add new insights to existing sections or create new sections as needed
39+
40+
3. **Maintain clarity**: Keep rules focused, actionable, and well-organized
41+
42+
4. **Preserve existing context**: Don't remove valuable information unless it's outdated
43+
44+
## When to Update Rules
45+
46+
Update rules when you encounter:
47+
48+
- New patterns that developers should follow consistently
49+
- Solutions to common problems that could help future development
50+
- Clarifications about existing practices
51+
- Tool usage patterns that improve workflow
52+
- Architecture insights that affect code organization
53+
54+
Remember: Rules should capture knowledge that helps maintain consistency and quality across the sentry-cli codebase.

‎.cursor/rules/rust-development.mdc‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
description: Rust development patterns and conventions for sentry-cli
3+
globs: *.rs,Cargo.*,.cargo/**/*,src/**/*,apple-catalog-parsing/**/*
4+
alwaysApply: false
5+
---
6+
7+
# Rust Development Guidelines
8+
9+
## Code Organization
10+
11+
- Follow existing module structure in `src/commands/` for new commands
12+
- Use `anyhow::Result` for error handling patterns
13+
- Consider cross-platform compatibility
14+
- Ensure backward compatibility for CLI interface
15+
16+
## Common Patterns
17+
18+
- Use existing error types and handling patterns
19+
- Follow established CLI argument parsing patterns using `clap`
20+
- Reuse utility functions from `src/utils/`
21+
- Match existing code style and naming conventions
22+
- Add appropriate logging using `log` crate patterns
23+
24+
## Development Commands
25+
26+
```bash
27+
# Essential Rust workflow - run against the whole workspace
28+
cargo build --workspace
29+
cargo test --workspace
30+
cargo clippy --workspace
31+
cargo fmt
32+
33+
# Local testing
34+
./bin/sentry-cli --help
35+
```
36+
37+
## Testing Requirements
38+
39+
- Update integration tests in `tests/integration/` with `.trycmd` files
40+
- Unit tests alongside source code
41+
- Cross-platform testing considerations
42+
43+
## Error Handling Patterns
44+
45+
- Use `anyhow::Result` for application-level errors
46+
- Use `thiserror` for library-level error types (see `src/utils/auth_token/error.rs`)
47+
- Chain errors with `.context()` for better error messages
48+
- Custom error types in `src/api/errors/` and `src/utils/dif_upload/error.rs`
49+
50+
## Testing Patterns
51+
52+
- Integration tests use `trycmd` crate for CLI testing (asserting output)
53+
- Use `assert_cmd` crate when asserting behavior rather than just output
54+
- Test fixtures in `tests/integration/_fixtures/`
55+
- Mock API responses in `tests/integration/_responses/`
56+
- Use `TestManager` for setting up test environments
57+
- Platform-specific tests with `#[cfg(target_os = "...")]`
58+
59+
## Swift/Apple Integration
60+
61+
- Swift code in `apple-catalog-parsing/` is used for parsing xarchive files
62+
- Used by the `mobile-app upload` command for iOS app processing
63+
- Built as a separate crate with FFI bindings to Rust
64+
- Only compiled on macOS targets
65+
- Tests run via `swift-test.yml` workflow in CI
66+
67+
# Rust Testing Guidelines
68+
69+
## Unit Tests
70+
71+
- Colocate with source code
72+
- Use `#[cfg(test)]` modules
73+
- Mock external dependencies
74+
75+
## Integration Tests
76+
77+
- Use `trycmd` for CLI interface testing when asserting output
78+
- Use `assert_cmd` for testing behavior rather than just output
79+
- Structure: `tests/integration/_cases/<command>/<test>.trycmd`
80+
- Fixtures: `tests/integration/_fixtures/`
81+
- Expected outputs: `tests/integration/_expected_outputs/`
82+
- API mocks: `tests/integration/_responses/`
83+
84+
## Snapshot Management
85+
86+
```bash
87+
# Update snapshots
88+
TRYCMD=overwrite cargo test
89+
90+
# Debug test output
91+
TRYCMD=dump cargo test
92+
```
93+
94+
## Test Utilities
95+
96+
- `TestManager`: Sets up test environment with mock server
97+
- `MockEndpointBuilder`: Creates API endpoint mocks
98+
- `copy_recursively`: Helper for fixture setup
99+
- Environment setup via `test_utils::env`
100+
101+
## Platform-Specific Testing
102+
103+
- Use `#[cfg(windows)]` for Windows-specific tests
104+
- Separate `.trycmd` files when behavior differs
105+
- Test on CI matrix: Linux, macOS, Windows
106+
107+
## Assert Command vs Trycmd
108+
109+
- `trycmd`: Best for testing exact CLI output, supports snapshot testing
110+
- `assert_cmd`: Better for testing behavior, exit codes, and when you need programmatic assertions
111+
- Example of `assert_cmd` usage can be found in `TestManager::run_and_assert()`# Testing Guidelines
112+
113+
## Unit Tests
114+
115+
- Colocate with source code
116+
- Use `#[cfg(test)]` modules
117+
- Mock external dependencies
118+
119+
## Integration Tests
120+
121+
- Use `trycmd` for CLI interface testing when asserting output
122+
- Use `assert_cmd` for testing behavior rather than just output
123+
- Structure: `tests/integration/_cases/<command>/<test>.trycmd`
124+
- Fixtures: `tests/integration/_fixtures/`
125+
- Expected outputs: `tests/integration/_expected_outputs/`
126+
- API mocks: `tests/integration/_responses/`
127+
128+
## Snapshot Management
129+
130+
```bash
131+
# Update snapshots
132+
TRYCMD=overwrite cargo test
133+
134+
# Debug test output
135+
TRYCMD=dump cargo test
136+
```
137+
138+
## Test Utilities
139+
140+
- `TestManager`: Sets up test environment with mock server
141+
- `MockEndpointBuilder`: Creates API endpoint mocks
142+
- `copy_recursively`: Helper for fixture setup
143+
- Environment setup via `test_utils::env`
144+
145+
## Platform-Specific Testing
146+
147+
- Use `#[cfg(windows)]` for Windows-specific tests
148+
- Separate `.trycmd` files when behavior differs
149+
- Test on CI matrix: Linux, macOS, Windows
150+
151+
## Assert Command vs Trycmd
152+
153+
- `trycmd`: Best for testing exact CLI output, supports snapshot testing
154+
- `assert_cmd`: Better for testing behavior, exit codes, and when you need programmatic assertions
155+
- Example of `assert_cmd` usage can be found in `TestManager::run_and_assert()`

‎.cursor/rules/sentry-cli-project.mdc‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
description: Core development guidelines and context for sentry-cli
3+
alwaysApply: true
4+
---
5+
6+
# Sentry CLI Development Guidelines
7+
8+
## Project Overview
9+
10+
This is **sentry-cli**, a command-line utility for working with Sentry. It's primarily written in **Rust** with **JavaScript/Node.js** wrapper components for npm distribution.
11+
12+
## Language & Architecture
13+
14+
- **Primary language**: Rust (core functionality)
15+
- **Secondary language**: JavaScript/TypeScript (npm wrapper, installation scripts)
16+
- **Build system**: Cargo for Rust, npm/yarn for JavaScript
17+
- **Cross-platform**: Supports multiple architectures (darwin, linux, windows, ARM variants)
18+
- **Binary distributions**: Located in `npm-binary-distributions/` for different platforms
19+
20+
## Project Structure
21+
22+
- `src/` - Core Rust source code with command modules and utilities
23+
- `js/` - JavaScript wrapper and npm package code
24+
- `scripts/` - Build and utility scripts
25+
- `tests/integration/` - Integration tests using `.trycmd` format
26+
- `npm-binary-distributions/` - Platform-specific binary packages
27+
- `.github/workflows/` - CI/CD workflows (follows reusable workflow pattern)
28+
29+
## Development Standards
30+
31+
### Commit Message Format
32+
33+
**MUST follow Sentry's commit message format**: `type(scope): subject`
34+
35+
Valid types: `build`, `ci`, `docs`, `feat`, `fix`, `perf`, `ref`, `style`, `test`, `meta`, `license`, `revert`
36+
37+
Subject requirements:
38+
39+
- Capitalize first letter
40+
- Use imperative mood ("Add" not "Added")
41+
- No trailing period
42+
- Max 70 characters for header
43+
44+
Reference: https://develop.sentry.dev/engineering-practices/commit-messages/
45+
46+
### Performance & Scale Considerations
47+
48+
- CLI tool should be fast and responsive
49+
- Consider impact on cold start times
50+
- Memory usage matters for CI environments
51+
- Network operations should be optimized and retryable
52+
53+
### Security Best Practices
54+
55+
- Handle authentication tokens securely
56+
- Validate file paths to prevent directory traversal
57+
- Consider impact of processing user-provided files (sourcemaps, debug files)
58+
- Follow Rust security best practices
59+
60+
## Testing Requirements
61+
62+
- Unit tests alongside source code
63+
- Integration tests using `.trycmd` format in `tests/integration/`
64+
- Mock HTTP responses in `tests/integration/_responses/`
65+
- Test fixtures in `tests/integration/_fixtures/`
66+
- Cross-platform testing via CI matrix
67+
68+
Remember: This is a production tool used by many developers. Changes should be well-tested, backward-compatible, and follow established patterns.

0 commit comments

Comments
 (0)