@superblocksteam/sdk 2.0.156 → 2.0.157-next.0

package/src/dev-utils/fatal-process-barrier.mts

@@ -0,0 +1,262 @@
+import {
+  sanitizeLogError,
+  sanitizeLogMessage,
+} from "@superblocksteam/telemetry";
+
+import { safeStringify } from "../telemetry/safe-stringify.js";
+import { buildFatalExitLog, parseIsWarm } from "./fatal-exit.mjs";
+
+export type FatalProcessHandler = "uncaughtException" | "unhandledRejection";
+
+export type FatalProcessListener = (...args: unknown[]) => void;
+
+/**
+ * The slice of `process` this needs, so a test can emit a crash without arming
+ * the real handlers and taking the runner down with them.
+ */
+export type FatalProcessHost = {
+  off: (event: string, handler: FatalProcessListener) => void;
+  on: (event: string, handler: FatalProcessListener) => void;
+};
+
+export type FatalErrorMeta = {
+  error: {
+    kind: string;
+    message: string;
+    stack?: string;
+  };
+};
+
+export type FatalProcessBarrierHooks = {
+  isNonFatal?: (handler: FatalProcessHandler, reason: unknown) => boolean;
+  /**
+   * Runs after the fatal-exit line is written and before `exit(1)`. The server
+   * path uses this for graceful shutdown. The early/preload path leaves it
+   * unset.
+   */
+  onFatal?: (
+    handler: FatalProcessHandler,
+    reason: unknown,
+  ) => void | Promise<void>;
+};
+
+export type FatalProcessBarrierOptions = FatalProcessBarrierHooks & {
+  exit?: (code: number) => void;
+  isWarm?: boolean;
+  log?: (message: string, meta?: FatalErrorMeta) => void;
+  process?: FatalProcessHost;
+};
+
+type BarrierState = {
+  fatalHandled: boolean;
+  hooks: {
+    exit: (code: number) => void;
+    isNonFatal?: FatalProcessBarrierHooks["isNonFatal"];
+    isWarm: boolean;
+    log: (message: string, meta?: FatalErrorMeta) => void;
+    onFatal?: FatalProcessBarrierHooks["onFatal"];
+  };
+  off: () => void;
+};
+
+/**
+ * Armed state lives on `globalThis`, not in a module-level WeakMap: the
+ * packaged CLI loads TWO copies of this file (bin/run.js imports the
+ * node_modules export; createDevServer uses the esbuild-bundled copy). A
+ * per-module map would make the second call register a new listener pair
+ * instead of attaching `isNonFatal` / `onFatal`, and the early copy would
+ * `exit(1)` on recoverable Vite/socket errors before shutdown ran.
+ */
+declare global {
+  var __superblocksFatalProcessBarrierArmed:
+    | WeakMap<FatalProcessHost, BarrierState>
+    | undefined;
+}
+
+function armedHosts(): WeakMap<FatalProcessHost, BarrierState> {
+  const existing = globalThis.__superblocksFatalProcessBarrierArmed;
+  if (existing) {
+    return existing;
+  }
+  const created = new WeakMap<FatalProcessHost, BarrierState>();
+  globalThis.__superblocksFatalProcessBarrierArmed = created;
+  return created;
+}
+
+function fatalErrorMeta(reason: unknown): FatalErrorMeta {
+  if (reason instanceof Error) {
+    return {
+      error: {
+        kind: reason.name,
+        message: reason.message,
+        stack: reason.stack,
+      },
+    };
+  }
+  return {
+    error: {
+      kind: "Unknown Error",
+      message: safeStringify(reason),
+    },
+  };
+}
+
+function stringField(value: unknown, key: string): string | undefined {
+  if (typeof value !== "object" || value === null || !(key in value)) {
+    return undefined;
+  }
+  const field = Reflect.get(value, key);
+  if (typeof field === "string") {
+    return field;
+  }
+  if (field === undefined) {
+    return undefined;
+  }
+  return safeStringify(field);
+}
+
+function defaultLog(message: string, meta?: FatalErrorMeta): void {
+  const safeMessage = sanitizeLogMessage(message);
+  if (!meta?.error) {
+    console.error(safeMessage);
+    return;
+  }
+  const sanitized = sanitizeLogError(meta.error);
+  console.error(safeMessage, {
+    error: {
+      kind:
+        stringField(sanitized, "kind") ??
+        stringField(sanitized, "name") ??
+        "Error",
+      message: stringField(sanitized, "message"),
+      stack: stringField(sanitized, "stack"),
+    },
+  });
+}
+
+function mergeHooks(
+  existing: BarrierState["hooks"],
+  options: FatalProcessBarrierOptions,
+): BarrierState["hooks"] {
+  return {
+    exit: options.exit ?? existing.exit,
+    isNonFatal: options.isNonFatal ?? existing.isNonFatal,
+    isWarm: options.isWarm ?? existing.isWarm,
+    log: options.log ?? existing.log,
+    onFatal: options.onFatal ?? existing.onFatal,
+  };
+}
+
+function handleCrash(
+  state: BarrierState,
+  handler: FatalProcessHandler,
+  reason: unknown,
+): void {
+  if (state.fatalHandled) {
+    return;
+  }
+  try {
+    if (state.hooks.isNonFatal?.(handler, reason)) {
+      return;
+    }
+  } catch (predicateError) {
+    // A throw inside the non-fatal check must not skip the fatal-exit line.
+    state.hooks.log(
+      "fatal process barrier isNonFatal threw; continuing as fatal",
+      fatalErrorMeta(predicateError),
+    );
+  }
+  state.fatalHandled = true;
+  try {
+    state.hooks.log(
+      buildFatalExitLog({
+        exitCode: 1,
+        handler,
+        isWarm: state.hooks.isWarm,
+      }),
+      fatalErrorMeta(reason),
+    );
+  } catch {
+    // Meta construction or the logger can throw; still run onFatal and exit(1).
+  }
+  const finish = (): void => {
+    state.hooks.exit(1);
+  };
+  const onFatal = state.hooks.onFatal;
+  if (!onFatal) {
+    finish();
+    return;
+  }
+  void Promise.resolve()
+    .then(() => onFatal(handler, reason))
+    .catch(() => undefined)
+    .finally(finish);
+}
+
+/**
+ * Arm process-level crash handlers once per host. A second call on the same
+ * host is a no-op for listeners and updates hooks when the caller supplies them
+ * (preload arms early; `createDevServer` later attaches shutdown). Shared
+ * across the node_modules and esbuild copies of this module.
+ */
+export function installFatalProcessBarrier(
+  options: FatalProcessBarrierOptions = {},
+): () => void {
+  const host = options.process ?? process;
+  const armed = armedHosts();
+  const existing = armed.get(host);
+  if (existing) {
+    existing.hooks = mergeHooks(existing.hooks, options);
+    return existing.off;
+  }
+
+  const state: BarrierState = {
+    fatalHandled: false,
+    hooks: {
+      exit: options.exit ?? ((code: number) => process.exit(code)),
+      isNonFatal: options.isNonFatal,
+      isWarm:
+        options.isWarm ?? parseIsWarm(process.env.SUPERBLOCKS_WARM_STANDBY),
+      log: options.log ?? defaultLog,
+      onFatal: options.onFatal,
+    },
+    off: () => undefined,
+  };
+
+  const onException = (error: unknown) => {
+    handleCrash(state, "uncaughtException", error);
+  };
+  const onRejection = (reason: unknown) => {
+    handleCrash(state, "unhandledRejection", reason);
+  };
+
+  host.on("uncaughtException", onException);
+  host.on("unhandledRejection", onRejection);
+
+  state.off = () => {
+    armed.delete(host);
+    host.off("uncaughtException", onException);
+    host.off("unhandledRejection", onRejection);
+  };
+  armed.set(host, state);
+  return state.off;
+}
+
+export function isFatalProcessHandled(
+  host: FatalProcessHost = process,
+): boolean {
+  return armedHosts().get(host)?.fatalHandled ?? false;
+}
+
+/** Exit code graceful shutdown should use so a crash is not reported as 0. */
+export function fatalAwareExitCode(host: FatalProcessHost = process): number {
+  return isFatalProcessHandled(host) ? 1 : 0;
+}
+
+/**
+ * Child/warm entry: arm before oclif/`dev()` so a startup crash still writes
+ * `event=dev_server_fatal_exit`. Safe to call again later from createDevServer.
+ */
+export function installEarlyFatalProcessBarrier(): void {
+  installFatalProcessBarrier();
+}

package/src/dev-utils/fatal-process-barrier.spawn-fixture.mts

@@ -0,0 +1,12 @@
+import { pathToFileURL } from "node:url";
+
+import { installEarlyFatalProcessBarrier } from "./fatal-process-barrier.mjs";
+
+const isMain =
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isMain) {
+  installEarlyFatalProcessBarrier();
+  throw new TypeError("spawn-fixture crash");
+}

package/src/dev-utils/fatal-process-barrier.test.mts

@@ -0,0 +1,346 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { FATAL_EXIT_EVENT } from "./fatal-exit.mjs";
+import {
+  fatalAwareExitCode,
+  installFatalProcessBarrier,
+  isFatalProcessHandled,
+  type FatalProcessHost,
+} from "./fatal-process-barrier.mjs";
+
+/**
+ * Stands in for `process` so a test can emit crash events without arming the
+ * real handlers, which would take the test runner down with them.
+ */
+function fakeProcess(): FatalProcessHost & {
+  emit: (event: string, ...args: unknown[]) => void;
+  listenerCount: (event: string) => number;
+} {
+  const handlers = new Map<string, ((...args: unknown[]) => void)[]>();
+  return {
+    emit(event: string, ...args: unknown[]): void {
+      for (const handler of handlers.get(event) ?? []) {
+        handler(...args);
+      }
+    },
+    listenerCount(event: string): number {
+      return handlers.get(event)?.length ?? 0;
+    },
+    off(event: string, handler: (...args: unknown[]) => void): void {
+      handlers.set(
+        event,
+        (handlers.get(event) ?? []).filter((each) => each !== handler),
+      );
+    },
+    on(event: string, handler: (...args: unknown[]) => void): void {
+      handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+    },
+  };
+}
+
+describe("installFatalProcessBarrier", () => {
+  it("logs a fatal-exit line with error meta and exits 1 when a throw happens before the server exists", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const crash = new TypeError("cannot read properties of null");
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("uncaughtException", crash);
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(log).toHaveBeenCalledTimes(1);
+    const [message, meta] = log.mock.calls[0] ?? [];
+    expect(message).toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(message).toContain("handler=uncaughtException");
+    expect(message).toContain("exit_code=1");
+    expect(meta).toEqual({
+      error: {
+        kind: "TypeError",
+        message: "cannot read properties of null",
+        stack: crash.stack,
+      },
+    });
+  });
+
+  it("serializes a plain-object rejection so the message is not [object Object]", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const reason = { code: 8, message: "[internal] Connection closed" };
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("unhandledRejection", reason);
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    const [, meta] = log.mock.calls[0] ?? [];
+    expect(meta).toEqual({
+      error: {
+        kind: "Unknown Error",
+        message: JSON.stringify(reason),
+      },
+    });
+  });
+
+  it("serializes a BigInt field in a non-Error rejection and still exits 1", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const reason = { id: 8n, message: "closed" };
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("unhandledRejection", reason);
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    const [message, meta] = log.mock.calls[0] ?? [];
+    expect(String(message)).toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(meta).toEqual({
+      error: {
+        kind: "Unknown Error",
+        message: '{"id":"8","message":"closed"}',
+      },
+    });
+  });
+
+  it("still writes the fatal-exit line and exits 1 when toJSON throws", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const reason = {
+      toJSON() {
+        throw new Error("cannot serialize");
+      },
+    };
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("unhandledRejection", reason);
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(log).toHaveBeenCalledTimes(1);
+    const [message, meta] = log.mock.calls[0] ?? [];
+    expect(String(message)).toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(meta).toEqual({
+      error: {
+        kind: "Unknown Error",
+        message: "[object Object]",
+      },
+    });
+    expect(isFatalProcessHandled(host)).toBe(true);
+  });
+
+  it("still exits 1 when the fatal log itself throws after the barrier is marked handled", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+
+    installFatalProcessBarrier({
+      exit,
+      isWarm: false,
+      log: () => {
+        throw new Error("logger exploded");
+      },
+      process: host,
+    });
+    host.emit("uncaughtException", new Error("boom"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(isFatalProcessHandled(host)).toBe(true);
+  });
+
+  it("labels an unhandled rejection as a rejection, not an exception", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("unhandledRejection", new Error("upstream timed out"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    const [message] = log.mock.calls[0] ?? [];
+    expect(message).toContain("handler=unhandledRejection");
+  });
+
+  it("writes one fatal-exit line for a burst of crashes", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("uncaughtException", new Error("first"));
+    host.emit("unhandledRejection", new Error("second"));
+    host.emit("uncaughtException", new Error("third"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledTimes(1));
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(String(log.mock.calls[0]?.[0])).toContain(
+      "handler=uncaughtException",
+    );
+  });
+
+  it("arms one set of handlers however many times it is installed", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    host.emit("uncaughtException", new Error("boom"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledTimes(1));
+    expect(log).toHaveBeenCalledTimes(1);
+  });
+
+  it("still exits fatally when isNonFatal throws, and logs the predicate failure", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const predicateError = new Error("predicate exploded");
+
+    installFatalProcessBarrier({
+      exit,
+      isNonFatal: () => {
+        throw predicateError;
+      },
+      log,
+      process: host,
+    });
+    host.emit("unhandledRejection", new Error("closed"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(log).toHaveBeenCalledTimes(2);
+    const [predicateMessage, predicateMeta] = log.mock.calls[0] ?? [];
+    expect(String(predicateMessage)).not.toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(predicateMeta).toEqual({
+      error: {
+        kind: "Error",
+        message: "predicate exploded",
+        stack: predicateError.stack,
+      },
+    });
+    const [fatalMessage] = log.mock.calls[1] ?? [];
+    expect(String(fatalMessage)).toContain(`event=${FATAL_EXIT_EVENT}`);
+  });
+
+  it("keeps the process alive when isNonFatal says the reason is recoverable", () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+
+    installFatalProcessBarrier({
+      exit,
+      isNonFatal: (_handler, reason) =>
+        reason instanceof Error && reason.message === "closed",
+      log,
+      process: host,
+    });
+    host.emit("unhandledRejection", new Error("closed"));
+
+    expect(exit).not.toHaveBeenCalled();
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it("upgrades onFatal on an already-armed host without a second listener", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const onFatal = vi.fn();
+
+    installFatalProcessBarrier({ exit, isWarm: false, log, process: host });
+    installFatalProcessBarrier({ onFatal, process: host });
+    host.emit("uncaughtException", new Error("boom"));
+
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(onFatal).toHaveBeenCalledTimes(1);
+    expect(onFatal.mock.calls[0]?.[0]).toBe("uncaughtException");
+  });
+
+  it("reports a crash as exit code 1 so graceful shutdown cannot claim 0", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+
+    installFatalProcessBarrier({
+      exit,
+      log: () => undefined,
+      onFatal: () => undefined,
+      process: host,
+    });
+    expect(fatalAwareExitCode(host)).toBe(0);
+    host.emit("uncaughtException", new Error("boom"));
+    await vi.waitFor(() => expect(isFatalProcessHandled(host)).toBe(true));
+    expect(fatalAwareExitCode(host)).toBe(1);
+  });
+});
+
+describe("installFatalProcessBarrier across CLI module copies", () => {
+  afterEach(() => {
+    vi.resetModules();
+  });
+
+  it("shares hooks across module instances, as when bin/run.js and the esbuild bundle each load their own", async () => {
+    const host = fakeProcess();
+    const exit = vi.fn();
+    const log = vi.fn();
+    const onFatal = vi.fn();
+
+    const early = await import("./fatal-process-barrier.mjs");
+    early.installFatalProcessBarrier({
+      exit,
+      isWarm: false,
+      log,
+      process: host,
+    });
+    expect(host.listenerCount("uncaughtException")).toBe(1);
+    expect(host.listenerCount("unhandledRejection")).toBe(1);
+
+    vi.resetModules();
+    const later = await import("./fatal-process-barrier.mjs");
+    later.installFatalProcessBarrier({
+      exit,
+      isNonFatal: (_handler, reason) =>
+        reason instanceof Error && reason.message === "closed",
+      log,
+      onFatal,
+      process: host,
+    });
+
+    expect(host.listenerCount("uncaughtException")).toBe(1);
+    expect(host.listenerCount("unhandledRejection")).toBe(1);
+
+    host.emit("unhandledRejection", new Error("closed"));
+    expect(exit).not.toHaveBeenCalled();
+    expect(log).not.toHaveBeenCalled();
+    expect(onFatal).not.toHaveBeenCalled();
+
+    host.emit("uncaughtException", new Error("boom"));
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
+    expect(onFatal).toHaveBeenCalledTimes(1);
+    expect(log).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("installEarlyFatalProcessBarrier in a real Node process", () => {
+  it("writes the fatal-exit token and stack to stderr before exiting 1", () => {
+    const fixture = fileURLToPath(
+      new URL("./fatal-process-barrier.spawn-fixture.mts", import.meta.url),
+    );
+    const require = createRequire(
+      fileURLToPath(new URL("../../package.json", import.meta.url)),
+    );
+    const tsx = require.resolve("tsx");
+    const result = spawnSync(process.execPath, ["--import", tsx, fixture], {
+      encoding: "utf8",
+      env: { ...process.env, NODE_OPTIONS: "" },
+      timeout: 30_000,
+    });
+
+    const output = `${result.stdout}${result.stderr}`;
+    expect(result.status).toBe(1);
+    expect(output).toContain(`event=${FATAL_EXIT_EVENT}`);
+    expect(output).toContain("handler=uncaughtException");
+    expect(output).toContain("spawn-fixture crash");
+    expect(output).toMatch(/TypeError/);
+  });
+});

package/src/telemetry/logging.ts

@@ -214,7 +214,7 @@ export function getErrorMeta(error: unknown): ErrorMeta {
   return {
     error: {
       kind: "Unknown Error",
-      message: safeStringify(error) ?? String(error),
+      message: safeStringify(error),
     },
   };
 }

package/src/telemetry/safe-stringify.ts

@@ -1,3 +1,11 @@
+function fallbackString(value: unknown): string {
+  try {
+    return String(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
 export function safeStringify(obj: unknown): string {
   if (obj === null || obj === undefined) {
     return String(obj);
@@ -9,15 +17,22 @@ export function safeStringify(obj: unknown): string {
     return String(obj);
   }
 
-  const seen = new WeakSet();
-  return JSON.stringify(obj, (_key, value) => {
-    if (value === null || typeof value !== "object") {
+  const seen = new WeakSet<object>();
+  try {
+    return JSON.stringify(obj, (_key, value: unknown) => {
+      if (typeof value === "bigint") {
+        return value.toString();
+      }
+      if (value === null || typeof value !== "object") {
+        return value;
+      }
+      if (seen.has(value)) {
+        return "[Circular]";
+      }
+      seen.add(value);
       return value;
-    }
-    if (seen.has(value)) {
-      return "[Circular]";
-    }
-    seen.add(value);
-    return value;
-  });
+    });
+  } catch {
+    return fallbackString(obj);
+  }
 }

package/test/safe-stringify.test.mts

@@ -15,4 +15,29 @@ describe("safeStringify", () => {
     obj.self = obj;
     expect(safeStringify(obj)).toBe('{"a":1,"self":"[Circular]"}');
   });
+
+  it("does not throw on BigInt fields", () => {
+    expect(safeStringify({ id: 8n })).toBe('{"id":"8"}');
+  });
+
+  it("does not throw when toJSON throws", () => {
+    const obj = {
+      toJSON() {
+        throw new Error("cannot serialize");
+      },
+    };
+    expect(safeStringify(obj)).toBe("[object Object]");
+  });
+
+  it("does not throw when both toJSON and toString throw", () => {
+    const obj = {
+      toJSON() {
+        throw new Error("cannot serialize");
+      },
+      toString() {
+        throw new Error("cannot stringify");
+      },
+    };
+    expect(safeStringify(obj)).toBe("[unserializable]");
+  });
 });