@kungfu-tech/buildchain 2.2.3-alpha.0 → 2.2.3-alpha.1

package/AGENTS.md

@@ -29,7 +29,7 @@ For new repositories, prefer the CLI:
 ```sh
 npx @kungfu-tech/buildchain init --type package
 npx @kungfu-tech/buildchain validate --require-version-state
-npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.0
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.2
 ```
 
 See [`docs/cli.md`](docs/cli.md), [`docs/lifecycle-protocol.md`](docs/lifecycle-protocol.md),

package/README.md

@@ -55,11 +55,31 @@ npx buildchain version
 npx buildchain doctor --json
 ```
 
-The npm package exposes the `buildchain` command and importable toolkit APIs:
+The npm package is also the Buildchain toolkit. Use the command when a workflow
+or shell step needs an executable; use the ESM APIs directly from JavaScript
+build scripts. JavaScript callers should import the package instead of spawning
+the CLI or unpacking the standalone binary:
 
 ```js
-import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
-import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
+import {
+  createBuildchainLogger,
+  verifyBuildchainLogEvents,
+} from "@kungfu-tech/buildchain/logging";
+
+const logger = createBuildchainLogger({
+  path: ".buildchain/logs/native-build.jsonl",
+  source: "user",
+  component: "native-build",
+});
+
+await logger.span("native.compile", { phase: "build" }, async () => {
+  await compileNativeTargets();
+});
+
+const report = verifyBuildchainLogEvents({
+  path: logger.path,
+  requireEvents: ["native.compile.start", "native.compile.end"],
+});
 ```
 
 The package also ships `dist/site/` as the Buildchain-owned fact source for
@@ -130,7 +150,18 @@ should open a new major line.
 
 ## Toolkit Observability
 
-Buildchain includes a logging toolkit for release and build steps:
+Buildchain includes a logging toolkit for release and build steps. Inside
+JavaScript build code, prefer the package API:
+
+```js
+import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+
+const logger = createBuildchainLogger({ source: "user", component: "conan" });
+logger.mark("conan.profile.ready", { phase: "configure" });
+await logger.span("conan.install", { phase: "dependencies" }, runConanInstall);
+```
+
+In workflows or shell scripts, use the equivalent CLI:
 
 ```bash
 buildchain mark --event native.configure --phase configure --component cmake

package/docs/MAP.md

@@ -21,6 +21,7 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |
 | How do I install a standalone binary or npm package? | [`install.md`](install.md) | use | stable |
 | How do I run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |
+| How do I import Buildchain toolkit APIs from JavaScript build code? | [`toolkit-observability.md`](toolkit-observability.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |
 | How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |
 | How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |
@@ -67,7 +68,8 @@ running artifact), *use* (consume / extend) - and a **status**:
   [`release-passport.md`](release-passport.md),
   [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).
 - **Buildchain logging / timestamps / consumer build phase timing** ->
-  [`toolkit-observability.md`](toolkit-observability.md) and [`cli.md`](cli.md).
+  [`toolkit-observability.md`](toolkit-observability.md) for JavaScript API
+  imports, and [`cli.md`](cli.md) for workflow or shell command usage.
 - **buildchain.libkungfu.dev / package-owned site facts** ->
   [`site-bundle-contract.md`](site-bundle-contract.md).
 - **sites / web previews / staging / production gates** ->

package/docs/cli.md

@@ -1,8 +1,8 @@
-# Buildchain CLI and npm Package
+# Buildchain CLI, npm Package, and Toolkit API
 
 Buildchain is published as the public npm package
 `@kungfu-tech/buildchain`. The package contains the `buildchain` command,
-the shared core libraries, and the local scripts needed to initialize and
+the importable ESM toolkit APIs, and the local scripts needed to initialize and
 validate repositories before they use the reusable GitHub workflow surface.
 
 The npm package is not the release authority. Release authority still comes
@@ -27,6 +27,22 @@ pnpm add -D @kungfu-tech/buildchain
 pnpm exec buildchain validate
 ```
 
+Use the package API directly inside JavaScript build scripts:
+
+```js
+import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+
+const logger = createBuildchainLogger({ source: "user", component: "build" });
+await logger.span("build.native", { phase: "build" }, async () => {
+  await buildNativeArtifacts();
+});
+```
+
+The standalone binary and CLI are for workflow steps, shell scripts, and
+non-JavaScript environments. JavaScript code that already depends on
+`@kungfu-tech/buildchain` should import the toolkit API instead of spawning
+`npx buildchain` or a downloaded binary.
+
 ## Commands
 
 `buildchain init` writes a starter `buildchain.toml` and a reusable workflow
@@ -153,9 +169,9 @@ for agents: trust, completeness, impact, recovery route, and next action.
 maintainer opens or merges a channel PR:
 
 ```bash
-buildchain release --dry-run --target-ref alpha/v2/v2.0
-buildchain release --dry-run --target-ref release/v2/v2.0 --sha <verified-sha>
-buildchain release dry-run --target-ref publish-gate/major --source-ref release/v2/v2.0
+buildchain release --dry-run --target-ref alpha/v2/v2.2
+buildchain release --dry-run --target-ref release/v2/v2.2 --sha <verified-sha>
+buildchain release dry-run --target-ref publish-gate/major --source-ref release/v2/v2.2
 buildchain release explain --target-ref alpha/v2/v2.1 --json
 ```
 

package/docs/toolkit-observability.md

@@ -4,6 +4,82 @@ Buildchain ships a small logging toolkit for repository workflows and project
 scripts. The goal is to separate time spent in Buildchain's framework from time
 spent in the consumer's own build, test, packaging, and publish steps.
 
+## Choose API or CLI
+
+`@kungfu-tech/buildchain` is not only a CLI package. It exports ESM toolkit APIs
+that project scripts can import directly:
+
+```js
+import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+```
+
+Use the API inside JavaScript or TypeScript build code. Do not spawn
+`buildchain`, download the standalone binary, or shell out through `npx` from
+code that can import the package. The CLI is for GitHub Actions steps, shell
+scripts, and non-JavaScript tools.
+
+When a script runs inside `buildchain lifecycle run`, the lifecycle runner sets
+`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. Imported loggers pick up those
+environment variables automatically, so events emitted deep inside the build are
+grouped into the same lifecycle summary.
+
+Outside a Buildchain lifecycle or GitHub Actions run, the logger defaults to
+console output unless a path is provided. Pass `path` when local scripts should
+write a reusable JSONL log:
+
+```js
+const logger = createBuildchainLogger({
+  path: ".buildchain/logs/native-build.jsonl",
+  source: "user",
+  component: "native-build",
+});
+```
+
+## Library API
+
+```js
+import {
+  createBuildchainLogger,
+  verifyBuildchainLogEvents,
+} from "@kungfu-tech/buildchain/logging";
+
+const logger = createBuildchainLogger({
+  source: "user",
+  component: "native-build",
+});
+
+logger.mark("configure.ready", {
+  phase: "configure",
+  attributes: { preset: "release" },
+});
+
+await logger.span("native.compile", {
+  phase: "build",
+  attributes: { target: "release" },
+}, async () => {
+  await compile();
+});
+
+const report = verifyBuildchainLogEvents({
+  path: logger.path,
+  minEvents: 3,
+  requirePhases: ["configure", "build"],
+  requireEvents: [
+    "configure.ready",
+    "native.compile.start",
+    "native.compile.end",
+  ],
+});
+
+if (!report.ok) {
+  throw new Error("Buildchain observability verification failed");
+}
+```
+
+Use the API when a build script has internal stages that are invisible to the
+outer workflow. Keep secret values out of attributes; known sensitive keys are
+redacted, but callers should still avoid logging private material.
+
 ## CLI Logging
 
 ```bash
@@ -26,31 +102,6 @@ buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4
 Every event records a timestamp. `span` records duration and preserves the
 wrapped command's exit code.
 
-## Library API
-
-```js
-import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
-
-const logger = createBuildchainLogger({
-  source: "consumer",
-  component: "native-build",
-  phase: "compile",
-});
-
-const span = logger.span("native.compile", { attributes: { target: "release" } });
-try {
-  await compile();
-  span.end();
-} catch (error) {
-  span.error(error);
-  throw error;
-}
-```
-
-Use the API when a build script has internal stages that are invisible to the
-outer workflow. Keep secret values out of attributes; known sensitive keys are
-redacted, but callers should still avoid logging private material.
-
 ## Release Gate
 
 Buildchain's own binary distribution lane verifies required log events before
@@ -67,4 +118,3 @@ buildchain verify observability-log .buildchain/logs/events.jsonl \
 
 This makes missing instrumentation a release failure instead of a dashboard
 afterthought.
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.2.3-alpha.0",
+  "version": "2.2.3-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/README.md

@@ -9,6 +9,24 @@ Current shared surfaces:
 - version-state file discovery and update helpers;
 - lifecycle stage normalization and execution;
 - config validation for release-package and `web-surface` projects.
+- toolkit observability logging through `@kungfu-tech/buildchain/logging`;
+- release passport creation and verification through
+  `@kungfu-tech/buildchain/release-passport`.
+
+## Toolkit Imports
+
+The npm package exports ESM APIs. JavaScript build scripts should import these
+APIs directly instead of spawning the `buildchain` CLI:
+
+```js
+import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+
+const logger = createBuildchainLogger({ source: "user", component: "native" });
+await logger.span("native.package", { phase: "package" }, packageArtifacts);
+```
+
+The CLI remains the right surface for GitHub Actions steps, shell scripts, and
+non-JavaScript build tools.
 
 Web-surface validation stays in core because both local scripts and GitHub
 Actions need the same fail-closed interpretation of project, channel, deploy,