@tarout/cli 0.3.0 → 0.4.0

package/dist/index.js

@@ -1,12 +1,4 @@
 #!/usr/bin/env node
-import {
-  failSpinner,
-  registerBillingCommands,
-  startSpinner,
-  stopSpinner,
-  succeedSpinner,
-  updateSpinner
-} from "./chunk-BS6DFVSU.js";
 import {
   AuthError,
   BuildFailedError,
@@ -21,7 +13,7 @@ import {
   handleError,
   platformFetch,
   resetApiClient
-} from "./chunk-NHNK5ZQ5.js";
+} from "./chunk-Y6TWR3XZ.js";
 import {
   clearConfig,
   getApiUrl,
@@ -42,7 +34,7 @@ import {
   password,
   promptOrEmit,
   select
-} from "./chunk-CJMIX35A.js";
+} from "./chunk-DI66W4S5.js";
 import {
   ExitCode,
   box,
@@ -61,7 +53,7 @@ import {
   shouldSkipConfirmation,
   success,
   table
-} from "./chunk-KL3JNPAY.js";
+} from "./chunk-K7JK5HIL.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -69,7 +61,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@tarout/cli",
-  version: "0.3.0",
+  version: "0.4.0",
   description: "Tarout CLI \u2014 the Saudi cloud platform for coding agents",
   type: "module",
   bin: {
@@ -211,6 +203,52 @@ function isCredentialError(error2) {
   );
 }
 
+// src/utils/spinner.ts
+import ora from "ora";
+var currentSpinner = null;
+function jsonMode() {
+  try {
+    return isJsonMode();
+  } catch {
+    return false;
+  }
+}
+function startSpinner(text) {
+  if (jsonMode()) return null;
+  if (currentSpinner) {
+    currentSpinner.stop();
+  }
+  currentSpinner = ora(text).start();
+  return currentSpinner;
+}
+function succeedSpinner(text) {
+  if (jsonMode()) return;
+  if (currentSpinner) {
+    currentSpinner.succeed(text);
+    currentSpinner = null;
+  }
+}
+function failSpinner(text) {
+  if (jsonMode()) return;
+  if (currentSpinner) {
+    currentSpinner.fail(text);
+    currentSpinner = null;
+  }
+}
+function stopSpinner() {
+  if (jsonMode()) return;
+  if (currentSpinner) {
+    currentSpinner.stop();
+    currentSpinner = null;
+  }
+}
+function updateSpinner(text) {
+  if (jsonMode()) return;
+  if (currentSpinner) {
+    currentSpinner.text = text;
+  }
+}
+
 // src/commands/account.ts
 function registerAccountCommands(program2) {
   const account = program2.command("account").description("Manage your user account");
@@ -594,7 +632,7 @@ Root access: ${hasAccess ? colors.success("yes") : colors.error("no")}
     try {
       if (!isLoggedIn()) throw new AuthError();
       if (!shouldSkipConfirmation()) {
-        const { confirm: confirmFn } = await import("./prompts-QQ2FZKQT.js");
+        const { confirm: confirmFn } = await import("./prompts-JH6YBHHV.js");
         const ok = await confirmFn(
           `Remove user "${userId}" from the organization?`,
           false,
@@ -621,7 +659,7 @@ Root access: ${hasAccess ? colors.success("yes") : colors.error("no")}
   account.command("assign-permissions").argument("<user-id>", "User ID").option("--role <role>", "Role: admin, member").description("Assign permissions/role to a member (org owner only)").action(async (userId, options) => {
     try {
       if (!isLoggedIn()) throw new AuthError();
-      const { select: selectFn } = await import("./prompts-QQ2FZKQT.js");
+      const { select: selectFn } = await import("./prompts-JH6YBHHV.js");
       const role = options.role || await selectFn(
         "Role:",
         [
@@ -1506,7 +1544,7 @@ function registerAppsCommands(program2) {
         throw new NotFoundError("Application", appIdentifier, suggestions);
       }
       if (!shouldSkipConfirmation()) {
-        const { confirm: confirm2 } = await import("./prompts-QQ2FZKQT.js");
+        const { confirm: confirm2 } = await import("./prompts-JH6YBHHV.js");
         const confirmed = await confirm2(
           `Stop application "${app.name}"?`,
           false,
@@ -1824,7 +1862,7 @@ function registerAppsCommands(program2) {
         throw new NotFoundError("Application", appIdentifier);
       }
       if (!shouldSkipConfirmation()) {
-        const { confirm: confirm2 } = await import("./prompts-QQ2FZKQT.js");
+        const { confirm: confirm2 } = await import("./prompts-JH6YBHHV.js");
         const confirmed = await confirm2(
           `Disconnect source provider from "${app.name}"?`,
           false,
@@ -3265,7 +3303,7 @@ function registerAuthCommands(program2) {
           () => input("Token name (e.g., ci-deploy):")
         );
       }
-      const { getApiClient: getApiClient2 } = await import("./api-QAKANRFX.js");
+      const { getApiClient: getApiClient2 } = await import("./api-QVUO7EWV.js");
       const client = getApiClient2();
       const profile = getCurrentProfile();
       let keyOrg = profile?.organizationId;
@@ -3562,33 +3600,1062 @@ function registerBackupsCommands(program2) {
       handleError(err);
     }
   });
-  backups.command("files").argument("<destination-id>", "Backup destination ID").description("List backup files in a destination").option("-s, --search <path>", "Search path or prefix", "").action(async (destinationId, options) => {
+  backups.command("files").argument("<destination-id>", "Backup destination ID").description("List backup files in a destination").option("-s, --search <path>", "Search path or prefix", "").action(async (destinationId, options) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Listing backup files...");
+      const files = await client.backup.listBackupFiles.query({
+        destinationId,
+        search: options.search || ""
+      });
+      succeedSpinner();
+      if (isJsonMode()) {
+        outputData(files);
+        return;
+      }
+      const list = Array.isArray(files) ? files : [];
+      if (!list.length) {
+        log("");
+        log("No backup files found.");
+        return;
+      }
+      log("");
+      table(
+        ["NAME", "SIZE", "TYPE"],
+        list.map((f) => [
+          f.Name || f.Path || "",
+          f.IsDir ? colors.dim("DIR") : formatBytes2(f.Size || 0),
+          f.IsDir ? colors.dim("directory") : "file"
+        ])
+      );
+      log("");
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  backups.command("download-url").argument("<destination-id>", "Backup destination ID").argument("<backup-file>", "Backup file path").description("Get a signed download URL for a backup file").action(async (destinationId, backupFile) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Generating download URL...");
+      const result = await client.backup.getBackupDownloadUrl.mutate({
+        destinationId,
+        backupFile
+      });
+      succeedSpinner();
+      if (isJsonMode()) {
+        outputData(result);
+        return;
+      }
+      log("");
+      log(`Download URL for ${colors.cyan(backupFile)}:`);
+      log("");
+      log(`  ${colors.cyan(result.url || String(result))}`);
+      log("");
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  backups.command("backup-web").argument("<backup-id>", "Backup configuration ID").description("Manually trigger a web server / app backup").action(async (backupId) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Triggering web server backup...");
+      const result = await client.backup.manualBackupWebServer.mutate({
+        backupId
+      });
+      succeedSpinner("Web server backup triggered!");
+      if (isJsonMode()) outputData(result);
+      else {
+        log("");
+        log(colors.success("Backup job started. Check logs for progress."));
+        log("");
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  backups.command("restore").argument("<backup-id>", "Backup configuration ID").argument("<backup-file>", "Backup file name to restore").description("Restore a backup with streaming log output").action(async (backupId, backupFile) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      if (!shouldSkipConfirmation()) {
+        const { confirm: confirmFn } = await import("./prompts-JH6YBHHV.js");
+        const ok = await confirmFn(
+          `Restore backup file "${backupFile}"? This will overwrite current data.`,
+          false
+        );
+        if (!ok) {
+          log("Cancelled.");
+          return;
+        }
+      }
+      const client = getApiClient();
+      const _spinner = startSpinner("Starting restore...");
+      const result = await client.backup.restoreBackupWithLogs.mutate({
+        backupId,
+        backupFile
+      });
+      succeedSpinner("Restore initiated!");
+      if (isJsonMode()) outputData(result);
+      else {
+        log("");
+        log(
+          colors.success("Restore job started. Monitor logs for progress.")
+        );
+        if (result?.jobId)
+          log(`  Job ID: ${colors.dim(result.jobId)}`);
+        log("");
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+}
+function formatDate3(date) {
+  if (!date) return colors.dim("-");
+  return new Date(date).toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric"
+  });
+}
+function formatBytes2(bytes) {
+  if (!bytes || bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / 1024 ** i).toFixed(1)} ${units[i]}`;
+}
+
+// src/commands/billing.ts
+import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+import open3 from "open";
+
+// src/lib/billing-upgrade.ts
+function resolveTarget(input2) {
+  if (input2.kind === "plan") return input2.planKey ?? "";
+  if (input2.kind === "addon") {
+    return input2.addonKey ?? input2.addons?.[0]?.addonKey ?? "";
+  }
+  return input2.planKey ?? "shared";
+}
+function chargeFromResult(result) {
+  if (typeof result?.proratedChargeHalalas === "number") {
+    return result.proratedChargeHalalas;
+  }
+  if (typeof result?.proratedCharge === "number") return result.proratedCharge;
+  return void 0;
+}
+async function performBillingChange(client, input2) {
+  const kind = input2.kind;
+  const target = resolveTarget(input2);
+  let result;
+  if (kind === "plan") {
+    result = await client.subscription.changePlan.mutate({
+      planKey: input2.planKey,
+      planQuantity: input2.quantity,
+      billingPeriod: input2.billingPeriod,
+      addons: input2.addons
+    });
+  } else if (kind === "addon") {
+    const addons = input2.addons ?? (input2.addonKey ? [{ addonKey: input2.addonKey, quantity: input2.quantity ?? 1 }] : []);
+    result = await client.subscription.purchaseAddons.mutate({ addons });
+  } else {
+    result = await client.subscription.setPlanQuantity.mutate({
+      quantity: input2.quantity
+    });
+  }
+  return finalizeBillingMutation(client, result, {
+    kind,
+    target,
+    wait: input2.wait,
+    timeoutMs: input2.timeoutMs,
+    openBrowser: input2.openBrowser,
+    onCheckoutOpened: input2.onCheckoutOpened
+  });
+}
+async function finalizeBillingMutation(client, result, ctx) {
+  const { kind, target } = ctx;
+  const amountHalalas = chargeFromResult(result ?? {});
+  if (result?.applied) {
+    return {
+      status: "applied",
+      kind,
+      target,
+      amountHalalas,
+      effectiveAt: result?.effectiveAt
+    };
+  }
+  if (!result?.paymentUrl || !result?.orderId) {
+    return {
+      status: "deferred",
+      kind,
+      target,
+      amountHalalas,
+      effectiveAt: result?.effectiveAt
+    };
+  }
+  const orderId = result.orderId;
+  const paymentUrl = result.paymentUrl;
+  if (!ctx.wait) {
+    return {
+      status: "payment_required",
+      kind,
+      target,
+      orderId,
+      paymentUrl,
+      amountHalalas
+    };
+  }
+  ctx.onCheckoutOpened?.({ orderId, paymentUrl });
+  if (ctx.openBrowser) {
+    try {
+      await ctx.openBrowser(paymentUrl);
+    } catch {
+    }
+  }
+  const final = await pollCheckoutUntilTerminal(client, orderId, {
+    timeoutMs: ctx.timeoutMs ?? 6e5,
+    intervalMs: 4e3
+  });
+  const status = final.status === "PAID" ? "paid" : final.status === "FAILED" ? "failed" : final.status === "EXPIRED" ? "expired" : "pending_timeout";
+  return {
+    status,
+    kind,
+    target,
+    orderId,
+    paymentUrl,
+    amountHalalas,
+    failureReason: final.failureReason
+  };
+}
+function nextCommandFor(result) {
+  if ((result.status === "payment_required" || result.status === "pending_timeout") && result.orderId) {
+    return `tarout billing wait ${result.orderId} --timeout 600`;
+  }
+  return void 0;
+}
+function formatHalalas(halalas) {
+  if (typeof halalas !== "number") return void 0;
+  return `${(halalas / 100).toFixed(2)} SAR`;
+}
+function emitBillingResult(result, opts) {
+  const label = opts?.label ?? result.target;
+  const nextCommand = nextCommandFor(result);
+  const amount = formatHalalas(result.amountHalalas);
+  const envelope = {
+    status: result.status,
+    kind: result.kind,
+    target: result.target,
+    ...result.orderId ? { orderId: result.orderId } : {},
+    ...result.paymentUrl ? { paymentUrl: result.paymentUrl } : {},
+    ...typeof result.amountHalalas === "number" ? { amountHalalas: result.amountHalalas } : {},
+    ...nextCommand ? { nextCommand } : {}
+  };
+  switch (result.status) {
+    case "applied":
+      outputData({ ...envelope, hint: "Applied immediately. Retry your last action." });
+      box("Plan changed", [
+        `${label}: ${colors.success("applied immediately")}`,
+        amount ? `Charged: ${amount}` : ""
+      ].filter(Boolean));
+      return ExitCode.SUCCESS;
+    case "paid":
+      outputData({ ...envelope, hint: "Payment confirmed. Retry your last action." });
+      box("Payment confirmed", [
+        `${label}: ${colors.success("subscription is active")}`,
+        "Retry your last action."
+      ]);
+      return ExitCode.SUCCESS;
+    case "deferred":
+      outputData({
+        ...envelope,
+        hint: "Change staged for the end of the current billing period."
+      });
+      box("Plan change staged", [
+        `${label}: will apply at the end of the current billing period.`
+      ]);
+      return ExitCode.SUCCESS;
+    case "payment_required":
+      outputData({
+        ...envelope,
+        hint: `Open paymentUrl to complete checkout, then run \`${nextCommand}\` \u2014 or re-run with --wait.`
+      });
+      box("Payment required", [
+        `${label}`,
+        `Open: ${colors.cyan(result.paymentUrl ?? "")}`,
+        `Order ID: ${colors.dim(result.orderId ?? "")}`,
+        `Then: ${colors.dim(nextCommand ?? "")}`
+      ]);
+      return ExitCode.SUCCESS;
+    case "pending_timeout":
+      outputError(
+        "CHECKOUT_PENDING",
+        "Hosted checkout is still pending after the timeout \u2014 resume polling or finish payment in the browser.",
+        { ...envelope }
+      );
+      box("Still waiting", [
+        `Order ID: ${colors.dim(result.orderId ?? "")}`,
+        `Run: ${colors.dim(nextCommand ?? "")}`
+      ]);
+      return ExitCode.CHECKOUT_PENDING;
+    default: {
+      const code = result.status === "expired" ? "CHECKOUT_EXPIRED" : "CHECKOUT_FAILED";
+      outputError(
+        code,
+        result.failureReason ?? `Checkout ${result.status}.`,
+        { ...envelope }
+      );
+      box("Payment failed", [
+        `Order ID: ${colors.dim(result.orderId ?? "")}`,
+        `Reason: ${result.failureReason ?? result.status}`
+      ]);
+      return ExitCode.GENERAL_ERROR;
+    }
+  }
+}
+async function pollCheckoutUntilTerminal(client, orderId, opts) {
+  const deadline = Date.now() + opts.timeoutMs;
+  let lastStatus = "";
+  while (Date.now() < deadline) {
+    const r2 = await client.subscription.pollCheckoutStatus.query({ orderId });
+    if (r2.status !== lastStatus) {
+      if (isJsonMode()) {
+        outputJsonLine({
+          type: "event",
+          event: "checkout_status",
+          orderId,
+          status: r2.status
+        });
+      }
+      lastStatus = r2.status;
+    }
+    if (r2.status !== "PENDING") {
+      return {
+        status: r2.status,
+        paidAt: r2.paidAt,
+        failedAt: r2.failedAt,
+        failureReason: r2.failureReason
+      };
+    }
+    await new Promise((res) => setTimeout(res, opts.intervalMs));
+  }
+  const r = await client.subscription.pollCheckoutStatus.query({ orderId });
+  return {
+    status: r.status,
+    paidAt: r.paidAt,
+    failedAt: r.failedAt,
+    failureReason: r.failureReason
+  };
+}
+
+// src/commands/billing.ts
+function reportBillingResult(result, label) {
+  const code = emitBillingResult(result, { label });
+  if (code !== ExitCode.SUCCESS) exit(code);
+}
+function browserOpener(noOpen) {
+  if (isJsonMode() || noOpen) return void 0;
+  return async (url) => {
+    await open3(url);
+  };
+}
+function isConflictError(err) {
+  const e = err;
+  return (e?.code ?? e?.data?.code) === "CONFLICT";
+}
+function registerBillingCommands(program2) {
+  const billing = program2.command("billing").description("Manage subscription and billing");
+  billing.command("status").description("Show current subscription and entitlements").action(async () => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Fetching subscription...");
+      const subscription = await client.subscription.getCurrent.query();
+      succeedSpinner();
+      if (isJsonMode()) {
+        outputData(subscription);
+        return;
+      }
+      log("");
+      log(colors.bold("Current Subscription"));
+      log("");
+      if (!subscription || !subscription.planKey) {
+        log(`  Plan: ${colors.dim("No active subscription (free tier)")}`);
+      } else {
+        log(`  Plan: ${colors.cyan(subscription.planKey)}`);
+        if (subscription.planQuantity && subscription.planQuantity > 1) {
+          log(`  Quantity: ${subscription.planQuantity}`);
+        }
+        log(`  Status: ${formatSubStatus(subscription.status || "active")}`);
+        if (subscription.currentPeriodEnd) {
+          log(`  Renews: ${formatDate4(subscription.currentPeriodEnd)}`);
+        }
+        if (subscription.cancelAtPeriodEnd) {
+          log(`  ${colors.warn("\u26A0 Cancels at end of billing period")}`);
+        }
+      }
+      if (subscription?.items && subscription.items.length > 0) {
+        log("");
+        log(colors.bold("Add-ons"));
+        table(
+          ["ADDON", "QUANTITY"],
+          subscription.items.map((item) => [
+            colors.cyan(item.addonKey || item.key || ""),
+            String(item.quantity || 1)
+          ])
+        );
+      }
+      log("");
+      log(`To view available plans: ${colors.dim("tarout billing plans")}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("plans").description("List available subscription plans").action(async () => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Fetching plans...");
+      const catalog = await client.subscription.getCatalog.query();
+      succeedSpinner();
+      if (isJsonMode()) {
+        outputData(catalog);
+        return;
+      }
+      log("");
+      log(colors.bold("Available Plans"));
+      log("");
+      const plans = catalog?.plans || catalog || [];
+      if (!Array.isArray(plans) || plans.length === 0) {
+        log("No plans available.");
+        return;
+      }
+      table(
+        ["PLAN", "PRICE", "DESCRIPTION"],
+        plans.map((p) => [
+          colors.cyan(p.planKey || p.key || p.name || ""),
+          p.priceHalalas ? `${(p.priceHalalas / 100).toFixed(2)} SAR/mo` : colors.dim("Free"),
+          p.description || ""
+        ])
+      );
+      log("");
+      log(`To upgrade: ${colors.dim("tarout billing upgrade <plan>")}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("upgrade").argument("[plan]", "Plan key to switch to (alias: --plan)").description("Upgrade or change subscription plan").option(
+    "--plan <key>",
+    "Plan key (alias for the positional argument; useful for agent invocations)"
+  ).option(
+    "-q, --quantity <n>",
+    "Plan quantity (for multi-slot plans)",
+    Number.parseInt
+  ).option(
+    "--billing-period <period>",
+    "Billing period: monthly or yearly (yearly = 10\xD7 monthly, 2 months free)",
+    parseBillingPeriod
+  ).option(
+    "--addon <key[:qty]>",
+    "Bundled addon to purchase with the plan change (repeatable, e.g. --addon db.standard:2)",
+    collectAddon,
+    []
+  ).option(
+    "-w, --wait",
+    "After hosted-checkout opens, poll status until the payment is confirmed"
+  ).option(
+    "--timeout <seconds>",
+    "Maximum wait time in seconds (default 600)",
+    (v) => Number.parseInt(v, 10),
+    600
+  ).option(
+    "--no-open",
+    "Do not auto-open the payment URL in the default browser"
+  ).action(async (planKey, options) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      let targetPlan = planKey || options.plan;
+      const billingPeriod = options.billingPeriod;
+      const addons = Array.isArray(options.addon) && options.addon.length > 0 ? options.addon : void 0;
+      if (!targetPlan) {
+        const _spinner = startSpinner("Fetching plans...");
+        const catalog = await client.subscription.getCatalog.query();
+        succeedSpinner();
+        const plans = catalog?.plans || catalog || [];
+        if (!Array.isArray(plans) || plans.length === 0) {
+          log("No plans available.");
+          return;
+        }
+        targetPlan = await select(
+          "Select a plan:",
+          plans.map((p) => ({
+            name: `${p.planKey || p.key || p.name} ${p.priceHalalas ? `(${(p.priceHalalas / 100).toFixed(2)} SAR/mo)` : "(Free)"}`,
+            value: p.planKey || p.key || p.name
+          })),
+          {
+            field: "plan",
+            flag: "--plan",
+            context: {
+              available: plans.map((p) => ({
+                key: p.planKey || p.key || p.name,
+                priceHalalas: p.priceHalalas ?? 0
+              }))
+            }
+          }
+        );
+      }
+      if (!targetPlan) {
+        throw new Error("No plan selected");
+      }
+      const _previewSpinner = startSpinner("Calculating change...");
+      let preview;
+      try {
+        preview = await client.subscription.previewPlanChange.query({
+          planKey: targetPlan,
+          planQuantity: options.quantity,
+          billingPeriod,
+          addons
+        });
+        succeedSpinner();
+      } catch {
+        failSpinner();
+        preview = null;
+      }
+      if (!shouldSkipConfirmation()) {
+        log("");
+        log(`Plan: ${colors.cyan(targetPlan)}`);
+        if (options.quantity) log(`Quantity: ${options.quantity}`);
+        if (billingPeriod) log(`Billing period: ${billingPeriod}`);
+        if (addons && addons.length > 0) {
+          log(
+            `Addons: ${addons.map((a) => `${a.addonKey}\xD7${a.quantity}`).join(", ")}`
+          );
+        }
+        const amountDueHalalas = typeof preview?.proratedChargeHalalas === "number" ? preview.proratedChargeHalalas : void 0;
+        if (amountDueHalalas !== void 0) {
+          log(
+            `Amount due now: ${colors.bold(`${(amountDueHalalas / 100).toFixed(2)} SAR`)} ${colors.dim("(incl. 15% VAT for SA orgs at checkout)")}`
+          );
+        }
+        if (typeof preview?.newPeriodTotalHalalas === "number") {
+          log(
+            `New recurring total: ${(preview.newPeriodTotalHalalas / 100).toFixed(2)} SAR`
+          );
+        }
+        log("");
+        const confirmed = await confirm(
+          `Switch to plan "${targetPlan}"?`,
+          false,
+          {
+            field: "confirm_upgrade",
+            flag: "--yes",
+            context: {
+              plan: targetPlan,
+              quantity: options.quantity,
+              billingPeriod,
+              addons,
+              amountDueHalalas
+            }
+          }
+        );
+        if (!confirmed) {
+          log("Cancelled.");
+          return;
+        }
+      }
+      const _changeSpinner = startSpinner("Changing plan...");
+      const result = await performBillingChange(client, {
+        kind: "plan",
+        planKey: targetPlan,
+        quantity: options.quantity,
+        billingPeriod,
+        addons,
+        wait: options.wait,
+        timeoutMs: options.timeout * 1e3,
+        openBrowser: browserOpener(options.open === false),
+        onCheckoutOpened: ({ orderId, paymentUrl }) => {
+          if (isJsonMode()) {
+            outputJsonLine({
+              type: "event",
+              event: "checkout_started",
+              orderId,
+              paymentUrl
+            });
+          } else {
+            log("");
+            log("Open this URL to complete payment:");
+            log(`  ${colors.cyan(paymentUrl)}`);
+            log(`Order ID: ${colors.dim(orderId)}`);
+            log(`Polling for confirmation (up to ${options.timeout}s)...`);
+          }
+        }
+      });
+      succeedSpinner("Plan change processed.");
+      reportBillingResult(result, `Plan: ${targetPlan}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("confirm").argument("<orderId>", "Order ID returned by `billing upgrade`").description("Manually confirm a pending checkout (skips browser flow)").action(async (orderId) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _s = startSpinner("Confirming checkout...");
+      const result = await client.subscription.confirmCheckout.mutate({
+        orderId
+      });
+      succeedSpinner("Checkout confirmed.");
+      const mapped = {
+        status: result?.applied ? "paid" : "payment_required",
+        kind: "plan",
+        target: orderId,
+        orderId,
+        ...result?.paymentUrl ? { paymentUrl: result.paymentUrl } : {}
+      };
+      reportBillingResult(mapped, `Order ${orderId.slice(0, 8)}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("wait").argument("<orderId>", "Order ID to wait on").description("Poll a pending checkout until it resolves").option(
+    "--timeout <seconds>",
+    "Maximum wait time in seconds (default 600)",
+    (v) => Number.parseInt(v, 10),
+    600
+  ).action(async (orderId, options) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      if (isJsonMode()) {
+        outputJsonLine({
+          type: "event",
+          event: "checkout_polling_started",
+          orderId,
+          timeoutSeconds: options.timeout
+        });
+      }
+      const final = await pollCheckoutUntilTerminal(client, orderId, {
+        timeoutMs: options.timeout * 1e3,
+        intervalMs: 4e3
+      });
+      const result = {
+        status: final.status === "PAID" ? "paid" : final.status === "FAILED" ? "failed" : final.status === "EXPIRED" ? "expired" : "pending_timeout",
+        kind: "plan",
+        target: orderId,
+        orderId,
+        failureReason: final.failureReason
+      };
+      reportBillingResult(result, `Order ${orderId.slice(0, 8)}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("cancel").description("Cancel current subscription (at period end)").action(async () => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      if (!shouldSkipConfirmation()) {
+        log("");
+        log(
+          colors.warn(
+            "Cancelling your subscription will downgrade to free tier at the end of the billing period."
+          )
+        );
+        log("");
+        const confirmed = await confirm(
+          "Are you sure you want to cancel your subscription?",
+          false,
+          { field: "confirm_cancel", flag: "--yes" }
+        );
+        if (!confirmed) {
+          log("Cancelled.");
+          return;
+        }
+      }
+      const client = getApiClient();
+      const _spinner = startSpinner("Cancelling subscription...");
+      await client.subscription.cancel.mutate();
+      succeedSpinner("Subscription scheduled for cancellation");
+      if (isJsonMode()) {
+        outputData({ cancelled: true });
+      } else {
+        log("");
+        log(
+          "Your subscription will remain active until the end of the current billing period."
+        );
+        log(`To undo: ${colors.dim("tarout billing resume")}`);
+        log("");
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("resume").description("Resume a cancelled subscription").action(async () => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Resuming subscription...");
+      await client.subscription.resume.mutate();
+      succeedSpinner("Subscription resumed!");
+      if (isJsonMode()) {
+        outputData({ resumed: true });
+      } else {
+        log("");
+        log(
+          colors.success(
+            "Your subscription has been resumed and will continue normally."
+          )
+        );
+        log("");
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("addon:add").argument("<addon>", "Addon key to add").option("-q, --quantity <n>", "Addon quantity", Number.parseInt).option(
+    "-w, --wait",
+    "After hosted-checkout opens, poll status until the payment is confirmed"
+  ).option(
+    "--timeout <seconds>",
+    "Maximum wait time in seconds (default 600)",
+    (v) => Number.parseInt(v, 10),
+    600
+  ).option("--no-open", "Do not auto-open the payment URL in the browser").description("Add a new addon line (extra db/storage/etc. slot)").action(async (addonKey, options) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const quantity = options.quantity || 1;
+      if (!shouldSkipConfirmation()) {
+        log("");
+        log(`Addon: ${colors.cyan(addonKey)}`);
+        log(`Quantity: ${quantity}`);
+        log("");
+        const confirmed = await confirm(
+          `Add addon "${addonKey}" \xD7 ${quantity}?`,
+          false,
+          {
+            field: "confirm_addon_add",
+            flag: "--yes",
+            context: { addonKey, quantity }
+          }
+        );
+        if (!confirmed) {
+          log("Cancelled.");
+          return;
+        }
+      }
+      const client = getApiClient();
+      const _spinner = startSpinner("Adding addon...");
+      let raw;
+      try {
+        raw = await client.subscription.addAddon.mutate({
+          addonKey,
+          quantity
+        });
+      } catch (err) {
+        failSpinner();
+        if (isConflictError(err)) {
+          const nextCommand = `tarout billing addon:quantity ${addonKey} <newQty>`;
+          outputError(
+            "ADDON_EXISTS",
+            `Addon "${addonKey}" is already on your subscription \u2014 change its quantity instead of adding it again.`,
+            { addonKey, nextCommand }
+          );
+          if (!isJsonMode()) {
+            box("Addon already present", [
+              `Use: ${colors.dim(nextCommand)}`,
+              `Or buy more slots: ${colors.dim(`tarout billing addon:buy ${addonKey} --wait`)}`
+            ]);
+          }
+          exit(ExitCode.INVALID_ARGUMENTS);
+          return;
+        }
+        throw err;
+      }
+      succeedSpinner("Addon processed.");
+      const result = await finalizeBillingMutation(client, raw, {
+        kind: "addon",
+        target: addonKey,
+        wait: options.wait,
+        timeoutMs: options.timeout * 1e3,
+        openBrowser: browserOpener(options.open === false)
+      });
+      reportBillingResult(result, `Addon: ${addonKey} \xD7${quantity}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("addon:remove").argument("<addon>", "Addon key to remove").description("Remove an addon").action(async (addonKey) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      if (!shouldSkipConfirmation()) {
+        const confirmed = await confirm(
+          `Remove addon "${addonKey}"?`,
+          false,
+          {
+            field: "confirm_addon_remove",
+            flag: "--yes",
+            context: { addonKey }
+          }
+        );
+        if (!confirmed) {
+          log("Cancelled.");
+          return;
+        }
+      }
+      const client = getApiClient();
+      const _spinner = startSpinner("Removing addon...");
+      await client.subscription.removeAddon.mutate({ addonKey });
+      succeedSpinner("Addon removed!");
+      if (isJsonMode()) {
+        outputData({ removed: true, addonKey });
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("plan:quantity").argument("<quantity>", "New plan quantity", Number.parseInt).option(
+    "-w, --wait",
+    "After hosted-checkout opens, poll status until the payment is confirmed"
+  ).option(
+    "--timeout <seconds>",
+    "Maximum wait time in seconds (default 600)",
+    (v) => Number.parseInt(v, 10),
+    600
+  ).option("--no-open", "Do not auto-open the payment URL in the browser").description("Set quantity for a multi-slot plan (adds/removes app slots)").action(async (quantity, options) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Updating plan quantity...");
+      const result = await performBillingChange(client, {
+        kind: "plan_quantity",
+        quantity,
+        wait: options.wait,
+        timeoutMs: options.timeout * 1e3,
+        openBrowser: browserOpener(options.open === false)
+      });
+      succeedSpinner("Plan quantity processed.");
+      reportBillingResult(result, `Plan quantity: ${quantity}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("addon:quantity").argument("<addon>", "Addon key").argument("<quantity>", "New quantity", Number.parseInt).description("Update quantity for an existing addon").action(async (addonKey, quantity) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Updating addon quantity...");
+      const result = await client.subscription.updateAddonQuantity.mutate({
+        addonKey,
+        quantity
+      });
+      succeedSpinner("Addon quantity updated!");
+      if (isJsonMode()) outputData(result);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("addon:preview").argument("<addon>", "Addon key").option("-q, --quantity <n>", "Quantity", Number.parseInt).description("Preview cost of purchasing addons").action(async (addonKey, options) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Calculating preview...");
+      const preview = await client.subscription.previewAddonsPurchase.query({
+        addons: [{ addonKey, quantity: options.quantity || 1 }]
+      });
+      succeedSpinner();
+      if (isJsonMode()) {
+        outputData(preview);
+        return;
+      }
+      const p = preview;
+      log("");
+      log(colors.bold("Addon Purchase Preview"));
+      log(`  Addon:      ${colors.cyan(addonKey)}`);
+      log(`  Quantity:   ${options.quantity || 1}`);
+      if (typeof p?.totalProratedHalalas === "number") {
+        log(
+          `  Amount Due: ${colors.bold(`${(p.totalProratedHalalas / 100).toFixed(2)} SAR`)} ${colors.dim("(incl. 15% VAT for SA orgs at checkout)")}`
+        );
+      }
+      if (typeof p?.newPeriodTotalHalalas === "number") {
+        log(
+          `  New total:  ${(p.newPeriodTotalHalalas / 100).toFixed(2)} SAR`
+        );
+      }
+      log("");
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("addon:buy").argument("<addon>", "Addon key").option("-q, --quantity <n>", "Quantity", Number.parseInt).option(
+    "-w, --wait",
+    "After hosted-checkout opens, poll status until the payment is confirmed"
+  ).option(
+    "--timeout <seconds>",
+    "Maximum wait time in seconds (default 600)",
+    (v) => Number.parseInt(v, 10),
+    600
+  ).option("--no-open", "Do not auto-open the payment URL in the browser").description("Purchase addon slots (extra db/storage/etc.)").action(async (addonKey, options) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const quantity = options.quantity || 1;
+      if (!shouldSkipConfirmation()) {
+        log(`
+Purchase ${quantity}\xD7 ${colors.cyan(addonKey)}?`);
+        const confirmed = await confirm("Proceed?", false, {
+          field: "confirm_addon_buy",
+          flag: "--yes",
+          context: { addonKey, quantity }
+        });
+        if (!confirmed) {
+          log("Cancelled.");
+          return;
+        }
+      }
+      const client = getApiClient();
+      const _spinner = startSpinner("Purchasing addon...");
+      const result = await performBillingChange(client, {
+        kind: "addon",
+        addonKey,
+        quantity,
+        wait: options.wait,
+        timeoutMs: options.timeout * 1e3,
+        openBrowser: browserOpener(options.open === false)
+      });
+      succeedSpinner("Addon purchase processed.");
+      reportBillingResult(result, `Addon: ${addonKey} \xD7${quantity}`);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("plan:cancel-pending").description("Cancel a pending plan change (keeps current plan)").action(async () => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      if (!shouldSkipConfirmation()) {
+        const confirmed = await confirm(
+          "Cancel the pending plan change?",
+          false,
+          { field: "confirm_pending_cancel", flag: "--yes" }
+        );
+        if (!confirmed) {
+          log("Cancelled.");
+          return;
+        }
+      }
+      const client = getApiClient();
+      const _spinner = startSpinner("Cancelling pending change...");
+      await client.subscription.cancelPendingPlanChange.mutate();
+      succeedSpinner("Pending plan change cancelled!");
+      if (isJsonMode()) outputData({ cancelled: true });
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("checkout:confirm").argument("<session-id>", "Checkout session ID").description("Confirm a pending checkout session").action(async (sessionId) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Confirming checkout...");
+      const result = await client.subscription.confirmCheckout.mutate({
+        sessionId
+      });
+      succeedSpinner("Checkout confirmed!");
+      if (isJsonMode()) outputData(result);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("checkout:get").argument("<session-id>", "Checkout session ID").description("Get details of a checkout session").action(async (sessionId) => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Fetching checkout...");
+      const data = await client.payment.getCheckout.query({
+        sessionId
+      });
+      succeedSpinner();
+      if (isJsonMode()) outputData(data);
+      else {
+        const d = data;
+        log("");
+        log(colors.bold("Checkout Session"));
+        log(`  ID:     ${d.sessionId || sessionId}`);
+        log(`  Status: ${d.status || "-"}`);
+        log(
+          `  Amount: ${d.amount !== void 0 ? `${(d.amount / 100).toFixed(2)} SAR` : "-"}`
+        );
+        log("");
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("checkout:pay").argument("<session-id>", "Checkout session ID").description("Submit card payment for a checkout session").option("--card-number <n>", "Card number").option("--exp-month <m>", "Expiry month").option("--exp-year <y>", "Expiry year").option("--cvv <cvv>", "CVV").option("--name <name>", "Cardholder name").action(async (sessionId, options) => {
     try {
       if (!isLoggedIn()) throw new AuthError();
       const client = getApiClient();
-      const _spinner = startSpinner("Listing backup files...");
-      const files = await client.backup.listBackupFiles.query({
-        destinationId,
-        search: options.search || ""
+      const _spinner = startSpinner("Processing payment...");
+      const result = await client.payment.submitCardPayment.mutate({
+        sessionId,
+        cardNumber: options.cardNumber,
+        expMonth: options.expMonth,
+        expYear: options.expYear,
+        cvv: options.cvv,
+        cardholderName: options.name
       });
+      succeedSpinner("Payment submitted!");
+      if (isJsonMode()) outputData(result);
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("usage").description("Show resource usage breakdown").action(async () => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Fetching usage...");
+      const data = await client.billing.getUsageBreakdown.query();
       succeedSpinner();
       if (isJsonMode()) {
-        outputData(files);
+        outputData(data);
         return;
       }
-      const list = Array.isArray(files) ? files : [];
+      const d = data;
+      log("");
+      log(colors.bold("Usage Breakdown"));
+      log(`  Apps:      ${d.apps ?? "-"}`);
+      log(`  Databases: ${d.databases ?? "-"}`);
+      log(`  Storage:   ${d.storage ?? "-"}`);
+      log(`  Domains:   ${d.domains ?? "-"}`);
+      log("");
+    } catch (err) {
+      handleError(err);
+    }
+  });
+  billing.command("resources").description("Show detailed resource usage and costs").action(async () => {
+    try {
+      if (!isLoggedIn()) throw new AuthError();
+      const client = getApiClient();
+      const _spinner = startSpinner("Fetching resource usage...");
+      const data = await client.billing.getDetailedResourceUsage.query();
+      succeedSpinner();
+      if (isJsonMode()) {
+        outputData(data);
+        return;
+      }
+      const list = Array.isArray(data) ? data : data?.resources || [];
       if (!list.length) {
-        log("");
-        log("No backup files found.");
+        log("\nNo active resources.\n");
         return;
       }
       log("");
       table(
-        ["NAME", "SIZE", "TYPE"],
-        list.map((f) => [
-          f.Name || f.Path || "",
-          f.IsDir ? colors.dim("DIR") : formatBytes2(f.Size || 0),
-          f.IsDir ? colors.dim("directory") : "file"
+        ["TYPE", "NAME", "COST (SAR)"],
+        list.map((r) => [
+          r.type || "-",
+          r.name || "-",
+          r.cost !== void 0 ? (r.cost / 100).toFixed(2) : "-"
         ])
       );
       log("");
@@ -3596,85 +4663,132 @@ function registerBackupsCommands(program2) {
       handleError(err);
     }
   });
-  backups.command("download-url").argument("<destination-id>", "Backup destination ID").argument("<backup-file>", "Backup file path").description("Get a signed download URL for a backup file").action(async (destinationId, backupFile) => {
+  billing.command("trend").description("Show daily cost trend").option("--days <n>", "Number of days", "30").action(async (options) => {
     try {
       if (!isLoggedIn()) throw new AuthError();
       const client = getApiClient();
-      const _spinner = startSpinner("Generating download URL...");
-      const result = await client.backup.getBackupDownloadUrl.mutate({
-        destinationId,
-        backupFile
+      const _spinner = startSpinner("Fetching cost trend...");
+      const data = await client.billing.getDailyCostTrend.query({
+        days: Number.parseInt(options.days || "30")
       });
       succeedSpinner();
       if (isJsonMode()) {
-        outputData(result);
+        outputData(data);
+        return;
+      }
+      const list = Array.isArray(data) ? data : data?.trend || [];
+      if (!list.length) {
+        log("\nNo cost data found.\n");
         return;
       }
       log("");
-      log(`Download URL for ${colors.cyan(backupFile)}:`);
-      log("");
-      log(`  ${colors.cyan(result.url || String(result))}`);
+      log(colors.bold("Daily Cost Trend"));
+      table(
+        ["DATE", "COST (SAR)"],
+        list.map((d) => [
+          d.date || "-",
+          d.cost !== void 0 ? (d.cost / 100).toFixed(2) : "-"
+        ])
+      );
       log("");
     } catch (err) {
       handleError(err);
     }
   });
-  backups.command("backup-web").argument("<backup-id>", "Backup configuration ID").description("Manually trigger a web server / app backup").action(async (backupId) => {
+  billing.command("estimate").description("Estimate cost for a resource type").option("--type <type>", "Resource type (app, database, storage, domain)").option("--plan <plan>", "Plan key").action(async (options) => {
     try {
       if (!isLoggedIn()) throw new AuthError();
       const client = getApiClient();
-      const _spinner = startSpinner("Triggering web server backup...");
-      const result = await client.backup.manualBackupWebServer.mutate({
-        backupId
+      const _spinner = startSpinner("Calculating estimate...");
+      const data = await client.billing.getResourceEstimate.query({
+        resourceType: options.type,
+        planKey: options.plan
       });
-      succeedSpinner("Web server backup triggered!");
-      if (isJsonMode()) outputData(result);
-      else {
-        log("");
-        log(colors.success("Backup job started. Check logs for progress."));
-        log("");
+      succeedSpinner();
+      if (isJsonMode()) {
+        outputData(data);
+        return;
       }
+      const d = data;
+      log("");
+      log(colors.bold("Resource Estimate"));
+      log(
+        `  Monthly: ${d.monthly !== void 0 ? `${(d.monthly / 100).toFixed(2)} SAR` : "-"}`
+      );
+      log(
+        `  Hourly:  ${d.hourly !== void 0 ? `${(d.hourly / 100).toFixed(4)} SAR` : "-"}`
+      );
+      log("");
     } catch (err) {
       handleError(err);
     }
   });
-  backups.command("restore").argument("<backup-id>", "Backup configuration ID").argument("<backup-file>", "Backup file name to restore").description("Restore a backup with streaming log output").action(async (backupId, backupFile) => {
+  billing.command("active-resources").description("List all active billable resources").action(async () => {
     try {
       if (!isLoggedIn()) throw new AuthError();
-      if (!shouldSkipConfirmation()) {
-        const { confirm: confirmFn } = await import("./prompts-QQ2FZKQT.js");
-        const ok = await confirmFn(
-          `Restore backup file "${backupFile}"? This will overwrite current data.`,
-          false
-        );
-        if (!ok) {
-          log("Cancelled.");
-          return;
-        }
-      }
       const client = getApiClient();
-      const _spinner = startSpinner("Starting restore...");
-      const result = await client.backup.restoreBackupWithLogs.mutate({
-        backupId,
-        backupFile
-      });
-      succeedSpinner("Restore initiated!");
-      if (isJsonMode()) outputData(result);
-      else {
-        log("");
-        log(
-          colors.success("Restore job started. Monitor logs for progress.")
-        );
-        if (result?.jobId)
-          log(`  Job ID: ${colors.dim(result.jobId)}`);
-        log("");
+      const _spinner = startSpinner("Fetching active resources...");
+      const data = await client.billing.getActiveResources.query();
+      succeedSpinner();
+      if (isJsonMode()) {
+        outputData(data);
+        return;
+      }
+      const list = Array.isArray(data) ? data : data?.resources || [];
+      if (!list.length) {
+        log("\nNo active billable resources.\n");
+        return;
       }
+      log("");
+      table(
+        ["TYPE", "NAME", "STATUS", "PLAN"],
+        list.map((r) => [
+          r.type || "-",
+          r.name || "-",
+          r.status || "-",
+          r.plan || r.planKey || "-"
+        ])
+      );
+      log("");
     } catch (err) {
       handleError(err);
     }
   });
 }
-function formatDate3(date) {
+function collectAddon(value, previous) {
+  const [rawKey, rawQty] = value.split(":");
+  const addonKey = (rawKey || "").trim();
+  if (!addonKey) {
+    throw new InvalidArgumentError2(
+      `Invalid --addon value "${value}". Expected key[:qty] (e.g. db.standard:2).`
+    );
+  }
+  const quantity = rawQty === void 0 ? 1 : Number.parseInt(rawQty, 10);
+  if (!Number.isFinite(quantity) || quantity <= 0) {
+    throw new InvalidArgumentError2(
+      `Invalid --addon quantity in "${value}". Expected a positive integer.`
+    );
+  }
+  return [...previous, { addonKey, quantity }];
+}
+function parseBillingPeriod(raw) {
+  const v = raw.toLowerCase();
+  if (v === "monthly" || v === "yearly") return v;
+  throw new InvalidArgumentError2(
+    `Invalid --billing-period "${raw}". Expected "monthly" or "yearly".`
+  );
+}
+function formatSubStatus(status) {
+  const map = {
+    active: colors.success("active"),
+    trialing: colors.info("trialing"),
+    past_due: colors.warn("past due"),
+    cancelled: colors.error("cancelled"),
+    none: colors.dim("none")
+  };
+  return map[status] || status;
+}
+function formatDate4(date) {
   if (!date) return colors.dim("-");
   return new Date(date).toLocaleDateString("en-US", {
     month: "short",
@@ -3682,12 +4796,6 @@ function formatDate3(date) {
     year: "numeric"
   });
 }
-function formatBytes2(bytes) {
-  if (!bytes || bytes === 0) return "0 B";
-  const units = ["B", "KB", "MB", "GB", "TB"];
-  const i = Math.floor(Math.log(bytes) / Math.log(1024));
-  return `${(bytes / 1024 ** i).toFixed(1)} ${units[i]}`;
-}
 
 // src/lib/process.ts
 import { spawn } from "child_process";
@@ -4370,7 +5478,7 @@ function registerDbCommands(program2) {
           db2.name,
           getTypeLabel(db2.type),
           getStatusBadge(db2.status),
-          formatDate4(db2.created)
+          formatDate5(db2.created)
         ])
       );
       log("");
@@ -5226,7 +6334,7 @@ function findDatabase(databases, identifier) {
 function generateSlug2(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63);
 }
-function formatDate4(date) {
+function formatDate5(date) {
   const d = new Date(date);
   return d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
 }
@@ -5312,7 +6420,78 @@ import {
 import { tmpdir } from "os";
 import { basename, dirname, join as join3 } from "path";
 import { promisify } from "util";
-import open3 from "open";
+import open4 from "open";
+
+// src/lib/entitlement-remedy.ts
+var planKeyOf = (p) => p.planKey ?? p.key ?? "";
+var addonKeyOf = (a) => a.addonKey ?? a.key ?? "";
+function nextPlanForRequested(requested) {
+  const r = (requested ?? "free").trim().toLowerCase();
+  if (!r || r === "free") return "shared";
+  if (r === "shared") return "shared";
+  if (r === "dedicated" || r === "dedicated_small") return "dedicated_small";
+  if (r === "dedicated_medium") return "dedicated_medium";
+  if (r === "dedicated_large") return "dedicated_large";
+  return r;
+}
+function resolveEntitlementRemedy(failedKey, catalog, opts) {
+  const plans = catalog?.plans ?? [];
+  const addons = catalog?.addons ?? [];
+  if (failedKey?.startsWith("app.shared")) {
+    const sharedPlan = plans.find((p) => p.quantityAware);
+    const targetKey = sharedPlan ? planKeyOf(sharedPlan) : "shared";
+    const next = (opts?.currentSharedQuantity ?? 1) + 1;
+    return {
+      kind: "plan_quantity",
+      failedKey,
+      targetKey,
+      targetName: sharedPlan?.name,
+      priceHalalas: sharedPlan?.priceHalalas,
+      command: `tarout billing plan:quantity ${next} --wait`,
+      hint: `Your ${sharedPlan?.name ?? "Starter"} plan is quantity-aware \u2014 add an app slot by raising the plan quantity to ${next}.`
+    };
+  }
+  if (failedKey?.startsWith("app.dedicated") || failedKey?.startsWith("host.")) {
+    const requested = opts?.requestedPlan;
+    const target2 = requested && requested.toLowerCase().startsWith("dedicated") ? nextPlanForRequested(requested) : "dedicated_small";
+    const plan2 = plans.find((p) => planKeyOf(p) === target2);
+    return {
+      kind: "plan",
+      failedKey,
+      targetKey: target2,
+      targetName: plan2?.name,
+      priceHalalas: plan2?.priceHalalas,
+      command: `tarout billing upgrade ${target2} --wait`,
+      hint: `A dedicated host slot is required \u2014 upgrade to ${plan2?.name ?? target2}.`
+    };
+  }
+  if (failedKey?.startsWith("db.") || failedKey?.startsWith("storage.") || failedKey?.startsWith("domain") || failedKey?.startsWith("email")) {
+    const matched = addons.find(
+      (a) => a.grants?.some((g) => g.entitlementKey === failedKey)
+    ) ?? addons.find((a) => addonKeyOf(a) === failedKey.replace(/\.slots$/, ""));
+    const targetKey = matched ? addonKeyOf(matched) : failedKey.replace(/\.slots$/, "");
+    return {
+      kind: "addon",
+      failedKey,
+      targetKey,
+      targetName: matched?.name,
+      priceHalalas: matched?.priceHalalas,
+      command: `tarout billing addon:buy ${targetKey} --wait`,
+      hint: `Add a ${matched?.name ?? targetKey} slot with an addon purchase.`
+    };
+  }
+  const target = nextPlanForRequested(opts?.requestedPlan);
+  const plan = plans.find((p) => planKeyOf(p) === target);
+  return {
+    kind: "plan",
+    failedKey,
+    targetKey: target,
+    targetName: plan?.name,
+    priceHalalas: plan?.priceHalalas,
+    command: `tarout billing upgrade ${target} --wait`,
+    hint: `Upgrade to a paid plan (${plan?.name ?? target}) to continue.`
+  };
+}
 
 // src/lib/websocket.ts
 import WebSocket from "ws";
@@ -5477,7 +6656,7 @@ async function authenticateViaBrowser(action, apiUrl) {
   log(
     action === "register" ? "Opening browser to create your account..." : "Opening browser to authenticate..."
   );
-  await open3(authUrl);
+  await open4(authUrl);
   const _spinner = startSpinner(
     action === "register" ? "Waiting for account creation..." : "Waiting for authentication..."
   );
@@ -6093,48 +7272,37 @@ function formatPlanPrice(priceHalalas) {
   return `${(priceHalalas / 100).toFixed(2)} SAR/mo`;
 }
 async function runInlineUpgrade(client, planKey) {
-  const { pollCheckoutUntilTerminal } = await import("./billing-GUA4S2Y4.js");
   const _changing = startSpinner(`Switching to plan "${planKey}"...`);
-  const result = await client.subscription.changePlan.mutate({ planKey });
-  if (result?.applied) {
-    succeedSpinner("Plan applied.");
-    return true;
-  }
-  if (!result?.paymentUrl || !result?.orderId) {
-    failSpinner("Plan change did not return a payment URL.");
-    return false;
-  }
-  succeedSpinner("Checkout opened \u2014 waiting for payment confirmation.");
-  const orderId = result.orderId;
-  const paymentUrl = result.paymentUrl;
-  log("");
-  log(`Open this URL to complete payment:`);
-  log(`  ${colors.cyan(paymentUrl)}`);
-  log(`Order ID: ${colors.dim(orderId)}`);
-  try {
-    await open3(paymentUrl);
-  } catch {
-  }
-  const _pollSpinner = startSpinner("Polling for payment confirmation...");
-  const final = await pollCheckoutUntilTerminal(client, orderId, {
+  const result = await performBillingChange(client, {
+    kind: "plan",
+    planKey,
+    wait: true,
     timeoutMs: 6e5,
-    intervalMs: 4e3
+    openBrowser: isJsonMode() ? void 0 : async (url) => {
+      await open4(url);
+    },
+    onCheckoutOpened: ({ orderId, paymentUrl }) => {
+      log("");
+      log("Open this URL to complete payment:");
+      log(`  ${colors.cyan(paymentUrl)}`);
+      log(`Order ID: ${colors.dim(orderId)}`);
+    }
   });
-  if (final.status === "PAID") {
-    succeedSpinner("Payment confirmed.");
+  if (result.status === "applied" || result.status === "paid") {
+    succeedSpinner("Plan applied.");
     return true;
   }
   failSpinner(
-    final.status === "PENDING" ? "Payment still pending after 10 minutes." : `Payment ${final.status.toLowerCase()}.`
+    result.status === "deferred" ? "Plan change did not require an immediate payment." : result.status === "pending_timeout" ? "Payment still pending after 10 minutes." : `Payment ${result.status}.`
   );
-  if (final.failureReason) {
-    log(colors.error(final.failureReason));
+  if (result.failureReason) log(colors.error(result.failureReason));
+  if (result.orderId) {
+    log(
+      colors.dim(
+        `Resume later with: tarout billing wait ${result.orderId.slice(0, 8)} --timeout 600`
+      )
+    );
   }
-  log(
-    colors.dim(
-      `Resume later with: tarout billing wait ${orderId.slice(0, 8)} --timeout 600`
-    )
-  );
   return false;
 }
 async function getAppPlanChoices(client, preloadedOptions) {
@@ -6189,13 +7357,7 @@ function isEntitlementError(err) {
   return msg.includes("plan limit reached") || msg.includes("entitlement") || msg.includes("upgrade to add more") || msg.includes("active subscription") || msg.includes("free_not_allowed_on_paid_plan");
 }
 function inferSuggestedPlan(requested) {
-  const r = (requested ?? "free").trim().toLowerCase();
-  if (!r || r === "free") return "shared";
-  if (r === "shared") return "shared";
-  if (r === "dedicated" || r === "dedicated_small") return "dedicated_small";
-  if (r === "dedicated_medium") return "dedicated_medium";
-  if (r === "dedicated_large") return "dedicated_large";
-  return r;
+  return nextPlanForRequested(requested);
 }
 var ENTITLEMENT_LABELS = {
   "app.free.slots": "Free app slot",
@@ -6233,6 +7395,22 @@ function extractEntitlementKeyFromError(err) {
   const m = msg.match(/Plan limit reached for ([\w.]+)/i);
   return m?.[1];
 }
+async function emitNeedsUpgrade(client, err, requestedPlan, retryCommand) {
+  const message = err instanceof Error ? err.message : "Plan upgrade required";
+  const failedKey = extractEntitlementKeyFromError(err);
+  const catalog = await fetchCatalogSafely(client);
+  const remedy = resolveEntitlementRemedy(failedKey, catalog, { requestedPlan });
+  outputError("NEEDS_UPGRADE", message, {
+    failedEntitlementKey: failedKey,
+    remedyKind: remedy.kind,
+    // `suggestedPlan` retained for back-compat; now correct for every gate
+    // (the plan key, addon key, or quantity-aware plan to act on).
+    suggestedPlan: remedy.targetKey,
+    suggestedTarget: remedy.targetKey,
+    nextCommand: remedy.command,
+    hint: `${remedy.hint} Then retry: ${retryCommand}.`
+  });
+}
 async function promptUpgradeFromEntitlementError(client, err, requestedPlan) {
   const catalog = await fetchCatalogSafely(client);
   const allPlans = catalog?.plans ?? [];
@@ -6376,7 +7554,7 @@ async function openGitProviderSetup() {
   log(
     `No GitHub account is required if you keep using ${colors.dim("--source upload")}.`
   );
-  await open3(url);
+  await open4(url);
 }
 async function configureOptionalResources(client, profile, app, options, inspection) {
   const database = await resolveDatabaseChoice(options, inspection);
@@ -6787,28 +7965,58 @@ function resolveExplicitStorageRef(candidates, ref) {
   }
   return match;
 }
+function emitReuseNotice(payload) {
+  if (isJsonMode()) {
+    outputJsonLine({ type: "event", event: payload.event, ...payload.details });
+    return;
+  }
+  log(colors.warn(payload.humanMessage));
+  if (payload.humanHint) log(colors.dim(`  ${payload.humanHint}`));
+}
 async function finalizeDatabaseReuse(client, candidate, kind, requestedPlan, planExplicit) {
   let plan = candidate.plan;
   let upgraded = false;
   if (planExplicit && requestedPlan) {
     const cmp = compareResourcePlan(requestedPlan, candidate.plan);
+    const upgradeCommand = `tarout db upgrade ${candidate.name} --plan ${requestedPlan.toLowerCase()}`;
     if (cmp > 0) {
-      const ok = await confirmUpgrade(
-        `${formatDatabaseKind(kind)} ${candidate.name} is on ${candidate.plan}. Upgrade to ${requestedPlan} before attaching?`,
-        true,
-        kind === "postgres" ? "upgrade_postgres" : "upgrade_mysql"
-      );
-      if (ok) {
-        await runDatabaseUpgrade(client, kind, candidate.id, requestedPlan);
-        plan = requestedPlan;
-        upgraded = true;
+      if (isJsonMode() || shouldSkipConfirmation()) {
+        emitReuseNotice({
+          event: "reuse_plan_unchanged",
+          humanMessage: `${formatDatabaseKind(kind)} ${candidate.name} stays on ${candidate.plan}; requested ${requestedPlan} was not applied automatically.`,
+          humanHint: `Upgrade explicitly with: ${upgradeCommand}`,
+          details: {
+            resourceType: "database",
+            name: candidate.name,
+            currentPlan: candidate.plan,
+            requestedPlan,
+            nextCommand: upgradeCommand,
+            hint: "Database plan upgrades are billing-mutating and may require checkout; run the command above to upgrade."
+          }
+        });
+      } else {
+        const ok = await confirmUpgrade(
+          `${formatDatabaseKind(kind)} ${candidate.name} is on ${candidate.plan}. Upgrade to ${requestedPlan} before attaching?`,
+          true,
+          kind === "postgres" ? "upgrade_postgres" : "upgrade_mysql"
+        );
+        if (ok) {
+          await runDatabaseUpgrade(client, kind, candidate.id, requestedPlan);
+          plan = requestedPlan;
+          upgraded = true;
+        }
       }
-    } else if (cmp < 0 && !isJsonMode()) {
-      log(
-        colors.warn(
-          `Requested ${requestedPlan} is lower than existing ${candidate.plan}; attaching at current plan.`
-        )
-      );
+    } else if (cmp < 0) {
+      emitReuseNotice({
+        event: "reuse_plan_lower",
+        humanMessage: `Requested ${requestedPlan} is lower than existing ${candidate.plan}; attaching at current plan.`,
+        details: {
+          resourceType: "database",
+          name: candidate.name,
+          currentPlan: candidate.plan,
+          requestedPlan
+        }
+      });
     }
   }
   return {
@@ -6824,16 +8032,10 @@ async function finalizeStorageReuse(client, candidate, requestedPlan, planExplic
   let upgraded = false;
   if (planExplicit && requestedPlan) {
     const cmp = compareResourcePlan(requestedPlan, candidate.plan);
+    const upgradeCommand = `tarout storage upgrade ${candidate.name} --plan ${requestedPlan.toLowerCase()}`;
     if (cmp > 0) {
-      if (candidate.plan !== "FREE") {
-        if (!isJsonMode()) {
-          log(
-            colors.warn(
-              `Storage bucket ${candidate.name} is on ${candidate.plan}. Inline upgrades to ${requestedPlan} are only supported from FREE \u2014 upgrade from the dashboard. Attaching at current plan.`
-            )
-          );
-        }
-      } else if (requestedPlan === "STARTER" || requestedPlan === "STANDARD" || requestedPlan === "PRO") {
+      const isPaidUpgradeable = requestedPlan === "STARTER" || requestedPlan === "STANDARD" || requestedPlan === "PRO";
+      if (candidate.plan === "FREE" && isPaidUpgradeable && !isJsonMode() && !shouldSkipConfirmation()) {
         const ok = await confirmUpgrade(
           `Storage bucket ${candidate.name} is on FREE. Upgrade to ${requestedPlan} before attaching?`,
           true,
@@ -6844,13 +8046,32 @@ async function finalizeStorageReuse(client, candidate, requestedPlan, planExplic
           plan = requestedPlan;
           upgraded = true;
         }
+      } else {
+        emitReuseNotice({
+          event: "reuse_plan_unchanged",
+          humanMessage: `Storage bucket ${candidate.name} stays on ${candidate.plan}; requested ${requestedPlan} was not applied automatically.`,
+          humanHint: `Upgrade explicitly with: ${upgradeCommand}`,
+          details: {
+            resourceType: "storage",
+            name: candidate.name,
+            currentPlan: candidate.plan,
+            requestedPlan,
+            nextCommand: upgradeCommand,
+            hint: "Storage plan upgrades are billing-mutating; run the command above to upgrade."
+          }
+        });
       }
-    } else if (cmp < 0 && !isJsonMode()) {
-      log(
-        colors.warn(
-          `Requested ${requestedPlan} is lower than existing ${candidate.plan}; attaching at current plan.`
-        )
-      );
+    } else if (cmp < 0) {
+      emitReuseNotice({
+        event: "reuse_plan_lower",
+        humanMessage: `Requested ${requestedPlan} is lower than existing ${candidate.plan}; attaching at current plan.`,
+        details: {
+          resourceType: "storage",
+          name: candidate.name,
+          currentPlan: candidate.plan,
+          requestedPlan
+        }
+      });
     }
   }
   return {
@@ -6862,9 +8083,6 @@ async function finalizeStorageReuse(client, candidate, requestedPlan, planExplic
   };
 }
 async function confirmUpgrade(message, defaultValue, field) {
-  if (isJsonMode() || shouldSkipConfirmation()) {
-    return false;
-  }
   return confirm(message, defaultValue, {
     field,
     flag: "--yes (default attaches at current plan; pass --database-plan/--storage-plan with --yes to force an upgrade)"
@@ -7301,11 +8519,12 @@ function registerDeployCommands(program2) {
       if (isEntitlementError(err)) {
         const message = err instanceof Error ? err.message : "Plan upgrade required";
         if (isJsonMode() || shouldSkipConfirmation()) {
-          outputError("NEEDS_UPGRADE", message, {
-            suggestedPlan: inferSuggestedPlan(options.plan),
-            failedEntitlementKey: extractEntitlementKeyFromError(err),
-            hint: "Run `tarout billing upgrade <plan> --wait` to add slots, then retry `tarout deploy`."
-          });
+          await emitNeedsUpgrade(
+            getApiClient(),
+            err,
+            options.plan,
+            "tarout deploy"
+          );
           exit(ExitCode.PERMISSION_DENIED);
         }
         log("");
@@ -7316,11 +8535,12 @@ function registerDeployCommands(program2) {
           options.plan
         );
         if (!upgraded) {
-          outputError("NEEDS_UPGRADE", message, {
-            suggestedPlan: inferSuggestedPlan(options.plan),
-            failedEntitlementKey: extractEntitlementKeyFromError(err),
-            hint: "Run `tarout billing upgrade <plan> --wait`, then retry `tarout deploy`."
-          });
+          await emitNeedsUpgrade(
+            getApiClient(),
+            err,
+            options.plan,
+            "tarout deploy"
+          );
           exit(ExitCode.PERMISSION_DENIED);
         }
         box("Upgrade complete", [
@@ -7451,7 +8671,7 @@ function registerDeployCommands(program2) {
           colors.cyan(d.deploymentId.slice(0, 8)),
           getStatusBadge(d.status),
           d.title || colors.dim("-"),
-          formatDate5(d.createdAt)
+          formatDate6(d.createdAt)
         ])
       );
       log("");
@@ -7643,10 +8863,10 @@ function registerDeployCommands(program2) {
         );
         log("");
         const choices = successfulDeployments.slice(0, 10).map((d, index) => ({
-          name: `${colors.cyan(d.deploymentId.slice(0, 8))} - ${d.title || "Deployment"} (${formatDate5(d.createdAt)})${index === 0 ? colors.dim(" [current]") : ""}`,
+          name: `${colors.cyan(d.deploymentId.slice(0, 8))} - ${d.title || "Deployment"} (${formatDate6(d.createdAt)})${index === 0 ? colors.dim(" [current]") : ""}`,
           value: d.deploymentId
         }));
-        const { select: select2 } = await import("./prompts-QQ2FZKQT.js");
+        const { select: select2 } = await import("./prompts-JH6YBHHV.js");
         targetDeploymentId = await select2(
           "Select deployment:",
           choices,
@@ -7662,10 +8882,10 @@ function registerDeployCommands(program2) {
         log(`  Deployment: ${colors.cyan(targetDeploymentId.slice(0, 8))}`);
         log(`  Title: ${targetDeployment?.title || "Deployment"}`);
         log(
-          `  Created: ${targetDeployment ? formatDate5(targetDeployment.createdAt) : colors.dim("unknown")}`
+          `  Created: ${targetDeployment ? formatDate6(targetDeployment.createdAt) : colors.dim("unknown")}`
         );
         log("");
-        const { confirm: confirm2 } = await import("./prompts-QQ2FZKQT.js");
+        const { confirm: confirm2 } = await import("./prompts-JH6YBHHV.js");
         const confirmed = await confirm2(
           "Are you sure you want to rollback?",
           false,
@@ -7787,7 +9007,7 @@ function findApp3(apps, identifier) {
     (app) => app.applicationId === identifier || app.applicationId.startsWith(identifier) || app.name.toLowerCase() === lowerIdentifier || app.appName?.toLowerCase() === lowerIdentifier
   );
 }
-function formatDate5(date) {
+function formatDate6(date) {
   const d = new Date(date);
   return d.toLocaleString("en-US", {
     month: "short",
@@ -8428,7 +9648,7 @@ function registerDomainsCommands(program2) {
           d.source === "purchased" ? colors.info("purchased") : colors.dim("external"),
           formatStatus(d.status),
           formatCfStatus(d.cloudflareZoneStatus),
-          d.source === "purchased" && d.expiryDate ? formatDate6(d.expiryDate) : colors.dim("-"),
+          d.source === "purchased" && d.expiryDate ? formatDate7(d.expiryDate) : colors.dim("-"),
           d.source === "purchased" ? d.autoRenew ? colors.success("on") : colors.warn("off") : colors.dim("-")
         ])
       );
@@ -10348,7 +11568,7 @@ function formatCfStatus(status) {
       return status;
   }
 }
-function formatDate6(dateValue) {
+function formatDate7(dateValue) {
   try {
     const date = dateValue instanceof Date ? dateValue : new Date(dateValue);
     return date.toISOString().split("T")[0] || "";
@@ -10406,7 +11626,7 @@ function registerEnvCommands(program2) {
           colors.cyan(v.key),
           options.reveal ? v.value || colors.dim("-") : maskValue(v.value),
           v.isSecret ? colors.warn("Yes") : "No",
-          formatDate7(v.updatedAt)
+          formatDate8(v.updatedAt)
         ])
       );
       log("");
@@ -10789,7 +12009,7 @@ ${colors.bold(key)}: ${maskValue(val.value || String(v))}
       } else {
         const _raw = await import("process");
         log('Enter JSON key-value object (e.g. {"KEY":"value"}):');
-        const input2 = await (await import("./prompts-QQ2FZKQT.js")).input(
+        const input2 = await (await import("./prompts-JH6YBHHV.js")).input(
           "JSON:"
         );
         vars = JSON.parse(input2);
@@ -10812,7 +12032,7 @@ ${colors.bold(key)}: ${maskValue(val.value || String(v))}
     try {
       if (!isLoggedIn()) throw new AuthError();
       if (!shouldSkipConfirmation()) {
-        const { confirm: confirmFn } = await import("./prompts-QQ2FZKQT.js");
+        const { confirm: confirmFn } = await import("./prompts-JH6YBHHV.js");
         const ok = await confirmFn(
           `Delete ${keys.length} variable(s)?`,
           false
@@ -10851,7 +12071,7 @@ ${colors.bold(key)}: ${maskValue(val.value || String(v))}
       );
       if (!app) throw new NotFoundError("Application", appIdentifier);
       if (!shouldSkipConfirmation()) {
-        const { confirm: confirmFn } = await import("./prompts-QQ2FZKQT.js");
+        const { confirm: confirmFn } = await import("./prompts-JH6YBHHV.js");
         const ok = await confirmFn(
           `Copy env vars from ${fromEnvId} to ${toEnvId}?`,
           false
@@ -10885,7 +12105,7 @@ function maskValue(value) {
   if (value.length <= 4) return "****";
   return `${value.slice(0, 2)}****${value.slice(-2)}`;
 }
-function formatDate7(date) {
+function formatDate8(date) {
   const d = new Date(date);
   return d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
 }
@@ -11542,7 +12762,7 @@ function registerKeysCommands(program2) {
           k.name,
           colors.dim(`${(k.fingerprint || "").slice(0, 20)}...`),
           k.isDefault ? colors.success("*") : "",
-          formatDate8(k.createdAt)
+          formatDate9(k.createdAt)
         ])
       );
       log("");
@@ -11756,7 +12976,7 @@ function findKey(keys, identifier) {
     (k) => (k.keyId || k.id) === identifier || (k.keyId || k.id || "").startsWith(identifier) || k.name.toLowerCase() === lower
   );
 }
-function formatDate8(date) {
+function formatDate9(date) {
   if (!date) return colors.dim("-");
   return new Date(date).toLocaleDateString("en-US", {
     month: "short",
@@ -12849,7 +14069,7 @@ function registerOrgsCommands(program2) {
           m.user?.name || m.name || colors.dim("-"),
           m.user?.email || m.email || colors.dim("-"),
           formatRole(m.role),
-          formatDate9(m.createdAt)
+          formatDate10(m.createdAt)
         ])
       );
       log("");
@@ -12885,7 +14105,7 @@ function registerOrgsCommands(program2) {
           inv.email,
           formatRole(inv.role),
           inv.status || "pending",
-          formatDate9(inv.createdAt)
+          formatDate10(inv.createdAt)
         ])
       );
       log("");
@@ -13373,7 +14593,7 @@ function formatRole(role) {
   };
   return map[role] || role;
 }
-function formatDate9(date) {
+function formatDate10(date) {
   if (!date) return colors.dim("-");
   return new Date(date).toLocaleDateString("en-US", {
     month: "short",
@@ -13659,7 +14879,7 @@ function registerProjectsCommands(program2) {
 }
 
 // src/commands/providers.ts
-import open4 from "open";
+import open5 from "open";
 function registerProvidersCommands(program2) {
   const providers = program2.command("providers").description("Manage Git providers (GitHub, GitLab, Bitbucket)");
   providers.command("list").alias("ls").description("List all connected Git providers").action(async () => {
@@ -13776,7 +14996,7 @@ function registerProvidersCommands(program2) {
       log(
         "Complete the GitHub browser flow, then connect the repository to your app."
       );
-      await open4(url);
+      await open5(url);
     } catch (err) {
       handleError(err);
     }
@@ -14581,7 +15801,7 @@ function registerServersCommands(program2) {
           s.serverSize || s.size || colors.dim("-"),
           getStatusBadge(s.status || "unknown"),
           s.publicIp || s.ip || colors.dim("-"),
-          formatDate10(s.createdAt)
+          formatDate11(s.createdAt)
         ])
       );
       log("");
@@ -14743,7 +15963,7 @@ function registerServersCommands(program2) {
       log(`  Private IP: ${details.privateIp || colors.dim("-")}`);
       log("");
       if (details.createdAt) {
-        log(`  Created: ${formatDate10(details.createdAt)}`);
+        log(`  Created: ${formatDate11(details.createdAt)}`);
       }
       log("");
     } catch (err) {
@@ -15012,7 +16232,7 @@ function registerServersCommands(program2) {
           s.name || colors.dim("-"),
           s.status || colors.dim("-"),
           formatBytes4(s.diskSizeGb ? s.diskSizeGb * 1024 * 1024 * 1024 : 0),
-          formatDate10(s.createdAt)
+          formatDate11(s.createdAt)
         ])
       );
       log("");
@@ -15536,7 +16756,7 @@ function registerServersCommands(program2) {
           colors.cyan(ip.ip || ip.address || "-"),
           ip.region || "-",
           ip.assignedServerId ? colors.dim(ip.assignedServerId.slice(0, 8)) : colors.dim("unassigned"),
-          formatDate10(ip.createdAt)
+          formatDate11(ip.createdAt)
         ])
       );
       log("");
@@ -16390,7 +17610,7 @@ function findServer(servers, identifier) {
     (s) => (s.id || s.serverId) === identifier || (s.id || s.serverId || "").startsWith(identifier) || (s.name || "").toLowerCase() === lower
   );
 }
-function formatDate10(date) {
+function formatDate11(date) {
   if (!date) return colors.dim("-");
   return new Date(date).toLocaleDateString("en-US", {
     month: "short",
@@ -16576,7 +17796,7 @@ function registerStorageCommands(program2) {
           b.plan || colors.dim("free"),
           b.region || colors.dim("-"),
           b.publicAccess ? colors.success("yes") : colors.dim("no"),
-          formatDate11(b.createdAt)
+          formatDate12(b.createdAt)
         ])
       );
       log("");
@@ -16759,7 +17979,7 @@ function registerStorageCommands(program2) {
         log(`  ${colors.dim("Not available")}`);
       }
       log("");
-      log(`  Created: ${formatDate11(bucket.createdAt)}`);
+      log(`  Created: ${formatDate12(bucket.createdAt)}`);
       log("");
     } catch (err) {
       handleError(err);
@@ -16809,7 +18029,7 @@ function registerStorageCommands(program2) {
           f.name || f.key || "",
           formatBytes5(f.size || f.sizeBytes || 0),
           f.contentType || colors.dim("-"),
-          formatDate11(f.updated || f.updatedAt || f.lastModified)
+          formatDate12(f.updated || f.updatedAt || f.lastModified)
         ])
       );
       log("");
@@ -17250,7 +18470,7 @@ function findBucket(buckets, identifier) {
     (b) => (b.bucketId || b.id) === identifier || (b.bucketId || b.id || "").startsWith(identifier) || b.name.toLowerCase() === lower
   );
 }
-function formatDate11(date) {
+function formatDate12(date) {
   if (!date) return colors.dim("-");
   return new Date(date).toLocaleDateString("en-US", {
     month: "short",
@@ -17312,7 +18532,7 @@ ${colors.warn(`${unread.count} unread ticket${unread.count === 1 ? "" : "s"}`)}`
           formatStatus2(t.status),
           formatPriority(t.priority),
           t.category || colors.dim("-"),
-          formatDate12(t.createdAt)
+          formatDate13(t.createdAt)
         ])
       );
       log("");
@@ -17449,7 +18669,7 @@ ${colors.warn(`${unread.count} unread ticket${unread.count === 1 ? "" : "s"}`)}`
       log(`  Status: ${formatStatus2(ticket.status)}`);
       log(`  Priority: ${formatPriority(ticket.priority)}`);
       log(`  Category: ${ticket.category || colors.dim("-")}`);
-      log(`  Created: ${formatDate12(ticket.createdAt)}`);
+      log(`  Created: ${formatDate13(ticket.createdAt)}`);
       log("");
       if (ticket.description) {
         log(colors.bold("Description"));
@@ -17701,7 +18921,7 @@ function formatPriority(priority) {
   };
   return map[priority] || priority;
 }
-function formatDate12(date) {
+function formatDate13(date) {
   if (!date) return colors.dim("-");
   return new Date(date).toLocaleDateString("en-US", {
     month: "short",
@@ -17921,11 +19141,7 @@ function registerUpCommand(program2) {
           if (isEntitlementError(err)) {
             const message = err instanceof Error ? err.message : "Plan upgrade required";
             if (isJsonMode() || shouldSkipConfirmation()) {
-              outputError("NEEDS_UPGRADE", message, {
-                suggestedPlan: inferSuggestedPlan(options.plan),
-                failedEntitlementKey: extractEntitlementKeyFromError(err),
-                hint: "Run `tarout billing upgrade <plan> --wait` to add slots, then retry `tarout up`."
-              });
+              await emitNeedsUpgrade(client, err, options.plan, "tarout up");
               exit(ExitCode.PERMISSION_DENIED);
             }
             log("");
@@ -17936,11 +19152,7 @@ function registerUpCommand(program2) {
               options.plan
             );
             if (!upgraded) {
-              outputError("NEEDS_UPGRADE", message, {
-                suggestedPlan: inferSuggestedPlan(options.plan),
-                failedEntitlementKey: extractEntitlementKeyFromError(err),
-                hint: "Run `tarout billing upgrade <plan> --wait`, then retry `tarout up`."
-              });
+              await emitNeedsUpgrade(client, err, options.plan, "tarout up");
               exit(ExitCode.PERMISSION_DENIED);
             }
             box("Upgrade complete", [
@@ -18149,7 +19361,7 @@ function registerWalletCommands(program2) {
       table(
         ["DATE", "TYPE", "AMOUNT", "BALANCE", "DESCRIPTION"],
         entries.map((e) => [
-          formatDate13(e.createdAt),
+          formatDate14(e.createdAt),
           formatType(e.type),
           formatAmount(e.amountHalalas),
           formatAmount(e.balanceAfterHalalas),
@@ -18250,7 +19462,7 @@ function formatType(type) {
   };
   return map[type] || type;
 }
-function formatDate13(iso) {
+function formatDate14(iso) {
   return new Date(iso).toLocaleDateString("en-US", {
     month: "short",
     day: "numeric"