@rebasepro/cli 0.17.3 → 0.18.0

package/LICENSE

@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

package/README.md

@@ -8,6 +8,10 @@ Developer CLI for scaffolding, running, and managing Rebase projects.
 pnpm add -g @rebasepro/cli
 ```
 
+ESM-only: `"type": "module"` with no CommonJS build, so it is loaded with
+`import`. `require()` of it resolves only on Node 22.12+, which supports
+`require(esm)`.
+
 The CLI is also bundled with every Rebase project as a local dependency.
 
 ## Commands
@@ -26,6 +30,9 @@ The CLI is also bundled with every Rebase project as a local dependency.
 | `rebase generate-sdk` | Generate a typed TypeScript SDK from collections |
 | `rebase auth reset-password` | Reset a user's password |
 | `rebase doctor` | Detect schema drift between collections, Drizzle schema, and database |
+| `rebase status` | Show every resource this project declares and whether its variables are set |
+| `rebase resources` | List the databases, buckets and topics this project declares |
+| `rebase skills install` | Install Rebase agent skills for your AI coding assistant |
 | `rebase cloud <command>` | Manage your apps on Rebase Cloud (auth, deploy, databases, …) |
 
 Run `rebase --help` or `rebase <command> --help` for detailed usage.
@@ -61,13 +68,24 @@ Run `rebase cloud --help` for the full list.
 ## Quick Start
 
 ```bash
-rebase init my-app
+pnpm dlx @rebasepro/cli init my-app
 cd my-app
-docker compose up -d db
-pnpm run db:push
+pnpm install
 pnpm run dev
 ```
 
+That is the whole first run. With no `DATABASE_URL` set, `rebase dev` starts a
+managed PostgreSQL (PGlite) in the project directory, generates the Drizzle
+schema from your collections, and creates the tables at boot — no database to
+install and no schema step.
+
+Two commands worth knowing straight after:
+
+```bash
+rebase status           # every resource, and whether its variables are set
+rebase skills install   # Rebase skills for your AI coding assistant
+```
+
 ## Related Packages
 
 | Package | Role |

package/bin/rebase.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -7,6 +7,85 @@ const here = dirname(fileURLToPath(import.meta.url));
 const distEntry = join(here, "..", "dist", "index.es.js");
 const srcDir = join(here, "..", "src");
 
+/**
+ * Colour, but only for a terminal.
+ *
+ * Every other line the CLI prints goes through chalk, which checks this for
+ * itself. These three did not — they are written before the bundle is even
+ * imported, so they hard-coded `\x1b[31m` — and stderr is exactly where that
+ * costs something: `rebase status extra 2>err.txt` wrote the escapes into the
+ * file, and CI logs, `2>&1 | grep`, and every agent reading a failed command's
+ * output got them too.
+ *
+ * `NO_COLOR` and `FORCE_COLOR` are the two conventions chalk honours, so
+ * honouring the same two keeps one CLI rather than two.
+ */
+const useColor = process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0"
+    ? true
+    : Boolean(process.stderr.isTTY) && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+
+const paint = (code, text) => (useColor ? `\x1b[${code}m${text}\x1b[0m` : text);
+const red = (text) => paint(31, text);
+const yellow = (text) => paint(33, text);
+const dim = (text) => paint(90, text);
+
+/**
+ * Refuse to run on a Node older than this CLI's own floor, before anything else.
+ *
+ * `engines.node` is declared on all 22 packages and `check:floors` keeps the
+ * numbers in step — on the reasoning that "npm and pnpm check `engines` on
+ * install, so the number is load-bearing". pnpm 11 does not: a project whose
+ * `engines.node` is `>=99.0.0` installs silently and exits 0, and so does a
+ * *dependency* declaring it. npm prints `EBADENGINE` and also exits 0. So the
+ * declared floor was enforced by nothing at all, and `rebase init` on Node 20
+ * said nothing until a syntax error surfaced from inside a dependency —
+ * `checkNodeVersion` existed but only `rebase doctor` ever called it.
+ *
+ * First, and before `await import("../dist/…")`, because the bundle is the
+ * thing most likely to fail incomprehensibly on an old runtime: the point is to
+ * name the version rather than let the reader debug a stack trace in minified
+ * output.
+ *
+ * The floor is read from this package's own `package.json` rather than written
+ * here, so it cannot drift from what `check:floors` gates and from what
+ * `rebase doctor` reports. The comparison duplicates
+ * `doctor-environment.ts`'s — importing it would mean importing the bundle,
+ * which is the thing being guarded — and `bin-floor.test.ts` asserts the two
+ * still agree.
+ */
+function assertNodeFloor() {
+    let required;
+    try {
+        const manifest = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+        required = manifest?.engines?.node;
+    } catch {
+        return; // No manifest, no floor to enforce. Never a reason to refuse.
+    }
+    if (typeof required !== "string") return;
+
+    // `>=x[.y[.z]]`, the only form any engines.node in this repo takes. Anything
+    // else parses to nothing and the guard stands down rather than guessing.
+    const declared = required.match(/>=\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!declared) return;
+    const running = process.versions.node.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!running) return;
+
+    for (let i = 1; i <= 3; i++) {
+        const min = Number(declared[i] ?? 0);
+        const now = Number(running[i] ?? 0);
+        if (now > min) return;
+        if (now < min) {
+            process.stderr.write(
+                `${red(`✗ rebase CLI: Node ${process.versions.node} is running, and Rebase needs ${required}.`)}\n` +
+                `  Install Node ${declared[1]} or newer (nvm install ${declared[1]}), then reinstall dependencies.\n`
+            );
+            process.exit(1);
+        }
+    }
+}
+
+assertNodeFloor();
+
 /**
  * Warn when the built CLI is older than the source it was built from.
  *
@@ -53,7 +132,7 @@ function warnIfStale() {
         ? `${Math.round(seconds / 3600)}h`
         : seconds >= 60 ? `${Math.round(seconds / 60)}m` : `${seconds}s`;
     process.stderr.write(
-        `⚠ rebase CLI: dist/ is ${ago} older than src/ — you are running a stale build.\n` +
+        `${yellow(`⚠ rebase CLI: dist/ is ${ago} older than src/ — you are running a stale build.`)}\n` +
         `  Rebuild with: (cd ${join(here, "..")} && npm run build)\n`
     );
 }
@@ -77,7 +156,7 @@ try {
 if (!existsSync(distEntry)) {
     const dev = existsSync(srcDir);
     process.stderr.write(
-        `\x1b[31m✗ rebase CLI: not built yet — ${distEntry} is missing.\x1b[0m\n` +
+        `${red(`✗ rebase CLI: not built yet — ${distEntry} is missing.`)}\n` +
         (dev
             ? "  Build it with: pnpm --filter @rebasepro/cli build\n" +
               "  (or `pnpm build` from the repo root to build every package)\n"
@@ -102,16 +181,24 @@ const { entry } = await import("../dist/index.es.js");
  * friendly and exit never reach here. The stack is available behind
  * `--debug`/`REBASE_DEBUG`, because when the message is *not* enough that is
  * the only thing that helps.
+ *
+ * With one exception: a *usage* error. `rebase status extra` has no stack worth
+ * reading — it points at `arg` and `utils/args.ts` — and the hint suggests
+ * re-running with another flag, when the flags are precisely what went wrong.
+ * `utils/args.ts` marks those with `isUsageError` rather than a class, because
+ * this file imports the bundle and `instanceof` cannot reach across it.
  */
 const wantsStack = process.argv.includes("--debug") || process.env.REBASE_DEBUG === "1";
 
 entry(process.argv).catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`\x1b[31m✗ ${message}\x1b[0m\n`);
+    const isUsage = Boolean(error && typeof error === "object" && error.isUsageError);
+
+    process.stderr.write(`${red(`✗ ${message}`)}\n`);
     if (wantsStack && error instanceof Error && error.stack) {
         process.stderr.write(`\n${error.stack}\n`);
-    } else {
-        process.stderr.write("\x1b[90m  Re-run with --debug for the stack trace.\x1b[0m\n");
+    } else if (!isUsage) {
+        process.stderr.write(`${dim("  Re-run with --debug for the stack trace.")}\n`);
     }
     process.exit(1);
 });

package/dist/branch-pointer-dBiClJ0p.js

@@ -0,0 +1,111 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import path from "path";
+import fs from "fs";
+//#region src/dev-db/branch-pointer.ts
+/**
+* Which database branch this checkout is working on.
+*
+* `rebase db branch create` made a full copy of the database in about a second
+* and then stopped one step short of being a feature: there was no `switch`, no
+* `--branch` on `rebase dev`, and nothing wrote the branch anywhere a command
+* would read it. The only way to *use* a branch was to hand-edit
+* `DATABASE_URL`, and the documentation claimed otherwise — "the CLI updates
+* your local development configuration" — which it did not; the `.env` was
+* byte-identical afterwards.
+*
+* This is that missing step, and the shape of it is chosen to avoid three
+* things:
+*
+* 1. **It does not touch `.env`.** That file holds secrets, comments and the
+*    developer's own ordering, and a command that rewrites it in place will
+*    eventually lose something that was not its business. The branch is
+*    recorded beside the other per-checkout state in `.rebase/`, which is
+*    already gitignored — a branch is a fact about one machine, never about
+*    the project.
+*
+* 2. **It stores a name, not a connection string.** The credentials stay in
+*    exactly one place; the URL is derived by swapping the database name on
+*    the base one at resolution time. A stored URL would be a second copy of
+*    the password, and would go stale the moment `.env` changed.
+*
+* 3. **It does not outrank an explicit instruction.** `--database-url` and a
+*    `DATABASE_URL` in the shell are more immediate and more specific than a
+*    switch made yesterday, so they still win. The pointer sits directly above
+*    the project's `.env`: it is a deliberate, persistent choice, and `.env` is
+*    the project default it is meant to override. Anything less and `switch`
+*    would silently do nothing on every project that sets `DATABASE_URL` —
+*    which is every project not using the managed database.
+*/
+var branch_pointer_exports = /* @__PURE__ */ __exportAll({
+	BRANCH_DB_PREFIX: () => "rb_",
+	branchDatabaseName: () => branchDatabaseName,
+	branchPointerPath: () => branchPointerPath,
+	branchUrl: () => branchUrl,
+	clearActiveBranch: () => clearActiveBranch,
+	databaseNameOf: () => databaseNameOf,
+	readActiveBranch: () => readActiveBranch,
+	writeActiveBranch: () => writeActiveBranch
+});
+/** Where the pointer lives, next to the rest of the per-checkout state. */
+function branchPointerPath(projectRoot) {
+	return path.join(projectRoot, ".rebase", "branch.json");
+}
+function branchDatabaseName(name) {
+	return `rb_${name}`;
+}
+/** Read the active branch, or null when the checkout is on the main database. */
+function readActiveBranch(projectRoot) {
+	try {
+		const raw = fs.readFileSync(branchPointerPath(projectRoot), "utf-8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.name !== "string" || typeof parsed.database !== "string") return null;
+		if (!parsed.name || !parsed.database) return null;
+		return {
+			name: parsed.name,
+			database: parsed.database
+		};
+	} catch {
+		return null;
+	}
+}
+function writeActiveBranch(projectRoot, branch) {
+	const file = branchPointerPath(projectRoot);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, `${JSON.stringify(branch, null, 2)}\n`, "utf-8");
+}
+/** Return to the main database. Absent is success — this is idempotent. */
+function clearActiveBranch(projectRoot) {
+	fs.rmSync(branchPointerPath(projectRoot), { force: true });
+}
+/**
+* The base connection string with its database swapped for the branch's.
+*
+* Everything else is carried across untouched — credentials, host, port, and
+* the query string, which is load-bearing here: `?sslmode=disable` is what a
+* local Docker Postgres needs, and dropping it turns a switch into a TLS error
+* that says nothing about branches.
+*
+* Returns null for a connection string that cannot be parsed, so the caller can
+* say so plainly rather than emitting a mangled URL that fails later.
+*/
+function branchUrl(baseUrl, database) {
+	try {
+		const url = new URL(baseUrl);
+		url.pathname = `/${database}`;
+		return url.toString();
+	} catch {
+		return null;
+	}
+}
+/** The database name in a connection string, for reporting what you are on. */
+function databaseNameOf(connectionString) {
+	try {
+		return new URL(connectionString).pathname.replace(/^\//, "") || null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { branch_pointer_exports as n, readActiveBranch as r, branchUrl as t };
+
+//# sourceMappingURL=branch-pointer-dBiClJ0p.js.map

package/dist/branch-pointer-dBiClJ0p.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-pointer-dBiClJ0p.js","names":[],"sources":["../src/dev-db/branch-pointer.ts"],"sourcesContent":["/**\n * Which database branch this checkout is working on.\n *\n * `rebase db branch create` made a full copy of the database in about a second\n * and then stopped one step short of being a feature: there was no `switch`, no\n * `--branch` on `rebase dev`, and nothing wrote the branch anywhere a command\n * would read it. The only way to *use* a branch was to hand-edit\n * `DATABASE_URL`, and the documentation claimed otherwise — \"the CLI updates\n * your local development configuration\" — which it did not; the `.env` was\n * byte-identical afterwards.\n *\n * This is that missing step, and the shape of it is chosen to avoid three\n * things:\n *\n * 1. **It does not touch `.env`.** That file holds secrets, comments and the\n *    developer's own ordering, and a command that rewrites it in place will\n *    eventually lose something that was not its business. The branch is\n *    recorded beside the other per-checkout state in `.rebase/`, which is\n *    already gitignored — a branch is a fact about one machine, never about\n *    the project.\n *\n * 2. **It stores a name, not a connection string.** The credentials stay in\n *    exactly one place; the URL is derived by swapping the database name on\n *    the base one at resolution time. A stored URL would be a second copy of\n *    the password, and would go stale the moment `.env` changed.\n *\n * 3. **It does not outrank an explicit instruction.** `--database-url` and a\n *    `DATABASE_URL` in the shell are more immediate and more specific than a\n *    switch made yesterday, so they still win. The pointer sits directly above\n *    the project's `.env`: it is a deliberate, persistent choice, and `.env` is\n *    the project default it is meant to override. Anything less and `switch`\n *    would silently do nothing on every project that sets `DATABASE_URL` —\n *    which is every project not using the managed database.\n */\n\nimport fs from \"fs\";\nimport path from \"path\";\n\n/** Where the pointer lives, next to the rest of the per-checkout state. */\nexport function branchPointerPath(projectRoot: string): string {\n    return path.join(projectRoot, \".rebase\", \"branch.json\");\n}\n\nexport interface ActiveBranch {\n    /** The name the developer typed. */\n    name: string;\n    /** The PostgreSQL database that name refers to. */\n    database: string;\n}\n\n/**\n * The prefix `BranchService` puts on every branch database.\n *\n * Duplicated from the driver rather than imported because the CLI must answer\n * \"which database\" without loading a database driver — `rebase dev` reads this\n * before it knows which plugin the project uses. It is covered by a test that\n * fails if the driver's prefix moves.\n */\nexport const BRANCH_DB_PREFIX = \"rb_\";\n\nexport function branchDatabaseName(name: string): string {\n    return `${BRANCH_DB_PREFIX}${name}`;\n}\n\n/** Read the active branch, or null when the checkout is on the main database. */\nexport function readActiveBranch(projectRoot: string): ActiveBranch | null {\n    try {\n        const raw = fs.readFileSync(branchPointerPath(projectRoot), \"utf-8\");\n        const parsed = JSON.parse(raw) as Partial<ActiveBranch>;\n        if (typeof parsed.name !== \"string\" || typeof parsed.database !== \"string\") return null;\n        if (!parsed.name || !parsed.database) return null;\n\n        return { name: parsed.name, database: parsed.database };\n    } catch {\n        // Absent is the common case and is not an error. A corrupt file is\n        // treated the same way: the answer is \"no branch\", which is the state\n        // the developer can always get back to with `branch switch --off`.\n        return null;\n    }\n}\n\nexport function writeActiveBranch(projectRoot: string, branch: ActiveBranch): void {\n    const file = branchPointerPath(projectRoot);\n    fs.mkdirSync(path.dirname(file), { recursive: true });\n    fs.writeFileSync(file, `${JSON.stringify(branch, null, 2)}\\n`, \"utf-8\");\n}\n\n/** Return to the main database. Absent is success — this is idempotent. */\nexport function clearActiveBranch(projectRoot: string): void {\n    fs.rmSync(branchPointerPath(projectRoot), { force: true });\n}\n\n/**\n * The base connection string with its database swapped for the branch's.\n *\n * Everything else is carried across untouched — credentials, host, port, and\n * the query string, which is load-bearing here: `?sslmode=disable` is what a\n * local Docker Postgres needs, and dropping it turns a switch into a TLS error\n * that says nothing about branches.\n *\n * Returns null for a connection string that cannot be parsed, so the caller can\n * say so plainly rather than emitting a mangled URL that fails later.\n */\nexport function branchUrl(baseUrl: string, database: string): string | null {\n    try {\n        const url = new URL(baseUrl);\n        // `pathname` keeps its leading slash; a URL with no database at all\n        // still gets one, which is what connecting to a named branch means.\n        url.pathname = `/${database}`;\n\n        return url.toString();\n    } catch {\n        return null;\n    }\n}\n\n/** The database name in a connection string, for reporting what you are on. */\nexport function databaseNameOf(connectionString: string): string | null {\n    try {\n        const name = new URL(connectionString).pathname.replace(/^\\//, \"\");\n\n        return name || null;\n    } catch {\n        return null;\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,kBAAkB,aAA6B;CAC3D,OAAO,KAAK,KAAK,aAAa,WAAW,aAAa;AAC1D;AAmBA,SAAgB,mBAAmB,MAAsB;CACrD,OAAO,MAAsB;AACjC;;AAGA,SAAgB,iBAAiB,aAA0C;CACvE,IAAI;EACA,MAAM,MAAM,GAAG,aAAa,kBAAkB,WAAW,GAAG,OAAO;EACnE,MAAM,SAAS,KAAK,MAAM,GAAG;EAC7B,IAAI,OAAO,OAAO,SAAS,YAAY,OAAO,OAAO,aAAa,UAAU,OAAO;EACnF,IAAI,CAAC,OAAO,QAAQ,CAAC,OAAO,UAAU,OAAO;EAE7C,OAAO;GAAE,MAAM,OAAO;GAAM,UAAU,OAAO;EAAS;CAC1D,QAAQ;EAIJ,OAAO;CACX;AACJ;AAEA,SAAgB,kBAAkB,aAAqB,QAA4B;CAC/E,MAAM,OAAO,kBAAkB,WAAW;CAC1C,GAAG,UAAU,KAAK,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;CACpD,GAAG,cAAc,MAAM,GAAG,KAAK,UAAU,QAAQ,MAAM,CAAC,EAAE,KAAK,OAAO;AAC1E;;AAGA,SAAgB,kBAAkB,aAA2B;CACzD,GAAG,OAAO,kBAAkB,WAAW,GAAG,EAAE,OAAO,KAAK,CAAC;AAC7D;;;;;;;;;;;;AAaA,SAAgB,UAAU,SAAiB,UAAiC;CACxE,IAAI;EACA,MAAM,MAAM,IAAI,IAAI,OAAO;EAG3B,IAAI,WAAW,IAAI;EAEnB,OAAO,IAAI,SAAS;CACxB,QAAQ;EACJ,OAAO;CACX;AACJ;;AAGA,SAAgB,eAAe,kBAAyC;CACpE,IAAI;EAGA,OAFa,IAAI,IAAI,gBAAgB,CAAC,CAAC,SAAS,QAAQ,OAAO,EAExD,KAAQ;CACnB,QAAQ;EACJ,OAAO;CACX;AACJ"}

package/dist/bundle.d.ts

@@ -1,4 +1,4 @@
-import { type ResourceGraph, type NativeDependency, type RebaseBundleManifest, type RebaseBackendAppConfig } from "@rebasepro/types";
+import { type ResourceGraph, type NativeDependency, type RebaseBundleManifest, type RebaseBundleFunction, type RebaseBackendAppConfig } from "@rebasepro/types";
 export declare const DEFAULT_BUNDLE_DIR = "dist-bundle";
 export interface BuildBundleOptions {
     projectRoot: string;
@@ -89,15 +89,28 @@ export declare function detectNativeDependencies(projectRoot: string, declared:
  * wasted space and at worst a version conflict. Workspace packages are excluded
  * too: they are not on the registry the runtime installs from, and the project's
  * own config package already travels inside the bundle.
+ *
+ * Throws when a declared range is not something the registry can resolve, or
+ * when two manifests declare a name at ranges nothing satisfies. The
+ * alternative is a bundle that builds green and fails at the deploy's install
+ * step, minutes later and on a machine the developer cannot see. `rebase build`
+ * reports both in its own words first; this is the backstop for every other
+ * caller, `rebase cloud deploy` included.
  */
 export declare function collectDeclaredDependencies(projectRoot: string): Record<string, string>;
-/** One `@rebasepro/*` dependency as some package.json in the project declares it. */
+/** One dependency as some package.json in the project declares it. */
 export interface DeclaredFrameworkDep {
     name: string;
     range: string;
     /** Project-relative package.json it was declared in. */
     file: string;
 }
+/** One name two of the bundle's manifests declare at ranges nothing satisfies. */
+export interface DeclaredDepConflict {
+    name: string;
+    /** The two declarations, in manifest order. */
+    declarations: [DeclaredFrameworkDep, DeclaredFrameworkDep];
+}
 export interface FrameworkDepDrift {
     /** Declared at a version that can never reach the CLI's own. */
     behind: DeclaredFrameworkDep[];
@@ -107,7 +120,27 @@ export interface FrameworkDepDrift {
      * packages against each other.
      */
     disagreeing: string[];
+    /**
+     * Third-party names two bundle manifests declare at ranges no single version
+     * satisfies. One of the two wins in `deps.declared` and the loser's code was
+     * typechecked against a version the runtime will never install.
+     */
+    conflicting: DeclaredDepConflict[];
 }
+/**
+ * Names two of the bundle's manifests declare at ranges nothing satisfies.
+ *
+ * `collectDeclaredDependencies` has to pick one — the app's — and the loser is
+ * silent: the bundle tells the managed runtime to install a version the other
+ * half of the project was never compiled against. The stock scaffold shipped
+ * exactly that (`dotenv ^16` at the root, `^17.4.2` in `backend/`), so every
+ * bundle built from a default project asked for dotenv 16.
+ *
+ * Scoped to the three manifests that feed `deps.declared`, and to their
+ * `dependencies`: a `frontend/` that wants a different major of a build tool is
+ * not this problem, and `devDependencies` never reach the bundle.
+ */
+export declare function detectDeclaredDepConflicts(projectRoot: string): DeclaredDepConflict[];
 /**
  * Find `@rebasepro/*` dependencies pinned to a version older than this CLI.
  *
@@ -126,6 +159,24 @@ export interface FrameworkDepDrift {
  * one nobody looks at.
  */
 export declare function detectFrameworkDepDrift(projectRoot: string, cliVersion: string): FrameworkDepDrift;
+/**
+ * The `[start, end)` ranges of `//` and block comments in JavaScript source.
+ *
+ * `normalizeEsmSpecifiers` scans emitted output with a regular expression, and a
+ * regular expression cannot tell a specifier from a specifier somebody wrote
+ * about. The stock template ships one: `config/resources.ts` documents
+ * `import { media } from "../resources";` inside a docblock, tsc preserves the
+ * comment, and every `rebase build` of an untouched scaffold printed
+ * `⚠ 1 import(s) could not be resolved`. A warning that is wrong on the default
+ * project teaches people to ignore the warning that predicts a boot failure.
+ *
+ * Strings are tracked only so a `//` inside one — every `http://` in the tree —
+ * does not open a comment that swallows the rest of the line. A `'` or `"` span
+ * ends at the newline as well as at its closing quote: a JavaScript string
+ * cannot contain a raw newline, so a quote that reaches one was never a string
+ * (a regex literal's, most likely) and the mistake must not run on.
+ */
+export declare function commentSpans(source: string): Array<[number, number]>;
 /**
  * Rewrite relative import specifiers in emitted JavaScript so Node can resolve them.
  *
@@ -169,6 +220,33 @@ export declare function findUnusedServerEntry(projectRoot: string, functionsDir:
 /**
  * Compile and assemble a bundle.
  */
+/** What `composeBundleManifest` needs: every input, already resolved. */
+export interface ComposeManifestInput {
+    runtimeRange: string;
+    builtAgainst: string;
+    schemaVersion: string;
+    appName: string;
+    entry: RebaseBundleManifest["entry"];
+    collectionSlugs: string[];
+    functions: RebaseBundleFunction[];
+    nativeModules: NativeDependency[];
+    declaresStorageAuthorize: boolean;
+    resources: ResourceGraph | undefined;
+    declaredDeps: Record<string, string>;
+    build: RebaseBundleManifest["build"];
+}
+/**
+ * The bundle manifest, as a pure function of its inputs.
+ *
+ * Separated from `buildBundle` so the SHAPE a host reads can be pinned by a
+ * test without compiling a project: `tooling/contracts/bundle-manifest.json`
+ * is written from this with fixed inputs, and the control plane's own tests
+ * read that file to prove they consume what the CLI emits. That contract is
+ * what was missing when buckets moved from `storage.sources` into `resources`
+ * and the control plane went on reading the old field for two weeks — every
+ * declared bucket arriving as nothing, with both suites green.
+ */
+export declare function composeBundleManifest(input: ComposeManifestInput): RebaseBundleManifest;
 export declare function buildBundle(options: BuildBundleOptions): Promise<BuildBundleResult>;
 /** Default install target: what the published runtime image runs. */
 export declare const VENDOR_TARGET_OS = "linux";
@@ -339,4 +417,3 @@ export declare function buildStaticBundle(options: {
     manifest: RebaseBundleManifest;
     fileCount: number;
 };
-export declare function resolveCliVersion(): string;

package/dist/cli.d.ts

@@ -1 +1,23 @@
+/**
+ * The flags that mean the same thing wherever they appear.
+ *
+ * `--debug` is in here even though this file does not act on it: it is
+ * implemented one level up, in `bin/rebase.js`, which prints the stack of a
+ * failed command instead of the one-line message. That is exactly why it went
+ * missing from the help for as long as it did — the flag lived in the
+ * launcher, the Options block lived here, and neither knew about the other.
+ * Declaring it here puts both under one spec, which `cli.test.ts` holds
+ * against the printed help.
+ *
+ * Exported for that test.
+ */
+export declare const ROOT_FLAGS: {
+    readonly "--version": BooleanConstructor;
+    readonly "--help": BooleanConstructor;
+    readonly "--debug": BooleanConstructor;
+    readonly "-v": "--version";
+    readonly "-h": "--help";
+};
 export declare function entry(args: string[]): Promise<void>;
+/** The global help. Exported so its Options block can be held against {@link ROOT_FLAGS}. */
+export declare function printHelp(): void;

package/dist/commands/auth.d.ts

@@ -61,3 +61,16 @@ export declare function resolveResetPasswordArgs(rawArgs: string[]): {
     email?: string;
     password?: string;
 };
+/**
+ * A password for a reset that was not given one.
+ *
+ * This used to be a constant, and `--help` printed it as the default. Reset is
+ * the documented way back into an account nobody can sign in to — an admin,
+ * usually — so the recovery path set every such account to a fixed string that
+ * ships inside a public repository and a published npm package, and left it
+ * there until somebody remembered to change it.
+ *
+ * base64url of 18 random bytes: 24 characters, ~144 bits, no shell-quoting
+ * hazard, and nothing that reads like a placeholder somebody might keep.
+ */
+export declare function generatePassword(): string;

package/dist/commands/cloud/action-help.d.ts

@@ -11,16 +11,6 @@ export interface ActionHelp {
     /** Anything a caller gets wrong more than once. */
     notes?: string[];
 }
-/**
- * Flags every cloud command accepts, documented once.
- *
- * Excluded from the spec comparison below — they are merged in by
- * `parseCloudArgs` for every command in the family, so repeating them per entry
- * would be nine copies of the same four lines.
- */
-export declare const GLOBAL_HELP_FLAGS: Array<[string, string]>;
-/** Flag names that `parseCloudArgs` adds to every command in the family. */
-export declare const GLOBAL_SPEC_KEYS: Set<string>;
 export declare const ACTION_HELP: Record<string, ActionHelp>;
 /** Print one action's page — human, or its JSON description when piped. */
 export declare function printActionHelp(entry: ActionHelp): void;

package/dist/commands/cloud/auth.d.ts

@@ -1,3 +1,40 @@
+/**
+ * Every flag `rebase cloud login` accepts.
+ *
+ * Hoisted out of the `arg` call so one declaration serves the parser,
+ * `action-help.ts`'s page for this command, and the test that holds the two to
+ * each other — the same arrangement `DEPLOY_FLAGS` and `CREATE_PROJECT_FLAGS`
+ * already use.
+ */
+export declare const LOGIN_FLAGS: {
+    readonly "--email": StringConstructor;
+    readonly "--password": StringConstructor;
+    readonly "-e": "--email";
+};
+/**
+ * Where credentials may come from, in the order this command prefers them.
+ *
+ * The environment is the non-interactive route, and it exists so `--password`
+ * does not have to be. A password written as an argument is in the shell's
+ * history file and in the process table for as long as the command runs, and
+ * neither is something this CLI can redact after the fact — the same reasoning
+ * `rls-check` states for its connection string, which carries one too.
+ *
+ * There is no machine token yet, so CI genuinely does need a human's password;
+ * `REBASE_CLOUD_PASSWORD` is how a secret store hands it over without it
+ * appearing on a command line.
+ */
+export declare const PASSWORD_ENV = "REBASE_CLOUD_PASSWORD";
+export declare const EMAIL_ENV = "REBASE_CLOUD_EMAIL";
+/**
+ * Whether this line put a password in the shell's history.
+ *
+ * Exported for its test: the warning is the whole feature, so "it warns exactly
+ * when the flag was used" is the thing worth pinning.
+ */
+export declare function passwordOnTheCommandLine(args: {
+    "--password"?: string;
+}): boolean;
 export declare function loginCommand(rawArgs: string[]): Promise<void>;
 export declare function logoutCommand(rawArgs: string[]): Promise<void>;
 export declare function whoamiCommand(rawArgs: string[]): Promise<void>;

package/dist/commands/cloud/context.d.ts

@@ -8,6 +8,19 @@ export declare function getContextOrg(url: string): string | undefined;
 /** Mark a host as the active context (called on login). */
 export declare function setCurrentContext(url: string): void;
 export declare function resolveCloudUrl(rawArgs: string[]): string;
+/**
+ * Refuse to run a control-plane command in a directory linked straight at a
+ * backend.
+ *
+ * The alternative — quietly using the default control plane — would be worse
+ * than the bug it replaces: the user asked for `https://api.example.com` and
+ * would get an answer about `app.rebase.pro` with nothing saying so. Naming the
+ * link, and both ways out of it, is the whole message.
+ *
+ * `--project` and `--url` are the ways out, so a line carrying either passes
+ * through: both say, explicitly, which control-plane subject the caller means.
+ */
+export declare function refuseDirectLink(rawArgs: string[]): void;
 export type CloudClient = ReturnType<typeof createRebaseClient>;
 /**
  * Build an SDK client bound to a control-plane host, backed by the on-disk
@@ -200,7 +213,7 @@ export declare function emit<T>(human: () => void, json: JsonArg<T>): void;
  * `json: unknown` accepted a function without complaint, and four call sites in
  * `resources.ts` passed `() => ({ … })` — mirroring the human argument beside
  * it, which *is* a thunk. In JSON mode `printJson` then stringified a function,
- * which is `undefined`. So `rebase cloud resources`, `resources set` and two
+ * which is `undefined`. So `rebase cloud compute`, `compute set` and two
  * cluster commands printed the single word `undefined` on every piped or
  * `--json` run — and since this family forces JSON mode off a TTY, that is
  * every scripted use of them.
@@ -224,7 +237,64 @@ export type JsonArg<T> = T extends (...args: never[]) => unknown ? never : T;
  * `env` shipped this shape first, alone; this generalises it so every group
  * answers the same way.
  */
-export declare function emitHelp(command: string, actions: string[], human: () => void, extra?: Record<string, unknown>): void;
+export declare function emitHelp(command: string, actions: Array<string | HelpAction>, human: () => void, extra?: Record<string, unknown>): void;
+/**
+ * One action on a group's help page.
+ *
+ * The page used to exist twice: a hand-formatted template literal for a
+ * terminal, and a bare list of action WORDS for everything else. So the two
+ * answers to `--help` were not the same answer — piped, `rebase cloud env
+ * --help` said `["list","set","unset","reveal","pull"]` and not one description,
+ * not one flag, and not the sentence about build-time variables that is the
+ * whole reason the page exists. This family forces JSON mode off a TTY, so that
+ * was every scripted and every agent-driven read of it.
+ *
+ * One description, rendered twice.
+ */
+export interface HelpAction {
+    /** The action word: `set`, `backup restore`. */
+    action: string;
+    /** The usage tail after the word: `KEY=VALUE`, `<domain>`, `[-y]`. */
+    args?: string;
+    /** One line: what it does. */
+    description: string;
+    /** Flags this action takes of its own, `[flag, description]`. */
+    flags?: Array<[string, string]>;
+    /** The heading it sits under, on a page that groups its actions. */
+    section?: string;
+}
+/** A whole group page — `rebase cloud env --help`. */
+export interface GroupHelp {
+    /** The command words, no leading `rebase`: `cloud env`, or `cloud` itself. */
+    command: string;
+    /** The title's tail: "Environment variables". */
+    title: string;
+    actions: HelpAction[];
+    /** Options that belong to the group rather than to one action. */
+    options?: Array<[string, string]>;
+    /** Closing paragraphs — the things a reader gets wrong more than once. */
+    notes?: string[];
+}
+/**
+ * Flags every cloud command accepts, documented once.
+ *
+ * Lives here rather than in `action-help.ts` because both help renderers print
+ * it and `action-help` imports this module, not the other way round.
+ */
+export declare const GLOBAL_HELP_FLAGS: Array<[string, string]>;
+/**
+ * Flag names `parseCloudArgs` adds to every command in the family.
+ *
+ * Derived from `GLOBAL_CLOUD_FLAGS` rather than listed again — a second copy is
+ * how a global gains a spelling that the collision sweep does not know about.
+ * `--debug` is the one addition: `bin/rebase.js` takes it off `process.argv`
+ * itself, so no cloud spec declares it and every command still accepts it.
+ */
+export declare const GLOBAL_SPEC_KEYS: Set<string>;
+/**
+ * Print a group's page — the human one, and the same content as JSON when piped.
+ */
+export declare function printGroupHelp(page: GroupHelp): void;
 /**
  * Print a warning (+ optional hint) — in every output mode, always to stderr.
  *
@@ -347,6 +417,24 @@ export declare function parseCloudArgs<S extends arg.Spec>(opts: {
     flags: arg.Result<S & typeof GLOBAL_CLOUD_FLAGS>;
     positionals: string[];
 };
+/**
+ * Refuse an action word its group does not dispatch. Returns for `undefined`,
+ * which is every group's default action.
+ *
+ * The groups that switch on their action already do this in a `default:` case.
+ * The groups written as a chain of `if (action === "x") return …` did not: a
+ * word that matched nothing fell out of the chain into the *default* action, so
+ * `rebase cloud storage creat` listed the buckets and exited 0, and
+ * `rebase cloud billing usage` printed the account. Reporting a typo as a
+ * successful run of a different command is the failure mode this family exists
+ * to not have — an agent branching on the exit code learns nothing, and a person
+ * reads the output of a command they did not ask for.
+ *
+ * One spelling, so the code is `unknown_command` everywhere rather than the
+ * default `"error"` half of them used, and the hint always names the group's own
+ * `--help` rather than the index page.
+ */
+export declare function requireKnownAction(group: string, action: string | undefined, known: readonly string[]): void;
 /**
  * `--timeout <seconds>` as milliseconds, or `fallbackMs` when it was not given.
  *