path-link 0.2.0__py3-none-any.whl

project_paths/__init__.py

@@ -0,0 +1,165 @@
+"""
+ptool-serena: Type-safe path configuration for Python projects
+
+A powerful library for managing project paths with built-in validation,
+static model generation, and comprehensive security features.
+
+Quick Start
+-----------
+    >>> from project_paths import ProjectPaths
+    >>>
+    >>> # Load paths from pyproject.toml
+    >>> paths = ProjectPaths.from_pyproject()
+    >>>
+    >>> # Access paths (all are pathlib.Path objects)
+    >>> config_dir = paths.config_dir
+    >>> settings = paths["settings_file"]
+
+Key Features
+------------
+- Dynamic path management from pyproject.toml or .paths files
+- Type-safe static model generation for IDE support
+- Built-in validators: StrictPathValidator, SandboxPathValidator
+- Path traversal attack prevention
+- CLI tool for validation and inspection
+- Offline-accessible documentation
+
+Documentation Access (Offline)
+-------------------------------
+Access comprehensive documentation programmatically, even in airgapped environments:
+
+    >>> from project_paths import get_ai_guidelines, get_developer_guide, get_metadata
+    >>> import json
+    >>>
+    >>> # Get AI assistant usage patterns and best practices
+    >>> ai_docs = get_ai_guidelines()
+    >>> print(f"AI Guidelines: {len(ai_docs):,} characters")
+    >>>
+    >>> # Get architecture and development guide
+    >>> dev_docs = get_developer_guide()
+    >>>
+    >>> # Get machine-readable metadata
+    >>> metadata = json.loads(get_metadata())
+    >>> print(f"Version: {metadata['version']}")
+    >>> print(f"Public APIs: {len(metadata['public_api'])}")
+
+Validation Example
+------------------
+    >>> from project_paths import validate_or_raise, StrictPathValidator
+    >>>
+    >>> paths = ProjectPaths.from_pyproject()
+    >>> validator = StrictPathValidator(
+    ...     required=["config_dir", "data_dir"],
+    ...     must_be_dir=["config_dir"],
+    ...     allow_symlinks=False  # Security: block symlinks
+    ... )
+    >>> validate_or_raise(paths, validator)
+
+CLI Commands
+------------
+    $ ptool print                    # Show all configured paths
+    $ ptool validate --strict        # Validate project structure
+    $ ptool gen-static               # Generate static model
+    $ ptool --help                   # Full CLI reference
+
+Critical Rules
+--------------
+- NEVER instantiate ProjectPaths() directly (raises NotImplementedError)
+- ALWAYS use factory methods: from_pyproject() or from_config()
+- Regenerate static model after pyproject.toml changes
+- Use validators before filesystem operations
+
+See Also
+--------
+- Full documentation: README.md in package root
+- AI guidelines: get_ai_guidelines()
+- Developer guide: get_developer_guide()
+- Package metadata: get_metadata()
+- GitHub: https://github.com/yourusername/ptool-serena
+"""
+
+from importlib.resources import files
+
+from .model import ProjectPaths
+from .get_paths import write_dataclass_file
+from .validation import (
+    Severity,
+    Finding,
+    ValidationResult,
+    PathValidator,
+    PathValidationError,
+    validate_or_raise,
+    CompositeValidator,
+)
+from .builtin_validators.strict import StrictPathValidator
+from .builtin_validators.sandbox import SandboxPathValidator
+
+
+def get_ai_guidelines() -> str:
+    """
+    Return AI assistant guidelines for working with this package.
+
+    This provides comprehensive guidance for AI agents helping users with ptool-serena,
+    including usage patterns, critical rules, validation patterns, and troubleshooting.
+
+    Returns:
+        str: Full content of AI guidelines (formerly assistant_context.md)
+
+    Example:
+        >>> guidelines = get_ai_guidelines()
+        >>> print(guidelines[:100])
+    """
+    return files("project_paths.docs").joinpath("ai_guidelines.md").read_text()
+
+
+def get_developer_guide() -> str:
+    """
+    Return developer guide for contributing to this package.
+
+    This provides architecture details, development setup, testing patterns,
+    and contribution guidelines for developers working on ptool-serena.
+
+    Returns:
+        str: Full content of developer guide (formerly CLAUDE.md)
+
+    Example:
+        >>> guide = get_developer_guide()
+        >>> print(guide[:100])
+    """
+    return files("project_paths.docs").joinpath("developer_guide.md").read_text()
+
+
+def get_metadata() -> str:
+    """
+    Return machine-readable project metadata.
+
+    This provides structured information about the package including version,
+    public API, validators, CLI commands, and architecture notes.
+
+    Returns:
+        str: JSON content of project metadata (formerly assistant_handoff.json)
+
+    Example:
+        >>> import json
+        >>> metadata = json.loads(get_metadata())
+        >>> print(metadata['version'])
+    """
+    return files("project_paths.docs").joinpath("metadata.json").read_text()
+
+
+__all__ = [
+    "ProjectPaths",
+    "write_dataclass_file",
+    "Severity",
+    "Finding",
+    "ValidationResult",
+    "PathValidator",
+    "PathValidationError",
+    "validate_or_raise",
+    "CompositeValidator",
+    "StrictPathValidator",
+    "SandboxPathValidator",
+    "get_ai_guidelines",
+    "get_developer_guide",
+    "get_metadata",
+]

project_paths/builder.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+import os
+from pathlib import Path
+from tomllib import load as toml_load
+from typing import Callable, Dict, Any, Optional
+
+from dotenv import dotenv_values
+from pydantic import Field
+
+
+def get_paths_from_pyproject() -> Dict[str, str]:
+    """Load path variables from pyproject.toml."""
+    pyproject_path = Path.cwd() / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return {}
+
+    with pyproject_path.open("rb") as f:
+        pyproject_data = toml_load(f)
+
+    tool_config = pyproject_data.get("tool", {}).get("project_paths", {})
+    if not tool_config:
+        return {}
+
+    paths = tool_config.get("paths", {})
+    files = tool_config.get("files", {})
+
+    if not isinstance(paths, dict) or not isinstance(files, dict):
+        raise TypeError("`paths` and `files` must be tables in pyproject.toml")
+
+    return {**paths, **files}
+
+
+def get_paths_from_dot_paths(path_to_config: Path) -> Dict[str, str]:
+    """Load path variables from a .paths file."""
+    if not path_to_config.is_file():
+        raise FileNotFoundError(f"Configuration file not found: {path_to_config}")
+
+    values = dotenv_values(path_to_config)
+
+    # Filter out None values which can occur with empty lines
+    return {k: v for k, v in values.items() if v is not None}
+
+
+def make_path_factory(base: Path, rel_path: str):
+    """Creates a lambda function to resolve a path relative to a base."""
+    # Expand environment variables and user home directory
+    expanded_path = os.path.expandvars(os.path.expanduser(rel_path))
+    return lambda: base / expanded_path
+
+
+def build_field_definitions(
+    loader_func: Callable[..., Dict[str, str]] = get_paths_from_pyproject,
+    config_path: Optional[Path] = None,
+) -> dict[str, tuple[type[Path], Any]]:
+    """
+    Builds a dictionary of Pydantic field definitions from a configuration source.
+
+    Args:
+        loader_func: The function used to load the raw path strings.
+        config_path: The optional path to the configuration file.
+
+    Returns:
+        A dictionary of field definitions for the dynamic Pydantic model.
+    """
+    if config_path:
+        env_values = loader_func(config_path)
+        base_dir = config_path.parent.resolve()
+    else:
+        env_values = loader_func()
+        base_dir = Path.cwd()
+
+    fields = {
+        "root": (Path, Field(default_factory=Path.home)),
+        "base_dir": (Path, Field(default_factory=lambda: base_dir)),
+    }
+
+    for key, val in env_values.items():
+        if key not in fields:
+            fields[key] = (
+                Path,
+                Field(default_factory=make_path_factory(base_dir, val)),
+            )
+
+    return fields

project_paths/builtin_validators/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in validators for common validation scenarios."""
+
+from .strict import StrictPathValidator
+from .sandbox import SandboxPathValidator
+
+__all__ = ["StrictPathValidator", "SandboxPathValidator"]

project_paths/builtin_validators/sandbox.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, TYPE_CHECKING
+
+from ..validation import Finding, Severity, ValidationResult
+
+if TYPE_CHECKING:
+    from ..model import _ProjectPathsBase
+
+
+@dataclass
+class SandboxPathValidator:
+    """
+    Validates that paths stay within a base directory sandbox.
+
+    This is a security-focused validator that prevents path traversal attacks
+    and ensures all paths remain within the project's base directory.
+
+    Features:
+    - Detects '..' path escape attempts
+    - Validates paths stay within base_dir
+    - Optionally allows absolute paths (with validation)
+    - Configurable strict mode for maximum security
+    """
+
+    base_dir_key: str = "base_dir"
+    """The key in ProjectPaths that represents the base directory."""
+
+    check_paths: Iterable[str] = ()
+    """Specific path keys to check. If empty, checks all paths."""
+
+    allow_absolute: bool = False
+    """Allow absolute paths that are within base_dir."""
+
+    strict_mode: bool = True
+    """In strict mode, block all attempts at path traversal, even if they resolve safely."""
+
+    def validate(self, p: "_ProjectPathsBase") -> ValidationResult:
+        """
+        Validates that all paths stay within the base directory sandbox.
+
+        Args:
+            p: The ProjectPaths instance to validate.
+
+        Returns:
+            A ValidationResult containing all findings.
+        """
+        vr = ValidationResult()
+        all_paths = p.to_dict()
+
+        # Get base directory
+        if self.base_dir_key not in all_paths:
+            vr.add(
+                Finding(
+                    severity=Severity.ERROR,
+                    code="SANDBOX_BASE_MISSING",
+                    field=self.base_dir_key,
+                    message=f"Sandbox base directory key '{self.base_dir_key}' not found in ProjectPaths.",
+                )
+            )
+            return vr
+
+        base_dir = Path(all_paths[self.base_dir_key])
+
+        # Resolve base_dir to handle symlinks and get absolute path
+        try:
+            base_dir_resolved = base_dir.resolve()
+        except (OSError, RuntimeError) as e:
+            vr.add(
+                Finding(
+                    severity=Severity.ERROR,
+                    code="SANDBOX_BASE_UNRESOLVABLE",
+                    field=self.base_dir_key,
+                    path=str(base_dir),
+                    message=f"Cannot resolve base directory: {e}",
+                )
+            )
+            return vr
+
+        # Determine which paths to check
+        if self.check_paths:
+            keys_to_check = set(self.check_paths)
+        else:
+            # Check all paths except base_dir itself
+            keys_to_check = set(all_paths.keys()) - {self.base_dir_key}
+
+        for key in sorted(keys_to_check):
+            if key not in all_paths:
+                continue  # Skip missing keys - that's StrictPathValidator's job
+
+            path = Path(all_paths[key])
+            path_str = str(path)
+
+            # Check 1: Detect suspicious '..' patterns in strict mode
+            if self.strict_mode:
+                parts = path.parts
+                if ".." in parts:
+                    vr.add(
+                        Finding(
+                            severity=Severity.ERROR,
+                            code="PATH_TRAVERSAL_ATTEMPT",
+                            field=key,
+                            path=path_str,
+                            message="Path contains '..' traversal pattern (blocked in strict mode)",
+                        )
+                    )
+                    continue  # Don't proceed with further checks for this path
+
+            # Check 2: Validate absolute paths if not allowed
+            if path.is_absolute() and not self.allow_absolute:
+                vr.add(
+                    Finding(
+                        severity=Severity.ERROR,
+                        code="ABSOLUTE_PATH_BLOCKED",
+                        field=key,
+                        path=path_str,
+                        message="Absolute paths not allowed (set allow_absolute=True to permit)",
+                    )
+                )
+                continue
+
+            # Check 3: Resolve path and verify it's within base_dir
+            try:
+                # For relative paths, resolve relative to base_dir
+                if not path.is_absolute():
+                    full_path = base_dir / path
+                else:
+                    full_path = path
+
+                path_resolved = full_path.resolve()
+            except (OSError, RuntimeError) as e:
+                vr.add(
+                    Finding(
+                        severity=Severity.WARNING,
+                        code="PATH_UNRESOLVABLE",
+                        field=key,
+                        path=path_str,
+                        message=f"Cannot resolve path: {e}",
+                    )
+                )
+                continue
+
+            # Check if resolved path is within base_dir
+            try:
+                # relative_to() raises ValueError if path is not relative to base
+                path_resolved.relative_to(base_dir_resolved)
+            except ValueError:
+                vr.add(
+                    Finding(
+                        severity=Severity.ERROR,
+                        code="PATH_ESCAPES_SANDBOX",
+                        field=key,
+                        path=path_str,
+                        message=f"Path escapes sandbox (resolves outside {base_dir_resolved})",
+                    )
+                )
+
+        return vr

project_paths/builtin_validators/strict.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, TYPE_CHECKING
+
+from ..validation import Finding, Severity, ValidationResult
+
+if TYPE_CHECKING:
+    from ..model import _ProjectPathsBase
+
+
+@dataclass
+class StrictPathValidator:
+    """
+    Validates path existence, type (file/directory), and symlinks based on configured rules.
+    """
+
+    required: Iterable[str]
+    must_be_dir: Iterable[str] = ()
+    must_be_file: Iterable[str] = ()
+    allow_symlinks: bool = False
+
+    def validate(self, p: "_ProjectPathsBase") -> ValidationResult:
+        """
+        Validates paths against the configured rules.
+
+        Args:
+            p: The ProjectPaths instance to validate.
+
+        Returns:
+            A ValidationResult containing all findings.
+        """
+        vr = ValidationResult()
+        all_paths = p.to_dict()
+
+        req_set = set(self.required)
+        dir_set = set(self.must_be_dir)
+        file_set = set(self.must_be_file)
+
+        # Configuration conflict guard
+        conflict = dir_set & file_set
+        if conflict:
+            for k in sorted(conflict):
+                vr.add(
+                    Finding(
+                        severity=Severity.ERROR,
+                        code="CONFLICTING_KIND_RULES",
+                        field=k,
+                        message="Field listed as both must_be_dir and must_be_file",
+                    )
+                )
+            return vr
+
+        keys_to_check = req_set | dir_set | file_set
+
+        for k in keys_to_check:
+            if k not in all_paths:
+                is_required = k in req_set
+                vr.add(
+                    Finding(
+                        severity=Severity.ERROR if is_required else Severity.WARNING,
+                        code="KEY_NOT_FOUND",
+                        field=k,
+                        message=f"Path key '{k}' not found in ProjectPaths model.",
+                    )
+                )
+                continue
+
+            path = Path(all_paths[k])
+
+            if not self.allow_symlinks and path.is_symlink():
+                vr.add(
+                    Finding(
+                        severity=Severity.ERROR,
+                        code="SYMLINK_BLOCKED",
+                        field=k,
+                        path=str(path),
+                        message="Symlinks not permitted",
+                    )
+                )
+
+            exists = path.exists()
+
+            if k in req_set and not exists:
+                vr.add(
+                    Finding(
+                        severity=Severity.ERROR,
+                        code="MISSING_REQUIRED",
+                        field=k,
+                        path=str(path),
+                        message="Required path missing",
+                    )
+                )
+            elif not exists and k in (dir_set | file_set):
+                vr.add(
+                    Finding(
+                        severity=Severity.WARNING,
+                        code="MISSING_OPTIONAL",
+                        field=k,
+                        path=str(path),
+                        message="Optional path missing",
+                    )
+                )
+
+            if exists:
+                if k in dir_set and not path.is_dir():
+                    vr.add(
+                        Finding(
+                            severity=Severity.ERROR,
+                            code="NOT_A_DIRECTORY",
+                            field=k,
+                            path=str(path),
+                            message="Expected directory",
+                        )
+                    )
+                if k in file_set and not path.is_file():
+                    vr.add(
+                        Finding(
+                            severity=Severity.ERROR,
+                            code="NOT_A_FILE",
+                            field=k,
+                            path=str(path),
+                            message="Expected file",
+                        )
+                    )
+        return vr