docmost-cli 0.4.0__py3-none-any.whl

docmost_cli/api/spaces.py

@@ -0,0 +1,141 @@
+"""Space API methods."""
+
+from typing import Any
+
+from docmost_cli.api.client import DocmostClient
+from docmost_cli.api.pagination import build_body
+from docmost_cli.output.formatter import print_error
+
+__all__ = [
+    "create_space",
+    "get_space_info",
+    "list_spaces",
+    "resolve_space_id",
+    "update_space",
+]
+
+
+def list_spaces(
+    client: DocmostClient,
+    *,
+    limit: int | None = None,
+    cursor: str | None = None,
+) -> dict[str, Any]:
+    """List spaces with optional pagination.
+
+    Args:
+        client: Authenticated Docmost client.
+        limit: Max results to return.
+        cursor: Pagination cursor.
+
+    Returns:
+        Raw API response dict.
+    """
+    body = build_body({}, limit=limit, cursor=cursor)
+    return client.post("/spaces", json=body)
+
+
+def get_space_info(
+    client: DocmostClient,
+    *,
+    slug: str | None = None,
+    space_id: str | None = None,
+) -> dict[str, Any]:
+    """Get space info by slug or ID.
+
+    Args:
+        client: Authenticated Docmost client.
+        slug: Space slug (e.g., "engineering").
+        space_id: Space UUID.
+
+    Returns:
+        Space info dict.
+    """
+    if space_id:
+        result = client.post("/spaces/info", json={"spaceId": space_id})
+        return result.get("data", result)
+    if slug:
+        # /spaces/info only accepts spaceId, so search by slug in the full list
+        return _find_space_by_slug(client, slug)
+    print_error("Either slug or space_id is required.", exit_code=1)
+
+
+def _find_space_by_slug(client: DocmostClient, slug: str) -> dict[str, Any]:
+    """Find a space by slug from the spaces list.
+
+    Args:
+        client: Authenticated Docmost client.
+        slug: Space slug to find.
+
+    Returns:
+        Space info dict.
+    """
+    from docmost_cli.api.pagination import extract_items
+
+    result = list_spaces(client)
+    items = extract_items(result)
+    for space in items:
+        if space.get("slug") == slug:
+            return space
+    print_error(f"Space '{slug}' not found.", exit_code=4)
+
+
+def resolve_space_id(client: DocmostClient, slug: str) -> str:
+    """Resolve a space slug to its UUID.
+
+    Args:
+        client: Authenticated Docmost client.
+        slug: Space slug.
+
+    Returns:
+        Space UUID string.
+    """
+    info = get_space_info(client, slug=slug)
+    space_id = info.get("id")
+    if not space_id:
+        print_error(f"Space '{slug}' not found.", exit_code=4)
+    return space_id
+
+
+def create_space(
+    client: DocmostClient,
+    *,
+    name: str,
+    slug: str | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Create a new space.
+
+    Args:
+        client: Authenticated Docmost client.
+        name: Space name.
+        slug: Space slug (auto-generated if omitted).
+        description: Space description.
+
+    Returns:
+        Raw API response dict.
+    """
+    body = build_body({"name": name}, slug=slug, description=description)
+    return client.post("/spaces/create", json=body)
+
+
+def update_space(
+    client: DocmostClient,
+    *,
+    space_id: str,
+    name: str | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Update an existing space.
+
+    Args:
+        client: Authenticated Docmost client.
+        space_id: Space UUID.
+        name: New space name.
+        description: New description.
+
+    Returns:
+        Raw API response dict.
+    """
+    body = build_body({"spaceId": space_id}, name=name, description=description)
+    return client.post("/spaces/update", json=body)

docmost_cli/api/users.py

@@ -0,0 +1,25 @@
+"""User API methods."""
+
+from typing import Any
+
+from docmost_cli.api.client import DocmostClient
+
+__all__ = [
+    "get_current_user",
+]
+
+
+def get_current_user(client: DocmostClient) -> dict[str, Any]:
+    """Get the currently authenticated user's info.
+
+    Args:
+        client: Authenticated Docmost client.
+
+    Returns:
+        Unwrapped user info dict.
+    """
+    result = client.post("/users/me", json={})
+    data = result.get("data", result)
+    if "user" in data and isinstance(data["user"], dict):
+        return data["user"]
+    return data

docmost_cli/api/workspace.py

@@ -0,0 +1,43 @@
+"""Workspace API methods."""
+
+from typing import Any
+
+from docmost_cli.api.client import DocmostClient
+from docmost_cli.api.pagination import build_body
+
+__all__ = [
+    "get_workspace_info",
+    "list_workspace_members",
+]
+
+
+def get_workspace_info(client: DocmostClient) -> dict[str, Any]:
+    """Get workspace information.
+
+    Args:
+        client: Authenticated Docmost client.
+
+    Returns:
+        Raw API response dict with workspace details.
+    """
+    return client.post("/workspace/info", json={})
+
+
+def list_workspace_members(
+    client: DocmostClient,
+    *,
+    limit: int | None = None,
+    cursor: str | None = None,
+) -> dict[str, Any]:
+    """List workspace members with optional pagination.
+
+    Args:
+        client: Authenticated Docmost client.
+        limit: Max results to return.
+        cursor: Pagination cursor.
+
+    Returns:
+        Raw API response dict with members list.
+    """
+    body = build_body({}, limit=limit, cursor=cursor)
+    return client.post("/workspace/members", json=body)

docmost_cli/cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI command modules."""
+
+__all__: list[str] = []

docmost_cli/cli/attachment.py

@@ -0,0 +1,30 @@
+"""Attachment subcommands."""
+
+import typer
+
+from docmost_cli.api.attachments import search_attachments
+from docmost_cli.api.pagination import extract_items
+from docmost_cli.api.spaces import resolve_space_id
+from docmost_cli.cli.main import get_client
+from docmost_cli.output.formatter import print_table
+
+__all__ = ["attachment_app"]
+
+attachment_app = typer.Typer(name="attachment", help="Attachment operations.")
+
+
+@attachment_app.command("search")
+def attachment_search_cmd(
+    query: str = typer.Argument(..., help="Search query string"),
+    space: str | None = typer.Option(None, "--space", help="Space slug to scope search"),
+    json_mode: bool = typer.Option(False, "--json", help="Output as JSON array"),
+) -> None:
+    """Search attachments."""
+    client = get_client()
+    space_id = None
+    if space:
+        space_id = resolve_space_id(client, space)
+    result = search_attachments(client, query, space_id=space_id)
+    items = extract_items(result)
+    columns = ["id", "fileName", "type"]
+    print_table(items, columns, json_mode=json_mode)

docmost_cli/cli/comment.py

@@ -0,0 +1,83 @@
+"""Comment subcommands."""
+
+from typing import Any
+
+import typer
+
+from docmost_cli.api.comments import create_comment, list_comments, update_comment
+from docmost_cli.api.pagination import extract_id, extract_items
+from docmost_cli.cli.main import get_client
+from docmost_cli.output.formatter import print_result, print_table
+
+__all__ = ["comment_app"]
+
+comment_app = typer.Typer(name="comment", help="Comment operations.")
+
+
+def _extract_text_from_prosemirror(doc: dict[str, Any]) -> str:
+    """Extract plain text from a ProseMirror document for display.
+
+    Args:
+        doc: ProseMirror document dict.
+
+    Returns:
+        Plain text string, truncated to ~100 chars.
+    """
+    texts: list[str] = []
+
+    def walk(node: dict[str, Any]) -> None:
+        if node.get("type") == "text":
+            texts.append(node.get("text", ""))
+        for child in node.get("content", []):
+            if isinstance(child, dict):
+                walk(child)
+
+    walk(doc)
+    full = " ".join(texts)
+    if len(full) > 100:
+        return full[:97] + "..."
+    return full
+
+
+@comment_app.command("list")
+def comment_list_cmd(
+    page_id: str = typer.Argument(help="Page ID to list comments for"),
+    json_mode: bool = typer.Option(False, "--json", help="Output as JSON array"),
+) -> None:
+    """List comments on a page."""
+    client = get_client()
+    result = list_comments(client, page_id)
+    items = extract_items(result)
+
+    # For table display, extract text from ProseMirror content
+    if not json_mode:
+        for item in items:
+            content = item.get("content")
+            if isinstance(content, dict):
+                item["content"] = _extract_text_from_prosemirror(content)
+
+    columns = ["id", "content", "creatorId", "createdAt"]
+    print_table(items, columns, json_mode=json_mode)
+
+
+@comment_app.command("create")
+def comment_create_cmd(
+    page_id: str = typer.Argument(help="Page ID to comment on"),
+    content: str = typer.Option(..., "--content", help="Comment text (required)"),
+) -> None:
+    """Add a comment to a page."""
+    client = get_client()
+    result = create_comment(client, page_id=page_id, content=content)
+    comment_id = extract_id(result)
+    print_result(comment_id, f"Created comment on page '{page_id}'")
+
+
+@comment_app.command("update")
+def comment_update_cmd(
+    comment_id: str = typer.Argument(help="Comment ID to update"),
+    content: str = typer.Option(..., "--content", help="New comment text (required)"),
+) -> None:
+    """Update an existing comment."""
+    client = get_client()
+    update_comment(client, comment_id=comment_id, content=content)
+    print_result(comment_id, f"Updated comment '{comment_id}'")

docmost_cli/cli/config_cmd.py

@@ -0,0 +1,143 @@
+"""Config management subcommands: init, show, set, test."""
+
+import sys
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from docmost_cli.api.auth import AuthError
+from docmost_cli.config.store import (
+    get_config_path,
+    read_config,
+    set_config_value,
+    write_config,
+)
+from docmost_cli.output.formatter import print_error
+
+__all__ = ["config_app"]
+
+config_app = typer.Typer(name="config", help="Manage configuration.")
+_console = Console(stderr=True)
+
+
+def _get_effective_config_path() -> str | None:
+    """Get the config path from global state (set via --config global option)."""
+    from docmost_cli.cli.main import state
+
+    return str(state.config_path) if state.config_path else None
+
+
+def _mask(value: str) -> str:
+    """Mask a secret value, showing only the first 4 chars."""
+    if len(value) <= 4:
+        return "****"
+    return value[:4] + "*" * (len(value) - 4)
+
+
+@config_app.command("init")
+def config_init(
+    profile: str = typer.Option("default", "--profile", "-p", help="Profile to configure"),
+) -> None:
+    """Interactive setup wizard for Docmost CLI configuration."""
+    _console.print("[bold]Docmost CLI Configuration[/bold]\n")
+
+    url = typer.prompt("Docmost URL (e.g., https://docs.example.com)")
+    url = url.rstrip("/")
+
+    _console.print("\nAuthentication method:")
+    _console.print("  1. API key (Enterprise edition)")
+    _console.print("  2. Email + password (Community/AGPL edition)")
+    auth_choice = typer.prompt("Choose", type=int, default=1)
+
+    config_values: dict[str, str] = {"url": url}
+
+    if auth_choice == 1:
+        api_key = typer.prompt("API key")
+        config_values["api_key"] = api_key
+    else:
+        email = typer.prompt("Email")
+        password = typer.prompt("Password", hide_input=True)
+        config_values["email"] = email
+        config_values["password"] = password
+
+    path = get_config_path(_get_effective_config_path())
+    config = read_config(path)
+    config[profile] = config_values
+    write_config(config, path)
+
+    _console.print(f"\n[green]Configuration saved to {path}[/green]")
+    _console.print(f"Profile: [bold]{profile}[/bold]")
+    _console.print("\nRun [bold]docmost-cli config test[/bold] to verify connectivity.")
+
+
+@config_app.command("show")
+def config_show() -> None:
+    """Show current configuration (secrets are masked)."""
+    from docmost_cli.cli.main import state
+
+    if state.settings:
+        values: dict[str, str] = {
+            "url": state.settings.url or "",
+            "api_key": state.settings.api_key or "",
+            "email": state.settings.email or "",
+            "password": state.settings.password or "",
+            "profile": state.settings.profile,
+        }
+    else:
+        values = {"profile": "default"}
+
+    table = Table(title=f"Configuration — profile '{values.get('profile', 'default')}'")
+    table.add_column("Key", style="bold")
+    table.add_column("Value")
+
+    secret_keys = {"api_key", "password"}
+    for key, value in values.items():
+        if not value:
+            continue
+        display = _mask(value) if key in secret_keys else value
+        table.add_row(key, display)
+
+    console = Console()
+    console.print(table)
+
+
+@config_app.command("set")
+def config_set(
+    key: str = typer.Argument(help="Config key to set"),
+    value: str = typer.Argument(help="Value to set"),
+    profile: str = typer.Option("default", "--profile", "-p", help="Profile to update"),
+) -> None:
+    """Set a configuration value."""
+    valid_keys = {"url", "api_key", "email", "password"}
+    if key not in valid_keys:
+        print_error(f"Unknown config key '{key}'. Valid keys: {', '.join(sorted(valid_keys))}")
+
+    path = get_config_path(_get_effective_config_path())
+    set_config_value(key, value, profile, path)
+    _console.print(f"Set [bold]{key}[/bold] in profile '{profile}'")
+
+
+@config_app.command("test")
+def config_test() -> None:
+    """Test connectivity and authentication."""
+    from docmost_cli.cli.main import get_client
+
+    _console.print("Testing connection...\n")
+
+    try:
+        client = get_client()
+    except (AuthError, SystemExit) as exc:
+        print_error(f"Configuration error: {exc}", exit_code=3)
+
+    try:
+        from docmost_cli.api.users import get_current_user
+
+        result = get_current_user(client)
+    except SystemExit:
+        sys.exit(3)
+
+    name = result.get("name", result.get("email", "Unknown"))
+    _console.print("[green]Connected successfully![/green]")
+    _console.print(f"Authenticated as: [bold]{name}[/bold]")
+    _console.print(f"URL: {client._base_url}")

docmost_cli/cli/main.py

@@ -0,0 +1,133 @@
+"""Top-level typer app with global options and subcommand registration."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+from docmost_cli.api.client import DocmostClient
+from docmost_cli.config.store import load_settings
+from docmost_cli.output.formatter import print_error
+
+if TYPE_CHECKING:
+    from docmost_cli.config.settings import DocmostSettings
+
+__all__ = ["_ensure_utf8_stdio", "app", "get_client", "state"]
+
+
+class State:
+    """Global state shared across subcommands."""
+
+    def __init__(self) -> None:
+        self.settings: DocmostSettings | None = None
+        self.client: DocmostClient | None = None
+        self.config_path: Path | None = None
+        self.verbose: bool = False
+        self.yes: bool = False
+
+
+state = State()
+
+app = typer.Typer(
+    name="docmost-cli",
+    help="CLI tool for managing Docmost wiki instances.",
+    no_args_is_help=True,
+)
+
+
+def _ensure_utf8_stdio() -> None:
+    """Reconfigure stdout/stderr to UTF-8 on Windows.
+
+    Needed so emoji and Rich box-drawing chars work on cp1252 consoles.
+    Also called in __main__.py for 'python -m docmost_cli' invocation.
+    """
+    if sys.platform == "win32":
+        try:
+            sys.stdout.reconfigure(encoding="utf-8")
+            sys.stderr.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError):
+            pass
+
+
+@app.callback()
+def main(
+    profile: str = typer.Option("default", "--profile", "-p", help="Config profile name"),
+    url: str | None = typer.Option(None, "--url", help="Override Docmost URL"),
+    api_key: str | None = typer.Option(None, "--api-key", help="Override API key"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompts"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Debug logging"),
+    config: str | None = typer.Option(None, "--config", help="Path to config file"),
+) -> None:
+    """Docmost CLI — manage your Docmost wiki from the terminal."""
+    _ensure_utf8_stdio()
+    cli_overrides: dict[str, str] = {}
+    if url is not None:
+        cli_overrides["url"] = url
+    if api_key is not None:
+        cli_overrides["api_key"] = api_key
+
+    state.config_path = Path(config) if config else None
+    state.settings = load_settings(
+        profile=profile,
+        config_path=state.config_path,
+        cli_overrides=cli_overrides if cli_overrides else None,
+    )
+    state.verbose = verbose
+    state.yes = yes
+
+
+def get_client() -> DocmostClient:
+    """Get or create the DocmostClient.
+
+    Called by commands that need API access. Creates the client lazily
+    so commands like 'config show' don't require a valid API connection.
+
+    Returns:
+        A configured DocmostClient instance.
+    """
+    if state.client is None:
+        if state.settings is None:
+            print_error("Not configured. Run 'docmost-cli config init'.", exit_code=1)
+        state.client = DocmostClient(state.settings, verbose=state.verbose)
+    return state.client
+
+
+# Register subcommand groups
+from docmost_cli.cli.config_cmd import config_app  # noqa: E402
+
+app.add_typer(config_app)
+
+from docmost_cli.cli.page import page_app  # noqa: E402
+
+app.add_typer(page_app)
+
+from docmost_cli.cli.space import space_app  # noqa: E402
+
+app.add_typer(space_app)
+
+from docmost_cli.cli.comment import comment_app  # noqa: E402
+
+app.add_typer(comment_app)
+
+from docmost_cli.cli.search import search_app  # noqa: E402
+
+app.add_typer(search_app)
+
+from docmost_cli.cli.attachment import attachment_app  # noqa: E402
+
+app.add_typer(attachment_app)
+
+from docmost_cli.cli.workspace import workspace_app  # noqa: E402
+
+app.add_typer(workspace_app)
+
+from docmost_cli.cli.user import user_app  # noqa: E402
+
+app.add_typer(user_app)
+
+from docmost_cli.cli.sync_cmd import sync_app  # noqa: E402
+
+app.add_typer(sync_app)