feat(auth): add --scope/-s and --read-only flags to login and refresh

[RaeesBhatti]

Summary

Adds explicit OAuth scope selection to auth login and auth refresh,
following gh CLI conventions. Also adds scope-aware 403 error recovery.

Fixes #1031.

Motivation

• AI agents: a growing use case is letting an AI agent read Sentry
  issues for debugging context. A read-only OAuth path means "let the
  agent investigate" doesn't also mean "let the agent accidentally
  change production state."
• Principle of least privilege: CI jobs and local dev sessions that
  only read shouldn't hold tokens that can also write or delete.
• gh parity: gh auth login / gh auth refresh support
  --scopes/-s for explicit scope selection and interactive 403
  recovery. This PR brings the same ergonomics to the Sentry CLI.

Features

auth login --scope/-s and --read-only

# Read-only OAuth token (sugar for the :read subset)
sentry auth login --read-only

# Explicit scope selection (repeatable, comma-separated)
sentry auth login --scope project:read --scope org:read
sentry auth login -s project:read,org:read

# Full default scopes (unchanged behavior)
sentry auth login

Scopes are validated against the canonical SENTRY_SCOPES set from
getsentry/sentry. Conflict guards reject --token + scope flags and
--read-only + --scope.

auth refresh --scope/-s and --read-only

Like gh auth refresh -s <scope> — re-runs the OAuth device flow with
the requested scopes, bypassing the "already authenticated" gate:

sentry auth refresh --scope event:read --scope org:read
sentry auth refresh --read-only

Scope-aware 403 error hints

When the API returns 403 with specific missing scopes, the error now
suggests the exact fix command:

Your token is missing the required scope(s) 'event:read'.
Re-authenticate with: sentry auth refresh --scope event:read

Interactive 403 scope recovery (TTY only)

In interactive terminals, catches 403 missing-scope errors for OAuth
tokens and prompts:

Missing scope(s): 'event:read'. Re-authenticate with default scopes? (Y/n)

On confirmation, re-authenticates via the device flow (merging missing
scopes with the default set) and retries the command automatically.

Implementation

• src/lib/oauth.ts — resolveOAuthScopeString() resolver;
  requestDeviceCode(scope) and performDeviceFlow(..., scope) take a
  resolved scope string (not a boolean)
• src/lib/api-scope.ts — export canonical SENTRY_SCOPES for validation
• src/lib/api/infrastructure.ts — scope-aware 403 enrichment hints
• src/cli.ts — scopeRecoveryMiddleware for interactive 403 auto-fix
• src/commands/auth/login.ts — --read-only + --scope/-s flags
• src/commands/auth/refresh.ts — --read-only + --scope/-s flags

Test plan

• 110+ tests pass across 6 test files
• Property-based tests for resolveOAuthScopeString (fast-check)
• Unit tests for flag conflict guards, scope forwarding, and 403 enrichment
• All existing auth tests continue to pass

Credits

Based on the initial --read-only implementation by @RaeesBhatti in the
original PR. Extended with --scope/-s, auth refresh support,
scope-aware 403 hints, and interactive recovery middleware.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 98bc598. Configure here.}

[BYK]

Thanks for the initial implementation @RaeesBhatti! Your PR was the foundation for the scope selection feature. We expanded it to include explicit --scope/-s flags (following gh conventions), added scope support to auth refresh, and wired up interactive 403 recovery. Appreciate you kicking this off!