@kungfu-tech/buildchain 3.0.3 → 3.0.4-alpha.0

package/packages/core/paper-agent-entry.js

@@ -0,0 +1,361 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  PAPER_PATHS,
+  PAPER_WORK_BRANCH_PATTERN,
+  gitResult,
+  gitValue,
+  paperDevelopmentRef,
+  readJson,
+  sha256Text,
+  stableJson,
+  workCheck,
+} from "./paper-repository.js";
+
+export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
+export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
+export const PAPER_AGENT_ENTRY_SECTION_START =
+  "<!-- buildchain:paper-agent-entry:v1:start -->";
+export const PAPER_AGENT_ENTRY_SECTION_END =
+  "<!-- buildchain:paper-agent-entry:v1:end -->";
+
+const EXACT_PAPER_SCRIPTS = Object.freeze({
+  "paper:agent:verify": "buildchain paper agent verify --json",
+  "paper:work:start": "buildchain paper work start",
+  "paper:work:submit": "buildchain paper work submit",
+});
+
+const GIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/i;
+
+function jsonText(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+export function paperAgentEntryInstructions({ developmentRef }) {
+  return `${PAPER_AGENT_ENTRY_SECTION_START}
+## Paper work entry (required)
+
+This repository uses the Buildchain-managed Paper path. Before changing any
+tracked file, inspect the current branch and follow the matching rule:
+
+- On \`main\`, \`${developmentRef}\`, or another protected channel, do not edit.
+  Switch to the exact current \`${developmentRef}\`, install the pinned pnpm
+  dependencies when needed, then run
+  \`pnpm paper:work:start -- <topic> --execute --json\`.
+- On an existing \`feature/*\`, \`fix/*\`, \`docs/*\`, \`chore/*\`, \`ci/*\`, or
+  \`refactor/*\` branch, run \`pnpm paper:agent:verify\` before continuing.
+- Before opening or updating a pull request, commit the intended bytes and run
+  \`pnpm paper:work:submit -- --execute --json\`. The target must be
+  \`${developmentRef}\`; direct protected-branch pushes and force pushes are
+  forbidden.
+
+The required remote check independently verifies this contract, the exact
+Buildchain package and runtime authority, and feature-to-development lineage.
+Passing local commands alone is not acceptance, and manually bypassing them
+does not bypass remote policy.
+${PAPER_AGENT_ENTRY_SECTION_END}`;
+}
+
+export function mergePaperAgentEntryInstructions(
+  current = "",
+  { developmentRef },
+) {
+  const source = String(current || "");
+  const section = paperAgentEntryInstructions({ developmentRef });
+  const start = source.indexOf(PAPER_AGENT_ENTRY_SECTION_START);
+  const end = source.indexOf(PAPER_AGENT_ENTRY_SECTION_END);
+  if ((start === -1) !== (end === -1)) {
+    throw new Error(
+      "AGENTS.md has an incomplete Buildchain Paper agent-entry managed section",
+    );
+  }
+  if (start === -1) {
+    return source.trim()
+      ? `${source.trimEnd()}\n\n${section}\n`
+      : `# AGENTS.md\n\n${section}\n`;
+  }
+  if (
+    source.indexOf(PAPER_AGENT_ENTRY_SECTION_START, start + 1) !== -1 ||
+    source.indexOf(PAPER_AGENT_ENTRY_SECTION_END, end + 1) !== -1 ||
+    end < start
+  ) {
+    throw new Error(
+      "AGENTS.md has ambiguous Buildchain Paper agent-entry managed sections",
+    );
+  }
+  return `${source.slice(0, start)}${section}${source.slice(
+    end + PAPER_AGENT_ENTRY_SECTION_END.length,
+  )}`;
+}
+
+export function createPaperAgentEntry({
+  buildchainVersion,
+  buildchainSha,
+  developmentRef,
+}) {
+  const version = String(buildchainVersion || "").trim();
+  const sourceSha = String(buildchainSha || "").trim();
+  if (!/^3\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(
+      "paper agent entry requires an exact Buildchain v3 version",
+    );
+  }
+  if (!GIT_SHA_PATTERN.test(sourceSha)) {
+    throw new Error(
+      "paper agent entry requires an exact Buildchain source SHA",
+    );
+  }
+  if (!/^dev\/v\d+\/v\d+\.\d+$/.test(developmentRef)) {
+    throw new Error("paper agent entry requires an exact development ref");
+  }
+  const payload = {
+    schemaVersion: PAPER_AGENT_ENTRY_SCHEMA_VERSION,
+    contract: PAPER_AGENT_ENTRY_CONTRACT,
+    runtime: {
+      package: "@kungfu-tech/buildchain",
+      version,
+      sourceSha,
+    },
+    repository: {
+      developmentRef,
+      pullRequestTarget: developmentRef,
+    },
+    commands: {
+      verify: "pnpm paper:agent:verify",
+      start: "pnpm paper:work:start -- <topic> --execute --json",
+      submit: "pnpm paper:work:submit -- --execute --json",
+    },
+    policy: {
+      localMutation: "dry-run-first",
+      protectedBranchPatterns: [
+        "main",
+        "dev/**",
+        "alpha/**",
+        "release/**",
+        "publish-gate/**",
+      ],
+      workBranchPattern: PAPER_WORK_BRANCH_PATTERN.source,
+      forcePush: false,
+      remoteAcceptance: "required-buildchain-check",
+    },
+  };
+  return {
+    ...payload,
+    entryDigest: sha256Text(stableJson(payload)),
+  };
+}
+
+export function paperAgentEntryFiles({
+  cwd,
+  buildchainVersion,
+  buildchainSha,
+  developmentRef = "",
+}) {
+  const resolvedDevelopmentRef = developmentRef || paperDevelopmentRef(cwd);
+  const agentsPath = path.resolve(cwd, PAPER_PATHS.agentInstructions);
+  const currentAgents = fs.existsSync(agentsPath)
+    ? fs.readFileSync(agentsPath, "utf8")
+    : "";
+  const entry = createPaperAgentEntry({
+    buildchainVersion,
+    buildchainSha,
+    developmentRef: resolvedDevelopmentRef,
+  });
+  return new Map([
+    [PAPER_PATHS.agentEntry, jsonText(entry)],
+    [
+      PAPER_PATHS.agentInstructions,
+      mergePaperAgentEntryInstructions(currentAgents, {
+        developmentRef: resolvedDevelopmentRef,
+      }),
+    ],
+  ]);
+}
+
+export function resolvePaperBuildchainSha(buildchainRoot, buildchainSha = "") {
+  if (buildchainSha) return buildchainSha;
+  if (!fs.existsSync(path.resolve(buildchainRoot, ".git"))) return "";
+  const observed = gitValue(buildchainRoot, ["rev-parse", "HEAD"]);
+  return GIT_SHA_PATTERN.test(observed) ? observed : "";
+}
+
+function expectedCiBranches(developmentRef) {
+  return [
+    developmentRef,
+    developmentRef.replace(/^dev\//, "alpha/"),
+    developmentRef.replace(/^dev\//, "release/"),
+  ];
+}
+
+function ciContext({ env, developmentRef }) {
+  const event = String(env.GITHUB_EVENT_NAME || "");
+  const sourceBranch = String(
+    env.GITHUB_HEAD_REF || env.BUILDCHAIN_PAPER_SOURCE_BRANCH || "",
+  );
+  const targetBranch = String(
+    env.GITHUB_BASE_REF || env.BUILDCHAIN_PAPER_TARGET_BRANCH || "",
+  );
+  const refName = String(
+    env.GITHUB_REF_NAME || env.BUILDCHAIN_PAPER_REF_NAME || "",
+  );
+  const pullRequest = ["pull_request", "pull_request_target"].includes(event);
+  const branchOk = pullRequest
+    ? PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) &&
+      targetBranch === developmentRef
+    : expectedCiBranches(developmentRef).includes(refName);
+  return {
+    mode: "ci",
+    event,
+    sourceBranch,
+    targetBranch,
+    refName,
+    pullRequest,
+    ok: branchOk,
+    message: pullRequest
+      ? `Pull requests must use an allowed work branch and target ${developmentRef}.`
+      : `Channel checks must run on ${expectedCiBranches(developmentRef).join(", ")}.`,
+  };
+}
+
+function localContext({ cwd, developmentRef }) {
+  const branch = gitValue(cwd, ["branch", "--show-current"]);
+  const developmentSha = gitValue(cwd, [
+    "rev-parse",
+    "--verify",
+    `refs/remotes/origin/${developmentRef}`,
+  ]);
+  const containsDevelopment =
+    PAPER_WORK_BRANCH_PATTERN.test(branch) &&
+    GIT_SHA_PATTERN.test(developmentSha) &&
+    gitResult(cwd, ["merge-base", "--is-ancestor", developmentSha, "HEAD"]).ok;
+  return {
+    mode: "local",
+    branch,
+    developmentRef,
+    developmentSha,
+    ok: containsDevelopment,
+    message: PAPER_WORK_BRANCH_PATTERN.test(branch)
+      ? `The work branch must contain origin/${developmentRef}.`
+      : `Run paper work start from the exact ${developmentRef} channel before editing.`,
+  };
+}
+
+export function collectPaperAgentEntry({
+  cwd = process.cwd(),
+  buildchainSha = "",
+  mode = "contract",
+  env = process.env,
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const developmentRef = paperDevelopmentRef(resolvedCwd);
+  const source = readJson(path.resolve(resolvedCwd, PAPER_PATHS.agentEntry));
+  const entry = source.value || {};
+  const effectiveBuildchainSha =
+    buildchainSha || String(entry.runtime?.sourceSha || "");
+  const packageJson =
+    readJson(path.resolve(resolvedCwd, "package.json")).value || {};
+  const pinPath = path.resolve(resolvedCwd, PAPER_PATHS.versionPin);
+  const versionPin = fs.existsSync(pinPath)
+    ? fs.readFileSync(pinPath, "utf8").trim()
+    : "";
+  const agentsPath = path.resolve(resolvedCwd, PAPER_PATHS.agentInstructions);
+  const agents = fs.existsSync(agentsPath)
+    ? fs.readFileSync(agentsPath, "utf8")
+    : "";
+  const expectedInstructions = paperAgentEntryInstructions({ developmentRef });
+  const { entryDigest: observedDigest, ...entryPayload } = entry;
+  const checks = [
+    workCheck(
+      "agent-entry.contract",
+      source.exists &&
+        !source.error &&
+        entry.contract === PAPER_AGENT_ENTRY_CONTRACT &&
+        entry.schemaVersion === PAPER_AGENT_ENTRY_SCHEMA_VERSION,
+      "The versioned Paper agent-entry contract exists and parses.",
+      "buildchain paper migrate --write --json",
+    ),
+    workCheck(
+      "agent-entry.digest",
+      SHA256_PATTERN.test(String(observedDigest || "")) &&
+        observedDigest === sha256Text(stableJson(entryPayload)),
+      "The Paper agent-entry contract digest matches its exact payload.",
+      "buildchain paper migrate --write --json",
+    ),
+    workCheck(
+      "agent-entry.instructions",
+      agents.includes(expectedInstructions) &&
+        agents.split(PAPER_AGENT_ENTRY_SECTION_START).length === 2 &&
+        agents.split(PAPER_AGENT_ENTRY_SECTION_END).length === 2,
+      "AGENTS.md contains exactly one current Buildchain-managed Paper entry section.",
+      "buildchain paper migrate --write --json",
+    ),
+    workCheck(
+      "agent-entry.package-version",
+      Boolean(versionPin) &&
+        entry.runtime?.version === versionPin &&
+        packageJson.devDependencies?.["@kungfu-tech/buildchain"] === versionPin,
+      "The agent-entry contract, version pin, and exact Buildchain dependency agree.",
+      "buildchain paper migrate --write --json && pnpm install --lockfile-only",
+    ),
+    workCheck(
+      "agent-entry.runtime-source",
+      GIT_SHA_PATTERN.test(effectiveBuildchainSha) &&
+        entry.runtime?.sourceSha === effectiveBuildchainSha,
+      "The agent-entry contract is bound to the exact executing Buildchain source SHA.",
+      "buildchain paper migrate --write --json",
+    ),
+    workCheck(
+      "agent-entry.development-ref",
+      entry.repository?.developmentRef === developmentRef &&
+        entry.repository?.pullRequestTarget === developmentRef,
+      `The agent-entry contract targets ${developmentRef}.`,
+      "buildchain paper migrate --write --json",
+    ),
+    ...Object.entries(EXACT_PAPER_SCRIPTS).map(([name, command]) =>
+      workCheck(
+        `agent-entry.script.${name}`,
+        packageJson.scripts?.[name] === command,
+        `package.json exposes the exact ${name} command.`,
+        "buildchain paper migrate --write --json",
+      ),
+    ),
+  ];
+  const context =
+    mode === "ci"
+      ? ciContext({ env, developmentRef })
+      : mode === "local"
+        ? localContext({ cwd: resolvedCwd, developmentRef })
+        : { mode: "contract", ok: true };
+  if (mode !== "contract") {
+    checks.push(
+      workCheck(
+        "agent-entry.work-context",
+        context.ok,
+        context.message,
+        mode === "ci"
+          ? "retarget the pull request to the configured development channel"
+          : `pnpm paper:work:start -- <topic> --execute --json`,
+      ),
+    );
+  }
+  const ok = checks.every((entryCheck) => entryCheck.status === "pass");
+  return {
+    schemaVersion: 1,
+    contract: PAPER_AGENT_ENTRY_CONTRACT,
+    ok,
+    cwd: resolvedCwd,
+    mode,
+    entry,
+    context,
+    checks,
+    nextActions: checks
+      .filter((entryCheck) => entryCheck.status === "fail")
+      .map((entryCheck) => ({
+        id: `repair-${entryCheck.id}`,
+        command: entryCheck.correctiveCommand,
+        description: entryCheck.message,
+      })),
+  };
+}

package/packages/core/paper-repository.js

@@ -6,6 +6,8 @@ import { loadBuildchainConfig } from "./buildchain-config.js";
 
 export const PAPER_PATHS = Object.freeze({
   config: ".buildchain/buildchain.toml",
+  agentEntry: ".buildchain/paper/agent-entry.json",
+  agentInstructions: "AGENTS.md",
   versionPin: ".buildchain-version",
   contractLock: ".buildchain/contract-lock.json",
   buildWorkflow: ".github/workflows/build.yml",

package/packages/core/paper-scaffold-content.js

@@ -0,0 +1,163 @@
+function jsonText(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function texEscape(value) {
+  return String(value || "")
+    .replaceAll("\\", "\\textbackslash{}")
+    .replaceAll("&", "\\&")
+    .replaceAll("%", "\\%")
+    .replaceAll("$", "\\$")
+    .replaceAll("#", "\\#")
+    .replaceAll("_", "\\_")
+    .replaceAll("{", "\\{")
+    .replaceAll("}", "\\}");
+}
+
+export function scaffoldMakefile({ image, digest, command }) {
+  return `.PHONY: check pdf clean
+
+BUILDER_IMAGE := ${image}@${digest}
+SOURCE_DATE_EPOCH ?= 0
+
+check:
+\t@test -f paper/main.tex
+\t@test -f paper/references.bib
+\t@git diff --check
+
+pdf:
+\t@mkdir -p _build
+\tdocker run --rm --network=none \\
+\t\t-e SOURCE_DATE_EPOCH="$(SOURCE_DATE_EPOCH)" \\
+\t\t-e TZ=UTC -e LANG=C.UTF-8 -e LC_ALL=C.UTF-8 -e HOME=/tmp \\
+\t\t-v "$(CURDIR):/workspace" -w /workspace \\
+\t\t"$(BUILDER_IMAGE)" bash -lc '${command}'
+
+clean:
+\trm -rf _build
+`;
+}
+
+export function paperPackageScripts(current = {}) {
+  return {
+    ...current,
+    "buildchain:paper": "buildchain paper",
+    "paper:preflight": "buildchain paper preflight --json",
+    "paper:agent:verify": "buildchain paper agent verify --json",
+    "paper:work:start": "buildchain paper work start",
+    "paper:work:submit": "buildchain paper work submit",
+    "paper:status": "buildchain paper status --json",
+  };
+}
+
+export function managedPaperPackageJson(current, buildchainVersion) {
+  if (!/^3\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(buildchainVersion)) {
+    throw new Error(
+      "paper repositories require an exact Buildchain v3 version",
+    );
+  }
+  const packageManager = current.packageManager || "pnpm@11.7.0";
+  if (!packageManager.startsWith("pnpm@")) {
+    throw new Error("paper repositories require a pnpm packageManager");
+  }
+  return {
+    ...current,
+    private: true,
+    scripts: paperPackageScripts(current.scripts),
+    devDependencies: {
+      ...(current.devDependencies || {}),
+      "@kungfu-tech/buildchain": buildchainVersion,
+    },
+    packageManager,
+  };
+}
+
+export function scaffoldPackageJson({
+  name,
+  packageName,
+  repository,
+  buildchainVersion,
+}) {
+  return jsonText({
+    ...managedPaperPackageJson(
+      {
+        name: packageName,
+        description: `${name} publication source repository.`,
+        repository: {
+          type: "git",
+          url: `git+https://github.com/${repository}.git`,
+        },
+        license: "Apache-2.0",
+      },
+      buildchainVersion,
+    ),
+  });
+}
+
+export function scaffoldReadme({ title, packageName }) {
+  return `# ${title}
+
+This repository is a Buildchain-governed publication artifact source.
+
+## Local workflow
+
+\`\`\`sh
+pnpm paper:preflight
+pnpm paper:agent:verify
+pnpm paper:work:start -- <topic>
+pnpm paper:work:submit
+make pdf
+\`\`\`
+
+The public package identity is \`${packageName}\`. Buildchain owns reproducible
+artifact generation, sealed publication, npm Trusted Publishing, and recovery;
+this repository owns the paper source and review history.
+
+See [docs/MAP.md](docs/MAP.md) for the repository map.
+`;
+}
+
+export function scaffoldMap() {
+  return `# Repository Map
+
+- \`paper/main.tex\`: paper source entrypoint.
+- \`paper/references.bib\`: bibliography source.
+- \`AGENTS.md\`: mandatory managed entry instructions for people and coding agents.
+- \`.buildchain/paper/agent-entry.json\`: versioned, digest-bound local and CI entry policy.
+- \`.buildchain/buildchain.toml\`: publication identity, toolchain, package, and lifecycle contract.
+- \`.buildchain/contract-lock.json\`: accepted Buildchain runtime contract.
+- \`.github/workflows/build.yml\`: thin read-only build and reproducibility caller.
+- \`.github/workflows/verify.yml\`: thin required check that enforces the Paper entry and acceptance policy.
+- \`.github/workflows/paper-release.yml\`: thin protected sealed-release caller.
+
+The repository does not own npm transaction logic, publication authority,
+release-state recovery, or site deployment mechanics. Those remain Buildchain,
+npm/GitHub, and downstream site responsibilities respectively.
+`;
+}
+
+export function scaffoldMainTex(title) {
+  return `\\documentclass[11pt]{article}
+\\usepackage[T1]{fontenc}
+\\usepackage{lmodern}
+\\usepackage{hyperref}
+
+\\title{${texEscape(title)}}
+\\author{}
+\\date{}
+
+\\begin{document}
+\\maketitle
+
+\\begin{abstract}
+Replace this paragraph with the paper abstract.
+\\end{abstract}
+
+\\section{Introduction}
+Replace this section with the reviewed paper content.
+
+\\bibliographystyle{plain}
+\\bibliography{paper/references}
+\\end{document}
+`;
+}

package/packages/core/paper-work.js

@@ -1,11 +1,14 @@
 import path from "node:path";
+import { collectPaperAgentEntry } from "./paper-agent-entry.js";
 import {
+  PAPER_PATHS,
   PAPER_WORK_BRANCH_PATTERN,
   gitResult,
   gitValue,
   normalizedWorkBranch,
   paperDevelopmentRef,
   paperWorkSource,
+  readJson,
   remoteBranchObservation,
   rootedPlan,
   workCheck,
@@ -26,10 +29,20 @@ function failedActions(checks) {
     }));
 }
 
+function agentEntryForWork(cwd, buildchainSha) {
+  const policy = readJson(path.resolve(cwd, PAPER_PATHS.agentEntry)).value;
+  return collectPaperAgentEntry({
+    cwd,
+    buildchainSha: buildchainSha || policy?.runtime?.sourceSha || "",
+    mode: "contract",
+  });
+}
+
 export function createPaperWorkStartPlan({
   cwd = process.cwd(),
   topic = "",
   branch = "",
+  buildchainSha = "",
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const source = paperWorkSource(resolvedCwd);
@@ -56,7 +69,14 @@ export function createPaperWorkStartPlan({
         `${remoteDevelopment.sha}^{commit}`,
       ]).ok
     : false;
+  const agentEntry = agentEntryForWork(resolvedCwd, buildchainSha);
   const checks = [
+    workCheck(
+      "agent-entry.current",
+      agentEntry.ok,
+      "The mandatory Buildchain Paper agent-entry contract is current.",
+      "buildchain paper migrate --write --json",
+    ),
     workCheck(
       "repository.canonical-origin",
       source.canonical,
@@ -121,6 +141,9 @@ export function createPaperWorkStartPlan({
       developmentRef,
       remoteDevelopmentSha: remoteDevelopment.sha,
     },
+    runtime: {
+      sourceSha: buildchainSha || agentEntry.entry?.runtime?.sourceSha || "",
+    },
     target: { branch: targetBranch, startSha: remoteDevelopment.sha },
     checks,
     mutation: {
@@ -155,6 +178,7 @@ export function executePaperWorkStart(plan) {
   const fresh = createPaperWorkStartPlan({
     cwd: plan.cwd,
     branch: plan.target.branch,
+    buildchainSha: plan.runtime?.sourceSha || "",
   });
   if (!fresh.ok || fresh.planRoot !== plan.planRoot) {
     return {
@@ -184,6 +208,7 @@ export function createPaperWorkSubmitPlan({
   cwd = process.cwd(),
   pullRequests = [],
   pullRequestObservation = { ok: true },
+  buildchainSha = "",
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const source = paperWorkSource(resolvedCwd);
@@ -222,7 +247,14 @@ export function createPaperWorkSubmitPlan({
       entry.headRefName === source.branch &&
       entry.baseRefName === developmentRef,
   );
+  const agentEntry = agentEntryForWork(resolvedCwd, buildchainSha);
   const checks = [
+    workCheck(
+      "agent-entry.current",
+      agentEntry.ok,
+      "The mandatory Buildchain Paper agent-entry contract is current.",
+      "buildchain paper migrate --write --json",
+    ),
     workCheck(
       "repository.canonical-origin",
       source.canonical,
@@ -292,6 +324,9 @@ export function createPaperWorkSubmitPlan({
       remoteSha: remoteWork.sha,
     },
     target: { branch: developmentRef, sha: remoteDevelopment.sha },
+    runtime: {
+      sourceSha: buildchainSha || agentEntry.entry?.runtime?.sourceSha || "",
+    },
     pullRequest: matchingPullRequest || null,
     checks,
     mutation: {