@kungfu-tech/buildchain 2.0.15-alpha.1 → 2.0.15

package/README.md

@@ -106,8 +106,8 @@ Buildchain v2 ships these active surfaces:
   manifests, publish-gate source locks, resolved release manifests, and
   aggregate build summaries;
 - `.github/workflows/.web-surface.yml` as the reusable site/app surface for PR
-  preview plans, closed-PR preview cleanup plans, push-main staging promotion
-  plans, and explicit production environment gates;
+  preview plans and optional apply, closed-PR preview cleanup apply, push-main
+  staging apply, and explicit production environment gates;
 - `actions/run-lifecycle` for callers that need the same lifecycle/manifest
   contract inside their own workflows;
 - governance-closed self-promotion through `Buildchain Ref Promotion`.

package/docs/publish-transaction.md

@@ -236,6 +236,18 @@ stop in `finalizing` and output `finalization-needed=true`. A later run can
 resume from the same transaction state and complete ref movement without
 republishing matching artifacts.
 
+If finalization fails after an exact Git tag, a channel branch, or dev/alpha
+sync ref has already moved, the next run reads the durable `finalizing` state
+and continues from the recorded transaction. The current workflow SHA may be a
+version-state merge commit that contains or corresponds to the transaction's
+`release_material_sha`; it does not have to equal the original `source_sha` or
+the transaction `release_sha`. Exact tags are accepted when they already point
+at the transaction release/material SHA or the finalized channel head. Floating
+channel tags and dev/alpha refs are then retried idempotently, and the
+transaction is marked `complete` only after those public refs are consistent.
+An exact tag at an unrelated SHA is still a material conflict and blocks
+recovery.
+
 If finalization fails after an exact Git tag is created, the next run reads the
 durable `finalizing` state, verifies the exact tag points at the recorded
 release SHA, and retries the remaining floating refs. An exact tag at a

package/docs/web-surface-deployments.md

@@ -285,10 +285,55 @@ The reusable workflow maps GitHub events to Buildchain web-surface semantics:
 | `push` to `main` | validate, build, verify, and plan `staging` from the merged `main` SHA |
 | `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |
 
-The workflow deliberately plans and emits manifests by default. Callers that
-want live AWS mutation should invoke `deploy-apply` / `cleanup-apply` from a
-controlled deploy job with scoped credentials. This keeps production from being
-an implicit side effect of merging to `main`.
+The workflow deliberately plans and emits manifests by default. Live mutation is
+opt-in per channel:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+  pull-requests: write
+
+jobs:
+  web-surface:
+    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
+    with:
+      buildchain-ref: v2
+      build-command: pnpm run build
+      verify-command: pnpm run check
+      artifact-path: dist
+      preview-apply: true
+      preview-cleanup-apply: true
+      preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions
+      staging-apply: true
+      staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions
+      production-apply: false
+      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions
+      production-environment: production
+```
+
+When enabled, Buildchain owns the full release apply state machine:
+
+- PR preview deploys run `deploy-apply --dry-run false` with the preview role
+  and update a single idempotent PR comment.
+- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role
+  only.
+- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging
+  role.
+- Production runs only on `workflow_dispatch` when both `production-approved`
+  and `production-apply` are true, and the job is gated by the configured GitHub
+  Environment.
+
+Callers must grant `id-token: write` for OIDC role assumption. Preview comments
+also need `pull-requests: write`. The AWS roles remain caller-owned and should
+be scoped by channel: preview can mutate only preview resources, staging can
+mutate only staging resources, and production can mutate only production
+resources.
+
+Apply mode fails closed when the deploy config still contains placeholder AWS
+targets such as `pending-preview-distribution`. Planning can use placeholders
+for dry-run-only design work, but live apply requires concrete bucket and
+CloudFront distribution identifiers.
 
 ## Site Repository Shape
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.0.15-alpha.1",
+  "version": "2.0.15",
   "private": false,
   "description": "Kungfu Buildchain reusable workflows, release governance, and CLI tooling.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/scripts/web-surface-core.mjs

@@ -223,6 +223,31 @@ function appliedStatus({ dryRun, operations, noOp = false }) {
   return dryRun ? "planned" : "applied";
 }
 
+function isPlaceholderValue(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return (
+    normalized === "" ||
+    normalized === "pending" ||
+    normalized.startsWith("pending-") ||
+    normalized.startsWith("pending_") ||
+    normalized.includes("placeholder") ||
+    normalized.includes("example.")
+  );
+}
+
+function assertConcreteAwsDeployConfig({ deployConfig, channel, operation }) {
+  const bucket = deployConfig.bucket || deployConfig.target || "";
+  const distribution = deployConfig.cloudfront_distribution || deployConfig.distribution || "";
+  if (isPlaceholderValue(bucket)) {
+    throw new Error(`web-surface ${operation} apply requires concrete deploy.${channel}.bucket or deploy.${channel}.target`);
+  }
+  if (isPlaceholderValue(distribution)) {
+    throw new Error(
+      `web-surface ${operation} apply requires concrete deploy.${channel}.cloudfront_distribution or deploy.${channel}.distribution`,
+    );
+  }
+}
+
 function deployManifestKey(deployConfig, manifest) {
   return joinS3Key(manifestPrefixFor(deployConfig), `${manifest.alias || manifest.channel}.json`);
 }
@@ -485,6 +510,13 @@ export function applyWebSurfaceDeploy({
   if (resolvedPlan.adapter !== "aws-s3-cloudfront") {
     throw new Error(`web-surface deploy apply does not support adapter: ${resolvedPlan.adapter}`);
   }
+  if (!dryRun) {
+    assertConcreteAwsDeployConfig({
+      deployConfig,
+      channel: resolvedPlan.channel,
+      operation: "deploy",
+    });
+  }
   const bucket = deployConfig.bucket || deployConfig.target || "";
   const artifactRoot = path.resolve(cwd, resolvedPlan.artifact.path);
   const objectPrefix = objectPrefixFor(deployConfig, resolvedPlan.manifest.alias || resolvedPlan.manifest.channel);
@@ -669,6 +701,13 @@ export function applyWebSurfaceCleanup({
   if (cleanup.adapter !== "aws-s3-cloudfront") {
     throw new Error(`web-surface cleanup apply does not support adapter: ${cleanup.adapter}`);
   }
+  if (!dryRun) {
+    assertConcreteAwsDeployConfig({
+      deployConfig,
+      channel: cleanup.channel,
+      operation: "cleanup",
+    });
+  }
   const bucket = deployConfig.bucket || deployConfig.target || "";
   const operations = cleanup.entries.flatMap((entry) => {
     const entryOperations = [

package/scripts/web-surface.mjs

@@ -125,6 +125,7 @@ export function webSurfaceCli() {
       "web-surface-apply-mode": result.applyMode,
       "web-surface-apply-status": result.status,
       "web-surface-manifest-json": JSON.stringify(result.manifest),
+      "web-surface-apply-result-json": JSON.stringify(result),
     });
     assertApplySucceeded(result);
     return result;