@rebasepro/cli 0.9.1-canary.f2f61da → 0.9.1-canary.faee831

package/dist/index.es.js

@@ -3287,13 +3287,18 @@ function fmtDate(value) {
 */
 var POLL_INTERVAL_MS = 1500;
 var POLL_TIMEOUT_MS = 900 * 1e3;
+var MAX_SOURCE_UPLOAD_BYTES = 100 * 1024 * 1024;
 function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
 }
-function run(cmd, cmdArgs, cwd) {
+function run(cmd, cmdArgs, cwd, env) {
 	return new Promise((resolve, reject) => {
 		const child = spawn(cmd, cmdArgs, {
 			cwd,
+			env: env ? {
+				...process.env,
+				...env
+			} : void 0,
 			stdio: [
 				"ignore",
 				"ignore",
@@ -3323,7 +3328,7 @@ async function createSourceTarball(sourceDir) {
 	for (const ignore of [".gitignore", ".rebaseignore"]) if (fs.existsSync(path.join(dir, ignore))) tarArgs.push(`--exclude-from=${ignore}`);
 	tarArgs.push(".");
 	try {
-		await run("tar", tarArgs, dir);
+		await run("tar", tarArgs, dir, { COPYFILE_DISABLE: "1" });
 	} catch (e) {
 		fail(`Failed to package source: ${e instanceof Error ? e.message : String(e)}`);
 	}
@@ -3333,6 +3338,7 @@ async function createSourceTarball(sourceDir) {
 async function uploadSource(url, token, projectId, tarPath) {
 	const bytes = fs.readFileSync(tarPath);
 	const sizeMb = (bytes.length / 1024 / 1024).toFixed(1);
+	if (bytes.length > MAX_SOURCE_UPLOAD_BYTES) fail(`Source context is ${sizeMb} MB — the upload cap is ${Math.round(MAX_SOURCE_UPLOAD_BYTES / 1024 / 1024)} MB.`, "Trim the build context: exclude sourcemaps (*.map), build output and large assets via .rebaseignore or .gitignore.");
 	console.log(chalk.gray(`  Uploading source (${sizeMb} MB)...`));
 	const res = await fetch(`${url}/api/functions/deploy/upload?projectId=${encodeURIComponent(projectId)}`, {
 		method: "POST",
@@ -4865,7 +4871,7 @@ function deploymentDurationMs(dep) {
 	const ms = b - a;
 	return ms >= 0 ? ms : null;
 }
-function formatDuration(ms) {
+function formatDuration$1(ms) {
 	const totalSec = Math.max(0, Math.round(ms / 1e3));
 	if (totalSec < 60) return `${totalSec}s`;
 	const m = Math.floor(totalSec / 60);
@@ -4938,7 +4944,7 @@ async function deploymentsListCommand(rawArgs) {
 				return;
 			}
 			for (const v of views) {
-				const dur = v.durationMs !== null ? formatDuration(v.durationMs) : chalk.gray("running");
+				const dur = v.durationMs !== null ? formatDuration$1(v.durationMs) : chalk.gray("running");
 				const trig = v.trigger.source;
 				const roll = v.rollbackable ? chalk.green(" ↺ rollbackable") : "";
 				console.log(`  ${chalk.gray(`[${v.id}]`)} ${colorStatus(v.status)}  ${chalk.gray(String(v.createdAt ?? "—"))}  ${dur}  ${chalk.gray(trig)}${roll}`);
@@ -5109,6 +5115,737 @@ async function powerCommand(action, rawArgs) {
 	}
 }
 //#endregion
+//#region src/commands/cloud/debug.ts
+/**
+* `rebase cloud debug <subcommand>` — one entry point for "why is my deployed
+* app not behaving".
+*
+* ## Why this exists
+*
+* The useful signals for a deployed project live in four different places — the
+* control plane, the workload's pods, the tenant database, and the public URL —
+* and each is normally reached with a different tool and a different set of
+* flags. Getting to a log should not be a research task. This started life as a
+* hand-rolled `prod-debug.sh` for a single project, with the namespace and the
+* URL hardcoded at the top; it earned its place twice in one week, so it is
+* generalised here to any project the CLI can already resolve.
+*
+* ## Read-only by default
+*
+* Every subcommand here only reads. The two things the original script could do
+* that mutate are deliberately NOT reproduced as-is:
+*
+*   - restarting the workload lives at `rebase cloud restart`, which already
+*     gates downtime behind `--yes`; duplicating it here would give the same
+*     destructive act a second, ungated spelling.
+*   - `debug db` prints the port-forward recipe and the connection's *shape*.
+*     It opens no session and prints no password — `rebase cloud db info
+*     --reveal` is the explicit, auditable way to get one.
+*
+* ## The probes are the point
+*
+* `debug health` is the highest-value piece and the reason the script existed.
+* A bare status code is not a diagnosis: a 404 from a functions route means
+* something completely different from a 404 at the root, and a 200 on an
+* unauthenticated read is a finding rather than a success. So every probe ships
+* with the interpretation of what it got, not just the number — see
+* {@link PROBES}.
+*/
+/** A response never arrived: DNS, TLS, ingress, or the pod. */
+var NO_RESPONSE = {
+	verdict: "fail",
+	meaning: "nothing answered — the hostname does not resolve, the ingress has no route, or no pod is running"
+};
+function serverError(what) {
+	return {
+		verdict: "fail",
+		meaning: `the server is running but ${what}`
+	};
+}
+/**
+* The probe set, in the order a failure cascades: if `health` is down, nothing
+* below it is meaningful, so it is checked first and reported first.
+*/
+var PROBES = [
+	{
+		id: "health",
+		label: "health",
+		method: "GET",
+		path: () => "/health",
+		healthy: "200 — the backend is up",
+		interpret: (status) => {
+			if (status === null) return NO_RESPONSE;
+			if (status === 200) return {
+				verdict: "ok",
+				meaning: "the backend is up and serving"
+			};
+			if (status === 404) return {
+				verdict: "fail",
+				meaning: "something answered but it is not a Rebase backend — the ingress is routing this host elsewhere"
+			};
+			if (status >= 500) return serverError("its health endpoint is failing");
+			return {
+				verdict: "unknown",
+				meaning: "unexpected for a health endpoint"
+			};
+		}
+	},
+	{
+		id: "spa",
+		label: "spa",
+		method: "GET",
+		path: () => "/",
+		healthy: "200 — the frontend is being served",
+		interpret: (status) => {
+			if (status === null) return NO_RESPONSE;
+			if (status === 200) return {
+				verdict: "ok",
+				meaning: "the frontend bundle is being served"
+			};
+			if (status === 404) return {
+				verdict: "warn",
+				meaning: "no frontend at the root — expected for a backend-only project, otherwise the SPA assets were not bundled into the image"
+			};
+			if (status >= 500) return serverError("the root route throws");
+			return {
+				verdict: "unknown",
+				meaning: "unexpected at the site root"
+			};
+		}
+	},
+	{
+		id: "auth",
+		label: "auth",
+		method: "POST",
+		path: () => "/api/auth/login",
+		body: {},
+		healthy: "400 — auth is mounted and rejects an empty body",
+		interpret: (status) => {
+			if (status === null) return NO_RESPONSE;
+			if (status === 400 || status === 422) return {
+				verdict: "ok",
+				meaning: "auth is mounted and rejected the empty body, as it should"
+			};
+			if (status === 401 || status === 403) return {
+				verdict: "ok",
+				meaning: "auth is mounted and refused the credentials"
+			};
+			if (status === 404) return {
+				verdict: "fail",
+				meaning: "the auth routes are NOT mounted — this project cannot sign anyone in"
+			};
+			if (status === 200) return {
+				verdict: "fail",
+				meaning: "an EMPTY login body was accepted — a login with no credentials must never succeed"
+			};
+			if (status >= 500) return serverError("the login route throws — often a missing or unmigrated auth table");
+			return {
+				verdict: "unknown",
+				meaning: "unexpected for a login route"
+			};
+		}
+	},
+	{
+		id: "unauthRead",
+		label: "unauth read",
+		method: "GET",
+		path: (t) => `/api/data/${encodeURIComponent(t.collection)}`,
+		healthy: "401 — reads require authentication",
+		interpret: (status) => {
+			if (status === null) return NO_RESPONSE;
+			if (status === 401 || status === 403) return {
+				verdict: "ok",
+				meaning: "unauthenticated reads are refused — row-level security is enforced"
+			};
+			if (status === 200) return {
+				verdict: "warn",
+				meaning: "this collection is readable with NO authentication — correct only if it is deliberately public"
+			};
+			if (status === 404) return {
+				verdict: "warn",
+				meaning: "no such collection on this deployment — check the name, or pass --collection"
+			};
+			if (status >= 500) return serverError("the read reached the database and failed — most often an RLS policy naming a column or table that is not there");
+			return {
+				verdict: "unknown",
+				meaning: "unexpected for a data read"
+			};
+		}
+	},
+	{
+		id: "functions",
+		label: "functions",
+		method: "GET",
+		/**
+		* The router's own listing endpoint, NOT a function's path.
+		*
+		* This matters, and it is the one place the original script got a wrong
+		* answer. A function is a Hono sub-app mounted at `/<name>`, and it
+		* usually defines only sub-routes (`/get`, `/list`) — so
+		* `/api/functions/<name>` 404s **even when everything is mounted and
+		* healthy**. Probing there cannot separate "the router is missing" from
+		* "that function defines no root route", and reporting the first is how
+		* you send someone to debug a deployment that was fine.
+		*
+		* `GET /api/functions` is unambiguous: the router registers a listing
+		* route at its own root (see `createFunctionRoutes`), so a 200 proves
+		* the mount *and* names every function that loaded.
+		*/
+		path: () => "/api/functions",
+		healthy: "200 — the functions router is mounted and lists its functions",
+		interpret: (status) => {
+			if (status === null) return NO_RESPONSE;
+			if (status === 200) return {
+				verdict: "ok",
+				meaning: "the functions router is mounted"
+			};
+			if (status === 401 || status === 403) return {
+				verdict: "ok",
+				meaning: "the functions router is mounted (its listing requires auth)"
+			};
+			if (status === 404) return {
+				verdict: "fail",
+				meaning: "the functions router did not mount — no functions directory was found at build time, or it held no functions, so every function on this project is unreachable"
+			};
+			if (status >= 500) return serverError("the functions router throws");
+			return {
+				verdict: "unknown",
+				meaning: "unexpected for the functions listing"
+			};
+		},
+		needsBody: true,
+		refine: (body, t) => {
+			const names = functionNames(body);
+			if (!names) return null;
+			if (t.fn && !names.includes(t.fn)) return {
+				verdict: "fail",
+				meaning: `the router is mounted but no function is named "${t.fn}" — it loaded ${names.length}: ${names.join(", ")}`
+			};
+			const found = t.fn ? `, including ${t.fn}` : "";
+			return {
+				verdict: "ok",
+				meaning: `the functions router is mounted and loaded ${names.length} function${names.length === 1 ? "" : "s"}${found}`
+			};
+		}
+	}
+];
+/** The function names out of a listing body, or null when it is not one. */
+function functionNames(body) {
+	const list = body?.functions;
+	if (!Array.isArray(list)) return null;
+	const names = list.map((f) => f?.name).filter((n) => typeof n === "string");
+	return names.length === list.length ? names : null;
+}
+/** Milliseconds before a probe is treated as unanswered. */
+var PROBE_TIMEOUT_MS = 1e4;
+/**
+* Ceiling on a probe body we will parse. The only body read is the function
+* listing; anything larger is a page we have no use for, and a debug command
+* must not be the thing that runs a machine out of memory.
+*/
+var MAX_PROBE_BODY_BYTES = 256 * 1024;
+/**
+* Run one probe. A transport failure is a `null` status, never a thrown error:
+* "nothing answered" is a diagnosis in its own right and the other probes still
+* need to run.
+*/
+async function runProbe(origin, spec, targets) {
+	const url = `${origin}${spec.path(targets)}`;
+	const started = Date.now();
+	let status = null;
+	let body;
+	try {
+		const res = await fetch(url, {
+			method: spec.method,
+			headers: spec.body ? { "Content-Type": "application/json" } : void 0,
+			body: spec.body ? JSON.stringify(spec.body) : void 0,
+			redirect: "manual",
+			signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
+		});
+		status = res.status;
+		if (spec.needsBody && res.ok) {
+			const text = await res.text();
+			if (text.length <= MAX_PROBE_BODY_BYTES) try {
+				body = JSON.parse(text);
+			} catch {}
+		}
+	} catch {
+		status = null;
+	}
+	const statusReading = spec.interpret(status);
+	const reading = status !== null && spec.refine?.(body, targets) || statusReading;
+	return {
+		statusOk: statusReading.verdict === "ok",
+		id: spec.id,
+		label: spec.label,
+		method: spec.method,
+		url,
+		status,
+		ms: Date.now() - started,
+		verdict: reading.verdict,
+		meaning: reading.meaning,
+		healthy: spec.healthy
+	};
+}
+/** The worst verdict across probes — what the command's exit code keys off. */
+function overallVerdict(results) {
+	if (results.some((r) => r.verdict === "fail")) return "fail";
+	if (results.some((r) => r.verdict === "unknown")) return "unknown";
+	if (results.some((r) => r.verdict === "warn")) return "warn";
+	return "ok";
+}
+function verdictMark(v) {
+	switch (v) {
+		case "ok": return chalk.green("✓");
+		case "warn": return chalk.yellow("!");
+		case "fail": return chalk.red("✗");
+		default: return chalk.gray("?");
+	}
+}
+var LOG_PREFIX_RE = /^(?:(\d{4}-\d{2}-\d{2}T[\d:.]+Z?)\s+)?(?:\[([^\]]+)\]\s+)?([\s\S]*)$/;
+function parseLogLine(line) {
+	const m = LOG_PREFIX_RE.exec(line);
+	if (!m) return {
+		ts: null,
+		pod: null,
+		text: line
+	};
+	return {
+		ts: m[1] ?? null,
+		pod: m[2] ?? null,
+		text: m[3] ?? ""
+	};
+}
+/**
+* Lines an operator scanning for a fault wants to see.
+*
+* Matches the structured `severity` field first, then the shapes that show up
+* in unstructured output. `refus`/`denied` are in the list because a permission
+* failure often logs at info level and is exactly what one is hunting for.
+*/
+function isErrorLine(text) {
+	return /"(?:severity|level)":\s*"(?:ERROR|WARN(?:ING)?|error|warn)"|\bError:|\bERR!|refus|denied|EACCES|ECONNREFUSED/i.test(text);
+}
+/**
+* Pull an HTTP request record out of a log line, or null when it is not one.
+*
+* Only structured request lines are recognised. Guessing at prose would produce
+* a table with invented columns, which is worse than a short one.
+*/
+function parseRequestLine(text) {
+	const start = text.indexOf("{");
+	if (start === -1) return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(text.slice(start));
+	} catch {
+		return null;
+	}
+	if (parsed.message !== "request" && parsed.msg !== "request") return null;
+	const num = (v) => {
+		const n = typeof v === "string" ? Number(v) : typeof v === "number" ? v : NaN;
+		return Number.isFinite(n) ? n : null;
+	};
+	return {
+		status: num(parsed.status),
+		method: typeof parsed.method === "string" ? parsed.method : "",
+		path: typeof parsed.path === "string" ? parsed.path : "",
+		latencyMs: num(parsed.latencyMs ?? parsed.durationMs)
+	};
+}
+/**
+* Startup lines: what the server *decided* it was going to do. Which storage
+* backend it bound, which functions it loaded, whether auth tables were found.
+* This is the fastest way to tell a misconfiguration from a runtime fault.
+*/
+function isBootLine(text) {
+	return /storage|Loaded function|Mounted|Auth tables|Server running|listening|Refusing|migrat/i.test(text);
+}
+/** Render a number of seconds back as the compact duration a user would type. */
+function formatDuration(seconds) {
+	if (seconds % 86400 === 0 && seconds >= 86400) return `${seconds / 86400}d`;
+	if (seconds % 3600 === 0 && seconds >= 3600) return `${seconds / 3600}h`;
+	if (seconds % 60 === 0 && seconds >= 60) return `${seconds / 60}m`;
+	return `${seconds}s`;
+}
+/**
+* Parse a duration like `15m`, `2h`, `90s`, `1d` (or a bare number of seconds)
+* into seconds. Returns null when it is not a duration.
+*/
+function parseSince(input) {
+	if (!input) return null;
+	const m = /^(\d+(?:\.\d+)?)\s*([smhd])?$/i.exec(input.trim());
+	if (!m) return null;
+	const value = parseFloat(m[1]);
+	const unit = (m[2] || "s").toLowerCase();
+	return Math.round(value * (unit === "s" ? 1 : unit === "m" ? 60 : unit === "h" ? 3600 : 86400));
+}
+async function fetchRuntimeLogs(client, projectId, opts) {
+	const params = new URLSearchParams();
+	if (opts.sinceSeconds !== void 0) params.set("sinceSeconds", String(opts.sinceSeconds));
+	if (opts.tailLines !== void 0) params.set("tailLines", String(opts.tailLines));
+	if (opts.previous) params.set("previous", "true");
+	params.set("timestamps", "true");
+	const qs = params.toString();
+	return client.functions.invoke("runtime-logs", void 0, {
+		method: "GET",
+		path: `${projectId}${qs ? `?${qs}` : ""}`
+	});
+}
+/** Print the per-pod states runtime-logs reports, including its hints. */
+function printPodStates(res) {
+	if (res.state === "no_pods") {
+		console.log(chalk.yellow(`  ${res.message ?? "No pods are running for this project."}`));
+		console.log("");
+		return;
+	}
+	for (const p of res.pods ?? []) {
+		if (p.state === "ok") continue;
+		console.log(`  ${chalk.yellow(p.pod)} ${chalk.gray(`(${p.state})`)}`);
+		if (p.message) console.log(chalk.gray(`    ${p.message}`));
+		if (p.hint) console.log(chalk.cyan(`    → ${p.hint}`));
+	}
+	if (res.truncated) console.log(chalk.gray("  (output truncated — narrow the window with --since)"));
+}
+/** Resolve the public origin a project is served at. */
+async function resolveOrigin(rawArgs, client, url, projectId) {
+	const parsed = arg({ "--host": String }, {
+		argv: rawArgs.slice(3),
+		permissive: true
+	});
+	if (parsed["--host"]) {
+		const h = parsed["--host"].trim().replace(/\/+$/, "");
+		return /^https?:\/\//.test(h) ? h : `https://${h}`;
+	}
+	const [project, baseDomain] = await Promise.all([client.data.collection("projects").findById(projectId), fetchTenantBaseDomain(client, url)]);
+	if (!project) fail(`Project ${displayProjectRef(rawArgs)} not found.`);
+	const host = projectHost(project, baseDomain);
+	if (!host) fail("Could not determine the public URL for this project.", "It may never have been deployed. Pass --host <hostname> to probe an address directly.");
+	return `https://${host}`;
+}
+async function healthCommand(rawArgs) {
+	const parsed = arg({
+		"--collection": String,
+		"--function": String
+	}, {
+		argv: rawArgs.slice(3),
+		permissive: true
+	});
+	const targets = {
+		collection: parsed["--collection"] || "users",
+		fn: parsed["--function"]
+	};
+	const { client, url } = await requireClient(rawArgs);
+	const origin = await resolveOrigin(rawArgs, client, url, await requireProject(rawArgs, client));
+	const results = [];
+	for (const spec of PROBES) results.push(await runProbe(origin, spec, targets));
+	const overall = overallVerdict(results);
+	emit(() => {
+		console.log("");
+		console.log(chalk.bold(`  🩺 Health — ${displayProjectRef(rawArgs)}`) + chalk.gray(`  ${origin}`));
+		console.log("");
+		const width = Math.max(...results.map((r) => r.label.length));
+		for (const r of results) {
+			const code = r.status === null ? chalk.red("---") : String(r.status);
+			console.log(`  ${verdictMark(r.verdict)} ${chalk.bold(r.label.padEnd(width))}  ${code.padStart(3)}  ${chalk.gray(`${r.ms}ms`)}`);
+			console.log(`      ${chalk.gray(r.meaning)}`);
+		}
+		console.log("");
+		if (overall === "ok") console.log(chalk.green("  Everything reachable and wired as expected."));
+		else {
+			const bad = results.filter((r) => r.verdict === "fail" || r.verdict === "warn");
+			console.log(chalk.gray(`  ${bad.length} of ${results.length} check${bad.length === 1 ? "" : "s"} need attention.`));
+			const wrongStatus = bad.filter((r) => !r.statusOk);
+			if (wrongStatus.length > 0) {
+				console.log(chalk.gray("  A healthy deployment answers:"));
+				for (const r of wrongStatus) console.log(chalk.gray(`    ${r.label.padEnd(width)}  ${r.healthy}`));
+			}
+		}
+		console.log("");
+	}, {
+		origin,
+		overall,
+		probes: results
+	});
+	if (overall === "fail") process.exit(1);
+}
+async function logView(rawArgs, view) {
+	const parsed = arg({
+		"--since": String,
+		"--tail": Number,
+		"--previous": Boolean
+	}, {
+		argv: rawArgs.slice(3),
+		permissive: true
+	});
+	const sinceArg = parsed["--since"];
+	if (sinceArg !== void 0 && parseSince(sinceArg) === null) fail(`--since must be a duration like 15m, 2h or 90s; received "${sinceArg}".`);
+	const sinceSeconds = parseSince(sinceArg) ?? view.defaultSinceSeconds;
+	const { client } = await requireClient(rawArgs);
+	const projectId = await requireProject(rawArgs, client);
+	let res;
+	try {
+		res = await fetchRuntimeLogs(client, projectId, {
+			sinceSeconds,
+			tailLines: parsed["--tail"] ?? 500,
+			previous: Boolean(parsed["--previous"])
+		});
+	} catch (e) {
+		reportError(e, "Failed to fetch runtime logs");
+	}
+	const parsedLines = (res.logs ?? "").split("\n").filter((l) => l !== "").map(parseLogLine);
+	const kept = view.filter ? parsedLines.filter((l) => view.filter(l.text)) : parsedLines;
+	const shown = kept.slice(-view.limit);
+	emit(() => {
+		console.log("");
+		console.log(chalk.bold(`  ${view.title} — ${displayProjectRef(rawArgs)}`) + chalk.gray(`  last ${formatDuration(sinceSeconds)}`));
+		console.log("");
+		printPodStates(res);
+		if (shown.length === 0) {
+			console.log(chalk.gray("  (nothing matched in this window)"));
+			console.log("");
+			return;
+		}
+		for (const l of shown) console.log(`  ${l.pod ? chalk.gray(`[${l.pod}] `) : ""}${l.text}`);
+		console.log("");
+		if (kept.length > shown.length) {
+			console.log(chalk.gray(`  (showing the last ${shown.length} of ${kept.length} matching lines)`));
+			console.log("");
+		}
+	}, {
+		sinceSeconds,
+		state: res.state ?? null,
+		pods: res.pods ?? [],
+		truncated: Boolean(res.truncated),
+		matched: kept.length,
+		lines: shown
+	});
+}
+async function requestsCommand(rawArgs) {
+	const parsed = arg({
+		"--since": String,
+		"--tail": Number
+	}, {
+		argv: rawArgs.slice(3),
+		permissive: true
+	});
+	const sinceArg = parsed["--since"];
+	if (sinceArg !== void 0 && parseSince(sinceArg) === null) fail(`--since must be a duration like 15m, 2h or 90s; received "${sinceArg}".`);
+	const sinceSeconds = parseSince(sinceArg) ?? 900;
+	const { client } = await requireClient(rawArgs);
+	const projectId = await requireProject(rawArgs, client);
+	let res;
+	try {
+		res = await fetchRuntimeLogs(client, projectId, {
+			sinceSeconds,
+			tailLines: parsed["--tail"] ?? 1e3
+		});
+	} catch (e) {
+		reportError(e, "Failed to fetch runtime logs");
+	}
+	const shown = (res.logs ?? "").split("\n").filter((l) => l !== "").map((l) => parseRequestLine(parseLogLine(l).text)).filter((e) => e !== null).slice(-40);
+	emit(() => {
+		console.log("");
+		console.log(chalk.bold(`  🌐 Requests — ${displayProjectRef(rawArgs)}`) + chalk.gray(`  last ${formatDuration(sinceSeconds)}`));
+		console.log("");
+		printPodStates(res);
+		if (shown.length === 0) {
+			console.log(chalk.gray("  No structured request lines in this window."));
+			console.log(chalk.gray("  (this view needs the server's request logging; try `debug logs`)"));
+			console.log("");
+			return;
+		}
+		for (const e of shown) {
+			const status = e.status ?? 0;
+			const color = status >= 500 ? chalk.red : status >= 400 ? chalk.yellow : chalk.green;
+			console.log(`  ${color(String(e.status ?? "---").padStart(3))}  ${e.method.padEnd(6)} ${e.path.slice(0, 70).padEnd(70)} ${chalk.gray(e.latencyMs === null ? "" : `${e.latencyMs}ms`)}`);
+		}
+		console.log("");
+	}, {
+		sinceSeconds,
+		requests: shown
+	});
+}
+async function podCommand(rawArgs) {
+	const { client } = await requireClient(rawArgs);
+	const projectId = await requireProject(rawArgs, client);
+	let m;
+	try {
+		m = await client.functions.invoke("metrics", void 0, {
+			method: "GET",
+			path: projectId
+		});
+	} catch (e) {
+		reportError(e, "Failed to read workload placement");
+	}
+	const p = m.placement ?? {};
+	const replicas = p.replicas ?? {};
+	emit(() => {
+		console.log("");
+		console.log(chalk.bold(`  ☸  Workload — ${displayProjectRef(rawArgs)}`));
+		console.log("");
+		keyValues([
+			["Status", m.status ? colorStatus(m.status === "running" ? "active" : m.status) : void 0],
+			["Replicas", replicas.desired === void 0 ? void 0 : `${replicas.available ?? 0} / ${replicas.desired} available`],
+			["Namespace", p.namespace],
+			["Cluster", p.cluster],
+			["Region", [p.provider, p.region].filter(Boolean).join(" · ") || void 0],
+			["Host", p.host],
+			["Image", p.image],
+			["CPU", m.cpu ?? void 0],
+			["Memory", m.memory ?? void 0]
+		]);
+		console.log("");
+		if ((replicas.available ?? 0) === 0 && (replicas.desired ?? 0) > 0) {
+			console.log(chalk.yellow("  No replica is available — the pod is not passing its readiness check."));
+			console.log(chalk.gray("  See why with:  ") + chalk.bold("rebase cloud debug logs --previous"));
+			console.log("");
+		}
+	}, {
+		status: m.status ?? null,
+		placement: p
+	});
+}
+async function dbDebugCommand(rawArgs) {
+	const { client } = await requireClient(rawArgs);
+	const projectId = await requireProject(rawArgs, client);
+	let info;
+	try {
+		info = await client.functions.invoke("db-info", void 0, {
+			method: "GET",
+			path: projectId
+		});
+	} catch (e) {
+		reportError(e, "Failed to read database connection info");
+	}
+	const pf = info.portForward;
+	const forwardCmd = pf ? `kubectl port-forward -n ${pf.namespace} svc/${pf.service} ${pf.localPort}:${pf.remotePort}` : null;
+	const psqlCmd = pf && info.username && info.database ? `psql -h 127.0.0.1 -p ${pf.localPort} -U ${info.username} -d ${info.database}` : null;
+	emit(() => {
+		console.log("");
+		console.log(chalk.bold(`  🐘 Database — ${displayProjectRef(rawArgs)}`));
+		console.log("");
+		if (info.unavailableReason) {
+			console.log(chalk.yellow(`  ${info.unavailableReason}`));
+			console.log("");
+			return;
+		}
+		keyValues([
+			["Type", info.type],
+			["Host", info.host],
+			["Port", info.port],
+			["Database", info.database],
+			["Username", info.username],
+			["Password", info.passwordAvailable ? chalk.gray("stored — not shown here") : chalk.yellow("none stored")]
+		]);
+		console.log("");
+		if (forwardCmd) {
+			console.log(chalk.gray("  A managed database is only reachable inside its cluster. To connect:"));
+			console.log("");
+			console.log(`    ${forwardCmd}`);
+			if (psqlCmd) console.log(`    ${psqlCmd}`);
+			console.log("");
+			if (info.passwordAvailable) {
+				console.log(chalk.gray("  Get the password with:  ") + chalk.bold("rebase cloud db info --reveal"));
+				console.log("");
+			}
+		}
+	}, {
+		type: info.type ?? null,
+		host: info.host ?? null,
+		port: info.port ?? null,
+		database: info.database ?? null,
+		username: info.username ?? null,
+		passwordAvailable: Boolean(info.passwordAvailable),
+		portForwardCommand: forwardCmd,
+		psqlCommand: psqlCmd
+	});
+}
+async function debugCommand(action, rawArgs) {
+	switch (action) {
+		case void 0:
+		case "health":
+			await healthCommand(rawArgs);
+			break;
+		case "logs":
+			await logView(rawArgs, {
+				defaultSinceSeconds: 900,
+				limit: 200,
+				title: "📄 Logs"
+			});
+			break;
+		case "errors":
+			await logView(rawArgs, {
+				filter: isErrorLine,
+				defaultSinceSeconds: 3600,
+				limit: 40,
+				title: "🔥 Errors"
+			});
+			break;
+		case "boot":
+			await logView(rawArgs, {
+				filter: isBootLine,
+				defaultSinceSeconds: 168 * 3600,
+				limit: 25,
+				title: "🚀 Boot"
+			});
+			break;
+		case "requests":
+			await requestsCommand(rawArgs);
+			break;
+		case "pod":
+		case "workload":
+			await podCommand(rawArgs);
+			break;
+		case "db":
+			await dbDebugCommand(rawArgs);
+			break;
+		case "help":
+		case "--help":
+			printDebugHelp();
+			break;
+		default:
+			if (isJsonMode()) fail(`Unknown debug command: ${action}`, void 0, "unknown_command");
+			console.error(chalk.red(`Unknown debug command: ${action}`));
+			console.log("");
+			printDebugHelp();
+			process.exit(1);
+	}
+}
+function printDebugHelp() {
+	console.log(`
+${chalk.bold("rebase cloud debug")} — Find out why a deployed project is misbehaving
+
+${chalk.green.bold("Usage")}
+  rebase cloud debug ${chalk.blue("<subcommand>")} [options]
+
+${chalk.green.bold("End-to-end")}
+  ${chalk.blue.bold("health")}                  Probe the live URL and explain every status code ${chalk.gray("(default)")}
+
+${chalk.green.bold("Runtime")}
+  ${chalk.blue.bold("logs")} ${chalk.gray("[--since 15m]")}      Recent application logs
+  ${chalk.blue.bold("errors")} ${chalk.gray("[--since 1h]")}     Error and warning lines only
+  ${chalk.blue.bold("requests")} ${chalk.gray("[--since 15m]")}  HTTP requests the server logged ${chalk.gray("(status, path, latency)")}
+  ${chalk.blue.bold("boot")}                    What the server decided at startup ${chalk.gray("(storage, functions, auth)")}
+  ${chalk.blue.bold("pod")}                     Replicas, image, namespace, cluster placement
+
+${chalk.green.bold("Data")}
+  ${chalk.blue.bold("db")}                      Connection shape + the port-forward recipe ${chalk.gray("(no password)")}
+
+${chalk.green.bold("Options")}
+  ${chalk.blue("--since <dur>")}           Lookback window: ${chalk.gray("90s, 15m, 2h, 1d")}
+  ${chalk.blue("--tail <n>")}              Lines to read per pod ${chalk.gray("(default 500)")}
+  ${chalk.blue("--previous")}              Read the CRASHED container instance ${chalk.gray("(where the reason lives)")}
+  ${chalk.blue("--host <hostname>")}       Probe this address instead of the project's own
+  ${chalk.blue("--collection <name>")}     Collection for the unauth-read probe ${chalk.gray("(default: users)")}
+  ${chalk.blue("--function <name>")}       Also assert this function loaded ${chalk.gray("(checked against the listing)")}
+  ${chalk.blue("--project, -p <slug>")}    Operate on a project without linking
+
+${chalk.gray("Everything here is read-only. `health` exits non-zero when a check fails,")}
+${chalk.gray("so it works in a deploy script. To restart a workload, use `rebase cloud restart`.")}
+`);
+}
+//#endregion
 //#region src/commands/cloud/resources.ts
 /**
 * `rebase cloud` resource subcommands: status, metrics, webhooks, storage,
@@ -5221,7 +5958,10 @@ async function webhooksCommand(subcommand, rawArgs) {
 		reportError(e, "Webhook operation failed");
 	}
 }
-async function storageCommand(rawArgs) {
+async function storageCommand(action, rawArgs) {
+	if (action === "create") return storageCreateCommand(rawArgs);
+	if (action === "attach") return storageAttachCommand(rawArgs);
+	if (action === "help") return printStorageHelp();
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	try {
@@ -5246,6 +5986,107 @@ async function storageCommand(rawArgs) {
 		reportError(e, "Failed to list storage");
 	}
 }
+function printStorageHelp() {
+	console.log("");
+	console.log(chalk.bold("  rebase cloud storage"));
+	console.log("");
+	console.log("  " + chalk.blue.bold("storage") + "                   List this project's storage");
+	console.log("  " + chalk.blue.bold("storage create") + "            Provision platform-managed storage");
+	console.log("  " + chalk.blue.bold("storage attach") + "            Attach your own S3-compatible bucket");
+	console.log("");
+	console.log(chalk.gray("  attach options:"));
+	console.log(chalk.gray("    --bucket <name>          Bucket name (required)"));
+	console.log(chalk.gray("    --access-key-id <id>     Access key ID (required)"));
+	console.log(chalk.gray("    --secret-access-key <s>  Secret access key (required)"));
+	console.log(chalk.gray("    --endpoint <url>         S3 endpoint; omit for AWS"));
+	console.log(chalk.gray("    --region <region>        Region"));
+	console.log(chalk.gray("    --force-path-style       Required by MinIO and some gateways"));
+	console.log("");
+	console.log(chalk.gray("  Without either, a tenant falls back to the container filesystem and"));
+	console.log(chalk.gray("  loses uploaded files on its next restart."));
+	console.log("");
+}
+async function storageCreateCommand(rawArgs) {
+	const { client } = await requireClient(rawArgs);
+	const projectId = await requireProject(rawArgs, client);
+	try {
+		console.log("");
+		console.log(chalk.gray("  Provisioning managed storage — this creates a bucket and its credentials..."));
+		const res = await client.functions.invoke(`storage-provision/${encodeURIComponent(projectId)}`, void 0, { method: "POST" });
+		const info = res.data ?? res.data;
+		success(`Managed storage provisioned for ${displayProjectRef(rawArgs)}.`);
+		keyValues([
+			["Bucket", info.bucketName],
+			["Region", info.region],
+			["Endpoint", info.endpoint],
+			["Access key", info.accessKeyId]
+		]);
+		console.log("");
+		console.log(chalk.gray("  The secret key is stored encrypted and injected at deploy time; it is not displayed."));
+		console.log(chalk.gray("  Redeploy for the tenant to pick it up:  ") + chalk.bold("rebase cloud deploy"));
+		console.log("");
+	} catch (e) {
+		reportError(e, "Failed to provision managed storage");
+	}
+}
+async function storageAttachCommand(rawArgs) {
+	const parsed = arg({
+		"--bucket": String,
+		"--access-key-id": String,
+		"--secret-access-key": String,
+		"--endpoint": String,
+		"--region": String,
+		"--force-path-style": Boolean
+	}, {
+		argv: rawArgs.slice(3),
+		permissive: true
+	});
+	const bucket = parsed["--bucket"];
+	const accessKeyId = parsed["--access-key-id"];
+	const secretAccessKey = parsed["--secret-access-key"];
+	const missing = [
+		!bucket && "--bucket",
+		!accessKeyId && "--access-key-id",
+		!secretAccessKey && "--secret-access-key"
+	].filter(Boolean);
+	if (missing.length > 0) fail(`Missing ${missing.join(", ")}.`, "A bucket without credentials cannot be used, and would be stored as though it could. Run `rebase cloud storage --help` for the full list.");
+	const { client } = await requireClient(rawArgs);
+	const projectId = await requireProject(rawArgs, client);
+	try {
+		const existing = (await client.data.collection("storages").find({
+			where: { project: ["==", projectId] },
+			limit: 1
+		})).data[0];
+		const row = {
+			project: projectId,
+			type: "byos",
+			status: "active",
+			s3Bucket: bucket,
+			s3AccessKeyId: accessKeyId,
+			s3SecretAccessKey: secretAccessKey,
+			bucketName: bucket
+		};
+		if (parsed["--endpoint"]) row.s3Endpoint = parsed["--endpoint"];
+		if (parsed["--region"]) {
+			row.s3Region = parsed["--region"];
+			row.region = parsed["--region"];
+		}
+		if (parsed["--force-path-style"]) row.s3ForcePathStyle = true;
+		if (existing?.id) await client.data.collection("storages").update(String(existing.id), row);
+		else await client.data.collection("storages").create(row);
+		success(`Storage attached to ${displayProjectRef(rawArgs)}.`);
+		keyValues([
+			["Bucket", bucket],
+			["Endpoint", parsed["--endpoint"] ?? "AWS S3"],
+			["Region", parsed["--region"] ?? "(default)"]
+		]);
+		console.log("");
+		console.log(chalk.gray("  Redeploy for the tenant to pick it up:  ") + chalk.bold("rebase cloud deploy"));
+		console.log("");
+	} catch (e) {
+		reportError(e, "Failed to attach storage");
+	}
+}
 async function clustersCommand(rawArgs) {
 	const { client } = await requireClient(rawArgs);
 	try {
@@ -5437,6 +6278,9 @@ async function cloudCommand(subcommand, rawArgs) {
 		case "metrics":
 			await metricsCommand(rawArgs);
 			break;
+		case "debug":
+			await debugCommand(action, rawArgs);
+			break;
 		case "env":
 			await envCommand(action, rawArgs);
 			break;
@@ -5463,7 +6307,7 @@ async function cloudCommand(subcommand, rawArgs) {
 			await webhooksCommand(action, rawArgs);
 			break;
 		case "storage":
-			await storageCommand(rawArgs);
+			await storageCommand(action, rawArgs);
 			break;
 		case "clusters":
 			await clustersCommand(rawArgs);
@@ -5548,6 +6392,7 @@ ${chalk.green.bold("Deploy & observe")}
   ${chalk.blue.bold("start|stop|restart")} ${chalk.gray("[-y]")}  Power ops ${chalk.gray("(stop/restart need -y)")}
   ${chalk.blue.bold("status")}                  One-glance project status
   ${chalk.blue.bold("metrics")}                 Live CPU / memory / disk
+  ${chalk.blue.bold("debug")} ${chalk.gray("[health|logs|…]")}    Diagnose a misbehaving deployment ${chalk.gray("(read-only)")}
 
 ${chalk.green.bold("Config")}
   ${chalk.blue.bold("env list|set|unset|reveal|pull")}
@@ -5566,6 +6411,8 @@ ${chalk.green.bold("Databases")}
 ${chalk.green.bold("Other resources")}
   ${chalk.blue.bold("webhooks list|create|delete")}
   ${chalk.blue.bold("storage")}                 List storage buckets
+  ${chalk.blue.bold("storage create")}          Provision platform-managed storage
+  ${chalk.blue.bold("storage attach")}          Attach your own S3-compatible bucket
   ${chalk.blue.bold("clusters")}                List compute clusters
   ${chalk.blue.bold("billing setup")}           Attach a card to the org ${chalk.gray("(one-time, opens browser)")}
   ${chalk.blue.bold("billing")}                 Show billing account + card on file