@superblocksteam/sdk 2.0.151 → 2.0.152-next.1

package/dist/vite-plugin-generate-api-build-manifest.mjs

@@ -17,6 +17,28 @@ const BUILD_MANIFEST_HASHED_RE = /[\\/]build-manifest(?:-[A-Za-z0-9]+)?\.js$/;
 function isBuildManifestModule(id) {
     return (id.endsWith(BUILD_MANIFEST_SUFFIX) || BUILD_MANIFEST_HASHED_RE.test(id));
 }
+/**
+ * Emits a structured WARN when the logger supports it, falling back to a
+ * plain `warn` with just the human-readable message otherwise.
+ * `warnStructured` is optional on the `Logger` type (future/alternate
+ * implementations may omit it), so calling it with `?.` alone would let an
+ * auth-relevant warning disappear silently on such a logger. Both call
+ * sites in this plugin route through here instead of duplicating the
+ * fallback branch.
+ *
+ * `message` must be the plain, uncolored text — it becomes the OTel log
+ * body when `warnStructured` is available, and ANSI escapes have no place
+ * in a structured body. Coloring is applied only in the console-facing
+ * fallback branch below.
+ */
+function warnStructured(logger, message, attributes) {
+    if (logger.warnStructured) {
+        logger.warnStructured(message, attributes);
+    }
+    else {
+        logger.warn(yellow(message));
+    }
+}
 /**
  * Vite plugin that generates a build manifest for the application.
  *
@@ -74,6 +96,30 @@ export function generateApiBuildManifestPlugin(root) {
                 ? await collectSdkApisFromRegistry(root, {
                     pathExists: (p) => fs.pathExists(p),
                     readFile: (p, enc) => fs.readFile(p, enc),
+                    realpath: (p) => fs.realpath(p),
+                }, {
+                    onUnresolvedIntegrations: (apiName, entryPoint, unresolvedKeys) => {
+                        warnStructured(logger, `[superblocks] Could not resolve integration(s) ${unresolvedKeys
+                            .map((k) => `"${k}"`)
+                            .join(", ")} declared in ${entryPoint} (API "${apiName}") — check-auth may be skipped for this API in deployed/preview mode. Declare the integration or its ID in the same file.`, {
+                            // Bounded/numeric only — api name, entry point, and the
+                            // unresolved keys themselves are free-form text and stay
+                            // in the message body (searchable, not faceted) to keep
+                            // OTel log attribute cardinality low. See the
+                            // `LogAttributes` doc comment in ./telemetry/logging.ts.
+                            "sdk.integrations.unresolved_count": unresolvedKeys.length,
+                        });
+                    },
+                    onExtractionError: (apiName, entryPoint, error) => {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        warnStructured(logger, `[superblocks] Failed to extract integrations from ${entryPoint} (API "${apiName}"): ${errorMessage} — check-auth may be skipped for this API in deployed/preview mode.`, {
+                            // Bounded constant only — api name, entry point, and the
+                            // raw error message are free-form text and stay in the
+                            // message body. See the `LogAttributes` doc comment in
+                            // ./telemetry/logging.ts.
+                            "sdk.extraction.error_category": "read_or_extract_failed",
+                        });
+                    },
                 })
                 : {};
             manifestCode = `export default ${JSON.stringify({

package/dist/vite-plugin-generate-api-build-manifest.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin-generate-api-build-manifest.mjs","sourceRoot":"","sources":["../src/vite-plugin-generate-api-build-manifest.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vite-plugin-generate-api-build-manifest.mjs","sourceRoot":"","sources":["../src/vite-plugin-generate-api-build-manifest.mts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk",
-  "version": "2.0.151",
+  "version": "2.0.152-next.1",
   "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.151",
-    "@superblocksteam/shared": "0.9604.3",
-    "@superblocksteam/telemetry": "2.0.151",
-    "@superblocksteam/util": "2.0.151",
-    "@superblocksteam/vite-plugin-file-sync": "2.0.151"
+    "@superblocksteam/library-shared": "2.0.152-next.1",
+    "@superblocksteam/shared": "0.9605.1",
+    "@superblocksteam/telemetry": "2.0.152-next.1",
+    "@superblocksteam/util": "2.0.152-next.1",
+    "@superblocksteam/vite-plugin-file-sync": "2.0.152-next.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/src/cli-replacement/automatic-upgrades.ts

@@ -181,13 +181,15 @@ async function upgradeCliWithOclif(targetVersion: string): Promise<boolean> {
 }
 
 // Resolves when an install command ran and post-install validation passed.
-// Every failure throws `UpgradeFailed` carrying a classified, non-blocking
+// Every failure throws `UpgradeFailed` carrying a classified
 // `DependencyUpgradeError` — the no-command branch, an exec failure, and a
-// post-install version mismatch all degrade the same way. The dev.mts join
-// routes that marker to the degrade path, so the live-edit pod keeps serving
-// the currently installed version instead of crash-looping. The auto-upgrade
-// is best-effort: the running version still works, so a failed upgrade is
-// never fatal.
+// post-install version mismatch all arrive the same way. What the dev.mts join
+// does with that marker depends on who owns the process: on a developer machine
+// it degrades, so the dev server keeps serving the currently installed version.
+// In a disposable sandbox (`SUPERBLOCKS_IS_CSB=true`) a failure that could have
+// mutated `node_modules` is fatal — the process exits so the sandbox is
+// replaced rather than left serving a possibly-tainted tree (ENG-5297). See
+// `handleStartupError` and `upgradeCategoryCouldTaintTree` in dev.mts.
 async function upgradeCliWithPackageManager(
   pm: DetectResult,
   targetVersion: string,

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

@@ -294,6 +294,7 @@ function buildMockSdk() {
       devServerCloudInactivityTimeoutMinutes: () => 30,
       devServerLocalInactivityTimeoutMinutes: () => 30,
       enableSessionRecording: () => false,
+      removeManualCommitsEnabled: () => false,
     })),
     getFeatureFlagsForUser: vi.fn(() => ({
       devServerCloudInactivityTimeoutMinutes: () => 30,

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

@@ -342,6 +342,7 @@ function buildMockSdk() {
       devServerCloudInactivityTimeoutMinutes: () => 30,
       devServerLocalInactivityTimeoutMinutes: () => 30,
       enableSessionRecording: () => false,
+      removeManualCommitsEnabled: () => false,
     })),
     getFeatureFlagsForUser: vi.fn(() => ({
       devServerCloudInactivityTimeoutMinutes: () => 30,

package/src/cli-replacement/dev.interception.test.mts

@@ -1,24 +1,35 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 
+import type { DependencyUpgradeError } from "@superblocksteam/library-shared/types";
+
+import type * as TelemetryModule from "../telemetry/index.js";
+import type { Logger } from "../telemetry/logging.js";
 import {
   InitialInstallFailed,
   UpgradeFailed,
 } from "./dependency-install-classifier.mjs";
-import { handleStartupError } from "./dev.mjs";
+import {
+  flushTelemetryWithTimeout,
+  handleStartupError,
+  runFatalExitShutdown,
+  upgradeCategoryCouldTaintTree,
+  type DevServerStatus,
+} from "./dev.mjs";
 
 // Mock the metrics module so we can assert recordInitialInstallFailure /
 // recordUpgradeFailure calls. vi.mock is hoisted, so we use vi.hoisted to
 // declare the spies before the factory.
-const { recordInitialInstallFailureMock, recordUpgradeFailureMock } =
+const { recordInitialInstallFailureMock, recordUpgradeFailureMock, flushMock } =
   vi.hoisted(() => ({
     recordInitialInstallFailureMock: vi.fn(),
     recordUpgradeFailureMock: vi.fn(),
+    flushMock: vi.fn(),
   }));
 vi.mock("../dev-utils/dev-server-metrics.mjs", () => ({
   devServerMetrics: {
     recordInitialInstallFailure: recordInitialInstallFailureMock,
     recordUpgradeFailure: recordUpgradeFailureMock,
-    flush: vi.fn(),
+    flush: flushMock,
     recordEndpoint: vi.fn(),
     recordSocketUpgrade: vi.fn(),
     recordViteEagerInit: vi.fn(),
@@ -28,17 +39,37 @@ vi.mock("../dev-utils/dev-server-metrics.mjs", () => ({
   },
 }));
 
-const makeLogger = () =>
-  ({ error: () => {}, info: () => {}, warn: () => {} }) as any;
+// The raced telemetry flush is the one piece of the fatal-exit path that talks
+// to the OTel SDK, so it is stubbed to make both race outcomes reachable.
+const { shutdownTelemetryMock } = vi.hoisted(() => ({
+  shutdownTelemetryMock: vi.fn<() => Promise<boolean>>(async () => true),
+}));
+vi.mock("../telemetry/index.js", async (importOriginal) => ({
+  ...(await importOriginal<typeof TelemetryModule>()),
+  shutdownTelemetry: shutdownTelemetryMock,
+}));
+
+// Annotated rather than cast so a new required `Logger` member breaks this file
+// instead of being silently absent. `vi.fn()` over `() => {}` keeps every call
+// assertable if a test ever needs to check what was logged.
+const makeLogger = (): Logger => ({
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+});
 
 beforeEach(() => {
   recordInitialInstallFailureMock.mockClear();
   recordUpgradeFailureMock.mockClear();
+  flushMock.mockClear();
+  shutdownTelemetryMock.mockReset();
+  shutdownTelemetryMock.mockImplementation(async () => true);
 });
 
 describe("handleStartupError", () => {
   it("records + does NOT exit for InitialInstallFailed", () => {
-    const status = { serverErrors: [] as any[] };
+    const status: DevServerStatus = { serverErrors: [] };
     const marker = new InitialInstallFailed({
       type: "dev-server/dependency-install",
       timestamp: "t",
@@ -51,7 +82,7 @@ describe("handleStartupError", () => {
   });
 
   it("emits the install-failure metric with category on the degrade path", () => {
-    const status = { serverErrors: [] as any[] };
+    const status: DevServerStatus = { serverErrors: [] };
     const marker = new InitialInstallFailed({
       type: "dev-server/dependency-install",
       timestamp: "t",
@@ -70,13 +101,13 @@ describe("handleStartupError", () => {
   });
 
   it("does NOT emit the install-failure metric on the exit path", () => {
-    const status = { serverErrors: [] as any[] };
+    const status: DevServerStatus = { serverErrors: [] };
     handleStartupError(new Error("lock failed"), status, makeLogger());
     expect(recordInitialInstallFailureMock).not.toHaveBeenCalled();
   });
 
   it("exits for a non-marker error (lock / sync / genuinely-unusable upgrade env)", () => {
-    const status = { serverErrors: [] as any[] };
+    const status: DevServerStatus = { serverErrors: [] };
     const decision = handleStartupError(
       new Error("lock failed"),
       status,
@@ -86,8 +117,164 @@ describe("handleStartupError", () => {
     expect(status.serverErrors).toHaveLength(0);
   });
 
+  // ENG-5297: in a disposable cloud sandbox the upgrade is an in-place
+  // `npm install` into the *live* node_modules, and the install manifest
+  // includes esbuild. A failed upgrade therefore kills the running esbuild
+  // service ("The service was stopped"), rejecting vitePromise — so
+  // "keep the current version" preserves a process that can no longer serve
+  // anything. Exiting hands the pod to SABS, which already reaps terminal pods
+  // (RestartPolicy: Never), instead of leaving a zombie answering 500s.
+  it("exits for UpgradeFailed in a disposable sandbox (live tree may be tainted)", () => {
+    const status: DevServerStatus = { serverErrors: [] };
+    const marker = new UpgradeFailed({
+      type: "dev-server/dependency-upgrade",
+      timestamp: "t",
+      category: "unknown",
+      currentVersion: "2.0.148",
+      targetVersion: "2.0.149",
+      rawError: "dependency upgrade failed (unknown)",
+    });
+    const decision = handleStartupError(marker, status, makeLogger(), {
+      disposableSandbox: true,
+    });
+    expect(decision).toBe("exit");
+    // The failure is still recorded so the exit is observable, not silent.
+    expect(status.serverErrors).toHaveLength(1);
+    // `outcome` distinguishes an exiting pod from one that merely degraded —
+    // without it a crash loop is indistinguishable from a quietly-degraded
+    // fleet.
+    expect(recordUpgradeFailureMock).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "exit" }),
+    );
+    // `record()` and `flush()` gate on the same `isTelemetryInitialized()`
+    // check with nothing async in between, so a `flush()` here can never drain
+    // the sample recorded a line earlier. The caller's `shutdownTelemetry()`
+    // is what actually forces the export.
+    expect(flushMock).not.toHaveBeenCalled();
+  });
+
+  // ENG-5336: exiting is the right call only when the failure could have
+  // mutated the on-disk tree. npm resolves the whole graph before it extracts
+  // anything, so a registry that refused/never answered the metadata fetch
+  // provably left `node_modules` — and the running esbuild service — untouched.
+  // These are also exactly the failures a registry outage produces, so exiting
+  // on them would take out every live-edit pod in the fleet at once, replacing
+  // them with pods that hit the same outage.
+  const RESOLUTION_PHASE_CATEGORIES = [
+    "not_in_registry",
+    "registry_auth_failed",
+    "registry_unreachable",
+    "tls_failed",
+  ] as const;
+
+  // Every category the union names: the resolution-phase four plus the
+  // conservative default. Annotated rather than `as const` because a spread into
+  // a fresh literal widens `"unknown"` to `string` otherwise, which would take
+  // the type checking off `upgradeMarker` at the `it.each` below.
+  const ALL_UPGRADE_CATEGORIES: readonly DependencyUpgradeError["category"][] =
+    [...RESOLUTION_PHASE_CATEGORIES, "unknown"];
+
+  // Typing the parameter (rather than casting inside) is what keeps the
+  // `it.each` tables below checked end to end: a category added to either array
+  // that the marker cannot carry is a compile error, not a silent `any`.
+  const upgradeMarker = (category: DependencyUpgradeError["category"]) =>
+    new UpgradeFailed({
+      type: "dev-server/dependency-upgrade",
+      timestamp: "t",
+      category,
+      currentVersion: "2.0.148",
+      targetVersion: "2.0.149",
+      rawError: `dependency upgrade failed (${category})`,
+    });
+
+  it.each(RESOLUTION_PHASE_CATEGORIES)(
+    "degrades in a disposable sandbox for the resolution-phase category '%s'",
+    (category) => {
+      const status: DevServerStatus = { serverErrors: [] };
+      const decision = handleStartupError(
+        upgradeMarker(category),
+        status,
+        makeLogger(),
+        { disposableSandbox: true },
+      );
+      expect(decision).toBe("degrade");
+      expect(status.serverErrors).toHaveLength(1);
+      expect(recordUpgradeFailureMock).toHaveBeenCalledWith(
+        expect.objectContaining({ category, outcome: "degrade" }),
+      );
+    },
+  );
+
+  it("still exits in a disposable sandbox for an unclassified failure", () => {
+    // ENG-5297 arrived as `category: "unknown"` — the conservative default
+    // must keep exiting, or this PR's whole reason for existing is undone.
+    const status: DevServerStatus = { serverErrors: [] };
+    expect(
+      handleStartupError(upgradeMarker("unknown"), status, makeLogger(), {
+        disposableSandbox: true,
+      }),
+    ).toBe("exit");
+  });
+
+  it.each(ALL_UPGRADE_CATEGORIES)(
+    "degrades on a developer machine regardless of category ('%s')",
+    (category) => {
+      const status: DevServerStatus = { serverErrors: [] };
+      expect(
+        handleStartupError(upgradeMarker(category), status, makeLogger(), {
+          disposableSandbox: false,
+        }),
+      ).toBe("degrade");
+      expect(recordUpgradeFailureMock).toHaveBeenCalledWith(
+        expect.objectContaining({ outcome: "degrade" }),
+      );
+    },
+  );
+
+  describe("upgradeCategoryCouldTaintTree", () => {
+    it.each(RESOLUTION_PHASE_CATEGORIES)(
+      "reports '%s' as unable to have touched the tree",
+      (category) => {
+        expect(upgradeCategoryCouldTaintTree(category)).toBe(false);
+      },
+    );
+
+    it("defaults to 'could have tainted' for an unclassified failure", () => {
+      expect(upgradeCategoryCouldTaintTree("unknown")).toBe(true);
+    });
+
+    it("defaults to 'could have tainted' for a category it has never seen", () => {
+      // Conservative default: a future category must fail closed (exit), not
+      // silently inherit the degrade path. `string` is the real runtime contract
+      // here, since the payload crosses the socket — a category outside today's
+      // union cannot be put on an `UpgradeFailed` marker without an `as` cast,
+      // which is why this function takes the category rather than the marker.
+      expect(upgradeCategoryCouldTaintTree("brand_new")).toBe(true);
+    });
+  });
+
+  it("labels the degrade outcome and does not force a flush", () => {
+    const status: DevServerStatus = { serverErrors: [] };
+    const marker = new UpgradeFailed({
+      type: "dev-server/dependency-upgrade",
+      timestamp: "t",
+      category: "unknown",
+      currentVersion: "2.0.148",
+      targetVersion: "2.0.149",
+      rawError: "x",
+    });
+    handleStartupError(marker, status, makeLogger(), {
+      disposableSandbox: false,
+    });
+    expect(recordUpgradeFailureMock).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "degrade" }),
+    );
+    // A surviving process reaches the next export tick on its own.
+    expect(flushMock).not.toHaveBeenCalled();
+  });
+
   it("records + does NOT exit for UpgradeFailed (best-effort upgrade degrades)", () => {
-    const status = { serverErrors: [] as any[] };
+    const status: DevServerStatus = { serverErrors: [] };
     const marker = new UpgradeFailed({
       type: "dev-server/dependency-upgrade",
       timestamp: "t",
@@ -105,8 +292,145 @@ describe("handleStartupError", () => {
       category: "not_in_registry",
       npmErrorCode: "ETARGET",
       hasAnyRegistryConfigured: true,
+      outcome: "degrade",
     });
     // The upgrade failure must not be miscounted as an initial-install failure.
     expect(recordInitialInstallFailureMock).not.toHaveBeenCalled();
   });
 });
+
+// ENG-5336: the two fatal-exit blocks in `dev()` depend on teardown steps that
+// each talk to something that can fail or stop answering. Losing the lock
+// release means the replacement sandbox's `acquireLock()` gets a ConflictError
+// until the server-side TTL expires — and the replacement is the entire reason
+// the exit path exists. `runFatalExitShutdown` is the shared, exported sequence
+// those blocks call, so these are the guarantees the exit story rests on.
+describe("runFatalExitShutdown", () => {
+  const stepTimeoutMs = 5000;
+
+  it("runs the steps in order: cache removal, then lock release", async () => {
+    const calls: string[] = [];
+    await runFatalExitShutdown({
+      logger: makeLogger(),
+      removeIntegrationCache: async () => {
+        calls.push("cache");
+      },
+      shutdownLockService: async () => {
+        calls.push("lock");
+      },
+    });
+    expect(calls).toEqual(["cache", "lock"]);
+  });
+
+  it("still releases the lock when cache removal rejects", async () => {
+    const shutdownLockService = vi.fn(async () => {});
+    await expect(
+      runFatalExitShutdown({
+        logger: makeLogger(),
+        removeIntegrationCache: async () => {
+          throw new Error("ai-service IPC is gone");
+        },
+        shutdownLockService,
+      }),
+    ).resolves.toBeUndefined();
+    expect(shutdownLockService).toHaveBeenCalledOnce();
+  });
+
+  it("still releases the lock when cache removal throws synchronously", async () => {
+    const shutdownLockService = vi.fn(async () => {});
+    await runFatalExitShutdown({
+      logger: makeLogger(),
+      removeIntegrationCache: () => {
+        throw new Error("sync boom");
+      },
+      shutdownLockService,
+    });
+    expect(shutdownLockService).toHaveBeenCalledOnce();
+  });
+
+  it("never rejects when the lock release itself rejects", async () => {
+    await expect(
+      runFatalExitShutdown({
+        logger: makeLogger(),
+        shutdownLockService: async () => {
+          throw new Error("lock server unreachable");
+        },
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("tolerates absent services (no ai-service / no lock service)", async () => {
+    await expect(
+      runFatalExitShutdown({ logger: makeLogger() }),
+    ).resolves.toBeUndefined();
+  });
+
+  // The hang is the ENG-5297 symptom itself: an unsettled await above the
+  // `finally { process.exit(1) }` leaves the pod Ready but zombied forever.
+  it("abandons a step that never settles and still runs the later steps", async () => {
+    vi.useFakeTimers();
+    try {
+      const shutdownLockService = vi.fn(async () => {});
+      const settled = vi.fn();
+      const done = runFatalExitShutdown({
+        logger: makeLogger(),
+        removeIntegrationCache: () => new Promise<void>(() => {}),
+        shutdownLockService,
+      }).then(settled);
+
+      await vi.advanceTimersByTimeAsync(stepTimeoutMs - 1);
+      expect(shutdownLockService).not.toHaveBeenCalled();
+
+      await vi.advanceTimersByTimeAsync(2);
+      await done;
+      expect(shutdownLockService).toHaveBeenCalledOnce();
+      expect(settled).toHaveBeenCalledOnce();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+// Shared by the fatal-exit sequence above and the auto-upgrade CLI restart in
+// `dev()`. It used to be duplicated at the restart site, and the copy never
+// cleared its timeout timer — an armed 3s timer holds the event loop open for
+// any caller that does not immediately `process.exit`.
+describe("flushTelemetryWithTimeout", () => {
+  const flushTimeoutMs = 3000;
+
+  it("reports a completed flush and leaves no armed timer behind", async () => {
+    vi.useFakeTimers();
+    try {
+      await expect(flushTelemetryWithTimeout()).resolves.toBe(true);
+      expect(vi.getTimerCount()).toBe(0);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("reports a flush that did not run (telemetry never initialized)", async () => {
+    shutdownTelemetryMock.mockImplementation(async () => false);
+    await expect(flushTelemetryWithTimeout()).resolves.toBe(false);
+  });
+
+  // A stuck exporter must not wedge the exit: the timeout wins the race, the
+  // caller is told no flush happened, and the timer is still cleaned up.
+  it("gives up on a stuck exporter after the timeout and clears the timer", async () => {
+    vi.useFakeTimers();
+    try {
+      shutdownTelemetryMock.mockImplementation(
+        () => new Promise<boolean>(() => {}),
+      );
+      const pending = flushTelemetryWithTimeout();
+
+      await vi.advanceTimersByTimeAsync(flushTimeoutMs - 1);
+      expect(vi.getTimerCount()).toBe(1);
+
+      await vi.advanceTimersByTimeAsync(2);
+      await expect(pending).resolves.toBe(false);
+      expect(vi.getTimerCount()).toBe(0);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});