@kungfu-tech/buildchain 2.11.2-alpha.1 → 2.11.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",

package/scripts/generate-site-bundle.mjs

@@ -431,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." },
@@ -466,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." },
@@ -537,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");
@@ -815,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"],

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;
+  }
+}