@superblocksteam/sdk 2.0.150-next.0 → 2.0.150-next.2

package/src/cli-replacement/install-packages.npm-registry.test.mts

@@ -26,6 +26,7 @@ import {
 } from "vitest";
 
 import type { installPackages as InstallPackagesType } from "./dev.mjs";
+import type * as DiskSpace from "./disk-space.mjs";
 
 const execMock = vi.fn();
 const execFileMock = vi.fn();
@@ -45,6 +46,17 @@ vi.mock("package-manager-detector", () => ({
   resolveCommand: (...args: unknown[]) => resolveCommandMock(...args),
 }));
 
+const recoverFromDiskFullMock = vi.fn();
+vi.mock("./disk-space.mjs", async (importOriginal) => {
+  const actual = await importOriginal<typeof DiskSpace>();
+  return {
+    ...actual,
+    getDiskSpace: vi.fn(async () => null),
+    recoverFromDiskFull: (...args: unknown[]) =>
+      recoverFromDiskFullMock(...args),
+  };
+});
+
 vi.mock("node:fs/promises", () => ({
   readFile: vi.fn(async () => "{}"),
   writeFile: vi.fn(async () => undefined),
@@ -53,8 +65,20 @@ vi.mock("node:fs/promises", () => ({
   mkdir: vi.fn(async () => undefined),
 }));
 
+// npm's `--timing` phase breakdown is read back from a file on disk. The
+// parser has its own coverage in `npm-install-timing.test.mts`; here we only
+// care that whatever it returns reaches the success log line.
+const consumeTimingMock = vi.fn<
+  (logsDir: string) => Promise<Record<string, number> | null>
+>(async () => null);
+vi.mock("./npm-install-timing.mjs", () => ({
+  consumeNpmInstallTimingAttributes: (logsDir: string) =>
+    consumeTimingMock(logsDir),
+}));
+
 const mockLogger = {
   info: vi.fn(),
+  infoStructured: vi.fn(),
   warn: vi.fn(),
   error: vi.fn(),
   debug: vi.fn(),
@@ -118,6 +142,8 @@ beforeAll(async () => {
 
 beforeEach(() => {
   vi.clearAllMocks();
+  mockLogger.infoStructured.mockReset();
+  mockLogger.warn.mockReset();
   // Default: npm package manager, install resolves to a real command so we
   // can read back the args the call site passed in.
   detectMock.mockResolvedValue({
@@ -146,6 +172,8 @@ beforeEach(() => {
       }
     },
   );
+  recoverFromDiskFullMock.mockResolvedValue(undefined);
+  consumeTimingMock.mockResolvedValue(null);
 });
 
 function getResolveCommandArgs(): string[] {
@@ -183,6 +211,7 @@ describe("installPackages honors allow_install_scripts policy", () => {
     // Existing baseline npm flags must survive.
     expect(args).toContain("--fund=false");
     expect(args).toContain("--audit=false");
+    expect(args).toContain("--timing");
   });
 
   it("does NOT append --ignore-scripts when allow_install_scripts === true", async () => {
@@ -252,6 +281,8 @@ describe("installPackages honors allow_install_scripts policy", () => {
     expect(args).toContain("--ignore-scripts");
     expect(args).not.toContain("--fund=false");
     expect(args).not.toContain("--audit=false");
+    // pnpm has no equivalent of npm's phase timing.
+    expect(args).not.toContain("--timing");
   });
 });
 
@@ -343,3 +374,207 @@ describe("installPackages userconfig env plumbing", () => {
   //     (`userconfig-env.integration.test.mts`) would fail to resolve
   //     `npm`/`pnpm` on PATH if the overlay clobbered it.
 });
+
+describe("installPackages success logging", () => {
+  it("keeps unrecognized package-manager output out of structured attributes", async () => {
+    const { installPackages } = await import("./dev.mjs");
+
+    await installPackages("/tmp/app", mockLogger as never);
+
+    expect(mockLogger.infoStructured).toHaveBeenCalledWith(
+      "Package installation completed successfully",
+      {
+        "superblocks.npm.install.disk_recovered": false,
+        "superblocks.npm.install.duration_seconds": expect.any(Number),
+        "superblocks.npm.install.summary_parsed": false,
+      },
+    );
+    expect(mockLogger.info).toHaveBeenCalledWith("ok");
+  });
+
+  it("marks parsed npm summaries and emits their counts", async () => {
+    const stdout = JSON.stringify({
+      added: 8,
+      audited: 432,
+      changed: 2,
+      removed: 0,
+    });
+    execMock.mockImplementation(
+      (
+        _cmd: string,
+        _opts: unknown,
+        cb?: (err: null, result: { stdout: string }) => void,
+      ) => cb?.(null, { stdout }),
+    );
+    const { installPackages } = await import("./dev.mjs");
+
+    await installPackages("/tmp/app", mockLogger as never);
+
+    expect(mockLogger.infoStructured).toHaveBeenCalledWith(
+      "Package installation completed successfully",
+      {
+        "superblocks.npm.install.added": 8,
+        "superblocks.npm.install.audited": 432,
+        "superblocks.npm.install.changed": 2,
+        "superblocks.npm.install.disk_recovered": false,
+        "superblocks.npm.install.duration_seconds": expect.any(Number),
+        "superblocks.npm.install.removed": 0,
+        "superblocks.npm.install.summary_parsed": true,
+      },
+    );
+    expect(mockLogger.info).not.toHaveBeenCalledWith(stdout);
+  });
+
+  it("joins npm's phase timings to the same success log line", async () => {
+    consumeTimingMock.mockResolvedValue({
+      "superblocks.npm.install.ideal_tree_seconds": 0.23,
+      "superblocks.npm.install.unpack_seconds": 23.2,
+    });
+    const stdout = JSON.stringify({
+      added: 0,
+      audited: 432,
+      changed: 5,
+      removed: 0,
+    });
+    execMock.mockImplementation(
+      (
+        _cmd: string,
+        _opts: unknown,
+        cb?: (err: null, result: { stdout: string }) => void,
+      ) => cb?.(null, { stdout }),
+    );
+    const { installPackages } = await import("./dev.mjs");
+
+    await installPackages("/tmp/app", mockLogger as never);
+
+    // npm writes the timing file into the same dir as its debug log.
+    expect(consumeTimingMock).toHaveBeenCalledWith(
+      "/tmp/app/.superblocks/logs",
+    );
+    expect(mockLogger.infoStructured).toHaveBeenCalledWith(
+      "Package installation completed successfully",
+      {
+        "superblocks.npm.install.added": 0,
+        "superblocks.npm.install.audited": 432,
+        "superblocks.npm.install.changed": 5,
+        "superblocks.npm.install.disk_recovered": false,
+        "superblocks.npm.install.duration_seconds": expect.any(Number),
+        "superblocks.npm.install.ideal_tree_seconds": 0.23,
+        "superblocks.npm.install.removed": 0,
+        "superblocks.npm.install.summary_parsed": true,
+        "superblocks.npm.install.unpack_seconds": 23.2,
+      },
+    );
+  });
+
+  it("still logs the counts when there is no timing file to read", async () => {
+    consumeTimingMock.mockResolvedValue(null);
+    const { installPackages } = await import("./dev.mjs");
+
+    await installPackages("/tmp/app", mockLogger as never);
+
+    expect(mockLogger.infoStructured).toHaveBeenCalledWith(
+      "Package installation completed successfully",
+      {
+        "superblocks.npm.install.disk_recovered": false,
+        "superblocks.npm.install.duration_seconds": expect.any(Number),
+        "superblocks.npm.install.summary_parsed": false,
+      },
+    );
+  });
+
+  it("does not read a timing file under pnpm, which cannot write one", async () => {
+    detectMock.mockResolvedValue({
+      name: "pnpm",
+      agent: "pnpm",
+      version: "11.0.0",
+    });
+    resolveCommandMock.mockImplementation(
+      (_agent: string, _action: string, args: string[]) => ({
+        command: "pnpm",
+        args: ["install", ...args],
+      }),
+    );
+    const { installPackages } = await import("./dev.mjs");
+
+    await installPackages("/tmp/app", mockLogger as never);
+
+    // A leftover npm timing file must not be reported as pnpm's timings.
+    expect(consumeTimingMock).not.toHaveBeenCalled();
+  });
+
+  it("does not fail a completed install when the timing read rejects", async () => {
+    consumeTimingMock.mockRejectedValue(new Error("logs dir unreadable"));
+    const { installPackages } = await import("./dev.mjs");
+
+    await expect(
+      installPackages("/tmp/app", mockLogger as never),
+    ).resolves.toBeUndefined();
+
+    expect(execMock).toHaveBeenCalledTimes(1);
+    expect(mockLogger.infoStructured).toHaveBeenCalledWith(
+      "Package installation completed successfully",
+      expect.objectContaining({
+        "superblocks.npm.install.duration_seconds": expect.any(Number),
+      }),
+    );
+  });
+
+  it("does not fail or retry when success logging throws", async () => {
+    mockLogger.infoStructured.mockImplementationOnce(() => {
+      throw new Error("telemetry unavailable");
+    });
+    mockLogger.warn.mockImplementation((message: string) => {
+      if (message === "Could not emit package installation success telemetry") {
+        throw new Error("warning unavailable");
+      }
+    });
+    const { installPackages } = await import("./dev.mjs");
+
+    await expect(
+      installPackages("/tmp/app", mockLogger),
+    ).resolves.toBeUndefined();
+
+    expect(execMock).toHaveBeenCalledTimes(1);
+    expect(mockLogger.error).not.toHaveBeenCalledWith(
+      "Error during package installation",
+      expect.anything(),
+    );
+  });
+
+  it("does not fail after disk recovery when success logging throws", async () => {
+    execMock.mockImplementation(
+      (
+        _cmd: string,
+        _opts: unknown,
+        cb?: (err: NodeJS.ErrnoException) => void,
+      ) => {
+        const error: NodeJS.ErrnoException = new Error(
+          "no space left on device",
+        );
+        error.code = "ENOSPC";
+        cb?.(error);
+      },
+    );
+    recoverFromDiskFullMock.mockResolvedValue({ recovered: true });
+    mockLogger.infoStructured.mockImplementationOnce(() => {
+      throw new Error("telemetry unavailable");
+    });
+    mockLogger.warn.mockImplementation((message: string) => {
+      if (message === "Could not emit package installation success telemetry") {
+        throw new Error("warning unavailable");
+      }
+    });
+    const { installPackages } = await import("./dev.mjs");
+
+    await expect(
+      installPackages("/tmp/app", mockLogger),
+    ).resolves.toBeUndefined();
+
+    expect(recoverFromDiskFullMock).toHaveBeenCalledTimes(1);
+    expect(mockLogger.error).not.toHaveBeenCalledWith(
+      "Error during package installation",
+      expect.anything(),
+    );
+  });
+});

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

@@ -0,0 +1,82 @@
+/**
+ * `npm install` already runs with `--json` so a failure can be classified from
+ * the structured error envelope. On the SUCCESS path that same JSON was passed
+ * straight to `logger.info(stdout)` as the log MESSAGE, which is why Datadog
+ * shows an empty line after "Package installation completed successfully" and
+ * the counts never reached anyone.
+ *
+ * Those counts are the only evidence of what an install actually did. Deciding
+ * whether to persist a node_modules delta, and whether the trade is worth it,
+ * needs to distinguish "added 8 packages" from "added nothing and still spent
+ * 52 seconds".
+ */
+
+export type NpmInstallSummary = {
+  added: number;
+  removed: number;
+  changed: number;
+  audited: number;
+};
+
+/**
+ * npm reports affected packages either as counts or as arrays of package
+ * objects, depending on version. Normalize both to a count and treat anything
+ * else as zero, so a shape change upstream degrades to an under-count rather
+ * than `NaN` in telemetry.
+ */
+function toCount(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    // Clamp: a negative count is meaningless and would skew any aggregation
+    // built on these attributes.
+    return Math.max(0, Math.trunc(value));
+  }
+  if (Array.isArray(value)) {
+    return value.length;
+  }
+  return 0;
+}
+
+/**
+ * Parse npm's `--json` install summary.
+ *
+ * Returns null when there is nothing parseable — no output, output that is
+ * not a JSON object, or a JSON object that carries none of npm's summary keys
+ * (the install may have run under yarn/pnpm, whose JSON output would otherwise
+ * masquerade as a confidently-measured no-op npm install). Callers should fall
+ * back to logging the raw text so an unrecognized shape is still recoverable
+ * from logs.
+ */
+export function parseNpmInstallSummary(
+  stdout: string,
+): NpmInstallSummary | null {
+  const trimmed = stdout.trim();
+  if (trimmed === "") {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const record = parsed as Record<string, unknown>;
+  const hasNpmSummaryKey = ["added", "removed", "changed", "audited"].some(
+    (key) => key in record,
+  );
+  if (!hasNpmSummaryKey) {
+    return null;
+  }
+
+  return {
+    added: toCount(record.added),
+    removed: toCount(record.removed),
+    changed: toCount(record.changed),
+    audited: toCount(record.audited),
+  };
+}

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;
+  }
+}