@rebasepro/cli 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/collection-drift-BKj_BoMq.js

@@ -0,0 +1,106 @@
+import fs from "fs";
+import path from "path";
+import { DEFAULT_DATA_SOURCE_KEY, getDataSourceCapabilities } from "@rebasepro/types";
+//#region src/utils/collection-drift.ts
+/**
+* Which edits under `config/collections` can put the *SQL* schema out of date.
+*
+* `rebase dev` watches that directory and, on any change, either tells the
+* developer to run `rebase schema generate` / `rebase db push` or runs them.
+* The watcher is recursive and knows nothing about what it is watching, so it
+* said that about every file under the directory — including a
+* `collections/firestore/exercises.ts`, whose documents live in Firestore and
+* for which there is no Drizzle schema to regenerate and no database to push
+* to. Advice that is wrong on every edit is advice a developer learns to
+* ignore, which is worse than none: the same box is the only warning for the
+* Postgres collection next to it, where it is real.
+*
+* Two independent reasons a change cannot affect the SQL schema, both checked
+* here:
+*
+* 1. **The loader would never read the file.** `loadCollectionsFromDirectory`
+*    reads the top level of the collections directory only — no recursion, no
+*    `index`, no tests, no declarations. A file it does not read cannot change
+*    what it returns, and the watcher must not claim otherwise.
+* 2. **Every collection in it is served by another engine.** A Firestore or
+*    MongoDB collection has no table, no migration and no policies.
+*
+* The engine check reads the source text rather than importing the module: the
+* CLI runs as plain Node and cannot evaluate a project's TypeScript, and a
+* watcher must answer in the time between two keystrokes. Anything it cannot
+* read confidently counts as SQL-affecting — a spurious warning is a nuisance,
+* a suppressed one hides real drift.
+*/
+/**
+* Would `loadCollectionsFromDirectory` load this file?
+*
+* Mirrors that loader's own `isCollectionFile` plus its flat (non-recursive)
+* scan. `relativePath` is relative to the collections directory, as `fs.watch`
+* reports it.
+*/
+function isLoadedCollectionFile(relativePath) {
+	const normalized = relativePath.split(path.sep).join("/");
+	if (normalized.includes("/")) return false;
+	const file = normalized;
+	if (!file.endsWith(".ts") && !file.endsWith(".js")) return false;
+	if (file.startsWith(".")) return false;
+	if (file.includes(".test.")) return false;
+	if (file.endsWith(".d.ts")) return false;
+	if (file === "index.ts" || file === "index.js") return false;
+	return true;
+}
+var ENGINE_LITERAL = /\bengine\s*:\s*["'`]([^"'`]+)["'`]/g;
+var DATA_SOURCE_LITERAL = /\bdataSource\s*:\s*["'`]([^"'`]+)["'`]/g;
+/**
+* Drop comments, so a `// engine: "firestore"` in a docblock cannot silence a
+* warning about the Postgres collection the file actually declares.
+*
+* Deliberately naive — it does not understand strings, so a `//` inside one
+* (a URL in a default value) eats the rest of that line. That only ever removes
+* text, and removing an engine literal makes this file *more* likely to warn,
+* which is the side to be wrong on.
+*/
+function stripComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+}
+function literals(source, pattern) {
+	const found = [];
+	for (const match of source.matchAll(pattern)) found.push(match[1]);
+	return found;
+}
+/**
+* Does this collection source declare anything a SQL toolchain would own?
+*
+* The fallback order matches `resolveDataSource`: an explicit `engine` wins,
+* and a collection that only names a `dataSource` is resolved as if the key
+* were the engine — which is what that function does when no registry is
+* available, and the CLI has none. An engine nobody recognises counts as
+* relational, for the reason `isRelationalCollection` gives.
+*
+* A file declaring several collections is SQL-affecting if *any* of them is.
+*/
+function declaresRelationalCollection(rawSource) {
+	const source = stripComments(rawSource);
+	const engines = literals(source, ENGINE_LITERAL);
+	const declared = engines.length > 0 ? engines : literals(source, DATA_SOURCE_LITERAL).filter((key) => key !== DEFAULT_DATA_SOURCE_KEY);
+	if (declared.length === 0) return true;
+	return declared.some((engine) => getDataSourceCapabilities(engine).supportsRelations);
+}
+/**
+* Can this edit have changed the generated SQL schema?
+*
+* Answers `true` when it cannot tell — an unreadable file is a reason to warn,
+* not a reason to go quiet.
+*/
+function affectsSqlSchema(collectionsDir, relativePath) {
+	if (!isLoadedCollectionFile(relativePath)) return false;
+	try {
+		return declaresRelationalCollection(fs.readFileSync(path.join(collectionsDir, relativePath), "utf8"));
+	} catch {
+		return true;
+	}
+}
+//#endregion
+export { isLoadedCollectionFile as n, affectsSqlSchema as t };
+
+//# sourceMappingURL=collection-drift-BKj_BoMq.js.map

package/dist/collection-drift-BKj_BoMq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-drift-BKj_BoMq.js","names":[],"sources":["../src/utils/collection-drift.ts"],"sourcesContent":["/**\n * Which edits under `config/collections` can put the *SQL* schema out of date.\n *\n * `rebase dev` watches that directory and, on any change, either tells the\n * developer to run `rebase schema generate` / `rebase db push` or runs them.\n * The watcher is recursive and knows nothing about what it is watching, so it\n * said that about every file under the directory — including a\n * `collections/firestore/exercises.ts`, whose documents live in Firestore and\n * for which there is no Drizzle schema to regenerate and no database to push\n * to. Advice that is wrong on every edit is advice a developer learns to\n * ignore, which is worse than none: the same box is the only warning for the\n * Postgres collection next to it, where it is real.\n *\n * Two independent reasons a change cannot affect the SQL schema, both checked\n * here:\n *\n * 1. **The loader would never read the file.** `loadCollectionsFromDirectory`\n *    reads the top level of the collections directory only — no recursion, no\n *    `index`, no tests, no declarations. A file it does not read cannot change\n *    what it returns, and the watcher must not claim otherwise.\n * 2. **Every collection in it is served by another engine.** A Firestore or\n *    MongoDB collection has no table, no migration and no policies.\n *\n * The engine check reads the source text rather than importing the module: the\n * CLI runs as plain Node and cannot evaluate a project's TypeScript, and a\n * watcher must answer in the time between two keystrokes. Anything it cannot\n * read confidently counts as SQL-affecting — a spurious warning is a nuisance,\n * a suppressed one hides real drift.\n */\nimport fs from \"fs\";\nimport path from \"path\";\nimport { DEFAULT_DATA_SOURCE_KEY, getDataSourceCapabilities } from \"@rebasepro/types\";\n\n/**\n * Would `loadCollectionsFromDirectory` load this file?\n *\n * Mirrors that loader's own `isCollectionFile` plus its flat (non-recursive)\n * scan. `relativePath` is relative to the collections directory, as `fs.watch`\n * reports it.\n */\nexport function isLoadedCollectionFile(relativePath: string): boolean {\n    const normalized = relativePath.split(path.sep).join(\"/\");\n    // A nested path is a subdirectory, which the loader does not descend into.\n    if (normalized.includes(\"/\")) return false;\n\n    const file = normalized;\n    if (!file.endsWith(\".ts\") && !file.endsWith(\".js\")) return false;\n    if (file.startsWith(\".\")) return false;\n    if (file.includes(\".test.\")) return false;\n    if (file.endsWith(\".d.ts\")) return false;\n    // The directory's own module: defaults live there, not a collection.\n    if (file === \"index.ts\" || file === \"index.js\") return false;\n    return true;\n}\n\nconst ENGINE_LITERAL = /\\bengine\\s*:\\s*[\"'`]([^\"'`]+)[\"'`]/g;\nconst DATA_SOURCE_LITERAL = /\\bdataSource\\s*:\\s*[\"'`]([^\"'`]+)[\"'`]/g;\n\n/**\n * Drop comments, so a `// engine: \"firestore\"` in a docblock cannot silence a\n * warning about the Postgres collection the file actually declares.\n *\n * Deliberately naive — it does not understand strings, so a `//` inside one\n * (a URL in a default value) eats the rest of that line. That only ever removes\n * text, and removing an engine literal makes this file *more* likely to warn,\n * which is the side to be wrong on.\n */\nfunction stripComments(source: string): string {\n    return source.replace(/\\/\\*[\\s\\S]*?\\*\\//g, \" \").replace(/\\/\\/[^\\n]*/g, \" \");\n}\n\nfunction literals(source: string, pattern: RegExp): string[] {\n    const found: string[] = [];\n    for (const match of source.matchAll(pattern)) found.push(match[1]);\n    return found;\n}\n\n/**\n * Does this collection source declare anything a SQL toolchain would own?\n *\n * The fallback order matches `resolveDataSource`: an explicit `engine` wins,\n * and a collection that only names a `dataSource` is resolved as if the key\n * were the engine — which is what that function does when no registry is\n * available, and the CLI has none. An engine nobody recognises counts as\n * relational, for the reason `isRelationalCollection` gives.\n *\n * A file declaring several collections is SQL-affecting if *any* of them is.\n */\nexport function declaresRelationalCollection(rawSource: string): boolean {\n    const source = stripComments(rawSource);\n    const engines = literals(source, ENGINE_LITERAL);\n    const declared = engines.length > 0\n        ? engines\n        : literals(source, DATA_SOURCE_LITERAL).filter(key => key !== DEFAULT_DATA_SOURCE_KEY);\n\n    if (declared.length === 0) return true;\n    return declared.some(engine => getDataSourceCapabilities(engine).supportsRelations);\n}\n\n/**\n * Can this edit have changed the generated SQL schema?\n *\n * Answers `true` when it cannot tell — an unreadable file is a reason to warn,\n * not a reason to go quiet.\n */\nexport function affectsSqlSchema(collectionsDir: string, relativePath: string): boolean {\n    if (!isLoadedCollectionFile(relativePath)) return false;\n    try {\n        return declaresRelationalCollection(\n            fs.readFileSync(path.join(collectionsDir, relativePath), \"utf8\")\n        );\n    } catch {\n        // Deleted between the event and the read, or unreadable. Both leave the\n        // schema genuinely in question.\n        return true;\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,uBAAuB,cAA+B;CAClE,MAAM,aAAa,aAAa,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG;CAExD,IAAI,WAAW,SAAS,GAAG,GAAG,OAAO;CAErC,MAAM,OAAO;CACb,IAAI,CAAC,KAAK,SAAS,KAAK,KAAK,CAAC,KAAK,SAAS,KAAK,GAAG,OAAO;CAC3D,IAAI,KAAK,WAAW,GAAG,GAAG,OAAO;CACjC,IAAI,KAAK,SAAS,QAAQ,GAAG,OAAO;CACpC,IAAI,KAAK,SAAS,OAAO,GAAG,OAAO;CAEnC,IAAI,SAAS,cAAc,SAAS,YAAY,OAAO;CACvD,OAAO;AACX;AAEA,IAAM,iBAAiB;AACvB,IAAM,sBAAsB;;;;;;;;;;AAW5B,SAAS,cAAc,QAAwB;CAC3C,OAAO,OAAO,QAAQ,qBAAqB,GAAG,CAAC,CAAC,QAAQ,eAAe,GAAG;AAC9E;AAEA,SAAS,SAAS,QAAgB,SAA2B;CACzD,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,SAAS,OAAO,SAAS,OAAO,GAAG,MAAM,KAAK,MAAM,EAAE;CACjE,OAAO;AACX;;;;;;;;;;;;AAaA,SAAgB,6BAA6B,WAA4B;CACrE,MAAM,SAAS,cAAc,SAAS;CACtC,MAAM,UAAU,SAAS,QAAQ,cAAc;CAC/C,MAAM,WAAW,QAAQ,SAAS,IAC5B,UACA,SAAS,QAAQ,mBAAmB,CAAC,CAAC,QAAO,QAAO,QAAQ,uBAAuB;CAEzF,IAAI,SAAS,WAAW,GAAG,OAAO;CAClC,OAAO,SAAS,MAAK,WAAU,0BAA0B,MAAM,CAAC,CAAC,iBAAiB;AACtF;;;;;;;AAQA,SAAgB,iBAAiB,gBAAwB,cAA+B;CACpF,IAAI,CAAC,uBAAuB,YAAY,GAAG,OAAO;CAClD,IAAI;EACA,OAAO,6BACH,GAAG,aAAa,KAAK,KAAK,gBAAgB,YAAY,GAAG,MAAM,CACnE;CACJ,QAAQ;EAGJ,OAAO;CACX;AACJ"}

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,94 @@
+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"];
+/** The running backend's URL. Shared with `rebase storage`. */
+export declare function resolveBaseUrl(env: Record<string, string>, projectRoot?: string): string;
+/**
+ * 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 +106,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

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

@@ -0,0 +1,53 @@
+import { type CloudClient } from "./context.js";
+/** The control-plane function that mints runtime tokens. */
+export declare const RUNTIME_TOKEN_FUNCTION = "runtime-token";
+/** The one scope these commands ask the platform for. */
+export declare const CRON_READ_SCOPE = "cron:read";
+/** What `runtime-token` answers. */
+export interface RuntimeTokenResponse {
+    /** `rpt_…` — the bearer the runtime accepts. */
+    token: string;
+    /** ISO timestamp; past it the runtime refuses the token. */
+    expiresAt?: string;
+    /** What the token was granted, which may be narrower than what was asked. */
+    scopes?: string[];
+}
+/**
+ * A 404 that is about the route, not the project: the JSON envelope a Rebase
+ * backend answers for an unmatched path, or the bare one a router answers
+ * before that handler exists.
+ */
+export declare function isMissingRoute(message: string | undefined): boolean;
+/**
+ * Ask the control plane for a token the project's runtime will accept.
+ *
+ * A missing route means this control plane has no `runtime-token` function
+ * yet, which is a different fix from "no such project" and is said so.
+ */
+export declare function mintRuntimeToken(client: CloudClient, projectId: string, scopes: string[]): Promise<RuntimeTokenResponse>;
+/**
+ * GET a path on the runtime with a platform token, and refuse — with what it
+ * means for this command — anything but a 2xx.
+ *
+ * `notFound` words the 404, which means different things per route: no cron
+ * surface at all on the list, no such job on its logs.
+ */
+export declare function runtimeGet<T>(origin: string, path: string, token: string, notFound: {
+    message: string;
+    hint?: string;
+    code: string;
+}): Promise<T>;
+/** `2026-10-05T10:31:00.000Z` → `2026-10-05 10:31:00Z`, or `—`. */
+export declare function shortTime(iso: string | undefined): string;
+/** Milliseconds as `850ms`, `2.4s` or `3m 10s`. */
+export declare function shortDuration(ms: number | undefined): string;
+/** The flags `cron list` parses — the help page lists exactly these. */
+export declare const CRON_LIST_FLAGS: {
+    "--host": StringConstructor;
+};
+/** The flags `cron logs` parses — the help page lists exactly these. */
+export declare const CRON_LOGS_FLAGS: {
+    "--limit": NumberConstructor;
+    "--host": StringConstructor;
+};
+export declare function cronCommand(action: string | undefined, rawArgs: string[]): Promise<void>;