meta: Add Cursor rules

.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

.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

.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.

.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/<command>/<test>.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()`

.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.