@kungfu-tech/buildchain 3.0.4-alpha.2 → 3.0.4-alpha.3

package/scripts/release-propagation.mjs

@@ -3,9 +3,17 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import {
+  claimReleasePropagationWork,
+  completeReleasePropagationWork,
   createReleasePropagationReceipt,
+  createReleasePropagationStageReceipt,
+  createReleasePropagationWork,
   planReleasePropagation,
   readReleasePropagationJson,
+  recordReleasePropagationStage,
+  repairReleasePropagationWork,
+  resumeReleasePropagationWork,
+  verifyReleasePropagationWork,
   writeReleasePropagationLock,
 } from "../packages/core/release-propagation.js";
 
@@ -25,6 +33,34 @@ function usage() {
                                          [--production-state <state>]
                                          [--observed-at <iso-8601>]
                                          [--output <file>] [--json]
+  buildchain release-propagation work create --plan <json-or-path>
+                                            --expected-downstream-base-sha <git-sha>
+                                            [--work-context <json-or-path>]
+                                            [--target <id-or-repo>]
+                                            [--output <file>] [--json]
+  buildchain release-propagation work status --work <json-or-path> [--json]
+  buildchain release-propagation work resume --work <json-or-path> [--json]
+  buildchain release-propagation work claim --work <json-or-path>
+                                           --authority <json-or-path>
+                                           --expected-work-root <sha256:...>
+                                           [--family-state <json-or-path>]
+                                           [--output <file>] [--json]
+  buildchain release-propagation work receipt --work <json-or-path>
+                                             --receipt-input <json-or-path>
+                                             [--output <file>] [--json]
+  buildchain release-propagation work record --work <json-or-path>
+                                            --receipt <json-or-path>
+                                            --expected-work-root <sha256:...>
+                                            [--output <file>] [--json]
+  buildchain release-propagation work repair --work <json-or-path>
+                                            --receipt <json-or-path>
+                                            --expected-work-root <sha256:...>
+                                            [--output <file>] [--json]
+  buildchain release-propagation work complete --work <json-or-path>
+                                              --receipt <json-or-path>
+                                              --completion-decision <json-or-path>
+                                              --expected-work-root <sha256:...>
+                                              [--output <file>] [--json]
 `;
 }
 
@@ -49,6 +85,92 @@ function writeOutput(filePath, value) {
   fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+function readJsonFlag(args, name) {
+  return readReleasePropagationJson(readFlag(args, name), {
+    label: `--${name}`,
+    cwd: process.cwd(),
+  });
+}
+
+function readOptionalJsonFlag(args, name) {
+  return args.includes(`--${name}`) ? readJsonFlag(args, name) : undefined;
+}
+
+function emitWorkResult(args, value, summary) {
+  writeOutput(readFlag(args, "output", ""), value);
+  if (hasFlag(args, "json")) {
+    printJson(value);
+  } else {
+    process.stdout.write(`${summary}\n`);
+  }
+}
+
+function runWorkCli(args) {
+  const [mode = "", ...workArgs] = args;
+  if (!mode || mode === "--help" || mode === "-h") {
+    process.stdout.write(usage());
+    return;
+  }
+  if (mode === "create") {
+    const result = createReleasePropagationWork({
+      plan: readJsonFlag(workArgs, "plan"),
+      target: readFlag(workArgs, "target", ""),
+      workContext: readOptionalJsonFlag(workArgs, "work-context"),
+      expectedDownstreamBaseSha: readFlag(workArgs, "expected-downstream-base-sha"),
+    });
+    emitWorkResult(workArgs, result, `release propagation work: ${result.contentRoot}`);
+    return;
+  }
+  if (mode === "status" || mode === "resume") {
+    const work = readJsonFlag(workArgs, "work");
+    const result = mode === "resume"
+      ? resumeReleasePropagationWork(work)
+      : verifyReleasePropagationWork(work);
+    emitWorkResult(workArgs, result, `release propagation next action: ${result.nextAction.action} ${result.currentStage}`);
+    return;
+  }
+  if (mode === "claim") {
+    const result = claimReleasePropagationWork({
+      work: readJsonFlag(workArgs, "work"),
+      authority: readJsonFlag(workArgs, "authority"),
+      familyState: readOptionalJsonFlag(workArgs, "family-state"),
+      expectedWorkRoot: readFlag(workArgs, "expected-work-root"),
+    });
+    emitWorkResult(workArgs, result, `release propagation work claimed: ${result.contentRoot}`);
+    return;
+  }
+  if (mode === "receipt") {
+    const work = readJsonFlag(workArgs, "work");
+    const input = readJsonFlag(workArgs, "receipt-input");
+    const result = createReleasePropagationStageReceipt({ work, ...input });
+    emitWorkResult(workArgs, result, `release propagation stage receipt: ${result.receiptRoot}`);
+    return;
+  }
+  if (mode === "record" || mode === "repair") {
+    const transition = {
+      work: readJsonFlag(workArgs, "work"),
+      receipt: readJsonFlag(workArgs, "receipt"),
+      expectedWorkRoot: readFlag(workArgs, "expected-work-root"),
+    };
+    const result = mode === "record"
+      ? recordReleasePropagationStage(transition)
+      : repairReleasePropagationWork(transition);
+    emitWorkResult(workArgs, result, `release propagation work advanced: ${result.contentRoot}`);
+    return;
+  }
+  if (mode === "complete") {
+    const result = completeReleasePropagationWork({
+      work: readJsonFlag(workArgs, "work"),
+      receipt: readJsonFlag(workArgs, "receipt"),
+      completionDecision: readJsonFlag(workArgs, "completion-decision"),
+      expectedWorkRoot: readFlag(workArgs, "expected-work-root"),
+    });
+    emitWorkResult(workArgs, result, `release propagation work complete: ${result.contentRoot}`);
+    return;
+  }
+  throw new Error(`unsupported release-propagation work command: ${mode}`);
+}
+
 export function runReleasePropagationCli(argv = process.argv.slice(2)) {
   const [mode = "", ...args] = argv;
   if (!mode || mode === "--help" || mode === "-h") {
@@ -80,6 +202,10 @@ export function runReleasePropagationCli(argv = process.argv.slice(2)) {
     }
     return;
   }
+  if (mode === "work") {
+    runWorkCli(args);
+    return;
+  }
   if (mode === "write-lock") {
     const plan = readReleasePropagationJson(readFlag(args, "plan"), {
       label: "--plan",

package/scripts/resolve-artifact-transfer-mode.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const VALID_MODES = new Set(["github-artifacts", "s3-to-github-artifacts"]);
+
+function firstValue(...values) {
+  return values.find((value) => String(value || "").trim()) || "";
+}
+
+function resolveArtifactTransferMode(env = process.env) {
+  const mode = env.INPUT_TRANSFER_MODE || "github-artifacts";
+  if (!VALID_MODES.has(mode)) {
+    throw new Error(
+      `artifact-transfer-mode must be github-artifacts or s3-to-github-artifacts, got: ${mode}`,
+    );
+  }
+  if (mode === "github-artifacts") {
+    return {
+      mode,
+      s3Bucket: "",
+      s3Region: "",
+      s3Prefix: "",
+      oidcAudience: "",
+    };
+  }
+  const s3Bucket = firstValue(env.INPUT_S3_BUCKET, env.VAR_S3_BUCKET);
+  const s3Region = firstValue(env.INPUT_S3_REGION, env.VAR_S3_REGION);
+  const s3Prefix = firstValue(
+    env.INPUT_S3_PREFIX,
+    env.VAR_S3_PREFIX,
+    "buildchain-artifacts",
+  );
+  const uploadRole = firstValue(
+    env.INPUT_S3_UPLOAD_ROLE_ARN,
+    env.VAR_S3_UPLOAD_ROLE_ARN,
+    env.SECRET_S3_UPLOAD_ROLE_ARN,
+    env.INPUT_S3_ROLE_ARN,
+    env.VAR_S3_ROLE_ARN,
+    env.SECRET_S3_ROLE_ARN,
+  );
+  const downloadRole = firstValue(
+    env.INPUT_S3_DOWNLOAD_ROLE_ARN,
+    env.VAR_S3_DOWNLOAD_ROLE_ARN,
+    env.SECRET_S3_DOWNLOAD_ROLE_ARN,
+    env.INPUT_S3_ROLE_ARN,
+    env.VAR_S3_ROLE_ARN,
+    env.SECRET_S3_ROLE_ARN,
+  );
+  if (!s3Bucket) {
+    throw new Error(
+      "artifact-transfer-mode=s3-to-github-artifacts requires artifact-relay-s3-bucket or BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET",
+    );
+  }
+  if (!s3Region) {
+    throw new Error(
+      "artifact-transfer-mode=s3-to-github-artifacts requires artifact-relay-s3-region or BUILDCHAIN_ARTIFACT_RELAY_S3_REGION",
+    );
+  }
+  if (!uploadRole) {
+    throw new Error(
+      "artifact-transfer-mode=s3-to-github-artifacts requires an upload role ARN input, variable, or secret",
+    );
+  }
+  if (!downloadRole) {
+    throw new Error(
+      "artifact-transfer-mode=s3-to-github-artifacts requires a download role ARN input, variable, or secret",
+    );
+  }
+  const oidcAudience = firstValue(
+    env.INPUT_OIDC_AUDIENCE,
+    env.VAR_OIDC_AUDIENCE,
+    s3Region.startsWith("cn-") ? "sts.amazonaws.com.cn" : "sts.amazonaws.com",
+  );
+  return { mode, s3Bucket, s3Region, s3Prefix, oidcAudience };
+}
+
+function writeArtifactTransferOutputs(outputPath, resolution) {
+  if (!outputPath) {
+    throw new Error("GITHUB_OUTPUT is required");
+  }
+  fs.mkdirSync(path.dirname(path.resolve(outputPath)), { recursive: true });
+  fs.appendFileSync(
+    outputPath,
+    [
+      `mode=${resolution.mode}`,
+      `s3-bucket=${resolution.s3Bucket}`,
+      `s3-region=${resolution.s3Region}`,
+      `s3-prefix=${resolution.s3Prefix}`,
+      `oidc-audience=${resolution.oidcAudience}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+function main() {
+  const resolution = resolveArtifactTransferMode();
+  writeArtifactTransferOutputs(process.env.GITHUB_OUTPUT, resolution);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(
+      `::error::${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exitCode = 1;
+  }
+}
+
+export { resolveArtifactTransferMode, writeArtifactTransferOutputs };

package/scripts/web-surface-core.mjs

@@ -9,6 +9,29 @@ import { fileURLToPath } from "node:url";
 import { loadBuildchainConfig, validateBuildchainConfig } from "../packages/core/buildchain-config.js";
 import { createSurfaceTimestampPolicy } from "../packages/core/surface-manifest.js";
 import { validateInstallerPublication, verifyInstallerPublicReadback } from "./installer-publication.mjs";
+import {
+  classifyPreviewAlias,
+  resolveChannelUrl,
+  resolvePathOnlyUrl,
+  resolveSurfaceUrl,
+  manifestPrefixFor,
+  objectPrefixFor,
+  normalizeSurfacePath,
+  surfaceDeployConfig,
+  surfaceObjectPrefixFor,
+  normalizeS3Key,
+  joinS3Key,
+  joinUrlPath,
+  urlWithPath,
+  s3Uri,
+  cdnPath,
+  cdnWildcardPath,
+  viewerWildcardPath,
+  surfaceArtifactPrefix,
+  surfaceArtifactRootFor,
+  syncStaticArtifactArgs,
+  mutableCacheControlArgs,
+} from "./web-surface-routing.mjs";
 
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
@@ -89,231 +112,47 @@ function retentionConfig(config, channel) {
   };
 }
 
-function classifyPreviewAlias(alias) {
-  if (/^pr-\d+$/.test(alias)) {
-    return {
-      kind: "pr",
-      mutable: true,
-      retentionClass: "preview-pr-ephemeral",
-      retentionKey: "pr_days",
-    };
-  }
-  if (/^sha-[0-9a-f]{6,40}$/i.test(alias)) {
-    return {
-      kind: "sha",
-      mutable: false,
-      retentionClass: "preview-sha-immutable",
-      retentionKey: "sha_days",
-    };
-  }
-  return {
-    kind: "custom",
-    mutable: true,
-    retentionClass: "preview-custom-ephemeral",
-    retentionKey: "pr_days",
-  };
-}
 
-function resolveChannelUrl(channel, alias) {
-  if (channel.urlPattern) {
-    if (!alias) {
-      throw new Error(`channel ${channel.name} requires alias for url_pattern`);
-    }
-    return channel.urlPattern.replaceAll("{alias}", alias);
-  }
-  return channel.url;
-}
 
-function resolvePathOnlyUrl(channel, sourcePath, alias) {
-  const base = resolveChannelUrl(channel, alias);
-  const url = new URL(base);
-  const normalizedPath = normalizeSurfacePath(sourcePath);
-  if (normalizedPath === "/") {
-    return `${url.origin}/`;
-  }
-  return new URL(normalizedPath.replace(/^\//, ""), `${url.origin}/`).toString();
-}
 
-function resolveSurfaceUrl({ surface, channel, channelName, alias }) {
-  if (channelName === "preview" && surface.previewUrlPattern) {
-    if (!alias) {
-      throw new Error(`surface ${surface.name} requires alias for preview_url_pattern`);
-    }
-    return surface.previewUrlPattern.replaceAll("{alias}", alias);
-  }
-  if (channelName === "staging" && surface.stagingUrl) {
-    return surface.stagingUrl;
-  }
-  if (channelName === "production" && surface.productionUrl) {
-    return surface.productionUrl;
-  }
-  if (surface.pathOnly) {
-    return resolvePathOnlyUrl(channel, surface.path, alias);
-  }
-  const key = channelName === "preview"
-    ? "preview_url_pattern"
-    : `${channelName}_url`;
-  throw new Error(`surfaces.${surface.name}.${key} is required for channel ${channelName}`);
-}
 
-function manifestPrefixFor(deployConfig) {
-  return deployConfig.manifest_prefix || ".buildchain/deployments";
-}
 
-function objectPrefixFor(deployConfig, alias) {
-  if (Object.hasOwn(deployConfig, "prefix")) {
-    return normalizeS3Key(deployConfig.prefix);
-  }
-  return alias || "preview";
-}
 
-function normalizeSurfacePath(value) {
-  const normalized = `/${String(value || "/").replace(/^\/+/, "")}`.replace(/\/{2,}/g, "/");
-  if (normalized === "/") {
-    return normalized;
-  }
-  return normalized.endsWith("/") ? normalized : `${normalized}/`;
-}
 
-function surfaceDeployConfig(deployConfig, surfaceName) {
-  const overrides = deployConfig.surfaces?.[surfaceName];
-  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) {
-    return deployConfig;
-  }
-  return {
-    ...deployConfig,
-    ...overrides,
-    cacheControl: deployConfig.cacheControl || overrides.cacheControl
-      ? { ...(deployConfig.cacheControl || {}), ...(overrides.cacheControl || {}) }
-      : undefined,
-    surfaces: deployConfig.surfaces,
-    secretRefs: [
-      ...new Set([
-        ...(deployConfig.secretRefs || []),
-        ...(Array.isArray(overrides.secretRefs) ? overrides.secretRefs : []),
-      ]),
-    ],
-    artifactPath: overrides.artifactPath || deployConfig.artifactPath,
-  };
-}
 
-function surfaceObjectPrefixFor({ deployConfig, surface, alias }) {
-  const effective = surfaceDeployConfig(deployConfig, surface.name);
-  if (Object.hasOwn(effective, "prefix")) {
-    return normalizeS3Key(effective.prefix);
-  }
-  const root = objectPrefixFor(deployConfig, alias);
-  const surfacePath = normalizeS3Key(surface.path);
-  if (!surfacePath) {
-    return root;
-  }
-  return joinS3Key(root, surfacePath);
-}
 
-function normalizeS3Key(value) {
-  return String(value || "")
-    .replace(/^\/+/, "")
-    .replace(/\/{2,}/g, "/")
-    .replace(/\/+$/, "");
-}
 
-function joinS3Key(...parts) {
-  return normalizeS3Key(parts.filter(Boolean).join("/"));
-}
 
-function joinUrlPath(...parts) {
-  const raw = parts.join("/");
-  const normalized = normalizeS3Key(raw);
-  if (!normalized) {
-    return "/";
-  }
-  return raw.endsWith("/") ? `/${normalized}/` : `/${normalized}`;
-}
 
-function urlWithPath(baseUrl, requestPath) {
-  const url = new URL(baseUrl);
-  url.pathname = joinUrlPath(requestPath);
-  url.search = "";
-  url.hash = "";
-  return url.toString();
-}
 
-function s3Uri(bucket, key = "") {
-  if (!bucket) {
-    throw new Error("aws-s3-cloudfront adapter requires a bucket or target");
-  }
-  const normalizedKey = normalizeS3Key(key);
-  return normalizedKey ? `s3://${bucket}/${normalizedKey}` : `s3://${bucket}`;
-}
 
-function cdnPath(value) {
-  const normalized = normalizeS3Key(value);
-  return normalized ? `/${normalized}` : "/";
-}
 
-function cdnWildcardPath(value) {
-  const normalized = normalizeS3Key(value);
-  return normalized ? `/${normalized}/*` : "/*";
-}
 
-function viewerWildcardPath(binding) {
-  try {
-    return cdnWildcardPath(new URL(binding.url).pathname);
-  } catch {
-    return cdnWildcardPath(binding.objectPrefix);
-  }
-}
 
-function surfaceArtifactPrefix(binding) {
-  return normalizeS3Key(binding.sourcePath);
-}
 
-function surfaceArtifactRootFor({ artifactRoot, binding }) {
-  const prefix = normalizeS3Key(binding.artifactPathPrefix || surfaceArtifactPrefix(binding));
-  const root = prefix ? path.join(artifactRoot, prefix) : artifactRoot;
-  if (fs.existsSync(root)) {
-    return root;
-  }
-  return artifactRoot;
-}
-
-function syncStaticArtifactArgs({ artifactRoot, bucket, objectPrefix, deleteExcludes = [], cacheControl = "" }) {
-  const args = ["s3", "sync", artifactRoot, s3Uri(bucket, objectPrefix), "--delete"];
-  if (!objectPrefix) {
-    args.push("--exclude", ".buildchain/*");
-  }
-  for (const pattern of deleteExcludes) {
-    args.push("--exclude", pattern);
-  }
-  if (cacheControl) {
-    args.push("--cache-control", cacheControl);
-  }
-  return args;
-}
-
-function mutableCacheControlArgs({ artifactRoot, bucket, objectPrefix, cacheControl = "", excludePatterns = [] }) {
-  if (!cacheControl) return [];
-  const args = [
-    "s3",
-    "cp",
-    artifactRoot,
-    s3Uri(bucket, objectPrefix),
-    "--recursive",
-    "--exclude",
-    "*",
-    "--include",
-    "*.html",
-    "--include",
-    "*.json",
-    "--include",
-    "*.xml",
-  ];
-  for (const pattern of excludePatterns) {
-    args.push("--exclude", pattern);
-  }
-  args.push("--cache-control", cacheControl);
-  return args;
-}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 const PUBLICATION_ARCHIVE_POLICY_CONTRACT = "kungfu-buildchain-publication-archive-policy";
 const OBSERVED_EVIDENCE_OWNERSHIP_CONTRACT = "kungfu-buildchain-observed-evidence-ownership";