patchshuttle 0.1.0a2__py3-none-any.whl

patchshuttle/__init__.py

@@ -0,0 +1,98 @@
+"""Public package surface for PatchShuttle."""
+
+from patchshuttle._version import __version__
+from patchshuttle.audit import AuditActionResult, AuditRunResult, AuditStatus
+from patchshuttle.context import (
+    HandoffResult,
+    SnapshotResult,
+    create_handoff,
+    create_snapshot,
+)
+from patchshuttle.errors import (
+    ExecutionError,
+    ExecutionErrorCode,
+    JobError,
+    JobErrorCode,
+    PlanningError,
+    PlanningErrorCode,
+    PolicyError,
+    PolicyErrorCode,
+    WorkspaceError,
+    WorkspaceErrorCode,
+)
+from patchshuttle.execution import RunResult, RunStatus, execute_plan
+from patchshuttle.models import Action, Check, Job, JobKind
+from patchshuttle.operations import ManualRollbackResult, rollback_job
+from patchshuttle.parser import load_job, validate_job
+from patchshuttle.planner import (
+    ActionDisposition,
+    FileDisposition,
+    NewlineStyle,
+    PathFingerprint,
+    Plan,
+    PlannedAction,
+    PlannedCheck,
+    PlannedFileChange,
+    plan_job,
+)
+from patchshuttle.policy import PathKind, Policy, WorkspacePath
+from patchshuttle.verification import VerificationRunResult
+from patchshuttle.workspace import (
+    Workspace,
+    WorkspaceInitResult,
+    WorkspaceInitStatus,
+    discover_workspace,
+    init_workspace,
+    load_workspace,
+)
+
+__all__ = [
+    "Action",
+    "ActionDisposition",
+    "AuditActionResult",
+    "AuditRunResult",
+    "AuditStatus",
+    "Check",
+    "ExecutionError",
+    "ExecutionErrorCode",
+    "FileDisposition",
+    "HandoffResult",
+    "Job",
+    "JobError",
+    "JobErrorCode",
+    "JobKind",
+    "ManualRollbackResult",
+    "NewlineStyle",
+    "PathKind",
+    "PathFingerprint",
+    "Plan",
+    "PlannedAction",
+    "PlannedCheck",
+    "PlannedFileChange",
+    "PlanningError",
+    "PlanningErrorCode",
+    "Policy",
+    "PolicyError",
+    "PolicyErrorCode",
+    "RunResult",
+    "RunStatus",
+    "SnapshotResult",
+    "VerificationRunResult",
+    "Workspace",
+    "WorkspaceError",
+    "WorkspaceErrorCode",
+    "WorkspaceInitResult",
+    "WorkspaceInitStatus",
+    "WorkspacePath",
+    "__version__",
+    "create_handoff",
+    "create_snapshot",
+    "discover_workspace",
+    "execute_plan",
+    "init_workspace",
+    "load_job",
+    "load_workspace",
+    "plan_job",
+    "rollback_job",
+    "validate_job",
+]

patchshuttle/_diff.py

@@ -0,0 +1,317 @@
+"""Strict in-process unified-diff parsing and dry-run application."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from patchshuttle.errors import PlanningError, PlanningErrorCode
+
+_HUNK_HEADER = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(?:.*)?(?:\n)?$")
+_BINARY_MARKERS = ("Binary files ", "GIT binary patch")
+_FORBIDDEN_METADATA = (
+    "new file mode ",
+    "deleted file mode ",
+    "old mode ",
+    "new mode ",
+    "similarity index ",
+    "rename from ",
+    "rename to ",
+    "copy from ",
+    "copy to ",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DiffHunk:
+    old_start: int
+    old_count: int
+    new_start: int
+    new_count: int
+    old_lines: tuple[str, ...]
+    new_lines: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class FileDiff:
+    path: str
+    hunks: tuple[DiffHunk, ...]
+
+
+def parse_unified_diff(
+    value: str,
+    *,
+    strip: int,
+    item_id: str,
+) -> tuple[FileDiff, ...]:
+    """Parse a text-only, existing-file unified diff without side effects."""
+
+    normalized = value.replace("\r\n", "\n").replace("\r", "\n")
+    lines = normalized.splitlines(keepends=True)
+    if not lines:
+        raise _error(
+            PlanningErrorCode.DIFF_INVALID,
+            "unified diff is empty",
+            item_id,
+        )
+
+    parsed: list[FileDiff] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        if line.startswith(_BINARY_MARKERS):
+            raise _error(
+                PlanningErrorCode.DIFF_BINARY_FORBIDDEN,
+                "binary diffs are not allowed",
+                item_id,
+            )
+        if line.startswith(_FORBIDDEN_METADATA):
+            raise _error(
+                PlanningErrorCode.DIFF_PATH_INVALID,
+                "file creation, deletion, rename, copy, and mode changes are forbidden",
+                item_id,
+            )
+        if line.startswith("diff --git ") or line.startswith("index "):
+            index += 1
+            continue
+        if not line.startswith("--- "):
+            raise _error(
+                PlanningErrorCode.DIFF_INVALID,
+                "expected an old-file header beginning with '--- '",
+                item_id,
+            )
+
+        old_path = _parse_header_path(line, strip=strip, item_id=item_id)
+        index += 1
+        if index >= len(lines) or not lines[index].startswith("+++ "):
+            raise _error(
+                PlanningErrorCode.DIFF_INVALID,
+                "old-file header must be followed by a new-file header",
+                item_id,
+            )
+        new_path = _parse_header_path(lines[index], strip=strip, item_id=item_id)
+        if old_path != new_path:
+            raise _error(
+                PlanningErrorCode.DIFF_PATH_INVALID,
+                "unified diff may not rename or copy files",
+                item_id,
+                path=new_path,
+            )
+        index += 1
+
+        hunks: list[DiffHunk] = []
+        while index < len(lines) and lines[index].startswith("@@ "):
+            hunk, index = _parse_hunk(lines, index, item_id=item_id)
+            hunks.append(hunk)
+        if not hunks:
+            raise _error(
+                PlanningErrorCode.DIFF_INVALID,
+                "each file diff requires at least one hunk",
+                item_id,
+                path=new_path,
+            )
+        if any(existing.path == new_path for existing in parsed):
+            raise _error(
+                PlanningErrorCode.DIFF_INVALID,
+                "a unified diff may contain each target file only once",
+                item_id,
+                path=new_path,
+            )
+        parsed.append(FileDiff(path=new_path, hunks=tuple(hunks)))
+
+    if not parsed:
+        raise _error(
+            PlanningErrorCode.DIFF_INVALID,
+            "unified diff does not contain a file patch",
+            item_id,
+        )
+    return tuple(parsed)
+
+
+def apply_file_diff(text: str, diff: FileDiff, *, item_id: str) -> str:
+    """Apply parsed hunks to normalized LF text in memory."""
+
+    source = text.splitlines(keepends=True)
+    output: list[str] = []
+    cursor = 0
+    for hunk in diff.hunks:
+        start = hunk.old_start if hunk.old_count == 0 else hunk.old_start - 1
+        end = start + len(hunk.old_lines)
+        if start < cursor or end > len(source):
+            raise _error(
+                PlanningErrorCode.DIFF_HUNK_MISMATCH,
+                "hunk range does not match the current file",
+                item_id,
+                path=diff.path,
+            )
+        if tuple(source[start:end]) != hunk.old_lines:
+            raise _error(
+                PlanningErrorCode.DIFF_HUNK_MISMATCH,
+                "hunk context does not match the current file",
+                item_id,
+                path=diff.path,
+            )
+        output.extend(source[cursor:start])
+        output.extend(hunk.new_lines)
+        cursor = end
+    output.extend(source[cursor:])
+    return "".join(output)
+
+
+def _parse_header_path(line: str, *, strip: int, item_id: str) -> str:
+    raw = line[4:].rstrip("\n").split("\t", 1)[0]
+    if raw == "/dev/null":
+        raise _error(
+            PlanningErrorCode.DIFF_PATH_INVALID,
+            "file creation and deletion diffs are not allowed",
+            item_id,
+        )
+    if not raw or raw.startswith('"'):
+        raise _error(
+            PlanningErrorCode.DIFF_PATH_INVALID,
+            "quoted or empty diff paths are not supported",
+            item_id,
+        )
+    if raw.startswith(("/", "\\")):
+        raise _error(
+            PlanningErrorCode.DIFF_PATH_INVALID,
+            "absolute diff paths are not allowed",
+            item_id,
+            path=raw,
+        )
+
+    parts = raw.replace("\\", "/").split("/")
+    if len(parts) <= strip:
+        raise _error(
+            PlanningErrorCode.DIFF_PATH_INVALID,
+            f"diff path has fewer than {strip + 1} component(s)",
+            item_id,
+            path=raw,
+        )
+    stripped = PurePosixPath(*parts[strip:]).as_posix()
+    return stripped
+
+
+def _parse_hunk(
+    lines: list[str],
+    index: int,
+    *,
+    item_id: str,
+) -> tuple[DiffHunk, int]:
+    match = _HUNK_HEADER.fullmatch(lines[index])
+    if match is None:
+        raise _error(
+            PlanningErrorCode.DIFF_INVALID,
+            "invalid unified-diff hunk header",
+            item_id,
+        )
+    old_start = int(match.group(1))
+    old_count = int(match.group(2) or 1)
+    new_start = int(match.group(3))
+    new_count = int(match.group(4) or 1)
+    if (old_start == 0 and old_count != 0) or (new_start == 0 and new_count != 0):
+        raise _error(
+            PlanningErrorCode.DIFF_INVALID,
+            "a zero hunk start is valid only for an empty range",
+            item_id,
+        )
+    index += 1
+    old_lines: list[str] = []
+    new_lines: list[str] = []
+    previous_prefix: str | None = None
+
+    while index < len(lines):
+        line = lines[index]
+        if line.startswith(("@@ ", "--- ", "diff --git ")):
+            break
+        if line.startswith(_BINARY_MARKERS) or line.startswith(_FORBIDDEN_METADATA):
+            break
+        if line.startswith("\\"):
+            if line.rstrip("\n") != "\":
+                raise _error(
+                    PlanningErrorCode.DIFF_INVALID,
+                    "unknown backslash marker in unified diff",
+                    item_id,
+                )
+            _remove_last_newline(
+                old_lines,
+                new_lines,
+                previous_prefix=previous_prefix,
+                item_id=item_id,
+            )
+            index += 1
+            continue
+        if not line or line[0] not in " +-":
+            raise _error(
+                PlanningErrorCode.DIFF_INVALID,
+                "hunk lines must begin with space, '+', or '-'",
+                item_id,
+            )
+
+        previous_prefix = line[0]
+        content = line[1:]
+        if previous_prefix in " -":
+            old_lines.append(content)
+        if previous_prefix in " +":
+            new_lines.append(content)
+        index += 1
+
+    if len(old_lines) != old_count or len(new_lines) != new_count:
+        raise _error(
+            PlanningErrorCode.DIFF_INVALID,
+            "hunk body line counts do not match its header",
+            item_id,
+        )
+    return (
+        DiffHunk(
+            old_start=old_start,
+            old_count=old_count,
+            new_start=new_start,
+            new_count=new_count,
+            old_lines=tuple(old_lines),
+            new_lines=tuple(new_lines),
+        ),
+        index,
+    )
+
+
+def _remove_last_newline(
+    old_lines: list[str],
+    new_lines: list[str],
+    *,
+    previous_prefix: str | None,
+    item_id: str,
+) -> None:
+    if previous_prefix is None:
+        raise _error(
+            PlanningErrorCode.DIFF_INVALID,
+            "no-newline marker must follow a hunk content line",
+            item_id,
+        )
+    targets = []
+    if previous_prefix in " -":
+        targets.append(old_lines)
+    if previous_prefix in " +":
+        targets.append(new_lines)
+    for target in targets:
+        if not target or not target[-1].endswith("\n"):
+            raise _error(
+                PlanningErrorCode.DIFF_INVALID,
+                "no-newline marker is duplicated or misplaced",
+                item_id,
+            )
+        target[-1] = target[-1][:-1]
+
+
+def _error(
+    code: PlanningErrorCode,
+    message: str,
+    item_id: str,
+    *,
+    path: str | None = None,
+) -> PlanningError:
+    return PlanningError(code, message, item_id=item_id, path=path)
+
+
+__all__ = ["FileDiff", "apply_file_diff", "parse_unified_diff"]

patchshuttle/_process.py

@@ -0,0 +1,198 @@
+"""Shared bounded subprocess execution for trusted fixed command adapters."""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import BinaryIO
+
+
+class ProcessStatus(str, Enum):
+    """Low-level outcome of one controlled child process."""
+
+    PASSED = "PASSED"
+    FAILED = "FAILED"
+    TIMED_OUT = "TIMED_OUT"
+    ERROR = "ERROR"
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessCommand:
+    """A fixed argument array and its local execution limits."""
+
+    argv: tuple[str, ...]
+    working_directory: Path
+    timeout_seconds: int
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessResult:
+    """Bounded output and status returned by a controlled child process."""
+
+    status: ProcessStatus
+    return_code: int | None
+    duration_ms: int
+    stdout: str
+    stderr: str
+    stdout_truncated: bool
+    stderr_truncated: bool
+
+    @property
+    def success(self) -> bool:
+        return self.status is ProcessStatus.PASSED
+
+
+def run_process(
+    command: ProcessCommand,
+    *,
+    maximum_output_bytes: int,
+) -> ProcessResult:
+    """Run one fixed command without a shell and with bounded captured output."""
+
+    started = time.monotonic_ns()
+    with (
+        tempfile.TemporaryFile(mode="w+b") as stdout_stream,
+        tempfile.TemporaryFile(mode="w+b") as stderr_stream,
+    ):
+        try:
+            process = subprocess.Popen(
+                command.argv,
+                cwd=command.working_directory,
+                stdin=subprocess.DEVNULL,
+                stdout=stdout_stream,
+                stderr=stderr_stream,
+                shell=False,
+                **_process_group_options(),
+            )
+        except OSError as exc:
+            stderr, stderr_truncated = _bounded_text(
+                str(exc).encode("utf-8", errors="replace"),
+                maximum_output_bytes,
+            )
+            return _result(
+                status=ProcessStatus.ERROR,
+                return_code=None,
+                started=started,
+                stdout="",
+                stderr=stderr,
+                stdout_truncated=False,
+                stderr_truncated=stderr_truncated,
+            )
+
+        timed_out = False
+        try:
+            return_code = process.wait(timeout=command.timeout_seconds)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            return_code = None
+            _terminate_process(process)
+        except BaseException:
+            _terminate_process(process)
+            raise
+
+        stdout, stdout_truncated = _read_stream(
+            stdout_stream,
+            maximum_output_bytes,
+        )
+        stderr, stderr_truncated = _read_stream(
+            stderr_stream,
+            maximum_output_bytes,
+        )
+        status = (
+            ProcessStatus.TIMED_OUT
+            if timed_out
+            else ProcessStatus.PASSED if return_code == 0 else ProcessStatus.FAILED
+        )
+        return _result(
+            status=status,
+            return_code=return_code,
+            started=started,
+            stdout=stdout,
+            stderr=stderr,
+            stdout_truncated=stdout_truncated,
+            stderr_truncated=stderr_truncated,
+        )
+
+
+def _result(
+    *,
+    status: ProcessStatus,
+    return_code: int | None,
+    started: int,
+    stdout: str,
+    stderr: str,
+    stdout_truncated: bool,
+    stderr_truncated: bool,
+) -> ProcessResult:
+    return ProcessResult(
+        status=status,
+        return_code=return_code,
+        duration_ms=(time.monotonic_ns() - started) // 1_000_000,
+        stdout=stdout,
+        stderr=stderr,
+        stdout_truncated=stdout_truncated,
+        stderr_truncated=stderr_truncated,
+    )
+
+
+def _read_stream(stream: BinaryIO, maximum: int) -> tuple[str, bool]:
+    stream.flush()
+    stream.seek(0)
+    return _bounded_text(stream.read(maximum + 1), maximum)
+
+
+def _bounded_text(raw: bytes, maximum: int) -> tuple[str, bool]:
+    truncated = len(raw) > maximum
+    text = raw[:maximum].decode("utf-8", errors="replace")
+    return text.replace("\r\n", "\n").replace("\r", "\n"), truncated
+
+
+def _process_group_options() -> dict[str, object]:
+    if os.name == "nt":  # pragma: no cover - exercised by Windows CI
+        return {"creationflags": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)}
+    return {"start_new_session": True}
+
+
+def _terminate_process(process) -> None:
+    if process.poll() is not None:
+        return
+    _signal_process(process, force=False)
+    try:
+        process.wait(timeout=1)
+        return
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    _signal_process(process, force=True)
+    try:
+        process.wait(timeout=1)
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+
+def _signal_process(process, *, force: bool) -> None:
+    if os.name != "nt":
+        selected = signal.SIGKILL if force else signal.SIGTERM
+        try:
+            os.killpg(process.pid, selected)
+            return
+        except OSError:
+            pass
+    operation = process.kill if force else process.terminate
+    try:
+        operation()
+    except OSError:
+        pass
+
+
+__all__ = [
+    "ProcessCommand",
+    "ProcessResult",
+    "ProcessStatus",
+    "run_process",
+]

patchshuttle/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the PatchShuttle package version."""
+
+__version__ = "0.1.0a2"

patchshuttle/actions/__init__.py

@@ -0,0 +1,80 @@
+"""Guarded low-level actions used by the transaction runner."""
+
+from patchshuttle.actions.constructors import (
+    apply_diff,
+)
+from patchshuttle.actions.constructors import (
+    create_directory as _declarative_create_directory,
+)
+from patchshuttle.actions.constructors import (
+    create_file,
+    delete_exact,
+    environment,
+    file_info,
+    find_files,
+    git_status,
+    hash,
+    insert_after,
+    insert_before,
+    read,
+    replace_exact,
+    search,
+    tree,
+)
+from patchshuttle.actions.create import (
+    FilePublishError,
+    atomic_create_file,
+)
+from patchshuttle.actions.create import create_directory as apply_create_directory
+from patchshuttle.actions.create import (
+    verify_created_directory,
+    verify_created_file,
+)
+from patchshuttle.actions.modify import (
+    FileReplaceError,
+    atomic_replace_file,
+    atomic_restore_file,
+    verify_modified_file,
+    verify_restored_file,
+)
+from patchshuttle.workspace import Workspace
+
+
+def create_directory(*args, **kwargs):
+    """Create a declarative action, retaining the legacy internal call form."""
+
+    if (args and isinstance(args[0], Workspace)) or isinstance(
+        kwargs.get("workspace"),
+        Workspace,
+    ):
+        return apply_create_directory(*args, **kwargs)
+    return _declarative_create_directory(*args, **kwargs)
+
+
+__all__ = [
+    "FilePublishError",
+    "FileReplaceError",
+    "atomic_create_file",
+    "atomic_replace_file",
+    "atomic_restore_file",
+    "apply_create_directory",
+    "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",
+    "verify_created_directory",
+    "verify_created_file",
+    "verify_modified_file",
+    "verify_restored_file",
+]