porringer 0.2.1.dev87__tar.gz → 0.2.1.dev89__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: porringer
-Version: 0.2.1.dev87
+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.dev87 → porringer-0.2.1.dev89}/porringer/backend/command/core/execution.py

@@ -688,6 +688,14 @@ async def execute_uninstall(
     if package_cache is not None:
         ctx = replace(ctx, package_cache=package_cache)
 
+    # --- Per-distro WSL runtime context -----------------------------------
+    if (
+        action.distro is not None
+        and ctx.wsl_runtime_contexts
+        and (wsl_ctx := ctx.wsl_runtime_contexts.get(action.distro)) is not None
+    ):
+        ctx = replace(ctx, runtime_context=wsl_ctx)
+
     resolved = await resolve_uninstall_operation(
         action,
         environments,

{porringer-0.2.1.dev87 → porringer-0.2.1.dev89}/porringer/backend/command/package.py

@@ -14,7 +14,7 @@ import builtins
 import logging
 from collections.abc import Awaitable, Callable
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from packaging.utils import canonicalize_name
 from packaging.version import Version
@@ -30,8 +30,9 @@ from porringer.backend.command.core.resolution import (
     resolve_uninstall_operation,
     resolved_to_result,
 )
+from porringer.backend.command.core.wsl_overlay import overlay_wsl_plugin, wsl_transport_for
 from porringer.core.plugin_schema.environment import CheckUpdatesParameters, Environment
-from porringer.core.plugin_schema.runtime import RuntimeConsumer, RuntimeContext
+from porringer.core.plugin_schema.runtime import RuntimeConsumer, RuntimeContext, RuntimeProvider
 from porringer.core.schema import Package, PackageRef
 from porringer.schema import (
     CheckParameters,
@@ -74,6 +75,7 @@ async def _imperative_action(
     dry_run: bool,
     resolve_fn: _ResolveFn,
     execute_fn: _ExecuteFn,
+    distro: str | None = None,
 ) -> SetupActionResult:
     """Shared skeleton for imperative package operations.
 
@@ -114,10 +116,19 @@ async def _imperative_action(
         installer=plugin_name,
         package=package,
         runtime_tag=runtime_tag,
+        distro=distro,
     )
 
     ctx = ResolutionContext(runtime_context=runtime_context)
 
+    if distro is not None:
+        wsl_ctx = await _resolve_wsl_runtime_context(environments, distro)
+        if wsl_ctx is not None:
+            ctx = ResolutionContext(
+                runtime_context=runtime_context,
+                wsl_runtime_contexts={distro: wsl_ctx},
+            )
+
     if dry_run:
         resolved = await resolve_fn(action, environments, ctx)
         return resolved_to_result(resolved)
@@ -147,6 +158,42 @@ async def _discover_with_runtime(runtime_context: RuntimeContext | None) -> Disc
 _discover_environments = discover_environments
 
 
+async def _resolve_wsl_runtime_context(
+    environments: dict[str, Environment],
+    distro: str,
+) -> RuntimeContext | None:
+    """Resolve the interpreter path inside a WSL distro.
+
+    Scans *environments* for :class:`RuntimeProvider` plugins, wraps
+    each with a :class:`WslTransport`, and attempts to resolve the
+    default executable inside the target distro.
+
+    Returns:
+        A :class:`RuntimeContext` mapping the provider's kind to the
+        resolved executable, or ``None`` when no provider succeeds.
+    """
+    transport = wsl_transport_for(distro)
+    if transport is None:
+        return None
+
+    for env in environments.values():
+        if not isinstance(env, RuntimeProvider):
+            continue
+        wsl_env = cast(RuntimeProvider, env.with_transport(transport))
+        kind = cast(type[RuntimeProvider], type(env)).provided_runtime_kind()
+        try:
+            tag = await wsl_env.default_tag()
+        except Exception:
+            continue
+        if tag is None:
+            continue
+        executable = await wsl_env.resolve_executable(tag)
+        if executable is not None:
+            return RuntimeContext(executables={kind: executable})
+
+    return None
+
+
 async def _build_update_infos(
     env: Any,
     check_params: CheckUpdatesParameters,
@@ -199,6 +246,7 @@ class PackageCommands:
         *,
         plugins: DiscoveredPlugins | None = None,
         runtime_context: RuntimeContext | None = None,
+        distro: str | None = None,
     ) -> builtins.list[Package]:
         """List packages installed in a plugin's environment.
 
@@ -215,6 +263,9 @@ class PackageCommands:
                 queries the global / default environment.
             plugins: Pre-discovered plugins.
             runtime_context: Pre-resolved runtime context.
+            distro: Target WSL2 distribution name.  When set,
+                the plugin is wrapped with a :class:`WslTransport`
+                so that package queries execute inside the distro.
 
         Returns:
             The packages managed by the named plugin.
@@ -222,7 +273,7 @@ class PackageCommands:
         Raises:
             PluginError: If the plugin is not found.
         """
-        logger.debug('Listing packages for plugin: %s', plugin_name)
+        logger.debug('Listing packages for plugin: %s (distro=%s)', plugin_name, distro)
 
         if plugins is not None:
             environments = plugins.environments
@@ -239,6 +290,14 @@ class PackageCommands:
             available = sorted(environments.keys())
             raise PluginError(f"Plugin '{plugin_name}' not found. Available: {', '.join(available)}")
 
+        if distro is not None:
+            environments = overlay_wsl_plugin(environments, key, distro)
+            env = environments[key]
+            if isinstance(env, RuntimeConsumer):
+                wsl_ctx = await _resolve_wsl_runtime_context(environments, distro)
+                if wsl_ctx is not None:
+                    runtime_context = wsl_ctx
+
         if not env.query_availability(runtime_context):
             logger.debug("Plugin '%s' is not available; returning empty package list", plugin_name)
             return []
@@ -329,6 +388,7 @@ class PackageCommands:
         skip_global: bool = False,
         plugins: DiscoveredPlugins | None = None,
         runtime_context: RuntimeContext | None = None,
+        distro: str | None = None,
     ) -> builtins.list[ScopedPackage]:
         """List packages across multiple scopes (global + per-directory).
 
@@ -342,6 +402,7 @@ class PackageCommands:
             skip_global: When ``True``, skip the global (``project_path=None``) scope.
             plugins: Pre-discovered plugins.
             runtime_context: Pre-resolved runtime context.
+            distro: Target WSL2 distribution name.
 
         Returns:
             A flat list of scoped packages across all queried scopes.
@@ -364,6 +425,7 @@ class PackageCommands:
                 project_path=project_path,
                 plugins=plugins,
                 runtime_context=runtime_context,
+                distro=distro,
             )
             return [
                 ScopedPackage(
@@ -396,6 +458,7 @@ class PackageCommands:
         project_path: Path | None = None,
         plugins: DiscoveredPlugins | None = None,
         runtime_context: RuntimeContext | None = None,
+        distro: str | None = None,
     ) -> tuple[builtins.list[Package], set[str]]:
         """List installed packages with manifest cross-referencing.
 
@@ -410,6 +473,7 @@ class PackageCommands:
             project_path: Path to the project directory.
             plugins: Pre-discovered plugins.
             runtime_context: Pre-resolved runtime context.
+            distro: Target WSL2 distribution name.
 
         Returns:
             A ``(packages, declared_names)`` tuple.  *declared_names*
@@ -429,6 +493,7 @@ class PackageCommands:
             project_path=project_path,
             plugins=plugins,
             runtime_context=runtime_context,
+            distro=distro,
         )
 
         return installed, declared_names
@@ -444,6 +509,7 @@ class PackageCommands:
         plugins: DiscoveredPlugins | None = None,
         runtime_context: RuntimeContext | None = None,
         dry_run: bool = False,
+        distro: str | None = None,
     ) -> SetupActionResult:
         """Install a package if it is not already present.
 
@@ -457,6 +523,8 @@ class PackageCommands:
             plugins: Pre-discovered plugins.
             runtime_context: Optional resolved runtime paths.
             dry_run: When ``True``, resolve only.
+            distro: Target WSL2 distribution name.  When set,
+                the action executes inside the named distro.
 
         Returns:
             A ``SetupActionResult`` describing the outcome.
@@ -473,6 +541,7 @@ class PackageCommands:
             execute_fn=lambda action, envs, queue, ctx: execute_package(
                 action, envs, SyncStrategy.MINIMAL, queue, context=ctx
             ),
+            distro=distro,
         )
 
     @staticmethod
@@ -484,6 +553,7 @@ class PackageCommands:
         plugins: DiscoveredPlugins | None = None,
         runtime_context: RuntimeContext | None = None,
         dry_run: bool = False,
+        distro: str | None = None,
     ) -> SetupActionResult:
         """Upgrade (or install) a single package to its latest version.
 
@@ -497,6 +567,8 @@ class PackageCommands:
             plugins: Pre-discovered plugins.
             runtime_context: Optional resolved runtime paths.
             dry_run: When ``True``, resolve only.
+            distro: Target WSL2 distribution name.  When set,
+                the action executes inside the named distro.
 
         Returns:
             A ``SetupActionResult`` describing the outcome.
@@ -513,6 +585,7 @@ class PackageCommands:
             execute_fn=lambda action, envs, queue, ctx: execute_package(
                 action, envs, SyncStrategy.LATEST, queue, context=ctx
             ),
+            distro=distro,
         )
 
     @staticmethod
@@ -524,6 +597,7 @@ class PackageCommands:
         plugins: DiscoveredPlugins | None = None,
         runtime_context: RuntimeContext | None = None,
         dry_run: bool = False,
+        distro: str | None = None,
     ) -> SetupActionResult:
         """Uninstall a managed package.
 
@@ -537,6 +611,8 @@ class PackageCommands:
             plugins: Pre-discovered plugins.
             runtime_context: Optional resolved runtime paths.
             dry_run: When ``True``, resolve only.
+            distro: Target WSL2 distribution name.  When set,
+                the action executes inside the named distro.
 
         Returns:
             A ``SetupActionResult`` describing the outcome.
@@ -551,6 +627,7 @@ class PackageCommands:
             dry_run=dry_run,
             resolve_fn=resolve_uninstall_operation,
             execute_fn=lambda action, envs, queue, ctx: execute_uninstall(action, envs, queue, context=ctx),
+            distro=distro,
         )
 
     # --- Update checking ---
@@ -560,6 +637,7 @@ class PackageCommands:
         params: CheckParameters | None = None,
         *,
         plugins: DiscoveredPlugins | None = None,
+        distro: str | None = None,
     ) -> builtins.list[CheckResult]:
         """Check for package updates across all (or selected) plugins.
 
@@ -567,6 +645,9 @@ class PackageCommands:
             params: Optional check parameters (plugin filter,
                 pre-release flag).
             plugins: Pre-discovered plugins.
+            distro: Target WSL2 distribution name.  When set,
+                each plugin is wrapped with a :class:`WslTransport`
+                so that update checks execute inside the distro.
 
         Returns:
             One :class:`CheckResult` per queried plugin.
@@ -581,14 +662,24 @@ class PackageCommands:
         if runtime_context is None:
             runtime_context = await Builder.resolve_runtime_context(plugins.environments)
 
+        environments: dict[str, Environment] = dict(plugins.environments)
+
+        transport = wsl_transport_for(distro) if distro is not None else None
+        if distro is not None:
+            wsl_ctx = await _resolve_wsl_runtime_context(environments, distro)
+            if wsl_ctx is not None:
+                runtime_context = wsl_ctx
+
         results: builtins.list[CheckResult] = []
 
-        for name, env in plugins.environments.items():
+        for name, env in environments.items():
             if params.plugins and name not in params.plugins:
                 continue
 
-            plugin_type = type(env)
-            if not plugin_type.is_supported() or not env.query_availability(runtime_context):
+            target_env = env.with_transport(transport) if transport else env
+
+            plugin_type = type(target_env)
+            if not plugin_type.is_supported() or not target_env.query_availability(runtime_context):
                 logger.debug('Skipping unavailable plugin %s for update check', name)
                 continue
 
@@ -598,7 +689,7 @@ class PackageCommands:
                     include_prereleases=params.include_prereleases,
                     runtime_context=runtime_context,
                 )
-                package_infos = await _build_update_infos(env, check_params, runtime_context)
+                package_infos = await _build_update_infos(target_env, check_params, runtime_context)
                 results.append(CheckResult(plugin=name, packages=package_infos))
 
             except (PluginError, UpdateError) as e:

{porringer-0.2.1.dev87 → 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.dev87 → 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.dev87 → 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.dev87 → 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.dev87"
+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.dev87 → 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')))