@vendure/cloud 0.3.1 → 0.4.0

package/dist/cli/lib/console-session-lock.js

@@ -0,0 +1,235 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, open, readFile, rename, stat, unlink, utimes } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { consoleConfigDir } from "./console-credential.js";
+import { ConsoleSessionLockUnavailableError } from "./errors.js";
+import { logger } from "./logger.js";
+// The cross-process lock guarding `~/.vendure/console-credentials.json`.
+//
+// Console rotates the refresh token on use and refuses the spent one, so two processes that refresh
+// together leave one of them with nothing, and a stale pair written back over a live one ends a
+// session that was working. Two processes are ordinary here: `vendure dev` runs for hours while
+// Cloud commands run in another terminal.
+//
+// **This is a vendored fork, not a second implementation.** It is
+// `test/fixtures/console-auth/upstream/session-lock.ts` from
+// `vendurehq/vendure-platform@0d09dfd2`, adapted only in what this repository requires: double
+// quotes, this project's formatting, `ConsoleSessionLockUnavailableError` in place of a bare
+// `Error`, and a debug line on the release path. The algorithm, the constants and the reasoning are
+// upstream's. Forking rather than importing is what upstream's README asks for, because the two
+// tools ship on separate release trains, and there is no published build to depend on: nothing has
+// been released to that repository's `major` dist-tag.
+//
+// The fork is what makes the drift dangerous, so two things guard it. `cli-console-session-lock.integration.test.ts`
+// pins the values both processes must agree on against the vendored copy, and runs that copy in a
+// second process against this one over a single credential file. That proves the fork still
+// cooperates with its original. It does not prove two independent implementations agree, and
+// nothing here should be read as claiming it does.
+//
+// This is not `file-lock.ts`. That lock guards `~/.vendure-cloud/refresh.lock`, is best-effort by
+// design, and runs the guarded work anyway when it cannot be taken. Neither property is allowed
+// here: a participant that runs unlocked is a participant that is not in the protocol.
+/**
+ * How long a lock file may sit untouched before another participant may take it over.
+ *
+ * A holder touches its own lock while it works, so this measures a holder that has stopped rather
+ * than one that is slow.
+ */
+export const CONSOLE_SESSION_LOCK_STALE_MS = 30_000;
+/**
+ * How long to wait for a lock somebody else holds.
+ *
+ * Never shorter than the stale budget. A waiter that gave up sooner could give up while the holder
+ * is dead but not yet stale, and then "I gave up waiting" would stop meaning "the holder is gone".
+ */
+export const CONSOLE_SESSION_LOCK_WAIT_MS = 30_000;
+const CONSOLE_SESSION_LOCK_POLL_MS = 50;
+/** The lock file, beside the credential it guards. */
+export function consoleSessionLockPath(home) {
+    return join(consoleConfigDir(home), "console-credentials.lock");
+}
+/**
+ * Run `work` while holding the Console session lock.
+ *
+ * Every step that spends a refresh token or rewrites the credential file goes through here,
+ * including the ones in the other tool. Guarding only some of the call sites leaves the double
+ * spend reachable through the rest.
+ *
+ * The lock is not reentrant.
+ */
+export async function withConsoleSessionLock(options, work) {
+    const lock = await acquire(options);
+    const beat = heartbeat(lock, options.staleMs ?? CONSOLE_SESSION_LOCK_STALE_MS);
+    try {
+        return await work();
+    }
+    finally {
+        clearInterval(beat);
+        await release(lock);
+    }
+}
+/**
+ * Say the holder is still here, by touching the lock while the work runs.
+ *
+ * Without it the stale budget measures how long the work takes rather than whether the holder is
+ * alive, so a hold that runs long on a loaded machine is broken while it is still working and two
+ * processes refresh at once. A third of the budget leaves two missed beats before anyone may act
+ * on the silence.
+ */
+function heartbeat(lock, staleMs) {
+    const beat = setInterval(() => {
+        void (async () => {
+            // Only ours. A lock broken and taken over while this holder was working belongs to
+            // somebody else, and beating on their behalf would keep their lock alive after they let
+            // it go.
+            const current = await readLockFile(lock.path);
+            if (current?.token !== lock.token)
+                return;
+            const when = new Date();
+            await utimes(lock.path, when, when);
+        })().catch(() => undefined);
+    }, Math.max(1, Math.round(staleMs / 3)));
+    // A lock is never a reason to keep the process running.
+    beat.unref();
+    return beat;
+}
+async function acquire(options) {
+    const path = consoleSessionLockPath(options.home);
+    const staleMs = options.staleMs ?? CONSOLE_SESSION_LOCK_STALE_MS;
+    const waitMs = Math.max(options.waitMs ?? CONSOLE_SESSION_LOCK_WAIT_MS, staleMs);
+    const pollMs = options.pollMs ?? CONSOLE_SESSION_LOCK_POLL_MS;
+    const token = randomUUID();
+    const deadline = Date.now() + waitMs;
+    await mkdir(consoleConfigDir(options.home), { recursive: true, mode: 0o700 });
+    const takeOver = async () => {
+        if (!(await breakIfStale(path, staleMs)))
+            return undefined;
+        return (await create(path, token)) ? { path, token } : undefined;
+    };
+    for (;;) {
+        if (await create(path, token))
+            return { path, token };
+        const taken = await takeOver();
+        if (taken)
+            return taken;
+        // Checked on every pass, including one that broke a lock. A state where `create` reports
+        // `EEXIST` while the lock itself cannot be read, such as a dangling symlink on the path, is
+        // otherwise a loop with no exit.
+        if (Date.now() >= deadline) {
+            // The lock can cross the stale boundary while the checks above are reading it, so it gets
+            // one last look. Without it a waiter that spent its whole budget can still walk away from a
+            // dead holder.
+            const last = await takeOver();
+            if (last)
+                return last;
+            throw new ConsoleSessionLockUnavailableError();
+        }
+        await sleep(pollMs);
+    }
+}
+/**
+ * Create the lock file, or report that somebody else holds it.
+ *
+ * `wx` is the whole mechanism: the create either wins or fails with `EEXIST`, with no window in
+ * between. The body records who took it, which is what makes releasing and breaking safe, and
+ * gives a person looking at a stuck lock a pid to check.
+ */
+async function create(path, token) {
+    let handle;
+    try {
+        handle = await open(path, "wx", 0o600);
+    }
+    catch (error) {
+        const { code } = error;
+        if (code === "EEXIST")
+            return false;
+        throw new ConsoleSessionLockUnavailableError({ cause: error });
+    }
+    try {
+        const body = { token, pid: process.pid, acquiredAt: new Date().toISOString() };
+        await handle.writeFile(`${JSON.stringify(body)}\n`, "utf8");
+        return true;
+    }
+    catch (error) {
+        await unlink(path).catch(() => undefined);
+        throw new ConsoleSessionLockUnavailableError({ cause: error });
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+/**
+ * Take a lock whose holder has stopped touching it out of the way. Reports whether the path is
+ * worth another create attempt.
+ */
+async function breakIfStale(path, staleMs) {
+    const before = await readLockFile(path);
+    if (!before)
+        return true;
+    // `Date.now()` counts whole milliseconds while `mtimeMs` carries a fraction, so an untouched
+    // lock written in the same millisecond a waiter started reads as younger than that waiter's own
+    // clock says it is. Floor it: both sides then measure in the same units, and a waiter that has
+    // spent its whole budget can always break what it spent the budget on.
+    if (Date.now() - Math.floor(before.mtimeMs) < staleMs)
+        return false;
+    // Move the lock aside rather than unlink it. `rename` is one operation, so one waiter moves this
+    // file and the rest get `ENOENT` and go back to creating. Unlinking by path would let a second
+    // waiter, still holding its reading of a file the first waiter has already removed, delete the
+    // fresh lock the first waiter created in its place and leave two holders.
+    const aside = `${path}.${randomUUID()}`;
+    try {
+        await rename(path, aside);
+    }
+    catch {
+        return true;
+    }
+    const moved = await readLockFile(aside);
+    if (moved && moved.token !== before.token) {
+        // Somebody took the lock between the read above and the rename, so what moved is their live
+        // lock and not the dead one. Put it back. `link` fails rather than overwrite, and a failure
+        // means a third lock is already there, at which point the holder whose lock was moved has lost
+        // it whatever happens next.
+        await link(aside, path).catch(() => undefined);
+    }
+    await unlink(aside).catch(() => undefined);
+    return true;
+}
+/**
+ * Give up the lock.
+ *
+ * A lock carrying somebody else's token is not ours to remove: ours was already broken as stale
+ * and the file belongs to whoever took it. Releasing it would let a third process in while the
+ * second one writes.
+ */
+async function release(lock) {
+    const current = await readLockFile(lock.path);
+    if (current?.token !== lock.token) {
+        logger.debug("Console session lock was taken over while held; leaving it alone");
+        return;
+    }
+    await unlink(lock.path).catch(() => undefined);
+}
+async function readLockFile(path) {
+    try {
+        const info = await stat(path);
+        let token;
+        try {
+            const value = JSON.parse(await readFile(path, "utf8"));
+            if (value && typeof value === "object" && "token" in value) {
+                const { token: candidate } = value;
+                if (typeof candidate === "string")
+                    token = candidate;
+            }
+        }
+        catch {
+            // A lock written by something older, or caught mid-write. It still holds the lock; it just
+            // cannot prove ownership, so it can only ever be removed by the stale path.
+        }
+        return { token, mtimeMs: info.mtimeMs };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=console-session-lock.js.map

package/dist/cli/lib/console-session-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-session-lock.js","sourceRoot":"","sources":["../../../src/cli/lib/console-session-lock.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/console-session.d.ts

@@ -0,0 +1,47 @@
+import { type ConsoleCredentialLocation } from "./console-credential.js";
+export interface ConsoleSessionOptions extends ConsoleCredentialLocation {
+    fetch?: typeof globalThis.fetch;
+    now?: () => Date;
+}
+/**
+ * Whether this machine may reuse the shared Vendure Console CLI Session for Cloud commands.
+ *
+ * Off unless the variable is set, and the control plane refuses a Console session unless it has
+ * been configured to reach Console, so both ends of CLO-641 default to the behaviour that shipped
+ * before it. The switch is one a person sets rather than something inferred from the presence of a
+ * file another tool wrote: finding a credential is not the same as being told to use it, and a
+ * machine that turned this on by itself would change which account a command runs under.
+ *
+ * It lives here rather than in `config.ts` because a machine with the feature off must not even
+ * read the Console credential, and keeping the switch beside the reader is what makes that
+ * obvious at the one call site that checks it.
+ */
+export declare function isSharedConsoleSessionEnabled(): boolean;
+export interface ResolvedConsoleSession {
+    accessToken: string;
+    /** Whether the access token is past its expiry, counting the skew. */
+    expired: boolean;
+    /** Whether an expired session can be renewed without a browser. */
+    refreshable: boolean;
+}
+/**
+ * The stored Console session, or `undefined` when this machine has none to reuse.
+ *
+ * Synchronous, because it sits on the credential-resolution path that every command runs through
+ * before it does any work. An expired session is still returned: it may carry a refresh token, and
+ * the renewal happens on the first 401 through the same retry the stored Cloud login uses.
+ */
+export declare function resolveConsoleSession(options?: ConsoleCredentialLocation & {
+    now?: () => Date;
+}): ResolvedConsoleSession | undefined;
+/**
+ * Renew the shared session and return the fresh access token.
+ *
+ * Deduplicated twice, for the same reason the stored Cloud login is. This promise collapses the
+ * concurrent calls of one process, and the session lock underneath it serializes the token request
+ * against every other process on the machine, Cloud and Platform alike. Neither is enough alone:
+ * this one knows nothing about the other tool, and the lock cannot see a second client inside this
+ * process that is already waiting on it.
+ */
+export declare function refreshConsoleSession(failedAccessToken: string | undefined, options?: ConsoleSessionOptions): Promise<string>;
+//# sourceMappingURL=console-session.d.ts.map

package/dist/cli/lib/console-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-session.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/console-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,yBAAyB,EAK/B,MAAM,yBAAyB,CAAC;AAgCjC,MAAM,WAAW,qBAAsB,SAAQ,yBAAyB;IACtE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,IAAI,OAAO,CAGvD;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,yBAAyB,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GAC7D,sBAAsB,GAAG,SAAS,CAUpC;AAID;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAUjB"}

package/dist/cli/lib/console-session.js

@@ -0,0 +1,235 @@
+import { discardConsoleCredential, isConsoleCredentialExpired, readConsoleCredential, writeConsoleCredential, } from "./console-credential.js";
+import { consoleOrigins } from "./console-origins.js";
+import { withConsoleSessionLock } from "./console-session-lock.js";
+import { ConsoleSessionNotAcceptedError, ConsoleSessionRejectedError, ConsoleSessionUnavailableError, } from "./errors.js";
+import { logger } from "./logger.js";
+// Reusing the Console CLI Session that Vendure Platform already obtained for this person, so a
+// developer who signed in during `vendure console link` does not approve a second login for Cloud.
+//
+// Cloud never mints one of these. It reads the stored session, refreshes it when it has expired,
+// and presents the access token to the control plane, which resolves the identity behind it
+// server-side against Console. Nothing here decodes the token or trusts what the file claims about
+// who the person is.
+const TOKEN_PATH = "/v1/auth/cli/token";
+/**
+ * The deadline covers reading the answer as well as getting it. A server that sends headers and
+ * then stops sending would otherwise hold the session lock for as long as it liked, and the lock's
+ * stale budget is set from this bound.
+ */
+const TOKEN_REQUEST_TIMEOUT_MS = 10_000;
+/** What Console names a grant it will not honour again. */
+const GRANT_REFUSED_CODE = "cli_session.invalid_grant";
+const MAX_TOKEN_LIFETIME_SECONDS = 365 * 24 * 60 * 60;
+/**
+ * Whether this machine may reuse the shared Vendure Console CLI Session for Cloud commands.
+ *
+ * Off unless the variable is set, and the control plane refuses a Console session unless it has
+ * been configured to reach Console, so both ends of CLO-641 default to the behaviour that shipped
+ * before it. The switch is one a person sets rather than something inferred from the presence of a
+ * file another tool wrote: finding a credential is not the same as being told to use it, and a
+ * machine that turned this on by itself would change which account a command runs under.
+ *
+ * It lives here rather than in `config.ts` because a machine with the feature off must not even
+ * read the Console credential, and keeping the switch beside the reader is what makes that
+ * obvious at the one call site that checks it.
+ */
+export function isSharedConsoleSessionEnabled() {
+    const value = process.env.VENDURE_CLOUD_SHARED_CONSOLE_SESSION;
+    return value === "1" || value === "true";
+}
+/**
+ * The stored Console session, or `undefined` when this machine has none to reuse.
+ *
+ * Synchronous, because it sits on the credential-resolution path that every command runs through
+ * before it does any work. An expired session is still returned: it may carry a refresh token, and
+ * the renewal happens on the first 401 through the same retry the stored Cloud login uses.
+ */
+export function resolveConsoleSession(options = {}) {
+    const credential = readConsoleCredential(options);
+    if (!credential) {
+        return undefined;
+    }
+    return {
+        accessToken: credential.accessToken,
+        expired: isConsoleCredentialExpired(credential, options.now?.() ?? new Date()),
+        refreshable: credential.refreshToken !== undefined,
+    };
+}
+let activeRefresh = null;
+/**
+ * Renew the shared session and return the fresh access token.
+ *
+ * Deduplicated twice, for the same reason the stored Cloud login is. This promise collapses the
+ * concurrent calls of one process, and the session lock underneath it serializes the token request
+ * against every other process on the machine, Cloud and Platform alike. Neither is enough alone:
+ * this one knows nothing about the other tool, and the lock cannot see a second client inside this
+ * process that is already waiting on it.
+ */
+export function refreshConsoleSession(failedAccessToken, options = {}) {
+    if (activeRefresh) {
+        return activeRefresh;
+    }
+    activeRefresh = withConsoleSessionLock({ home: options.home }, () => refreshUnderLock(failedAccessToken, options)).finally(() => {
+        activeRefresh = null;
+    });
+    return activeRefresh;
+}
+async function refreshUnderLock(failedAccessToken, options) {
+    // Read again now that the lock is held. Waiting for it is the usual way to find out that another
+    // process has already refreshed, and by then the pair read before the wait is the stale copy.
+    let credential = readConsoleCredential(options);
+    if (!credential) {
+        throw new ConsoleSessionRejectedError();
+    }
+    if (credential.accessToken !== failedAccessToken) {
+        if (!isConsoleCredentialExpired(credential, currentTime(options))) {
+            logger.debug("Another process already refreshed the Console session; reusing its access token");
+            return credential.accessToken;
+        }
+    }
+    else if (!isConsoleCredentialExpired(credential, currentTime(options))) {
+        // The token that was refused is still the stored one and it has not expired, so whatever the
+        // control plane objected to, it was not the age of this token. Spending the grant would rotate
+        // a credential another Vendure product owns, on every failing command, and buy a retry that is
+        // refused for the same reason. A 401 is not by itself evidence that a session needs renewing.
+        logger.debug("Console session was refused while still valid; not spending the refresh grant");
+        throw new ConsoleSessionNotAcceptedError();
+    }
+    for (let attempt = 0;; attempt++) {
+        const spent = credential.refreshToken;
+        if (!spent) {
+            throw new ConsoleSessionRejectedError();
+        }
+        try {
+            const renewed = await requestToken(credential.apiOrigin, spent, options);
+            writeConsoleCredential({
+                schemaVersion: 2,
+                origin: credential.origin,
+                apiOrigin: credential.apiOrigin,
+                accessToken: renewed.accessToken,
+                expiresAt: renewed.expiresAt,
+                ...(renewed.refreshToken ? { refreshToken: renewed.refreshToken } : {}),
+            }, { home: options.home });
+            return renewed.accessToken;
+        }
+        catch (error) {
+            // A transient failure says nothing about the refresh token, so the credential survives it
+            // untouched. One retry, and only against a token somebody else rotated in, is enough to hand
+            // over the race. A second refusal is reported rather than acted on: it refuses a token this
+            // process took from a store another participant was still moving, which is not the proof the
+            // first refusal is.
+            if (attempt > 0 || !(error instanceof ConsoleSessionRejectedError)) {
+                throw error;
+            }
+            const latest = readConsoleCredential(options);
+            if (latest?.refreshToken && latest.refreshToken !== spent) {
+                logger.debug("Console refresh token was spent by another process; using its replacement");
+                if (!isConsoleCredentialExpired(latest, currentTime(options))) {
+                    return latest.accessToken;
+                }
+                credential = latest;
+                continue;
+            }
+            // The store still holds the token that was just refused, and the lock was held across both
+            // the refusal and this read, so nothing can have rotated it in between. The session is over.
+            discardConsoleCredential({ home: options.home });
+            throw error;
+        }
+    }
+}
+async function requestToken(storedApiOrigin, refreshToken, options) {
+    // Re-checked rather than taken from the file. The origin was validated when the credential was
+    // read, and validating it again here means no path reaches `fetch` with a URL that skipped the
+    // check.
+    const { apiOrigin } = consoleOrigins({ apiOrigin: storedApiOrigin });
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    let response;
+    try {
+        response = await fetchImpl(`${apiOrigin}${TOKEN_PATH}`, {
+            method: "POST",
+            redirect: "error",
+            signal: AbortSignal.timeout(TOKEN_REQUEST_TIMEOUT_MS),
+            headers: { accept: "application/json", "content-type": "application/json" },
+            body: JSON.stringify({ grant_type: "refresh_token", refresh_token: refreshToken }),
+        });
+    }
+    catch (error) {
+        throw new ConsoleSessionUnavailableError({ cause: error });
+    }
+    if (!response.ok) {
+        throw (await refusesTheGrant(response))
+            ? new ConsoleSessionRejectedError()
+            : new ConsoleSessionUnavailableError({
+                cause: new Error(`Vendure Console answered the token request with ${response.status}.`),
+            });
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new ConsoleSessionUnavailableError({ cause: error });
+    }
+    return toRenewedSession(body, refreshToken, currentTime(options));
+}
+/**
+ * Whether Console judged the grant itself and refused it.
+ *
+ * The status alone does not say. A 404 from an API origin pointed at the wrong host, a 403 from a
+ * proxy in front of Console, and a 401 from a gateway that wants a credential of its own are all
+ * 4xx, and none of them is Console reporting a spent refresh token. Console names that case in the
+ * body, so the body decides, and everything else leaves the stored credential alone.
+ */
+async function refusesTheGrant(response) {
+    if (response.status < 400 || response.status >= 500) {
+        return false;
+    }
+    try {
+        const value = JSON.parse(await response.text());
+        if (!value || typeof value !== "object" || !("code" in value)) {
+            return false;
+        }
+        const { code } = value;
+        return code === GRANT_REFUSED_CODE;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate the token response. An unreadable expiry is a failure rather than an assumed default: a
+ * session treated as valid for longer than it is fails later, where the cause is no longer visible.
+ */
+function toRenewedSession(value, presentedRefreshToken, now) {
+    const body = value;
+    if (typeof body?.access_token !== "string" || !body.access_token) {
+        throw new ConsoleSessionUnavailableError({
+            cause: new Error("Vendure Console returned no access token."),
+        });
+    }
+    if (body.token_type !== "Bearer") {
+        throw new ConsoleSessionUnavailableError({
+            cause: new Error("Vendure Console returned an unsupported token type."),
+        });
+    }
+    if (typeof body.expires_in !== "number" ||
+        !Number.isInteger(body.expires_in) ||
+        body.expires_in <= 0 ||
+        body.expires_in > MAX_TOKEN_LIFETIME_SECONDS) {
+        throw new ConsoleSessionUnavailableError({
+            cause: new Error("Vendure Console returned no usable token expiry."),
+        });
+    }
+    const refreshToken = typeof body.refresh_token === "string" && body.refresh_token
+        ? body.refresh_token
+        : presentedRefreshToken;
+    return {
+        accessToken: body.access_token,
+        expiresAt: new Date(now.getTime() + body.expires_in * 1000).toISOString(),
+        refreshToken,
+    };
+}
+function currentTime(options) {
+    return options.now?.() ?? new Date();
+}
+//# sourceMappingURL=console-session.js.map

package/dist/cli/lib/console-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-session.js","sourceRoot":"","sources":["../../../src/cli/lib/console-session.ts"],"names":[],"mappings":"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"}

package/dist/cli/lib/contract/backup-schedule-reasons.d.ts

@@ -0,0 +1,4 @@
+import type { BackupScheduleExclusion } from "./database.js";
+export declare const BACKUP_SCHEDULE_EXCLUSION_DESCRIPTIONS: Record<BackupScheduleExclusion, string>;
+export declare function describeBackupScheduleExclusion(reason: BackupScheduleExclusion): string;
+//# sourceMappingURL=backup-schedule-reasons.d.ts.map

package/dist/cli/lib/contract/backup-schedule-reasons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-schedule-reasons.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/contract/backup-schedule-reasons.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAQ7D,eAAO,MAAM,sCAAsC,EAAE,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAK1F,CAAC;AAEF,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAKvF"}

package/dist/cli/lib/contract/backup-schedule-reasons.js

@@ -0,0 +1,17 @@
+// Why a VC Environment receives no scheduled dump, in the words a customer reads. The wire carries
+// the code so that a client can act on the case — the two want different next steps, and only one of
+// them is a suggestion the platform will accept.
+//
+// Stated positively rather than left to an empty list, because the inference a customer draws from
+// silence is the wrong one.
+export const BACKUP_SCHEDULE_EXCLUSION_DESCRIPTIONS = {
+    "non-production": "This environment receives no scheduled backups. Scheduled backups run for production environments only.",
+    "not-deployed": "This environment has no provisioned database, so no scheduled backup runs for it yet.",
+};
+export function describeBackupScheduleExclusion(reason) {
+    // A control plane ahead of this reader can send a code it has no sentence for. Saying the platform
+    // gave a reason this client cannot render beats printing nothing where an explanation belongs.
+    const description = BACKUP_SCHEDULE_EXCLUSION_DESCRIPTIONS[reason];
+    return description ?? `This environment receives no scheduled backups (${reason}).`;
+}
+//# sourceMappingURL=backup-schedule-reasons.js.map

package/dist/cli/lib/contract/backup-schedule-reasons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-schedule-reasons.js","sourceRoot":"","sources":["../../../../src/cli/lib/contract/backup-schedule-reasons.ts"],"names":[],"mappings":"AAIA,mGAAmG;AACnG,qGAAqG;AACrG,iDAAiD;AACjD,EAAE;AACF,mGAAmG;AACnG,4BAA4B;AAC5B,MAAM,CAAC,MAAM,sCAAsC,GAA4C;IAC7F,gBAAgB,EACd,yGAAyG;IAC3G,cAAc,EACZ,uFAAuF;CAC1F,CAAC;AAEF,MAAM,UAAU,+BAA+B,CAAC,MAA+B;IAC7E,mGAAmG;IACnG,+FAA+F;IAC/F,MAAM,WAAW,GAAuB,sCAAsC,CAAC,MAAM,CAAC,CAAC;IACvF,OAAO,WAAW,IAAI,mDAAmD,MAAM,IAAI,CAAC;AACtF,CAAC"}

package/dist/cli/lib/contract/build-settings.d.ts

@@ -14,7 +14,7 @@ export interface ResolvedBuildSettings {
 declare const appDirSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
 export { appDirSchema };
 export declare const sourceBuildSettingsSchema: z.ZodObject<{
-    nodeVersion: z.ZodOptional<z.ZodLiteral<20 | 22 | 24>>;
+    nodeVersion: z.ZodOptional<z.ZodLiteral<24 | 20 | 22>>;
     packageManager: z.ZodOptional<z.ZodEnum<{
         bun: "bun";
         pnpm: "pnpm";

package/dist/cli/lib/contract/database.d.ts

@@ -1,9 +1,12 @@
 export declare const DATABASE_BACKUP_KINDS: readonly ["manual", "scheduled", "safety"];
 export type DatabaseBackupKind = (typeof DATABASE_BACKUP_KINDS)[number];
+export type ScheduledDatabaseBackupTier = "daily" | "weekly";
+export type DatabaseBackupTier = ScheduledDatabaseBackupTier | "recovery";
 export interface DatabaseBackup {
     id: string;
     status: string;
     kind: DatabaseBackupKind;
+    tier: DatabaseBackupTier;
     createdAt: string;
     completedAt: string | null;
     sizeBytes: number | null;
@@ -31,6 +34,22 @@ export interface RestoreResult {
     safetyBackupId: string;
     deadlineAt: string;
 }
+export type BackupScheduleDay = "Sunday" | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday";
+export interface BackupScheduleEntry {
+    tier: ScheduledDatabaseBackupTier;
+    day: BackupScheduleDay | null;
+    startsAt: string;
+    timeZone: string;
+    retentionDays: number;
+}
+export type BackupScheduleExclusion = "non-production" | "not-deployed";
+export type BackupSchedule = {
+    scheduled: true;
+    entries: BackupScheduleEntry[];
+} | {
+    scheduled: false;
+    reason: BackupScheduleExclusion;
+};
 export interface TunnelTicket {
     ticket: string;
     expiresAt: string;

package/dist/cli/lib/contract/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/contract/database.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,qBAAqB,4CAA6C,CAAC;AAChF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAG9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAID,eAAO,MAAM,yBAAyB,uDAAwD,CAAC;AAC/F,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAO/E,eAAO,MAAM,uBAAuB,0EAM1B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAIxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,oBAAoB,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAG3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAG1B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IAKvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAED,eAAO,MAAM,2BAA2B,cAAc,CAAC;AACvD,eAAO,MAAM,4BAA4B,aAAqD,CAAC"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/contract/database.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,qBAAqB,4CAA6C,CAAC;AAChF,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAKxE,MAAM,MAAM,2BAA2B,GAAG,OAAO,GAAG,QAAQ,CAAC;AAC7D,MAAM,MAAM,kBAAkB,GAAG,2BAA2B,GAAG,UAAU,CAAC;AAE1E,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,kBAAkB,CAAC;IAGzB,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAG9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAID,eAAO,MAAM,yBAAyB,uDAAwD,CAAC;AAC/F,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAO/E,eAAO,MAAM,uBAAuB,0EAM1B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAIxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,oBAAoB,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAG3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAG1B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IAKvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,UAAU,CAAC;AAEf,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,2BAA2B,CAAC;IAClC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAExE,MAAM,MAAM,cAAc,GACtB;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,mBAAmB,EAAE,CAAA;CAAE,GACnD;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAED,eAAO,MAAM,2BAA2B,cAAc,CAAC;AACvD,eAAO,MAAM,4BAA4B,aAAqD,CAAC"}

package/dist/cli/lib/contract/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../../src/cli/lib/contract/database.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,oGAAoG;AACpG,4BAA4B;AAC5B,EAAE;AACF,iGAAiG;AACjG,oGAAoG;AACpG,qFAAqF;AAErF,oGAAoG;AACpG,kGAAkG;AAClG,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAiBhF,kFAAkF;AAClF,oFAAoF;AACpF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAG/F,8FAA8F;AAC9F,iGAAiG;AACjG,gGAAgG;AAChG,gGAAgG;AAChG,0BAA0B;AAC1B,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,QAAQ;IACR,eAAe;IACf,WAAW;IACX,WAAW;IACX,QAAQ;CACA,CAAC;AA4CX,MAAM,CAAC,MAAM,2BAA2B,GAAG,WAAW,CAAC;AACvD,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC"}
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../../src/cli/lib/contract/database.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,oGAAoG;AACpG,4BAA4B;AAC5B,EAAE;AACF,iGAAiG;AACjG,oGAAoG;AACpG,qFAAqF;AAErF,oGAAoG;AACpG,kGAAkG;AAClG,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AA0BhF,kFAAkF;AAClF,oFAAoF;AACpF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;AAG/F,8FAA8F;AAC9F,iGAAiG;AACjG,gGAAgG;AAChG,gGAAgG;AAChG,0BAA0B;AAC1B,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,QAAQ;IACR,eAAe;IACf,WAAW;IACX,WAAW;IACX,QAAQ;CACA,CAAC;AAqEX,MAAM,CAAC,MAAM,2BAA2B,GAAG,WAAW,CAAC;AACvD,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC"}