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

package/docs/web-surface-deployments.md

@@ -139,11 +139,11 @@ Dynamic adapters can also fill `runtimeId`, `configFingerprint`,
 `rollbackLimitations`. Buildchain records secret reference names only, never
 secret values.
 
-## Dry-Run Deploy Plans
+## Deploy Plans
 
-The first implementation is deliberately dry-run only. It plans the adapter
-steps and writes manifest JSON, but it does not touch AWS, DNS, CloudFront, or
-deployment credentials.
+Deploy planning is the default behavior. It plans the adapter steps and writes
+manifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment
+credentials.
 
 ```bash
 node scripts/web-surface.mjs \
@@ -172,10 +172,77 @@ The CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:
 - `web-surface-artifact-hash`
 - `web-surface-manifest-json`
 
+## Explicit Apply
+
+`deploy-apply` and `cleanup-apply` are explicit execution modes for the
+`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;
+live AWS mutation requires `--dry-run false`.
+
+Deploy apply syncs the artifact, writes the deployment manifest, and invalidates
+CloudFront when a distribution id is configured:
+
+```bash
+node scripts/web-surface.mjs \
+  --mode deploy-apply \
+  --cwd fixtures/web-surface-shaped \
+  --channel staging \
+  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
+  --artifact-path dist \
+  --dry-run false \
+  --output .buildchain/web-surface-staging-apply.json
+```
+
+It can also execute a previously saved deploy plan. In that mode Buildchain
+recomputes the local artifact hash before running AWS commands and fails closed
+if the artifact no longer matches the saved plan:
+
+```bash
+node scripts/web-surface.mjs \
+  --mode deploy-apply \
+  --cwd fixtures/web-surface-shaped \
+  --plan .buildchain/web-surface-staging-plan.json \
+  --dry-run false \
+  --output .buildchain/web-surface-staging-apply.json
+```
+
+Cleanup apply deletes preview content, deletes the preview manifest, and
+invalidates CloudFront:
+
+```bash
+node scripts/web-surface.mjs \
+  --mode cleanup-apply \
+  --cwd fixtures/web-surface-shaped \
+  --event pull-request-closed \
+  --pull-number 123 \
+  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
+  --dry-run false \
+  --output .buildchain/web-surface-cleanup-apply.json
+```
+
+Cleanup apply can also execute a saved cleanup plan:
+
+```bash
+node scripts/web-surface.mjs \
+  --mode cleanup-apply \
+  --cwd fixtures/web-surface-shaped \
+  --plan .buildchain/web-surface-cleanup-plan.json \
+  --dry-run false \
+  --output .buildchain/web-surface-cleanup-apply.json
+```
+
+Apply output records the channel, alias, source SHA, artifact hash, target
+bucket, object prefix, manifest key, CDN invalidation paths, actor/run metadata,
+and every adapter operation with `executed`, `exitCode`, `stdout`, and `stderr`.
+If an operation fails, Buildchain records the failed operation, stops subsequent
+adapter operations, and exits non-zero after writing the result JSON. Buildchain
+records secret reference names only; the runner must provide the AWS CLI and
+credentials outside Buildchain, typically through OIDC and the declared
+`secret_refs`.
+
 ## Cleanup Plans
 
-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
+Preview cleanup is an auditable cleanup contract. It can run as a dry-run plan,
+an apply-mode plan, or the explicit `cleanup-apply` executor with preview-only
 credentials:
 
 ```bash
@@ -187,11 +254,11 @@ node scripts/web-surface.mjs \
   --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. 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.
+The plan and apply result keep mutable PR aliases and immutable SHA aliases
+distinct so a caller 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
 
@@ -218,10 +285,10 @@ 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; 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`.
+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`.
 
 ## Site Repository Shape
 
@@ -249,7 +316,9 @@ only needs a deterministic artifact path and the manifest facts.
 
 ## Boundaries
 
-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.
+Buildchain only performs live AWS mutations in explicit apply modes with
+`--dry-run false`. Production deploys must still be gated by a human-controlled
+workflow, release, or GitHub Environment. DNS changes, staging auth
+implementation, CloudFront distribution creation, and credential provisioning
+remain explicitly authorized infrastructure operations outside the web-surface
+artifact apply contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.0.14",
+  "version": "2.0.15-alpha.1",
   "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

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -124,6 +125,152 @@ function objectPrefixFor(deployConfig, alias) {
   return deployConfig.prefix || alias || "preview";
 }
 
+function normalizeS3Key(value) {
+  return String(value || "")
+    .replace(/^\/+/, "")
+    .replace(/\/{2,}/g, "/");
+}
+
+function joinS3Key(...parts) {
+  return normalizeS3Key(parts.filter(Boolean).join("/"));
+}
+
+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 defaultCommandRunner({ command, args, stdin = "" }) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    input: stdin,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const stderr = String(result.stderr || "").trim();
+    throw new Error(`${command} ${args.join(" ")} failed with exit code ${result.status}${stderr ? `: ${stderr}` : ""}`);
+  }
+  return {
+    exitCode: result.status,
+    stdout: String(result.stdout || ""),
+    stderr: String(result.stderr || ""),
+  };
+}
+
+function runAdapterOperation({ operation, dryRun, commandRunner }) {
+  if (dryRun) {
+    return {
+      ...operation,
+      status: "planned",
+      executed: false,
+      exitCode: null,
+      stdout: "",
+      stderr: "",
+    };
+  }
+  try {
+    const commandResult = commandRunner(operation);
+    const exitCode = commandResult?.exitCode ?? 0;
+    return {
+      ...operation,
+      status: exitCode === 0 ? "applied" : "failed",
+      executed: true,
+      exitCode,
+      stdout: commandResult?.stdout || "",
+      stderr: commandResult?.stderr || "",
+    };
+  } catch (error) {
+    return {
+      ...operation,
+      status: "failed",
+      executed: true,
+      exitCode: null,
+      stdout: "",
+      stderr: String(error.message || error),
+    };
+  }
+}
+
+function runAdapterOperations({ operations, dryRun, commandRunner }) {
+  const results = [];
+  for (const operation of operations) {
+    const result = runAdapterOperation({ operation, dryRun, commandRunner });
+    results.push(result);
+    if (result.status === "failed") {
+      break;
+    }
+  }
+  return results;
+}
+
+function appliedStatus({ dryRun, operations, noOp = false }) {
+  if (noOp) {
+    return "no-op";
+  }
+  if (operations.some((operation) => operation.status === "failed")) {
+    return "failed";
+  }
+  return dryRun ? "planned" : "applied";
+}
+
+function deployManifestKey(deployConfig, manifest) {
+  return joinS3Key(manifestPrefixFor(deployConfig), `${manifest.alias || manifest.channel}.json`);
+}
+
+function assertDeployPlan(plan) {
+  if (plan?.contract !== "kungfu-buildchain-web-surface-deploy-plan") {
+    throw new Error("web-surface deploy apply requires a deploy plan");
+  }
+  if (!plan.manifest) {
+    throw new Error("web-surface deploy plan is missing manifest");
+  }
+  if (!plan.artifact?.hash) {
+    throw new Error("web-surface deploy plan is missing artifact hash");
+  }
+  if (plan.manifest.artifactHash !== plan.artifact.hash) {
+    throw new Error("web-surface deploy plan artifact hash does not match manifest");
+  }
+  return plan;
+}
+
+function verifyDeployPlanArtifact({ cwd, plan }) {
+  const artifactPath = plan.artifact.path || ".";
+  const actual = createWebSurfaceArtifactHash({ cwd, artifactPath });
+  if (actual.artifactHash !== plan.artifact.hash) {
+    throw new Error(
+      `web-surface deploy plan artifact hash mismatch: expected ${plan.artifact.hash}, got ${actual.artifactHash}`,
+    );
+  }
+  return {
+    ...plan,
+    artifact: {
+      ...plan.artifact,
+      path: artifactPath,
+      files: actual.files,
+    },
+  };
+}
+
+function assertCleanupPlan(plan) {
+  if (plan?.contract !== "kungfu-buildchain-web-surface-cleanup-plan") {
+    throw new Error("web-surface cleanup apply requires a cleanup plan");
+  }
+  if (!Array.isArray(plan.entries)) {
+    throw new Error("web-surface cleanup plan is missing entries");
+  }
+  return plan;
+}
+
 function retentionFor({ config, channelName, alias, deployedAt }) {
   if (channelName === "preview") {
     const classified = classifyPreviewAlias(alias);
@@ -303,6 +450,92 @@ export function planWebSurfaceDeploy({
   };
 }
 
+export function applyWebSurfaceDeploy({
+  cwd = process.cwd(),
+  channel = "preview",
+  alias = "",
+  sourceSha = "",
+  artifactHash = "",
+  artifactPath = "",
+  plan = null,
+  dryRun = true,
+  actor = "",
+  runId = "",
+  appliedAt = new Date().toISOString(),
+  commandRunner = defaultCommandRunner,
+} = {}) {
+  const resolvedPlan = plan
+    ? verifyDeployPlanArtifact({ cwd, plan: assertDeployPlan(plan) })
+    : planWebSurfaceDeploy({
+        cwd,
+        channel,
+        alias,
+        sourceSha,
+        artifactHash,
+        artifactPath,
+        dryRun: true,
+        deployedAt: appliedAt,
+      });
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const config = assertWebSurfaceConfig(loadedConfig);
+  const deployConfig = config.deploy?.[resolvedPlan.channel];
+  if (!deployConfig) {
+    throw new Error(`missing deploy.${resolvedPlan.channel}`);
+  }
+  if (resolvedPlan.adapter !== "aws-s3-cloudfront") {
+    throw new Error(`web-surface deploy apply does not support adapter: ${resolvedPlan.adapter}`);
+  }
+  const bucket = deployConfig.bucket || deployConfig.target || "";
+  const artifactRoot = path.resolve(cwd, resolvedPlan.artifact.path);
+  const objectPrefix = objectPrefixFor(deployConfig, resolvedPlan.manifest.alias || resolvedPlan.manifest.channel);
+  const manifestKey = deployManifestKey(deployConfig, resolvedPlan.manifest);
+  const invalidationPaths = [`${cdnPath(objectPrefix)}/*`, cdnPath(manifestKey)];
+  const operations = [
+    {
+      action: "sync-static-artifact",
+      command: "aws",
+      args: ["s3", "sync", artifactRoot, s3Uri(bucket, objectPrefix), "--delete"],
+    },
+    {
+      action: "write-deployment-manifest",
+      command: "aws",
+      args: ["s3", "cp", "-", s3Uri(bucket, manifestKey), "--content-type", "application/json"],
+      stdin: `${JSON.stringify(resolvedPlan.manifest, null, 2)}\n`,
+    },
+  ];
+  const distribution = deployConfig.cloudfront_distribution || deployConfig.distribution || "";
+  if (distribution) {
+    operations.push({
+      action: "invalidate-cdn",
+      command: "aws",
+      args: ["cloudfront", "create-invalidation", "--distribution-id", distribution, "--paths", ...invalidationPaths],
+    });
+  }
+  const operationResults = runAdapterOperations({ operations, dryRun, commandRunner });
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-deploy-apply",
+    dryRun,
+    applyMode: dryRun ? "dry-run" : "apply",
+    status: appliedStatus({ dryRun, operations: operationResults }),
+    actor,
+    runId,
+    appliedAt,
+    channel: resolvedPlan.channel,
+    alias: resolvedPlan.alias,
+    url: resolvedPlan.url,
+    sourceSha: resolvedPlan.manifest.sourceSha,
+    artifactHash: resolvedPlan.artifact.hash,
+    adapter: resolvedPlan.adapter,
+    target: bucket,
+    objectPrefix,
+    manifestKey,
+    invalidationPaths,
+    manifest: resolvedPlan.manifest,
+    operations: operationResults,
+  };
+}
+
 function planAdapterSteps(adapter, deployConfig, manifest) {
   if (adapter === "aws-s3-cloudfront") {
     return [
@@ -399,6 +632,100 @@ export function planWebSurfaceCleanup({
   };
 }
 
+export function applyWebSurfaceCleanup({
+  cwd = process.cwd(),
+  aliases = [],
+  channel = "preview",
+  now = new Date().toISOString(),
+  event = "manual",
+  sourceSha = "",
+  pullNumber = "",
+  actor = "",
+  runId = "",
+  plan = null,
+  dryRun = true,
+  commandRunner = defaultCommandRunner,
+} = {}) {
+  const cleanup = plan
+    ? assertCleanupPlan(plan)
+    : planWebSurfaceCleanup({
+        cwd,
+        aliases,
+        channel,
+        now,
+        event,
+        sourceSha,
+        pullNumber,
+        actor,
+        runId,
+        dryRun,
+      });
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const config = assertWebSurfaceConfig(loadedConfig);
+  const deployConfig = config.deploy?.[cleanup.channel];
+  if (!deployConfig) {
+    throw new Error(`missing deploy.${cleanup.channel}`);
+  }
+  if (cleanup.adapter !== "aws-s3-cloudfront") {
+    throw new Error(`web-surface cleanup apply does not support adapter: ${cleanup.adapter}`);
+  }
+  const bucket = deployConfig.bucket || deployConfig.target || "";
+  const operations = cleanup.entries.flatMap((entry) => {
+    const entryOperations = [
+      {
+        action: "delete-static-prefix",
+        alias: entry.alias,
+        command: "aws",
+        args: ["s3", "rm", s3Uri(bucket, entry.objectPrefix), "--recursive"],
+      },
+      {
+        action: "delete-deployment-manifest",
+        alias: entry.alias,
+        command: "aws",
+        args: ["s3", "rm", s3Uri(bucket, entry.manifestKey)],
+      },
+    ];
+    const distribution = deployConfig.cloudfront_distribution || deployConfig.distribution || "";
+    if (distribution) {
+      entryOperations.push({
+        action: "invalidate-cdn",
+        alias: entry.alias,
+        command: "aws",
+        args: [
+          "cloudfront",
+          "create-invalidation",
+          "--distribution-id",
+          distribution,
+          "--paths",
+          `${cdnPath(entry.objectPrefix)}/*`,
+          cdnPath(entry.manifestKey),
+        ],
+      });
+    }
+    return entryOperations;
+  });
+  const operationResults = runAdapterOperations({ operations, dryRun, commandRunner });
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-cleanup-apply",
+    dryRun,
+    applyMode: dryRun ? "dry-run" : "apply",
+    status: appliedStatus({ dryRun, operations: operationResults, noOp: cleanup.status === "no-op" }),
+    event,
+    channel,
+    now,
+    sourceSha: cleanup.sourceSha,
+    pullNumber: cleanup.pullNumber,
+    actor,
+    runId,
+    adapter: cleanup.adapter,
+    target: bucket,
+    manifestPrefix: cleanup.manifestPrefix,
+    entries: cleanup.entries,
+    operations: operationResults,
+  };
+}
+
 function cleanupAdapterSteps(adapter, deployConfig, entry) {
   if (adapter === "aws-s3-cloudfront") {
     return [

package/scripts/web-surface.mjs

@@ -3,6 +3,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import {
+  applyWebSurfaceCleanup,
+  applyWebSurfaceDeploy,
   defaultWebSurfaceAlias,
   planWebSurfaceCleanup,
   planWebSurfaceDeploy,
@@ -36,6 +38,20 @@ function writeJson(result, outputPath) {
   }
 }
 
+function readJsonFileArg(name) {
+  const value = readArg(name, "");
+  if (!value) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(path.resolve(value), "utf8"));
+}
+
+function assertApplySucceeded(result) {
+  if (result.status === "failed") {
+    throw new Error(`web-surface ${result.contract} failed; see apply result for operation details`);
+  }
+}
+
 export function webSurfaceCli() {
   const mode = readArg("mode", process.env.BUILDCHAIN_WEB_SURFACE_MODE || "validate");
   const cwd = readArg("cwd", process.env.BUILDCHAIN_WORKDIR || process.cwd());
@@ -80,6 +96,40 @@ export function webSurfaceCli() {
     return outputResult;
   }
 
+  if (mode === "deploy-apply") {
+    const plan = readJsonFileArg("plan");
+    const alias = plan
+      ? readArg("alias", process.env.BUILDCHAIN_WEB_SURFACE_ALIAS || "")
+      : readArg(
+          "alias",
+          process.env.BUILDCHAIN_WEB_SURFACE_ALIAS || defaultWebSurfaceAlias({ channel, sourceSha, pullNumber }),
+        );
+    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 || ""),
+    });
+    writeJson(result, output);
+    writeGitHubOutputs({
+      "web-surface-channel": result.channel,
+      "web-surface-alias": result.alias,
+      "web-surface-url": result.url,
+      "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),
+    });
+    assertApplySucceeded(result);
+    return result;
+  }
+
   if (mode === "cleanup-plan") {
     const aliases = readArg("aliases", process.env.BUILDCHAIN_WEB_SURFACE_ALIASES || "")
       .split(",")
@@ -106,6 +156,35 @@ export function webSurfaceCli() {
     return result;
   }
 
+  if (mode === "cleanup-apply") {
+    const plan = readJsonFileArg("plan");
+    const aliases = readArg("aliases", process.env.BUILDCHAIN_WEB_SURFACE_ALIASES || "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    const result = applyWebSurfaceCleanup({
+      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 || ""),
+      plan,
+      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-result-json": JSON.stringify(result),
+    });
+    assertApplySucceeded(result);
+    return result;
+  }
+
   throw new Error(`unsupported web-surface mode: ${mode}`);
 }