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

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

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

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

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

@@ -62,6 +62,8 @@ def apply_plan(
             raise ConfpubError(
                 ERR_IO_FILE_NOT_FOUND,
                 f"Source file missing: {page.source_file}",
+                retryable=False,
+                suggested_action="fix_input",
             )
 
         # Fingerprint check (unless skipped)

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

@@ -177,7 +177,7 @@ def page_list(
         from confpub.confluence import build_client, _slim_page
         client = build_client()
         pages = client.list_pages(space)
-        ctx.result = {"pages": [_slim_page(p) for p in pages]}
+        ctx.result = {"pages": [_slim_page(p, base_url=client._config.base_url.rstrip("/")) for p in pages]}
 
 
 @page_app.command("inspect")
@@ -186,6 +186,7 @@ def page_inspect(
     title: str = typer.Option(None, "--title", help="Page title"),
     page_id: str = typer.Option(None, "--page-id", help="Confluence page ID"),
     raw: bool = typer.Option(False, "--raw", help="Return full raw API response"),
+    format: str = typer.Option("storage", "--format", help="Output format: storage (raw HTML) or markdown"),
 ) -> None:
     """Inspect a Confluence page."""
     with command_context("page.inspect", target={"space": space, "title": title, "page_id": page_id}) as ctx:
@@ -201,29 +202,51 @@ def page_inspect(
         if not page:
             from confpub.errors import ERR_VALIDATION_NOT_FOUND
             raise ConfpubError(ERR_VALIDATION_NOT_FOUND, f"Page not found")
-        ctx.result = page if raw else _slim_page(page)
+        if raw:
+            ctx.result = page
+        else:
+            result = _slim_page(page, base_url=client._config.base_url.rstrip("/"))
+            if format == "markdown" and "body_storage" in result:
+                from confpub.reverse_converter import convert_storage_to_markdown
+                conversion = convert_storage_to_markdown(result["body_storage"])
+                result["body_markdown"] = conversion.markdown
+                del result["body_storage"]
+                if conversion.warnings:
+                    result["conversion_warnings"] = conversion.warnings
+                if conversion.unknown_macros:
+                    result["unknown_macros"] = conversion.unknown_macros
+            ctx.result = result
 
 
 @page_app.command("publish")
 def page_publish(
     file: str = typer.Argument(..., help="Markdown file to publish"),
     space: str = typer.Option(..., "--space", help="Confluence space key"),
-    parent: str = typer.Option(..., "--parent", help="Parent page title"),
+    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)"),
+    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"),
 ) -> None:
     """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 confpub.publish import publish_page
         result = publish_page(
             file=file,
             space=space,
-            parent=parent,
+            parent=parent or "",
             title=title,
+            page_id=page_id,
             dry_run=dry_run,
             backup=backup,
             progress_callback=ctx,
@@ -270,15 +293,26 @@ def page_pull(
 
 @page_app.command("delete")
 def page_delete(
-    space: str = typer.Option(..., "--space", help="Confluence space key"),
-    title: str = typer.Option(..., "--title", help="Page title"),
+    space: Optional[str] = typer.Option(None, "--space", help="Confluence space key"),
+    title: Optional[str] = typer.Option(None, "--title", help="Page title"),
+    page_id: Optional[str] = typer.Option(None, "--page-id", help="Confluence page ID"),
     cascade: bool = typer.Option(False, "--cascade", help="Also delete child pages"),
 ) -> None:
     """Delete a Confluence page."""
-    with command_context("page.delete", target={"space": space, "title": title}) as ctx:
+    with command_context("page.delete", target={"space": space, "title": title, "page_id": page_id}) as ctx:
+        if not page_id and not (space and title):
+            raise ConfpubError(
+                "ERR_VALIDATION_REQUIRED",
+                "Either --page-id or both --space and --title are required",
+            )
         from confpub.confluence import build_client
         client = build_client()
-        result = client.delete_page_by_title(space, title, cascade=cascade)
+        if page_id:
+            if cascade:
+                client._delete_descendants(page_id)
+            result = client.delete_page(page_id)
+        else:
+            result = client.delete_page_by_title(space, title, cascade=cascade)
         ctx.result = result
 
 
@@ -421,6 +455,7 @@ def config_inspect() -> None:
 def search(
     cql: Optional[str] = typer.Option(None, "--cql", help="Raw CQL query"),
     space: Optional[str] = typer.Option(None, "--space", help="Filter by space key"),
+    title: Optional[str] = typer.Option(None, "--title", help="Search by page title (fuzzy match)"),
     content_type: Optional[str] = typer.Option(None, "--type", help="Filter by content type (page, blogpost, etc.)"),
     limit: int = typer.Option(25, "--limit", help="Maximum results to return"),
     start: int = typer.Option(0, "--start", help="Starting offset for pagination"),
@@ -428,12 +463,14 @@ def search(
     excerpt_length: int = typer.Option(200, "--excerpt-length", help="Max excerpt chars (0 = unlimited)"),
 ) -> None:
     """Search Confluence content using CQL."""
-    target = {"cql": cql, "space": space, "type": content_type}
+    target = {"cql": cql, "space": space, "title": title, "type": content_type}
     with command_context("search", target=target) as ctx:
         # Build effective CQL from flags
         fragments: list[str] = []
         if space:
             fragments.append(f'space = "{space}"')
+        if title:
+            fragments.append(f'title ~ "{title}"')
         if content_type:
             fragments.append(f'type = "{content_type}"')
         if cql:
@@ -442,7 +479,7 @@ def search(
         if not fragments:
             raise ConfpubError(
                 "ERR_VALIDATION_REQUIRED",
-                "At least one of --cql, --space, or --type is required",
+                "At least one of --cql, --space, --title, or --type is required",
             )
 
         effective_cql = " AND ".join(fragments)
@@ -484,6 +521,7 @@ def guide(
                     raise validation_error(
                         ERR_VALIDATION_REQUIRED,
                         f"Unknown guide section: {section}",
+                        valid_sections=list(full_guide.keys()),
                     )
             ctx.result = result
         else:

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

@@ -32,10 +32,10 @@ class ConfluenceClient:
         self._call_count = 0
 
         # Suppress noisy atlassian-python-api logging (e.g. "Can't find 'X' page")
-        from confpub.output import is_quiet
+        from confpub.output import is_verbose
 
         atlassian_logger = logging.getLogger("atlassian")
-        atlassian_logger.setLevel(logging.CRITICAL if is_quiet() else logging.WARNING)
+        atlassian_logger.setLevel(logging.WARNING if is_verbose() else logging.CRITICAL)
 
     @staticmethod
     def _build_api(config: ResolvedConfig) -> Any:
@@ -74,7 +74,7 @@ class ConfluenceClient:
             raise ConfpubError(
                 ERR_AUTH_FORBIDDEN,
                 f"Permission denied ({context}): {msg}",
-                suggested_action="escalate",
+                details={"note": "This may indicate a nonexistent resource; Confluence returns 403 for both."},
             ) from exc
         # Not found (404 or explicit "not found")
         if "404" in msg or "not found" in msg.lower():
@@ -93,7 +93,7 @@ class ConfluenceClient:
         """Get a page by space key and title."""
         self._call_count += 1
         try:
-            result = self._api.get_page_by_title(space, title, expand="version,body.storage,space")
+            result = self._api.get_page_by_title(space, title, expand="version,body.storage,space,ancestors")
             return result if result else None
         except Exception as exc:
             self._handle_error(exc, "get_page")
@@ -103,7 +103,7 @@ class ConfluenceClient:
         """Get a page by its Confluence ID."""
         self._call_count += 1
         try:
-            return self._api.get_page_by_id(page_id, expand="version,body.storage,space")
+            return self._api.get_page_by_id(page_id, expand="version,body.storage,space,ancestors")
         except Exception as exc:
             self._handle_error(exc, "get_page_by_id")
             return {}
@@ -230,6 +230,16 @@ class ConfluenceClient:
             start += limit
         return all_children
 
+    def get_page_ancestors(self, page_id: str) -> list[dict[str, Any]]:
+        """Get the ancestor chain of a page (root first, immediate parent last)."""
+        self._call_count += 1
+        try:
+            page = self._api.get_page_by_id(page_id, expand="ancestors")
+            return page.get("ancestors", [])
+        except Exception as exc:
+            self._handle_error(exc, "get_page_ancestors")
+            return []
+
     # ------------------------------------------------------------------
     # Space operations
     # ------------------------------------------------------------------
@@ -403,7 +413,7 @@ class ConfluenceClient:
             return None
 
 
-def _slim_page(page: dict[str, Any]) -> dict[str, Any]:
+def _slim_page(page: dict[str, Any], *, base_url: str = "") -> dict[str, Any]:
     """Extract agent-relevant fields from a raw Confluence page object."""
     result: dict[str, Any] = {
         "id": page.get("id"),
@@ -419,9 +429,14 @@ def _slim_page(page: dict[str, Any]) -> dict[str, Any]:
     body = page.get("body", {}).get("storage", {}).get("value")
     if body is not None:
         result["body_storage"] = body
+    ancestors = page.get("ancestors")
+    if isinstance(ancestors, list) and ancestors:
+        parent = ancestors[-1]
+        result["parent_id"] = parent.get("id")
+        result["parent_title"] = parent.get("title")
     links = page.get("_links", {})
     if "webui" in links:
-        base = links.get("base", "")
+        base = base_url or links.get("base", "")
         result["webui"] = base + links["webui"]
     return result
 

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

@@ -65,7 +65,8 @@ def build_guide() -> dict[str, Any]:
                 "group": "read",
                 "mutates": False,
                 "description": "Search Confluence content using CQL",
-                "flags": ["--cql", "--space", "--type", "--limit", "--start", "--include-archived", "--excerpt-length"],
+                "flags": ["--cql", "--space", "--title", "--type", "--limit", "--start", "--include-archived", "--excerpt-length"],
+                "agent_hint": "Most agent workflows should include --type page to exclude attachments and space entities from results.",
                 "result_schema": {
                     "cql_query": "string — effective CQL sent to the API",
                     "results": "list of {id, type, title, excerpt, url, space_key, entity_type, status, last_modified, container_title}",
@@ -78,6 +79,7 @@ def build_guide() -> dict[str, Any]:
                     'confpub search --cql \'label = "api-docs"\'',
                     "confpub search --space DEV --type page --limit 10",
                     'confpub search --space DEV --cql \'title ~ "deploy"\'',
+                    'confpub search --title "deploy guide" --space DEV',
                 ],
             },
             "page.list": {
@@ -90,13 +92,13 @@ def build_guide() -> dict[str, Any]:
                 "group": "read",
                 "mutates": False,
                 "description": "Inspect a Confluence page",
-                "flags": ["--space", "--title", "--page-id"],
+                "flags": ["--space", "--title", "--page-id", "--format"],
             },
             "page.publish": {
                 "group": "write",
                 "mutates": True,
                 "description": "Publish a single Markdown file to Confluence",
-                "flags": ["--space", "--parent", "--title", "--dry-run", "--backup"],
+                "flags": ["--space", "--parent", "--title", "--page-id", "--dry-run", "--backup"],
             },
             "page.pull": {
                 "group": "read",
@@ -115,7 +117,7 @@ def build_guide() -> dict[str, Any]:
                 "group": "write",
                 "mutates": True,
                 "description": "Delete a Confluence page",
-                "flags": ["--space", "--title", "--cascade"],
+                "flags": ["--space", "--title", "--page-id", "--cascade"],
                 "safety_flags": {
                     "--cascade": "Also deletes child pages",
                 },
@@ -232,6 +234,43 @@ def build_guide() -> dict[str, Any]:
                 "to the same workspace return ERR_CONFLICT_LOCK"
             ),
         },
+        "lockfile": {
+            "description": "Local state file tracking page IDs and versions from publish/pull operations.",
+            "file": "confpub.lock",
+            "schema": {
+                "schema_version": "Lockfile format version (currently '1.0')",
+                "last_updated": "ISO 8601 timestamp of last write",
+                "pages": "Map of page title to { page_id, version }",
+            },
+            "behavior": [
+                "Created/updated automatically by page.publish, page.pull, and plan.apply",
+                "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",
+            ],
+        },
+        "assertions": {
+            "description": "Post-condition assertions verified by plan.verify.",
+            "file_format": "JSON array of assertion objects, or embedded in confpub.yaml under the 'assertions' key.",
+            "auto_generation": "When --plan is passed without --assertions, plan.verify auto-generates page.exists assertions for every create/update page in the plan.",
+            "types": {
+                "page.exists": {
+                    "description": "Verify that a page exists in the given space.",
+                    "required_fields": ["type", "space", "title"],
+                    "example": {"type": "page.exists", "space": "DEV", "title": "My Page"},
+                },
+                "page.parent": {
+                    "description": "Verify that a page has the expected parent.",
+                    "required_fields": ["type", "space", "title", "expected_parent"],
+                    "example": {"type": "page.parent", "space": "DEV", "title": "My Page", "expected_parent": "Parent Page"},
+                },
+                "attachment.exists": {
+                    "description": "Verify that an attachment exists on a page.",
+                    "required_fields": ["type", "space", "page", "filename"],
+                    "example": {"type": "attachment.exists", "space": "DEV", "page": "My Page", "filename": "diagram.png"},
+                },
+            },
+        },
         "auth": {
             "precedence": [
                 "--token + --user",

{confpub_cli-0.5.0 → confpub_cli-0.7.0}/confpub/manifest.py

@@ -139,7 +139,12 @@ def load_manifest(path: str) -> Manifest:
     p = Path(path)
     if not p.exists():
         from confpub.errors import ERR_IO_FILE_NOT_FOUND
-        raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"Manifest not found: {path}")
+        raise ConfpubError(
+            ERR_IO_FILE_NOT_FOUND,
+            f"Manifest not found: {path}",
+            retryable=False,
+            suggested_action="fix_input",
+        )
     try:
         data = yaml.safe_load(p.read_text(encoding="utf-8"))
         if not isinstance(data, dict):

{confpub_cli-0.5.0 → confpub_cli-0.7.0}/confpub/planner.py

@@ -70,6 +70,8 @@ def create_plan(
                 ERR_IO_FILE_NOT_FOUND,
                 f"Source file not found: {fp.file}",
                 details={"file": fp.file},
+                retryable=False,
+                suggested_action="fix_input",
             )
 
         # Read and convert markdown

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

@@ -35,6 +35,7 @@ def publish_page(
     space: str,
     parent: str,
     title: str | None = None,
+    page_id: str | None = None,
     dry_run: bool = False,
     backup: bool = False,
     progress_callback: Any = None,
@@ -49,6 +50,8 @@ def publish_page(
             ERR_IO_FILE_NOT_FOUND,
             f"Source file not found: {file}",
             details={"file": file},
+            retryable=False,
+            suggested_action="fix_input",
         )
 
     # Derive title from filename if not provided
@@ -71,7 +74,14 @@ def publish_page(
     existing_page_id = None
     current_version = None
 
-    if page_title in lockfile.pages:
+    if page_id:
+        # Direct page ID provided — skip lockfile/title lookup
+        existing_page_id = page_id
+        page_data = client.get_page_by_id(existing_page_id)
+        if page_data:
+            version = page_data.get("version", {})
+            current_version = version.get("number") if isinstance(version, dict) else version
+    elif page_title in lockfile.pages:
         existing_page_id = lockfile.pages[page_title].page_id
         page_data = client.get_page_by_id(existing_page_id)
         if page_data:
@@ -97,6 +107,12 @@ def publish_page(
     # Determine operation
     operation = "update" if existing_page_id else "create"
 
+    # 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"
+
     if dry_run:
         change: dict[str, Any] = {
             "type": f"page.{operation}",
@@ -122,6 +138,18 @@ def publish_page(
         return result_dict
 
     # Real publish
+    if operation == "noop":
+        return {
+            "dry_run": False,
+            "changes": [{
+                "type": "page.noop",
+                "title": page_title,
+                "confluence_page_id": existing_page_id,
+                "before": {"version": current_version} if current_version else None,
+            }],
+            "summary": {"noop": 1},
+        }
+
     backup_file_path: str | None = None
     if operation == "create":
         # Find parent page

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

@@ -107,8 +107,9 @@ def _compute_file_paths(
             while current and current != root_page_id:
                 chain.append(id_to_slug.get(current, current))
                 current = id_to_parent.get(current)  # type: ignore[assignment]
-            if pid == root_page_id:
-                chain.append(slug)
+            # Always include root as the outermost directory
+            if root_slug:
+                chain.append(root_slug)
             chain.reverse()
             rel_path = os.path.join(*chain, "index.md") if len(chain) > 0 else f"{slug}/index.md"
             paths[pid] = os.path.join(output_dir, rel_path)
@@ -185,6 +186,7 @@ def _build_page_tree(
     pages: list[dict[str, Any]],
     file_paths: dict[str, str],
     root_page_id: str,
+    output_dir: str = ".",
 ) -> list[dict[str, Any]]:
     """Build a hierarchical page tree for manifest generation."""
     id_to_entry: dict[str, dict[str, Any]] = {}
@@ -198,7 +200,7 @@ def _build_page_tree(
 
         id_to_entry[pid] = {
             "title": page.get("title", ""),
-            "file": os.path.basename(file_path) if file_path else "",
+            "file": os.path.relpath(file_path, output_dir) if file_path else "",
             "children": [],
         }
         children_map.setdefault(parent_id, []).append(pid)
@@ -308,10 +310,13 @@ def pull_pages(
 
     # Generate manifest if requested or recursive with multiple pages
     manifest_file: str | None = None
-    if generate_manifest or (recursive and len(all_pages) > 1):
+    if generate_manifest:
         root_title = root_page.get("title", "")
-        page_tree = _build_page_tree(all_pages, file_paths, root_id)
-        manifest_yaml = generate_manifest_yaml(root_space, root_title, page_tree)
+        # Determine the actual parent of the root page
+        ancestors = client.get_page_ancestors(root_id)
+        manifest_parent = ancestors[-1].get("title", root_title) if ancestors else root_title
+        page_tree = _build_page_tree(all_pages, file_paths, root_id, output_dir)
+        manifest_yaml = generate_manifest_yaml(root_space, manifest_parent, page_tree)
         manifest_path = os.path.join(output_dir, "confpub.yaml")
         Path(manifest_path).write_text(manifest_yaml, encoding="utf-8")
         manifest_file = manifest_path

{confpub_cli-0.5.0 → confpub_cli-0.7.0}/confpub/validator.py

@@ -19,9 +19,14 @@ from confpub.manifest import PlanArtifact, PlanPage
 
 def _load_plan(plan_path: str) -> PlanArtifact:
     """Load and parse a plan artifact JSON file."""
-    p = Path(plan_path)
+    p = Path(plan_path).resolve()
     if not p.exists():
-        raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"Plan file not found: {plan_path}")
+        raise ConfpubError(
+            ERR_IO_FILE_NOT_FOUND,
+            f"Plan file not found: {plan_path}",
+            retryable=False,
+            suggested_action="fix_input",
+        )
     try:
         data = json.loads(p.read_text(encoding="utf-8"))
         return PlanArtifact(**data)

{confpub_cli-0.5.0 → confpub_cli-0.7.0}/confpub/verifier.py

@@ -20,7 +20,12 @@ def _load_assertions(assertions_path: str | None, plan_path: str | None) -> list
     if assertions_path:
         p = Path(assertions_path)
         if not p.exists():
-            raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"Assertions file not found: {assertions_path}")
+            raise ConfpubError(
+                ERR_IO_FILE_NOT_FOUND,
+                f"Assertions file not found: {assertions_path}",
+                retryable=False,
+                suggested_action="fix_input",
+            )
         try:
             data = json.loads(p.read_text(encoding="utf-8"))
             if isinstance(data, list):
@@ -30,13 +35,41 @@ def _load_assertions(assertions_path: str | None, plan_path: str | None) -> list
             raise ConfpubError(ERR_VALIDATION_MANIFEST, f"Invalid assertions JSON: {exc}") from exc
 
     if plan_path:
-        # Try to load assertions from the plan's source manifest
         p = Path(plan_path)
         if not p.exists():
-            raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"Plan file not found: {plan_path}")
+            raise ConfpubError(
+                ERR_IO_FILE_NOT_FOUND,
+                f"Plan file not found: {plan_path}",
+                retryable=False,
+                suggested_action="fix_input",
+            )
+
+        # Check for confpub.yaml alongside the plan file
+        manifest_path = p.parent / "confpub.yaml"
+        if manifest_path.exists():
+            try:
+                import yaml
+                manifest_data = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
+                if isinstance(manifest_data, dict) and manifest_data.get("assertions"):
+                    raw = manifest_data["assertions"]
+                    if isinstance(raw, list):
+                        return raw
+            except Exception:
+                pass
+
+        # Auto-generate page.exists assertions from the plan
         plan_data = json.loads(p.read_text(encoding="utf-8"))
-        # Plan doesn't contain assertions directly — return empty
-        return []
+        auto: list[dict[str, Any]] = []
+        space = plan_data.get("space", "")
+        for page in plan_data.get("pages", []):
+            op = page.get("operation", "")
+            if op in ("create", "update"):
+                auto.append({
+                    "type": "page.exists",
+                    "space": space,
+                    "title": page.get("title", ""),
+                })
+        return auto
 
     return []
 
@@ -78,14 +111,22 @@ def verify_assertions(
                 all_passed = False
 
         elif a_type == "page.parent":
+            space = assertion.get("space", "")
             title = assertion.get("title", "")
             expected_parent = assertion.get("expected_parent", "")
             result["title"] = title
-            # Get page and check its parent
-            # This is a simplified check — in a full implementation
-            # we'd look up the page's ancestor chain
-            result["passed"] = True  # Simplified for now
             result["expected_parent"] = expected_parent
+            page = client.get_page(space, title) if space else None
+            if page:
+                ancestors = client.get_page_ancestors(str(page["id"]))
+                actual_parent = ancestors[-1].get("title", "") if ancestors else ""
+                result["actual_parent"] = actual_parent
+                result["passed"] = actual_parent == expected_parent
+            else:
+                result["passed"] = False
+                result["error"] = f"Page '{title}' not found"
+            if not result["passed"]:
+                all_passed = False
 
         elif a_type == "attachment.exists":
             page_title = assertion.get("page", "")

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

@@ -52,7 +52,7 @@ class TestGetPage:
         result = client.get_page("DEV", "Test")
         assert result["id"] == "123"
         client._mock_api.get_page_by_title.assert_called_once_with(
-            "DEV", "Test", expand="version,body.storage,space"
+            "DEV", "Test", expand="version,body.storage,space,ancestors"
         )
 
     def test_returns_none_when_not_found(self, client):

{confpub_cli-0.5.0 → confpub_cli-0.7.0}/tests/test_guide.py

@@ -6,7 +6,7 @@ from confpub.guide import build_guide
 class TestBuildGuide:
     def test_has_required_top_level_keys(self):
         guide = build_guide()
-        for key in ("schema_version", "commands", "error_codes", "auth", "concurrency"):
+        for key in ("schema_version", "commands", "error_codes", "auth", "concurrency", "lockfile"):
             assert key in guide, f"Missing top-level key: {key}"
 
     def test_all_commands_present(self):

{confpub_cli-0.5.0 → confpub_cli-0.7.0}/tests/test_puller.py

@@ -58,11 +58,15 @@ def _mock_client(pages: dict[str, dict], children: dict[str, list] | None = None
     def download_attachment(pid, filename, path):
         return False
 
+    def get_page_ancestors(pid):
+        return []
+
     client.get_page_by_id = get_page_by_id
     client.get_page = get_page
     client.get_page_children_deep = get_page_children_deep
     client.get_attachments = get_attachments
     client.download_attachment = download_attachment
+    client.get_page_ancestors = get_page_ancestors
     return client
 
 
@@ -176,6 +180,7 @@ class TestRecursivePull:
                 page_id="1",
                 output_dir=str(tmp_path),
                 recursive=True,
+                generate_manifest=True,
             )
 
         assert result["summary"]["manifest_generated"] is True
@@ -265,7 +270,7 @@ class TestLayoutModes:
 
         assert result["layout"] == "nested"
         assert (tmp_path / "root" / "index.md").exists()
-        assert (tmp_path / "child" / "index.md").exists()
+        assert (tmp_path / "root" / "child" / "index.md").exists()
 
 
 # ---------------------------------------------------------------------------
@@ -405,6 +410,7 @@ class TestDataCenterCompat:
             result = pull_pages(
                 space="PROJ", title="Root",
                 output_dir=str(tmp_path), recursive=True,
+                generate_manifest=True,
             )
 
         assert result["summary"]["pages_pulled"] == 2

{confpub_cli-0.5.0 → confpub_cli-0.7.0}/tests/test_verifier.py

@@ -12,7 +12,7 @@ from confpub.verifier import verify_assertions
 
 SAMPLE_ASSERTIONS = [
     {"type": "page.exists", "space": "DEV", "title": "Overview"},
-    {"type": "page.parent", "title": "Child", "expected_parent": "Overview"},
+    {"type": "page.parent", "space": "DEV", "title": "Child", "expected_parent": "Overview"},
     {"type": "attachment.exists", "space": "DEV", "page": "Overview", "filename": "arch.png"},
 ]
 
@@ -31,6 +31,7 @@ class TestVerifyAssertions:
         mock_client = MagicMock()
         mock_client.get_page.return_value = {"id": "123", "title": "Overview"}
         mock_client.get_attachments.return_value = [{"title": "arch.png"}]
+        mock_client.get_page_ancestors.return_value = [{"id": "100", "title": "Overview"}]
         MockClient.return_value = mock_client
         mock_config.return_value = MagicMock()
 

confpub_cli-0.5.0/FEEDBACK.md

@@ -1,226 +0,0 @@
-# confpub-cli v0.2.3 — Blind Test Feedback
-
-**Tester**: Claude Opus 4.6 (LLM agent)
-**Date**: 2026-03-01
-**Environment**: Windows 11, bash shell, `uvx confpub-cli`
-**Confluence**: Cloud instance (thomasklokrohde.atlassian.net)
-
----
-
-## Overall Impression
-
-confpub-cli is a remarkably well-designed agent-first CLI. As an LLM agent driving it
-zero-shot, I was productive within seconds. The `guide` command gave me everything I
-needed to understand the full command surface, error taxonomy, and concurrency rules.
-The consistent JSON envelope made it trivial to parse every response. This is one of
-the best-designed CLIs I've encountered for agent consumption.
-
-**Rating: 4/5** — Excellent foundation with a handful of rough edges to polish.
-
----
-
-## What Works Well
-
-### Structured JSON Envelope
-Every command returns the same `{ ok, command, target, result, warnings, errors, metrics }`
-shape. Parsing is zero-effort. The `request_id` and `metrics.duration_ms` fields are a
-nice touch for tracing and diagnostics.
-
-### `guide` Command
-Brilliant bootstrapping mechanism. One call gives an agent: every command with its flags,
-mutability annotations, error codes with exit codes and retry hints, auth precedence,
-and concurrency rules. The `--section` flag is useful for targeted queries. This alone
-puts confpub ahead of most CLI tools for agent integration.
-
-### Transactional Plan Workflow
-The plan → validate → apply → verify pipeline is well thought out:
-- `plan create` generates a readable artifact with clear operation types
-- `plan validate` checks for drift before apply
-- `plan apply` supports `--dry-run` for preview
-- The lockfile (`confpub.lock`) enables idempotent re-publishing
-
-I tested the full cycle and it worked flawlessly: manifest → plan → validate → dry-run → apply → verify.
-
-### Markdown Conversion
-Tested headings, bold/italic, inline code, fenced code blocks (with language), tables,
-admonitions (`[!NOTE]`, `[!WARNING]`, `[!TIP]`), strikethrough, and horizontal rules.
-All converted correctly to Confluence Storage Format. Particularly impressed that
-admonitions map to the proper Confluence Info/Warning/Tip macros.
-
-### Error Taxonomy
-Stable error codes (`ERR_*`) with structured details, exit codes, and `suggested_action`
-hints (`fix_input`, `retry`, `reauth`, `escalate`). An agent can branch on these without
-parsing human-readable messages. The `retryable` flag and `retry_after_ms` for I/O errors
-are agent-friendly.
-
-### Safety Design
-- Write commands are clearly annotated as `mutates: true` in the guide
-- `--dry-run` is available on both `page publish` and `plan apply`
-- `--cascade` is a separate opt-in for cascading deletes
-- `safety_flags` section in the guide calls out dangerous flags
-
-### Auth Resolution
-Clean precedence chain (flags → env vars → config file → keychain) with auto-detection
-of Cloud vs Server from the URL. `auth inspect` gives a quick status check.
-
----
-
-## Bugs Found
-
-### BUG-1: `--space` flag ignored during page update (Severity: High)
-
-When I published a page to space `SD`, then re-published with `--space NONEXIST`, the
-command succeeded (exit 0) and updated the existing page in the `SD` space. The `--space`
-flag was silently ignored on the update path.
-
-**Repro:**
-```bash
-confpub page publish test.md --space SD --parent "Software Development"
-# Creates page in SD, version 1
-
-confpub page publish test.md --space NONEXIST --parent "Software Development"
-# Expected: error (space not found or page not found in that space)
-# Actual: ok=true, updated page in SD to version 3
-```
-
-**Impact**: An agent could accidentally update a page in the wrong space without any
-warning. The title-based lookup appears to match globally (or against the lockfile)
-rather than scoping to the specified space.
-
-### BUG-2: Nonexistent page returns `ok: true` with `result: null` (Severity: Medium)
-
-```bash
-confpub page inspect --space SD --title "nonexistent-page"
-# Returns: ok=true, result=null, errors=[]
-```
-
-This should return `ok: false` with an appropriate error (e.g., a new `ERR_NOT_FOUND`
-code). An agent checking `ok` to determine success would incorrectly think the call
-succeeded. Currently the only way to detect "not found" is to check if `result` is null,
-which is an undocumented convention.
-
-A `"Can't find ... page"` message also leaks to stderr, suggesting the underlying library
-knows it's not found — the CLI just doesn't surface it as a structured error.
-
-### BUG-3: Missing required options return exit code 2, not JSON envelope (Severity: Medium)
-
-```bash
-confpub page list
-# Returns Typer's error format: "Missing option '--space'." with exit code 2
-```
-
-This breaks the documented invariant: "stdout is exclusively JSON — one object, no
-preamble, no epilogue." An agent expecting to always parse JSON on stdout will crash.
-Exit code 2 is also undocumented (the error code table only covers 0/10/20/40/50/90).
-
-**Suggestion**: Catch Typer's `MissingParameter` and convert it to an
-`ERR_VALIDATION_REQUIRED` envelope with exit code 10.
-
-### BUG-4: `--backup` flag produces no observable output (Severity: Low)
-
-```bash
-confpub page publish test.md --space SD --parent "Software Development" --backup
-```
-
-The command succeeded but the result JSON contains no mention of a backup being created —
-no backup file path, no `backup: true` field, nothing. Either the backup didn't happen,
-or it happened silently. An agent has no way to confirm.
-
-### BUG-5: Nonexistent parent accepted in dry-run (Severity: Low)
-
-```bash
-confpub page publish test.md --space SD --parent "Nonexistent Parent" --dry-run
-# Returns: ok=true, type=page.update
-```
-
-Dry-run should ideally validate that the parent page exists, or at least emit a warning.
-Currently it plans an update to a nonexistent parent, which would fail on real apply.
-
----
-
-## Improvement Suggestions
-
-### 1. Normalize attachment command output
-
-`attachment.list` and `attachment.upload` return raw Confluence API responses with
-internal fields (`_expandable`, ARIs, `base64EncodedAri`, full user profiles). Every
-other command returns a curated result. These should be normalized to the same level
-of curation.
-
-**Suggested `attachment.list` shape:**
-```json
-{
-  "attachments": [
-    {
-      "id": "att262400",
-      "title": "test-attachment.txt",
-      "media_type": "application/binary",
-      "file_size": 27,
-      "download_url": "/download/attachments/360459/test-attachment.txt?..."
-    }
-  ]
-}
-```
-
-### 2. Add `--format` flag or page count to `page.list`
-
-For spaces with many pages, `page.list` returns everything. Consider:
-- A `--limit` / `--offset` for pagination
-- A `--format compact` option (just titles + IDs)
-- Include total count in the result
-
-### 3. Suppress `"Can't find ... page"` stderr noise
-
-Multiple commands emit `"Can't find 'X' page on ..."` to stderr. This comes from the
-underlying `atlassian-python-api` library but leaks through even with `--quiet`. Since
-not finding a page is a normal flow (e.g., first publish), this shouldn't appear by
-default — maybe only with `--verbose`.
-
-### 4. Add stdin support
-
-`echo "# Hello" | confpub page publish - --space SD --parent "Docs" --title "Hello"`
-would be useful for piped workflows and agent-generated content. Currently `-` is treated
-as a literal filename.
-
-### 5. `plan verify` with no assertions is a no-op
-
-```bash
-confpub plan verify --plan confpub-plan.json
-# Returns: all_passed=true, results=[]
-```
-
-Without `--assertions`, this always passes vacuously. Consider:
-- Auto-generating basic assertions from the plan (pages exist, correct parent, version incremented)
-- Emitting a warning when no assertions are provided
-
-### 6. Consider `--json` flag for Typer-level errors
-
-As a bridge until BUG-3 is fully fixed, a `--json` flag could force JSON output even
-for framework-level errors (missing options, unknown commands).
-
-### 7. Lockfile includes pages from `page publish` and `plan apply`
-
-The lockfile accumulated entries from both `page publish` (single-file mode) and
-`plan apply`. This might be intentional for idempotency, but it could surprise users
-who expected the lockfile to only track manifest-managed pages. Consider documenting
-this behavior or separating the two.
-
----
-
-## Summary
-
-| Area | Score |
-|------|-------|
-| Agent discoverability (`guide`) | 5/5 |
-| JSON envelope consistency | 4/5 (BUG-3 breaks it for Typer errors) |
-| Error handling | 4/5 (BUG-2 masks not-found) |
-| Markdown conversion | 5/5 |
-| Plan workflow | 5/5 |
-| Write correctness | 3/5 (BUG-1 is a real data integrity risk) |
-| Output curation | 3/5 (attachments leak raw API) |
-| Documentation (README) | 5/5 |
-
-confpub is production-ready for the core read + plan + publish workflows. The main
-blocker is BUG-1 (space flag ignored on updates), which could cause silent cross-space
-writes. Fixing that plus normalizing the attachment output would bring this to a
-strong 5/5.