@replayio/app-building 1.11.0 → 1.13.0

package/README.md

@@ -14,6 +14,8 @@ npm install @replayio/app-building
 import {
   loadDotEnv,
   FileContainerRegistry,
+  getInfisicalConfig,
+  resolveContainerSecrets,
   createMachine,
   destroyMachine,
   type ContainerConfig,
@@ -23,14 +25,17 @@ import {
   httpOptsFor,
 } from "@replayio/app-building";
 
-// Assemble config once at startup
-const envVars = loadDotEnv("/path/to/project");
+// Load orchestration vars from .env, then fetch build secrets from Infisical
+const orchestrationVars = loadDotEnv("/path/to/project");
+const infisicalConfig = getInfisicalConfig(orchestrationVars);
+const containerSecrets = await resolveContainerSecrets(infisicalConfig);
+
 const config: ContainerConfig = {
   projectRoot: "/path/to/project",  // optional — only needed for local Docker operations
-  envVars,
+  envVars: containerSecrets,
   registry: new FileContainerRegistry("/path/to/.container-registry.jsonl"),
-  flyToken: envVars.FLY_API_TOKEN,
-  flyApp: envVars.FLY_APP_NAME,
+  flyToken: orchestrationVars.FLY_API_TOKEN,
+  flyApp: orchestrationVars.FLY_APP_NAME,
 };
 
 // Create a Fly machine (automatically provisions a volume)
@@ -54,7 +59,7 @@ await destroyMachine(config.flyApp, config.flyToken, machineId, volumeId);
 
 | Export | Description |
 |---|---|
-| `ContainerConfig` | Interface bundling all external state: optional `projectRoot` (only needed for local Docker operations), `envVars`, `registry`, optional `flyToken`/`flyApp`/`imageRef`/`webhookUrl`/`detached`/`initialPrompt`. See [Webhooks](#webhooks) and [Container lifecycle](#container-lifecycle) below. |
+| `ContainerConfig` | Interface bundling all external state: optional `projectRoot` (only needed for local Docker operations), `envVars` (build secrets from Infisical), `registry`, optional `flyToken`/`flyApp`/`imageRef`/`webhookUrl`/`webhookSecret`/`detached`/`initialPrompt`/`localPort`. See [Webhooks](#webhooks) and [Container lifecycle](#container-lifecycle) 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. |
@@ -114,6 +119,35 @@ await destroyMachine(config.flyApp, config.flyToken, machineId, volumeId);
 
 **Types:** `FlyMachineInfo`, `FlyVolumeInfo`, `CreateMachineResult`
 
+### Secrets (Infisical)
+
+| Export | Description |
+|---|---|
+| `getInfisicalConfig(envVars)` | Extract `InfisicalConfig` from env vars. Returns `null` if any required var is missing (enables fallback to raw `.env`). |
+| `resolveContainerSecrets(config)` | Fetch global build secrets from Infisical and merge with Infisical config vars. Returns a `Record<string, string>` suitable for `ContainerConfig.envVars`. |
+| `fetchGlobalSecrets(config)` | Fetch secrets from the `/global/` path. |
+| `fetchBranchSecrets(config, branch)` | Fetch secrets from `/branches/<branch>/`. |
+| `fetchInfisicalSecrets(config, path)` | Raw fetch from any Infisical folder path. |
+
+**Types:** `InfisicalConfig`
+
+**Usage pattern** (orchestration scripts):
+
+```ts
+const orchestrationVars = loadDotEnv(projectRoot);
+const infisicalConfig = getInfisicalConfig(orchestrationVars);
+const containerSecrets = infisicalConfig
+  ? await resolveContainerSecrets(infisicalConfig)
+  : orchestrationVars; // fallback for local dev without Infisical
+
+const config: ContainerConfig = {
+  envVars: containerSecrets,
+  flyToken: orchestrationVars.FLY_API_TOKEN,
+  flyApp: orchestrationVars.FLY_APP_NAME,
+  ...
+};
+```
+
 ### Image ref
 
 | Export | Description |
@@ -154,7 +188,7 @@ so that interactive users can send follow-up messages at any time.
 
 ## Webhooks
 
-Set `webhookUrl` on `ContainerConfig` to receive real-time notifications of container activity. The container POSTs JSON to that URL on key events (no retries; failures are logged to stderr). If `WEBHOOK_SECRET` is set in the environment, the container sends it as a `Bearer` token in the `Authorization` header.
+Set `webhookUrl` on `ContainerConfig` to receive real-time notifications of container activity. The container POSTs JSON to that URL on key events (no retries; failures are logged to stderr). Set `webhookSecret` to include a `Bearer` token in the `Authorization` header for authenticating webhook requests.
 
 ### Payload format
 
@@ -195,10 +229,15 @@ Every POST body has this shape:
 ### Example
 
 ```ts
+const orchestrationVars = loadDotEnv("/path/to/project");
+const infisicalConfig = getInfisicalConfig(orchestrationVars);
+const containerSecrets = await resolveContainerSecrets(infisicalConfig);
+
 const config: ContainerConfig = {
   projectRoot: "/path/to/project",
-  envVars: loadDotEnv("/path/to/project"),
+  envVars: containerSecrets,
   registry: new FileContainerRegistry("/path/to/.container-registry.jsonl"),
   webhookUrl: "https://example.com/hooks/container-events",
+  webhookSecret: "your-webhook-secret",
 };
 ```

package/dist/container.d.ts

@@ -16,10 +16,13 @@ export interface ContainerConfig {
     flyApp?: string;
     imageRef?: string;
     webhookUrl?: string;
+    webhookSecret?: string;
     /** Start the container in detached mode. It will exit after processing all messages and tasks. */
     detached?: boolean;
     /** Initial prompt to queue at container startup (before the HTTP server accepts external requests). */
     initialPrompt?: string;
+    /** Override the host port for local containers (default: auto-selected). */
+    localPort?: number;
 }
 export interface RepoOptions {
     repoUrl: string;

package/dist/container.js

@@ -105,13 +105,16 @@ export async function startContainer(config, repo) {
     buildImage(config);
     const uniqueId = Math.random().toString(36).slice(2, 8);
     const containerName = `app-building-${uniqueId}`;
-    const hostPort = findFreePort();
+    const containerPort = 3000;
+    const hostPort = config.localPort ?? findFreePort();
     const extra = {
-        PORT: String(hostPort),
+        PORT: String(containerPort),
         CONTAINER_NAME: containerName,
     };
     if (config.webhookUrl)
         extra.WEBHOOK_URL = config.webhookUrl;
+    if (config.webhookSecret)
+        extra.WEBHOOK_SECRET = config.webhookSecret;
     if (config.detached)
         extra.DETACHED = "1";
     if (config.initialPrompt)
@@ -121,7 +124,7 @@ export async function startContainer(config, repo) {
     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}:${hostPort}`);
+    args.push("-p", `${hostPort}:${containerPort}`);
     for (const [k, v] of Object.entries(containerEnv)) {
         args.push("--env", `${k}=${v}`);
     }

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from "./container-registry";
 export * from "./container-utils";
 export * from "./http-client";
 export * from "./image-ref";
+export * from "./secrets";

package/dist/index.js

@@ -4,3 +4,4 @@ export * from "./container-registry";
 export * from "./container-utils";
 export * from "./http-client";
 export * from "./image-ref";
+export * from "./secrets";

package/dist/secrets.d.ts

@@ -0,0 +1,29 @@
+export interface InfisicalConfig {
+    token: string;
+    projectId: string;
+    environment: string;
+}
+/**
+ * Fetch secrets from an Infisical folder path.
+ * Returns a key-value record of secret names to values.
+ */
+export declare function fetchInfisicalSecrets(config: InfisicalConfig, secretPath: string): Promise<Record<string, string>>;
+/**
+ * Fetch global build secrets from `/global/`.
+ */
+export declare function fetchGlobalSecrets(config: InfisicalConfig): Promise<Record<string, string>>;
+/**
+ * Fetch per-branch deployment secrets from `/branches/<branch>/`.
+ */
+export declare function fetchBranchSecrets(config: InfisicalConfig, branch: string): Promise<Record<string, string>>;
+/**
+ * Resolve the full set of secrets to inject into a container:
+ * global build secrets + Infisical config vars (so the container can fetch branch secrets).
+ * Throws if any required secret from .env.example is missing.
+ */
+export declare function resolveContainerSecrets(config: InfisicalConfig): Promise<Record<string, string>>;
+/**
+ * Extract Infisical config from environment variables.
+ * Throws if any required Infisical var is missing.
+ */
+export declare function getInfisicalConfig(envVars: Record<string, string>): InfisicalConfig;

package/dist/secrets.js

@@ -0,0 +1,95 @@
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INFISICAL_API_BASE = "https://app.infisical.com";
+/** Keys listed in src/package/.env.example that must be present in container secrets. */
+function getRequiredSecretKeys() {
+    const examplePath = resolve(__dirname, ".env.example");
+    return readFileSync(examplePath, "utf-8")
+        .split("\n")
+        .map((l) => l.split("#")[0].trim())
+        .filter((l) => l && l.includes("="))
+        .map((l) => l.split("=")[0].trim());
+}
+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;
+}
+/**
+ * Fetch secrets from an Infisical folder path.
+ * Returns a key-value record of secret names to values.
+ */
+export async function fetchInfisicalSecrets(config, secretPath) {
+    const params = new URLSearchParams({
+        workspaceId: config.projectId,
+        environment: config.environment,
+        secretPath,
+    });
+    const res = await infisicalFetch(`/api/v3/secrets/raw?${params}`, config);
+    const data = (await res.json());
+    const secrets = {};
+    for (const s of data.secrets) {
+        secrets[s.secretKey] = s.secretValue;
+    }
+    return secrets;
+}
+/**
+ * Fetch global build secrets from `/global/`.
+ */
+export async function fetchGlobalSecrets(config) {
+    return fetchInfisicalSecrets(config, "/global/");
+}
+/**
+ * Fetch per-branch deployment secrets from `/branches/<branch>/`.
+ */
+export async function fetchBranchSecrets(config, branch) {
+    return fetchInfisicalSecrets(config, `/branches/${branch}/`);
+}
+/**
+ * Resolve the full set of secrets to inject into a container:
+ * global build secrets + Infisical config vars (so the container can fetch branch secrets).
+ * Throws if any required secret from .env.example is missing.
+ */
+export async function resolveContainerSecrets(config) {
+    const globals = await fetchGlobalSecrets(config);
+    const secrets = {
+        ...globals,
+        INFISICAL_TOKEN: config.token,
+        INFISICAL_PROJECT_ID: config.projectId,
+        INFISICAL_ENVIRONMENT: config.environment,
+    };
+    const required = getRequiredSecretKeys();
+    const missing = required.filter((k) => !secrets[k]);
+    if (missing.length > 0) {
+        throw new Error(`Missing required secrets in Infisical /global/: ${missing.join(", ")}`);
+    }
+    return secrets;
+}
+/**
+ * Extract Infisical config from environment variables.
+ * Throws if any required Infisical var is missing.
+ */
+export function getInfisicalConfig(envVars) {
+    const token = envVars.INFISICAL_TOKEN;
+    const projectId = envVars.INFISICAL_PROJECT_ID;
+    const environment = envVars.INFISICAL_ENVIRONMENT;
+    const missing = [
+        !token && "INFISICAL_TOKEN",
+        !projectId && "INFISICAL_PROJECT_ID",
+        !environment && "INFISICAL_ENVIRONMENT",
+    ].filter(Boolean);
+    if (missing.length > 0) {
+        throw new Error(`Missing Infisical config in .env: ${missing.join(", ")}`);
+    }
+    return { token: token, projectId: projectId, environment: environment };
+}

package/package.json

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