@replayio/app-building 1.0.2 → 1.1.0

package/README.md

@@ -1,92 +1,175 @@
-# app-building
+# @replayio/app-building
 
-Simple and extensible platform for dark factory agentic app building: creating apps
-according to a spec without human involvement along the way. Example use cases:
+Library for managing agentic app-building containers. Start and stop containers locally (Docker) or remotely (Fly.io), communicate with the in-container HTTP server, and track container state via a local registry.
 
-* `npm run agent -- -p "Build me an app XYZ based on this spec: ..."`
-* `npm run agent -- -p "Continue maintaining app XYZ and fix these bugs: ..."`
-* `npm run agent -- -i` for interactive access to the agent.
+## Install
 
-Core ideas:
+```bash
+npm install @replayio/app-building
+```
 
-* The agent runs within a docker container that clones the target repo and exposes an HTTP server for control.
-* The host communicates with the container via HTTP — sending prompts, polling events/logs, and managing lifecycle.
-* The agent builds by following a set of skill documents with guides
-  for breaking its work down into jobs and directives for performing those tasks.
-* The agent commits logs for it to review later and improve its skills.
-* All code changes are committed and pushed back to the remote from inside the container.
+## Usage
+
+```ts
+import {
+  loadDotEnv,
+  FileContainerRegistry,
+  type ContainerConfig,
+  type RepoOptions,
+  startRemoteContainer,
+  stopRemoteContainer,
+  httpGet,
+  httpPost,
+  httpOptsFor,
+} from "@replayio/app-building";
+
+// Assemble config once at startup
+const envVars = loadDotEnv("/path/to/project");
+const config: ContainerConfig = {
+  projectRoot: "/path/to/project",  // optional — only needed for local Docker operations
+  envVars,
+  registry: new FileContainerRegistry("/path/to/.container-registry.jsonl"),
+  flyToken: envVars.FLY_API_TOKEN,
+  flyApp: envVars.FLY_APP_NAME,
+};
+
+// Start a remote container
+const repo: RepoOptions = { repoUrl: "https://github.com/...", cloneBranch: "main", pushBranch: "main" };
+const state = await startRemoteContainer(config, repo);
+
+// Send a prompt and wait for completion
+const httpOpts = httpOptsFor(state);
+const { id } = await httpPost(`${state.baseUrl}/message`, { prompt: "Build the app" }, httpOpts);
+
+// Check status
+const status = await httpGet(`${state.baseUrl}/status`, httpOpts);
+
+// Query the registry
+const alive = await config.registry.findAlive();
+
+// Clean up
+await stopRemoteContainer(config, state);
+```
 
-Containers can run locally or remotely.
+## Exported API
 
-## Setup
+### Domain objects
 
-```bash
-npm install
-```
+| Export | Description |
+|---|---|
+| `ContainerConfig` | Interface bundling all external state: optional `projectRoot` (only needed for local Docker operations), `envVars`, `registry`, optional `flyToken`/`flyApp`/`imageRef`/`webhookUrl`. See [Webhooks](#webhooks) below. |
+| `RepoOptions` | Per-invocation git settings: `repoUrl`, `cloneBranch`, `pushBranch`. |
+| `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. |
 
-Copy `.env.example` to `.env` and fill in all required API keys.
+### Container lifecycle
 
-## Running the Agent
+| 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. |
 
-`npm run agent` starts a new container with the running agent. By default the container is local, add `--remote` to spawn the container remotely. This requires FLY_API_TOKEN in .env
+**Types:** `AgentState`, `ContainerConfig`, `RepoOptions`
 
-### Detached mode
+### Container registry (`ContainerRegistry` interface / `FileContainerRegistry` class)
 
-```bash
-npm run agent
-npm run agent -- -p "<prompt>"
-npm run agent -- --branch dev --push-branch feature/xyz -p "<prompt>"
-```
+| Method | Description |
+|---|---|
+| `log(state)` | Append a new entry to the registry. |
+| `markStopped(name?)` | Mark a container as stopped. |
+| `clearStopped(name)` | Clear the stopped flag (container came back alive). |
+| `getRecent(limit?)` | Read the most recent registry entries. |
+| `find(name)` | Find a specific container by name. |
+| `findAlive()` | Probe recent entries and return those that are alive. Reconciles stopped flags. |
 
-Starts a container, optionally queues a prompt, then detaches. The container processes the prompt followed by any pending tasks, commits and pushes results, then exits.
+**Types:** `RegistryEntry`
 
-### Interactive mode
+### HTTP client
 
-```bash
-npm run agent -- -i
-```
+| Export | Description |
+|---|---|
+| `httpGet(url, opts?)` | GET with retries and timeout. Returns parsed JSON. |
+| `httpPost(url, body?, opts?)` | POST with retries and timeout. Returns parsed JSON. |
 
-Chat with the agent inside a container. Output is streamed via event polling. Press ESC to interrupt the current message. On exit, the container is detached and finishes any remaining work.
+**Types:** `HttpOptions`
 
-### Checking status
+### Container utilities
 
-```bash
-npm run status
-```
+| Export | Description |
+|---|---|
+| `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`. |
 
-Connects to the running container's HTTP API and shows state, revision, queue depth, cost, and recent log output. Tails logs in real-time (Ctrl+C to stop). Errors if no agent is running.
+### Fly.io machines
 
-### Stopping the agent
+| Export | Description |
+|---|---|
+| `createApp(token, name, org?)` | Create a Fly app and allocate IPs. |
+| `createMachine(app, token, image, env, name)` | Create a Fly machine. Returns machine ID. |
+| `waitForMachine(app, token, machineId, timeout?)` | Wait for a machine to reach `started` state. |
+| `destroyMachine(app, token, machineId)` | Force-destroy a machine. |
+| `listMachines(app, token)` | List all machines for an app. |
 
-```bash
-npm run stop
-npm run stop -- <containerName>
-```
+**Types:** `FlyMachineInfo`
 
-Sends an HTTP stop signal. Without arguments, finds and stops all running containers. Pass a container name to stop a specific one.
+### Image ref
 
-## Skills
+| Export | Description |
+|---|---|
+| `getImageRef()` | Returns `CONTAINER_IMAGE_REF` env var, or `ghcr.io/replayio/app-building:latest` by default. Used by `startRemoteContainer`. |
 
-The provided skill documents emphasize a structured approach for autonomously building
-high quality, well tested apps from the initial spec. During the initial app build
-it does the following:
+## Webhooks
 
-1. Designs a comprehensive test specification based on the initial spec.
-2. Builds the app and writes tests to match the spec.
-3. Gets all the tests to pass, deploys to production, and does further testing.
+Set `webhookUrl` on `ContainerConfig` to receive real-time notifications of container activity. The container POSTs fire-and-forget JSON to that URL on key events (no retries, failures are silently ignored).
 
-The initial build will not come out perfect. The agent can followup with maintenance passes
-where it checks to make sure it closely followed the spec and skill directives and fixes
-any issues it finds. It will also fix reported bugs and update the skills to avoid
-similar problems in the future.
+### Payload format
 
-As long as each individual step the agent takes is within its capabilities (it can usually
-do it but not always) the agent will converge on an app that follows the initial spec
-and skill directives.
+Every POST body has this shape:
 
-Key things to watch out for:
+```json
+{
+  "type": "container.started",
+  "containerName": "app-building-abc123",
+  "timestamp": "2026-02-28T12:00:00.000Z",
+  "data": { ... }
+}
+```
 
-* Best suited for CRUD and API-calling apps up to a medium level of complexity.
-  Overly complicated or specialized apps will not work as well yet.
-* Make sure to get a Replay API key and configure it. The agent will use Replay to identify
-  and debug problems it encounters in tests or the deployed app.
+| Field | Type | Description |
+|---|---|---|
+| `type` | `string` | Event type (see table below). |
+| `containerName` | `string` | Name of the container that emitted the event. |
+| `timestamp` | `string` | ISO-8601 timestamp. |
+| `data` | `object` | Event-specific payload. Present on all events; contents vary by type. |
+
+### Events
+
+| Type | When | `data` fields |
+|---|---|---|
+| `container.started` | HTTP server is listening | `pushBranch`, `revision` |
+| `container.idle` | State transitions to idle | `pendingTasks`, `queueLength` |
+| `container.processing` | State transitions to processing | `iteration` |
+| `container.stopping` | State transitions to stopping | _(empty)_ |
+| `container.stopped` | State transitions to stopped | _(empty)_ |
+| `message.queued` | `POST /message` received | `messageId`, `prompt` |
+| `message.done` | Message processing complete | `messageId`, `cost_usd`, `duration_ms`, `num_turns` |
+| `message.error` | Message processing failed | `messageId`, `error` |
+| `task.started` | Task processing begins | `pendingTasks` |
+| `task.done` | Task processing complete | `tasksProcessed`, `totalCost` |
+| `log` | Each log line | `line` |
+
+### Example
+
+```ts
+const config: ContainerConfig = {
+  projectRoot: "/path/to/project",
+  envVars: loadDotEnv("/path/to/project"),
+  registry: new FileContainerRegistry("/path/to/.container-registry.jsonl"),
+  webhookUrl: "https://example.com/hooks/container-events",
+};
+```

package/dist/{package/container-registry.d.ts → container-registry.d.ts}

@@ -3,7 +3,15 @@ export interface RegistryEntry extends AgentState {
     startedAt: string;
     stoppedAt?: string;
 }
-export declare class ContainerRegistry {
+export interface ContainerRegistry {
+    log(state: AgentState): void;
+    markStopped(containerName?: string): void;
+    clearStopped(containerName: string): void;
+    getRecent(limit?: number): RegistryEntry[];
+    find(containerName: string): RegistryEntry | null;
+    findAlive(): Promise<RegistryEntry[]>;
+}
+export declare class FileContainerRegistry implements ContainerRegistry {
     private filePath;
     constructor(filePath: string);
     private readRegistry;

package/dist/{package/container-registry.js → container-registry.js}

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync, appendFileSync, existsSync } from "fs";
 import { probeAlive } from "./container-utils";
-export class ContainerRegistry {
+export class FileContainerRegistry {
     filePath;
     constructor(filePath) {
         this.filePath = filePath;

package/dist/{package/container.d.ts → container.d.ts}

@@ -8,12 +8,13 @@ export interface AgentState {
     flyMachineId?: string;
 }
 export interface ContainerConfig {
-    projectRoot: string;
+    projectRoot?: string;
     envVars: Record<string, string>;
     registry: ContainerRegistry;
     flyToken?: string;
     flyApp?: string;
     imageRef?: string;
+    webhookUrl?: string;
 }
 export interface RepoOptions {
     repoUrl: string;

package/dist/{package/container.js → container.js}

@@ -28,6 +28,8 @@ export function loadDotEnv(projectRoot) {
     return vars;
 }
 export function buildImage(config) {
+    if (!config.projectRoot)
+        throw new Error("projectRoot is required for local Docker operations");
     console.log("Building Docker image...");
     execFileSync("docker", ["build", "--network", "host", "-t", IMAGE_NAME, config.projectRoot], {
         stdio: "inherit",
@@ -92,10 +94,13 @@ export async function startContainer(config, repo) {
     const uniqueId = Math.random().toString(36).slice(2, 8);
     const containerName = `app-building-${uniqueId}`;
     const hostPort = findFreePort();
-    const containerEnv = buildContainerEnv(repo, config.envVars, {
+    const extra = {
         PORT: String(hostPort),
         CONTAINER_NAME: containerName,
-    });
+    };
+    if (config.webhookUrl)
+        extra.WEBHOOK_URL = config.webhookUrl;
+    const containerEnv = buildContainerEnv(repo, config.envVars, extra);
     // Build docker run args
     const args = ["run", "-d", "--rm", "--name", containerName];
     // --network host: container shares host network stack (no -p needed)
@@ -163,10 +168,13 @@ export async function startRemoteContainer(config, repo) {
     const uniqueId = Math.random().toString(36).slice(2, 8);
     const machineName = `app-building-${uniqueId}`;
     // Build env vars for the machine
-    const containerEnv = buildContainerEnv(repo, config.envVars, {
+    const remoteExtra = {
         PORT: "3000",
         CONTAINER_NAME: machineName,
-    });
+    };
+    if (config.webhookUrl)
+        remoteExtra.WEBHOOK_URL = config.webhookUrl;
+    const containerEnv = buildContainerEnv(repo, config.envVars, remoteExtra);
     // Remove Fly-specific vars from container env (not needed inside)
     delete containerEnv.FLY_API_TOKEN;
     delete containerEnv.FLY_APP_NAME;
@@ -260,6 +268,8 @@ export function stopContainer(config, containerName) {
     config.registry.markStopped(containerName);
 }
 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}`;

package/package.json

@@ -1,35 +1,18 @@
 {
   "name": "@replayio/app-building",
-  "version": "1.0.2",
-  "description": "Simple agent loop for building apps with Claude Code CLI",
+  "version": "1.1.0",
+  "description": "Library for managing agentic app-building containers",
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/package/index.js",
-      "types": "./dist/package/index.d.ts"
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     }
   },
   "files": [
-    "dist/package"
+    "dist"
   ],
-  "readme": "src/package/README.md",
   "scripts": {
-    "agent": "tsx src/agent.ts",
-    "status": "tsx src/status.ts",
-    "read-log": "tsx src/read-log.ts",
-    "reset-app": "tsx src/reset-app.ts",
-    "docker:build": "docker build --no-cache --network=host -t app-building .",
-    "test-container": "tsx src/test-container.ts",
-    "stop": "tsx src/stop.ts",
-    "fly-machines": "tsx src/fly-machines.ts",
-    "add-task": "tsx scripts/add-task.ts"
-  },
-  "devDependencies": {
-    "@types/node": "^25.3.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.5.0"
-  },
-  "dependencies": {
-    "commander": "^14.0.3"
+    "prepublishOnly": "tsc -p tsconfig.json"
   }
 }