@replayio/app-building 1.7.0 → 1.8.0

package/README.md

@@ -14,10 +14,10 @@ npm install @replayio/app-building
 import {
   loadDotEnv,
   FileContainerRegistry,
+  createMachine,
+  destroyMachine,
   type ContainerConfig,
   type RepoOptions,
-  startRemoteContainer,
-  stopRemoteContainer,
   httpGet,
   httpPost,
   httpOptsFor,
@@ -33,20 +33,19 @@ const config: ContainerConfig = {
   flyApp: envVars.FLY_APP_NAME,
 };
 
-// Start a detached container with an initial prompt — it will process and exit when done
-config.detached = true;
-config.initialPrompt = "Build the app";
-const repo: RepoOptions = { repoUrl: "https://github.com/...", cloneBranch: "main", pushBranch: "main" };
-const state = await startRemoteContainer(config, repo);
+// Create a Fly machine (automatically provisions a volume)
+const { machineId, volumeId } = await createMachine(
+  config.flyApp, config.flyToken, imageRef, containerEnv, machineName,
+);
 
 // Check status
-const status = await httpGet(`${state.baseUrl}/status`, httpOpts);
+const status = await httpGet(`https://${config.flyApp}.fly.dev/status`);
 
 // Query the registry
 const alive = await config.registry.findAlive();
 
-// Clean up
-await stopRemoteContainer(config, state);
+// Clean up (destroys machine and its volume)
+await destroyMachine(config.flyApp, config.flyToken, machineId, volumeId);
 ```
 
 ## Exported API
@@ -65,9 +64,7 @@ await stopRemoteContainer(config, state);
 | Export | Description |
 |---|---|
 | `startContainer(config, repo)` | Build the Docker image locally and start a container with `--network host`. Returns `AgentState`. |
-| `startRemoteContainer(config, repo)` | Create a Fly.io machine using the GHCR image. Requires `config.flyToken` and `config.flyApp`. Returns `AgentState`. |
 | `stopContainer(config, containerName)` | Stop a local Docker container by name. |
-| `stopRemoteContainer(config, state)` | Destroy the Fly.io machine for a remote container. Requires `config.flyToken`. |
 | `buildImage(config)` | Build the Docker image locally (called automatically by `startContainer`). |
 | `spawnTestContainer(config)` | Start an interactive (`-it`) container with the repo mounted at `/repo`. |
 | `loadDotEnv(projectRoot)` | Parse a `.env` file and return key-value pairs. |
@@ -103,26 +100,25 @@ await stopRemoteContainer(config, state);
 | `httpOptsFor(state)` | Return `HttpOptions` for a container (adds `fly-force-instance-id` header for remote containers). |
 | `probeAlive(entry)` | Check if a container is responding to `/status`. |
 
-### Fly.io machines
+### Fly.io utilities
 
 | Export | Description |
 |---|---|
 | `createApp(token, name, org?)` | Create a Fly app and allocate IPs. |
-| `createMachine(app, token, image, env, name, volumeId?)` | Create a Fly machine. If `volumeId` is provided, mounts it at `/repo`. Returns machine ID. |
-| `waitForMachine(app, token, machineId, timeout?)` | Wait for a machine to reach `started` state. |
-| `destroyMachine(app, token, machineId)` | Force-destroy a machine. |
+| `createMachine(app, token, image, env, name)` | Create a Fly machine with a 50GB volume mounted at `/repo`. Returns `{ machineId, volumeId }`. |
+| `waitForMachine(app, token, machineId)` | Poll until a machine reaches `started` state. |
 | `listMachines(app, token)` | List all machines for an app. |
-| `createVolume(app, token, name, sizeGb?)` | Create a Fly volume (default 50 GB). Returns volume ID. |
-| `deleteVolume(app, token, volumeId)` | Delete a Fly volume. |
+| `destroyMachine(app, token, machineId, volumeId?)` | Force-destroy a machine and optionally its volume. |
 | `listVolumes(app, token)` | List all volumes for an app. |
+| `deleteVolume(app, token, volumeId)` | Delete a Fly volume. |
 
-**Types:** `FlyMachineInfo`, `FlyVolumeInfo`
+**Types:** `FlyMachineInfo`, `FlyVolumeInfo`, `CreateMachineResult`
 
 ### Image ref
 
 | Export | Description |
 |---|---|
-| `getImageRef()` | Returns `CONTAINER_IMAGE_REF` env var, or `ghcr.io/replayio/app-building:latest` by default. Used by `startRemoteContainer`. |
+| `getImageRef()` | Returns `CONTAINER_IMAGE_REF` env var, or `ghcr.io/replayio/app-building:latest` by default. |
 
 ## Container HTTP API
 

package/dist/container.d.ts

@@ -29,7 +29,5 @@ export interface RepoOptions {
 export declare function loadDotEnv(projectRoot: string): Record<string, string>;
 export declare function buildImage(config: ContainerConfig): void;
 export declare function startContainer(config: ContainerConfig, repo: RepoOptions): Promise<AgentState>;
-export declare function startRemoteContainer(config: ContainerConfig, repo: RepoOptions): Promise<AgentState>;
-export declare function stopRemoteContainer(config: ContainerConfig, state: AgentState): Promise<void>;
 export declare function stopContainer(config: ContainerConfig, containerName: string): void;
 export declare function spawnTestContainer(config: ContainerConfig): Promise<void>;

package/dist/container.js

@@ -1,8 +1,6 @@
 import { execFileSync, spawn } from "child_process";
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
-import { createMachine, waitForMachine, destroyMachine, listMachines, createVolume, deleteVolume } from "./fly";
-import { getImageRef } from "./image-ref";
 const IMAGE_NAME = "app-building";
 function debugLog(...args) {
     if (process.env.DEBUG)
@@ -177,131 +175,6 @@ export async function startContainer(config, repo) {
     config.registry.log(agentState);
     return agentState;
 }
-export async function startRemoteContainer(config, repo) {
-    debugLog("startRemoteContainer config:", {
-        projectRoot: config.projectRoot,
-        flyApp: config.flyApp,
-        imageRef: config.imageRef,
-        webhookUrl: config.webhookUrl,
-        detached: config.detached,
-        initialPrompt: config.initialPrompt ? `${config.initialPrompt.slice(0, 100)}...` : undefined,
-        envVarKeys: Object.keys(config.envVars),
-    });
-    debugLog("startRemoteContainer repo:", repo);
-    if (!config.flyToken)
-        throw new Error("flyToken is required for remote containers");
-    if (!config.flyApp)
-        throw new Error("flyApp is required for remote containers");
-    const imageRef = config.imageRef ?? getImageRef();
-    const uniqueId = Math.random().toString(36).slice(2, 8);
-    const machineName = `app-building-${uniqueId}`;
-    // Build env vars for the machine
-    const remoteExtra = {
-        PORT: "3000",
-        CONTAINER_NAME: machineName,
-    };
-    if (config.webhookUrl)
-        remoteExtra.WEBHOOK_URL = config.webhookUrl;
-    if (config.detached)
-        remoteExtra.DETACHED = "1";
-    if (config.initialPrompt)
-        remoteExtra.INITIAL_PROMPT = config.initialPrompt;
-    const containerEnv = buildContainerEnv(repo, config.envVars, remoteExtra);
-    // Log existing machines (but don't destroy — multiple containers may run concurrently)
-    const existing = await listMachines(config.flyApp, config.flyToken);
-    if (existing.length > 0) {
-        console.log(`${existing.length} existing machine(s) in ${config.flyApp}:`);
-        for (const m of existing) {
-            console.log(`  ${m.id} (${m.name}) — ${m.state}`);
-        }
-    }
-    // Create a volume for /repo storage
-    console.log("Creating Fly volume...");
-    const volumeId = await createVolume(config.flyApp, config.flyToken, `repo-${uniqueId}`);
-    console.log(`Volume created: ${volumeId}`);
-    // Retry machine creation — the registry tag may take a moment to propagate
-    console.log("Creating Fly machine...");
-    let machineId = "";
-    for (let attempt = 0; attempt < 5; attempt++) {
-        try {
-            machineId = await createMachine(config.flyApp, config.flyToken, imageRef, containerEnv, machineName, volumeId);
-            break;
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (msg.includes("MANIFEST_UNKNOWN") && attempt < 4) {
-                console.log("Image not yet available in registry, retrying in 5s...");
-                await new Promise((r) => setTimeout(r, 5000));
-                continue;
-            }
-            // Clean up volume if machine creation fails
-            await deleteVolume(config.flyApp, config.flyToken, volumeId).catch(() => { });
-            throw err;
-        }
-    }
-    console.log(`Machine created: ${machineId}`);
-    // Register immediately so the container is tracked even if startup times out
-    const baseUrl = `https://${config.flyApp}.fly.dev`;
-    const agentState = {
-        type: "remote",
-        containerName: machineName,
-        port: 443,
-        baseUrl,
-        flyApp: config.flyApp,
-        flyMachineId: machineId,
-        flyVolumeId: volumeId,
-    };
-    config.registry.log(agentState);
-    console.log("Waiting for machine to start...");
-    await waitForMachine(config.flyApp, config.flyToken, machineId);
-    console.log("Machine started.");
-    // Poll the public URL until the HTTP server is ready, targeting this specific machine
-    const maxWait = 180000;
-    const interval = 2000;
-    const start = Date.now();
-    let ready = false;
-    while (Date.now() - start < maxWait) {
-        try {
-            const res = await fetch(`${baseUrl}/status`, {
-                headers: { "fly-force-instance-id": machineId },
-            });
-            if (res.ok) {
-                ready = true;
-                break;
-            }
-        }
-        catch {
-            // Not ready yet
-        }
-        await new Promise((r) => setTimeout(r, interval));
-    }
-    if (!ready) {
-        // Clean up machine and volume if we can't reach it
-        console.log("Timed out waiting for machine, destroying...");
-        await destroyMachine(config.flyApp, config.flyToken, machineId).catch(() => { });
-        await deleteVolume(config.flyApp, config.flyToken, volumeId).catch(() => { });
-        throw new Error("Remote container did not become ready within timeout");
-    }
-    return agentState;
-}
-export async function stopRemoteContainer(config, state) {
-    if (!state.flyApp || !state.flyMachineId) {
-        throw new Error("Missing flyApp or flyMachineId in agent state");
-    }
-    if (!config.flyToken)
-        throw new Error("flyToken is required to stop remote container");
-    console.log(`Destroying Fly machine ${state.flyMachineId}...`);
-    await destroyMachine(state.flyApp, config.flyToken, state.flyMachineId);
-    console.log("Machine destroyed.");
-    if (state.flyVolumeId) {
-        console.log(`Deleting Fly volume ${state.flyVolumeId}...`);
-        await deleteVolume(state.flyApp, config.flyToken, state.flyVolumeId).catch((err) => {
-            console.log(`Warning: failed to delete volume: ${err instanceof Error ? err.message : err}`);
-        });
-        console.log("Volume deleted.");
-    }
-    config.registry.markStopped(state.containerName);
-}
 export function stopContainer(config, containerName) {
     try {
         execFileSync("docker", ["stop", containerName], { stdio: "ignore", timeout: 30000 });

package/dist/fly.d.ts

@@ -11,20 +11,24 @@ export declare function createVolume(app: string, token: string, name: string, s
  * Delete a Fly Volume.
  */
 export declare function deleteVolume(app: string, token: string, volumeId: string): Promise<void>;
+export interface CreateMachineResult {
+    machineId: string;
+    volumeId: string;
+}
 /**
  * Create a Fly Machine with the given image and env vars.
- * If volumeId is provided, it is mounted at /repo.
- * Returns the machine ID.
+ * Creates a volume mounted at /repo for storage.
+ * Returns the machine ID and volume ID.
  */
-export declare function createMachine(app: string, token: string, image: string, env: Record<string, string>, name: string, volumeId?: string): Promise<string>;
+export declare function createMachine(app: string, token: string, image: string, env: Record<string, string>, name: string): Promise<CreateMachineResult>;
 /**
  * Wait for a Fly Machine to reach the "started" state.
  */
 export declare function waitForMachine(app: string, token: string, machineId: string, timeoutMs?: number): Promise<void>;
 /**
- * Destroy a Fly Machine (force).
+ * Destroy a Fly Machine (force) and its attached volume.
  */
-export declare function destroyMachine(app: string, token: string, machineId: string): Promise<void>;
+export declare function destroyMachine(app: string, token: string, machineId: string, volumeId?: string): Promise<void>;
 export interface FlyMachineInfo {
     id: string;
     name: string;

package/dist/fly.js

@@ -78,39 +78,48 @@ export async function deleteVolume(app, token, volumeId) {
 }
 /**
  * Create a Fly Machine with the given image and env vars.
- * If volumeId is provided, it is mounted at /repo.
- * Returns the machine ID.
+ * Creates a volume mounted at /repo for storage.
+ * Returns the machine ID and volume ID.
  */
-export async function createMachine(app, token, image, env, name, volumeId) {
-    const config = {
-        image,
-        env,
-        auto_destroy: true,
-        restart: { policy: "no" },
-        guest: {
-            cpu_kind: "performance",
-            cpus: 16,
-            memory_mb: 32768,
-        },
-        services: [
-            {
-                ports: [{ port: 443, handlers: ["tls", "http"] }],
-                protocol: "tcp",
-                internal_port: 3000,
-                autostart: false,
-                autostop: "off",
-            },
-        ],
-    };
-    if (volumeId) {
-        config.mounts = [{ volume: volumeId, path: "/repo" }];
+export async function createMachine(app, token, image, env, name) {
+    // Create a volume for /repo storage
+    const volumeId = await createVolume(app, token, `repo-${name}`, 50);
+    try {
+        const res = await flyFetch(`/apps/${app}/machines`, token, {
+            method: "POST",
+            body: JSON.stringify({
+                name,
+                config: {
+                    image,
+                    env,
+                    auto_destroy: true,
+                    restart: { policy: "no" },
+                    guest: {
+                        cpu_kind: "performance",
+                        cpus: 16,
+                        memory_mb: 32768,
+                    },
+                    mounts: [{ volume: volumeId, path: "/repo" }],
+                    services: [
+                        {
+                            ports: [{ port: 443, handlers: ["tls", "http"] }],
+                            protocol: "tcp",
+                            internal_port: 3000,
+                            autostart: false,
+                            autostop: "off",
+                        },
+                    ],
+                },
+            }),
+        });
+        const data = (await res.json());
+        return { machineId: data.id, volumeId };
+    }
+    catch (err) {
+        // Clean up volume if machine creation fails
+        await deleteVolume(app, token, volumeId).catch(() => { });
+        throw err;
     }
-    const res = await flyFetch(`/apps/${app}/machines`, token, {
-        method: "POST",
-        body: JSON.stringify({ name, config }),
-    });
-    const data = (await res.json());
-    return data.id;
 }
 /**
  * Wait for a Fly Machine to reach the "started" state.
@@ -130,12 +139,17 @@ export async function waitForMachine(app, token, machineId, timeoutMs = 180000)
     throw new Error(`Machine ${machineId} did not reach started state within ${timeoutMs / 1000}s`);
 }
 /**
- * Destroy a Fly Machine (force).
+ * Destroy a Fly Machine (force) and its attached volume.
  */
-export async function destroyMachine(app, token, machineId) {
+export async function destroyMachine(app, token, machineId, volumeId) {
     await flyFetch(`/apps/${app}/machines/${machineId}?force=true`, token, {
         method: "DELETE",
     });
+    if (volumeId) {
+        await deleteVolume(app, token, volumeId).catch((err) => {
+            console.log(`Warning: failed to delete volume ${volumeId}: ${err instanceof Error ? err.message : err}`);
+        });
+    }
 }
 /**
  * List all machines for a Fly app.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio/app-building",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Library for managing agentic app-building containers",
   "type": "module",
   "exports": {