@replayio/app-building 1.18.0 → 1.19.0

package/README.md

@@ -15,12 +15,11 @@ import {
   loadDotEnv,
   FileContainerRegistry,
   getInfisicalConfig,
-  createMachine,
-  destroyMachine,
+  startContainer,
+  stopContainer,
   type ContainerConfig,
   type RepoOptions,
   httpGet,
-  httpPost,
   httpOptsFor,
 } from "@replayio/app-building";
 
@@ -28,36 +27,41 @@ import {
 const orchestrationVars = loadDotEnv("/path/to/project");
 const infisicalConfig = await getInfisicalConfig(orchestrationVars);
 
+// Local container (no flyToken/flyApp)
 const config: ContainerConfig = {
-  projectRoot: "/path/to/project",  // optional — only needed for local Docker operations
+  projectRoot: "/path/to/project",
   infisical: infisicalConfig,
   registry: new FileContainerRegistry("/path/to/.container-registry.jsonl"),
+};
+
+// Remote container (set flyToken + flyApp)
+const remoteConfig: ContainerConfig = {
+  ...config,
   flyToken: orchestrationVars.FLY_API_TOKEN,
   flyApp: orchestrationVars.FLY_APP_NAME,
 };
 
-// Create a Fly machine (automatically provisions a volume)
-const { machineId, volumeId } = await createMachine(
-  config.flyApp, config.flyToken, imageRef, containerEnv, machineName,
-);
+// Start — automatically chooses local or remote based on config
+const repo: RepoOptions = { repoUrl: "https://...", cloneBranch: "main", pushBranch: "feature/x" };
+const state = await startContainer(config, repo);
 
 // Check status
-const status = await httpGet(`https://${config.flyApp}.fly.dev/status`);
+const status = await httpGet(`${state.baseUrl}/status`, httpOptsFor(state));
 
 // Query the registry
 const alive = await config.registry.findAlive();
 
-// Clean up (destroys machine and its volume)
-await destroyMachine(config.flyApp, config.flyToken, machineId, volumeId);
+// Stop — handles both local and remote
+await stopContainer(config, state);
 ```
 
 ## Secrets architecture
 
 Secrets are never passed directly to the container or agent. Instead:
 
-1. The orchestration host passes **Infisical credentials** (token, project ID, environment) to the container.
-2. At startup, the container fetches all secrets from Infisical and stores them in memory.
-3. A **secrets server** (`127.0.0.1:9119`) runs inside the container, accessible only locally.
+1. The orchestration host passes **Infisical credentials** (`InfisicalConfig`) to the container via `ContainerConfig.infisical`.
+2. At startup, the container fetches global secrets from Infisical for internal use (clone token, agent API key).
+3. A **secrets server** (`127.0.0.1:9119`) runs inside the container, accessible only locally. It fetches secrets live from Infisical on every request — no caching.
 4. The agent process runs with a **restricted environment** — only `ANTHROPIC_API_KEY` (required for the Claude CLI) is present.
 5. When the agent needs to run a command that requires secrets, it uses `exec-secrets`:
 
@@ -66,9 +70,9 @@ exec-secrets NEON_API_KEY -- curl -s -H "Authorization: Bearer $NEON_API_KEY" ht
 exec-secrets NETLIFY_AUTH_TOKEN NETLIFY_ACCOUNT_SLUG -- netlify deploy --prod
 ```
 
-The secrets server spawns the command with the requested secrets in its environment and **redacts all secret values** from the output.
+The secrets server spawns the command with the requested secrets in its environment and **redacts requested secret values** from the output.
 
-The agent can also run `list-secrets` to see which secrets are available, and `set-branch-secret` to store new branch-level secrets (e.g., `DATABASE_URL` created at deploy time). The server rejects values that have already appeared in logs.
+The agent can also run `list-secrets` to see which secrets are available, and `set-branch-secret` to store new branch-level secrets (e.g., `DATABASE_URL` created at deploy time). The server rejects credential values that have already appeared in logs.
 
 ## Exported API
 
@@ -76,8 +80,9 @@ The agent can also run `list-secrets` to see which secrets are available, and `s
 
 | Export | Description |
 |---|---|
-| `ContainerConfig` | Interface bundling all external state: `infisical` (required `InfisicalConfig`), optional `projectRoot` (only needed for local Docker operations), `registry`, optional `flyToken`/`flyApp`/`imageRef`/`webhookUrl`/`webhookSecret`/`detached`/`initialPrompt`/`localPort`/`absorbTasks`. See [Webhooks](#webhooks) and [Container lifecycle](#container-lifecycle) below. |
+| `ContainerConfig` | `infisical` (required `InfisicalConfig`), optional `projectRoot` (local Docker only), `registry`, `flyToken`/`flyApp` (set both for remote Fly.io), `imageRef`, `webhookUrl`/`webhookSecret`, `detached`, `initialPrompt`, `localPort`, `absorbTasks`. |
 | `RepoOptions` | Per-invocation git settings: `repoUrl`, `cloneBranch`, `pushBranch`. |
+| `AgentState` | Returned by `startContainer`. Contains `type`, `containerName`, `port`, `baseUrl`, and Fly-specific fields for remote containers. |
 | `ContainerRegistry` | Interface for container registry storage. Methods: `log`, `markStopped`, `clearStopped`, `getRecent`, `find`, `findAlive`. |
 | `FileContainerRegistry` | Built-in file-backed implementation of `ContainerRegistry`, backed by a `.jsonl` file. |
 
@@ -85,14 +90,12 @@ The agent can also run `list-secrets` to see which secrets are available, and `s
 
 | Export | Description |
 |---|---|
-| `startContainer(config, repo)` | Build the Docker image locally and start a container with `--network host`. Returns `AgentState`. |
-| `stopContainer(config, containerName)` | Stop a local Docker container by name. |
-| `buildImage(config)` | Build the Docker image locally (called automatically by `startContainer`). |
-| `spawnTestContainer(config)` | Start an interactive (`-it`) container with the repo mounted at `/repo`. |
+| `startContainer(config, repo)` | Start a container. Uses local Docker if `flyToken`/`flyApp` are not set, Fly.io if they are. Returns `AgentState`. |
+| `stopContainer(config, state)` | Stop a container by its `AgentState` or `RegistryEntry`. Handles both local and remote. |
+| `buildImage(config)` | Build the Docker image locally (called automatically by `startContainer` for local containers). |
+| `spawnTestContainer(config)` | Start an interactive (`-it`) local container with the repo mounted at `/repo`. |
 | `loadDotEnv(projectRoot)` | Parse a `.env` file and return key-value pairs. |
 
-**Types:** `AgentState`, `ContainerConfig`, `RepoOptions`
-
 ### Container registry (`ContainerRegistry` interface / `FileContainerRegistry` class)
 
 | Method | Description |
@@ -122,20 +125,6 @@ The agent can also run `list-secrets` to see which secrets are available, and `s
 | `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 utilities
-
-| Export | Description |
-|---|---|
-| `createApp(token, name, org?)` | Create a Fly app and allocate IPs. |
-| `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. |
-| `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`, `CreateMachineResult`
-
 ### Secrets (Infisical)
 
 | Export | Description |
@@ -144,25 +133,11 @@ The agent can also run `list-secrets` to see which secrets are available, and `s
 | `getInfisicalConfig(envVars)` | Extract `InfisicalConfig` from env vars and log in. Requires `INFISICAL_CLIENT_ID`, `INFISICAL_CLIENT_SECRET`, `INFISICAL_PROJECT_ID`, `INFISICAL_ENVIRONMENT`. |
 | `fetchGlobalSecrets(config)` | Fetch secrets from the `/global/` path. |
 | `fetchBranchSecrets(config, branch)` | Fetch secrets from `/branches/<branch>/`. |
-| `createBranchSecret(config, branch, name, value)` | Create or update a secret in `/branches/<branch>/`. |
+| `createBranchSecret(config, branch, name, value)` | Create or update a secret in `/branches/<branch>/`. Creates the folder if needed. |
 | `fetchInfisicalSecrets(config, path)` | Raw fetch from any Infisical folder path. |
 
 **Types:** `InfisicalConfig`
 
-**Usage pattern** (orchestration scripts):
-
-```ts
-const orchestrationVars = loadDotEnv(projectRoot);
-const infisicalConfig = await getInfisicalConfig(orchestrationVars);
-
-const config: ContainerConfig = {
-  infisical: infisicalConfig,
-  flyToken: orchestrationVars.FLY_API_TOKEN,
-  flyApp: orchestrationVars.FLY_APP_NAME,
-  ...
-};
-```
-
 ### Image ref
 
 | Export | Description |

package/dist/container.d.ts

@@ -1,4 +1,4 @@
-import type { ContainerRegistry } from "./container-registry";
+import type { ContainerRegistry, RegistryEntry } from "./container-registry";
 import type { InfisicalConfig } from "./secrets";
 export interface AgentState {
     type: "local" | "remote";
@@ -35,6 +35,16 @@ export interface RepoOptions {
 }
 export declare function loadDotEnv(projectRoot: string): Record<string, string>;
 export declare function buildImage(config: ContainerConfig): void;
+/**
+ * Start a container (local Docker or remote Fly.io based on config).
+ * If flyToken and flyApp are set, starts remotely; otherwise locally.
+ */
 export declare function startContainer(config: ContainerConfig, repo: RepoOptions): Promise<AgentState>;
-export declare function stopContainer(config: ContainerConfig, containerName: string): void;
+/**
+ * Stop a container by its state or registry entry.
+ */
+export declare function stopContainer(config: ContainerConfig, state: AgentState | RegistryEntry): Promise<void>;
+/**
+ * Spawn an interactive test container (local only).
+ */
 export declare function spawnTestContainer(config: ContainerConfig): Promise<void>;

package/dist/container.js

@@ -1,6 +1,8 @@
 import { execFileSync, spawn } from "child_process";
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
+import { createMachine, waitForMachine, destroyMachine, listMachines } from "./fly";
+import { getImageRef } from "./image-ref";
 const IMAGE_NAME = "app-building";
 function debugLog(...args) {
     if (process.env.DEBUG)
@@ -73,13 +75,6 @@ function findFreePort() {
     }
     return port;
 }
-function infisicalEnvVars(config) {
-    return {
-        INFISICAL_TOKEN: config.token,
-        INFISICAL_PROJECT_ID: config.projectId,
-        INFISICAL_ENVIRONMENT: config.environment,
-    };
-}
 function buildContainerEnv(repo, infisical, extra = {}) {
     const env = {
         REPO_URL: repo.repoUrl,
@@ -90,7 +85,9 @@ function buildContainerEnv(repo, infisical, extra = {}) {
         GIT_COMMITTER_NAME: "App Builder",
         GIT_COMMITTER_EMAIL: "app-builder@localhost",
         PLAYWRIGHT_BROWSERS_PATH: "/opt/playwright",
-        ...infisicalEnvVars(infisical),
+        INFISICAL_TOKEN: infisical.token,
+        INFISICAL_PROJECT_ID: infisical.projectId,
+        INFISICAL_ENVIRONMENT: infisical.environment,
         ...extra,
     };
     if (process.env.DEBUG) {
@@ -98,23 +95,9 @@ function buildContainerEnv(repo, infisical, extra = {}) {
     }
     return env;
 }
-export async function startContainer(config, repo) {
-    debugLog("startContainer 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,
-    });
-    debugLog("startContainer repo:", repo);
-    buildImage(config);
-    const uniqueId = Math.random().toString(36).slice(2, 8);
-    const containerName = `app-building-${uniqueId}`;
-    const containerPort = 3000;
-    const hostPort = config.localPort ?? findFreePort();
+function buildExtraEnv(config, containerName) {
     const extra = {
-        PORT: String(containerPort),
+        PORT: "3000",
         CONTAINER_NAME: containerName,
     };
     if (config.webhookUrl)
@@ -127,35 +110,44 @@ export async function startContainer(config, repo) {
         extra.INITIAL_PROMPT = config.initialPrompt;
     if (config.absorbTasks)
         extra.ABSORB_TASKS = "1";
+    return extra;
+}
+function isRemote(config) {
+    return !!(config.flyToken && config.flyApp);
+}
+// ---------------------------------------------------------------------------
+// Local container
+// ---------------------------------------------------------------------------
+async function startLocalContainer(config, repo) {
+    buildImage(config);
+    const uniqueId = Math.random().toString(36).slice(2, 8);
+    const containerName = `app-building-${uniqueId}`;
+    const containerPort = 3000;
+    const hostPort = config.localPort ?? findFreePort();
+    const extra = buildExtraEnv(config, containerName);
+    extra.PORT = String(containerPort);
     const containerEnv = buildContainerEnv(repo, config.infisical, extra);
-    // Build docker run args
     const args = ["run", "-d", "--rm", "--name", containerName];
-    // Use explicit port mapping for macOS Docker Desktop compatibility
-    // (--network host only works on Linux)
     args.push("-p", `${hostPort}:${containerPort}`);
     for (const [k, v] of Object.entries(containerEnv)) {
         args.push("--env", `${k}=${v}`);
     }
-    // Image name — CMD is baked in (server.ts)
     args.push(IMAGE_NAME);
     const containerId = execFileSync("docker", args, {
         encoding: "utf-8",
         timeout: 30000,
     }).trim();
     console.log(`Container started: ${containerId.slice(0, 12)} (${containerName})`);
-    // Wait for the HTTP server to become ready
     const baseUrl = `http://127.0.0.1:${hostPort}`;
-    const maxWait = 120000; // clone can take a while
+    const maxWait = 120000;
     const interval = 1000;
     const start = Date.now();
     let ready = false;
     while (Date.now() - start < maxWait) {
-        // Check if the container is still alive (--rm removes it on exit)
         try {
             execFileSync("docker", ["inspect", "--format", "{{.State.Running}}", containerName], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5000 });
         }
         catch {
-            // Container is gone — grab logs from docker if possible, otherwise just report
             let logs = "";
             try {
                 logs = execFileSync("docker", ["logs", "--tail", "30", containerName], {
@@ -183,26 +175,151 @@ export async function startContainer(config, repo) {
     if (!ready) {
         throw new Error("Container did not become ready within timeout");
     }
-    const agentState = { type: "local", containerName, port: hostPort, baseUrl };
-    config.registry.log(agentState);
-    return agentState;
+    return { type: "local", containerName, port: hostPort, baseUrl };
 }
-export function stopContainer(config, containerName) {
+function stopLocalContainer(containerName) {
     try {
         execFileSync("docker", ["stop", containerName], { stdio: "ignore", timeout: 30000 });
     }
     catch {
         // Container may already be stopped
     }
-    config.registry.markStopped(containerName);
 }
+// ---------------------------------------------------------------------------
+// Remote container (Fly.io)
+// ---------------------------------------------------------------------------
+async function startRemoteContainerImpl(config, 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}`;
+    const extra = buildExtraEnv(config, machineName);
+    const containerEnv = buildContainerEnv(repo, config.infisical, extra);
+    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}`);
+        }
+    }
+    console.log("Creating Fly machine (with volume)...");
+    let machineId = "";
+    let volumeId = "";
+    for (let attempt = 0; attempt < 5; attempt++) {
+        try {
+            const result = await createMachine(config.flyApp, config.flyToken, imageRef, containerEnv, machineName);
+            machineId = result.machineId;
+            volumeId = result.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;
+            }
+            throw err;
+        }
+    }
+    console.log(`Machine created: ${machineId} (volume: ${volumeId})`);
+    const baseUrl = `https://${config.flyApp}.fly.dev`;
+    const agentState = {
+        type: "remote",
+        containerName: machineName,
+        port: 443,
+        baseUrl,
+        flyApp: config.flyApp,
+        flyMachineId: machineId,
+        flyVolumeId: volumeId,
+    };
+    console.log("Waiting for machine to start...");
+    await waitForMachine(config.flyApp, config.flyToken, machineId);
+    console.log("Machine started.");
+    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) {
+        console.log("Timed out waiting for machine, destroying...");
+        await destroyMachine(config.flyApp, config.flyToken, machineId, volumeId).catch(() => { });
+        throw new Error("Remote container did not become ready within timeout");
+    }
+    return agentState;
+}
+async function stopRemoteContainerImpl(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, state.flyVolumeId);
+    console.log("Machine destroyed.");
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Start a container (local Docker or remote Fly.io based on config).
+ * If flyToken and flyApp are set, starts remotely; otherwise locally.
+ */
+export async function startContainer(config, repo) {
+    debugLog("startContainer config:", {
+        projectRoot: config.projectRoot,
+        flyApp: config.flyApp,
+        imageRef: config.imageRef,
+        webhookUrl: config.webhookUrl,
+        detached: config.detached,
+        remote: isRemote(config),
+        initialPrompt: config.initialPrompt ? `${config.initialPrompt.slice(0, 100)}...` : undefined,
+    });
+    debugLog("startContainer repo:", repo);
+    const state = isRemote(config)
+        ? await startRemoteContainerImpl(config, repo)
+        : await startLocalContainer(config, repo);
+    config.registry.log(state);
+    return state;
+}
+/**
+ * Stop a container by its state or registry entry.
+ */
+export async function stopContainer(config, state) {
+    if (state.type === "remote") {
+        await stopRemoteContainerImpl(config, state);
+    }
+    else {
+        stopLocalContainer(state.containerName);
+    }
+    config.registry.markStopped(state.containerName);
+}
+/**
+ * Spawn an interactive test container (local only).
+ */
 export function spawnTestContainer(config) {
     if (!config.projectRoot)
         throw new Error("projectRoot is required for local Docker operations");
     ensureImageExists(config.projectRoot);
     const uniqueId = Math.random().toString(36).slice(2, 8);
     const containerName = `app-building-test-${uniqueId}`;
-    const infisicalVars = infisicalEnvVars(config.infisical);
     const args = ["run", "-it", "--rm", "--name", containerName];
     args.push("-v", `${config.projectRoot}:/repo`);
     args.push("-w", "/repo");
@@ -210,9 +327,9 @@ export function spawnTestContainer(config) {
     args.push("--user", `${process.getuid()}:${process.getgid()}`);
     args.push("--env", "HOME=/repo/.agent-home");
     args.push("--env", "PLAYWRIGHT_BROWSERS_PATH=/opt/playwright");
-    for (const [k, v] of Object.entries(infisicalVars)) {
-        args.push("--env", `${k}=${v}`);
-    }
+    args.push("--env", `INFISICAL_TOKEN=${config.infisical.token}`);
+    args.push("--env", `INFISICAL_PROJECT_ID=${config.infisical.projectId}`);
+    args.push("--env", `INFISICAL_ENVIRONMENT=${config.infisical.environment}`);
     args.push(IMAGE_NAME, "bash");
     return new Promise((resolvePromise, reject) => {
         const child = spawn("docker", args, { stdio: "inherit" });

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export * from "./fly";
 export * from "./container";
 export * from "./container-registry";
 export * from "./container-utils";

package/dist/index.js

@@ -1,4 +1,3 @@
-export * from "./fly";
 export * from "./container";
 export * from "./container-registry";
 export * from "./container-utils";

package/package.json

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