filekeeper-cli 0.1.0__py3-none-any.whl

filekeeper/cli/exit_codes.py

@@ -0,0 +1,84 @@
+"""Stable process exit codes.
+
+These numbers are part of the published contract: scripts and agents may branch
+on them. They are documented in ``README.md`` and must not be renumbered.
+"""
+
+from __future__ import annotations
+
+from ..core.errors import ErrorCode, FilekeeperError
+
+SUCCESS = 0
+GENERAL_ERROR = 1
+INVALID_ARGUMENT = 2
+PATH_NOT_FOUND = 3
+ACCESS_DENIED = 4
+CONFLICT = 5
+ABSOLUTE_PATH_OUTSIDE_WORKSPACE = 6
+PATCH_FAILED = 7
+PARTIAL_RECOVERY = 8
+STORAGE_ERROR = 9
+SENSITIVE_PATH_REFUSED = 10
+SYMLINK_ESCAPE_REFUSED = 11
+UNDO_CONFLICT = 12
+HISTORY_UNAVAILABLE = 13
+
+_BY_CODE: dict[str, int] = {
+    str(ErrorCode.INVALID_ARGUMENT): INVALID_ARGUMENT,
+    str(ErrorCode.NOT_A_FILE): INVALID_ARGUMENT,
+    str(ErrorCode.NOT_A_DIRECTORY): INVALID_ARGUMENT,
+    str(ErrorCode.LIMIT_EXCEEDED): INVALID_ARGUMENT,
+    str(ErrorCode.INVALID_PATTERN): INVALID_ARGUMENT,
+    str(ErrorCode.NO_WORKSPACE_SELECTED): INVALID_ARGUMENT,
+    str(ErrorCode.ALREADY_EXISTS): INVALID_ARGUMENT,
+    str(ErrorCode.BINARY_CONTENT_REFUSED): INVALID_ARGUMENT,
+    str(ErrorCode.PATH_NOT_FOUND): PATH_NOT_FOUND,
+    str(ErrorCode.WORKSPACE_NOT_FOUND): PATH_NOT_FOUND,
+    str(ErrorCode.PATH_OUTSIDE_WORKSPACE): ACCESS_DENIED,
+    str(ErrorCode.ABSOLUTE_PATH_OUTSIDE_WORKSPACE): ABSOLUTE_PATH_OUTSIDE_WORKSPACE,
+    str(ErrorCode.SYMLINK_ESCAPE_REFUSED): SYMLINK_ESCAPE_REFUSED,
+    str(ErrorCode.PATH_IS_STATE_PATH): ACCESS_DENIED,
+    str(ErrorCode.SYMLINK_WRITE_REFUSED): ACCESS_DENIED,
+    str(ErrorCode.SPECIAL_FILE_REFUSED): ACCESS_DENIED,
+    str(ErrorCode.SENSITIVE_PATH_REFUSED): SENSITIVE_PATH_REFUSED,
+    str(ErrorCode.CONTENT_CONFLICT): CONFLICT,
+    str(ErrorCode.NO_MATCH): CONFLICT,
+    str(ErrorCode.MATCH_COUNT_MISMATCH): CONFLICT,
+    str(ErrorCode.PATCH_FAILED): PATCH_FAILED,
+    str(ErrorCode.PARTIAL_RECOVERY): PARTIAL_RECOVERY,
+    str(ErrorCode.STORAGE_ERROR): STORAGE_ERROR,
+    str(ErrorCode.MIGRATION_ERROR): STORAGE_ERROR,
+    str(ErrorCode.OPERATION_NOT_FOUND): PATH_NOT_FOUND,
+    str(ErrorCode.UNDO_CONFLICT): UNDO_CONFLICT,
+    str(ErrorCode.HISTORY_UNAVAILABLE): HISTORY_UNAVAILABLE,
+    str(ErrorCode.WORKSPACE_EXISTS): INVALID_ARGUMENT,
+    str(ErrorCode.NOT_IMPLEMENTED_YET): GENERAL_ERROR,
+    str(ErrorCode.INTERNAL_ERROR): GENERAL_ERROR,
+}
+
+EXIT_CODE_DOCUMENTATION: tuple[tuple[int, str], ...] = (
+    (SUCCESS, "success"),
+    (GENERAL_ERROR, "unexpected error"),
+    (INVALID_ARGUMENT, "invalid arguments or validation error"),
+    (PATH_NOT_FOUND, "path or workspace not found"),
+    (ACCESS_DENIED, "permission or workspace-boundary violation"),
+    (CONFLICT, "concurrency conflict: stale hash, missing match or match-count mismatch"),
+    (ABSOLUTE_PATH_OUTSIDE_WORKSPACE, "absolute path outside the workspace"),
+    (PATCH_FAILED, "patch could not be applied; the pre-patch state is intact"),
+    (PARTIAL_RECOVERY, "a failed patch could not be fully rolled back"),
+    (STORAGE_ERROR, "storage or database error"),
+    (SENSITIVE_PATH_REFUSED, "write refused: target looks like credential material"),
+    (SYMLINK_ESCAPE_REFUSED, "symlink target outside the workspace"),
+    (UNDO_CONFLICT, "undo refused: the path changed after the operation"),
+    (HISTORY_UNAVAILABLE, "history needed for restore is missing, corrupt or skipped"),
+)
+
+
+def exit_code_for(error: FilekeeperError) -> int:
+    return _BY_CODE.get(str(error.code), GENERAL_ERROR)
+
+
+def exit_code_for_code(code: str) -> int:
+    """Map a bare error-code string, for results that report failures as data."""
+
+    return _BY_CODE.get(code, GENERAL_ERROR)

filekeeper/cli/output.py

@@ -0,0 +1,244 @@
+"""Rendering: human-readable text by default, one stable JSON object with --json.
+
+Nothing here decides behaviour; it prints what Core returned. JSON payloads are
+documented in ``README.md``: always an object, always with ``ok``, and errors
+carry ``error.code`` / ``error.message`` / ``error.retryable``.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from ..core.errors import FilekeeperError
+from ..core.models import (
+    ContentSearchResult,
+    DirectoryListing,
+    ExistsResult,
+    FileReadResult,
+    MutationResult,
+    OperationDiff,
+    OperationRecord,
+    PathInfo,
+    PathSearchResult,
+    ReadManyEntry,
+    Workspace,
+)
+
+
+def jsonable(value: Any) -> Any:
+    """Convert dataclasses, enums, tuples and paths into JSON-ready values."""
+
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        fields = dataclasses.fields(value)
+        return {field.name: jsonable(getattr(value, field.name)) for field in fields}
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(key): jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [jsonable(item) for item in value]
+    return value
+
+
+def print_json(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(jsonable(payload), ensure_ascii=False, indent=2, sort_keys=False))
+    sys.stdout.write("\n")
+
+
+def print_error(error: FilekeeperError, *, as_json: bool) -> None:
+    if as_json:
+        print_json({"ok": False, "error": error.to_dict()})
+        return
+    sys.stderr.write(f"error: {error.code}: {error.message}\n")
+    for key, value in error.details.items():
+        sys.stderr.write(f"  {key}: {value}\n")
+
+
+def result_payload(result: Any) -> dict[str, Any]:
+    payload = jsonable(result)
+    merged: dict[str, Any] = {"ok": True}
+    merged.update(payload)
+    return merged
+
+
+# -- human renderers -------------------------------------------------------
+def read(result: FileReadResult) -> str:
+    return result.content
+
+
+def read_many(entries: tuple[ReadManyEntry, ...]) -> str:
+    chunks: list[str] = []
+    for entry in entries:
+        chunks.append(f"== {entry.path} ==")
+        if entry.ok and entry.result is not None:
+            chunks.append(entry.result.content.rstrip("\n"))
+        else:
+            code = entry.error.code if entry.error else "UNKNOWN"
+            message = entry.error.message if entry.error else "read failed"
+            chunks.append(f"[{code}] {message}")
+    return "\n".join(chunks)
+
+
+def listing(result: DirectoryListing) -> str:
+    lines: list[str] = []
+    for entry in result.entries:
+        marker = "/" if entry.kind == "directory" else "@" if entry.kind == "symlink" else ""
+        lines.append(f"{entry.kind:<9} {entry.size_bytes:>10}  {entry.path}{marker}")
+    if result.truncated:
+        lines.append(f"... truncated at {result.max_entries} entries")
+    return "\n".join(lines)
+
+
+def info(result: PathInfo) -> str:
+    lines = [
+        f"path: {result.path}",
+        f"kind: {result.kind}",
+        f"size_bytes: {result.size_bytes}",
+        f"mode: {result.mode:04o}",
+        f"modified_at: {result.modified_at}",
+    ]
+    if result.is_symlink:
+        lines.append(f"symlink_target: {result.symlink_target}")
+    if result.content_hash is not None:
+        lines.append(f"content_hash: {result.content_hash}")
+    if result.is_text is not None:
+        lines.append(f"is_text: {result.is_text}")
+    if result.line_count is not None:
+        lines.append(f"line_count: {result.line_count}")
+    if result.encoding is not None:
+        lines.append(f"encoding: {result.encoding}")
+    if result.newline is not None:
+        lines.append(f"newline: {json.dumps(result.newline)}")
+    return "\n".join(lines)
+
+
+def exists(result: ExistsResult) -> str:
+    if not result.exists:
+        return f"{result.path}: absent"
+    return f"{result.path}: present ({result.kind})"
+
+
+def path_search(result: PathSearchResult) -> str:
+    lines = list(result.paths)
+    if result.truncated:
+        lines.append("... truncated; narrow the glob or raise the result limit")
+    return "\n".join(lines)
+
+
+def content_search(result: ContentSearchResult) -> str:
+    lines = [
+        f"{match.path}:{match.line_number}:{match.column}: {match.line}" for match in result.matches
+    ]
+    if result.truncated:
+        lines.append("... truncated; narrow the query or raise the result limit")
+    return "\n".join(lines)
+
+
+def mutation(result: MutationResult) -> str:
+    lines: list[str] = []
+    for item in result.items:
+        lines.append(f"{item.change:<9} {item.path}")
+    lines.append(result.summary)
+    if result.after_hash:
+        lines.append(f"after_hash: {result.after_hash}")
+    if result.before_hash and result.before_hash != result.after_hash:
+        lines.append(f"before_hash: {result.before_hash}")
+    if result.match_stage is not None:
+        lines.append(f"match_stage: {result.match_stage}")
+    if result.match_count is not None:
+        lines.append(f"match_count: {result.match_count}")
+    if result.patch_files:
+        lines.append(
+            f"patch_files: {len(result.patch_files)} "
+            "(recoverable through history, not atomic across files)"
+        )
+        for file in result.patch_files:
+            hunks = ", ".join(
+                f"hunk {hunk.old_start}: {hunk.status}" for hunk in file.hunks
+            )
+            lines.append(f"  {file.change:<9} {file.path}  {hunks}")
+    if result.preview_diff:
+        lines.append("diff:")
+        lines.extend(result.preview_diff.rstrip("\n").split("\n"))
+    if result.operation_id is not None:
+        lines.append(f"operation_id: {result.operation_id}")
+        lines.append(f"undo_available: {'yes' if result.undo_available else 'no'}")
+    elif result.dry_run:
+        lines.append("operation_id: none (dry run: nothing was recorded)")
+    for warning in result.warnings:
+        lines.append(f"warning: {warning}")
+    return "\n".join(lines)
+
+
+def history_list(operations: tuple[OperationRecord, ...]) -> str:
+    if not operations:
+        return "no recorded operations in this workspace"
+    lines = [
+        f"{record.operation_id}  {record.created_at}  {record.status:<9} "
+        f"{record.operation_type:<17} {record.target_path or '-'}"
+        + (f"  [{record.actor}]" if record.actor else "")
+        for record in operations
+    ]
+    return "\n".join(lines)
+
+
+def history_show(record: OperationRecord) -> str:
+    lines = [
+        f"operation_id: {record.operation_id}",
+        f"workspace_id: {record.workspace_id}",
+        f"operation_type: {record.operation_type}",
+        f"status: {record.status}",
+        f"created_at: {record.created_at}",
+        f"target_path: {record.target_path or '-'}",
+        f"actor: {record.actor or '-'}",
+        f"task_id: {record.task_id or '-'}",
+        f"summary: {record.summary or '-'}",
+        f"before_hash: {record.before_hash or '-'}",
+        f"after_hash: {record.after_hash or '-'}",
+        "items:",
+    ]
+    for item in record.items:
+        exists = f"{int(item.before_exists)}->{int(item.after_exists)}"
+        lines.append(
+            f"  {item.item_type:<9} {item.relative_path}  exists {exists}  "
+            f"before {item.before_blob_hash or '-'}  after {item.after_blob_hash or '-'}"
+        )
+    if record.history_skipped:
+        lines.append("history_skipped: " + ", ".join(record.history_skipped))
+    return "\n".join(lines)
+
+
+def history_diff(diff: OperationDiff) -> str:
+    chunks: list[str] = []
+    for entry in diff.items:
+        if entry.is_binary:
+            chunks.append(f"# {entry.path}: binary content, no textual diff")
+            continue
+        if entry.unified_diff:
+            chunks.append(entry.unified_diff.rstrip("\n"))
+    return "\n".join(chunks) if chunks else "no textual differences recorded"
+
+
+def workspace_summary(workspace: Workspace, *, is_default: bool = False) -> str:
+    suffix = "  (default)" if is_default else ""
+    return f"{workspace.name}\t{workspace.root_path}\t{workspace.id}{suffix}"
+
+
+def workspace_detail(workspace: Workspace, *, is_default: bool = False) -> str:
+    return "\n".join(
+        [
+            f"name: {workspace.name}",
+            f"id: {workspace.id}",
+            f"root: {workspace.root_path}",
+            f"created_at: {workspace.created_at}",
+            f"updated_at: {workspace.updated_at}",
+            f"default: {is_default}",
+        ]
+    )

filekeeper/core/__init__.py

@@ -0,0 +1,51 @@
+"""Filekeeper Core: workspace-confined, crash-safe filesystem operations.
+
+Core imports nothing outside the Python standard library. It has no knowledge of
+the CLI, of the MCP server, or of any filesystem protocol.
+"""
+
+from .config import Config
+from .errors import ErrorCode, FilekeeperError
+from .history.blobs import BlobStore
+from .models import (
+    ContentMatch,
+    ContentSearchResult,
+    DirectoryEntry,
+    DirectoryListing,
+    ErrorDetail,
+    ExistsResult,
+    FileReadResult,
+    MutationResult,
+    OperationItemResult,
+    PathInfo,
+    PathSearchResult,
+    ReadManyEntry,
+    Workspace,
+)
+from .service import Filekeeper, FilekeeperService, init_home
+from .workspace import WorkspaceHandle, WorkspaceRegistry
+
+__all__ = [
+    "BlobStore",
+    "Config",
+    "ContentMatch",
+    "ContentSearchResult",
+    "DirectoryEntry",
+    "DirectoryListing",
+    "ErrorCode",
+    "ErrorDetail",
+    "ExistsResult",
+    "FileReadResult",
+    "Filekeeper",
+    "FilekeeperError",
+    "FilekeeperService",
+    "MutationResult",
+    "OperationItemResult",
+    "PathInfo",
+    "PathSearchResult",
+    "ReadManyEntry",
+    "Workspace",
+    "WorkspaceHandle",
+    "WorkspaceRegistry",
+    "init_home",
+]

filekeeper/core/config.py

@@ -0,0 +1,133 @@
+"""Home directory resolution and configuration.
+
+Two kinds of state exist, and they live in different places on purpose:
+
+* the **registry** (workspace registrations and settings) lives in the user's
+  home, because it spans workspaces;
+* **per-workspace state** (the future operation journal and blob store) lives in
+  ``<workspace>/.filekeeper/`` by default, so it travels with the checkout.
+  ``state_location = "global"`` opts into one shared store under the home
+  directory instead.
+
+``config.toml`` in the home directory holds tunable limits. It is read on every
+invocation; writing it is left to the user (``keeper init`` creates it with the
+defaults spelled out).
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, fields
+from pathlib import Path
+
+from .errors import StorageError, ValidationError
+
+CONFIG_FILENAME = "config.toml"
+STATE_DIR_NAME = ".filekeeper"
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    """Limits and behaviour switches. Values are bytes unless stated otherwise."""
+
+    max_read_bytes: int = 5 * 1024 * 1024
+    max_write_bytes: int = 20 * 1024 * 1024
+    max_search_results: int = 500
+    max_directory_entries: int = 2000
+    max_recursion_depth: int = 25
+    max_line_length: int = 2000
+    max_history_blob_bytes: int = 4 * 1024 * 1024
+    fsync: bool = True
+    state_location: str = "project"
+
+    def __post_init__(self) -> None:
+        if self.state_location not in {"project", "global"}:
+            raise ValidationError(
+                "state_location must be 'project' or 'global'",
+                details={"state_location": self.state_location},
+            )
+        for field_info in fields(self):
+            value = getattr(self, field_info.name)
+            if isinstance(value, int) and not isinstance(value, bool) and value <= 0:
+                raise ValidationError(
+                    f"{field_info.name} must be positive", details={"value": value}
+                )
+
+
+def resolve_home(override: str | os.PathLike[str] | None = None) -> Path:
+    """Resolve Filekeeper's home directory: explicit, ``FILEKEEPER_HOME``, XDG, then default."""
+
+    if override is not None:
+        return Path(override).expanduser()
+    from_env = os.environ.get("FILEKEEPER_HOME")
+    if from_env:
+        return Path(from_env).expanduser()
+    xdg = os.environ.get("XDG_DATA_HOME")
+    if xdg:
+        return Path(xdg).expanduser() / "filekeeper"
+    return Path.home() / ".local" / "share" / "filekeeper"
+
+
+def config_path(home: Path) -> Path:
+    return home / CONFIG_FILENAME
+
+
+def load_config(home: Path) -> Config:
+    """Load ``config.toml``; a missing file yields defaults. Unknown keys are ignored."""
+
+    path = config_path(home)
+    if not path.exists():
+        return Config()
+    try:
+        with path.open("rb") as handle:
+            raw = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise StorageError(
+            f"cannot read configuration file: "
+            f"{getattr(exc, 'strerror', None) or exc}",
+            details={"path": str(path)},
+        ) from exc
+
+    section = raw.get("filekeeper", raw)
+    if not isinstance(section, dict):
+        raise StorageError("configuration file must contain a table", details={"path": str(path)})
+
+    known = {field_info.name for field_info in fields(Config)}
+    values: dict[str, object] = {}
+    for key, value in section.items():
+        if key in known:
+            values[key] = value
+    try:
+        return Config(**values)  # type: ignore[arg-type]
+    except TypeError as exc:
+        raise StorageError(
+            f"invalid configuration value: {exc}", details={"path": str(path)}
+        ) from exc
+
+
+DEFAULT_CONFIG_TOML = """\
+# Filekeeper configuration.
+# All sizes are bytes. Delete a key to fall back to the built-in default.
+
+[filekeeper]
+max_read_bytes = 5242880
+max_write_bytes = 20971520
+max_search_results = 500
+max_directory_entries = 2000
+max_recursion_depth = 25
+max_line_length = 2000
+
+# Files above this size are skipped by history: the mutation is still recorded,
+# but its previous bytes are not stored, so it cannot be undone. This keeps one
+# large edit from silently filling the blob store.
+max_history_blob_bytes = 4194304
+
+# Durability of atomic writes: flush and fsync the temporary file and the
+# parent directory before reporting success.
+fsync = true
+
+# "project" keeps per-workspace state in <workspace>/.filekeeper/ (default).
+# "global" keeps one shared store under this home directory instead.
+state_location = "project"
+"""