@forgezero/agent 0.1.28 → 0.1.30

package/dist/fz-agent.js

@@ -4886,6 +4886,16 @@ import { readFileSync } from "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" },
@@ -4924,7 +4934,7 @@ function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8")
     architecture
   };
 }
-function validateSoftwareRequirements(value) {
+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;
@@ -4942,13 +4952,18 @@ function validateSoftwareRequirements(value) {
     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 === "retired" || options.channel !== "development" && catalog.status !== "active") {
+      throw new Error(`software requirement is not available for ${options.channel ?? "production"}: ${requirement.id}@${requirement.version}`);
+    }
     return requirement;
   });
 }
 async function ensureSoftwareRequirements(requirementsInput, options) {
   const requirements = validateSoftwareRequirements(requirementsInput);
   const observation = options.observation ?? observeSoftwareHost();
-  if (observation.os.id !== "ubuntu" || observation.os.versionId !== "26.04" || observation.architecture !== "x64") {
+  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 = [];
@@ -4973,7 +4988,7 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
 }
 
 // src/definition.ts
-var PIPELINE_VERSION = 1;
+var PIPELINE_VERSION = 2;
 
 class DefinitionError extends Error {
   constructor(message) {
@@ -4998,6 +5013,7 @@ var exactKeys = (value, allowed, where) => {
   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",
@@ -5012,37 +5028,52 @@ var RESERVED_STEP_ENV = new Set([
 ]);
 function parseDeployDefinition(value) {
   const root = record(value, "pipeline");
-  exactKeys(root, ["version", "name", "requireAttestation", "roles", "steps"], "pipeline");
+  exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
+  if (root.$schema !== undefined && (typeof root.$schema !== "string" || !root.$schema.startsWith("https://"))) {
+    throw new DefinitionError("pipeline.$schema must be an HTTPS URL.");
+  }
   if (root.version !== PIPELINE_VERSION) {
     throw new DefinitionError(`pipeline.version must be ${PIPELINE_VERSION}.`);
   }
-  if (!Array.isArray(root.roles) || root.roles.length === 0) {
-    throw new DefinitionError("pipeline.roles must contain at least one role.");
+  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 roles = root.roles.map((raw, index) => {
-    const role = record(raw, `roles[${index}]`);
-    exactKeys(role, ["name", "software"], `roles[${index}]`);
-    if (!Array.isArray(role.software)) {
-      throw new DefinitionError(`roles[${index}].software must be an array.`);
+  const profiles = {};
+  for (const [name, raw] of profileEntries) {
+    if (!NAME.test(name))
+      throw new DefinitionError(`pipeline profile name is invalid: ${name}.`);
+    const profile = record(raw, `profiles.${name}`);
+    exactKeys(profile, ["software"], `profiles.${name}`);
+    if (!Array.isArray(profile.software)) {
+      throw new DefinitionError(`profiles.${name}.software must be an array.`);
     }
-    return {
-      name: text(role.name, `roles[${index}].name`),
-      software: validateSoftwareRequirements(role.software)
-    };
-  });
-  if (new Set(roles.map((role) => role.name)).size !== roles.length) {
-    throw new DefinitionError("pipeline.roles must have unique names.");
+    profiles[name] = { software: validateSoftwareRequirements(profile.software) };
   }
   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", "secrets", "once", "always", "timeoutMs", "when"], `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.`);
+    }
+    let selectedProfiles;
+    if (step.profiles !== undefined) {
+      if (!Array.isArray(step.profiles) || step.profiles.length === 0 || step.profiles.some((name) => typeof name !== "string" || !Object.hasOwn(profiles, name))) {
+        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((name) => typeof name !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(name)))) {
       throw new DefinitionError(`steps[${index}].secrets must contain names only.`);
     }
@@ -5073,8 +5104,9 @@ function parseDeployDefinition(value) {
       name: text(step.name, `steps[${index}].name`),
       run: text(step.run, `steps[${index}].run`),
       phase,
+      scope: step.scope,
+      profiles: selectedProfiles,
       secrets: step.secrets,
-      once: step.once === true,
       always: step.always === true,
       timeoutMs,
       when
@@ -5087,7 +5119,7 @@ function parseDeployDefinition(value) {
     version: PIPELINE_VERSION,
     name: text(root.name, "pipeline.name"),
     requireAttestation: root.requireAttestation === true,
-    roles,
+    profiles,
     steps
   };
 }
@@ -5217,7 +5249,7 @@ function createDeploymentManager(options) {
   const exec = options.exec ?? shell;
   const projectExec = options.projectExec ?? exec;
   const now = options.now ?? Date.now;
-  const readDefinition = options.readDefinition ?? ((path) => Bun.YAML.parse(readFileSync2(path, "utf8")));
+  const readDefinition = options.readDefinition ?? ((path) => JSON.parse(readFileSync2(path, "utf8")));
   const credentialsDirectory = process.env.CREDENTIALS_DIRECTORY;
   const gitCredentialPath = options.gitCredentialPath ?? (credentialsDirectory ? join(credentialsDirectory, "git-deploy-key") : undefined);
   const knownHostsPath = options.knownHostsPath ?? "/etc/forgezero/git/known_hosts";
@@ -5332,22 +5364,22 @@ function createDeploymentManager(options) {
     if (request.revision && head !== request.revision) {
       throw new DeploymentError("SOURCE_FAILED", `Git checked out ${head}, not requested ${request.revision}.`);
     }
-    const definition = parseDeployDefinition(readDefinition(join(release, ".fz", "deploy.yaml")));
-    const selectedRole = definition.roles.find((candidate) => candidate.name === options.role);
-    if (!selectedRole)
-      throw new DeploymentError("PIPELINE_FAILED", `pipeline role does not exist: ${options.role}.`);
-    if (selectedRole.software.length > 0) {
+    const definition = parseDeployDefinition(readDefinition(join(release, ".fz", "deploy.json")));
+    const selectedProfile = definition.profiles[options.profile];
+    if (!selectedProfile)
+      throw new DeploymentError("PIPELINE_FAILED", `pipeline profile does not exist: ${options.profile}.`);
+    if (selectedProfile.software.length > 0) {
       if (!options.ensureSoftware) {
         throw new DeploymentError("PIPELINE_FAILED", "the supervised software helper is unavailable");
       }
-      await options.ensureSoftware(selectedRole.software);
+      await options.ensureSoftware(selectedProfile.software);
     }
     const phaseEnvironment = {
       ...options.environment ?? {},
       FZ_RELEASE: release,
       FZ_DEPLOY_REVISION: head,
       FZ_DEPLOY_BRANCH: options.branch,
-      FZ_DEPLOY_ROLE: options.role,
+      FZ_DEPLOY_PROFILE: options.profile,
       ...options.publicApiUrl ? { PUBLIC_API_URL: options.publicApiUrl } : {}
     };
     const phaseExec = ({ command, env: secrets, timeoutMs }) => projectExec({ command, cwd: release, env: { ...phaseEnvironment, ...secrets }, timeoutMs });
@@ -5363,7 +5395,7 @@ function createDeploymentManager(options) {
         return {
           name: `${definition.name}:${phase}`,
           requireAttestation: definition.requireAttestation,
-          steps: definition.steps.filter((step) => step.phase === phase && (!step.once || request.coordinator === true) && (!step.when || Object.entries(step.when).every(([name, expected]) => phaseEnvironment[name] === expected)))
+          steps: definition.steps.filter((step) => step.phase === phase && (!step.profiles || step.profiles.includes(options.profile)) && (step.scope === "target" || request.releaseExecutor === true) && (!step.when || Object.entries(step.when).every(([name, expected]) => phaseEnvironment[name] === expected)))
         };
       })
     ].filter((pipeline) => pipeline.steps.length > 0);
@@ -5400,7 +5432,7 @@ function createDeploymentManager(options) {
       return revision.toLowerCase();
     },
     deploy(request = {}) {
-      const revisionKey = request.revision ? `${request.revision.toLowerCase()}:${request.coordinator === true ? "coordinator" : "node"}` : undefined;
+      const revisionKey = request.revision ? `${request.revision.toLowerCase()}:${request.releaseExecutor === true ? "release" : "target"}` : undefined;
       if (revisionKey) {
         const existing = activeRevisions.get(revisionKey);
         if (existing)
@@ -5592,7 +5624,7 @@ async function deployClaim(options, claim) {
   schedule();
   let result;
   try {
-    result = await manager.deploy({ revision: claim.revision, coordinator: claim.coordinator }).result;
+    result = await manager.deploy({ revision: claim.revision, releaseExecutor: claim.releaseExecutor }).result;
   } finally {
     stopped = true;
     clearTimer(timer);
@@ -6377,11 +6409,10 @@ ${attestationSetup}if [[ ! -x /usr/local/bin/bun ]]; then
   install -m 0755 ${agentBun}/bin/bun /usr/local/bin/bun
   rm -f /run/fz-bun-install
 fi
-if [[ ! -x /usr/local/bin/fz-agent ]] || [[ "$(/usr/local/bin/fz-agent --version 2>/dev/null || true)" != "${profile.agentVersion}" ]]; then
+if [[ ! -x /usr/local/lib/forgezero/agent/fz-agent ]] || [[ "$(/usr/local/lib/forgezero/agent/fz-agent --version 2>/dev/null || true)" != "${profile.agentVersion}" ]]; then
   env BUN_INSTALL=${agentBun} /usr/local/bin/bun add -g --no-cache --force @forgezero/agent@${profile.agentVersion}
-  ln -sfn ${agentBun}/bin/fz-agent /usr/local/bin/fz-agent
 fi
-env   FZ_API=${profile.apiUrl}   FZ_AGENT_BIN=/usr/local/bin/fz-agent   FZ_AGENT_USER=forgezero-agent   FZ_SOCKET_PATH=/run/forgezero/vault.sock   FZ_SEED_CREDENTIAL_PATH=/etc/forgezero/creds/agent-seed.cred   FZ_GIT_CREDENTIAL_PATH=/etc/forgezero/creds/git-deploy-key.cred   FZ_GIT_PUBLIC_KEY_PATH=/etc/forgezero/git/deploy.pub   FZ_DEPLOY_ROOT=/opt/forgezero   FZ_DEPLOY_PULL=${hasEnrolment ? "true" : "false"}   FZ_NODE_LABEL=${nodeLabel}   ${agentBun}/bin/fz agent install --apply${hasEnrolment ? " --enrol" : ""}
+env   FZ_API=${profile.apiUrl}   FZ_AGENT_BIN=/usr/local/lib/forgezero/agent/fz-agent   FZ_AGENT_USER=forgezero-agent   FZ_SOCKET_PATH=/run/forgezero/vault.sock   FZ_SEED_CREDENTIAL_PATH=/etc/forgezero/creds/agent-seed.cred   FZ_GIT_CREDENTIAL_PATH=/etc/forgezero/creds/git-deploy-key.cred   FZ_GIT_PUBLIC_KEY_PATH=/etc/forgezero/git/deploy.pub   FZ_DEPLOY_ROOT=/opt/forgezero   FZ_DEPLOY_PULL=${hasEnrolment ? "true" : "false"}   FZ_NODE_LABEL=${nodeLabel}   ${agentBun}/bin/fz agent install --apply${hasEnrolment ? " --enrol" : ""}
 `;
 }
 function cloudInit(profile, claim, manifest) {
@@ -7876,7 +7907,7 @@ function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, t
 import { readFileSync as readFileSync7 } from "fs";
 
 // src/version.ts
-var VERSION2 = "0.1.28";
+var VERSION2 = "0.1.30";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");
@@ -8165,7 +8196,7 @@ if (import.meta.main) {
       "  FZ_SEED_PATH       legacy/dev seed file (default: " + DEFAULT_SEED_PATH + ")",
       "  FZ_NODE_KEY      override the node key  (default: derived from the seed)",
       "",
-      "  deploy [--revision=<full-sha>] [--coordinator]",
+      "  deploy [--revision=<full-sha>] [--release-executor]",
       "  identity            print this sealed seed's public identity",
       "  enrol               consume a systemd-loaded compute capability",
       "  metal-helper --profile=/etc/forgezero/metal.json",
@@ -8222,9 +8253,9 @@ if (import.meta.main) {
     const profilePath = args.find((arg) => arg.startsWith("--profile="))?.slice("--profile=".length);
     if (!profilePath)
       throw new Error("metal-helper requires --profile=/absolute/path.json");
-    const profile = JSON.parse(readFileSync8(profilePath, "utf8"));
+    const profile2 = JSON.parse(readFileSync8(profilePath, "utf8"));
     const helper = startMetalHelper({
-      profile,
+      profile: profile2,
       socketPath: process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET
     });
     console.log(`[metal-helper] listening on ${process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET}`);
@@ -8340,8 +8371,8 @@ if (import.meta.main) {
     const profilePath = args.find((arg) => arg.startsWith("--profile="))?.slice("--profile=".length);
     if (!profilePath)
       throw new Error("metal-isolation requires --profile=/absolute/path.json");
-    const profile = JSON.parse(readFileSync8(profilePath, "utf8"));
-    await applyMetalIsolation(profile);
+    const profile2 = JSON.parse(readFileSync8(profilePath, "utf8"));
+    await applyMetalIsolation(profile2);
     console.log("[metal-isolation] host and guest cgroup boundaries active");
     process.exit(0);
   }
@@ -8469,7 +8500,7 @@ if (import.meta.main) {
       op: "deploy",
       request: {
         revision: revisionArg?.slice("--revision=".length),
-        coordinator: args.includes("--coordinator")
+        releaseExecutor: args.includes("--release-executor")
       }
     } : command2 === "cancel" ? { op: "cancel", id: idArg?.slice("--id=".length) ?? "" } : ["pause-key", "resume-key", "stop-key", "start-key"].includes(command2) ? {
       op: command2,
@@ -8487,7 +8518,6 @@ if (import.meta.main) {
   const attestationSource = existsSync13("/dev/sev-guest") ? createSnpAttestationSource() : undefined;
   const running = runAgent({
     socketPath: process.env.FZ_SOCKET_PATH ?? DEFAULT_SOCKET_PATH,
-    listenFd: systemdListenFd(),
     seedCredential: process.env.FZ_SEED_CREDENTIAL,
     seedPath: process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH,
     nodeKey: process.env.FZ_NODE_KEY,
@@ -8577,19 +8607,19 @@ if (import.meta.main) {
   } : systemdDeploymentSecrets;
   const repository = process.env.FZ_DEPLOY_REPO;
   const branch = process.env.FZ_DEPLOY_BRANCH;
-  const role = process.env.FZ_DEPLOY_ROLE;
+  const profile = process.env.FZ_DEPLOY_PROFILE;
   const root = process.env.FZ_DEPLOY_ROOT;
   const pullEnabled = process.env.FZ_DEPLOY_PULL === "true" && Boolean(process.env.FZ_API);
   if (pullEnabled && !binding) {
     throw new Error("agent: outbound guest deployment requires a persisted tenant enrolment binding");
   }
-  if (root && (repository && branch && role || pullEnabled)) {
+  if (root && (repository && branch && profile || pullEnabled)) {
     const managers = new Map;
     const managerOptions = (source, key) => ({
       key,
       repository: source.repository,
       branch: source.branch,
-      role: source.role,
+      profile: source.profile,
       sourceAuth: source.auth,
       root,
       publicApiUrl: process.env.FZ_PUBLIC_API_URL,
@@ -8606,7 +8636,7 @@ if (import.meta.main) {
       ensureSoftware: (requirements) => requestSoftware(requirements, process.env.FZ_SOFTWARE_HELPER_SOCKET ?? DEFAULT_SOFTWARE_HELPER_SOCKET),
       projectExec: process.env.FZ_DEPLOY_RUNNER_SOCKET ? (input) => requestDeploymentCommand(input, process.env.FZ_DEPLOY_RUNNER_SOCKET) : undefined
     });
-    const staticManager = repository && branch && role ? createDeploymentManager(managerOptions({ repository, branch, role }, process.env.FZ_DEPLOY_KEY ?? `${repository}:${branch}:${role}`)) : undefined;
+    const staticManager = repository && branch && profile ? createDeploymentManager(managerOptions({ repository, branch, profile }, process.env.FZ_DEPLOY_KEY ?? `${repository}:${branch}:${profile}`)) : undefined;
     if (staticManager)
       managers.set("__static__", staticManager);
     const control = staticManager ? startControlServer(staticManager, process.env.FZ_CONTROL_SOCKET ?? DEFAULT_CONTROL_SOCKET) : undefined;
@@ -8622,7 +8652,7 @@ if (import.meta.main) {
           claim.pipelineKey,
           claim.source.repository,
           claim.source.branch,
-          claim.source.role,
+          claim.source.profile,
           JSON.stringify(claim.source.auth ?? null)
         ].join("\x00");
         const existing = managers.get(cacheKey);
@@ -8820,6 +8850,8 @@ export {
   SUPPORTED_GUEST_IMAGE,
   SOFTWARE_HELPER_UNIT_PATH,
   SOFTWARE_HELPER_GROUP,
+  SOFTWARE_CATALOG,
+  OS_CATALOG,
   MAX_AGENT_TARBALL_BYTES,
   DeploymentError,
   DEFAULT_SOFTWARE_HELPER_SOCKET,