porringer 0.2.1.dev50__tar.gz → 0.2.1.dev52__tar.gz

{porringer-0.2.1.dev50 → porringer-0.2.1.dev52}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.1
 Name: porringer
-Version: 0.2.1.dev50
+Version: 0.2.1.dev52
 Author-Email: Synodic Software <contact@synodic.software>
 License: MIT
 Project-URL: homepage, https://github.com/synodic/porringer
 Project-URL: repository, https://github.com/synodic/porringer
 Requires-Python: >=3.14
-Requires-Dist: typer[all]>=0.24.0
+Requires-Dist: typer[all]>=0.24.1
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: platformdirs>=4.9.2
 Requires-Dist: userpath>=1.9.2

{porringer-0.2.1.dev50 → porringer-0.2.1.dev52}/porringer/backend/command/core/action_builder.py

@@ -224,6 +224,10 @@ def build_actions(
             for package in packages:
                 if not package.is_applicable():
                     continue
+                # Use the manifest description if set, otherwise surface
+                # the repo URL as the package description so UI cards
+                # show *what* is being cloned.
+                scm_description = package.description or str(package.name)
                 actions.append(
                     SetupAction(
                         description=action_description(kind, verb, installer, package=package.name),
@@ -231,7 +235,7 @@ def build_actions(
                         ecosystem=ecosystem,
                         installer=installer,
                         package=package.name,
-                        package_description=package.description,
+                        package_description=scm_description,
                     )
                 )
             continue

{porringer-0.2.1.dev50 → porringer-0.2.1.dev52}/porringer/backend/command/core/execution.py

@@ -30,6 +30,7 @@ from porringer.core.plugin_schema.runtime import RuntimeConsumer, RuntimeProvide
 from porringer.core.plugin_schema.scm import ScmEnvironment
 from porringer.core.schema import Package, PluginKind
 from porringer.schema import (
+    CloneStatusKind,
     ManifestMetadata,
     ProgressEvent,
     ProgressEventKind,
@@ -53,9 +54,9 @@ from .action_builder import (
 from .discovery import (
     DiscoveredPlugins,
     discover_all_plugins,
-    discover_plugins,
     invalidate_plugin_cache,
 )
+from .phase import run_phases
 from .presence import async_dry_run_action
 from .resolution import (
     OperationKind,
@@ -73,8 +74,8 @@ class ExecutionState:
 
     Owns the discovered plugin dicts, grouped phase actions, and
     common parameters that every phase needs.  Provides
-    ``phase_transition()`` and ``propagate_runtime()`` as methods
-    so callers don't need to pass a half-dozen arguments.
+    :meth:`refresh_all_plugins` and :meth:`propagate_runtime` as
+    methods so callers don't need to pass a half-dozen arguments.
     """
 
     actions: list[SetupAction]
@@ -103,36 +104,23 @@ class ExecutionState:
         """The sync strategy from the current parameters."""
         return self.parameters.strategy
 
-    # -- phase-transition machinery ------------------------------------
+    # -- plugin refresh machinery --------------------------------------
 
-    def phase_transition(self) -> None:
-        """Refresh PATH, re-discover environment plugins, and resolve deferred actions.
+    def refresh_all_plugins(self) -> None:
+        """Refresh PATH and re-discover all plugin types.
 
-        Mutates ``self.environments`` in place and updates
-        descriptions / CLI commands on any newly-resolved actions.
-        The cached runtime executable (if any) is automatically
-        re-propagated to newly-created consumer instances.
+        Invalidates the plugin cache, re-discovers environments,
+        project environments, and SCM environments, then re-applies
+        the cached runtime executable to all new consumer instances.
         """
         refresh_path()
         invalidate_plugin_cache()
-        self.environments = discover_plugins('environment', Environment, check_dependencies=True)
+        plugins = discover_all_plugins()
+        self.environments = dict(plugins.environments)
+        self.project_environments = dict(plugins.project_environments)
+        self.scm_environments = dict(plugins.scm_environments)
         self._apply_resolved_runtime()
 
-        for phase_actions in self.phases.values():
-            if phase_actions:
-                _resolve_deferred_actions(phase_actions, self.environments, self.strategy)
-
-        for phase_actions in self.phases.values():
-            for action in phase_actions:
-                if action.cli_command is None or action.installer is not None:
-                    action.cli_command = get_cli_command(
-                        action,
-                        self.environments,
-                        self.strategy,
-                        self.project_environments,
-                        self.scm_environments,
-                    )
-
     def propagate_runtime(self) -> None:
         """Resolve interpreter paths from completed runtime actions and propagate downstream.
 
@@ -140,8 +128,7 @@ class ExecutionState:
         actions, resolves its executable, injects the directory onto
         ``PATH``, and sets ``runtime_executable`` on every matching
         ``RuntimeConsumer``.  The result is cached so that subsequent
-        calls to :meth:`phase_transition` or
-        :meth:`refresh_project_environments` can re-apply it to
+        calls to :meth:`refresh_all_plugins` can re-apply it to
         newly-created plugin instances.
         """
         result = _propagate_runtime(
@@ -152,17 +139,6 @@ class ExecutionState:
         if result is not None:
             self._resolved_runtime = result
 
-    def refresh_project_environments(self) -> None:
-        """Re-discover project-environment plugins and re-propagate the runtime.
-
-        Replaces ``self.project_environments`` with freshly-discovered
-        instances and re-applies the cached runtime executable so that
-        new ``RuntimeConsumer`` project environments inherit the
-        resolved interpreter path.
-        """
-        self.project_environments = discover_plugins('project_environment', ProjectEnvironment)
-        self._apply_resolved_runtime()
-
     def _apply_resolved_runtime(self) -> None:
         """Re-apply the cached runtime executable to all current consumers.
 
@@ -195,6 +171,59 @@ class ExecutionState:
         """Plugin-management context for this execution run."""
         return PluginContext(project_environments=self.project_environments)
 
+    # -- phase executor delegates --------------------------------------
+
+    async def run_package_actions(self, actions: list[SetupAction]) -> tuple[list[SetupActionResult], bool]:
+        """Execute package/tool/runtime actions.
+
+        Returns:
+            Tuple of (results, should_continue).
+        """
+        return await execute_package_actions(
+            actions,
+            self.environments,
+            self.parameters,
+            self.event_queue,
+            self.plugin_context,
+        )
+
+    async def run_project_phase(self, actions: list[SetupAction]) -> list[SetupActionResult]:
+        """Execute or skip project sync actions."""
+        return await handle_project_phase(actions, self)
+
+    async def run_scm_actions(self, actions: list[SetupAction]) -> list[SetupActionResult]:
+        """Execute SCM clone actions."""
+        return await _execute_scm_actions(
+            actions,
+            self.scm_environments,
+            self.fallback_dir,
+            self.parameters,
+            self.event_queue,
+        )
+
+    async def run_command_actions(self, actions: list[SetupAction]) -> list[SetupActionResult]:
+        """Execute post-sync shell commands."""
+        return await execute_command_actions(actions, self)
+
+    def resolve_deferred(self, actions: list[SetupAction]) -> None:
+        """Resolve deferred actions and update their CLI commands."""
+        _resolve_deferred_actions(
+            actions,
+            self.environments,
+            self.strategy,
+            scm_environments=self.scm_environments,
+            project_environments=self.project_environments,
+        )
+        for action in actions:
+            if action.cli_command is None or action.installer is not None:
+                action.cli_command = get_cli_command(
+                    action,
+                    self.environments,
+                    self.strategy,
+                    self.project_environments,
+                    self.scm_environments,
+                )
+
     def early_return(self) -> SetupResults:
         """Create a ``SetupResults`` from the results accumulated so far."""
         return SetupResults(
@@ -1100,78 +1129,8 @@ async def execute_single(
         )
     )
 
-    # --- Phase 1: runtime-provider actions (pim / pyenv) ---------------
-    if state.phases[PluginKind.RUNTIME]:
-        runtime_results, should_continue = await execute_package_actions(
-            state.phases[PluginKind.RUNTIME],
-            state.environments,
-            state.parameters,
-            state.event_queue,
-            state.plugin_context,
-        )
-        state.results.extend(runtime_results)
-        if not should_continue:
-            return state.early_return()
-        state.propagate_runtime()
-
-        # Phase transition: re-discover plugins now that the runtime
-        # is installed and its directories are on PATH, so that
-        # downstream consumers (pip, uv, etc.) become available.
-        state.phase_transition()
-
-    # --- Phase 2a: package-kind actions (pip, uv, etc.) ---------------
-    if state.phases[PluginKind.PACKAGE]:
-        package_results, should_continue = await execute_package_actions(
-            state.phases[PluginKind.PACKAGE],
-            state.environments,
-            state.parameters,
-            state.event_queue,
-            state.plugin_context,
-        )
-        state.results.extend(package_results)
-        if not should_continue:
-            return state.early_return()
-
-    # --- Phase 2b: tool-kind actions (pipx, etc.) ---------------------
-    if state.phases[PluginKind.TOOL]:
-        # Phase transition: re-discover plugins so that tools installed
-        # in Phase 2a (e.g. pipx via pip) are now available as backends.
-        state.phase_transition()
-
-        tool_results, should_continue = await execute_package_actions(
-            state.phases[PluginKind.TOOL],
-            state.environments,
-            state.parameters,
-            state.event_queue,
-            state.plugin_context,
-        )
-        state.results.extend(tool_results)
-        if not should_continue:
-            return state.early_return()
-
-    # --- Phase 3: project sync ----------------------------------------
-    if state.phases[PluginKind.PROJECT]:
-        # Re-discover project environments in case tools installed in
-        # earlier phases provide new project-environment backends.
-        state.refresh_project_environments()
-
-        state.results.extend(await handle_project_phase(state.phases[PluginKind.PROJECT], state))
-
-    # --- Phase 4: SCM clone -------------------------------------------
-    if state.phases[PluginKind.SCM]:
-        state.results.extend(
-            await _execute_scm_actions(
-                state.phases[PluginKind.SCM],
-                state.scm_environments,
-                state.fallback_dir,
-                state.parameters,
-                state.event_queue,
-            )
-        )
-
-    # --- Phase 5: post-sync commands ----------------------------------
-    if state.phases[None]:
-        state.results.extend(await execute_command_actions(state.phases[None], state))
+    # Run all phases via the generalized phase loop.
+    await run_phases(state)
 
     return SetupResults(
         actions=actions,
@@ -1284,6 +1243,8 @@ def _resolve_deferred_actions(
     actions: list[SetupAction],
     environments: dict[str, Environment],
     strategy: SyncStrategy = SyncStrategy.MINIMAL,
+    scm_environments: dict[str, ScmEnvironment] | None = None,
+    project_environments: dict[str, ProjectEnvironment] | None = None,
 ) -> None:
     """Resolve deferred actions whose `installer` is `None`.
 
@@ -1297,12 +1258,19 @@ def _resolve_deferred_actions(
         actions: Mutable list of actions to resolve in-place.
         environments: Freshly-discovered environment plugins.
         strategy: Sync strategy (for description verb).
+        scm_environments: Optional SCM-environment plugins.
+        project_environments: Optional project-environment plugins.
     """
     deferred = [a for a in actions if a.installer is None and a.ecosystem is not None]
     if not deferred:
         return
 
-    resolver = BackendResolver(environments)
+    all_plugins: dict[str, Environment | ScmEnvironment | ProjectEnvironment] = {
+        **environments,
+        **(scm_environments or {}),
+        **(project_environments or {}),
+    }
+    resolver = BackendResolver(all_plugins)
     verb = STRATEGY_VERB[strategy]
 
     for action in deferred:
@@ -1646,14 +1614,29 @@ async def _execute_scm_clone(
     destination = working_dir
 
     # Skip if already cloned
-    if scm_env.is_cloned(url, destination):
-        return SetupActionResult(
-            action=action,
-            success=True,
-            skipped=True,
-            skip_reason=SkipReason.ALREADY_INSTALLED,
-            message=f"Repository already cloned at '{destination}'",
-        )
+    clone_status = scm_env.is_cloned(url, destination)
+
+    match clone_status.kind:
+        case CloneStatusKind.CLONED:
+            actual_url = clone_status.remote_url or url
+            message = f"SCM skip: repo already cloned at '{destination}' (remote: {actual_url})"
+            logger.info(message)
+            return SetupActionResult(
+                action=action,
+                success=True,
+                skipped=True,
+                skip_reason=SkipReason.ALREADY_INSTALLED,
+                message=message,
+            )
+        case CloneStatusKind.MISSING:
+            logger.info("SCM clone needed: .git not found at '%s'", destination)
+        case CloneStatusKind.URL_MISMATCH:
+            logger.info(
+                "SCM clone needed: remote URL mismatch at '%s' (expected '%s', found '%s')",
+                destination,
+                url,
+                clone_status.remote_url,
+            )
 
     if parameters.dry_run:
         # Dry-run — no-op

porringer-0.2.1.dev52/porringer/backend/command/core/phase.py

@@ -0,0 +1,247 @@
+"""Generalized phase abstraction for the execution pipeline.
+
+Each phase in the setup flow (runtime → packages → tools → project-sync →
+SCM → post-sync commands) is represented by a :class:`Phase` instance that
+encapsulates the *refresh → resolve-deferred → execute → post-hook* cycle.
+
+The :func:`run_phases` driver replaces the hand-coded per-phase blocks in
+``execute_single()`` with a uniform loop.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, override
+
+from porringer.core.schema import PluginKind
+from porringer.schema import SetupActionResult
+
+if TYPE_CHECKING:
+    from .execution import ExecutionState
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Phase result
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class PhaseResult:
+    """Outcome of a single phase execution.
+
+    Attributes:
+        results: Per-action results produced by this phase.
+        should_continue: ``False`` when fail-fast was triggered and the
+            pipeline should abort immediately.
+    """
+
+    results: list[SetupActionResult]
+    should_continue: bool = True
+
+
+# ---------------------------------------------------------------------------
+# Phase protocol
+# ---------------------------------------------------------------------------
+
+
+class Phase(Protocol):
+    """Unified interface for every execution phase.
+
+    Implementors define *kind* (which action bucket they handle),
+    *refresh* (plugin re-discovery), *execute* (the actual work), and
+    *post_execute* (hooks that run after a successful phase).
+    """
+
+    @property
+    def kind(self) -> PluginKind | None:
+        """The ``PluginKind`` this phase processes (``None`` for post-sync commands)."""
+        ...
+
+    def refresh(self, state: ExecutionState) -> None:
+        """Re-discover plugins and resolve deferred actions for **this** phase only.
+
+        Called *before* :meth:`execute`.  The default implementation is a no-op.
+        """
+        ...
+
+    async def execute(self, state: ExecutionState) -> PhaseResult:
+        """Run the phase's actions and return aggregated results.
+
+        Must return a :class:`PhaseResult`.  Set ``should_continue=False``
+        to abort the pipeline (fail-fast).
+        """
+        ...
+
+    def post_execute(self, state: ExecutionState) -> None:
+        """Hook called *after* a successful execution (``should_continue=True``).
+
+        Typical use: propagate a resolved runtime to downstream consumers.
+        The default implementation is a no-op.
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Concrete phases
+# ---------------------------------------------------------------------------
+
+
+class _PhaseBase:
+    """Shared helpers for concrete phase implementations."""
+
+    _kind: PluginKind | None
+
+    @property
+    def kind(self) -> PluginKind | None:
+        return self._kind
+
+    # Default no-ops — subclasses override as needed.
+    def refresh(self, state: ExecutionState) -> None:  # noqa: D102
+        pass
+
+    def post_execute(self, state: ExecutionState) -> None:  # noqa: D102
+        pass
+
+
+class RuntimePhase(_PhaseBase):
+    """Phase 1: install / resolve language runtimes (pim, pyenv)."""
+
+    _kind = PluginKind.RUNTIME
+
+    async def execute(self, state: ExecutionState) -> PhaseResult:  # noqa: D102
+        results, ok = await state.run_package_actions(state.phases[self._kind])
+        return PhaseResult(results=results, should_continue=ok)
+
+    @override
+    def post_execute(self, state: ExecutionState) -> None:
+        """Propagate the resolved runtime and trigger a full plugin refresh."""
+        state.propagate_runtime()
+        state.refresh_all_plugins()
+
+
+class PackagePhase(_PhaseBase):
+    """Phase 2a: install packages into the current environment (pip, uv)."""
+
+    _kind = PluginKind.PACKAGE
+
+    async def execute(self, state: ExecutionState) -> PhaseResult:  # noqa: D102
+        results, ok = await state.run_package_actions(state.phases[self._kind])
+        return PhaseResult(results=results, should_continue=ok)
+
+
+class ToolPhase(_PhaseBase):
+    """Phase 2b: install isolated CLI tools (pipx, etc.)."""
+
+    _kind = PluginKind.TOOL
+
+    @override
+    def refresh(self, state: ExecutionState) -> None:
+        """Re-discover plugins so that tools installed in Phase 2a become available."""
+        state.refresh_all_plugins()
+
+    async def execute(self, state: ExecutionState) -> PhaseResult:  # noqa: D102
+        results, ok = await state.run_package_actions(state.phases[self._kind])
+        return PhaseResult(results=results, should_continue=ok)
+
+
+class ProjectPhase(_PhaseBase):
+    """Phase 3: run project-sync (pdm install, uv sync, etc.)."""
+
+    _kind = PluginKind.PROJECT
+
+    @override
+    def refresh(self, state: ExecutionState) -> None:
+        """Re-discover all plugins so that project environments installed in earlier phases are available."""
+        state.refresh_all_plugins()
+
+    async def execute(self, state: ExecutionState) -> PhaseResult:  # noqa: D102
+        results = await state.run_project_phase(state.phases[self._kind])
+        failed = any(not r.success and not r.skipped for r in results)
+        ok = not (failed and state.parameters.fail_fast)
+        return PhaseResult(results=results, should_continue=ok)
+
+
+class ScmPhase(_PhaseBase):
+    """Phase 4: clone source-control repositories."""
+
+    _kind = PluginKind.SCM
+
+    @override
+    def refresh(self, state: ExecutionState) -> None:
+        """Re-discover plugins so that SCM tools installed in earlier phases are available."""
+        state.refresh_all_plugins()
+
+    async def execute(self, state: ExecutionState) -> PhaseResult:  # noqa: D102
+        results = await state.run_scm_actions(state.phases[self._kind])
+        failed = any(not r.success and not r.skipped for r in results)
+        ok = not (failed and state.parameters.fail_fast)
+        return PhaseResult(results=results, should_continue=ok)
+
+
+class CommandPhase(_PhaseBase):
+    """Phase 5: run arbitrary post-sync shell commands."""
+
+    _kind = None
+
+    async def execute(self, state: ExecutionState) -> PhaseResult:  # noqa: D102
+        results = await state.run_command_actions(state.phases[self._kind])
+        failed = any(not r.success and not r.skipped for r in results)
+        ok = not (failed and state.parameters.fail_fast)
+        return PhaseResult(results=results, should_continue=ok)
+
+
+# ---------------------------------------------------------------------------
+# Canonical phase ordering
+# ---------------------------------------------------------------------------
+
+PHASES: list[Phase] = [
+    RuntimePhase(),
+    PackagePhase(),
+    ToolPhase(),
+    ProjectPhase(),
+    ScmPhase(),
+    CommandPhase(),
+]
+"""The ordered list of phases that :func:`run_phases` iterates."""
+
+
+# ---------------------------------------------------------------------------
+# Phase loop driver
+# ---------------------------------------------------------------------------
+
+
+async def run_phases(state: ExecutionState) -> None:
+    """Execute all non-empty phases in order.
+
+    For each phase:
+
+    1. **Skip** if the phase bucket is empty.
+    2. **Refresh** — re-discover plugins and resolve deferred actions
+       (scoped to this phase only).
+    3. **Execute** — run the phase's actions and collect results.
+    4. **Post-execute** — run post-hooks (e.g. runtime propagation)
+       only when the phase completed without aborting the pipeline.
+    """
+    for phase in PHASES:
+        actions = state.phases.get(phase.kind)
+        if not actions:
+            continue
+
+        # 1. Refresh plugins
+        phase.refresh(state)
+
+        # 2. Resolve deferred actions for THIS phase only
+        state.resolve_deferred(actions)
+
+        # 3. Execute
+        result = await phase.execute(state)
+        state.results.extend(result.results)
+
+        if not result.should_continue:
+            return
+
+        # 4. Post-execute hooks
+        phase.post_execute(state)