feat(dashboard): add widget add, edit, and delete commands (#407)

## Summary
- Add `sentry dashboard widget add` — add a widget with inline
`--display`/`--query`/`--where`/`--group-by`/`--sort`/`--limit` flags
- Add `sentry dashboard widget edit` — edit an existing widget by
`--index` or `--title`, merging only changed fields
- Add `sentry dashboard widget delete` — remove a widget by `--index` or
`--title`
- Add widget formatters (`formatWidgetAdded`, `formatWidgetDeleted`,
`formatWidgetEdited`)

All widget commands use the GET-modify-PUT pattern with server field
stripping and auto-layout for new widgets.

Stacked on #406.

## Test plan
- [x] `bun run typecheck` — no new type errors
- [x] `bun run lint` — passes
- [x] `bun test test/types/dashboard.test.ts` — 53 tests pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

src/commands/dashboard/create.ts

@@ -138,7 +138,9 @@ export const createCommand = buildCommand({
       "Examples:\n" +
       "  sentry dashboard create 'My Dashboard'\n" +
       "  sentry dashboard create my-org/ 'My Dashboard'\n" +
-      "  sentry dashboard create my-org/my-project 'My Dashboard'",
+      "  sentry dashboard create my-org/my-project 'My Dashboard'\n\n" +
+      "Add widgets after creation with:\n" +
+      '  sentry dashboard widget add <dashboard> "My Widget" --display line --query count',
   },
   output: {
     human: formatDashboardCreated,
@@ -162,10 +164,12 @@ export const createCommand = buildCommand({
 
     const dashboard = await createDashboard(orgSlug, {
       title,
+      widgets: [],
       projects: projectIds.length > 0 ? projectIds : undefined,
     });
     const url = buildDashboardUrl(orgSlug, dashboard.id);
 
     yield new CommandOutput({ ...dashboard, url } as CreateResult);
+    return { hint: `Dashboard: ${url}` };
   },
 });

src/commands/dashboard/index.ts

@@ -2,12 +2,14 @@ import { buildRouteMap } from "@stricli/core";
 import { createCommand } from "./create.js";
 import { listCommand } from "./list.js";
 import { viewCommand } from "./view.js";
+import { widgetRoute } from "./widget/index.js";
 
 export const dashboardRoute = buildRouteMap({
   routes: {
     list: listCommand,
     view: viewCommand,
     create: createCommand,
+    widget: widgetRoute,
   },
   docs: {
     brief: "Manage Sentry dashboards",
@@ -16,7 +18,8 @@ export const dashboardRoute = buildRouteMap({
       "Commands:\n" +
       "  list     List dashboards\n" +
       "  view     View a dashboard\n" +
-      "  create   Create a dashboard",
+      "  create   Create a dashboard\n" +
+      "  widget   Manage dashboard widgets (add, edit, delete)",
     hideRoute: {},
   },
 });

src/commands/dashboard/resolve.ts

@@ -10,6 +10,27 @@ import type { parseOrgProjectArg } from "../../lib/arg-parsing.js";
 import { ContextError, ValidationError } from "../../lib/errors.js";
 import { resolveOrg } from "../../lib/resolve-target.js";
 import { isAllDigits } from "../../lib/utils.js";
+import {
+  type DashboardWidget,
+  DISPLAY_TYPES,
+  parseAggregate,
+  parseSortExpression,
+  parseWidgetInput,
+  prepareWidgetQueries,
+  validateAggregateNames,
+  WIDGET_TYPES,
+} from "../../types/dashboard.js";
+
+/** Shared widget query flags used by `add` and `edit` commands */
+export type WidgetQueryFlags = {
+  readonly display?: string;
+  readonly dataset?: string;
+  readonly query?: string[];
+  readonly where?: string;
+  readonly "group-by"?: string[];
+  readonly sort?: string;
+  readonly limit?: number;
+};
 
 /**
  * Resolve org slug from a parsed org/project target argument.
@@ -119,3 +140,114 @@ export async function resolveDashboardId(
 
   return match.id;
 }
+
+/**
+ * Resolve widget index from --index or --title flags.
+ *
+ * @param widgets - Array of widgets in the dashboard
+ * @param index - Explicit 0-based widget index
+ * @param title - Widget title to match
+ * @returns Resolved widget index
+ */
+export function resolveWidgetIndex(
+  widgets: DashboardWidget[],
+  index: number | undefined,
+  title: string | undefined
+): number {
+  if (index !== undefined) {
+    if (index < 0 || index >= widgets.length) {
+      throw new ValidationError(
+        `Widget index ${index} out of range (dashboard has ${widgets.length} widgets).`,
+        "index"
+      );
+    }
+    return index;
+  }
+  const lowerTitle = (title ?? "").toLowerCase();
+  const matchIndex = widgets.findIndex(
+    (w) => w.title.toLowerCase() === lowerTitle
+  );
+  if (matchIndex === -1) {
+    throw new ValidationError(
+      `No widget with title '${title}' found in dashboard.`,
+      "title"
+    );
+  }
+  return matchIndex;
+}
+
+/**
+ * Build a widget from user-provided flag values.
+ *
+ * Shared between `dashboard widget add` and `dashboard widget edit`.
+ * Parses aggregate shorthand, sort expressions, and validates via Zod schema.
+ *
+ * @param opts - Widget configuration from parsed flags
+ * @returns Validated widget with computed query fields
+ */
+export function buildWidgetFromFlags(opts: {
+  title: string;
+  display: string;
+  dataset?: string;
+  query?: string[];
+  where?: string;
+  groupBy?: string[];
+  sort?: string;
+  limit?: number;
+}): DashboardWidget {
+  const aggregates = (opts.query ?? ["count"]).map(parseAggregate);
+  validateAggregateNames(aggregates, opts.dataset);
+
+  const columns = opts.groupBy ?? [];
+  // Auto-default orderby to first aggregate descending when group-by is used.
+  // Without this, chart widgets (line/area/bar) with group-by + limit error
+  // because the dashboard can't determine which top N groups to display.
+  let orderby = opts.sort ? parseSortExpression(opts.sort) : undefined;
+  if (columns.length > 0 && !orderby && aggregates.length > 0) {
+    orderby = `-${aggregates[0]}`;
+  }
+
+  const raw = {
+    title: opts.title,
+    displayType: opts.display,
+    ...(opts.dataset && { widgetType: opts.dataset }),
+    queries: [
+      {
+        aggregates,
+        columns,
+        conditions: opts.where ?? "",
+        ...(orderby && { orderby }),
+        name: "",
+      },
+    ],
+    ...(opts.limit !== undefined && { limit: opts.limit }),
+  };
+  return prepareWidgetQueries(parseWidgetInput(raw));
+}
+
+/**
+ * Validate --display and --dataset flag values against known enums.
+ *
+ * @param display - Display type flag value
+ * @param dataset - Dataset flag value
+ */
+export function validateWidgetEnums(display?: string, dataset?: string): void {
+  if (
+    display &&
+    !DISPLAY_TYPES.includes(display as (typeof DISPLAY_TYPES)[number])
+  ) {
+    throw new ValidationError(
+      `Invalid --display value "${display}".\nValid display types: ${DISPLAY_TYPES.join(", ")}`,
+      "display"
+    );
+  }
+  if (
+    dataset &&
+    !WIDGET_TYPES.includes(dataset as (typeof WIDGET_TYPES)[number])
+  ) {
+    throw new ValidationError(
+      `Invalid --dataset value "${dataset}".\nValid datasets: ${WIDGET_TYPES.join(", ")}`,
+      "dataset"
+    );
+  }
+}

src/commands/dashboard/view.ts

@@ -16,6 +16,7 @@ import {
   FRESH_ALIASES,
   FRESH_FLAG,
 } from "../../lib/list-command.js";
+import { withProgress } from "../../lib/polling.js";
 import { buildDashboardUrl } from "../../lib/sentry-urls.js";
 import type { DashboardDetail } from "../../types/dashboard.js";
 import {
@@ -87,8 +88,12 @@ export const viewCommand = buildCommand({
       return;
     }
 
-    const dashboard = await getDashboard(orgSlug, dashboardId);
+    const dashboard = await withProgress(
+      { message: "Fetching dashboard...", json: flags.json },
+      () => getDashboard(orgSlug, dashboardId)
+    );
 
     yield new CommandOutput({ ...dashboard, url } as ViewResult);
+    return { hint: `Dashboard: ${url}` };
   },
 });