apiblaze 0.21.18 → 0.21.19

package/dist/index.js

@@ -53,6 +53,7 @@ var init_types = __esm({
 // src/lib/auth.ts
 var auth_exports = {};
 __export(auth_exports, {
+  LocalAuthError: () => LocalAuthError,
   clearCredentials: () => clearCredentials,
   getAccessToken: () => getAccessToken,
   getApiblazeDir: () => getApiblazeDir,
@@ -85,17 +86,17 @@ function getAccessToken() {
   if (fromEnv && fromEnv.trim()) return fromEnv.trim();
   const creds = loadCredentials();
   if (!creds) {
-    throw new Error("Not authenticated. Run `apiblaze login` first.");
+    throw new LocalAuthError("not_authenticated", "Not authenticated. Run `apiblaze login` first.");
   }
   if (Date.now() >= creds.expiresAt) {
-    throw new Error("Session expired. Run `apiblaze login` to re-authenticate.");
+    throw new LocalAuthError("session_expired", "Session expired. Run `apiblaze login` to re-authenticate.");
   }
   return creds.accessToken;
 }
 function getApiblazeDir() {
   return APIBLAZE_DIR;
 }
-var fs2, os2, path2, APIBLAZE_DIR, CREDENTIALS_PATH;
+var fs2, os2, path2, APIBLAZE_DIR, CREDENTIALS_PATH, LocalAuthError;
 var init_auth = __esm({
   "src/lib/auth.ts"() {
     "use strict";
@@ -104,6 +105,13 @@ var init_auth = __esm({
     path2 = __toESM(require("path"));
     APIBLAZE_DIR = path2.join(os2.homedir(), ".apiblaze");
     CREDENTIALS_PATH = path2.join(APIBLAZE_DIR, "credentials.json");
+    LocalAuthError = class extends Error {
+      constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "LocalAuthError";
+      }
+    };
   }
 });
 
@@ -1352,7 +1360,7 @@ var import_commander = require("commander");
 var import_chalk68 = __toESM(require("chalk"));
 
 // package.json
-var version = "0.21.18";
+var version = "0.21.19";
 
 // src/lib/version-guard.ts
 var import_fs = __toESM(require("fs"));
@@ -1384,33 +1392,77 @@ function cliRefusal(policy, headerVersion) {
 
 // src/lib/version-guard.ts
 var DASHBOARD_BASE = process.env.APIBLAZE_DASHBOARD_BASE || "https://dashboard.apiblaze.com";
-var CACHE_FILE = import_path.default.join(import_os.default.homedir(), ".apiblaze", "cli-policy.json");
+function cacheFile() {
+  return import_path.default.join(import_os.default.homedir(), ".apiblaze", "cli-policy.json");
+}
 var CACHE_MS = 10 * 6e4;
 var UPGRADE_EXIT_CODE = 3;
-var OWN_SUFFIXES = ["apiblaze.com", "abz.run", "tryabz.run", "mcpblaze.com"];
-function isApiblazeHost(url) {
-  let host;
+var CONTROL_PLANE_HOSTS = /* @__PURE__ */ new Set([
+  "dashboard.apiblaze.com",
+  "auth.apiblaze.com",
+  "apikeys.apiblaze.com",
+  "api.apiblaze.com",
+  "mcp.apiblaze.com",
+  "mcp.mcpblaze.com",
+  "tunnel.apiblaze.com"
+  // the tunnel worker (dashboard TUNNEL_CONNECT_URL → lib/tunnel-client.ts)
+]);
+var CONTROL_PLANE_ENV = ["APIBLAZE_DASHBOARD_BASE", "APIBLAZE_AUTH_BASE", "APIBLAZE_APIKEYS_BASE", "APIBLAZE_API_BASE"];
+function isControlPlaneHost(url) {
+  let parsed;
   try {
-    host = new URL(url).hostname.toLowerCase();
+    parsed = new URL(url);
   } catch {
     return false;
   }
-  if (OWN_SUFFIXES.some((s) => host === s || host.endsWith(`.${s}`))) return true;
-  for (const v of [process.env.APIBLAZE_DASHBOARD_BASE, process.env.APIBLAZE_AUTH_BASE, process.env.APIBLAZE_APIKEYS_BASE]) {
+  if (CONTROL_PLANE_HOSTS.has(parsed.hostname.toLowerCase())) return true;
+  for (const name of CONTROL_PLANE_ENV) {
+    const v = process.env[name];
     try {
-      if (v && new URL(v).hostname.toLowerCase() === host) return true;
+      if (v && new URL(v).host.toLowerCase() === parsed.host.toLowerCase()) return true;
     } catch {
     }
   }
   return false;
 }
-function exitForUpgrade(version2, min, message) {
+var CliUpgradeRequired = class extends Error {
+  constructor(version2, minVersion, serverMessage) {
+    super(`This APIblaze CLI (v${version2}) is no longer supported \u2014 the minimum is v${minVersion}.`);
+    this.version = version2;
+    this.minVersion = minVersion;
+    this.serverMessage = serverMessage;
+    this.code = "cli_upgrade_required";
+    this.name = "CliUpgradeRequired";
+  }
+};
+function printUpgradeMessage(err) {
   console.error("");
-  console.error(import_chalk.default.red(`  This APIblaze CLI (v${version2}) is no longer supported \u2014 the minimum is v${min}.`));
-  if (message) console.error(import_chalk.default.yellow(`  ${message}`));
+  console.error(import_chalk.default.red(`  ${err.message}`));
+  if (err.serverMessage) console.error(import_chalk.default.yellow(`  ${err.serverMessage}`));
   console.error(import_chalk.default.cyan("  Upgrade:  npm i -g apiblaze@latest    (or run: npx apiblaze@latest \u2026)"));
+  console.error(import_chalk.default.dim("  Operators: `apiblaze op \u2026` is never blocked; APIBLAZE_SKIP_VERSION_CHECK=1 skips this local check."));
   console.error("");
-  process.exit(UPGRADE_EXIT_CODE);
+}
+var shutdownHook = null;
+var handling = null;
+function setUpgradeShutdown(hook) {
+  shutdownHook = hook;
+}
+function handleUpgradeRequired(err) {
+  if (handling) return handling;
+  handling = (async () => {
+    printUpgradeMessage(err);
+    const hook = shutdownHook;
+    shutdownHook = null;
+    if (hook) {
+      try {
+        await hook(UPGRADE_EXIT_CODE);
+      } catch {
+      }
+    }
+    process.exit(UPGRADE_EXIT_CODE);
+  })();
+  return handling;
 }
 var installed = false;
 function installFetchGuard(version2) {
@@ -1419,7 +1471,7 @@ function installFetchGuard(version2) {
   const base2 = globalThis.fetch.bind(globalThis);
   globalThis.fetch = (async (input, init) => {
     const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-    if (!isApiblazeHost(url)) return base2(input, init);
+    if (!isControlPlaneHost(url)) return base2(input, init);
     const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
     headers.set(CLI_VERSION_HEADER, version2);
     if (!headers.has("user-agent")) headers.set("user-agent", `apiblaze-cli/${version2}`);
@@ -1430,49 +1482,75 @@ function installFetchGuard(version2) {
         body = await res.clone().json();
       } catch {
       }
-      if (body?.error === "cli_upgrade_required") exitForUpgrade(version2, body.min_version ?? "?", body.message ?? null);
+      if (body?.error === "cli_upgrade_required") {
+        const err = new CliUpgradeRequired(
+          version2,
+          typeof body.min_version === "string" ? body.min_version : "?",
+          typeof body.message === "string" ? body.message : null
+        );
+        if (shutdownHook) void handleUpgradeRequired(err);
+        throw err;
+      }
     }
     return res;
   });
 }
+function normalizePolicy(raw) {
+  const r = raw && typeof raw === "object" ? raw : {};
+  return {
+    ...DEFAULT_CLI_POLICY,
+    min_version: isVersion(r.min_version) ? r.min_version : DEFAULT_CLI_POLICY.min_version,
+    reject_unversioned: r.reject_unversioned === true,
+    message: typeof r.message === "string" && r.message.trim() ? r.message : null,
+    ...typeof r.updated_at === "string" ? { updated_at: r.updated_at } : {},
+    ...typeof r.updated_by === "string" ? { updated_by: r.updated_by } : {}
+  };
+}
 async function fetchPolicy() {
   try {
     const res = await fetch(`${DASHBOARD_BASE}/api/cli/policy`, { signal: AbortSignal.timeout(1500) });
     if (!res.ok) return null;
-    return { ...DEFAULT_CLI_POLICY, ...await res.json() };
+    return normalizePolicy(await res.json());
   } catch {
     return null;
   }
 }
 function readCache() {
   try {
-    return JSON.parse(import_fs.default.readFileSync(CACHE_FILE, "utf8"));
+    const raw = JSON.parse(import_fs.default.readFileSync(cacheFile(), "utf8"));
+    if (!raw || typeof raw !== "object" || typeof raw.at !== "number" || !Number.isFinite(raw.at)) return null;
+    return { at: raw.at, policy: raw.policy === null ? null : normalizePolicy(raw.policy) };
   } catch {
     return null;
   }
 }
 function writeCache(policy) {
   try {
-    import_fs.default.mkdirSync(import_path.default.dirname(CACHE_FILE), { recursive: true });
-    import_fs.default.writeFileSync(CACHE_FILE, JSON.stringify({ at: Date.now(), policy }));
+    import_fs.default.mkdirSync(import_path.default.dirname(cacheFile()), { recursive: true });
+    import_fs.default.writeFileSync(cacheFile(), JSON.stringify({ at: Date.now(), policy }));
   } catch {
   }
 }
 async function checkCliPolicy(version2, opts = {}) {
   if (process.env.APIBLAZE_SKIP_VERSION_CHECK === "1") return;
   const cached = opts.fresh ? null : readCache();
-  let policy = cached && Date.now() - cached.at < CACHE_MS ? cached.policy : null;
-  if (!policy) {
+  let policy;
+  if (cached && Date.now() - cached.at >= 0 && Date.now() - cached.at < CACHE_MS) {
+    policy = cached.policy;
+  } else {
     policy = await fetchPolicy();
-    if (policy) writeCache(policy);
+    writeCache(policy);
   }
-  if (policy && cliRefusal(policy, version2)) exitForUpgrade(version2, policy.min_version, policy.message);
+  if (policy && cliRefusal(policy, version2)) throw new CliUpgradeRequired(version2, policy.min_version, policy.message);
 }
 function watchCliPolicy(version2) {
   const t = setInterval(() => {
-    void checkCliPolicy(version2, { fresh: true });
+    checkCliPolicy(version2, { fresh: true }).catch((err) => {
+      if (err instanceof CliUpgradeRequired) void handleUpgradeRequired(err);
+    });
   }, 10 * 6e4);
   t.unref?.();
+  return () => clearInterval(t);
 }
 
 // src/index.ts
@@ -2109,6 +2187,20 @@ var PING_INTERVAL_MS = 3e4;
 var SILENCE_LIMIT_MS = 75e3;
 var MAX_RECONNECT_DELAY_MS = 15e3;
 var TOKEN_REFRESH_AFTER_MS = 24e4;
+var MAX_REFRESH_RETRY_DELAY_MS = 6e4;
+var DEFINITIVE_CODES = /* @__PURE__ */ new Set(["key_rejected", "team_not_covered", "token_expired", "invalid_token", "project_not_found"]);
+var REFUSAL_MIN_REPEATS = 2;
+var REFUSAL_MIN_SPAN_MS = 6e4;
+function definitiveRefusal(err, projectId) {
+  const body = err?.body;
+  const code = typeof body?.error === "string" ? body.error : null;
+  if (!code || !DEFINITIVE_CODES.has(code)) return null;
+  if (code === "project_not_found") {
+    const named = body?.project === projectId || Array.isArray(body?.projects) && body.projects.includes(projectId);
+    return named ? code : null;
+  }
+  return code;
+}
 var OFFLINE_CODES = /* @__PURE__ */ new Set(["ECONNREFUSED", "ECONNRESET", "ENOTFOUND", "EHOSTUNREACH"]);
 var STRIP_HEADERS = /* @__PURE__ */ new Set([
   "host",
@@ -2142,11 +2234,14 @@ function startTunnelClient(opts) {
   let token = opts.token;
   let tokenAt = Date.now();
   let tokenRefused = false;
+  let refreshFailures = 0;
+  let refusal = null;
   let lastFrameAt = Date.now();
   let capturing = false;
   function connect() {
     const url = `${connectUrl}?project=${encodeURIComponent(opts.projectId)}&token=${encodeURIComponent(token)}`;
-    const socket = new import_ws.default(url, { headers: { [CLI_VERSION_HEADER]: version, "user-agent": `apiblaze-cli/${version}` } });
+    const headers = isControlPlaneHost(connectUrl) ? { [CLI_VERSION_HEADER]: version, "user-agent": `apiblaze-cli/${version}` } : {};
+    const socket = new import_ws.default(url, { headers });
     ws = socket;
     socket.on("open", () => {
       reconnects = 0;
@@ -2185,14 +2280,18 @@ function startTunnelClient(opts) {
     socket.on("error", () => {
     });
   }
-  function scheduleReconnect() {
-    const delay = Math.min(1e3 * 2 ** reconnects, MAX_RECONNECT_DELAY_MS);
+  function scheduleReconnect(delayMs) {
+    const delay = delayMs ?? Math.min(1e3 * 2 ** reconnects, MAX_RECONNECT_DELAY_MS);
     reconnects++;
-    opts.onStatus?.(`disconnected \u2014 reconnecting in ${Math.round(delay / 1e3)}s`);
+    if (delayMs === void 0) opts.onStatus?.(`disconnected \u2014 reconnecting in ${Math.round(delay / 1e3)}s`);
     setTimeout(() => {
       void reconnect();
     }, delay);
   }
+  function stop(reason, code) {
+    closed = true;
+    opts.onFatal?.(reason, code);
+  }
   async function reconnect() {
     if (closed) return;
     if (opts.refresh && (tokenRefused || Date.now() - tokenAt > TOKEN_REFRESH_AFTER_MS)) {
@@ -2202,15 +2301,30 @@ function startTunnelClient(opts) {
         token = fresh.token;
         tokenAt = Date.now();
         tokenRefused = false;
+        refreshFailures = 0;
+        refusal = null;
       } catch (err) {
-        const status2 = typeof err?.status === "number" ? err.status : 0;
-        if (status2 === 401 || status2 === 403) {
-          closed = true;
-          opts.onFatal?.(err?.message ?? `HTTP ${status2}`);
+        if (closed) return;
+        if (err?.name === "LocalAuthError") {
+          stop(err.message, typeof err.code === "string" ? err.code : "session_expired");
           return;
         }
-        opts.onStatus?.(`could not refresh the tunnel token (${err?.message ?? err}) \u2014 retrying`);
-        scheduleReconnect();
+        const code = definitiveRefusal(err, opts.projectId);
+        if (code) {
+          const now = Date.now();
+          refusal = refusal && refusal.code === code ? { ...refusal, count: refusal.count + 1 } : { code, firstAt: now, count: 1 };
+          if (refusal.count >= REFUSAL_MIN_REPEATS && now - refusal.firstAt >= REFUSAL_MIN_SPAN_MS) {
+            stop(err?.message ?? code, code);
+            return;
+          }
+        } else {
+          refusal = null;
+        }
+        const delay = Math.min(2e3 * 2 ** refreshFailures, MAX_REFRESH_RETRY_DELAY_MS);
+        refreshFailures++;
+        tokenRefused = true;
+        opts.onStatus?.(`could not refresh the tunnel token (${err?.message ?? err}) \u2014 retrying in ${Math.round(delay / 1e3)}s`);
+        scheduleReconnect(delay);
         return;
       }
     }
@@ -2340,6 +2454,7 @@ function startTunnelClient(opts) {
 }
 
 // src/commands/dev.ts
+init_types();
 init_anon_cred();
 
 // src/commands/create.ts
@@ -6690,6 +6805,20 @@ async function runDev(options) {
   }
   let restore = [];
   let connect;
+  let clients = [];
+  let isCleaningUp = false;
+  async function cleanup(exitCode = 0) {
+    if (isCleaningUp) return;
+    isCleaningUp = true;
+    setUpgradeShutdown(null);
+    console.log(import_chalk20.default.gray("\n\nShutting down..."));
+    for (const client of clients) client.close();
+    if (captureStream) await new Promise((resolve4) => captureStream.end(() => resolve4()));
+    await deleteDevTunnel(restore, keyAuth).catch(() => {
+    });
+    console.log(exitCode === 0 ? import_chalk20.default.green("Tunnel stopped.") : import_chalk20.default.yellow("Tunnel stopped."));
+    process.exit(exitCode);
+  }
   const registerTargets = { targets: selected.map((t) => ({ projectId: t.projectId, tenantId: t.tenantId })) };
   {
     const spinner = (0, import_ora7.default)("Registering the tunnel...").start();
@@ -6697,6 +6826,7 @@ async function runDev(options) {
       const result = await putDevTunnel(registerTargets, keyAuth);
       restore = (result.restore ?? []).map((r) => unmarkRestore(r, options.port));
       connect = result.connect;
+      setUpgradeShutdown((code) => cleanup(code));
       spinner.stop();
     } catch (err) {
       spinner.fail("Failed to register the tunnel.");
@@ -6710,15 +6840,22 @@ async function runDev(options) {
     else held.push(line);
   };
   const fatal = /* @__PURE__ */ new Set();
-  const clients = connect.projects.map(
+  let lastFatalCode;
+  clients = connect.projects.map(
     (projectId) => startTunnelClient({
       connectUrl: connect.url,
       token: connect.token,
       // Re-register for a fresh token. PUT is idempotent on an already-tunnelled
       // project; its restore snapshot would be the marker, so it is IGNORED —
-      // teardown keeps replaying the one taken at start.
+      // teardown keeps replaying the one taken at start. Projects whose client
+      // already stopped are left out; a project the dashboard reports missing
+      // is a per-project refusal (stops that client only, once it repeats).
       refresh: async () => {
-        const again = await putDevTunnel(registerTargets, keyAuth);
+        const still = { targets: registerTargets.targets.filter((t) => !fatal.has(t.projectId)) };
+        const again = await putDevTunnel(still.targets.length ? still : registerTargets, keyAuth);
+        if (again.not_found?.includes(projectId) || !again.connect.projects.includes(projectId)) {
+          throw new ApiError(404, `project ${projectId} not found`, { error: "project_not_found", project: projectId });
+        }
         return { url: again.connect.url, token: again.connect.token };
       },
       projectId,
@@ -6733,12 +6870,16 @@ async function runDev(options) {
 \u2713 Local server detected on port ${options.port} \u2014 forwarding resumed.
 `)),
       onRecord: recordSink,
-      onFatal: (reason) => {
-        say(import_chalk20.default.red(`[${projectId}] tunnel stopped: the dashboard refused to renew it (${reason}).`));
+      onFatal: (reason, code) => {
+        const local = code === "session_expired" || code === "not_authenticated";
+        say(import_chalk20.default.red(local ? `[${projectId}] tunnel stopped: ${reason}` : code === "project_not_found" ? `[${projectId}] tunnel stopped: the project no longer exists (or is no longer visible to this credential).` : `[${projectId}] tunnel stopped: the dashboard refused to renew it (${reason}).`));
         fatal.add(projectId);
+        if (code !== "project_not_found") lastFatalCode = code;
         if (fatal.size === connect.projects.length) {
-          say(import_chalk20.default.yellow(auth.mode === "key" ? `  This anonymous workspace's key no longer covers these projects \u2014 most likely the workspace was claimed into an account.
-  Run \`npx ${B.cli} login\`, then \`npx ${B.cli} dev --port ${options.port} --auto\` to reattach.` : `  Your login no longer covers these projects. Run \`npx ${B.cli} login\`, then \`npx ${B.cli} dev --port ${options.port} --auto\` to reattach.`));
+          if (lastFatalCode) {
+            say(import_chalk20.default.yellow(auth.mode === "key" ? `  This anonymous workspace's key no longer covers these projects \u2014 most likely the workspace was claimed into an account.
+  Run \`npx ${B.cli} login\`, then \`npx ${B.cli} dev --port ${options.port} --auto\` to reattach.` : `  Your login no longer covers these projects (or it expired). Run \`npx ${B.cli} login\`, then \`npx ${B.cli} dev --port ${options.port} --auto\` to reattach.`));
+          }
           void cleanup(1);
         }
       }
@@ -6755,18 +6896,6 @@ async function runDev(options) {
   console.log();
   live = true;
   for (const line of held) console.log(line);
-  let isCleaningUp = false;
-  async function cleanup(exitCode = 0) {
-    if (isCleaningUp) return;
-    isCleaningUp = true;
-    console.log(import_chalk20.default.gray("\n\nShutting down..."));
-    for (const client of clients) client.close();
-    captureStream?.end();
-    await deleteDevTunnel(restore, keyAuth).catch(() => {
-    });
-    console.log(exitCode === 0 ? import_chalk20.default.green("Tunnel stopped.") : import_chalk20.default.yellow("Tunnel stopped."));
-    process.exit(exitCode);
-  }
   process.on("SIGINT", () => void cleanup());
   process.on("SIGTERM", () => void cleanup());
   process.on("SIGHUP", () => void cleanup());
@@ -15303,7 +15432,7 @@ function isOperatorLogin() {
   return !!email && OPERATOR_EMAILS.has(email);
 }
 var OP_COMMANDS = [
-  { cmd: "cli-policy", blurb: "Minimum CLI version the platform accepts (--min x.y.z, --reject-unversioned)" },
+  { cmd: "cli-policy", blurb: 'Minimum CLI version the platform accepts (--min x.y.z --reason "\u2026" [--force], --reject-unversioned)' },
   { cmd: "op latency", blurb: "which FEATURE is slow, and what inside it", extra: "--hours N --team T --project P" },
   { cmd: "op latency slow", blurb: "slowest requests, each with a request id you can look up", extra: "--min-ms N" },
   { cmd: "op latency llm", blurb: "chat timing by provider/model, tokens, credit-reserve cost" },
@@ -15450,16 +15579,20 @@ async function runOp(sub, opts = {}, view, arg) {
       const wantsChange = typeof opts.min === "string" || !!opts.rejectUnversioned || !!opts.allowUnversioned || typeof opts.message === "string";
       let out = cur;
       if (wantsChange) {
+        const reason = typeof opts.reason === "string" ? opts.reason.trim() : "";
+        if (!reason) throw new Error('cli-policy: a change needs --reason "<why>" (recorded with the policy).');
         out = await opCall({ method: "PUT", path: "/operator/cli/policy", summary: "set CLI version policy", body: {
           min_version: typeof opts.min === "string" ? opts.min : cur.min_version,
           reject_unversioned: opts.rejectUnversioned ? true : opts.allowUnversioned ? false : cur.reject_unversioned,
-          message: typeof opts.message === "string" ? opts.message : cur.message
+          message: typeof opts.message === "string" ? opts.message : cur.message,
+          reason,
+          ...opts.force ? { force: true } : {}
         } });
       }
       if (opts.json) return void console.log(JSON.stringify(out, null, 2));
       console.log("");
       console.log(`  Minimum CLI version:   ${import_chalk67.default.bold(out.min_version)}${out.min_version === "0.0.0" ? import_chalk67.default.dim("  (no minimum)") : ""}`);
-      console.log(`  Refuse unversioned:    ${out.reject_unversioned ? import_chalk67.default.yellow("yes \u2014 CLIs released before 2026-09-27 are refused") : "no"}`);
+      console.log(`  Refuse unversioned:    ${out.reject_unversioned ? import_chalk67.default.yellow("yes \u2014 CLIs released before 2026-09-27 get a 426 (cheap refusals; they keep retrying)") : "no"}`);
       console.log(`  Message:               ${out.message ?? import_chalk67.default.dim("(default)")}`);
       if (out.updated_at) console.log(import_chalk67.default.dim(`  Updated ${out.updated_at}${out.updated_by ? ` by ${out.updated_by}` : ""}`));
       console.log(import_chalk67.default.dim("  Takes effect within ~1 minute on the CLI lane; running `dev` sessions re-check every 10 minutes."));
@@ -15971,7 +16104,7 @@ apikeys.command("list").description("List control-plane API keys in your team").
 apikeys.command("mint").description("Create a control-plane API key (secret shown once) \u2014 or, with --tenant, a consumer key in that tenant: a backend key (default), a client key (--client) or a person-bound key (--for)").option("--desc <text>", "Description").option("--expires-days <n>", "Expiry in days (default 90 server-side)").option("--tenant <slug>", "Mint a CONSUMER key in this tenant instead of a control-plane key").option("--backend", `Backend key (default). ${HOLDER_HELP.backend}`).option("--client", `Client key. ${HOLDER_HELP.client} Needs --tenant.`).option("--for <email|id>", "Issue this key to a named person \u2014 calls made with it count as that person, and ownership rules trust it. The Users & Groups widget's admin lane accepts only such a key, one per admin. Needs --tenant.").option("--admin", "With --for: a key that acts as that tenant admin on the IAM API (users & groups) \u2014 adds manage-access; env defaults to prod").option("--env <name>", "Environment the consumer key is valid for (with --tenant; default dev, prod with --admin)").option("--team <id|name>", "Team (defaults to active team)").option("--json", "Output machine-readable JSON").action(action((opts, cmd) => runKeyMint({ ...cmd.parent?.opts(), ...opts })));
 apikeys.command("revoke").description("Revoke a control-plane API key").argument("<keyId>", "Key id (see `apikeys list`)").option("--team <id|name>", "Team (defaults to active team)").action(action((keyId, opts, cmd) => runKeyRevoke(keyId, { ...cmd.parent?.opts(), ...opts })));
 program.addCommand(apikeys);
-var op = new import_commander.Command("op").description("Operator menu (platform operators only)").argument("[action]", "latency | mark | wallet | money | incident | residue | sweep | test | perf | cli-policy (omit for the menu)").argument("[view]", "for `latency`: slow | llm | compare | grades | distance \xB7 for `wallet`: list | inspect | freeze \u2026 \xB7 for `money`: exposure | journal | reconcile \xB7 for `incident`: status | allow | deny | extend \xB7 for `mark`: the change name, quoted").argument("[arg]", "for `wallet inspect` / `money journal`: the wallet id (or a team id)").option("-y, --yes", "Skip the sweep confirmation prompt").option("--json", "Output machine-readable JSON").option("--hours <n>", "Look-back window in hours (default 1)").option("--team <id>", "Filter to one team").option("--only <ids>", "for `test`: comma-separated spec/gut ids or prefixes").option("--group <name>", "for `test`: only specs whose group matches").option("--skip-guts", "for `test`: contract specs only").option("--guts-only", "for `test`: server-side gut checks only").option("--fail-fast", "for `test`: stop at the first failure").option("--timeout <s>", "for `test`: seconds to wait per check (default 150)").option("--perf", "for `test`: run the performance gate instead of the suite (fixed-rate load on a sandbox proxy)").option("--consumer", "for `test`: probe the data plane with the stored `consumer login` token instead of the suite").option("--path <p>", "for `test --consumer`: request path on the proxy (default /get)").option("--proxy <name@version>", "for `test --consumer`: the OAuth-door proxy to knock on (default: the sandbox proxy for a sandbox-tenant session)").option("--rps <n>", "for `test --perf`: requests per second (default 100, max 300)").option("--seconds <n>", "for `test --perf`: how long to send for (default 60, max 300)").option("--url <url>", "for `test --perf`: load this fixture URL instead of provisioning one (with --key; nothing is torn down)").option("--max-p50 <ms>", "for `test --perf`: client p50 threshold (default 250)").option("--max-p95 <ms>", "for `test --perf`: client p95 threshold (default 800)").option("--max-error-rate <pct>", "for `test --perf`: error-rate threshold in percent (default 0.5)").option("--max-gateway-p50 <ms>", "for `test --perf`: apiblaze-overhead p50 threshold (default 60)").option("--max-gateway-p95 <ms>", "for `test --perf`: apiblaze-overhead p95 threshold (default 250)").option("--project <name>", "Filter to one proxy").option("--api-version <v>", "Filter to one API version").option("--tenant <name>", "Filter to one tenant").option("--route <path>", "Filter to one route").option("--environment <env>", "Filter to one environment").option("--status-class <c>", "Filter to a status class (2xx/4xx/5xx)").option("--min-ms <n>", "For `latency slow`: minimum duration (default 1000)").option("--min <version>", "for `cli-policy`: minimum CLI version (x.y.z; 0.0.0 = none)").option("--reject-unversioned", "for `cli-policy`: also refuse CLIs that send no version (released before 2026-09-27)").option("--allow-unversioned", "for `cli-policy`: stop refusing unversioned CLIs").option("--message <text>", "for `cli-policy`: message shown with the upgrade instruction").option("--days <n>", "For `latency grades`: how many days back (default 7)").option("--threshold-ms <n>", "For `latency distance`: network ms above which distance counts as a problem (default 50)").option("--excellent <ms>", "Grade threshold: under this is excellent (default 250)").option("--okay <ms>", "Grade threshold: under this is okay (default 500)").option("--bad <ms>", "Grade threshold: under this is bad, at/over is terrible (default 1000)").option("--key <key>", "for `test --perf --url`: the fixture's API key").option("--since <date>", "for `money journal` / `money reconcile`: start of the window (ISO date)").option("--kind <k>", "for `money journal`: one journal kind only").option("--limit <n>", "for `money journal` / `money exposure`: row cap").action(action((sub, view, arg, opts) => runOp(sub, opts, view, arg))).addHelpText("after", () => `
+var op = new import_commander.Command("op").description("Operator menu (platform operators only)").argument("[action]", "latency | mark | wallet | money | incident | residue | sweep | test | perf | cli-policy (omit for the menu)").argument("[view]", "for `latency`: slow | llm | compare | grades | distance \xB7 for `wallet`: list | inspect | freeze \u2026 \xB7 for `money`: exposure | journal | reconcile \xB7 for `incident`: status | allow | deny | extend \xB7 for `mark`: the change name, quoted").argument("[arg]", "for `wallet inspect` / `money journal`: the wallet id (or a team id)").option("-y, --yes", "Skip the sweep confirmation prompt").option("--json", "Output machine-readable JSON").option("--hours <n>", "Look-back window in hours (default 1)").option("--team <id>", "Filter to one team").option("--only <ids>", "for `test`: comma-separated spec/gut ids or prefixes").option("--group <name>", "for `test`: only specs whose group matches").option("--skip-guts", "for `test`: contract specs only").option("--guts-only", "for `test`: server-side gut checks only").option("--fail-fast", "for `test`: stop at the first failure").option("--timeout <s>", "for `test`: seconds to wait per check (default 150)").option("--perf", "for `test`: run the performance gate instead of the suite (fixed-rate load on a sandbox proxy)").option("--consumer", "for `test`: probe the data plane with the stored `consumer login` token instead of the suite").option("--path <p>", "for `test --consumer`: request path on the proxy (default /get)").option("--proxy <name@version>", "for `test --consumer`: the OAuth-door proxy to knock on (default: the sandbox proxy for a sandbox-tenant session)").option("--rps <n>", "for `test --perf`: requests per second (default 100, max 300)").option("--seconds <n>", "for `test --perf`: how long to send for (default 60, max 300)").option("--url <url>", "for `test --perf`: load this fixture URL instead of provisioning one (with --key; nothing is torn down)").option("--max-p50 <ms>", "for `test --perf`: client p50 threshold (default 250)").option("--max-p95 <ms>", "for `test --perf`: client p95 threshold (default 800)").option("--max-error-rate <pct>", "for `test --perf`: error-rate threshold in percent (default 0.5)").option("--max-gateway-p50 <ms>", "for `test --perf`: apiblaze-overhead p50 threshold (default 60)").option("--max-gateway-p95 <ms>", "for `test --perf`: apiblaze-overhead p95 threshold (default 250)").option("--project <name>", "Filter to one proxy").option("--api-version <v>", "Filter to one API version").option("--tenant <name>", "Filter to one tenant").option("--route <path>", "Filter to one route").option("--environment <env>", "Filter to one environment").option("--status-class <c>", "Filter to a status class (2xx/4xx/5xx)").option("--min-ms <n>", "For `latency slow`: minimum duration (default 1000)").option("--min <version>", "for `cli-policy`: minimum CLI version (x.y.z; 0.0.0 = none)").option("--reject-unversioned", "for `cli-policy`: also refuse CLIs that send no version (released before 2026-09-27)").option("--allow-unversioned", "for `cli-policy`: stop refusing unversioned CLIs").option("--message <text>", "for `cli-policy`: message shown with the upgrade instruction").option("--reason <text>", "for `cli-policy`: why the policy changes (required for a change; recorded with it)").option("--force", "for `cli-policy`: allow a minimum above the latest published npm version (locks out every CLI until it ships)").option("--days <n>", "For `latency grades`: how many days back (default 7)").option("--threshold-ms <n>", "For `latency distance`: network ms above which distance counts as a problem (default 50)").option("--excellent <ms>", "Grade threshold: under this is excellent (default 250)").option("--okay <ms>", "Grade threshold: under this is okay (default 500)").option("--bad <ms>", "Grade threshold: under this is bad, at/over is terrible (default 1000)").option("--key <key>", "for `test --perf --url`: the fixture's API key").option("--since <date>", "for `money journal` / `money reconcile`: start of the window (ISO date)").option("--kind <k>", "for `money journal`: one journal kind only").option("--limit <n>", "for `money journal` / `money exposure`: row cap").action(action((sub, view, arg, opts) => runOp(sub, opts, view, arg))).addHelpText("after", () => `
 ${renderOpCommands()}
 `);
 program.addCommand(op, { hidden: true });
@@ -16070,6 +16203,10 @@ async function recoverStaleTeam() {
   }
 }
 async function printError(err) {
+  if (err instanceof CliUpgradeRequired) {
+    await handleUpgradeRequired(err);
+    return;
+  }
   if (err instanceof ApiError) {
     const data = err.body;
     const extra = [data?.body?.reason, data?.body?.details, data?.details, data?.body?.error].find((x) => typeof x === "string" && x && x !== err.message);
@@ -16103,8 +16240,23 @@ does not have it, your npx cache is serving an older copy \u2014 re-run as:
 }
 hintStaleCacheOnUnknownOption(program);
 installFetchGuard(version);
-var skipPolicy = process.argv.some((a) => a === "--version" || a === "-V" || a === "--help" || a === "-h");
+var firstCommand = process.argv.slice(2).find((a) => !a.startsWith("-"));
+var skipPolicy = firstCommand === "op" || process.argv.some((a) => a === "--version" || a === "-V" || a === "--help" || a === "-h");
+process.on("unhandledRejection", (reason) => {
+  if (reason instanceof CliUpgradeRequired) {
+    void handleUpgradeRequired(reason);
+    return;
+  }
+  console.error(reason);
+  process.exit(1);
+});
 (async () => {
-  if (!skipPolicy) await checkCliPolicy(version);
+  if (!skipPolicy) {
+    try {
+      await checkCliPolicy(version);
+    } catch (err) {
+      if (err instanceof CliUpgradeRequired) return void await handleUpgradeRequired(err);
+    }
+  }
   program.parse(process.argv);
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apiblaze",
-  "version": "0.21.18",
+  "version": "0.21.19",
   "description": "APIblaze CLI — Chat with your APIs, Manage your API keys, users and groups with the APIblaze serverless proxy",
   "keywords": [
     "apiblaze",