Distillation

Date: Sep 10, 2026

• 🔴 (09:08) User stated that package.json must always be checked for the latest scripts; commands run from packages/cli or from repo root via pnpm --filter sentry run <script>.
• 🔴 (09:08) User stated all packages must be in devDependencies, never dependencies, because everything is bundled at build time via esbuild; CI enforces this with pnpm run check:deps.
• 🔴 (09:08) User stated packages must always be added with pnpm add -D <package> using the -D flag.
• 🔴 (09:08) User stated the generated live command/subcommand and domain-API project structure is maintained in apps/cli-docs/src/content/docs/contributing.md in the project-structure block generated by script/generate-docs-sections.ts; it must not be duplicated to avoid drift. Current commands can be checked with ls src/commands/ or sentry --help.
• 🔴 (09:08) User stated command implementation rules: functions use async *func() generators, yield new CommandOutput(data), and return { hint }; output.human must receive the same data serialized to JSON; command wrappers inject --json and --fields, so commands must not add their own json flag, call stdout.write(), or branch on if (flags.json).
• 🔴 (09:08) User stated create commands must import DRY_RUN_FLAG and DRY_RUN_ALIASES for consistent dry-run support.
• 🔴 (09:08) User stated paginated commands should use buildPaginationContextKey(), resolveCursor(), advancePaginationState(), hasPreviousPage(), and nextCursor/hasMore state as shown for entity/org/project context.
• 🔴 (09:08) User stated never to pass a per_page value larger than API_MAX_PER_PAGE to the API because the server silently caps it and commands would return fewer requested items.
• 🔴 (09:08) User stated all CLI errors extend the CliError base class in src/lib/errors.ts.
• 🔴 (09:08) User stated that when a user-provided name or title matches no entity, commands must use fuzzyMatch() from src/lib/fuzzy.ts and show at most 5 similar candidates rather than listing all entities.
• 🔴 (09:08) User stated existing shared modules must be checked before creating a new src/lib/*.ts utility file.
• 🔴 (09:08) User stated src/lib/list-command.ts provides the buildOrgListCommand factory and shared Stricli constants LIST_TARGET_POSITIONAL, LIST_JSON_FLAG, LIST_CURSOR_FLAG, and buildListLimitFlag; it should be used for simple entity lists such as team list and repo list.
• 🔴 (09:08) User stated the default commenting rule is to prefer JSDoc over inline comments; code should be readable without comments narrating obvious behavior.
• 🔴 (09:08) User stated property-based and model-based testing are preferred over traditional unit tests because they automatically find edge cases and provide better coverage with less code.
• 🔴 (09:08) User stated property tests must express invariants that always hold regardless of input, using fcAssert, property, and { numRuns: DEFAULT_NUM_RUNS } where applicable.
• 🔴 (09:08) User stated good candidates for property-based testing are parsing functions such as DSN, issue-ID, and alias parsing; encoding/decoding round trips; symmetric operations; idempotent operations; and validation functions accepting valid inputs and rejecting invalid inputs.
• 🔴 (09:08) User stated model-based/property-testing examples are test/lib/db/model-based.test.ts and test/lib/db/dsn-cache.model-based.test.ts.
• 🔴 (09:08) User stated that if a module has a *.property.test.ts file, unit tests must not re-check the same invariants with hardcoded examples; the companion property test must be checked first.
• 🔴 (09:08) User stated repository placement conventions: commands in src/commands/<domain>/; Sentry 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/; model-test helpers in test/model-based/helpers.ts; documentation in docs/src/content/docs/; and hand-written command docs in docs/src/fragments/commands/.
• 🟡 (09:08) Search results identified credential-host-scoping code in packages/cli/src/lib/token-host.ts, including isHostTrusted() at line 31 and isHostTrustedForClaim() at line 140; token claim parsing in packages/cli/src/lib/token-claims.ts via parseSntrysClaim() at line 43; and getConfiguredSentryUrl() in packages/cli/src/lib/constants.ts, which derives a normalized URL from an sntrys_ claim in SENTRY_AUTH_TOKEN or SENTRY_TOKEN.
• 🟡 (09:08) Search results identified auth environment-token precedence in packages/cli/src/lib/db/auth.ts: SENTRY_AUTH_TOKEN takes priority over SENTRY_TOKEN, matching legacy sentry-cli behavior.