@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/clients/confluence_cli_client.py

@@ -1,977 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import inspect
-import os
-import re
-from datetime import datetime
-from pathlib import Path
-from time import perf_counter
-from typing import Any
-
-from confluence_orchestrator.content import ContentClient
-from confluence_orchestrator.crawl_tree import CrawlOptions, crawl_tree_to_disk
-from vds_audit_orchestrator.errors import DataSourceError
-from vds_audit_orchestrator.logging_config import get_logger
-
-from confluence_orchestrator import ConfluenceClient, load_settings
-
-logger = get_logger(__name__)
-
-
-class ConfluenceCliClient:
-    """Confluence adapter backed by confluence_orchestrator SDK (no subprocess).
-
-    FR-148: Mid-execution degraded mode support. When the selected Confluence
-    base URL fails with a transport-level error, ``_call`` sets
-    ``self._degraded = True`` and logs ``confluence_transport_unreachable``.
-    Callers can check ``client.is_degraded`` to skip later upload phases or add
-    degradation warnings to reports. ``mark_degraded()`` lets external code
-    force the flag (e.g. after an explicit startup connectivity check).
-    """
-
-    REGISTRY_DISCOVERY_RETRIES = 0
-
-    def __init__(
-        self,
-        project_path: Path | None = None,
-        *,
-        server: str | None = None,
-        timeout: int = 120,
-        retries: int = 3,
-    ):
-        self._project_path = project_path
-        self._server = server
-        self._timeout = timeout
-        self._retries = retries
-        # FR-148 mid-execution degraded mode: set to True when the selected
-        # base URL fails with a transport error, or when mark_degraded() is
-        # called explicitly.
-        self._degraded: bool = False
-
-        settings = load_settings(strict=True)
-        self._http = ConfluenceClient(settings, server=server, timeout=timeout)
-        self._content = ContentClient(self._http)
-
-    @classmethod
-    def for_registry_discovery(
-        cls,
-        project_path: Path | None = None,
-        *,
-        server: str | None = None,
-        timeout: int = 120,
-    ) -> ConfluenceCliClient:
-        """Factory for parse-registry path where parser-level retry owns backoff."""
-        return cls(project_path=project_path, server=server, timeout=timeout, retries=cls.REGISTRY_DISCOVERY_RETRIES)
-
-    @classmethod
-    def for_checklist_reads(
-        cls,
-        project_path: Path | None = None,
-        *,
-        timeout: int | None = None,
-        server: str | None = None,
-    ) -> ConfluenceCliClient:
-        """Factory for read-heavy checklist and knowledge page fetches.
-
-        Phase 153: Routes to the internal server by default since that is
-        where the checklist pages live.  The external server has different
-        permissions and cannot access internal-only pages.  Override with
-        ``VDS_AUDIT_CHECKLIST_READ_SERVER=external`` or the ``server``
-        parameter if external routing is needed.
-        """
-        effective_timeout = timeout or int(os.environ.get("VDS_AUDIT_CHECKLIST_READ_TIMEOUT", "60"))
-        effective_server = server or os.environ.get("VDS_AUDIT_CHECKLIST_READ_SERVER", "internal")
-        logger.info(
-            "confluence_checklist_read_server_selected",
-            server=effective_server,
-            source="parameter"
-            if server
-            else ("env" if os.environ.get("VDS_AUDIT_CHECKLIST_READ_SERVER") else "default"),
-        )
-        return cls(
-            project_path=project_path,
-            server=effective_server,
-            timeout=effective_timeout,
-            retries=2,
-        )
-
-    # ------------------------------------------------------------------
-    # FR-148: Degraded mode API
-    # ------------------------------------------------------------------
-
-    @property
-    def is_degraded(self) -> bool:
-        """True when the selected Confluence base URL failed with transport errors.
-
-        Once set, callers should skip upload phases and add degradation warnings
-        to reports rather than retrying individual page operations implicitly
-        against a different configured URL.
-        """
-        return self._degraded
-
-    def mark_degraded(self, *, reason: str = "manually_marked") -> None:
-        """Force the client into degraded mode.
-
-        Used by startup health checks (``_auto_activate_offline_mode``) so that
-        a client pre-created for uploads can be marked before any page operation
-        is attempted, avoiding 120 s timeouts on each upload page.
-        """
-        if not self._degraded:
-            self._degraded = True
-            logger.warning(
-                "confluence_client_marked_degraded",
-                reason=reason,
-            )
-
-    async def probe_reachable(self) -> tuple[bool, str]:
-        """Lightweight connectivity probe using the existing SDK client infrastructure.
-
-        FR-148/FR-162: Used by ``collect_confluence_connectivity_payload`` at workflow startup to
-        auto-detect Confluence unavailability before the evaluation pipeline begins.
-
-        Calls the SDK's dedicated ``probe_reachable()`` helper, which uses the
-        same REST search path as normal CQL reads while preserving explicit
-        ``start=0`` semantics. Auth failures (401/403) count as *reachable*
-        because the server responded. Transport-level errors (timeouts,
-        connection refused) count as *unreachable*.
-
-        Returns:
-            ``(reachable, detail)`` — reachable is True when the server is up,
-            detail is a short human-readable string explaining the outcome.
-        """
-        try:
-            await self._call(
-                "probe_reachable",
-                context={"probe": True},
-                func=self._http.probe_reachable,
-            )
-            return True, "reachable (probe succeeded)"
-        except Exception as exc:
-            exc_str = str(exc)
-            # Auth failures (401/403) mean the server IS up but credentials are wrong —
-            # treat as reachable so we don't suppress evaluation due to a config issue.
-            if any(code in exc_str for code in ("401", "403", "Unauthorized", "Forbidden")):
-                return True, f"reachable (auth error: {exc_str[:120]})"
-            if self._is_transport_error(exc):
-                return False, f"unreachable (transport error): {exc_str[:200]}"
-            # 404, 500, etc. — server responded, so it's technically reachable.
-            return True, f"reachable (server error): {exc_str[:120]}"
-
-    @staticmethod
-    def _extract_rate_limit_metadata(exc: DataSourceError) -> dict[str, Any]:
-        """Extract explicit 429 / Retry-After signals from error context and message."""
-        context = exc.context if isinstance(exc.context, dict) else {}
-        fragments = [str(exc), str(context.get("error") or "")]
-        blob = "\n".join(fragments)
-        blob_lower = blob.lower()
-        rate_limited = "429" in blob_lower or "retry-after" in blob_lower or "rate limit" in blob_lower
-
-        retry_after_seconds: int | None = None
-        retry_after_match = re.search(r"retry[- ]after\s*[:=]?\s*(\d+)", blob_lower)
-        if retry_after_match:
-            retry_after_seconds = int(retry_after_match.group(1))
-
-        return {
-            "rate_limited": rate_limited,
-            "retry_after_seconds": retry_after_seconds,
-        }
-
-    @staticmethod
-    def _is_transport_error(exc: Exception) -> bool:
-        """Return True for connection/timeout errors on the selected base URL."""
-        error_str = str(exc).lower()
-        if any(code in error_str for code in ("401", "403", "unauthorized", "forbidden")):
-            return False
-        if isinstance(exc, (ConnectionError, TimeoutError)):
-            return True
-        if isinstance(exc, OSError) and not isinstance(exc, PermissionError):
-            return True
-        transport_keywords = ("timed out", "timeout", "connection", "read timeout", "connect error", "network")
-        return any(kw in error_str for kw in transport_keywords)
-
-    async def _call(
-        self,
-        operation: str,
-        *,
-        context: dict[str, Any] | None,
-        func: Any,
-    ) -> Any:
-        started = perf_counter()
-        is_probe = bool((context or {}).get("probe"))
-        try:
-            payload = await asyncio.to_thread(func)
-            elapsed_ms = int((perf_counter() - started) * 1000)
-            log_success = logger.debug if is_probe else logger.info
-            log_success(
-                "confluence_sdk_call_completed",
-                operation=operation,
-                elapsed_ms=elapsed_ms,
-                retries_configured=self._retries,
-                attempt=1,
-                max_attempts=self._retries + 1,
-            )
-            return payload
-        except Exception as raw_exc:
-            elapsed_ms = int((perf_counter() - started) * 1000)
-            exc = DataSourceError(
-                f"Confluence operation failed: {operation}",
-                context={"operation": operation, **(context or {}), "error": str(raw_exc)},
-            )
-            rate_limit = self._extract_rate_limit_metadata(exc)
-            if rate_limit["rate_limited"]:
-                exc.context["rate_limited"] = True
-            if rate_limit["retry_after_seconds"] is not None:
-                exc.context["retry_after_seconds"] = rate_limit["retry_after_seconds"]
-
-            # FR-148: Mark the client as degraded when the selected base URL
-            # fails due to a transport error. Auth failures (401/403), 404 Not
-            # Found, and other non-transport errors are NOT marked degraded —
-            # those represent correct server responses that the caller should
-            # handle explicitly. We intentionally do not fail over to another
-            # configured URL: each base URL is treated as its own distinct
-            # Confluence surface.
-            if self._is_transport_error(raw_exc) and not self._degraded:
-                self._degraded = True
-                log_fn = logger.debug if is_probe else logger.warning
-                event_name = (
-                    "confluence_probe_transport_unreachable" if is_probe else "confluence_transport_unreachable"
-                )
-                log_fn(
-                    event_name,
-                    operation=operation,
-                    error=str(raw_exc),
-                    degraded=True,
-                    note=(
-                        "Selected Confluence base URL failed with a transport error. "
-                        "Client is now in degraded mode — subsequent upload phases "
-                        "will be skipped and a degradation warning will be added to the report."
-                    ),
-                )
-
-            log_fn = logger.debug if is_probe else logger.warning
-            log_fn(
-                "confluence_sdk_call_failed",
-                operation=operation,
-                elapsed_ms=elapsed_ms,
-                retries_configured=self._retries,
-                attempt=1,
-                max_attempts=self._retries + 1,
-                rate_limited=bool(rate_limit["rate_limited"]),
-                retry_after_seconds=rate_limit["retry_after_seconds"],
-                error=str(raw_exc),
-                probe=is_probe,
-            )
-            raise exc from raw_exc
-
-    async def get_page(self, page_id: str, *, expand: str | None = None) -> dict[str, Any] | None:
-        expand_list = [token.strip() for token in (expand or "").split(",") if token.strip()]
-        payload = await self._call(
-            "get_page",
-            context={"page_id": page_id, "expand": expand},
-            func=lambda: self._content.get_page(page_id, expand=expand_list or None),
-        )
-        return payload if isinstance(payload, dict) else None
-
-    async def get_page_history(self, page_id: str) -> dict[str, Any] | None:
-        payload = await self._call(
-            "get_page_history",
-            context={"page_id": page_id},
-            func=lambda: self._http.get_page_history(page_id),
-        )
-        if not isinstance(payload, dict):
-            return None
-        history = payload.get("history")
-        return history if isinstance(history, dict) else payload
-
-    async def list_child_pages(self, page_id: str) -> list[dict[str, Any]]:
-        payload = await self._call(
-            "list_child_pages",
-            context={"page_id": page_id},
-            func=lambda: self._http.get_child_pages(page_id),
-        )
-        if isinstance(payload, list):
-            return [x for x in payload if isinstance(x, dict)]
-        if isinstance(payload, dict):
-            results = payload.get("results") or payload.get("pages") or payload.get("children")
-            if isinstance(results, list):
-                return [x for x in results if isinstance(x, dict)]
-        return []
-
-    async def list_attachments(self, page_id: str) -> list[dict[str, Any]]:
-        payload = await self._call(
-            "list_attachments",
-            context={"page_id": page_id},
-            func=lambda: self._content.list_attachments(page_id),
-        )
-        if isinstance(payload, dict):
-            results = payload.get("results") or payload.get("attachments") or []
-            return [x for x in results if isinstance(x, dict)]
-        return []
-
-    async def download_attachment(
-        self, attachment_id: str, output_path: str | Path, *, filename: str | None = None
-    ) -> Path:
-        payload = await self._call(
-            "download_attachment",
-            context={"attachment_id": attachment_id, "output_path": str(output_path), "filename": filename},
-            func=lambda: self._content.download_attachment(attachment_id, output_path, filename=filename),
-        )
-        if isinstance(payload, Path):
-            return payload
-        return Path(output_path)
-
-    async def crawl_tree(
-        self,
-        root_ref: str,
-        output_dir: Path,
-        *,
-        depth: int = 3,
-        max_nodes: int | None = None,
-        include_attachments: bool = True,
-        emit_corpus: bool = False,
-        emit_link_graph: bool = False,
-        emit_tables: bool = False,
-        emit_mentions: bool = False,
-        body_format: str | None = None,
-        chunk_max_chars: int | None = None,
-        cache_mode: str | None = None,
-        cache_ttl_hours: int | None = None,
-        crawl_concurrency: int | None = None,
-        staged_crawl_mode: str | None = None,
-        incremental: bool = True,
-        incremental_overlap_minutes: int = 5,
-        full_reconciliation_interval_days: int = 7,
-        rate_limit_budget: int | None = None,
-        content_root: Path | None = None,
-        project_storage_key: str | None = None,
-        manifest_path: Path | None = None,
-    ) -> dict[str, Any]:
-        resolved_body = (body_format or "view").strip().lower().replace("-", "_")
-        resolved_staged_raw = (staged_crawl_mode or "").strip()
-        resolved_staged = resolved_staged_raw.lower().replace("-", "_") if resolved_staged_raw else None
-        options_kwargs: dict[str, Any] = {
-            "max_depth": depth,
-            "include_attachments": include_attachments,
-            "emit_corpus": emit_corpus,
-            "emit_link_graph": emit_link_graph,
-            "emit_tables": emit_tables,
-            "emit_mentions": emit_mentions,
-            "body_format": resolved_body,
-            "chunk_max_chars": chunk_max_chars,
-            "resume": incremental,
-        }
-        option_params = set(inspect.signature(CrawlOptions).parameters.keys())
-        if max_nodes is not None and "max_nodes" in option_params:
-            options_kwargs["max_nodes"] = int(max_nodes)
-        if resolved_staged is not None and "staged_mode" in option_params:
-            options_kwargs["staged_mode"] = resolved_staged
-        elif resolved_staged is not None and "staged_crawl_mode" in option_params:
-            options_kwargs["staged_crawl_mode"] = resolved_staged
-        if crawl_concurrency is not None and "page_concurrency" in option_params:
-            options_kwargs["page_concurrency"] = int(crawl_concurrency)
-        elif crawl_concurrency is not None and "crawl_concurrency" in option_params:
-            options_kwargs["crawl_concurrency"] = int(crawl_concurrency)
-        if "incremental_cql" in option_params:
-            options_kwargs["incremental_cql"] = bool(incremental)
-        if "incremental_overlap_minutes" in option_params:
-            options_kwargs["incremental_overlap_minutes"] = int(incremental_overlap_minutes)
-        if "full_reconciliation_interval_days" in option_params:
-            options_kwargs["full_reconciliation_interval_days"] = int(full_reconciliation_interval_days)
-        if rate_limit_budget is not None and "rate_limit_budget" in option_params:
-            options_kwargs["rate_limit_budget"] = int(rate_limit_budget)
-
-        payload = await self._call(
-            "crawl_tree",
-            context={
-                "root_ref": root_ref,
-                "output_dir": str(output_dir),
-                "depth": depth,
-                "max_nodes": max_nodes,
-                "include_attachments": include_attachments,
-                "emit_corpus": emit_corpus,
-                "emit_link_graph": emit_link_graph,
-                "emit_tables": emit_tables,
-                "emit_mentions": emit_mentions,
-                "body_format": resolved_body,
-                "chunk_max_chars": chunk_max_chars,
-                "cache_mode": cache_mode,
-                "cache_ttl_hours": cache_ttl_hours,
-                "crawl_concurrency": crawl_concurrency,
-                "staged_crawl_mode": resolved_staged,
-                "incremental": incremental,
-                "incremental_overlap_minutes": incremental_overlap_minutes,
-                "full_reconciliation_interval_days": full_reconciliation_interval_days,
-                "rate_limit_budget": rate_limit_budget,
-                "content_root": str(content_root) if content_root is not None else None,
-                "project_storage_key": project_storage_key,
-            },
-            func=lambda: crawl_tree_to_disk(
-                http=self._http,
-                root_ref=root_ref,
-                output_dir=output_dir,
-                options=CrawlOptions(**options_kwargs),
-                manifest_path=manifest_path,
-            ),
-        )
-        if not isinstance(payload, dict):
-            return {}
-        payload["cache"] = {
-            "mode": cache_mode,
-            "ttl_hours": cache_ttl_hours,
-            "incremental": incremental,
-            "incremental_overlap_minutes": int(incremental_overlap_minutes),
-            "full_reconciliation_interval_days": int(full_reconciliation_interval_days),
-            "max_nodes": max_nodes,
-            "rate_limit_budget": rate_limit_budget,
-            "effective_resume": incremental,
-            "content_root": str(content_root) if content_root else None,
-            "project_storage_key": project_storage_key,
-        }
-        if isinstance(payload.get("http_telemetry"), dict) and not isinstance(payload.get("telemetry"), dict):
-            payload["telemetry"] = payload["http_telemetry"]
-        return payload
-
-    async def get_content_page(self, page_id: str, *, expand: str | None = None) -> dict[str, Any] | None:
-        return await self.get_page(page_id, expand=expand)
-
-    async def create_page(
-        self,
-        *,
-        space_key: str,
-        title: str,
-        body_file: Path,
-        parent_id: str | None = None,
-    ) -> dict[str, Any]:
-        body = body_file.read_text(encoding="utf-8")
-        payload = await self._call(
-            "create_page",
-            context={"space_key": space_key, "title": title, "parent_id": parent_id},
-            func=lambda: self._content.create_page(space_key=space_key, title=title, body=body, parent_id=parent_id),
-        )
-        return payload if isinstance(payload, dict) else {}
-
-    async def update_page(
-        self,
-        page_id: str,
-        *,
-        title: str | None = None,
-        body: str | None = None,
-        body_file: Path | None = None,
-        version: int | None = None,
-        parent_id: str | None = None,
-    ) -> dict[str, Any]:
-        """Update an existing Confluence page.
-
-        Args:
-            page_id: ID of the page to update.
-            title: New title for the page (optional).
-            body: Body content string (optional). Ignored when ``body_file`` is
-                also provided — ``body_file`` takes precedence.
-            body_file: Path to a file whose text content is used as the body.
-                Takes precedence over ``body`` when both are provided.
-            version: Target version number. When omitted the underlying SDK
-                fetches the current version automatically.
-            parent_id: ID of the new parent page. Pass to move the page to a
-                different location in the page hierarchy.
-        """
-        resolved_body = body_file.read_text(encoding="utf-8") if body_file else body
-        payload = await self._call(
-            "update_page",
-            context={"page_id": page_id, "title": title, "version": version, "parent_id": parent_id},
-            func=lambda: self._content.update_page(
-                page_id,
-                title=title,
-                body=resolved_body,
-                version=version,
-                parent_id=parent_id,
-            ),
-        )
-        return payload if isinstance(payload, dict) else {}
-
-    async def create_or_update_page(
-        self,
-        *,
-        space_key: str,
-        title: str,
-        body_file: Path,
-        parent_id: str | None = None,
-    ) -> dict[str, Any]:
-        """Create a page or update it if one with the same title already exists.
-
-        FR-149: Upsert logic — search for an existing page by title under the
-        same parent before attempting creation.  If found, update in place.
-        If create_page raises a "page already exists" error (race condition),
-        fall back to search + update so no call-site ever needs to handle
-        duplicate-title errors for publication paths.
-
-        Returns:
-            Page dict with at least an ``"id"`` key from Confluence.
-        """
-        # 1. Check for existing page under the same parent (or space-wide if no parent).
-        try:
-            if parent_id:
-                cql = f'parent={parent_id} and title="{title}" and type=page'
-            else:
-                cql = f'space="{space_key}" and title="{title}" and type=page'
-            results = await self.search_cql(cql, limit=1)
-            if results and results[0].get("id"):
-                existing = results[0]
-                page_id = str(existing["id"])
-                version_num = None
-                version_info = existing.get("version")
-                if isinstance(version_info, dict):
-                    raw = version_info.get("number")
-                    if isinstance(raw, int):
-                        version_num = raw + 1
-                logger.info(
-                    "confluence_create_or_update_page_updating_existing",
-                    title=title,
-                    page_id=page_id,
-                    version=version_num,
-                )
-                return await self.update_page(
-                    page_id,
-                    title=title,
-                    body_file=body_file,
-                    version=version_num,
-                )
-        except DataSourceError:
-            # Search failed — fall through to create; create will also raise if
-            # the page truly cannot be created.
-            pass
-
-        # 2. No existing page found — attempt to create.
-        try:
-            return await self.create_page(
-                space_key=space_key,
-                title=title,
-                body_file=body_file,
-                parent_id=parent_id,
-            )
-        except DataSourceError as exc:
-            msg = str(exc).lower()
-            if "already exists" not in msg:
-                raise
-            # Race condition: page was created between search and create.
-            # Fall back to search + update.
-            logger.warning(
-                "confluence_create_or_update_page_race_condition_fallback",
-                title=title,
-                space_key=space_key,
-                parent_id=parent_id,
-                error=str(exc),
-            )
-            # Try CQL search first (may fail due to eventual consistency).
-            if parent_id:
-                cql = f'parent={parent_id} and title="{title}" and type=page'
-            else:
-                cql = f'space="{space_key}" and title="{title}" and type=page'
-            results = await self.search_cql(cql, limit=1)
-            if results and results[0].get("id"):
-                existing = results[0]
-                page_id = str(existing["id"])
-                version_num = None
-                version_info = existing.get("version")
-                if isinstance(version_info, dict):
-                    raw = version_info.get("number")
-                    if isinstance(raw, int):
-                        version_num = raw + 1
-                return await self.update_page(
-                    page_id,
-                    title=title,
-                    body_file=body_file,
-                    version=version_num,
-                )
-
-            # CQL index is eventually consistent — the page exists (create_page
-            # confirmed it) but CQL cannot find it yet.  Fall back to the REST
-            # ``get_child_pages`` endpoint which reads directly from the DB.
-            if parent_id:
-                try:
-                    children = await self.get_child_pages(parent_id)
-                    for child in children:
-                        if child.get("title") == title and child.get("id"):
-                            child_id = str(child["id"])
-                            logger.info(
-                                "confluence_create_or_update_page_found_via_children",
-                                title=title,
-                                page_id=child_id,
-                                parent_id=parent_id,
-                            )
-                            return await self.update_page(
-                                child_id,
-                                title=title,
-                                body_file=body_file,
-                            )
-                except DataSourceError:
-                    pass  # Children lookup also failed; re-raise original error.
-
-            raise
-
-    async def upload_attachment(
-        self,
-        *,
-        page_id: str,
-        file_path: Path,
-    ) -> dict[str, Any]:
-        payload = await self._call(
-            "upload_attachment",
-            context={"page_id": page_id, "file_path": str(file_path)},
-            func=lambda: self._content.upload_attachment(page_id, file_path),
-        )
-        return payload if isinstance(payload, dict) else {}
-
-    async def update_attachment(
-        self,
-        *,
-        page_id: str,
-        attachment_id: str,
-        file_path: Path,
-    ) -> dict[str, Any]:
-        payload = await self._call(
-            "update_attachment",
-            context={"page_id": page_id, "attachment_id": attachment_id, "file_path": str(file_path)},
-            func=lambda: self._content.update_attachment(page_id, attachment_id, file_path),
-        )
-        return payload if isinstance(payload, dict) else {}
-
-    async def search_page(self, space: str, title: str) -> dict[str, Any]:
-        cql = f'space="{space}" and title="{title}" and type=page'
-        payload = await self._call(
-            "search_page",
-            context={"space": space, "title": title, "cql": cql},
-            func=lambda: self._content.search_cql(cql, limit=1),
-        )
-        return payload if isinstance(payload, dict) else {}
-
-    async def search_cql(self, cql: str, limit: int = 25, start: int = 0) -> list[dict[str, Any]]:
-        payload = await self._call(
-            "search_cql",
-            context={"cql": cql, "limit": limit, "start": start},
-            func=lambda: self._content.search_cql(cql, limit=limit, start=start),
-        )
-        if not isinstance(payload, dict):
-            return []
-        results = payload.get("results", [])
-        normalized: list[dict[str, Any]] = []
-        for entry in results:
-            if isinstance(entry, dict):
-                content = entry.get("content")
-                if isinstance(content, dict):
-                    normalized.append(content)
-                else:
-                    normalized.append(entry)
-        return normalized
-
-    async def get_child_pages(
-        self,
-        page_id: str,
-        *,
-        expand: str | None = None,
-        lightweight: bool = True,
-    ) -> list[dict[str, Any]]:
-        resolved_expand = expand
-        if not lightweight and resolved_expand is None:
-            resolved_expand = "body.storage"
-
-        expand_list = [token.strip() for token in (resolved_expand or "").split(",") if token.strip()]
-        payload = await self._call(
-            "get_child_pages",
-            context={"page_id": page_id, "expand": resolved_expand, "lightweight": lightweight},
-            func=lambda: self._content.get_child_pages(page_id, expand=expand_list or None),
-        )
-        if isinstance(payload, list):
-            return payload
-        return []
-
-    # ------------------------------------------------------------------
-    # G-1: Delete page
-    # ------------------------------------------------------------------
-
-    async def delete_page(self, page_id: str) -> None:
-        """Delete (trash) a Confluence page."""
-        await self._call(
-            "delete_page",
-            context={"page_id": page_id},
-            func=lambda: self._content.delete_page(page_id),
-        )
-
-    # ------------------------------------------------------------------
-    # G-2: Move page
-    # ------------------------------------------------------------------
-
-    async def move_page(
-        self,
-        page_id: str,
-        target_title: str,
-        position: str = "append",
-        *,
-        space_key: str | None = None,
-    ) -> dict[str, Any]:
-        """Move a page to a new location under the target page."""
-        payload = await self._call(
-            "move_page",
-            context={"page_id": page_id, "target_title": target_title, "position": position, "space_key": space_key},
-            func=lambda: self._content.move_page(page_id, target_title, position=position, space_key=space_key),
-        )
-        return payload if isinstance(payload, dict) else {}
-
-    async def move_page_to_parent(self, page_id: str, new_parent_id: str) -> dict[str, Any]:
-        """Move a page under a new parent by updating its ancestors.
-
-        Phase 156: Uses the update_page endpoint with ``parent_id`` to reparent
-        a page in the Confluence hierarchy without changing its title or body.
-        Fetches the current page version to construct the required version
-        increment.
-        """
-        page = await self.get_page(page_id, expand="version")
-        title: str | None = None
-        version: int | None = None
-        if isinstance(page, dict):
-            title = page.get("title")
-            version_info = page.get("version")
-            if isinstance(version_info, dict):
-                number = version_info.get("number")
-                if isinstance(number, int):
-                    version = number + 1
-        return await self.update_page(
-            page_id,
-            title=title,
-            parent_id=new_parent_id,
-            version=version,
-        )
-
-    # ------------------------------------------------------------------
-    # G-3: Add comment
-    # ------------------------------------------------------------------
-
-    async def add_comment(
-        self,
-        page_id: str,
-        body: str,
-        *,
-        parent_id: str | None = None,
-    ) -> dict[str, Any]:
-        """Add a storage-format comment to a page."""
-        payload = await self._call(
-            "add_comment",
-            context={"page_id": page_id, "parent_id": parent_id},
-            func=lambda: self._content.add_comment(page_id, body, parent_id=parent_id),
-        )
-        return payload if isinstance(payload, dict) else {}
-
-    # ------------------------------------------------------------------
-    # G-6: Rename page (title-only update)
-    # ------------------------------------------------------------------
-
-    async def rename_page(self, page_id: str, new_title: str) -> dict[str, Any]:
-        """Rename a page by updating only its title."""
-        payload = await self._call(
-            "rename_page",
-            context={"page_id": page_id, "new_title": new_title},
-            func=lambda: self._content.update_page(page_id, title=new_title),
-        )
-        return payload if isinstance(payload, dict) else {}
-
-    # ------------------------------------------------------------------
-    # Phase 126: Conditional GET Support (TSK-126.7)
-    # ------------------------------------------------------------------
-
-    async def get_page_conditional(
-        self,
-        page_id: str,
-        *,
-        etag: str | None = None,
-        last_modified: datetime | None = None,
-        cached_version: int | str | None = None,
-        expand: str | None = None,
-    ) -> tuple[bool, dict[str, Any] | None]:
-        """Conditional GET using ETag/If-Modified-Since or version comparison.
-
-        Attempts to avoid fetching full page content when the cached version
-        is still current. Supports multiple conditional strategies:
-
-        1. ETag/If-Modified-Since: If the underlying SDK supports these headers,
-           the API will return 304 Not Modified when content hasn't changed.
-
-        2. Version comparison: Fetches only version metadata and compares
-           against the cached version number to determine if content changed.
-
-        **Limitation**: The atlassian-python-api library used by
-        confluence_orchestrator does not expose direct ETag/If-Modified-Since
-        header support. This implementation falls back to version comparison,
-        which still provides conditional fetching behavior with minimal
-        bandwidth usage (only version metadata is fetched).
-
-        Args:
-            page_id: Confluence page ID
-            etag: ETag from cached response (currently unused due to SDK limitation)
-            last_modified: Last-Modified timestamp from cached response
-                (currently unused due to SDK limitation)
-            cached_version: Cached version number for comparison
-            expand: Comma-separated list of expansions to include
-
-        Returns:
-            Tuple of (modified, data):
-            - modified: True if page was modified (or cache invalid), False if unchanged
-            - data: Page data dict if modified=True, None if modified=False
-
-        Example:
-            >>> client = ConfluenceCliClient()
-            >>> changed, page = await client.get_page_conditional("88718940", cached_version="15")
-            >>> if not changed:
-            ...     print("Page unchanged - using cache")
-            >>> else:
-            ...     print(f"Page updated to version {page['version']['number']}")
-        """
-        # Use version comparison as the primary conditional strategy
-        # since ETag/If-Modified-Since headers are not exposed by the SDK
-        if cached_version is not None:
-            # Fetch only version metadata for lightweight comparison
-            version_page = await self.get_page(str(page_id), expand="version")
-
-            if isinstance(version_page, dict):
-                current_version = version_page.get("version", {}).get("number")
-
-                # Normalize comparison
-                cached_int: int | None = None
-                if isinstance(cached_version, int):
-                    cached_int = cached_version
-                elif isinstance(cached_version, str) and cached_version.isdigit():
-                    cached_int = int(cached_version)
-
-                current_int: int | None = None
-                if isinstance(current_version, int):
-                    current_int = current_version
-                elif isinstance(current_version, str) and current_version.isdigit():
-                    current_int = int(current_version)
-
-                # Version match - content unchanged
-                if current_int is not None and cached_int is not None and current_int == cached_int:
-                    logger.debug(
-                        "confluence_conditional_get_not_modified",
-                        page_id=page_id,
-                        cached_version=cached_int,
-                        current_version=current_int,
-                    )
-                    return False, None
-
-            # Version mismatch or fetch failed - need full content
-            # If expand was requested, fetch full content
-            if expand:
-                full_page = await self.get_page(str(page_id), expand=expand)
-                return True, full_page if isinstance(full_page, dict) else None
-
-            # Return version_page as the data (already has basic info)
-            return True, version_page if isinstance(version_page, dict) else None
-
-        # No cached version - fetch full content
-        if expand:
-            page = await self.get_page(str(page_id), expand=expand)
-        else:
-            page = await self.get_page(str(page_id))
-
-        return True, page if isinstance(page, dict) else None
-
-    # ------------------------------------------------------------------
-    # G-7: Delete attachment
-    # ------------------------------------------------------------------
-
-    async def delete_attachment(
-        self,
-        page_id: str,
-        attachment_id: str | None = None,
-        *,
-        filename: str | None = None,
-    ) -> None:
-        """Delete an attachment by ID or filename."""
-        await self._call(
-            "delete_attachment",
-            context={"page_id": page_id, "attachment_id": attachment_id, "filename": filename},
-            func=lambda: self._content.delete_attachment(page_id, attachment_id, filename=filename),
-        )
-
-    # ------------------------------------------------------------------
-    # G-8: Resolve Confluence short URLs (/x/<tinyId>)
-    # ------------------------------------------------------------------
-
-    async def resolve_tiny_url(self, tiny_id: str) -> str | None:
-        """Resolve a Confluence short URL (/x/<tinyId>) to a numeric page ID.
-
-        Confluence short URLs redirect to the full page URL which contains the
-        pageId in the query string.  We follow the redirect with a HEAD request
-        (no body transferred) and extract the pageId from the Location header or
-        the final URL.
-
-        Returns the numeric page ID string, or None if resolution fails.
-        """
-        from urllib.parse import parse_qs, urlparse
-
-        import httpx
-
-        settings = load_settings(strict=False)
-        server = self._server or "internal"
-        try:
-            base_url = str(settings.url_for(server)).rstrip("/")
-        except Exception:
-            base_url = "http://confluence.digital.vn"
-
-        token = settings.token_for(server)
-        headers: dict[str, str] = {"Accept": "text/html,application/xhtml+xml"}
-        if token:
-            headers["Authorization"] = f"Bearer {token}"
-
-        short_url = f"{base_url}/x/{tiny_id}"
-
-        def _do_resolve() -> str | None:
-            try:
-                # TODO: route through SDK's _call() once it supports redirect-following HEAD
-                # requests. For now we construct a raw httpx.Client but auth credentials
-                # are sourced from the SDK settings (base_url + token above) so the SDK
-                # auth mechanism is still respected.
-                with httpx.Client(
-                    follow_redirects=True,
-                    timeout=15,
-                    headers=headers,
-                ) as client:
-                    response = client.head(short_url)
-                    final_url = str(response.url)
-            except Exception as exc:
-                logger.debug(
-                    "confluence_tiny_url_resolution_failed",
-                    tiny_id=tiny_id,
-                    short_url=short_url,
-                    error=str(exc),
-                )
-                return None
-
-            # Extract pageId from final URL query string
-            try:
-                parsed = urlparse(final_url)
-                qs = parse_qs(parsed.query)
-                for key in ("pageId", "pageid", "pageID"):
-                    values = qs.get(key, [])
-                    for value in values:
-                        candidate = str(value or "").strip()
-                        if candidate.isdigit():
-                            logger.debug(
-                                "confluence_tiny_url_resolved",
-                                tiny_id=tiny_id,
-                                short_url=short_url,
-                                final_url=final_url,
-                                page_id=candidate,
-                            )
-                            return candidate
-            except Exception:
-                pass
-
-            logger.debug(
-                "confluence_tiny_url_no_page_id_in_redirect",
-                tiny_id=tiny_id,
-                short_url=short_url,
-                final_url=final_url,
-            )
-            return None
-
-        return await asyncio.to_thread(_do_resolve)