unfazed 0.6.0 → 0.8.0

package/REFERENCE.md

@@ -0,0 +1,284 @@
+# unfazed SDK reference
+
+Every method of `Unfazed`, with its signature, in one page. In a script:
+`import { Unfazed, help } from "unfazed"; const unfazed = new Unfazed();`
+(run_script injects the credential; elsewhere `UNFZ_API_TOKEN` or
+`npx unfazed login`). `help()` returns this page; `help("writeFiles")` one
+entry. Methods are async and throw an `UnfazedError` subclass on failure.
+Every method takes an optional last `options` with `signal` (and, for single
+requests, `timeoutMs`). The names follow the MCP tools: `listCommits` is
+`list_commits`, `waitForEvents` is `wait_for_events`.
+
+```ts
+import { Unfazed } from "unfazed";
+
+export default async () => {
+  const unfazed = new Unfazed();
+  const ws = await unfazed.ensureWorkspace("hello");
+  const wrote = await unfazed.writeFiles(ws.id, {
+    "server.ts": `export default { fetch: () => new Response("hi") }`,
+    "package.json": JSON.stringify({ name: "hello" }),
+  }, { commitMessage: "First version" });                // ONE request, ONE commit
+  const app = await unfazed.deployService({ workspaceId: ws.id, alias: "hello", wait: true });
+  return { url: app.url, commit: wrote.commit?.sha, timings: app.timings };
+};
+```
+
+## Saved, committed, deployed
+
+A file write has three states. **Saved**: the call returned; the app's
+files have it and the next deploy uses it. **Committed**: on an app with
+platform git, `commit.committed && !commit.waiting`; it is in `listCommits`.
+**Deployed**: a deploy of those files went READY (`deployService({ wait:
+true })`). A write never deploys by itself, except when `commit.deploys` is
+true (the branch head is imported like a push).
+
+`commit.waiting: true` means saved, with the commit queued for the git
+server: it lands in order, `sha` is null until then, nothing to retry.
+`waitForCommit` (or `writeFiles(…, { waitForCommit: true })`) resolves once
+it landed.
+
+## Workspaces
+
+### `createWorkspace(name: string): Promise<Workspace>`
+A new workspace: files, env, deployments. Names are unique per owner,
+case-insensitively; prefer `ensureWorkspace` in re-runnable scripts.
+
+### `ensureWorkspace(name: string): Promise<Workspace>`
+The workspace named `name`, created only when missing. Safe to re-run.
+
+### `listWorkspaces(): Promise<Workspace[]>`
+
+### `liveApps(workspaceId: string): Promise<LiveApp[]>`
+The apps the workspace serves now: `{ alias, deploymentID, domains }`.
+
+### `deleteWorkspace(workspaceId: string, options?: { withDeployments?: true, confirmAliases: string[], ignoreNotFound?: boolean }): Promise<boolean>`
+Deletes it; with `withDeployments`, every app it serves, which
+`confirmAliases` must name exactly (`liveApps`). Kept 30 days for support.
+
+### `deleteApp(app: { workspaceId, alias }, options?: { ignoreNotFound?: boolean }): Promise<DeleteAppResult>`
+Deletes one app (every deployment of the alias, its App State, env and
+bindings); the workspace and its other apps stay.
+
+### `whoami(): Promise<Whoami>`
+Who the token is, its scopes, usage and limits.
+
+## Files
+
+### `writeFiles(workspaceId: string, files: Record<string, string | { text } | { base64 } | { bytes }>, options?: { commitMessage?: string, waitForCommit?: boolean | WaitOptions, allowPartial?: boolean }): Promise<WriteFilesResult>`
+Writes every file in ONE request, which is ONE commit on an app with
+platform git (MCP `write_workspace_files`). Result: `{ files: [{ path, ok,
+error, file }], written, failed, totalBytes, commit, commits, landed? }`;
+`commit` is `{ sha, branch, message, committed, waiting, waitingCount,
+deploys, conflicts, writeSHA, paused }` or null without platform git. Not
+transactional: when a file fails it throws `UnfazedWriteError` (`.result`,
+`.failed`) unless `allowPartial`. Up to 100 files and 32 MiB per request; a
+bigger map is several requests, each a commit.
+
+```ts
+const out = await unfazed.writeFiles(ws.id, { "a.ts": a, "logo.png": { bytes } }, { commitMessage: "Logo" });
+if (out.commit?.conflicts.length) console.log("a push changed", out.commit.conflicts, "mine:", out.commit.writeSHA);
+```
+
+### `writeFile(workspaceId: string, path: string, text: string, options?: { commitMessage?, waitForCommit? }): Promise<WorkspaceFile & { commit }>`
+One text file: `writeFiles` with one entry.
+
+### `writeBinaryFile(workspaceId: string, path: string, content: Uint8Array | ArrayBuffer | { base64: string }, options?): Promise<WorkspaceFile & { commit }>`
+
+### `waitForCommit(workspaceId: string, waitOptions?: WaitOptions): Promise<{ branch, head, waitedMs }>`
+Resolves once no write of the app waits for its commit; `head` then has
+every earlier write. Immediate (`head: null`) without platform git. Default
+timeout 2 minutes (`UnfazedTimeoutError`; the writes stay saved).
+
+### `readFile(workspaceId: string, path: string, input?: { offset?, limit? }): Promise<{ text, totalBytes, truncated, nextOffset, file } | null>`
+
+### `listFiles(workspaceId: string, input?: { limit?, offset?, order? }): Promise<WorkspaceFilePage>`
+
+### `deleteFile(workspaceId: string, path: string): Promise<boolean>`
+`false` when there was nothing to delete.
+
+## Deploys
+
+### `deployService(options: { workspaceId, alias?, wait?, waitOptions?, timings?, runtime?, serviceMode?, healthPath?, cronSchedule?, cronPath? }): Promise<DeployResult>`
+Builds and deploys the workspace as an HTTP service (`server.ts` default
+export, or `unfazed.json`). Returns BUILDING at once; with `wait: true`,
+resolves READY or throws `UnfazedDeployError` (`reason` FAILED with the
+build error, or TIMEOUT; default 10 minutes). Every call is a new release;
+the same `alias` redeploys that app.
+
+With `wait: true` the result has `timings`:
+`{ client: { createMs, waitMs, totalMs, waitRequests, waitMode },
+platform: { totalMs, buildMs, promoteMs, phases, buildMode,
+artifactTransport, buildMemoryMiB } }`, both in milliseconds. `platform` is
+what the platform measured (created to READY); `client` is what you waited.
+The wait is server-side, so the two differ by about one round trip.
+
+```ts
+const app = await unfazed.deployService({ workspaceId: ws.id, alias: "api", wait: true });
+app.timings?.platform?.phases;   // { vm_install: 900, vm_build: 2600, admission: 40, … }
+```
+
+### `deployStatic(options: { workspaceId, alias?, wait?, spaMode? }): Promise<DeployResult>`
+
+### `deployBox(options: { workspaceId, alias, wait?, resources?: { memMiB?, vcpus?, diskGiB? } }): Promise<DeployResult>`
+A persistent Linux VM over SSH (`sshCommand`). Always pass `alias`.
+
+### `deploy(input: CreateDeploymentInput, options?: { wait?, waitOptions?, timings? }): Promise<DeployResult>`
+Any `createDeployment` input.
+
+### `waitForDeployment(deploymentId: string, waitOptions?: WaitOptions): Promise<Deployment>`
+Waits server-side (MCP `wait_for_deployment`: one request per 45 s at most,
+answered when the status changes) until READY; throws `UnfazedDeployError`
+on FAILED or timeout. A new app's landing on its server is waited for too.
+`waitOptions: { timeoutMs?, signal?, mode?: "server" | "poll" }`. The
+platform holds at most 16 waits of one account at once; past that a wait
+polls instead.
+
+### `getDeployment(deploymentId: string): Promise<Deployment | null>`
+
+### `getDeploymentByAlias(alias: string): Promise<Deployment | null>`
+
+### `listDeployments(input?: { workspaceID?, alias?, kind?, limit?, offset? }): Promise<DeploymentPage>`
+Newest first.
+
+### `listReleases(alias: string): Promise<Deployment[]>`
+The alias's history; `aliasHeld` marks the live one.
+
+### `rollback(options: { alias, to?, expectedCurrentId?, retries? }): Promise<Deployment>`
+Points the alias back at a prior READY release (default: the one before
+the live one). A bare `rollback({ alias })` toggles; pin `to` in anything
+re-runnable.
+
+### `deleteDeployment(deploymentId: string, options?: { ignoreNotFound? }): Promise<boolean>`
+
+## Runtime, logs, events, timings
+
+### `getStatus(deploymentId: string): Promise<ServiceStatus>`
+`{ running, health, inFlight, restartCount, memSizeMiB, lastError, … }`.
+
+### `getLogs(deploymentId: string, input?: { tailBytes? }): Promise<{ stdout, stderr, truncated, … }>`
+Filter in the script: `logs.stderr.split("\n").filter((l) => l.includes("ERROR"))`.
+
+### `getEvents(deploymentId: string, limit?: number): Promise<DeploymentEvent[]>`
+The latest `limit` (default 20) lifecycle events, oldest first: `{ type,
+typeEnum, severity, message, vmID, metadata, createdAt }`. `type` is the
+event's own name, as MCP reports it: `"deployment.build_finished"`,
+`"deployment.phases"`, `"service.vm_started"`. `typeEnum` is the GraphQL
+enum (`UNKNOWN` for names it lacks); match on `type`.
+
+### `getDeploymentTimings(deploymentId: string): Promise<PlatformTimings | null>`
+A deploy's measured phases (ms) from its timing events: `{ totalMs,
+buildMs, promoteMs, phases, buildMode, artifactTransport, buildMemoryMiB }`.
+`parseDeploymentTimings(events)` does the same for events you already read.
+
+### `restartService(deploymentId: string)` / `stopService(deploymentId: string)`
+
+## Env and secrets
+
+Snapshotted into a release at deploy time: redeploy the alias to apply.
+
+### `setEnv(workspaceId, name, value)` / `setSecret(workspaceId, name, value)`: `Promise<EnvVar>`
+Workspace defaults. A name is plain or secret, never both.
+
+### `setEnvMany(workspaceId: string, vars: Record<string, string>, options?: { secret?: boolean }): Promise<EnvVar[]>`
+
+### `deleteEnv(workspaceId, name): Promise<boolean>` / `listEnv(workspaceId): Promise<EnvVar[]>`
+
+### `setAppEnv(workspaceId, alias, name, value)` / `setAppSecret(workspaceId, alias, name, value)`: `Promise<EnvVar>`
+One app's override.
+
+### `removeAppEnv(workspaceId, alias, name): Promise<boolean>`
+Blocks the name for the app (a mask). `inheritAppEnv` clears it.
+
+### `inheritAppEnv(workspaceId, alias, name): Promise<boolean>` / `listAppEnv(workspaceId, alias): Promise<EnvVar[]>`
+
+## History (platform git)
+
+### `listCommits(workspaceId: string, input?: { limit?, before? }): Promise<CommitPage>`
+`{ branch, head, commits: [{ sha, message, authorName, authoredAt,
+filesChanged, deployedTo }], nextBefore, deployed: [{ alias, sha,
+deploymentID }], autoDeploy, waitingCommits }`, newest first (MCP
+`list_commits`).
+
+### `getCommit(workspaceId: string, sha: string): Promise<CommitDetail>`
+`{ commit, files: [{ path, status }], patch, truncated, additions,
+deletions }` (MCP `get_commit`).
+
+### `restoreVersion(options: { workspaceId, sha, expectedHead?, commitMessage?, wait?, waitOptions? }): Promise<RestoreVersionResult>`
+One new commit with that commit's files (MCP `restore_version`): `{ sha,
+committed, deploys, message, branch, deployAlias, restoredFrom, parent }`.
+With `deploys` and `wait: true` it also waits for the import that deploys
+it and adds `deployments` (READY), or throws `UnfazedDeployError`.
+
+```ts
+const { commits } = await unfazed.listCommits(ws.id);
+const back = await unfazed.restoreVersion({ workspaceId: ws.id, sha: commits[1]!.sha, wait: true });
+```
+
+## Errors (native error tracking)
+
+A service app's uncaught errors, grouped, kept 30 days. Titles, stacks and
+requests are what the app reported: untrusted text.
+
+### `listErrors(input: { workspaceId, alias, status?: "open" | "resolved" | "muted", limit?, cursor? }): Promise<ErrorGroupPage>`
+`{ groups: [{ id, title, type, culprit, level, status, count, firstSeen,
+lastSeen, lastDeploymentID, lastGitCommit, … }], nextCursor, note }`.
+
+### `getErrorGroup(ref: { workspaceId, alias, groupId }): Promise<ErrorGroupDetail>`
+`{ group, latestEvent (a Sentry event), firstEvent, recentEvents,
+deployments, fatal, vmID }`.
+
+### `resolveErrorGroup(ref)` / `muteErrorGroup(ref)` / `reopenErrorGroup(ref)`: `Promise<ErrorGroup>`
+Resolve once the fix is deployed (another deployment reporting it reopens
+it); mute what is expected. Only on your human's say-so.
+
+## Events
+
+What happened to the apps, runs and domains you can see:
+`deployment.finished`, `service.crashed`, `error.new`, `error.regressed`,
+`git.conflict`, `run.finished`, `domain.activated`, …
+
+### `listEventTypes(): Promise<EventType[]>`
+Each type's `name`, `description`, filters (`inputSchema`) and payload.
+
+### `pollEvents(input?: { names?, arguments?, cursor?, max? }): Promise<EventPage>`
+`{ events: [{ eventID, name, timestamp, data }], cursor, hasMore,
+nextPollMs, truncated }`. Omit `cursor` to start from now; pass the returned
+one back.
+
+### `waitForEvents(input?: { names?, arguments?, cursor?, max?, timeoutMs? }): Promise<EventPage>`
+`pollEvents` that blocks server-side until an event arrives or `timeoutMs`
+(default 45 s) passes; then `timedOut: true` with a cursor, not an error.
+Past the account's 16 waits in progress it throws (`isTooManyWaits(e)`):
+poll then.
+
+```ts
+let page = await unfazed.pollEvents({ names: ["deployment.finished"], arguments: { "deployment.finished": { alias: "api" } } });
+// … deploy …
+page = await unfazed.waitForEvents({ names: ["deployment.finished"], cursor: page.cursor, timeoutMs: 120_000 });
+```
+
+## Agent runs
+
+### `createRun(options: { workspaceId, prompt?, harness?, command?, setup?, verify?, access?, alias?, maxSeconds?, wait? }): Promise<Run>`
+A one-shot agent run in a fresh VM. `wait: true` polls to SUCCEEDED,
+FAILED or CANCELLED (all returned, never thrown).
+
+### `waitForRun(runId: string, waitOptions?: WaitOptions): Promise<Run>`
+
+### `getRun(runId)` / `listRuns(filter?: { workspaceId?, status?, limit?, offset? })` / `cancelRun(runId)`
+
+### `followUpRun(runId: string, options: { prompt, mode?, wait? }): Promise<Run>`
+
+### `answerRun(runId: string, answer: string): Promise<Run>`
+Answers a BLOCKED run's question.
+
+### `runEvents(runId)` / `runConsole(runId, { tailBytes? })` / `runTranscript(runId, { tailBytes? })`
+
+### `listRunHarnesses(): Promise<RunHarness[]>`
+
+## Anything else
+
+`unfazed.client` is the typed GraphQL transport over the same credential:
+`await unfazed.client.query(document, variables)`. `operations` exports
+every document the SDK uses.

package/dist/cli/login.d.ts

@@ -0,0 +1,129 @@
+import { type StoredCredentials } from "../credentials.js";
+import { UnfazedError } from "../errors.js";
+export declare const USER_AGENT = "unfazed-cli/0.8.0 (+https://unfazed.dev/auth.md)";
+/** What a login asks for: reading and deploying, like an MCP client. */
+export declare const DEFAULT_SCOPE = "unfz:read unfz:deploy";
+export declare const CLIENT_NAME = "unfazed CLI";
+export declare const CALLBACK_PATH = "/callback";
+/** The redirect registered once; each login uses it with its own port. */
+export declare const REGISTERED_REDIRECT_URI = "http://127.0.0.1/callback";
+/** Registered clients, per issuer, beside the login. */
+export declare const CLIENTS_FILE = "oauth-clients.json";
+/** How long a login waits for the browser. */
+export declare const LOGIN_TIMEOUT_MS: number;
+export type Env = Record<string, string | undefined>;
+/** The `fetch` the CLI needs; the global one fits. */
+export type Fetch = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    redirect?: "manual" | "follow";
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** A login that could not be completed; the message says why and what to do. */
+export declare class UnfazedLoginError extends UnfazedError {
+}
+/** The GraphQL endpoint: given, else `UNFZ_API_URL`, else unfazed.dev's; a bare origin gets `/query`. */
+export declare function resolveEndpoint(raw: string | undefined, env: Env): string;
+/** Whether a URL may carry tokens: https, or plain http to this machine only. */
+export declare function safeURL(raw: unknown): raw is string;
+/** RFC 8414 authorization server metadata: the fields the CLI uses. */
+export interface AuthServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    revocation_endpoint?: string;
+    code_challenge_methods_supported?: string[];
+    response_types_supported?: string[];
+    authorization_response_iss_parameter_supported?: boolean;
+}
+/** Reads and checks the metadata of the server at `origin` (e.g. https://unfazed.dev). */
+export declare function discover(origin: string, fetch: Fetch): Promise<AuthServerMetadata>;
+/** A PKCE verifier and its S256 challenge. */
+export declare function pkcePair(): {
+    verifier: string;
+    challenge: string;
+};
+/** A client the CLI registered at one issuer. */
+export interface ClientRecord {
+    client_id: string;
+    redirect_uri: string;
+    scope: string;
+    registered_at: string;
+}
+/** The cached client for `issuer` that may ask for `scope`, if any. */
+export declare function cachedClient(env: Env, issuer: string, scope: string): ClientRecord | undefined;
+export interface LoginOptions {
+    /** GraphQL endpoint or platform origin. Default: `UNFZ_API_URL`, else https://unfazed.dev. */
+    endpoint?: string;
+    /** Space-separated scopes. Default: `unfz:read unfz:deploy`. */
+    scope?: string;
+    /** Default `process.env`: where `UNFZ_API_URL` and the login's location come from. */
+    env?: Env;
+    fetch?: Fetch;
+    /** Opens the sign-in URL; resolves to whether a browser started. Default: print only. */
+    openBrowser?: (url: string) => boolean | Promise<boolean>;
+    /** Where progress goes (never a token). Default: stderr. */
+    log?: (line: string) => void;
+    /** Where a pasted answer is read from (a browser on another machine). Default: none. */
+    input?: NodeJS.ReadableStream;
+    /** How long to wait for the browser. Default {@link LOGIN_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/** Signs in through the browser and stores the login. Resolves to it and where it was stored. */
+export declare function login(options?: LoginOptions): Promise<{
+    credentials: StoredCredentials;
+    path: string;
+}>;
+/** The fields `whoami` shows. */
+export interface Actor {
+    kind: string;
+    userID: string;
+    name: string;
+    scopes: string[];
+}
+export interface WhoamiResult {
+    actor: Actor;
+    endpoint: string;
+    /** `token`: UNFZ_API_TOKEN; `login`: the stored login at `path`. */
+    source: "token" | "login";
+    path?: string;
+}
+/** Who the SDK acts as here: `UNFZ_API_TOKEN` when set, else the stored login (refreshed as needed). */
+export declare function whoami(options?: {
+    env?: Env;
+    fetch?: Fetch;
+}): Promise<WhoamiResult>;
+export interface LogoutResult {
+    /** Whether there was a login to remove. */
+    signedOut: boolean;
+    issuer?: string;
+    /** Whether the server revoked the tokens. */
+    revoked: boolean;
+    /** Whether the server offers revocation (RFC 7009). */
+    revocationSupported: boolean;
+}
+/**
+ * Revokes the stored tokens when the server advertises revocation, then
+ * deletes the login. The endpoint is read from the server's metadata again,
+ * so one the server gained since the login is used.
+ */
+export declare function logout(options?: {
+    env?: Env;
+    fetch?: Fetch;
+}): Promise<LogoutResult>;
+export declare function accountName(credentials: StoredCredentials): string;
+/**
+ * Whether a browser can be expected here. Over SSH, or on Linux without a
+ * display, the login prints the URL instead (and takes the pasted answer).
+ */
+export declare function canOpenBrowser(env: Env, platform?: NodeJS.Platform): boolean;
+/** The command that opens `url` — `$BROWSER`, `open`, `xdg-open` or the Windows URL handler — as argv, never a shell line. */
+export declare function browserCommand(url: string, env: Env, platform?: NodeJS.Platform): string[];
+/** Starts the browser on `url`. Resolves to whether it could be started. */
+export declare function openBrowser(url: string, env?: Env, platform?: NodeJS.Platform): Promise<boolean>;