@series-a/cli 0.6.2 → 0.7.1

package/README.md

@@ -40,6 +40,19 @@ npx @series-a/cli@latest login
 # Prompts for API key + workspace ID (the 6-char slug, e.g. dmw9wj)
 ```
 
+### Admin login
+
+Admin keys (`advos_admin_…`) are detected automatically — no workspace prompt:
+
+```bash
+advisoros login --admin
+# ✓ Logged in as admin profile "default" — N workspaces reachable
+
+advisoros workspaces list                       # admin-only, no workspace needed
+advisoros campaigns list --workspace dmw9wj     # pass workspace per command
+advisoros whoami                                # shows scope: admin (cross-workspace)
+```
+
 Multiple workspaces?
 
 ```bash
@@ -188,6 +201,35 @@ JOB=$(advisoros agents run lead-intelligence --input '{}' --json | jq -r '.run.j
 watch -n 5 "advisoros agents job $JOB --json | jq '{status,progress}'"
 ```
 
+## Safety rails
+
+Anything that stops sending, un-enrols leads or deletes data now asks first.
+
+```bash
+# Launch is a dry run until you confirm — preflight runs server-side.
+advisoros campaigns preflight 9884b9ec
+advisoros campaigns launch 9884b9ec            # shows blockers, changes nothing
+advisoros campaigns launch 9884b9ec --confirm  # actually launches
+
+# Destructive commands prompt; scripts must pass --yes.
+advisoros campaigns delete 9884b9ec --dry-run
+advisoros campaigns delete 9884b9ec --yes
+advisoros sequences delete-step 6b60d6ad --yes
+```
+
+A campaign with no leads, no sequence, no steps or no sender account is
+**refused**, not silently activated. `--force` overrides once you know why.
+
+New commands: `campaigns preflight|archive|clone|delete|remove-leads`,
+`sequences delete|update-step|delete-step`.
+
+## Reading more than 200 rows
+
+List commands accept `--limit` up to 1000 and every list response carries
+`pagination` (`total`, `limit`, `offset`, `next_cursor`, `has_more`). If you ask
+for more than the maximum, the response says it was clamped instead of quietly
+truncating.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -238,3 +280,23 @@ git push --follow-tags
 
 See [`docs/agent-api.md`](../../docs/agent-api.md) for the underlying `/agent-api` envelope.
 
+
+
+## Admin keys
+
+Admin keys (`advos_admin_…`) are authorised by the key itself — they do **not** need an
+`agent_workspace_bindings` row. `agent_name` is an audit label only.
+
+```bash
+advisoros login --admin --profile ops     # no workspace prompt; prints reachable workspace count
+advisoros whoami --profile ops            # scope: admin (cross-workspace) + reachable count
+advisoros workspaces list --profile ops   # every reachable workspace (paginated, up to 1000)
+advisoros analytics overview --workspace dmw9wj --profile ops
+```
+
+Caller identity is overridable: `--as-agent <name>` on any command, `ADVISOROS_AGENT_NAME`
+in the environment, or the `agentName` stored on the profile at login (default `advisoros-cli`).
+
+Workspace-scoped keys are unchanged: they can only reach their own workspace (403 otherwise)
+and cannot use the `workspaces` resource. An agent without bindings now gets a typed 403
+explaining to use an admin key, instead of a 500.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-a/cli",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "AdvisorPro command-line interface — drive leads, campaigns, sequences and agents from your terminal.",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -26,7 +26,11 @@ export async function call(resource, action, params = {}, opts = {}) {
     process.env.ADVISOROS_BASE_URL ||
     stored?.baseUrl ||
     DEFAULTS.baseUrl;
-  const agentName = opts.agentName || stored?.agentName || "advisoros-cli";
+  const agentName =
+    opts.agentName ||
+    process.env.ADVISOROS_AGENT_NAME ||
+    stored?.agentName ||
+    "advisoros-cli";
 
   if (!apiKey) {
     throw new AdvisorOSApiError(

package/src/commands/auth.mjs

@@ -10,8 +10,10 @@ export function registerAuth(program) {
     .description("Save an API key + workspace to ~/.advisoros/config.json")
     .option("-p, --profile <name>", "profile name", "default")
     .option("--api-key <key>", "API key (otherwise prompted)")
-    .option("--workspace <id>", "workspace id (otherwise prompted)")
+    .option("--workspace <id>", "workspace id (otherwise prompted, unless --admin)")
+    .option("--admin", "admin key login — verify cross-workspace, no workspace required", false)
     .option("--base-url <url>", "agent-api base URL", DEFAULTS.baseUrl)
+    .option("--as-agent <name>", "caller identity to send as agent_name", "advisoros-cli")
     .action(async (opts) => {
       try {
         let { apiKey, workspace, baseUrl, profile } = opts;
@@ -19,13 +21,16 @@ export function registerAuth(program) {
           const r = await prompts({
             type: "password",
             name: "v",
-            message: "API key (from Settings → API Keys)",
+            message: "API key (from Settings → API Keys; advos_admin_… for admin)",
             validate: (v) => v && v.length > 10 ? true : "Required",
           });
           apiKey = r.v;
         }
         if (!apiKey) return fail(new Error("Aborted"));
-        if (!workspace) {
+
+        const isAdmin = opts.admin || apiKey.startsWith("advos_admin_");
+
+        if (!isAdmin && !workspace) {
           const r = await prompts({
             type: "text",
             name: "v",
@@ -34,14 +39,31 @@ export function registerAuth(program) {
           });
           workspace = r.v;
         }
-        if (!workspace) return fail(new Error("Aborted"));
+        if (!isAdmin && !workspace) return fail(new Error("Aborted"));
+
+        const agentName = opts.asAgent || "advisoros-cli";
+
+        if (isAdmin) {
+          // Verify the admin key cross-workspace; no workspace slug needed.
+          const verify = await call("workspaces", "list", { limit: 1000 }, {
+            apiKey, baseUrl, agentName,
+          });
+          const count = verify?.pagination?.total ?? verify?.workspaces?.length ?? 0;
+          await setProfile(profile, { apiKey, baseUrl, admin: true, agentName, ...(workspace ? { workspaceId: workspace } : {}) });
+          process.stdout.write(chalk.green(
+            `\n✓ Logged in as admin profile "${profile}" — ${count} workspaces reachable\n` +
+            `  Config: ${CONFIG_PATH}\n` +
+            `  Tip: pass --workspace <slug> per command, or set ADVISOROS_WORKSPACE_ID.\n`,
+          ));
+          return;
+        }
 
         // Verify the credentials with a cheap round-trip.
         const verify = await call("agents", "list", {}, {
-          apiKey, workspaceId: workspace, baseUrl,
+          apiKey, workspaceId: workspace, baseUrl, agentName,
         });
         const count = verify?.agents?.length ?? 0;
-        await setProfile(profile, { apiKey, workspaceId: workspace, baseUrl });
+        await setProfile(profile, { apiKey, workspaceId: workspace, baseUrl, agentName });
         process.stdout.write(chalk.green(
           `\n✓ Logged in as profile "${profile}" — workspace ${workspace} (${count} agents visible)\n` +
           `  Config: ${CONFIG_PATH}\n`,
@@ -58,9 +80,24 @@ export function registerAuth(program) {
         const p = await getProfile(opts.profile);
         if (!p) return fail(new Error(`Profile "${opts.profile}" not found. Run \`advisoros login\`.`));
         const masked = p.apiKey ? p.apiKey.slice(0, 8) + "…" + p.apiKey.slice(-4) : "(none)";
+        const isAdmin = Boolean(p.admin) || String(p.apiKey || "").startsWith("advos_admin_");
+
+        let reachable = null;
+        if (isAdmin) {
+          try {
+            const r = await call("workspaces", "list", { limit: 1000 }, {
+              apiKey: p.apiKey, baseUrl: p.baseUrl, agentName: p.agentName,
+            });
+            reachable = r?.pagination?.total ?? r?.workspaces?.length ?? null;
+          } catch { reachable = null; }
+        }
+
         process.stdout.write(
           `profile:    ${opts.profile}\n` +
-          `workspace:  ${p.workspaceId}\n` +
+          `scope:      ${isAdmin ? "admin (cross-workspace)" : "workspace"}\n` +
+          `workspace:  ${p.workspaceId || "(none — pass --workspace per command)"}\n` +
+          (isAdmin ? `reachable:  ${reachable == null ? "(could not verify)" : `${reachable} workspaces`}\n` : "") +
+          `agent:      ${p.agentName || "advisoros-cli"}\n` +
           `base url:   ${p.baseUrl || DEFAULTS.baseUrl}\n` +
           `api key:    ${masked}\n`,
         );

package/src/commands/resources.mjs

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { call } from "../api.mjs";
-import { emit, fail, ctxFrom, withCommonOpts, table, truncate } from "../ui.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, table, truncate, confirmDestructive } from "../ui.mjs";
 
 function parseCsv(text) {
   // Tiny CSV parser: header row + comma-separated values, quoted fields supported.
@@ -174,8 +174,10 @@ export function registerLeads(program) {
 
   withCommonOpts(leads.command("delete <id>"))
     .description("Delete a lead")
+    .option("-y, --yes", "skip the confirmation prompt")
     .action(async function (id) {
       try {
+        await confirmDestructive(this, `Delete lead ${id}. This cannot be undone.`);
         const r = await call("leads", "delete", { id }, ctxFrom(this));
         emit(this, r, () => process.stdout.write(`✓ Deleted ${id}\n`));
       } catch (e) { fail(e); }
@@ -291,11 +293,56 @@ export function registerCampaigns(program) {
       } catch (e) { fail(e); }
     });
 
-  withCommonOpts(c.command("launch <id>"))
-    .description("Activate a campaign (status → active)")
+  withCommonOpts(c.command("remove-leads <campaignId>"))
+    .description("Un-enrol leads from a campaign")
+    .option("--lead-ids <ids>", "comma-separated lead ids")
+    .option("--all", "remove every enrolled lead")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .option("--dry-run", "show what would be removed")
+    .action(async function (campaignId, opts) {
+      try {
+        const ids = opts.leadIds ? opts.leadIds.split(",").map((s) => s.trim()).filter(Boolean) : [];
+        if (!ids.length && !opts.all) return fail(new Error("--lead-ids or --all required"));
+        const params = { campaign_id: campaignId, lead_ids: ids, all: !!opts.all };
+        if (opts.dryRun) {
+          const d = await call("campaigns", "remove_leads", { ...params, dry_run: true }, ctxFrom(this));
+          return emit(this, d, (x) => process.stdout.write(`Would remove ${x.would_remove} lead(s) from ${campaignId}\n`));
+        }
+        await confirmDestructive(this, `Remove ${opts.all ? "ALL enrolled leads" : `${ids.length} lead(s)`} from campaign ${campaignId}.`);
+        const r = await call("campaigns", "remove_leads", params, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Removed ${d.removed} lead(s)\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("preflight <id>"))
+    .description("Check whether a campaign is safe to launch (read-only)")
     .action(async function (id) {
       try {
-        const r = await call("campaigns", "launch", { campaign_id: id }, ctxFrom(this));
+        const r = await call("campaigns", "preflight", { campaign_id: id }, ctxFrom(this));
+        emit(this, r, renderPreflight);
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("launch <id>"))
+    .description("Activate a campaign — runs preflight first, then requires --confirm")
+    .option("--confirm", "actually launch (without it, this is a dry run)")
+    .option("--force", "launch even if preflight found blockers")
+    .action(async function (id, opts) {
+      try {
+        if (!opts.confirm) {
+          const d = await call("campaigns", "launch", { campaign_id: id, dry_run: true }, ctxFrom(this));
+          return emit(this, d, (x) => {
+            renderPreflight(x.preflight ?? x);
+            process.stdout.write(
+              x.preflight?.ok
+                ? `\nDry run only. Re-run with --confirm to launch.\n`
+                : `\nDry run only. Fix the blockers above, then re-run with --confirm.\n`,
+            );
+          });
+        }
+        const r = await call(
+          "campaigns", "launch", { campaign_id: id, force: !!opts.force }, ctxFrom(this),
+        );
         emit(this, r, (d) => process.stdout.write(`✓ ${d.campaign?.name ?? id} → ${d.campaign?.status}\n`));
       } catch (e) { fail(e); }
     });
@@ -311,14 +358,84 @@ export function registerCampaigns(program) {
 
   withCommonOpts(c.command("resume <id>"))
     .description("Resume a paused campaign")
-    .action(async function (id) {
+    .option("--confirm", "required — resuming restarts sending")
+    .option("--force", "resume even if preflight found blockers")
+    .action(async function (id, opts) {
       try {
-        const r = await call("campaigns", "resume", { campaign_id: id }, ctxFrom(this));
+        if (!opts.confirm) {
+          const d = await call("campaigns", "resume", { campaign_id: id, dry_run: true }, ctxFrom(this));
+          return emit(this, d, (x) => {
+            renderPreflight(x.preflight ?? x);
+            process.stdout.write(`\nDry run only. Re-run with --confirm to resume.\n`);
+          });
+        }
+        const r = await call("campaigns", "resume", { campaign_id: id, force: !!opts.force }, ctxFrom(this));
         emit(this, r, (d) => process.stdout.write(`✓ ${d.campaign?.name ?? id} → ${d.campaign?.status}\n`));
       } catch (e) { fail(e); }
     });
+
+  withCommonOpts(c.command("archive <id>"))
+    .description("Archive a campaign (reversible, keeps history)")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async function (id) {
+      try {
+        await confirmDestructive(this, `Archive campaign ${id}. It will stop sending.`);
+        const r = await call("campaigns", "archive", { campaign_id: id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ ${d.campaign?.name ?? id} → archived\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("clone <id>"))
+    .description("Duplicate a campaign as a fresh draft (no leads, no history)")
+    .option("--name <name>", "name for the copy")
+    .action(async function (id, opts) {
+      try {
+        const r = await call("campaigns", "clone", { campaign_id: id, name: opts.name }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Cloned to ${d.campaign?.id} — ${d.campaign?.name}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(c.command("delete <id>"))
+    .description("Permanently delete a campaign and its enrolments")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .option("--dry-run", "show what would be deleted")
+    .option("--force", "delete even when the campaign has dispatch history")
+    .action(async function (id, opts) {
+      try {
+        if (opts.dryRun) {
+          const d = await call("campaigns", "delete", { campaign_id: id, dry_run: true }, ctxFrom(this));
+          return emit(this, d, (x) =>
+            process.stdout.write(
+              `Would delete campaign ${x.campaign?.name ?? id} (${x.dispatches} dispatched actions)\n`,
+            ));
+        }
+        await confirmDestructive(
+          this,
+          `Permanently delete campaign ${id} and every lead enrolment on it. This cannot be undone.`,
+          { expect: id.slice(0, 8) },
+        );
+        const r = await call(
+          "campaigns", "delete", { campaign_id: id, force: !!opts.force }, ctxFrom(this),
+        );
+        emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.name ?? id}\n`));
+      } catch (e) { fail(e); }
+    });
+}
+
+function renderPreflight(p) {
+  if (!p) return;
+  process.stdout.write(
+    `${p.ok ? "✓ Ready to launch" : "✖ Not ready"} — ${p.name ?? p.campaign_id} (${p.status})\n`,
+  );
+  const c = p.checks ?? {};
+  process.stdout.write(
+    `  leads: ${c.leads_enrolled}   steps: ${c.sequence_steps}   senders: ${c.sender_accounts}   daily limit: ${c.daily_send_limit ?? "—"}\n`,
+  );
+  for (const b of p.blockers ?? []) process.stdout.write(`  ✖ ${b}\n`);
+  for (const w of p.warnings ?? []) process.stdout.write(`  ! ${w}\n`);
 }
 
+
 export function registerSequences(program) {
   const s = program.command("sequences").description("Manage LinkedIn sequences");
 
@@ -501,8 +618,68 @@ export function registerSequences(program) {
         });
       } catch (e) { fail(e); }
     });
+
+  withCommonOpts(s.command("update-step <stepId>"))
+    .description("Patch one step in place (message, delay, variant, channel, action)")
+    .option("--action <action>", "step action")
+    .option("--message <text>", "message_content")
+    .option("--delay <days>", "delay_days")
+    .option("--variant <v>", "variant")
+    .option("--channel <c>", "channel")
+    .action(async function (stepId, opts) {
+      try {
+        const params = { step_id: stepId };
+        if (opts.action !== undefined) params.action = opts.action;
+        if (opts.message !== undefined) params.message_content = opts.message;
+        if (opts.delay !== undefined) params.delay_days = Number(opts.delay);
+        if (opts.variant !== undefined) params.variant = opts.variant;
+        if (opts.channel !== undefined) params.channel = opts.channel;
+        const r = await call("sequences", "update_step", params, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Updated step ${d.step?.id ?? stepId} (${d.step?.action})\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("delete-step <stepId>"))
+    .description("Delete one step; its children are re-parented")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .option("--dry-run", "show what would change")
+    .action(async function (stepId, opts) {
+      try {
+        if (opts.dryRun) {
+          const d = await call("sequences", "delete_step", { step_id: stepId, dry_run: true }, ctxFrom(this));
+          return emit(this, d, (x) =>
+            process.stdout.write(`Would delete step ${stepId}; ${x.reparented_children} child step(s) re-parented\n`));
+        }
+        await confirmDestructive(this, `Delete sequence step ${stepId}. Child steps will be re-parented.`);
+        const r = await call("sequences", "delete_step", { step_id: stepId }, ctxFrom(this));
+        emit(this, r, (d) =>
+          process.stdout.write(`✓ Deleted step ${stepId} (${d.reparented_children} child step(s) re-parented)\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(s.command("delete <id>"))
+    .description("Delete a sequence and all its steps")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .option("--dry-run", "show what would be deleted")
+    .option("--force", "delete even if campaigns still use it (they are detached)")
+    .action(async function (id, opts) {
+      try {
+        if (opts.dryRun) {
+          const d = await call("sequences", "delete", { id, dry_run: true }, ctxFrom(this));
+          return emit(this, d, (x) =>
+            process.stdout.write(
+              `Would delete sequence ${x.sequence?.name ?? id}; used by ${x.used_by_campaigns?.length ?? 0} campaign(s)\n`,
+            ));
+        }
+        await confirmDestructive(this, `Delete sequence ${id} and every step on it. This cannot be undone.`);
+        const r = await call("sequences", "delete", { id, force: !!opts.force }, ctxFrom(this));
+        emit(this, r, (d) =>
+          process.stdout.write(`✓ Deleted sequence ${d.sequence_id} (${d.detached_campaigns} campaign(s) detached)\n`));
+      } catch (e) { fail(e); }
+    });
 }
 
+
 function parseSnoozeDuration(s) {
   // Accepts e.g. "30m", "2h", "1d", "45" (minutes). Returns minutes (int).
   if (!s) return null;
@@ -900,8 +1077,10 @@ export function registerContent(program) {
 
   withCommonOpts(c.command("delete <id>"))
     .description("Delete a content item")
+    .option("-y, --yes", "skip the confirmation prompt")
     .action(async function (id) {
       try {
+        await confirmDestructive(this, `Delete content item ${id}. This cannot be undone.`);
         const r = await call("content", "delete", { id }, ctxFrom(this));
         emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
       } catch (e) { fail(e); }
@@ -1043,8 +1222,10 @@ export function registerCalendar(program) {
 
   withCommonOpts(cal.command("delete <id>"))
     .description("Delete a calendar post")
+    .option("-y, --yes", "skip the confirmation prompt")
     .action(async function (id) {
       try {
+        await confirmDestructive(this, `Delete calendar post ${id}. This cannot be undone.`);
         const r = await call("calendar", "delete", { id }, ctxFrom(this));
         emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
       } catch (e) { fail(e); }
@@ -1152,8 +1333,10 @@ export function registerSignals(program) {
 
   withCommonOpts(s.command("delete <id>"))
     .description("Delete a signal")
+    .option("-y, --yes", "skip the confirmation prompt")
     .action(async function (id) {
       try {
+        await confirmDestructive(this, `Delete signal ${id}. This cannot be undone.`);
         const r = await call("signals", "delete", { id }, ctxFrom(this));
         emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
       } catch (e) { fail(e); }
@@ -1283,8 +1466,10 @@ export function registerPipelines(program) {
 
   withCommonOpts(p.command("delete <id>"))
     .description("Delete an opportunity")
+    .option("-y, --yes", "skip the confirmation prompt")
     .action(async function (id) {
       try {
+        await confirmDestructive(this, `Delete pipeline record ${id}. This cannot be undone.`);
         const r = await call("pipelines", "delete", { id }, ctxFrom(this));
         emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
       } catch (e) { fail(e); }
@@ -1472,8 +1657,10 @@ export function registerAgents(program) {
 
   withCommonOpts(a.command("delete <id>"))
     .description("Delete an agent")
+    .option("-y, --yes", "skip the confirmation prompt")
     .action(async function (id) {
       try {
+        await confirmDestructive(this, `Delete agent ${id}. This cannot be undone.`);
         const r = await call("agents", "delete", { id }, ctxFrom(this));
         emit(this, r, (d) => process.stdout.write(`✓ Deleted ${d.deleted}\n`));
       } catch (e) { fail(e); }

package/src/index.mjs

@@ -20,8 +20,9 @@ const program = new Command();
 program
   .name("advisoros")
   .description("AdvisorPro CLI — drive leads, campaigns, sequences and agents from your terminal.")
-  .version("0.5.0")
-  .option("--json", "machine-readable JSON output (applies to all subcommands)");
+  .version("0.7.0")
+  .option("--json", "machine-readable JSON output (applies to all subcommands)")
+  .option("--as-agent <name>", "caller identity sent as agent_name (audit label only)");
 
 registerAuth(program);
 registerLeads(program);

package/src/ui.mjs

@@ -45,7 +45,8 @@ export function withCommonOpts(cmd) {
     .option("--json", "output raw JSON")
     .option("-w, --workspace <id>", "override workspace_id")
     .option("-p, --profile <name>", "use a named profile")
-    .option("--api-key <key>", "override API key");
+    .option("--api-key <key>", "override API key")
+    .option("--as-agent <name>", "caller identity sent as agent_name (audit label)");
 }
 
 export function ctxFrom(cmd) {
@@ -54,5 +55,50 @@ export function ctxFrom(cmd) {
     apiKey: opts.apiKey,
     workspaceId: opts.workspace,
     profile: opts.profile,
+    agentName: opts.asAgent,
   };
 }
+
+/**
+ * Gate a destructive command. Returns true when it may proceed.
+ * Non-interactive shells must pass --yes; --json implies scripted use, so it
+ * also requires --yes rather than hanging on a prompt.
+ */
+export async function confirmDestructive(cmd, summary, { expect } = {}) {
+  const opts = cmd.optsWithGlobals();
+  if (opts.yes) return true;
+  if (isJsonMode(cmd) || !process.stdin.isTTY) {
+    process.stderr.write(
+      chalk.red(`✖ Refusing to run without confirmation.\n`) +
+      chalk.gray(`  ${summary}\n  Re-run with --yes to confirm (or --dry-run to preview).\n`),
+    );
+    process.exit(1);
+  }
+  const { default: prompts } = await import("prompts");
+  process.stdout.write(chalk.yellow(`\n${summary}\n`));
+  if (expect) {
+    const r = await prompts({
+      type: "text",
+      name: "v",
+      message: `Type "${expect}" to confirm`,
+    });
+    if (r.v !== expect) {
+      process.stdout.write("Aborted.\n");
+      process.exit(1);
+    }
+    return true;
+  }
+  const r = await prompts({ type: "confirm", name: "v", message: "Proceed?", initial: false });
+  if (!r.v) {
+    process.stdout.write("Aborted.\n");
+    process.exit(1);
+  }
+  return true;
+}
+
+/** Common flags for destructive commands. */
+export function withDestructiveOpts(cmd) {
+  return cmd
+    .option("-y, --yes", "skip the confirmation prompt")
+    .option("--dry-run", "show what would happen without changing anything");
+}