@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/tests/test_clients/test_confluence_cli_client.py

@@ -1,1149 +0,0 @@
-from __future__ import annotations
-
-import inspect
-from types import SimpleNamespace
-from typing import Any
-from unittest.mock import MagicMock
-
-import pytest
-import vds_audit_orchestrator.clients.confluence_cli_client as confluence_cli_module
-from vds_audit_orchestrator.clients.confluence_cli_client import ConfluenceCliClient
-from vds_audit_orchestrator.errors import DataSourceError
-
-
-@pytest.mark.asyncio
-async def test_get_page_calls_sdk(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "get_page"
-        assert context["page_id"] == "123"
-        return {"id": "123"}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.get_page(client, "123")
-    assert result == {"id": "123"}
-
-
-@pytest.mark.asyncio
-async def test_search_page_builds_cql(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "search_page"
-        assert 'space="DOC"' in context["cql"]
-        assert 'title="Home"' in context["cql"]
-        return {"results": []}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.search_page(client, "DOC", "Home")
-    assert result == {"results": []}
-
-
-@pytest.mark.asyncio
-async def test_get_child_pages_passes_expand(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "get_child_pages"
-        assert context["expand"] == "body.storage"
-        return [{"id": "88716677"}]
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.get_child_pages(client, "88716675", expand="body.storage")
-    assert result == [{"id": "88716677"}]
-
-
-@pytest.mark.asyncio
-async def test_get_child_pages_non_lightweight_defaults_to_body_storage(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "get_child_pages"
-        assert context["expand"] == "body.storage"
-        return [{"id": "88716677"}]
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.get_child_pages(client, "88716675", lightweight=False)
-    assert result == [{"id": "88716677"}]
-
-
-@pytest.mark.asyncio
-async def test_get_child_pages_marks_rate_limit_signals_from_error(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-
-    error = DataSourceError(
-        "confluence failed",
-        context={
-            "error": "HTTP 429 Too Many Requests Retry-After: 9",
-            "attempt": 1,
-            "max_attempts": 1,
-        },
-    )
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        raise error
-
-    monkeypatch.setattr(client, "_call", fake_call)
-
-    with pytest.raises(DataSourceError) as exc_info:
-        await ConfluenceCliClient.get_child_pages(client, "88716675")
-
-    context = exc_info.value.context
-    # _call already translated metadata in real execution; passthrough in this unit test.
-    assert "error" in context
-
-
-def test_registry_discovery_factory_uses_zero_retries(monkeypatch):
-    captured: dict[str, int] = {}
-    original_init = ConfluenceCliClient.__init__
-
-    def fake_init(self, *args, **kwargs):
-        captured["retries"] = int(kwargs.get("retries", -1))
-
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", fake_init)
-    ConfluenceCliClient.for_registry_discovery()
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", original_init)
-    assert captured["retries"] == 0
-
-
-@pytest.mark.asyncio
-async def test_crawl_tree_sets_cache_payload(monkeypatch, tmp_path):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "crawl_tree"
-        return {"status": "ok", "http_telemetry": {"retries_total": 3}}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.crawl_tree(
-        client,
-        "root-123",
-        tmp_path / "out",
-        cache_mode="read-write",
-        cache_ttl_hours=48,
-        incremental=False,
-    )
-
-    assert result["status"] == "ok"
-    assert result["cache"]["mode"] == "read-write"
-    assert result["cache"]["ttl_hours"] == 48
-    assert result["cache"]["incremental"] is False
-    assert result["cache"]["incremental_overlap_minutes"] == 5
-    assert result["cache"]["full_reconciliation_interval_days"] == 7
-    assert result["telemetry"]["retries_total"] == 3
-
-
-@pytest.mark.asyncio
-async def test_crawl_tree_passes_content_root_and_project_storage_key(monkeypatch, tmp_path):
-    sig = inspect.signature(ConfluenceCliClient.crawl_tree)
-    missing = [name for name in ("content_root", "project_storage_key") if name not in sig.parameters]
-    if missing:
-        pytest.xfail(f"ConfluenceCliClient.crawl_tree missing options: {', '.join(missing)}")
-
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-    content_root = tmp_path / "content-root"
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "crawl_tree"
-        assert context["content_root"] == str(content_root)
-        assert context["project_storage_key"] == "insurance-core"
-        return {"status": "ok"}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.crawl_tree(
-        client,
-        "root-123",
-        tmp_path / "out",
-        content_root=content_root,
-        project_storage_key="insurance-core",
-    )
-    assert result == {
-        "status": "ok",
-        "cache": {
-            "mode": None,
-            "ttl_hours": None,
-            "incremental": True,
-            "incremental_overlap_minutes": 5,
-            "full_reconciliation_interval_days": 7,
-            "max_nodes": None,
-            "rate_limit_budget": None,
-            "effective_resume": True,
-            "content_root": str(content_root),
-            "project_storage_key": "insurance-core",
-        },
-    }
-
-
-@pytest.mark.asyncio
-async def test_crawl_tree_does_not_force_optional_crawl_pass_through_defaults(monkeypatch, tmp_path):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-    captured_context: dict[str, object] = {}
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "crawl_tree"
-        captured_context.update(context)
-        return {"status": "ok"}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    await ConfluenceCliClient.crawl_tree(
-        client,
-        "root-123",
-        tmp_path / "out",
-    )
-
-    assert captured_context["crawl_concurrency"] is None
-    assert captured_context["staged_crawl_mode"] is None
-    assert captured_context["max_nodes"] is None
-    assert captured_context["incremental_overlap_minutes"] == 5
-    assert captured_context["full_reconciliation_interval_days"] == 7
-    assert captured_context["rate_limit_budget"] is None
-
-
-@pytest.mark.asyncio
-async def test_crawl_tree_passes_incremental_windows_to_options_and_context(monkeypatch, tmp_path):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-    client._http = object()
-    captured_context: dict[str, object] = {}
-    captured_options: dict[str, object] = {}
-
-    def fake_crawl_tree_to_disk(*, http, root_ref, output_dir, options, manifest_path):
-        captured_options["options"] = options
-        return {
-            "status": "ok",
-            "resume_state": {
-                "last_sync_timestamp": "2026-02-24T00:00:00+00:00",
-                "last_full_reconciliation_timestamp": "2026-02-18T00:00:00+00:00",
-            },
-        }
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "crawl_tree"
-        captured_context.update(context)
-        return func()
-
-    monkeypatch.setattr(
-        "vds_audit_orchestrator.clients.confluence_cli_client.crawl_tree_to_disk", fake_crawl_tree_to_disk
-    )
-    monkeypatch.setattr(client, "_call", fake_call)
-
-    result = await ConfluenceCliClient.crawl_tree(
-        client,
-        "root-123",
-        tmp_path / "out",
-        max_nodes=777,
-        incremental_overlap_minutes=17,
-        full_reconciliation_interval_days=30,
-        rate_limit_budget=22222,
-    )
-
-    assert captured_context["max_nodes"] == 777
-    assert captured_context["incremental_overlap_minutes"] == 17
-    assert captured_context["full_reconciliation_interval_days"] == 30
-    assert captured_context["rate_limit_budget"] == 22222
-    options = captured_options["options"]
-    option_params = set(inspect.signature(type(options)).parameters.keys())
-    if "max_nodes" in option_params:
-        assert options.max_nodes == 777  # type: ignore[attr-defined]
-    if "incremental_overlap_minutes" in option_params:
-        assert options.incremental_overlap_minutes == 17  # type: ignore[attr-defined]
-    if "full_reconciliation_interval_days" in option_params:
-        assert options.full_reconciliation_interval_days == 30  # type: ignore[attr-defined]
-    if "rate_limit_budget" in option_params:
-        assert options.rate_limit_budget == 22222  # type: ignore[attr-defined]
-    assert result["cache"]["max_nodes"] == 777
-    assert result["cache"]["incremental_overlap_minutes"] == 17
-    assert result["cache"]["full_reconciliation_interval_days"] == 30
-    assert result["cache"]["rate_limit_budget"] == 22222
-    assert result["resume_state"]["last_sync_timestamp"] == "2026-02-24T00:00:00+00:00"
-    assert result["resume_state"]["last_full_reconciliation_timestamp"] == "2026-02-18T00:00:00+00:00"
-
-
-# ------------------------------------------------------------------
-# G-1: delete_page
-# ------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_delete_page_calls_sdk(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "delete_page"
-        assert context["page_id"] == "456"
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.delete_page(client, "456")
-    assert result is None
-
-
-# ------------------------------------------------------------------
-# G-2: move_page
-# ------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_move_page_calls_sdk(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "move_page"
-        assert context["page_id"] == "789"
-        assert context["target_title"] == "Archive"
-        assert context["position"] == "append"
-        assert context["space_key"] is None
-        return {"status": "ok"}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.move_page(client, "789", "Archive")
-    assert result == {"status": "ok"}
-
-
-@pytest.mark.asyncio
-async def test_move_page_passes_space_key(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "move_page"
-        assert context["space_key"] == "DOC"
-        assert context["position"] == "before"
-        return {"status": "moved"}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.move_page(client, "789", "Target", position="before", space_key="DOC")
-    assert result == {"status": "moved"}
-
-
-@pytest.mark.asyncio
-async def test_move_page_returns_empty_dict_on_non_dict(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        return None
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.move_page(client, "789", "Archive")
-    assert result == {}
-
-
-# ------------------------------------------------------------------
-# G-3: add_comment
-# ------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_add_comment_calls_sdk(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "add_comment"
-        assert context["page_id"] == "100"
-        assert context["parent_id"] is None
-        return {"id": "comment-1"}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.add_comment(client, "100", "<p>Automated audit note</p>")
-    assert result == {"id": "comment-1"}
-
-
-@pytest.mark.asyncio
-async def test_add_comment_with_parent_id(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "add_comment"
-        assert context["page_id"] == "100"
-        assert context["parent_id"] == "comment-0"
-        return {"id": "comment-reply"}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.add_comment(client, "100", "<p>Reply</p>", parent_id="comment-0")
-    assert result == {"id": "comment-reply"}
-
-
-# ------------------------------------------------------------------
-# G-6: rename_page
-# ------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_rename_page_calls_sdk(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "rename_page"
-        assert context["page_id"] == "200"
-        assert context["new_title"] == "[ARCHIVED] Old Page"
-        return {"id": "200", "title": "[ARCHIVED] Old Page"}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.rename_page(client, "200", "[ARCHIVED] Old Page")
-    assert result == {"id": "200", "title": "[ARCHIVED] Old Page"}
-
-
-# ------------------------------------------------------------------
-# G-7: delete_attachment
-# ------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_delete_attachment_by_id(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "delete_attachment"
-        assert context["page_id"] == "300"
-        assert context["attachment_id"] == "att-1"
-        assert context["filename"] is None
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.delete_attachment(client, "300", "att-1")
-    assert result is None
-
-
-@pytest.mark.asyncio
-async def test_delete_attachment_by_filename(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "delete_attachment"
-        assert context["page_id"] == "300"
-        assert context["attachment_id"] is None
-        assert context["filename"] == "stale-report.xlsx"
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    result = await ConfluenceCliClient.delete_attachment(client, "300", filename="stale-report.xlsx")
-    assert result is None
-
-
-# ---------------------------------------------------------------------------
-# FR-148: probe_reachable tests
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_probe_reachable_returns_true_on_success(monkeypatch):
-    """FR-148: probe_reachable returns (True, ...) when _call succeeds."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-    client._http = MagicMock()
-    client._http.probe_reachable.return_value = {"results": [], "start": 0}
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "probe_reachable"
-        assert context == {"probe": True}
-        assert func == client._http.probe_reachable
-        return func()
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    reachable, detail = await ConfluenceCliClient.probe_reachable(client)
-    assert reachable is True
-    assert "reachable" in detail
-
-
-@pytest.mark.asyncio
-async def test_probe_reachable_returns_false_on_transport_error(monkeypatch):
-    """FR-148: probe_reachable returns (False, ...) on transport-level errors."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-    client._http = MagicMock()
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        raise TimeoutError("read timeout after 10s")
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    reachable, detail = await ConfluenceCliClient.probe_reachable(client)
-    assert reachable is False
-    assert "unreachable" in detail
-
-
-@pytest.mark.asyncio
-async def test_probe_reachable_treats_auth_error_as_reachable(monkeypatch):
-    """FR-148: probe_reachable treats 401/403 errors as reachable (server responded)."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-    client._http = MagicMock()
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        raise Exception("401 Unauthorized: invalid token")
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    reachable, detail = await ConfluenceCliClient.probe_reachable(client)
-    assert reachable is True
-    assert "reachable" in detail
-
-
-@pytest.mark.asyncio
-async def test_probe_reachable_treats_server_error_as_reachable(monkeypatch):
-    """FR-148: probe_reachable treats non-transport server errors as reachable."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-    client._http = MagicMock()
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        raise Exception("500 Internal Server Error: unexpected condition")
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    reachable, _detail = await ConfluenceCliClient.probe_reachable(client)
-    # 500 is not a transport error — server responded (degraded but reachable)
-    assert reachable is True
-
-
-@pytest.mark.asyncio
-async def test_call_probe_transport_error_logs_at_info(monkeypatch):
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-
-    debug_calls: list[str] = []
-    warning_calls: list[str] = []
-
-    fake_logger = SimpleNamespace(
-        info=lambda event, **kwargs: None,
-        debug=lambda event, **kwargs: debug_calls.append(event),
-        warning=lambda event, **kwargs: warning_calls.append(event),
-    )
-    monkeypatch.setattr(confluence_cli_module, "logger", fake_logger)
-
-    def fail() -> None:
-        raise TimeoutError("read timeout after 10s")
-
-    with pytest.raises(DataSourceError):
-        await ConfluenceCliClient._call(
-            client,
-            "probe_reachable",
-            context={"probe": True},
-            func=fail,
-        )
-
-    assert "confluence_probe_transport_unreachable" in debug_calls
-    assert "confluence_sdk_call_failed" in debug_calls
-    assert warning_calls == []
-
-
-# ---------------------------------------------------------------------------
-# FR-149: create_or_update_page (upsert) tests
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_create_or_update_page_creates_when_no_existing_page(monkeypatch, tmp_path):
-    """FR-149: When no existing page is found, create_or_update_page calls create_page."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-    client._degraded = False
-
-    body_file = tmp_path / "body.html"
-    body_file.write_text("<p>Hello</p>", encoding="utf-8")
-
-    calls: list[str] = []
-
-    async def fake_search_cql(cql, limit=25, start=0):
-        calls.append("search_cql")
-        return []
-
-    async def fake_create_page(*, space_key, title, body_file, parent_id=None):
-        calls.append("create_page")
-        assert space_key == "VDS"
-        assert title == "My Report"
-        assert parent_id == "999"
-        return {"id": "new-page-id", "title": title}
-
-    monkeypatch.setattr(client, "search_cql", fake_search_cql)
-    monkeypatch.setattr(client, "create_page", fake_create_page)
-
-    result = await ConfluenceCliClient.create_or_update_page(
-        client,
-        space_key="VDS",
-        title="My Report",
-        body_file=body_file,
-        parent_id="999",
-    )
-
-    assert result == {"id": "new-page-id", "title": "My Report"}
-    assert calls == ["search_cql", "create_page"]
-
-
-@pytest.mark.asyncio
-async def test_create_or_update_page_updates_existing_page(monkeypatch, tmp_path):
-    """FR-149: When an existing page is found by title, create_or_update_page calls update_page."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-    client._degraded = False
-
-    body_file = tmp_path / "body.html"
-    body_file.write_text("<p>Updated</p>", encoding="utf-8")
-
-    calls: list[str] = []
-
-    async def fake_search_cql(cql, limit=25, start=0):
-        calls.append("search_cql")
-        return [{"id": "existing-page-id", "title": "My Report", "version": {"number": 3}}]
-
-    async def fake_update_page(page_id, *, title=None, body_file=None, version=None):
-        calls.append("update_page")
-        assert page_id == "existing-page-id"
-        assert version == 4  # current version + 1
-        return {"id": "existing-page-id", "title": title or "My Report"}
-
-    monkeypatch.setattr(client, "search_cql", fake_search_cql)
-    monkeypatch.setattr(client, "update_page", fake_update_page)
-
-    result = await ConfluenceCliClient.create_or_update_page(
-        client,
-        space_key="VDS",
-        title="My Report",
-        body_file=body_file,
-        parent_id="999",
-    )
-
-    assert result == {"id": "existing-page-id", "title": "My Report"}
-    assert calls == ["search_cql", "update_page"]
-
-
-@pytest.mark.asyncio
-async def test_create_or_update_page_race_condition_fallback(monkeypatch, tmp_path):
-    """FR-149: When search returns empty but create_page raises 'already exists', fall back to search + update."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-    client._degraded = False
-
-    body_file = tmp_path / "body.html"
-    body_file.write_text("<p>Race</p>", encoding="utf-8")
-
-    search_call_count = 0
-
-    async def fake_search_cql(cql, limit=25, start=0):
-        nonlocal search_call_count
-        search_call_count += 1
-        if search_call_count == 1:
-            # First search: page not yet visible
-            return []
-        # Second search (fallback after race): page now visible
-        return [{"id": "race-page-id", "title": "My Report", "version": {"number": 1}}]
-
-    async def fake_create_page(*, space_key, title, body_file, parent_id=None):
-        raise DataSourceError(
-            "Confluence operation failed: create_page",
-            context={"error": "A page with this title already exists: My Report"},
-        )
-
-    update_calls: list[str] = []
-
-    async def fake_update_page(page_id, *, title=None, body_file=None, version=None):
-        update_calls.append(page_id)
-        assert page_id == "race-page-id"
-        assert version == 2  # version 1 + 1
-        return {"id": "race-page-id", "title": title or "My Report"}
-
-    monkeypatch.setattr(client, "search_cql", fake_search_cql)
-    monkeypatch.setattr(client, "create_page", fake_create_page)
-    monkeypatch.setattr(client, "update_page", fake_update_page)
-
-    result = await ConfluenceCliClient.create_or_update_page(
-        client,
-        space_key="VDS",
-        title="My Report",
-        body_file=body_file,
-        parent_id="999",
-    )
-
-    assert result == {"id": "race-page-id", "title": "My Report"}
-    assert update_calls == ["race-page-id"]
-    assert search_call_count == 2
-
-
-@pytest.mark.asyncio
-async def test_create_or_update_page_raises_when_both_create_and_fallback_fail(monkeypatch, tmp_path):
-    """FR-149: When create_page raises 'already exists' and fallback search also finds nothing, re-raise."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-    client._degraded = False
-
-    body_file = tmp_path / "body.html"
-    body_file.write_text("<p>Fail</p>", encoding="utf-8")
-
-    async def fake_search_cql(cql, limit=25, start=0):
-        return []  # Both searches return empty
-
-    async def fake_create_page(*, space_key, title, body_file, parent_id=None):
-        raise DataSourceError(
-            "Confluence operation failed: create_page",
-            context={"error": "A page with this title already exists: My Report"},
-        )
-
-    async def fake_get_child_pages(page_id, *, expand=None, lightweight=True):
-        return []  # Children lookup also finds nothing
-
-    monkeypatch.setattr(client, "search_cql", fake_search_cql)
-    monkeypatch.setattr(client, "create_page", fake_create_page)
-    monkeypatch.setattr(client, "get_child_pages", fake_get_child_pages)
-
-    with pytest.raises(DataSourceError, match="create_page"):
-        await ConfluenceCliClient.create_or_update_page(
-            client,
-            space_key="VDS",
-            title="My Report",
-            body_file=body_file,
-            parent_id="999",
-        )
-
-
-@pytest.mark.asyncio
-async def test_create_or_update_page_race_condition_children_fallback(monkeypatch, tmp_path):
-    """When CQL is eventually consistent but get_child_pages finds the page, update succeeds."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    body_file = tmp_path / "body.html"
-    body_file.write_text("<p>Children Fallback</p>", encoding="utf-8")
-
-    async def fake_search_cql(cql, limit=25, start=0):
-        return []  # CQL index lagging — always returns empty
-
-    async def fake_create_page(*, space_key, title, body_file, parent_id=None):
-        raise DataSourceError(
-            "Confluence operation failed: create_page",
-            context={"error": "A page with this title already exists: My Report"},
-        )
-
-    async def fake_get_child_pages(page_id, *, expand=None, lightweight=True):
-        # REST API (not CQL) — returns the page directly from the DB
-        return [{"id": "child-found-id", "title": "My Report"}]
-
-    update_calls: list[str] = []
-
-    async def fake_update_page(page_id, *, title=None, body_file=None, version=None):
-        update_calls.append(page_id)
-        return {"id": page_id, "title": title or "My Report"}
-
-    monkeypatch.setattr(client, "search_cql", fake_search_cql)
-    monkeypatch.setattr(client, "create_page", fake_create_page)
-    monkeypatch.setattr(client, "get_child_pages", fake_get_child_pages)
-    monkeypatch.setattr(client, "update_page", fake_update_page)
-
-    result = await ConfluenceCliClient.create_or_update_page(
-        client,
-        space_key="VDS",
-        title="My Report",
-        body_file=body_file,
-        parent_id="999",
-    )
-
-    assert result == {"id": "child-found-id", "title": "My Report"}
-    assert update_calls == ["child-found-id"]
-
-
-# ---------------------------------------------------------------------------
-# TSK-144Q.5: for_checklist_reads named constructor
-# ---------------------------------------------------------------------------
-
-
-def test_for_checklist_reads_defaults_to_internal_server(monkeypatch):
-    """P153-C: for_checklist_reads() must default to server='internal'."""
-    captured: dict[str, object] = {}
-    original_init = ConfluenceCliClient.__init__
-
-    # Ensure no env override leaks from the host environment.
-    monkeypatch.delenv("VDS_AUDIT_CHECKLIST_READ_SERVER", raising=False)
-
-    def fake_init(self, *args, **kwargs):
-        captured["server"] = kwargs.get("server")
-
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", fake_init)
-    ConfluenceCliClient.for_checklist_reads()
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", original_init)
-    assert captured["server"] == "internal"
-
-
-def test_for_checklist_reads_default_timeout_60(monkeypatch):
-    """for_checklist_reads() default timeout is 60 when no env var is set."""
-    captured: dict[str, object] = {}
-    original_init = ConfluenceCliClient.__init__
-
-    def fake_init(self, *args, **kwargs):
-        captured["timeout"] = kwargs.get("timeout")
-
-    monkeypatch.setenv("VDS_AUDIT_CHECKLIST_READ_TIMEOUT", "")
-    monkeypatch.delenv("VDS_AUDIT_CHECKLIST_READ_TIMEOUT", raising=False)
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", fake_init)
-    ConfluenceCliClient.for_checklist_reads()
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", original_init)
-    assert captured["timeout"] == 60
-
-
-def test_for_checklist_reads_env_override_timeout(monkeypatch):
-    """for_checklist_reads() reads VDS_AUDIT_CHECKLIST_READ_TIMEOUT from env."""
-    captured: dict[str, object] = {}
-    original_init = ConfluenceCliClient.__init__
-
-    def fake_init(self, *args, **kwargs):
-        captured["timeout"] = kwargs.get("timeout")
-
-    monkeypatch.setenv("VDS_AUDIT_CHECKLIST_READ_TIMEOUT", "30")
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", fake_init)
-    ConfluenceCliClient.for_checklist_reads()
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", original_init)
-    assert captured["timeout"] == 30
-
-
-def test_for_checklist_reads_explicit_timeout_override(monkeypatch):
-    """Explicit timeout= parameter overrides both default and env var."""
-    captured: dict[str, object] = {}
-    original_init = ConfluenceCliClient.__init__
-
-    def fake_init(self, *args, **kwargs):
-        captured["timeout"] = kwargs.get("timeout")
-
-    monkeypatch.setenv("VDS_AUDIT_CHECKLIST_READ_TIMEOUT", "30")
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", fake_init)
-    ConfluenceCliClient.for_checklist_reads(timeout=45)
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", original_init)
-    assert captured["timeout"] == 45
-
-
-# ---------------------------------------------------------------------------
-# update_page: new body and parent_id parameters
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_update_page_passes_parent_id_to_content_client(monkeypatch):
-    """update_page with parent_id must pass parent_id through to the underlying content client."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-
-    captured: dict[str, object] = {}
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        captured["operation"] = operation
-        captured["context"] = context
-        # Invoke func to verify it passes parent_id to _content.update_page
-        return func()
-
-    class FakeContent:
-        def update_page(
-            self,
-            page_id: str,
-            *,
-            title: str | None = None,
-            body: str | None = None,
-            version: int | None = None,
-            parent_id: str | None = None,
-            **kwargs: object,
-        ) -> dict[str, object]:
-            captured["update_page_kwargs"] = {
-                "page_id": page_id,
-                "title": title,
-                "body": body,
-                "version": version,
-                "parent_id": parent_id,
-            }
-            return {"id": page_id, "title": title}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    client._content = FakeContent()  # type: ignore[attr-defined]
-
-    result = await ConfluenceCliClient.update_page(
-        client,
-        "page-42",
-        title="Moved Page",
-        body="<p>content</p>",
-        parent_id="parent-99",
-    )
-
-    assert result == {"id": "page-42", "title": "Moved Page"}
-    assert captured["context"]["parent_id"] == "parent-99"
-    assert captured["update_page_kwargs"]["parent_id"] == "parent-99"
-    assert captured["update_page_kwargs"]["body"] == "<p>content</p>"
-
-
-@pytest.mark.asyncio
-async def test_update_page_body_string_used_when_no_body_file(monkeypatch):
-    """update_page with body string (no body_file) must pass the body string to content client."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-
-    captured: dict[str, object] = {}
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        return func()
-
-    class FakeContent:
-        def update_page(self, page_id: str, *, body: str | None = None, **kwargs: object) -> dict[str, object]:
-            captured["body"] = body
-            return {"id": page_id}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    client._content = FakeContent()  # type: ignore[attr-defined]
-
-    await ConfluenceCliClient.update_page(client, "page-1", title="T", body="<p>direct body</p>")
-
-    assert captured["body"] == "<p>direct body</p>"
-
-
-@pytest.mark.asyncio
-async def test_update_page_body_file_takes_precedence_over_body_string(monkeypatch, tmp_path):
-    """When both body and body_file are provided, body_file must take precedence."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-
-    body_file = tmp_path / "content.html"
-    body_file.write_text("<p>from file</p>", encoding="utf-8")
-
-    captured: dict[str, object] = {}
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        return func()
-
-    class FakeContent:
-        def update_page(self, page_id: str, *, body: str | None = None, **kwargs: object) -> dict[str, object]:
-            captured["body"] = body
-            return {"id": page_id}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    client._content = FakeContent()  # type: ignore[attr-defined]
-
-    await ConfluenceCliClient.update_page(
-        client,
-        "page-1",
-        title="T",
-        body="<p>ignored string</p>",
-        body_file=body_file,
-    )
-
-    assert captured["body"] == "<p>from file</p>"
-
-
-@pytest.mark.asyncio
-async def test_update_page_without_parent_id_passes_none(monkeypatch):
-    """update_page without parent_id must pass parent_id=None to content client (no move)."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 0
-    client._degraded = False
-
-    captured: dict[str, object] = {}
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        captured["context_parent_id"] = context.get("parent_id")
-        return func()
-
-    class FakeContent:
-        def update_page(self, page_id: str, *, parent_id: str | None = None, **kwargs: object) -> dict[str, object]:
-            captured["parent_id"] = parent_id
-            return {"id": page_id}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    client._content = FakeContent()  # type: ignore[attr-defined]
-
-    await ConfluenceCliClient.update_page(client, "page-1", title="T")
-
-    assert captured["parent_id"] is None
-    assert captured["context_parent_id"] is None
-
-
-# ------------------------------------------------------------------
-# Phase 153 tests — CQL start, checklist routing, distinct endpoint behavior
-# ------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_search_cql_passes_start_zero_explicitly(monkeypatch):
-    """P153-A: search_cql must forward start=0 to the underlying SDK."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    captured: dict[str, Any] = {}
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert operation == "search_cql"
-        assert context["start"] == 0
-        # Execute the lambda to verify it passes start=0 into the SDK.
-        # We mock _content.search_cql to capture the call.
-        captured["func_result"] = func()
-        return {"results": []}
-
-    class FakeContent:
-        def search_cql(self, cql: str, *, limit: int = 25, start: int = 0) -> dict[str, Any]:
-            captured["cql"] = cql
-            captured["limit"] = limit
-            captured["start"] = start
-            return {"results": []}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    client._content = FakeContent()  # type: ignore[attr-defined]
-    client._content_secondary = None  # type: ignore[attr-defined]
-
-    result = await ConfluenceCliClient.search_cql(client, "type=page", limit=5)
-    assert result == []
-    assert captured["start"] == 0
-    assert captured["limit"] == 5
-
-
-@pytest.mark.asyncio
-async def test_search_cql_with_custom_start(monkeypatch):
-    """P153-A: search_cql must forward a custom start value."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-
-    captured: dict[str, Any] = {}
-
-    async def fake_call(operation, *, context, func, secondary_func=None):
-        assert context["start"] == 5
-        captured["func_result"] = func()
-        return {"results": []}
-
-    class FakeContent:
-        def search_cql(self, cql: str, *, limit: int = 25, start: int = 0) -> dict[str, Any]:
-            captured["start"] = start
-            return {"results": []}
-
-    monkeypatch.setattr(client, "_call", fake_call)
-    client._content = FakeContent()  # type: ignore[attr-defined]
-    client._content_secondary = None  # type: ignore[attr-defined]
-
-    result = await ConfluenceCliClient.search_cql(client, "type=page", start=5)
-    assert result == []
-    assert captured["start"] == 5
-
-
-def test_for_checklist_reads_defaults_to_internal(monkeypatch):
-    """P153-C: for_checklist_reads must default to server='internal'."""
-    captured: dict[str, Any] = {}
-
-    def fake_init(self, *args: Any, **kwargs: Any) -> None:
-        captured["server"] = kwargs.get("server") or (args[1] if len(args) > 1 else None)
-        captured["timeout"] = kwargs.get("timeout")
-        captured["retries"] = kwargs.get("retries")
-
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", fake_init)
-    # Ensure no env override leaks from the host environment.
-    monkeypatch.delenv("VDS_AUDIT_CHECKLIST_READ_SERVER", raising=False)
-    monkeypatch.delenv("VDS_AUDIT_CHECKLIST_READ_TIMEOUT", raising=False)
-
-    ConfluenceCliClient.for_checklist_reads()
-    assert captured["server"] == "internal", f"Expected 'internal', got {captured['server']!r}"
-    assert captured["retries"] == 2
-
-
-def test_for_checklist_reads_env_override_to_external(monkeypatch):
-    """P153-C: for_checklist_reads must respect VDS_AUDIT_CHECKLIST_READ_SERVER env var."""
-    captured: dict[str, Any] = {}
-
-    def fake_init(self, *args: Any, **kwargs: Any) -> None:
-        captured["server"] = kwargs.get("server") or (args[1] if len(args) > 1 else None)
-
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", fake_init)
-    monkeypatch.setenv("VDS_AUDIT_CHECKLIST_READ_SERVER", "external")
-
-    ConfluenceCliClient.for_checklist_reads()
-    assert captured["server"] == "external", f"Expected 'external', got {captured['server']!r}"
-
-    monkeypatch.delenv("VDS_AUDIT_CHECKLIST_READ_SERVER", raising=False)
-
-
-def test_for_checklist_reads_explicit_parameter_overrides_env(monkeypatch):
-    """P153-C: Explicit server parameter takes precedence over env var."""
-    captured: dict[str, Any] = {}
-
-    def fake_init(self, *args: Any, **kwargs: Any) -> None:
-        captured["server"] = kwargs.get("server") or (args[1] if len(args) > 1 else None)
-
-    monkeypatch.setattr(ConfluenceCliClient, "__init__", fake_init)
-    monkeypatch.setenv("VDS_AUDIT_CHECKLIST_READ_SERVER", "external")
-
-    ConfluenceCliClient.for_checklist_reads(server="internal")
-    assert captured["server"] == "internal", f"Expected 'internal', got {captured['server']!r}"
-
-    monkeypatch.delenv("VDS_AUDIT_CHECKLIST_READ_SERVER", raising=False)
-
-
-@pytest.mark.asyncio
-async def test_transport_error_marks_degraded_without_url_failover():
-    """P153-D: transport failures degrade the selected base URL without failover."""
-    client = ConfluenceCliClient.__new__(ConfluenceCliClient)
-    client._retries = 3
-    client._content_secondary = None
-    client._degraded = False
-    client._timeout = 10
-
-    def failing_primary() -> Any:
-        raise ConnectionError("primary unreachable")
-
-    with pytest.raises(DataSourceError):
-        await client._call("test_no_failover", context={"test": True}, func=failing_primary)
-
-    assert client._degraded is True