@synteq/cli 0.2.0 → 1.1.2

package/dist/apps-support/deploy.d.ts

@@ -0,0 +1,197 @@
+import { type ClientRequest, type IncomingMessage } from "node:http";
+import type { ApiClient } from "../api/client.js";
+import type { Build } from "../api/types.js";
+/** Terminal build statuses — polling stops here. Mirrors the backend
+ *  BuildStatus enum (pending | building | pushing | succeeded | failed). */
+export declare const BUILD_TERMINAL: ReadonlySet<string>;
+/** Terminal release outcomes a deploy can end in. */
+export declare const RELEASE_TERMINAL: ReadonlySet<string>;
+export type Frontend = "dockerfile" | "railpack";
+/** 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 declare function pickFrontend(dir: string, explicit?: string | null): Frontend;
+/**
+ * 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 declare const TARBALL_EXCLUDES: readonly [".git", "node_modules", ".venv", "__pycache__"];
+/**
+ * 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 declare function isDotenvName(name: string): boolean;
+/** Does any segment of a slash-separated relative path name a dotenv file? */
+export declare function hasDotenvSegment(relPath: string): boolean;
+/**
+ * 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 declare function dotenvFiles(dir: string): string[];
+/**
+ * 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 declare function sourceRootEntries(dir: string): string[];
+/**
+ * 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 declare function gitSourceList(dir: string): string[] | null;
+/** Extra `--exclude` patterns from a `.synteqignore` in `dir` (one per line,
+ *  `#` comments) for folders that are not git checkouts. */
+export declare function synteqIgnorePatterns(dir: string): string[];
+/**
+ * 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 declare function fetchSourceTarball(rawUrl: string, opts?: {
+    maxBytes?: number;
+    fetchFn?: typeof fetch;
+}): Promise<string>;
+export declare function makeTarball(dir: string): Promise<string>;
+export declare function humanSize(path: string): string;
+export declare function sleep(ms: number): Promise<void>;
+/** 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 declare const RAW_FALLBACK_MAX_BYTES = 95000000;
+/** 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 declare class UploadPutError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * 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 declare function sha256File(path: string): Promise<string>;
+/** Signature of `node:http`/`node:https`'s `request()` — narrowed to what
+ *  `putFile` needs. Overridable via `opts.requestFn` so a test can assert on
+ *  the options passed (e.g. `rejectUnauthorized`) without a real TLS server. */
+export type PutRequestFn = (url: URL, options: Record<string, unknown>, callback: (res: IncomingMessage) => void) => ClientRequest;
+/**
+ * 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 declare function putFile(url: string, path: string, size: number, headers: Record<string, string>, onProgress?: (sentBytes: number, totalBytes: number) => void, opts?: {
+    insecure?: boolean;
+    requestFn?: PutRequestFn;
+}): Promise<void>;
+export interface UploadSourceOpts {
+    /** Integer percent complete (0-100), called only when the value CHANGES
+     *  (m-1) — a raw byte-progress callback fires once per 64 KiB chunk, which
+     *  floods a TUI's React state / a spinner's message with ~16k updates for
+     *  a 1 GB upload. */
+    onProgress?: (percent: number) => void;
+    /** Test-only: replaces the real timer-based wait between retries so a test
+     *  exercising multiple attempts doesn't spend real wall-clock seconds.
+     *  Defaults to the real `sleep`. */
+    sleepFn?: (ms: number) => Promise<void>;
+}
+/**
+ * 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 declare function uploadSource(api: ApiClient, appId: string, archivePath: string, opts?: UploadSourceOpts): Promise<Build>;
+/**
+ * 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 declare function pollBuild(api: ApiClient, appId: string, initial: Build, opts: {
+    intervalMs: number;
+    timeoutMs: number;
+    onStatus?: (status: string, build: Build) => void;
+}): Promise<Build>;
+/**
+ * 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 declare function buildDetail(b: Build): string | 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 declare function resolveNewRelease(api: ApiClient, appId: string, build: Build): Promise<{
+    number: number;
+    id: string;
+} | 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 declare function waitForReleaseOutcome(api: ApiClient, appId: string, releaseNumber: number, timeoutSeconds: number, onTick?: (status: string | null) => void): Promise<string | null>;