confpub-cli 0.7.0__tar.gz → 1.0.0__tar.gz

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/PKG-INFO

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

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

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/confpub/applier.py

@@ -14,7 +14,7 @@ from typing import Any
 from confpub.assets import AssetRef, discover_assets, rewrite_image_urls, upload_assets
 from confpub.config import load_config
 from confpub.confluence import ConfluenceClient
-from confpub.converter import convert_markdown
+from confpub.converter import convert_markdown, fingerprint_content
 from confpub.errors import ERR_CONFLICT_FINGERPRINT, ERR_IO_FILE_NOT_FOUND, ConfpubError
 from confpub.lockfile import Lockfile, load_lockfile, save_lockfile, update_lockfile
 from confpub.manifest import PlanArtifact
@@ -126,6 +126,7 @@ def apply_plan(
 
                 # Update lockfile and parent tracking
                 update_lockfile(lockfile, page.title, new_id, new_version if isinstance(new_version, int) else 1)
+                lockfile.pages[page.title].content_fingerprint = fingerprint_content(storage)
                 parent_ids[page.title] = new_id
 
             counts["create"] += 1
@@ -180,6 +181,7 @@ def apply_plan(
                     lockfile, page.title, page.confluence_page_id,
                     new_version if isinstance(new_version, int) else 1,
                 )
+                lockfile.pages[page.title].content_fingerprint = fingerprint_content(storage)
                 parent_ids[page.title] = page.confluence_page_id
 
             counts["update"] += 1
@@ -193,4 +195,5 @@ def apply_plan(
         "dry_run": dry_run,
         "changes": changes,
         "summary": counts,
+        "lockfile_updated": not dry_run and len(changes) > 0,
     }

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/confpub/cli.py

@@ -171,12 +171,14 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
 @page_app.command("list")
 def page_list(
     space: str = typer.Option(..., "--space", help="Confluence space key"),
+    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:
     """List pages in a Confluence space."""
     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)
+        pages = client.list_pages(space, start=start, limit=limit)
         ctx.result = {"pages": [_slim_page(p, base_url=client._config.base_url.rstrip("/")) for p in pages]}
 
 
@@ -231,15 +233,21 @@ def page_publish(
     """Publish a single Markdown file to Confluence."""
     from confpub.publish import derive_title
     resolved_title = derive_title(file, title)
-    if not page_id and not parent:
-        raise ConfpubError(
-            "ERR_VALIDATION_REQUIRED",
-            "Either --page-id or --parent is required",
-        )
     target = {"space": space, "title": resolved_title, "file": file}
     if page_id:
         target["page_id"] = page_id
     with command_context("page.publish", target=target) as ctx:
+        from pathlib import Path as _Path
+        if not _Path(file).exists():
+            raise ConfpubError(
+                "ERR_IO_FILE_NOT_FOUND",
+                f"File not found: {file}",
+            )
+        if not page_id and not parent:
+            raise ConfpubError(
+                "ERR_VALIDATION_REQUIRED",
+                "Either --page-id or --parent is required",
+            )
         from confpub.publish import publish_page
         result = publish_page(
             file=file,
@@ -307,12 +315,54 @@ def page_delete(
             )
         from confpub.confluence import build_client
         client = build_client()
+
+        # Collect page IDs that will be deleted (for lockfile cleanup)
+        deleted_ids: set[str] = set()
         if page_id:
             if cascade:
+                # Collect descendant IDs before deleting
+                def _collect_ids(pid: str) -> None:
+                    children = client.get_page_children(pid)
+                    for child in children:
+                        cid = str(child["id"])
+                        deleted_ids.add(cid)
+                        _collect_ids(cid)
+                _collect_ids(page_id)
                 client._delete_descendants(page_id)
+            deleted_ids.add(page_id)
             result = client.delete_page(page_id)
         else:
+            if cascade:
+                page = client.get_page(space, title)
+                if page:
+                    pid = str(page["id"])
+                    def _collect_ids_by_title(p: str) -> None:
+                        children = client.get_page_children(p)
+                        for child in children:
+                            cid = str(child["id"])
+                            deleted_ids.add(cid)
+                            _collect_ids_by_title(cid)
+                    _collect_ids_by_title(pid)
+                    deleted_ids.add(pid)
             result = client.delete_page_by_title(space, title, cascade=cascade)
+
+        # Clean up lockfile entries for deleted pages
+        from pathlib import Path
+        from confpub.lockfile import Lockfile, load_lockfile, save_lockfile, remove_from_lockfile
+        lockfile_path = Path.cwd() / "confpub.lock"
+        lockfile = load_lockfile(lockfile_path)
+        if lockfile:
+            removed = False
+            if title and not page_id:
+                removed = remove_from_lockfile(lockfile, title) or removed
+            # Remove entries matching any deleted page ID
+            for lf_title, entry in list(lockfile.pages.items()):
+                if entry.page_id in deleted_ids:
+                    remove_from_lockfile(lockfile, lf_title)
+                    removed = True
+            if removed:
+                save_lockfile(lockfile_path, lockfile)
+
         ctx.result = result
 
 
@@ -494,6 +544,10 @@ def search(
             excerpt_length=excerpt_length,
         )
         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)."
+            )
         ctx.result = result
 
 
@@ -546,3 +600,7 @@ def run() -> None:
         envelope = Envelope.failure("cli", [err])
         emit_stdout(envelope.to_json_bytes())
         sys.exit(10)
+    except ConfpubError as e:
+        envelope = Envelope.failure("cli", [e])
+        emit_stdout(envelope.to_json_bytes())
+        sys.exit(exit_code_for(e.code))

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/confpub/confluence.py

@@ -64,6 +64,7 @@ class ConfluenceClient:
                 ERR_AUTH_FORBIDDEN,
                 f"Permission denied: {msg}",
                 suggested_action="escalate",
+                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:
             raise ConfpubError(ERR_IO_TIMEOUT, f"Request timed out: {msg}") from exc
@@ -78,9 +79,9 @@ class ConfluenceClient:
             ) from exc
         # Not found (404 or explicit "not found")
         if "404" in msg or "not found" in msg.lower():
-            from confpub.errors import ERR_IO_FILE_NOT_FOUND
+            from confpub.errors import ERR_VALIDATION_NOT_FOUND
             raise ConfpubError(
-                ERR_IO_FILE_NOT_FOUND,
+                ERR_VALIDATION_NOT_FOUND,
                 f"Resource not found ({context}): {msg}",
             ) from exc
         raise ConfpubError(ERR_INTERNAL_SDK, f"Unexpected API error ({context}): {msg}") from exc
@@ -175,10 +176,11 @@ class ConfluenceClient:
         """Delete a page by space and title."""
         page = self.get_page(space, title)
         if not page:
-            from confpub.errors import ERR_IO_FILE_NOT_FOUND
+            from confpub.errors import ERR_VALIDATION_NOT_FOUND
             raise ConfpubError(
-                ERR_IO_FILE_NOT_FOUND,
+                ERR_VALIDATION_NOT_FOUND,
                 f"Page '{title}' not found in space '{space}'",
+                retryable=False,
             )
         page_id = str(page["id"])
         if cascade:
@@ -260,11 +262,13 @@ class ConfluenceClient:
             self._handle_error(exc, "list_spaces")
             return []
 
-    def list_pages(self, space: str) -> list[dict[str, Any]]:
+    def list_pages(self, space: str, *, start: int = 0, limit: int = 25) -> list[dict[str, Any]]:
         """List pages in a space."""
         self._call_count += 1
         try:
-            result = self._api.get_all_pages_from_space(space, expand="version")
+            result = self._api.get_all_pages_from_space(
+                space, start=start, limit=limit, expand="version",
+            )
             return result if isinstance(result, list) else []
         except Exception as exc:
             self._handle_error(exc, "list_pages")
@@ -338,6 +342,9 @@ class ConfluenceClient:
         try:
             result = self._api.attach_file(filepath, page_id=page_id)
             if isinstance(result, dict):
+                # API returns {"results": [...]} wrapper — extract the attachment
+                if "results" in result and isinstance(result["results"], list) and result["results"]:
+                    return _slim_attachment(result["results"][0])
                 return _slim_attachment(result)
             return {"uploaded": True, "file": filepath}
         except Exception as exc:
@@ -364,13 +371,13 @@ class ConfluenceClient:
         """
         self._call_count += 1
         try:
-            raw = self._api.cql(
-                cql,
-                start=start,
-                limit=limit,
-                excerpt="highlight",
-                include_archived_spaces=include_archived_spaces,
-            )
+            raw = self._api.get("rest/api/search", params={
+                "cql": cql,
+                "start": start,
+                "limit": limit,
+                "excerpt": "highlight",
+                "includeArchivedSpaces": include_archived_spaces,
+            })
         except Exception as exc:
             msg = str(exc)
             if "400" in msg or "cannot be parsed" in msg.lower():
@@ -386,6 +393,9 @@ class ConfluenceClient:
         results_raw = raw.get("results", []) if isinstance(raw, dict) else []
         total = raw.get("totalSize", 0) if isinstance(raw, dict) else 0
 
+        api_start = raw.get("start", start) if isinstance(raw, dict) else start
+        api_limit = raw.get("limit", limit) if isinstance(raw, dict) else limit
+
         results = [
             _slim_search_result(r, base_url=base_url, excerpt_length=excerpt_length)
             for r in results_raw
@@ -393,9 +403,9 @@ class ConfluenceClient:
         return {
             "results": results,
             "total": total,
-            "start": start,
-            "limit": limit,
-            "has_more": (start + limit) < total,
+            "start": api_start,
+            "limit": api_limit,
+            "has_more": (api_start + api_limit) < total,
         }
 
     # ------------------------------------------------------------------

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/confpub/guide.py

@@ -86,7 +86,7 @@ def build_guide() -> dict[str, Any]:
                 "group": "read",
                 "mutates": False,
                 "description": "List pages in a Confluence space",
-                "flags": ["--space"],
+                "flags": ["--space", "--limit", "--start"],
             },
             "page.inspect": {
                 "group": "read",
@@ -244,6 +244,7 @@ def build_guide() -> dict[str, Any]:
             },
             "behavior": [
                 "Created/updated automatically by page.publish, page.pull, and plan.apply",
+                "Entries removed automatically by page.delete (including --cascade)",
                 "Written atomically (temp file + rename) for crash safety",
                 "Used by plan.create to detect existing pages and versions",
                 "Does not prevent concurrent operations — purely local state tracking",

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/confpub/lockfile.py

@@ -21,6 +21,7 @@ class LockPageEntry(BaseModel):
 
     page_id: str
     version: int = 1
+    content_fingerprint: str | None = None
 
 
 class Lockfile(BaseModel):
@@ -89,3 +90,14 @@ def update_lockfile(
     """Update a page entry in the lockfile."""
     lockfile.pages[title] = LockPageEntry(page_id=page_id, version=version)
     return lockfile
+
+
+def remove_from_lockfile(lockfile: Lockfile, title: str) -> bool:
+    """Remove a page entry from the lockfile by title.
+
+    Returns True if the entry was found and removed, False otherwise.
+    """
+    if title in lockfile.pages:
+        del lockfile.pages[title]
+        return True
+    return False

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/confpub/publish.py

@@ -109,9 +109,16 @@ def publish_page(
 
     # Detect noop — skip update when content is unchanged
     if operation == "update":
-        remote_fingerprint = client.fingerprint_page(existing_page_id)
-        if remote_fingerprint and remote_fingerprint == local_fingerprint:
-            operation = "noop"
+        # Check lockfile fingerprint first (avoids Confluence normalization mismatch)
+        if page_title in lockfile.pages:
+            entry = lockfile.pages[page_title]
+            if entry.content_fingerprint and entry.content_fingerprint == local_fingerprint:
+                operation = "noop"
+        # Fallback: compare against remote fingerprint
+        if operation == "update":
+            remote_fingerprint = client.fingerprint_page(existing_page_id)
+            if remote_fingerprint and remote_fingerprint == local_fingerprint:
+                operation = "noop"
 
     if dry_run:
         change: dict[str, Any] = {
@@ -186,7 +193,9 @@ def publish_page(
         uploaded_attachments = [a.source_path for a in assets]
 
     # Update lockfile
-    update_lockfile(lockfile, page_title, page_id, new_version if isinstance(new_version, int) else 1)
+    new_version_int = new_version if isinstance(new_version, int) else 1
+    update_lockfile(lockfile, page_title, page_id, new_version_int)
+    lockfile.pages[page_title].content_fingerprint = local_fingerprint
     save_lockfile(lockfile_path, lockfile)
 
     change = {

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/confpub/puller.py

@@ -12,7 +12,7 @@ from pathlib import Path
 from typing import Any
 
 from confpub.confluence import ConfluenceClient, build_client
-from confpub.output import emit_stderr
+from confpub.output import emit_progress
 from confpub.errors import (
     ERR_CONFLICT_FILE_EXISTS,
     ERR_VALIDATION_NOT_FOUND,
@@ -47,7 +47,7 @@ def _collect_tree(
     def _walk(pid: str, parent_id: str | None) -> None:
         children = client.get_page_children_deep(pid)
         if children:
-            emit_stderr(f"Found {len(children)} child page(s) under {pid}")
+            emit_progress(0, 0, f"Found {len(children)} child page(s) under {pid}")
         for child in children:
             child_id = str(child["id"])
             pages.append({
@@ -130,8 +130,8 @@ def _check_conflicts(file_paths: dict[str, str], force: bool) -> None:
             ERR_CONFLICT_FILE_EXISTS,
             f"Output files already exist: {', '.join(existing[:5])}"
             + (f" (and {len(existing) - 5} more)" if len(existing) > 5 else ""),
-            details={"existing_files": existing},
-            suggested_action="fix_input",
+            details={"existing_files": existing, "hint": "Use --force to overwrite existing files"},
+            suggested_action="retry_with_flag",
         )
 
 

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/tests/test_applier.py

@@ -127,6 +127,42 @@ class TestApplyPlanReal:
         assert "Existing Page" in lock_data["pages"]
 
 
+class TestApplyLockfileFingerprints:
+    @patch("confpub.applier.load_config")
+    @patch("confpub.applier.ConfluenceClient")
+    def test_lockfile_entries_have_fingerprints(self, MockClient, mock_config, plan_dir, mock_client):
+        MockClient.return_value = mock_client
+        mock_config.return_value = MagicMock()
+
+        result = apply_plan(str(plan_dir / "plan.json"), dry_run=False)
+
+        lockfile_path = plan_dir / "confpub.lock"
+        assert lockfile_path.exists()
+        lock_data = json.loads(lockfile_path.read_text())
+        for title in ("New Page", "Existing Page"):
+            entry = lock_data["pages"][title]
+            assert entry["content_fingerprint"] is not None, f"{title} has null fingerprint"
+            assert len(entry["content_fingerprint"]) == 64  # SHA-256 hex digest
+
+    @patch("confpub.applier.load_config")
+    @patch("confpub.applier.ConfluenceClient")
+    def test_lockfile_updated_in_result(self, MockClient, mock_config, plan_dir, mock_client):
+        MockClient.return_value = mock_client
+        mock_config.return_value = MagicMock()
+
+        result = apply_plan(str(plan_dir / "plan.json"), dry_run=False)
+        assert result["lockfile_updated"] is True
+
+    @patch("confpub.applier.load_config")
+    @patch("confpub.applier.ConfluenceClient")
+    def test_lockfile_updated_false_on_dry_run(self, MockClient, mock_config, plan_dir, mock_client):
+        MockClient.return_value = mock_client
+        mock_config.return_value = MagicMock()
+
+        result = apply_plan(str(plan_dir / "plan.json"), dry_run=True)
+        assert result["lockfile_updated"] is False
+
+
 class TestFingerprintCheck:
     @patch("confpub.applier.load_config")
     @patch("confpub.applier.ConfluenceClient")

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/tests/test_confluence.py

@@ -12,6 +12,7 @@ from confpub.errors import (
     ERR_CONFLICT_PAGE_EXISTS,
     ERR_IO_CONNECTION,
     ERR_IO_FILE_NOT_FOUND,
+    ERR_VALIDATION_NOT_FOUND,
     ERR_INTERNAL_SDK,
     ERR_VALIDATION_REQUIRED,
     ConfpubError,
@@ -260,7 +261,7 @@ class TestErrorTranslation:
         client._mock_api.get_all_spaces.side_effect = Exception("404 Not Found")
         with pytest.raises(ConfpubError) as exc_info:
             client.list_spaces()
-        assert exc_info.value.code == ERR_IO_FILE_NOT_FOUND
+        assert exc_info.value.code == ERR_VALIDATION_NOT_FOUND
 
     def test_generic_error(self, client):
         client._mock_api.get_all_spaces.side_effect = Exception("Something weird happened")
@@ -322,7 +323,7 @@ class TestSlimPage:
 
 class TestSearch:
     def test_structured_results(self, client):
-        client._mock_api.cql.return_value = {
+        client._mock_api.get.return_value = {
             "results": [
                 {
                     "entityType": "content",
@@ -357,14 +358,14 @@ class TestSearch:
         assert r["container_title"] == "Development"
 
     def test_empty_results(self, client):
-        client._mock_api.cql.return_value = {"results": [], "totalSize": 0}
+        client._mock_api.get.return_value = {"results": [], "totalSize": 0}
         result = client.search('title = "nonexistent"')
         assert result["results"] == []
         assert result["total"] == 0
         assert result["has_more"] is False
 
     def test_has_more_pagination(self, client):
-        client._mock_api.cql.return_value = {
+        client._mock_api.get.return_value = {
             "results": [{"entityType": "content", "content": {"id": "1"}, "excerpt": ""}],
             "totalSize": 50,
         }
@@ -375,31 +376,34 @@ class TestSearch:
         assert result["limit"] == 10
 
     def test_invalid_cql_raises_validation(self, client):
-        client._mock_api.cql.side_effect = Exception("400 The query cannot be parsed")
+        client._mock_api.get.side_effect = Exception("400 The query cannot be parsed")
         with pytest.raises(ConfpubError) as exc_info:
             client.search("invalid!!")
         assert exc_info.value.code == ERR_VALIDATION_REQUIRED
 
     def test_auth_error(self, client):
-        client._mock_api.cql.side_effect = Exception("401 Unauthorized")
+        client._mock_api.get.side_effect = Exception("401 Unauthorized")
         with pytest.raises(ConfpubError) as exc_info:
             client.search("type = page")
         assert exc_info.value.code == ERR_AUTH_FORBIDDEN
 
     def test_include_archived_passthrough(self, client):
-        client._mock_api.cql.return_value = {"results": [], "totalSize": 0}
+        client._mock_api.get.return_value = {"results": [], "totalSize": 0}
         client.search("type = page", include_archived_spaces=True)
-        client._mock_api.cql.assert_called_once_with(
-            "type = page",
-            start=0,
-            limit=25,
-            excerpt="highlight",
-            include_archived_spaces=True,
+        client._mock_api.get.assert_called_once_with(
+            "rest/api/search",
+            params={
+                "cql": "type = page",
+                "start": 0,
+                "limit": 25,
+                "excerpt": "highlight",
+                "includeArchivedSpaces": True,
+            },
         )
 
     def test_excerpt_truncation(self, client):
         long_excerpt = "word " * 100  # 500 chars
-        client._mock_api.cql.return_value = {
+        client._mock_api.get.return_value = {
             "results": [{"entityType": "content", "content": {"id": "1"}, "excerpt": long_excerpt}],
             "totalSize": 1,
         }

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/tests/test_integration.py

@@ -110,7 +110,7 @@ class TestPersonalSpaceKeyCLI:
         """--space ~thro must arrive as literal '~thro' in the command handler."""
         captured = {}
 
-        def fake_list_pages(self, space):
+        def fake_list_pages(self, space, **kwargs):
             captured["space"] = space
             return []
 

{confpub_cli-0.7.0 → confpub_cli-1.0.0}/tests/test_lockfile.py

@@ -8,6 +8,7 @@ from confpub.lockfile import (
     LockPageEntry,
     Lockfile,
     load_lockfile,
+    remove_from_lockfile,
     save_lockfile,
     update_lockfile,
 )
@@ -110,3 +111,35 @@ class TestUpdateLockfile:
         update_lockfile(lf, "A", "1", 2)
         assert lf.pages["B"].page_id == "2"
         assert lf.pages["B"].version == 1
+
+
+class TestRemoveFromLockfile:
+    def test_remove_existing_entry(self):
+        lf = Lockfile(pages={
+            "A": LockPageEntry(page_id="1", version=1),
+            "B": LockPageEntry(page_id="2", version=2),
+        })
+        result = remove_from_lockfile(lf, "A")
+        assert result is True
+        assert "A" not in lf.pages
+        assert "B" in lf.pages
+
+    def test_remove_nonexistent_entry(self):
+        lf = Lockfile(pages={
+            "A": LockPageEntry(page_id="1", version=1),
+        })
+        result = remove_from_lockfile(lf, "Missing")
+        assert result is False
+        assert "A" in lf.pages
+
+    def test_remove_from_empty_lockfile(self):
+        lf = Lockfile()
+        result = remove_from_lockfile(lf, "Anything")
+        assert result is False
+
+    def test_remove_all_entries(self):
+        lf = Lockfile(pages={
+            "A": LockPageEntry(page_id="1", version=1),
+        })
+        remove_from_lockfile(lf, "A")
+        assert len(lf.pages) == 0