From 6b74c4475eb34a8d2d364b0e0fe1bb3bd9f0b27b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 8 Jun 2026 12:15:19 +0000 Subject: [PATCH 1/2] fix(docs): update AGENTS.md from stale Bun references to pnpm/Node/vitest MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md contained extensive Bun-specific guidance that no longer matched the codebase after the migration to pnpm + Node.js + vitest: - Replace 'Built with Bun' with 'Built with Node.js' - Replace all bun commands (bun install, bun test, etc.) with pnpm equivalents - Remove Bun API reference table (Bun.file, Bun.write, Bun.spawn, etc.) - Replace with Node.js API guidance (node:fs, node:child_process) - Fix test framework references from bun:test to vitest - Fix mock API from mock.module() to vi.mock() - Fix test runner config references from Bun flags to vitest.config.ts - Fix BUN_TEST_WORKER_ID to VITEST_POOL_ID - Remove stale .cursor/rules/bun-cli.mdc reference - Replace bun run check:* with pnpm run check:* - Replace bun run generate:* with pnpm run generate:* Co-authored-by: Miguel Betegón --- AGENTS.md | 119 +++++++++++++++++++++--------------------------------- 1 file changed, 46 insertions(+), 73 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 798b0250b..790a468eb 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 [Node.js](https://nodejs.org) and [Stricli](https://bloomberg.github.io/stricli/). ### 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 esbuild + fossilize (Node SEA), SQLite caching for API responses ### Key Features @@ -28,7 +28,6 @@ Guidelines for AI agents working in this codebase. Before working on this codebase, read the Cursor rules: -- **`.cursor/rules/bun-cli.mdc`** - Bun API usage, file I/O, process spawning, testing - **`.cursor/rules/ultracite.mdc`** - Code style, formatting, linting rules ## Quick Reference: Commands @@ -37,70 +36,44 @@ 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 -- --help # Run CLI with args # 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 (vitest) +pnpm run test:e2e # Run end-to-end tests +pnpm run test:unit -- --watch # Watch mode +pnpm run test:unit -- --filter "name" # Run tests matching pattern ``` ## 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`. -## Rules: Use Bun APIs +## Rules: Use Node.js APIs -**CRITICAL**: This project uses Bun as runtime. Always prefer Bun-native APIs over Node.js equivalents. +**CRITICAL**: This project uses Node.js 22.15+ as runtime. Use standard Node.js APIs for file I/O, process spawning, etc. The codebase uses `node:fs`, `node:fs/promises`, `node:child_process`, and other Node.js built-in modules. -Read the full guidelines in `.cursor/rules/bun-cli.mdc`. - -**Bun Documentation**: https://bun.sh/docs - Consult these docs when unsure about Bun APIs. - -### Quick Bun API Reference - -| Task | Use This | NOT This | -|------|----------|----------| -| Read file | `await Bun.file(path).text()` | `fs.readFileSync()` | -| Write file | `await Bun.write(path, content)` | `fs.writeFileSync()` | -| Check file exists | `await Bun.file(path).exists()` | `fs.existsSync()` | -| Spawn process | `Bun.spawn()` | `child_process.spawn()` | -| Shell commands | `Bun.$\`command\`` ⚠️ | `child_process.exec()` | -| Find executable | `Bun.which("git")` | `which` package | -| Glob patterns | `new Bun.Glob()` | `glob` / `fast-glob` packages | -| Sleep | `await Bun.sleep(ms)` | `setTimeout` with Promise | -| Parse JSON file | `await Bun.file(path).json()` | Read + JSON.parse | - -**Exception**: Use `node:fs` for directory creation with permissions: -```typescript -import { mkdirSync } from "node:fs"; -mkdirSync(dir, { recursive: true, mode: 0o700 }); -``` - -**Exception**: `Bun.$` (shell tagged template) has no shim in `script/node-polyfills.ts` and will crash on the npm/node distribution. Until a shim is added, use `execSync` from `node:child_process` for shell commands that must work in both runtimes: ```typescript +import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs"; +import { readFile, writeFile } from "node:fs/promises"; import { execSync } from "node:child_process"; -const result = execSync("id -u username", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }); ``` ## Architecture @@ -409,12 +382,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 +483,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 +527,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 +673,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 +707,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: true` and `pool: "forks"` (see `vitest.config.ts`), 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 +730,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"; @@ -769,24 +742,24 @@ const slugArb = array(constantFrom(..."abcdefghijklmnopqrstuvwxyz0123456789".spl describe("property: myFunction", () => { test("is symmetric", () => { - fcAssert( - property(slugArb, slugArb, (a, b) => { - // Properties should always hold regardless of input - expect(myFunction(a, b)).toBe(myFunction(b, a)); - }), - { numRuns: DEFAULT_NUM_RUNS } - ); + fcAssert( + property(slugArb, slugArb, (a, b) => { + // Properties should always hold regardless of input + expect(myFunction(a, b)).toBe(myFunction(b, a)); + }), + { numRuns: DEFAULT_NUM_RUNS } + ); }); test("round-trip: encode then decode returns original", () => { - fcAssert( - property(validInputArb, (input) => { - const encoded = encode(input); - const decoded = decode(encoded); - expect(decoded).toEqual(input); - }), - { numRuns: DEFAULT_NUM_RUNS } - ); + fcAssert( + property(validInputArb, (input) => { + const encoded = encode(input); + const decoded = decode(encoded); + expect(decoded).toEqual(input); + }), + { numRuns: DEFAULT_NUM_RUNS } + ); }); }); ``` @@ -805,7 +778,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,16 +906,16 @@ 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 () => { - expect(await someFunction("input")).toBe("expected output"); + expect(await someFunction("input")).toBe("expected output"); }); }); // Mock modules when needed -mock.module("./some-module", () => ({ +vi.mock("./some-module", () => ({ default: () => "mocked", })); ``` From 776c41ae890aaeeb618339c7ab1318a3bf4a1988 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 8 Jun 2026 12:17:22 +0000 Subject: [PATCH 2/2] docs: add installer flags to getting-started, expand agentic-usage IDE docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document --no-modify-path, --no-completions, --no-agent-skills installer flags - Document SENTRY_INSTALL_DIR and SENTRY_INIT env vars for the installer - Add CI/Docker example for non-interactive installs - Add Claude Code marketplace install instructions to agentic-usage.md - Add Cursor plugin installation instructions to agentic-usage.md - Expand Requirements section with specific IDE links - Add documentation audit report as docs/DOCUMENTATION_AUDIT.md Co-authored-by: Miguel Betegón --- docs/DOCUMENTATION_AUDIT.md | 243 ++++++++++++++++++++++ docs/src/content/docs/agentic-usage.md | 29 ++- docs/src/content/docs/getting-started.mdx | 19 ++ 3 files changed, 288 insertions(+), 3 deletions(-) create mode 100644 docs/DOCUMENTATION_AUDIT.md diff --git a/docs/DOCUMENTATION_AUDIT.md b/docs/DOCUMENTATION_AUDIT.md new file mode 100644 index 000000000..2d40300ff --- /dev/null +++ b/docs/DOCUMENTATION_AUDIT.md @@ -0,0 +1,243 @@ +# Documentation Audit Report + +Audit performed on 2026-06-08 against commit on branch `cursor/sentry-cli-documentation-audit-ac19`. + +--- + +## A. Undocumented or Missing Commands/Subcommands + +Command docs are auto-generated from CLI metadata by `script/generate-command-docs.ts`, so every route in `src/app.ts` gets a page. However, fragment files (hand-written examples in `docs/src/fragments/commands/`) are the committed source of custom content. All routes have fragments, so no commands are entirely undocumented. + +**No gaps found** — the generation system covers all visible routes. + +--- + +## B. Undocumented Flags + +Since command docs are auto-generated from the Stricli route tree, all non-hidden flags are included in the generated output. The generation script filters out hidden flags and globally-injected flags (`--json`, `--fields`, `--help`, `--helpAll`, `--log-level`). + +**No gaps found** for auto-generated content. + +However, the **`configuration.md` fragment** (`docs/src/fragments/configuration.md`) documents `--log-level` and `--verbose` as global options but does not mention `--org` and `--project` (hidden global flags injected by `buildCommand`). Since these are hidden, this is by design. + +--- + +## C. Missing Usage Examples + +Fragment files provide bash examples for all command groups. Coverage is thin in a few areas: + +| Fragment | Issue | +|----------|-------| +| `schema.md` | Only 2 examples; no example for `--all` or `--search` flags | +| `repo.md` | Only basic list examples (3 lines); no `--limit` or `--fresh` usage | +| `team.md` | Only basic list examples (3 lines); no `--limit` or `--fresh` usage | + +--- + +## D. Stale Descriptions + +No material discrepancies found between `brief` strings in code and doc fragment content. The generation script uses the code's `brief` directly, so these stay in sync by design. + +--- + +## E. Missing Route Mappings in Skill Generator + +The `ROUTE_TO_REFERENCE` map was **removed** in a prior refactor. The current `script/generate-skill.ts` uses a 1:1 route-to-reference mapping (`groupRoutesByReference`), automatically creating one reference file per visible route. **No manual mapping is required, so no gaps exist.** + +--- + +## F. Installation / Distribution Gaps + +### F1. Install script `--version` flag undocumented in `getting-started.mdx` + +The install script accepts `--version ` (aliased as `-v`) to pin a specific version. The getting-started page documents `SENTRY_VERSION` env var and `--version nightly` but does **not** list the full flag syntax: + +``` +-h, --help Show usage +-v, --version Pin version (e.g. 0.19.0) or "nightly" +--no-modify-path Skip shell config PATH edits +--no-completions Skip shell completions +--no-agent-skills Skip agent skill installation +``` + +Only `--version nightly` is shown. The other flags (`--no-modify-path`, `--no-completions`, `--no-agent-skills`) are not documented in any doc page. + +**Source:** `install` script lines ~34-52 +**Expected in:** `docs/src/content/docs/getting-started.mdx` + +### F2. `SENTRY_INIT` env var undocumented in getting-started + +The install script supports `SENTRY_INIT=1` to run `sentry init` after installation. This is documented in `env-registry.ts` but not in `getting-started.mdx`. + +**Source:** `install` script, `src/lib/env-registry.ts` +**Expected in:** `docs/src/content/docs/getting-started.mdx` + +### F3. `SENTRY_INSTALL_DIR` env var undocumented in getting-started + +The install script supports `SENTRY_INSTALL_DIR` to override the install location. Not documented in getting-started. + +**Source:** `install` script, `src/lib/env-registry.ts` +**Expected in:** `docs/src/content/docs/getting-started.mdx` + +### F4. Alpine/musl auto-dependency installation undocumented + +The install script auto-installs `libstdc++` and `libgcc` via `apk` on Alpine Linux when running as root. This is not documented anywhere. + +**Source:** `install` script (function `ensure_alpine_deps`) +**Expected in:** `docs/src/content/docs/getting-started.mdx` (Supported Platforms section) + +### F5. Windows installation support understated + +The getting-started page says Windows is supported "Via Git Bash, MSYS2, or WSL" but does not explain that the installer only supports x64 on Windows. Also, PowerShell is explicitly not supported by the curl installer. + +**Source:** `install` script +**Expected in:** `docs/src/content/docs/getting-started.mdx` + +### F6. `yarn` missing from README "Run Without Installing" + +README shows `npx`, `pnpm dlx`, `yarn dlx`, `bunx` for running without installing, and also shows `yarn global add sentry` in the package managers section. The docs index page does NOT include `yarn` in the install selector component. This is a minor inconsistency. + +**Source:** `README.md` line 47, `docs/src/content/docs/index.mdx` InstallSelector +**Expected in:** consistency between README.md and docs index + +--- + +## G. Undocumented Environment Variables + +The `env-registry.ts` is the authoritative list. Since `configuration.md` is **generated** from the registry, all registered variables will appear in the generated page. However, several environment variables used in the source code are **not registered** in `env-registry.ts`: + +| Variable | Used In | Description | +|----------|---------|-------------| +| `SENTRY_SPOTLIGHT` | `src/commands/local/run.ts` | Spotlight URL injected into child processes | +| `SENTRY_TRACES_SAMPLE_RATE` | `src/commands/local/run.ts` | Trace sample rate injected by `local run` | +| `SENTRY_MONITOR_SLUG` | `src/commands/monitor/run.ts` | Monitor slug passed to wrapped command | + +These are **injected** env vars (set by the CLI for child processes) rather than **read** env vars, so excluding them from the configuration page may be intentional. However, `SENTRY_MONITOR_SLUG` is documented in the monitor fragment, while `SENTRY_SPOTLIGHT` and `SENTRY_TRACES_SAMPLE_RATE` are mentioned in the local fragment and agent-guidance.md. + +--- + +## H. Auth / Self-Hosted Gaps + +### H1. OAuth scopes: `event:admin` missing from docs + +The `OAUTH_SCOPES` array in `src/lib/oauth.ts` includes: +``` +project:read, project:write, project:admin, org:read, event:read, event:write, member:read, team:read, team:write +``` + +The generated sections in `DEVELOPMENT.md` and `self-hosted.md` match. **No gap found** — the docs are generated from the same source. + +### H2. Token storage `host` column undocumented + +The auth database schema (v16+) includes a `host` column that scopes tokens to specific Sentry instances. The `self-hosted.md` page mentions "Once authenticated, the CLI stores your instance URL" but does not explain the host-scoping security model (that tokens are rejected if the request host doesn't match the stored host). + +**Source:** `src/lib/db/auth.ts` +**Expected in:** `docs/src/content/docs/self-hosted.md` + +### H3. `--read-only` and `--scope` flags on `auth login` undocumented in getting-started + +The `auth login` command supports `--read-only` (request only read scopes) and `--scope` (custom scope list). These are documented in the auto-generated command page but not mentioned in `getting-started.mdx` or `self-hosted.md`. + +**Source:** `src/commands/auth/login.ts` +**Expected in:** `docs/src/content/docs/getting-started.mdx`, `docs/src/content/docs/self-hosted.md` + +### H4. Login trust anchor security model undocumented + +The `--url` flag on `auth login` is described as "the most secure way to authenticate with a new host" in a `:::note` in self-hosted.md, but the full security model (trust anchors, untrusted host refusal, `.sentryclirc` bypass protection) is not explained. + +**Source:** `src/commands/auth/login.ts` (`refuseLoginToUntrustedHost`, `applyLoginUrl`) +**Expected in:** `docs/src/content/docs/self-hosted.md` + +--- + +## I. Plugin/Skills Gaps + +### I1. Cursor plugin installation not documented in `agentic-usage.md` + +The `plugins/README.md` documents Cursor support via `.cursor/skills/` symlink, but `agentic-usage.md` only mentions "Claude Code" and "any agent that reads from `~/.agents` such as Cursor". The Cursor plugin system (via `.cursor/skills/` directory and the skills plugin format) is not described in the agentic-usage page. + +**Source:** `plugins/README.md` +**Expected in:** `docs/src/content/docs/agentic-usage.md` + +### I2. Claude Code marketplace installation undocumented in `agentic-usage.md` + +The `plugins/README.md` describes `claude plugin marketplace add getsentry/cli` for installing via the Claude Code marketplace. This method is not mentioned in `agentic-usage.md`. + +**Source:** `plugins/README.md` +**Expected in:** `docs/src/content/docs/agentic-usage.md` + +### I3. `npx skills add` command may be outdated + +The `agentic-usage.md` page suggests `npx skills add https://cli.sentry.dev` for manual installation. The actual skill install mechanism in code (`src/lib/agent-skills.ts`) writes files directly to `~/.agents/skills/` or `~/.claude/skills/` directories. The `npx skills add` command is an external tool not part of this repository. If this external tool no longer exists or works differently, this advice could be stale. + +**Source:** `docs/src/content/docs/agentic-usage.md` + +--- + +## J. README / DEVELOPMENT.md / AGENTS.md Drift + +### J1. **CRITICAL: AGENTS.md references Bun throughout, but the project uses pnpm + Node.js + vitest** + +This is the **single largest documentation drift** in the repository. AGENTS.md contains extensive Bun-specific guidance that no longer matches the codebase: + +| AGENTS.md Claim | Actual Codebase | +|-----------------|-----------------| +| "Built with Bun" | Built with pnpm + esbuild + fossilize | +| "Use Bun as runtime" | Uses Node.js 22.15+ as runtime | +| `bun install` | `pnpm install` | +| `bun run dev` | `pnpm run dev` | +| `bun test` | `vitest` via `pnpm run test:unit` | +| `bun run lint` | `pnpm run lint` | +| `Bun.file(path).text()` | Standard Node.js `fs` APIs | +| `Bun.write(path, content)` | Standard Node.js `fs` APIs | +| `Bun.spawn()` | `child_process` / `execSync` | +| `Bun.which()` | Not used | +| `Bun.Glob()` | Not used | +| `Bun.sleep(ms)` | Not used | +| `bun:test` imports | `vitest` imports | +| `bun add -d ` | `pnpm add -d ` | +| "Native binaries via Bun" | Native binaries via esbuild + fossilize (Node SEA) | +| `bun run --env-file=.env.local` | `dotenv` / `export $(cat .env.local)` | +| "Bun's test runner uses `--isolate --parallel`" | vitest uses `isolate: true, pool: "forks"` | +| `BUN_TEST_WORKER_ID` | Not applicable (vitest) | + +The Quick Bun API Reference table, the exception notes about `Bun.$`, and numerous inline references to Bun APIs are all stale. + +**Source:** `AGENTS.md` throughout, vs. `package.json`, `vitest.config.ts`, `src/**/*.ts` + +### J2. AGENTS.md test commands are wrong + +| AGENTS.md | Actual (`package.json`) | +|-----------|------------------------| +| `bun test` | `pnpm run test:unit` (runs vitest) | +| `bun test path/to/file.test.ts` | `pnpm run test:unit -- test/path/file.test.ts` | +| `bun test --watch` | `pnpm run test:unit -- --watch` | +| `bun test --filter "test name"` | `pnpm run test:unit -- --filter "test name"` | +| `bun run test:unit` | `pnpm run test:unit` | +| `bun run test:e2e` | `pnpm run test:e2e` | + +### J3. AGENTS.md "Testing (bun:test + fast-check)" section header is wrong + +Should be "Testing (vitest + fast-check)". All test imports use `from "vitest"` not `from "bun:test"`. + +### J4. README and DEVELOPMENT.md are correct + +Both README.md and DEVELOPMENT.md correctly use `pnpm` and reference Node.js 22.15+. Their generated sections are maintained by `script/generate-docs-sections.ts`. **No drift found in these files.** + +### J5. No additional drift found in DEVELOPMENT.md + +Both README.md and DEVELOPMENT.md correctly use `pnpm`, reference Node.js 22.15+, and `.env.example` exists as referenced in contributing.md. + +--- + +## Top 5 Most Impactful Fixes (Prioritized) + +1. **Fix AGENTS.md Bun→pnpm/Node/vitest migration** (J1-J3): AGENTS.md is the primary guidance for AI agents working on the codebase. Every Bun reference leads agents to write incorrect code, use wrong commands, and import from non-existent modules. This affects every agent interaction. + +2. **Add install script flags to getting-started.mdx** (F1): Users/CI pipelines need `--no-modify-path`, `--no-completions`, `--no-agent-skills` for non-interactive installs but can't discover them from the docs. + +3. **Expand bash examples in schema.md fragment** (C): The schema command has the thinnest example coverage relative to its feature set (`--all`, `--search` flags). + +4. **Document Cursor plugin installation in agentic-usage.md** (I1-I2): Cursor is a widely-used IDE; the current doc only mentions Claude Code and generic `~/.agents`. + +5. **Document host-scoping security model in self-hosted.md** (H2): Users running self-hosted Sentry don't understand why tokens are rejected when the request host doesn't match the stored host. diff --git a/docs/src/content/docs/agentic-usage.md b/docs/src/content/docs/agentic-usage.md index f18193b1a..7c22fbfd9 100644 --- a/docs/src/content/docs/agentic-usage.md +++ b/docs/src/content/docs/agentic-usage.md @@ -13,13 +13,33 @@ To skip automatic skill installation, pass `--no-agent-skills` to `sentry cli se ## Manual Installation -Add the Sentry CLI skill to your agent manually: +### Claude Code + +Install via the Claude Code plugin marketplace: + +```bash +claude plugin marketplace add getsentry/cli +claude plugin install sentry/cli +``` + +### Cursor + +Cursor reads skills from the `.cursor/skills/` directory. You can symlink or copy the plugin's skill files: + +```bash +# From a local clone of the CLI repo +ln -s /path/to/cli/plugins/sentry-cli/skills/sentry-cli ~/.cursor/skills/sentry-cli +``` + +### Other Agents + +For agents that read from `~/.agents` (the open [Agent Skills](https://github.com/getsentry/skills) format): ```bash npx skills add https://cli.sentry.dev ``` -This registers the Sentry CLI as a skill that your agent can invoke when needed. +Or manually copy the skill files from `plugins/sentry-cli/skills/sentry-cli/` into your agent's skills directory. ## Capabilities @@ -49,4 +69,7 @@ The skill uses your existing CLI authentication, so you'll need to run `sentry a ## 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: + - [Claude Code](https://claude.ai/code) — via plugin marketplace or `~/.claude/skills/` + - [Cursor](https://cursor.sh) — via `.cursor/skills/` directory + - Any agent that reads from `~/.agents/skills/` (the open [Agent Skills](https://github.com/getsentry/skills) format) diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index ab018ccf8..6951c473b 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -36,6 +36,25 @@ The `--version` flag takes precedence over `SENTRY_VERSION` if both are set. The chosen channel is persisted so that `sentry cli upgrade` automatically tracks the same channel on future updates. +#### Installer Flags + +The install script accepts these flags (pass them after `--` when piping to bash): + +| Flag | Description | +|------|-------------| +| `--version ` | Pin to a specific version or `nightly` | +| `--no-modify-path` | Skip adding the install directory to your shell PATH | +| `--no-completions` | Skip installing shell completions | +| `--no-agent-skills` | Skip installing AI agent skill files | + +```bash +# CI/Docker: install without modifying PATH or shell config +curl https://cli.sentry.dev/install -fsS | bash -s -- --no-modify-path --no-completions +``` + +You can also set `SENTRY_INSTALL_DIR` to control where the binary is placed, +and `SENTRY_INIT=1` to run `sentry init` after installation. + #### Supported Platforms {/* GENERATED:START platform-support */}