@rebasepro/cli 0.11.1-canary.gfd39654 → 0.12.1-canary.g009ed95

package/bin/rebase.js

@@ -65,6 +65,53 @@ try {
     /* ignore */
 }
 
+/**
+ * `dist/` is gitignored, so in a fresh clone it does not exist until someone
+ * runs a build — and `rebase` is reached long before that: CONTRIBUTING's
+ * getting-started steps call `db push` and `dev` through it. Importing a
+ * missing module raises a bare ERR_MODULE_NOT_FOUND stack trace naming an
+ * internal path, which reads as a broken repository rather than a missing step.
+ *
+ * stderr, like the staleness warning above, so `--json` output stays parseable.
+ */
+if (!existsSync(distEntry)) {
+    const dev = existsSync(srcDir);
+    process.stderr.write(
+        `\x1b[31m✗ rebase CLI: not built yet — ${distEntry} is missing.\x1b[0m\n` +
+        (dev
+            ? "  Build it with: pnpm --filter @rebasepro/cli build\n" +
+              "  (or `pnpm build` from the repo root to build every package)\n"
+            : "  This install looks incomplete; try reinstalling @rebasepro/cli.\n")
+    );
+    process.exit(1);
+}
+
 const { entry } = await import("../dist/index.es.js");
 
-entry(process.argv);
+/**
+ * The CLI's last line of defence.
+ *
+ * `entry()` returns a promise and nothing was awaiting it, so anything a
+ * command threw surfaced as an unhandled rejection: Node's own stack trace,
+ * rooted in `dist/index.es.js`, with the CLI's bundled line numbers and no
+ * exit code of its own. "Collections directory not found" is a sentence a
+ * developer can act on; the same sentence under ten frames of bundle internals
+ * reads as a crash in Rebase.
+ *
+ * The message is the error's own — commands that already print something
+ * 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.
+ */
+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`);
+    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");
+    }
+    process.exit(1);
+});

package/dist/bundle.d.ts

@@ -1,4 +1,4 @@
-import { type NativeDependency, type RebaseBundleManifest, type RebaseBackendAppConfig } from "@rebasepro/types";
+import { type DeclaredStorageSources, type NativeDependency, type RebaseBundleManifest, type RebaseBackendAppConfig } from "@rebasepro/types";
 export declare const DEFAULT_BUNDLE_DIR = "dist-bundle";
 export interface BuildBundleOptions {
     projectRoot: string;
@@ -8,6 +8,13 @@ export interface BuildBundleOptions {
     outDir?: string;
     /** Runtime range from the manifest, recorded for compatibility checks. */
     runtimeRange: string;
+    /**
+     * The `storage` block of `rebase.json` — which buckets this project uses.
+     *
+     * Passed in rather than re-read here so `rebase.json` is parsed and validated
+     * once, by the command that owns it.
+     */
+    storage?: DeclaredStorageSources;
     /** Skip type checking. Faster, and strictly worse — for iteration only. */
     skipTypeCheck?: boolean;
     /** Skip regenerating the Drizzle schema from the collections. */
@@ -37,7 +44,7 @@ export interface BuildBundleResult {
  * says exactly how to proceed, while a false positive would hand back the crash
  * loop this exists to prevent.
  */
-export declare function detectStorageAuthorize(compiledConfigDir: string): boolean;
+export declare function detectStorageAuthorize(compiledConfigDir: string, depth?: number): boolean;
 /**
  * Detect native code in the dependency closure.
  *
@@ -61,6 +68,41 @@ export declare function detectNativeDependencies(projectRoot: string, declared:
  * own config package already travels inside the bundle.
  */
 export declare function collectDeclaredDependencies(projectRoot: string): Record<string, string>;
+/** One `@rebasepro/*` 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;
+}
+export interface FrameworkDepDrift {
+    /** Declared at a version that can never reach the CLI's own. */
+    behind: DeclaredFrameworkDep[];
+    /**
+     * The distinct lower bounds found across all declared `@rebasepro/*`, when
+     * there is more than one — the project is pinning mixed-era framework
+     * packages against each other.
+     */
+    disagreeing: string[];
+}
+/**
+ * Find `@rebasepro/*` dependencies pinned to a version older than this CLI.
+ *
+ * This is the only place a developer can be told. In development, every
+ * `@rebasepro/*` resolves through pnpm's `link:`/`workspace:` overrides to the
+ * checkout, so the version STRINGS in package.json are never exercised — the
+ * project runs fine locally on whatever is on disk, and the declared numbers are
+ * first honoured when the runtime npm-installs them from a bundle in the cloud.
+ * A project scaffolded at 0.10.0 therefore keeps working on a developer's
+ * machine indefinitely while being, in the cloud, a 0.10.0 driver.
+ *
+ * That matters because the image supplies only `@rebasepro/server`; the database
+ * driver comes from these declarations and a newer runtime never updates it.
+ * Every package.json is scanned, `dependencies` and `devDependencies` both,
+ * because they have to be bumped together and the one that gets forgotten is the
+ * one nobody looks at.
+ */
+export declare function detectFrameworkDepDrift(projectRoot: string, cliVersion: string): FrameworkDepDrift;
 /**
  * Rewrite relative import specifiers in emitted JavaScript so Node can resolve them.
  *
@@ -94,11 +136,10 @@ export declare function normalizeEsmSpecifiers(outDir: string): {
  * deployed green, and answered 404 on every one of them, with the file still
  * sitting in the repository looking exactly like the server.
  *
- * A project that means to keep its own entrypoint declares the app as
- * `"type": "custom"`, which builds the repository's Dockerfile instead — which
- * is what {@link synthesizeManifest} already infers for a manifest-less repo
- * carrying one. The warning names that route rather than implying the file is
- * a mistake.
+ * A project that means to keep its own entrypoint runs `rebase eject`, which
+ * writes the entrypoint, a Dockerfile and a compose file together and flips the
+ * backend to `runtime: "custom"`. The warning names that route rather than
+ * implying the file is a mistake.
  */
 export declare function findUnusedServerEntry(projectRoot: string, functionsDir: string): string | undefined;
 /**
@@ -151,8 +192,15 @@ export declare function foldStaticIntoBundle(options: {
     bundleDir: string;
     /** Directory of built frontend assets (the static app's `output`). */
     assetsDir: string;
+    /** The app's name in `rebase.json`. Names its directory inside the bundle. */
+    appName: string;
+    /** Public base path this app is served under. */
+    path: string;
+    /** Serve `index.html` for unmatched paths under `path`. */
+    spa: boolean;
 }): {
     fileCount: number;
+    dir: string;
 };
 export declare function buildStaticBundle(options: {
     projectRoot: string;
@@ -160,8 +208,13 @@ export declare function buildStaticBundle(options: {
     assetsDir: string;
     outDir: string;
     runtimeRange: string;
+    /** Public base path. Default `/` — a standalone bundle owns its origin. */
+    path?: string;
+    /** Serve `index.html` for unmatched paths. Default `true`. */
+    spa?: boolean;
 }): {
     outDir: string;
     manifest: RebaseBundleManifest;
     fileCount: number;
 };
+export declare function resolveCliVersion(): string;

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

@@ -84,6 +84,39 @@ export interface ProjectLink {
 export declare function readLink(cwd?: string): ProjectLink | null;
 export declare function writeLink(link: ProjectLink, cwd?: string): void;
 export declare function removeLink(cwd?: string): boolean;
+/**
+ * Flags that may appear anywhere on a `rebase cloud` line, including *before*
+ * the resource group.
+ *
+ * They have to be declared wherever positionals are resolved, because `arg`'s
+ * `permissive: true` does not merely tolerate an undeclared flag — it pushes it
+ * into `_` alongside the positionals, and for a flag that takes a value it
+ * pushes the value in too. So `cloud --project acme storage create` parsed
+ * without this spec yields `_` of `["--project", "acme", "storage", "create"]`,
+ * and the group reads as `"acme"`: a real project name, in the group position,
+ * dispatching to nothing. Skipping tokens that start with `-` does not save you
+ * there — the damage is the orphaned value, which looks exactly like a
+ * positional.
+ *
+ * Only genuinely global flags belong here. Group-specific ones (`--bucket`,
+ * `--region`, …) are declared by the handler that owns them and always follow
+ * the group, so they cannot shift the group or action.
+ *
+ * `-p` is `--project` in eighteen places and `--password` in `login`. That
+ * ambiguity does not matter to the one caller that reads this spec: it resolves
+ * positionals and never looks at a flag's value, so all it needs to know is
+ * that `-p` takes one. Anything that wants the value must keep declaring it
+ * itself, with the meaning its own command gives it.
+ */
+export declare const GLOBAL_CLOUD_FLAGS: {
+    readonly "--json": BooleanConstructor;
+    readonly "--yes": BooleanConstructor;
+    readonly "--help": BooleanConstructor;
+    readonly "--project": StringConstructor;
+    readonly "-p": "--project";
+    readonly "-y": "--yes";
+    readonly "-h": "--help";
+};
 /**
  * The raw project reference to operate on: explicit `--project` flag wins,
  * otherwise the linked project. Exits with guidance when neither is present.
@@ -134,6 +167,26 @@ export declare function printJson(value: unknown): void;
  * call is what guarantees a command can never print a table AND a JSON blob.
  */
 export declare function emit(human: () => void, json: unknown): void;
+/**
+ * Print a warning (+ optional hint) — in every output mode, always to stderr.
+ *
+ * `emit` is for a command's *result*, and JSON mode legitimately replaces the
+ * human rendering of one. A warning is not a result: it says the command is
+ * about to do something the caller may not have meant, and that is exactly as
+ * true when the output is piped. Gating one on `!isJsonMode()` deleted it
+ * precisely where nobody was watching the terminal — a `--source` deploy ejected
+ * a live project off the managed runtime and said so only to a TTY that wasn't
+ * there.
+ *
+ * stdout carries the JSON value and nothing else, so warnings go to stderr:
+ * a machine parser reading stdout cannot be corrupted by one. Only the
+ * *formatting* may depend on the mode — colour and indentation for a terminal,
+ * plain ASCII otherwise. Whether a warning is emitted at all may not.
+ *
+ * Anything a caller might branch on belongs in the JSON payload as well; stderr
+ * is for whoever reads the transcript afterwards.
+ */
+export declare function warn(message: string, hint?: string): void;
 /** Print an error (+ optional hint) and exit non-zero. Never returns. */
 export declare function fail(message: string, hint?: string, code?: string): never;
 /**

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

@@ -46,5 +46,69 @@ export declare function timeAgo(value: string | Date | undefined, now: Date): st
 export declare function isManagedProject(project: DeployProjectRow | undefined, latest: DeploySourceRow | undefined): boolean;
 /** What a `deploy` with nothing attached will build, in the words to print. */
 export declare function planBareDeploy(project: DeployProjectRow | undefined, latest: DeploySourceRow | undefined, now: Date): BareDeployPlan;
+/**
+ * A warning attached to a deploy: printed for the human, carried in the JSON.
+ *
+ * `code` is the stable half — the message is prose and will be reworded, so it
+ * is the code that CI or an agent branches on.
+ */
+export interface DeployWarning {
+    code: string;
+    message: string;
+    hint?: string;
+}
+/** `code` of the warning below, and the field name it sets in the payload. */
+export declare const EJECTS_MANAGED_RUNTIME = "ejects_managed_runtime";
+/** The one sentence that says a source build undoes `runtimeMode: managed`. */
+export declare function ejectWarning(projectRef: string): DeployWarning;
+/** How a container-image deploy was asked for — the input to both rules below. */
+export interface EjectContext {
+    /** The project currently runs on the managed runtime. */
+    managed: boolean;
+    /** `--source` was passed: build this directory. */
+    source: boolean;
+    /** `--force` was passed: eject on purpose. */
+    force: boolean;
+}
+/**
+ * Why a container-image deploy of a managed project is refused — or `undefined`
+ * to let it through.
+ *
+ * Every path below this point builds a container image, and a successful one
+ * sets `runtimeMode: "custom"` server-side. So the question is never "which flag
+ * was used" but "did the caller ask to leave the managed runtime", and only
+ * `--force` answers it.
+ *
+ * `--source` used to be read as answering it too, on the theory that uploading a
+ * build context is self-evidently a deliberate eject. It is not: `--source`
+ * picks *which source* gets built — this directory, rather than the stale
+ * archive the control plane is holding — and the eject is a side effect of the
+ * answer. That is exactly how a live project got flipped to `custom` by someone
+ * whose actual intent was "deploy what I have here", and it is the same
+ * ignorance the bare form is refused for. Same ignorance, same refusal.
+ */
+export declare function ejectRefusal(opts: EjectContext, projectRef: string): {
+    message: string;
+    hint: string;
+    code: string;
+} | undefined;
+/**
+ * Which warnings a container-image deploy has earned.
+ *
+ * Pure, and separate from the printing, because the printing is what went
+ * wrong: the eject warning used to be written inline behind `!isJsonMode()`, so
+ * the fact that a deploy ejects a managed project existed only as a side effect
+ * of a TTY being attached. Deciding here, emitting once at the call site, means
+ * the decision cannot be output-mode-dependent again.
+ *
+ * The condition is just `managed`: anything reaching this point is a container
+ * image build that `ejectRefusal` has already let through, and on a managed
+ * project that is an eject however it was spelled. A caller who passed `--force`
+ * knows — the warning is for the transcript and the payload, which is what
+ * anyone reviewing the deploy afterwards actually reads.
+ */
+export declare function deployWarnings(opts: EjectContext, projectRef: string): DeployWarning[];
+/** The warning half of a deploy's JSON payload — merged into whatever it emits. */
+export declare function warningPayload(warnings: DeployWarning[]): Record<string, unknown>;
 export declare function deployCommand(rawArgs: string[], projectRef: string): Promise<void>;
 export declare function logsCommand(rawArgs: string[], projectRef: string): Promise<void>;

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

@@ -1 +1,24 @@
+/**
+ * Positional tokens after `rebase cloud` (group, action, …).
+ *
+ * Two things stop a flag being mistaken for the group. `GLOBAL_CLOUD_FLAGS` is
+ * declared so `arg` *consumes* the flags that may precede it — critically
+ * together with their values, which is the half that filtering cannot do. The
+ * leading-`-` skip then covers a flag nobody declared, so an unrecognised
+ * boolean shifts nothing.
+ *
+ * Only leading tokens are skipped: past the group and action, an undeclared
+ * flag and its value are somebody else's positionals and none of our business.
+ * A flag this file has never heard of, that takes a value, placed before the
+ * group, is the one shape still unresolvable here — there is no way to know
+ * whether the token after it is its value or the group, and guessing either way
+ * is worse than the handler reporting an unknown group.
+ *
+ * Exported so its tests can drive the real thing. The dispatch test used to
+ * re-implement it locally as `slice(3).filter(a => !a.startsWith("-"))` — which
+ * filtered flags, while this function did not — so the test asserted the
+ * behaviour we wanted against a copy that had it, and stayed green for as long
+ * as the real dispatcher was broken.
+ */
+export declare function positionals(rawArgs: string[]): string[];
 export declare function cloudCommand(subcommand: string | undefined, rawArgs: string[]): Promise<void>;

package/dist/commands/dev.d.ts

@@ -1 +1,17 @@
+/** Well-known filename the backend writes its actual port to. */
+export declare const DEV_PORT_FILENAME = ".rebase-dev-port";
+/**
+ * Compute a deterministic port from the project root path.
+ * Range: 3001–3999 (avoids privileged ports and common services).
+ * Two different project directories will almost always get different ports.
+ */
+export declare function getProjectPort(projectRoot: string): number;
+/**
+ * Resolve the best starting port for this project:
+ * 1. Explicit --port flag (highest priority)
+ * 2. PORT env var
+ * 3. Previously used port from .rebase-dev-port (port affinity across restarts)
+ * 4. Deterministic hash from project path (unique per project)
+ */
+export declare function resolveStartPort(projectRoot: string, explicitPort?: number): number;
 export declare function devCommand(rawArgs: string[]): Promise<void>;

package/dist/commands/eject.d.ts

@@ -0,0 +1 @@
+export declare function ejectCommand(rawArgs?: string[]): Promise<void>;

package/dist/commands/init.d.ts

@@ -1,19 +1,23 @@
 import type { PackageManager, PMCommands } from "../utils/package-manager";
-/** Returns an error message, or null when the name is a valid package name. */
-export declare function validateProjectName(name: string): string | null;
-export type TemplatePreset = "blog" | "ecommerce" | "blank";
 /**
- * How much of Rebase to scaffold.
+ * Every scaffolded file that carries a `{{PLACEHOLDER}}`.
  *
- * `cms` is the full triad (config + backend + frontend). `baas` is the backend
- * alone, serving the database over REST with no collection files and no UI.
- */
-/**
- * `cms` scaffolds BaaS + the admin UI; `baas` scaffolds the API alone. The
- * values match `RebaseBackendConfig.mode`, which is what the generated backend
- * sets — the labels below are what users actually read.
+ * Exported because it is the single source of truth: `init.test.ts` reads it and
+ * asserts that every template file containing `{{` appears here. It used to be a
+ * local, with the test harness keeping a *second* copy — so the two drifted, and
+ * a test built on the copy could not observe the production list at all.
+ *
+ * The drift shipped: `docker-compose.yml` arrived with the self-host work
+ * (26fd5259c) and was added to neither, so every scaffolded project got a literal
+ * `name: {{PROJECT_NAME}}`. In YAML `{{...}}` is a map, not a string, so the
+ * documented `docker compose up` path failed on the file before doing anything:
+ *
+ *   yaml: unmarshal errors: line 28: cannot unmarshal !!map into string
  */
-export type TemplateFlavor = "cms" | "baas";
+export declare const TEMPLATE_PLACEHOLDER_FILES: string[];
+/** Returns an error message, or null when the name is a valid package name. */
+export declare function validateProjectName(name: string): string | null;
+export type TemplatePreset = "blog" | "ecommerce" | "blank";
 export interface InitOptions {
     projectName: string;
     git: boolean;
@@ -26,8 +30,8 @@ export interface InitOptions {
     preset: TemplatePreset;
     /** Whether `preset` came from an explicit --template rather than the default. */
     explicitPreset?: boolean;
-    /** Which parts of Rebase to scaffold. */
-    flavor: TemplateFlavor;
+    /** Scaffold the backend alone, with no admin panel and no collections. */
+    headless: boolean;
     /** Detected package manager (pnpm or npm). */
     pm: PackageManager;
     /** Command helpers for the detected PM. */
@@ -42,7 +46,7 @@ export interface InitOptions {
 export interface BuildQuestionsParams {
     nameArg?: string;
     templateArg?: TemplatePreset;
-    flavorArg?: TemplateFlavor;
+    headlessArg?: boolean;
     hasGitFlag: boolean;
     hasInstallFlag: boolean;
     pm: PackageManager;

package/dist/fold-static.d.ts

@@ -4,6 +4,8 @@ export interface FoldableManifest {
         type?: string;
         build?: string;
         output?: string;
+        path?: string;
+        spa?: boolean;
     }>;
 }
 export interface FoldOptions {
@@ -11,36 +13,60 @@ export interface FoldOptions {
     manifest: FoldableManifest;
     /** The backend bundle directory, already written. */
     bundleDir: string;
-    /** Skip running the app's own build command; fold what is already built. */
+    /** Skip running each app's own build command; fold what is already built. */
     skipBuild?: boolean;
     log?: (message: string) => void;
 }
 export interface FoldOutcome {
     appName: string;
     fileCount: number;
+    /** Public base path this app was folded in at. */
+    path: string;
+}
+/** A static app as folding sees it, with the manifest's defaults applied. */
+export interface FoldableApp {
+    name: string;
+    build?: string;
+    output?: string;
+    /** Public base path, defaulted to `/`. */
+    path: string;
+    /** SPA fallback, defaulted to `true`. */
+    spa: boolean;
 }
 /**
- * Which static app, if any, should be served by the backend.
+ * Every static app in the manifest, in mount order.
  *
- * Exactly one `static` app is folded. With several, folding would have to choose,
- * and silently picking one of two websites is worse than doing nothing — so it
- * declines and names what it saw. Pure, so the decision is testable without a
- * filesystem.
+ * Longest path first, so the `/`-rooted app is registered last — its catch-all
+ * would otherwise claim its siblings' URLs. Pure, so the ordering is testable
+ * without a filesystem.
  */
-export declare function selectFoldableApp(manifest: FoldableManifest): {
-    app?: {
+export declare function foldableApps(manifest: FoldableManifest): {
+    apps: FoldableApp[];
+    /** Apps that cannot be folded, and why. */
+    skipped: {
         name: string;
-        build?: string;
-        output?: string;
-    };
-    /** Why nothing will be folded, when that is the answer. */
-    reason?: string;
+        reason: string;
+    }[];
 };
 /**
- * Build the project's frontend and fold it into the backend bundle.
+ * Assert a built app's assets are actually rooted at the path it is served from.
+ *
+ * An app mounted at `/admin` but built with Vite's default `base: "/"` emits
+ * `<script src="/assets/index-a1b2.js">`. The server serves `index.html` fine
+ * and 404s every asset: a blank page, no server error, nothing in the logs. It
+ * is the single most expensive silent failure in this design, so it is a build
+ * error rather than a runtime surprise.
+ *
+ * Only `<script src>` and `<link href>` are inspected — those are what a bundler
+ * rewrites through `base`. Author-written anchors and canonical URLs are not
+ * evidence of a misbuild.
+ */
+export declare function assertBuiltForPath(indexHtml: string, basePath: string, appName: string): void;
+/**
+ * Build the project's static apps and fold them into the backend bundle.
  *
  * Throws rather than exiting, so the caller decides whether a missing frontend
  * should fail its command — a `build` may reasonably want to stop, and so should
  * a deploy, but that is not this function's call to make.
  */
-export declare function foldFrontendIntoBundle(options: FoldOptions): Promise<FoldOutcome | null>;
+export declare function foldFrontendIntoBundle(options: FoldOptions): Promise<FoldOutcome[]>;

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from "./commands/schema";
 export * from "./commands/db";
 export * from "./commands/dev";
 export * from "./commands/build";
+export * from "./commands/eject";
 export * from "./commands/start";
 export * from "./commands/auth";
 export * from "./commands/doctor";