@tarout/cli 0.9.0 → 0.10.1

package/dist/index.js

@@ -62,7 +62,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@tarout/cli",
-  version: "0.9.0",
+  version: "0.10.1",
   description: "Tarout CLI \u2014 the Saudi cloud platform for coding agents",
   type: "module",
   bin: {
@@ -787,6 +787,19 @@ function upsertMarkdownBlock(filePath, block) {
 `, "utf-8");
   return "appended";
 }
+function hasTaroutAllowlist(cwd) {
+  const settingsPath = join(cwd, ".claude", "settings.local.json");
+  if (!existsSync(settingsPath)) return false;
+  try {
+    const settings = JSON.parse(
+      readFileSync(settingsPath, "utf-8")
+    );
+    const allow = settings?.permissions?.allow;
+    return Array.isArray(allow) && allow.includes(TAROUT_ALLOW_ENTRY);
+  } catch {
+    return false;
+  }
+}
 function mergeClaudeSettings(claudeDir) {
   const settingsPath = join(claudeDir, "settings.local.json");
   const relPath = join(".claude", "settings.local.json");
@@ -3066,9 +3079,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";
@@ -3227,12 +3237,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."
+          )
+        );
+      }
     }
   };
 }
@@ -3288,12 +3320,9 @@ function registerAuthCommands(program2) {
       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");
-      }
+      await openInBrowser(authUrl, {
+        hint: "If the browser didn't open, visit this URL to authenticate:"
+      });
       const _spinner = startSpinner("Waiting for authentication...");
       try {
         const authData = await authServer.waitForCallback();
@@ -3402,12 +3431,9 @@ function registerAuthCommands(program2) {
       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");
-      }
+      await openInBrowser(authUrl, {
+        hint: "If the browser didn't open, visit this URL to create your account:"
+      });
       const _spinner = startSpinner("Waiting for account creation...");
       try {
         const authData = await authServer.waitForCallback();
@@ -3951,6 +3977,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") {
@@ -3977,8 +4015,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
@@ -4217,6 +4263,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 () => {
@@ -4604,26 +4667,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 {
@@ -4779,20 +4854,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",
@@ -5722,7 +5809,40 @@ 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.";
+function isAgentDriven() {
+  return isJsonMode() || isNonInteractiveMode();
+}
+function ensureAgentSetup(cwd, disabled = false) {
+  if (disabled || !isAgentDriven() || hasTaroutAllowlist(cwd)) return;
+  const result = scaffoldAgentConfig({ cwd, agent: "claude" });
+  if (isJsonMode()) {
+    outputJsonLine({
+      type: "event",
+      event: "agent_setup_done",
+      files: result.files
+    });
+  } else {
+    for (const file of result.files) {
+      log(colors.dim(`  agent setup: ${file.action} ${file.path}`));
+    }
+  }
+}
+function emitAgentSetupHint(cwd) {
+  if (!isAgentDriven() || hasTaroutAllowlist(cwd)) return;
+  if (isJsonMode()) {
+    outputJsonLine({
+      type: "event",
+      event: "agent_setup_required",
+      hint: SETUP_HINT
+    });
+  } else {
+    warn(SETUP_HINT);
+  }
+}
 
 // src/lib/entitlement-remedy.ts
 var planKeyOf = (p) => p.planKey ?? p.key ?? "";
@@ -5736,6 +5856,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 ?? [];
@@ -5755,7 +5890,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",
@@ -5768,7 +5903,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 {
@@ -5796,7 +5931,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",
@@ -5972,7 +6107,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..."
   );
@@ -6659,6 +6796,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;
@@ -6702,13 +6847,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("");
@@ -6718,7 +6879,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 }
     ],
@@ -6729,13 +6890,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);
 }
@@ -6829,9 +6996,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
     );
@@ -6859,9 +7026,20 @@ 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 [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}\`. Then retry: ${retryCommand}.` : `${remedy.hint} Then retry: ${retryCommand}.`;
   outputError("NEEDS_UPGRADE", message, {
     failedEntitlementKey: failedKey,
@@ -6933,7 +7111,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(
@@ -6943,10 +7121,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("");
@@ -7076,7 +7258,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);
@@ -8022,8 +8204,12 @@ function registerDeployCommands(program2) {
   ).option("--install-command <cmd>", "Custom install command").option("--build-command <cmd>", "Custom build command").option(
     "--output-directory <path>",
     "Build output directory (static assets)"
-  ).option("--start-command <cmd>", "Custom start command").option("-w, --wait", "Wait for deployment to complete and stream logs").option("--watch", "Alias for --wait").action(async (appIdentifier, options) => {
+  ).option("--start-command <cmd>", "Custom start command").option("-w, --wait", "Wait for deployment to complete and stream logs").option("--watch", "Alias for --wait").option(
+    "--no-agent-setup",
+    "Don't auto-write the agent permission allowlist (CLAUDE.md / .claude/settings.local.json) on first run"
+  ).action(async (appIdentifier, options) => {
     try {
+      ensureAgentSetup(process.cwd(), options.agentSetup === false);
       const inspection = inspectCurrentProject();
       printProjectInspection(inspection);
       const profile = await ensureAuthenticatedForDeploy(options);
@@ -8983,6 +9169,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);
     }
   });
@@ -13176,10 +13395,14 @@ function registerInitCommand(program2) {
   ).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)"
-  ).option("--database-plan <plan>", "Database plan (e.g. free, starter)").option("--storage", "Provision file storage").option("--storage-plan <plan>", "Storage plan (e.g. free, starter)").option("--scaffold", "Write a minimal starter app if the directory is empty").option("--no-env-write", "Do not write a local .env file with connection strings").action(async (cwdArg, options) => {
+  ).option("--database-plan <plan>", "Database plan (e.g. free, starter)").option("--storage", "Provision file storage").option("--storage-plan <plan>", "Storage plan (e.g. free, starter)").option("--scaffold", "Write a minimal starter app if the directory is empty").option("--no-env-write", "Do not write a local .env file with connection strings").option(
+    "--no-agent-setup",
+    "Don't auto-write the agent permission allowlist (CLAUDE.md / .claude/settings.local.json) on first run"
+  ).action(async (cwdArg, options) => {
     try {
       const cwd = cwdArg ? resolve2(cwdArg) : process.cwd();
       if (cwdArg) process.chdir(cwd);
+      ensureAgentSetup(cwd, options.agentSetup === false);
       if (options.scaffold) {
         const files = scaffoldStarter(cwd);
         emitEvent({ event: "scaffold_done", files });
@@ -13237,13 +13460,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;
@@ -15473,7 +15695,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 () => {
@@ -15590,7 +15812,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);
     }
@@ -19625,10 +19847,14 @@ function registerUpCommand(program2) {
   ).option("--start-command <cmd>", "Custom start command").option(
     "--idempotency-key <key>",
     "Idempotency key for safe retries (Phase 2; logged only in v1)"
+  ).option(
+    "--no-agent-setup",
+    "Don't auto-write the agent permission allowlist (CLAUDE.md / .claude/settings.local.json) on first run"
   ).action(async (cwdArg, options) => {
     try {
       const cwd = cwdArg ? resolve3(cwdArg) : process.cwd();
       if (cwdArg) process.chdir(cwd);
+      ensureAgentSetup(cwd, options.agentSetup === false);
       const source = normalizeSource(options.source);
       const idempotencyKey = options.idempotencyKey?.trim();
       if (idempotencyKey) {
@@ -20054,11 +20280,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>"}`)}`
@@ -20128,7 +20359,7 @@ var program = new Command();
 program.name("tarout").description("Tarout PaaS Command Line Interface").version(package_default.version).option("--json", "Output as JSON (machine-readable)").option("-y, --yes", "Skip all confirmation prompts").option(
   "--non-interactive",
   "Fail fast on missing input (emit needs_input + exit 6 instead of prompting on TTY)"
-).option("-q, --quiet", "Minimal output").option("-v, --verbose", "Extra debug information").option("--no-color", "Disable colored output").hook("preAction", (thisCommand) => {
+).option("-q, --quiet", "Minimal output").option("-v, --verbose", "Extra debug information").option("--no-color", "Disable colored output").hook("preAction", (thisCommand, actionCommand) => {
   const opts = thisCommand.opts();
   const stdinIsTTY = Boolean(process.stdin.isTTY);
   setGlobalOptions({
@@ -20139,6 +20370,12 @@ program.name("tarout").description("Tarout PaaS Command Line Interface").version
     verbose: opts.verbose || false,
     noColor: opts.color === false
   });
+  const sub = actionCommand?.name();
+  const isAgentNamespace = actionCommand?.parent?.name() === "agent";
+  const autoRunsSetup = !!sub && ["up", "deploy", "init"].includes(sub);
+  if (!isAgentNamespace && !autoRunsSetup) {
+    emitAgentSetupHint(process.cwd());
+  }
 });
 registerAuthCommands(program);
 registerAppsCommands(program);

package/package.json

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