fix cache handling for upgrade, cleanup docs and version output

Author: pirate

README.md

@@ -101,14 +101,6 @@ abxpkg uninstall yt-dlp
 abxpkg load yt-dlp
 ```
 
-Hidden aliases are also available:
-
-```bash
-abxpkg add yt-dlp       # alias for install
-abxpkg upgrade yt-dlp   # alias for update
-abxpkg remove yt-dlp    # alias for uninstall
-```
-
 `abxpkg --version` and `abxpkg version` stream the package version first, then a host/env summary line, then one section per selected provider showing its current resolved runtime state (`INSTALLER_BINARY`, `PATH`, `ENV`, `install_root`, `bin_dir`, and any active cached dependency / installed binaries).
 
 `abxpkg version <binary>` is a thin alias for `abxpkg load <binary>`.
@@ -206,7 +198,7 @@ abx --min-version=2024.1.1 --min-release-age=0 yt-dlp --help
 | `--dry-run[=BOOL]` | `bool` | Show installer commands without executing them. Bare `--dry-run` = `True`. |
 | `--debug[=BOOL]` | `bool` | Emit DEBUG logs to `stderr`. Bare `--debug` = `True`. Defaults to `ABXPKG_DEBUG` or `False`. |
 
-Every value-taking flag also accepts the literal string `None` / `null` / `nil` / `""` to reset to the provider's built-in default (or its env-var-backed default). The precedence is: explicit per-subcommand flag > group-level flag > environment variable > built-in default.
+Every value-taking flag also accepts the literal string `None` / `null` / `""` to reset to the provider's default resolution path. For `postinstall_scripts` / `min_release_age`, that means the action-specific effective default for that provider (`False` / `7` on supporting providers, `True` / `0` otherwise). The precedence is: explicit per-subcommand flag > group-level flag > environment variable > built-in default.
 
 #### Select specific providers / re-order provider precedence
 
@@ -609,8 +601,8 @@ All abxpkg env vars are read once at import time and only apply when set. Explic
 | `ABXPKG_DEBUG` | `0` | Enables DEBUG-level CLI logging on `stderr` for `abxpkg` / `abx`. The matching CLI flag is `--debug`. Default CLI logging level is `INFO`. |
 | `ABXPKG_INSTALL_TIMEOUT` | `120` | Seconds to wait for `install()` / `update()` / `uninstall()` handler subprocesses. |
 | `ABXPKG_VERSION_TIMEOUT` | `10` | Seconds to wait for version / metadata probes (`--version`, `npm show`, `pip show`, etc.). |
-| `ABXPKG_POSTINSTALL_SCRIPTS` | unset | Hydrates the provider-level default for the `postinstall_scripts` kwarg on every provider that supports it (`pip`, `uv`, `npm`, `pnpm`, `yarn`, `bun`, `deno`, `brew`, `chromewebstore`, `puppeteer`). |
-| `ABXPKG_MIN_RELEASE_AGE` | `7` | Hydrates the provider-level default (in days) for the `min_release_age` kwarg on every provider that supports it (`pip`, `uv`, `npm`, `pnpm`, `yarn`, `bun`, `deno`). |
+| `ABXPKG_POSTINSTALL_SCRIPTS` | unset | Hydrates the provider-level default for the `postinstall_scripts` kwarg on every provider that supports it (`pip`, `uv`, `npm`, `pnpm`, `yarn`, `bun`, `deno`, `brew`, `chromewebstore`, `puppeteer`). When left unset, action execution resolves to the provider/action default (`False` on supporting providers, `True` otherwise). |
+| `ABXPKG_MIN_RELEASE_AGE` | `7` | Hydrates the provider-level default (in days) for the `min_release_age` kwarg on every provider that supports it (`pip`, `uv`, `npm`, `pnpm`, `yarn`, `bun`, `deno`). When left unset, action execution resolves to the provider/action default (`7` on supporting providers, `0` otherwise). |
 | `ABXPKG_BINPROVIDERS` | shared default order | Comma-separated list of provider names to enable (and their order) for the `abxpkg` CLI. By default this uses `DEFAULT_PROVIDER_NAMES` from `abxpkg.__init__` (which excludes `ansible` / `pyinfra`, and also excludes `apt` on macOS). |
 
 **Install-root controls** (one global default + one per-provider override):
@@ -680,7 +672,7 @@ dry_run = False                      # or ABXPKG_DRY_RUN=1 / DRY_RUN=1
 - `no_cache`: use `--no-cache` / `ABXPKG_NO_CACHE=1` on the CLI, or pass `no_cache=True` directly to `load()` / `install()` / `update()` / `uninstall()`. For `install()`, this skips the initial `load()` check and forces a fresh install path.
 - `install_timeout`: shared provider-level timeout used by `install()`, `update()`, and `uninstall()` handler execution paths. Can also be set with `ABXPKG_INSTALL_TIMEOUT`.
 - `version_timeout`: shared provider-level timeout used by version / metadata probes such as `--version`, `npm show`, `npm list`, `pip show`, `go version -m`, and brew lookups. Can also be set with `ABXPKG_VERSION_TIMEOUT`.
-- `postinstall_scripts` and `min_release_age` are standard provider/binary/action kwargs, but only supporting providers hydrate default values from `ABXPKG_POSTINSTALL_SCRIPTS` and `ABXPKG_MIN_RELEASE_AGE`.
+- `postinstall_scripts` and `min_release_age` are standard provider/binary/action kwargs. Supporting providers hydrate defaults from `ABXPKG_POSTINSTALL_SCRIPTS` and `ABXPKG_MIN_RELEASE_AGE`; when those remain unset/`None`, install/update/uninstall resolve them to effective action defaults (`False` / `7` on supporting providers, `True` / `0` otherwise).
 - Providers that do not support one of those controls leave the provider default as `None`. If you pass an explicit unsupported value during `install()` / `update()`, it is logged as a warning and ignored.
 - Precedence is: explicit action args > `Binary(...)` defaults > provider defaults.
 

abxpkg/binprovider.py

@@ -1327,6 +1327,7 @@ def has_cached_binary(self, bin_name: BinName) -> bool:
             cached_provider_name = cache_value.get("provider_name")
             cached_bin_name = cache_value.get("bin_name")
             cached_abspath = cache_value.get("abspath")
+            cache_kind = cache_value.get("cache_kind")
             if not isinstance(cached_provider_name, str) or not isinstance(
                 cached_bin_name,
                 str,
@@ -1343,6 +1344,14 @@ def has_cached_binary(self, bin_name: BinName) -> bool:
                 or not isinstance(cached_abspath, str)
             ):
                 continue
+            if not isinstance(cache_kind, str):
+                cache_kind = (
+                    "dependency"
+                    if str(cached_bin_name) == str(self.INSTALLER_BIN)
+                    else "binary"
+                )
+            if cache_kind != "binary":
+                continue
             cached_path = Path(cached_abspath)
             if not (cached_path.exists() or cached_path.is_symlink()):
                 cache.pop(cache_key, None)
@@ -1353,6 +1362,138 @@ def has_cached_binary(self, bin_name: BinName) -> bool:
             save_derived_cache(derived_env_path, cache)
         return has_valid_cache
 
+    @log_method_call(include_result=True)
+    def depends_on_binaries(self) -> list[ShallowBinary]:
+        derived_env_path = self.derived_env_path
+        if derived_env_path is None or not derived_env_path.is_file():
+            return []
+        cache = load_derived_cache(derived_env_path)
+        dependencies: list[ShallowBinary] = []
+        seen: set[tuple[str, str, str]] = set()
+        for cache_key, cache_value in sorted(cache.items()):
+            if not isinstance(cache_value, dict):
+                continue
+            cached_provider_name = cache_value.get("provider_name")
+            cached_bin_name = cache_value.get("bin_name")
+            cached_abspath = cache_value.get("abspath")
+            cache_kind = cache_value.get("cache_kind")
+            if (
+                not isinstance(cached_provider_name, str)
+                or not isinstance(cached_bin_name, str)
+                or not isinstance(cached_abspath, str)
+            ):
+                try:
+                    cached_provider_name, cached_bin_name, cached_abspath = json.loads(
+                        cache_key,
+                    )
+                except Exception:
+                    continue
+            if cached_provider_name != self.name or not isinstance(cached_abspath, str):
+                continue
+            if not isinstance(cache_kind, str):
+                cache_kind = (
+                    "dependency"
+                    if str(cached_bin_name) == str(self.INSTALLER_BIN)
+                    else "binary"
+                )
+            if cache_kind != "dependency":
+                continue
+            loaded = self.load_cached_binary(cached_bin_name, Path(cached_abspath))
+            if loaded is None or loaded.loaded_abspath is None:
+                continue
+            resolved_provider = loaded.loaded_binprovider or self
+            dedupe_key = (
+                loaded.name,
+                str(loaded.loaded_abspath),
+                resolved_provider.name,
+            )
+            if dedupe_key in seen:
+                continue
+            seen.add(dedupe_key)
+            dependencies.append(
+                ShallowBinary.model_validate(
+                    {
+                        "name": loaded.name,
+                        "description": loaded.description,
+                        "binprovider": resolved_provider,
+                        "abspath": loaded.loaded_abspath,
+                        "version": loaded.loaded_version,
+                        "sha256": loaded.loaded_sha256,
+                        "mtime": loaded.loaded_mtime,
+                        "euid": loaded.loaded_euid,
+                        "binproviders": [resolved_provider],
+                        "overrides": loaded.overrides,
+                    },
+                ),
+            )
+        return dependencies
+
+    @log_method_call(include_result=True)
+    def installed_binaries(self) -> list[ShallowBinary]:
+        derived_env_path = self.derived_env_path
+        if derived_env_path is None or not derived_env_path.is_file():
+            return []
+        cache = load_derived_cache(derived_env_path)
+        binaries: list[ShallowBinary] = []
+        seen: set[tuple[str, str, str]] = set()
+        for cache_key, cache_value in sorted(cache.items()):
+            if not isinstance(cache_value, dict):
+                continue
+            cached_provider_name = cache_value.get("provider_name")
+            cached_bin_name = cache_value.get("bin_name")
+            cached_abspath = cache_value.get("abspath")
+            cache_kind = cache_value.get("cache_kind")
+            if (
+                not isinstance(cached_provider_name, str)
+                or not isinstance(cached_bin_name, str)
+                or not isinstance(cached_abspath, str)
+            ):
+                try:
+                    cached_provider_name, cached_bin_name, cached_abspath = json.loads(
+                        cache_key,
+                    )
+                except Exception:
+                    continue
+            if cached_provider_name != self.name or not isinstance(cached_abspath, str):
+                continue
+            if not isinstance(cache_kind, str):
+                cache_kind = (
+                    "dependency"
+                    if str(cached_bin_name) == str(self.INSTALLER_BIN)
+                    else "binary"
+                )
+            if cache_kind != "binary":
+                continue
+            loaded = self.load_cached_binary(cached_bin_name, Path(cached_abspath))
+            if loaded is None or loaded.loaded_abspath is None:
+                continue
+            resolved_provider = loaded.loaded_binprovider or self
+            dedupe_key = (
+                loaded.name,
+                str(loaded.loaded_abspath),
+                resolved_provider.name,
+            )
+            if dedupe_key in seen:
+                continue
+            seen.add(dedupe_key)
+            binaries.append(
+                ShallowBinary.model_validate(
+                    {
+                        "name": loaded.name,
+                        "description": loaded.description,
+                        "binprovider": resolved_provider,
+                        "abspath": loaded.loaded_abspath,
+                        "version": loaded.loaded_version,
+                        "sha256": loaded.loaded_sha256,
+                        "mtime": loaded.loaded_mtime,
+                        "euid": loaded.loaded_euid,
+                        "binproviders": [resolved_provider],
+                        "overrides": loaded.overrides,
+                    },
+                ),
+            )
+        return binaries
+
     def setup_PATH(self, no_cache: bool = False) -> None:
         """Populate runtime PATH lazily.
 
@@ -2124,15 +2265,7 @@ def update(
             getattr(getattr(update_handler, "__func__", update_handler), "__name__", "")
             == "update_noop"
         ):
-            result = self.load(bin_name=bin_name, quiet=quiet, no_cache=no_cache)
-            if result is not None:
-                self._assert_min_version_satisfied(
-                    bin_name=bin_name,
-                    action="update",
-                    loaded_version=result.loaded_version,
-                    min_version=min_version,
-                )
-            return result
+            return None
 
         self.setup(
             postinstall_scripts=postinstall_scripts,
@@ -2184,7 +2317,7 @@ def update(
 
         self.invalidate_cache(bin_name)
 
-        result = self.load(bin_name, quiet=True, no_cache=True)
+        result = self.load(bin_name, quiet=True, no_cache=no_cache)
         if not quiet:
             assert result is not None, (
                 f"❌ {self.__class__.__name__} Unable to find version for {bin_name} after updating. PATH={self.PATH} LOG={update_log}"
@@ -2612,6 +2745,7 @@ def has_cached_binary(self, bin_name: BinName) -> bool:
             cached_provider_name = cache_value.get("provider_name")
             cached_bin_name = cache_value.get("bin_name")
             cached_abspath = cache_value.get("abspath")
+            cache_kind = cache_value.get("cache_kind")
             if (
                 not isinstance(cached_provider_name, str)
                 or not isinstance(cached_bin_name, str)
@@ -2626,6 +2760,14 @@ def has_cached_binary(self, bin_name: BinName) -> bool:
 
             if cached_provider_name != self.name or cached_bin_name != str(bin_name):
                 continue
+            if not isinstance(cache_kind, str):
+                cache_kind = (
+                    "dependency"
+                    if str(cached_bin_name) == str(self.INSTALLER_BIN)
+                    else "binary"
+                )
+            if cache_kind != "binary":
+                continue
 
             if self._is_managed_by_other_provider(Path(cached_abspath)):
                 cache.pop(cache_key, None)