exist-shell 0.1.0__py3-none-any.whl

exist_shell/config.py

@@ -0,0 +1,233 @@
+"""Configuration models and persistence for servers and collections."""
+
+import os
+import sys
+from pathlib import Path
+
+import tomlkit
+from pydantic import BaseModel, Field, SecretStr
+
+NICK_PATTERN = r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$"
+
+if sys.platform == "win32":
+    import platformdirs
+
+    _DEFAULT_CONFIG_PATH = Path(platformdirs.user_config_dir("exsh", appauthor=False)) / "config.toml"
+    _DEFAULT_CACHE_DIR = Path(platformdirs.user_cache_dir("exsh", appauthor=False))
+else:
+    _DEFAULT_CONFIG_PATH = Path.home() / ".config" / "exsh" / "config.toml"
+    _DEFAULT_CACHE_DIR = Path.home() / ".cache" / "exsh"
+
+
+class _AppState:
+    r"""Process-level singleton that holds the active config file path.
+
+    The path is resolved in this order:
+    1. Explicitly set via ``set_config_path()`` (called by the ``--config`` flag).
+    2. ``EXSH_CONFIG`` environment variable.
+    3. Platform default: XDG (``~/.config/exsh``) on Unix, ``%APPDATA%\exsh`` on Windows.
+       XDG Base Directory Specification is a freedesktop.org standard for where
+       applications should store config, cache, and data files on Linux/macOS.
+    """
+
+    def __init__(self) -> None:
+        """Initialise with no explicit path set."""
+        self._config_path: Path | None = None
+
+    def set_config_path(self, path: Path) -> None:
+        """Override the config file path for this process.
+
+        Args:
+            path: Absolute or relative path to the config file.
+        """
+        self._config_path = path
+
+    def config_path(self) -> Path:
+        """Return the resolved config file path.
+
+        Returns:
+            Path to the configuration file.
+        """
+        if self._config_path is not None:
+            return self._config_path
+        env = os.environ.get("EXSH_CONFIG")
+        return Path(env) if env else _DEFAULT_CONFIG_PATH
+
+
+app_state = _AppState()
+
+
+class Server(BaseModel):
+    """An eXist-db server configuration."""
+
+    nick: str = Field(pattern=NICK_PATTERN)
+    host: str
+    port: int = 8080
+    user: str = "admin"
+    password: SecretStr = SecretStr("")
+
+
+class Collection(BaseModel):
+    """A named collection on an eXist-db server."""
+
+    nick: str = Field(pattern=NICK_PATTERN)
+    server_nick: str
+    name: str
+
+
+class Config(BaseModel):
+    """Full application configuration holding servers and collections."""
+
+    servers: dict[str, Server] = {}
+    collections: dict[str, Collection] = {}
+    cache_dir: Path | None = None
+
+    def resolved_cache_dir(self) -> Path:
+        """Return the active cache root directory.
+
+        Returns:
+            ``cache_dir`` from config if set, otherwise ``~/.cache/exsh``.
+        """
+        return self.cache_dir if self.cache_dir is not None else _DEFAULT_CACHE_DIR
+
+    @classmethod
+    def load(cls) -> "Config":
+        """Load configuration from disk, returning an empty config if the file is missing.
+
+        Returns:
+            The loaded Config instance.
+        """
+        path = app_state.config_path()
+        if not path.exists():
+            return cls()
+        with open(path) as f:
+            raw = tomlkit.load(f)
+        servers = {
+            nick: Server(nick=nick, **data)
+            for nick, data in raw.get("servers", {}).items()
+        }
+        collections = {
+            nick: Collection(nick=nick, **data)
+            for nick, data in raw.get("collections", {}).items()
+        }
+        cache_dir_raw = raw.get("cache_dir")
+        cache_dir = Path(cache_dir_raw) if cache_dir_raw else None
+        return cls(servers=servers, collections=collections, cache_dir=cache_dir)
+
+    def save(self) -> None:
+        """Persist the current configuration to disk atomically."""
+        path = app_state.config_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data: dict = {
+            "servers": {
+                nick: {
+                    "host": s.host,
+                    "port": s.port,
+                    "user": s.user,
+                    "password": s.password.get_secret_value(),
+                }
+                for nick, s in self.servers.items()
+            },
+            "collections": {
+                nick: {
+                    "server_nick": c.server_nick,
+                    "name": c.name,
+                }
+                for nick, c in self.collections.items()
+            },
+        }
+        if self.cache_dir is not None:
+            data["cache_dir"] = str(self.cache_dir)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(tomlkit.dumps(data))
+        tmp.rename(path)
+
+    def add_server(self, server: Server) -> None:
+        """Add a server and persist the configuration.
+
+        Args:
+            server: The server to add.
+
+        Raises:
+            ValueError: If a server with the same nick already exists.
+        """
+        if server.nick in self.servers:
+            raise ValueError(f"Server nick '{server.nick}' already exists.")
+        self.servers[server.nick] = server
+        self.save()
+
+    def add_collection(self, collection: Collection) -> None:
+        """Add a collection and persist the configuration.
+
+        Args:
+            collection: The collection to add.
+
+        Raises:
+            ValueError: If a collection with the same nick already exists.
+        """
+        if collection.nick in self.collections:
+            raise ValueError(f"Collection nick '{collection.nick}' already exists.")
+        self.collections[collection.nick] = collection
+        self.save()
+
+    def remove_collection(self, nick: str) -> None:
+        """Remove a collection and persist the configuration.
+
+        Args:
+            nick: Nickname of the collection to remove.
+
+        Raises:
+            KeyError: If no collection with that nick exists.
+        """
+        del self.collections[nick]
+        self.save()
+
+    def remove_server(self, nick: str) -> list[str]:
+        """Remove a server and all collections registered on it, then persist.
+
+        Args:
+            nick: Nickname of the server to remove.
+
+        Returns:
+            List of collection nicks that were removed as a side-effect.
+
+        Raises:
+            KeyError: If no server with that nick exists.
+        """
+        del self.servers[nick]
+        cascaded = [c for c, col in self.collections.items() if col.server_nick == nick]
+        for c in cascaded:
+            del self.collections[c]
+        self.save()
+        return cascaded
+
+    def rename_server(self, old_nick: str, new_nick: str) -> list[str]:
+        """Rename a server nick and update all collection references, then persist.
+
+        Args:
+            old_nick: Current nickname of the server.
+            new_nick: New nickname for the server.
+
+        Returns:
+            List of collection nicks whose server_nick was updated.
+
+        Raises:
+            KeyError: If no server with old_nick exists.
+            ValueError: If new_nick already exists as a server nick.
+        """
+        if new_nick in self.servers:
+            raise ValueError(f"Server nick '{new_nick}' already exists.")
+        server = self.servers[old_nick]
+        self.servers[new_nick] = Server(
+            nick=new_nick,
+            host=server.host,
+            port=server.port,
+            user=server.user,
+            password=server.password,
+        )
+        del self.servers[old_nick]
+        updated = [c for c, col in self.collections.items() if col.server_nick == old_nick]
+        for c in updated:
+            self.collections[c] = self.collections[c].model_copy(update={"server_nick": new_nick})
+        self.save()
+        return updated

exist_shell/exceptions.py

@@ -0,0 +1,68 @@
+"""Custom exceptions for eXist-db REST API errors."""
+
+
+class ExistError(Exception):
+    """Base exception for eXist-db REST API errors.
+
+    Attributes:
+        status_code: HTTP status code associated with the error, if any.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        """Initialize with a message and optional HTTP status code."""
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ExistConnectionError(ExistError):
+    """Raised when a network-level error prevents reaching the server.
+
+    Attributes:
+        url: The URL that could not be reached.
+        cause: The underlying transport exception.
+    """
+
+    def __init__(self, url: str, cause: Exception) -> None:
+        """Initialize with the target URL and the underlying cause."""
+        super().__init__(f"Cannot connect to {url}: {cause}")
+        self.url = url
+        self.cause = cause
+
+
+class ExistAuthError(ExistError):
+    """Raised when the server returns HTTP 401 Unauthorized.
+
+    Attributes:
+        url: The URL that rejected the credentials.
+    """
+
+    def __init__(self, url: str) -> None:
+        """Initialize with the URL that rejected authentication."""
+        super().__init__(f"Authentication failed for {url}", status_code=401)
+        self.url = url
+
+
+class ExistNotFoundError(ExistError):
+    """Raised when the server returns HTTP 404 Not Found.
+
+    Attributes:
+        path: The eXist path that was not found.
+    """
+
+    def __init__(self, path: str) -> None:
+        """Initialize with the path that was not found."""
+        super().__init__(f"Not found: {path}", status_code=404)
+        self.path = path
+
+
+class ExistQueryError(ExistError):
+    """Raised when the server rejects or fails to execute an XQuery.
+
+    Attributes:
+        detail: The error detail returned by the server.
+    """
+
+    def __init__(self, detail: str) -> None:
+        """Initialize with the server-provided error detail."""
+        super().__init__(f"XQuery error: {detail}")
+        self.detail = detail

exist_shell/main.py

@@ -0,0 +1,64 @@
+"""Entry point and top-level CLI app for exsh."""
+
+from pathlib import Path
+
+import typer
+
+from exist_shell import __version__
+from exist_shell.commands import collection, group, server, user
+from exist_shell.config import app_state
+from exist_shell.commands.cat import cat
+from exist_shell.commands.chmod import chmod
+from exist_shell.commands.chown import chown
+from exist_shell.commands.exec import exec as exec_query
+from exist_shell.commands.cp import cp
+from exist_shell.commands.mkdir import mkdir
+from exist_shell.commands.mv import mv
+from exist_shell.commands.edit import edit
+from exist_shell.commands.ls import ls
+from exist_shell.commands.put import put
+from exist_shell.commands.rm import rm
+from exist_shell.commands.sync import sync
+
+app = typer.Typer(
+    name="exsh",
+    help="eXist-db shell — interact with eXist-db via REST",
+    no_args_is_help=True,
+)
+
+app.add_typer(server.app, name="server", help="Manage servers.")
+app.add_typer(collection.app, name="collection", help="Manage collections.")
+app.add_typer(user.app, name="user", help="Manage users.")
+app.add_typer(group.app, name="group", help="Manage groups.")
+app.command("ls", help="List contents of a collection path.")(ls)
+app.command("chown", help="Change the owner and/or group of a document or collection.")(chown)
+app.command("chmod", help="Change POSIX permissions of a document or collection.")(chmod)
+app.command("cat", help="Print document content to stdout.")(cat)
+app.command("put", help="Upload a document to a collection path.")(put)
+app.command("edit", help="Edit a document in $VISUAL/$EDITOR and re-upload if changed.")(edit)
+app.command("cp", help="Copy a document between local paths and remote collections.")(cp)
+app.command("mv", help="Move or rename a document or collection on the server.")(mv)
+app.command("rm", help="Delete one or more documents from a collection path.")(rm)
+app.command("mkdir", help="Create a collection at a path inside a registered collection.")(mkdir)
+app.command("sync", help="Sync a local folder and a remote collection.")(sync)
+app.command("exec", help="Execute an XQuery script on an eXist-db server.")(exec_query)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"exsh {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(False, "--version", callback=_version_callback, is_eager=True, help="Show version and exit."),
+    config: Path | None = typer.Option(None, "--config", help="Path to config file (overrides EXSH_CONFIG env var and default)."),
+) -> None:
+    """eXist-db shell — interact with eXist-db via REST."""
+    if config is not None:
+        app_state.set_config_path(config)
+
+
+if __name__ == "__main__":
+    app()

exist_shell/models.py

@@ -0,0 +1,61 @@
+"""Pydantic models for eXist-db REST API responses."""
+
+from typing import NamedTuple
+
+from pydantic import BaseModel
+
+
+class CollectionEntry(BaseModel):
+    """A subcollection entry returned by the eXist-db REST API."""
+
+    name: str
+    created: str | None = None
+    owner: str | None = None
+    group: str | None = None
+    permissions: str | None = None
+
+
+class ResourceEntry(BaseModel):
+    """A document resource entry returned by the eXist-db REST API."""
+
+    name: str
+    created: str | None = None
+    last_modified: str | None = None
+    owner: str | None = None
+    group: str | None = None
+    permissions: str | None = None
+    size: int | None = None
+    mime_type: str | None = None
+
+
+CollectionItem = CollectionEntry | ResourceEntry
+
+
+class DocumentResult(NamedTuple):
+    """A retrieved document's raw content and declared MIME type."""
+
+    content: bytes
+    mime_type: str
+
+
+class GroupEntry(BaseModel):
+    """A group entry with name and member list."""
+
+    name: str
+    members: list[str]
+
+
+class UserEntry(BaseModel):
+    """A user entry with username and groups."""
+
+    username: str
+    groups: list[str]
+
+
+class UserInfo(BaseModel):
+    """Detailed user account information."""
+
+    username: str
+    full_name: str | None = None
+    groups: list[str] = []
+    enabled: bool = True

exist_shell/utils.py

@@ -0,0 +1,179 @@
+"""Shared utilities for exist-shell commands."""
+
+import mimetypes
+import xml.etree.ElementTree as ET
+from contextlib import contextmanager
+from collections.abc import Generator
+from pathlib import Path
+
+import typer
+
+from exist_shell.config import Collection, Config, Server
+from exist_shell.exceptions import ExistAuthError, ExistConnectionError, ExistNotFoundError
+
+
+def xq_escape(value: str) -> str:
+    """Escape a string for safe embedding in an XQuery double-quoted string literal.
+
+    Doubles every ``"`` character so the value can be placed directly
+    between XQuery double-quote delimiters without ending the literal early.
+
+    Args:
+        value: The raw string to embed in an XQuery double-quoted string.
+
+    Returns:
+        The string with every double-quote character doubled.
+    """
+    return value.replace('"', '""')
+
+
+def is_remote(target: str) -> bool:
+    """Return True if target uses the ``nick:path`` remote syntax.
+
+    Args:
+        target: Raw argument string from the CLI.
+
+    Returns:
+        True if the string contains ``:``, indicating a remote path.
+    """
+    return ":" in target
+
+
+def parse_user_at_server(value: str) -> tuple[str, str | None]:
+    """Split a ``user@server`` argument into a (username, server_nick) pair.
+
+    Args:
+        value: Raw argument from the CLI, e.g. ``alice@prod``, ``alice``, or ``@prod``.
+
+    Returns:
+        A tuple ``(username, server_nick)`` where ``server_nick`` is ``None``
+        if no ``@`` suffix was present, and ``username`` is empty for bare
+        ``@server`` forms.
+    """
+    if "@" in value:
+        username, _, server = value.rpartition("@")
+        return username, server if server else None
+    return value, None
+
+
+def guess_mime(path: Path, default: str = "application/octet-stream") -> str:
+    """Guess the MIME type of a file from its extension.
+
+    Args:
+        path: Local file path.
+        default: MIME type to return when the extension is unknown.
+
+    Returns:
+        Guessed MIME type string, or ``default`` if the extension is unrecognised.
+    """
+    guessed, _ = mimetypes.guess_type(str(path))
+    return guessed or default
+
+
+def check_xml_wellformed(content: bytes, mime: str) -> str | None:
+    """Return an error message if content is malformed XML, or None if valid or not XML.
+
+    Only inspects content when the MIME type is an XML type (``application/xml``,
+    ``text/xml``, or any type ending in ``+xml``).
+
+    Args:
+        content: Raw bytes to check.
+        mime: MIME type of the content.
+
+    Returns:
+        None if the content passes the check or is not an XML MIME type; an
+        error message string if the XML is malformed.
+    """
+    if mime != "application/xml" and mime != "text/xml" and not mime.endswith("+xml"):
+        return None
+    try:
+        ET.fromstring(content)
+    except ET.ParseError as e:
+        return str(e)
+    return None
+
+
+def validate_path(path: str) -> None:
+    """Reject paths that contain traversal sequences or null bytes.
+
+    Args:
+        path: The eXist path to validate (e.g. /subdir/doc.xml).
+
+    Raises:
+        ValueError: If the path contains ``..``, ``.``, or null bytes.
+    """
+    if "\x00" in path:
+        raise ValueError("path contains null bytes")
+    for segment in path.split("/"):
+        if segment in ("..", "."):
+            raise ValueError(f"path traversal not allowed: '{segment}' segment")
+
+
+def parse_target(target: str, *, path_required: bool = True) -> tuple[str, str]:
+    """Parse and validate a ``<nick>:<path>`` target argument.
+
+    Args:
+        target: Raw argument string from the CLI (e.g. ``myapp:/docs/file.xml``).
+        path_required: If True, exit with an error when no path is given.
+            If False, default the path to ``/`` (used by ``ls``).
+
+    Returns:
+        Tuple of ``(nick, normalized_path)`` where path starts with ``/``.
+    """
+    nick, _, path = target.partition(":")
+    if not path:
+        if path_required:
+            typer.echo("Error: path is required (use <nick>:<path>).", err=True)
+            raise typer.Exit(1)
+        path = "/"
+    if not path.startswith("/"):
+        path = "/" + path
+    try:
+        validate_path(path)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    return nick, path
+
+
+def resolve_collection(nick: str, path: str) -> tuple[Collection, Server, str]:
+    """Look up a collection by nick and compute the full eXist path.
+
+    Args:
+        nick: The collection nickname from the CLI argument.
+        path: The validated path component (starts with ``/``).
+
+    Returns:
+        Tuple of ``(collection, server, full_path)`` where ``full_path``
+        starts with ``/db/``.
+    """
+    config = Config.load()
+    if nick not in config.collections:
+        typer.echo(f"Error: collection '{nick}' not found.", err=True)
+        raise typer.Exit(1)
+    collection = config.collections[nick]
+    server = config.servers[collection.server_nick]
+    full_path = f"/db/{collection.name}{path}"
+    return collection, server, full_path
+
+
+@contextmanager
+def handle_exist_errors(path: str, nick: str, server_nick: str) -> Generator[None, None, None]:
+    """Context manager that catches eXist client errors and exits cleanly.
+
+    Args:
+        path: The path being accessed (used in error messages).
+        nick: The collection nick (used in error messages).
+        server_nick: The server nick (used in authentication error messages).
+    """
+    try:
+        yield
+    except ExistNotFoundError:
+        typer.echo(f"Error: path '{path}' not found in collection '{nick}'.", err=True)
+        raise typer.Exit(1)
+    except ExistAuthError:
+        typer.echo(f"Error: authentication failed for server '{server_nick}'.", err=True)
+        raise typer.Exit(1)
+    except ExistConnectionError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)