Distillation

Date: Sep 10, 2026

• 🔴 (09:08) User stated that commands must always be checked against the latest package.json scripts; commands run from packages/cli or from the repository root via pnpm --filter sentry run <script>.
• 🔴 (09:08) User stated that all packages must be declared in devDependencies, never dependencies, because everything is bundled at build time via esbuild; CI enforces this through pnpm run check:deps.
• 🔴 (09:08) User stated that adding a package must always use pnpm add -D <package> with the -D flag.
• 🔴 (09:08) User stated that formatting/rendering logic belongs in src/lib/formatters/<domain>.ts; command files exceeding approximately 400 lines should extract formatting helpers into a dedicated formatter module.
• 🔴 (09:08) User stated markdown-output conventions: use mdKvTable(), colorTag(), escapeMarkdownCell(), and renderMarkdown(); never use raw muted() or chalk in output strings, instead use colorTag("muted", text) within markdown; tree output that cannot use renderMarkdown() should use isPlainOutput() ? text : muted(text).
• 🔴 (09:08) User stated isPlainOutput() precedence is SENTRY_PLAIN_OUTPUT > NO_COLOR > FORCE_COLOR (TTY only) > !isTTY; it resides at src/lib/formatters/plain-detect.ts and is re-exported from markdown.ts for compatibility.
• 🔴 (09:08) User stated cursor-stack behavior: the DB stores a JSON array of opaque page-start cursors plus a page index; cursors may be plain API cursors, compound issue-list cursors, or dashboard-list extended cursors with mid-page bookmarks; -c next increments, -c prev decrements, -c first resets to 0, back-then-forward truncates stale entries, and "last" silently aliases "next".
• 🔴 (09:08) User stated never to pass per_page greater than API_MAX_PER_PAGE to the API, because the server silently caps oversized values and commands would return fewer items than requested.
• 🔴 (09:08) User stated timestamp sorting must use "date", not "time"; sort types should be exported by the API layer (for example, SpanSortValue from api/traces.ts) and imported by commands, matching issue list, trace list, and span list.
• 🔴 (09:08) User stated all config operations are asynchronous and must always be awaited.
• 🔴 (09:08) User stated local ESM imports must use .js extensions; imports must group external packages before local imports and use the type keyword for type-only imports.
• 🔴 (09:08) User stated different Sentry API endpoints use different project-filtering mechanisms and both mechanisms must never be applied simultaneously.
• 🔴 (09:08) User stated inline comments that merely restate code are prohibited.
• 🔴 (09:08) User stated property-test properties must always hold regardless of input; use fcAssert(property(...), { numRuns: DEFAULT_NUM_RUNS }).
• 🔴 (09:08) User stated unit tests alongside property tests should cover: edge cases beyond the property generator’s range (such as self-hosted DSNs when the arbitrary produces only SaaS DSNs); exact output-format documentation including strings, column layouts, and rendered versus plain mode; concurrency/timing behavior not expressible by property tests; and multi-function integration behavior such as writeJsonList envelope shape.
• 🟡 (09:08) packages/cli/src/lib/token-claims.ts defines parseSntrysClaim(token: string | undefined): SntrysClaim | undefined for sntrys_ org-auth tokens formatted as sntrys_<base64(JSON{iat, url, region_url, org})>_<random-secret>.
• 🟡 (09:08) packages/cli/src/lib/token-claims.ts defines SntrysClaim as { url: string; regionUrl?: string; org?: string }; region_url is returned as regionUrl, and org is an optional organization slug embedded when issued.
• 🟡 (09:08) parseSntrysClaim() behavior: rejects absent tokens, tokens longer than MAX_TOKEN_LENGTH = 2048, non-sntrys_ tokens, tokens not containing exactly 2 underscores, empty payloads, invalid base64/JSON payloads, non-object payloads, payloads without truthy iat, and payloads without a nonempty string url; it returns optional nonempty-string region_url and org values through optionalString().
• 🟡 (09:08) packages/cli/src/lib/token-claims.ts documents that sntrys_ claims are unsigned and forgeable; the accepted threat-model rationale is that an attacker able to provide a forged token has already compromised the credential. For legitimate tokens, the server-issued claim is treated as authoritative and resistant to environment-variable injection; captureEnvTokenHost uses the claim as its primary source ahead of environment variables.
• 🟡 (09:08) packages/cli/src/lib/sentry-client.ts imports parseSntrysClaim from ./token-claims.js and applies a defense-in-depth sntrys_ host check in prepareHeaders(): it reads parseSntrysClaim(token)?.url and, if present, throws HostScopeError("Credentials", normalizeOrigin(input) ?? "<unknown host>", claimUrl) when isHostTrustedForClaim(input, claimUrl) is false; malformed claims fail open, while valid claims permit control-silo multi-region fan-out via region URLs.
• 🟡 (09:08) prepareHeaders() in packages/cli/src/lib/sentry-client.ts also enforces isRequestOriginTrusted(input) before credential injection, throwing HostScopeError with getActiveTokenHost() for an untrusted request origin; this is defense in depth beyond URL-argument and rc-shim entry-point guards.
• 🟡 (09:08) prepareHeaders(input, init, token) preserves SDK-provided headers when the SDK invokes fetch(request) without init: it uses init?.headers ?? (input instanceof Request ? input.headers : undefined) before creating new Headers(sourceHeaders), preventing Node.js fetch(request, {headers}) behavior from stripping existing Content-Type and causing HTTP 415 responses.
• 🟡 (09:08) prepareHeaders() sets Authorization: Bearer ${token}, sets User-Agent only when absent using getUserAgent(), injects sentry-trace and baggage from getTraceData() when telemetry supplies them, and scopes self-hosted proxy custom headers through applyCustomHeaders(headers, input).
• 🟡 (09:08) packages/cli/src/lib/sentry-client.ts request configuration values include REQUEST_TIMEOUT_MS = 30_000, an /\/autofix\/?(?:\?|$)/ endpoint override of 120_000 ms for Seer autofix POSTs, MAX_RETRIES = 2, MAX_BACKOFF_MS = 10_000, retryable HTTP statuses [408, 429, 500, 502, 503, 504], and retry marker header "x-sentry-cli-retry".
• 🟡 (09:08) backoffDelay(attempt) in packages/cli/src/lib/sentry-client.ts calculates Math.min(1000 * 2 ** attempt, MAX_BACKOFF_MS).