docs: fix auth token precedence, update stale architecture tree, and documentation audit report#783
Draft
cursor[bot] wants to merge 1 commit intomainfrom
Draft
docs: fix auth token precedence, update stale architecture tree, and documentation audit report#783cursor[bot] wants to merge 1 commit intomainfrom
cursor[bot] wants to merge 1 commit intomainfrom
Conversation
… tree - Fix SENTRY_AUTH_TOKEN description in env-registry.ts: stored OAuth token takes priority by default, not the env var (unless SENTRY_FORCE_ENV_TOKEN is set) - Fix auth fragment docs: token precedence order was inverted - Update AGENTS.md architecture tree: add missing command directories (dashboard, release, sourcemap, repo, init, schema) and update subcommand lists for auth, cli, event, issue, project - Update DEVELOPMENT.md env var table: add SENTRY_AUTH_TOKEN, SENTRY_FORCE_ENV_TOKEN, SENTRY_CLI_NO_TELEMETRY, SENTRY_LOG_LEVEL - Update agentic-usage.md: document automatic skill installation, expand supported agent list beyond Claude Code Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Contributor
Semver Impact of This PR🟢 Patch (bug fixes) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨
Bug Fixes 🐛
Documentation 📚
Internal Changes 🔧
🤖 This preview updates automatically when you update the PR. |
Contributor
|
Contributor
Codecov Results 📊✅ 138 passed | Total: 138 | Pass Rate: 100% | Execution Time: 0ms 📊 Comparison with Base Branch
✨ No test changes detected All tests are passing successfully. ✅ Patch coverage is 100.00%. Project has 1709 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
+ Coverage 95.52% 95.52% —%
==========================================
Files 262 262 —
Lines 38174 38173 -1
Branches 0 0 —
==========================================
+ Hits 36464 36464 —
- Misses 1710 1709 -1
- Partials 0 0 —Generated by Codecov Action |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR fixes several documentation inaccuracies found during a comprehensive audit of the repository's documentation against the actual implementation. It also includes a full gap report below.
Changes
1. Fix auth token precedence documentation (Critical)
The
SENTRY_AUTH_TOKENdescription inenv-registry.tsand the auth command fragment incorrectly stated that environment tokens take precedence over stored OAuth tokens. In reality (since PR #646), stored OAuth tokens take priority by default because they support automatic refresh. TheSENTRY_FORCE_ENV_TOKENenv var restores the old behavior.Files changed:
src/lib/env-registry.ts— FixedSENTRY_AUTH_TOKENdescriptiondocs/src/fragments/commands/auth.md— Corrected "Token Precedence" section2. Update stale AGENTS.md architecture tree
The
commands/tree inAGENTS.mdwas significantly outdated, missing 7 command directories and many subcommands.Added:
dashboard/,release/,sourcemap/,repo/,init.ts,schema.tsUpdated subcommand lists for:
auth/,cli/,event/,issue/,project/3. Update DEVELOPMENT.md environment variables table
Added 4 missing env vars:
SENTRY_AUTH_TOKEN,SENTRY_FORCE_ENV_TOKEN,SENTRY_CLI_NO_TELEMETRY,SENTRY_LOG_LEVEL.4. Expand agentic-usage.md
sentry cli setup~/.agentsconvention)--no-agent-skillsopt-out documentationFull Documentation Audit Report
A. Undocumented or Missing Commands/Subcommands
All implemented commands have corresponding documentation fragments in
docs/src/fragments/commands/. No command directories are missing fragments. The generated doc system + fragment system provides full coverage.However, the
AGENTS.mdarchitecture tree (now fixed in this PR) was missing:dashboard/(list, view, create, widget add/edit/delete)release/(list, view, create, finalize, delete, deploy, deploys, set-commits, propose-version)sourcemap/(inject, upload)repo/(list)init.ts,schema.tsB. Undocumented Flags
Most flags are auto-documented by the generated command docs system. However, several globally-injected flags deserve explicit documentation:
--freshbuildListCommand--log-levelbuildCommand(hidden)configuration.mdfragment--verbose/-vbuildCommand(hidden)configuration.mdfragment--json/--fieldsbuildCommand(whenoutputset)Notable undocumented flags:
sentry cli setup --install— Internal flag used by the installer, intentionally undocumentedsentry cli upgrade --offline— Not mentioned incli.mdfragmentsentry auth login --timeout— Not mentioned in auth fragment (default: 900s)sentry auth login --force— Not mentioned in auth fragmentsentry auth status --fresh— Not mentioned in auth fragmentsentry event list --full— Not mentioned in event fragmentsentry trace view --full— Not mentioned in trace fragmentsentry issue list --compact— Not mentioned in issue fragmentsentry release create --finalize— Mentioned in example but not in a flags tablesentry release set-commits --initial-depth— Not documentedsentry release set-commits --clear— Not documentedsentry release deploy --time— Not documentedsentry release deploy --url,--started,--finished— Not documentedC. Missing Usage Examples
All command fragments include bash examples. Coverage is good. Minor gaps:
sentry auth whoami— No standalone example in auth fragment (only briefly shown)sentry cli defaults— Examples exist in configuration fragment but not in cli fragmentsentry release deploys— No example in release fragmentsentry release propose-version— Only shown inline in another example, no standalone sectionD. Stale Descriptions
env-registry.tsSENTRY_AUTH_TOKENdocs/src/fragments/commands/auth.mdAGENTS.mdcommands treeDEVELOPMENT.mdenv vars tableE. Missing Route Mappings in Skill Generator
No gaps. The
ROUTE_TO_REFERENCEmap was replaced by automatic introspection ingenerate-skill.ts. All non-hidden routes automatically get reference files. Hidden routes (plural aliases likeissues,orgs,sourcemaps, pluswhoami) are intentionally excluded.F. Installation / Distribution Gaps
The install documentation in
getting-started.mdxandREADME.mdis accurate and comprehensive. Minor observations:--versionflag andSENTRY_VERSIONenv varSENTRY_INSTALL_DIRSENTRY_INIT=1--no-modify-path/--no-completionsinstaller flagsG. Undocumented Environment Variables
The
env-registry.tsis comprehensive and generatesconfiguration.md. All major env vars are registered. However,configuration.mdis gitignored (generated), sodocs/src/content/docs/configuration.mdwas reported as "not found" during this audit — it only exists after runningbun run generate:docs.All 21 env vars from
env-registry.tsare documented:SENTRY_AUTH_TOKEN,SENTRY_TOKEN,SENTRY_FORCE_ENV_TOKEN,SENTRY_ORG,SENTRY_PROJECT,SENTRY_DSN,SENTRY_HOST,SENTRY_URL,SENTRY_CLIENT_ID,SENTRY_CUSTOM_HEADERS,SENTRY_CONFIG_DIR,SENTRY_INSTALL_DIR,SENTRY_VERSION,SENTRY_INIT,SENTRY_PLAIN_OUTPUT,NO_COLOR,FORCE_COLOR,SENTRY_OUTPUT_FORMAT,SENTRY_LOG_LEVEL,SENTRY_CLI_NO_TELEMETRY,SENTRY_CLI_NO_UPDATE_CHECK,SENTRY_NO_CACHE,SENTRY_MAX_PAGINATION_PAGES,SENTRY_CLI_NO_AUTO_REPAIR.H. Auth / Self-Hosted Gaps
oauth.tsinto DEVELOPMENT.md and self-hosted.md~/.sentry/cli.db).sentryclircbackward compatibilityI. Plugin/Skills Gaps
sentry cli setupplugins/README.mdbut.cursor/skills/path doesn't exist in repo — README may be aspirational~/.agentsconvention--no-agent-skillsopt-outJ. README / DEVELOPMENT.md Drift
packageManager: bun@1.3.11in package.jsonbun testbun run test(runstest:unit && test:isolated)bun testworks tooengines.node: ">=22"in package.jsonSENTRY_AUTH_TOKENbuild requirementSENTRY_CLIENT_IDenv var(required)in env tablebun test --coveragetest:unituses--coverage --coverage-reporter=lcovTop 5 Most Impactful Fixes (Prioritized)
Auth token precedence inversion (Fixed) —
env-registry.tsand auth fragment told users env tokens win over stored OAuth, but the opposite is true since Wizard-generated SENTRY_AUTH_TOKEN blocks OAuth-based CLI login #646. This could cause confusion for CI/CD setups where users setSENTRY_AUTH_TOKENexpecting it to override an interactive login.AGENTS.md stale architecture tree (Fixed) — Missing 7+ command directories (
dashboard,release,sourcemap,repo,init,schema) means AI agents working on this codebase had an incomplete picture of the command surface.Agentic usage: missing automatic install docs (Fixed) — The primary installation path (automatic via
sentry cli setup) was undocumented, and supported agents were listed as only "Claude Code".Release command flags undocumented —
set-commits --initial-depth,--clear,deploy --time/--url/--started/--finished, andpropose-versiondetails are not in the fragment. This is the largest single area of missing flag documentation.Node.js >=22 not mentioned in getting-started for npm install — Users installing via
npm install -g sentrymay not realize they need Node.js 22+, which is a hard requirement due to thenode:sqlitepolyfill. This is only documented inlibrary-usage.md.