@superblocksteam/sdk 2.0.149 → 2.0.150-next.1

package/src/cli-replacement/npm-install-summary.test.mts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+
+import { parseNpmInstallSummary } from "./npm-install-summary.mjs";
+
+describe("parseNpmInstallSummary", () => {
+  it("reads npm's numeric count summary", () => {
+    expect(
+      parseNpmInstallSummary(
+        JSON.stringify({
+          added: 8,
+          removed: 0,
+          changed: 2,
+          audited: 432,
+          funding: 12,
+        }),
+      ),
+    ).toEqual({ added: 8, removed: 0, changed: 2, audited: 432 });
+  });
+
+  // Some npm versions emit the affected packages as arrays instead of counts.
+  it("reads the array form by taking lengths", () => {
+    expect(
+      parseNpmInstallSummary(
+        JSON.stringify({
+          added: [{ name: "@dnd-kit/core" }, { name: "@dnd-kit/utilities" }],
+          removed: [],
+          changed: [{ name: "react" }],
+          audited: 432,
+        }),
+      ),
+    ).toEqual({ added: 2, removed: 0, changed: 1, audited: 432 });
+  });
+
+  // `{}` carries none of npm's summary keys, so it is indistinguishable from
+  // another tool's JSON output. Treat it as unrecognized: the caller's
+  // raw_output fallback keeps the text recoverable instead of logging a
+  // confident all-zero install that never happened.
+  it("returns null for a JSON object without any npm summary keys", () => {
+    expect(parseNpmInstallSummary("{}")).toBeNull();
+    // e.g. a different package manager honoring --json with its own shape
+    expect(
+      parseNpmInstallSummary(
+        JSON.stringify({ success: true, warnings: [], elapsed: 3200 }),
+      ),
+    ).toBeNull();
+  });
+
+  it("tolerates surrounding whitespace and npm's trailing newline", () => {
+    expect(parseNpmInstallSummary('\n  {"added": 1}\n')).toEqual({
+      added: 1,
+      removed: 0,
+      changed: 0,
+      audited: 0,
+    });
+  });
+
+  it("returns null for empty output", () => {
+    expect(parseNpmInstallSummary("")).toBeNull();
+    expect(parseNpmInstallSummary("   \n ")).toBeNull();
+  });
+
+  it("returns null for non-JSON output rather than throwing", () => {
+    expect(parseNpmInstallSummary("added 8 packages in 32s")).toBeNull();
+  });
+
+  it("returns null for JSON that is not an object", () => {
+    expect(parseNpmInstallSummary("[]")).toBeNull();
+    expect(parseNpmInstallSummary('"done"')).toBeNull();
+  });
+
+  it("clamps a negative count so aggregations cannot be skewed", () => {
+    expect(parseNpmInstallSummary(JSON.stringify({ added: -3 }))).toEqual({
+      added: 0,
+      removed: 0,
+      changed: 0,
+      audited: 0,
+    });
+  });
+
+  it("truncates a fractional count to an integer", () => {
+    expect(parseNpmInstallSummary(JSON.stringify({ audited: 12.9 }))).toEqual({
+      added: 0,
+      removed: 0,
+      changed: 0,
+      audited: 12,
+    });
+  });
+
+  it("ignores unexpected value types instead of emitting NaN", () => {
+    expect(
+      parseNpmInstallSummary(JSON.stringify({ added: "eight", removed: null })),
+    ).toEqual({ added: 0, removed: 0, changed: 0, audited: 0 });
+  });
+});

package/src/cli-replacement/npm-install-timing.mts

@@ -0,0 +1,121 @@
+/**
+ * npm's `--json` install summary says how many packages changed, but not where
+ * the time went. A real install reported `changed: 5, added: 0` alongside a
+ * 27 second duration - the counts cannot explain that. Measuring the same pod
+ * by hand showed the time was `reify:unpack` writing about 65,000 files (23.2s
+ * of 24.5s), while resolving metadata (`idealTree`) took 230ms. Without that
+ * split, a slow install is indistinguishable from a slow registry.
+ *
+ * npm records the split itself when run with `--timing`. It does NOT go to
+ * stdout: npm writes `<logs-dir>/<log id>-timing.json`, shaped
+ * `{ metadata, timers, unfinishedTimers }`, where `timers` is a flat object of
+ * timer name to milliseconds.
+ */
+import nodeFs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * The only timers we are willing to emit, paired with their attribute name.
+ *
+ * This has to be a fixed list rather than a pass-through of `timers`, because
+ * npm also records one `reifyNode:node_modules/<package>` timer per package it
+ * touched. Emitting those would mean unbounded attribute cardinality and would
+ * put dependency names into telemetry.
+ *
+ * Seconds, to match the `superblocks.npm.install.duration_seconds` attribute
+ * these sit next to.
+ */
+const TIMER_ATTRIBUTES: ReadonlyArray<readonly [string, string]> = [
+  ["idealTree", "superblocks.npm.install.ideal_tree_seconds"],
+  ["reify", "superblocks.npm.install.reify_seconds"],
+  ["reify:build", "superblocks.npm.install.build_seconds"],
+  ["reify:loadTrees", "superblocks.npm.install.load_trees_seconds"],
+  ["reify:unpack", "superblocks.npm.install.unpack_seconds"],
+];
+
+const TIMING_FILE_SUFFIX = "-timing.json";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * npm's log ids are fixed-width ISO timestamps (`2026-08-07T12_00_00_000Z`),
+ * so sorting the names alphabetically orders them by time. Cheaper and more
+ * predictable than stat-ing every file for an mtime.
+ */
+async function listTimingFiles(logsDir: string): Promise<string[]> {
+  const entries = await nodeFs.readdir(logsDir);
+  return entries.filter((name) => name.endsWith(TIMING_FILE_SUFFIX)).sort();
+}
+
+/**
+ * npm's own `logs-max` pruning covers its debug logs but leaves timing files
+ * alone, so they would pile up on the app volume for the life of the pod. We
+ * only ever need the one we just read, so drop them all once it is read.
+ */
+async function removeTimingFiles(
+  logsDir: string,
+  names: string[],
+): Promise<void> {
+  await Promise.all(
+    names.map((name) =>
+      nodeFs.unlink(path.join(logsDir, name)).catch(() => undefined),
+    ),
+  );
+}
+
+function toSeconds(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  // A negative duration is meaningless and would skew any aggregation built on
+  // these attributes.
+  return Math.max(0, value) / 1000;
+}
+
+/**
+ * Read the phase durations npm recorded for the most recent install, then
+ * delete the timing files so the logs dir stays bounded.
+ *
+ * Returns null when there is nothing usable - no timing file, an unreadable or
+ * non-JSON file, or a file carrying none of the whitelisted timers. A timer
+ * npm did not record is omitted rather than reported as 0, because "npm
+ * unpacked nothing" and "npm never got as far as unpacking" are different
+ * facts; a recorded 0 IS emitted, since an install that unpacked nothing is
+ * exactly the case worth telling apart from a slow one.
+ *
+ * Never throws: this runs on the success path of a completed install, and no
+ * telemetry read may turn that into a failure.
+ */
+export async function consumeNpmInstallTimingAttributes(
+  logsDir: string,
+): Promise<Record<string, number> | null> {
+  try {
+    const names = await listTimingFiles(logsDir);
+    const newest = names.at(-1);
+    if (newest === undefined) {
+      return null;
+    }
+
+    const raw = await nodeFs.readFile(path.join(logsDir, newest), "utf8");
+    await removeTimingFiles(logsDir, names);
+
+    const parsed: unknown = JSON.parse(raw);
+    if (!isRecord(parsed) || !isRecord(parsed.timers)) {
+      return null;
+    }
+    const timers = parsed.timers;
+
+    const attributes: Record<string, number> = {};
+    for (const [timer, attribute] of TIMER_ATTRIBUTES) {
+      const seconds = toSeconds(timers[timer]);
+      if (seconds !== undefined) {
+        attributes[attribute] = seconds;
+      }
+    }
+    return Object.keys(attributes).length > 0 ? attributes : null;
+  } catch {
+    return null;
+  }
+}

package/src/cli-replacement/npm-install-timing.test.mts

@@ -0,0 +1,199 @@
+import nodeFs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { consumeNpmInstallTimingAttributes } from "./npm-install-timing.mjs";
+
+let logsDir: string;
+
+beforeEach(async () => {
+  logsDir = await nodeFs.mkdtemp(path.join(os.tmpdir(), "npm-timing-"));
+});
+
+afterEach(async () => {
+  await nodeFs.rm(logsDir, { force: true, recursive: true });
+});
+
+/** Write a timing file using npm's own naming (`<log id>-timing.json`). */
+async function writeTimingFile(
+  logId: string,
+  contents: unknown,
+): Promise<string> {
+  const file = path.join(logsDir, `${logId}-timing.json`);
+  await nodeFs.writeFile(
+    file,
+    typeof contents === "string" ? contents : JSON.stringify(contents),
+  );
+  return file;
+}
+
+async function listTimingFiles(): Promise<string[]> {
+  const entries = await nodeFs.readdir(logsDir);
+  return entries.filter((name) => name.endsWith("-timing.json"));
+}
+
+describe("consumeNpmInstallTimingAttributes", () => {
+  it("converts the whitelisted timers from milliseconds to seconds", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      metadata: { version: "11.16.0" },
+      timers: {
+        idealTree: 230,
+        reify: 24500,
+        "reify:build": 90,
+        "reify:loadTrees": 400,
+        "reify:unpack": 23200,
+      },
+      unfinishedTimers: {},
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.build_seconds": 0.09,
+      "superblocks.npm.install.ideal_tree_seconds": 0.23,
+      "superblocks.npm.install.load_trees_seconds": 0.4,
+      "superblocks.npm.install.reify_seconds": 24.5,
+      "superblocks.npm.install.unpack_seconds": 23.2,
+    });
+  });
+
+  // npm records one `reifyNode:node_modules/<package>` timer per package it
+  // touched. Emitting those would be unbounded attribute cardinality and would
+  // put dependency names into telemetry, so only the fixed whitelist is ever
+  // emitted.
+  it("never emits a per-package reifyNode timer", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: {
+        idealTree: 100,
+        "reifyNode:node_modules/@dnd-kit/core": 12,
+        "reifyNode:node_modules/lodash": 34,
+        "reifyNode:node_modules/react": 56,
+      },
+    });
+
+    const attributes = await consumeNpmInstallTimingAttributes(logsDir);
+
+    expect(attributes).toEqual({
+      "superblocks.npm.install.ideal_tree_seconds": 0.1,
+    });
+    expect(
+      Object.keys(attributes ?? {}).some((key) => key.includes("reifyNode")),
+    ).toBe(false);
+  });
+
+  // Which phases npm records depends on what the install did, so a missing
+  // timer is normal rather than an error.
+  it("omits timers npm did not record", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { reify: 500 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.reify_seconds": 0.5,
+    });
+  });
+
+  // "npm unpacked nothing" is the signal that separates a metadata-only
+  // install from one that wrote tens of thousands of files, so a recorded zero
+  // is real data and must not be dropped as if it were missing.
+  it("emits a recorded zero rather than dropping it", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { "reify:unpack": 0 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.unpack_seconds": 0,
+    });
+  });
+
+  // npm's log ids are fixed-width ISO timestamps, so the newest file is the
+  // last one alphabetically.
+  it("reads the newest file when older installs left files behind", async () => {
+    await writeTimingFile("2026-08-07T11_00_00_000Z", {
+      timers: { reify: 1000 },
+    });
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { reify: 2000 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.reify_seconds": 2,
+    });
+  });
+
+  // npm's `logs-max` pruning only covers its debug logs, so timing files would
+  // pile up on the app volume forever if nothing removed them.
+  it("removes the timing files it read so they cannot accumulate", async () => {
+    await writeTimingFile("2026-08-07T11_00_00_000Z", {
+      timers: { reify: 1000 },
+    });
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { reify: 2000 },
+    });
+    const debugLog = path.join(logsDir, "2026-08-07T12_00_00_000Z-debug-0.log");
+    await nodeFs.writeFile(debugLog, "npm debug output");
+
+    await consumeNpmInstallTimingAttributes(logsDir);
+
+    expect(await listTimingFiles()).toEqual([]);
+    // npm's debug log is a separate diagnostic that must survive.
+    await expect(nodeFs.readFile(debugLog, "utf8")).resolves.toBe(
+      "npm debug output",
+    );
+  });
+
+  it("returns null when the logs dir has no timing file", async () => {
+    await nodeFs.writeFile(
+      path.join(logsDir, "2026-08-07T12_00_00_000Z-debug-0.log"),
+      "npm debug output",
+    );
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toBeNull();
+  });
+
+  it("returns null when the logs dir does not exist", async () => {
+    expect(
+      await consumeNpmInstallTimingAttributes(path.join(logsDir, "missing")),
+    ).toBeNull();
+  });
+
+  it("returns null for a file that is not JSON rather than throwing", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", "not json at all");
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toBeNull();
+  });
+
+  it("returns null when the file carries no timers object", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", { metadata: {} });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toBeNull();
+  });
+
+  it("returns null when none of the whitelisted timers are present", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { "npm:load": 12, "reifyNode:node_modules/lodash": 34 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toBeNull();
+  });
+
+  it("ignores timer values that are not finite numbers", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { idealTree: "230", reify: null, "reify:unpack": 23200 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.unpack_seconds": 23.2,
+    });
+  });
+
+  it("clamps a negative duration so dashboards cannot be skewed", async () => {
+    await writeTimingFile("2026-08-07T12_00_00_000Z", {
+      timers: { reify: -500 },
+    });
+
+    expect(await consumeNpmInstallTimingAttributes(logsDir)).toEqual({
+      "superblocks.npm.install.reify_seconds": 0,
+    });
+  });
+});

package/src/telemetry/logging.test.ts

@@ -156,6 +156,61 @@ describe("telemetry logger error sanitization", () => {
   });
 });
 
+describe("telemetry logger infoStructured", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("emits an INFO record carrying structured attributes (not flattened into the body)", () => {
+    const logger = getLogger();
+
+    logger.infoStructured?.("Package installation completed successfully", {
+      "superblocks.npm.install.added": 8,
+      "superblocks.npm.install.duration_seconds": 32.5,
+      "superblocks.npm.install.outcome": "success",
+    });
+
+    expect(emitMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        severityText: "INFO",
+        body: "sanitized-message:Package installation completed successfully",
+        attributes: {
+          "superblocks.npm.install.added": 8,
+          "superblocks.npm.install.duration_seconds": 32.5,
+          "superblocks.npm.install.outcome": "sanitized-object:success",
+        },
+      }),
+    );
+    // Winston gets the body only (structured attributes go to OTel, not also
+    // to stdout log shippers as a duplicate).
+    expect(winstonLoggerMock.info).toHaveBeenCalledWith(
+      "sanitized-message:Package installation completed successfully",
+    );
+  });
+
+  it("strips secret-named attribute keys before emitting", () => {
+    const logger = getLogger();
+
+    logger.infoStructured?.("install done", {
+      registry: "https://npm.example.com",
+      token: "[REDACTED:token]",
+    });
+
+    expect(emitMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: expect.objectContaining({
+          registry: "sanitized-object:https://npm.example.com",
+        }),
+      }),
+    );
+    expect(emitMock).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: expect.objectContaining({ token: expect.anything() }),
+      }),
+    );
+  });
+});
+
 describe("telemetry logger warnStructured", () => {
   beforeEach(() => {
     vi.clearAllMocks();

package/src/telemetry/logging.ts

@@ -79,6 +79,13 @@ export interface Logger {
   debug: (...messages: unknown[]) => void;
   info: (...messages: unknown[]) => void;
   warn: (...messages: unknown[]) => void;
+  /**
+   * Emit an INFO-level log whose structured attributes are exported as OTel
+   * log attributes (Datadog facets) instead of being flattened into the
+   * message body. Plain `info()` joins every argument into one body string, so
+   * attributes passed to it are never queryable.
+   */
+  infoStructured?: (message: string, attributes: LogAttributes) => void;
   /**
    * Emit a WARN-level log whose structured attributes are exported as OTel log
    * attributes (Datadog facets) instead of being flattened into the message
@@ -120,6 +127,18 @@ const logger: Logger = Object.freeze({
     });
     winstonLogger.warn(body);
   },
+  infoStructured: (message: string, attributes: LogAttributes) => {
+    const body = sanitizeLogMessage(message);
+    // Same sanitize-then-emit contract as warnStructured below.
+    const safeAttributes = sanitizeLogObject(attributes);
+    getTracedLogger().emit({
+      severityNumber: SeverityNumber.INFO,
+      severityText: "INFO",
+      body,
+      attributes: safeAttributes,
+    });
+    winstonLogger.info(body);
+  },
   warnStructured: (message: string, attributes: LogAttributes) => {
     const body = sanitizeLogMessage(message);
     // sanitizeLogObject strips secret-named keys and redacts secret values,
@@ -174,6 +193,8 @@ export function getLogger(
     // above, it forwards raw args to the supplied function and does NOT
     // sanitize or emit OTel attributes. Production callers use the default
     // logger (and the vite-plugin wrapLogger) which sanitize before emitting.
+    infoStructured: (message: string, attributes: LogAttributes) =>
+      loggerOverride(message, attributes),
     warnStructured: (message: string, attributes: LogAttributes) =>
       loggerOverride(message, attributes),
     error: loggerOverride as (message: string, meta?: ErrorMeta) => void,