From 46bc693de6ca2de0309a33a57c167179252f1412 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 20 Jul 2026 12:12:20 +0000 Subject: [PATCH 1/4] =?UTF-8?q?docs:=20fix=20AGENTS.md=20toolchain=20drift?= =?UTF-8?q?=20(bun=20=E2=86=92=20pnpm/vitest)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md Quick Reference and Testing sections still referenced bun as the package manager and test runner. The actual toolchain is pnpm@10.11.0 with vitest for testing. Updated: - All 'bun install/run/test' → 'pnpm install/run' + vitest - 'bun add -d' → 'pnpm add -D' - 'bun:test' imports → 'vitest' - 'mock.module()' → 'vi.mock()' - BUN_TEST_WORKER_ID → VITEST_POOL_ID - 'Bun'\''s test runner' → 'Vitest' Co-authored-by: Miguel Betegón --- AGENTS.md | 50 +++++++++++------------ docs/src/content/docs/agentic-usage.md | 13 +++++- docs/src/content/docs/getting-started.mdx | 4 +- docs/src/fragments/commands/proguard.md | 21 ++++++++++ src/commands/cli/upgrade.ts | 2 +- src/lib/env-registry.ts | 2 +- 6 files changed, 60 insertions(+), 32 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 798b0250b9..5cd17b59f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,35 +37,33 @@ Before working on this codebase, read the Cursor rules: ```bash # Development -bun install # Install dependencies -bun run dev # Run CLI in dev mode -bun run --env-file=.env.local src/bin.ts # Dev with env vars +pnpm install # Install dependencies +pnpm run dev # Run CLI in dev mode +pnpm run cli # Run CLI with .env.local # Build -bun run build # Build for current platform -bun run build:all # Build for all platforms +pnpm run build # Build for current platform +pnpm run build:all # Build for all platforms # Type Checking -bun run typecheck # Check types +pnpm run typecheck # Check types # Linting & Formatting -bun run lint # Check for issues -bun run lint:fix # Auto-fix issues (run before committing) +pnpm run lint # Check for issues +pnpm run lint:fix # Auto-fix issues (run before committing) # Testing -bun test # Run all tests -bun test path/to/file.test.ts # Run single test file -bun test --watch # Watch mode -bun test --filter "test name" # Run tests matching pattern -bun run test:unit # Run unit tests only -bun run test:e2e # Run e2e tests only +pnpm run test:unit # Run unit tests only +pnpm run test:e2e # Run e2e tests only +vitest run test/lib/some.test.ts # Run single test file +vitest --watch # Watch mode ``` ## Rules: No Runtime Dependencies -**CRITICAL**: All packages must be in `devDependencies`, never `dependencies`. Everything is bundled at build time via esbuild. CI enforces this with `bun run check:deps`. +**CRITICAL**: All packages must be in `devDependencies`, never `dependencies`. Everything is bundled at build time via esbuild. CI enforces this with `pnpm run check:deps`. -When adding a package, always use `bun add -d ` (the `-d` flag). +When adding a package, always use `pnpm add -D ` (the `-D` flag). When the `@sentry/api` SDK provides types for an API response, import them directly from `@sentry/api` instead of creating redundant Zod schemas in `src/types/sentry.ts`. @@ -409,12 +407,12 @@ Use `"date"` for timestamp-based sort (not `"time"`). Export sort types from the ### Generated Docs & Skills -All command docs and skill files are generated via `bun run generate:docs` (which runs `generate:command-docs` then `generate:skill`). This runs automatically as part of `dev`, `build`, `typecheck`, and `test` scripts. +All command docs and skill files are generated via `pnpm run generate:docs` (which runs `generate:command-docs` then `generate:skill`). This runs automatically as part of `dev`, `build`, `typecheck`, and `test` scripts. - **Command docs** (`docs/src/content/docs/commands/*.md`) are **gitignored** and generated from CLI metadata + hand-written fragments in `docs/src/fragments/commands/`. - **Skill files** (`plugins/sentry-cli/skills/sentry-cli/`) are **committed** (consumed by external plugin systems) and auto-committed by CI when stale. - Edit fragments in `docs/src/fragments/commands/` for custom examples and guides. -- `bun run check:fragments` validates fragment ↔ route consistency. +- `pnpm run check:fragments` validates fragment ↔ route consistency. - Positional `placeholder` values must be descriptive: `"org/project/trace-id"` not `"args"`. ### Zod Schemas for Validation @@ -510,7 +508,7 @@ CliError (base, exitCode=1) - Pass `alternatives: []` when defaults are irrelevant (e.g., for missing Trace ID, Event ID) - Use `" and "` in `resource` for plural grammar: `"Trace ID and span ID"` → "are required" -**CI enforcement:** `bun run check:errors` scans for `ContextError` with multiline commands, `CliError` with ad-hoc "Try:" strings, and silent `catch` blocks (advisory). +**CI enforcement:** `pnpm run check:errors` scans for `ContextError` with multiline commands, `CliError` with ad-hoc "Try:" strings, and silent `catch` blocks (advisory). ```typescript // Usage examples @@ -554,7 +552,7 @@ catch (error) { Use `logger.withTag("command-name")` for tagged logging in command files. -**CI enforcement:** `bun run check:errors` includes a silent-catch scan that flags +**CI enforcement:** `pnpm run check:errors` includes a silent-catch scan that flags `catch` blocks which are empty, comment-only, or return-only without surfacing the error. It is currently **advisory** (warns, does not fail CI) because of a pre-existing backlog; run with `SENTRY_STRICT_SILENT_CATCH=1` to enforce. Do not add new silent @@ -700,7 +698,7 @@ await deleteUserData(userId) ### Goal Minimal comments, maximum clarity. Comments explain **intent and reasoning**, not syntax. -## Testing (bun:test + fast-check) +## Testing (vitest + fast-check) **Prefer property-based and model-based testing** over traditional unit tests. These approaches find edge cases automatically and provide better coverage with less code. @@ -734,7 +732,7 @@ Tests that need a database or config directory **must** use `useTestConfigDir()` - `const baseDir = process.env[CONFIG_DIR_ENV_VAR]!` at module scope — This captures a value that may be stale - Manual `beforeEach`/`afterEach` that sets/deletes `SENTRY_CONFIG_DIR` -**Why**: Bun's test runner uses `--isolate --parallel` (see `test:unit` in `package.json`), so each test file runs in a fresh global environment within a worker process. That bounds most cross-file leaks to a single worker, but `process.env` is still shared within a file's lifecycle — if your `afterEach` deletes the env var, the next describe/test's module-level code (or a beforeEach that re-reads env) gets `undefined`, causing `TypeError: The "paths[0]" property must be of type string`. Also, `TEST_TMP_DIR` is namespaced by `BUN_TEST_WORKER_ID` in `test/constants.ts` so parallel workers don't wipe each other's temp state during preload. +**Why**: Vitest runs with `--isolate` (see `test:unit` in `package.json`), so each test file runs in a fresh global environment within a worker process. That bounds most cross-file leaks to a single worker, but `process.env` is still shared within a file's lifecycle — if your `afterEach` deletes the env var, the next describe/test's module-level code (or a beforeEach that re-reads env) gets `undefined`, causing `TypeError: The "paths[0]" property must be of type string`. Also, `TEST_TMP_DIR` is namespaced by `VITEST_POOL_ID` in `test/constants.ts` so parallel workers don't wipe each other's temp state during preload. ```typescript // CORRECT: Use the helper @@ -757,7 +755,7 @@ afterEach(() => { delete process.env.SENTRY_CONFIG_DIR; }); // BUG! Use property-based tests when verifying invariants that should hold for **any valid input**. ```typescript -import { describe, expect, test } from "bun:test"; +import { describe, expect, test } from "vitest"; import { constantFrom, assert as fcAssert, property, tuple } from "fast-check"; import { DEFAULT_NUM_RUNS } from "../model-based/helpers.js"; @@ -805,7 +803,7 @@ describe("property: myFunction", () => { Use model-based tests for **stateful systems** where sequences of operations should maintain invariants. ```typescript -import { describe, expect, test } from "bun:test"; +import { describe, expect, test } from "vitest"; import { type AsyncCommand, asyncModelRun, @@ -933,7 +931,7 @@ When adding property tests for a function that already has unit tests, **remove ``` ```typescript -import { describe, expect, test, mock } from "bun:test"; +import { describe, expect, test, vi } from "vitest"; describe("feature", () => { test("should return specific value", async () => { @@ -942,7 +940,7 @@ describe("feature", () => { }); // Mock modules when needed -mock.module("./some-module", () => ({ +vi.mock("./some-module", () => ({ default: () => "mocked", })); ``` diff --git a/docs/src/content/docs/agentic-usage.md b/docs/src/content/docs/agentic-usage.md index f18193b1a0..4550a9bf01 100644 --- a/docs/src/content/docs/agentic-usage.md +++ b/docs/src/content/docs/agentic-usage.md @@ -3,7 +3,7 @@ title: Agentic Usage description: Enable AI coding agents to use the Sentry CLI --- -AI coding agents like Claude Code — and any agent that reads skills from `~/.agents` (such as Cursor) — can use the Sentry CLI through the skill system. This allows agents to interact with Sentry directly from your development environment. +AI coding agents like Claude Code, Cursor, Windsurf, Gemini CLI, OpenAI Codex, Goose, Amp, Augment, and OpenCode can use the Sentry CLI through the skill system. This allows agents to interact with Sentry directly from your development environment. ## Automatic Installation @@ -46,7 +46,16 @@ The CLI has dedicated commands for most Sentry tasks, so agents should prefer `s The skill uses your existing CLI authentication, so you'll need to run `sentry auth login` first if you haven't already. +## Supported Agents + +The CLI detects and supports the following AI coding agents: + +- **Claude Code** — skills installed to `~/.claude` +- **Cursor, Windsurf, Gemini CLI, OpenAI Codex, Goose, Amp, Augment, OpenCode** — skills installed to `~/.agents` + +Any other agent that reads from `~/.agents/skills/` is also supported automatically. + ## Requirements - An authenticated Sentry CLI installation (`sentry auth login`) -- An AI coding agent that supports the skills system (e.g., Claude Code, or any agent that reads from `~/.agents` such as Cursor) +- An AI coding agent that supports the skills system diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index a6e3fcc07f..a6598ca7fa 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -24,7 +24,7 @@ which is especially useful in CI/CD pipelines and Dockerfiles: ```bash # Pin to a specific stable version -SENTRY_VERSION=0.19.0 curl https://cli.sentry.dev/install -fsS | bash +SENTRY_VERSION=0.38.0 curl https://cli.sentry.dev/install -fsS | bash # Pin to nightly SENTRY_VERSION=nightly curl https://cli.sentry.dev/install -fsS | bash @@ -75,7 +75,7 @@ brew install getsentry/tools/sentry ## Package Managers -Install globally with your preferred package manager (the npm/pnpm/yarn packages require **Node.js 22.15+**): +Install globally with your preferred package manager (the npm/pnpm/yarn packages require **Node.js 18+**; on Node.js 22.15+ the CLI uses built-in `node:sqlite`, on 18–22.14 it falls back to a bundled WASM SQLite driver): Date: Mon, 20 Jul 2026 12:13:19 +0000 Subject: [PATCH 2/4] =?UTF-8?q?docs:=20update=20stale=20version=20pin=20ex?= =?UTF-8?q?amples=20(0.19.0=20=E2=86=92=200.38.0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The install script usage help and getting-started docs still showed 0.19.0 as the version pinning example. Updated to the current latest release 0.38.0. Co-authored-by: Miguel Betegón --- install | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/install b/install index ca2b6b8d77..7064d36ecc 100755 --- a/install +++ b/install @@ -89,14 +89,14 @@ Options: Environment Variables: SENTRY_INSTALL_DIR Override the installation directory - SENTRY_VERSION Install a specific version (e.g., 0.19.0, nightly) + SENTRY_VERSION Install a specific version (e.g., 0.38.0, nightly) SENTRY_INIT Set to 1 to run \`sentry init\` after installing Examples: curl -fsSL https://cli.sentry.dev/install | bash curl -fsSL https://cli.sentry.dev/install | SENTRY_INIT=1 bash curl -fsSL https://cli.sentry.dev/install | bash -s -- --version nightly - curl -fsSL https://cli.sentry.dev/install | bash -s -- --version 0.19.0 + curl -fsSL https://cli.sentry.dev/install | bash -s -- --version 0.38.0 SENTRY_VERSION=nightly curl -fsSL https://cli.sentry.dev/install | bash SENTRY_INSTALL_DIR=~/.local/bin curl -fsSL https://cli.sentry.dev/install | bash EOF From fd1b0895772ecc8742439b63bd70df3db08b2749 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 20 Jul 2026 12:13:48 +0000 Subject: [PATCH 3/4] =?UTF-8?q?docs(AGENTS.md):=20fix=20project=20overview?= =?UTF-8?q?=20=E2=80=94=20esbuild/fossilize,=20not=20Bun?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CLI is bundled with esbuild and packaged into Node.js SEA binaries via fossilize. Bun APIs are used in source but shimmed for the Node.js distribution. Updated the overview to reflect the actual build pipeline. Co-authored-by: Miguel Betegón --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5cd17b59f8..4c03a7542a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Guidelines for AI agents working in this codebase. ## Project Overview -**Sentry CLI** is a command-line interface for [Sentry](https://sentry.io), built with [Bun](https://bun.sh) and [Stricli](https://bloomberg.github.io/stricli/). +**Sentry CLI** is a command-line interface for [Sentry](https://sentry.io), built with [Stricli](https://bloomberg.github.io/stricli/) and bundled via [esbuild](https://esbuild.github.io/) into standalone Node.js SEA binaries (via [fossilize](https://github.com/nicolo-ribaudo/fossilize)). Source code uses [Bun](https://bun.sh) APIs for file I/O and process spawning, shimmed for the Node.js distribution. ### Goals @@ -12,7 +12,7 @@ Guidelines for AI agents working in this codebase. - **AI-powered debugging** - Integrate Seer AI for root cause analysis and fix plans - **Developer-friendly** - Follow `gh` CLI conventions for intuitive UX - **Agent-friendly** - JSON output and predictable behavior for AI coding agents -- **Fast** - Native binaries via Bun, SQLite caching for API responses +- **Fast** - Native binaries via Node.js SEA, SQLite caching for API responses ### Key Features From b023e9d783a8518f30ce4b01974348cf6129819d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 20 Jul 2026 12:16:06 +0000 Subject: [PATCH 4/4] chore: regenerate docs --- .../skills/sentry-cli/references/proguard.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/plugins/sentry-cli/skills/sentry-cli/references/proguard.md b/plugins/sentry-cli/skills/sentry-cli/references/proguard.md index c5049a020f..6b0de2371b 100644 --- a/plugins/sentry-cli/skills/sentry-cli/references/proguard.md +++ b/plugins/sentry-cli/skills/sentry-cli/references/proguard.md @@ -20,6 +20,25 @@ Upload ProGuard/R8 mapping files to Sentry - `--no-upload - Compute and print UUIDs without uploading (dry-run)` - `--require-one - Require at least one mapping file (error if none provided)` +**Examples:** + +```bash +# Upload a ProGuard/R8 mapping file (org/project auto-detected) +sentry proguard upload ./app/build/outputs/mapping/release/mapping.txt + +# Upload multiple mapping files at once +sentry proguard upload build/mapping1.txt build/mapping2.txt + +# Upload with a forced UUID (single file only) +sentry proguard upload mapping.txt --uuid 5db7294d-87fc-5726-a5c0-4a90679657a5 + +# Dry run — compute UUIDs without uploading +sentry proguard upload mapping.txt --no-upload + +# Require at least one file (useful in CI — fails if glob expands to nothing) +sentry proguard upload build/outputs/**/*.txt --require-one +``` + ### `sentry proguard uuid ` Compute the UUID for a ProGuard mapping file