unfazed 0.0.1 → 0.2.0

package/dist/unfazed.js

@@ -0,0 +1,738 @@
+import { UnfazedClient } from "./client.js";
+import { DEPLOYMENT_NOT_FOUND, UnfazedConflictError, UnfazedDeployError, UnfazedGraphQLError, UnfazedNotFoundError, WORKSPACE_NOT_FOUND, isDuplicateWorkspaceName, isNotFoundSentinel as isNotFound, looksLikeCASConflict, } from "./errors.js";
+import * as ops from "./operations.js";
+import { pollWithBackoff, resolveWaitOptions } from "./wait.js";
+/**
+ * Layer 2 — the agent workflow layer.
+ *
+ * Wraps the chains an agent actually performs (create → write → deploy → wait
+ * → read logs → roll back) so a code-mode script does in one call what would
+ * otherwise be many round trips through a model's context. Everything here is
+ * built on {@link UnfazedClient}, exposed as `.client` for anything not
+ * wrapped.
+ *
+ * ```ts
+ * const unfazed = new Unfazed();                       // reads UNFZ_API_TOKEN
+ * const ws = await unfazed.createWorkspace("hello");
+ * await unfazed.writeFiles(ws.id, { "server.ts": code });
+ * const app = await unfazed.deployService({ workspaceId: ws.id, alias: "hello", wait: true });
+ * console.log(app.url);
+ * ```
+ */
+export class Unfazed {
+    /** The underlying typed GraphQL client. Use it for un-wrapped operations. */
+    client;
+    constructor(options = {}) {
+        const { client, ...clientOptions } = options;
+        this.client = client ?? new UnfazedClient(clientOptions);
+    }
+    /* ---------------------------------------------------------------- identity */
+    /** Who this token authenticates as, plus usage and resource limits. */
+    async whoami(options) {
+        const data = await this.client.query(ops.WhoamiDocument, {}, options);
+        return data.whoami;
+    }
+    /* -------------------------------------------------------------- workspaces */
+    /** Creates a source workspace — the container for files, env and deployments. */
+    async createWorkspace(name, options) {
+        const data = await this.client.mutate(ops.CreateWorkspaceDocument, { name }, options);
+        return data.createWorkspace.workspace;
+    }
+    /** Workspaces visible to this token. */
+    async listWorkspaces(options) {
+        const data = await this.client.query(ops.ListWorkspacesDocument, {}, options);
+        return data.workspaces;
+    }
+    /**
+     * Deletes a workspace and everything anchored to it — deployments, env, and
+     * a BOX's persistent data disk. Not recoverable.
+     *
+     * **The cascade is opt-out, not opt-in.** The server refuses to delete a
+     * workspace that has ANY deployment history — including FAILED records, and
+     * including deployments whose alias was long since taken over by something
+     * else — unless the mutation carries `withDeployments`. Since almost every
+     * workspace an agent creates gets deployed at least once, defaulting to
+     * `false` would make this method fail on nearly every real workspace, so it
+     * defaults to **`true`**: the behaviour this docstring has always promised.
+     *
+     * Pass `withDeployments: false` for the strict variant, which refuses rather
+     * than cascading and is the safer choice when you are deleting a workspace
+     * you did not create:
+     *
+     * ```ts
+     * await unfazed.deleteWorkspace(ws.id);                            // cascade
+     * await unfazed.deleteWorkspace(ws.id, { withDeployments: false }); // refuse if deployed
+     * await unfazed.deleteWorkspace(id, { ignoreNotFound: true });      // false, not a throw
+     * ```
+     *
+     * With `ignoreNotFound` a workspace that is absent (or belongs to someone
+     * else — the server returns one indistinguishable sentinel for both, on
+     * purpose) resolves to `false` instead of throwing, which makes teardown in
+     * a `finally` block idempotent.
+     */
+    async deleteWorkspace(workspaceId, options = {}) {
+        const withDeployments = options.withDeployments ?? true;
+        try {
+            const data = await this.client.mutate(ops.DeleteWorkspaceDocument, { workspaceID: workspaceId, withDeployments }, options);
+            return data.deleteWorkspace.ok;
+        }
+        catch (e) {
+            if (options.ignoreNotFound && isNotFound(e, WORKSPACE_NOT_FOUND))
+                return false;
+            throw e;
+        }
+    }
+    /**
+     * Returns the workspace named `name`, creating it only if it does not exist.
+     *
+     * Workspace names are unique per owner, case-insensitively — a second
+     * `createWorkspace("Hello")` after a `createWorkspace("hello")` is an error,
+     * not a second workspace. That makes the bare create a poor fit for any
+     * script that might run twice; this is the re-runnable form.
+     *
+     * ```ts
+     * const ws = await unfazed.ensureWorkspace("greeter");   // safe to re-run
+     * ```
+     *
+     * Costs one list, plus one create only on a miss. The create is still
+     * guarded: if a concurrent caller wins the race, the duplicate-name error is
+     * caught and the now-existing workspace is returned instead of thrown.
+     */
+    async ensureWorkspace(name, options) {
+        const existing = await this.#findWorkspaceByName(name, options);
+        if (existing)
+            return existing;
+        try {
+            return await this.createWorkspace(name, options);
+        }
+        catch (e) {
+            // Lost a create/create race, or the server's case folding is stricter
+            // than ours. Either way the workspace exists now — re-read rather than
+            // failing a script whose intent was "make sure this exists".
+            if (!isDuplicateWorkspaceName(e))
+                throw e;
+            const raced = await this.#findWorkspaceByName(name, options);
+            if (raced)
+                return raced;
+            // The name is taken by something we cannot see. Surface the real error.
+            throw e;
+        }
+    }
+    /* ------------------------------------------------------------------- files */
+    /**
+     * Writes many files in as few requests as possible.
+     *
+     * The API is one-file-per-mutation, so writing a 12-file app naively costs 12
+     * round trips. This batches them into a single GraphQL document with one
+     * ALIASED root field per file (`f0: writeWorkspaceTextFile(...)`,
+     * `f1: ...`), which the server resolves in one request.
+     *
+     * ```ts
+     * await unfazed.writeFiles(ws.id, {
+     *   "server.ts": serverCode,
+     *   "unfazed.json": JSON.stringify({ entry: "server.ts" }),
+     *   "public/logo.png": { bytes: pngBytes },
+     * });
+     * ```
+     *
+     * Batches are NOT atomic: GraphQL resolves each aliased field independently,
+     * so a partial failure leaves earlier writes committed. The thrown
+     * {@link UnfazedGraphQLError} carries `data` with whichever aliases
+     * succeeded, and `error.path` identifies the ones that did not.
+     */
+    async writeFiles(workspaceId, files, options = {}) {
+        const entries = Object.entries(files).map(([path, content]) => normalizeFile(path, content));
+        if (entries.length === 0)
+            return [];
+        const batchSize = options.batchSize ?? 20;
+        const maxBatchBytes = options.maxBatchBytes ?? 4 * 1024 * 1024;
+        const written = [];
+        for (const batch of chunkFiles(entries, batchSize, maxBatchBytes)) {
+            written.push(...(await this.#writeBatch(workspaceId, batch, options.signal)));
+        }
+        return written;
+    }
+    /** Writes one text file. Prefer {@link writeFiles} for more than one. */
+    async writeFile(workspaceId, path, text, options) {
+        const data = await this.client.mutate(ops.WriteTextFileDocument, { workspaceID: workspaceId, path, text }, options);
+        return data.writeWorkspaceTextFile.file;
+    }
+    /** Writes one binary file. Accepts raw bytes or a base64 string. */
+    async writeBinaryFile(workspaceId, path, content, options) {
+        const contentBase64 = "base64" in content ? content.base64 : toBase64(content);
+        const data = await this.client.mutate(ops.WriteBase64FileDocument, { workspaceID: workspaceId, path, contentBase64 }, options);
+        return data.writeWorkspaceBase64File.file;
+    }
+    /** Lists workspace files (paginated). */
+    async listFiles(workspaceId, input = {}, options) {
+        const data = await this.client.query(ops.ListFilesDocument, { input: { workspaceID: workspaceId, ...input } }, options);
+        return data.workspaceFilesPage;
+    }
+    /** Reads a text file, optionally a byte range of it. Null when absent. */
+    async readFile(workspaceId, path, input = {}, options) {
+        const data = await this.client.query(ops.ReadFileDocument, { input: { workspaceID: workspaceId, path, ...input } }, options);
+        return data.readWorkspaceFile;
+    }
+    /**
+     * Deletes a workspace file.
+     *
+     * Returns `false` when there was nothing to delete — an absent path is not
+     * an error. See the `ok: false` convention on {@link deleteEnv}.
+     */
+    async deleteFile(workspaceId, path, options) {
+        const data = await this.client.mutate(ops.DeleteFileDocument, { workspaceID: workspaceId, path }, options);
+        return data.deleteWorkspaceFile.ok;
+    }
+    /* ----------------------------------------------------------------- deploys
+     *
+     * Every deploy method here MINTS A NEW RELEASE on every call. There is no
+     * content dedupe: deploying byte-identical files twice produces two distinct
+     * releases with two ids, both real, both counting against retention (which
+     * keeps only the most recent few per alias and prunes the rest). Deploying
+     * in a retry loop is therefore not free — it churns the release history and
+     * can push a release you still wanted to roll back to out of retention.
+     * Check {@link getDeployment} or {@link listReleases} before redeploying if
+     * you only meant to converge.
+     */
+    /**
+     * Deploys the workspace as a SERVICE (an HTTP server).
+     *
+     * With `wait: true` this resolves only once the build, VM boot and health
+     * probe have all passed.
+     *
+     * Passing the same `alias` again redeploys that alias — a new release that
+     * takes over the alias when it goes READY. Omitting `alias` lets the server
+     * generate one, which means a different app on every call.
+     */
+    deployService(options) {
+        const { workspaceId, alias, runtime, serviceMode, healthPath, cronSchedule, cronPath } = options;
+        return this.#deploy({
+            workspaceID: workspaceId,
+            kind: "SERVICE",
+            ...(alias === undefined ? {} : { alias }),
+            ...(runtime === undefined ? {} : { runtime }),
+            ...(serviceMode === undefined ? {} : { serviceMode }),
+            ...(healthPath === undefined ? {} : { healthPath }),
+            ...(cronSchedule === undefined ? {} : { cronSchedule }),
+            ...(cronPath === undefined ? {} : { cronPath }),
+        }, options);
+    }
+    /** Deploys the workspace as a STATIC site. */
+    deployStatic(options) {
+        const { workspaceId, alias, spaMode } = options;
+        return this.#deploy({
+            workspaceID: workspaceId,
+            kind: "STATIC",
+            ...(alias === undefined ? {} : { alias }),
+            ...(spaMode === undefined ? {} : { spaMode }),
+        }, options);
+    }
+    /**
+     * Deploys a BOX: a persistent always-on Linux VM with a data disk that
+     * survives stops and redeploys. A dev machine, not an HTTP service. The
+     * result's `sshCommand` is how you get in.
+     *
+     * ⚠️ **Omitting `alias` creates a NEW BOX every single call.** There is no
+     * "the workspace's box" to update: with no alias the server generates a
+     * fresh random one, so a script run twice leaves you with two box records,
+     * not one redeployed box.
+     *
+     * The data disk, meanwhile, is keyed by WORKSPACE — one disk, shared by
+     * every box in the workspace, and it is the box's real identity. Since only
+     * one VM can hold that disk read-write, the second box cannot even start
+     * while the first is running (`box data disk for workspace ... is attached
+     * to VM ...; stop it first`). The result is a pile of dead box records
+     * fighting over one disk.
+     *
+     * **Always pass an explicit `alias` in anything re-runnable.** Redeploying
+     * the same alias is the in-place update you actually want.
+     *
+     * ```ts
+     * await unfazed.deployBox({ workspaceId: ws.id, alias: "dev" });   // re-runnable
+     * ```
+     */
+    deployBox(options) {
+        const { workspaceId, alias, resources } = options;
+        return this.#deploy({
+            workspaceID: workspaceId,
+            kind: "BOX",
+            ...(alias === undefined ? {} : { alias }),
+            ...(resources === undefined ? {} : { boxResources: resources }),
+        }, options);
+    }
+    /** Escape hatch: deploy with a raw CreateDeploymentInput. */
+    deploy(input, options = {}) {
+        return this.#deploy(input, options);
+    }
+    async #deploy(input, options) {
+        const requestOptions = options.signal ? { signal: options.signal } : {};
+        const data = await this.client.mutate(ops.CreateDeploymentDocument, { input }, requestOptions);
+        const deployment = data.createDeployment.deployment;
+        if (!options.wait)
+            return deployment;
+        return this.waitForDeployment(deployment.id, {
+            ...options.waitOptions,
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    /**
+     * Polls a deployment until it is READY, throwing on FAILED or timeout.
+     *
+     * BUILDING is the only non-terminal status; READY and FAILED are terminal.
+     * The poll query selects six fields rather than the full deployment, because
+     * this runs every few seconds for potentially minutes — then the READY
+     * deployment is re-read in full so callers get the same shape `deployService`
+     * returns without `wait`.
+     */
+    async waitForDeployment(deploymentId, waitOptions = {}) {
+        const resolved = resolveWaitOptions(waitOptions);
+        const requestOptions = resolved.signal ? { signal: resolved.signal } : {};
+        let last = null;
+        await pollWithBackoff(async () => {
+            const data = await this.client.query(ops.PollDeploymentDocument, { id: deploymentId }, requestOptions);
+            const d = data.deployment;
+            if (!d) {
+                throw new UnfazedNotFoundError(`unfazed: deployment ${deploymentId} not found`);
+            }
+            last = d;
+            if (d.status === "READY")
+                return { done: true, value: true };
+            if (d.status === "FAILED") {
+                throw new UnfazedDeployError("FAILED", deploymentId, d, `unfazed: deployment ${deploymentId} FAILED${d.error ? `: ${d.error}` : ""}`);
+            }
+            return { done: false };
+        }, resolved, () => new UnfazedDeployError("TIMEOUT", deploymentId, last, `unfazed: deployment ${deploymentId} still ${last?.status ?? "BUILDING"} after ${resolved.timeoutMs}ms`));
+        const full = await this.getDeployment(deploymentId, requestOptions);
+        if (!full)
+            throw new UnfazedNotFoundError(`unfazed: deployment ${deploymentId} not found`);
+        return full;
+    }
+    /** Reads one deployment by id. Null when absent. */
+    async getDeployment(deploymentId, options) {
+        const data = await this.client.query(ops.GetDeploymentDocument, { id: deploymentId }, options);
+        return data.deployment;
+    }
+    /** Reads the deployment currently serving an alias. Null when absent. */
+    async getDeploymentByAlias(alias, options) {
+        const data = await this.client.query(ops.GetDeploymentByAliasDocument, { alias }, options);
+        return data.deploymentByAlias;
+    }
+    /** Lists deployments (paginated, filterable by kind/alias/workspace). */
+    async listDeployments(input = {}, options) {
+        const data = await this.client.query(ops.ListDeploymentsDocument, { input }, options);
+        return data.deploymentsPage;
+    }
+    /* ------------------------------------------------------- runtime & logging */
+    /** Live VM status: health, in-flight requests, restarts, RAM ceiling. */
+    async getStatus(deploymentId, options) {
+        const data = await this.client.query(ops.ServiceStatusDocument, { deploymentID: deploymentId }, options);
+        return data.serviceStatus;
+    }
+    /**
+     * Tail of the service's stdout/stderr.
+     *
+     * The point of doing this from a script rather than through tool calls: you
+     * can filter locally. `(await unfazed.getLogs(id)).stderr.split("\n")
+     * .filter(l => l.includes("ERROR"))` costs a model zero context, where the
+     * same tail through an MCP tool spends all of it.
+     */
+    async getLogs(deploymentId, input = {}, options) {
+        const data = await this.client.query(ops.ServiceLogsDocument, { deploymentID: deploymentId, tailBytes: input.tailBytes ?? null }, options);
+        return data.serviceLogs;
+    }
+    /** Deployment lifecycle events — build, boot, probe, cron, restarts. */
+    async getEvents(deploymentId, limit, options) {
+        const data = await this.client.query(ops.DeploymentEventsDocument, { deploymentID: deploymentId, limit: limit ?? null }, options);
+        return data.deploymentEvents;
+    }
+    /** Restarts a service's VM. */
+    async restartService(deploymentId, options) {
+        const data = await this.client.mutate(ops.RestartServiceDocument, { deploymentID: deploymentId }, options);
+        return data.restartService;
+    }
+    /** Stops a service's VM. An on-demand service cold-starts again on request. */
+    async stopService(deploymentId, options) {
+        const data = await this.client.mutate(ops.StopServiceDocument, { deploymentID: deploymentId }, options);
+        return data.stopService;
+    }
+    /**
+     * Deletes a deployment: stops its VM, releases its alias, drops its release.
+     *
+     * With `ignoreNotFound` a deployment that is absent — or belongs to another
+     * tenant, which the server reports identically so ids cannot be probed —
+     * resolves to `false` instead of throwing, making cleanup loops idempotent.
+     */
+    async deleteDeployment(deploymentId, options = {}) {
+        try {
+            const data = await this.client.mutate(ops.DeleteDeploymentDocument, { deploymentID: deploymentId }, options);
+            return data.deleteDeployment.ok;
+        }
+        catch (e) {
+            if (options.ignoreNotFound && isNotFound(e, DEPLOYMENT_NOT_FOUND))
+                return false;
+            throw e;
+        }
+    }
+    /* ------------------------------------------------------------ env & secrets
+     *
+     * Workspace values are SERVICE defaults for every app in the source; app
+     * values override them for one alias. Both are SNAPSHOTTED into a release at
+     * deploy time — changing either does not affect a running app until you
+     * redeploy that alias. Old releases are immutable, and STATIC gets no env.
+     */
+    /**
+     * Sets a workspace-default env var. Redeploy the alias to apply it.
+     *
+     * A name is either plain or secret, never both: this DELETES a workspace
+     * secret of the same name. {@link setSecret} displaces a plain var the same
+     * way. Last write wins, and the kind flips silently — so re-running a setup
+     * script that calls `setSecret("API_KEY", ...)` after one that called
+     * `setEnv("API_KEY", ...)` quietly converts it, and vice versa.
+     */
+    async setEnv(workspaceId, name, value, options) {
+        const data = await this.client.mutate(ops.SetWorkspaceEnvDocument, { workspaceID: workspaceId, name, value }, options);
+        return data.setWorkspaceEnv.env;
+    }
+    /**
+     * Sets a workspace-default secret. The value is never readable again.
+     *
+     * Mutually exclusive with {@link setEnv}: this DELETES a plain workspace var
+     * of the same name. See {@link setEnv} for the displacement rule.
+     */
+    async setSecret(workspaceId, name, value, options) {
+        const data = await this.client.mutate(ops.SetWorkspaceSecretDocument, { workspaceID: workspaceId, name, value }, options);
+        return data.setWorkspaceSecret.env;
+    }
+    /**
+     * Sets many workspace env vars in one request, via aliased mutations —
+     * the same batching trick as {@link writeFiles}.
+     *
+     * Pass `{ secret: true }` to route them all to `setWorkspaceSecret`.
+     *
+     * It inherits {@link writeFiles}' failure semantics too: the batch is NOT
+     * atomic. GraphQL resolves each aliased field independently, so a rejected
+     * name (over the limit, malformed, whatever) leaves the vars before it
+     * already committed. The thrown {@link UnfazedGraphQLError} carries `data`
+     * with the aliases that succeeded and `errors[].path` naming those that did
+     * not — do not assume "it threw" means "nothing was written".
+     *
+     * Each name still displaces its opposite kind, exactly as {@link setEnv} and
+     * {@link setSecret} do one at a time.
+     */
+    async setEnvMany(workspaceId, vars, options = {}) {
+        const entries = Object.entries(vars);
+        if (entries.length === 0)
+            return [];
+        const field = options.secret ? "setWorkspaceSecret" : "setWorkspaceEnv";
+        const varDefs = ["$workspaceID: ID!"];
+        const fields = [];
+        const variables = { workspaceID: workspaceId };
+        entries.forEach(([name, value], i) => {
+            varDefs.push(`$n${i}: String!`, `$v${i}: String!`);
+            variables[`n${i}`] = name;
+            variables[`v${i}`] = value;
+            fields.push(`  e${i}: ${field}(input: { workspaceID: $workspaceID, name: $n${i}, value: $v${i} }) { env { ${ENV_SELECTION} } }`);
+        });
+        const document = `mutation SdkSetEnvBatch(${varDefs.join(", ")}) {\n${fields.join("\n")}\n}`;
+        const data = await this.client.mutate(document, variables, options.signal ? { signal: options.signal } : {});
+        return entries.map((_, i) => data[`e${i}`].env);
+    }
+    /**
+     * Deletes a workspace-default env var (plain or secret).
+     *
+     * **The `ok: false` convention.** A `false` here does NOT mean failure — it
+     * means "nothing to do, the world is already in the state you asked for".
+     * The var did not exist. Every `ok`-returning mutation in this SDK follows
+     * the rule ({@link deleteFile}, {@link inheritAppEnv}, {@link removeAppEnv}),
+     * so the idempotent-cleanup pattern is simply to ignore the boolean; a real
+     * failure throws.
+     */
+    async deleteEnv(workspaceId, name, options) {
+        const data = await this.client.mutate(ops.DeleteWorkspaceEnvDocument, { workspaceID: workspaceId, name }, options);
+        return data.deleteWorkspaceEnv.ok;
+    }
+    /** Workspace-default env vars. Secret values are redacted. */
+    async listEnv(workspaceId, options) {
+        const data = await this.client.query(ops.ListWorkspaceEnvDocument, { workspaceID: workspaceId }, options);
+        return data.workspaceEnv;
+    }
+    /**
+     * Sets an env var for ONE alias, overriding the workspace default.
+     *
+     * Displaces both of the other states this name could be in for the app: it
+     * deletes an app SECRET of the same name, and it CLEARS a REMOVE mask left
+     * by {@link removeAppEnv}. So setting a value is also the way to un-block a
+     * masked name, and a name is only ever one of plain / secret / masked.
+     */
+    async setAppEnv(workspaceId, alias, name, value, options) {
+        const data = await this.client.mutate(ops.SetAppEnvDocument, { workspaceID: workspaceId, alias, name, value }, options);
+        return data.setAppEnv.env;
+    }
+    /**
+     * Sets a secret for ONE alias, overriding the workspace default.
+     *
+     * Like {@link setAppEnv}, this deletes a plain app var of the same name and
+     * clears a REMOVE mask for it.
+     */
+    async setAppSecret(workspaceId, alias, name, value, options) {
+        const data = await this.client.mutate(ops.SetAppSecretDocument, { workspaceID: workspaceId, alias, name, value }, options);
+        return data.setAppSecret.env;
+    }
+    /**
+     * REMOVE: blocks this name for the app entirely — the app override, the
+     * workspace default, and integration enrichment. Not the same as deleting an
+     * override; use {@link inheritAppEnv} for that.
+     *
+     * This WRITES A MASK, and the mask is a real, persistent row. Two things
+     * follow that surprise people:
+     *
+     *  - It is written even when nothing was inherited. Masking a name that no
+     *    workspace default and no integration ever provided is not a no-op; it
+     *    leaves a tombstone that keeps blocking the name if a default appears
+     *    later. Clear it with {@link inheritAppEnv}.
+     *  - It COSTS A SLOT. A workspace gets 128 env entries total — that budget
+     *    is shared across the workspace defaults AND every app scope combined,
+     *    not 128 per scope — and masks count toward it just like values do.
+     *    Masking names in a loop can exhaust the workspace's env budget.
+     *
+     * Returns `false` when the exact mask was already present (a second call for
+     * the same name), per the {@link deleteEnv} `ok: false` convention. It
+     * returns `true` when it had something to change — including converting an
+     * existing override into a mask.
+     */
+    async removeAppEnv(workspaceId, alias, name, options) {
+        const data = await this.client.mutate(ops.RemoveAppEnvDocument, { workspaceID: workspaceId, alias, name }, options);
+        return data.removeAppEnv.ok;
+    }
+    /**
+     * INHERIT: clears the app override/mask so workspace and integration values
+     * apply again. This is the undo for both {@link setAppEnv} and
+     * {@link removeAppEnv}.
+     *
+     * Returns `false` when there was no override and no mask to clear — nothing
+     * to do, not a failure. See {@link deleteEnv}.
+     */
+    async inheritAppEnv(workspaceId, alias, name, options) {
+        const data = await this.client.mutate(ops.InheritAppEnvDocument, { workspaceID: workspaceId, alias, name }, options);
+        return data.inheritAppEnv.ok;
+    }
+    /** The effective env view for one alias: overrides, inherited and masked. */
+    async listAppEnv(workspaceId, alias, options) {
+        const data = await this.client.query(ops.ListAppEnvDocument, { workspaceID: workspaceId, alias }, options);
+        return data.appEnv;
+    }
+    /* -------------------------------------------------- releases & rollback */
+    /**
+     * An alias's terminal release history, newest first.
+     *
+     * Exactly one entry has `aliasHeld: true` — the live release. FAILED entries
+     * appear on purpose (they are rejected promotions, so a kept-live previous
+     * release is never mistaken for a silent fallback) and cannot be rolled back
+     * to. Retention keeps only the most recent few per alias, default 5.
+     */
+    async listReleases(alias, options) {
+        const data = await this.client.query(ops.ListReleasesDocument, { alias }, options);
+        return data.deploymentReleases;
+    }
+    /**
+     * Rolls an alias back to a prior release, handling the whole compare-and-swap
+     * protocol in one call.
+     *
+     * The server requires the caller to prove it observed the current state: you
+     * must pass the live release's id AND its opaque `aliasRevision`, and the
+     * swap fails if either changed since you listed — including same-id ABA. So
+     * this method does the full dance: list releases, find the `aliasHeld` entry,
+     * pick the target, and submit both guard values.
+     *
+     * On a rejected guard it re-lists and retries (default once). The TARGET is
+     * pinned across retries while the guard is refreshed, so a concurrent deploy
+     * can never redirect the rollback to a different release than the one chosen.
+     *
+     * ```ts
+     * await unfazed.rollback({ alias: "my-app" });              // undo last deploy
+     * await unfazed.rollback({ alias: "my-app", to: relId });   // to a specific release
+     * await unfazed.rollback({ alias: "my-app", to: relId, expectedCurrentId: liveId });
+     * ```
+     *
+     * ⚠️ **A bare `rollback({ alias })` is a TOGGLE, not an idempotent step.**
+     * It means "restore the most recent READY release that is not the live one",
+     * which is a different release each time the alias moves. Run the same
+     * script twice and the second run rolls back the rollback — A → B → A → B,
+     * forever, with each hop a real alias swap. Nothing errors, because every
+     * individual call did exactly what it was asked.
+     *
+     * In anything re-runnable — a retry loop, a CI job, an agent that might redo
+     * a step — pin the outcome instead:
+     *
+     *  - `to:` names the release you want live, so re-running is a no-op-ish
+     *    convergence rather than a flip (a second run then reports the target
+     *    already holds the alias instead of moving it);
+     *  - `expectedCurrentId:` states what you expect to be live now, so a second
+     *    run fails loudly instead of silently undoing the first.
+     */
+    async rollback(options) {
+        const { alias, signal, expectedCurrentId } = options;
+        // A caller-supplied precondition and the CAS retry are mutually exclusive:
+        // retrying re-guards against whatever holds the alias NOW, which is the
+        // one thing `expectedCurrentId` exists to refuse.
+        const retries = expectedCurrentId === undefined ? (options.retries ?? 1) : 0;
+        const requestOptions = signal ? { signal } : {};
+        let targetId = options.to;
+        for (let attempt = 0;; attempt++) {
+            const releases = await this.listReleases(alias, requestOptions);
+            if (releases.length === 0) {
+                throw new UnfazedNotFoundError(`unfazed: alias "${alias}" has no release history`);
+            }
+            const current = releases.find((r) => r.aliasHeld);
+            if (!current) {
+                throw new UnfazedNotFoundError(`unfazed: alias "${alias}" has no current release holding the alias`);
+            }
+            // The caller's precondition, checked before anything is sent. Failing
+            // here rather than at the server keeps a violated expectation from
+            // costing an alias swap, and reports the holder we actually observed.
+            if (expectedCurrentId !== undefined && current.id !== expectedCurrentId) {
+                throw new UnfazedConflictError(`unfazed: alias "${alias}" is held by ${current.id}, not the expected ` +
+                    `${expectedCurrentId} — it moved since you read it; re-read and decide again`, []);
+            }
+            // Pin the target on the first pass so a retry refreshes only the guard.
+            if (targetId === undefined) {
+                const previous = releases.find((r) => r.id !== current.id && r.status === "READY");
+                if (!previous) {
+                    throw new UnfazedNotFoundError(`unfazed: alias "${alias}" has no prior READY release to roll back to ` +
+                        `(history: ${releases.map((r) => `${r.id}:${r.status}`).join(", ")})`);
+                }
+                targetId = previous.id;
+            }
+            const target = releases.find((r) => r.id === targetId);
+            if (!target) {
+                throw new UnfazedNotFoundError(`unfazed: release ${targetId} is not in alias "${alias}"'s history ` +
+                    `(it may have been pruned; retention keeps only the most recent few)`);
+            }
+            if (target.id === current.id) {
+                throw new UnfazedConflictError(`unfazed: release ${targetId} already holds alias "${alias}"`, []);
+            }
+            if (target.status !== "READY") {
+                throw new UnfazedConflictError(`unfazed: release ${targetId} is ${target.status}, only READY releases can be restored`, []);
+            }
+            try {
+                const data = await this.client.mutate(ops.RollbackDocument, {
+                    deploymentID: target.id,
+                    expectedCurrentDeploymentID: current.id,
+                    expectedCurrentAliasRevision: current.aliasRevision,
+                }, requestOptions);
+                return data.rollbackDeployment;
+            }
+            catch (e) {
+                const retryable = e instanceof UnfazedGraphQLError && looksLikeCASConflict(e.errors) && attempt < retries;
+                if (!retryable) {
+                    if (e instanceof UnfazedGraphQLError && looksLikeCASConflict(e.errors)) {
+                        throw new UnfazedConflictError(`unfazed: rollback of "${alias}" lost the compare-and-swap after ${attempt + 1} attempt(s) — the alias is being deployed concurrently. ${e.message}`, e.errors);
+                    }
+                    throw e;
+                }
+                // Loop: re-list, rebuild the guard, keep the same target.
+            }
+        }
+    }
+    /* -------------------------------------------------------------- internals */
+    /**
+     * Finds a visible workspace by name, the way the server compares names.
+     *
+     * The server rejects duplicates with Go's `strings.EqualFold`, so matching
+     * must be case-insensitive here too or `ensureWorkspace` would try to create
+     * a "new" workspace the server considers a duplicate. An exact-case hit wins
+     * over a folded one, which only matters if a name ever slipped past the
+     * uniqueness check.
+     */
+    async #findWorkspaceByName(name, options) {
+        const workspaces = await this.listWorkspaces(options);
+        const folded = name.toLowerCase();
+        return (workspaces.find((w) => w.name === name) ??
+            workspaces.find((w) => w.name.toLowerCase() === folded));
+    }
+    async #writeBatch(workspaceId, batch, signal) {
+        const varDefs = ["$workspaceID: ID!"];
+        const fields = [];
+        const variables = { workspaceID: workspaceId };
+        batch.forEach((file, i) => {
+            variables[`p${i}`] = file.path;
+            variables[`c${i}`] = file.content;
+            varDefs.push(`$p${i}: String!`, `$c${i}: String!`);
+            fields.push(file.kind === "text"
+                ? `  f${i}: writeWorkspaceTextFile(input: { workspaceID: $workspaceID, path: $p${i}, text: $c${i} }) { file { ${FILE_SELECTION} } }`
+                : `  f${i}: writeWorkspaceBase64File(input: { workspaceID: $workspaceID, path: $p${i}, contentBase64: $c${i} }) { file { ${FILE_SELECTION} } }`);
+        });
+        // Built at runtime rather than codegen'd: the field COUNT varies per call,
+        // so no static document can express it. The field shapes are still fixed
+        // and typed below, and each individual mutation is codegen-validated by its
+        // single-file twin in operations.ts.
+        const document = `mutation SdkWriteFilesBatch(${varDefs.join(", ")}) {\n${fields.join("\n")}\n}`;
+        const data = await this.client.mutate(document, variables, signal ? { signal } : {});
+        return batch.map((_, i) => data[`f${i}`].file);
+    }
+}
+const FILE_SELECTION = "path sizeBytes size sha256 updatedAt";
+const ENV_SELECTION = "name value secret alias inherited masked updatedAt";
+function normalizeFile(path, content) {
+    if (typeof content === "string")
+        return { path, kind: "text", content };
+    if ("text" in content)
+        return { path, kind: "text", content: content.text };
+    if ("base64" in content)
+        return { path, kind: "base64", content: content.base64 };
+    return { path, kind: "base64", content: toBase64(content.bytes) };
+}
+function toBase64(input) {
+    const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+    // Node/Bun have Buffer; browsers and workers do not.
+    const maybeBuffer = globalThis
+        .Buffer;
+    if (maybeBuffer)
+        return maybeBuffer.from(bytes).toString("base64");
+    let binary = "";
+    const CHUNK = 0x8000; // avoid blowing the argument limit on large files
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+const utf8 = new TextEncoder();
+/**
+ * UTF-8 byte length, which is what the wire actually costs.
+ *
+ * `String.length` counts UTF-16 code units and undercounts by up to 3x on
+ * non-ASCII text — a CJK or emoji-heavy payload would sail past a budget it
+ * had already blown.
+ */
+function utf8Bytes(s) {
+    return utf8.encode(s).length;
+}
+/**
+ * Splits files into request-sized batches.
+ *
+ * Closes a batch on whichever limit trips first — count or bytes — but always
+ * emits at least one file per batch, so a single file larger than
+ * `maxBatchBytes` still gets sent (and fails loudly at the server's limit)
+ * rather than silently vanishing into an empty batch.
+ */
+function chunkFiles(files, batchSize, maxBatchBytes) {
+    const batches = [];
+    let current = [];
+    let bytes = 0;
+    for (const file of files) {
+        // Measured once per file, so the encode cost is linear in the payload the
+        // request was going to carry anyway.
+        const size = utf8Bytes(file.content) + utf8Bytes(file.path);
+        if (current.length > 0 && (current.length >= batchSize || bytes + size > maxBatchBytes)) {
+            batches.push(current);
+            current = [];
+            bytes = 0;
+        }
+        current.push(file);
+        bytes += size;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+//# sourceMappingURL=unfazed.js.map