@superblocksteam/sdk 2.0.82 → 2.0.83-next.1

package/src/cli-replacement/version-detection.test.ts

@@ -0,0 +1,336 @@
+/**
+ * Tests for CLI version detection with caching.
+ */
+
+import * as child_process from "node:child_process";
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import {
+  getCurrentCliVersion,
+  clearCliVersionCache,
+} from "./version-detection.js";
+
+// Mock child_process.exec and execFile
+vi.mock("node:child_process", () => ({
+  exec: vi.fn(),
+  execFile: vi.fn(),
+}));
+
+// Mock logger to suppress console output during tests
+vi.mock("../telemetry/logging.js", () => ({
+  getLogger: () => ({
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  }),
+}));
+
+describe("version-detection", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    // Reset environment and cache before each test
+    process.env = { ...originalEnv };
+    clearCliVersionCache(); // Clear cache
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    // Restore original environment
+    process.env = originalEnv;
+  });
+
+  describe("Docker/CSB environment", () => {
+    it("should read version from SUPERBLOCKS_CLI_VERSION env var", async () => {
+      process.env.SUPERBLOCKS_IS_CSB = "true";
+      process.env.SUPERBLOCKS_CLI_VERSION = "2.0.0-next.1";
+
+      const result = await getCurrentCliVersion();
+
+      expect(result).toEqual({
+        version: "2.0.0-next.1",
+        alias: undefined,
+      });
+      // Should not call subprocess
+      expect(child_process.exec).not.toHaveBeenCalled();
+    });
+
+    it("should detect ephemeral builds from SNAPSHOT in version", async () => {
+      process.env.SUPERBLOCKS_IS_CSB = "true";
+      process.env.SUPERBLOCKS_CLI_VERSION = "2.0.0-SNAPSHOT.ebd2b86d643331f5";
+
+      const result = await getCurrentCliVersion();
+
+      expect(result).toEqual({
+        version: "2.0.0-SNAPSHOT.ebd2b86d643331f5",
+        alias: "@superblocksteam/cli-ephemeral",
+      });
+      expect(child_process.exec).not.toHaveBeenCalled();
+    });
+
+    it("should fall back to subprocess if env var not set", async () => {
+      process.env.SUPERBLOCKS_IS_CSB = "true";
+      // No SUPERBLOCKS_CLI_VERSION set
+
+      // Mock subprocess calls
+      const execMock = child_process.exec as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      const execFileMock = child_process.execFile as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      execMock.mockImplementationOnce((_cmd, callback: any) => {
+        // which/where command
+        callback(null, { stdout: "/usr/local/bin/superblocks\n" });
+      });
+      execFileMock.mockImplementationOnce((_path, _args, callback: any) => {
+        // version command
+        callback(null, {
+          stdout: JSON.stringify({
+            cliVersion: "@superblocksteam/cli/2.0.0-next.1",
+          }),
+        });
+      });
+
+      const result = await getCurrentCliVersion();
+
+      expect(result).toEqual({
+        version: "2.0.0-next.1",
+      });
+      expect(child_process.exec).toHaveBeenCalledTimes(1);
+      expect(child_process.execFile).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("Local environment", () => {
+    beforeEach(() => {
+      process.env.SUPERBLOCKS_IS_CSB = "false";
+    });
+
+    it("should detect version via subprocess", async () => {
+      const execMock = child_process.exec as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      const execFileMock = child_process.execFile as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      execMock.mockImplementationOnce((_cmd, callback: any) => {
+        // which/where command
+        callback(null, { stdout: "/usr/local/bin/superblocks\n" });
+      });
+      execFileMock.mockImplementationOnce((_path, _args, callback: any) => {
+        // version command
+        callback(null, {
+          stdout: JSON.stringify({
+            cliVersion: "@superblocksteam/cli/2.0.0-next.1",
+          }),
+        });
+      });
+
+      const result = await getCurrentCliVersion();
+
+      expect(result).toEqual({
+        version: "2.0.0-next.1",
+      });
+      expect(child_process.exec).toHaveBeenCalledTimes(1);
+      expect(child_process.execFile).toHaveBeenCalledTimes(1);
+    });
+
+    it("should detect ephemeral builds with alias", async () => {
+      const execMock = child_process.exec as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      const execFileMock = child_process.execFile as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      execMock.mockImplementationOnce((_cmd, callback: any) => {
+        callback(null, { stdout: "/usr/local/bin/superblocks\n" });
+      });
+      execFileMock.mockImplementationOnce((_path, _args, callback: any) => {
+        callback(null, {
+          stdout: JSON.stringify({
+            cliVersion:
+              "@superblocksteam/cli-ephemeral/2.0.0-SNAPSHOT.ebd2b86d643331f5",
+          }),
+        });
+      });
+
+      const result = await getCurrentCliVersion();
+
+      expect(result).toEqual({
+        version: "2.0.0-SNAPSHOT.ebd2b86d643331f5",
+        alias: "@superblocksteam/cli-ephemeral",
+      });
+    });
+
+    it("should use Windows 'where' command on win32", async () => {
+      const originalPlatform = process.platform;
+      Object.defineProperty(process, "platform", {
+        value: "win32",
+        configurable: true,
+      });
+
+      try {
+        const execMock = child_process.exec as unknown as ReturnType<
+          typeof vi.fn
+        >;
+        const execFileMock = child_process.execFile as unknown as ReturnType<
+          typeof vi.fn
+        >;
+        execMock.mockImplementationOnce((cmd, callback: any) => {
+          expect(cmd).toContain("where superblocks");
+          callback(null, { stdout: "C:\\Program Files\\superblocks.exe\n" });
+        });
+        execFileMock.mockImplementationOnce((_path, _args, callback: any) => {
+          callback(null, {
+            stdout: JSON.stringify({
+              cliVersion: "@superblocksteam/cli/2.0.0-next.1",
+            }),
+          });
+        });
+
+        await getCurrentCliVersion();
+      } finally {
+        // Restore platform
+        Object.defineProperty(process, "platform", {
+          value: originalPlatform,
+          configurable: true,
+        });
+      }
+    });
+
+    it("should return undefined if CLI not found", async () => {
+      const execMock = child_process.exec as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      execMock.mockImplementationOnce((_cmd, callback: any) => {
+        callback(null, { stdout: "" }); // Empty output = not found
+      });
+
+      const result = await getCurrentCliVersion();
+
+      expect(result).toBeUndefined();
+      // Should only call which/where, not version command
+      expect(child_process.exec).toHaveBeenCalledTimes(1);
+    });
+
+    it("should return undefined on error", async () => {
+      const execMock = child_process.exec as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      execMock.mockImplementationOnce((_cmd, callback: any) => {
+        callback(new Error("Command not found"));
+      });
+
+      const result = await getCurrentCliVersion();
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("Caching behavior", () => {
+    beforeEach(() => {
+      process.env.SUPERBLOCKS_IS_CSB = "false";
+    });
+
+    it("should cache successful subprocess result", async () => {
+      const execMock = child_process.exec as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      const execFileMock = child_process.execFile as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      execMock.mockImplementationOnce((_cmd, callback: any) => {
+        callback(null, { stdout: "/usr/local/bin/superblocks\n" });
+      });
+      execFileMock.mockImplementationOnce((_path, _args, callback: any) => {
+        callback(null, {
+          stdout: JSON.stringify({
+            cliVersion: "@superblocksteam/cli/2.0.0-next.1",
+          }),
+        });
+      });
+
+      // First call - should execute subprocess
+      const result1 = await getCurrentCliVersion();
+      expect(result1).toEqual({ version: "2.0.0-next.1" });
+      expect(child_process.exec).toHaveBeenCalledTimes(1);
+      expect(child_process.execFile).toHaveBeenCalledTimes(1);
+
+      // Second call - should use cache
+      const result2 = await getCurrentCliVersion();
+      expect(result2).toEqual({ version: "2.0.0-next.1" });
+      expect(child_process.exec).toHaveBeenCalledTimes(1); // Still 1, not 2
+      expect(child_process.execFile).toHaveBeenCalledTimes(1); // Still 1, not 2
+    });
+
+    it("should cache Docker env var result", async () => {
+      process.env.SUPERBLOCKS_IS_CSB = "true";
+      process.env.SUPERBLOCKS_CLI_VERSION = "2.0.0-next.1";
+
+      // First call
+      const result1 = await getCurrentCliVersion();
+      expect(result1).toEqual({ version: "2.0.0-next.1", alias: undefined });
+
+      // Second call - should use cache
+      const result2 = await getCurrentCliVersion();
+      expect(result2).toEqual({ version: "2.0.0-next.1", alias: undefined });
+
+      expect(child_process.exec).not.toHaveBeenCalled();
+    });
+
+    it("should NOT cache failures (allows retry on transient errors)", async () => {
+      const execMock = child_process.exec as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      execMock
+        .mockImplementationOnce((_cmd, callback: any) => {
+          callback(new Error("Not found"));
+        })
+        .mockImplementationOnce((_cmd, callback: any) => {
+          callback(new Error("Still not found"));
+        });
+
+      // First call - should attempt detection and fail
+      const result1 = await getCurrentCliVersion();
+      expect(result1).toBeUndefined();
+      expect(child_process.exec).toHaveBeenCalledTimes(1);
+
+      // Second call - should retry (not cached) since failures aren't cached
+      const result2 = await getCurrentCliVersion();
+      expect(result2).toBeUndefined();
+      expect(child_process.exec).toHaveBeenCalledTimes(2); // Retried!
+    });
+
+    it("should re-detect after cache is cleared", async () => {
+      const execMock = child_process.exec as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      const execFileMock = child_process.execFile as unknown as ReturnType<
+        typeof vi.fn
+      >;
+      execMock.mockImplementation((_cmd, callback: any) => {
+        callback(null, { stdout: "/usr/local/bin/superblocks\n" });
+      });
+      execFileMock.mockImplementation((_path, _args, callback: any) => {
+        callback(null, {
+          stdout: JSON.stringify({
+            cliVersion: "@superblocksteam/cli/2.0.0-next.1",
+          }),
+        });
+      });
+
+      // First detection
+      await getCurrentCliVersion();
+      expect(child_process.exec).toHaveBeenCalledTimes(1);
+      expect(child_process.execFile).toHaveBeenCalledTimes(1);
+
+      // Clear cache
+      clearCliVersionCache();
+
+      // Should re-detect
+      await getCurrentCliVersion();
+      expect(child_process.exec).toHaveBeenCalledTimes(2); // 1 + 1
+      expect(child_process.execFile).toHaveBeenCalledTimes(2); // 1 + 1
+    });
+  });
+});

package/src/cli-replacement/version-detection.ts

@@ -0,0 +1,220 @@
+/**
+ * CLI version detection with environment-aware caching.
+ *
+ * This module provides cached CLI version detection optimized for different
+ * environments:
+ * - Docker/CSB: Reads from SUPERBLOCKS_CLI_VERSION env var (instant, ~0ms)
+ * - Local: Caches subprocess result (6s first call, 0ms subsequent calls)
+ *
+ * The caching strategy eliminates duplicate subprocess executions that previously
+ * caused ~12s delays during dev server startup.
+ */
+
+import * as child_process from "node:child_process";
+import { promisify } from "node:util";
+import { isNativeError } from "node:util/types";
+import { getLogger } from "../telemetry/logging.js";
+
+const exec = promisify(child_process.exec);
+const execFile = promisify(child_process.execFile);
+const logger = getLogger();
+
+/**
+ * Package version information returned by version detection.
+ */
+export interface PackageVersionInfo {
+  /** Semantic version string (e.g., "2.0.0-next.1") */
+  version: string;
+  /** Optional package alias for ephemeral builds (e.g., "@superblocksteam/cli-ephemeral") */
+  alias?: string;
+}
+
+/**
+ * Module-level cache for CLI version.
+ * - undefined: Not yet fetched
+ * - null: Fetch attempted but failed
+ * - PackageVersionInfo: Successfully fetched
+ */
+let cachedCliVersion: PackageVersionInfo | undefined | null = undefined;
+
+/**
+ * Detects if running in Docker/CSB environment.
+ *
+ * @returns true if SUPERBLOCKS_IS_CSB environment variable is set to "true"
+ */
+function isDockerEnvironment(): boolean {
+  return process.env.SUPERBLOCKS_IS_CSB === "true";
+}
+
+/**
+ * Reads CLI version from SUPERBLOCKS_CLI_VERSION environment variable.
+ *
+ * This is the fast path for Docker/CSB environments where the version
+ * is injected at build time.
+ *
+ * @returns PackageVersionInfo if env var is set, undefined otherwise
+ */
+function getVersionFromEnvironment(): PackageVersionInfo | undefined {
+  const envVersion = process.env.SUPERBLOCKS_CLI_VERSION;
+  if (!envVersion) return undefined;
+
+  // Detect ephemeral builds by SNAPSHOT in version string
+  const isEphemeral = envVersion.includes("SNAPSHOT");
+
+  return {
+    version: envVersion,
+    alias: isEphemeral ? "@superblocksteam/cli-ephemeral" : undefined,
+  };
+}
+
+/**
+ * Detects CLI version by spawning subprocesses.
+ *
+ * This is the slow path (~6s) used in local development environments.
+ * It executes two commands:
+ * 1. `which superblocks` (or `where` on Windows) - Find CLI binary in PATH
+ * 2. `superblocks version --json` - Execute CLI to get version
+ *
+ * @returns PackageVersionInfo if CLI is found and version can be read, undefined otherwise
+ */
+async function getVersionFromSubprocess(): Promise<
+  PackageVersionInfo | undefined
+> {
+  try {
+    const command = process.platform === "win32" ? "where" : "which";
+    const { stdout } = await exec(`${command} superblocks`);
+    const superblocksPath = stdout.trim().split("\n")[0]; // Take first line only
+
+    if (!superblocksPath) return undefined;
+
+    // Use execFile to properly handle paths with spaces (e.g., "C:\Program Files\...")
+    const { stdout: versionOutput } = await execFile(superblocksPath, [
+      "version",
+      "--json",
+    ]);
+    const json = JSON.parse(versionOutput) as Record<string, string>;
+
+    // Extract version from string like:
+    // - "@superblocksteam/cli/2.0.0-next.1"
+    // - "@superblocksteam/cli-ephemeral/2.0.0-SNAPSHOT.ebd2b86d643331f5"
+    const version = json.cliVersion?.replace(
+      /@superblocksteam\/cli(-ephemeral)?\//,
+      "",
+    );
+
+    // Detect alias (e.g., cli-ephemeral) for ephemeral builds
+    const aliasMatch = json.cliVersion?.match(/@superblocksteam\/([^\/]+)/);
+    if (aliasMatch && aliasMatch[1] !== "cli") {
+      return {
+        version: version,
+        alias: `@superblocksteam/${aliasMatch[1]}`,
+      };
+    }
+
+    return { version };
+  } catch (error) {
+    if (isNativeError(error)) {
+      // Expected: CLI not installed (which/where returns empty or command not found)
+      if (
+        error.message.includes("not found") ||
+        error.message.includes("command not found")
+      ) {
+        logger.debug("CLI binary not found in PATH");
+        return undefined;
+      }
+      // Unexpected: permission errors, malformed output, etc.
+      logger.warn(
+        `Failed to detect CLI version: ${error.message}. Automatic upgrades will be disabled.`,
+      );
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Gets the current CLI version with caching.
+ *
+ * Detection strategy (in order):
+ * 1. Return cached value if available (only successful detections are cached)
+ * 2. Docker/CSB: Read from SUPERBLOCKS_CLI_VERSION env var (~0ms)
+ * 3. Local: Execute subprocess and cache result (~6s first call, ~0ms subsequent)
+ *
+ * The cache is shared across all callers, eliminating duplicate subprocess
+ * executions. This reduces dev server startup from ~12s to ~6s (local) or
+ * ~0s (Docker).
+ *
+ * Note: Failures are NOT cached, allowing recovery from transient issues
+ * (network glitches, filesystem races) without requiring a dev server restart.
+ *
+ * @returns PackageVersionInfo if CLI version can be detected, undefined otherwise
+ *
+ * @example
+ * // First call in Docker - instant
+ * const version = await getCurrentCliVersion();
+ * // Returns: { version: "2.0.0-next.1" }
+ *
+ * @example
+ * // First call locally - slow (~6s)
+ * const version1 = await getCurrentCliVersion();
+ * // Second call - instant (cached)
+ * const version2 = await getCurrentCliVersion();
+ */
+export async function getCurrentCliVersion(): Promise<
+  PackageVersionInfo | undefined
+> {
+  // Return cached value if available (only successful detections are cached)
+  if (cachedCliVersion !== undefined && cachedCliVersion !== null) {
+    return cachedCliVersion;
+  }
+
+  // Docker/CSB: Try environment variable first (fast path)
+  if (isDockerEnvironment()) {
+    cachedCliVersion = getVersionFromEnvironment();
+    if (cachedCliVersion) {
+      logger.debug(`CLI version from environment: ${cachedCliVersion.version}`);
+      return cachedCliVersion;
+    }
+  }
+
+  // Local: Use subprocess detection (slow path, but cached on success)
+  logger.debug("Detecting CLI version via subprocess...");
+  const detectedVersion = await getVersionFromSubprocess();
+
+  if (detectedVersion) {
+    logger.debug(`CLI version from subprocess: ${detectedVersion.version}`);
+    cachedCliVersion = detectedVersion; // Cache successful detection
+  } else {
+    logger.debug("Could not detect CLI version");
+    // Don't cache failures - allow retry on next call in case of transient issues
+  }
+
+  return detectedVersion;
+}
+
+/**
+ * Clears the cached CLI version, optionally setting it to a known value.
+ *
+ * This is used after CLI upgrades to update the cache with the newly installed
+ * version, avoiding the need for subprocess detection. If a version is provided,
+ * the cache is set to that version; otherwise, the cache is cleared and the next
+ * call to getCurrentCliVersion() will re-detect.
+ *
+ * @param newVersion - Optional version info to set the cache to (e.g., after upgrade)
+ *
+ * @example
+ * // After upgrading CLI to a known version
+ * clearCliVersionCache({ version: "2.0.0-next.2" });
+ * const version = await getCurrentCliVersion(); // Returns cached version instantly
+ *
+ * @example
+ * // Clear cache completely (for tests)
+ * clearCliVersionCache();
+ * const version = await getCurrentCliVersion(); // Will re-detect
+ */
+export function clearCliVersionCache(newVersion?: PackageVersionInfo): void {
+  if (newVersion) {
+    cachedCliVersion = newVersion;
+  } else {
+    cachedCliVersion = undefined;
+  }
+}