exist-shell 0.1.0__py3-none-any.whl

exist_shell/commands/chown.py

@@ -0,0 +1,121 @@
+"""chown command — change the owner and/or group of a document or collection."""
+
+import typer
+
+from exist_shell.client import ExistClient
+from exist_shell.completions import chown_spec_completer, 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
+
+
+def _parse_spec(spec: str) -> tuple[str | None, str | None]:
+    """Parse an owner spec into ``(owner, group)``, stripping any ``server@`` prefix.
+
+    Accepted forms: ``owner``, ``:group``, ``owner:group``,
+    ``server@owner``, ``server@:group``, ``server@owner:group``.
+    The ``server@`` prefix is used only for tab completion and is discarded here.
+
+    Args:
+        spec: The raw owner spec from the CLI.
+
+    Returns:
+        Tuple ``(owner, group)`` where either element is ``None`` when not
+        specified.
+    """
+    if "@" in spec:
+        _, _, spec = spec.partition("@")
+    if ":" in spec:
+        owner, _, group = spec.partition(":")
+        return owner.strip() or None, group.strip() or None
+    return spec.strip() or None, None
+
+
+def _chown_tree(client: ExistClient, path: str, owner: str | None, group: str | None) -> int:
+    """Recursively change ownership of a collection and all its contents.
+
+    Args:
+        client: Active ExistClient.
+        path: Full eXist path to the root collection.
+        owner: New owner username, or ``None`` to leave unchanged.
+        group: New group name, or ``None`` to leave unchanged.
+
+    Returns:
+        Total number of resources and collections whose ownership was changed.
+    """
+    client.chown_resource(path, owner, group)
+    count = 1
+    for item in client.list_collection(path):
+        child = f"{path}/{item.name}"
+        if isinstance(item, CollectionEntry):
+            count += _chown_tree(client, child, owner, group)
+        else:
+            client.chown_resource(child, owner, group)
+            count += 1
+    return count
+
+
+def chown(
+    owner_spec: str = typer.Argument(
+        help=(
+            "Owner/group spec: 'owner', ':group', 'owner:group'. "
+            "Prefix with 'server@' to pin a server for tab completion "
+            "(e.g. 'prod@alice:editors')."
+        ),
+        autocompletion=chown_spec_completer,
+    ),
+    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 the owner and/or group of a document or collection on the server.
+
+    Raises:
+        typer.Exit: If the ``server@`` prefix in the owner spec names a different
+            server than the one the target collection is registered against.
+    """
+    spec_server_nick = owner_spec.partition("@")[0] if "@" in owner_spec else None
+    owner, group = _parse_spec(owner_spec)
+    if owner is None and group is None:
+        typer.echo(
+            "Error: specify at least an owner or a group "
+            "(e.g. 'alice', ':editors', 'alice:editors').",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    nick, path = parse_target(target, path_required=False)
+    collection, server, full_path = resolve_collection(nick, path)
+
+    if spec_server_nick and spec_server_nick != collection.server_nick:
+        typer.echo(
+            f"Error: owner spec targets server '{spec_server_nick}' but "
+            f"collection '{nick}' belongs to server '{collection.server_nick}'.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    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 chown a single document.",
+                            err=True,
+                        )
+                        raise typer.Exit(1)
+                    count = _chown_tree(client, full_path, owner, group)
+                    typer.echo(f"Ownership of '{path}' updated ({count} items).")
+                else:
+                    client.chown_resource(full_path, owner, group)
+                    typer.echo(f"Ownership of '{path}' updated.")
+    except ExistQueryError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)

exist_shell/commands/collection.py

@@ -0,0 +1,189 @@
+"""Collection management commands (add, new, ls, rm)."""
+
+import typer
+
+from exist_shell.client import ExistClient
+from exist_shell.config import Collection, Config
+from exist_shell.exceptions import ExistAuthError, ExistConnectionError, ExistNotFoundError
+
+app = typer.Typer(help="Manage collections.", no_args_is_help=True)
+
+
+def _complete_collection_target(incomplete: str) -> list[str]:
+    if "@" not in incomplete:
+        return []
+    prefix, partial = incomplete.split("@", 1)
+    try:
+        servers = Config.load().servers
+    except Exception:
+        return []
+    return [f"{prefix}@{nick}" for nick in servers if nick.startswith(partial)]
+
+
+def _complete_server(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, c in config.collections.items():
+        typer.echo(f"{nick}\t/db/{c.name}\t@{c.server_nick}")
+
+
+app.command("ls", help="List configured collections.")(_list)
+app.command("list", help="List configured collections.", hidden=True)(_list)
+
+
+@app.command("add")
+def collection_add(
+    target: str = typer.Argument(
+        help="Collection name, optionally with server: <name>[@<server>].",
+        autocompletion=_complete_collection_target,
+    ),
+    server: str | None = typer.Option(
+        None, "--server", help="Server nick.", autocompletion=_complete_server
+    ),
+    nick: str | None = typer.Option(None, help="Nickname (default: collection name)."),
+) -> None:
+    """Add a collection and verify it exists on the server before saving."""
+    name = target
+    if "@" in target:
+        name, server_from_target = target.split("@", 1)
+        if server is not None and server != server_from_target:
+            typer.echo("Error: conflicting --server and @server in argument.", err=True)
+            raise typer.Exit(1)
+        server = server_from_target
+
+    config = Config.load()
+
+    if server is None:
+        if len(config.servers) == 1:
+            server = next(iter(config.servers))
+        else:
+            typer.echo("Error: --server is required when multiple servers are configured.", err=True)
+            raise typer.Exit(1)
+
+    if server not in config.servers:
+        typer.echo(f"Error: server '{server}' not found.", err=True)
+        raise typer.Exit(1)
+
+    resolved_nick = nick or name
+    if resolved_nick in config.collections:
+        typer.echo(
+            f"Error: nick '{resolved_nick}' already exists. Use --nick to provide a unique nickname.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    try:
+        with ExistClient(config.servers[server]) as client:
+            if not client.collection_exists(name):
+                typer.echo(f"Error: '/db/{name}' not found on server '{server}'.", err=True)
+                raise typer.Exit(1)
+    except ExistAuthError:
+        typer.echo(f"Error: authentication failed for server '{server}'.", err=True)
+        raise typer.Exit(1)
+    except ExistConnectionError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    config.add_collection(Collection(nick=resolved_nick, server_nick=server, name=name))
+    typer.echo(f"Collection '{resolved_nick}' added.")
+
+
+@app.command("new")
+def collection_new(
+    target: str = typer.Argument(
+        help="Collection name, optionally with server: <name>[@<server>].",
+        autocompletion=_complete_collection_target,
+    ),
+    server: str | None = typer.Option(
+        None, "--server", help="Server nick.", autocompletion=_complete_server
+    ),
+    nick: str | None = typer.Option(None, "--nick", help="Nickname (default: collection name)."),
+) -> None:
+    """Create /db/<name> on the server and register it in the config."""
+    name = target
+    if "@" in target:
+        name, server_from_target = target.split("@", 1)
+        if server is not None and server != server_from_target:
+            typer.echo("Error: conflicting --server and @server in argument.", err=True)
+            raise typer.Exit(1)
+        server = server_from_target
+
+    config = Config.load()
+
+    if server is None:
+        if len(config.servers) == 1:
+            server = next(iter(config.servers))
+        else:
+            typer.echo("Error: --server is required when multiple servers are configured.", err=True)
+            raise typer.Exit(1)
+
+    if server not in config.servers:
+        typer.echo(f"Error: server '{server}' not found.", err=True)
+        raise typer.Exit(1)
+
+    resolved_nick = nick or name
+    if resolved_nick in config.collections:
+        typer.echo(
+            f"Error: nick '{resolved_nick}' already exists. Use --nick to provide a unique nickname.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    try:
+        with ExistClient(config.servers[server]) as client:
+            if client.collection_exists(name):
+                typer.echo(f"'/db/{name}' already exists on server '{server}'.")
+                return
+            client.create_collection(f"/db/{name}")
+    except ExistAuthError:
+        typer.echo(f"Error: authentication failed for server '{server}'.", err=True)
+        raise typer.Exit(1)
+    except ExistConnectionError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    config.add_collection(Collection(nick=resolved_nick, server_nick=server, name=name))
+    typer.echo(f"Collection '{resolved_nick}' created at /db/{name}.")
+
+
+@app.command("rm")
+def collection_rm(
+    nick: str = typer.Argument(help="Nickname of the collection to remove."),
+    delete: bool = typer.Option(False, "--delete", help="Also delete the collection from the server."),
+) -> None:
+    """Remove a collection from the config, optionally deleting it from the server."""
+    config = Config.load()
+    if nick not in config.collections:
+        typer.echo(f"Error: collection '{nick}' not found.", err=True)
+        raise typer.Exit(1)
+
+    if delete:
+        collection = config.collections[nick]
+        if collection.server_nick not in config.servers:
+            typer.echo(f"Error: server '{collection.server_nick}' not found.", err=True)
+            raise typer.Exit(1)
+        try:
+            with ExistClient(config.servers[collection.server_nick]) as client:
+                client.delete_collection(f"/db/{collection.name}")
+        except ExistAuthError:
+            typer.echo(f"Error: authentication failed for server '{collection.server_nick}'.", err=True)
+            raise typer.Exit(1)
+        except ExistConnectionError as e:
+            typer.echo(f"Error: {e}", err=True)
+            raise typer.Exit(1)
+        except ExistNotFoundError:
+            typer.echo(
+                f"Error: '/db/{collection.name}' not found on server '{collection.server_nick}'.",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+    config.remove_collection(nick)
+    typer.echo(f"Collection '{nick}' removed.")

exist_shell/commands/cp.py

@@ -0,0 +1,142 @@
+"""cp command — copy documents between local paths and remote eXist collections."""
+
+from pathlib import Path, 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.utils import guess_mime, handle_exist_errors, is_remote, parse_target, resolve_collection
+
+
+def _remote_dest(path: str, source_name: str) -> str:
+    """Resolve the final remote destination path.
+
+    Args:
+        path: The target path as typed (may end with ``/`` to signal a directory).
+        source_name: Filename to append when path ends with ``/``.
+
+    Returns:
+        Final destination path without a trailing slash.
+    """
+    if path.endswith("/"):
+        return path.rstrip("/") + "/" + source_name
+    return path
+
+
+def _local_dest(target: str, source_name: str) -> Path:
+    """Resolve the final local destination path.
+
+    Args:
+        target: Local target path as typed.
+        source_name: Filename to append when target is an existing directory.
+
+    Returns:
+        Resolved local Path for writing.
+    """
+    p = Path(target)
+    if p.is_dir():
+        return p / source_name
+    return p
+
+
+def _local_to_remote(source: str, target: str) -> None:
+    """Copy a local file to a remote eXist path.
+
+    Args:
+        source: Local file path.
+        target: Remote ``nick:path`` destination.
+    """
+    src_path = Path(source)
+    try:
+        content = src_path.read_bytes()
+    except OSError as e:
+        typer.echo(f"Error: cannot read '{source}': {e}", err=True)
+        raise typer.Exit(1)
+
+    mime_type = guess_mime(src_path)
+
+    nick, tgt_path = parse_target(target)
+    dest_path = _remote_dest(tgt_path, src_path.name)
+    collection, server, full_dest = resolve_collection(nick, dest_path)
+
+    with handle_exist_errors(dest_path, nick, collection.server_nick):
+        with ExistClient(server) as client:
+            client.put_document(full_dest, content, mime_type)
+    invalidate(nick)
+
+
+def _remote_to_local(source: str, target: str) -> None:
+    """Copy a remote eXist document to a local path.
+
+    Args:
+        source: Remote ``nick:path`` source.
+        target: Local file or directory path.
+    """
+    nick, src_path = parse_target(source)
+    collection, server, full_src = resolve_collection(nick, src_path)
+
+    with handle_exist_errors(src_path, nick, collection.server_nick):
+        with ExistClient(server) as client:
+            result = client.get_document(full_src)
+
+    dest = _local_dest(target, PurePosixPath(src_path).name)
+    try:
+        dest.write_bytes(result.content)
+    except OSError as e:
+        typer.echo(f"Error: cannot write '{dest}': {e}", err=True)
+        raise typer.Exit(1)
+
+
+def _remote_to_remote(source: str, target: str) -> None:
+    """Copy a remote eXist document to another remote eXist path.
+
+    Args:
+        source: Remote ``nick:path`` source.
+        target: Remote ``nick:path`` destination (may be a different collection or server).
+    """
+    src_nick, src_path = parse_target(source)
+    src_collection, src_server, src_full = resolve_collection(src_nick, src_path)
+
+    with handle_exist_errors(src_path, src_nick, src_collection.server_nick):
+        with ExistClient(src_server) as client:
+            result = client.get_document(src_full)
+
+    tgt_nick, tgt_path = parse_target(target)
+    dest_path = _remote_dest(tgt_path, PurePosixPath(src_path).name)
+    tgt_collection, tgt_server, tgt_full = resolve_collection(tgt_nick, dest_path)
+
+    with handle_exist_errors(dest_path, tgt_nick, tgt_collection.server_nick):
+        with ExistClient(tgt_server) as client:
+            client.put_document(tgt_full, result.content, result.mime_type)
+    invalidate(tgt_nick)
+
+
+def cp(
+    source: str = typer.Argument(
+        help="Source: remote ``<nick>:<path>`` or local file path.",
+        autocompletion=collection_target_completer("resource", allow_local=True),
+    ),
+    target: str = typer.Argument(
+        help="Target: remote ``<nick>:<path>`` or local path (file or directory).",
+        autocompletion=collection_target_completer("any", allow_local=True),
+    ),
+) -> None:
+    """Copy a document between local paths and remote eXist collections."""
+    src_remote = is_remote(source)
+    tgt_remote = is_remote(target)
+
+    if not src_remote and not tgt_remote:
+        typer.echo(
+            "Error: at least one of source or target must be a remote path (nick:path).",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    if src_remote and tgt_remote:
+        _remote_to_remote(source, target)
+    elif src_remote:
+        _remote_to_local(source, target)
+    else:
+        _local_to_remote(source, target)

exist_shell/commands/edit.py

@@ -0,0 +1,85 @@
+"""edit command — download, edit locally, and re-upload a document."""
+
+import os
+import shlex
+import subprocess
+import sys
+import tempfile
+from pathlib import Path, 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.utils import check_xml_wellformed, handle_exist_errors, parse_target, resolve_collection
+
+
+def _find_editor() -> str:
+    """Return the editor command from $VISUAL, $EDITOR, or a platform default.
+
+    Returns:
+        Editor command string (may include flags, e.g. ``code --wait``).
+    """
+    for var in ("VISUAL", "EDITOR"):
+        val = os.environ.get(var, "").strip()
+        if val:
+            return val
+    return "notepad" if sys.platform == "win32" else "vi"
+
+
+def edit(
+    target: str = typer.Argument(
+        help="Collection and document path: <nick>:<path>.",
+        autocompletion=collection_target_completer("resource"),
+    ),
+) -> None:
+    """Download a document, open it in $VISUAL/$EDITOR, and re-upload if changed."""
+    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)
+
+    suffix = PurePosixPath(path).suffix
+    with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+        tmp_path = Path(tmp.name)
+        tmp.write(result.content)
+
+    try:
+        editor = _find_editor()
+        last_seen = result.content
+
+        while True:
+            proc = subprocess.run(shlex.split(editor) + [str(tmp_path)])
+            if proc.returncode != 0:
+                typer.echo(f"Error: editor exited with code {proc.returncode}.", err=True)
+                raise typer.Exit(1)
+
+            new_content = tmp_path.read_bytes()
+
+            if new_content == last_seen:
+                if last_seen == result.content:
+                    typer.echo("No changes.")
+                else:
+                    typer.echo("Aborted: document still has XML errors, not uploaded.", err=True)
+                    raise typer.Exit(1)
+                return
+
+            if xml_error := check_xml_wellformed(new_content, result.mime_type):
+                typer.echo(f"Warning: not well-formed XML: {xml_error}", err=True)
+                typer.echo("Fix the error and save to continue, or quit without changes to abort.", err=True)
+                typer.echo("Press Enter to re-open the editor...", err=True)
+                sys.stdin.readline()
+                last_seen = new_content
+                continue
+
+            break
+
+        with handle_exist_errors(path, nick, collection.server_nick):
+            with ExistClient(server) as client:
+                client.put_document(full_path, new_content, result.mime_type)
+        invalidate(nick)
+    finally:
+        tmp_path.unlink(missing_ok=True)

exist_shell/commands/exec.py

@@ -0,0 +1,65 @@
+"""exec command — execute an XQuery script on an eXist-db server."""
+
+import sys
+from pathlib import Path
+
+import typer
+
+from exist_shell.client import ExistClient
+from exist_shell.exceptions import ExistQueryError
+from exist_shell.utils import handle_exist_errors, parse_target, resolve_collection
+from exist_shell.xquery import list_validators, preprocess, validate_locally
+
+
+def exec(
+    target: str | None = typer.Argument(
+        default=None,
+        help="Collection context for the query: <nick>[:<path>].",
+    ),
+    file: Path | None = typer.Option(None, "-f", "--file", help="XQuery file to execute (default: stdin)."),
+    no_fix: bool = typer.Option(False, "--no-fix", help="Skip XQuery preprocessing (version declaration, namespace imports)."),
+    no_validate: bool = typer.Option(False, "--no-validate", help="Skip local validation even if a validator is installed."),
+    validator: str | None = typer.Option(None, "--validator", help="Name of the local validator to use (default: first installed)."),
+    list_validators_flag: bool = typer.Option(False, "--list-validators", help="List known validators and their install status, then exit."),
+) -> None:
+    """Execute an XQuery script on an eXist-db server and print the result."""
+    if list_validators_flag:
+        for name, path in list_validators():
+            status = path or "not installed"
+            typer.echo(f"{name:12}{status}")
+        raise typer.Exit()
+
+    if target is None:
+        typer.echo("Error: missing argument 'TARGET'.", err=True)
+        raise typer.Exit(1)
+
+    nick, path = parse_target(target, path_required=False)
+    collection, server, full_path = resolve_collection(nick, path)
+
+    if file is not None:
+        try:
+            code = file.read_text(encoding="utf-8")
+        except OSError as e:
+            typer.echo(f"Error: cannot read '{file}': {e}", err=True)
+            raise typer.Exit(1)
+    else:
+        code = sys.stdin.read()
+
+    if not no_fix:
+        code = preprocess(code)
+
+    if not no_validate:
+        result = validate_locally(code, validator=validator)
+        if not result.ok:
+            typer.echo(f"Error: {result.error}", err=True)
+            raise typer.Exit(1)
+
+    try:
+        with handle_exist_errors(path, nick, collection.server_nick):
+            with ExistClient(server) as client:
+                output = client.execute_query(code, context=full_path)
+    except ExistQueryError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(output, nl=False)