@indigoai-us/hq-cli 5.12.1 → 5.12.3

package/src/utils/version-check.test.ts

@@ -0,0 +1,146 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+vi.mock("../cli-version.js", () => ({ CLI_VERSION: "5.12.1" }));
+
+const tmpHome = path.join(os.tmpdir(), `hq-cli-version-check-${process.pid}`);
+
+beforeEach(() => {
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  fs.mkdirSync(tmpHome, { recursive: true });
+  vi.stubEnv("HOME", tmpHome);
+  vi.unstubAllEnvs();
+  vi.stubEnv("HOME", tmpHome);
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+async function loadModule() {
+  vi.resetModules();
+  return await import("./version-check.js");
+}
+
+function writeCache(latest: string, ageMs = 0): void {
+  const cacheDir = path.join(tmpHome, ".hq");
+  fs.mkdirSync(cacheDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(cacheDir, "version-check.json"),
+    JSON.stringify({ latest, fetchedAt: Date.now() - ageMs }),
+  );
+}
+
+describe("maybeWarnNewVersion", () => {
+  it("warns on stderr when cached latest is newer than CLI_VERSION", async () => {
+    writeCache("5.99.0");
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mod = await loadModule();
+    mod.maybeWarnNewVersion();
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = warn.mock.calls[0]?.join(" ") ?? "";
+    expect(msg).toContain("5.99.0");
+    expect(msg.toLowerCase()).toContain("update");
+  });
+
+  it("is silent when cached latest equals CLI_VERSION", async () => {
+    writeCache("5.12.1");
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mod = await loadModule();
+    mod.maybeWarnNewVersion();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("is silent when cached latest is older than CLI_VERSION", async () => {
+    writeCache("5.0.0");
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mod = await loadModule();
+    mod.maybeWarnNewVersion();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("is silent when there is no cache yet (first run)", async () => {
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mod = await loadModule();
+    mod.maybeWarnNewVersion();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("ignores cache entries older than the TTL (24h default)", async () => {
+    writeCache("5.99.0", 25 * 60 * 60 * 1000);
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mod = await loadModule();
+    mod.maybeWarnNewVersion();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("is silent when HQ_NO_UPDATE_CHECK=1 is set, even with newer cached version", async () => {
+    writeCache("5.99.0");
+    vi.stubEnv("HQ_NO_UPDATE_CHECK", "1");
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mod = await loadModule();
+    mod.maybeWarnNewVersion();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("does not throw on malformed cache JSON", async () => {
+    const cacheDir = path.join(tmpHome, ".hq");
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.writeFileSync(path.join(cacheDir, "version-check.json"), "not json{");
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    const mod = await loadModule();
+    expect(() => mod.maybeWarnNewVersion()).not.toThrow();
+    expect(warn).not.toHaveBeenCalled();
+  });
+});
+
+describe("refreshVersionCache", () => {
+  it("writes the latest version from the npm registry to the cache file", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: "5.99.0" }),
+    } as unknown as Response);
+    vi.stubGlobal("fetch", fetchMock);
+
+    const mod = await loadModule();
+    await mod.refreshVersionCache();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const url = fetchMock.mock.calls[0]?.[0] as string;
+    expect(url).toContain("registry.npmjs.org");
+    expect(url).toContain("%40indigoai-us%2Fhq-cli");
+
+    const cachePath = path.join(tmpHome, ".hq", "version-check.json");
+    const written = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+    expect(written.latest).toBe("5.99.0");
+    expect(typeof written.fetchedAt).toBe("number");
+  });
+
+  it("does not throw or write a cache when fetch fails", async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new Error("network down"));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const mod = await loadModule();
+    await expect(mod.refreshVersionCache()).resolves.toBeUndefined();
+
+    const cachePath = path.join(tmpHome, ".hq", "version-check.json");
+    expect(fs.existsSync(cachePath)).toBe(false);
+  });
+
+  it("does not fetch or write cache when HQ_NO_UPDATE_CHECK=1", async () => {
+    vi.stubEnv("HQ_NO_UPDATE_CHECK", "1");
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    const mod = await loadModule();
+    await mod.refreshVersionCache();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    const cachePath = path.join(tmpHome, ".hq", "version-check.json");
+    expect(fs.existsSync(cachePath)).toBe(false);
+  });
+});

package/src/utils/version-check.ts

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import semver from "semver";
+import chalk from "chalk";
+import { CLI_VERSION } from "../cli-version.js";
+
+const PACKAGE_NAME = "@indigoai-us/hq-cli";
+const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3_000;
+
+interface CacheEntry {
+  latest: string;
+  fetchedAt: number;
+}
+
+function cachePath(): string {
+  return path.join(os.homedir(), ".hq", "version-check.json");
+}
+
+function isOptedOut(): boolean {
+  return process.env.HQ_NO_UPDATE_CHECK === "1";
+}
+
+function readCache(): CacheEntry | null {
+  try {
+    const raw = fs.readFileSync(cachePath(), "utf-8");
+    const parsed = JSON.parse(raw) as Partial<CacheEntry>;
+    if (
+      typeof parsed.latest !== "string" ||
+      typeof parsed.fetchedAt !== "number"
+    ) {
+      return null;
+    }
+    return { latest: parsed.latest, fetchedAt: parsed.fetchedAt };
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(entry: CacheEntry): void {
+  try {
+    const file = cachePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(entry));
+  } catch {
+    // best-effort; never break the CLI on cache write failure
+  }
+}
+
+export function maybeWarnNewVersion(): void {
+  if (isOptedOut()) return;
+  const entry = readCache();
+  if (!entry) return;
+  if (Date.now() - entry.fetchedAt > CACHE_TTL_MS) return;
+
+  const current = semver.valid(CLI_VERSION);
+  const latest = semver.valid(entry.latest);
+  if (!current || !latest) return;
+  if (!semver.gt(latest, current)) return;
+
+  const msg = chalk.yellow(
+    `⚠ A new version of hq is available: ${entry.latest} (current: ${CLI_VERSION}). It's recommended to update.`,
+  );
+  console.error(msg);
+}
+
+export async function refreshVersionCache(): Promise<void> {
+  if (isOptedOut()) return;
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) return;
+    const body = (await res.json()) as { version?: unknown };
+    if (typeof body.version !== "string") return;
+    writeCache({ latest: body.version, fetchedAt: Date.now() });
+  } catch {
+    // best-effort; offline / registry down / timeout — silent
+  }
+}