usecli 0.1.78__tar.gz → 0.1.80__tar.gz

{usecli-0.1.78 → usecli-0.1.80}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usecli
-Version: 0.1.78
+Version: 0.1.80
 Summary: A powerful Python CLI framework for building beautiful, developer-friendly command-line tools.
 Author: Edward Boswell
 Author-email: Edward Boswell <thememium@gmail.com>
@@ -245,11 +245,41 @@ about        Show app info
 help         Show help
 init         Initialize usecli (usecli only)
 inspire      Random quote
+upgrade      Upgrade the application to the latest version
 make:command Create new command (usecli only)
 make:theme   Create new theme (usecli only)
 make:bundle  Build a standalone executable with PyInstaller (usecli only)
 ```
 
+### Upgrades
+
+Every CLI built on usecli ships `upgrade`, which detects how the running
+package was installed and delegates to the same package manager — `uv tool`,
+`pipx`, or `pip` — instead of creating a second installation:
+
+```bash
+mycli upgrade --check   # show installed/latest versions and the source
+mycli upgrade           # confirm and install the latest release
+mycli upgrade --force   # skip the prompt and the up-to-date check
+```
+
+The source comes from packaging metadata: PyPI for index installs, and the
+Git remote for PEP 610 `direct_url.json` installs. Override it in
+`usecli.config.toml` when metadata is not enough (private mirrors, missing
+`direct_url.json`, a package name that differs from the command name):
+
+```toml
+[usecli.upgrade]
+enabled = true
+source = "git"                                  # "auto" (default) | "pypi" | "git"
+package = "mycli"                               # optional
+url = "https://github.com/owner/mycli.git"      # required for "git" unless detected
+ref = "main"                                    # branch, tag, or commit
+```
+
+Frozen bundles, editable installs, and commit-pinned installs are reported
+as non-upgradeable with an explanation and manual next step.
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 <!-- ENTRY POINTS & PACKAGING -->
@@ -289,9 +319,14 @@ file is always named `usecli.config.toml`):
 # main.py
 from usecli import run
 
-if __name__ == "__main__":
+
+def main():
     run()  # auto-detect project config
     # run("path/to/usecli.config.toml")          # or point at a specific config
+
+
+if __name__ == "__main__":
+    main()
 ```
 
 Run it in development (no PyInstaller required):
@@ -300,6 +335,14 @@ Run it in development (no PyInstaller required):
 uv run python main.py --help
 ```
 
+To expose the same entry point as a console script, point `[project.scripts]`
+at the `main` function in your `myapp` package (the usual `src/myapp` layout):
+
+```toml
+[project.scripts]
+myapp = "myapp:main"
+```
+
 Because `run()` injects the located config explicitly, a custom `main.py` works
 regardless of whether your CLI also has a `[project.scripts]` entry.
 

{usecli-0.1.78 → usecli-0.1.80}/README.md

@@ -215,11 +215,41 @@ about        Show app info
 help         Show help
 init         Initialize usecli (usecli only)
 inspire      Random quote
+upgrade      Upgrade the application to the latest version
 make:command Create new command (usecli only)
 make:theme   Create new theme (usecli only)
 make:bundle  Build a standalone executable with PyInstaller (usecli only)
 ```
 
+### Upgrades
+
+Every CLI built on usecli ships `upgrade`, which detects how the running
+package was installed and delegates to the same package manager — `uv tool`,
+`pipx`, or `pip` — instead of creating a second installation:
+
+```bash
+mycli upgrade --check   # show installed/latest versions and the source
+mycli upgrade           # confirm and install the latest release
+mycli upgrade --force   # skip the prompt and the up-to-date check
+```
+
+The source comes from packaging metadata: PyPI for index installs, and the
+Git remote for PEP 610 `direct_url.json` installs. Override it in
+`usecli.config.toml` when metadata is not enough (private mirrors, missing
+`direct_url.json`, a package name that differs from the command name):
+
+```toml
+[usecli.upgrade]
+enabled = true
+source = "git"                                  # "auto" (default) | "pypi" | "git"
+package = "mycli"                               # optional
+url = "https://github.com/owner/mycli.git"      # required for "git" unless detected
+ref = "main"                                    # branch, tag, or commit
+```
+
+Frozen bundles, editable installs, and commit-pinned installs are reported
+as non-upgradeable with an explanation and manual next step.
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 <!-- ENTRY POINTS & PACKAGING -->
@@ -259,9 +289,14 @@ file is always named `usecli.config.toml`):
 # main.py
 from usecli import run
 
-if __name__ == "__main__":
+
+def main():
     run()  # auto-detect project config
     # run("path/to/usecli.config.toml")          # or point at a specific config
+
+
+if __name__ == "__main__":
+    main()
 ```
 
 Run it in development (no PyInstaller required):
@@ -270,6 +305,14 @@ Run it in development (no PyInstaller required):
 uv run python main.py --help
 ```
 
+To expose the same entry point as a console script, point `[project.scripts]`
+at the `main` function in your `myapp` package (the usual `src/myapp` layout):
+
+```toml
+[project.scripts]
+myapp = "myapp:main"
+```
+
 Because `run()` injects the located config explicitly, a custom `main.py` works
 regardless of whether your CLI also has a `[project.scripts]` entry.
 

{usecli-0.1.78 → usecli-0.1.80}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.78"
+version = "0.1.80"
 description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
 readme = "README.md"
 requires-python = ">=3.10"

{usecli-0.1.78 → usecli-0.1.80}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.78"
+version = "0.1.80"
 description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
 readme = "README.md"
 authors = [{ name = "Edward Boswell", email = "thememium@gmail.com" }]

{usecli-0.1.78 → usecli-0.1.80}/src/usecli/__init__.py

@@ -274,7 +274,7 @@ def _ensure_cli_initialized() -> None:
                     fail(error.__class__.__name__, str(error), 1)
 
         def invoke(self, ctx):
-            from click.exceptions import Exit
+            from click.exceptions import ClickException, Exit
 
             from usecli.cli.core.runtime import is_json_mode
 
@@ -306,7 +306,9 @@ def _ensure_cli_initialized() -> None:
                 styled_error = UsecliUsageError(e.message, ctx=e.ctx)
                 styled_error.show()
                 sys.exit(styled_error.exit_code)
-            except _TyperClickException as e:
+            # UsecliError extends real-click ClickException, not the vendored
+            # typer._click one — catch both, mirroring the JSON path.
+            except (_TyperClickException, ClickException) as e:
                 if hasattr(e, "show"):
                     e.show()
                 sys.exit(e.exit_code if hasattr(e, "exit_code") else 1)

usecli-0.1.80/src/usecli/cli/commands/defaults/base/upgrade_command.py

@@ -0,0 +1,316 @@
+"""UpgradeCommand - upgrade the running application to the latest version.
+
+A built-in default command available in every generated CLI. Installation
+discovery, checking, and mutation are delegated to
+``usecli.shared.upgrades.UpgradeService``; this command owns only the
+interaction: flag handling, confirmation, and output formatting.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+
+from usecli.cli.config.colors import COLOR
+from usecli.cli.core.base_command import BaseCommand
+from usecli.cli.core.exceptions.base import UsecliError
+from usecli.shared.config.manager import get_config
+from usecli.shared.upgrades import UpgradeService
+from usecli.shared.upgrades.checker import UpgradeStatus
+from usecli.shared.upgrades.discovery import InstallInfo
+from usecli.ui import Confirm
+
+
+class _LazyConsole:
+    _console: Any | None = None
+
+    def _get_console(self) -> Any:
+        if self._console is None:
+            from rich.console import Console
+
+            self._console = Console()
+        return self._console
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._get_console(), name)
+
+
+console = _LazyConsole()
+
+
+def _short_commit(commit: str | None) -> str:
+    """Render a commit id for display; version labels pass through intact."""
+    if not commit:
+        return "-"
+    import re
+
+    if re.fullmatch(r"[0-9a-fA-F]{8,40}", commit):
+        return commit[:7]
+    return commit
+
+
+class UpgradeCommand(BaseCommand):
+    """Upgrade the running application from its original install source."""
+
+    def visible(self) -> bool:
+        config = get_config()
+        return bool(config.get("upgrade.enabled", True))
+
+    def signature(self) -> str:
+        return "upgrade"
+
+    def description(self) -> str:
+        return "Upgrade the application to the latest version"
+
+    def handle(
+        self,
+        check: Annotated[
+            bool,
+            typer.Option(
+                "--check",
+                help="Only check for updates; do not install anything.",
+            ),
+        ] = False,
+        force: Annotated[
+            bool,
+            typer.Option(
+                "--force",
+                help=(
+                    "Upgrade even when already up to date and skip the "
+                    "confirmation prompt."
+                ),
+            ),
+        ] = False,
+    ) -> dict[str, object]:
+        """Handle the command execution."""
+        from usecli.cli.core.runtime import is_json_mode
+
+        config = get_config()
+        install = UpgradeService.discover(config)
+        status = UpgradeService.check(install, config)
+
+        data: dict[str, object] = {
+            "mode": "check" if check else "apply",
+            "package": install.package,
+            "current": install.version,
+            "latest": status.latest,
+            "source": install.source,
+            "source_detail": status.detail,
+            "installer": install.installer,
+            "url": install.url,
+            "revision": install.revision,
+            "commit": install.commit,
+            "pinned": install.pinned,
+            "pinned_reason": install.pinned_reason,
+            "frozen": install.frozen,
+            "update_available": status.update_available,
+            "upgraded": None,
+            "error": status.error,
+            "latest_tag": status.latest_tag,
+            "latest_tag_commit": status.latest_tag_commit,
+            "note": status.note,
+            "pyproject_path": None,
+            "pyproject_previous_version": None,
+            "pyproject_new_version": None,
+            "pyproject_updated": None,
+            "pyproject_reason": None,
+        }
+
+        if check:
+            if status.error:
+                raise UsecliError(
+                    status.error,
+                    suggestion="Check your network connection and try again.",
+                )
+            if is_json_mode():
+                return data
+            self._print_check(status)
+            return data
+
+        # Mutations are impossible for these installations; fail loudly.
+        if (
+            install.frozen
+            or install.pinned
+            or install.source
+            in (
+                "editable",
+                "unknown",
+            )
+        ):
+            raise UsecliError(
+                self._blocked_message(install),
+                suggestion=self._blocked_suggestion(install),
+            )
+
+        if status.error is None and not status.update_available and not force:
+            data["upgraded"] = False
+            data["message"] = "Already up to date."
+            if is_json_mode():
+                return data
+            console.print(
+                f"[{COLOR.INFO}]Already up to date ({install.version}).[/{COLOR.INFO}]"
+            )
+            return data
+
+        if not is_json_mode() and not force:
+            confirmed = Confirm.ask(
+                f"[{COLOR.WARNING}]Upgrade {install.package} from "
+                f"{install.version} to "
+                f"{_short_commit(status.latest) if status.latest else 'latest'}?"
+                f"[/{COLOR.WARNING}]",
+                default=False,
+            )
+            if not confirmed:
+                data["upgraded"] = False
+                data["message"] = "Aborted."
+                console.print(
+                    f"[{COLOR.INFO}]Aborted. Re-run with --force to skip "
+                    f"confirmation.[/{COLOR.INFO}]"
+                )
+                return data
+
+        result = self._run_upgrade(install, config, status)
+        data["upgraded"] = result.success
+        data["message"] = result.message
+
+        if result.pyproject is not None:
+            data["pyproject_path"] = result.pyproject.path
+            data["pyproject_previous_version"] = result.pyproject.previous_version
+            data["pyproject_new_version"] = result.pyproject.new_version
+            data["pyproject_updated"] = result.pyproject.updated
+            data["pyproject_reason"] = result.pyproject.reason
+
+        if not result.success:
+            raise UsecliError(
+                result.message or "Upgrade failed.",
+                suggestion="Run the upgrade command manually.",
+            )
+
+        if is_json_mode():
+            return data
+
+        console.print(f"[{COLOR.SUCCESS}]✓ Upgrade complete.[/{COLOR.SUCCESS}]")
+
+        if result.pyproject is not None:
+            if result.pyproject.updated:
+                console.print(result.pyproject.summary)
+            elif result.pyproject.reason:
+                console.print(
+                    f"[{COLOR.WARNING}]⚠ {result.pyproject.reason}[/{COLOR.WARNING}]"
+                )
+
+        from usecli.cli.core.ui.title import get_project_name
+
+        console.print(
+            f"Run `[bold {COLOR.PRIMARY}]{get_project_name()} --version"
+            f"[/bold {COLOR.PRIMARY}]` to verify."
+        )
+        return data
+
+    def _run_upgrade(
+        self,
+        install: InstallInfo,
+        config: Any,
+        status: UpgradeStatus,
+    ):
+        """Run the upgrade behind a spinner (auto-disabled in JSON mode)."""
+        from usecli import Spinner
+
+        target = status.latest or "latest"
+        with Spinner(f"Upgrading {install.package}") as spinner:
+            spinner.update(
+                f"Upgrading {install.package} ({install.version} → {target})"
+            )
+            return UpgradeService.upgrade(
+                install,
+                config,
+                target_revision=status.latest_tag,
+            )
+
+    def _print_check(self, status: UpgradeStatus) -> None:
+        """Render the non-mutating check report."""
+        install = status.install
+        console.print()
+        console.print(f"[bold {COLOR.PRIMARY}]Upgrade Check[/bold {COLOR.PRIMARY}]")
+        console.print(f"[{COLOR.PRIMARY}]─" * 78)
+        self._print_row("Package", install.package or "unknown")
+        self._print_row("Installed", install.version)
+        self._print_row("Source", status.detail or install.source)
+        if install.source == "git":
+            if install.revision:
+                self._print_row("Ref", install.revision)
+            self._print_row("Commit", _short_commit(install.commit))
+            if status.latest:
+                self._print_row("Latest", _short_commit(status.latest))
+        elif status.latest:
+            self._print_row("Latest", status.latest)
+        self._print_row("Installer", install.installer or "unknown")
+        console.print()
+
+        if install.pinned:
+            console.print(
+                f"[{COLOR.WARNING}]This installation is pinned "
+                f"({install.pinned_reason}); no automatic upgrade."
+                f"[/{COLOR.WARNING}]"
+            )
+        elif status.update_available:
+            from usecli.cli.core.ui.title import get_project_name
+
+            console.print(
+                f"[{COLOR.SUCCESS}]Update available: {install.version} → "
+                f"{_short_commit(status.latest)}. Run "
+                f"`{get_project_name()} upgrade` to update.[/{COLOR.SUCCESS}]"
+            )
+        else:
+            if status.note:
+                console.print(f"[{COLOR.INFO}]{status.note}[/{COLOR.INFO}]")
+            else:
+                console.print(f"[{COLOR.INFO}]You are up to date.[/{COLOR.INFO}]")
+        console.print()
+
+    def _print_row(self, label: str, value: str) -> None:
+        visible_value = console.render_str(value).plain
+        right_align_column = 76
+        indent_width = 2
+        padding_spaces = 2
+        dots_length = (
+            right_align_column
+            - indent_width
+            - len(label)
+            - padding_spaces
+            - len(visible_value)
+        )
+        dots = "." * max(dots_length, 1)
+        console.print(
+            f"  [{COLOR.FOREGROUND}]{label}[/{COLOR.FOREGROUND}] {dots} {value}"
+        )
+
+    def _blocked_message(self, install: InstallInfo) -> str:
+        if install.frozen:
+            return "This application runs from a frozen bundle and cannot self-upgrade."
+        if install.source == "editable":
+            return "This is an editable install and cannot self-upgrade."
+        if install.pinned:
+            return (
+                f"This installation is pinned ({install.pinned_reason}) and "
+                "will not automatically upgrade."
+            )
+        return (
+            "Could not determine how this application was installed; "
+            "automatic upgrade is unavailable."
+        )
+
+    def _blocked_suggestion(self, install: InstallInfo) -> str:
+        if install.frozen:
+            return "Download the latest release or rebuild the bundle."
+        if install.source == "editable":
+            return "Update the source repository and re-sync (e.g. `uv sync`)."
+        if install.source == "git" and install.url:
+            revision = f"@{install.revision}" if install.revision else ""
+            return (
+                "Reinstall from the source you want, e.g. "
+                f'`uv tool install --force "{install.package} @ '
+                f'git+{install.url}{revision}"`.'
+            )
+        return "Reinstall the package with your package manager to upgrade."

{usecli-0.1.78 → usecli-0.1.80}/src/usecli/cli/templates/usecli.config.toml.j2

@@ -9,3 +9,13 @@ templates_dir = "{{ templates_dir | default('cli/templates') }}"
 themes_dir = "{{ themes_dir | default('cli/themes') }}"
 theme = "{{ theme | default('default') }}"
 hide_inspire = {{ hide_inspire | default(false) | lower }}
+
+[usecli.upgrade]
+enabled = {{ upgrade_enabled | default(true) | lower }}
+# Where upgrades come from: "auto" (detect from install metadata), "pypi", or "git".
+source = "{{ upgrade_source | default('auto') }}"
+# Git only: repository URL. Falls back to the URL in the install metadata.
+# url = "https://github.com/owner/repo.git"
+# Optional: distribution name and Git ref (branch, tag, or commit) overrides.
+# package = "my-cli"
+# ref = "main"

{usecli-0.1.78 → usecli-0.1.80}/src/usecli/entry.py

@@ -5,9 +5,12 @@ thin ``main.py``::
 
     from usecli import run
 
-    if __name__ == "__main__":
+    def main():
         run()                         # auto-detect the project config
-        run("my/custom/cli.toml")     # or point at a specific config
+        # run("my/custom/cli.toml")   # or point at a specific config
+
+    if __name__ == "__main__":
+        main()
 
 It works in three contexts:
 

{usecli-0.1.78 → usecli-0.1.80}/src/usecli/shared/config/manager.py

@@ -284,6 +284,16 @@ class ConfigManager:
         "environment": "prod",
         "command_name": "usecli",
         "hide_inspire": False,
+        # The built-in `upgrade` command reads [usecli.upgrade]. `source`
+        # overrides install-source detection: "auto" (packaging metadata),
+        # "pypi", or "git" (with `package`/`url`/`ref` overrides).
+        "upgrade": {
+            "enabled": True,
+            "source": "auto",
+            "package": None,
+            "url": None,
+            "ref": None,
+        },
     }
 
     def __init__(
@@ -320,7 +330,8 @@ class ConfigManager:
         # find_project_root discovery (up-walk + bounded rglob tree search) that
         # would otherwise be spent rediscovering it. Derive the project root
         # from the config's own directory instead.
-        if usecli_config_path is None:
+        # Unreachable: the normalization above guarantees a Path here.
+        if usecli_config_path is None:  # pragma: no cover
             detected_root = find_project_root(start_dir)
         else:
             detected_root = None
@@ -328,7 +339,7 @@ class ConfigManager:
             config_parent = self.usecli_config_path.parent
             if detected_root is None:
                 detected_root = config_parent
-            else:
+            else:  # pragma: no cover - detected_root is always None here
                 root_config = detected_root / USECLI_CONFIG_TOML
                 if self.usecli_config_path.resolve() != root_config.resolve():
                     detected_root = config_parent

usecli-0.1.80/src/usecli/shared/upgrades/__init__.py

@@ -0,0 +1,22 @@
+"""Reusable self-upgrade machinery for usecli applications.
+
+Every generated CLI inherits a built-in ``upgrade`` command built on this
+package. Installations are classified from standard packaging metadata
+(``INSTALLER`` and PEP 610 ``direct_url.json``) — no CLI-author
+configuration required.
+"""
+
+from usecli.shared.upgrades.checker import UpgradeStatus
+from usecli.shared.upgrades.discovery import InstallInfo, InstallSource
+from usecli.shared.upgrades.installer import UpgradeResult
+from usecli.shared.upgrades.pyproject import PyprojectUpdate
+from usecli.shared.upgrades.service import UpgradeService
+
+__all__ = [
+    "InstallInfo",
+    "InstallSource",
+    "PyprojectUpdate",
+    "UpgradeResult",
+    "UpgradeService",
+    "UpgradeStatus",
+]