porringer 0.2.1.dev90__tar.gz → 0.2.1.dev92__tar.gz

porringer-0.2.1.dev92/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.1
+Name: porringer
+Version: 0.2.1.dev92
+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.26.8
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: userpath>=1.9.2
+Requires-Dist: packaging>=26.2
+Requires-Dist: aiohttp>=3.14.1
+Requires-Dist: stamina>=26.1.0
+Requires-Dist: filelock>=3.29.4
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/synodic/porringer/development/docs/images/porringer-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/synodic/porringer/development/docs/images/porringer-light.svg">
+    <img width=25% alt="Porringer Logo" src="https://raw.githubusercontent.com/synodic/porringer/development/docs/images/porringer-light.svg">
+  </picture>
+  <br>
+  <em>A meta-package manager for all porridges</em>
+</p>
+
+# Porringer
+
+A CLI and Python API for synchronizing developer environments from a declarative manifest. Porringer reads the packages, tools, runtimes, repositories, and project sync work you want, then delegates the actual work to installed package managers through plugins.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
+[![PyPI version](https://img.shields.io/pypi/v/porringer.svg)](https://pypi.org/project/porringer/)
+
+## Features
+
+- Manifest-driven setup from `porringer.json` or `[tool.porringer]` in `pyproject.toml`.
+- Plugin-based installers for Python, Node, system packages, project sync, runtimes, and source repositories.
+- Read-only previews with stable action IDs, command previews, diagnostics, and JSON output.
+- Sync strategies for minimal installs, latest allowed versions, or exact declared constraints.
+- JSONL progress streams, replay records, and trace artifacts for downstream clients.
+- Python APIs for inspection, execution, cached projects, profiles, tools, progress events, and client snapshots.
+
+## Quick Start
+
+Install Porringer into an isolated CLI environment, then preview a manifest before running it:
+
+```shell
+pipx install porringer
+porringer preview examples/python-dev
+porringer install examples/python-dev
+```
+
+See [Setup](https://synodic.github.io/porringer/setup/) for `uv`, `pip`, and development checkout instructions.
+
+## Development
+
+Porringer uses [PDM](https://pdm-project.org/en/latest/) for local development. Common tasks are defined in `pyproject.toml` under `[tool.pdm.scripts]`:
+
+```shell
+pdm install
+pdm run test
+pdm run generate
+```
+
+See [Development](https://synodic.github.io/porringer/development/) for test lanes, traces, smoke tests, and diagnostics.
+
+For contribution guidelines, see [CONTRIBUTING.md](https://github.com/synodic/.github/blob/stable/CONTRIBUTING.md).
+
+## Documentation
+
+- [Documentation home](https://synodic.github.io/porringer/)
+- [Setup](https://synodic.github.io/porringer/setup/)
+- [Install links](https://synodic.github.io/porringer/links/)
+- [Install command](https://synodic.github.io/porringer/install/)
+- [Preview command](https://synodic.github.io/porringer/preview/)
+- [Check command](https://synodic.github.io/porringer/check/)
+- [Download command](https://synodic.github.io/porringer/download/)
+- [API surface](https://synodic.github.io/porringer/api/)
+- [Development](https://synodic.github.io/porringer/development/)
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.
+
+Copyright © 2025 Synodic Software

porringer-0.2.1.dev92/README.md

@@ -0,0 +1,69 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/synodic/porringer/development/docs/images/porringer-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/synodic/porringer/development/docs/images/porringer-light.svg">
+    <img width=25% alt="Porringer Logo" src="https://raw.githubusercontent.com/synodic/porringer/development/docs/images/porringer-light.svg">
+  </picture>
+  <br>
+  <em>A meta-package manager for all porridges</em>
+</p>
+
+# Porringer
+
+A CLI and Python API for synchronizing developer environments from a declarative manifest. Porringer reads the packages, tools, runtimes, repositories, and project sync work you want, then delegates the actual work to installed package managers through plugins.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
+[![PyPI version](https://img.shields.io/pypi/v/porringer.svg)](https://pypi.org/project/porringer/)
+
+## Features
+
+- Manifest-driven setup from `porringer.json` or `[tool.porringer]` in `pyproject.toml`.
+- Plugin-based installers for Python, Node, system packages, project sync, runtimes, and source repositories.
+- Read-only previews with stable action IDs, command previews, diagnostics, and JSON output.
+- Sync strategies for minimal installs, latest allowed versions, or exact declared constraints.
+- JSONL progress streams, replay records, and trace artifacts for downstream clients.
+- Python APIs for inspection, execution, cached projects, profiles, tools, progress events, and client snapshots.
+
+## Quick Start
+
+Install Porringer into an isolated CLI environment, then preview a manifest before running it:
+
+```shell
+pipx install porringer
+porringer preview examples/python-dev
+porringer install examples/python-dev
+```
+
+See [Setup](https://synodic.github.io/porringer/setup/) for `uv`, `pip`, and development checkout instructions.
+
+## Development
+
+Porringer uses [PDM](https://pdm-project.org/en/latest/) for local development. Common tasks are defined in `pyproject.toml` under `[tool.pdm.scripts]`:
+
+```shell
+pdm install
+pdm run test
+pdm run generate
+```
+
+See [Development](https://synodic.github.io/porringer/development/) for test lanes, traces, smoke tests, and diagnostics.
+
+For contribution guidelines, see [CONTRIBUTING.md](https://github.com/synodic/.github/blob/stable/CONTRIBUTING.md).
+
+## Documentation
+
+- [Documentation home](https://synodic.github.io/porringer/)
+- [Setup](https://synodic.github.io/porringer/setup/)
+- [Install links](https://synodic.github.io/porringer/links/)
+- [Install command](https://synodic.github.io/porringer/install/)
+- [Preview command](https://synodic.github.io/porringer/preview/)
+- [Check command](https://synodic.github.io/porringer/check/)
+- [Download command](https://synodic.github.io/porringer/download/)
+- [API surface](https://synodic.github.io/porringer/api/)
+- [Development](https://synodic.github.io/porringer/development/)
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.
+
+Copyright © 2025 Synodic Software

porringer-0.2.1.dev92/porringer/__init__.py

@@ -0,0 +1,60 @@
+"""Public package exports.
+
+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.
+"""
+
+import logging
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _metadata_version
+
+from porringer.api import API
+from porringer.backend.command.core.discovery import DiscoveredPlugins
+from porringer.core.plugin_schema.runtime import RuntimeContext
+from porringer.schema.cache import LocalConfiguration
+from porringer.schema.execution import SetupParameters
+from porringer.schema.manifest import SetupManifest
+from porringer.utility.exception import (
+    CommandTimeoutError,
+    ManifestError,
+    ManifestValidationCode,
+    NotSupportedError,
+    PluginDependencyError,
+    PluginError,
+    PorringerError,
+    ProcessError,
+    SetupError,
+    UpdateError,
+)
+
+__all__ = [
+    'API',
+    'CommandTimeoutError',
+    'DiscoveredPlugins',
+    'LocalConfiguration',
+    'ManifestError',
+    'ManifestValidationCode',
+    'NotSupportedError',
+    'PluginDependencyError',
+    'PluginError',
+    'PorringerError',
+    'ProcessError',
+    'RuntimeContext',
+    'SetupError',
+    'SetupManifest',
+    'SetupParameters',
+    'UpdateError',
+    '__version__',
+]
+
+try:
+    __version__: str = _metadata_version('porringer')
+except PackageNotFoundError:
+    __version__ = '0.0.0'
+
+# Register a NullHandler so library consumers can attach their own logging
+# handlers without seeing warnings about an unconfigured logger.
+# See https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library
+logging.getLogger(__name__).addHandler(logging.NullHandler())

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

@@ -1,17 +1,25 @@
-"""API for Porringer"""
+"""Helpers for api.
+
+Public API surface for Porringer.
+"""
 
 import asyncio
 import logging
 
 from porringer.backend.builder import Builder
 from porringer.backend.cache import DirectoryCacheManager
+from porringer.backend.command.client import ClientCommands
 from porringer.backend.command.core.discovery import DiscoveredPlugins, discover_all_plugins
 from porringer.backend.command.package import PackageCommands
 from porringer.backend.command.plugin import PluginCommands
+from porringer.backend.command.profile import ProfileCommands
+from porringer.backend.command.project import ProjectCommands
 from porringer.backend.command.self import check_self_updates
 from porringer.backend.command.sync import SyncCommands
+from porringer.backend.command.tool import ToolCommands
 from porringer.backend.resolver import resolve_configuration
 from porringer.backend.schema import GlobalConfiguration
+from porringer.core.plugin_schema.runtime import RuntimeContext
 from porringer.schema import (
     DownloadParameters,
     DownloadResult,
@@ -25,19 +33,14 @@ logger = logging.getLogger(__name__)
 
 
 class API:
-    """API for programmatic access to Porringer's functionality.
-
-    Provides namespace sub-APIs:
+    """Programmatic interface for Porringer's core operations.
 
-    * ``api.plugin``  — porringer extension management (install,
-      update, remove extension packages).
-    * ``api.package`` — managed-package operations (list, install,
-      upgrade, uninstall packages, check for updates).
-    * ``api.sync``    — manifest loading, streaming execution.
-    * ``api.cache``   — directory registration and validation.
+    The class exposes stable sub-APIs for manifest inspection and execution,
+    package management, project registration, cached tool operations, and
+    profile handling.
 
     Cross-cutting helpers live directly on the ``API`` class:
-    :meth:`discover_plugins`, :meth:`check_self_updates`,
+    :meth:`discover_plugins`, :meth:`check_self_updates`, and
     :meth:`download`.
     """
 
@@ -46,7 +49,7 @@ class API:
         local_configuration: LocalConfiguration,
         global_configuration: GlobalConfiguration | None = None,
     ) -> None:
-        """Initializes the API
+        """Initializes the API.
 
         Args:
             local_configuration: The local configuration.
@@ -57,13 +60,17 @@ class API:
 
         configuration = resolve_configuration(local_configuration, global_configuration)
 
-        self.cache = DirectoryCacheManager(configuration.data_directory)
+        self._cache = DirectoryCacheManager(configuration.data_directory)
 
-        self.plugin = PluginCommands()
+        self.extension = PluginCommands()
         self.package = PackageCommands()
-        self.sync = SyncCommands(self.cache)
+        self.sync = SyncCommands(self._cache)
+        self.project = ProjectCommands(self._cache, self.sync)
+        self.tool = ToolCommands(self.sync, self.package)
+        self.profile = ProfileCommands(self.sync)
+        self.client = ClientCommands(self.project, self.tool)
 
-    # --- Discovery & runtime resolution ---
+    # Discover plugins and resolve runtime information.
 
     @staticmethod
     async def discover_plugins(
@@ -76,14 +83,14 @@ class API:
         This is the recommended entry-point for GUI callers.  It
         returns a :class:`DiscoveredPlugins` object that can be
         forwarded to every subsequent operation
-        (``api.sync.execute_stream``, ``api.package.list``,
+        (``api.sync.inspect``, ``api.sync.run``, ``api.package.list``,
         ``api.package.upgrade``, etc.) so that plugin discovery and
         runtime resolution happen exactly once.
 
         Args:
             use_cache: Reuse cached entry-point scan metadata when
                 ``True`` (the default).  Pass ``False`` to force a
-                fresh scan after installing/removing plugin packages.
+                fresh scan after installing or uninstalling extension packages.
             resolve_runtime: When ``True`` (the default), resolve a
                 :class:`RuntimeContext` from available
                 ``RuntimeProvider`` plugins and attach it to the
@@ -96,15 +103,29 @@ class API:
         """
         plugins = await asyncio.to_thread(discover_all_plugins, use_cache=use_cache)
         if resolve_runtime:
-            plugins.runtime_context = await Builder.resolve_runtime_context(plugins.environments)
-            logger.debug(
-                'discover_plugins: runtime_context=%s',
-                {k: str(v) for k, v in plugins.runtime_context.executables.items()}
-                if plugins.runtime_context.executables
-                else '<empty>',
-            )
+            await API.resolve_runtime_context(plugins)
         return plugins
 
+    @staticmethod
+    async def resolve_runtime_context(plugins: DiscoveredPlugins) -> RuntimeContext:
+        """Resolve and attach runtime context for previously discovered plugins.
+
+        Args:
+            plugins: A :class:`DiscoveredPlugins` object, usually from
+                :meth:`discover_plugins` with ``resolve_runtime=False``.
+
+        Returns:
+            The resolved :class:`RuntimeContext` attached to ``plugins``.
+        """
+        plugins.runtime_context = await Builder.resolve_runtime_context(plugins.environments)
+        logger.debug(
+            'resolve_runtime_context: runtime_context=%s',
+            {k: str(v) for k, v in plugins.runtime_context.executables.items()}
+            if plugins.runtime_context.executables
+            else '<empty>',
+        )
+        return plugins.runtime_context
+
     @staticmethod
     async def check_self_updates() -> PackageUpdateInfo:
         """Check for updates to the Porringer package by querying PyPI.

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

@@ -1,4 +1,6 @@
-"""Backend package for Porringer.
+"""Public package exports for the backend module.
+
+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.dev90 → porringer-0.2.1.dev92}/porringer/backend/backend.py

@@ -1,9 +1,11 @@
-"""Backend resolution for mapping (kind, ecosystem) pairs to installer plugins.
+"""Backend helpers for backend.
 
-The `BackendResolver` determines which plugin should handle each
-`(PluginKind, ecosystem)` pair declared in a manifest.  For example,
-`(PACKAGE, "python")` might resolve to `uv` or `pip` depending
-on availability and user preferences.
+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,
+`(PACKAGE, "python")` might resolve to `uv`, `pip`, or another matching
+plugin depending on availability and user preferences.
 """
 
 import logging
@@ -16,7 +18,7 @@ from porringer.core.schema import Ecosystem, Plugin, PluginKind
 
 logger = logging.getLogger(__name__)
 
-# Type alias for any plugin that participates in backend resolution.
+# A plugin that participates in backend resolution.
 BackendPlugin = Plugin
 
 
@@ -62,19 +64,18 @@ class BackendResolver:
         self._preferences = preferences or {}
         self._runtime_context = runtime_context
 
-        # Index: (kind, ecosystem) -> [plugin_name, ...]
+        # Index registered plugin names by `(kind, ecosystem)` pair.
         self._backend_plugins: dict[tuple[PluginKind, Ecosystem], list[str]] = defaultdict(list)
         for name, plugin in self._all_plugins.items():
             ecosystem = type(plugin).ecosystem()
             if ecosystem is not None:
                 self._backend_plugins[(type(plugin).plugin_kind(), ecosystem)].append(name)
 
-        # Resolve only the pairs the caller actually needs.  When
-        # *needed_pairs* is ``None`` every registered pair is resolved
-        # (existing behaviour).  Passing an explicit set avoids
-        # spurious "No available plugin" log messages for ecosystems
-        # that are registered via entry-points but irrelevant to the
-        # current manifest.
+        # Resolve only the pairs the caller needs right away. When
+        # *needed_pairs* is ``None``, every registered pair is resolved to
+        # preserve the existing behavior. Passing an explicit set avoids
+        # noisy "No available plugin" log messages for ecosystems that are
+        # registered via entry points but irrelevant to the current manifest.
         resolve_keys = needed_pairs if needed_pairs is not None else set(self._backend_plugins)
 
         # Resolve once and cache

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

@@ -1,8 +1,10 @@
-"""Builder — generic plugin discovery and construction.
+"""Backend helpers for builder.
 
-Provides `Builder.find_plugins()` and `Builder.build_plugins()`
-for discovering and instantiating plugins from any entry-point group
-without per-kind boilerplate.
+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
+per-plugin-kind boilerplate.
 """
 
 import asyncio
@@ -16,7 +18,12 @@ from packaging.utils import canonicalize_name
 from packaging.version import Version
 
 from porringer.core.plugin_schema.environment import Environment
-from porringer.core.plugin_schema.runtime import ResolvedRuntime, RuntimeContext, RuntimeProvider
+from porringer.core.plugin_schema.runtime import (
+    DefaultRuntimeExecutableProvider,
+    ResolvedRuntime,
+    RuntimeContext,
+    RuntimeProvider,
+)
 from porringer.core.schema import Distribution, Plugin, PluginDependency, PluginParameters
 
 logger = logging.getLogger(__name__)
@@ -36,12 +43,29 @@ async def _resolve_provider_executable(
     env: RuntimeProvider,
     kind: str,
 ) -> Path | None:
-    """Resolve a single executable from *env* trying default_tag then available_tags.
+    """Resolve a single executable from *env* by trying the fastest route first.
 
     Returns the resolved :class:`~pathlib.Path` or ``None`` when no
-    executable could be obtained.
+    executable can be obtained.
     """
-    # --- Fast path: provider-reported default --------------------------
+    # Use the provider's built-in default executable when it is available.
+    if isinstance(env, DefaultRuntimeExecutableProvider):
+        try:
+            executable = await env.default_executable()
+        except Exception:
+            logger.debug("default_executable() failed for '%s'", name, exc_info=True)
+            executable = None
+
+        if executable is not None:
+            logger.debug(
+                "Resolved runtime '%s' via provider '%s' default_executable: path=%s",
+                kind,
+                name,
+                executable,
+            )
+            return executable
+
+    # Try the provider's preferred default tag next.
     try:
         default = await env.default_tag()
     except Exception:
@@ -76,7 +100,7 @@ async def _resolve_provider_executable(
             name,
         )
 
-    # --- Fallback: enumerate all tags ----------------------------------
+    # Fall back to scanning every available tag.
     try:
         tags = await env.available_tags()
     except Exception:
@@ -122,7 +146,7 @@ async def _resolve_provider_executable(
 
 
 class Builder:
-    """Helper class for building Porringer projects"""
+    """Helper class for building Porringer projects."""
 
     # ------------------------------------------------------------------
     # Generic discovery & construction
@@ -134,7 +158,7 @@ class Builder:
         base_class: type[T],
         *,
         check_dependencies: bool = False,
-    ) -> list[PluginInformation[T]]:
+    ) -> tuple[list[PluginInformation[T]], dict[str, str]]:
         """Search for registered plugins in an entry-point group.
 
         Scans `porringer.<group>` for classes that are subclasses of
@@ -147,9 +171,12 @@ class Builder:
                 and filters out plugins with unmet required dependencies.
 
         Returns:
-            A list of discovered plugin information objects.
+            A tuple of ``(infos, load_errors)`` where *load_errors* maps
+            entry-point name to a human-readable error message for every
+            plugin that could not be loaded.
         """
         plugin_types: list[PluginInformation[T]] = []
+        load_errors: dict[str, str] = {}
 
         entry_points = list(metadata.entry_points(group=f'porringer.{group}'))
         logger.debug('Entry points for porringer.%s: %s', group, [ep.name for ep in entry_points])
@@ -159,12 +186,15 @@ class Builder:
                 loaded_type = entry_point.load()
             except Exception as e:
                 logger.warning("Plugin '%s' could not be loaded: %s. Skipping", entry_point.name, e)
+                load_errors[entry_point.name] = str(e)
                 continue
 
             plugin_name = str(canonicalize_name(entry_point.name))
 
             if entry_point.dist is None:
+                msg = 'plugin is not installed'
                 logger.warning("Plugin '%s' is not installed. Skipping", plugin_name)
+                load_errors[plugin_name] = msg
                 continue
 
             if not issubclass(loaded_type, base_class):
@@ -176,7 +206,7 @@ class Builder:
         if check_dependencies:
             plugin_types = Builder._resolve_dependencies(plugin_types)
 
-        return plugin_types
+        return plugin_types, load_errors
 
     @staticmethod
     def build_plugin[T: Plugin](info: PluginInformation[T]) -> T:

{porringer-0.2.1.dev90 → porringer-0.2.1.dev92}/porringer/backend/cache.py

@@ -1,9 +1,11 @@
 """Directory cache management for manifest directories."""
 
+import contextlib
 import json
 import logging
 from pathlib import Path
 
+from filelock import FileLock
 from pydantic import ValidationError
 
 from porringer.backend.command.manifest import has_manifest
@@ -69,32 +71,26 @@ class DirectoryCacheManager:
         return self._cache
 
     def _save(self) -> None:
-        """Save cache to disk atomically."""
+        """Save cache to disk atomically under a cross-process lock."""
         if self._cache is None:
             return
 
         self.data_directory.mkdir(parents=True, exist_ok=True)
 
-        # Write to temp file then rename for atomic write
         temp_path = self._cache_path.with_suffix('.tmp')
+        lock_path = self._cache_path.with_suffix(f'{self._cache_path.suffix}.lock')
         try:
-            temp_path.write_text(self._cache.model_dump_json(indent=2), encoding='utf-8')
-            temp_path.replace(self._cache_path)
+            with FileLock(lock_path):
+                temp_path.write_text(self._cache.model_dump_json(indent=2), encoding='utf-8')
+                temp_path.replace(self._cache_path)
             logger.debug(f'Saved directory cache to {self._cache_path}')
-        except PermissionError as e:
-            if temp_path.exists():
-                temp_path.unlink()
-            logger.error(f'Permission denied writing cache: {e}')
-            raise
         except OSError as e:
-            if temp_path.exists():
-                temp_path.unlink()
             logger.error(f'Failed to write cache: {e}')
             raise
-        except Exception:
+        finally:
             if temp_path.exists():
-                temp_path.unlink()
-            raise
+                with contextlib.suppress(OSError):
+                    temp_path.unlink()
 
     @staticmethod
     def _normalize_path(path: Path) -> Path:

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

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

porringer-0.2.1.dev92/porringer/backend/command/client.py

@@ -0,0 +1,47 @@
+"""CLI command implementation for client.
+
+Client-oriented aggregate commands.
+"""
+
+import asyncio
+
+from porringer.backend.command.core.discovery import DiscoveredPlugins, discover_all_plugins
+from porringer.backend.command.core.inspection import plugin_snapshots
+from porringer.backend.command.project import ProjectCommands
+from porringer.backend.command.tool import ToolCommands
+from porringer.schema import ClientSnapshot, InspectionMode, ManagedToolReport
+from porringer.utility.observability import result_status
+
+
+class ClientCommands:
+    """Aggregate read models for long-lived clients."""
+
+    def __init__(self, project_commands: ProjectCommands, tool_commands: ToolCommands) -> None:
+        """Initialize client commands."""
+        self._project = project_commands
+        self._tool = tool_commands
+
+    async def snapshot(
+        self,
+        *,
+        inspection_mode: InspectionMode = InspectionMode.FAST,
+        include_updates: bool = False,
+        plugins: DiscoveredPlugins | None = None,
+    ) -> ClientSnapshot:
+        """Return a low-latency state bundle for GUI or agent clients."""
+        shared_plugins = plugins or await asyncio.to_thread(discover_all_plugins, use_cache=True)
+        projects = await self._project.inspect_cached(inspection_mode=inspection_mode, plugins=shared_plugins)
+        updates: ManagedToolReport | None = None
+        if include_updates:
+            updates = await self._tool.check_updates(plugins=shared_plugins)
+        diagnostics = projects.diagnostics + (updates.diagnostics if updates is not None else ())
+        follow_up_actions = projects.follow_up_actions + (updates.follow_up_actions if updates is not None else ())
+        return ClientSnapshot(
+            status=result_status(projects.success and (updates.success if updates is not None else True), diagnostics),
+            inspection_mode=inspection_mode,
+            plugins=plugin_snapshots(shared_plugins),
+            projects=projects,
+            updates=updates,
+            diagnostics=diagnostics,
+            follow_up_actions=follow_up_actions,
+        )

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

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