@kungfu-tech/buildchain 3.0.3-alpha.1 → 3.0.3-alpha.2

package/packages/core/paper.js

@@ -1,12 +1,8 @@
-import { spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import {
-  loadBuildchainConfig,
-  validateBuildchainConfig,
-} from "./buildchain-config.js";
+import { validateBuildchainConfig } from "./buildchain-config.js";
 import {
   createBuildchainContractLock,
   createBuildchainContractWorld,
@@ -22,6 +18,37 @@ import {
   PUBLICATION_SEALED_BUNDLE_CONTRACT,
   verifyPublicationSealedBundle,
 } from "./publication-sealed-bundle.js";
+import {
+  PAPER_PATHS,
+  commandResult,
+  gitResult,
+  gitValue,
+  normalizeRepository,
+  paperConfig,
+  parsePaperVersion,
+  readJson,
+  resolvePaperRepository,
+  sha256Text,
+  stableJson,
+} from "./paper-repository.js";
+
+export { PAPER_PATHS, resolvePaperRepository } from "./paper-repository.js";
+export {
+  PAPER_WORK_START_PLAN_CONTRACT,
+  PAPER_WORK_SUBMIT_PLAN_CONTRACT,
+  createPaperWorkStartPlan,
+  createPaperWorkSubmitPlan,
+  executePaperWorkStart,
+  executePaperWorkSubmitPush,
+} from "./paper-work.js";
+export {
+  PAPER_FLEET_AUDIT_CONTRACT,
+  PAPER_FLEET_UPDATE_PLAN_CONTRACT,
+  collectPaperFleetAudit,
+  discoverPaperFleet,
+  planPaperFleetUpdate,
+  writePaperFleetUpdate,
+} from "./paper-fleet.js";
 
 export const PAPER_SCAFFOLD_CONTRACT = "kungfu-buildchain-paper-scaffold";
 export const PAPER_MIGRATION_CONTRACT = "kungfu-buildchain-paper-migration";
@@ -50,22 +77,6 @@ export const PAPER_STATE_ORDER = Object.freeze([
   "production-visible",
 ]);
 
-export const PAPER_PATHS = Object.freeze({
-  config: ".buildchain/buildchain.toml",
-  versionPin: ".buildchain-version",
-  contractLock: ".buildchain/contract-lock.json",
-  buildWorkflow: ".github/workflows/build.yml",
-  releaseWorkflow: ".github/workflows/paper-release.yml",
-  reproducibilityReceipt:
-    ".buildchain/publication/reproducibility-receipt.json",
-  sealedBundle: ".buildchain/admitted/sealed-bundle.json",
-  admission: ".buildchain/admitted/publication-admission.json",
-  capability: ".buildchain/admitted/publication-capability.json",
-  npmBootstrap: ".buildchain/paper/npm-bootstrap.json",
-  npmTrust: ".buildchain/paper/npm-trust.json",
-  provisioningAuthority: ".buildchain/paper/provisioning-authority.json",
-  visibility: ".buildchain/paper/visibility.json",
-});
 const PAPER_SCAFFOLD_PATHS = Object.freeze([
   PAPER_PATHS.config,
   PAPER_PATHS.contractLock,
@@ -100,23 +111,6 @@ function toPosix(value) {
     .join("/");
 }
 
-function stableJson(value) {
-  if (Array.isArray(value)) {
-    return `[${value.map(stableJson).join(",")}]`;
-  }
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value)
-      .sort()
-      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
-      .join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-function sha256Text(value) {
-  return `sha256:${crypto.createHash("sha256").update(String(value)).digest("hex")}`;
-}
-
 function sha256File(filePath) {
   return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
 }
@@ -125,21 +119,6 @@ function jsonText(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
-function readJson(filePath) {
-  if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
-    return { exists: false, value: undefined, error: "" };
-  }
-  try {
-    return {
-      exists: true,
-      value: JSON.parse(fs.readFileSync(filePath, "utf8")),
-      error: "",
-    };
-  } catch (error) {
-    return { exists: true, value: undefined, error: error.message };
-  }
-}
-
 function existingFileFact(cwd, relativePath) {
   const filePath = path.resolve(cwd, relativePath);
   if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
@@ -160,51 +139,6 @@ function normalizePackageName(value, label = "package name") {
   return normalized;
 }
 
-function normalizeRepository(value) {
-  const normalized = String(value || "")
-    .trim()
-    .replace(/^git\+/, "")
-    .replace(/^git@github\.com:/, "")
-    .replace(/^ssh:\/\/git@github\.com\//, "")
-    .replace(/^https?:\/\/github\.com\//, "")
-    .replace(/\.git$/, "")
-    .replace(/^\/+|\/+$/g, "");
-  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(normalized)) {
-    return "";
-  }
-  return normalized;
-}
-
-function commandResult(
-  command,
-  args,
-  { cwd, env = process.env, timeout = 15000 } = {},
-) {
-  const result = spawnSync(command, args, {
-    cwd,
-    env,
-    encoding: "utf8",
-    timeout,
-    maxBuffer: 2 * 1024 * 1024,
-  });
-  return {
-    ok: result.status === 0,
-    status: result.status ?? 1,
-    stdout: String(result.stdout || "").trim(),
-    stderr: String(result.stderr || "").trim(),
-    error: result.error?.message || "",
-  };
-}
-
-function gitResult(cwd, args) {
-  return commandResult("git", args, { cwd });
-}
-
-function gitValue(cwd, args) {
-  const result = gitResult(cwd, args);
-  return result.ok ? result.stdout : "";
-}
-
 function buildchainPackageIdentity(buildchainRoot, explicitVersion = "") {
   const packageJson = readJson(
     path.resolve(buildchainRoot, "package.json"),
@@ -541,16 +475,58 @@ clean:
 `;
 }
 
-function scaffoldPackageJson({ name, packageName, repository }) {
-  return jsonText({
-    name: packageName,
+function paperPackageScripts(current = {}) {
+  return {
+    ...current,
+    "buildchain:paper": "buildchain paper",
+    "paper:preflight": "buildchain paper preflight --json",
+    "paper:work:start": "buildchain paper work start",
+    "paper:work:submit": "buildchain paper work submit",
+    "paper:status": "buildchain paper status --json",
+  };
+}
+
+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,
-    description: `${name} publication source repository.`,
-    repository: {
-      type: "git",
-      url: `git+https://github.com/${repository}.git`,
+    scripts: paperPackageScripts(current.scripts),
+    devDependencies: {
+      ...(current.devDependencies || {}),
+      "@kungfu-tech/buildchain": buildchainVersion,
     },
-    license: "Apache-2.0",
+    packageManager,
+  };
+}
+
+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,
+    ),
   });
 }
 
@@ -562,9 +538,10 @@ This repository is a Buildchain-governed publication artifact source.
 ## Local workflow
 
 \`\`\`sh
-buildchain paper preflight --json
-buildchain paper build
-buildchain paper status --json
+pnpm paper:preflight
+pnpm paper:work:start -- <topic>
+pnpm paper:work:submit
+make pdf
 \`\`\`
 
 The public package identity is \`${packageName}\`. Buildchain owns reproducible
@@ -644,8 +621,13 @@ function scaffoldFiles({
     acceptedAt,
   });
   const contractLockText = jsonText(contractLock);
-  const buildWorkflow = scaffoldBuildWorkflow(buildchainSha);
-  const releaseWorkflow = scaffoldReleaseWorkflow(buildchainSha);
+  const buildWorkflow = scaffoldBuildWorkflow(buildchainSha, {
+    artifactName: name,
+  });
+  const releaseWorkflow = scaffoldReleaseWorkflow(buildchainSha, {
+    artifactPaths: "_build/main.pdf",
+    releasePassportProductName: title,
+  });
   const provisioningAuthority = createPaperProvisioningAuthority({
     repository,
     packageName,
@@ -673,7 +655,15 @@ function scaffoldFiles({
     [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
     ["Makefile", scaffoldMakefile()],
-    ["package.json", scaffoldPackageJson({ name, packageName, repository })],
+    [
+      "package.json",
+      scaffoldPackageJson({
+        name,
+        packageName,
+        repository,
+        buildchainVersion,
+      }),
+    ],
     ["README.md", scaffoldReadme({ title, packageName })],
     ["docs/MAP.md", scaffoldMap()],
     ["paper/main.tex", scaffoldMainTex(title)],
@@ -953,12 +943,21 @@ function migrationFiles({
     buildWorkflow,
     releaseWorkflow,
   });
+  const currentPackage = readJson(path.resolve(cwd, "package.json"));
+  if (!currentPackage.exists || currentPackage.error || !currentPackage.value) {
+    throw new Error("paper migration requires a valid package.json");
+  }
+  const packageJson = managedPaperPackageJson(
+    currentPackage.value,
+    runtimeIdentity.version,
+  );
   return new Map([
     [PAPER_PATHS.contractLock, contractLockText],
     [PAPER_PATHS.versionPin, `${runtimeIdentity.version}\n`],
     [PAPER_PATHS.buildWorkflow, buildWorkflow],
     [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
     [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
+    ["package.json", jsonText(packageJson)],
   ]);
 }
 
@@ -1063,6 +1062,12 @@ export function planPaperMigration({
               description:
                 "Write the reviewed Buildchain-owned control files without changing paper content or publication configuration.",
             },
+            {
+              id: "refresh-pnpm-lock",
+              command: "pnpm install --lockfile-only",
+              description:
+                "Bind the exact Buildchain v3 dependency into pnpm-lock.yaml after the reviewed package update.",
+            },
           ],
   };
   Object.defineProperty(result, "_plannedFiles", {
@@ -1133,26 +1138,6 @@ export function writePaperMigration(plan) {
   };
 }
 
-function paperConfig(cwd) {
-  const loaded = loadBuildchainConfig(cwd);
-  if (!loaded) {
-    return {
-      loaded: undefined,
-      error: `${PAPER_PATHS.config} is missing`,
-    };
-  }
-  if (loaded.config.project?.type !== "publication-artifact") {
-    return {
-      loaded,
-      error: 'project.type must be "publication-artifact"',
-    };
-  }
-  if (!loaded.config.publication) {
-    return { loaded, error: "[publication] is missing" };
-  }
-  return { loaded, error: "" };
-}
-
 function state(id, status, reason, evidence = []) {
   return {
     id,
@@ -1591,20 +1576,6 @@ export function collectPaperStatus({ cwd = process.cwd() } = {}) {
   };
 }
 
-export function resolvePaperRepository(cwd = process.cwd()) {
-  const packagePath = path.resolve(cwd, "package.json");
-  const sourcePackage = readJson(packagePath).value;
-  const configured =
-    typeof sourcePackage?.repository === "string"
-      ? sourcePackage.repository
-      : sourcePackage?.repository?.url;
-  const fromPackage = normalizeRepository(configured);
-  if (fromPackage) return fromPackage;
-  return normalizeRepository(
-    gitValue(cwd, ["config", "--get", "remote.origin.url"]),
-  );
-}
-
 function validatePaperProvisioningAuthority(cwd) {
   const authorityPath = path.resolve(cwd, PAPER_PATHS.provisioningAuthority);
   const source = readJson(authorityPath);
@@ -2527,23 +2498,6 @@ export function createPaperBuildPlan({
   };
 }
 
-function parsePaperVersion(version) {
-  const normalized = String(version || "")
-    .trim()
-    .replace(/^v/, "");
-  const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
-  if (!match) {
-    throw new Error("publication.version must be semver before planning Alpha");
-  }
-  return {
-    version: normalized,
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    prerelease: match[4] || "",
-  };
-}
-
 function resolvePaperChannelRef(cwd, ref) {
   const candidates = [
     {

package/packages/core/public-surface-audit.js

@@ -1,6 +1,12 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import {
+  commandId,
+  enumerateCliCommandsFromBin,
+} from "./public-surface-cli.js";
+
+export { enumerateCliCommandsFromBin } from "./public-surface-cli.js";
 
 export const BUILDCHAIN_PUBLIC_SURFACE_AUDIT_CONTRACT = "kungfu-buildchain-public-surface-reverse-audit";
 
@@ -40,82 +46,6 @@ function listDirectories(root, dir) {
     .sort();
 }
 
-function commandId(first = "", second = "", third = "") {
-  const head = String(first || "").trim();
-  const sub = String(second || "").trim();
-  const leaf = String(third || "").trim();
-  const normalizedLeaf = leaf === "..." ? "" : leaf;
-  if (!head) return "";
-  if (["-h", "--help", "help"].includes(head)) return "help";
-  if (["-v", "--version", "version"].includes(head)) return "version";
-  if (head === "release" && ["--dry-run", "dry-run", "explain"].includes(sub)) return "release-dry-run";
-  if (head === "release" && sub === "line") return "release-line-open";
-  if (head === "release") return "release-transaction";
-  if (head === "transaction") return "transaction-inspect";
-  if (head === "collect" && sub) return `collect-${sub}`;
-  if (head === "verify" && sub) return `verify-${sub}`;
-  if (head === "explain" && sub) return `explain-${sub}`;
-  if (head === "inspect" && sub) return `inspect-${sub}`;
-  if (head === "npm" && sub) return `npm-${sub}`;
-  if (head === "lifecycle" && sub) return "lifecycle";
-  if (head === "log" && sub) return "logging";
-  if (head === "diagnostics" && sub) return `diagnostics-${sub}`;
-  if (head === "facts" && sub) return "build-facts";
-  if (head === "kfd") {
-    if (!sub || sub === "...") return "kfd";
-    if (sub === "schema") return normalizedLeaf ? `kfd-schema-${normalizedLeaf}` : "kfd-schema";
-    if (sub === "upstream") return normalizedLeaf ? `kfd-upstream-${normalizedLeaf}` : "kfd-upstream";
-    if (/^[1-9][0-9]*$/.test(sub)) return normalizedLeaf ? `kfd-${sub}-${normalizedLeaf}` : `kfd-${sub}`;
-    return `kfd-${sub}`;
-  }
-  if (head === "sample" && sub) return `sample-${sub}`;
-  if (head === "badges" && sub) return `badges-${sub}`;
-  if (head === "homebrew" && sub) return `homebrew-${sub}`;
-  if (head === "release-propagation") return "release-propagation";
-  if (head === "publish-source") return "publish-source";
-  if (head === "publication-artifact" && sub) return `publication-artifact-${sub}`;
-  if (head === "publication-artifact") return "publication-artifact";
-  if (head === "publication" && sub) return `publication-artifact-${sub}`;
-  if (head === "publication") return "publication-artifact";
-  if (head === "paper" && sub === "bootstrap" && normalizedLeaf === "npm") return "paper-bootstrap-npm";
-  if (head === "paper" && sub) return `paper-${sub}`;
-  if (head === "paper") return "paper";
-  if (head === "build-contract") return "build-contract";
-  if (head === "infra-contract") return "infra-contract";
-  if (head === "web-surface") return "web-surface";
-  return head;
-}
-
-export function enumerateCliCommandsFromBin({ root = process.cwd(), binPath = "bin/buildchain.mjs" } = {}) {
-  const source = readText(root, binPath);
-  const dispatchSource = [
-    source,
-    ...listFiles(root, "bin/internal", (name) => name.endsWith(".mjs"))
-      .map((relPath) => readText(root, relPath)),
-  ].join("\n");
-  const usageMatch = source.match(/return `Usage:\n([\s\S]*?)`;\n}/);
-  const usage = usageMatch?.[1] || "";
-  const usageCommands = [];
-  for (const line of usage.split(/\r?\n/)) {
-    const match = line.trim().match(/^buildchain\s+([^\s]+)(?:\s+([^\s]+))?(?:\s+([^\s]+))?/);
-    if (!match) continue;
-    usageCommands.push({
-      id: commandId(match[1], match[2], match[3]),
-      usage: line.trim().replace(/\s+/g, " "),
-    });
-  }
-  const dispatchCommands = [...dispatchSource.matchAll(/if\s*\(\s*command\s*===\s*"([^"]+)"/g)]
-    .map((match) => commandId(match[1]));
-  return uniqueSorted([
-    ...usageCommands.map((entry) => entry.id),
-    ...dispatchCommands,
-  ]).map((id) => ({
-    id,
-    source: "bin/buildchain.mjs",
-    usage: usageCommands.find((entry) => entry.id === id)?.usage || `buildchain ${id}`,
-  }));
-}
-
 function parseYamlWorkflowCall(text) {
   const lines = text.split(/\r?\n/);
   const result = { reusable: false, inputs: [], secrets: [], outputs: [] };
@@ -333,8 +263,26 @@ export function collectPublicSurfaceReverseAudit({
       mode: "closed-world-enumerable",
       scope: "Buildchain CLI usage/dispatch, reusable workflow inputs, action inputs, site pages, and documentation command references",
       residualRisk: [
-        "Shell commands delegated through helper scripts are only counted when exposed through bin/buildchain.mjs usage or docs.",
-        "YAML parsing is limited to first-class action/workflow inputs, not arbitrary step environment variables.",
+        {
+          id: "public-surface-helper-command-enumeration",
+          definedBy: "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk",
+          riskType: "natural-language-semantic-risk",
+          trustImpact: "downgrade-warning",
+          machineProvability: "not-machine-verifiable",
+          agentAction: "semantic-review-required",
+          owner: "Buildchain maintainers",
+          reason: "Shell commands delegated through helper scripts are counted only when exposed through bin/buildchain.mjs usage or documentation.",
+        },
+        {
+          id: "public-surface-yaml-enumeration",
+          definedBy: "https://kfd.libkungfu.dev/schemas/kfd-2/trust-taxonomy.schema.json#/$defs/residualRisk",
+          riskType: "natural-language-semantic-risk",
+          trustImpact: "downgrade-warning",
+          machineProvability: "not-machine-verifiable",
+          agentAction: "semantic-review-required",
+          owner: "Buildchain maintainers",
+          reason: "YAML enumeration covers first-class action and workflow inputs, not arbitrary step environment variables.",
+        },
       ],
     },
   };

package/packages/core/public-surface-cli.js

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function readText(root, relPath) {
+  return fs.readFileSync(path.join(root, relPath), "utf8");
+}
+
+function listFiles(root, dir, predicate = () => true) {
+  const base = path.join(root, dir);
+  if (!fs.existsSync(base)) return [];
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && predicate(entry.name))
+    .map((entry) => `${dir}/${entry.name}`)
+    .sort();
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function releaseCommandId(sub) {
+  if (["--dry-run", "dry-run", "explain"].includes(sub))
+    return "release-dry-run";
+  if (sub === "line") return "release-line-open";
+  return "release-transaction";
+}
+
+function kfdCommandId(sub, leaf) {
+  if (!sub || sub === "...") return "kfd";
+  if (["schema", "upstream"].includes(sub) || /^[1-9][0-9]*$/.test(sub)) {
+    return leaf ? `kfd-${sub}-${leaf}` : `kfd-${sub}`;
+  }
+  return `kfd-${sub}`;
+}
+
+function paperCommandId(sub, leaf) {
+  if (sub === "bootstrap" && leaf === "npm") return "paper-bootstrap-npm";
+  if (["work", "fleet"].includes(sub) && leaf) return `paper-${sub}-${leaf}`;
+  return sub ? `paper-${sub}` : "paper";
+}
+
+export function commandId(first = "", second = "", third = "") {
+  const head = String(first || "").trim();
+  const sub = String(second || "").trim();
+  const leaf =
+    String(third || "").trim() === "..." ? "" : String(third || "").trim();
+  const paired = new Set([
+    "collect",
+    "verify",
+    "explain",
+    "inspect",
+    "npm",
+    "diagnostics",
+    "sample",
+    "badges",
+    "homebrew",
+  ]);
+  if (!head) return "";
+  if (["-h", "--help", "help"].includes(head)) return "help";
+  if (["-v", "--version", "version"].includes(head)) return "version";
+  if (head === "release") return releaseCommandId(sub);
+  if (head === "transaction") return "transaction-inspect";
+  if (paired.has(head) && sub) return `${head}-${sub}`;
+  if (head === "lifecycle" && sub) return "lifecycle";
+  if (head === "log" && sub) return "logging";
+  if (head === "facts" && sub) return "build-facts";
+  if (head === "kfd") return kfdCommandId(sub, leaf);
+  if (["release-propagation", "publish-source"].includes(head)) return head;
+  if (["publication-artifact", "publication"].includes(head)) {
+    return sub ? `publication-artifact-${sub}` : "publication-artifact";
+  }
+  if (head === "paper") return paperCommandId(sub, leaf);
+  return head;
+}
+
+function usageCommands(source) {
+  const usageMatch = source.match(/`Usage:\n([\s\S]*?)`;/);
+  const rows = [];
+  for (const line of (usageMatch?.[1] || "").split(/\r?\n/)) {
+    const match = line
+      .trim()
+      .match(/^buildchain\s+([^\s]+)(?:\s+([^\s]+))?(?:\s+([^\s]+))?/);
+    if (!match) continue;
+    rows.push({
+      id: commandId(match[1], match[2], match[3]),
+      usage: line.trim().replace(/\s+/g, " "),
+    });
+  }
+  return rows;
+}
+
+export function enumerateCliCommandsFromBin({
+  root = process.cwd(),
+  binPath = "bin/buildchain.mjs",
+} = {}) {
+  const binSource = readText(root, binPath);
+  const helpSource = readText(root, "scripts/buildchain-cli-help.mjs");
+  const dispatchSource = [
+    binSource,
+    ...listFiles(root, "bin/internal", (name) => name.endsWith(".mjs")).map(
+      (relPath) => readText(root, relPath),
+    ),
+  ].join("\n");
+  const usage = usageCommands(helpSource);
+  const dispatch = [
+    ...dispatchSource.matchAll(/if\s*\(\s*command\s*===\s*"([^"]+)"/g),
+  ].map((match) => commandId(match[1]));
+  return uniqueSorted([...usage.map((entry) => entry.id), ...dispatch]).map(
+    (id) => ({
+      id,
+      source: "bin/buildchain.mjs",
+      usage:
+        usage.find((entry) => entry.id === id)?.usage || `buildchain ${id}`,
+    }),
+  );
+}