@forgezero/agent 0.1.29 → 0.1.31

package/dist/index.d.ts

@@ -32,8 +32,8 @@ export type { AgentRelease, StagedAgentRelease, UpdateCommand, UpdateCommandResu
 export { activateAgentRelease, probeAgentSocket, requestAgentUpdate, startAgentUpdateHelper, AGENT_UPDATE_GROUP, AGENT_UPDATE_HELPER_UNIT_PATH, AGENT_UPDATE_RECEIPT } from './agent-update-helper';
 export type { AgentUpdateRequest, AgentUpdateResponse } from './agent-update-helper';
 export { DEFAULT_SOFTWARE_HELPER_SOCKET, requestSoftware, startSoftwareHelper, SOFTWARE_HELPER_GROUP, SOFTWARE_HELPER_UNIT_PATH } from './software-helper';
-export { ensureSoftwareRequirements, observeSoftwareHost, validateSoftwareRequirements } from './software';
-export type { SoftwareCommandResult, SoftwareExec, SoftwareObservation, SoftwareRequirement } from './software';
+export { ensureSoftwareRequirements, observeSoftwareHost, validateSoftwareRequirements, OS_CATALOG, SOFTWARE_CATALOG } from './software';
+export type { CatalogStatus, DeploymentChannel, OsCatalogEntry, SoftwareCatalogEntry, SoftwareCommandResult, SoftwareExec, SoftwareId, SoftwareObservation, SoftwareRequirement } from './software';
 export { heartbeatAgentOnce, observeAgentHost, startAgentHeartbeat } from './agent-heartbeat';
 export type { AgentHeartbeatOptions, AgentHeartbeatResponse, AgentObservation } from './agent-heartbeat';
 export { DEFAULT_DEPLOYMENT_RUNNER_SOCKET, requestDeploymentCommand, startDeploymentRunner } from './deployment-runner';

package/dist/project-context.d.ts

@@ -0,0 +1,37 @@
+export declare const PROJECT_CONTEXT_VERSION: 1;
+export interface ProjectTruthSource {
+    area: string;
+    path: string;
+    description: string;
+}
+export interface ProjectContextManifest {
+    schemaVersion: typeof PROJECT_CONTEXT_VERSION;
+    name: string;
+    purpose: string;
+    truth: readonly ProjectTruthSource[];
+    readFirst: readonly string[];
+    verify: readonly string[];
+    rules: readonly string[];
+    /** Files or directories that are generated, historical, or otherwise not authoritative. */
+    nonAuthoritative: readonly string[];
+}
+export interface ContextFile {
+    path: string;
+    content: string;
+}
+export interface ContextCheck {
+    ok: boolean;
+    problems: string[];
+}
+export declare class ProjectContextError extends Error {
+    constructor(message: string);
+}
+export declare function parseProjectContext(value: unknown): ProjectContextManifest;
+export declare function defaultProjectContext(root?: string): ProjectContextManifest;
+export declare function renderProjectContext(manifest: ProjectContextManifest): string;
+export declare function projectContextFiles(manifestInput: ProjectContextManifest): ContextFile[];
+export declare function initializeProjectContext(rootInput: string, manifestInput?: ProjectContextManifest, options?: {
+    force?: boolean;
+}): ContextFile[];
+export declare function syncProjectContext(rootInput: string): ContextFile[];
+export declare function checkProjectContext(rootInput: string): ContextCheck;

package/dist/project-context.js

@@ -0,0 +1,266 @@
+// @bun
+// src/project-context.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+var PROJECT_CONTEXT_VERSION = 1;
+var GENERATED = "<!-- Generated by @forgezero/agent project context. Edit .forgezero/project.json, then run `fz project sync`. -->";
+
+class ProjectContextError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProjectContextError";
+  }
+}
+var text = (value, where) => {
+  if (typeof value !== "string" || !value.trim() || /[\r\0]/.test(value)) {
+    throw new ProjectContextError(`${where} must be non-empty text.`);
+  }
+  return value.trim();
+};
+var relativePath = (value, where) => {
+  const path = text(value, where);
+  if (path.startsWith("/") || path.split("/").includes("..")) {
+    throw new ProjectContextError(`${where} must stay inside the repository.`);
+  }
+  return path.replace(/^\.\//, "");
+};
+var stringList = (value, where, paths = false) => {
+  if (!Array.isArray(value) || value.length > 128) {
+    throw new ProjectContextError(`${where} must be an array of at most 128 entries.`);
+  }
+  const items = value.map((item, index) => paths ? relativePath(item, `${where}[${index}]`) : text(item, `${where}[${index}]`));
+  if (new Set(items).size !== items.length)
+    throw new ProjectContextError(`${where} must not contain duplicates.`);
+  return items;
+};
+function parseProjectContext(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ProjectContextError("project context must be an object.");
+  }
+  const row = value;
+  const allowed = ["schemaVersion", "name", "purpose", "truth", "readFirst", "verify", "rules", "nonAuthoritative"];
+  const unknown = Object.keys(row).filter((key) => !allowed.includes(key));
+  if (unknown.length)
+    throw new ProjectContextError(`project context contains unknown field(s): ${unknown.join(", ")}.`);
+  if (row.schemaVersion !== PROJECT_CONTEXT_VERSION) {
+    throw new ProjectContextError(`project context schemaVersion must be ${PROJECT_CONTEXT_VERSION}.`);
+  }
+  if (!Array.isArray(row.truth) || row.truth.length === 0 || row.truth.length > 64) {
+    throw new ProjectContextError("project context truth must contain from 1 to 64 sources.");
+  }
+  const truth = row.truth.map((item, index) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new ProjectContextError(`truth[${index}] must be an object.`);
+    }
+    const source = item;
+    if (Object.keys(source).some((key) => !["area", "path", "description"].includes(key))) {
+      throw new ProjectContextError(`truth[${index}] contains an unknown field.`);
+    }
+    return {
+      area: text(source.area, `truth[${index}].area`),
+      path: relativePath(source.path, `truth[${index}].path`),
+      description: text(source.description, `truth[${index}].description`)
+    };
+  });
+  const areas = truth.map((source) => source.area);
+  if (new Set(areas).size !== areas.length)
+    throw new ProjectContextError("project context truth areas must be unique.");
+  return {
+    schemaVersion: PROJECT_CONTEXT_VERSION,
+    name: text(row.name, "project context name"),
+    purpose: text(row.purpose, "project context purpose"),
+    truth,
+    readFirst: stringList(row.readFirst, "project context readFirst", true),
+    verify: stringList(row.verify, "project context verify"),
+    rules: stringList(row.rules, "project context rules"),
+    nonAuthoritative: stringList(row.nonAuthoritative, "project context nonAuthoritative", true)
+  };
+}
+function defaultProjectContext(root = process.cwd()) {
+  let name = root.split("/").filter(Boolean).at(-1) ?? "project";
+  let verify = ["npm test"];
+  const manifestPath = join(root, "package.json");
+  if (existsSync(manifestPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(manifestPath, "utf8"));
+      name = pkg.name ?? name;
+      const runner = existsSync(join(root, "bun.lock")) ? "bun run" : "npm run";
+      verify = ["check", "test", "build"].filter((script) => pkg.scripts?.[script]).map((script) => `${runner} ${script}`);
+      if (verify.length === 0)
+        verify = [existsSync(join(root, "bun.lock")) ? "bun test" : "npm test"];
+    } catch {}
+  }
+  return {
+    schemaVersion: PROJECT_CONTEXT_VERSION,
+    name,
+    purpose: "Describe the product outcome here; implementation details belong in the truth sources below.",
+    truth: [
+      { area: "architecture", path: "docs/architecture.md", description: "Current system boundaries and decisions." },
+      { area: "progress", path: "docs/progress.md", description: "Evidence-backed delivery state and next work." }
+    ],
+    readFirst: [".forgezero/PROJECT.md"],
+    verify,
+    rules: [
+      "Inspect the current worktree before editing and preserve unrelated changes.",
+      "Update a truth source instead of copying architecture or progress into another document.",
+      "Never report a feature as complete without running its declared verification."
+    ],
+    nonAuthoritative: ["audit/"]
+  };
+}
+function renderProjectContext(manifest) {
+  const truth = manifest.truth.map((source) => `| ${source.area} | \`${source.path}\` | ${source.description} |`).join(`
+`);
+  return `${GENERATED}
+# ${manifest.name} \u2014 project context
+
+${manifest.purpose}
+
+## Read first
+
+${manifest.readFirst.map((path) => `- \`${path}\``).join(`
+`) || "- No additional entry points."}
+
+## Sources of truth
+
+| Area | Path | Authority |
+|---|---|---|
+${truth}
+
+If two files disagree, the file named in this table wins. Fix or regenerate the
+other file in the same change. Conversation memory, audit snapshots and generated
+output never override repository truth.
+
+## Project rules
+
+${manifest.rules.map((rule) => `- ${rule}`).join(`
+`) || "- No additional project rules."}
+
+## Verification
+
+${manifest.verify.map((command) => `- \`${command}\``).join(`
+`) || "- No verification command declared."}
+
+## Non-authoritative material
+
+${manifest.nonAuthoritative.map((path) => `- \`${path}\``).join(`
+`) || "- None declared."}
+
+Tools, skills and AI vendors may change. They are execution aids, not memory.
+Persist every accepted decision and status change in the source of truth that
+owns it, then run \`fz project check\` before handoff.
+`;
+}
+var adapter = (name) => `${GENERATED}
+# ${name} project instructions
+
+Read \`.forgezero/PROJECT.md\` completely before acting. It is generated from
+\`.forgezero/project.json\`, the vendor-neutral project context. Follow every
+source of truth and verification command it names.
+
+Do not treat this adapter, conversation memory, an audit report, generated
+output, a tool, or a skill as architectural authority. When work changes an
+accepted decision or delivery state, update the named Git source in the same
+change and run \`fz project check\`.
+`;
+function projectContextFiles(manifestInput) {
+  const manifest = parseProjectContext(manifestInput);
+  return [
+    { path: ".forgezero/PROJECT.md", content: renderProjectContext(manifest) },
+    { path: "AGENTS.md", content: adapter("AI agent") },
+    { path: "CLAUDE.md", content: adapter("Claude") },
+    { path: "GEMINI.md", content: adapter("Gemini") },
+    { path: ".github/copilot-instructions.md", content: adapter("GitHub Copilot") },
+    { path: ".cursor/rules/project-context.mdc", content: `${GENERATED}
+---
+description: Repository source-of-truth contract
+alwaysApply: true
+---
+
+${adapter("Cursor").replace(`${GENERATED}
+`, "")}` }
+  ];
+}
+var atomicWrite = (path, content) => {
+  mkdirSync(dirname(path), { recursive: true });
+  const next = `${path}.${process.pid}.next`;
+  writeFileSync(next, content, { mode: 420 });
+  renameSync(next, path);
+};
+function initializeProjectContext(rootInput, manifestInput = defaultProjectContext(rootInput), options = {}) {
+  const root = resolve(rootInput);
+  const manifest = parseProjectContext(manifestInput);
+  const manifestPath = join(root, ".forgezero", "project.json");
+  const files = projectContextFiles(manifest);
+  const collisions = [manifestPath, ...files.map((file) => join(root, file.path))].filter((path) => {
+    if (!existsSync(path))
+      return false;
+    if (path === manifestPath)
+      return true;
+    return !readFileSync(path, "utf8").startsWith(GENERATED);
+  });
+  if (collisions.length && !options.force) {
+    throw new ProjectContextError(`refusing to replace existing project context: ${collisions.join(", ")}`);
+  }
+  atomicWrite(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  for (const file of files)
+    atomicWrite(join(root, file.path), file.content);
+  return files;
+}
+function syncProjectContext(rootInput) {
+  const root = resolve(rootInput);
+  const manifestPath = join(root, ".forgezero", "project.json");
+  if (!existsSync(manifestPath))
+    throw new ProjectContextError("No .forgezero/project.json. Run `fz project init`.");
+  const manifest = parseProjectContext(JSON.parse(readFileSync(manifestPath, "utf8")));
+  const files = projectContextFiles(manifest);
+  for (const file of files) {
+    const path = join(root, file.path);
+    if (existsSync(path) && !readFileSync(path, "utf8").startsWith(GENERATED)) {
+      throw new ProjectContextError(`refusing to replace non-generated adapter: ${file.path}`);
+    }
+    atomicWrite(path, file.content);
+  }
+  return files;
+}
+function checkProjectContext(rootInput) {
+  const root = resolve(rootInput);
+  const manifestPath = join(root, ".forgezero", "project.json");
+  if (!existsSync(manifestPath))
+    return { ok: false, problems: ["missing .forgezero/project.json"] };
+  let manifest;
+  try {
+    manifest = parseProjectContext(JSON.parse(readFileSync(manifestPath, "utf8")));
+  } catch (cause) {
+    return { ok: false, problems: [cause instanceof Error ? cause.message : String(cause)] };
+  }
+  const problems = [];
+  for (const source of manifest.truth) {
+    if (!existsSync(join(root, source.path)))
+      problems.push(`missing truth source: ${source.path}`);
+  }
+  for (const path of manifest.readFirst) {
+    if (!existsSync(join(root, path)))
+      problems.push(`missing read-first file: ${path}`);
+  }
+  for (const file of projectContextFiles(manifest)) {
+    const path = join(root, file.path);
+    if (!existsSync(path))
+      problems.push(`missing generated adapter: ${file.path}`);
+    else if (readFileSync(path, "utf8") !== file.content)
+      problems.push(`drifted generated adapter: ${file.path}`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+export {
+  syncProjectContext,
+  renderProjectContext,
+  projectContextFiles,
+  parseProjectContext,
+  initializeProjectContext,
+  defaultProjectContext,
+  checkProjectContext,
+  ProjectContextError,
+  PROJECT_CONTEXT_VERSION
+};

package/dist/provision.d.ts

@@ -83,7 +83,7 @@ export interface UnitOptions {
     controlSocketPath?: string;
     repository?: string;
     branch?: string;
-    role?: string;
+    profile?: string;
     deployRoot?: string;
     publicApiUrl?: string;
     /** Non-secret phase values, named explicitly instead of inheriting the unit environment. */

package/dist/provision.js

@@ -361,6 +361,16 @@ import { readFileSync as readFileSync2 } 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" },
@@ -399,7 +409,7 @@ function observeSoftwareHost(osRelease = readFileSync2("/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;
@@ -417,13 +427,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 !== "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();
-  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 = [];
@@ -554,7 +569,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION2 = "0.1.29";
+var VERSION2 = "0.1.31";
 
 // src/provision.ts
 function atLeast(version, floor) {
@@ -993,7 +1008,7 @@ function agentUnit(options) {
     options.gitPublicKeyPath ? `FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}` : null,
     options.repository ? `FZ_DEPLOY_REPO=${options.repository}` : null,
     options.branch ? `FZ_DEPLOY_BRANCH=${options.branch}` : null,
-    options.role ? `FZ_DEPLOY_ROLE=${options.role}` : null,
+    options.profile ? `FZ_DEPLOY_PROFILE=${options.profile}` : null,
     options.repository && options.branch ? `FZ_DEPLOY_KEY=${options.project ?? "platform"}:${options.environment ?? "production"}` : null,
     deploymentEnabled ? `FZ_DEPLOY_ROOT=${deployRoot}` : null,
     deploymentEnabled ? `FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}` : null,

package/dist/software-helper.js

@@ -3,6 +3,16 @@ 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" },
@@ -41,7 +51,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;
@@ -59,13 +69,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 !== "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();
-  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 = [];

package/dist/software.d.ts

@@ -1,8 +1,25 @@
+export type CatalogStatus = 'testing' | 'active' | 'retired';
+export type DeploymentChannel = 'development' | 'production';
+export type SoftwareId = 'bun' | 'nginx' | 'arangodb' | 'cloudflared' | 'ufw';
 /** Repository input is a catalogue coordinate, never a root command. */
 export interface SoftwareRequirement {
-    id: 'bun' | 'nginx' | 'arangodb' | 'cloudflared' | 'ufw';
+    id: SoftwareId;
     version: string;
 }
+export interface SoftwareCatalogEntry extends SoftwareRequirement {
+    status: CatalogStatus;
+    os: 'ubuntu';
+    osVersion: '26.04';
+    architecture: 'x64';
+    /** What promotes this coordinate beyond an unreviewed candidate. */
+    evidence: 'reviewed-strategy-and-tests';
+}
+export interface OsCatalogEntry {
+    id: 'ubuntu';
+    version: '26.04';
+    architecture: 'x64';
+    status: CatalogStatus;
+}
 export interface SoftwareObservation {
     os: {
         id: string;
@@ -15,8 +32,13 @@ export interface SoftwareCommandResult {
     output: string;
 }
 export type SoftwareExec = (command: string) => Promise<SoftwareCommandResult>;
+/** Public, command-free catalog. Root strategies remain private below. */
+export declare const OS_CATALOG: readonly OsCatalogEntry[];
+export declare const SOFTWARE_CATALOG: readonly SoftwareCatalogEntry[];
 export declare function observeSoftwareHost(osRelease?: string, architecture?: NodeJS.Architecture): SoftwareObservation;
-export declare function validateSoftwareRequirements(value: unknown): SoftwareRequirement[];
+export declare function validateSoftwareRequirements(value: unknown, _options?: {
+    channel?: DeploymentChannel;
+}): SoftwareRequirement[];
 export declare function ensureSoftwareRequirements(requirementsInput: unknown, options: {
     observation?: SoftwareObservation;
     exec: SoftwareExec;

package/dist/software.js

@@ -3,6 +3,16 @@ 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" },
@@ -41,7 +51,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;
@@ -59,13 +69,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 !== "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();
-  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 = [];
@@ -91,5 +106,7 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
 export {
   validateSoftwareRequirements,
   observeSoftwareHost,
-  ensureSoftwareRequirements
+  ensureSoftwareRequirements,
+  SOFTWARE_CATALOG,
+  OS_CATALOG
 };

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.29";
+export declare const VERSION = "0.1.31";

package/package.json

@@ -1,12 +1,12 @@
 {
 	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/agent",
-	"version": "0.1.29",
+	"version": "0.1.31",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",
 		"prebuild": "rm -rf dist",
-		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/agent-update.ts src/agent-update-helper.ts src/agent-heartbeat.ts src/software.ts src/software-helper.ts src/ubuntu.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/deploy-file.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/agent-update.ts src/agent-update-helper.ts src/agent-heartbeat.ts src/software.ts src/software-helper.ts src/ubuntu.ts --root src --outdir dist --target browser --format esm --packages external && bun build src/project-context.ts --root src --outdir dist --target bun --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"devDependencies": {
@@ -34,6 +34,7 @@
 	},
 	"files": [
 		"dist",
+		"schema",
 		"README.md",
 		"LICENSE"
 	],
@@ -72,6 +73,11 @@
 			"types": "./dist/definition.d.ts",
 			"default": "./dist/definition.js"
 		},
+		"./deploy-file": {
+			"types": "./dist/deploy-file.d.ts",
+			"default": "./dist/deploy-file.js"
+		},
+		"./schema/deploy-v2.json": "./schema/deploy-v2.json",
 		"./ssh-listen": {
 			"types": "./dist/ssh-listen.d.ts",
 			"default": "./dist/ssh-listen.js"
@@ -123,6 +129,10 @@
 		"./ubuntu": {
 			"types": "./dist/ubuntu.d.ts",
 			"default": "./dist/ubuntu.js"
+		},
+		"./project-context": {
+			"types": "./dist/project-context.d.ts",
+			"default": "./dist/project-context.js"
 		}
 	}
 }

package/schema/deploy-v2.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://www.forgezero.net/schemas/deploy-v2.json",
+  "title": "ForgeZero deployment pipeline",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "name", "profiles", "steps"],
+  "properties": {
+    "$schema": { "type": "string", "const": "https://www.forgezero.net/schemas/deploy-v2.json" },
+    "version": { "const": 2 },
+    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
+    "requireAttestation": { "type": "boolean" },
+    "profiles": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 32,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]{0,62}$" },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["software"],
+        "properties": {
+          "software": {
+            "type": "array",
+            "maxItems": 32,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "version"],
+              "properties": {
+                "id": { "enum": ["bun", "nginx", "arangodb", "cloudflared", "ufw"] },
+                "version": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "phase", "scope", "run"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "phase": { "enum": ["build", "release", "migrate", "health"] },
+          "scope": { "enum": ["target", "release"] },
+          "profiles": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,62}$" }
+          },
+          "run": { "type": "string", "minLength": 1 },
+          "secrets": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" }, "uniqueItems": true },
+          "always": { "type": "boolean" },
+          "when": {
+            "type": "object",
+            "minProperties": 1,
+            "propertyNames": { "pattern": "^[A-Z_][A-Z0-9_]*$" },
+            "additionalProperties": { "type": "string", "minLength": 1 }
+          },
+          "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 86400000 }
+        }
+      }
+    }
+  }
+}