@rebasepro/cli 0.21.1-canary.g8c5a265 → 0.21.1

package/dist/index.es.js

@@ -13,7 +13,7 @@ import path from "path";
 import * as fs$1 from "fs";
 import fs from "fs";
 import net from "net";
-import { promisify } from "util";
+import { isDeepStrictEqual, promisify } from "util";
 import { execa, execaCommandSync } from "execa";
 import { cp } from "fs/promises";
 import { fileURLToPath, pathToFileURL } from "url";
@@ -2362,11 +2362,11 @@ async function probeRelease(version) {
 		};
 		return {
 			kind: "unreachable",
-			reason: firstLine(text) || "the registry could not be reached"
+			reason: firstLine$1(text) || "the registry could not be reached"
 		};
 	}
 }
-function firstLine(text) {
+function firstLine$1(text) {
 	return text.split("\n").map((l) => l.trim()).filter(Boolean)[0] ?? "";
 }
 async function replacePlaceholders(options) {
@@ -4545,7 +4545,7 @@ function checkCmsPath(value, appPath, fieldPath, issues) {
 	}
 	return cms;
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
@@ -4682,7 +4682,7 @@ function isNearMiss(a, b) {
 }
 function validateApp(name, raw, issues) {
 	const base = `apps.${name}`;
-	if (!isRecord(raw)) {
+	if (!isRecord$1(raw)) {
 		issues.push({
 			path: base,
 			message: "must be an object"
@@ -4782,7 +4782,7 @@ function validateApp(name, raw, issues) {
 */
 function validateManifest(raw) {
 	const issues = [];
-	if (!isRecord(raw)) return { issues: [{
+	if (!isRecord$1(raw)) return { issues: [{
 		path: "",
 		message: `${MANIFEST_FILENAME} must contain a JSON object`
 	}] };
@@ -4793,7 +4793,7 @@ function validateManifest(raw) {
 			message
 		});
 	}
-	if (!isRecord(raw.apps)) {
+	if (!isRecord$1(raw.apps)) {
 		issues.push({
 			path: "apps",
 			message: "is required and must be an object"
@@ -4981,7 +4981,7 @@ var MODELLED_MANIFEST_KEYS = [
 function readManifestObject(filePath) {
 	try {
 		const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
-		return isRecord(parsed) ? parsed : {};
+		return isRecord$1(parsed) ? parsed : {};
 	} catch {
 		return {};
 	}
@@ -8824,7 +8824,7 @@ function projectResourceGraph(graph) {
 * entrypoint, falls back to the previous behaviour: run every workspace's own
 * `build` script. Nothing that built before stops building.
 */
-function printHelp$5() {
+function printHelp$6() {
 	console.log(`
 ${chalk.bold("rebase build")} — build the apps declared in rebase.json
 
@@ -8886,7 +8886,7 @@ function dockerBuildHint(projectRoot, name, app) {
 }
 async function buildCommand(rawArgs = []) {
 	if (wantsHelp(rawArgs)) {
-		printHelp$5();
+		printHelp$6();
 		return;
 	}
 	const { flags: args, positionals: requested } = parseCommandArgs({
@@ -9012,10 +9012,12 @@ async function buildCommand(rawArgs = []) {
 				console.log(chalk.yellow(`    ⚠ framework dependencies older than this CLI (${cliVersion$1()}):`));
 				for (const dep of drift.behind) console.log(chalk.dim(`      ${dep.name}@${dep.range}  (${dep.file})`));
 				console.log(chalk.dim("      The image supplies the server, but your bundle supplies the database"));
-				console.log(chalk.dim("      driver — a newer runtime does not update it. Bump these and rebuild."));
+				console.log(chalk.dim("      driver — a newer runtime does not update it."));
+				console.log(chalk.dim(`      Run \`${upgradeToThisCli()}\`, then rebuild.`));
 			} else if (drift.disagreeing.length > 0) {
 				console.log(chalk.yellow(`    ⚠ mixed @rebasepro versions declared: ${drift.disagreeing.join(", ")}`));
-				console.log(chalk.dim("      These are published together and expect to run together; pin them alike."));
+				console.log(chalk.dim("      These are published together and expect to run together."));
+				console.log(chalk.dim(`      Run \`${upgradeToThisCli()}\` to pin them alike, then rebuild.`));
 			}
 			if (!args["--no-static"]) {
 				const folded = await foldFrontendIntoBundle({
@@ -9091,6 +9093,17 @@ async function buildAssetApp(projectRoot, name, app, runtimeRange, outOverride)
 	console.log(chalk.green(`  ✓ static bundle → ${rel}/`) + chalk.dim(` (${result.fileCount} file(s) → served at ${basePath})`));
 	return result.outDir;
 }
+/**
+* The `rebase upgrade` line the drift warnings print.
+*
+* Aimed at this CLI's own version, because that is what the warning measured
+* against: "older than this CLI" is answered by moving to exactly this CLI, not
+* to whatever `latest` happens to be — which, on a canary, is older still.
+*/
+function upgradeToThisCli() {
+	const version = cliVersion$1();
+	return version === "unknown" ? "rebase upgrade" : `rebase upgrade --to ${version}`;
+}
 /** The pre-manifest behaviour: build every workspace package. */
 async function runWorkspaceBuilds(projectRoot) {
 	const pm = detectPackageManager(projectRoot);
@@ -9240,7 +9253,7 @@ function projectNameOf(projectRoot) {
 	} catch {}
 	return path.basename(projectRoot);
 }
-function printHelp$4() {
+function printHelp$5() {
 	console.log(`
 ${chalk.bold("rebase eject")} — take ownership of the server process
 
@@ -9261,7 +9274,7 @@ ${chalk.bold("Options")}
 }
 async function ejectCommand(rawArgs = []) {
 	if (wantsHelp(rawArgs)) {
-		printHelp$4();
+		printHelp$5();
 		return;
 	}
 	const { flags: args, positionals } = parseCommandArgs({
@@ -9443,7 +9456,7 @@ function restoreBackendScripts(projectRoot) {
 * `rebase.json`) this falls back to the backend workspace's own `start` script,
 * which is what such a project has always used.
 */
-function printHelp$3() {
+function printHelp$4() {
 	console.log(`
 ${chalk.bold("rebase start")} — run a built bundle
 
@@ -9460,7 +9473,7 @@ Build first with ${chalk.cyan("rebase build")}.
 }
 async function startCommand(rawArgs = []) {
 	if (wantsHelp(rawArgs)) {
-		printHelp$3();
+		printHelp$4();
 		return;
 	}
 	const { flags: args } = parseCommandArgs({
@@ -10056,7 +10069,7 @@ function checkNodeVersion(running, required) {
 	}];
 }
 /** The lockfiles a project may have, and the manager each one belongs to. */
-var LOCKFILES = {
+var LOCKFILES$1 = {
 	"pnpm-lock.yaml": "pnpm",
 	"package-lock.json": "npm",
 	"yarn.lock": "yarn",
@@ -10073,18 +10086,18 @@ var LOCKFILES = {
 * at it.
 */
 function checkPackageManager(lockfilesPresent, declared) {
-	const known = lockfilesPresent.filter((file) => file in LOCKFILES);
+	const known = lockfilesPresent.filter((file) => file in LOCKFILES$1);
 	if (known.length < 2) {
 		const declaredName = declared?.split("@")[0];
-		if (known.length === 1 && declaredName && LOCKFILES[known[0]] !== declaredName) return [{
+		if (known.length === 1 && declaredName && LOCKFILES$1[known[0]] !== declaredName) return [{
 			check: "package-manager",
 			severity: "warning",
-			message: `This project declares packageManager "${declared}" and has a ${LOCKFILES[known[0]]} lockfile (${known[0]}).`,
+			message: `This project declares packageManager "${declared}" and has a ${LOCKFILES$1[known[0]]} lockfile (${known[0]}).`,
 			fix: `Delete ${known[0]} and node_modules, then install with ${declaredName}.`
 		}];
 		return [];
 	}
-	const managers = known.map((file) => LOCKFILES[file]);
+	const managers = known.map((file) => LOCKFILES$1[file]);
 	return [{
 		check: "package-manager",
 		severity: "error",
@@ -10192,7 +10205,7 @@ function checkVersionSkew(declared) {
 			check: "versions",
 			severity: "error",
 			message: `${name} is pinned to different versions in this project: ${described}.`,
-			fix: "Pin one version everywhere and reinstall. Two copies of a Rebase package break `instanceof` between them, which fails as a type guard rejecting its own type."
+			fix: "Run `rebase upgrade` to pin every @rebasepro package to one release and reinstall. Two copies of a Rebase package break `instanceof` between them, which fails as a type guard rejecting its own type."
 		});
 	}
 	return findings;
@@ -10318,7 +10331,7 @@ function collectEnvironmentFindings(projectRoot, envFile) {
 	const findings = [];
 	findings.push(...checkNodeVersion(process.versions.node, readCliEngines()));
 	const rootPackage = readJson(path.join(projectRoot, "package.json"));
-	findings.push(...checkPackageManager(Object.keys(LOCKFILES).filter((file) => fs.existsSync(path.join(projectRoot, file))), typeof rootPackage?.packageManager === "string" ? rootPackage.packageManager : void 0));
+	findings.push(...checkPackageManager(Object.keys(LOCKFILES$1).filter((file) => fs.existsSync(path.join(projectRoot, file))), typeof rootPackage?.packageManager === "string" ? rootPackage.packageManager : void 0));
 	findings.push(...checkDuplicateSlugs(readDeclaredSlugs(projectRoot)));
 	if (envFile && fs.existsSync(envFile)) try {
 		findings.push(...checkEnvSanity(parseEnvFile(fs.readFileSync(envFile, "utf-8"))));
@@ -10385,7 +10398,7 @@ function readAtlasBinaryState(projectRoot) {
 }
 /** The reader's own package manager, from the lockfile beside their project. */
 function readPackageManagerName(projectRoot) {
-	for (const [file, manager] of Object.entries(LOCKFILES)) if (fs.existsSync(path.join(projectRoot, file))) return manager;
+	for (const [file, manager] of Object.entries(LOCKFILES$1)) if (fs.existsSync(path.join(projectRoot, file))) return manager;
 	return "pnpm";
 }
 /** The `engines.node` range of the CLI actually running. */
@@ -11942,7 +11955,7 @@ var TELEMETRY_SUBCOMMANDS = [
 ];
 async function telemetryCommand(rawArgs) {
 	if (wantsHelp(rawArgs)) {
-		printHelp$2();
+		printHelp$3();
 		return;
 	}
 	const { positionals } = parseCommandArgs({
@@ -12020,7 +12033,7 @@ function printPayload() {
 	console.log(chalk.gray("  hostname, your project name or anything you have typed."));
 	console.log("");
 }
-function printHelp$2() {
+function printHelp$3() {
 	console.log(`
 ${chalk.bold("rebase telemetry")} — anonymous usage sharing (asked once per project)
 
@@ -15120,7 +15133,13 @@ function bundleDeployBody(input) {
 		...input.commit ? {
 			gitCommitHash: input.commit.hash,
 			gitCommitMessage: input.commit.message
-		} : {}
+		} : {},
+		...input.rebuildSource ? { rebuildSource: {
+			sourceId: input.rebuildSource.sourceId,
+			projectPath: input.rebuildSource.projectPath,
+			buildEnv: input.rebuildSource.buildEnv
+		} } : {},
+		...input.allowFrameworkDowngrade ? { allowFrameworkDowngrade: true } : {}
 	};
 }
 /**
@@ -15161,10 +15180,393 @@ async function uploadBundle(url, token, projectId, tarPath) {
 	return data.bundleId;
 }
 //#endregion
+//#region src/commands/cloud/rebuild-source.ts
+/**
+* The project's source, uploaded beside its bundle so the platform can rebuild it.
+*
+* A managed deploy ships a built bundle, and a bundle is fixed to the framework
+* release it was built on. When the platform rolls a newer release across the
+* fleet it has to rebuild each project from source — and the bundle path never
+* uploaded any: the control plane held a tarball of compiled output and
+* nothing it could compile again. So every bundle deploy now also packs the
+* source the bundle was built from, uploads it, and names it in the trigger.
+*
+* Three rules shape what goes in:
+*
+*  - **Git decides, when there is a repository.** `git ls-files --cached
+*    --others --exclude-standard` at the repository's top level is exactly what
+*    the developer considers source: `.gitignore` honoured the way git honours
+*    it, and a sibling package the project links (`link:../../packages/editor`)
+*    included, because it is outside the project directory but inside the
+*    repository.
+*  - **Secrets never leave the machine, whatever git says.** A committed `.env`
+*    is still a `.env`. {@link neverUploaded} is applied after git, not instead
+*    of it.
+*  - **It never costs the deploy.** The bundle is what runs; the source only
+*    lets a later platform upgrade rebuild it. Too large, unpackable, refused by
+*    the control plane — each is a warning, and the deploy goes on without it.
+*/
+/**
+* The control plane's cap on an uploaded source archive.
+*
+* Keep in sync with its build-context cap (deploy/upload `MAX_BYTES` and the
+* backend's `maxBodySize`). Checked before uploading, so an oversized archive is
+* a message in milliseconds rather than a bare 413 after the upload.
+*/
+var MAX_SOURCE_UPLOAD_BYTES = 100 * 1024 * 1024;
+/** Env files that are templates by convention, and safe to ship. */
+var ENV_TEMPLATES = /* @__PURE__ */ new Set([
+	".env.example",
+	".env.sample",
+	".env.template"
+]);
+/**
+* Whether a file must never be uploaded, whatever the ignore rules said.
+*
+* `relativePath` is POSIX. Installed packages, git's own directory and built
+* bundles are never source. Every `.env` and `.env.*` is excluded except the
+* three template names, and so is direnv's `.envrc`, which is the same thing
+* under another name.
+*/
+function neverUploaded(relativePath) {
+	const segments = relativePath.split("/");
+	if (segments.some((segment) => segment === "node_modules" || segment === ".git" || segment.startsWith("dist-bundle"))) return true;
+	const base = segments[segments.length - 1];
+	if (base === ".envrc") return true;
+	if ((base === ".env" || base.startsWith(".env.")) && !ENV_TEMPLATES.has(base)) return true;
+	return false;
+}
+/** Directories the walk outside a repository never enters. */
+var WALK_SKIP = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	".rebase",
+	".turbo",
+	".next",
+	"coverage"
+]);
+var runGit = (cwd, args) => execFileSync("git", [
+	"-C",
+	cwd,
+	...args
+], {
+	encoding: "utf8",
+	stdio: [
+		"ignore",
+		"pipe",
+		"ignore"
+	],
+	maxBuffer: 256 * 1024 * 1024
+});
+function toPosix(relative) {
+	return relative.split(path.sep).join("/");
+}
+/** A regular file on disk: not missing, not a directory or submodule, not a symlink. */
+function isRegularFile(absolute) {
+	try {
+		return fs.lstatSync(absolute).isFile();
+	} catch {
+		return false;
+	}
+}
+/**
+* The files of the repository `dir` belongs to — tracked and unignored, the way
+* git sees them — or, outside any repository, `dir` walked with fixed excludes.
+*/
+function listUnit(dir, git) {
+	try {
+		const toplevel = git(dir, ["rev-parse", "--show-toplevel"]).trim();
+		if (toplevel) {
+			const root = fs.realpathSync(toplevel);
+			const listed = git(root, [
+				"ls-files",
+				"-z",
+				"--cached",
+				"--others",
+				"--exclude-standard"
+			]);
+			return {
+				root,
+				files: [...new Set(listed.split("\0").filter(Boolean))].filter((relative) => !neverUploaded(relative) && isRegularFile(path.join(root, relative))),
+				fromGit: true
+			};
+		}
+	} catch {}
+	const files = [];
+	const walk = (current, prefix) => {
+		let entries;
+		try {
+			entries = fs.readdirSync(current, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+			if (entry.isDirectory()) {
+				if (WALK_SKIP.has(entry.name) || entry.name.startsWith("dist")) continue;
+				walk(path.join(current, entry.name), relative);
+			} else if (entry.isFile() && !neverUploaded(relative)) files.push(relative);
+		}
+	};
+	walk(dir, "");
+	return {
+		root: dir,
+		files,
+		fromGit: false
+	};
+}
+/** Whether `candidate` is `dir` or inside it. */
+function isWithin(dir, candidate) {
+	const relative = path.relative(dir, candidate);
+	return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+/** The deepest directory containing every path given. */
+function commonAncestor(paths) {
+	let ancestor = paths[0];
+	for (const p of paths.slice(1)) while (!isWithin(ancestor, p)) ancestor = path.dirname(ancestor);
+	return ancestor;
+}
+var DEPENDENCY_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies"
+];
+/**
+* Directories outside every unit that a unit's `package.json` files link to
+* with `link:` or `file:`.
+*
+* `@rebasepro/*` links are not followed. They point at a local framework
+* checkout, which is not the project's source and would drag a whole monorepo
+* into the archive; a rebuild moves those packages to a published release
+* anyway.
+*/
+function externalLinkTargets(units) {
+	const targets = /* @__PURE__ */ new Set();
+	for (const unit of units) for (const relative of unit.files) {
+		if (path.posix.basename(relative) !== "package.json") continue;
+		let manifest;
+		try {
+			manifest = JSON.parse(fs.readFileSync(path.join(unit.root, relative), "utf8"));
+		} catch {
+			continue;
+		}
+		if (typeof manifest !== "object" || manifest === null) continue;
+		for (const field of DEPENDENCY_FIELDS) {
+			const deps = manifest[field];
+			if (typeof deps !== "object" || deps === null) continue;
+			for (const [name, spec] of Object.entries(deps)) {
+				if (name.startsWith("@rebasepro/") || typeof spec !== "string") continue;
+				const match = /^(?:link|file):(.+)$/.exec(spec);
+				if (!match) continue;
+				const target = path.resolve(unit.root, path.posix.dirname(relative), match[1]);
+				let real;
+				try {
+					real = fs.realpathSync(target);
+					if (!fs.statSync(real).isDirectory()) continue;
+				} catch {
+					continue;
+				}
+				if (!units.some((u) => isWithin(u.root, real))) targets.add(real);
+			}
+		}
+	}
+	return [...targets];
+}
+/**
+* The files a source upload carries, and where they are rooted.
+*
+* The project's repository first — or the project walked, outside git. Then
+* every repository a local `link:`/`file:` dependency reaches outside it, until
+* nothing new is reached, rooted together at their deepest common directory.
+* That is dadaki's shape: its Rebase project is a repository of its own, nested
+* inside the editor's repository (which ignores it), and its frontend links
+* `../../packages/editor` from there. A listing of the project's repository
+* alone rebuilt into "Rollup failed to resolve import @dadaki/editor".
+*
+* Paths are resolved through `realpath` first: git reports its top level with
+* symlinks resolved (`/private/var/…` for a macOS temp directory), and a
+* project path computed against the unresolved one would climb out of the
+* archive with `../`.
+*/
+function listSourceFiles(projectRoot, git = runGit) {
+	const realRoot = fs.realpathSync(projectRoot);
+	const units = [listUnit(realRoot, git)];
+	for (let reached = externalLinkTargets(units); reached.length > 0; reached = externalLinkTargets(units)) for (const target of reached) {
+		if (units.some((u) => isWithin(u.root, target))) continue;
+		units.push(listUnit(target, git));
+	}
+	const root = commonAncestor(units.map((u) => u.root));
+	const files = /* @__PURE__ */ new Set();
+	for (const unit of units) {
+		const prefix = toPosix(path.relative(root, unit.root));
+		for (const file of unit.files) files.add(prefix ? `${prefix}/${file}` : file);
+	}
+	return {
+		root,
+		files: [...files].sort(),
+		projectPath: toPosix(path.relative(root, realRoot)),
+		fromGit: units.every((u) => u.fromGit)
+	};
+}
+/**
+* Pack a listing into a gzipped tarball at `outPath`.
+*
+* The list goes to tar as a NUL-separated file (`--null -T`), so a path with a
+* space or a newline in it is one path. `--no-xattrs` and `COPYFILE_DISABLE`
+* keep macOS's extended attributes and AppleDouble `._*` sidecars out of the
+* archive, as `packBundle` does; GNU tar accepts both. Every path handed to tar
+* is absolute, because GNU tar resolves a `-T` file after it has applied `-C`.
+*/
+function packSource(listing, outPath) {
+	const listPath = `${outPath}.files`;
+	fs.writeFileSync(listPath, listing.files.map((file) => `${file}\0`).join(""));
+	return new Promise((resolve, reject) => {
+		const child = spawn("tar", [
+			"-czf",
+			path.resolve(outPath),
+			"--no-xattrs",
+			"--null",
+			"-C",
+			listing.root,
+			"-T",
+			path.resolve(listPath)
+		], {
+			stdio: [
+				"ignore",
+				"ignore",
+				"pipe"
+			],
+			env: {
+				...process.env,
+				COPYFILE_DISABLE: "1"
+			}
+		});
+		let stderr = "";
+		child.stderr.on("data", (chunk) => stderr += String(chunk));
+		child.on("error", reject);
+		child.on("close", (code) => code === 0 ? resolve() : reject(new Error(stderr.trim() || `tar exited ${code}`)));
+	}).finally(() => fs.rmSync(listPath, { force: true }));
+}
+/** Upload a source archive; returns the control plane's id for it. */
+async function uploadRebuildSource(url, token, projectId, tarPath) {
+	const bytes = fs.readFileSync(tarPath);
+	const res = await fetch(`${url}/api/functions/deploy/source/upload?projectId=${encodeURIComponent(projectId)}`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/gzip",
+			"User-Agent": cliUserAgent()
+		},
+		body: bytes
+	});
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`the upload was refused (${res.status}): ${body || res.statusText}`);
+	}
+	const data = await res.json();
+	const sourceId = typeof data === "object" && data !== null && "sourceId" in data ? data.sourceId : void 0;
+	if (typeof sourceId !== "string" || !/^[0-9a-f]{32}$/i.test(sourceId)) throw new Error("the control plane did not return a source id");
+	return sourceId;
+}
+/** The env files Vite reads for a production build, lowest precedence first. */
+var PRODUCTION_ENV_FILES = [
+	".env",
+	".env.local",
+	".env.production",
+	".env.production.local"
+];
+/**
+* The `VITE_*` values a rebuild of this project's frontend needs.
+*
+* The `.env` files are never uploaded, so the values a static app is built with
+* have to travel separately — and only the `VITE_*` ones, which Vite inlines
+* into the client bundle and are public by construction. Nothing else is read.
+*
+* Read the way Vite reads them for `vite build`: `.env`, `.env.local`,
+* `.env.production`, `.env.production.local`, later winning — from the project
+* root, then from each static app's own `root`, which is where its Vite config
+* usually points. `process.env` wins over every file, as it does in Vite.
+*
+* `VITE_API_URL` is the one exception, taken from `process.env` only.
+* `staticBuildEnv` sets it to `process.env.VITE_API_URL ?? ""` for every
+* static build, so a value in a `.env` file never reaches a deployed bundle —
+* it is the `http://localhost:3001` of local development. Sending it would make
+* the rebuild bake in exactly the address the local build refuses to.
+*/
+function collectBuildEnv(projectRoot, appRoots, env = process.env) {
+	const collected = {};
+	const seen = /* @__PURE__ */ new Set();
+	for (const dir of [projectRoot, ...appRoots.map((root) => path.resolve(projectRoot, root))]) {
+		const resolved = path.resolve(dir);
+		if (seen.has(resolved) || !fs.existsSync(resolved)) continue;
+		seen.add(resolved);
+		for (const name of PRODUCTION_ENV_FILES) {
+			let parsed;
+			try {
+				parsed = dotenv.parse(fs.readFileSync(path.join(resolved, name), "utf8"));
+			} catch {
+				continue;
+			}
+			for (const [key, value] of Object.entries(parsed)) if (key.startsWith("VITE_")) collected[key] = value;
+		}
+	}
+	delete collected.VITE_API_URL;
+	for (const [key, value] of Object.entries(env)) if (key.startsWith("VITE_") && value !== void 0) collected[key] = value;
+	return collected;
+}
+/** The `root` of every static app a manifest declares, in declaration order. */
+function staticAppRoots(manifest) {
+	if (!manifest) return [];
+	const roots = [];
+	for (const app of Object.values(manifest.apps)) if (app.type === "static" && typeof app.root === "string" && app.root !== "") roots.push(app.root);
+	return roots;
+}
+var DEFAULT_STEPS = {
+	list: (projectRoot) => listSourceFiles(projectRoot),
+	pack: packSource,
+	upload: uploadRebuildSource
+};
+/**
+* List, pack and upload the project's source. Never throws.
+*
+* Returns what the trigger should carry, or null — after a warning saying why
+* and what it costs — when the source could not be sent. The caller deploys
+* either way.
+*/
+async function prepareRebuildSource(opts) {
+	const steps = {
+		...DEFAULT_STEPS,
+		...opts.steps
+	};
+	const maxBytes = opts.maxBytes ?? 104857600;
+	const tarPath = path.join(os.tmpdir(), `rebase-rebuild-src-${process.pid}-${Date.now()}.tar.gz`);
+	const cost = "Platform upgrades will not rebuild this project until a later deploy uploads its source.";
+	try {
+		const listing = steps.list(opts.projectRoot);
+		await steps.pack(listing, tarPath);
+		const size = fs.statSync(tarPath).size;
+		const mb = (bytes) => (bytes / 1024 / 1024).toFixed(1);
+		if (size > maxBytes) {
+			opts.warn(`The project source is ${mb(size)} MB compressed, over the ${Math.round(maxBytes / 1024 / 1024)} MB upload limit, so it was not uploaded. ${cost}`, listing.fromGit ? "Stop tracking large assets and build output in git, or pass --no-source to skip it on purpose." : "Initialise a git repository with a .gitignore to choose what is source, or pass --no-source.");
+			return null;
+		}
+		opts.progress(`  Uploading source (${listing.files.length} files, ${mb(size)} MB)...`);
+		return {
+			sourceId: await steps.upload(opts.url, opts.token, opts.projectId, tarPath),
+			projectPath: listing.projectPath,
+			buildEnv: collectBuildEnv(opts.projectRoot, staticAppRoots(opts.manifest))
+		};
+	} catch (err) {
+		opts.warn(`The project source was not uploaded: ${err instanceof Error ? err.message : String(err)}. ${cost}`, "The deploy continues with the bundle alone.");
+		return null;
+	} finally {
+		fs.rmSync(tarPath, { force: true });
+	}
+}
+//#endregion
 //#region src/commands/cloud/deploy.ts
 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));
 }
@@ -15256,7 +15658,7 @@ function progress(line) {
 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.");
+	if (bytes.length > 104857600) 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.");
 	progress(chalk.gray(`  Uploading source (${sizeMb} MB)...`));
 	const res = await fetch(`${url}/api/functions/deploy/upload?projectId=${encodeURIComponent(projectId)}`, {
 		method: "POST",
@@ -15303,6 +15705,7 @@ async function deployBundle(opts) {
 			bundleDir = staticDir;
 			await uploadAndTrigger({
 				...opts,
+				projectRoot,
 				bundleDir,
 				appName: target.name
 			});
@@ -15338,6 +15741,7 @@ async function deployBundle(opts) {
 	}
 	await uploadAndTrigger({
 		...opts,
+		projectRoot,
 		bundleDir
 	});
 }
@@ -15352,7 +15756,7 @@ async function deployBundle(opts) {
 * bundle with no site in it.
 */
 async function uploadAndTrigger(opts) {
-	const { client, url, projectId, projectRef, bundleDir } = opts;
+	const { client, url, projectId, projectRef, projectRoot, bundleDir } = opts;
 	const manifest = readBundleManifest(bundleDir);
 	if (manifest.hooks?.native) {
 		const names = (manifest.hooks.nativeModules ?? []).map((m) => m.name).join(", ");
@@ -15377,10 +15781,22 @@ async function uploadAndTrigger(opts) {
 		console.log("");
 		console.log(`  🚀 Triggering managed deployment for ${chalk.bold(projectRef)} (schema ${manifest.schemaVersion})...`);
 	}
-	let declaredApps = [];
+	let projectManifest;
 	try {
-		declaredApps = declaredAppsFrom(loadManifest(process.cwd()).manifest);
+		projectManifest = loadManifest(projectRoot).manifest;
 	} catch {}
+	const declaredApps = declaredAppsFrom(projectManifest);
+	let rebuildSource = null;
+	if (opts.uploadSource && manifest.kind !== "static" && await platformRebuildsOff(client, projectId)) progress(chalk.gray("  Platform rebuilds are off for this project, so its source is not uploaded (turn them on with `rebase cloud settings set --platform-rebuilds on`)."));
+	else if (opts.uploadSource && manifest.kind !== "static") rebuildSource = await prepareRebuildSource({
+		projectRoot,
+		url,
+		token,
+		projectId,
+		manifest: projectManifest,
+		progress: (line) => progress(chalk.gray(line)),
+		warn
+	});
 	const body = bundleDeployBody({
 		projectId,
 		bundleId,
@@ -15388,7 +15804,9 @@ async function uploadAndTrigger(opts) {
 		app: opts.appName,
 		message: opts.message,
 		declaredApps,
-		commit: bundleCommit(process.cwd())
+		commit: bundleCommit(projectRoot),
+		rebuildSource,
+		allowFrameworkDowngrade: opts.allowDowngrade
 	});
 	let deploymentId;
 	let managed;
@@ -15398,6 +15816,8 @@ async function uploadAndTrigger(opts) {
 		deploymentId = String(res.deployment.id);
 		managed = res.managed === true;
 	} catch (e) {
+		const refusal = intakeRefusal(e);
+		if (refusal) fail(refusal.message, refusal.hint, refusal.code);
 		reportError(e, "Managed deploy failed to start");
 	}
 	if (!opts.follow) {
@@ -15408,6 +15828,7 @@ async function uploadAndTrigger(opts) {
 			success: true,
 			deploymentId,
 			managed,
+			sourceUploaded: rebuildSource !== null,
 			following: false
 		});
 		return;
@@ -15427,6 +15848,7 @@ async function uploadAndTrigger(opts) {
 		success: true,
 		deploymentId,
 		managed,
+		sourceUploaded: rebuildSource !== null,
 		following: true,
 		status
 	});
@@ -15696,6 +16118,8 @@ var DEPLOY_FLAGS = {
 	"--bundle-dir": String,
 	"--skip-type-check": Boolean,
 	"--eject": Boolean,
+	"--no-source": Boolean,
+	"--allow-downgrade": Boolean,
 	"-m": "--message"
 };
 /**
@@ -15760,6 +16184,7 @@ async function deployCommand(rawArgs, projectRef) {
 	const startedAt = Date.now();
 	const { flags: args, appName } = resolveDeployArgs(rawArgs);
 	if (args["--wait"] && args["--no-follow"]) fail("--wait and --no-follow ask for opposite things.", "`deploy` follows by default — pass neither, or `--no-follow` to return as soon as the build is triggered.", "usage");
+	if (args["--source"] && args["--no-source"]) fail("--source and --no-source ask for opposite things.", "`--source <path>` builds a container image from a directory; `--no-source` skips uploading the source beside a managed bundle. Pass one.", "usage");
 	const { client, url } = await requireClient(rawArgs);
 	const projectId = await resolveProjectRef(projectRef, client);
 	await requirePaymentMethod(client, projectId);
@@ -15777,7 +16202,9 @@ async function deployCommand(rawArgs, projectRef) {
 			appName,
 			skipTypeCheck: args["--skip-type-check"] === true,
 			follow: args["--no-follow"] !== true,
-			timeoutMs: resolveDeployTimeout(args["--timeout"])
+			timeoutMs: resolveDeployTimeout(args["--timeout"]),
+			uploadSource: args["--no-source"] !== true,
+			allowDowngrade: args["--allow-downgrade"] === true
 		});
 		return;
 	}
@@ -15909,10 +16336,62 @@ function resolveTriggerFailure(e) {
 		fail(blocking?.id ? `Deployment ${blocking.id} is already in progress for this project${blocking.triggerSource && blocking.triggerSource !== "unknown" ? `, triggered from the ${blocking.triggerSource}` : ""}${blocking.createdAt ? ` at ${fmtDate(blocking.createdAt)}` : ""}.` : "A deployment is already in progress for this project.", blocking?.id ? `Follow it with \`rebase cloud logs -f\`, or stop it with \`rebase cloud cancel ${blocking.id}\`.` : "Follow it with `rebase cloud logs -f`.", "deploy_in_progress");
 	}
 	if (err?.status === 402) fail(err.message || "Payment required before deploying.", "Attach a card once with `rebase cloud billing setup`, then deploy again.", "payment_required");
-	if (err?.status === 400 && err.details?.intakeCode) fail(err.message || "This bundle was refused.", err.details.hint ?? "Run `rebase cloud compute` to see what this project reserves.", err.details.intakeCode);
+	const refusal = intakeRefusal(e);
+	if (refusal) fail(refusal.message, refusal.hint, refusal.code);
 	reportError(e, "Failed to trigger deployment");
 }
 /**
+* Whether the project's owner turned platform rebuilds off.
+*
+* Only an explicit `false` counts: a project row that predates the switch, or
+* one that could not be read, is on — which is the default, and the control
+* plane refuses an upload it should not have anyway.
+*/
+async function platformRebuildsOff(client, projectId) {
+	try {
+		const row = await client.data.collection("projects").findById(projectId);
+		return typeof row === "object" && row !== null && "platformRebuilds" in row && row.platformRebuilds === false;
+	} catch {
+		return false;
+	}
+}
+/**
+* An intake refusal, which is a decision about what was deployed rather than a
+* transport error — or undefined for anything else.
+*
+* It carries a stable code in `details.intakeCode` and usually a remedy in
+* `details.hint`, and both used to be discarded: the deploy printed `Failed to
+* trigger deployment (400): …` and threw the hint away. The managed path, where
+* bundles are refused, never looked for either. Both paths answer through this
+* now, in the three-argument shape `fail` takes, so `--json` carries the code
+* and a person sees the fix.
+*
+* A downgrade gets one more line, because its two remedies are both in this
+* CLI: move the project forward, or say the step back is meant.
+*/
+function intakeRefusal(e) {
+	if (typeof e !== "object" || e === null) return void 0;
+	const status = "status" in e && typeof e.status === "number" ? e.status : void 0;
+	const details = "details" in e && typeof e.details === "object" && e.details !== null ? e.details : void 0;
+	const code = details && "intakeCode" in details && typeof details.intakeCode === "string" ? details.intakeCode : void 0;
+	if (status === void 0 || status < 400 || status >= 500 || !code) return void 0;
+	const message = "message" in e && typeof e.message === "string" && e.message !== "" ? e.message : "This bundle was refused.";
+	const serverHint = details && "hint" in details && typeof details.hint === "string" && details.hint !== "" ? details.hint : void 0;
+	if (code === "FRAMEWORK_DOWNGRADE") {
+		const remedy = "Run `rebase upgrade` to move this project's @rebasepro packages forward and deploy again, or pass `--allow-downgrade` to deploy the older release on purpose.";
+		return {
+			message,
+			hint: serverHint ? `${serverHint}\n  ${remedy}` : remedy,
+			code
+		};
+	}
+	return {
+		message,
+		hint: serverHint ?? "Run `rebase cloud compute` to see what this project reserves.",
+		code
+	};
+}
+/**
 * Poll a deployment record and print new log output as it arrives. Returns the
 * terminal status; a non-success still exits non-zero, as it always has.
 *
@@ -17033,7 +17512,7 @@ function printExtensionsHelp() {
 * `rebase cloud settings` — a project's editable configuration.
 *
 *   settings                 Show the current settings
-*   settings set [flags]     Update name / branch / repo / subdomain
+*   settings set [flags]     Update name / branch / repo / subdomain / platform rebuilds
 *
 * These are plain `projects` updates. A subdomain change is validated against
 * `check-subdomain` up front so the CLI fails with the real reason rather than a
@@ -17080,7 +17559,8 @@ async function showSettings(rawArgs) {
 				["Branch", p.gitBranch],
 				["Custom domain", p.customDomain],
 				["Provider", p.provider],
-				["Region", p.region]
+				["Region", p.region],
+				["Platform rebuilds", p.platformRebuilds === false ? "off" : "on"]
 			]);
 			console.log("");
 		}, {
@@ -17091,12 +17571,20 @@ async function showSettings(rawArgs) {
 			gitBranch: p.gitBranch ?? null,
 			customDomain: p.customDomain ?? null,
 			provider: p.provider ?? null,
-			region: p.region ?? null
+			region: p.region ?? null,
+			platformRebuilds: p.platformRebuilds !== false
 		});
 	} catch (e) {
 		reportError(e, "Failed to load settings");
 	}
 }
+/** `on`/`off` (or `true`/`false`) as a boolean, or null for anything else. */
+function parseOnOff(value) {
+	const v = value.trim().toLowerCase();
+	if (v === "on" || v === "true") return true;
+	if (v === "off" || v === "false") return false;
+	return null;
+}
 /** Build the update patch from the flags actually supplied (pure/testable). */
 function buildSettingsPatch(args) {
 	const patch = {};
@@ -17104,6 +17592,7 @@ function buildSettingsPatch(args) {
 	if (args.subdomain !== void 0) patch.subdomain = args.subdomain.toLowerCase();
 	if (args.repo !== void 0) patch.gitRepoUrl = args.repo;
 	if (args.branch !== void 0) patch.gitBranch = args.branch;
+	if (args.platformRebuilds !== void 0) patch.platformRebuilds = args.platformRebuilds;
 	return patch;
 }
 /** What `rebase cloud settings set` parses. Its page is the group's own. */
@@ -17111,7 +17600,8 @@ var SET_SETTINGS_FLAGS = {
 	"--name": String,
 	"--subdomain": String,
 	"--repo": String,
-	"--branch": String
+	"--branch": String,
+	"--platform-rebuilds": String
 };
 async function setSettings(rawArgs) {
 	const { flags: args } = parseCloudArgs({
@@ -17124,15 +17614,22 @@ async function setSettings(rawArgs) {
 	const { client } = await requireClient(rawArgs);
 	const projectId = await requireProject(rawArgs, client);
 	const projectRef = displayProjectRef(rawArgs);
+	let platformRebuilds;
+	if (args["--platform-rebuilds"] !== void 0) {
+		const parsed = parseOnOff(args["--platform-rebuilds"]);
+		if (parsed === null) fail(`--platform-rebuilds takes on or off (got "${args["--platform-rebuilds"]}").`, void 0, "usage");
+		platformRebuilds = parsed;
+	}
 	const patch = buildSettingsPatch({
 		name: args["--name"],
 		subdomain: args["--subdomain"],
 		repo: args["--repo"],
-		branch: args["--branch"]
+		branch: args["--branch"],
+		platformRebuilds
 	});
-	if (Object.keys(patch).length === 0) fail("Nothing to update.", "Pass --name, --subdomain, --repo, or --branch.", "usage");
+	if (Object.keys(patch).length === 0) fail("Nothing to update.", "Pass --name, --subdomain, --repo, --branch, or --platform-rebuilds.", "usage");
 	try {
-		if (patch.subdomain) {
+		if (typeof patch.subdomain === "string" && patch.subdomain) {
 			const check = await client.functions.invoke("check-subdomain", { subdomain: patch.subdomain }).catch(() => void 0);
 			if (check && !check.available) fail(`Subdomain "${patch.subdomain}" is not available${check.reason ? ` (${check.reason})` : ""}.`, void 0, "subdomain_taken");
 		}
@@ -17152,7 +17649,7 @@ function printSettingsHelp() {
 		title: "Project configuration",
 		actions: [{
 			action: "show",
-			description: "Name, subdomain, repository and branch as recorded"
+			description: "Name, subdomain, repository, branch and platform rebuilds as recorded"
 		}, {
 			action: "set",
 			description: "Change one or more of them",
@@ -17160,7 +17657,8 @@ function printSettingsHelp() {
 				["--name <name>", "Display name"],
 				["--subdomain <sub>", "The <slug>.rebase.website host"],
 				["--repo <git url>", "Repository to build from"],
-				["--branch <branch>", "Branch to build"]
+				["--branch <branch>", "Branch to build"],
+				["--platform-rebuilds <on|off>", "Rebuild this app on new framework releases (default on)"]
 			]
 		}]
 	});
@@ -18577,6 +19075,8 @@ var ACTION_HELP = {
 			["--bundle-dir <path>", "Deploy a bundle that is already built"],
 			["--source <path>", "Upload this directory and build a container image from it"],
 			["--skip-type-check", "Compile without type checking, as `rebase build` does"],
+			["--no-source", "Do not upload the project's source beside a backend bundle"],
+			["--allow-downgrade", "Deploy a bundle built on an older framework release than the project runs"],
 			["--eject", "Leave the managed runtime on purpose (ejects to a container image)"]
 		],
 		examples: [
@@ -18584,7 +19084,12 @@ var ACTION_HELP = {
 			"rebase cloud deploy web --message \"add search\"",
 			"rebase cloud deploy --timeout 300 --json"
 		],
-		notes: ["A project whose rebase.json declares runtime: managed deploys a bundle without --bundle.", "--source on a managed project is refused: it would swap the project onto a container image."]
+		notes: [
+			"A project whose rebase.json declares runtime: managed deploys a bundle without --bundle.",
+			"--source on a managed project is refused: it would swap the project onto a container image.",
+			"A backend bundle deploy also uploads the project's source (what git tracks, never a .env), so a platform upgrade can rebuild it on a newer release. If it is over 100 MB or the upload fails, the deploy goes on without it and says so.",
+			"A bundle older than the release the project runs is refused as FRAMEWORK_DOWNGRADE. Run `rebase upgrade` and deploy again, or pass --allow-downgrade."
+		]
 	},
 	logs: {
 		command: "cloud logs",
@@ -19444,7 +19949,7 @@ function printCloudHelp() {
 * a mobile app with no repo relationship at all — an ordinary thing rather than
 * a special case.
 */
-function printHelp$1() {
+function printHelp$2() {
 	console.log(`
 ${chalk.bold("rebase apps")} — the apps this repository contributes
 
@@ -19467,7 +19972,7 @@ var APPS_SUBCOMMANDS = [
 ];
 async function appsCommand(subcommand, rawArgs = []) {
 	if (!subcommand || subcommand === "--help" || wantsHelp(rawArgs)) {
-		printHelp$1();
+		printHelp$2();
 		return;
 	}
 	const { flags: args, positionals } = parseCommandArgs({
@@ -19629,6 +20134,1000 @@ function loadManifestOrExit(projectRoot, asJson = false) {
 	}
 }
 //#endregion
+//#region src/upgrade.ts
+/**
+* Moving a project's `@rebasepro/*` pins to one release.
+*
+* Every `@rebasepro/*` package ships at one version, and a project declares them
+* in several `package.json` files — the root, `backend/`, `frontend/`,
+* `config/`, and whatever else the repository holds. Bumping them by hand means
+* finding every one, keeping each range's `^` or `~`, and noticing the override
+* that quietly wins over all of them. `rebase upgrade` is that job, done the same
+* way every time; the control plane runs it too, when it rebuilds a managed
+* project on a newer release.
+*
+* Everything here is pure file work, so it can be tested against a temporary
+* directory: which specs move, the rewrite itself, and what overrides say. The
+* command in `commands/upgrade.ts` adds the registry lookup, the install and the
+* printing.
+*
+* ## The rewrite is textual
+*
+* A `package.json` is authored. Parsing it and writing `JSON.stringify` back
+* reformats the file, reorders nothing but reindents everything, and drops a
+* trailing newline or a two-space indent somebody chose — a one-line version
+* bump that arrives as a whole-file diff. So the file is scanned for the exact
+* byte range of each value, only those bytes are replaced, and the result is
+* parsed again and compared against what was intended. A file whose rewrite
+* does not parse back to exactly the intended values is not written.
+*/
+/** The dependency blocks a pin is moved in. `peerDependencies` is not one. */
+var PIN_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies"
+];
+/** The package whose published versions stand for the release as a whole. */
+var RELEASE_PACKAGE = "@rebasepro/cli";
+/** `MAJOR.MINOR.PATCH`, with an optional prerelease and build, and nothing else. */
+var SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/** Whether `value` is one exact version — `0.21.0`, `0.21.1-canary.g8c5a265`. */
+function isExactVersion(value) {
+	return SEMVER.test(value);
+}
+/** An error that carries the `--json` envelope's code and a remedy. */
+var UpgradeError = class extends Error {
+	code;
+	hint;
+	constructor(message, code, hint) {
+		super(message);
+		this.code = code;
+		this.hint = hint;
+		this.name = "UpgradeError";
+	}
+};
+/**
+* What a dependency spec is, as far as moving it goes.
+*
+* Only a plain version is moved, because only a plain version has an obvious
+* answer: `^0.19.1` becomes `^0.21.0`. A `>=` floor, a `||` union or a partial
+* `^0.19` could each be rewritten several ways, and a tag or a workspace link
+* already means something other than "this release" — so each is reported with
+* its reason and left as written.
+*/
+function classifySpec(spec) {
+	const movable = /^([\^~]?)(.+)$/.exec(spec);
+	if (movable && isExactVersion(movable[2])) return {
+		kind: "movable",
+		prefix: movable[1],
+		version: movable[2]
+	};
+	for (const protocol of [
+		"link:",
+		"file:",
+		"portal:"
+	]) if (spec.startsWith(protocol)) return {
+		kind: "local",
+		protocol
+	};
+	return {
+		kind: "other",
+		reason: otherReason(spec)
+	};
+}
+function otherReason(spec) {
+	const trimmed = spec.trim();
+	if (trimmed.startsWith("workspace:")) return "a workspace: link, resolved inside this repository rather than from the registry";
+	if (trimmed.startsWith("npm:")) return "an npm: alias; move the aliased version by hand";
+	if (/^(git\+|git:|github:|gitlab:|bitbucket:|git@)/.test(trimmed) || /^https?:\/\//.test(trimmed)) return "a git or URL dependency, not a registry version";
+	if (trimmed === "" || trimmed === "*" || /^[xX]$/.test(trimmed)) return "a wildcard, which already takes whatever the registry has";
+	if (trimmed.includes("||")) return "a union of ranges, with no single version to move";
+	if (/^[<>=]/.test(trimmed) || /\s-\s/.test(trimmed)) return "a comparator range, with no single version to move";
+	if (/^[\^~]?v?\d/.test(trimmed)) return "not a plain MAJOR.MINOR.PATCH version";
+	return "a dist-tag, not a version";
+}
+/**
+* The `@rebasepro/*` package an override key targets, or null.
+*
+* pnpm and npm key an override by name, optionally narrowed: `@rebasepro/x@<1`,
+* `parent>@rebasepro/x`; yarn's `resolutions` by a path, `**\/@rebasepro/x`. The
+* target is the last segment either way.
+*/
+function overrideTarget(key) {
+	const match = /(?:^|[/>])(@rebasepro\/[^/@>\s]+)(?:@[^/>]*)?$/.exec(key);
+	return match ? match[1] : null;
+}
+/**
+* Directories the walk never enters: installed packages, build output (`dist`,
+* `dist-bundle`, `dist-bundle-admin`, …) and anything hidden (`.git`,
+* `.rebase`, an editor's worktrees). None of them hold a manifest anybody
+* authored for this project, and `dist-bundle/package.json` in particular is a
+* generated copy that `rebase build` rewrites anyway.
+*/
+function skipDirectory(name) {
+	return name === "node_modules" || name.startsWith("dist") || name.startsWith(".");
+}
+/** Every `package.json` and `pnpm-workspace.yaml` under the project root. */
+function discoverProjectFiles(projectRoot) {
+	const found = {
+		packageJsons: [],
+		workspaceYamls: []
+	};
+	const walk = (dir) => {
+		let entries;
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+		for (const entry of entries) {
+			const full = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (!skipDirectory(entry.name)) walk(full);
+			} else if (entry.isFile()) {
+				if (entry.name === "package.json") found.packageJsons.push(full);
+				else if (entry.name === "pnpm-workspace.yaml") found.workspaceYamls.push(full);
+			}
+		}
+	};
+	walk(projectRoot);
+	return found;
+}
+/** Project-relative, POSIX. What every file path in the output looks like. */
+function relativeTo(projectRoot, absolute) {
+	return path.relative(projectRoot, absolute).split(path.sep).join("/");
+}
+/**
+* Work out every change the upgrade makes, without writing anything.
+*
+* `--dry-run` prints this; a real run writes `writes` and nothing else.
+*/
+function planUpgrade(projectRoot, target, options = {}) {
+	if (!isExactVersion(target)) throw new UpgradeError(`"${target}" is not an exact version.`, "target_invalid");
+	const plan = {
+		target,
+		changed: [],
+		skipped: [],
+		overrides: [],
+		unreadable: [],
+		writes: []
+	};
+	const files = discoverProjectFiles(projectRoot);
+	for (const absolute of files.packageJsons) {
+		const file = relativeTo(projectRoot, absolute);
+		const original = fs.readFileSync(absolute, "utf8");
+		const content = planPackageJson(file, original, target, options, plan);
+		if (content !== null && content !== original) plan.writes.push({
+			file,
+			absolute,
+			content
+		});
+	}
+	for (const absolute of files.workspaceYamls) {
+		const file = relativeTo(projectRoot, absolute);
+		const original = fs.readFileSync(absolute, "utf8");
+		const content = planWorkspaceYaml(file, original, target, options, plan);
+		if (content !== original) plan.writes.push({
+			file,
+			absolute,
+			content
+		});
+	}
+	return plan;
+}
+/** Write what the plan changes. Nothing else on disk is touched. */
+function applyUpgradePlan(plan) {
+	for (const write of plan.writes) fs.writeFileSync(write.absolute, write.content, "utf8");
+}
+/** Override blocks in a `package.json`, as paths from the root object. */
+var JSON_OVERRIDE_BLOCKS = [
+	["pnpm", "overrides"],
+	["overrides"],
+	["resolutions"]
+];
+function planPackageJson(file, original, target, options, plan) {
+	const bom = original.startsWith("") ? "" : "";
+	const text = original.slice(bom.length);
+	let parsed;
+	let tree;
+	try {
+		parsed = JSON.parse(text);
+		tree = scanJson(text);
+	} catch (err) {
+		plan.unreadable.push({
+			file,
+			reason: `not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+		});
+		return null;
+	}
+	if (!isRecord(parsed) || tree.kind !== "object") {
+		plan.unreadable.push({
+			file,
+			reason: "not a JSON object"
+		});
+		return null;
+	}
+	const expected = structuredClone(parsed);
+	const edits = [];
+	/** Override members to remove, as [block path, key]. */
+	const removals = [];
+	for (const field of PIN_FIELDS) {
+		const block = memberValue(tree, [field]);
+		if (block?.kind !== "object") continue;
+		for (const member of block.members) {
+			if (!member.key.startsWith("@rebasepro/")) continue;
+			if (member.value.kind !== "string") {
+				plan.skipped.push({
+					file,
+					name: member.key,
+					field,
+					spec: text.slice(member.value.start, member.value.end),
+					reason: "not a string"
+				});
+				continue;
+			}
+			const spec = member.value.value;
+			const cls = classifySpec(spec);
+			if (cls.kind === "movable") {
+				const to = `${cls.prefix}${target}`;
+				if (to === spec) continue;
+				edits.push({
+					start: member.value.start,
+					end: member.value.end,
+					replacement: JSON.stringify(to)
+				});
+				setPath(expected, [field, member.key], to);
+				plan.changed.push({
+					file,
+					name: member.key,
+					field,
+					from: spec,
+					to
+				});
+			} else {
+				const reason = cls.kind === "local" ? `a local ${cls.protocol} path, which points at a checkout on this machine rather than a release` : cls.reason;
+				plan.skipped.push({
+					file,
+					name: member.key,
+					field,
+					spec,
+					reason
+				});
+			}
+		}
+	}
+	for (const blockPath of JSON_OVERRIDE_BLOCKS) {
+		const block = memberValue(tree, blockPath);
+		if (block?.kind !== "object") continue;
+		const field = blockPath.join(".");
+		for (const member of block.members) {
+			if (!overrideTarget(member.key)) continue;
+			if (member.value.kind !== "string") {
+				plan.skipped.push({
+					file,
+					name: member.key,
+					field,
+					spec: text.slice(member.value.start, member.value.end),
+					reason: "a nested override, which has no single version to move; edit it by hand"
+				});
+				continue;
+			}
+			const spec = member.value.value;
+			const cls = classifySpec(spec);
+			if (cls.kind === "movable") {
+				const to = `${cls.prefix}${target}`;
+				if (to === spec) continue;
+				edits.push({
+					start: member.value.start,
+					end: member.value.end,
+					replacement: JSON.stringify(to)
+				});
+				setPath(expected, [...blockPath, member.key], to);
+				plan.overrides.push({
+					file,
+					name: member.key,
+					spec,
+					action: "bumped",
+					to
+				});
+			} else if (cls.kind === "local") if (options.dropLocalOverrides) {
+				removals.push([blockPath, member.key]);
+				deletePath(expected, [...blockPath, member.key]);
+				plan.overrides.push({
+					file,
+					name: member.key,
+					spec,
+					action: "removed-local"
+				});
+			} else plan.overrides.push({
+				file,
+				name: member.key,
+				spec,
+				action: "kept-local"
+			});
+			else plan.skipped.push({
+				file,
+				name: member.key,
+				field,
+				spec,
+				reason: cls.reason
+			});
+		}
+	}
+	if (edits.length === 0 && removals.length === 0) return original;
+	let next = applyEdits(text, edits);
+	for (const [blockPath, key] of removals) next = removeJsonMember(next, blockPath, key);
+	for (const blockPath of JSON_OVERRIDE_BLOCKS) {
+		if (!removals.some(([removedFrom]) => removedFrom === blockPath)) continue;
+		for (let depth = blockPath.length; depth > 0; depth--) {
+			const containerPath = blockPath.slice(0, depth);
+			const node = memberValue(scanJson(next), containerPath);
+			if (node?.kind !== "object" || node.members.length > 0) break;
+			next = removeJsonMember(next, containerPath.slice(0, -1), containerPath[containerPath.length - 1]);
+			deletePath(expected, containerPath);
+		}
+	}
+	let reparsed;
+	try {
+		reparsed = JSON.parse(next);
+	} catch {
+		reparsed = void 0;
+	}
+	if (!isDeepStrictEqual(reparsed, expected)) throw new UpgradeError(`Could not rewrite ${file} without disturbing it; nothing was written.`, "rewrite_failed", "Move its @rebasepro versions by hand, then run `rebase upgrade` again.");
+	return bom + next;
+}
+/**
+* The structure of a JSON document, with where each value starts and ends.
+*
+* `JSON.parse` answers what a file says; this answers where it says it, which is
+* what a rewrite that leaves every other byte alone needs. Throws on anything
+* that is not JSON — callers have already parsed the same text, so that never
+* happens in practice.
+*/
+function scanJson(text) {
+	let i = 0;
+	const WHITESPACE = " 	\n\r";
+	const skipWhitespace = () => {
+		while (i < text.length && WHITESPACE.includes(text[i])) i++;
+	};
+	const unexpected = () => {
+		throw new Error(`unexpected ${i < text.length ? `"${text[i]}"` : "end of input"} at offset ${i}`);
+	};
+	const readString = () => {
+		const start = i;
+		if (text[i] !== "\"") unexpected();
+		i++;
+		while (i < text.length && text[i] !== "\"") i += text[i] === "\\" ? 2 : 1;
+		if (i >= text.length) unexpected();
+		i++;
+		return {
+			kind: "string",
+			start,
+			end: i,
+			value: JSON.parse(text.slice(start, i))
+		};
+	};
+	const readValue = () => {
+		skipWhitespace();
+		const start = i;
+		if (text[i] === "{") {
+			i++;
+			const members = [];
+			skipWhitespace();
+			if (text[i] === "}") {
+				i++;
+				return {
+					kind: "object",
+					start,
+					end: i,
+					members
+				};
+			}
+			for (;;) {
+				skipWhitespace();
+				const key = readString();
+				skipWhitespace();
+				if (text[i] !== ":") unexpected();
+				i++;
+				members.push({
+					key: key.value,
+					keyStart: key.start,
+					value: readValue()
+				});
+				skipWhitespace();
+				if (text[i] === ",") {
+					i++;
+					continue;
+				}
+				if (text[i] === "}") {
+					i++;
+					return {
+						kind: "object",
+						start,
+						end: i,
+						members
+					};
+				}
+				unexpected();
+			}
+		}
+		if (text[i] === "[") {
+			i++;
+			skipWhitespace();
+			if (text[i] === "]") {
+				i++;
+				return {
+					kind: "array",
+					start,
+					end: i
+				};
+			}
+			for (;;) {
+				readValue();
+				skipWhitespace();
+				if (text[i] === ",") {
+					i++;
+					continue;
+				}
+				if (text[i] === "]") {
+					i++;
+					return {
+						kind: "array",
+						start,
+						end: i
+					};
+				}
+				unexpected();
+			}
+		}
+		if (text[i] === "\"") return readString();
+		while (i < text.length && !",:{}[]\"".includes(text[i]) && !WHITESPACE.includes(text[i])) i++;
+		if (i === start) unexpected();
+		return {
+			kind: "scalar",
+			start,
+			end: i
+		};
+	};
+	const root = readValue();
+	skipWhitespace();
+	if (i !== text.length) unexpected();
+	return root;
+}
+/** The value at a path of object keys, or undefined. The last duplicate wins, as in `JSON.parse`. */
+function memberValue(root, keys) {
+	let node = root;
+	for (const key of keys) {
+		if (node?.kind !== "object") return void 0;
+		const members = node.members.filter((m) => m.key === key);
+		node = members[members.length - 1]?.value;
+	}
+	return node;
+}
+/** Apply non-overlapping edits, last first so the earlier offsets stay valid. */
+function applyEdits(text, edits) {
+	let out = text;
+	for (const edit of [...edits].sort((a, b) => b.start - a.start)) out = out.slice(0, edit.start) + edit.replacement + out.slice(edit.end);
+	return out;
+}
+/**
+* Remove one member from the object at `objectPath`, taking its comma with it.
+*
+* Rescans rather than trusting offsets from before an earlier edit. A middle or
+* first member takes everything up to the next key, so the next member inherits
+* its indentation; the last takes the comma and whitespace after the previous
+* value, so the closing brace keeps its line; an only member leaves `{}`.
+*/
+function removeJsonMember(text, objectPath, key) {
+	const container = memberValue(scanJson(text), objectPath);
+	if (container?.kind !== "object") return text;
+	const index = container.members.findIndex((m) => m.key === key);
+	if (index === -1) return text;
+	const members = container.members;
+	const member = members[index];
+	if (members.length === 1) return text.slice(0, container.start + 1) + text.slice(container.end - 1);
+	if (index < members.length - 1) return text.slice(0, member.keyStart) + text.slice(members[index + 1].keyStart);
+	return text.slice(0, members[index - 1].value.end) + text.slice(member.value.end);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function setPath(root, keys, value) {
+	let node = root;
+	for (const key of keys.slice(0, -1)) {
+		const next = node[key];
+		if (!isRecord(next)) return;
+		node = next;
+	}
+	node[keys[keys.length - 1]] = value;
+}
+function deletePath(root, keys) {
+	let node = root;
+	for (const key of keys.slice(0, -1)) {
+		const next = node[key];
+		if (!isRecord(next)) return;
+		node = next;
+	}
+	delete node[keys[keys.length - 1]];
+}
+/** Lines, each without its `\r`, and whether the file used them. */
+function splitLines(text) {
+	return text.split("\n").map((line) => line.endsWith("\r") ? line.slice(0, -1) : line);
+}
+/**
+* A YAML scalar at the start of `rest`: its text, and where that text sits.
+*
+* Double- and single-quoted and plain scalars, which is every shape an override
+* value is written in. A double-quoted one with an escape in it is refused
+* rather than decoded: no version or path needs one, and getting the decoding
+* wrong would rewrite a value this does not understand.
+*/
+function readYamlScalar(rest) {
+	if (rest.startsWith("\"")) {
+		const close = rest.indexOf("\"", 1);
+		if (close === -1 || rest.slice(1, close).includes("\\")) return null;
+		if (!/^\s*(#.*)?$/.test(rest.slice(close + 1))) return null;
+		return {
+			value: rest.slice(1, close),
+			start: 1,
+			end: close
+		};
+	}
+	if (rest.startsWith("'")) {
+		const close = rest.indexOf("'", 1);
+		if (close === -1 || rest[close + 1] === "'") return null;
+		if (!/^\s*(#.*)?$/.test(rest.slice(close + 1))) return null;
+		return {
+			value: rest.slice(1, close),
+			start: 1,
+			end: close
+		};
+	}
+	const comment = rest.search(/\s#/);
+	const plain = (comment === -1 ? rest : rest.slice(0, comment)).trimEnd();
+	if (plain === "" || /^[[{&*!|>%@`]/.test(plain)) return null;
+	return {
+		value: plain,
+		start: 0,
+		end: plain.length
+	};
+}
+/**
+* The top-level `overrides:` block of a `pnpm-workspace.yaml`, read line by line.
+*
+* Deliberately narrow. The file is YAML, and the CLI carries no YAML parser; the
+* shape pnpm documents and every project writes is a block mapping of one
+* scalar per line, which a line reader handles exactly. Anything else in the
+* block is counted rather than guessed at, and an inline `overrides: { … }` is
+* reported as not handled.
+*/
+function readYamlOverrides(lines) {
+	const keyLine = lines.findIndex((line) => /^overrides:\s*(#.*)?$/.test(line));
+	if (keyLine === -1) return null;
+	const block = {
+		keyLine,
+		lines: [],
+		entries: [],
+		otherContent: 0
+	};
+	for (let index = keyLine + 1; index < lines.length; index++) {
+		const line = lines[index];
+		if (line.trim() !== "" && !/^\s/.test(line) && !line.startsWith("#")) break;
+		block.lines.push(index);
+		if (line.trim() === "" || /^\s*#/.test(line)) continue;
+		const entry = /^(\s+)("[^"]*"|'[^']*'|[^\s"'#][^:#]*?)\s*:(\s+|$)/.exec(line);
+		const valueOffset = entry ? entry[0].length : -1;
+		const scalar = entry ? readYamlScalar(line.slice(valueOffset)) : null;
+		if (!entry || !scalar) {
+			block.otherContent++;
+			continue;
+		}
+		const rawKey = entry[2];
+		const key = /^["']/.test(rawKey) ? rawKey.slice(1, -1) : rawKey;
+		block.entries.push({
+			line: index,
+			key,
+			value: scalar.value,
+			valueStart: valueOffset + scalar.start,
+			valueEnd: valueOffset + scalar.end
+		});
+	}
+	return block;
+}
+function planWorkspaceYaml(file, original, target, options, plan) {
+	const lines = splitLines(original);
+	const crlf = original.includes("\r\n");
+	const block = readYamlOverrides(lines);
+	if (!block) {
+		const inline = lines.find((line) => /^overrides:\s*[^\s#]/.test(line));
+		if (inline && inline.includes("@rebasepro/")) plan.skipped.push({
+			file,
+			name: "overrides",
+			field: "overrides",
+			spec: inline.slice(10).trim(),
+			reason: "an inline overrides map, which this does not rewrite; write it as a block, or edit it by hand"
+		});
+		return original;
+	}
+	const next = [...lines];
+	const removed = /* @__PURE__ */ new Set();
+	const expected = /* @__PURE__ */ new Map();
+	for (const entry of block.entries) {
+		if (!overrideTarget(entry.key)) {
+			expected.set(entry.key, entry.value);
+			continue;
+		}
+		const cls = classifySpec(entry.value);
+		if (cls.kind === "movable") {
+			const to = `${cls.prefix}${target}`;
+			expected.set(entry.key, to);
+			if (to === entry.value) continue;
+			const line = lines[entry.line];
+			next[entry.line] = line.slice(0, entry.valueStart) + to + line.slice(entry.valueEnd);
+			plan.overrides.push({
+				file,
+				name: entry.key,
+				spec: entry.value,
+				action: "bumped",
+				to
+			});
+		} else if (cls.kind === "local") if (options.dropLocalOverrides) {
+			removed.add(entry.line);
+			plan.overrides.push({
+				file,
+				name: entry.key,
+				spec: entry.value,
+				action: "removed-local"
+			});
+		} else {
+			expected.set(entry.key, entry.value);
+			plan.overrides.push({
+				file,
+				name: entry.key,
+				spec: entry.value,
+				action: "kept-local"
+			});
+		}
+		else {
+			expected.set(entry.key, entry.value);
+			plan.skipped.push({
+				file,
+				name: entry.key,
+				field: "overrides",
+				spec: entry.value,
+				reason: cls.reason
+			});
+		}
+	}
+	const survivors = block.entries.filter((entry) => !removed.has(entry.line)).length + block.otherContent;
+	if (removed.size > 0 && survivors === 0) removed.add(block.keyLine);
+	const content = next.filter((_, index) => !removed.has(index)).join(crlf ? "\r\n" : "\n");
+	const after = readYamlOverrides(splitLines(content));
+	if (!isDeepStrictEqual(after ? after.entries.map((e) => [e.key, e.value]) : [], [...expected.entries()])) throw new UpgradeError(`Could not rewrite ${file} without disturbing it; nothing was written.`, "rewrite_failed", "Move its @rebasepro overrides by hand, then run `rebase upgrade` again.");
+	return content;
+}
+/** Lockfiles, in the order they are looked for in each directory. */
+var LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["package-lock.json", "npm"],
+	["yarn.lock", "yarn"],
+	["bun.lockb", "bun"],
+	["bun.lock", "bun"]
+];
+/**
+* The package manager this project installs with, from what is on disk.
+*
+* A lockfile is the project's own statement, so it wins. The search starts at
+* the project root and walks up, because a project inside a workspace has its
+* lockfile at the workspace root; it stops at the repository's root, so a stray
+* lockfile in a home directory is never read as this project's choice. With no
+* lockfile anywhere, a `pnpm-workspace.yaml` still says pnpm; otherwise npm,
+* the one every Node install has.
+*/
+function detectInstaller(projectRoot) {
+	let dir = path.resolve(projectRoot);
+	let workspaceYaml = false;
+	for (;;) {
+		for (const [lockfile, installer] of LOCKFILES) if (fs.existsSync(path.join(dir, lockfile))) return installer;
+		if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml"))) workspaceYaml = true;
+		const parent = path.dirname(dir);
+		if (parent === dir || fs.existsSync(path.join(dir, ".git"))) break;
+		dir = parent;
+	}
+	return workspaceYaml ? "pnpm" : "npm";
+}
+/**
+* The install command for each package manager — pnpm's and npm's from the
+* helpers every other command uses, yarn's and bun's spelled the same way.
+*/
+function installCommand(installer) {
+	const [bin, ...args] = installer === "pnpm" || installer === "npm" ? getPMCommands(installer).install : [installer, "install"];
+	return [bin, args];
+}
+/**
+* The exact version `--to` names.
+*
+* An exact version is used as written, with no network call: the control plane
+* passes one when it rebuilds a project, and that rebuild must not depend on a
+* registry lookup succeeding for anything but the install itself. Anything
+* else is a dist-tag, asked of the registry through `npmView` — which runs npm
+* in the project, so its `.npmrc` and the user's registry config apply.
+*/
+async function resolveTarget(requested, npmView) {
+	const trimmed = requested.trim();
+	const bare = trimmed.replace(/^v(?=\d)/, "");
+	if (isExactVersion(bare)) return bare;
+	if (!/^[A-Za-z][\w.-]*$/.test(trimmed)) throw new UpgradeError(`"${requested}" is neither an exact version nor a dist-tag.`, "target_invalid", "Pass an exact version such as 0.21.0, or a dist-tag such as latest or canary.");
+	let answer;
+	try {
+		answer = (await npmView(`${RELEASE_PACKAGE}@${trimmed}`)).trim();
+	} catch (err) {
+		const detail = err instanceof Error ? firstLine(err.message) : String(err);
+		throw new UpgradeError(`Could not resolve "${trimmed}" on the npm registry${detail ? `: ${detail}` : "."}`, "target_unresolved", "Check the tag and your registry access, or pass an exact version with --to.");
+	}
+	if (!isExactVersion(answer)) throw new UpgradeError(`The registry has no single version for ${RELEASE_PACKAGE}@${trimmed}${answer ? ` (it answered "${firstLine(answer)}")` : ""}.`, "target_unresolved", "Check the tag, or pass an exact version with --to.");
+	return answer;
+}
+function firstLine(text) {
+	return text.split("\n").map((line) => line.trim()).filter(Boolean)[0] ?? "";
+}
+/**
+* Whether moving from `from` to `to` goes backwards, for the one-word note the
+* summary prints. Prerelease identifiers compare as SemVer orders them: a
+* release outranks its own prereleases.
+*/
+function isDowngrade(from, to) {
+	const a = SEMVER.exec(from.replace(/^[\^~]/, ""));
+	const b = SEMVER.exec(to.replace(/^[\^~]/, ""));
+	if (!a || !b) return false;
+	for (let i = 1; i <= 3; i++) {
+		const diff = Number(a[i]) - Number(b[i]);
+		if (diff !== 0) return diff > 0;
+	}
+	const preA = a[4];
+	const preB = b[4];
+	if (preA === preB) return false;
+	if (preA === void 0) return true;
+	if (preB === void 0) return false;
+	const partsA = preA.split(".");
+	const partsB = preB.split(".");
+	for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+		const x = partsA[i];
+		const y = partsB[i];
+		if (x === void 0) return false;
+		if (y === void 0) return true;
+		if (x === y) continue;
+		const nx = /^\d+$/.test(x) ? Number(x) : NaN;
+		const ny = /^\d+$/.test(y) ? Number(y) : NaN;
+		if (!Number.isNaN(nx) && !Number.isNaN(ny)) return nx > ny;
+		if (!Number.isNaN(nx)) return false;
+		if (!Number.isNaN(ny)) return true;
+		return x > y;
+	}
+	return false;
+}
+//#endregion
+//#region src/commands/upgrade.ts
+/**
+* CLI command: rebase upgrade [--to <version|tag>]
+*
+* Moves every `@rebasepro/*` package the project pins to one release, then
+* installs. The file work — which specs move, the rewrite, what overrides say —
+* is `../upgrade.ts`; this adds the registry lookup for a tag, the install, and
+* the two ways of saying what happened.
+*/
+/** Every flag `rebase upgrade` accepts. Its help page and the docs verifier read this. */
+var UPGRADE_FLAGS = {
+	"--to": String,
+	"--drop-local-overrides": Boolean,
+	"--no-install": Boolean,
+	"--dry-run": Boolean,
+	"--json": Boolean
+};
+function printHelp$1() {
+	console.log(`
+${chalk.bold("rebase upgrade")} — move every @rebasepro package this project pins to one release
+
+${chalk.bold("Usage")}
+  rebase upgrade [--to <version|tag>] [options]
+
+${chalk.bold("Options")}
+  --to <version|tag>          The release: an exact version (0.21.0) or a dist-tag
+                              (latest, canary). Default: latest
+  --drop-local-overrides      Remove link: and file: overrides of @rebasepro packages,
+                              which win over every pin
+  --no-install                Rewrite the package.json files, but do not install
+  --dry-run                   Print what would change, and write nothing
+  --json                      One JSON document on stdout
+  -h, --help                  Show this help
+
+${chalk.bold("What it changes")}
+  Every @rebasepro/* entry in dependencies, devDependencies and optionalDependencies,
+  in every package.json under the project (node_modules, dist* and hidden
+  directories excepted). ^ and ~ are kept. peerDependencies are left alone, and so
+  are workspace:, link:, file:, git and tag specs, which are listed with the reason.
+  Overrides in pnpm-workspace.yaml and package.json are bumped the same way.
+
+${chalk.bold("Examples")}
+  rebase upgrade                          Move to the latest release and install
+  rebase upgrade --to canary --dry-run    See what the canary would change
+  rebase upgrade --to 0.21.0 --no-install --json
+`.trim());
+}
+var defaultIo = {
+	npmView: async (spec, cwd) => {
+		try {
+			return (await execa("npm", [
+				"view",
+				spec,
+				"version"
+			], { cwd })).stdout;
+		} catch (err) {
+			throw new Error(npmFailure(err));
+		}
+	},
+	install: async ([bin, args], cwd, quietStdout) => {
+		await execa(bin, args, {
+			cwd,
+			stdio: quietStdout ? [
+				"ignore",
+				2,
+				"inherit"
+			] : "inherit"
+		});
+	}
+};
+/**
+* The one line of a failed `npm view` worth printing.
+*
+* execa's own message is the command line that failed, which says nothing the
+* reader does not know. npm's stderr says why — `404 No match found for version
+* nosuchtag` — under an `npm error code E404` line that says less.
+*/
+function npmFailure(err) {
+	return (typeof err === "object" && err !== null && "stderr" in err && typeof err.stderr === "string" ? err.stderr : "").split("\n").map((line) => line.replace(/^npm (?:error|ERR!)\s*/, "").trim()).find((line) => line !== "" && !/^code\s/.test(line) && !/^\d{3}$/.test(line)) ?? (err instanceof Error ? err.message : String(err));
+}
+async function upgradeCommand(rawArgs, io = defaultIo) {
+	if (wantsHelp(rawArgs)) {
+		printHelp$1();
+		return;
+	}
+	const { flags } = parseCommandArgs({
+		spec: UPGRADE_FLAGS,
+		rawArgs,
+		commandWords: 1,
+		command: "upgrade",
+		maxPositionals: 0
+	});
+	const json = flags["--json"] === true;
+	const dryRun = flags["--dry-run"] === true;
+	const projectRoot = requireProjectRoot();
+	/** Every refusal, in whichever of the two languages was asked for. */
+	const refuse = (message, code, hint, issues) => {
+		if (json) failAsJson(message, code, hint, issues);
+		console.error(chalk.red(`✗ ${message}`));
+		for (const issue of issues ?? []) console.error(`  ${chalk.gray(issue.path ?? "")} ${issue.message}`);
+		if (hint) console.error(chalk.gray(`  ${hint}`));
+		process.exit(1);
+	};
+	try {
+		loadManifest(projectRoot);
+	} catch (err) {
+		if (err instanceof ManifestError) refuse(err.message, "manifest_invalid", "Fix rebase.json, then run this again.", err.issues.map((issue) => ({
+			path: issue.path,
+			message: issue.message
+		})));
+		throw err;
+	}
+	let plan;
+	try {
+		plan = planUpgrade(projectRoot, await resolveTarget(flags["--to"] ?? "latest", (spec) => io.npmView(spec, projectRoot)), { dropLocalOverrides: flags["--drop-local-overrides"] === true });
+	} catch (err) {
+		if (err instanceof UpgradeError) refuse(err.message, err.code, err.hint);
+		throw err;
+	}
+	if (!dryRun) applyUpgradePlan(plan);
+	const wrote = !dryRun && plan.writes.length > 0;
+	const install = wrote && flags["--no-install"] !== true;
+	const installer = detectInstaller(projectRoot);
+	const [bin, args] = installCommand(installer);
+	const installLine = [bin, ...args].join(" ");
+	if (!json) printSummary(plan, dryRun);
+	let installed = false;
+	if (install) {
+		if (!json) console.log(chalk.gray(`  Installing with ${installer}...\n`));
+		try {
+			await io.install([bin, args], projectRoot, json);
+			installed = true;
+		} catch {
+			refuse(`\`${installLine}\` failed.`, "install_failed", `The package.json edits were kept. Fix what the install reported and run \`${installLine}\` again, or revert the edits with git.`);
+		}
+	}
+	const result = {
+		target: plan.target,
+		changed: plan.changed,
+		skipped: plan.skipped,
+		overrides: plan.overrides,
+		unreadable: plan.unreadable,
+		installed,
+		dryRun
+	};
+	if (json) {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+	printOutcome(plan, {
+		dryRun,
+		wrote,
+		installed,
+		installLine
+	});
+}
+/** Changes grouped by file, then what was left alone and why, then overrides. */
+function printSummary(plan, dryRun) {
+	console.log("");
+	console.log(`${chalk.bold("Rebase")} — ${dryRun ? "what upgrading" : "upgrading"} @rebasepro packages to ${chalk.cyan(plan.target)}${dryRun ? " would change" : ""}`);
+	const byFile = /* @__PURE__ */ new Map();
+	for (const pin of plan.changed) byFile.set(pin.file, [...byFile.get(pin.file) ?? [], pin]);
+	const nameWidth = Math.max(0, ...plan.changed.map((pin) => pin.name.length));
+	for (const [file, pins] of byFile) {
+		console.log("");
+		console.log(`  ${chalk.bold(file)}`);
+		for (const pin of pins) {
+			const field = pin.field === "dependencies" ? "" : chalk.gray(`  ${pin.field}`);
+			const older = isDowngrade(pin.from, pin.to) ? chalk.yellow("  (older)") : "";
+			console.log(`    ${pin.name.padEnd(nameWidth)}  ${chalk.gray(pin.from)} → ${chalk.green(pin.to)}${field}${older}`);
+		}
+	}
+	if (plan.skipped.length > 0) {
+		console.log("");
+		console.log(`  ${chalk.bold("Left alone")}`);
+		for (const skip of plan.skipped) {
+			console.log(`    ${skip.name}  ${chalk.gray(skip.spec)}  ${chalk.gray(`(${skip.file}, ${skip.field})`)}`);
+			console.log(chalk.gray(`      ${skip.reason}`));
+		}
+	}
+	if (plan.overrides.length > 0) {
+		console.log("");
+		console.log(`  ${chalk.bold("Overrides")}`);
+		for (const override of plan.overrides) {
+			const where = chalk.gray(`(${override.file})`);
+			if (override.action === "bumped") console.log(`    ${override.name}  ${chalk.gray(override.spec)} → ${chalk.green(override.to ?? "")}  ${where}`);
+			else if (override.action === "removed-local") console.log(`    ${override.name}  ${chalk.gray(override.spec)}  ${where}  ${chalk.green(dryRun ? "would be removed" : "removed")}`);
+			else {
+				console.log(`    ${chalk.yellow("⚠")} ${override.name} → ${override.spec}  ${where}`);
+				console.log(chalk.yellow("      local override — wins over every pin, the upgrade will not reach these packages"));
+			}
+		}
+		if (plan.overrides.some((o) => o.action === "kept-local")) console.log(chalk.gray("      Run again with --drop-local-overrides to remove them."));
+	}
+	if (plan.unreadable.length > 0) {
+		console.log("");
+		console.log(`  ${chalk.bold("Not read")}`);
+		for (const entry of plan.unreadable) console.log(`    ${entry.file}  ${chalk.gray(entry.reason)}`);
+	}
+	console.log("");
+}
+function printOutcome(plan, outcome) {
+	const moved = plan.changed.length + plan.overrides.filter((o) => o.action !== "kept-local").length;
+	if (outcome.dryRun) {
+		console.log(chalk.gray(moved === 0 ? `  Nothing to change: this project is already on ${plan.target}.` : "  Dry run — nothing was written. Run it without --dry-run to apply."));
+		console.log("");
+		return;
+	}
+	if (!outcome.wrote) {
+		console.log(chalk.green(`✓ This project is already on ${plan.target}.`));
+		console.log("");
+		return;
+	}
+	const files = plan.writes.length;
+	console.log(chalk.green(`✓ Moved ${moved} entr${moved === 1 ? "y" : "ies"} in ${files} file${files === 1 ? "" : "s"} to ${plan.target}${outcome.installed ? " and installed" : ""}.`));
+	if (!outcome.installed) console.log(chalk.gray(`  Install with \`${outcome.installLine}\`, then run \`rebase build\`, then \`rebase cloud deploy\`.`));
+	else console.log(chalk.gray("  Run `rebase build`, then `rebase cloud deploy`."));
+	console.log("");
+}
+//#endregion
 //#region src/cli.ts
 /**
 * Silence dotenv's own banner, for this process and everything it spawns.
@@ -19697,7 +21196,8 @@ async function entry(args) {
 		"generate-sdk",
 		"telemetry",
 		"resources",
-		"status"
+		"status",
+		"upgrade"
 	];
 	if (!command || parsedArgs["--help"] && !namespacedCommands.includes(command)) {
 		printHelp();
@@ -19776,6 +21276,9 @@ async function dispatch(command, effectiveSubcommand, args, parsedArgs, namespac
 		case "start":
 			await startCommand(args);
 			break;
+		case "upgrade":
+			await upgradeCommand(args);
+			break;
 		case "apps":
 			await appsCommand(effectiveSubcommand, args);
 			break;
@@ -19823,6 +21326,7 @@ ${chalk.green.bold("Commands")}
   ${chalk.blue.bold("build")}                   Build the apps declared in rebase.json into a bundle
   ${chalk.blue.bold("normalize-imports")}       Complete compiled output's relative imports for Node ESM
   ${chalk.blue.bold("start")}                   Start the backend server ${chalk.gray("(production)")}
+  ${chalk.blue.bold("upgrade")}                 Move every @rebasepro package to one release, then install
   ${chalk.blue.bold("apps list")}               Show the apps this repository declares
 
 ${chalk.green.bold("Schema")}