@kungfu-tech/buildchain 2.11.14-alpha.0 → 2.11.14-alpha.2

package/packages/core/stable-release-gate.js

@@ -0,0 +1,284 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const STABLE_RELEASE_POLICY_CONTRACT = "kungfu-buildchain-stable-release-policy";
+export const STABLE_RELEASE_GATE_CONTRACT = "kungfu-buildchain-stable-release-gate";
+
+function string(value = "") {
+  return String(value ?? "").trim();
+}
+
+function positiveInteger(value, label) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return number;
+}
+
+function timestamp(value, label) {
+  const normalized = string(value);
+  const milliseconds = Date.parse(normalized);
+  if (!normalized || !Number.isFinite(milliseconds)) {
+    throw new Error(`${label} must be an ISO-8601 timestamp`);
+  }
+  return { iso: new Date(milliseconds).toISOString(), milliseconds };
+}
+
+function loadJsonInput({ cwd = process.cwd(), input = "", label }) {
+  const normalized = string(input);
+  if (!normalized) {
+    return undefined;
+  }
+  if (normalized.startsWith("{")) {
+    return JSON.parse(normalized);
+  }
+  const resolved = path.isAbsolute(normalized) ? normalized : path.resolve(cwd, normalized);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`${label} path does not exist: ${normalized}`);
+  }
+  return JSON.parse(fs.readFileSync(resolved, "utf8"));
+}
+
+export function loadStableReleasePolicy({ cwd = process.cwd(), input = "" } = {}) {
+  const policy = loadJsonInput({ cwd, input, label: "stable release policy" });
+  if (!policy) {
+    return undefined;
+  }
+  if (policy.contract !== STABLE_RELEASE_POLICY_CONTRACT) {
+    throw new Error(`stable release policy contract must be ${STABLE_RELEASE_POLICY_CONTRACT}`);
+  }
+  if (Number(policy.schemaVersion) !== 1) {
+    throw new Error("stable release policy schemaVersion must be 1");
+  }
+  const minimumStableIntervalSeconds = positiveInteger(
+    policy.minimumStableIntervalSeconds,
+    "minimumStableIntervalSeconds",
+  );
+  const minimumCanarySoakSeconds = positiveInteger(
+    policy.minimumCanarySoakSeconds,
+    "minimumCanarySoakSeconds",
+  );
+  const productPathPrefixes = [...new Set(
+    (Array.isArray(policy.productPathPrefixes) ? policy.productPathPrefixes : [])
+      .map(string)
+      .filter(Boolean),
+  )];
+  if (productPathPrefixes.length === 0) {
+    throw new Error("stable release policy requires productPathPrefixes[]");
+  }
+  const requiredCanaries = (Array.isArray(policy.requiredCanaries) ? policy.requiredCanaries : [])
+    .map((canary, index) => {
+      const id = string(canary?.id);
+      const source = string(canary?.source);
+      if (!id) {
+        throw new Error(`requiredCanaries[${index}].id is required`);
+      }
+      if (!new Set(["release-candidate", "commit-status"]).has(source)) {
+        throw new Error(`requiredCanaries[${index}].source must be release-candidate or commit-status`);
+      }
+      if (source === "commit-status" && !string(canary.context)) {
+        throw new Error(`requiredCanaries[${index}].context is required for commit-status canaries`);
+      }
+      return {
+        id,
+        source,
+        repository: string(canary.repository),
+        workflow: string(canary.workflow),
+        context: string(canary.context),
+        allowedAttestors: [...new Set(
+          (Array.isArray(canary.allowedAttestors) ? canary.allowedAttestors : [])
+            .map(string)
+            .filter(Boolean),
+        )],
+      };
+    });
+  if (requiredCanaries.length === 0) {
+    throw new Error("stable release policy requires requiredCanaries[]");
+  }
+  if (new Set(requiredCanaries.map((canary) => canary.id)).size !== requiredCanaries.length) {
+    throw new Error("stable release policy canary ids must be unique");
+  }
+  return {
+    schemaVersion: 1,
+    contract: STABLE_RELEASE_POLICY_CONTRACT,
+    enabled: policy.enabled !== false,
+    minimumStableIntervalSeconds,
+    minimumCanarySoakSeconds,
+    productPathPrefixes,
+    requiredCanaries,
+  };
+}
+
+function check(ok, id, message, details = {}) {
+  return { id, status: ok ? "pass" : "fail", message, details };
+}
+
+function matchesProductPath(file, prefixes) {
+  return prefixes.some((prefix) => file === prefix || file.startsWith(prefix));
+}
+
+export function evaluateStableReleaseGate({
+  policy,
+  channel = "",
+  candidate = {},
+  previousStable = undefined,
+  changedPaths = [],
+  impact = {},
+  canaries = [],
+  now = new Date().toISOString(),
+} = {}) {
+  const normalizedChannel = string(channel);
+  if (!policy || policy.enabled === false || normalizedChannel !== "release") {
+    return {
+      schemaVersion: 1,
+      contract: STABLE_RELEASE_GATE_CONTRACT,
+      applies: false,
+      ok: true,
+      channel: normalizedChannel,
+      checks: [],
+      summary: { reason: !policy ? "policy-not-configured" : policy.enabled === false ? "policy-disabled" : "non-stable-channel" },
+    };
+  }
+
+  const nowTime = timestamp(now, "now");
+  const candidatePublished = timestamp(candidate.publishedAt, "candidate.publishedAt");
+  const candidateSha = string(candidate.sha);
+  const candidateTag = string(candidate.tag);
+  const checks = [];
+  checks.push(check(/^[0-9a-f]{40}$/i.test(candidateSha), "candidate.sha", "candidate alpha SHA is exact", { sha: candidateSha }));
+  checks.push(check(/-alpha\.\d+$/.test(candidateTag), "candidate.tag", "candidate is an exact alpha tag", { tag: candidateTag }));
+
+  if (previousStable) {
+    const previousPublished = timestamp(previousStable.publishedAt, "previousStable.publishedAt");
+    const elapsedSeconds = Math.floor((nowTime.milliseconds - previousPublished.milliseconds) / 1000);
+    checks.push(check(
+      elapsedSeconds >= policy.minimumStableIntervalSeconds,
+      "stable.minimum_interval",
+      "minimum interval since the previous stable release is satisfied",
+      {
+        previousTag: string(previousStable.tag),
+        previousPublishedAt: previousPublished.iso,
+        elapsedSeconds,
+        requiredSeconds: policy.minimumStableIntervalSeconds,
+      },
+    ));
+  } else {
+    checks.push(check(true, "stable.minimum_interval", "no previous stable release exists", { firstStable: true }));
+  }
+
+  const normalizedChangedPaths = [...new Set(changedPaths.map(string).filter(Boolean))].sort();
+  const productChangedPaths = normalizedChangedPaths.filter((file) =>
+    matchesProductPath(file, policy.productPathPrefixes));
+  checks.push(check(
+    productChangedPaths.length > 0,
+    "stable.product_diff",
+    "candidate contains a product or contract difference from the current stable release",
+    { changedPaths: productChangedPaths, comparedPathCount: normalizedChangedPaths.length },
+  ));
+
+  const surfaceImpacts = Array.isArray(impact?.surfaceImpacts) ? impact.surfaceImpacts : [];
+  checks.push(check(
+    surfaceImpacts.length > 0 && string(impact?.summary) !== "",
+    "stable.impact",
+    "version-bound impact declares a summary and at least one surface",
+    { summary: string(impact?.summary), surfaceIds: surfaceImpacts.map((entry) => string(entry?.id)).filter(Boolean) },
+  ));
+
+  const canaryById = new Map(canaries.map((canary) => [string(canary?.id), canary]));
+  const canaryCompletionTimes = [];
+  for (const required of policy.requiredCanaries) {
+    const evidence = canaryById.get(required.id);
+    const completedAt = evidence?.completedAt
+      ? timestamp(evidence.completedAt, `canary ${required.id} completedAt`)
+      : undefined;
+    const attestorAllowed = required.allowedAttestors.length === 0 ||
+      required.allowedAttestors.includes(string(evidence?.attestor));
+    const valid = Boolean(
+      evidence &&
+      string(evidence.status) === "success" &&
+      string(evidence.candidateSha) === candidateSha &&
+      completedAt &&
+      completedAt.milliseconds >= candidatePublished.milliseconds &&
+      attestorAllowed,
+    );
+    if (completedAt) {
+      canaryCompletionTimes.push(completedAt.milliseconds);
+    }
+    checks.push(check(
+      valid,
+      `stable.canary.${required.id}`,
+      `required canary ${required.id} passed for the exact alpha candidate`,
+      {
+        source: required.source,
+        context: required.context,
+        repository: string(evidence?.repository || required.repository),
+        workflow: string(evidence?.workflow || required.workflow),
+        runtimeRef: string(evidence?.runtimeRef),
+        candidateSha: string(evidence?.candidateSha),
+        completedAt: completedAt?.iso || "",
+        evidenceUrl: string(evidence?.evidenceUrl),
+        attestor: string(evidence?.attestor),
+        attestorAllowed,
+      },
+    ));
+  }
+
+  const soakStartMilliseconds = Math.max(candidatePublished.milliseconds, ...canaryCompletionTimes);
+  const soakElapsedSeconds = Math.floor((nowTime.milliseconds - soakStartMilliseconds) / 1000);
+  checks.push(check(
+    canaryCompletionTimes.length === policy.requiredCanaries.length &&
+      soakElapsedSeconds >= policy.minimumCanarySoakSeconds,
+    "stable.canary_soak",
+    "minimum soak interval after the final required canary is satisfied",
+    {
+      soakStartedAt: new Date(soakStartMilliseconds).toISOString(),
+      elapsedSeconds: soakElapsedSeconds,
+      requiredSeconds: policy.minimumCanarySoakSeconds,
+    },
+  ));
+
+  const ok = checks.every((entry) => entry.status === "pass");
+  return {
+    schemaVersion: 1,
+    contract: STABLE_RELEASE_GATE_CONTRACT,
+    applies: true,
+    ok,
+    channel: normalizedChannel,
+    evaluatedAt: nowTime.iso,
+    candidate: {
+      tag: candidateTag,
+      sha: candidateSha,
+      publishedAt: candidatePublished.iso,
+    },
+    previousStable: previousStable
+      ? {
+          tag: string(previousStable.tag),
+          sha: string(previousStable.sha),
+          publishedAt: timestamp(previousStable.publishedAt, "previousStable.publishedAt").iso,
+        }
+      : undefined,
+    policy: {
+      minimumStableIntervalSeconds: policy.minimumStableIntervalSeconds,
+      minimumCanarySoakSeconds: policy.minimumCanarySoakSeconds,
+      requiredCanaries: policy.requiredCanaries.map((canary) => canary.id),
+    },
+    checks,
+    summary: {
+      decision: ok ? "allow" : "block",
+      failedChecks: checks.filter((entry) => entry.status === "fail").map((entry) => entry.id),
+      productChangedPaths,
+    },
+  };
+}
+
+export function assertStableReleaseGate(input = {}) {
+  const report = evaluateStableReleaseGate(input);
+  if (!report.ok) {
+    throw Object.assign(
+      new Error(`stable release gate blocked promotion: ${report.summary.failedChecks.join(", ")}`),
+      { report },
+    );
+  }
+  return report;
+}

package/scripts/check-inventory.mjs

@@ -725,6 +725,8 @@ for (const requiredSnippet of [
   "publish-source-ref: ${{ steps.publish-gate.outputs.ref }}",
   "publish-source-sha: ${{ steps.publish-gate.outputs.sha }}",
   "publish-source-locked: ${{ steps.publish-gate.outputs.locked }}",
+  "Enforce Buildchain stable release canary gate",
+  "BUILDCHAIN_STABLE_RELEASE_POLICY: .buildchain/stable-release-policy.json",
 ]) {
   if (!releaseCandidatePromoteWorkflow.includes(requiredSnippet)) {
     throw new Error(`release candidate promote workflow missing KFD gate pass-through: ${requiredSnippet}`);

package/scripts/locked-source-checkout.mjs

@@ -213,6 +213,31 @@ function fetchSha({ targetPath, remoteName, remoteUrl, sha, fetchRef, timeoutMs,
   }
 }
 
+export function runBoundedFetch({ attempts = 1, fetch, onAttempt = () => {}, onRetry = () => {}, shouldRetry = () => true }) {
+  const limit = Math.max(1, Math.floor(Number(attempts) || 1));
+  let lastError;
+  for (let attempt = 1; attempt <= limit; attempt += 1) {
+    onAttempt({ attempt, limit });
+    try {
+      return { value: fetch({ attempt, limit }), attempts: attempt };
+    } catch (error) {
+      lastError = error;
+      if (attempt >= limit || !shouldRetry(error)) {
+        error.fetchAttempts = attempt;
+        throw error;
+      }
+      onRetry({ attempt, limit, error });
+    }
+  }
+  throw lastError;
+}
+
+function retryableGitFetchError(error) {
+  const code = String(error?.code || "").toUpperCase();
+  if (["ETIMEDOUT", "ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ENETUNREACH", "EPIPE"].includes(code)) return true;
+  return /timed?\s*out|timeout|connection (?:reset|refused)|remote end hung up|early eof|rpc failed|http (?:429|5\d\d)|temporary failure|network is unreachable/i.test(String(error?.message || error || ""));
+}
+
 function githubRemoteUrl({ repository, serverUrl = "https://github.com" }) {
   const base = String(serverUrl || "https://github.com").replace(/\/+$/, "");
   return `${base}/${repository}.git`;
@@ -252,6 +277,7 @@ export function lockedSourceCheckout({
   referenceRepositoryTemplate = readEnv("BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE"),
   fallback = readEnv("BUILDCHAIN_CHECKOUT_CACHE_FALLBACK", "github"),
   timeoutSeconds = Number(readEnv("BUILDCHAIN_CHECKOUT_CACHE_TIMEOUT_SECONDS", "60") || 60),
+  fetchAttempts = Number(readEnv("BUILDCHAIN_CHECKOUT_CACHE_FETCH_ATTEMPTS", "3") || 3),
   diagnosticsPath = readEnv("BUILDCHAIN_SOURCE_CHECKOUT_DIAGNOSTICS_PATH", ".buildchain/diagnostics/source-checkout.json"),
   githubToken = readEnv("GITHUB_TOKEN"),
   githubServerUrl = readEnv("GITHUB_SERVER_URL", "https://github.com"),
@@ -265,6 +291,7 @@ export function lockedSourceCheckout({
   const treeSha = sourceTreeSha ? assertSha(sourceTreeSha, "sourceTreeSha") : "";
   const repoParts = splitRepository(repository);
   const timeoutMs = Math.max(1, Number(timeoutSeconds || 60)) * 1000;
+  const normalizedFetchAttempts = Math.max(1, Math.floor(Number(fetchAttempts) || 3));
   const targetPath = ensureCheckoutTarget(checkoutPath, workspace);
   git(["init"], { cwd: targetPath, timeoutMs });
   const renderedMirrorUrl = renderTemplate(mirrorUrlTemplate, { ...repoParts, sha });
@@ -285,6 +312,7 @@ export function lockedSourceCheckout({
       mode: normalizedMode,
       fallback: normalizedFallback,
       timeoutSeconds: Math.max(1, Number(timeoutSeconds || 60)),
+      fetchAttempts: normalizedFetchAttempts,
       mirror: sanitizeIdentity(renderedMirrorUrl),
       referenceRepository: sanitizeIdentity(renderedReferenceRepository),
     },
@@ -294,6 +322,7 @@ export function lockedSourceCheckout({
       transport: "github",
       fallbackUsed: normalizedMode === "off",
       fallbackReason: normalizedMode === "off" ? "cache disabled" : "",
+      githubFetchAttempts: 0,
     },
     verification: {
       head: "",
@@ -352,15 +381,20 @@ export function lockedSourceCheckout({
     if (!evidence.cache.fallbackReason && checkoutError) {
       evidence.cache.fallbackReason = checkoutError.message;
     }
-    fetchSha({
-      targetPath,
-      remoteName: "origin",
-      remoteUrl,
-      sha,
-      fetchRef,
-      timeoutMs,
-      env: githubAuthEnv(githubToken),
-    });
+    try {
+      const fetchResult = runBoundedFetch({
+        attempts: normalizedFetchAttempts,
+        fetch: () => fetchSha({ targetPath, remoteName: "origin", remoteUrl, sha, fetchRef, timeoutMs, env: githubAuthEnv(githubToken) }),
+        onAttempt: ({ attempt }) => { evidence.cache.githubFetchAttempts = attempt; },
+        onRetry: ({ attempt, limit, error }) => console.log(`buildchain: GitHub source fetch failed, retry ${attempt + 1}/${limit}: ${error.message}`),
+        shouldRetry: retryableGitFetchError,
+      });
+      evidence.cache.githubFetchAttempts = fetchResult.attempts;
+    } catch (error) {
+      evidence.durationMs = Date.now() - startedAt;
+      writeEvidence(path.resolve(workspace, diagnosticsPath), evidence);
+      throw error;
+    }
     checkoutFetchedCommit(targetPath, sha, timeoutMs);
   }
   evidence.verification = verifyCheckout({ targetPath, sourceSha: sha, sourceTreeSha: treeSha });

package/scripts/publication-artifact.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { pathToFileURL } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
 import { writePublicationArtifact } from "../packages/core/publication-artifact.js";
 
 function readFlag(args, name, fallback = "") {
@@ -11,16 +13,32 @@ function readBooleanFlag(args, name) {
   return args.includes(`--${name}`);
 }
 
+function readRegistryInputs(args, cwd) {
+  const inputs = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--registry-input" && args[index + 1]) inputs.push(args[index + 1]);
+  }
+  const inputDir = readFlag(args, "registry-input-dir", "");
+  if (inputDir) {
+    const resolved = path.resolve(cwd, inputDir);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) throw new Error(`publication registry input directory is missing: ${inputDir}`);
+    inputs.push(...fs.readdirSync(resolved).filter((entry) => entry.endsWith(".json")).sort().map((entry) => path.join(resolved, entry)));
+  }
+  return inputs;
+}
+
 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>] [--registry-output <file>] [--source-bundle <file>] [--no-source-bundle] [--json]");
+    throw new Error("usage: buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--passport-output <file>] [--registry-output <file>] [--registry-input <file>] [--registry-input-dir <dir>] [--source-bundle <file>] [--no-source-bundle] [--json]");
   }
+  const cwd = readFlag(args, "cwd", process.cwd());
   const result = writePublicationArtifact({
-    cwd: readFlag(args, "cwd", process.cwd()),
+    cwd,
     output: readFlag(args, "output", ""),
     passportOutput: readFlag(args, "passport-output", ""),
     registryOutput: readFlag(args, "registry-output", ""),
+    registryInputs: readRegistryInputs(args, cwd),
     sourceSha: readFlag(args, "source-sha", ""),
     sourceBundlePath: readFlag(args, "source-bundle", ""),
     sourceBundle: !readBooleanFlag(args, "no-source-bundle"),

package/scripts/publication-registry-hydrate.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadBuildchainConfig } from "../packages/core/buildchain-config.js";
+
+const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+
+function semverParts(value) {
+  const match = String(value || "")
+    .trim()
+    .match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) return undefined;
+  return {
+    core: match.slice(1, 4).map(Number),
+    prerelease: match[4] ? match[4].split(".") : [],
+  };
+}
+
+export function compareSemver(left, right) {
+  const a = semverParts(left);
+  const b = semverParts(right);
+  if (!a || !b) throw new Error(`invalid semver comparison: ${left}, ${right}`);
+  for (let index = 0; index < 3; index += 1) {
+    if (a.core[index] !== b.core[index]) return a.core[index] - b.core[index];
+  }
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    return a.prerelease.length === b.prerelease.length
+      ? 0
+      : a.prerelease.length === 0
+        ? 1
+        : -1;
+  }
+  const length = Math.max(a.prerelease.length, b.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const av = a.prerelease[index];
+    const bv = b.prerelease[index];
+    if (av === undefined || bv === undefined) return av === undefined ? -1 : 1;
+    if (av === bv) continue;
+    const an = /^\d+$/.test(av);
+    const bn = /^\d+$/.test(bv);
+    if (an && bn) return Number(av) - Number(bv);
+    if (an !== bn) return an ? -1 : 1;
+    return av.localeCompare(bv);
+  }
+  return 0;
+}
+
+function run(command, args, options = {}) {
+  return execFileSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+  }).trim();
+}
+
+function packageVersions(packageName, registry, commandRunner) {
+  try {
+    const output = commandRunner("npm", [
+      "view",
+      packageName,
+      "versions",
+      "--json",
+      `--registry=${registry}`,
+    ]);
+    const parsed = JSON.parse(output || "[]");
+    return Array.isArray(parsed) ? parsed : parsed ? [parsed] : [];
+  } catch (error) {
+    const detail = [error?.message, error?.stderr, error?.stdout]
+      .filter(Boolean)
+      .join("\n");
+    if (/E404|404 Not Found|is not in this registry/i.test(detail)) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+export function hydratePublishedPublicationRegistry({
+  cwd = process.cwd(),
+  outputDir = ".buildchain/publication/registry-inputs",
+  evidencePath = ".buildchain/publication/registry-hydration.json",
+  registry = DEFAULT_REGISTRY,
+  commandRunner = run,
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const config = loadBuildchainConfig(resolvedCwd).config;
+  const packageName =
+    config.publish?.package || config.publish?.mainPackage || "";
+  const currentVersion = config.publication?.version || "";
+  const registryPath = config.publication?.archive?.registryPath || "";
+  const resolvedOutputDir = path.resolve(resolvedCwd, outputDir);
+  fs.rmSync(resolvedOutputDir, { recursive: true, force: true });
+  fs.mkdirSync(resolvedOutputDir, { recursive: true });
+  if (!packageName || !currentVersion || !registryPath) {
+    return {
+      status: "not-configured",
+      packageName,
+      currentVersion,
+      inputDir: path
+        .relative(resolvedCwd, resolvedOutputDir)
+        .split(path.sep)
+        .join("/"),
+      sources: [],
+    };
+  }
+  const publishedVersions = packageVersions(
+    packageName,
+    registry,
+    commandRunner,
+  )
+    .filter(
+      (version) =>
+        semverParts(version) && compareSemver(version, currentVersion) < 0,
+    )
+    .sort(compareSemver);
+  const sources = [];
+  for (const version of publishedVersions) {
+    const packageDir = path.join(resolvedOutputDir, `.package-${version}`);
+    fs.mkdirSync(packageDir, { recursive: true });
+    const packed = JSON.parse(
+      commandRunner(
+        "npm",
+        [
+          "pack",
+          `${packageName}@${version}`,
+          "--json",
+          "--ignore-scripts",
+          "--pack-destination",
+          packageDir,
+          `--registry=${registry}`,
+        ],
+        { cwd: resolvedCwd },
+      ),
+    );
+    const pack = Array.isArray(packed) ? packed[0] : packed;
+    if (!pack?.filename || !pack?.integrity) {
+      throw new Error(
+        `npm pack did not report filename and integrity for ${packageName}@${version}`,
+      );
+    }
+    const tarball = path.resolve(packageDir, pack.filename);
+    const archiveRegistryPath = `package/${registryPath}`;
+    const archiveEntries = commandRunner("tar", ["-tzf", tarball]).split(/\r?\n/);
+    if (!archiveEntries.includes(archiveRegistryPath)) {
+      sources.push({
+        package: packageName,
+        version,
+        integrity: pack.integrity,
+        status: "registry-not-present",
+      });
+      continue;
+    }
+    const target = path.join(resolvedOutputDir, `${version}.json`);
+    const registryJson = commandRunner("tar", ["-xOzf", tarball, archiveRegistryPath]);
+    fs.writeFileSync(target, `${registryJson}\n`);
+    sources.push({
+      package: packageName,
+      version,
+      integrity: pack.integrity,
+      status: "accepted-input",
+      registryPath: path
+        .relative(resolvedCwd, target)
+        .split(path.sep)
+        .join("/"),
+    });
+  }
+  for (const entry of fs.readdirSync(resolvedOutputDir)) {
+    if (entry.startsWith(".package-")) {
+      fs.rmSync(path.join(resolvedOutputDir, entry), {
+        recursive: true,
+        force: true,
+      });
+    }
+  }
+  const evidence = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-publication-registry-hydration",
+    status: sources.some((source) => source.status === "accepted-input")
+      ? "hydrated"
+      : "bootstrap",
+    authentication: "npm-registry-https-plus-package-integrity",
+    registry,
+    packageName,
+    currentVersion,
+    inputDir: path
+      .relative(resolvedCwd, resolvedOutputDir)
+      .split(path.sep)
+      .join("/"),
+    sources,
+  };
+  const resolvedEvidencePath = path.resolve(resolvedCwd, evidencePath);
+  fs.mkdirSync(path.dirname(resolvedEvidencePath), { recursive: true });
+  fs.writeFileSync(
+    resolvedEvidencePath,
+    `${JSON.stringify(evidence, null, 2)}\n`,
+  );
+  return evidence;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const cwdIndex = process.argv.indexOf("--cwd");
+    const result = hydratePublishedPublicationRegistry({
+      cwd: cwdIndex === -1 ? process.cwd() : process.argv[cwdIndex + 1],
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch (error) {
+    console.error(`publication-registry-hydrate: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/run-lifecycle-core.mjs

@@ -446,6 +446,9 @@ export function runLifecycle({
 
   if (command.trim()) {
     commandSource = "workflow-input";
+    const lifecycle = loadedConfig?.config?.lifecycle || {};
+    const configuredStage = stageName ? lifecycle[stageName] : undefined;
+    const commandShell = configuredStage?.shell || true;
     const startedAt = Date.now();
     userLog.info("lifecycle.command.start", {
       attributes: {
@@ -457,6 +460,8 @@ export function runLifecycle({
     try {
       const commandEnv = {
         ...process.env,
+        ...(lifecycle.env || {}),
+        ...(configuredStage?.env || {}),
         ...(resolvedLogPath
           ? {
               BUILDCHAIN_LOG_PATH: resolvedLogPath,
@@ -469,7 +474,7 @@ export function runLifecycle({
           command,
           cwd: resolvedCwd,
           env: commandEnv,
-          shell: true,
+          shell: commandShell,
           label: `lifecycle-${stageName || "command"}`,
           processSummaryPath: resolvedProcessSummaryPath,
           processSamplesPath: resolvedProcessSamplesPath,
@@ -480,7 +485,7 @@ export function runLifecycle({
         execSync(command, {
           cwd: resolvedCwd,
           env: commandEnv,
-          shell: true,
+          shell: commandShell,
           stdio: "inherit",
         });
       }