Merge pull request #1831 from transformerlab/fix/cli-local-install-upgrade-hint

Warn when CLI is installed from a non-PyPI source

Author: aliasaria

cli/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "transformerlab-cli"
-version = "0.0.17"
+version = "0.0.18"
 description = "Transformer Lab CLI"
 requires-python = ">=3.10"
 authors = [{ name = "Transformer Lab", email = "hello@transformerlab.ai" }]

cli/src/transformerlab_cli/commands/version.py

@@ -11,10 +11,17 @@
 @app.command()
 def version() -> None:
     """Display the CLI version and check for updates."""
-    from transformerlab_cli.util.pypi import fetch_latest_version, get_installed_version, _parse_version
+    from transformerlab_cli.util.pypi import (
+        _parse_version,
+        describe_install_source,
+        fetch_latest_version,
+        get_install_source,
+        get_installed_version,
+    )
 
     installed = get_installed_version()
     latest = fetch_latest_version()
+    source = get_install_source()
 
     # Determine state: update available, up to date, or check failed
     update_available = False
@@ -29,18 +36,33 @@ def version() -> None:
         data: dict[str, object] = {"installed_version": installed, "update_available": update_available}
         if update_available:
             data["latest_version"] = latest
-            data["upgrade_command"] = "uv tool upgrade transformerlab-cli"
+            data["upgrade_command"] = (
+                "uv tool install --force transformerlab-cli"
+                if source is not None
+                else "uv tool upgrade transformerlab-cli"
+            )
+        if source is not None:
+            data["install_source"] = source
         if not check_succeeded:
             data["check_succeeded"] = False
         print(json.dumps(data))
     else:
         console.print(f"v{installed}", highlight=False)
         if update_available:
-            console.print(
-                f"[yellow]Update available:[/yellow] v{latest}\n"
-                f"Run [bold]uv tool upgrade transformerlab-cli[/bold] to upgrade."
-            )
+            console.print(f"[yellow]Update available:[/yellow] v{latest}")
+            if source is None:
+                console.print("Run [bold]uv tool upgrade transformerlab-cli[/bold] to upgrade.")
+            else:
+                console.print(
+                    f"[yellow]Installed from {describe_install_source(source)}[/yellow]\n"
+                    f"[dim]`uv tool upgrade` resolves against this source, not PyPI — "
+                    f"it won't fetch v{latest}.\n"
+                    f"Pull source updates, or run "
+                    f"[bold]uv tool install --force transformerlab-cli[/bold] to switch to PyPI.[/dim]"
+                )
         elif check_succeeded:
             console.print("[green]You are up to date.[/green]")
+            if source is not None:
+                console.print(f"[dim]Installed from {describe_install_source(source)}[/dim]")
         else:
             console.print("[dim]Could not check for updates.[/dim]")

cli/src/transformerlab_cli/util/pypi.py

@@ -3,7 +3,7 @@
 import json
 import os
 import time
-from importlib.metadata import PackageNotFoundError
+from importlib.metadata import PackageNotFoundError, distribution
 from importlib.metadata import version as pkg_version
 
 import httpx
@@ -13,16 +13,52 @@
 PYPI_URL = "https://pypi.org/pypi/transformerlab-cli/json"
 CACHE_FILE = os.path.join(CONFIG_DIR, ".version_cache.json")
 CACHE_TTL_SECONDS = 4 * 60 * 60  # 4 hours
+PACKAGE_NAME = "transformerlab-cli"
 
 
 def get_installed_version() -> str:
     """Return the installed CLI version from package metadata, or 'unknown'."""
     try:
-        return pkg_version("transformerlab-cli")
+        return pkg_version(PACKAGE_NAME)
     except PackageNotFoundError:
         return "unknown"
 
 
+def get_install_source() -> dict | None:
+    """Return PEP 610 direct_url.json contents for non-PyPI installs, else None.
+
+    PyPI installs have no direct_url.json. Local paths, editable installs, and
+    VCS (git) installs do — so its presence means `uv tool upgrade` will resolve
+    against that source rather than PyPI.
+    """
+    try:
+        dist = distribution(PACKAGE_NAME)
+        raw = dist.read_text("direct_url.json")
+        if raw is None:
+            return None
+        return json.loads(raw)
+    except Exception:
+        return None
+
+
+def describe_install_source(direct_url: dict) -> str:
+    """Human-readable description of a direct_url.json entry."""
+    url = direct_url.get("url", "") or ""
+    dir_info = direct_url.get("dir_info") or {}
+    vcs_info = direct_url.get("vcs_info") or {}
+
+    if vcs_info:
+        vcs = vcs_info.get("vcs", "vcs")
+        commit = (vcs_info.get("commit_id") or "")[:7]
+        suffix = f" @ {commit}" if commit else ""
+        return f"{vcs}: {url}{suffix}"
+    if url.startswith("file://"):
+        path = url[len("file://") :]
+        kind = "editable directory" if dir_info.get("editable") else "local directory"
+        return f"{kind}: {path}"
+    return url or "unknown source"
+
+
 def _parse_version(v: str) -> tuple[int, ...]:
     """Parse a PEP 440 version string into a tuple of ints for comparison.
 

cli/src/transformerlab_cli/util/version_check.py

@@ -7,21 +7,32 @@
 def check_for_update(console: Console) -> None:
     """Check if a newer CLI version is available on PyPI and print a banner if so."""
     try:
-        from transformerlab_cli.util.pypi import is_update_available
+        from transformerlab_cli.util.pypi import (
+            describe_install_source,
+            get_install_source,
+            is_update_available,
+        )
 
         installed, latest = is_update_available()
         if latest is None:
             return
 
-        console.print(
-            Panel(
-                f"[yellow]Update available![/yellow] "
-                f"You are running [bold]v{installed}[/bold], but [bold]v{latest}[/bold] is available.\n"
-                f"Run [bold]uv tool upgrade transformerlab-cli[/bold] to upgrade.",
-                border_style="yellow",
-                expand=False,
-            )
+        source = get_install_source()
+        header = (
+            f"[yellow]Update available![/yellow] "
+            f"You are running [bold]v{installed}[/bold], but [bold]v{latest}[/bold] is available."
         )
+        if source is None:
+            body = f"{header}\nRun [bold]uv tool upgrade transformerlab-cli[/bold] to upgrade."
+        else:
+            body = (
+                f"{header}\n"
+                f"[dim]Installed from {describe_install_source(source)} — "
+                f"`uv tool upgrade` won't fetch PyPI.\n"
+                f"Run [bold]uv tool install --force transformerlab-cli[/bold] to switch to PyPI.[/dim]"
+            )
+
+        console.print(Panel(body, border_style="yellow", expand=False))
     except Exception:
         # Never let version check failures interrupt CLI usage
         pass

cli/tests/test_pypi_cache.py

@@ -9,7 +9,9 @@
     _parse_version,
     _read_cache,
     _write_cache,
+    describe_install_source,
     fetch_latest_version,
+    get_install_source,
     is_update_available,
 )
 
@@ -144,3 +146,44 @@ def test_is_update_available_unknown_version():
         installed, latest = is_update_available()
     assert installed == "unknown"
     assert latest is None
+
+
+def test_get_install_source_pypi_returns_none():
+    """A PyPI install has no direct_url.json, so get_install_source returns None."""
+    mock_dist = MagicMock()
+    mock_dist.read_text.return_value = None
+    with patch("transformerlab_cli.util.pypi.distribution", return_value=mock_dist):
+        assert get_install_source() is None
+
+
+def test_get_install_source_local_path():
+    """A local-path install returns parsed direct_url.json contents."""
+    payload = {"url": "file:///Users/alice/project/cli", "dir_info": {"editable": False}}
+    mock_dist = MagicMock()
+    mock_dist.read_text.return_value = json.dumps(payload)
+    with patch("transformerlab_cli.util.pypi.distribution", return_value=mock_dist):
+        assert get_install_source() == payload
+
+
+def test_get_install_source_package_not_found():
+    """Never raises — returns None if the package metadata lookup fails."""
+    with patch("transformerlab_cli.util.pypi.distribution", side_effect=Exception("missing")):
+        assert get_install_source() is None
+
+
+def test_describe_install_source_local():
+    payload = {"url": "file:///Users/alice/project/cli", "dir_info": {"editable": False}}
+    assert describe_install_source(payload) == "local directory: /Users/alice/project/cli"
+
+
+def test_describe_install_source_editable():
+    payload = {"url": "file:///Users/alice/project/cli", "dir_info": {"editable": True}}
+    assert describe_install_source(payload) == "editable directory: /Users/alice/project/cli"
+
+
+def test_describe_install_source_vcs():
+    payload = {
+        "url": "https://github.com/example/repo",
+        "vcs_info": {"vcs": "git", "commit_id": "abcdef1234567890"},
+    }
+    assert describe_install_source(payload) == "git: https://github.com/example/repo @ abcdef1"