@kungfu-tech/buildchain 2.4.3-alpha.0 → 2.4.3

package/docs/publish-transaction.md

@@ -57,7 +57,10 @@ first, restores the local working copies, and only then decides whether to
 publish, repair, or finalize.
 
 Every meaningful state transition is written to the durable ref before public
-release refs move. If the durable write fails, the action fails closed.
+release refs move. Release-state GitHub API reads and writes use retry/backoff
+for transient service failures such as HTTP 5xx responses, connection resets,
+timeouts, and "other side closed" socket failures. If the durable write still
+cannot be persisted after retries, the action fails closed.
 
 Durable release-state refs reserve their exact version even when the public exact
 tag was never created. If a later machine run sees a failed or repair-required
@@ -296,6 +299,9 @@ the transaction `release_sha`. Exact tags are accepted when they already point
 at the transaction release/material SHA or the finalized channel head. Floating
 channel tags and dev/alpha refs are then retried idempotently, and the
 transaction is marked `complete` only after those public refs are consistent.
+Writing `complete` clears any stale `failure` value from earlier attempts, so
+the durable `state.json` represents the successful final state instead of the
+last transient error seen before a rerun.
 An exact tag at an unrelated SHA is still a material conflict and blocks
 recovery.
 

package/docs/toolkit-observability.md

@@ -158,18 +158,24 @@ writeDiagnosticsArtifact(".buildchain/artifacts/diagnostics.json", {
 `collectCacheDiagnostics()` includes package-manager/workspace context, selected
 cache directory stats, and compiler-cache stats from `ccache --show-stats
 --json` plus `sccache --show-stats --stats-format json` when those tools are
-present. Missing cache tools are recorded as unavailable instead of failing the
-diagnostics artifact. Call `collectCompilerCacheDiagnostics()` directly when a
-consumer script only needs compiler cache data.
+present. If a ccache build does not support JSON stats, Buildchain falls back to
+plain `ccache --show-stats` and parses the text counters. Missing cache tools
+are recorded as unavailable instead of failing the diagnostics artifact. Call
+`collectCompilerCacheDiagnostics()` directly when a consumer script only needs
+compiler cache data. Native diagnostics also expose `compilerCaches` and
+`nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate
+summary, so reviewers do not have to dig through nested cache sections first.
 
 Process samples are intentionally summarized before they become long-lived
 artifacts. The summary records requested parallelism, the source of that value
-(`command`, `env:MAKEFLAGS`, `env:CMAKE_BUILD_PARALLEL_LEVEL`, or `explicit`),
-observed active process concurrency, elapsed sample time, total sampled CPU,
-and conservative command categories such as `compiler`, `archive`, `linker`,
-`build-tool`, and `cache`. This lets native projects distinguish "we asked for
+(`command`, `process-tree`, `env:MAKEFLAGS`,
+`env:CMAKE_BUILD_PARALLEL_LEVEL`, or `explicit`), observed active process
+concurrency, elapsed sample time, total sampled CPU, and conservative command
+categories such as `compiler`, `archive`, `linker`, `build-tool`, and `cache`.
+The sampler detects common `make -j N`, `ninja -j N`, CMake/MSBuild/Xcode job
+flags, and MAKEFLAGS. This lets native projects distinguish "we asked for
 `make -j20`" from "the build graph only kept two active compiler or archive
-children busy during the sampled window" without storing full command lines.
+children busy during the sampled window" without storing environment dumps.
 
 Native repositories can opt into a reusable diagnostics profile in
 `buildchain.toml`:
@@ -304,12 +310,15 @@ buildchain sample process-tree \
   make -j20
 ```
 
-The JSONL sample file stores timestamped process-tree snapshots with command
-basenames, CPU percentages, elapsed time, and requested parallelism context. The
-summary file records observed concurrency, total sampled CPU, command
-categories, and top command basenames. This is intended for diagnosing
-low-utilization tails such as archive/link phases without logging full command
-lines or environment dumps.
+The JSONL sample file stores timestamped process-tree snapshots with full
+redacted command lines, command basenames, CPU percentages when available,
+elapsed time, and requested parallelism context. Unix and macOS snapshots read
+the full `ps args` field instead of truncated `comm` names. Windows snapshots
+read `Win32_Process` command lines through PowerShell so the sampler no longer
+returns an empty process set on Windows runners. The summary file records
+observed concurrency, total sampled CPU, command categories, and top command
+basenames. This is intended for diagnosing low-utilization tails such as
+archive/link phases without logging full environment dumps.
 
 The lifecycle observability summary is stage-wide, not just final-step timing:
 when install and build write to the same Buildchain log, the final platform

package/package.json

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

package/packages/core/diagnostics.js

@@ -497,26 +497,70 @@ function parseJsonDiagnostics(value = "") {
   }
 }
 
-function collectCompilerCacheTool({ command, args, cwd, runCommand }) {
-  try {
-    const output = runCommand(command, args, { cwd, timeoutMs: 5000 });
-    const text = String(output || "").trim();
-    const stats = parseJsonDiagnostics(text);
-    return {
-      available: true,
-      command,
-      format: stats ? "json" : "text",
-      stats: stats || {},
-      rawBytes: Buffer.byteLength(text, "utf8"),
-      parseError: stats ? "" : "stats output was not JSON",
-    };
-  } catch (error) {
-    return {
-      available: false,
-      command,
-      error: error?.code || error?.message || "stats command failed",
-    };
+function parseTextStats(value = "") {
+  const stats = {};
+  for (const line of String(value || "").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const match = trimmed.match(/^(.+?)(?:\s{2,}|\t+|:\s+)([-+]?\d+(?:\.\d+)?)(?:\s|$)/);
+    if (!match) {
+      continue;
+    }
+    const key = match[1]
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "_")
+      .replace(/^_+|_+$/g, "");
+    if (!key) {
+      continue;
+    }
+    const number = Number(match[2]);
+    stats[key] = Number.isFinite(number) ? number : match[2];
   }
+  return stats;
+}
+
+function collectCompilerCacheTool({ command, attempts, cwd, runCommand }) {
+  let lastError;
+  for (const attempt of attempts) {
+    const args = attempt.args || [];
+    const expectedFormat = attempt.format || "";
+    try {
+      const output = runCommand(command, args, { cwd, timeoutMs: 5000 });
+      const text = String(output || "").trim();
+      const jsonStats = parseJsonDiagnostics(text);
+      if (jsonStats) {
+        return {
+          available: true,
+          command,
+          args,
+          format: "json",
+          stats: jsonStats,
+          rawBytes: Buffer.byteLength(text, "utf8"),
+          parseError: "",
+        };
+      }
+      const textStats = parseTextStats(text);
+      return {
+        available: true,
+        command,
+        args,
+        format: "text",
+        stats: textStats,
+        rawBytes: Buffer.byteLength(text, "utf8"),
+        parseError: Object.keys(textStats).length ? "" : `${expectedFormat || "stats"} output was not parseable`,
+      };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  return {
+    available: false,
+    command,
+    error: lastError?.code || lastError?.message || "stats command failed",
+  };
 }
 
 export function collectCompilerCacheDiagnostics({
@@ -527,13 +571,18 @@ export function collectCompilerCacheDiagnostics({
   return {
     ccache: collectCompilerCacheTool({
       command: "ccache",
-      args: ["--show-stats", "--json"],
+      attempts: [
+        { args: ["--show-stats", "--json"], format: "json" },
+        { args: ["--show-stats"], format: "text" },
+      ],
       cwd: resolvedCwd,
       runCommand,
     }),
     sccache: collectCompilerCacheTool({
       command: "sccache",
-      args: ["--show-stats", "--stats-format", "json"],
+      attempts: [
+        { args: ["--show-stats", "--stats-format", "json"], format: "json" },
+      ],
       cwd: resolvedCwd,
       runCommand,
     }),
@@ -578,41 +627,21 @@ export function redactDiagnosticsValue(key, value, pattern = DEFAULT_SECRET_KEY_
   return value;
 }
 
-export function collectProcessTreeSnapshot({ rootPid = process.pid, cwd = process.cwd() } = {}) {
-  const pid = String(rootPid || process.pid);
-  if (process.platform === "win32") {
-    return { rootPid: pid, platform: process.platform, processes: [] };
-  }
-  let lines = [];
-  try {
-    lines = execFileSync("ps", ["-axo", "pid=,ppid=,pcpu=,comm=,args="], {
-      cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 5000,
-    }).split(/\r?\n/).filter(Boolean);
-  } catch {
-    return { rootPid: pid, platform: process.platform, processes: [] };
-  }
-  const rows = lines.map((line) => {
-    const match = line.trim().match(/^(\d+)\s+(\d+)\s+([0-9.]+)\s+(\S+)(?:\s+(.*))?$/);
-    const args = match?.[5] || "";
-    return match
-      ? {
-          pid: match[1],
-          ppid: match[2],
-          cpu: Number(match[3]),
-          command: path.basename(match[4]),
-          commandLine: redactCommandLine(args),
-        }
-      : undefined;
-  }).filter(Boolean);
+function processCommandFromLine(commandLine = "", fallback = "") {
+  const firstToken = shellishTokens(commandLine)[0] || fallback;
+  return String(firstToken || "")
+    .replace(/[()]/g, "")
+    .split(/[\\/]/)
+    .pop();
+}
+
+function normalizeProcessRows({ rootPid, platform, rows = [] }) {
   const byParent = new Map();
   for (const row of rows) {
     byParent.set(row.ppid, [...(byParent.get(row.ppid) || []), row]);
   }
   const seen = new Set();
-  const stack = [pid];
+  const stack = [String(rootPid)];
   const processes = [];
   while (stack.length) {
     const current = stack.pop();
@@ -625,11 +654,80 @@ export function collectProcessTreeSnapshot({ rootPid = process.pid, cwd = proces
       stack.push(child.pid);
     }
   }
-  return { rootPid: pid, platform: process.platform, processes };
+  return { rootPid: String(rootPid), platform, processes };
+}
+
+function collectWindowsProcessRows({ cwd, runCommand }) {
+  const script = [
+    "$ErrorActionPreference = 'Stop'",
+    "Get-CimInstance Win32_Process |",
+    "Select-Object ProcessId,ParentProcessId,Name,CommandLine |",
+    "ConvertTo-Json -Compress",
+  ].join("; ");
+  const output = runCommand("powershell", ["-NoProfile", "-Command", script], {
+    cwd,
+    timeoutMs: 5000,
+  });
+  const parsed = JSON.parse(String(output || "[]"));
+  const entries = Array.isArray(parsed) ? parsed : [parsed];
+  return entries.map((entry) => {
+    const commandLine = redactCommandLine(entry.CommandLine || entry.Name || "");
+    return {
+      pid: String(entry.ProcessId || ""),
+      ppid: String(entry.ParentProcessId || ""),
+      cpu: 0,
+      command: processCommandFromLine(commandLine, entry.Name || ""),
+      commandLine,
+    };
+  }).filter((entry) => entry.pid && entry.ppid);
+}
+
+export function collectProcessTreeSnapshot({
+  rootPid = process.pid,
+  cwd = process.cwd(),
+  platform = process.platform,
+  runCommand = defaultDiagnosticCommandRunner,
+} = {}) {
+  const pid = String(rootPid || process.pid);
+  if (platform === "win32") {
+    try {
+      return normalizeProcessRows({
+        rootPid: pid,
+        platform,
+        rows: collectWindowsProcessRows({ cwd, runCommand }),
+      });
+    } catch {
+      return { rootPid: pid, platform, processes: [] };
+    }
+  }
+  let lines = [];
+  try {
+    lines = runCommand("ps", ["-axo", "pid=,ppid=,pcpu=,args="], {
+      cwd,
+      timeoutMs: 5000,
+    }).split(/\r?\n/).filter(Boolean);
+  } catch {
+    return { rootPid: pid, platform, processes: [] };
+  }
+  const rows = lines.map((line) => {
+    const match = line.trim().match(/^(\d+)\s+(\d+)\s+([0-9.]+)\s+(.*)$/);
+    const args = match?.[4] || "";
+    const commandLine = redactCommandLine(args);
+    return match
+      ? {
+          pid: match[1],
+          ppid: match[2],
+          cpu: Number(match[3]),
+          command: processCommandFromLine(commandLine),
+          commandLine,
+        }
+      : undefined;
+  }).filter(Boolean);
+  return normalizeProcessRows({ rootPid: pid, platform, rows });
 }
 
 export function classifyProcessCommand(command = "") {
-  const name = path.basename(String(command || "")).toLowerCase();
+  const name = String(command || "").split(/[\\/]/).pop().toLowerCase();
   if (/^(ccache|sccache)$/.test(name)) {
     return "cache";
   }
@@ -657,7 +755,12 @@ function firstPositiveInteger(value) {
 }
 
 function commandName(value = "") {
-  return path.basename(String(value || "").replace(/[()]/g, "").replace(/\.exe$/i, "")).toLowerCase();
+  return String(value || "")
+    .replace(/[()]/g, "")
+    .replace(/\.exe$/i, "")
+    .split(/[\\/]/)
+    .pop()
+    .toLowerCase();
 }
 
 function detectParallelismFromTokens(tokens = []) {
@@ -945,6 +1048,8 @@ export function createDiagnosticsArtifact({
   const events = logPath ? readBuildchainLogEvents(logPath) : [];
   const loadedConfig = loadBuildchainConfig(resolvedCwd);
   const nativeProfile = getNativeDiagnosticsProfile(loadedConfig);
+  const native = collectNativeDiagnostics({ cwd: resolvedCwd, profile: nativeProfile });
+  const cache = collectCacheDiagnostics({ cwd: resolvedCwd, cacheDirs });
   return {
     schemaVersion: 1,
     contract: BUILDCHAIN_DIAGNOSTICS_CONTRACT,
@@ -953,8 +1058,10 @@ export function createDiagnosticsArtifact({
     buildchain: collectBuildchainDiagnostics({ cwd: resolvedCwd, artifactPaths }),
     runner: collectRunnerDiagnostics(),
     tools: collectToolDiagnostics({ cwd: resolvedCwd }),
-    cache: collectCacheDiagnostics({ cwd: resolvedCwd, cacheDirs }),
-    native: collectNativeDiagnostics({ cwd: resolvedCwd, profile: nativeProfile }),
+    cache,
+    native,
+    compilerCaches: native.compilerCaches || cache.compilerCaches || {},
+    nativeCacheDirs: native.cacheDirs || [],
     git: collectGitDiagnostics({ cwd: resolvedCwd }),
     lifecycleObservability: lifecycleObservability || summarizeLifecycleObservability({ events, logPath }),
     process: processSummary || summarizeProcessSamples({ samples: processSamples, requestedParallelism }),
@@ -1353,6 +1460,12 @@ export function summarizeDiagnosticsArtifacts(inputs = []) {
       runnerDetails: compactRunnerDetails(entry.runner || {}),
       tools: compactToolSummary(entry.tools || {}, entry.native?.tools || {}),
       cache: compactCacheSummary(entry.cache || {}, entry.native || {}),
+      compilerCaches: compactCompilerCacheSummary(entry.compilerCaches || entry.native?.compilerCaches || entry.cache?.compilerCaches || {}),
+      nativeCacheDirs: Array.isArray(entry.nativeCacheDirs)
+        ? entry.nativeCacheDirs
+        : Array.isArray(entry.native?.cacheDirs)
+          ? entry.native.cacheDirs
+          : [],
       process: entry.process || {},
       diagnosticsContract,
       ...(diagnosticsManifest ? { diagnosticsManifest } : {}),

package/packages/core/publish-transaction.js

@@ -164,6 +164,9 @@ export function transitionReleaseTransaction(record, nextState, metadata = {}) {
       throw new Error(`cannot transition release transaction from ${currentState} to ${nextState}`);
     }
   }
+  const nextFailure = nextState === "complete"
+    ? optionalString(metadata.failure ?? "")
+    : optionalString(metadata.failure ?? record.failure);
   return {
     ...record,
     previous_state: currentState === nextState ? record.previous_state || "" : currentState,
@@ -171,7 +174,7 @@ export function transitionReleaseTransaction(record, nextState, metadata = {}) {
     actor: optionalString(metadata.actor ?? record.actor),
     run_id: optionalString(metadata.runId ?? record.run_id),
     superseded_by: optionalString(metadata.supersededBy ?? record.superseded_by),
-    failure: optionalString(metadata.failure ?? record.failure),
+    failure: nextFailure,
     updated_at: nowIso(),
   };
 }