unfazed 0.1.0 → 0.2.0

package/dist/unfazed.js

@@ -1,5 +1,5 @@
 import { UnfazedClient } from "./client.js";
-import { UnfazedConflictError, UnfazedDeployError, UnfazedGraphQLError, UnfazedNotFoundError, looksLikeCASConflict, } from "./errors.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";
 /**
@@ -46,10 +46,77 @@ export 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.
      */
-    async deleteWorkspace(workspaceId, options) {
-        const data = await this.client.mutate(ops.DeleteWorkspaceDocument, { workspaceID: workspaceId }, options);
-        return data.deleteWorkspace.ok;
+    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 */
     /**
@@ -106,17 +173,36 @@ export class Unfazed {
         const data = await this.client.query(ops.ReadFileDocument, { input: { workspaceID: workspaceId, path, ...input } }, options);
         return data.readWorkspaceFile;
     }
-    /** 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}.
+     */
     async deleteFile(workspaceId, path, options) {
         const data = await this.client.mutate(ops.DeleteFileDocument, { workspaceID: workspaceId, path }, options);
         return data.deleteWorkspaceFile.ok;
     }
-    /* ----------------------------------------------------------------- deploys */
+    /* ----------------------------------------------------------------- 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;
@@ -145,6 +231,25 @@ export 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) {
         const { workspaceId, alias, resources } = options;
@@ -250,10 +355,23 @@ export class Unfazed {
         const data = await this.client.mutate(ops.StopServiceDocument, { deploymentID: deploymentId }, options);
         return data.stopService;
     }
-    /** Deletes a deployment. */
-    async deleteDeployment(deploymentId, options) {
-        const data = await this.client.mutate(ops.DeleteDeploymentDocument, { deploymentID: deploymentId }, options);
-        return data.deleteDeployment.ok;
+    /**
+     * 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
      *
@@ -262,12 +380,25 @@ export class Unfazed {
      * 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. */
+    /**
+     * 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. */
+    /**
+     * 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;
@@ -277,6 +408,16 @@ export class Unfazed {
      * 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);
@@ -296,7 +437,16 @@ export class Unfazed {
         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. */
+    /**
+     * 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;
@@ -306,12 +456,24 @@ export class Unfazed {
         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. */
+    /**
+     * 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. */
+    /**
+     * 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;
@@ -320,12 +482,36 @@ export class Unfazed {
      * 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. */
+    /**
+     * 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;
@@ -365,11 +551,31 @@ export 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.
      */
     async rollback(options) {
-        const { alias, signal } = options;
-        const retries = options.retries ?? 1;
+        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++) {
@@ -381,6 +587,13 @@ export class Unfazed {
             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");
@@ -422,6 +635,21 @@ export class Unfazed {
         }
     }
     /* -------------------------------------------------------------- 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 = [];