@replayio/app-building 1.0.1 → 1.0.3

package/README.md

@@ -1,92 +1,124 @@
-# 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.
-
-Core ideas:
-
-* 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.
-
-Containers can run locally or remotely.
-
-## Setup
+## Install
 
 ```bash
-npm install
+npm install @replayio/app-building
 ```
 
-Copy `.env.example` to `.env` and fill in all required API keys.
+## Usage
+
+```ts
+import {
+  loadDotEnv,
+  ContainerRegistry,
+  type ContainerConfig,
+  type RepoOptions,
+  startContainer,
+  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",
+  envVars,
+  registry: new ContainerRegistry("/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);
+```
 
-## Running the Agent
+## Exported API
 
-`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
+### Domain objects
 
-### Detached mode
+| Export | Description |
+|---|---|
+| `ContainerConfig` | Interface bundling all external state: `projectRoot`, `envVars`, `registry`, optional `flyToken`/`flyApp`/`imageRef`. |
+| `RepoOptions` | Per-invocation git settings: `repoUrl`, `cloneBranch`, `pushBranch`. |
+| `ContainerRegistry` | Class encapsulating `.container-registry.jsonl` persistence. Methods: `log`, `markStopped`, `clearStopped`, `getRecent`, `find`, `findAlive`. |
 
-```bash
-npm run agent
-npm run agent -- -p "<prompt>"
-npm run agent -- --branch dev --push-branch feature/xyz -p "<prompt>"
-```
+### Container lifecycle
 
-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.
+| 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. |
 
-### Interactive mode
+**Types:** `AgentState`, `ContainerConfig`, `RepoOptions`
 
-```bash
-npm run agent -- -i
-```
-
-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.
+### Container registry (`ContainerRegistry` class)
 
-### Checking status
+| 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. |
 
-```bash
-npm run status
-```
+**Types:** `RegistryEntry`
 
-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.
+### HTTP client
 
-### Stopping the agent
-
-```bash
-npm run stop
-npm run stop -- <containerName>
-```
+| 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. |
 
-Sends an HTTP stop signal. Without arguments, finds and stops all running containers. Pass a container name to stop a specific one.
+**Types:** `HttpOptions`
 
-## Skills
+### Container utilities
 
-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:
+| 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`. |
 
-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.
+### Fly.io machines
 
-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.
+| 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. |
 
-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.
+**Types:** `FlyMachineInfo`
 
-Key things to watch out for:
+### Image ref
 
-* 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.
+| Export | Description |
+|---|---|
+| `getImageRef()` | Returns `CONTAINER_IMAGE_REF` env var, or `ghcr.io/replayio/app-building:latest` by default. Used by `startRemoteContainer`. |

package/package.json

@@ -1,35 +1,18 @@
 {
   "name": "@replayio/app-building",
-  "version": "1.0.1",
-  "description": "Simple agent loop for building apps with Claude Code CLI",
+  "version": "1.0.3",
+  "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"
   }
 }