confpub-cli 1.0.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-1.0.0 → confpub_cli-1.1.0}/PKG-INFO

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

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

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

@@ -125,8 +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)
-                lockfile.pages[page.title].content_fingerprint = fingerprint_content(storage)
+                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
@@ -180,8 +179,8 @@ 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),
                 )
-                lockfile.pages[page.title].content_fingerprint = fingerprint_content(storage)
                 parent_ids[page.title] = page.confluence_page_id
 
             counts["update"] += 1
@@ -196,4 +195,5 @@ def apply_plan(
         "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-1.0.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
@@ -237,12 +247,6 @@ def page_publish(
     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",
@@ -316,18 +320,11 @@ def page_delete(
         from confpub.confluence import build_client
         client = build_client()
 
-        # Collect page IDs that will be deleted (for lockfile cleanup)
+        # Collect descendant IDs before deleting (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)
+                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)
@@ -336,33 +333,21 @@ def page_delete(
                 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.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 Lockfile, load_lockfile, save_lockfile, remove_from_lockfile
+        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:
-            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)
+        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
 
 

{confpub_cli-1.0.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)

{confpub_cli-1.0.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,6 +84,7 @@ 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": {
@@ -92,13 +97,36 @@ def build_guide() -> dict[str, Any]:
                 "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 "
@@ -248,6 +315,11 @@ def build_guide() -> dict[str, Any]:
                 "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-1.0.0 → confpub_cli-1.1.0}/confpub/lockfile.py

@@ -86,9 +86,12 @@ 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
 
 
@@ -101,3 +104,18 @@ def remove_from_lockfile(lockfile: Lockfile, title: str) -> bool:
         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-1.0.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-1.0.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({

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

@@ -163,6 +163,27 @@ class TestApplyLockfileFingerprints:
         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-1.0.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-1.0.0 → confpub_cli-1.1.0}/tests/test_integration.py

@@ -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"])