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

package/scripts/generate-site-bundle.mjs

@@ -35,6 +35,12 @@ import {
 import { createSurfaceTimestampPolicy } from "../packages/core/surface-manifest.js";
 import { cliCommandMeta, nodeApiMeta } from "./site-capability-metadata.mjs";
 import { projectHomepageIntro } from "./site-bundle-homepage.mjs";
+import { BUILDCHAIN_USAGE } from "./buildchain-cli-help.mjs";
+import {
+  cliReferenceById,
+  createCliReference,
+} from "./public-reference.mjs";
+import { createSiteNodeApiRegistry } from "./site-reference-registry.mjs";
 import {
   BUILDCHAIN_COMMAND_REGISTRY,
   resolveBuildchainCommand,
@@ -341,9 +347,12 @@ function publicSurfaceLifecycle({ owner, maturity, nonDuplicationRationale }) {
 
 const manualMetaById = new Map(Object.entries({
   map: { capabilityGroup: "getting-started", audience: ["agent", "consumer"], maturity: "stable", order: 10 },
+  "getting-started": { capabilityGroup: "getting-started", audience: ["consumer", "agent"], maturity: "stable", order: 15 },
   install: { capabilityGroup: "getting-started", audience: ["consumer"], maturity: "stable", order: 20 },
   "product-mechanism": { capabilityGroup: "getting-started", audience: ["agent", "maintainer"], maturity: "stable", order: 30 },
   cli: { capabilityGroup: "api-cli-reference", audience: ["agent", "developer"], maturity: "stable", order: 40 },
+  "cli-reference": { capabilityGroup: "api-cli-reference", audience: ["agent", "developer", "operator"], maturity: "stable", order: 42 },
+  "node-api-reference": { capabilityGroup: "api-cli-reference", audience: ["agent", "developer"], maturity: "stable", order: 44 },
   "release-passport": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 100 },
   "github-artifact-attestation": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 108 },
   "publication-authority": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 105 },
@@ -409,6 +418,8 @@ function pageCapabilityMeta(relPath, category) {
 
 function createCliRegistry(packageJson) {
   const commands = enumerateCliCommandsFromBin({ root });
+  const reference = createCliReference(BUILDCHAIN_USAGE);
+  const referenceById = cliReferenceById(reference);
   const documentedTopLevelCommands = new Set();
   for (const entry of commands) {
     const command = entry.usage.split(/\s+/)[1] || "";
@@ -433,6 +444,13 @@ function createCliRegistry(packageJson) {
       const meta = cliCommandMeta(entry.id);
       return {
         ...entry,
+        ...(referenceById.get(entry.id) || {
+          paths: [],
+          syntaxes: [],
+          options: [],
+          aliases: [],
+          helpCommands: [],
+        }),
         purpose: meta.purpose,
         capabilityGroup: meta.capabilityGroup,
         audience: meta.audience,
@@ -621,6 +639,21 @@ function createPublicationReleaseRegistry({ packageJson, timestampPolicy }) {
   };
 }
 
+const RELEASE_PROPAGATION_MODEL = {
+  graphContract: "kungfu-buildchain-release-propagation-graph",
+  planContract: "kungfu-buildchain-release-propagation-plan",
+  lockContract: "kungfu-buildchain-release-propagation-lock",
+  workContract: "kungfu-buildchain-release-propagation-work",
+  stageReceiptContract: "kungfu-buildchain-release-propagation-stage-receipt",
+  workControlBindings: [
+    "kungfu.assignment-graph.work-ref/v1",
+    "kungfu.work-control.initiative-family-state/v2",
+  ],
+  completionBoundary: "production-online-readback-plus-accepted-work-control-decision",
+  defaultChannelPolicy: "preserve",
+  defaultChannelMap: { alpha: "alpha", release: "release" },
+};
+
 function buildSiteBundle() {
   const packageJson = readJson("package.json");
   const inventory = readJson("tests/buildchain-inventory.json");
@@ -723,40 +756,7 @@ function buildSiteBundle() {
     pages,
   };
 
-  const nodeApiRegistry = {
-    schemaVersion: 1,
-    contract: "kungfu-buildchain-node-api-registry",
-    package: packageJson.name,
-    moduleSystem: packageJson.type || "module",
-    exports: Object.entries(packageJson.exports || {})
-      .filter(([specifier]) => !specifier.startsWith("./site/") && specifier !== "./package.json")
-      .map(([specifier, target]) => {
-        const meta = nodeApiMeta(specifier);
-        return {
-          specifier: specifier === "." ? packageJson.name : `${packageJson.name}/${specifier.replace(/^\.\//, "")}`,
-          export: specifier,
-          target,
-          digest: typeof target === "string" ? sha256File(target.replace(/^\.\//, "")) : "",
-          summary: meta.summary,
-          capabilityGroup: meta.capabilityGroup,
-          audience: meta.audience,
-          ...publicSurfaceLifecycle({
-            owner: "buildchain-core",
-            maturity: meta.maturity,
-            nonDuplicationRationale: "Existing package subpath retained as the canonical API boundary for this capability.",
-          }),
-        };
-      }),
-    docs: [
-      { id: "cli-and-node-package", path: "docs/cli.md", digest: sha256File("docs/cli.md") },
-      { id: "build-facts", path: "docs/build-facts.md", digest: sha256File("docs/build-facts.md") },
-      { id: "kfd-support", path: "docs/kfd-support.md", digest: sha256File("docs/kfd-support.md") },
-      { id: "readme-badges", path: "docs/readme-badges.md", digest: sha256File("docs/readme-badges.md") },
-      { id: "homebrew", path: "docs/homebrew.md", digest: sha256File("docs/homebrew.md") },
-      { id: "site-bundle-contract", path: "docs/site-bundle-contract.md", digest: sha256File("docs/site-bundle-contract.md") },
-    ],
-    guidance: "These are the public Node import surfaces shipped by the npm package. Agents should prefer these exports over internal file paths.",
-  };
+  const nodeApiRegistry = createSiteNodeApiRegistry({ root, packageJson, nodeApiMeta, sha256File, publicSurfaceLifecycle });
 
   const workflowRegistry = {
     schemaVersion: 1,
@@ -857,13 +857,7 @@ function buildSiteBundle() {
       schema: "schemas/release-passport-v1.schema.json",
       checkManifest: "release-passport-check-manifest.json",
     },
-    releasePropagation: {
-      graphContract: "kungfu-buildchain-release-propagation-graph",
-      planContract: "kungfu-buildchain-release-propagation-plan",
-      lockContract: "kungfu-buildchain-release-propagation-lock",
-      defaultChannelPolicy: "preserve",
-      defaultChannelMap: { alpha: "alpha", release: "release" },
-    },
+    releasePropagation: RELEASE_PROPAGATION_MODEL,
     npm: {
       package: packageJson.name,
       command: packageJson.bin?.buildchain || "",

package/scripts/maintainability-metrics.mjs

@@ -174,10 +174,12 @@ function architectureSummary(root, revision = "") {
   const implementationPaths = new Set(
     index.capabilities.flatMap((entry) => entry.implementation || []),
   );
-  const graph = new Map(
-    [...implementationPaths].map((file) => [file, new Set()]),
+  const repositorySources = trackedFiles(root, revision).filter(
+    isHandMaintainedSource,
   );
-  for (const file of implementationPaths) {
+  const repositorySourceSet = new Set(repositorySources);
+  const graph = new Map(repositorySources.map((file) => [file, new Set()]));
+  for (const file of repositorySources) {
     if (!JS_EXTENSIONS.has(path.extname(file))) continue;
     for (const specifier of relativeImports(
       readTrackedFile(root, file, revision),
@@ -192,10 +194,20 @@ function architectureSummary(root, revision = "") {
         `${base}.cjs`,
         `${base}/index.js`,
         `${base}/index.mjs`,
-      ].find((candidate) => implementationPaths.has(candidate));
+      ].find((candidate) => repositorySourceSet.has(candidate));
       if (target) graph.get(file).add(target);
     }
   }
+  const exclusions = new Set(
+    (index.ownershipExclusions || []).map((entry) => entry.path),
+  );
+  const ownedSources = repositorySources.filter((file) =>
+    index.ownershipRules?.some((rule) =>
+      (rule.paths || []).some(
+        (prefix) => file === prefix || file.startsWith(`${prefix}/`),
+      ),
+    ),
+  ).length;
   return {
     capabilities: index.capabilities.length,
     implementationMappings: index.capabilities.reduce(
@@ -207,6 +219,14 @@ function architectureSummary(root, revision = "") {
       0,
     ),
     dependencyRules: index.dependencyRules.length,
+    repositorySources: repositorySources.length,
+    ownedSources,
+    excludedSources: repositorySources.filter((file) => exclusions.has(file))
+      .length,
+    dependencyEdges: [...graph.values()].reduce(
+      (total, targets) => total + targets.size,
+      0,
+    ),
     dependencyCycles: dependencyCycles(graph).length,
   };
 }

package/scripts/paper-work-fleet-cli.mjs

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import {
   PAPER_FLEET_AUDIT_CONTRACT,
@@ -17,6 +18,7 @@ import {
   planPaperMigration,
   planPaperScaffold,
   planPaperFleetUpdate,
+  paperFleetTransitionWorkspace,
   writePaperFleetUpdate,
   writePaperMigration,
   writePaperScaffold,
@@ -467,9 +469,26 @@ function runFleetAudit(options) {
 function refreshFleetLocks(result) {
   for (const entry of result.results || []) {
     if (!entry.ok) continue;
-    const lock = commandResult("pnpm", ["install", "--lockfile-only"], {
-      cwd: entry.cwd,
-    });
+    const workspacePath = path.resolve(entry.cwd, "pnpm-workspace.yaml");
+    const lockPath = path.resolve(entry.cwd, "pnpm-lock.yaml");
+    const finalWorkspace = fs.readFileSync(workspacePath, "utf8");
+    const transitionWorkspace = paperFleetTransitionWorkspace(
+      finalWorkspace,
+      fs.existsSync(lockPath) ? fs.readFileSync(lockPath, "utf8") : "",
+    );
+    let lock;
+    try {
+      if (transitionWorkspace !== finalWorkspace) {
+        fs.writeFileSync(workspacePath, transitionWorkspace);
+      }
+      lock = commandResult("pnpm", ["install", "--lockfile-only"], {
+        cwd: entry.cwd,
+      });
+    } finally {
+      if (fs.readFileSync(workspacePath, "utf8") !== finalWorkspace) {
+        fs.writeFileSync(workspacePath, finalWorkspace);
+      }
+    }
     if (lock.ok) continue;
     return {
       ...result,