@crewhaus/cloud-adapter-flyio 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crewhaus/cloud-adapter-flyio",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "One-click deploy adapter for Fly.io — generates a fly.toml + a Fly-tuned Dockerfile and wraps the Machines API for daemon target shapes (Section 44)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/docker-images": "0.0.0",
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/cloud-adapter-flyio"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/cloud-adapter-flyio#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,329 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  FLY_DEFAULT_API_BASE,
+  FLY_TARGET_SHAPES,
+  FlyAdapterError,
+  deployToFly,
+  flyDockerfileFor,
+  flyTomlFor,
+  isFlyTargetShape,
+  scrubApiToken,
+} from "./index";
+
+const API_TOKEN_ENV = "FLY_API_TOKEN";
+
+describe("isFlyTargetShape", () => {
+  test("accepts daemon shapes", () => {
+    for (const shape of FLY_TARGET_SHAPES) {
+      expect(isFlyTargetShape(shape)).toBe(true);
+    }
+  });
+  test("rejects one-shot shapes", () => {
+    for (const shape of ["cli", "workflow", "eval", "graph", "pipeline", "crew", "research"]) {
+      expect(isFlyTargetShape(shape)).toBe(false);
+    }
+  });
+});
+
+describe("flyTomlFor", () => {
+  test("web shape emits http_service block + healthcheck", () => {
+    const toml = flyTomlFor({ target: "channel", appName: "my-bot" });
+    expect(toml).toContain('app = "my-bot"');
+    expect(toml).toContain('primary_region = "iad"');
+    expect(toml).toContain("[build]");
+    expect(toml).toContain('dockerfile = "Dockerfile.fly"');
+    expect(toml).toContain("[http_service]");
+    expect(toml).toContain("internal_port = 8080");
+    expect(toml).toContain("force_https = true");
+    expect(toml).toContain('path = "/healthz"');
+    expect(toml).toContain("[[vm]]");
+    expect(toml).toContain('cpu_kind = "shared"');
+  });
+
+  test("batch shape emits process group (no http_service)", () => {
+    const toml = flyTomlFor({ target: "batch", appName: "my-worker" });
+    expect(toml).not.toContain("[http_service]");
+    expect(toml).toContain("[processes]");
+    expect(toml).toContain("worker =");
+  });
+
+  test("env vars are TOML-encoded + sorted", () => {
+    const a = flyTomlFor({
+      target: "channel",
+      appName: "svc",
+      envVars: { ZETA: "1", ALPHA: "2" },
+    });
+    const b = flyTomlFor({
+      target: "channel",
+      appName: "svc",
+      envVars: { ALPHA: "2", ZETA: "1" },
+    });
+    expect(a).toBe(b);
+    const alpha = a.indexOf("ALPHA");
+    const zeta = a.indexOf("ZETA");
+    expect(alpha).toBeLessThan(zeta);
+  });
+
+  test("env var values with quotes are escaped", () => {
+    const toml = flyTomlFor({
+      target: "channel",
+      appName: "svc",
+      envVars: { TRICKY: 'has "quote" inside' },
+    });
+    expect(toml).toContain('TRICKY = "has \\"quote\\" inside"');
+  });
+
+  test("respects vm preset", () => {
+    const toml = flyTomlFor({ target: "channel", appName: "svc", vm: "performance-2x" });
+    expect(toml).toContain('cpu_kind = "performance"');
+    expect(toml).toContain("cpus = 2");
+    expect(toml).toContain("memory_mb = 4096");
+  });
+
+  test("respects internal port + region overrides", () => {
+    const toml = flyTomlFor({
+      target: "channel",
+      appName: "svc",
+      internalPort: 3000,
+      primaryRegion: "fra",
+    });
+    expect(toml).toContain("internal_port = 3000");
+    expect(toml).toContain('primary_region = "fra"');
+  });
+
+  test("rejects invalid app names", () => {
+    expect(() => flyTomlFor({ target: "channel", appName: "MyApp" })).toThrow(FlyAdapterError);
+    expect(() => flyTomlFor({ target: "channel", appName: "-leading" })).toThrow(FlyAdapterError);
+    expect(() =>
+      flyTomlFor({ target: "channel", appName: "this-app-name-is-far-too-long-for-fly" }),
+    ).toThrow(FlyAdapterError);
+  });
+
+  test("rejects unsupported target shapes", () => {
+    expect(() => flyTomlFor({ target: "cli", appName: "svc" })).toThrow(FlyAdapterError);
+    expect(() => flyTomlFor({ target: "eval", appName: "svc" })).toThrow(FlyAdapterError);
+  });
+});
+
+describe("flyDockerfileFor", () => {
+  test("web shape gets EXPOSE on the internal port", () => {
+    const df = flyDockerfileFor({ target: "channel", baseImage: "crewhaus/channel:0.1.0" });
+    expect(df).toContain("FROM crewhaus/channel:0.1.0");
+    expect(df).toContain("ENV PORT=8080");
+    expect(df).toContain("EXPOSE 8080");
+  });
+
+  test("worker shape skips EXPOSE", () => {
+    const df = flyDockerfileFor({ target: "batch", baseImage: "crewhaus/batch:0.1.0" });
+    expect(df).not.toContain("EXPOSE");
+  });
+
+  test("respects internal port override", () => {
+    const df = flyDockerfileFor({
+      target: "channel",
+      baseImage: "crewhaus/channel:0.1.0",
+      internalPort: 3000,
+    });
+    expect(df).toContain("EXPOSE 3000");
+    expect(df).toContain("ENV PORT=3000");
+  });
+
+  test("rejects one-shot shapes", () => {
+    expect(() => flyDockerfileFor({ target: "cli", baseImage: "x" })).toThrow(FlyAdapterError);
+  });
+
+  test("rejects unknown shapes", () => {
+    expect(() => flyDockerfileFor({ target: "mystery" as never, baseImage: "x" })).toThrow(
+      FlyAdapterError,
+    );
+  });
+});
+
+describe("scrubApiToken", () => {
+  test("redacts the token", () => {
+    expect(scrubApiToken("token fo_abcdefghij123 leaked", "fo_abcdefghij123")).toBe(
+      "token [REDACTED:FLY_API_TOKEN] leaked",
+    );
+  });
+  test("ignores short tokens", () => {
+    expect(scrubApiToken("untouched", "abc")).toBe("untouched");
+  });
+  test("ignores undefined tokens", () => {
+    expect(scrubApiToken("untouched", undefined)).toBe("untouched");
+  });
+});
+
+describe("deployToFly", () => {
+  const ORIGINAL_TOKEN = process.env[API_TOKEN_ENV];
+  afterEach(() => {
+    if (ORIGINAL_TOKEN === undefined) delete process.env[API_TOKEN_ENV];
+    else process.env[API_TOKEN_ENV] = ORIGINAL_TOKEN;
+  });
+
+  function okFetchImpl(machineId = "m-default", state = "started"): typeof fetch {
+    return (async (url: string | URL) => {
+      const u = String(url);
+      if (u.endsWith("/apps")) {
+        return new Response("{}", { status: 201 });
+      }
+      if (u.includes("/machines")) {
+        return new Response(JSON.stringify({ id: machineId, state }), { status: 200 });
+      }
+      return new Response("not matched", { status: 500 });
+    }) as unknown as typeof fetch;
+  }
+
+  test("creates app + launches first machine", async () => {
+    const record = await deployToFly({
+      target: "channel",
+      appName: "my-bot",
+      imageRef: "registry.fly.io/my-bot:latest",
+      apiToken: "fo_testtoken_abc",
+      fetchImpl: okFetchImpl("m-12345", "started"),
+    });
+    expect(record.appName).toBe("my-bot");
+    expect(record.machineId).toBe("m-12345");
+    expect(record.status).toBe("started");
+    expect(record.region).toBe("iad");
+  });
+
+  test("treats 409 app-create conflict as success (already exists)", async () => {
+    const fetchImpl = (async (url: string | URL) => {
+      const u = String(url);
+      if (u.endsWith("/apps")) {
+        return new Response('{"error":"app exists"}', { status: 409 });
+      }
+      return new Response(JSON.stringify({ id: "m-x", state: "started" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const record = await deployToFly({
+      target: "channel",
+      appName: "my-bot",
+      imageRef: "img",
+      apiToken: "fo_testtoken_abc",
+      fetchImpl,
+    });
+    expect(record.machineId).toBe("m-x");
+  });
+
+  test("scrubs the token from machine-launch error bodies", async () => {
+    const fetchImpl = (async (url: string | URL) => {
+      const u = String(url);
+      if (u.endsWith("/apps")) return new Response("{}", { status: 201 });
+      return new Response("unauthorized — token fo_leakingtoken_full denied", {
+        status: 401,
+        statusText: "Unauthorized",
+      });
+    }) as unknown as typeof fetch;
+    let caught: Error | undefined;
+    try {
+      await deployToFly({
+        target: "channel",
+        appName: "my-bot",
+        imageRef: "img",
+        apiToken: "fo_leakingtoken_full",
+        fetchImpl,
+      });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeInstanceOf(FlyAdapterError);
+    expect(caught?.message).not.toContain("fo_leakingtoken_full");
+    expect(caught?.message).toContain("[REDACTED:FLY_API_TOKEN]");
+  });
+
+  test("scrubs the token from app-create error bodies", async () => {
+    const fetchImpl = (async () =>
+      new Response("forbidden — token fo_leakingtoken_full denied", {
+        status: 403,
+        statusText: "Forbidden",
+      })) as unknown as typeof fetch;
+    let caught: Error | undefined;
+    try {
+      await deployToFly({
+        target: "channel",
+        appName: "my-bot",
+        imageRef: "img",
+        apiToken: "fo_leakingtoken_full",
+        fetchImpl,
+      });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeInstanceOf(FlyAdapterError);
+    expect(caught?.message).not.toContain("fo_leakingtoken_full");
+  });
+
+  test("throws clearly when no token is configured", async () => {
+    delete process.env[API_TOKEN_ENV];
+    let caught: Error | undefined;
+    try {
+      await deployToFly({
+        target: "channel",
+        appName: "my-bot",
+        imageRef: "img",
+      });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeInstanceOf(FlyAdapterError);
+    expect(caught?.message).toContain("FLY_API_TOKEN is required");
+  });
+
+  test("resolves token from env when apiToken omitted", async () => {
+    process.env[API_TOKEN_ENV] = "fo_env_provided_token";
+    let seenAuth: string | undefined;
+    const fetchImpl = (async (url: string | URL, init?: RequestInit) => {
+      seenAuth = (init?.headers as Record<string, string>)["Authorization"];
+      const u = String(url);
+      if (u.endsWith("/apps")) return new Response("{}", { status: 201 });
+      return new Response(JSON.stringify({ id: "m-1", state: "started" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    await deployToFly({
+      target: "channel",
+      appName: "my-bot",
+      imageRef: "img",
+      fetchImpl,
+    });
+    expect(seenAuth).toBe("Bearer fo_env_provided_token");
+  });
+
+  test("rejects invalid app name before any network call", async () => {
+    let called = false;
+    const fetchImpl = (async () => {
+      called = true;
+      return new Response("", { status: 200 });
+    }) as unknown as typeof fetch;
+    let caught: Error | undefined;
+    try {
+      await deployToFly({
+        target: "channel",
+        appName: "BadCaps",
+        imageRef: "img",
+        apiToken: "fo_testtoken_abc",
+        fetchImpl,
+      });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeInstanceOf(FlyAdapterError);
+    expect(called).toBe(false);
+  });
+
+  test("uses the configured base url", async () => {
+    let seenUrl: string | undefined;
+    const fetchImpl = (async (url: string | URL) => {
+      seenUrl = seenUrl ?? String(url);
+      const u = String(url);
+      if (u.endsWith("/apps")) return new Response("{}", { status: 201 });
+      return new Response(JSON.stringify({ id: "m-1", state: "started" }), { status: 200 });
+    }) as unknown as typeof fetch;
+    await deployToFly({
+      target: "channel",
+      appName: "my-bot",
+      imageRef: "img",
+      apiToken: "fo_testtoken_abc",
+      fetchImpl,
+    });
+    expect(seenUrl).toBe(`${FLY_DEFAULT_API_BASE}/apps`);
+  });
+});

package/src/index.ts

@@ -0,0 +1,345 @@
+import { type TargetShape, isTargetShape } from "@crewhaus/docker-images";
+import { CrewhausError } from "@crewhaus/errors";
+
+/**
+ * Section 44 — `@crewhaus/cloud-adapter-flyio`
+ *
+ * One-click deploy adapter for [Fly.io](https://fly.io). Three surfaces:
+ *
+ *   - `flyTomlFor({target, appName, region, …})` — emits a deterministic
+ *     `fly.toml` config: HTTP service block for web shapes, process
+ *     groups for batch workers, VM sizing, env vars, healthchecks.
+ *
+ *   - `flyDockerfileFor({target, baseImage})` — wraps the §32 docker-images
+ *     base with a Fly-tuned `EXPOSE` + healthcheck against the internal
+ *     port (default 8080). Fly's load balancer probes via `[http_service.checks]`
+ *     so a container HEALTHCHECK is optional, but we add one for shapes
+ *     that already define `/healthz` to match the §44 contract.
+ *
+ *   - `deployToFly({apiToken, appName, …})` — creates the app + first
+ *     machine via the Machines API (`https://api.machines.dev/v1`).
+ *     Live calls gated on `FLY_API_TOKEN` env (or explicit `apiToken`)
+ *     plus injectable `fetchImpl` test seam.
+ *
+ * SECURITY (T8 credential-leak guard): `scrubApiToken()` runs every
+ * error path before surfacing to the caller — same approach as the
+ * §37 `exporter-datadog` `scrubApiKey` helper, mirrored from
+ * §44 `cloud-adapter-render`.
+ *
+ * Targets: daemon shapes only (channel, managed, batch, voice, browser).
+ * One-shot shapes throw `FlyAdapterError`.
+ */
+
+export class FlyAdapterError extends CrewhausError {
+  override readonly name = "FlyAdapterError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export const FLY_TARGET_SHAPES = [
+  "channel",
+  "managed",
+  "batch",
+  "voice",
+  "browser",
+] as const satisfies readonly TargetShape[];
+
+export type FlyTargetShape = (typeof FLY_TARGET_SHAPES)[number];
+
+export function isFlyTargetShape(value: unknown): value is FlyTargetShape {
+  return typeof value === "string" && (FLY_TARGET_SHAPES as readonly string[]).includes(value);
+}
+
+/**
+ * Subset of Fly's primary regions. Fly publishes the full list at
+ * https://fly.io/docs/reference/regions/ — we accept any 3-letter code,
+ * but the named list here makes typos cheaper for the common cases.
+ */
+export const FLY_REGIONS = [
+  "iad",
+  "ord",
+  "lax",
+  "sjc",
+  "lhr",
+  "fra",
+  "ams",
+  "sin",
+  "syd",
+  "nrt",
+  "gru",
+] as const;
+export type FlyRegion = (typeof FLY_REGIONS)[number];
+
+export type FlyVmPreset = "shared-1x" | "shared-2x" | "performance-1x" | "performance-2x";
+
+const VM_SIZING: Readonly<
+  Record<FlyVmPreset, { cpuKind: string; cpus: number; memoryMb: number }>
+> = {
+  "shared-1x": { cpuKind: "shared", cpus: 1, memoryMb: 256 },
+  "shared-2x": { cpuKind: "shared", cpus: 2, memoryMb: 512 },
+  "performance-1x": { cpuKind: "performance", cpus: 1, memoryMb: 2048 },
+  "performance-2x": { cpuKind: "performance", cpus: 2, memoryMb: 4096 },
+};
+
+const SERVICE_TYPE_FOR_TARGET: Readonly<Record<FlyTargetShape, "web" | "worker">> = {
+  channel: "web",
+  managed: "web",
+  voice: "web",
+  browser: "web",
+  batch: "worker",
+};
+
+const APP_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$/;
+
+function assertFlyTarget(target: TargetShape): asserts target is FlyTargetShape {
+  if (!isFlyTargetShape(target)) {
+    throw new FlyAdapterError(
+      `target shape "${target}" is not supported by Fly.io. Supported daemon shapes: ${FLY_TARGET_SHAPES.join(", ")}.`,
+    );
+  }
+}
+
+function assertAppName(name: string): void {
+  if (!APP_NAME_PATTERN.test(name)) {
+    throw new FlyAdapterError(
+      `app name "${name}" is invalid. Must be lowercase alphanumerics + hyphens, 1-30 chars, no leading/trailing hyphen.`,
+    );
+  }
+}
+
+function tomlEscape(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+export type FlyTomlOptions = {
+  readonly target: TargetShape;
+  readonly appName: string;
+  readonly primaryRegion?: FlyRegion | string;
+  readonly internalPort?: number;
+  readonly vm?: FlyVmPreset;
+  /** Plain-text env vars merged into `[env]`. Secret values must come from `fly secrets set`. */
+  readonly envVars?: Readonly<Record<string, string>>;
+  /** Path to the Dockerfile inside the build context. Defaults to `Dockerfile.fly`. */
+  readonly dockerfilePath?: string;
+};
+
+const TOML_HEADER = "# Generated by @crewhaus/cloud-adapter-flyio — do not edit by hand";
+
+export function flyTomlFor(opts: FlyTomlOptions): string {
+  if (!isTargetShape(opts.target)) {
+    throw new FlyAdapterError(`unknown target shape "${opts.target}"`);
+  }
+  assertFlyTarget(opts.target);
+  assertAppName(opts.appName);
+
+  const serviceType = SERVICE_TYPE_FOR_TARGET[opts.target];
+  const region = opts.primaryRegion ?? "iad";
+  const port = opts.internalPort ?? 8080;
+  const vm = VM_SIZING[opts.vm ?? "shared-1x"];
+  const dockerfilePath = opts.dockerfilePath ?? "Dockerfile.fly";
+
+  const lines: string[] = [
+    TOML_HEADER,
+    `app = "${tomlEscape(opts.appName)}"`,
+    `primary_region = "${tomlEscape(region)}"`,
+    "",
+    "[build]",
+    `  dockerfile = "${tomlEscape(dockerfilePath)}"`,
+  ];
+
+  if (opts.envVars && Object.keys(opts.envVars).length > 0) {
+    lines.push("", "[env]");
+    for (const key of Object.keys(opts.envVars).sort()) {
+      const value = opts.envVars[key];
+      if (value === undefined) continue;
+      lines.push(`  ${key} = "${tomlEscape(value)}"`);
+    }
+  }
+
+  if (serviceType === "web") {
+    lines.push(
+      "",
+      "[http_service]",
+      `  internal_port = ${port}`,
+      "  force_https = true",
+      "  auto_stop_machines = true",
+      "  auto_start_machines = true",
+      "  min_machines_running = 0",
+      "",
+      "  [[http_service.checks]]",
+      '    interval = "30s"',
+      '    timeout = "5s"',
+      '    grace_period = "10s"',
+      '    method = "GET"',
+      '    path = "/healthz"',
+    );
+  } else {
+    lines.push("", "[processes]", `  worker = "node /app/dist/agent.js"`);
+  }
+
+  lines.push(
+    "",
+    "[[vm]]",
+    `  cpu_kind = "${vm.cpuKind}"`,
+    `  cpus = ${vm.cpus}`,
+    `  memory_mb = ${vm.memoryMb}`,
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
+export type FlyDockerfileOptions = {
+  readonly target: TargetShape;
+  readonly baseImage: string;
+  /** Internal port the container listens on (matches `flyTomlFor.internalPort`). */
+  readonly internalPort?: number;
+};
+
+export function flyDockerfileFor(opts: FlyDockerfileOptions): string {
+  if (!isTargetShape(opts.target)) {
+    throw new FlyAdapterError(`unknown target shape "${opts.target}"`);
+  }
+  assertFlyTarget(opts.target);
+  const isWeb = SERVICE_TYPE_FOR_TARGET[opts.target] === "web";
+  const port = opts.internalPort ?? 8080;
+  const lines = [
+    `# Fly.io-tuned wrapper around ${opts.baseImage}`,
+    `FROM ${opts.baseImage}`,
+    `ENV PORT=${port}`,
+  ];
+  if (isWeb) {
+    lines.push(`EXPOSE ${port}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export type FlyDeployRecord = {
+  readonly appName: string;
+  readonly machineId: string;
+  readonly status: string;
+  readonly region: string;
+};
+
+export type DeployToFlyOptions = {
+  readonly appName: string;
+  readonly imageRef: string;
+  readonly target: TargetShape;
+  readonly region?: FlyRegion | string;
+  readonly apiToken?: string;
+  readonly apiBaseUrl?: string;
+  /** Org slug the app belongs to. Defaults to "personal". */
+  readonly orgSlug?: string;
+  readonly fetchImpl?: typeof fetch;
+};
+
+export const FLY_DEFAULT_API_BASE = "https://api.machines.dev/v1";
+
+function resolveApiToken(provided: string | undefined): string {
+  const key = provided ?? process.env["FLY_API_TOKEN"];
+  if (key === undefined || key.length === 0) {
+    throw new FlyAdapterError(
+      "FLY_API_TOKEN is required. Pass `apiToken` explicitly or set the env var.",
+    );
+  }
+  return key;
+}
+
+export function scrubApiToken(message: string, apiToken: string | undefined): string {
+  if (apiToken === undefined || apiToken.length < 8) return message;
+  return message.split(apiToken).join("[REDACTED:FLY_API_TOKEN]");
+}
+
+/**
+ * Two-step deploy: (1) create app (idempotent — Fly returns 409 if it
+ * exists, which we treat as success), (2) launch first machine running
+ * the image. Returns a `FlyDeployRecord`. All errors run through
+ * `scrubApiToken()` before surfacing.
+ */
+export async function deployToFly(opts: DeployToFlyOptions): Promise<FlyDeployRecord> {
+  if (!isTargetShape(opts.target)) {
+    throw new FlyAdapterError(`unknown target shape "${opts.target}"`);
+  }
+  assertFlyTarget(opts.target);
+  assertAppName(opts.appName);
+  const apiToken = resolveApiToken(opts.apiToken);
+  const baseUrl = opts.apiBaseUrl ?? FLY_DEFAULT_API_BASE;
+  const region = opts.region ?? "iad";
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const orgSlug = opts.orgSlug ?? "personal";
+
+  const headers = {
+    Authorization: `Bearer ${apiToken}`,
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+
+  // Step 1: create app (treat 409 conflict as already-exists, which is fine).
+  let createResponse: Response;
+  try {
+    createResponse = await fetchFn(`${baseUrl}/apps`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ app_name: opts.appName, org_slug: orgSlug }),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new FlyAdapterError(
+      `Fly Machines API request failed: ${scrubApiToken(msg, apiToken)}`,
+      err,
+    );
+  }
+  if (!createResponse.ok && createResponse.status !== 409) {
+    const body = scrubApiToken(await createResponse.text(), apiToken);
+    throw new FlyAdapterError(
+      `Fly app create returned ${createResponse.status} ${createResponse.statusText}: ${body}`,
+    );
+  }
+
+  // Step 2: launch the first machine.
+  let launchResponse: Response;
+  try {
+    launchResponse = await fetchFn(`${baseUrl}/apps/${opts.appName}/machines`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        region,
+        config: {
+          image: opts.imageRef,
+          auto_destroy: false,
+          restart: { policy: "always" },
+        },
+      }),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new FlyAdapterError(
+      `Fly Machines API request failed: ${scrubApiToken(msg, apiToken)}`,
+      err,
+    );
+  }
+  const launchText = await launchResponse.text();
+  const scrubbed = scrubApiToken(launchText, apiToken);
+  if (!launchResponse.ok) {
+    throw new FlyAdapterError(
+      `Fly machine launch returned ${launchResponse.status} ${launchResponse.statusText}: ${scrubbed}`,
+    );
+  }
+
+  let parsed: { id?: string; state?: string };
+  try {
+    parsed = JSON.parse(launchText);
+  } catch (err) {
+    throw new FlyAdapterError(`Fly Machines API returned non-JSON body: ${scrubbed}`, err);
+  }
+  const machineId = parsed.id;
+  if (typeof machineId !== "string") {
+    throw new FlyAdapterError(`Fly Machines API response missing machine id: ${scrubbed}`);
+  }
+  return {
+    appName: opts.appName,
+    machineId,
+    status: parsed.state ?? "created",
+    region,
+  };
+}