// ---------------------------------------------------------------------------
// Update check: one source of truth for "is a newer Executor published?"
//
// Both surfaces that tell a user to upgrade read from here:
//   - the CLI prints an "update available" line under its ready banner, and
//   - the web/desktop shell lights up its sidebar UpdateCard,
// the latter by fetching the `/v1/app/npm/dist-tags` route (see
// `server/npm-dist-tags.ts`), which serves `resolveDistTags()` verbatim.
//
// The semver helpers are a deliberate port of the ones the web shell already
// carries (`packages/app/src/web/shell.tsx`) so the client- and server-side
// "is this newer?" verdicts can never disagree.
//
// Resolution order (see `resolveDistTags`):
//   1. `EXECUTOR_DISABLE_UPDATE_CHECK` set  -> {} (no check, both surfaces quiet)
//   2. `EXECUTOR_NPM_DIST_TAGS` JSON override -> parsed tags (tests / air-gapped)
//   3. `EXECUTOR_FORCE_LATEST_VERSION` single value -> { latest, beta } = value
//   4. npm registry dist-tags endpoint, cached in-process
//   5. any failure -> {} (the check is best-effort; never a hard error)
// ---------------------------------------------------------------------------

export type UpdateChannel = "latest" | "beta";

/** The published npm package the CLI ships as. */
export const EXECUTOR_PACKAGE_NAME = "executor";

/** Lightweight dist-tags-only registry endpoint (not the full packument). */
const NPM_DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${EXECUTOR_PACKAGE_NAME}/dist-tags`;

/** How long a successful registry lookup is reused before refetching. */
const DIST_TAGS_TTL_MS = 10 * 60 * 1000;

/** How long an empty result (offline, timeout, no tags) is reused before
 *  retrying. Negative-caches failures so an air-gapped server does not pay the
 *  fetch timeout on every shell load, while still recovering quickly. */
const EMPTY_TTL_MS = 60 * 1000;

/** How long to wait on the registry before giving up (a check, not a gate). */
const NPM_FETCH_TIMEOUT_MS = 1500;

// ── Semver (ported from the web shell, kept byte-for-byte in behaviour) ────

type ParsedVersion = {
  readonly major: number;
  readonly minor: number;
  readonly patch: number;
  readonly prerelease: ReadonlyArray<string | number> | null;
};

const semverPattern =
  /^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:-(?<prerelease>[0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;

export const resolveUpdateChannel = (version: string): UpdateChannel =>
  version.includes("-beta.") ? "beta" : "latest";

const parseVersion = (version: string): ParsedVersion | null => {
  const match = version.trim().match(semverPattern);
  if (!match?.groups) return null;
  return {
    major: Number(match.groups.major),
    minor: Number(match.groups.minor),
    patch: Number(match.groups.patch),
    prerelease: match.groups.prerelease
      ? match.groups.prerelease.split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id))
      : null,
  };
};

const comparePrereleaseIdentifiers = (
  left: ReadonlyArray<string | number> | null,
  right: ReadonlyArray<string | number> | null,
): number => {
  if (left === null && right === null) return 0;
  if (left === null) return 1;
  if (right === null) return -1;
  const max = Math.max(left.length, right.length);
  for (let i = 0; i < max; i++) {
    const l = left[i];
    const r = right[i];
    if (l === undefined) return -1;
    if (r === undefined) return 1;
    if (l === r) continue;
    if (typeof l === "number" && typeof r === "number") return l < r ? -1 : 1;
    if (typeof l === "number") return -1;
    if (typeof r === "number") return 1;
    return l < r ? -1 : 1;
  }
  return 0;
};

/**
 * `-1` if `left` is older than `right`, `1` if newer, `0` if equal, `null` if
 * either side is not parseable semver.
 */
export const compareVersions = (left: string, right: string): number | null => {
  const lv = parseVersion(left);
  const rv = parseVersion(right);
  if (!lv || !rv) return null;
  if (lv.major !== rv.major) return lv.major < rv.major ? -1 : 1;
  if (lv.minor !== rv.minor) return lv.minor < rv.minor ? -1 : 1;
  if (lv.patch !== rv.patch) return lv.patch < rv.patch ? -1 : 1;
  return comparePrereleaseIdentifiers(lv.prerelease, rv.prerelease);
};

/**
 * True when `version` parses as `0.0.0`, with or without a prerelease suffix
 * (e.g. `0.0.0-dev`). `0.0.0` is never a published release — it is the
 * build-time fallback baked in when the real version was unavailable at
 * build time — so a build carrying it must never claim an update.
 */
export const isUnstampedVersion = (version: string): boolean => {
  const parsed = parseVersion(version);
  return parsed !== null && parsed.major === 0 && parsed.minor === 0 && parsed.patch === 0;
};

/**
 * The dist-tag channel `version` can legitimately be compared against, or
 * `null` when there is none (the check should be suppressed, not run):
 *   - an unstamped build (0.0.0*) never shipped, so there is nothing to
 *     compare it against
 *   - unparseable input has no meaningful channel
 *   - no prerelease -> the `latest` tag
 *   - a prerelease whose first identifier is `beta` -> the `beta` tag
 *   - any other prerelease (rc, alpha, next, dev, ...) has no matching
 *     dist-tag, so suppress rather than nag forever against a channel it can
 *     never catch up to
 */
export const resolveComparisonChannel = (version: string): UpdateChannel | null => {
  if (isUnstampedVersion(version)) return null;
  const parsed = parseVersion(version);
  if (!parsed) return null;
  if (parsed.prerelease === null) return "latest";
  return parsed.prerelease[0] === "beta" ? "beta" : null;
};

/**
 * The single "should we nag?" verdict both the CLI and the web UpdateCard
 * read. False whenever there is nothing to compare: no current version, no
 * dist-tag channel this version could match (see `resolveComparisonChannel`),
 * or no published tag for that channel.
 */
export const isUpdateAvailable = (
  currentVersion: string | undefined,
  latestVersion: string | null,
): boolean => {
  if (currentVersion === undefined) return false;
  if (resolveComparisonChannel(currentVersion) === null) return false;
  if (latestVersion === null) return false;
  return compareVersions(currentVersion, latestVersion) === -1;
};

// ── dist-tags resolution ──────────────────────────────────────────────────

export type DistTags = Partial<Record<UpdateChannel, string>>;

export type ResolveDistTagsOptions = {
  /** Env source; defaults to `process.env`. Injectable for tests. */
  readonly env?: Record<string, string | undefined>;
  /** Fetch impl; defaults to global `fetch`. Injectable for tests. */
  readonly fetchImpl?: typeof fetch;
};

type CacheEntry = { readonly at: number; readonly tags: DistTags };
let registryCache: CacheEntry | null = null;

// Read `process.env` without a hard `process` reference, so this module stays
// isomorphic (it is pulled into the browser-side type graph via the shared web
// shell's update card, which has no node types).
const ambientEnv = (): Record<string, string | undefined> => {
  const globalProcess = (
    globalThis as { readonly process?: { readonly env?: Record<string, string | undefined> } }
  ).process;
  return globalProcess?.env ?? {};
};

/** Reset the in-process registry cache. Test seam. */
export const __resetDistTagsCache = (): void => {
  registryCache = null;
};

const pickTags = (value: unknown): DistTags => {
  if (typeof value !== "object" || value === null) return {};
  const record = value as Record<string, unknown>;
  const tags: DistTags = {};
  if (typeof record.latest === "string") tags.latest = record.latest;
  if (typeof record.beta === "string") tags.beta = record.beta;
  return tags;
};

const parseTagsJson = (raw: string): DistTags | null => {
  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: an operator-supplied env override is untrusted text; a malformed value is ignored, not fatal
  try {
    // oxlint-disable-next-line executor/no-json-parse -- boundary: untrusted env override, structurally validated by pickTags below
    return pickTags(JSON.parse(raw));
  } catch {
    return null;
  }
};

const overrideFromEnv = (env: Record<string, string | undefined>): DistTags | null => {
  const raw = env.EXECUTOR_NPM_DIST_TAGS?.trim();
  if (raw) {
    const parsed = parseTagsJson(raw);
    if (parsed) return parsed;
  }
  const forced = env.EXECUTOR_FORCE_LATEST_VERSION?.trim();
  if (forced) return { latest: forced, beta: forced };
  return null;
};

/**
 * Resolve the published dist-tags for the `executor` package. Best-effort:
 * returns `{}` when disabled, offline, timed out, or the registry misbehaves,
 * never throws.
 */
export const resolveDistTags = async (options?: ResolveDistTagsOptions): Promise<DistTags> => {
  const env = options?.env ?? ambientEnv();
  if (env.EXECUTOR_DISABLE_UPDATE_CHECK) return {};

  const override = overrideFromEnv(env);
  if (override) return override;

  const now = Date.now();
  if (registryCache) {
    // Empty results (failures, or a package with no tags) carry the shorter
    // negative TTL so a transient outage recovers quickly; real tags stick.
    const ttl =
      registryCache.tags.latest || registryCache.tags.beta ? DIST_TAGS_TTL_MS : EMPTY_TTL_MS;
    if (now - registryCache.at < ttl) return registryCache.tags;
  }

  const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
  // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: best-effort fetch of an external registry; any failure (offline, timeout, bad JSON) collapses to "no update signal", never an error
  try {
    const res = await fetchImpl(NPM_DIST_TAGS_URL, {
      headers: { accept: "application/json" },
      signal: AbortSignal.timeout(NPM_FETCH_TIMEOUT_MS),
    });
    if (!res.ok) {
      registryCache = { at: now, tags: {} };
      return {};
    }
    const tags = pickTags(await res.json());
    registryCache = { at: now, tags };
    return tags;
  } catch {
    registryCache = { at: now, tags: {} };
    return {};
  }
};

// ── checkForUpdate ─────────────────────────────────────────────────────────

export type UpdateStatus = {
  readonly updateAvailable: boolean;
  readonly currentVersion: string;
  readonly latestVersion: string | null;
  readonly channel: UpdateChannel;
  /** Suggested upgrade command, e.g. `npm i -g executor@latest`. */
  readonly command: string;
};

/**
 * Compare a running version against the published dist-tags for its channel.
 * Best-effort: an unreachable registry yields `updateAvailable: false`.
 */
export const checkForUpdate = async (
  currentVersion: string,
  options?: ResolveDistTagsOptions,
): Promise<UpdateStatus> => {
  const channel = resolveUpdateChannel(currentVersion);
  const command = `npm i -g ${EXECUTOR_PACKAGE_NAME}@${channel}`;

  // No dist-tag can legitimately be compared against this version (unstamped
  // dev build, or a prerelease channel that never gets published) — do not
  // even hit the registry, since the answer is already known.
  const comparisonChannel = resolveComparisonChannel(currentVersion);
  if (comparisonChannel === null) {
    return { updateAvailable: false, currentVersion, latestVersion: null, channel, command };
  }

  const tags = await resolveDistTags(options);
  const latestVersion = tags[comparisonChannel] ?? null;
  const updateAvailable = isUpdateAvailable(currentVersion, latestVersion);
  return { updateAvailable, currentVersion, latestVersion, channel, command };
};