@kungfu-tech/buildchain 2.9.1 → 2.10.0

package/packages/core/public-surface-audit.js

@@ -59,6 +59,7 @@ function commandId(first = "", second = "") {
   if (head === "log" && sub) return "logging";
   if (head === "diagnostics" && sub) return `diagnostics-${sub}`;
   if (head === "facts" && sub) return "build-facts";
+  if (head === "kfd-3" && sub) return `kfd-3-${sub}`;
   if (head === "sample" && sub) return `sample-${sub}`;
   if (head === "badges" && sub) return `badges-${sub}`;
   if (head === "homebrew" && sub) return `homebrew-${sub}`;

package/scripts/check-inventory.mjs

@@ -126,6 +126,9 @@ if (rootPackage.exports?.["./buildchain-contract"] !== "./packages/core/buildcha
 if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-reporting.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/issue-reporting");
 }
+if (rootPackage.exports?.["./kfd-3-surfaces"] !== "./packages/core/kfd3-surface-register.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/kfd-3-surfaces");
+}
 if (rootPackage.exports?.["./release-line-bootstrap"] !== "./packages/core/release-line-bootstrap.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/release-line-bootstrap");
 }
@@ -244,6 +247,17 @@ for (const requiredSnippet of [
     throw new Error(`packages/core/index.js must export Build Facts API: ${requiredSnippet}`);
   }
 }
+for (const requiredSnippet of [
+  "detectKfd3Surfaces",
+  "registerKfd3Surfaces",
+  "auditKfd3Surfaces",
+  "createKfd3SurfaceWitness",
+  "queryKfd3Capabilities",
+]) {
+  if (!coreIndexSource.includes(requiredSnippet)) {
+    throw new Error(`packages/core/index.js must export KFD-3 surface API: ${requiredSnippet}`);
+  }
+}
 for (const requiredSnippet of [
   "collectBadgeBundleFacts",
   "renderBadgeBundleBlock",

package/scripts/generate-site-bundle.mjs

@@ -308,6 +308,11 @@ function buildSiteBundle() {
     ["span", "Run a command inside a Buildchain log span."],
     ["diagnostics-summary", "Summarize diagnostics artifacts into JSON and cross-platform lifecycle timing tables."],
     ["build-facts", "Collect and verify Git source, version, module output, product artifact, and legacy Kungfu buildinfo facts."],
+    ["kfd-3-detect", "Detect standard KFD-3 public surface candidates from source and artifact metadata."],
+    ["kfd-3-register", "Declare detected KFD-3 public surfaces into a product-owned surface registry."],
+    ["kfd-3-audit", "Compare detected, declared, and enforced KFD-3 public surfaces."],
+    ["kfd-3-witness", "Generate release-passport-compatible KFD-3 surface witnesses from a product registry."],
+    ["kfd-3-query", "Return an agent-readable KFD-3 capability map for a product, registry, or release passport."],
     ["sample-process-tree", "Sample process-tree diagnostics for a wrapped command."],
     ["npm-dry-run", "Verify npm publish shape before a release transaction."],
     ["infra-contract", "Validate and publish provider-neutral infrastructure contract evidence."],
@@ -348,6 +353,7 @@ function buildSiteBundle() {
       "docs/install.md",
       "docs/cli.md",
       "docs/build-facts.md",
+      "docs/kfd-support.md",
       "docs/reusable-build-surface.md",
       "docs/release-candidate.md",
       "docs/release-governance.md",
@@ -394,6 +400,7 @@ function buildSiteBundle() {
     docs: [
       { id: "cli-and-node-package", path: "docs/cli.md", digest: sha256File("docs/cli.md") },
       { id: "build-facts", path: "docs/build-facts.md", digest: sha256File("docs/build-facts.md") },
+      { id: "kfd-support", path: "docs/kfd-support.md", digest: sha256File("docs/kfd-support.md") },
       { id: "readme-badges", path: "docs/readme-badges.md", digest: sha256File("docs/readme-badges.md") },
       { id: "homebrew", path: "docs/homebrew.md", digest: sha256File("docs/homebrew.md") },
       { id: "site-bundle-contract", path: "docs/site-bundle-contract.md", digest: sha256File("docs/site-bundle-contract.md") },

package/scripts/web-surface-core.mjs

@@ -324,70 +324,6 @@ function directoryIndexAliasOperations({ surfaceArtifactRoot, bucket, binding })
     });
 }
 
-function cloudfrontDefaultRootObjectOperation({ distributionId, directoryIndex = "index.html" }) {
-  const normalizedDistribution = String(distributionId || "").trim();
-  const normalizedDirectoryIndex = normalizeS3Key(directoryIndex || "index.html");
-  if (!normalizedDistribution || !normalizedDirectoryIndex || normalizedDirectoryIndex.includes("/")) {
-    return null;
-  }
-  return {
-    action: "ensure-cloudfront-default-root-object",
-    surface: "__distribution__",
-    command: "bash",
-    args: [
-      "-euo",
-      "pipefail",
-      "-c",
-      [
-        'distribution_id="$1"',
-        'root_object="$2"',
-        'tmp_dir="$(mktemp -d)"',
-        'trap \'rm -rf "$tmp_dir"\' EXIT',
-        'aws cloudfront get-distribution-config --id "$distribution_id" > "$tmp_dir/distribution.json"',
-        'etag="$(jq -r \'.ETag\' "$tmp_dir/distribution.json")"',
-        'current="$(jq -r \'.DistributionConfig.DefaultRootObject // ""\' "$tmp_dir/distribution.json")"',
-        'if [ "$current" = "$root_object" ]; then',
-        '  echo "cloudfront default root object already $root_object for $distribution_id"',
-        '  exit 0',
-        'fi',
-        'jq --arg root "$root_object" \'.DistributionConfig | .DefaultRootObject = $root\' "$tmp_dir/distribution.json" > "$tmp_dir/distribution-config.json"',
-        'aws cloudfront update-distribution --id "$distribution_id" --if-match "$etag" --distribution-config "file://$tmp_dir/distribution-config.json" >/dev/null',
-        'aws cloudfront wait distribution-deployed --id "$distribution_id"',
-        'echo "cloudfront default root object set to $root_object for $distribution_id"',
-      ].join("\n"),
-      "buildchain-cloudfront-default-root-object",
-      normalizedDistribution,
-      normalizedDirectoryIndex,
-    ],
-    routing: {
-      contract: "kungfu-buildchain-web-surface-cloudfront-default-root-object",
-      distributionId: normalizedDistribution,
-      defaultRootObject: normalizedDirectoryIndex,
-      reason: "Surface host root requests must resolve to index.html before host/path prefix rewrite reaches the S3 origin.",
-    },
-  };
-}
-
-function cloudfrontDefaultRootObjectOperations({ bindings }) {
-  const seen = new Set();
-  return (bindings || []).flatMap((binding) => {
-    if (binding.directoryIndexResolution === false || !binding.distributionId) {
-      return [];
-    }
-    const directoryIndex = binding.directoryIndex || "index.html";
-    const key = `${binding.distributionId}:${directoryIndex}`;
-    if (seen.has(key)) {
-      return [];
-    }
-    seen.add(key);
-    const operation = cloudfrontDefaultRootObjectOperation({
-      distributionId: binding.distributionId,
-      directoryIndex,
-    });
-    return operation ? [operation] : [];
-  });
-}
-
 function defaultCommandRunner({ command, args, stdin = "" }) {
   const result = spawnSync(command, args, {
     encoding: "utf8",
@@ -1006,7 +942,6 @@ export function applyWebSurfaceDeploy({
     }
   }
   const operations = [
-    ...cloudfrontDefaultRootObjectOperations({ bindings }),
     ...bindings.flatMap((binding) => deployBindingOperations({
       artifactRoot,
       deployConfig,
@@ -1495,12 +1430,6 @@ function deployBindingOperations({ artifactRoot, deployConfig, manifest, binding
 function planAdapterSteps(adapter, deployConfig, manifest) {
   if (adapter === "aws-s3-cloudfront") {
     return [
-      ...cloudfrontDefaultRootObjectOperations({ bindings: manifest.surfaceBindings }).map((operation) => ({
-        action: operation.action,
-        surface: operation.surface,
-        distribution: operation.routing.distributionId,
-        defaultRootObject: operation.routing.defaultRootObject,
-      })),
       ...manifest.surfaceBindings.flatMap((binding) => [
         {
           action: "sync-static-artifact",

package/scripts/web-surface.mjs

@@ -50,10 +50,59 @@ function readJsonFileArg(name) {
 
 function assertApplySucceeded(result) {
   if (result.status === "failed") {
+    printApplyFailureSummary(result);
     throw new Error(`web-surface ${result.contract} failed; see apply result for operation details`);
   }
 }
 
+function operationFailureSummary(result) {
+  const failed = (result.operations || []).find((operation) => operation.status === "failed");
+  if (!failed) {
+    return "";
+  }
+  const stderr = String(failed.stderr || "").trim();
+  const stdout = String(failed.stdout || "").trim();
+  return [
+    `web-surface failed operation: ${failed.action || "unknown"}`,
+    `surface: ${failed.surface || "unknown"}`,
+    failed.command ? `command: ${failed.command} ${(failed.args || []).join(" ")}` : "",
+    failed.exitCode !== null && failed.exitCode !== undefined ? `exitCode: ${failed.exitCode}` : "",
+    stderr ? `stderr: ${stderr}` : "",
+    stdout ? `stdout: ${stdout}` : "",
+  ].filter(Boolean).join("\n");
+}
+
+function printApplyFailureSummary(result) {
+  const summary = operationFailureSummary(result);
+  if (summary) {
+    console.error(summary);
+  }
+}
+
+function writeFailureResult({ output, mode, cwd, error }) {
+  if (!output) {
+    return null;
+  }
+  const resolvedOutput = path.resolve(output);
+  if (fs.existsSync(resolvedOutput)) {
+    return JSON.parse(fs.readFileSync(resolvedOutput, "utf8"));
+  }
+  const result = {
+    schemaVersion: 1,
+    contract: mode === "cleanup-apply"
+      ? "kungfu-buildchain-web-surface-cleanup-apply"
+      : "kungfu-buildchain-web-surface-deploy-apply",
+    status: "failed",
+    error: {
+      message: String(error?.message || error),
+    },
+    cwd,
+    generatedAt: new Date().toISOString(),
+  };
+  writeJson(result, resolvedOutput);
+  return result;
+}
+
 export function webSurfaceCli() {
   const mode = readArg("mode", process.env.BUILDCHAIN_WEB_SURFACE_MODE || "validate");
   const cwd = readArg("cwd", process.env.BUILDCHAIN_WORKDIR || process.cwd());
@@ -120,34 +169,39 @@ export function webSurfaceCli() {
       "published-at",
       process.env.BUILDCHAIN_SITE_PUBLISHED_AT || process.env.BUILDCHAIN_SURFACE_PUBLISHED_AT || "",
     );
-    const result = applyWebSurfaceDeploy({
-      cwd,
-      channel,
-      alias,
-      sourceSha,
-      artifactHash: readArg("artifact-hash", process.env.BUILDCHAIN_WEB_SURFACE_ARTIFACT_HASH || ""),
-      artifactPath: readArg("artifact-path", process.env.BUILDCHAIN_WEB_SURFACE_ARTIFACT_PATH || ""),
-      plan,
-      dryRun: readBooleanArg("dry-run", true),
-      actor: readArg("actor", process.env.GITHUB_ACTOR || ""),
-      runId: readArg("run-id", process.env.GITHUB_RUN_ID || ""),
-      ...(publishedAt ? { appliedAt: publishedAt } : {}),
-    });
-    writeJson(result, output);
-    writeGitHubOutputs({
-      "web-surface-channel": result.channel,
-      "web-surface-alias": result.alias,
-      "web-surface-url": result.url,
-      "web-surface-urls-json": JSON.stringify(result.urls || {}),
-      "web-surface-artifact-hash": result.artifactHash,
-      "web-surface-apply-mode": result.applyMode,
-      "web-surface-apply-status": result.status,
-      "web-surface-manifest-json": JSON.stringify(result.manifest),
-      "web-surface-bindings-json": JSON.stringify(result.surfaceBindings || []),
-      "web-surface-apply-result-json": JSON.stringify(result),
-    });
-    assertApplySucceeded(result);
-    return result;
+    try {
+      const result = applyWebSurfaceDeploy({
+        cwd,
+        channel,
+        alias,
+        sourceSha,
+        artifactHash: readArg("artifact-hash", process.env.BUILDCHAIN_WEB_SURFACE_ARTIFACT_HASH || ""),
+        artifactPath: readArg("artifact-path", process.env.BUILDCHAIN_WEB_SURFACE_ARTIFACT_PATH || ""),
+        plan,
+        dryRun: readBooleanArg("dry-run", true),
+        actor: readArg("actor", process.env.GITHUB_ACTOR || ""),
+        runId: readArg("run-id", process.env.GITHUB_RUN_ID || ""),
+        ...(publishedAt ? { appliedAt: publishedAt } : {}),
+      });
+      writeJson(result, output);
+      writeGitHubOutputs({
+        "web-surface-channel": result.channel,
+        "web-surface-alias": result.alias,
+        "web-surface-url": result.url,
+        "web-surface-urls-json": JSON.stringify(result.urls || {}),
+        "web-surface-artifact-hash": result.artifactHash,
+        "web-surface-apply-mode": result.applyMode,
+        "web-surface-apply-status": result.status,
+        "web-surface-manifest-json": JSON.stringify(result.manifest),
+        "web-surface-bindings-json": JSON.stringify(result.surfaceBindings || []),
+        "web-surface-apply-result-json": JSON.stringify(result),
+      });
+      assertApplySucceeded(result);
+      return result;
+    } catch (error) {
+      writeFailureResult({ output, mode, cwd, error });
+      throw error;
+    }
   }
 
   if (mode === "production-preflight") {