@forgezero/agent 0.1.29 → 0.1.30

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 existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/agent-update.ts
@@ -4886,7 +4886,7 @@ 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.30";
 
 // src/software.ts
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
@@ -5363,7 +5363,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 +9275,261 @@ 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/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 +9545,9 @@ 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(),
+    force: false
   };
   const positional = [];
   for (let index = 0;index < argv.length; index += 1) {
@@ -9309,6 +9566,14 @@ 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 === "--force")
+      options.force = true;
     else if (token === "--key")
       options.key = argv[++index];
     else if (token === "--mode")
@@ -9327,15 +9592,15 @@ function parseOptions(argv) {
   return { command: positional[0] ?? "help", args: positional.slice(1), options };
 }
 var out = {
-  line: (text = "") => process.stdout.write(`${text}
+  line: (text2 = "") => process.stdout.write(`${text2}
 `),
-  step: (text) => process.stdout.write(`  ${text}
+  step: (text2) => process.stdout.write(`  ${text2}
 `),
-  warn: (text) => process.stderr.write(`  ! ${text}
+  warn: (text2) => process.stderr.write(`  ! ${text2}
 `),
-  fail: (text) => process.stderr.write(`  \u2717 ${text}
+  fail: (text2) => process.stderr.write(`  \u2717 ${text2}
 `),
-  ok: (text) => process.stdout.write(`  \u2713 ${text}
+  ok: (text2) => process.stdout.write(`  \u2713 ${text2}
 `)
 };
 var sessionCookie = null;
@@ -9490,7 +9755,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 +9805,17 @@ async function cmdAgent(options, args) {
     return 0;
   }
   try {
-    writeFileSync(plan.unitPath, plan.unit, { mode: 420 });
+    writeFileSync2(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 });
+      mkdirSync2(dirname2(auxiliary.path), { recursive: true, mode: 493 });
+      writeFileSync2(auxiliary.path, auxiliary.unit, { mode: 420 });
       out.ok(`Wrote ${auxiliary.path}`);
     }
     if (options.enrol) {
-      if (existsSync(enrolTokenSourcePath)) {
+      if (existsSync2(enrolTokenSourcePath)) {
         const source = statSync(enrolTokenSourcePath);
-        const token = readFileSync(enrolTokenSourcePath, "utf8").trim();
+        const token = readFileSync2(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 +9828,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}
+        writeFileSync2(enrolTokenSourcePath, `${token}
 `, { mode: 384, flag: "wx" });
       }
     }
@@ -9574,7 +9839,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(`  ${readFileSync2(gitPublicKeyPath, "utf8").trim()}`);
     out.line();
     return 0;
   } catch (cause) {
@@ -9691,6 +9956,43 @@ 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 usage() {
   out.line(`
   fz ${VERSION2} \u2014 ForgeZero control surface
@@ -9712,6 +10014,9 @@ 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
 
   CEREMONY OPTIONS
     --key <fp|index>        Which agent key to use for custody
@@ -9734,6 +10039,10 @@ 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 init/sync/check
+    --name <name>          Project name during init
+    --purpose <text>       Product outcome during init
+    --force                Init may replace existing AI instruction files
 
   CUSTODY FACTORS
     Every custodian share is sealed TWICE and either envelope alone opens it:
@@ -9762,6 +10071,9 @@ async function runCli() {
     case "agent":
       code = await cmdAgent(options, args);
       break;
+    case "project":
+      code = cmdProject(options, args);
+      break;
     case "genesis":
       code = await cmdGenesis(options);
       break;
@@ -9785,7 +10097,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") {
     out.warn(`Ignored: ${args.join(" ")}`);
   }
   process.exit(code);

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;