Distillation

Date: Sep 10, 2026

• 🔴 (09:33) User directed to always check package.json for the latest scripts; commands run from packages/cli or from repo root via pnpm --filter sentry run <script>.
• 🔴 (09:33) User specified all packages must be placed in devDependencies, never dependencies, because everything is bundled at build time via esbuild; CI enforces this through pnpm run check:deps.
• 🔴 (09:33) User directed that adding a package must always use pnpm add -D <package>.
• 🔴 (09:33) User specified to import buildRouteMap from ../../lib/route-map.js, never directly from @stricli/core, because the wrapper auto-injects standard subcommand aliases according to existing route keys.
• 🔴 (09:33) User specified manual pagination for buildListCommand commands such as trace/span/dashboard list must directly call resolveCursor, advancePaginationState, hasPreviousPage, and paginationHint.
• 🔴 (09:33) User directed never to pass an API per_page value larger than API_MAX_PER_PAGE; the server silently caps larger values and commands would return fewer items than requested.
• 🔴 (09:33) User specified timestamp-based sort must use "date", not "time"; sort types should be exported from the API layer (for example, SpanSortValue from api/traces.ts) and imported into commands, matching issue list, trace list, and span list.
• 🔴 (09:33) User specified unmatched user-provided entity names/titles must use fuzzyMatch() from src/lib/fuzzy.ts to suggest similar candidates rather than listing all entities; show at most 5 fuzzy matches.
• 🔴 (09:33) User prefers JSDoc over inline comments; code should be readable without narrating what it already says.
• 🔴 (09:33) User specified property-test invariants must always hold regardless of input; property tests use fcAssert(property(...), { numRuns: DEFAULT_NUM_RUNS }).
• 🔴 (09:33) User directed that when a module has a *.property.test.ts companion file, unit tests must not re-check the same invariants with hardcoded examples; check the property file before adding unit tests.
• 🟡 (09:33) Project test-environment guidance: Vitest runs each test file in a worker-pool worker process (test:unit in package.json), bounding most cross-file leakage to one worker; within a file, process.env remains shared, so deleting an env var in afterEach can cause later module-level code or beforeEach rereads to receive undefined and throw TypeError: The "paths[0]" property must be of type string. TEST_TMP_DIR is namespaced by VITEST_POOL_ID in test/constants.ts to prevent parallel workers from wiping one another’s preload temp state.
• 🟡 (09:33) Project placement conventions: new commands in src/commands/<domain>/; API types in src/types/sentry.ts; config types in src/types/config.ts; Seer types in src/types/seer.ts; utilities in src/lib/; DSN-language support in src/lib/dsn/languages/; DB operations in src/lib/db/; build scripts in script/; property tests in test/lib/<name>.property.test.ts; model-based tests in test/lib/db/<name>.model-based.test.ts; unit tests in test/ mirroring src/; E2E tests in test/e2e/; test helpers in test/model-based/helpers.ts; documentation in docs/src/content/docs/; hand-written command documentation in docs/src/fragments/commands/.
• 🟡 (09:33) packages/cli/src/lib/token-claims.ts defines parseSntrysClaim(token: string | undefined): SntrysClaim | undefined for Sentry org-auth tokens formatted as sntrys_<base64(JSON{iat, url, region_url, org})>_<random-secret>.
• 🟡 (09:33) parseSntrysClaim() accepts only nonempty sntrys_ tokens of at most MAX_TOKEN_LENGTH = 2048, with exactly 2 underscores; it base64-decodes and JSON-parses the payload, requires truthy iat and nonempty string url, and returns { url, regionUrl, org }, with regionUrl derived from region_url and optional org accepted only when nonempty strings.
• 🟡 (09:33) packages/cli/src/lib/token-claims.ts documents that sntrys_ claims are unsigned and forgeable, but legitimate token claims are authoritative and immune to SENTRY_HOST environment-injection attacks; captureEnvTokenHost uses the claim as the primary trust source for sntrys_ tokens ahead of environment variables. Forged-token risk is accepted because supplying a forged token already compromises the credential and is out of the threat model.