Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

23.0 KB
Raw Blame
import { useState, useEffect, useCallback, useRef } from 'react';
import { useTranslation } from 'react-i18next';

import {
  fetchReleaseNotes,
  fetchReleaseNotesIndex,
  type ReleaseNotes,
} from '@/release-notes';
import { useLocale } from '@/hooks/useLocale';
import type { SupportedLocale } from '@/i18n';
import { toast } from '@/lib/toast';
import { createLogger } from '@/lib/logger';

const log = createLogger('UseUpdateNotice');

const STORAGE_KEY = 'xdt-maker:lastReadVersion';

/**
 * Cap on how many versions get aggregated into a single **auto** popup. Users
 * who skip many releases don't actually read 30 blocks of notes — the wall
 * becomes scary and the CDN takes a beating fanning out that many parallel
 * fetches. Manual look-back (`onOpen`) is NOT capped — it lazy-loads full
 * history on scroll, so the initial cost stays constant regardless of depth.
 */
const MAX_AGGREGATED_VERSIONS = 5;

/**
 * How long the pre-install preview waits for the version index before opening
 * with the pending version alone. The index contributes only the *in-between*
 * blocks of a multi-version jump; a slow or unreachable CDN must not turn the
 * banner's link into a dead click for the full request timeout (15s in
 * `releaseNotesService`).
 */
const PREVIEW_INDEX_BUDGET_MS = 3000;

/**
 * A fresh install/update can race the CDN publishing the current notice or
 * the renderer mounting during startup. Retry the automatic path once after a
 * short pause; manual and pre-install preview paths already have explicit
 * user-driven retry/fallback behavior.
 */
const AUTO_NOTICE_RETRY_DELAY_MS = 2000;

/** Numeric semver comparison. Returns >0 if a > b, <0 if a < b, 0 if equal. */
function cmpVersion(a: string, b: string): number {
  const pa = a.split('.').map(Number);
  const pb = b.split('.').map(Number);
  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
    if (diff !== 0) return diff;
  }
  return 0;
}

/**
 * Two dialog modes with very different data / UX contracts:
 *
 *   - `auto`  — fired once per launch after a version upgrade. Loads the diff
 *              `(lastRead, appVersion]` (max N) all up front. Badge is static
 *              `v<oldest> → v<newest>`. Dismissal advances `lastReadVersion`.
 *
 *   - `manual`— fired by user clicking the flame icon. Loads only appVersion's
 *              notes up front; the rest of the history is exposed via
 *              `allVersions` and lazy-fetched via `loadVersion` as the dialog
 *              scrolls placeholders into view. Badge tracks the topmost
 *              visible version + doubles as a dropdown to jump to any version.
 *              Dismissal does NOT touch lastReadVersion (manual look-back
 *              must not suppress the next real upgrade popup).
 *
 * `onOpenVersion(pending)` is a third entry point — the sidebar UpdateBanner
 * previewing an update that is downloaded but **not installed yet**. It reuses
 * the `auto` layout contract verbatim (pre-loaded blocks, `v旧 → v新` badge,
 * version count, no lazy history, no version jumper) because it carries the
 * same shape of payload: an aggregated diff range. The only difference is which
 * range — auto covers `(lastRead, appVersion]`, preview covers
 * `(appVersion, pending]`, so a user who skipped several releases sees every
 * version the restart will jump over, and a plain one-version bump sees one
 * block.
 *
 * Two things it deliberately does NOT do: attach the installed version or its
 * back-catalogue (that's the flame icon's job — `onOpen`), and advance
 * `lastReadVersion` on dismiss (that would swallow the real popup after the
 * restart). The read-marker, not `mode`, is what governs the latter — see
 * `readMarkerRef`.
 */
export type UpdateNoticeMode = 'auto' | 'manual';

export interface UseUpdateNoticeReturn {
  /** Dialog visibility. */
  open: boolean;
  /** Which UX contract the dialog is currently under. Null when closed. */
  mode: UpdateNoticeMode | null;
  /**
   * Initial notes for the dialog to render immediately.
   *   - auto: the loaded diff range, newest-first.
   *   - manual: `[appVersionNotes]` (single entry) — the rest of history is
   *             loaded lazily via `loadVersion` on scroll.
   * Null when dialog is closed.
   */
  releaseNotes: ReleaseNotes[] | null;
  /**
   * Manual mode only: full history of versions on CDN (`≤ appVersion`),
   * newest-first. The dialog renders one placeholder per entry and hydrates
   * on demand via `loadVersion`. Null in auto mode / when dialog is closed.
   */
  allVersions: string[] | null;
  /**
   * Fetch a single version's notes. Returns null on 404 / parse / network.
   * Backed by main-side + renderer-side caches, so repeated calls for the
   * same version are near-free — the dialog can wire it into
   * IntersectionObserver callbacks without extra bookkeeping.
   */
  loadVersion: (version: string) => Promise<ReleaseNotes | null>;
  /** Close the dialog (writes lastReadVersion in auto mode only). */
  dismiss: () => void;
  /** Manually open the dialog for a lazy full-history review. */
  onOpen: () => void;
  /**
   * Open the dialog as a pre-install preview of `pendingVersion`: that version
   * plus every version between it and the installed one, aggregated in the
   * `auto` layout. Dismissal does not touch `lastReadVersion`.
   *
   * No fallback to a different version: if `pendingVersion`'s own notes can't
   * be fetched we toast and stay closed rather than answering a question the
   * user didn't ask. Callers should gate their entry point on a successful
   * `fetchReleaseNotes` probe so this stays an edge case.
   */
  onOpenVersion: (pendingVersion: string) => void;
}

/**
 * Resolve the diff set of versions to auto-load given user's last-read cursor
 * and the current app version. Auto path only — manual path uses the full
 * `allVersions` array separately.
 *
 * - Fresh install (lastRead === null): only the current version.
 * - Same version (lastRead === appVersion): nothing (caller returns early).
 * - Upgrade: every index entry strictly greater than lastRead and less than
 *   or equal to appVersion, with tolerant fallbacks for edge conditions
 *   (lastRead older than earliest index entry, appVersion not yet in index,
 *   user downgraded).
 */
function versionsToFetch(
  index: string[] | null,
  lastRead: string | null,
  appVersion: string,
): string[] {
  if (lastRead === null || !index) return [appVersion];
  const curIdx = index.indexOf(appVersion);
  if (curIdx === -1) return [appVersion];
  const lastIdx = index.indexOf(lastRead);
  if (lastIdx === -1) {
    const insertIdx = index.findIndex((v) => cmpVersion(v, lastRead) > 0);
    if (insertIdx === -1 || insertIdx > curIdx) return [appVersion];
    return index.slice(insertIdx, curIdx + 1);
  }
  if (curIdx <= lastIdx) return [appVersion];
  return index.slice(lastIdx + 1, curIdx + 1);
}

/**
 * Build the pre-install preview range for `onOpenVersion`: every version the
 * user is about to jump over, i.e. index entries in `(appVersion, pending]`,
 * ascending, plus `pending` itself.
 *
 * Deliberately excludes `appVersion` and everything older — the question is
 * "what do I get by restarting", not "what has ever shipped". Skipping several
 * releases therefore yields several blocks; a normal one-version bump yields
 * exactly one.
 *
 * - Index unreachable → just `[pending]`; the dialog still opens with the one
 *   block that matters.
 * - `pending` not in the index yet (CDN publishes the notice and the index
 *   separately, so there is a window) → appended anyway. It is the version the
 *   caller already probed successfully.
 * - Capped to the newest `MAX_AGGREGATED_VERSIONS` for the same reason auto
 *   mode is: nobody reads 30 blocks, and each one is a CDN round-trip.
 */
function versionsToPreview(
  index: string[] | null,
  appVersion: string,
  pending: string,
): string[] {
  const inRange = (index ?? []).filter(
    (v) => cmpVersion(v, appVersion) > 0 && cmpVersion(v, pending) <= 0,
  );
  if (!inRange.includes(pending)) inRange.push(pending);
  return inRange.slice(-MAX_AGGREGATED_VERSIONS);
}

/**
 * Build the manual-mode full-history list: everything in the CDN index up to
 * (and including) appVersion, reversed to newest-first for UI convenience.
 * Returns just `[appVersion]` when index isn't reachable — the dialog still
 * opens with a single block, matching the pre-lazy behaviour.
 */
function versionsForManual(index: string[] | null, appVersion: string): string[] {
  if (!index) return [appVersion];
  const curIdx = index.indexOf(appVersion);
  if (curIdx !== -1) return index.slice(0, curIdx + 1).reverse();
  // appVersion 尚未进入 CDN index(刚发布版本存在短暂延迟):
  // 仍然列出 index 中所有 <= appVersion 的历史版本,并把当前版本插到最前面,
  // 避免手动查看历史路径在版本刚发布时退化成单一条目。
  const olderVersions = index
    .filter((v) => cmpVersion(v, appVersion) <= 0)
    .reverse();
  return [appVersion, ...olderVersions];
}

export function useUpdateNotice(): UseUpdateNoticeReturn {
  const { t } = useTranslation();
  const { effectiveLocale } = useLocale();
  const [open, setOpen] = useState(false);
  const [mode, setMode] = useState<UpdateNoticeMode | null>(null);
  const [releaseNotes, setReleaseNotes] = useState<ReleaseNotes[] | null>(null);
  const [allVersions, setAllVersions] = useState<string[] | null>(null);
  /**
   * Version to write to `lastReadVersion` on dismiss. See extended comment on
   * the previous implementation for gap-safe logic. Manual look-back sets
   * this to null so dismiss doesn't touch lastReadVersion.
   */
  const readMarkerRef = useRef<string | null>(null);
  // Set synchronously (before any await) in onOpen so the auto-fetch path
  // can bail out if manual dialog was opened while the fetch was in flight.
  const dialogOpenedRef = useRef(false);
  // Once a user explicitly opens either manual history or a pre-install
  // preview, suppress the pending automatic retry for this hook lifetime.
  // This must outlive dialogOpenedRef: dismiss() intentionally resets the
  // latter, but the automatic attempt must not resurrect after dismissal.
  const autoNoticeSuppressedRef = useRef(false);
  // Stored handle for the dismiss cleanup timer so onOpen can cancel it if
  // the user re-opens the dialog before the 200ms animation delay fires.
  const dismissTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  // Async entry points capture a locale. This ref prevents a slower response
  // for the previous locale from replacing newly selected-language content.
  const localeRef = useRef(effectiveLocale);
  localeRef.current = effectiveLocale;
  const previousLocaleRef = useRef(effectiveLocale);

  /**
   * Resolve a whole version set in one stable locale. If the user changes the
   * language while requests are in flight, the raw/version cache makes the
   * retry local and cheap while preventing a mixed-language result set.
   */
  const fetchVersionsForCurrentLocale = useCallback(
    async (
      versions: string[],
      initialRequest?: {
        version: string;
        locale: SupportedLocale;
        promise: Promise<ReleaseNotes | null>;
      },
    ): Promise<(ReleaseNotes | null)[]> => {
      let requestLocale = localeRef.current;
      let canUseInitialRequest = true;
      for (;;) {
        const results = await Promise.all(versions.map((version) => {
          if (
            canUseInitialRequest &&
            initialRequest?.version === version &&
            initialRequest.locale === requestLocale
          ) {
            return initialRequest.promise;
          }
          return fetchReleaseNotes(version, requestLocale);
        }));
        canUseInitialRequest = false;
        if (localeRef.current === requestLocale) return results;
        requestLocale = localeRef.current;
      }
    },
    [],
  );

  useEffect(() => {
    const appVersion = window.electronAPI.appVersion;
    let lastRead: string | null = null;
    try {
      lastRead = localStorage.getItem(STORAGE_KEY);
    } catch {
      // localStorage not available — fall through to the fetch path so the
      // user still sees the dialog; we just won't be able to mark it read.
    }

    // Already saw this exact version → nothing to do.
    if (lastRead === appVersion) return;

    let cancelled = false;
    autoNoticeSuppressedRef.current = false;

    (async () => {
      // A transient CDN miss should not permanently lose the upgrade notice for
      // this process. Keep the retry bounded so a genuinely unavailable CDN
      // does not hold the renderer in a retry loop.
      for (let attempt = 0; attempt < 2; attempt += 1) {
        // Fresh install: skip the index round-trip and show only the current
        // version's notes. We don't want to blast a new user with 30 versions
        // of history on first launch.
        const index = lastRead === null ? null : await fetchReleaseNotesIndex();
        if (cancelled || dialogOpenedRef.current || autoNoticeSuppressedRef.current) return;

        const targets = versionsToFetch(index, lastRead, appVersion).slice(
          -MAX_AGGREGATED_VERSIONS,
        );
        const results = await fetchVersionsForCurrentLocale(targets);
        if (cancelled || dialogOpenedRef.current || autoNoticeSuppressedRef.current) return;
        const notes = results.filter((n): n is ReleaseNotes => n !== null);

        if (notes.length > 0 && notes.some((n) => n.version === appVersion)) {
          // Compute the safe read-marker (unchanged from prior impl).
          const isCurIdxMissing = index !== null && index.indexOf(appVersion) === -1;
          const firstFailIdx = results.findIndex((n) => n === null);
          if (isCurIdxMissing) {
            readMarkerRef.current = lastRead ?? null;
          } else if (firstFailIdx === -1) {
            readMarkerRef.current = appVersion;
          } else if (firstFailIdx === 0) {
            const skipKey = `xdt-maker:notice-skip-tried-${targets[0]}`;
            if (localStorage.getItem(skipKey) === null) {
              localStorage.setItem(skipKey, '1');
              readMarkerRef.current = lastRead ?? null;
            } else {
              readMarkerRef.current = targets[0];
            }
          } else {
            readMarkerRef.current = targets[firstFailIdx - 1];
          }

          notes.reverse();
          setMode('auto');
          setReleaseNotes(notes);
          setOpen(true);
          return;
        }

        if (
          attempt === 0 &&
          !cancelled &&
          !dialogOpenedRef.current &&
          !autoNoticeSuppressedRef.current
        ) {
          await new Promise<void>((resolve) => {
            setTimeout(resolve, AUTO_NOTICE_RETRY_DELAY_MS);
          });
        }
      }
    })().catch((err) => {
      log.warn('auto-fetch threw:', err);
    });

    return () => { cancelled = true; };
  }, [fetchVersionsForCurrentLocale]);

  // Re-select every version currently owned by the hook when the language
  // changes. Renderer raw caching keeps this local: no extra CDN/IPC request.
  useEffect(() => {
    if (previousLocaleRef.current === effectiveLocale) return;
    previousLocaleRef.current = effectiveLocale;
    const versions = releaseNotes?.map((notes) => notes.version) ?? [];
    if (versions.length === 0) return;

    let cancelled = false;
    void Promise.all(versions.map((version) => fetchReleaseNotes(version, effectiveLocale)))
      .then((localized) => {
        if (cancelled || localeRef.current !== effectiveLocale) return;
        const byVersion = new Map(
          localized
            .filter((notes): notes is ReleaseNotes => notes !== null)
            .map((notes) => [notes.version, notes]),
        );
        setReleaseNotes((current) =>
          current?.map((notes) => byVersion.get(notes.version) ?? notes) ?? current,
        );
      })
      .catch((err) => {
        log.warn('locale-refresh threw:', err);
      });

    return () => { cancelled = true; };
  }, [effectiveLocale, releaseNotes]);

  const dismiss = useCallback(() => {
    dialogOpenedRef.current = false;
    setOpen(false);
    const marker = readMarkerRef.current;
    if (marker !== null) {
      try { localStorage.setItem(STORAGE_KEY, marker); } catch { /* noop */ }
    }
    readMarkerRef.current = null;
    // Delay clearing state so the exit animation can play before unmount.
    // Store the handle so onOpen() can cancel it if the dialog is re-opened
    // within the 200ms window (cached fetches can resolve in ~10ms, which
    // would race with the pending cleanup and blank the dialog).
    dismissTimerRef.current = setTimeout(() => {
      setReleaseNotes(null);
      setAllVersions(null);
      setMode(null);
    }, 200);
  }, []);

  const onOpen = useCallback(() => {
    if (open) return;
    // Cancel any pending dismiss cleanup so a fast re-open doesn't wipe the
    // state that the new open just wrote.
    if (dismissTimerRef.current !== null) {
      clearTimeout(dismissTimerRef.current);
      dismissTimerRef.current = null;
    }
    // Set synchronously so the auto-fetch path can see it immediately even
    // before this async IIFE has called setOpen/setMode.
    autoNoticeSuppressedRef.current = true;
    dialogOpenedRef.current = true;
    const appVersion = window.electronAPI.appVersion;

    (async () => {
      // Fetch index + appVersion's notes in parallel. The index is what the
      // dialog uses to render placeholders for every history entry; the
      // appVersion notes are what the top block shows immediately so the
      // dialog isn't blank-until-lazy-load on open.
      const warmupLocale = localeRef.current;
      const appNotesWarmup = fetchReleaseNotes(appVersion, warmupLocale)
        .catch(() => null);
      const index = await fetchReleaseNotesIndex();
      const [appNotes] = await fetchVersionsForCurrentLocale(
        [appVersion],
        { version: appVersion, locale: warmupLocale, promise: appNotesWarmup },
      );
      // The dialog needs at least one loaded note as its initial seed.
      // If appVersion's JSON is temporarily unavailable (CDN lag / 404), try
      // the most-recent historical version from the index as fallback seed so
      // users can still browse full history.  Only bail when the index is also
      // unavailable or every candidate fetch fails.
      let seed = appNotes;
      if (!seed && index && index.length > 0) {
        // Try each historical version in order (newest first) until one loads,
        // so a single bad/lagging CDN file doesn't block the entire history view.
        for (const fallbackVersion of versionsForManual(index, appVersion)) {
          if (fallbackVersion === appVersion) continue;
          const [fallback] = await fetchVersionsForCurrentLocale([fallbackVersion]);
          if (fallback) {
            seed = fallback;
            break;
          }
        }
      }
      if (!seed) {
        dialogOpenedRef.current = false;
        toast.error(t('logic.toasts.fetchUpdateNoticeFailed'));
        return;
      }

      // Guard against a race with auto-fetch: if the auto path already opened
      // the dialog with a valid marker, the manual overlay would either fight
      // for the same setOpen slot or worse, wipe the auto marker on dismiss.
      // The `open` check at the top of onOpen already covers the "already
      // open" case; this covers the sub-1s window where marker was set but
      // setOpen hasn't rendered yet.
      if (readMarkerRef.current !== null) return;

      setMode('manual');
      setReleaseNotes([seed]);
      setAllVersions(versionsForManual(index, appVersion));
      readMarkerRef.current = null;
      setOpen(true);
    })().catch((err) => {
      dialogOpenedRef.current = false;
      log.warn('manual-fetch threw:', err);
      toast.error(t('logic.toasts.fetchUpdateNoticeFailed'));
    });
  }, [t, open, fetchVersionsForCurrentLocale]);

  const onOpenVersion = useCallback((pendingVersion: string) => {
    // `open` is state, so two clicks in the same tick both read `false` and both
    // fan out to the CDN. `dialogOpenedRef` is set synchronously below and stays
    // true until dismiss (or a failed attempt), so it is the re-entrancy guard
    // that actually holds for a double-clicked text link.
    if (open || dialogOpenedRef.current) return;
    if (dismissTimerRef.current !== null) {
      clearTimeout(dismissTimerRef.current);
      dismissTimerRef.current = null;
    }
    autoNoticeSuppressedRef.current = true;
    dialogOpenedRef.current = true;
    const appVersion = window.electronAPI.appVersion;

    (async () => {
      // Kick off the pending version's notes immediately — it is the one block
      // that must be there, and the banner's probe usually leaves it cached, so
      // this resolves ~instantly and overlaps whatever the index costs.
      const warmupLocale = localeRef.current;
      const pendingNotesWarmup = fetchReleaseNotes(pendingVersion, warmupLocale)
        .catch(() => null);
      // The index only adds the *in-between* blocks. Waiting out the full CDN
      // timeout (15s, releaseNotesService) for them would make the link look
      // dead, so give it a budget and degrade to the pending version alone —
      // the same degradation `versionsToPreview` already does for a null index.
      const index = await Promise.race([
        fetchReleaseNotesIndex(),
        new Promise<null>((resolve) => {
          setTimeout(() => resolve(null), PREVIEW_INDEX_BUDGET_MS);
        }),
      ]);
      const targets = versionsToPreview(index, appVersion, pendingVersion);
      const results = await fetchVersionsForCurrentLocale(
        targets,
        { version: pendingVersion, locale: warmupLocale, promise: pendingNotesWarmup },
      );
      const notes = results.filter((n): n is ReleaseNotes => n !== null);

      // The pending version's own notes are the point of this dialog — if only
      // the in-between ones loaded, we'd be answering a question the user
      // didn't ask. Bail (the banner's probe makes this a rare CDN race).
      if (!notes.some((n) => n.version === pendingVersion)) {
        dialogOpenedRef.current = false;
        toast.error(t('logic.toasts.fetchUpdateNoticeFailed'));
        return;
      }

      // Same race guard as onOpen: never clobber an auto popup that has already
      // claimed the dialog with a real read-marker.
      if (readMarkerRef.current !== null) return;

      notes.reverse();
      setMode('auto');
      setReleaseNotes(notes);
      setAllVersions(null);
      // Stays null: dismissing a pre-install preview must NOT advance
      // lastReadVersion, or the real popup after the restart never fires.
      readMarkerRef.current = null;
      setOpen(true);
    })().catch((err) => {
      dialogOpenedRef.current = false;
      log.warn('preview-fetch threw:', err);
      toast.error(t('logic.toasts.fetchUpdateNoticeFailed'));
    });
  }, [t, open, fetchVersionsForCurrentLocale]);

  const loadVersion = useCallback(
    (version: string) => fetchReleaseNotes(version, effectiveLocale),
    [effectiveLocale],
  );

  return {
    open,
    mode,
    releaseNotes,
    allVersions,
    loadVersion,
    dismiss,
    onOpen,
    onOpenVersion,
  };
}