unfazed 0.1.0 → 0.2.0

package/dist/unfazed.d.ts

@@ -1,8 +1,33 @@
 import { UnfazedClient, type ClientOptions, type RequestOptions } from "./client.js";
-import type { CreateDeploymentInput, DeploymentFieldsFragment, ListDeploymentsInput, ServiceMode, ServiceRuntime } from "./generated/graphql.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;
@@ -106,8 +131,25 @@ export interface RollbackOptions {
      * 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 {
@@ -180,8 +222,55 @@ export declare class Unfazed {
     /**
      * 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?: RequestOptions): Promise<boolean>;
+    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.
      *
@@ -248,13 +337,22 @@ export declare class Unfazed {
             updatedAt: string;
         };
     } | null>;
-    /** Deletes a workspace file. */
+    /**
+     * 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. */
@@ -263,6 +361,25 @@ export declare class Unfazed {
      * 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. */
@@ -379,37 +496,111 @@ export declare class Unfazed {
         restartCount: number;
         lastError: string | null;
     }>;
-    /** Deletes a deployment. */
-    deleteDeployment(deploymentId: string, options?: RequestOptions): Promise<boolean>;
-    /** Sets a workspace-default env var. Redeploy the alias to apply it. */
+    /**
+     * 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. */
+    /**
+     * 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. */
+    /**
+     * 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. */
+    /**
+     * 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. */
+    /**
+     * 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. */
+    /**
+     * 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[]>;
@@ -439,7 +630,24 @@ export declare class Unfazed {
      * ```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>;
 }