confpub-cli 1.7.4__tar.gz → 1.7.6__tar.gz

{confpub_cli-1.7.4 → confpub_cli-1.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confpub-cli
-Version: 1.7.4
+Version: 1.7.6
 Summary: Agent-first CLI to publish Markdown to Confluence
 Project-URL: Homepage, https://github.com/ThomasRohde/confpub-cli
 Project-URL: Repository, https://github.com/ThomasRohde/confpub-cli.git

{confpub_cli-1.7.4 → confpub_cli-1.7.6}/confpub/__init__.py

@@ -1,3 +1,3 @@
 """confpub — Agent-first CLI to publish Markdown to Confluence."""
 
-__version__ = "1.7.4"
+__version__ = "1.7.6"

{confpub_cli-1.7.4 → confpub_cli-1.7.6}/confpub/cli.py

@@ -217,6 +217,8 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
 @page_app.command("list")
 def page_list(
     space: Optional[str] = typer.Option(None, "--space", help="Confluence space key (or CONFPUB_SPACE env var)"),
+    title: Optional[str] = typer.Option(None, "--title", help="Filter by title (substring match)"),
+    label: Optional[str] = typer.Option(None, "--label", help="Filter by label"),
     limit: int = typer.Option(25, "--limit", help="Maximum number of pages to return"),
     start: int = typer.Option(0, "--start", help="Starting offset for pagination"),
 ) -> None:
@@ -227,14 +229,38 @@ def page_list(
         from confpub.confluence import build_client, _slim_page
         client = build_client()
         ctx.client = client
-        page_result = client.list_pages(space, start=start, limit=limit)
-        ctx.result = {
-            "pages": [_slim_page(p, base_url=client._config.base_url.rstrip("/"), is_cloud=client._config.is_cloud) for p in page_result["pages"]],
-            "start": page_result["start"],
-            "limit": page_result["limit"],
-            "size": page_result["size"],
-            "has_more": page_result["has_more"],
-        }
+
+        if label:
+            # Use CQL search for label filtering — the list_pages API doesn't support it
+            cql = f'type = page AND space = "{space}" AND label = "{label}"'
+            if title:
+                cql += f' AND title ~ "{title}"'
+            search_result = client.search(cql, start=start, limit=limit)
+            pages = []
+            for sr in search_result.get("results", []):
+                page_id = sr.get("id")
+                if page_id:
+                    pages.append(sr)
+            ctx.result = {
+                "pages": pages,
+                "start": search_result.get("start", start),
+                "limit": search_result.get("limit", limit),
+                "size": len(pages),
+                "has_more": search_result.get("has_more", False),
+            }
+        else:
+            page_result = client.list_pages(space, start=start, limit=limit)
+            pages = [_slim_page(p, base_url=client._config.base_url.rstrip("/"), is_cloud=client._config.is_cloud) for p in page_result["pages"]]
+            if title:
+                title_lower = title.lower()
+                pages = [p for p in pages if title_lower in (p.get("title") or "").lower()]
+            ctx.result = {
+                "pages": pages,
+                "start": page_result["start"],
+                "limit": page_result["limit"],
+                "size": len(pages),
+                "has_more": page_result["has_more"],
+            }
 
 
 @page_app.command("inspect")
@@ -265,6 +291,8 @@ def page_inspect(
             ctx.result = page
         else:
             result = _slim_page(page, base_url=client._config.base_url.rstrip("/"), is_cloud=client._config.is_cloud)
+            labels = client.get_labels(str(page["id"]))
+            result["labels"] = labels
             if format == "markdown" and "body_storage" in result:
                 from confpub.reverse_converter import convert_storage_to_markdown
                 conversion = convert_storage_to_markdown(result["body_storage"])
@@ -316,6 +344,15 @@ def page_publish(
     if effective_page_id:
         target["page_id"] = effective_page_id
     with command_context("page.publish", target=target) as ctx:
+        if not source.exists():
+            from confpub.errors import ERR_IO_FILE_NOT_FOUND
+            raise ConfpubError(
+                ERR_IO_FILE_NOT_FOUND,
+                f"Source file not found: {file}",
+                details={"file": file},
+                retryable=False,
+                suggested_action="fix_input",
+            )
         space = _resolve_space(space, required=True, fm_space=fm_space)
         ctx.target["space"] = space
 
@@ -502,10 +539,21 @@ def attachment_upload(
 ) -> None:
     """Upload an attachment to a Confluence page."""
     with command_context("attachment.upload", target={"page_id": page_id, "file": file}) as ctx:
+        from pathlib import Path as _Path
+        from confpub.errors import ERR_IO_FILE_NOT_FOUND
+        source = _Path(file).resolve()
+        if not source.exists():
+            raise ConfpubError(
+                ERR_IO_FILE_NOT_FOUND,
+                f"File not found: {file}",
+                details={"file": file},
+                retryable=False,
+                suggested_action="fix_input",
+            )
         from confpub.confluence import build_client
         client = build_client()
         ctx.client = client
-        result = client.upload_attachment(page_id, file)
+        result = client.upload_attachment(page_id, str(source))
         ctx.result = result
 
 
@@ -764,9 +812,15 @@ def search(
         )
         result["cql_query"] = effective_cql
         if space and result.get("total", 0) == 0:
-            ctx.warnings.append(
-                f"No results found. Verify space '{space}' exists (use 'space list' to check)."
-            )
+            try:
+                spaces = client.list_spaces()
+                known_keys = {s["key"] for s in spaces}
+                if space not in known_keys:
+                    ctx.warnings.append(f"Space '{space}' not found. Use 'space list' to see accessible spaces.")
+                else:
+                    ctx.warnings.append(f"No results found in space '{space}'.")
+            except Exception:
+                ctx.warnings.append(f"No results found. Verify space '{space}' exists (use 'space list' to check).")
         ctx.result = result
 
 

{confpub_cli-1.7.4 → confpub_cli-1.7.6}/confpub/confluence.py

@@ -62,6 +62,14 @@ class ConfluenceClient:
     def _handle_error(self, exc: Exception, context: str = "") -> None:
         """Translate atlassian-python-api exceptions to ConfpubError."""
         msg = str(exc)
+        if isinstance(exc, (FileNotFoundError, OSError)) and not isinstance(exc, ConnectionError):
+            from confpub.errors import ERR_IO_FILE_NOT_FOUND
+            raise ConfpubError(
+                ERR_IO_FILE_NOT_FOUND,
+                f"File error ({context}): {msg}",
+                retryable=False,
+                suggested_action="fix_input",
+            ) from exc
         if "401" in msg or "Unauthorized" in msg:
             raise ConfpubError(
                 ERR_AUTH_FORBIDDEN,

{confpub_cli-1.7.4 → confpub_cli-1.7.6}/confpub/front_matter.py

@@ -10,6 +10,8 @@ import dataclasses
 from dataclasses import dataclass, field
 from typing import Any
 
+import yaml
+
 from confpub.converter import extract_front_matter
 from confpub.errors import ERR_VALIDATION_MARKDOWN, ConfpubError
 
@@ -24,6 +26,22 @@ class FrontMatterData:
     labels: list[str] = field(default_factory=list)
     page_id: str | None = None
 
+    def to_yaml_block(self) -> str:
+        """Serialize to a YAML front matter block (``--- ... ---``)."""
+        data: dict[str, Any] = {}
+        if self.title is not None:
+            data["title"] = self.title
+        if self.page_id is not None:
+            data["page_id"] = self.page_id
+        if self.space is not None:
+            data["space"] = self.space
+        if self.parent is not None:
+            data["parent"] = self.parent
+        if self.labels:
+            data["labels"] = self.labels
+        yaml_str = yaml.dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False)
+        return f"---\n{yaml_str}---\n\n"
+
 
 def _validate_string(raw: dict[str, Any], key: str) -> str | None:
     """Extract and validate a string field, or None if absent."""

{confpub_cli-1.7.4 → confpub_cli-1.7.6}/confpub/guide.py

@@ -93,7 +93,7 @@ def build_guide() -> dict[str, Any]:
                 "group": "read",
                 "mutates": False,
                 "description": "List pages in a Confluence space",
-                "flags": ["--space", "--limit", "--start"],
+                "flags": ["--space", "--title", "--label", "--limit", "--start"],
                 "result_schema": {
                     "pages": "list of slim page objects",
                     "start": "int — current offset",
@@ -104,6 +104,8 @@ def build_guide() -> dict[str, Any]:
                 "agent_hint": (
                     "Use --start and --limit for pagination: first call with --start 0 --limit 25, "
                     "then if has_more is true, call again with --start 25 --limit 25, and so on. "
+                    "Use --title for client-side substring filtering on page titles. "
+                    "Use --label to filter pages by label (uses CQL search). "
                     "For personal spaces, quote the tilde: --space '~username' "
                     "(PowerShell expands unquoted ~). Or set CONFPUB_SPACE env var."
                 ),
@@ -115,7 +117,8 @@ def build_guide() -> dict[str, Any]:
                 "flags": ["--space", "--title", "--page-id", "--format", "--raw"],
                 "agent_hint": (
                     "Use --format markdown to get the page body as Markdown instead of Confluence storage format. "
-                    "Use --raw for the full unprocessed API response (useful for debugging)."
+                    "Use --raw for the full unprocessed Confluence REST API v2 page response "
+                    "(includes extensions, metadata, restrictions, version history — useful for debugging or advanced introspection)."
                 ),
                 "result_schema": {
                     "page_id": "string",
@@ -125,6 +128,7 @@ def build_guide() -> dict[str, Any]:
                     "url": "string",
                     "body_storage": "string (when --format storage, the default)",
                     "body_markdown": "string (when --format markdown)",
+                    "labels": "list of {name, id, prefix} objects",
                 },
                 "examples": [
                     'confpub page inspect --space DEV --title "My Page"',
@@ -333,7 +337,7 @@ def build_guide() -> dict[str, Any]:
             "description": "Flags that can be placed at the top level or between group name and subcommand.",
             "flags": {
                 "--quiet": "Suppress progress output on stderr",
-                "--verbose": "Include diagnostics in result",
+                "--verbose": "Include diagnostics in result (adds metrics.diagnostics with api_call_count, python_version, confpub_version, config_source, confluence_url, is_cloud; on error includes traceback)",
                 "--compact": "Output single-line JSON (no indentation)",
                 "--version": "Show version and exit (top-level only)",
             },

{confpub_cli-1.7.4 → confpub_cli-1.7.6}/confpub/puller.py

@@ -9,9 +9,7 @@ from __future__ import annotations
 import os
 import re
 from pathlib import Path
-from typing import Any
-
-import yaml
+from typing import Any, Literal
 
 from confpub.confluence import ConfluenceClient, build_client
 from confpub.output import emit_progress
@@ -21,10 +19,13 @@ from confpub.errors import (
     ERR_VALIDATION_REQUIRED,
     ConfpubError,
 )
+from confpub.front_matter import FrontMatterData
 from confpub.lockfile import Lockfile, load_lockfile, save_lockfile, update_lockfile
 from confpub.manifest import generate_manifest_yaml
 from confpub.reverse_converter import convert_storage_to_markdown
 
+Layout = Literal["flat", "nested"]
+
 
 def _slugify(title: str) -> str:
     """Convert a page title to a filename-safe slug.
@@ -77,15 +78,22 @@ def _collect_tree(
 def _compute_file_paths(
     pages: list[dict[str, Any]],
     output_dir: str,
-    layout: str,
+    layout: Layout,
     root_page_id: str,
-) -> dict[str, str]:
-    """Compute output file paths for each page. Returns {page_id: file_path}."""
+) -> tuple[dict[str, str], dict[str, str], dict[str, str | None]]:
+    """Compute output file paths and lookup maps for each page.
+
+    Returns (file_paths, id_to_title, id_to_parent) where:
+    - file_paths: {page_id: file_path}
+    - id_to_title: {page_id: title}
+    - id_to_parent: {page_id: parent_page_id or None}
+    """
     paths: dict[str, str] = {}
     root_slug: str | None = None
 
-    # Build parent lookup
+    # Build lookup maps
     id_to_slug: dict[str, str] = {}
+    id_to_title: dict[str, str] = {}
     id_to_parent: dict[str, str | None] = {}
 
     for entry in pages:
@@ -93,6 +101,7 @@ def _compute_file_paths(
         pid = str(page["id"])
         slug = _slugify(page.get("title", pid))
         id_to_slug[pid] = slug
+        id_to_title[pid] = page.get("title", "")
         id_to_parent[pid] = str(entry["parent_id"]) if entry["parent_id"] else None
         if pid == root_page_id:
             root_slug = slug
@@ -119,7 +128,7 @@ def _compute_file_paths(
             # Flat layout
             paths[pid] = os.path.join(output_dir, f"{slug}.md")
 
-    return paths
+    return paths, id_to_title, id_to_parent
 
 
 def _check_conflicts(file_paths: dict[str, str], force: bool) -> None:
@@ -147,7 +156,7 @@ def _download_page_attachments(
     page_id: str,
     slug: str,
     output_dir: str,
-    layout: str,
+    layout: Layout,
     warnings: list[str],
     file_path: str | None = None,
 ) -> dict[str, str]:
@@ -164,8 +173,6 @@ def _download_page_attachments(
     if layout == "nested" and file_path:
         # Place assets next to the markdown file (e.g. .../page-slug/assets/)
         assets_dir = os.path.join(os.path.dirname(file_path), "assets")
-    elif layout == "nested":
-        assets_dir = os.path.join(output_dir, slug, "assets")
     else:
         assets_dir = os.path.join(output_dir, "assets", slug)
 
@@ -234,27 +241,6 @@ def _build_page_tree(
     return [root_entry]
 
 
-def _build_front_matter(
-    title: str,
-    page_id: str,
-    space: str,
-    parent: str | None = None,
-    labels: list[str] | None = None,
-) -> str:
-    """Build a YAML front matter block for a pulled markdown file."""
-    data: dict[str, Any] = {
-        "title": title,
-        "page_id": page_id,
-        "space": space,
-    }
-    if parent:
-        data["parent"] = parent
-    if labels:
-        data["labels"] = labels
-    yaml_str = yaml.dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False)
-    return f"---\n{yaml_str}---\n\n"
-
-
 def pull_pages(
     *,
     space: str | None = None,
@@ -263,7 +249,7 @@ def pull_pages(
     output_dir: str = ".",
     recursive: bool = False,
     force: bool = False,
-    layout: str = "flat",
+    layout: Layout = "flat",
     include_attachments: bool = True,
 ) -> dict[str, Any]:
     """Pull pages from Confluence to local Markdown files.
@@ -296,23 +282,14 @@ def pull_pages(
     # Collect all pages to pull
     all_pages = _collect_tree(client, root_id, recursive)
 
-    # Compute output file paths
-    file_paths = _compute_file_paths(all_pages, output_dir, layout, root_id)
+    # Compute output file paths and lookup maps
+    file_paths, id_to_title, id_to_parent = _compute_file_paths(all_pages, output_dir, layout, root_id)
 
     # Check for conflicts
     _check_conflicts(file_paths, force)
 
-    # Build lookup maps for front matter parent resolution
-    id_to_title: dict[str, str] = {}
-    id_to_parent: dict[str, str | None] = {}
-    for entry in all_pages:
-        page = entry["page"]
-        pid = str(page["id"])
-        id_to_title[pid] = page.get("title", "")
-        id_to_parent[pid] = str(entry["parent_id"]) if entry["parent_id"] else None
-
-    # Get the root page's parent in Confluence (for front matter + manifest)
-    ancestors = client.get_page_ancestors(root_id)
+    # Get the root page's parent from already-fetched ancestors (no extra API call)
+    ancestors = root_page.get("ancestors", [])
     root_parent_title = ancestors[-1].get("title", "") if ancestors else None
 
     # Process each page
@@ -360,14 +337,14 @@ def pull_pages(
             parent_title = id_to_title.get(par_id) if par_id else None
 
         # Build and prepend front matter
-        front_matter = _build_front_matter(
+        fm = FrontMatterData(
             title=page_title,
             page_id=pid,
             space=root_space,
             parent=parent_title,
-            labels=page_labels,
+            labels=page_labels or [],
         )
-        markdown_content = front_matter + conv_result.markdown
+        markdown_content = fm.to_yaml_block() + conv_result.markdown
 
         # Write markdown file
         os.makedirs(os.path.dirname(out_path) or ".", exist_ok=True)
@@ -384,7 +361,7 @@ def pull_pages(
 
     # Always generate manifest
     root_title = root_page.get("title", "")
-    manifest_parent = ancestors[-1].get("title", root_title) if ancestors else root_title
+    manifest_parent = root_parent_title or root_title
     pulled_labels: dict[str, list[str]] = {
         f["page_id"]: f.get("labels", []) for f in files_result
     }

{confpub_cli-1.7.4 → confpub_cli-1.7.6}/tests/test_puller.py

@@ -10,7 +10,8 @@ import pytest
 import yaml
 
 from confpub.errors import ERR_CONFLICT_FILE_EXISTS, ERR_VALIDATION_REQUIRED, ConfpubError
-from confpub.puller import _build_front_matter, _slugify, pull_pages
+from confpub.front_matter import FrontMatterData
+from confpub.puller import _slugify, pull_pages
 
 
 # ---------------------------------------------------------------------------
@@ -594,10 +595,10 @@ class TestManifestFlag:
 
 class TestBuildFrontMatter:
     def test_basic_fields(self):
-        fm = _build_front_matter("My Page", "123", "SD")
-        assert fm.startswith("---\n")
-        assert fm.endswith("---\n\n")
-        parsed = yaml.safe_load(fm.strip("- \n"))
+        block = FrontMatterData(title="My Page", page_id="123", space="SD").to_yaml_block()
+        assert block.startswith("---\n")
+        assert block.endswith("---\n\n")
+        parsed = yaml.safe_load(block.strip("- \n"))
         assert parsed["title"] == "My Page"
         assert parsed["page_id"] == "123"
         assert parsed["space"] == "SD"
@@ -605,14 +606,17 @@ class TestBuildFrontMatter:
         assert "labels" not in parsed
 
     def test_with_parent_and_labels(self):
-        fm = _build_front_matter("Child", "456", "SD", parent="Parent Page", labels=["a", "b"])
-        parsed = yaml.safe_load(fm.strip("- \n"))
+        block = FrontMatterData(
+            title="Child", page_id="456", space="SD",
+            parent="Parent Page", labels=["a", "b"],
+        ).to_yaml_block()
+        parsed = yaml.safe_load(block.strip("- \n"))
         assert parsed["parent"] == "Parent Page"
         assert parsed["labels"] == ["a", "b"]
 
     def test_empty_labels_omitted(self):
-        fm = _build_front_matter("Page", "1", "SD", labels=[])
-        parsed = yaml.safe_load(fm.strip("- \n"))
+        block = FrontMatterData(title="Page", page_id="1", space="SD").to_yaml_block()
+        parsed = yaml.safe_load(block.strip("- \n"))
         assert "labels" not in parsed
 
 
@@ -661,8 +665,8 @@ class TestFrontMatterInPulledFiles:
     def test_root_page_has_parent_from_ancestors(self, tmp_path):
         """Root page gets parent from Confluence ancestors."""
         page = _make_page("1", "Root")
+        page["ancestors"] = [{"title": "Space Home"}]
         client = _mock_client({"1": page})
-        client.get_page_ancestors = lambda pid: [{"title": "Space Home"}]
 
         with patch("confpub.puller.build_client", return_value=client):
             pull_pages(page_id="1", output_dir=str(tmp_path))