exist-shell 0.1.0__py3-none-any.whl

exist_shell/commands/group.py

@@ -0,0 +1,183 @@
+"""Group management commands (ls, list, add, rm)."""
+
+import typer
+
+from exist_shell.client import ExistClient
+from exist_shell.completions import server_at_completer, server_nick_completer, user_arg_completer
+from exist_shell.config import Config
+from exist_shell.exceptions import ExistAuthError, ExistConnectionError, ExistQueryError
+from exist_shell.utils import parse_user_at_server
+
+app = typer.Typer(help="Manage eXist-db groups.", no_args_is_help=True)
+
+
+def _resolve_server(
+    config: Config,
+    inline_server: str | None,
+    flag_server: str | None,
+) -> str:
+    """Resolve the effective server nick from an inline @server and --server flag.
+
+    Args:
+        config: The loaded configuration.
+        inline_server: Server nick extracted from a ``group@server`` or ``@server``
+            argument; ``None`` if no ``@`` suffix was present.
+        flag_server: Server nick provided via the ``--server`` option; ``None``
+            if the flag was omitted.
+
+    Returns:
+        The resolved server nick, guaranteed to exist in ``config.servers``.
+
+    Raises:
+        typer.Exit: If both sources conflict, no server can be determined, or
+            the resolved nick does not exist in the configuration.
+    """
+    if not config.servers:
+        typer.echo("Error: no servers configured. Use 'exsh server add' first.", err=True)
+        raise typer.Exit(1)
+    if inline_server and flag_server:
+        typer.echo(
+            "Error: conflicting server specifications: use @server or --server, not both.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    server = inline_server or flag_server
+    if server is None:
+        if len(config.servers) != 1:
+            typer.echo(
+                "Error: --server is required when multiple servers are configured.",
+                err=True,
+            )
+            raise typer.Exit(1)
+        server = next(iter(config.servers))
+    if server not in config.servers:
+        typer.echo(f"Error: server '{server}' not found.", err=True)
+        raise typer.Exit(1)
+    return server
+
+
+@app.command("ls")
+def group_ls(
+    at_server: str | None = typer.Argument(None, metavar="@SERVER", help="Server in @nick form (e.g. @prod).", autocompletion=server_at_completer),
+    server: str | None = typer.Option(None, "--server", help="Server nick to query.", autocompletion=server_nick_completer),
+) -> None:
+    """List all groups and their members.
+
+    The server may be specified as a bare ``@nick`` positional argument
+    (e.g. ``group ls @prod``) or via ``--server``.  When omitted and only one
+    server is configured it is selected automatically.
+
+    Args:
+        at_server: Optional server nick in ``@nick`` form.
+        server: Server nick to query. Auto-selected when only one server is
+            configured; required when multiple servers are configured.
+    """
+    inline_server: str | None = None
+    if at_server is not None:
+        if not at_server.startswith("@"):
+            typer.echo("Error: positional server argument must be in @nick form (e.g. @prod).", err=True)
+            raise typer.Exit(1)
+        inline_server = at_server[1:]
+        if not inline_server:
+            typer.echo("Error: server nick cannot be empty.", err=True)
+            raise typer.Exit(1)
+
+    config = Config.load()
+    resolved = _resolve_server(config, inline_server, server)
+
+    try:
+        with ExistClient(config.servers[resolved]) as client:
+            groups = client.list_groups()
+    except ExistAuthError:
+        typer.echo(f"Error: authentication failed for server '{resolved}'.", err=True)
+        raise typer.Exit(1)
+    except ExistConnectionError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    for g in groups:
+        typer.echo(f"{g.name}\t{', '.join(g.members)}")
+
+
+@app.command("add")
+def group_add(
+    groupname: str = typer.Argument(help="Group name to create, optionally as group@server.", autocompletion=user_arg_completer),
+    server: str | None = typer.Option(None, "--server", help="Server nick to target.", autocompletion=server_nick_completer),
+) -> None:
+    """Create a new group on the server.
+
+    The group name may include an inline server nick using ``group@server``
+    syntax (e.g. ``editors@prod``).
+
+    Args:
+        groupname: The new group name, optionally suffixed with ``@server_nick``.
+        server: Server nick to target. Auto-selected when only one server is
+            configured; required when multiple servers are configured.
+    """
+    bare_groupname, inline_server = parse_user_at_server(groupname)
+    if not bare_groupname:
+        typer.echo("Error: group name cannot be empty.", err=True)
+        raise typer.Exit(1)
+
+    config = Config.load()
+    resolved = _resolve_server(config, inline_server, server)
+
+    try:
+        with ExistClient(config.servers[resolved]) as client:
+            client.create_group(bare_groupname)
+    except ExistAuthError:
+        typer.echo(f"Error: authentication failed for server '{resolved}'.", err=True)
+        raise typer.Exit(1)
+    except ExistConnectionError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except ExistQueryError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"Group '{bare_groupname}' created.")
+
+
+@app.command("rm")
+def group_rm(
+    groupname: str = typer.Argument(help="Group name to remove, optionally as group@server.", autocompletion=user_arg_completer),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    server: str | None = typer.Option(None, "--server", help="Server nick to target.", autocompletion=server_nick_completer),
+) -> None:
+    """Remove a group from the server.
+
+    The group name may include an inline server nick using ``group@server``
+    syntax (e.g. ``editors@prod``).  Prompts for confirmation unless ``--yes``
+    is supplied.
+
+    Args:
+        groupname: The group name to remove, optionally suffixed with ``@server_nick``.
+        yes: When True, skip the confirmation prompt.
+        server: Server nick to target. Auto-selected when only one server is
+            configured; required when multiple servers are configured.
+    """
+    bare_groupname, inline_server = parse_user_at_server(groupname)
+    if not bare_groupname:
+        typer.echo("Error: group name cannot be empty.", err=True)
+        raise typer.Exit(1)
+
+    config = Config.load()
+    resolved = _resolve_server(config, inline_server, server)
+
+    if not yes:
+        typer.confirm(f"Remove group '{bare_groupname}'?", abort=True)
+
+    try:
+        with ExistClient(config.servers[resolved]) as client:
+            client.delete_group(bare_groupname)
+    except ExistAuthError:
+        typer.echo(f"Error: authentication failed for server '{resolved}'.", err=True)
+        raise typer.Exit(1)
+    except ExistConnectionError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except ExistQueryError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"Group '{bare_groupname}' removed.")

exist_shell/commands/ls.py

@@ -0,0 +1,66 @@
+"""ls command — list contents of an eXist collection path."""
+
+import typer
+
+from exist_shell.client import ExistClient
+from exist_shell.completions import collection_target_completer
+from exist_shell.models import CollectionEntry, CollectionItem, ResourceEntry
+from exist_shell.utils import handle_exist_errors, parse_target, resolve_collection
+
+
+def _sort_key_time(item: CollectionItem) -> str:
+    """Return the best available timestamp for sorting."""
+    if isinstance(item, ResourceEntry):
+        return item.last_modified or item.created or ""
+    return item.created or ""
+
+
+def ls(
+    target: str = typer.Argument(
+        help="Collection and path: <nick>[:<path>].",
+        autocompletion=collection_target_completer("any"),
+    ),
+    sort: str = typer.Option("name", "--sort", "-s", help="Sort by: name, time."),
+    reverse: bool = typer.Option(False, "--reverse", "-r", help="Reverse sort order."),
+    names_only: bool = typer.Option(False, "--names-only", help="Print only names, one per line."),
+) -> None:
+    """List subcollections and resources at a collection path."""
+    nick, path = parse_target(target, path_required=False)
+    collection, server, full_path = resolve_collection(nick, path)
+
+    with handle_exist_errors(path, nick, collection.server_nick):
+        with ExistClient(server) as client:
+            items = client.list_collection(full_path)
+
+    if sort == "time":
+        items = sorted(items, key=_sort_key_time, reverse=reverse)
+    else:
+        items = sorted(items, key=lambda x: x.name, reverse=reverse)
+
+    if names_only:
+        for item in items:
+            display_name = f"{item.name}/" if isinstance(item, CollectionEntry) else item.name
+            typer.echo(display_name)
+        return
+
+    rows: list[tuple[str, str, str, str]] = []
+    for item in items:
+        display_name = f"{item.name}/" if isinstance(item, CollectionEntry) else item.name
+        if isinstance(item, CollectionEntry):
+            rows.append((display_name, item.permissions or "", item.owner or "", item.created or ""))
+        else:
+            assert isinstance(item, ResourceEntry)
+            rows.append((
+                display_name,
+                item.permissions or "",
+                item.owner or "",
+                item.last_modified or item.created or "",
+            ))
+
+    if not rows:
+        return
+
+    widths = [max(len(row[col]) for row in rows) for col in range(len(rows[0]))]
+    for row in rows:
+        padded = "  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row[:-1]))
+        typer.echo(f"{padded}  {row[-1]}")

exist_shell/commands/mkdir.py

@@ -0,0 +1,24 @@
+"""mkdir command — create a collection in eXist-db."""
+
+import typer
+
+from exist_shell.cache import invalidate
+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
+
+
+def mkdir(
+    target: str = typer.Argument(
+        help="Collection and new path: <nick>:<path>.",
+        autocompletion=collection_target_completer("collection"),
+    ),
+) -> None:
+    """Create a collection at a path inside a registered collection."""
+    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:
+            client.create_collection(full_path)
+    invalidate(nick)

exist_shell/commands/mv.py

@@ -0,0 +1,124 @@
+"""mv command — move or rename a document or collection on an eXist server."""
+
+from pathlib import PurePosixPath
+
+import typer
+
+from exist_shell.cache import invalidate
+from exist_shell.client import ExistClient
+from exist_shell.completions import collection_target_completer
+from exist_shell.models import CollectionEntry
+from exist_shell.utils import handle_exist_errors, is_remote, parse_target, resolve_collection
+
+
+def _dest_path(target_path: str, source_name: str) -> str:
+    """Resolve the destination path, appending source name when target ends with '/'.
+
+    Args:
+        target_path: The path component of the target argument.
+        source_name: Name to append when path ends with '/'.
+
+    Returns:
+        Final destination path without a trailing slash.
+    """
+    if target_path.endswith("/"):
+        return target_path.rstrip("/") + "/" + source_name
+    return target_path
+
+
+def _collect_docs(client: ExistClient, base: str, rel_prefix: str = "") -> list[tuple[str, str]]:
+    """Recursively collect all (rel_path, full_path) document pairs under base.
+
+    Args:
+        client: Active ExistClient.
+        base: Full eXist path to walk.
+        rel_prefix: Relative path prefix accumulated during recursion.
+
+    Returns:
+        List of (relative_path, full_path) tuples for every document found.
+    """
+    items = client.list_collection(base)
+    result: list[tuple[str, str]] = []
+    for item in items:
+        rel = f"{rel_prefix}/{item.name}" if rel_prefix else item.name
+        if isinstance(item, CollectionEntry):
+            result.extend(_collect_docs(client, f"{base}/{item.name}", rel))
+        else:
+            result.append((rel, f"{base}/{item.name}"))
+    return result
+
+
+def _copy_then_delete_collection(client: ExistClient, src: str, dst: str) -> None:
+    """Move a collection via REST: copy all contents first, then delete the source.
+
+    All documents and subcollections are created at the destination before any
+    deletion, so a partial failure leaves the source intact.
+
+    Args:
+        client: Active ExistClient.
+        src: Full eXist path of the source collection.
+        dst: Full eXist path of the destination collection.
+    """
+    docs = _collect_docs(client, src)
+
+    # Create destination root and any needed subcollection paths.
+    # create_collection is idempotent and handles intermediate levels.
+    client.create_collection(dst)
+    seen: set[str] = set()
+    for rel_path, _ in docs:
+        parent = str(PurePosixPath(rel_path).parent)
+        if parent != "." and parent not in seen:
+            client.create_collection(f"{dst}/{parent}")
+            seen.add(parent)
+
+    # Upload all documents (add-before-remove).
+    for rel_path, src_full_path in docs:
+        doc = client.get_document(src_full_path)
+        client.put_document(f"{dst}/{rel_path}", doc.content, doc.mime_type)
+
+    # Delete source only after all uploads succeed.
+    client.delete_collection(src)
+
+
+def mv(
+    source: str = typer.Argument(
+        help="Source remote path: <nick>:<path>.",
+        autocompletion=collection_target_completer("any"),
+    ),
+    target: str = typer.Argument(
+        help="Target remote path: <nick>:<path>. Trailing '/' moves source into that collection.",
+        autocompletion=collection_target_completer("any"),
+    ),
+) -> None:
+    """Move or rename a document or collection on the server."""
+    if not is_remote(source) or not is_remote(target):
+        typer.echo(
+            "Error: both source and target must be remote paths (nick:path).",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    src_nick, src_path = parse_target(source)
+    src_collection, src_server, src_full = resolve_collection(src_nick, src_path)
+
+    tgt_nick, tgt_path = parse_target(target)
+    resolved_dest = _dest_path(tgt_path, PurePosixPath(src_path).name)
+    tgt_collection, tgt_server, tgt_full = resolve_collection(tgt_nick, resolved_dest)
+
+    if src_server.host != tgt_server.host or src_server.port != tgt_server.port:
+        typer.echo(
+            "Error: cross-server mv is not supported. Use cp + rm instead.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    with handle_exist_errors(src_path, src_nick, src_collection.server_nick):
+        with ExistClient(src_server) as client:
+            if client.is_collection(src_full):
+                _copy_then_delete_collection(client, src_full, tgt_full)
+            else:
+                client.move_document(src_full, tgt_full)
+
+    invalidate(src_nick)
+    if tgt_nick != src_nick:
+        invalidate(tgt_nick)

exist_shell/commands/put.py

@@ -0,0 +1,63 @@
+"""put command — upload a document to an eXist collection path."""
+
+import sys
+from pathlib import Path
+
+import typer
+
+from exist_shell.cache import invalidate
+from exist_shell.client import ExistClient
+from exist_shell.completions import collection_target_completer
+from exist_shell.utils import check_xml_wellformed, guess_mime, handle_exist_errors, parse_target, resolve_collection
+
+
+def _resolve_mime(file: Path | None, mime: str | None) -> str:
+    """Determine the MIME type to use for the upload.
+
+    Args:
+        file: Local file path, or None when reading from stdin.
+        mime: Explicit MIME type from --mime flag, or None.
+
+    Returns:
+        Resolved MIME type string.
+    """
+    if mime is not None:
+        return mime
+    if file is not None:
+        return guess_mime(file)
+    return "application/xml"
+
+
+def put(
+    target: str = typer.Argument(
+        help="Collection and document path: <nick>:<path>.",
+        autocompletion=collection_target_completer("any"),
+    ),
+    file: Path | None = typer.Option(None, "-f", "--file", help="Local file to upload (default: stdin)."),
+    mime: str | None = typer.Option(None, "--mime", help="MIME type (default: application/xml, or guessed from file extension)."),
+) -> None:
+    """Upload a document to a collection path from a file or stdin."""
+    nick, path = parse_target(target)
+    collection, server, full_path = resolve_collection(nick, path)
+    resolved_mime = _resolve_mime(file, mime)
+
+    if file is not None:
+        try:
+            content = file.read_bytes()
+        except OSError as e:
+            typer.echo(f"Error: cannot read '{file}': {e}", err=True)
+            raise typer.Exit(1)
+    else:
+        content = sys.stdin.buffer.read()
+
+    if xml_error := check_xml_wellformed(content, resolved_mime):
+        source = str(file) if file is not None else "stdin"
+        typer.echo(f"Error: '{source}' is not well-formed XML: {xml_error}", err=True)
+        raise typer.Exit(1)
+
+    # PUT silently overwrites existing documents. A --no-clobber flag could
+    # check existence first (HEAD request) and abort if the resource is found.
+    with handle_exist_errors(path, nick, collection.server_nick):
+        with ExistClient(server) as client:
+            client.put_document(full_path, content, resolved_mime)
+    invalidate(nick)

exist_shell/commands/rm.py

@@ -0,0 +1,23 @@
+"""rm command — delete documents from an eXist collection path."""
+
+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
+
+
+def rm(
+    targets: list[str] = typer.Argument(
+        help="One or more collection and document paths: <nick>:<path>.",
+        autocompletion=collection_target_completer("resource"),
+    ),
+) -> None:
+    """Delete one or more documents from a collection path."""
+    for target in targets:
+        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:
+                client.delete_document(full_path)

exist_shell/commands/server.py

@@ -0,0 +1,114 @@
+"""Server management commands (add, ls, rm, rename)."""
+
+import re
+
+import typer
+
+from pydantic import SecretStr
+
+from exist_shell.client import ExistClient
+from exist_shell.config import NICK_PATTERN, Config, Server
+from exist_shell.exceptions import ExistAuthError, ExistConnectionError
+
+app = typer.Typer(help="Manage servers.", no_args_is_help=True)
+
+
+def _default_nick(host: str) -> str:
+    return host.split(".")[0]
+
+
+def _complete_server_nick(incomplete: str) -> list[str]:
+    try:
+        servers = Config.load().servers
+    except Exception:
+        return []
+    return [nick for nick in servers if nick.startswith(incomplete)]
+
+
+def _list() -> None:
+    config = Config.load()
+    for nick, s in config.servers.items():
+        typer.echo(f"{nick}\t{s.user}@{s.host}:{s.port}")
+
+
+app.command("ls", help="List configured servers.")(_list)
+app.command("list", help="List configured servers.", hidden=True)(_list)
+
+
+@app.command("add")
+def server_add(
+    host: str = typer.Argument(help="Hostname or IP of the eXist server."),
+    port: int = typer.Option(8080, help="HTTP port."),
+    user: str = typer.Option("admin", help="Username."),
+    password: str = typer.Option(
+        "",
+        "--password",
+        envvar="EXIST_PASSWORD",
+        hide_input=True,
+        prompt="Password (leave empty for none)",
+        help="Password.",
+    ),
+    nick: str | None = typer.Option(None, help="Nickname (default: hostname without domain)."),
+) -> None:
+    """Add a server and verify connectivity before saving."""
+    resolved_nick = nick or _default_nick(host)
+    config = Config.load()
+    if resolved_nick in config.servers:
+        typer.echo(f"Error: server nick '{resolved_nick}' already exists.", err=True)
+        raise typer.Exit(1)
+    server = Server(nick=resolved_nick, host=host, port=port, user=user, password=SecretStr(password))
+    try:
+        with ExistClient(server) as client:
+            client.check_connection()
+    except ExistAuthError:
+        typer.echo(f"Error: authentication failed for {host}:{port}.", err=True)
+        raise typer.Exit(1)
+    except ExistConnectionError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    config.add_server(server)
+    typer.echo(f"Server '{resolved_nick}' added.")
+
+
+@app.command("rename")
+def server_rename(
+    old_nick: str = typer.Argument(
+        help="Current nickname of the server.", autocompletion=_complete_server_nick
+    ),
+    new_nick: str = typer.Argument(help="New nickname for the server."),
+) -> None:
+    """Rename a server nick, updating all collection references."""
+    if old_nick == new_nick:
+        typer.echo("Error: new nick is the same as the old nick.", err=True)
+        raise typer.Exit(1)
+    if not re.match(NICK_PATTERN, new_nick):
+        typer.echo(f"Error: '{new_nick}' is not a valid server nick.", err=True)
+        raise typer.Exit(1)
+    config = Config.load()
+    if old_nick not in config.servers:
+        typer.echo(f"Error: server nick '{old_nick}' not found.", err=True)
+        raise typer.Exit(1)
+    if new_nick in config.servers:
+        typer.echo(f"Error: server nick '{new_nick}' already exists.", err=True)
+        raise typer.Exit(1)
+    updated = config.rename_server(old_nick, new_nick)
+    if updated:
+        noun = "collection" if len(updated) == 1 else "collections"
+        typer.echo(f"Also updated {len(updated)} {noun}: {', '.join(updated)}.")
+    typer.echo(f"Server '{old_nick}' renamed to '{new_nick}'.")
+
+
+@app.command("rm")
+def server_rm(
+    nick: str = typer.Argument(help="Nickname of the server to remove."),
+) -> None:
+    """Remove a server and all its registered collections from the config."""
+    config = Config.load()
+    if nick not in config.servers:
+        typer.echo(f"Error: server nick '{nick}' not found.", err=True)
+        raise typer.Exit(1)
+    cascaded = config.remove_server(nick)
+    if cascaded:
+        noun = "collection" if len(cascaded) == 1 else "collections"
+        typer.echo(f"Also removed {len(cascaded)} {noun}: {', '.join(cascaded)}.")
+    typer.echo(f"Server '{nick}' removed.")