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

package/README.md

@@ -104,6 +104,9 @@ Buildchain v2 ships these active surfaces:
   commands, trusted event gating, artifact name templates, expected artifact
   checks, deterministic artifact 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;
 - `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/lifecycle-protocol.md

@@ -287,7 +287,8 @@ noindex = true
 [channels.staging]
 url = "https://staging.kungfu.tech"
 visibility = "protected"
-requires_auth = true
+access_control = "managed-network"
+edge_auth = "none"
 noindex = true
 promotable = true
 

package/docs/web-surface-deployments.md

@@ -42,7 +42,8 @@ noindex = true
 [channels.staging]
 url = "https://staging.kungfu.tech"
 visibility = "protected"
-requires_auth = true
+access_control = "managed-network"
+edge_auth = "none"
 noindex = true
 promotable = true
 
@@ -64,7 +65,11 @@ Buildchain validates these hard constraints:
 
 - `channels.preview.url_pattern` is required and must contain the alias shape
   used by preview deployments.
-- `channels.staging.requires_auth = true` is required.
+- `channels.staging.access_control` must protect staging. Supported modes are
+  `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.
+- `channels.staging.edge_auth` records whether the edge layer owns auth. Use
+  `edge_auth = "none"` when staging is protected by managed network controls
+  such as WAF/IP allowlists or VPN access.
 - `channels.staging.noindex = true` is required.
 - `channels.production.url` is required.
 - deploy adapters must be declared per channel.
@@ -122,6 +127,9 @@ rollback:
   "deployedAt": "2026-07-01T00:00:00.000Z",
   "retentionClass": "preview-sha-immutable",
   "expiresAt": "2026-09-29T00:00:00.000Z",
+  "accessControl": "none",
+  "edgeAuth": "none",
+  "noindex": true,
   "secretRefs": ["AWS_ROLE_ARN"]
 }
 ```
@@ -166,17 +174,54 @@ The CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:
 
 ## Cleanup Plans
 
-Preview cleanup is also a dry-run plan:
+Preview cleanup is an auditable cleanup contract. It can run as a dry-run plan
+or as an apply-mode plan for the caller workflow to execute with preview-only
+credentials:
 
 ```bash
 node scripts/web-surface.mjs \
   --mode cleanup-plan \
   --cwd fixtures/web-surface-shaped \
+  --event pull-request-closed \
+  --pull-number 123 \
   --aliases pr-123,sha-abcdef123456
 ```
 
 The plan keeps mutable PR aliases and immutable SHA aliases distinct so a caller
-can expire them with different retention windows.
+can expire them with different retention windows. Closed-PR cleanup can derive
+`pr-N` from `--pull-number`, records the event, source SHA, actor, run id,
+preview bucket/prefix, manifest key, and adapter steps, and is an auditable
+no-op when no aliases are requested.
+
+## Reusable Workflow Shape
+
+Buildchain ships `.github/workflows/.web-surface.yml` for repositories that want
+the standard PR review and promotion flow without copying bespoke glue:
+
+```yaml
+jobs:
+  web-surface:
+    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
+    with:
+      buildchain-ref: v2
+      build-command: npm run build
+      verify-command: npm run check
+      artifact-path: dist
+```
+
+The reusable workflow maps GitHub events to Buildchain web-surface semantics:
+
+| Event | Buildchain behavior |
+| --- | --- |
+| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |
+| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |
+| `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; live AWS mutation still
+belongs to the caller's controlled deploy step or a later adapter apply
+implementation. This keeps production from being an implicit side effect of
+merging to `main`.
 
 ## Site Repository Shape
 
@@ -208,4 +253,3 @@ Buildchain does not currently perform live AWS mutations for web surfaces.
 Production deploy, DNS changes, staging auth implementation, CloudFront
 distribution creation, and credential provisioning remain explicitly authorized
 operations outside the dry-run contract.
-

package/package.json

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

package/packages/core/buildchain-config.js

@@ -12,6 +12,8 @@ const SUPPORTED_VERSION_NEXT = new Set(["auto", "manual"]);
 const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface"]);
 const WEB_SURFACE_CHANNELS = ["preview", "staging", "production"];
 const SUPPORTED_CHANNEL_VISIBILITY = new Set(["ephemeral", "protected", "public", "internal"]);
+const SUPPORTED_ACCESS_CONTROL = new Set(["none", "managed-network", "edge-basic-auth", "oidc", "app-auth"]);
+const SUPPORTED_EDGE_AUTH = new Set(["none", "cloudfront-basic-auth", "oidc", "app-auth"]);
 const SUPPORTED_DEPLOY_ADAPTERS = new Set([
   "aws-s3-cloudfront",
   "aws-elastic-beanstalk",
@@ -159,13 +161,18 @@ function normalizeChannelConfig(name, channel) {
   if (!SUPPORTED_CHANNEL_VISIBILITY.has(visibility)) {
     throw new Error(`channels.${name}.visibility must be one of ephemeral, protected, public, or internal`);
   }
+  const accessControl = normalizeAccessControl(channel, name);
+  const edgeAuth = normalizeEdgeAuth(channel, name, accessControl);
   const normalized = {
     name,
     visibility,
-    requiresAuth: optionalBoolean(channel.requires_auth, name === "staging"),
+    requiresAuth: optionalBoolean(channel.requires_auth, accessControl !== "none"),
+    requiresControlledAccess: accessControl !== "none",
     noindex: optionalBoolean(channel.noindex, name !== "production"),
     promotable: optionalBoolean(channel.promotable, name === "staging"),
     canonical: optionalBoolean(channel.canonical, name === "production"),
+    accessControl,
+    edgeAuth,
   };
   if (hasUrl) {
     normalized.url = assertString(channel.url, `channels.${name}.url`);
@@ -176,6 +183,36 @@ function normalizeChannelConfig(name, channel) {
   return normalized;
 }
 
+function normalizeAccessControl(channel, name) {
+  if (channel.access_control !== undefined) {
+    const accessControl = assertString(channel.access_control, `channels.${name}.access_control`);
+    if (!SUPPORTED_ACCESS_CONTROL.has(accessControl)) {
+      throw new Error(`channels.${name}.access_control must be one of none, managed-network, edge-basic-auth, oidc, or app-auth`);
+    }
+    return accessControl;
+  }
+  if (name === "staging") {
+    return "edge-basic-auth";
+  }
+  if (name === "production") {
+    return "none";
+  }
+  return "none";
+}
+
+function normalizeEdgeAuth(channel, name, accessControl) {
+  if (channel.edge_auth !== undefined) {
+    const edgeAuth = assertString(channel.edge_auth, `channels.${name}.edge_auth`);
+    if (!SUPPORTED_EDGE_AUTH.has(edgeAuth)) {
+      throw new Error(`channels.${name}.edge_auth must be one of none, cloudfront-basic-auth, oidc, or app-auth`);
+    }
+    return edgeAuth;
+  }
+  return accessControl === "edge-basic-auth"
+    ? "cloudfront-basic-auth"
+    : "none";
+}
+
 function defaultChannelVisibility(name) {
   if (name === "preview") {
     return "ephemeral";
@@ -290,17 +327,20 @@ function validateWebSurfaceConfig(config) {
       throw new Error(`channels.${name}.url is required for web-surface`);
     }
   }
-  if (!config.channels.staging.requiresAuth) {
-    throw new Error("channels.staging.requires_auth must be true for web-surface");
+  if (config.channels.staging.visibility === "public") {
+    throw new Error("channels.staging.visibility must not be public for web-surface");
+  }
+  if (config.channels.staging.accessControl === "none") {
+    throw new Error("channels.staging.access_control must protect staging for web-surface");
+  }
+  if (config.channels.staging.accessControl === "edge-basic-auth" && config.channels.staging.edgeAuth === "none") {
+    throw new Error("channels.staging.edge_auth must not be none when access_control = edge-basic-auth");
   }
   if (!config.channels.staging.noindex) {
     throw new Error("channels.staging.noindex must be true for web-surface");
   }
   const stagingSecurity = config.security?.staging;
   if (stagingSecurity) {
-    if (stagingSecurity.requiresAuth === false) {
-      throw new Error("security.staging.requires_auth must not disable staging auth");
-    }
     if (stagingSecurity.noindex === false) {
       throw new Error("security.staging.noindex must not disable staging noindex");
     }
@@ -624,6 +664,9 @@ export function validateBuildchainConfig(
             {
               visibility: channel.visibility,
               requiresAuth: channel.requiresAuth,
+              requiresControlledAccess: channel.requiresControlledAccess,
+              accessControl: channel.accessControl,
+              edgeAuth: channel.edgeAuth,
               noindex: channel.noindex,
               promotable: channel.promotable,
               canonical: channel.canonical,

package/scripts/init-repo.mjs

@@ -163,7 +163,8 @@ noindex = true
 [channels.staging]
 url = "https://staging.example.com"
 visibility = "protected"
-requires_auth = true
+access_control = "managed-network"
+edge_auth = "none"
 noindex = true
 promotable = true
 
@@ -193,7 +194,6 @@ bucket_ref = "AWS_PRODUCTION_BUCKET"
 distribution_ref = "AWS_PRODUCTION_DISTRIBUTION"
 
 [security.staging]
-requires_auth = true
 noindex = true
 isolated_providers = true
 

package/scripts/web-surface-core.mjs

@@ -116,6 +116,14 @@ function resolveChannelUrl(channel, alias) {
   return channel.url;
 }
 
+function manifestPrefixFor(deployConfig) {
+  return deployConfig.manifest_prefix || ".buildchain/deployments";
+}
+
+function objectPrefixFor(deployConfig, alias) {
+  return deployConfig.prefix || alias || "preview";
+}
+
 function retentionFor({ config, channelName, alias, deployedAt }) {
   if (channelName === "preview") {
     const classified = classifyPreviewAlias(alias);
@@ -224,6 +232,11 @@ export function createWebSurfaceDeploymentManifest({
     retentionClass: retention.retentionClass,
     expiresAt: retention.expiresAt,
     mutableAlias: retention.mutableAlias,
+    accessControl: channelConfig.accessControl,
+    edgeAuth: channelConfig.edgeAuth,
+    noindex: channelConfig.noindex,
+    promotable: channelConfig.promotable,
+    canonical: channelConfig.canonical,
     runtimeId,
     configFingerprint,
     secretRefs: [
@@ -296,11 +309,11 @@ function planAdapterSteps(adapter, deployConfig, manifest) {
       {
         action: "sync-static-artifact",
         target: deployConfig.bucket || deployConfig.target || "",
-        prefix: deployConfig.prefix || manifest.alias || manifest.channel,
+        prefix: objectPrefixFor(deployConfig, manifest.alias || manifest.channel),
       },
       {
         action: "write-deployment-manifest",
-        target: deployConfig.manifest_prefix || ".buildchain/deployments",
+        target: manifestPrefixFor(deployConfig),
       },
       {
         action: "invalidate-cdn",
@@ -315,7 +328,7 @@ function planAdapterSteps(adapter, deployConfig, manifest) {
     },
     {
       action: "write-deployment-manifest",
-      target: deployConfig.manifest_prefix || ".buildchain/deployments",
+      target: manifestPrefixFor(deployConfig),
     },
   ];
 }
@@ -325,37 +338,100 @@ export function planWebSurfaceCleanup({
   aliases = [],
   channel = "preview",
   now = new Date().toISOString(),
+  event = "manual",
+  sourceSha = "",
+  pullNumber = "",
+  actor = "",
+  runId = "",
   dryRun = true,
 } = {}) {
-  if (!dryRun) {
-    throw new Error("web-surface cleanup currently supports dry-run planning only");
-  }
   const loadedConfig = loadBuildchainConfig(cwd);
   const config = assertWebSurfaceConfig(loadedConfig);
   if (channel !== "preview") {
-    throw new Error("web-surface cleanup plan currently supports preview aliases only");
+    throw new Error("web-surface cleanup currently supports preview aliases only");
+  }
+  const deployConfig = config.deploy?.[channel];
+  if (!deployConfig) {
+    throw new Error(`missing deploy.${channel}`);
+  }
+  const requestedAliases = [...aliases];
+  if (requestedAliases.length === 0 && pullNumber) {
+    requestedAliases.push(`pr-${pullNumber}`);
   }
+  const manifestPrefix = manifestPrefixFor(deployConfig);
   return {
     schemaVersion: 1,
     contract: "kungfu-buildchain-web-surface-cleanup-plan",
-    dryRun: true,
+    dryRun,
+    applyMode: dryRun ? "dry-run" : "apply",
+    event,
     channel,
     now,
-    entries: aliases.map((alias) => {
+    sourceSha: sourceSha ? assertSha(sourceSha, "sourceSha") : "",
+    pullNumber: pullNumber ? String(pullNumber) : "",
+    actor,
+    runId,
+    status: requestedAliases.length === 0 ? "no-op" : "planned",
+    adapter: deployConfig.adapter,
+    target: deployConfig.bucket || deployConfig.target || "",
+    manifestPrefix,
+    secretRefs: [...new Set([...(deployConfig.secretRefs || [])])],
+    entries: requestedAliases.map((alias) => {
       const classified = classifyPreviewAlias(alias);
       const retention = retentionConfig(config, "preview");
+      const objectPrefix = objectPrefixFor(deployConfig, alias);
       return {
         alias,
         aliasKind: classified.kind,
         mutableAlias: classified.mutable,
         retentionClass: classified.retentionClass,
         retentionDays: retention[classified.retentionKey],
-        action: "expire-preview-alias",
+        action: "delete-preview-alias",
+        objectPrefix,
+        manifestKey: `${manifestPrefix.replace(/\/$/, "")}/${alias}.json`,
+        steps: cleanupAdapterSteps(deployConfig.adapter, deployConfig, {
+          alias,
+          objectPrefix,
+          manifestPrefix,
+        }),
       };
     }),
   };
 }
 
+function cleanupAdapterSteps(adapter, deployConfig, entry) {
+  if (adapter === "aws-s3-cloudfront") {
+    return [
+      {
+        action: "delete-static-prefix",
+        target: deployConfig.bucket || deployConfig.target || "",
+        prefix: entry.objectPrefix,
+      },
+      {
+        action: "delete-deployment-manifest",
+        target: entry.manifestPrefix,
+        key: `${entry.manifestPrefix.replace(/\/$/, "")}/${entry.alias}.json`,
+      },
+      {
+        action: "invalidate-cdn",
+        distribution: deployConfig.cloudfront_distribution || deployConfig.distribution || "",
+      },
+    ];
+  }
+  return [
+    {
+      action: "delete-preview-environment",
+      target: deployConfig.environment || deployConfig.service || deployConfig.target || "",
+      alias: entry.alias,
+    },
+    {
+      action: "delete-deployment-manifest",
+      target: entry.manifestPrefix,
+      key: `${entry.manifestPrefix.replace(/\/$/, "")}/${entry.alias}.json`,
+    },
+  ];
+}
+
 export function defaultWebSurfaceAlias({ channel = "preview", sourceSha = "", pullNumber = "" } = {}) {
   if (channel !== "preview") {
     return "";

package/scripts/web-surface.mjs

@@ -89,11 +89,18 @@ export function webSurfaceCli() {
       cwd,
       channel,
       aliases,
+      sourceSha,
+      pullNumber,
+      event: readArg("event", process.env.BUILDCHAIN_WEB_SURFACE_EVENT || "manual"),
+      actor: readArg("actor", process.env.GITHUB_ACTOR || ""),
+      runId: readArg("run-id", process.env.GITHUB_RUN_ID || ""),
       dryRun: readBooleanArg("dry-run", true),
     });
     writeJson(result, output);
     writeGitHubOutputs({
       "web-surface-cleanup-count": String(result.entries.length),
+      "web-surface-cleanup-mode": result.applyMode,
+      "web-surface-cleanup-status": result.status,
       "web-surface-cleanup-plan-json": JSON.stringify(result),
     });
     return result;