|
| 1 | +# Documentation Audit Report |
| 2 | + |
| 3 | +Audit of the Sentry CLI repository comparing implementation (`src/`) to documentation |
| 4 | +(`README.md`, `DEVELOPMENT.md`, `AGENTS.md`, `docs/src/content/docs/`, `docs/src/fragments/`). |
| 5 | + |
| 6 | +Generated: 2026-05-25 |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## A. Undocumented or Missing Commands/Subcommands |
| 11 | + |
| 12 | +Command docs are auto-generated from code metadata plus hand-written fragments in |
| 13 | +`docs/src/fragments/commands/`. The fragment-to-route mapping is CI-enforced and currently |
| 14 | +1:1 complete. However, several **subcommands within a route** lack coverage in their fragment: |
| 15 | + |
| 16 | +| Command | Source | Fragment (`docs/src/fragments/commands/`) | Gap | |
| 17 | +|---------|--------|-------------------------------------------|-----| |
| 18 | +| `sentry issue events` | `src/commands/issue/events.ts` | `issue.md` | No example or mention in fragment; only covered indirectly via `event.md` (`sentry event list`) | |
| 19 | +| `sentry dashboard revisions` | `src/commands/dashboard/revisions.ts` | `dashboard.md` | Not mentioned in fragment | |
| 20 | +| `sentry dashboard restore` | `src/commands/dashboard/restore.ts` | `dashboard.md` | Not mentioned in fragment | |
| 21 | +| `sentry cli import` | `src/commands/cli/import.ts` | `cli.md` | No example in fragment | |
| 22 | +| `sentry cli defaults` | `src/commands/cli/defaults.ts` | `cli.md` | No example in fragment (documented only in `configuration.md` fragment) | |
| 23 | + |
| 24 | +**Note:** `sentry cli defaults` being in `configuration.md` may be intentional, but the |
| 25 | +`cli.md` fragment has zero mention of it, which is confusing since it's under `sentry cli`. |
| 26 | + |
| 27 | +--- |
| 28 | + |
| 29 | +## B. Undocumented Flags |
| 30 | + |
| 31 | +These non-hidden flags are defined in code but not demonstrated or mentioned in their |
| 32 | +corresponding fragment. The auto-generated reference tables do include them, but the |
| 33 | +hand-written examples and prose do not cover them: |
| 34 | + |
| 35 | +| Command | Flag | Fragment | |
| 36 | +|---------|------|----------| |
| 37 | +| `sentry auth login` | `--url`, `--timeout`, `--force` | `auth.md` — only env-based self-hosted shown | |
| 38 | +| `sentry explore` | `--environment` / `-e` | `explore.md` | |
| 39 | +| `sentry explore` | `--dataset replays` | `explore.md` | |
| 40 | +| `sentry log list` | `--period` / `-t` | `log.md` | |
| 41 | +| `sentry log list` | `--sort` / `-s` | `log.md` | |
| 42 | +| `sentry local serve` | `--host` / `-H` | `local.md` | |
| 43 | +| `sentry local run` | `--host`, `--port` flags | `local.md` — only bare example shown | |
| 44 | +| `sentry local serve` | `--filter ai` value | `local.md` — `ai` not listed as filter option | |
| 45 | +| `sentry api` | `--silent`, `--raw-field` / `-f` | `api.md` | |
| 46 | +| `sentry dashboard widget add` | `--dataset` | `dashboard.md` — rich docs only in code `fullDescription` | |
| 47 | +| `sentry issue view` | `--spans` | `issue.md` | |
| 48 | +| `sentry issue archive` | `--until` compound syntax | `issue.md` — basic syntax shown, compound mode underdocumented | |
| 49 | + |
| 50 | +--- |
| 51 | + |
| 52 | +## C. Missing Usage Examples |
| 53 | + |
| 54 | +These subcommands exist in the CLI but have no bash examples in any fragment: |
| 55 | + |
| 56 | +| Command | Fragment | |
| 57 | +|---------|----------| |
| 58 | +| `sentry issue events` | `issue.md` | |
| 59 | +| `sentry dashboard revisions` | `dashboard.md` | |
| 60 | +| `sentry dashboard restore` | `dashboard.md` | |
| 61 | +| `sentry cli import` | `cli.md` | |
| 62 | +| `sentry cli defaults` (in `cli.md`) | `cli.md` (examples exist in `configuration.md` only) | |
| 63 | + |
| 64 | +--- |
| 65 | + |
| 66 | +## D. Stale Descriptions |
| 67 | + |
| 68 | +| Location | Doc says | Code says | Impact | |
| 69 | +|----------|----------|-----------|--------| |
| 70 | +| `README.md` (GENERATED:START dev-prereq) | "Bun v1.3+" as prerequisite | Build uses `fossilize` (Node SEA), not Bun. `AGENTS.md` says "built with Node.js". `packageManager` is `pnpm@10.11.0`. | **High** — misleads contributors into installing Bun unnecessarily | |
| 71 | +| `DEVELOPMENT.md` line 5 | "Bun installed" as prerequisite | Same as above — Bun not needed for dev or build | **High** | |
| 72 | +| `DEVELOPMENT.md` line 91 | "Building the native binary still requires Bun" | Build uses `fossilize` + Node SEA, not Bun | **High** | |
| 73 | +| `contributing.md` (GENERATED) | "Bun runtime (v1.3 or later)" | Same | **High** | |
| 74 | +| `script/generate-docs-sections.ts` | `generateDevPrereq()` hard-codes Bun | Should reference Node.js ≥22.15 or just pnpm | **Root cause** of all Bun prerequisite mentions | |
| 75 | +| `AGENTS.md` line 15 | "Native binaries via Node SEA" | Correct ✓ | N/A | |
| 76 | +| `library-usage.md` | "Node.js (≥22.15) or Bun" | Library API works via CJS bundle — Bun runtime support is plausible but untested; `engines` only lists Node | Low | |
| 77 | + |
| 78 | +--- |
| 79 | + |
| 80 | +## E. Missing Route Mappings in Skill Generator |
| 81 | + |
| 82 | +The `ROUTE_TO_REFERENCE` map no longer exists in `script/generate-skill.ts`. It was |
| 83 | +replaced by a 1:1 `groupRoutesByReference()` function that generates a reference file |
| 84 | +per visible route. **All visible routes are covered.** Hidden plural aliases and `whoami` |
| 85 | +are correctly excluded. |
| 86 | + |
| 87 | +No gaps found in this section. |
| 88 | + |
| 89 | +--- |
| 90 | + |
| 91 | +## F. Installation / Distribution Gaps |
| 92 | + |
| 93 | +| Gap | Source | Doc location | Details | |
| 94 | +|-----|--------|--------------|---------| |
| 95 | +| **Bun prerequisite is wrong** | `script/generate-docs-sections.ts` → `generateDevPrereq()` | `README.md`, `DEVELOPMENT.md`, `contributing.md` | Build uses fossilize/Node SEA; Bun is not required. The generator falls back to "1.3" when `packageManager` doesn't contain `bun@` | |
| 96 | +| `SENTRY_INSTALL_DIR` | `install` script, `src/commands/cli/setup.ts` | Not in `getting-started.mdx` | Install dir override documented only in generated `configuration.md`; should be mentioned in install script docs | |
| 97 | +| `SENTRY_INIT` | `install` script | Not in `getting-started.mdx` | Post-install init wizard trigger not mentioned | |
| 98 | +| Install script `--no-*` flags | `install` script accepts `--no-modify-path`, `--no-completions`, `--no-agent-skills` | `getting-started.mdx` | Only `--version nightly` shown; skip flags undocumented | |
| 99 | +| Install directory precedence | `install` script: `SENTRY_INSTALL_DIR` → `~/.local/bin` → `~/bin` → `~/.sentry/bin` | Not documented | Users may want to control where the binary lands | |
| 100 | +| Alpine/musl auto-install | Install script auto-installs `libstdc++ libgcc` on Alpine | Not documented | Affects Docker/CI users on Alpine | |
| 101 | +| `yarn global add sentry` | Package manager support in code | `getting-started.mdx` has yarn; `README.md` does not list yarn | Minor inconsistency | |
| 102 | +| `pnpm dlx`, `yarn dlx`, `bunx` | Supported in `getting-started.mdx` | `README.md` only shows `npx` | Minor inconsistency | |
| 103 | +| Nightly not available via package managers | `upgrade.ts` migrates to curl binary when switching to nightly from npm/pnpm/bun/yarn | Not documented in `getting-started.mdx` | Users switching to nightly may be surprised by binary location change | |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## G. Undocumented Environment Variables |
| 108 | + |
| 109 | +The environment variable reference is generated from `src/lib/env-registry.ts` into |
| 110 | +`docs/src/content/docs/configuration.md` (gitignored). The registry is comprehensive. |
| 111 | + |
| 112 | +**Variables in code but NOT in `env-registry.ts`:** |
| 113 | + |
| 114 | +| Variable | Used in | Notes | |
| 115 | +|----------|---------|-------| |
| 116 | +| `SENTRY_SPOTLIGHT` | `src/commands/local/run.ts` | Injected by `sentry local run`; not user-facing (internal to Sentry SDK) | |
| 117 | +| `SENTRY_TRACES_SAMPLE_RATE` | `src/commands/local/run.ts` | Injected by `sentry local run`; not user-facing | |
| 118 | +| `SENTRY_CLIENT_ID_BUILD` | `src/lib/oauth.ts` | Build-time embedded client ID; not user-configurable | |
| 119 | +| `SENTRY_OUTPUT_FORMAT` | `src/lib/env-registry.ts` | In registry ✓ but not in `self-hosted.md` env table — probably fine since it's a library API concern | |
| 120 | + |
| 121 | +**Verdict:** The env-registry is well-maintained. The above are internal/build-time variables that appropriately aren't user-documented. |
| 122 | + |
| 123 | +**However**, `docs/src/content/docs/configuration.md` does not exist as a committed file — |
| 124 | +it is gitignored and generated. This means the full environment variable reference is only |
| 125 | +accessible via the built doc site. Users reading the repo directly cannot find it. |
| 126 | + |
| 127 | +--- |
| 128 | + |
| 129 | +## H. Auth / Self-Hosted Gaps |
| 130 | + |
| 131 | +| Gap | Source | Doc location | Details | |
| 132 | +|-----|--------|--------------|---------| |
| 133 | +| Host trust model | `src/commands/auth/login.ts` — refuses untrusted hosts unless `--url` explicitly passed | `self-hosted.md` | Not explained; users may not understand why login fails without `--url` | |
| 134 | +| `auth login --force` flag | `src/commands/auth/login.ts` | `auth.md` fragment, `self-hosted.md` | Not documented in fragments | |
| 135 | +| `auth login --timeout` flag | `src/commands/auth/login.ts` (default 900s) | `auth.md` fragment | Not documented | |
| 136 | +| `SENTRY_CLIENT_ID_BUILD` fallback | `src/lib/oauth.ts` — committed default client ID for SaaS | Not documented | Intentionally internal; no gap | |
| 137 | +| OAuth scope `event:write` | `src/lib/oauth.ts` — in `OAUTH_SCOPES` | `DEVELOPMENT.md`, `self-hosted.md` | Both correctly show the scopes (generated) ✓ | |
| 138 | +| Token storage host scoping | `src/lib/db/auth.ts` — tokens bound to host origin | Not mentioned in docs | Defense-in-depth measure not documented; users switching instances may be confused | |
| 139 | +| `SENTRY_FORCE_ENV_TOKEN` | `src/lib/db/auth.ts` | `self-hosted.md` ✓, `DEVELOPMENT.md` ✓ | Covered | |
| 140 | +| `sentry auth refresh --force` | `src/commands/auth/refresh.ts` | `auth.md` | Fragment has no example for `--force` specifically, but the command is documented | |
| 141 | + |
| 142 | +--- |
| 143 | + |
| 144 | +## I. Plugin/Skills Gaps |
| 145 | + |
| 146 | +| Gap | Source | Doc location | Details | |
| 147 | +|-----|--------|--------------|---------| |
| 148 | +| `~/.agents/` install path | `src/lib/agent-skills.ts` — installs to `~/.agents/skills/sentry-cli/` | `agentic-usage.md` — mentions `~/.agents` | Covered ✓ | |
| 149 | +| `~/.claude/` install path | `src/lib/agent-skills.ts` — installs to `~/.claude/skills/sentry-cli/` | `agentic-usage.md` — mentions `~/.claude` | Covered ✓ | |
| 150 | +| Cursor IDE support | `plugins/README.md` — `.cursor/skills/sentry-cli/` | `agentic-usage.md` | Says "Cursor" reads from `~/.agents` but doesn't mention `.cursor/skills/` in repo | |
| 151 | +| Claude Code marketplace install | `plugins/README.md` — `claude plugin marketplace add getsentry/cli` | `agentic-usage.md` | Not mentioned; only `npx skills add` shown | |
| 152 | +| Plugin manifest version | `plugins/sentry-cli/.claude-plugin/plugin.json` — version "0.35.0" | Not documented | Internal detail; no gap | |
| 153 | +| `--no-agent-skills` flag | `src/commands/cli/setup.ts` | `agentic-usage.md` ✓ | Covered | |
| 154 | +| Skills embedded in binary | `src/lib/agent-skills.ts` — reads from generated `skill-content.ts` | `agentic-usage.md` — says "No network fetch needed" | Covered ✓ | |
| 155 | +| Skill refresh on upgrade | `src/commands/cli/upgrade.ts` → spawns `cli setup` | `agentic-usage.md` ✓ | Covered | |
| 156 | + |
| 157 | +--- |
| 158 | + |
| 159 | +## J. README / DEVELOPMENT.md Drift |
| 160 | + |
| 161 | +| Claim | File | Reality | Severity | |
| 162 | +|-------|------|---------|----------| |
| 163 | +| **"Bun v1.3+"** as dev prerequisite | `README.md` (generated section) | Build uses fossilize/Node SEA; runtime is Node.js ≥22.15; `packageManager` is pnpm. Bun is not a prerequisite. | **Critical** | |
| 164 | +| **"Bun installed"** as prerequisite | `DEVELOPMENT.md` line 5 | Same as above | **Critical** | |
| 165 | +| **"Building the native binary still requires Bun"** | `DEVELOPMENT.md` line 91 | Build uses `fossilize` (Node SEA), esbuild for bundling. No Bun dependency. | **Critical** | |
| 166 | +| **"Bun runtime (v1.3 or later)"** | `contributing.md` (generated) | Same as above | **Critical** | |
| 167 | +| `pnpm run dev` description | `AGENTS.md` | `package.json` script `dev` runs generate + tsx — correct ✓ | N/A | |
| 168 | +| `pnpm test` runs unit tests | `AGENTS.md` | `package.json`: `"test": "pnpm run test:unit"` — correct ✓ | N/A | |
| 169 | +| OAuth scopes | `DEVELOPMENT.md` (generated) | Matches `src/lib/oauth.ts` — correct ✓ | N/A | |
| 170 | +| License "FSL-1.1-Apache-2.0" | `README.md` | Matches `package.json` ✓ | N/A | |
| 171 | +| Node.js engine `>=22.15` | `package.json` | README library usage says "Node.js (≥22.15)" — correct ✓ | N/A | |
| 172 | +| `git clone https://github.com/getsentry/cli.git` | `README.md`, `contributing.md` | Matches `package.json` repository URL ✓ | N/A | |
| 173 | + |
| 174 | +--- |
| 175 | + |
| 176 | +## Top 5 Most Impactful Fixes (Prioritized) |
| 177 | + |
| 178 | +### 1. Fix Bun prerequisite in doc generator (Critical) |
| 179 | + |
| 180 | +**File:** `script/generate-docs-sections.ts` |
| 181 | + |
| 182 | +The `generateDevPrereq()` function hard-codes "Bun" as a prerequisite. The build |
| 183 | +pipeline uses fossilize (Node SEA) + esbuild. The runtime is Node.js. This affects |
| 184 | +`README.md`, `DEVELOPMENT.md`, and `contributing.md` via generated sections. |
| 185 | + |
| 186 | +**Fix:** Update `generateDevPrereq()` to reference Node.js ≥22.15 and pnpm instead |
| 187 | +of Bun. Update the non-generated parts of `DEVELOPMENT.md` that mention Bun. |
| 188 | + |
| 189 | +### 2. Add missing subcommand examples to fragments (High) |
| 190 | + |
| 191 | +**Files:** `docs/src/fragments/commands/dashboard.md`, `issue.md`, `cli.md` |
| 192 | + |
| 193 | +Three subcommands have zero documentation in fragments: |
| 194 | +- `sentry dashboard revisions` / `sentry dashboard restore` |
| 195 | +- `sentry issue events` |
| 196 | +- `sentry cli import` |
| 197 | + |
| 198 | +### 3. Document `auth login` flags in fragment (High) |
| 199 | + |
| 200 | +**File:** `docs/src/fragments/commands/auth.md` |
| 201 | + |
| 202 | +The `--url`, `--timeout`, and `--force` flags for `sentry auth login` are important |
| 203 | +for self-hosted users and automation but have no examples in the auth fragment. |
| 204 | + |
| 205 | +### 4. Document install script flags and env vars in getting-started (Medium) |
| 206 | + |
| 207 | +**File:** `docs/src/content/docs/getting-started.mdx` |
| 208 | + |
| 209 | +The install script accepts `--no-modify-path`, `--no-completions`, `--no-agent-skills`, |
| 210 | +and the env vars `SENTRY_INSTALL_DIR` and `SENTRY_INIT`. These are useful for CI/Docker |
| 211 | +but undocumented in getting-started. |
| 212 | + |
| 213 | +### 5. Add `@latest` / `@most_frequent` magic selectors to issue fragment (Medium) |
| 214 | + |
| 215 | +**File:** `docs/src/fragments/commands/issue.md` |
| 216 | + |
| 217 | +The issue route's `fullDescription` mentions `@latest` and `@most_frequent` selectors |
| 218 | +for `sentry issue view @latest`, but no fragment documents them with examples. |
0 commit comments