Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(web): surface upgrades in the dashboard + share release info via core (#556)

Raghav Chamadiyace7d28b046db
diff --git a/README.md b/README.md
index 01692e7f9..60a50a130 100644
--- a/README.md
+++ b/README.md
@@ -374,7 +374,7 @@ To add the MCP server to another editor manually:
> commit-triggered update takes **under 30 seconds** and only regenerates the
> pages your change touched.
-**Docs:** [Quickstart](docs/QUICKSTART.md) · [User Guide](docs/USER_GUIDE.md) · [CLI Reference](docs/CLI_REFERENCE.md) · [Codex](docs/CODEX.md) · [MCP Tools](docs/MCP_TOOLS.md) · [Distill](docs/DISTILL.md) · [Workspaces](docs/WORKSPACES.md) · [Auto-Sync](docs/AUTO_SYNC.md) · [Config](docs/CONFIG.md)
+**Docs:** [Quickstart](docs/QUICKSTART.md) · [User Guide](docs/USER_GUIDE.md) · [CLI Reference](docs/CLI_REFERENCE.md) · [Codex](docs/CODEX.md) · [MCP Tools](docs/MCP_TOOLS.md) · [Distill](docs/DISTILL.md) · [Workspaces](docs/WORKSPACES.md) · [Auto-Sync](docs/AUTO_SYNC.md) · [Upgrading](docs/UPGRADING.md) · [Config](docs/CONFIG.md)
---
diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md
index 13f8c4281..bfe5fe5e7 100644
--- a/docs/CLI_REFERENCE.md
+++ b/docs/CLI_REFERENCE.md
@@ -737,6 +737,30 @@ its absence never fails doctor.
---
+### `repowise whats-new`
+
+Show release notes for repowise versions you haven't seen yet. By default it
+lists releases newer than the last one you viewed, then records the current
+version as seen. Works offline from the changelog bundled with the install.
+
+| Flag | Description |
+|------|-------------|
+| `--version X.Y.Z` | Show notes for a single release |
+| `--all` | Show the full changelog history |
+
+```bash
+repowise whats-new # what changed since you last looked
+repowise whats-new --version 0.21.0 # one specific release
+repowise whats-new --all # full history
+```
+
+`repowise update` shows a short "what's new" panel automatically after you
+upgrade to a newer version, and both `update` and `serve` print a one-line,
+non-blocking notice when a newer release is available on PyPI. See
+[docs/UPGRADING.md](UPGRADING.md) for the full upgrade flow.
+
+---
+
### `repowise delete [REPO_ID]`
Delete a repository's index and all stored intelligence (wiki, graph, embeddings,
diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md
new file mode 100644
index 000000000..cc5d9714e
--- /dev/null
+++ b/docs/UPGRADING.md
@@ -0,0 +1,41 @@
+# Upgrading repowise
+
+repowise is built so that upgrading is painless: **upgrade the package, run `repowise update`, and your existing index keeps working.** A full reindex is only ever *recommended* for a genuinely breaking change, never forced, and repowise tells you exactly when and how.
+
+## The short version
+
+```bash
+pipx upgrade repowise # or: uv tool upgrade repowise / pip install -U repowise
+cd your-repo
+repowise update # picks up the new version against your existing index
+```
+
+That's it. No reindex in the normal case.
+
+## What happens on upgrade
+
+When you run `repowise update` (or `repowise serve`) after upgrading, repowise:
+
+1. **Reads your store's format version** and compares it to the running build. The on-disk store records which version wrote it, so repowise knows exactly what, if anything, an upgrade needs.
+2. **Applies any automatic, no-cost adjustments in place.** New database columns are back-filled automatically. If your embedding model changed, vectors are re-embedded for you (no LLM calls). You don't run anything.
+3. **Keeps your parse cache warm.** Ordinary releases do not invalidate cached work, so updates stay fast.
+4. **Shows you what changed.** A short "what's new" summary appears for the versions you crossed, and `repowise whats-new` shows release notes any time. The web UI surfaces a dismissible "update available" banner and a what's-new view.
+
+## When a reindex is recommended
+
+Rarely, a release changes the store format in a way an in-place migration can't cover. When that happens repowise **keeps your existing index working** and shows a clear notice with the exact command, for example:
+
+```
+Reindex recommended: repowise init --force
+```
+
+It is a recommendation, not a requirement. Nothing is wiped until you choose to run it. You can keep using the current index and reindex when convenient.
+
+## Checking your version
+
+- CLI: `repowise --version`, or `repowise doctor` for an update check with the right upgrade command for your install method.
+- Web UI: the version is shown in the sidebar footer, with a dot when a newer release is available.
+
+## See also
+
+- `docs/CHANGELOG.md` - full release notes.
diff --git a/packages/cli/src/repowise/cli/update_check.py b/packages/cli/src/repowise/cli/update_check.py
index e470676c6..08c766fbb 100644
--- a/packages/cli/src/repowise/cli/update_check.py
+++ b/packages/cli/src/repowise/cli/update_check.py
@@ -22,12 +22,23 @@ import time
from dataclasses import dataclass
from pathlib import Path
-PYPI_URL = "https://pypi.org/pypi/repowise/json"
-
-#: Default freshness window for the cached PyPI check. Within this window the
-#: last fetched ``latest_version`` is reused so routine commands never hit the
-#: network. 24h keeps the advisory current without nagging PyPI on every run.
-DEFAULT_TTL_HOURS = 24.0
+# Version comparison and the PyPI fetch are defined once in core (the server
+# shares them too). Re-exported here so existing ``repowise.cli.update_check``
+# importers keep working.
+from repowise.core.upgrade.release import (
+ DEFAULT_TTL_HOURS,
+ fetch_latest_version,
+ is_newer_version,
+)
+
+__all__ = [
+ "DEFAULT_TTL_HOURS",
+ "UpdateCheck",
+ "get_cli_update_check",
+ "get_cli_update_check_cached",
+ "is_newer_version",
+ "suggest_update_command",
+]
@dataclass(frozen=True)
@@ -50,44 +61,6 @@ class UpdateCheck:
error: str | None = None
-def _parse_release(version: str) -> tuple[int, ...] | None:
- """Parse the leading numeric release parts of a version string.
-
- Returns a tuple of ints for the dotted numeric prefix (so ``0.15.2`` ->
- ``(0, 15, 2)``). Pre-release/local suffixes such as ``-rc1`` or ``+local``
- are ignored. Returns ``None`` when no numeric component can be parsed.
- """
- parts: list[int] = []
- for chunk in version.strip().split("."):
- digits = ""
- for ch in chunk:
- if ch.isdigit():
- digits += ch
- else:
- break
- if not digits:
- break
- parts.append(int(digits))
- return tuple(parts) or None
-
-
-def is_newer_version(latest: str, current: str) -> bool:
- """Return ``True`` if ``latest`` is a strictly newer release than ``current``.
-
- Uses a simple numeric-release comparison. If either version cannot be
- parsed, returns ``False`` (no update decision) rather than raising.
- """
- lat = _parse_release(latest)
- cur = _parse_release(current)
- if lat is None or cur is None:
- return False
- # Pad to equal length so 0.15 compares correctly against 0.15.2.
- length = max(len(lat), len(cur))
- lat = lat + (0,) * (length - len(lat))
- cur = cur + (0,) * (length - len(cur))
- return lat > cur
-
-
def suggest_update_command(executable: str | None, python: str) -> tuple[str, str]:
"""Suggest an upgrade command and human-readable install hint.
@@ -146,23 +119,7 @@ def get_cli_update_check(timeout: float = 2.0) -> UpdateCheck:
else:
suggested, hint = suggest_update_command(resolved or running, python)
- latest: str | None = None
- error: str | None = None
- try:
- import httpx
-
- resp = httpx.get(PYPI_URL, timeout=timeout)
- resp.raise_for_status()
- fetched = resp.json()["info"]["version"]
- # Only accept a version we can actually compare; otherwise leave
- # latest=None so callers report "unknown" rather than a false "latest".
- if _parse_release(fetched) is None:
- error = f"unparsable latest version: {fetched!r}"
- else:
- latest = fetched
- except Exception as exc: # network, JSON, missing key — all advisory
- error = str(exc) or exc.__class__.__name__
-
+ latest, error = fetch_latest_version(timeout=timeout)
if latest is None:
update_available: bool | None = None
else:
diff --git a/packages/cli/src/repowise/cli/whats_new.py b/packages/cli/src/repowise/cli/whats_new.py
index 1c156b15f..b6b45c4db 100644
--- a/packages/cli/src/repowise/cli/whats_new.py
+++ b/packages/cli/src/repowise/cli/whats_new.py
@@ -24,12 +24,13 @@ from repowise.core.upgrade.changelog import (
entries_between,
parse_changelog,
)
+from repowise.core.upgrade.release import BUNDLED_CHANGELOG_PATH
from .helpers import user_global_dir
RELEASES_URL = "https://github.com/repowise-dev/repowise/releases"
-_BUNDLED_CHANGELOG = Path(__file__).parent / "_data" / "CHANGELOG.md"
+_BUNDLED_CHANGELOG = BUNDLED_CHANGELOG_PATH
_LAST_SEEN_FILENAME = "last-seen-version"
diff --git a/packages/cli/src/repowise/cli/_data/CHANGELOG.md b/packages/core/src/repowise/core/upgrade/_data/CHANGELOG.md
similarity index 100%
rename from packages/cli/src/repowise/cli/_data/CHANGELOG.md
rename to packages/core/src/repowise/core/upgrade/_data/CHANGELOG.md
diff --git a/packages/core/src/repowise/core/upgrade/release.py b/packages/core/src/repowise/core/upgrade/release.py
new file mode 100644
index 000000000..3964ecad0
--- /dev/null
+++ b/packages/core/src/repowise/core/upgrade/release.py
@@ -0,0 +1,182 @@
+"""Release info shared by every presenter: version compare, PyPI freshness, and
+repowise's own bundled changelog.
+
+This is the neutral home (in ``repowise-core``) for logic both the CLI and the
+server need. The server depends only on core, so anything it shares with the CLI
+lives here rather than in ``repowise.cli``. The CLI re-uses these helpers too, so
+the version comparator and PyPI fetch are defined once.
+
+Everything is best-effort: network and cache failures return an empty/unknown
+result rather than raising.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .changelog import ChangelogEntry, parse_changelog
+
+PYPI_URL = "https://pypi.org/pypi/repowise/json"
+
+#: Default freshness window for the cached PyPI check (hours). Within it the last
+#: fetched ``latest_version`` is reused so routine calls never hit the network.
+DEFAULT_TTL_HOURS = 24.0
+
+#: repowise's own changelog, bundled into the wheel as core package data so both
+#: ``repowise whats-new`` and the web what's-new view work offline.
+BUNDLED_CHANGELOG_PATH = Path(__file__).parent / "_data" / "CHANGELOG.md"
+
+#: Shared cache file (also written by the CLI advisory) under the user-global dir.
+_CACHE_PATH = Path.home() / ".repowise" / "update-check.json"
+
+
+# --- version comparison ---------------------------------------------------
+
+
+def parse_release(version: str) -> tuple[int, ...] | None:
+ """Parse the leading numeric release parts of *version* (``0.15.2`` -> ``(0,15,2)``).
+
+ Pre-release/local suffixes (``-rc1``, ``+local``) are ignored. Returns
+ ``None`` when no numeric component can be parsed.
+ """
+ parts: list[int] = []
+ for chunk in version.strip().split("."):
+ digits = ""
+ for ch in chunk:
+ if ch.isdigit():
+ digits += ch
+ else:
+ break
+ if not digits:
+ break
+ parts.append(int(digits))
+ return tuple(parts) or None
+
+
+def is_newer_version(latest: str, current: str) -> bool:
+ """Return ``True`` if *latest* is a strictly newer release than *current*.
+
+ Unparsable versions yield ``False`` (no update decision) rather than raising.
+ """
+ lat = parse_release(latest)
+ cur = parse_release(current)
+ if lat is None or cur is None:
+ return False
+ length = max(len(lat), len(cur))
+ lat = lat + (0,) * (length - len(lat))
+ cur = cur + (0,) * (length - len(cur))
+ return lat > cur
+
+
+# --- PyPI freshness -------------------------------------------------------
+
+
+def fetch_latest_version(timeout: float = 2.0) -> tuple[str | None, str | None]:
+ """Fetch repowise's latest published version from PyPI. Never raises.
+
+ Returns ``(latest, error)``. ``latest`` is ``None`` on any failure (network,
+ JSON, or a version we cannot compare), with ``error`` describing why.
+ """
+ try:
+ import httpx
+
+ resp = httpx.get(PYPI_URL, timeout=timeout)
+ resp.raise_for_status()
+ fetched = resp.json()["info"]["version"]
+ if parse_release(fetched) is None:
+ return None, f"unparsable latest version: {fetched!r}"
+ return fetched, None
+ except Exception as exc: # network, JSON, missing key - all advisory
+ return None, str(exc) or exc.__class__.__name__
+
+
+@dataclass(frozen=True)
+class ReleaseCheck:
+ """Outcome of a PyPI freshness check.
+
+ ``update_available`` is ``None`` when ``latest`` could not be determined, so
+ callers can tell "up to date" apart from "unknown".
+ """
+
+ current_version: str
+ latest_version: str | None
+ update_available: bool | None
+ error: str | None = None
+
+
+def check_latest_version_cached(
+ current_version: str,
+ *,
+ ttl_hours: float = DEFAULT_TTL_HOURS,
+ timeout: float = 2.0,
+) -> ReleaseCheck:
+ """TTL-cached PyPI freshness check. Never raises.
+
+ Reuses the last fetched ``latest_version`` from the shared
+ ``~/.repowise/update-check.json`` while younger than *ttl_hours* (the same
+ file the CLI advisory uses, so the two share a single network call). On a
+ miss it fetches live and persists the result. All cache I/O is best-effort.
+ """
+ latest, error = _read_cached_latest(ttl_hours)
+ if latest is _MISS:
+ latest, error = fetch_latest_version(timeout=timeout)
+ _write_cached_latest(latest, error)
+ update_available = is_newer_version(latest, current_version) if latest else None
+ return ReleaseCheck(
+ current_version=current_version,
+ latest_version=latest,
+ update_available=update_available,
+ error=error,
+ )
+
+
+#: Sentinel for "no fresh cache entry" (distinct from a cached ``latest=None``).
+_MISS = object()
+
+
+def _read_cached_latest(ttl_hours: float):
+ try:
+ cached = json.loads(_CACHE_PATH.read_text(encoding="utf-8"))
+ age = time.time() - float(cached["checked_at"])
+ if 0 <= age < ttl_hours * 3600:
+ return cached.get("latest_version"), cached.get("error")
+ except Exception:
+ pass
+ return _MISS, None
+
+
+def _write_cached_latest(latest: str | None, error: str | None) -> None:
+ with contextlib.suppress(Exception):
+ _CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+ _CACHE_PATH.write_text(
+ json.dumps({"checked_at": time.time(), "latest_version": latest, "error": error}),
+ encoding="utf-8",
+ )
+
+
+# --- bundled changelog ----------------------------------------------------
+
+
+def load_bundled_changelog() -> list[ChangelogEntry]:
+ """Parse repowise's bundled changelog, or ``[]`` if it cannot be read."""
+ try:
+ return parse_changelog(BUNDLED_CHANGELOG_PATH.read_text(encoding="utf-8"))
+ except Exception:
+ return []
+
+
+__all__ = [
+ "BUNDLED_CHANGELOG_PATH",
+ "DEFAULT_TTL_HOURS",
+ "PYPI_URL",
+ "ReleaseCheck",
+ "check_latest_version_cached",
+ "fetch_latest_version",
+ "is_newer_version",
+ "load_bundled_changelog",
+ "parse_release",
+]
diff --git a/packages/server/src/repowise/server/app.py b/packages/server/src/repowise/server/app.py
index 94dcb923b..0800c2d65 100644
--- a/packages/server/src/repowise/server/app.py
+++ b/packages/server/src/repowise/server/app.py
@@ -48,6 +48,7 @@ from repowise.server.routers import (
jobs,
knowledge_map,
mcp,
+ meta,
modules,
overview,
owners,
@@ -410,6 +411,7 @@ def create_app() -> FastAPI:
app.include_router(chat.router)
app.include_router(providers.router)
app.include_router(mcp.router)
+ app.include_router(meta.router)
app.include_router(costs.router)
app.include_router(security.router)
app.include_router(blast_radius.router)
diff --git a/packages/server/src/repowise/server/routers/meta.py b/packages/server/src/repowise/server/routers/meta.py
new file mode 100644
index 000000000..43fcbdff0
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/meta.py
@@ -0,0 +1,90 @@
+"""``/api/meta`` endpoints: repowise version freshness + release changelog.
+
+Powers the web UI's upgrade banner, "what's new" view, and version footer. All
+logic is shared with the CLI through :mod:`repowise.core.upgrade` so the server
+never depends on ``repowise.cli``. Best-effort: PyPI / changelog / store-read
+failures degrade to partial responses, never errors.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, Request
+
+from repowise.core.persistence import crud
+from repowise.core.persistence.database import get_session
+from repowise.core.upgrade import UpgradeTier, assess
+from repowise.core.upgrade.release import check_latest_version_cached, load_bundled_changelog
+from repowise.server import __version__
+from repowise.server.deps import resolve_session_factory, verify_api_key
+from repowise.server.schemas import (
+ ChangelogEntryModel,
+ ChangelogResponse,
+ ChangelogSectionModel,
+ VersionResponse,
+)
+
+router = APIRouter(prefix="/api/meta", tags=["meta"], dependencies=[Depends(verify_api_key)])
+
+#: Generic, install-method-agnostic upgrade hint for the web (the server can't
+#: know how the user installed the CLI). The CLI itself shows a tailored command.
+_UPGRADE_COMMAND = "pip install -U repowise"
+
+
[email protected]("/version", response_model=VersionResponse)
+async def get_version(request: Request, repo_id: str | None = None) -> VersionResponse:
+ """Server version + PyPI freshness, plus store status when ``repo_id`` given.
+
+ The global version/freshness path needs no database; a session is opened
+ lazily only when a ``repo_id`` is supplied (for the store-format fields).
+ """
+ check = check_latest_version_cached(__version__)
+ resp = VersionResponse(
+ server_version=__version__,
+ latest_version=check.latest_version,
+ update_available=check.update_available,
+ upgrade_command=_UPGRADE_COMMAND,
+ )
+
+ if repo_id:
+ await _attach_store_status(resp, repo_id, request)
+ return resp
+
+
+async def _attach_store_status(resp: VersionResponse, repo_id: str, request: Request) -> None:
+ """Fill the store-format fields for *repo_id*. Best-effort, never raises."""
+ try:
+ factory = resolve_session_factory(request.app.state, repo_id)
+ async with get_session(factory) as session:
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None or not repo.local_path:
+ return
+ state_path = Path(repo.local_path) / ".repowise" / "state.json"
+ state = json.loads(state_path.read_text(encoding="utf-8")) if state_path.is_file() else {}
+ verdict = assess(state)
+ resp.store_format_version = verdict.from_store_version
+ resp.store_compatible = verdict.tier != UpgradeTier.REINDEX_RECOMMENDED
+ resp.reindex_recommended = verdict.reindex_recommended
+ resp.reindex_command = verdict.reindex_command
+ except Exception:
+ return
+
+
[email protected]("/changelog", response_model=ChangelogResponse)
+async def get_changelog(limit: int = 20) -> ChangelogResponse:
+ """Return repowise's bundled changelog, newest first, capped at *limit*."""
+ entries = load_bundled_changelog()[: max(0, limit)]
+ return ChangelogResponse(
+ entries=[
+ ChangelogEntryModel(
+ version=e.version,
+ label=e.label,
+ sections=[
+ ChangelogSectionModel(name=s.name, items=list(s.items)) for s in e.sections
+ ],
+ )
+ for e in entries
+ ]
+ )
diff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.py
index 231989cef..8698fc006 100644
--- a/packages/server/src/repowise/server/schemas/__init__.py
+++ b/packages/server/src/repowise/server/schemas/__init__.py
@@ -103,6 +103,12 @@ from .mcp import (
McpToolSurfaceResponse,
UpdateMcpToolsRequest,
)
+from .meta import (
+ ChangelogEntryModel,
+ ChangelogResponse,
+ ChangelogSectionModel,
+ VersionResponse,
+)
from .intelligence import (
CallerCalleeEntry,
CallersCalleesResponse,
@@ -222,6 +228,9 @@ __all__ = [
"C4SystemResponse",
"CallerCalleeEntry",
"CallersCalleesResponse",
+ "ChangelogEntryModel",
+ "ChangelogResponse",
+ "ChangelogSectionModel",
"ChatMessageResponse",
"ChatRequest",
"CochangeWarning",
@@ -314,6 +323,7 @@ __all__ = [
"SymbolResponse",
"TransitiveEntry",
"UpdateMcpToolsRequest",
+ "VersionResponse",
"WebhookResponse",
"WorkspaceCoChangeEntry",
"WorkspaceBlastRadiusResponse",
diff --git a/packages/server/src/repowise/server/schemas/meta.py b/packages/server/src/repowise/server/schemas/meta.py
new file mode 100644
index 000000000..3e7980da9
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/meta.py
@@ -0,0 +1,38 @@
+"""Response schemas for the ``/api/meta`` endpoints (version + changelog)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class VersionResponse(BaseModel):
+ """Server version, PyPI freshness, and (optional) per-repo store status."""
+
+ server_version: str
+ latest_version: str | None = None
+ #: ``None`` when PyPI could not be reached (distinct from "up to date").
+ update_available: bool | None = None
+ upgrade_command: str
+
+ # Store-format status for a specific repo (populated only when ``repo_id``
+ # is supplied and resolvable). ``store_compatible`` is False only when a
+ # reindex is recommended; we recommend, never force.
+ store_format_version: int | None = None
+ store_compatible: bool | None = None
+ reindex_recommended: bool = False
+ reindex_command: str | None = None
+
+
+class ChangelogSectionModel(BaseModel):
+ name: str
+ items: list[str]
+
+
+class ChangelogEntryModel(BaseModel):
+ version: str
+ label: str | None = None
+ sections: list[ChangelogSectionModel]
+
+
+class ChangelogResponse(BaseModel):
+ entries: list[ChangelogEntryModel]
diff --git a/packages/web/src/app/layout.tsx b/packages/web/src/app/layout.tsx
index 90fe06c1f..f987413c9 100644
--- a/packages/web/src/app/layout.tsx
+++ b/packages/web/src/app/layout.tsx
@@ -12,6 +12,7 @@ import { MobileNav } from "@/components/layout/mobile-nav";
import { CommandPalette } from "@/components/search/command-palette";
import { ContextDrawerShell } from "@/components/layout/context-drawer-provider";
import { SWRProvider } from "@/components/layout/swr-provider";
+import { UpgradeBanner } from "@/components/layout/upgrade-banner";
import { listRepos } from "@/lib/api/repos";
import { getWorkspace } from "@/lib/api/workspace";
import type { WorkspaceResponse } from "@/lib/api/types";
@@ -67,7 +68,9 @@ export default async function RootLayout({
<TooltipProvider delayDuration={300}>
<Suspense fallback={null}>
<ContextDrawerShell>
- <div className="flex h-screen overflow-hidden">
+ <div className="flex h-screen flex-col overflow-hidden">
+ <UpgradeBanner />
+ <div className="flex flex-1 overflow-hidden">
<Sidebar repos={repos} workspace={workspace} />
<div className="flex flex-1 flex-col min-w-0 overflow-hidden">
<MobileNav repos={repos} workspace={workspace} />
@@ -75,6 +78,7 @@ export default async function RootLayout({
{children}
</main>
</div>
+ </div>
</div>
<CommandPalette repos={repos} workspace={workspace} />
</ContextDrawerShell>
diff --git a/packages/web/src/app/repos/[id]/layout.tsx b/packages/web/src/app/repos/[id]/layout.tsx
index 1f4c8818e..2d0912350 100644
--- a/packages/web/src/app/repos/[id]/layout.tsx
+++ b/packages/web/src/app/repos/[id]/layout.tsx
@@ -2,6 +2,7 @@ import { redirect } from "next/navigation";
import { getRepo } from "@/lib/api/repos";
import { ActiveJobBannerWrapper as ActiveJobBanner } from "@/components/dashboard/active-job-banner-wrapper";
import { PageTransition } from "@/components/layout/page-transition";
+import { ReindexHintBanner } from "@/components/layout/reindex-hint-banner";
import { RepoBreadcrumb } from "@/components/layout/repo-breadcrumb";
interface RepoLayoutProps {
@@ -20,6 +21,7 @@ export default async function RepoLayout({ children, params }: RepoLayoutProps)
}
return (
<>
+ <ReindexHintBanner repoId={id} />
<ActiveJobBanner repoId={id} />
<RepoBreadcrumb repoName={repoName} />
<PageTransition>{children}</PageTransition>
diff --git a/packages/web/src/components/layout/mobile-nav.tsx b/packages/web/src/components/layout/mobile-nav.tsx
index f85ea9ab4..f424a4722 100644
--- a/packages/web/src/components/layout/mobile-nav.tsx
+++ b/packages/web/src/components/layout/mobile-nav.tsx
@@ -16,6 +16,7 @@ import { Sheet, SheetContent, SheetHeader, SheetTitle } from "@repowise-dev/ui/u
import { ScrollArea } from "@repowise-dev/ui/ui/scroll-area";
import { Separator } from "@repowise-dev/ui/ui/separator";
import { AddRepoDialog } from "@/components/repos/add-repo-dialog";
+import { VersionFooter } from "./version-footer";
import { cn } from "@/lib/utils/cn";
import {
GLOBAL_NAV,
@@ -241,7 +242,7 @@ export function MobileNav({ repos = [], workspace }: MobileNavProps) {
</ScrollArea>
<div className="border-t border-[var(--color-border-default)] px-4 py-3">
- <p className="text-xs text-[var(--color-text-tertiary)]">repowise v0.21.0</p>
+ <VersionFooter />
</div>
</SheetContent>
</Sheet>
diff --git a/packages/web/src/components/layout/reindex-hint-banner.tsx b/packages/web/src/components/layout/reindex-hint-banner.tsx
new file mode 100644
index 000000000..4586890a4
--- /dev/null
+++ b/packages/web/src/components/layout/reindex-hint-banner.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { AlertTriangle, X } from "lucide-react";
+import useSWR from "swr";
+import { getMetaVersion } from "@/lib/api/meta";
+
+const STORAGE_PREFIX = "repowise:reindex-hint-dismissed:";
+
+export interface ReindexHintBannerProps {
+ repoId: string;
+}
+
+/**
+ * Per-repo notice shown only when the store format of this repo is behind the
+ * running build in a way that recommends a reindex. We recommend, never force:
+ * this is purely informational and dismissible. Renders nothing in the common
+ * case (store compatible) or if the check fails.
+ */
+export function ReindexHintBanner({ repoId }: ReindexHintBannerProps) {
+ const { data: meta } = useSWR(
+ ["meta-version", repoId],
+ () => getMetaVersion(repoId),
+ { revalidateOnFocus: false, revalidateOnReconnect: false },
+ );
+ const [dismissed, setDismissed] = useState(true);
+
+ const recommended = meta?.reindex_recommended === true;
+ const command = meta?.reindex_command ?? null;
+
+ useEffect(() => {
+ if (!recommended || typeof window === "undefined") return;
+ try {
+ setDismissed(!!window.localStorage.getItem(STORAGE_PREFIX + repoId));
+ } catch {
+ setDismissed(false);
+ }
+ }, [recommended, repoId]);
+
+ if (!recommended || dismissed) return null;
+
+ const dismiss = () => {
+ try {
+ window.localStorage.setItem(STORAGE_PREFIX + repoId, "1");
+ } catch {
+ /* localStorage unavailable - hide for this session only. */
+ }
+ setDismissed(true);
+ };
+
+ return (
+ <div
+ role="status"
+ className="flex items-start gap-3 border-b border-[var(--color-border-default)] bg-[var(--color-accent-muted)] px-4 py-2 text-sm"
+ >
+ <AlertTriangle
+ className="mt-0.5 h-4 w-4 shrink-0 text-[var(--color-accent-primary)]"
+ aria-hidden="true"
+ />
+ <div className="flex-1 text-[var(--color-text-primary)]">
+ This index was built by an older repowise. It still works, but a reindex is
+ recommended to pick up the latest format.
+ {command && (
+ <>
+ {" "}
+ <code className="rounded bg-[var(--color-bg-elevated)] px-1.5 py-0.5 text-xs">
+ {command}
+ </code>
+ </>
+ )}
+ </div>
+ <button
+ type="button"
+ onClick={dismiss}
+ aria-label="Dismiss"
+ className="rounded p-1 text-[var(--color-text-tertiary)] hover:bg-[var(--color-bg-elevated)] hover:text-[var(--color-text-primary)]"
+ >
+ <X className="h-4 w-4" />
+ </button>
+ </div>
+ );
+}
diff --git a/packages/web/src/components/layout/sidebar.tsx b/packages/web/src/components/layout/sidebar.tsx
index 4ea41f92f..589a1d167 100644
--- a/packages/web/src/components/layout/sidebar.tsx
+++ b/packages/web/src/components/layout/sidebar.tsx
@@ -24,6 +24,7 @@ import { Separator } from "@repowise-dev/ui/ui/separator";
import { Tooltip, TooltipContent, TooltipTrigger } from "@repowise-dev/ui/ui/tooltip";
import { ThemeToggle } from "@repowise-dev/ui/shared/theme-toggle";
import { AddRepoDialog } from "@/components/repos/add-repo-dialog";
+import { VersionFooter } from "./version-footer";
import type { RepoResponse, WorkspaceResponse } from "@/lib/api/types";
interface SidebarProps {
@@ -353,9 +354,7 @@ export function Sidebar({ repos = [], activeRepoId, workspace }: SidebarProps) {
{!isIconOnly && (
<div className="flex flex-col gap-3 border-t border-[var(--color-border-default)] px-4 py-3">
<ThemeToggle className="w-full justify-between" />
- <p className="text-xs text-[var(--color-text-tertiary)]">
- repowise v0.21.0
- </p>
+ <VersionFooter />
</div>
)}
</aside>
diff --git a/packages/web/src/components/layout/upgrade-banner.tsx b/packages/web/src/components/layout/upgrade-banner.tsx
new file mode 100644
index 000000000..67566bae1
--- /dev/null
+++ b/packages/web/src/components/layout/upgrade-banner.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { ArrowUpCircle, X } from "lucide-react";
+import { useMetaVersion } from "@/lib/hooks/use-meta-version";
+import { WhatsNewModal } from "./whats-new-modal";
+
+const STORAGE_PREFIX = "repowise:upgrade-banner-dismissed:v";
+
+/**
+ * Global, non-blocking "newer release available" banner. Dismissal is keyed per
+ * version, so a fresh release re-shows it once. Never an error if the version
+ * check fails - it simply renders nothing.
+ */
+export function UpgradeBanner() {
+ const { meta } = useMetaVersion();
+ const [dismissed, setDismissed] = useState(true);
+ const [showWhatsNew, setShowWhatsNew] = useState(false);
+
+ const latest = meta?.latest_version ?? null;
+ const updateAvailable = meta?.update_available === true && latest !== null;
+
+ useEffect(() => {
+ if (!updateAvailable || typeof window === "undefined") return;
+ try {
+ setDismissed(!!window.localStorage.getItem(STORAGE_PREFIX + latest));
+ } catch {
+ setDismissed(false);
+ }
+ }, [updateAvailable, latest]);
+
+ if (!updateAvailable || dismissed) return null;
+
+ const dismiss = () => {
+ try {
+ window.localStorage.setItem(STORAGE_PREFIX + latest, "1");
+ } catch {
+ /* localStorage unavailable - hide for this session only. */
+ }
+ setDismissed(true);
+ };
+
+ return (
+ <>
+ <div
+ role="status"
+ className="flex items-center gap-3 border-b border-[var(--color-border-default)] bg-[var(--color-accent-muted)] px-4 py-2 text-sm"
+ >
+ <ArrowUpCircle
+ className="h-4 w-4 shrink-0 text-[var(--color-accent-primary)]"
+ aria-hidden="true"
+ />
+ <p className="flex-1 text-[var(--color-text-primary)]">
+ repowise <span className="font-medium">v{latest}</span> is available
+ {meta?.server_version ? (
+ <span className="text-[var(--color-text-tertiary)]"> (you have v{meta.server_version})</span>
+ ) : null}
+ .{" "}
+ {meta?.upgrade_command && (
+ <code className="rounded bg-[var(--color-bg-elevated)] px-1.5 py-0.5 text-xs">
+ {meta.upgrade_command}
+ </code>
+ )}{" "}
+ <button
+ type="button"
+ onClick={() => setShowWhatsNew(true)}
+ className="text-[var(--color-accent-primary)] underline underline-offset-2 hover:opacity-80"
+ >
+ What&apos;s new
+ </button>
+ </p>
+ <button
+ type="button"
+ onClick={dismiss}
+ aria-label="Dismiss"
+ className="rounded p-1 text-[var(--color-text-tertiary)] hover:bg-[var(--color-bg-elevated)] hover:text-[var(--color-text-primary)]"
+ >
+ <X className="h-4 w-4" />
+ </button>
+ </div>
+ <WhatsNewModal open={showWhatsNew} onOpenChange={setShowWhatsNew} />
+ </>
+ );
+}
diff --git a/packages/web/src/components/layout/version-footer.tsx b/packages/web/src/components/layout/version-footer.tsx
new file mode 100644
index 000000000..a47cbc2ba
--- /dev/null
+++ b/packages/web/src/components/layout/version-footer.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import { useState } from "react";
+import { useMetaVersion } from "@/lib/hooks/use-meta-version";
+import { WhatsNewModal } from "./whats-new-modal";
+
+/**
+ * Dynamic version label for the sidebar / mobile-nav footers. Shows the running
+ * server version (falling back to a static label until it loads) and an
+ * "update available" dot that opens the what's-new view.
+ */
+export function VersionFooter() {
+ const { meta } = useMetaVersion();
+ const [showWhatsNew, setShowWhatsNew] = useState(false);
+
+ const version = meta?.server_version;
+ const updateAvailable = meta?.update_available === true;
+
+ return (
+ <>
+ <button
+ type="button"
+ onClick={() => setShowWhatsNew(true)}
+ className="flex items-center gap-1.5 text-xs text-[var(--color-text-tertiary)] hover:text-[var(--color-text-secondary)]"
+ >
+ <span>repowise{version ? ` v${version}` : ""}</span>
+ {updateAvailable && (
+ <span
+ className="h-1.5 w-1.5 rounded-full bg-[var(--color-accent-primary)]"
+ aria-label="Update available"
+ />
+ )}
+ </button>
+ <WhatsNewModal open={showWhatsNew} onOpenChange={setShowWhatsNew} />
+ </>
+ );
+}
diff --git a/packages/web/src/components/layout/whats-new-modal.tsx b/packages/web/src/components/layout/whats-new-modal.tsx
new file mode 100644
index 000000000..7dca6c387
--- /dev/null
+++ b/packages/web/src/components/layout/whats-new-modal.tsx
@@ -0,0 +1,79 @@
+"use client";
+
+import {
+ Dialog,
+ DialogContent,
+ DialogHeader,
+ DialogTitle,
+} from "@repowise-dev/ui/ui/dialog";
+import { useChangelog } from "@/lib/hooks/use-meta-version";
+
+export interface WhatsNewModalProps {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+}
+
+/** Renders repowise's recent release notes from the bundled changelog. */
+export function WhatsNewModal({ open, onOpenChange }: WhatsNewModalProps) {
+ // Only fetch once the modal is opened.
+ const { entries, error, isLoading } = useChangelog(open);
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent className="max-h-[80vh] overflow-y-auto sm:max-w-2xl">
+ <DialogHeader>
+ <DialogTitle>What&apos;s new in repowise</DialogTitle>
+ </DialogHeader>
+
+ {isLoading && (
+ <p className="text-sm text-[var(--color-text-tertiary)]">Loading release notes...</p>
+ )}
+ {error && (
+ <p className="text-sm text-[var(--color-text-tertiary)]">
+ Release notes unavailable.{" "}
+ <a
+ href="https://github.com/repowise-dev/repowise/releases"
+ target="_blank"
+ rel="noreferrer"
+ className="text-[var(--color-accent-primary)] underline"
+ >
+ View on GitHub
+ </a>
+ </p>
+ )}
+
+ <div className="space-y-6">
+ {entries.map((entry) => (
+ <section key={entry.version} className="space-y-2">
+ <h3 className="flex items-baseline gap-2">
+ <span className="text-base font-semibold text-[var(--color-text-primary)]">
+ v{entry.version}
+ </span>
+ {entry.label && (
+ <span className="text-xs text-[var(--color-text-tertiary)]">{entry.label}</span>
+ )}
+ </h3>
+ {entry.sections.map((section) => (
+ <div key={section.name} className="space-y-1">
+ <p className="text-xs font-medium uppercase tracking-wide text-[var(--color-text-secondary)]">
+ {section.name}
+ </p>
+ <ul className="list-disc space-y-1 pl-5 text-sm text-[var(--color-text-secondary)]">
+ {section.items.map((item, i) => (
+ <li key={i}>{stripMarkdown(item)}</li>
+ ))}
+ </ul>
+ </div>
+ ))}
+ </section>
+ ))}
+ </div>
+ </DialogContent>
+ </Dialog>
+ );
+}
+
+/** Light touch: drop bold markers so they don't render as literal asterisks. */
+function stripMarkdown(text: string): string {
+ return text.replace(/\*\*/g, "");
+}
diff --git a/packages/web/src/lib/api/meta.ts b/packages/web/src/lib/api/meta.ts
new file mode 100644
index 000000000..6e8c3d5b7
--- /dev/null
+++ b/packages/web/src/lib/api/meta.ts
@@ -0,0 +1,44 @@
+/**
+ * Meta endpoints: repowise version freshness + release changelog.
+ * Powers the upgrade banner, what's-new view, and version footer.
+ */
+
+import { apiGet } from "./client";
+
+export interface MetaVersion {
+ server_version: string;
+ latest_version: string | null;
+ /** null when PyPI could not be reached (distinct from "up to date"). */
+ update_available: boolean | null;
+ upgrade_command: string;
+ store_format_version: number | null;
+ store_compatible: boolean | null;
+ reindex_recommended: boolean;
+ reindex_command: string | null;
+}
+
+export interface ChangelogSection {
+ name: string;
+ items: string[];
+}
+
+export interface ChangelogEntry {
+ version: string;
+ label: string | null;
+ sections: ChangelogSection[];
+}
+
+export interface ChangelogData {
+ entries: ChangelogEntry[];
+}
+
+export async function getMetaVersion(repoId?: string): Promise<MetaVersion> {
+ return apiGet<MetaVersion>(
+ "/api/meta/version",
+ repoId ? { repo_id: repoId } : undefined,
+ );
+}
+
+export async function getChangelog(limit = 20): Promise<ChangelogData> {
+ return apiGet<ChangelogData>("/api/meta/changelog", { limit });
+}
diff --git a/packages/web/src/lib/hooks/use-meta-version.ts b/packages/web/src/lib/hooks/use-meta-version.ts
new file mode 100644
index 000000000..b29713a0e
--- /dev/null
+++ b/packages/web/src/lib/hooks/use-meta-version.ts
@@ -0,0 +1,30 @@
+"use client";
+
+import useSWR from "swr";
+import { getChangelog, getMetaVersion } from "@/lib/api/meta";
+
+const SWR_OPTS = { revalidateOnFocus: false, revalidateOnReconnect: false };
+
+/**
+ * Server version + PyPI freshness. Shared key so the banner and the version
+ * footer dedupe to a single request.
+ */
+export function useMetaVersion() {
+ const { data, error, isLoading } = useSWR(
+ "meta-version",
+ () => getMetaVersion(),
+ // Re-check hourly; the server caches the PyPI lookup so this is cheap.
+ { ...SWR_OPTS, refreshInterval: 60 * 60 * 1000 },
+ );
+ return { meta: data ?? null, error: (error as Error | undefined) ?? null, isLoading };
+}
+
+/** Changelog entries. Fetched lazily (pass enabled=false until the view opens). */
+export function useChangelog(enabled: boolean, limit = 20) {
+ const { data, error, isLoading } = useSWR(
+ enabled ? ["changelog", limit] : null,
+ () => getChangelog(limit),
+ SWR_OPTS,
+ );
+ return { entries: data?.entries ?? [], error: (error as Error | undefined) ?? null, isLoading };
+}
diff --git a/pyproject.toml b/pyproject.toml
index 12347dad5..8375bff8c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -136,10 +136,11 @@ namespaces = true
[tool.setuptools.package-data]
"repowise.core.ingestion" = ["queries/*.scm"]
"repowise.core.generation" = ["templates/*.j2"]
-# Bundled copy of docs/CHANGELOG.md so `repowise whats-new` and the post-upgrade
-# panel work offline from the installed wheel. Kept in sync with the canonical
-# docs/CHANGELOG.md by a drift-guard test (see tests/unit/upgrade).
-"repowise.cli" = ["_data/CHANGELOG.md"]
+# Bundled copy of docs/CHANGELOG.md so the CLI `whats-new` / post-upgrade panel
+# and the web what's-new view work offline from the installed wheel. Lives in
+# core (the neutral home shared by cli + server). Kept in sync with the
+# canonical docs/CHANGELOG.md by a drift-guard test (see tests/unit/upgrade).
+"repowise.core.upgrade" = ["_data/CHANGELOG.md"]
# ---------------------------------------------------------------------------
# uv workspace (kept for local development)
diff --git a/tests/unit/server/conftest.py b/tests/unit/server/conftest.py
index d9533c444..b01875413 100644
--- a/tests/unit/server/conftest.py
+++ b/tests/unit/server/conftest.py
@@ -37,6 +37,7 @@ def _create_test_app():
graph,
health,
jobs,
+ meta,
modules,
owners,
pages,
@@ -75,6 +76,7 @@ def _create_test_app():
app.include_router(symbols.router)
app.include_router(graph.router)
app.include_router(c4.router)
+ app.include_router(meta.router)
app.include_router(webhooks.router)
app.include_router(git.router)
app.include_router(dead_code.router)
diff --git a/tests/unit/server/test_meta_api.py b/tests/unit/server/test_meta_api.py
new file mode 100644
index 000000000..4fb1988a2
--- /dev/null
+++ b/tests/unit/server/test_meta_api.py
@@ -0,0 +1,91 @@
+"""Tests for the /api/meta endpoints (version freshness + changelog)."""
+
+from __future__ import annotations
+
+import pytest
+from httpx import AsyncClient
+
+import repowise.core.upgrade.release as rel
+
+
[email protected](autouse=True)
+def _stub_pypi(monkeypatch, tmp_path):
+ """Keep these tests offline and deterministic."""
+ monkeypatch.setattr(rel, "_CACHE_PATH", tmp_path / "update-check.json")
+ monkeypatch.setattr(rel, "fetch_latest_version", lambda timeout=2.0: ("9.9.9", None))
+
+
+async def test_version_endpoint(client: AsyncClient) -> None:
+ resp = await client.get("/api/meta/version")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["server_version"]
+ assert body["latest_version"] == "9.9.9"
+ assert body["update_available"] is True
+ assert body["upgrade_command"]
+ # No repo_id -> store fields stay unset.
+ assert body["store_format_version"] is None
+ assert body["reindex_recommended"] is False
+
+
+async def test_version_endpoint_up_to_date(client: AsyncClient, monkeypatch) -> None:
+ from repowise.server import __version__
+
+ monkeypatch.setattr(rel, "fetch_latest_version", lambda timeout=2.0: (__version__, None))
+ resp = await client.get("/api/meta/version")
+ assert resp.status_code == 200
+ assert resp.json()["update_available"] is False
+
+
+async def test_version_endpoint_unknown_when_offline(client: AsyncClient, monkeypatch) -> None:
+ monkeypatch.setattr(rel, "fetch_latest_version", lambda timeout=2.0: (None, "offline"))
+ resp = await client.get("/api/meta/version")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["latest_version"] is None
+ assert body["update_available"] is None
+
+
+async def test_version_endpoint_unknown_repo_id_is_graceful(client: AsyncClient) -> None:
+ """An unresolvable repo_id must not error; store fields stay unset."""
+ resp = await client.get("/api/meta/version", params={"repo_id": "does-not-exist"})
+ assert resp.status_code == 200
+ assert resp.json()["store_format_version"] is None
+
+
+async def test_version_endpoint_populates_store_status(client: AsyncClient, tmp_path) -> None:
+ """A resolvable repo with a state.json fills the store-format fields."""
+ import json
+
+ from tests.unit.server.conftest import create_test_repo
+
+ repo = await create_test_repo(client, tmp_path)
+ repo_dir = tmp_path / "test-repo"
+ (repo_dir / ".repowise").mkdir(parents=True, exist_ok=True)
+ (repo_dir / ".repowise" / "state.json").write_text(
+ json.dumps({"store_format_version": 1, "written_by_version": "0.21.0"}),
+ encoding="utf-8",
+ )
+
+ resp = await client.get("/api/meta/version", params={"repo_id": repo["id"]})
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["store_format_version"] == 1
+ assert body["store_compatible"] is True
+ assert body["reindex_recommended"] is False
+
+
+async def test_changelog_endpoint(client: AsyncClient) -> None:
+ resp = await client.get("/api/meta/changelog", params={"limit": 3})
+ assert resp.status_code == 200
+ entries = resp.json()["entries"]
+ assert 0 < len(entries) <= 3
+ first = entries[0]
+ assert first["version"]
+ assert isinstance(first["sections"], list)
diff --git a/tests/unit/upgrade/test_bundled_changelog_sync.py b/tests/unit/upgrade/test_bundled_changelog_sync.py
index 24cb182c4..4b69a38cb 100644
--- a/tests/unit/upgrade/test_bundled_changelog_sync.py
+++ b/tests/unit/upgrade/test_bundled_changelog_sync.py
@@ -13,9 +13,9 @@ from pathlib import Path
import pytest
-import repowise.cli as cli_pkg
+from repowise.core.upgrade.release import BUNDLED_CHANGELOG_PATH
-_BUNDLED = Path(cli_pkg.__file__).parent / "_data" / "CHANGELOG.md"
+_BUNDLED = BUNDLED_CHANGELOG_PATH
def _source_changelog() -> Path | None:
diff --git a/tests/unit/upgrade/test_release.py b/tests/unit/upgrade/test_release.py
new file mode 100644
index 000000000..9475a8604
--- /dev/null
+++ b/tests/unit/upgrade/test_release.py
@@ -0,0 +1,104 @@
+"""Tests for the shared release-info layer in core (version compare, PyPI cache,
+bundled changelog)."""
+
+from __future__ import annotations
+
+import json
+
+import repowise.core.upgrade.release as rel
+from repowise.core.upgrade.release import (
+ BUNDLED_CHANGELOG_PATH,
+ ReleaseCheck,
+ check_latest_version_cached,
+ is_newer_version,
+ load_bundled_changelog,
+ parse_release,
+)
+
+# --- version compare ------------------------------------------------------
+
+
+def test_is_newer_version():
+ assert is_newer_version("0.22.0", "0.21.0")
+ assert is_newer_version("0.21.2", "0.21") # padded compare
+ assert not is_newer_version("0.21.0", "0.21.0")
+ assert not is_newer_version("0.20.0", "0.21.0")
+
+
+def test_is_newer_version_unparsable_is_false():
+ assert not is_newer_version("garbage", "0.21.0")
+ assert not is_newer_version("0.21.0", "")
+
+
+def test_parse_release_ignores_suffix():
+ assert parse_release("0.15.2-rc1") == (0, 15, 2)
+ assert parse_release("1.2") == (1, 2)
+ assert parse_release("nope") is None
+
+
+# --- bundled changelog ----------------------------------------------------
+
+
+def test_bundled_changelog_exists_and_parses():
+ assert BUNDLED_CHANGELOG_PATH.is_file()
+ entries = load_bundled_changelog()
+ assert len(entries) > 0
+ assert all(e.version for e in entries)
+
+
+# --- cached PyPI check ----------------------------------------------------
+
+
+def _redirect_cache(monkeypatch, tmp_path):
+ monkeypatch.setattr(rel, "_CACHE_PATH", tmp_path / "update-check.json")
+
+
+def test_check_latest_version_cached_miss_then_hit(monkeypatch, tmp_path):
+ _redirect_cache(monkeypatch, tmp_path)
+ calls = {"n": 0}
+
+ def _fetch(timeout=2.0):
+ calls["n"] += 1
+ return "9.9.9", None
+
+ monkeypatch.setattr(rel, "fetch_latest_version", _fetch)
+
+ first = check_latest_version_cached("0.21.0")
+ second = check_latest_version_cached("0.21.0")
+
+ assert calls["n"] == 1 # second served from cache
+ assert isinstance(first, ReleaseCheck)
+ assert first.latest_version == "9.9.9"
+ assert first.update_available is True
+ assert second.update_available is True
+
+
+def test_check_latest_version_cached_recomputes_against_current(monkeypatch, tmp_path):
+ _redirect_cache(monkeypatch, tmp_path)
+ (tmp_path / "update-check.json").write_text(
+ json.dumps({"checked_at": rel.time.time(), "latest_version": "0.21.0", "error": None}),
+ encoding="utf-8",
+ )
+ # Cache hit; latest == current -> no update available.
+ result = check_latest_version_cached("0.21.0")
+ assert result.update_available is False
+
+
+def test_check_latest_version_unknown_when_fetch_fails(monkeypatch, tmp_path):
+ _redirect_cache(monkeypatch, tmp_path)
+ monkeypatch.setattr(rel, "fetch_latest_version", lambda timeout=2.0: (None, "offline"))
+ result = check_latest_version_cached("0.21.0")
+ assert result.latest_version is None
+ assert result.update_available is None
+ assert result.error == "offline"
+
+
+def test_expired_cache_refetches(monkeypatch, tmp_path):
+ _redirect_cache(monkeypatch, tmp_path)
+ (tmp_path / "update-check.json").write_text(
+ json.dumps({"checked_at": 0, "latest_version": "1.0.0", "error": None}),
+ encoding="utf-8",
+ )
+ monkeypatch.setattr(rel, "fetch_latest_version", lambda timeout=2.0: ("9.9.9", None))
+ result = check_latest_version_cached("0.21.0", ttl_hours=24)
+ assert result.latest_version == "9.9.9"