@crewhaus/cloud-adapter-flyio 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+import { type TargetShape } 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 declare class FlyAdapterError extends CrewhausError {
+    readonly name = "FlyAdapterError";
+    constructor(message: string, cause?: unknown);
+}
+export declare const FLY_TARGET_SHAPES: readonly ["channel", "managed", "batch", "voice", "browser"];
+export type FlyTargetShape = (typeof FLY_TARGET_SHAPES)[number];
+export declare function isFlyTargetShape(value: unknown): value is FlyTargetShape;
+/**
+ * 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 declare const FLY_REGIONS: readonly ["iad", "ord", "lax", "sjc", "lhr", "fra", "ams", "sin", "syd", "nrt", "gru"];
+export type FlyRegion = (typeof FLY_REGIONS)[number];
+export type FlyVmPreset = "shared-1x" | "shared-2x" | "performance-1x" | "performance-2x";
+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;
+};
+export declare function flyTomlFor(opts: FlyTomlOptions): string;
+export type FlyDockerfileOptions = {
+    readonly target: TargetShape;
+    readonly baseImage: string;
+    /** Internal port the container listens on (matches `flyTomlFor.internalPort`). */
+    readonly internalPort?: number;
+};
+export declare function flyDockerfileFor(opts: FlyDockerfileOptions): string;
+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 declare const FLY_DEFAULT_API_BASE = "https://api.machines.dev/v1";
+export declare function scrubApiToken(message: string, apiToken: string | undefined): string;
+/**
+ * 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 declare function deployToFly(opts: DeployToFlyOptions): Promise<FlyDeployRecord>;

package/dist/index.js

@@ -0,0 +1,241 @@
+import { 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 {
+    name = "FlyAdapterError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export const FLY_TARGET_SHAPES = [
+    "channel",
+    "managed",
+    "batch",
+    "voice",
+    "browser",
+];
+export function isFlyTargetShape(value) {
+    return typeof value === "string" && FLY_TARGET_SHAPES.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",
+];
+const VM_SIZING = {
+    "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 = {
+    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) {
+    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) {
+    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) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+const TOML_HEADER = "# Generated by @crewhaus/cloud-adapter-flyio — do not edit by hand";
+export function flyTomlFor(opts) {
+    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 = [
+        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 function flyDockerfileFor(opts) {
+    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 const FLY_DEFAULT_API_BASE = "https://api.machines.dev/v1";
+function resolveApiToken(provided) {
+    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, apiToken) {
+    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) {
+    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;
+    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;
+    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;
+    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,
+    };
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/cloud-adapter-flyio",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/docker-images": "0.1.4",
-    "@crewhaus/errors": "0.1.4"
+    "@crewhaus/docker-images": "0.1.5",
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,635 +0,0 @@
-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`);
-  });
-
-  test('falls back to status "created" when launch body omits state', async () => {
-    const fetchImpl = (async (url: string | URL) => {
-      const u = String(url);
-      if (u.endsWith("/apps")) return new Response("{}", { status: 201 });
-      // No `state` field — exercises the `?? "created"` fallback.
-      return new Response(JSON.stringify({ id: "m-nostate" }), { 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-nostate");
-    expect(record.status).toBe("created");
-  });
-
-  test("throws when launch returns 2xx with a non-JSON body", async () => {
-    const fetchImpl = (async (url: string | URL) => {
-      const u = String(url);
-      if (u.endsWith("/apps")) return new Response("{}", { status: 201 });
-      return new Response("not json at all", { status: 200 });
-    }) as unknown as typeof fetch;
-    let caught: Error | undefined;
-    try {
-      await deployToFly({
-        target: "channel",
-        appName: "my-bot",
-        imageRef: "img",
-        apiToken: "fo_testtoken_abc",
-        fetchImpl,
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(FlyAdapterError);
-    expect(caught?.message).toContain("non-JSON body");
-  });
-
-  test("throws when launch body is valid JSON but missing machine id", async () => {
-    const fetchImpl = (async (url: string | URL) => {
-      const u = String(url);
-      if (u.endsWith("/apps")) return new Response("{}", { status: 201 });
-      // Valid JSON, but `id` is absent (or non-string).
-      return new Response(JSON.stringify({ state: "started" }), { status: 200 });
-    }) as unknown as typeof fetch;
-    let caught: Error | undefined;
-    try {
-      await deployToFly({
-        target: "channel",
-        appName: "my-bot",
-        imageRef: "img",
-        apiToken: "fo_testtoken_abc",
-        fetchImpl,
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(FlyAdapterError);
-    expect(caught?.message).toContain("missing machine id");
-  });
-
-  test("wraps a thrown fetch on app-create and scrubs the token", async () => {
-    const fetchImpl = (async () => {
-      throw new Error("network down for fo_leakingtoken_full retry");
-    }) 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).toContain("Fly Machines API request failed");
-    expect(caught?.message).not.toContain("fo_leakingtoken_full");
-    expect(caught?.message).toContain("[REDACTED:FLY_API_TOKEN]");
-    expect((caught as FlyAdapterError).cause).toBeInstanceOf(Error);
-  });
-
-  test("wraps a non-Error thrown fetch on machine launch", async () => {
-    const fetchImpl = (async (url: string | URL) => {
-      const u = String(url);
-      if (u.endsWith("/apps")) return new Response("{}", { status: 201 });
-      // Throw a non-Error so the `String(err)` branch is taken.
-      throw "boom-string";
-    }) as unknown as typeof fetch;
-    let caught: Error | undefined;
-    try {
-      await deployToFly({
-        target: "channel",
-        appName: "my-bot",
-        imageRef: "img",
-        apiToken: "fo_testtoken_abc",
-        fetchImpl,
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(FlyAdapterError);
-    expect(caught?.message).toContain("Fly Machines API request failed: boom-string");
-  });
-
-  test("rejects unsupported (one-shot) target shapes 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: "eval",
-        appName: "my-bot",
-        imageRef: "img",
-        apiToken: "fo_testtoken_abc",
-        fetchImpl,
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(FlyAdapterError);
-    expect(called).toBe(false);
-  });
-
-  test("rejects unknown target shapes 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: "mystery" as never,
-        appName: "my-bot",
-        imageRef: "img",
-        apiToken: "fo_testtoken_abc",
-        fetchImpl,
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(FlyAdapterError);
-    expect(caught?.message).toContain("unknown target shape");
-    expect(called).toBe(false);
-  });
-
-  test("treats an empty-string apiToken as unconfigured", async () => {
-    delete process.env[API_TOKEN_ENV];
-    let caught: Error | undefined;
-    try {
-      await deployToFly({
-        target: "channel",
-        appName: "my-bot",
-        imageRef: "img",
-        apiToken: "",
-      });
-    } catch (err) {
-      caught = err as Error;
-    }
-    expect(caught).toBeInstanceOf(FlyAdapterError);
-    expect(caught?.message).toContain("FLY_API_TOKEN is required");
-  });
-
-  test("honors an explicit org slug + region in the request payload", async () => {
-    let createBody: string | undefined;
-    let launchBody: string | undefined;
-    const fetchImpl = (async (url: string | URL, init?: RequestInit) => {
-      const u = String(url);
-      if (u.endsWith("/apps")) {
-        createBody = init?.body as string;
-        return new Response("{}", { status: 201 });
-      }
-      launchBody = init?.body as string;
-      return new Response(JSON.stringify({ id: "m-1", state: "started" }), { status: 200 });
-    }) as unknown as typeof fetch;
-    const record = await deployToFly({
-      target: "channel",
-      appName: "my-bot",
-      imageRef: "img",
-      apiToken: "fo_testtoken_abc",
-      orgSlug: "acme-co",
-      region: "fra",
-      fetchImpl,
-    });
-    expect(record.region).toBe("fra");
-    expect(JSON.parse(createBody as string).org_slug).toBe("acme-co");
-    expect(JSON.parse(launchBody as string).region).toBe("fra");
-  });
-
-  test("surfaces a scrubbed app-create failure for non-409 statuses", async () => {
-    const fetchImpl = (async () =>
-      new Response("boom fo_leakingtoken_full boom", {
-        status: 500,
-        statusText: "Internal Server Error",
-      })) 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).toContain("Fly app create returned 500");
-    expect(caught?.message).not.toContain("fo_leakingtoken_full");
-  });
-});
-
-describe("security: app name guards the Machines API URL path", () => {
-  // Regression: appName is interpolated into `${baseUrl}/apps/${appName}/machines`.
-  // assertAppName must reject path-traversal / SSRF payloads BEFORE any fetch runs.
-  const PAYLOADS = [
-    "../../etc/passwd",
-    "app/../../admin",
-    "app%2F..%2Fadmin",
-    "app name",
-    "app\nmachines",
-    "evil.example.com",
-    "UPPER",
-  ];
-  for (const payload of PAYLOADS) {
-    test(`rejects "${payload}" without calling fetch`, 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: payload,
-          imageRef: "img",
-          apiToken: "fo_testtoken_abc",
-          fetchImpl,
-        });
-      } catch (err) {
-        caught = err as Error;
-      }
-      expect(caught).toBeInstanceOf(FlyAdapterError);
-      expect(called).toBe(false);
-    });
-  }
-});
-
-describe("flyTomlFor: unknown vs unsupported shape branches", () => {
-  test("rejects an entirely unknown shape (isTargetShape=false)", () => {
-    expect(() => flyTomlFor({ target: "mystery" as never, appName: "svc" })).toThrow(
-      /unknown target shape/,
-    );
-  });
-
-  test("skips env entries whose value is undefined", () => {
-    const toml = flyTomlFor({
-      target: "channel",
-      appName: "svc",
-      // `MISSING` is explicitly undefined; it must not emit a line.
-      envVars: { KEEP: "1", MISSING: undefined } as unknown as Record<string, string>,
-    });
-    expect(toml).toContain('KEEP = "1"');
-    expect(toml).not.toContain("MISSING");
-  });
-
-  test("omits the [env] block entirely when envVars is empty", () => {
-    const toml = flyTomlFor({ target: "channel", appName: "svc", envVars: {} });
-    expect(toml).not.toContain("[env]");
-  });
-
-  test("escapes backslashes in env values", () => {
-    const toml = flyTomlFor({
-      target: "channel",
-      appName: "svc",
-      envVars: { WIN: "C:\\path" },
-    });
-    expect(toml).toContain('WIN = "C:\\\\path"');
-  });
-
-  test("uses a custom dockerfile path", () => {
-    const toml = flyTomlFor({
-      target: "channel",
-      appName: "svc",
-      dockerfilePath: "ops/Dockerfile.custom",
-    });
-    expect(toml).toContain('dockerfile = "ops/Dockerfile.custom"');
-  });
-
-  test("supports every web shape and the lone worker shape", () => {
-    for (const shape of ["channel", "managed", "voice", "browser"] as const) {
-      expect(flyTomlFor({ target: shape, appName: "svc" })).toContain("[http_service]");
-    }
-    expect(flyTomlFor({ target: "batch", appName: "svc" })).toContain("[processes]");
-  });
-});

package/src/index.ts

@@ -1,345 +0,0 @@
-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,
-  };
-}