@forgezero/agent 0.1.52 → 0.1.55

package/dist/community-rehearsal-host.js

@@ -4,6 +4,7 @@ import {
   accessSync,
   chmodSync,
   copyFileSync,
+  existsSync,
   mkdtempSync,
   mkdirSync,
   readFileSync,
@@ -24,6 +25,7 @@ var OS_CATALOG = [
 ];
 var SOFTWARE_CATALOG = [
   { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "docker", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
@@ -33,6 +35,7 @@ var SOFTWARE_CATALOG = [
 ];
 var UBUNTU_2604_X64 = [
   { requirement: { id: "bun", version: "1.3.14" } },
+  { requirement: { id: "docker", version: "ubuntu-26.04" } },
   { requirement: { id: "nginx", version: "ubuntu-26.04" } },
   { requirement: { id: "arangodb", version: "3.11.14" } },
   { requirement: { id: "cloudflared", version: "2026.7.3" } },
@@ -41,6 +44,15 @@ var UBUNTU_2604_X64 = [
   { requirement: { id: "openssh-client", version: "ubuntu-26.04" } }
 ];
 var path = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+var DOCKER_DAEMON_PATH = "/etc/docker/daemon.json";
+var DOCKER_DAEMON_CONFIG = `${JSON.stringify({
+  "data-root": "/var/lib/docker",
+  "storage-driver": "overlay2",
+  "live-restore": true,
+  "log-driver": "local",
+  "log-opts": { "max-size": "10m", "max-file": "3" }
+}, null, 2)}
+`;
 var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
 var runSoftwareCommand = async (argv, env = {}) => {
   let child;
@@ -83,12 +95,21 @@ async function executeSoftwareOperation(operation) {
   if (operation.kind === "check") {
     if (software === "bun")
       return run(["/usr/local/bin/bun", "--version"]).then((r) => ({ ...r, exitCode: successful(r, /^1\.3\.14\s*$/m) ? 0 : 1 }));
+    if (software === "docker") {
+      const binary = await run(["/usr/bin/docker", "--version"]);
+      if (!successful(binary, /Docker version/))
+        return { ...binary, exitCode: 1 };
+      if (!existsSync(DOCKER_DAEMON_PATH) || readFileSync(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG)
+        return { exitCode: 1, output: "Docker daemon policy is absent or differs from the reviewed ForgeZero policy" };
+      const active = await run(["/usr/bin/systemctl", "is-active", "--quiet", "docker.service"]);
+      return active.exitCode === 0 ? { exitCode: 0, output: binary.output } : active;
+    }
     if (software === "nginx") {
       const binary = await run(["/usr/sbin/nginx", "-v"]);
       return binary.exitCode === 0 ? run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]) : binary;
     }
     if (software === "arangodb") {
-      const binary = await run(["/usr/bin/arangod", "--version"]);
+      const binary = await run(["/usr/sbin/arangod", "--version"]);
       if (!successful(binary, /3\.11\.14/))
         return { ...binary, exitCode: 1 };
       const [active, enabled] = await Promise.all([
@@ -115,11 +136,22 @@ async function executeSoftwareOperation(operation) {
       return { exitCode: 1, output: cause instanceof Error ? cause.message : String(cause) };
     }
   }
-  if (software === "nginx" || software === "ufw" || software === "openssh-client") {
-    const installed = await aptInstall(software === "openssh-client" ? "openssh-client" : software);
-    if (installed.exitCode !== 0 || software !== "nginx")
+  if (software === "docker" || software === "nginx" || software === "ufw" || software === "openssh-client") {
+    const packageName = software === "openssh-client" ? "openssh-client" : software === "docker" ? "docker.io" : software;
+    const installed = await aptInstall(packageName);
+    if (installed.exitCode !== 0 || software !== "nginx" && software !== "docker")
       return installed;
-    return run(["/usr/bin/systemctl", "enable", "--now", "nginx.service"]);
+    if (software === "docker") {
+      mkdirSync("/etc/docker", { recursive: true, mode: 493 });
+      if (existsSync(DOCKER_DAEMON_PATH) && readFileSync(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG) {
+        return { exitCode: 2, output: "refusing to overwrite an existing Docker daemon configuration that differs from the reviewed ForgeZero policy" };
+      }
+      if (!existsSync(DOCKER_DAEMON_PATH))
+        writeFileSync(DOCKER_DAEMON_PATH, DOCKER_DAEMON_CONFIG, { mode: 420, flag: "wx" });
+      const enabled = await run(["/usr/bin/systemctl", "enable", "docker.service"]);
+      return enabled.exitCode === 0 ? run(["/usr/bin/systemctl", "restart", "docker.service"]) : enabled;
+    }
+    return run(["/usr/bin/systemctl", "enable", "--now", `${software}.service`]);
   }
   const directory = mkdtempSync(join(tmpdir(), "forgezero-software-"));
   try {
@@ -204,7 +236,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "docker", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };
@@ -387,7 +419,7 @@ function planCommunityRehearsalPrepare(request) {
   const node = exactNode(request.node);
   const releaseRoot = `${COMMUNITY_REHEARSAL_ROOT}/releases/${request.release}`;
   return [
-    { kind: "exec", argv: ["/usr/bin/arangod", "--version"] },
+    { kind: "exec", argv: ["/usr/sbin/arangod", "--version"] },
     { kind: "exec", argv: ["/usr/bin/systemctl", "stop", "forgezero-community-api.service"], accepted: [0, 5] },
     { kind: "exec", argv: ["/usr/bin/systemctl", "stop", "forgezero-rehearsal-db.service"], accepted: [0, 5] },
     { kind: "remove-tree", path: COMMUNITY_DATABASE_ROOT },
@@ -442,7 +474,7 @@ async function applyOperations(operations) {
       const result = await exec(operation.argv, operation.stdin);
       if (!(operation.accepted ?? [0]).includes(result.exitCode))
         throw new Error(`${operation.argv[0]} failed (${result.exitCode}): ${result.output.trim()}`);
-      if (operation.argv[0] === "/usr/bin/arangod" && !result.output.split(/\r?\n/, 1)[0]?.includes(COMMUNITY_REHEARSAL_VERSION)) {
+      if (operation.argv[0] === "/usr/sbin/arangod" && !result.output.split(/\r?\n/, 1)[0]?.includes(COMMUNITY_REHEARSAL_VERSION)) {
         throw new Error(`community rehearsal requires ArangoDB ${COMMUNITY_REHEARSAL_VERSION}`);
       }
     }

package/dist/container-supervisor.d.ts

@@ -0,0 +1,36 @@
+import type { ApplicationComponent } from './deploy';
+import type { ServiceActivationState } from './service-supervisor';
+export interface ContainerBuildRequest {
+    key: string;
+    revision: string;
+    root: string;
+    release: string;
+    component: string;
+    application: ApplicationComponent;
+    noCache?: boolean;
+}
+export interface ContainerActivateRequest extends ContainerBuildRequest {
+    image: string;
+}
+export interface ContainerBuildResult {
+    image: string;
+    digest: string;
+}
+export interface ContainerHost {
+    realpath(path: string): string;
+    exists(path: string): boolean;
+    read(path: string): string;
+    write(path: string, content: string, mode: number): void;
+    remove(path: string): void;
+    list(path: string): string[];
+    mkdir(path: string, mode: number): void;
+    exec(argv: readonly string[]): Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    health(port: number, path: string, timeoutMs: number, method: 'GET' | 'HEAD', expectedStatus: readonly number[]): Promise<boolean>;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+}
+export declare function buildContainerImage(requestValue: ContainerBuildRequest, host?: ContainerHost): Promise<ContainerBuildResult>;
+export declare function activateContainer(requestValue: ContainerActivateRequest, host?: ContainerHost): Promise<ServiceActivationState>;

package/dist/definition.js

@@ -4,6 +4,7 @@ import {
   accessSync,
   chmodSync,
   copyFileSync,
+  existsSync,
   mkdtempSync,
   mkdirSync,
   readFileSync,
@@ -24,6 +25,7 @@ var OS_CATALOG = [
 ];
 var SOFTWARE_CATALOG = [
   { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "docker", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
@@ -33,6 +35,7 @@ var SOFTWARE_CATALOG = [
 ];
 var UBUNTU_2604_X64 = [
   { requirement: { id: "bun", version: "1.3.14" } },
+  { requirement: { id: "docker", version: "ubuntu-26.04" } },
   { requirement: { id: "nginx", version: "ubuntu-26.04" } },
   { requirement: { id: "arangodb", version: "3.11.14" } },
   { requirement: { id: "cloudflared", version: "2026.7.3" } },
@@ -41,6 +44,15 @@ var UBUNTU_2604_X64 = [
   { requirement: { id: "openssh-client", version: "ubuntu-26.04" } }
 ];
 var path = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+var DOCKER_DAEMON_PATH = "/etc/docker/daemon.json";
+var DOCKER_DAEMON_CONFIG = `${JSON.stringify({
+  "data-root": "/var/lib/docker",
+  "storage-driver": "overlay2",
+  "live-restore": true,
+  "log-driver": "local",
+  "log-opts": { "max-size": "10m", "max-file": "3" }
+}, null, 2)}
+`;
 var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
 var runSoftwareCommand = async (argv, env = {}) => {
   let child;
@@ -83,12 +95,21 @@ async function executeSoftwareOperation(operation) {
   if (operation.kind === "check") {
     if (software === "bun")
       return run(["/usr/local/bin/bun", "--version"]).then((r) => ({ ...r, exitCode: successful(r, /^1\.3\.14\s*$/m) ? 0 : 1 }));
+    if (software === "docker") {
+      const binary = await run(["/usr/bin/docker", "--version"]);
+      if (!successful(binary, /Docker version/))
+        return { ...binary, exitCode: 1 };
+      if (!existsSync(DOCKER_DAEMON_PATH) || readFileSync(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG)
+        return { exitCode: 1, output: "Docker daemon policy is absent or differs from the reviewed ForgeZero policy" };
+      const active = await run(["/usr/bin/systemctl", "is-active", "--quiet", "docker.service"]);
+      return active.exitCode === 0 ? { exitCode: 0, output: binary.output } : active;
+    }
     if (software === "nginx") {
       const binary = await run(["/usr/sbin/nginx", "-v"]);
       return binary.exitCode === 0 ? run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]) : binary;
     }
     if (software === "arangodb") {
-      const binary = await run(["/usr/bin/arangod", "--version"]);
+      const binary = await run(["/usr/sbin/arangod", "--version"]);
       if (!successful(binary, /3\.11\.14/))
         return { ...binary, exitCode: 1 };
       const [active, enabled] = await Promise.all([
@@ -115,11 +136,22 @@ async function executeSoftwareOperation(operation) {
       return { exitCode: 1, output: cause instanceof Error ? cause.message : String(cause) };
     }
   }
-  if (software === "nginx" || software === "ufw" || software === "openssh-client") {
-    const installed = await aptInstall(software === "openssh-client" ? "openssh-client" : software);
-    if (installed.exitCode !== 0 || software !== "nginx")
+  if (software === "docker" || software === "nginx" || software === "ufw" || software === "openssh-client") {
+    const packageName = software === "openssh-client" ? "openssh-client" : software === "docker" ? "docker.io" : software;
+    const installed = await aptInstall(packageName);
+    if (installed.exitCode !== 0 || software !== "nginx" && software !== "docker")
       return installed;
-    return run(["/usr/bin/systemctl", "enable", "--now", "nginx.service"]);
+    if (software === "docker") {
+      mkdirSync("/etc/docker", { recursive: true, mode: 493 });
+      if (existsSync(DOCKER_DAEMON_PATH) && readFileSync(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG) {
+        return { exitCode: 2, output: "refusing to overwrite an existing Docker daemon configuration that differs from the reviewed ForgeZero policy" };
+      }
+      if (!existsSync(DOCKER_DAEMON_PATH))
+        writeFileSync(DOCKER_DAEMON_PATH, DOCKER_DAEMON_CONFIG, { mode: 420, flag: "wx" });
+      const enabled = await run(["/usr/bin/systemctl", "enable", "docker.service"]);
+      return enabled.exitCode === 0 ? run(["/usr/bin/systemctl", "restart", "docker.service"]) : enabled;
+    }
+    return run(["/usr/bin/systemctl", "enable", "--now", `${software}.service`]);
   }
   const directory = mkdtempSync(join(tmpdir(), "forgezero-software-"));
   try {
@@ -204,7 +236,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "docker", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };

package/dist/deploy-actions.d.ts

@@ -0,0 +1,87 @@
+import { type ComponentDefinition, type Condition, type CredentialDefinition, type JsonObject, type RequirementDefinition, type RetryDefinition, type StepScope, type WorkflowStepDefinition } from './deploy';
+interface StepOptions {
+    scope: StepScope;
+    if?: Condition;
+    timeoutMs?: number;
+    retry?: RetryDefinition;
+    failure?: WorkflowStepDefinition['failure'];
+    compensate?: WorkflowStepDefinition['compensate'];
+}
+export declare const actions: {
+    readonly software: {
+        readonly ensure: (withValue: {
+            requirements: readonly string[];
+        }, options: StepOptions) => WorkflowStepDefinition<{
+            requirements: readonly string[];
+        }>;
+    };
+    readonly exec: {
+        readonly argv: (withValue: {
+            component: string;
+            argv: readonly string[];
+            credentials?: Readonly<Record<string, string>>;
+        }, options: StepOptions) => WorkflowStepDefinition<{
+            component: string;
+            argv: readonly string[];
+            credentials?: Readonly<Record<string, string>>;
+        }>;
+    };
+    readonly container: {
+        readonly build: (withValue: {
+            component: string;
+            noCache?: boolean;
+        }, options: StepOptions) => WorkflowStepDefinition<{
+            component: string;
+            noCache?: boolean;
+        }>;
+        readonly pull: (withValue: {
+            component: string;
+        }, options: StepOptions) => WorkflowStepDefinition<{
+            component: string;
+        }>;
+    };
+    readonly service: {
+        readonly deploy: (withValue: {
+            component: string;
+            imageDigest?: string | {
+                $ref: `steps.${string}.outputs.${string}`;
+            };
+        }, options: StepOptions) => WorkflowStepDefinition<{
+            component: string;
+            imageDigest?: string | {
+                $ref: `steps.${string}.outputs.${string}`;
+            };
+        }>;
+        readonly health: (withValue: {
+            component: string;
+        }, options: StepOptions) => WorkflowStepDefinition<{
+            component: string;
+        }>;
+        readonly promote: (withValue: {
+            component: string;
+            imageDigest?: string | {
+                $ref: `steps.${string}.outputs.${string}`;
+            };
+        }, options: StepOptions) => WorkflowStepDefinition<{
+            component: string;
+            imageDigest?: string | {
+                $ref: `steps.${string}.outputs.${string}`;
+            };
+        }>;
+    };
+    readonly storage: {
+        readonly verify: (withValue: {
+            component: string;
+        }, options: StepOptions) => WorkflowStepDefinition<{
+            component: string;
+        }>;
+    };
+    readonly extension: <T extends JsonObject>(uses: `${string}@${number}`, withValue: T, options: StepOptions) => WorkflowStepDefinition<T>;
+};
+/** Close package-owned action inputs at runtime. Third-party actions stay namespaced and are closed by their installed handler contract. */
+export declare function validateBuiltInAction(definition: WorkflowStepDefinition, context: {
+    components: Readonly<Record<string, ComponentDefinition>>;
+    requirements: Readonly<Record<string, RequirementDefinition>>;
+    credentials: Readonly<Record<string, CredentialDefinition>>;
+}, where: string): void;
+export {};

package/dist/deploy-compiler.d.ts

@@ -0,0 +1,26 @@
+import { type DeploymentPlan } from './deploy-plan';
+export declare const DEPLOY_SOURCE_FILE = "forgezero.deploy.ts";
+export declare const DEPLOY_PLAN_FILE = ".fz/deploy.plan.json";
+export interface DeploymentCompilation {
+    source: string;
+    output: string;
+    plan: DeploymentPlan;
+    digest: `sha256:${string}`;
+    changed: boolean;
+}
+export declare function defaultTypeScriptDeployment(name: string): string;
+export declare function initializeTypeScriptDeployment(rootValue: string, options: {
+    name: string;
+    force?: boolean;
+}): string;
+export declare function loadDeploymentSource(root: string, sourceFile?: string): Promise<unknown>;
+export declare function compileDeploymentProject(rootValue: string, options?: {
+    sourceFile?: string;
+    outputFile?: string;
+    write?: boolean;
+}): Promise<DeploymentCompilation>;
+export declare function inspectCompiledDeployment(rootValue: string, outputFile?: string): {
+    path: string;
+    plan: DeploymentPlan;
+    digest: `sha256:${string}`;
+};