porringer 0.2.1.dev91__tar.gz → 0.2.1.dev92__tar.gz

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: porringer
-Version: 0.2.1.dev91
+Version: 0.2.1.dev92
 Author-Email: Synodic Software <contact@synodic.software>
 License: MIT
 Project-URL: homepage, https://github.com/synodic/porringer

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/__init__.py

@@ -1,6 +1,6 @@
-"""Public package exports."""
+"""Public package exports.
 
-"""Public package entry points for Porringer.
+Public package entry points for Porringer.
 
 This package exposes the public API, backend helpers, CLI commands, and
 supporting utilities that applications use when integrating with Porringer.

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/api.py

@@ -1,6 +1,7 @@
-"""Helpers for api."""
+"""Helpers for api.
 
-"""Public API surface for Porringer."""
+Public API surface for Porringer.
+"""
 
 import asyncio
 import logging

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/__init__.py

@@ -1,6 +1,6 @@
-"""Public package exports for the backend module."""
+"""Public package exports for the backend module.
 
-"""Backend package for Porringer.
+Backend package for Porringer.
 
 This package contains modules and utilities for backend processing,
 including configuration resolution, plugin management, and command execution.

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/backend.py

@@ -1,6 +1,6 @@
-"""Backend helpers for backend."""
+"""Backend helpers for backend.
 
-"""Backend resolution for mapping `(kind, ecosystem)` pairs to installer plugins.
+Backend resolution for mapping `(kind, ecosystem)` pairs to installer plugins.
 
 The `BackendResolver` chooses the plugin that should handle each
 `(PluginKind, ecosystem)` pair declared in a manifest. For example,

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/builder.py

@@ -1,6 +1,6 @@
-"""Backend helpers for builder."""
+"""Backend helpers for builder.
 
-"""Helpers for discovering and constructing plugins from entry points.
+Helpers for discovering and constructing plugins from entry points.
 
 The builder offers reusable logic for scanning entry-point groups,
 instantiating plugins, and resolving runtime executables without duplicating

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/__init__.py

@@ -1,6 +1,6 @@
-"""Public package exports for the backend.command module."""
+"""Public package exports for the backend.command module.
 
-"""Command package for Porringer backend.
+Command package for Porringer backend.
 
 This package contains command modules for backend operations,
 including plugin management and self-update functionalities.

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/client.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for client."""
+"""CLI command implementation for client.
 
-"""Client-oriented aggregate commands."""
+Client-oriented aggregate commands.
+"""
 
 import asyncio
 

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/core/__init__.py

@@ -1,6 +1,6 @@
-"""Public package exports for the backend.command.core module."""
+"""Public package exports for the backend.command.core module.
 
-"""Core backend command modules.
+Core backend command modules.
 
 This package contains the core implementation modules for the
 backend command system: action building, execution, plugin

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/core/action_builder.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for action builder."""
+"""CLI command implementation for action builder.
 
-"""Action plan construction.
+Action plan construction.
 
 Builds the list of `SetupAction` objects from a parsed manifest and
 resolved plugins.  Also contains the preview/parse entry point that
@@ -388,6 +388,8 @@ def build_actions(
             ``dict[str, Environment]`` for backward compatibility
             with existing callers / tests.
         strategy: The sync strategy (used for description text).
+        search_from: The directory from which project-relevance discovery
+            should start.
 
     Returns:
         List of actions to perform.

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/core/discovery.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for discovery."""
+"""CLI command implementation for discovery.
 
-"""Plugin discovery helpers.
+Plugin discovery helpers.
 
 Provides `discover_plugins` which wraps entry-point discovery and
 instantiation into a single canonical-name-keyed dict.  Extracted from

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/core/execution.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for execution."""
+"""CLI command implementation for execution.
 
-"""Phased execution engine.
+Phased execution engine.
 
 Orchestrates the multi-phase setup flow: runtime → packages → tools →
 project-sync → SCM.  Each phase ensures its prerequisites are met before
@@ -1717,38 +1717,56 @@ async def _execute_project_sync(
                 )
 
     try:
-        # Always observe output: build the CLI steps from the plugin and
-        # run them via run_command for line-by-line progress.
-        plan = type(proj_env).command_plan(effective_dir, runtime_context=runtime_context)
-        effective_dir = plan.directory
-        steps = plan.steps or ([plan.argv] if plan.argv else [])
-
-        progress = CommandProgress(
-            action=action,
-            callback=_make_progress_callback(action, event_queue),
-            phase='sync',
+        return await _run_project_sync_steps(
+            action,
+            proj_env,
+            effective_dir,
+            event_queue,
+            runtime_context=runtime_context,
         )
+    except Exception as e:
+        return SetupActionResult(action=action, success=False, message=str(e))
 
-        success = True
-        for args in steps:
-            cmd_result = await run_command(args, progress=progress, cwd=effective_dir, timeout=300.0)
-            success = cmd_result.returncode == 0
-            if not success:
-                break
 
-        if success:
-            return SetupActionResult(
-                action=action,
-                success=True,
-                message=f'Synced project via {action.installer}',
-            )
+async def _run_project_sync_steps(
+    action: SetupAction,
+    proj_env: ProjectEnvironment,
+    effective_dir: Path,
+    event_queue: asyncio.Queue[ProgressEvent | None],
+    *,
+    runtime_context: RuntimeContext | None = None,
+) -> SetupActionResult:
+    """Run the resolved project-sync steps and return their outcome."""
+    # Always observe output: build the CLI steps from the plugin and
+    # run them via run_command for line-by-line progress.
+    plan = type(proj_env).command_plan(effective_dir, runtime_context=runtime_context)
+    effective_dir = plan.directory
+    steps = plan.steps or ([plan.argv] if plan.argv else [])
+
+    progress = CommandProgress(
+        action=action,
+        callback=_make_progress_callback(action, event_queue),
+        phase='sync',
+    )
+
+    success = True
+    for args in steps:
+        cmd_result = await run_command(args, progress=progress, cwd=effective_dir, timeout=300.0)
+        success = cmd_result.returncode == 0
+        if not success:
+            break
+
+    if success:
         return SetupActionResult(
             action=action,
-            success=False,
-            message=f'Project sync failed via {action.installer}',
+            success=True,
+            message=f'Synced project via {action.installer}',
         )
-    except Exception as e:
-        return SetupActionResult(action=action, success=False, message=str(e))
+    return SetupActionResult(
+        action=action,
+        success=False,
+        message=f'Project sync failed via {action.installer}',
+    )
 
 
 # ---------------------------------------------------------------------------

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/core/inspection.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for inspection."""
+"""CLI command implementation for inspection.
 
-"""Build structured inspection reports for manifest previews."""
+Build structured inspection reports for manifest previews.
+"""
 
 import asyncio
 from pathlib import Path

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/core/phase.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for phase."""
+"""CLI command implementation for phase.
 
-"""Generalized phase abstraction for the execution pipeline.
+Generalized phase abstraction for the execution pipeline.
 
 Each phase in the setup flow (runtime → packages → tools → project-sync →
 SCM) is represented by a :class:`Phase` instance that

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/core/presence.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for presence."""
+"""CLI command implementation for presence.
 
-"""Presence detection and action inspection.
+Presence detection and action inspection.
 
 Checks whether packages are already installed so the sync engine can
 skip redundant operations.

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/core/resolution.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for resolution."""
+"""CLI command implementation for resolution.
 
-"""Unified operation resolution for inspection and real execution.
+Unified operation resolution for inspection and real execution.
 
 Determines the correct operation (install, upgrade, or skip) for a
 given action based on the sync strategy and current system state.
@@ -485,7 +485,7 @@ async def _resolve_package_operation(
 _VERSION_PATTERN = re.compile(r'v?(\d+\.\d+(?:\.\d+)*)')
 
 
-async def _capture_subprocess(args: list[str], *, timeout: int) -> tuple[int | None, bytes, bytes] | None:
+async def _capture_subprocess(args: list[str], *, timeout_seconds: int) -> tuple[int | None, bytes, bytes] | None:
     """Run *args*, capturing stdout/stderr under a command trace.
 
     Returns ``(returncode, stdout, stderr)`` on completion, or ``None``
@@ -498,7 +498,7 @@ async def _capture_subprocess(args: list[str], *, timeout: int) -> tuple[int | N
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
         )
-        stdout_bytes, stderr_bytes = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+        stdout_bytes, stderr_bytes = await asyncio.wait_for(proc.communicate(), timeout=timeout_seconds)
         trace.finish(returncode=proc.returncode, stdout=stdout_bytes, stderr=stderr_bytes)
         return proc.returncode, stdout_bytes or b'', stderr_bytes or b''
     except (FileNotFoundError, OSError, TimeoutError) as exc:
@@ -516,7 +516,7 @@ async def probe_tool_version(name: str) -> str | None:
     Returns the version string on success, or ``None`` when the
     subprocess fails, times out, or the output cannot be parsed.
     """
-    result = await _capture_subprocess([name, '--version'], timeout=5)
+    result = await _capture_subprocess([name, '--version'], timeout_seconds=5)
     if result is None:
         return None
     _, stdout_bytes, stderr_bytes = result
@@ -538,13 +538,19 @@ _REQUIRES_SCRIPT = (
 ``Requires-Dist`` entries as a JSON list of strings."""
 
 
-async def _run_metadata_script(python: str, script: str, package_name: str, *, timeout: int = 10) -> bytes | None:
+async def _run_metadata_script(
+    python: str,
+    script: str,
+    package_name: str,
+    *,
+    timeout_seconds: int = 10,
+) -> bytes | None:
     """Run a metadata-introspection one-liner in *python* and return stdout.
 
     Returns raw stdout bytes on success, or ``None`` when the
     subprocess fails, times out, or cannot be started.
     """
-    result = await _capture_subprocess([python, '-c', script, package_name], timeout=timeout)
+    result = await _capture_subprocess([python, '-c', script, package_name], timeout_seconds=timeout_seconds)
     if result is None:
         return None
     returncode, stdout_bytes, _ = result
@@ -654,7 +660,7 @@ async def fetch_plugin_extras_context(
     Returns ``(requires, installed_names)`` on success, or ``None``
     when introspection fails.
     """
-    raw = await _run_metadata_script(python, _PLUGIN_EXTRAS_SCRIPT, package_name, timeout=15)
+    raw = await _run_metadata_script(python, _PLUGIN_EXTRAS_SCRIPT, package_name, timeout_seconds=15)
     if raw is None:
         return None
     try:

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/manifest.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for manifest."""
+"""CLI command implementation for manifest.
 
-"""Manifest loading, parsing, and validation.
+Manifest loading, parsing, and validation.
 
 Handles finding, loading, and validating porringer manifests.
 Supports three modes:

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/package.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for package."""
+"""CLI command implementation for package.
 
-"""The package command module.
+The package command module.
 
 Imperative package operations — listing, installing, upgrading,
 uninstalling, and checking for updates on packages managed by

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/plugin.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for plugin."""
+"""CLI command implementation for plugin.
 
-"""The plugin command module.
+The plugin command module.
 
 Manages *porringer extension* packages — installing, upgrading, and
 uninstalling plugins that extend porringer's capabilities (e.g.
@@ -182,7 +182,7 @@ class PluginCommands:
         *,
         verb: str,
         dry_run: bool,
-        timeout: int,
+        timeout_seconds: int,
     ) -> PluginOperationResult:
         """Execute a plugin subprocess operation with dry-run support.
 
@@ -195,7 +195,7 @@ class PluginCommands:
             args: Full command-line arguments.
             verb: Human-readable verb (``"install"``, ``"uninstall"``, ``"upgrade"``).
             dry_run: If ``True``, only report what would be done.
-            timeout: Subprocess timeout in seconds.
+            timeout_seconds: Subprocess timeout in seconds.
 
         Returns:
             PluginOperationResult indicating outcome.
@@ -212,7 +212,7 @@ class PluginCommands:
             )
 
         try:
-            result = await run_command(args, timeout=timeout)
+            result = await run_command(args, timeout=timeout_seconds)
             if result.returncode != 0:
                 logger.error('%s failed for %s: %s', verb.capitalize(), name, result.stderr)
                 return PluginOperationResult(
@@ -267,9 +267,21 @@ class PluginCommands:
         args = PluginCommands._build_install_args(name)
 
         if dry_run:
-            return await PluginCommands._run_plugin_operation(name, args, verb='install', dry_run=True, timeout=120)
+            return await PluginCommands._run_plugin_operation(
+                name,
+                args,
+                verb='install',
+                dry_run=True,
+                timeout_seconds=120,
+            )
 
-        result = await PluginCommands._run_plugin_operation(name, args, verb='install', dry_run=False, timeout=120)
+        result = await PluginCommands._run_plugin_operation(
+            name,
+            args,
+            verb='install',
+            dry_run=False,
+            timeout_seconds=120,
+        )
         if not result.success:
             return result
 
@@ -315,7 +327,13 @@ class PluginCommands:
             logger.info('Uninstalling plugin: %s', name)
             args = PluginCommands._build_uninstall_args(name)
             results.append(
-                await PluginCommands._run_plugin_operation(name, args, verb='uninstall', dry_run=dry_run, timeout=60)
+                await PluginCommands._run_plugin_operation(
+                    name,
+                    args,
+                    verb='uninstall',
+                    dry_run=dry_run,
+                    timeout_seconds=60,
+                )
             )
 
         return results
@@ -337,7 +355,13 @@ class PluginCommands:
             logger.info('Upgrading plugin: %s', name)
             args = PluginCommands._build_upgrade_args(name)
             results.append(
-                await PluginCommands._run_plugin_operation(name, args, verb='upgrade', dry_run=dry_run, timeout=120)
+                await PluginCommands._run_plugin_operation(
+                    name,
+                    args,
+                    verb='upgrade',
+                    dry_run=dry_run,
+                    timeout_seconds=120,
+                )
             )
 
         return results

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/profile.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for profile."""
+"""CLI command implementation for profile.
 
-"""Portable setup profile commands."""
+Portable setup profile commands.
+"""
 
 import json
 import shutil
@@ -31,7 +32,12 @@ class ProfileCommands:
         self._sync = sync_commands
 
     @staticmethod
-    async def resolve(url: str, *, timeout: int = 300, expected_hash: str | None = None) -> SetupProfile:
+    async def resolve(
+        url: str,
+        *,
+        timeout_seconds: int = 300,
+        expected_hash: str | None = None,
+    ) -> SetupProfile:
         """Download, parse, and validate a setup profile."""
         validate_profile_url(url)
         tmp_dir = Path(tempfile.mkdtemp(prefix='porringer_profile_'))
@@ -41,7 +47,7 @@ class ProfileCommands:
                 DownloadParameters(
                     url=url,
                     destination=destination,
-                    timeout=timeout,
+                    timeout=timeout_seconds,
                     expected_hash=expected_hash,
                 )
             )
@@ -58,7 +64,11 @@ class ProfileCommands:
             shutil.rmtree(tmp_dir, ignore_errors=True)
 
     @staticmethod
-    async def _download_profile_manifests(profile: SetupProfile, *, timeout: int = 300) -> tuple[Path, list[Path]]:
+    async def _download_profile_manifests(
+        profile: SetupProfile,
+        *,
+        timeout_seconds: int = 300,
+    ) -> tuple[Path, list[Path]]:
         """Download profile manifests into a temporary directory.
 
         Each manifest is optionally hash-verified when ``expected_hash`` is
@@ -73,7 +83,7 @@ class ProfileCommands:
                     DownloadParameters(
                         url=manifest.url,
                         destination=destination,
-                        timeout=timeout,
+                        timeout=timeout_seconds,
                         expected_hash=manifest.expected_hash,
                     )
                 )

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/project.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for project."""
+"""CLI command implementation for project.
 
-"""Project and cached-directory inspection commands."""
+Project and cached-directory inspection commands.
+"""
 
 import asyncio
 from pathlib import Path
@@ -61,7 +62,7 @@ class ProjectCommands:
         plugins: DiscoveredPlugins | None = None,
     ) -> ProjectInspection:
         """Inspect one project directory or manifest path."""
-        directory_path = Path(path).resolve()
+        directory_path = await asyncio.to_thread(Path(path).resolve)
         exists = await asyncio.to_thread(directory_path.exists)
         has_manifest = await asyncio.to_thread(self._sync.has_manifest, directory_path) if exists else False
         validation = DirectoryValidationResult(

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/self.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for self."""
+"""CLI command implementation for self.
 
-"""Utilities for managing and checking the Porringer installation version."""
+Utilities for managing and checking the Porringer installation version.
+"""
 
 import contextlib
 import importlib.metadata

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/sync.py

@@ -1,6 +1,6 @@
-"""CLI command implementation for sync."""
+"""CLI command implementation for sync.
 
-"""The sync command module.
+The sync command module.
 
 Thin facade that wires together manifest loading, action building,
 presence detection, and phased execution.  The heavy lifting lives

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/command/tool.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for tool."""
+"""CLI command implementation for tool.
 
-"""Managed tool/package operations over cached manifests."""
+Managed tool/package operations over cached manifests.
+"""
 
 from collections.abc import Callable
 

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/resolver.py

@@ -1,6 +1,7 @@
-"""Backend helpers for resolver."""
+"""Backend helpers for resolver.
 
-"""Resolves."""
+Resolves.
+"""
 
 import logging
 

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/backend/schema.py

@@ -1,6 +1,7 @@
-"""Backend helpers for schema."""
+"""Backend helpers for schema.
 
-"""Backend schema."""
+Backend schema.
+"""
 
 from pathlib import Path
 

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/console/__init__.py

@@ -1,6 +1,6 @@
-"""Public package exports for the console module."""
+"""Public package exports for the console module.
 
-"""Console package for Porringer.
+Console package for Porringer.
 
 This package contains modules and utilities for the command-line interface,
 including command definitions and configuration management.

porringer-0.2.1.dev92/porringer/console/command/__init__.py

@@ -0,0 +1,4 @@
+"""Public package exports for the console.command module.
+
+Commands for the Porringer console application.
+"""

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/console/command/cache.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for cache."""
+"""CLI command implementation for cache.
 
-"""Porringer CLI cache command module for managing manifest directories."""
+Porringer CLI cache command module for managing manifest directories.
+"""
 
 import asyncio
 from pathlib import Path

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/console/command/check.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for check."""
+"""CLI command implementation for check.
 
-"""Porringer CLI check command module for checking package updates via plugins."""
+Porringer CLI check command module for checking package updates via plugins.
+"""
 
 import asyncio
 from typing import Annotated

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/console/command/download.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for download."""
+"""CLI command implementation for download.
 
-"""Porringer CLI download command module for downloading files."""
+Porringer CLI download command module for downloading files.
+"""
 
 import asyncio
 from pathlib import Path

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/console/command/env.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for env."""
+"""CLI command implementation for env.
 
-"""Porringer CLI environment diagnostics."""
+Porringer CLI environment diagnostics.
+"""
 
 import asyncio
 import json

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/console/command/install.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for install."""
+"""CLI command implementation for install.
 
-"""Porringer CLI install command."""
+Porringer CLI install command.
+"""
 
 import asyncio
 from dataclasses import dataclass

{porringer-0.2.1.dev91 → porringer-0.2.1.dev92}/porringer/console/command/open.py

@@ -1,6 +1,7 @@
-"""CLI command implementation for open."""
+"""CLI command implementation for open.
 
-"""Porringer CLI open command — the OS install-link handler entry point."""
+Porringer CLI open command — the OS install-link handler entry point.
+"""
 
 from typing import Annotated