diff --git a/.cursor/rules/cicd-patterns.mdc b/.cursor/rules/cicd-patterns.mdc new file mode 100644 index 0000000000..41aa979a24 --- /dev/null +++ b/.cursor/rules/cicd-patterns.mdc @@ -0,0 +1,60 @@ +--- +description: CI/CD workflow patterns and conventions for sentry-cli +globs: .github/workflows/**/* +alwaysApply: false +--- + +# CI/CD Workflow Guidelines + +## Reusable Workflow Pattern + +- Main `ci.yml` calls separate workflows (`lint.yml`, `test.yml`, etc.) +- Extract actual logic into separate workflows that `ci.yml` calls +- Use `uses: ./.github/workflows/workflow-name.yml` pattern + +## Required Checks Pattern + +- All workflows must pass before merge via "Check required jobs" pattern +- Update the `required` job dependencies when adding new workflows +- Branch protection relies on this "Check required jobs" validation + +## Test Matrix Requirements + +- Test matrix should cover primary platforms (Ubuntu, macOS, Windows) +- Consider impact on binary distribution pipeline +- Cross-platform testing is essential + +## Branch Protection + +- Main branches (`master`, `1.x`, `release/**`) are protected +- Merge strategy: Primarily squash merging, some rebase merging allowed +- Restrict pushes to protected branches (force use of PRs) + +## Adding New Workflows + +When adding new CI checks: + +1. Create separate reusable workflow file +2. Call it from main `ci.yml` +3. Add to `required` job dependencies +4. Test across platform matrix + +## Specific Workflows + +- `lint.yml`: Rustfmt, Clippy, cross-platform +- `test.yml`: Rust tests with feature matrix +- `test_node.yml`: JavaScript/Node.js tests +- `swift-test.yml`: Apple catalog parsing tests + +## Release Process + +- Uses `.craft.yml` for release automation +- Platform-specific binary builds +- npm package publishing coordination +- Docker image releases (edge/latest tags) + +## Environment Variables in CI + +- `RUSTFLAGS: -Dwarnings` enforced in CI +- Feature flag testing: `-Funstable-mobile-app` +- Cross-platform matrix: Ubuntu 24.04, macOS 14, Windows 2022 diff --git a/.cursor/rules/javascript-development.mdc b/.cursor/rules/javascript-development.mdc new file mode 100644 index 0000000000..d82f73e6e7 --- /dev/null +++ b/.cursor/rules/javascript-development.mdc @@ -0,0 +1,41 @@ +--- +description: JavaScript/TypeScript development patterns for sentry-cli npm wrapper +globs: js/**/*,scripts/**/*,package.json,*.js +alwaysApply: false +--- + +# JavaScript Development Guidelines + +## Code Organization + +- Maintain compatibility with existing npm package structure +- Update TypeScript definitions in `js/index.d.ts` if needed +- Consider impact on installation flow in `scripts/install.js` +- Test across different Node.js versions + +## Installation & Distribution + +- Installation logic in `scripts/install.js` handles platform detection +- Consider offline/air-gapped environments +- Binary management via `npm-binary-distributions/` + +## Development Commands + +```bash +# JavaScript workflow +npm test +npm run fix +npm run check:types +``` + +## Code Quality + +- Uses ESLint, Prettier, and Jest +- Follow existing patterns for error handling +- Maintain backward compatibility + +## TypeScript Support + +- Type definitions maintained in `js/index.d.ts` +- Sync with Rust CLI interface changes +- Consider backward compatibility for JS API diff --git a/.cursor/rules/rule-management.mdc b/.cursor/rules/rule-management.mdc new file mode 100644 index 0000000000..13343019b0 --- /dev/null +++ b/.cursor/rules/rule-management.mdc @@ -0,0 +1,56 @@ +--- +description: Instructions for maintaining and updating Cursor rules for sentry-cli +alwaysApply: true +--- + +# Rule Management Guidelines + +## Proactive Rule Updates + +When conversations include new context that could be **generally applicable** to sentry-cli development, you should update the relevant rule files in `.cursor/rules/`. + +### What to Capture + +- **Development patterns** that emerge during problem-solving +- **Best practices** discovered or discussed +- **Common pitfalls** and how to avoid them +- **Workflow improvements** that benefit the team +- **Architecture decisions** that affect future development +- **Tool configurations** or setup requirements +- **Testing strategies** and patterns + +### What NOT to Capture + +- **Task-specific information** (one-time fixes, specific bug solutions) +- **Temporary workarounds** or experimental approaches +- **Personal preferences** that don't reflect team standards +- **Implementation details** for specific features + +## Update Strategy + +1. **Identify the appropriate rule file**: + + - `sentry-cli-project.mdc` - General project context + - `rust-development.mdc` - Rust-specific patterns + - `javascript-development.mdc` - JS/TS patterns + - `cicd-patterns.mdc` - CI/CD workflows + +2. **Update incrementally**: Add new insights to existing sections or create new sections as needed + +3. **Maintain clarity**: Keep rules focused, actionable, and well-organized + +4. **Preserve existing context**: Don't remove valuable information unless it's outdated + +5. **Don't repeat yourself**: Do not add redundant information to a rule. + +## When to Update Rules + +Update rules when you encounter: + +- New patterns that developers should follow consistently +- Solutions to common problems that could help future development +- Clarifications about existing practices +- Tool usage patterns that improve workflow +- Architecture insights that affect code organization + +Remember: Rules should capture knowledge that helps maintain consistency and quality across the sentry-cli codebase. diff --git a/.cursor/rules/rust-development.mdc b/.cursor/rules/rust-development.mdc new file mode 100644 index 0000000000..53ec5b779b --- /dev/null +++ b/.cursor/rules/rust-development.mdc @@ -0,0 +1,96 @@ +--- +description: Rust development patterns and conventions for sentry-cli +globs: *.rs,Cargo.*,.cargo/**/*,src/**/*,apple-catalog-parsing/**/* +alwaysApply: false +--- + +# Rust Development Guidelines + +## Code Organization + +- Follow existing module structure in `src/commands/` for new commands +- Use `anyhow::Result` for error handling patterns +- Consider cross-platform compatibility +- Ensure backward compatibility for CLI interface + +## Common Patterns + +- Use existing error types and handling patterns +- Follow established CLI argument parsing patterns using `clap` +- Reuse utility functions from `src/utils/` +- Match existing code style and naming conventions +- Add appropriate logging using `log` crate patterns + +## Development Commands + +```bash +# Essential Rust workflow - run against the whole workspace +cargo build --workspace +cargo test --workspace +cargo clippy --workspace +cargo fmt + +# Local testing +./bin/sentry-cli --help +``` + +## Error Handling Patterns + +- Use `anyhow::Result` for application-level errors +- Use `thiserror` for library-level error types (see `src/utils/auth_token/error.rs`) +- Chain errors with `.context()` for better error messages +- Custom error types in `src/api/errors/` and `src/utils/dif_upload/error.rs` + +## Swift/Apple Integration + +- Swift code in `apple-catalog-parsing/` is used for parsing xarchive files +- Used by the `mobile-app upload` command for iOS app processing +- Built as a separate crate with FFI bindings to Rust +- Only compiled on macOS targets +- Tests run via `swift-test.yml` workflow in CI + +# Rust Testing Guidelines + +## Unit Tests + +- Colocate with source code +- Use `#[cfg(test)]` modules +- Mock external dependencies + +## Integration Tests + +- Use `trycmd` for CLI interface testing when asserting output +- Use `assert_cmd` for testing behavior rather than just output +- Structure: `tests/integration/_cases//.trycmd` +- Fixtures: `tests/integration/_fixtures/` +- Expected outputs: `tests/integration/_expected_outputs/` +- API mocks: `tests/integration/_responses/` + +## Snapshot Management + +```bash +# Update snapshots +TRYCMD=overwrite cargo test + +# Debug test output +TRYCMD=dump cargo test +``` + +## Test Utilities + +- `TestManager`: Sets up test environment with mock server +- `MockEndpointBuilder`: Creates API endpoint mocks +- `copy_recursively`: Helper for fixture setup +- Environment setup via `test_utils::env` + +## Platform-Specific Testing + +- Use `#[cfg(windows)]` for Windows-specific tests +- Separate `.trycmd` files when behavior differs +- Test on CI matrix: Linux, macOS, Windows + +## Assert Command vs Trycmd + +- `trycmd`: Best for testing exact CLI output, supports snapshot testing +- `assert_cmd`: Better for testing behavior, exit codes, and when you need programmatic assertions +- Example of `assert_cmd` usage can be found in `TestManager::run_and_assert()` diff --git a/.cursor/rules/sentry-cli-project.mdc b/.cursor/rules/sentry-cli-project.mdc new file mode 100644 index 0000000000..47ae894f4f --- /dev/null +++ b/.cursor/rules/sentry-cli-project.mdc @@ -0,0 +1,68 @@ +--- +description: Core development guidelines and context for sentry-cli +alwaysApply: true +--- + +# Sentry CLI Development Guidelines + +## Project Overview + +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. + +## Language & Architecture + +- **Primary language**: Rust (core functionality) +- **Secondary language**: JavaScript/TypeScript (npm wrapper, installation scripts) +- **Build system**: Cargo for Rust, npm/yarn for JavaScript +- **Cross-platform**: Supports multiple architectures (darwin, linux, windows, ARM variants) +- **Binary distributions**: Located in `npm-binary-distributions/` for different platforms + +## Project Structure + +- `src/` - Core Rust source code with command modules and utilities +- `js/` - JavaScript wrapper and npm package code +- `scripts/` - Build and utility scripts +- `tests/integration/` - Integration tests using `.trycmd` format +- `npm-binary-distributions/` - Platform-specific binary packages +- `.github/workflows/` - CI/CD workflows (follows reusable workflow pattern) + +## Development Standards + +### Commit Message Format + +**MUST follow Sentry's commit message format**: `type(scope): subject` + +Valid types: `build`, `ci`, `docs`, `feat`, `fix`, `perf`, `ref`, `style`, `test`, `meta`, `license`, `revert` + +Subject requirements: + +- Capitalize first letter +- Use imperative mood ("Add" not "Added") +- No trailing period +- Max 70 characters for header + +Reference: https://develop.sentry.dev/engineering-practices/commit-messages/ + +### Performance & Scale Considerations + +- CLI tool should be fast and responsive +- Consider impact on cold start times +- Memory usage matters for CI environments +- Network operations should be optimized and retryable + +### Security Best Practices + +- Handle authentication tokens securely +- Validate file paths to prevent directory traversal +- Consider impact of processing user-provided files (sourcemaps, debug files) +- Follow Rust security best practices + +## Testing Requirements + +- Unit tests alongside source code +- Integration tests using `.trycmd` format in `tests/integration/` +- Mock HTTP responses in `tests/integration/_responses/` +- Test fixtures in `tests/integration/_fixtures/` +- Cross-platform testing via CI matrix + +Remember: This is a production tool used by many developers. Changes should be well-tested, backward-compatible, and follow established patterns.