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

Add src/lib/mutate-command.ts with shared infrastructure for create/delete
commands, paralleling list-command.ts for list commands:

- Level A: Shared flag constants (DRY_RUN_FLAG, YES_FLAG, FORCE_FLAG,
  DESTRUCTIVE_FLAGS/ALIASES, DRY_RUN_ALIASES)
- Level B: Shared utilities (isConfirmationBypassed, guardNonInteractive,
  confirmByTyping, requireExplicitTarget)
- Level C: buildDeleteCommand wrapper — auto-injects --yes/--force/--dry-run
  flags and runs a non-interactive safety guard as a pre-hook

Refactor existing commands to use the new shared infrastructure:
- project delete: uses buildDeleteCommand, confirmByTyping, requireExplicitTarget
- project create: uses DRY_RUN_FLAG and DRY_RUN_ALIASES
- dashboard widget delete: uses buildDeleteCommand, gains --dry-run support

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

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,21 @@
  * sentry dashboard widget delete
  *
  * Remove a widget from an existing dashboard.
+ *
+ * Uses `buildDeleteCommand` — auto-injects `--yes`/`--force`/`--dry-run`
+ * flags and enforces the non-interactive guard before `func()` runs.
+ * `--yes`/`--force` are no-ops for now (no confirmation prompt) but
+ * available for scripting and forward-compatibility.
  */
 
 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 +33,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,9 +44,10 @@ type DeleteResult = {
   dashboard: DashboardDetail;
   widgetTitle: string;
   url: string;
+  dryRun?: boolean;
 };
 
-export const deleteCommand = buildCommand({
+export const deleteCommand = buildDeleteCommand({
   docs: {
     brief: "Delete a widget from a dashboard",
     fullDescription:
@@ -46,10 +56,27 @@ export const deleteCommand = buildCommand({
       "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'",
+      "  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,
+      };
+    },
   },
   parameters: {
     positional: {
@@ -95,16 +122,33 @@ export const deleteCommand = buildCommand({
     );
     const dashboardId = await resolveDashboardId(orgSlug, dashboardRef);
 
-    // GET current dashboard → find widget → splice → PUT
+    // GET current dashboard → find widget
     const current = await getDashboard(orgSlug, dashboardId).catch(
       (error: unknown) =>
-        enrichDashboardError(error, { orgSlug, dashboardId, operation: "view" })
+        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);
+
+    // 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}` };
+    }
+
+    // Splice the widget and PUT the updated dashboard
     const updateBody = prepareDashboardForUpdate(current);
     updateBody.widgets.splice(widgetIndex, 1);
 
@@ -119,7 +163,6 @@ export const deleteCommand = buildCommand({
         operation: "update",
       })
     );
-    const url = buildDashboardUrl(orgSlug, dashboardId);
 
     yield new CommandOutput({
       dashboard: updated,

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,

src/commands/project/delete.ts

@@ -12,29 +12,33 @@
  * 5. Display result
  *
  * Safety measures:
- * - No auto-detect mode: requires explicit target to prevent accidental deletion
- * - Type-out confirmation: user must type the full `org/project` slug
- * - Strict cancellation check (Symbol(clack:cancel) gotcha)
- * - Refuses to run in non-interactive mode without --yes flag
+ * - Uses `buildDeleteCommand` — auto-injects `--yes`/`--force`/`--dry-run`
+ *   flags and enforces the non-interactive guard before `func()` runs
+ * - No auto-detect mode: `requireExplicitTarget` blocks accidental deletion
+ * - Type-out confirmation via `confirmByTyping` (unless --yes/--force)
  */
 
-import { isatty } from "node:tty";
 import type { SentryContext } from "../../context.js";
 import {
   deleteProject,
   getOrganization,
   getProject,
 } from "../../lib/api-client.js";
 import { parseOrgProjectArg } from "../../lib/arg-parsing.js";
-import { buildCommand } from "../../lib/command.js";
 import { getCachedOrgRole } from "../../lib/db/regions.js";
-import { ApiError, CliError, ContextError } from "../../lib/errors.js";
+import { ApiError } from "../../lib/errors.js";
 import {
   formatProjectDeleted,
   type ProjectDeleteResult,
 } from "../../lib/formatters/human.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import { logger } from "../../lib/logger.js";
+import {
+  buildDeleteCommand,
+  confirmByTyping,
+  isConfirmationBypassed,
+  requireExplicitTarget,
+} from "../../lib/mutate-command.js";
 import { resolveOrgProjectTarget } from "../../lib/resolve-target.js";
 import { buildProjectUrl } from "../../lib/sentry-urls.js";
 
@@ -43,46 +47,6 @@ const log = logger.withTag("project.delete");
 /** Command name used in error messages and resolution hints */
 const COMMAND_NAME = "project delete";
 
-/**
- * Prompt for confirmation before deleting a project.
- *
- * Uses a type-out confirmation where the user must type the full
- * `org/project` slug — similar to GitHub's deletion confirmation.
- *
- * Throws in non-interactive mode without --yes. Returns true if
- * the typed input matches, false otherwise.
- *
- * @param orgSlug - Organization slug for display and matching
- * @param project - Project with slug and name for display and matching
- * @returns true if confirmed, false if cancelled or mismatched
- */
-async function confirmDeletion(
-  orgSlug: string,
-  project: { slug: string; name: string }
-): Promise<boolean> {
-  const expected = `${orgSlug}/${project.slug}`;
-
-  if (!isatty(0)) {
-    throw new CliError(
-      `Refusing to delete '${expected}' in non-interactive mode. ` +
-        "Use --yes or --force to confirm."
-    );
-  }
-
-  const response = await log.prompt(
-    `Type '${expected}' to permanently delete project '${project.name}':`,
-    { type: "text", placeholder: expected }
-  );
-
-  // consola prompt returns Symbol(clack:cancel) on Ctrl+C — a truthy value.
-  // Check type to avoid treating cancel as a valid response.
-  if (typeof response !== "string") {
-    return false;
-  }
-
-  return response.trim() === expected;
-}
-
 /**
  * Build an actionable 403 error by checking the user's org role.
  *
@@ -164,7 +128,7 @@ type DeleteFlags = {
   readonly fields?: string[];
 };
 
-export const deleteCommand = buildCommand({
+export const deleteCommand = buildDeleteCommand({
   docs: {
     brief: "Delete a project",
     fullDescription:
@@ -207,39 +171,17 @@ export const deleteCommand = buildCommand({
         },
       ],
     },
-    flags: {
-      yes: {
-        kind: "boolean",
-        brief: "Skip confirmation prompt",
-        default: false,
-      },
-      force: {
-        kind: "boolean",
-        brief: "Force deletion without confirmation",
-        default: false,
-      },
-      "dry-run": {
-        kind: "boolean",
-        brief: "Validate and show what would be deleted without deleting",
-        default: false,
-      },
-    },
-    aliases: { y: "yes", f: "force", n: "dry-run" },
   },
   async *func(this: SentryContext, flags: DeleteFlags, target: string) {
     const { cwd } = this;
 
     // Block auto-detect for safety — destructive commands require explicit targets
     const parsed = parseOrgProjectArg(target);
-    if (parsed.type === "auto-detect") {
-      throw new ContextError(
-        "Project target",
-        `sentry ${COMMAND_NAME} <org>/<project>`,
-        [
-          "Auto-detection is disabled for delete — specify the target explicitly",
-        ]
-      );
-    }
+    requireExplicitTarget(
+      parsed,
+      "Project target",
+      `sentry ${COMMAND_NAME} <org>/<project>`
+    );
 
     const resolved = await resolveOrgProjectTarget(parsed, cwd, COMMAND_NAME);
     const { org: orgSlug, project: projectSlug } = resolved;
@@ -255,9 +197,13 @@ export const deleteCommand = buildCommand({
       return;
     }
 
-    // Confirmation gate
-    if (!(flags.yes || flags.force)) {
-      const confirmed = await confirmDeletion(orgSlug, project);
+    // Confirmation gate — non-interactive guard is handled by buildDeleteCommand
+    if (!isConfirmationBypassed(flags)) {
+      const expected = `${orgSlug}/${project.slug}`;
+      const confirmed = await confirmByTyping(
+        expected,
+        `Type '${expected}' to permanently delete project '${project.name}':`
+      );
       if (!confirmed) {
         log.info("Cancelled.");
         return;