patchshuttle 0.1.0a2__py3-none-any.whl

patchshuttle/actions/constructors.py

@@ -0,0 +1,211 @@
+"""Declarative public action constructors."""
+
+from __future__ import annotations
+
+from patchshuttle.models import Action
+
+
+def tree(
+    path: str = ".",
+    *,
+    depth: int = 4,
+    max_entries: int = 500,
+    include_hidden: bool = False,
+) -> Action:
+    return Action(
+        {
+            "tree": {
+                "path": path,
+                "depth": depth,
+                "max_entries": max_entries,
+                "include_hidden": include_hidden,
+            }
+        }
+    )
+
+
+def read(
+    path: str,
+    *,
+    start_line: int = 1,
+    end_line: int | None = None,
+    max_bytes: int | None = None,
+) -> Action:
+    parameters = {"path": path, "start_line": start_line}
+    if end_line is not None:
+        parameters["end_line"] = end_line
+    if max_bytes is not None:
+        parameters["max_bytes"] = max_bytes
+    return Action({"read": parameters})
+
+
+def search(
+    text: str,
+    *,
+    path: str = ".",
+    glob: str | None = None,
+    case_sensitive: bool = True,
+    max_results: int = 200,
+) -> Action:
+    parameters = {
+        "path": path,
+        "text": text,
+        "case_sensitive": case_sensitive,
+        "max_results": max_results,
+    }
+    if glob is not None:
+        parameters["glob"] = glob
+    return Action({"search": parameters})
+
+
+def find_files(
+    glob: str,
+    *,
+    path: str = ".",
+    max_results: int = 500,
+) -> Action:
+    return Action(
+        {
+            "find_files": {
+                "path": path,
+                "glob": glob,
+                "max_results": max_results,
+            }
+        }
+    )
+
+
+def file_info(path: str) -> Action:
+    return Action({"file_info": {"path": path}})
+
+
+def hash(path: str, *, algorithm: str = "sha256") -> Action:
+    return Action({"hash": {"path": path, "algorithm": algorithm}})
+
+
+def git_status() -> Action:
+    return Action({"git_status": {}})
+
+
+def environment() -> Action:
+    return Action({"environment": {}})
+
+
+def create_directory(path: str) -> Action:
+    return Action({"create_directory": {"path": path}})
+
+
+def create_file(
+    path: str,
+    content: str,
+    *,
+    encoding: str = "utf-8",
+    newline: str = "lf",
+) -> Action:
+    return Action(
+        {
+            "create_file": {
+                "path": path,
+                "content": content,
+                "encoding": encoding,
+                "newline": newline,
+            }
+        }
+    )
+
+
+def replace_exact(
+    path: str,
+    old: str,
+    new: str,
+    *,
+    expected_count: int = 1,
+) -> Action:
+    return Action(
+        {
+            "replace_exact": {
+                "path": path,
+                "old": old,
+                "new": new,
+                "expected_count": expected_count,
+            }
+        }
+    )
+
+
+def insert_before(
+    path: str,
+    anchor: str,
+    content: str,
+    *,
+    expected_count: int = 1,
+) -> Action:
+    return Action(
+        {
+            "insert_before": {
+                "path": path,
+                "anchor": anchor,
+                "content": content,
+                "expected_count": expected_count,
+            }
+        }
+    )
+
+
+def insert_after(
+    path: str,
+    anchor: str,
+    content: str,
+    *,
+    expected_count: int = 1,
+) -> Action:
+    return Action(
+        {
+            "insert_after": {
+                "path": path,
+                "anchor": anchor,
+                "content": content,
+                "expected_count": expected_count,
+            }
+        }
+    )
+
+
+def delete_exact(
+    path: str,
+    text: str,
+    *,
+    expected_count: int = 1,
+) -> Action:
+    return Action(
+        {
+            "delete_exact": {
+                "path": path,
+                "text": text,
+                "expected_count": expected_count,
+            }
+        }
+    )
+
+
+def apply_diff(diff: str, *, strip: int = 1) -> Action:
+    return Action({"apply_diff": {"diff": diff, "strip": strip}})
+
+
+__all__ = [
+    "apply_diff",
+    "create_directory",
+    "create_file",
+    "delete_exact",
+    "environment",
+    "file_info",
+    "find_files",
+    "git_status",
+    "hash",
+    "insert_after",
+    "insert_before",
+    "read",
+    "replace_exact",
+    "search",
+    "tree",
+]

patchshuttle/actions/create.py

@@ -0,0 +1,155 @@
+"""Race-resistant creation primitives for already-approved plans."""
+
+from __future__ import annotations
+
+import errno
+import hashlib
+import os
+import uuid
+from pathlib import Path, PurePosixPath
+
+from patchshuttle.planner import PlannedFileChange
+from patchshuttle.policy import PathKind, Policy
+from patchshuttle.workspace import Workspace
+
+_LINK_FALLBACK_ERRORS = frozenset(
+    value
+    for value in (
+        errno.EPERM,
+        errno.EXDEV,
+        getattr(errno, "ENOTSUP", None),
+        getattr(errno, "EOPNOTSUPP", None),
+    )
+    if value is not None
+)
+
+
+class FilePublishError(OSError):
+    """A publication failure that reports which temporary paths now exist."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        target_created: bool,
+        temporary_path: Path | None = None,
+    ) -> None:
+        self.target_created = target_created
+        self.temporary_path = temporary_path
+        super().__init__(message)
+
+
+def create_directory(workspace: Workspace, path: PurePosixPath) -> None:
+    """Create one missing planned directory without accepting races."""
+
+    target = Policy(workspace).resolve(path, allow_missing=True)
+    if target.kind is not PathKind.MISSING:
+        raise FileExistsError(path.as_posix())
+    target.absolute.mkdir()
+
+
+def verify_created_directory(workspace: Workspace, path: PurePosixPath) -> None:
+    """Require the post-state promised by a directory creation action."""
+
+    target = Policy(workspace).resolve(path, allow_missing=True)
+    if target.kind is not PathKind.DIRECTORY:
+        raise OSError(f"created directory has an unexpected post-state: {path}")
+
+
+def atomic_create_file(workspace: Workspace, change: PlannedFileChange) -> None:
+    """Publish a complete new file without replacing an existing target."""
+
+    policy = Policy(workspace)
+    target = policy.resolve(change.path, allow_missing=True)
+    if target.kind is not PathKind.MISSING:
+        raise FileExistsError(change.path.as_posix())
+    parent = policy.resolve(change.path.parent, allow_root=True)
+
+    temporary = parent.absolute / f".patchshuttle-{uuid.uuid4().hex}.tmp"
+    descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o666)
+    published = False
+    pending: BaseException | None = None
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(change.content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        try:
+            os.link(temporary, target.absolute)
+        except OSError as exc:
+            if exc.errno not in _LINK_FALLBACK_ERRORS:
+                raise
+            _exclusive_copy(target.absolute, change.content)
+        published = True
+    except BaseException as exc:
+        pending = exc
+
+    cleanup_error: OSError | None = None
+    try:
+        temporary.unlink()
+    except FileNotFoundError:
+        pass
+    except OSError as exc:
+        cleanup_error = exc
+
+    if cleanup_error is not None:
+        target_created = published or (
+            isinstance(pending, FilePublishError) and pending.target_created
+        )
+        raise FilePublishError(
+            "temporary create-file data could not be removed",
+            target_created=target_created,
+            temporary_path=temporary,
+        ) from (pending or cleanup_error)
+    if pending is not None:
+        raise pending
+
+
+def verify_created_file(workspace: Workspace, change: PlannedFileChange) -> None:
+    """Require exact bytes, length, and hash after a create-file action."""
+
+    target = Policy(workspace).resolve(change.path, allow_missing=True)
+    if target.kind is not PathKind.FILE:
+        raise OSError(f"created file has an unexpected post-state: {change.path}")
+    raw = target.absolute.read_bytes()
+    if (
+        len(raw) != change.after_size
+        or hashlib.sha256(raw).hexdigest() != change.after_sha256
+        or raw != change.content
+    ):
+        raise OSError(
+            f"created file content failed post-state validation: {change.path}"
+        )
+
+
+def _exclusive_copy(target: Path, content: bytes) -> None:
+    descriptor = os.open(
+        target,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+        0o666,
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+    except BaseException as exc:
+        try:
+            target.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError as cleanup_error:
+            raise FilePublishError(
+                "a partial create-file target could not be removed",
+                target_created=True,
+            ) from cleanup_error
+        raise exc
+
+
+__all__ = [
+    "FilePublishError",
+    "atomic_create_file",
+    "create_directory",
+    "verify_created_directory",
+    "verify_created_file",
+]

patchshuttle/actions/modify.py

@@ -0,0 +1,174 @@
+"""Atomic replacement primitives for planned existing-file changes."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+import uuid
+from collections.abc import Callable
+from pathlib import Path, PurePosixPath
+
+from patchshuttle.planner import PlannedFileChange
+from patchshuttle.policy import PathKind, Policy, WorkspacePath
+from patchshuttle.workspace import Workspace
+
+
+class FileReplaceError(OSError):
+    """A replacement failure with retained temporary-path context."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        target_modified: bool,
+        temporary_path: Path | None = None,
+    ) -> None:
+        self.target_modified = target_modified
+        self.temporary_path = temporary_path
+        super().__init__(message)
+
+
+def atomic_replace_file(
+    workspace: Workspace,
+    change: PlannedFileChange,
+    *,
+    mode: int,
+) -> None:
+    """Replace a still-matching existing file with its planned final bytes."""
+
+    policy = Policy(workspace)
+    target = _require_file(policy, change.path)
+    _require_planned_original(target, change)
+    _atomic_replace_bytes(
+        target.absolute,
+        change.content,
+        mode=mode,
+        before_publish=lambda: _require_planned_original(
+            _require_file(policy, change.path),
+            change,
+        ),
+    )
+
+
+def verify_modified_file(
+    workspace: Workspace,
+    change: PlannedFileChange,
+    *,
+    mode: int,
+) -> None:
+    """Require exact planned bytes and preserved mode after replacement."""
+
+    target = _require_file(Policy(workspace), change.path)
+    raw = target.absolute.read_bytes()
+    if (
+        len(raw) != change.after_size
+        or hashlib.sha256(raw).hexdigest() != change.after_sha256
+        or raw != change.content
+        or stat.S_IMODE(target.absolute.lstat().st_mode) != mode
+    ):
+        raise OSError(f"modified file failed post-state validation: {change.path}")
+
+
+def atomic_restore_file(
+    workspace: Workspace,
+    path: PurePosixPath,
+    content: bytes,
+    *,
+    mode: int,
+) -> None:
+    """Restore retained bytes to a regular or unexpectedly missing target."""
+
+    policy = Policy(workspace)
+    target = policy.resolve(path, allow_missing=True)
+    if target.kind not in {PathKind.FILE, PathKind.MISSING}:
+        raise OSError(f"rollback target has an unexpected type: {path}")
+    parent = policy.resolve(path.parent, allow_root=True)
+    _atomic_replace_bytes(parent.absolute / path.name, content, mode=mode)
+
+
+def verify_restored_file(
+    workspace: Workspace,
+    path: PurePosixPath,
+    content: bytes,
+    *,
+    mode: int,
+) -> None:
+    """Require exact original bytes and mode after a rollback restoration."""
+
+    target = _require_file(Policy(workspace), path)
+    raw = target.absolute.read_bytes()
+    if raw != content or stat.S_IMODE(target.absolute.lstat().st_mode) != mode:
+        raise OSError(f"restored file failed post-state validation: {path}")
+
+
+def _require_file(policy: Policy, path: PurePosixPath) -> WorkspacePath:
+    target = policy.resolve(path, allow_missing=True)
+    if target.kind is not PathKind.FILE:
+        raise OSError(f"planned modification target is not a regular file: {path}")
+    return target
+
+
+def _require_planned_original(
+    target: WorkspacePath,
+    change: PlannedFileChange,
+) -> None:
+    if change.before_size is None or change.before_sha256 is None:
+        raise OSError(f"planned modification lacks an original hash: {change.path}")
+    raw = target.absolute.read_bytes()
+    if (
+        len(raw) != change.before_size
+        or hashlib.sha256(raw).hexdigest() != change.before_sha256
+    ):
+        raise OSError(f"modification target changed after planning: {change.path}")
+
+
+def _atomic_replace_bytes(
+    target: Path,
+    content: bytes,
+    *,
+    mode: int,
+    before_publish: Callable[[], None] | None = None,
+) -> None:
+    temporary = target.parent / f".patchshuttle-{uuid.uuid4().hex}.tmp"
+    descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    replaced = False
+    pending: BaseException | None = None
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary.chmod(mode)
+        if before_publish is not None:
+            before_publish()
+        os.replace(temporary, target)
+        replaced = True
+    except BaseException as exc:
+        pending = exc
+
+    cleanup_error: OSError | None = None
+    try:
+        temporary.unlink()
+    except FileNotFoundError:
+        pass
+    except OSError as exc:
+        cleanup_error = exc
+
+    if cleanup_error is not None:
+        raise FileReplaceError(
+            "temporary replacement data could not be removed",
+            target_modified=replaced,
+            temporary_path=temporary,
+        ) from (pending or cleanup_error)
+    if pending is not None:
+        raise pending
+
+
+__all__ = [
+    "FileReplaceError",
+    "atomic_replace_file",
+    "atomic_restore_file",
+    "verify_modified_file",
+    "verify_restored_file",
+]