@spatius/cli 0.1.0-beta.0

package/dist/cli.js

@@ -0,0 +1,2523 @@
+#!/usr/bin/env node
+import {
+  CliError,
+  asCliError,
+  buildProgram
+} from "./chunk-YILIK7FE.js";
+
+// src/cli.ts
+import { CommanderError } from "commander";
+
+// src/auth/index.ts
+import { createHash as createHash2 } from "crypto";
+
+// src/auth/client.ts
+function object(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw invalidResponse();
+  return value;
+}
+function string(value, key) {
+  const result = value[key];
+  if (typeof result !== "string" || !result.trim()) throw invalidResponse();
+  return result;
+}
+function invalidResponse() {
+  return new CliError(
+    "STUDIO_INVALID_RESPONSE",
+    "Studio returned an invalid response.",
+    { retryable: true }
+  );
+}
+var errorStatuses = {
+  UNAUTHORIZED: 401,
+  unauthorized: 401,
+  FORBIDDEN: 403,
+  PERMISSION_DENIED: 403,
+  forbidden: 403,
+  NOT_FOUND: 404,
+  not_found: 404,
+  INVALID_ARGUMENT: 400,
+  invalid_request: 400,
+  QUOTA_EXCEEDED: 429,
+  ALREADY_EXISTS: 409,
+  UNAVAILABLE: 503,
+  INTERNAL_SERVER_ERROR: 500
+};
+var StudioClient = class {
+  constructor(origin2, fetcher = globalThis.fetch) {
+    this.origin = origin2;
+    this.fetcher = fetcher;
+  }
+  origin;
+  fetcher;
+  async request(path, options = {}) {
+    const method = options.body === void 0 ? "GET" : "POST";
+    let response;
+    try {
+      response = await this.fetcher(new URL(path, this.origin), {
+        method,
+        headers: {
+          Accept: "application/json",
+          ...options.token ? { Authorization: `Bearer ${options.token}` } : {},
+          ...options.body === void 0 ? {} : { "Content-Type": "application/json" }
+        },
+        ...options.body === void 0 ? {} : { body: JSON.stringify(options.body) },
+        redirect: "error",
+        signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(3e4)]) : AbortSignal.timeout(3e4)
+      });
+    } catch {
+      if (options.signal?.aborted)
+        throw new CliError("INTERRUPTED", "Login was interrupted.", {
+          exitCode: 130
+        });
+      throw new CliError(
+        "STUDIO_UNAVAILABLE",
+        "The Studio request could not be completed.",
+        {
+          retryable: method === "GET",
+          recovery: "Check your connection and retry a read. Reconcile setup before retrying a creation."
+        }
+      );
+    }
+    let payload;
+    try {
+      const reader = response.body?.getReader();
+      const chunks = [];
+      let length = 0;
+      if (reader) {
+        try {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            length += value.length;
+            if (length > 2 * 1024 * 1024) throw invalidResponse();
+            chunks.push(value);
+          }
+        } finally {
+          await reader.cancel().catch(() => void 0);
+        }
+      }
+      const text = Buffer.concat(chunks).toString("utf8");
+      payload = text.trim() ? object(JSON.parse(text)) : {};
+    } catch {
+      if (!response.ok) throw this.httpError(response.status);
+      throw invalidResponse();
+    }
+    const errors = payload.errors;
+    const raw = Array.isArray(errors) && errors.length ? errors[0] : payload.error;
+    if (raw !== void 0 && raw !== null) {
+      const detail = typeof raw === "object" ? raw : {};
+      const number = Number(detail.status);
+      const status = Number.isInteger(number) && number >= 400 && number <= 599 ? number : errorStatuses[String(detail.code)] ?? (response.ok ? 500 : response.status);
+      throw this.httpError(status);
+    }
+    if (!response.ok) throw this.httpError(response.status);
+    return payload;
+  }
+  httpError(status) {
+    return new CliError(
+      status === 401 ? "AUTH_REQUIRED" : status === 403 ? "STUDIO_FORBIDDEN" : status === 404 ? "STUDIO_NOT_FOUND" : "STUDIO_ERROR",
+      status === 401 ? "Your Studio login is no longer valid." : `Studio rejected the request (HTTP ${status}).`,
+      {
+        status,
+        retryable: status === 429 || status >= 500,
+        ...status === 401 ? { recovery: "Run spatius auth login." } : {}
+      }
+    );
+  }
+};
+
+// src/auth/login.ts
+import { execFile } from "child_process";
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import { promisify } from "util";
+async function browserLogin(client, studioWebOrigin, options) {
+  if (options.signal?.aborted)
+    throw new CliError("INTERRUPTED", "Login was interrupted.", {
+      exitCode: 130
+    });
+  const verifier = randomBytes(32).toString("base64url");
+  const state = randomBytes(18).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  let redirectUri;
+  let requestId = "";
+  let complete = () => void 0;
+  let reject = () => void 0;
+  const callback = new Promise((resolve3, fail) => {
+    complete = resolve3;
+    reject = fail;
+  });
+  void callback.catch(() => void 0);
+  let settled = false;
+  const server = createServer((request, response) => {
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("Referrer-Policy", "no-referrer");
+    response.setHeader("Content-Security-Policy", "default-src 'none'");
+    if (request.method !== "GET" || request.headers.host !== redirectUri.host || !request.url || settled) {
+      response.writeHead(404).end("Not found");
+      return;
+    }
+    const url = new URL(request.url, redirectUri);
+    const query = url.searchParams;
+    if (url.origin !== redirectUri.origin || url.pathname !== "/callback") {
+      response.writeHead(404).end("Not found");
+      return;
+    }
+    if (query.getAll("state").length !== 1 || query.get("state") !== state || query.getAll("auth_request_id").length !== 1 || query.get("auth_request_id") !== requestId) {
+      response.writeHead(400).end("Invalid authorization callback.");
+      return;
+    }
+    if (query.has("error")) {
+      settled = true;
+      response.writeHead(400).end("Authorization was declined. Return to your terminal.");
+      reject(
+        new CliError("AUTH_DECLINED", "Studio authorization was declined.")
+      );
+      return;
+    }
+    const code = query.get("auth_code");
+    if (!code || query.getAll("auth_code").length !== 1) {
+      response.writeHead(400).end("Invalid authorization callback.");
+      return;
+    }
+    settled = true;
+    response.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" }).end("Spatius authorization received. Return to your terminal.");
+    complete(code);
+  });
+  let timeout;
+  const onAbort = () => reject(
+    new CliError("INTERRUPTED", "Login was interrupted.", { exitCode: 130 })
+  );
+  try {
+    await new Promise((resolve3, fail) => {
+      server.once("error", fail);
+      server.listen(0, "127.0.0.1", () => {
+        server.off("error", fail);
+        resolve3();
+      });
+    }).catch(() => {
+      throw new CliError(
+        "AUTH_CALLBACK_UNAVAILABLE",
+        "The local login callback listener could not be started.",
+        {
+          recovery: "Allow local loopback connections, then run spatius auth login again."
+        }
+      );
+    });
+    redirectUri = new URL(
+      `http://127.0.0.1:${server.address().port}/callback`
+    );
+    const session = await client.request("/v1/cli/auth/sessions", {
+      body: {
+        clientName: "Spatius CLI",
+        codeChallenge: challenge,
+        codeChallengeMethod: "CLI_AUTH_CODE_CHALLENGE_METHOD_S256",
+        redirectUri: redirectUri.href,
+        state
+      },
+      signal: options.signal
+    });
+    requestId = string(session, "authRequestId");
+    const authorizeUrl = new URL(string(session, "authorizeUrl"));
+    if (authorizeUrl.origin !== studioWebOrigin || authorizeUrl.username || authorizeUrl.password || authorizeUrl.pathname !== `/cli/auth/${encodeURIComponent(requestId)}`) {
+      throw new CliError(
+        "UNSAFE_AUTH_URL",
+        "Studio returned an unexpected authorization URL."
+      );
+    }
+    const expiresAt = typeof session.expiresAt === "string" ? Date.parse(session.expiresAt) - Date.now() : Number.POSITIVE_INFINITY;
+    const expiresIn = typeof session.expiresIn === "number" && session.expiresIn > 0 ? session.expiresIn * 1e3 : Number.POSITIVE_INFINITY;
+    const requested = options.timeoutMs ?? 5 * 6e4;
+    if (!Number.isFinite(requested) || requested <= 0)
+      throw new CliError("INVALID_ARGUMENT", "Login timeout must be positive.");
+    const milliseconds = Math.max(
+      1,
+      Math.min(
+        requested,
+        10 * 6e4,
+        Number.isFinite(expiresAt) ? expiresAt : Infinity,
+        expiresIn
+      )
+    );
+    timeout = setTimeout(
+      () => reject(
+        new CliError(
+          "AUTH_TIMEOUT",
+          "Timed out waiting for Studio authorization.",
+          { recovery: "Run spatius auth login again." }
+        )
+      ),
+      milliseconds
+    );
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted) onAbort();
+    options.onAuthorize?.(authorizeUrl.href);
+    if (!options.noBrowser) {
+      const executable = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32.exe" : "xdg-open";
+      const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", authorizeUrl.href] : [authorizeUrl.href];
+      await promisify(execFile)(executable, args, {
+        timeout: 1e4,
+        windowsHide: true
+      }).catch(() => void 0);
+    }
+    const authCode = await callback;
+    return await client.request("/v1/cli/auth/token", {
+      body: { authRequestId: requestId, authCode, codeVerifier: verifier },
+      signal: options.signal
+    });
+  } finally {
+    if (timeout) clearTimeout(timeout);
+    options.signal?.removeEventListener("abort", onAbort);
+    await new Promise((resolve3) => {
+      server.close(() => resolve3());
+      server.closeAllConnections();
+    });
+  }
+}
+
+// src/auth/storage.ts
+import { randomUUID } from "crypto";
+import { constants } from "fs";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+  stat
+} from "fs/promises";
+import { homedir } from "os";
+import { dirname, isAbsolute, join } from "path";
+import { setTimeout as delay } from "timers/promises";
+function ioError(error) {
+  return error?.code;
+}
+function defaultDirectory() {
+  if (process.platform === "win32")
+    return join(
+      process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"),
+      "Spatius"
+    );
+  const xdg = process.env.XDG_CONFIG_HOME;
+  return join(
+    xdg && isAbsolute(xdg) ? xdg : join(homedir(), ".config"),
+    "spatius"
+  );
+}
+function unsafe() {
+  return new CliError(
+    "UNSAFE_AUTH_STORAGE",
+    "The credential path is not a private regular file or directory.",
+    {
+      recovery: "Use a private configuration directory owned by your user; remove symbolic links or shared credential files."
+    }
+  );
+}
+var AuthStorage = class {
+  directory;
+  filename;
+  constructor(directory = defaultDirectory()) {
+    if (!isAbsolute(directory))
+      throw new CliError(
+        "INVALID_CONFIG",
+        "The configuration directory must be an absolute path."
+      );
+    this.directory = directory;
+    this.filename = join(directory, "auth.json");
+  }
+  async ensureDirectory() {
+    await mkdir(this.directory, { recursive: true, mode: 448 });
+    const info = await lstat(this.directory);
+    if (!info.isDirectory() || info.isSymbolicLink() || process.getuid && info.uid !== process.getuid())
+      throw unsafe();
+    if (process.platform !== "win32") await chmod(this.directory, 448);
+  }
+  async read() {
+    try {
+      const directory = await lstat(this.directory);
+      if (!directory.isDirectory() || directory.isSymbolicLink() || process.getuid && directory.uid !== process.getuid())
+        throw unsafe();
+    } catch (error) {
+      if (ioError(error) === "ENOENT")
+        return { version: 1, active: {}, profiles: {} };
+      throw error;
+    }
+    let file;
+    try {
+      file = await open(
+        this.filename,
+        constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)
+      );
+    } catch (error) {
+      if (ioError(error) === "ENOENT")
+        return { version: 1, active: {}, profiles: {} };
+      if (ioError(error) === "ELOOP") throw unsafe();
+      throw error;
+    }
+    try {
+      const info = await file.stat();
+      if (!info.isFile() || info.nlink !== 1 || info.size > 1024 * 1024 || process.getuid && info.uid !== process.getuid() || process.platform !== "win32" && (info.mode & 63) !== 0)
+        throw unsafe();
+      const state = JSON.parse(await file.readFile("utf8"));
+      if (!validState(state)) throw new Error("Invalid auth state");
+      return state;
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      throw new CliError(
+        "AUTH_STATE_INVALID",
+        "The saved login state could not be read.",
+        {
+          recovery: "Restore the private auth.json file from a known backup, or remove it and run spatius auth login."
+        }
+      );
+    } finally {
+      await file.close();
+    }
+  }
+  async write(state) {
+    const temporary = join(this.directory, `.auth-${randomUUID()}.tmp`);
+    const file = await open(temporary, "wx", 384);
+    try {
+      await file.writeFile(`${JSON.stringify(state)}
+`);
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    try {
+      await rename(temporary, this.filename);
+      if (process.platform !== "win32") {
+        const dir = await open(dirname(this.filename), "r");
+        try {
+          await dir.sync();
+        } finally {
+          await dir.close();
+        }
+      }
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  }
+  async locked(operation) {
+    await this.ensureDirectory();
+    const lock = join(this.directory, ".auth-lock");
+    const ownerFile = join(lock, "owner.json");
+    const nonce = randomUUID();
+    const deadline = Date.now() + 45e3;
+    for (; ; ) {
+      try {
+        await mkdir(lock, { mode: 448 });
+        const owner = await open(ownerFile, "wx", 384);
+        try {
+          await owner.writeFile(JSON.stringify({ pid: process.pid, nonce }));
+        } finally {
+          await owner.close();
+        }
+        break;
+      } catch (error) {
+        if (ioError(error) !== "EEXIST") throw error;
+        const lockInfo = await lstat(lock).catch(() => void 0);
+        if (lockInfo && (!lockInfo.isDirectory() || lockInfo.isSymbolicLink()))
+          throw unsafe();
+        let abandoned = false;
+        try {
+          const owner = JSON.parse(await readFile(ownerFile, "utf8"));
+          if (!Number.isInteger(owner.pid) || owner.pid <= 0) throw unsafe();
+          try {
+            process.kill(owner.pid, 0);
+          } catch (error2) {
+            abandoned = ioError(error2) === "ESRCH";
+          }
+        } catch (error2) {
+          if (error2 instanceof CliError) throw error2;
+          const info = await stat(lock).catch(() => void 0);
+          abandoned = !!info && Date.now() - info.mtimeMs > 3e4;
+        }
+        if (abandoned) {
+          const stale = `${lock}.stale-${nonce}`;
+          try {
+            await rename(lock, stale);
+            await rm(stale, { recursive: true, force: true });
+          } catch (error2) {
+            if (ioError(error2) !== "ENOENT") throw error2;
+          }
+          continue;
+        }
+        if (Date.now() >= deadline)
+          throw new CliError(
+            "AUTH_BUSY",
+            "Another Spatius command is updating login state.",
+            {
+              retryable: true,
+              recovery: "Wait for the other command to finish, then retry."
+            }
+          );
+        await delay(50);
+      }
+    }
+    try {
+      return await operation(await this.read());
+    } finally {
+      const owner = JSON.parse(await readFile(ownerFile, "utf8"));
+      if (owner.nonce === nonce)
+        await rm(lock, { recursive: true, force: true });
+    }
+  }
+};
+function validState(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value;
+  if (state.version !== 1 || !state.active || !state.profiles || typeof state.active !== "object" || typeof state.profiles !== "object" || Array.isArray(state.active) || Array.isArray(state.profiles))
+    return false;
+  if (!Object.values(state.active).every((v) => typeof v === "string"))
+    return false;
+  return Object.values(state.profiles).every(
+    (profile) => profile && typeof profile === "object" && typeof profile.userId === "string" && typeof profile.consoleOrigin === "string" && typeof profile.studioOrigin === "string" && ["accessToken", "refreshToken", "expiresAt", "appId", "apiKey"].every(
+      (key) => profile[key] === void 0 || typeof profile[key] === "string"
+    ) && ["refreshPending", "pendingApp", "pendingKey"].every(
+      (key) => profile[key] === void 0 || typeof profile[key] === "boolean"
+    )
+  );
+}
+
+// src/auth/index.ts
+var defaultAppName = "Spatius CLI";
+var hash = (value) => createHash2("sha256").update(value).digest("hex");
+function canonicalOrigin(value) {
+  const url = new URL(value);
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) {
+    throw new CliError(
+      "INVALID_CONFIG",
+      "Studio and Console origins must be HTTPS origins, or HTTP loopback origins for local development."
+    );
+  }
+  return url.origin;
+}
+function requireLogin() {
+  return new CliError(
+    "AUTH_REQUIRED",
+    "Log in to Spatius Studio before using this command.",
+    { recovery: "Run spatius auth login.", exitCode: 1 }
+  );
+}
+function relogin() {
+  return new CliError(
+    "AUTH_RELOGIN_REQUIRED",
+    "The previous token refresh did not complete safely.",
+    {
+      recovery: "Run spatius auth login. Do not retry the previous refresh token.",
+      exitCode: 1
+    }
+  );
+}
+function safeApp(app) {
+  return { appId: app.appId, name: app.name, createdAt: app.createdAt };
+}
+function parseApp(raw) {
+  const value = object(raw);
+  const keys = value.apiKeys === void 0 ? [] : value.apiKeys;
+  if (!Array.isArray(keys)) throw invalidResponse();
+  return {
+    appId: string(value, "appId"),
+    name: string(value, "name"),
+    createdAt: string(value, "createdAt"),
+    keys: keys.map((raw2) => {
+      const key = object(raw2);
+      return {
+        value: string(key, "apiKey"),
+        createdAt: string(key, "createdAt")
+      };
+    })
+  };
+}
+function applyTokens(profile, value) {
+  const token = object(value);
+  const access = string(token, "accessToken");
+  const refresh = string(token, "refreshToken");
+  let expiry = typeof token.expiresAt === "string" ? Date.parse(token.expiresAt) : NaN;
+  if (!Number.isFinite(expiry) && typeof token.expiresIn === "number" && token.expiresIn > 0)
+    expiry = Date.now() + token.expiresIn * 1e3;
+  if (!Number.isFinite(expiry) || expiry <= Date.now()) throw invalidResponse();
+  profile.accessToken = access;
+  profile.refreshToken = refresh;
+  profile.expiresAt = new Date(expiry).toISOString();
+  delete profile.refreshPending;
+}
+var AuthManager = class {
+  studioOrigin;
+  studioWebOrigin;
+  consoleOrigin;
+  originKey;
+  storage;
+  client;
+  constructor(options) {
+    this.studioOrigin = canonicalOrigin(options.studioOrigin);
+    this.studioWebOrigin = canonicalOrigin(
+      options.studioWebOrigin ?? "https://app.spatius.ai"
+    );
+    this.consoleOrigin = canonicalOrigin(options.consoleOrigin);
+    this.originKey = hash(`${this.studioOrigin}
+${this.consoleOrigin}`);
+    this.storage = new AuthStorage(options.configDir);
+    this.client = new StudioClient(this.studioOrigin, options.fetch);
+  }
+  stateDirectory() {
+    return this.storage.directory;
+  }
+  async login(options = {}) {
+    const result = await browserLogin(
+      this.client,
+      this.studioWebOrigin,
+      options
+    );
+    const userId = string(object(result.user), "id");
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+      userId
+    ))
+      throw invalidResponse();
+    return this.storage.locked(async (state) => {
+      const profileKey = this.profileKey(userId);
+      const profile = state.profiles[profileKey] ?? {
+        userId,
+        consoleOrigin: this.consoleOrigin,
+        studioOrigin: this.studioOrigin
+      };
+      applyTokens(profile, result.token);
+      state.profiles[profileKey] = profile;
+      state.active[this.originKey] = profileKey;
+      await this.storage.write(state);
+      return this.summary(profile);
+    });
+  }
+  async status() {
+    return this.storage.locked(async (state) => {
+      const profile = this.current(state, false);
+      if (!profile?.accessToken || !profile.refreshToken || profile.refreshPending)
+        return { authenticated: false };
+      try {
+        await this.verifyIdentity(state, profile);
+        return this.summary(profile);
+      } catch (error) {
+        if (error instanceof CliError && (error.options.status === 401 || error.code === "AUTH_RELOGIN_REQUIRED" || error.code === "AUTH_REQUIRED"))
+          return { authenticated: false };
+        throw error;
+      }
+    });
+  }
+  async logout() {
+    return this.storage.locked(async (state) => {
+      const profile = this.current(state, false);
+      if (!profile) return { authenticated: false, revoked: true };
+      let revoked = true;
+      try {
+        if (profile.refreshToken)
+          await this.client.request("/v1/cli/auth/token:revoke", {
+            body: { refreshToken: profile.refreshToken }
+          });
+      } catch {
+        revoked = false;
+      }
+      delete profile.accessToken;
+      delete profile.refreshToken;
+      delete profile.expiresAt;
+      delete profile.refreshPending;
+      delete profile.apiKey;
+      await this.storage.write(state);
+      return { authenticated: false, revoked };
+    });
+  }
+  async accessToken() {
+    return this.storage.locked(async (state) => {
+      const profile = this.current(state);
+      await this.ensureToken(state, profile);
+      return profile.accessToken;
+    });
+  }
+  async identity() {
+    return this.storage.locked(async (state) => {
+      const profile = this.current(state);
+      await this.verifyIdentity(state, profile);
+      return {
+        userId: profile.userId,
+        profileKey: this.profileKey(profile.userId)
+      };
+    });
+  }
+  async credentials() {
+    return this.storage.locked(async (state) => {
+      const profile = this.current(state);
+      await this.verifyIdentity(state, profile);
+      if (!profile.appId || !profile.apiKey)
+        throw new CliError(
+          "SETUP_REQUIRED",
+          "No app credentials are configured for this Studio account.",
+          { recovery: "Run spatius setup." }
+        );
+      const app = await this.getApp(state, profile, profile.appId);
+      if (!app.keys.some((key) => key.value === profile.apiKey)) {
+        delete profile.apiKey;
+        await this.storage.write(state);
+        throw new CliError(
+          "APP_KEY_UNAVAILABLE",
+          "The selected app key is no longer active.",
+          { recovery: "Run spatius setup to select an active key." }
+        );
+      }
+      return {
+        userId: profile.userId,
+        appId: profile.appId,
+        apiKey: profile.apiKey
+      };
+    });
+  }
+  async listApps() {
+    return this.storage.locked(async (state) => {
+      const profile = this.current(state);
+      await this.verifyIdentity(state, profile);
+      return (await this.apps(state, profile)).map(safeApp);
+    });
+  }
+  async setup(options = {}) {
+    return this.storage.locked(async (state) => {
+      const profile = this.current(state);
+      await this.verifyIdentity(state, profile);
+      let app;
+      let reused = true;
+      if (options.appId !== void 0) {
+        if (!options.appId.trim())
+          throw new CliError("INVALID_ARGUMENT", "An app ID is required.");
+        app = await this.getApp(state, profile, options.appId);
+        if (profile.appId !== app.appId) {
+          delete profile.apiKey;
+          delete profile.pendingKey;
+        }
+        profile.appId = app.appId;
+        delete profile.pendingApp;
+        await this.storage.write(state);
+      } else {
+        if (profile.appId) {
+          try {
+            app = await this.getApp(state, profile, profile.appId);
+          } catch (error) {
+            if (!(error instanceof CliError) || error.code !== "APP_UNAVAILABLE")
+              throw error;
+            delete profile.appId;
+            delete profile.apiKey;
+            delete profile.pendingKey;
+            await this.storage.write(state);
+          }
+        }
+        if (!app) {
+          app = this.matchApp(await this.apps(state, profile));
+          if (!app) {
+            if (profile.pendingApp && !options.retryUncertain)
+              throw this.uncertain("app");
+            profile.pendingApp = true;
+            await this.storage.write(state);
+            try {
+              const created = await this.authorized(
+                state,
+                profile,
+                (token) => this.client.request("/v1/apps", {
+                  token,
+                  body: { name: defaultAppName }
+                })
+              );
+              profile.appId = string(created, "appId");
+              delete profile.pendingApp;
+              await this.storage.write(state);
+              reused = false;
+              app = await this.getApp(state, profile, profile.appId);
+            } catch (error) {
+              if (profile.appId) throw error;
+              if (this.definiteRejection(error)) {
+                delete profile.pendingApp;
+                await this.storage.write(state);
+                throw error;
+              }
+              app = this.matchApp(await this.apps(state, profile));
+              if (!app) throw this.uncertain("app");
+            }
+          }
+          profile.appId = app.appId;
+          delete profile.pendingApp;
+          await this.storage.write(state);
+        }
+      }
+      if (!app) throw invalidResponse();
+      const selectKey = (candidate) => {
+        const cached = candidate.keys.find(
+          (key2) => key2.value === profile.apiKey
+        );
+        return cached?.value ?? [...candidate.keys].sort(
+          (a, b) => a.createdAt.localeCompare(b.createdAt) || hash(a.value).localeCompare(hash(b.value))
+        )[0]?.value;
+      };
+      let key = selectKey(app);
+      if (!key) {
+        if (profile.pendingKey && !options.retryUncertain)
+          throw this.uncertain("key");
+        profile.pendingKey = true;
+        await this.storage.write(state);
+        try {
+          const response = await this.authorized(
+            state,
+            profile,
+            (token) => this.client.request(
+              `/v1/apps/${encodeURIComponent(app.appId)}/api-keys`,
+              { token, body: { appId: app.appId } }
+            )
+          );
+          key = string(object(response.apiKey), "apiKey");
+        } catch (error) {
+          if (this.definiteRejection(error)) {
+            delete profile.pendingKey;
+            await this.storage.write(state);
+            throw error;
+          }
+          key = selectKey(await this.getApp(state, profile, app.appId));
+          if (!key) throw this.uncertain("key");
+        }
+      }
+      profile.apiKey = key;
+      delete profile.pendingKey;
+      await this.storage.write(state);
+      return { userId: profile.userId, appId: app.appId, reused };
+    });
+  }
+  uncertain(kind) {
+    return new CliError(
+      "BOOTSTRAP_UNCERTAIN",
+      `Studio may have created the ${kind}, but it is not visible yet.`,
+      {
+        recovery: "Run spatius setup again to reconcile. Only if creation did not complete, use spatius setup --retry-uncertain; it can create a duplicate."
+      }
+    );
+  }
+  definiteRejection(error) {
+    return error instanceof CliError && error.options.status !== void 0 && error.options.status >= 400 && error.options.status < 500 && error.options.status !== 408;
+  }
+  profileKey(userId) {
+    return hash(`${this.originKey}
+${userId}`);
+  }
+  current(state, required = true) {
+    const key = state.active[this.originKey];
+    const profile = key ? state.profiles[key] : void 0;
+    if (!profile) {
+      if (required) throw requireLogin();
+      return void 0;
+    }
+    if (profile.consoleOrigin !== this.consoleOrigin || profile.studioOrigin !== this.studioOrigin || this.profileKey(profile.userId) !== key)
+      throw new CliError(
+        "AUTH_STATE_INVALID",
+        "The saved login profile does not match this environment."
+      );
+    if (required && profile.refreshPending) throw relogin();
+    if (required && (!profile.accessToken || !profile.refreshToken))
+      throw requireLogin();
+    return profile;
+  }
+  summary(profile) {
+    return {
+      authenticated: true,
+      userId: profile.userId,
+      profileKey: this.profileKey(profile.userId),
+      ...profile.appId ? { appId: profile.appId } : {},
+      expiresAt: profile.expiresAt
+    };
+  }
+  async refresh(state, profile) {
+    if (profile.refreshPending) throw relogin();
+    if (!profile.refreshToken) throw requireLogin();
+    profile.refreshPending = true;
+    await this.storage.write(state);
+    try {
+      const response = await this.client.request("/v1/cli/auth/token:refresh", {
+        body: { refreshToken: profile.refreshToken }
+      });
+      applyTokens(profile, response.token);
+      await this.storage.write(state);
+    } catch {
+      profile.refreshPending = true;
+      await this.storage.write(state);
+      throw relogin();
+    }
+  }
+  async ensureToken(state, profile) {
+    if (profile.refreshPending) throw relogin();
+    if (!profile.accessToken || !profile.refreshToken) throw requireLogin();
+    const expiry = Date.parse(profile.expiresAt ?? "");
+    if (!Number.isFinite(expiry) || expiry <= Date.now() + 6e4)
+      await this.refresh(state, profile);
+  }
+  async authorized(state, profile, operation) {
+    await this.ensureToken(state, profile);
+    try {
+      return await operation(profile.accessToken);
+    } catch (error) {
+      if (!(error instanceof CliError) || error.options.status !== 401)
+        throw error;
+      await this.refresh(state, profile);
+      return operation(profile.accessToken);
+    }
+  }
+  async verifyIdentity(state, profile) {
+    let response;
+    try {
+      response = await this.authorized(
+        state,
+        profile,
+        (token) => this.client.request("/v1/auth/me", { token })
+      );
+    } catch (error) {
+      if (error instanceof CliError && error.options.status === 404)
+        throw requireLogin();
+      throw error;
+    }
+    if (string(object(response.user), "id") !== profile.userId)
+      throw new CliError(
+        "AUTH_IDENTITY_MISMATCH",
+        "Studio returned a different account for the saved login.",
+        { recovery: "Run spatius auth logout, then spatius auth login." }
+      );
+  }
+  async getApp(state, profile, appId) {
+    try {
+      const response = await this.authorized(
+        state,
+        profile,
+        (token) => this.client.request(`/v1/apps/${encodeURIComponent(appId)}`, { token })
+      );
+      const app = parseApp(response.app);
+      if (app.appId !== appId) throw invalidResponse();
+      return app;
+    } catch (error) {
+      if (error instanceof CliError && error.options.status === 404)
+        throw new CliError(
+          "APP_UNAVAILABLE",
+          "The selected app does not exist or does not belong to this Studio account.",
+          {
+            recovery: "Run spatius apps list, then spatius setup --app-id <APP_ID>."
+          }
+        );
+      throw error;
+    }
+  }
+  async apps(state, profile) {
+    const result = /* @__PURE__ */ new Map();
+    const seen = /* @__PURE__ */ new Set();
+    let pageToken = "";
+    do {
+      const query = new URLSearchParams({ "pagination.pageSize": "100" });
+      if (pageToken) query.set("pagination.pageToken", pageToken);
+      const response = await this.authorized(
+        state,
+        profile,
+        (token) => this.client.request(`/v1/apps?${query}`, { token })
+      );
+      const apps = response.apps === void 0 ? [] : response.apps;
+      if (!Array.isArray(apps)) throw invalidResponse();
+      for (const raw of apps) {
+        const app = parseApp(raw);
+        result.set(app.appId, app);
+      }
+      const pagination = response.pagination === void 0 ? {} : object(response.pagination);
+      if (pagination.nextPageToken !== void 0 && typeof pagination.nextPageToken !== "string")
+        throw invalidResponse();
+      pageToken = pagination.nextPageToken ?? "";
+      if (pageToken && (seen.has(pageToken) || seen.size >= 1e3))
+        throw invalidResponse();
+      seen.add(pageToken);
+    } while (pageToken);
+    return [...result.values()];
+  }
+  matchApp(apps) {
+    const matches = apps.filter((app) => app.name === defaultAppName).sort(
+      (a, b) => a.createdAt.localeCompare(b.createdAt) || a.appId.localeCompare(b.appId)
+    );
+    if (matches.length > 1)
+      throw new CliError(
+        "APP_SELECTION_REQUIRED",
+        "More than one Spatius CLI app exists for this account.",
+        {
+          details: { apps: matches.map(safeApp) },
+          recovery: "Choose an app explicitly with spatius setup --app-id <APP_ID>."
+        }
+      );
+    return matches[0];
+  }
+};
+
+// src/workflows/index.ts
+import { createHash as createHash4, randomUUID as randomUUID3 } from "crypto";
+import { open as open4, mkdir as mkdir3, link, rename as rename3, unlink as unlink2, stat as stat2 } from "fs/promises";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+import { setTimeout as delay3 } from "timers/promises";
+
+// ../contracts/src/index.ts
+var MIB = 1024 * 1024;
+var PART_SIZE = 8 * MIB;
+var INPUT_TTL_MS = 24 * 60 * 60 * 1e3;
+var UPLOAD_TTL_MS = 60 * 60 * 1e3;
+var DEFAULT_LIMITS = {
+  maxBytes: 2 * 1024 * MIB,
+  uploadsPerDay: 100,
+  unfinished: 10,
+  requestsPerSecond: 10,
+  burst: 20
+};
+var MEDIA = {
+  "avatar-image": { maxBytes: 5 * MIB, types: ["image/jpeg", "image/png"] },
+  audio: {
+    maxBytes: 500 * MIB,
+    types: [
+      "audio/mpeg",
+      "audio/mp3",
+      "audio/wav",
+      "audio/x-wav",
+      "audio/wave",
+      "audio/vnd.wave",
+      "audio/mp4",
+      "audio/x-m4a",
+      "audio/aac",
+      "audio/ogg"
+    ]
+  },
+  background: {
+    maxBytes: 50 * MIB,
+    types: ["image/png", "image/jpeg", "image/webp"]
+  }
+};
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function validMedia(kind, contentType, size) {
+  return Number.isSafeInteger(size) && size > 0 && size <= MEDIA[kind].maxBytes && MEDIA[kind].types.includes(contentType);
+}
+function matchesMediaSignature(type, bytes) {
+  const ascii = (start, length) => String.fromCharCode(...bytes.subarray(start, start + length));
+  if (type === "image/png")
+    return bytes.length >= 8 && [137, 80, 78, 71, 13, 10, 26, 10].every((v, i) => bytes[i] === v);
+  if (type === "image/jpeg")
+    return bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+  if (type === "image/webp")
+    return ascii(0, 4) === "RIFF" && ascii(8, 4) === "WEBP";
+  if (["audio/wav", "audio/x-wav", "audio/wave", "audio/vnd.wave"].includes(type))
+    return ["RIFF", "RF64"].includes(ascii(0, 4)) && ascii(8, 4) === "WAVE";
+  if (type === "audio/ogg") return ascii(0, 4) === "OggS";
+  if (["audio/mp4", "audio/x-m4a"].includes(type))
+    return ascii(4, 4) === "ftyp";
+  if (["audio/mpeg", "audio/mp3"].includes(type))
+    return ascii(0, 3) === "ID3" || bytes[0] === 255 && ((bytes[1] ?? 0) & 224) === 224;
+  if (type === "audio/aac")
+    return bytes[0] === 255 && ((bytes[1] ?? 0) & 246) === 240;
+  return false;
+}
+var VIDEO_DEFAULTS = {
+  width: 1024,
+  height: 1024,
+  fit: "crop",
+  backgroundColor: "#000000",
+  backgroundFit: "cover",
+  leadInSeconds: 0,
+  leadOutSeconds: 0
+};
+
+// src/core/http.ts
+import { setTimeout as delay2 } from "timers/promises";
+async function readJson(response, maxBytes = 2 * 1024 * 1024) {
+  const reader = response.body?.getReader();
+  if (!reader)
+    throw new CliError(
+      "INVALID_RESPONSE",
+      "The service returned an empty response."
+    );
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes)
+        throw new CliError(
+          "INVALID_RESPONSE",
+          "The service response exceeded the size limit."
+        );
+      chunks.push(value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch (error) {
+    await reader.cancel().catch(() => void 0);
+    if (error instanceof CliError) throw error;
+    throw new CliError(
+      "INVALID_RESPONSE",
+      "The service returned invalid JSON."
+    );
+  } finally {
+    reader.releaseLock();
+  }
+}
+function retryAfterSeconds(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  const result = Number.isFinite(seconds) ? seconds : (Date.parse(value) - Date.now()) / 1e3;
+  return Number.isFinite(result) ? Math.max(0, Math.ceil(result)) : void 0;
+}
+async function requestJson(url, options = {}) {
+  const method = options.method ?? "GET";
+  const retries = options.retry ?? method === "GET" ? 3 : 0;
+  const send = options.fetch ?? globalThis.fetch;
+  for (let attempt = 0; ; attempt++) {
+    options.signal?.throwIfAborted();
+    const timeout = AbortSignal.timeout(options.timeoutMs ?? 3e4);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let failure;
+    try {
+      const response = await send(url, {
+        method,
+        headers: {
+          accept: "application/json",
+          ...options.body === void 0 ? {} : { "content-type": "application/json" },
+          ...options.headers
+        },
+        ...options.body === void 0 ? {} : { body: JSON.stringify(options.body) },
+        redirect: "error",
+        signal
+      });
+      if (response.ok) return await readJson(response);
+      const status = response.status;
+      let code = `HTTP_${status}`;
+      try {
+        const data = await readJson(response, 64 * 1024);
+        if (typeof data?.error?.code === "string" && /^[a-zA-Z0-9_.-]{1,100}$/.test(data.error.code))
+          code = data.error.code;
+      } catch {
+      }
+      const requestId = response.headers.get("x-request-id");
+      failure = new CliError(
+        code,
+        `The service rejected the request (HTTP ${status}).`,
+        {
+          status,
+          retryable: status === 429 || status >= 500,
+          retryAfter: retryAfterSeconds(response.headers.get("retry-after")),
+          recovery: status === 401 ? "Run spatius auth login or spatius setup to restore credentials." : status === 403 ? "Ask an administrator to verify API access and avatar permissions for this account." : status === 402 ? "Check your Avatar Creations balance in Studio." : status === 409 ? "Reuse the original request input or explicitly start a new operation." : "Inspect the operation state before retrying a creation.",
+          ...requestId && /^[a-zA-Z0-9_-]{1,100}$/.test(requestId) ? { details: { requestId } } : {}
+        }
+      );
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      failure = error instanceof CliError ? error : new CliError(
+        "NETWORK_ERROR",
+        "The service request did not complete.",
+        {
+          retryable: true,
+          recovery: "Check connectivity. Resume a saved creation instead of creating again."
+        }
+      );
+    }
+    if (attempt >= retries || !failure.options.retryable) throw failure;
+    const waitSeconds = failure.options.retryAfter ?? Math.min(8, 2 ** attempt);
+    if (waitSeconds > 30) throw failure;
+    await delay2(waitSeconds * 1e3, void 0, { signal: options.signal });
+  }
+}
+
+// src/client/media.ts
+var MediaClient = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async request(path, method = "GET", body, timeoutMs = 3e4, signal = this.options.signal) {
+    try {
+      return await requestJson(`${this.options.origin}${path}`, {
+        method,
+        body,
+        headers: { authorization: `Bearer ${await this.options.token()}` },
+        fetch: this.options.fetch,
+        signal,
+        retry: method === "GET",
+        timeoutMs
+      });
+    } catch (error) {
+      if (error instanceof CliError && error.code === "upload_busy")
+        error.options.retryable = true;
+      throw error;
+    }
+  }
+  create(body) {
+    return this.request("/v1/uploads", "POST", body);
+  }
+  get(id, signal) {
+    return this.request(
+      `/v1/uploads/${id}`,
+      "GET",
+      void 0,
+      3e4,
+      signal ?? this.options.signal
+    );
+  }
+  complete(id) {
+    return this.request(
+      `/v1/uploads/${id}/complete`,
+      "POST",
+      {},
+      3e5
+    );
+  }
+  abort(id) {
+    return this.request(`/v1/uploads/${id}`, "DELETE");
+  }
+  async part(id, number, bytes, sha256) {
+    const signal = AbortSignal.any([
+      AbortSignal.timeout(3e5),
+      ...this.options.signal ? [this.options.signal] : []
+    ]);
+    let response;
+    try {
+      response = await (this.options.fetch ?? fetch)(
+        `${this.options.origin}/v1/uploads/${id}/parts/${number}`,
+        {
+          method: "PUT",
+          headers: {
+            authorization: `Bearer ${await this.options.token()}`,
+            "content-type": "application/octet-stream",
+            "content-length": String(bytes.byteLength),
+            "x-content-sha256": sha256
+          },
+          body: bytes,
+          redirect: "error",
+          signal
+        }
+      );
+    } catch {
+      this.options.signal?.throwIfAborted();
+      throw new CliError(
+        "UPLOAD_TRANSPORT_ERROR",
+        "The upload part response was not received.",
+        { retryable: true }
+      );
+    }
+    const text = await boundedText(response);
+    if (!response.ok) {
+      let code = "UPLOAD_FAILED";
+      try {
+        const data = JSON.parse(text);
+        if (typeof data?.error?.code === "string" && /^[a-zA-Z0-9_]+$/.test(data.error.code))
+          code = data.error.code;
+      } catch {
+      }
+      const retryAfter = Number(response.headers.get("retry-after"));
+      throw new CliError(
+        code,
+        "The temporary media service rejected the upload part.",
+        {
+          status: response.status,
+          retryable: response.status === 429 || response.status >= 500 || code === "upload_busy",
+          ...Number.isFinite(retryAfter) && retryAfter > 0 ? { retryAfter } : {}
+        }
+      );
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new CliError(
+        "INVALID_RESPONSE",
+        "The upload service returned an invalid response.",
+        { retryable: true }
+      );
+    }
+  }
+};
+async function boundedText(response, max = 1024 * 1024) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (; ; ) {
+      const next = await reader.read();
+      if (next.done) break;
+      size += next.value.byteLength;
+      if (size > max)
+        throw new CliError(
+          "INVALID_RESPONSE",
+          "The service response exceeded its size limit."
+        );
+      chunks.push(next.value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+  } finally {
+    await reader.cancel().catch(() => {
+    });
+  }
+}
+
+// src/workflows/state.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import {
+  mkdir as mkdir2,
+  readFile as readFile2,
+  rename as rename2,
+  unlink,
+  writeFile,
+  chmod as chmod2,
+  open as open2
+} from "fs/promises";
+import { join as join2 } from "path";
+function identifier(value, label = "ID") {
+  if (!UUID_PATTERN.test(value))
+    throw new CliError("INVALID_ARGUMENT", `${label} must be a UUID.`, {
+      exitCode: 2
+    });
+  return value.toLowerCase();
+}
+var StateStore = class {
+  directory;
+  constructor(root, profileKey) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(profileKey))
+      throw new CliError("INVALID_PROFILE", "Invalid account profile.");
+    this.directory = join2(root, "operations", profileKey);
+  }
+  async initialize() {
+    await mkdir2(this.directory, { recursive: true, mode: 448 });
+    await chmod2(this.directory, 448);
+  }
+  async read(id) {
+    try {
+      return JSON.parse(
+        await readFile2(join2(this.directory, `${identifier(id)}.json`), "utf8")
+      );
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (error.code !== "ENOENT")
+        throw new CliError(
+          "OPERATION_UNREADABLE",
+          "The saved operation cannot be read. Preserve it for recovery; do not submit another creation automatically."
+        );
+      throw new CliError(
+        "OPERATION_NOT_FOUND",
+        "No saved operation exists for this account and ID.",
+        {
+          recovery: "Use the operation ID returned by the original command under the same Studio account."
+        }
+      );
+    }
+  }
+  async write(id, value) {
+    await this.initialize();
+    const target = join2(this.directory, `${identifier(id)}.json`);
+    const temporary = `${target}.${randomUUID2()}.tmp`;
+    try {
+      const handle = await open2(temporary, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify(value));
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename2(temporary, target);
+      if (process.platform !== "win32") {
+        const directory = await open2(this.directory, "r");
+        try {
+          await directory.sync();
+        } finally {
+          await directory.close();
+        }
+      }
+    } finally {
+      await unlink(temporary).catch(() => {
+      });
+    }
+  }
+  async locked(id, run) {
+    await this.initialize();
+    const path = join2(this.directory, `${identifier(id)}.lock`);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await writeFile(path, String(process.pid), { mode: 384, flag: "wx" });
+        break;
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        let alive = true;
+        try {
+          const pid = Number(await readFile2(path, "utf8"));
+          if (pid > 0) process.kill(pid, 0);
+        } catch (cause) {
+          if (cause.code === "ESRCH") alive = false;
+        }
+        if (alive || attempt > 0)
+          throw new CliError(
+            "OPERATION_BUSY",
+            "This operation is already running in another process.",
+            { retryable: true }
+          );
+        await unlink(path).catch(() => {
+        });
+      }
+    }
+    try {
+      return await run();
+    } finally {
+      await unlink(path).catch(() => {
+      });
+    }
+  }
+};
+
+// src/workflows/media.ts
+import { createHash as createHash3 } from "crypto";
+import { open as open3 } from "fs/promises";
+import { resolve } from "path";
+function sourceUrl(input) {
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) return void 0;
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new CliError("INVALID_ARGUMENT", "The source URL is invalid.", {
+      exitCode: 2
+    });
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || input.length > 4096 || /\s/.test(input)) {
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      "Sources require HTTP(S) URLs without embedded credentials, at most 4096 characters.",
+      { exitCode: 2 }
+    );
+  }
+  return input;
+}
+async function inspectMedia(file, kind, signal) {
+  const path = resolve(file);
+  const handle = await open3(path, "r").catch(() => {
+    throw new CliError("FILE_UNREADABLE", "The input file cannot be read.", {
+      exitCode: 2
+    });
+  });
+  try {
+    const stat3 = await handle.stat();
+    if (!stat3.isFile() || stat3.size <= 0 || stat3.size > MEDIA[kind].maxBytes) {
+      throw new CliError(
+        "INVALID_MEDIA",
+        `Input must be a nonempty regular file of at most ${MEDIA[kind].maxBytes} bytes.`,
+        { exitCode: 2 }
+      );
+    }
+    const header = Buffer.alloc(32);
+    const first = await handle.read(header, 0, header.length, 0);
+    const types = [...MEDIA[kind].types].sort(
+      (a, b) => Number(b === "audio/aac") - Number(a === "audio/aac")
+    );
+    const contentType = types.find(
+      (type) => matchesMediaSignature(type, header.subarray(0, first.bytesRead))
+    );
+    if (!contentType || !validMedia(kind, contentType, stat3.size))
+      throw new CliError(
+        "UNSUPPORTED_MEDIA",
+        "The input bytes do not match a supported media type.",
+        { exitCode: 2 }
+      );
+    const hash2 = createHash3("sha256");
+    const buffer = Buffer.alloc(1024 * 1024);
+    let offset = 0;
+    while (offset < stat3.size) {
+      signal?.throwIfAborted();
+      const { bytesRead } = await handle.read(
+        buffer,
+        0,
+        Math.min(buffer.length, stat3.size - offset),
+        offset
+      );
+      if (!bytesRead)
+        throw new CliError(
+          "INPUT_CHANGED",
+          "The input file changed while being read."
+        );
+      hash2.update(buffer.subarray(0, bytesRead));
+      offset += bytesRead;
+    }
+    const after = await handle.stat();
+    if (after.size !== stat3.size || after.mtimeMs !== stat3.mtimeMs)
+      throw new CliError(
+        "INPUT_CHANGED",
+        "The input file changed while being read."
+      );
+    return { path, size: stat3.size, contentType, sha256: hash2.digest("hex") };
+  } finally {
+    await handle.close();
+  }
+}
+
+// src/workflows/index.ts
+var Workflows = class {
+  constructor(options) {
+    this.options = options;
+    this.media = new MediaClient({
+      origin: options.mediaOrigin.replace(/\/$/, ""),
+      token: () => options.auth.accessToken(),
+      fetch: options.fetch,
+      signal: options.signal
+    });
+  }
+  options;
+  media;
+  progress(event) {
+    this.options.onProgress?.(event);
+  }
+  async context() {
+    const identity = await this.options.auth.identity();
+    return {
+      ...identity,
+      store: new StateStore(
+        this.options.auth.stateDirectory(),
+        identity.profileKey
+      )
+    };
+  }
+  checkScope(journal, userId) {
+    if (journal.userId !== userId || journal.consoleOrigin !== this.options.consoleOrigin || journal.mediaOrigin !== this.options.mediaOrigin) {
+      throw new CliError(
+        "OPERATION_SCOPE_MISMATCH",
+        "The saved operation belongs to another account or service environment."
+      );
+    }
+  }
+  async upload(file, options) {
+    const local = await inspectMedia(file, options.kind, this.options.signal);
+    const { store, userId } = await this.context();
+    const id = options.resume ? identifier(options.resume, "Upload operation ID") : randomUUID3();
+    return store.locked(id, async () => {
+      let journal;
+      if (options.resume) {
+        try {
+          journal = await store.read(id);
+        } catch (error) {
+          if (!(error instanceof CliError) || error.code !== "OPERATION_NOT_FOUND")
+            throw error;
+          const remote = await this.media.get(id);
+          journal = {
+            version: 1,
+            type: "upload",
+            id,
+            userId,
+            consoleOrigin: this.options.consoleOrigin,
+            mediaOrigin: this.options.mediaOrigin,
+            kind: options.kind,
+            file: local,
+            upload: remote
+          };
+        }
+        this.checkScope(journal, userId);
+        if (journal.type !== "upload" || journal.kind !== options.kind || journal.file.sha256 !== local.sha256 || journal.file.size !== local.size || journal.file.contentType !== local.contentType) {
+          throw new CliError(
+            "INPUT_CHANGED",
+            "Upload resume requires the original file bytes and media kind."
+          );
+        }
+      } else {
+        journal = {
+          version: 1,
+          type: "upload",
+          id,
+          userId,
+          consoleOrigin: this.options.consoleOrigin,
+          mediaOrigin: this.options.mediaOrigin,
+          kind: options.kind,
+          file: local
+        };
+        await store.write(id, journal);
+      }
+      this.progress({ stage: "uploading", operationId: id });
+      try {
+        let remote = journal.upload ? await this.media.get(journal.upload.id) : await this.media.create({
+          requestId: id,
+          kind: options.kind,
+          size: local.size,
+          contentType: local.contentType,
+          sha256: local.sha256
+        });
+        journal.upload = remote;
+        await store.write(id, journal);
+        const validate = () => {
+          if (remote.sha256 !== local.sha256 || remote.size !== local.size || remote.kind !== options.kind || remote.partSize !== PART_SIZE)
+            throw new CliError(
+              "INVALID_RESPONSE",
+              "The upload service returned incompatible file metadata."
+            );
+          if (["expired", "aborted", "aborting"].includes(remote.status))
+            throw new CliError(
+              "UPLOAD_EXPIRED",
+              "This upload is no longer resumable.",
+              {
+                recovery: "Start a new upload. Do not replace input URLs in an uncertain video submission."
+              }
+            );
+        };
+        validate();
+        remote = await this.settleUpload(remote, id);
+        validate();
+        journal.upload = remote;
+        await store.write(id, journal);
+        if (remote.status === "completed")
+          return this.completedUpload(remote, id);
+        const handle = await open4(local.path, "r");
+        try {
+          for (let number = 1; number <= Math.ceil(local.size / PART_SIZE); number++) {
+            if (remote.status === "completed") break;
+            if (remote.acceptedParts.includes(number)) continue;
+            const length = Math.min(
+              PART_SIZE,
+              local.size - (number - 1) * PART_SIZE
+            );
+            const bytes = Buffer.alloc(length);
+            let read = 0;
+            while (read < length) {
+              const result = await handle.read(
+                bytes,
+                read,
+                length - read,
+                (number - 1) * PART_SIZE + read
+              );
+              if (!result.bytesRead)
+                throw new CliError(
+                  "INPUT_CHANGED",
+                  "The file changed during upload."
+                );
+              read += result.bytesRead;
+            }
+            const hash2 = createHash4("sha256").update(bytes).digest("hex");
+            for (let attempt = 0; ; attempt++) {
+              try {
+                remote = await this.media.part(remote.id, number, bytes, hash2);
+                break;
+              } catch (error) {
+                if (!(error instanceof CliError) || !error.options.retryable || (error.options.retryAfter ?? 0) > 30 || attempt >= 4)
+                  throw error;
+                await this.pause(
+                  Math.max(
+                    error.options.retryAfter ?? 0,
+                    Math.min(2 ** attempt, 15)
+                  ) * 1e3
+                );
+                remote = await this.settleUpload(
+                  await this.media.get(remote.id),
+                  id
+                );
+                validate();
+                if (remote.acceptedParts.includes(number) || remote.status === "completed")
+                  break;
+              }
+            }
+            journal.upload = remote;
+            await store.write(id, journal);
+            this.progress({
+              stage: "uploading",
+              operationId: id,
+              acceptedParts: remote.acceptedParts.length,
+              partCount: remote.partCount
+            });
+          }
+        } finally {
+          await handle.close();
+        }
+        for (let attempt = 0; ; attempt++) {
+          try {
+            remote = remote.status === "completed" ? remote : await this.media.complete(remote.id);
+            remote = await this.settleUpload(remote, id);
+            break;
+          } catch (error) {
+            if (!(error instanceof CliError) || !error.options.retryable || (error.options.retryAfter ?? 0) > 30 || attempt >= 4)
+              throw error;
+            await this.pause(
+              Math.max(
+                error.options.retryAfter ?? 0,
+                Math.min(2 ** attempt, 15)
+              ) * 1e3
+            );
+            remote = await this.settleUpload(
+              await this.media.get(remote.id),
+              id
+            );
+            validate();
+          }
+        }
+        journal.upload = remote;
+        await store.write(id, journal);
+        return this.completedUpload(remote, id);
+      } catch (error) {
+        throw this.withOperation(error, id, "assets upload");
+      }
+    });
+  }
+  async settleUpload(initial, operationId) {
+    let upload = initial;
+    const expiry = Date.parse(initial.uploadExpiresAt);
+    if (!Number.isFinite(expiry))
+      throw new CliError(
+        "INVALID_RESPONSE",
+        "The upload service returned an invalid transfer deadline."
+      );
+    const serverDeadline = expiry + (initial.status === "finalizing" ? 3e5 : 0);
+    const deadline = Math.min(Date.now() + 3e5, serverDeadline);
+    const waiting = () => ["initializing", "finalizing"].includes(upload.status);
+    if (waiting() && deadline <= Date.now())
+      throw new CliError(
+        "UPLOAD_EXPIRED",
+        "The upload preparation deadline has expired."
+      );
+    const deadlineSignal = AbortSignal.timeout(
+      Math.max(1, Math.ceil(deadline - Date.now()))
+    );
+    const signal = AbortSignal.any([
+      deadlineSignal,
+      ...this.options.signal ? [this.options.signal] : []
+    ]);
+    for (let attempt = 0; waiting(); attempt++) {
+      this.progress({ stage: upload.status, operationId, uploadId: upload.id });
+      try {
+        const interval = Math.min(15e3, 1e3 * 2 ** Math.min(attempt, 4));
+        const remaining = deadline - Date.now();
+        await delay3(Math.min(interval, Math.max(1, remaining)), void 0, {
+          signal
+        });
+        if (remaining <= interval) {
+          if (deadline === serverDeadline)
+            throw new CliError(
+              "UPLOAD_EXPIRED",
+              "The upload preparation deadline has expired."
+            );
+          throw new CliError(
+            "UPLOAD_WAIT_TIMEOUT",
+            "The upload is still initializing or verifying. Its saved state can be resumed.",
+            { retryable: true }
+          );
+        }
+        upload = await this.media.get(initial.id, signal);
+      } catch (error) {
+        this.options.signal?.throwIfAborted();
+        if (deadlineSignal.aborted && Date.now() >= serverDeadline)
+          throw new CliError(
+            "UPLOAD_EXPIRED",
+            "The upload preparation deadline has expired."
+          );
+        if (deadlineSignal.aborted)
+          throw new CliError(
+            "UPLOAD_WAIT_TIMEOUT",
+            "The upload is still initializing or verifying. Its saved state can be resumed.",
+            { retryable: true }
+          );
+        throw error;
+      }
+      if (upload.id !== initial.id || upload.sha256 !== initial.sha256 || upload.size !== initial.size || upload.kind !== initial.kind || upload.contentType !== initial.contentType || upload.partSize !== PART_SIZE) {
+        throw new CliError(
+          "INVALID_RESPONSE",
+          "The upload identity changed while waiting."
+        );
+      }
+    }
+    if (["expired", "aborted", "aborting"].includes(upload.status) || upload.status === "uploading" && Date.parse(upload.uploadExpiresAt) <= Date.now()) {
+      throw new CliError(
+        "UPLOAD_EXPIRED",
+        "This upload is no longer resumable.",
+        {
+          recovery: "Start a new upload. Do not replace input URLs in an uncertain video submission."
+        }
+      );
+    }
+    if (!["uploading", "completed"].includes(upload.status))
+      throw new CliError(
+        "INVALID_RESPONSE",
+        "The upload service returned an invalid status."
+      );
+    return upload;
+  }
+  completedUpload(upload, operationId) {
+    if (upload.status !== "completed" || !upload.url || !upload.expiresAt || !Number.isFinite(Date.parse(upload.expiresAt)) || Date.parse(upload.expiresAt) <= Date.now())
+      throw new CliError(
+        "UPLOAD_NOT_READY",
+        "The upload is not ready for use.",
+        { retryable: true }
+      );
+    const source = sourceUrl(upload.url);
+    if (!source)
+      throw new CliError(
+        "INVALID_RESPONSE",
+        "The upload service returned an invalid file URL."
+      );
+    const parsed = new URL(source);
+    const localHTTP = parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+    if (parsed.origin !== new URL(this.options.mediaOrigin).origin || parsed.protocol !== "https:" && !localHTTP) {
+      throw new CliError(
+        "INVALID_RESPONSE",
+        "The upload file URL must use the configured media service over HTTPS (or loopback HTTP for local development)."
+      );
+    }
+    return { ...upload, operationId };
+  }
+  getUpload(id) {
+    return this.media.get(identifier(id, "Upload ID"));
+  }
+  abortUpload(id) {
+    return this.media.abort(identifier(id, "Upload ID"));
+  }
+  withOperation(error, operationId, command) {
+    const original = error instanceof CliError ? error : new CliError(
+      "OPERATION_FAILED",
+      "The operation stopped before completion."
+    );
+    const inherited = original.options.details;
+    const plainDetails = inherited !== null && typeof inherited === "object" && (Object.getPrototypeOf(inherited) === Object.prototype || Object.getPrototypeOf(inherited) === null) ? inherited : {};
+    const details = { ...plainDetails, operationId };
+    const recovery = command === "assets upload" ? `Run spatius assets upload with the original file and --kind, adding --resume ${operationId}.` : `Resume with spatius ${command} --resume ${operationId}.`;
+    if (this.options.signal?.aborted)
+      return new CliError(
+        "INTERRUPTED",
+        "Operation interrupted; its progress has been saved.",
+        {
+          exitCode: 130,
+          details,
+          recovery
+        }
+      );
+    return new CliError(original.code, original.message, {
+      ...original.options,
+      details,
+      recovery: original.options.recovery ?? recovery
+    });
+  }
+  async input(value, kind) {
+    if (!value)
+      throw new CliError("INVALID_ARGUMENT", `A ${kind} input is required.`, {
+        exitCode: 2
+      });
+    const url = sourceUrl(value);
+    return url ? { value, kind, url } : {
+      value,
+      kind,
+      file: await inspectMedia(value, kind, this.options.signal),
+      uploadOperationId: randomUUID3()
+    };
+  }
+  videoSettings(video = {}) {
+    const settings = { ...VIDEO_DEFAULTS, ...video };
+    for (const dimension of [settings.width, settings.height])
+      if (!Number.isInteger(dimension) || dimension < 64 || dimension > 1920 || dimension % 2)
+        throw new CliError(
+          "INVALID_ARGUMENT",
+          "Video dimensions must be even integers from 64 to 1920.",
+          { exitCode: 2 }
+        );
+    if (settings.width * settings.height > 2073600 || !["crop", "contain"].includes(settings.fit) || !["cover", "contain", "stretch"].includes(settings.backgroundFit) || !/^#[0-9a-f]{6}$/i.test(settings.backgroundColor))
+      throw new CliError(
+        "INVALID_ARGUMENT",
+        "Invalid video presentation settings.",
+        { exitCode: 2 }
+      );
+    for (const duration of [settings.leadInSeconds, settings.leadOutSeconds])
+      if (!Number.isFinite(duration) || duration < 0 || duration > 60)
+        throw new CliError(
+          "INVALID_ARGUMENT",
+          "Lead-in and lead-out must be finite seconds from 0 to 60.",
+          { exitCode: 2 }
+        );
+    settings.backgroundColor = settings.backgroundColor.toLowerCase();
+    return settings;
+  }
+  name(name) {
+    if (name !== void 0 && (!name.trim() || name.length > 128))
+      throw new CliError(
+        "INVALID_ARGUMENT",
+        "Name must contain 1 to 128 characters.",
+        { exitCode: 2 }
+      );
+    return name;
+  }
+  async createAvatar(options) {
+    if (options.resume) {
+      if (options.image !== void 0 || options.name !== void 0 || options.dryRun)
+        throw new CliError(
+          "INVALID_ARGUMENT",
+          "Resume cannot be combined with new inputs or dry-run.",
+          { exitCode: 2 }
+        );
+      return this.create("avatar", options);
+    }
+    const inputs = {
+      imageUrl: await this.input(options.image, "avatar-image")
+    };
+    return this.create("avatar", options, inputs, {
+      ...this.name(options.name) !== void 0 ? { name: options.name } : {}
+    });
+  }
+  async createVideo(options) {
+    if (options.resume) {
+      if ([
+        options.avatarId,
+        options.audio,
+        options.background,
+        options.name,
+        options.requestId
+      ].some((value) => value !== void 0) || options.video && Object.keys(options.video).length > 0 || options.dryRun)
+        throw new CliError(
+          "INVALID_ARGUMENT",
+          "Resume cannot be combined with new inputs or dry-run.",
+          { exitCode: 2 }
+        );
+      return this.create("video", options);
+    }
+    if (!options.avatarId)
+      throw new CliError("INVALID_ARGUMENT", "An Avatar ID is required.", {
+        exitCode: 2
+      });
+    const avatarId = identifier(options.avatarId, "Avatar ID");
+    const inputs = {
+      audioUrl: await this.input(options.audio, "audio")
+    };
+    if (options.background)
+      inputs.backgroundUrl = await this.input(options.background, "background");
+    return this.create("video", options, inputs, {
+      avatarId,
+      requestId: options.requestId ? identifier(options.requestId, "Request ID") : randomUUID3(),
+      video: this.videoSettings(options.video),
+      ...this.name(options.name) !== void 0 ? { name: options.name } : {}
+    });
+  }
+  async create(kind, options, inputs, body) {
+    if (options.dryRun)
+      return {
+        dryRun: true,
+        method: "POST",
+        path: `/v1/open/${kind === "avatar" ? "avatars" : "videos"}`,
+        body,
+        inputs: Object.fromEntries(
+          Object.entries(inputs ?? {}).map(([key, input]) => [
+            key,
+            input.file ? {
+              kind: input.kind,
+              path: input.file.path,
+              size: input.file.size,
+              contentType: input.file.contentType,
+              sha256: input.file.sha256,
+              action: "temporary_upload"
+            } : { kind: input.kind, action: "use_supplied_url" }
+          ])
+        )
+      };
+    const { store, userId } = await this.context();
+    const credentials = await this.options.auth.credentials();
+    const id = options.resume ? identifier(options.resume, "Operation ID") : kind === "video" ? identifier(String(body.requestId), "Request ID") : randomUUID3();
+    return store.locked(id, async () => {
+      let journal;
+      let existing;
+      try {
+        existing = await store.read(id);
+      } catch (error) {
+        if (!(error instanceof CliError) || error.code !== "OPERATION_NOT_FOUND" || options.resume)
+          throw error;
+      }
+      if (existing) {
+        journal = existing;
+        this.checkScope(journal, userId);
+        if (journal.type !== kind || journal.appId !== credentials.appId)
+          throw new CliError(
+            "OPERATION_SCOPE_MISMATCH",
+            "Resume requires the original command and App ID."
+          );
+        if (!options.resume && inputFingerprint(journal.body, journal.inputs) !== inputFingerprint(body, inputs)) {
+          throw new CliError(
+            "REQUEST_ID_CONFLICT",
+            "This request ID is already associated with different inputs.",
+            {
+              status: 409,
+              recovery: "Reuse the original inputs, or choose a new request ID for a separate render."
+            }
+          );
+        }
+      } else {
+        journal = {
+          version: 1,
+          type: kind,
+          id,
+          userId,
+          appId: credentials.appId,
+          consoleOrigin: this.options.consoleOrigin,
+          mediaOrigin: this.options.mediaOrigin,
+          state: "preparing",
+          inputs,
+          body
+        };
+        await store.write(id, journal);
+      }
+      this.progress({ stage: journal.state, operationId: id });
+      try {
+        if (journal.state === "accepted" && journal.job)
+          return options.wait ? {
+            operationId: id,
+            ...await this.waitJob(kind, journal.job.jobId, options)
+          } : { operationId: id, ...journal.job };
+        if (journal.state === "submitting" && kind === "avatar")
+          throw new CliError(
+            "SUBMISSION_UNCERTAIN",
+            "Avatar creation may already have been accepted. It cannot safely be submitted again automatically.",
+            {
+              recovery: "Inspect spatius avatars jobs list and match the previous creation before starting another avatar."
+            }
+          );
+        for (const [field, input] of Object.entries(journal.inputs)) {
+          if (!input.url) {
+            if (!input.file || !input.uploadOperationId)
+              throw new CliError(
+                "INVALID_OPERATION",
+                "The saved input is incomplete."
+              );
+            const current = await inspectMedia(
+              input.file.path,
+              input.kind,
+              this.options.signal
+            );
+            if (current.sha256 !== input.file.sha256 || current.size !== input.file.size)
+              throw new CliError(
+                "INPUT_CHANGED",
+                "The local input changed since this operation started."
+              );
+            let exists = true;
+            try {
+              await store.read(input.uploadOperationId);
+            } catch (error) {
+              if (error instanceof CliError && error.code === "OPERATION_NOT_FOUND")
+                exists = false;
+              else throw error;
+            }
+            if (!exists)
+              await store.write(input.uploadOperationId, {
+                version: 1,
+                type: "upload",
+                id: input.uploadOperationId,
+                userId,
+                consoleOrigin: this.options.consoleOrigin,
+                mediaOrigin: this.options.mediaOrigin,
+                kind: input.kind,
+                file: input.file
+              });
+            const uploaded = await this.upload(input.file.path, {
+              kind: input.kind,
+              resume: input.uploadOperationId
+            });
+            input.url = uploaded.url;
+            input.expiresAt = uploaded.expiresAt;
+            journal.body[field] = input.url;
+            await store.write(id, journal);
+          } else journal.body[field] = input.url;
+          if (input.expiresAt && Date.parse(input.expiresAt) <= Date.now() + 30 * 6e4)
+            throw new CliError(
+              "SOURCE_EXPIRED",
+              "A saved input URL no longer covers the preparation window.",
+              {
+                recovery: journal.state === "submitting" ? "Inspect existing video jobs. Do not substitute another URL under this request ID." : "Start a new operation to upload fresh inputs."
+              }
+            );
+        }
+        journal.state = "ready";
+        await store.write(id, journal);
+        journal.state = "submitting";
+        await store.write(id, journal);
+        const attempts = kind === "video" ? 3 : 1;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+          try {
+            const result = await this.consoleRequest(
+              kind === "video" ? "/videos" : "/avatars",
+              "POST",
+              journal.body,
+              false,
+              this.options.signal,
+              { appId: journal.appId, userId: journal.userId }
+            );
+            if (!result.jobId || !UUID_PATTERN.test(result.jobId))
+              throw new CliError(
+                "INVALID_RESPONSE",
+                "Creation response did not include a valid job ID.",
+                { retryable: kind === "video" }
+              );
+            journal.job = result;
+            journal.state = "accepted";
+            await store.write(id, journal);
+            break;
+          } catch (error) {
+            const rejected = error instanceof CliError && error.options.status !== void 0 && error.options.status >= 400 && error.options.status < 500;
+            if (rejected || error instanceof CliError && error.code === "OPERATION_SCOPE_MISMATCH") {
+              journal.state = "ready";
+              await store.write(id, journal);
+            } else if (kind === "avatar") {
+              throw new CliError(
+                "SUBMISSION_UNCERTAIN",
+                "Avatar creation may already have been accepted. Do not submit it again automatically.",
+                {
+                  recovery: "Inspect spatius avatars jobs list and match the previous creation before starting another avatar."
+                }
+              );
+            }
+            if (!(error instanceof CliError) || !error.options.retryable || (error.options.retryAfter ?? 0) > 30 || attempt + 1 >= attempts)
+              throw error;
+            journal.state = "submitting";
+            await store.write(id, journal);
+            await this.pause(
+              Math.max(error.options.retryAfter ?? 0, 2 ** attempt) * 1e3
+            );
+          }
+        }
+        return options.wait ? {
+          operationId: id,
+          ...await this.waitJob(kind, journal.job.jobId, options)
+        } : { operationId: id, ...journal.job };
+      } catch (error) {
+        throw this.withOperation(
+          error,
+          id,
+          `${kind === "avatar" ? "avatars" : "videos"} create`
+        );
+      }
+    });
+  }
+  async consoleRequest(path, method = "GET", body, retry = true, signal = this.options.signal, owner) {
+    const credentials = await this.options.auth.credentials();
+    if (owner) {
+      const identity = await this.options.auth.identity();
+      if (credentials.appId !== owner.appId || identity.userId !== owner.userId || credentials.userId !== void 0 && credentials.userId !== owner.userId)
+        throw new CliError(
+          "OPERATION_SCOPE_MISMATCH",
+          "The active account or App changed while preparing this operation. Resume under the original identity."
+        );
+    }
+    return requestJson(
+      `${this.options.consoleOrigin.replace(/\/$/, "")}/v1/open${path}`,
+      {
+        method,
+        body,
+        headers: {
+          "x-app-id": credentials.appId,
+          "x-api-key": credentials.apiKey
+        },
+        signal,
+        fetch: this.options.fetch,
+        retry: method === "GET" && retry
+      }
+    );
+  }
+  getAvatar(id) {
+    return this.consoleRequest(
+      `/avatars/${identifier(id, "Avatar ID")}`
+    );
+  }
+  listAvatars(options = {}) {
+    return this.consoleRequest(`/avatars${this.query(options)}`);
+  }
+  getJob(kind, id) {
+    return this.consoleRequest(
+      `/${kind}-jobs/${identifier(id, "Job ID")}`
+    );
+  }
+  listJobs(kind, options = {}) {
+    return this.consoleRequest(`/${kind}-jobs${this.query(options)}`);
+  }
+  query(options) {
+    const query = new URLSearchParams();
+    if (options.pageSize !== void 0) {
+      if (!Number.isInteger(options.pageSize) || options.pageSize < 1 || options.pageSize > 100)
+        throw new CliError(
+          "INVALID_ARGUMENT",
+          "Page size must be an integer from 1 to 100.",
+          { exitCode: 2 }
+        );
+      query.set("pagination.pageSize", String(options.pageSize));
+    }
+    if (options.pageToken) query.set("pagination.pageToken", options.pageToken);
+    for (const status of options.statuses ?? []) {
+      if (!["queued", "processing", "succeeded", "failed", "expired"].includes(
+        status
+      ))
+        throw new CliError("INVALID_ARGUMENT", "Invalid job status.", {
+          exitCode: 2
+        });
+      query.append("statuses", status);
+    }
+    return query.size ? `?${query}` : "";
+  }
+  async waitJob(kind, id, options = {}) {
+    identifier(id, "Job ID");
+    const timeout = options.timeout ?? 600;
+    if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 86400)
+      throw new CliError(
+        "INVALID_ARGUMENT",
+        "Timeout must be seconds greater than zero and at most 86400.",
+        { exitCode: 2 }
+      );
+    const deadline = Date.now() + timeout * 1e3;
+    const deadlineSignal = AbortSignal.timeout(Math.ceil(timeout * 1e3));
+    const signal = AbortSignal.any([
+      deadlineSignal,
+      ...this.options.signal ? [this.options.signal] : []
+    ]);
+    for (; ; ) {
+      let detail;
+      try {
+        detail = await this.consoleRequest(
+          `/${kind}-jobs/${id}`,
+          "GET",
+          void 0,
+          true,
+          signal
+        );
+      } catch (error) {
+        if (deadlineSignal.aborted && !this.options.signal?.aborted)
+          throw this.waitTimeout(kind, id);
+        throw error;
+      }
+      const job = detail.job;
+      if (!job || !["queued", "processing", "succeeded", "failed", "expired"].includes(
+        job.status
+      ))
+        throw new CliError(
+          "INVALID_RESPONSE",
+          "The job service returned an invalid status."
+        );
+      this.progress({
+        stage: job.progress?.stage ?? job.status,
+        jobId: id,
+        status: job.status
+      });
+      if (job.status === "succeeded") return detail;
+      if (job.status === "failed" || job.status === "expired")
+        throw new CliError(
+          job.error?.code ?? (job.status === "expired" ? "JOB_EXPIRED" : "JOB_FAILED"),
+          job.error?.message ?? "The job did not succeed.",
+          {
+            retryable: job.error?.retryable ?? false,
+            details: { jobId: id, status: job.status },
+            recovery: "This job is terminal. Inspect its error before deliberately creating another job."
+          }
+        );
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw this.waitTimeout(kind, id);
+      try {
+        await delay3(Math.min(15e3, remaining), void 0, { signal });
+        if (remaining <= 15e3) throw this.waitTimeout(kind, id);
+      } catch {
+        if (this.options.signal?.aborted) this.options.signal.throwIfAborted();
+        throw this.waitTimeout(kind, id);
+      }
+    }
+  }
+  waitTimeout(kind, id) {
+    return new CliError(
+      "WAIT_TIMEOUT",
+      "The job is still running when the wait deadline ended.",
+      {
+        retryable: true,
+        exitCode: 3,
+        details: { jobId: id },
+        recovery: `Continue with spatius ${kind === "avatar" ? "avatars jobs" : "videos"} wait ${id}. The remote job was not cancelled.`
+      }
+    );
+  }
+  async pause(milliseconds) {
+    await delay3(milliseconds, void 0, { signal: this.options.signal });
+  }
+  async download(jobId, options) {
+    const output = resolve2(options.output);
+    const directory = dirname2(output);
+    if (!options.force && await stat2(output).then(
+      () => true,
+      () => false
+    ))
+      throw new CliError(
+        "OUTPUT_EXISTS",
+        "The output file already exists. Use --force to replace it.",
+        { exitCode: 2 }
+      );
+    const detail = await this.getJob("video", jobId);
+    if (detail.job.status !== "succeeded" || !detail.videoUrl || detail.job.expiresAt && Date.parse(detail.job.expiresAt) <= Date.now())
+      throw new CliError(
+        "VIDEO_UNAVAILABLE",
+        "The video is not ready or its output has expired.",
+        { retryable: ["queued", "processing"].includes(detail.job.status) }
+      );
+    if (!sourceUrl(detail.videoUrl))
+      throw new CliError(
+        "INVALID_RESPONSE",
+        "The video service returned an invalid download URL."
+      );
+    const downloadURL = new URL(detail.videoUrl);
+    const consoleURL = new URL(this.options.consoleOrigin);
+    const isLoopback = (hostname) => ["localhost", "127.0.0.1", "[::1]"].includes(hostname);
+    if (downloadURL.protocol !== "https:" && !(downloadURL.protocol === "http:" && isLoopback(downloadURL.hostname) && consoleURL.protocol === "http:" && isLoopback(consoleURL.hostname))) {
+      throw new CliError(
+        "DOWNLOAD_UNAVAILABLE",
+        "The video service returned an insecure output URL.",
+        {
+          retryable: true,
+          recovery: "Request a fresh download link. Only HTTPS output links are supported outside explicitly configured loopback development."
+        }
+      );
+    }
+    await mkdir3(directory, { recursive: true });
+    const temporary = `${output}.${randomUUID3()}.partial`;
+    const handle = await open4(temporary, "wx", 384);
+    let bytes = 0;
+    try {
+      const signal = AbortSignal.any([
+        AbortSignal.timeout(6e5),
+        ...this.options.signal ? [this.options.signal] : []
+      ]);
+      let response;
+      try {
+        response = await (this.options.fetch ?? fetch)(detail.videoUrl, {
+          signal,
+          redirect: "error"
+        });
+      } catch {
+        this.options.signal?.throwIfAborted();
+        throw new CliError(
+          "DOWNLOAD_UNAVAILABLE",
+          "The direct signed video download could not be reached.",
+          {
+            retryable: true,
+            recovery: "Run the download command again to obtain a fresh signed URL. Output redirects are not followed."
+          }
+        );
+      }
+      if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        throw new CliError(
+          "DOWNLOAD_UNAVAILABLE",
+          "The signed video download is unavailable.",
+          {
+            retryable: true,
+            recovery: "Run the download command again to obtain a fresh signed URL."
+          }
+        );
+      }
+      const reader = response.body.getReader();
+      try {
+        for (; ; ) {
+          const next = await reader.read();
+          if (next.done) break;
+          let offset = 0;
+          while (offset < next.value.byteLength) {
+            const result = await handle.write(next.value, offset);
+            offset += result.bytesWritten;
+          }
+          bytes += next.value.byteLength;
+        }
+      } finally {
+        await reader.cancel().catch(() => {
+        });
+      }
+      if (!bytes)
+        throw new CliError("DOWNLOAD_EMPTY", "The video download was empty.", {
+          retryable: true
+        });
+      await handle.sync();
+      await handle.close();
+      if (options.force) await rename3(temporary, output);
+      else {
+        await link(temporary, output);
+        await unlink2(temporary);
+      }
+      return { jobId, output, bytes };
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      this.options.signal?.throwIfAborted();
+      throw new CliError(
+        "DOWNLOAD_FAILED",
+        "The video download did not complete.",
+        {
+          retryable: true,
+          recovery: "Run the download command again; no partial result replaced the destination."
+        }
+      );
+    } finally {
+      await handle.close().catch(() => {
+      });
+      await unlink2(temporary).catch(() => {
+      });
+    }
+  }
+};
+function inputFingerprint(body, inputs) {
+  const request = Object.fromEntries(
+    Object.entries(body).filter(([key]) => !Object.hasOwn(inputs, key))
+  );
+  const sources = Object.fromEntries(
+    Object.entries(inputs).map(([key, input]) => [
+      key,
+      input.file ? {
+        kind: input.kind,
+        sha256: input.file.sha256,
+        size: input.file.size,
+        contentType: input.file.contentType
+      } : { kind: input.kind, url: input.value }
+    ])
+  );
+  const canonical = (value) => value && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(
+    Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)])
+  ) : value;
+  return createHash4("sha256").update(JSON.stringify(canonical({ request, sources }))).digest("hex");
+}
+
+// src/core/config.ts
+import { isAbsolute as isAbsolute2 } from "path";
+function origin(value, name) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new CliError("INVALID_CONFIG", `${name} must be an absolute origin.`);
+  }
+  const local = ["127.0.0.1", "[::1]", "localhost"].includes(url.hostname);
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || url.protocol !== "https:" && !(local && url.protocol === "http:")) {
+    throw new CliError(
+      "INVALID_CONFIG",
+      `${name} must be an HTTPS origin, or a localhost HTTP origin for development.`
+    );
+  }
+  return url.origin;
+}
+function readConfig(env = process.env) {
+  const configDir = env.SPATIUS_CONFIG_DIR;
+  if (configDir && !isAbsolute2(configDir))
+    throw new CliError(
+      "INVALID_CONFIG",
+      "SPATIUS_CONFIG_DIR must be absolute."
+    );
+  return {
+    studioOrigin: origin(
+      env.SPATIUS_STUDIO_URL ?? "https://api.studio.spatius.ai",
+      "SPATIUS_STUDIO_URL"
+    ),
+    studioWebOrigin: origin(
+      env.SPATIUS_STUDIO_WEB_URL ?? "https://app.spatius.ai",
+      "SPATIUS_STUDIO_WEB_URL"
+    ),
+    consoleOrigin: origin(
+      env.SPATIUS_CONSOLE_URL ?? "https://console.spatius.ai",
+      "SPATIUS_CONSOLE_URL"
+    ),
+    mediaOrigin: origin(
+      env.SPATIUS_MEDIA_URL ?? "https://cli-media.spatius.ai",
+      "SPATIUS_MEDIA_URL"
+    ),
+    ...configDir ? { configDir } : {}
+  };
+}
+
+// package.json
+var package_default = {
+  name: "@spatius/cli",
+  version: "0.1.0-beta.0",
+  description: "Spatius avatar and video workflows for coding agents",
+  type: "module",
+  license: "MIT",
+  bin: {
+    spatius: "./dist/cli.js"
+  },
+  engines: {
+    node: ">=22"
+  },
+  files: [
+    "dist",
+    "skills",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/spatius-ai/spatius-cli.git",
+    directory: "packages/cli"
+  },
+  scripts: {
+    build: "tsup && node ../../scripts/package-assets.mjs",
+    dev: "tsx src/cli.ts",
+    typecheck: "tsc -p tsconfig.json",
+    test: "vitest run",
+    prepack: "pnpm build"
+  },
+  dependencies: {
+    commander: "^14.0.0"
+  },
+  devDependencies: {
+    "@spatius/contracts": "workspace:*",
+    tsup: "^8.5.0",
+    tsx: "^4.20.0"
+  },
+  publishConfig: {
+    access: "public",
+    provenance: true
+  }
+};
+
+// src/cli.ts
+var controller = new AbortController();
+var interrupt = () => controller.abort(new DOMException("Interrupted", "AbortError"));
+process.once("SIGINT", interrupt);
+process.once("SIGTERM", interrupt);
+var progress = (event) => process.stderr.write(
+  `${JSON.stringify({ schemaVersion: 1, ...typeof event === "object" && event !== null ? event : { event } })}
+`
+);
+var emit = (data) => process.stdout.write(
+  `${JSON.stringify({ schemaVersion: 1, ok: true, data })}
+`
+);
+var context;
+var program = buildProgram(
+  () => {
+    if (!context) {
+      const config = readConfig();
+      const auth = new AuthManager(config);
+      context = {
+        auth,
+        workflows: new Workflows({
+          ...config,
+          auth,
+          signal: controller.signal,
+          onProgress: progress
+        }),
+        signal: controller.signal,
+        progress
+      };
+    }
+    return context;
+  },
+  emit,
+  package_default.version
+);
+program.configureOutput({ writeErr: () => void 0 });
+try {
+  if (process.argv.length <= 2) program.outputHelp();
+  else await program.parseAsync(process.argv);
+} catch (error) {
+  if (error instanceof CommanderError && error.exitCode === 0)
+    process.exitCode = 0;
+  else {
+    const e = error instanceof CommanderError ? new CliError("INVALID_ARGUMENT", error.message, {
+      exitCode: 2,
+      recovery: "Run spatius --help or spatius schema."
+    }) : asCliError(error);
+    process.stderr.write(
+      `${JSON.stringify({ schemaVersion: 1, ok: false, error: { code: e.code, message: e.message, retryable: e.options.retryable ?? false, recovery: e.options.recovery, details: e.options.details } })}
+`
+    );
+    process.exitCode = e.options.exitCode ?? 1;
+  }
+} finally {
+  process.removeListener("SIGINT", interrupt);
+  process.removeListener("SIGTERM", interrupt);
+}