@replayio/app-building 1.17.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,45 +27,41 @@ import {
 const orchestrationVars = loadDotEnv("/path/to/project");
 const infisicalConfig = await getInfisicalConfig(orchestrationVars);
 
-// Only pass Infisical credentials to the container — not actual secrets.
-// The container fetches secrets from Infisical at startup and manages them
-// via an internal secrets server. The agent never has direct access to secrets.
-const containerEnvVars: Record<string, string> = {
-  INFISICAL_TOKEN: infisicalConfig.token,
-  INFISICAL_PROJECT_ID: infisicalConfig.projectId,
-  INFISICAL_ENVIRONMENT: infisicalConfig.environment,
-};
-
+// Local container (no flyToken/flyApp)
 const config: ContainerConfig = {
-  projectRoot: "/path/to/project",  // optional — only needed for local Docker operations
-  envVars: containerEnvVars,
+  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`:
 
@@ -75,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
 
@@ -85,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: optional `projectRoot` (only needed for local Docker operations), `envVars` (Infisical credentials), `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. |
 
@@ -94,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 |
@@ -131,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 |
@@ -153,30 +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);
-
-// Pass only Infisical credentials to the container
-const config: ContainerConfig = {
-  envVars: {
-    INFISICAL_TOKEN: infisicalConfig.token,
-    INFISICAL_PROJECT_ID: infisicalConfig.projectId,
-    INFISICAL_ENVIRONMENT: infisicalConfig.environment,
-  },
-  flyToken: orchestrationVars.FLY_API_TOKEN,
-  flyApp: orchestrationVars.FLY_APP_NAME,
-  ...
-};
-```
-
 ### Image ref
 
 | Export | Description |
@@ -269,11 +230,7 @@ const infisicalConfig = await getInfisicalConfig(orchestrationVars);
 
 const config: ContainerConfig = {
   projectRoot: "/path/to/project",
-  envVars: {
-    INFISICAL_TOKEN: infisicalConfig.token,
-    INFISICAL_PROJECT_ID: infisicalConfig.projectId,
-    INFISICAL_ENVIRONMENT: infisicalConfig.environment,
-  },
+  infisical: infisicalConfig,
   registry: new FileContainerRegistry("/path/to/.container-registry.jsonl"),
   webhookUrl: "https://example.com/hooks/container-events",
   webhookSecret: "your-webhook-secret",

package/dist/container.d.ts

@@ -1,4 +1,5 @@
-import type { ContainerRegistry } from "./container-registry";
+import type { ContainerRegistry, RegistryEntry } from "./container-registry";
+import type { InfisicalConfig } from "./secrets";
 export interface AgentState {
     type: "local" | "remote";
     containerName: string;
@@ -10,7 +11,8 @@ export interface AgentState {
 }
 export interface ContainerConfig {
     projectRoot?: string;
-    envVars: Record<string, string>;
+    /** Infisical credentials — required for all containers. */
+    infisical: InfisicalConfig;
     registry: ContainerRegistry;
     flyToken?: string;
     flyApp?: string;
@@ -33,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,7 +75,7 @@ function findFreePort() {
     }
     return port;
 }
-function buildContainerEnv(repo, envVars, extra = {}) {
+function buildContainerEnv(repo, infisical, extra = {}) {
     const env = {
         REPO_URL: repo.repoUrl,
         CLONE_BRANCH: repo.cloneBranch,
@@ -83,7 +85,9 @@ function buildContainerEnv(repo, envVars, extra = {}) {
         GIT_COMMITTER_NAME: "App Builder",
         GIT_COMMITTER_EMAIL: "app-builder@localhost",
         PLAYWRIGHT_BROWSERS_PATH: "/opt/playwright",
-        ...envVars,
+        INFISICAL_TOKEN: infisical.token,
+        INFISICAL_PROJECT_ID: infisical.projectId,
+        INFISICAL_ENVIRONMENT: infisical.environment,
         ...extra,
     };
     if (process.env.DEBUG) {
@@ -91,24 +95,9 @@ function buildContainerEnv(repo, envVars, 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,
-        envVarKeys: Object.keys(config.envVars),
-    });
-    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)
@@ -121,35 +110,44 @@ export async function startContainer(config, repo) {
         extra.INITIAL_PROMPT = config.initialPrompt;
     if (config.absorbTasks)
         extra.ABSORB_TASKS = "1";
-    const containerEnv = buildContainerEnv(repo, config.envVars, extra);
-    // Build docker run args
+    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);
     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], {
@@ -177,19 +175,145 @@ 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");
@@ -203,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(config.envVars)) {
-        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/dist/secrets.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Infisical secrets API.
+ *
+ * API versions used (per https://infisical.com/docs/api-reference):
+ *   - Auth:    POST /api/v1/auth/universal-auth/login
+ *   - Secrets: GET/POST/PATCH /api/v4/secrets[/{secretName}]
+ *   - Folders: POST /api/v2/folders
+ */
 export interface InfisicalConfig {
     token: string;
     projectId: string;
@@ -5,12 +13,14 @@ export interface InfisicalConfig {
 }
 /**
  * Log in to Infisical using Universal Auth (Client ID + Client Secret).
- * Returns a short-lived access token (default 30 day TTL).
+ * POST /api/v1/auth/universal-auth/login
+ * Returns a short-lived access token.
  */
 export declare function infisicalLogin(clientId: string, clientSecret: string): Promise<string>;
 /**
  * Fetch secrets from an Infisical folder path.
- * Returns a key-value record of secret names to values.
+ * GET /api/v4/secrets?projectId=…&environment=…&secretPath=…
+ * Returns a key→value record.
  */
 export declare function fetchInfisicalSecrets(config: InfisicalConfig, secretPath: string): Promise<Record<string, string>>;
 /**
@@ -23,7 +33,12 @@ export declare function fetchGlobalSecrets(config: InfisicalConfig): Promise<Rec
 export declare function fetchBranchSecrets(config: InfisicalConfig, branch: string): Promise<Record<string, string>>;
 /**
  * Create or update a branch secret in Infisical.
- * Uses POST to create, falls back to PATCH if it already exists.
+ * Creates the folder path if it doesn't exist yet.
+ *
+ *   POST  /api/v4/secrets/{name}   — create
+ *   PATCH /api/v4/secrets/{name}   — update (if secret already exists)
+ *
+ * Body: { projectId, environment, secretPath, secretValue, type }
  */
 export declare function createBranchSecret(config: InfisicalConfig, branch: string, name: string, value: string): Promise<void>;
 /**

package/dist/secrets.js

@@ -1,7 +1,19 @@
+/**
+ * Infisical secrets API.
+ *
+ * API versions used (per https://infisical.com/docs/api-reference):
+ *   - Auth:    POST /api/v1/auth/universal-auth/login
+ *   - Secrets: GET/POST/PATCH /api/v4/secrets[/{secretName}]
+ *   - Folders: POST /api/v2/folders
+ */
 const INFISICAL_API_BASE = "https://app.infisical.com";
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
 /**
  * Log in to Infisical using Universal Auth (Client ID + Client Secret).
- * Returns a short-lived access token (default 30 day TTL).
+ * POST /api/v1/auth/universal-auth/login
+ * Returns a short-lived access token.
  */
 export async function infisicalLogin(clientId, clientSecret) {
     const res = await fetch(`${INFISICAL_API_BASE}/api/v1/auth/universal-auth/login`, {
@@ -16,30 +28,33 @@ export async function infisicalLogin(clientId, clientSecret) {
     const data = (await res.json());
     return data.accessToken;
 }
-async function infisicalFetch(path, config) {
-    const res = await fetch(`${INFISICAL_API_BASE}${path}`, {
-        headers: {
-            Authorization: `Bearer ${config.token}`,
-            "Content-Type": "application/json",
-        },
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new Error(`Infisical API GET ${path} → ${res.status}: ${body}`);
-    }
-    return res;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function authHeaders(config) {
+    return {
+        Authorization: `Bearer ${config.token}`,
+        "Content-Type": "application/json",
+    };
 }
 /**
  * Fetch secrets from an Infisical folder path.
- * Returns a key-value record of secret names to values.
+ * GET /api/v4/secrets?projectId=…&environment=…&secretPath=…
+ * Returns a key→value record.
  */
 export async function fetchInfisicalSecrets(config, secretPath) {
     const params = new URLSearchParams({
-        workspaceId: config.projectId,
+        projectId: config.projectId,
         environment: config.environment,
         secretPath,
     });
-    const res = await infisicalFetch(`/api/v3/secrets/raw?${params}`, config);
+    const res = await fetch(`${INFISICAL_API_BASE}/api/v4/secrets?${params}`, {
+        headers: authHeaders(config),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Infisical GET secrets ${secretPath} → ${res.status}: ${body}`);
+    }
     const data = (await res.json());
     const secrets = {};
     for (const s of data.secrets) {
@@ -59,24 +74,66 @@ export async function fetchGlobalSecrets(config) {
 export async function fetchBranchSecrets(config, branch) {
     return fetchInfisicalSecrets(config, `/branches/${branch}/`);
 }
+// ---------------------------------------------------------------------------
+// Folders
+// ---------------------------------------------------------------------------
+/**
+ * Ensure all folders in a path exist, creating any missing ones.
+ * POST /api/v2/folders  — body: { projectId, environment, name, path }
+ *
+ * Infisical requires folders to exist before secrets can be written into them.
+ * We walk each segment of the path and issue a create; a 400 response means
+ * the folder already exists (the docs list 400 for "Bad Request" which
+ * Infisical returns for duplicate folder names).
+ */
+async function ensureFolder(config, folderPath) {
+    const segments = folderPath.split("/").filter(Boolean);
+    let parentPath = "/";
+    for (const segment of segments) {
+        const res = await fetch(`${INFISICAL_API_BASE}/api/v2/folders`, {
+            method: "POST",
+            headers: authHeaders(config),
+            body: JSON.stringify({
+                projectId: config.projectId,
+                environment: config.environment,
+                name: segment,
+                path: parentPath,
+            }),
+        });
+        // 200 = created. 400 = folder already exists (Infisical returns 400 for
+        // duplicate folder names under the same parent).
+        if (res.ok || res.status === 400) {
+            parentPath += segment + "/";
+            continue;
+        }
+        const text = await res.text().catch(() => "");
+        throw new Error(`Infisical create folder ${parentPath}${segment} → ${res.status}: ${text}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Secrets — write
+// ---------------------------------------------------------------------------
 /**
  * Create or update a branch secret in Infisical.
- * Uses POST to create, falls back to PATCH if it already exists.
+ * Creates the folder path if it doesn't exist yet.
+ *
+ *   POST  /api/v4/secrets/{name}   — create
+ *   PATCH /api/v4/secrets/{name}   — update (if secret already exists)
+ *
+ * Body: { projectId, environment, secretPath, secretValue, type }
  */
 export async function createBranchSecret(config, branch, name, value) {
     const secretPath = `/branches/${branch}/`;
-    const url = `${INFISICAL_API_BASE}/api/v3/secrets/raw/${encodeURIComponent(name)}`;
+    const url = `${INFISICAL_API_BASE}/api/v4/secrets/${encodeURIComponent(name)}`;
     const body = {
-        workspaceId: config.projectId,
+        projectId: config.projectId,
         environment: config.environment,
         secretPath,
         secretValue: value,
         type: "shared",
     };
-    const headers = {
-        Authorization: `Bearer ${config.token}`,
-        "Content-Type": "application/json",
-    };
+    const headers = authHeaders(config);
+    // --- Try POST (create) ---------------------------------------------------
     const res = await fetch(url, {
         method: "POST",
         headers,
@@ -84,8 +141,8 @@ export async function createBranchSecret(config, branch, name, value) {
     });
     if (res.ok)
         return;
-    // If conflict (already exists), try PATCH to update
-    if (res.status === 400 || res.status === 409) {
+    // Secret already exists → PATCH to update
+    if (res.status === 400) {
         const patchRes = await fetch(url, {
             method: "PATCH",
             headers,
@@ -96,9 +153,37 @@ export async function createBranchSecret(config, branch, name, value) {
         const text = await patchRes.text().catch(() => "");
         throw new Error(`Infisical PATCH ${name} → ${patchRes.status}: ${text}`);
     }
+    // Folder doesn't exist → create folders then retry POST
+    if (res.status === 404) {
+        await ensureFolder(config, secretPath);
+        const retryRes = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (retryRes.ok)
+            return;
+        // Retry may 400 if another process created it concurrently → try PATCH
+        if (retryRes.status === 400) {
+            const patchRes = await fetch(url, {
+                method: "PATCH",
+                headers,
+                body: JSON.stringify(body),
+            });
+            if (patchRes.ok)
+                return;
+            const text = await patchRes.text().catch(() => "");
+            throw new Error(`Infisical PATCH ${name} (after folder creation) → ${patchRes.status}: ${text}`);
+        }
+        const text = await retryRes.text().catch(() => "");
+        throw new Error(`Infisical POST ${name} (after folder creation) → ${retryRes.status}: ${text}`);
+    }
     const text = await res.text().catch(() => "");
     throw new Error(`Infisical POST ${name} → ${res.status}: ${text}`);
 }
+// ---------------------------------------------------------------------------
+// Config helper
+// ---------------------------------------------------------------------------
 /**
  * Extract Infisical config from environment variables and log in.
  * Reads INFISICAL_CLIENT_ID, INFISICAL_CLIENT_SECRET, INFISICAL_PROJECT_ID,

package/package.json

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