@kungfu-tech/buildchain 4.1.3 → 4.1.4

package/packages/core/adoption/consumer-init.js

@@ -0,0 +1,279 @@
+import fs from "node:fs";
+import path from "node:path";
+import { stringify } from "smol-toml";
+import { compileConsumerPlan, CONFIG_PATH } from "../consumer/contract/plan.js";
+import { consumerWorkflows } from "../consumer/contract/entries.js";
+import {
+  assertPackageManager,
+  detectPackageManager,
+} from "../build/package-manager.js";
+
+const TYPES = {
+  package: "npm",
+  npm: "npm",
+  native: "binary",
+  binary: "binary",
+  "publication-artifact": "paper",
+  paper: "paper",
+  "anchored-package": "npm",
+};
+const START = "<!-- buildchain:consumer:start -->";
+const END = "<!-- buildchain:consumer:end -->";
+
+function packageManager(cwd, requested) {
+  if (requested) return assertPackageManager(requested);
+  try {
+    return detectPackageManager(cwd).name;
+  } catch {
+    return "pnpm";
+  }
+}
+
+function product(type, manager, artifactName) {
+  const lifecycle = {
+    npm: {
+      install: [
+        manager === "npm"
+          ? "npm ci"
+          : manager === "yarn"
+            ? "corepack yarn install --immutable"
+            : "corepack pnpm install --frozen-lockfile",
+      ],
+      build: [
+        manager === "npm" ? "npm run build" : `corepack ${manager} run build`,
+      ],
+      verify: [
+        manager === "npm" ? "npm run check" : `corepack ${manager} run check`,
+      ],
+    },
+    binary: {
+      build: [
+        "cmake -S . -B build -DCMAKE_BUILD_TYPE=Release",
+        "cmake --build build --config Release",
+        "cmake --install build --prefix dist/stage",
+        "cmake -E tar czf dist/product.tar.gz --format=gnutar dist/stage",
+      ],
+      verify: ["ctest --test-dir build --output-on-failure"],
+    },
+    paper: { build: ["make pdf"], verify: ["make check"] },
+  }[type];
+  const artifact = {
+    npm: { path: ".", kind: "npm-package", extension: ".tgz" },
+    binary: {
+      path: "dist/product.tar.gz",
+      kind: "archive",
+      extension: ".tar.gz",
+    },
+    paper: { path: "_build/main.pdf", kind: "pdf", extension: ".pdf" },
+  }[type];
+  return {
+    id: "main",
+    type,
+    platforms: ["linux-x64"],
+    ...lifecycle,
+    artifacts: [
+      {
+        id: "main",
+        path: artifact.path,
+        kind: artifact.kind,
+        ...(artifactName
+          ? {
+              filename: artifactName.endsWith(artifact.extension)
+                ? artifactName
+                : `${artifactName}${artifact.extension}`,
+            }
+          : {}),
+      },
+    ],
+    targets: [
+      {
+        provider: type === "npm" ? "npm" : "github-release",
+        artifacts: ["main"],
+        ...(type === "npm" ? { access: "public" } : {}),
+      },
+    ],
+  };
+}
+
+function versionSource(cwd, type) {
+  const packagePath = path.join(cwd, "package.json");
+  for (const file of ["package.json", "release.json"]) {
+    const stat = fs.lstatSync(path.join(cwd, file), { throwIfNoEntry: false });
+    if (stat && !stat.isFile())
+      throw new Error(`${file}: version authority must be a regular file`);
+  }
+  const manifest = fs.existsSync(packagePath)
+    ? JSON.parse(fs.readFileSync(packagePath, "utf8"))
+    : null;
+  if (type === "npm" && typeof manifest?.version !== "string")
+    throw new Error(
+      "npm initialization requires the product's package.json with a version",
+    );
+  const file = manifest?.version ? "package.json" : "release.json";
+  const existing =
+    file === "package.json"
+      ? manifest
+      : fs.existsSync(path.join(cwd, file))
+        ? JSON.parse(fs.readFileSync(path.join(cwd, file), "utf8"))
+        : null;
+  if (existing && typeof existing.version !== "string")
+    throw new Error(`${file}: version must be a string`);
+  const version = existing?.version || "0.1.0-alpha.0";
+  return {
+    file,
+    version,
+    files: existing
+      ? {}
+      : { [file]: `${JSON.stringify({ version }, null, 2)}\n` },
+  };
+}
+
+function versionLine(version) {
+  const line =
+    /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.exec(
+      version,
+    );
+  if (!line)
+    throw new Error("The product version must be semantic version text");
+  return `v${line[1]}/v${line[1]}.${line[2]}`;
+}
+
+export function consumerAgentInstructions(current = "") {
+  for (const name of ["next-development", "paper-agent-entry"]) {
+    const legacyStart = `<!-- buildchain:${name}:v1:start -->`;
+    const legacyEnd = `<!-- buildchain:${name}:v1:end -->`;
+    if (current.includes(legacyStart) || current.includes(legacyEnd)) {
+      const start = current.indexOf(legacyStart),
+        end = current.indexOf(legacyEnd);
+      if (
+        start < 0 ||
+        end < start ||
+        current.indexOf(legacyStart, start + 1) !== -1 ||
+        current.indexOf(legacyEnd, end + 1) !== -1
+      )
+        throw new Error(
+          "Incomplete or ambiguous legacy Buildchain instructions",
+        );
+      current = current.slice(0, start) + current.slice(end + legacyEnd.length);
+    }
+  }
+  const section = `${START}
+## Buildchain consumer
+
+Maintain product install, build and verification commands in schema-2
+\`.buildchain/buildchain.toml\`. Keep the generated \`buildchain.yml\` and
+\`buildchain-recover.yml\` caller bytes unchanged across product types.
+Open a protected channel PR to request delivery or publication. The published
+runtime owns version preparation, publication and next-development completion.
+Recover only an exact attempt, with an optional temporary repaired runtime.
+Tool-maintained \`.buildchain/contract-lock.json\` and
+\`.buildchain/alpha-contract-lock.json\` bind the published runtime.
+Consumer scripts must not implement release controllers or provider protocols.
+${END}`;
+  if (current.includes(START) !== current.includes(END))
+    throw new Error("Incomplete managed Buildchain consumer instructions");
+  if (current.includes(START)) {
+    const start = current.indexOf(START),
+      end = current.indexOf(END) + END.length;
+    if (
+      end < start ||
+      current.indexOf(START, start + START.length) !== -1 ||
+      current.indexOf(END, end) !== -1
+    )
+      throw new Error("Ambiguous managed Buildchain consumer instructions");
+    return current.slice(0, start) + section + current.slice(end);
+  }
+  const header =
+    current.trimEnd() ||
+    `---
+status: active
+period: ongoing
+theme: buildchain-consumer
+doc_type: process-rule
+source_level: generated-template
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-20
+---
+
+# Repository instructions`;
+  return `${header}\n\n${section}\n`;
+}
+
+export function planConsumerInitialization({
+  cwd,
+  type,
+  requestedManager = "",
+  artifactName = "",
+}) {
+  const productType = TYPES[type];
+  if (!productType)
+    throw new Error(
+      "init supports npm/package, binary/native, paper/publication-artifact, and anchored-package; legacy web-surface and infra-contract initialization is not part of the schema-2 pipeline",
+    );
+  const manager = packageManager(cwd, requestedManager);
+  const version = versionSource(cwd, productType);
+  return {
+    manager,
+    productType,
+    files: {
+      ...version.files,
+      [CONFIG_PATH]: consumerConfiguration({
+        type,
+        manager,
+        artifactName,
+        version: version.version,
+        versionFile: version.file,
+      }),
+      ...consumerWorkflows(),
+    },
+  };
+}
+
+// Shared pure plan construction for init and product-source scaffolders.
+export function consumerConfiguration({
+  type,
+  manager = "pnpm",
+  artifactName = "",
+  version,
+  versionFile = "package.json",
+}) {
+  const productType = TYPES[type];
+  if (!productType)
+    throw new Error(`Unsupported consumer product type: ${type}`);
+  if (productType === "npm") assertPackageManager(manager);
+  const line = versionLine(version);
+  const plan = {
+    schema: 2,
+    products: [product(productType, manager, artifactName)],
+    version: {
+      strategy: type === "anchored-package" ? "anchored" : "semver",
+      files: [{ path: versionFile, format: "json", key: "version" }],
+    },
+    channels: [
+      ...["feature", "fix", "chore", "docs", "ci", "refactor"].map(
+        (prefix) => ({
+          from: `${prefix}/*`,
+          to: `dev/${line}`,
+          operation: "develop",
+        }),
+      ),
+      {
+        from: `dev/${line}`,
+        to: `alpha/${line}`,
+        operation: "alpha",
+      },
+      {
+        from: `alpha/${line}`,
+        to: `release/${line}`,
+        operation: "stable",
+      },
+    ],
+    review: { minimum_approvals: 1, code_owners: true, merge_queue: true },
+  };
+  const toml = stringify(plan);
+  compileConsumerPlan(toml);
+  return toml;
+}

package/packages/core/adoption/qualification/admission.js

@@ -83,7 +83,7 @@ export function admitAdopterPolicy({
     invocationRoot: consumerRoot,
     repository,
     sourceSha: consumerSha,
-    invokedWorkflow: ".github/workflows/public-build-adopter-qualification.yml",
+    invokedWorkflow: ".github/workflows/.build-adopter-qualification.yml",
     invocationSourcePath,
     resolvedWorkflowSha: runtimeSha,
     resolvedRuntimeSha: runtimeSha,

package/packages/core/build/cli/cache.mjs

@@ -10,8 +10,6 @@ import {
   readBooleanFlag,
   readFlag,
   readJsonInput,
-  readRepeatedFlag,
-  readRepeatedJsonInputs,
   writeJsonFile,
 } from "../../contracts/cli/options.mjs";
 

package/packages/core/build/cli/facts.mjs

@@ -9,10 +9,7 @@ import {
   printJson,
   readBooleanFlag,
   readFlag,
-  readJsonInput,
   readRepeatedFlag,
-  readRepeatedJsonInputs,
-  writeJsonFile,
 } from "../../contracts/cli/options.mjs";
 import { runCompatibilityFactsCli } from "../../governance/cli/compatibility-facts.mjs";
 import { root } from "../../contracts/cli/context.mjs";

package/packages/core/build/cli/homebrew.mjs

@@ -9,10 +9,6 @@ import {
   printJson,
   readBooleanFlag,
   readFlag,
-  readJsonInput,
-  readRepeatedFlag,
-  readRepeatedJsonInputs,
-  writeJsonFile,
 } from "../../contracts/cli/options.mjs";
 
 export async function runHomebrewCli(args = []) {

package/packages/core/build/cli/lifecycle.mjs

@@ -4,10 +4,7 @@ import {
   printJson,
   readBooleanFlag,
   readFlag,
-  readJsonInput,
   readRepeatedFlag,
-  readRepeatedJsonInputs,
-  writeJsonFile,
 } from "../../contracts/cli/options.mjs";
 import { runScript } from "../../workflow/cli/process.mjs";
 

package/packages/core/build/github-artifact-attestation.js

@@ -13,7 +13,7 @@ export const GITHUB_ARTIFACT_ATTESTATION_VERIFICATION_CONTRACT =
 export const GITHUB_ARTIFACT_ATTESTATION_PREDICATE_TYPE =
   "https://buildchain.libkungfu.dev/attestations/github-artifact/v1";
 export const GITHUB_ARTIFACT_ATTESTATION_WORKFLOW =
-  ".github/workflows/public-release-artifact-attestation.yml";
+  ".github/workflows/.release-artifact-attestation.yml";
 
 const SHA256 = /^sha256:([0-9a-f]{64})$/;
 const COMMIT = /^[0-9a-f]{40}$/;
@@ -127,7 +127,7 @@ function normalizeSigner(value) {
   if (signerRepository !== "kungfu-systems/buildchain") {
     throw new Error("policy.signer.repository must be kungfu-systems/buildchain");
   }
-  if (workflowPath !== GITHUB_ARTIFACT_ATTESTATION_WORKFLOW) {
+  if (![GITHUB_ARTIFACT_ATTESTATION_WORKFLOW, ".github/workflows/public-release-artifact-attestation.yml"].includes(workflowPath)) {
     throw new Error(`policy.signer.workflowPath must be ${GITHUB_ARTIFACT_ATTESTATION_WORKFLOW}`);
   }
   return {

package/packages/core/build/platform-stage-checkpoints.js

@@ -225,7 +225,7 @@ export function validatePlatformStageCheckpointDeclaration(value) {
   tokens([...stageIds].sort(), "$/declaration/stageIds");
   exactKeys(
     value.projections,
-    ["protectedWorkflow", "generatedTemplate", "agentGuidance", "manual"],
+    ["protectedWorkflow", "productVerification", "agentGuidance", "manual"],
     "$/declaration/projections",
   );
   exactKeys(

package/packages/core/build/signing/dispatch.js

@@ -14,7 +14,7 @@ function repository(value, label) {
   return normalized;
 }
 
-const AUTHORITY_WORKFLOW = "public-release-signing-authority.yml";
+const AUTHORITY_WORKFLOW = ".release-signing-authority.yml";
 
 export function resolveAuthorityDispatchRef(value = "v4") {
   if (!["v4", "v4-alpha"].includes(value))

package/packages/core/consumer/buildchain-config.js

@@ -7,6 +7,7 @@ import {
   BUILDCHAIN_CONFIG_PATH,
 } from "../contracts/buildchain-layout.js";
 import { readProductConfiguration } from "./contract/reader.js";
+import { consumerConfigurationSummary } from "./contract/local-validation.js";
 import { runShellCommandSync } from "../runtime/spawn-command.js";
 import { normalizeBuildConfiguration } from "../build/build-configuration.js";
 
@@ -1637,6 +1638,14 @@ export function validateBuildchainConfig(
     throw new Error("version state is required but no version.files are configured");
   }
 
+  if (loadedConfig.config.schema === 2)
+    return consumerConfigurationSummary(
+      loadedConfig,
+      versionFiles,
+      discoverConfiguredDerivedVersionMaterial(cwd, loadedConfig),
+      requireLifecycleStages,
+    );
+
   const lifecycleStages = configuredLifecycleStages(loadedConfig);
   const stageNames = new Set(lifecycleStages.map((stage) => stage.name));
   const missingStages = requireLifecycleStages.filter((stage) => !stageNames.has(stage));