docmost-cli 0.4.0__py3-none-any.whl

docmost_cli/config/settings.py

@@ -0,0 +1,23 @@
+"""Pydantic settings model for Docmost CLI configuration.
+
+Resolution order: CLI flags > env vars > config file > defaults.
+The config file is loaded by store.py and merged separately.
+"""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["DocmostSettings"]
+
+
+class DocmostSettings(BaseSettings):
+    """Typed settings for a Docmost CLI session."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="DOCMOST_",
+    )
+
+    url: str | None = None
+    api_key: str | None = None
+    email: str | None = None
+    password: str | None = None
+    profile: str = "default"

docmost_cli/config/store.py

@@ -0,0 +1,160 @@
+"""Config file read/write and settings factory.
+
+Handles TOML config file at ~/.config/docmost-cli/config.toml
+and session cache at ~/.cache/docmost-cli/session.json.
+"""
+
+import os
+import tomllib
+from pathlib import Path
+
+import tomli_w
+
+from docmost_cli.config.settings import DocmostSettings
+
+__all__ = [
+    "get_cache_dir",
+    "get_config_path",
+    "load_settings",
+    "read_config",
+    "read_profile",
+    "set_config_value",
+    "write_config",
+]
+
+APP_NAME = "docmost-cli"
+
+
+def get_config_path(override: str | None = None) -> Path:
+    """Return the config file path.
+
+    Args:
+        override: Explicit path to use instead of the default.
+
+    Returns:
+        Path to the config TOML file.
+    """
+    if override:
+        return Path(override)
+    config_home = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(config_home) if config_home else Path.home() / ".config"
+    return base / APP_NAME / "config.toml"
+
+
+def get_cache_dir() -> Path:
+    """Return the cache directory path for session tokens."""
+    cache_home = os.environ.get("XDG_CACHE_HOME")
+    base = Path(cache_home) if cache_home else Path.home() / ".cache"
+    return base / APP_NAME
+
+
+def read_config(config_path: Path | None = None) -> dict[str, dict[str, str]]:
+    """Read the full TOML config, returning all profiles.
+
+    Args:
+        config_path: Path to config file. Uses default if None.
+
+    Returns:
+        Dict of profile name → dict of key-value pairs.
+    """
+    path = config_path or get_config_path()
+    if not path.exists():
+        return {}
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def read_profile(profile: str = "default", config_path: Path | None = None) -> dict[str, str]:
+    """Read a specific profile from the config file.
+
+    Args:
+        profile: Profile name to read.
+        config_path: Path to config file. Uses default if None.
+
+    Returns:
+        Dict of config values for the profile. Empty dict if not found.
+    """
+    config = read_config(config_path)
+    return config.get(profile, {})
+
+
+def write_config(config: dict[str, dict[str, str]], config_path: Path | None = None) -> None:
+    """Write the full config dict to the TOML file.
+
+    Creates parent directories if needed. Writes atomically via temp file.
+
+    Args:
+        config: Full config dict (profile name → key-value pairs).
+        config_path: Path to config file. Uses default if None.
+    """
+    path = config_path or get_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(".tmp")
+    with open(tmp_path, "wb") as f:
+        tomli_w.dump(config, f)
+    tmp_path.replace(path)
+
+
+def set_config_value(
+    key: str,
+    value: str,
+    profile: str = "default",
+    config_path: Path | None = None,
+) -> None:
+    """Set a single key in a profile, creating profile/file if needed.
+
+    Args:
+        key: Config key to set.
+        value: Value to set.
+        profile: Profile to update.
+        config_path: Path to config file. Uses default if None.
+    """
+    config = read_config(config_path)
+    if profile not in config:
+        config[profile] = {}
+    config[profile][key] = value
+    write_config(config, config_path)
+
+
+def load_settings(
+    profile: str = "default",
+    config_path: Path | None = None,
+    cli_overrides: dict[str, str] | None = None,
+) -> DocmostSettings:
+    """Load settings with full priority chain.
+
+    Priority: CLI overrides > env vars > config file > defaults.
+
+    In pydantic-settings v2, init kwargs beat env vars. So we construct
+    with no kwargs first (picks up env vars), then fill in config file
+    values only for fields that are still unset, then apply CLI overrides.
+
+    Args:
+        profile: Config profile name to load.
+        config_path: Path to config file. Uses default if None.
+        cli_overrides: Dict of CLI flag overrides (highest priority).
+
+    Returns:
+        Fully resolved DocmostSettings instance.
+    """
+    file_values = read_profile(profile, config_path)
+
+    # Step 1: Construct with no init kwargs — picks up env vars.
+    settings = DocmostSettings()
+
+    # Step 2: Fill in config file values only where env didn't set a value.
+    updates: dict[str, str] = {}
+    for key, value in file_values.items():
+        if key in DocmostSettings.model_fields and getattr(settings, key) is None:
+            updates[key] = value
+    updates["profile"] = profile
+    if updates:
+        settings = settings.model_copy(update=updates)
+
+    # Step 3: CLI overrides beat everything.
+    if cli_overrides:
+        non_none = {k: v for k, v in cli_overrides.items() if v is not None}
+        if non_none:
+            settings = settings.model_copy(update=non_none)
+
+    return settings

docmost_cli/convert/__init__.py

@@ -0,0 +1,3 @@
+"""ProseMirror ↔ Markdown conversion."""
+
+__all__: list[str] = []

docmost_cli/convert/prosemirror_to_md.py

@@ -0,0 +1,300 @@
+"""ProseMirror JSON → Markdown converter.
+
+Handles all Docmost node types and marks, converting ProseMirror
+document trees into GitHub-Flavored Markdown.
+"""
+
+from typing import Any
+
+__all__ = ["convert_to_markdown"]
+
+
+class ProseMirrorConverter:
+    """Recursive ProseMirror node walker that produces Markdown output."""
+
+    def __init__(self) -> None:
+        self._indent = 0
+        self._list_type: list[str] = []  # stack: "bullet", "ordered", "task"
+        self._ordered_counter: list[int] = []  # counter per ordered list level
+
+    def convert(self, doc: dict[str, Any]) -> str:
+        """Convert a ProseMirror document to Markdown.
+
+        Args:
+            doc: ProseMirror document dict (root node with type "doc").
+
+        Returns:
+            Markdown string ending with a single newline.
+        """
+        if not isinstance(doc, dict):
+            return ""
+        result = self._walk_node(doc)
+        return result.rstrip("\n") + "\n"
+
+    # -- Dispatch -----------------------------------------------------------
+
+    def _walk_node(self, node: dict[str, Any]) -> str:
+        """Dispatch to the handler for a node's type."""
+        node_type = node.get("type", "")
+        handler = getattr(self, f"_node_{node_type}", None)
+        if handler:
+            return handler(node)
+        # Unknown node: try to extract content recursively
+        return self._walk_children(node)
+
+    def _walk_children(self, node: dict[str, Any]) -> str:
+        """Walk all child nodes and concatenate their output."""
+        return "".join(self._walk_node(child) for child in node.get("content", []))
+
+    # -- Block nodes --------------------------------------------------------
+
+    def _node_doc(self, node: dict[str, Any]) -> str:
+        return self._walk_children(node)
+
+    def _node_paragraph(self, node: dict[str, Any]) -> str:
+        text = self._render_inline(node.get("content", []))
+        # Inside a list item, don't add double newline
+        if self._indent > 0:
+            return text
+        return text + "\n\n"
+
+    def _node_heading(self, node: dict[str, Any]) -> str:
+        level = node.get("attrs", {}).get("level", 1)
+        text = self._render_inline(node.get("content", []))
+        return "#" * level + " " + text + "\n\n"
+
+    def _node_bulletList(self, node: dict[str, Any]) -> str:
+        return self._handle_list(node, "bullet")
+
+    def _node_orderedList(self, node: dict[str, Any]) -> str:
+        return self._handle_list(node, "ordered")
+
+    def _node_taskList(self, node: dict[str, Any]) -> str:
+        return self._handle_list(node, "task")
+
+    def _handle_list(self, node: dict[str, Any], list_type: str) -> str:
+        self._list_type.append(list_type)
+        self._indent += 1
+        if list_type == "ordered":
+            self._ordered_counter.append(0)
+
+        result = ""
+        for child in node.get("content", []):
+            if child.get("type") in ("listItem", "taskItem"):
+                result += self._handle_list_item(child)
+
+        self._indent -= 1
+        self._list_type.pop()
+        if list_type == "ordered":
+            self._ordered_counter.pop()
+
+        # Add trailing newline after top-level list
+        if self._indent == 0:
+            result += "\n"
+        return result
+
+    def _node_listItem(self, node: dict[str, Any]) -> str:
+        return self._handle_list_item(node)
+
+    def _node_taskItem(self, node: dict[str, Any]) -> str:
+        return self._handle_list_item(node)
+
+    def _handle_list_item(self, node: dict[str, Any]) -> str:
+        indent = "  " * (self._indent - 1)
+        current_type = self._list_type[-1] if self._list_type else "bullet"
+
+        # Determine prefix
+        if current_type == "task":
+            checked = node.get("attrs", {}).get("checked", False)
+            prefix = "- [x] " if checked else "- [ ] "
+        elif current_type == "ordered":
+            self._ordered_counter[-1] += 1
+            prefix = f"{self._ordered_counter[-1]}. "
+        else:
+            prefix = "- "
+
+        # Separate inline content from nested lists
+        text_parts: list[str] = []
+        nested_parts: list[str] = []
+        for child in node.get("content", []):
+            child_type = child.get("type", "")
+            if child_type in ("bulletList", "orderedList", "taskList"):
+                nested_parts.append(self._walk_node(child))
+            elif child_type == "paragraph":
+                text_parts.append(self._render_inline(child.get("content", [])))
+            else:
+                text_parts.append(self._walk_node(child))
+
+        text = " ".join(t.strip() for t in text_parts if t.strip())
+        result = indent + prefix + text + "\n"
+        result += "".join(nested_parts)
+        return result
+
+    def _node_codeBlock(self, node: dict[str, Any]) -> str:
+        lang = node.get("attrs", {}).get("language", "")
+        code = self._render_inline(node.get("content", []))
+        return f"```{lang}\n{code}\n```\n\n"
+
+    def _node_blockquote(self, node: dict[str, Any]) -> str:
+        content = self._walk_children(node)
+        lines = content.rstrip("\n").split("\n")
+        quoted = "\n".join("> " + line for line in lines)
+        return quoted + "\n\n"
+
+    def _node_horizontalRule(self, node: dict[str, Any]) -> str:
+        return "---\n\n"
+
+    def _node_table(self, node: dict[str, Any]) -> str:
+        rows = node.get("content", [])
+        if not rows:
+            return ""
+
+        output_lines: list[str] = []
+        for i, row in enumerate(rows):
+            cells = row.get("content", [])
+            cell_texts = []
+            for cell in cells:
+                # Cell content is usually paragraphs
+                text = self._walk_children(cell).strip().replace("\n", " ")
+                # Escape pipes in cell content
+                text = text.replace("|", "\\|")
+                cell_texts.append(text)
+
+            output_lines.append("| " + " | ".join(cell_texts) + " |")
+
+            # Separator after header row
+            if i == 0:
+                output_lines.append("|" + "|".join("---" for _ in cell_texts) + "|")
+
+        return "\n".join(output_lines) + "\n\n"
+
+    def _node_image(self, node: dict[str, Any]) -> str:
+        attrs = node.get("attrs", {})
+        alt = attrs.get("alt", "")
+        src = attrs.get("src", "")
+        title = attrs.get("title", "")
+        if title:
+            return f'![{alt}]({src} "{title}")\n\n'
+        return f"![{alt}]({src})\n\n"
+
+    def _node_hardBreak(self, node: dict[str, Any]) -> str:
+        return "\n"
+
+    def _node_callout(self, node: dict[str, Any]) -> str:
+        callout_type = node.get("attrs", {}).get("type", "info")
+        content = self._walk_children(node).strip()
+        return f"> **{callout_type}**: {content}\n\n"
+
+    def _node_details(self, node: dict[str, Any]) -> str:
+        summary = ""
+        body = ""
+        for child in node.get("content", []):
+            if child.get("type") == "detailsSummary":
+                summary = self._render_inline(child.get("content", []))
+            elif child.get("type") == "detailsContent":
+                body = self._walk_children(child).strip()
+        return f"<details>\n<summary>{summary.strip()}</summary>\n\n{body}\n</details>\n\n"
+
+    def _node_detailsSummary(self, node: dict[str, Any]) -> str:
+        return self._render_inline(node.get("content", []))
+
+    def _node_detailsContent(self, node: dict[str, Any]) -> str:
+        return self._walk_children(node)
+
+    def _node_mathBlock(self, node: dict[str, Any]) -> str:
+        content = self._render_inline(node.get("content", []))
+        return f"$$\n{content.strip()}\n$$\n\n"
+
+    def _node_embed(self, node: dict[str, Any]) -> str:
+        src = node.get("attrs", {}).get("src", "")
+        return f"[Embed: {src}]\n\n"
+
+    def _node_drawio(self, node: dict[str, Any]) -> str:
+        return "[Diagram: drawio]\n\n"
+
+    def _node_excalidraw(self, node: dict[str, Any]) -> str:
+        return "[Diagram: excalidraw]\n\n"
+
+    # -- Inline rendering ---------------------------------------------------
+
+    def _render_inline(self, content: list[dict[str, Any]]) -> str:
+        """Render inline nodes (text with marks, hard breaks, etc.)."""
+        parts: list[str] = []
+        for node in content or []:
+            node_type = node.get("type", "")
+            if node_type == "text":
+                text = node.get("text", "")
+                marks = node.get("marks", [])
+                parts.append(self._apply_marks(text, marks))
+            elif node_type == "hardBreak":
+                parts.append("\n")
+            elif node_type == "image":
+                attrs = node.get("attrs", {})
+                alt = attrs.get("alt", "")
+                src = attrs.get("src", "")
+                parts.append(f"![{alt}]({src})")
+            else:
+                # Other inline nodes
+                parts.append(self._walk_node(node))
+        return "".join(parts)
+
+    def _apply_marks(self, text: str, marks: list[dict[str, Any]]) -> str:
+        """Wrap text in Markdown mark delimiters."""
+        if not marks:
+            return text
+
+        # Sort by precedence: outermost wraps first
+        precedence = {
+            "link": 0,
+            "bold": 1,
+            "italic": 2,
+            "strike": 3,
+            "code": 4,
+            "highlight": 5,
+            "underline": 6,
+        }
+        sorted_marks = sorted(
+            marks,
+            key=lambda m: precedence.get(m.get("type", ""), 99),
+            reverse=True,
+        )
+
+        for mark in sorted_marks:
+            text = self._apply_single_mark(text, mark)
+        return text
+
+    @staticmethod
+    def _apply_single_mark(text: str, mark: dict[str, Any]) -> str:
+        """Apply a single mark to text."""
+        mark_type = mark.get("type", "")
+        attrs = mark.get("attrs", {})
+
+        if mark_type == "bold":
+            return f"**{text}**"
+        if mark_type == "italic":
+            return f"*{text}*"
+        if mark_type == "code":
+            return f"`{text}`"
+        if mark_type == "strike":
+            return f"~~{text}~~"
+        if mark_type == "link":
+            href = attrs.get("href", "")
+            return f"[{text}]({href})"
+        if mark_type == "highlight":
+            return f"=={text}=="
+        if mark_type == "underline":
+            return f"<u>{text}</u>"
+        # Unknown mark: passthrough
+        return text
+
+
+def convert_to_markdown(doc: dict[str, Any]) -> str:
+    """Convert a ProseMirror document to Markdown.
+
+    Args:
+        doc: ProseMirror document dict.
+
+    Returns:
+        Markdown string.
+    """
+    return ProseMirrorConverter().convert(doc)

docmost_cli/models/__init__.py

@@ -0,0 +1,3 @@
+"""Pydantic data models for Docmost API types."""
+
+__all__: list[str] = []

docmost_cli/models/common.py

@@ -0,0 +1,3 @@
+"""Shared data models used across the project."""
+
+__all__: list[str] = []

docmost_cli/output/__init__.py

@@ -0,0 +1,17 @@
+"""Output formatting helpers enforcing stdout/stderr separation."""
+
+from docmost_cli.output.formatter import (
+    print_content,
+    print_content_with_meta,
+    print_error,
+    print_key_value,
+    print_result,
+)
+
+__all__ = [
+    "print_content",
+    "print_content_with_meta",
+    "print_error",
+    "print_key_value",
+    "print_result",
+]

docmost_cli/output/formatter.py

@@ -0,0 +1,85 @@
+"""Output dispatch: stdout/stderr separation for all command types."""
+
+import json
+import sys
+from typing import Any, NoReturn
+
+from rich.console import Console
+
+__all__ = [
+    "print_content",
+    "print_content_with_meta",
+    "print_error",
+    "print_key_value",
+    "print_result",
+    "print_table",
+]
+
+_err_console = Console(stderr=True)
+
+
+def print_content(content: str) -> None:
+    """Print content (Markdown) directly to stdout."""
+    sys.stdout.write(content)
+
+
+def print_content_with_meta(content: str, meta: dict[str, Any]) -> None:
+    """Print YAML frontmatter + Markdown content to stdout."""
+    lines = ["---"]
+    for key, value in meta.items():
+        lines.append(f"{key}: {value}")
+    lines.append("---")
+    lines.append("")
+    sys.stdout.write("\n".join(lines))
+    sys.stdout.write(content)
+
+
+def print_key_value(data: dict[str, Any], key_style: str = "bold") -> None:
+    """Print key-value pairs for single-item info display.
+
+    Args:
+        data: Dictionary of key-value pairs to display.
+        key_style: Rich style string for keys column.
+    """
+    from rich.table import Table
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style=key_style)
+    table.add_column()
+    for key, value in data.items():
+        if value is not None and value != "":
+            table.add_row(str(key), str(value))
+
+    console = Console()
+    console.print(table)
+
+
+def print_table(rows: list[dict[str, Any]], columns: list[str], json_mode: bool = False) -> None:
+    """Print as rich table or JSON array depending on mode."""
+    if json_mode:
+        filtered = [{col: row.get(col) for col in columns} for row in rows]
+        sys.stdout.write(json.dumps(filtered, indent=2, default=str) + "\n")
+        return
+
+    from rich.table import Table
+
+    table = Table()
+    for col in columns:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*(str(row.get(col, "")) for col in columns))
+
+    console = Console()
+    console.print(table)
+
+
+def print_result(resource_id: str, message: str) -> None:
+    """Print resource ID to stdout, confirmation to stderr."""
+    sys.stdout.write(resource_id + "\n")
+    _err_console.print(message)
+
+
+def print_error(message: str, exit_code: int = 1) -> NoReturn:
+    """Print error to stderr and exit with given code."""
+    _err_console.print(f"[red]Error:[/red] {message}")
+    raise SystemExit(exit_code)

docmost_cli/output/tree.py

@@ -0,0 +1,66 @@
+"""Tree view rendering for hierarchical page lists.
+
+Renders nested page structures using Unicode box-drawing characters.
+"""
+
+from typing import Any
+
+from rich.console import Console
+
+__all__ = ["print_tree"]
+
+MAX_TITLE_LEN = 60
+_console = Console()
+
+
+def print_tree(pages: list[dict[str, Any]]) -> None:
+    """Render a nested page tree using box-drawing characters.
+
+    Expects pages with nested 'children' arrays, as returned by
+    POST /pages/sidebar-pages.
+
+    Args:
+        pages: List of page dicts, each may have a 'children' key.
+    """
+    for i, page in enumerate(pages):
+        is_last = i == len(pages) - 1
+        _print_node(page, "", is_last)
+
+
+def _print_node(
+    page: dict[str, Any],
+    prefix: str,
+    is_last: bool,
+) -> None:
+    """Print a single tree node and recurse into children."""
+    connector = "\\-- " if is_last else "+-- "
+
+    icon = page.get("icon", "") or ""
+    title = page.get("title", page.get("id", "???"))
+
+    # Truncate long titles
+    if len(title) > MAX_TITLE_LEN:
+        title = title[: MAX_TITLE_LEN - 3] + "..."
+
+    # Rich uses LegacyWindowsRenderer which bypasses sys.stdout encoding.
+    # Strip emoji that can't be encoded on Windows cp1252.
+    safe_icon = ""
+    if icon:
+        try:
+            icon.encode("cp1252")
+            safe_icon = icon
+        except (UnicodeEncodeError, UnicodeDecodeError):
+            pass
+
+    label = f"{safe_icon} {title}".strip() if safe_icon else title
+    _console.print(f"{prefix}{connector}{label}")
+
+    # Recurse into children
+    children = page.get("children", [])
+    if not children:
+        return
+
+    child_prefix = prefix + ("    " if is_last else "|   ")
+    for j, child in enumerate(children):
+        child_is_last = j == len(children) - 1
+        _print_node(child, child_prefix, child_is_last)