filekeeper-cli 0.1.0__py3-none-any.whl

filekeeper/core/history/undo.py

@@ -0,0 +1,358 @@
+"""Safe undo with up-front conflict detection.
+
+Undo never blindly overwrites: every affected path must still match one of the
+two states recorded for it — the post-operation state (untouched since the
+change) or the pre-operation state (already back where undo wants it, which is
+what a partially applied multi-file operation leaves behind). A path that
+matches neither was changed by someone else, and the whole undo is refused
+before a single byte is written.
+
+The undo is itself recorded as an operation, so the ledger stays truthful.
+Redo is deliberately absent from this release; see ``README.md``.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..errors import (
+    HistoryUnavailableError,
+    StorageError,
+    UndoConflictError,
+    storage_failure,
+)
+from ..models import MutationResult, OperationItemRecord, OperationItemResult, OperationRecord
+from ..safety.atomic import atomic_write_bytes, fsync_directory
+from ..safety.hashing import hash_file
+from .journal import COMMITTED, FAILED, UNDONE, OperationJournal, PendingItem
+
+
+@dataclass(frozen=True, slots=True)
+class _Step:
+    item: OperationItemRecord
+    action: str  # "restore-file", "restore-directory", "remove-file", "remove-directory", "none"
+    data: bytes | None = None
+
+
+def _target_path(journal: OperationJournal, relative_path: str) -> Path:
+    candidate = (journal.root / relative_path).resolve()
+    root = journal.root.resolve()
+    if candidate != root and root not in candidate.parents:
+        raise StorageError(
+            "refusing to undo a path outside the workspace",
+            details={"path": relative_path},
+        )
+    return candidate
+
+
+def _current(item: OperationItemRecord, path: Path) -> tuple[bool, str | None]:
+    if item.item_type == "directory":
+        return path.is_dir(), None
+    if not path.is_file():
+        return False, None
+    try:
+        return True, hash_file(path, display_path=item.relative_path)
+    except OSError:
+        return False, None
+
+
+def _matches(
+    exists: bool, digest: str | None, current_exists: bool, current_hash: str | None
+) -> bool:
+    if exists != current_exists:
+        return False
+    if not exists:
+        return True
+    if digest is None:
+        return True
+    return current_hash == digest
+
+
+def _load_before(journal: OperationJournal, item: OperationItemRecord) -> bytes:
+    if item.before_blob_hash is None:
+        raise HistoryUnavailableError(
+            f"history was not stored for {item.relative_path}, so it cannot be restored",
+            details={"path": item.relative_path, "operation_item": item.relative_path},
+        )
+    try:
+        return journal.blobs.get_bytes(item.before_blob_hash)
+    except StorageError as exc:
+        raise HistoryUnavailableError(
+            f"the recorded content for {item.relative_path} is missing or corrupt: {exc.message}",
+            details={"path": item.relative_path, "hash": item.before_blob_hash},
+        ) from exc
+
+
+def _plan(journal: OperationJournal, record: OperationRecord) -> list[_Step]:
+    steps: list[_Step] = []
+    conflicts: list[str] = []
+    already_before = 0
+
+    for item in record.items:
+        path = _target_path(journal, item.relative_path)
+        current_exists, current_hash = _current(item, path)
+        matches_before = _matches(
+            item.before_exists, item.before_blob_hash, current_exists, current_hash
+        )
+        matches_after = _matches(
+            item.after_exists, item.after_blob_hash, current_exists, current_hash
+        )
+        if not matches_before and not matches_after:
+            conflicts.append(item.relative_path)
+            continue
+        if matches_before:
+            already_before += 1
+            continue
+
+        if not item.before_exists:
+            action = "remove-directory" if item.item_type == "directory" else "remove-file"
+            steps.append(_Step(item=item, action=action))
+            continue
+
+        if item.item_type == "directory":
+            steps.append(_Step(item=item, action="restore-directory"))
+        else:
+            steps.append(_Step(item=item, action="restore-file", data=_load_before(journal, item)))
+
+    # A directory may only be removed when every entry inside it is also being
+    # removed by this same undo. That keeps "undo of a directory create" from
+    # destroying files the user added afterwards, while allowing a directory
+    # move (whose children are all recorded) to be reversed.
+    removal_paths = {
+        journal.root.joinpath(step.item.relative_path).resolve()
+        for step in steps
+        if step.action in {"remove-file", "remove-directory"}
+    }
+    for step in steps:
+        if step.action != "remove-directory":
+            continue
+        directory = _target_path(journal, step.item.relative_path)
+        try:
+            leftovers = [
+                entry for entry in directory.iterdir() if entry.resolve() not in removal_paths
+            ]
+        except OSError:
+            leftovers = [directory]
+        if leftovers:
+            conflicts.append(step.item.relative_path)
+
+    if conflicts:
+        raise UndoConflictError(
+            "cannot undo: these paths changed after the operation, so nothing was modified",
+            details={
+                "operation_id": record.operation_id,
+                "conflicting_paths": ", ".join(sorted(conflicts)),
+            },
+        )
+    if record.status == FAILED and already_before == len(record.items):
+        raise UndoConflictError(
+            "operation did not take effect; there is nothing to undo",
+            details={"operation_id": record.operation_id},
+        )
+    if record.status == UNDONE:
+        raise UndoConflictError(
+            "operation is already undone", details={"operation_id": record.operation_id}
+        )
+    if record.status not in {COMMITTED, FAILED}:
+        raise UndoConflictError(
+            "operation is not committed and cannot be undone",
+            details={"operation_id": record.operation_id, "status": record.status},
+        )
+    return steps
+
+
+def _apply(journal: OperationJournal, steps: list[_Step]) -> None:
+    directories = [step for step in steps if step.action == "restore-directory"]
+    for step in sorted(directories, key=lambda entry: entry.item.relative_path.count("/")):
+        path = _target_path(journal, step.item.relative_path)
+        try:
+            path.mkdir(parents=True, exist_ok=True)
+            if step.item.before_mode is not None:
+                os.chmod(path, stat.S_IMODE(step.item.before_mode))
+        except OSError as exc:
+            raise storage_failure("restore directory", step.item.relative_path, exc) from exc
+
+    for step in steps:
+        if step.action != "restore-file":
+            continue
+        path = _target_path(journal, step.item.relative_path)
+        try:
+            atomic_write_bytes(
+                path,
+                step.data or b"",
+                mode=step.item.before_mode,
+                fsync=journal.config.fsync,
+                display_path=step.item.relative_path,
+            )
+        except OSError as exc:
+            raise storage_failure("restore file", step.item.relative_path, exc) from exc
+
+    removable = [step for step in steps if step.action in {"remove-file", "remove-directory"}]
+    files = [step for step in removable if step.action == "remove-file"]
+    for step in files:
+        path = _target_path(journal, step.item.relative_path)
+        try:
+            path.unlink()
+            fsync_directory(path.parent)
+        except OSError as exc:
+            raise storage_failure(
+                "remove file during undo", step.item.relative_path, exc
+            ) from exc
+
+    directories = [step for step in removable if step.action == "remove-directory"]
+    for step in sorted(
+        directories, key=lambda entry: entry.item.relative_path.count("/"), reverse=True
+    ):
+        path = _target_path(journal, step.item.relative_path)
+        try:
+            path.rmdir()
+            fsync_directory(path.parent)
+        except OSError as exc:
+            raise storage_failure(
+                "remove directory during undo", step.item.relative_path, exc
+            ) from exc
+
+
+def _undo_items(record: OperationRecord) -> list[PendingItem]:
+    items: list[PendingItem] = []
+    for item in record.items:
+        items.append(
+            PendingItem(
+                relative_path=item.relative_path,
+                item_type=item.item_type,
+                before_exists=item.after_exists,
+                after_exists=item.before_exists,
+                before_hash=item.after_blob_hash,
+                after_hash=item.before_blob_hash,
+                before_mode=item.after_mode,
+                after_mode=item.before_mode,
+            )
+        )
+    return items
+
+
+def _result(
+    journal: OperationJournal,
+    record: OperationRecord,
+    undo_operation_id: str,
+    *,
+    workspace_name: str,
+    steps: list[_Step],
+) -> MutationResult:
+    items = tuple(
+        OperationItemResult(
+            path=step.item.relative_path,
+            change=(
+                "deleted"
+                if not step.item.before_exists
+                else "created"
+                if not step.item.after_exists
+                else "modified"
+            ),
+            before_hash=step.item.after_blob_hash,
+            after_hash=step.item.before_blob_hash,
+        )
+        for step in steps
+        if step.action != "none"
+    )
+    return MutationResult(
+        workspace=workspace_name,
+        path=record.target_path or "",
+        changed=True,
+        before_hash=record.after_hash,
+        after_hash=record.before_hash,
+        summary=f"Undid operation {record.operation_id}.",
+        operation_id=undo_operation_id,
+        undo_available=True,
+        items=items,
+        affected_count=len(items),
+    )
+
+
+def undo_operation(
+    journal: OperationJournal,
+    operation_id: str,
+    *,
+    workspace_name: str,
+    actor: str | None = None,
+    task_id: str | None = None,
+) -> MutationResult:
+    """Restore the recorded pre-state of one operation, or refuse and change nothing."""
+
+    record = journal.get(operation_id)
+    if record is None:
+        from ..errors import OperationNotFoundError
+
+        raise OperationNotFoundError(
+            "no operation with that id in this workspace", details={"operation_id": operation_id}
+        )
+    steps = _plan(journal, record)
+    undo_items = _undo_items(record)
+
+    begun = journal.begin(
+        operation_type="undo",
+        target_path=record.target_path,
+        summary=f"Undid operation {record.operation_id}.",
+        items=undo_items,
+        actor=actor,
+        task_id=task_id,
+        before_hash=record.after_hash,
+        after_hash=record.before_hash,
+        metadata={"undone_operation": record.operation_id},
+    )
+    try:
+        _apply(journal, steps)
+    except Exception:
+        journal.abort(begun.operation_id)
+        raise
+    journal.commit(begun.operation_id)
+    journal._set_status(record.operation_id, UNDONE)
+    return _result(
+        journal, record, begun.operation_id, workspace_name=workspace_name, steps=steps
+    )
+
+
+def latest_undoable(journal: OperationJournal, *, actor: str | None = None) -> OperationRecord:
+    clauses = ["status IN (?, ?)"]
+    parameters: list[object] = [COMMITTED, FAILED]
+    if actor is not None:
+        clauses.append("actor = ?")
+        parameters.append(actor)
+    connection = journal._connect()
+    try:
+        row = connection.execute(
+            f"SELECT * FROM operations WHERE {' AND '.join(clauses)} "
+            "ORDER BY created_at DESC, rowid DESC LIMIT 1",
+            tuple(parameters),
+        ).fetchone()
+    finally:
+        connection.close()
+    if row is None:
+        raise UndoConflictError(
+            "no undoable operation in this workspace",
+            details={"actor": actor},
+        )
+    record = journal.get(str(row["id"]))
+    assert record is not None
+    return record
+
+
+def undo_last(
+    journal: OperationJournal,
+    *,
+    workspace_name: str,
+    actor: str | None = None,
+    task_id: str | None = None,
+) -> MutationResult:
+    """Undo the most recent operation in *this* workspace; never another one's."""
+
+    record = latest_undoable(journal, actor=actor)
+    return undo_operation(
+        journal, record.operation_id, workspace_name=workspace_name, actor=actor, task_id=task_id
+    )
+
+
+__all__ = ["latest_undoable", "undo_last", "undo_operation"]

filekeeper/core/models.py

@@ -0,0 +1,293 @@
+"""Value types returned by Core.
+
+All result types are frozen dataclasses. Paths in results are
+workspace-relative POSIX strings so that CLI and MCP output are identical and
+free of host-specific absolute paths.
+
+Hashes are SHA-256 and are formatted as ``sha256:<64 hex characters>``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+EntryKind = Literal["file", "directory", "symlink", "other"]
+
+
+@dataclass(frozen=True, slots=True)
+class Workspace:
+    """A registered workspace root."""
+
+    id: str
+    name: str
+    root_path: str
+    created_at: str
+    updated_at: str
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorDetail:
+    """An error rendered as data, for multi-result calls that must not raise."""
+
+    code: str
+    message: str
+    retryable: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "code": self.code,
+            "message": self.message,
+            "retryable": self.retryable,
+        }
+        if self.details:
+            payload["details"] = self.details
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class FileReadResult:
+    """A bounded read. ``content`` holds the requested lines with their original endings.
+
+    Line numbers are 1-based and inclusive. ``total_lines`` is ``None`` when the
+    read was truncated byte-wise before the end of the file; ``next_start_line``
+    then names the first line that was not returned.
+    """
+
+    path: str
+    content: str
+    start_line: int
+    end_line: int
+    returned_line_count: int
+    total_lines: int | None
+    size_bytes: int
+    content_hash: str
+    encoding: str
+    newline: str
+    has_bom: bool
+    truncated: bool = False
+    truncation_reason: str | None = None
+    next_start_line: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ReadManyEntry:
+    """One file's outcome inside :meth:`read_multiple_files`; failures are data, not raises."""
+
+    path: str
+    ok: bool
+    result: FileReadResult | None = None
+    error: ErrorDetail | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DirectoryEntry:
+    path: str
+    name: str
+    kind: EntryKind
+    size_bytes: int
+    is_symlink: bool
+
+
+@dataclass(frozen=True, slots=True)
+class DirectoryListing:
+    path: str
+    entries: tuple[DirectoryEntry, ...]
+    truncated: bool
+    max_entries: int
+
+
+@dataclass(frozen=True, slots=True)
+class PathInfo:
+    path: str
+    kind: EntryKind
+    size_bytes: int
+    mode: int
+    modified_at: str
+    is_symlink: bool
+    symlink_target: str | None = None
+    is_text: bool | None = None
+    content_hash: str | None = None
+    line_count: int | None = None
+    encoding: str | None = None
+    newline: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ExistsResult:
+    path: str
+    exists: bool
+    kind: EntryKind | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PathSearchResult:
+    path: str
+    glob: str
+    paths: tuple[str, ...]
+    truncated: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ContentMatch:
+    path: str
+    line_number: int
+    line: str
+    column: int
+
+
+@dataclass(frozen=True, slots=True)
+class ContentSearchResult:
+    path: str
+    query: str
+    regex: bool
+    matches: tuple[ContentMatch, ...]
+    truncated: bool
+    files_searched: int
+
+
+@dataclass(frozen=True, slots=True)
+class OperationItemResult:
+    """One path touched by a mutation.
+
+    ``operation_item_id`` is reserved for the history layer; it is ``None`` in
+    releases that do not record history.
+    """
+
+    path: str
+    change: Literal["created", "modified", "deleted", "moved", "unchanged"]
+    before_hash: str | None = None
+    after_hash: str | None = None
+    size_bytes: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OperationItemRecord:
+    """One path recorded against an operation in the durable history."""
+
+    relative_path: str
+    item_type: str
+    before_blob_hash: str | None
+    after_blob_hash: str | None
+    before_exists: bool
+    after_exists: bool
+    before_mode: int | None
+    after_mode: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class OperationRecord:
+    """An operation as stored in the history ledger.
+
+    ``operation_id`` is the single key used by every surface: mutations,
+    ``history list`` / ``history show``, diff, undo and the MCP tools.
+    """
+
+    operation_id: str
+    workspace_id: str
+    operation_type: str
+    target_path: str | None
+    status: str
+    created_at: str
+    actor: str | None
+    task_id: str | None
+    summary: str | None
+    before_hash: str | None
+    after_hash: str | None
+    items: tuple[OperationItemRecord, ...] = ()
+    history_skipped: tuple[str, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class DiffEntry:
+    """One path's before/after comparison inside :func:`diff_operation`."""
+
+    path: str
+    item_type: str
+    before_exists: bool
+    after_exists: bool
+    is_binary: bool
+    unified_diff: str
+
+
+@dataclass(frozen=True, slots=True)
+class OperationDiff:
+    operation_id: str
+    items: tuple[DiffEntry, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class PatchHunkResult:
+    """One unified-diff hunk and what happened to it.
+
+    ``status`` is ``"applied"`` for a real application, ``"would_apply"`` for a
+    dry run, and ``"rejected"`` when a hunk could not be placed. Line numbers in
+    a hunk header are 1-based; an empty old side uses position 0.
+    """
+
+    old_start: int
+    old_count: int
+    new_start: int
+    new_count: int
+    status: str
+
+
+@dataclass(frozen=True, slots=True)
+class PatchFileResult:
+    """One path affected by :func:`apply_patch`, with its per-hunk outcomes."""
+
+    path: str
+    change: Literal["created", "modified", "deleted", "unchanged"]
+    applied: bool
+    before_hash: str | None
+    after_hash: str | None
+    hunks: tuple[PatchHunkResult, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class MutationResult:
+    """The stable shape of every mutating call.
+
+    ``operation_id`` names the durable history record for the mutation and is
+    ``None`` only for a dry run. ``undo_available`` says whether that record can
+    restore the previous bytes: it is ``False`` when an affected file exceeded
+    the history size cap, because its previous bytes were deliberately not
+    stored.
+
+    ``match_stage`` and ``match_count`` describe text replacement, and
+    ``preview_diff`` carries a dry-run unified diff. ``patch_files`` describes a
+    patch application; a recovered failure reports what was rolled back in the
+    error details.
+    """
+
+    workspace: str
+    path: str
+    changed: bool
+    before_hash: str | None
+    after_hash: str | None
+    summary: str
+    operation_id: str | None = None
+    undo_available: bool = False
+    dry_run: bool = False
+    warnings: tuple[str, ...] = ()
+    items: tuple[OperationItemResult, ...] = ()
+    affected_count: int | None = None
+    history_skipped: tuple[str, ...] = ()
+    match_stage: str | None = None
+    match_count: int | None = None
+    preview_diff: str | None = None
+    patch_files: tuple[PatchFileResult, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = _jsonable(asdict(self))
+        return payload
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {key: _jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(item) for item in value]
+    return value

filekeeper/core/operations/__init__.py

@@ -0,0 +1,9 @@
+"""Filesystem operations, grouped by concern.
+
+``edit`` is a published stub for a later release; importing it is safe and every
+call raises rather than pretending to work.
+"""
+
+from . import directory, edit, read, search, write
+
+__all__ = ["directory", "edit", "read", "search", "write"]