feat(doctor): add sentry doctor

apps/cli-docs/src/content/docs/contributing.md

@@ -83,6 +83,7 @@ cli/
 │   │   ├── trace/       # list, logs, view
 │   │   ├── trial/       # list, start
 │   │   ├── api.ts       # Make an authenticated API request
+│   │   ├── doctor.ts    # Check whether Sentry is correctly set up and actually working
 │   │   ├── explore.ts   # Query aggregate event data (Explore)
 │   │   ├── help.ts      # Help command
 │   │   ├── info.ts      # Print configuration and verify authentication

apps/cli-docs/src/fragments/commands/doctor.md

@@ -0,0 +1,52 @@
+## Examples
+
+```bash
+# Read-only health check
+sentry doctor
+
+# Machine-readable report (every result, including passes)
+sentry doctor --json
+
+# Send a test event and confirm ingest (a write)
+sentry doctor --send-test-event
+```
+
+`--json` is this run's results (`id`, `status`, `detail`, optional `evidence` / `remediation`) plus `capture` and `server`. It is not a catalog of what each check means.
+
+`skip` = could not tell. `warn` never fails the run. Only `fail` exits 1.
+
+## Checks
+
+### Server (what Sentry knows)
+
+| Check | Means |
+|---|---|
+| `dsn.present` | A DSN exists somewhere in the project |
+| `dsn.placeholder` | That DSN is not the docs example |
+| `dsn.conflict` | More than one distinct DSN — events may split |
+| `dsn.resolves` | The DSN maps to a project you can access |
+| `project.first_event` | That project has received at least one event, ever |
+| `project.last_event` | Recent activity (warns if last issue is >30 days old) |
+| `project.key_active` | This DSN's key still exists and is enabled |
+| `project.environments` | Events are tagged with an environment |
+| `release.attribution` | Events are tied to a release |
+| `artifacts.uploaded` | Source maps / debug files exist on the project |
+
+### Local (what the repo says)
+
+| Check | Means |
+|---|---|
+| `init.present` | An init call (or platform auto-init) exists |
+| `config.dsn_set` | That init actually sets a DSN |
+| `config.environment` | `environment` is set (else local + prod mix) |
+| `config.debug` | `debug: true` is not hardcoded on |
+| `config.sample_rate` | Trace sample rate isn't 0 or 1.0 |
+| `build.upload_configured` | A bundler / dSYM / Proguard upload plugin is present |
+| `capture.complete` | Doctor finished scanning the tree |
+
+### Opt-in / extra
+
+| Check | Means |
+|---|---|
+| `live.roundtrip` | `--send-test-event`: ingest accepted it, and (if DSN resolved) search found it |
+| `judge.*` | LLM pass over captured config; skip if no model |

packages/cli/package.json

@@ -85,7 +85,7 @@
     "check:stale-refs": "pnpm tsx script/check-stale-references.ts"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.39.0",
+    "@anthropic-ai/sdk": "^0.117.1",
     "@biomejs/biome": "2.3.8",
     "@clack/prompts": "0.11.0",
     "@hono/node-server": "^2.0.10",

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

@@ -460,6 +460,14 @@ Work with debug information files
 
 → Full flags and examples: `references/debug-files.md`
 
+### Doctor
+
+Check whether Sentry is correctly set up and actually working
+
+- `sentry doctor` — Check whether Sentry is correctly set up and actually working
+
+→ Full flags and examples: `references/doctor.md`
+
 ### Dashboard
 
 Manage Sentry dashboards

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/doctor.md

@@ -0,0 +1,35 @@
+---
+name: sentry-cli-doctor
+version: 0.45.0-dev.0
+description: Check whether Sentry is correctly set up and actually working
+requires:
+  bins: ["sentry"]
+  auth: true
+---
+
+# Doctor Commands
+
+Check whether Sentry is correctly set up and actually working
+
+### `sentry doctor`
+
+Check whether Sentry is correctly set up and actually working
+
+**Flags:**
+- `--sendTestEvent - Send a synthetic event to the configured DSN and confirm it arrives (a write)`
+- `--fix - After reporting, run the setup workflow to produce a fix plan`
+
+**Examples:**
+
+```bash
+# Read-only health check
+sentry doctor
+
+# Machine-readable report (every result, including passes)
+sentry doctor --json
+
+# Send a test event and confirm ingest (a write)
+sentry doctor --send-test-event
+```
+
+All commands also support `--json`, `--fields`, `--help`, `--log-level`, and `--verbose` flags.

packages/cli/src/app.ts

@@ -19,6 +19,7 @@ import { dartSymbolMapRoute } from "./commands/dart-symbol-map/index.js";
 import { dashboardRoute } from "./commands/dashboard/index.js";
 import { listCommand as dashboardListCommand } from "./commands/dashboard/list.js";
 import { debugFilesRoute } from "./commands/debug-files/index.js";
+import { doctorCommand } from "./commands/doctor.js";
 import { docsRoute } from "./commands/docs/index.js";
 import { eventRoute } from "./commands/event/index.js";
 import { listCommand as eventListCommand } from "./commands/event/list.js";
@@ -118,6 +119,7 @@ export const routes = buildRouteMap({
     "agent-conversation": conversationRoute,
     "dart-symbol-map": dartSymbolMapRoute,
     "debug-files": debugFilesRoute,
+    doctor: doctorCommand,
     dashboard: dashboardRoute,
     docs: docsRoute,
     org: orgRoute,

packages/cli/src/commands/doctor.ts

@@ -0,0 +1,127 @@
+/**
+ * `sentry doctor` — is Sentry actually working in this project?
+ *
+ * Four stages, only the first two do I/O. `auth: false` so an unauthenticated
+ * run reports "unauthorized" as a finding rather than crashing, following the
+ * `info.ts` pattern.
+ */
+
+import type { SentryContext } from "../context.js";
+import { buildCommand } from "../lib/command.js";
+import { CLI_VERSION } from "../lib/constants.js";
+import { capture } from "../lib/doctor/capture.js";
+import { REGISTRY } from "../lib/doctor/checks/index.js";
+import {
+  buildReport,
+  type DoctorReport,
+  exitCodeFor,
+  formatDoctorReport,
+} from "../lib/doctor/render.js";
+import { resolveServerFacts } from "../lib/doctor/resolve.js";
+import { runChecks } from "../lib/doctor/types.js";
+import { CommandOutput } from "../lib/formatters/output.js";
+import { withProgress } from "../lib/polling.js";
+
+export type DoctorFlags = {
+  sendTestEvent: boolean;
+  fix: boolean;
+  json?: boolean;
+};
+
+/** The whole command, minus presentation — so tests never touch the CLI. */
+export async function runDoctor(
+  ctx: SentryContext,
+  flags: Partial<DoctorFlags> = {},
+  setMessage: (msg: string) => void = () => {
+    /* tests / JSON mode */
+  }
+): Promise<{ report: DoctorReport; exitCode: 0 | 1 }> {
+  const started = Date.now();
+
+  setMessage("Scanning this project...");
+  const captured = await capture(ctx.cwd);
+  setMessage("Asking Sentry...");
+  const server = await resolveServerFacts(captured);
+  setMessage("Checking configuration...");
+  const results = runChecks(REGISTRY, { capture: captured, server });
+
+  const { judge } = await import("../lib/doctor/judge.js");
+  results.push(...(await judge(captured)));
+
+  if (flags.sendTestEvent) {
+    setMessage("Sending a test event...");
+    const { liveRoundtripCheck } = await import("../lib/doctor/live.js");
+    results.push(await liveRoundtripCheck(captured, server));
+  } else {
+    results.push({
+      id: "live.roundtrip",
+      status: "skip",
+      detail: "Not requested. Run with --send-test-event.",
+    });
+  }
+
+  return {
+    report: buildReport({
+      capture: captured,
+      server,
+      results,
+      cliVersion: CLI_VERSION,
+      timestamp: new Date(started).toISOString(),
+      elapsedMs: Date.now() - started,
+    }),
+    exitCode: exitCodeFor(results),
+  };
+}
+
+export const doctorCommand = buildCommand({
+  // Runs unauthenticated; a missing session becomes a finding, not a crash.
+  auth: false,
+  docs: {
+    brief: "Check whether Sentry is correctly set up and actually working",
+    fullDescription:
+      "Inspects this project's Sentry configuration, asks Sentry what it has " +
+      "actually received, and reports what is wrong along with instructions " +
+      "to fix it. Reads only, unless you pass --send-test-event.",
+  },
+  output: { human: formatDoctorReport },
+  parameters: {
+    flags: {
+      sendTestEvent: {
+        kind: "boolean",
+        brief:
+          "Send a synthetic event to the configured DSN and confirm it arrives (a write)",
+        default: false,
+      },
+      fix: {
+        kind: "boolean",
+        brief: "After reporting, run the setup workflow to produce a fix plan",
+        default: false,
+      },
+    },
+    positional: { kind: "tuple", parameters: [] },
+  },
+  async *func(this: SentryContext, flags: DoctorFlags) {
+    const { report, exitCode } = await withProgress(
+      { message: "Scanning this project...", json: flags.json },
+      (setMessage) => runDoctor(this, flags, setMessage)
+    );
+
+    yield new CommandOutput(report);
+
+    const { offerSupportExport } = await import("../lib/doctor/report.js");
+    await offerSupportExport(report, flags.json);
+
+    if (
+      flags.fix &&
+      report.results.some((r) => r.status === "fail" || r.status === "warn")
+    ) {
+      const { runFix } = await import("../lib/doctor/fix.js");
+      await runFix(this, report);
+    }
+
+    // Set last: a broken project is a finding, and the report is the payload.
+    this.process.exitCode = exitCode;
+  },
+});
+
+export default doctorCommand;