feat(commands): add shared helpers and buildDeleteCommand for mutation commands (#639)

## Summary

- Add `src/lib/mutate-command.ts` with shared infrastructure for
create/delete commands, paralleling `list-command.ts` for list commands
- Refactor existing create/delete commands to use the new shared helpers
- Add `--yes`/`--force`/`--dry-run` flags to `dashboard widget delete`
via `buildDeleteCommand`

## What's in `mutate-command.ts`

**Level A — Shared flag constants:** `DRY_RUN_FLAG`, `YES_FLAG`,
`FORCE_FLAG`, plus spreadable bundles
(`DESTRUCTIVE_FLAGS`/`DESTRUCTIVE_ALIASES`, `DRY_RUN_ALIASES`)

**Level B — Shared utilities:** `isConfirmationBypassed()`,
`guardNonInteractive()`, `confirmByTyping()`, `requireExplicitTarget()`

**Level C — `buildDeleteCommand()` wrapper:** Drop-in replacement for
`buildCommand` that auto-injects `--yes`/`--force`/`--dry-run` flags +
aliases and runs a non-interactive safety guard as a pre-hook (analogous
to `applyFreshFlag()` in `buildListCommand`). Options to skip specific
injections (`noForceFlag`, `noDryRunFlag`, `noNonInteractiveGuard`).

## Refactored commands

| Command | Change |
|---------|--------|
| `project delete` | Uses `buildDeleteCommand`, `confirmByTyping`,
`requireExplicitTarget` (no behavior change) |
| `project create` | Uses `DRY_RUN_FLAG`/`DRY_RUN_ALIASES` (no behavior
change) |
| `dashboard widget delete` | Uses `buildDeleteCommand` with
`noNonInteractiveGuard` (reversible op), gains `--dry-run` preview
support |

---------

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

Author: BYK

AGENTS.md

@@ -288,6 +288,50 @@ All non-trivial human output must use the markdown rendering pipeline:
 
 Reference: `formatters/trace.ts` (`formatAncestorChain`), `formatters/human.ts` (`plainSafeMuted`)
 
+### Create & Delete Command Standards
+
+Mutation (create/delete) commands use shared infrastructure from `src/lib/mutate-command.ts`,
+paralleling `list-command.ts` for list commands.
+
+**Delete commands** MUST use `buildDeleteCommand()` instead of `buildCommand()`. It:
+1. Auto-injects `--yes`, `--force`, `--dry-run` flags with `-y`, `-f`, `-n` aliases
+2. Runs a non-interactive safety guard before `func()` — refuses to proceed if
+   stdin is not a TTY and `--yes`/`--force` was not passed (dry-run bypasses)
+3. Options to skip specific injections (`noForceFlag`, `noDryRunFlag`, `noNonInteractiveGuard`)
+
+```typescript
+import { buildDeleteCommand, confirmByTyping, isConfirmationBypassed, requireExplicitTarget } from "../../lib/mutate-command.js";
+
+export const deleteCommand = buildDeleteCommand({
+  // Same args as buildCommand — flags/aliases auto-injected
+  async *func(this: SentryContext, flags, target) {
+    requireExplicitTarget(parsed, "Entity", "sentry entity delete <target>");
+    if (flags["dry-run"]) { yield preview; return; }
+    if (!isConfirmationBypassed(flags)) {
+      if (!await confirmByTyping(expected, promptMessage)) return;
+    }
+    await doDelete();
+  },
+});
+```
+
+**Create commands** import `DRY_RUN_FLAG` and `DRY_RUN_ALIASES` for consistent dry-run support:
+
+```typescript
+import { DRY_RUN_FLAG, DRY_RUN_ALIASES } from "../../lib/mutate-command.js";
+
+// In parameters:
+flags: { "dry-run": DRY_RUN_FLAG, team: { ... } },
+aliases: { ...DRY_RUN_ALIASES, t: "team" },
+```
+
+**Key utilities** in `mutate-command.ts`:
+- `isConfirmationBypassed(flags)` — true if `--yes` or `--force` is set
+- `guardNonInteractive(flags)` — throws in non-interactive mode without `--yes`
+- `confirmByTyping(expected, message)` — type-out confirmation prompt
+- `requireExplicitTarget(parsed, entityType, usage)` — blocks auto-detect for safety
+- `DESTRUCTIVE_FLAGS` / `DESTRUCTIVE_ALIASES` — spreadable bundles for manual use
+
 ### List Command Pagination
 
 All list commands with API pagination MUST use the shared cursor-stack

docs/src/content/docs/commands/dashboard.md

@@ -126,6 +126,9 @@ Delete a widget from a dashboard
 |--------|-------------|
 | `-i, --index <index>` | Widget index (0-based) |
 | `-t, --title <title>` | Widget title to match |
+| `-y, --yes` | Skip confirmation prompt |
+| `-f, --force` | Force the operation without confirmation |
+| `-n, --dry-run` | Show what would happen without making changes |
 
 All commands support `--json` for machine-readable output and `--fields` to select specific JSON fields.
 

docs/src/content/docs/commands/project.md

@@ -23,7 +23,7 @@ Create a new project
 | Option | Description |
 |--------|-------------|
 | `-t, --team <team>` | Team to create the project under |
-| `-n, --dry-run` | Validate inputs and show what would be created without creating it |
+| `-n, --dry-run` | Show what would happen without making changes |
 
 ### `sentry project delete <org/project>`
 
@@ -40,8 +40,8 @@ Delete a project
 | Option | Description |
 |--------|-------------|
 | `-y, --yes` | Skip confirmation prompt |
-| `-f, --force` | Force deletion without confirmation |
-| `-n, --dry-run` | Validate and show what would be deleted without deleting |
+| `-f, --force` | Force the operation without confirmation |
+| `-n, --dry-run` | Show what would happen without making changes |
 
 ### `sentry project list <org/project>`
 

plugins/sentry-cli/skills/sentry-cli/references/dashboards.md

@@ -152,6 +152,9 @@ Delete a widget from a dashboard
 **Flags:**
 - `-i, --index <value> - Widget index (0-based)`
 - `-t, --title <value> - Widget title to match`
+- `-y, --yes - Skip confirmation prompt`
+- `-f, --force - Force the operation without confirmation`
+- `-n, --dry-run - Show what would happen without making changes`
 
 **Examples:**
 

plugins/sentry-cli/skills/sentry-cli/references/projects.md

@@ -17,7 +17,7 @@ Create a new project
 
 **Flags:**
 - `-t, --team <value> - Team to create the project under`
-- `-n, --dry-run - Validate inputs and show what would be created without creating it`
+- `-n, --dry-run - Show what would happen without making changes`
 
 **Examples:**
 
@@ -38,8 +38,8 @@ Delete a project
 
 **Flags:**
 - `-y, --yes - Skip confirmation prompt`
-- `-f, --force - Force deletion without confirmation`
-- `-n, --dry-run - Validate and show what would be deleted without deleting`
+- `-f, --force - Force the operation without confirmation`
+- `-n, --dry-run - Show what would happen without making changes`
 
 **Examples:**
 

src/commands/dashboard/widget/delete.ts

@@ -2,15 +2,22 @@
  * sentry dashboard widget delete
  *
  * Remove a widget from an existing dashboard.
+ *
+ * Uses `buildDeleteCommand` — auto-injects `--yes`/`--force`/`--dry-run`
+ * flags. Non-interactive guard is disabled (`noNonInteractiveGuard`) because
+ * widget deletion is reversible (re-add the widget). `--yes`/`--force` are
+ * accepted but have no effect today (no confirmation prompt); `--dry-run`
+ * shows which widget would be removed without modifying the dashboard.
  */
 
 import type { SentryContext } from "../../../context.js";
 import { getDashboard, updateDashboard } from "../../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../../lib/arg-parsing.js";
-import { buildCommand, numberParser } from "../../../lib/command.js";
+import { numberParser } from "../../../lib/command.js";
 import { ValidationError } from "../../../lib/errors.js";
 import { formatWidgetDeleted } from "../../../lib/formatters/human.js";
 import { CommandOutput } from "../../../lib/formatters/output.js";
+import { buildDeleteCommand } from "../../../lib/mutate-command.js";
 import { buildDashboardUrl } from "../../../lib/sentry-urls.js";
 import {
   type DashboardDetail,
@@ -27,6 +34,9 @@ import {
 type DeleteFlags = {
   readonly index?: number;
   readonly title?: string;
+  readonly yes: boolean;
+  readonly force: boolean;
+  readonly "dry-run": boolean;
   readonly json: boolean;
   readonly fields?: string[];
 };
@@ -35,97 +45,134 @@ type DeleteResult = {
   dashboard: DashboardDetail;
   widgetTitle: string;
   url: string;
+  dryRun?: boolean;
 };
 
-export const deleteCommand = buildCommand({
-  docs: {
-    brief: "Delete a widget from a dashboard",
-    fullDescription:
-      "Remove a widget from an existing Sentry dashboard.\n\n" +
-      "The dashboard can be specified by numeric ID or title.\n" +
-      "Identify the widget by --index (0-based) or --title.\n\n" +
-      "Examples:\n" +
-      "  sentry dashboard widget delete 12345 --index 0\n" +
-      "  sentry dashboard widget delete 'My Dashboard' --title 'Error Rate'",
-  },
-  output: {
-    human: formatWidgetDeleted,
-  },
-  parameters: {
-    positional: {
-      kind: "array",
-      parameter: {
-        placeholder: "org/project/dashboard",
-        brief: "[<org/project>] <dashboard-id-or-title>",
-        parse: String,
+export const deleteCommand = buildDeleteCommand(
+  {
+    docs: {
+      brief: "Delete a widget from a dashboard",
+      fullDescription:
+        "Remove a widget from an existing Sentry dashboard.\n\n" +
+        "The dashboard can be specified by numeric ID or title.\n" +
+        "Identify the widget by --index (0-based) or --title.\n\n" +
+        "Examples:\n" +
+        "  sentry dashboard widget delete 12345 --index 0\n" +
+        "  sentry dashboard widget delete 'My Dashboard' --title 'Error Rate'\n" +
+        "  sentry dashboard widget delete 12345 --index 0 --dry-run",
+    },
+    output: {
+      human: formatWidgetDeleted,
+      jsonTransform: (result: DeleteResult) => {
+        if (result.dryRun) {
+          return {
+            dryRun: true,
+            widgetTitle: result.widgetTitle,
+            widgetCount: result.dashboard.widgets?.length ?? 0,
+            url: result.url,
+          };
+        }
+        return {
+          deleted: true,
+          widgetTitle: result.widgetTitle,
+          widgetCount: result.dashboard.widgets?.length ?? 0,
+          url: result.url,
+        };
       },
     },
-    flags: {
-      index: {
-        kind: "parsed",
-        parse: numberParser,
-        brief: "Widget index (0-based)",
-        optional: true,
+    parameters: {
+      positional: {
+        kind: "array",
+        parameter: {
+          placeholder: "org/project/dashboard",
+          brief: "[<org/project>] <dashboard-id-or-title>",
+          parse: String,
+        },
       },
-      title: {
-        kind: "parsed",
-        parse: String,
-        brief: "Widget title to match",
-        optional: true,
+      flags: {
+        index: {
+          kind: "parsed",
+          parse: numberParser,
+          brief: "Widget index (0-based)",
+          optional: true,
+        },
+        title: {
+          kind: "parsed",
+          parse: String,
+          brief: "Widget title to match",
+          optional: true,
+        },
       },
+      aliases: { i: "index", t: "title" },
     },
-    aliases: { i: "index", t: "title" },
-  },
-  async *func(this: SentryContext, flags: DeleteFlags, ...args: string[]) {
-    const { cwd } = this;
+    async *func(this: SentryContext, flags: DeleteFlags, ...args: string[]) {
+      const { cwd } = this;
 
-    if (flags.index === undefined && !flags.title) {
-      throw new ValidationError(
-        "Specify --index or --title to identify the widget to delete.",
-        "index"
+      if (flags.index === undefined && !flags.title) {
+        throw new ValidationError(
+          "Specify --index or --title to identify the widget to delete.",
+          "index"
+        );
+      }
+
+      const { dashboardRef, targetArg } = parseDashboardPositionalArgs(args);
+      const parsed = parseOrgProjectArg(targetArg);
+      const orgSlug = await resolveOrgFromTarget(
+        parsed,
+        cwd,
+        "sentry dashboard widget delete <org>/ <id> (--index <n> | --title <name>)"
       );
-    }
+      const dashboardId = await resolveDashboardId(orgSlug, dashboardRef);
 
-    const { dashboardRef, targetArg } = parseDashboardPositionalArgs(args);
-    const parsed = parseOrgProjectArg(targetArg);
-    const orgSlug = await resolveOrgFromTarget(
-      parsed,
-      cwd,
-      "sentry dashboard widget delete <org>/ <id> (--index <n> | --title <name>)"
-    );
-    const dashboardId = await resolveDashboardId(orgSlug, dashboardRef);
+      // GET current dashboard → find widget
+      const current = await getDashboard(orgSlug, dashboardId).catch(
+        (error: unknown) =>
+          enrichDashboardError(error, {
+            orgSlug,
+            dashboardId,
+            operation: "view",
+          })
+      );
+      const widgets = current.widgets ?? [];
 
-    // GET current dashboard → find widget → splice → PUT
-    const current = await getDashboard(orgSlug, dashboardId).catch(
-      (error: unknown) =>
-        enrichDashboardError(error, { orgSlug, dashboardId, operation: "view" })
-    );
-    const widgets = current.widgets ?? [];
+      const widgetIndex = resolveWidgetIndex(widgets, flags.index, flags.title);
+      const widgetTitle = widgets[widgetIndex]?.title;
+      const url = buildDashboardUrl(orgSlug, dashboardId);
 
-    const widgetIndex = resolveWidgetIndex(widgets, flags.index, flags.title);
+      // Dry-run mode: show what would be removed without removing it
+      if (flags["dry-run"]) {
+        yield new CommandOutput({
+          dashboard: current,
+          widgetTitle,
+          url,
+          dryRun: true,
+        } as DeleteResult);
+        return { hint: `Dashboard: ${url}` };
+      }
 
-    const widgetTitle = widgets[widgetIndex]?.title;
-    const updateBody = prepareDashboardForUpdate(current);
-    updateBody.widgets.splice(widgetIndex, 1);
+      // Splice the widget and PUT the updated dashboard
+      const updateBody = prepareDashboardForUpdate(current);
+      updateBody.widgets.splice(widgetIndex, 1);
 
-    const updated = await updateDashboard(
-      orgSlug,
-      dashboardId,
-      updateBody
-    ).catch((error: unknown) =>
-      enrichDashboardError(error, {
+      const updated = await updateDashboard(
         orgSlug,
         dashboardId,
-        operation: "update",
-      })
-    );
-    const url = buildDashboardUrl(orgSlug, dashboardId);
+        updateBody
+      ).catch((error: unknown) =>
+        enrichDashboardError(error, {
+          orgSlug,
+          dashboardId,
+          operation: "update",
+        })
+      );
 
-    yield new CommandOutput({
-      dashboard: updated,
-      widgetTitle,
-      url,
-    } as DeleteResult);
-    return { hint: `Dashboard: ${url}` };
+      yield new CommandOutput({
+        dashboard: updated,
+        widgetTitle,
+        url,
+      } as DeleteResult);
+      return { hint: `Dashboard: ${url}` };
+    },
   },
-});
+  { noNonInteractiveGuard: true }
+);

src/commands/project/create.ts

@@ -40,6 +40,7 @@ import { CommandOutput } from "../../lib/formatters/output.js";
 import { buildMarkdownTable, type Column } from "../../lib/formatters/table.js";
 import { renderTextTable } from "../../lib/formatters/text-table.js";
 import { logger } from "../../lib/logger.js";
+import { DRY_RUN_ALIASES, DRY_RUN_FLAG } from "../../lib/mutate-command.js";
 import {
   COMMON_PLATFORMS,
   isValidPlatform,
@@ -312,14 +313,9 @@ export const createCommand = buildCommand({
         brief: "Team to create the project under",
         optional: true,
       },
-      "dry-run": {
-        kind: "boolean",
-        brief:
-          "Validate inputs and show what would be created without creating it",
-        default: false,
-      },
+      "dry-run": DRY_RUN_FLAG,
     },
-    aliases: { t: "team", n: "dry-run" },
+    aliases: { ...DRY_RUN_ALIASES, t: "team" },
   },
   async *func(
     this: SentryContext,