Skip to content

Context7 Platform -- Up-to-date docs for AI agents

8.4 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
import { mkdir, readFile, rm, writeFile } from "fs/promises";
import { join } from "path";
import { tmpdir } from "os";

import {
  checkForUpdates,
  compareVersions,
  detectInstallMethod,
  getUpgradePlan,
  markUpdateNotificationShown,
  shouldShowUpdateNotification,
  shouldSkipUpdateNotifier,
} from "../utils/update-check.js";

let tempDir: string;
let stateFile: string;

beforeEach(async () => {
  tempDir = join(tmpdir(), `ctx7-update-${Date.now()}`);
  stateFile = join(tempDir, "cli-state.json");
  await mkdir(tempDir, { recursive: true });
  vi.stubGlobal(
    "fetch",
    vi.fn(() => {
      throw new Error("fetch not mocked");
    })
  );
});

afterEach(async () => {
  await rm(tempDir, { recursive: true, force: true });
  vi.unstubAllGlobals();
  vi.unstubAllEnvs();
  vi.doUnmock("os");
  vi.resetModules();
  vi.restoreAllMocks();
});

describe("compareVersions", () => {
  test("orders semantic versions correctly", () => {
    expect(compareVersions("0.3.14", "0.3.13")).toBeGreaterThan(0);
    expect(compareVersions("0.3.13", "0.3.13")).toBe(0);
    expect(compareVersions("0.3.13", "0.3.14")).toBeLessThan(0);
  });
});

describe("detectInstallMethod", () => {
  test("detects npx and pnpm dlx", () => {
    expect(
      detectInstallMethod({
        npm_execpath: "/usr/local/lib/node_modules/npm/bin/npm-cli.js",
        npm_command: "exec",
      })
    ).toBe("npx");

    expect(
      detectInstallMethod({
        npm_execpath: "/Users/test/Library/pnpm/pnpm.cjs",
        npm_command: "dlx",
      })
    ).toBe("pnpm-dlx");
  });

  test("detects npm, pnpm, bun, and bunx style shells", () => {
    expect(
      detectInstallMethod({
        npm_execpath: "/usr/local/lib/node_modules/npm/bin/npm-cli.js",
        npm_command: "install",
      })
    ).toBe("npm-global");

    expect(
      detectInstallMethod({
        npm_execpath: "/Users/test/Library/pnpm/pnpm.cjs",
        npm_command: "add",
      })
    ).toBe("pnpm-global");

    expect(
      detectInstallMethod({
        npm_execpath: "/Users/test/.bun/bin/bun",
        npm_command: "add",
      })
    ).toBe("bun-global");

    expect(
      detectInstallMethod({
        npm_execpath: "/Users/test/.bun/bin/bun",
        npm_command: "x",
      })
    ).toBe("bunx");
  });

  test("falls back to npm-global for npm user agents", () => {
    expect(detectInstallMethod({ npm_config_user_agent: "npm/10.0.0 node/v22.0.0" })).toBe(
      "npm-global"
    );
  });
});

describe("getUpgradePlan", () => {
  test("returns explicit runner commands for ephemeral installs", () => {
    expect(getUpgradePlan("npx").displayCommand).toBe("npx ctx7@latest <command>");
    expect(getUpgradePlan("pnpm-dlx").displayCommand).toBe("pnpm dlx ctx7@latest <command>");
  });

  test("does not auto-run upgrade plans for unknown installs", () => {
    expect(getUpgradePlan("unknown").canRun).toBe(false);
  });
});

describe("checkForUpdates", () => {
  test("uses cached latest version when the cache is fresh", async () => {
    vi.stubGlobal(
      "fetch",
      vi.fn().mockResolvedValue({
        ok: true,
        json: () => Promise.resolve({ version: "9.9.9" }),
      })
    );

    const fetched = await checkForUpdates({ force: true, stateFile, now: 1000 });
    expect(fetched?.updateAvailable).toBe(true);

    const fetchMock = vi.mocked(fetch);
    fetchMock.mockClear();

    const info = await checkForUpdates({
      stateFile,
      now: 2000,
      cacheTtlMs: 10_000,
    });

    expect(info?.latestVersion).toBe("9.9.9");
    expect(fetchMock).not.toHaveBeenCalled();
  });
});

describe("default cli-state persistence", () => {
  test("writes updater state under the XDG state directory when using the default path", async () => {
    const fakeHome = join(tempDir, "fake-home");
    await mkdir(fakeHome, { recursive: true });

    vi.resetModules();
    vi.doMock("os", async () => {
      const actual = await vi.importActual<typeof import("os")>("os");
      return { ...actual, homedir: () => fakeHome };
    });

    vi.stubGlobal(
      "fetch",
      vi.fn().mockResolvedValue({
        ok: true,
        json: () => Promise.resolve({ version: "9.9.9" }),
      })
    );

    const updateCheck = await import("../utils/update-check.js");

    await updateCheck.checkForUpdates({ force: true, now: 1000 });
    await updateCheck.markUpdateNotificationShown("9.9.9", { now: 2000 });

    const persisted = JSON.parse(
      await readFile(join(fakeHome, ".local", "state", "context7", "cli-state.json"), "utf-8")
    ) as {
      latestVersion?: string;
      lastCheckedAt?: number;
      notifiedVersion?: string;
      lastNotifiedAt?: number;
    };

    expect(persisted).toEqual({
      latestVersion: "9.9.9",
      lastCheckedAt: 1000,
      notifiedVersion: "9.9.9",
      lastNotifiedAt: 2000,
    });
  });

  test("honors XDG_STATE_HOME for updater state", async () => {
    // Mock homedir so the legacy-migration step cannot touch the real ~/.context7.
    const fakeHome = join(tempDir, "fake-home");
    await mkdir(fakeHome, { recursive: true });
    const stateHome = join(tempDir, "xdg-state");
    vi.stubEnv("XDG_STATE_HOME", stateHome);

    vi.resetModules();
    vi.doMock("os", async () => {
      const actual = await vi.importActual<typeof import("os")>("os");
      return { ...actual, homedir: () => fakeHome };
    });

    vi.stubGlobal(
      "fetch",
      vi.fn().mockResolvedValue({
        ok: true,
        json: () => Promise.resolve({ version: "9.9.9" }),
      })
    );

    const updateCheck = await import("../utils/update-check.js");
    await updateCheck.checkForUpdates({ force: true, now: 1000 });

    const persisted = JSON.parse(
      await readFile(join(stateHome, "context7", "cli-state.json"), "utf-8")
    ) as {
      latestVersion?: string;
      lastCheckedAt?: number;
    };

    expect(persisted).toEqual({
      latestVersion: "9.9.9",
      lastCheckedAt: 1000,
    });
  });

  test("migrates legacy ~/.context7 cli-state into the XDG state directory", async () => {
    const fakeHome = join(tempDir, "fake-home");
    const legacyDir = join(fakeHome, ".context7");
    await mkdir(legacyDir, { recursive: true });
    await writeFile(
      join(legacyDir, "cli-state.json"),
      JSON.stringify({ latestVersion: "9.9.9", lastCheckedAt: 1000 }),
      "utf-8"
    );

    vi.resetModules();
    vi.doMock("os", async () => {
      const actual = await vi.importActual<typeof import("os")>("os");
      return { ...actual, homedir: () => fakeHome };
    });

    vi.stubGlobal(
      "fetch",
      vi.fn(() => {
        throw new Error("fetch should not be called for a fresh migrated cache");
      })
    );

    const updateCheck = await import("../utils/update-check.js");

    const info = await updateCheck.checkForUpdates({
      now: 2000,
      cacheTtlMs: 10_000,
    });

    expect(info?.latestVersion).toBe("9.9.9");
    expect(fetch).not.toHaveBeenCalled();
    expect(
      JSON.parse(
        await readFile(join(fakeHome, ".local", "state", "context7", "cli-state.json"), "utf-8")
      )
    ).toEqual({ latestVersion: "9.9.9", lastCheckedAt: 1000 });
  });
});

describe("update notifications", () => {
  test("respects notification cooldown per latest version", async () => {
    const info = {
      currentVersion: "0.3.13",
      latestVersion: "9.9.9",
      updateAvailable: true,
      installMethod: "npm-global" as const,
      upgradePlan: getUpgradePlan("npm-global"),
    };

    expect(await shouldShowUpdateNotification(info, { stateFile, now: 1000 })).toBe(true);

    await markUpdateNotificationShown("9.9.9", { stateFile, now: 1000 });

    expect(await shouldShowUpdateNotification(info, { stateFile, now: 2000 })).toBe(false);
    expect(
      await shouldShowUpdateNotification(info, { stateFile, now: 1000 + 25 * 60 * 60 * 1000 })
    ).toBe(true);
  });

  test("skips notifier for json, version, and custom deployments", () => {
    expect(shouldSkipUpdateNotifier(["node", "ctx7", "library", "react", "--json"])).toBe(true);
    expect(shouldSkipUpdateNotifier(["node", "ctx7", "--version"])).toBe(true);
    expect(
      shouldSkipUpdateNotifier(["node", "ctx7", "setup", "--base-url", "https://context7.internal"])
    ).toBe(true);
    expect(shouldSkipUpdateNotifier(["node", "ctx7", "--base-url=https://context7.internal"])).toBe(
      true
    );
    expect(shouldSkipUpdateNotifier(["node", "ctx7", "docs", "/a/b", "q"])).toBe(false);
  });
});