@synteq/cli 0.2.0 → 1.1.2

package/dist/apps-support/deploy.js

@@ -0,0 +1,639 @@
+/**
+ * Source deploy plumbing shared by `synteq deploy` and the TUI's Deploy
+ * walkthrough: pack a directory, pick the build frontend, and follow a
+ * build → release to its outcome. Lifted out of commands/deploy.ts so the
+ * two surfaces cannot drift (the same excludes, the same terminal states,
+ * the same "a succeeded build is not a live release" rule).
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync, statSync, lstatSync, existsSync, readdirSync, readFileSync, createReadStream, createWriteStream, rmSync, } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { ApiError, NetworkError } from "../api/errors.js";
+import { isTransientError } from "../ui/wait.js";
+/** Terminal build statuses — polling stops here. Mirrors the backend
+ *  BuildStatus enum (pending | building | pushing | succeeded | failed). */
+export const BUILD_TERMINAL = new Set(["succeeded", "failed"]);
+/** Terminal release outcomes a deploy can end in. */
+export const RELEASE_TERMINAL = new Set([
+    "live",
+    "start_failed",
+    "health_failed",
+    "superseded",
+]);
+/** An explicit choice wins; otherwise a Dockerfile in the source root means
+ *  `dockerfile`, and its absence means `railpack` (zero-config). Without
+ *  this a Dockerfile-less repo would fail with "open Dockerfile: no such
+ *  file". */
+export function pickFrontend(dir, explicit) {
+    if (explicit === "dockerfile" || explicit === "railpack")
+        return explicit;
+    return existsSync(join(dir, "Dockerfile")) ? "dockerfile" : "railpack";
+}
+/**
+ * Tarball a directory to a temp .tgz using the system `tar`. Excludes
+ * dependency caches and VCS metadata ONLY — they are never build inputs and
+ * dominate the archive. Build OUTPUT directories (`dist`, `.next`) are
+ * deliberately kept: a Go app embedding its prebuilt frontend needs them,
+ * and anchoring an exclude to the root is not portable across GNU tar and
+ * bsdtar. Resolves to the archive path.
+ */
+/** Never build inputs: dependency caches and VCS metadata. */
+export const TARBALL_EXCLUDES = [".git", "node_modules", ".venv", "__pycache__"];
+/** The `.env.*` spellings that document the variables an app wants, never
+ *  their values: they ship like any other file. */
+const DOTENV_DOC_SUFFIXES = [".example", ".sample", ".template"];
+/**
+ * Is `name` (one path segment) a dotenv file: `.env` or `.env.<anything>`
+ * (`.env.local`, `.env.production`), but not `.env.example`, `.env.sample`
+ * or `.env.template`?
+ *
+ * A dotenv file holds the secrets of the machine you deploy FROM. It is never
+ * packed, on any intake path: the image goes to a registry and a `COPY . .`
+ * would bake it into every layer, so the orchestrator drops it at extraction
+ * too (apps `build.IsDotenvName`, the same rule). Variables for the deployed
+ * app are set with `synteq app env set` / `synteq function env set` or the
+ * Environment tab and injected at run time. There is no opt-in: `tar` has no
+ * negation, and a `!.env` line in `.synteqignore` is not honoured.
+ */
+export function isDotenvName(name) {
+    if (name === ".env")
+        return true;
+    if (!name.startsWith(".env."))
+        return false;
+    return !DOTENV_DOC_SUFFIXES.some((s) => name.endsWith(s));
+}
+/** Does any segment of a slash-separated relative path name a dotenv file? */
+export function hasDotenvSegment(relPath) {
+    return relPath.split("/").some(isDotenvName);
+}
+/**
+ * The dotenv files `makeTarball` leaves out of `dir`, as root-relative
+ * paths: what git lists for a checkout, else a walk of the tree (skipping
+ * `TARBALL_EXCLUDES` and never following symlinks). Printed by the deploy so
+ * nobody wonders where their `.env` went.
+ */
+export function dotenvFiles(dir) {
+    const files = gitSourceListRaw(dir);
+    if (files !== null)
+        return files.filter(hasDotenvSegment).sort();
+    const found = [];
+    const walk = (abs, rel) => {
+        let entries;
+        try {
+            entries = readdirSync(abs);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries.sort()) {
+            if (TARBALL_EXCLUDES.includes(name))
+                continue;
+            const relPath = rel ? `${rel}/${name}` : name;
+            let st;
+            try {
+                st = lstatSync(join(abs, name));
+            }
+            catch {
+                continue;
+            }
+            if (st.isSymbolicLink())
+                continue;
+            if (isDotenvName(name)) {
+                found.push(relPath);
+                continue;
+            }
+            if (st.isDirectory())
+                walk(join(abs, name), relPath);
+        }
+    };
+    walk(dir, "");
+    return found;
+}
+/** Build OUTPUT that can legitimately be shipped (a prebuilt frontend) but
+ *  never counts as "source" on its own — a checkout with nothing else left
+ *  in it (a branch switch that removed the tracked files, a wrong cwd) is
+ *  exactly the upload that fails late in the builder with a bare "could not
+ *  determine how to build the app". */
+const OUTPUT_ONLY_DIRS = new Set(["dist", "build", "out", ".next", ".nuxt", "target", ".output", "coverage"]);
+/**
+ * The names at the root of what `makeTarball` would ship that are actual
+ * source: anything that is not an excluded cache, not build output, and not
+ * OS/editor noise. Empty means there is nothing for a builder to work from.
+ */
+export function sourceRootEntries(dir) {
+    return readdirSync(dir).filter((name) => !TARBALL_EXCLUDES.includes(name) &&
+        !OUTPUT_ONLY_DIRS.has(name) &&
+        !isDotenvName(name) &&
+        name !== ".DS_Store" &&
+        !name.startsWith("._"));
+}
+/**
+ * The file list `makeTarball` ships when `dir` is a git checkout: what git
+ * itself considers tracked or untracked-but-not-ignored, so `.gitignore` is
+ * honoured exactly and build output such as `.next`, `.open-next` or
+ * `.wrangler` never ships (the 471 MB marketing-site pack, 2026-09-27). Null
+ * when `dir` is not a git checkout or git is unavailable; the caller then
+ * falls back to the static excludes plus `.synteqignore`. Paths are relative
+ * to `dir`. Dotenv files (`isDotenvName`) are left out even when git tracks
+ * them.
+ */
+export function gitSourceList(dir) {
+    return gitSourceListRaw(dir)?.filter((f) => !hasDotenvSegment(f)) ?? null;
+}
+/** `gitSourceList` before the dotenv rule: what git says is source. */
+function gitSourceListRaw(dir) {
+    const probe = spawnSync("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"], { encoding: "utf8" });
+    if (probe.status !== 0 || probe.stdout.trim() !== "true")
+        return null;
+    const ls = spawnSync("git", ["-C", dir, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    if (ls.status !== 0)
+        return null;
+    const excluded = new Set(TARBALL_EXCLUDES);
+    return ls.stdout
+        .split("\0")
+        .filter((f) => f.length > 0)
+        .filter((f) => !f.split("/").some((seg) => excluded.has(seg)))
+        .filter((f) => existsSync(join(dir, f)));
+}
+/** Extra `--exclude` patterns from a `.synteqignore` in `dir` (one per line,
+ *  `#` comments) for folders that are not git checkouts. */
+export function synteqIgnorePatterns(dir) {
+    const f = join(dir, ".synteqignore");
+    if (!existsSync(f))
+        return [];
+    return readFileSync(f, "utf8")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith("#"));
+}
+/**
+ * Download a source tarball to a temp file — `synteq deploy --source-url`.
+ * The CLI fetches it and uploads it the way a packed directory goes up: the
+ * platform never dials a customer-supplied URL. Returns the file's path; the
+ * caller removes its directory, as with makeTarball.
+ *
+ * Errors name the host only: a pre-signed URL is a credential.
+ */
+export async function fetchSourceTarball(rawUrl, opts = {}) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error("--source-url is not a valid URL.");
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error("--source-url must be an http(s) URL.");
+    }
+    let res;
+    try {
+        res = await (opts.fetchFn ?? fetch)(url, { redirect: "follow" });
+    }
+    catch {
+        throw new Error(`Could not reach ${url.host} to download the source tarball.`);
+    }
+    if (!res.ok || !res.body) {
+        throw new Error(`${url.host} answered ${res.status} for the source tarball.`);
+    }
+    const tooLarge = () => new Error(`The source tarball is larger than your plan's ${Math.floor((opts.maxBytes ?? 0) / 1_000_000)} MB source limit.`);
+    const announced = Number(res.headers.get("content-length") ?? 0);
+    if (opts.maxBytes && announced > opts.maxBytes)
+        throw tooLarge();
+    const out = join(mkdtempSync(join(tmpdir(), "synteq-deploy-")), "source.tgz");
+    let head = Buffer.alloc(0);
+    let size = 0;
+    const meter = new Transform({
+        transform(chunk, _enc, cb) {
+            size += chunk.length;
+            if (head.length < 2)
+                head = Buffer.concat([head, chunk]).subarray(0, 2);
+            cb(opts.maxBytes && size > opts.maxBytes ? tooLarge() : null, chunk);
+        },
+    });
+    try {
+        await pipeline(Readable.fromWeb(res.body), meter, createWriteStream(out));
+        if (head.length < 2 || head[0] !== 0x1f || head[1] !== 0x8b) {
+            throw new Error(`${url.host} did not return a gzip tarball (.tar.gz / .tgz).`);
+        }
+    }
+    catch (e) {
+        rmSync(dirname(out), { recursive: true, force: true });
+        if (e instanceof Error && /source (tarball|limit)|gzip tarball/.test(e.message))
+            throw e;
+        throw new Error(`The download from ${url.host} was interrupted.`);
+    }
+    return out;
+}
+export function makeTarball(dir) {
+    const out = join(mkdtempSync(join(tmpdir(), "synteq-deploy-")), "source.tgz");
+    const files = gitSourceList(dir);
+    let args;
+    let stdinList = null;
+    if (files !== null) {
+        // git decides what is source: tracked + untracked-not-ignored files.
+        args = ["-czf", out, "-C", dir, "--null", "-T", "-"];
+        stdinList = files.map((f) => `./${f}`).join("\0") + (files.length ? "\0" : "");
+    }
+    else {
+        // Dotenv files go in by the basenames actually present (`.env`,
+        // `.env.local`...): a basename `--exclude` matches at any depth on both
+        // GNU tar and bsdtar, and naming only the files found keeps
+        // `.env.example` — tar has no way to say `.env.*` minus the docs.
+        const dotenv = [...new Set(dotenvFiles(dir).map((f) => f.slice(f.lastIndexOf("/") + 1)))];
+        const excludes = [...TARBALL_EXCLUDES, ...dotenv, ...synteqIgnorePatterns(dir)];
+        args = ["-czf", out, ...excludes.flatMap((e) => ["--exclude", e]), "-C", dir, "."];
+    }
+    return new Promise((res, rej) => {
+        // COPYFILE_DISABLE: macOS bsdtar otherwise writes AppleDouble `._name`
+        // entries next to every file with extended attributes, which the builder
+        // then lists as if they were source.
+        const p = spawn("tar", args, {
+            stdio: [stdinList === null ? "ignore" : "pipe", "ignore", "pipe"],
+            env: { ...process.env, COPYFILE_DISABLE: "1" },
+        });
+        if (stdinList !== null && p.stdin)
+            p.stdin.end(stdinList);
+        let stderr = "";
+        p.stderr?.on("data", (d) => (stderr += d.toString()));
+        p.on("error", (e) => rej(new Error(`Could not run tar (${e.message}). Is tar installed?`)));
+        p.on("close", (code) => code === 0 ? res(out) : rej(new Error(`tar exited ${code}: ${stderr.trim() || "unknown error"}`)));
+    });
+}
+export function humanSize(path) {
+    try {
+        const bytes = statSync(path).size;
+        if (bytes < 1024)
+            return `${bytes} B`;
+        if (bytes < 1024 * 1024)
+            return `${(bytes / 1024).toFixed(1)} KB`;
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+    catch {
+        return "?";
+    }
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// ── Direct source upload (task P3) ──────────────────────────────────────
+//
+// `synteq deploy --dir` used to send the whole tarball as the raw body of
+// POST /apps/{id}/deploys/source. A proxy in front of the API rejects
+// bodies over 100 MB, and the archive can legitimately be ~1 GB, so the
+// direct path instead PUTs the file straight to the object store via a
+// presigned URL the API mints, then tells the API which object to build
+// from. `uploadSource()` is the one entry point both `commands/deploy.ts`
+// and `tui/screens/Deploy.tsx` call, so the two surfaces can't diverge on
+// retry/fallback behaviour.
+/** Packed-source cap the CLI falls back to the raw-body upload under, when
+ *  the cluster doesn't support direct upload at all (D6 in the design doc). */
+export const RAW_FALLBACK_MAX_BYTES = 95_000_000;
+const UPLOAD_MAX_ATTEMPTS = 3;
+const UPLOAD_BACKOFF_MS = [1000, 3000];
+/** Thrown by `putFile` for a non-2xx response from the upload host, so
+ *  `uploadSource` can tell a signature/size mismatch (403 — do not retry)
+ *  apart from a transient 5xx (retry with a fresh URL) without parsing
+ *  strings. */
+export class UploadPutError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "UploadPutError";
+    }
+}
+/**
+ * SHA-256 of a file, streamed — never loads the file into memory. The
+ * archive can be ~1 GB; `crypto.createHash` over `fs.createReadStream` is
+ * the only way to hash that without a huge Buffer.
+ */
+export function sha256File(path) {
+    return new Promise((resolvePromise, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(path);
+        stream.on("error", reject);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolvePromise(hash.digest("hex")));
+    });
+}
+/**
+ * PUT a file's exact bytes to a presigned URL, streamed (never buffers the
+ * whole file). Uses `node:http`/`node:https` directly rather than `fetch`
+ * with a stream body: a streamed fetch body can fall back to chunked
+ * transfer-encoding instead of sending an explicit `Content-Length`, and the
+ * signed URL's signature covers `Content-Length` — a request that arrives
+ * chunked (or with any other length) is refused with 403. `http.request`
+ * with the header set explicitly always sends exactly that Content-Length
+ * and never adds Transfer-Encoding (verified against a local test server —
+ * see test/apps-support/upload.test.ts).
+ *
+ * Sends no `Authorization` header — the URL itself is the credential, and
+ * the caller's bearer token/API key must never reach the object-store host.
+ * Resolves on 2xx; rejects with `UploadPutError` (carrying the status) on
+ * any other response, or with the underlying error for a network failure.
+ *
+ * Settles EXACTLY ONCE no matter how the connection ends: a clean 2xx/non-2xx
+ * response, a request-level error, a response-level error/abort, the
+ * underlying connection closing before a response ever completed (I-2 — a
+ * server that sends headers and part of a body, then drops the socket, used
+ * to leave this promise unsettled forever), or a 300s stall with no response
+ * (`req.setTimeout`, matching the platform's own idle timeout). The file read
+ * stream is destroyed whenever the request settles, whichever way.
+ */
+export function putFile(url, path, size, headers, onProgress, opts = {}) {
+    return new Promise((resolvePromise, reject) => {
+        let target;
+        try {
+            target = new URL(url);
+        }
+        catch (e) {
+            reject(e instanceof Error ? e : new Error(String(e)));
+            return;
+        }
+        const isHttps = target.protocol === "https:";
+        const doRequest = opts.requestFn ?? (isHttps ? httpsRequest : httpRequest);
+        // The signed URL's signature covers Content-Length; make sure OUR value
+        // wins and nothing upstream can sneak in a Transfer-Encoding instead.
+        const reqHeaders = { ...headers };
+        for (const k of Object.keys(reqHeaders)) {
+            if (k.toLowerCase() === "transfer-encoding")
+                delete reqHeaders[k];
+        }
+        reqHeaders["Content-Length"] = String(size);
+        const reqOptions = { method: "PUT", headers: reqHeaders };
+        if (isHttps && opts.insecure)
+            reqOptions.rejectUnauthorized = false;
+        let settled = false;
+        const stream = createReadStream(path);
+        const finish = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            stream.destroy();
+            if (err)
+                reject(err);
+            else
+                resolvePromise();
+        };
+        const req = doRequest(target, reqOptions, (res) => {
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                body += chunk;
+            });
+            res.on("end", () => {
+                const status = res.statusCode ?? 0;
+                if (status >= 200 && status < 300) {
+                    finish();
+                }
+                else {
+                    finish(new UploadPutError(status, `Upload PUT failed with HTTP ${status}${body ? `: ${body.slice(0, 300)}` : ""}`));
+                }
+            });
+            // A connection that dies mid-response (after headers, before `end`)
+            // used to leave the promise unsettled forever — I-2.
+            res.on("error", (e) => finish(e instanceof Error ? e : new Error(String(e))));
+            res.on("aborted", () => finish(new Error("Upload response aborted before it finished.")));
+        });
+        // Matches the platform's own 300s idle timeout on this link — a stalled
+        // upload (no response, connection never closes) settles rather than
+        // hanging the command forever.
+        req.setTimeout(300_000, () => {
+            req.destroy(new Error("upload stalled"));
+        });
+        req.on("error", (e) => finish(e));
+        // The connection closing without a completed response (no `end`, no
+        // `error`) is the other half of I-2 — `finish`'s guard makes this a
+        // no-op on the normal path, where `end`/`error` already settled first.
+        req.on("close", () => finish(new Error("Upload connection closed before a response was received.")));
+        let sent = 0;
+        stream.on("error", (e) => {
+            req.destroy();
+            finish(e);
+        });
+        stream.on("data", (chunk) => {
+            sent += chunk.length;
+            onProgress?.(sent, size);
+        });
+        stream.pipe(req);
+    });
+}
+/**
+ * Upload a packed source archive and trigger the build — the one path both
+ * `synteq deploy --dir` and the TUI's Deploy walkthrough call.
+ *
+ * Tries direct upload first: mint a presigned PUT (fresh on every attempt —
+ * a used or expired URL must not be reused; a retry's mint names the
+ * previous attempt's object key as `replaces`), stream the file to it, then
+ * tell the API which object to build. Up to 3 attempts total; a network
+ * error or a 5xx from the upload host retries (1s, then 3s backoff) with a
+ * brand-new URL; a 403 (signature/size mismatch) is reported immediately,
+ * never retried, since retrying with the same bytes would fail identically.
+ *
+ * Falls back to the existing raw-body upload (`apps.deploySource`, which
+ * buffers the whole tarball) when the API's upload-url endpoint answers
+ * 501/404/405 — an older server, or a cluster that doesn't support direct
+ * upload at all — and the pack is small enough for the proxy's 100 MB body
+ * limit (95 MB budget, D6). Otherwise fails with exit 1 (thrown Error) and
+ * says so.
+ */
+export async function uploadSource(api, appId, archivePath, opts = {}) {
+    const size = statSync(archivePath).size;
+    const sha256 = await sha256File(archivePath);
+    const doSleep = opts.sleepFn ?? sleep;
+    // Each mint holds one of the user's few pending-upload slots on the API.
+    // A retry names the attempt it replaces so that slot is released first —
+    // otherwise one failed deploy (3 mints) fills them all. An older API
+    // rejects the unknown field with 422: mint once more without it, and stop
+    // sending it for the rest of this upload.
+    let previousKey;
+    let sendReplaces = true;
+    const mintUploadUrl = async () => {
+        const replaces = sendReplaces ? previousKey : undefined;
+        if (replaces === undefined)
+            return api.apps.sourceUploadUrl(appId, { sizeBytes: size, sha256 });
+        try {
+            return await api.apps.sourceUploadUrl(appId, { sizeBytes: size, sha256, replaces });
+        }
+        catch (e) {
+            if (!(e instanceof ApiError && e.status === 422))
+                throw e;
+            sendReplaces = false;
+            return api.apps.sourceUploadUrl(appId, { sizeBytes: size, sha256 });
+        }
+    };
+    for (let attempt = 0; attempt < UPLOAD_MAX_ATTEMPTS; attempt++) {
+        let mint;
+        try {
+            mint = await mintUploadUrl();
+            previousKey = mint.objectKey;
+        }
+        catch (e) {
+            // m-3: only an old orchestrator (no route at all) or a cluster that
+            // has switched direct upload off falls back to the raw body. A 404
+            // from `_load_owned_app` (the app itself is gone) shares the status
+            // code but carries FastAPI's real detail, never the generic
+            // route-missing "Not Found" — that case must surface as-is so a
+            // vanished app isn't reported as "direct upload not available".
+            if (e instanceof ApiError &&
+                (e.status === 501 || e.status === 405 || (e.status === 404 && e.detail === "Not Found"))) {
+                return fallbackToRawUpload(api, appId, archivePath, size);
+            }
+            if (e instanceof NetworkError && attempt < UPLOAD_MAX_ATTEMPTS - 1) {
+                await doSleep(UPLOAD_BACKOFF_MS[attempt] ?? 3000);
+                continue;
+            }
+            throw e;
+        }
+        let lastPercent = -1;
+        try {
+            await putFile(mint.uploadUrl, archivePath, size, mint.headers, (sentBytes, totalBytes) => {
+                // m-1: fire onProgress only when the integer percent changes — a
+                // raw per-chunk callback floods the TUI/spinner with ~16k updates
+                // for a 1 GB upload.
+                const pct = Math.floor((sentBytes / totalBytes) * 100);
+                if (pct !== lastPercent) {
+                    lastPercent = pct;
+                    opts.onProgress?.(pct);
+                }
+            }, { insecure: api.insecureTls });
+        }
+        catch (e) {
+            if (e instanceof UploadPutError) {
+                if (e.status === 403) {
+                    throw new Error("Upload rejected (403) — the signed upload URL no longer matches this file. Re-run the deploy.");
+                }
+                if (e.status >= 500 && attempt < UPLOAD_MAX_ATTEMPTS - 1) {
+                    await doSleep(UPLOAD_BACKOFF_MS[attempt] ?? 3000);
+                    continue;
+                }
+                // m-2: retries exhausted (or a non-403 status that isn't retried at
+                // all) — surface as the CLI's NetworkError (no url: the upload host's
+                // URL/query/object key must never reach a message) so
+                // BaseCommand.fail() maps it to exit 3, matching the CLI's contract
+                // for a server/network fault. The synthetic cause below carries only
+                // the HTTP status, never `e.message` (which can hold up to 300 bytes
+                // of the object store's raw XML error body, itself carrying the
+                // object key).
+                throw new NetworkError(new Error(`Upload host returned HTTP ${e.status}.`));
+            }
+            // A network error talking to the upload host — same retry rule as a
+            // network error minting the URL. Once retries are exhausted, wrap the
+            // raw node error (ECONNREFUSED/ECONNRESET/etc — carries host:port at
+            // most, never a path or query) the same way, for the same exit code.
+            if (attempt < UPLOAD_MAX_ATTEMPTS - 1) {
+                await doSleep(UPLOAD_BACKOFF_MS[attempt] ?? 3000);
+                continue;
+            }
+            throw new NetworkError(e);
+        }
+        return api.apps.deploySourceObject(appId, mint.objectKey);
+    }
+    throw new NetworkError(new Error("Uploading the source failed after 3 attempts."));
+}
+async function fallbackToRawUpload(api, appId, archivePath, size) {
+    if (size > RAW_FALLBACK_MAX_BYTES) {
+        throw new Error(`Direct upload is not available on this cluster, and the packed source ` +
+            `(${(size / 1_000_000).toFixed(1)} MB) is over the ${RAW_FALLBACK_MAX_BYTES / 1_000_000} MB ` +
+            `limit without it. Reduce the archive size, or ask an operator to enable direct upload.`);
+    }
+    const tarball = await readFile(archivePath);
+    return api.apps.deploySource(appId, new Uint8Array(tarball));
+}
+/**
+ * Poll GET /apps/{id}/builds until the build reaches a terminal status or
+ * the timeout elapses. `onStatus` fires on every observed transition — of
+ * the status, or of the queue position / build VM while the status holds
+ * (bpool1) — so a caller can drive a spinner or a checklist. Returns the
+ * final build row — the caller decides what "timed out while building"
+ * means.
+ */
+export async function pollBuild(api, appId, initial, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    let current = initial;
+    opts.onStatus?.(current.status, current);
+    while (!BUILD_TERMINAL.has(current.status) && Date.now() < deadline) {
+        await sleep(opts.intervalMs);
+        try {
+            const builds = await api.apps.builds(appId);
+            const found = builds.find((b) => b.id === initial.id);
+            if (found && (found.status !== current.status || buildDetail(found) !== buildDetail(current))) {
+                opts.onStatus?.(found.status, found);
+            }
+            if (found)
+                current = found;
+        }
+        catch (e) {
+            // A dropped connection or a 5xx is worth polling through. An expired
+            // session (or any other 4xx) is not: it would be retried, silently,
+            // until the 30-minute deadline. Same classification as `waitFor`.
+            if (!isTransientError(e))
+                throw e;
+        }
+    }
+    return current;
+}
+/**
+ * The detail line behind a build's status while it waits or runs (bpool1):
+ * "Queued — position 2 of 5" from the orchestrator's build queue. Null when
+ * there is nothing to add (which build VM runs it stays internal).
+ */
+export function buildDetail(b) {
+    if (b.status === "pending" && b.queuePosition && b.queueTotal) {
+        return `Queued — position ${b.queuePosition} of ${b.queueTotal}`;
+    }
+    return null;
+}
+/**
+ * After a successful build, the release it produced — matched by image
+ * digest, polled briefly because the status cron mints it a beat after the
+ * build flips to succeeded. Null when it has not appeared in time.
+ */
+export async function resolveNewRelease(api, appId, build) {
+    if (!build.imageDigest)
+        return null;
+    for (let i = 0; i < 6; i++) {
+        try {
+            const releases = await api.apps.releases(appId);
+            const match = releases.find((r) => r.imageDigest === build.imageDigest);
+            if (match)
+                return { number: match.number, id: match.id };
+        }
+        catch {
+            // transient — try again
+        }
+        await sleep(1500);
+    }
+    return null;
+}
+/**
+ * Wait for a release to reach a terminal outcome — live, start_failed,
+ * health_failed, superseded — or return null when the window runs out (still
+ * rolling). This is what stops a caller from declaring "Deployed" on a build
+ * whose release then fails its rollout.
+ */
+export async function waitForReleaseOutcome(api, appId, releaseNumber, timeoutSeconds, onTick) {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    while (Date.now() < deadline) {
+        try {
+            const releases = await api.apps.releases(appId);
+            const r = releases.find((x) => x.number === releaseNumber);
+            onTick?.(r?.status ?? null);
+            if (r && RELEASE_TERMINAL.has(r.status))
+                return r.status;
+        }
+        catch {
+            // transient — keep polling
+        }
+        await sleep(3000);
+    }
+    return null;
+}
+//# sourceMappingURL=deploy.js.map