@superblocksteam/sdk 2.0.137-next.0 → 2.0.138-next.0

package/src/cli-replacement/package-json-snapshot.test.mts

@@ -11,6 +11,21 @@ import {
   restoreManagedPackageDependencies,
 } from "./package-json-snapshot.mjs";
 
+async function writeTempPackageJson(packageJson: unknown): Promise<string> {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "pkg-json-"));
+  await fs.writeFile(
+    path.join(tmpDir, "package.json"),
+    JSON.stringify(packageJson, null, 2) + "\n",
+  );
+  return tmpDir;
+}
+
+async function readTempPackageJson(tmpDir: string): Promise<any> {
+  return JSON.parse(
+    await fs.readFile(path.join(tmpDir, "package.json"), "utf-8"),
+  );
+}
+
 describe("packageJsonSnapshot", () => {
   it("is stable for object key order changes", () => {
     const before = packageJsonSnapshot({
@@ -248,3 +263,109 @@ describe("restoreManagedPackageDependencies", () => {
     }
   });
 });
+
+describe("restoreManagedPackageDependencies zod override", () => {
+  it("injects the warm template zod override into an app that has none", async () => {
+    const tmpDir = await writeTempPackageJson({
+      name: "restored-app",
+      dependencies: {
+        "@superblocksteam/sdk-api": "0.0.7",
+        ai: "6.0.97",
+      },
+    });
+
+    try {
+      const changed = await restoreManagedPackageDependencies(tmpDir, {
+        overrides: { zod: "3.25.76" },
+      });
+
+      expect(changed).toBe(true);
+      const restored = await readTempPackageJson(tmpDir);
+      expect(restored.overrides?.zod).toBe("3.25.76");
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not inject a zod override when the warm template omits it", async () => {
+    const tmpDir = await writeTempPackageJson({
+      name: "restored-app",
+      dependencies: {
+        "@superblocksteam/sdk-api": "0.0.7",
+        ai: "6.0.97",
+      },
+    });
+
+    try {
+      const changed = await restoreManagedPackageDependencies(tmpDir, {
+        dependencies: { "@superblocksteam/sdk-api": "0.0.7" },
+      });
+
+      expect(changed).toBe(false);
+      const restored = await readTempPackageJson(tmpDir);
+      expect(restored.overrides).toBeUndefined();
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("preserves unrelated overrides while enforcing the zod override", async () => {
+    const tmpDir = await writeTempPackageJson({
+      name: "restored-app",
+      dependencies: { ai: "6.0.97" },
+      overrides: { lodash: "4.17.21" },
+    });
+
+    try {
+      await restoreManagedPackageDependencies(tmpDir, {
+        overrides: { zod: "3.25.76" },
+      });
+
+      const restored = await readTempPackageJson(tmpDir);
+      expect(restored.overrides).toEqual({
+        lodash: "4.17.21",
+        zod: "3.25.76",
+      });
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("overwrites a stale app zod override with the managed version", async () => {
+    const tmpDir = await writeTempPackageJson({
+      name: "restored-app",
+      dependencies: { ai: "6.0.97" },
+      overrides: { zod: "3.23.8" },
+    });
+
+    try {
+      const changed = await restoreManagedPackageDependencies(tmpDir, {
+        overrides: { zod: "3.25.76" },
+      });
+
+      expect(changed).toBe(true);
+      const restored = await readTempPackageJson(tmpDir);
+      expect(restored.overrides?.zod).toBe("3.25.76");
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not rewrite when the zod override already matches", async () => {
+    const tmpDir = await writeTempPackageJson({
+      name: "restored-app",
+      dependencies: { ai: "6.0.97" },
+      overrides: { zod: "3.25.76" },
+    });
+
+    try {
+      const changed = await restoreManagedPackageDependencies(tmpDir, {
+        overrides: { zod: "3.25.76" },
+      });
+
+      expect(changed).toBe(false);
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -403,27 +403,32 @@ class DevServerMetrics {
   }
 
   /**
-   * Records a degraded startup caused by a failed initial dependency install.
+   * Emits a dependency-failure counter with the standard low-cardinality tags.
+   * Shared by the initial-install and auto-upgrade degrade paths, which differ
+   * only in counter name + description.
    *
    * All tags are low-cardinality:
-   *   - `category`  is a closed enum from DependencyInstallError (safe).
+   *   - `category` is a closed enum from the matching error type.
    *   - `npm_error_code` is a bounded npm error code string (e.g. "E401",
    *     "ERESOLVE") or `"none"` when absent.
-   *   - `has_any_registry_configured` is a boolean string (`"true"` /
-   *     `"false"`) or `"unknown"` when the tri-state is undefined.
+   *   - `has_any_registry_configured` is `"true"` / `"false"` / `"unknown"`.
    *
-   * Do NOT pass raw package names, registry hostnames, or rawError — those
-   * are high-cardinality or contain customer-infra identifiers.
+   * Do NOT pass raw package names, registry hostnames, or rawError — those are
+   * high-cardinality or contain customer-infra identifiers.
    */
-  recordInitialInstallFailure({
-    category,
-    npmErrorCode,
-    hasAnyRegistryConfigured,
-  }: {
-    category: string;
-    npmErrorCode?: string;
-    hasAnyRegistryConfigured?: boolean;
-  }): void {
+  private recordDependencyFailure(
+    counterName: string,
+    description: string,
+    {
+      category,
+      npmErrorCode,
+      hasAnyRegistryConfigured,
+    }: {
+      category: string;
+      npmErrorCode?: string;
+      hasAnyRegistryConfigured?: boolean;
+    },
+  ): void {
     const labels = {
       category,
       npm_error_code: normalizeNpmErrorCodeTag(npmErrorCode),
@@ -433,15 +438,37 @@ class DevServerMetrics {
           : String(hasAnyRegistryConfigured),
     };
     this.record(() => {
-      getMeter()
-        .createCounter("dev_server_initial_install_failure_total", {
-          description:
-            "Count of degraded dev-server startups caused by a failed initial dependency install.",
-        })
-        .add(1, labels);
+      getMeter().createCounter(counterName, { description }).add(1, labels);
     });
   }
 
+  /** Records a degraded startup caused by a failed initial dependency install. */
+  recordInitialInstallFailure(labels: {
+    category: string;
+    npmErrorCode?: string;
+    hasAnyRegistryConfigured?: boolean;
+  }): void {
+    this.recordDependencyFailure(
+      "dev_server_initial_install_failure_total",
+      "Count of degraded dev-server startups caused by a failed initial dependency install.",
+      labels,
+    );
+  }
+
+  /** Records a degraded startup where a best-effort CLI/library auto-upgrade
+   *  failed and the pod kept serving the currently installed version. */
+  recordUpgradeFailure(labels: {
+    category: string;
+    npmErrorCode?: string;
+    hasAnyRegistryConfigured?: boolean;
+  }): void {
+    this.recordDependencyFailure(
+      "dev_server_auto_upgrade_failure_total",
+      "Count of degraded dev-server startups where a best-effort CLI/library auto-upgrade failed and the pod kept the current version.",
+      labels,
+    );
+  }
+
   /**
    * Records a recoverable shutdown error that was suppressed (logged at warn,
    * process left alive) instead of triggering a fatal exit. This is the

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

@@ -70,6 +70,7 @@ import {
   isRecoverableShutdownError,
   parseIsWarm,
 } from "./fatal-exit.mjs";
+import { prepareInPlaceRestart } from "./prepare-in-place-restart.mjs";
 import {
   formatViteDevServerStartedLog,
   logViteBuildError,
@@ -727,6 +728,22 @@ export async function createDevServer({
     }
   }
 
+  const runPrepareInPlaceRestart = async (options?: { flipRestart?: true }) => {
+    logger.info(
+      options?.flipRestart
+        ? "Pausing dev server while restarting after template flip"
+        : "Pausing dev server while restarting",
+    );
+    await prepareInPlaceRestart(
+      {
+        aiService,
+        closeViteServer,
+        lockService,
+      },
+      { flipRestart: options?.flipRestart, logger },
+    );
+  };
+
   async function runGracefulShutdown({
     logger,
     serverInitiated,
@@ -1018,11 +1035,7 @@ export async function createDevServer({
 
     try {
       if (isRestart) {
-        logger.info("Pausing dev server while restarting");
-        lockService?.setIsRestarting();
-        // Invalidate chat session cache to reload fresh chat messages after checkpoint restore
-        aiService?.chatSessionStore.invalidateCache();
-        await closeViteServer();
+        await runPrepareInPlaceRestart();
         res.send("ok");
         // RESTART_EXIT_CODE tells the supervisor to respawn, and this runs
         // synchronously below (no await), so the next /_sb_connect is served by
@@ -1347,6 +1360,7 @@ export async function createDevServer({
       logger: loggerOverride,
       httpServer,
       superblocksBaseUrl: explicitBaseUrl || localToken?.superblocksBaseUrl,
+      prepareInPlaceRestart: runPrepareInPlaceRestart,
       features: {
         enableSessionRecording: featureFlags?.enableSessionRecording() ?? false,
         // Gate the in-place restart on the LD flag OR the env escape hatch
@@ -1420,6 +1434,7 @@ async function startVite({
   logger: loggerOverride,
   superblocksBaseUrl,
   features,
+  prepareInPlaceRestart,
 }: CreateDevServerOptions & {
   app: express.Express;
   httpServer: http.Server;
@@ -1428,6 +1443,7 @@ async function startVite({
     enableSessionRecording: boolean;
     inPlaceTemplateRestartEnabled: boolean;
   };
+  prepareInPlaceRestart: (options?: { flipRestart?: true }) => Promise<void>;
 }): Promise<{
   viteServer: ViteDevServer;
   dispose: () => void;
@@ -1509,6 +1525,7 @@ async function startVite({
           superblocksBaseUrl,
           appRootDir: root,
           features,
+          prepareInPlaceRestart,
         } as FileSyncPluginParams,
         { isCustomBuildEnabled },
       );

package/src/dev-utils/prepare-in-place-restart.mts

@@ -0,0 +1,99 @@
+import { RESTART_REASON_FLIP_RESTART } from "@superblocksteam/library-shared/restart-contract";
+
+/** Upper bound on the pre-exit IPC handshake to the parent supervisor. */
+const RESTART_REASON_IPC_TIMEOUT_MS = 1000;
+
+export interface PrepareInPlaceRestartLogger {
+  warn(message: string, meta?: Record<string, unknown>): void;
+}
+
+export interface PrepareInPlaceRestartServices {
+  aiService?: {
+    chatSessionStore: { invalidateCache(): void };
+  };
+  closeViteServer?: () => Promise<void>;
+  lockService?: {
+    setIsRestarting(): void | Promise<void>;
+  };
+}
+
+export interface PrepareInPlaceRestartOptions {
+  flipRestart?: true;
+  logger?: PrepareInPlaceRestartLogger;
+}
+
+/**
+ * Tell the CLI parent supervisor that the imminent `RESTART_EXIT_CODE` exit is a
+ * template flip — not the editor-driven `/_sb_disconnect` restart, which shares
+ * the same exit code.
+ */
+export async function announceFlipRestartToParent(
+  logger?: PrepareInPlaceRestartLogger,
+): Promise<void> {
+  const send = process.send;
+  if (!send) {
+    return;
+  }
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = (): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve();
+    };
+    const timer = setTimeout(finish, RESTART_REASON_IPC_TIMEOUT_MS);
+    timer.unref?.();
+    const done = (): void => {
+      clearTimeout(timer);
+      finish();
+    };
+    try {
+      send.call(
+        process,
+        { type: "restartReason", reason: RESTART_REASON_FLIP_RESTART },
+        (error: Error | null) => {
+          if (error) {
+            logger?.warn(
+              "Failed to notify parent of flip restart reason; restart will surface as cold_start",
+              { error: error.message },
+            );
+          }
+          done();
+        },
+      );
+    } catch (error) {
+      logger?.warn(
+        "Failed to notify parent of flip restart reason; restart will surface as cold_start",
+        {
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+      done();
+    }
+  });
+}
+
+/**
+ * Shared teardown before an in-place dev-server restart (`process.exit(98)`).
+ * Used by `/_sb_disconnect` with `isRestart: true` and by the migration
+ * self-restart seam after a template flip.
+ */
+export async function prepareInPlaceRestart(
+  services: PrepareInPlaceRestartServices,
+  options?: PrepareInPlaceRestartOptions,
+): Promise<void> {
+  if (services.lockService) {
+    await services.lockService.setIsRestarting();
+  }
+  if (services.aiService?.chatSessionStore) {
+    services.aiService.chatSessionStore.invalidateCache();
+  }
+  if (options?.flipRestart) {
+    await announceFlipRestartToParent(options.logger);
+  }
+  if (services.closeViteServer) {
+    await services.closeViteServer();
+  }
+}

package/src/dev-utils/prepare-in-place-restart.test.mts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  announceFlipRestartToParent,
+  prepareInPlaceRestart,
+} from "./prepare-in-place-restart.mjs";
+
+describe("prepareInPlaceRestart", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("sets restarting, invalidates AI cache, and closes Vite when services are present", async () => {
+    const setIsRestarting = vi.fn();
+    const invalidateCache = vi.fn();
+    const closeViteServer = vi.fn(async () => {});
+
+    await prepareInPlaceRestart({
+      lockService: { setIsRestarting },
+      aiService: { chatSessionStore: { invalidateCache } },
+      closeViteServer,
+    });
+
+    expect(setIsRestarting).toHaveBeenCalledTimes(1);
+    expect(invalidateCache).toHaveBeenCalledTimes(1);
+    expect(closeViteServer).toHaveBeenCalledTimes(1);
+  });
+
+  it("announces flip restart to parent when flipRestart is set", async () => {
+    const send = vi.fn(
+      (_msg: unknown, cb: (err: Error | null) => void): boolean => {
+        cb(null);
+        return true;
+      },
+    );
+    process.send = send as unknown as typeof process.send;
+
+    await prepareInPlaceRestart(
+      {},
+      { flipRestart: true, logger: { warn: vi.fn() } },
+    );
+
+    expect(send).toHaveBeenCalledWith(
+      { type: "restartReason", reason: "flip_restart" },
+      expect.any(Function),
+    );
+  });
+
+  it("does not announce flip restart without flipRestart option", async () => {
+    const send = vi.fn(() => true);
+    process.send = send as unknown as typeof process.send;
+
+    await prepareInPlaceRestart({});
+
+    expect(send).not.toHaveBeenCalled();
+  });
+});
+
+describe("announceFlipRestartToParent", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    process.send = undefined;
+  });
+
+  it("no-ops when process.send is absent", async () => {
+    process.send = undefined;
+    await announceFlipRestartToParent();
+  });
+});

package/src/telemetry/index.ts

@@ -79,16 +79,30 @@ export const deploymentType = (() => {
  */
 export const isCloudPrem = deploymentType === DeploymentTypeEnum.CLOUD_PREM;
 
-async function shutdownTelemetry(): Promise<void> {
-  if (isTelemetryInitialized()) {
-    try {
-      await getTelemetryInstance().shutdown();
-    } catch (error) {
-      console.error("Error during telemetry shutdown:", error);
-    } finally {
-      resetTelemetry();
-      configured = false;
-    }
+/**
+ * Shut down telemetry, forcing a final flush of all buffered traces, metrics,
+ * and logs (via `sdk.shutdown()` → the metric reader's force-flush).
+ *
+ * Never rejects: shutdown errors are caught and logged internally. Returns
+ * `true` only when a flush actually ran to completion; `false` when telemetry
+ * was never initialized (nothing to flush) or `sdk.shutdown()` threw (the
+ * export may not have completed). Callers can use the return value to report
+ * whether buffered samples were really flushed — any `try/catch` around it is
+ * purely defensive.
+ */
+export async function shutdownTelemetry(): Promise<boolean> {
+  if (!isTelemetryInitialized()) {
+    return false;
+  }
+  try {
+    await getTelemetryInstance().shutdown();
+    return true;
+  } catch (error) {
+    console.error("Error during telemetry shutdown:", error);
+    return false;
+  } finally {
+    resetTelemetry();
+    configured = false;
   }
 }