docmost-cli 0.4.0__py3-none-any.whl

docmost_cli/sync/__init__.py

@@ -0,0 +1,57 @@
+"""Sync module for pulling and pushing Docmost spaces to local files."""
+
+from docmost_cli.sync.diff import (
+    ChangeType,
+    PageChange,
+    SyncDiff,
+    compute_diff,
+)
+from docmost_cli.sync.frontmatter import (
+    parse_frontmatter,
+    read_sync_file,
+    serialize_frontmatter,
+    write_sync_file,
+)
+from docmost_cli.sync.manifest import (
+    MANIFEST_FILENAME,
+    MANIFEST_VERSION,
+    build_manifest,
+    build_page_entry,
+    compute_content_hash,
+    load_manifest,
+    sanitize_filename,
+    save_manifest,
+)
+from docmost_cli.sync.pull import (
+    PullResult,
+    flatten_tree,
+    pull_space,
+)
+from docmost_cli.sync.push import (
+    PushResult,
+    push_space,
+)
+
+__all__ = [
+    "ChangeType",
+    "MANIFEST_FILENAME",
+    "MANIFEST_VERSION",
+    "PageChange",
+    "PullResult",
+    "PushResult",
+    "SyncDiff",
+    "build_manifest",
+    "build_page_entry",
+    "compute_content_hash",
+    "compute_diff",
+    "flatten_tree",
+    "load_manifest",
+    "parse_frontmatter",
+    "pull_space",
+    "push_space",
+    "read_sync_file",
+    "sanitize_filename",
+    "save_manifest",
+    "serialize_frontmatter",
+    "write_sync_file",
+]

docmost_cli/sync/diff.py

@@ -0,0 +1,156 @@
+"""Compute diff between local sync files and manifest state."""
+
+import enum
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+__all__ = ["ChangeType", "PageChange", "SyncDiff", "compute_diff"]
+
+
+class ChangeType(enum.Enum):
+    """Types of changes detected between local and manifest."""
+
+    NEW = "new"
+    CONTENT_CHANGED = "content_changed"
+    TITLE_CHANGED = "title_changed"
+    MOVED = "moved"
+    ICON_CHANGED = "icon_changed"
+    DELETED = "deleted"
+
+
+@dataclass
+class PageChange:
+    """A detected change for a single page."""
+
+    page_id: str  # Empty string for NEW pages
+    filename: str
+    changes: set[ChangeType] = field(default_factory=set)
+    local_meta: dict[str, str] | None = None  # From frontmatter
+    local_body: str | None = None  # Markdown body
+    manifest_entry: dict[str, Any] | None = None  # From manifest
+
+
+@dataclass
+class SyncDiff:
+    """Summary of all changes between local files and manifest."""
+
+    new: list[PageChange] = field(default_factory=list)
+    modified: list[PageChange] = field(default_factory=list)
+    moved: list[PageChange] = field(default_factory=list)
+    deleted: list[PageChange] = field(default_factory=list)
+    unchanged: int = 0
+
+    @property
+    def has_changes(self) -> bool:
+        """Return True if any changes were detected."""
+        return bool(self.new or self.modified or self.moved or self.deleted)
+
+
+def compute_diff(manifest: dict, dir_path: Path) -> SyncDiff:
+    """Compute diff between local files and manifest.
+
+    Algorithm:
+    1. Load manifest pages dict (keyed by page_id)
+    2. Scan dir for .md files, parse frontmatter of each
+    3. For each local file:
+       - If has id AND id in manifest: compare hash, title, parent_id, icon
+       - If has no id (empty string): NEW
+       - If has id NOT in manifest: treat as existing, classify changes
+    4. For each manifest entry not matched by any local file: DELETED
+
+    A single page can appear in BOTH modified and moved if content AND parent changed.
+
+    Args:
+        manifest: Loaded manifest dict.
+        dir_path: Directory containing .md files.
+
+    Returns:
+        SyncDiff summarizing all changes.
+    """
+    from docmost_cli.sync.frontmatter import read_sync_file
+    from docmost_cli.sync.manifest import compute_content_hash
+
+    diff = SyncDiff()
+    manifest_pages = manifest.get("pages", {})
+    seen_ids: set[str] = set()
+
+    # Scan local .md files
+    for md_file in sorted(dir_path.glob("*.md")):
+        meta, body = read_sync_file(md_file)
+        page_id = meta.get("id", "").strip()
+
+        if not page_id:
+            # NEW page -- no server ID yet
+            change = PageChange(
+                page_id="",
+                filename=md_file.name,
+                changes={ChangeType.NEW},
+                local_meta=meta,
+                local_body=body,
+            )
+            diff.new.append(change)
+            continue
+
+        seen_ids.add(page_id)
+        manifest_entry = manifest_pages.get(page_id)
+
+        # Compute current content hash
+        current_hash = compute_content_hash(body)
+
+        # Determine changes
+        changes: set[ChangeType] = set()
+
+        if manifest_entry:
+            if current_hash != manifest_entry.get("content_hash", ""):
+                changes.add(ChangeType.CONTENT_CHANGED)
+            if meta.get("title", "") != manifest_entry.get("title", ""):
+                changes.add(ChangeType.TITLE_CHANGED)
+            if meta.get("icon", "") != manifest_entry.get("icon", ""):
+                changes.add(ChangeType.ICON_CHANGED)
+
+            # Compare parent_id (normalize empty string and None)
+            local_parent = meta.get("parent_id", "").strip() or None
+            manifest_parent = manifest_entry.get("parent_id") or None
+            if local_parent != manifest_parent:
+                changes.add(ChangeType.MOVED)
+        else:
+            # ID not in manifest -- treat as content-changed to trigger update
+            changes.add(ChangeType.CONTENT_CHANGED)
+
+        if not changes:
+            diff.unchanged += 1
+            continue
+
+        page_change = PageChange(
+            page_id=page_id,
+            filename=md_file.name,
+            changes=changes,
+            local_meta=meta,
+            local_body=body,
+            manifest_entry=manifest_entry,
+        )
+
+        # Categorize: if content or title or icon changed -> modified
+        # If parent changed -> moved (can be both modified AND moved)
+        if changes & {
+            ChangeType.CONTENT_CHANGED,
+            ChangeType.TITLE_CHANGED,
+            ChangeType.ICON_CHANGED,
+        }:
+            diff.modified.append(page_change)
+        if ChangeType.MOVED in changes:
+            diff.moved.append(page_change)
+
+    # Check for deleted pages (in manifest but no local file)
+    for page_id, entry in manifest_pages.items():
+        if page_id not in seen_ids:
+            change = PageChange(
+                page_id=page_id,
+                filename=entry.get("filename", ""),
+                changes={ChangeType.DELETED},
+                manifest_entry=entry,
+            )
+            diff.deleted.append(change)
+
+    return diff

docmost_cli/sync/frontmatter.py

@@ -0,0 +1,152 @@
+"""YAML frontmatter parser/serializer for sync files.
+
+Hand-rolled for flat key-value strings only — no PyYAML dependency.
+Compatible with the format produced by output/formatter.py:print_content_with_meta.
+"""
+
+from pathlib import Path
+
+__all__ = [
+    "parse_frontmatter",
+    "read_sync_file",
+    "serialize_frontmatter",
+    "write_sync_file",
+]
+
+# Fixed ordering for known sync fields, ensuring consistent diffs.
+_FIELD_ORDER = ("id", "title", "parent_id", "icon")
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    """Parse YAML frontmatter from text.
+
+    Splits on ``---`` delimiters.  Parses flat ``key: value`` pairs.
+    Values are stripped.  Keys are stripped.
+
+    Args:
+        text: Full file content (frontmatter + body).
+
+    Returns:
+        Tuple of (metadata dict, body string).
+        If no frontmatter found, returns (empty dict, original text).
+
+    Rules:
+        - First line must be ``---`` (stripped).
+        - Frontmatter ends at next ``---`` line.
+        - Each line in frontmatter is ``key: value`` (split on first ``:`` only).
+        - Lines without ``:`` are skipped.
+        - Empty values are stored as empty string.
+        - Body is everything after the closing ``---``, with one leading newline
+          stripped (if present).
+    """
+    # Normalise Windows line endings so splitting is consistent.
+    normalised = text.replace("\r\n", "\n")
+
+    lines = normalised.split("\n")
+
+    # First line must be '---'
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+
+    # Find closing '---'
+    closing_idx: int | None = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            closing_idx = i
+            break
+
+    if closing_idx is None:
+        # No closing delimiter — treat entire text as body.
+        return {}, text
+
+    # Parse key: value pairs between the delimiters.
+    metadata: dict[str, str] = {}
+    for line in lines[1:closing_idx]:
+        colon_pos = line.find(":")
+        if colon_pos == -1:
+            continue
+        key = line[:colon_pos].strip()
+        value = line[colon_pos + 1 :].strip()
+        if key:
+            metadata[key] = value
+
+    # Body is everything after the closing '---'.
+    # Strip exactly one leading newline (the newline right after '---').
+    body = "\n".join(lines[closing_idx + 1 :])
+    if body.startswith("\n"):
+        body = body[1:]
+
+    return metadata, body
+
+
+def serialize_frontmatter(metadata: dict[str, str], body: str) -> str:
+    """Combine metadata dict and body into frontmatter + markdown string.
+
+    Output format::
+
+        ---
+        key1: value1
+        key2: value2
+        ---
+
+        body content here
+
+    An empty line separates the closing ``---`` from the body.
+    Known sync fields (id, title, parent_id, icon) appear first in a fixed
+    order; any remaining keys follow in insertion order.
+
+    Args:
+        metadata: Flat key-value metadata.
+        body: Markdown body content.
+
+    Returns:
+        Combined string with YAML frontmatter header.
+    """
+    lines: list[str] = ["---"]
+
+    # Emit known fields in fixed order first.
+    seen: set[str] = set()
+    for key in _FIELD_ORDER:
+        if key in metadata:
+            lines.append(f"{key}: {metadata[key]}")
+            seen.add(key)
+
+    # Emit remaining fields in insertion order.
+    for key, value in metadata.items():
+        if key not in seen:
+            lines.append(f"{key}: {value}")
+
+    lines.append("---")
+    lines.append("")  # blank separator line between closing --- and body
+    lines.append("")  # ensures trailing \n after the blank line
+    return "\n".join(lines) + body
+
+
+def read_sync_file(path: Path) -> tuple[dict[str, str], str]:
+    """Read a sync ``.md`` file, returning parsed frontmatter and body.
+
+    Args:
+        path: Path to the markdown file.
+
+    Returns:
+        Tuple of (metadata dict, body markdown string).
+
+    Raises:
+        FileNotFoundError: If *path* does not exist.
+    """
+    content = path.read_text(encoding="utf-8")
+    return parse_frontmatter(content)
+
+
+def write_sync_file(path: Path, metadata: dict[str, str], body: str) -> None:
+    """Write a sync ``.md`` file with frontmatter.
+
+    Creates parent directories if needed.  Writes with UTF-8 encoding.
+
+    Args:
+        path: Destination file path.
+        metadata: Flat key-value metadata for the frontmatter header.
+        body: Markdown body content.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(serialize_frontmatter(metadata, body), encoding="utf-8")

docmost_cli/sync/manifest.py

@@ -0,0 +1,195 @@
+"""Manifest file handling for sync state tracking.
+
+The manifest (.docmost-manifest.json) records which pages have been synced,
+their content hashes, and filename mappings so that subsequent sync operations
+can detect local and remote changes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from docmost_cli.output.formatter import print_error
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = [
+    "MANIFEST_FILENAME",
+    "MANIFEST_VERSION",
+    "build_manifest",
+    "build_page_entry",
+    "compute_content_hash",
+    "load_manifest",
+    "sanitize_filename",
+    "save_manifest",
+]
+
+MANIFEST_FILENAME = ".docmost-manifest.json"
+MANIFEST_VERSION = 1
+
+_UNSAFE_CHARS_RE = re.compile(r'[/\\:*?"<>|]')
+_MULTI_DASH_RE = re.compile(r"-{2,}")
+_MAX_TITLE_LENGTH = 80
+_ID_PREFIX_LENGTH = 8
+
+
+def sanitize_filename(title: str, page_id: str) -> str:
+    """Generate a safe filename from page title and ID prefix.
+
+    Format: ``{sanitized_title}--{id_prefix_8chars}.md``
+
+    Rules applied to the title portion:
+    - Replace ``/ \\ : * ? " < > |`` with ``-``
+    - Collapse multiple consecutive dashes to a single dash
+    - Strip leading/trailing dashes and whitespace
+    - Limit title portion to 80 characters
+    - Fall back to ``untitled`` if the title sanitizes to empty
+
+    Args:
+        title: The page title (may contain any characters).
+        page_id: The full page UUID.
+
+    Returns:
+        A filesystem-safe filename ending in ``.md``.
+    """
+    sanitized = _UNSAFE_CHARS_RE.sub("-", title)
+    sanitized = _MULTI_DASH_RE.sub("-", sanitized)
+    sanitized = sanitized.strip("- \t\n\r")
+    sanitized = sanitized[:_MAX_TITLE_LENGTH]
+    # Re-strip in case truncation left a trailing dash
+    sanitized = sanitized.rstrip("- ")
+    if not sanitized:
+        sanitized = "untitled"
+    id_prefix = page_id[:_ID_PREFIX_LENGTH]
+    return f"{sanitized}--{id_prefix}.md"
+
+
+def compute_content_hash(content: str) -> str:
+    """Compute SHA-256 hash of content for change detection.
+
+    Strips trailing whitespace before hashing so that insignificant
+    trailing newlines do not cause false-positive diffs.
+
+    Args:
+        content: The text content to hash.
+
+    Returns:
+        Hash string in the format ``sha256:{hex_digest}``.
+    """
+    normalized = content.rstrip()
+    digest = hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def load_manifest(dir_path: Path) -> dict | None:
+    """Load the sync manifest from a directory.
+
+    Args:
+        dir_path: Directory that should contain the manifest file.
+
+    Returns:
+        The parsed manifest dict, or ``None`` if the file does not exist.
+
+    Raises:
+        SystemExit: If the manifest version is newer than what this CLI supports.
+    """
+    manifest_path = dir_path / MANIFEST_FILENAME
+    try:
+        with manifest_path.open("r", encoding="utf-8") as f:
+            manifest: dict = json.load(f)
+    except FileNotFoundError:
+        return None
+    version = manifest.get("version", 0)
+    if version > MANIFEST_VERSION:
+        print_error(
+            f"Manifest version {version} is not supported by this CLI "
+            f"(max supported: {MANIFEST_VERSION}). Please upgrade docmost-cli."
+        )
+    return manifest
+
+
+def save_manifest(dir_path: Path, manifest: dict) -> None:
+    """Save the sync manifest to a directory as pretty-printed JSON.
+
+    Uses atomic write (write to ``.tmp`` then rename) to avoid
+    partial writes on crash.
+
+    Args:
+        dir_path: Directory where the manifest file will be written.
+        manifest: The manifest dict to persist.
+    """
+    manifest_path = dir_path / MANIFEST_FILENAME
+    tmp_path = dir_path / (MANIFEST_FILENAME + ".tmp")
+    with tmp_path.open("w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    tmp_path.replace(manifest_path)
+
+
+def build_manifest(
+    space_slug: str,
+    space_id: str,
+    pages: list[dict],
+) -> dict:
+    """Build a new manifest dict from page data.
+
+    Args:
+        space_slug: The space slug identifier (e.g. ``"eng"``).
+        space_id: The space UUID.
+        pages: List of dicts, each with keys:
+            ``id``, ``title``, ``filename``, ``parent_id``, ``icon``,
+            ``content_hash``.
+
+    Returns:
+        A complete manifest dict ready for :func:`save_manifest`.
+    """
+    now = datetime.now(UTC).isoformat()
+    pages_by_id: dict[str, dict] = {}
+    for page in pages:
+        pages_by_id[page["id"]] = build_page_entry(
+            title=page["title"],
+            filename=page["filename"],
+            parent_id=page.get("parent_id"),
+            icon=page.get("icon", ""),
+            content_hash=page["content_hash"],
+        )
+    return {
+        "version": MANIFEST_VERSION,
+        "space_slug": space_slug,
+        "space_id": space_id,
+        "synced_at": now,
+        "pages": pages_by_id,
+    }
+
+
+def build_page_entry(
+    title: str,
+    filename: str,
+    parent_id: str | None,
+    icon: str,
+    content_hash: str,
+) -> dict:
+    """Build a single page entry for inclusion in the manifest.
+
+    Args:
+        title: Page title.
+        filename: The sanitized local filename.
+        parent_id: Parent page ID, or ``None`` for root pages.
+        icon: Page icon (emoji or empty string).
+        content_hash: Content hash from :func:`compute_content_hash`.
+
+    Returns:
+        A dict representing one page in the manifest ``pages`` map.
+    """
+    return {
+        "title": title,
+        "filename": filename,
+        "parent_id": parent_id,
+        "icon": icon,
+        "content_hash": content_hash,
+    }