@forgezero/agent 0.1.29 → 0.1.31

package/dist/deploy-file.js

@@ -0,0 +1,378 @@
+// src/software.ts
+import { readFileSync } from "node:fs";
+var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
+var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
+var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+var OS_CATALOG = [
+  { id: "ubuntu", version: "26.04", architecture: "x64", status: "active" }
+];
+var SOFTWARE_CATALOG = [
+  { id: "bun", version: "1.3.14", 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" },
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+];
+var UBUNTU_2604_X64 = [
+  {
+    requirement: { id: "bun", version: "1.3.14" },
+    check: 'test "$(/usr/local/bin/bun --version 2>/dev/null)" = 1.3.14',
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL https://bun.sh/install -o "$tmp/install"; ` + `echo "${BUN_INSTALLER_SHA256}  $tmp/install" | sha256sum -c -; ` + `BUN_INSTALL="$tmp/bun" BUN_VERSION=1.3.14 bash "$tmp/install" >/dev/null; ` + `install -d -m 0755 /usr/local/lib/forgezero/runtime; ` + `install -m 0755 "$tmp/bun/bin/bun" /usr/local/lib/forgezero/runtime/bun.next; ` + `mv -Tf /usr/local/lib/forgezero/runtime/bun.next /usr/local/lib/forgezero/runtime/bun; ` + `ln -sfn /usr/local/lib/forgezero/runtime/bun /usr/local/bin/bun`
+  },
+  {
+    requirement: { id: "nginx", version: "ubuntu-26.04" },
+    check: "command -v nginx >/dev/null && systemctl is-active --quiet nginx",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y nginx && systemctl enable --now nginx"
+  },
+  {
+    requirement: { id: "arangodb", version: "3.11.14" },
+    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14'`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install`
+  },
+  {
+    requirement: { id: "cloudflared", version: "2026.7.3" },
+    check: `cloudflared --version 2>/dev/null | grep -q '2026.7.3'`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64' -o "$tmp/cloudflared"; ` + `echo "${CLOUDFLARED_SHA256}  $tmp/cloudflared" | sha256sum -c -; ` + `install -m 0755 "$tmp/cloudflared" /usr/local/bin/cloudflared`
+  },
+  {
+    requirement: { id: "ufw", version: "ubuntu-26.04" },
+    check: "command -v ufw >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
+  }
+];
+function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
+  const values = Object.fromEntries(osRelease.split(`
+`).flatMap((line) => {
+    const separator = line.indexOf("=");
+    return separator > 0 ? [[line.slice(0, separator), line.slice(separator + 1).replace(/^['"]|['"]$/g, "")]] : [];
+  }));
+  return {
+    os: { id: (values.ID ?? "unknown").toLowerCase(), versionId: values.VERSION_ID ?? "unknown" },
+    architecture
+  };
+}
+function validateSoftwareRequirements(value, _options = {}) {
+  if (!Array.isArray(value) || value.length > 32)
+    throw new Error("software requirements must be an array of at most 32 entries");
+  const seen = new Set;
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      throw new Error("software requirement must be an object");
+    const row = item;
+    if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
+      throw new Error("software requirement contains an unknown field");
+    }
+    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw"].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 };
+    if (seen.has(requirement.id))
+      throw new Error(`duplicate software requirement: ${requirement.id}`);
+    seen.add(requirement.id);
+    const catalog = SOFTWARE_CATALOG.find((candidate) => candidate.id === requirement.id && candidate.version === requirement.version);
+    if (!catalog || catalog.status !== "active") {
+      throw new Error(`software requirement is not active: ${requirement.id}@${requirement.version}`);
+    }
+    return requirement;
+  });
+}
+async function ensureSoftwareRequirements(requirementsInput, options) {
+  const requirements = validateSoftwareRequirements(requirementsInput);
+  const observation = options.observation ?? observeSoftwareHost();
+  const os = OS_CATALOG.find((candidate) => candidate.id === observation.os.id && candidate.version === observation.os.versionId && candidate.architecture === observation.architecture);
+  if (!os || os.status !== "active") {
+    throw new Error(`unsupported software strategy: ${observation.os.id} ${observation.os.versionId} ${observation.architecture}`);
+  }
+  const results = [];
+  for (const requirement of requirements) {
+    const strategy = UBUNTU_2604_X64.find(({ requirement: candidate }) => candidate.id === requirement.id && candidate.version === requirement.version);
+    if (!strategy)
+      throw new Error(`unsupported software requirement: ${requirement.id}@${requirement.version}`);
+    const before = await options.exec(strategy.check);
+    if (before.exitCode === 0) {
+      results.push({ ...requirement, changed: false });
+      continue;
+    }
+    const installed = await options.exec(strategy.install);
+    if (installed.exitCode !== 0)
+      throw new Error(`could not install ${requirement.id}@${requirement.version}: ${installed.output.trim()}`);
+    const after = await options.exec(strategy.check);
+    if (after.exitCode !== 0)
+      throw new Error(`${requirement.id}@${requirement.version} did not pass its post-install check`);
+    results.push({ ...requirement, changed: true });
+  }
+  return results;
+}
+
+// src/definition.ts
+var PIPELINE_VERSION = 2;
+var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
+
+class DefinitionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DefinitionError";
+  }
+}
+var record = (value, where) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new DefinitionError(`${where} must be an object.`);
+  }
+  return value;
+};
+var text = (value, where) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new DefinitionError(`${where} must be a non-empty string.`);
+  }
+  return value;
+};
+var exactKeys = (value, allowed, where) => {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0)
+    throw new DefinitionError(`${where} contains unknown field(s): ${unknown.join(", ")}.`);
+};
+var NAME = /^[a-z][a-z0-9-]{0,62}$/;
+var RESERVED_STEP_ENV = new Set([
+  "PATH",
+  "HOME",
+  "SHELL",
+  "PWD",
+  "BUN_INSTALL",
+  "NODE_OPTIONS",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "GIT_SSH",
+  "GIT_SSH_COMMAND"
+]);
+function parseDeployDefinition(value, options = {}) {
+  const root = record(value, "pipeline");
+  exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
+  if (root.$schema !== undefined && root.$schema !== DEPLOY_SCHEMA_URL) {
+    throw new DefinitionError(`pipeline.$schema must be ${DEPLOY_SCHEMA_URL}.`);
+  }
+  if (root.version !== PIPELINE_VERSION) {
+    throw new DefinitionError(`pipeline.version must be ${PIPELINE_VERSION}.`);
+  }
+  if (root.requireAttestation !== undefined && typeof root.requireAttestation !== "boolean") {
+    throw new DefinitionError("pipeline.requireAttestation must be a boolean.");
+  }
+  const rawProfiles = record(root.profiles, "pipeline.profiles");
+  const profileEntries = Object.entries(rawProfiles);
+  if (profileEntries.length === 0 || profileEntries.length > 32) {
+    throw new DefinitionError("pipeline.profiles must contain from 1 to 32 named profiles.");
+  }
+  if (!Array.isArray(root.steps) || root.steps.length === 0) {
+    throw new DefinitionError("pipeline.steps must contain at least one step.");
+  }
+  const profiles = {};
+  for (const [name2, raw] of profileEntries) {
+    if (!NAME.test(name2))
+      throw new DefinitionError(`pipeline profile name is invalid: ${name2}.`);
+    const profile = record(raw, `profiles.${name2}`);
+    exactKeys(profile, ["software"], `profiles.${name2}`);
+    if (!Array.isArray(profile.software)) {
+      throw new DefinitionError(`profiles.${name2}.software must be an array.`);
+    }
+    profiles[name2] = { software: validateSoftwareRequirements(profile.software, options) };
+  }
+  const phases = new Set(["build", "release", "migrate", "health"]);
+  const steps = root.steps.map((raw, index) => {
+    const step = record(raw, `steps[${index}]`);
+    exactKeys(step, ["name", "run", "phase", "scope", "profiles", "secrets", "always", "timeoutMs", "when"], `steps[${index}]`);
+    const phase = text(step.phase, `steps[${index}].phase`);
+    if (!phases.has(phase))
+      throw new DefinitionError(`steps[${index}].phase is not supported.`);
+    if (step.scope !== "target" && step.scope !== "release") {
+      throw new DefinitionError(`steps[${index}].scope must be target or release.`);
+    }
+    if (step.always !== undefined && typeof step.always !== "boolean") {
+      throw new DefinitionError(`steps[${index}].always must be a boolean.`);
+    }
+    let selectedProfiles;
+    if (step.profiles !== undefined) {
+      if (!Array.isArray(step.profiles) || step.profiles.length === 0 || step.profiles.some((name2) => typeof name2 !== "string" || !Object.hasOwn(profiles, name2))) {
+        throw new DefinitionError(`steps[${index}].profiles must name existing profiles.`);
+      }
+      selectedProfiles = [...step.profiles];
+      if (new Set(selectedProfiles).size !== selectedProfiles.length) {
+        throw new DefinitionError(`steps[${index}].profiles must not contain duplicates.`);
+      }
+    }
+    if (step.secrets !== undefined && (!Array.isArray(step.secrets) || step.secrets.some((name2) => typeof name2 !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name2)))) {
+      throw new DefinitionError(`steps[${index}].secrets must contain names only.`);
+    }
+    if (Array.isArray(step.secrets) && new Set(step.secrets).size !== step.secrets.length) {
+      throw new DefinitionError(`steps[${index}].secrets must not contain duplicates.`);
+    }
+    if (Array.isArray(step.secrets) && step.secrets.some((name2) => RESERVED_STEP_ENV.has(String(name2)))) {
+      throw new DefinitionError(`steps[${index}].secrets may not replace process-control environment variables.`);
+    }
+    const timeoutMs = step.timeoutMs === undefined ? undefined : Number(step.timeoutMs);
+    if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 86400000)) {
+      throw new DefinitionError(`steps[${index}].timeoutMs must be an integer from 1 to 86400000.`);
+    }
+    let when;
+    if (step.when !== undefined) {
+      const conditions = record(step.when, `steps[${index}].when`);
+      when = {};
+      for (const [name2, expected] of Object.entries(conditions)) {
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(name2) || typeof expected !== "string" || expected.length === 0) {
+          throw new DefinitionError(`steps[${index}].when must map environment names to non-empty strings.`);
+        }
+        when[name2] = expected;
+      }
+      if (Object.keys(when).length === 0)
+        throw new DefinitionError(`steps[${index}].when must not be empty.`);
+    }
+    return {
+      name: text(step.name, `steps[${index}].name`),
+      run: text(step.run, `steps[${index}].run`),
+      phase,
+      scope: step.scope,
+      profiles: selectedProfiles,
+      secrets: step.secrets,
+      always: step.always === true,
+      timeoutMs,
+      when
+    };
+  });
+  if (new Set(steps.map((step) => step.name)).size !== steps.length) {
+    throw new DefinitionError("pipeline.steps must have unique names.");
+  }
+  const name = text(root.name, "pipeline.name");
+  if (name.length > 120)
+    throw new DefinitionError("pipeline.name must be at most 120 characters.");
+  return {
+    version: PIPELINE_VERSION,
+    name,
+    requireAttestation: root.requireAttestation === true,
+    profiles,
+    steps
+  };
+}
+function phasePipeline(definition, phase, profile, executeRelease = false) {
+  if (!Object.hasOwn(definition.profiles, profile)) {
+    throw new DefinitionError(`pipeline profile does not exist: ${profile}.`);
+  }
+  return {
+    name: `${definition.name}:${phase}`,
+    requireAttestation: definition.requireAttestation,
+    steps: definition.steps.filter((step) => step.phase === phase && (!step.profiles || step.profiles.includes(profile)) && (step.scope === "target" || executeRelease))
+  };
+}
+
+// src/deploy-file.ts
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+var DEPLOY_FILE = ".fz/deploy.json";
+var DEPLOY_TODO_PREFIX = "ForgeZero pipeline TODO:";
+var stable = (value) => {
+  if (Array.isArray(value))
+    return `[${value.map(stable).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => `${JSON.stringify(key)}:${stable(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+};
+function deployDefinitionDigest(definition) {
+  return `sha256:${createHash("sha256").update(stable(definition)).digest("hex")}`;
+}
+var safeName = (value) => {
+  const normalized = value.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63);
+  return /^[a-z]/.test(normalized) ? normalized : `app-${normalized || "service"}`.slice(0, 63);
+};
+function packageHints(root) {
+  const packagePath = join(root, "package.json");
+  if (!existsSync(packagePath))
+    return { bun: existsSync(join(root, "bun.lock")) };
+  try {
+    const manifest = JSON.parse(readFileSync2(packagePath, "utf8"));
+    return {
+      name: typeof manifest.name === "string" ? manifest.name : undefined,
+      build: typeof manifest.scripts?.build === "string" ? "bun run build" : undefined,
+      bun: existsSync(join(root, "bun.lock")) || existsSync(join(root, "bun.lockb"))
+    };
+  } catch {
+    return { bun: existsSync(join(root, "bun.lock")) };
+  }
+}
+var blocker = (instruction) => `printf '%s\\n' '${DEPLOY_TODO_PREFIX} ${instruction}' >&2; exit 78`;
+function defaultDeployFile(root, options = {}) {
+  const hints = packageHints(root);
+  const software = options.software ?? (hints.bun ? SOFTWARE_CATALOG.filter((entry) => entry.id === "bun" && entry.status === "active").map(({ id, version }) => ({ id, version })) : []);
+  validateSoftwareRequirements(software, { channel: options.channel });
+  const profile = options.profile ?? "app";
+  const build = hints.build ?? blocker("replace the build step with the project build command");
+  return {
+    $schema: DEPLOY_SCHEMA_URL,
+    version: 2,
+    name: safeName(options.name ?? hints.name ?? basename(root)),
+    ...options.requireAttestation ? { requireAttestation: true } : {},
+    profiles: { [profile]: { software } },
+    steps: [
+      { name: "build", phase: "build", scope: "target", run: build, timeoutMs: 600000 },
+      {
+        name: "promote release",
+        phase: "release",
+        scope: "target",
+        run: blocker("replace the release step with an atomic promotion command"),
+        timeoutMs: 120000
+      },
+      {
+        name: "health check",
+        phase: "health",
+        scope: "target",
+        run: blocker("replace the health step with a bounded local health check"),
+        timeoutMs: 30000
+      }
+    ]
+  };
+}
+function inspectDeployFile(root, options = {}) {
+  const path = join(root, DEPLOY_FILE);
+  if (!existsSync(path))
+    throw new Error(`${DEPLOY_FILE} does not exist; run \`fz deploy init\`.`);
+  const raw = JSON.parse(readFileSync2(path, "utf8"));
+  const definition = parseDeployDefinition(raw, options);
+  const problems = definition.steps.filter((step) => step.run.includes(DEPLOY_TODO_PREFIX)).map((step) => `${step.name} still contains the safe initialization blocker`);
+  const profiles = Object.keys(definition.profiles).sort();
+  return {
+    path,
+    definition,
+    summary: {
+      path,
+      digest: deployDefinitionDigest(definition),
+      version: definition.version,
+      name: definition.name,
+      profiles,
+      software: Object.fromEntries(profiles.map((profile) => [
+        profile,
+        definition.profiles[profile].software
+      ])),
+      ready: problems.length === 0,
+      problems
+    }
+  };
+}
+function initializeDeployFile(root, options = {}) {
+  const path = join(root, DEPLOY_FILE);
+  if (existsSync(path) && !options.force) {
+    throw new Error(`${DEPLOY_FILE} already exists; use --force only when replacing it deliberately.`);
+  }
+  const raw = defaultDeployFile(root, options);
+  parseDeployDefinition(raw, { channel: options.channel });
+  mkdirSync(join(root, ".fz"), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(raw, null, 2)}
+`, { mode: 420 });
+  return inspectDeployFile(root, { channel: options.channel });
+}
+export {
+  inspectDeployFile,
+  initializeDeployFile,
+  deployDefinitionDigest,
+  defaultDeployFile,
+  DEPLOY_TODO_PREFIX,
+  DEPLOY_SCHEMA_URL,
+  DEPLOY_FILE
+};

package/dist/deployment-pull.d.ts

@@ -7,12 +7,12 @@ export interface RemoteDeploymentClaim {
     claimToken: string;
     claimExpiresAtTs: number;
     attempt: number;
-    /** True on exactly one compute in a clustered delivery. */
-    coordinator: boolean;
+    /** True on the one target deterministically elected for this release. */
+    releaseExecutor: boolean;
     source: {
         repository: string;
         branch: string;
-        role: string;
+        profile: string;
         knownHosts?: string;
         auth?: GitSourceAuth;
     };

package/dist/deployment.d.ts

@@ -16,14 +16,18 @@ export interface CommandResult {
 export interface DeploymentRequest {
     /** Optional exact commit from a verified webhook. Never a branch name. */
     revision?: string;
-    /** Whether this node is the coordinator allowed to execute `once` steps. */
-    coordinator?: boolean;
+    /** True only for the target deterministically elected for release-scoped steps. */
+    releaseExecutor?: boolean;
 }
 export interface DeploymentResult {
     key: string;
     repository: string;
     branch: string;
     revision: string;
+    /** Semantic digest of the validated definition from this exact commit. */
+    definitionDigest: string;
+    definitionVersion: number;
+    profile: string;
     release: string;
     ok: boolean;
     phases: readonly RunResult[];
@@ -46,7 +50,7 @@ export interface DeploymentOptions {
     key: string;
     repository: string;
     branch: string;
-    role: string;
+    profile: string;
     root: string;
     publicApiUrl?: string;
     sourceAuth?: GitSourceAuth;
@@ -74,8 +78,8 @@ export declare class DeploymentError extends Error {
 /**
  * One source and one pipeline owner.
  *
- * A request may choose an exact commit and whether this assigned node is the
- * coordinator. It cannot choose a repository, branch, working directory or
+ * A request may choose an exact commit and carry the control plane's
+ * deterministic release-executor decision. It cannot choose a repository, branch, working directory or
  * command: those are sealed into the agent unit and the checked-out definition.
  */
 export declare function createDeploymentManager(options: DeploymentOptions): {