hyperframes/packages/cli/src/utils/updateCheck.ts

import { compareVersions } from "compare-versions";
import { readConfig, writeConfig } from "../telemetry/config.js";
import { VERSION } from "../version.js";
import { isDevMode } from "./env.js";

const NPM_REGISTRY_URL = "https://registry.npmjs.org/hyperframes/latest";
const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
const FETCH_TIMEOUT_MS = 3000;

/** Returns true if `a` is newer than `b` per semver (handles alpha, beta, rc). */
function isNewerSemver(a: string, b: string): boolean {
  try {
    return compareVersions(a, b) > 0;
  } catch {
    return a !== b;
  }
}

export interface UpdateCheckResult {
  current: string;
  latest: string;
  updateAvailable: boolean;
}

export interface UpdateMeta {
  version: string;
  latestVersion?: string;
  updateAvailable: boolean;
}

/**
 * Check npm registry for the latest version. Uses a 24h cache to avoid
 * hitting the registry on every invocation.
 *
 * @param force - Skip cache and fetch fresh data
 */
export async function checkForUpdate(force?: boolean): Promise<UpdateCheckResult> {
  const config = readConfig();
  const now = Date.now();

  if (!force && config.lastUpdateCheck && config.latestVersion) {
    const lastCheck = new Date(config.lastUpdateCheck).getTime();
    if (now - lastCheck < CHECK_INTERVAL_MS) {
      return {
        current: VERSION,
        latest: config.latestVersion,
        updateAvailable: isNewerSemver(config.latestVersion, VERSION),
      };
    }
  }

  try {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
    const res = await fetch(NPM_REGISTRY_URL, {
      signal: controller.signal,
      headers: { Connection: "close" },
    });
    clearTimeout(timeout);

    if (!res.ok) return fallbackResult(config.latestVersion);

    const data = (await res.json()) as { version?: string };
    const latest = data.version ?? VERSION;

    config.lastUpdateCheck = new Date().toISOString();
    config.latestVersion = latest;
    writeConfig(config);

    return { current: VERSION, latest, updateAvailable: isNewerSemver(latest, VERSION) };
  } catch {
    return fallbackResult(config.latestVersion);
  }
}

function fallbackResult(cachedLatest?: string): UpdateCheckResult {
  return {
    current: VERSION,
    latest: cachedLatest ?? VERSION,
    updateAvailable: cachedLatest ? isNewerSemver(cachedLatest, VERSION) : false,
  };
}

/**
 * Synchronous read from cache — for _meta envelope on --json commands.
 * Never fetches. Returns what the last background check found.
 */
export function getUpdateMeta(): UpdateMeta {
  const config = readConfig();
  return {
    version: VERSION,
    latestVersion: config.latestVersion,
    updateAvailable: config.latestVersion ? isNewerSemver(config.latestVersion, VERSION) : false,
  };
}

/**
 * Wrap a JSON payload with the _meta version envelope.
 * Use this in all --json command outputs for consistent agent-friendly metadata.
 */
export function withMeta<T extends object>(data: T): T & { _meta: UpdateMeta } {
  return { ...data, _meta: getUpdateMeta() };
}

/**
 * Print update notice to stderr if a newer version is available.
 * Skipped in CI, non-TTY, dev mode, or when HYPERFRAMES_NO_UPDATE_CHECK is set.
 */
export function printUpdateNotice(): void {
  if (isDevMode()) return;
  if (process.env["CI"] === "true" || process.env["CI"] === "1") return;
  if (!process.stderr.isTTY) return;
  if (process.env["HYPERFRAMES_NO_UPDATE_CHECK"] === "1") return;

  const meta = getUpdateMeta();
  if (!meta.updateAvailable || !meta.latestVersion) return;

  process.stderr.write(
    `\n  Update available: ${meta.version} \u2192 ${meta.latestVersion}\n` +
      `  Run: npx hyperframes@latest\n\n`,
  );
}