docmost-cli 0.4.0__py3-none-any.whl

docmost_cli/sync/pull.py

@@ -0,0 +1,158 @@
+"""Pull space pages from Docmost server to local directory."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from docmost_cli.api.client import DocmostClient
+from docmost_cli.output.formatter import _err_console as _err
+
+__all__ = ["PullResult", "flatten_tree", "pull_space"]
+
+
+@dataclass
+class PullResult:
+    """Result of a pull operation."""
+
+    pages_pulled: int
+    dir_path: Path
+
+
+def flatten_tree(
+    pages: list[dict[str, Any]],
+    parent_id: str | None = None,
+) -> list[dict[str, Any]]:
+    """Flatten nested page tree into a flat list with parent_id.
+
+    Args:
+        pages: Nested page tree from build_page_tree.
+        parent_id: Parent page ID for current level.
+
+    Returns:
+        Flat list of dicts with: id, title, icon, parent_id
+    """
+    result: list[dict[str, Any]] = []
+    for page in pages:
+        result.append(
+            {
+                "id": page["id"],
+                "title": page.get("title", ""),
+                "icon": page.get("icon") or "",
+                "parent_id": parent_id,
+            }
+        )
+        children = page.get("children", [])
+        if children:
+            result.extend(flatten_tree(children, parent_id=page["id"]))
+    return result
+
+
+def pull_space(
+    client: DocmostClient,
+    space_slug: str,
+    dir_path: Path,
+    *,
+    force: bool = False,
+) -> PullResult:
+    """Pull all pages from a space to a local directory.
+
+    Algorithm:
+    1. Resolve space slug to ID
+    2. Build full page tree
+    3. Flatten tree to list with parent_id
+    4. For each page: fetch content, convert to markdown, write file
+    5. Write manifest LAST (atomic commit point)
+
+    Args:
+        client: Authenticated Docmost client.
+        space_slug: Space slug identifier.
+        dir_path: Target directory path.
+        force: Overwrite existing files without warning.
+
+    Returns:
+        PullResult with count and path.
+    """
+    from docmost_cli.api.pages import build_page_tree, get_page_content
+    from docmost_cli.api.spaces import resolve_space_id
+    from docmost_cli.convert.prosemirror_to_md import convert_to_markdown
+    from docmost_cli.output.formatter import print_error
+    from docmost_cli.sync.frontmatter import write_sync_file
+    from docmost_cli.sync.manifest import (
+        build_manifest,
+        build_page_entry,
+        compute_content_hash,
+        load_manifest,
+        sanitize_filename,
+        save_manifest,
+    )
+
+    # 1. Resolve space
+    space_id = resolve_space_id(client, space_slug)
+
+    # 2. Build page tree
+    _err.print(f"Fetching page tree for '{space_slug}'...")
+    tree = build_page_tree(client, space_id)
+
+    # 3. Flatten
+    flat_pages = flatten_tree(tree)
+    total = len(flat_pages)
+
+    if total == 0:
+        # Empty space -- create dir + empty manifest
+        dir_path.mkdir(parents=True, exist_ok=True)
+        manifest = build_manifest(space_slug, space_id, [])
+        save_manifest(dir_path, manifest)
+        _err.print(f"Pulled 0 pages from '{space_slug}' -> {dir_path}")
+        return PullResult(pages_pulled=0, dir_path=dir_path)
+
+    # 4. Check target directory
+    if dir_path.exists():
+        existing_manifest = load_manifest(dir_path)
+        if existing_manifest and not force:
+            print_error(
+                f"Directory '{dir_path}' already has synced data. Use --force to overwrite."
+            )
+        # If dir exists with no manifest OR force is set, proceed
+
+    dir_path.mkdir(parents=True, exist_ok=True)
+
+    # 5. Fetch content and write files
+    page_entries: list[dict[str, Any]] = []
+    for i, page_info in enumerate(flat_pages, 1):
+        page_id = page_info["id"]
+        title = page_info["title"]
+        _err.print(f"Pulling {i}/{total}: {title}")
+
+        # Fetch content
+        content_data = get_page_content(client, page_id)
+        pm_content = content_data.get("content")
+
+        markdown = convert_to_markdown(pm_content) if pm_content else ""
+
+        # Generate filename and write file
+        filename = sanitize_filename(title, page_id)
+        metadata = {
+            "id": page_id,
+            "title": title,
+            "parent_id": page_info["parent_id"] or "",
+            "icon": page_info["icon"],
+        }
+        write_sync_file(dir_path / filename, metadata, markdown)
+
+        # Build manifest entry
+        content_hash = compute_content_hash(markdown)
+        entry = build_page_entry(
+            title=title,
+            filename=filename,
+            parent_id=page_info["parent_id"],
+            icon=page_info["icon"],
+            content_hash=content_hash,
+        )
+        page_entries.append({"id": page_id, **entry})
+
+    # 6. Write manifest LAST
+    manifest = build_manifest(space_slug, space_id, page_entries)
+    save_manifest(dir_path, manifest)
+
+    _err.print(f"Pulled {total} pages from '{space_slug}' -> {dir_path}")
+    return PullResult(pages_pulled=total, dir_path=dir_path)

docmost_cli/sync/push.py

@@ -0,0 +1,374 @@
+"""Push local changes to Docmost server."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from docmost_cli.output.formatter import _err_console as _err
+from docmost_cli.sync.diff import ChangeType, SyncDiff
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from docmost_cli.api.client import DocmostClient
+
+__all__ = ["PushResult", "push_space"]
+
+
+@dataclass
+class PushResult:
+    """Result of a push operation."""
+
+    created: int = 0
+    updated: int = 0
+    moved: int = 0
+    deleted: int = 0
+    unchanged: int = 0
+    id_remaps: dict[str, str] = field(default_factory=dict)  # old_id -> new_id
+
+
+def push_space(
+    client: DocmostClient,
+    space_slug: str,
+    dir_path: Path,
+    *,
+    dry_run: bool = False,
+    delete: bool = False,
+    diff: SyncDiff | None = None,
+) -> PushResult:
+    """Push local changes to Docmost server.
+
+    Args:
+        client: Authenticated Docmost client.
+        space_slug: Space slug identifier.
+        dir_path: Directory containing synced files.
+        dry_run: If True, show plan without executing changes.
+        delete: If True, delete server pages not found locally.
+        diff: Pre-computed diff (avoids recomputing if caller already has it).
+
+    Returns:
+        PushResult with counts and any ID remaps.
+    """
+    from docmost_cli.api.pages import (
+        POSITION_FIRST,
+        create_and_place_page,
+        delete_page,
+        move_page,
+        try_update_page_content,
+        update_page_meta,
+    )
+    from docmost_cli.api.spaces import resolve_space_id
+    from docmost_cli.output.formatter import print_error
+    from docmost_cli.sync.diff import compute_diff
+    from docmost_cli.sync.frontmatter import write_sync_file
+    from docmost_cli.sync.manifest import (
+        build_page_entry,
+        compute_content_hash,
+        load_manifest,
+        save_manifest,
+    )
+
+    space_id = resolve_space_id(client, space_slug)
+
+    manifest = load_manifest(dir_path)
+    if manifest is None:
+        print_error(f"No manifest found in '{dir_path}'. Run 'sync pull' first.")
+
+    if diff is None:
+        diff = compute_diff(manifest, dir_path)
+    result = PushResult(unchanged=diff.unchanged)
+
+    if not diff.has_changes:
+        _err.print("No changes to push.")
+        return result
+
+    # Display summary
+    _print_summary(diff)
+
+    if dry_run:
+        _print_dry_run(diff)
+        return result
+
+    # --- Execute changes ---
+
+    enterprise: bool | None = None  # Cached edition detection
+    id_remap: dict[str, str] = {}  # old_id -> new_id
+
+    # Phase A: Create new pages (topological order)
+    existing_ids = set(manifest.get("pages", {}).keys())
+    sorted_new = _topological_sort(diff.new, existing_ids)
+
+    for change in sorted_new:
+        meta = change.local_meta or {}
+        body = change.local_body or ""
+        title = meta.get("title", "Untitled")
+        parent_id = meta.get("parent_id", "").strip() or None
+        icon = meta.get("icon", "").strip()
+
+        # Resolve parent_id through remap table
+        if parent_id and parent_id in id_remap:
+            parent_id = id_remap[parent_id]
+
+        _err.print(f"  Creating: {title}")
+        new_id = create_and_place_page(
+            client,
+            space_id=space_id,
+            title=title,
+            content=body,
+            parent_page_id=parent_id,
+            icon=icon,
+        )
+
+        # Write ID back to frontmatter
+        meta["id"] = new_id
+        write_sync_file(dir_path / change.filename, meta, body)
+
+        # Update manifest
+        content_hash = compute_content_hash(body)
+        manifest["pages"][new_id] = build_page_entry(
+            title=title,
+            filename=change.filename,
+            parent_id=parent_id,
+            icon=icon,
+            content_hash=content_hash,
+        )
+        existing_ids.add(new_id)
+        result.created += 1
+
+    # Phase B: Update modified pages
+    for change in diff.modified:
+        meta = change.local_meta or {}
+        body = change.local_body or ""
+        page_id = change.page_id
+        title = meta.get("title", "")
+        parent_id = meta.get("parent_id", "").strip() or None
+        icon = meta.get("icon", "").strip()
+
+        has_content_change = ChangeType.CONTENT_CHANGED in change.changes
+        has_meta_change = bool(change.changes & {ChangeType.TITLE_CHANGED, ChangeType.ICON_CHANGED})
+
+        # Content update
+        if has_content_change:
+            if enterprise is None:
+                # First attempt: probe and update in one call
+                enterprise = try_update_page_content(client, page_id=page_id, content=body)
+                if enterprise:
+                    _err.print(f"  Updated (Enterprise): {title}")
+            elif enterprise:
+                try_update_page_content(client, page_id=page_id, content=body)
+                _err.print(f"  Updated: {title}")
+
+            if not enterprise:
+                # Community: safe create-then-delete
+                _err.print(f"  Replacing: {title}")
+                new_id = _community_replace(
+                    client,
+                    space_id=space_id,
+                    old_page_id=page_id,
+                    title=title,
+                    content=body,
+                    parent_id=parent_id,
+                    icon=icon,
+                )
+                id_remap[page_id] = new_id
+                meta["id"] = new_id
+                write_sync_file(dir_path / change.filename, meta, body)
+                manifest["pages"].pop(page_id, None)
+                page_id = new_id
+
+        # Meta update (title/icon) — skip if community update already recreated the page
+        if has_meta_change and not (has_content_change and not enterprise):
+            _err.print(f"  Metadata: {title}")
+            update_page_meta(
+                client,
+                page_id=page_id,
+                title=title if ChangeType.TITLE_CHANGED in change.changes else None,
+                icon=icon if ChangeType.ICON_CHANGED in change.changes else None,
+            )
+
+        # Update manifest entry
+        content_hash = compute_content_hash(body)
+        manifest["pages"][page_id] = build_page_entry(
+            title=title,
+            filename=change.filename,
+            parent_id=parent_id,
+            icon=icon,
+            content_hash=content_hash,
+        )
+        result.updated += 1
+
+    # Phase B2: Move pages (that weren't already handled as part of modified)
+    modified_ids = {c.page_id for c in diff.modified}
+    for change in diff.moved:
+        if change.page_id in modified_ids:
+            continue
+
+        meta = change.local_meta or {}
+        page_id = change.page_id
+        parent_id = meta.get("parent_id", "").strip() or None
+        title = meta.get("title", page_id)
+
+        # Check remap
+        if page_id in id_remap:
+            page_id = id_remap[page_id]
+        if parent_id and parent_id in id_remap:
+            parent_id = id_remap[parent_id]
+
+        _err.print(f"  Moving: {title}")
+        move_page(
+            client,
+            page_id=page_id,
+            parent_page_id=parent_id,
+            position=POSITION_FIRST,
+        )
+
+        # Update manifest
+        if page_id in manifest["pages"]:
+            manifest["pages"][page_id]["parent_id"] = parent_id
+        result.moved += 1
+
+    # Phase C: Deletions
+    if diff.deleted:
+        if delete:
+            for change in diff.deleted:
+                entry = change.manifest_entry or {}
+                _err.print(f"  Deleting: {entry.get('title', change.page_id)}")
+                delete_page(client, change.page_id)
+                manifest["pages"].pop(change.page_id, None)
+                result.deleted += 1
+        else:
+            _err.print(
+                f"  [yellow]{len(diff.deleted)} page(s) on server not found locally. "
+                "Use --delete to remove.[/yellow]"
+            )
+
+    # Save ID remaps
+    result.id_remaps = id_remap
+    if id_remap:
+        _err.print(
+            f"[yellow]Community edition: {len(id_remap)} page(s) got new IDs. "
+            "Internal wiki links may need updating.[/yellow]"
+        )
+
+    # Save manifest
+    save_manifest(dir_path, manifest)
+
+    _err.print(
+        f"Pushed to '{space_slug}': "
+        f"{result.created} created, {result.updated} updated, "
+        f"{result.moved} moved, {result.deleted} deleted"
+    )
+    return result
+
+
+def _community_replace(
+    client: DocmostClient,
+    *,
+    space_id: str,
+    old_page_id: str,
+    title: str,
+    content: str,
+    parent_id: str | None,
+    icon: str,
+) -> str:
+    """Safe content update for Community edition: create new, then delete old.
+
+    The old page is only deleted after the new one is confirmed created.
+
+    Returns:
+        New page ID.
+    """
+    from docmost_cli.api.pages import create_and_place_page, delete_page
+
+    new_id = create_and_place_page(
+        client,
+        space_id=space_id,
+        title=title,
+        content=content,
+        parent_page_id=parent_id,
+        icon=icon,
+    )
+    delete_page(client, old_page_id)
+    return new_id
+
+
+def _topological_sort(new_changes: list, existing_ids: set[str]) -> list:
+    """Sort new pages so parents are created before children.
+
+    Pages with no parent or whose parent already exists on the server
+    are placed first. Pages whose parent_id references a server ID not
+    yet in the resolved set are deferred. Note: new pages have empty
+    page_id, so cross-references between new pages are not supported —
+    only references to existing server IDs are resolved.
+
+    Args:
+        new_changes: List of PageChange with NEW type.
+        existing_ids: Set of page IDs already on the server.
+
+    Returns:
+        Sorted list of PageChange.
+    """
+    result = []
+    remaining = list(new_changes)
+    resolved = set(existing_ids)
+
+    max_iterations = len(remaining) + 1
+    for _ in range(max_iterations):
+        if not remaining:
+            break
+        next_remaining = []
+        for change in remaining:
+            meta = change.local_meta or {}
+            parent_id = meta.get("parent_id", "").strip() or None
+            if parent_id is None or parent_id in resolved:
+                result.append(change)
+            else:
+                next_remaining.append(change)
+        if len(next_remaining) == len(remaining):
+            # No progress — circular or broken parent reference — add remaining
+            result.extend(next_remaining)
+            break
+        remaining = next_remaining
+
+    return result
+
+
+def _print_summary(diff: SyncDiff) -> None:
+    """Print change summary to stderr."""
+    lines: list[str] = []
+    if diff.new:
+        lines.append(f"  Create:    {len(diff.new)} page(s)")
+    if diff.modified:
+        lines.append(f"  Update:    {len(diff.modified)} page(s)")
+    if diff.moved:
+        move_only = [c for c in diff.moved if c not in diff.modified]
+        if move_only:
+            lines.append(f"  Move:      {len(move_only)} page(s)")
+    if diff.deleted:
+        lines.append(f"  Delete:    {len(diff.deleted)} page(s)")
+    lines.append(f"  Unchanged: {diff.unchanged} page(s)")
+    _err.print("Push plan:")
+    for line in lines:
+        _err.print(line)
+
+
+def _print_dry_run(diff: SyncDiff) -> None:
+    """Print detailed plan to stdout for scripting."""
+    import sys
+
+    for change in diff.new:
+        meta = change.local_meta or {}
+        sys.stdout.write(f"CREATE {change.filename} ({meta.get('title', '?')})\n")
+    for change in diff.modified:
+        types = ", ".join(c.value for c in change.changes if c != ChangeType.MOVED)
+        sys.stdout.write(f"UPDATE {change.filename} ({types})\n")
+    for change in diff.moved:
+        if change not in diff.modified:
+            meta = change.local_meta or {}
+            sys.stdout.write(
+                f"MOVE   {change.filename} -> parent:{meta.get('parent_id', 'root')}\n"
+            )
+    for change in diff.deleted:
+        entry = change.manifest_entry or {}
+        sys.stdout.write(f"DELETE {entry.get('filename', '?')} ({entry.get('title', '?')})\n")

docmost_cli-0.4.0.data/data/share/man/man1/docmost-cli-attachment.1

@@ -0,0 +1,57 @@
+.\" Manual page for docmost-cli-attachment(1)
+.\" Source: SPECIFICATION.md section 4.6, src/docmost_cli/cli/attachment.py
+.TH DOCMOST\-CLI\-ATTACHMENT 1 "2026\-03\-22" "docmost\-cli 0.4.0" "User Commands"
+.SH NAME
+docmost\-cli\-attachment \- attachment operations for Docmost wiki
+.SH SYNOPSIS
+.B docmost\-cli attachment search
+.I query
+.RB [ \-\-space
+.IR slug ]
+.RB [ \-\-json ]
+.SH DESCRIPTION
+Commands for working with file attachments in a Docmost wiki.
+.SH SUBCOMMANDS
+.SS search
+Search for attachments by name or content.
+.PP
+.I query
+is the search string.
+.TP
+.BI \-\-space " slug"
+Restrict search to attachments in a specific space.
+.TP
+.B \-\-json
+Output as a JSON array instead of a Rich table.
+.PP
+Table columns: id, fileName, type.
+.SH EXAMPLES
+Search for attachments:
+.PP
+.RS 4
+.EX
+$ docmost\-cli attachment search "architecture diagram"
+.EE
+.RE
+.PP
+Search within a space:
+.PP
+.RS 4
+.EX
+$ docmost\-cli attachment search "logo" \-\-space design
+.EE
+.RE
+.SH EXIT STATUS
+See
+.BR docmost\-cli (1).
+.SH SEE ALSO
+.BR docmost\-cli (1),
+.BR docmost\-cli\-search (1),
+.BR docmost\-cli\-page (1)
+.SH AUTHORS
+Georg
+.MT georg@mann\-mouse.at
+.ME .
+.SH COPYRIGHT
+Copyright \(co 2026 Georg.
+License AGPLv3+: GNU Affero General Public License version 3 or later.

docmost_cli-0.4.0.data/data/share/man/man1/docmost-cli-comment.1

@@ -0,0 +1,92 @@
+.\" Manual page for docmost-cli-comment(1)
+.\" Source: SPECIFICATION.md section 4.4, src/docmost_cli/cli/comment.py
+.TH DOCMOST\-CLI\-COMMENT 1 "2026\-03\-22" "docmost\-cli 0.4.0" "User Commands"
+.SH NAME
+docmost\-cli\-comment \- comment operations for Docmost wiki pages
+.SH SYNOPSIS
+.B docmost\-cli comment list
+.I page\-id
+.RB [ \-\-json ]
+.br
+.B docmost\-cli comment create
+.I page\-id
+.BI \-\-content " text"
+.br
+.B docmost\-cli comment update
+.I comment\-id
+.BI \-\-content " text"
+.SH DESCRIPTION
+Commands for managing comments on Docmost wiki pages.
+Comments are displayed as plain text extracted from the underlying
+ProseMirror content, truncated to approximately 100 characters in
+table output.
+.SH SUBCOMMANDS
+.SS list
+List comments on a page.
+.PP
+.I page\-id
+is the UUID of the page whose comments to list.
+.TP
+.B \-\-json
+Output as a JSON array instead of a Rich table.
+.PP
+Table columns: id, content, creatorId, createdAt.
+.SS create
+Add a comment to a page.
+.PP
+.I page\-id
+is the UUID of the page to comment on.
+.TP
+.BI \-\-content " text"
+Comment text.
+Required.
+.PP
+Outputs the new comment ID to stdout.
+.SS update
+Update an existing comment.
+.PP
+.I comment\-id
+is the UUID of the comment to update.
+.TP
+.BI \-\-content " text"
+New comment text.
+Required.
+.PP
+Outputs the updated comment ID to stdout.
+.SH EXAMPLES
+List comments on a page:
+.PP
+.RS 4
+.EX
+$ docmost\-cli comment list 019a2a69\-xxxx
+.EE
+.RE
+.PP
+Add a comment:
+.PP
+.RS 4
+.EX
+$ docmost\-cli comment create 019a2a69\-xxxx \-\-content "Looks good, ship it!"
+.EE
+.RE
+.PP
+Update a comment:
+.PP
+.RS 4
+.EX
+$ docmost\-cli comment update 019b3c8f\-yyyy \-\-content "Updated review notes"
+.EE
+.RE
+.SH EXIT STATUS
+See
+.BR docmost\-cli (1).
+.SH SEE ALSO
+.BR docmost\-cli (1),
+.BR docmost\-cli\-page (1)
+.SH AUTHORS
+Georg
+.MT georg@mann\-mouse.at
+.ME .
+.SH COPYRIGHT
+Copyright \(co 2026 Georg.
+License AGPLv3+: GNU Affero General Public License version 3 or later.