cli-web-codewiki 0.1.0__py3-none-any.whl

cli_web/codewiki/tests/test_e2e.py

@@ -0,0 +1,411 @@
+"""E2E and subprocess tests for cli-web-codewiki.
+
+All live tests hit the real codewiki.google API.
+Mark: @pytest.mark.e2e for live network tests.
+
+Usage:
+    pytest cli_web/codewiki/tests/test_e2e.py -v -s -m e2e
+    CLI_WEB_FORCE_INSTALLED=1 pytest cli_web/codewiki/tests/test_e2e.py -v -s
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+import pytest
+from cli_web.codewiki.core.client import CodeWikiClient
+from cli_web.codewiki.core.models import ChatResponse, Repository, WikiPage, WikiSection
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_cli(name: str = "cli-web-codewiki") -> str:
+    """Return the CLI entry-point path, falling back to module mode via sys.executable."""
+    if os.environ.get("CLI_WEB_FORCE_INSTALLED"):
+        path = shutil.which(name)
+        if path:
+            return path
+        raise FileNotFoundError(f"{name} not found in PATH")
+    path = shutil.which(name)
+    if path:
+        return path
+    return sys.executable
+
+
+# ---------------------------------------------------------------------------
+# TestLiveRepos
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.e2e
+class TestLiveRepos:
+    """Live tests for repository listing and search."""
+
+    def test_featured_repos_returns_data(self):
+        """Live: featured repos has at least 1 result with slug and stars."""
+        client = CodeWikiClient()
+        try:
+            repos = client.featured_repos()
+        finally:
+            client.close()
+
+        assert len(repos) > 0, "Expected at least one featured repo"
+        first = repos[0]
+        assert isinstance(first, Repository)
+        assert first.slug, "slug must be non-empty"
+        assert first.stars > 0, "stars must be positive"
+
+    def test_search_returns_results(self):
+        """Live: search for 'react' returns results."""
+        client = CodeWikiClient()
+        try:
+            repos = client.search_repos("react")
+        finally:
+            client.close()
+
+        assert len(repos) > 0, "Expected at least one search result for 'react'"
+        assert any("react" in r.slug.lower() for r in repos), (
+            "At least one slug should contain 'react'"
+        )
+
+    def test_search_empty_query_returns_empty(self):
+        """Live: search with nonsense query returns empty list."""
+        client = CodeWikiClient()
+        try:
+            repos = client.search_repos("zzzzznonexistent99999")
+        finally:
+            client.close()
+
+        assert isinstance(repos, list), "Result must be a list"
+
+    def test_search_with_limit(self):
+        """Live: search respects the limit parameter."""
+        client = CodeWikiClient()
+        try:
+            repos = client.search_repos("python", limit=5)
+        finally:
+            client.close()
+
+        assert isinstance(repos, list)
+        assert len(repos) <= 5, "Result count must not exceed requested limit"
+
+    def test_featured_repo_slugs_have_org_and_name(self):
+        """Live: each featured repo slug is in org/name format."""
+        client = CodeWikiClient()
+        try:
+            repos = client.featured_repos()
+        finally:
+            client.close()
+
+        assert len(repos) > 0
+        for repo in repos[:5]:
+            assert "/" in repo.slug, f"slug '{repo.slug}' missing org/name separator"
+            assert repo.org, f"org must be non-empty for slug '{repo.slug}'"
+            assert repo.name, f"name must be non-empty for slug '{repo.slug}'"
+
+
+# ---------------------------------------------------------------------------
+# TestLiveWiki
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.e2e
+class TestLiveWiki:
+    """Live tests for wiki page fetching."""
+
+    def test_wiki_get_returns_sections(self):
+        """Live: wiki get for facebook/react returns sections."""
+        client = CodeWikiClient()
+        try:
+            wiki = client.get_wiki("facebook/react")
+        finally:
+            client.close()
+
+        assert isinstance(wiki, WikiPage)
+        assert len(wiki.sections) > 0, "Expected at least one wiki section"
+        assert wiki.repo.slug == "facebook/react"
+        assert wiki.repo.commit_hash, "commit_hash must be present"
+
+    def test_wiki_sections_have_content(self):
+        """Live: first section has markdown content."""
+        client = CodeWikiClient()
+        try:
+            wiki = client.get_wiki("excalidraw/excalidraw")
+        finally:
+            client.close()
+
+        overview = wiki.sections[0]
+        assert isinstance(overview, WikiSection)
+        assert overview.title, "section title must be non-empty"
+        assert overview.level >= 1, "section level must be >= 1"
+        assert len(overview.content) > 50, (
+            f"Expected content > 50 chars, got {len(overview.content)}"
+        )
+
+    def test_wiki_not_found(self):
+        """Live: nonexistent repo raises NotFoundError."""
+        from cli_web.codewiki.core.exceptions import NotFoundError
+
+        client = CodeWikiClient()
+        try:
+            with pytest.raises(NotFoundError):
+                client.get_wiki("nonexistent-org-xyz/nonexistent-repo-abc")
+        finally:
+            client.close()
+
+    def test_wiki_sections_structure(self):
+        """Live: all wiki sections have required fields."""
+        client = CodeWikiClient()
+        try:
+            wiki = client.get_wiki("facebook/react")
+        finally:
+            client.close()
+
+        for section in wiki.sections:
+            assert isinstance(section, WikiSection)
+            assert isinstance(section.title, str)
+            assert isinstance(section.level, int)
+            assert section.level >= 1
+            assert isinstance(section.content, str)
+            assert isinstance(section.code_refs, list)
+
+    def test_wiki_repo_metadata(self):
+        """Live: wiki page contains repo metadata including github_url."""
+        client = CodeWikiClient()
+        try:
+            wiki = client.get_wiki("excalidraw/excalidraw")
+        finally:
+            client.close()
+
+        assert wiki.repo.github_url == "https://github.com/excalidraw/excalidraw"
+        assert wiki.repo.slug == "excalidraw/excalidraw"
+
+
+# ---------------------------------------------------------------------------
+# TestLiveChat
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.e2e
+class TestLiveChat:
+    """Live tests for the Gemini chat endpoint."""
+
+    def test_chat_returns_answer(self):
+        """Live: chat returns a markdown answer."""
+        client = CodeWikiClient()
+        try:
+            response = client.chat("What is this project about?", "facebook/react")
+        finally:
+            client.close()
+
+        assert isinstance(response, ChatResponse)
+        assert len(response.answer) > 50, f"Expected answer > 50 chars, got {len(response.answer)}"
+        assert response.repo_slug == "facebook/react"
+
+    def test_chat_no_rpc_leak(self):
+        """Live: chat answer must not contain raw RPC data."""
+        client = CodeWikiClient()
+        try:
+            response = client.chat("Describe the architecture", "excalidraw/excalidraw")
+        finally:
+            client.close()
+
+        assert "wrb.fr" not in response.answer, "RPC frame prefix leaked into answer"
+        assert "af.httprm" not in response.answer, "RPC metadata leaked into answer"
+
+    def test_chat_answer_is_string(self):
+        """Live: chat answer field is a plain string (not nested structure)."""
+        client = CodeWikiClient()
+        try:
+            response = client.chat("What programming language is used?", "facebook/react")
+        finally:
+            client.close()
+
+        assert isinstance(response.answer, str), "answer must be a plain string"
+        assert response.answer.strip(), "answer must not be blank"
+
+
+# ---------------------------------------------------------------------------
+# TestCLISubprocess
+# ---------------------------------------------------------------------------
+
+
+class TestCLISubprocess:
+    """Subprocess tests — exercise the installed CLI binary end-to-end."""
+
+    @classmethod
+    def setup_class(cls):
+        cls.cli = _resolve_cli()
+        # If cli is sys.executable, use module mode
+        cls.use_module = cls.cli == sys.executable
+
+    def _run(self, args: list[str], timeout: int = 60) -> subprocess.CompletedProcess:
+        if self.use_module:
+            cmd = [self.cli, "-m", "cli_web.codewiki"] + args
+        else:
+            cmd = [self.cli] + args
+        return subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+
+    def test_help_loads(self):
+        """Subprocess: --help exits 0 and mentions all command groups."""
+        result = self._run(["--help"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        assert "repos" in result.stdout
+        assert "wiki" in result.stdout
+        assert "chat" in result.stdout
+
+    def test_repos_help(self):
+        """Subprocess: repos --help lists featured and search subcommands."""
+        result = self._run(["repos", "--help"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        assert "featured" in result.stdout
+        assert "search" in result.stdout
+
+    def test_wiki_help(self):
+        """Subprocess: wiki --help lists get, sections, section subcommands."""
+        result = self._run(["wiki", "--help"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        assert "get" in result.stdout
+        assert "sections" in result.stdout
+        assert "section" in result.stdout
+
+    @pytest.mark.e2e
+    def test_repos_featured_json(self):
+        """Subprocess/live: repos featured --json returns valid structured output."""
+        result = self._run(["repos", "featured", "--json"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        data = json.loads(result.stdout)
+        assert data["success"] is True
+        assert isinstance(data["data"], list)
+        assert len(data["data"]) > 0
+        first = data["data"][0]
+        assert "slug" in first
+        assert "stars" in first
+
+    @pytest.mark.e2e
+    def test_repos_search_json(self):
+        """Subprocess/live: repos search returns valid JSON."""
+        result = self._run(["repos", "search", "kubernetes", "--json"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        data = json.loads(result.stdout)
+        assert data["success"] is True
+        assert isinstance(data["data"], list)
+
+    @pytest.mark.e2e
+    def test_repos_search_limit(self):
+        """Subprocess/live: repos search --limit is respected."""
+        result = self._run(["repos", "search", "python", "--limit", "3", "--json"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        data = json.loads(result.stdout)
+        assert data["success"] is True
+        assert len(data["data"]) <= 3
+
+    @pytest.mark.e2e
+    def test_wiki_sections_json(self):
+        """Subprocess/live: wiki sections returns a list with title fields."""
+        result = self._run(["wiki", "sections", "facebook/react", "--json"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        data = json.loads(result.stdout)
+        assert data["success"] is True
+        sections = data["data"]
+        assert isinstance(sections, list)
+        assert len(sections) > 0
+        assert "title" in sections[0]
+        assert "level" in sections[0]
+
+    @pytest.mark.e2e
+    def test_wiki_get_json(self):
+        """Subprocess/live: wiki get returns full page structure."""
+        result = self._run(["wiki", "get", "excalidraw/excalidraw", "--json"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        data = json.loads(result.stdout)
+        assert data["success"] is True
+        wiki = data["data"]
+        assert "repo" in wiki
+        assert "sections" in wiki
+        assert wiki["repo"]["slug"] == "excalidraw/excalidraw"
+        assert len(wiki["sections"]) > 0
+
+    @pytest.mark.e2e
+    def test_chat_ask_json(self):
+        """Subprocess/live: chat ask returns answer without RPC leaks."""
+        result = self._run(
+            ["chat", "ask", "What is this?", "--repo", "facebook/react", "--json"],
+            timeout=90,
+        )
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        data = json.loads(result.stdout)
+        assert data["success"] is True
+        answer = data["data"]["answer"]
+        assert len(answer) > 20, f"Expected longer answer, got: {answer!r}"
+        assert "wrb.fr" not in answer, "RPC frame prefix leaked into CLI output"
+
+    @pytest.mark.e2e
+    def test_wiki_not_found_returns_error_json(self):
+        """Subprocess/live: wiki get for nonexistent repo exits non-zero with error JSON."""
+        result = self._run(["wiki", "get", "nonexistent-org-xyz/nonexistent-repo-abc", "--json"])
+        assert result.returncode != 0
+        data = json.loads(result.stdout)
+        assert data.get("error") is True
+        assert data.get("code") == "NOT_FOUND"
+
+    @pytest.mark.e2e
+    def test_repos_featured_no_json_exits_zero(self):
+        """Subprocess/live: repos featured (no --json) prints table and exits 0."""
+        result = self._run(["repos", "featured"])
+        assert result.returncode == 0, f"stderr: {result.stderr}"
+        # Should contain at least one org/repo slug pattern
+        assert "/" in result.stdout
+
+
+# ---------------------------------------------------------------------------
+# TestReadOnlyRoundTrip
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.e2e
+class TestReadOnlyRoundTrip:
+    """Round-trip consistency tests across API calls."""
+
+    def test_list_detail_consistency(self):
+        """Round-trip: search result slug matches wiki page repo info."""
+        client = CodeWikiClient()
+        try:
+            results = client.search_repos("excalidraw")
+            assert len(results) > 0, "Expected at least one search result"
+            slug = results[0].slug
+            wiki = client.get_wiki(slug)
+        finally:
+            client.close()
+
+        assert wiki.repo.slug == slug, f"wiki.repo.slug '{wiki.repo.slug}' != search slug '{slug}'"
+        assert len(wiki.sections) > 0, "Expected at least one section in wiki page"
+
+    def test_featured_to_wiki_round_trip(self):
+        """Round-trip: first featured repo can have its wiki fetched."""
+        client = CodeWikiClient()
+        try:
+            repos = client.featured_repos()
+            assert len(repos) > 0
+            slug = repos[0].slug
+            wiki = client.get_wiki(slug)
+        finally:
+            client.close()
+
+        assert wiki.repo.slug == slug
+        # The wiki page must belong to the same org/repo
+        assert wiki.repo.org == repos[0].org
+        assert wiki.repo.name == repos[0].name

cli_web/codewiki/utils/config.py

@@ -0,0 +1,14 @@
+"""Configuration management for cli-web-codewiki."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+APP_NAME = "cli-web-codewiki"
+CONFIG_DIR = Path.home() / ".config" / APP_NAME
+
+
+def ensure_config_dir() -> Path:
+    """Create config directory if it doesn't exist."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    return CONFIG_DIR

cli_web/codewiki/utils/doctor.py

@@ -0,0 +1,188 @@
+"""``doctor`` — self-diagnosis for cli-web-* CLIs.
+
+CANONICAL SOURCE: cli-web-core/cli_web_core/doctor.py
+Vendored into every generated CLI at cli_web/<app>/utils/doctor.py by
+`cli-web-devkit resync`. Do not edit vendored copies by hand.
+
+Checks the local environment a support thread would ask about first:
+installation, Python version, config directory, auth material (when the
+CLI has an auth module), and optional dependencies. Read-only — never
+mutates state, never touches the network.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import shutil
+import stat
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class DoctorCheck:
+    name: str
+    status: str  # "ok" | "warn" | "fail"
+    detail: str = ""
+
+
+def _check_entry_point(app_name: str) -> DoctorCheck:
+    binary = f"cli-web-{app_name}"
+    path = shutil.which(binary)
+    if path:
+        return DoctorCheck("entry point", "ok", path)
+    return DoctorCheck(
+        "entry point",
+        "warn",
+        f"{binary} not on PATH — run `pip install -e .` in agent-harness/ "
+        f"(python -m fallback still works)",
+    )
+
+
+def _check_python() -> DoctorCheck:
+    # Intentional runtime guard: direct-source runs bypass pip's
+    # python_requires, so the interpreter check must live here.
+    if sys.version_info >= (3, 10):  # noqa: UP036
+        return DoctorCheck("python", "ok", sys.version.split()[0])
+    return DoctorCheck("python", "fail", f"{sys.version.split()[0]} < 3.10 (unsupported)")
+
+
+def _config_dir(app_name: str) -> Path:
+    return Path.home() / ".config" / f"cli-web-{app_name}"
+
+
+def _check_config_dir(app_name: str) -> DoctorCheck:
+    cfg = _config_dir(app_name)
+    if not cfg.exists():
+        return DoctorCheck("config dir", "ok", f"{cfg} (not created yet — created on first use)")
+    if os.access(cfg, os.W_OK):
+        return DoctorCheck("config dir", "ok", str(cfg))
+    return DoctorCheck("config dir", "fail", f"{cfg} is not writable")
+
+
+def _has_auth_module(pkg: str) -> bool:
+    try:
+        return importlib.util.find_spec(f"cli_web.{pkg}.core.auth") is not None
+    except (ImportError, ModuleNotFoundError, ValueError):
+        return False
+
+
+def _check_auth(app_name: str, pkg: str) -> list[DoctorCheck]:
+    if not _has_auth_module(pkg):
+        return [DoctorCheck("auth", "ok", "no auth module — public site, nothing to configure")]
+
+    checks: list[DoctorCheck] = []
+    if importlib.util.find_spec("playwright") is None:
+        checks.append(
+            DoctorCheck(
+                "playwright",
+                "warn",
+                "not installed — `auth login` (browser flow) unavailable; "
+                "pip install playwright && playwright install chromium",
+            )
+        )
+    else:
+        checks.append(DoctorCheck("playwright", "ok", "installed"))
+
+    env_var = f"CLI_WEB_{app_name.upper().replace('-', '_')}_AUTH_JSON"
+    if os.environ.get(env_var):
+        checks.append(DoctorCheck("auth source", "ok", f"using env var {env_var}"))
+        return checks
+
+    auth_file = _config_dir(app_name) / "auth.json"
+    if not auth_file.is_file():
+        checks.append(
+            DoctorCheck(
+                "auth file",
+                "warn",
+                f"{auth_file} missing — run: cli-web-{app_name} auth login (or set {env_var})",
+            )
+        )
+        return checks
+
+    checks.append(DoctorCheck("auth file", "ok", str(auth_file)))
+    if os.name == "posix":  # st_mode permission bits are meaningless on Windows
+        mode = stat.S_IMODE(auth_file.stat().st_mode)
+        if mode & 0o077:
+            checks.append(
+                DoctorCheck(
+                    "auth file permissions",
+                    "warn",
+                    f"{oct(mode)} — should be 600; run: chmod 600 {auth_file}",
+                )
+            )
+        else:
+            checks.append(DoctorCheck("auth file permissions", "ok", oct(mode)))
+    try:
+        json.loads(auth_file.read_text(encoding="utf-8"))
+        checks.append(DoctorCheck("auth file format", "ok", "valid JSON"))
+    except (OSError, json.JSONDecodeError) as exc:
+        checks.append(DoctorCheck("auth file format", "fail", f"unreadable: {exc}"))
+
+    return checks
+
+
+def _check_optional_deps() -> list[DoctorCheck]:
+    checks = []
+    if importlib.util.find_spec("prompt_toolkit") is None:
+        checks.append(
+            DoctorCheck("prompt_toolkit", "ok", "not installed — REPL uses plain input()")
+        )
+    else:
+        checks.append(DoctorCheck("prompt_toolkit", "ok", "installed (REPL autocomplete on)"))
+    return checks
+
+
+def run_doctor(app_name: str, pkg: str) -> list[DoctorCheck]:
+    checks = [
+        _check_python(),
+        _check_entry_point(app_name),
+        _check_config_dir(app_name),
+        *_check_auth(app_name, pkg),
+        *_check_optional_deps(),
+    ]
+    return checks
+
+
+def register_doctor_command(cli: Any, app_name: str, pkg: str | None = None) -> None:
+    """Attach a ``doctor`` command to a cli-web-* Click group."""
+    import click
+
+    resolved_pkg = pkg or app_name.replace("-", "_")
+
+    @cli.command("doctor")
+    @click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+    @click.pass_context
+    def doctor(ctx: Any, json_mode: bool) -> None:
+        """Diagnose this CLI's local setup (install, auth, dependencies)."""
+        if not json_mode:  # honor the group-level --json flag (ctx.obj["json"])
+            obj = ctx.find_root().obj
+            json_mode = bool(obj.get("json")) if isinstance(obj, dict) else False
+        checks = run_doctor(app_name, resolved_pkg)
+        failed = [c for c in checks if c.status == "fail"]
+        if json_mode:
+            click.echo(
+                json.dumps(
+                    {
+                        "success": not failed,
+                        "data": {
+                            "checks": [asdict(c) for c in checks],
+                            "ok": not failed,
+                        },
+                    },
+                    indent=2,
+                )
+            )
+        else:
+            marks = {"ok": "✓", "warn": "⚠", "fail": "✗"}
+            for c in checks:
+                detail = f"  {c.detail}" if c.detail else ""
+                click.echo(f" {marks[c.status]} {c.name}:{detail}")
+            click.echo()
+            click.echo("all good" if not failed else f"{len(failed)} problem(s) found")
+        if failed:
+            raise SystemExit(1)

cli_web/codewiki/utils/helpers.py

@@ -0,0 +1,67 @@
+"""Shared helpers for cli-web-codewiki."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+import sys
+
+import click
+
+from ..core.exceptions import CodeWikiError, RateLimitError, error_code_for
+
+
+@contextlib.contextmanager
+def handle_errors(json_mode: bool = False):
+    """Context manager for consistent error handling in commands."""
+    try:
+        yield
+    except KeyboardInterrupt:
+        if not json_mode:
+            click.echo("\nInterrupted.", err=True)
+        sys.exit(130)
+    except click.exceptions.Exit:
+        raise
+    except click.UsageError:
+        raise
+    except CodeWikiError as exc:
+        code = error_code_for(exc)
+        if json_mode:
+            err = {"error": True, "code": code, "message": str(exc)}
+            if isinstance(exc, RateLimitError) and exc.retry_after is not None:
+                err["retry_after"] = exc.retry_after
+            click.echo(json.dumps(err))
+        else:
+            click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+    except Exception as exc:
+        if json_mode:
+            click.echo(
+                json.dumps(
+                    {
+                        "error": True,
+                        "code": "INTERNAL_ERROR",
+                        "message": str(exc),
+                    }
+                )
+            )
+        else:
+            click.echo(f"Error: {exc}", err=True)
+        sys.exit(2)
+
+
+def _resolve_cli(name: str = "cli-web-codewiki") -> str:
+    """Find the CLI binary path for subprocess tests."""
+    if os.environ.get("CLI_WEB_FORCE_INSTALLED"):
+        path = shutil.which(name)
+        if path:
+            return path
+        raise FileNotFoundError(f"{name} not found in PATH")
+
+    path = shutil.which(name)
+    if path:
+        return path
+
+    return sys.executable