@rebasepro/cli 0.22.0 → 0.24.0

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

@@ -18,7 +18,26 @@ export declare function setContextOrg(url: string, org: string | undefined): voi
 export declare function getContextOrg(url: string): string | undefined;
 /** Mark a host as the active context (called on login). */
 export declare function setCurrentContext(url: string): void;
+/**
+ * Where the control-plane URL came from. `link` is the one a repository chose
+ * rather than the user — see {@link isKnownControlPlane}.
+ */
+export type CloudUrlSource = "flag" | "env" | "link" | "context" | "default";
 export declare function resolveCloudUrl(rawArgs: string[]): string;
+/** The control-plane URL, and which rung of the ladder above supplied it. */
+export declare function resolveCloudTarget(rawArgs: string[]): {
+    url: string;
+    source: CloudUrlSource;
+};
+/**
+ * Whether a control-plane host is one the user chose: the platform's own, or a
+ * host already in their credentials file because they signed in to it.
+ *
+ * A link file is part of the repository, and a cloned repository is not the
+ * user's to trust with their password. `login` asks before sending one to a
+ * linked host that is neither.
+ */
+export declare function isKnownControlPlane(url: string): boolean;
 /**
  * Refuse to run a control-plane command in a directory linked straight at a
  * backend.
@@ -41,14 +60,75 @@ export type CloudClient = ReturnType<typeof createRebaseClient>;
  */
 export declare function createCloudClient(url: string): CloudClient;
 /**
- * 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).
+ * 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: {
+        getSession(): {
+            accessToken: string;
+            expiresAt: number;
+        } | null;
+        refreshSession(): Promise<{
+            accessToken: string;
+        }>;
+    };
+}
+/**
+ * An access token with time left on it, refreshed first if it is close to
+ * expiry. Rejects when there is no session, or it cannot be refreshed.
+ *
+ * For the requests the SDK does not make itself. Its own calls refresh and
+ * retry on a 401; a raw `fetch` or a tunnel handshake presents whatever token
+ * it was handed, and `createCloudClient` never refreshes in the background. A
+ * 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.
+ *
+ * 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;
@@ -149,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>;

package/dist/commands/cloud/db-connect.d.ts

@@ -32,6 +32,7 @@
  * unreachable from a browser too.
  */
 import net from "node:net";
+import { type SessionHolder } from "./context.js";
 /** Documented in `action-help.ts`, and paired with it by `action-help.test.ts`. */
 export declare const DB_CONNECT_FLAGS: {
     readonly "--port": NumberConstructor;
@@ -53,6 +54,20 @@ export declare function localDsn(opts: {
     password?: string;
 }): string;
 export declare function dbConnect(rawArgs: string[]): Promise<void>;
+/**
+ * The local listener: each connection it accepts gets its own tunnel, signed in
+ * with a token that is current when the connection arrives.
+ *
+ * The command is left running for as long as the developer works, and the
+ * access token it started with lapses within the hour. Every connection is
+ * authenticated on its own, so each one reads the token then, refreshing it
+ * first when it is close to expiry — rather than the one read at startup, which
+ * the control plane refuses for every connection opened after it expires.
+ *
+ * The socket is paused while the token is read, so a client's first bytes wait
+ * for the tunnel exactly as they do once it is being established.
+ */
+export declare function tunnelListener(client: SessionHolder, endpoint: string): net.Server;
 /**
  * One accepted connection, carried over one WebSocket.
  *

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

@@ -1,3 +1,4 @@
+import { type CloudClient } from "./context.js";
 /** How a probe's outcome should be read. */
 export type Verdict = 
 /** Behaving as a healthy deployment should. */
@@ -114,5 +115,138 @@ export declare function formatDuration(seconds: number): string;
  * into seconds. Returns null when it is not a duration.
  */
 export declare function parseSince(input: string | undefined): number | null;
+/** One pod's entry in a `runtime-logs` answer. */
+export interface RuntimeLogsPod {
+    pod: string;
+    state: string;
+    /** Lines this pod returned. */
+    lines: number;
+    message: string | null;
+    hint: string | null;
+    /** The server's per-pod BYTE budget cut this pod's output. Says nothing about the line limit. */
+    truncated?: boolean;
+}
+export interface RuntimeLogsResponse {
+    logs?: string;
+    pods?: RuntimeLogsPod[];
+    ordering?: string;
+    /** A byte budget or the pod-count ceiling cut the result. Says nothing about the line limit. */
+    truncated?: boolean;
+    state?: string;
+    message?: string | null;
+}
+/**
+ * The most lines `runtime-logs` returns per pod.
+ *
+ * The control plane enforces this (`MAX_TAIL_LINES` in
+ * `saas/backend/functions/runtime-logs.ts`) by clamping a larger `tailLines`
+ * without saying so: its answer names neither the limit nor the value it used.
+ * `--tail 200000` therefore came back as 2000 lines reported as untruncated.
+ * The CLI clamps first, with the same number, so the lowering is something it
+ * can print rather than something that happened out of sight.
+ */
+export declare const SERVER_MAX_TAIL_LINES = 2000;
+/** How many lines per pod a read asks for, and why that may be less than requested. */
+export interface TailLimit {
+    /** What `--tail` asked for, or the view's default. */
+    requested: number;
+    /** What is sent: `requested`, lowered to {@link SERVER_MAX_TAIL_LINES}. */
+    applied: number;
+    /** Whether `--tail` was given, so a message can name the flag or the default. */
+    explicit: boolean;
+    /** Set when `applied < requested`: the sentence that says so. */
+    note: string | null;
+}
+export declare function resolveTail(requested: number, explicit: boolean): TailLimit;
+/** What one pod's lines actually cover. */
+export interface PodCoverage extends RuntimeLogsPod {
+    /** Earliest and latest timestamps among the lines this pod returned. */
+    firstTimestamp: string | null;
+    lastTimestamp: string | null;
+    /** A limit cut what this pod would otherwise have returned for the window. */
+    truncated: boolean;
+    /** Which limit: the per-pod line limit, or the server's byte budget. */
+    truncatedBy: "tail" | "bytes" | null;
+    /** The plain explanation, when truncated. */
+    truncatedReason: string | null;
+    /**
+     * Every line this pod holds in the window came back. With no window (read
+     * from the start), its first line is the start of its log.
+     */
+    complete: boolean;
+}
+/** The window asked for against the window delivered. */
+export interface LogCoverage {
+    /** Start of the window asked for, ISO. Null when reading each pod from its start. */
+    requestedFrom: string | null;
+    /** Earliest and latest timestamps across every line returned. */
+    firstTimestamp: string | null;
+    lastTimestamp: string | null;
+    pods: PodCoverage[];
+    truncated: boolean;
+    truncatedReasons: string[];
+}
+/** A span of milliseconds as `29d 23h`, `2h 5m`, `35m`, `40s`. */
+export declare function formatSpan(ms: number): string;
+/**
+ * Compare what a read covered with what it asked for.
+ *
+ * The server's `truncated` describes only its byte budgets and pod ceiling, so
+ * a pod that filled the line limit came back marked complete however much of
+ * the window it left unread. The line limit is the cut that matters most, and
+ * it is detected here: a pod that returned as many lines as the limit, whose
+ * earliest line is later than the start of the window, was cut by it.
+ *
+ * Filling the limit is the half that separates a cut from a young pod. A pod
+ * that started an hour ago also has no line older than an hour; it returned
+ * fewer lines than the limit, so what came back is its whole log, and nothing
+ * was cut.
+ */
+export declare function assessCoverage(opts: {
+    res: RuntimeLogsResponse;
+    lines: ParsedLogLine[];
+    /** The window asked for. Null reads each pod from its start. */
+    sinceSeconds: number | null;
+    tail: TailLimit;
+    now: number;
+}): LogCoverage;
+/**
+ * Resolve the public origin a project is served at — or `--host`, when given.
+ *
+ * Shared with `rebase cloud cron`, which reads the runtime at the same address
+ * `debug health` probes.
+ */
+export declare function resolveOrigin(rawArgs: string[], client: CloudClient, url: string, projectId: string): Promise<string>;
+/** What `debug logs`, `errors` and `boot` parse. Their help pairs against this. */
+export declare const LOG_VIEW_FLAGS: {
+    readonly "--since": StringConstructor;
+    readonly "--tail": NumberConstructor;
+    readonly "--previous": BooleanConstructor;
+};
+/** What `debug requests` parses. */
+export declare const REQUESTS_FLAGS: {
+    readonly "--since": StringConstructor;
+    readonly "--tail": NumberConstructor;
+};
+/** What `debug health` parses. */
+export declare const HEALTH_FLAGS: {
+    readonly "--collection": StringConstructor;
+    readonly "--function": StringConstructor;
+    readonly "--host": StringConstructor;
+};
+/**
+ * Whether a boot read reached each pod's start, which is where its startup
+ * lines are. A pod whose read was cut has not been looked at there, so finding
+ * no startup lines in it means nothing — and a line from later in its life
+ * that happens to mention `storage` is not its startup.
+ *
+ * Under `--since` a pod is never counted as reached: a complete read of the
+ * window starts at the pod's first line only if the pod started inside it, and
+ * nothing in the answer says whether it did.
+ */
+export declare function bootReach(pods: PodCoverage[], sinceSeconds: number | null): {
+    reachedStart: boolean;
+    unreached: string[];
+};
 export declare function debugCommand(action: string | undefined, rawArgs: string[]): Promise<void>;
 export declare function printDebugHelp(): void;

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

@@ -59,8 +59,22 @@ export declare function timeAgo(value: string | Date | undefined, now: Date): st
  * path.
  */
 export declare function isManagedProject(project: DeployProjectRow | undefined, latest: DeploySourceRow | undefined): boolean;
-/** What a `deploy` with nothing attached will build, in the words to print. */
-export declare function planBareDeploy(project: DeployProjectRow | undefined, latest: DeploySourceRow | undefined, now: Date): BareDeployPlan;
+/**
+ * The deployment whose uploaded archive a bare deploy rebuilds, if any.
+ *
+ * The control plane's own rule (`reusableSourceRef`, over the newest 25 rows):
+ * the newest row, by its own `createdAt`, carrying a build-context ref. Not the
+ * newest row — a rollback or a bundle deploy carries none, and the upload
+ * rebuilt then is the one before it.
+ */
+export declare function snapshotDeployment(recent: readonly DeploySourceRow[]): DeploySourceRow | undefined;
+/**
+ * What a `deploy` with nothing attached will build, in the words to print.
+ *
+ * `recent` is the project's newest deployments, newest first — the same page
+ * the control plane reads to choose an archive.
+ */
+export declare function planBareDeploy(project: DeployProjectRow | undefined, recent: readonly DeploySourceRow[], now: Date): BareDeployPlan;
 /**
  * A warning attached to a deploy: printed for the human, carried in the JSON.
  *
@@ -186,6 +200,8 @@ export declare const DEPLOY_FLAGS: {
     readonly "--bundle": BooleanConstructor;
     readonly "--bundle-dir": StringConstructor;
     readonly "--skip-type-check": BooleanConstructor;
+    readonly "--no-static": BooleanConstructor;
+    readonly "--skip-schema": BooleanConstructor;
     readonly "--eject": BooleanConstructor;
     readonly "--no-source": BooleanConstructor;
     readonly "--allow-downgrade": BooleanConstructor;
@@ -223,6 +239,8 @@ export declare function resolveDeployArgs(rawArgs: string[]): {
         readonly "--bundle": BooleanConstructor;
         readonly "--bundle-dir": StringConstructor;
         readonly "--skip-type-check": BooleanConstructor;
+        readonly "--no-static": BooleanConstructor;
+        readonly "--skip-schema": BooleanConstructor;
         readonly "--eject": BooleanConstructor;
         readonly "--no-source": BooleanConstructor;
         readonly "--allow-downgrade": BooleanConstructor;
@@ -290,6 +308,41 @@ export declare function deployedUrl(client: CloudClient, opts: {
     projectId?: string;
     url?: string;
 }): Promise<string | undefined>;
+/**
+ * The line an in-progress build keeps rewriting at the end of its log, to prove
+ * to the control plane that it is still alive.
+ *
+ * The control plane's own format — `HEARTBEAT_MARKER` and `heartbeatSuffix` in
+ * its `functions/deploy.ts` — which appends `\n<marker><ISO time>\n` to the log
+ * on every write and every 30 seconds, and drops it on the terminal write.
+ */
+export declare const BUILD_HEARTBEAT_MARKER = "\u23F3 Build in progress \u2014 control-plane heartbeat ";
+/**
+ * A deployment's log without its trailing heartbeat line: the build log itself.
+ *
+ * Only a heartbeat that is the last line is one. The same text anywhere else is
+ * the build quoting it.
+ */
+export declare function withoutHeartbeat(logs: string): string;
+/**
+ * What to print of a deployment's log, given everything printed so far.
+ *
+ * The `logs` column is not append-only. Its heartbeat line is rewritten at the
+ * end on every write, and a failed static deploy replaces its whole log with
+ * one line. Diffing the raw column by length therefore cut the start off every
+ * new chunk — as many characters as the heartbeat that had been there — and
+ * printed heartbeat fragments in their place: a failed managed deploy lost the
+ * first half of its reason.
+ *
+ * So the heartbeat is stripped first, and the log printed so far is compared
+ * with the log now. When it has only grown, the new text is printed. When it
+ * was rewritten, printing resumes from the start of the first line that
+ * differs, on a line of its own.
+ */
+export declare function nextLogChunk(printed: string, rowLogs: string): {
+    chunk: string;
+    printed: string;
+};
 /** What `rebase cloud logs` parses. Its page pairs against this. */
 export declare const LOGS_FLAGS: {
     readonly "--runtime": BooleanConstructor;

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

@@ -1,11 +1,11 @@
 export declare function domainsCommand(action: string | undefined, rawArgs: string[]): Promise<void>;
 /**
- * The domain `domains add` was asked to register.
+ * The domain an action was given, or undefined.
  *
  * Exported so its tests drive the real parser. Under the old operand filter
  * `rebase cloud domains add -p acme` registered a domain called "acme" — the
  * project slug, read out of `--project`'s own value — and a registered domain
  * is a project-record write, not a no-op.
  */
-export declare function resolveDomainArg(rawArgs: string[]): string | undefined;
+export declare function resolveDomainArg(rawArgs: string[], action?: string): string | undefined;
 export declare function printDomainsHelp(): void;

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

@@ -57,4 +57,18 @@ export declare function resolveEnvSetArgs(rawArgs: string[]): {
  * count of command words is the same for all of them.
  */
 export declare function resolveEnvKeyArg(rawArgs: string[], action: string): string | undefined;
+/**
+ * One `KEY=value` line that dotenv reads back as exactly `value`, or null when
+ * no quoting can carry it.
+ *
+ * dotenv's quoting is not JSON's, and `JSON.stringify` was what this used: a
+ * double-quoted value has only `\n` and `\r` unescaped, so every other
+ * backslash stayed and `{"a":1}` came back as `{\"a\":1}`. Single quotes and
+ * backticks are literal — nothing inside is unescaped, and either may span
+ * lines — so they carry any value without their own quote character. Double
+ * quotes come last: they cannot hold a `"` or a literal backslash-n, and they
+ * are the only way to carry a carriage return, which dotenv folds into a
+ * newline everywhere else.
+ */
+export declare function dotenvLine(key: string, value: string): string | null;
 export declare function printEnvHelp(): void;

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

@@ -1,19 +1,96 @@
 import { type HelpAction } from "./context.js";
+/**
+ * Every flag in the `rebase cloud` family that takes a value, and the short
+ * spellings of them — the globals aside, which `GLOBAL_CLOUD_FLAGS` declares.
+ *
+ * {@link positionals} needs them for one reason: `arg` only consumes a flag's
+ * value when the flag is declared, and an undeclared one leaves its value
+ * behind as a bare word in the action's position. `rebase cloud deployments
+ * --limit 5` dispatched to an action called "5", `rebase cloud debug --host
+ * staging.example.com` to one called "staging.example.com", and `rebase cloud
+ * projects --name shop create` to one called "shop" — each refused as an unknown
+ * command, for a line the command's own help offers.
+ *
+ * Every value is `String` whatever the command reads it as: only consumption
+ * matters here, and the command parses the value itself. One list for the whole
+ * family works because no flag takes a value in one command and none in
+ * another; `value-flags.test.ts` holds that, and holds this list to the specs
+ * the commands declare in both directions, so a new value flag fails a test
+ * until it is added here.
+ */
+export declare const CLOUD_VALUE_FLAGS: {
+    readonly "--access-key-id": StringConstructor;
+    readonly "--autoscale-cpu-target": StringConstructor;
+    readonly "--autoscale-max": StringConstructor;
+    readonly "--backup-access-key-id": StringConstructor;
+    readonly "--backup-bucket": StringConstructor;
+    readonly "--backup-endpoint": StringConstructor;
+    readonly "--backup-secret-access-key": StringConstructor;
+    readonly "--base-domain": StringConstructor;
+    readonly "--branch": StringConstructor;
+    readonly "--bucket": StringConstructor;
+    readonly "--bundle-dir": StringConstructor;
+    readonly "--can": StringConstructor;
+    readonly "--collection": StringConstructor;
+    readonly "--connection-string": StringConstructor;
+    readonly "--cpu": StringConstructor;
+    readonly "--db": StringConstructor;
+    readonly "--db-cpu": StringConstructor;
+    readonly "--db-instances": StringConstructor;
+    readonly "--db-memory": StringConstructor;
+    readonly "--email": StringConstructor;
+    readonly "--endpoint": StringConstructor;
+    readonly "--events": StringConstructor;
+    readonly "--expires-in": StringConstructor;
+    readonly "--function": StringConstructor;
+    readonly "--host": StringConstructor;
+    readonly "--ingress-address": StringConstructor;
+    readonly "--kubeconfig": StringConstructor;
+    readonly "--limit": StringConstructor;
+    readonly "--memory": StringConstructor;
+    readonly "--message": StringConstructor;
+    readonly "--name": StringConstructor;
+    readonly "--org": StringConstructor;
+    readonly "--output": StringConstructor;
+    readonly "--password": StringConstructor;
+    readonly "--platform-rebuilds": StringConstructor;
+    readonly "--port": StringConstructor;
+    readonly "--provider": StringConstructor;
+    readonly "--region": StringConstructor;
+    readonly "--replicas": StringConstructor;
+    readonly "--repo": StringConstructor;
+    readonly "--scale-to-zero": StringConstructor;
+    readonly "--secret-access-key": StringConstructor;
+    readonly "--since": StringConstructor;
+    readonly "--slug": StringConstructor;
+    readonly "--source": StringConstructor;
+    readonly "--spot": StringConstructor;
+    readonly "--storage": StringConstructor;
+    readonly "--subdomain": StringConstructor;
+    readonly "--table": StringConstructor;
+    readonly "--tail": StringConstructor;
+    readonly "--target": StringConstructor;
+    readonly "--timeout": StringConstructor;
+    readonly "--type": StringConstructor;
+    readonly "--out": "--output";
+    readonly "-e": "--email";
+    readonly "-m": "--message";
+    readonly "-n": "--name";
+};
 /**
  * Positional tokens after `rebase cloud` (group, action, …).
  *
- * Two things stop a flag being mistaken for the group. `GLOBAL_CLOUD_FLAGS` is
- * declared so `arg` *consumes* the flags that may precede it — critically
- * together with their values, which is the half that filtering cannot do. The
- * leading-`-` skip then covers a flag nobody declared, so an unrecognised
- * boolean shifts nothing.
- *
- * Only leading tokens are skipped: past the group and action, an undeclared
- * flag and its value are somebody else's positionals and none of our business.
- * A flag this file has never heard of, that takes a value, placed before the
- * group, is the one shape still unresolvable here — there is no way to know
- * whether the token after it is its value or the group, and guessing either way
- * is worse than the handler reporting an unknown group.
+ * Two things stop a flag being mistaken for the group or the action.
+ * `GLOBAL_CLOUD_FLAGS` and {@link CLOUD_VALUE_FLAGS} are declared so `arg`
+ * *consumes* every flag of the family that takes a value — critically together
+ * with its value, which is the half that filtering cannot do. The leading-`-`
+ * skip then covers a flag nobody declared, so an unrecognised boolean shifts
+ * nothing.
+ *
+ * A flag this family has never heard of, that takes a value, is the one shape
+ * still unresolvable here — there is no way to know whether the token after it
+ * is its value or the action. The command's own strict parse refuses that flag
+ * anyway, so the only cost is which refusal the caller reads.
  *
  * Exported so its tests can drive the real thing. The dispatch test used to
  * re-implement it locally as `slice(3).filter(a => !a.startsWith("-"))` — which

package/dist/commands/cloud/rebuild-source.d.ts

@@ -14,6 +14,12 @@ export declare const MAX_SOURCE_UPLOAD_BYTES: number;
  * bundles are never source. Every `.env` and `.env.*` is excluded except the
  * three template names, and so is direnv's `.envrc`, which is the same thing
  * under another name.
+ *
+ * So is what the CLI keeps on this machine: `.rebase/`, which holds the
+ * development database, and the `.rebase-dev-*` files beside it, one of which
+ * is the development signing secrets. And so is a `*.dump`, which is what
+ * `rebase db backup` writes: every row of the database, `rebase.users`
+ * password hashes included.
  */
 export declare function neverUploaded(relativePath: string): boolean;
 export interface SourceListing {
@@ -45,6 +51,21 @@ export type GitRunner = (cwd: string, args: string[]) => string;
  * archive with `../`.
  */
 export declare function listSourceFiles(projectRoot: string, git?: GitRunner): SourceListing;
+/**
+ * The files of a `--source` build context: `dir` and what is under it, relative
+ * to it, POSIX, sorted.
+ *
+ * The same rules as the rebuild source — git decides, and {@link neverUploaded}
+ * after it — restricted to `dir`, which is the context's root, so a Dockerfile
+ * in it still reads its paths from there. A `dir` that is a subfolder of a
+ * repository is held to that repository's `.gitignore`, which is where a
+ * monorepo keeps it.
+ *
+ * `.rebaseignore` in `dir` leaves out more, read with `.gitignore` syntax and
+ * anchored at `dir`. It needs git to be read, like `.gitignore` outside a
+ * repository; without git, a context that has one is refused.
+ */
+export declare function listContextFiles(dir: string, git?: GitRunner): string[];
 /**
  * Pack a listing into a gzipped tarball at `outPath`.
  *
@@ -54,7 +75,7 @@ export declare function listSourceFiles(projectRoot: string, git?: GitRunner): S
  * archive, as `packBundle` does; GNU tar accepts both. Every path handed to tar
  * is absolute, because GNU tar resolves a `-T` file after it has applied `-C`.
  */
-export declare function packSource(listing: SourceListing, outPath: string): Promise<void>;
+export declare function packSource(listing: Pick<SourceListing, "root" | "files">, outPath: string): Promise<void>;
 /** Upload a source archive; returns the control plane's id for it. */
 export declare function uploadRebuildSource(url: string, token: string, projectId: string, tarPath: string): Promise<string>;
 /**
@@ -100,7 +121,8 @@ export interface RebuildSourceSteps {
 export declare function prepareRebuildSource(opts: {
     projectRoot: string;
     url: string;
-    token: string;
+    /** The access token, read when the upload is sent rather than before the packing. */
+    token: () => Promise<string>;
     projectId: string;
     manifest?: RebaseProjectManifest;
     progress: (line: string) => void;