@kungfu-tech/buildchain 4.1.3 → 4.1.4-alpha.0

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.
Files changed (199) hide show
  1. package/AGENTS.md +11 -13
  2. package/CONTRIBUTING.md +32 -9
  3. package/README.md +56 -140
  4. package/actions/release/promotion/ref/README.md +1 -1
  5. package/architecture/action-taxonomy.json +1 -1
  6. package/architecture/agent-change-map.md +32 -45
  7. package/architecture/build-orchestration.json +1 -1
  8. package/architecture/capability-state-machine-manifest.json +5 -5
  9. package/architecture/ci-lane-change-budget.json +92 -92
  10. package/architecture/code-layout.json +2 -12
  11. package/architecture/core-mechanisms.json +38 -39
  12. package/architecture/cross-platform-adopter-qualification.json +1 -1
  13. package/architecture/dev-delivery-orchestration.json +2 -2
  14. package/architecture/floating-consumer-policy.json +3 -3
  15. package/architecture/internal-capabilities.json +27 -28
  16. package/architecture/maintainability-debt.json +60 -94
  17. package/architecture/maintainability-policy.json +7 -13
  18. package/architecture/minimal-consumer-migration.json +43 -5014
  19. package/architecture/platform-stage-checkpoints.json +1 -1
  20. package/architecture/release-tail-contract.json +2 -2
  21. package/architecture/release-topology.json +31 -25
  22. package/architecture/stage-capsule-qualification.json +1 -1
  23. package/architecture/universal-workflow-bootstrap.json +60 -60
  24. package/architecture/universal-workflow-capability-policy.json +3 -3
  25. package/architecture/universal-workflow-fault-campaign.json +7 -7
  26. package/architecture/workflow-taxonomy.json +59 -60
  27. package/contracts/fixtures/v4-tail-reseal-v1/valid.json +1 -1
  28. package/dist/site/buildchain-contract.json +138 -66
  29. package/dist/site/buildchain-site.json +257 -331
  30. package/dist/site/capability-registry.json +4 -4
  31. package/dist/site/cli-registry.json +6 -142
  32. package/dist/site/controller-registry.json +19 -19
  33. package/dist/site/kfd-claims.json +481 -529
  34. package/dist/site/kfd-upstream-aggregate.json +1 -1
  35. package/dist/site/manual-registry.json +22 -22
  36. package/dist/site/node-api-registry.json +82 -339
  37. package/dist/site/page-registry.json +229 -304
  38. package/dist/site/public-surface-audit.json +544 -754
  39. package/dist/site/publication-authority-registry.json +316 -316
  40. package/dist/site/publication-registry.json +1 -1
  41. package/dist/site/site-manifest.json +23 -23
  42. package/dist/site/workflow-registry.json +1071 -1027
  43. package/docs/MAP.md +28 -20
  44. package/docs/auditable-demo.md +17 -49
  45. package/docs/bootstrap-recovery.md +46 -37
  46. package/docs/cli-reference.md +2 -46
  47. package/docs/cli.md +97 -186
  48. package/docs/code-organization.md +7 -5
  49. package/docs/dev-alpha-candidate-patrol.md +19 -42
  50. package/docs/dev-delivery-orchestration.md +15 -11
  51. package/docs/dev-delivery-qualification-landing-adr.md +10 -9
  52. package/docs/dev-delivery-warrant.md +17 -16
  53. package/docs/dev-qualification-patrol.md +25 -20
  54. package/docs/getting-started.md +80 -139
  55. package/docs/github-artifact-attestation.md +31 -81
  56. package/docs/install.md +66 -30
  57. package/docs/lifecycle-protocol.md +19 -57
  58. package/docs/migration-inventory.md +17 -45
  59. package/docs/next-development-transition.md +13 -13
  60. package/docs/node-api-reference.md +122 -138
  61. package/docs/oci-publication.md +13 -10
  62. package/docs/publication-artifacts.md +128 -486
  63. package/docs/publication-authority.md +15 -45
  64. package/docs/publish-transaction.md +13 -11
  65. package/docs/release-candidate.md +126 -355
  66. package/docs/release-discussions.md +36 -67
  67. package/docs/release-flow.md +80 -339
  68. package/docs/release-governance.md +114 -962
  69. package/docs/release-promotion-request.md +45 -43
  70. package/docs/release-propagation.md +13 -27
  71. package/docs/release-tail-provider-plane.md +38 -65
  72. package/docs/reusable-build-surface.md +78 -196
  73. package/docs/runtime-train-validation.md +8 -6
  74. package/docs/stable-candidate-patrol.md +13 -66
  75. package/docs/v4-adopter-delivery.md +15 -15
  76. package/docs/v4-declarative-release-tail-migration.md +19 -17
  77. package/docs/v4-production-release.md +11 -6
  78. package/docs/v4-publication-rehearsal.md +12 -27
  79. package/docs/v4-stage-capsule.md +14 -20
  80. package/docs/v4-tail-reseal.md +34 -20
  81. package/docs/web-surface-deployments.md +26 -264
  82. package/docs/workflow-catalog.md +31 -31
  83. package/docs/workflow-path-migration.md +10 -4
  84. package/package.json +5 -4
  85. package/packages/core/adoption/buildchain-kfd-claims.js +7 -7
  86. package/packages/core/adoption/cli/output.mjs +1 -9
  87. package/packages/core/adoption/cli/product-gate.mjs +1 -15
  88. package/packages/core/adoption/cli/project.mjs +9 -10
  89. package/packages/core/adoption/cli/standards.mjs +1 -14
  90. package/packages/core/adoption/cli/support.mjs +0 -2
  91. package/packages/core/adoption/cli/surface-register.mjs +0 -2
  92. package/packages/core/adoption/commands/init-repo.mjs +77 -485
  93. package/packages/core/adoption/consumer-init.js +279 -0
  94. package/packages/core/adoption/qualification/admission.js +1 -1
  95. package/packages/core/build/cli/cache.mjs +0 -2
  96. package/packages/core/build/cli/facts.mjs +0 -3
  97. package/packages/core/build/cli/homebrew.mjs +0 -4
  98. package/packages/core/build/cli/lifecycle.mjs +0 -3
  99. package/packages/core/build/github-artifact-attestation.js +2 -2
  100. package/packages/core/build/platform-stage-checkpoints.js +1 -1
  101. package/packages/core/build/signing/dispatch.js +1 -1
  102. package/packages/core/consumer/buildchain-config.js +9 -0
  103. package/packages/core/consumer/contract/inspection.js +351 -9
  104. package/packages/core/consumer/contract/javascript-syntax.js +439 -0
  105. package/packages/core/consumer/contract/javascript-values.js +61 -0
  106. package/packages/core/consumer/contract/javascript.js +555 -0
  107. package/packages/core/consumer/contract/local-validation.js +84 -0
  108. package/packages/core/contracts/buildchain-contract.js +39 -8
  109. package/packages/core/contracts/cli/introspection.mjs +1 -9
  110. package/packages/core/contracts/public-surface-cli.js +0 -1
  111. package/packages/core/dev-delivery/dev-delivery-contract-surface.js +2 -2
  112. package/packages/core/governance/buildchain-publication-authority.js +24 -24
  113. package/packages/core/governance/cli/doctor.mjs +58 -42
  114. package/packages/core/governance/commands/architecture.mjs +6 -1
  115. package/packages/core/governance/commands/audit-publication-control-plane.mjs +1 -1
  116. package/packages/core/governance/commands/workflow-friction-report.mjs +1 -1
  117. package/packages/core/governance/github-governance-authority.js +2 -2
  118. package/packages/core/governance/publication/collection.js +1 -1
  119. package/packages/core/index.js +1 -3
  120. package/packages/core/observability/cli/candidate.mjs +0 -2
  121. package/packages/core/observability/cli/context.mjs +0 -5
  122. package/packages/core/observability/cli/diagnostics.mjs +0 -7
  123. package/packages/core/observability/cli/events.mjs +2 -10
  124. package/packages/core/paper/commands/paper-work-fleet-cli.mjs +1 -1
  125. package/packages/core/paper/commands/paper.mjs +33 -422
  126. package/packages/core/paper/consumer-status.js +72 -0
  127. package/packages/core/paper/operations/identity.js +0 -3
  128. package/packages/core/paper/operations/migration.js +460 -0
  129. package/packages/core/paper/operations/preflight-checks.js +8 -68
  130. package/packages/core/paper/operations/scaffold.js +16 -326
  131. package/packages/core/paper/operations/status.js +27 -53
  132. package/packages/core/paper/paper-agent-entry.js +36 -147
  133. package/packages/core/paper/paper-fleet.js +24 -39
  134. package/packages/core/paper/paper-repository.js +16 -0
  135. package/packages/core/paper/paper-runtime-channels.js +1 -1
  136. package/packages/core/paper/paper-scaffold-content.js +153 -162
  137. package/packages/core/paper/paper-work.js +3 -10
  138. package/packages/core/paper/paper.js +43 -5
  139. package/packages/core/providers/github/artifact-attestation.js +1 -1
  140. package/packages/core/providers/github/pipeline-context-artifacts.js +172 -0
  141. package/packages/core/publication/authority/control-plane.js +2 -2
  142. package/packages/core/publication/authority/seal.js +1 -1
  143. package/packages/core/publication/cli/dispatch.mjs +1 -12
  144. package/packages/core/publication/pipeline/actions.js +16 -9
  145. package/packages/core/publication/pipeline/apply.js +17 -9
  146. package/packages/core/publication/pipeline/context.js +29 -0
  147. package/packages/core/publication/pipeline/prepare.js +15 -6
  148. package/packages/core/publication/pipeline/recovery-materials.js +63 -1
  149. package/packages/core/publication/pipeline/recovery-prepare.js +21 -9
  150. package/packages/core/publication/pipeline/stable-entry.js +12 -7
  151. package/packages/core/publication/pipeline/stable-products.js +21 -19
  152. package/packages/core/publication/pipeline/version-actions.js +15 -6
  153. package/packages/core/publication/publication-rehearsal-projection.js +0 -9
  154. package/packages/core/release/cli/dispatch.mjs +1 -4
  155. package/packages/core/release/cli/inspection-handlers.mjs +1 -33
  156. package/packages/core/release/cli/release-handlers.mjs +2 -19
  157. package/packages/core/release/cli/verification-handlers.mjs +4 -25
  158. package/packages/core/release/next-development-projection.js +13 -13
  159. package/packages/core/release/passport/locations.js +13 -8
  160. package/packages/core/release/release-passport.js +70 -5
  161. package/packages/core/web/cli/badges.mjs +0 -4
  162. package/packages/core/web/publication-admission.js +1 -1
  163. package/packages/core/web/publication-capability.js +1 -1
  164. package/packages/core/web/readme-badges.js +1 -1
  165. package/packages/core/workflow/cli/main.mjs +1 -4
  166. package/packages/core/workflow/cli/process.mjs +1 -1
  167. package/packages/core/workflow/commands/buildchain-cli-help.mjs +2 -8
  168. package/packages/core/workflow/engine/conformance.js +1 -1
  169. package/packages/core/workflow/pipeline/build.js +21 -1
  170. package/packages/core/workflow/pipeline/delivery-observation.js +6 -2
  171. package/packages/core/workflow/workflow-taxonomy.mjs +61 -17
  172. package/scripts/check-code-layout.mjs +2 -0
  173. package/scripts/check-core-mechanism-inventory.mjs +29 -13
  174. package/scripts/check-floating-consumer-policy-contract.mjs +3 -3
  175. package/scripts/check-inventory.mjs +27 -27
  176. package/scripts/check-maintainability.mjs +28 -5
  177. package/scripts/check-public-dogfood-contract.mjs +3 -3
  178. package/scripts/check-release-topology.mjs +1 -1
  179. package/scripts/check-self-consumer-contract.mjs +7 -7
  180. package/scripts/check-universal-workflow-bootstrap.mjs +1 -1
  181. package/scripts/generate-channel-promotion-workflow.mjs +1 -1
  182. package/scripts/generate-minimal-consumer-contract.mjs +21 -1
  183. package/scripts/generate-site-bundle.mjs +2 -1
  184. package/scripts/generate-tail-reseal-fixture.mjs +3 -3
  185. package/scripts/inventory/promotion.mjs +1 -1
  186. package/scripts/next-development-self-dogfood-harness.mjs +1 -1
  187. package/scripts/next-development-self-dogfood.mjs +4 -4
  188. package/scripts/site-capability-metadata.mjs +2 -6
  189. package/scripts/source-metric-lineage.mjs +62 -7
  190. package/scripts/verify-golden-path.mjs +31 -35
  191. package/templates/native-dev-delivery.yml +1 -1
  192. package/templates/universal-buildchain-bootstrap.yml +1 -1
  193. package/packages/core/paper/operations/bootstrap.js +0 -75
  194. package/packages/core/paper/operations/plans.js +0 -213
  195. package/packages/core/paper/operations/provisioning.js +0 -113
  196. package/packages/core/paper/operations/scaffold-config.js +0 -77
  197. package/packages/core/paper/operations/scaffold-workflows.js +0 -116
  198. package/packages/core/paper/operations/workspace.js +0 -60
  199. package/packages/core/paper/paper-npm-bootstrap.js +0 -492
@@ -1,77 +0,0 @@
1
- import { appendNextDevelopmentToml } from "../../release/next-development-projection.js";
2
- import {
3
- DEFAULT_TOOLCHAIN_IMAGE,
4
- DEFAULT_TOOLCHAIN_DIGEST,
5
- DEFAULT_TOOLCHAIN_COMMAND,
6
- } from "./identity.js";
7
- export function tomlString(value) {
8
- return JSON.stringify(String(value || ""));
9
- }
10
- export function joinUrl(base, suffix = "") {
11
- const normalizedBase = String(base || "")
12
- .trim()
13
- .replace(/\/+$/, "");
14
- const normalizedSuffix = String(suffix || "")
15
- .trim()
16
- .replace(/^\/+|\/+$/g, "");
17
- if (!normalizedBase) return "";
18
- return normalizedSuffix
19
- ? `${normalizedBase}/${normalizedSuffix}/`
20
- : `${normalizedBase}/`;
21
- }
22
- export function scaffoldConfig({
23
- name,
24
- title,
25
- packageName,
26
- version,
27
- siteBaseUrl,
28
- }) {
29
- const archiveId = name.replace(/^paper-/, "");
30
- const canonicalUrl = joinUrl(siteBaseUrl, archiveId);
31
- const archive = canonicalUrl
32
- ? `
33
- [publication.archive]
34
- id = ${tomlString(archiveId)}
35
- canonical_url = ${tomlString(canonicalUrl)}
36
- latest_url = ${tomlString(joinUrl(canonicalUrl, "latest"))}
37
- latest_evidence_url = ${tomlString(`${joinUrl(canonicalUrl, "latest")}buildchain.release.json`)}
38
- immutable_base_url = ${tomlString(joinUrl(siteBaseUrl, "archive").replace(/\/$/, ""))}
39
- registry_path = ".buildchain/publication/publication-registry.json"
40
- `
41
- : "";
42
- return appendNextDevelopmentToml(`schema = 1
43
-
44
- [project]
45
- type = "publication-artifact"
46
- name = ${tomlString(name)}
47
-
48
- [publication]
49
- kind = "paper"
50
- title = ${tomlString(title)}
51
- version = ${tomlString(version)}
52
- primary_artifact = "_build/main.pdf"
53
- artifact_paths = ["_build/main.pdf"]
54
- metadata_paths = ["README.md", "docs/MAP.md"]
55
- source_paths = ["paper", "README.md", "LICENSE", "Makefile"]
56
- site_consumers = ${siteBaseUrl ? `[${tomlString(siteBaseUrl)}]` : "[]"}
57
- manifest_path = ".buildchain/publication/publication-artifact.json"
58
- source_bundle_path = ".buildchain/publication/source.tar.gz"
59
- ${archive}
60
- [publication.toolchain]
61
- type = "latex-docker"
62
- image = "${DEFAULT_TOOLCHAIN_IMAGE}"
63
- digest = "${DEFAULT_TOOLCHAIN_DIGEST}"
64
- command = "${DEFAULT_TOOLCHAIN_COMMAND}"
65
-
66
- [publish]
67
- kind = "npm-paper-package"
68
- package = ${tomlString(packageName)}
69
- auth = "trusted-publishing"
70
-
71
- [lifecycle.build]
72
- command = "make pdf"
73
-
74
- [lifecycle.verify]
75
- command = "make check"
76
- `);
77
- }
@@ -1,116 +0,0 @@
1
- import { nextDevelopmentWorkflowHeader } from "../../release/next-development-projection.js";
2
- export function scaffoldBuildWorkflow(
3
- entryRef,
4
- { artifactName = "paper-publication" } = {},
5
- ) {
6
- return `${nextDevelopmentWorkflowHeader()}name: Build
7
-
8
- on:
9
- workflow_dispatch:
10
- inputs:
11
- runtime-ref:
12
- description: Transient execution runtime; empty selects the consumer lock.
13
- required: false
14
- default: ""
15
- pull_request:
16
- push:
17
- branches:
18
- - "dev/**"
19
- - "alpha/**"
20
- - "release/**"
21
-
22
- permissions:
23
- contents: read
24
- issues: write
25
-
26
- jobs:
27
- publication:
28
- uses: kungfu-systems/buildchain/.github/workflows/public-build-publication.yml@${entryRef}
29
- with:
30
- runtime-ref: \${{ inputs.runtime-ref || '' }}
31
- contract-lock: .buildchain/contract-lock.json
32
- toolchain-type: config
33
- verify-command: make check
34
- artifact-name: ${JSON.stringify(artifactName)}
35
- `;
36
- }
37
- export function scaffoldVerifyWorkflow(entryRef) {
38
- return `${nextDevelopmentWorkflowHeader()}name: Verify
39
-
40
- on:
41
- pull_request:
42
- push:
43
- branches:
44
- - "dev/v*/v*"
45
- - "alpha/v*/v*"
46
- - "release/v*/v*"
47
- workflow_dispatch:
48
- inputs:
49
- runtime-ref:
50
- description: Transient execution runtime; empty selects the consumer lock.
51
- required: false
52
- default: ""
53
-
54
- permissions:
55
- actions: read
56
- contents: read
57
- pull-requests: read
58
-
59
- jobs:
60
- check:
61
- uses: kungfu-systems/buildchain/.github/workflows/public-build-check.yml@${entryRef}
62
- with:
63
- runtime-ref: \${{ inputs.runtime-ref || '' }}
64
- require-version-state: true
65
- upload-artifacts: true
66
- `;
67
- }
68
- export function scaffoldReleaseWorkflow(
69
- entryRef,
70
- { artifactPaths = "_build/main.pdf", releasePassportProductName = "" } = {},
71
- ) {
72
- const passportInput = releasePassportProductName
73
- ? ` release-passport-product-name: ${JSON.stringify(releasePassportProductName)}\n`
74
- : "";
75
- return `${nextDevelopmentWorkflowHeader()}name: Paper Release
76
-
77
- on:
78
- workflow_dispatch:
79
- inputs:
80
- runtime-ref:
81
- description: Transient execution runtime; empty selects the consumer lock.
82
- required: false
83
- default: ""
84
- push:
85
- branches:
86
- - "alpha/**"
87
- - "release/**"
88
-
89
- permissions:
90
- contents: read
91
-
92
- jobs:
93
- paper-release:
94
- uses: kungfu-systems/buildchain/.github/workflows/public-release-paper.yml@${entryRef}
95
- permissions:
96
- actions: read
97
- checks: write
98
- contents: read
99
- id-token: write
100
- issues: write
101
- pull-requests: write
102
- with:
103
- runtime-ref: \${{ inputs.runtime-ref || '' }}
104
- contract-lock: .buildchain/contract-lock.json
105
- publisher-workflow-path: .github/workflows/public-release-paper.yml
106
- toolchain-type: config
107
- verify-command: make check
108
- artifact-paths: ${JSON.stringify(artifactPaths)}
109
- ${passportInput} secrets:
110
- KUNGFU_GOVERNANCE_AUDITOR_APP_PRIVATE_KEY: \${{ secrets.KUNGFU_GOVERNANCE_AUDITOR_APP_PRIVATE_KEY }}
111
- BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}
112
- BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}
113
- BUILDCHAIN_GENERATED_WRITE_TOKEN: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_TOKEN }}
114
- BUILDCHAIN_PROMOTION_TOKEN: \${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
115
- `;
116
- }
@@ -1,60 +0,0 @@
1
- import { BUILDCHAIN_PACKAGE_NAME } from "./identity.js";
2
- export function paperPnpmWorkspace(current, buildchainVersion) {
3
- const entry = `${BUILDCHAIN_PACKAGE_NAME}@${buildchainVersion}`;
4
- const source = String(current || "");
5
- const lines = source ? source.replace(/\r\n/g, "\n").split("\n") : [];
6
- if (lines.at(-1) === "") lines.pop();
7
- const keyLines = lines
8
- .map((line, index) =>
9
- /^minimumReleaseAgeExclude:\s*(?:#.*)?$/.test(line) ? index : -1,
10
- )
11
- .filter((index) => index >= 0);
12
- const unsupportedKey = lines.some(
13
- (line) =>
14
- /^minimumReleaseAgeExclude\s*:/.test(line) &&
15
- !/^minimumReleaseAgeExclude:\s*(?:#.*)?$/.test(line),
16
- );
17
- if (unsupportedKey || keyLines.length > 1) {
18
- throw new Error(
19
- "paper migration requires minimumReleaseAgeExclude to be one top-level block sequence",
20
- );
21
- }
22
- if (keyLines.length === 0) {
23
- const prefix = lines.length > 0 ? [...lines, ""] : [];
24
- return `${[...prefix, "minimumReleaseAgeExclude:", ` - '${entry}'`].join(
25
- "\n",
26
- )}\n`;
27
- }
28
- const keyIndex = keyLines[0];
29
- let blockEnd = lines.length;
30
- for (let index = keyIndex + 1; index < lines.length; index += 1) {
31
- if (/^[^\s#]/.test(lines[index])) {
32
- blockEnd = index;
33
- break;
34
- }
35
- }
36
- const retained = [];
37
- for (const line of lines.slice(keyIndex + 1, blockEnd)) {
38
- if (!line.trim() || /^\s*#/.test(line)) {
39
- retained.push(line);
40
- continue;
41
- }
42
- const item = line.match(/^\s*-\s+(.+?)\s*(?:#.*)?$/);
43
- if (!item) {
44
- throw new Error(
45
- "paper migration requires minimumReleaseAgeExclude to contain scalar package entries",
46
- );
47
- }
48
- const value = item[1]
49
- .trim()
50
- .replace(/^'(.*)'$/, "$1")
51
- .replace(/^"(.*)"$/, "$1");
52
- if (!value.startsWith(`${BUILDCHAIN_PACKAGE_NAME}@`)) retained.push(line);
53
- }
54
- return `${[
55
- ...lines.slice(0, keyIndex + 1),
56
- ...retained,
57
- ` - '${entry}'`,
58
- ...lines.slice(blockEnd),
59
- ].join("\n")}\n`;
60
- }