ebk 0.4.4__py3-none-any.whl

ebk/skills/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: ebk
+description: Use this skill when working with ebk - an eBook metadata management CLI with SQLite storage, full-text search, hierarchical tags, and a virtual filesystem shell. Invoke for library management, book operations, imports/exports, or ebk shell navigation.
+---
+
+# ebk - eBook Metadata Management
+
+A CLI tool for managing ebook libraries with SQLite storage, full-text search, and a virtual filesystem shell.
+
+## Quick Reference
+
+```bash
+# Library management
+ebk lib init ~/my-library
+ebk lib migrate
+ebk lib backup -o backup.tar.gz
+ebk lib check
+
+# Query and discovery
+ebk query search "python programming"
+ebk query list --author "Knuth"
+ebk query stats
+ebk query sql "SELECT title FROM books WHERE language='en'"
+
+# Import books
+ebk import add book.pdf
+ebk import folder ~/Downloads/books/
+ebk import calibre ~/Calibre\ Library/
+ebk import isbn 978-0134685991
+
+# Export library
+ebk export json -o library.json
+ebk export csv -o library.csv
+ebk export opds -o catalog.xml --copy-files
+ebk export goodreads -o goodreads.csv
+ebk export calibre -o calibre.csv
+
+# Book operations
+ebk book info 42
+ebk book read 42 --text
+ebk book rate 42 --rating 5
+ebk book tag 42 --add "Work/Project-2024"
+ebk book purge ~/library --no-files --execute
+
+# Interactive
+ebk shell                    # VFS shell
+ebk serve                    # Web server
+```
+
+## Command Groups
+
+| Command | Purpose |
+|---------|---------|
+| `ebk lib` | Library management (init, migrate, backup, restore, check) |
+| `ebk query` | Query and discovery (search, list, stats, sql) |
+| `ebk import` | Import books (add, folder, calibre, isbn, opds, url) |
+| `ebk export` | Export library (json, csv, html, opds, goodreads, calibre) |
+| `ebk book` | Book operations (info, read, rate, favorite, tag, purge, merge) |
+| `ebk note` | Manage annotations (add, list, extract, export) |
+| `ebk tag` | Manage hierarchical tags (list, tree, add, remove, rename) |
+| `ebk queue` | Reading queue (list, add, remove, move, next) |
+| `ebk view` | Named library subsets (create, list, show, delete, edit) |
+| `ebk skill` | Claude Code skill management |
+
+## Search Syntax
+
+ebk supports advanced query syntax:
+
+```bash
+# Field-specific search
+ebk query search "title:Python author:Knuth"
+
+# Boolean operators
+ebk query search "python AND programming"
+ebk query search "python OR ruby"
+ebk query search "NOT java"
+
+# Exact phrases
+ebk query search '"machine learning"'
+
+# Comparisons
+ebk query search "rating:>=4"
+ebk query search "pages:>500"
+```
+
+## VFS Shell
+
+`ebk shell` provides filesystem-like navigation:
+
+```
+/                          # Root
+/books/{id}/              # Book by ID
+/books/{id}/title         # Title as text
+/books/{id}/authors       # Authors list
+/books/{id}/metadata      # Full JSON metadata
+/books/{id}/files/        # Ebook files
+/books/{id}/similar/      # Similar books
+/authors/{name}/          # Browse by author
+/subjects/{subject}/      # Browse by subject
+/tags/{hierarchy}/        # Hierarchical tags
+```
+
+Shell commands: `ls`, `cd`, `cat`, `find`, `grep`, `ln`, `mv`, `rm`, `mkdir`
+
+Supports piping: `ls /books/ | grep Python | head 10`
+
+## Python API
+
+```python
+from ebk.library_db import Library
+
+# Open library
+lib = Library.open("~/my-library")
+
+# Fluent query API
+results = (lib.query()
+    .filter_by_author("Knuth")
+    .filter_by_language("en")
+    .order_by("title")
+    .limit(20)
+    .all())
+
+# Search
+books = lib.search("python programming", limit=10)
+
+# Get book
+book = lib.get_book(42)
+print(book.title, book.authors)
+
+lib.close()
+```
+
+## Configuration
+
+Config file: `~/.config/ebk/config.json`
+
+```bash
+ebk config --library-path ~/my-library    # Set default library
+ebk config --llm-provider ollama          # Set LLM provider
+ebk config --show                         # Show current config
+```
+
+## Database Schema
+
+Core tables: `books`, `authors`, `subjects`, `files`, `covers`, `tags`, `personal_metadata`, `annotations`, `books_fts` (FTS5)
+
+Library directory structure:
+```
+library/
+├── library.db          # SQLite database
+├── files/              # Hash-prefixed ebook storage
+└── covers/
+    └── thumbnails/     # Cover images
+```
+
+## Views DSL
+
+Views are named, composable library subsets:
+
+```yaml
+name: unread-python
+description: Unread Python books
+filter:
+  reading_status: unread
+  subjects:
+    any: ["Python", "Programming"]
+sort: added desc
+limit: 50
+```
+
+```bash
+ebk view create unread-python --filter "reading_status:unread" --filter "subject:Python"
+ebk query list --view unread-python
+```
+
+## Tips
+
+1. Use `ebk config --library-path` to set a default library
+2. `ebk shell` for interactive exploration
+3. `ebk query sql` for complex custom queries
+4. `ebk export opds` for Android reader compatibility
+5. Tags are hierarchical: `Work/Project-2024/Research`

ebk/skills/__init__.py

@@ -0,0 +1 @@
+# Claude Code skill data for ebk

ebk/vfs/__init__.py

@@ -0,0 +1,101 @@
+"""Virtual File System for navigating the library database.
+
+The VFS provides a filesystem-like interface for browsing and interacting
+with the ebook library. It maps database entities to a hierarchical structure
+that can be navigated with familiar shell commands.
+
+Architecture:
+
+    ```
+    /                           # Root (RootNode)
+    ├── books/                  # All books (BooksDirectoryNode)
+    │   ├── 1/                 # Book 1 (BookNode)
+    │   │   ├── title          # Metadata file (TitleFileNode)
+    │   │   ├── authors        # Metadata file (AuthorsFileNode)
+    │   │   ├── description    # Metadata file
+    │   │   ├── text           # Extracted text (TextFileNode)
+    │   │   ├── files/         # Physical files (FilesDirectoryNode)
+    │   │   │   ├── book.pdf
+    │   │   │   └── book.epub
+    │   │   ├── similar/       # Similar books (SimilarDirectoryNode)
+    │   │   ├── annotations/   # User annotations
+    │   │   └── covers/        # Cover images
+    │   └── 2/
+    ├── authors/               # Browse by author (AuthorsDirectoryNode)
+    │   └── knuth-donald/      # Books by this author
+    ├── subjects/              # Browse by subject
+    └── series/                # Browse by series
+    ```
+
+Node Types:
+
+    - Node: Base class for all VFS entries
+    - DirectoryNode: Can contain children (cd into them)
+    - FileNode: Leaf nodes with content (cat them)
+    - VirtualNode: Dynamically computed (e.g., /books/, /similar/)
+    - SymlinkNode: Links to other nodes
+
+Path Resolution:
+
+    The PathResolver handles navigation:
+    - Absolute paths: /books/42/title
+    - Relative paths: ../other, ./files
+    - Special: ., .., ~ (home = /)
+    - Symlink following
+    - Tab completion support
+
+Usage Example:
+
+    ```python
+    from ebk.library_db import Library
+    from ebk.vfs import LibraryVFS
+
+    # Create VFS for a library
+    lib = Library.open("/path/to/library")
+    vfs = LibraryVFS(lib)
+
+    # Navigate
+    root = vfs.root
+    books_dir = vfs.resolver.resolve("/books", root)
+    book_node = vfs.resolver.resolve("/books/42", root)
+
+    # List children
+    children = books_dir.list_children()  # All books
+    for child in children:
+        print(child.name, child.get_info())
+
+    # Read file content
+    title_node = vfs.resolver.resolve("/books/42/title", root)
+    if isinstance(title_node, FileNode):
+        content = title_node.read_content()
+        print(content)
+    ```
+"""
+
+from ebk.vfs.base import (
+    Node,
+    DirectoryNode,
+    FileNode,
+    VirtualNode,
+    SymlinkNode,
+    NodeType,
+)
+from ebk.vfs.resolver import PathResolver, PathError, NotADirectoryError, NotFoundError
+from ebk.vfs.library_vfs import LibraryVFS
+
+__all__ = [
+    # Main entry point
+    "LibraryVFS",
+    # Core classes
+    "Node",
+    "DirectoryNode",
+    "FileNode",
+    "VirtualNode",
+    "SymlinkNode",
+    "NodeType",
+    # Path resolution
+    "PathResolver",
+    "PathError",
+    "NotADirectoryError",
+    "NotFoundError",
+]

ebk/vfs/base.py

@@ -0,0 +1,298 @@
+"""Base classes for the Virtual File System.
+
+The VFS maps the library database to a filesystem-like structure
+that can be navigated with shell commands (cd, ls, cat, etc.).
+
+Architecture:
+    - Node: Base class for all VFS nodes
+    - DirectoryNode: Nodes that can contain children (cd into them)
+    - FileNode: Leaf nodes with content (cat them)
+    - VirtualNode: Dynamically computed nodes (e.g., similar books)
+"""
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Dict, List, Optional, Any
+
+
+class NodeType(Enum):
+    """Type of VFS node."""
+    DIRECTORY = "directory"
+    FILE = "file"
+    VIRTUAL = "virtual"
+    SYMLINK = "symlink"
+
+
+class Node(ABC):
+    """Base class for all VFS nodes.
+
+    A Node represents an entry in the virtual filesystem. It can be
+    a directory (navigable), a file (readable), or something virtual
+    (dynamically computed).
+
+    Attributes:
+        name: The name of this node (e.g., "title", "books", "42")
+        parent: Parent directory node (None for root)
+        node_type: Type of node (directory, file, virtual, symlink)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: Optional['DirectoryNode'] = None,
+        node_type: NodeType = NodeType.FILE,
+    ):
+        """Initialize a VFS node.
+
+        Args:
+            name: Name of this node
+            parent: Parent directory (None for root)
+            node_type: Type of node
+        """
+        self.name = name
+        self.parent = parent
+        self.node_type = node_type
+
+    @abstractmethod
+    def get_info(self) -> Dict[str, Any]:
+        """Get metadata about this node for display.
+
+        Returns:
+            Dict with keys like: size, modified, type, description
+        """
+        pass
+
+    def get_path(self) -> str:
+        """Get absolute path to this node.
+
+        Returns:
+            Path like /books/42/title
+        """
+        if self.parent is None:
+            return "/"
+
+        parts = []
+        node = self
+        while node.parent is not None:
+            parts.append(node.name)
+            node = node.parent
+
+        if not parts:
+            return "/"
+
+        return "/" + "/".join(reversed(parts))
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name='{self.name}', path='{self.get_path()}')"
+
+
+class DirectoryNode(Node):
+    """A directory node that can contain children.
+
+    Directory nodes can be navigated into with `cd` and their
+    children can be listed with `ls`.
+
+    Children can be:
+    - Static: Fixed set of children
+    - Dynamic: Children computed on-demand (e.g., book list from DB)
+    """
+
+    def __init__(self, name: str, parent: Optional['DirectoryNode'] = None):
+        """Initialize a directory node.
+
+        Args:
+            name: Name of this directory
+            parent: Parent directory
+        """
+        super().__init__(name, parent, NodeType.DIRECTORY)
+        self._children: Dict[str, Node] = {}
+
+    @abstractmethod
+    def list_children(self) -> List[Node]:
+        """List all children of this directory.
+
+        This may compute children dynamically from the database.
+
+        Returns:
+            List of child nodes
+        """
+        pass
+
+    @abstractmethod
+    def get_child(self, name: str) -> Optional[Node]:
+        """Get a child node by name.
+
+        Args:
+            name: Name of child node
+
+        Returns:
+            Child node or None if not found
+        """
+        pass
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get directory metadata.
+
+        Returns:
+            Dict with directory information
+        """
+        children = self.list_children()
+        return {
+            "type": "directory",
+            "name": self.name,
+            "children_count": len(children),
+            "path": self.get_path(),
+        }
+
+
+class FileNode(Node):
+    """A file node with readable content.
+
+    File nodes represent data that can be read with `cat`.
+    Examples: book title, description, full text, etc.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: Optional[DirectoryNode] = None,
+        size: Optional[int] = None,
+    ):
+        """Initialize a file node.
+
+        Args:
+            name: Name of this file
+            parent: Parent directory
+            size: Size in bytes (if known)
+        """
+        super().__init__(name, parent, NodeType.FILE)
+        self._size = size
+
+    @abstractmethod
+    def read_content(self) -> str:
+        """Read the content of this file.
+
+        Returns:
+            File content as string
+        """
+        pass
+
+    def write_content(self, content: str) -> None:
+        """Write content to this file.
+
+        Args:
+            content: Content to write
+
+        Raises:
+            NotImplementedError: If the file is read-only
+        """
+        raise NotImplementedError(f"File '{self.name}' is read-only")
+
+    def is_writable(self) -> bool:
+        """Check if this file is writable.
+
+        Returns:
+            True if file supports writing, False otherwise
+        """
+        # By default, files are read-only unless they override write_content
+        try:
+            # Try calling write_content with empty string to see if it raises NotImplementedError
+            # This is a bit hacky but works
+            return hasattr(self.__class__, 'write_content') and \
+                   self.__class__.write_content != FileNode.write_content
+        except Exception:
+            return False
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get file metadata.
+
+        Returns:
+            Dict with file information
+        """
+        return {
+            "type": "file",
+            "name": self.name,
+            "size": self._size,
+            "path": self.get_path(),
+            "writable": self.is_writable(),
+        }
+
+
+class VirtualNode(DirectoryNode):
+    """A virtual directory with dynamically computed children.
+
+    Virtual nodes don't have a fixed set of children - they compute
+    them on-demand from the database or other sources.
+
+    Examples:
+    - /books/ - Lists all books from DB
+    - /books/42/similar/ - Computes similar books on-demand
+    - /authors/ - Lists all authors from DB
+    """
+
+    def __init__(self, name: str, parent: Optional[DirectoryNode] = None):
+        """Initialize a virtual directory node.
+
+        Args:
+            name: Name of this directory
+            parent: Parent directory
+        """
+        super().__init__(name, parent)
+        self.node_type = NodeType.VIRTUAL
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get virtual directory metadata.
+
+        Returns:
+            Dict with virtual directory information
+        """
+        info = super().get_info()
+        info["type"] = "virtual"
+        return info
+
+
+class SymlinkNode(Node):
+    """A symbolic link pointing to another node.
+
+    Used for creating convenient shortcuts, like similar books
+    appearing as links in /books/42/similar/.
+
+    Attributes:
+        target_path: Path to the target node
+        metadata: Optional metadata dict to include in get_info()
+    """
+
+    def __init__(
+        self,
+        name: str,
+        target_path: str,
+        parent: Optional[DirectoryNode] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize a symlink node.
+
+        Args:
+            name: Name of this symlink
+            target_path: Path to target node
+            parent: Parent directory
+            metadata: Optional metadata to include in get_info()
+        """
+        super().__init__(name, parent, NodeType.SYMLINK)
+        self.target_path = target_path
+        self.metadata = metadata or {}
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get symlink metadata.
+
+        Returns:
+            Dict with symlink information plus any provided metadata
+        """
+        info = {
+            "type": "symlink",
+            "name": self.name,
+            "target": self.target_path,
+            "path": self.get_path(),
+        }
+        # Merge in any provided metadata
+        info.update(self.metadata)
+        return info

ebk/vfs/library_vfs.py

@@ -0,0 +1,122 @@
+"""Main LibraryVFS class - entry point for VFS access."""
+
+from ebk.library_db import Library
+from ebk.vfs.base import DirectoryNode, Node
+from ebk.vfs.resolver import PathResolver
+from ebk.vfs.nodes import RootNode
+
+
+class LibraryVFS:
+    """Virtual File System for a library.
+
+    This is the main entry point for accessing the VFS. It creates
+    the root node and provides a resolver for path navigation.
+
+    Usage:
+        >>> lib = Library.open("/path/to/library")
+        >>> vfs = LibraryVFS(lib)
+        >>>
+        >>> # Navigate using resolver
+        >>> books_dir = vfs.resolver.resolve("/books", vfs.root)
+        >>> book_node = vfs.resolver.resolve("/books/42", vfs.root)
+        >>>
+        >>> # List children
+        >>> children = books_dir.list_children()
+        >>>
+        >>> # Read file content
+        >>> title_node = vfs.resolver.resolve("/books/42/title", vfs.root)
+        >>> if isinstance(title_node, FileNode):
+        >>>     print(title_node.read_content())
+    """
+
+    def __init__(self, library: Library):
+        """Initialize VFS for a library.
+
+        Args:
+            library: Library instance
+        """
+        self.library = library
+        self.root = RootNode(library)
+        self.resolver = PathResolver(self.root)
+        self.current = self.root  # Current working directory
+
+    def cd(self, path: str) -> bool:
+        """Change current directory.
+
+        Args:
+            path: Path to navigate to
+
+        Returns:
+            True if successful, False otherwise
+        """
+        new_dir = self.resolver.resolve_directory(path, self.current)
+        if new_dir is None:
+            return False
+
+        self.current = new_dir
+        return True
+
+    def pwd(self) -> str:
+        """Get current working directory path.
+
+        Returns:
+            Current path
+        """
+        return self.current.get_path()
+
+    def ls(self, path: str = ".") -> list:
+        """List children of a directory.
+
+        Args:
+            path: Path to list (default: current directory)
+
+        Returns:
+            List of nodes
+        """
+        node = self.resolver.resolve(path, self.current)
+        if node is None or not isinstance(node, DirectoryNode):
+            return []
+
+        return node.list_children()
+
+    def cat(self, path: str) -> str:
+        """Read content of a file node.
+
+        Args:
+            path: Path to file
+
+        Returns:
+            File content or error message
+        """
+        from ebk.vfs.base import FileNode
+
+        node = self.resolver.resolve(path, self.current)
+        if node is None:
+            return f"cat: {path}: No such file or directory"
+
+        if not isinstance(node, FileNode):
+            return f"cat: {path}: Is a directory"
+
+        return node.read_content()
+
+    def get_node(self, path: str) -> Node:
+        """Resolve a path to a node.
+
+        Args:
+            path: Path to resolve
+
+        Returns:
+            Resolved node or None
+        """
+        return self.resolver.resolve(path, self.current)
+
+    def complete(self, partial: str) -> list:
+        """Get tab completion candidates.
+
+        Args:
+            partial: Partial path
+
+        Returns:
+            List of completion candidates
+        """
+        return self.resolver.complete_path(partial, self.current)