@superblocksteam/sdk 2.0.110 → 2.0.111

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

@@ -0,0 +1,251 @@
+/**
+ * Tests for checkVersionsAndWritePackageJson, specifically around the
+ * skipCliUpgrade parameter introduced for warm pool activation.
+ *
+ * Warm pods ship with the latest CLI, so an auto-upgrade would pointlessly
+ * restart the process and defeat the warm pool. But we still need the
+ * package.json version sync when resuming an existing app so the user's
+ * @superblocksteam/library pin matches the target version.
+ */
+
+import fs from "node:fs/promises";
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+import { checkVersionsAndWritePackageJson } from "./automatic-upgrades.js";
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+vi.mock("node:fs/promises", () => ({
+  default: {
+    readFile: vi.fn(),
+    writeFile: vi.fn(),
+  },
+}));
+
+vi.mock("node:child_process", () => ({
+  exec: vi.fn(),
+}));
+
+const upgradeWithPackageManagerCalls: unknown[] = [];
+vi.mock("package-manager-detector/detect", () => ({
+  detect: vi.fn(async () => ({
+    name: "pnpm",
+    agent: "pnpm",
+    version: "10.0.0",
+  })),
+}));
+
+vi.mock("package-manager-detector", () => ({
+  resolveCommand: vi.fn(() => ({ command: "pnpm", args: ["install"] })),
+}));
+
+vi.mock("./version-detection.js", () => ({
+  getCurrentCliVersion: vi.fn(async () => ({
+    version: "2.0.0",
+    alias: undefined,
+  })),
+  clearCliVersionCache: vi.fn(),
+}));
+
+vi.mock("../telemetry/logging.js", () => ({
+  getLogger: () => ({
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  }),
+  getErrorMeta: vi.fn(() => ({})),
+}));
+
+vi.mock("../telemetry/index.js", () => ({
+  getTracer: () => ({
+    startActiveSpan: vi.fn((_name, fn) => fn({ end: vi.fn() })),
+  }),
+}));
+
+vi.mock("@superblocksteam/shared", async () => {
+  return {
+    NON_SB_ORG_UPDATE_ERROR: "non_sb_org_update_error",
+    // traceFunction in tests is a passthrough — we just want the fn to run.
+    traceFunction: async ({ fn }: { fn: () => Promise<unknown> }) => {
+      return await fn();
+    },
+  };
+});
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+const TARGET_CLI_VERSION = "2.1.0"; // newer than the mocked current 2.0.0
+const TARGET_LIBRARY_VERSION = "1.9.0";
+
+const mockLockService = {
+  shutdown: vi.fn(async () => undefined),
+} as unknown as Parameters<typeof checkVersionsAndWritePackageJson>[0];
+
+const mockConfig: Parameters<typeof checkVersionsAndWritePackageJson>[1] = {
+  id: "app-123",
+  branchName: "main",
+  superblocksBaseUrl: "https://example.test",
+  token: "test-token",
+  userId: "user-1",
+  userEmail: "test@example.com",
+  organizationId: "org-1",
+  featureFlags: {},
+} as unknown as Parameters<typeof checkVersionsAndWritePackageJson>[1];
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  upgradeWithPackageManagerCalls.length = 0;
+
+  // Mock global fetch used by getRemoteVersions
+  global.fetch = vi.fn(async () => ({
+    ok: true,
+    json: async () => ({
+      data: {
+        cli: TARGET_CLI_VERSION,
+        library: TARGET_LIBRARY_VERSION,
+      },
+    }),
+  })) as unknown as typeof fetch;
+
+  // Default package.json content
+  vi.mocked(fs.readFile).mockResolvedValue(
+    JSON.stringify({
+      name: "test-app",
+      dependencies: {
+        "@superblocksteam/library": "1.0.0",
+      },
+    }),
+  );
+  vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("checkVersionsAndWritePackageJson", () => {
+  describe("skipCliUpgrade=true (warm pool activation)", () => {
+    it("still writes package.json with the target library version", async () => {
+      await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false, // forceUpgrade
+        true, // skipCliUpgrade — the warm pool case
+      );
+
+      expect(fs.writeFile).toHaveBeenCalledTimes(1);
+      const [, writtenContent] = vi.mocked(fs.writeFile).mock.calls[0];
+      const parsed = JSON.parse(writtenContent as string);
+      expect(parsed.dependencies["@superblocksteam/library"]).toBe(
+        TARGET_LIBRARY_VERSION,
+      );
+    });
+
+    it("does NOT call the oclif CLI upgrader even when CLI is stale", async () => {
+      const { exec } = await import("node:child_process");
+      // If an upgrade were attempted, upgradeCliWithOclif would exec
+      // `which superblocks`. We assert that does not happen.
+
+      await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        true,
+      );
+
+      expect(exec).not.toHaveBeenCalled();
+    });
+
+    it("returns cliUpdated=false regardless of CLI version gap", async () => {
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        true,
+      );
+
+      expect(result.cliUpdated).toBe(false);
+    });
+
+    it("skipCliUpgrade overrides forceUpgrade", async () => {
+      const { exec } = await import("node:child_process");
+
+      await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        true, // forceUpgrade — should be overridden by skipCliUpgrade
+        true, // skipCliUpgrade wins
+      );
+
+      expect(exec).not.toHaveBeenCalled();
+      // But package.json still gets written
+      expect(fs.writeFile).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("skipCliUpgrade=false (default)", () => {
+    it("writes package.json with the target library version", async () => {
+      await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+
+      expect(fs.writeFile).toHaveBeenCalledTimes(1);
+      const [, writtenContent] = vi.mocked(fs.writeFile).mock.calls[0];
+      const parsed = JSON.parse(writtenContent as string);
+      expect(parsed.dependencies["@superblocksteam/library"]).toBe(
+        TARGET_LIBRARY_VERSION,
+      );
+    });
+
+    it("defaults to false when omitted (backward compat)", async () => {
+      // 3-arg call (pre-warm-pool signature) should behave as skipCliUpgrade=false
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+      );
+
+      // Still writes package.json
+      expect(fs.writeFile).toHaveBeenCalledTimes(1);
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe("SNAPSHOT library versions", () => {
+    it("pins to ephemeral alias when library target is a SNAPSHOT", async () => {
+      const snapshotVersion = "1.9.0-SNAPSHOT.abc123";
+      global.fetch = vi.fn(async () => ({
+        ok: true,
+        json: async () => ({
+          data: {
+            cli: TARGET_CLI_VERSION,
+            library: snapshotVersion,
+          },
+        }),
+      })) as unknown as typeof fetch;
+
+      await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        true, // warm pool
+      );
+
+      expect(fs.writeFile).toHaveBeenCalledTimes(1);
+      const [, writtenContent] = vi.mocked(fs.writeFile).mock.calls[0];
+      const parsed = JSON.parse(writtenContent as string);
+      expect(parsed.dependencies["@superblocksteam/library"]).toBe(
+        `npm:@superblocksteam/library-ephemeral@${snapshotVersion}`,
+      );
+    });
+  });
+});

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

@@ -181,6 +181,7 @@ export async function checkVersionsAndWritePackageJson(
   lockService: LockService,
   config: ApplicationConfigWithTokenConfigAndUserInfo,
   forceUpgrade: boolean = false,
+  skipCliUpgrade: boolean = false,
 ): Promise<{
   cliUpdated: boolean;
   upgradePromises: Promise<void>[];
@@ -269,7 +270,11 @@ export async function checkVersionsAndWritePackageJson(
       }
 
       try {
-        if ((cliNeedsUpgrade || forceUpgrade) && currentCliInfo) {
+        if (
+          !skipCliUpgrade &&
+          (cliNeedsUpgrade || forceUpgrade) &&
+          currentCliInfo
+        ) {
           const cliUpgradePromise = traceFunction({
             name: "upgradeCli",
             tracer,

package/src/cli-replacement/dev.mts

@@ -1,5 +1,6 @@
 import * as child_process from "node:child_process";
 import * as nodeFs from "node:fs/promises";
+import type { Server as HttpServer } from "node:http";
 import path from "node:path";
 import * as readline from "node:readline";
 import { promisify } from "node:util";
@@ -248,6 +249,14 @@ async function installPackages(cwd: string, logger: Logger) {
 export enum DevServerAutoUpgradeMode {
   SKIP = "skip-upgrade",
   FORCE = "force-upgrade",
+  /**
+   * Skip CLI auto-upgrade but still run the package.json version sync.
+   * Used by warm pool activation — the warm pod ships with the latest CLI
+   * so an auto-upgrade would pointlessly restart the process, but the user's
+   * application package.json still needs to be pinned to the target
+   * @superblocksteam/library version.
+   */
+  SKIP_CLI_ONLY = "skip-cli-only",
 }
 
 export async function dev(options: {
@@ -284,6 +293,9 @@ export async function dev(options: {
 
   /** Pre-fetched application data from the CLI validation step (avoids a duplicate network call). */
   prefetchedApplication?: MultiPageApplicationWrapper;
+
+  /** Pre-existing HTTP server from warm standby mode (avoids port gap on transition). */
+  existingServer?: HttpServer;
 }) {
   const {
     cwd,
@@ -311,6 +323,9 @@ export async function dev(options: {
   const tracer = getTracer();
   const logger = getLogger(options.logger);
   const skipAutoUpgrade = autoUpgradeMode === DevServerAutoUpgradeMode.SKIP;
+  const skipCliUpgrade =
+    skipAutoUpgrade ||
+    autoUpgradeMode === DevServerAutoUpgradeMode.SKIP_CLI_ONLY;
 
   await tracer.startActiveSpan("devServerStartup", async (startupSpan) => {
     try {
@@ -663,8 +678,13 @@ export async function dev(options: {
             let upgradePromises: Promise<void>[] = [];
             const forceUpgrade =
               options.autoUpgradeMode === DevServerAutoUpgradeMode.FORCE;
-            // Determine whether we must try to auto-upgrade the CLI
-            if (!skipAutoUpgrade || forceUpgrade) {
+            // Run version check when we haven't fully disabled auto-upgrades,
+            // when force is requested, or when only the CLI upgrade is skipped
+            // (warm pool still needs the package.json sync).
+            const skipCliOnly =
+              options.autoUpgradeMode ===
+              DevServerAutoUpgradeMode.SKIP_CLI_ONLY;
+            if (!skipAutoUpgrade || forceUpgrade || skipCliOnly) {
               await tracer.startActiveSpan(
                 "versionCheckAndUpgrade",
                 async (span) => {
@@ -684,6 +704,7 @@ export async function dev(options: {
                       lockService,
                       applicationConfigWithTokenConfigAndUserInfo,
                       forceUpgrade,
+                      skipCliUpgrade,
                     );
                     hasCliUpdated = result.cliUpdated;
                     upgradePromises = result.upgradePromises;
@@ -886,6 +907,10 @@ export async function dev(options: {
             logger: options.logger,
             sdk,
             superblocksBaseUrl: tokenConfig.superblocksBaseUrl,
+            existingServer: options.existingServer,
+            // TODO: Remove this cast — build the options object to match
+            // CreateDevServerOptions directly so new required fields cause a
+            // compile error instead of silently passing undefined.
           } as unknown as Parameters<typeof createDevServer>[0];
           const result = await createDevServer(createDevServerOptions);
           span.end();