@forgezero/agent 0.1.53 → 0.1.56

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,6 +95,15 @@ 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;
@@ -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 };
@@ -253,6 +285,7 @@ import { dirname } from "node:path";
 var COMMUNITY_REHEARSAL_VERSION = "3.11.14";
 var COMMUNITY_REHEARSAL_ROOT = "/opt/forgezero-rehearsals/community-cluster-api";
 var COMMUNITY_DATABASE_ROOT = "/var/lib/forgezero-rehearsal-cluster";
+var COMMUNITY_CREDENTIAL_PARENT = "/etc/forgezero-rehearsal";
 var COMMUNITY_CREDENTIAL_ROOT = "/etc/forgezero-rehearsal/creds";
 var NODES = new Map([
   ["dev-fz-n1", { address: "10.42.0.21", agency: true }],
@@ -294,6 +327,12 @@ function parseCommunityRehearsalHostRequest(value) {
     }
     return row;
   }
+  if (action === "cleanup") {
+    if (Object.keys(row).some((key) => !["action", "node"].includes(key))) {
+      throw new Error("community rehearsal cleanup has unknown fields");
+    }
+    return { action, node: node.name };
+  }
   if (["database-enable", "api-enable", "database-ready", "starter-ready", "api-ready", "database-status", "api-status"].includes(String(action))) {
     if (Object.keys(row).some((key) => !["action", "node"].includes(key)))
       throw new Error("community rehearsal host action has unknown fields");
@@ -409,6 +448,19 @@ function planCommunityRehearsalPrepare(request) {
     { kind: "unlink", path: request.archivePath }
   ];
 }
+function planCommunityRehearsalCleanup() {
+  return [
+    { kind: "exec", argv: ["/usr/bin/systemctl", "disable", "--now", "forgezero-community-api.service"], accepted: [0, 1, 5] },
+    { kind: "exec", argv: ["/usr/bin/systemctl", "disable", "--now", "forgezero-rehearsal-db.service"], accepted: [0, 1, 5] },
+    { kind: "unlink", path: "/etc/systemd/system/forgezero-community-api.service" },
+    { kind: "unlink", path: "/etc/systemd/system/forgezero-rehearsal-db.service" },
+    { kind: "remove-tree", path: COMMUNITY_DATABASE_ROOT },
+    { kind: "remove-tree", path: COMMUNITY_REHEARSAL_ROOT },
+    { kind: "remove-tree", path: COMMUNITY_CREDENTIAL_PARENT },
+    { kind: "exec", argv: ["/usr/bin/systemctl", "daemon-reload"] },
+    { kind: "exec", argv: ["/usr/bin/systemctl", "reset-failed", "forgezero-community-api.service", "forgezero-rehearsal-db.service"], accepted: [0, 1, 5] }
+  ];
+}
 async function exec(argv, stdin) {
   const child = Bun.spawn([...argv], { stdin: stdin === undefined ? "ignore" : "pipe", stdout: "pipe", stderr: "pipe" });
   if (stdin !== undefined && child.stdin && typeof child.stdin !== "number") {
@@ -471,6 +523,10 @@ async function runCommunityRehearsalHost(request) {
   if ((process.getuid?.() ?? -1) !== 0)
     throw new Error("community-rehearsal must run as root");
   const node = exactNode(request.node);
+  if (request.action === "cleanup") {
+    await applyOperations(planCommunityRehearsalCleanup());
+    return { ok: true, action: request.action, node: node.name };
+  }
   if (request.action === "prepare") {
     const metadata = lstatSync(request.archivePath);
     if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size < 1 || metadata.size > 64 * 1024 * 1024 || createHash2("sha256").update(readFileSync2(request.archivePath)).digest("hex") !== request.archiveSha256) {
@@ -522,10 +578,12 @@ async function runCommunityRehearsalHost(request) {
 export {
   runCommunityRehearsalHost,
   planCommunityRehearsalPrepare,
+  planCommunityRehearsalCleanup,
   parseCommunityRehearsalHostRequest,
   ensureCommunityRehearsalArango,
   COMMUNITY_REHEARSAL_VERSION,
   COMMUNITY_REHEARSAL_ROOT,
   COMMUNITY_DATABASE_ROOT,
-  COMMUNITY_CREDENTIAL_ROOT
+  COMMUNITY_CREDENTIAL_ROOT,
+  COMMUNITY_CREDENTIAL_PARENT
 };

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,6 +95,15 @@ 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;
@@ -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}`;
+};