confpub-cli 1.3.0__tar.gz → 1.4.2__tar.gz

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confpub-cli
-Version: 1.3.0
+Version: 1.4.2
 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
@@ -32,7 +32,7 @@ Requires-Dist: markdownify>=0.14
 Requires-Dist: orjson>=3.9
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: typer[all]>=0.9
+Requires-Dist: typer>=0.9
 Provides-Extra: dev
 Requires-Dist: hatch>=1.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/confpub/__init__.py

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

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/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)
@@ -71,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,
@@ -79,6 +82,7 @@ def main_callback(
     """confpub — publish Markdown to Confluence."""
     set_quiet(quiet)
     set_verbose(verbose)
+    set_compact(compact)
 
 
 # ---------------------------------------------------------------------------
@@ -94,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
@@ -117,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],
@@ -125,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
@@ -145,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)
@@ -155,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
@@ -174,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()))
 
 
 # ---------------------------------------------------------------------------
@@ -192,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")
@@ -208,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:
@@ -240,6 +261,7 @@ 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"),
@@ -247,7 +269,7 @@ def page_publish(
 ) -> 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
@@ -325,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()
@@ -379,6 +402,7 @@ def page_move(
             )
         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
@@ -400,6 +424,7 @@ def space_list() -> None:
     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}
 
@@ -412,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]}
 
@@ -425,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
 
@@ -537,6 +564,7 @@ def label_list(
     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)}
 
@@ -566,6 +594,7 @@ def label_add(
 
         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}
 
@@ -579,6 +608,7 @@ def label_remove(
     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)
@@ -625,6 +655,7 @@ def comment_add(
 
         from confpub.confluence import build_client
         client = build_client()
+        ctx.client = client
         result = client.add_comment(page_id, storage_body)
         ctx.result = result
 
@@ -669,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.3.0 → confpub_cli-1.4.2}/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"]:
@@ -441,10 +457,16 @@ class ConfluenceClient:
             self._call_count += 1
             try:
                 result = self._api.set_page_label(page_id, lbl)
-                if isinstance(result, dict):
+                if isinstance(result, dict) and result.get("name"):
                     results.append(_slim_label(result))
                 elif isinstance(result, list):
-                    results.extend(_slim_label(r) for r in result)
+                    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
@@ -498,11 +520,18 @@ class ConfluenceClient:
                 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,
-                "result": result if isinstance(result, dict) else {"raw": str(result)},
+                "page": page_data,
             }
         except Exception as exc:
             self._handle_error(exc, "move_page")

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/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.3.0 → confpub_cli-1.4.2}/confpub/guide.py

@@ -93,6 +93,17 @@ def build_guide() -> dict[str, Any]:
                 "mutates": False,
                 "description": "List pages in a Confluence space",
                 "flags": ["--space", "--limit", "--start"],
+                "result_schema": {
+                    "pages": "list of slim page objects",
+                    "start": "int — current offset",
+                    "limit": "int — page size",
+                    "size": "int — number of pages returned in this batch",
+                    "has_more": "bool — true if more pages may be available (heuristic: size >= limit)",
+                },
+                "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."
+                ),
             },
             "page.inspect": {
                 "group": "read",
@@ -122,11 +133,13 @@ def build_guide() -> dict[str, Any]:
                 "group": "write",
                 "mutates": True,
                 "description": "Publish a single Markdown file to Confluence",
-                "flags": ["--space", "--parent", "--title", "--page-id", "--dry-run", "--backup", "--label"],
+                "flags": ["--space", "--parent", "--title", "--title-from-h1", "--page-id", "--dry-run", "--backup", "--label"],
                 "agent_hint": (
+                    "Title precedence: explicit --title > --title-from-h1 (first H1 heading) > filename inference. "
                     "When --title is omitted, the title is inferred from the filename: "
                     "the stem is extracted, hyphens and underscores are replaced with spaces, "
                     "and the result is title-cased. E.g. 'my-cool-page.md' → 'My Cool Page'. "
+                    "Use --title-from-h1 to extract the title from the first # heading in the file. "
                     "Use --label to apply labels (repeatable): --label api --label docs."
                 ),
             },
@@ -315,6 +328,7 @@ def build_guide() -> dict[str, Any]:
             "flags": {
                 "--quiet": "Suppress progress output on stderr",
                 "--verbose": "Include diagnostics in result",
+                "--compact": "Output single-line JSON (no indentation)",
                 "--version": "Show version and exit (top-level only)",
             },
             "placement": [

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/confpub/output.py

@@ -16,6 +16,7 @@ import orjson
 # Module-level overrides set by the CLI layer
 _quiet: bool | None = None
 _verbose: bool | None = None
+_compact: bool = False
 
 
 def set_quiet(value: bool) -> None:
@@ -28,6 +29,16 @@ def set_verbose(value: bool) -> None:
     _verbose = value
 
 
+def set_compact(value: bool) -> None:
+    global _compact
+    _compact = value
+
+
+def is_compact() -> bool:
+    """True when JSON output should be single-line (no indentation)."""
+    return _compact
+
+
 def is_llm_mode() -> bool:
     """True when LLM=true is set in the environment."""
     return os.environ.get("LLM", "").lower() == "true"

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/confpub/publish.py

@@ -23,10 +23,19 @@ from confpub.errors import (
 from confpub.lockfile import Lockfile, load_lockfile, save_lockfile, update_lockfile
 
 
-def derive_title(file: str, title: str | None = None) -> str:
-    """Derive page title from explicit title or filename."""
+def derive_title(file: str, title: str | None = None, *, title_from_h1: bool = False) -> str:
+    """Derive page title from explicit title, H1 heading, or filename.
+
+    Precedence: explicit --title > --title-from-h1 > filename inference.
+    """
     if title:
         return title
+    if title_from_h1:
+        from confpub.converter import extract_h1_title
+        md_text = Path(file).read_text(encoding="utf-8")
+        h1 = extract_h1_title(md_text)
+        if h1:
+            return h1
     return Path(file).stem.replace("-", " ").replace("_", " ").title()
 
 

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/confpub/puller.py

@@ -200,9 +200,10 @@ def _build_page_tree(
         parent_id = str(entry["parent_id"]) if entry["parent_id"] else None
         file_path = file_paths.get(pid, "")
 
+        rel = os.path.relpath(file_path, output_dir).replace("\\", "/") if file_path else ""
         node: dict[str, Any] = {
             "title": page.get("title", ""),
-            "file": os.path.relpath(file_path, output_dir) if file_path else "",
+            "file": rel,
             "children": [],
         }
         if labels_map.get(pid):
@@ -317,7 +318,7 @@ def pull_pages(
             "labels": page_labels,
         })
 
-    # Generate manifest if requested or recursive with multiple pages
+    # Generate manifest if explicitly requested
     manifest_file: str | None = None
     if generate_manifest:
         root_title = root_page.get("title", "")

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/pyproject.toml

@@ -31,7 +31,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "typer[all]>=0.9",
+    "typer>=0.9",
     "pydantic>=2.0",
     "orjson>=3.9",
     "markdown-it-py[linkify,plugins]>=3.0",

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/tests/test_confluence.py

@@ -135,8 +135,37 @@ class TestListPages:
             {"id": "1", "title": "Page A"},
             {"id": "2", "title": "Page B"},
         ]
-        pages = client.list_pages("DEV")
-        assert len(pages) == 2
+        result = client.list_pages("DEV")
+        assert len(result["pages"]) == 2
+        assert result["size"] == 2
+        assert result["start"] == 0
+        assert result["limit"] == 25
+        assert result["has_more"] is False
+
+    def test_has_more_when_full_batch(self, client):
+        """has_more should be True when batch size equals limit."""
+        client._mock_api.get_all_pages_from_space.return_value = [
+            {"id": str(i), "title": f"Page {i}"} for i in range(5)
+        ]
+        result = client.list_pages("DEV", limit=5)
+        assert result["has_more"] is True
+        assert result["size"] == 5
+
+    def test_has_more_false_when_partial_batch(self, client):
+        """has_more should be False when fewer results than limit."""
+        client._mock_api.get_all_pages_from_space.return_value = [
+            {"id": "1", "title": "Only Page"},
+        ]
+        result = client.list_pages("DEV", limit=25)
+        assert result["has_more"] is False
+        assert result["size"] == 1
+
+    def test_pagination_params_passed_through(self, client):
+        """start and limit should be passed through to the result."""
+        client._mock_api.get_all_pages_from_space.return_value = []
+        result = client.list_pages("DEV", start=50, limit=10)
+        assert result["start"] == 50
+        assert result["limit"] == 10
 
 
 class TestAttachments:
@@ -152,6 +181,20 @@ class TestAttachments:
         result = client.upload_attachment("123", "/tmp/file.png")
         assert result["title"] == "file.png"
 
+    def test_upload_attachment_passes_content_type(self, client):
+        """Suggestion 3: upload_attachment should detect and pass content_type for known types."""
+        client._mock_api.attach_file.return_value = {"title": "readme.txt"}
+        client.upload_attachment("123", "/tmp/readme.txt")
+        call_kwargs = client._mock_api.attach_file.call_args
+        assert call_kwargs[1].get("content_type") == "text/plain"
+
+    def test_upload_attachment_png_content_type(self, client):
+        """MIME type detection for .png files."""
+        client._mock_api.attach_file.return_value = {"title": "image.png"}
+        client.upload_attachment("123", "/tmp/image.png")
+        call_kwargs = client._mock_api.attach_file.call_args
+        assert call_kwargs[1].get("content_type") == "image/png"
+
 
 class TestDownloadAttachment:
     def test_relative_url_uses_api_url(self, client, tmp_path):
@@ -256,6 +299,22 @@ class TestLabels:
         assert client._mock_api.set_page_label.call_count == 2
         assert len(results) == 2
 
+    def test_set_labels_empty_response_falls_back(self, client):
+        """When API returns empty/malformed dict, fall back to input label name."""
+        client._mock_api.set_page_label.return_value = {}
+        results = client.set_labels("123", ["my-label"])
+        assert len(results) == 1
+        assert results[0]["name"] == "my-label"
+        assert results[0]["prefix"] == "global"
+        assert results[0]["id"] is None
+
+    def test_set_labels_list_response_with_empty_entries(self, client):
+        """When API returns a list with empty entries, fall back to input label name."""
+        client._mock_api.set_page_label.return_value = [{}]
+        results = client.set_labels("123", ["tag1"])
+        assert len(results) == 1
+        assert results[0]["name"] == "tag1"
+
     def test_set_labels_call_count(self, client):
         """Each label should increment _call_count."""
         initial = client._call_count
@@ -319,6 +378,18 @@ class TestMovePage:
             "DEV", "123", target_title=None, target_id="456", position="append",
         )
 
+    def test_move_page_returns_normalized_page(self, client):
+        """Bug 3: move_page should return a 'page' key with slim page data, not raw 'result'."""
+        client._mock_api.move_page.return_value = {
+            "page": {"id": "123", "title": "My Page", "version": {"number": 3, "when": "2026-01-01"}}
+        }
+        result = client.move_page("DEV", "123", target_title="New Parent")
+        assert "result" not in result
+        assert "page" in result
+        assert result["page"]["id"] == "123"
+        assert result["page"]["title"] == "My Page"
+        assert result["moved"] is True
+
     def test_move_page_not_found(self, client):
         client._mock_api.move_page.side_effect = Exception("404 Not Found")
         with pytest.raises(ConfpubError) as exc_info:
@@ -348,6 +419,24 @@ class TestErrorTranslation:
             client.list_spaces()
         assert exc_info.value.code == ERR_IO_CONNECTION
 
+    def test_403_has_check_input_action(self, client):
+        """Bug 5: 403 errors should have suggested_action='check_input'."""
+        client._mock_api.get_all_spaces.side_effect = Exception("403 Forbidden")
+        with pytest.raises(ConfpubError) as exc_info:
+            client.list_spaces()
+        assert exc_info.value.code == ERR_AUTH_FORBIDDEN
+        assert exc_info.value.suggested_action == "check_input"
+
+    def test_permission_denied_has_check_input_action(self, client):
+        """Bug 5: permission-denied errors should have suggested_action='check_input'."""
+        client._mock_api.get_all_spaces.side_effect = Exception(
+            "User does not have permission to view the content"
+        )
+        with pytest.raises(ConfpubError) as exc_info:
+            client.list_spaces()
+        assert exc_info.value.code == ERR_AUTH_FORBIDDEN
+        assert exc_info.value.suggested_action == "check_input"
+
     def test_permission_error(self, client):
         client._mock_api.get_all_spaces.side_effect = Exception(
             "User does not have permission to view the content"

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/tests/test_converter.py

@@ -1,6 +1,6 @@
 """Tests for confpub.converter module."""
 
-from confpub.converter import convert_markdown, fingerprint_content
+from confpub.converter import convert_markdown, extract_h1_title, fingerprint_content
 
 
 class TestHeadings:
@@ -220,3 +220,31 @@ def hello():
         assert "<blockquote>" in result
         assert "<hr />" in result
         assert '<a href="https://example.com">' in result
+
+
+class TestExtractH1Title:
+    """Suggestion 2: extract_h1_title should extract text from first H1 heading."""
+
+    def test_simple_h1(self):
+        assert extract_h1_title("# My Page Title") == "My Page Title"
+
+    def test_h1_with_body(self):
+        md = "# Getting Started\n\nSome content here."
+        assert extract_h1_title(md) == "Getting Started"
+
+    def test_no_h1_returns_none(self):
+        assert extract_h1_title("## Only H2\n\nNo H1 here.") is None
+
+    def test_empty_returns_none(self):
+        assert extract_h1_title("") is None
+
+    def test_h1_with_inline_code(self):
+        assert extract_h1_title("# Using `confpub` CLI") == "Using confpub CLI"
+
+    def test_first_h1_wins(self):
+        md = "# First Title\n\n## Sub\n\n# Second Title"
+        assert extract_h1_title(md) == "First Title"
+
+    def test_h2_before_h1(self):
+        md = "## Intro\n\n# Main Title"
+        assert extract_h1_title(md) == "Main Title"

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/tests/test_integration.py

@@ -112,7 +112,7 @@ class TestPersonalSpaceKeyCLI:
 
         def fake_list_pages(self, space, **kwargs):
             captured["space"] = space
-            return []
+            return {"pages": [], "start": 0, "limit": 25, "size": 0, "has_more": False}
 
         from confpub.confluence import ConfluenceClient
         monkeypatch.setattr(ConfluenceClient, "list_pages", fake_list_pages)
@@ -309,6 +309,132 @@ class TestPageMoveValidation:
         assert "space" in data["errors"][0]["message"].lower()
 
 
+class TestCompactFlag:
+    """Suggestion 4: --compact should produce single-line JSON output."""
+
+    def test_compact_produces_single_line(self):
+        result = runner.invoke(app, ["--compact", "guide"])
+        assert result.exit_code == 0
+        # Compact output should be a single line (no newlines within the JSON)
+        lines = result.output.strip().split("\n")
+        assert len(lines) == 1
+        data = json.loads(lines[0])
+        assert data["ok"] is True
+
+    def test_compact_between_group_and_command(self, monkeypatch):
+        """--compact should work between group name and subcommand."""
+        def fake_list_pages(self, space, **kwargs):
+            return {"pages": [], "start": 0, "limit": 25, "size": 0, "has_more": False}
+
+        from confpub.confluence import ConfluenceClient
+        monkeypatch.setattr(ConfluenceClient, "list_pages", fake_list_pages)
+        monkeypatch.setattr("confpub.confluence.build_client", lambda: ConfluenceClient.__new__(ConfluenceClient))
+
+        result = runner.invoke(app, ["page", "--compact", "list", "--space", "DEV"])
+        assert result.exit_code == 0
+        lines = result.output.strip().split("\n")
+        assert len(lines) == 1
+
+    def test_without_compact_is_multiline(self):
+        result = runner.invoke(app, ["guide"])
+        assert result.exit_code == 0
+        lines = result.output.strip().split("\n")
+        assert len(lines) > 1
+
+
+class TestVerboseDiagnostics:
+    """Bug 6: --verbose should include rich diagnostics."""
+
+    def test_verbose_includes_diagnostics(self):
+        result = runner.invoke(app, ["--verbose", "guide"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert "diagnostics" in data["metrics"]
+        diag = data["metrics"]["diagnostics"]
+        assert "duration_ms" in diag
+        assert "confpub_version" in diag
+        assert "command" in diag
+
+    def test_verbose_with_client_includes_api_call_count(self, monkeypatch):
+        """When a client is used, diagnostics should include api_call_count."""
+        def fake_list_pages(self, space, **kwargs):
+            self._call_count += 1
+            return {"pages": [], "start": 0, "limit": 25, "size": 0, "has_more": False}
+
+        from confpub.confluence import ConfluenceClient
+        from confpub.config import ResolvedConfig
+        from unittest.mock import patch, MagicMock
+
+        mock_config = ResolvedConfig(
+            base_url="https://test.atlassian.net/wiki",
+            user="user@test.com",
+            token="test_token",
+            token_source="env_var",
+        )
+
+        with patch("confpub.confluence.ConfluenceClient._build_api") as mock_build:
+            mock_build.return_value = MagicMock()
+            real_client = ConfluenceClient(mock_config)
+
+        monkeypatch.setattr(ConfluenceClient, "list_pages", fake_list_pages)
+        monkeypatch.setattr("confpub.confluence.build_client", lambda: real_client)
+
+        result = runner.invoke(app, ["page", "--verbose", "list", "--space", "DEV"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert "diagnostics" in data["metrics"]
+        diag = data["metrics"]["diagnostics"]
+        assert "api_call_count" in diag
+        assert diag["api_call_count"] >= 1
+
+
+class TestPageListPagination:
+    """Suggestion 1: page.list should return pagination metadata."""
+
+    def test_page_list_has_pagination_fields(self, monkeypatch):
+        def fake_list_pages(self, space, **kwargs):
+            return {
+                "pages": [{"id": "1", "title": "P1"}],
+                "start": 0, "limit": 25, "size": 1, "has_more": False,
+            }
+
+        from confpub.confluence import ConfluenceClient
+        from confpub.config import ResolvedConfig
+        from unittest.mock import patch, MagicMock
+
+        mock_config = ResolvedConfig(
+            base_url="https://test.atlassian.net/wiki",
+            user="user@test.com",
+            token="test_token",
+            token_source="env_var",
+        )
+        with patch("confpub.confluence.ConfluenceClient._build_api") as mock_build:
+            mock_build.return_value = MagicMock()
+            real_client = ConfluenceClient(mock_config)
+
+        monkeypatch.setattr(ConfluenceClient, "list_pages", fake_list_pages)
+        monkeypatch.setattr("confpub.confluence.build_client", lambda: real_client)
+
+        result = runner.invoke(app, ["page", "list", "--space", "DEV"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        r = data["result"]
+        assert "pages" in r
+        assert "start" in r
+        assert "limit" in r
+        assert "size" in r
+        assert "has_more" in r
+
+
+class TestTitleFromH1Flag:
+    """Suggestion 2: --title-from-h1 flag should be available on page publish."""
+
+    def test_title_from_h1_in_help(self):
+        result = runner.invoke(app, ["page", "publish", "--help"])
+        assert result.exit_code == 0
+        assert "--title-from-h1" in result.output
+
+
 class TestEnvelopeContract:
     def test_guide_returns_full_envelope(self):
         result = runner.invoke(app, ["guide"])

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/tests/test_output.py

@@ -8,9 +8,11 @@ from confpub.output import (
     emit_stderr,
     emit_stdout,
     is_ci,
+    is_compact,
     is_llm_mode,
     is_quiet,
     is_verbose,
+    set_compact,
     set_quiet,
     set_verbose,
 )
@@ -97,3 +99,17 @@ class TestEmitStderr:
         captured = capsys.readouterr()
         assert captured.err == ""
         set_quiet(None)  # type: ignore[arg-type]
+
+
+class TestCompactMode:
+    """Suggestion 4: compact mode plumbing."""
+
+    def test_set_compact(self):
+        set_compact(True)
+        assert is_compact() is True
+        set_compact(False)
+        assert is_compact() is False
+
+    def test_default_is_not_compact(self):
+        set_compact(False)
+        assert is_compact() is False

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/tests/test_publish.py

@@ -46,6 +46,24 @@ class TestDeriveTitle:
     def test_path_uses_stem_only(self):
         assert derive_title("docs/subfolder/overview.md") == "Overview"
 
+    def test_title_from_h1(self, tmp_path):
+        """Suggestion 2: derive_title with title_from_h1=True extracts H1."""
+        md_file = tmp_path / "test.md"
+        md_file.write_text("# My Custom Title\n\nContent here.")
+        assert derive_title(str(md_file), title_from_h1=True) == "My Custom Title"
+
+    def test_title_from_h1_falls_back_to_filename(self, tmp_path):
+        """When no H1 is found, fall back to filename inference."""
+        md_file = tmp_path / "api-docs.md"
+        md_file.write_text("## Only H2\n\nNo H1 here.")
+        assert derive_title(str(md_file), title_from_h1=True) == "Api Docs"
+
+    def test_explicit_title_beats_h1(self, tmp_path):
+        """Explicit --title should win over --title-from-h1."""
+        md_file = tmp_path / "test.md"
+        md_file.write_text("# H1 Title\n\nContent here.")
+        assert derive_title(str(md_file), "Explicit Title", title_from_h1=True) == "Explicit Title"
+
 
 class TestPublishDryRun:
     @patch("confpub.publish.load_config")

{confpub_cli-1.3.0 → confpub_cli-1.4.2}/tests/test_puller.py

@@ -511,6 +511,56 @@ class TestMultiLevelRecursivePull:
 # ---------------------------------------------------------------------------
 
 
+class TestManifestPathSeparators:
+    """Bug 1: Manifest file paths must use forward slashes on all platforms."""
+
+    def test_manifest_paths_no_backslashes(self, tmp_path):
+        root = _make_page("1", "Root")
+        child = _make_page("2", "Child")
+        pages = {"1": root, "2": child}
+        children = {"1": [child]}
+        client = _mock_client(pages, children)
+
+        with patch("confpub.puller.build_client", return_value=client):
+            result = pull_pages(
+                page_id="1",
+                output_dir=str(tmp_path),
+                recursive=True,
+                layout="nested",
+                generate_manifest=True,
+            )
+
+        manifest_content = Path(result["manifest_file"]).read_text()
+        # No backslashes should appear in any file paths in the manifest
+        for line in manifest_content.split("\n"):
+            if "file:" in line:
+                assert "\\" not in line, f"Backslash found in manifest path: {line}"
+
+
+class TestNestedLayoutNoAutoManifest:
+    """Bug 4: --layout nested without --manifest should NOT create confpub.yaml."""
+
+    def test_nested_without_manifest_flag(self, tmp_path):
+        root = _make_page("1", "Root")
+        child = _make_page("2", "Child")
+        pages = {"1": root, "2": child}
+        children = {"1": [child]}
+        client = _mock_client(pages, children)
+
+        with patch("confpub.puller.build_client", return_value=client):
+            result = pull_pages(
+                page_id="1",
+                output_dir=str(tmp_path),
+                recursive=True,
+                layout="nested",
+                generate_manifest=False,
+            )
+
+        assert result["summary"]["manifest_generated"] is False
+        assert result["manifest_file"] is None
+        assert not (tmp_path / "confpub.yaml").exists()
+
+
 class TestManifestFlag:
     def test_single_page_with_manifest_flag(self, tmp_path):
         """--manifest generates confpub.yaml even for a single page."""