refactor: auto-generate SDK from route tree, single entry point

Rework the typed SDK to auto-discover ALL commands from the Stricli
route tree with zero manual config:

- generate-sdk.ts walks the entire route tree recursively, discovers
  44 commands, generates typed methods using CLI route names as-is
  (sdk.org.list, sdk.dashboard.widget.add)
- Return types derived from __jsonSchema (PR #582) via
  extractSchemaFields() — commands with schemas get typed returns,
  others default to unknown
- Positional params derived from introspection placeholder strings
- createSentrySDK() is now the single public API (default export)
- sdk.run() escape hatch replaces the standalone sentry() function
- SentryError/SentryOptions extracted to sdk-types.ts to break
  circular deps between index.ts and sdk-invoke.ts

Author: BYK

AGENTS.md

@@ -903,19 +903,22 @@ mock.module("./some-module", () => ({
 * **getConfigDir and getAuthToken read global process.env directly**: \`src/lib/env.ts\` provides a module-level env registry: \`getEnv()\` defaults to \`process.env\`, \`setEnv(env)\` swaps it. Library entry (\`src/index.ts\`) calls \`setEnv({ ...process.env, ...overrides })\` before running commands, restores in \`finally\`. All ~14 files that previously read \`process.env.SENTRY\_\*\` directly now use \`getEnv().SENTRY\_\*\`. Key files ported: \`db/auth.ts\`, \`db/index.ts\`, \`db/schema.ts\`, \`constants.ts\`, \`resolve-target.ts\`, \`telemetry.ts\`, \`formatters/plain-detect.ts\`, \`sentry-url-parser.ts\` (which also WRITES to env), \`logger.ts\`, \`response-cache.ts\`, \`api/infrastructure.ts\`, \`dsn/env.ts\`, \`version-check.ts\`, \`oauth.ts\`. CLI mode never calls \`setEnv()\` so behavior is unchanged. Tests using \`useTestConfigDir()\` continue to work since \`getEnv()\` defaults to \`process.env\`.
 
 <!-- lore:019d26a2-8d2f-7a31-81aa-e665b4dde197 -->
-* **Library API: variadic sentry() function with last-arg options detection**: The \`sentry()\` library export in \`src/index.ts\` uses variadic args with optional trailing options object: \`sentry("issue", "list", { token: "..." })\`. Last-arg detection: if final arg is an object (not string), it's \`SentryOptions\`. Options: \`token?\` (auth override, auto-fills from \`SENTRY\_AUTH\_TOKEN\`/\`SENTRY\_TOKEN\` env vars), \`text?\` (return human-readable string instead of parsed JSON), \`cwd?\` (working directory for DSN detection). Default behavior: JSON output via \`SENTRY\_OUTPUT\_FORMAT=json\` env var. Zero-copy return via \`captureObject\` duck-type on Writer — skips JSON.stringify/parse round-trip. Non-zero exit throws \`SentryError\` with \`.exitCode\` and \`.stderr\`. If \`capturedResult\` exists when an error is thrown (OutputError pattern), returns the data instead of throwing. Env isolation via \`setEnv({ ...process.env })\` — consumer's \`process.env\` never mutated. \`createSentrySDK(options?)\` provides typed namespace API that invokes commands directly via \`Command.loader()\`, bypassing Stricli's string dispatch.
+* **Library API: createSentrySDK() is the single entry point**: \`createSentrySDK(options?)\` in \`src/index.ts\` is the sole public API. It returns a typed SDK object with methods for every CLI command plus a \`run(...args)\` escape hatch. The standalone variadic \`sentry()\` function has been removed. \`SentryError\` and \`SentryOptions\` live in \`src/lib/sdk-types.ts\` (shared module to avoid circular deps between \`index.ts\` ↔ \`sdk-invoke.ts\`) and are re-exported from \`index.ts\`. Env isolation via \`setEnv()\`, zero-copy \`captureObject\` return, and \`OutputError\` → data recovery patterns are handled by \`buildInvoker()\` (typed methods) and \`buildRunner()\` (run escape hatch) in \`sdk-invoke.ts\`. Options: \`token?\`, \`text?\` (run-only), \`cwd?\`. Default JSON output via \`SENTRY\_OUTPUT\_FORMAT=json\` env var. Non-zero exit throws \`SentryError\` with \`.exitCode\` and \`.stderr\`.
 
 <!-- lore:019d26a2-8d34-76ef-a855-c28a7e7796d1 -->
 * **Library mode telemetry strips all global-polluting Sentry integrations**: When \`initSentry(enabled, { libraryMode: true })\` is called, the Sentry SDK initializes without integrations that pollute the host process. \`LIBRARY\_EXCLUDED\_INTEGRATIONS\` extends the base set with: \`OnUncaughtException\`, \`OnUnhandledRejection\`, \`ProcessSession\` (process listeners), \`Http\`/\`NodeFetch\` (trace header injection), \`FunctionToString\` (wraps \`Function.prototype.toString\`), \`ChildProcess\`/\`NodeContext\`. Also disables \`enableLogs\` and \`sendClientReports\` (both use timers/\`beforeExit\`), and skips \`process.on('beforeExit')\` handler registration. Keeps pure integrations: \`eventFiltersIntegration\`, \`linkedErrorsIntegration\`. Library entry manually calls \`client.flush(3000)\` after command completion (both success and error paths via \`flushTelemetry()\` helper). Only unavoidable global: \`globalThis.\_\_SENTRY\_\_\[SDK\_VERSION]\`.
 
 <!-- lore:019d2a93-55d9-7bc9-add2-c14a9a5fdd69 -->
-* **Typed SDK uses direct Command.loader() invocation bypassing Stricli dispatch**: \`createSentrySDK(options?)\` in \`src/index.ts\` builds a typed namespace API (\`sdk.organizations.list()\`, \`sdk.issues.get()\`) generated by \`script/generate-sdk.ts\`. At runtime, \`src/lib/sdk-invoke.ts\` resolves commands by walking the Stricli route tree via \`routes.getRoutingTargetForInput()\`, caches the \`Command\` objects, then calls \`command.loader()\` to get the wrapped func and invokes it with \`func.call(context, flags, ...args)\`. This bypasses Stricli's string scanning, route resolution, and flag parsing entirely — flags are passed as typed objects. The codegen script introspects flag definitions (kind, default, optional, variadic) at build time and generates TypeScript parameter interfaces. Return types use a manual type map (~20 entries) until schema registration on OutputConfig is implemented (#566).
+* **Typed SDK uses direct Command.loader() invocation bypassing Stricli dispatch**: \`createSentrySDK(options?)\` in \`src/index.ts\` builds a typed namespace API (\`sdk.org.list()\`, \`sdk.issue.view()\`) generated by \`script/generate-sdk.ts\`. At runtime, \`src/lib/sdk-invoke.ts\` resolves commands via Stricli route tree, caches \`Command\` objects, and calls \`command.loader()\` directly — bypassing string dispatch and flag parsing. The standalone variadic \`sentry()\` function has been removed: typed SDK methods are the primary path, with \`sdk.run()\` as an escape hatch for arbitrary CLI strings (interactive commands like \`auth login\`, raw \`api\` passthrough). The codegen auto-discovers ALL commands from the route tree with zero config, using CLI route names as-is (\`org.list\`, \`dashboard.widget.add\`). Return types are derived from \`__jsonSchema\` when present, otherwise \`unknown\`. Positional patterns are derived from introspection placeholder strings. Hidden routes (plural aliases) are skipped.
 
 ### Decision
 
 <!-- lore:019d26a2-8d3b-770a-866c-10ca04a374e7 -->
 * **OutputError propagates via throw instead of process.exit()**: The \`process.exit()\` call in \`command.ts\` (OutputError handler) is replaced with \`throw err\` to support library mode. \`OutputError\` is re-thrown through Stricli via \`exceptionWhileRunningCommand\` in \`app.ts\` (added before the \`AuthError\` check), so Stricli never writes an error message for it. In CLI mode (\`cli.ts\`), OutputError is caught and \`process.exitCode\` is set silently without writing to stderr (data was already rendered). In library mode (\`index.ts\`), the catch block checks if \`capturedResult\` has data (the OutputError's payload was rendered to stdout via \`captureObject\` before the throw) and returns it instead of throwing \`SentryError\`. This eliminates the only \`process.exit()\` outside of \`bin.ts\`.
 
+<!-- lore:019d2bd4-65c2-7b4c-99f7-cab41ee1ed71 -->
+* **SDK codegen auto-generates all commands from route tree**: \`script/generate-sdk.ts\` walks the entire Stricli route tree via \`discoverCommands()\`, skipping hidden routes (plural aliases). For each visible command: extracts flags via introspection, derives positional params from placeholder strings, checks \`__jsonSchema\` for typed return types (via \`extractSchemaFields()\`), and generates TypeScript param interfaces + method implementations. Naming uses CLI route path as-is: \`["org", "list"]\` → \`sdk.org.list()\`, \`["dashboard", "widget", "add"]\` → \`sdk.dashboard.widget.add()\`. Slash-separated positional names (e.g. \`org/project\`) are converted to camelCase (\`orgProject\`). Dotted field names in schemas are quoted (\`"span.op"\`). No manual config table — all 44+ commands are auto-discovered. Return types default to \`unknown\` when no schema is registered.
+
 ### Pattern
 
 <!-- lore:019d26a2-8d37-72ea-b7bd-14fef8556fea -->

README.md

@@ -88,43 +88,29 @@ Credentials are stored in `~/.sentry/` with restricted permissions (mode 600).
 Use Sentry CLI programmatically in Node.js (≥22) or Bun without spawning a subprocess:
 
 ```typescript
-import sentry from "sentry";
+import createSentrySDK from "sentry";
 
-// Returns parsed JSON — same as `sentry issue list --json`
-const issues = await sentry("issue", "list", "-l", "5");
+const sdk = createSentrySDK({ token: "sntrys_..." });
 
-// Explicit auth token (auto-fills from SENTRY_AUTH_TOKEN env var)
-const orgs = await sentry("org", "list", { token: "sntrys_..." });
+// Typed methods for every CLI command
+const orgs = await sdk.org.list();
+const issues = await sdk.issue.list({ orgProject: "acme/frontend", limit: 5 });
+const issue = await sdk.issue.view({ issue: "ACME-123" });
 
-// Human-readable text output
-const text = await sentry("issue", "list", { text: true });
+// Nested commands
+await sdk.dashboard.widget.add({ display: "line", query: "count" }, "my-org/my-dashboard");
 
-// Errors are thrown as SentryError with .exitCode and .stderr
-try {
-  await sentry("issue", "view", "NONEXISTENT-1");
-} catch (err) {
-  console.error(err.exitCode, err.stderr);
-}
+// Escape hatch for any CLI command
+const version = await sdk.run("--version");
+const text = await sdk.run("issue", "list", "-l", "5");
 ```
 
 Options (all optional):
 - `token` — Auth token. Falls back to `SENTRY_AUTH_TOKEN` / `SENTRY_TOKEN` env vars.
-- `text` — Return human-readable string instead of parsed JSON.
+- `text` — Return human-readable string instead of parsed JSON (affects `run()` only).
 - `cwd` — Working directory for DSN auto-detection. Defaults to `process.cwd()`.
 
-### Typed SDK
-
-For a more structured API with named parameters and typed returns:
-
-```typescript
-import { createSentrySDK } from "sentry";
-
-const sdk = createSentrySDK({ token: "sntrys_..." });
-
-const orgs = await sdk.organizations.list();
-const issues = await sdk.issues.list({ org: "acme", project: "frontend", limit: 5 });
-const issue = await sdk.issues.get({ issueId: "ACME-123" });
-```
+Errors are thrown as `SentryError` with `.exitCode` and `.stderr`.
 
 ---
 

biome.jsonc

@@ -67,12 +67,14 @@
       }
     },
     {
+      // src/index.ts is the library entry point — re-exports SentryError, SentryOptions, SentrySDK
       // db/index.ts exports db connection utilities - not a barrel file but triggers the rule
       // api-client.ts is a barrel that re-exports from src/lib/api/ domain modules
       // to preserve the existing import path for all consumers
       // markdown.ts re-exports isPlainOutput from plain-detect.ts for backward compat
       // script/debug-id.ts re-exports from src/lib/sourcemap/debug-id.ts for build scripts
       "includes": [
+        "src/index.ts",
         "src/lib/db/index.ts",
         "src/lib/api-client.ts",
         "src/lib/formatters/markdown.ts",

docs/src/content/docs/library-usage.md

@@ -16,71 +16,106 @@ npm install sentry
 ## Quick Start
 
 ```typescript
-import sentry from "sentry";
+import createSentrySDK from "sentry";
 
-// Run any CLI command — returns parsed JSON by default
-const issues = await sentry("issue", "list", "-l", "5");
-console.log(issues.data); // Array of issue objects
+const sdk = createSentrySDK({ token: "sntrys_..." });
+
+// Typed methods for every CLI command
+const orgs = await sdk.org.list();
+const issues = await sdk.issue.list({ orgProject: "acme/frontend", limit: 5 });
 ```
 
 ## Typed SDK
 
-For structured access with named parameters and TypeScript types, use `createSentrySDK`:
+`createSentrySDK()` returns an object with typed methods for **every** CLI command,
+organized by the CLI route hierarchy:
 
 ```typescript
-import { createSentrySDK } from "sentry";
+import createSentrySDK from "sentry";
 
 const sdk = createSentrySDK({ token: "sntrys_..." });
 ```
 
 ### Organizations
 
 ```typescript
-const orgs = await sdk.organizations.list();
-const org = await sdk.organizations.get("acme");
+const orgs = await sdk.org.list();
+const org = await sdk.org.view({ org: "acme" });
 ```
 
 ### Projects
 
 ```typescript
-const projects = await sdk.projects.list({ target: "acme/" });
-const project = await sdk.projects.get({ target: "acme/frontend" });
+const projects = await sdk.project.list({ orgProject: "acme/" });
+const project = await sdk.project.view({ orgProject: "acme/frontend" });
 ```
 
 ### Issues
 
 ```typescript
-const issues = await sdk.issues.list({
-  org: "acme",
-  project: "frontend",
+const issues = await sdk.issue.list({
+  orgProject: "acme/frontend",
   limit: 10,
   query: "is:unresolved",
   sort: "date",
 });
 
-const issue = await sdk.issues.get({ issueId: "ACME-123" });
+const issue = await sdk.issue.view({ issue: "ACME-123" });
 ```
 
 ### Events, Traces, Spans
 
 ```typescript
-const event = await sdk.events.get({ eventId: "abc123..." });
+const event = await sdk.event.view({}, "abc123...");
 
-const traces = await sdk.traces.list({ target: "acme/frontend" });
-const trace = await sdk.traces.get({ traceId: "abc123..." });
+const traces = await sdk.trace.list({ orgProject: "acme/frontend" });
+const trace = await sdk.trace.view({}, "abc123...");
 
-const spans = await sdk.spans.list({ target: "acme/frontend" });
+const spans = await sdk.span.list({}, "acme/frontend");
+```
+
+### Dashboards
+
+```typescript
+const dashboards = await sdk.dashboard.list({}, "acme/");
+const dashboard = await sdk.dashboard.view({}, "acme/", "my-dashboard");
+
+// Nested widget commands
+await sdk.dashboard.widget.add(
+  { display: "line", query: "count" },
+  "acme/", "my-dashboard"
+);
 ```
 
 ### Teams
 
 ```typescript
-const teams = await sdk.teams.list({ target: "acme/" });
+const teams = await sdk.team.list({ orgProject: "acme/" });
+```
+
+### Authentication
+
+```typescript
+await sdk.auth.login();
+await sdk.auth.status();
+const whoami = await sdk.auth.whoami();
 ```
 
 The typed SDK invokes command handlers directly — bypassing CLI string parsing
 for zero overhead beyond the command's own logic.
 
+## Escape Hatch: `run()`
+
+For commands not easily expressed through the typed API, or when you want to
+pass raw CLI flags, use `sdk.run()`:
+
+```typescript
+// Run any CLI command — returns parsed JSON by default
+const version = await sdk.run("--version");
+const issues = await sdk.run("issue", "list", "-l", "5");
+const help = await sdk.run("help", "issue");
+```
+
 ## Authentication
 
 The `token` option provides an auth token for the current invocation. When
@@ -93,65 +128,54 @@ omitted, it falls back to environment variables and stored credentials:
 
 ```typescript
 // Explicit token
-const orgs = await sentry("org", "list", { token: "sntrys_..." });
+const sdk = createSentrySDK({ token: "sntrys_..." });
 
 // Or set the env var — it's picked up automatically
 process.env.SENTRY_AUTH_TOKEN = "sntrys_...";
-const orgs = await sentry("org", "list");
+const sdk = createSentrySDK();
 ```
 
 ## Options
 
-All options are optional. Pass them as the last argument:
+All options are optional. Pass them when creating the SDK:
 
 ```typescript
-await sentry("issue", "list", { token: "...", text: true, cwd: "/my/project" });
+const sdk = createSentrySDK({ token: "...", text: true, cwd: "/my/project" });
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `token` | `string` | Auto-detected | Auth token for this invocation |
-| `text` | `boolean` | `false` | Return human-readable text instead of parsed JSON |
+| `text` | `boolean` | `false` | Return human-readable text instead of parsed JSON (`run()` only) |
 | `cwd` | `string` | `process.cwd()` | Working directory for DSN auto-detection |
 
 ## Return Values
 
-By default, commands that support JSON output return a **parsed JavaScript object**
-— no serialization overhead. Commands without JSON support (like `help` or `--version`)
-return a trimmed string.
+Typed SDK methods return **parsed JavaScript objects** with zero serialization
+overhead (via zero-copy capture). The `run()` escape hatch returns parsed JSON
+by default, or a trimmed string for commands without JSON support.
 
 ```typescript
-// Data commands → parsed object
-const issues = await sentry("issue", "list");
-// { data: [...], hasMore: true, nextCursor: "..." }
-
-// Single-entity commands → parsed object
-const issue = await sentry("issue", "view", "PROJ-123");
-// { id: "123", title: "Bug", status: "unresolved", ... }
+// Typed methods → typed return
+const issues = await sdk.issue.list({ orgProject: "acme/frontend" });
+// IssueListResult type with known fields
 
-// Text commands → string
-const version = await sentry("--version");
+// run() → parsed JSON or string
+const version = await sdk.run("--version");
 // "sentry 0.21.0"
 ```
 
-### Text Mode
-
-Pass `{ text: true }` to get the human-readable output as a string:
-
-```typescript
-const text = await sentry("issue", "list", { text: true });
-// "ID       TITLE              STATUS\n..."
-```
-
 ## Error Handling
 
-Commands that exit with a non-zero code throw a `SentryError`:
+Commands that fail throw a `SentryError`:
 
 ```typescript
-import sentry, { SentryError } from "sentry";
+import createSentrySDK, { SentryError } from "sentry";
+
+const sdk = createSentrySDK();
 
 try {
-  await sentry("issue", "view", "NONEXISTENT-1");
+  await sdk.issue.view({ issue: "NONEXISTENT-1" });
 } catch (err) {
   if (err instanceof SentryError) {
     console.error(err.message);   // Clean error message (no ANSI codes)
@@ -171,21 +195,21 @@ copy of the environment. This means:
 - Auth tokens passed via `token` don't leak to subsequent calls
 
 :::note
-Concurrent calls to `sentry()` are not supported in the current version.
+Concurrent calls are not supported in the current version.
 Calls should be sequential (awaited one at a time).
 :::
 
 ## Comparison with Subprocess
 
-| | Library (`sentry()`) | Subprocess (`child_process`) |
+| | Library (`createSentrySDK()`) | Subprocess (`child_process`) |
 |---|---|---|
 | **Startup** | ~0ms (in-process) | ~200ms (process spawn + init) |
 | **Output** | Parsed object (zero-copy) | String (needs JSON.parse) |
 | **Errors** | `SentryError` with typed fields | Exit code + stderr string |
 | **Auth** | `token` option or env vars | Env vars only |
-| **Node.js** | ≥22 required | Any version |
+| **Node.js** | >=22 required | Any version |
 
 ## Requirements
 
-- **Node.js ≥ 22** (required for `node:sqlite`)
+- **Node.js >= 22** (required for `node:sqlite`)
 - Or **Bun** (any recent version)

script/bundle.ts

@@ -23,8 +23,8 @@ const BUN_SQLITE_FILTER = /^bun:sqlite$/;
 const ANY_FILTER = /.*/;
 
 // Regex patterns for SDK type extraction
-/** Matches `export type FooParams = { ... };` blocks (multiline via dotAll) */
-const EXPORTED_TYPE_BLOCK_RE = /^export type \w+Params = \{[^}]*\};/gms;
+/** Matches `export type Foo = { ... };` blocks (Params + Result, multiline via dotAll) */
+const EXPORTED_TYPE_BLOCK_RE = /^export type \w+ = \{[^}]*\};/gms;
 
 /** Matches method lines: `name: (params): Promise<T> =>` */
 const SDK_METHOD_RE = /^(\s+)(\w+): \(([^)]*)\): (Promise<.+>)\s*=>$/;
@@ -340,13 +340,12 @@ export declare class SentryError extends Error {
   constructor(message: string, exitCode: number, stderr: string);
 }
 
-export declare function sentry(...args: string[]): Promise<unknown>;
-export declare function sentry(...args: [...string[], SentryOptions]): Promise<unknown>;
-
-export { sentry };
-export default sentry;
+export declare function createSentrySDK(options?: SentryOptions): SentrySDK & {
+  /** Run an arbitrary CLI command (escape hatch). */
+  run(...args: string[]): Promise<unknown>;
+};
 
-export declare function createSentrySDK(options?: SentryOptions): SentrySDK;
+export default createSentrySDK;
 `;
 
 // Extract parameter types and SentrySDK type from sdk.generated.ts.