@kungfu-tech/buildchain 3.0.3-alpha.1 → 3.0.3-alpha.3

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/README.md CHANGED
@@ -197,13 +197,18 @@ Bootstrap and inspect a governed paper repository through one interface:
197
197
  npx @kungfu-tech/buildchain paper scaffold \
198
198
  --package @kungfu-tech/paper-example \
199
199
  --repository kungfu-systems/paper-example
200
- npx @kungfu-tech/buildchain paper preflight --offline
201
- npx @kungfu-tech/buildchain paper status
200
+ pnpm add -D @kungfu-tech/buildchain@<exact-v3-version>
201
+ pnpm exec buildchain paper work start <topic>
202
+ pnpm exec buildchain paper work submit
203
+ pnpm exec buildchain paper preflight --offline
204
+ pnpm exec buildchain paper status
202
205
  ```
203
206
 
204
207
  The paper surface is dry-run first. Add `--write` only to create missing
205
- scaffold files; external mutations such as npm bootstrap, Alpha PR creation,
206
- and release resumption require `--execute`. See
208
+ scaffold files. `work start` and `work submit` validate the canonical remote,
209
+ exact development SHA, clean source, safe branch, and fast-forward boundary
210
+ before changing local or GitHub state. External mutations such as npm
211
+ bootstrap, Alpha PR creation, and release resumption require `--execute`. See
207
212
  [`docs/publication-artifacts.md`](docs/publication-artifacts.md) for the
208
213
  evidence-state model and operator flow.
209
214
 
@@ -13,6 +13,7 @@ import { runPublicationArtifactCli } from "../scripts/publication-artifact.mjs";
13
13
  import { runPublicationPackageCli } from "../scripts/publication-package.mjs";
14
14
  import { runPublicationReproducibilityCli } from "../scripts/publication-reproducibility.mjs";
15
15
  import { runPaperCli } from "../scripts/paper.mjs";
16
+ import { BUILDCHAIN_USAGE } from "../scripts/buildchain-cli-help.mjs";
16
17
  import { validateBuildchainConfig } from "../packages/core/buildchain-config.js";
17
18
  import { detectPackageManager } from "../packages/core/package-manager.js";
18
19
  import {
@@ -110,261 +111,6 @@ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
110
111
  const embeddedPackageVersion = process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION || "";
111
112
  const embeddedSourceSha = process.env.BUILDCHAIN_EMBEDDED_SOURCE_SHA || "";
112
113
 
113
- function usage() {
114
- return `Usage:
115
- buildchain --help
116
- buildchain version
117
- buildchain layout [--cwd <dir>] [--json]
118
- buildchain portable-cache plan --manifest <file-or-json> [--output <file>]
119
- [--github-output <file>] [--json]
120
- buildchain portable-cache receipt --plan <file-or-json> [--matched-key <key>]
121
- [--cache-hit true|false]
122
- [--validation-status pass|fail]
123
- [--validation-reason <text>]
124
- [--cold-fallback-status not-run|passed|failed]
125
- [--output <file>] [--json]
126
- buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]
127
- buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force]
128
- [--package-manager pnpm|npm|yarn] [--runner-preset <preset>]
129
- [--artifact-name <template>]
130
- buildchain validate [--cwd <dir>] [--require-version-state]
131
- [--require-lifecycle-stages <comma-list>]
132
- buildchain lifecycle run <stage> [--cwd <dir>] [--required]
133
- [--artifact-name <name>] [--artifact-path <path>]...
134
- [--manifest-path <path>] [--summary-path <path>]
135
- [--process-summary <json>]
136
- buildchain npm dry-run [--cwd <dir>] [--expected-tag <tag>] [--registry <url>]
137
- [--dist-tag <tag>] [--skip-npm-publish-dry-run] [--json]
138
- buildchain release --dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
139
- [--tags <comma-list>] [--json]
140
- buildchain release explain --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
141
- [--tags <comma-list>] [--json]
142
- buildchain release dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
143
- [--tags <comma-list>] [--json]
144
- buildchain release line open --major <n> --minor <n> [--source-ref <ref>]
145
- [--initial-version <version>] [--write] [--json]
146
- buildchain release-governance reconcile --repository <owner/repo>
147
- --branch <dev|alpha|release/vN/vN.N>
148
- --candidate-sha <sha> [--apply] [--json]
149
- buildchain github-governance <plan|apply|rollback|protection-policy-plan|ruleset-policy-plan> ...
150
- buildchain release <inspect|recover|finalize|abort> ...
151
- buildchain transaction inspect ...
152
- buildchain collect github-release --tag <tag> [--repository <owner/repo>]
153
- [--assets-dir <dir>] [--assets-json <json-or-path>]
154
- [--release-json <json-or-path>] [--package-set-json <json-or-path>]
155
- [--product-name <name>]
156
- [--publish-evidence-json <json-or-path>]
157
- [--trusted-publishing-json <json-or-path>]
158
- [--transaction-json <json-or-path>]
159
- [--anchor-manifest-json <json-or-path>]
160
- [--impact-json <json-or-path>]
161
- [--build-summary-json <json-or-path>]
162
- [--build-facts-json <json-or-path>]...
163
- [--platform-manifest-json <json-or-path>]...
164
- [--dist-tag-evidence-json <json-or-path>]
165
- [--kfd-1-witness-json <json-or-path>]...
166
- [--kfd-2-claim-json <json-or-path>]...
167
- [--kfd-3-prebuild-witness-json <json-or-path>]...
168
- [--kfd-3-artifact-witness-json <json-or-path>]...
169
- [--kfd-3-artifact-verify-cmd <command>]
170
- [--kfd-support-matrix-json <json-or-path>]
171
- [--kfd-product-gate-json <json-or-path>]...
172
- [--invariant-passport-json <json-or-path>]...
173
- [--invariant-passport-cmd <command>]
174
- [--release-evidence-json <json-or-path>]...
175
- [--github-artifact-attestation-policy-json <json-or-path>]...
176
- [--kfd-agent-hub-evidence-json <json-or-path>]
177
- [--base-passport-json <json-or-path>] [--require-base-kfd]
178
- [--release-extra-json <json-or-path>]
179
- [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
180
- buildchain create publication-admission --input-json <file-or-json> [--output <file>] [--json]
181
- buildchain create runner-provenance --input-json <file-or-json> [--output <file>] [--json]
182
- buildchain create github-artifact-attestation-policy --input-json <file-or-json> [--output <file>] [--json]
183
- buildchain verify release-passport <file-or-url> [--json]
184
- buildchain verify github-artifact-attestation <artifact>
185
- --evidence <file> --bundle <file>
186
- --platform-manifest <file> --release-passport <file> [--json]
187
- buildchain verify publication-admission <file-or-json>
188
- --registry-json <file-or-json>
189
- --runner-json <file-or-json>
190
- --control-plane-audit-json <file-or-json>
191
- --publication-evidence-json <file-or-json>
192
- [--expected-json <file-or-json>] [--used-nonce <nonce>]... [--json]
193
- buildchain audit publication-control-plane --repository <owner/repo> --branch <protected-branch>
194
- buildchain audit github-governance [--organization <owner>] [--repository <owner/repo>]
195
- [--output <file>] [--require-qualifying] [--json]
196
- [--source-sha <merged-branch-sha>] [--workflow-repository <owner/repo>]
197
- [--workflow <path>] [--workflow-ref <sha-or-ref>]
198
- [--job <id>] [--environment <name>] [--package <name>]
199
- [--publisher-mode npm-trusted-publisher|github-token|oidc-role]
200
- [--npm-trust-json <file-or-json>]
201
- [--provider-audit-json <file>] [--output <file>] [--allow-nonqualifying]
202
- buildchain verify artifact <file|dir|url|npm:...|oci:...|github-release:...>
203
- [--passport <file-or-url>] [--locator-config <json>]
204
- [--repository <owner/repo>] [--tag <tag>]
205
- [--npm-registry <url>] [--json]
206
- buildchain verify artifact-envelope <file-or-json> [--assessment-time <epoch>]
207
- [--expected-root <sha256:...>] [--expected-issuer <issuer>]
208
- [--expected-publisher <publisher>]
209
- [--expected-contract <version>] [--json]
210
- buildchain project kfx-admission <file-or-json> [--assessment-time <epoch>]
211
- [--expected-root <sha256:...>] [--expected-issuer <issuer>]
212
- [--expected-publisher <publisher>]
213
- [--expected-contract <version>] [--json]
214
- buildchain verify infra-contract-evidence-bundle <file> [--json]
215
- buildchain verify observability-log <jsonl> [--min-events <n>]
216
- [--require-phase <csv>]
217
- [--require-component <csv>]
218
- [--require-event <csv>] [--allow-errors] [--json]
219
- buildchain explain release --passport <file-or-url> [--for human|agent] [--json]
220
- buildchain explain artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--for human|agent] [--json]
221
- buildchain inspect release --passport <file-or-url> [--json]
222
- buildchain inspect artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--json]
223
- buildchain doctor [--cwd <dir>] [--require-publish-source-lock] [--json]
224
- buildchain dev merge-queue --repository <owner/repo> --branch <dev/vN/vN.M>
225
- [--from-config | --workflow <required-workflow.yml>...] [--cwd <dir>]
226
- [--check-response-timeout-minutes <n>]
227
- [--max-entries-to-build <n>] [--apply]
228
- buildchain log <info|warn|error> --event <name> [--phase <phase>]
229
- [--component <name>] [--source <name>] [--attribute key=value]...
230
- [--path <jsonl>] [--json]
231
- buildchain log summary [--path <jsonl>] [--json]
232
- buildchain diagnostics summary <diagnostics.json>... [--artifact <file>]...
233
- [--output <file>] [--json]
234
- buildchain facts module [--cwd <dir>] [--module <id>] [--module-root <path>]
235
- [--version-source <id>] [--output <file>]
236
- [--output-path <path>]... [--legacy-kungfu-buildinfo <file>] [--json]
237
- buildchain facts aggregate [--cwd <dir>] [--product <id>]
238
- [--module-fact <file>]... [--artifact <path>]...
239
- [--output <file>] [--json]
240
- buildchain facts verify [--cwd <dir>] --fact <file> [--json]
241
- buildchain kfd ...
242
- buildchain kfd hub <init|inspect|test|explain> [--cwd <dir>]
243
- [--declaration <path>] [--output-dir <path>]
244
- [--write] [--force] [--for agent] [--json]
245
- buildchain kfd status [--cwd <dir>] [--json]
246
- buildchain kfd migrate-layout [--cwd <dir>] [--write] [--force] [--json]
247
- buildchain kfd schema list [--standard kfd-1|kfd-2|kfd-3|kfd-4] [--json]
248
- buildchain kfd schema show <kfd-1|kfd-2|kfd-3|kfd-4> [--schema <name>] [--json]
249
- buildchain kfd upstream roles [--json]
250
- buildchain kfd upstream collect [--cwd <dir>] [--output <file>] [--json]
251
- buildchain kfd upstream check [--cwd <dir>] [--aggregate-json <file-or-json>] [--json]
252
- buildchain kfd aggregate [--cwd <dir>] [--json]
253
- buildchain kfd 1 schema [--schema <name>] [--json]
254
- buildchain kfd 1 witness [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--json]
255
- buildchain kfd 1 gate --witness-json <file-or-json>... [--cwd <dir>] [--artifact-root <dir>]
256
- [--output <file>] [--json]
257
- buildchain kfd 1 verify --gate-json <file-or-json> [--json]
258
- buildchain kfd 2 schema [--schema <name>] [--json]
259
- buildchain kfd 2 taxonomy --entry-json <file-or-json>... [--kind residualRisk|downgradeReason] [--json]
260
- buildchain kfd 2 claims [--cwd <dir>] [--output-dir <dir>] [--json]
261
- buildchain kfd 2 product-claims <check|write|render> [--cwd <dir>] [--registry <path>]
262
- [--output-dir <dir>] [--version <version>]
263
- [--channel <channel>] [--tag <tag>] [--source-sha <sha>] [--json]
264
- buildchain kfd 2 trust-claims [--claims-json <file-or-json>] [--json]
265
- buildchain kfd 2 trust-assessment [--assessment-json <file-or-json>] [--json]
266
- buildchain kfd 3 ...
267
- buildchain kfd 3 detect [--cwd <dir>] [--kind <kind>]... [--artifact <path>] [--json]
268
- buildchain kfd 3 register <node-api|python-api|cli|binary|documentation|site-bundle>
269
- [--cwd <dir>] [--registry <path>] [--artifact <path>]
270
- [--product <name>] [--json]
271
- buildchain kfd 3 audit [--cwd <dir>] [--registry <path>] [--artifact <path>] [--json]
272
- buildchain kfd 3 witness [--cwd <dir>] [--registry <path>] [--kind prebuild|artifact]
273
- [--source-sha <sha>] [--artifact <path>] [--output <file>] [--json]
274
- buildchain kfd 3 query [<product>] [--cwd <dir>] [--registry <path>]
275
- [--passport <file-or-url>] [--artifact <path>] [--json]
276
- buildchain kfd 4 schema [--schema <name>] [--json]
277
- buildchain kfd 4 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
278
- buildchain kfd 4 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
279
- buildchain kfd 5 schema [--schema <name>] [--json]
280
- buildchain kfd 5 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
281
- buildchain kfd 5 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
282
- buildchain kfd 7 schema [--schema <name>] [--json]
283
- buildchain kfd 7 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
284
- buildchain kfd 7 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
285
- buildchain kfd support project --matrix-json <file-or-json> --gate-json <file-or-json>...
286
- [--expected-source-sha <sha>] [--checked-at <date-time>]
287
- [--output <file>] [--json]
288
- buildchain kfd support verify --projection-json <file-or-json>
289
- [--expected-source-sha <sha>] [--checked-at <date-time>] [--json]
290
- buildchain sample process-tree [--interval-ms <n>] [--label <name>]
291
- [--output <jsonl>] [--summary-output <json>]
292
- [--requested-parallelism <n>] [--json]
293
- -- <command> [args...]
294
- buildchain mark --event <name> [--phase <phase>] [--component <name>]
295
- [--attribute key=value]... [--path <jsonl>] [--json]
296
- buildchain span --event <name> [--phase <phase>] [--component <name>]
297
- [--path <jsonl>] -- <command> [args...]
298
- buildchain web-surface ...
299
- buildchain infra-contract ...
300
- buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>]
301
- [--output <file>] [--passport-output <file>]
302
- [--registry-output <file>] [--source-bundle <file>]
303
- [--no-source-bundle] [--json]
304
- buildchain publication-artifact npm-package [--cwd <dir>] [--output-dir <dir>] [--package-name <name>] [--json]
305
- buildchain publication-artifact reproducibility [--cwd <dir>] [--source-sha <sha>]
306
- [--output <file>] [--promote]
307
- [--no-toolchain-pull]
308
- [--allow-unpinned-toolchain] [--json]
309
- buildchain paper scaffold --package <name> --repository <owner/repo> [--write] [--json]
310
- buildchain paper migrate [--cwd <dir>] [--write] [--json]
311
- buildchain paper preflight [--cwd <dir>] [--offline] [--json]
312
- buildchain paper bootstrap npm [--cwd <dir>] [--execute]
313
- [--confirm-public-package <name>] [--json]
314
- buildchain paper build [--cwd <dir>] [--execute] [--json]
315
- buildchain paper alpha [--cwd <dir>] [--source-ref <ref>] [--target-ref <ref>]
316
- [--execute] [--json]
317
- buildchain paper status [--cwd <dir>] [--json]
318
- buildchain paper resume [--cwd <dir>] [--buildchain-ref <ref>] [--execute] [--json]
319
- buildchain release-propagation <plan|write-lock> ...
320
- buildchain badges readme [--cwd <dir>] [--readme <path>] [--check] [--write] [--json]
321
- buildchain badges bundle [--cwd <dir>] [--readme <path>] [--claims <csv>] [--check] [--write] [--json]
322
- buildchain homebrew update-formula --package <name> --release-passport <file-or-url> [--write] [--json]
323
- buildchain homebrew check [--cwd <dir>] [--package <name>] [--release-passport <file-or-url>] [--json]
324
- buildchain publish-source <lock|manifest|verify-lock|verify-channel-ref|validate-anchored-release> ...
325
- buildchain build-contract ...
326
-
327
- Examples:
328
- buildchain init --type package --package-manager pnpm
329
- buildchain validate --require-version-state --require-lifecycle-stages build,verify
330
- buildchain lifecycle run build --artifact-path dist --artifact-name "{repo}-{version}-{platform}"
331
- buildchain npm dry-run --json
332
- buildchain release --dry-run --target-ref alpha/v3/v3.0
333
- buildchain release line open --major 3 --minor 1 --source-ref release/v3/v3.0 --json
334
- buildchain span --event native.build -- cmake --build build
335
- buildchain collect github-release --tag v3.0.0 --assets-dir dist --output-dir .buildchain/release-passport
336
- buildchain create publication-admission --input-json admission-input.json --output admission.json
337
- buildchain create runner-provenance --input-json runner-input.json --output runner.json
338
- buildchain verify release-passport .buildchain/release-passport/buildchain.release.json
339
- buildchain verify publication-admission admission.json --registry-json publication-authority-registry.json --runner-json runner.json --control-plane-audit-json control-plane.json --expected-json expected.json --json
340
- buildchain audit publication-control-plane --repository kungfu-systems/buildchain --branch release/v3/v3.0
341
- buildchain verify artifact ./dist/buildchain-x86_64-unknown-linux-gnu.tar.gz --passport .buildchain/release-passport/buildchain.release.json
342
- buildchain verify artifact-envelope .buildchain/kfx/artifact-verification-envelope.json --json
343
- buildchain project kfx-admission .buildchain/kfx/artifact-verification-envelope.json --json
344
- buildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json
345
- buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build
346
- buildchain infra-contract --mode plan --source-sha <sha>
347
- buildchain infra-contract --mode ci --source-sha <sha>
348
- buildchain infra-contract --mode plan --source-sha <sha> --execute-adapter-commands true
349
- buildchain infra-contract --mode apply --plan <plan.json> --source-sha <sha> --approval-id <id>
350
- buildchain infra-contract --mode apply --plan <plan.json> --source-sha <sha> --approval-id <id> --dry-run false --execute-adapter-commands true
351
- buildchain infra-contract --mode propagation-apply --propagation-plan <plan.json> --dry-run true
352
- buildchain infra-contract --mode evidence-bundle --artifact <artifact.json> --propagation-result <result.json>
353
- buildchain publication-artifact manifest --source-sha <sha> --json
354
- buildchain paper preflight --json
355
- buildchain paper status --json
356
- buildchain release-propagation plan --graph graph.json --upstream-release release.json --json
357
- buildchain kfd status --json
358
- buildchain kfd schema list --json
359
- buildchain kfd 1 witness --json
360
- buildchain kfd 2 claims --json
361
- buildchain kfd 2 trust-assessment --json
362
- buildchain kfd upstream collect --json
363
- buildchain kfd aggregate --json
364
- buildchain kfd 3 query buildchain --json
365
- `;
366
- }
367
-
368
114
  function readAttributes(args) {
369
115
  const attributes = {};
370
116
  for (const value of readRepeatedFlag(args, "attribute")) {
@@ -1482,7 +1228,7 @@ async function runProcessTreeSample(sampleArgs = []) {
1482
1228
 
1483
1229
  async function runRegisteredCommand(command, args) {
1484
1230
  if (!command || command === "-h" || command === "--help" || command === "help") {
1485
- process.stdout.write(usage());
1231
+ process.stdout.write(BUILDCHAIN_USAGE);
1486
1232
  return;
1487
1233
  }
1488
1234
 
@@ -4,7 +4,7 @@
4
4
  "product": {
5
5
  "name": "Buildchain",
6
6
  "package": "@kungfu-tech/buildchain",
7
- "version": "3.0.3-alpha.1",
7
+ "version": "3.0.3-alpha.3",
8
8
  "repository": "https://github.com/kungfu-systems/buildchain"
9
9
  },
10
10
  "majorLine": "v3",
@@ -619,7 +619,7 @@
619
619
  "README badge block checks and writes are generated from machine-readable repository facts"
620
620
  ],
621
621
  "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc",
622
- "auditDigest": "sha256:d05fb5cd9c99ee3765b83727b96d9fea15ab166443e91744da88cabd11b214a0"
622
+ "auditDigest": "sha256:0546ff18ae7c6a23122a13e7de3364a48ea3d106539a7f1471363218c5d2a561"
623
623
  },
624
624
  {
625
625
  "contractVersion": 1,
@@ -709,7 +709,7 @@
709
709
  "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
710
710
  ],
711
711
  "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
712
- "auditDigest": "sha256:a1b7fd11b698523b408f4395cd2fc766596cca7ec1723ea48291a509e9352f09"
712
+ "auditDigest": "sha256:d8c63856e51ed61dc7d8ecb055935216dbd9b02adc151fcf3585400b3e9d2988"
713
713
  },
714
714
  {
715
715
  "contractVersion": 1,
@@ -731,7 +731,7 @@
731
731
  "agents can discover supported Node APIs without importing internal file paths"
732
732
  ],
733
733
  "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
734
- "auditDigest": "sha256:74658c9b6795f7ba88421e13e1ddfdd3e25884b35d680a5b8ba1cf699f09c2a4"
734
+ "auditDigest": "sha256:580c8766d5007b1655b341b8e6d0f417cbdd1324f59cac094bead261fa50c961"
735
735
  },
736
736
  {
737
737
  "contractVersion": 1,
@@ -3522,5 +3522,5 @@
3522
3522
  }
3523
3523
  ],
3524
3524
  "compatibilityDigest": "sha256:61af7d0871220bc0909008bdc571905ad500cccf853e7841bc5d462a34b2d436",
3525
- "contractDigest": "sha256:a4093c16e292085ad013b11424a4432c3fa6c22ec0d9cd9fe412ec8a42359a7c"
3525
+ "contractDigest": "sha256:8b03b26e1175e136a3eb6ff6755844fe93cdfd4375f5c0f93221664ca2d7d660"
3526
3526
  }