filekeeper-cli 0.1.0__py3-none-any.whl

filekeeper/core/database.py

@@ -0,0 +1,226 @@
+"""SQLite connection setup and forward-only migrations.
+
+There are two migration chains because there are two stores:
+
+* the **registry** database (``<home>/metadata.sqlite3``) holds ``workspaces``
+  and ``settings`` — data that spans workspaces and cannot live inside one;
+* the **workspace** database (``<workspace>/.filekeeper/state.sqlite3``, or the
+  shared location in global mode) holds ``operations``, ``operation_items``,
+  ``blobs`` and ``locks`` — per-workspace state that travels with the tree.
+
+Both chains are ordered, numbered, and applied at most once. A database whose
+recorded version is ahead of this code is refused rather than guessed at.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import stat
+import uuid
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .errors import MigrationError, StorageError
+
+REGISTRY_SCHEMA_VERSION = 1
+WORKSPACE_SCHEMA_VERSION = 1
+
+_REGISTRY_MIGRATIONS: tuple[tuple[int, tuple[str, ...]], ...] = (
+    (
+        1,
+        (
+            """
+            CREATE TABLE workspaces (
+                id TEXT PRIMARY KEY,
+                name TEXT NOT NULL UNIQUE,
+                root_path TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            )
+            """,
+            "CREATE UNIQUE INDEX idx_workspaces_root_path ON workspaces(root_path)",
+            """
+            CREATE TABLE settings (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL
+            )
+            """,
+        ),
+    ),
+)
+
+_WORKSPACE_MIGRATIONS: tuple[tuple[int, tuple[str, ...]], ...] = (
+    (
+        1,
+        (
+            """
+            CREATE TABLE operations (
+                id TEXT PRIMARY KEY,
+                workspace_id TEXT NOT NULL,
+                operation_type TEXT NOT NULL,
+                target_path TEXT,
+                status TEXT NOT NULL CHECK (
+                    status IN ('pending', 'committed', 'undone', 'failed', 'partially_undone')
+                ),
+                created_at TEXT NOT NULL,
+                actor TEXT,
+                task_id TEXT,
+                summary TEXT,
+                before_hash TEXT,
+                after_hash TEXT,
+                metadata_json TEXT
+            )
+            """,
+            "CREATE INDEX idx_operations_workspace_time ON operations(workspace_id, created_at)",
+            "CREATE INDEX idx_operations_target_path ON operations(target_path)",
+            "CREATE INDEX idx_operations_task_id ON operations(task_id)",
+            """
+            CREATE TABLE operation_items (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                operation_id TEXT NOT NULL REFERENCES operations(id) ON DELETE CASCADE,
+                relative_path TEXT NOT NULL,
+                item_type TEXT NOT NULL,
+                before_blob_hash TEXT,
+                after_blob_hash TEXT,
+                before_exists INTEGER NOT NULL DEFAULT 0,
+                after_exists INTEGER NOT NULL DEFAULT 0,
+                before_mode INTEGER,
+                after_mode INTEGER
+            )
+            """,
+            "CREATE INDEX idx_operation_items_operation ON operation_items(operation_id)",
+            "CREATE INDEX idx_operation_items_path ON operation_items(relative_path)",
+            """
+            CREATE TABLE blobs (
+                hash TEXT PRIMARY KEY,
+                size INTEGER NOT NULL,
+                created_at TEXT NOT NULL
+            )
+            """,
+            """
+            CREATE TABLE locks (
+                workspace_id TEXT NOT NULL,
+                relative_path TEXT NOT NULL,
+                owner TEXT NOT NULL,
+                token TEXT NOT NULL,
+                expires_at TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                PRIMARY KEY (workspace_id, relative_path)
+            )
+            """,
+            "CREATE INDEX idx_locks_expires_at ON locks(expires_at)",
+        ),
+    ),
+)
+
+_MIGRATION_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS schema_migrations (
+    version INTEGER PRIMARY KEY,
+    applied_at TEXT NOT NULL
+)
+"""
+
+
+def utc_now() -> str:
+    """Current UTC time as an ISO-8601 string with second precision."""
+
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+def uuid_token() -> str:
+    """A short, URL-safe, collision-resistant identifier fragment."""
+
+    return uuid.uuid4().hex[:16]
+
+
+def connect(path: Path) -> sqlite3.Connection:
+    """Open a SQLite database with durable, foreign-key-enforcing settings."""
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path.parent, stat.S_IRWXU)
+    except OSError:  # pragma: no cover - restricted filesystems
+        pass
+    try:
+        connection = sqlite3.connect(path, timeout=10.0)
+    except sqlite3.Error as exc:
+        raise StorageError(f"cannot open database: {exc}", details={"path": str(path)}) from exc
+    connection.row_factory = sqlite3.Row
+    connection.execute("PRAGMA journal_mode = WAL")
+    # Full synchronous mode: a committed record survives an OS crash, which the
+    # recovery story depends on.
+    connection.execute("PRAGMA synchronous = FULL")
+    connection.execute("PRAGMA foreign_keys = ON")
+    connection.execute("PRAGMA busy_timeout = 5000")
+    return connection
+
+
+def _current_version(connection: sqlite3.Connection) -> int:
+    connection.execute(_MIGRATION_TABLE_SQL)
+    row = connection.execute("SELECT MAX(version) AS version FROM schema_migrations").fetchone()
+    if row is None or row["version"] is None:
+        return 0
+    return int(row["version"])
+
+
+def migrate(
+    connection: sqlite3.Connection,
+    migrations: Sequence[tuple[int, tuple[str, ...]]],
+    *,
+    label: str,
+) -> int:
+    """Apply every pending migration in order; return the resulting version."""
+
+    current = _current_version(connection)
+    target = max((version for version, _ in migrations), default=0)
+    if current > target:
+        raise MigrationError(
+            f"{label} database schema version {current} is newer than this release "
+            f"supports ({target}); upgrade Filekeeper",
+            details={"current": current, "supported": target},
+        )
+
+    for version, statements in migrations:
+        if version <= current:
+            continue
+        try:
+            with connection:
+                for statement in statements:
+                    connection.execute(statement)
+                connection.execute(
+                    "INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)",
+                    (version, utc_now()),
+                )
+        except sqlite3.Error as exc:
+            raise MigrationError(
+                f"cannot migrate {label} database to version {version}: {exc}",
+                details={"label": label, "version": version},
+            ) from exc
+        current = version
+    return current
+
+
+def migrate_registry(connection: sqlite3.Connection) -> int:
+    return migrate(connection, _REGISTRY_MIGRATIONS, label="registry")
+
+
+def migrate_workspace(connection: sqlite3.Connection) -> int:
+    return migrate(connection, _WORKSPACE_MIGRATIONS, label="workspace")
+
+
+def open_registry_database(path: Path) -> sqlite3.Connection:
+    connection = connect(path)
+    migrate_registry(connection)
+    return connection
+
+
+def open_workspace_database(path: Path) -> sqlite3.Connection:
+    connection = connect(path)
+    migrate_workspace(connection)
+    try:
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:  # pragma: no cover - restricted filesystems
+        pass
+    return connection

filekeeper/core/diffing.py

@@ -0,0 +1,127 @@
+"""Unified diff rendering that never concatenates two lines.
+
+``difflib.unified_diff`` renders each input line exactly as it received it, so a
+final line without a newline carries no terminator and runs straight into the
+next rendered line. That produces output no patch consumer can read.
+
+This module normalises every rendered content line to end with a newline and
+states a missing final newline explicitly with the conventional
+``\`` marker. Every line of the result, including the
+last, ends with ``\\n``.
+
+The same function feeds the human view, the JSON payload and the dry-run
+preview, so all three describe a change identically.
+"""
+
+from __future__ import annotations
+
+import difflib
+from dataclasses import dataclass
+
+NO_NEWLINE_MARKER = "\"
+
+
+@dataclass(frozen=True, slots=True)
+class DiffLine:
+    """One line of text, split from its terminator.
+
+    ``text`` keeps every character except the terminator, including unusual
+    separators such as a form feed, so joining ``raw`` values reproduces the
+    input exactly.
+    """
+
+    text: str
+    ending: str
+
+    @property
+    def raw(self) -> str:
+        return self.text + self.ending
+
+
+def split_lines(text: str) -> list[DiffLine]:
+    """Split text into lines without discarding each line's own terminator."""
+
+    lines: list[DiffLine] = []
+    for piece in text.splitlines(keepends=True):
+        if piece.endswith("\r\n"):
+            lines.append(DiffLine(piece[:-2], "\r\n"))
+        elif piece.endswith(("\n", "\r")):
+            lines.append(DiffLine(piece[:-1], piece[-1]))
+        else:
+            lines.append(DiffLine(piece, ""))
+    return lines
+
+
+def join_lines(lines: list[DiffLine]) -> str:
+    return "".join(line.raw for line in lines)
+
+
+def _unterminated_last_line(text: str) -> bool:
+    if not text:
+        return False
+    return not text.endswith(("\n", "\r"))
+
+
+def unified_diff_text(
+    before: str,
+    after: str,
+    *,
+    fromfile: str,
+    tofile: str,
+) -> str:
+    """Render a unified diff in which every line is newline-terminated.
+
+    A side that does not end with a newline gets an explicit marker after the
+    rendered line that represents its final line. The marker is emitted once
+    when both sides share the same final context line.
+    """
+
+    before_lines = split_lines(before)
+    after_lines = split_lines(after)
+    before_texts = [line.text for line in before_lines]
+    after_texts = [line.text for line in after_lines]
+
+    rendered = list(
+        difflib.unified_diff(
+            [text + "\n" for text in before_texts],
+            [text + "\n" for text in after_texts],
+            fromfile=fromfile,
+            tofile=tofile,
+            lineterm="\n",
+        )
+    )
+    if not rendered:
+        return ""
+
+    inserts: dict[int, bool] = {}
+
+    if before_lines and not before_lines[-1].ending:
+        target = before_texts[-1] + "\n"
+        for index in range(len(rendered) - 1, 1, -1):
+            if rendered[index][:1] in {"-", " "} and rendered[index][1:] == target:
+                inserts[index] = True
+                break
+
+    if after_lines and not after_lines[-1].ending:
+        target = after_texts[-1] + "\n"
+        for index in range(len(rendered) - 1, 1, -1):
+            if rendered[index][:1] in {"+", " "} and rendered[index][1:] == target:
+                inserts[index] = True
+                break
+
+    output: list[str] = []
+    marker = NO_NEWLINE_MARKER + "\n"
+    for index, line in enumerate(rendered):
+        output.append(line)
+        if index in inserts:
+            output.append(marker)
+    return "".join(output)
+
+
+__all__ = [
+    "NO_NEWLINE_MARKER",
+    "DiffLine",
+    "join_lines",
+    "split_lines",
+    "unified_diff_text",
+]

filekeeper/core/errors.py

@@ -0,0 +1,278 @@
+"""Structured errors with stable, documented codes.
+
+Every failure surfaced by Core is a :class:`FilekeeperError`. The code is the
+stable part of the contract: adapters (CLI, MCP) map codes to exit codes and to
+error payloads, and callers may branch on the code without parsing prose.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+
+class ErrorCode(StrEnum):
+    """Stable error codes. Adding a code is a compatible change; renaming one is not."""
+
+    INVALID_ARGUMENT = "INVALID_ARGUMENT"
+    PATH_NOT_FOUND = "PATH_NOT_FOUND"
+    NOT_A_FILE = "NOT_A_FILE"
+    NOT_A_DIRECTORY = "NOT_A_DIRECTORY"
+    PATH_OUTSIDE_WORKSPACE = "PATH_OUTSIDE_WORKSPACE"
+    ABSOLUTE_PATH_OUTSIDE_WORKSPACE = "ABSOLUTE_PATH_OUTSIDE_WORKSPACE"
+    SYMLINK_ESCAPE_REFUSED = "SYMLINK_ESCAPE_REFUSED"
+    PATH_IS_STATE_PATH = "PATH_IS_STATE_PATH"
+    SYMLINK_WRITE_REFUSED = "SYMLINK_WRITE_REFUSED"
+    SPECIAL_FILE_REFUSED = "SPECIAL_FILE_REFUSED"
+    SENSITIVE_PATH_REFUSED = "SENSITIVE_PATH_REFUSED"
+    ALREADY_EXISTS = "ALREADY_EXISTS"
+    CONTENT_CONFLICT = "CONTENT_CONFLICT"
+    NO_MATCH = "NO_MATCH"
+    MATCH_COUNT_MISMATCH = "MATCH_COUNT_MISMATCH"
+    PATCH_FAILED = "PATCH_FAILED"
+    PARTIAL_RECOVERY = "PARTIAL_RECOVERY"
+    BINARY_CONTENT_REFUSED = "BINARY_CONTENT_REFUSED"
+    LIMIT_EXCEEDED = "LIMIT_EXCEEDED"
+    INVALID_PATTERN = "INVALID_PATTERN"
+    WORKSPACE_NOT_FOUND = "WORKSPACE_NOT_FOUND"
+    WORKSPACE_EXISTS = "WORKSPACE_EXISTS"
+    NO_WORKSPACE_SELECTED = "NO_WORKSPACE_SELECTED"
+    STORAGE_ERROR = "STORAGE_ERROR"
+    MIGRATION_ERROR = "MIGRATION_ERROR"
+    OPERATION_NOT_FOUND = "OPERATION_NOT_FOUND"
+    UNDO_CONFLICT = "UNDO_CONFLICT"
+    HISTORY_UNAVAILABLE = "HISTORY_UNAVAILABLE"
+    NOT_IMPLEMENTED_YET = "NOT_IMPLEMENTED_YET"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
+class FilekeeperError(Exception):
+    """Base error carrying a stable code, a human message, and optional details."""
+
+    code: ErrorCode = ErrorCode.INTERNAL_ERROR
+    retryable: bool = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: ErrorCode | None = None,
+        retryable: bool | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        if code is not None:
+            self.code = code
+        if retryable is not None:
+            self.retryable = retryable
+        self.details: dict[str, Any] = details or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "code": str(self.code),
+            "message": self.message,
+            "retryable": self.retryable,
+        }
+        if self.details:
+            payload["details"] = dict(self.details)
+        return payload
+
+    def __str__(self) -> str:
+        return f"{self.code}: {self.message}"
+
+
+class ValidationError(FilekeeperError):
+    code = ErrorCode.INVALID_ARGUMENT
+
+
+class PathNotFoundError(FilekeeperError):
+    code = ErrorCode.PATH_NOT_FOUND
+
+
+class NotAFileError(FilekeeperError):
+    code = ErrorCode.NOT_A_FILE
+
+
+class NotADirectoryError(FilekeeperError):
+    code = ErrorCode.NOT_A_DIRECTORY
+
+
+class PathOutsideWorkspaceError(FilekeeperError):
+    """A relative path used ``..`` traversal."""
+
+    code = ErrorCode.PATH_OUTSIDE_WORKSPACE
+
+
+class AbsolutePathOutsideWorkspaceError(PathOutsideWorkspaceError):
+    """An absolute path resolved outside the selected workspace."""
+
+    code = ErrorCode.ABSOLUTE_PATH_OUTSIDE_WORKSPACE
+
+
+class SymlinkEscapeRefusedError(PathOutsideWorkspaceError):
+    """A symlink inside the workspace resolved to a target outside it."""
+
+    code = ErrorCode.SYMLINK_ESCAPE_REFUSED
+
+
+class StatePathError(FilekeeperError):
+    """A path points inside Filekeeper's own state directory."""
+
+    code = ErrorCode.PATH_IS_STATE_PATH
+
+
+class SymlinkWriteRefusedError(FilekeeperError):
+    code = ErrorCode.SYMLINK_WRITE_REFUSED
+
+
+class SpecialFileRefusedError(FilekeeperError):
+    code = ErrorCode.SPECIAL_FILE_REFUSED
+
+
+class SensitivePathRefusedError(FilekeeperError):
+    """The target looks like credential or key material and was refused."""
+
+    code = ErrorCode.SENSITIVE_PATH_REFUSED
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message, details=details)
+
+
+class AlreadyExistsError(FilekeeperError):
+    code = ErrorCode.ALREADY_EXISTS
+
+
+class ContentConflictError(FilekeeperError):
+    """The guarded write's expected hash or content no longer matches.
+
+    The identical request cannot succeed, so ``retryable`` is ``False``. The
+    recovery path is stated in the payload: read the current state again and
+    issue the write against the hash that read returned.
+    """
+
+    code = ErrorCode.CONTENT_CONFLICT
+    retryable = False
+
+    def __init__(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        payload: dict[str, Any] = {
+            "recovery": "re-read the target, then retry against its current hash"
+        }
+        if details:
+            payload.update(details)
+        super().__init__(message, details=payload)
+
+
+class NoMatchError(FilekeeperError):
+    """No occurrence of the requested text was found; nothing was modified."""
+
+    code = ErrorCode.NO_MATCH
+
+
+class MatchCountMismatchError(FilekeeperError):
+    """The requested text matched a different number of times than expected."""
+
+    code = ErrorCode.MATCH_COUNT_MISMATCH
+
+
+class PatchFailedError(FilekeeperError):
+    """A patch was rejected or could not be applied; the pre-patch state is intact."""
+
+    code = ErrorCode.PATCH_FAILED
+
+
+class PartialRecoveryError(FilekeeperError):
+    """A failed multi-file application could not be fully rolled back."""
+
+    code = ErrorCode.PARTIAL_RECOVERY
+
+
+class BinaryContentRefusedError(FilekeeperError):
+    code = ErrorCode.BINARY_CONTENT_REFUSED
+
+
+class LimitExceededError(FilekeeperError):
+    code = ErrorCode.LIMIT_EXCEEDED
+
+    def __init__(
+        self, message: str, *, limit: int, actual: int, details: dict[str, Any] | None = None
+    ) -> None:
+        payload: dict[str, Any] = {"limit": limit, "actual": actual}
+        if details:
+            payload.update(details)
+        super().__init__(message, details=payload)
+
+
+class InvalidPatternError(FilekeeperError):
+    code = ErrorCode.INVALID_PATTERN
+
+
+class WorkspaceNotFoundError(FilekeeperError):
+    code = ErrorCode.WORKSPACE_NOT_FOUND
+
+
+class WorkspaceExistsError(FilekeeperError):
+    code = ErrorCode.WORKSPACE_EXISTS
+
+
+class NoWorkspaceSelectedError(FilekeeperError):
+    code = ErrorCode.NO_WORKSPACE_SELECTED
+
+
+class StorageError(FilekeeperError):
+    code = ErrorCode.STORAGE_ERROR
+
+
+class MigrationError(FilekeeperError):
+    code = ErrorCode.MIGRATION_ERROR
+
+
+class OperationNotFoundError(FilekeeperError):
+    """No operation with that id is recorded in this workspace."""
+
+    code = ErrorCode.OPERATION_NOT_FOUND
+
+
+class UndoConflictError(FilekeeperError):
+    """Undo would destroy a later change; nothing was modified."""
+
+    code = ErrorCode.UNDO_CONFLICT
+
+
+class HistoryUnavailableError(FilekeeperError):
+    """The bytes needed to undo are missing, corrupt or were never stored."""
+
+    code = ErrorCode.HISTORY_UNAVAILABLE
+
+
+class NotImplementedYetError(FilekeeperError, NotImplementedError):
+    """A published API surface whose implementation is deliberately a later release.
+
+    It subclasses :class:`NotImplementedError` as well, so callers that guard the
+    standard exception also catch it. It is never a silent no-op.
+    """
+
+    code = ErrorCode.NOT_IMPLEMENTED_YET
+
+
+def storage_failure(action: str, path: str, exc: OSError) -> StorageError:
+    """Build the :class:`StorageError` for a failed filesystem call on ``path``.
+
+    ``path`` is the caller-facing path: the workspace-relative form for anything
+    inside a workspace. An ``OSError``'s own message embeds the resolved host
+    path, so only its standard reason phrase is carried into the message.
+
+    Guaranteed: a workspace file or directory is never named by its resolved
+    host path in a :class:`StorageError`, neither in the message nor in
+    ``details``. Every construction site that has a workspace path in hand
+    passes the relative form, and :func:`filekeeper.core.safety.hashing.hash_file`
+    never falls back to the resolved path.
+
+    Not covered: locations the operator chooses rather than workspace content —
+    the state directory and its database, and the configuration file. Those
+    errors report the location as the operator supplied it, and their message
+    still carries only the reason phrase.
+    """
+
+    reason = exc.strerror or type(exc).__name__
+    return StorageError(f"cannot {action} {path}: {reason}", details={"path": path})

filekeeper/core/history/__init__.py

@@ -0,0 +1,20 @@
+"""Durable operation history: blob store, journal, read surfaces, and undo."""
+
+from __future__ import annotations
+
+from .blobs import BlobStore
+from .journal import BeginResult, OperationJournal, PendingItem
+from .repository import diff_operation, get_operation, list_history
+from .undo import undo_last, undo_operation
+
+__all__ = [
+    "BeginResult",
+    "BlobStore",
+    "OperationJournal",
+    "PendingItem",
+    "diff_operation",
+    "get_operation",
+    "list_history",
+    "undo_last",
+    "undo_operation",
+]