feat(init): add init command for guided Sentry project setup

.github/workflows/init-eval.yml

@@ -0,0 +1,48 @@
+name: Init Eval
+
+on:
+  workflow_dispatch:
+    inputs:
+      platform:
+        description: "Platform to evaluate (or 'all')"
+        required: true
+        default: all
+        type: choice
+        options:
+          - all
+          - express
+          - nextjs
+          - python-fastapi
+          - python-flask
+          - react-vite
+          - sveltekit
+
+jobs:
+  eval:
+    name: Eval ${{ matrix.platform }}
+    runs-on: ubuntu-latest
+    environment: init-eval
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: ${{ inputs.platform == 'all'
+          && fromJson('["express","nextjs","python-fastapi","python-flask","react-vite","sveltekit"]')
+          || fromJson(format('["{0}"]', inputs.platform)) }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/cache@v4
+        id: cache
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('bun.lock', 'patches/**') }}
+      - if: steps.cache.outputs.cache-hit != 'true'
+        run: bun install --frozen-lockfile
+      - name: Run eval
+        env:
+          MASTRA_API_URL: ${{ secrets.MASTRA_API_URL }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: bun test ./test/init-eval/${{ matrix.platform }}.eval.test.ts --timeout 600000

.gitignore

@@ -1,5 +1,6 @@
 # dependencies (bun install)
 node_modules
+package-lock.json
 
 # output
 out
@@ -34,6 +35,7 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .cache
 *.tsbuildinfo
 .turbo
+.mastra
 
 # docs
 docs/dist

biome.jsonc

@@ -2,7 +2,7 @@
   "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
   "extends": ["ultracite/core"],
   "files": {
-    "includes": ["!docs"]
+    "includes": ["!docs", "!test/init-eval/templates"]
   },
   "javascript": {
     "globals": ["Bun"]

package.json

@@ -21,12 +21,15 @@
     "test:unit": "bun test test/lib test/commands test/types --coverage --coverage-reporter=lcov",
     "test:isolated": "bun test test/isolated",
     "test:e2e": "bun test test/e2e",
+    "test:init-eval": "bun test test/init-eval --timeout 600000",
     "generate:skill": "bun run script/generate-skill.ts",
     "check:skill": "bun run script/check-skill.ts",
     "check:deps": "bun run script/check-no-deps.ts"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
     "@biomejs/biome": "2.3.8",
+    "@mastra/client-js": "^1.4.0",
     "@sentry/api": "^0.1.0",
     "@sentry/bun": "10.39.0",
     "@sentry/esbuild-plugin": "^2.23.0",
@@ -42,6 +45,7 @@
     "esbuild": "^0.25.0",
     "fast-check": "^4.5.3",
     "ignore": "^7.0.5",
+    "openai": "^6.22.0",
     "p-limit": "^7.2.0",
     "pretty-ms": "^9.3.0",
     "qrcode-terminal": "^0.12.0",

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

@@ -571,6 +571,20 @@ View details of a specific trace
 - `-w, --web - Open in browser`
 - `--spans <value> - Span tree depth limit (number, "all" for unlimited, "no" to disable) - (default: "3")`
 
+### Init
+
+Initialize Sentry in your project
+
+#### `sentry init <directory>`
+
+Initialize Sentry in your project
+
+**Flags:**
+- `--force - Continue even if Sentry is already installed`
+- `-y, --yes - Non-interactive mode (accept defaults)`
+- `--dry-run - Preview changes without applying them`
+- `--features <value> - Comma-separated features: errors,tracing,logs,replay,metrics`
+
 ### Issues
 
 List issues in a project

src/app.ts

@@ -11,6 +11,7 @@ import { authRoute } from "./commands/auth/index.js";
 import { cliRoute } from "./commands/cli/index.js";
 import { eventRoute } from "./commands/event/index.js";
 import { helpCommand } from "./commands/help.js";
+import { initCommand } from "./commands/init.js";
 import { issueRoute } from "./commands/issue/index.js";
 import { listCommand as issueListCommand } from "./commands/issue/list.js";
 import { logRoute } from "./commands/log/index.js";
@@ -43,6 +44,7 @@ export const routes = buildRouteMap({
     event: eventRoute,
     log: logRoute,
     trace: traceRoute,
+    init: initCommand,
     api: apiCommand,
     issues: issueListCommand,
     orgs: orgListCommand,

src/commands/init.ts

@@ -0,0 +1,87 @@
+/**
+ * sentry init
+ *
+ * Initialize Sentry in a project using the remote wizard workflow.
+ * Communicates with the Mastra API via suspend/resume to perform
+ * local filesystem operations and interactive prompts.
+ */
+
+import path from "node:path";
+import type { SentryContext } from "../context.js";
+import { buildCommand } from "../lib/command.js";
+import { runWizard } from "../lib/init/wizard-runner.js";
+
+type InitFlags = {
+  readonly force: boolean;
+  readonly yes: boolean;
+  readonly "dry-run": boolean;
+  readonly features?: string;
+};
+
+export const initCommand = buildCommand<InitFlags, [string?], SentryContext>({
+  docs: {
+    brief: "Initialize Sentry in your project",
+    fullDescription:
+      "Runs the Sentry setup wizard to detect your project's framework, " +
+      "install the SDK, and configure error monitoring. Uses a remote " +
+      "workflow that coordinates local file operations through the CLI.",
+  },
+  parameters: {
+    positional: {
+      kind: "tuple",
+      parameters: [
+        {
+          placeholder: "directory",
+          brief: "Project directory (default: current directory)",
+          parse: String,
+          optional: true,
+        },
+      ],
+    },
+    flags: {
+      force: {
+        kind: "boolean",
+        brief: "Continue even if Sentry is already installed",
+        default: false,
+      },
+      yes: {
+        kind: "boolean",
+        brief: "Non-interactive mode (accept defaults)",
+        default: false,
+      },
+      "dry-run": {
+        kind: "boolean",
+        brief: "Preview changes without applying them",
+        default: false,
+      },
+      features: {
+        kind: "parsed",
+        parse: String,
+        brief: "Comma-separated features: errors,tracing,logs,replay,metrics",
+        optional: true,
+        placeholder: "list",
+      },
+    },
+    aliases: {
+      y: "yes",
+    },
+  },
+  async func(this: SentryContext, flags: InitFlags, directory?: string) {
+    const targetDir = directory ? path.resolve(this.cwd, directory) : this.cwd;
+    const featuresList = flags.features
+      ?.split(",")
+      .map((f) => f.trim())
+      .filter(Boolean);
+
+    await runWizard({
+      directory: targetDir,
+      force: flags.force,
+      yes: flags.yes,
+      dryRun: flags["dry-run"],
+      features: featuresList,
+      stdout: this.stdout,
+      stderr: this.stderr,
+      stdin: this.stdin,
+    });
+  },
+});

src/lib/help.ts

@@ -36,7 +36,7 @@ const BANNER_GRADIENT = [
  * Format the banner with a vertical gradient effect.
  * Each row gets progressively darker purple.
  */
-function formatBanner(): string {
+export function formatBanner(): string {
   return BANNER_ROWS.map((row, i) => {
     const color = BANNER_GRADIENT[i] ?? "#B4A4DE";
     return chalk.hex(color)(row);

src/lib/init/clack-utils.ts

@@ -0,0 +1,73 @@
+/**
+ * Clack Utilities
+ *
+ * Shared helpers for the clack-based init wizard UI.
+ */
+
+import { cancel, isCancel } from "@clack/prompts";
+import { SENTRY_DOCS_URL } from "./constants.js";
+
+export class WizardCancelledError extends Error {
+  constructor() {
+    super("Setup cancelled.");
+    this.name = "WizardCancelledError";
+  }
+}
+
+export function abortIfCancelled<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancel(`Setup cancelled. Visit ${SENTRY_DOCS_URL} to set up manually.`);
+    throw new WizardCancelledError();
+  }
+  return value as T;
+}
+
+export const FEATURE_INFO: Record<string, { label: string; hint: string }> = {
+  errorMonitoring: {
+    label: "Error Monitoring",
+    hint: "Automatic error and crash reporting",
+  },
+  performanceMonitoring: {
+    label: "Performance Monitoring",
+    hint: "Transaction and span tracing",
+  },
+  sessionReplay: {
+    label: "Session Replay",
+    hint: "Visual replay of user sessions",
+  },
+  profiling: {
+    label: "Profiling",
+    hint: "Code-level performance insights",
+  },
+  logs: { label: "Logging", hint: "Structured log ingestion" },
+  metrics: { label: "Custom Metrics", hint: "Track custom business metrics" },
+  sourceMaps: {
+    label: "Source Maps",
+    hint: "See original source code in production errors",
+  },
+};
+
+export function featureLabel(id: string): string {
+  return FEATURE_INFO[id]?.label ?? id;
+}
+
+export function featureHint(id: string): string | undefined {
+  return FEATURE_INFO[id]?.hint;
+}
+
+export const STEP_LABELS: Record<string, string> = {
+  "discover-context": "Analyzing project structure",
+  "select-target-app": "Selecting target application",
+  "resolve-dir": "Resolving project directory",
+  "check-existing-sentry": "Checking for existing Sentry installation",
+  "detect-platform": "Detecting platform and framework",
+  "ensure-sentry-project": "Setting up Sentry project",
+  "select-features": "Selecting features",
+  "determine-pm": "Detecting package manager",
+  "install-deps": "Installing dependencies",
+  "plan-codemods": "Planning code modifications",
+  "apply-codemods": "Applying code modifications",
+  "verify-changes": "Verifying changes",
+  "add-example-trigger": "Example error trigger",
+  "open-sentry-ui": "Finishing up",
+};

src/lib/init/constants.ts

@@ -0,0 +1,11 @@
+export const MASTRA_API_URL =
+  process.env.SENTRY_WIZARD_API_URL ??
+  "http://sentry-init-agent.getsentry.workers.dev";
+
+export const WORKFLOW_ID = "sentry-wizard";
+
+export const SENTRY_DOCS_URL = "https://docs.sentry.io/platforms/";
+
+export const MAX_FILE_BYTES = 262_144; // 256KB per file
+export const MAX_STDOUT_BYTES = 65_536; // 64KB stdout/stderr truncation
+export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000; // 2 minutes