ps-plugin-sdk 0.2.8__tar.gz

ps_plugin_sdk-0.2.8/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: ps-plugin-sdk
+Version: 0.2.8
+Summary: 
+Requires-Python: >=3.10,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: poetry (>=2.3.1,<3.0.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)

ps_plugin_sdk-0.2.8/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name        = "ps-plugin-sdk"
+description = ""
+requires-python = ">=3.10,<3.14"
+version = "0.2.8"
+dependencies = [
+    "poetry<3.0.0,>=2.3.1",
+    "pydantic<3.0.0,>=2.12.5",
+]
+
+[tool.poetry.group.ps.dependencies]
+ps-version = ">=0.2.8,<0.3.0"
+
+[tool.poetry]
+packages = [ { include = "ps/plugin/sdk", from = "src" } ]
+
+[tool.ps-plugin]
+host-project = ".."
+
+[build-system]
+requires    = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/__init__.py

@@ -0,0 +1 @@
+__all__ = []

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/events/__init__.py

@@ -0,0 +1,19 @@
+from ._cleo_inputs import CommandOptionsProtocol, ensure_argument, ensure_option
+from ._protocols import (
+    PoetryActivateProtocol,
+    PoetryCommandProtocol,
+    PoetryErrorProtocol,
+    PoetrySignalProtocol,
+    PoetryTerminateProtocol,
+)
+
+__all__ = [
+    "PoetryActivateProtocol",
+    "PoetryCommandProtocol",
+    "PoetryErrorProtocol",
+    "PoetrySignalProtocol",
+    "PoetryTerminateProtocol",
+    "ensure_argument",
+    "ensure_option",
+    "CommandOptionsProtocol",
+]

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/events/_cleo_inputs.py

@@ -0,0 +1,25 @@
+from typing import Protocol
+
+from cleo.io.inputs.option import Option
+from cleo.io.inputs.argument import Argument
+
+
+class CommandOptionsProtocol(Protocol):
+    options: list[Option]
+    arguments: list[Argument]
+
+
+def ensure_argument(command: CommandOptionsProtocol, argument: Argument) -> bool:
+    existing_names = {arg.name for arg in command.arguments}
+    if argument.name not in existing_names:
+        command.arguments.append(argument)
+        return True
+    return False
+
+
+def ensure_option(command: CommandOptionsProtocol, option: Option) -> bool:
+    existing_names = {opt.name for opt in command.options}
+    if option.name not in existing_names:
+        command.options.append(option)
+        return True
+    return False

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/events/_protocols.py

@@ -0,0 +1,32 @@
+from cleo.events.console_command_event import ConsoleCommandEvent
+from cleo.events.console_error_event import ConsoleErrorEvent
+from cleo.events.console_signal_event import ConsoleSignalEvent
+from cleo.events.console_terminate_event import ConsoleTerminateEvent
+from cleo.events.event_dispatcher import EventDispatcher
+from poetry.console.application import Application
+from typing_extensions import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PoetryActivateProtocol(Protocol):
+    def poetry_activate(self, application: Application) -> bool: ...
+
+
+@runtime_checkable
+class PoetryCommandProtocol(Protocol):
+    def poetry_command(self, event: ConsoleCommandEvent, dispatcher: EventDispatcher) -> None: ...
+
+
+@runtime_checkable
+class PoetryErrorProtocol(Protocol):
+    def poetry_error(self, event: ConsoleErrorEvent, dispatcher: EventDispatcher) -> None: ...
+
+
+@runtime_checkable
+class PoetryTerminateProtocol(Protocol):
+    def poetry_terminate(self, event: ConsoleTerminateEvent, dispatcher: EventDispatcher) -> None: ...
+
+
+@runtime_checkable
+class PoetrySignalProtocol(Protocol):
+    def poetry_signal(self, event: ConsoleSignalEvent, dispatcher: EventDispatcher) -> None: ...

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/logging/__init__.py

@@ -0,0 +1,8 @@
+from ._logging import get_module_name, get_module_verbal_name, log_debug, log_verbose
+
+__all__ = [
+    "get_module_name",
+    "get_module_verbal_name",
+    "log_debug",
+    "log_verbose",
+]

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/logging/_logging.py

@@ -0,0 +1,35 @@
+from typing import Type, Union
+
+from cleo.io.io import IO
+
+
+def get_module_verbal_name(obj: Union[Type, object], include_type: bool = False) -> str:
+    cls = obj if isinstance(obj, type) else type(obj)
+    cls_name = f"<fg=dark_gray>{cls.__module__}.{cls.__name__}</>"
+    name_attr = getattr(cls, "name", None)
+
+    if isinstance(name_attr, str):
+        return f"<fg=light_green>{name_attr}</> ({cls_name})" if include_type else name_attr
+
+    return cls_name
+
+
+def get_module_name(obj: Union[Type, object]) -> str:
+    cls = obj if isinstance(obj, type) else type(obj)
+    cls_name = f"{cls.__module__}.{cls.__name__}"
+    name_attr = getattr(cls, "name", None)
+
+    if isinstance(name_attr, str):
+        return name_attr
+
+    return cls_name
+
+
+def log_verbose(io: IO, message: str) -> None:
+    if io.is_verbose():
+        io.write_line(message)
+
+
+def log_debug(io: IO, message: str) -> None:
+    if io.is_debug():
+        io.write_line(message)

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/mixins/__init__.py

@@ -0,0 +1,5 @@
+from ._name_aware_protocol import NameAwareProtocol
+
+__all__ = [
+    "NameAwareProtocol",
+]

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/mixins/_name_aware_protocol.py

@@ -0,0 +1,7 @@
+from typing import ClassVar
+from typing_extensions import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NameAwareProtocol(Protocol):
+    name: ClassVar[str]

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/project/__init__.py

@@ -0,0 +1,28 @@
+from ._models import Project, ProjectDependency, ProjectFeedSource, SourcePriority, normalize_dist_name, dist_name_variants
+from ._environment import Environment
+from ._projects_helper import filter_projects
+from ._parsers import (
+    parse_name_from_document,
+    parse_dependencies_from_document,
+    parse_version_from_document,
+    parse_project,
+    parse_sources_from_document,
+    parse_source_dirs_from_document,
+)
+
+__all__ = [
+    "Project",
+    "ProjectDependency",
+    "ProjectFeedSource",
+    "SourcePriority",
+    "Environment",
+    "filter_projects",
+    "normalize_dist_name",
+    "dist_name_variants",
+    "parse_name_from_document",
+    "parse_dependencies_from_document",
+    "parse_version_from_document",
+    "parse_project",
+    "parse_sources_from_document",
+    "parse_source_dirs_from_document",
+]

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/project/_environment.py

@@ -0,0 +1,106 @@
+from pathlib import Path
+from typing import Iterable
+import tempfile
+import shutil
+import hashlib
+
+from ._models import Project
+from ._parsers import parse_project
+
+
+class Environment:
+    _host_project: Project
+    _projects: dict[Path, Project]
+    _backups: dict[Path, Path]
+
+    def __init__(self, entry_project_path: Path):
+        self._projects = {}
+        self._backups = {}
+        self._entry_project = self.add_project(entry_project_path, is_host=True)
+
+    @property
+    def host_project(self) -> Project:
+        return self._host_project
+
+    @property
+    def entry_project(self) -> Project:
+        return self._entry_project
+
+    @property
+    def projects(self) -> Iterable[Project]:
+        return self._projects.values()
+
+    def project_dependencies(self, project: Project) -> list[Project]:
+        result: list[Project] = []
+        for dep in project.dependencies:
+            resolved = dep.resolved_project_path
+            if resolved and resolved in self._projects:
+                result.append(self._projects[resolved])
+        return result
+
+    def sorted_projects(self, projects: Iterable[Project]) -> list[Project]:
+        project_list = list(projects)
+        project_set = {p.path for p in project_list}
+        result: list[Project] = []
+        visited: set[Path] = set()
+
+        def _visit(p: Project) -> None:
+            if p.path in visited:
+                return
+            visited.add(p.path)
+            for dep in self.project_dependencies(p):
+                if dep.path in project_set:
+                    _visit(dep)
+            result.append(p)
+
+        for p in project_list:
+            _visit(p)
+        return result
+
+    def add_project(self, project_path: Path, is_host: bool = False) -> Project:
+        project_path = project_path.resolve()
+        if project_path.is_dir():
+            project_path = project_path / "pyproject.toml"
+        if project_path in self._projects:
+            project = self._projects[project_path]
+        else:
+            project = parse_project(project_path)
+            if project is None:
+                raise FileNotFoundError(f"Project file not found at path: {project_path}")
+            self._projects[project_path] = project
+            if is_host:
+                self._host_project = project
+            for dependency in project.dependencies:
+                if dependency.path and dependency.develop is not False:
+                    self.add_project(dependency.path)
+            if project.plugin_settings.host_project:
+                host_project_path = Path(project.path.parent / project.plugin_settings.host_project).resolve()
+                if host_project_path.is_dir():
+                    host_project_path = host_project_path / "pyproject.toml"
+                self.add_project(host_project_path, is_host=True)
+
+        return project
+
+    def backup_projects(self, projects: Iterable[Project]) -> None:
+        for project in projects:
+            pyproject_path = project.path
+            if pyproject_path in self._backups:
+                continue
+
+            temp_dir = Path(tempfile.gettempdir())
+            path_hash = hashlib.sha256(str(pyproject_path).encode()).hexdigest()[:16]
+            backup_path = temp_dir / f"pyproject_backup_{path_hash}.toml"
+            shutil.copy2(pyproject_path, backup_path)
+            self._backups[pyproject_path] = backup_path
+
+    def restore_projects(self, projects: Iterable[Project]) -> None:
+        for project in projects:
+            pyproject_path = project.path
+            if pyproject_path not in self._backups:
+                continue
+
+            backup_path = self._backups[pyproject_path]
+            if backup_path.exists():
+                shutil.copy2(backup_path, pyproject_path)
+                backup_path.unlink()
+            del self._backups[pyproject_path]

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/project/_models.py

@@ -0,0 +1,245 @@
+import os
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Optional
+from pydantic import BaseModel, ConfigDict, Field
+from tomlkit import TOMLDocument, inline_table, table as toml_table
+from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
+
+from ps.version import Version, VersionConstraint
+
+from ..settings._settings import PluginSettings
+from ..toml._toml_value import TomlValue
+
+
+def normalize_dist_name(name: str) -> str:
+    return name.lower().replace("-", "_").replace(".", "_")
+
+
+def dist_name_variants(name: str) -> set[str]:
+    lower = name.lower()
+    return {
+        lower,
+        lower.replace("-", "_").replace(".", "_"),
+        lower.replace("_", "-"),
+    }
+
+
+class SourcePriority(StrEnum):
+    DEFAULT = "default"
+    PRIMARY = "primary"
+    SECONDARY = "secondary"
+    SUPPLEMENTAL = "supplemental"
+    EXPLICIT = "explicit"
+
+
+class ProjectFeedSource(BaseModel):
+    name: str
+    url: Optional[str] = None
+    priority: Optional[SourcePriority] = None
+
+
+class ProjectDependency(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    location: TomlValue = Field(exclude=True)
+    name: Optional[str] = None
+
+    # Classification
+    group: Optional[str] = None
+    optional: Optional[bool] = None
+    python: Optional[str] = None
+    markers: Optional[str] = None
+    extras: Optional[list[str]] = None
+    source: Optional[str] = None
+
+    # Location-based
+    path: Optional[Path] = None
+    develop: Optional[bool] = None
+    url: Optional[str] = None
+
+    # VCS
+    git: Optional[str] = None
+    branch: Optional[str] = None
+    tag: Optional[str] = None
+    rev: Optional[str] = None
+
+    @property
+    def version(self) -> Optional[str]:
+        if not self.location.exists:
+            return None
+
+        current_value = self.location.value
+        if isinstance(current_value, str):
+            # Either PEP 508 string or Poetry simple string
+            try:
+                req = Requirement(current_value)
+                return str(req.specifier) if req.specifier else "*"
+            except (ValueError, TypeError):
+                # Poetry simple string format
+                return current_value
+        elif isinstance(current_value, dict):
+            # Poetry dict format
+            version = current_value.get("version")
+            return str(version) if version is not None else None
+
+        return None
+
+    @property
+    def version_constraint(self) -> Optional[SpecifierSet]:
+        version_str = self.version
+        if not version_str:
+            return None
+        try:
+            # Handle Poetry wildcard (any version)
+            if version_str == "*":
+                return SpecifierSet("")
+            # Convert Poetry caret syntax to PEP 440
+            if version_str.startswith("^"):
+                version_str = self._convert_caret_to_pep440(version_str[1:])
+            return SpecifierSet(version_str)
+        except (ValueError, TypeError):
+            return None
+
+    def _convert_caret_to_pep440(self, version_str: str) -> str:
+        try:
+            version = Version.parse(version_str)
+            assert version is not None, "Invalid version for caret syntax"
+            return version.get_constraint(VersionConstraint.COMPATIBLE)
+        except Exception:
+            # Fallback to original if parsing fails
+            return f"^{version_str}"
+
+    def update_version(self, version_constraint: str | SpecifierSet) -> None:
+        if not self.location.exists:
+            return
+
+        # Convert SpecifierSet to string
+        constraint_str = str(version_constraint) if isinstance(version_constraint, SpecifierSet) else version_constraint
+
+        current_value = self.location.value
+
+        if isinstance(current_value, str):
+            # PEP 621/508 format: reconstruct the requirement string
+            self._update_pep508_version(constraint_str)
+        elif isinstance(current_value, dict):
+            # Poetry dict format
+            # Switch path/VCS/url dependencies to plain constraint
+            # to avoid invalid mixed-table definitions.
+            is_source_dependency = any(key in current_value for key in ("path", "git", "url"))
+            if is_source_dependency:
+                self.location.set(constraint_str)
+            else:
+                current_value["version"] = constraint_str
+                self.location.set(current_value)
+        else:
+            # Poetry simple string format: replace entire value
+            self.location.set(constraint_str)
+
+    def _update_pep508_version(self, version_constraint: str) -> None:
+        try:
+            current = self.location.value
+            if not isinstance(current, str):
+                return
+
+            req = Requirement(current)
+
+            # Reconstruct with new version constraint
+            parts = [req.name]
+            if self.extras:
+                parts.append(f"[{','.join(self.extras)}]")
+            parts.append(version_constraint)
+            if req.marker:
+                parts.append(f"; {req.marker}")
+
+            self.location.set("".join(parts))
+        except (ValueError, TypeError):
+            # Fallback: just set the version string
+            self.location.set(version_constraint)
+
+    @property
+    def resolved_project_path(self) -> Optional[Path]:
+        if self.path is None:
+            return None
+        if self.path.suffix == ".toml":
+            return self.path.resolve()
+        return (self.path / "pyproject.toml").resolve()
+
+
+class Project(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: TomlValue
+    version: TomlValue
+    path: Path
+    document: TOMLDocument = Field(exclude=True)
+    dependencies: list[ProjectDependency]
+    sources: list[ProjectFeedSource]
+    source_dirs: list[Path]
+    plugin_settings: PluginSettings
+
+    def save(self) -> None:
+        with open(self.path, "w") as f:
+            f.write(self.document.as_string())
+
+    def add_dependency(
+        self,
+        name: str,
+        constraint: Optional[str] = None,
+        group: Optional[str] = None,
+    ) -> "ProjectDependency":
+        entry: Any = constraint if constraint is not None else "*"
+        return self._write_dependency(name, entry, resolved_path=None, develop=None, group=group)
+
+    def add_development_dependency(
+        self,
+        name: str,
+        path: Path,
+        group: Optional[str] = None,
+    ) -> "ProjectDependency":
+        project_dir = self.path.parent
+        entry: Any = inline_table()
+        rel = Path(os.path.relpath(path, project_dir))
+        entry.append("path", str(rel).replace("\\", "/"))
+        entry.append("develop", True)
+        return self._write_dependency(name, entry, resolved_path=path.resolve(), develop=True, group=group)
+
+    def _write_dependency(
+        self,
+        name: str,
+        entry: Any,
+        resolved_path: Optional[Path],
+        develop: Optional[bool],
+        group: Optional[str],
+    ) -> "ProjectDependency":
+        if group is None:
+            dep_section = "tool.poetry.dependencies"
+            deps_table = self._get_or_create_table("tool", "poetry", "dependencies")
+        else:
+            dep_section = f"tool.poetry.group.{group}.dependencies"
+            group_table = self._get_or_create_table("tool", "poetry", "group", group)
+            if "dependencies" not in group_table:
+                group_table["dependencies"] = toml_table()
+            deps_table = group_table["dependencies"]
+
+        deps_table[name] = entry
+        location = TomlValue.locate(self.document, [f"{dep_section}.{name}"])
+
+        dep = ProjectDependency(
+            location=location,
+            name=name,
+            group=group,
+            path=resolved_path,
+            develop=develop,
+        )
+        self.dependencies.append(dep)
+        return dep
+
+    def _get_or_create_table(self, *keys: str) -> Any:
+        current: Any = self.document
+        for key in keys:
+            if key not in current:
+                current[key] = toml_table()
+            current = current[key]
+        return current

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/project/_parsers.py

@@ -0,0 +1,154 @@
+from pathlib import Path
+from typing import Any, Optional
+from tomlkit import TOMLDocument, parse
+from packaging.requirements import Requirement
+
+from ._models import Project, ProjectDependency, ProjectFeedSource, SourcePriority
+from ..toml._toml_value import TomlValue
+from ..settings._parsers import parse_plugin_settings_from_document
+
+
+def parse_name_from_document(document: TOMLDocument) -> TomlValue:
+    return TomlValue.locate(document, ["project.name", "tool.poetry.name"])
+
+
+def parse_version_from_document(document: TOMLDocument) -> TomlValue:
+    return TomlValue.locate(document, ["project.version", "tool.poetry.version"])
+
+
+def parse_dependency(document: TOMLDocument, dep_path: str, name: str, value: Any, group: Optional[str], project_path: Optional[Path] = None) -> Optional[ProjectDependency]:
+    location = TomlValue.locate(document, [dep_path])
+    if isinstance(value, str):
+        return ProjectDependency(
+            location=location,
+            name=name,
+            group=group,
+        )
+    if isinstance(value, dict):
+        local_path = None
+        if value.get("path"):
+            local_path = Path(value["path"])
+            if project_path and not local_path.is_absolute():
+                local_path = (project_path.parent / local_path).resolve()
+        return ProjectDependency(
+            location=location,
+            name=name,
+            group=group,
+            optional=value.get("optional"),
+            python=value.get("python"),
+            markers=value.get("markers"),
+            extras=list(value.get("extras", [])) or None,
+            source=value.get("source"),
+            path=local_path,
+            develop=value.get("develop"),
+            url=value.get("url"),
+            git=value.get("git"),
+            branch=value.get("branch"),
+            tag=value.get("tag"),
+            rev=value.get("rev"),
+        )
+
+    return None
+
+
+def parse_dependencies_from_document(document: TOMLDocument, project_path: Optional[Path] = None) -> list[ProjectDependency]:
+    dependencies = []
+
+    # Support PEP 621 format (array of PEP 508 strings)
+    pep621_deps = TomlValue.locate(document, ["project.dependencies"]).value
+    if pep621_deps and isinstance(pep621_deps, list):
+        for idx, dep_string in enumerate(pep621_deps):
+            if not isinstance(dep_string, str):
+                continue
+
+            try:
+                req = Requirement(dep_string)
+                dep_path = f"project.dependencies[{idx}]"
+                location = TomlValue.locate(document, [dep_path])
+
+                dependencies.append(ProjectDependency(
+                    location=location,
+                    name=req.name,
+                    extras=list(req.extras) if req.extras else None,
+                    markers=str(req.marker) if req.marker else None,
+                    group=None,
+                ))
+            except (ValueError, TypeError):
+                # Skip invalid dependency specifications
+                continue
+
+    # Support Poetry format (dictionary)
+    main_deps = TomlValue.locate(document, ["tool.poetry.dependencies"]).value or {}
+    for name, value in main_deps.items():
+        if name == "python":
+            continue
+        dep_path = f"tool.poetry.dependencies.{name}"
+        dep = parse_dependency(document, dep_path, name, value, group=None, project_path=project_path)
+        if dep:
+            dependencies.append(dep)
+
+    groups = TomlValue.locate(document, ["tool.poetry.group"]).value or {}
+    for group_name, group_data in groups.items():
+        for name, value in group_data.get("dependencies", {}).items():
+            dep_path = f"tool.poetry.group.{group_name}.dependencies.{name}"
+            dep = parse_dependency(document, dep_path, name, value, group=group_name, project_path=project_path)
+            if dep:
+                dependencies.append(dep)
+
+    return dependencies
+
+
+def parse_sources_from_document(document: TOMLDocument) -> list[ProjectFeedSource]:
+    sources_value = TomlValue.locate(document, ["tool.poetry.source"]).value
+    if not sources_value or not isinstance(sources_value, list):
+        return []
+
+    result = []
+    for entry in sources_value:
+        if not isinstance(entry, dict) or "name" not in entry:
+            continue
+        priority_raw = entry.get("priority")
+        priority = SourcePriority(priority_raw) if priority_raw in SourcePriority._value2member_map_ else None
+        result.append(ProjectFeedSource(
+            name=entry["name"],
+            url=entry.get("url"),
+            priority=priority,
+        ))
+    return result
+
+
+def parse_source_dirs_from_document(document: TOMLDocument, project_path: Path) -> list[Path]:
+    project_dir = project_path.parent
+    dirs: list[Path] = []
+    packages = TomlValue.locate(document, ["tool.poetry.packages"]).value or []
+    for entry in packages:
+        if not isinstance(entry, dict):
+            continue
+        include = entry.get("include")
+        if not include:
+            continue
+        base = project_dir / entry["from"] if entry.get("from") else project_dir
+        dirs.append((base / include).resolve())
+    return dirs or [project_dir]
+
+
+def parse_project(project_path: Path) -> Optional[Project]:
+    project_path = project_path.resolve()
+    if project_path.is_dir():
+        project_path = project_path / "pyproject.toml"
+
+    if not project_path.exists():
+        return None
+
+    with project_path.open('r', encoding='utf-8') as f:
+        data = parse(f.read())
+    return Project(
+        name=parse_name_from_document(data),
+        version=parse_version_from_document(data),
+        path=project_path,
+        document=data,
+        dependencies=parse_dependencies_from_document(data, project_path),
+        sources=parse_sources_from_document(data),
+        source_dirs=parse_source_dirs_from_document(data, project_path),
+        plugin_settings=parse_plugin_settings_from_document(data),
+    )

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/project/_projects_helper.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+from typing import Iterable, Optional
+
+from ._models import Project
+
+
+def filter_projects(inputs: list[str], projects: Iterable[Project]) -> list[Project]:
+    def _matches_reference(input: str, project_path: Path, project_name: Optional[str]) -> bool:
+        if input == project_name:
+            return True
+        try:
+            return Path(input).resolve().is_relative_to(project_path.parent)
+        except ValueError:
+            return False
+
+    unique_projects: dict[Path, Project] = {}
+    for project in projects:
+        unique_projects[project.path] = project
+
+    if not inputs:
+        selected_projects = unique_projects
+    else:
+        selected_projects = dict[Path, Project]()
+        sorted_projects = sorted(unique_projects.values(), key=lambda item: len(str(item.path)), reverse=True)
+        for ref in inputs:
+            for project in sorted_projects:
+                if _matches_reference(ref, project.path, project.name.value):
+                    selected_projects[project.path] = project
+                    break
+
+    return list(selected_projects.values())

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/settings/__init__.py

@@ -0,0 +1,7 @@
+from ._settings import PluginSettings
+from ._parsers import parse_plugin_settings_from_document
+
+__all__ = [
+    "PluginSettings",
+    "parse_plugin_settings_from_document",
+]

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/settings/_parsers.py

@@ -0,0 +1,15 @@
+from tomlkit import TOMLDocument
+
+from ..toml._toml_value import TomlValue
+from ._settings import PluginSettings
+
+
+def parse_plugin_settings_from_document(document: TOMLDocument) -> PluginSettings:
+    project_toml = document
+    settings_section = TomlValue.locate(project_toml, [f"tool.{PluginSettings.NAME}"]).value
+    if settings_section is None:
+        return PluginSettings(enabled=False)
+    result = PluginSettings.model_validate(settings_section, by_alias=True)
+    if result.enabled is None:
+        result.enabled = True
+    return result

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/settings/_settings.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+from typing import ClassVar, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PluginSettings(BaseModel):
+    NAME: ClassVar[str] = "ps-plugin"
+
+    enabled: Optional[bool] = Field(default=None, exclude=True)
+    host_project: Optional[Path] = Field(default=None, alias="host-project")
+    modules: Optional[list[str]] = Field(default=None, alias="modules")
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/toml/__init__.py

@@ -0,0 +1,5 @@
+from ._toml_value import TomlValue
+
+__all__ = [
+    "TomlValue",
+]

ps_plugin_sdk-0.2.8/src/ps/plugin/sdk/toml/_toml_value.py

@@ -0,0 +1,139 @@
+import re
+from typing import Any, List, Optional, Tuple
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field
+from tomlkit import TOMLDocument
+from tomlkit.items import AoT, Table
+
+
+Token = Tuple[str, Any]  # ("key", str) or ("index", int)
+
+
+def _split_dotted(dotted: str) -> List[str]:
+    return re.findall(r'"[^"]*"|[^.]+', dotted)
+
+
+def _parse_jsonpath(path: str) -> List[Token]:
+    if not path or path[0] != "$":
+        raise ValueError('JSONPath must start with "$"')
+
+    i, tokens = 1, []
+
+    while i < len(path):
+        if path[i] == ".":
+            i += 1
+            if i >= len(path):
+                raise ValueError(f"Unexpected end after '.' in JSONPath: {path!r}")
+            if path[i] == '"':
+                i += 1
+                start = i
+                while i < len(path) and path[i] != '"':
+                    i += 1
+                if i >= len(path):
+                    raise ValueError(f"Unterminated quoted key in JSONPath: {path!r}")
+                tokens.append(("key", path[start:i]))
+                i += 1
+            else:
+                if not (path[i].isalpha() or path[i] == "_"):
+                    raise ValueError(f"Invalid key start at position {i} in JSONPath: {path!r}")
+                start = i
+                while i < len(path) and (path[i].isalnum() or path[i] in "_-"):
+                    i += 1
+                tokens.append(("key", path[start:i]))
+        elif path[i] == "[":
+            i += 1
+            if i >= len(path) or not path[i].isdigit():
+                raise ValueError(f"Expected digit after '[' at position {i} in JSONPath: {path!r}")
+            start = i
+            while i < len(path) and path[i].isdigit():
+                i += 1
+            if i >= len(path) or path[i] != "]":
+                raise ValueError(f"Expected ']' after index at position {i} in JSONPath: {path!r}")
+            tokens.append(("index", int(path[start:i])))
+            i += 1
+        else:
+            raise ValueError(f"Unexpected character {path[i]!r} at position {i} in JSONPath: {path!r}")
+
+    return tokens
+
+
+def _get_by_jsonpath(document: Any, jsonpath: str) -> Any:
+    cur = document
+    for _, val in _parse_jsonpath(jsonpath):
+        cur = cur[val]
+    return cur
+
+
+def _set_by_jsonpath(document: Any, jsonpath: str, new_value: Any) -> None:
+    tokens = _parse_jsonpath(jsonpath)
+    if not tokens:
+        raise ValueError("Cannot set root '$'")
+
+    cur = document
+    for _, val in tokens[:-1]:
+        cur = cur[val]
+
+    cur[tokens[-1][1]] = new_value
+
+
+def _find_first_existing_jsonpath(document: Any, dotted: str) -> Optional[str]:
+    def rec(node: Any, parts: List[str], path: str) -> Optional[str]:
+        if not parts:
+            return path
+        head, *tail = parts
+        lookup_key = head[1:-1] if head.startswith('"') and head.endswith('"') else head
+        needs_quote = not all(c.isalnum() or c in "_-" for c in lookup_key)
+        jp_segment = f'."{lookup_key}"' if needs_quote else f".{lookup_key}"
+        if isinstance(node, (TOMLDocument, Table, dict)):
+            return rec(node[lookup_key], tail, f"{path}{jp_segment}") if lookup_key in node else None
+        if isinstance(node, (AoT, list)):
+            for i, item in enumerate(node):
+                if result := rec(item, parts, f"{path}[{i}]"):
+                    return result
+        return None
+
+    return rec(document, _split_dotted(dotted), "$")
+
+
+class TomlValue(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    document: TOMLDocument = Field(exclude=True)
+    jsonpath: Optional[str] = None
+
+    @property
+    def exists(self) -> bool:
+        if not self.jsonpath:
+            return False
+        try:
+            _get_by_jsonpath(self.document, self.jsonpath)
+            return True
+        except (KeyError, IndexError, Exception):
+            return False
+
+    @computed_field
+    @property
+    def value(self) -> Optional[Any]:
+        if not self.jsonpath:
+            return None
+        try:
+            return _get_by_jsonpath(self.document, self.jsonpath)
+        except (KeyError, IndexError, Exception):
+            return None
+
+    def set(self, new_value: Any) -> None:
+        if not self.jsonpath:
+            raise ValueError("Path not found")
+        _set_by_jsonpath(self.document, self.jsonpath, new_value)
+
+    @staticmethod
+    def locate(document: TOMLDocument, dotted_candidates: List[str]) -> 'TomlValue':
+        for dotted in dotted_candidates:
+            jp = _find_first_existing_jsonpath(document, dotted)
+            if jp:
+                return TomlValue(document=document, jsonpath=jp)
+        # If no existing path found, use first candidate as fallback
+        if dotted_candidates:
+            fallback_path = f"$.{dotted_candidates[0]}"
+            return TomlValue(document=document, jsonpath=fallback_path)
+        return TomlValue(document=document, jsonpath=None)