@forgezero/agent 0.1.29 → 0.1.31

package/dist/fz.js

@@ -4871,8 +4871,8 @@ async function spawnWith(command, env, report = () => {}) {
 
 // src/cli/index.ts
 init_dist();
-import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
-import { dirname } from "path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, statSync, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/agent-update.ts
@@ -4886,12 +4886,22 @@ var AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-
 var MAX_REQUEST_BYTES = 8 * 1024;
 
 // src/version.ts
-var VERSION2 = "0.1.29";
+var VERSION2 = "0.1.31";
 
 // src/software.ts
 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" },
@@ -4919,6 +4929,31 @@ var UBUNTU_2604_X64 = [
     install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
   }
 ];
+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;
+  });
+}
 
 // src/software-helper.ts
 var DEFAULT_SOFTWARE_HELPER_SOCKET = "/run/forgezero-software/helper.sock";
@@ -5363,7 +5398,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,
@@ -9275,6 +9310,517 @@ async function resolveIdentity(selector, socketPath) {
   return chosen;
 }
 
+// src/project-context.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname, join as join2, 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 = join2(root, "package.json");
+  if (existsSync(manifestPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(manifestPath, "utf8"));
+      name = pkg.name ?? name;
+      const runner = existsSync(join2(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(join2(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 = join2(root, ".forgezero", "project.json");
+  const files = projectContextFiles(manifest);
+  const collisions = [manifestPath, ...files.map((file) => join2(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(join2(root, file.path), file.content);
+  return files;
+}
+function syncProjectContext(rootInput) {
+  const root = resolve(rootInput);
+  const manifestPath = join2(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 = join2(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 = join2(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(join2(root, source.path)))
+      problems.push(`missing truth source: ${source.path}`);
+  }
+  for (const path of manifest.readFirst) {
+    if (!existsSync(join2(root, path)))
+      problems.push(`missing read-first file: ${path}`);
+  }
+  for (const file of projectContextFiles(manifest)) {
+    const path = join2(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 };
+}
+
+// src/deploy-file.ts
+import { createHash as createHash2 } from "crypto";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { basename, join as join3 } from "path";
+
+// 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 text2 = (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 NAME2 = /^[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 (!NAME2.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 = text2(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: text2(step.name, `steps[${index}].name`),
+      run: text2(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 = text2(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
+  };
+}
+
+// src/deploy-file.ts
+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:${createHash2("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 = join3(root, "package.json");
+  if (!existsSync2(packagePath))
+    return { bun: existsSync2(join3(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: existsSync2(join3(root, "bun.lock")) || existsSync2(join3(root, "bun.lockb"))
+    };
+  } catch {
+    return { bun: existsSync2(join3(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: id2, version }) => ({ id: id2, 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 = join3(root, DEPLOY_FILE);
+  if (!existsSync2(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 = join3(root, DEPLOY_FILE);
+  if (existsSync2(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 });
+  mkdirSync2(join3(root, ".fz"), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(raw, null, 2)}
+`, { mode: 420 });
+  return inspectDeployFile(root, { channel: options.channel });
+}
+
 // src/cli/index.ts
 var DEFAULT_MODE = THRESHOLD_MODES[0].id;
 var RECOMMENDED_MODE = (THRESHOLD_MODES.find((mode) => mode.recommended) ?? THRESHOLD_MODES[0]).id;
@@ -9290,7 +9836,13 @@ function parseOptions(argv) {
     mode: DEFAULT_MODE,
     user: process.env.FZ_USER ?? "operator",
     email: process.env.FZ_EMAIL ?? "operator@localhost",
-    preserveEnv: false
+    preserveEnv: false,
+    projectRoot: process.cwd(),
+    deployProfile: "app",
+    deploySoftware: [],
+    deployChannel: "production",
+    requireAttestation: false,
+    force: false
   };
   const positional = [];
   for (let index = 0;index < argv.length; index += 1) {
@@ -9309,6 +9861,26 @@ function parseOptions(argv) {
       options.enrol = true;
     else if (token === "--preserve-env")
       options.preserveEnv = true;
+    else if (token === "--root")
+      options.projectRoot = argv[++index] ?? options.projectRoot;
+    else if (token === "--name")
+      options.projectName = argv[++index];
+    else if (token === "--purpose")
+      options.projectPurpose = argv[++index];
+    else if (token === "--profile")
+      options.deployProfile = argv[++index] ?? options.deployProfile;
+    else if (token === "--software")
+      options.deploySoftware.push(argv[++index] ?? "");
+    else if (token === "--channel") {
+      const channel = argv[++index];
+      if (channel === "development" || channel === "production")
+        options.deployChannel = channel;
+      else
+        options.optionError = "--channel must be production or development.";
+    } else if (token === "--attestation")
+      options.requireAttestation = true;
+    else if (token === "--force")
+      options.force = true;
     else if (token === "--key")
       options.key = argv[++index];
     else if (token === "--mode")
@@ -9327,15 +9899,15 @@ function parseOptions(argv) {
   return { command: positional[0] ?? "help", args: positional.slice(1), options };
 }
 var out = {
-  line: (text = "") => process.stdout.write(`${text}
+  line: (text3 = "") => process.stdout.write(`${text3}
 `),
-  step: (text) => process.stdout.write(`  ${text}
+  step: (text3) => process.stdout.write(`  ${text3}
 `),
-  warn: (text) => process.stderr.write(`  ! ${text}
+  warn: (text3) => process.stderr.write(`  ! ${text3}
 `),
-  fail: (text) => process.stderr.write(`  \u2717 ${text}
+  fail: (text3) => process.stderr.write(`  \u2717 ${text3}
 `),
-  ok: (text) => process.stdout.write(`  \u2713 ${text}
+  ok: (text3) => process.stdout.write(`  \u2713 ${text3}
 `)
 };
 var sessionCookie = null;
@@ -9490,7 +10062,7 @@ async function cmdAgent(options, args) {
     controlSocketPath: process.env.FZ_CONTROL_SOCKET,
     repository: process.env.FZ_DEPLOY_REPO,
     branch: process.env.FZ_DEPLOY_BRANCH,
-    role: process.env.FZ_DEPLOY_ROLE,
+    profile: process.env.FZ_DEPLOY_PROFILE,
     deployRoot: process.env.FZ_DEPLOY_ROOT,
     publicApiUrl: process.env.FZ_PUBLIC_API_URL,
     deploymentEnvironment: parseAssignments(process.env.FZ_DEPLOY_ENV),
@@ -9540,17 +10112,17 @@ async function cmdAgent(options, args) {
     return 0;
   }
   try {
-    writeFileSync(plan.unitPath, plan.unit, { mode: 420 });
+    writeFileSync3(plan.unitPath, plan.unit, { mode: 420 });
     out.ok(`Wrote ${plan.unitPath}`);
     for (const auxiliary of plan.auxiliaryUnits) {
-      mkdirSync(dirname(auxiliary.path), { recursive: true, mode: 493 });
-      writeFileSync(auxiliary.path, auxiliary.unit, { mode: 420 });
+      mkdirSync3(dirname2(auxiliary.path), { recursive: true, mode: 493 });
+      writeFileSync3(auxiliary.path, auxiliary.unit, { mode: 420 });
       out.ok(`Wrote ${auxiliary.path}`);
     }
     if (options.enrol) {
-      if (existsSync(enrolTokenSourcePath)) {
+      if (existsSync3(enrolTokenSourcePath)) {
         const source = statSync(enrolTokenSourcePath);
-        const token = readFileSync(enrolTokenSourcePath, "utf8").trim();
+        const token = readFileSync3(enrolTokenSourcePath, "utf8").trim();
         if (!source.isFile() || (source.mode & 511) !== 384 || source.uid !== 0) {
           throw new Error("The preloaded enrolment token must be a root-owned 0600 file in /run.");
         }
@@ -9563,7 +10135,7 @@ async function cmdAgent(options, args) {
         if (await prompt.exited !== 0 || !/^fze_[A-Za-z0-9_-]{40,100}$/.test(token)) {
           throw new Error("A valid fze_ enrolment token was not provided.");
         }
-        writeFileSync(enrolTokenSourcePath, `${token}
+        writeFileSync3(enrolTokenSourcePath, `${token}
 `, { mode: 384, flag: "wx" });
       }
     }
@@ -9574,7 +10146,7 @@ async function cmdAgent(options, args) {
     out.line();
     out.line("  Add this machine-specific PUBLIC key as a read-only deploy key:");
     out.line();
-    out.line(`  ${readFileSync(gitPublicKeyPath, "utf8").trim()}`);
+    out.line(`  ${readFileSync3(gitPublicKeyPath, "utf8").trim()}`);
     out.line();
     return 0;
   } catch (cause) {
@@ -9691,6 +10263,123 @@ Is fz-agent running on this machine? \`fz agent install --apply\`.`);
     out.line(describeInjection(merged, Object.keys(secrets).length));
   return spawnWith(command, merged.env, (line) => out.line(line));
 }
+function cmdProject(options, args) {
+  const operation = args[0] ?? "check";
+  try {
+    if (operation === "init") {
+      const manifest = defaultProjectContext(options.projectRoot);
+      if (options.projectName)
+        manifest.name = options.projectName;
+      if (options.projectPurpose)
+        manifest.purpose = options.projectPurpose;
+      const files = initializeProjectContext(options.projectRoot, manifest, { force: options.force });
+      out.ok(`Project context initialized; ${files.length} generated adapters now share one Git source.`);
+      out.step("Edit .forgezero/project.json, create every named truth source, then run `fz project sync`.");
+      return 0;
+    }
+    if (operation === "sync") {
+      const files = syncProjectContext(options.projectRoot);
+      out.ok(`Synchronized ${files.length} AI adapters from .forgezero/project.json.`);
+      return 0;
+    }
+    if (operation === "check") {
+      const result = checkProjectContext(options.projectRoot);
+      if (options.json)
+        out.line(JSON.stringify(result, null, 2));
+      else if (result.ok)
+        out.ok("Project context and every AI adapter are in sync.");
+      else
+        for (const problem of result.problems)
+          out.fail(problem);
+      return result.ok ? 0 : 1;
+    }
+    out.fail("Usage: fz project init|sync|check [--root <path>] [--force]");
+    return 2;
+  } catch (cause) {
+    out.fail(cause instanceof Error ? cause.message : String(cause));
+    return 1;
+  }
+}
+function softwareCoordinates(values) {
+  if (values.length === 0)
+    return;
+  return values.map((coordinate) => {
+    const separator = coordinate.lastIndexOf("@");
+    if (separator < 1 || separator === coordinate.length - 1) {
+      throw new Error(`Software must be <key>@<version>, received: ${coordinate || "<empty>"}.`);
+    }
+    return {
+      id: coordinate.slice(0, separator),
+      version: coordinate.slice(separator + 1)
+    };
+  });
+}
+function cmdDeploy(options, args) {
+  const operation = args[0] ?? "check";
+  try {
+    if (options.optionError)
+      throw new Error(options.optionError);
+    if (operation === "init") {
+      const created = initializeDeployFile(options.projectRoot, {
+        name: options.projectName,
+        profile: options.deployProfile,
+        software: softwareCoordinates(options.deploySoftware),
+        requireAttestation: options.requireAttestation,
+        channel: options.deployChannel,
+        force: options.force
+      });
+      if (options.json)
+        out.line(JSON.stringify(created.summary, null, 2));
+      else {
+        out.ok(`Initialized .fz/deploy.json (${created.summary.digest}).`);
+        out.warn("Release and health use safe blockers until you replace them with project-specific commands.");
+        out.step("Run `fz deploy check`, commit the file, then push; the verified Git commit is the live sync.");
+      }
+      return 0;
+    }
+    if (operation === "check" || operation === "sync") {
+      const inspected = inspectDeployFile(options.projectRoot, { channel: options.deployChannel });
+      if (options.json)
+        out.line(JSON.stringify(inspected.summary, null, 2));
+      else {
+        out.step(`${inspected.summary.name} \xB7 v${inspected.summary.version} \xB7 ${inspected.summary.digest}`);
+        out.step(`profiles: ${inspected.summary.profiles.join(", ")}`);
+        for (const problem of inspected.summary.problems)
+          out.fail(problem);
+        if (inspected.summary.ready) {
+          out.ok("Deploy definition is typed, catalog-valid and ready to commit.");
+          if (operation === "sync") {
+            out.step("Commit and push this file. ForgeZero deploys the exact webhook commit; no second live file exists.");
+          }
+        }
+      }
+      return inspected.summary.ready ? 0 : 1;
+    }
+    if (operation === "catalog") {
+      const software = SOFTWARE_CATALOG.filter((entry) => entry.status === "active" || options.deployChannel === "development" && entry.status === "testing");
+      const payload = {
+        channel: options.deployChannel,
+        note: "Only active coordinates are selectable in deploy definitions.",
+        os: OS_CATALOG,
+        software
+      };
+      if (options.json)
+        out.line(JSON.stringify(payload, null, 2));
+      else {
+        out.line(`${options.deployChannel} software catalog (only active coordinates are selectable):`);
+        for (const entry of software) {
+          out.step(`${entry.id}@${entry.version} \xB7 ${entry.os} ${entry.osVersion} ${entry.architecture} \xB7 ${entry.status}`);
+        }
+      }
+      return 0;
+    }
+    out.fail("Usage: fz deploy init|check|sync|catalog [--root <path>] [--channel production|development]");
+    return 2;
+  } catch (cause) {
+    out.fail(cause instanceof Error ? cause.message : String(cause));
+    return 1;
+  }
+}
 function usage() {
   out.line(`
   fz ${VERSION2} \u2014 ForgeZero control surface
@@ -9712,6 +10401,13 @@ function usage() {
     fz agent install        Install the node agent as a systemd service, so
                             applications on this box read secrets through a
                             local socket instead of holding an API key
+    fz project init         Create vendor-neutral, Git-persisted AI context
+    fz project sync         Regenerate Claude/Codex/Gemini/Copilot/Cursor adapters
+    fz project check        Fail when truth sources or generated adapters drift
+    fz deploy init          Create a typed, fail-safe .fz/deploy.json
+    fz deploy check         Validate commands, profiles and software coordinates
+    fz deploy sync          Prove readiness and print the Git synchronization rule
+    fz deploy catalog       List selectable tested OS/software coordinates
 
   CEREMONY OPTIONS
     --key <fp|index>        Which agent key to use for custody
@@ -9734,6 +10430,14 @@ function usage() {
     --apply                 Write the unit rather than printing it (root)
     --enrol                Bind this machine with a one-time token prompted
                            securely by systemd (tenant-owned compute)
+    --root <path>           Project root for project/deploy commands
+    --name <name>           Project or deploy name during init
+    --purpose <text>        Product outcome during project init
+    --profile <name>        Initial deploy profile (default app)
+    --software <key@ver>    Initial tested software coordinate; repeatable
+    --channel <name>        Catalog view: production or development (shows testing)
+    --attestation           Require hardware attestation for every deploy step
+    --force                 Init may replace an existing generated target
 
   CUSTODY FACTORS
     Every custodian share is sealed TWICE and either envelope alone opens it:
@@ -9762,6 +10466,12 @@ async function runCli() {
     case "agent":
       code = await cmdAgent(options, args);
       break;
+    case "project":
+      code = cmdProject(options, args);
+      break;
+    case "deploy":
+      code = cmdDeploy(options, args);
+      break;
     case "genesis":
       code = await cmdGenesis(options);
       break;
@@ -9785,7 +10495,7 @@ async function runCli() {
       usage();
       code = 1;
   }
-  if (args.length > 0 && code === 0 && command !== "agent") {
+  if (args.length > 0 && code === 0 && command !== "agent" && command !== "project" && command !== "deploy") {
     out.warn(`Ignored: ${args.join(" ")}`);
   }
   process.exit(code);