@kungfu-tech/buildchain 2.11.1 → 2.11.2-alpha.2

package/packages/core/publication-package.js

@@ -0,0 +1,216 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { loadBuildchainConfig } from "./buildchain-config.js";
+
+export const PUBLICATION_NPM_PACKAGE_CONTRACT = "kungfu-buildchain-publication-npm-package";
+
+function toPosix(value) {
+  return String(value || "").split(path.sep).join("/");
+}
+
+function sha256File(filePath) {
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function copyFilePreservingPath({ cwd, outputDir, relPath, copied }) {
+  const source = path.resolve(cwd, relPath);
+  if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+    return undefined;
+  }
+  const normalized = toPosix(relPath);
+  if (copied.has(normalized)) {
+    return copied.get(normalized);
+  }
+  const target = path.join(outputDir, normalized);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+  const fact = {
+    path: normalized,
+    bytes: fs.statSync(target).size,
+    sha256: sha256File(target),
+  };
+  copied.set(normalized, fact);
+  return fact;
+}
+
+function publicationConfig(cwd) {
+  const loaded = loadBuildchainConfig(cwd);
+  if (loaded.config.project?.type !== "publication-artifact") {
+    throw new Error('publication npm package requires project.type = "publication-artifact"');
+  }
+  if (!loaded.config.publication) {
+    throw new Error("publication npm package requires [publication]");
+  }
+  const publish = loaded.config.publish || {};
+  if (publish.kind && publish.kind !== "npm-paper-package") {
+    throw new Error('publication npm package requires publish.kind = "npm-paper-package"');
+  }
+  return { loaded, publication: loaded.config.publication, publish };
+}
+
+export function collectPublicationPackageFacts({
+  cwd = process.cwd(),
+  packageName = "",
+  outputDir = ".buildchain/publication/npm-package",
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const { loaded, publication, publish } = publicationConfig(resolvedCwd);
+  const name = packageName || publish.package || publish.mainPackage || "";
+  if (!name) {
+    throw new Error("publication npm package requires publish.package or --package-name");
+  }
+  const version = publication.version || "";
+  if (!version) {
+    throw new Error("publication npm package requires publication.version");
+  }
+  return {
+    schemaVersion: 1,
+    contract: PUBLICATION_NPM_PACKAGE_CONTRACT,
+    package: {
+      name,
+      version,
+      distTag: publish.distTag || (version.includes("-") ? "alpha" : "latest"),
+      auth: publish.auth || "trusted-publishing",
+    },
+    project: {
+      name: loaded.config.project?.name || path.basename(resolvedCwd),
+      type: loaded.config.project?.type || "",
+    },
+    publication: {
+      kind: publication.kind,
+      title: publication.title,
+      version,
+      primaryArtifact: publication.primaryArtifact,
+      manifestPath: publication.manifestPath,
+      passportPath: ".buildchain/publication/publication-artifact-passport.json",
+      registryPath: publication.archive?.registryPath || "",
+      sourceBundlePath: publication.sourceBundlePath,
+      artifactPaths: [publication.primaryArtifact, ...publication.artifactPaths].filter(Boolean),
+      metadataPaths: publication.metadataPaths,
+      siteConsumers: publication.siteConsumers,
+    },
+    outputDir: toPosix(outputDir),
+  };
+}
+
+export function preparePublicationNpmPackage({
+  cwd = process.cwd(),
+  outputDir = ".buildchain/publication/npm-package",
+  packageName = "",
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const facts = collectPublicationPackageFacts({ cwd: resolvedCwd, outputDir, packageName });
+  const resolvedOutputDir = path.resolve(resolvedCwd, outputDir);
+  fs.rmSync(resolvedOutputDir, { recursive: true, force: true });
+  fs.mkdirSync(resolvedOutputDir, { recursive: true });
+
+  const copied = new Map();
+  const declaredPaths = [
+    facts.publication.manifestPath,
+    facts.publication.passportPath,
+    facts.publication.registryPath,
+    facts.publication.sourceBundlePath,
+    ...facts.publication.artifactPaths,
+    ...facts.publication.metadataPaths,
+  ].filter(Boolean);
+  const files = declaredPaths
+    .map((relPath) => copyFilePreservingPath({
+      cwd: resolvedCwd,
+      outputDir: resolvedOutputDir,
+      relPath,
+      copied,
+    }))
+    .filter(Boolean);
+
+  const manifestFile = path.resolve(resolvedCwd, facts.publication.manifestPath);
+  const passportFile = path.resolve(resolvedCwd, facts.publication.passportPath);
+  if (!fs.existsSync(manifestFile)) {
+    throw new Error(`publication manifest is missing: ${facts.publication.manifestPath}`);
+  }
+  if (!fs.existsSync(passportFile)) {
+    throw new Error(`publication passport is missing: ${facts.publication.passportPath}`);
+  }
+  if (!files.some((file) => file.path === facts.publication.primaryArtifact)) {
+    throw new Error(`publication primary artifact is missing from npm package: ${facts.publication.primaryArtifact}`);
+  }
+
+  const sourcePackage = fs.existsSync(path.join(resolvedCwd, "package.json"))
+    ? readJson(path.join(resolvedCwd, "package.json"))
+    : {};
+  const packageJson = {
+    name: facts.package.name,
+    version: facts.package.version,
+    private: false,
+    description: `${facts.publication.title} publication artifact package.`,
+    license: sourcePackage.license || "UNLICENSED",
+    type: "module",
+    files: [
+      ".buildchain/publication/",
+      "buildchain-publication-package.json",
+      facts.publication.primaryArtifact,
+      ...facts.publication.artifactPaths,
+      ...facts.publication.metadataPaths,
+    ].filter(Boolean),
+    exports: {
+      "./package.json": "./package.json",
+      "./publication-artifact.json": `./${facts.publication.manifestPath}`,
+      "./publication-artifact-passport.json": `./${facts.publication.passportPath}`,
+      ...(facts.publication.registryPath
+        ? { "./publication-registry.json": `./${facts.publication.registryPath}` }
+        : {}),
+    },
+    publishConfig: {
+      access: "public",
+      registry: "https://registry.npmjs.org/",
+    },
+    buildchain: {
+      contract: PUBLICATION_NPM_PACKAGE_CONTRACT,
+      publicationManifest: facts.publication.manifestPath,
+      publicationPassport: facts.publication.passportPath,
+      publicationRegistry: facts.publication.registryPath || undefined,
+      primaryArtifact: facts.publication.primaryArtifact,
+      sourceBundle: facts.publication.sourceBundlePath,
+      siteConsumers: facts.publication.siteConsumers,
+    },
+  };
+  fs.writeFileSync(path.join(resolvedOutputDir, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`);
+  const readme = [
+    `# ${facts.publication.title}`,
+    "",
+    "This npm package was synthesized by Buildchain from a publication-artifact repository.",
+    "",
+    `- Publication manifest: \`${facts.publication.manifestPath}\``,
+    `- Publication passport: \`${facts.publication.passportPath}\``,
+    `- Primary artifact: \`${facts.publication.primaryArtifact}\``,
+    "",
+  ].join("\n");
+  fs.writeFileSync(path.join(resolvedOutputDir, "README.md"), readme);
+
+  const packageManifest = {
+    ...facts,
+    outputDir: toPosix(path.relative(resolvedCwd, resolvedOutputDir)),
+    files: [
+      {
+        path: "package.json",
+        bytes: fs.statSync(path.join(resolvedOutputDir, "package.json")).size,
+        sha256: sha256File(path.join(resolvedOutputDir, "package.json")),
+      },
+      {
+        path: "README.md",
+        bytes: fs.statSync(path.join(resolvedOutputDir, "README.md")).size,
+        sha256: sha256File(path.join(resolvedOutputDir, "README.md")),
+      },
+      ...files,
+    ].sort((left, right) => left.path.localeCompare(right.path)),
+  };
+  fs.writeFileSync(
+    path.join(resolvedOutputDir, "buildchain-publication-package.json"),
+    `${JSON.stringify(packageManifest, null, 2)}\n`,
+  );
+  return packageManifest;
+}

package/scripts/check-inventory.mjs

@@ -20,6 +20,7 @@ const requiredPaths = [
   "bin/buildchain.mjs",
   "packages/core/homebrew.js",
   "packages/core/build-facts.js",
+  "packages/core/publication-package.js",
   "packages/core/release-line-bootstrap.js",
   "packages/core/public-surface-audit.js",
   "docs/MAP.md",
@@ -46,6 +47,7 @@ const requiredPaths = [
   "scripts/artifact-relay-s3.mjs",
   "scripts/npm-publish-dry-run.mjs",
   "scripts/npm-publish-transaction.mjs",
+  "scripts/publication-package.mjs",
   "scripts/release-candidate-resolver.mjs",
   "scripts/buildchain-patrol.mjs",
   "scripts/workflow-friction-report.mjs",
@@ -71,6 +73,7 @@ const requiredPaths = [
   ".github/workflows/release-candidate-promote.yml",
   ".github/workflows/release-propagation.yml",
   ".github/workflows/npm-publish.yml",
+  ".github/workflows/paper-release.yml",
   ".github/workflows/binary-distribution.yml",
   ".github/workflows/verify.yml",
   ".github/workflows/.build.yml",
@@ -298,6 +301,10 @@ if (siteBundle.package?.version !== rootPackage.version) {
 if (siteManifest.package?.version !== rootPackage.version) {
   throw new Error("site-manifest.json package.version must match package.json version");
 }
+const publicationRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/publication-registry.json"), "utf8"));
+if (publicationRegistry.package?.version !== rootPackage.version) {
+  throw new Error("publication-registry.json package.version must match package.json version");
+}
 if (siteBundle.source?.homepageTextSource !== "README.md") {
   throw new Error("buildchain-site.json source.homepageTextSource must be README.md");
 }
@@ -909,7 +916,7 @@ if (!badgeEndpointRegistry.badges?.some((entry) => entry.id === "buildchain-rele
   throw new Error("badge endpoint registry must include Buildchain Release Passport badge");
 }
 
-for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "page-registry.json", "capability-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "public-surface-audit.json", "release-model.json", "buildchain-contract.json"]) {
+for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "publication-registry.json", "page-registry.json", "capability-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "public-surface-audit.json", "release-model.json", "buildchain-contract.json"]) {
   if (!fs.existsSync(path.join(root, "dist", "site", siteFile))) {
     throw new Error(`site bundle missing ${siteFile}`);
   }

package/scripts/generate-site-bundle.mjs

@@ -24,6 +24,7 @@ import {
 import { createSurfaceTimestampPolicy } from "../packages/core/surface-manifest.js";
 
 const SITE_BUNDLE_CONTRACT = "kungfu-buildchain-site-bundle";
+const PUBLICATION_RELEASE_REGISTRY_CONTRACT = "kungfu-buildchain-publication-release-registry";
 const README_PATH = "README.md";
 const root = path.resolve(import.meta.dirname, "..");
 const outputDir = path.join(root, "dist", "site");
@@ -430,6 +431,7 @@ function cliCommandMeta(id) {
     "publish-source": { group: "release-passport-trust", purpose: "Create, inspect, or verify publish-gate source-lock refs." },
     "publication-artifact": { group: "reusable-build", purpose: "Generate publication artifact manifests, passports, and source bundles for paper/report repositories." },
     "publication-artifact-manifest": { group: "reusable-build", purpose: "Write a site-consumable publication artifact manifest, publication passport, and source bundle." },
+    "publication-artifact-npm-package": { group: "reusable-build", purpose: "Synthesize the declared npm paper package from a publication artifact manifest, passport, registry, source bundle, and primary artifact." },
     "release-dry-run": { group: "governance-versioning", purpose: "Explain what a channel merge would publish before the PR is merged." },
     "release-line-open": { group: "governance-versioning", purpose: "Plan or write the initial version-state commit for a new minor release line." },
     "release-propagation": { group: "site-and-propagation", purpose: "Plan channel-preserving downstream release PRs and write exact upstream release locks." },
@@ -465,6 +467,7 @@ function nodeApiMeta(exportName) {
     "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
     "./logging": { group: "observability-diagnostics", summary: "Buildchain JSONL logging, span, summary, and verification APIs." },
     "./publication-artifact": { group: "reusable-build", summary: "Publication artifact manifest, source bundle, and publication passport APIs." },
+    "./publication-package": { group: "reusable-build", summary: "Publication npm package synthesis APIs for Buildchain-managed paper release presets." },
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
@@ -522,6 +525,7 @@ function buildCapabilityRegistry({ docs, pages, cliRegistry, manualRegistry, nod
         "cli-registry.json",
         "node-api-registry.json",
         "workflow-registry.json",
+        "publication-registry.json",
         "kfd-upstream-aggregate.json",
         "kfd-claims.json",
       ],
@@ -535,7 +539,7 @@ function buildCapabilityRegistry({ docs, pages, cliRegistry, manualRegistry, nod
 
 function workflowCapabilityGroup(entry) {
   if (["web-surface", "release-propagation"].includes(entry.id)) return capabilityGroup("site-and-propagation");
-  if (["build", "release-candidate-promote", "publication-artifact"].includes(entry.id)) return capabilityGroup("reusable-build");
+  if (["build", "release-candidate-promote", "publication-artifact", "paper-release"].includes(entry.id)) return capabilityGroup("reusable-build");
   if (["buildchain-ref-promotion", "release-line-bootstrap"].includes(entry.id)) return capabilityGroup("release-passport-trust");
   if (entry.id.includes("patrol") || entry.id.includes("dev-pr-auto-merge")) return capabilityGroup("governance-versioning");
   if (entry.status === "repository-internal" || entry.status === "compatibility-fixture") return capabilityGroup("api-cli-reference");
@@ -574,6 +578,90 @@ function buildSitePages() {
   ].sort((a, b) => a.route.localeCompare(b.route));
 }
 
+function createPublicationReleaseRegistry({ packageJson, timestampPolicy }) {
+  return {
+    schemaVersion: 1,
+    contract: PUBLICATION_RELEASE_REGISTRY_CONTRACT,
+    ...timestampPolicy,
+    package: {
+      name: packageJson.name,
+      version: packageJson.version,
+      versionSource: "package.json#version",
+    },
+    sourceKind: "package-site-bundle",
+    sourceBoundary: {
+      truthOwner: "@kungfu-tech/buildchain",
+      siteRole: "rendering, routing, archive preservation checks, and agent discovery",
+      rule: "Downstream papers sites render this registry; Buildchain owns publication route, latest, immutable artifact, passport, and source bundle facts.",
+    },
+    archivePolicy: {
+      contract: "kungfu-buildchain-publication-archive-policy",
+      mutableRouteKinds: [
+        "canonical-reader",
+        "latest",
+        "registry-index",
+      ],
+      immutableRouteKinds: [
+        "version-artifact",
+        "version-passport",
+        "version-source",
+      ],
+      deploymentBoundary: "append-only immutable version prefixes",
+      rule: "A site build may update latest and canonical reader pages, but it must not delete or overwrite files under a declared immutable version prefix.",
+    },
+    publications: [
+      {
+        id: "publication-archive-fixture",
+        title: "Publication Archive Fixture",
+        summary: "A paper-shaped Buildchain package fact proving that site rendering preserves immutable versioned PDF, source, and passport routes while latest pages can move.",
+        canonicalReader: {
+          kind: "canonical-reader",
+          url: "https://kungfu.tech/whitepaper/",
+          owner: "site-kungfu-tech",
+        },
+        latest: {
+          kind: "latest",
+          version: "0.1.0",
+          path: "/publication-archive-fixture/latest/",
+        },
+        immutablePrefixTemplate: "/publication-archive-fixture/v{version}/",
+        versions: [
+          {
+            version: "0.1.0",
+            releasedAt: "2026-07-09T00:00:00.000Z",
+            immutable: true,
+            immutablePath: "/publication-archive-fixture/v0.1.0/",
+            source: {
+              repository: "https://github.com/kungfu-systems/publication-archive-fixture",
+              tag: "v0.1.0",
+              commit: "0000000000000000000000000000000000000000",
+              bundle: {
+                path: "source.tar.gz",
+                sha256: "sha256:e2ca891dbf441f867ed135b21b3556ee5cdcd3ec80038f267a3ecff496c5a38b",
+                fixtureBodyBase64: "c2l0ZS1saWJrdW5nZnUtZGV2IHB1YmxpY2F0aW9uIGFyY2hpdmUgZml4dHVyZSBzb3VyY2UgYnVuZGxlCnZlcnNpb246IDAuMS4wCg==",
+              },
+            },
+            passport: {
+              path: "publication-artifact-passport.json",
+              sha256: "sha256:ca214e2e17c8d3c01565e507e57d5b440943c762199aa8d9de21995940538cea",
+              fixtureBodyBase64: "ewogICJjb250cmFjdCI6ICJrdW5nZnUtYnVpbGRjaGFpbi1wdWJsaWNhdGlvbi1hcnRpZmFjdC1wYXNzcG9ydCIsCiAgInB1YmxpY2F0aW9uIjogInB1YmxpY2F0aW9uLWFyY2hpdmUtZml4dHVyZSIsCiAgInZlcnNpb24iOiAiMC4xLjAiLAogICJzdGF0dXMiOiAiZml4dHVyZSIKfQo=",
+            },
+            artifacts: [
+              {
+                role: "pdf",
+                path: "main.pdf",
+                mediaType: "application/pdf",
+                sha256: "sha256:c1c2020cbdcf0cc339323d2276480a48d9b8d7da9be1d19ab58a0b3c0b7a4fbb",
+                fixtureBodyBase64: "JVBERi0xLjQKJSBzaXRlLWxpYmt1bmdmdS1kZXYgcHVibGljYXRpb24gYXJjaGl2ZSBmaXh0dXJlCjEgMCBvYmogPDwgL1R5cGUgL0NhdGFsb2cgL1BhZ2VzIDIgMCBSID4+IGVuZG9iagoyIDAgb2JqIDw8IC9UeXBlIC9QYWdlcyAvS2lkcyBbMyAwIFJdIC9Db3VudCAxID4+IGVuZG9iagozIDAgb2JqIDw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMiAwIFIgL01lZGlhQm94IFswIDAgMzAwIDE0NF0gL0NvbnRlbnRzIDQgMCBSID4+IGVuZG9iago0IDAgb2JqIDw8IC9MZW5ndGggNzIgPj4gc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFB1YmxpY2F0aW9uIGFyY2hpdmUgZml4dHVyZSB2MC4xLjApIFRqIEVUCmVuZHN0cmVhbSBlbmRvYmoKeHJlZgowIDUKMDAwMDAwMDAwMCA2NTUzNSBmIAp0cmFpbGVyIDw8IC9Sb290IDEgMCBSIC9TaXplIDUgPj4Kc3RhcnR4cmVmCjM2MAolJUVPRgo=",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
 function buildSiteBundle() {
   const packageJson = readJson("package.json");
   const inventory = readJson("tests/buildchain-inventory.json");
@@ -729,6 +817,7 @@ function buildSiteBundle() {
         ["buildchain-ref-promotion", "release-governance"],
         ["release-line-bootstrap", "release-governance"],
         ["release-candidate-promote", "release-governance"],
+        ["paper-release", "reusable-build"],
         ["release-propagation", "release-propagation"],
         ["dev-pr-auto-merge", "dev-governance"],
         ["binary-distribution", "release-passport"],
@@ -843,6 +932,7 @@ function buildSiteBundle() {
       "buildchain-site.json",
       "site-manifest.json",
       "badge-endpoint-registry.json",
+      "publication-registry.json",
       "page-registry.json",
       "capability-registry.json",
       "cli-registry.json",
@@ -933,6 +1023,7 @@ function buildSiteBundle() {
       "release-model.json",
       "artifact-schemas.json",
       "badge-endpoint-registry.json",
+      "publication-registry.json",
       "product-mechanism.json",
       "release-provenance.json",
       "kfd-upstream-aggregate.json",
@@ -960,12 +1051,14 @@ function buildSiteBundle() {
       "kfd-upstream-aggregate.json",
       "kfd-claims.json",
       "badge-endpoint-registry.json",
+      "publication-registry.json",
     ],
     instruction: "Use this bundle as the package-owned fact source for Buildchain pages. Do not infer current release mechanics from prose alone.",
   };
   const badgeEndpointRegistry = createReadmeBadgeEndpointRegistry({
     kfdStandards: readPackageKfdStandards(),
   });
+  const publicationRegistry = createPublicationReleaseRegistry({ packageJson, timestampPolicy });
 
   const homepageSections = [
     homepageSection({
@@ -1094,6 +1187,7 @@ function buildSiteBundle() {
         "KFD claim registry",
         "KFD upstream aggregate registry",
         "release-passport evidence vocabulary",
+        "publication archive registry and immutable papers surface facts",
       ],
       ownedBySite: [
         "HTML structure",
@@ -1121,6 +1215,7 @@ function buildSiteBundle() {
     "release-model.json": releaseModel,
     "artifact-schemas.json": artifactSchemas,
     "badge-endpoint-registry.json": badgeEndpointRegistry,
+    "publication-registry.json": publicationRegistry,
     "buildchain-contract.json": createBuildchainContractWorld({ root }),
     "kfd-upstream-aggregate.json": collectKfdUpstreamFacts({ cwd: root, includeOwn: false }),
     "kfd-claims.json": createBuildchainKfdClaimRegistry({ root }),

package/scripts/publication-package.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { preparePublicationNpmPackage } from "../packages/core/publication-package.js";
+
+function readFlag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function readBooleanFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+export function runPublicationPackageCli(args = process.argv.slice(2)) {
+  const result = preparePublicationNpmPackage({
+    cwd: readFlag(args, "cwd", process.cwd()),
+    outputDir: readFlag(args, "output-dir", ".buildchain/publication/npm-package"),
+    packageName: readFlag(args, "package-name", ""),
+  });
+  if (readBooleanFlag(args, "json")) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(`publication-package-dir=${result.outputDir}\n`);
+    process.stdout.write(`publication-package-name=${result.package.name}\n`);
+    process.stdout.write(`publication-package-version=${result.package.version}\n`);
+    process.stdout.write(`publication-package-dist-tag=${result.package.distTag}\n`);
+  }
+  return result;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    runPublicationPackageCli();
+  } catch (error) {
+    console.error(`publication-package: ${error.message}`);
+    process.exitCode = 1;
+  }
+}