Skip to content

AGENTS.md

Latest commit

 

History

History
843 lines (662 loc) · 42.1 KB

AGENTS.md

File metadata and controls

843 lines (662 loc) · 42.1 KB

AGENTS.md

Guidelines for AI agents working in this codebase.

Project Overview

Sentry CLI is a command-line interface for Sentry, built with Bun and Stricli.

Goals

  • Zero-config experience - Auto-detect project context from DSNs in source code and env files
  • AI-powered debugging - Integrate Seer AI for root cause analysis and fix plans
  • Developer-friendly - Follow gh CLI conventions for intuitive UX
  • Agent-friendly - JSON output and predictable behavior for AI coding agents
  • Fast - Native binaries via Bun, SQLite caching for API responses

Key Features

  • DSN Auto-Detection - Scans .env files and source code (JS, Python, Go, Java, Ruby, PHP) to find Sentry DSNs
  • Project Root Detection - Walks up from CWD to find project boundaries using VCS, language, and build markers
  • Directory Name Inference - Fallback project matching using bidirectional word boundary matching
  • Multi-Region Support - Automatic region detection with fan-out to regional APIs (us.sentry.io, de.sentry.io)
  • Monorepo Support - Generates short aliases for multiple projects
  • Seer AI Integration - issue explain and issue plan commands for AI analysis
  • OAuth Device Flow - Secure authentication without browser redirects

Cursor Rules (Important!)

Before working on this codebase, read the Cursor rules:

  • .cursor/rules/bun-cli.mdc - Bun API usage, file I/O, process spawning, testing
  • .cursor/rules/ultracite.mdc - Code style, formatting, linting rules

Quick Reference: Commands

Note: Always check package.json for the latest scripts.

# Development
bun install                              # Install dependencies
bun run dev                              # Run CLI in dev mode
bun run --env-file=.env.local src/bin.ts # Dev with env vars

# Build
bun run build                            # Build for current platform
bun run build:all                        # Build for all platforms

# Type Checking
bun run typecheck                        # Check types

# Linting & Formatting
bun run lint                             # Check for issues
bun run lint:fix                         # Auto-fix issues (run before committing)

# Testing
bun test                                 # Run all tests
bun test path/to/file.test.ts            # Run single test file
bun test --watch                         # Watch mode
bun test --filter "test name"            # Run tests matching pattern
bun run test:unit                        # Run unit tests only
bun run test:e2e                         # Run e2e tests only

Rules: Use Bun APIs

CRITICAL: This project uses Bun as runtime. Always prefer Bun-native APIs over Node.js equivalents.

Read the full guidelines in .cursor/rules/bun-cli.mdc.

Bun Documentation: https://bun.sh/docs - Consult these docs when unsure about Bun APIs.

Quick Bun API Reference

Task Use This NOT This
Read file await Bun.file(path).text() fs.readFileSync()
Write file await Bun.write(path, content) fs.writeFileSync()
Check file exists await Bun.file(path).exists() fs.existsSync()
Spawn process Bun.spawn() child_process.spawn()
Shell commands Bun.$\command`` ⚠️ child_process.exec()
Find executable Bun.which("git") which package
Glob patterns new Bun.Glob() glob / fast-glob packages
Sleep await Bun.sleep(ms) setTimeout with Promise
Parse JSON file await Bun.file(path).json() Read + JSON.parse

Exception: Use node:fs for directory creation with permissions:

import { mkdirSync } from "node:fs";
mkdirSync(dir, { recursive: true, mode: 0o700 });

Exception: Bun.$ (shell tagged template) has no shim in script/node-polyfills.ts and will crash on the npm/node distribution. Until a shim is added, use execSync from node:child_process for shell commands that must work in both runtimes:

import { execSync } from "node:child_process";
const result = execSync("id -u username", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] });

Architecture

cli/
├── src/
│   ├── bin.ts              # Entry point
│   ├── app.ts              # Stricli application setup
│   ├── context.ts          # Dependency injection context
│   ├── commands/           # CLI commands
│   │   ├── auth/           # login, logout, status, refresh
│   │   ├── event/          # view
│   │   ├── issue/          # list, view, explain, plan
│   │   ├── org/            # list, view
│   │   ├── project/        # list, view
│   │   ├── span/           # list, view
│   │   ├── trace/          # list, view, logs
│   │   ├── log/            # list, view
│   │   ├── trial/          # list, start
│   │   ├── cli/            # fix, upgrade, feedback, setup
│   │   ├── api.ts          # Direct API access command
│   │   └── help.ts         # Help command
│   ├── lib/                # Shared utilities
│   │   ├── command.ts      # buildCommand wrapper (telemetry + output)
│   │   ├── api-client.ts   # Barrel re-export for API modules
│   │   ├── api/            # Domain API modules
│   │   │   ├── infrastructure.ts # Shared helpers, types, raw requests
│   │   │   ├── organizations.ts
│   │   │   ├── projects.ts
│   │   │   ├── issues.ts
│   │   │   ├── events.ts
│   │   │   ├── traces.ts      # Trace + span listing
│   │   │   ├── logs.ts
│   │   │   ├── seer.ts
│   │   │   └── trials.ts
│   │   ├── region.ts       # Multi-region resolution
│   │   ├── telemetry.ts    # Sentry SDK instrumentation
│   │   ├── sentry-urls.ts  # URL builders for Sentry
│   │   ├── hex-id.ts       # Hex ID validation (32-char + 16-char span)
│   │   ├── trace-id.ts     # Trace ID validation wrapper
│   │   ├── db/             # SQLite database layer
│   │   │   ├── instance.ts     # Database singleton
│   │   │   ├── schema.ts       # Table definitions
│   │   │   ├── migration.ts    # Schema migrations
│   │   │   ├── utils.ts        # SQL helpers (upsert)
│   │   │   ├── auth.ts         # Token storage
│   │   │   ├── user.ts         # User info cache
│   │   │   ├── regions.ts      # Org→region URL cache
│   │   │   ├── defaults.ts     # Default org/project
│   │   │   ├── pagination.ts   # Cursor pagination storage
│   │   │   ├── dsn-cache.ts    # DSN resolution cache
│   │   │   ├── project-cache.ts    # Project data cache
│   │   │   ├── project-root-cache.ts # Project root cache
│   │   │   ├── project-aliases.ts  # Monorepo alias mappings
│   │   │   └── version-check.ts    # Version check cache
│   │   ├── dsn/            # DSN detection system
│   │   │   ├── detector.ts     # High-level detection API
│   │   │   ├── scanner.ts      # File scanning logic
│   │   │   ├── code-scanner.ts # Code file DSN extraction
│   │   │   ├── project-root.ts # Project root detection
│   │   │   ├── parser.ts       # DSN parsing utilities
│   │   │   ├── resolver.ts     # DSN to org/project resolution
│   │   │   ├── fs-utils.ts     # File system helpers
│   │   │   ├── env.ts          # Environment variable detection
│   │   │   ├── env-file.ts     # .env file parsing
│   │   │   ├── errors.ts       # DSN-specific errors
│   │   │   ├── types.ts        # Type definitions
│   │   │   └── languages/      # Per-language DSN extractors
│   │   │       ├── javascript.ts
│   │   │       ├── python.ts
│   │   │       ├── go.ts
│   │   │       ├── java.ts
│   │   │       ├── ruby.ts
│   │   │       └── php.ts
│   │   ├── formatters/     # Output formatting
│   │   │   ├── human.ts    # Human-readable output
│   │   │   ├── json.ts     # JSON output
│   │   │   ├── output.ts   # Output utilities
│   │   │   ├── seer.ts     # Seer AI response formatting
│   │   │   ├── colors.ts   # Terminal colors
│   │   │   ├── markdown.ts # Markdown → ANSI renderer
│   │   │   ├── trace.ts    # Trace/span formatters
│   │   │   ├── time-utils.ts # Shared time/duration utils
│   │   │   ├── table.ts    # Table rendering
│   │   │   └── log.ts      # Log entry formatting
│   │   ├── oauth.ts            # OAuth device flow
│   │   ├── errors.ts           # Error classes
│   │   ├── resolve-target.ts   # Org/project resolution
│   │   ├── resolve-issue.ts    # Issue ID resolution
│   │   ├── issue-id.ts         # Issue ID parsing utilities
│   │   ├── arg-parsing.ts      # Argument parsing helpers
│   │   ├── alias.ts            # Alias generation
│   │   ├── promises.ts         # Promise utilities
│   │   ├── polling.ts          # Polling utilities
│   │   ├── upgrade.ts          # CLI upgrade functionality
│   │   ├── version-check.ts    # Version checking
│   │   ├── browser.ts          # Open URLs in browser
│   │   ├── clipboard.ts        # Clipboard access
│   │   └── qrcode.ts           # QR code generation
│   └── types/              # TypeScript types and Zod schemas
│       ├── sentry.ts       # Sentry API types
│       ├── config.ts       # Configuration types
│       ├── oauth.ts        # OAuth types
│       └── seer.ts         # Seer AI types
├── test/                   # Test files (mirrors src/ structure)
│   ├── lib/                # Unit tests for lib/
│   │   ├── *.test.ts           # Standard unit tests
│   │   ├── *.property.test.ts  # Property-based tests
│   │   └── db/
│   │       ├── *.test.ts           # DB unit tests
│   │       └── *.model-based.test.ts # Model-based tests
│   ├── model-based/        # Model-based testing helpers
│   │   └── helpers.ts      # Isolated DB context, constants
│   ├── commands/           # Unit tests for commands/
│   ├── e2e/                # End-to-end tests
│   ├── fixtures/           # Test fixtures
│   └── mocks/              # Test mocks
├── docs/                   # Documentation site (Astro + Starlight)
├── script/                 # Build and utility scripts
├── .cursor/rules/          # Cursor AI rules (read these!)
└── biome.jsonc             # Linting config (extends ultracite)

Key Patterns

CLI Commands (Stricli)

Commands use Stricli wrapped by src/lib/command.ts.

CRITICAL: Import buildCommand from ../../lib/command.js, NEVER from @stricli/core directly — the wrapper adds telemetry, --json/--fields injection, and output rendering.

Pattern:

import { buildCommand } from "../../lib/command.js";
import type { SentryContext } from "../../context.js";
import { CommandOutput } from "../../lib/formatters/output.js";

export const myCommand = buildCommand({
  docs: {
    brief: "Short description",
    fullDescription: "Detailed description",
  },
  output: {
    human: formatMyData,                // (data: T) => string
    jsonTransform: jsonTransformMyData, // optional: (data: T, fields?) => unknown
    jsonExclude: ["humanOnlyField"],    // optional: strip keys from JSON
  },
  parameters: {
    flags: {
      limit: { kind: "parsed", parse: Number, brief: "Max items", default: 10 },
    },
  },
  async *func(this: SentryContext, flags) {
    const data = await fetchData();
    yield new CommandOutput(data);
    return { hint: "Tip: use --json for machine-readable output" };
  },
});

Key rules:

  • Functions are async *func() generators — yield new CommandOutput(data), return { hint }.
  • output.human receives the same data object that gets serialized to JSON — no divergent-data paths.
  • The wrapper auto-injects --json and --fields flags. Do NOT add your own json flag.
  • Do NOT use stdout.write() or if (flags.json) branching — the wrapper handles it.

Positional Arguments

Use parseSlashSeparatedArg from src/lib/arg-parsing.ts for the standard [<org>/<project>/]<id> pattern. Required identifiers (trace IDs, span IDs) should be positional args, not flags.

import { parseSlashSeparatedArg, parseOrgProjectArg } from "../../lib/arg-parsing.js";

// "my-org/my-project/abc123" → { id: "abc123", targetArg: "my-org/my-project" }
const { id, targetArg } = parseSlashSeparatedArg(first, "Trace ID", USAGE_HINT);
const parsed = parseOrgProjectArg(targetArg);
// parsed.type: "auto-detect" | "explicit" | "project-search" | "org-all"

Reference: span/list.ts, trace/view.ts, event/view.ts

Markdown Rendering

All non-trivial human output must use the markdown rendering pipeline:

  • Build markdown strings with helpers: mdKvTable(), colorTag(), escapeMarkdownCell(), renderMarkdown()
  • NEVER use raw muted() / chalk in output strings — use colorTag("muted", text) inside markdown
  • Tree-structured output (box-drawing characters) that can't go through renderMarkdown() should use the plainSafeMuted pattern: isPlainOutput() ? text : muted(text)
  • isPlainOutput() precedence: SENTRY_PLAIN_OUTPUT > NO_COLOR > FORCE_COLOR (TTY only) > !isTTY
  • isPlainOutput() lives in src/lib/formatters/plain-detect.ts (re-exported from markdown.ts for compat)

Reference: formatters/trace.ts (formatAncestorChain), formatters/human.ts (plainSafeMuted)

List Command Pagination

All list commands with API pagination MUST use the shared cursor infrastructure:

import { LIST_CURSOR_FLAG } from "../../lib/list-command.js";
import {
  buildPaginationContextKey, resolveOrgCursor,
  setPaginationCursor, clearPaginationCursor,
} from "../../lib/db/pagination.js";

export const PAGINATION_KEY = "my-entity-list";

// In buildCommand:
flags: { cursor: LIST_CURSOR_FLAG },
aliases: { c: "cursor" },

// In func():
const contextKey = buildPaginationContextKey("entity", `${org}/${project}`, {
  sort: flags.sort, q: flags.query,
});
const cursor = resolveOrgCursor(flags.cursor, PAGINATION_KEY, contextKey);
const { data, nextCursor } = await listEntities(org, project, { cursor, ... });
if (nextCursor) setPaginationCursor(PAGINATION_KEY, contextKey, nextCursor);
else clearPaginationCursor(PAGINATION_KEY, contextKey);

Show -c last in the hint footer when more pages are available. Include nextCursor in the JSON envelope.

Reference template: trace/list.ts, span/list.ts

ID Validation

Use shared validators from src/lib/hex-id.ts:

  • validateHexId(value, label) — 32-char hex IDs (trace IDs, log IDs). Auto-strips UUID dashes.
  • validateSpanId(value) — 16-char hex span IDs. Auto-strips dashes.
  • validateTraceId(value) — thin wrapper around validateHexId in src/lib/trace-id.ts.

All normalize to lowercase. Throw ValidationError on invalid input.

Sort Convention

Use "date" for timestamp-based sort (not "time"). Export sort types from the API layer (e.g., SpanSortValue from api/traces.ts), import in commands. This matches issue list, trace list, and span list.

SKILL.md

  • Run bun run generate:skill after changing any command parameters, flags, or docs.
  • CI check bun run check:skill will fail if SKILL.md is stale.
  • Positional placeholder values must be descriptive: "org/project/trace-id" not "args".

Zod Schemas for Validation

All config and API types use Zod schemas:

import { z } from "zod";

export const MySchema = z.object({
  field: z.string(),
  optional: z.number().optional(),
});

export type MyType = z.infer<typeof MySchema>;

// Validate data
const result = MySchema.safeParse(data);
if (result.success) {
  // result.data is typed
}

Type Organization

  • Define Zod schemas alongside types in src/types/*.ts
  • Key type files: sentry.ts (API types), config.ts (configuration), oauth.ts (auth flow), seer.ts (Seer AI)
  • Re-export from src/types/index.ts
  • Use type imports: import type { MyType } from "../types/index.js"

SQL Utilities

Use the upsert() helper from src/lib/db/utils.ts to reduce SQL boilerplate:

import { upsert, runUpsert } from "../db/utils.js";

// Generate UPSERT statement
const { sql, values } = upsert("table", { id: 1, name: "foo" }, ["id"]);
db.query(sql).run(...values);

// Or use convenience wrapper
runUpsert(db, "table", { id: 1, name: "foo" }, ["id"]);

// Exclude columns from update
const { sql, values } = upsert(
  "users",
  { id: 1, name: "Bob", created_at: now },
  ["id"],
  { excludeFromUpdate: ["created_at"] }
);

Error Handling

All CLI errors extend the CliError base class from src/lib/errors.ts:

// Error hierarchy in src/lib/errors.ts
CliError (base)
├── ApiError (HTTP/API failures - status, detail, endpoint)
├── AuthError (authentication - reason: 'not_authenticated' | 'expired' | 'invalid')
├── ConfigError (configuration - suggestion?)
├── ContextError (missing context - resource, command, alternatives)
├── ResolutionError (value provided but not found - resource, headline, hint, suggestions)
├── ValidationError (input validation - field?)
├── DeviceFlowError (OAuth flow - code)
├── SeerError (Seer AI - reason: 'not_enabled' | 'no_budget' | 'ai_disabled')
└── UpgradeError (upgrade - reason: 'unknown_method' | 'network_error' | 'execution_failed' | 'version_not_found')

Choosing between ContextError, ResolutionError, and ValidationError:

Scenario Error Class Example
User omitted a required value ContextError No org/project provided
User provided a value that wasn't found ResolutionError Project 'cli' not found
User input is malformed ValidationError Invalid hex ID format

ContextError rules:

  • command must be a single-line CLI usage example (e.g., "sentry org view <slug>")
  • Constructor throws if command contains \n (catches misuse in tests)
  • Pass alternatives: [] when defaults are irrelevant (e.g., for missing Trace ID, Event ID)
  • Use " and " in resource for plural grammar: "Trace ID and span ID" → "are required"

CI enforcement: bun run check:errors scans for ContextError with multiline commands and CliError with ad-hoc "Try:" strings.

// Usage examples
throw new ContextError("Organization", "sentry org view <org-slug>");
throw new ContextError("Trace ID", "sentry trace view <trace-id>", []); // no alternatives
throw new ResolutionError("Project 'cli'", "not found", "sentry issue list <org>/cli", [
  "No project with this slug found in any accessible organization",
]);
throw new ValidationError("Invalid trace ID format", "traceId");

Async Config Functions

All config operations are async. Always await:

const token = await getAuthToken();
const isAuth = await isAuthenticated();
await setAuthToken(token, expiresIn);

Imports

  • Use .js extension for local imports (ESM requirement)
  • Group: external packages first, then local imports
  • Use type keyword for type-only imports
import { z } from "zod";
import { buildCommand } from "../../lib/command.js";
import type { SentryContext } from "../../context.js";
import { getAuthToken } from "../../lib/config.js";

List Command Infrastructure

Two abstraction levels exist for list commands:

  1. src/lib/list-command.ts — buildOrgListCommand factory + shared Stricli parameter constants (LIST_TARGET_POSITIONAL, LIST_JSON_FLAG, LIST_CURSOR_FLAG, buildListLimitFlag). Use this for simple entity lists like team list and repo list.

  2. src/lib/org-list.ts — dispatchOrgScopedList with OrgListConfig and a 4-mode handler map: auto-detect, explicit, org-all, project-search. Complex commands (project list, issue list) call dispatchOrgScopedList with an overrides map directly instead of using buildOrgListCommand.

Key rules when writing overrides:

  • Each mode handler receives a HandlerContext<T> with the narrowed parsed plus shared I/O (stdout, cwd, flags). Access parsed fields via ctx.parsed.org, ctx.parsed.projectSlug, etc. — no manual Extract<> casts needed.
  • Commands with extra fields (e.g., stderr, setContext) spread the context and add them: (ctx) => handle({ ...ctx, flags, stderr, setContext }). Override ctx.flags with the command-specific flags type when needed.
  • resolveCursor() must be called inside the org-all override closure, not before dispatchOrgScopedList, so that --cursor validation errors fire correctly for non-org-all modes.
  • handleProjectSearch errors must use "Project" as the ContextError resource, not config.entityName.
  1. Standalone list commands (e.g., span list, trace list) that don't use org-scoped dispatch wire pagination directly in func(). See the "List Command Pagination" section above for the pattern.

Commenting & Documentation (JSDoc-first)

Default Rule

  • Prefer JSDoc over inline comments.
  • Code should be readable without narrating what it already says.

Required: JSDoc

Add JSDoc comments on:

  • Every exported function, class, and type (and important internal ones).
  • Types/interfaces: document each field/property (what it represents, units, allowed values, meaning of null, defaults).

Include in JSDoc:

  • What it does
  • Key business rules / constraints
  • Assumptions and edge cases
  • Side effects
  • Why it exists (when non-obvious)

Inline Comments (rare)

Inline comments are allowed only when they add information the code cannot express:

  • "Why" - business reason, constraint, historical context
  • Non-obvious behavior - surprising edge cases
  • Workarounds - bugs in dependencies, platform quirks
  • Hardcoded values - why hardcoded, what would break if changed

Inline comments are NOT allowed if they just restate the code:

// Bad:
if (!person) // if no person  
i++          // increment i   
return result // return result 

// Good:
// Required by GDPR Article 17 - user requested deletion
await deleteUserData(userId)

Prohibited Comment Styles

  • ASCII art section dividers - Do not use decorative box-drawing characters like ───────── to create section headers. Use standard JSDoc comments or simple // Section Name comments instead.

Goal

Minimal comments, maximum clarity. Comments explain intent and reasoning, not syntax.

Testing (bun:test + fast-check)

Prefer property-based and model-based testing over traditional unit tests. These approaches find edge cases automatically and provide better coverage with less code.

fast-check Documentation: https://fast-check.dev/docs/core-blocks/arbitraries/

Testing Hierarchy (in order of preference)

  1. Model-Based Tests - For stateful systems (database, caches, state machines)
  2. Property-Based Tests - For pure functions, parsing, validation, transformations
  3. Unit Tests - Only for trivial cases or when properties are hard to express

Test File Naming

Type Pattern Location
Property-based *.property.test.ts test/lib/
Model-based *.model-based.test.ts test/lib/db/
Unit tests *.test.ts test/ (mirrors src/)
E2E tests *.test.ts test/e2e/

Test Environment Isolation (CRITICAL)

Tests that need a database or config directory must use useTestConfigDir() from test/helpers.ts. This helper:

  • Creates a unique temp directory in beforeEach
  • Sets SENTRY_CONFIG_DIR to point at it
  • Restores (never deletes) the env var in afterEach
  • Closes the database and cleans up temp files

NEVER do any of these in test files:

  • delete process.env.SENTRY_CONFIG_DIR — This pollutes other test files that load after yours
  • const baseDir = process.env[CONFIG_DIR_ENV_VAR]! at module scope — This captures a value that may be stale
  • Manual beforeEach/afterEach that sets/deletes SENTRY_CONFIG_DIR

Why: Bun runs test files sequentially in one thread (load → run all tests → load next file). If your afterEach deletes the env var, the next file's module-level code reads undefined, causing TypeError: The "paths[0]" property must be of type string.

// CORRECT: Use the helper
import { useTestConfigDir } from "../helpers.js";

const getConfigDir = useTestConfigDir("my-test-prefix-");

// If you need the directory path in a test:
test("example", () => {
  const dir = getConfigDir();
});

// WRONG: Manual env var management
beforeEach(() => { process.env.SENTRY_CONFIG_DIR = tmpDir; });
afterEach(() => { delete process.env.SENTRY_CONFIG_DIR; }); // BUG!

Property-Based Testing

Use property-based tests when verifying invariants that should hold for any valid input.

import { describe, expect, test } from "bun:test";
import { constantFrom, assert as fcAssert, property, tuple } from "fast-check";
import { DEFAULT_NUM_RUNS } from "../model-based/helpers.js";

// Define arbitraries (random data generators)
const slugArb = array(constantFrom(..."abcdefghijklmnopqrstuvwxyz0123456789".split("")), {
  minLength: 1,
  maxLength: 15,
}).map((chars) => chars.join(""));

describe("property: myFunction", () => {
  test("is symmetric", () => {
    fcAssert(
      property(slugArb, slugArb, (a, b) => {
        // Properties should always hold regardless of input
        expect(myFunction(a, b)).toBe(myFunction(b, a));
      }),
      { numRuns: DEFAULT_NUM_RUNS }
    );
  });

  test("round-trip: encode then decode returns original", () => {
    fcAssert(
      property(validInputArb, (input) => {
        const encoded = encode(input);
        const decoded = decode(encoded);
        expect(decoded).toEqual(input);
      }),
      { numRuns: DEFAULT_NUM_RUNS }
    );
  });
});

Good candidates for property-based testing:

  • Parsing functions (DSN, issue IDs, aliases)
  • Encoding/decoding (round-trip invariant)
  • Symmetric operations (a op b = b op a)
  • Idempotent operations (f(f(x)) = f(x))
  • Validation functions (valid inputs accepted, invalid rejected)

See examples: test/lib/dsn.property.test.ts, test/lib/alias.property.test.ts, test/lib/issue-id.property.test.ts

Model-Based Testing

Use model-based tests for stateful systems where sequences of operations should maintain invariants.

import { describe, expect, test } from "bun:test";
import {
  type AsyncCommand,
  asyncModelRun,
  asyncProperty,
  commands,
  assert as fcAssert,
} from "fast-check";
import { createIsolatedDbContext, DEFAULT_NUM_RUNS } from "../../model-based/helpers.js";

// Define a simplified model of expected state
type DbModel = {
  entries: Map<string, string>;
};

// Define commands that operate on both model and real system
class SetCommand implements AsyncCommand<DbModel, RealDb> {
  constructor(readonly key: string, readonly value: string) {}
  
  check = () => true;
  
  async run(model: DbModel, real: RealDb): Promise<void> {
    // Apply to real system
    await realSet(this.key, this.value);
    
    // Update model
    model.entries.set(this.key, this.value);
  }
  
  toString = () => `set("${this.key}", "${this.value}")`;
}

class GetCommand implements AsyncCommand<DbModel, RealDb> {
  constructor(readonly key: string) {}
  
  check = () => true;
  
  async run(model: DbModel, real: RealDb): Promise<void> {
    const realValue = await realGet(this.key);
    const expectedValue = model.entries.get(this.key);
    
    // Verify real system matches model
    expect(realValue).toBe(expectedValue);
  }
  
  toString = () => `get("${this.key}")`;
}

describe("model-based: database", () => {
  test("random sequences maintain consistency", () => {
    fcAssert(
      asyncProperty(commands(allCommandArbs), async (cmds) => {
        const cleanup = createIsolatedDbContext();
        try {
          await asyncModelRun(
            () => ({ model: { entries: new Map() }, real: {} }),
            cmds
          );
        } finally {
          cleanup();
        }
      }),
      { numRuns: DEFAULT_NUM_RUNS }
    );
  });
});

Good candidates for model-based testing:

  • Database operations (auth, caches, regions)
  • Stateful caches with invalidation
  • Systems with cross-cutting invariants (e.g., clearAuth also clears regions)

See examples: test/lib/db/model-based.test.ts, test/lib/db/dsn-cache.model-based.test.ts

Test Helpers

Use test/model-based/helpers.ts for shared utilities:

import { createIsolatedDbContext, DEFAULT_NUM_RUNS } from "../model-based/helpers.js";

// Create isolated DB for each test run (prevents interference)
const cleanup = createIsolatedDbContext();
try {
  // ... test code
} finally {
  cleanup();
}

// Use consistent number of runs across tests
fcAssert(property(...), { numRuns: DEFAULT_NUM_RUNS }); // 50 runs

When to Use Unit Tests

Use traditional unit tests only when:

  • Testing trivial logic with obvious expected values
  • Properties are difficult to express or would be tautological
  • Testing error messages or specific output formatting
  • Integration with external systems (E2E tests)

Avoiding Unit/Property Test Duplication

When a *.property.test.ts file exists for a module, do not add unit tests that re-check the same invariants with hardcoded examples. Before adding a unit test, check whether the companion property file already generates random inputs for that invariant.

Unit tests that belong alongside property tests:

  • Edge cases outside the property generator's range (e.g., self-hosted DSNs when the arbitrary only produces SaaS ones)
  • Specific output format documentation (exact strings, column layouts, rendered vs plain mode)
  • Concurrency/timing behavior that property tests cannot express
  • Integration tests exercising multiple functions together (e.g., writeJsonList envelope shape)

Unit tests to avoid when property tests exist:

  • "returns true for valid input" / "returns false for invalid input" — the property test already covers this with random inputs
  • Basic round-trip assertions — property tests check decode(encode(x)) === x for all x
  • Hardcoded examples of invariants like idempotency, symmetry, or subset relationships

When adding property tests for a function that already has unit tests, remove the unit tests that become redundant. Add a header comment to the unit test file noting which invariants live in the property file:

/**
 * Note: Core invariants (round-trips, validation, ordering) are tested via
 * property-based tests in foo.property.test.ts. These tests focus on edge
 * cases and specific output formatting not covered by property generators.
 */
import { describe, expect, test, mock } from "bun:test";

describe("feature", () => {
  test("should return specific value", async () => {
    expect(await someFunction("input")).toBe("expected output");
  });
});

// Mock modules when needed
mock.module("./some-module", () => ({
  default: () => "mocked",
}));

File Locations

What Where
Add new command src/commands/<domain>/
Add API types src/types/sentry.ts
Add config types src/types/config.ts
Add Seer types src/types/seer.ts
Add utility src/lib/
Add DSN language support src/lib/dsn/languages/
Add DB operations src/lib/db/
Build scripts script/
Add property tests test/lib/<name>.property.test.ts
Add model-based tests test/lib/db/<name>.model-based.test.ts
Add unit tests test/ (mirror src/ structure)
Add E2E tests test/e2e/
Test helpers test/model-based/helpers.ts
Add documentation docs/src/content/docs/

Long-term Knowledge

Architecture

  • DSN org prefix normalization in arg-parsing.ts: Sentry DSN hosts encode org IDs as `oNNNNN` (e.g., `o1081365.ingest.us.sentry.io`). The Sentry API rejects the `o`-prefixed form. `stripDsnOrgPrefix()` in `src/lib/arg-parsing.ts` uses `/^o(\d+)$/` to strip the prefix — safe for slugs like `organic`. Applied in `parseOrgProjectArg()` and `parseWithSlash()`, covering all API call paths consuming `parsed.org`.
  • GHCR versioned nightly tags for delta upgrade support: GHCR nightly distribution uses three tag types: `:nightly` (rolling), `:nightly-<version>` (immutable), `:patch-<version>` (delta manifest). Delta patches use zig-bsdiff TRDIFF10 (zstd-compressed), ~50KB vs ~29MB full. Client bspatch via `Bun.zstdDecompressSync()`. N-1 patches only, full download fallback, SHA-256 verify, 60% size threshold. npm/Node excluded. Test mocks: use `mockGhcrNightlyVersion()` helper.
  • Issue list auto-pagination beyond API's 100-item cap: Sentry API silently caps `limit` at 100 per request. `listIssuesAllPages()` auto-paginates using Link headers, bounded by MAX_PAGINATION_PAGES (50). `API_MAX_PER_PAGE` constant is shared across all paginated consumers. `--limit` means total results everywhere (max 1000, default 25). Org-all mode uses `fetchOrgAllIssues()`; explicit `--cursor` does single-page fetch to preserve cursor chain.
  • Self-hosted OAuth device flow requires Sentry 26.1.0+ and SENTRY_CLIENT_ID: Self-hosted OAuth device flow requires Sentry 26.1.0+ and both `SENTRY_URL` and `SENTRY_CLIENT_ID` env vars. Users must create a public OAuth app in Settings → Developer Settings. The client ID is NOT optional for self-hosted. Fallback for older instances: `sentry auth login --token`. `getSentryUrl()` and `getClientId()` in `src/lib/oauth.ts` read lazily (not at module load) so URL parsing from arguments can set `SENTRY_URL` after import.
  • Sentry CLI markdown-first formatting pipeline replaces ad-hoc ANSI: Formatters build CommonMark strings; `renderMarkdown()` renders to ANSI for TTY or raw markdown for non-TTY. Key helpers: `colorTag()`, `mdKvTable()`, `mdRow()`, `mdTableHeader()` (`:` suffix = right-aligned), `renderTextTable()`. `isPlainOutput()` checks `SENTRY_PLAIN_OUTPUT` > `NO_COLOR` > `!isTTY`. Batch path: `formatXxxTable()`. Streaming path: `StreamingTable` (TTY) or raw markdown rows (plain). Both share `buildXxxRowCells()`.
  • Sentry issue stats field: time-series controlled by groupStatsPeriod: The `stats` field on issues is `{ '24h': [[ts, count], ...] }`. Key depends on `groupStatsPeriod` param (`""`, `"14d"`, `"24h"`, `"auto"`). `statsPeriod` controls time window; `groupStatsPeriod` controls stats key. **Critical**: `count` is period-scoped — `lifetime.count` is the true lifetime total. Issue list table uses `groupStatsPeriod: 'auto'` for sparkline data. Column order: SHORT ID, ISSUE, SEEN, AGE, TREND, EVENTS, USERS, TRIAGE. TREND auto-hidden when terminal < 100 cols. `--compact` tri-state: explicit overrides; `undefined` triggers `shouldAutoCompact(rowCount)` — compact if `3N + 3 > termHeight`, false for non-TTY. Height is `3N + 3` (not `3N + 4`) because last data row has no trailing separator.
  • Sentry trace-logs API is org-scoped, not project-scoped: The Sentry trace-logs endpoint (`/organizations/{org}/trace-logs/`) is org-scoped, so `trace logs` uses `resolveOrg()` not `resolveOrgAndProject()`. The endpoint is PRIVATE in Sentry source, excluded from the public OpenAPI schema — `@sentry/api` has no generated types. The hand-written `TraceLogSchema` in `src/types/sentry.ts` is required until Sentry makes it public.
  • withAuthGuard returns discriminated Result type, not fallback+onError: `withAuthGuard<T>(fn)` in `src/lib/errors.ts` returns a discriminated Result: `{ ok: true, value: T } | { ok: false, error: unknown }`. AuthErrors always re-throw (triggers bin.ts auto-login). All other errors are captured. Callers inspect `result.ok` to degrade gracefully. Used across 12+ files.

Gotcha

  • Biome lint: Response.redirect() required, nested ternaries forbidden: Biome lint rules that frequently trip up this codebase: (1) `useResponseRedirect`: use `Response.redirect(url, status)` not `new Response`. (2) `noNestedTernary`: use `if/else`. (3) `noComputedPropertyAccess`: use `obj.property` not `obj["property"]`. (4) Max cognitive complexity 15 per function — extract helpers to stay under.
  • Bugbot flags defensive null-checks as dead code — keep them with JSDoc justification: Cursor Bugbot and Sentry Seer repeatedly flag two false positives: (1) defensive null-checks as "dead code" — keep them with JSDoc explaining why the guard exists for future safety, especially when removing would require `!` assertions banned by `noNonNullAssertion`. (2) stderr spinner output during `--json` mode — always a false positive since progress goes to stderr, JSON to stdout. Reply explaining the rationale and resolve.
  • Bun mock.module for node:tty requires default export and class stubs: Bun testing gotchas: (1) `mock.module()` for CJS built-ins requires a `default` re-export plus all named exports. Missing any causes `SyntaxError: Export named 'X' not found`. Always check the real module's full export list. (2) `Bun.mmap()` always opens with PROT_WRITE — macOS SIGKILL on signed Mach-O, Linux ETXTBSY. Fix: use `new Uint8Array(await Bun.file(path).arrayBuffer())` in bspatch.ts. (3) Wrap `Bun.which()` with optional `pathEnv` param for deterministic testing without mocks.

Pattern

  • Branch naming and commit message conventions for Sentry CLI: Branch naming: `feat/<short-description>` or `fix/<issue-number>-<short-description>` (e.g., `feat/ghcr-nightly-distribution`, `fix/268-limit-auto-pagination`). Commit message format: `type(scope): description (#issue)` (e.g., `fix(issue-list): auto-paginate --limit beyond 100 (#268)`, `feat(nightly): distribute via GHCR instead of GitHub Releases`). Types seen: fix, refactor, meta, release, feat. PRs are created as drafts via `gh pr create --draft`. Implementation plans are attached to commits via `git notes add` rather than in PR body or commit message.
  • Codecov patch coverage only counts test:unit and test:isolated, not E2E: CI coverage merges `test:unit` (`test/lib test/commands test/types --coverage`) and `test:isolated` (`test/isolated --coverage`) into `coverage/merged.lcov`. E2E tests (`test/e2e`) are NOT included in coverage reports. So func tests that spy on exports (e.g., `spyOn(apiClient, 'getLogs')`) give zero coverage to the mocked function's body. To cover `api-client.ts` function bodies in unit tests, mock `globalThis.fetch` + `setOrgRegion()` + `setAuthToken()` and call the real function.
  • Pagination contextKey must include all query-varying parameters with escaping: Pagination `contextKey` must encode every query-varying parameter (sort, query, period) with `escapeContextKeyValue()` (replaces `|` with `%7C`). Always provide a fallback before escaping since `flags.period` may be `undefined` in tests despite having a default: `flags.period ? escapeContextKeyValue(flags.period) : "90d"`.
  • PR review workflow: reply, resolve, amend, force-push: PR review workflow: (1) Read unresolved threads via GraphQL, (2) make code changes, (3) run lint+typecheck+tests, (4) create a SEPARATE commit per review round (not amend) for incremental review, (5) push normally, (6) reply to comments via REST API, (7) resolve threads via GraphQL `resolveReviewThread`. Only amend+force-push when user explicitly asks or pre-commit hook modified files.
  • Stricli optional boolean flags produce tri-state (true/false/undefined): Stricli boolean flags with `optional: true` (no `default`) produce `boolean | undefined` in the flags type. `--flag` → `true`, `--no-flag` → `false`, omitted → `undefined`. This enables auto-detect patterns: explicit user choice overrides, `undefined` triggers heuristic. Used by `--compact` on issue list. The flag type must be `readonly field?: boolean` (not `readonly field: boolean`). This differs from `default: false` which always produces a defined boolean.
  • Testing Stricli command func() bodies via spyOn mocking: Stricli/Bun test patterns: (1) Command func tests: `const func = await cmd.loader()`, then `func.call(mockContext, flags, ...args)`. `loader()` return type union causes LSP errors — false positives that pass `tsc`. File naming: `*.func.test.ts`. (2) ESM prevents `vi.spyOn` on Node built-in exports. Workaround: test subclass that overrides the method calling the built-in. (3) Follow-mode uses `setTimeout`-based scheduling; test with `interceptSigint()` helper. `Bun.sleep()` has no AbortSignal so `setTimeout`/`clearTimeout` required.