porringer 0.2.1.dev88__tar.gz → 0.2.1.dev89__tar.gz

{porringer-0.2.1.dev88 → porringer-0.2.1.dev89}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: porringer
-Version: 0.2.1.dev88
+Version: 0.2.1.dev89
 Author-Email: Synodic Software <contact@synodic.software>
 License: MIT
 Project-URL: homepage, https://github.com/synodic/porringer
@@ -8,10 +8,10 @@ Project-URL: repository, https://github.com/synodic/porringer
 Requires-Python: >=3.14
 Requires-Dist: typer[all]>=0.24.1
 Requires-Dist: pydantic>=2.12.5
-Requires-Dist: platformdirs>=4.9.4
+Requires-Dist: platformdirs>=4.9.6
 Requires-Dist: userpath>=1.9.2
 Requires-Dist: packaging>=26.0
-Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: aiohttp>=3.13.5
 Description-Content-Type: text/markdown
 
 <p align="center">

{porringer-0.2.1.dev88 → porringer-0.2.1.dev89}/porringer/core/plugin_schema/tool_based.py

@@ -19,6 +19,7 @@ import logging
 import re
 import shutil
 import subprocess
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Any, Self
 
@@ -39,6 +40,19 @@ class ToolBasedPlugin(Plugin):
     considered available.
     """
 
+    @classmethod
+    def auxiliary_tools(cls) -> Sequence[str]:
+        """Return optional CLI tools that may be invoked as post-action side effects.
+
+        Override to declare tools the plugin calls via ``shutil.which``
+        outside its primary ``tool_name()``.  The test framework uses
+        this to verify that the plugin tolerates each tool being absent.
+
+        Returns:
+            Tool names (empty by default).
+        """
+        return ()
+
     def with_transport(self, transport: Transport) -> Self:
         """Create a new instance of this plugin using a different transport."""
         parameters = PluginParameters(distribution=self._distribution, transport=transport)

{porringer-0.2.1.dev88 → porringer-0.2.1.dev89}/porringer/plugin/pip/plugin.py

@@ -5,7 +5,7 @@ import json
 import logging
 import re
 import shutil
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from pathlib import Path
 from typing import override
 
@@ -44,6 +44,12 @@ class PIPEnvironment(PythonEnvironment):
     the underlying Python installation.
     """
 
+    @classmethod
+    @override
+    def auxiliary_tools(cls) -> Sequence[str]:
+        """Pip may invoke ``pymanager`` to refresh global aliases."""
+        return ('pymanager',)
+
     @classmethod
     @override
     def tool_name(cls) -> str:
@@ -127,6 +133,10 @@ class PIPEnvironment(PythonEnvironment):
         When a progress_callback is provided, streams stderr line-by-line to
         report download and install phases. Otherwise falls back to the simple
         `run_command` path for zero overhead.
+
+        On Windows, if the Python Install Manager (pymanager) is available,
+        runs ``pymanager install --refresh`` after a successful install to
+        regenerate global aliases for newly installed entry points.
         """
         logger = logging.getLogger('porringer.pip.install')
         args = list(
@@ -139,9 +149,30 @@ class PIPEnvironment(PythonEnvironment):
 
         if params.progress_callback is None:
             # Fast path — no streaming needed
-            return await self._install_simple(args, params.package, logger)
+            result = await self._install_simple(args, params.package, logger)
+        else:
+            result = await self._install_with_progress(args, params, logger)
 
-        return await self._install_with_progress(args, params, logger)
+        if not params.dry:
+            await self._refresh_pymanager_aliases(logger)
+
+        return result
+
+    @staticmethod
+    async def _refresh_pymanager_aliases(logger: logging.Logger) -> None:
+        """Best-effort refresh of pymanager global aliases after pip install.
+
+        No-op when pymanager is absent.  Failures never block the install.
+        """
+        if shutil.which('pymanager') is None:
+            return
+
+        try:
+            result = await run_command(['pymanager', 'install', '--refresh'])
+            if result.returncode != 0:
+                logger.warning('pymanager install --refresh exited with code %d', result.returncode)
+        except Exception as exc:
+            logger.warning('Failed to refresh pymanager aliases: %s', exc)
 
     @staticmethod
     async def _install_simple(args: list[str], package: PackageRef, logger: logging.Logger) -> Package | None:

{porringer-0.2.1.dev88 → porringer-0.2.1.dev89}/porringer/test/pytest/tests.py

@@ -1,15 +1,19 @@
 """Implementation of tests that should be overridden in plugins"""
 
 import shutil
-from abc import ABCMeta
+from abc import ABCMeta, abstractmethod
+from collections.abc import Generator
+from typing import NamedTuple
+from unittest.mock import AsyncMock
 
 from packaging.version import Version
 
 import pytest
-from porringer.core.plugin_schema.environment import Environment
+from porringer.core.plugin_schema.environment import Environment, PackageParameters
 from porringer.core.plugin_schema.project_environment import ProjectEnvironment
 from porringer.core.plugin_schema.runtime import RuntimeProvider
 from porringer.core.plugin_schema.scm import ScmEnvironment
+from porringer.core.plugin_schema.tool_based import ToolBasedPlugin
 from porringer.core.schema import Distribution, PackageRef, PluginParameters
 from porringer.test.pytest.shared import (
     EnvironmentTests,
@@ -183,3 +187,70 @@ class RuntimeProviderUnitTests[T: Environment](EnvironmentUnitTests[T], RuntimeP
         kind = plugin_type.provided_runtime_kind()
         assert isinstance(kind, str)
         assert len(kind) > 0
+
+
+class InstallContext(NamedTuple):
+    """Context returned by the ``install_context`` fixture."""
+
+    plugin: Environment
+    params: PackageParameters
+    mock_run: AsyncMock
+    scenario: str
+
+
+class AuxiliaryToolTests[T: ToolBasedPlugin](metaclass=ABCMeta):
+    """Mixin that tests auxiliary-tool interactions declared via ``_auxiliary_tools``.
+
+    Concrete test classes must provide:
+
+    * ``fixture_install_context`` — a fixture yielding an
+      :class:`InstallContext` whose ``scenario`` field indicates which
+      auxiliary-tool configuration is active.
+
+    Expected scenarios (the fixture should be parametrized over these):
+
+    * ``"tools_absent"`` — ``shutil.which`` returns ``None`` for
+      auxiliary tools; ``run_command`` is not expected to be called
+      for them.
+    * ``"tools_present"`` — ``shutil.which`` returns a fake path;
+      ``run_command`` mock returns success.
+    * ``"tools_fail_exception"`` — ``shutil.which`` returns a fake
+      path; ``run_command`` raises ``OSError`` for auxiliary tools.
+    * ``"tools_fail_nonzero"`` — ``shutil.which`` returns a fake path;
+      ``run_command`` returns non-zero for auxiliary tools.
+
+    The mixin is intentionally separate from ``EnvironmentUnitTests`` so
+    that plugins without auxiliary tools don't inherit meaningless tests.
+    """
+
+    @abstractmethod
+    @pytest.fixture(name='install_context')
+    def fixture_install_context(self) -> Generator[InstallContext]:
+        """Yield an ``InstallContext`` with install internals mocked."""
+        raise NotImplementedError('Override this fixture')
+
+    @staticmethod
+    async def test_install_succeeds(install_context: InstallContext) -> None:
+        """install() succeeds regardless of auxiliary tool availability."""
+        plugin, params, _mock_run, _scenario = install_context
+        result = await plugin.install(params)
+        # Install should never fail due to auxiliary tool issues
+        assert result is not None
+
+    @staticmethod
+    async def test_auxiliary_tools_called_only_when_present(
+        install_context: InstallContext,
+    ) -> None:
+        """Auxiliary tools are invoked when present, skipped when absent."""
+        plugin, params, mock_run, scenario = install_context
+        aux = type(plugin).auxiliary_tools()
+        if not aux:
+            pytest.skip('No auxiliary tools declared')
+
+        await plugin.install(params)
+
+        called_args = [str(c) for c in mock_run.call_args_list]
+        if scenario == 'tools_absent':
+            assert not any(tool in arg for arg in called_args for tool in aux)
+        else:
+            assert any(tool in arg for arg in called_args for tool in aux)

{porringer-0.2.1.dev88 → porringer-0.2.1.dev89}/pyproject.toml

@@ -10,12 +10,12 @@ requires-python = ">=3.14"
 dependencies = [
     "typer[all]>=0.24.1",
     "pydantic>=2.12.5",
-    "platformdirs>=4.9.4",
+    "platformdirs>=4.9.6",
     "userpath>=1.9.2",
     "packaging>=26.0",
-    "aiohttp>=3.13.3",
+    "aiohttp>=3.13.5",
 ]
-version = "0.2.1.dev88"
+version = "0.2.1.dev89"
 
 [project.license]
 text = "MIT"
@@ -56,17 +56,17 @@ porringer = "porringer.console.entry:app"
 
 [dependency-groups]
 lint = [
-    "ruff>=0.15.7",
-    "pyrefly>=0.57.1",
+    "ruff>=0.15.10",
+    "pyrefly>=0.60.2",
 ]
 test = [
-    "pytest>=9.0.2",
+    "pytest>=9.0.3",
     "pytest-cov>=7.1.0",
     "pytest-mock>=3.15.1",
     "pytest-asyncio>=1.3.0",
 ]
 docs = [
-    "zensical>=0.0.28",
+    "zensical>=0.0.32",
 ]
 
 [tool.pytest.ini_options]
@@ -78,6 +78,7 @@ testpaths = [
 markers = [
     "fresh_plugins: invalidate the plugin discovery cache before this test",
     "mock_packages: use a cached package list instead of real subprocess calls",
+    "bare_environment: simulate a bare system with only the primary tool on PATH",
 ]
 
 [tool.ruff]

{porringer-0.2.1.dev88 → porringer-0.2.1.dev89}/tests/conftest.py

@@ -1,5 +1,6 @@
 """Shared pytest configuration and fixtures."""
 
+import shutil
 import sys
 import tempfile
 from collections.abc import Generator
@@ -55,6 +56,10 @@ def pytest_configure(config: pytest.Config) -> None:
         'markers',
         'frozen_app: simulate a frozen (PyInstaller) application environment',
     )
+    config.addinivalue_line(
+        'markers',
+        'bare_environment: simulate a bare system with only the primary tool on PATH',
+    )
 
 
 def pytest_runtest_setup(item: pytest.Item) -> None:
@@ -104,6 +109,30 @@ def frozen_context(*, which_result: str | None = None) -> Generator[None]:
             p.stop()
 
 
+@contextmanager
+def bare_environment_context(*, allowed_tools: set[str] | None = None) -> Generator[None]:
+    """Context manager that hides all CLI tools except *allowed_tools*.
+
+    Patches ``shutil.which`` globally so that any tool not in
+    *allowed_tools* appears absent.  This catches undeclared
+    auxiliary-tool dependencies.
+
+    Args:
+        allowed_tools: Tool names that should remain discoverable.
+            When ``None``, **all** tools are hidden.
+    """
+    allowed = allowed_tools or set()
+    original_which = shutil.which
+
+    def _restricted_which(name: str, *args, **kwargs) -> str | None:
+        if name in allowed:
+            return original_which(name, *args, **kwargs)
+        return None
+
+    with patch('shutil.which', side_effect=_restricted_which):
+        yield
+
+
 @pytest.fixture(autouse=True)
 def _apply_mock_packages(
     request: pytest.FixtureRequest,

porringer-0.2.1.dev89/tests/integration/test_bare_environment.py

@@ -0,0 +1,49 @@
+"""Integration tests that verify plugins tolerate a bare environment.
+
+Every available plugin is dry-run installed under a restricted PATH
+where only the plugin's primary tool is discoverable.  This catches
+undeclared auxiliary-tool dependencies that would fail on a clean
+machine.
+
+Safety guarantees (no system mutation):
+
+1. ``dry_run=True`` — the sync engine skips all mutating actions
+   (install, clone, post-sync commands).  Only read-only subprocess
+   calls happen (e.g. ``git rev-parse`` for presence detection,
+   ``pip list`` for package queries).
+2. ``bare_environment_context`` — restricts ``shutil.which`` so that
+   even if a mutating code path were accidentally reached, most tools
+   would appear absent and the operation would be skipped or fail
+   before spawning a process.
+3. ``session_api`` — uses an isolated temporary directory tree for
+   configuration and cache (no writes to user/system porringer dirs).
+"""
+
+from pathlib import Path
+
+import pytest
+
+from porringer.api import API
+from porringer.schema import SetupParameters
+from tests.conftest import bare_environment_context
+
+_BOOTSTRAP_DIR = Path(__file__).resolve().parents[2] / 'examples' / 'python-bootstrap'
+
+
+@pytest.mark.bare_environment
+@pytest.mark.fresh_plugins
+class TestBareEnvironmentDryRun:
+    """Dry-run the bootstrap example under a bare PATH."""
+
+    @staticmethod
+    async def test_dry_run_succeeds_under_bare_environment(session_api: API) -> None:
+        """Dry-run with only primary tools on PATH should not crash."""
+        setup_params = SetupParameters(paths=_BOOTSTRAP_DIR, dry_run=True)
+
+        with bare_environment_context(allowed_tools={'pip', 'python', 'git'}):
+            results = await session_api.sync.run(setup_params)
+
+        assert len(results.manifest_results) >= 1
+        for manifest in results.manifest_results:
+            # Every action should resolve without raising
+            assert manifest.actions is not None

porringer-0.2.1.dev89/tests/unit/plugins/pip/conftest.py

@@ -0,0 +1,7 @@
+"""Shared fixtures for pip plugin tests."""
+
+from packaging.version import Version
+
+from porringer.core.schema import Distribution, PluginParameters
+
+_MOCK_PARAMS = PluginParameters(distribution=Distribution(version=Version('0.0.0')))

porringer-0.2.1.dev89/tests/unit/plugins/pip/test_auxiliary_tools.py

@@ -0,0 +1,96 @@
+"""Tests for auxiliary-tool interactions in the pip plugin."""
+
+from collections.abc import Generator
+from typing import override
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from packaging.version import Version
+
+from porringer.core.plugin_schema.environment import PackageParameters
+from porringer.core.schema import Distribution, Package, PackageRef, PluginParameters
+from porringer.plugin.pip.plugin import PIPEnvironment
+from porringer.test.pytest.tests import AuxiliaryToolTests, InstallContext
+from porringer.utility.utility import CommandResult
+
+_MOCK_PARAMS = PluginParameters(distribution=Distribution(version=Version('0.0.0')))
+
+_SCENARIOS = ['tools_absent', 'tools_present', 'tools_fail_exception', 'tools_fail_nonzero']
+
+
+def _make_context(scenario: str) -> Generator[InstallContext]:
+    """Build an InstallContext for the given scenario."""
+    env = PIPEnvironment(_MOCK_PARAMS)
+    params = PackageParameters(package=PackageRef(name='test-pkg'))
+
+    # Determine shutil.which behavior
+    which_return = None if scenario == 'tools_absent' else r'C:\Program Files\pymanager\pymanager.exe'
+
+    # Determine run_command behavior for auxiliary tool calls
+    if scenario == 'tools_fail_exception':
+
+        async def run_side_effect(args, **kwargs):
+            if args == ['pymanager', 'install', '--refresh']:
+                raise OSError('pymanager crashed')
+            return CommandResult(returncode=0, stdout='', stderr='')
+
+        mock_run = AsyncMock(side_effect=run_side_effect)
+    elif scenario == 'tools_fail_nonzero':
+
+        async def run_side_effect_nonzero(args, **kwargs):
+            if args == ['pymanager', 'install', '--refresh']:
+                return CommandResult(returncode=1, stdout='', stderr='something went wrong')
+            return CommandResult(returncode=0, stdout='', stderr='')
+
+        mock_run = AsyncMock(side_effect=run_side_effect_nonzero)
+    else:
+        mock_run = AsyncMock(return_value=CommandResult(returncode=0, stdout='', stderr=''))
+
+    with (
+        patch.object(
+            PIPEnvironment,
+            '_install_simple',
+            new_callable=AsyncMock,
+            return_value=Package(name='test-pkg', version=None),
+        ),
+        patch.object(env, 'install_command', return_value=['python', '-m', 'pip', 'install', 'test-pkg']),
+        patch('porringer.plugin.pip.plugin.run_command', mock_run),
+        patch('porringer.plugin.pip.plugin.shutil.which', return_value=which_return),
+    ):
+        yield InstallContext(plugin=env, params=params, mock_run=mock_run, scenario=scenario)
+
+
+class TestPymanagerRefresh(AuxiliaryToolTests[PIPEnvironment]):
+    """Auxiliary-tool tests for pip's pymanager refresh integration."""
+
+    @override
+    @pytest.fixture(name='install_context', params=_SCENARIOS)
+    def fixture_install_context(self, request: pytest.FixtureRequest) -> Generator[InstallContext]:
+        """Yield an InstallContext parametrized over auxiliary-tool scenarios."""
+        yield from _make_context(request.param)
+
+    @staticmethod
+    async def test_refresh_not_called_on_dry_run() -> None:
+        """Dry-run install does not trigger refresh even with pymanager available."""
+        env = PIPEnvironment(_MOCK_PARAMS)
+        params = PackageParameters(package=PackageRef(name='test-pkg'), dry=True)
+
+        with (
+            patch.object(
+                PIPEnvironment,
+                '_install_simple',
+                new_callable=AsyncMock,
+                return_value=Package(name='test-pkg', version=None),
+            ),
+            patch.object(env, 'install_command', return_value=['python', '-m', 'pip', 'install', 'test-pkg']),
+            patch(
+                'porringer.plugin.pip.plugin.shutil.which',
+                return_value=r'C:\Program Files\pymanager\pymanager.exe',
+            ),
+            patch('porringer.plugin.pip.plugin.run_command', new_callable=AsyncMock) as mock_run,
+        ):
+            mock_run.return_value = CommandResult(returncode=0, stdout='', stderr='')
+            result = await env.install(params)
+
+            assert result is not None
+            mock_run.assert_not_called()

{porringer-0.2.1.dev88 → porringer-0.2.1.dev89}/tests/unit/test_backend_resolver.py

@@ -6,7 +6,7 @@ The resolver selects a plugin per (PluginKind, ecosystem) pair using:
 """
 
 from pathlib import Path
-from typing import Self, cast
+from typing import Self
 
 from packaging.version import Version
 
@@ -36,7 +36,7 @@ class _StubPlugin:
 
     def with_transport(self, transport: Transport) -> Self:
         parameters = PluginParameters(distribution=self._distribution, transport=transport)
-        return cast(Self, type(self)(parameters))
+        return type(self)(parameters)
 
     @staticmethod
     def ecosystem() -> Ecosystem | None: