unfazed 0.0.1 → 0.2.0

package/dist/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every GraphQL document the workflow layer sends.\n *\n * These are wrapped in `graphql(...)` so graphql-codegen validates them\n * against the vendored schema at codegen time and emits exact result/variable\n * types. A field that stops existing server-side turns into a compile error\n * here rather than a runtime surprise in an agent's script.\n *\n * The one document NOT defined here is the batched file write: it has a\n * variable number of aliased root fields, so it is assembled at runtime in\n * `unfazed.ts`. See the comment there.\n */\nimport { graphql } from \"./generated/gql.js\";\n\n/**\n * Deployment fields the SDK returns everywhere.\n *\n * `id` + `aliasRevision` + `aliasHeld` are the rollback compare-and-swap\n * triple; `previewUrl` is the immutable by-id URL you can verify BEFORE the\n * alias moves; `error` carries the build failure text when status is FAILED.\n */\nexport const DeploymentFieldsFragment = graphql(`\n  fragment DeploymentFields on Deployment {\n    id\n    workspaceID\n    kind\n    runtime\n    alias\n    serviceMode\n    healthPath\n    cronSchedule\n    cronPath\n    url\n    previewUrl\n    sshCommand\n    aliasHeld\n    aliasRevision\n    status\n    error\n    filesCount\n    sizeBytes\n    size\n    spaMode\n    gitRepo\n    gitCommit\n    createdAt\n  }\n`);\n\nexport const WhoamiDocument = graphql(`\n  query SdkWhoami {\n    whoami {\n      kind\n      userID\n      name\n      agentID\n      agentName\n      claimed\n      claimedBy\n      scopes\n      expiresAt\n      usage {\n        month\n        requests\n        limit\n      }\n      resources {\n        workspaces\n        workspaceLimit\n        services\n        serviceLimit\n      }\n    }\n  }\n`);\n\nexport const CreateWorkspaceDocument = graphql(`\n  mutation SdkCreateWorkspace($name: String!) {\n    createWorkspace(input: { name: $name }) {\n      workspace {\n        id\n        name\n        ownerId\n        projectId\n        createdAt\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const ListWorkspacesDocument = graphql(`\n  query SdkListWorkspaces {\n    workspaces {\n      id\n      name\n      ownerId\n      projectId\n      createdAt\n      updatedAt\n    }\n  }\n`);\n\n/**\n * Deleting a workspace, with the deployment cascade made explicit.\n *\n * `withDeployments` is not decoration: without it the server REFUSES while the\n * workspace has any deployment history at all — including FAILED records —\n * with `workspace %q still has deployments; delete them first`. A workspace\n * that was ever deployed is therefore undeletable through the bare mutation,\n * so the SDK always sends the flag and lets the caller choose the value.\n */\nexport const DeleteWorkspaceDocument = graphql(`\n  mutation SdkDeleteWorkspace($workspaceID: ID!, $withDeployments: Boolean) {\n    deleteWorkspace(input: { workspaceID: $workspaceID, withDeployments: $withDeployments }) {\n      ok\n    }\n  }\n`);\n\nexport const WriteTextFileDocument = graphql(`\n  mutation SdkWriteTextFile($workspaceID: ID!, $path: String!, $text: String!) {\n    writeWorkspaceTextFile(input: { workspaceID: $workspaceID, path: $path, text: $text }) {\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const WriteBase64FileDocument = graphql(`\n  mutation SdkWriteBase64File($workspaceID: ID!, $path: String!, $contentBase64: String!) {\n    writeWorkspaceBase64File(\n      input: { workspaceID: $workspaceID, path: $path, contentBase64: $contentBase64 }\n    ) {\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const ListFilesDocument = graphql(`\n  query SdkListFiles($input: ListWorkspaceFilesInput!) {\n    workspaceFilesPage(input: $input) {\n      items {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n      total\n      limit\n      offset\n      hasMore\n      nextOffset\n    }\n  }\n`);\n\nexport const ReadFileDocument = graphql(`\n  query SdkReadFile($input: ReadWorkspaceFileInput!) {\n    readWorkspaceFile(input: $input) {\n      text\n      offset\n      limit\n      totalBytes\n      truncated\n      nextOffset\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const DeleteFileDocument = graphql(`\n  mutation SdkDeleteFile($workspaceID: ID!, $path: String!) {\n    deleteWorkspaceFile(input: { workspaceID: $workspaceID, path: $path }) {\n      ok\n    }\n  }\n`);\n\nexport const CreateDeploymentDocument = graphql(`\n  mutation SdkCreateDeployment($input: CreateDeploymentInput!) {\n    createDeployment(input: $input) {\n      deployment {\n        ...DeploymentFields\n      }\n    }\n  }\n`);\n\nexport const DeployWorkspaceDocument = graphql(`\n  mutation SdkDeployWorkspace($input: DeployWorkspaceInput!) {\n    deployWorkspace(input: $input) {\n      deployment {\n        ...DeploymentFields\n      }\n    }\n  }\n`);\n\nexport const GetDeploymentDocument = graphql(`\n  query SdkGetDeployment($id: ID!) {\n    deployment(id: $id) {\n      ...DeploymentFields\n    }\n  }\n`);\n\n/**\n * The poll document, deliberately narrow.\n *\n * Waiting can run for minutes at a few seconds per tick; selecting the full\n * fragment every time would cost the server (and an agent's rate limit) far\n * more than the four fields the state machine actually reads.\n */\nexport const PollDeploymentDocument = graphql(`\n  query SdkPollDeployment($id: ID!) {\n    deployment(id: $id) {\n      id\n      status\n      error\n      aliasHeld\n      url\n      previewUrl\n    }\n  }\n`);\n\nexport const GetDeploymentByAliasDocument = graphql(`\n  query SdkGetDeploymentByAlias($alias: String!) {\n    deploymentByAlias(alias: $alias) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const ListDeploymentsDocument = graphql(`\n  query SdkListDeployments($input: ListDeploymentsInput) {\n    deploymentsPage(input: $input) {\n      items {\n        ...DeploymentFields\n      }\n      total\n      limit\n      offset\n      hasMore\n      nextOffset\n    }\n  }\n`);\n\nexport const ListReleasesDocument = graphql(`\n  query SdkListReleases($alias: String!) {\n    deploymentReleases(alias: $alias) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const RollbackDocument = graphql(`\n  mutation SdkRollback(\n    $deploymentID: ID!\n    $expectedCurrentDeploymentID: ID!\n    $expectedCurrentAliasRevision: String!\n  ) {\n    rollbackDeployment(\n      input: {\n        deploymentID: $deploymentID\n        expectedCurrentDeploymentID: $expectedCurrentDeploymentID\n        expectedCurrentAliasRevision: $expectedCurrentAliasRevision\n      }\n    ) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const ServiceStatusDocument = graphql(`\n  query SdkServiceStatus($deploymentID: ID!) {\n    serviceStatus(deploymentID: $deploymentID) {\n      deploymentID\n      alias\n      serviceMode\n      running\n      health\n      vmID\n      inFlight\n      alwaysOn\n      memSizeMiB\n      startedAt\n      lastUsedAt\n      lastStoppedAt\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const ServiceLogsDocument = graphql(`\n  query SdkServiceLogs($deploymentID: ID!, $tailBytes: Int) {\n    serviceLogs(deploymentID: $deploymentID, tailBytes: $tailBytes) {\n      deploymentID\n      stdout\n      stderr\n      truncated\n      stdoutBytes\n      stderrBytes\n      tailBytes\n    }\n  }\n`);\n\nexport const DeploymentEventsDocument = graphql(`\n  query SdkDeploymentEvents($deploymentID: ID!, $limit: Int) {\n    deploymentEvents(deploymentID: $deploymentID, limit: $limit) {\n      id\n      deploymentID\n      type\n      rawType\n      severity\n      message\n      vmID\n      createdAt\n    }\n  }\n`);\n\nexport const RestartServiceDocument = graphql(`\n  mutation SdkRestartService($deploymentID: ID!) {\n    restartService(input: { deploymentID: $deploymentID }) {\n      deploymentID\n      running\n      health\n      vmID\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const StopServiceDocument = graphql(`\n  mutation SdkStopService($deploymentID: ID!) {\n    stopService(input: { deploymentID: $deploymentID }) {\n      deploymentID\n      running\n      health\n      vmID\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const DeleteDeploymentDocument = graphql(`\n  mutation SdkDeleteDeployment($deploymentID: ID!) {\n    deleteDeployment(input: { deploymentID: $deploymentID }) {\n      ok\n    }\n  }\n`);\n\n/* -------------------------------------------------------------------------\n * Env & secrets\n *\n * Workspace-scoped values are SERVICE defaults for every app in the source;\n * app-scoped values override them for one alias. Both are snapshotted into a\n * release at deploy time, so a change only reaches a running app after a\n * redeploy — the workflow layer's doc comments repeat this where it matters.\n * ---------------------------------------------------------------------- */\n\nexport const SetWorkspaceEnvDocument = graphql(`\n  mutation SdkSetWorkspaceEnv($workspaceID: ID!, $name: String!, $value: String!) {\n    setWorkspaceEnv(input: { workspaceID: $workspaceID, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const SetWorkspaceSecretDocument = graphql(`\n  mutation SdkSetWorkspaceSecret($workspaceID: ID!, $name: String!, $value: String!) {\n    setWorkspaceSecret(input: { workspaceID: $workspaceID, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const DeleteWorkspaceEnvDocument = graphql(`\n  mutation SdkDeleteWorkspaceEnv($workspaceID: ID!, $name: String!) {\n    deleteWorkspaceEnv(input: { workspaceID: $workspaceID, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const ListWorkspaceEnvDocument = graphql(`\n  query SdkListWorkspaceEnv($workspaceID: ID!) {\n    workspaceEnv(workspaceID: $workspaceID) {\n      name\n      value\n      secret\n      alias\n      inherited\n      masked\n      updatedAt\n    }\n  }\n`);\n\nexport const SetAppEnvDocument = graphql(`\n  mutation SdkSetAppEnv($workspaceID: ID!, $alias: String!, $name: String!, $value: String!) {\n    setAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const SetAppSecretDocument = graphql(`\n  mutation SdkSetAppSecret($workspaceID: ID!, $alias: String!, $name: String!, $value: String!) {\n    setAppSecret(input: { workspaceID: $workspaceID, alias: $alias, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const RemoveAppEnvDocument = graphql(`\n  mutation SdkRemoveAppEnv($workspaceID: ID!, $alias: String!, $name: String!) {\n    removeAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const InheritAppEnvDocument = graphql(`\n  mutation SdkInheritAppEnv($workspaceID: ID!, $alias: String!, $name: String!) {\n    inheritAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const ListAppEnvDocument = graphql(`\n  query SdkListAppEnv($workspaceID: ID!, $alias: String!) {\n    appEnv(workspaceID: $workspaceID, alias: $alias) {\n      name\n      value\n      secret\n      alias\n      inherited\n      masked\n      updatedAt\n    }\n  }\n`);\n"]}

package/dist/unfazed.d.ts

@@ -0,0 +1,653 @@
+import { UnfazedClient, type ClientOptions, type RequestOptions } from "./client.js";
+import type { CreateDeploymentInput, DeploymentFieldsFragment, ListDeploymentsInput, ServiceMode, ServiceRuntime, SdkCreateWorkspaceMutation } from "./generated/graphql.js";
+import { type WaitOptions } from "./wait.js";
+/** A deployment as the workflow layer returns it. */
+export type Deployment = DeploymentFieldsFragment;
+/**
+ * A workspace as {@link Unfazed.createWorkspace} and
+ * {@link Unfazed.ensureWorkspace} return it.
+ *
+ * Derived from the generated mutation type rather than hand-written, so the
+ * two documents selecting these fields cannot drift apart without a compile
+ * error — which is exactly what makes `ensureWorkspace` able to return either
+ * a listed or a freshly created workspace under one type.
+ */
+export type Workspace = SdkCreateWorkspaceMutation["createWorkspace"]["workspace"];
+/** Options for {@link Unfazed.deleteWorkspace}. */
+export type DeleteWorkspaceOptions = {
+    /**
+     * Also delete every deployment snapshotted from the workspace, stopping
+     * their service VMs. **Defaults to `true`** — see the method docs for why.
+     */
+    withDeployments?: boolean;
+    /** Resolve `false` instead of throwing when the workspace is not visible. */
+    ignoreNotFound?: boolean;
+} & RequestOptions;
+/** Options for {@link Unfazed.deleteDeployment}. */
+export type DeleteDeploymentOptions = {
+    /** Resolve `false` instead of throwing when the deployment is not visible. */
+    ignoreNotFound?: boolean;
+} & RequestOptions;
+/** A file record returned by any write/list operation. */
+export interface WorkspaceFile {
+    path: string;
+    sizeBytes: number;
+    size: string;
+    sha256: string;
+    updatedAt: string;
+}
+/** One env var in a workspace- or app-scoped view. Secret values are never returned. */
+export interface EnvVar {
+    name: string;
+    value: string | null;
+    secret: boolean;
+    alias: string | null;
+    inherited: boolean;
+    masked: boolean;
+    updatedAt: string;
+}
+/**
+ * A file's contents for {@link Unfazed.writeFiles}.
+ *
+ * A bare string is text — the overwhelmingly common case, and what makes
+ * `{ "server.ts": code }` read well. Binary goes through `bytes` or `base64`,
+ * which route to `writeWorkspaceBase64File` instead.
+ */
+export type FileContent = string | {
+    text: string;
+} | {
+    base64: string;
+} | {
+    bytes: Uint8Array | ArrayBuffer;
+};
+/** Files keyed by workspace-relative path. */
+export type FilesMap = Record<string, FileContent>;
+export interface WriteFilesOptions {
+    /**
+     * Max files per GraphQL request. Default 20.
+     *
+     * The batch is one document with N aliased root fields; too many at once
+     * makes a single oversized request whose failure is all-or-nothing to
+     * diagnose. Twenty keeps a typical app to one or two round trips.
+     */
+    batchSize?: number;
+    /**
+     * Max total payload bytes per request. Default 4 MiB. Whichever limit trips
+     * first closes the batch, so one large file cannot blow the request up.
+     */
+    maxBatchBytes?: number;
+    signal?: AbortSignal;
+}
+/** Common options for the deploy helpers. */
+export interface DeployOptions {
+    workspaceId: string;
+    alias?: string;
+    /**
+     * Block until the deployment reaches a terminal status.
+     *
+     * `createDeployment` returns BUILDING immediately; the build, VM boot and
+     * health probe run in the background. With `wait: true` the call resolves
+     * only on READY and throws {@link UnfazedDeployError} on FAILED — which is
+     * what makes a one-script deploy possible.
+     */
+    wait?: boolean;
+    /** Backoff/timeout knobs used when `wait` is true. */
+    waitOptions?: WaitOptions;
+    signal?: AbortSignal;
+}
+export interface DeployServiceOptions extends DeployOptions {
+    /** Omit to auto-detect: a root go.mod+main.go is GO, otherwise BUN. */
+    runtime?: ServiceRuntime;
+    /** Omit for ON_DEMAND. Only set ALWAYS_ON to keep the VM warm. */
+    serviceMode?: ServiceMode;
+    healthPath?: string;
+    /** Standard 5-field cron spec. Prefer ON_DEMAND + cron over ALWAYS_ON. */
+    cronSchedule?: string;
+    /** Path the cron tick POSTs to. Defaults to /cron when cronSchedule is set. */
+    cronPath?: string;
+}
+export interface DeployStaticOptions extends DeployOptions {
+    /** Serve index.html for missing paths (single-page apps). */
+    spaMode?: boolean;
+}
+export interface DeployBoxOptions extends DeployOptions {
+    /** VM size. Omit for platform defaults (2048 MiB / 2 vCPU / 8 GiB disk). */
+    resources?: {
+        memMiB?: number;
+        vcpus?: number;
+        diskGiB?: number;
+    };
+}
+export interface RollbackOptions {
+    /** The alias to roll back. */
+    alias: string;
+    /**
+     * Release to restore. Omit to pick the most recent READY release that is not
+     * the current holder — i.e. "undo the last deploy".
+     */
+    to?: string;
+    /**
+     * Re-list-and-retry attempts when the compare-and-swap guard is rejected.
+     * Default 1. Each retry refreshes the guard from a fresh read; the TARGET
+     * release stays pinned, so a retry can never silently roll back to something
+     * other than what was chosen.
+     *
+     * Ignored when {@link expectedCurrentId} is set — see there.
+     */
+    retries?: number;
+    /**
+     * The release you believe currently holds the alias. When set, the rollback
+     * proceeds only if that is still true.
+     *
+     * This turns the rollback from "undo whatever is live now" into a checked
+     * operation: if the live holder is anything else, you get
+     * {@link UnfazedConflictError} BEFORE any mutation is sent, so a rollback
+     * script can never act on a world that moved since you inspected it.
+     *
+     * It also disables the CAS retry, necessarily: a rejected guard means the
+     * alias moved, and the alias having moved is precisely the precondition you
+     * asked to be enforced. Retrying would refresh the guard to the new holder
+     * and roll back the very deploy the precondition existed to protect.
+     */
+    expectedCurrentId?: string;
+    signal?: AbortSignal;
+}
+export interface UnfazedOptions extends ClientOptions {
+    /** Use an existing core client instead of constructing one. */
+    client?: UnfazedClient;
+}
+/**
+ * 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 declare class Unfazed {
+    #private;
+    /** The underlying typed GraphQL client. Use it for un-wrapped operations. */
+    readonly client: UnfazedClient;
+    constructor(options?: UnfazedOptions);
+    /** Who this token authenticates as, plus usage and resource limits. */
+    whoami(options?: RequestOptions): Promise<{
+        kind: import("./index.js").CurrentActorKind;
+        userID: string;
+        name: string;
+        agentID: string | null;
+        agentName: string | null;
+        claimed: boolean;
+        claimedBy: string | null;
+        scopes: Array<string>;
+        expiresAt: string | null;
+        usage: {
+            month: string;
+            requests: number;
+            limit: number;
+        } | null;
+        resources: {
+            workspaces: number;
+            workspaceLimit: number;
+            services: number;
+            serviceLimit: number;
+        } | null;
+    }>;
+    /** Creates a source workspace — the container for files, env and deployments. */
+    createWorkspace(name: string, options?: RequestOptions): Promise<{
+        id: string;
+        name: string;
+        ownerId: string;
+        projectId: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Workspaces visible to this token. */
+    listWorkspaces(options?: RequestOptions): Promise<{
+        id: string;
+        name: string;
+        ownerId: string;
+        projectId: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }[]>;
+    /**
+     * 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.
+     */
+    deleteWorkspace(workspaceId: string, options?: DeleteWorkspaceOptions): Promise<boolean>;
+    /**
+     * 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.
+     */
+    ensureWorkspace(name: string, options?: RequestOptions): Promise<{
+        id: string;
+        name: string;
+        ownerId: string;
+        projectId: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /**
+     * 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.
+     */
+    writeFiles(workspaceId: string, files: FilesMap, options?: WriteFilesOptions): Promise<WorkspaceFile[]>;
+    /** Writes one text file. Prefer {@link writeFiles} for more than one. */
+    writeFile(workspaceId: string, path: string, text: string, options?: RequestOptions): Promise<WorkspaceFile>;
+    /** Writes one binary file. Accepts raw bytes or a base64 string. */
+    writeBinaryFile(workspaceId: string, path: string, content: Uint8Array | ArrayBuffer | {
+        base64: string;
+    }, options?: RequestOptions): Promise<WorkspaceFile>;
+    /** Lists workspace files (paginated). */
+    listFiles(workspaceId: string, input?: {
+        limit?: number;
+        offset?: number;
+        order?: string;
+    }, options?: RequestOptions): Promise<{
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+        nextOffset: number | null;
+        items: Array<{
+            path: string;
+            sizeBytes: number;
+            size: string;
+            sha256: string;
+            updatedAt: string;
+        }>;
+    }>;
+    /** Reads a text file, optionally a byte range of it. Null when absent. */
+    readFile(workspaceId: string, path: string, input?: {
+        offset?: number;
+        limit?: number;
+    }, options?: RequestOptions): Promise<{
+        text: string;
+        offset: number;
+        limit: number;
+        totalBytes: number;
+        truncated: boolean;
+        nextOffset: number | null;
+        file: {
+            path: string;
+            sizeBytes: number;
+            size: string;
+            sha256: string;
+            updatedAt: string;
+        };
+    } | null>;
+    /**
+     * 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}.
+     */
+    deleteFile(workspaceId: string, path: string, options?: RequestOptions): Promise<boolean>;
+    /**
+     * 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: DeployServiceOptions): Promise<Deployment>;
+    /** Deploys the workspace as a STATIC site. */
+    deployStatic(options: DeployStaticOptions): Promise<Deployment>;
+    /**
+     * 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: DeployBoxOptions): Promise<Deployment>;
+    /** Escape hatch: deploy with a raw CreateDeploymentInput. */
+    deploy(input: CreateDeploymentInput, options?: Omit<DeployOptions, "workspaceId">): Promise<Deployment>;
+    /**
+     * 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`.
+     */
+    waitForDeployment(deploymentId: string, waitOptions?: WaitOptions): Promise<Deployment>;
+    /** Reads one deployment by id. Null when absent. */
+    getDeployment(deploymentId: string, options?: RequestOptions): Promise<Deployment | null>;
+    /** Reads the deployment currently serving an alias. Null when absent. */
+    getDeploymentByAlias(alias: string, options?: RequestOptions): Promise<Deployment | null>;
+    /** Lists deployments (paginated, filterable by kind/alias/workspace). */
+    listDeployments(input?: ListDeploymentsInput, options?: RequestOptions): Promise<{
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+        nextOffset: number | null;
+        items: Array<{
+            id: string;
+            workspaceID: string;
+            kind: import("./index.js").DeploymentKind;
+            runtime: ServiceRuntime | null;
+            alias: string | null;
+            serviceMode: ServiceMode;
+            healthPath: string | null;
+            cronSchedule: string | null;
+            cronPath: string | null;
+            url: string;
+            previewUrl: string;
+            sshCommand: string | null;
+            aliasHeld: boolean;
+            aliasRevision: string;
+            status: import("./index.js").DeploymentStatus;
+            error: string | null;
+            filesCount: number;
+            sizeBytes: number;
+            size: string;
+            spaMode: boolean;
+            gitRepo: string | null;
+            gitCommit: string | null;
+            createdAt: string;
+        }>;
+    }>;
+    /** Live VM status: health, in-flight requests, restarts, RAM ceiling. */
+    getStatus(deploymentId: string, options?: RequestOptions): Promise<{
+        deploymentID: string;
+        alias: string | null;
+        serviceMode: ServiceMode;
+        running: boolean;
+        health: string;
+        vmID: string | null;
+        inFlight: number;
+        alwaysOn: boolean;
+        memSizeMiB: number;
+        startedAt: string | null;
+        lastUsedAt: string | null;
+        lastStoppedAt: string | null;
+        restartCount: number;
+        lastError: string | null;
+    }>;
+    /**
+     * 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.
+     */
+    getLogs(deploymentId: string, input?: {
+        tailBytes?: number;
+    }, options?: RequestOptions): Promise<{
+        deploymentID: string;
+        stdout: string;
+        stderr: string;
+        truncated: boolean;
+        stdoutBytes: number;
+        stderrBytes: number;
+        tailBytes: number;
+    }>;
+    /** Deployment lifecycle events — build, boot, probe, cron, restarts. */
+    getEvents(deploymentId: string, limit?: number, options?: RequestOptions): Promise<{
+        id: string;
+        deploymentID: string;
+        type: import("./index.js").DeploymentEventType;
+        rawType: string;
+        severity: import("./index.js").DeploymentEventSeverity;
+        message: string;
+        vmID: string | null;
+        createdAt: string;
+    }[]>;
+    /** Restarts a service's VM. */
+    restartService(deploymentId: string, options?: RequestOptions): Promise<{
+        deploymentID: string;
+        running: boolean;
+        health: string;
+        vmID: string | null;
+        restartCount: number;
+        lastError: string | null;
+    }>;
+    /** Stops a service's VM. An on-demand service cold-starts again on request. */
+    stopService(deploymentId: string, options?: RequestOptions): Promise<{
+        deploymentID: string;
+        running: boolean;
+        health: string;
+        vmID: string | null;
+        restartCount: number;
+        lastError: string | null;
+    }>;
+    /**
+     * 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.
+     */
+    deleteDeployment(deploymentId: string, options?: DeleteDeploymentOptions): Promise<boolean>;
+    /**
+     * 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.
+     */
+    setEnv(workspaceId: string, name: string, value: string, options?: RequestOptions): Promise<EnvVar>;
+    /**
+     * 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.
+     */
+    setSecret(workspaceId: string, name: string, value: string, options?: RequestOptions): Promise<EnvVar>;
+    /**
+     * 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.
+     */
+    setEnvMany(workspaceId: string, vars: Record<string, string>, options?: {
+        secret?: boolean;
+        signal?: AbortSignal;
+    }): Promise<EnvVar[]>;
+    /**
+     * 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.
+     */
+    deleteEnv(workspaceId: string, name: string, options?: RequestOptions): Promise<boolean>;
+    /** Workspace-default env vars. Secret values are redacted. */
+    listEnv(workspaceId: string, options?: RequestOptions): Promise<EnvVar[]>;
+    /**
+     * 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.
+     */
+    setAppEnv(workspaceId: string, alias: string, name: string, value: string, options?: RequestOptions): Promise<EnvVar>;
+    /**
+     * 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.
+     */
+    setAppSecret(workspaceId: string, alias: string, name: string, value: string, options?: RequestOptions): Promise<EnvVar>;
+    /**
+     * 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.
+     */
+    removeAppEnv(workspaceId: string, alias: string, name: string, options?: RequestOptions): Promise<boolean>;
+    /**
+     * 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}.
+     */
+    inheritAppEnv(workspaceId: string, alias: string, name: string, options?: RequestOptions): Promise<boolean>;
+    /** The effective env view for one alias: overrides, inherited and masked. */
+    listAppEnv(workspaceId: string, alias: string, options?: RequestOptions): Promise<EnvVar[]>;
+    /**
+     * 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.
+     */
+    listReleases(alias: string, options?: RequestOptions): Promise<Deployment[]>;
+    /**
+     * 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.
+     */
+    rollback(options: RollbackOptions): Promise<Deployment>;
+}