@tarout/cli 0.10.0 → 0.11.0

package/dist/index.js

@@ -62,7 +62,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@tarout/cli",
-  version: "0.10.0",
+  version: "0.11.0",
   description: "Tarout CLI \u2014 the Saudi cloud platform for coding agents",
   type: "module",
   bin: {
@@ -753,8 +753,12 @@ don't hand-edit infrastructure.
 - **Run locally** with cloud env vars: \`tarout dev\`.
 - **Full agent guide:** https://tarout.sa/docs/for-ai/onboarding
 
-Run Tarout commands with \`--json\` for machine-readable output. On a \`NEEDS_UPGRADE\`
-error, surface it to the user and follow the upgrade flow instead of auto-retrying.
+Run Tarout commands with \`--json\` for machine-readable output. New apps and
+databases automatically use your org's **subscribed tier** \u2014 don't pass
+\`--plan free\` / \`--database-plan free\`. \`tarout login\` opens the browser for you;
+the user just signs in. A \`NEEDS_UPGRADE\` error means the org is out of slots for
+its tier: surface the two options (buy the add-on vs upgrade the plan) and let the
+user pick \u2014 the chosen command opens the payment page and waits until it's confirmed.
 Ask before destructive actions (delete, rollback, revealing secrets).
 ${BLOCK_END}`;
 function markdownTargetFor(agent) {
@@ -3079,9 +3083,6 @@ function formatTime(ts) {
   });
 }
 
-// src/commands/auth.ts
-import open3 from "open";
-
 // src/lib/auth-server.ts
 import { randomBytes, timingSafeEqual } from "crypto";
 import express from "express";
@@ -3240,12 +3241,34 @@ function canLaunchBrowser() {
   }
   return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
 }
+async function openInBrowser(url, opts) {
+  if (!isJsonMode()) {
+    log(
+      colors.dim(opts?.hint ?? "If the browser didn't open, visit this URL:")
+    );
+    log(`  ${colors.cyan(url)}`);
+  }
+  if (opts?.noOpen || !canLaunchBrowser()) return false;
+  try {
+    await open2(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function paymentBrowserOpener(opts) {
   if (opts?.noOpen || !canLaunchBrowser()) return void 0;
   return async (url) => {
     try {
       await open2(url);
     } catch {
+      if (!isJsonMode()) {
+        log(
+          colors.dim(
+            "Couldn't open the browser automatically \u2014 use the payment link to complete checkout."
+          )
+        );
+      }
     }
   };
 }
@@ -3255,21 +3278,24 @@ function shouldAutoConfirmPaidCheckout(amountDueHalalas) {
 }
 
 // src/commands/auth.ts
-function refuseBrowserAuthForAgent(action) {
-  const message = `tarout ${action} requires a browser. Agents should ask the user to run \`tarout token <api-token>\` or set TAROUT_TOKEN \u2014 generate one at https://tarout.sa/dashboard/settings/profile.`;
+function announceAuthUrl(authUrl, callbackPort, launched) {
   if (isJsonMode()) {
-    outputError("AUTH_BOOTSTRAP_REQUIRED", message, {
-      action,
-      recommendedFlags: [
-        "export TAROUT_TOKEN=<token>",
-        "tarout token <api-token>"
-      ]
+    outputJsonLine({
+      type: "event",
+      event: "auth_url",
+      authUrl,
+      browserLaunched: launched,
+      callbackPort
     });
-  } else {
-    process.stderr.write(`error: ${message}
-`);
+    return;
+  }
+  if (!canLaunchBrowser()) {
+    log(
+      colors.dim(
+        "On a remote/headless host? Run `tarout token <api-token>` instead \u2014 generate one at https://tarout.sa/dashboard/settings/profile."
+      )
+    );
   }
-  exit(ExitCode.AUTH_ERROR);
 }
 function registerAuthCommands(program2) {
   program2.command("login").description("Authenticate with Tarout via browser").option("--api-url <url>", "Custom API URL", "https://tarout.sa").action(async (options) => {
@@ -3292,21 +3318,16 @@ function registerAuthCommands(program2) {
           return;
         }
       }
-      if (isJsonMode() || !canLaunchBrowser()) {
-        refuseBrowserAuthForAgent("login");
-      }
       const apiUrl = options.apiUrl;
       log("");
       log("Opening browser to authenticate...");
       const authServer = await startAuthServer();
       const callbackUrl = `http://localhost:${authServer.port}/callback?state=${encodeURIComponent(authServer.state)}`;
       const authUrl = `${apiUrl}/cli-authorize?callback=${encodeURIComponent(callbackUrl)}`;
-      try {
-        await open3(authUrl);
-      } catch {
-        authServer.close();
-        refuseBrowserAuthForAgent("login");
-      }
+      const launched = await openInBrowser(authUrl, {
+        hint: "If the browser didn't open, visit this URL to authenticate:"
+      });
+      announceAuthUrl(authUrl, authServer.port, launched);
       const _spinner = startSpinner("Waiting for authentication...");
       try {
         const authData = await authServer.waitForCallback();
@@ -3406,21 +3427,16 @@ function registerAuthCommands(program2) {
           return;
         }
       }
-      if (isJsonMode() || !canLaunchBrowser()) {
-        refuseBrowserAuthForAgent("register");
-      }
       const apiUrl = options.apiUrl;
       log("");
       log("Opening browser to create your account...");
       const authServer = await startAuthServer();
       const callbackUrl = `http://localhost:${authServer.port}/callback?state=${encodeURIComponent(authServer.state)}`;
       const authUrl = `${apiUrl}/cli-authorize?action=register&callback=${encodeURIComponent(callbackUrl)}`;
-      try {
-        await open3(authUrl);
-      } catch {
-        authServer.close();
-        refuseBrowserAuthForAgent("register");
-      }
+      const launched = await openInBrowser(authUrl, {
+        hint: "If the browser didn't open, visit this URL to create your account:"
+      });
+      announceAuthUrl(authUrl, authServer.port, launched);
       const _spinner = startSpinner("Waiting for account creation...");
       try {
         const authData = await authServer.waitForCallback();
@@ -3964,6 +3980,18 @@ import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
 
 // src/lib/billing-upgrade.ts
 var AGENT_BILLING_PERMISSION_HINT = `If your agent's permission system blocks this billing command, ask the user to allowlist Tarout billing once so you can run it directly (Claude Code: add "Bash(tarout billing:*)" to .claude/settings.json). Running an upgrade only opens the hosted payment page \u2014 the user still completes payment in the browser.`;
+function storageSlotTierForAddonKey(addonKey) {
+  switch (addonKey) {
+    case "storage.starter":
+      return "STARTER";
+    case "storage.standard":
+      return "STANDARD";
+    case "storage.pro":
+      return "PRO";
+    default:
+      return null;
+  }
+}
 function resolveTarget(input2) {
   if (input2.kind === "plan") return input2.planKey ?? "";
   if (input2.kind === "addon") {
@@ -3990,8 +4018,16 @@ async function performBillingChange(client, input2) {
       addons: input2.addons
     });
   } else if (kind === "addon") {
-    const items = input2.addons ?? (input2.addonKey ? [{ addonKey: input2.addonKey, quantity: input2.quantity ?? 1 }] : []);
-    result = await client.subscription.purchaseAddons.mutate({ items });
+    const storageTier = !input2.addons && input2.addonKey ? storageSlotTierForAddonKey(input2.addonKey) : null;
+    if (storageTier) {
+      result = await client.storage.purchaseStorageSlot.mutate({
+        tier: storageTier,
+        quantity: input2.quantity ?? 1
+      });
+    } else {
+      const items = input2.addons ?? (input2.addonKey ? [{ addonKey: input2.addonKey, quantity: input2.quantity ?? 1 }] : []);
+      result = await client.subscription.purchaseAddons.mutate({ items });
+    }
   } else {
     result = await client.subscription.setPlanQuantity.mutate({
       quantity: input2.quantity
@@ -4111,7 +4147,7 @@ function emitBillingResult(result, opts) {
     case "payment_required":
       outputData({
         ...envelope,
-        hint: `Open paymentUrl to complete checkout, then run \`${nextCommand}\` \u2014 or re-run with --wait.`
+        hint: `Open paymentUrl to complete checkout, then run \`${nextCommand}\` \u2014 or re-run without --no-wait (waiting is the default).`
       });
       box("Payment required", [
         `${label}`,
@@ -4197,6 +4233,16 @@ function isPaidFamily(planKey) {
   const family = planFamily(planKey);
   return family === "SHARED" || family === "DEDICATED";
 }
+function dbAddonKeyForPlanFamily(planKey) {
+  switch (planFamily(planKey)) {
+    case "SHARED":
+      return "db.standard";
+    case "DEDICATED":
+      return "db.pro";
+    default:
+      return null;
+  }
+}
 function resourceAddonKeysForPlan(planKey) {
   switch (planFamily(planKey)) {
     case "SHARED":
@@ -4230,6 +4276,23 @@ function isConflictError(err) {
   const e = err;
   return (e?.code ?? e?.data?.code) === "CONFLICT";
 }
+async function previewAddonAmountDue(client, addonKey, quantity) {
+  try {
+    if (storageSlotTierForAddonKey(addonKey)) {
+      const catalog = await client.subscription.getCatalog.query();
+      const addon = (catalog?.addons ?? []).find(
+        (a) => (a.key ?? a.addonKey) === addonKey
+      );
+      return typeof addon?.priceHalalas === "number" ? addon.priceHalalas * quantity : void 0;
+    }
+    const preview = await client.subscription.previewAddonsPurchase.query({
+      items: [{ addonKey, quantity }]
+    });
+    return typeof preview?.totalProratedHalalas === "number" ? preview.totalProratedHalalas : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function registerBillingCommands(program2) {
   const billing = program2.command("billing").description("Manage subscription and billing");
   billing.command("status").description("Show current subscription and entitlements").action(async () => {
@@ -4328,8 +4391,8 @@ function registerBillingCommands(program2) {
     collectAddon,
     []
   ).option(
-    "-w, --wait",
-    "After hosted-checkout opens, poll status until the payment is confirmed"
+    "--no-wait",
+    "Return as soon as the hosted checkout opens, without polling for confirmation (default: wait until paid)"
   ).option(
     "--timeout <seconds>",
     "Maximum wait time in seconds (default 600)",
@@ -4606,8 +4669,8 @@ function registerBillingCommands(program2) {
     }
   });
   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"
+    "--no-wait",
+    "Return as soon as the hosted checkout opens, without polling for confirmation (default: wait until paid)"
   ).option(
     "--timeout <seconds>",
     "Maximum wait time in seconds (default 600)",
@@ -4617,26 +4680,38 @@ function registerBillingCommands(program2) {
     try {
       if (!isLoggedIn()) throw new AuthError();
       const quantity = options.quantity || 1;
+      const client = getApiClient();
       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 }
-          }
+        const amountDueHalalas = await previewAddonAmountDue(
+          client,
+          addonKey,
+          quantity
         );
-        if (!confirmed) {
-          log("Cancelled.");
-          return;
+        if (shouldAutoConfirmPaidCheckout(amountDueHalalas)) {
+          log(
+            `
+Adding ${colors.cyan(addonKey)} \xD7 ${quantity} \u2014 opening the secure payment page...`
+          );
+        } else {
+          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, amountDueHalalas }
+            }
+          );
+          if (!confirmed) {
+            log("Cancelled.");
+            return;
+          }
         }
       }
-      const client = getApiClient();
       const _spinner = startSpinner("Adding addon...");
       let raw;
       try {
@@ -4707,8 +4782,8 @@ function registerBillingCommands(program2) {
     }
   });
   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"
+    "--no-wait",
+    "Return as soon as the hosted checkout opens, without polling for confirmation (default: wait until paid)"
   ).option(
     "--timeout <seconds>",
     "Maximum wait time in seconds (default 600)",
@@ -4781,8 +4856,8 @@ function registerBillingCommands(program2) {
     }
   });
   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"
+    "--no-wait",
+    "Return as soon as the hosted checkout opens, without polling for confirmation (default: wait until paid)"
   ).option(
     "--timeout <seconds>",
     "Maximum wait time in seconds (default 600)",
@@ -4792,20 +4867,32 @@ function registerBillingCommands(program2) {
     try {
       if (!isLoggedIn()) throw new AuthError();
       const quantity = options.quantity || 1;
+      const client = getApiClient();
       if (!shouldSkipConfirmation()) {
-        log(`
+        const amountDueHalalas = await previewAddonAmountDue(
+          client,
+          addonKey,
+          quantity
+        );
+        if (shouldAutoConfirmPaidCheckout(amountDueHalalas)) {
+          log(
+            `
+Purchasing ${quantity}\xD7 ${colors.cyan(addonKey)} \u2014 opening the secure payment page...`
+          );
+        } else {
+          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 confirmed = await confirm("Proceed?", false, {
+            field: "confirm_addon_buy",
+            flag: "--yes",
+            context: { addonKey, quantity, amountDueHalalas }
+          });
+          if (!confirmed) {
+            log("Cancelled.");
+            return;
+          }
         }
       }
-      const client = getApiClient();
       const _spinner = startSpinner("Purchasing addon...");
       const result = await performBillingChange(client, {
         kind: "addon",
@@ -5735,7 +5822,7 @@ import {
 import { tmpdir } from "os";
 import { basename, dirname, join as join4 } from "path";
 import { promisify } from "util";
-import open4 from "open";
+import open3 from "open";
 
 // src/lib/agent-setup.ts
 var SETUP_HINT = "Run `tarout agent init` to allowlist Bash(tarout:*) so tarout commands run without per-command approval prompts.";
@@ -5782,6 +5869,21 @@ function nextPlanForRequested(requested) {
   if (r === "dedicated_large") return "dedicated_large";
   return r;
 }
+function nextPlanForCurrent(currentPlanKey) {
+  const family = planFamily(currentPlanKey);
+  if (family === "SHARED") return "dedicated_small";
+  if (family === "DEDICATED") {
+    const k = (currentPlanKey ?? "").trim().toLowerCase();
+    if (k === "dedicated_large") return "dedicated_large";
+    if (k === "dedicated_medium") return "dedicated_large";
+    return "dedicated_medium";
+  }
+  return "shared";
+}
+function upgradeTargetPlan(opts) {
+  if (opts?.currentPlanKey) return nextPlanForCurrent(opts.currentPlanKey);
+  return nextPlanForRequested(opts?.requestedPlan);
+}
 function resolveEntitlementRemedy(failedKey, catalog, opts) {
   const plans = catalog?.plans ?? [];
   const addons = catalog?.addons ?? [];
@@ -5801,7 +5903,7 @@ function resolveEntitlementRemedy(failedKey, catalog, opts) {
   }
   if (failedKey?.startsWith("app.dedicated") || failedKey?.startsWith("host.")) {
     const requested = opts?.requestedPlan;
-    const target2 = requested && requested.toLowerCase().startsWith("dedicated") ? nextPlanForRequested(requested) : "dedicated_small";
+    const target2 = planFamily(opts?.currentPlanKey) === "DEDICATED" ? nextPlanForCurrent(opts?.currentPlanKey) : requested && requested.toLowerCase().startsWith("dedicated") ? nextPlanForRequested(requested) : "dedicated_small";
     const plan2 = plans.find((p) => planKeyOf(p) === target2);
     return {
       kind: "plan",
@@ -5814,7 +5916,7 @@ function resolveEntitlementRemedy(failedKey, catalog, opts) {
     };
   }
   if (failedKey === "db.free.slots" || failedKey === "storage.free.slots") {
-    const target2 = nextPlanForRequested(opts?.requestedPlan);
+    const target2 = upgradeTargetPlan(opts);
     const plan2 = plans.find((p) => planKeyOf(p) === target2);
     const resource = failedKey === "db.free.slots" ? "database" : "storage bucket";
     return {
@@ -5842,7 +5944,7 @@ function resolveEntitlementRemedy(failedKey, catalog, opts) {
       hint: `Add a ${matched?.name ?? targetKey} slot with an addon purchase.`
     };
   }
-  const target = nextPlanForRequested(opts?.requestedPlan);
+  const target = upgradeTargetPlan(opts);
   const plan = plans.find((p) => planKeyOf(p) === target);
   return {
     kind: "plan",
@@ -6018,7 +6120,9 @@ async function authenticateViaBrowser(action, apiUrl) {
   log(
     action === "register" ? "Opening browser to create your account..." : "Opening browser to authenticate..."
   );
-  await open4(authUrl);
+  await openInBrowser(authUrl, {
+    hint: action === "register" ? "If the browser didn't open, visit this URL to create your account:" : "If the browser didn't open, visit this URL to authenticate:"
+  });
   const _spinner = startSpinner(
     action === "register" ? "Waiting for account creation..." : "Waiting for authentication..."
   );
@@ -6705,6 +6809,14 @@ async function getCurrentPlanQuantitySafely(client) {
     return 1;
   }
 }
+async function getCurrentPlanKeySafely(client) {
+  try {
+    const sub = await client.subscription.getCurrent.query();
+    return sub?.planKey ?? "free";
+  } catch {
+    return void 0;
+  }
+}
 async function runInlineTargetedRemedy(client, remedy) {
   let input2;
   let label;
@@ -6748,13 +6860,29 @@ async function runInlineTargetedRemedy(client, remedy) {
 }
 async function promptEntitlementRemedy(client, err, requestedPlan) {
   const failedKey = extractEntitlementKeyFromError(err);
-  const catalog = await fetchCatalogSafely(client);
-  const remedy = resolveEntitlementRemedy(failedKey, catalog, { requestedPlan });
+  const [catalog, currentPlanKey] = await Promise.all([
+    fetchCatalogSafely(client),
+    getCurrentPlanKeySafely(client)
+  ]);
+  const remedy = resolveEntitlementRemedy(failedKey, catalog, {
+    requestedPlan,
+    currentPlanKey
+  });
   if (remedy.kind === "plan") {
-    return promptUpgradeFromEntitlementError(client, err, requestedPlan);
+    return promptUpgradeFromEntitlementError(
+      client,
+      err,
+      requestedPlan,
+      currentPlanKey
+    );
   }
   const price = remedy.priceHalalas !== void 0 ? ` (${formatPlanPrice(remedy.priceHalalas)})` : "";
   const targetedLabel = remedy.kind === "plan_quantity" ? `Add one more app slot${price}` : `Add just the ${remedy.targetName ?? remedy.targetKey}${price}`;
+  const upgradePlanKey = upgradeTargetPlan({ currentPlanKey, requestedPlan });
+  const upgradePlanDef = (catalog?.plans ?? []).find(
+    (p) => (p.planKey ?? p.key) === upgradePlanKey
+  );
+  const upgradeLabel = `Upgrade to ${upgradePlanDef?.name ?? upgradePlanKey}`;
   log("");
   log(colors.warn("That resource isn't included in your current plan."));
   log("");
@@ -6764,7 +6892,7 @@ async function promptEntitlementRemedy(client, err, requestedPlan) {
   const choice = await select(
     "How would you like to add it?",
     [
-      { name: "Upgrade the plan", value: UPGRADE },
+      { name: upgradeLabel, value: UPGRADE },
       { name: targetedLabel, value: TARGETED },
       { name: "Cancel", value: CANCEL }
     ],
@@ -6775,13 +6903,19 @@ async function promptEntitlementRemedy(client, err, requestedPlan) {
         failedEntitlementKey: failedKey,
         remedyKind: remedy.kind,
         targetKey: remedy.targetKey,
-        command: remedy.command
+        command: remedy.command,
+        upgradePlanKey
       }
     }
   );
   if (choice === CANCEL) return false;
   if (choice === UPGRADE) {
-    return promptUpgradeFromEntitlementError(client, err, requestedPlan);
+    return promptUpgradeFromEntitlementError(
+      client,
+      err,
+      requestedPlan,
+      currentPlanKey
+    );
   }
   return runInlineTargetedRemedy(client, remedy);
 }
@@ -6875,9 +7009,9 @@ function extractEntitlementKeyFromError(err) {
   const m = msg.match(/Plan limit reached for ([\w.]+)/i);
   return m?.[1];
 }
-function buildRemedyOptions(remedy, requestedPlan, catalog) {
+function buildRemedyOptions(remedy, requestedPlan, catalog, currentPlanKey) {
   if (remedy.kind === "addon" || remedy.kind === "plan_quantity") {
-    const upgradePlan = nextPlanForRequested(requestedPlan);
+    const upgradePlan = upgradeTargetPlan({ currentPlanKey, requestedPlan });
     const planDef = (catalog?.plans ?? []).find(
       (p) => (p.planKey ?? p.key) === upgradePlan
     );
@@ -6905,10 +7039,21 @@ function buildRemedyOptions(remedy, requestedPlan, catalog) {
 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 });
-  const options = buildRemedyOptions(remedy, requestedPlan, catalog);
-  const hint = options.length > 1 ? `Two ways to resolve this \u2014 ask the user which they prefer, do not choose for them: (1) ${options[0]?.label}: \`${options[0]?.command}\`; (2) ${options[1]?.label}: \`${options[1]?.command}\`. Then retry: ${retryCommand}.` : `${remedy.hint} Then retry: ${retryCommand}.`;
+  const [catalog, currentPlanKey] = await Promise.all([
+    fetchCatalogSafely(client),
+    getCurrentPlanKeySafely(client)
+  ]);
+  const remedy = resolveEntitlementRemedy(failedKey, catalog, {
+    requestedPlan,
+    currentPlanKey
+  });
+  const options = buildRemedyOptions(
+    remedy,
+    requestedPlan,
+    catalog,
+    currentPlanKey
+  );
+  const hint = options.length > 1 ? `Two ways to resolve this \u2014 ask the user which they prefer, do not choose for them: (1) ${options[0]?.label}: \`${options[0]?.command}\`; (2) ${options[1]?.label}: \`${options[1]?.command}\`. The chosen command opens the payment page and waits until it's confirmed, then retry: ${retryCommand}.` : `${remedy.hint} That command opens the payment page and waits until it's confirmed, then retry: ${retryCommand}.`;
   outputError("NEEDS_UPGRADE", message, {
     failedEntitlementKey: failedKey,
     remedyKind: remedy.kind,
@@ -6979,7 +7124,7 @@ async function explainFreeResourceSlotExhaustion(client, failedKey) {
   log(`  \u2022 Upgrade:   ${colors.cyan("tarout billing upgrade shared --wait")}`);
   log("");
 }
-async function promptUpgradeFromEntitlementError(client, err, requestedPlan) {
+async function promptUpgradeFromEntitlementError(client, err, requestedPlan, currentPlanKey) {
   const catalog = await fetchCatalogSafely(client);
   const allPlans = catalog?.plans ?? [];
   const upgradeable = allPlans.filter(
@@ -6989,10 +7134,14 @@ async function promptUpgradeFromEntitlementError(client, err, requestedPlan) {
     return false;
   }
   const failedKey = extractEntitlementKeyFromError(err);
+  const ladderKey = upgradeTargetPlan({ currentPlanKey, requestedPlan });
+  const ladderPlan = upgradeable.find(
+    (p) => (p.planKey || p.key) === ladderKey
+  );
   const matchingPlan = failedKey ? upgradeable.find(
     (p) => p.grants?.some((g) => g.entitlementKey === failedKey)
   ) : void 0;
-  const recommendedKey = matchingPlan ? matchingPlan.planKey || matchingPlan.key : inferSuggestedPlan(requestedPlan);
+  const recommendedKey = ladderPlan ? ladderKey : matchingPlan ? matchingPlan.planKey || matchingPlan.key : inferSuggestedPlan(requestedPlan);
   log("");
   log(colors.bold("Available upgrade plans:"));
   log("");
@@ -7122,7 +7271,7 @@ async function openGitProviderSetup() {
   log(
     `No GitHub account is required if you keep using ${colors.dim("--source upload")}.`
   );
-  await open4(url);
+  await open3(url);
 }
 async function configureOptionalResources(client, profile, app, options, inspection) {
   const database = await resolveDatabaseChoice(options, inspection);
@@ -7275,6 +7424,57 @@ async function resolveResourcePlan(client, kind, value, message) {
     }
   });
 }
+function dbTierForAddonKey(addonKey) {
+  if (addonKey === "db.pro") return "PRO";
+  if (addonKey === "db.standard") return "STANDARD";
+  return "STARTER";
+}
+async function ensureDatabasePlan(client, requested) {
+  const currentPlanKey = await getCurrentPlanKeySafely(client);
+  const addonKey = dbAddonKeyForPlanFamily(currentPlanKey);
+  const orgIsPaid = addonKey !== null;
+  if (requested && !(requested === "FREE" && orgIsPaid)) {
+    return { ok: true, plan: requested };
+  }
+  const tiers = await loadResourceTiers(client, "database");
+  const hasCreatable = tiers.some((t) => t.canCreate);
+  if (hasCreatable || !orgIsPaid) {
+    return { ok: true, plan: pickDefaultResourceTier(tiers) };
+  }
+  if (!isJsonMode()) {
+    log("");
+    log(
+      colors.dim(
+        `Your plan has no open database slot \u2014 adding the ${addonKey} add-on. Complete payment in the browser to continue.`
+      )
+    );
+  }
+  const result = await performBillingChange(client, {
+    kind: "addon",
+    addonKey,
+    quantity: 1,
+    wait: true,
+    timeoutMs: 6e5,
+    openBrowser: paymentBrowserOpener(),
+    onCheckoutOpened: ({ orderId, paymentUrl }) => {
+      if (!isJsonMode()) {
+        log("");
+        log("Open this URL to complete payment:");
+        log(`  ${colors.cyan(paymentUrl)}`);
+        log(`Order ID: ${colors.dim(orderId)}`);
+      }
+    }
+  });
+  if (result.status === "applied" || result.status === "paid") {
+    return { ok: true, plan: dbTierForAddonKey(addonKey) };
+  }
+  return { ok: false, result };
+}
+async function resolveDatabasePlanOrExit(client, requested) {
+  const resolution = await ensureDatabasePlan(client, requested);
+  if (resolution.ok) return resolution.plan;
+  exit(emitBillingResult(resolution.result, { label: "Database add-on" }));
+}
 async function createAndAttachDatabase(client, profile, app, input2) {
   const appName = generateResourceSlug(app.name, input2.kind);
   const label = input2.kind === "postgres" ? "Postgres" : "MySQL";
@@ -7412,12 +7612,7 @@ async function resolveDatabaseProvisioning(client, profile, app, kind, options)
     }
   );
   if (picked === "__create__") {
-    const plan = requestedPlan ?? await resolveResourcePlan(
-      client,
-      "database",
-      void 0,
-      "Database plan:"
-    );
+    const plan = await resolveDatabasePlanOrExit(client, requestedPlan);
     return {
       action: "create",
       plan,
@@ -7782,7 +7977,7 @@ async function attachExistingStorage(client, app, decision) {
   }
 }
 async function buildDatabaseCreateDecision(client, app, kind, requestedPlan) {
-  const plan = requestedPlan ?? await resolveResourcePlan(client, "database", void 0, "Database plan:");
+  const plan = await resolveDatabasePlanOrExit(client, requestedPlan);
   return {
     action: "create",
     plan,
@@ -8879,10 +9074,7 @@ function normalizeDbPlan(value) {
   );
 }
 async function resolveDbPlan(client, explicit) {
-  const normalized = normalizeDbPlan(explicit);
-  if (normalized) return normalized;
-  const tiers = await loadResourceTiers(client, "database");
-  return pickDefaultResourceTier(tiers);
+  return resolveDatabasePlanOrExit(client, normalizeDbPlan(explicit));
 }
 function registerDbCommands(program2) {
   const db = program2.command("db").description("Manage databases");
@@ -9033,6 +9225,39 @@ function registerDbCommands(program2) {
       }
       log("");
     } catch (err) {
+      if (isEntitlementError(err)) {
+        if (isJsonMode() || isNonInteractiveMode() || shouldSkipConfirmation()) {
+          await emitNeedsUpgrade(
+            getApiClient(),
+            err,
+            void 0,
+            "tarout db create"
+          );
+          exit(ExitCode.PERMISSION_DENIED);
+        }
+        const message = err instanceof Error ? err.message : "Plan upgrade required";
+        log("");
+        log(colors.warn(message));
+        const upgraded = await promptEntitlementRemedy(
+          getApiClient(),
+          err,
+          void 0
+        );
+        if (!upgraded) {
+          await emitNeedsUpgrade(
+            getApiClient(),
+            err,
+            void 0,
+            "tarout db create"
+          );
+          exit(ExitCode.PERMISSION_DENIED);
+        }
+        box("Billing updated", [
+          colors.success("Subscription updated."),
+          `Run ${colors.cyan("tarout db create")} again to create the database.`
+        ]);
+        return;
+      }
       handleError(err);
     }
   });
@@ -13221,8 +13446,7 @@ function registerInitCommand(program2) {
     "Custom API URL (defaults to saved profile or https://tarout.sa)"
   ).option("--token <token>", "API token for this run").option("--name <name>", "Application name (defaults to directory name)").option(
     "--plan <plan>",
-    "App hosting plan: free, shared, or dedicated",
-    "free"
+    "App hosting plan: free, shared, or dedicated (defaults to your org's subscribed tier)"
   ).option("-r, --region <region>", "Deployment region", DEFAULT_REGION2).option("--description <text>", "Description for the newly created app").option(
     "--database <type>",
     "Provision a database: none, postgres, or mysql (defaults to auto-detected)"
@@ -13291,13 +13515,12 @@ function registerInitCommand(program2) {
           });
         } catch (err) {
           if (isEntitlementError(err)) {
-            const message = err instanceof Error ? err.message : "Plan upgrade required";
-            outputError("NEEDS_UPGRADE", message, {
-              suggestedPlan: inferSuggestedPlan(options.plan),
-              failedEntitlementKey: extractEntitlementKeyFromError(err),
-              hint: "Run `tarout billing upgrade <plan> --wait` to add slots, then retry `tarout init`.",
-              permissionHint: AGENT_BILLING_PERMISSION_HINT
-            });
+            await emitNeedsUpgrade(
+              getApiClient(),
+              err,
+              options.plan,
+              "tarout init"
+            );
             exit(ExitCode.PERMISSION_DENIED);
           }
           throw err;
@@ -15527,7 +15750,7 @@ function registerProjectsCommands(program2) {
 }
 
 // src/commands/providers.ts
-import open5 from "open";
+import open4 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 () => {
@@ -15644,7 +15867,7 @@ function registerProvidersCommands(program2) {
       log(
         "Complete the GitHub browser flow, then connect the repository to your app."
       );
-      await open5(url);
+      await open4(url);
     } catch (err) {
       handleError(err);
     }
@@ -20112,11 +20335,16 @@ function registerWalletCommands(program2) {
         outputData(result);
         return;
       }
+      const paymentUrl = result.paymentUrl || result.url || "";
       box("Wallet Top-Up", [
         `Order ID: ${colors.cyan(result.orderId || "")}`,
         `Amount: ${result.amount ? `${(result.amount / 100).toFixed(2)} SAR` : "Default"}`,
-        `Payment URL: ${colors.cyan(result.paymentUrl || result.url || "")}`
+        `Payment URL: ${colors.cyan(paymentUrl)}`
       ]);
+      if (paymentUrl) {
+        const openPayment = paymentBrowserOpener();
+        if (openPayment) await openPayment(paymentUrl);
+      }
       log("Complete payment in your browser to credit the wallet.");
       log(
         `Confirm after payment: ${colors.dim(`tarout wallet confirm ${result.orderId || "<orderId>"}`)}`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tarout/cli",
-	"version": "0.10.0",
+	"version": "0.11.0",
 	"description": "Tarout CLI — the Saudi cloud platform for coding agents",
 	"type": "module",
 	"bin": {