@kungfu-tech/buildchain 2.10.4 → 2.10.5

package/README.md

@@ -171,10 +171,25 @@ npx @kungfu-tech/buildchain validate --require-version-state
 npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.2
 ```
 
-Buildchain supports package and non-package projects through `buildchain.toml`.
+Buildchain supports package and non-package projects through
+`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain
+readable, but new consumers should keep Buildchain-owned files under
+`.buildchain/`:
+
+```text
+.buildchain/buildchain.toml
+.buildchain/contract-lock.json
+.buildchain/kfd/kfd-3-surfaces.json
+.buildchain/release-passport/buildchain.release.json
+```
+
 Lifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom
 scripts, or any other command that can run in the repository checkout.
 
+The KFD entrypoint is `buildchain kfd`. Buildchain currently provides concrete
+KFD-1 contract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface
+workflows; KFD-4 is exposed as schema-only until a verification protocol exists.
+
 Buildchain's active GitHub Action surface is deliberately small:
 
 - `actions/validate-config`

package/bin/buildchain.mjs

@@ -64,6 +64,15 @@ import {
   writeBuildFacts,
   writeKungfuBuildInfoProjection,
 } from "../packages/core/build-facts.js";
+import {
+  collectKfdStatus,
+  kfd1,
+  kfd2,
+  layout as buildchainLayout,
+  listKfdSchemas,
+  normalizeKfdStandardId,
+  readKfdSchema,
+} from "../packages/core/kfd.js";
 import {
   auditKfd3Surfaces,
   createKfd3SurfaceWitness,
@@ -147,15 +156,30 @@ function usage() {
                              [--module-fact <file>]... [--artifact <path>]...
                              [--output <file>] [--json]
   buildchain facts verify [--cwd <dir>] --fact <file> [--json]
-  buildchain kfd-3 detect [--cwd <dir>] [--kind <kind>]... [--artifact <path>] [--json]
-  buildchain kfd-3 register <node-api|python-api|cli|binary|documentation|site-bundle>
+  buildchain kfd ...
+  buildchain kfd status [--cwd <dir>] [--json]
+  buildchain kfd migrate-layout [--cwd <dir>] [--write] [--force] [--json]
+  buildchain kfd schema list [--standard kfd-1|kfd-2|kfd-3|kfd-4] [--json]
+  buildchain kfd schema show <kfd-1|kfd-2|kfd-3|kfd-4> [--schema <name>] [--json]
+  buildchain kfd 1 schema [--schema <name>] [--json]
+  buildchain kfd 1 witness [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--json]
+  buildchain kfd 1 gate --witness-json <file-or-json>... [--cwd <dir>] [--artifact-root <dir>]
+                        [--output <file>] [--json]
+  buildchain kfd 1 verify --gate-json <file-or-json> [--json]
+  buildchain kfd 2 schema [--schema <name>] [--json]
+  buildchain kfd 2 taxonomy --entry-json <file-or-json>... [--kind residualRisk|downgradeReason] [--json]
+  buildchain kfd 2 claims [--cwd <dir>] [--output-dir <dir>] [--json]
+  buildchain kfd 3 ...
+  buildchain kfd 3 detect [--cwd <dir>] [--kind <kind>]... [--artifact <path>] [--json]
+  buildchain kfd 3 register <node-api|python-api|cli|binary|documentation|site-bundle>
                            [--cwd <dir>] [--registry <path>] [--artifact <path>]
                            [--product <name>] [--json]
-  buildchain kfd-3 audit [--cwd <dir>] [--registry <path>] [--artifact <path>] [--json]
-  buildchain kfd-3 witness [--cwd <dir>] [--registry <path>] [--kind prebuild|artifact]
+  buildchain kfd 3 audit [--cwd <dir>] [--registry <path>] [--artifact <path>] [--json]
+  buildchain kfd 3 witness [--cwd <dir>] [--registry <path>] [--kind prebuild|artifact]
                             [--source-sha <sha>] [--artifact <path>] [--output <file>] [--json]
-  buildchain kfd-3 query [<product>] [--cwd <dir>] [--registry <path>]
+  buildchain kfd 3 query [<product>] [--cwd <dir>] [--registry <path>]
                           [--passport <file-or-url>] [--artifact <path>] [--json]
+  buildchain kfd 4 schema [--schema <name>] [--json]
   buildchain sample process-tree [--interval-ms <n>] [--label <name>]
                                  [--output <jsonl>] [--summary-output <json>]
                                  [--requested-parallelism <n>] [--json]
@@ -195,7 +219,11 @@ Examples:
   buildchain infra-contract --mode propagation-apply --propagation-plan <plan.json> --dry-run true
   buildchain infra-contract --mode evidence-bundle --artifact <artifact.json> --propagation-result <result.json>
   buildchain release-propagation plan --graph graph.json --upstream-release release.json --json
-  buildchain kfd-3 query buildchain --json
+  buildchain kfd status --json
+  buildchain kfd schema list --json
+  buildchain kfd 1 witness --json
+  buildchain kfd 2 claims --json
+  buildchain kfd 3 query buildchain --json
 `;
 }
 
@@ -335,6 +363,25 @@ function writeJsonFile(filePath, value) {
   return filePath;
 }
 
+function readJsonInput(value, { cwd = process.cwd(), label = "json" } = {}) {
+  const input = String(value || "").trim();
+  if (!input) {
+    throw new Error(`${label} is required`);
+  }
+  const filePath = path.isAbsolute(input) ? input : path.join(cwd, input);
+  if (fs.existsSync(filePath)) {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  }
+  return JSON.parse(input);
+}
+
+function readRepeatedJsonInputs(args, name, { cwd = process.cwd(), label = name } = {}) {
+  return readRepeatedFlag(args, name).map((value, index) => readJsonInput(value, {
+    cwd,
+    label: `${label}[${index}]`,
+  }));
+}
+
 async function runReadmeBadgesCli(args = []) {
   const [subcommand = "", surface = "", ...badgeArgs] = args;
   if (!["readme", "bundle"].includes(subcommand) || (surface && surface.startsWith("--") === false)) {
@@ -477,11 +524,11 @@ function kfd3Kinds(args = []) {
 async function runKfd3Cli(args = []) {
   const [subcommand = "", maybeKindOrProduct = "", ...rest] = args;
   if (!["detect", "register", "audit", "witness", "query"].includes(subcommand)) {
-    throw new Error("usage: buildchain kfd-3 <detect|register|audit|witness|query> ...");
+    throw new Error("usage: buildchain kfd 3 <detect|register|audit|witness|query> ...");
   }
   const effectiveArgs = maybeKindOrProduct && maybeKindOrProduct.startsWith("--") ? [maybeKindOrProduct, ...rest] : rest;
   const cwd = path.resolve(readFlag(effectiveArgs, "cwd", process.cwd()));
-  const registryPath = readFlag(effectiveArgs, "registry", "buildchain.kfd3.json");
+  const registryPath = readFlag(effectiveArgs, "registry", "");
   const artifactPath = readFlag(effectiveArgs, "artifact", "");
   const json = readBooleanFlag(effectiveArgs, "json");
 
@@ -490,7 +537,7 @@ async function runKfd3Cli(args = []) {
     if (json) {
       printJson(result);
     } else {
-      process.stdout.write(`kfd-3 detect: ${result.summary.surfaceCount} surfaces\n`);
+      process.stdout.write(`kfd 3 detect: ${result.summary.surfaceCount} surfaces\n`);
       for (const entry of result.surfaces) {
         process.stdout.write(`- ${entry.kind}: ${entry.id} (${entry.detectionMethod})\n`);
       }
@@ -501,7 +548,7 @@ async function runKfd3Cli(args = []) {
   if (subcommand === "register") {
     const registerKind = maybeKindOrProduct && !maybeKindOrProduct.startsWith("--") ? maybeKindOrProduct : "";
     if (!registerKind) {
-      throw new Error("usage: buildchain kfd-3 register <node-api|python-api|cli|binary|documentation|site-bundle>");
+      throw new Error("usage: buildchain kfd 3 register <node-api|python-api|cli|binary|documentation|site-bundle>");
     }
     const result = registerKfd3Surfaces({
       cwd,
@@ -515,7 +562,7 @@ async function runKfd3Cli(args = []) {
     if (json) {
       printJson(result);
     } else {
-      process.stdout.write(`kfd-3 register: ${result.registeredCount} ${registerKind} surfaces -> ${registryPath}\n`);
+      process.stdout.write(`kfd 3 register: ${result.registeredCount} ${registerKind} surfaces -> ${registryPath}\n`);
     }
     return;
   }
@@ -525,7 +572,7 @@ async function runKfd3Cli(args = []) {
     if (json) {
       printJson(report);
     } else {
-      process.stdout.write(`kfd-3 audit: ${report.status}\n`);
+      process.stdout.write(`kfd 3 audit: ${report.status}\n`);
       process.stdout.write(`detected=${report.summary.detected} declared=${report.summary.declared} enforced=${report.summary.enforced}\n`);
       for (const issue of report.issues) {
         process.stdout.write(`- ${issue.level}: ${issue.code}: ${issue.surfaceId}\n`);
@@ -552,7 +599,7 @@ async function runKfd3Cli(args = []) {
     if (json || !output) {
       printJson(witness);
     } else {
-      process.stdout.write(`kfd-3 witness: wrote ${output}\n`);
+      process.stdout.write(`kfd 3 witness: wrote ${output}\n`);
     }
     return;
   }
@@ -568,7 +615,7 @@ async function runKfd3Cli(args = []) {
   if (json) {
     printJson(result);
   } else {
-    process.stdout.write(`kfd-3 query: ${result.product} (${result.status || result.kfd?.kfd3 || "unknown"})\n`);
+    process.stdout.write(`kfd 3 query: ${result.product} (${result.status || result.kfd?.kfd3 || "unknown"})\n`);
     process.stdout.write(`capabilities: ${result.capabilities?.length || 0}\n`);
     for (const entry of result.capabilities || []) {
       process.stdout.write(`- ${entry.kind}: ${entry.id} [${entry.state || "declared"}]\n`);
@@ -576,6 +623,242 @@ async function runKfd3Cli(args = []) {
   }
 }
 
+function printKfdSchemaOrJson({ result, json }) {
+  if (json) {
+    printJson(result);
+  } else {
+    process.stdout.write(JSON.stringify(result.schema, null, 2));
+    process.stdout.write("\n");
+  }
+}
+
+function runKfd1Cli(args = []) {
+  const [rawAction = "schema", ...rest] = args;
+  const action = rawAction || "schema";
+  const cwd = path.resolve(readFlag(rest, "cwd", process.cwd()));
+  const json = readBooleanFlag(rest, "json");
+  if (action === "schema") {
+    printKfdSchemaOrJson({
+      result: readKfdSchema({ standard: "kfd-1", schema: readFlag(rest, "schema", "") }),
+      json,
+    });
+    return;
+  }
+  if (action === "witness") {
+    const witness = kfd1.createBuildchainWitness({
+      root: cwd,
+      sourceSha: readFlag(rest, "source-sha", process.env.GITHUB_SHA || ""),
+    });
+    const output = readFlag(rest, "output", "");
+    if (output) {
+      writeJsonFile(path.resolve(cwd, output), witness);
+    }
+    if (json || !output) {
+      printJson(witness);
+    } else {
+      process.stdout.write(`kfd 1 witness: wrote ${output}\n`);
+    }
+    return;
+  }
+  if (action === "gate") {
+    const witnesses = readRepeatedJsonInputs(rest, "witness-json", { cwd, label: "kfd-1 witness" });
+    if (witnesses.length === 0) {
+      throw new Error("buildchain kfd 1 gate requires at least one --witness-json");
+    }
+    const gate = kfd1.createReleaseGateEvidence({
+      cwd,
+      artifactRoot: readFlag(rest, "artifact-root", ""),
+      witnesses,
+    });
+    const output = readFlag(rest, "output", "");
+    if (output) {
+      writeJsonFile(path.resolve(cwd, output), gate);
+    }
+    if (json || !output) {
+      printJson(gate);
+    } else {
+      process.stdout.write(`kfd 1 gate: wrote ${output}\n`);
+    }
+    return;
+  }
+  if (action === "verify") {
+    const gate = readJsonInput(readFlag(rest, "gate-json", ""), { cwd, label: "kfd-1 gate" });
+    const issues = kfd1.validateReleaseGateEvidence(gate);
+    const result = {
+      schemaVersion: 1,
+      contract: "kungfu-buildchain-kfd-1-verify-result",
+      ok: issues.length === 0,
+      issues,
+    };
+    if (json) {
+      printJson(result);
+    } else {
+      process.stdout.write(`kfd 1 verify: ${result.ok ? "ok" : "failed"}\n`);
+      for (const issue of issues) {
+        process.stdout.write(`- ${issue.level || "error"}: ${issue.code || "kfd-1"}: ${issue.message || issue}\n`);
+      }
+    }
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  throw new Error("usage: buildchain kfd 1 <schema|witness|gate|verify> ...");
+}
+
+function runKfd2Cli(args = []) {
+  const [rawAction = "schema", ...rest] = args;
+  const action = rawAction || "schema";
+  const cwd = path.resolve(readFlag(rest, "cwd", process.cwd()));
+  const json = readBooleanFlag(rest, "json");
+  if (action === "schema") {
+    printKfdSchemaOrJson({
+      result: readKfdSchema({ standard: "kfd-2", schema: readFlag(rest, "schema", "") }),
+      json,
+    });
+    return;
+  }
+  if (action === "taxonomy") {
+    const kind = readFlag(rest, "kind", "residualRisk");
+    const entries = readRepeatedJsonInputs(rest, "entry-json", { cwd, label: "kfd-2 taxonomy entry" });
+    const result = {
+      schemaVersion: 1,
+      contract: "kungfu-buildchain-kfd-2-taxonomy-validation",
+      ok: true,
+      kind,
+      entries: kfd2.validateTaxonomyEntries({ entries, kind }),
+    };
+    if (json) {
+      printJson(result);
+    } else {
+      process.stdout.write(`kfd 2 taxonomy: ${result.entries.length} ${kind} entries ok\n`);
+    }
+    return;
+  }
+  if (action === "claims") {
+    const claims = kfd2.createBuildchainClaims({ root: cwd });
+    const outputDir = readFlag(rest, "output-dir", "");
+    if (outputDir) {
+      for (const claim of claims) {
+        const slug = String(claim.id || "claim").replace(/[^a-z0-9._-]+/gi, "-");
+        writeJsonFile(path.resolve(cwd, outputDir, `${slug}.json`), claim);
+      }
+    }
+    const result = {
+      schemaVersion: 1,
+      contract: "kungfu-buildchain-kfd-2-claims",
+      count: claims.length,
+      claims,
+    };
+    if (json || !outputDir) {
+      printJson(result);
+    } else {
+      process.stdout.write(`kfd 2 claims: wrote ${claims.length} claims to ${outputDir}\n`);
+    }
+    return;
+  }
+  throw new Error("usage: buildchain kfd 2 <schema|taxonomy|claims> ...");
+}
+
+async function runKfdCli(args = []) {
+  const [subcommand = "", maybeStandardOrAction = "", ...rest] = args;
+  if (!subcommand) {
+    throw new Error("usage: buildchain kfd <status|migrate-layout|schema|1|2|3|4> ...");
+  }
+
+  if (subcommand === "status") {
+    const effectiveArgs = maybeStandardOrAction && maybeStandardOrAction.startsWith("--") ? [maybeStandardOrAction, ...rest] : rest;
+    const cwd = path.resolve(readFlag(effectiveArgs, "cwd", process.cwd()));
+    const result = collectKfdStatus({ cwd });
+    if (readBooleanFlag(effectiveArgs, "json")) {
+      printJson(result);
+    } else {
+      process.stdout.write(`kfd status: layout=${result.layout.status}\n`);
+      for (const [standard, capabilities] of Object.entries(result.support)) {
+        process.stdout.write(`- ${standard}: ${capabilities.join(", ")}\n`);
+      }
+    }
+    return;
+  }
+
+  if (subcommand === "migrate-layout") {
+    const effectiveArgs = maybeStandardOrAction && maybeStandardOrAction.startsWith("--") ? [maybeStandardOrAction, ...rest] : rest;
+    const cwd = path.resolve(readFlag(effectiveArgs, "cwd", process.cwd()));
+    const result = buildchainLayout.migrate({
+      cwd,
+      write: readBooleanFlag(effectiveArgs, "write"),
+      force: readBooleanFlag(effectiveArgs, "force"),
+    });
+    if (readBooleanFlag(effectiveArgs, "json")) {
+      printJson(result);
+    } else {
+      process.stdout.write(`kfd migrate-layout: ${result.status}${result.write ? " (write)" : " (dry-run)"}\n`);
+      for (const move of result.moves) {
+        process.stdout.write(`- ${move.from} -> ${move.to}\n`);
+      }
+    }
+    return;
+  }
+
+  if (subcommand === "schema") {
+    const [schemaCommand = "", maybeStandard = "", ...schemaRest] = [maybeStandardOrAction, ...rest];
+    const effectiveArgs = maybeStandard && maybeStandard.startsWith("--") ? [maybeStandard, ...schemaRest] : schemaRest;
+    const json = readBooleanFlag(effectiveArgs, "json");
+    if (schemaCommand === "list") {
+      const result = listKfdSchemas({ standard: readFlag(effectiveArgs, "standard", "") });
+      if (json) {
+        printJson(result);
+      } else {
+        process.stdout.write(`kfd schema list: ${result.schemas.length} schemas\n`);
+        for (const entry of result.schemas) {
+          process.stdout.write(`- ${entry.standard}:${entry.name} ${entry.schemaId || entry.schemaPath}\n`);
+        }
+      }
+      return;
+    }
+    if (schemaCommand === "show") {
+      const standard = maybeStandard && !maybeStandard.startsWith("--") ? maybeStandard : readFlag(effectiveArgs, "standard", "");
+      if (!standard) {
+        throw new Error("usage: buildchain kfd schema show <kfd-1|kfd-2|kfd-3|kfd-4> [--schema <name>]");
+      }
+      const result = readKfdSchema({ standard, schema: readFlag(effectiveArgs, "schema", "") });
+      if (json) {
+        printJson(result);
+      } else {
+        process.stdout.write(JSON.stringify(result.schema, null, 2));
+        process.stdout.write("\n");
+      }
+      return;
+    }
+    throw new Error("usage: buildchain kfd schema <list|show> ...");
+  }
+
+  const standard = normalizeKfdStandardId(subcommand);
+  if (standard === "kfd-1") {
+    runKfd1Cli([maybeStandardOrAction, ...rest]);
+    return;
+  }
+  if (standard === "kfd-2") {
+    runKfd2Cli([maybeStandardOrAction, ...rest]);
+    return;
+  }
+  if (standard === "kfd-3") {
+    await runKfd3Cli([maybeStandardOrAction, ...rest]);
+    return;
+  }
+  if (standard === "kfd-4") {
+    const action = maybeStandardOrAction || "schema";
+    if (action === "schema") {
+      const schemaArgs = rest;
+      const json = readBooleanFlag(schemaArgs, "json");
+      printKfdSchemaOrJson({ result: readKfdSchema({ standard, schema: readFlag(schemaArgs, "schema", "") }), json });
+      return;
+    }
+    throw new Error("KFD-4 is currently schema-only in Buildchain; use: buildchain kfd 4 schema");
+  }
+  throw new Error("usage: buildchain kfd <status|migrate-layout|schema|1|2|3|4> ...");
+}
+
 async function runBuildFactsCli(args = []) {
   const [subcommand = "", ...factArgs] = args;
   const cwd = path.resolve(readFlag(factArgs, "cwd", process.cwd()));
@@ -940,8 +1223,8 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
-  if (command === "kfd-3") {
-    await runKfd3Cli(args);
+  if (command === "kfd") {
+    await runKfdCli(args);
     return;
   }
 

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.10.4",
+    "version": "2.10.5",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -92,7 +92,7 @@
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes"
       ],
       "breakingDigest": "sha256:403d2fcdb0c5eabe749e89102defad69745f70a1556707bec7831fcc2e9fa8f8",
-      "auditDigest": "sha256:377c48c5991c0bc8c0d7874596c2ecb83f8fd61837c8cbc37439058d1f97e71f"
+      "auditDigest": "sha256:b3e96fe1d01793481dcf507373b7856a9b29451d168b18cd0f149517cb61ffde"
     },
     {
       "contractVersion": 1,
@@ -134,7 +134,7 @@
         "breaking contract drift fails closed before rendering, deployment, or release publication"
       ],
       "breakingDigest": "sha256:82ee63cb336e40d832dfff4a1c5e6cbfa221a4fc8b2359990033bc931bffc43a",
-      "auditDigest": "sha256:c7ccd61dcad7420276d5c13549ccbbd7f9afee30eab28ff09fe3d59b2a3f638f"
+      "auditDigest": "sha256:ae85fb8353b26d804f9856b971c9c77bd19bbbf6286f35e015284ebce31c818a"
     },
     {
       "contractVersion": 1,
@@ -344,7 +344,7 @@
         "README badge block checks and writes are generated from machine-readable repository facts"
       ],
       "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc",
-      "auditDigest": "sha256:1bdab893fbb6af1d1d0b840e3583fafb874522c2dde1ae39f393f3fa97b1ef72"
+      "auditDigest": "sha256:e7d8cea1254cd2a5acb2c217ae986cc349fd7117147a819fbc17d8dac7ed0755"
     },
     {
       "contractVersion": 1,
@@ -434,7 +434,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:e48299d248fbea70481f03d7d3ce200e59ac0d8667cfb78b34307821cfe220d2"
+      "auditDigest": "sha256:e6e30455ad08e8e979bea81065523e3082ca837470a979adc874bfa623740ef1"
     },
     {
       "contractVersion": 1,
@@ -456,9 +456,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:2f9d529de163b590729dd01cda95eff0ebaed8152fab6502a26bfa32984b7d8a"
+      "auditDigest": "sha256:1d012a0a8f04a4c91abb0a6546103031584247fff028c4066e491ace8afab49d"
     }
   ],
   "compatibilityDigest": "sha256:967df7e854fdf582294ddfb6403eff25c00db9518a24051e7d47cbd75527c785",
-  "contractDigest": "sha256:657034ebc39315b3450cd4c4356af2529b6a2ad03d0df680ec6010f3396df52d"
+  "contractDigest": "sha256:515f9d76f67aa18c607f96ecdd608cda561929ea3ae3c887609fe28d0f05c25f"
 }