Distillation

Date: Sep 10, 2026

• 🔴 (12:01) User stated apiRequestToRegion always sends JSON and explicitly sets the JSON content type.
• 🔴 (12:01) User stated route groups use Stricli’s buildRouteMap, wrapped by src/lib/route-map.ts.
• 🔴 (12:01) User stated create commands must import DRY_RUN_FLAG and DRY_RUN_ALIASES for consistent dry-run support.
• 🔴 (12:01) User stated cursor pagination uses a stack model: the DB stores a JSON array of opaque page-start cursors plus a page index; entries may be plain API cursors, compound issue-list cursors, or extended dashboard-list cursors with mid-page bookmarks. -c next increments the index, -c prev decrements it, -c first resets it to 0, "last" silently aliases "next", and moving back then forward truncates the stack to prevent stale entries.
• 🔴 (12:01) User stated list commands where --limit exceeds API_MAX_PER_PAGE (100) must transparently fetch multiple pages until results.length >= limit or pages are exhausted; perPage must be capped at Math.min(flags.limit, API_MAX_PER_PAGE), following the listIssuesAllPages pattern.
• 🔴 (12:01) User stated Zod schemas should be defined alongside types in src/types/*.ts, re-exported through src/types/index.ts, and consumed with type-only imports such as import type { MyType } from "../types/index.js". Key files are src/types/sentry.ts for API types, src/types/config.ts for configuration, src/types/oauth.ts for authentication flow, and src/types/seer.ts for Seer AI.
• 🔴 (12:01) User stated CLI exit-code ranges are 1x for authentication, 2x for input/configuration, 3x for API/network, 4x for feature/billing, 5x for operations, and 6x for command-specific errors; the complete definitions are in EXIT in src/lib/errors.ts and at https://cli.sentry.dev/exit-codes/.
• 🔴 (12:01) User stated silent catch blocks are prohibited in src/ production code. This includes syntactically empty catch {} blocks detected by Biome’s noEmptyBlockStatements and blocks containing only return without logging, because those silently discard errors.
• 🔴 (12:01) User stated identifier-detection helpers are: looksLikeIssueShortId(value) for uppercase dash-separated issue IDs such as CLI-G5; SPAN_ID_RE.test(value) for 16-character hexadecimal span IDs; HEX_ID_RE.test(value) for 32-character hexadecimal trace/event/log IDs; and /[^0-9a-f]/.test(normalized) to identify values containing non-hexadecimal characters and therefore likely representing a slug/name.
• 🔴 (12:01) User stated every new src/lib/**/*.ts file must begin with a module-level JSDoc comment describing the module’s purpose.
• 🔴 (12:01) User stated property-based test properties should always hold regardless of input. The example uses Vitest and fast-check imports describe, expect, test, constantFrom, assert as fcAssert, property, and tuple, with { numRuns: DEFAULT_NUM_RUNS } imported from ../model-based/helpers.js.
• 🔴 (12:01) User stated model-based database tests should use AsyncCommand<DbModel, RealDb>, createIsolatedDbContext(), asyncModelRun, and cleanup in a finally block; randomized command sequences run with { numRuns: DEFAULT_NUM_RUNS }.
• 🔴 (12:01) User specified the project placement map: new commands go in src/commands/<domain>/; API types in src/types/sentry.ts; configuration 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 the src/ structure; E2E tests in test/e2e/; test helpers in test/model-based/helpers.ts; documentation in docs/src/content/docs/; and hand-written command documentation fragments in docs/src/fragments/commands/.