@superblocksteam/sdk 2.0.146 → 2.0.147

package/package.json

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

package/src/dev-utils/dev-server-metrics.mts

@@ -504,6 +504,25 @@ class DevServerMetrics {
     });
   }
 
+  /**
+   * Records a Vite/esbuild build error suppressed instead of exiting. This is
+   * the alertable replacement for the `dev_server_fatal_exit` log token when
+   * optimizeDeps or transform failures would previously crash the pod.
+   */
+  recordRecoverableBuildError(labels: {
+    category: string;
+    handler: RecoverableShutdownHandler;
+  }): void {
+    this.record(() => {
+      getMeter()
+        .createCounter("dev_server_recoverable_build_error_total", {
+          description:
+            "Count of Vite/esbuild build errors suppressed instead of exiting, by category and handler.",
+        })
+        .add(1, labels);
+    });
+  }
+
   /**
    * Records an ENOSPC disk-recovery attempt and its outcome. Lets dashboards
    * and alerts answer "how often is the live-edit PVC filling up, and is

package/src/dev-utils/dev-server.mts

@@ -76,6 +76,7 @@ import {
 } from "./fatal-exit.mjs";
 import { OPTIMIZE_DEPS_CONFIG } from "./optimize-deps-config.mjs";
 import { prepareInPlaceRestart } from "./prepare-in-place-restart.mjs";
+import { handleRecoverableBuildError } from "./recoverable-build-error.mjs";
 import {
   formatViteDevServerStartedLog,
   logViteBuildError,
@@ -521,6 +522,73 @@ export function buildStatusPayload<T extends object>(
   return { ...base, serverErrors: devServerStatus?.serverErrors ?? [] };
 }
 
+type ProcessErrorHandler = "uncaughtException" | "unhandledRejection";
+
+// Both listeners log a recoverable shutdown, but with different wording, and
+// these lines are what on-call greps when a pod stays up instead of restarting.
+// Keeping the two strings side by side makes that difference deliberate.
+const RECOVERABLE_SHUTDOWN_LOG_MESSAGE: Record<ProcessErrorHandler, string> = {
+  uncaughtException: "Ignoring recoverable shutdown error (uncaughtException)",
+  unhandledRejection:
+    "Ignoring recoverable shutdown rejection (unhandledRejection)",
+};
+
+/**
+ * Decides whether a process-level error keeps the pod alive, and performs the
+ * recording for the cases that do. Returns `true` when the caller must return
+ * early without taking the fatal-exit path.
+ *
+ * Extracted from the `uncaughtException` / `unhandledRejection` listeners so
+ * this decision is testable: registered listeners are effectively unreachable
+ * from unit tests, so an early `return` could be deleted with the whole suite
+ * staying green while the pod died on every recoverable build error.
+ */
+export function handleNonFatalProcessError(params: {
+  devServerStatus?: { serverErrors: ServerError[] };
+  devServerMetrics: {
+    recordRecoverableBuildError: (labels: {
+      category: string;
+      handler: ProcessErrorHandler;
+    }) => void;
+    recordRecoverableShutdownError: (
+      handler: ProcessErrorHandler,
+      reason: unknown,
+    ) => void;
+  };
+  handler: ProcessErrorHandler;
+  logger: { warn: (message: string, meta?: unknown) => void };
+  reason: unknown;
+}): boolean {
+  // A connection or server we depend on closing mid-flight (socket code 8/10,
+  // or Vite's ERR_CLOSED_SERVER from a call racing an in-place restart) is
+  // expected and recoverable, so it must not kill the pod. See
+  // isRecoverableShutdownError for the shapes and why their owning paths
+  // already treat them as non-fatal.
+  if (isRecoverableShutdownError(params.reason)) {
+    params.logger.warn(
+      RECOVERABLE_SHUTDOWN_LOG_MESSAGE[params.handler],
+      getErrorMeta(params.reason),
+    );
+    // Keep an alertable signal. Suppressing the fatal exit drops the
+    // dev_server_fatal_exit log token, so this counter is the only
+    // dashboard-queryable way to see these (and catch a regression in their
+    // rate) without a log search.
+    params.devServerMetrics.recordRecoverableShutdownError(
+      params.handler,
+      params.reason,
+    );
+    return true;
+  }
+
+  return handleRecoverableBuildError({
+    devServerStatus: params.devServerStatus,
+    devServerMetrics: params.devServerMetrics,
+    handler: params.handler,
+    logger: params.logger,
+    reason: params.reason,
+  });
+}
+
 /**
  * Stable per-process identity for the dev-server runtime. `bootId` is generated
  * once at module load, so it changes on every process start (including an
@@ -1232,24 +1300,15 @@ export async function createDevServer({
     if (fatalExitHandled) {
       return;
     }
-    // A connection or server we depend on closing mid-flight (socket code 8/10,
-    // or Vite's ERR_CLOSED_SERVER from a call racing an in-place restart) is
-    // expected and recoverable, so it must not kill the pod. See
-    // isRecoverableShutdownError for the shapes and why their owning paths
-    // already treat them as non-fatal.
-    if (isRecoverableShutdownError(error)) {
-      logger.warn(
-        "Ignoring recoverable shutdown error (uncaughtException)",
-        getErrorMeta(error),
-      );
-      // Keep an alertable signal. Suppressing the fatal exit drops the
-      // dev_server_fatal_exit log token, so this counter is the only
-      // dashboard-queryable way to see these (and catch a regression in their
-      // rate) without a log search.
-      devServerMetrics.recordRecoverableShutdownError(
-        "uncaughtException",
-        error,
-      );
+    if (
+      handleNonFatalProcessError({
+        devServerStatus,
+        devServerMetrics,
+        handler: "uncaughtException",
+        logger,
+        reason: error,
+      })
+    ) {
       return;
     }
     fatalExitHandled = true;
@@ -1286,20 +1345,15 @@ export async function createDevServer({
     if (fatalExitHandled) {
       return;
     }
-    // See the uncaughtException handler above: a connection/server close racing
-    // an in-place restart (socket code 8/10 or Vite's ERR_CLOSED_SERVER) is
-    // recoverable and must not wedge the pod (APPS-4797).
-    if (isRecoverableShutdownError(reason)) {
-      logger.warn(
-        "Ignoring recoverable shutdown rejection (unhandledRejection)",
-        getErrorMeta(reason),
-      );
-      // Alertable signal in place of the suppressed dev_server_fatal_exit log
-      // token; see the uncaughtException handler above.
-      devServerMetrics.recordRecoverableShutdownError(
-        "unhandledRejection",
+    if (
+      handleNonFatalProcessError({
+        devServerStatus,
+        devServerMetrics,
+        handler: "unhandledRejection",
+        logger,
         reason,
-      );
+      })
+    ) {
       return;
     }
     fatalExitHandled = true;

package/src/dev-utils/dev-server.process-errors.test.mts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ServerError } from "@superblocksteam/library-shared/types";
+
+import { handleNonFatalProcessError } from "./dev-server.mjs";
+
+/**
+ * The `uncaughtException` / `unhandledRejection` listeners decide whether an
+ * error keeps the pod alive or takes it through the fatal-exit path. That
+ * decision is what these tests pin: without it, deleting an early `return` in
+ * either listener leaves the whole suite green while the pod dies on every
+ * recoverable build error — the exact regression this PR exists to prevent.
+ */
+describe("handleNonFatalProcessError", () => {
+  const makeParams = (
+    reason: unknown,
+    handler: "uncaughtException" | "unhandledRejection" = "unhandledRejection",
+  ) => {
+    const logger = { warn: vi.fn(), error: vi.fn() };
+    const devServerStatus = { serverErrors: [] as ServerError[] };
+    const devServerMetrics = {
+      recordRecoverableBuildError: vi.fn(),
+      recordRecoverableShutdownError: vi.fn(),
+    };
+    return { devServerMetrics, devServerStatus, handler, logger, reason };
+  };
+
+  it("keeps the pod alive for a Vite build error and records it for the editor", () => {
+    const params = makeParams({
+      errors: [{ text: 'Could not resolve "buffer/"' }],
+    });
+
+    expect(handleNonFatalProcessError(params)).toBe(true);
+    // Recorded so `/_sb_connect` can hand it to the editor overlay.
+    expect(params.devServerStatus.serverErrors).toHaveLength(1);
+    expect(
+      params.devServerMetrics.recordRecoverableBuildError,
+    ).toHaveBeenCalledWith({
+      category: "module_resolve",
+      handler: "unhandledRejection",
+    });
+  });
+
+  it("keeps the pod alive for a close racing an in-place restart", () => {
+    for (const code of [8, 10, "ERR_CLOSED_SERVER"]) {
+      const params = makeParams(Object.assign(new Error("closed"), { code }));
+      expect(handleNonFatalProcessError(params)).toBe(true);
+      expect(
+        params.devServerMetrics.recordRecoverableShutdownError,
+      ).toHaveBeenCalled();
+    }
+  });
+
+  it("preserves the distinct log wording each handler uses", () => {
+    // These lines are what on-call greps when a pod stays up instead of
+    // restarting, so the wording is part of the contract.
+    const onException = makeParams(
+      Object.assign(new Error("closed"), { code: 8 }),
+      "uncaughtException",
+    );
+    handleNonFatalProcessError(onException);
+    expect(onException.logger.warn).toHaveBeenCalledWith(
+      "Ignoring recoverable shutdown error (uncaughtException)",
+      expect.anything(),
+    );
+
+    const onRejection = makeParams(
+      Object.assign(new Error("closed"), { code: 8 }),
+      "unhandledRejection",
+    );
+    handleNonFatalProcessError(onRejection);
+    expect(onRejection.logger.warn).toHaveBeenCalledWith(
+      "Ignoring recoverable shutdown rejection (unhandledRejection)",
+      expect.anything(),
+    );
+  });
+
+  it("sends a genuine crash to the fatal path", () => {
+    const params = makeParams(new TypeError("cannot read properties of null"));
+
+    expect(handleNonFatalProcessError(params)).toBe(false);
+    expect(params.devServerStatus.serverErrors).toHaveLength(0);
+    expect(
+      params.devServerMetrics.recordRecoverableBuildError,
+    ).not.toHaveBeenCalled();
+    expect(
+      params.devServerMetrics.recordRecoverableShutdownError,
+    ).not.toHaveBeenCalled();
+  });
+
+  it("sends a malformed build-ish reason to the fatal path rather than throwing", () => {
+    // `isViteBuildError` accepts this on the message marker without
+    // re-validating `errors`. A throw here would run inside the listener before
+    // the fatal-exit line is written, killing the pod with no record of the real
+    // error, so the safe direction is a clean `false`.
+    const params = makeParams({
+      errors: [{ text: 42 }],
+      message: "Transform failed with 1 error",
+    });
+
+    expect(() => handleNonFatalProcessError(params)).not.toThrow();
+  });
+});

package/src/dev-utils/fatal-exit.mts

@@ -162,3 +162,131 @@ export function isRecoverableShutdownError(reason: unknown): boolean {
   }
   return RECOVERABLE_SHUTDOWN_CODES.has(code);
 }
+
+// Every alternative here has to be specific to Vite/esbuild output. A false
+// positive marks a genuine crash recoverable, which keeps a broken pod alive
+// and suppresses the `dev_server_fatal_exit` signal we alert on. That is why
+// `Could not resolve` requires esbuild's quoted specifier
+// (`Could not resolve "buffer/"`): the bare phrase also appears in package
+// manager output ("Could not resolve dependency:") and DNS failures
+// ("could not resolve host").
+const VITE_BUILD_MESSAGE_MARKERS =
+  /Could not resolve ["']|Build failed with \d+ error|Pre-transform error|Failed to resolve import|Transform failed/i;
+
+/**
+ * An esbuild `BuildFailure` carries `errors: Message[]`, where each `Message`
+ * has a `text` string. Requiring that inner shape keeps the check specific:
+ * a bare `errors` array is far too common to treat as proof of a build failure.
+ */
+function hasEsbuildBuildFailureShape(reason: object): boolean {
+  const errors = (reason as { errors?: unknown }).errors;
+  return (
+    Array.isArray(errors) &&
+    errors.length > 0 &&
+    errors.every(
+      (entry) =>
+        typeof entry === "object" &&
+        entry !== null &&
+        typeof (entry as { text?: unknown }).text === "string",
+    )
+  );
+}
+
+/**
+ * Vite/esbuild build failures that should keep the dev-server process alive and
+ * surface through `devServerStatus.serverErrors` instead of `process.exit(1)`.
+ *
+ * Deliberately narrow: anything not positively identified as a build failure
+ * must stay fatal, so genuine crashes still exit and emit
+ * `dev_server_fatal_exit`. Rollup/Vite plugin errors are matched by their
+ * message rather than by structural fields like `id`/`plugin`/`loc`, which are
+ * far too common to be evidence of a build failure on their own.
+ */
+export function isViteBuildError(reason: unknown): boolean {
+  if (typeof reason !== "object" || reason === null) {
+    if (typeof reason === "string") {
+      return VITE_BUILD_MESSAGE_MARKERS.test(reason);
+    }
+    return false;
+  }
+
+  if (hasEsbuildBuildFailureShape(reason)) {
+    return true;
+  }
+
+  const message =
+    reason instanceof Error
+      ? reason.message
+      : typeof (reason as { message?: unknown }).message === "string"
+        ? (reason as { message: string }).message
+        : undefined;
+
+  if (message && VITE_BUILD_MESSAGE_MARKERS.test(message)) {
+    return true;
+  }
+
+  return false;
+}
+
+/** Pull usable esbuild `Message.text` strings off any object-shaped reason. */
+function extractEsbuildErrorTexts(reason: unknown): string[] {
+  if (typeof reason !== "object" || reason === null) {
+    return [];
+  }
+
+  const errors = (reason as { errors?: unknown }).errors;
+  if (!Array.isArray(errors)) {
+    return [];
+  }
+
+  // Read defensively. `isViteBuildError` can classify on a message marker alone
+  // without re-validating the array, so entries here may be anything. This
+  // function runs inside the `uncaughtException` / `unhandledRejection`
+  // listeners before the fatal-exit line is written, and a throw there tears the
+  // process down immediately.
+  return errors
+    .map((entry) =>
+      typeof entry === "object" &&
+      entry !== null &&
+      typeof (entry as { text?: unknown }).text === "string"
+        ? (entry as { text: string }).text.trim()
+        : "",
+    )
+    .filter((text) => text.length > 0);
+}
+
+/** Best-effort text extraction for Vite/esbuild rejection reasons. */
+export function extractViteBuildErrorMessage(reason: unknown): string {
+  if (typeof reason === "string") {
+    return reason;
+  }
+
+  // Real optimizeDeps rejections are esbuild `BuildFailure` values — Error
+  // subclasses with `errors: Message[]`. Prefer those structured texts over the
+  // stack so the overlay and Clark see `Could not resolve "buffer/"`, not a
+  // noisy stack trace.
+  const esbuildTexts = extractEsbuildErrorTexts(reason);
+  if (esbuildTexts.length > 0) {
+    return esbuildTexts.join("\n");
+  }
+
+  if (reason instanceof Error) {
+    return reason.stack ?? reason.message;
+  }
+
+  if (typeof reason === "object" && reason !== null) {
+    const candidate = reason as { message?: unknown };
+
+    if (typeof candidate.message === "string" && candidate.message.trim()) {
+      return candidate.message;
+    }
+
+    try {
+      return JSON.stringify(reason);
+    } catch {
+      return String(reason);
+    }
+  }
+
+  return String(reason);
+}

package/src/dev-utils/fatal-exit.test.mts

@@ -3,7 +3,9 @@ import { describe, expect, it } from "vitest";
 import {
   buildFatalExitLog,
   FATAL_EXIT_EVENT,
+  extractViteBuildErrorMessage,
   isRecoverableShutdownError,
+  isViteBuildError,
   parseIsWarm,
 } from "./fatal-exit.mjs";
 
@@ -127,3 +129,203 @@ describe("isRecoverableShutdownError", () => {
     expect(isRecoverableShutdownError({ code: "ERR_OTHER" })).toBe(false);
   });
 });
+
+describe("isViteBuildError", () => {
+  it("matches esbuild BuildFailure shapes", () => {
+    expect(
+      isViteBuildError({
+        errors: [
+          {
+            text: 'Could not resolve "buffer/"',
+          },
+        ],
+        warnings: [],
+      }),
+    ).toBe(true);
+  });
+
+  it("matches Rollup/Vite plugin errors via their message", () => {
+    expect(
+      isViteBuildError(
+        Object.assign(
+          new Error('Failed to resolve import "buffer/" from "helpers.js"'),
+          {
+            frame: "5: import buffer from 'buffer/'",
+            id: "/app/node_modules/plotly.js/src/traces/image/helpers.js",
+            loc: { column: 0, file: "helpers.js", line: 5 },
+            plugin: "vite:import-analysis",
+          },
+        ),
+      ),
+    ).toBe(true);
+  });
+
+  it("does not match non-build rejections that merely carry Rollup-ish fields", () => {
+    // `id` is ubiquitous in this process (RuntimeErrorData, ConsoleLogEntry,
+    // socket payloads), and `typeof null === "object"` makes a bare `loc` check
+    // match too. Structural fields alone must never mark a rejection
+    // recoverable: that would swallow genuine crashes and suppress the
+    // dev_server_fatal_exit signal we alert on.
+    expect(isViteBuildError({ id: "abc123", message: "boom" })).toBe(false);
+    expect(isViteBuildError({ loc: null })).toBe(false);
+    expect(isViteBuildError({ plugin: "some-plugin" })).toBe(false);
+    expect(isViteBuildError({ frame: "..." })).toBe(false);
+  });
+
+  it("ignores esbuild-ish objects whose errors array is not esbuild messages", () => {
+    expect(isViteBuildError({ errors: [] })).toBe(false);
+    expect(isViteBuildError({ errors: ["nope"] })).toBe(false);
+  });
+
+  it("keeps AggregateError fatal even though it carries an errors array", () => {
+    // The only thing separating an AggregateError from an esbuild BuildFailure
+    // is the `typeof entry.text === "string"` requirement. Without this test,
+    // simplifying that shape check would silently reclassify every
+    // `Promise.any` rejection and undici `AggregateError [ECONNREFUSED]` as a
+    // recoverable build error — keeping a genuinely broken pod alive and
+    // dropping it out of the fatal-exit population we alert on.
+    expect(
+      isViteBuildError(
+        new AggregateError(
+          [
+            new Error("connect ECONNREFUSED"),
+            new Error("connect ECONNREFUSED"),
+          ],
+          "All promises were rejected",
+        ),
+      ),
+    ).toBe(false);
+    expect(
+      isViteBuildError({
+        errors: [new Error("connect ECONNREFUSED 127.0.0.1:5432")],
+      }),
+    ).toBe(false);
+  });
+
+  it("matches known Vite/esbuild message markers", () => {
+    expect(
+      isViteBuildError(
+        'Build failed with 1 error:\nCould not resolve "buffer/"',
+      ),
+    ).toBe(true);
+    expect(
+      isViteBuildError("Pre-transform error: Failed to resolve import"),
+    ).toBe(true);
+  });
+
+  it("does not match plain runtime errors", () => {
+    expect(isViteBuildError(new TypeError("Cannot read property 'x'"))).toBe(
+      false,
+    );
+    expect(isViteBuildError(undefined)).toBe(false);
+  });
+
+  it("requires esbuild's quoted specifier before trusting 'Could not resolve'", () => {
+    // esbuild always quotes the specifier (`Could not resolve "buffer/"`).
+    // Matching the bare phrase pulls in package-manager and DNS failures, and
+    // calling those recoverable would keep a genuinely broken pod alive while
+    // suppressing the dev_server_fatal_exit signal we alert on.
+    expect(
+      isViteBuildError(
+        new Error("Could not resolve dependency: peer react@^18.0.0"),
+      ),
+    ).toBe(false);
+    expect(
+      isViteBuildError(
+        "getaddrinfo ENOTFOUND: could not resolve host cdn.example.com",
+      ),
+    ).toBe(false);
+    expect(isViteBuildError('Could not resolve "buffer/"')).toBe(true);
+  });
+});
+
+describe("extractViteBuildErrorMessage", () => {
+  it("joins esbuild error texts", () => {
+    expect(
+      extractViteBuildErrorMessage({
+        errors: [{ text: 'Could not resolve "buffer/"' }],
+      }),
+    ).toBe('Could not resolve "buffer/"');
+  });
+
+  it("prefers errors[].text over stack for esbuild BuildFailure-shaped Errors", () => {
+    // Real optimizeDeps rejections are Error subclasses carrying `errors:
+    // Message[]`. The old `instanceof Error` early return sent the stack to the
+    // overlay instead of the resolve/transform line Clark needs.
+    class FakeBuildFailure extends Error {
+      errors: Array<{ text: string }>;
+      constructor(message: string, errors: Array<{ text: string }>) {
+        super(message);
+        this.errors = errors;
+      }
+    }
+
+    const reason = new FakeBuildFailure("Build failed with 1 error", [
+      { text: 'Could not resolve "buffer/"' },
+    ]);
+
+    expect(extractViteBuildErrorMessage(reason)).toBe(
+      'Could not resolve "buffer/"',
+    );
+    expect(extractViteBuildErrorMessage(reason)).not.toMatch(/^\s*at /m);
+  });
+
+  it("still uses stack for plain Errors without structured texts", () => {
+    const err = new Error("something broke");
+    expect(extractViteBuildErrorMessage(err)).toContain("something broke");
+  });
+
+  // This function runs inside the `uncaughtException` / `unhandledRejection`
+  // listeners, before the fatal-exit line is written. A throw here does not
+  // degrade to the fatal path — Node tears the process down immediately, so the
+  // real error never reaches the logs and the misleading TypeError shows up in
+  // its place. `isViteBuildError` accepts a message-marker match without
+  // re-validating `errors`, so a malformed `errors` array does reach us.
+  it("survives an errors array that is not esbuild messages", () => {
+    for (const errors of [
+      [{ text: 42 }],
+      [null],
+      [undefined],
+      ["plain string"],
+      [{ text: { nested: true } }],
+    ]) {
+      expect(() =>
+        extractViteBuildErrorMessage({
+          errors,
+          message: "Transform failed with 1 error",
+        }),
+      ).not.toThrow();
+    }
+  });
+
+  it("falls back to the message when no entry carries usable text", () => {
+    // Returning "" here would be classified, counted, and then rendered
+    // nowhere: the UI dispatches `loadError(rawError)` and an empty string is
+    // falsy, so the overlay never appears.
+    expect(
+      extractViteBuildErrorMessage({
+        errors: [{}],
+        message: "Build failed with 1 error",
+      }),
+    ).toBe("Build failed with 1 error");
+    expect(
+      extractViteBuildErrorMessage({
+        errors: [{ text: 42 }],
+        message: "Transform failed with 1 error",
+      }),
+    ).toBe("Transform failed with 1 error");
+  });
+
+  it("still prefers usable entry text over the outer message", () => {
+    expect(
+      extractViteBuildErrorMessage({
+        errors: [{ text: 'Could not resolve "buffer/"' }, { text: 42 }],
+        message: "Build failed with 1 error",
+      }),
+    ).toBe('Could not resolve "buffer/"');
+  });
+
+  it("never returns an empty string for an object with no usable text at all", () => {
+    expect(extractViteBuildErrorMessage({ errors: [{}] })).not.toBe("");
+  });
+});