@kungfu-tech/buildchain 2.14.0 → 2.14.1-alpha.1

package/bin/buildchain.mjs

@@ -96,6 +96,7 @@ import {
   registerKfd3Surfaces,
 } from "../packages/core/kfd3-surface-register.js";
 import { createBuildchainLayoutDiscovery } from "../packages/core/buildchain-layout.js";
+import { createPortableDevCachePlan, createPortableDevCacheReceipt } from "../packages/core/portable-dev-cache.js";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const embeddedPackageVersion = process.env.BUILDCHAIN_EMBEDDED_PACKAGE_VERSION || "";
@@ -105,6 +106,14 @@ function usage() {
   buildchain --help
   buildchain version
   buildchain layout [--cwd <dir>] [--json]
+  buildchain portable-cache plan --manifest <file-or-json> [--output <file>]
+                                 [--github-output <file>] [--json]
+  buildchain portable-cache receipt --plan <file-or-json> [--matched-key <key>]
+                                    [--cache-hit true|false]
+                                    [--validation-status pass|fail]
+                                    [--validation-reason <text>]
+                                    [--cold-fallback-status not-run|passed|failed]
+                                    [--output <file>] [--json]
   buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force]
                   [--package-manager pnpm|npm|yarn] [--runner-preset <preset>]
                   [--artifact-name <template>]
@@ -1348,6 +1357,51 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "portable-cache") {
+    const [subcommand = "", ...cacheArgs] = args;
+    if (subcommand === "plan") {
+      const manifestValue = readFlag(cacheArgs, "manifest", "");
+      if (!manifestValue) throw new Error("usage: buildchain portable-cache plan --manifest <file-or-json>");
+      const value = createPortableDevCachePlan(readJsonInput(manifestValue, { label: "portable cache manifest" }));
+      const output = readFlag(cacheArgs, "output", "");
+      if (output) writeJsonFile(path.resolve(output), value);
+      const githubOutput = readFlag(cacheArgs, "github-output", "");
+      if (githubOutput) {
+        const delimiter = `BUILDCHAIN_PORTABLE_CACHE_${crypto.randomBytes(8).toString("hex")}`;
+        const fields = {
+          "cache-key": value.key,
+          "restore-keys": value.restoreKeys.join("\n"),
+          "cache-paths": value.paths.join("\n"),
+          "plan-digest": value.planDigest,
+          "plan-json": JSON.stringify(value),
+        };
+        const lines = Object.entries(fields).flatMap(([name, field]) => [`${name}<<${delimiter}`, field, delimiter]);
+        fs.appendFileSync(path.resolve(githubOutput), `${lines.join("\n")}\n`);
+      }
+      if (!output || readBooleanFlag(cacheArgs, "json")) printJson(value);
+      else process.stdout.write(`portable cache plan: ${output}\n`);
+      return;
+    }
+    if (subcommand === "receipt") {
+      const planValue = readFlag(cacheArgs, "plan", "");
+      if (!planValue) throw new Error("usage: buildchain portable-cache receipt --plan <file-or-json>");
+      const value = createPortableDevCacheReceipt({
+        plan: readJsonInput(planValue, { label: "portable cache plan" }),
+        matchedKey: readFlag(cacheArgs, "matched-key", ""),
+        cacheHit: readFlag(cacheArgs, "cache-hit", ""),
+        validationStatus: readFlag(cacheArgs, "validation-status", "pass"),
+        validationReason: readFlag(cacheArgs, "validation-reason", ""),
+        coldFallbackStatus: readFlag(cacheArgs, "cold-fallback-status", "not-run"),
+      });
+      const output = readFlag(cacheArgs, "output", "");
+      if (output) writeJsonFile(path.resolve(output), value);
+      if (!output || readBooleanFlag(cacheArgs, "json")) printJson(value);
+      else process.stdout.write(`portable cache receipt: ${output}\n`);
+      return;
+    }
+    throw new Error("usage: buildchain portable-cache <plan|receipt> ...");
+  }
+
   if (command === "init") {
     const result = initBuildchainRepo({
       cwd: readFlag(args, "cwd", process.cwd()),

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.14.0",
+    "version": "2.14.1-alpha.1",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -437,7 +437,7 @@
         "README badge block checks and writes are generated from machine-readable repository facts"
       ],
       "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc",
-      "auditDigest": "sha256:da02a9a5dd23c28317010ac52ad75e1d99262e09beedc58993fb46568ea90f46"
+      "auditDigest": "sha256:3f232f89616d18e9b6fdd9470a33961cd25e3401d204905707cbe18fdecf5d2c"
     },
     {
       "contractVersion": 1,
@@ -527,7 +527,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:32e2353d96a70c0334f6b56508b8689de0e5c5a89eb5789aebcc456e1613ed1e"
+      "auditDigest": "sha256:42bcce2ffadc96b22976ffbcd0d7e71dcdc7aae0706013deac9fe9f663423e62"
     },
     {
       "contractVersion": 1,
@@ -549,7 +549,7 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:749a7207d0b71b3d9f5f4a2d4b23c3f92c9ebdb2c3ce41b38869327f9b43fd5b"
+      "auditDigest": "sha256:9f0cf71c3fd2cdafee57c242afc3b02f3146f61d0d4c4e6db402a0fdbe02f5cd"
     },
     {
       "contractVersion": 1,
@@ -2709,5 +2709,5 @@
     }
   ],
   "compatibilityDigest": "sha256:af162b86ab4506e9b5f1d3c59b41f3fd57fbad79ff4d749a7f12ff16460517f8",
-  "contractDigest": "sha256:c793cb37b1b203bb9381404020a08adc1dcf12c6bf94e7aa52a59b19bebbea73"
+  "contractDigest": "sha256:d27a2b7cfccc916749f1565958fd4124a014ddeb35b5c954bf367802665a9dc7"
 }