pull-cli 0.1.0__py3-none-any.whl

pull_cli/__init__.py

@@ -0,0 +1,5 @@
+"""AI-optimized Confluence extraction CLI."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

pull_cli/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pull_cli/assets.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import hashlib
+import mimetypes
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+from bs4 import BeautifulSoup
+
+from .attachment_extractors import extract_text_sidecar, write_extracted_markdown
+from .clients.base import ConfluenceClient
+from .models import AssetRecord, AssetReference, AttachmentRecord, PullOptions, WarningRecord
+from .paths import safe_filename, unique_name
+from .security import sanitize_url
+
+ATTACHMENT_PATH_RE = re.compile(r"/download/attachments/(?P<page_id>[^/]+)/(?P<filename>[^?#]+)")
+
+
+@dataclass
+class AssetCandidate:
+    original: str
+    role: str
+    html_attribute: str
+    attachment: AttachmentRecord | None = None
+    filename: str | None = None
+
+
+def discover_asset_candidates(
+    html: str,
+    *,
+    page_id: str,
+    attachments: list[AttachmentRecord],
+    options: PullOptions,
+) -> list[AssetCandidate]:
+    if options.no_assets:
+        return []
+    soup = BeautifulSoup(html or "", "lxml")
+    attachment_by_name = {attachment.filename.lower(): attachment for attachment in attachments}
+    attachment_by_url = {
+        _normalize_url(attachment.download_url): attachment
+        for attachment in attachments
+        if attachment.download_url
+    }
+    candidates: list[AssetCandidate] = []
+    seen: set[tuple[str, str]] = set()
+
+    for tag in soup.find_all("img"):
+        src = tag.get("src")
+        if not isinstance(src, str) or _is_external(src) or _is_confluence_chrome_asset(src):
+            continue
+        attachment = attachment_by_url.get(_normalize_url(src)) or attachment_by_name.get(_filename_from_url(src).lower())
+        _add_candidate(
+            candidates,
+            seen,
+            AssetCandidate(src, "visible-image", "src", attachment, _filename_from_url(src)),
+        )
+
+    for tag in soup.find_all("a"):
+        href = tag.get("href")
+        if not isinstance(href, str):
+            continue
+        filename = _filename_from_url(href)
+        attachment = attachment_by_url.get(_normalize_url(href)) or attachment_by_name.get(filename.lower())
+        if attachment or ATTACHMENT_PATH_RE.search(href):
+            _add_candidate(candidates, seen, AssetCandidate(href, "linked-attachment", "href", attachment, filename))
+
+    if options.asset_policy in {"page", "all"}:
+        for attachment in attachments:
+            _add_candidate(
+                candidates,
+                seen,
+                AssetCandidate(
+                    attachment.download_url or attachment.web_url or attachment.filename,
+                    "page-attachment",
+                    "attachment",
+                    attachment,
+                    attachment.filename,
+                ),
+            )
+
+    return candidates
+
+
+def download_assets(
+    candidates: list[AssetCandidate],
+    *,
+    page_id: str,
+    page_assets_dir: Path,
+    page_assets_path: str,
+    client: ConfluenceClient,
+    extract_attachments: bool = False,
+) -> tuple[list[AssetRecord], list[WarningRecord]]:
+    assets: list[AssetRecord] = []
+    warnings: list[WarningRecord] = []
+    used_names: set[str] = set()
+    page_assets_dir.mkdir(parents=True, exist_ok=True)
+    for index, candidate in enumerate(candidates, start=1):
+        filename = safe_filename(candidate.attachment.filename if candidate.attachment else candidate.filename or "asset")
+        filename = unique_name(filename, used_names)
+        try:
+            content = (
+                client.download_attachment(candidate.attachment)
+                if candidate.attachment
+                else client.download_url(candidate.original)
+            )
+        except Exception as exc:  # noqa: BLE001
+            warnings.append(
+                WarningRecord(
+                    code="W_ASSET_DOWNLOAD_FAILED",
+                    message=f"Could not download asset {filename}.",
+                    source_page_id=page_id,
+                    details={"source_url": sanitize_url(candidate.original), "reason": str(exc)},
+                )
+            )
+            continue
+        target = page_assets_dir / filename
+        target.write_bytes(content)
+        digest = hashlib.sha256(content).hexdigest()
+        media_type = candidate.attachment.media_type if candidate.attachment else mimetypes.guess_type(filename)[0]
+        sidecars: list[str] = []
+        if extract_attachments:
+            try:
+                extracted = extract_text_sidecar(target)
+                if extracted:
+                    sidecar = write_extracted_markdown(target, extracted)
+                    sidecars.append(f"{page_assets_path}/{sidecar.name}")
+            except Exception as exc:  # noqa: BLE001
+                warnings.append(
+                    WarningRecord(
+                        code="W_ATTACHMENT_TEXT_EXTRACTION_FAILED",
+                        message=f"Could not extract text sidecar for {filename}.",
+                        source_page_id=page_id,
+                        details={"reason": str(exc), "filename": filename},
+                    )
+                )
+        assets.append(
+            AssetRecord(
+                asset_id=f"asset-{page_id}-{index}",
+                source_page_id=page_id,
+                attachment_id=candidate.attachment.attachment_id if candidate.attachment else None,
+                filename=filename,
+                media_type=media_type,
+                local_path=f"{page_assets_path}/{filename}",
+                sha256=digest,
+                role=candidate.role,
+                source_url=sanitize_url(candidate.attachment.download_url if candidate.attachment else candidate.original),
+                references=[
+                    AssetReference(
+                        page_id=page_id,
+                        html_attribute=candidate.html_attribute,
+                        original=sanitize_url(candidate.original) or candidate.original,
+                    )
+                ],
+                sidecars=sidecars,
+            )
+        )
+    return assets, warnings
+
+
+def skipped_asset_warnings(html: str, *, page_id: str) -> list[WarningRecord]:
+    soup = BeautifulSoup(html or "", "lxml")
+    warnings: list[WarningRecord] = []
+    for tag in soup.find_all("img"):
+        src = tag.get("src")
+        if isinstance(src, str):
+            warnings.append(
+                WarningRecord(
+                    code="W_ASSET_SKIPPED_BY_POLICY",
+                    message="Image asset download was skipped by --no-assets.",
+                    source_page_id=page_id,
+                    details={"source_url": sanitize_url(src)},
+                )
+            )
+    for tag in soup.find_all("a"):
+        href = tag.get("href")
+        if isinstance(href, str) and ATTACHMENT_PATH_RE.search(href):
+            warnings.append(
+                WarningRecord(
+                    code="W_ASSET_SKIPPED_BY_POLICY",
+                    message="Attachment download was skipped by --no-assets.",
+                    source_page_id=page_id,
+                    details={"source_url": sanitize_url(href)},
+                )
+            )
+    return warnings
+
+
+def _add_candidate(
+    candidates: list[AssetCandidate], seen: set[tuple[str, str]], candidate: AssetCandidate
+) -> None:
+    key_value = (
+        f"attachment:{candidate.attachment.attachment_id}"
+        if candidate.attachment
+        else _normalize_url(candidate.original)
+    )
+    key = (key_value, "asset")
+    if key in seen:
+        return
+    seen.add(key)
+    candidates.append(candidate)
+
+
+def _filename_from_url(url: str) -> str:
+    parsed = urlsplit(url)
+    path = unquote(parsed.path)
+    match = ATTACHMENT_PATH_RE.search(path)
+    if match:
+        return unquote(match.group("filename"))
+    return Path(path).name or "asset"
+
+
+def _normalize_url(url: str | None) -> str:
+    if not url:
+        return ""
+    parsed = urlsplit(url)
+    return unquote(parsed.path).lower()
+
+
+def _is_external(url: str) -> bool:
+    return url.startswith(("http://", "https://")) and "/download/attachments/" not in url
+
+
+def _is_confluence_chrome_asset(url: str) -> bool:
+    parsed = urlsplit(url)
+    return any(
+        marker in parsed.path
+        for marker in (
+            "/images/icons/",
+            "/s/",
+            "/download/resources/",
+            "/plugins/servlet/",
+        )
+    )

pull_cli/attachment_extractors.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+TEXT_SUFFIXES = {".txt", ".md", ".csv", ".tsv", ".json", ".xml", ".svg", ".log", ".yaml", ".yml"}
+
+
+def extract_text_sidecar(path: Path) -> str | None:
+    suffix = path.suffix.lower()
+    if suffix in TEXT_SUFFIXES:
+        return _read_text(path)
+    if suffix == ".pdf":
+        return _extract_pdf(path)
+    if suffix == ".docx":
+        return _extract_docx(path)
+    if suffix == ".xlsx":
+        return _extract_xlsx(path)
+    if suffix == ".pptx":
+        return _extract_pptx(path)
+    return None
+
+
+def write_extracted_markdown(path: Path, text: str) -> Path:
+    sidecar = path.with_name(f"{path.stem}.extracted.md")
+    sidecar.write_text(f"# Extracted Text: {path.name}\n\n{text.strip()}\n", encoding="utf-8")
+    return sidecar
+
+
+def _read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _extract_pdf(path: Path) -> str | None:
+    try:
+        from pypdf import PdfReader
+    except ImportError:
+        return None
+    reader = PdfReader(str(path))
+    return "\n\n".join(page.extract_text() or "" for page in reader.pages).strip() or None
+
+
+def _extract_docx(path: Path) -> str | None:
+    try:
+        import docx
+    except ImportError:
+        return None
+    document = docx.Document(str(path))
+    return "\n".join(paragraph.text for paragraph in document.paragraphs if paragraph.text).strip() or None
+
+
+def _extract_xlsx(path: Path) -> str | None:
+    try:
+        import openpyxl
+    except ImportError:
+        return None
+    workbook = openpyxl.load_workbook(str(path), read_only=True, data_only=True)
+    lines: list[str] = []
+    for sheet in workbook.worksheets:
+        lines.append(f"## Sheet: {sheet.title}")
+        for row in sheet.iter_rows(values_only=True):
+            values = ["" if value is None else str(value) for value in row]
+            if any(values):
+                lines.append("\t".join(values))
+    return "\n".join(lines).strip() or None
+
+
+def _extract_pptx(path: Path) -> str | None:
+    try:
+        from pptx import Presentation
+    except ImportError:
+        return None
+    presentation = Presentation(str(path))
+    lines: list[str] = []
+    for slide_number, slide in enumerate(presentation.slides, start=1):
+        lines.append(f"## Slide {slide_number}")
+        for shape in slide.shapes:
+            if hasattr(shape, "text") and shape.text:
+                lines.append(shape.text)
+            if getattr(shape, "has_table", False):
+                rows = []
+                for row in shape.table.rows:
+                    rows.append([cell.text for cell in row.cells])
+                lines.append(json.dumps(rows, ensure_ascii=False))
+    return "\n".join(lines).strip() or None

pull_cli/cli.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .clients import build_client
+from .config import resolve_config
+from .envelope import emit_json, make_envelope, wants_json
+from .errors import EXIT_INTERNAL, EXIT_SUCCESS, EXIT_VALIDATION, PullError
+from .extractor import extract
+from .guide import guide_payload
+from .models import PullOptions, TargetSelection
+from .resolver import resolve_target
+from .security import sanitize_url
+from .validator import validate_package
+
+
+class PullArgumentParser(argparse.ArgumentParser):
+    def __init__(self, *args, json_mode: bool = False, command: str = "pull", **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.json_mode = json_mode
+        self.command = command
+
+    def error(self, message: str) -> None:
+        if self.json_mode:
+            error = PullError(
+                code="ERR_VALIDATION_INVALID_ARGUMENT",
+                message=message,
+                exit_code=EXIT_VALIDATION,
+                suggested_action="Run pull --help or pull guide --json for valid arguments.",
+                details={"argument_error": message},
+            )
+            emit_json(make_envelope(ok=False, command=self.command, errors=[error]))
+            raise SystemExit(EXIT_VALIDATION)
+        super().error(message)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = list(argv if argv is not None else sys.argv[1:])
+    try:
+        if args and args[0] == "validate":
+            return _main_validate(args[1:])
+        if args and args[0] == "guide":
+            return _main_guide(args[1:])
+        if args and args[0] == "version":
+            print(f"pull-cli {__version__}")
+            return EXIT_SUCCESS
+        return _main_pull(args)
+    except PullError as exc:
+        if _argv_wants_json(args):
+            emit_json(make_envelope(ok=False, command="pull", errors=[exc]))
+        else:
+            print(f"{exc.code}: {exc.message}", file=sys.stderr)
+            if exc.suggested_action:
+                print(f"Suggested action: {exc.suggested_action}", file=sys.stderr)
+        return exc.exit_code
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:  # noqa: BLE001
+        error = PullError(
+            code="ERR_INTERNAL_CONVERSION",
+            message="An internal error occurred.",
+            exit_code=EXIT_INTERNAL,
+            details={"reason": str(exc)},
+        )
+        if _argv_wants_json(args):
+            emit_json(make_envelope(ok=False, command="pull", errors=[error]))
+        else:
+            print(f"{error.code}: {error.message}", file=sys.stderr)
+        return EXIT_INTERNAL
+
+
+def _main_pull(argv: Sequence[str]) -> int:
+    parser = _pull_parser(json_mode=_argv_wants_json(argv))
+    ns = parser.parse_args(argv)
+    json_mode = wants_json(ns.json)
+    started = time.perf_counter()
+    config = resolve_config(
+        base_url=ns.base_url,
+        user=ns.user,
+        token=ns.token,
+        cloud_id=ns.cloud_id,
+        ssl_verify=ns.ssl_verify,
+        config_path=ns.config,
+    )
+    selection = TargetSelection(
+        positional=ns.page_ref,
+        page_id=ns.page_id,
+        url=ns.url,
+        space=ns.space,
+        title=ns.title,
+    )
+    options = PullOptions(
+        output=Path(ns.output),
+        force=ns.force,
+        clean=ns.clean,
+        tree=ns.tree,
+        depth=ns.depth,
+        max_pages=ns.max_pages,
+        layout=ns.layout,
+        output_mode=ns.output_mode,
+        write_bundle=ns.bundle,
+        write_html=ns.html,
+        write_source=ns.source,
+        write_chunks=ns.chunks,
+        asset_policy=ns.assets,
+        no_assets=ns.no_assets,
+        extract_attachments=ns.extract_attachments,
+        comments=ns.comments,
+        diagram_sources=ns.diagram_sources,
+        render_mode=ns.render_mode,
+        macro_policy=ns.macro_policy,
+        unknown_macro=ns.unknown_macro,
+        rewrite_links=ns.rewrite_links,
+        follow_includes=ns.follow_includes,
+        follow_links=ns.follow_links,
+        include_non_page_children=ns.include_non_page_children,
+        redact_source_urls=ns.redact_source_urls,
+        redact_manifest=ns.redact_manifest,
+        strict=ns.strict,
+    )
+    client = build_client(config)
+    try:
+        root = resolve_target(selection, client)
+        result = extract(client=client, root=root, options=options)
+    finally:
+        client.close()
+    duration_ms = int((time.perf_counter() - started) * 1000)
+    result.metrics["duration_ms"] = duration_ms
+    payload = make_envelope(
+        ok=True,
+        command="pull",
+        target={
+            "page_id": result.pages[0].page.page_id if result.pages else root.page_id,
+            "url": sanitize_url(
+                result.pages[0].page.url if result.pages else root.url,
+                redact_source_url=options.redact_source_urls,
+            ),
+        },
+        result={
+            "output_dir": str(result.output_dir),
+            "manifest": str(result.manifest_path),
+            "ai_entry": str(result.ai_entry_path) if result.ai_entry_path else None,
+            "bundle": str(result.bundle_path) if result.bundle_path else None,
+            "output_mode": options.output_mode,
+            "pages": len(result.pages),
+            "assets": len(result.assets),
+            "warnings": len(result.warnings),
+        },
+        warnings=result.warnings,
+        metrics=result.metrics,
+    )
+    if json_mode:
+        emit_json(payload)
+    else:
+        print(
+            f"Pulled {len(result.pages)} page(s), {len(result.assets)} asset(s), "
+            f"{len(result.warnings)} warning(s) into {result.output_dir}"
+        )
+    return EXIT_SUCCESS
+
+
+def _main_validate(argv: Sequence[str]) -> int:
+    parser = PullArgumentParser(
+        prog="pull validate",
+        description="Validate a pulled Confluence package.",
+        json_mode=_argv_wants_json(argv),
+        command="validate",
+    )
+    parser.add_argument("path", nargs="?", metavar="MANIFEST_OR_OUTPUT_DIR")
+    parser.add_argument("--json", action="store_true", help="Emit a structured JSON envelope.")
+    ns = parser.parse_args(argv)
+    json_mode = wants_json(ns.json)
+    if not ns.path:
+        error = PullError(
+            code="ERR_VALIDATION_REQUIRED",
+            message="Missing required MANIFEST_OR_OUTPUT_DIR argument.",
+            exit_code=EXIT_VALIDATION,
+            suggested_action="Pass an output directory or manifest.yaml path.",
+        )
+        payload = make_envelope(ok=False, command="validate", target={}, errors=[error])
+        if json_mode:
+            emit_json(payload)
+        else:
+            print(f"{error.code}: {error.message}", file=sys.stderr)
+            print("Usage: pull validate MANIFEST_OR_OUTPUT_DIR [--json]", file=sys.stderr)
+        return EXIT_VALIDATION
+    validation = validate_package(Path(ns.path))
+    payload = make_envelope(
+        ok=validation.ok,
+        command="validate",
+        target={"path": ns.path},
+        result={
+            "manifest": str(validation.manifest_path),
+            "output_dir": str(validation.output_dir),
+            "errors": len(validation.errors),
+            "warnings": len(validation.warnings),
+            "validation_warnings": len(validation.warnings),
+            "package_warnings": validation.metrics.get("package_warnings", 0),
+        },
+        warnings=validation.warnings,
+        errors=validation.errors,
+        metrics=validation.metrics,
+    )
+    if json_mode:
+        emit_json(payload)
+    elif validation.ok:
+        print(
+            f"Validation passed for {validation.manifest_path} "
+            f"({validation.metrics.get('pages', 0)} page(s), {validation.metrics.get('assets', 0)} asset(s))."
+        )
+    else:
+        for error in validation.errors:
+            print(f"{error['code']}: {error['message']}", file=sys.stderr)
+            details = error.get("details", {})
+            if details.get("file"):
+                print(f"  file: {details['file']}", file=sys.stderr)
+            if details.get("link"):
+                print(f"  link: {details['link']}", file=sys.stderr)
+            if details.get("resolution_base"):
+                print(f"  resolution_base: {details['resolution_base']}", file=sys.stderr)
+            if details.get("candidate_path"):
+                print(f"  candidate_path: {details['candidate_path']}", file=sys.stderr)
+        print("Rerun with --json for the structured validation envelope.", file=sys.stderr)
+    return 0 if validation.ok else 10
+
+
+def _main_guide(argv: Sequence[str]) -> int:
+    parser = PullArgumentParser(
+        prog="pull guide",
+        description="Emit agent-readable CLI and output schema.",
+        json_mode=_argv_wants_json(argv),
+        command="guide",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit only the guide payload as JSON.")
+    ns = parser.parse_args(argv)
+    payload = guide_payload()
+    if wants_json(ns.json):
+        print(json.dumps(payload, ensure_ascii=False, separators=(",", ":")))
+    else:
+        print("pull-cli guide")
+        print("Commands: pull PAGE_REF [OPTIONS], pull validate PATH, pull guide --json")
+        print("Use --json or LLM=true for stable agent envelopes on pull/validate.")
+        print("Recommended agent flow: pull guide --json, pull ... --json, pull validate <output-dir> --json.")
+        print("Default output mode is simple: root AI Markdown, page Markdown, assets, and validation control files.")
+        print("Use --output-mode full for bundle.md, page HTML snapshots, and source.storage.xml; use --clean to remove stale files when switching modes.")
+        print("Start analysis from <sanitized-root-page-title>.md in the output package.")
+        print("Manifest and AI manifest paths are package-root-relative; page links are page-file-relative.")
+        print("Run pull guide --json for the full machine-readable schema, error codes, and warning codes.")
+    return EXIT_SUCCESS
+
+
+def _pull_parser(*, json_mode: bool = False) -> argparse.ArgumentParser:
+    parser = PullArgumentParser(
+        prog="pull",
+        description="Pull Confluence pages into local AI-consumable evidence packages.",
+        epilog=(
+            "Commands: pull PAGE_REF [OPTIONS]; pull validate MANIFEST_OR_OUTPUT_DIR [--json]; "
+            "pull guide [--json]; pull version. "
+            "Default output mode is simple; use --output-mode full for bundle/html/source artifacts. "
+            "Agent flow: pull guide --json, pull ... --json, pull validate <output-dir> --json."
+        ),
+        json_mode=json_mode,
+        command="pull",
+    )
+    parser.add_argument("page_ref", nargs="?", metavar="PAGE_REF", help="Confluence page ID or page URL.")
+    parser.add_argument("--page-id", dest="page_id", help="Confluence page/content ID.")
+    parser.add_argument("--url", help="Confluence page URL.")
+    parser.add_argument("--space", help="Confluence space key, used with --title.")
+    parser.add_argument("--title", help="Confluence page title, used with --space.")
+
+    parser.add_argument("--tree", action="store_true", help="Pull descendant page hierarchy.")
+    parser.add_argument("--depth", type=int, help="Tree depth limit; 0 equals single page.")
+    parser.add_argument("--max-pages", type=int, default=500, help="Safety cap for tree pulls.")
+    parser.add_argument("--include-non-page-children", action="store_true")
+
+    parser.add_argument("-o", "--output", default="pulled-confluence", help="Output directory.")
+    parser.add_argument("--force", action="store_true", help="Overwrite files in an existing output directory.")
+    parser.add_argument("--clean", action="store_true", help="Delete stale files in the output directory first.")
+    parser.add_argument("--layout", choices=["auto", "nested", "flat"], default="auto")
+    parser.add_argument(
+        "--output-mode",
+        choices=["simple", "full"],
+        default="simple",
+        help="Output artifact profile. simple writes quiet agent-facing Markdown by default; full writes all evidence artifacts.",
+    )
+    parser.add_argument("--bundle", dest="bundle", action=argparse.BooleanOptionalAction, default=None)
+    parser.add_argument("--html", dest="html", action=argparse.BooleanOptionalAction, default=None)
+    parser.add_argument("--source", dest="source", action=argparse.BooleanOptionalAction, default=None)
+    parser.add_argument("--chunks", action="store_true")
+
+    parser.add_argument("--assets", choices=["visible", "page", "all"], default="visible")
+    parser.add_argument("--no-assets", action="store_true")
+    parser.add_argument("--extract-attachments", action="store_true")
+    parser.add_argument("--comments", action="store_true", help="Fetch page and inline comments into page-local comments.md sidecars.")
+    parser.add_argument("--diagram-sources", action="store_true")
+
+    parser.add_argument("--render-mode", choices=["hybrid", "view", "export-view", "styled-view", "storage"], default="hybrid")
+    parser.add_argument("--macro-policy", choices=["expand", "placeholder", "strict"], default="expand")
+    parser.add_argument("--unknown-macro", choices=["warn", "error", "ignore"], default="warn")
+
+    parser.add_argument("--rewrite-links", dest="rewrite_links", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--follow-includes", action="store_true")
+    parser.add_argument("--follow-links", choices=["same-tree", "same-space", "none"], default="none")
+
+    parser.add_argument("--base-url", help="Confluence base URL.")
+    parser.add_argument("--user", help="Confluence username/email.")
+    parser.add_argument("--token", help="Confluence API token or PAT. Prefer env vars.")
+    parser.add_argument("--cloud-id", help="Optional Confluence Cloud ID.")
+    parser.add_argument("--ssl-verify", help="true, false, or path to an enterprise CA bundle.")
+    parser.add_argument("--config", help="Optional config YAML path.")
+
+    parser.add_argument("--json", action="store_true", help="Emit a structured JSON object on stdout.")
+    parser.add_argument("--version", action="version", version=f"pull-cli {__version__}")
+    parser.add_argument("--quiet", action="store_true", help="Accepted but currently no-op; reserved for progress suppression.")
+    parser.add_argument("--verbose", action="store_true", help="Accepted but currently no-op; reserved for extra diagnostics.")
+    parser.add_argument("--redact-source-urls", action="store_true")
+    parser.add_argument("--redact-manifest", action="store_true")
+    parser.add_argument("--strict", action="store_true", help="Treat strict extraction failures as errors.")
+    return parser
+
+
+def _argv_wants_json(argv: Sequence[str]) -> bool:
+    return "--json" in argv or wants_json(False)

pull_cli/clients/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from .base import ConfluenceClient
+from .cloud_v2 import CloudV2Client
+from .data_center import DataCenterClient
+from .hybrid import build_client
+
+__all__ = ["CloudV2Client", "ConfluenceClient", "DataCenterClient", "build_client"]