All providers: never treat managed shims as source-of-truth for load()

Core principle (per maintainer): the symlinks/shims abxpkg writes under
``bin_dir`` are a human-convenience side-effect of install, not a
source of truth. ``load()`` and every other internal lookup must
always consult the underlying package manager / CLI instead.

Audit result — only three providers had a "shim-first" short-circuit
in ``default_abspath_handler``; the others (``docker``, ``bash``
wrappers; ``npm``/``pip``/``pnpm``/``yarn``/``uv``/``cargo``/``gem``/
``goget`` where bin_dir IS the package manager's install location, not
a shim of something upstream) were already correct.

Fixed:
- ``BrewProvider``: removed the initial ``bin_abspath(bin_name,
  PATH=str(self.bin_dir))`` short-circuit. Now always computes the
  brew Cellar / opt / PATH search list first and only refreshes the
  managed shim to match the freshly-resolved target.
- ``PuppeteerProvider``: removed the ``bin_dir/<name>`` shim check
  before falling back to ``puppeteer-browsers list``. Now always asks
  the CLI first, then refreshes the shim to point at the fresh path.
- ``PlaywrightProvider``: same — always asks ``playwright-core``'s
  ``executablePath()`` first, shim becomes output-only.

Also updated the uninstall-handler docstrings for both puppeteer and
playwright to reflect that dropping the shim is a cosmetic cleanup
(to keep managed PATH tidy) rather than a correctness requirement for
``load()``.

Author: claude

abxpkg/binprovider_brew.py

@@ -396,15 +396,15 @@ def default_abspath_handler(
         if not self.PATH:
             return None
 
-        linked_bin = self._linked_bin_path(bin_name)
-        if linked_bin is not None:
-            linked_abspath = bin_abspath(bin_name, PATH=str(self.bin_dir))
-            if linked_abspath:
-                return linked_abspath
-
+        # Authoritative lookup: search brew's own Cellar / opt / PATH
+        # entries for the real formula binary. The managed ``bin_dir``
+        # shim is a convenience side-effect of install — never a source
+        # of truth — so we always consult brew's paths first and only
+        # refresh the shim to match the freshly-resolved target.
         search_paths = self._brew_search_paths(bin_name, no_cache=no_cache)
         abspath = bin_abspath(bin_name, PATH=search_paths)
         if abspath:
+            linked_bin = self._linked_bin_path(bin_name)
             if linked_bin is None or Path(abspath).parent == self.bin_dir:
                 return abspath
             return self._refresh_bin_link(bin_name, abspath)

abxpkg/binprovider_playwright.py

@@ -564,10 +564,11 @@ def default_abspath_handler(
             except Exception:
                 return None
             return None
-        if self.bin_dir is not None:
-            link = self.bin_dir / str(bin_name)
-            if link.exists() and os.access(link, os.X_OK):
-                return link
+        # Authoritative lookup: ask ``playwright-core`` where the browser
+        # actually lives via its ``executablePath()`` API — never trust
+        # the managed ``bin_dir`` shim as a source of truth, it may
+        # point at a browser that was removed out-of-band. When
+        # playwright-core reports nothing, we report nothing.
         resolved = self._playwright_browser_path(
             str(bin_name),
             no_cache=no_cache,
@@ -725,8 +726,11 @@ def default_uninstall_handler(
         install_args: InstallArgs | None = None,
         **context,
     ) -> bool:
-        # Drop the managed shim first so ``load()`` stops returning the
-        # symlink even if the browser-dir rmtree partially fails.
+        # Clean up the convenience shim under ``bin_dir`` alongside the
+        # real browser removal. ``load()`` never consults this shim as a
+        # source of truth (it always asks playwright-core directly), so
+        # dropping it is a cosmetic cleanup to keep the managed PATH
+        # tidy rather than a correctness requirement.
         if self.bin_dir is not None:
             (self.bin_dir / bin_name).unlink(missing_ok=True)
 

abxpkg/binprovider_puppeteer.py

@@ -419,15 +419,19 @@ def default_abspath_handler(
             except Exception:
                 return None
             return None
-        bin_dir = self.bin_dir
-        assert bin_dir is not None
-        link_path = bin_dir / str(bin_name)
-        if link_path.exists() and os.access(link_path, os.X_OK):
-            return link_path
 
+        # Authoritative lookup: ask puppeteer-browsers where the browser
+        # actually lives — never trust the managed ``bin_dir`` shim as a
+        # source of truth, it may point at a browser that was removed
+        # out-of-band. When the CLI reports nothing, we report nothing.
         resolved = self._resolve_installed_browser_path(str(bin_name))
         if not resolved or not resolved.exists():
             return None
+
+        # Refresh the convenience shim under ``bin_dir`` so ``PATH`` users
+        # get a stable entry pointing at the freshly-resolved executable.
+        # Fall back to the resolved path directly when the shim refresh
+        # fails (read-only FS etc.).
         try:
             return self._refresh_symlink(str(bin_name), resolved)
         except OSError:
@@ -688,8 +692,11 @@ def default_uninstall_handler(
         install_args: InstallArgs | None = None,
         **context,
     ) -> bool:
-        # Drop the managed shim first so ``load()`` stops returning the
-        # symlink even if the browser-dir rmtree partially fails.
+        # Clean up the convenience shim under ``bin_dir`` alongside the
+        # real browser removal. ``load()`` never consults this shim as a
+        # source of truth (it always asks puppeteer-browsers directly),
+        # so dropping it is a cosmetic cleanup to keep the managed PATH
+        # tidy rather than a correctness requirement.
         if self.bin_dir is not None:
             bin_path = self.bin_dir / bin_name
             if bin_path.exists() or bin_path.is_symlink():