@rebasepro/cli 0.23.0 → 0.24.0

package/README.md

@@ -22,7 +22,7 @@ The CLI is also bundled with every Rebase project as a local dependency.
 | `rebase dev` | Start the development server (backend + frontend) |
 | `rebase build` | Build the apps declared in `rebase.json` into a bundle |
 | `rebase normalize-imports` | Complete compiled output's relative imports for Node ESM |
-| `rebase start` | Start the backend server (production) |
+| `rebase start` | Run the built bundle, as a deployment does, in the `NODE_ENV` you set |
 | `rebase apps list` | Show the apps this repository declares |
 | `rebase schema generate` | Generate Drizzle schema from collection definitions |
 | `rebase schema introspect` | Introspect an existing database → Rebase collections |
@@ -36,7 +36,7 @@ The CLI is also bundled with every Rebase project as a local dependency.
 | `rebase db reset` | Delete the managed development database and start over |
 | `rebase generate-sdk` | Generate a typed TypeScript SDK from collections |
 | `rebase auth reset-password` | Reset a user's password |
-| `rebase api-keys list \| create \| revoke` | Manage scoped service API keys |
+| `rebase api-keys list \| get \| create \| revoke \| scopes` | Manage service API keys and the scopes they hold |
 | `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 |
@@ -64,7 +64,7 @@ rebase cloud status                # project status at a glance
 
 | Group | Commands |
 |-------|----------|
-| Auth | `login`, `logout`, `whoami` |
+| Auth | `login`, `logout`, `whoami`, `tokens list \| create \| revoke` |
 | Link/context | `link`, `unlink`, `use [org]`, `open` |
 | Projects | `projects list \| create \| info \| delete` |
 | Deploy/observe | `deploy`, `logs [--runtime] [-f]`, `status`, `metrics` |
@@ -75,6 +75,22 @@ rebase cloud status                # project status at a glance
 Most commands act on the linked project unless you pass `--project <id>`.
 Run `rebase cloud --help` for the full list.
 
+### Tokens for CI and agents
+
+A token acts as your account, narrowed to what it was created for on one project.
+Create it from a signed-in terminal, then hand it to CI as `REBASE_TOKEN` — every
+`rebase cloud` command uses it instead of a login, and never reads or writes the
+stored session:
+
+```bash
+rebase cloud tokens create --project shop --can deploy,logs --expires-in 90
+# → export REBASE_TOKEN=rk_live_…   (shown once)
+REBASE_TOKEN=rk_live_… rebase cloud deploy --project shop
+```
+
+`--can` takes `deploy`, `logs`, `env`, `database` and `backups`. A token cannot
+create, list or revoke tokens, and none can restore a backup.
+
 ## Quick Start
 
 ```bash

package/bin/rebase.js

@@ -133,7 +133,7 @@ function warnIfStale() {
         : seconds >= 60 ? `${Math.round(seconds / 60)}m` : `${seconds}s`;
     process.stderr.write(
         `${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`
+        "  Rebuild with: pnpm --filter @rebasepro/cli build\n"
     );
 }
 

package/dist/{branch-pointer-dBiClJ0p.js → branch-pointer-kk9F5FBO.js}

@@ -106,6 +106,6 @@ function databaseNameOf(connectionString) {
 	}
 }
 //#endregion
-export { branch_pointer_exports as n, readActiveBranch as r, branchUrl as t };
+export { readActiveBranch as i, branch_pointer_exports as n, databaseNameOf as r, branchUrl as t };
 
-//# sourceMappingURL=branch-pointer-dBiClJ0p.js.map
+//# sourceMappingURL=branch-pointer-kk9F5FBO.js.map

package/dist/{branch-pointer-dBiClJ0p.js.map → branch-pointer-kk9F5FBO.js.map}

@@ -1 +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"}
+{"version":3,"file":"branch-pointer-kk9F5FBO.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

@@ -404,8 +404,10 @@ export declare function foldStaticIntoBundle(options: {
     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. */
+    /** Public base path this app is served under. Always a path, never a URL. */
     path: string;
+    /** The one hostname this app answers on, when its manifest `path` names one. */
+    host?: string;
     /** Serve `index.html` for unmatched paths under `path`. */
     spa: boolean;
     /** Where this app mounts the Rebase CMS, if it does. */
@@ -420,8 +422,10 @@ export declare function buildStaticBundle(options: {
     assetsDir: string;
     outDir: string;
     runtimeRange: string;
-    /** Public base path. Default `/` — a standalone bundle owns its origin. */
+    /** Public base path. Default `/` — a standalone bundle owns its origin. Always a path. */
     path?: string;
+    /** The one hostname this app answers on, when its manifest `path` names one. */
+    host?: string;
     /** Serve `index.html` for unmatched paths. Default `true`. */
     spa?: boolean;
     /** Where this app mounts the Rebase CMS, if it does. */

package/dist/cli.d.ts

@@ -18,6 +18,27 @@ export declare const ROOT_FLAGS: {
     readonly "-v": "--version";
     readonly "-h": "--help";
 };
+/**
+ * The subcommand in the words after a command, read against the subcommands the
+ * group dispatches.
+ *
+ * The first word that is not a flag is not always the subcommand: after a flag
+ * that takes a value it is that value. `rebase db --collections ./c push` was
+ * refused as an unknown db command `./c`, `rebase api-keys --name ci create` as
+ * one called `ci`, and `rebase skills --agent claude install` as `claude` —
+ * lines every one of those commands parses happily once it is reached.
+ *
+ * Which flags take a value is not known at this level, so the vocabulary decides
+ * instead: a word the group dispatches is the subcommand; a word straight after
+ * a flag (and not glued to it with `=`) may be that flag's value and is passed
+ * over. When no word is a known subcommand, the first word is returned as
+ * before, so a typo — `rebase db psuh`, `rebase db --dry-run psuh` — still
+ * reaches the group and is refused by name. A command with no vocabulary keeps
+ * the first word.
+ *
+ * Exported for its tests.
+ */
+export declare function resolveSubcommand(after: readonly string[], known: readonly string[]): string | undefined;
 /**
  * The command and subcommand words as `cli.error` may send them: each one is a
  * word this CLI dispatches, `"none"` when nothing was typed, or `"other"`.

package/dist/commands/__test_support__/parser-specs.d.ts

@@ -0,0 +1,13 @@
+export interface ParsedCommandSpec {
+    /** The command words, as the call names them: `"build"`, `"skills install"`. */
+    command: string;
+    /** Canonical long flags: the value is a type, not another flag's name. */
+    flags: string[];
+    /** Every spelling the parser accepts, aliases and short flags included. */
+    accepted: string[];
+    file: string;
+}
+/** The parser calls in one file. Throws on a call it cannot read, so a new shape fails loudly. */
+export declare function parsedCommands(file: string): ParsedCommandSpec[];
+/** Every parser call under `src/` that the dispatch reaches: `cli.ts` and the command modules. */
+export declare function allParsedCommands(commandsDir: string): ParsedCommandSpec[];

package/dist/commands/agent-setup.d.ts

@@ -0,0 +1,116 @@
+import { type AgentKey, type LoadedSkill } from "./skills.js";
+import { type PackageManager } from "../utils/package-manager.js";
+/** The name the server is registered under, in every config. */
+export declare const MCP_SERVER_NAME = "rebase";
+/** The MCP server's package: a devDependency of the project, pinned with the rest. */
+export declare const MCP_PACKAGE = "@rebasepro/mcp";
+/** The bin {@link MCP_PACKAGE} declares. */
+export declare const MCP_BIN = "rebase-mcp";
+/** The command an assistant spawns, and its arguments. */
+export interface McpLaunch {
+    command: string;
+    args: string[];
+}
+/**
+ * How an assistant starts the Rebase MCP server: the project's own copy, through
+ * the project's package manager.
+ *
+ * Not `npx -y @rebasepro/mcp`, which fetched the newest release on every first
+ * start. The server drives the project's own CLI (`pnpm exec rebase …`) and calls
+ * the project's own backend (`/api/admin/schema/plan`, …), whose versions the
+ * lockfile pins — so a server from the registry ran ahead of both, at every
+ * start, and downloaded before it could answer. `@rebasepro/mcp` is a
+ * devDependency of the scaffold, pinned to the CLI's version like every other
+ * `@rebasepro` package, and this runs that copy.
+ *
+ * `npx --no`, not `npx`: an assistant spawns the server with no TTY, and npx
+ * then assumes "yes" and installs a missing package from the registry under the
+ * name it was given. `--no` makes a missing install an error instead.
+ */
+export declare function mcpLaunch(pm: PackageManager): McpLaunch;
+/** What writing one MCP config did. */
+export type McpWriteStatus = 
+/** The file was created, or the server was added beside the ones in it. */
+"added"
+/** A `rebase` server was already there. It is left exactly as it was. */
+ | "present"
+/** The file exists but is not something this can edit without losing data. */
+ | "unreadable";
+export interface McpWriteResult {
+    /** Project-relative path of the config file. */
+    file: string;
+    status: McpWriteStatus;
+}
+/**
+ * The Codex block, as TOML. Appended rather than merged: there is no TOML
+ * parser here, and an append keeps every byte already in the file.
+ */
+export declare function renderCodexServer(projectDir: string, launch: McpLaunch): string;
+/**
+ * Register the Rebase MCP server in the agent's project-level config, started
+ * through the project's package manager (see {@link mcpLaunch}).
+ *
+ * Returns null for an agent with no project-level config to write.
+ */
+export declare function writeMcpConfig(agentKey: AgentKey, projectDir: string, pm?: PackageManager): McpWriteResult | null;
+/** What making sure the project depends on the MCP server did. */
+export type McpDependencyStatus = 
+/** Added to `devDependencies`, at this CLI's version: an install is due. */
+"added"
+/** Already a dependency. Left at the version the project chose. */
+ | "present"
+/** No `package.json`, or one that is not plain JSON: left alone. */
+ | "unreadable";
+/**
+ * Make the project depend on {@link MCP_PACKAGE}, which the config written by
+ * {@link writeMcpConfig} runs from the project's own install.
+ *
+ * Pinned to this CLI's version, as `rebase init` pins every `@rebasepro`
+ * package; a project that already lists it keeps its own choice.
+ */
+export declare function ensureMcpDependency(projectDir: string): McpDependencyStatus;
+/**
+ * Point the scaffold's `.mcp.json` at the project's package manager.
+ *
+ * The template ships the pnpm spelling (`pnpm exec rebase-mcp`); an npm project
+ * has no pnpm to run it with. Only the entry the template wrote is rewritten.
+ */
+export declare function retargetScaffoldMcpConfig(projectDir: string, pm: PackageManager): void;
+/**
+ * Whether the agent's project-level config already registers the Rebase
+ * server: `null` for an agent that has no such config, `false` when the file
+ * is missing or does not name it. Reads only — for the hint `rebase skills
+ * install` prints when it was not asked to write one.
+ */
+export declare function mcpServerRegistered(agentKey: AgentKey, projectDir: string): boolean | null;
+/** What `configureAgents` did for one agent. */
+export interface AgentSetupResult {
+    agent: AgentKey;
+    /** Skills written, or null when the bundle could not be loaded. */
+    skills: number | null;
+    /** An earlier agent in the same run that already wrote the skills directory. */
+    sharedWith?: AgentKey;
+    mcp: McpWriteResult | null;
+}
+/**
+ * Install the skills and register the MCP server for each agent.
+ *
+ * Never throws for a missing skills bundle — the scaffold it runs inside must
+ * not fail over its assistants — and reports it as `skills: null` instead.
+ */
+export declare function configureAgents(agents: readonly AgentKey[], projectDir: string, load?: () => LoadedSkill[], pm?: PackageManager): {
+    results: AgentSetupResult[];
+    skillsError?: string;
+    mcpDependency?: McpDependencyStatus;
+};
+/** The line to print when {@link ensureMcpDependency} changed or could not change the manifest. */
+export declare function mcpDependencyNote(status: McpDependencyStatus | undefined, pm: PackageManager): string | undefined;
+/** One line per agent, for the scaffold's output. */
+export declare function printAgentSetup({ results, skillsError, mcpDependency }: ReturnType<typeof configureAgents>, pm?: PackageManager): void;
+/**
+ * Ask whether to set up AI agents, then which, pre-ticking what is installed.
+ *
+ * Interactive only; the caller has already refused a non-TTY. Returns [] when
+ * the developer says no or unticks everything.
+ */
+export declare function promptForAgents(home?: string): Promise<AgentKey[]>;

package/dist/commands/api-keys.d.ts

@@ -1,40 +1,92 @@
+import { type ApiKeyMasked, type ScopeSummary } from "@rebasepro/types";
 /** Everything the switch below dispatches, for the did-you-mean. */
-export declare const API_KEYS_SUBCOMMANDS: readonly ["list", "create", "revoke"];
+export declare const API_KEYS_SUBCOMMANDS: readonly ["list", "get", "create", "revoke", "scopes"];
+/**
+ * What to print when a request fails: the server's error code and message,
+ * which is what says why — `SCOPE_EXCEEDS_CREATOR`, `INVALID_SCOPES`,
+ * `ROLE_EXCEEDS_CREATOR`, `KEY_MANAGEMENT_SCOPE` — and a hint where one helps.
+ *
+ * Exported so its tests can read the lines without a server.
+ */
+export declare function describeFailure(action: string, error: unknown, baseUrl: string): string[];
 export declare function apiKeysCommand(subcommand: string | undefined, rawArgs: string[]): Promise<void>;
+/**
+ * The lines that describe one key: what it is, what it may do and whom it
+ * runs as.
+ *
+ * A service key runs as the RLS role `service` plus its own `roles`; a
+ * personal key runs as its owner's roles as they are when it is used, so it
+ * has none of its own to show.
+ *
+ * Exported so its tests can read the lines without a server.
+ */
+export declare function describeKey(key: ApiKeyMasked, now?: Date): string[];
+/** The flags `rebase api-keys list` takes: none of its own. */
+export declare const LIST_KEYS_FLAGS: {};
+/** The flags `rebase api-keys get` takes. */
+export declare const GET_KEY_FLAGS: {
+    readonly "--id": StringConstructor;
+};
+/**
+ * Which key this invocation names, as a positional or as `--id`.
+ *
+ * Exported so its tests can drive the real parser rather than a copy of it.
+ */
+export declare function resolveGetKeyArgs(rawArgs: string[]): {
+    id?: string;
+};
 /** The flags `rebase api-keys create` takes. */
 export declare const CREATE_KEY_FLAGS: {
-    readonly "--name": StringConstructor;
-    readonly "--permissions": StringConstructor;
-    readonly "--full-access": BooleanConstructor;
-    readonly "--admin": BooleanConstructor;
-    readonly "--rate-limit": NumberConstructor;
-    readonly "--expires": StringConstructor;
-    readonly "-n": "--name";
+    "--name": StringConstructor;
+    "--scopes": [StringConstructor];
+    "--full-access": BooleanConstructor;
+    "--roles": [StringConstructor];
+    "--rate-limit": NumberConstructor;
+    "--expires-in": StringConstructor;
+    "--expires-at": StringConstructor;
+    "-n": string;
 };
+/**
+ * Options `create` refuses by name, each with the flag that does that job.
+ *
+ * Checked before the line is parsed: the strict parser would answer them
+ * "unknown option", which does not say what to type instead.
+ */
+export declare const RETIRED_CREATE_OPTIONS: Readonly<Record<string, string>>;
+/** What `rebase api-keys create` was asked to mint. */
+export interface CreateKeyPlan {
+    name: string;
+    /** The scopes named with `--scopes`, or `"held"` for `--full-access`. */
+    scopes: string[] | "held";
+    /** RLS roles beside `service`. */
+    roles: string[];
+    rate_limit: number | null;
+    expires_at: string | null;
+}
 /**
  * What this invocation asks to be created.
  *
  * The name may be given either way — `--name "My Key"` or as the single
  * positional — and under the old permissive parse an undeclared flag became
  * that positional: `rebase api-keys create --debug --full-access` created a
- * key called `--debug` with read/write/delete on every collection, and
- * `--debug` is what the CLI prints after every failure as the thing to re-run
- * with. Strict parsing makes the flag an error instead of a name.
+ * key called `--debug` with access to everything, and `--debug` is what the
+ * CLI prints after every failure as the thing to re-run with. Strict parsing
+ * makes the flag an error instead of a name.
+ *
+ * What the key may do has to be asked for by name — `--scopes` or
+ * `--full-access` — never defaulted: a forgotten flag must not mint a key that
+ * reaches everything.
  *
  * Exported so its tests can drive the real parser rather than a copy of it.
  */
-export declare function resolveCreateKeyArgs(rawArgs: string[]): {
-    flags: import("arg").Result<{
-        readonly "--name": StringConstructor;
-        readonly "--permissions": StringConstructor;
-        readonly "--full-access": BooleanConstructor;
-        readonly "--admin": BooleanConstructor;
-        readonly "--rate-limit": NumberConstructor;
-        readonly "--expires": StringConstructor;
-        readonly "-n": "--name";
-    }>;
-    name: string;
-};
+export declare function resolveCreateKeyArgs(rawArgs: string[], now?: Date): CreateKeyPlan;
+/**
+ * The scopes `--full-access` puts on a key: every one the caller holds, less
+ * key management, which no key may hold.
+ *
+ * Exported so its tests can check the subtraction without a server.
+ */
+export declare function grantableScopes(held: readonly string[]): string[];
 /** The flags `rebase api-keys revoke` takes. */
 export declare const REVOKE_KEY_FLAGS: {
     readonly "--id": StringConstructor;
@@ -52,3 +104,12 @@ export declare const REVOKE_KEY_FLAGS: {
 export declare function resolveRevokeKeyArgs(rawArgs: string[]): {
     id?: string;
 };
+/** The flags `rebase api-keys scopes` takes: none of its own. */
+export declare const SCOPES_LIST_FLAGS: {};
+/**
+ * The scope catalogue as printed lines: one section per plane, each scope with
+ * its label and what its target names, marked when the caller holds it.
+ *
+ * Exported so its tests can read the lines without a server.
+ */
+export declare function describeScopes(scopes: readonly ScopeSummary[], held: readonly string[]): string[];

package/dist/commands/apps.d.ts

@@ -1,3 +1,20 @@
+import type { RebaseAppConfig } from "@rebasepro/types";
+import { loadManifest } from "../manifest.js";
 /** Everything the switch below dispatches, for the did-you-mean. */
 export declare const APPS_SUBCOMMANDS: readonly ["list", "init", "config"];
 export declare function appsCommand(subcommand: string | undefined, rawArgs?: string[]): Promise<void>;
+/**
+ * One app's line in `rebase apps list`.
+ *
+ * A static app shows its full address — the https URL when its `path` gives it
+ * a hostname — and the CMS as the address a browser would open. `CMS at /` on
+ * an app that lives on `admin.example.com` reads as the project's own root,
+ * which is the one place that CMS is not.
+ */
+export declare function describeApp(name: string, app: RebaseAppConfig): string;
+/**
+ * Whether `rebase build` folds this static app into the backend bundle, which
+ * then serves it on the API's own origin: a managed backend, and an app with
+ * built output to fold. The same predicate the build folds by.
+ */
+export declare function servedByBackend(manifest: ReturnType<typeof loadManifest>["manifest"], appName: string): boolean;

package/dist/commands/auth.d.ts

@@ -80,6 +80,13 @@ export declare function generatePassword(): string;
  * The script the direct-database fallback runs under the project's own tsx, so
  * it resolves the project's `@rebasepro/server-postgres` and schema.
  *
+ * It ends the account's sessions in the transaction that sets the password,
+ * as every door through the API does (`replaceUserPassword`): the refresh
+ * tokens and outstanding reset links go, and `tokens_valid_after` voids the
+ * access tokens already handed out. An operator resetting a phished account
+ * with the backend down is the case this exists for, and a reset that left the
+ * attacker's refresh token minting access tokens did not recover anything.
+ *
  * It exits 0 only when a row was updated: a missing user and a thrown error are
  * both exit 1. `echoPassword` prints the new password, for a generated one.
  *

package/dist/commands/build.d.ts

@@ -39,7 +39,11 @@ export declare function buildCommand(rawArgs?: string[]): Promise<void>;
  * with its JSON error.
  */
 export declare function buildAssetApp(projectRoot: string, name: string, app: RebaseAppConfig, runtimeRange: string, outOverride?: string, 
-/** `quietStdout`: every line, the build command's included, goes to stderr. See `toolStdio`. */
+/**
+ * `quietStdout`: every line, the build command's included, goes to stderr. See `toolStdio`.
+ * `builtApps`: the static apps already built in this run (see `FoldOptions.builtApps`).
+ */
 options?: {
     quietStdout?: boolean;
+    builtApps?: Set<string>;
 }): Promise<string | undefined>;

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

@@ -20,9 +20,10 @@ export declare const LOGIN_FLAGS: {
  * 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.
+ * CI should not need a password at all: `rebase cloud tokens create` mints a
+ * token narrowed to one project, and `REBASE_TOKEN` hands it to every cloud
+ * command. Where a login is still wanted, `REBASE_CLOUD_PASSWORD` is how a
+ * secret store hands the password over without it appearing on a command line.
  */
 export declare const PASSWORD_ENV = "REBASE_CLOUD_PASSWORD";
 export declare const EMAIL_ENV = "REBASE_CLOUD_EMAIL";

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

@@ -126,3 +126,48 @@ export declare function declaredAppsFrom(manifest: {
 } | null | undefined): DeclaredApp[];
 /** Upload a bundle archive; returns the control-plane bundle id. */
 export declare function uploadBundle(url: string, token: string, projectId: string, tarPath: string): Promise<string>;
+/** One DNS record a hostname needs, as the control plane lists it. */
+export interface DeployHostRecord {
+    type: string;
+    name: string;
+    values: string[];
+}
+/**
+ * A hostname an app in this deploy is declared on, as the deploy found it.
+ *
+ * The control plane registers each one on the project as it deploys — an app
+ * whose `path` is `https://admin.example.com` needs that host on the project
+ * before anything can route it — and a new one starts `pending`, because it is
+ * served only once its DNS is published and verified. `records` is what to
+ * publish, present for a pending host.
+ */
+export interface DeployHost {
+    host: string;
+    status: "verified" | "pending";
+    records?: DeployHostRecord[];
+}
+/**
+ * The `hosts` a deploy response carries, read defensively.
+ *
+ * `undefined` when there is no such field, which is what a control plane that
+ * predates host-routed apps answers: the caller then leaves `hosts` out of its
+ * own output rather than reporting an empty set nobody looked for. An entry
+ * with no hostname is dropped, and any status but `verified` is pending — the
+ * same rule `cloud domains` reads rows by, because an unreadable status must
+ * not print as live.
+ */
+export declare function deployHostsFrom(response: unknown): DeployHost[] | undefined;
+/**
+ * What to tell somebody whose deploy declared a hostname that is not live yet.
+ *
+ * A deploy that succeeds with an app on a hostname nobody can reach reads as a
+ * broken deploy, so each pending host gets its own block: that it is registered
+ * but waiting, the records to create, and the command that finishes the job.
+ * The records come from the control plane, never composed here — A or CNAME
+ * depends on apex-vs-subdomain and on the ingress behind the project, which
+ * the CLI cannot know. Plain text: the caller colours it.
+ */
+export declare function pendingHostNotices(hosts: DeployHost[]): Array<{
+    headline: string;
+    details: string[];
+}>;

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

@@ -59,6 +59,24 @@ export type CloudClient = ReturnType<typeof createRebaseClient>;
  * by `requireClient`.
  */
 export declare function createCloudClient(url: string): CloudClient;
+/**
+ * The environment variable that authenticates the cloud family with a token
+ * instead of a `cloud login` session — for CI and agents, which have no
+ * terminal to log in at and should not hold a person's password.
+ */
+export declare const TOKEN_ENV = "REBASE_TOKEN";
+/** `REBASE_TOKEN`, trimmed, or undefined when it is unset or blank. */
+export declare function envToken(): string | undefined;
+/**
+ * A client that sends `token` as its bearer and nothing else.
+ *
+ * No session: the token is not refreshed, and the credentials file is neither
+ * read nor written — a CI job's token must not become, or replace, the login
+ * of whoever owns the machine. A 401 is answered by {@link explainRefusedToken}
+ * rather than by the SDK's session refresh, because there is no session to
+ * refresh and "log in again" is the wrong remedy for a token.
+ */
+export declare function createTokenClient(url: string, token: string): CloudClient;
 /** The half of a client that holds its session — all {@link freshAccessToken} reads. */
 export interface SessionHolder {
     auth: {
@@ -81,17 +99,36 @@ export interface SessionHolder {
  * token read once at the start of a command that runs for longer than it
  * lives — a deploy's build, a `db connect` left open — is refused by the time
  * it is used, so it is read here at the moment it is sent.
+ *
+ * A client built from `REBASE_TOKEN` has no session; its token is returned
+ * as it is, since there is nothing to refresh it with.
  */
 export declare function freshAccessToken(client: SessionHolder): Promise<string>;
 /**
- * Return an authenticated client for the resolved host, refreshing the access
- * token if it is close to expiry. Exits with a helpful message when there is no
- * usable session (never logged in, or the refresh token was revoked).
+ * Return an authenticated client for the resolved host.
+ *
+ * With `REBASE_TOKEN` set, that token is the credential for every request and
+ * the stored login is not consulted at all. Otherwise it is the `cloud login`
+ * session — see {@link requireSessionClient}.
  */
 export declare function requireClient(rawArgs: string[]): Promise<{
     client: CloudClient;
     url: string;
 }>;
+/**
+ * Return a client holding the `cloud login` session for the resolved host,
+ * refreshing the access token if it is close to expiry, whether or not
+ * `REBASE_TOKEN` is set. Exits with a helpful message when there is no usable
+ * session (never logged in, or the refresh token was revoked).
+ *
+ * For the commands a token cannot run — minting and revoking tokens: a key that
+ * could mint keys could mint its own successor, so the control plane refuses
+ * every key on those routes.
+ */
+export declare function requireSessionClient(rawArgs: string[]): Promise<{
+    client: CloudClient;
+    url: string;
+}>;
 /** One place a deploy can actually land, as the control plane describes it. */
 export interface DeployTarget {
     clusterId?: string | null;
@@ -192,8 +229,10 @@ export declare function removeLink(cwd?: string): boolean;
  * 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.
+ * `--region`, …) are declared by the handler that owns them. They can still
+ * precede the action — or stand in for it, on a group with a default — so the
+ * dispatcher also declares every one that takes a value: `CLOUD_VALUE_FLAGS`
+ * in `index.ts`.
  *
  * `-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