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

cli_web/codewiki/__init__.py

@@ -0,0 +1,3 @@
+"""cli-web-codewiki — CLI for Google Code Wiki."""
+
+__version__ = "0.1.0"

cli_web/codewiki/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as: python -m cli_web.codewiki"""
+
+from .codewiki_cli import main
+
+if __name__ == "__main__":
+    main()

cli_web/codewiki/codewiki_cli.py

@@ -0,0 +1,142 @@
+"""cli-web-codewiki — CLI for Google Code Wiki.
+
+Browse Gemini-generated documentation for open source repositories,
+search for repos, explore wiki sections, and chat with Gemini.
+"""
+
+from __future__ import annotations
+
+import shlex
+import sys
+
+# Windows UTF-8 fix — must be before any output
+if sys.stdout.encoding and sys.stdout.encoding.lower() not in ("utf-8", "utf8"):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except AttributeError:
+        pass
+if sys.stderr.encoding and sys.stderr.encoding.lower() not in ("utf-8", "utf8"):
+    try:
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except AttributeError:
+        pass
+
+import click
+
+from .commands.chat import chat_group
+from .commands.repos import repos
+from .commands.wiki import wiki_group
+from .utils.repl_skin import ReplSkin
+
+_skin = ReplSkin("codewiki", version="0.1.0")
+
+
+@click.group(invoke_without_command=True)
+@click.version_option("0.1.0", prog_name="cli-web-codewiki")
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    hidden=True,
+    help="Output as JSON (pass to subcommands).",
+)
+@click.pass_context
+def cli(ctx: click.Context, as_json: bool) -> None:
+    """cli-web-codewiki — Browse AI-generated code documentation."""
+    ctx.ensure_object(dict)
+    ctx.obj["json"] = as_json
+    if ctx.invoked_subcommand is None:
+        _run_repl(ctx)
+
+
+cli.add_command(repos)
+cli.add_command(wiki_group, "wiki")
+cli.add_command(chat_group, "chat")
+
+
+def _print_repl_help() -> None:
+    """Print REPL help matching actual command surface."""
+    _skin.info("Available commands:")
+    print()
+    print("  repos featured                      List featured repositories")
+    print("  repos search <query>                Search repos by name")
+    print("    --limit N                           Max results (default 25)")
+    print("    --offset N                          Pagination offset")
+    print()
+    print("  wiki get <org/repo>                 Get full wiki content")
+    print("  wiki sections <org/repo>            List wiki sections (TOC)")
+    print("  wiki section <org/repo> <title>     Get a specific section")
+    print("  wiki download <org/repo>            Download wiki as .md files")
+    print("    -o <dir>                            Output directory")
+    print()
+    print("  chat ask <question> --repo <org/repo>")
+    print("                                      Ask Gemini about a repo")
+    print()
+    print("  All commands support --json for structured output.")
+    print()
+    print("  help / ?                            Show this help")
+    print("  quit / exit / q                     Exit REPL")
+    print()
+
+
+def _run_repl(ctx: click.Context) -> None:
+    """Enter interactive REPL mode."""
+    _skin.print_banner()
+    _skin.info("Type 'help' for available commands, 'quit' to exit.")
+    print()
+
+    pt_session = _skin.create_prompt_session()
+
+    while True:
+        try:
+            line = _skin.get_input(pt_session)
+        except (EOFError, KeyboardInterrupt):
+            _skin.print_goodbye()
+            sys.exit(0)
+
+        if not line:
+            continue
+        if line in ("quit", "exit", "q"):
+            _skin.print_goodbye()
+            sys.exit(0)
+        if line in ("help", "?"):
+            _print_repl_help()
+            continue
+
+        try:
+            args = shlex.split(line)
+        except ValueError as exc:
+            _skin.error(f"Parse error: {exc}")
+            continue
+
+        # Propagate --json if set at top level
+        repl_args = ["--json"] + args if ctx.obj.get("json") else args
+
+        try:
+            cli.main(args=repl_args, standalone_mode=False, prog_name="cli-web-codewiki")
+        except SystemExit:
+            pass
+        except click.UsageError as exc:
+            _skin.error(str(exc))
+        except Exception as exc:
+            _skin.error(str(exc))
+
+
+def main() -> None:
+    """Entry point for console_scripts."""
+    cli()
+
+
+# MCP server mode — exposes every command as an MCP tool over stdio.
+# Canonical adapter: cli-web-core/cli_web_core/mcp_server.py (vendored copy).
+from cli_web.codewiki import __version__ as _pkg_version  # noqa: E402
+from cli_web.codewiki.utils.doctor import register_doctor_command  # noqa: E402
+from cli_web.codewiki.utils.mcp_server import register_mcp_command  # noqa: E402
+
+register_mcp_command(cli, app_name="codewiki", version=_pkg_version)
+register_doctor_command(cli, app_name="codewiki", pkg="codewiki")
+
+
+if __name__ == "__main__":
+    main()

cli_web/codewiki/commands/chat.py

@@ -0,0 +1,46 @@
+"""Chat command — ask Gemini about a repository."""
+
+from __future__ import annotations
+
+import click
+
+from ..core.client import CodeWikiClient
+from ..utils.helpers import handle_errors
+from ..utils.output import print_json
+
+try:
+    from rich.console import Console
+    from rich.markdown import Markdown
+
+    _RICH_AVAILABLE = True
+except ImportError:
+    _RICH_AVAILABLE = False
+
+
+@click.group("chat")
+def chat_group():
+    """Ask Gemini questions about a repository."""
+
+
+@chat_group.command("ask")
+@click.argument("question")
+@click.option("--repo", required=True, help='Repository slug, e.g. "excalidraw/excalidraw".')
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def ask(question: str, repo: str, as_json: bool) -> None:
+    """Ask Gemini about a repository."""
+    with handle_errors(json_mode=as_json):
+        client = CodeWikiClient()
+        try:
+            response = client.chat(question=question, repo_slug=repo)
+        finally:
+            client.close()
+
+        if as_json:
+            print_json({"success": True, "data": response.to_dict()})
+        else:
+            header = f"Gemini — {repo}:"
+            click.echo(f"\n{header}\n")
+            if _RICH_AVAILABLE:
+                Console().print(Markdown(response.answer))
+            else:
+                click.echo(response.answer)

cli_web/codewiki/commands/repos.py

@@ -0,0 +1,90 @@
+"""Repository commands: featured, search."""
+
+from __future__ import annotations
+
+import click
+
+from ..core.client import CodeWikiClient
+from ..utils.helpers import handle_errors
+from ..utils.output import print_json
+
+_SEP = "\u2500"
+_SLUG_W = 34
+_STARS_W = 8
+_DESC_W = 60
+
+
+def _truncate(text: str, max_len: int) -> str:
+    if len(text) <= max_len:
+        return text
+    return text[: max_len - 3] + "..."
+
+
+def _format_stars(stars: int) -> str:
+    if stars >= 1_000:
+        return f"{stars / 1_000:.1f}k"
+    return str(stars)
+
+
+def _print_repo_table(repos) -> None:
+    header_slug = "Slug"
+    header_stars = "Stars"
+    header_desc = "Description"
+
+    click.echo(f"{header_slug:<{_SLUG_W}}  {header_stars:<{_STARS_W}} {header_desc}")
+    click.echo(_SEP * (_SLUG_W + 2 + _STARS_W + 1 + _DESC_W))
+
+    for repo in repos:
+        slug = _truncate(repo.slug, _SLUG_W)
+        stars = _format_stars(repo.stars)
+        desc = _truncate(repo.description, _DESC_W)
+        click.echo(f"{slug:<{_SLUG_W}}  {stars:<{_STARS_W}} {desc}")
+
+
+@click.group("repos")
+def repos():
+    """List and search repositories on Code Wiki."""
+    pass
+
+
+@repos.command("featured")
+@click.option("--json", "as_json", is_flag=True, default=False, help="Output as JSON.")
+def featured(as_json: bool) -> None:
+    """List featured repositories."""
+    with handle_errors(json_mode=as_json):
+        client = CodeWikiClient()
+        try:
+            result = client.featured_repos()
+        finally:
+            client.close()
+
+        if as_json:
+            print_json({"success": True, "data": [repo.to_dict() for repo in result]})
+        else:
+            if not result:
+                click.echo("No featured repositories found.")
+            else:
+                _print_repo_table(result)
+
+
+@repos.command("search")
+@click.argument("query")
+@click.option("--limit", default=25, show_default=True, help="Maximum number of results.")
+@click.option("--offset", default=0, show_default=True, help="Result offset for pagination.")
+@click.option("--json", "as_json", is_flag=True, default=False, help="Output as JSON.")
+def search(query: str, limit: int, offset: int, as_json: bool) -> None:
+    """Search repositories by QUERY."""
+    with handle_errors(json_mode=as_json):
+        client = CodeWikiClient()
+        try:
+            result = client.search_repos(query, limit=limit, offset=offset)
+        finally:
+            client.close()
+
+        if as_json:
+            print_json({"success": True, "data": [repo.to_dict() for repo in result]})
+        else:
+            if not result:
+                click.echo(f"No repositories found for '{query}'.")
+            else:
+                _print_repo_table(result)

cli_web/codewiki/commands/wiki.py

@@ -0,0 +1,267 @@
+"""Wiki command group — get wiki pages and sections for a repository."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import click
+
+from ..core.client import CodeWikiClient
+from ..core.exceptions import NotFoundError
+from ..utils.helpers import handle_errors
+from ..utils.output import print_json
+
+
+# Indent prefix per heading level (level 1 = no indent, level 2 = 2 spaces, etc.)
+def _indent(level: int) -> str:
+    if level <= 1:
+        return ""
+    return "  " * (level - 1)
+
+
+def _heading(level: int, title: str) -> str:
+    """Return a markdown-style heading for a given level."""
+    hashes = "#" * max(1, level + 1)
+    return f"{hashes} {title}"
+
+
+def _truncate(text: str, width: int = 50) -> str:
+    if len(text) <= width:
+        return text
+    return text[: width - 1] + "…"
+
+
+@click.group("wiki")
+def wiki_group():
+    """Get wiki pages and sections for a GitHub repository."""
+
+
+@wiki_group.command("get")
+@click.argument("repo")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def wiki_get(repo: str, as_json: bool) -> None:
+    """Get full wiki content for a repo (e.g. excalidraw/excalidraw)."""
+    with handle_errors(json_mode=as_json):
+        client = CodeWikiClient()
+        try:
+            wiki = client.get_wiki(repo)
+        finally:
+            client.close()
+
+        if as_json:
+            print_json({"success": True, "data": wiki.to_dict()})
+        else:
+            commit = wiki.repo.commit_hash or "unknown"
+            click.echo(f"\n{wiki.repo.slug}  @{commit}\n")
+            for section in wiki.sections:
+                heading = _heading(section.level, section.title)
+                click.echo(heading)
+                if section.content:
+                    click.echo(section.content)
+                click.echo()
+
+
+@wiki_group.command("sections")
+@click.argument("repo")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def wiki_sections(repo: str, as_json: bool) -> None:
+    """List wiki sections / table of contents for a repo."""
+    with handle_errors(json_mode=as_json):
+        client = CodeWikiClient()
+        try:
+            wiki = client.get_wiki(repo)
+        finally:
+            client.close()
+
+        if as_json:
+            print_json({"success": True, "data": [s.to_dict() for s in wiki.sections]})
+        else:
+            click.echo(f"\n{wiki.repo.slug} — {len(wiki.sections)} sections\n")
+
+            col_title = 45
+            col_desc = 52
+
+            header = f"  {'Section':<{col_title}}  {'Description':<{col_desc}}"
+            click.echo(header)
+            click.echo("  " + "-" * (col_title + col_desc + 2))
+
+            for section in wiki.sections:
+                indent = _indent(section.level)
+                display_title = indent + section.title
+                display_desc = _truncate(section.description, 50) if section.description else ""
+                click.echo(f"  {display_title:<{col_title}}  {display_desc:<{col_desc}}")
+
+            click.echo()
+
+
+@wiki_group.command("section")
+@click.argument("repo")
+@click.argument("title")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def wiki_section(repo: str, title: str, as_json: bool) -> None:
+    """Get content of a specific section by title (case-insensitive partial match)."""
+    with handle_errors(json_mode=as_json):
+        client = CodeWikiClient()
+        try:
+            wiki = client.get_wiki(repo)
+        finally:
+            client.close()
+
+        query = title.lower()
+        matches = [s for s in wiki.sections if query in s.title.lower()]
+
+        if not matches:
+            raise NotFoundError(f"No section matching '{title}' in {repo}")
+
+        if len(matches) > 1:
+            candidates = [s.title for s in matches]
+            if as_json:
+                print_json(
+                    {
+                        "error": True,
+                        "code": "AMBIGUOUS_MATCH",
+                        "message": f"Multiple sections match '{title}'",
+                        "candidates": candidates,
+                    }
+                )
+            else:
+                click.echo(
+                    f"Multiple sections match '{title}'. Please be more specific:\n", err=True
+                )
+                for s in matches:
+                    click.echo(f"  {_indent(s.level)}{s.title}", err=True)
+            raise SystemExit(1)
+
+        section = matches[0]
+
+        if as_json:
+            print_json({"success": True, "data": section.to_dict()})
+        else:
+            heading = _heading(section.level, section.title)
+            click.echo(f"\n{heading}\n")
+            if section.description:
+                click.echo(section.description)
+                click.echo()
+            if section.content:
+                click.echo(section.content)
+            click.echo()
+
+
+def _slugify(text: str) -> str:
+    """Convert a section title to a safe filename slug."""
+    s = text.lower().strip()
+    s = re.sub(r"[^\w\s-]", "", s)
+    s = re.sub(r"[\s_]+", "-", s)
+    s = re.sub(r"-+", "-", s).strip("-")
+    return s[:80] or "untitled"
+
+
+@wiki_group.command("download")
+@click.argument("repo")
+@click.option(
+    "--output", "-o", default=None, help="Output directory (default: <org>-<repo>-wiki/)."
+)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def wiki_download(repo: str, output: str | None, as_json: bool) -> None:
+    """Download full wiki as organized markdown files into a folder."""
+    with handle_errors(json_mode=as_json):
+        client = CodeWikiClient()
+        try:
+            wiki = client.get_wiki(repo)
+        finally:
+            client.close()
+
+        if not wiki.sections:
+            raise NotFoundError(f"No wiki content found for {repo}")
+
+        # Determine output directory
+        if output:
+            out_dir = Path(output)
+        else:
+            safe_name = repo.replace("/", "-")
+            out_dir = Path(f"{safe_name}-wiki")
+
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        # Determine chapter split level: use level 1 if there are multiple,
+        # otherwise split at level 2 (common for wikis with a single overview root)
+        level_1_count = sum(1 for s in wiki.sections if s.level == 1)
+        split_level = 1 if level_1_count > 1 else 2
+
+        # Group sections into chapters at the split level
+        chapters: list[tuple[int, str, list]] = []  # (index, title, sections)
+        current_chapter_title = None
+        current_sections: list = []
+        chapter_idx = 0
+
+        for sec in wiki.sections:
+            if sec.level <= split_level:
+                if current_chapter_title is not None:
+                    chapters.append((chapter_idx, current_chapter_title, current_sections))
+                    chapter_idx += 1
+                current_chapter_title = sec.title
+                current_sections = [sec]
+            else:
+                current_sections.append(sec)
+
+        if current_chapter_title is not None:
+            chapters.append((chapter_idx, current_chapter_title, current_sections))
+
+        # Write index.md
+        index_lines = [
+            f"# {wiki.repo.slug}",
+            "",
+            f"Commit: `{wiki.repo.commit_hash or 'unknown'}`",
+            f"Sections: {len(wiki.sections)}",
+            "",
+            "## Table of Contents",
+            "",
+        ]
+        files_written = []
+
+        for idx, chapter_title, sections in chapters:
+            filename = f"{idx:02d}-{_slugify(chapter_title)}.md"
+            index_lines.append(f"{idx + 1}. [{chapter_title}]({filename})")
+            files_written.append(filename)
+
+            # Write chapter file
+            chapter_path = out_dir / filename
+            lines = []
+            for sec in sections:
+                heading = "#" * max(1, sec.level)
+                lines.append(f"{heading} {sec.title}")
+                lines.append("")
+                if sec.description and sec.description != sec.content:
+                    lines.append(f"*{sec.description}*")
+                    lines.append("")
+                if sec.content:
+                    lines.append(sec.content)
+                    lines.append("")
+
+            chapter_path.write_text("\n".join(lines), encoding="utf-8")
+
+        index_path = out_dir / "index.md"
+        index_path.write_text("\n".join(index_lines) + "\n", encoding="utf-8")
+        files_written.insert(0, "index.md")
+
+        if as_json:
+            print_json(
+                {
+                    "success": True,
+                    "data": {
+                        "repo": repo,
+                        "output_dir": str(out_dir),
+                        "files": files_written,
+                        "chapters": len(chapters),
+                        "total_sections": len(wiki.sections),
+                    },
+                }
+            )
+        else:
+            click.echo(f"\nDownloaded wiki for {wiki.repo.slug} to {out_dir}/")
+            click.echo(f"  {len(chapters)} chapters, {len(wiki.sections)} sections\n")
+            click.echo("  Files:")
+            for f in files_written:
+                click.echo(f"    {f}")
+            click.echo()