patchshuttle 0.1.0a2__py3-none-any.whl

patchshuttle/policy.py

@@ -0,0 +1,377 @@
+"""Workspace-relative path normalization and immutable local policy."""
+
+from __future__ import annotations
+
+import fnmatch
+import ntpath
+import os
+import re
+import stat
+from dataclasses import dataclass, field
+from enum import Enum
+from functools import lru_cache
+from os import PathLike
+from pathlib import Path, PurePosixPath
+
+from patchshuttle.errors import PolicyError, PolicyErrorCode
+from patchshuttle.workspace import Workspace
+
+_URL_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
+
+class PathKind(str, Enum):
+    """Observable filesystem kind returned by a successful policy check."""
+
+    MISSING = "missing"
+    FILE = "file"
+    DIRECTORY = "directory"
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspacePath:
+    """One canonical workspace path and its inspected filesystem kind."""
+
+    relative: PurePosixPath
+    absolute: Path
+    kind: PathKind
+
+    @property
+    def exists(self) -> bool:
+        return self.kind is not PathKind.MISSING
+
+
+@dataclass(frozen=True, slots=True)
+class _GlobPattern:
+    source: str
+    segments: tuple[str, ...]
+
+    def matches(self, path: PurePosixPath, *, case_sensitive: bool) -> bool:
+        patterns = self.segments
+        values = path.parts
+        if not case_sensitive:
+            patterns = tuple(part.casefold() for part in patterns)
+            values = tuple(part.casefold() for part in values)
+
+        @lru_cache(maxsize=None)
+        def match(pattern_index: int, value_index: int) -> bool:
+            if pattern_index == len(patterns):
+                return value_index == len(values)
+
+            pattern = patterns[pattern_index]
+            if pattern == "**":
+                return match(pattern_index + 1, value_index) or (
+                    value_index < len(values) and match(pattern_index, value_index + 1)
+                )
+
+            return (
+                value_index < len(values)
+                and fnmatch.fnmatchcase(values[value_index], pattern)
+                and match(pattern_index + 1, value_index + 1)
+            )
+
+        return match(0, 0)
+
+
+def _platform_case_sensitive() -> bool:
+    return os.path.normcase("A") != os.path.normcase("a")
+
+
+@dataclass(frozen=True, slots=True)
+class Policy:
+    """Immutable workspace path policy derived from local configuration."""
+
+    workspace: Workspace
+    case_sensitive: bool = field(default_factory=_platform_case_sensitive)
+    _protected_patterns: tuple[_GlobPattern, ...] = field(init=False, repr=False)
+    _exception_patterns: tuple[_GlobPattern, ...] = field(init=False, repr=False)
+    _ignored_patterns: tuple[_GlobPattern, ...] = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        project = self.workspace.config.project
+        object.__setattr__(
+            self,
+            "_protected_patterns",
+            _compile_patterns(project.protected_paths),
+        )
+        object.__setattr__(
+            self,
+            "_exception_patterns",
+            _compile_patterns(project.protected_path_exceptions),
+        )
+        object.__setattr__(
+            self,
+            "_ignored_patterns",
+            _compile_patterns(project.ignored_paths),
+        )
+
+    @property
+    def root(self) -> Path:
+        return self.workspace.root
+
+    def normalize(self, value: str | PathLike[str]) -> PurePosixPath:
+        """Return a canonical relative path without touching the filesystem."""
+
+        return _normalize_path(value)
+
+    def is_protected(self, value: str | PathLike[str]) -> bool:
+        """Report whether a canonical path is blocked from AI job access."""
+
+        relative = self.normalize(value)
+        return self._is_protected(relative)
+
+    def is_ignored(self, value: str | PathLike[str]) -> bool:
+        """Report whether inventory and audit traversal should skip a path."""
+
+        relative = self.normalize(value)
+        return any(
+            pattern.matches(prefix, case_sensitive=self.case_sensitive)
+            for prefix in _path_prefixes(relative)
+            for pattern in self._ignored_patterns
+        )
+
+    def resolve(
+        self,
+        value: str | PathLike[str],
+        *,
+        allow_root: bool = False,
+        allow_missing: bool = False,
+    ) -> WorkspacePath:
+        """Validate, inspect, and resolve one path without changing anything."""
+
+        relative = self.normalize(value)
+        display_path = relative.as_posix()
+        if not relative.parts:
+            if not allow_root:
+                raise PolicyError(
+                    PolicyErrorCode.PATH_ROOT_FORBIDDEN,
+                    "workspace root requires explicit read-only permission",
+                    path=display_path,
+                )
+            return WorkspacePath(
+                relative=relative,
+                absolute=self.root,
+                kind=PathKind.DIRECTORY,
+            )
+
+        if self._is_protected(relative):
+            raise PolicyError(
+                PolicyErrorCode.PATH_PROTECTED,
+                "path is protected by local policy",
+                path=display_path,
+            )
+
+        candidate = self.root.joinpath(*relative.parts)
+        kind = self._inspect(relative)
+        resolved = self._resolve_candidate(candidate, display_path)
+        if not _is_within_root(
+            self.root,
+            resolved,
+            case_sensitive=self.case_sensitive,
+        ):
+            raise PolicyError(
+                PolicyErrorCode.PATH_OUTSIDE_WORKSPACE,
+                "resolved path escapes the workspace root",
+                path=display_path,
+            )
+        if not _paths_equal(
+            candidate,
+            resolved,
+            case_sensitive=self.case_sensitive,
+        ):
+            raise PolicyError(
+                PolicyErrorCode.PATH_SYMLINK,
+                "path changed or resolved through a symbolic link",
+                path=display_path,
+            )
+
+        if kind is PathKind.MISSING and not allow_missing:
+            raise PolicyError(
+                PolicyErrorCode.PATH_NOT_FOUND,
+                "path does not exist",
+                path=display_path,
+            )
+
+        return WorkspacePath(relative=relative, absolute=resolved, kind=kind)
+
+    def _is_protected(self, relative: PurePosixPath) -> bool:
+        if not relative.parts:
+            return True
+
+        first = relative.parts[0]
+        patches_name = "patches" if self.case_sensitive else "patches".casefold()
+        compared_first = first if self.case_sensitive else first.casefold()
+        if compared_first == patches_name:
+            return True
+
+        if any(
+            pattern.matches(relative, case_sensitive=self.case_sensitive)
+            for pattern in self._exception_patterns
+        ):
+            return False
+        return any(
+            pattern.matches(prefix, case_sensitive=self.case_sensitive)
+            for prefix in _path_prefixes(relative)
+            for pattern in self._protected_patterns
+        )
+
+    def _inspect(self, relative: PurePosixPath) -> PathKind:
+        current = self.root
+        for index, part in enumerate(relative.parts):
+            current = current / part
+            current_relative = PurePosixPath(*relative.parts[: index + 1]).as_posix()
+            try:
+                mode = current.lstat().st_mode
+            except FileNotFoundError:
+                return PathKind.MISSING
+            except NotADirectoryError as exc:
+                raise PolicyError(
+                    PolicyErrorCode.PATH_PARENT_NOT_DIRECTORY,
+                    "an existing parent is not a directory",
+                    path=PurePosixPath(*relative.parts[:index]).as_posix(),
+                ) from exc
+            except OSError as exc:
+                raise PolicyError(
+                    PolicyErrorCode.PATH_INSPECTION_FAILED,
+                    "path metadata could not be read",
+                    path=current_relative,
+                ) from exc
+
+            if stat.S_ISLNK(mode):
+                raise PolicyError(
+                    PolicyErrorCode.PATH_SYMLINK,
+                    "symbolic-link targets and parents are not allowed",
+                    path=current_relative,
+                )
+
+            is_target = index == len(relative.parts) - 1
+            if not is_target:
+                if not stat.S_ISDIR(mode):
+                    raise PolicyError(
+                        PolicyErrorCode.PATH_PARENT_NOT_DIRECTORY,
+                        "an existing parent is not a directory",
+                        path=current_relative,
+                    )
+                continue
+
+            if stat.S_ISREG(mode):
+                return PathKind.FILE
+            if stat.S_ISDIR(mode):
+                return PathKind.DIRECTORY
+            raise PolicyError(
+                PolicyErrorCode.PATH_SPECIAL_FILE,
+                "device files, sockets, and named pipes are not allowed",
+                path=current_relative,
+            )
+
+        return PathKind.MISSING  # pragma: no cover - root handled by resolve
+
+    @staticmethod
+    def _resolve_candidate(candidate: Path, display_path: str) -> Path:
+        try:
+            return candidate.resolve(strict=False)
+        except (OSError, RuntimeError) as exc:
+            raise PolicyError(
+                PolicyErrorCode.PATH_INSPECTION_FAILED,
+                "path could not be resolved",
+                path=display_path,
+            ) from exc
+
+
+def _normalize_path(value: str | PathLike[str]) -> PurePosixPath:
+    try:
+        raw = os.fspath(value)
+    except TypeError as exc:
+        raise PolicyError(
+            PolicyErrorCode.PATH_INVALID,
+            "path must be text or a text path-like value",
+        ) from exc
+
+    if not isinstance(raw, str) or not raw or "\0" in raw:
+        raise PolicyError(
+            PolicyErrorCode.PATH_INVALID,
+            "path must be non-empty text without null bytes",
+        )
+
+    drive, _ = ntpath.splitdrive(raw)
+    if drive or raw.startswith(("/", "\\")):
+        raise PolicyError(
+            PolicyErrorCode.PATH_ABSOLUTE,
+            "absolute and drive-qualified paths are not allowed",
+            path=raw,
+        )
+    if _URL_SCHEME.match(raw):
+        raise PolicyError(
+            PolicyErrorCode.PATH_URL,
+            "URL-like paths are not allowed",
+            path=raw,
+        )
+
+    parts: list[str] = []
+    for part in raw.replace("\\", "/").split("/"):
+        if part == "..":
+            raise PolicyError(
+                PolicyErrorCode.PATH_TRAVERSAL,
+                "parent traversal is not allowed",
+                path=raw,
+            )
+        if part not in ("", "."):
+            parts.append(part)
+    return PurePosixPath(*parts) if parts else PurePosixPath(".")
+
+
+def _compile_patterns(patterns: tuple[str, ...]) -> tuple[_GlobPattern, ...]:
+    compiled: list[_GlobPattern] = []
+    for pattern in patterns:
+        try:
+            normalized = _normalize_path(pattern)
+        except PolicyError as exc:
+            raise PolicyError(
+                PolicyErrorCode.POLICY_PATTERN_INVALID,
+                "local policy pattern must be a relative workspace glob",
+                path=pattern,
+            ) from exc
+        compiled.append(_GlobPattern(source=pattern, segments=tuple(normalized.parts)))
+    return tuple(compiled)
+
+
+def _path_prefixes(path: PurePosixPath) -> tuple[PurePosixPath, ...]:
+    if not path.parts:
+        return (path,)
+    return tuple(
+        PurePosixPath(*path.parts[:index]) for index in range(1, len(path.parts) + 1)
+    )
+
+
+def _is_within_root(
+    root: Path,
+    candidate: Path,
+    *,
+    case_sensitive: bool,
+) -> bool:
+    root_text = str(root)
+    candidate_text = str(candidate)
+    if not case_sensitive:
+        root_text = root_text.casefold()
+        candidate_text = candidate_text.casefold()
+    try:
+        common = os.path.commonpath((root_text, candidate_text))
+    except ValueError:
+        return False
+    return common == root_text
+
+
+def _paths_equal(
+    left: Path,
+    right: Path,
+    *,
+    case_sensitive: bool,
+) -> bool:
+    left_text = os.path.normpath(str(left))
+    right_text = os.path.normpath(str(right))
+    if not case_sensitive:
+        left_text = left_text.casefold()
+        right_text = right_text.casefold()
+    return left_text == right_text
+
+
+__all__ = ["PathKind", "Policy", "WorkspacePath"]

patchshuttle/py.typed

@@ -0,0 +1 @@
+

patchshuttle/registry.py

@@ -0,0 +1,275 @@
+"""Atomic project-local job identity and lifecycle registry."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from patchshuttle.errors import ExecutionError, ExecutionErrorCode
+from patchshuttle.models import JobKind
+from patchshuttle.workspace import Workspace
+
+_REGISTRY_RELATIVE_PATH = Path("patches/state/registry.json")
+_MAX_REGISTRY_BYTES = 5_000_000
+
+
+class RegistryDecision(str, Enum):
+    """Identity decision made before an execution attempt."""
+
+    PROCEED = "PROCEED"
+    ALREADY_APPLIED = "ALREADY_APPLIED"
+    PATCH_ID_CONFLICT = "PATCH_ID_CONFLICT"
+
+
+@dataclass(frozen=True, slots=True)
+class RegistryJobRecord:
+    """Validated latest project-local state for one stable job ID."""
+
+    job_id: str
+    job_hash: str
+    kind: str
+    first_run_at: str
+    latest_run_at: str
+    latest_result: str
+    backup_reference: str | None
+    rollback_state: str
+    archived_job_copy: str
+    completed: bool
+    run_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class Registry:
+    """Immutable validated view of ``patches/state/registry.json``."""
+
+    project_id: str
+    jobs: dict[str, RegistryJobRecord]
+
+
+def load_registry(workspace: Workspace) -> Registry:
+    """Read and validate an atomically published registry snapshot."""
+
+    path = workspace.root / _REGISTRY_RELATIVE_PATH
+    try:
+        metadata = path.lstat()
+        if not stat.S_ISREG(metadata.st_mode) or metadata.st_size > _MAX_REGISTRY_BYTES:
+            raise OSError("registry is not a bounded regular file")
+        raw = path.read_bytes()
+    except OSError as exc:
+        raise _registry_error("workspace registry could not be read") from exc
+
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+        registry = _parse_registry(payload)
+    except (UnicodeDecodeError, json.JSONDecodeError, TypeError, ValueError) as exc:
+        raise _registry_error("workspace registry is invalid") from exc
+
+    if registry.project_id != workspace.project_id:
+        raise _registry_error("workspace registry project ID does not match config")
+    return registry
+
+
+def decide_job(
+    registry: Registry,
+    *,
+    job_id: str,
+    job_hash: str,
+) -> RegistryDecision:
+    """Apply the protocol's stable-ID and normalized-hash rules."""
+
+    existing = registry.jobs.get(job_id)
+    if existing is None:
+        return RegistryDecision.PROCEED
+    if existing.job_hash != job_hash:
+        return RegistryDecision.PATCH_ID_CONFLICT
+    if existing.completed:
+        return RegistryDecision.ALREADY_APPLIED
+    return RegistryDecision.PROCEED
+
+
+def update_registry(
+    workspace: Workspace,
+    registry: Registry,
+    *,
+    job_id: str,
+    job_hash: str,
+    kind: JobKind,
+    occurred_at: str,
+    result: str,
+    backup_path: Path | None,
+    rollback_state: str,
+    archived_job_path: Path,
+    completed: bool,
+    reset_completed: bool = False,
+) -> RegistryJobRecord:
+    """Atomically retain the latest run state while preserving job identity.
+
+    The caller must hold ``patches/state/run.lock`` across its decision and
+    this write.
+    """
+
+    existing = registry.jobs.get(job_id)
+    established_hash = existing.job_hash if existing is not None else job_hash
+    established_kind = existing.kind if existing is not None else kind.value
+    record = RegistryJobRecord(
+        job_id=job_id,
+        job_hash=established_hash,
+        kind=established_kind,
+        first_run_at=(existing.first_run_at if existing is not None else occurred_at),
+        latest_run_at=occurred_at,
+        latest_result=result,
+        backup_reference=(
+            _relative_path(workspace, backup_path)
+            if backup_path is not None
+            else (existing.backup_reference if existing is not None else None)
+        ),
+        rollback_state=rollback_state,
+        archived_job_copy=_relative_path(workspace, archived_job_path),
+        completed=(
+            completed
+            if reset_completed
+            else completed or (existing.completed if existing is not None else False)
+        ),
+        run_count=(existing.run_count + 1 if existing is not None else 1),
+    )
+    jobs = dict(registry.jobs)
+    jobs[job_id] = record
+    _write_registry(
+        workspace,
+        Registry(project_id=registry.project_id, jobs=jobs),
+    )
+    return record
+
+
+def get_job(registry: Registry, job_id: str) -> RegistryJobRecord:
+    """Return one job or raise a stable read-command error."""
+
+    try:
+        return registry.jobs[job_id]
+    except KeyError as exc:
+        raise ExecutionError(
+            ExecutionErrorCode.JOB_NOT_FOUND,
+            "job ID is not present in the workspace registry",
+            item_id=job_id,
+        ) from exc
+
+
+def _parse_registry(payload: Any) -> Registry:
+    if not isinstance(payload, dict):
+        raise TypeError("registry root must be an object")
+    project_id = payload.get("project_id")
+    raw_jobs = payload.get("jobs")
+    if not isinstance(project_id, str) or not isinstance(raw_jobs, dict):
+        raise TypeError("registry project_id and jobs are required")
+    jobs: dict[str, RegistryJobRecord] = {}
+    for job_id, value in raw_jobs.items():
+        if not isinstance(job_id, str) or not isinstance(value, dict):
+            raise TypeError("registry jobs must be keyed objects")
+        record = RegistryJobRecord(
+            job_id=_required(value, "job_id", str),
+            job_hash=_required(value, "job_hash", str),
+            kind=_required(value, "kind", str),
+            first_run_at=_required(value, "first_run_at", str),
+            latest_run_at=_required(value, "latest_run_at", str),
+            latest_result=_required(value, "latest_result", str),
+            backup_reference=_optional_string(value, "backup_reference"),
+            rollback_state=_required(value, "rollback_state", str),
+            archived_job_copy=_required(value, "archived_job_copy", str),
+            completed=_required(value, "completed", bool),
+            run_count=_required(value, "run_count", int),
+        )
+        if record.job_id != job_id or record.run_count < 1:
+            raise ValueError("registry job identity or run count is invalid")
+        jobs[job_id] = record
+    return Registry(project_id=project_id, jobs=jobs)
+
+
+def _required(value: dict[str, Any], key: str, expected: type):
+    item = value.get(key)
+    if type(item) is not expected:
+        raise TypeError(f"registry field {key} has an invalid type")
+    return item
+
+
+def _optional_string(value: dict[str, Any], key: str) -> str | None:
+    item = value.get(key)
+    if item is not None and not isinstance(item, str):
+        raise TypeError(f"registry field {key} has an invalid type")
+    return item
+
+
+def _write_registry(workspace: Workspace, registry: Registry) -> None:
+    path = workspace.root / _REGISTRY_RELATIVE_PATH
+    temporary = path.parent / f".registry-{uuid.uuid4().hex}.tmp"
+    payload = {
+        "jobs": {
+            job_id: _record_payload(record)
+            for job_id, record in sorted(registry.jobs.items())
+        },
+        "project_id": registry.project_id,
+    }
+    raw = (
+        json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    ).encode("utf-8")
+    try:
+        descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(raw)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    except OSError as exc:
+        raise _registry_error("workspace registry could not be written") from exc
+    finally:
+        try:
+            temporary.unlink()
+        except OSError:
+            pass
+
+
+def _record_payload(record: RegistryJobRecord) -> dict[str, object]:
+    return {
+        "archived_job_copy": record.archived_job_copy,
+        "backup_reference": record.backup_reference,
+        "completed": record.completed,
+        "first_run_at": record.first_run_at,
+        "job_hash": record.job_hash,
+        "job_id": record.job_id,
+        "kind": record.kind,
+        "latest_result": record.latest_result,
+        "latest_run_at": record.latest_run_at,
+        "rollback_state": record.rollback_state,
+        "run_count": record.run_count,
+    }
+
+
+def _relative_path(workspace: Workspace, path: Path) -> str:
+    try:
+        return path.relative_to(workspace.root).as_posix()
+    except ValueError as exc:  # pragma: no cover - internal path invariant
+        raise _registry_error("operational path is outside the workspace") from exc
+
+
+def _registry_error(message: str) -> ExecutionError:
+    return ExecutionError(
+        ExecutionErrorCode.OPERATIONAL_RECORD_FAILED,
+        message,
+        path=_REGISTRY_RELATIVE_PATH.as_posix(),
+    )
+
+
+__all__ = [
+    "Registry",
+    "RegistryDecision",
+    "RegistryJobRecord",
+    "decide_job",
+    "get_job",
+    "load_registry",
+    "update_registry",
+]