@kungfu-tech/buildchain 3.0.6 → 3.0.7-alpha.1

package/scripts/materialize-self-release-candidate-version.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  getVersionStrategy,
+  loadConfiguredAnchorManifest,
+  discoverConfiguredDerivedVersionMaterial,
+} from "../packages/core/buildchain-config.js";
+import {
+  alignMajorBootstrapReleaseImpact,
+  currentConfiguredVersion,
+  discoverVersionStateFiles,
+  runVersionVerification,
+  updateVersionStateContents,
+  versionVerificationAllowedPathsForPromotion,
+  versionVerificationEnv,
+} from "../actions/promote-buildchain-ref/internal/version-state.js";
+
+function required(value, name) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${name} is required`);
+  return normalized;
+}
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (!argument.startsWith("--")) throw new Error(`unexpected argument: ${argument}`);
+    const name = argument.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`--${name} requires a value`);
+    options[name] = value;
+    index += 1;
+  }
+  return options;
+}
+
+export function materializeSelfReleaseCandidateVersion({
+  cwd = process.cwd(),
+  version,
+  channel,
+  sourceSha,
+  generatedAt,
+} = {}) {
+  const resolvedVersion = required(version, "version");
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(resolvedVersion)) {
+    throw new Error(`version must be an exact semantic version: ${resolvedVersion}`);
+  }
+  const resolvedChannel = required(channel, "channel");
+  if (!new Set(["alpha", "release", "major"]).has(resolvedChannel)) {
+    throw new Error(`channel must be alpha, release, or major: ${resolvedChannel}`);
+  }
+  const resolvedSourceSha = required(sourceSha, "sourceSha");
+  if (!/^[0-9a-f]{40}$/i.test(resolvedSourceSha)) {
+    throw new Error("sourceSha must be a 40-character Git SHA");
+  }
+  const resolvedGeneratedAt = required(generatedAt, "generatedAt");
+  if (Number.isNaN(Date.parse(resolvedGeneratedAt))) {
+    throw new Error(`generatedAt must be an ISO timestamp: ${resolvedGeneratedAt}`);
+  }
+
+  const discovered = discoverVersionStateFiles(cwd);
+  if (discovered.files.length === 0) {
+    throw new Error("self-release candidate requires declared version state");
+  }
+  const discoveredPaths = discovered.files.map((file) => file.path);
+  const derivedPaths = discoverConfiguredDerivedVersionMaterial(
+    cwd,
+    discovered.config,
+  ).map((file) => file.path);
+  const versionStrategy = getVersionStrategy(discovered.config);
+  const anchorManifest = loadConfiguredAnchorManifest(cwd, discovered.config);
+  const lifecycleEnv = versionVerificationEnv(versionStrategy, anchorManifest, {
+    generatedAt: resolvedGeneratedAt,
+    sourceSha: resolvedSourceSha,
+  });
+  if (resolvedChannel === "major") {
+    lifecycleEnv.BUILDCHAIN_MAJOR_VERSION_BOOTSTRAP = "true";
+  }
+
+  let changedFiles = updateVersionStateContents(discovered.files, resolvedVersion);
+  if (resolvedChannel === "major") {
+    changedFiles = alignMajorBootstrapReleaseImpact(changedFiles, {
+      version: resolvedVersion,
+    });
+  }
+  const materializedFiles = runVersionVerification({
+    cwd,
+    loadedConfig: discovered.config,
+    version: resolvedVersion,
+    changedFiles,
+    allowedPaths: versionVerificationAllowedPathsForPromotion(
+      resolvedChannel,
+      discoveredPaths,
+      derivedPaths,
+    ),
+    env: lifecycleEnv,
+    runLifecycleVerify: false,
+  });
+  const materialized = discoverVersionStateFiles(cwd);
+  const actualVersion = currentConfiguredVersion(materialized.files);
+  if (actualVersion !== resolvedVersion) {
+    throw new Error(
+      `materialized self-release candidate version mismatch: expected ${resolvedVersion}, got ${actualVersion || "<empty>"}`,
+    );
+  }
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-self-release-candidate-version/v1",
+    version: resolvedVersion,
+    channel: resolvedChannel,
+    sourceSha: resolvedSourceSha,
+    generatedAt: resolvedGeneratedAt,
+    files: materializedFiles.map((file) => file.path),
+  };
+}
+
+export function materializeSelfReleaseCandidateVersionCli(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  const result = materializeSelfReleaseCandidateVersion({
+    cwd: path.resolve(options.cwd || process.cwd()),
+    version: options.version,
+    channel: options.channel,
+    sourceSha: options["source-sha"],
+    generatedAt: options["generated-at"],
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return result;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  materializeSelfReleaseCandidateVersionCli();
+}

package/scripts/publication-commit-evidence.mjs

@@ -7,6 +7,12 @@ import { pathToFileURL } from "node:url";
 
 const SCHEMA = "kungfu-buildchain-publication-commit-evidence/v1";
 const INSTALLER_BUNDLE_SCHEMA = "kungfu.installer-publication-bundle/v1";
+const RELEASE_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const RELEASE_REDIRECT_HOSTS = new Set([
+  "github.com",
+  "release-assets.githubusercontent.com",
+  "objects.githubusercontent.com",
+]);
 
 function requiredString(value, label) {
   if (typeof value !== "string" || value.trim() === "") {
@@ -104,7 +110,7 @@ function validateInstallerBundle(evidence, expected) {
   }
   if (
     exactSha(bundle.sourceCommit, "installerBundle.sourceCommit") !==
-      expected.sourceSha ||
+      expected.candidateSourceSha ||
     !["alpha", "stable"].includes(bundle.channel)
   ) {
     throw new Error("installer bundle release identity mismatch");
@@ -228,6 +234,7 @@ function validateInstallerBundle(evidence, expected) {
   return {
     schema: bundle.schema,
     bundleRoot,
+    sourceCommit: bundle.sourceCommit,
     manifestDigest: bundle.manifestDigest,
     channel: bundle.channel,
     channelPayloadRoot: bundle.channelPayloadRoot,
@@ -238,10 +245,9 @@ function validateInstallerBundle(evidence, expected) {
     assets: bundle.assets,
   };
 }
-
 export function validatePublicationCommitEvidence(
   evidence,
-  { version, sourceSha, releaseSha, releaseTag } = {},
+  { version, sourceSha, candidateSourceSha, releaseSha, releaseTag } = {},
 ) {
   if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
     throw new Error("publication commit evidence must be an object");
@@ -264,6 +270,17 @@ export function validatePublicationCommitEvidence(
       throw new Error(`publication commit evidence ${field} mismatch`);
     }
   }
+  expected.candidateSourceSha = exactSha(
+    candidateSourceSha ?? identity.candidateSourceSha ?? expected.sourceSha,
+    "expected candidateSourceSha",
+  );
+  if (
+    identity.candidateSourceSha !== undefined &&
+    exactSha(identity.candidateSourceSha, "identity.candidateSourceSha") !==
+      expected.candidateSourceSha
+  ) {
+    throw new Error("publication commit evidence candidateSourceSha mismatch");
+  }
   const publicUrl = publicHttps(evidence.publication?.url, "publication.url");
   const payloadRoot = sha256Root(
     evidence.publication?.payloadRoot,
@@ -313,15 +330,47 @@ export async function verifyInstallerBundleReadback(
   if (typeof fetchImpl !== "function") {
     throw new Error("installer bundle read-back requires fetch");
   }
-  const manifestResponse = await fetchImpl(result.publicUrl, {
-    redirect: "manual",
-    cache: "no-store",
-  });
-  if (manifestResponse.status !== 200) {
-    throw new Error(
-      `installer bundle manifest read-back failed: HTTP ${manifestResponse.status}`,
-    );
-  }
+  const fetchReleaseReadback = async (url, label) => {
+    let current = url;
+    for (let hop = 0; hop <= 3; hop += 1) {
+      const response = await fetchImpl(current, {
+        redirect: "manual",
+        cache: "no-store",
+      });
+      if (response.status === 200) return response;
+      if (!RELEASE_REDIRECT_STATUSES.has(response.status)) {
+        throw new Error(`${label} failed: HTTP ${response.status}`);
+      }
+      if (hop === 3) {
+        throw new Error(`${label} exceeded the bounded redirect limit`);
+      }
+      const location = response.headers?.get?.("location");
+      if (!location) {
+        throw new Error(`${label} redirect omitted Location`);
+      }
+      const redirect = new URL(location, current);
+      if (
+        redirect.protocol !== "https:" ||
+        redirect.username ||
+        redirect.password ||
+        !RELEASE_REDIRECT_HOSTS.has(redirect.hostname) ||
+        (redirect.hostname === "github.com" &&
+          !redirect.pathname.startsWith(
+            "/kungfu-systems/kungfu/releases/download/",
+          ))
+      ) {
+        throw new Error(
+          `${label} redirected outside trusted GitHub release storage`,
+        );
+      }
+      current = redirect.href;
+    }
+    throw new Error(`${label} failed without a terminal response`);
+  };
+  const manifestResponse = await fetchReleaseReadback(
+    result.publicUrl,
+    "installer bundle manifest read-back",
+  );
   const manifestBytes = Buffer.from(await manifestResponse.arrayBuffer());
   if (digest(manifestBytes) !== bundle.manifestDigest) {
     throw new Error("installer bundle manifest digest mismatch");
@@ -336,7 +385,7 @@ export async function verifyInstallerBundleReadback(
     semanticRoot(unsigned) !== bundle.bundleRoot ||
     manifest.package?.name !== "@kungfu-tech/site" ||
     typeof manifest.package?.version !== "string" ||
-    manifest.identity?.sourceCommit !== result.identity.sourceSha ||
+    manifest.identity?.sourceCommit !== result.identity.candidateSourceSha ||
     manifest.identity?.releaseSha !== result.identity.releaseSha ||
     manifest.identity?.releaseTag !== result.identity.releaseTag ||
     manifest.identity?.version !== result.identity.version ||
@@ -365,15 +414,10 @@ export async function verifyInstallerBundleReadback(
   for (const asset of bundle.assets) {
     let observation = byUrl.get(asset.releaseUrl);
     if (!observation) {
-      const response = await fetchImpl(asset.releaseUrl, {
-        redirect: "manual",
-        cache: "no-store",
-      });
-      if (response.status !== 200) {
-        throw new Error(
-          `installer bundle asset read-back failed: HTTP ${response.status}`,
-        );
-      }
+      const response = await fetchReleaseReadback(
+        asset.releaseUrl,
+        "installer bundle asset read-back",
+      );
       const bytes = Buffer.from(await response.arrayBuffer());
       observation = {
         releaseUrl: asset.releaseUrl,
@@ -394,7 +438,7 @@ export async function verifyInstallerBundleReadback(
     schema: "kungfu-buildchain-installer-publication-bundle-seal/v1",
     bundleRoot: bundle.bundleRoot,
     manifestDigest: bundle.manifestDigest,
-    sourceCommit: result.identity.sourceSha,
+    sourceCommit: result.identity.candidateSourceSha,
     releaseTag: result.identity.releaseTag,
     releasePassport: bundle.releasePassport,
     observations,
@@ -409,6 +453,8 @@ async function main(args) {
     if (value === "--evidence") options.evidence = args[++index];
     else if (value === "--version") options.version = args[++index];
     else if (value === "--source-sha") options.sourceSha = args[++index];
+    else if (value === "--candidate-source-sha")
+      options.candidateSourceSha = args[++index];
     else if (value === "--release-sha") options.releaseSha = args[++index];
     else if (value === "--release-tag") options.releaseTag = args[++index];
     else throw new Error(`unknown argument: ${value}`);

package/scripts/release-candidate-resolver.mjs

@@ -351,16 +351,22 @@ export function generatePublishRequiredArtifacts({
     const files = Array.isArray(manifest.files) ? manifest.files : [];
     return files
       .filter((file) => file?.sha256)
-      .map((file) => ({
-        kind,
-        name: packageNameFromArtifactPath(file.path || file.name || manifest.artifactName || platform),
-        ref,
-        digest: String(file.sha256).startsWith("sha256:")
-          ? String(file.sha256)
-          : `sha256:${file.sha256}`,
-        role: "platform",
-        platform,
-      }));
+      .map((file) => {
+        const name = String(file.path || file.name || manifest.artifactName || platform)
+          .replaceAll("\\", "/")
+          .replace(/^\.\//, "");
+        return {
+          ...(platform ? { group: platform } : {}),
+          kind,
+          name,
+          ref,
+          digest: String(file.sha256).startsWith("sha256:")
+            ? String(file.sha256)
+            : `sha256:${file.sha256}`,
+          role: "platform",
+          platform,
+        };
+      });
   });
 }
 

package/scripts/release-tail.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  compileReleaseTailDeclaration,
+  createReleaseTailTransaction,
+  readReleaseTailTransaction,
+  validateReleaseTailTransaction,
+  writeReleaseTailTransaction,
+} from "../packages/core/release-tail-provider-plane.js";
+import { diagnoseLegacyReleaseTailHooks } from "../packages/core/release-tail-compatibility.js";
+import {
+  executePublicationRehearsal,
+  publicationRehearsalDiagnostic,
+} from "../packages/core/publication-rehearsal-runtime.js";
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index < 0 ? fallback : args[index + 1] || "";
+}
+
+function readJson(value, label) {
+  if (!value) throw new Error(`${label} is required`);
+  const filePath = path.resolve(value);
+  if (fs.existsSync(filePath))
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  return JSON.parse(value);
+}
+
+function output(value, filePath = "") {
+  if (filePath) {
+    const resolved = path.resolve(filePath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, `${JSON.stringify(value, null, 2)}\n`);
+  }
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function runReleaseTailCli(args = process.argv.slice(2)) {
+  const [mode = "status", ...options] = args;
+  if (mode === "rehearse") {
+    const capsulePath = flag(options, "capsule");
+    const capsuleRoot = flag(options, "capsule-root");
+    const statePath = flag(options, "state");
+    const evidencePath = flag(options, "evidence");
+    for (const [name, value] of Object.entries({
+      "--capsule": capsulePath,
+      "--capsule-root": capsuleRoot,
+      "--state": statePath,
+      "--evidence": evidencePath,
+    })) {
+      if (!value || !path.isAbsolute(value)) {
+        throw new Error(`${name} must be an explicit absolute path`);
+      }
+    }
+    const capsule = readJson(capsulePath, "--capsule");
+    const rehearsalMode = flag(options, "mode", "simulate");
+    if (!new Set(["simulate", "replay"]).has(rehearsalMode)) {
+      throw new Error("local rehearsal --mode must be simulate or replay");
+    }
+    const environment = flag(options, "environment-json")
+      ? readJson(flag(options, "environment-json"), "--environment-json")
+      : {};
+    let result;
+    try {
+      result = await executePublicationRehearsal({
+        capsule,
+        capsuleRoot,
+        mode: rehearsalMode,
+        environment,
+        checkpoint: (transaction) =>
+          writeReleaseTailTransaction(statePath, transaction),
+      });
+    } catch (error) {
+      const diagnostic = publicationRehearsalDiagnostic(error, { capsule });
+      output(diagnostic, evidencePath);
+      throw error;
+    }
+    writeReleaseTailTransaction(statePath, result.transaction);
+    output(result.evidence, evidencePath);
+    return result;
+  }
+  if (mode === "plan") {
+    const plan = compileReleaseTailDeclaration(
+      readJson(flag(options, "declaration"), "--declaration"),
+    );
+    output(plan, flag(options, "output"));
+    return plan;
+  }
+  if (mode === "init") {
+    const transaction = createReleaseTailTransaction(
+      readJson(flag(options, "declaration"), "--declaration"),
+    );
+    const statePath = flag(
+      options,
+      "state",
+      ".buildchain/release-tail/state.json",
+    );
+    writeReleaseTailTransaction(statePath, transaction);
+    output(transaction);
+    return transaction;
+  }
+  if (mode === "status" || mode === "verify") {
+    const statePath = flag(
+      options,
+      "state",
+      ".buildchain/release-tail/state.json",
+    );
+    const transaction = readReleaseTailTransaction(statePath);
+    const validation = validateReleaseTailTransaction(transaction);
+    const nextOperation = transaction.operations.find(
+      (entry) => entry.status === "pending",
+    );
+    const report = {
+      schema: "kungfu.buildchain.release-tail.status/v1",
+      ok: validation.valid,
+      state: transaction.state,
+      stateRoot: transaction.stateRoot,
+      transactionRoot: transaction.transactionRoot,
+      nextOperation: nextOperation
+        ? {
+            operationId: nextOperation.operationId,
+            capabilityId: nextOperation.capabilityId,
+            adapter: nextOperation.effect.adapter,
+          }
+        : null,
+      receiptRoots: transaction.receipts.map((receipt) => receipt.receiptRoot),
+      issues: validation.issues,
+    };
+    output(report, flag(options, "output"));
+    return report;
+  }
+  if (mode === "compat") {
+    const report = diagnoseLegacyReleaseTailHooks(
+      readJson(flag(options, "hooks-json"), "--hooks-json"),
+    );
+    output(report, flag(options, "output"));
+    if (!report.compatible) process.exitCode = 1;
+    return report;
+  }
+  throw new Error(
+    "usage: buildchain release-tail <plan|init|status|verify|compat|rehearse> [--declaration <json-or-path>] [--capsule <path>] [--capsule-root <absolute-path>] [--mode <simulate|replay>] [--state <path>] [--evidence <path>] [--hooks-json <json-or-path>] [--output <path>]",
+  );
+}
+
+if (
+  !process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT &&
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    await runReleaseTailCli();
+  } catch (error) {
+    console.error(`release-tail: ${error.message}`);
+    process.exitCode = 1;
+  }
+}