@rebasepro/cli 0.23.0 → 0.24.1-canary.g19596ef

package/dist/context-BqhRydBg.js

@@ -0,0 +1,1234 @@
+import { c as findProjectRoot } from "./project-Wp2zoyeN.js";
+import { n as parseCommandArgs } from "./args-BnmsEXvu.js";
+import { t as cliUserAgent } from "./version-Buyyo1ut.js";
+import chalk from "chalk";
+import arg from "arg";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { spawn } from "child_process";
+import { parseEnvBoolean } from "@rebasepro/types";
+import inquirer from "inquirer";
+import { createMemoryStorage, createRebaseClient } from "@rebasepro/client";
+//#region src/commands/cloud/errors.ts
+/**
+* Turning a control-plane failure into something the caller can act on.
+*
+* The control plane talks to Kubernetes, and when Kubernetes refuses it, the
+* refusal travels back verbatim: a whole `Status` object, the request headers,
+* an `audit-id`, an `x-kubernetes-pf-flowschema-uid`. That reached the user's
+* terminal unedited. Two things are wrong with it beyond the noise.
+*
+* The first is that the one sentence that matters is buried in the middle of a
+* JSON blob, so the remedy — if there is one — is the hardest part to find.
+*
+* The second is worse, and is the reason this file exists rather than a
+* `slice(0, 200)`. A `403` naming a `system:serviceaccount:` is a statement
+* about the PLATFORM's own credentials: some role the control plane runs as is
+* missing a grant. Nothing in the user's project can change that — not the
+* collections, not `rebase.json`, not the deploy flags — and the error, printed
+* raw in the middle of `rebase cloud deploy`, reads exactly like a project
+* fault. Someone acting on that reading deletes working code looking for the
+* cause. (That is not hypothetical: three cron jobs were removed from a project
+* to test whether they caused a `cronjobs.batch` 403. They did not.)
+*
+* So this classifies before it summarises, and says whose problem it is.
+*/
+/**
+* The service accounts a Kubernetes 403 can name, and what each means.
+*
+* `system:serviceaccount:` is the platform's own identity — the control plane's
+* pod, or a tenant's operator. A project cannot grant it anything, because the
+* grant lives in a cluster the project does not own. `system:anonymous` is the
+* same fact with the credential missing entirely.
+*/
+var PLATFORM_PRINCIPAL_RE = /system:(?:serviceaccount:|anonymous|node:)/;
+/**
+* A Kubernetes `Status` object embedded anywhere in a message.
+*
+* Scanned for rather than parsed off the front: the control plane wraps it
+* ("Failed to create the tenant namespace: …"), the client library appends
+* headers after it, and both halves are worth keeping out of the summary.
+* Balanced-brace scanning rather than a regex, because `details.causes` nests
+* and a lazy `\{.*?\}` truncates the object at the first inner brace — which
+* parses to nothing and silently falls through to the raw message.
+*/
+function extractKubernetesStatus(text) {
+	for (let start = text.indexOf("{"); start !== -1; start = text.indexOf("{", start + 1)) {
+		let depth = 0;
+		let inString = false;
+		let escaped = false;
+		for (let i = start; i < text.length; i++) {
+			const ch = text[i];
+			if (escaped) {
+				escaped = false;
+				continue;
+			}
+			if (ch === "\\") {
+				escaped = true;
+				continue;
+			}
+			if (ch === "\"") {
+				inString = !inString;
+				continue;
+			}
+			if (inString) continue;
+			if (ch === "{") depth++;
+			else if (ch === "}") {
+				depth--;
+				if (depth !== 0) continue;
+				const candidate = text.slice(start, i + 1);
+				let parsed;
+				try {
+					parsed = JSON.parse(candidate);
+				} catch {
+					break;
+				}
+				const obj = parsed;
+				if (obj?.kind === "Status" || obj?.status === "Failure" && typeof obj.code === "number") return {
+					message: typeof obj.message === "string" ? obj.message : void 0,
+					reason: typeof obj.reason === "string" ? obj.reason : void 0,
+					code: typeof obj.code === "number" ? obj.code : void 0,
+					details: obj.details ?? void 0
+				};
+				break;
+			}
+		}
+	}
+}
+/**
+* Strip the transport noise a Kubernetes client appends to its own message.
+*
+* Only ever applied to the fallback path — when no `Status` was found, the
+* message is all there is, and cutting it at the first header keeps the
+* sentence while dropping the `audit-id` and the flowschema uid nobody outside
+* the cluster can use.
+*/
+function trimTransportNoise(message) {
+	const cut = message.search(/\s*(?:headers:|HTTP request failed|audit-id|x-kubernetes-pf-|\{"kind":"Status")/i);
+	return (cut > 0 ? message.slice(0, cut) : message).trim().replace(/[\s:,-]+$/, "");
+}
+/** The longest a summary may be before it stops being one. */
+var MAX_SUMMARY = 300;
+/**
+* One actionable line (plus a hint) from whatever the control plane returned.
+*
+* `status` is the HTTP status of the control-plane call itself, which is a
+* different number from the `code` inside an embedded Kubernetes `Status` — the
+* control plane routinely answers 500 while the cluster answered 403, and it is
+* the inner one that says what happened.
+*/
+function summarizeError(error, context) {
+	const err = error;
+	const raw = err?.message ?? String(error);
+	const k8s = extractKubernetesStatus(raw);
+	if (k8s) {
+		const inner = k8s.message?.trim() ?? "";
+		if ((k8s.code === 403 || k8s.reason === "Forbidden") && PLATFORM_PRINCIPAL_RE.test(inner)) return {
+			message: `${context}: the platform's own cluster credentials were refused by Kubernetes.`,
+			hint: `${truncate(inner)}\n  This is a platform-side permission, not something your project can grant. Nothing in your code, collections or deploy flags will change it — report it with the message above rather than retrying or changing the project.`,
+			code: "platform_permission_denied",
+			platform: true,
+			raw
+		};
+		return {
+			message: `${context}: ${truncate(inner || k8s.reason || "the cluster refused the request")}`,
+			hint: k8s.code ? `Kubernetes answered ${k8s.code}${k8s.reason ? ` (${k8s.reason})` : ""}.` : void 0,
+			code: k8s.reason ? `k8s_${k8s.reason.toLowerCase()}` : "k8s_error",
+			platform: false,
+			raw
+		};
+	}
+	const trimmed = trimTransportNoise(raw);
+	return {
+		message: `${context}${err?.status ? ` (${err.status})` : ""}: ${truncate(trimmed || raw)}`,
+		code: err?.code ?? (err?.status ? `http_${err.status}` : "request_failed"),
+		platform: false,
+		raw
+	};
+}
+function truncate(text) {
+	const flat = text.replace(/\s+/g, " ").trim();
+	return flat.length > MAX_SUMMARY ? `${flat.slice(0, MAX_SUMMARY - 1)}…` : flat;
+}
+/**
+* Whether the caller asked for the untouched body.
+*
+* `--debug` is already what `bin/rebase.js` prints after every failure as the
+* thing to add, so the raw payload hangs off the flag people are told to reach
+* for rather than off one invented here.
+*
+* The one reader of `REBASE_DEBUG` in the commands, spelled as the bin spells
+* it. It used to be `=== "1"` here while the quote fallbacks in `resources.ts`
+* tested the raw string for truthiness, so `=true` hid the body and `=0`
+* printed the fallback.
+*/
+function wantsRawError(argv = process.argv) {
+	return argv.includes("--debug") || parseEnvBoolean(process.env.REBASE_DEBUG) === true;
+}
+//#endregion
+//#region src/commands/cloud/context.ts
+/**
+* Shared foundation for the `rebase cloud` command family.
+*
+* Everything cloud subcommands need in common lives here:
+*   - credential storage  (~/.rebase/credentials.json, keyed per control-plane host)
+*   - project link file    (.rebase/cloud.json in the project dir)
+*   - control-plane URL resolution
+*   - an authenticated `@rebasepro/client` instance (createCloudClient / requireClient)
+*   - small output helpers shared across subcommands
+*
+* The control plane is itself a Rebase app, so we reuse the same SDK the web
+* console uses (`@rebasepro/client`). Auth, token refresh, the data REST client
+* and function invocation all come from the SDK — the CLI only supplies a
+* file-backed AuthStorage so a login persists across invocations.
+*/
+/** Default hosted control plane (the Rebase Cloud console origin). */
+var DEFAULT_CLOUD_URL = "https://app.rebase.pro";
+/** The storage key the SDK's auth module reads/writes the session under. */
+var SDK_SESSION_KEY = "rebase_auth";
+/** ~/.rebase/credentials.json — one file, many hosts. */
+function credentialsPath() {
+	return path.join(os.homedir(), ".rebase", "credentials.json");
+}
+/** Project-local link file: <project>/.rebase/cloud.json */
+/**
+* The billing account an organization row points at, whichever key it arrived under.
+*
+* REST serves every column under its own property name, so the relation comes
+* back as `billingAccountId`. Both readers in this CLI checked
+* `billing_account_id` and `billingAccount` — neither is what arrives — so
+* `rebase cloud billing` answered "no billing account" for every organization,
+* and the deploy pre-check never saw an internal plan. The other two spellings
+* are still accepted: older servers and fixtures send them.
+*/
+function billingAccountIdOf(org) {
+	if (typeof org !== "object" || org === null) return void 0;
+	for (const key of [
+		"billingAccountId",
+		"billing_account_id",
+		"billingAccount"
+	]) {
+		const value = org[key];
+		if (typeof value === "string" || typeof value === "number") return value;
+	}
+}
+function projectLinkPath(cwd = process.cwd()) {
+	const root = findProjectRoot(cwd) || cwd;
+	return path.join(root, ".rebase", "cloud.json");
+}
+function readCredentials() {
+	try {
+		const raw = fs.readFileSync(credentialsPath(), "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!parsed.contexts) parsed.contexts = {};
+		return parsed;
+	} catch {
+		return { contexts: {} };
+	}
+}
+function writeCredentials(data) {
+	const file = credentialsPath();
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, JSON.stringify(data, null, 2), { mode: 384 });
+	try {
+		fs.chmodSync(file, 384);
+	} catch {}
+}
+/** Host that a bare `rebase cloud` command should target, if any. */
+function currentContextUrl() {
+	return readCredentials().current;
+}
+/** Persist the active organization id for a host. */
+function setContextOrg(url, org) {
+	const creds = readCredentials();
+	const entry = creds.contexts[url] || {};
+	if (org) entry.org = org;
+	else delete entry.org;
+	creds.contexts[url] = entry;
+	writeCredentials(creds);
+}
+function getContextOrg(url) {
+	return readCredentials().contexts[url]?.org;
+}
+function createFileAuthStorage(url) {
+	return {
+		getItem(key) {
+			if (key !== SDK_SESSION_KEY) return null;
+			return readCredentials().contexts[url]?.auth ?? null;
+		},
+		setItem(key, value) {
+			if (key !== SDK_SESSION_KEY) return;
+			const creds = readCredentials();
+			const entry = creds.contexts[url] || {};
+			entry.auth = value;
+			creds.contexts[url] = entry;
+			if (!creds.current) creds.current = url;
+			writeCredentials(creds);
+		},
+		removeItem(key) {
+			if (key !== SDK_SESSION_KEY) return;
+			const creds = readCredentials();
+			if (creds.contexts[url]) {
+				delete creds.contexts[url].auth;
+				delete creds.contexts[url].org;
+			}
+			writeCredentials(creds);
+		}
+	};
+}
+/** Mark a host as the active context (called on login). */
+function setCurrentContext(url) {
+	const creds = readCredentials();
+	creds.current = url;
+	if (!creds.contexts[url]) creds.contexts[url] = {};
+	writeCredentials(creds);
+}
+function resolveCloudUrl(rawArgs) {
+	return resolveCloudTarget(rawArgs).url;
+}
+/** The control-plane URL, and which rung of the ladder above supplied it. */
+function resolveCloudTarget(rawArgs) {
+	const parsed = arg({ "--url": String }, {
+		argv: rawArgs.slice(2),
+		permissive: true
+	});
+	if (parsed["--url"]) return {
+		url: normalizeUrl(parsed["--url"]),
+		source: "flag"
+	};
+	if (process.env.REBASE_CLOUD_URL) return {
+		url: normalizeUrl(process.env.REBASE_CLOUD_URL),
+		source: "env"
+	};
+	const link = readLink();
+	if (link?.url && link.mode !== "direct") return {
+		url: normalizeUrl(link.url),
+		source: "link"
+	};
+	const current = currentContextUrl();
+	if (current) return {
+		url: normalizeUrl(current),
+		source: "context"
+	};
+	return {
+		url: DEFAULT_CLOUD_URL,
+		source: "default"
+	};
+}
+/**
+* Whether a control-plane host is one the user chose: the platform's own, or a
+* host already in their credentials file because they signed in to it.
+*
+* A link file is part of the repository, and a cloned repository is not the
+* user's to trust with their password. `login` asks before sending one to a
+* linked host that is neither.
+*/
+function isKnownControlPlane(url) {
+	return url === DEFAULT_CLOUD_URL || Object.hasOwn(readCredentials().contexts, url);
+}
+/**
+* Refuse to run a control-plane command in a directory linked straight at a
+* backend.
+*
+* The alternative — quietly using the default control plane — would be worse
+* than the bug it replaces: the user asked for `https://api.example.com` and
+* would get an answer about `app.rebase.pro` with nothing saying so. Naming the
+* link, and both ways out of it, is the whole message.
+*
+* `--project` and `--url` are the ways out, so a line carrying either passes
+* through: both say, explicitly, which control-plane subject the caller means.
+*/
+function refuseDirectLink(rawArgs) {
+	const link = readLink();
+	if (link?.mode !== "direct") return;
+	const parsed = arg({
+		"--project": String,
+		"-p": "--project",
+		"--url": String
+	}, {
+		argv: rawArgs.slice(2),
+		permissive: true
+	});
+	if (parsed["--project"] || parsed["--url"]) return;
+	fail(`This directory is linked directly to ${chalk.cyan(link.url)} — ${chalk.bold("rebase cloud unlink")} first, or pass ${chalk.bold("--project")}.`, "A direct link is one backend, not a control plane: it has no projects, no organizations and no session.", "direct_link");
+}
+function normalizeUrl(url) {
+	let u = url.trim().replace(/\/+$/, "");
+	if (!/^https?:\/\//.test(u)) u = `https://${u}`;
+	return u;
+}
+/**
+* Build an SDK client bound to a control-plane host, backed by the on-disk
+* credential store. `autoRefresh` is disabled so we never leave a dangling
+* setTimeout that keeps the CLI process alive; token refresh is done on demand
+* by `requireClient`.
+*/
+function createCloudClient(url) {
+	return createRebaseClient({
+		baseUrl: url,
+		realtime: false,
+		headers: { "User-Agent": cliUserAgent() },
+		auth: {
+			storage: createFileAuthStorage(url),
+			persistSession: true,
+			autoRefresh: false
+		}
+	});
+}
+/**
+* The environment variable that authenticates the cloud family with a token
+* instead of a `cloud login` session — for CI and agents, which have no
+* terminal to log in at and should not hold a person's password.
+*/
+var TOKEN_ENV = "REBASE_TOKEN";
+/** `REBASE_TOKEN`, trimmed, or undefined when it is unset or blank. */
+function envToken() {
+	const value = process.env[TOKEN_ENV]?.trim();
+	return value ? value : void 0;
+}
+/** The token each token-authenticated client was built with — see {@link freshAccessToken}. */
+var STATIC_TOKENS = /* @__PURE__ */ new WeakMap();
+/**
+* A client that sends `token` as its bearer and nothing else.
+*
+* No session: the token is not refreshed, and the credentials file is neither
+* read nor written — a CI job's token must not become, or replace, the login
+* of whoever owns the machine. A 401 is answered by {@link explainRefusedToken}
+* rather than by the SDK's session refresh, because there is no session to
+* refresh and "log in again" is the wrong remedy for a token.
+*/
+function createTokenClient(url, token) {
+	const client = createRebaseClient({
+		baseUrl: url,
+		realtime: false,
+		headers: { "User-Agent": cliUserAgent() },
+		token,
+		auth: {
+			storage: createMemoryStorage(),
+			persistSession: false,
+			autoRefresh: false
+		}
+	});
+	client.setOnUnauthorized(() => explainRefusedToken(url, token));
+	STATIC_TOKENS.set(client, token);
+	return client;
+}
+/**
+* Why the control plane answered a token-authenticated request with 401, and
+* what to do about it. Never returns.
+*
+* Two different causes reach the same status. Usually the token itself was
+* refused — it expired, was revoked, or belongs to another control plane — and
+* the remedy is a new token. But a few endpoints take only a person's session
+* (`/auth/me` among them), and those refuse a perfectly good token too. One
+* request to `/api/auth/scopes`, which accepts a token, tells the two apart, so
+* neither is answered with the other's remedy.
+*/
+async function explainRefusedToken(url, token) {
+	let tokenAccepted = false;
+	try {
+		tokenAccepted = (await fetch(`${url}/api/auth/scopes`, { headers: {
+			Authorization: `Bearer ${token}`,
+			"User-Agent": cliUserAgent()
+		} })).ok;
+	} catch {}
+	if (tokenAccepted) fail(`This command needs a signed-in session, and ${TOKEN_ENV} is an API token.`, `Unset ${TOKEN_ENV} and run ${chalk.bold("rebase cloud login")} to run it.`, "session_required");
+	fail(`${TOKEN_ENV} was rejected by ${url}: it has expired, been revoked, or was not issued by this control plane.`, `Create a new one with ${chalk.bold("rebase cloud tokens create")} and put it in ${TOKEN_ENV}.`, "token_rejected");
+}
+/** Two minutes of head-room before a token is treated as expired. */
+var EXPIRY_BUFFER_MS = 12e4;
+/**
+* An access token with time left on it, refreshed first if it is close to
+* expiry. Rejects when there is no session, or it cannot be refreshed.
+*
+* For the requests the SDK does not make itself. Its own calls refresh and
+* retry on a 401; a raw `fetch` or a tunnel handshake presents whatever token
+* it was handed, and `createCloudClient` never refreshes in the background. A
+* token read once at the start of a command that runs for longer than it
+* lives — a deploy's build, a `db connect` left open — is refused by the time
+* it is used, so it is read here at the moment it is sent.
+*
+* A client built from `REBASE_TOKEN` has no session; its token is returned
+* as it is, since there is nothing to refresh it with.
+*/
+async function freshAccessToken(client) {
+	const fixed = STATIC_TOKENS.get(client);
+	if (fixed) return fixed;
+	const session = client.auth.getSession();
+	if (session?.accessToken && session.expiresAt > Date.now() + EXPIRY_BUFFER_MS) return session.accessToken;
+	return (await client.auth.refreshSession()).accessToken;
+}
+/**
+* Return an authenticated client for the resolved host.
+*
+* With `REBASE_TOKEN` set, that token is the credential for every request and
+* the stored login is not consulted at all. Otherwise it is the `cloud login`
+* session — see {@link requireSessionClient}.
+*/
+async function requireClient(rawArgs) {
+	const token = envToken();
+	if (!token) return requireSessionClient(rawArgs);
+	refuseDirectLink(rawArgs);
+	const url = resolveCloudUrl(rawArgs);
+	return {
+		client: createTokenClient(url, token),
+		url
+	};
+}
+/**
+* Return a client holding the `cloud login` session for the resolved host,
+* refreshing the access token if it is close to expiry, whether or not
+* `REBASE_TOKEN` is set. Exits with a helpful message when there is no usable
+* session (never logged in, or the refresh token was revoked).
+*
+* For the commands a token cannot run — minting and revoking tokens: a key that
+* could mint keys could mint its own successor, so the control plane refuses
+* every key on those routes.
+*/
+async function requireSessionClient(rawArgs) {
+	refuseDirectLink(rawArgs);
+	const url = resolveCloudUrl(rawArgs);
+	const client = createCloudClient(url);
+	const session = client.auth.getSession();
+	if (!session || !session.accessToken) {
+		if (envToken()) fail(`This command needs a signed-in session for ${chalk.cyan(url)}, and ${TOKEN_ENV} is an API token.`, `A token cannot manage tokens. Run ${chalk.bold("rebase cloud login")} first.`, "session_required");
+		fail(`Not logged in to ${chalk.cyan(url)}.`, `Run ${chalk.bold("rebase cloud login")} first.`, "not_logged_in");
+	}
+	if (session.expiresAt <= Date.now() + EXPIRY_BUFFER_MS) try {
+		await client.auth.refreshSession();
+	} catch {
+		fail(`Your session for ${chalk.cyan(url)} has expired.`, `Run ${chalk.bold("rebase cloud login")} to sign in again.`, "session_expired");
+	}
+	return {
+		client,
+		url
+	};
+}
+/**
+* The control plane's public, non-secret self-description (`platform-config`).
+*
+* None of it is knowable from the CLI side: it is per-deployment configuration —
+* production serves tenants at `rebase.website` on GKE, a dev control plane at
+* `localhost` on Docker. Guessing produced two separate lies: a congratulation
+* URL that resolved nowhere near the app, and a `provider` the project does not
+* run on (see `createProject`).
+*
+* Cached per host for the process: it is fixed for a control plane's lifetime,
+* and `projects list` formats one host per row off a single fetch.
+*
+* @returns the config, or `undefined` if the control plane doesn't serve
+*   `platform-config` (an older deployment) or the request failed. A failure is
+*   cached too — a short-lived CLI should not retry once per row. Note the
+*   distinction callers rely on: `undefined` means "this control plane cannot
+*   tell us", whereas `deployTargets: []` is a control plane stating that it has
+*   no infrastructure configured.
+*/
+var platformConfigCache = /* @__PURE__ */ new Map();
+function fetchPlatformConfig(client, url) {
+	let pending = platformConfigCache.get(url);
+	if (!pending) {
+		pending = client.functions.invoke("platform-config", void 0, { method: "GET" }).then((cfg) => cfg ?? void 0).catch(() => void 0);
+		platformConfigCache.set(url, pending);
+	}
+	return pending;
+}
+/**
+* The base domain tenant projects are served at, derived from the same
+* TENANT_BASE_DOMAIN the ingress and the console read (see
+* saas/backend/src/utils/tenant-domain.ts).
+*/
+function fetchTenantBaseDomain(client, url) {
+	return fetchPlatformConfig(client, url).then((cfg) => cfg?.tenantBaseDomain?.trim() || void 0);
+}
+/**
+* The infrastructure a deploy for this control plane would ACTUALLY use, in the
+* resolver's own preference order (saas/backend/src/k8s/resolve.ts).
+*
+* @returns the targets, or `undefined` when the control plane cannot say.
+*/
+function fetchDeployTargets(client, url) {
+	return fetchPlatformConfig(client, url).then((cfg) => Array.isArray(cfg?.deployTargets) ? cfg.deployTargets : void 0);
+}
+/**
+* Public host for a project — `<subdomain>.<base>`, or the bare subdomain when
+* the base domain is unknown.
+*
+* It deliberately never falls back to a guessed domain. The user copies this
+* string into a browser, so a plausible-but-wrong hostname is worse than an
+* obviously incomplete one: `acme.rebase.pro` looks reachable and isn't, while
+* `acme` reads as "the subdomain is acme" and prompts no wasted debugging.
+*/
+function formatTenantHost(subdomain, baseDomain) {
+	if (!subdomain) return void 0;
+	return baseDomain ? `${subdomain}.${baseDomain}` : subdomain;
+}
+/**
+* The host to display for a project.
+*
+* Prefers `host` off the record: the control plane resolves it through the same
+* `tenantHost()` the ingress uses, so it accounts for the project's *cluster*
+* base domain. The CLI cannot compute that itself — `clusters` is admin-only
+* under RLS, so a normal user's token cannot read `baseDomain`, and a project on
+* a second cluster is served somewhere the platform default does not name.
+*
+* `baseDomain` (from `platform-config`) remains the fallback for a control plane
+* that predates the hook — right for the single-cluster case, which is every
+* project today.
+*/
+function projectHost(project, baseDomain) {
+	return project.host || formatTenantHost(project.subdomain, baseDomain);
+}
+function readLink(cwd = process.cwd()) {
+	try {
+		return JSON.parse(fs.readFileSync(projectLinkPath(cwd), "utf-8"));
+	} catch {
+		return null;
+	}
+}
+function writeLink(link, cwd = process.cwd()) {
+	const file = projectLinkPath(cwd);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, JSON.stringify(link, null, 2));
+}
+function removeLink(cwd = process.cwd()) {
+	const file = projectLinkPath(cwd);
+	if (fs.existsSync(file)) {
+		fs.rmSync(file);
+		return true;
+	}
+	return false;
+}
+/**
+* Flags that may appear anywhere on a `rebase cloud` line, including *before*
+* the resource group.
+*
+* They have to be declared wherever positionals are resolved, because `arg`'s
+* `permissive: true` does not merely tolerate an undeclared flag — it pushes it
+* into `_` alongside the positionals, and for a flag that takes a value it
+* pushes the value in too. So `cloud --project acme storage create` parsed
+* without this spec yields `_` of `["--project", "acme", "storage", "create"]`,
+* and the group reads as `"acme"`: a real project name, in the group position,
+* dispatching to nothing. Skipping tokens that start with `-` does not save you
+* there — the damage is the orphaned value, which looks exactly like a
+* positional.
+*
+* Only genuinely global flags belong here. Group-specific ones (`--bucket`,
+* `--region`, …) are declared by the handler that owns them. They can still
+* precede the action — or stand in for it, on a group with a default — so the
+* dispatcher also declares every one that takes a value: `CLOUD_VALUE_FLAGS`
+* in `index.ts`.
+*
+* `-p` is `--project` in eighteen places and `--password` in `login`. That
+* ambiguity does not matter to the one caller that reads this spec: it resolves
+* positionals and never looks at a flag's value, so all it needs to know is
+* that `-p` takes one. Anything that wants the value must keep declaring it
+* itself, with the meaning its own command gives it.
+*/
+var GLOBAL_CLOUD_FLAGS = {
+	"--json": Boolean,
+	"--yes": Boolean,
+	"--help": Boolean,
+	"--project": String,
+	"--url": String,
+	"-p": "--project",
+	"-y": "--yes",
+	"-h": "--help"
+};
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* The raw project reference to operate on: explicit `--project` flag wins,
+* otherwise the linked project. Exits with guidance when neither is present.
+* The value is a slug (the project's subdomain, as shown in console URLs) or,
+* for old scripts and link files, a raw project UUID.
+*/
+function requireProjectRef(rawArgs) {
+	const parsed = arg({
+		"--project": String,
+		"-p": "--project"
+	}, {
+		argv: rawArgs.slice(2),
+		permissive: true
+	});
+	if (parsed["--project"]) return parsed["--project"];
+	const link = readLink();
+	if (link?.projectId) return link.projectId;
+	fail("No project specified and this directory is not linked.", `Pass ${chalk.bold("--project <slug>")} or run ${chalk.bold("rebase cloud link")}.`, "no_project");
+}
+/**
+* Resolve a project reference — slug or UUID — to the internal id the API
+* takes, or undefined when no such project is visible. Slugs cost one lookup;
+* UUIDs pass through untouched so linked directories and old scripts skip the
+* round-trip.
+*/
+async function lookupProjectId(ref, client) {
+	if (UUID_RE.test(ref)) return ref;
+	const row = (await client.data.collection("projects").find({
+		where: { subdomain: ["==", ref] },
+		limit: 1
+	})).data[0];
+	return row?.id === void 0 ? void 0 : String(row.id);
+}
+/** Like `lookupProjectId`, but exits with guidance when the ref matches nothing. */
+async function resolveProjectRef(ref, client) {
+	const id = await lookupProjectId(ref, client);
+	if (id === void 0) fail(`No project with slug ${chalk.bold(ref)}.`, `List yours with ${chalk.bold("rebase cloud projects")}.`, "project_not_found");
+	return id;
+}
+/** `requireProjectRef` + `resolveProjectRef` in one step. */
+async function requireProject(rawArgs, client) {
+	return resolveProjectRef(requireProjectRef(rawArgs), client);
+}
+/**
+* The project reference to SHOW: the slug the user typed or the linked slug.
+* Never resolves — for human output only. Old link files predate `slug` and
+* fall back to the stored id.
+*/
+function displayProjectRef(rawArgs) {
+	const parsed = arg({
+		"--project": String,
+		"-p": "--project"
+	}, {
+		argv: rawArgs.slice(2),
+		permissive: true
+	});
+	if (parsed["--project"]) return parsed["--project"];
+	const link = readLink();
+	return link?.slug || link?.projectId || "";
+}
+var JSON_MODE = false;
+/**
+* Resolve and latch the output mode for this invocation. Call once at the top of
+* `cloudCommand`, before anything can print or `fail`. Returns the resolved mode
+* (handy for tests, which otherwise leave it at its `false` default).
+*/
+function initOutputMode(rawArgs) {
+	if (arg({ "--json": Boolean }, {
+		argv: rawArgs.slice(2),
+		permissive: true
+	})["--json"]) JSON_MODE = true;
+	else JSON_MODE = parseEnvBoolean(process.env.REBASE_JSON) ?? process.stdout.isTTY !== true;
+	return JSON_MODE;
+}
+/** Whether the current invocation is emitting machine-readable JSON. */
+function isJsonMode() {
+	return JSON_MODE;
+}
+/** Strip ANSI colour codes — JSON output must never carry terminal escapes. */
+var ANSI_RE = /\[[0-9;]*m/g;
+function stripAnsi(s) {
+	return s.replace(ANSI_RE, "");
+}
+/**
+* Write one JSON value to stdout, followed by a newline.
+*
+* Indented, because the overwhelmingly common reader is a person or an agent
+* looking at a terminal — JSON mode is entered automatically whenever stdout is
+* not a TTY, so `rebase cloud deployments list` piped anywhere at all produced
+* a project's entire deployment history as one unwrapped line. `JSON.parse`
+* does not care about the whitespace; everything else does.
+*/
+function printJson(value) {
+	process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+/**
+* The one output primitive every new command uses: in JSON mode emit `json`
+* (and nothing else); otherwise run `human`. Keeping the two behind a single
+* call is what guarantees a command can never print a table AND a JSON blob.
+*/
+function emit(human, json) {
+	if (JSON_MODE) printJson(json);
+	else human();
+}
+/**
+* Print a help page — the human one, or a machine-readable description of the
+* same command in JSON mode.
+*
+* `--help` is the one place where "stdout is not a TTY" is a weak signal: a
+* person runs `rebase cloud db --help | less` and wants the page. But the rule
+* this family promises is that stdout carries one JSON value whenever it is not
+* a terminal, and a help page is the easiest possible thing to describe
+* structurally — so rather than carve out an exception, help answers the same
+* question in the reader's own language. For an agent, `--help` piped is then a
+* discovery call rather than 60 lines of ANSI to scrape.
+*
+* `env` shipped this shape first, alone; this generalises it so every group
+* answers the same way.
+*/
+function emitHelp(command, actions, human, extra = {}) {
+	emit(human, {
+		command,
+		actions: actions.map((entry) => describeAction(entry, command)),
+		...extra
+	});
+}
+/**
+* Normalise an action for the JSON form. Strings stay legal — the index page
+* lists group names, which are not actions of the command being described.
+*
+* `command` is the page's own command (`cloud env`), so the usage line a caller
+* reads is a line it can run: without it the answer said `rebase cloud set
+* KEY=VALUE`, which is a command that does not exist.
+*/
+function describeAction(entry, command) {
+	if (typeof entry === "string") return {
+		action: entry,
+		description: "",
+		flags: []
+	};
+	return {
+		action: entry.action,
+		usage: `rebase ${command} ${entry.action}${entry.args ? ` ${entry.args}` : ""}`,
+		description: entry.description,
+		flags: (entry.flags ?? []).map(([flag, description]) => ({
+			flag,
+			description
+		}))
+	};
+}
+/**
+* Flags every cloud command accepts, documented once.
+*
+* Lives here rather than in `action-help.ts` because both help renderers print
+* it and `action-help` imports this module, not the other way round.
+*/
+var GLOBAL_HELP_FLAGS = [
+	["--project, -p <slug>", "Operate on a project without linking this directory"],
+	["--json", "Machine-readable output (also when piped, or REBASE_JSON=1)"],
+	["--url <origin>", "Target a specific control plane (or REBASE_CLOUD_URL)"],
+	["--yes, -y", "Skip confirmation prompts"],
+	["--debug", "Print the untouched error body after a failure"]
+];
+[...Object.keys(GLOBAL_CLOUD_FLAGS)];
+/** Column width for an action word (+ its args) before its description. */
+var HELP_COLUMN = 28;
+/**
+* The gap after `text` in a `width`-wide column, never less than one space.
+*
+* `padEnd` returns the string unchanged when it is already at the width, which
+* glues the description onto the flag: `--connection-string <url>The external…`.
+*/
+function pad(text, width) {
+	return " ".repeat(Math.max(1, width - text.length));
+}
+/**
+* Print a group's page — the human one, and the same content as JSON when piped.
+*/
+function printGroupHelp(page) {
+	emitHelp(page.command, page.actions, () => {
+		console.log("");
+		console.log(`${chalk.bold(`rebase ${page.command}`)} — ${page.title}`);
+		console.log("");
+		console.log(chalk.green.bold("Usage"));
+		console.log(`  rebase ${page.command} ${chalk.blue("<action>")} [options]`);
+		let section;
+		for (const entry of page.actions) {
+			const heading = entry.section ?? "Commands";
+			if (heading !== section) {
+				section = heading;
+				console.log("");
+				console.log(chalk.green.bold(heading));
+			}
+			const word = `${entry.action}${entry.args ? ` ${entry.args}` : ""}`;
+			console.log(`  ${chalk.blue.bold(entry.action)}${entry.args ? ` ${chalk.gray(entry.args)}` : ""}${pad(word, HELP_COLUMN)}${entry.description}`);
+			for (const [flag, description] of entry.flags ?? []) console.log(`      ${chalk.blue(flag)}${pad(flag, HELP_COLUMN - 4)}${chalk.gray(description)}`);
+		}
+		if (page.options?.length) {
+			console.log("");
+			console.log(chalk.green.bold("Options"));
+			for (const [flag, description] of page.options) console.log(`  ${chalk.blue(flag)}${pad(flag, HELP_COLUMN)}${description}`);
+		}
+		console.log("");
+		console.log(chalk.green.bold("Global options"));
+		for (const [flag, description] of GLOBAL_HELP_FLAGS) console.log(`  ${chalk.blue(flag)}${pad(flag, HELP_COLUMN)}${chalk.gray(description)}`);
+		if (page.notes?.length) {
+			console.log("");
+			for (const note of page.notes) console.log(chalk.gray(`  ${note}`));
+		}
+		console.log("");
+	}, {
+		usage: `rebase ${page.command} <action> [options]`,
+		summary: page.title,
+		options: (page.options ?? []).map(([flag, description]) => ({
+			flag,
+			description
+		})),
+		globalFlags: GLOBAL_HELP_FLAGS.map(([flag, description]) => ({
+			flag,
+			description
+		})),
+		notes: page.notes ?? []
+	});
+}
+/**
+* Print a warning (+ optional hint) — in every output mode, always to stderr.
+*
+* `emit` is for a command's *result*, and JSON mode legitimately replaces the
+* human rendering of one. A warning is not a result: it says the command is
+* about to do something the caller may not have meant, and that is exactly as
+* true when the output is piped. Gating one on `!isJsonMode()` deleted it
+* precisely where nobody was watching the terminal — a `--source` deploy ejected
+* a live project off the managed runtime and said so only to a TTY that wasn't
+* there.
+*
+* stdout carries the JSON value and nothing else, so warnings go to stderr:
+* a machine parser reading stdout cannot be corrupted by one. Only the
+* *formatting* may depend on the mode — colour and indentation for a terminal,
+* plain ASCII otherwise. Whether a warning is emitted at all may not.
+*
+* Anything a caller might branch on belongs in the JSON payload as well; stderr
+* is for whoever reads the transcript afterwards.
+*/
+function warn(message, hint) {
+	if (JSON_MODE) {
+		process.stderr.write(`warning: ${stripAnsi(message)}\n`);
+		if (hint) process.stderr.write(`  ${stripAnsi(hint)}\n`);
+		return;
+	}
+	console.error("");
+	console.error(chalk.yellow(`  ⚠ ${message}`));
+	if (hint) console.error(chalk.gray(`    ${hint}`));
+}
+/**
+* Print an error (+ optional hint) and exit non-zero. Never returns.
+*
+* `code` is the field a caller branches on, and it defaults to `"error"` rather
+* than `null`. An envelope whose only machine-readable field is null is not
+* machine-readable — `{"error":{"message":"No project specified…","code":null}}`
+* forced the very substring-matching on `message` that the envelope exists to
+* make unnecessary, and `message` is the field most likely to be reworded.
+*
+* `"error"` is deliberately a poor code: it says "this refusal has not been
+* classified yet" without ever being absent. Anything a caller might plausibly
+* want to distinguish — `usage`, `not_found`, `unauthenticated` — passes a real
+* one. Codes are part of the CLI's contract once shipped; see
+* `cloud-reporting.test.ts`, which pins the ones commands are documented to
+* return.
+*/
+function fail(message, hint, code) {
+	if (JSON_MODE) {
+		printJson({ error: {
+			message: stripAnsi(message),
+			code: code ?? "error",
+			hint: hint ? stripAnsi(hint) : void 0
+		} });
+		process.exit(1);
+	}
+	console.error("");
+	console.error(chalk.red(`  ✗ ${message}`));
+	if (hint) console.error(chalk.gray(`  ${hint}`));
+	console.error("");
+	process.exit(1);
+}
+/**
+* Confirm a destructive/irreversible action, respecting non-interactive use.
+*
+* With `--yes`/`-y` it proceeds silently. In JSON mode or a non-TTY it REFUSES
+* to prompt — a prompt that can hang is a known repo landmine — and fails,
+* telling the caller to pass `--yes`. Only an interactive terminal gets a real
+* confirm prompt; declining there aborts cleanly (exit 0).
+*/
+async function confirmDestructive(opts) {
+	if (opts.yes) return;
+	if (JSON_MODE || process.stdin.isTTY !== true) fail("This action is destructive and needs confirmation.", `Re-run with ${chalk.bold("--yes")} to proceed.`, "confirmation_required");
+	const { confirmed } = await inquirer.prompt([{
+		type: "confirm",
+		name: "confirmed",
+		default: false,
+		message: opts.prompt
+	}]);
+	if (!confirmed) {
+		console.error(chalk.gray("  Aborted."));
+		process.exit(0);
+	}
+}
+/**
+* Refuse, rather than prompt, when there is nobody to answer.
+*
+* `confirmDestructive` has always done this for yes/no confirmations. The
+* *value* prompts had no such guard: `cloud login`, `cloud link`, `cloud use`,
+* `cloud orgs create` and `cloud db create` all called `inquirer.prompt`
+* unconditionally, so piping any of them — which is how an agent runs every
+* command in this family — parked the process on a prompt reading from a stdin
+* that was never going to produce a line. A hang is the worst failure mode
+* available here: no output, no exit code, nothing to retry on.
+*
+* @param what   what the prompt would have asked for, e.g. "an email and password"
+* @param flags  the flags that supply it non-interactively
+*/
+function requireInteractive(what, flags) {
+	if (JSON_MODE || process.stdin.isTTY !== true) fail(`This command needs ${what}, and there is no terminal to ask on.`, `Pass ${chalk.bold(flags)}.`, "input_required");
+}
+/**
+* Resolve one cloud command's flags and ARGUMENTS from the full `process.argv`.
+*
+* This replaces `cloudPositionals`, which was `rawArgs.slice(3).filter(a =>
+* !a.startsWith("-"))`. Dropping `-`-prefixed tokens looks like it solves the
+* permissive-parse problem and does not: a flag that takes a VALUE leaves the
+* value behind, an ordinary word in the argument position that no filter can
+* tell from a real one. `--project` is the flag every one of these commands
+* documents, so the failure was reachable from the help page:
+*
+*   rebase cloud env unset -p acme            → removed the variable "acme"
+*   rebase cloud env set KEY -p acme          → stored the value "acme"
+*   rebase cloud domains add -p acme          → registered the domain "acme"
+*   rebase cloud webhooks delete -p acme 42   → deleted webhook "acme", not 42
+*   rebase cloud cancel -p acme               → cancelled deployment id "acme"
+*
+* The filter's other half is quieter. A flag nobody declared *is* dropped by
+* it — but only from the operands, never from the run: nothing rejects it, so
+* the command proceeds with the argument missing or defaulted. `db backup
+* --dry-run` listed backups, `domains remove --dry-run` detached the domain,
+* and `env set KEY=v --secrett` stored the value as an ordinary variable that
+* `env reveal` will hand back. The one place an undeclared flag became the
+* argument outright is `projects info|delete`, which resolved its id through
+* `positionals()` instead — that skips only LEADING `-` tokens, so `projects
+* delete --force` looked up a project named "--force".
+*
+* So: parse the whole line strictly, through the same `parseCommandArgs` the
+* non-cloud commands use — `arg` then consumes each declared flag *with its
+* value* wherever it appears, and rejects the undeclared, leaving `_` holding
+* the command words followed by the real arguments. `commandWords` counts from
+* `cloud` itself (`cloud env set` ⇒ 3), and is applied to the parsed
+* positionals, so a flag written before the group shifts nothing.
+*
+* Two things this adds over calling `parseCommandArgs` directly, and the reason
+* it is worth a wrapper:
+*
+*  - `GLOBAL_CLOUD_FLAGS` is merged in. `--json`, `--yes` and `--project` may
+*    appear anywhere on a cloud line including before the group, so a strict
+*    parse that did not declare them would reject the CLI's own documented
+*    usage. (`parseCommandArgs` adds `--debug`/`--help` on top of that.)
+*  - A parse error is reported through `fail`, not thrown. A throw reaches
+*    `bin/rebase.js`, which prints `✗ …` to stderr — which is right for every
+*    other command and wrong here: `rebase cloud` is in JSON mode whenever
+*    stdout is not a TTY, i.e. always for the agents this family is built for,
+*    and it promises them exactly one JSON value. `fail` keeps that promise,
+*    with the same `usage` code the other refusals in this family use.
+*/
+function parseCloudArgs(opts) {
+	const spec = {
+		...GLOBAL_CLOUD_FLAGS,
+		...opts.spec
+	};
+	try {
+		const parsed = parseCommandArgs({
+			...opts,
+			spec
+		});
+		return {
+			flags: parsed.flags,
+			positionals: parsed.positionals
+		};
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err), void 0, "usage");
+	}
+}
+/**
+* Refuse an action word its group does not dispatch. Returns for `undefined`,
+* which is every group's default action.
+*
+* The groups that switch on their action already do this in a `default:` case.
+* The groups written as a chain of `if (action === "x") return …` did not: a
+* word that matched nothing fell out of the chain into the *default* action, so
+* `rebase cloud storage creat` listed the buckets and exited 0, and
+* `rebase cloud billing usage` printed the account. Reporting a typo as a
+* successful run of a different command is the failure mode this family exists
+* to not have — an agent branching on the exit code learns nothing, and a person
+* reads the output of a command they did not ask for.
+*
+* One spelling, so the code is `unknown_command` everywhere rather than the
+* default `"error"` half of them used, and the hint always names the group's own
+* `--help` rather than the index page.
+*/
+function requireKnownAction(group, action, known) {
+	if (action === void 0 || known.includes(action)) return;
+	fail(`Unknown ${group} command: ${action}`, `Run \`rebase cloud ${group} --help\`. Actions: ${known.join(", ")}.`, "unknown_command");
+}
+/**
+* `--timeout <seconds>` as milliseconds, or `fallbackMs` when it was not given.
+*
+* One function rather than one per command, because two commands take this flag
+* and a second copy is where the two would come to disagree about what
+* `--timeout 0` means.
+*
+* A value this cannot read is a refusal, not a fall back to the default. The
+* whole reason a caller passes a timeout is that it has a deadline of its own;
+* quietly substituting a different one is how a fifteen-minute wait turns up
+* inside a five-minute CI step, having been asked for `--timeout 30s`.
+*/
+function resolveTimeoutMs(value, opts) {
+	if (value === void 0) return opts.fallbackMs;
+	const seconds = Number(value);
+	if (!Number.isFinite(seconds) || seconds <= 0) fail(`--timeout takes a number of seconds (got "${value}").`, `Run \`rebase ${opts.command} --help\`.`, "usage");
+	return seconds * 1e3;
+}
+/**
+* Announce an outcome — "Logged in as …", "Deleted project …".
+*
+* On **stderr**, in both modes. It reads like a result and is not one: the
+* result is the JSON value (or the table) on stdout, and every JSON payload in
+* this family already carries `success: true`. Leaving this on stdout meant a
+* successful `rebase cloud link | jq` was handed a green tick followed by an
+* object — one stream, two syntaxes, and only the second parseable.
+*
+* It stays visible in JSON mode, unlike `note`: an agent that got a `success`
+* line on a command it expected to refuse has learned something.
+*/
+function success(message) {
+	if (JSON_MODE) {
+		process.stderr.write(`${stripAnsi(message)}\n`);
+		return;
+	}
+	console.error("");
+	console.error(chalk.bold.green(`  ✓ ${message}`));
+	console.error("");
+}
+/**
+* Narrate progress, or point at the next step — "Signing in to …", "Redeploy
+* for the tenant to pick this up".
+*
+* stderr, and **suppressed entirely in JSON mode**. This is the one helper that
+* a mode may silence, and the distinction from `warn` is worth keeping sharp:
+*
+*   - A warning is a *condition*. It is as true when piped as when watched, so
+*     silencing it hides something the caller would want to know. `warn` never
+*     silences.
+*   - A note is *hand-holding*. "Next: run `rebase generate-sdk`" tells a person
+*     what to type; the agent reading the JSON already has the same information
+*     structurally, or does not need it. Printing it anyway is transcript noise.
+*
+* When in doubt it is a warning. The cost of a needless warning is a line; the
+* cost of a swallowed one is the deploy that ejected a project off the managed
+* runtime and said so only to a terminal nobody was looking at.
+*/
+function note(message, indent = "  ") {
+	if (JSON_MODE) return;
+	console.error(`${indent}${message}`);
+}
+/** A blank spacer line on the narration stream. No-op in JSON mode. */
+function noteBlank() {
+	if (JSON_MODE) return;
+	console.error("");
+}
+/** Colorize a deployment / resource status token. */
+function colorStatus(status) {
+	switch (status) {
+		case "active":
+		case "success":
+		case "connected": return chalk.green(status);
+		case "deploying":
+		case "provisioning":
+		case "pending_billing":
+		case "untested": return chalk.yellow(status ?? "");
+		case "failed": return chalk.red(status);
+		case "stopped": return chalk.gray(status);
+		default: return chalk.gray(status ?? "unknown");
+	}
+}
+/**
+* Render a two-column key/value block with aligned keys. Empty rows are skipped
+* — including `null`, which the API sends for an unset column and which used to
+* print the literal string "null" (e.g. `Custom domain: null`).
+*/
+function keyValues(rows) {
+	const width = Math.max(...rows.map(([k]) => k.length));
+	for (const [k, v] of rows) {
+		if (v === void 0 || v === null || v === "") continue;
+		console.log(`  ${chalk.gray(`${k}:`.padEnd(width + 1))} ${v}`);
+	}
+}
+/**
+* Surface an SDK/HTTP error consistently. The SDK throws RebaseApiError with
+* a `.status` and `.message`; anything else falls back to its string form.
+*
+* The message is summarised rather than printed — see `summarizeError`. What
+* arrives here is routinely a whole Kubernetes `Status` object with the request
+* headers appended, and the one sentence worth reading is inside it. The
+* untouched body is still available, behind `--debug`, on stderr where it
+* cannot corrupt the JSON value on stdout.
+*/
+function reportError(e, context) {
+	const err = e;
+	const summary = summarizeError(e, context);
+	if (wantsRawError()) process.stderr.write(`\n${summary.raw}\n\n`);
+	if (JSON_MODE) {
+		printJson({ error: {
+			message: stripAnsi(summary.message),
+			code: summary.code,
+			status: err?.status ?? null,
+			hint: summary.hint ? stripAnsi(summary.hint) : void 0,
+			platform: summary.platform,
+			context
+		} });
+		process.exit(1);
+	}
+	fail(summary.message, summary.hint, summary.code);
+}
+/**
+* Open a URL in the user's default browser (best effort). Always announces the
+* URL first so it stays usable over SSH or when no browser is available.
+*
+* The announcement is narration, not the result — it goes to stderr, and in
+* JSON mode it is silent. Every caller `emit`s the same URL in its payload, so
+* a machine reader gets it from the one place it is guaranteed to be parseable
+* rather than from a line that happens to end in a URL.
+*/
+function openUrl(target, label = "Opening") {
+	noteBlank();
+	note(`${label} ${chalk.cyan(target)}`);
+	noteBlank();
+	const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+	try {
+		const child = spawn(opener, [target], {
+			stdio: "ignore",
+			detached: true,
+			shell: process.platform === "win32"
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+/**
+* Read the control plane's rows as a subcommand's row shape.
+*
+* `client.data.collection(...)` is typed against the *generated* schema of the
+* project the SDK is pointed at, and the control-plane collections this CLI
+* reads are not in one — so every row arrives as an open
+* `Record<string, unknown>`. A declared `interface` gets no implicit index
+* signature, so it does not overlap that, and a direct `as` is refused: which
+* is how ten call sites came to write `as unknown as XRow[]`, an assertion
+* about a wire payload with nothing checking it in either direction.
+*
+* There is exactly one invariant to check and this checks it. Everything else
+* the shapes declare is optional and already read as such, so there is nothing
+* further to verify — but a row with no usable `id` is not a row any of these
+* commands can act on, and passing it through was how a listing came to print
+* `[undefined]` and a lookup came to compare against the string `"undefined"`.
+*/
+function cloudRows(rows) {
+	return (rows ?? []).filter((row) => typeof row?.id === "string" || typeof row?.id === "number");
+}
+/** {@link cloudRows} for an endpoint that returns a single row. */
+function cloudRow(row) {
+	return cloudRows(row ? [row] : [])[0];
+}
+/**
+* {@link cloudRows} for a write that must have produced a row.
+*
+* `create()` returning something with no usable `id` means the control plane
+* accepted the write and then described it in a way this CLI cannot act on.
+* The callers all go straight on to use that id — `setContextOrg(url,
+* String(created.id))` — so asserting the shape, which is what stood here,
+* turned a control-plane fault into an organization whose active id is the
+* seven-letter string `"undefined"`, stored in the user's config file.
+*/
+function requireCloudRow(row, what) {
+	const parsed = cloudRow(row);
+	if (!parsed) throw new Error(`The control plane accepted the ${what} but returned no id for it.`);
+	return parsed;
+}
+//#endregion
+export { projectHost as A, requireProject as B, lookupProjectId as C, parseCloudArgs as D, openUrl as E, reportError as F, resolveProjectRef as G, requireSessionClient as H, requireClient as I, setCurrentContext as J, resolveTimeoutMs as K, requireCloudRow as L, readLink as M, refuseDirectLink as N, printGroupHelp as O, removeLink as P, wantsRawError as Q, requireInteractive as R, keyValues as S, noteBlank as T, resolveCloudTarget as U, requireProjectRef as V, resolveCloudUrl as W, warn as X, success as Y, writeLink as Z, freshAccessToken as _, cloudRow as a, isJsonMode as b, confirmDestructive as c, emit as d, emitHelp as f, fetchTenantBaseDomain as g, fetchDeployTargets as h, billingAccountIdOf as i, projectLinkPath as j, printJson as k, createCloudClient as l, fail as m, GLOBAL_HELP_FLAGS as n, cloudRows as o, envToken as p, setContextOrg as q, TOKEN_ENV as r, colorStatus as s, GLOBAL_CLOUD_FLAGS as t, displayProjectRef as u, getContextOrg as v, note as w, isKnownControlPlane as x, initOutputMode as y, requireKnownAction as z };
+
+//# sourceMappingURL=context-BqhRydBg.js.map