@kungfu-tech/buildchain 3.0.4-alpha.1 → 3.0.4-alpha.11

package/AGENTS.md

@@ -6,9 +6,14 @@ restating them.
 
 ## Are you using Buildchain, or building it?
 
-- **Using Buildchain** - initialize a repository, call a reusable workflow, run
-  a release dry-run, or inspect the release model: start at the documentation
-  map, [`docs/MAP.md`](docs/MAP.md).
+- **Adopting Buildchain for the first time** - follow the 15-30 minute
+  [`Golden Path`](docs/getting-started.md).
+- **Looking up a CLI command** - use the generated
+  [`CLI Reference`](docs/cli-reference.md).
+- **Writing Node build automation** - use the generated
+  [`Node API Reference`](docs/node-api-reference.md).
+- **Exploring advanced workflows, release governance, or product
+  capabilities** - start at the [`Documentation Map`](docs/MAP.md).
 - **Building or contributing to this repo** - read the rest of this file, then
   [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
@@ -74,8 +79,9 @@ pnpm install --frozen-lockfile
 pnpm run check
 ```
 
-`pnpm run check` validates inventory data, lints root workflows, runs unit tests,
-and rebuilds every action bundle.
+`pnpm run check` validates inventory data, generated public references and site
+bundle drift, lints root workflows, runs unit tests, and rebuilds every action
+bundle.
 
 Before broad maintenance or consolidation work, read the current engineering
 handoff in
@@ -109,6 +115,9 @@ handoff in
 - Do not build or document official release integrations that bypass provider
   protections, hide credential boundaries, or forge release evidence.
 - Keep generated action bundles in sync with source changes.
+- When public documentation, CLI usage authority, or package exports change,
+  follow the [Site Bundle Contract generation steps](docs/site-bundle-contract.md#generation)
+  and commit the updated generated references and `dist/site/` facts.
 - Keep documentation in sync with behavior, especially release governance and
   reusable workflow contracts.
 - [`docs/MAP.md`](docs/MAP.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md) are the

package/README.md

@@ -25,6 +25,20 @@ its existing CI.
 
 The same mechanism releases Buildchain itself.
 
+## Choose Your Path
+
+| You are... | Start here | You will get... |
+| --- | --- | --- |
+| adopting Buildchain for the first time | [Golden Path](docs/getting-started.md) | an exact install, project declaration, validated config, reusable workflow, release dry-run, and Passport inspection |
+| looking up a CLI command | [Generated CLI Reference](docs/cli-reference.md) | governed syntax, options, aliases, and side-effect-free help paths |
+| writing JavaScript automation | [Generated Node API Reference](docs/node-api-reference.md) | every public subpath and symbol with source-derived signatures and behavior boundaries |
+| operating an advanced build or release | [Documentation Map](docs/MAP.md) | capability-, intent-, and maturity-based navigation to normative contracts |
+
+The Golden Path is the beginner lane. Advanced workflow, signing, publishing,
+and governance manuals remain separate so a first-time consumer does not need
+to understand the entire release control plane before reaching a valid local
+configuration.
+
 ## Where Buildchain sits in the Agent Supply Chain
 
 Buildchain binds a product's declarations to the exact source cut, build,
@@ -48,6 +62,10 @@ or protocol evidence through the repository issue tracker.
 
 ## Install and Verify
 
+New repository adopters should follow the [15–30 minute Golden Path](docs/getting-started.md).
+The commands below are the shorter verification-only route for an existing
+consumer.
+
 For v3, use the published npm package and verify the release passport before
 trusting release evidence:
 

package/bin/buildchain.mjs

@@ -14,6 +14,7 @@ import { runPublicationPackageCli } from "../scripts/publication-package.mjs";
 import { runPublicationReproducibilityCli } from "../scripts/publication-reproducibility.mjs";
 import { runPaperCli } from "../scripts/paper.mjs";
 import { BUILDCHAIN_USAGE } from "../scripts/buildchain-cli-help.mjs";
+import { formatCliHelp } from "../scripts/public-reference.mjs";
 import { validateBuildchainConfig } from "../packages/core/buildchain-config.js";
 import { detectPackageManager } from "../packages/core/package-manager.js";
 import {
@@ -102,10 +103,7 @@ import {
   TRUST_RELEASE_COMMANDS,
   dispatchTrustReleaseCommand,
 } from "./internal/trust-release-cli.mjs";
-import {
-  BUILDCHAIN_COMMAND_REGISTRY,
-  dispatchRegisteredCommand,
-} from "./internal/command-registry.mjs";
+import { dispatchRegisteredCommand } from "./internal/command-registry.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const embeddedPackageVersion = process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION || "";
@@ -1226,18 +1224,19 @@ async function runProcessTreeSample(sampleArgs = []) {
   return report;
 }
 
-async function runRegisteredCommand(command, args) {
-  if (!command || command === "-h" || command === "--help" || command === "help") {
-    process.stdout.write(BUILDCHAIN_USAGE);
+async function handleHelpCommand(args) {
+    process.stdout.write(formatCliHelp({ usageText: BUILDCHAIN_USAGE, pathParts: args }));
     return;
-  }
 
-  if (command === "version" || command === "--version" || command === "-v") {
+}
+
+async function handleVersionCommand(args) {
     process.stdout.write(`${packageVersion()}\n`);
     return;
-  }
 
-  if (command === "layout") {
+}
+
+async function handleLayoutCommand(args) {
     const result = createBuildchainLayoutDiscovery({
       cwd: readFlag(args, "cwd", process.cwd()),
       buildchainVersion: packageVersion(),
@@ -1251,9 +1250,10 @@ async function runRegisteredCommand(command, args) {
       process.stdout.write(`- Shifu jurisdiction: ${result.shifu.jurisdiction.field}=${result.shifu.jurisdiction.value}\n`);
     }
     return;
-  }
 
-  if (command === "portable-cache") {
+}
+
+async function handlePortableCacheCommand(args) {
     const [subcommand = "", ...cacheArgs] = args;
     if (subcommand === "plan") {
       const manifestValue = readFlag(cacheArgs, "manifest", "");
@@ -1296,9 +1296,10 @@ async function runRegisteredCommand(command, args) {
       return;
     }
     throw new Error("usage: buildchain portable-cache <plan|receipt> ...");
-  }
 
-  if (command === "candidate") {
+}
+
+async function handleCandidateCommand(args) {
     const [subcommand = "", ...candidateArgs] = args;
     if (subcommand !== "timeline") {
       throw new Error("usage: buildchain candidate timeline --input <file-or-json>");
@@ -1318,9 +1319,10 @@ async function runRegisteredCommand(command, args) {
       process.stdout.write(`wrote: ${output}\n`);
     }
     return;
-  }
 
-  if (command === "init") {
+}
+
+async function handleInitCommand(args) {
     const result = initBuildchainRepo({
       cwd: readFlag(args, "cwd", process.cwd()),
       type: readFlag(args, "type", "package"),
@@ -1331,9 +1333,10 @@ async function runRegisteredCommand(command, args) {
     });
     printJson(result);
     return;
-  }
 
-  if (command === "validate") {
+}
+
+async function handleValidateCommand(args) {
     const lifecycleStages = readFlag(args, "require-lifecycle-stages", "")
       .split(",")
       .map((entry) => entry.trim())
@@ -1343,9 +1346,10 @@ async function runRegisteredCommand(command, args) {
       requireLifecycleStages: lifecycleStages,
     }));
     return;
-  }
 
-  if (command === "doctor") {
+}
+
+async function handleDoctorCommand(args) {
     const result = runDoctor({
       cwd: readFlag(args, "cwd", process.cwd()),
       requirePublishSourceLock: readBooleanFlag(args, "require-publish-source-lock"),
@@ -1359,18 +1363,20 @@ async function runRegisteredCommand(command, args) {
       }
     }
     return;
-  }
 
-  if (command === "dev") {
+}
+
+async function handleDevCommand(args) {
     const [subcommand = "", ...devArgs] = args;
     if (subcommand !== "merge-queue") {
       throw new Error("usage: buildchain dev merge-queue --repository <owner/repo> --branch <dev/vN/vN.M> [--from-config | --workflow <path>...]");
     }
     runScript("dev-merge-queue.mjs", devArgs);
     return;
-  }
 
-  if (command === "log") {
+}
+
+async function handleLogCommand(args) {
     const [levelOrSubcommand = "info", ...logArgs] = args;
     if (levelOrSubcommand === "summary") {
       const logPath = defaultCliLogPath(logArgs);
@@ -1407,9 +1413,10 @@ async function runRegisteredCommand(command, args) {
       printJson(event);
     }
     return;
-  }
 
-  if (command === "diagnostics") {
+}
+
+async function handleDiagnosticsCommand(args) {
     const [subcommand = "", ...diagnosticsArgs] = args;
     if (subcommand !== "summary") {
       throw new Error("usage: buildchain diagnostics summary <diagnostics.json>...");
@@ -1438,28 +1445,32 @@ async function runRegisteredCommand(command, args) {
       }
     }
     return;
-  }
 
-  if (command === "facts") {
+}
+
+async function handleFactsCommand(args) {
     await runBuildFactsCli(args);
     return;
-  }
 
-  if (command === "kfd") {
+}
+
+async function handleKfdCommand(args) {
     await runKfdCli(args);
     return;
-  }
 
-  if (command === "sample") {
+}
+
+async function handleSampleCommand(args) {
     const [subcommand = "", ...sampleArgs] = args;
     if (subcommand !== "process-tree") {
       throw new Error("usage: buildchain sample process-tree -- <command> [args...]");
     }
     await runProcessTreeSample(sampleArgs);
     return;
-  }
 
-  if (command === "mark") {
+}
+
+async function handleMarkCommand(args) {
     const eventName = readFlag(args, "event", "");
     if (!eventName) {
       throw new Error("buildchain mark requires --event <name>");
@@ -1473,9 +1484,10 @@ async function runRegisteredCommand(command, args) {
       printJson(event);
     }
     return;
-  }
 
-  if (command === "span") {
+}
+
+async function handleSpanCommand(args) {
     const separator = args.indexOf("--");
     const spanArgs = separator === -1 ? args : args.slice(0, separator);
     const commandArgs = separator === -1 ? [] : args.slice(separator + 1);
@@ -1517,9 +1529,10 @@ async function runRegisteredCommand(command, args) {
       attributes: readAttributes(spanArgs),
     });
     return;
-  }
 
-  if (command === "lifecycle") {
+}
+
+async function handleLifecycleCommand(args) {
     const [subcommand, stageName = "", ...lifecycleArgs] = args;
     if (subcommand !== "run" || !stageName) {
       throw new Error("usage: buildchain lifecycle run <stage>");
@@ -1540,9 +1553,10 @@ async function runRegisteredCommand(command, args) {
     });
     printJson(manifest);
     return;
-  }
 
-  if (command === "npm") {
+}
+
+async function handleNpmCommand(args) {
     const [subcommand = "", ...npmArgs] = args;
     if (subcommand !== "dry-run") {
       throw new Error("usage: buildchain npm dry-run");
@@ -1561,24 +1575,28 @@ async function runRegisteredCommand(command, args) {
       process.stdout.write(`pack entries: ${result.pack.entryCount}\n`);
     }
     return;
-  }
 
-  if (TRUST_RELEASE_COMMANDS.has(command)) {
+}
+
+async function handleTrustReleaseCommand(args, { command }) {
     await dispatchTrustReleaseCommand({ command, args, runScript, packageVersion });
     return;
-  }
 
-  if (command === "web-surface") {
+}
+
+async function handleWebSurfaceCommand(args) {
     runScript("web-surface.mjs", args);
     return;
-  }
 
-  if (command === "infra-contract") {
+}
+
+async function handleInfraContractCommand(args) {
     runScript("infra-contract.mjs", args);
     return;
-  }
 
-  if (command === "publication-artifact" || command === "publication") {
+}
+
+async function handlePublicationArtifactCommand(args) {
     if (args[0] === "npm-package" || args[0] === "package") {
       runPublicationPackageCli(args.slice(1));
       return;
@@ -1589,9 +1607,10 @@ async function runRegisteredCommand(command, args) {
     }
     runPublicationArtifactCli(args);
     return;
-  }
 
-  if (command === "paper") {
+}
+
+async function handlePaperCommand(args) {
     await runPaperCli(args, {
       buildchainRoot: root,
       buildchainVersion: packageVersion(),
@@ -1600,39 +1619,46 @@ async function runRegisteredCommand(command, args) {
         process.env.BUILDCHAIN_RUNTIME_SHA || embeddedSourceSha || "",
     });
     return;
-  }
 
-  if (command === "release-propagation") {
+}
+
+async function handleReleasePropagationCommand(args) {
     runReleasePropagationCli(args);
     return;
-  }
 
-  if (command === "release-governance") {
+}
+
+async function handleReleaseGovernanceCommand(args) {
     await runReleaseGovernanceCli(args);
     return;
-  }
 
-  if (command === "github-governance") {
+}
+
+async function handleGitHubGovernanceCommand(args) {
     runScript("reconcile-github-governance.mjs", args);
     return;
-  }
 
-  if (command === "badges") {
+}
+
+async function handleBadgesCommand(args) {
     await runReadmeBadgesCli(args);
     return;
-  }
 
-  if (command === "homebrew") {
+}
+
+async function handleHomebrewCommand(args) {
     await runHomebrewCli(args);
     return;
-  }
 
-  if (command === "build-contract") {
+}
+
+async function handleBuildContractCommand(args) {
     runScript("resolve-build-contract.mjs", args);
     return;
-  }
 
-  if (command === "publish-source") {
+}
+
+async function handlePublishSourceCommand(args) {
     const [mode = "lock", ...publishArgs] = args;
     if (mode === "lock" || mode === "manifest") {
       runScript("resolve-publish-source.mjs", ["--mode", mode, ...publishArgs]);
@@ -1665,19 +1691,56 @@ async function runRegisteredCommand(command, args) {
       return;
     }
     throw new Error(`unsupported publish-source command: ${mode}`);
-  }
 
-  throw new Error(`unsupported buildchain command: ${command}`);
 }
 
-const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze(Object.fromEntries(
-  BUILDCHAIN_COMMAND_REGISTRY.map((entry) => [
-    entry.id,
-    (args) => runRegisteredCommand(entry.id, args),
-  ]),
-));
+const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze({
+  "help": handleHelpCommand,
+  "version": handleVersionCommand,
+  "layout": handleLayoutCommand,
+  "portable-cache": handlePortableCacheCommand,
+  "candidate": handleCandidateCommand,
+  "init": handleInitCommand,
+  "validate": handleValidateCommand,
+  "doctor": handleDoctorCommand,
+  "dev": handleDevCommand,
+  "log": handleLogCommand,
+  "diagnostics": handleDiagnosticsCommand,
+  "facts": handleFactsCommand,
+  "kfd": handleKfdCommand,
+  "sample": handleSampleCommand,
+  "mark": handleMarkCommand,
+  "span": handleSpanCommand,
+  "lifecycle": handleLifecycleCommand,
+  "npm": handleNpmCommand,
+  ...Object.fromEntries(
+    [...TRUST_RELEASE_COMMANDS].map((command) => [
+      command,
+      (args) => handleTrustReleaseCommand(args, { command }),
+    ]),
+  ),
+  "web-surface": handleWebSurfaceCommand,
+  "infra-contract": handleInfraContractCommand,
+  "publication-artifact": handlePublicationArtifactCommand,
+  "paper": handlePaperCommand,
+  "release-propagation": handleReleasePropagationCommand,
+  "release-governance": handleReleaseGovernanceCommand,
+  "github-governance": handleGitHubGovernanceCommand,
+  "badges": handleBadgesCommand,
+  "homebrew": handleHomebrewCommand,
+  "build-contract": handleBuildContractCommand,
+  "publish-source": handlePublishSourceCommand,
+});
 
 async function main(argv = process.argv.slice(2)) {
+  const helpIndex = argv.findIndex((entry) => entry === "--help" || entry === "-h");
+  if (helpIndex >= 0) {
+    process.stdout.write(formatCliHelp({
+      usageText: BUILDCHAIN_USAGE,
+      pathParts: argv.slice(0, helpIndex),
+    }));
+    return;
+  }
   const [command = "help", ...args] = argv;
   return dispatchRegisteredCommand({
     command,