@kungfu-tech/buildchain 2.10.9 → 2.10.10

package/packages/core/publication-artifact.js

@@ -0,0 +1,245 @@
+import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { loadBuildchainConfig } from "./buildchain-config.js";
+
+export const PUBLICATION_ARTIFACT_MANIFEST_CONTRACT = "kungfu-buildchain-publication-artifact-manifest";
+export const PUBLICATION_ARTIFACT_PASSPORT_CONTRACT = "kungfu-buildchain-publication-artifact-passport";
+
+function toPosix(value) {
+  return String(value || "").split(path.sep).join("/");
+}
+
+function sha256Buffer(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function sha256FilePath(filePath) {
+  return sha256Buffer(fs.readFileSync(filePath));
+}
+
+function repoRelative(cwd, filePath) {
+  const relative = path.relative(cwd, filePath);
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative)
+    ? toPosix(relative)
+    : toPosix(path.resolve(filePath));
+}
+
+function listFiles(cwd, relPath) {
+  const target = path.resolve(cwd, relPath);
+  if (!fs.existsSync(target)) {
+    return [];
+  }
+  const stat = fs.statSync(target);
+  if (stat.isFile()) {
+    return [target];
+  }
+  if (!stat.isDirectory()) {
+    return [];
+  }
+  return fs
+    .readdirSync(target, { withFileTypes: true })
+    .flatMap((entry) => listFiles(cwd, path.join(repoRelative(cwd, target), entry.name)));
+}
+
+function collectFiles(cwd, paths = []) {
+  const files = new Map();
+  for (const relPath of paths) {
+    for (const filePath of listFiles(cwd, relPath)) {
+      const relative = repoRelative(cwd, filePath);
+      files.set(relative, {
+        path: relative,
+        bytes: fs.statSync(filePath).size,
+        sha256: sha256FilePath(filePath),
+      });
+    }
+  }
+  return [...files.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function gitValue(cwd, args, fallback = "") {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return fallback;
+  }
+}
+
+function createdAt(now = new Date()) {
+  const sourceDateEpoch = process.env.SOURCE_DATE_EPOCH || "";
+  if (/^\d+$/.test(sourceDateEpoch)) {
+    return new Date(Number(sourceDateEpoch) * 1000).toISOString();
+  }
+  return now.toISOString();
+}
+
+export function createPublicationSourceBundle({
+  cwd = process.cwd(),
+  sourcePaths = [],
+  output = ".buildchain/publication/source.tar.gz",
+} = {}) {
+  const outputPath = path.resolve(cwd, output);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const paths = sourcePaths.length > 0 ? sourcePaths : ["."];
+  execFileSync("git", [
+    "archive",
+    "--format=tar.gz",
+    `--output=${outputPath}`,
+    "HEAD",
+    ...paths,
+  ], { cwd, stdio: "pipe" });
+  return {
+    path: toPosix(path.relative(cwd, outputPath)),
+    bytes: fs.statSync(outputPath).size,
+    sha256: sha256FilePath(outputPath),
+  };
+}
+
+export function collectPublicationArtifact({
+  cwd = process.cwd(),
+  sourceSha = "",
+  sourceBundle = true,
+  sourceBundlePath = "",
+  generatedAt = "",
+} = {}) {
+  const loaded = loadBuildchainConfig(cwd);
+  if (!loaded?.config?.publication) {
+    throw new Error("publication artifact manifest requires [publication] in .buildchain/buildchain.toml");
+  }
+  if (loaded.config.project?.type !== "publication-artifact") {
+    throw new Error('publication artifact manifest requires project.type = "publication-artifact"');
+  }
+  const publication = loaded.config.publication;
+  const artifactPaths = [publication.primaryArtifact, ...publication.artifactPaths]
+    .filter(Boolean)
+    .filter((value, index, list) => list.indexOf(value) === index);
+  const artifacts = collectFiles(cwd, artifactPaths);
+  if (!artifacts.find((artifact) => artifact.path === publication.primaryArtifact)) {
+    throw new Error(`publication primary artifact is missing: ${publication.primaryArtifact}`);
+  }
+  const metadata = collectFiles(cwd, publication.metadataPaths);
+  const sourceFiles = collectFiles(cwd, publication.sourcePaths);
+  const bundle = sourceBundle
+    ? createPublicationSourceBundle({
+        cwd,
+        sourcePaths: publication.sourcePaths,
+        output: sourceBundlePath || publication.sourceBundlePath,
+      })
+    : undefined;
+  const resolvedSourceSha = sourceSha || gitValue(cwd, ["rev-parse", "HEAD"]);
+  const sourceTreeSha = gitValue(cwd, ["rev-parse", `${resolvedSourceSha}^{tree}`]);
+  const timestamp = generatedAt || createdAt();
+  const manifest = {
+    schemaVersion: 1,
+    contract: PUBLICATION_ARTIFACT_MANIFEST_CONTRACT,
+    project: {
+      name: loaded.config.project?.name || path.basename(path.resolve(cwd)),
+      type: "publication-artifact",
+    },
+    publication: {
+      kind: publication.kind,
+      title: publication.title,
+      version: publication.version,
+      abstract: publication.abstract,
+      authors: publication.authors,
+      primaryArtifact: publication.primaryArtifact,
+      siteConsumers: publication.siteConsumers,
+    },
+    source: {
+      repository: gitValue(cwd, ["config", "--get", "remote.origin.url"]),
+      sha: resolvedSourceSha,
+      treeSha: sourceTreeSha,
+      sourcePaths: publication.sourcePaths,
+      sourceFiles,
+      sourceBundle: bundle,
+    },
+    artifacts,
+    metadata,
+    generatedAt: timestamp,
+    publishedAt: timestamp,
+    reproducible: true,
+    timestampPolicy: "ci-injected",
+    deterministicInputs: [
+      "publication source paths",
+      "publication metadata paths",
+      "publication primary artifact",
+      "Buildchain publication contract",
+      "source SHA",
+      "source tree SHA",
+    ],
+    timestampPolicyDetails: {
+      contract: "kungfu-buildchain-surface-timestamp-policy",
+      timestampFields: ["generatedAt", "publishedAt"],
+      timestampFieldsParticipateInArtifactDigest: false,
+      artifactDigestScope: "publication artifact digests cover files and source bundle, not manifest timestamps",
+    },
+  };
+  return {
+    manifest,
+    passport: {
+      schemaVersion: 1,
+      contract: PUBLICATION_ARTIFACT_PASSPORT_CONTRACT,
+      status: "passed",
+      manifestDigest: `sha256:${sha256Buffer(Buffer.from(JSON.stringify(manifest, null, 2)))}`,
+      source: manifest.source,
+      artifacts: manifest.artifacts,
+      responsibility: {
+        producer: "publication repository",
+        renderer: "site repository",
+        buildchain: "artifact contract, manifest, source bundle, and evidence generation",
+      },
+      auditBoundary: {
+        machineVerified: [
+          "declared publication artifact files exist",
+          "declared publication metadata files exist",
+          "declared publication source files are hashed",
+          "source bundle digest is recorded",
+        ],
+        outsideBoundary: [
+          "paper scientific claims",
+          "bibliography quality",
+          "human review of publication content",
+        ],
+      },
+      residualRisk: [
+        {
+          riskType: "natural-language-semantic-risk",
+          trustImpact: "downgrade-warning",
+          machineProvability: "not-machine-verifiable",
+          agentAction: "semantic-review-required",
+          note: "Buildchain verifies declared files and hashes; it does not peer-review paper claims.",
+        },
+      ],
+    },
+  };
+}
+
+export function writePublicationArtifact({
+  cwd = process.cwd(),
+  output = "",
+  passportOutput = "",
+  sourceSha = "",
+  sourceBundle = true,
+  sourceBundlePath = "",
+  generatedAt = "",
+} = {}) {
+  const collected = collectPublicationArtifact({
+    cwd,
+    sourceSha,
+    sourceBundle,
+    sourceBundlePath,
+    generatedAt,
+  });
+  const manifestOutput = output || loadBuildchainConfig(cwd).config.publication.manifestPath;
+  const passportPath = passportOutput || ".buildchain/publication/publication-artifact-passport.json";
+  fs.mkdirSync(path.dirname(path.resolve(cwd, manifestOutput)), { recursive: true });
+  fs.mkdirSync(path.dirname(path.resolve(cwd, passportPath)), { recursive: true });
+  fs.writeFileSync(path.resolve(cwd, manifestOutput), `${JSON.stringify(collected.manifest, null, 2)}\n`);
+  fs.writeFileSync(path.resolve(cwd, passportPath), `${JSON.stringify(collected.passport, null, 2)}\n`);
+  return {
+    ...collected,
+    manifestPath: toPosix(manifestOutput),
+    passportPath: toPosix(passportPath),
+  };
+}

package/scripts/generate-site-bundle.mjs

@@ -325,6 +325,7 @@ const manualMetaById = new Map(Object.entries({
   "site-bundle-contract": { capabilityGroup: "site-and-propagation", audience: ["site", "agent"], maturity: "stable", order: 400 },
   "web-surface-deployments": { capabilityGroup: "site-and-propagation", audience: ["site", "release-operator"], maturity: "stable", order: 410 },
   "release-propagation": { capabilityGroup: "site-and-propagation", audience: ["release-operator", "agent"], maturity: "preview", order: 420 },
+  "publication-artifacts": { capabilityGroup: "reusable-build", audience: ["consumer", "site", "agent"], maturity: "stable", order: 430 },
   "readme-badges": { capabilityGroup: "distribution-indexes", audience: ["consumer", "site"], maturity: "stable", order: 500 },
   homebrew: { capabilityGroup: "distribution-indexes", audience: ["consumer", "release-operator"], maturity: "stable", order: 510 },
   "build-facts": { capabilityGroup: "observability-diagnostics", audience: ["maintainer", "agent"], maturity: "stable", order: 600 },
@@ -427,6 +428,8 @@ function cliCommandMeta(id) {
     npm: { group: "release-passport-trust", purpose: "Inspect npm publishing command families." },
     "npm-dry-run": { group: "release-passport-trust", purpose: "Verify npm publish shape before a release transaction." },
     "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." },
     "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." },
@@ -461,6 +464,7 @@ function nodeApiMeta(exportName) {
     "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
     "./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." },
     "./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." },
@@ -531,7 +535,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"].includes(entry.id)) return capabilityGroup("reusable-build");
+  if (["build", "release-candidate-promote", "publication-artifact"].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");

package/scripts/init-repo.mjs

@@ -239,6 +239,33 @@ command = "buildchain infra-contract --mode ci"
 `;
 }
 
+function publicationArtifactToml(cwd) {
+  const name = repoName(cwd);
+  return `schema = 1
+
+[project]
+type = "publication-artifact"
+name = "${name}"
+
+[publication]
+kind = "paper"
+title = "${name}"
+primary_artifact = "_build/main.pdf"
+artifact_paths = ["_build/main.pdf"]
+metadata_paths = ["README.md", "docs/MAP.md"]
+source_paths = ["paper", "README.md", "LICENSE", "Makefile"]
+site_consumers = ["papers-site"]
+manifest_path = ".buildchain/publication/publication-artifact.json"
+source_bundle_path = ".buildchain/publication/source.tar.gz"
+
+[lifecycle.build]
+command = "make pdf"
+
+[lifecycle.verify]
+command = "make check"
+`;
+}
+
 function infraContractDesiredJson(cwd) {
   return `${JSON.stringify({
     service: repoName(cwd),
@@ -280,10 +307,48 @@ function workflowArtifactPaths(type) {
         .buildchain/infra-contract-evidence-bundle.json
         .buildchain/infra-contract-evidence-verification.json`;
   }
+  if (type === "publication-artifact") {
+    return `_build/main.pdf
+        .buildchain/publication/publication-artifact.json
+        .buildchain/publication/publication-artifact-passport.json
+        .buildchain/publication/source.tar.gz`;
+  }
   return `dist
         build/stage`;
 }
 
+function publicationWorkflowYaml() {
+  return `name: Build
+
+on:
+  workflow_dispatch:
+    inputs:
+      buildchain-ref:
+        description: "Temporary Buildchain runtime ref for trusted manual validation"
+        required: false
+        default: ""
+  pull_request:
+  push:
+    branches:
+      - "dev/**"
+      - "alpha/**"
+      - "release/**"
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  publication:
+    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2
+    with:
+      buildchain-ref: \${{ inputs.buildchain-ref || '' }}
+      build-command: make pdf
+      verify-command: make check
+      artifact-name: publication-artifact
+`;
+}
+
 function workflowYaml({ type, runnerPreset, artifactName }) {
   return `name: Build
 
@@ -350,19 +415,28 @@ export function initBuildchainRepo({
     if (type === "infra-contract") {
       return infraContractToml(resolvedCwd);
     }
+    if (type === "publication-artifact") {
+      return publicationArtifactToml(resolvedCwd);
+    }
     if (type === "anchored-package") {
       return anchoredPackageToml(resolvedCwd, manager);
     }
-    throw new Error("init --type must be one of package, native, web-surface, infra-contract, or anchored-package");
+    throw new Error("init --type must be one of package, native, web-surface, infra-contract, publication-artifact, or anchored-package");
   })();
 
   const written = [
     writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, { force }),
-    writeIfAllowed(path.join(resolvedCwd, ".github", "workflows", "build.yml"), workflowYaml({
-      type,
-      runnerPreset,
-      artifactName,
-    }), { force }),
+    writeIfAllowed(
+      path.join(resolvedCwd, ".github", "workflows", "build.yml"),
+      type === "publication-artifact"
+        ? publicationWorkflowYaml()
+        : workflowYaml({
+            type,
+            runnerPreset,
+            artifactName,
+          }),
+      { force },
+    ),
   ];
 
   if (type === "anchored-package" && !fs.existsSync(path.join(resolvedCwd, "release.json"))) {

package/scripts/publication-artifact.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { writePublicationArtifact } from "../packages/core/publication-artifact.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 runPublicationArtifactCli(args = process.argv.slice(2)) {
+  const [mode = "manifest"] = args;
+  if (!["manifest", "collect"].includes(mode)) {
+    throw new Error("usage: buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--passport-output <file>] [--source-bundle <file>] [--no-source-bundle] [--json]");
+  }
+  const result = writePublicationArtifact({
+    cwd: readFlag(args, "cwd", process.cwd()),
+    output: readFlag(args, "output", ""),
+    passportOutput: readFlag(args, "passport-output", ""),
+    sourceSha: readFlag(args, "source-sha", ""),
+    sourceBundlePath: readFlag(args, "source-bundle", ""),
+    sourceBundle: !readBooleanFlag(args, "no-source-bundle"),
+    generatedAt: readFlag(args, "generated-at", ""),
+  });
+  if (readBooleanFlag(args, "json")) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(`publication-manifest=${result.manifestPath}\n`);
+    process.stdout.write(`publication-passport=${result.passportPath}\n`);
+    process.stdout.write(`publication-primary-artifact=${result.manifest.publication.primaryArtifact}\n`);
+  }
+  return result;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    runPublicationArtifactCli();
+  } catch (error) {
+    console.error(`publication-artifact: ${error.message}`);
+    process.exitCode = 1;
+  }
+}