@cdxgen/cdxgen 13.0.0 → 13.0.1

package/README.md

@@ -214,7 +214,7 @@ Common asset names:
 #### Linux
 
 ```bash
-VERSION="v13.0.0"
+VERSION="v13.0.1"
 ASSET="cdx-audit-linux-amd64"
 BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
 
@@ -228,7 +228,7 @@ chmod +x "${ASSET}"
 #### macOS
 
 ```bash
-VERSION="v13.0.0"
+VERSION="v13.0.1"
 ASSET="cdx-audit-darwin-arm64"
 BASE_URL="https://github.com/cdxgen/cdxgen/releases/download/${VERSION}"
 
@@ -242,7 +242,7 @@ chmod +x "${ASSET}"
 #### Windows (PowerShell)
 
 ```powershell
-$Version = "v13.0.0"
+$Version = "v13.0.1"
 $Asset = "cdx-audit-windows-amd64.exe"
 $BaseUrl = "https://github.com/cdxgen/cdxgen/releases/download/$Version"
 
@@ -267,7 +267,7 @@ steps:
     env:
       GH_TOKEN: ${{ github.token }}
     run: |
-      gh release download v13.0.0 \
+      gh release download v13.0.1 \
         --repo cdxgen/cdxgen \
         --pattern 'cdx-audit-linux-amd64' \
         --pattern 'cdx-audit-linux-amd64.sha256'

package/bin/cdxgen.js

@@ -887,15 +887,26 @@ if (args.bomAuditIncludeTrusted && args.bomAuditOnlyTrusted) {
 
 if (args.tui && !readEnvironmentVariable("CI")) {
   const cdxuiPath = resolvePluginBinary("cdxui");
-  if (cdxuiPath) {
-    const cdxgenArgs = process.argv.slice(2).filter((a) => a !== "--tui");
+  if (!cdxuiPath) {
+    console.error(
+      "The terminal user interface requires the cdxui plugin binary, which is not installed for this platform.\nInstall @cdxgen/cdxgen-plugins-bin, or set CDXUI_CMD to a cdxui binary, then retry. Continuing without the interface.",
+    );
+  } else {
+    const cdxgenArgs = process.argv
+      .slice(2)
+      .filter((a) => a !== "--tui" && !a.startsWith("--tui="));
+    // Arguments cross the process boundary separated by the unit separator
+    // rather than by spaces: a scan path may legitimately contain a space, and
+    // re-splitting on whitespace would silently turn it into two paths.
     const cdxuiResult = safeSpawnSync(cdxuiPath, ["--generate"], {
       stdio: "inherit",
       env: {
         ...process.env,
         CDXGEN_CMD:
-          readEnvironmentVariable("CDXGEN_CMD") || process.argv[1] || "cdxgen",
-        CDXGEN_ARGS: cdxgenArgs.join(" "),
+          readEnvironmentVariable("CDXGEN_CMD") ||
+          [process.argv[0], process.argv[1]].filter(Boolean).join("\x1f") ||
+          "cdxgen",
+        CDXGEN_ARGS: cdxgenArgs.join("\x1f"),
       },
     });
     process.exit(cdxuiResult.status || 0);

package/bin/convert.js

@@ -7,6 +7,7 @@ import process from "node:process";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
+import { installConsoleShim, restoreConsole } from "../lib/core/ui.js";
 import {
   retrieveCdxgenVersion,
   safeExistsSync,
@@ -74,6 +75,12 @@ const args = _yargs
   .help()
   .wrap(Math.min(120, yargs().terminalWidth())).argv;
 
+// stdout carries the payload and nothing else; every diagnostic goes to the
+// live region's stream. Without the shim a `--print`/`--json` document shares
+// stdout with progress messages and cannot be piped into a parser.
+installConsoleShim();
+process.once("exit", restoreConsole);
+
 const loadCycloneDxBom = async (inputPath) => {
   if (!safeExistsSync(inputPath)) {
     console.error(`Input file '${inputPath}' not found.`);

package/bin/hbom.js

@@ -8,6 +8,7 @@ import { hideBin } from "yargs/helpers";
 
 import { createHBom } from "../lib/cli/index.js";
 import { thoughtLog } from "../lib/core/logger.js";
+import { installConsoleShim, restoreConsole } from "../lib/core/ui.js";
 import {
   DEBUG_MODE,
   isDryRun,
@@ -192,6 +193,12 @@ const args = _yargs
   })
   .wrap(Math.min(120, yargs().terminalWidth())).argv;
 
+// stdout carries the payload and nothing else; every diagnostic goes to the
+// live region's stream. Without the shim a `--print`/`--json` document shares
+// stdout with progress messages and cannot be piped into a parser.
+installConsoleShim();
+process.once("exit", restoreConsole);
+
 if (args.help) {
   console.log(`${retrieveCdxgenVersion()}\n`);
   _yargs.showHelp();
@@ -334,8 +341,9 @@ async function loadBomFromInputFile(inputFile) {
 function printHbomDiagnosticsReport(bomJson) {
   const hbomSummary = getHbomSummary(bomJson);
   if (options.json) {
-    console.log(
-      JSON.stringify(
+    // A machine-readable report is a payload too, not a diagnostic.
+    process.stdout.write(
+      `${JSON.stringify(
         {
           actionableDiagnosticCount: hbomSummary.actionableDiagnosticCount,
           architecture: hbomSummary.architecture,
@@ -359,7 +367,7 @@ function printHbomDiagnosticsReport(bomJson) {
         },
         null,
         2,
-      ),
+      )}\n`,
     );
     return;
   }
@@ -459,7 +467,8 @@ async function runDiagnosticsCommand() {
   }
   const output = JSON.stringify(bomJson, null, options.pretty ? 2 : null);
   if (options.print) {
-    console.log(output);
+    // The document is the payload, so it bypasses the console shim.
+    process.stdout.write(`${output}\n`);
   } else {
     const outputDirectory = getOutputDirectory(options.output);
     if (outputDirectory && !safeExistsSync(outputDirectory)) {

package/bin/tracebom.js

@@ -7,6 +7,7 @@ import { hideBin } from "yargs/helpers";
 
 import { validateSpecVersion } from "../lib/cli/cliOptions.js";
 import { createDynamicBom } from "../lib/cli/index.js";
+import { installConsoleShim, restoreConsole } from "../lib/core/ui.js";
 import {
   DEBUG_MODE,
   retrieveCdxgenVersion,
@@ -200,6 +201,12 @@ const args = _yargs
   })
   .wrap(Math.min(120, yargs().terminalWidth())).argv;
 
+// stdout carries the payload and nothing else; every diagnostic goes to the
+// live region's stream. Without the shim a `--print`/`--json` document shares
+// stdout with progress messages and cannot be piped into a parser.
+installConsoleShim();
+process.once("exit", restoreConsole);
+
 if (args.help) {
   console.log(`${retrieveCdxgenVersion()}\n`);
   _yargs.showHelp();
@@ -274,7 +281,8 @@ const options = {
   const jsonPayload = JSON.stringify(bomJson, null, DEBUG_MODE ? 2 : null);
 
   if (args.print) {
-    console.log(jsonPayload);
+    // The document is the payload, so it bypasses the console shim.
+    process.stdout.write(`${jsonPayload}\n`);
   }
 
   safeWriteSync(options.output, jsonPayload);

package/lib/cli/bomAssembly.js

@@ -220,7 +220,12 @@ function anchorDetectedParent(
     Array.isArray(components) &&
     !components.some((comp) => comp["bom-ref"] === detectedRef)
   ) {
-    components.push({ ...detectedParent });
+    // The detected parent carries transient keys (`license`, `evidence`,
+    // `_integrity`, `qualifiers`, `repository`, `homepage`) that only
+    // `metadata.component` is cleaned of. As a regular component it must go
+    // through the same conversion or schema validation rejects the document
+    // (issue #4320). The copy keeps the caller's context object untouched.
+    components.push(cleanParentComponent({ ...detectedParent }));
   }
   // The caller owns the array it passed, and postProcess merges these edges
   // across generators, so the re-anchoring is returned rather than spliced in.
@@ -1302,8 +1307,7 @@ export function processHashes(pkg, component) {
       addComponentHash(ahash.alg, ahash.content, component);
     }
   } else if (pkg._shasum) {
-    const ahash = { alg: "SHA-1", content: pkg._shasum };
-    component.hashes.push(ahash);
+    addComponentHash("SHA-1", pkg._shasum, component);
   } else if (pkg._integrity) {
     const integrity = parse(pkg._integrity) || {};
     // Components may have multiple hashes with various lengths. Check each one
@@ -1326,24 +1330,69 @@ export function processHashes(pkg, component) {
   }
 }
 
+// Digest length in hex characters for each algorithm CycloneDX names. A digest
+// that decodes to the wrong length for its algorithm is corrupt, whatever
+// encoding it arrived in.
+const HASH_HEX_LENGTHS = {
+  MD5: 32,
+  "SHA-1": 40,
+  "SHA-256": 64,
+  "SHA-384": 96,
+  "SHA-512": 128,
+  "SHA3-256": 64,
+  "SHA3-384": 96,
+  "SHA3-512": 128,
+  "BLAKE2b-256": 64,
+  "BLAKE2b-384": 96,
+  "BLAKE2b-512": 128,
+};
+
+// Lengths the CycloneDX hash-content pattern accepts, for algorithms not in the
+// table above.
+const HASH_HEX_LENGTHS_ANY = new Set([32, 40, 64, 96, 128]);
+
 /**
  * Adds a hash to component.
+ *
+ * Registries hand out digests in hex or in the base64 form npm uses for
+ * `integrity`, and both are accepted. A digest that is neither, or that decodes
+ * to the wrong length for its algorithm, is dropped rather than copied through:
+ * CycloneDX constrains `hash.content` to a hex digest, so emitting it anyway
+ * fails schema validation for the whole document over one bad package.
  */
 export function addComponentHash(alg, digest, component) {
-  let hash;
-  // If it is a valid hash simply use it
+  const hash = normalizeHashContent(alg, digest);
+  if (!hash) {
+    return;
+  }
+  component.hashes.push({ alg: alg, content: hash });
+}
+
+/**
+ * Normalize a digest to the lower-case hex form CycloneDX requires.
+ *
+ * @param {string} alg Hash algorithm name
+ * @param {string} digest Digest in hex or base64
+ * @returns {string|undefined} Hex digest, or undefined when it cannot be trusted
+ */
+export function normalizeHashContent(alg, digest) {
+  if (!digest || typeof digest !== "string") {
+    return undefined;
+  }
+  const expectedLength = HASH_HEX_LENGTHS[alg];
+  const isExpectedLength = (value) =>
+    expectedLength
+      ? value.length === expectedLength
+      : HASH_HEX_LENGTHS_ANY.has(value.length);
+
   if (new RegExp(HASH_PATTERN).test(digest)) {
-    hash = digest;
-  } else {
-    // Check if base64 encoded
-    const isBase64Encoded =
-      Buffer.from(digest, "base64").toString("base64") === digest;
-    hash = isBase64Encoded
-      ? Buffer.from(digest, "base64").toString("hex")
-      : digest;
+    return isExpectedLength(digest) ? digest : undefined;
   }
-  const ahash = { alg: alg, content: hash };
-  component.hashes.push(ahash);
+  // npm and friends carry the digest base64-encoded. Node decodes leniently, so
+  // the decoded length is the check that matters: a truncated or invented value
+  // decodes to something, just not to a digest of the right size.
+  const decoded = Buffer.from(digest, "base64").toString("hex");
+  return isExpectedLength(decoded) ? decoded : undefined;
 }
 
 /**

package/lib/cli/cliOptions.js

@@ -14,6 +14,7 @@
 import { join, resolve } from "node:path";
 
 import { isSecureMode, readEnvironmentVariable } from "../core/activity.js";
+import { PROJECT_TYPE_ALIASES } from "../core/env.js";
 import {
   DEFAULT_CDX_SPEC_VERSION,
   normalizeCycloneDxComponentTypeFilter,
@@ -217,6 +218,24 @@ export function buildInitialOptions(args, { filePath, isRemoteOrPurl }) {
   return res;
 }
 
+/**
+ * Check whether the supplied project types include an OS inventory type
+ * (`os` or an alias such as `linux`, `windows`, `macos`).
+ *
+ * @param {string|string[]|undefined|null} projectTypes Project types.
+ * @returns {boolean} True when an OS inventory type is requested.
+ */
+function hasOsProjectType(projectTypes) {
+  if (!projectTypes) {
+    return false;
+  }
+  const values = Array.isArray(projectTypes) ? projectTypes : [projectTypes];
+  const osTypes = new Set(["os", ...(PROJECT_TYPE_ALIASES.os || [])]);
+  return values
+    .flatMap((projectType) => `${projectType}`.split(","))
+    .some((projectType) => osTypes.has(projectType.trim().toLowerCase()));
+}
+
 /**
  * @typedef {object} OptionsWarning
  * @property {"info"|"warn"|"error"} level   Severity level
@@ -263,6 +282,17 @@ export function applyPostConstructionOverrides(options, context) {
             "The cbom command does not support --component-type. Use cdxgen with --include-crypto when you need component-type filtering.",
         });
       }
+      // Crypto evidence collection analyses source code with atom, which is
+      // meaningless and extremely slow for OS inventories (discussion #4310).
+      // Refuse the combination and direct users to obom.
+      if (hasOsProjectType(options.projectType)) {
+        warnings.push({
+          level: "error",
+          message:
+            "The cbom command does not support OS inventory project types (-t os). Use the obom command instead to generate an OBOM for an operating system installation.",
+        });
+        return warnings;
+      }
       options.includeCrypto = true;
     }
     options.evidence = true;

package/lib/core/logger.js

@@ -1,6 +1,8 @@
 import { Console } from "node:console";
 import fs from "node:fs";
 import process from "node:process";
+import { Writable } from "node:stream";
+import { isMainThread } from "node:worker_threads";
 
 // Environment variables here are read with raw `process.env` rather than
 // `readEnvironmentVariable`: that helper lives in activity.js, which imports
@@ -12,6 +14,18 @@ import process from "node:process";
 const logStream =
   process.env.CDXGEN_LOG_STREAM === "stdout" ? process.stdout : process.stderr;
 
+/**
+ * The stream every human-readable diagnostic is written to.
+ *
+ * Exported so that the live region and the table renderer resolve the same
+ * destination as the loggers do. A caller that sets `CDXGEN_LOG_STREAM=stdout`
+ * gets the pre-v13 behaviour for all of it, not just for the thought and trace
+ * logs.
+ *
+ * @type {NodeJS.WritableStream}
+ */
+export const diagnosticStream = logStream;
+
 // Custom lightweight colors formatting helper replacing yoctocolors
 const colors = {
   cyanBright: (text) => `\x1b[96m${text}\x1b[39m`,
@@ -24,11 +38,83 @@ export const THINK_MODE =
   ["true", "1"].includes(process.env.CDXGEN_THINK_MODE) ||
   process.env.CDXGEN_DEBUG_MODE === "verbose";
 
+// Log files are written synchronously rather than through
+// `fs.createWriteStream`. A write stream buffers, so anything still queued when
+// the process exits is lost, leaving readers that tail these files a truncated
+// log with no closing `</think>` marker. Writing through one shared descriptor
+// per path also keeps the two Console channels from interleaving at
+// independent file offsets.
+const syncFileWriters = new Map();
+
+/**
+ * Open a synchronous writer for a log file path.
+ *
+ * `Console` requires a real stream, so this is a `Writable` whose `_write`
+ * completes synchronously: bytes reach the descriptor as each record is
+ * logged, and nothing is left queued for an event loop turn that a process
+ * exit may never take.
+ *
+ * @param {string} filePath Destination path
+ * @returns {Writable} Writer, or the diagnostic stream when the path is unwritable
+ */
+function openSyncFileWriter(filePath) {
+  const existing = syncFileWriters.get(filePath);
+  if (existing) {
+    return existing;
+  }
+  let fd;
+  try {
+    // Worker threads log to the same path through their own instance of this
+    // module, so the descriptor is opened in append mode: O_APPEND lands every
+    // write at the end of the file no matter how many writers share it, where
+    // a truncating open gives each writer its own offset and they punch holes
+    // through each other's records. The main thread truncates once so a run
+    // still starts from an empty log.
+    if (isMainThread) {
+      try {
+        fs.truncateSync(filePath, 0);
+      } catch {
+        // No file yet: the append open below creates it.
+      }
+    }
+    fd = fs.openSync(filePath, "a");
+  } catch {
+    // An unwritable path must not take the whole run down: fall back to the
+    // diagnostic stream so the records stay visible somewhere.
+    return logStream;
+  }
+  const writer = new Writable({
+    write(chunk, _encoding, callback) {
+      if (fd !== undefined) {
+        try {
+          fs.writeSync(fd, chunk);
+        } catch {
+          // A full disk or a revoked descriptor must not abort BOM generation.
+        }
+      }
+      callback();
+    },
+  });
+  writer.closeSync = () => {
+    if (fd === undefined) {
+      return;
+    }
+    try {
+      fs.closeSync(fd);
+    } finally {
+      fd = undefined;
+      syncFileWriters.delete(filePath);
+    }
+  };
+  syncFileWriters.set(filePath, writer);
+  return writer;
+}
+
 const thinkOutput = process.env.CDXGEN_THOUGHT_LOG
-  ? fs.createWriteStream(process.env.CDXGEN_THOUGHT_LOG)
+  ? openSyncFileWriter(process.env.CDXGEN_THOUGHT_LOG)
   : logStream;
 const thinkErrorOutput = process.env.CDXGEN_THOUGHT_LOG
-  ? fs.createWriteStream(process.env.CDXGEN_THOUGHT_LOG)
+  ? thinkOutput
   : process.stderr;
 const thinkLogger = new Console({
   stdout: thinkOutput,
@@ -44,10 +130,10 @@ export const TRACE_MODE =
   process.env.CDXGEN_DEBUG_MODE === "verbose";
 
 const traceOutput = process.env.CDXGEN_TRACE_LOG
-  ? fs.createWriteStream(process.env.CDXGEN_TRACE_LOG)
+  ? openSyncFileWriter(process.env.CDXGEN_TRACE_LOG)
   : logStream;
 const traceErrorOutput = process.env.CDXGEN_TRACE_LOG
-  ? fs.createWriteStream(process.env.CDXGEN_TRACE_LOG)
+  ? traceOutput
   : process.stderr;
 const traceLogger = new Console({
   stdout: traceOutput,
@@ -80,14 +166,18 @@ export function thoughtLog(s, args) {
     thinkLogger.log(colorizeText(`${s}`));
   }
 }
+let thoughtBlockClosed = false;
+
 /**
  * Closes the think log group by emitting the closing `</think>` marker.
- * Has no effect if THINK_MODE is not enabled.
+ * Has no effect if THINK_MODE is not enabled, and emits the marker at most
+ * once so an explicit call followed by the exit handler cannot produce two.
  *
  * @returns {void}
  */
 export function thoughtEnd() {
-  if (THINK_MODE) {
+  if (THINK_MODE && !thoughtBlockClosed) {
+    thoughtBlockClosed = true;
     thinkLogger.groupEnd();
     thinkLogger.log(colorizeText("</think>"));
   }
@@ -103,6 +193,33 @@ function colorizeText(s) {
   return colors.dim(s);
 }
 
+// Fields serialized for each trace type. The allow-list is per-type because a
+// single shared list either drops the fields a type exists to carry or leaks
+// unbounded caller objects into the stream: `activity` and `phase` records
+// carry no field in common with `spawn` and `http`.
+const TRACE_FIELDS = {
+  activity: [
+    "identifier",
+    "kind",
+    "status",
+    "target",
+    "reason",
+    "networkIntent",
+    "command",
+    "cwd",
+  ],
+  phase: ["phase", "state", "detail", "note", "done", "total", "elapsedMs"],
+};
+
+const DEFAULT_TRACE_FIELDS = [
+  "command",
+  "cwd",
+  "protocol",
+  "host",
+  "path",
+  "pathname",
+];
+
 /**
  * Log trace messages
  *
@@ -123,15 +240,10 @@ export function traceLog(traceType, args) {
     message.type = traceType;
   }
   if (args) {
-    for (const k of [
-      "command",
-      "cwd",
-      "protocol",
-      "host",
-      "path",
-      "pathname",
-    ]) {
-      if (args[k]) {
+    for (const k of TRACE_FIELDS[traceType] || DEFAULT_TRACE_FIELDS) {
+      // Numeric progress counters are meaningful at zero, so presence is
+      // tested rather than truthiness.
+      if (args[k] !== undefined && args[k] !== null && args[k] !== "") {
         message[k] = args[k];
       }
     }
@@ -140,3 +252,29 @@ export function traceLog(traceType, args) {
     traceLogger.log(JSON.stringify(message, null, null));
   }
 }
+
+let logStreamsClosed = false;
+
+/**
+ * Terminate the think block and close the log file descriptors.
+ *
+ * Readers tail these files as a live feed, so a run that ends without the
+ * closing `</think>` marker leaves the consumer holding an unterminated block.
+ * Registered on process exit and safe to call more than once.
+ *
+ * @returns {void}
+ */
+export function closeLogStreams() {
+  if (logStreamsClosed) {
+    return;
+  }
+  logStreamsClosed = true;
+  thoughtEnd();
+  for (const writer of [...syncFileWriters.values()]) {
+    writer.closeSync();
+  }
+}
+
+// The writers are synchronous, so this handler only has to emit the terminator
+// and release the descriptors — work that is legal during `exit`.
+process.on("exit", closeLogStreams);

package/lib/core/ui.js

@@ -17,6 +17,7 @@ import process from "node:process";
 import { formatWithOptions, inspect } from "node:util";
 
 import { readEnvironmentVariable } from "./activity.js";
+import { diagnosticStream, TRACE_MODE, traceLog } from "./logger.js";
 import { stringWidth, stripAnsi } from "./text.js";
 
 // Frame interval, and the floor on how often detail/progress updates redraw.
@@ -94,7 +95,11 @@ const PHASE_OUTCOMES = {
  * @returns {{stream: object, interactive: boolean, color: boolean, unicode: boolean, glyphs: object, columns: () => number, rows: () => number}} Capability snapshot
  */
 export function detectCapabilities(overrides = {}) {
-  const stream = overrides.stream || process.stderr;
+  // `CDXGEN_LOG_STREAM=stdout` is the documented escape hatch for callers that
+  // scraped v12's stdout. Resolving the destination here rather than pinning
+  // stderr is what makes it apply to the region, the banners and the tables
+  // instead of only to the thought and trace logs.
+  const stream = overrides.stream || diagnosticStream;
   const env = overrides.env;
   const read = (name) => (env ? env[name] : readEnvironmentVariable(name));
   const isSet = (name) => {
@@ -282,7 +287,7 @@ function formatArgs(args) {
  * Create a live-region controller.
  *
  * @param {object} [options] Controller options
- * @param {object} [options.stream] Writable stream (default `process.stderr`)
+ * @param {object} [options.stream] Writable stream (default: the diagnostic stream, stderr unless `CDXGEN_LOG_STREAM=stdout`)
  * @param {number|string} [options.level] Verbosity ladder 0..3
  * @param {("text"|"json")} [options.format] Log serialization format
  * @param {boolean} [options.noProgress] Force-disable the live region
@@ -538,6 +543,40 @@ export function createUi(options = {}) {
     }
   }
 
+  /**
+   * Mirror a phase transition onto the trace stream.
+   *
+   * The live region is a terminal affordance, so a piped consumer such as the
+   * cdxui terminal UI would otherwise have to scrape formatted lines to learn
+   * what cdxgen is doing. Emitting the phase model structurally lets it render
+   * its own progress. `progress` transitions are throttled to the frame
+   * interval so a per-file loop costs one event per frame, not one per file.
+   *
+   * @param {object} handle Phase handle
+   * @param {string} state One of started, progress, succeeded, failed, skipped
+   */
+  function tracePhase(handle, state) {
+    if (!TRACE_MODE) {
+      return;
+    }
+    const at = now();
+    if (state === "progress") {
+      if (at - (handle.tracedAt || 0) < REFRESH_MS) {
+        return;
+      }
+      handle.tracedAt = at;
+    }
+    traceLog("phase", {
+      phase: handle.label,
+      state,
+      detail: handle.detailText ?? undefined,
+      note: handle.note ?? undefined,
+      done: handle.total > 0 ? handle.done : undefined,
+      total: handle.total > 0 ? handle.total : undefined,
+      elapsedMs: at - handle.startedAt,
+    });
+  }
+
   function commitPhase(phase) {
     const outcome = PHASE_OUTCOMES[phase.status] || PHASE_OUTCOMES.succeeded;
     const glyph = caps.glyphs[phase.status] || caps.glyphs.succeeded;
@@ -568,6 +607,7 @@ export function createUi(options = {}) {
       startedAt: now(),
       note: null,
       committed: false,
+      tracedAt: 0,
 
       /**
        * Replace the trailing detail text on this phase's row.
@@ -578,6 +618,7 @@ export function createUi(options = {}) {
       detail(text) {
         if (!this.committed) {
           this.detailText = text ? `${text}` : null;
+          tracePhase(this, "progress");
           requestRender();
         }
         return this;
@@ -594,6 +635,7 @@ export function createUi(options = {}) {
         if (!this.committed) {
           this.done = Number(done) || 0;
           this.total = Number(total) || 0;
+          tracePhase(this, "progress");
           requestRender();
         }
         return this;
@@ -631,6 +673,7 @@ export function createUi(options = {}) {
       },
     };
     running.push(handle);
+    tracePhase(handle, "started");
     startTimer();
     requestRender(true);
     return handle;
@@ -643,6 +686,7 @@ export function createUi(options = {}) {
     handle.committed = true;
     handle.status = status;
     handle.note = note ? `${note}` : null;
+    tracePhase(handle, status);
     const index = running.indexOf(handle);
     if (index >= 0) {
       running.splice(index, 1);