@superblocksteam/sdk 2.0.157-next.5 → 2.0.157

package/src/dev-utils/dev-server.shutdown-lock.test.mts

@@ -1,58 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { handOverLockOnExit } from "./dev-server.mjs";
-
-/**
- * ENG-6128. The dev server's exit path used to drive the lock service through a
- * `shutdown({ serverInitiated })` that decided, inside the lock service, whether
- * to release. That flag is the dev server's knowledge, not the lock service's,
- * and getting it wrong in either direction is a live-edit outage: releasing a
- * lock the server has already reassigned takes the app away from the session
- * taking over, and failing to release on a normal exit makes the replacement
- * sandbox wait out the TTL.
- */
-describe("handOverLockOnExit", () => {
-  const makeLockService = () => ({
-    notifyClosedByServer: vi.fn(async () => undefined),
-    relinquishLock: vi.fn(async () => undefined),
-  });
-
-  it("hands the lock back when the dev server is the one stopping", async () => {
-    const lockService = makeLockService();
-
-    await handOverLockOnExit(lockService, { serverInitiated: false });
-
-    // Prompt release is the whole recovery story for this path: the heartbeat
-    // dies with the process, so anything not released here blocks the
-    // replacement sandbox for the two-minute TTL.
-    expect(lockService.relinquishLock).toHaveBeenCalledOnce();
-    expect(lockService.notifyClosedByServer).not.toHaveBeenCalled();
-  });
-
-  it("only notifies when the server closed the session", async () => {
-    const lockService = makeLockService();
-
-    await handOverLockOnExit(lockService, {
-      serverInitiated: true,
-      switchingTo: "local",
-      initiatedByEmail: "someone@example.com",
-    });
-
-    // The server has already taken the lock — on a local↔cloud switch it now
-    // belongs to the session taking over, so releasing would take it away from
-    // them.
-    expect(lockService.relinquishLock).not.toHaveBeenCalled();
-    expect(lockService.notifyClosedByServer).toHaveBeenCalledWith({
-      switchingTo: "local",
-      initiatedByEmail: "someone@example.com",
-    });
-  });
-
-  it("is a no-op when the dev server never had a lock service", async () => {
-    // Startup can fail before the lock service exists, and the exit path still
-    // runs.
-    await expect(
-      handOverLockOnExit(undefined, { serverInitiated: false }),
-    ).resolves.toBeUndefined();
-  });
-});

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

@@ -1,262 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,346 +0,0 @@
-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/);
-  });
-});