exist-shell 0.1.0__py3-none-any.whl

exist_shell/client/_permissions.py

@@ -0,0 +1,172 @@
+"""Permissions mixin — ownership and mode operations."""
+
+import xml.etree.ElementTree as ET
+
+from exist_shell.client._queries import QueryMixin
+from exist_shell.utils import xq_escape
+
+
+def _mode_str_to_int(mode_str: str) -> int:
+    """Convert a POSIX mode string to an integer mode value.
+
+    Handles 9-character strings (``"rwxr-xr-x"``) as well as 10-character
+    strings with a leading type character (``"drwxr-xr-x"``).  Special bits
+    (setuid ``s/S``, setgid ``s/S``, sticky ``t/T``) are decoded correctly.
+
+    Args:
+        mode_str: Mode string to convert.
+
+    Returns:
+        Integer mode value (0–0o7777).
+    """
+    if len(mode_str) >= 10:
+        mode_str = mode_str[1:]
+    if len(mode_str) < 9:
+        return 0
+    mode_str = mode_str[:9]
+    value = 0
+    # user
+    if mode_str[0] == "r":
+        value |= 0o400
+    if mode_str[1] == "w":
+        value |= 0o200
+    if mode_str[2] in ("x", "s"):
+        value |= 0o100
+    if mode_str[2] in ("s", "S"):
+        value |= 0o4000
+    # group
+    if mode_str[3] == "r":
+        value |= 0o040
+    if mode_str[4] == "w":
+        value |= 0o020
+    if mode_str[5] in ("x", "s"):
+        value |= 0o010
+    if mode_str[5] in ("s", "S"):
+        value |= 0o2000
+    # other
+    if mode_str[6] == "r":
+        value |= 0o004
+    if mode_str[7] == "w":
+        value |= 0o002
+    if mode_str[8] in ("x", "t"):
+        value |= 0o001
+    if mode_str[8] in ("t", "T"):
+        value |= 0o1000
+    return value
+
+
+def _int_to_mode_str(mode: int) -> str:
+    """Convert an integer mode value to a 9-character POSIX mode string.
+
+    Args:
+        mode: Integer mode value (0–0o7777).
+
+    Returns:
+        9-character string like ``"rwxr-xr-x"``.
+    """
+    chars: list[str] = []
+    # user
+    chars.append("r" if mode & 0o400 else "-")
+    chars.append("w" if mode & 0o200 else "-")
+    if mode & 0o4000:
+        chars.append("s" if mode & 0o100 else "S")
+    else:
+        chars.append("x" if mode & 0o100 else "-")
+    # group
+    chars.append("r" if mode & 0o040 else "-")
+    chars.append("w" if mode & 0o020 else "-")
+    if mode & 0o2000:
+        chars.append("s" if mode & 0o010 else "S")
+    else:
+        chars.append("x" if mode & 0o010 else "-")
+    # other
+    chars.append("r" if mode & 0o004 else "-")
+    chars.append("w" if mode & 0o002 else "-")
+    if mode & 0o1000:
+        chars.append("t" if mode & 0o001 else "T")
+    else:
+        chars.append("x" if mode & 0o001 else "-")
+    return "".join(chars)
+
+
+class PermissionMixin(QueryMixin):
+    """Mixin providing ownership and mode operations against the eXist REST API."""
+
+    def chown_resource(self, path: str, owner: str | None, group: str | None) -> None:
+        """Change the owner and/or group of a document or collection.
+
+        Validates that the specified owner and group exist on the server before
+        applying the change, in a single round-trip.  Either ``owner`` or
+        ``group`` (or both) must be non-``None``.
+
+        Args:
+            path: Full eXist path starting with ``/db/``.
+            owner: New owner username, or ``None`` to leave unchanged.
+            group: New group name, or ``None`` to leave unchanged.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the user or group does not exist, the path is
+                not found, permission is denied, or the query otherwise fails.
+        """
+        safe_path = xq_escape(path)
+        validation: list[str] = []
+        changes: list[str] = []
+
+        if owner:
+            s = xq_escape(owner)
+            validation.append(
+                f'if (not(sm:user-exists("{s}"))) then error((), "User not found: {s}") else ()'
+            )
+            changes.append(f'sm:chown(xs:anyURI("{safe_path}"), "{s}")')
+
+        if group:
+            s = xq_escape(group)
+            validation.append(
+                f'if (not(sm:group-exists("{s}"))) then error((), "Group not found: {s}") else ()'
+            )
+            changes.append(f'sm:chgrp(xs:anyURI("{safe_path}"), "{s}")')
+
+        clauses = validation + changes
+        query = 'xquery version "3.1"; (' + ", ".join(clauses) + ", ())"
+        self.execute_query(query)
+
+    def get_permissions(self, path: str) -> int:
+        """Return the POSIX mode bits for a document or collection as an integer.
+
+        Args:
+            path: Full eXist path starting with ``/db/``.
+
+        Returns:
+            Integer mode value (0–0o7777).
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the path does not exist or the query fails.
+        """
+        safe_path = xq_escape(path)
+        query = f'xquery version "3.1"; sm:get-permissions(xs:anyURI("{safe_path}"))'
+        raw = self.execute_query(query)
+        el = ET.fromstring(raw)
+        mode_str = el.get("mode", "---------")
+        return _mode_str_to_int(mode_str)
+
+    def chmod_resource(self, path: str, mode: int) -> None:
+        """Change the POSIX mode of a document or collection.
+
+        Args:
+            path: Full eXist path starting with ``/db/``.
+            mode: New mode as an integer (0–0o7777).
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the path does not exist, permission is denied,
+                or the query otherwise fails.
+        """
+        safe_path = xq_escape(path)
+        mode_str = _int_to_mode_str(mode)
+        query = f'xquery version "3.1"; sm:chmod(xs:anyURI("{safe_path}"), "{mode_str}")'
+        self.execute_query(query)

exist_shell/client/_queries.py

@@ -0,0 +1,37 @@
+"""Query mixin — XQuery execution."""
+
+import httpx
+
+from exist_shell.client._base import ExistClientBase
+from exist_shell.exceptions import ExistAuthError, ExistConnectionError, ExistQueryError
+
+
+class QueryMixin(ExistClientBase):
+    """Mixin providing XQuery execution against the eXist REST API."""
+
+    def execute_query(self, query: str, context: str = "/db") -> str:
+        """Execute an XQuery string and return the raw response body.
+
+        Args:
+            query: XQuery source code to execute.
+            context: The eXist collection path used as the query context.
+
+        Returns:
+            Raw response text from the server.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the server returns HTTP 400 or 500 (query error).
+        """
+        url = self._url(context)
+        try:
+            r = self._http.post(url, data={"_query": query, "_wrap": "no"})
+        except httpx.RequestError as e:
+            raise ExistConnectionError(url, e) from e
+        if r.status_code == 401:
+            raise ExistAuthError(url)
+        if r.status_code in (400, 500):
+            raise ExistQueryError(r.text.strip())
+        r.raise_for_status()
+        return r.text

exist_shell/client/_users.py

@@ -0,0 +1,158 @@
+"""Users mixin — user account operations."""
+
+import xml.etree.ElementTree as ET
+
+from exist_shell.client._queries import QueryMixin
+from exist_shell.models import UserEntry, UserInfo
+from exist_shell.utils import xq_escape
+
+
+class UserMixin(QueryMixin):
+    """Mixin providing user account operations against the eXist REST API."""
+
+    def list_users(self) -> list[UserEntry]:
+        """List all user accounts and their group memberships.
+
+        Returns:
+            List of UserEntry objects sorted alphabetically by username.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the XQuery fails.
+        """
+        query = (
+            'xquery version "3.1"; '
+            '<users>{ '
+            'for $u in sm:list-users() '
+            'let $groups := sm:get-user-groups($u) '
+            'order by $u '
+            'return <user name="{$u}" groups="{string-join($groups, ",")}"/> '
+            '}</users>'
+        )
+        raw = self.execute_query(query)
+        root = ET.fromstring(raw)
+        result: list[UserEntry] = []
+        for el in root.findall("user"):
+            groups_str = el.get("groups", "")
+            groups = [g for g in groups_str.split(",") if g]
+            result.append(UserEntry(username=el.get("name", ""), groups=groups))
+        return result
+
+    def get_user(self, username: str) -> UserInfo:
+        """Get detailed information about a single user account.
+
+        Args:
+            username: The account name to look up.
+
+        Returns:
+            UserInfo with the account's username, full name, group memberships,
+            and whether the account is enabled.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the user does not exist or the query fails.
+        """
+        safe = xq_escape(username)
+        query = (
+            'xquery version "3.1"; '
+            f'if (not(sm:user-exists("{safe}"))) '
+            f'then error((), "User not found: {safe}") '
+            f'else '
+            f'let $groups := sm:get-user-groups("{safe}") '
+            f'let $enabled := sm:is-account-enabled("{safe}") '
+            f'let $fullname := (sm:get-account-metadata("{safe}", xs:anyURI("http://axschema.org/namePerson")), "")[1] '
+            f'return <user '
+            f'name="{safe}" '
+            f'fullname="{{$fullname}}" '
+            f'enabled="{{$enabled}}" '
+            f'groups="{{string-join($groups, \',\')}}" />'
+        )
+        raw = self.execute_query(query)
+        el = ET.fromstring(raw)
+        groups_str = el.get("groups", "")
+        groups = [g for g in groups_str.split(",") if g]
+        return UserInfo(
+            username=el.get("name", username),
+            full_name=el.get("fullname") or None,
+            groups=groups,
+            enabled=(el.get("enabled", "true").lower() == "true"),
+        )
+
+    def user_exists(self, username: str) -> bool:
+        """Check whether a user account exists on the server.
+
+        Args:
+            username: The account name to check.
+
+        Returns:
+            True if the account exists, False otherwise.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the query fails.
+        """
+        safe = xq_escape(username)
+        query = f'xquery version "3.1"; sm:user-exists("{safe}")'
+        return self.execute_query(query).strip() == "true"
+
+    def create_user(self, username: str, password: str, groups: list[str]) -> None:
+        """Create a new user account.
+
+        The first entry in groups becomes the primary group.
+
+        Args:
+            username: The new account name.
+            password: The plaintext password.
+            groups: One or more group names; the first is the primary group.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the account already exists or the query fails.
+        """
+        safe_user = xq_escape(username)
+        safe_pass = xq_escape(password)
+        groups_xq = ", ".join(f'"{xq_escape(g)}"' for g in groups)
+        query = (
+            'xquery version "3.1"; '
+            f'sm:create-account("{safe_user}", "{safe_pass}", ({groups_xq}))'
+        )
+        self.execute_query(query)
+
+    def delete_user(self, username: str) -> None:
+        """Remove a user account from the server.
+
+        Args:
+            username: The account name to remove.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the user does not exist or the query fails.
+        """
+        safe = xq_escape(username)
+        query = f'xquery version "3.1"; sm:remove-account("{safe}")'
+        self.execute_query(query)
+
+    def change_password(self, username: str, password: str) -> None:
+        """Change the password of an existing user account.
+
+        Args:
+            username: The account name.
+            password: The new plaintext password.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the user does not exist or the query fails.
+        """
+        safe_user = xq_escape(username)
+        safe_pass = xq_escape(password)
+        query = (
+            'xquery version "3.1"; '
+            f'sm:passwd("{safe_user}", "{safe_pass}")'
+        )
+        self.execute_query(query)

exist_shell/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI subcommands for exsh."""

exist_shell/commands/cat.py

@@ -0,0 +1,51 @@
+"""cat command — print document content from an eXist collection path."""
+
+import sys
+
+import typer
+
+from exist_shell.client import ExistClient
+from exist_shell.completions import collection_target_completer
+from exist_shell.utils import handle_exist_errors, parse_target, resolve_collection
+
+_TEXT_TYPES = {"application/xml", "application/json", "application/javascript"}
+
+
+def _is_text(mime_type: str) -> bool:
+    """Return True if the MIME type should be treated as human-readable text.
+
+    Args:
+        mime_type: The MIME type string (without parameters).
+
+    Returns:
+        True if the content is printable text, False if binary.
+    """
+    return mime_type.startswith("text/") or mime_type in _TEXT_TYPES
+
+
+def cat(
+    target: str = typer.Argument(
+        help="Collection and document path: <nick>:<path>.",
+        autocompletion=collection_target_completer("resource"),
+    ),
+    raw: bool = typer.Option(False, "--raw", help="Write raw bytes to stdout even for binary content."),
+) -> None:
+    """Print the content of a document to stdout."""
+    nick, path = parse_target(target)
+    collection, server, full_path = resolve_collection(nick, path)
+
+    with handle_exist_errors(path, nick, collection.server_nick):
+        with ExistClient(server) as client:
+            result = client.get_document(full_path)
+
+    if not raw and not _is_text(result.mime_type):
+        typer.echo(
+            f"Error: '{path}' is binary ({result.mime_type}). Use --raw to write bytes to stdout.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    if raw:
+        sys.stdout.buffer.write(result.content)
+    else:
+        sys.stdout.write(result.content.decode())

exist_shell/commands/chmod.py

@@ -0,0 +1,236 @@
+"""chmod command — change POSIX permissions on a document or collection."""
+
+import re
+from collections.abc import Callable
+
+import typer
+
+from exist_shell.client import ExistClient
+from exist_shell.completions import collection_target_completer
+from exist_shell.exceptions import ExistQueryError
+from exist_shell.models import CollectionEntry
+from exist_shell.utils import handle_exist_errors, parse_target, resolve_collection
+
+# ---------------------------------------------------------------------------
+# Per-who bit tables used by the symbolic-mode parser
+# ---------------------------------------------------------------------------
+
+# Maps (who, perm_char) → the bit to set/clear
+_WHO_PERM: dict[str, dict[str, int]] = {
+    "u": {"r": 0o400, "w": 0o200, "x": 0o100, "s": 0o4000, "t": 0},
+    "g": {"r": 0o040, "w": 0o020, "x": 0o010, "s": 0o2000, "t": 0},
+    "o": {"r": 0o004, "w": 0o002, "x": 0o001, "s": 0,       "t": 0o1000},
+}
+
+# Bits to clear when applying the '=' operator for a given who
+_WHO_CLEAR: dict[str, int] = {
+    "u": 0o4700,   # setuid + user rwx
+    "g": 0o2070,   # setgid + group rwx
+    "o": 0o1007,   # sticky + other rwx
+}
+
+# ---------------------------------------------------------------------------
+# Mode parsing helpers
+# ---------------------------------------------------------------------------
+
+_OCTAL_RE = re.compile(r"0?[0-7]{1,4}$")
+_SYMBOLIC_RE = re.compile(r"[ugoa]*[+\-=][rwxst]*(,[ugoa]*[+\-=][rwxst]*)*$")
+
+# Type alias: either a resolved integer mode or a callable that maps the
+# current mode (int) to the new mode (int).
+_ModeSpec = int | Callable[[int], int]
+
+
+def _is_octal_mode(mode: str) -> bool:
+    """Return ``True`` if *mode* looks like an octal mode string.
+
+    Accepts strings of 1–4 octal digits with an optional leading ``0``
+    (e.g. ``"0755"``, ``"644"``, ``"7"``, ``"4755"``).
+
+    Args:
+        mode: The mode string from the CLI.
+
+    Returns:
+        ``True`` when the string is a valid octal mode.
+    """
+    return bool(_OCTAL_RE.match(mode))
+
+
+def _parse_octal_mode(mode: str) -> int:
+    """Parse an octal mode string to an integer.
+
+    Args:
+        mode: An octal string like ``"0755"`` or ``"644"``.
+
+    Returns:
+        Integer mode value (0–0o7777).
+    """
+    return int(mode, 8)
+
+
+def _apply_symbolic_mode(mode_str: str, current: int) -> int:
+    """Apply a symbolic mode string to a current integer mode.
+
+    Parses a comma-separated list of clauses of the form
+    ``[ugoa]*[+-=][rwxst]*``.  An empty *who* prefix is treated as ``a``
+    (all).
+
+    Args:
+        mode_str: Symbolic mode string (e.g. ``"u+x"``, ``"go-w"``,
+            ``"a=rw"``, ``"u+x,go-r"``).
+        current: Current mode as an integer.
+
+    Returns:
+        New mode as an integer.
+
+    Raises:
+        ValueError: If the mode string contains an invalid clause.
+    """
+    result = current
+    for clause in mode_str.split(","):
+        m = re.fullmatch(r"([ugoa]*)([+\-=])([rwxst]*)", clause.strip())
+        if not m:
+            raise ValueError(f"invalid symbolic mode clause: '{clause}'")
+        who_str, op, perms_str = m.groups()
+
+        # Empty who or explicit 'a' expands to all three categories.
+        whos: list[str] = list(who_str) if (who_str and who_str != "a") else ["u", "g", "o"]
+
+        # Accumulate the bits that change.
+        change_bits = 0
+        for w in whos:
+            for p in perms_str:
+                change_bits |= _WHO_PERM[w].get(p, 0)
+
+        if op == "+":
+            result |= change_bits
+        elif op == "-":
+            result &= ~change_bits
+        else:  # op == "="
+            # Clear all bits belonging to the specified who, then set new ones.
+            clear_mask = 0
+            for w in whos:
+                clear_mask |= _WHO_CLEAR[w]
+            result = (result & ~clear_mask) | change_bits
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers shared by single and recursive apply
+# ---------------------------------------------------------------------------
+
+
+def _resolve_mode(client: ExistClient, path: str, mode_spec: _ModeSpec) -> int:
+    """Return the concrete integer mode to apply at *path*.
+
+    For an integer *mode_spec* this is a no-op.  For a callable, it first
+    queries the current permissions of *path* and passes them through.
+
+    Args:
+        client: Active ExistClient.
+        path: Full eXist path to query (only used for symbolic specs).
+        mode_spec: Resolved integer or symbolic-mode callable.
+
+    Returns:
+        Integer mode to apply.
+    """
+    if not isinstance(mode_spec, int):
+        current = client.get_permissions(path)
+        return mode_spec(current)
+    return mode_spec
+
+
+def _chmod_tree(client: ExistClient, path: str, mode_spec: _ModeSpec) -> int:
+    """Recursively change permissions of a collection and all its contents.
+
+    For an octal (integer) *mode_spec* the same absolute mode is applied to
+    every item.  For a symbolic *mode_spec* the relative change is applied
+    independently to each item's current permissions.
+
+    Args:
+        client: Active ExistClient.
+        path: Full eXist path to the root collection.
+        mode_spec: Resolved integer mode or symbolic-mode callable.
+
+    Returns:
+        Total number of resources and collections whose mode was changed.
+    """
+    client.chmod_resource(path, _resolve_mode(client, path, mode_spec))
+    count = 1
+    for item in client.list_collection(path):
+        child = f"{path}/{item.name}"
+        if isinstance(item, CollectionEntry):
+            count += _chmod_tree(client, child, mode_spec)
+        else:
+            client.chmod_resource(child, _resolve_mode(client, child, mode_spec))
+            count += 1
+    return count
+
+
+# ---------------------------------------------------------------------------
+# chmod command
+# ---------------------------------------------------------------------------
+
+
+def chmod(
+    mode: str = typer.Argument(
+        help=(
+            "Permission mode: octal (e.g. '0755', '644') or symbolic "
+            "(e.g. 'u+x', 'go-w', 'a=rw', 'u+x,go-r')."
+        ),
+    ),
+    target: str = typer.Argument(
+        help="Remote path: <nick>:<path>.",
+        autocompletion=collection_target_completer("any"),
+    ),
+    recursive: bool = typer.Option(
+        False, "--recursive", "-R",
+        help="Apply recursively to all contents of a collection.",
+    ),
+) -> None:
+    """Change POSIX permissions on a document or collection.
+
+    Accepts both octal (e.g. ``0755``, ``644``) and symbolic (e.g. ``u+x``,
+    ``go-w``, ``a=rw``) mode specifications.
+
+    Raises:
+        typer.Exit: On invalid mode, unknown collection, or server error.
+    """
+    # Determine and validate the mode specification.
+    mode_spec: _ModeSpec
+    if _is_octal_mode(mode):
+        mode_spec = _parse_octal_mode(mode)
+    elif _SYMBOLIC_RE.match(mode):
+        captured = mode
+        mode_spec = lambda current, _m=captured: _apply_symbolic_mode(_m, current)
+    else:
+        typer.echo(
+            f"Error: invalid mode '{mode}'. "
+            "Use octal (e.g. '0755') or symbolic (e.g. 'u+x', 'go-w').",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    nick, path = parse_target(target, path_required=False)
+    collection, server, full_path = resolve_collection(nick, path)
+
+    try:
+        with handle_exist_errors(path, nick, collection.server_nick):
+            with ExistClient(server) as client:
+                if recursive:
+                    if not client.is_collection(full_path):
+                        typer.echo(
+                            f"Error: '{path}' is not a collection. "
+                            "Omit -R to chmod a single document.",
+                            err=True,
+                        )
+                        raise typer.Exit(1)
+                    count = _chmod_tree(client, full_path, mode_spec)
+                    typer.echo(f"Permissions of '{path}' updated ({count} items).")
+                else:
+                    client.chmod_resource(full_path, _resolve_mode(client, full_path, mode_spec))
+                    typer.echo(f"Permissions of '{path}' updated.")
+    except ExistQueryError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)