unfazed 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jilio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,388 @@
 # unfazed
 
-Placeholder package. This name is reserved and the package is under active development — nothing usable is published yet.
+Official TypeScript SDK for [unfazed](https://unfazed.dev) — deploy and operate
+agent-built apps (static sites, HTTP services, persistent Linux boxes) in
+isolated microVMs.
+
+**This is the code-mode companion to the unfazed MCP server.** Same platform,
+same bearer token, different shape. Use the MCP tools when you want the model to
+decide one step at a time. Use this SDK when you'd rather write one script that
+does the whole chain and only reports back what matters.
+
+```
+MCP:  create_workspace → write_file → write_file → write_file → deploy
+      → list_deployments → list_deployments → list_deployments → get_logs
+      (9+ round trips, every result lands in the model's context)
+
+SDK:  one script. Three requests. You read the four lines you cared about.
+```
+
+- Zero runtime dependencies. Installing `unfazed` installs exactly one package.
+- Strict TypeScript, generated from the platform's own GraphQL schema.
+- Bun-first, runs unchanged on Node >= 20 and Deno.
+
+## Install
+
+```sh
+bun add unfazed     # or: npm i unfazed
+```
+
+## Auth
+
+Get a token from <https://unfazed.dev/auth.md> (or `POST
+https://unfazed.dev/agents/register`). The SDK reads `UNFZ_API_TOKEN`:
+
+```sh
+export UNFZ_API_TOKEN="..."
+```
+
+```ts
+const unfazed = new Unfazed();                       // reads UNFZ_API_TOKEN
+const unfazed = new Unfazed({ token });              // or pass it explicitly
+```
+
+Both endpoint and token are configurable. `UNFZ_API_URL` overrides the endpoint
+(default `https://unfazed.dev/query`); `baseUrl` is a convenience for
+self-hosted control planes where only the host differs.
+
+```ts
+new Unfazed({ token, baseUrl: "https://staging.example.com" });   // → /query
+new Unfazed({ token, endpoint: "https://example.com/graphql" });  // exact
+```
+
+## Code mode: deploy, wait, tail logs, in one script
+
+```ts
+#!/usr/bin/env bun
+import { Unfazed, UnfazedDeployError } from "unfazed";
+
+const unfazed = new Unfazed();
+
+const ws = await unfazed.createWorkspace("greeter");
+
+// One request, not three — batched as aliased mutations.
+await unfazed.writeFiles(ws.id, {
+  "server.ts": `
+    export default {
+      fetch(req: Request) {
+        const name = new URL(req.url).searchParams.get("name") ?? "world";
+        return Response.json({ hello: name });
+      },
+    };
+  `,
+  "unfazed.json": JSON.stringify({ entry: "server.ts" }),
+  "README.md": "# greeter",
+});
+
+try {
+  // Blocks until the build, VM boot and health probe all pass.
+  const app = await unfazed.deployService({
+    workspaceId: ws.id,
+    alias: "greeter",
+    wait: true,
+  });
+  console.log(`live: ${app.url}`);
+
+  // Verify it for real before trusting the alias.
+  const res = await fetch(`${app.url}?name=agent`);
+  console.log(res.status, await res.json());
+
+  // Filter logs LOCALLY. This is the whole point: a 16 KiB tail costs the
+  // model nothing, because only the matching lines are ever printed.
+  const logs = await unfazed.getLogs(app.id, { tailBytes: 16384 });
+  const errors = logs.stdout
+    .split("\n")
+    .filter((l) => /error|warn/i.test(l))
+    .slice(-20);
+  console.log(errors.length ? errors.join("\n") : "no errors in tail");
+} catch (e) {
+  if (e instanceof UnfazedDeployError && e.reason === "FAILED") {
+    // The build finished and is broken — retrying will not help.
+    console.error("build failed:", e.message);
+    process.exit(1);
+  }
+  throw e;
+}
+```
+
+## Two layers
+
+### 1. Typed GraphQL core — `UnfazedClient`
+
+A fetch-based transport with full types and nothing else. Use it for any of the
+platform's ~660 schema fields the workflow layer doesn't wrap.
+
+```ts
+import { UnfazedClient, operations } from "unfazed";
+
+const client = new UnfazedClient();
+
+// Generated documents infer both result and variable types.
+const { whoami } = await client.query(operations.WhoamiDocument, {});
+
+// Or your own document, with explicit types.
+const data = await client.query<{ workspaces: { id: string }[] }, never>(
+  `query { workspaces { id } }`,
+);
+```
+
+Errors are typed and specific: `UnfazedAuthError`, `UnfazedHTTPError` (carries
+`status`/`body`), `UnfazedGraphQLError` (carries `errors` **and any partial
+`data`**), `UnfazedTimeoutError`, `UnfazedDeployError`, `UnfazedConflictError`,
+`UnfazedNotFoundError`. All extend `UnfazedError`.
+
+### 2. Workflow layer — `Unfazed`
+
+The chains an agent actually performs. Reach `client` from it any time:
+`unfazed.client.query(...)`.
+
+**Identity**
+| Method | Notes |
+| --- | --- |
+| `whoami()` | actor kind, scopes, usage and resource limits |
+
+**Workspaces**
+| Method | Notes |
+| --- | --- |
+| `createWorkspace(name)` | names are unique per owner, case-insensitively |
+| `ensureWorkspace(name)` | get-or-create; **use this in re-runnable scripts** |
+| `listWorkspaces()` | |
+| `deleteWorkspace(id, opts?)` | cascades to deployments by default; also destroys a BOX's data disk |
+
+**Files**
+| Method | Notes |
+| --- | --- |
+| `writeFiles(wsId, files, opts?)` | **batched** — many files per request |
+| `writeFile(wsId, path, text)` | |
+| `writeBinaryFile(wsId, path, bytes)` | base64 under the hood |
+| `listFiles(wsId, page?)` | |
+| `readFile(wsId, path, range?)` | |
+| `deleteFile(wsId, path)` | |
+
+**Deploy**
+| Method | Notes |
+| --- | --- |
+| `deployService(opts)` | `wait: true` polls to READY |
+| `deployStatic(opts)` | `spaMode` for single-page apps |
+| `deployBox(opts)` | persistent Linux VM; result carries `sshCommand` |
+| `deploy(input, opts?)` | raw `CreateDeploymentInput` escape hatch |
+| `waitForDeployment(id, opts?)` | standalone poller |
+| `getDeployment(id)` / `getDeploymentByAlias(alias)` | |
+| `listDeployments(filter?)` | |
+
+**Runtime**
+| Method | Notes |
+| --- | --- |
+| `getLogs(id, { tailBytes })` | stdout + stderr tail |
+| `getStatus(id)` | health, in-flight, restarts, `memSizeMiB` |
+| `getEvents(id, limit?)` | build/boot/probe/cron lifecycle events |
+| `restartService(id)` / `stopService(id)` | |
+| `deleteDeployment(id, opts?)` | `ignoreNotFound` for idempotent cleanup |
+
+**Env & secrets**
+| Method | Notes |
+| --- | --- |
+| `setEnv` / `setSecret` / `deleteEnv` / `listEnv` | workspace-wide defaults |
+| `setEnvMany(wsId, vars, { secret? })` | **batched**, and **not atomic** |
+| `setAppEnv` / `setAppSecret` | one alias only |
+| `removeAppEnv` (mask) / `inheritAppEnv` (unmask) | a mask is a persistent row, and costs a slot |
+| `listAppEnv(wsId, alias)` | effective view; secrets redacted |
+
+**Releases**
+| Method | Notes |
+| --- | --- |
+| `listReleases(alias)` | newest first; one entry has `aliasHeld: true` |
+| `rollback({ alias, to?, expectedCurrentId?, retries? })` | **whole compare-and-swap in one call** |
+
+## The two things worth knowing
+
+### `writeFiles` batches, because the API is one-file-per-mutation
+
+Writing a 12-file app the obvious way costs 12 round trips. `writeFiles` puts
+one **aliased** mutation per file into a single GraphQL document:
+
+```graphql
+mutation SdkWriteFilesBatch($workspaceID: ID!, $p0: String!, $c0: String!, ...) {
+  f0: writeWorkspaceTextFile(input: { workspaceID: $workspaceID, path: $p0, text: $c0 }) { file { ... } }
+  f1: writeWorkspaceBase64File(input: { workspaceID: $workspaceID, path: $p1, contentBase64: $c1 }) { file { ... } }
+}
+```
+
+Text and binary mix freely in one batch. It splits automatically at 20 files or
+4 MiB per request (`batchSize`, `maxBatchBytes`).
+
+Batches are **not atomic** — GraphQL resolves each field independently. If one
+path fails, the others still commit; the thrown `UnfazedGraphQLError` carries
+`data` with the aliases that succeeded and `errors[].path` naming the ones that
+didn't.
+
+### `rollback` does the compare-and-swap for you
+
+The platform requires you to prove you observed the current state: you must send
+the live release's id **and** its opaque `aliasRevision`, and the swap is
+rejected if either moved — including same-id ABA. That's a read-then-write
+protocol, and getting it wrong means racing a concurrent deploy.
+
+`rollback` does the whole thing in one call: list releases → find the `aliasHeld`
+entry → pick the target → submit both guard values.
+
+```ts
+await unfazed.rollback({ alias: "my-app" });             // undo the last deploy
+await unfazed.rollback({ alias: "my-app", to: relId });  // a specific release
+```
+
+If the guard is rejected it re-lists and retries once (`retries`). The **target
+stays pinned** across retries while the guard is refreshed — a concurrent deploy
+can never redirect your rollback to a release you didn't choose. Non-READY
+targets and the current holder are refused client-side, before the mutation.
+
+> ⚠️ **A bare `rollback({ alias })` is a toggle, not an idempotent step.** It
+> means "restore the most recent READY release that isn't live", 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, every hop a real alias
+> swap, nothing ever erroring — each call did exactly what it was asked.
+
+In anything re-runnable — a retry loop, a CI job, an agent redoing a step — pin
+the outcome instead of asking for "the previous one":
+
+```ts
+// Names the release you want live. A second run refuses instead of flipping.
+await unfazed.rollback({ alias: "my-app", to: relId });
+
+// States what you expect to be live NOW. If anything else holds the alias you
+// get UnfazedConflictError before a single mutation goes out — and the CAS
+// retry is disabled, because a moved alias IS the precondition failing.
+await unfazed.rollback({ alias: "my-app", to: relId, expectedCurrentId: liveId });
+```
+
+## Deploy semantics the SDK can't hide
+
+- `createDeployment` returns **`BUILDING`** immediately. `READY` and `FAILED`
+  are the only terminal states. `wait: true` exists because of this.
+- `previewUrl` is the immutable by-id URL. It 503s (with `Retry-After`) while
+  building and 422s with the build error on failure — use it to verify a build
+  before it owns the public alias.
+- Env and secrets are **snapshotted into a release at deploy time**. Changing
+  them does not affect a running app until you redeploy that alias. Old releases
+  are immutable, and STATIC deployments get no env at all.
+- Release retention keeps only the most recent few per alias (default 5). Older
+  releases can't be inspected or restored.
+- **Every deploy call mints a new release. There is no content dedupe** —
+  deploying byte-identical files twice gives you two distinct releases. A retry
+  loop churns the history and can push a release you still wanted out of
+  retention.
+- **`deployBox` without an `alias` creates a NEW box every call.** The server
+  generates a fresh random alias, so a script run twice leaves two box records —
+  while the data disk is keyed by **workspace**, shared by all of them. Only one
+  VM can hold that disk read-write, so the second box won't even start. Always
+  pass an explicit `alias` in a re-runnable script.
+
+## Things that are re-runnable, and things that aren't
+
+Agents re-run scripts. These are the operations where the second run does not do
+what the first one did:
+
+| Instead of | Use | Because |
+| --- | --- | --- |
+| `createWorkspace(name)` | `ensureWorkspace(name)` | names are unique per owner, case-insensitively — a second create is an error |
+| `deployBox({ workspaceId })` | `deployBox({ workspaceId, alias })` | no alias ⇒ a brand-new box each time |
+| `rollback({ alias })` | `rollback({ alias, to })` or `expectedCurrentId` | bare rollback is a toggle |
+| `deleteWorkspace(id)` throwing | `deleteWorkspace(id, { ignoreNotFound: true })` | already-deleted is not a failure |
+| `deleteDeployment(id)` throwing | `deleteDeployment(id, { ignoreNotFound: true })` | same |
+
+`ignoreNotFound` matches the server's two exact sentinels — `workspace was not
+found` and `deployment was not found` — and nothing else. A message that merely
+*contains* "not found" still throws, so a real failure can't be mistaken for a
+successful teardown. (Both sentinels also cover "belongs to another tenant": the
+server reports the two identically so ids can't be probed.)
+
+### Deleting a workspace cascades by default
+
+`deleteWorkspace` sends `withDeployments: true` unless you say otherwise. It has
+to: the server **refuses** to delete a workspace with any deployment history at
+all — including FAILED-only history — without that flag, so the strict form
+fails on nearly every workspace that was ever deployed.
+
+```ts
+await unfazed.deleteWorkspace(ws.id);                             // cascade (default)
+await unfazed.deleteWorkspace(ws.id, { withDeployments: false }); // refuse if deployed
+```
+
+## Env & secrets: three states, not two
+
+A name in a given scope is exactly one of **plain**, **secret**, or **masked**,
+and the setters silently move it between them:
+
+- `setEnv` deletes a same-named secret; `setSecret` deletes a same-named plain
+  var. Same for `setAppEnv` / `setAppSecret`. Last write wins and the *kind*
+  flips with it.
+- `setAppEnv` / `setAppSecret` also clear a REMOVE mask — setting a value is how
+  you un-block a masked name.
+- `removeAppEnv` writes a **persistent mask row**, even when nothing was
+  inherited to mask. It keeps blocking the name if a workspace default appears
+  later. `inheritAppEnv` clears it.
+- Masks **cost a slot**. A workspace has 128 env entries total — shared across
+  the workspace defaults *and* every app scope combined, not 128 each — and
+  masks count like values do.
+
+`ok: false` from `deleteEnv`, `deleteFile`, `inheritAppEnv`, or a second
+`removeAppEnv` is **not a failure**. It means "nothing to do — already in the
+state you asked for". Real failures throw. So idempotent cleanup is just
+ignoring the boolean.
+
+`setEnvMany` batches like `writeFiles`, and is **not atomic** for the same
+reason: a rejected name leaves the ones before it committed, with the successful
+aliases in the thrown error's `data`.
+
+## Development
+
+```sh
+bun install
+bun run codegen      # regenerate typed operations from the vendored schema
+bun run typecheck
+bun test
+bun run build
+bun run check        # all of the above, plus a dist smoke test on Bun AND Node
+```
+
+### Regenerating from the schema
+
+`schema/schema.graphqls` is a **vendored copy** of `graph/schema.graphqls` from
+the [unfazed](https://unfazed.dev) repo — the same contract gqlgen serves. It is
+vendored so `bun install && bun run build` works with no access to the platform
+repo, and `schema/SOURCE.json` records the exact unfazed commit it came from.
+
+To refresh it against a local unfazed checkout:
+
+```sh
+bun run sync-schema                              # tries ../../../unfazed, then $UNFAZED_REPO
+UNFAZED_REPO=~/src/unfazed bun run sync-schema
+bun run sync-schema -- --repo ~/src/unfazed
+bun run sync-schema -- --check                   # verify only; non-zero if stale
+
+bun run codegen && bun test                      # ALWAYS follow a sync with these
+```
+
+`src/generated/` is committed on purpose: consumers of the published package
+never run codegen, and neither does a clean CI checkout. A schema change that
+invalidates an operation shows up as a **compile error**, not a runtime
+surprise.
+
+`bun run codegen` also runs `scripts/postcodegen.ts`, which inlines the one
+type-only import graphql-codegen emits (`DocumentTypeDecoration`) so the package
+keeps zero dependencies. `test/generated.test.ts` asserts that invariant.
+
+## Publishing
+
+Publishing is a deliberate, attended step — there is intentionally **no**
+`prepublishOnly`/`prepare` script that could fire a publish or a stale build by
+accident. `dist/` is gitignored, so build before publishing:
+
+```sh
+bun run check          # typecheck + tests + build + dist smoke
+npm publish            # or: bun publish --access public
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,134 @@
+/** SDK version, sent as the User-Agent. Keep in sync with package.json. */
+export declare const VERSION = "0.2.0";
+/**
+ * Default GraphQL endpoint.
+ *
+ * Note this is the FULL endpoint, not an origin: the platform's own documented
+ * convention (`UNFZ_API_URL="https://unfazed.dev/query"`, and cmd/showcase-deploy
+ * in the unfazed repo) treats the /query URL as the configurable unit, so the
+ * SDK matches it rather than inventing a base-URL convention.
+ */
+export declare const DEFAULT_ENDPOINT = "https://unfazed.dev/query";
+/** Platform origin, used to derive the endpoint when only `baseUrl` is given. */
+export declare const DEFAULT_BASE_URL = "https://unfazed.dev";
+/** Path of the GraphQL endpoint under an origin. */
+export declare const GRAPHQL_PATH = "/query";
+/**
+ * Environment variable holding the bearer token.
+ *
+ * This is the platform's documented name (docs/agent-deployments.md,
+ * internal/agentdocs/reference.md). It accepts either an operator API token or
+ * an agent access token from POST /agents/register — /query takes both as
+ * plain bearers.
+ */
+export declare const TOKEN_ENV_VAR = "UNFZ_API_TOKEN";
+/** Environment variable holding the full GraphQL endpoint URL. */
+export declare const ENDPOINT_ENV_VAR = "UNFZ_API_URL";
+/** Minimal structural type of the `fetch` the transport needs. */
+export type FetchLike = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+export interface ClientOptions {
+    /**
+     * Bearer token. Falls back to `UNFZ_API_TOKEN`. Get one from
+     * https://unfazed.dev/auth.md — the same token the MCP server uses.
+     */
+    token?: string;
+    /**
+     * Full GraphQL endpoint URL. Wins over `baseUrl`. Falls back to
+     * `UNFZ_API_URL`, then {@link DEFAULT_ENDPOINT}.
+     */
+    endpoint?: string;
+    /**
+     * Platform origin; `/query` is appended. Convenience for self-hosted or
+     * staging control planes where only the host differs.
+     */
+    baseUrl?: string;
+    /** Extra headers merged into every request. Authorization always wins. */
+    headers?: Record<string, string>;
+    /**
+     * Per-request timeout in ms. Default 60_000. Pass 0 to disable.
+     *
+     * Bounds the WHOLE request — connect, headers and reading the response body —
+     * so a proxy that answers with headers and then stalls still fails on time.
+     */
+    timeoutMs?: number;
+    /** Injection point for tests and instrumented/proxied transports. */
+    fetch?: FetchLike;
+    /** Overrides the default `unfazed-sdk/<version>` User-Agent. */
+    userAgent?: string;
+}
+/**
+ * A GraphQL document.
+ *
+ * Structural rather than `string & {...}` on purpose: graphql-codegen emits
+ * `TypedDocumentString`, a String SUBCLASS, which is not assignable to the
+ * primitive `string`. Requiring only `toString()` plus the optional phantom
+ * `__apiType` lets three things through with full inference:
+ *
+ *  - generated `TypedDocumentString` documents (types inferred),
+ *  - documents assembled at runtime, like the batched writeFiles mutation,
+ *  - plain template-literal strings a caller wrote by hand.
+ */
+export interface GraphQLDocument<TResult, TVariables> {
+    /** Phantom type carrier. Never called; present only to bind the generics. */
+    __apiType?: (variables: TVariables) => TResult;
+    toString(): string;
+}
+/** Result type carried by a typed document. */
+export type ResultOf<T> = T extends GraphQLDocument<infer R, infer _V> ? R : unknown;
+/** Variables type carried by a typed document. */
+export type VariablesOf<T> = T extends GraphQLDocument<infer _R, infer V> ? V : never;
+/** Per-request knobs. */
+export interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    operationName?: string;
+}
+/**
+ * Layer 1 — a typed, dependency-free GraphQL transport over `fetch`.
+ *
+ * This is the SDK's entire networking surface. It understands auth, timeouts
+ * and the GraphQL error envelope, and nothing about deployments. The workflow
+ * layer ({@link import("./unfazed.js").Unfazed}) is built strictly on top of
+ * it, so you can always drop down here for any operation the workflow layer
+ * does not wrap — the schema has ~660 fields and the workflow layer
+ * deliberately covers only the agent-facing ones.
+ *
+ * ```ts
+ * const client = new UnfazedClient();               // reads UNFZ_API_TOKEN
+ * const data = await client.query<{ whoami: { name: string } }, never>(
+ *   `query { whoami { name } }`,
+ * );
+ * ```
+ */
+export declare class UnfazedClient {
+    #private;
+    /** Resolved GraphQL endpoint URL. */
+    readonly endpoint: string;
+    constructor(options?: ClientOptions);
+    /** Runs a query document. Identical wire behaviour to {@link mutate}. */
+    query<TResult, TVariables>(document: GraphQLDocument<TResult, TVariables>, variables?: TVariables, options?: RequestOptions): Promise<TResult>;
+    /**
+     * Runs a mutation document. Distinct from {@link query} for call-site
+     * readability only — GraphQL over HTTP POST makes no distinction.
+     */
+    mutate<TResult, TVariables>(document: GraphQLDocument<TResult, TVariables>, variables?: TVariables, options?: RequestOptions): Promise<TResult>;
+    /**
+     * The single code path behind {@link query} and {@link mutate}.
+     *
+     * Throws {@link UnfazedHTTPError} on non-2xx, {@link UnfazedGraphQLError}
+     * when the body carries `errors`, {@link UnfazedTimeoutError} on timeout or
+     * abort. Resolves to the `data` object on success.
+     */
+    request<TResult = unknown>(document: string | {
+        toString(): string;
+    }, variables?: unknown, options?: RequestOptions): Promise<TResult>;
+}