@rebasepro/cli 0.23.0 → 0.24.1-canary.g19596ef

package/dist/commands/dev.d.ts

@@ -1,3 +1,4 @@
+import { type AppAddress, type RebaseProjectManifest } from "@rebasepro/types";
 import { type PreparedDatabase } from "../dev-db/prepare.js";
 /**
  * The line the watcher prints when it is about to run the entry again.
@@ -29,6 +30,21 @@ import { type PreparedDatabase } from "../dev-db/prepare.js";
  * Exported so `dev-crash-marker.test.ts` can hold the running tsx to it.
  */
 export declare const WATCHER_RESTART_MARKER: RegExp;
+/**
+ * Calls `onLine` with each line a child process writes to `stream`.
+ *
+ * A pipe hands over whatever has been written so far, so one line can arrive
+ * in two chunks. Split chunk by chunk, "Server running at http://localhost:3001"
+ * could read as two fragments that neither matched, and `rebase dev` then
+ * never announced the backend or started the admin panel. So the piece after
+ * the last newline is held for the next chunk, decoded as UTF-8 across chunk
+ * boundaries. A held piece is handed over at the end of the stream, or after
+ * `idleFlushMs` with nothing more written, so a prompt or a progress line
+ * still shows when it is written.
+ *
+ * Exported for its test.
+ */
+export declare function forEachOutputLine(stream: NodeJS.ReadableStream | null | undefined, onLine: (line: string) => void, idleFlushMs?: number): void;
 /**
  * The corrected banner line, when the backend says it moved port.
  *
@@ -65,15 +81,50 @@ export declare function portMovedNotice(line: string): {
  *
  * @param projectRoot   Absolute path the relative entries are resolved against.
  * @param paths         The `REBASE_DEV_*` map from {@link devRuntimeEnv}.
- * @param includeConfig Whether `config/` is watched here. It is only when
- *                      auto-generation is off; with `--generate` a dedicated
- *                      watcher already regenerates the schema and SDK, and tsx
- *                      restarts on the files that produces.
  */
 export declare function devWatchIncludes(projectRoot: string, paths: {
     REBASE_DEV_FUNCTIONS?: string;
     REBASE_DEV_CRONS?: string;
-}, includeConfig: boolean): string[];
+}): string[];
+/**
+ * The file dev writes to restart the backend, or `null` when tsx would not see it.
+ *
+ * Outside the project, so nothing appears in the developer's tree, and keyed by
+ * the project so two `rebase dev`s never restart each other. tsx ignores every
+ * path with a dot-named segment (its built-in `**\/.*\/**`), so a trigger under
+ * `.rebase/` — or under a TMPDIR inside a dot directory — would never fire; in
+ * that case there is no trigger and {@link devWatchArgs} leaves the
+ * collections to tsx, as before.
+ */
+export declare function devRestartTrigger(projectRoot: string): string | null;
+/**
+ * The `tsx watch` argument list for the backend (unquoted).
+ *
+ * One save of a collection file must restart the backend once. The runtime
+ * `import()`s the collections, so tsx tracks them as dependencies and used to
+ * restart the moment a file was saved — before dev had regenerated
+ * `schema.generated.ts`. That boot warned "schema.generated.ts no longer
+ * describes the database … Run `rebase schema generate`", telling the reader to
+ * run what dev was running at that moment, and the regeneration then rewrote
+ * the file and restarted the backend a second time. So tsx is told to leave the
+ * collections directory alone (`--exclude` wins over its dependency tracking),
+ * and dev restarts the backend itself, once, after the regeneration — through
+ * `restartTrigger`, which tsx watches.
+ *
+ * Every included directory also gets tsx's own default ignores, made absolute.
+ * tsx resolves those defaults (`**\/node_modules/**`, `**\/.*`, …) against its
+ * cwd, which is `backend/`, so they never reached `config/`, a sibling: chokidar
+ * walked `config/node_modules` — following symlinks — before tsx spawned the
+ * backend at all, and kept every file in it watched. In the monorepo's example
+ * app that was 17 s before the first backend line and 1,400 open files, and any
+ * install (or another checkout's Vite build writing `.vite-temp` deep inside
+ * that tree) restarted the backend. A `.DS_Store` or an editor swap file in
+ * `config/` restarted it too.
+ */
+export declare function devWatchArgs(projectRoot: string, paths: {
+    REBASE_DEV_FUNCTIONS?: string;
+    REBASE_DEV_CRONS?: string;
+}, entryTarget: string, restartTrigger: string | null): string[];
 /** Well-known filename the backend writes its actual port to. */
 export declare const DEV_PORT_FILENAME = ".rebase-dev-port";
 /**
@@ -84,12 +135,6 @@ export declare const DEV_PORT_FILENAME = ".rebase-dev-port";
  * template still says this number, so the two cannot drift apart in silence.
  */
 export declare const SCAFFOLD_DEFAULT_PORT = 3001;
-/**
- * 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;
 /**
  * Which rung of the ladder below decided the port.
  *
@@ -138,6 +183,53 @@ export declare function resolveStartPort(projectRoot: string, explicitPort?: num
  * Exported for its test.
  */
 export declare function databaseEndpoint(url: string | null | undefined): string | null;
+/**
+ * What the start banner needs to know about a project's static apps.
+ *
+ * `rebase dev` runs one frontend: Vite in `frontend/`, at the root of its own
+ * localhost port, whatever path or hostname the manifest declares for it. So an
+ * app's local address and its deployed one are different things, and for an app
+ * with a hostname of its own they share nothing at all — appending its address
+ * to the local URL would print `http://localhost:5173https://admin.example.com`.
+ */
+export interface DevStaticShape {
+    declaresStaticApp: boolean;
+    /** The declared app whose `root` is the `frontend/` that `rebase dev` runs, if one is. */
+    served?: {
+        appName: string;
+        address: AppAddress;
+    };
+    /** Where the CMS is, when an app declares one. */
+    cms?: {
+        appName: string;
+        /** Always a path. */
+        path: string;
+        /** The serving app's hostname, when its `path` names one. */
+        host?: string;
+        /** Whether the app serving it is the one `rebase dev` runs, so it has a local address. */
+        servedLocally: boolean;
+    };
+}
+/**
+ * Read {@link DevStaticShape} out of a loaded manifest. Exported for its test.
+ *
+ * Which declared app is running is decided by its `root` being `frontend/`,
+ * because that directory is what `startFrontend` launches and nothing else is.
+ * When no declared app has that root, which app serves the CMS cannot be told,
+ * and it is read as the frontend that does run — what the banner has always
+ * assumed, and right for every project `rebase init` scaffolds.
+ */
+export declare function devStaticShape(manifest: RebaseProjectManifest, projectRoot: string, frontendDir: string | null): DevStaticShape;
+/**
+ * The banner's lines for a project with a frontend. Exported for its test.
+ *
+ * Every address is printed whole, once: the local one Vite answers on, and —
+ * for an app with a hostname — the https URL it answers on once deployed, on a
+ * line of its own beneath it. A CMS in an app `rebase dev` does not run gets its
+ * deployed address and a note saying so, rather than a localhost URL that the
+ * running frontend's SPA fallback would answer with the wrong app.
+ */
+export declare function appBannerLines(frontendUrl: string, api: string, shape: DevStaticShape): Array<[string, string]>;
 /**
  * The `↳ Database =` line: which database, why it was chosen, and where it is.
  *
@@ -206,7 +298,6 @@ export declare const DEV_FLAGS: {
     readonly "--backend-only": BooleanConstructor;
     readonly "--frontend-only": BooleanConstructor;
     readonly "--port": NumberConstructor;
-    readonly "--generate": BooleanConstructor;
     /**
      * Point this run at a database of your own, ahead of everything else.
      *
@@ -220,9 +311,23 @@ export declare const DEV_FLAGS: {
     readonly "-b": "--backend-only";
     readonly "-f": "--frontend-only";
     readonly "-P": "--port";
-    readonly "-g": "--generate";
     readonly "--no-db": BooleanConstructor;
 };
+/** What {@link ensureGeneratedSchema} did at startup. */
+export type SchemaGeneration = "generated" | "skipped" | "failed";
+/**
+ * Whether dev must still run the driver's `schema stale --fix` before the
+ * backend boots.
+ *
+ * Not after a regeneration that succeeded: that wrote `schema.generated.ts`
+ * from these collections with this driver, moments earlier, and `stale`
+ * compares the file against the same generator — it can only answer "nothing
+ * stale", and it cost a driver process (~0.6 s) on every start. The repair it
+ * exists for, a library upgrade that changed what the generator derives, is
+ * exactly what the regeneration already did. When generation was skipped or
+ * failed, the preflight is the remaining safety net and still runs.
+ */
+export declare function needsStaleSchemaPreflight(generation: SchemaGeneration): boolean;
 /**
  * One variable's value out of `.env` text, or undefined when it has none.
  *
@@ -251,4 +356,67 @@ export declare function readEnvValue(envText: string, key: string): string | und
  * it is invisible in any assertion about the push's *outcome*.
  */
 export declare function schemaPushArgv(databaseUrl: string | undefined): string[];
+/**
+ * Start-up's independent halves, overlapped rather than run one after another.
+ *
+ * `rebase dev` used to regenerate the schema and the SDK, then derive the
+ * resource graph (every collection evaluated again, in this process), then
+ * start the managed database and wait for it — about a second when it was not
+ * already running — and only then spawn the backend. None of the three reads
+ * what another writes: the generators read `config/` and write
+ * `backend/src/schema.generated.ts` and `generated/sdk/`; the derivation reads
+ * `config/resources.ts` and the collections; the database needs neither, and
+ * `schema generate` never connects to one. So `database` starts first and is
+ * collected last.
+ *
+ * `preflight` is the exception, and the reason this is not one `Promise.all`:
+ * on the `--docker` path it pushes the schema the generators have just written,
+ * so it still runs after them.
+ *
+ * A database that fails to start is reported where it always was — after the
+ * generators' and the preflight's output — rather than ahead of it, and it is
+ * never an unhandled rejection while they run.
+ *
+ * Exported for its test.
+ */
+export declare function overlapDevStartup<T>(steps: {
+    generate: () => Promise<SchemaGeneration>;
+    preflight: () => Promise<void>;
+    /** Resolve and, for the managed database, start it. `null` when this run starts none. */
+    database: (() => Promise<T>) | null;
+}): Promise<{
+    schemaGeneration: SchemaGeneration;
+    database: T | null;
+}>;
+/**
+ * Whether the admin panel can start beside the backend instead of after it.
+ *
+ * Vite has to be told the backend's URL when it starts (`VITE_API_URL`), and
+ * the backend's port is only certain once it has bound — so the admin panel
+ * used to wait for "Server running at", and the time to it was the backend's
+ * whole boot plus Vite's start. It can start beside the backend whenever the
+ * port the backend will bind is known in advance:
+ *
+ * - **named with `--port`**: the server binds it or refuses to start, never
+ *   walks past it (`REBASE_DEV_PORT_EXPLICIT`), and `pinnedPortRefusal` has
+ *   already checked that nothing answers there;
+ * - **free, and the port the backend tries first**: the server tries the port
+ *   its last run landed on before the one it is given (`.rebase-dev-port`), so
+ *   a remembered port must be this one — the "kept from the last run" rung —
+ *   or absent, which it is after every clean exit, and the derived port is
+ *   then the one tried. A port something already answers on would make the
+ *   backend move, so that case keeps the old order.
+ *
+ * Nothing here can rule out another process taking the port in the second the
+ * backend boots, so `devCommand` still compares the announced port with the
+ * one Vite was given and restarts the admin panel when they differ.
+ *
+ * Exported for its test.
+ */
+export declare function frontendCanStartWithBackend(options: {
+    projectRoot: string;
+    port: number;
+    pinned: boolean;
+    probe?: (host: string, port: number) => Promise<boolean>;
+}): Promise<boolean>;
 export declare function devCommand(rawArgs: string[]): Promise<void>;

package/dist/commands/doctor.d.ts

@@ -57,4 +57,9 @@ export declare const DOCTOR_FLAGS: {
     readonly "--sdk": StringConstructor;
     readonly "-k": "--sdk";
 };
+/**
+ * The line handed to the driver, every path on it resolved from where the
+ * command was run — the driver runs in `backend/`. See `utils/path-flags.ts`.
+ */
+export declare function doctorDriverArgs(rawArgs: string[], cwd: string): string[];
 export declare function doctorCommand(rawArgs: string[]): Promise<void>;

package/dist/commands/generate_sdk.d.ts

@@ -1,8 +1,9 @@
 /**
  * CLI command: generate-sdk
  *
- * Reads collection definitions from a specified directory (default: ./config/collections),
- * generates a typed TypeScript SDK, and writes it to the output directory (default: ./generated/sdk).
+ * Reads every collection file in a directory (default: ./config/collections) —
+ * the files the backend serves, not the barrel's list — generates a typed
+ * TypeScript SDK, and writes it to the output directory (default: ./generated/sdk).
  *
  * Uses jiti for dynamic TypeScript import of collection files.
  */
@@ -21,8 +22,34 @@ interface GenerateSDKArgs {
     from?: string;
     /** Bearer token for the contract endpoint. Falls back to REBASE_SERVICE_KEY. */
     token?: string;
+    /**
+     * Also register the generated `Database` for server-side code: write the
+     * types and the `Register` augmentation into `config/generated/`. See
+     * {@link writeRegistration}.
+     */
+    register?: boolean;
+    /**
+     * The directory holding `rebase.json`, where `--register` is remembered.
+     * Found from `cwd` when not given.
+     */
+    projectRoot?: string;
     help?: boolean;
 }
+/** What `--register` writes, and what marks a project as having opted in. */
+export declare const REGISTER_FILE = "register.ts";
+/**
+ * Where `--register` writes: `generated/` beside the collections directory,
+ * which is `config/generated/` in a scaffolded project.
+ *
+ * Inside `config/` because that is the one directory both compiles of a
+ * collection file include: the backend's program (it includes
+ * `../config/**`) and the `config` package's own `tsc`. A registration
+ * there that imported `../generated/sdk/database.types` pulled a file from
+ * outside `config/` into that package's program, which TypeScript refuses
+ * (the file is not under its `rootDir`) — so the types are copied in beside
+ * the registration rather than imported from the SDK.
+ */
+export declare function registrationDir(collectionsDir: string): string;
 /**
  * The base URL to show in the printed usage example.
  *

package/dist/commands/init.d.ts

@@ -1,4 +1,5 @@
 import type { PackageManager, PMCommands } from "../utils/package-manager.js";
+import { type AgentKey } from "./skills.js";
 /**
  * Every scaffolded file that carries a `{{PLACEHOLDER}}`.
  *
@@ -42,6 +43,10 @@ export interface InitOptions {
     setupKey?: string;
     /** Control-plane URL the setup key is redeemed against. */
     cloudUrl?: string;
+    /** AI coding agents to install skills and the MCP server for. */
+    agents: AgentKey[];
+    /** Whoever reads the closing steps can answer a prompt (a TTY, not --yes). */
+    interactive?: boolean;
 }
 export interface BuildQuestionsParams {
     nameArg?: string;
@@ -91,6 +96,14 @@ export type InitQuestion = {
     default: unknown;
     when?: (answers: Record<string, unknown>) => boolean;
 };
+/**
+ * Why `input` cannot be this project's `DATABASE_URL`, or null when it can.
+ *
+ * The runtime refuses anything that is not a URL, and only a Postgres one can
+ * work, so `init` refuses the same — before the scaffold is written around it.
+ * The value itself is never repeated back: it may hold a password.
+ */
+export declare function databaseUrlProblem(input: string): string | null;
 export declare function buildInitQuestions(params: BuildQuestionsParams): InitQuestion[];
 /**
  * The `cd` a user must type to enter the new project.
@@ -105,21 +118,109 @@ export declare function printInitHelp(): void;
 export declare function createRebaseApp(rawArgs: string[]): Promise<void>;
 /** The flags `rebase init` takes. */
 export declare const INIT_FLAGS: {
-    readonly "--git": BooleanConstructor;
-    readonly "--install": BooleanConstructor;
-    readonly "--no-install": BooleanConstructor;
-    readonly "--database-url": StringConstructor;
-    readonly "--introspect": BooleanConstructor;
-    readonly "--template": StringConstructor;
-    readonly "--headless": BooleanConstructor;
-    readonly "--project": StringConstructor;
-    readonly "--setup-key": StringConstructor;
-    readonly "--yes": BooleanConstructor;
-    readonly "-g": "--git";
-    readonly "-i": "--install";
-    readonly "-t": "--template";
-    readonly "-y": "--yes";
+    "--git": BooleanConstructor;
+    "--install": BooleanConstructor;
+    "--no-install": BooleanConstructor;
+    "--database-url": StringConstructor;
+    "--introspect": BooleanConstructor;
+    "--template": StringConstructor;
+    "--headless": BooleanConstructor;
+    "--project": StringConstructor;
+    "--setup-key": StringConstructor;
+    "--agent": [StringConstructor];
+    "--yes": BooleanConstructor;
+    "-a": string;
+    "-g": string;
+    "-i": string;
+    "-t": string;
+    "-y": string;
 };
+/** What the closing "Next steps" depend on: the project's shape, and what `init` managed to do. */
+export interface InitNextStepsInput {
+    headless: boolean;
+    /** `--database-url` was given, so `.env` names the user's own database. */
+    ownDatabase: boolean;
+    /** Introspection was asked for. */
+    introspect: boolean;
+    /** Introspection ran and produced collections. */
+    introspected: boolean;
+    /** Dependencies were installed. */
+    installed: boolean;
+    /** What the reader types to enter the project; "" when they are in it. */
+    cdTarget: string;
+    pm: PMCommands;
+}
+/**
+ * The "Next steps" `init` closes on, every command one that works as printed.
+ *
+ * Each flavour has its own steps, and the branch for one flavour must not run
+ * for another. The `--database-url` branch was checked before the headless one,
+ * so `init --headless --database-url` — the documented BaaS path — opened on
+ * `pnpm run db:push`: a script the headless scaffold does not have, for a
+ * schema it does not declare (its tables are the developer's own), with an
+ * Atlas it does not install. `init-next-steps.test.ts` holds every script
+ * named here to the scaffold it is printed for.
+ */
+export declare function initNextSteps(input: InitNextStepsInput): string[];
+/**
+ * The closing "AI Agent Skills" lines, each command one its reader can run.
+ *
+ * `rebase skills install` with no `--agent` prompts, and refuses without a
+ * TTY — so printing it bare at the end of `rebase init --yes`, the agent and
+ * CI path, told that reader to run a command that answers "Cannot prompt".
+ * Named agents are spelled out (a refresh must not depend on detection, which
+ * never finds Copilot); otherwise a TTY reader gets the prompt, anyone else
+ * the `--agent` form.
+ */
+export declare function agentNextSteps(agents: readonly AgentKey[], interactive: boolean, pm: PMCommands): string[];
+/**
+ * What a directory may already hold for `rebase init` to scaffold into it.
+ *
+ * `git clone` of an empty repository, or `git init`, leaves exactly `.git` —
+ * and `rebase init . --yes --git` is the help's own example. Counting every
+ * entry as "not empty" refused the one directory that example is most likely
+ * to be typed in. The entries here are a repository's metadata, the files
+ * operating systems drop into any folder, and a licence: none of them is
+ * something the scaffold writes (`init.test.ts` holds the template to that),
+ * so tolerating them can never overwrite anything. Everything else is a
+ * conflict and is named, never merged into.
+ */
+export declare const SCAFFOLD_TOLERATED_ENTRIES: ReadonlySet<string>;
+/** Entries in `dir` the scaffold would overwrite or mix with — `[]` when it may proceed. */
+export declare function scaffoldDirectoryConflicts(dir: string): string[];
+/** The refusal for a directory that already holds files, with the two ways forward. */
+export declare function scaffoldConflictMessage(projectName: string, displayPath: string, conflicts: string[]): string[];
+/**
+ * `git init`, or nothing when the directory is already a repository.
+ *
+ * A cloned repository keeps its branch, its remote and its history: the
+ * scaffold is committed on top of what is there. Only a repository this
+ * function created is pointed at `main`.
+ */
+export declare function initGitRepository(targetDirectory: string): Promise<boolean>;
+/**
+ * Where the generated Drizzle schema for each preset ships, beside the template.
+ *
+ * `rebase dev` regenerates `backend/src/schema.generated.ts` on every start, and
+ * the Studio's schema editor refuses to commit over a dirty copy of it — a
+ * schema change must not sweep up somebody's work in progress. So whatever
+ * `init` writes there, and commits under `--git`, has to be byte-for-byte what
+ * that first regeneration produces. A stub (`export const tables = {}`) was
+ * rewritten on the first `rebase dev`, and every new project's first Studio
+ * edit was refused with `SCHEMA_EDIT_DIRTY_TREE` before its owner had changed
+ * a thing.
+ *
+ * The file cannot be generated here: generation loads the collection files,
+ * and they import `@rebasepro/cms-types`, which the project does not have
+ * until it is installed — `init --git` without `--install` commits first. So
+ * each preset's output is generated in this repository and shipped, and
+ * `init-generated-schema.test.ts` fails the moment one of them differs from
+ * what the generator writes for that preset's collections.
+ *
+ * Outside `templates/template` on purpose: a preset's schema must not be
+ * copied into a project that chose another preset.
+ */
+export declare function shippedSchemaPath(preset: TemplatePreset): string;
 /**
  * Whether `port` is free — on the wildcard address *and* on both loopback addresses.
  *

package/dist/commands/schema.d.ts

@@ -1,3 +1,9 @@
+/**
+ * The line handed to the driver, its paths resolved from where the command was
+ * run (the driver runs in `backend/`). `--schema` is left alone: on
+ * `introspect` it names a Postgres schema, not a file.
+ */
+export declare function schemaDriverArgs(rawArgs: string[], cwd: string): string[];
 export declare function schemaCommand(subcommand: string | undefined, rawArgs: string[]): Promise<void>;
 /** Every subcommand the family dispatches — the help table's keys. */
 export declare const SCHEMA_SUBCOMMANDS: string[];