@superblocksteam/sdk 2.0.130-next.3 → 2.0.130-next.5

package/dist/telemetry/memory-metrics.test.js

@@ -0,0 +1,256 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+const h = vi.hoisted(() => {
+    const gauges = [];
+    const observableCounters = [];
+    const counters = [];
+    const histograms = [];
+    return {
+        gauges,
+        observableCounters,
+        counters,
+        histograms,
+        throwOnGaugeName: undefined,
+        delayMonitor: {
+            enable: vi.fn(),
+            disable: vi.fn(),
+            reset: vi.fn(),
+            mean: 2_000_000,
+            max: 80_000_000,
+            percentile: vi.fn((p) => p * 1_000_000),
+        },
+        gcCallback: undefined,
+        elu: vi.fn(),
+        addBatchObservableCallback: vi.fn((callback, callbackInstruments) => {
+            for (const instrument of callbackInstruments) {
+                const captured = [...gauges, ...observableCounters].find((g) => g.name === instrument.name);
+                if (captured)
+                    captured.callback = callback;
+            }
+        }),
+        removeBatchObservableCallback: vi.fn(),
+    };
+});
+vi.mock("node:perf_hooks", async () => {
+    const actual = await vi.importActual("node:perf_hooks");
+    return {
+        ...actual,
+        PerformanceObserver: class {
+            constructor(callback) {
+                h.gcCallback = callback;
+            }
+            observe = vi.fn();
+            disconnect = vi.fn();
+        },
+        monitorEventLoopDelay: vi.fn(() => h.delayMonitor),
+        performance: {
+            ...actual.performance,
+            eventLoopUtilization: h.elu,
+        },
+    };
+});
+vi.mock("./index.js", () => ({
+    getMeter: () => ({
+        createObservableGauge: (name) => {
+            if (h.throwOnGaugeName === name) {
+                throw new Error(`createObservableGauge failed for ${name}`);
+            }
+            const gauge = { name };
+            h.gauges.push(gauge);
+            return gauge;
+        },
+        createObservableCounter: (name) => {
+            const counter = { name };
+            h.observableCounters.push(counter);
+            return counter;
+        },
+        createCounter: (name) => {
+            const counter = { name, adds: [] };
+            h.counters.push(counter);
+            return {
+                add: (value, attrs) => counter.adds.push({ value, attrs }),
+            };
+        },
+        createHistogram: (name, options) => {
+            const histogram = { name, options, records: [] };
+            h.histograms.push(histogram);
+            return {
+                record: (value, attrs) => histogram.records.push({ value, attrs }),
+            };
+        },
+        addBatchObservableCallback: h.addBatchObservableCallback,
+        removeBatchObservableCallback: h.removeBatchObservableCallback,
+    }),
+}));
+function observeAll() {
+    const observations = [];
+    const callback = h.gauges.find((g) => g.callback)?.callback;
+    if (!callback)
+        throw new Error("missing observable callback");
+    callback({
+        observe: (gauge, value, attrs) => observations.push({ name: gauge.name, value, attrs }),
+    });
+    return observations;
+}
+describe("memory metrics", () => {
+    beforeEach(async () => {
+        vi.resetModules();
+        h.gauges.length = 0;
+        h.observableCounters.length = 0;
+        h.counters.length = 0;
+        h.histograms.length = 0;
+        h.throwOnGaugeName = undefined;
+        h.delayMonitor.enable.mockClear();
+        h.delayMonitor.disable.mockClear();
+        h.delayMonitor.reset.mockClear();
+        h.delayMonitor.percentile.mockClear();
+        h.gcCallback = undefined;
+        h.elu.mockReset();
+        h.elu
+            .mockReturnValueOnce({ idle: 0, active: 0, utilization: 0 })
+            .mockReturnValueOnce({ idle: 25, active: 75, utilization: 0.75 })
+            .mockReturnValue({ idle: 100, active: 200, utilization: 0.67 });
+        h.addBatchObservableCallback.mockClear();
+        h.removeBatchObservableCallback.mockClear();
+    });
+    it("observes event-loop, V8 heap, and memory-pressure gauges", async () => {
+        const { startMemoryMetrics, stopMemoryMetrics } = await import("./memory-metrics.js");
+        startMemoryMetrics();
+        const observations = observeAll();
+        stopMemoryMetrics();
+        expect(h.delayMonitor.enable).toHaveBeenCalledOnce();
+        expect(observations.map((o) => o.name)).toEqual(expect.arrayContaining([
+            "nodejs.event_loop.delay.max_ms",
+            "nodejs.event_loop.delay.p99_ms",
+            "nodejs.event_loop.utilization",
+            "nodejs.memory.heap_limit_bytes",
+            "nodejs.memory.heap_used_ratio",
+        ]));
+        expect(h.observableCounters.map((counter) => counter.name)).toEqual([
+            "nodejs.process.cpu.user_seconds",
+            "nodejs.process.cpu.system_seconds",
+        ]);
+        expect(observations.find((o) => o.name === "nodejs.event_loop.delay.max_ms")
+            ?.value).toBe(80);
+        expect(observations.find((o) => o.name === "nodejs.event_loop.utilization")
+            ?.value).toBe(0.75);
+        expect(h.delayMonitor.reset).toHaveBeenCalledOnce();
+        expect(h.delayMonitor.disable).toHaveBeenCalledOnce();
+    });
+    it("cleans up the event-loop delay monitor when setup fails", async () => {
+        const { startMemoryMetrics, stopMemoryMetrics } = await import("./memory-metrics.js");
+        h.throwOnGaugeName = "nodejs.memory.rss_bytes";
+        expect(() => startMemoryMetrics()).toThrow("createObservableGauge failed for nodejs.memory.rss_bytes");
+        expect(h.delayMonitor.disable).toHaveBeenCalledOnce();
+        h.throwOnGaugeName = undefined;
+        startMemoryMetrics();
+        stopMemoryMetrics();
+        expect(h.delayMonitor.enable).toHaveBeenCalledOnce();
+        expect(h.delayMonitor.disable).toHaveBeenCalledTimes(2);
+    });
+    it("resets event-loop delay even when observation fails", async () => {
+        const { startMemoryMetrics, stopMemoryMetrics } = await import("./memory-metrics.js");
+        startMemoryMetrics();
+        const callback = h.gauges.find((g) => g.callback)?.callback;
+        if (!callback)
+            throw new Error("missing observable callback");
+        expect(() => callback({
+            observe: (instrument) => {
+                if (instrument.name === "nodejs.memory.rss_bytes") {
+                    throw new Error("observe failed");
+                }
+            },
+        })).toThrow("observe failed");
+        stopMemoryMetrics();
+        expect(h.delayMonitor.reset).toHaveBeenCalledOnce();
+    });
+    it("does not register metrics twice until stopped", async () => {
+        const { startMemoryMetrics, stopMemoryMetrics } = await import("./memory-metrics.js");
+        startMemoryMetrics();
+        startMemoryMetrics();
+        stopMemoryMetrics();
+        startMemoryMetrics();
+        stopMemoryMetrics();
+        expect(h.delayMonitor.enable).toHaveBeenCalledTimes(2);
+        expect(h.addBatchObservableCallback).toHaveBeenCalledTimes(2);
+        expect(h.removeBatchObservableCallback).toHaveBeenCalledTimes(2);
+    });
+    it("records GC count and duration with bounded kind labels", async () => {
+        const { startMemoryMetrics, stopMemoryMetrics } = await import("./memory-metrics.js");
+        startMemoryMetrics();
+        h.gcCallback?.({
+            getEntries: () => [
+                { detail: { kind: 1 }, duration: 12 },
+                { detail: { kind: 4 }, duration: 34 },
+                { kind: 999, duration: 56 },
+            ],
+        });
+        stopMemoryMetrics();
+        const gcCounter = h.counters.find((c) => c.name === "nodejs.gc.count");
+        const gcDuration = h.histograms.find((histogram) => histogram.name === "nodejs.gc.duration_ms");
+        expect(gcCounter?.adds.map((a) => a.attrs)).toEqual([
+            { kind: "minor" },
+            { kind: "major" },
+            { kind: "unknown" },
+        ]);
+        expect(gcDuration?.records).toEqual([
+            { value: 12, attrs: { kind: "minor" } },
+            { value: 34, attrs: { kind: "major" } },
+            { value: 56, attrs: { kind: "unknown" } },
+        ]);
+        expect(gcDuration?.options).toEqual({
+            description: "Garbage collection duration by collection kind",
+            unit: "ms",
+            advice: {
+                explicitBucketBoundaries: [0.5, 1, 2, 5, 10, 25, 50, 100, 250, 500],
+            },
+        });
+    });
+});
+describe("readCgroupMemory", () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+    it("reads cgroup v2 memory usage and ratio", async () => {
+        const root = mkdtempSync(path.join(tmpdir(), "sb-cgroup-"));
+        writeFileSync(path.join(root, "memory.current"), "50\n");
+        writeFileSync(path.join(root, "memory.max"), "200\n");
+        const { readCgroupMemory } = await import("./memory-metrics.js");
+        expect(readCgroupMemory(root)).toEqual({
+            currentBytes: 50,
+            limitBytes: 200,
+            usageRatio: 0.25,
+        });
+    });
+    it("returns undefined when cgroup files are absent or unlimited", async () => {
+        const root = mkdtempSync(path.join(tmpdir(), "sb-cgroup-"));
+        const { readCgroupMemory } = await import("./memory-metrics.js");
+        expect(readCgroupMemory(root)).toBeUndefined();
+        writeFileSync(path.join(root, "memory.current"), "50\n");
+        writeFileSync(path.join(root, "memory.max"), "max\n");
+        expect(readCgroupMemory(root)).toBeUndefined();
+    });
+    it("does not combine v2 usage with v1 limits", async () => {
+        const root = mkdtempSync(path.join(tmpdir(), "sb-cgroup-"));
+        const memoryRoot = path.join(root, "memory");
+        mkdirSync(memoryRoot);
+        writeFileSync(path.join(root, "memory.current"), "50\n");
+        writeFileSync(path.join(root, "memory.max"), "max\n");
+        writeFileSync(path.join(memoryRoot, "memory.usage_in_bytes"), "60\n");
+        writeFileSync(path.join(memoryRoot, "memory.limit_in_bytes"), "200\n");
+        const { readCgroupMemory } = await import("./memory-metrics.js");
+        expect(readCgroupMemory(root)).toBeUndefined();
+    });
+    it("treats cgroup v1 sentinel limits as unlimited", async () => {
+        const root = mkdtempSync(path.join(tmpdir(), "sb-cgroup-"));
+        const memoryRoot = path.join(root, "memory");
+        mkdirSync(memoryRoot);
+        writeFileSync(path.join(memoryRoot, "memory.usage_in_bytes"), "50\n");
+        writeFileSync(path.join(memoryRoot, "memory.limit_in_bytes"), "9223372036854771712\n");
+        const { readCgroupMemory } = await import("./memory-metrics.js");
+        expect(readCgroupMemory(root)).toBeUndefined();
+    });
+});
+//# sourceMappingURL=memory-metrics.test.js.map

package/dist/telemetry/memory-metrics.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-metrics.test.js","sourceRoot":"","sources":["../../src/telemetry/memory-metrics.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk",
-  "version": "2.0.130-next.3",
+  "version": "2.0.130-next.5",
   "description": "Superblocks JS SDK",
   "homepage": "https://www.superblocks.com",
   "license": "Superblocks Community Software License",
@@ -48,11 +48,11 @@
     "vite-tsconfig-paths": "^6.0.4",
     "winston": "^3.17.0",
     "yaml": "^2.7.1",
-    "@superblocksteam/library-shared": "2.0.130-next.3",
-    "@superblocksteam/shared": "0.9591.3",
-    "@superblocksteam/telemetry": "2.0.130-next.3",
-    "@superblocksteam/util": "2.0.130-next.3",
-    "@superblocksteam/vite-plugin-file-sync": "2.0.130-next.3"
+    "@superblocksteam/shared": "0.9592.1",
+    "@superblocksteam/library-shared": "2.0.130-next.5",
+    "@superblocksteam/telemetry": "2.0.130-next.5",
+    "@superblocksteam/util": "2.0.130-next.5",
+    "@superblocksteam/vite-plugin-file-sync": "2.0.130-next.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/src/cli-replacement/dependency-install-classifier.mts

@@ -9,6 +9,8 @@ import {
   type ParseContext,
 } from "@superblocksteam/vite-plugin-file-sync/npm-registry";
 
+import { isDiskFullError } from "./disk-space.mjs";
+
 /** Marker thrown by the INITIAL verification install so the dev.mts catch can
  *  degrade by ORIGIN (never on classifiability). Carries the classified error. */
 export class InitialInstallFailed extends Error {
@@ -90,6 +92,18 @@ export function classifyInitialInstallError(
   if (blockedFromJson) return fromBlocked(blockedFromJson, rawError);
 
   const combined = `${stdout}\n${stderr}`;
+
+  if (isDiskFullError({ stdout, stderr, message: failure.message })) {
+    return {
+      type: "dev-server/dependency-install",
+      timestamp: new Date().toISOString(),
+      category: "disk_full",
+      npmErrorCode: "ENOSPC",
+      hasAnyRegistryConfigured: ctx.hasAnyRegistryConfigured,
+      rawError,
+    };
+  }
+
   const codeMatch = combined.match(DEP_CONFLICT_CODES);
   if (codeMatch) {
     return {

package/src/cli-replacement/dependency-install-classifier.test.mts

@@ -47,6 +47,45 @@ describe("classifyInitialInstallError", () => {
     expect(e.registryHost).toBe("reg.corp");
   });
 
+  it("classifies an ENOSPC --json envelope as disk_full", () => {
+    const ENOSPC_JSON = JSON.stringify({
+      error: {
+        code: "ENOSPC",
+        summary: "ENOSPC: no space left on device, write",
+        detail: "nospc ENOSPC: no space left on device, write",
+      },
+    });
+    const e = classifyInitialInstallError(
+      { stdout: ENOSPC_JSON, stderr: "npm error code ENOSPC", message: "x" },
+      { hasAnyRegistryConfigured: true, requestedPackages: [] },
+    );
+    expect(e.category).toBe("disk_full");
+    expect(e.npmErrorCode).toBe("ENOSPC");
+  });
+
+  it("classifies a bare 'no space left on device' stderr as disk_full", () => {
+    const e = classifyInitialInstallError(
+      {
+        stdout: "not json",
+        stderr:
+          "npm error code ENOSPC\nnpm error syscall write\nnpm error errno -28\nnpm error nospc ENOSPC: no space left on device, write",
+        message: "Command failed",
+      },
+      {},
+    );
+    expect(e.category).toBe("disk_full");
+    expect(e.npmErrorCode).toBe("ENOSPC");
+  });
+
+  it("classifies a bare 'errno -28' (no ENOSPC code name) as disk_full", () => {
+    const e = classifyInitialInstallError(
+      { stdout: "", stderr: "npm error errno -28", message: "Command failed" },
+      {},
+    );
+    expect(e.category).toBe("disk_full");
+    expect(e.npmErrorCode).toBe("ENOSPC");
+  });
+
   it("falls back to unknown for an unmapped code (still a DependencyInstallError)", () => {
     const e = classifyInitialInstallError(
       {

package/src/cli-replacement/dev-s3-restore.test.mts

@@ -115,6 +115,7 @@ vi.mock("@superblocksteam/util", () => ({
 vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
   AiService: class {
     initialize = vi.fn(async () => undefined);
+    notifyMigrationAppArtifactsReady = vi.fn();
     removeIntegrationCache = vi.fn(async () => undefined);
     chatSessionStore = { invalidateCache: vi.fn() };
     // `dev.mts` reads this at startup for two paths: `syncHomeNpmrc`

package/src/cli-replacement/dev-startup-git-before-dbfs-order.test.mts

@@ -115,6 +115,7 @@ vi.mock("@superblocksteam/util", () => ({
 vi.mock("@superblocksteam/vite-plugin-file-sync/ai-service", () => ({
   AiService: class {
     initialize = vi.fn(async () => undefined);
+    notifyMigrationAppArtifactsReady = vi.fn();
     removeIntegrationCache = vi.fn(async () => undefined);
     chatSessionStore = { invalidateCache: vi.fn() };
     getNpmRegistryClient = vi.fn(() => undefined);

package/src/cli-replacement/dev.mts

@@ -70,6 +70,7 @@ import {
   classifyInitialInstallError,
   InitialInstallFailed,
 } from "./dependency-install-classifier.mjs";
+import { getDiskSpace, recoverFromDiskFull } from "./disk-space.mjs";
 import {
   ensureRemoteHasDefaultBranch,
   getGitErrorFields,
@@ -342,6 +343,12 @@ export async function installPackages(
   logger: Logger,
   npmRegistryClient?: NpmRegistryClient,
 ) {
+  // Hoisted so the catch's ENOSPC recovery can re-run the EXACT same install
+  // (same agent, args, env, --ignore-scripts policy) after reclaiming disk
+  // space, rather than reconstructing — and risking diverging from — it.
+  let runInstall:
+    | (() => Promise<{ stdout: string; stderr: string }>)
+    | undefined;
   try {
     const pm = await detect({
       strategies: [
@@ -445,25 +452,89 @@ export async function installPackages(
     // (`category: "unknown"`, `npmErrorCode: undefined` from real npm against a
     // missing `/tmp/app`).
     const exec = promisify(child_process.exec);
-    const { stdout } = await exec(`${command} ${args.join(" ")}`, {
-      cwd,
-      env: buildInstallEnv(superblocksNpmrcPath(), logsDir),
-    });
+    // Re-runnable so the ENOSPC recovery path below can retry the EXACT same
+    // install after reclaiming disk space.
+    runInstall = () =>
+      exec(`${command} ${args.join(" ")}`, {
+        cwd,
+        env: buildInstallEnv(superblocksNpmrcPath(), logsDir),
+      });
+
+    // Cheap `df` snapshot before the install (statfs only — no directory walk
+    // on the happy path). On a 3Gi live-edit PVC this is the baseline that
+    // makes an ENOSPC mid-install interpretable after the fact.
+    const diskBefore = await getDiskSpace(cwd);
+    if (diskBefore) {
+      logger.info(
+        `Disk usage before package install [freeBytes=${diskBefore.freeBytes} totalBytes=${diskBefore.totalBytes} percentUsed=${diskBefore.percentUsed}] cwd=${cwd}`,
+        { disk: diskBefore },
+      );
+    } else {
+      logger.warn(
+        `Could not read disk usage before package install (statfs failed) cwd=${cwd}`,
+      );
+    }
+
+    const { stdout } = await runInstall();
     logger.info("Package installation completed successfully");
     logger.info(stdout);
   } catch (error) {
-    logger.error("Error during package installation", getErrorMeta(error));
     // `util.promisify(child_process.exec)` preserves `.stdout`/`.stderr` on
     // the rejected error separately; with `--json`, the structured npm error
     // envelope lands on `.stdout`. Classify it into a DependencyInstallError
     // and throw the `InitialInstallFailed` marker so the `dev()` catch can
     // degrade by origin rather than crash-looping the dev-server pod.
     const ctx = await buildInstallParseContext(cwd, npmRegistryClient);
-    const f = error as { stdout?: string; stderr?: string; message?: string };
-    const serverError = classifyInitialInstallError(
-      { stdout: f.stdout, stderr: f.stderr, message: f.message },
-      ctx,
-    );
+    const toFailure = (e: unknown) => {
+      const f = e as { stdout?: string; stderr?: string; message?: string };
+      return { stdout: f.stdout, stderr: f.stderr, message: f.message };
+    };
+    let serverError = classifyInitialInstallError(toFailure(error), ctx);
+    // The error whose meta we log on the way out — kept in lockstep with the
+    // (possibly reclassified) `serverError` we throw, so operational logs and
+    // the user-visible error never disagree.
+    let errorToLog: unknown = error;
+
+    // ENOSPC: the live-edit volume filled up mid-install. Try to recover by
+    // reclaiming regenerable build artifacts (and, if that's not enough, the
+    // half-written node_modules) and retrying the install before giving up.
+    // The recovery logs each tier's df + freed bytes, which doubles as the
+    // only autopsy we can get of a PVC that `reclaimPolicy: Delete` destroys
+    // at teardown. `runInstall` is only set once the command was resolved; if
+    // the failure happened before that, there's nothing to retry.
+    if (serverError.category === "disk_full" && runInstall) {
+      let recovery: Awaited<ReturnType<typeof recoverFromDiskFull>> | undefined;
+      try {
+        recovery = await recoverFromDiskFull(cwd, runInstall, logger);
+      } catch (recoveryErr) {
+        // Recovery is best-effort; an unexpected throw must never escape as a
+        // raw error (that would bypass the InitialInstallFailed contract the
+        // dev() catch relies on). Swallow it and surface the original failure.
+        logger.warn("Disk recovery threw unexpectedly", {
+          error: String(recoveryErr),
+        });
+      }
+      if (recovery) {
+        devServerMetrics.recordDiskRecovery({ recovered: recovery.recovered });
+        if (recovery.recovered) {
+          logger.info(
+            "Package installation completed successfully after disk recovery",
+          );
+          return;
+        }
+        // Reclassify the final attempt so the surfaced error reflects the last
+        // npm output (still disk_full if genuinely out of space).
+        if (recovery.lastError !== undefined) {
+          errorToLog = recovery.lastError;
+          serverError = classifyInitialInstallError(
+            toFailure(recovery.lastError),
+            ctx,
+          );
+        }
+      }
+    }
+
+    logger.error("Error during package installation", getErrorMeta(errorToLog));
     throw new InitialInstallFailed(serverError);
   }
 }
@@ -968,6 +1039,7 @@ export async function dev(options: {
               logger,
               tokenManager,
               features: AiServiceFeatureFlags.create(flagBootstrap),
+              flagBootstrap,
               pluginExecutionVersions:
                 currentUser.organizations[0].pluginExecutionVersions,
             });
@@ -983,6 +1055,10 @@ export async function dev(options: {
               },
             );
 
+            if (uploadFirst) {
+              aiService?.notifyMigrationAppArtifactsReady();
+            }
+
             logger.info(
               `[dev-startup] Starting git sync (${downloadFirst ? "download" : "upload"}-first) on branch '${activeDbfsBranchName}'`,
             );
@@ -1174,6 +1250,10 @@ export async function dev(options: {
               logger.info("[dev-startup] Skipping download, already in sync");
             }
 
+            if (downloadFirst) {
+              aiService?.notifyMigrationAppArtifactsReady();
+            }
+
             // Unconditional lockfile sanitation (APPS-4300): strip
             // cross-registry `resolved` URLs from any lockfile on disk
             // regardless of whether install runs next. The lockfile here is