mkdocs2confluence 0.12.0__tar.gz → 0.12.2__tar.gz

{mkdocs2confluence-0.12.0/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.12.0
+Version: 0.12.2
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -25,6 +25,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML>=6.0.3
 Requires-Dist: httpx>=0.27
+Requires-Dist: idna>=3.15
 Requires-Dist: tinycss2>=1.5.1
 Provides-Extra: pdf
 Requires-Dist: weasyprint>=60.0; extra == "pdf"
@@ -181,7 +182,13 @@ mk2conf publish                                 # go live
 
 ![Architecture](https://raw.githubusercontent.com/jeckyl2010/mkdocs2confluence/main/docs/architecture.png)
 
-Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**. The plan phase makes all API read calls; the execute phase makes all write calls in nav order so parent pages always exist before their children.
+Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**.
+
+The publisher is split into two phases:
+- `planner.py` builds a nav-ordered publish plan, compiles pages, and makes the read-side API calls needed to decide create vs update vs skip.
+- `executor.py` applies that plan, performs the write-side API calls, uploads attachments, and wires parent/child relationships in nav order so parent pages always exist before their children.
+
+`publisher/pipeline.py` remains a compatibility facade that re-exports the public publish surface used by the CLI and tests.
 
 ---
 

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.12.2}/README.md

@@ -140,7 +140,13 @@ mk2conf publish                                 # go live
 
 ![Architecture](https://raw.githubusercontent.com/jeckyl2010/mkdocs2confluence/main/docs/architecture.png)
 
-Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**. The plan phase makes all API read calls; the execute phase makes all write calls in nav order so parent pages always exist before their children.
+Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**.
+
+The publisher is split into two phases:
+- `planner.py` builds a nav-ordered publish plan, compiles pages, and makes the read-side API calls needed to decide create vs update vs skip.
+- `executor.py` applies that plan, performs the write-side API calls, uploads attachments, and wires parent/child relationships in nav order so parent pages always exist before their children.
+
+`publisher/pipeline.py` remains a compatibility facade that re-exports the public publish surface used by the CLI and tests.
 
 ---
 

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.12.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.12.0"
+version = "0.12.2"
 description = "Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more"
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }
@@ -32,6 +32,7 @@ classifiers = [
 dependencies = [
   "PyYAML>=6.0.3",
   "httpx>=0.27",
+  "idna>=3.15",
   "tinycss2>=1.5.1",
 ]
 

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.12.2/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.12.0
+Version: 0.12.2
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -25,6 +25,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML>=6.0.3
 Requires-Dist: httpx>=0.27
+Requires-Dist: idna>=3.15
 Requires-Dist: tinycss2>=1.5.1
 Provides-Extra: pdf
 Requires-Dist: weasyprint>=60.0; extra == "pdf"
@@ -181,7 +182,13 @@ mk2conf publish                                 # go live
 
 ![Architecture](https://raw.githubusercontent.com/jeckyl2010/mkdocs2confluence/main/docs/architecture.png)
 
-Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**. The plan phase makes all API read calls; the execute phase makes all write calls in nav order so parent pages always exist before their children.
+Pipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**.
+
+The publisher is split into two phases:
+- `planner.py` builds a nav-ordered publish plan, compiles pages, and makes the read-side API calls needed to decide create vs update vs skip.
+- `executor.py` applies that plan, performs the write-side API calls, uploads attachments, and wires parent/child relationships in nav order so parent pages always exist before their children.
+
+`publisher/pipeline.py` remains a compatibility facade that re-exports the public publish surface used by the CLI and tests.
 
 ---
 

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.12.2}/src/mkdocs2confluence.egg-info/SOURCES.txt

@@ -9,6 +9,9 @@ src/mkdocs2confluence.egg-info/requires.txt
 src/mkdocs2confluence.egg-info/top_level.txt
 src/mkdocs_to_confluence/__init__.py
 src/mkdocs_to_confluence/cli.py
+src/mkdocs_to_confluence/compiler/__init__.py
+src/mkdocs_to_confluence/compiler/models.py
+src/mkdocs_to_confluence/compiler/page.py
 src/mkdocs_to_confluence/emitter/__init__.py
 src/mkdocs_to_confluence/emitter/xhtml.py
 src/mkdocs_to_confluence/ir/__init__.py
@@ -37,8 +40,11 @@ src/mkdocs_to_confluence/preview/render.py
 src/mkdocs_to_confluence/preview/server.py
 src/mkdocs_to_confluence/publisher/__init__.py
 src/mkdocs_to_confluence/publisher/client.py
+src/mkdocs_to_confluence/publisher/executor.py
 src/mkdocs_to_confluence/publisher/http_retry.py
+src/mkdocs_to_confluence/publisher/models.py
 src/mkdocs_to_confluence/publisher/pipeline.py
+src/mkdocs_to_confluence/publisher/planner.py
 src/mkdocs_to_confluence/sync/__init__.py
 src/mkdocs_to_confluence/sync/anchoring.py
 src/mkdocs_to_confluence/sync/command.py

{mkdocs2confluence-0.12.0 → mkdocs2confluence-0.12.2}/src/mkdocs2confluence.egg-info/requires.txt

@@ -1,5 +1,6 @@
 PyYAML>=6.0.3
 httpx>=0.27
+idna>=3.15
 tinycss2>=1.5.1
 
 [dev]

mkdocs2confluence-0.12.2/src/mkdocs_to_confluence/compiler/__init__.py

@@ -0,0 +1,6 @@
+"""Compiler entry points for MkDocs-to-Confluence page compilation."""
+
+from mkdocs_to_confluence.compiler.models import CompileResult
+from mkdocs_to_confluence.compiler.page import compile_page
+
+__all__ = ["CompileResult", "compile_page"]

mkdocs2confluence-0.12.2/src/mkdocs_to_confluence/compiler/models.py

@@ -0,0 +1,17 @@
+"""Typed models for compiler outputs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CompileResult:
+    """Result of compiling a single MkDocs page to Confluence storage XHTML."""
+
+    xhtml: str
+    attachments: list[Path] = field(default_factory=list)
+    labels: tuple[str, ...] = ()
+    confluence_status: str | None = None
+    version_message: str | None = None

mkdocs2confluence-0.12.2/src/mkdocs_to_confluence/compiler/page.py

@@ -0,0 +1,110 @@
+"""Page compilation pipeline for MkDocs-to-Confluence."""
+
+from __future__ import annotations
+
+from mkdocs_to_confluence.compiler.models import CompileResult
+from mkdocs_to_confluence.emitter.xhtml import emit
+from mkdocs_to_confluence.ir.nodes import ChildrenMacro, FrontMatter, SourceFooter
+from mkdocs_to_confluence.loader.config import MkDocsConfig
+from mkdocs_to_confluence.loader.nav import NavNode
+from mkdocs_to_confluence.loader.page import load_page
+from mkdocs_to_confluence.parser.markdown import parse
+from mkdocs_to_confluence.preprocess.abbrevs import (
+    extract_abbreviations,
+    strip_abbreviation_defs,
+)
+from mkdocs_to_confluence.preprocess.frontmatter import extract_front_matter
+from mkdocs_to_confluence.preprocess.icons import strip_icon_shortcodes
+from mkdocs_to_confluence.preprocess.includes import (
+    preprocess_includes,
+    strip_html_comments,
+    strip_unsupported_html,
+)
+from mkdocs_to_confluence.preprocess.linkdefs import (
+    collect_link_defs,
+    expand_link_refs,
+    strip_link_defs,
+)
+from mkdocs_to_confluence.transforms.abbrevs import apply_abbreviations
+from mkdocs_to_confluence.transforms.assets import resolve_local_assets
+from mkdocs_to_confluence.transforms.editlink import attach_source_url
+from mkdocs_to_confluence.transforms.footer import build_source_footer
+from mkdocs_to_confluence.transforms.internallinks import resolve_internal_links
+from mkdocs_to_confluence.transforms.mermaid import DEFAULT_KROKI_URL, render_mermaid_diagrams
+
+
+def compile_page(
+    node: NavNode,
+    config: MkDocsConfig,
+    link_map: dict[str, str] | None = None,
+    *,
+    is_section_index: bool = False,
+    quiet: bool = False,
+) -> CompileResult:
+    """Run the full compile pipeline for one page and return a typed result."""
+    if node.source_path is None:
+        return CompileResult(xhtml="")
+
+    raw = load_page(node)
+
+    preprocessed = preprocess_includes(
+        raw,
+        source_path=node.source_path,
+        docs_dir=config.docs_dir,
+    )
+    preprocessed = strip_unsupported_html(preprocessed)
+    preprocessed = strip_html_comments(preprocessed)
+    preprocessed = strip_icon_shortcodes(preprocessed)
+    front_matter, preprocessed = extract_front_matter(preprocessed)
+    abbrevs = extract_abbreviations(preprocessed)
+    preprocessed = strip_abbreviation_defs(preprocessed)
+    link_defs = collect_link_defs(preprocessed)
+    preprocessed = expand_link_refs(preprocessed, link_defs)
+    preprocessed = strip_link_defs(preprocessed)
+    ir_nodes = parse(preprocessed)
+    if is_section_index:
+        ir_nodes = ir_nodes + (ChildrenMacro(),)
+    ir_nodes = apply_abbreviations(ir_nodes, abbrevs, page_text=preprocessed)
+    ir_nodes, attachments = resolve_local_assets(
+        ir_nodes,
+        page_path=node.source_path,
+        docs_dir=config.docs_dir,
+    )
+    mermaid_render = config.confluence.mermaid_render if config.confluence else "kroki"
+    if mermaid_render != "none":
+        kroki_url = (
+            mermaid_render[len("kroki:"):] if mermaid_render.startswith("kroki:") else DEFAULT_KROKI_URL
+        )
+        ir_nodes, mermaid_attachments = render_mermaid_diagrams(ir_nodes, kroki_url, quiet=quiet)
+        attachments = attachments + mermaid_attachments
+    effective_link_map = link_map if link_map is not None else {}
+    if node.docs_path:
+        ir_nodes = resolve_internal_links(ir_nodes, effective_link_map, node.docs_path)
+    if front_matter is not None:
+        ir_nodes = (front_matter,) + ir_nodes
+    edit_url = config.page_edit_url(node.docs_path or "")
+    site_url = config.page_site_url(node.docs_path or "")
+    if site_url:
+        ir_nodes = attach_source_url(ir_nodes, "", site_url)
+    if edit_url:
+        abs_path = str(config.docs_dir / (node.docs_path or ""))
+        footer = build_source_footer(edit_url, abs_path)
+        ir_nodes = ir_nodes + (footer,)
+
+    labels: tuple[str, ...] = ()
+    confluence_status: str | None = None
+    version_message: str | None = None
+    for node_item in ir_nodes:
+        if isinstance(node_item, FrontMatter):
+            labels = node_item.labels
+            confluence_status = node_item.confluence_status
+        if isinstance(node_item, SourceFooter) and node_item.commit_sha and node_item.commit_summary:
+            version_message = f"{node_item.commit_sha}: {node_item.commit_summary}"
+
+    return CompileResult(
+        xhtml=emit(ir_nodes),
+        attachments=attachments,
+        labels=labels,
+        confluence_status=confluence_status,
+        version_message=version_message,
+    )

mkdocs2confluence-0.12.2/src/mkdocs_to_confluence/publisher/executor.py

@@ -0,0 +1,378 @@
+"""Execution helpers for the nav-driven publish pipeline."""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from mkdocs_to_confluence.publisher.client import ConfluenceError
+from mkdocs_to_confluence.publisher.models import PageAction, PublishReport
+from mkdocs_to_confluence.transforms.assets import _make_attachment_name
+
+if TYPE_CHECKING:
+    from mkdocs_to_confluence.publisher.client import ConfluenceClient
+
+
+def _upload_assets(
+    page_id: str,
+    attachments: list[Path],
+    docs_dir: Path,
+    client: ConfluenceClient,
+    *,
+    quiet: bool = False,
+) -> tuple[int, int, list[tuple[str, str]]]:
+    """Upload attachments for one page sequentially."""
+    pairs = [(_make_attachment_name(p, docs_dir), p) for p in attachments]
+    uploaded = 0
+    skipped = 0
+    errors: list[tuple[str, str]] = []
+
+    # Fetch once; reuse across all uploads (read-only).
+    existing = client.list_attachments(page_id)
+
+    for name, path in pairs:
+        # Skip upload if local file is not newer than what Confluence already has.
+        if name in existing:
+            try:
+                created_at = existing[name]["version"]["createdAt"]
+                confluence_ts = datetime.fromisoformat(
+                    created_at.replace("Z", "+00:00")
+                )
+                local_mtime = datetime.fromtimestamp(
+                    path.stat().st_mtime, tz=timezone.utc
+                )
+                if local_mtime <= confluence_ts:
+                    if not quiet:
+                        print(f"        skipping   {name} (unchanged)")
+                    skipped += 1
+                    continue
+            except (KeyError, ValueError, OSError):
+                pass  # can't compare — fall through to upload
+
+        if not quiet:
+            print(f"        uploading  {name}")
+        try:
+            client.upload_attachment(page_id, path, name, existing)
+            uploaded += 1
+        except Exception as exc:
+            errors.append((name, str(exc)))
+
+    return uploaded, skipped, errors
+
+
+def _execute_folder_action(
+    action: PageAction,
+    client: ConfluenceClient,
+    space_id: str,
+    root_page_id: str | None,
+    report: PublishReport,
+    *,
+    quiet: bool = False,
+) -> None:
+    """Handle folder create/find for a single folder action."""
+    if action.page_id is not None:
+        # Already found at plan time — reuse.
+        report.updated += 1
+    elif action.parent_is_folder or action.parent_id == root_page_id:
+        # Parent is a Confluence folder, or this is a top-level section
+        # directly under the configured root page — use native folder API.
+        existing_folder = None
+        if action.parent_id is not None:
+            try:
+                existing_folder = client.find_folder_under(
+                    action.parent_id,
+                    action.title,
+                    parent_is_folder=action.parent_is_folder,
+                )
+            except Exception as find_exc:
+                print(
+                    f"  [warn] find_folder_under failed "
+                    f"(parent_id={action.parent_id}): {find_exc}",
+                    file=sys.stderr,
+                )
+        if existing_folder is not None:
+            action.page_id = str(existing_folder["id"])
+            report.updated += 1
+        else:
+            folder_parent = (
+                action.parent_id if action.parent_is_folder else None
+            )
+            folder = client.create_folder(
+                space_id, action.title, parent_id=folder_parent
+            )
+            action.page_id = str(folder["id"])
+            report.created += 1
+            if not quiet:
+                print(
+                    f"         folder id={action.page_id}"
+                    f"  parent_id={action.parent_id}"
+                    f"  parent_is_folder={action.parent_is_folder}"
+                )
+    else:
+        # Parent is a dynamically-created page (e.g. a section-index page).
+        # Confluence folders cannot be nested under pages — use a stub page.
+        action.is_folder = False
+        existing = client.find_page(space_id, action.title)
+        if existing is not None:
+            action.page_id = str(existing["id"])
+            report.updated += 1
+        else:
+            stub = client.create_page(
+                space_id, action.title, "", parent_id=action.parent_id,
+            )
+            action.page_id = str(stub["id"])
+            report.created += 1
+
+
+def _execute_page_action(
+    action: PageAction,
+    client: ConfluenceClient,
+    space_id: str,
+    report: PublishReport,
+) -> None:
+    """Handle create/update (with stale fallback) for a single page action."""
+    if action.action == "create":
+        page = client.create_page(
+            space_id,
+            action.title,
+            action.xhtml or "",
+            parent_id=action.parent_id,
+        )
+        action.page_id = str(page["id"])
+        report.created += 1
+        try:
+            client.stamp_managed(action.page_id)
+        except Exception:
+            pass  # non-fatal
+    elif action.action == "update":
+        if action.page_id is None or action.version is None:
+            raise RuntimeError(
+                f"Update action for '{action.title}' is missing page_id or version"
+            )
+        try:
+            client.update_page(
+                action.page_id,
+                action.title,
+                action.xhtml or "",
+                action.version + 1,
+                parent_id=action.parent_id,
+                version_message=action.version_message,
+            )
+            report.updated += 1
+        except ConfluenceError as upd_exc:
+            err = str(upd_exc)
+            # 404 = page deleted; 400 "another space" = stale page_id
+            # from a different Confluence space. Both mean the existing
+            # page can't be updated — fall back to create a fresh one.
+            is_stale = "HTTP 404" in err or (
+                "HTTP 400" in err and "another space" in err.lower()
+            )
+            if not is_stale:
+                raise
+            print(
+                f"  [warn] update failed ({err[:80].strip()}) —"
+                " stale page_id; falling back to create",
+                file=sys.stderr,
+            )
+            action.page_id = None
+            page = client.create_page(
+                space_id,
+                action.title,
+                action.xhtml or "",
+                parent_id=action.parent_id,
+            )
+            action.page_id = str(page["id"])
+            report.created += 1
+            try:
+                client.stamp_managed(action.page_id)
+            except Exception:
+                pass  # non-fatal
+
+
+def _wire_children(
+    action: PageAction,
+    action_by_node: dict[int, PageAction],
+) -> None:
+    """Propagate a section's resolved page_id to all its direct children."""
+    if action.page_id is None:
+        return
+    for child_node in action.node.children:
+        child_action = action_by_node.get(id(child_node))
+        if child_action is not None:
+            child_action.parent_id = action.page_id
+            child_action.parent_is_folder = action.is_folder
+
+
+def _apply_page_presentation(
+    action: PageAction,
+    client: ConfluenceClient,
+    *,
+    full_width: bool,
+    space_key: str | None = None,
+    suppress_full_width_errors: bool = False,
+) -> None:
+    """Apply page status and full-width presentation updates."""
+    if action.page_id and action.confluence_status and not action.is_folder:
+        try:
+            print(f"  [status] setting '{action.confluence_status}' on page {action.page_id!r}...")
+            client.set_page_status(action.page_id, action.confluence_status, space_key=space_key)
+            print("  [status] ok")
+        except Exception as exc:
+            # Always print status errors — user configured status explicitly
+            print(f"  [warn] could not set page status '{action.confluence_status}': {exc}")
+
+    # Set full-width LAST — Confluence's state/label PUTs can reset the appearance property.
+    if full_width and action.page_id and not action.is_folder:
+        try:
+            client.set_page_full_width(action.page_id)
+        except Exception as exc:
+            if not suppress_full_width_errors:
+                print(f"  [warn] could not set full-width on page {action.page_id!r}: {exc}")
+
+
+def _post_process_action(
+    action: PageAction,
+    client: ConfluenceClient,
+    *,
+    full_width: bool,
+    docs_dir: Path,
+    report: PublishReport,
+    space_key: str | None = None,
+    quiet: bool = False,
+) -> None:
+    """Run all non-fatal post-create/update work for a single action."""
+    # Store content hash after create/update so the next run can skip unchanged pages.
+    if action.page_id and action.content_hash and action.action in ("create", "update"):
+        try:
+            client.set_content_hash(action.page_id, action.content_hash)
+        except Exception:
+            pass  # non-fatal
+
+    # Apply labels (tags) from front matter — non-fatal on failure.
+    if action.page_id and action.labels and not action.is_folder:
+        try:
+            client.set_page_labels(action.page_id, action.labels)
+        except Exception:
+            pass
+
+    _apply_page_presentation(
+        action,
+        client,
+        full_width=full_width,
+        space_key=space_key,
+        suppress_full_width_errors=True,
+    )
+
+    # Upload assets — skip files whose mtime is not newer than Confluence.
+    if action.page_id and action.attachments:
+        uploaded, asset_skipped, asset_errors = _upload_assets(
+            action.page_id, action.attachments, docs_dir, client, quiet=quiet
+        )
+        report.assets_uploaded += uploaded
+        report.assets_skipped += asset_skipped
+        for name, msg in asset_errors:
+            report.errors.append((f"{action.title} / {name}", msg))
+
+
+def execute_publish(
+    plan: list[PageAction],
+    client: ConfluenceClient,
+    *,
+    dry_run: bool = False,
+    space_id: str,
+    space_key: str | None = None,
+    docs_dir: Path,
+    full_width: bool = True,
+    root_page_id: str | None = None,
+    prune: bool = False,
+    quiet: bool = False,
+) -> PublishReport:
+    """Execute the publish plan."""
+    report = PublishReport()
+
+    if dry_run:
+        report.skipped = sum(1 for a in plan if a.action == "skip")
+        report.created = sum(1 for a in plan if a.action == "create")
+        report.updated = sum(1 for a in plan if a.action == "update")
+        return report
+
+    # Index: nav node id → PageAction, used to wire child parent_ids after
+    # each section is created/updated.
+    action_by_node: dict[int, PageAction] = {id(a.node): a for a in plan}
+
+    active = [a for a in plan if a.action != "skip"]
+    total = len(active)
+    if not quiet:
+        print(f"\nPublishing {total} page(s)...")
+    counter = 0
+
+    for action in plan:
+        if action.action == "skip":
+            report.skipped += 1
+            _apply_page_presentation(action, client, full_width=full_width, space_key=space_key)
+            continue
+
+        counter += 1
+        if not quiet:
+            print(f"  [{counter}/{total}] {action.action:<6}  '{action.title}'")
+
+        try:
+            if action.is_folder:
+                _execute_folder_action(action, client, space_id, root_page_id, report, quiet=quiet)
+            else:
+                _execute_page_action(action, client, space_id, report)
+        except Exception as exc:
+            report.errors.append((action.title, str(exc)))
+            # Do NOT `continue` — all post-execute blocks below are guarded by
+            # action.page_id checks, so they are safely skipped on failure.
+            # Critically, child parent_id wiring must still run for section
+            # pages whose children were planned with parent_id=None.
+
+        if action.node.is_section and action.page_id:
+            _wire_children(action, action_by_node)
+
+        _post_process_action(
+            action, client,
+            full_width=full_width, docs_dir=docs_dir, space_key=space_key, report=report, quiet=quiet,
+        )
+
+    if prune and root_page_id:
+        published_ids = {a.page_id for a in plan if a.page_id}
+        _prune_orphans(client, root_page_id, published_ids, report, quiet=quiet)
+
+    return report
+
+
+def _prune_orphans(
+    client: ConfluenceClient,
+    root_page_id: str,
+    published_ids: set[str],
+    report: PublishReport,
+    *,
+    quiet: bool = False,
+) -> None:
+    """Delete managed descendant pages that are no longer in the publish plan."""
+    try:
+        all_descendants = client.get_descendant_ids(root_page_id)
+    except Exception as exc:
+        print(f"  [warn] prune: could not fetch descendants — {exc}", file=sys.stderr)
+        return
+
+    orphan_candidates = [pid for pid in all_descendants if pid not in published_ids]
+    if not orphan_candidates:
+        return
+
+    if not quiet:
+        print(f"\nPruning: checking {len(orphan_candidates)} orphan candidate(s)...")
+    for page_id in orphan_candidates:
+        try:
+            if not client.is_managed(page_id):
+                continue
+            client.delete_page(page_id)
+            report.pruned += 1
+            if not quiet:
+                print(f"  deleted orphan page {page_id}")
+        except Exception as exc:
+            print(f"  [warn] prune: failed to delete page {page_id} — {exc}", file=sys.stderr)