@superblocksteam/sdk 2.0.146 → 2.0.147

package/src/dev-utils/recoverable-build-error.mts

@@ -0,0 +1,151 @@
+import type {
+  DevServerBuildError,
+  ServerError,
+} from "@superblocksteam/library-shared/types";
+
+import {
+  extractViteBuildErrorMessage,
+  isViteBuildError,
+} from "./fatal-exit.mjs";
+import {
+  diagnoseViteBuildLogMessage,
+  truncateViteRawLog,
+} from "./vite-dev-server-diagnostics.mjs";
+
+/** Maximum build errors retained on `devServerStatus.serverErrors`. */
+export const MAX_DEV_SERVER_BUILD_ERRORS = 5;
+
+type DevServerStatus = { serverErrors: ServerError[] };
+
+export function buildDevServerBuildErrorDedupeKey(
+  entry: Pick<DevServerBuildError, "category" | "unresolvedSpecifier">,
+): string {
+  return `${entry.category}:${entry.unresolvedSpecifier ?? ""}`;
+}
+
+export function buildDevServerBuildError(reason: unknown): DevServerBuildError {
+  const fullMessage = extractViteBuildErrorMessage(reason);
+  // Classify against the full text so a specifier past the cap is still found,
+  // but store the capped copy: this string is persisted on `serverErrors`,
+  // logged, sent over `/_sb_connect`, and rendered in the editor overlay.
+  const diagnostic = diagnoseViteBuildLogMessage(fullMessage);
+  const rawError = truncateViteRawLog(fullMessage);
+
+  if (diagnostic.category === "module_resolve") {
+    return {
+      type: "dev-server/build",
+      timestamp: new Date().toISOString(),
+      category: diagnostic.category,
+      unresolvedSpecifier: diagnostic.unresolvedSpecifier,
+      rawError,
+    };
+  }
+
+  return {
+    type: "dev-server/build",
+    timestamp: new Date().toISOString(),
+    category: diagnostic.category,
+    rawError,
+  };
+}
+
+export function upsertDevServerBuildError(
+  devServerStatus: DevServerStatus,
+  entry: DevServerBuildError,
+): void {
+  const dedupeKey = buildDevServerBuildErrorDedupeKey(entry);
+  devServerStatus.serverErrors = devServerStatus.serverErrors.filter(
+    (existing) =>
+      existing.type !== "dev-server/build" ||
+      buildDevServerBuildErrorDedupeKey(existing) !== dedupeKey,
+  );
+  devServerStatus.serverErrors.push(entry);
+
+  // Cap build errors only. `serverErrors` is shared with the startup path,
+  // which pushes a dependency-install/upgrade entry once per pod before Vite
+  // serves anything; those sit at the front and can never be re-reported, so a
+  // whole-array cap keeping the newest entries would evict them first.
+  let excess =
+    devServerStatus.serverErrors.filter(
+      (existing) => existing.type === "dev-server/build",
+    ).length - MAX_DEV_SERVER_BUILD_ERRORS;
+  if (excess > 0) {
+    devServerStatus.serverErrors = devServerStatus.serverErrors.filter(
+      (existing) => {
+        if (excess > 0 && existing.type === "dev-server/build") {
+          excess -= 1;
+          return false;
+        }
+        return true;
+      },
+    );
+  }
+}
+
+type RecoverableBuildErrorHandler = "uncaughtException" | "unhandledRejection";
+
+type RecoverableBuildErrorMetrics = {
+  recordRecoverableBuildError: (labels: {
+    category: string;
+    handler: RecoverableBuildErrorHandler;
+  }) => void;
+};
+
+/**
+ * When a Vite/esbuild build error reaches the process-level handler, keep the
+ * pod alive and record it for the editor's `/_sb_connect` readiness path.
+ */
+export function handleRecoverableBuildError(params: {
+  devServerStatus?: DevServerStatus;
+  devServerMetrics: RecoverableBuildErrorMetrics;
+  handler: RecoverableBuildErrorHandler;
+  logger: {
+    warn: (message: string, meta?: unknown) => void;
+  };
+  reason: unknown;
+}): boolean {
+  // Never throw. This runs inside the process-level `uncaughtException` /
+  // `unhandledRejection` listeners, ahead of the caller's `fatalExitHandled`
+  // latch and its fatal-exit log line. Node does not degrade a throw from those
+  // listeners to the normal fatal path — it tears the process down immediately,
+  // losing the real error, the metric, and `gracefulShutdown`, and leaving a
+  // misleading TypeError in their place. Returning `false` instead routes the
+  // caller to its fatal path, which logs the original reason.
+  //
+  // `isViteBuildError` classifies on a message marker without re-validating
+  // `errors`, so a malformed array reaches the extraction below; that specific
+  // hazard is handled in `extractViteBuildErrorMessage`, and this guard covers
+  // whatever else the diagnostic, upsert, and metric steps can raise.
+  try {
+    if (!isViteBuildError(params.reason)) {
+      return false;
+    }
+
+    const entry = buildDevServerBuildError(params.reason);
+    if (params.devServerStatus) {
+      upsertDevServerBuildError(params.devServerStatus, entry);
+    }
+
+    params.devServerMetrics.recordRecoverableBuildError({
+      category: entry.category,
+      handler: params.handler,
+    });
+
+    params.logger.warn(
+      `Ignoring recoverable Vite build error (${params.handler})`,
+      { error: entry },
+    );
+
+    return true;
+  } catch (recordError) {
+    // Falling through to the fatal path is the safe direction: the pod exits
+    // and the caller logs the original reason. Note the bookkeeping failure
+    // separately so a malformed-reason bug stays diagnosable instead of looking
+    // like a plain crash.
+    params.logger.warn(
+      `Failed to record recoverable Vite build error (${params.handler}); treating as fatal`,
+      { recordError },
+    );
+    return false;
+  }
+}

package/src/dev-utils/recoverable-build-error.test.mts

@@ -0,0 +1,236 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type {
+  DevServerBuildError,
+  ServerError,
+} from "@superblocksteam/library-shared/types";
+
+import {
+  buildDevServerBuildError,
+  buildDevServerBuildErrorDedupeKey,
+  handleRecoverableBuildError,
+  MAX_DEV_SERVER_BUILD_ERRORS,
+  upsertDevServerBuildError,
+} from "./recoverable-build-error.mjs";
+import { VITE_ERROR_RAW_LOG_MAX_CHARS } from "./vite-dev-server-diagnostics.mjs";
+
+describe("buildDevServerBuildError", () => {
+  it("classifies module resolve failures with the unresolved specifier", () => {
+    const entry = buildDevServerBuildError({
+      errors: [{ text: 'Could not resolve "buffer/"' }],
+    });
+    expect(entry.type).toBe("dev-server/build");
+    expect(entry.category).toBe("module_resolve");
+    expect(entry.unresolvedSpecifier).toBe("buffer/");
+    expect(entry.rawError).toContain("buffer/");
+  });
+
+  it("truncates rawError to the same cap the logging pipeline uses", () => {
+    // rawError is persisted on serverErrors, logged, shipped over
+    // /_sb_connect, and rendered in the editor overlay. A pathological stack or
+    // a failure listing hundreds of specifiers must not reach any of those
+    // unbounded.
+    const entry = buildDevServerBuildError({
+      errors: [
+        {
+          text: `Could not resolve "buffer/"\n${"x".repeat(
+            VITE_ERROR_RAW_LOG_MAX_CHARS * 2,
+          )}`,
+        },
+      ],
+    });
+
+    expect(entry.rawError.length).toBeLessThan(
+      VITE_ERROR_RAW_LOG_MAX_CHARS + 100,
+    );
+    expect(entry.rawError).toContain("(truncated)");
+    // Classification still reads the full text, so the specifier survives even
+    // when it sits past the cap.
+    expect(entry.category).toBe("module_resolve");
+    expect(entry.unresolvedSpecifier).toBe("buffer/");
+  });
+});
+
+describe("upsertDevServerBuildError", () => {
+  it("dedupes by category and unresolved specifier and caps the list", () => {
+    const devServerStatus = { serverErrors: [] as ServerError[] };
+    const first = buildDevServerBuildError({
+      errors: [{ text: 'Could not resolve "buffer/"' }],
+    });
+    const second = buildDevServerBuildError({
+      errors: [{ text: 'Could not resolve "buffer/"' }],
+    });
+
+    upsertDevServerBuildError(devServerStatus, first);
+    upsertDevServerBuildError(devServerStatus, second);
+    expect(devServerStatus.serverErrors).toHaveLength(1);
+    expect(devServerStatus.serverErrors[0]?.timestamp).toBe(second.timestamp);
+
+    for (let index = 0; index < MAX_DEV_SERVER_BUILD_ERRORS + 2; index++) {
+      upsertDevServerBuildError(
+        devServerStatus,
+        buildDevServerBuildError({
+          errors: [{ text: `Could not resolve "pkg-${index}/"` }],
+        }),
+      );
+    }
+    expect(devServerStatus.serverErrors.length).toBeLessThanOrEqual(
+      MAX_DEV_SERVER_BUILD_ERRORS,
+    );
+  });
+
+  it("uses a stable dedupe key", () => {
+    expect(
+      buildDevServerBuildErrorDedupeKey({
+        category: "module_resolve",
+        unresolvedSpecifier: "buffer/",
+      }),
+    ).toBe("module_resolve:buffer/");
+  });
+
+  it("keeps startup errors when a burst of build errors exceeds the cap", () => {
+    // `serverErrors` is shared with the startup path, which pushes a
+    // `dependency-install` / `dependency-upgrade` entry once per pod before
+    // Vite ever serves a request. Those sit at the front of the array, so a
+    // cap that counted every entry and kept only the newest would evict the
+    // install failure first — the one entry the user most needs to act on, and
+    // one that can never be re-reported.
+    const installError: ServerError = {
+      type: "dev-server/dependency-install",
+      timestamp: new Date("2026-01-01T00:00:00.000Z").toISOString(),
+      category: "not_in_registry",
+      message: "npm ERR! 404 Not Found - GET https://registry/plotly.js",
+    } as ServerError;
+    const devServerStatus = { serverErrors: [installError] };
+
+    for (let index = 0; index < MAX_DEV_SERVER_BUILD_ERRORS + 3; index++) {
+      upsertDevServerBuildError(
+        devServerStatus,
+        buildDevServerBuildError({
+          errors: [{ text: `Could not resolve "pkg-${index}/"` }],
+        }),
+      );
+    }
+
+    expect(devServerStatus.serverErrors).toContain(installError);
+    expect(
+      devServerStatus.serverErrors.filter(
+        (entry) => entry.type === "dev-server/build",
+      ),
+    ).toHaveLength(MAX_DEV_SERVER_BUILD_ERRORS);
+  });
+
+  it("evicts the oldest build error rather than an arbitrary entry", () => {
+    const devServerStatus = { serverErrors: [] as ServerError[] };
+    for (let index = 0; index < MAX_DEV_SERVER_BUILD_ERRORS + 1; index++) {
+      upsertDevServerBuildError(
+        devServerStatus,
+        buildDevServerBuildError({
+          errors: [{ text: `Could not resolve "pkg-${index}/"` }],
+        }),
+      );
+    }
+
+    const specifiers = devServerStatus.serverErrors.map(
+      (entry) => (entry as DevServerBuildError).unresolvedSpecifier,
+    );
+    expect(specifiers).not.toContain("pkg-0/");
+    expect(specifiers).toContain(`pkg-${MAX_DEV_SERVER_BUILD_ERRORS}/`);
+  });
+});
+
+describe("handleRecoverableBuildError", () => {
+  it("records a build error and returns true for esbuild failures", () => {
+    const devServerStatus = { serverErrors: [] as ServerError[] };
+    const recordRecoverableBuildError = vi.fn();
+    const metrics = {
+      recordRecoverableBuildError,
+    };
+
+    const handled = handleRecoverableBuildError({
+      devServerStatus,
+      devServerMetrics: metrics,
+      handler: "unhandledRejection",
+      logger: { warn: vi.fn() },
+      reason: {
+        errors: [{ text: 'Could not resolve "buffer/"' }],
+      },
+    });
+
+    expect(handled).toBe(true);
+    expect(devServerStatus.serverErrors).toHaveLength(1);
+    expect(recordRecoverableBuildError).toHaveBeenCalledWith({
+      category: "module_resolve",
+      handler: "unhandledRejection",
+    });
+  });
+
+  // This runs inside the `uncaughtException` / `unhandledRejection` listeners
+  // before the caller writes its fatal-exit line. An escaping throw there does
+  // not degrade to the fatal path: Node tears the process down immediately, so
+  // the real error never reaches the logs, no metric is emitted, and
+  // `gracefulShutdown` never runs. Returning false instead routes the caller to
+  // its normal fatal path, which logs the original reason.
+  it("falls back to the fatal path instead of throwing when recording fails", () => {
+    const logger = { warn: vi.fn() };
+    const handled = handleRecoverableBuildError({
+      devServerStatus: { serverErrors: [] as ServerError[] },
+      devServerMetrics: {
+        recordRecoverableBuildError: () => {
+          throw new Error("meter unavailable");
+        },
+      },
+      handler: "uncaughtException",
+      logger,
+      reason: { errors: [{ text: 'Could not resolve "buffer/"' }] },
+    });
+
+    expect(handled).toBe(false);
+    // The bookkeeping failure is noted separately so a malformed reason is
+    // diagnosable rather than looking like a plain crash.
+    expect(logger.warn).toHaveBeenCalled();
+  });
+
+  it("keeps the recoverable path for a reason whose errors array is malformed", () => {
+    // `isViteBuildError` accepts this via the message marker without
+    // re-validating `errors`, which is how a malformed array reaches the
+    // extraction step.
+    const devServerStatus = { serverErrors: [] as ServerError[] };
+    const logger = { warn: vi.fn() };
+
+    const handled = handleRecoverableBuildError({
+      devServerStatus,
+      devServerMetrics: { recordRecoverableBuildError: vi.fn() },
+      handler: "unhandledRejection",
+      logger,
+      reason: {
+        errors: [{ text: 42 }],
+        message: "Transform failed with 1 error",
+      },
+    });
+
+    expect(handled).toBe(true);
+    expect(devServerStatus.serverErrors).toHaveLength(1);
+    expect(
+      (devServerStatus.serverErrors[0] as { rawError: string }).rawError,
+    ).toContain("Transform failed");
+  });
+
+  it("returns false for non-build errors", () => {
+    const devServerStatus = { serverErrors: [] as ServerError[] };
+    const metrics = {
+      recordRecoverableBuildError: vi.fn(),
+    };
+
+    expect(
+      handleRecoverableBuildError({
+        devServerStatus,
+        devServerMetrics: metrics,
+        handler: "uncaughtException",
+        logger: { warn: vi.fn() },
+        reason: new TypeError("boom"),
+      }),
+    ).toBe(false);
+    expect(devServerStatus.serverErrors).toHaveLength(0);
+  });
+});