confpub-cli 0.8.0__tar.gz → 1.1.0__tar.gz

confpub_cli-1.1.0/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+```bash
+uv pip install -e ".[dev]"              # Install with dev deps
+pytest tests/ -v                        # Run all tests
+pytest tests/test_converter.py -v       # Run one test module
+pytest tests/test_converter.py::TestHeadings::test_h1 -v  # Run single test
+pytest tests/ -k "fingerprint" -v       # Run tests matching name pattern
+pytest tests/ -v --cov=confpub          # Run with coverage
+uvx hatch version minor                 # Bump version (patch/minor/major)
+```
+
+No linter is configured. Python 3.10+ required.
+
+## Architecture
+
+Agent-first CLI for publishing Markdown to Confluence. Every command returns structured JSON on stdout; stderr is reserved for progress/diagnostics.
+
+### Command flow
+
+All commands follow the same pattern through `cli.py`:
+
+1. Typer handler receives flags
+2. `command_context()` context manager wraps execution — catches `ConfpubError` and unexpected exceptions, records timing, emits the JSON envelope via `Envelope` (envelope.py)
+3. Handler delegates to a domain module (publish.py, applier.py, puller.py, etc.)
+4. Domain module calls `ConfluenceClient` (confluence.py) which wraps atlassian-python-api and translates its exceptions into `ConfpubError`
+
+### Key design rules
+
+- **stdout is JSON-only** — one envelope object per invocation, never mixed with text
+- **Error codes are stable** — prefixed by category (`ERR_VALIDATION_*`, `ERR_AUTH_*`, `ERR_CONFLICT_*`, `ERR_IO_*`, `ERR_INTERNAL_*`), each maps to a fixed exit code via prefix (10/20/40/50/90). Never rename or remove error codes without a major version bump.
+- **`ConfpubError`** carries code, message, retryable flag, suggested_action, and details dict — all fields flow into the envelope's `errors` array
+- **Lockfile** (`confpub.lock`) maps page titles to Confluence page IDs for idempotent re-publishing. Updated by publish, pull, apply, and delete. Uses atomic writes (tempfile + rename).
+
+### Transactional workflow
+
+`plan create` → `plan validate` → `plan apply` → `plan verify` — each step is a separate command with no side effects except apply. Fingerprinting (SHA-256 of storage-format body) detects external edits between plan creation and apply.
+
+### Markdown conversion
+
+`converter.py` uses markdown-it-py with a custom `ConfluenceRenderer` to produce Confluence Storage Format XHTML. `reverse_converter.py` does the inverse using BeautifulSoup4 + markdownify. Both are pure functions (no I/O, no network).
+
+### Test conventions
+
+- Tests use `typer.testing.CliRunner` via `run_cli` fixture (conftest.py)
+- Confluence API calls are mocked with `unittest.mock` — no live integration tests
+- Test classes group related cases (e.g., `TestHeadings`, `TestApplyPlanReal`)
+- New domain functions get unit tests; CLI-level behavior gets integration tests in `test_integration.py`
+
+## Version
+
+Defined in `confpub/__init__.py`, read by hatch from `pyproject.toml` config. Bump with `uvx hatch version`. Push to `main` triggers GitHub Actions publish to PyPI.

{confpub_cli-0.8.0 → confpub_cli-1.1.0}/PKG-INFO

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

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

{confpub_cli-0.8.0 → confpub_cli-1.1.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
@@ -125,7 +125,7 @@ def apply_plan(
                     counts["attachments_upload"] += len(assets)
 
                 # Update lockfile and parent tracking
-                update_lockfile(lockfile, page.title, new_id, new_version if isinstance(new_version, int) else 1)
+                update_lockfile(lockfile, page.title, new_id, new_version if isinstance(new_version, int) else 1, content_fingerprint=fingerprint_content(storage))
                 parent_ids[page.title] = new_id
 
             counts["create"] += 1
@@ -179,6 +179,7 @@ def apply_plan(
                 update_lockfile(
                     lockfile, page.title, page.confluence_page_id,
                     new_version if isinstance(new_version, int) else 1,
+                    content_fingerprint=fingerprint_content(storage),
                 )
                 parent_ids[page.title] = page.confluence_page_id
 
@@ -193,4 +194,6 @@ def apply_plan(
         "dry_run": dry_run,
         "changes": changes,
         "summary": counts,
+        "lockfile_updated": not dry_run and len(changes) > 0,
+        "lockfile_path": str(lockfile_path) if not dry_run else None,
     }

{confpub_cli-0.8.0 → confpub_cli-1.1.0}/confpub/cli.py

@@ -22,12 +22,22 @@ from confpub.output import emit_stderr, emit_stdout, is_verbose, set_quiet, set_
 # Subcommand group apps
 # ---------------------------------------------------------------------------
 
-page_app = typer.Typer(help="Page operations")
-plan_app = typer.Typer(help="Transactional plan workflow")
-auth_app = typer.Typer(help="Authentication")
-config_app = typer.Typer(help="Configuration")
-space_app = typer.Typer(help="Space operations")
-attachment_app = typer.Typer(help="Attachment operations")
+
+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"),
+) -> None:
+    """Allow --quiet/--verbose between the group name and the subcommand."""
+    set_quiet(quiet)
+    set_verbose(verbose)
+
+
+page_app = typer.Typer(help="Page operations", callback=_group_callback)
+plan_app = typer.Typer(help="Transactional plan workflow", callback=_group_callback)
+auth_app = typer.Typer(help="Authentication", callback=_group_callback)
+config_app = typer.Typer(help="Configuration", callback=_group_callback)
+space_app = typer.Typer(help="Space operations", callback=_group_callback)
+attachment_app = typer.Typer(help="Attachment operations", callback=_group_callback)
 
 # ---------------------------------------------------------------------------
 # Main app
@@ -171,12 +181,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]}
 
 
@@ -307,12 +319,35 @@ def page_delete(
             )
         from confpub.confluence import build_client
         client = build_client()
+
+        # Collect descendant IDs before deleting (for lockfile cleanup)
+        deleted_ids: set[str] = set()
         if page_id:
             if cascade:
+                deleted_ids.update(client.get_descendant_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"])
+                    deleted_ids.update(client.get_descendant_ids(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 load_lockfile, save_lockfile, remove_by_page_ids
+        lockfile_path = Path.cwd() / "confpub.lock"
+        lockfile = load_lockfile(lockfile_path)
+        if lockfile and remove_by_page_ids(lockfile, deleted_ids, title=title if not page_id else None):
+            save_lockfile(lockfile_path, lockfile)
+
+        # Enrich result with deleted ID summary
+        result["deleted_ids"] = sorted(deleted_ids)
+        result["deleted_count"] = len(deleted_ids)
         ctx.result = result
 
 
@@ -494,6 +529,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
 
 

{confpub_cli-0.8.0 → confpub_cli-1.1.0}/confpub/confluence.py

@@ -187,6 +187,16 @@ class ConfluenceClient:
             self._delete_descendants(page_id)
         return self.delete_page(page_id)
 
+    def get_descendant_ids(self, page_id: str) -> set[str]:
+        """Recursively collect all descendant page IDs."""
+        ids: set[str] = set()
+        children = self.get_page_children(page_id)
+        for child in children:
+            child_id = str(child["id"])
+            ids.add(child_id)
+            ids.update(self.get_descendant_ids(child_id))
+        return ids
+
     def _delete_descendants(self, page_id: str) -> None:
         """Recursively delete all descendants depth-first (leaves first)."""
         children = self.get_page_children(page_id)
@@ -262,11 +272,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")

{confpub_cli-0.8.0 → confpub_cli-1.1.0}/confpub/guide.py

@@ -66,7 +66,11 @@ def build_guide() -> dict[str, Any]:
                 "mutates": False,
                 "description": "Search Confluence content using CQL",
                 "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.",
+                "agent_hint": (
+                    "Most agent workflows should include --type page to exclude attachments and space entities from results. "
+                    "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."
+                ),
                 "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}",
@@ -80,25 +84,49 @@ def build_guide() -> dict[str, Any]:
                     "confpub search --space DEV --type page --limit 10",
                     'confpub search --space DEV --cql \'title ~ "deploy"\'',
                     'confpub search --title "deploy guide" --space DEV',
+                    "confpub search --space DEV --type page --start 0 --limit 50",
                 ],
             },
             "page.list": {
                 "group": "read",
                 "mutates": False,
                 "description": "List pages in a Confluence space",
-                "flags": ["--space"],
+                "flags": ["--space", "--limit", "--start"],
             },
             "page.inspect": {
                 "group": "read",
                 "mutates": False,
                 "description": "Inspect a Confluence page",
-                "flags": ["--space", "--title", "--page-id", "--format"],
+                "flags": ["--space", "--title", "--page-id", "--format", "--raw"],
+                "agent_hint": (
+                    "Use --format markdown to get the page body as Markdown instead of Confluence storage format. "
+                    "Use --raw for the full unprocessed API response (useful for debugging)."
+                ),
+                "result_schema": {
+                    "page_id": "string",
+                    "title": "string",
+                    "space_key": "string",
+                    "version": "int",
+                    "url": "string",
+                    "body_storage": "string (when --format storage, the default)",
+                    "body_markdown": "string (when --format markdown)",
+                },
+                "examples": [
+                    'confpub page inspect --space DEV --title "My Page"',
+                    "confpub page inspect --page-id 12345 --format markdown",
+                    "confpub page inspect --page-id 12345 --raw",
+                ],
             },
             "page.publish": {
                 "group": "write",
                 "mutates": True,
                 "description": "Publish a single Markdown file to Confluence",
                 "flags": ["--space", "--parent", "--title", "--page-id", "--dry-run", "--backup"],
+                "agent_hint": (
+                    "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'."
+                ),
             },
             "page.pull": {
                 "group": "read",
@@ -112,6 +140,11 @@ def build_guide() -> dict[str, Any]:
                 "safety_flags": {
                     "--force": "Overwrites existing local files without confirmation",
                 },
+                "agent_hint": (
+                    "During recursive pulls, NDJSON progress events are emitted on stderr "
+                    "with step (running discovery count) and total (0 until known). "
+                    "Use --quiet to suppress."
+                ),
             },
             "page.delete": {
                 "group": "write",
@@ -121,6 +154,10 @@ def build_guide() -> dict[str, Any]:
                 "safety_flags": {
                     "--cascade": "Also deletes child pages",
                 },
+                "result_schema": {
+                    "deleted_ids": "list of string — sorted page IDs that were deleted",
+                    "deleted_count": "int — number of pages deleted (including children when --cascade)",
+                },
             },
             "space.list": {
                 "group": "read",
@@ -167,6 +204,13 @@ def build_guide() -> dict[str, Any]:
                     ),
                     "--cascade": "Allows deletes that affect child pages",
                 },
+                "result_schema": {
+                    "dry_run": "bool",
+                    "changes": "list of change records",
+                    "summary": "{create: int, update: int, attachments_upload: int}",
+                    "lockfile_updated": "bool — true if lockfile was written",
+                    "lockfile_path": "string | null — absolute path to lockfile (null on dry-run)",
+                },
             },
             "plan.verify": {
                 "group": "transactional",
@@ -185,6 +229,16 @@ def build_guide() -> dict[str, Any]:
                 "mutates": True,
                 "description": "Set a configuration value",
                 "flags": [],
+                "args": ["KEY", "VALUE"],
+                "agent_hint": (
+                    "Valid keys: base_url, user, token. "
+                    "Values are persisted to the config file (~/.confpub/config.json)."
+                ),
+                "examples": [
+                    "confpub config set base_url https://mysite.atlassian.net/wiki",
+                    "confpub config set user alice@example.com",
+                    "confpub config set token ATATT...",
+                ],
             },
             "config.inspect": {
                 "group": "config",
@@ -216,6 +270,19 @@ def build_guide() -> dict[str, Any]:
             ERR_INTERNAL_REVERSE_CONVERTER: _error_code_entry(ERR_INTERNAL_REVERSE_CONVERTER),
             ERR_INTERNAL_SDK: _error_code_entry(ERR_INTERNAL_SDK),
         },
+        "global_flags": {
+            "description": "Flags that can be placed at the top level or between group name and subcommand.",
+            "flags": {
+                "--quiet": "Suppress progress output on stderr",
+                "--verbose": "Include diagnostics in result",
+                "--version": "Show version and exit (top-level only)",
+            },
+            "placement": [
+                "confpub --quiet page publish ...  (before the group)",
+                "confpub page --quiet publish ...  (between group and command)",
+                "Both positions are equivalent; the flag is parsed by the group callback",
+            ],
+        },
         "concurrency": {
             "rule": (
                 "Never run multiple write commands against the same "
@@ -244,9 +311,15 @@ 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",
+                (
+                    "Path resolution: page.publish and page.delete use CWD/confpub.lock; "
+                    "page.pull uses <output-dir>/confpub.lock; "
+                    "plan.apply uses <plan-dir>/confpub.lock (same directory as the plan artifact)"
+                ),
             ],
         },
         "assertions": {

{confpub_cli-0.8.0 → confpub_cli-1.1.0}/confpub/lockfile.py

@@ -86,7 +86,36 @@ def save_lockfile(path: str | Path, lockfile: Lockfile) -> None:
 
 def update_lockfile(
     lockfile: Lockfile, title: str, page_id: str, version: int,
+    content_fingerprint: str | None = None,
 ) -> Lockfile:
     """Update a page entry in the lockfile."""
-    lockfile.pages[title] = LockPageEntry(page_id=page_id, version=version)
+    lockfile.pages[title] = LockPageEntry(
+        page_id=page_id, version=version, content_fingerprint=content_fingerprint,
+    )
     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
+
+
+def remove_by_page_ids(lockfile: Lockfile, page_ids: set[str], title: str | None = None) -> bool:
+    """Remove lockfile entries matching any of the given page IDs, plus an optional title.
+
+    Returns True if any entries were removed.
+    """
+    removed = False
+    if title:
+        removed = remove_from_lockfile(lockfile, title) or removed
+    for lf_title, entry in list(lockfile.pages.items()):
+        if entry.page_id in page_ids:
+            del lockfile.pages[lf_title]
+            removed = True
+    return removed

{confpub_cli-0.8.0 → confpub_cli-1.1.0}/confpub/publish.py

@@ -194,8 +194,7 @@ def publish_page(
 
     # Update lockfile
     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
+    update_lockfile(lockfile, page_title, page_id, new_version_int, content_fingerprint=local_fingerprint)
     save_lockfile(lockfile_path, lockfile)
 
     change = {

{confpub_cli-0.8.0 → confpub_cli-1.1.0}/confpub/puller.py

@@ -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_progress(0, 0, f"Found {len(children)} child page(s) under {pid}")
+            emit_progress(len(pages) + 1, 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.8.0 → confpub_cli-1.1.0}/tests/test_applier.py

@@ -127,6 +127,63 @@ 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 TestApplyLockfilePath:
+    @patch("confpub.applier.load_config")
+    @patch("confpub.applier.ConfluenceClient")
+    def test_lockfile_path_present_on_real_apply(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_path"] is not None
+        assert "confpub.lock" in result["lockfile_path"]
+
+    @patch("confpub.applier.load_config")
+    @patch("confpub.applier.ConfluenceClient")
+    def test_lockfile_path_null_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_path"] is None
+
+
 class TestFingerprintCheck:
     @patch("confpub.applier.load_config")
     @patch("confpub.applier.ConfluenceClient")

{confpub_cli-0.8.0 → confpub_cli-1.1.0}/tests/test_guide.py

@@ -112,3 +112,64 @@ class TestBuildGuide:
         assert "rule" in concurrency
         assert "safe_patterns" in concurrency
         assert len(concurrency["safe_patterns"]) > 0
+
+    def test_global_flags_section(self):
+        guide = build_guide()
+        assert "global_flags" in guide
+        gf = guide["global_flags"]
+        assert "--quiet" in gf["flags"]
+        assert "--verbose" in gf["flags"]
+        assert "placement" in gf
+        assert len(gf["placement"]) > 0
+
+    def test_page_inspect_has_raw_flag(self):
+        guide = build_guide()
+        cmd = guide["commands"]["page.inspect"]
+        assert "--raw" in cmd["flags"]
+        assert "result_schema" in cmd
+        assert "examples" in cmd
+        assert "agent_hint" in cmd
+
+    def test_page_publish_has_title_inference_hint(self):
+        guide = build_guide()
+        cmd = guide["commands"]["page.publish"]
+        assert "agent_hint" in cmd
+        assert "title-cased" in cmd["agent_hint"]
+
+    def test_page_pull_has_progress_hint(self):
+        guide = build_guide()
+        cmd = guide["commands"]["page.pull"]
+        assert "agent_hint" in cmd
+        assert "progress" in cmd["agent_hint"].lower()
+
+    def test_page_delete_has_result_schema(self):
+        guide = build_guide()
+        cmd = guide["commands"]["page.delete"]
+        assert "result_schema" in cmd
+        assert "deleted_ids" in cmd["result_schema"]
+        assert "deleted_count" in cmd["result_schema"]
+
+    def test_plan_apply_has_result_schema(self):
+        guide = build_guide()
+        cmd = guide["commands"]["plan.apply"]
+        assert "result_schema" in cmd
+        assert "lockfile_path" in cmd["result_schema"]
+
+    def test_config_set_has_args_and_examples(self):
+        guide = build_guide()
+        cmd = guide["commands"]["config.set"]
+        assert "args" in cmd
+        assert "agent_hint" in cmd
+        assert "examples" in cmd
+        assert len(cmd["examples"]) > 0
+
+    def test_search_has_pagination_example(self):
+        guide = build_guide()
+        cmd = guide["commands"]["search"]
+        assert any("--start" in ex for ex in cmd["examples"])
+        assert "pagination" in cmd["agent_hint"].lower()
+
+    def test_lockfile_path_resolution_documented(self):
+        guide = build_guide()
+        behaviors = guide["lockfile"]["behavior"]
+        assert any("Path resolution" in b for b in behaviors)

{confpub_cli-0.8.0 → confpub_cli-1.1.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 []
 
@@ -163,6 +163,51 @@ class TestSearchCommand:
         assert "search" in result.output
 
 
+class TestQuietFlagPosition:
+    """Bug 1: --quiet and --verbose should work between group name and subcommand."""
+
+    def test_quiet_before_group(self):
+        result = runner.invoke(app, ["--quiet", "page", "--help"])
+        assert result.exit_code == 0
+
+    def test_quiet_between_group_and_command(self):
+        result = runner.invoke(app, ["page", "--quiet", "--help"])
+        assert result.exit_code == 0
+
+    def test_verbose_between_group_and_command(self):
+        result = runner.invoke(app, ["page", "--verbose", "--help"])
+        assert result.exit_code == 0
+
+    def test_quiet_on_plan_group(self):
+        result = runner.invoke(app, ["plan", "--quiet", "--help"])
+        assert result.exit_code == 0
+
+
+class TestDeleteCascadeResult:
+    """Bug 3: Delete result should include deleted_ids and deleted_count."""
+
+    def test_delete_result_has_deleted_ids(self, monkeypatch):
+        from confpub.confluence import ConfluenceClient
+
+        mock_client = ConfluenceClient.__new__(ConfluenceClient)
+        monkeypatch.setattr("confpub.confluence.build_client", lambda: mock_client)
+        monkeypatch.setattr(mock_client, "get_descendant_ids", lambda pid: ["child1", "child2"])
+        monkeypatch.setattr(mock_client, "_delete_descendants", lambda pid: None)
+        monkeypatch.setattr(mock_client, "delete_page", lambda pid: {"status": "deleted"})
+
+        # Prevent lockfile I/O
+        monkeypatch.setattr("confpub.lockfile.load_lockfile", lambda p: None)
+
+        result = runner.invoke(app, ["page", "delete", "--page-id", "123", "--cascade"])
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert data["ok"] is True
+        assert "deleted_ids" in data["result"]
+        assert "deleted_count" in data["result"]
+        assert data["result"]["deleted_count"] == 3  # page + 2 children
+        assert sorted(data["result"]["deleted_ids"]) == ["123", "child1", "child2"]
+
+
 class TestEnvelopeContract:
     def test_guide_returns_full_envelope(self):
         result = runner.invoke(app, ["guide"])

{confpub_cli-0.8.0 → confpub_cli-1.1.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