feat: add schema command for Sentry API introspection

Phase 2 of #346: Add `sentry schema` command for runtime API introspection
by AI agents.

New features:
- `sentry schema` — list all API resources with endpoint counts
- `sentry schema <resource>` — list endpoints for a resource
- `sentry schema <resource> <operation>` — show endpoint details
- `sentry schema --list` — flat list of all 214 API endpoints
- `sentry schema --search <query>` — search across endpoints
- All modes support `--json` for machine-readable output

Architecture:
- `script/generate-api-schema.ts` — build-time parser that extracts
  endpoint metadata from `@sentry/api` (function names, HTTP methods,
  URL templates, JSDoc descriptions, deprecation status)
- `src/generated/api-schema.json` — lightweight index (102KB, 214
  endpoints) bundled into the CLI
- `src/lib/api-schema.ts` — runtime query functions (by resource,
  operation, or full-text search)
- `src/commands/schema.ts` — command with human + JSON output modes

Tests: 19 unit tests for schema query functions

Author: BYK

AGENTS.md

@@ -72,7 +72,9 @@
     "test:e2e": "bun test --timeout 15000 test/e2e",
     "test:init-eval": "bun test test/init-eval --timeout 600000 --concurrency 6",
     "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:schema": "bun run script/generate-api-schema.ts && git diff --exit-code src/generated/api-schema.json",
     "check:deps": "bun run script/check-no-deps.ts"
   },
   "type": "module"

package.json

@@ -737,6 +737,20 @@ Initialize Sentry in your project
 - `--features <value>... - Features to enable: errors,tracing,logs,replay,metrics`
 - `-t, --team <value> - Team slug to create the project under`
 
+### Schema
+
+Browse the Sentry API schema
+
+#### `sentry schema <resource...>`
+
+Browse the Sentry API schema
+
+**Flags:**
+- `--list - List all endpoints in a flat table`
+- `--search <value> - Search endpoints by keyword`
+- `--json - Output as JSON`
+- `--fields <value> - Comma-separated fields to include in JSON output (dot.notation supported)`
+
 ### Issues
 
 List issues in a project

plugins/sentry-cli/skills/sentry-cli/SKILL.md

@@ -0,0 +1,293 @@
+#!/usr/bin/env bun
+/**
+ * Generate API Schema Index from @sentry/api
+ *
+ * Parses the @sentry/api package at build time to generate a lightweight
+ * JSON index of all API endpoints. This index is bundled into the CLI
+ * for runtime introspection via `sentry schema`.
+ *
+ * Data sources:
+ *   1. index.js — function name, HTTP method, URL template
+ *   2. sdk.gen.d.ts — JSDoc descriptions, deprecation status
+ *
+ * Usage:
+ *   bun run script/generate-api-schema.ts
+ *
+ * Output:
+ *   src/generated/api-schema.json
+ */
+
+const API_PKG = "node_modules/@sentry/api/dist";
+const OUTPUT_PATH = "src/generated/api-schema.json";
+
+/** Regex to strip JSDoc line prefix (" * ") */
+const JSDOC_LINE_PREFIX = /^\s*\*\s?/;
+/** Regex to collapse multiple spaces */
+const MULTI_SPACE = /\s+/g;
+/** Regex to extract path parameters from URL templates */
+const PATH_PARAM_PATTERN = /\{(\w+)\}/g;
+/** Regex to extract leading lowercase verb from function name */
+const LEADING_VERB_PATTERN = /^([a-z]+)/;
+
+/** Parsed endpoint data — exported to make this file a module for top-level await */
+export type ApiEndpoint = {
+  /** SDK function name */
+  fn: string;
+  /** HTTP method */
+  method: string;
+  /** URL template with {param} placeholders */
+  path: string;
+  /** Human-readable description from JSDoc */
+  description: string;
+  /** Path parameter names extracted from URL template */
+  pathParams: string[];
+  /** Whether the endpoint is deprecated */
+  deprecated: boolean;
+  /** Resource category derived from URL path */
+  resource: string;
+  /** Operation verb derived from function name */
+  operation: string;
+};
+
+// ---------------------------------------------------------------------------
+// Step 1: Parse index.js for function → {method, url}
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract function name, HTTP method, and URL from each SDK function in the
+ * bundled JS. Each function follows the pattern:
+ *   var NAME = (options...) => (options...client ?? client).METHOD({...url: "URL"...})
+ */
+async function parseJsBundle(): Promise<
+  Map<string, { method: string; url: string }>
+> {
+  const js = await Bun.file(`${API_PKG}/index.js`).text();
+  const results = new Map<string, { method: string; url: string }>();
+
+  // Match function declarations with method calls
+  const funcPattern =
+    /var (\w+) = \(options\S*\) => \(options\S*client \?\? client\)\.(\w+)\(/g;
+  // Match URL assignments
+  const urlPattern = /url: "([^"]+)"/g;
+
+  // Extract all function declarations
+  const funcs: { name: string; method: string; index: number }[] = [];
+  let match: RegExpExecArray | null;
+  match = funcPattern.exec(js);
+  while (match !== null) {
+    funcs.push({
+      name: match[1],
+      method: match[2].toUpperCase(),
+      index: match.index,
+    });
+    match = funcPattern.exec(js);
+  }
+
+  // Extract all URLs
+  const urls: { url: string; index: number }[] = [];
+  match = urlPattern.exec(js);
+  while (match !== null) {
+    urls.push({ url: match[1], index: match.index });
+    match = urlPattern.exec(js);
+  }
+
+  // Match each function to its URL (the URL that follows it in the source)
+  for (const func of funcs) {
+    const nextUrl = urls.find((u) => u.index > func.index);
+    if (nextUrl) {
+      results.set(func.name, { method: func.method, url: nextUrl.url });
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Step 2: Parse sdk.gen.d.ts for JSDoc descriptions
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract JSDoc descriptions and deprecation status for each exported function.
+ * Pattern: JSDoc block immediately before `export declare const NAME`
+ */
+async function parseDeclarations(): Promise<
+  Map<string, { description: string; deprecated: boolean }>
+> {
+  const dts = await Bun.file(`${API_PKG}/sdk.gen.d.ts`).text();
+  const results = new Map<
+    string,
+    { description: string; deprecated: boolean }
+  >();
+
+  // Match JSDoc + export declare const patterns
+  const pattern = /\/\*\*\n([\s\S]*?)\*\/\nexport declare const (\w+):/g;
+
+  let match = pattern.exec(dts);
+  while (match !== null) {
+    const jsdocBody = match[1];
+    const name = match[2];
+
+    // Clean up JSDoc: remove leading " * " from each line, trim
+    const description = jsdocBody
+      .split("\n")
+      .map((line) => line.replace(JSDOC_LINE_PREFIX, "").trim())
+      .filter((line) => line.length > 0)
+      .join(" ")
+      .replace(MULTI_SPACE, " ")
+      .trim();
+
+    const deprecated =
+      description.includes("## Deprecated") ||
+      description.includes("🚧") ||
+      name.startsWith("deprecated");
+
+    results.set(name, { description, deprecated });
+
+    match = pattern.exec(dts);
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Step 3: Derive resource and operation from URL and function name
+// ---------------------------------------------------------------------------
+
+/** Known operation verbs that appear as function name prefixes */
+const OPERATION_VERBS = [
+  "list",
+  "retrieve",
+  "create",
+  "update",
+  "delete",
+  "fetch",
+  "query",
+  "add",
+  "remove",
+  "bulk",
+  "start",
+  "enable",
+  "disable",
+  "edit",
+  "register",
+  "resolve",
+  "submit",
+  "upload",
+  "mutate",
+  "provision",
+  "get",
+  "debug",
+  "regenerate",
+  "syncs",
+  "deprecated",
+] as const;
+
+/**
+ * Derive the resource name from a URL template.
+ * Uses the last non-parameter path segment.
+ *
+ * Examples:
+ *   /api/0/organizations/{org}/issues/ → "issues"
+ *   /api/0/issues/{issue_id}/ → "issues"
+ *   /api/0/teams/{org}/{team}/projects/ → "projects"
+ *   /api/0/organizations/ → "organizations"
+ */
+function deriveResource(url: string): string {
+  const segments = url
+    .split("/")
+    .filter((s) => s.length > 0 && !s.startsWith("{"));
+  // Skip "api" and "0" prefix segments
+  const meaningful = segments.filter((s) => s !== "api" && s !== "0");
+  // Return the last meaningful segment
+  return meaningful.at(-1) ?? "unknown";
+}
+
+/**
+ * Derive the operation verb from a function name.
+ * Extracts the leading verb token.
+ *
+ * Examples:
+ *   listAnOrganization_sIssues → "list"
+ *   retrieveAnIssue → "retrieve"
+ *   createANewProject → "create"
+ *   deprecatedListAnOrganization_sMetricAlertRules → "list" (strips deprecated prefix)
+ */
+function deriveOperation(fnName: string): string {
+  let name = fnName;
+
+  // Strip "deprecated" prefix to get the actual verb
+  if (name.startsWith("deprecated")) {
+    name = name.charAt(10).toLowerCase() + name.slice(11);
+  }
+
+  // Match against known verbs
+  for (const verb of OPERATION_VERBS) {
+    if (verb === "deprecated") {
+      continue;
+    }
+    if (name.startsWith(verb)) {
+      return verb;
+    }
+  }
+
+  // Fallback: first lowercase sequence before an uppercase letter
+  const match = name.match(LEADING_VERB_PATTERN);
+  return match ? match[1] : "unknown";
+}
+
+/**
+ * Extract path parameter names from a URL template.
+ * /api/0/organizations/{organization_id_or_slug}/issues/ → ["organization_id_or_slug"]
+ */
+function extractPathParams(url: string): string[] {
+  const params: string[] = [];
+  const pattern = new RegExp(
+    PATH_PARAM_PATTERN.source,
+    PATH_PARAM_PATTERN.flags
+  );
+  let match = pattern.exec(url);
+  while (match !== null) {
+    params.push(match[1]);
+    match = pattern.exec(url);
+  }
+  return params;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const jsData = await parseJsBundle();
+const dtsData = await parseDeclarations();
+
+const endpoints: ApiEndpoint[] = [];
+
+for (const [name, { method, url }] of jsData) {
+  const decl = dtsData.get(name);
+
+  endpoints.push({
+    fn: name,
+    method,
+    path: url,
+    description: decl?.description ?? "",
+    pathParams: extractPathParams(url),
+    deprecated: decl?.deprecated ?? false,
+    resource: deriveResource(url),
+    operation: deriveOperation(name),
+  });
+}
+
+// Sort by resource, then operation for stable output
+endpoints.sort((a, b) => {
+  const resourceCmp = a.resource.localeCompare(b.resource);
+  if (resourceCmp !== 0) {
+    return resourceCmp;
+  }
+  return a.operation.localeCompare(b.operation);
+});
+
+await Bun.write(OUTPUT_PATH, JSON.stringify(endpoints, null, 2));
+
+console.log(
+  `Generated ${OUTPUT_PATH} (${endpoints.length} endpoints, ${Math.round(JSON.stringify(endpoints).length / 1024)}KB)`
+);

script/generate-api-schema.ts

@@ -24,6 +24,7 @@ import { projectRoute } from "./commands/project/index.js";
 import { listCommand as projectListCommand } from "./commands/project/list.js";
 import { repoRoute } from "./commands/repo/index.js";
 import { listCommand as repoListCommand } from "./commands/repo/list.js";
+import { schemaCommand } from "./commands/schema.js";
 import { spanRoute } from "./commands/span/index.js";
 import { listCommand as spanListCommand } from "./commands/span/list.js";
 import { teamRoute } from "./commands/team/index.js";
@@ -75,6 +76,7 @@ export const routes = buildRouteMap({
     trial: trialRoute,
     init: initCommand,
     api: apiCommand,
+    schema: schemaCommand,
     issues: issueListCommand,
     orgs: orgListCommand,
     projects: projectListCommand,