@rebasepro/cli 0.13.0 → 0.13.1-canary.g18cfeb7

package/dist/index.es.js

@@ -12,8 +12,9 @@ import crypto from "crypto";
 import { execSync, spawn, spawnSync } from "child_process";
 import os from "os";
 import { createRebaseClient } from "@rebasepro/client";
+import dotenv from "dotenv";
 import { createRequire } from "module";
-import { BUNDLE_FORMAT_VERSION, RUNTIME_CONTRACT_VERSION, computeSchemaVersion, deserializeCollections, findStorageSuffixCollision, normalizeStorageSources, storageEnvSuffix } from "@rebasepro/types";
+import { BUNDLE_FORMAT_VERSION, DEFAULT_DATA_SOURCE_KEY, RUNTIME_CONTRACT_VERSION, computeSchemaVersion, deserializeCollections, findStorageSuffixCollision, getDataSourceCapabilities, normalizeStorageSources, storageEnvSuffix } from "@rebasepro/types";
 import { generateSDK } from "@rebasepro/codegen";
 //#region src/utils/package-manager.ts
 /**
@@ -289,6 +290,34 @@ function findEnvFile(projectRoot) {
 	return null;
 }
 /**
+* Read the project's `.env` into a plain object.
+*
+* One reader, because there were four: `dotenv` in `start`, a hand-rolled
+* `indexOf("=")` loop in `api-keys`, a single-key regex in `auth`, and its own
+* splitting in `cloud env`. `dotenv` is a declared dependency of this package,
+* so the other three existed for no reason and disagreed with the correct one
+* on the two things people actually write in a `.env`:
+*
+*   - `export KEY=value`, which the hand-rolled parser keyed as
+*     `export KEY` — so the command reported the key as unset while it was
+*     right there in the file;
+*   - `KEY=value # comment`, whose comment travelled into the value and then
+*     into an `Authorization` header, coming back as a 401 with nothing
+*     pointing at the cause.
+*
+* Returns `{}` when the project has no `.env`, so callers can treat "absent"
+* and "empty" alike.
+*/
+function readEnvFile(projectRoot) {
+	const envFile = findEnvFile(projectRoot);
+	if (!envFile || !fs.existsSync(envFile)) return {};
+	try {
+		return dotenv.parse(fs.readFileSync(envFile, "utf-8"));
+	} catch {
+		return {};
+	}
+}
+/**
 * Resolve a binary from the project's node_modules/.bin.
 * Checks backend, root, parent monorepo root, then falls back to PATH.
 */
@@ -1789,7 +1818,7 @@ async function createProject$1(options) {
 		console.log(`  ${chalk.cyan(runDev.join(" "))}`);
 	}
 	console.log("");
-	console.log(isBaas ? chalk.gray("This starts a headless API (Hono + PostgreSQL). There are no collection files: ") + chalk.gray("the API is derived from your database schema. Once it serves a table, docs are at /api/swagger.") : chalk.gray("This starts both the backend (Hono + PostgreSQL)") + chalk.gray(" and the frontend (Vite + React) concurrently."));
+	console.log(isBaas ? introspected ? chalk.gray("This starts a headless API (Hono + PostgreSQL) over the collections just ") + chalk.gray("generated from your database in config/collections. Edit them to change what the ") + chalk.gray("API exposes; docs are at /api/swagger.") : chalk.gray("This starts a headless API (Hono + PostgreSQL). There are no collection files: ") + chalk.gray("the API is derived from your database schema. Once it serves a table, docs are at /api/swagger.") : chalk.gray("This starts both the backend (Hono + PostgreSQL)") + chalk.gray(" and the frontend (Vite + React) concurrently."));
 	console.log("");
 	console.log(chalk.gray("Docs: https://rebase.pro/docs"));
 	console.log(chalk.gray("GitHub: https://github.com/rebasepro/rebase"));
@@ -2013,6 +2042,32 @@ function readCliVersion() {
 	} catch {}
 	return "latest";
 }
+/**
+* The runtime image tag to pin, given the version of the CLI doing the scaffolding.
+*
+* Only a stable release publishes `rebasepro/server` — a multi-arch build on
+* every push to main would cost minutes per commit for an image nobody pulls.
+* So pinning a prerelease CLI's own version writes a tag that cannot exist, and
+* `docker compose up` fails on `manifest unknown`, which is the same dead end
+* as the missing-repository bug this pinning was added to prevent.
+*
+* A prerelease therefore falls back to `latest`, which is correct rather than
+* merely available: a bundle's manifest declares the runtime range it needs
+* (`^1`), the image supplies only `@rebasepro/server`, and the framework a
+* bundle runs is installed from its own `deps.declared` at boot. The current
+* stable runtime boots a canary bundle by design.
+*
+* A floating tag is a real cost — it is what pinning exists to avoid — so say
+* so in the file rather than leaving a reader to discover it.
+*/
+function resolveRuntimeImageTag(cliVersion) {
+	if (/^\d+\.\d+\.\d+-/.test(cliVersion)) return {
+		tag: "latest",
+		note: `# Scaffolded by a prerelease CLI (${cliVersion}), which publishes no runtime image,\n# so this floats to the newest stable runtime. Pin an exact version once you
+# deploy: a moving tag changes what you are running with no version changing.`
+	};
+	return { tag: cliVersion };
+}
 async function configureEnvFile(targetDirectory, databaseUrl) {
 	const envExamplePath = path.join(targetDirectory, ".env.example");
 	const envPath = path.join(targetDirectory, ".env");
@@ -2031,8 +2086,9 @@ async function configureEnvFile(targetDirectory, databaseUrl) {
 		envContent = envContent.replace(/^#\s*REBASE_SERVICE_KEY=.*$/m, `REBASE_SERVICE_KEY=${serviceKey}`);
 		const composeApiPort = /^PORT=(\d+)/m.exec(envContent)?.[1] ?? "3001";
 		envContent = envContent.replace(/^#\s*CORS_ORIGINS=.*$/m, `CORS_ORIGINS=http://localhost:${composeApiPort}`);
-		const runtimeVersion = readCliVersion();
-		envContent = /^#?\s*REBASE_VERSION=.*$/m.test(envContent) ? envContent.replace(/^#?\s*REBASE_VERSION=.*$/m, `REBASE_VERSION=${runtimeVersion}`) : `${envContent.trimEnd()}\n\n# The Rebase runtime image tag docker-compose.yml pulls.\n# Change this and restart to upgrade; your project bundle is untouched.\nREBASE_VERSION=${runtimeVersion}\n`;
+		const { tag: runtimeVersion, note } = resolveRuntimeImageTag(readCliVersion());
+		const pinned = `${note ? `${note}\n` : ""}REBASE_VERSION=${runtimeVersion}`;
+		envContent = /^#?\s*REBASE_VERSION=.*$/m.test(envContent) ? envContent.replace(/^#?\s*REBASE_VERSION=.*$/m, pinned) : `${envContent.trimEnd()}\n\n# The Rebase runtime image tag docker-compose.yml pulls.\n# Change this and restart to upgrade; your project bundle is untouched.\n${pinned}\n`;
 		if (databaseUrl) {
 			if (/[\r\n]/.test(databaseUrl)) throw new Error("Invalid DATABASE_URL: multiline values are not allowed.");
 			const { pinSearchPath } = await import("@rebasepro/server-postgres");
@@ -2040,7 +2096,7 @@ async function configureEnvFile(targetDirectory, databaseUrl) {
 			envContent = envContent.replace(/^DATABASE_URL=.*$/m, `DATABASE_URL=${pinnedUrl}\nDATABASE_PASSWORD=${dbPassword}`);
 		} else {
 			const dbPort = await findAvailablePort(5432);
-			envContent = envContent.replace(/^DATABASE_URL=.*$/m, `DATABASE_URL=postgresql://rebase:${dbPassword}@localhost:${dbPort}/rebase?options=-c%20search_path=public&sslmode=disable\nDATABASE_PASSWORD=${dbPassword}`);
+			envContent = envContent.replace(/^DATABASE_URL=.*$/m, `DATABASE_URL=postgresql://rebase_app:${dbPassword}@localhost:${dbPort}/rebase?options=-c%20search_path=public&sslmode=disable\nDATABASE_PASSWORD=${dbPassword}`);
 			const dockerComposePath = path.join(targetDirectory, "docker-compose.yml");
 			if (fs.existsSync(dockerComposePath)) {
 				let dockerComposeContent = fs.readFileSync(dockerComposePath, "utf-8");
@@ -2367,7 +2423,7 @@ async function schemaCommand(subcommand, rawArgs) {
 		return;
 	}
 	const projectRoot = requireProjectRoot();
-	recordEvent("cli.schema_generate", { subcommand: subcommand ?? "none" }, { projectRoot });
+	recordEvent("cli.schema", { subcommand: subcommand ?? "none" }, { projectRoot });
 	const backendDir = requireBackendDir(projectRoot);
 	const activePlugin = getActiveBackendPlugin(backendDir);
 	if (!activePlugin) {
@@ -2436,7 +2492,7 @@ async function dbCommand(subcommand, rawArgs) {
 		return;
 	}
 	const projectRoot = requireProjectRoot();
-	recordEvent("cli.db_push", { subcommand: subcommand ?? "none" }, { projectRoot });
+	recordEvent("cli.db", { subcommand: subcommand ?? "none" }, { projectRoot });
 	const backendDir = requireBackendDir(projectRoot);
 	const activePlugin = getActiveBackendPlugin(backendDir);
 	if (!activePlugin) {
@@ -3074,6 +3130,106 @@ function resolveBackendPaths(app, projectRoot) {
 	};
 }
 //#endregion
+//#region src/utils/collection-drift.ts
+/**
+* Which edits under `config/collections` can put the *SQL* schema out of date.
+*
+* `rebase dev` watches that directory and, on any change, either tells the
+* developer to run `rebase schema generate` / `rebase db push` or runs them.
+* The watcher is recursive and knows nothing about what it is watching, so it
+* said that about every file under the directory — including a
+* `collections/firestore/exercises.ts`, whose documents live in Firestore and
+* for which there is no Drizzle schema to regenerate and no database to push
+* to. Advice that is wrong on every edit is advice a developer learns to
+* ignore, which is worse than none: the same box is the only warning for the
+* Postgres collection next to it, where it is real.
+*
+* Two independent reasons a change cannot affect the SQL schema, both checked
+* here:
+*
+* 1. **The loader would never read the file.** `loadCollectionsFromDirectory`
+*    reads the top level of the collections directory only — no recursion, no
+*    `index`, no tests, no declarations. A file it does not read cannot change
+*    what it returns, and the watcher must not claim otherwise.
+* 2. **Every collection in it is served by another engine.** A Firestore or
+*    MongoDB collection has no table, no migration and no policies.
+*
+* The engine check reads the source text rather than importing the module: the
+* CLI runs as plain Node and cannot evaluate a project's TypeScript, and a
+* watcher must answer in the time between two keystrokes. Anything it cannot
+* read confidently counts as SQL-affecting — a spurious warning is a nuisance,
+* a suppressed one hides real drift.
+*/
+/**
+* Would `loadCollectionsFromDirectory` load this file?
+*
+* Mirrors that loader's own `isCollectionFile` plus its flat (non-recursive)
+* scan. `relativePath` is relative to the collections directory, as `fs.watch`
+* reports it.
+*/
+function isLoadedCollectionFile(relativePath) {
+	const normalized = relativePath.split(path.sep).join("/");
+	if (normalized.includes("/")) return false;
+	const file = normalized;
+	if (!file.endsWith(".ts") && !file.endsWith(".js")) return false;
+	if (file.startsWith(".")) return false;
+	if (file.includes(".test.")) return false;
+	if (file.endsWith(".d.ts")) return false;
+	if (file === "index.ts" || file === "index.js") return false;
+	return true;
+}
+var ENGINE_LITERAL = /\bengine\s*:\s*["'`]([^"'`]+)["'`]/g;
+var DATA_SOURCE_LITERAL = /\bdataSource\s*:\s*["'`]([^"'`]+)["'`]/g;
+/**
+* Drop comments, so a `// engine: "firestore"` in a docblock cannot silence a
+* warning about the Postgres collection the file actually declares.
+*
+* Deliberately naive — it does not understand strings, so a `//` inside one
+* (a URL in a default value) eats the rest of that line. That only ever removes
+* text, and removing an engine literal makes this file *more* likely to warn,
+* which is the side to be wrong on.
+*/
+function stripComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+}
+function literals(source, pattern) {
+	const found = [];
+	for (const match of source.matchAll(pattern)) found.push(match[1]);
+	return found;
+}
+/**
+* Does this collection source declare anything a SQL toolchain would own?
+*
+* The fallback order matches `resolveDataSource`: an explicit `engine` wins,
+* and a collection that only names a `dataSource` is resolved as if the key
+* were the engine — which is what that function does when no registry is
+* available, and the CLI has none. An engine nobody recognises counts as
+* relational, for the reason `isRelationalCollection` gives.
+*
+* A file declaring several collections is SQL-affecting if *any* of them is.
+*/
+function declaresRelationalCollection(rawSource) {
+	const source = stripComments(rawSource);
+	const engines = literals(source, ENGINE_LITERAL);
+	const declared = engines.length > 0 ? engines : literals(source, DATA_SOURCE_LITERAL).filter((key) => key !== DEFAULT_DATA_SOURCE_KEY);
+	if (declared.length === 0) return true;
+	return declared.some((engine) => getDataSourceCapabilities(engine).supportsRelations);
+}
+/**
+* Can this edit have changed the generated SQL schema?
+*
+* Answers `true` when it cannot tell — an unreadable file is a reason to warn,
+* not a reason to go quiet.
+*/
+function affectsSqlSchema(collectionsDir, relativePath) {
+	if (!isLoadedCollectionFile(relativePath)) return false;
+	try {
+		return declaresRelationalCollection(fs.readFileSync(path.join(collectionsDir, relativePath), "utf8"));
+	} catch {
+		return true;
+	}
+}
+//#endregion
 //#region src/commands/dev.ts
 /**
 * CLI command: rebase dev
@@ -3167,14 +3323,33 @@ function getProjectPort(projectRoot) {
 * 3. Previously used port from .rebase-dev-port (port affinity across restarts)
 * 4. Deterministic hash from project path (unique per project)
 */
+/**
+* A TCP port, or `undefined` for anything that is not one.
+*
+* One predicate for both sources below. The port file was already checked for
+* range, and `PORT` — the source a human or a platform actually sets — was not,
+* so `PORT=oops` reached `parseInt` and was returned as `NaN`: the dev server
+* then bound to whatever the OS handed out and the CLI printed a URL for a port
+* nothing was listening on.
+*/
+function parsePort(raw) {
+	if (raw === void 0) return void 0;
+	const port = Number(raw.trim());
+	if (!Number.isInteger(port) || port <= 0 || port >= 65536) return void 0;
+	return port;
+}
 function resolveStartPort(projectRoot, explicitPort) {
 	if (explicitPort) return explicitPort;
-	if (process.env.PORT) return parseInt(process.env.PORT, 10);
+	if (process.env.PORT) {
+		const fromEnv = parsePort(process.env.PORT);
+		if (fromEnv !== void 0) return fromEnv;
+		console.warn(chalk.yellow(`  ⚠ Ignoring PORT="${process.env.PORT}" — not a port between 1 and 65535.`));
+	}
 	try {
 		const portFile = path.join(projectRoot, DEV_PORT_FILENAME);
 		if (fs.existsSync(portFile)) {
-			const saved = parseInt(fs.readFileSync(portFile, "utf-8").trim(), 10);
-			if (saved > 0 && saved < 65536) return saved;
+			const saved = parsePort(fs.readFileSync(portFile, "utf-8"));
+			if (saved !== void 0) return saved;
 		}
 	} catch {}
 	return getProjectPort(projectRoot);
@@ -3188,7 +3363,7 @@ async function devCommand(rawArgs) {
 		"--help": Boolean,
 		"-b": "--backend-only",
 		"-f": "--frontend-only",
-		"-p": "--port",
+		"-P": "--port",
 		"-g": "--generate",
 		"-h": "--help"
 	}, {
@@ -3345,6 +3520,20 @@ async function devCommand(rawArgs) {
 		} catch {}
 		/** Whether the frontend has been launched (we only launch it once). */
 		let frontendLaunched = false;
+		try {
+			const activePlugin = getActiveBackendPlugin(backendDir);
+			const pluginCli = activePlugin ? resolvePluginCliScript(backendDir, activePlugin) : null;
+			if (pluginCli) await execa(tsxBin, [
+				pluginCli,
+				"schema",
+				"stale",
+				"--fix"
+			], {
+				cwd: backendDir,
+				stdio: "inherit",
+				env
+			});
+		} catch {}
 		if (shouldGenerate) {
 			console.log(chalk.gray("  → Ensuring schema and SDK are generated on start..."));
 			try {
@@ -3372,14 +3561,18 @@ async function devCommand(rawArgs) {
 			const collectionsDir = path.join(projectRoot, "config", "collections");
 			if (fs.existsSync(collectionsDir)) {
 				let watchDebounce = null;
+				let sqlSchemaAffected = false;
 				fs.watch(collectionsDir, { recursive: true }, (eventType, filename) => {
 					if (!filename || filename.startsWith(".") || filename.endsWith(".tmp")) return;
+					sqlSchemaAffected = sqlSchemaAffected || affectsSqlSchema(collectionsDir, filename);
 					if (watchDebounce) clearTimeout(watchDebounce);
 					watchDebounce = setTimeout(async () => {
-						console.log(chalk.yellow(`\n  🔄 Collection change detected (${filename}). Regenerating schema & SDK...`));
+						const regenerateSchema = sqlSchemaAffected;
+						sqlSchemaAffected = false;
+						console.log(chalk.yellow(`\n  🔄 Collection change detected (${filename}). Regenerating ${regenerateSchema ? "schema & SDK" : "SDK"}...`));
 						try {
 							const activePlugin = getActiveBackendPlugin(backendDir);
-							const pluginCli = activePlugin ? resolvePluginCliScript(backendDir, activePlugin) : null;
+							const pluginCli = regenerateSchema && activePlugin ? resolvePluginCliScript(backendDir, activePlugin) : null;
 							if (pluginCli) await execa(tsxBin, [
 								pluginCli,
 								"schema",
@@ -3395,7 +3588,7 @@ async function devCommand(rawArgs) {
 								stdio: "inherit",
 								env
 							});
-							console.log(chalk.green("  ✓ Schema & SDK regenerated successfully. Hono will reload."));
+							console.log(chalk.green(`  ✓ ${regenerateSchema ? "Schema & SDK" : "SDK"} regenerated successfully. Hono will reload.`));
 						} catch (err) {
 							console.error(chalk.red(`  ✗ Failed to regenerate schema/SDK: ${err instanceof Error ? err.message : err}`));
 						}
@@ -3420,12 +3613,14 @@ async function devCommand(rawArgs) {
 				let driftDebounce = null;
 				fs.watch(collectionsDir, { recursive: true }, (_eventType, filename) => {
 					if (!filename || filename.startsWith(".") || filename.endsWith(".tmp")) return;
+					if (!affectsSqlSchema(collectionsDir, filename)) return;
 					if (driftDebounce) clearTimeout(driftDebounce);
 					driftDebounce = setTimeout(() => {
+						const shown = filename.length > 31 ? `…${filename.slice(-30)}` : filename.padEnd(31);
 						console.log([
 							"",
 							chalk.yellow("  ┌──────────────────────────────────────────────────────────────┐"),
-							chalk.yellow("  │  ⚠️  Collection file changed: ") + chalk.white(filename.padEnd(31)) + chalk.yellow("│"),
+							chalk.yellow("  │  ⚠️  Collection file changed: ") + chalk.white(shown) + chalk.yellow("│"),
 							chalk.yellow("  │                                                              │"),
 							chalk.yellow("  │  Your schema may be out of sync. Run:                        │"),
 							chalk.yellow("  │    ") + chalk.cyan("rebase schema generate") + chalk.yellow("   regenerate Drizzle schema        │"),
@@ -4732,7 +4927,8 @@ ${chalk.bold("Examples")}
 }
 async function buildCommand(rawArgs = []) {
 	const args = arg({
-		"--out": String,
+		"--output": String,
+		"--out": "--output",
 		"--skip-type-check": Boolean,
 		"--skip-schema": Boolean,
 		"--no-static": Boolean,
@@ -4800,7 +4996,7 @@ async function buildCommand(rawArgs = []) {
 				projectRoot,
 				appName: name,
 				app,
-				outDir: args["--out"],
+				outDir: args["--output"],
 				runtimeRange: manifest.rebase,
 				storage: manifest.storage,
 				skipTypeCheck: args["--skip-type-check"],
@@ -4837,7 +5033,7 @@ async function buildCommand(rawArgs = []) {
 				});
 				for (const outcome of folded ?? []) console.log(chalk.green(`    ✓ ${outcome.appName} folded in`) + chalk.dim(` (${outcome.fileCount} file(s) → served at ${outcome.path})`));
 			}
-		} else if (app.type === "static") await buildAssetApp(projectRoot, name, app, manifest.rebase, args["--out"]);
+		} else if (app.type === "static") await buildAssetApp(projectRoot, name, app, manifest.rebase, args["--output"]);
 		console.log("");
 	}
 	console.log(chalk.green("✓ Build complete."));
@@ -5286,6 +5482,48 @@ async function startWorkspaceBackend(projectRoot, env) {
 * Subcommands:
 *   reset-password — Reset a user's password
 */
+/**
+* Pick the user with exactly this email out of a search response.
+*
+* `/api/admin/users?search=` is an `ILIKE '%…%'` over email **or display
+* name**, ordered by role count descending. This used to take row `[0]` and
+* reset it, then print the email it had been *given* as confirmation — so two
+* ordinary situations ended in a successful-looking reset of somebody else's
+* account:
+*
+*   - a substring collision: `bob@example.com` also matches
+*     `robert.bob@example.com`;
+*   - a display name, which is user-controlled and accepted up to 255
+*     characters with no constraint on its content, containing an address
+*     belonging to someone else.
+*
+* The ordering makes it worse rather than better — `array_length(roles) DESC
+* NULLS LAST` puts the most privileged match first, so the account most likely
+* to be reset by mistake is an admin's.
+*
+* Returns `undefined` when nothing matched exactly, which the caller reports
+* rather than falling through to a guess. The direct-database fallback below
+* has always matched with `eq(usersTable.email, email)`; this is the same
+* definition, so the command no longer resets different accounts depending on
+* whether the backend happened to be running.
+*/
+function selectUserForEmail(payload, email) {
+	const wanted = email.trim().toLowerCase();
+	if (!wanted) return void 0;
+	const rows = Array.isArray(payload) ? payload : payload && typeof payload === "object" && Array.isArray(payload.users) ? payload.users : [];
+	for (const row of rows) {
+		if (!row || typeof row !== "object") continue;
+		const record = row;
+		const rowEmail = typeof record.email === "string" ? record.email.trim().toLowerCase() : void 0;
+		if (!rowEmail || rowEmail !== wanted) continue;
+		const id = typeof record.id === "string" ? record.id : typeof record.uid === "string" ? record.uid : void 0;
+		if (!id) continue;
+		return {
+			id,
+			email: record.email
+		};
+	}
+}
 async function authCommand(subcommand, rawArgs) {
 	if (!subcommand || subcommand === "--help") {
 		printAuthHelp();
@@ -5306,8 +5544,7 @@ async function resetPassword(rawArgs) {
 	const args = arg({
 		"--email": String,
 		"--password": String,
-		"-e": "--email",
-		"-p": "--password"
+		"-e": "--email"
 	}, {
 		argv: rawArgs.slice(4),
 		permissive: true
@@ -5322,12 +5559,8 @@ async function resetPassword(rawArgs) {
 		process.exit(1);
 	}
 	const projectRoot = requireProjectRoot();
-	let envServiceKey;
 	const envFile = findEnvFile(projectRoot);
-	if (envFile && fs.existsSync(envFile)) try {
-		const match = fs.readFileSync(envFile, "utf8").match(/^\s*REBASE_SERVICE_KEY\s*=\s*['"]?(.*?)['"]?\s*$/m);
-		if (match && match[1]) envServiceKey = match[1];
-	} catch {}
+	const envServiceKey = readEnvFile(projectRoot).REBASE_SERVICE_KEY;
 	let baseUrl = process.env.REBASE_BASE_URL;
 	let serviceKey = process.env.REBASE_SERVICE_KEY || envServiceKey;
 	const statePath = path.join(projectRoot, ".rebase", "state.json");
@@ -5347,7 +5580,7 @@ async function resetPassword(rawArgs) {
 		try {
 			const finalPass = newPassword || "NewPassword123!";
 			const cleanBaseUrl = baseUrl.replace(/\/+$/, "");
-			const searchUrl = `${cleanBaseUrl}/api/admin/users?search=${encodeURIComponent(email)}&limit=1`;
+			const searchUrl = `${cleanBaseUrl}/api/admin/users?search=${encodeURIComponent(email)}&limit=50`;
 			const searchRes = await fetch(searchUrl, { headers: {
 				"Authorization": `Bearer ${serviceKey}`,
 				"Accept": "application/json"
@@ -5355,18 +5588,9 @@ async function resetPassword(rawArgs) {
 			if (!searchRes.ok) throw new Error(`Failed to list users: ${searchRes.statusText}`);
 			const searchData = await searchRes.json();
 			if (!searchData || typeof searchData !== "object") throw new Error("Invalid response format from user search API.");
-			let userId;
-			if (Array.isArray(searchData)) {
-				const firstUser = searchData[0];
-				if (firstUser && typeof firstUser === "object" && "id" in firstUser && typeof firstUser.id === "string") userId = firstUser.id;
-				else if (firstUser && typeof firstUser === "object" && "uid" in firstUser && typeof firstUser.uid === "string") userId = firstUser.uid;
-			} else if ("users" in searchData && Array.isArray(searchData.users)) {
-				const firstUser = searchData.users[0];
-				if (firstUser && typeof firstUser === "object" && "id" in firstUser && typeof firstUser.id === "string") userId = firstUser.id;
-				else if (firstUser && typeof firstUser === "object" && "uid" in firstUser && typeof firstUser.uid === "string") userId = firstUser.uid;
-			}
-			if (!userId) throw new Error(`User not found with email: ${email}`);
-			const resetUrl = `${cleanBaseUrl}/api/admin/users/${userId}/reset-password`;
+			const matched = selectUserForEmail(searchData, email);
+			if (!matched) throw new Error(`No user has the email ${email}.`);
+			const resetUrl = `${cleanBaseUrl}/api/admin/users/${matched.id}/reset-password`;
 			const resetRes = await fetch(resetUrl, {
 				method: "POST",
 				headers: {
@@ -5383,7 +5607,7 @@ async function resetPassword(rawArgs) {
 			console.log("API reset successful.");
 			console.log(chalk.bold("  🔑 Rebase Auth — Reset Password (via API)"));
 			console.log("");
-			console.log(`  ${chalk.gray("Email:")} ${email}`);
+			console.log(`  ${chalk.gray("Email:")} ${matched.email}`);
 			console.log(`  ${chalk.gray("Password:")} ${finalPass}`);
 			console.log("");
 			return;
@@ -5451,10 +5675,12 @@ async function resetPassword() {
     if (result.length > 0) {
         console.log("✅ Password reset for: " + result[0].email);
         ${!newPassword ? "console.log(\"   New password: \" + newPassword);" : ""}
-    } else {
-        console.log("✗ User not found: " + email);
+        process.exit(0);
     }
-    process.exit(0);
+    // Nothing was updated, so nothing was reset. Exiting 0 here reported
+    // success for a no-op, which is what a script would have believed.
+    console.error("✗ User not found: " + email);
+    process.exit(1);
 }
 
 resetPassword().catch(console.error);
@@ -5472,11 +5698,20 @@ resetPassword().catch(console.error);
 			stdio: "inherit",
 			env
 		});
+		const cleanup = () => {
+			try {
+				fs.unlinkSync(tmpScriptPath);
+			} catch {}
+		};
 		return new Promise((resolve) => {
+			child.on("error", (err) => {
+				cleanup();
+				console.error(chalk.red("✗ Could not run the reset script."));
+				console.error(chalk.gray(`  ${err.message}`));
+				process.exit(1);
+			});
 			child.on("close", (code) => {
-				try {
-					fs.unlinkSync(tmpScriptPath);
-				} catch {}
+				cleanup();
 				if (code !== 0) process.exit(code ?? 1);
 				resolve();
 			});
@@ -5514,7 +5749,34 @@ ${chalk.green.bold("Examples")}
 * Detects three-way schema drift between collection definitions,
 * the generated Drizzle schema, and the live PostgreSQL database.
 */
+/**
+* `--help` is answered before the project guard, not after.
+*
+* `doctor` declared no `--help` at all, so the flag fell through to the command
+* body and hit `requireProjectRoot()` — and `rebase doctor --help` outside a
+* project answered "✗ Could not find a Rebase project root." Asking a command
+* what it does is the one question that cannot require being somewhere
+* particular to ask.
+*/
+function printDoctorHelp() {
+	console.log(`
+${chalk.bold("rebase doctor")} — Detect drift between collections, schema and database
+
+${chalk.green.bold("Usage")}
+  rebase doctor
+
+Compares the collections you declare, the generated Drizzle schema, and the
+tables that actually exist, then reports what disagrees and how to reconcile it.
+
+Run from inside a Rebase project — it reads the project's collections and
+connects to its database.
+`);
+}
 async function doctorCommand(rawArgs) {
+	if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+		printDoctorHelp();
+		return;
+	}
 	const projectRoot = requireProjectRoot();
 	const backendDir = requireBackendDir(projectRoot);
 	const activePlugin = getActiveBackendPlugin(backendDir);
@@ -5663,7 +5925,8 @@ async function skillsCommand(subcommand, rawArgs) {
 }
 /**
 * Agents named explicitly on the command line, e.g. `--agent claude --agent cursor`
-* (also accepts a comma-separated list). Returns null when none were given.
+* (also accepts a comma-separated list, and `all`). Returns null when none were
+* given.
 */
 function parseAgentFlags(rawArgs) {
 	const requested = [];
@@ -5673,6 +5936,7 @@ function parseAgentFlags(rawArgs) {
 		if (value && !value.startsWith("-")) requested.push(...value.split(",").map((v) => v.trim()).filter(Boolean));
 	}
 	if (requested.length === 0) return null;
+	if (requested.includes("all")) return Object.keys(AGENTS);
 	const valid = Object.keys(AGENTS);
 	const unknown = requested.filter((a) => !valid.includes(a));
 	if (unknown.length > 0) {
@@ -5700,6 +5964,7 @@ async function skillsInstall(rawArgs = []) {
 		if (!process.stdin.isTTY) {
 			console.error(chalk.red("Cannot prompt: this is a non-interactive terminal (no TTY)."));
 			console.error(chalk.yellow(`  Name the agents explicitly, e.g. rebase skills install --agent ${Object.keys(AGENTS)[0]}`));
+			console.error(chalk.yellow("  Or install for every supported agent:  rebase skills install --agent all"));
 			console.error(chalk.gray(`  Available: ${Object.keys(AGENTS).join(", ")}`));
 			process.exit(1);
 		}
@@ -5747,13 +6012,16 @@ ${chalk.green.bold("Subcommands")}
 
 ${chalk.green.bold("Options")}
   ${chalk.blue("--agent, -a")}   Agent(s) to install for, skipping detection and the prompt.
-                Repeat the flag or pass a comma-separated list.
-                Available: ${Object.keys(AGENTS).join(", ")}
+                Repeat the flag or pass a comma-separated list, or ${chalk.bold("all")}.
+                Required without a TTY: a scaffolded project carries a marker
+                file for every agent, so detection cannot pick one for you.
+                Available: ${Object.keys(AGENTS).join(", ")}, all
 
 ${chalk.green.bold("Examples")}
   ${chalk.cyan("rebase skills install")}
   ${chalk.cyan("rebase skills install --agent claude")}
   ${chalk.cyan("rebase skills install --agent claude,cursor")}
+  ${chalk.cyan("rebase skills install --agent all")}   ${chalk.gray("# scripted / CI")}
 `);
 }
 //#endregion
@@ -5766,25 +6034,13 @@ ${chalk.green.bold("Examples")}
 *   create  — Create a new API key
 *   revoke  — Revoke an existing API key
 */
-function loadEnv(projectRoot) {
-	const envFile = findEnvFile(projectRoot);
-	const env = {};
-	if (envFile && fs.existsSync(envFile)) {
-		const content = fs.readFileSync(envFile, "utf-8");
-		for (const line of content.split("\n")) {
-			const trimmed = line.trim();
-			if (!trimmed || trimmed.startsWith("#")) continue;
-			const idx = trimmed.indexOf("=");
-			if (idx > 0) {
-				const key = trimmed.slice(0, idx).trim();
-				let value = trimmed.slice(idx + 1).trim();
-				if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
-				env[key] = value;
-			}
-		}
-	}
-	return env;
-}
+/**
+* Was a hand-rolled `indexOf("=")` loop. It keyed `export KEY=value` as
+* `export KEY` and carried a trailing `# comment` into the value — so a key
+* that was present read as absent, or reached an `Authorization` header with a
+* comment attached and came back 401. See `readEnvFile`.
+*/
+var loadEnv = readEnvFile;
 function resolveBaseUrl(env, projectRoot) {
 	if (env.REBASE_BASE_URL) return env.REBASE_BASE_URL;
 	if (projectRoot) try {
@@ -6055,7 +6311,12 @@ ${chalk.green.bold("Examples")}
 * a documentation comment that quietly fell out of date two releases ago.
 */
 async function telemetryCommand(rawArgs) {
-	switch (rawArgs.slice(3).filter((a) => !a.startsWith("-"))[0]) {
+	const subcommand = rawArgs.slice(3).filter((a) => !a.startsWith("-"))[0];
+	if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+		printHelp$2();
+		return;
+	}
+	switch (subcommand) {
 		case "status":
 		case void 0:
 			printStatus();
@@ -6154,8 +6415,7 @@ async function loginCommand(rawArgs) {
 	const args = arg({
 		"--email": String,
 		"--password": String,
-		"-e": "--email",
-		"-p": "--password"
+		"-e": "--email"
 	}, {
 		argv: rawArgs.slice(3),
 		permissive: true
@@ -8162,7 +8422,8 @@ async function revealEnv(rawArgs) {
 }
 async function pullEnv(rawArgs) {
 	const args = arg({
-		"--out": String,
+		"--output": String,
+		"--out": "--output",
 		"--yes": Boolean,
 		"-y": "--yes",
 		"--project": String,
@@ -8174,7 +8435,7 @@ async function pullEnv(rawArgs) {
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	displayProjectRef(rawArgs);
-	const outPath = path.resolve(args["--out"] || ".env");
+	const outPath = path.resolve(args["--output"] || ".env");
 	try {
 		const list = await fetchEnvVars(client, projectId);
 		if (fs.existsSync(outPath)) await confirmDestructive({
@@ -10293,15 +10554,43 @@ function positionals(rawArgs) {
 	while (i < rest.length && rest[i].startsWith("-")) i++;
 	return rest.slice(i);
 }
+/**
+* The help page for each group, keyed by every alias the dispatch below accepts.
+*
+* Aliases are listed explicitly rather than normalised first, so a group that
+* gains one and forgets it here degrades to the index page — wrong, but a page.
+* `cloud-help.test.ts` asserts the two stay in step.
+*
+* A group absent from this map has no page of its own; the index lists it.
+*/
+var GROUP_HELP = {
+	env: printEnvHelp,
+	domains: printDomainsHelp,
+	domain: printDomainsHelp,
+	extensions: printExtensionsHelp,
+	extension: printExtensionsHelp,
+	settings: printSettingsHelp,
+	orgs: printOrgsHelp,
+	org: printOrgsHelp,
+	db: printDbHelp,
+	database: printDbHelp,
+	debug: printDebugHelp,
+	storage: printStorageHelp
+};
 async function cloudCommand(subcommand, rawArgs) {
 	initOutputMode(rawArgs);
 	const pos = positionals(rawArgs);
 	const group = pos[0] ?? (subcommand !== "--help" ? subcommand : void 0);
+	const wantsHelp = rawArgs.includes("--help") || rawArgs.includes("-h");
 	const action = pos[1];
-	if (!group || subcommand === "--help") {
+	if (!group) {
 		printCloudHelp();
 		return;
 	}
+	if (wantsHelp) {
+		(GROUP_HELP[group] ?? printCloudHelp)();
+		return;
+	}
 	switch (group) {
 		case "login":
 			await loginCommand(rawArgs);
@@ -10741,7 +11030,7 @@ async function entry(args) {
 		printHelp();
 		return;
 	}
-	const effectiveSubcommand = parsedArgs["--help"] ? "--help" : subcommand;
+	const effectiveSubcommand = parsedArgs["--help"] && !subcommand ? "--help" : subcommand;
 	switch (command) {
 		case "init":
 			await createRebaseApp(args);
@@ -10860,9 +11149,11 @@ ${chalk.green.bold("API Keys")}
   ${chalk.blue.bold("api-keys list")}           List all service API keys
   ${chalk.blue.bold("api-keys create")}         Create a new scoped API key
   ${chalk.blue.bold("api-keys revoke")}         Revoke an existing API key
-  ${chalk.blue.bold("telemetry")}               Anonymous usage sharing (opt-in, off by default)
   ${chalk.blue.bold("api-keys")} ${chalk.gray("--help")}         Show API key command help
 
+${chalk.green.bold("Usage sharing")}
+  ${chalk.blue.bold("telemetry")}               Anonymous usage sharing (opt-in, off by default)
+
 ${chalk.green.bold("Rebase Cloud")}
   ${chalk.blue.bold("cloud login")}             Sign in to the hosted control plane
   ${chalk.blue.bold("cloud link")}              Link this directory to a cloud project
@@ -10893,6 +11184,6 @@ function telemetryNotice() {
 	return chalk.gray(`Usage sharing: ${sharing ? "on" : "off"} — ${chalk.cyan("rebase telemetry")} to inspect or change\n`);
 }
 //#endregion
-export { CURRENT_RUNTIME_RANGE, DEFAULT_BUNDLE_DIR, DEFAULT_CONFIG_DIR, DEFAULT_CRONS_DIR, DEFAULT_FUNCTIONS_DIR, DEFAULT_SCHEMA_FILE, DEV_PORT_FILENAME, MANIFEST_FILENAME, ManifestError, TEMPLATE_PLACEHOLDER_FILES, appsCommand, assessManagedCompatibility, authCommand, buildBundle, buildCommand, buildInitQuestions, buildStaticBundle, buildableApps, cloudCommand, collectDeclaredDependencies, configureEnvFile, createRebaseApp, dbCommand, detectFrameworkDepDrift, detectNativeDependencies, detectPackageManager, detectStorageAuthorize, devCommand, doctorCommand, ejectCommand, entry, findBackendApp, findBackendDir, findEnvFile, findFrontendDir, findProjectRoot, findUnusedServerEntry, foldStaticIntoBundle, formatCdTarget, generateSdkCommand, getActiveBackendPlugin, getPMCommands, getProjectPort, isIdentifierLike, isPnpmAvailable, loadManifest, manifestExists, manifestPath, normalizeEsmSpecifiers, pnpmAvailabilityFromProbe, positionals, printInitHelp, requireBackendDir, requireProjectRoot, resetPnpmAvailabilityCache, resolveBackendPaths, resolveCliVersion, resolveExampleBaseUrl, resolveLocalBin, resolvePluginCliScript, resolveStartPort, resolveTsx, schemaCommand, startCommand, synthesizeManifest, validateManifest, validateProjectName, validateTsxInstallation, writeManifest };
+export { CURRENT_RUNTIME_RANGE, DEFAULT_BUNDLE_DIR, DEFAULT_CONFIG_DIR, DEFAULT_CRONS_DIR, DEFAULT_FUNCTIONS_DIR, DEFAULT_SCHEMA_FILE, DEV_PORT_FILENAME, MANIFEST_FILENAME, ManifestError, TEMPLATE_PLACEHOLDER_FILES, appsCommand, assessManagedCompatibility, authCommand, buildBundle, buildCommand, buildInitQuestions, buildStaticBundle, buildableApps, cloudCommand, collectDeclaredDependencies, configureEnvFile, createRebaseApp, dbCommand, detectFrameworkDepDrift, detectNativeDependencies, detectPackageManager, detectStorageAuthorize, devCommand, doctorCommand, ejectCommand, entry, findBackendApp, findBackendDir, findEnvFile, findFrontendDir, findProjectRoot, findUnusedServerEntry, foldStaticIntoBundle, formatCdTarget, generateSdkCommand, getActiveBackendPlugin, getPMCommands, getProjectPort, isIdentifierLike, isPnpmAvailable, loadManifest, manifestExists, manifestPath, normalizeEsmSpecifiers, pnpmAvailabilityFromProbe, positionals, printInitHelp, readEnvFile, requireBackendDir, requireProjectRoot, resetPnpmAvailabilityCache, resolveBackendPaths, resolveCliVersion, resolveExampleBaseUrl, resolveLocalBin, resolvePluginCliScript, resolveRuntimeImageTag, resolveStartPort, resolveTsx, schemaCommand, selectUserForEmail, startCommand, synthesizeManifest, validateManifest, validateProjectName, validateTsxInstallation, writeManifest };
 
 //# sourceMappingURL=index.es.js.map