docmost-cli 0.4.0__py3-none-any.whl

docmost_cli/__init__.py

@@ -0,0 +1,5 @@
+"""docmost-cli: CLI tool for managing Docmost wiki instances."""
+
+__version__ = "0.4.0"
+
+__all__ = ["__version__"]

docmost_cli/__main__.py

@@ -0,0 +1,18 @@
+"""Entry point for `python -m docmost_cli`."""
+
+import sys
+
+# Fix Windows console encoding: enable UTF-8 so Rich box-drawing chars
+# and emoji content don't crash with cp1252. This runs before cli/main.py
+# is imported. See also _ensure_utf8_stdio() in cli/main.py (for the
+# pyproject scripts entry point which bypasses __main__.py).
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except (AttributeError, ValueError):
+        pass
+
+from docmost_cli.cli.main import app
+
+app()

docmost_cli/api/__init__.py

@@ -0,0 +1,5 @@
+"""Docmost API client and endpoint methods."""
+
+from docmost_cli.api.client import DocmostClient
+
+__all__ = ["DocmostClient"]

docmost_cli/api/attachments.py

@@ -0,0 +1,30 @@
+"""Attachment API methods."""
+
+from typing import Any
+
+from docmost_cli.api.client import DocmostClient
+from docmost_cli.api.pagination import build_body
+
+__all__ = [
+    "search_attachments",
+]
+
+
+def search_attachments(
+    client: DocmostClient,
+    query: str,
+    *,
+    space_id: str | None = None,
+) -> dict[str, Any]:
+    """Search attachments by query string.
+
+    Args:
+        client: Authenticated Docmost client.
+        query: Search query string.
+        space_id: Optional space UUID to scope the search.
+
+    Returns:
+        Raw API response dict with matching attachments.
+    """
+    body = build_body({"query": query}, spaceId=space_id)
+    return client.post("/attachments/search", json=body)

docmost_cli/api/auth.py

@@ -0,0 +1,202 @@
+"""Authentication strategies for Docmost API.
+
+Supports two auth modes:
+- API key (Enterprise): Bearer token in Authorization header
+- Session (Community/AGPL): POST /api/auth/login, cache JWT
+"""
+
+import json
+from abc import ABC, abstractmethod
+from datetime import UTC, datetime
+from pathlib import Path
+
+import httpx
+
+from docmost_cli.config.settings import DocmostSettings
+from docmost_cli.config.store import get_cache_dir
+
+__all__ = ["ApiKeyAuth", "AuthError", "AuthStrategy", "SessionAuth", "create_auth"]
+
+
+class AuthError(Exception):
+    """Raised when authentication fails."""
+
+
+class AuthStrategy(ABC):
+    """Base class for authentication strategies."""
+
+    @abstractmethod
+    def apply(self, request: httpx.Request) -> None:
+        """Add auth headers to a request."""
+
+    @abstractmethod
+    def can_retry(self) -> bool:
+        """Whether this strategy supports re-authentication on 401."""
+
+    @abstractmethod
+    def refresh(self, client: httpx.Client) -> None:
+        """Re-authenticate. Called on 401 if can_retry() is True."""
+
+
+class ApiKeyAuth(AuthStrategy):
+    """Bearer token authentication for Enterprise edition."""
+
+    def __init__(self, api_key: str) -> None:
+        self._api_key = api_key
+
+    def apply(self, request: httpx.Request) -> None:
+        """Set Authorization: Bearer header."""
+        request.headers["Authorization"] = f"Bearer {self._api_key}"
+
+    def can_retry(self) -> bool:
+        """API key is static; no retry possible."""
+        return False
+
+    def refresh(self, client: httpx.Client) -> None:
+        """Not supported for API key auth."""
+        raise AuthError("API key authentication failed. Check your API key.")
+
+
+class SessionAuth(AuthStrategy):
+    """Session-based authentication for Community/AGPL edition.
+
+    Authenticates via POST /api/auth/login, extracts JWT from the response,
+    and caches it in ~/.cache/docmost-cli/session.json.
+    """
+
+    def __init__(self, url: str, email: str, password: str) -> None:
+        self._url = url.rstrip("/")
+        self._email = email
+        self._password = password
+        self._token: str | None = None
+        self._load_cached_token()
+
+    def _cache_path(self) -> Path:
+        """Return the path to the session cache file."""
+        return get_cache_dir() / "session.json"
+
+    def _load_cached_token(self) -> None:
+        """Try to load a cached JWT from the cache file."""
+        cache = self._cache_path()
+        if not cache.exists():
+            return
+        try:
+            data = json.loads(cache.read_text())
+            if data.get("url") == self._url and data.get("email") == self._email:
+                self._token = data.get("token")
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    def _save_cached_token(self) -> None:
+        """Save the current JWT to the cache file."""
+        if not self._token:
+            return
+        cache = self._cache_path()
+        cache.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "token": self._token,
+            "url": self._url,
+            "email": self._email,
+            "created_at": datetime.now(UTC).isoformat(),
+        }
+        cache.write_text(json.dumps(data, indent=2))
+        import contextlib
+
+        with contextlib.suppress(OSError):
+            cache.chmod(0o600)  # Owner read/write only
+
+    def apply(self, request: httpx.Request) -> None:
+        """Set Authorization header from cached token."""
+        if self._token:
+            request.headers["Authorization"] = f"Bearer {self._token}"
+
+    def can_retry(self) -> bool:
+        """Session auth supports re-authentication."""
+        return True
+
+    def refresh(self, client: httpx.Client) -> None:
+        """POST /api/auth/login to get a fresh JWT.
+
+        Extracts the token from the response JSON body or Set-Cookie header.
+
+        Args:
+            client: The httpx client to use for the login request.
+
+        Raises:
+            AuthError: If login fails.
+        """
+        login_url = f"{self._url}/api/auth/login"
+        try:
+            response = client.post(
+                login_url,
+                json={"email": self._email, "password": self._password},
+            )
+        except httpx.HTTPError as exc:
+            raise AuthError(f"Failed to connect for authentication: {exc}") from exc
+
+        if response.status_code != 200:
+            raise AuthError(
+                f"Authentication failed (HTTP {response.status_code}). "
+                "Check your email and password."
+            )
+
+        # Try to extract token from response cookies (Docmost uses authToken cookie)
+        token: str | None = None
+        cookies = response.cookies
+        if "authToken" in cookies:
+            token = cookies["authToken"]
+        elif "token" in cookies:
+            token = cookies["token"]
+
+        # Fallback: try response JSON body
+        if not token:
+            try:
+                body = response.json()
+                token = body.get("token") or body.get("authToken")
+            except (json.JSONDecodeError, AttributeError):
+                pass
+
+        # Fallback: parse Set-Cookie header manually
+        if not token:
+            for cookie_header in response.headers.get_list("set-cookie"):
+                if "authToken=" in cookie_header:
+                    token = cookie_header.split("authToken=")[1].split(";")[0]
+                    break
+
+        if not token:
+            raise AuthError(
+                "Authentication succeeded but no token found in response. "
+                "This may be an unsupported Docmost version."
+            )
+
+        self._token = token
+        self._save_cached_token()
+
+
+def create_auth(settings: DocmostSettings) -> AuthStrategy:
+    """Create the appropriate auth strategy based on settings.
+
+    Priority: api_key > email+password > error.
+
+    Args:
+        settings: The resolved settings.
+
+    Returns:
+        An AuthStrategy instance.
+
+    Raises:
+        AuthError: If no credentials are configured.
+    """
+    if settings.api_key:
+        return ApiKeyAuth(settings.api_key)
+
+    if settings.email and settings.password:
+        if not settings.url:
+            raise AuthError("URL is required for session authentication.")
+        return SessionAuth(settings.url, settings.email, settings.password)
+
+    raise AuthError(
+        "No authentication configured. "
+        "Set DOCMOST_API_KEY or DOCMOST_EMAIL + DOCMOST_PASSWORD. "
+        "Run 'docmost-cli config init' for interactive setup."
+    )

docmost_cli/api/client.py

@@ -0,0 +1,296 @@
+"""DocmostClient: central HTTP client with auth, retry, and error handling.
+
+All API calls go through this client. It handles:
+- Auth header injection via AuthStrategy
+- 401 retry (session auth re-authentication)
+- Exponential backoff retry for transient errors (429, 5xx)
+- HTTP error translation to user-friendly messages with exit codes
+- Optional verbose debug logging
+"""
+
+import logging
+import sys
+import time
+from typing import Any
+
+import httpx
+
+from docmost_cli.api.auth import AuthError, AuthStrategy, create_auth
+from docmost_cli.config.settings import DocmostSettings
+from docmost_cli.output.formatter import print_error
+
+__all__ = ["DocmostClient"]
+
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+_MAX_RETRIES = 3
+_BASE_BACKOFF = 1.0
+_BACKOFF_FACTOR = 2.0
+
+
+class DocmostClient:
+    """HTTP client for the Docmost API.
+
+    Uses httpx.Client for connection pooling. Provides authenticated
+    request methods with automatic error handling and retry logic.
+    """
+
+    def __init__(self, settings: DocmostSettings, *, verbose: bool = False) -> None:
+        if not settings.url:
+            print_error(
+                "No Docmost URL configured. Run 'docmost-cli config init' or set DOCMOST_URL.",
+                exit_code=1,
+            )
+
+        self._settings = settings
+        self._base_url = settings.url.rstrip("/")  # type: ignore[union-attr]
+        self._auth: AuthStrategy = create_auth(settings)
+        self._http = httpx.Client(timeout=30.0)
+        self._verbose = verbose
+
+        # Set up logging
+        self._log = logging.getLogger("docmost_cli")
+        if verbose and not self._log.handlers:
+            handler = logging.StreamHandler(sys.stderr)
+            handler.setFormatter(logging.Formatter("[docmost] %(message)s"))
+            self._log.addHandler(handler)
+            self._log.setLevel(logging.DEBUG)
+
+    def _send_with_retry(self, request: httpx.Request) -> httpx.Response:
+        """Send a request with auth, retry on 401/429/5xx, and error handling.
+
+        Args:
+            request: The prepared httpx request.
+
+        Returns:
+            The HTTP response (success only; errors raise SystemExit).
+        """
+        self._auth.apply(request)
+
+        if self._verbose:
+            self._log.debug("%s %s", request.method, request.url)
+
+        start = time.monotonic()
+
+        try:
+            response = self._http.send(request)
+        except httpx.ConnectError:
+            print_error(
+                f"Cannot connect to {self._base_url}. Check the URL and your network.",
+                exit_code=1,
+            )
+        except httpx.TimeoutException:
+            print_error(
+                f"Request timed out connecting to {self._base_url}.",
+                exit_code=1,
+            )
+
+        if self._verbose:
+            elapsed = (time.monotonic() - start) * 1000
+            self._log.debug("  → %s (%dms)", response.status_code, elapsed)
+
+        # Handle 401 retry for session auth
+        if response.status_code == 401 and self._auth.can_retry():
+            try:
+                self._auth.refresh(self._http)
+            except AuthError as exc:
+                print_error(str(exc), exit_code=3)
+
+            request = self._http.build_request(
+                request.method,
+                str(request.url),
+                headers=dict(request.headers),
+                content=request.content,
+            )
+            self._auth.apply(request)
+            try:
+                response = self._http.send(request)
+            except httpx.HTTPError:
+                print_error("Request failed after re-authentication.", exit_code=1)
+
+        # Exponential backoff retry for transient errors
+        for attempt in range(_MAX_RETRIES):
+            if response.status_code not in _RETRYABLE_STATUS:
+                break
+
+            # Parse Retry-After header for 429
+            wait = _BASE_BACKOFF * (_BACKOFF_FACTOR**attempt)
+            if response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                if retry_after and retry_after.isdigit():
+                    wait = min(float(retry_after), 60.0)
+
+            if self._verbose:
+                self._log.debug(
+                    "  Retrying in %.1fs (attempt %d/%d)...",
+                    wait,
+                    attempt + 1,
+                    _MAX_RETRIES,
+                )
+
+            time.sleep(wait)
+
+            request = self._http.build_request(
+                request.method,
+                str(request.url),
+                headers=dict(request.headers),
+                content=request.content,
+            )
+            self._auth.apply(request)
+            try:
+                response = self._http.send(request)
+            except httpx.HTTPError:
+                if attempt == _MAX_RETRIES - 1:
+                    print_error(
+                        f"Request failed after {_MAX_RETRIES} retries.",
+                        exit_code=1,
+                    )
+                continue
+
+            if self._verbose:
+                self._log.debug("  → %s (retry)", response.status_code)
+
+        # Translate HTTP errors
+        self._handle_error(response)
+
+        return response
+
+    def request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Make an authenticated API request with error handling.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            path: API path relative to /api/ (e.g., "/pages/info").
+            **kwargs: Additional arguments passed to httpx (json, params, etc.).
+
+        Returns:
+            Parsed JSON response body.
+        """
+        url = f"{self._base_url}/api{path}"
+        request = self._http.build_request(method, url, **kwargs)
+        response = self._send_with_retry(request)
+        return response.json()
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Convenience method for POST requests.
+
+        Most Docmost API endpoints use POST.
+
+        Args:
+            path: API path relative to /api/.
+            json: JSON body to send.
+
+        Returns:
+            Parsed JSON response body.
+        """
+        return self.request("POST", path, json=json)
+
+    def post_multipart(
+        self,
+        path: str,
+        data: dict[str, str] | None = None,
+        files: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """POST with multipart/form-data for file uploads.
+
+        Args:
+            path: API path relative to /api/.
+            data: Form fields.
+            files: File fields (httpx files format).
+
+        Returns:
+            Parsed JSON response body.
+        """
+        url = f"{self._base_url}/api{path}"
+        request = self._http.build_request("POST", url, data=data, files=files)
+        response = self._send_with_retry(request)
+        return response.json()
+
+    def post_raw(
+        self, path: str, json: dict[str, Any] | None = None, *, raise_on_error: bool = True
+    ) -> httpx.Response:
+        """POST request returning raw httpx.Response.
+
+        Use for binary/non-JSON responses or silent probes.
+
+        Args:
+            path: API path relative to /api/.
+            json: JSON body to send.
+            raise_on_error: If False, skip error handling (for endpoint probes).
+        """
+        url = f"{self._base_url}/api{path}"
+        request = self._http.build_request("POST", url, json=json)
+        self._auth.apply(request)
+        try:
+            response = self._http.send(request)
+        except httpx.HTTPError:
+            if raise_on_error:
+                print_error("Request failed.", exit_code=1)
+            return httpx.Response(status_code=0)  # Sentinel for failed probe
+        if raise_on_error:
+            self._handle_error(response)
+        return response
+
+    def get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Convenience method for GET requests.
+
+        Args:
+            path: API path relative to /api/.
+            **kwargs: Additional arguments (params, etc.).
+
+        Returns:
+            Parsed JSON response body.
+        """
+        return self.request("GET", path, **kwargs)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> "DocmostClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    @staticmethod
+    def _handle_error(response: httpx.Response) -> None:
+        """Translate HTTP error responses to user-friendly messages.
+
+        Args:
+            response: The HTTP response to check.
+        """
+        if response.is_success:
+            return
+
+        status = response.status_code
+
+        if status == 401:
+            print_error(
+                "Authentication failed. Run 'docmost-cli config test' to verify.",
+                exit_code=3,
+            )
+        elif status == 403:
+            print_error("Permission denied.", exit_code=1)
+        elif status == 404:
+            print_error(
+                "Resource not found. Check the ID or slug.",
+                exit_code=4,
+            )
+        elif status == 422:
+            try:
+                detail = response.json().get("message", "Validation error")
+            except (ValueError, AttributeError):
+                detail = "Validation error"
+            print_error(f"Validation error: {detail}", exit_code=1)
+        elif status == 429:
+            print_error("Rate limited. Try again later.", exit_code=1)
+        elif status >= 500:
+            print_error(
+                f"Server error ({status}). Check Docmost logs.",
+                exit_code=1,
+            )
+        else:
+            print_error(
+                f"Unexpected error (HTTP {status}).",
+                exit_code=1,
+            )

docmost_cli/api/comments.py

@@ -0,0 +1,103 @@
+"""Comment API methods."""
+
+import json
+from typing import Any
+
+from docmost_cli.api.client import DocmostClient
+
+__all__ = [
+    "create_comment",
+    "list_comments",
+    "update_comment",
+]
+
+
+def _wrap_text_as_prosemirror(text: str) -> dict[str, Any]:
+    """Wrap plain text into a minimal ProseMirror document.
+
+    Creates the structure Docmost expects for comment content.
+    Multi-line text is split into separate paragraphs.
+
+    Args:
+        text: Plain text content.
+
+    Returns:
+        ProseMirror document dict.
+    """
+    paragraphs = []
+    for line in text.split("\n"):
+        if line.strip():
+            paragraphs.append(
+                {
+                    "type": "paragraph",
+                    "content": [{"type": "text", "text": line}],
+                }
+            )
+        else:
+            paragraphs.append({"type": "paragraph"})
+
+    if not paragraphs:
+        paragraphs = [{"type": "paragraph", "content": [{"type": "text", "text": text}]}]
+
+    return {"type": "doc", "content": paragraphs}
+
+
+def list_comments(client: DocmostClient, page_id: str) -> dict[str, Any]:
+    """List all comments on a page.
+
+    Args:
+        client: Authenticated Docmost client.
+        page_id: Page UUID.
+
+    Returns:
+        Raw API response dict.
+    """
+    return client.post("/comments", json={"pageId": page_id})
+
+
+def create_comment(
+    client: DocmostClient,
+    *,
+    page_id: str,
+    content: str,
+) -> dict[str, Any]:
+    """Create a comment on a page.
+
+    Content is wrapped in ProseMirror JSON format as required by the API.
+
+    Args:
+        client: Authenticated Docmost client.
+        page_id: Page UUID.
+        content: Plain text comment content.
+
+    Returns:
+        Raw API response dict.
+    """
+    pm_content = _wrap_text_as_prosemirror(content)
+    return client.post(
+        "/comments/create",
+        json={"pageId": page_id, "content": json.dumps(pm_content)},
+    )
+
+
+def update_comment(
+    client: DocmostClient,
+    *,
+    comment_id: str,
+    content: str,
+) -> dict[str, Any]:
+    """Update an existing comment.
+
+    Args:
+        client: Authenticated Docmost client.
+        comment_id: Comment UUID.
+        content: New plain text content.
+
+    Returns:
+        Raw API response dict.
+    """
+    pm_content = _wrap_text_as_prosemirror(content)
+    return client.post(
+        "/comments/update",
+        json={"commentId": comment_id, "content": json.dumps(pm_content)},
+    )