@kungfu-tech/buildchain 2.8.8 → 2.8.9-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/site/buildchain-contract.json +47 -5
- package/dist/site/buildchain-site.json +12 -7
- package/dist/site/kfd-claims.json +1 -1
- package/dist/site/manual-registry.json +1 -1
- package/dist/site/node-api-registry.json +1 -1
- package/dist/site/page-registry.json +7 -2
- package/dist/site/site-manifest.json +5 -5
- package/docs/web-surface-deployments.md +32 -0
- package/package.json +1 -1
- package/packages/core/buildchain-contract.js +37 -0
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
"product": {
|
|
5
5
|
"name": "Buildchain",
|
|
6
6
|
"package": "@kungfu-tech/buildchain",
|
|
7
|
-
"version": "2.8.
|
|
7
|
+
"version": "2.8.9-alpha.1",
|
|
8
8
|
"repository": "https://github.com/kungfu-systems/buildchain"
|
|
9
9
|
},
|
|
10
10
|
"majorLine": "v2",
|
|
@@ -94,6 +94,48 @@
|
|
|
94
94
|
"breakingDigest": "sha256:403d2fcdb0c5eabe749e89102defad69745f70a1556707bec7831fcc2e9fa8f8",
|
|
95
95
|
"auditDigest": "sha256:277d9e6a9b55986911f8331cfbad1d747631085cc73c3ab207319c52ed29d429"
|
|
96
96
|
},
|
|
97
|
+
{
|
|
98
|
+
"contractVersion": 1,
|
|
99
|
+
"stability": "stable",
|
|
100
|
+
"additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
|
|
101
|
+
"id": "web-surface",
|
|
102
|
+
"kind": "workflow",
|
|
103
|
+
"path": ".github/workflows/.web-surface.yml",
|
|
104
|
+
"publicRef": "kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2",
|
|
105
|
+
"requiredInputs": [],
|
|
106
|
+
"requiredOutputs": [
|
|
107
|
+
"buildchain-runtime-sha",
|
|
108
|
+
"web-surface-channel",
|
|
109
|
+
"web-surface-url",
|
|
110
|
+
"web-surface-manifest-json"
|
|
111
|
+
],
|
|
112
|
+
"breakingDefaults": {
|
|
113
|
+
"buildchainRefDefault": "workflow-shell-ref-or-v2",
|
|
114
|
+
"contractCompatibilityPolicy": "major-compatible",
|
|
115
|
+
"breakingDriftPolicy": "fail-closed-before-build"
|
|
116
|
+
},
|
|
117
|
+
"optionalInputs": [
|
|
118
|
+
"buildchain-ref",
|
|
119
|
+
"buildchain-contract-lock-path",
|
|
120
|
+
"buildchain-contract-compatibility-policy",
|
|
121
|
+
"buildchain-contract-drift-issue-mode",
|
|
122
|
+
"build-command",
|
|
123
|
+
"verify-command",
|
|
124
|
+
"artifact-path",
|
|
125
|
+
"preview-apply",
|
|
126
|
+
"staging-apply",
|
|
127
|
+
"production-apply",
|
|
128
|
+
"production-release-on-main"
|
|
129
|
+
],
|
|
130
|
+
"guarantees": [
|
|
131
|
+
"runtime floating refs are resolved to immutable SHAs before caller build and deploy work",
|
|
132
|
+
"contract drift is checked before caller build, web-surface render, deploy planning, and apply side effects",
|
|
133
|
+
"compatible contract drift continues and produces a consumer issue or summary",
|
|
134
|
+
"breaking contract drift fails closed before rendering, deployment, or release publication"
|
|
135
|
+
],
|
|
136
|
+
"breakingDigest": "sha256:82ee63cb336e40d832dfff4a1c5e6cbfa221a4fc8b2359990033bc931bffc43a",
|
|
137
|
+
"auditDigest": "sha256:5416c9f4112bf24e7cef556f792034842252f65dcf9e8adf338ddc85a5137ada"
|
|
138
|
+
},
|
|
97
139
|
{
|
|
98
140
|
"contractVersion": 1,
|
|
99
141
|
"stability": "stable",
|
|
@@ -320,7 +362,7 @@
|
|
|
320
362
|
"manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
|
|
321
363
|
],
|
|
322
364
|
"breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
|
|
323
|
-
"auditDigest": "sha256:
|
|
365
|
+
"auditDigest": "sha256:56f4d576816d32f34844a248c9b5fdcb1adac99ef8588a1d1591577e8939ad78"
|
|
324
366
|
},
|
|
325
367
|
{
|
|
326
368
|
"contractVersion": 1,
|
|
@@ -342,9 +384,9 @@
|
|
|
342
384
|
"agents can discover supported Node APIs without importing internal file paths"
|
|
343
385
|
],
|
|
344
386
|
"breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
|
|
345
|
-
"auditDigest": "sha256:
|
|
387
|
+
"auditDigest": "sha256:8002cc53fb052c49e519cf2466d41b9f76a6241bcc8354520fad5121a7b78065"
|
|
346
388
|
}
|
|
347
389
|
],
|
|
348
|
-
"compatibilityDigest": "sha256:
|
|
349
|
-
"contractDigest": "sha256:
|
|
390
|
+
"compatibilityDigest": "sha256:85e27de8d34ceac1652d9374697ea5a1a7a08666d2ba7ae377b9afdd14e2ca1f",
|
|
391
|
+
"contractDigest": "sha256:287fb149877fe91ae0f5535c37ab2a78aec7741258d65a47b594dfb5acc0a521"
|
|
350
392
|
}
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"contract": "kungfu-buildchain-site-bundle",
|
|
4
|
-
"generatedAt": "2026-07-07T09:
|
|
5
|
-
"publishedAt": "2026-07-07T09:
|
|
4
|
+
"generatedAt": "2026-07-07T09:52:33.653Z",
|
|
5
|
+
"publishedAt": "2026-07-07T09:52:33.653Z",
|
|
6
6
|
"reproducible": true,
|
|
7
7
|
"timestampPolicy": "ci-injected",
|
|
8
8
|
"deterministicInputs": [
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"declared Buildchain surface manifest contract"
|
|
20
20
|
],
|
|
21
21
|
"sourceDateEpoch": "0",
|
|
22
|
-
"sourceRevision": "
|
|
22
|
+
"sourceRevision": "1e40482d191fe9dbd014c96c252867b65c71e0b9",
|
|
23
23
|
"timestampPolicyDetails": {
|
|
24
24
|
"contract": "kungfu-buildchain-surface-timestamp-policy",
|
|
25
25
|
"timestampFields": [
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
},
|
|
38
38
|
"package": {
|
|
39
39
|
"name": "@kungfu-tech/buildchain",
|
|
40
|
-
"version": "2.8.
|
|
40
|
+
"version": "2.8.9-alpha.1",
|
|
41
41
|
"versionSource": "package.json#version"
|
|
42
42
|
},
|
|
43
43
|
"source": {
|
|
@@ -1251,7 +1251,7 @@
|
|
|
1251
1251
|
"route": "/docs/web-surface-deployments",
|
|
1252
1252
|
"category": "manual",
|
|
1253
1253
|
"sourcePath": "docs/web-surface-deployments.md",
|
|
1254
|
-
"digest": "sha256:
|
|
1254
|
+
"digest": "sha256:f42cc7a81dbeb1b31bec21de61e9807af317bda4055f693ab807b15d9ec77367",
|
|
1255
1255
|
"headings": [
|
|
1256
1256
|
{
|
|
1257
1257
|
"level": 1,
|
|
@@ -1268,6 +1268,11 @@
|
|
|
1268
1268
|
"title": "Multi-Surface Host Mapping",
|
|
1269
1269
|
"anchor": "multi-surface-host-mapping"
|
|
1270
1270
|
},
|
|
1271
|
+
{
|
|
1272
|
+
"level": 3,
|
|
1273
|
+
"title": "Floating Runtime Contract Lock",
|
|
1274
|
+
"anchor": "floating-runtime-contract-lock"
|
|
1275
|
+
},
|
|
1271
1276
|
{
|
|
1272
1277
|
"level": 2,
|
|
1273
1278
|
"title": "Preview Aliases",
|
|
@@ -1314,7 +1319,7 @@
|
|
|
1314
1319
|
"anchor": "boundaries"
|
|
1315
1320
|
}
|
|
1316
1321
|
],
|
|
1317
|
-
"markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n reference metadata.\n\n## Configuration\n\n`buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub: https://pr-12.preview.libkungfu.dev\ncore: https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd: https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n `edge_auth = \"none\"` when staging is protected by managed network controls\n such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n \"schemaVersion\": 1,\n \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n \"site\": \"libkungfu-dev\",\n \"channel\": \"preview\",\n \"alias\": \"sha-abcdef123456\",\n \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n \"reproducible\": true,\n \"timestampPolicy\": \"ci-injected\",\n \"deterministicInputs\": [\n \"web-surface artifact content\",\n \"buildchain.toml web-surface channels/deploy/surfaces\",\n \"sourceSha\",\n \"artifactHash\",\n \"deployment channel\",\n \"deployment alias\"\n ],\n \"sourceRevision\": \"...\",\n \"timestampPolicyDetails\": {\n \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n \"timestampFieldsParticipateInArtifactDigest\": false,\n \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n },\n \"sourceSha\": \"...\",\n \"artifactHash\": \"...\",\n \"deployTarget\": \"libkungfu-dev-preview\",\n \"adapter\": \"aws-s3-cloudfront\",\n \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n \"retentionClass\": \"preview-sha-immutable\",\n \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n \"accessControl\": \"none\",\n \"edgeAuth\": \"none\",\n \"noindex\": true,\n \"secretRefs\": [\"AWS_ROLE_ARN\"],\n \"surfaceBindings\": [\n {\n \"surface\": \"hub\",\n \"channel\": \"preview\",\n \"alias\": \"sha-abcdef123456\",\n \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n \"sourcePath\": \"/\",\n \"canonicalUrl\": \"https://libkungfu.dev\",\n \"bucket\": \"libkungfu-dev-preview\",\n \"distributionId\": \"E-PREVIEW\",\n \"originPath\": \"\",\n \"objectPrefix\": \"sha-abcdef123456\",\n \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n \"noindex\": true,\n \"accessControl\": \"none\"\n }\n ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-plan \\\n --cwd fixtures/web-surface-shaped \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode manifest \\\n --cwd fixtures/web-surface-shaped \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --alias pr-123 \\\n --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-apply \\\n --cwd fixtures/web-surface-shaped \\\n --channel staging \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --artifact-path dist \\\n --dry-run false \\\n --output .buildchain/web-surface-staging-apply.json\n```\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-apply \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-staging-plan.json \\\n --dry-run false \\\n --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-apply \\\n --cwd fixtures/web-surface-shaped \\\n --event pull-request-closed \\\n --pull-number 123 \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --dry-run false \\\n --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-apply \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-cleanup-plan.json \\\n --dry-run false \\\n --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, and every adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode production-preflight \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-production-plan.json \\\n --execute true \\\n --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode health-check \\\n --cwd fixtures/web-surface-shaped \\\n --result .buildchain/web-surface-production-apply.json \\\n --output .buildchain/web-surface-production-health.json\n```\n\nThe health check fetches every surface URL from the apply result and fails\nproduction if a response is unreachable, returns an unexpected status, or still\nsends `x-robots-tag: noindex`. It also verifies that each surface binding\nrecorded a deployment manifest pointer. The production release passport embeds\nthe deploy plan, apply result, production preflight, and health check so a\nreviewer or agent can audit why the production site changed and whether every\ndeclared host was actually covered.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-plan \\\n --cwd fixtures/web-surface-shaped \\\n --event pull-request-closed \\\n --pull-number 123 \\\n --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: npm run build\n verify-command: npm run check\n artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v2`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n workflow_dispatch:\n inputs:\n buildchain-ref:\n description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n required: false\n default: \"\"\n\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n build-command: pnpm run build\n verify-command: pnpm run check\n artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n contents: read\n id-token: write\n pull-requests: write\n\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: pnpm run build\n verify-command: pnpm run check\n artifact-path: dist\n preview-apply: true\n preview-cleanup-apply: true\n preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n staging-apply: true\n staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n production-apply: false\n production-release-on-main: false\n production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n production-environment: production\n release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n role, then write a staging release feedback passport artifact and comment the\n associated merged PR with the staging URL, source SHA, artifact identity, run\n URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n update a Buildchain-owned release PR from\n `release/<channel>-<short-sha>` to `main`, unless the current push already\n came from a matching release PR merge. The release PR contains one empty\n release-intent commit, carries `production-release-label`, and includes the\n staging URLs, source SHA, artifact hash, and staging release-passport artifact\n link in the PR body.\n- Release pull requests that match the configured production gate get a\n Buildchain review comment with the staging URL and production target, so the\n operator can verify staging from the PR page and use merge as the approval\n action. Consumers do not need to hand-write `gh pr create` or production\n release-intent glue.\n- Production runs when `production-apply` is true and either:\n - a trusted `workflow_dispatch` passes `production-approved=true`; or\n - `production-release-on-main=true` and the `main` push commit is associated\n with exactly one same-repository, merged release pull request matching\n `production-release-label` and `production-release-head-prefix`.\n The production job is then gated by the configured GitHub Environment.\n- Production apply writes a production release feedback passport artifact and\n comments the release PR with the production URL, source SHA, artifact\n identity, run URL, rollback pointer, and failure context when apply did not\n complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: npm run build\n verify-command: npm run check\n artifact-path: dist\n production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}\n production-release-on-main: true\n production-release-label: buildchain-release\n production-release-head-prefix: release/\n production-release-branch-channel: production\n production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n production-environment: production\n```\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs or a production apply without `production-approved=true`\non manual dispatch fail immediately instead of spending the build and plan jobs\nfirst.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
|
|
1322
|
+
"markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n reference metadata.\n\n## Configuration\n\n`buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub: https://pr-12.preview.libkungfu.dev\ncore: https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd: https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n `edge_auth = \"none\"` when staging is protected by managed network controls\n such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\n### Floating Runtime Contract Lock\n\nWeb-surface repositories can consume the stable Buildchain workflow shell with a\nfloating ref, such as:\n\n```yaml\njobs:\n web:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n buildchain-contract-lock-path: buildchain.contract-lock.json\n buildchain-contract-compatibility-policy: major-compatible\n buildchain-contract-drift-issue-mode: compatible-and-breaking\n build-command: pnpm build\n artifact-path: dist\n```\n\nThe caller repository commits `buildchain.contract-lock.json` after reviewing an\naccepted Buildchain runtime SHA and contract digest. The reusable workflow then\nresolves the floating runtime to an immutable SHA, checks the lock before the\ncaller build command, and applies these rules:\n\n- unchanged lock: continue without feedback;\n- compatible drift: continue, write the drift summary, and open or update a\n caller-repository issue when permissions allow;\n- breaking drift: fail closed before rendering, deployment planning, deploy\n apply, or release publication.\n\nThe caller no longer needs to run `scripts/buildchain-contract-lock.mjs` inside\nits own build command. That check belongs to Buildchain because the actual\ncontract world is stored in the Buildchain runtime ref being used.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n \"schemaVersion\": 1,\n \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n \"site\": \"libkungfu-dev\",\n \"channel\": \"preview\",\n \"alias\": \"sha-abcdef123456\",\n \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n \"reproducible\": true,\n \"timestampPolicy\": \"ci-injected\",\n \"deterministicInputs\": [\n \"web-surface artifact content\",\n \"buildchain.toml web-surface channels/deploy/surfaces\",\n \"sourceSha\",\n \"artifactHash\",\n \"deployment channel\",\n \"deployment alias\"\n ],\n \"sourceRevision\": \"...\",\n \"timestampPolicyDetails\": {\n \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n \"timestampFieldsParticipateInArtifactDigest\": false,\n \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n },\n \"sourceSha\": \"...\",\n \"artifactHash\": \"...\",\n \"deployTarget\": \"libkungfu-dev-preview\",\n \"adapter\": \"aws-s3-cloudfront\",\n \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n \"retentionClass\": \"preview-sha-immutable\",\n \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n \"accessControl\": \"none\",\n \"edgeAuth\": \"none\",\n \"noindex\": true,\n \"secretRefs\": [\"AWS_ROLE_ARN\"],\n \"surfaceBindings\": [\n {\n \"surface\": \"hub\",\n \"channel\": \"preview\",\n \"alias\": \"sha-abcdef123456\",\n \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n \"sourcePath\": \"/\",\n \"canonicalUrl\": \"https://libkungfu.dev\",\n \"bucket\": \"libkungfu-dev-preview\",\n \"distributionId\": \"E-PREVIEW\",\n \"originPath\": \"\",\n \"objectPrefix\": \"sha-abcdef123456\",\n \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n \"noindex\": true,\n \"accessControl\": \"none\"\n }\n ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-plan \\\n --cwd fixtures/web-surface-shaped \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode manifest \\\n --cwd fixtures/web-surface-shaped \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --alias pr-123 \\\n --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-apply \\\n --cwd fixtures/web-surface-shaped \\\n --channel staging \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --artifact-path dist \\\n --dry-run false \\\n --output .buildchain/web-surface-staging-apply.json\n```\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-apply \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-staging-plan.json \\\n --dry-run false \\\n --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-apply \\\n --cwd fixtures/web-surface-shaped \\\n --event pull-request-closed \\\n --pull-number 123 \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --dry-run false \\\n --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-apply \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-cleanup-plan.json \\\n --dry-run false \\\n --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, and every adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode production-preflight \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-production-plan.json \\\n --execute true \\\n --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode health-check \\\n --cwd fixtures/web-surface-shaped \\\n --result .buildchain/web-surface-production-apply.json \\\n --output .buildchain/web-surface-production-health.json\n```\n\nThe health check fetches every surface URL from the apply result and fails\nproduction if a response is unreachable, returns an unexpected status, or still\nsends `x-robots-tag: noindex`. It also verifies that each surface binding\nrecorded a deployment manifest pointer. The production release passport embeds\nthe deploy plan, apply result, production preflight, and health check so a\nreviewer or agent can audit why the production site changed and whether every\ndeclared host was actually covered.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-plan \\\n --cwd fixtures/web-surface-shaped \\\n --event pull-request-closed \\\n --pull-number 123 \\\n --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: npm run build\n verify-command: npm run check\n artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v2`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n workflow_dispatch:\n inputs:\n buildchain-ref:\n description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n required: false\n default: \"\"\n\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n build-command: pnpm run build\n verify-command: pnpm run check\n artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n contents: read\n id-token: write\n pull-requests: write\n\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: pnpm run build\n verify-command: pnpm run check\n artifact-path: dist\n preview-apply: true\n preview-cleanup-apply: true\n preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n staging-apply: true\n staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n production-apply: false\n production-release-on-main: false\n production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n production-environment: production\n release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n role, then write a staging release feedback passport artifact and comment the\n associated merged PR with the staging URL, source SHA, artifact identity, run\n URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n update a Buildchain-owned release PR from\n `release/<channel>-<short-sha>` to `main`, unless the current push already\n came from a matching release PR merge. The release PR contains one empty\n release-intent commit, carries `production-release-label`, and includes the\n staging URLs, source SHA, artifact hash, and staging release-passport artifact\n link in the PR body.\n- Release pull requests that match the configured production gate get a\n Buildchain review comment with the staging URL and production target, so the\n operator can verify staging from the PR page and use merge as the approval\n action. Consumers do not need to hand-write `gh pr create` or production\n release-intent glue.\n- Production runs when `production-apply` is true and either:\n - a trusted `workflow_dispatch` passes `production-approved=true`; or\n - `production-release-on-main=true` and the `main` push commit is associated\n with exactly one same-repository, merged release pull request matching\n `production-release-label` and `production-release-head-prefix`.\n The production job is then gated by the configured GitHub Environment.\n- Production apply writes a production release feedback passport artifact and\n comments the release PR with the production URL, source SHA, artifact\n identity, run URL, rollback pointer, and failure context when apply did not\n complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: npm run build\n verify-command: npm run check\n artifact-path: dist\n production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}\n production-release-on-main: true\n production-release-label: buildchain-release\n production-release-head-prefix: release/\n production-release-branch-channel: production\n production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n production-environment: production\n```\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs or a production apply without `production-approved=true`\non manual dispatch fail immediately instead of spending the build and plan jobs\nfirst.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
|
|
1318
1323
|
},
|
|
1319
1324
|
{
|
|
1320
1325
|
"id": "fixture:infra-contract-aws-cdk-shaped",
|
|
@@ -1774,7 +1779,7 @@
|
|
|
1774
1779
|
"path": "docs/web-surface-deployments.md",
|
|
1775
1780
|
"plane": "use",
|
|
1776
1781
|
"exists": true,
|
|
1777
|
-
"digest": "sha256:
|
|
1782
|
+
"digest": "sha256:f42cc7a81dbeb1b31bec21de61e9807af317bda4055f693ab807b15d9ec77367"
|
|
1778
1783
|
}
|
|
1779
1784
|
],
|
|
1780
1785
|
"releaseModel": {
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
},
|
|
15
15
|
"runtimeContract": {
|
|
16
16
|
"contract": "kungfu-buildchain-runtime-contract-world",
|
|
17
|
-
"compatibilityDigest": "sha256:
|
|
17
|
+
"compatibilityDigest": "sha256:85e27de8d34ceac1652d9374697ea5a1a7a08666d2ba7ae377b9afdd14e2ca1f",
|
|
18
18
|
"majorLine": "v2"
|
|
19
19
|
},
|
|
20
20
|
"publicClaims": [
|
|
@@ -149,7 +149,7 @@
|
|
|
149
149
|
"title": "Web surface deployments",
|
|
150
150
|
"path": "docs/web-surface-deployments.md",
|
|
151
151
|
"plane": "use",
|
|
152
|
-
"digest": "sha256:
|
|
152
|
+
"digest": "sha256:f42cc7a81dbeb1b31bec21de61e9807af317bda4055f693ab807b15d9ec77367"
|
|
153
153
|
}
|
|
154
154
|
],
|
|
155
155
|
"requiredAgentManuals": [
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"specifier": "@kungfu-tech/buildchain/buildchain-contract",
|
|
27
27
|
"export": "./buildchain-contract",
|
|
28
28
|
"target": "./packages/core/buildchain-contract.js",
|
|
29
|
-
"digest": "sha256:
|
|
29
|
+
"digest": "sha256:55a47f7476e7307fffdc29b5af6acf4f40d57987557cf470f26611414d927d5b"
|
|
30
30
|
},
|
|
31
31
|
{
|
|
32
32
|
"specifier": "@kungfu-tech/buildchain/diagnostics",
|
|
@@ -1197,7 +1197,7 @@
|
|
|
1197
1197
|
"route": "/docs/web-surface-deployments",
|
|
1198
1198
|
"category": "manual",
|
|
1199
1199
|
"sourcePath": "docs/web-surface-deployments.md",
|
|
1200
|
-
"digest": "sha256:
|
|
1200
|
+
"digest": "sha256:f42cc7a81dbeb1b31bec21de61e9807af317bda4055f693ab807b15d9ec77367",
|
|
1201
1201
|
"headings": [
|
|
1202
1202
|
{
|
|
1203
1203
|
"level": 1,
|
|
@@ -1214,6 +1214,11 @@
|
|
|
1214
1214
|
"title": "Multi-Surface Host Mapping",
|
|
1215
1215
|
"anchor": "multi-surface-host-mapping"
|
|
1216
1216
|
},
|
|
1217
|
+
{
|
|
1218
|
+
"level": 3,
|
|
1219
|
+
"title": "Floating Runtime Contract Lock",
|
|
1220
|
+
"anchor": "floating-runtime-contract-lock"
|
|
1221
|
+
},
|
|
1217
1222
|
{
|
|
1218
1223
|
"level": 2,
|
|
1219
1224
|
"title": "Preview Aliases",
|
|
@@ -1260,7 +1265,7 @@
|
|
|
1260
1265
|
"anchor": "boundaries"
|
|
1261
1266
|
}
|
|
1262
1267
|
],
|
|
1263
|
-
"markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n reference metadata.\n\n## Configuration\n\n`buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub: https://pr-12.preview.libkungfu.dev\ncore: https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd: https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n `edge_auth = \"none\"` when staging is protected by managed network controls\n such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n \"schemaVersion\": 1,\n \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n \"site\": \"libkungfu-dev\",\n \"channel\": \"preview\",\n \"alias\": \"sha-abcdef123456\",\n \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n \"reproducible\": true,\n \"timestampPolicy\": \"ci-injected\",\n \"deterministicInputs\": [\n \"web-surface artifact content\",\n \"buildchain.toml web-surface channels/deploy/surfaces\",\n \"sourceSha\",\n \"artifactHash\",\n \"deployment channel\",\n \"deployment alias\"\n ],\n \"sourceRevision\": \"...\",\n \"timestampPolicyDetails\": {\n \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n \"timestampFieldsParticipateInArtifactDigest\": false,\n \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n },\n \"sourceSha\": \"...\",\n \"artifactHash\": \"...\",\n \"deployTarget\": \"libkungfu-dev-preview\",\n \"adapter\": \"aws-s3-cloudfront\",\n \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n \"retentionClass\": \"preview-sha-immutable\",\n \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n \"accessControl\": \"none\",\n \"edgeAuth\": \"none\",\n \"noindex\": true,\n \"secretRefs\": [\"AWS_ROLE_ARN\"],\n \"surfaceBindings\": [\n {\n \"surface\": \"hub\",\n \"channel\": \"preview\",\n \"alias\": \"sha-abcdef123456\",\n \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n \"sourcePath\": \"/\",\n \"canonicalUrl\": \"https://libkungfu.dev\",\n \"bucket\": \"libkungfu-dev-preview\",\n \"distributionId\": \"E-PREVIEW\",\n \"originPath\": \"\",\n \"objectPrefix\": \"sha-abcdef123456\",\n \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n \"noindex\": true,\n \"accessControl\": \"none\"\n }\n ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-plan \\\n --cwd fixtures/web-surface-shaped \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode manifest \\\n --cwd fixtures/web-surface-shaped \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --alias pr-123 \\\n --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-apply \\\n --cwd fixtures/web-surface-shaped \\\n --channel staging \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --artifact-path dist \\\n --dry-run false \\\n --output .buildchain/web-surface-staging-apply.json\n```\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-apply \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-staging-plan.json \\\n --dry-run false \\\n --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-apply \\\n --cwd fixtures/web-surface-shaped \\\n --event pull-request-closed \\\n --pull-number 123 \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --dry-run false \\\n --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-apply \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-cleanup-plan.json \\\n --dry-run false \\\n --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, and every adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode production-preflight \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-production-plan.json \\\n --execute true \\\n --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode health-check \\\n --cwd fixtures/web-surface-shaped \\\n --result .buildchain/web-surface-production-apply.json \\\n --output .buildchain/web-surface-production-health.json\n```\n\nThe health check fetches every surface URL from the apply result and fails\nproduction if a response is unreachable, returns an unexpected status, or still\nsends `x-robots-tag: noindex`. It also verifies that each surface binding\nrecorded a deployment manifest pointer. The production release passport embeds\nthe deploy plan, apply result, production preflight, and health check so a\nreviewer or agent can audit why the production site changed and whether every\ndeclared host was actually covered.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-plan \\\n --cwd fixtures/web-surface-shaped \\\n --event pull-request-closed \\\n --pull-number 123 \\\n --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: npm run build\n verify-command: npm run check\n artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v2`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n workflow_dispatch:\n inputs:\n buildchain-ref:\n description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n required: false\n default: \"\"\n\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n build-command: pnpm run build\n verify-command: pnpm run check\n artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n contents: read\n id-token: write\n pull-requests: write\n\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: pnpm run build\n verify-command: pnpm run check\n artifact-path: dist\n preview-apply: true\n preview-cleanup-apply: true\n preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n staging-apply: true\n staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n production-apply: false\n production-release-on-main: false\n production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n production-environment: production\n release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n role, then write a staging release feedback passport artifact and comment the\n associated merged PR with the staging URL, source SHA, artifact identity, run\n URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n update a Buildchain-owned release PR from\n `release/<channel>-<short-sha>` to `main`, unless the current push already\n came from a matching release PR merge. The release PR contains one empty\n release-intent commit, carries `production-release-label`, and includes the\n staging URLs, source SHA, artifact hash, and staging release-passport artifact\n link in the PR body.\n- Release pull requests that match the configured production gate get a\n Buildchain review comment with the staging URL and production target, so the\n operator can verify staging from the PR page and use merge as the approval\n action. Consumers do not need to hand-write `gh pr create` or production\n release-intent glue.\n- Production runs when `production-apply` is true and either:\n - a trusted `workflow_dispatch` passes `production-approved=true`; or\n - `production-release-on-main=true` and the `main` push commit is associated\n with exactly one same-repository, merged release pull request matching\n `production-release-label` and `production-release-head-prefix`.\n The production job is then gated by the configured GitHub Environment.\n- Production apply writes a production release feedback passport artifact and\n comments the release PR with the production URL, source SHA, artifact\n identity, run URL, rollback pointer, and failure context when apply did not\n complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: npm run build\n verify-command: npm run check\n artifact-path: dist\n production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}\n production-release-on-main: true\n production-release-label: buildchain-release\n production-release-head-prefix: release/\n production-release-branch-channel: production\n production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n production-environment: production\n```\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs or a production apply without `production-approved=true`\non manual dispatch fail immediately instead of spending the build and plan jobs\nfirst.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
|
|
1268
|
+
"markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n reference metadata.\n\n## Configuration\n\n`buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub: https://pr-12.preview.libkungfu.dev\ncore: https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd: https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n `edge_auth = \"none\"` when staging is protected by managed network controls\n such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\n### Floating Runtime Contract Lock\n\nWeb-surface repositories can consume the stable Buildchain workflow shell with a\nfloating ref, such as:\n\n```yaml\njobs:\n web:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n buildchain-contract-lock-path: buildchain.contract-lock.json\n buildchain-contract-compatibility-policy: major-compatible\n buildchain-contract-drift-issue-mode: compatible-and-breaking\n build-command: pnpm build\n artifact-path: dist\n```\n\nThe caller repository commits `buildchain.contract-lock.json` after reviewing an\naccepted Buildchain runtime SHA and contract digest. The reusable workflow then\nresolves the floating runtime to an immutable SHA, checks the lock before the\ncaller build command, and applies these rules:\n\n- unchanged lock: continue without feedback;\n- compatible drift: continue, write the drift summary, and open or update a\n caller-repository issue when permissions allow;\n- breaking drift: fail closed before rendering, deployment planning, deploy\n apply, or release publication.\n\nThe caller no longer needs to run `scripts/buildchain-contract-lock.mjs` inside\nits own build command. That check belongs to Buildchain because the actual\ncontract world is stored in the Buildchain runtime ref being used.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n \"schemaVersion\": 1,\n \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n \"site\": \"libkungfu-dev\",\n \"channel\": \"preview\",\n \"alias\": \"sha-abcdef123456\",\n \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n \"reproducible\": true,\n \"timestampPolicy\": \"ci-injected\",\n \"deterministicInputs\": [\n \"web-surface artifact content\",\n \"buildchain.toml web-surface channels/deploy/surfaces\",\n \"sourceSha\",\n \"artifactHash\",\n \"deployment channel\",\n \"deployment alias\"\n ],\n \"sourceRevision\": \"...\",\n \"timestampPolicyDetails\": {\n \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n \"timestampFieldsParticipateInArtifactDigest\": false,\n \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n },\n \"sourceSha\": \"...\",\n \"artifactHash\": \"...\",\n \"deployTarget\": \"libkungfu-dev-preview\",\n \"adapter\": \"aws-s3-cloudfront\",\n \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n \"retentionClass\": \"preview-sha-immutable\",\n \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n \"accessControl\": \"none\",\n \"edgeAuth\": \"none\",\n \"noindex\": true,\n \"secretRefs\": [\"AWS_ROLE_ARN\"],\n \"surfaceBindings\": [\n {\n \"surface\": \"hub\",\n \"channel\": \"preview\",\n \"alias\": \"sha-abcdef123456\",\n \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n \"sourcePath\": \"/\",\n \"canonicalUrl\": \"https://libkungfu.dev\",\n \"bucket\": \"libkungfu-dev-preview\",\n \"distributionId\": \"E-PREVIEW\",\n \"originPath\": \"\",\n \"objectPrefix\": \"sha-abcdef123456\",\n \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n \"noindex\": true,\n \"accessControl\": \"none\"\n }\n ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-plan \\\n --cwd fixtures/web-surface-shaped \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode manifest \\\n --cwd fixtures/web-surface-shaped \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --alias pr-123 \\\n --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-apply \\\n --cwd fixtures/web-surface-shaped \\\n --channel staging \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --artifact-path dist \\\n --dry-run false \\\n --output .buildchain/web-surface-staging-apply.json\n```\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode deploy-apply \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-staging-plan.json \\\n --dry-run false \\\n --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-apply \\\n --cwd fixtures/web-surface-shaped \\\n --event pull-request-closed \\\n --pull-number 123 \\\n --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n --dry-run false \\\n --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-apply \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-cleanup-plan.json \\\n --dry-run false \\\n --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, and every adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode production-preflight \\\n --cwd fixtures/web-surface-shaped \\\n --plan .buildchain/web-surface-production-plan.json \\\n --execute true \\\n --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode health-check \\\n --cwd fixtures/web-surface-shaped \\\n --result .buildchain/web-surface-production-apply.json \\\n --output .buildchain/web-surface-production-health.json\n```\n\nThe health check fetches every surface URL from the apply result and fails\nproduction if a response is unreachable, returns an unexpected status, or still\nsends `x-robots-tag: noindex`. It also verifies that each surface binding\nrecorded a deployment manifest pointer. The production release passport embeds\nthe deploy plan, apply result, production preflight, and health check so a\nreviewer or agent can audit why the production site changed and whether every\ndeclared host was actually covered.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n --mode cleanup-plan \\\n --cwd fixtures/web-surface-shaped \\\n --event pull-request-closed \\\n --pull-number 123 \\\n --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: npm run build\n verify-command: npm run check\n artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v2`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n workflow_dispatch:\n inputs:\n buildchain-ref:\n description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n required: false\n default: \"\"\n\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n build-command: pnpm run build\n verify-command: pnpm run check\n artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n contents: read\n id-token: write\n pull-requests: write\n\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: pnpm run build\n verify-command: pnpm run check\n artifact-path: dist\n preview-apply: true\n preview-cleanup-apply: true\n preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n staging-apply: true\n staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n production-apply: false\n production-release-on-main: false\n production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n production-environment: production\n release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n role, then write a staging release feedback passport artifact and comment the\n associated merged PR with the staging URL, source SHA, artifact identity, run\n URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n update a Buildchain-owned release PR from\n `release/<channel>-<short-sha>` to `main`, unless the current push already\n came from a matching release PR merge. The release PR contains one empty\n release-intent commit, carries `production-release-label`, and includes the\n staging URLs, source SHA, artifact hash, and staging release-passport artifact\n link in the PR body.\n- Release pull requests that match the configured production gate get a\n Buildchain review comment with the staging URL and production target, so the\n operator can verify staging from the PR page and use merge as the approval\n action. Consumers do not need to hand-write `gh pr create` or production\n release-intent glue.\n- Production runs when `production-apply` is true and either:\n - a trusted `workflow_dispatch` passes `production-approved=true`; or\n - `production-release-on-main=true` and the `main` push commit is associated\n with exactly one same-repository, merged release pull request matching\n `production-release-label` and `production-release-head-prefix`.\n The production job is then gated by the configured GitHub Environment.\n- Production apply writes a production release feedback passport artifact and\n comments the release PR with the production URL, source SHA, artifact\n identity, run URL, rollback pointer, and failure context when apply did not\n complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n web-surface:\n uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n with:\n build-command: npm run build\n verify-command: npm run check\n artifact-path: dist\n production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}\n production-release-on-main: true\n production-release-label: buildchain-release\n production-release-head-prefix: release/\n production-release-branch-channel: production\n production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n production-environment: production\n```\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs or a production apply without `production-approved=true`\non manual dispatch fail immediately instead of spending the build and plan jobs\nfirst.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
|
|
1264
1269
|
},
|
|
1265
1270
|
{
|
|
1266
1271
|
"id": "fixture:infra-contract-aws-cdk-shaped",
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"contract": "kungfu-buildchain-site-manifest",
|
|
4
|
-
"generatedAt": "2026-07-07T09:
|
|
5
|
-
"publishedAt": "2026-07-07T09:
|
|
4
|
+
"generatedAt": "2026-07-07T09:52:33.653Z",
|
|
5
|
+
"publishedAt": "2026-07-07T09:52:33.653Z",
|
|
6
6
|
"reproducible": true,
|
|
7
7
|
"timestampPolicy": "ci-injected",
|
|
8
8
|
"deterministicInputs": [
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"declared Buildchain surface manifest contract"
|
|
20
20
|
],
|
|
21
21
|
"sourceDateEpoch": "0",
|
|
22
|
-
"sourceRevision": "
|
|
22
|
+
"sourceRevision": "1e40482d191fe9dbd014c96c252867b65c71e0b9",
|
|
23
23
|
"timestampPolicyDetails": {
|
|
24
24
|
"contract": "kungfu-buildchain-surface-timestamp-policy",
|
|
25
25
|
"timestampFields": [
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
},
|
|
38
38
|
"package": {
|
|
39
39
|
"name": "@kungfu-tech/buildchain",
|
|
40
|
-
"version": "2.8.
|
|
40
|
+
"version": "2.8.9-alpha.1",
|
|
41
41
|
"versionSource": "package.json#version"
|
|
42
42
|
},
|
|
43
43
|
"entrypoint": "buildchain-site.json",
|
|
@@ -213,7 +213,7 @@
|
|
|
213
213
|
"path": "docs/web-surface-deployments.md",
|
|
214
214
|
"plane": "use",
|
|
215
215
|
"exists": true,
|
|
216
|
-
"digest": "sha256:
|
|
216
|
+
"digest": "sha256:f42cc7a81dbeb1b31bec21de61e9807af317bda4055f693ab807b15d9ec77367"
|
|
217
217
|
}
|
|
218
218
|
],
|
|
219
219
|
"facts": [
|
|
@@ -151,6 +151,38 @@ Buildchain validates these hard constraints:
|
|
|
151
151
|
- secret material must be declared as reference names, such as
|
|
152
152
|
`secret_refs = ["AWS_ROLE_ARN"]`; inline secret-like deploy keys are rejected.
|
|
153
153
|
|
|
154
|
+
### Floating Runtime Contract Lock
|
|
155
|
+
|
|
156
|
+
Web-surface repositories can consume the stable Buildchain workflow shell with a
|
|
157
|
+
floating ref, such as:
|
|
158
|
+
|
|
159
|
+
```yaml
|
|
160
|
+
jobs:
|
|
161
|
+
web:
|
|
162
|
+
uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
|
|
163
|
+
with:
|
|
164
|
+
buildchain-contract-lock-path: buildchain.contract-lock.json
|
|
165
|
+
buildchain-contract-compatibility-policy: major-compatible
|
|
166
|
+
buildchain-contract-drift-issue-mode: compatible-and-breaking
|
|
167
|
+
build-command: pnpm build
|
|
168
|
+
artifact-path: dist
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The caller repository commits `buildchain.contract-lock.json` after reviewing an
|
|
172
|
+
accepted Buildchain runtime SHA and contract digest. The reusable workflow then
|
|
173
|
+
resolves the floating runtime to an immutable SHA, checks the lock before the
|
|
174
|
+
caller build command, and applies these rules:
|
|
175
|
+
|
|
176
|
+
- unchanged lock: continue without feedback;
|
|
177
|
+
- compatible drift: continue, write the drift summary, and open or update a
|
|
178
|
+
caller-repository issue when permissions allow;
|
|
179
|
+
- breaking drift: fail closed before rendering, deployment planning, deploy
|
|
180
|
+
apply, or release publication.
|
|
181
|
+
|
|
182
|
+
The caller no longer needs to run `scripts/buildchain-contract-lock.mjs` inside
|
|
183
|
+
its own build command. That check belongs to Buildchain because the actual
|
|
184
|
+
contract world is stored in the Buildchain runtime ref being used.
|
|
185
|
+
|
|
154
186
|
Supported adapter names are:
|
|
155
187
|
|
|
156
188
|
| Adapter | Initial use |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kungfu-tech/buildchain",
|
|
3
|
-
"version": "2.8.
|
|
3
|
+
"version": "2.8.9-alpha.1",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
|
|
6
6
|
"repository": "https://github.com/kungfu-systems/buildchain",
|
|
@@ -142,6 +142,43 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
|
|
|
142
142
|
"GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes",
|
|
143
143
|
],
|
|
144
144
|
}),
|
|
145
|
+
surface(root, {
|
|
146
|
+
id: "web-surface",
|
|
147
|
+
kind: "workflow",
|
|
148
|
+
path: ".github/workflows/.web-surface.yml",
|
|
149
|
+
publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/.web-surface.yml@${majorLine}`,
|
|
150
|
+
requiredInputs: [],
|
|
151
|
+
requiredOutputs: [
|
|
152
|
+
"buildchain-runtime-sha",
|
|
153
|
+
"web-surface-channel",
|
|
154
|
+
"web-surface-url",
|
|
155
|
+
"web-surface-manifest-json",
|
|
156
|
+
],
|
|
157
|
+
breakingDefaults: {
|
|
158
|
+
buildchainRefDefault: "workflow-shell-ref-or-v2",
|
|
159
|
+
contractCompatibilityPolicy: "major-compatible",
|
|
160
|
+
breakingDriftPolicy: "fail-closed-before-build",
|
|
161
|
+
},
|
|
162
|
+
optionalInputs: [
|
|
163
|
+
"buildchain-ref",
|
|
164
|
+
"buildchain-contract-lock-path",
|
|
165
|
+
"buildchain-contract-compatibility-policy",
|
|
166
|
+
"buildchain-contract-drift-issue-mode",
|
|
167
|
+
"build-command",
|
|
168
|
+
"verify-command",
|
|
169
|
+
"artifact-path",
|
|
170
|
+
"preview-apply",
|
|
171
|
+
"staging-apply",
|
|
172
|
+
"production-apply",
|
|
173
|
+
"production-release-on-main",
|
|
174
|
+
],
|
|
175
|
+
guarantees: [
|
|
176
|
+
"runtime floating refs are resolved to immutable SHAs before caller build and deploy work",
|
|
177
|
+
"contract drift is checked before caller build, web-surface render, deploy planning, and apply side effects",
|
|
178
|
+
"compatible contract drift continues and produces a consumer issue or summary",
|
|
179
|
+
"breaking contract drift fails closed before rendering, deployment, or release publication",
|
|
180
|
+
],
|
|
181
|
+
}),
|
|
145
182
|
surface(root, {
|
|
146
183
|
id: "promote-buildchain-ref-action",
|
|
147
184
|
kind: "action",
|