fix: improve error messages — fix ContextError/ResolutionError misuse

Fix the 'Try: ... Or: ...' error message pattern that produced confusing
output for hundreds of users (CLI-7V: 127 events, CLI-4A: 21 events, etc).

Problems fixed:
- ContextError misused for resolution failures, producing messages like
  'Project is required. Specify it using: No project found...'
- Grammar: 'Trace ID and span ID is required' → 'are required'
- Irrelevant DSN/project alternatives shown for missing positional IDs
- Ad-hoc 'Try:' strings in raw CliError bypassing structured errors
- Pagination cursor using ContextError instead of ValidationError
- event view throwing confusing error for issue URLs (now fetches latest event)

Prevention measures:
- Runtime assertion in ContextError constructor: command must be single-line
- CI check script (check:errors) scanning for multiline ContextError commands
  and ad-hoc 'Try:' patterns in CliError
- Improved JSDoc explaining when to use ContextError vs ResolutionError
- AGENTS.md updated with error class selection guidance

Fixes CLI-7V, CLI-4A, CLI-EZ, CLI-CC, CLI-DQ

Author: BYK

.github/workflows/ci.yml

@@ -149,6 +149,7 @@ jobs:
       - run: bun run lint
       - run: bun run typecheck
       - run: bun run check:deps
+      - run: bun run check:errors
 
   test-unit:
     name: Unit Tests

AGENTS.md

@@ -399,19 +399,37 @@ CliError (base)
 ├── 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 |
 
-// Usage: throw specific error types
-import { ApiError, AuthError, SeerError } from "../lib/errors.js";
-throw new AuthError("not_authenticated");
-throw new ApiError("Request failed", 404, "Not found");
-throw new SeerError("not_enabled", orgSlug); // Includes actionable URL
+**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"
 
-// In commands: let errors propagate to central handler
-// The bin.ts entry point catches and formats all errors consistently
+**CI enforcement:** `bun run check:errors` scans for `ContextError` with multiline commands and `CliError` with ad-hoc "Try:" strings.
+
+```typescript
+// 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

package.json

@@ -74,7 +74,8 @@
     "generate:skill": "bun run script/generate-skill.ts",
     "generate:schema": "bun run script/generate-api-schema.ts",
     "check:skill": "bun run script/check-skill.ts",
-    "check:deps": "bun run script/check-no-deps.ts"
+    "check:deps": "bun run script/check-no-deps.ts",
+    "check:errors": "bun run script/check-error-patterns.ts"
   },
   "type": "module"
 }

script/check-error-patterns.ts

@@ -0,0 +1,280 @@
+#!/usr/bin/env bun
+/**
+ * Check for Error Class Misuse Patterns
+ *
+ * Scans source files for common anti-patterns in error class usage:
+ *
+ * 1. `new ContextError(resource, command)` where command contains `\n`
+ *    → Should use ResolutionError for resolution failures
+ *
+ * 2. `new CliError(... "Try:" ...)` — ad-hoc "Try:" strings
+ *    → Should use ResolutionError with structured hint/suggestions
+ *
+ * Usage:
+ *   bun run script/check-error-patterns.ts
+ *
+ * Exit codes:
+ *   0 - No anti-patterns found
+ *   1 - Anti-patterns detected
+ */
+
+export {};
+
+type Violation = { file: string; line: number; message: string };
+
+const CONTEXT_ERROR_RE = /new ContextError\(/g;
+const TRY_PATTERN_RE = /["'`]Try:/;
+
+const glob = new Bun.Glob("src/**/*.ts");
+const violations: Violation[] = [];
+
+/** Characters that open a nesting level in JavaScript source. */
+function isOpener(ch: string): boolean {
+  return ch === "(" || ch === "[" || ch === "{";
+}
+
+/** Characters that close a nesting level in JavaScript source. */
+function isCloser(ch: string): boolean {
+  return ch === ")" || ch === "]" || ch === "}";
+}
+
+/** Characters that start a string literal in JavaScript source. */
+function isQuote(ch: string): boolean {
+  return ch === '"' || ch === "'" || ch === "`";
+}
+
+/**
+ * Skip past a `${...}` expression inside a template literal.
+ * @param content - Full source text
+ * @param start - Index right after the `{` in `${`
+ * @returns Index right after the closing `}`
+ */
+function skipTemplateExpression(content: string, start: number): number {
+  let braceDepth = 1;
+  let i = start;
+  while (i < content.length && braceDepth > 0) {
+    const ec = content[i];
+    if (ec === "\\") {
+      i += 2;
+    } else if (ec === "`") {
+      i = skipTemplateLiteral(content, i + 1);
+    } else if (ec === "{") {
+      braceDepth += 1;
+      i += 1;
+    } else if (ec === "}") {
+      braceDepth -= 1;
+      i += 1;
+    } else {
+      i += 1;
+    }
+  }
+  return i;
+}
+
+/**
+ * Skip past a template literal, handling nested `${...}` expressions.
+ * @param content - Full source text
+ * @param start - Index right after the opening backtick
+ * @returns Index right after the closing backtick
+ */
+function skipTemplateLiteral(content: string, start: number): number {
+  let i = start;
+  while (i < content.length) {
+    const ch = content[i];
+    if (ch === "\\") {
+      i += 2;
+    } else if (ch === "`") {
+      return i + 1;
+    } else if (ch === "$" && content[i + 1] === "{") {
+      i = skipTemplateExpression(content, i + 2);
+    } else {
+      i += 1;
+    }
+  }
+  return i;
+}
+
+/**
+ * Advance past a string literal (single-quoted, double-quoted, or template).
+ * @param content - Full source text
+ * @param start - Index of the opening quote character
+ * @returns Index right after the closing quote
+ */
+function skipString(content: string, start: number): number {
+  const quote = content[start];
+  if (quote === "`") {
+    return skipTemplateLiteral(content, start + 1);
+  }
+  let i = start + 1;
+  while (i < content.length) {
+    const ch = content[i];
+    if (ch === "\\") {
+      i += 2;
+    } else if (ch === quote) {
+      return i + 1;
+    } else {
+      i += 1;
+    }
+  }
+  return i;
+}
+
+/**
+ * Advance one token in JS source, skipping strings as atomic units.
+ * @returns The next index and the character at position `i` (or the string span's first char).
+ */
+function advanceToken(
+  content: string,
+  i: number
+): { next: number; ch: string } {
+  const ch = content[i] ?? "";
+  if (isQuote(ch)) {
+    return { next: skipString(content, i), ch };
+  }
+  return { next: i + 1, ch };
+}
+
+/**
+ * Walk from `startIdx` (just inside the opening `(`) to find the matching `)`,
+ * tracking commas at depth 1.
+ * @returns The index of the first comma (between arg1 and arg2) and the closing paren index.
+ */
+function findCallBounds(
+  content: string,
+  startIdx: number
+): { commaIdx: number; closingIdx: number } | null {
+  let depth = 1;
+  let commaCount = 0;
+  let commaIdx = -1;
+  let i = startIdx;
+
+  while (i < content.length && depth > 0) {
+    const { next, ch } = advanceToken(content, i);
+    if (isOpener(ch)) {
+      depth += 1;
+    } else if (isCloser(ch)) {
+      depth -= 1;
+    } else if (ch === "," && depth === 1) {
+      commaCount += 1;
+      if (commaCount === 1) {
+        commaIdx = i;
+      }
+    }
+    i = next;
+  }
+
+  if (commaIdx === -1) {
+    return null;
+  }
+  return { commaIdx, closingIdx: i - 1 };
+}
+
+/**
+ * Extract the second argument of a `new ContextError(...)` call from source text.
+ * Properly handles template literals so backticks don't break depth tracking.
+ * @returns The raw source text of the second argument, or null if not found.
+ */
+function extractSecondArg(content: string, startIdx: number): string | null {
+  const bounds = findCallBounds(content, startIdx);
+  if (!bounds) {
+    return null;
+  }
+
+  const { commaIdx, closingIdx } = bounds;
+
+  // Find end of second arg: next comma at depth 1 or closing paren
+  let endIdx = closingIdx;
+  let d = 1;
+  for (let j = commaIdx + 1; j < closingIdx; j += 1) {
+    const { next, ch } = advanceToken(content, j);
+    if (isOpener(ch)) {
+      d += 1;
+    } else if (isCloser(ch)) {
+      d -= 1;
+    } else if (ch === "," && d === 1) {
+      endIdx = j;
+      break;
+    }
+    // advanceToken may skip multiple chars (strings), adjust loop var
+    j = next - 1; // -1 because for-loop increments
+  }
+
+  return content.slice(commaIdx + 1, endIdx).trim();
+}
+
+/**
+ * Detect `new ContextError(` where the second argument contains `\n`.
+ * This catches resolution-failure prose stuffed into the command parameter.
+ */
+function checkContextErrorNewlines(content: string, filePath: string): void {
+  let match = CONTEXT_ERROR_RE.exec(content);
+  while (match !== null) {
+    const startIdx = match.index + match[0].length;
+    const secondArg = extractSecondArg(content, startIdx);
+
+    if (secondArg?.includes("\\n")) {
+      const line = content.slice(0, match.index).split("\n").length;
+      violations.push({
+        file: filePath,
+        line,
+        message:
+          "ContextError command contains '\\n'. Use ResolutionError for multi-line resolution failures.",
+      });
+    }
+    match = CONTEXT_ERROR_RE.exec(content);
+  }
+}
+
+/**
+ * Detect `new CliError(... "Try:" ...)` — ad-hoc "Try:" strings that bypass
+ * the structured ResolutionError pattern.
+ */
+function checkAdHocTryPatterns(content: string, filePath: string): void {
+  const lines = content.split("\n");
+  let inCliError = false;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (line.includes("new CliError(")) {
+      inCliError = true;
+    }
+    if (inCliError && TRY_PATTERN_RE.test(line)) {
+      violations.push({
+        file: filePath,
+        line: i + 1,
+        message:
+          'CliError contains "Try:" — use ResolutionError with structured hint/suggestions instead.',
+      });
+      inCliError = false;
+    }
+    // Reset after a reasonable window (closing paren)
+    if (inCliError && line.includes(");")) {
+      inCliError = false;
+    }
+  }
+}
+
+for await (const filePath of glob.scan(".")) {
+  const content = await Bun.file(filePath).text();
+  checkContextErrorNewlines(content, filePath);
+  checkAdHocTryPatterns(content, filePath);
+}
+
+if (violations.length === 0) {
+  console.log("✓ No error class anti-patterns found");
+  process.exit(0);
+}
+
+console.error(`✗ Found ${violations.length} error class anti-pattern(s):\n`);
+for (const v of violations) {
+  console.error(`  ${v.file}:${v.line}`);
+  console.error(`    ${v.message}\n`);
+}
+console.error(
+  "Fix: Use ResolutionError for resolution failures, ValidationError for input errors."
+);
+console.error(
+  "See ContextError JSDoc in src/lib/errors.ts for usage guidance."
+);
+
+process.exit(1);