confpub-cli 1.2.0__tar.gz → 1.4.1__tar.gz

{confpub_cli-1.2.0 → confpub_cli-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confpub-cli
-Version: 1.2.0
+Version: 1.4.1
 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.2.0 → confpub_cli-1.4.1}/confpub/__init__.py

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

{confpub_cli-1.2.0 → confpub_cli-1.4.1}/confpub/applier.py

@@ -43,7 +43,7 @@ def apply_plan(
     lockfile = load_lockfile(lockfile_path) or Lockfile()
 
     changes: list[dict[str, Any]] = []
-    counts = {"create": 0, "update": 0, "attachments_upload": 0}
+    counts = {"create": 0, "update": 0, "attachments_upload": 0, "labels_applied": 0}
 
     # Resolve parent page IDs by title
     parent_ids: dict[str, str] = {}  # title → page_id
@@ -128,9 +128,19 @@ def apply_plan(
                     change["attachments_added"] = [a.source_path for a in assets]
                     counts["attachments_upload"] += len(assets)
 
+                # Apply labels
+                if page.labels:
+                    client.set_labels(new_id, page.labels)
+                    change["labels_added"] = page.labels
+                    counts["labels_applied"] += len(page.labels)
+
                 # Update lockfile and parent tracking
                 update_lockfile(lockfile, page.title, new_id, new_version if isinstance(new_version, int) else 1, content_fingerprint=fingerprint_content(storage))
                 parent_ids[page.title] = new_id
+            else:
+                # Dry-run: report labels
+                if page.labels:
+                    change["labels_to_apply"] = page.labels
 
             counts["create"] += 1
             changes.append(change)
@@ -184,12 +194,22 @@ def apply_plan(
                     change["attachments_added"] = [a.source_path for a in assets]
                     counts["attachments_upload"] += len(assets)
 
+                # Apply labels
+                if page.labels:
+                    client.set_labels(page.confluence_page_id, page.labels)
+                    change["labels_added"] = page.labels
+                    counts["labels_applied"] += len(page.labels)
+
                 update_lockfile(
                     lockfile, page.title, page.confluence_page_id,
                     new_version if isinstance(new_version, int) else 1,
                     content_fingerprint=fingerprint_content(storage),
                 )
                 parent_ids[page.title] = page.confluence_page_id
+            else:
+                # Dry-run: report labels
+                if page.labels:
+                    change["labels_to_apply"] = page.labels
 
             counts["update"] += 1
             changes.append(change)

{confpub_cli-1.2.0 → confpub_cli-1.4.1}/confpub/cli.py

@@ -16,7 +16,7 @@ import typer
 from confpub import __version__
 from confpub.envelope import Envelope
 from confpub.errors import ConfpubError, exit_code_for, ERR_INTERNAL_SDK
-from confpub.output import emit_stderr, emit_stdout, is_verbose, set_quiet, set_verbose
+from confpub.output import emit_stderr, emit_stdout, is_compact, is_verbose, set_compact, set_quiet, set_verbose
 
 # ---------------------------------------------------------------------------
 # Subcommand group apps
@@ -26,10 +26,12 @@ from confpub.output import emit_stderr, emit_stdout, is_verbose, set_quiet, set_
 def _group_callback(
     quiet: bool = typer.Option(False, "--quiet", help="Suppress progress output on stderr"),
     verbose: bool = typer.Option(False, "--verbose", help="Include diagnostics in result"),
+    compact: bool = typer.Option(False, "--compact", help="Output single-line JSON (no indentation)"),
 ) -> None:
-    """Allow --quiet/--verbose between the group name and the subcommand."""
+    """Allow --quiet/--verbose/--compact between the group name and the subcommand."""
     set_quiet(quiet)
     set_verbose(verbose)
+    set_compact(compact)
 
 
 page_app = typer.Typer(help="Page operations", callback=_group_callback)
@@ -38,6 +40,8 @@ auth_app = typer.Typer(help="Authentication", callback=_group_callback)
 config_app = typer.Typer(help="Configuration", callback=_group_callback)
 space_app = typer.Typer(help="Space operations", callback=_group_callback)
 attachment_app = typer.Typer(help="Attachment operations", callback=_group_callback)
+label_app = typer.Typer(help="Label operations", callback=_group_callback)
+comment_app = typer.Typer(help="Comment operations", callback=_group_callback)
 
 # ---------------------------------------------------------------------------
 # Main app
@@ -55,6 +59,8 @@ app.add_typer(auth_app, name="auth")
 app.add_typer(config_app, name="config")
 app.add_typer(space_app, name="space")
 app.add_typer(attachment_app, name="attachment")
+app.add_typer(label_app, name="label")
+app.add_typer(comment_app, name="comment")
 
 
 def _version_callback(value: bool) -> None:
@@ -67,6 +73,7 @@ def _version_callback(value: bool) -> None:
 def main_callback(
     quiet: bool = typer.Option(False, "--quiet", help="Suppress progress output on stderr"),
     verbose: bool = typer.Option(False, "--verbose", help="Include diagnostics in result"),
+    compact: bool = typer.Option(False, "--compact", help="Output single-line JSON (no indentation)"),
     version: bool = typer.Option(
         False, "--version", help="Show version and exit",
         callback=_version_callback, is_eager=True,
@@ -75,6 +82,7 @@ def main_callback(
     """confpub — publish Markdown to Confluence."""
     set_quiet(quiet)
     set_verbose(verbose)
+    set_compact(compact)
 
 
 # ---------------------------------------------------------------------------
@@ -90,6 +98,7 @@ class CommandResult:
         self.target: dict[str, Any] | None = None
         self.warnings: list[str] = []
         self.metrics: dict[str, Any] = {}
+        self.client: Any = None
 
 
 @contextmanager
@@ -113,7 +122,10 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
         ctx.metrics["duration_ms"] = duration_ms
         if is_verbose():
             import traceback as tb
-            ctx.metrics["diagnostics"] = {"traceback": tb.format_exc()}
+            err_diag: dict[str, Any] = {"traceback": tb.format_exc()}
+            if ctx.client and hasattr(ctx.client, "_call_count"):
+                err_diag["api_call_count"] = ctx.client._call_count
+            ctx.metrics["diagnostics"] = err_diag
         envelope = Envelope.failure(
             command_name,
             [e],
@@ -121,7 +133,7 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
             warnings=ctx.warnings,
             metrics=ctx.metrics,
         )
-        emit_stdout(envelope.to_json_bytes())
+        emit_stdout(envelope.to_json_bytes(indent=not is_compact()))
         raise typer.Exit(code=exit_code_for(e.code))
     except typer.Exit:
         raise
@@ -141,7 +153,7 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
             warnings=ctx.warnings,
             metrics=ctx.metrics,
         )
-        emit_stdout(envelope.to_json_bytes())
+        emit_stdout(envelope.to_json_bytes(indent=not is_compact()))
         raise typer.Exit(code=90)
     else:
         duration_ms = int((time.monotonic() - start) * 1000)
@@ -151,15 +163,20 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
             from confpub.config import load_config as _load_verbose_config
 
             diag: dict[str, Any] = {
+                "duration_ms": duration_ms,
                 "command": command_name,
                 "target": ctx.target,
                 "warning_count": len(ctx.warnings),
                 "python_version": sys.version,
                 "confpub_version": __version__,
             }
+            if ctx.client and hasattr(ctx.client, "_call_count"):
+                diag["api_call_count"] = ctx.client._call_count
             try:
                 _vcfg = _load_verbose_config()
+                diag["config_source"] = _vcfg.token_source
                 diag["confluence_url"] = _vcfg.base_url
+                diag["is_cloud"] = _vcfg.is_cloud
             except Exception:
                 pass
             ctx.metrics["diagnostics"] = diag
@@ -170,7 +187,7 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
             warnings=ctx.warnings,
             metrics=ctx.metrics,
         )
-        emit_stdout(envelope.to_json_bytes())
+        emit_stdout(envelope.to_json_bytes(indent=not is_compact()))
 
 
 # ---------------------------------------------------------------------------
@@ -188,8 +205,15 @@ def page_list(
     with command_context("page.list", target={"space": space}) as ctx:
         from confpub.confluence import build_client, _slim_page
         client = build_client()
-        pages = 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 pages]}
+        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"],
+        }
 
 
 @page_app.command("inspect")
@@ -204,6 +228,7 @@ def page_inspect(
     with command_context("page.inspect", target={"space": space, "title": title, "page_id": page_id}) as ctx:
         from confpub.confluence import build_client, _slim_page
         client = build_client()
+        ctx.client = client
         if page_id:
             page = client.get_page_by_id(page_id)
         else:
@@ -236,13 +261,15 @@ def page_publish(
     space: str = typer.Option(..., "--space", help="Confluence space key"),
     parent: Optional[str] = typer.Option(None, "--parent", help="Parent page title"),
     title: Optional[str] = typer.Option(None, "--title", help="Page title (defaults to filename stem, hyphen/underscore→spaces, title-cased)"),
+    title_from_h1: bool = typer.Option(False, "--title-from-h1", help="Derive title from first H1 heading in the Markdown file"),
     page_id: Optional[str] = typer.Option(None, "--page-id", help="Confluence page ID (skip lookup, update directly)"),
     dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without writing"),
     backup: bool = typer.Option(False, "--backup", help="Backup existing page before overwriting"),
+    label: Optional[list[str]] = typer.Option(None, "--label", help="Label to apply (repeatable)"),
 ) -> None:
     """Publish a single Markdown file to Confluence."""
     from confpub.publish import derive_title
-    resolved_title = derive_title(file, title)
+    resolved_title = derive_title(file, title, title_from_h1=title_from_h1)
     target = {"space": space, "title": resolved_title, "file": file}
     if page_id:
         target["page_id"] = page_id
@@ -262,6 +289,7 @@ def page_publish(
             dry_run=dry_run,
             backup=backup,
             progress_callback=ctx,
+            labels=label or [],
         )
         ctx.result = result
 
@@ -319,6 +347,7 @@ def page_delete(
             )
         from confpub.confluence import build_client
         client = build_client()
+        ctx.client = client
 
         # Collect descendant IDs before deleting (for lockfile cleanup)
         deleted_ids: set[str] = set()
@@ -351,12 +380,51 @@ def page_delete(
         ctx.result = result
 
 
+@page_app.command("move")
+def page_move(
+    page_id: str = typer.Option(..., "--page-id", help="Confluence page ID to move"),
+    target_parent: Optional[str] = typer.Option(None, "--target-parent", help="Title of the new parent page"),
+    space: Optional[str] = typer.Option(None, "--space", help="Space key (required with --target-parent)"),
+    target_parent_id: Optional[str] = typer.Option(None, "--target-parent-id", help="Page ID of the new parent"),
+) -> None:
+    """Move a page under a new parent."""
+    target = {"page_id": page_id}
+    with command_context("page.move", target=target) as ctx:
+        if not target_parent and not target_parent_id:
+            raise ConfpubError(
+                "ERR_VALIDATION_REQUIRED",
+                "Either --target-parent or --target-parent-id is required",
+            )
+        if target_parent and not space:
+            raise ConfpubError(
+                "ERR_VALIDATION_REQUIRED",
+                "--space is required when using --target-parent",
+            )
+        from confpub.confluence import build_client
+        client = build_client()
+        ctx.client = client
+
+        if target_parent_id:
+            # Use target_id directly — more reliable, no title resolution needed
+            parent_page = client.get_page_by_id(target_parent_id)
+            if not parent_page or not parent_page.get("id"):
+                from confpub.errors import ERR_VALIDATION_NOT_FOUND
+                raise ConfpubError(ERR_VALIDATION_NOT_FOUND, f"Target parent page not found: {target_parent_id}")
+            resolved_space = parent_page.get("space", {}).get("key", space or "")
+            result = client.move_page(resolved_space, page_id, target_id=target_parent_id)
+        else:
+            result = client.move_page(space, page_id, target_title=target_parent)
+
+        ctx.result = result
+
+
 @space_app.command("list")
 def space_list() -> None:
     """List accessible Confluence spaces."""
     with command_context("space.list") as ctx:
         from confpub.confluence import build_client
         client = build_client()
+        ctx.client = client
         spaces = client.list_spaces()
         ctx.result = {"spaces": spaces}
 
@@ -369,6 +437,7 @@ def attachment_list(
     with command_context("attachment.list", target={"page_id": page_id}) as ctx:
         from confpub.confluence import build_client, _slim_attachment
         client = build_client()
+        ctx.client = client
         attachments = client.get_attachments(page_id)
         ctx.result = {"attachments": [_slim_attachment(a) for a in attachments]}
 
@@ -382,6 +451,7 @@ def attachment_upload(
     with command_context("attachment.upload", target={"page_id": page_id, "file": file}) as ctx:
         from confpub.confluence import build_client
         client = build_client()
+        ctx.client = client
         result = client.upload_attachment(page_id, file)
         ctx.result = result
 
@@ -481,6 +551,115 @@ def config_inspect() -> None:
         ctx.result = config.to_display_dict()
 
 
+# ---------------------------------------------------------------------------
+# Label commands
+# ---------------------------------------------------------------------------
+
+
+@label_app.command("list")
+def label_list(
+    page_id: str = typer.Option(..., "--page-id", help="Confluence page ID"),
+) -> None:
+    """List labels on a Confluence page."""
+    with command_context("label.list", target={"page_id": page_id}) as ctx:
+        from confpub.confluence import build_client
+        client = build_client()
+        ctx.client = client
+        labels = client.get_labels(page_id)
+        ctx.result = {"labels": labels, "count": len(labels)}
+
+
+@label_app.command("add")
+def label_add(
+    page_id: str = typer.Option(..., "--page-id", help="Confluence page ID"),
+    label: list[str] = typer.Option(..., "--label", help="Label name (repeatable)"),
+) -> None:
+    """Add labels to a Confluence page."""
+    with command_context("label.add", target={"page_id": page_id}) as ctx:
+        from confpub.errors import ERR_VALIDATION_LABEL
+        # Validate labels
+        for lbl in label:
+            if " " in lbl:
+                raise ConfpubError(
+                    ERR_VALIDATION_LABEL,
+                    f"Label must not contain spaces: '{lbl}'",
+                    details={"label": lbl},
+                )
+            if len(lbl) > 255:
+                raise ConfpubError(
+                    ERR_VALIDATION_LABEL,
+                    f"Label exceeds 255 characters: '{lbl[:50]}...'",
+                    details={"label": lbl, "length": len(lbl)},
+                )
+
+        from confpub.confluence import build_client
+        client = build_client()
+        ctx.client = client
+        results = client.set_labels(page_id, label)
+        ctx.result = {"labels_added": label, "results": results}
+
+
+@label_app.command("remove")
+def label_remove(
+    page_id: str = typer.Option(..., "--page-id", help="Confluence page ID"),
+    label: list[str] = typer.Option(..., "--label", help="Label name to remove (repeatable)"),
+) -> None:
+    """Remove labels from a Confluence page."""
+    with command_context("label.remove", target={"page_id": page_id}) as ctx:
+        from confpub.confluence import build_client
+        client = build_client()
+        ctx.client = client
+        results = []
+        for lbl in label:
+            result = client.remove_label(page_id, lbl)
+            results.append(result)
+        ctx.result = {"labels_removed": label, "results": results}
+
+
+# ---------------------------------------------------------------------------
+# Comment commands
+# ---------------------------------------------------------------------------
+
+
+@comment_app.command("add")
+def comment_add(
+    page_id: str = typer.Option(..., "--page-id", help="Confluence page ID"),
+    text: Optional[str] = typer.Option(None, "--text", help="Comment text (Markdown)"),
+    file: Optional[str] = typer.Option(None, "--file", help="Path to Markdown file for comment body"),
+) -> None:
+    """Add a comment to a Confluence page."""
+    with command_context("comment.add", target={"page_id": page_id}) as ctx:
+        if not text and not file:
+            raise ConfpubError(
+                "ERR_VALIDATION_REQUIRED",
+                "Either --text or --file is required",
+            )
+        if text and file:
+            raise ConfpubError(
+                "ERR_VALIDATION_REQUIRED",
+                "--text and --file are mutually exclusive",
+            )
+
+        if file:
+            from pathlib import Path
+            p = Path(file)
+            if not p.exists():
+                from confpub.errors import ERR_IO_FILE_NOT_FOUND
+                raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"File not found: {file}")
+            md_text = p.read_text(encoding="utf-8")
+        else:
+            md_text = text
+
+        from confpub.converter import convert_markdown
+        storage_body = convert_markdown(md_text)
+
+        from confpub.confluence import build_client
+        client = build_client()
+        ctx.client = client
+        result = client.add_comment(page_id, storage_body)
+        ctx.result = result
+
+
 # ---------------------------------------------------------------------------
 # search command (top-level, not in a subgroup)
 # ---------------------------------------------------------------------------
@@ -521,6 +700,7 @@ def search(
 
         from confpub.confluence import build_client
         client = build_client()
+        ctx.client = client
         result = client.search(
             effective_cql,
             start=start,

{confpub_cli-1.2.0 → confpub_cli-1.4.1}/confpub/confluence.py

@@ -63,7 +63,7 @@ class ConfluenceClient:
             raise ConfpubError(
                 ERR_AUTH_FORBIDDEN,
                 f"Permission denied: {msg}",
-                suggested_action="escalate",
+                suggested_action="check_input",
                 details={"note": "Confluence returns HTTP 403 for both forbidden and nonexistent resources. Verify the resource exists."},
             ) from exc
         if "timeout" in msg.lower() or "Timeout" in msg:
@@ -75,6 +75,7 @@ class ConfluenceClient:
             raise ConfpubError(
                 ERR_AUTH_FORBIDDEN,
                 f"Permission denied ({context}): {msg}",
+                suggested_action="check_input",
                 details={"note": "This may indicate a nonexistent resource; Confluence returns 403 for both."},
             ) from exc
         # Not found (404 or explicit "not found")
@@ -273,17 +274,27 @@ class ConfluenceClient:
             self._handle_error(exc, "list_spaces")
             return []
 
-    def list_pages(self, space: str, *, start: int = 0, limit: int = 25) -> list[dict[str, Any]]:
-        """List pages in a space."""
+    def list_pages(self, space: str, *, start: int = 0, limit: int = 25) -> dict[str, Any]:
+        """List pages in a space.
+
+        Returns a dict with keys: pages, start, limit, size, has_more.
+        """
         self._call_count += 1
         try:
             result = self._api.get_all_pages_from_space(
                 space, start=start, limit=limit, expand="version",
             )
-            return result if isinstance(result, list) else []
+            pages = result if isinstance(result, list) else []
+            return {
+                "pages": pages,
+                "start": start,
+                "limit": limit,
+                "size": len(pages),
+                "has_more": len(pages) >= limit,
+            }
         except Exception as exc:
             self._handle_error(exc, "list_pages")
-            return []
+            return {"pages": [], "start": start, "limit": limit, "size": 0, "has_more": False}
 
     # ------------------------------------------------------------------
     # Attachment operations
@@ -351,7 +362,12 @@ class ConfluenceClient:
         """Upload an attachment to a page."""
         self._call_count += 1
         try:
-            result = self._api.attach_file(filepath, page_id=page_id)
+            import mimetypes
+            content_type, _ = mimetypes.guess_type(filepath)
+            kwargs: dict[str, Any] = {"page_id": page_id}
+            if content_type:
+                kwargs["content_type"] = content_type
+            result = self._api.attach_file(filepath, **kwargs)
             if isinstance(result, dict):
                 # API returns {"results": [...]} wrapper — extract the attachment
                 if "results" in result and isinstance(result["results"], list) and result["results"]:
@@ -419,6 +435,108 @@ class ConfluenceClient:
             "has_more": (api_start + api_limit) < total,
         }
 
+    # ------------------------------------------------------------------
+    # Label operations
+    # ------------------------------------------------------------------
+
+    def get_labels(self, page_id: str) -> list[dict[str, Any]]:
+        """Get labels on a page."""
+        self._call_count += 1
+        try:
+            result = self._api.get_page_labels(page_id)
+            raw = result.get("results", []) if isinstance(result, dict) else (result if isinstance(result, list) else [])
+            return [_slim_label(lbl) for lbl in raw]
+        except Exception as exc:
+            self._handle_error(exc, "get_labels")
+            return []
+
+    def set_labels(self, page_id: str, labels: list[str]) -> list[dict[str, Any]]:
+        """Set labels on a page (additive — does not remove existing labels)."""
+        results: list[dict[str, Any]] = []
+        for lbl in labels:
+            self._call_count += 1
+            try:
+                result = self._api.set_page_label(page_id, lbl)
+                if isinstance(result, dict) and result.get("name"):
+                    results.append(_slim_label(result))
+                elif isinstance(result, list):
+                    results.extend(
+                        _slim_label(r) if isinstance(r, dict) and r.get("name")
+                        else {"name": lbl, "prefix": "global", "id": None}
+                        for r in result
+                    )
+                else:
+                    results.append({"name": lbl, "prefix": "global", "id": None})
+            except Exception as exc:
+                self._handle_error(exc, "set_labels")
+        return results
+
+    def remove_label(self, page_id: str, label: str) -> dict[str, Any]:
+        """Remove a label from a page."""
+        self._call_count += 1
+        try:
+            self._api.remove_page_label(page_id, label)
+            return {"removed": True, "label": label, "page_id": page_id}
+        except Exception as exc:
+            self._handle_error(exc, "remove_label")
+            return {}
+
+    # ------------------------------------------------------------------
+    # Comment operations
+    # ------------------------------------------------------------------
+
+    def add_comment(self, page_id: str, body: str) -> dict[str, Any]:
+        """Add a comment to a page."""
+        self._call_count += 1
+        try:
+            result = self._api.add_comment(page_id, body)
+            return {
+                "id": result.get("id") if isinstance(result, dict) else None,
+                "page_id": page_id,
+                "created": True,
+            }
+        except Exception as exc:
+            self._handle_error(exc, "add_comment")
+            return {}
+
+    # ------------------------------------------------------------------
+    # Page move
+    # ------------------------------------------------------------------
+
+    def move_page(
+        self,
+        space_key: str,
+        page_id: str,
+        target_title: str | None = None,
+        target_id: str | None = None,
+        position: str = "append",
+    ) -> dict[str, Any]:
+        """Move a page under a new parent."""
+        self._call_count += 1
+        try:
+            result = self._api.move_page(
+                space_key, page_id,
+                target_title=target_title,
+                target_id=target_id,
+                position=position,
+            )
+            base_url = self._config.base_url.rstrip("/") if self._config.base_url else ""
+            page_data: dict[str, Any] | None = None
+            if isinstance(result, dict):
+                # The API may return the page directly or nested under a 'page' key
+                raw_page = result.get("page", result) if "page" in result else result
+                if raw_page.get("id"):
+                    page_data = _slim_page(raw_page, base_url=base_url, is_cloud=self._config.is_cloud)
+            return {
+                "moved": True,
+                "page_id": page_id,
+                "target_parent": target_title or target_id,
+                "page": page_data,
+            }
+        except Exception as exc:
+            self._handle_error(exc, "move_page")
+            return {}
+
     # ------------------------------------------------------------------
     # Fingerprinting
     # ------------------------------------------------------------------
@@ -536,6 +654,15 @@ def _slim_attachment(att: dict[str, Any]) -> dict[str, Any]:
     return result
 
 
+def _slim_label(lbl: dict[str, Any]) -> dict[str, Any]:
+    """Extract agent-relevant fields from a raw Confluence label object."""
+    return {
+        "name": lbl.get("name", ""),
+        "prefix": lbl.get("prefix", "global"),
+        "id": lbl.get("id"),
+    }
+
+
 def _slim_search_result(
     item: dict[str, Any],
     *,

{confpub_cli-1.2.0 → confpub_cli-1.4.1}/confpub/converter.py

@@ -366,6 +366,27 @@ def convert_markdown(md_text: str) -> str:
     return renderer.render(tokens, {}, {})
 
 
+def extract_h1_title(md_text: str) -> str | None:
+    """Extract the text of the first H1 heading from Markdown source.
+
+    Returns the title string, or None if no H1 is found.
+    """
+    parser = _create_parser()
+    tokens = parser.parse(md_text)
+    for i, token in enumerate(tokens):
+        if token.type == "heading_open" and token.tag == "h1":
+            # The next token should be an inline token with the heading content
+            if i + 1 < len(tokens) and tokens[i + 1].type == "inline":
+                inline = tokens[i + 1]
+                if inline.children:
+                    parts: list[str] = []
+                    for child in inline.children:
+                        if child.type in ("text", "code_inline"):
+                            parts.append(child.content)
+                    return "".join(parts) if parts else None
+    return None
+
+
 def fingerprint_content(content: str) -> str:
     """Return SHA-256 hex digest of content."""
     return hashlib.sha256(content.encode("utf-8")).hexdigest()

{confpub_cli-1.2.0 → confpub_cli-1.4.1}/confpub/errors.py

@@ -15,6 +15,7 @@ ERR_VALIDATION_MARKDOWN = "ERR_VALIDATION_MARKDOWN"
 ERR_VALIDATION_ASSET_MISSING = "ERR_VALIDATION_ASSET_MISSING"
 ERR_VALIDATION_SPACE_MISMATCH = "ERR_VALIDATION_SPACE_MISMATCH"
 ERR_VALIDATION_NOT_FOUND = "ERR_VALIDATION_NOT_FOUND"
+ERR_VALIDATION_LABEL = "ERR_VALIDATION_LABEL"
 
 # Auth (exit 20)
 ERR_AUTH_REQUIRED = "ERR_AUTH_REQUIRED"