cocoindex-code-plus 0.1.0__py3-none-any.whl

cocoindex_code_plus/cli.py

@@ -0,0 +1,384 @@
+# © 2025 CocoIndex Inc. All rights reserved.
+# SPDX-License-Identifier: LicenseRef-CocoIndex-Proprietary
+"""The ``ccx`` client CLI.
+
+Commands stay close to the CocoIndex Code open source edition, but talk to a
+remote query server over HTTP instead of a local daemon.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Callable
+from typing import TypeVar
+
+import httpx
+import typer
+
+from . import client, settings
+from ._version import __version__
+
+T = TypeVar("T")
+
+# Matches the namespace/repo path in a GitHub or GitLab remote URL (SSH or
+# HTTPS, optional trailing `.git`). The path may be nested for GitLab subgroups,
+# e.g. `git@gitlab.com:group/subgroup/project.git` -> `group/subgroup/project`;
+# `https://github.com/owner/repo` -> `owner/repo`.
+_REMOTE_RE = re.compile(r"(?:github|gitlab)\.com[:/](?P<path>.+?)(?:\.git)?/?$")
+
+
+def _parse_remote_url(url: str) -> str | None:
+    """Extract the ``<namespace>/<repo>`` path from a GitHub/GitLab remote URL,
+    or ``None`` if it isn't one. The server resolves this name to a ``repo_key``."""
+    match = _REMOTE_RE.search(url)
+    return match["path"] if match else None
+
+
+def _detect_local_repo() -> str | None:
+    """Return the ``<namespace>/<repo>`` of the CWD's ``origin`` remote (GitHub
+    or GitLab), or ``None`` if not in a git checkout / the remote isn't one of
+    those hosts."""
+    try:
+        proc = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=True,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return _parse_remote_url(proc.stdout.strip())
+
+
+app = typer.Typer(
+    name="ccx",
+    help="CocoIndex Code Plus — query indexed codebases from the command line.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def _load_env() -> None:
+    """Auto-load .env (non-overriding) before running any command."""
+    settings.load_env()
+
+
+@app.command()
+def status(
+    server: str | None = typer.Option(
+        None,
+        "--server",
+        help="Query server base URL (defaults to $CCX_SERVER_URL).",
+    ),
+) -> None:
+    """Check whether the query server is healthy."""
+    base_url = server or settings.server_url()
+    try:
+        result = client.health(base_url)
+    except httpx.HTTPError as exc:
+        typer.secho(f"Query server unreachable at {base_url}: {exc}", fg=typer.colors.RED)
+        raise typer.Exit(code=1) from exc
+
+    typer.secho(f"Query server: {result.status}", fg=typer.colors.GREEN)
+    typer.echo(f"  url:     {base_url}")
+    typer.echo(f"  version: {result.version}")
+    typer.echo(f"  uptime:  {result.uptime_seconds:.1f}s")
+
+
+def _error_detail(exc: httpx.HTTPStatusError) -> str:
+    """Pull the server's ``detail`` message out of an error response."""
+    try:
+        body = exc.response.json()
+    except ValueError:
+        return exc.response.text or str(exc)
+    detail = body.get("detail") if isinstance(body, dict) else None
+    return str(detail) if detail else str(exc)
+
+
+@app.command()
+def search(
+    query: list[str] = typer.Argument(..., help="Search query (words are joined)."),
+    top_k: int = typer.Option(5, "-k", "--top-k", help="Max results to return."),
+    repo: str | None = typer.Option(
+        None,
+        "--repo",
+        help="Restrict results to one indexed repo, as '<owner>/<repo>' or bare "
+        "'<repo>'. Default: auto-detect from the current git checkout.",
+    ),
+    all_repos: bool = typer.Option(
+        False,
+        "--all-repos",
+        help="Search across all indexed repos (disables repo auto-detection).",
+    ),
+    git_ref: str | None = typer.Option(
+        None,
+        "--git-ref",
+        help="Restrict results to one indexed git ref of the repo, qualified as "
+        "'heads/<branch>' or 'tags/<tag>' (requires a repo scope).",
+    ),
+    server: str | None = typer.Option(
+        None,
+        "--server",
+        help="Query server base URL (defaults to $CCX_SERVER_URL).",
+    ),
+) -> None:
+    """Semantic search across the indexed codebases.
+
+    By default this filters to the repo of the current git checkout (detected
+    from its ``origin`` GitHub remote). Pass ``--repo`` to target another, or
+    ``--all-repos`` to search everything.
+    """
+    if all_repos and repo is not None:
+        typer.secho("Pass either --repo or --all-repos, not both.", fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+    if all_repos:
+        selected_repo: str | None = None
+    elif repo is not None:
+        selected_repo = repo
+    else:
+        selected_repo = _detect_local_repo()
+        if selected_repo is not None:
+            typer.secho(
+                f"Filtering to {selected_repo} (use --all-repos to search everything).",
+                fg=typer.colors.BRIGHT_BLACK,
+                err=True,
+            )
+        else:
+            typer.secho(
+                "No GitHub repo detected in the current directory; searching all "
+                "indexed repos (use --repo <owner>/<repo> to scope).",
+                fg=typer.colors.BRIGHT_BLACK,
+                err=True,
+            )
+
+    if git_ref is not None and selected_repo is None:
+        typer.secho(
+            "--git-ref requires a repo scope; pass --repo <owner>/<repo> "
+            "(not available with --all-repos).",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    base_url = server or settings.server_url()
+    query_text = " ".join(query)
+    try:
+        result = client.search(
+            query_text,
+            top_k=top_k,
+            repo=selected_repo,
+            git_ref=git_ref,
+            base_url=base_url,
+        )
+    except httpx.HTTPStatusError as exc:
+        typer.secho(
+            f"Search failed (HTTP {exc.response.status_code}): {_error_detail(exc)}",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1) from exc
+    except httpx.HTTPError as exc:
+        typer.secho(f"Query server unreachable at {base_url}: {exc}", fg=typer.colors.RED)
+        raise typer.Exit(code=1) from exc
+
+    if not result.results:
+        typer.echo("No results.")
+        return
+
+    for item in result.results:
+        typer.secho(
+            f"[{item.score:.3f}] {item.repo_key} {item.filename} "
+            f"(L{item.start_line}-L{item.end_line})",
+            fg=typer.colors.CYAN,
+        )
+        typer.echo(item.code.rstrip("\n"))
+        typer.echo("---")
+
+
+@app.command()
+def grep(
+    pattern: str = typer.Argument(
+        ...,
+        help=r"Structural pattern matched against the AST (not text). The '\' sigil "
+        r"marks metavariables, e.g. 'def \NAME(\(ARGS*\)):' or 'foo(\X)'.",
+    ),
+    language: str = typer.Option(
+        ..., "-l", "--language", help="Source language to parse + match (e.g. python, rust, c++)."
+    ),
+    git_ref: str = typer.Option(
+        ..., "--git-ref", help="Indexed git ref, qualified as 'heads/<branch>' or 'tags/<tag>'."
+    ),
+    repo: str | None = typer.Option(
+        None, "--repo", help="Indexed repo (default: auto-detect from the git checkout)."
+    ),
+    paths: list[str] = typer.Option(
+        None, "--path", help="Restrict to files matching this glob (repeatable, e.g. 'src/*.py')."
+    ),
+    limit: int = typer.Option(100, "-k", "--limit", help="Max matches to return."),
+    offset: int = typer.Option(0, "--offset", help="Skip this many matches (pagination)."),
+    server: str | None = typer.Option(None, "--server", help="Query server base URL."),
+) -> None:
+    """AST-based structural grep over an indexed repo at a given ref.
+
+    The pattern is parsed and matched against the code's syntax tree, so
+    ``foo(\\X)`` matches calls to ``foo`` regardless of formatting and never matches
+    the text inside comments or strings.
+    """
+    base_url = server or settings.server_url()
+    result = _run(
+        base_url,
+        lambda: client.grep(
+            pattern=pattern,
+            language=language,
+            repo=_require_repo(repo),
+            git_ref=git_ref,
+            paths=list(paths or []),
+            limit=limit,
+            offset=offset,
+            base_url=base_url,
+        ),
+    )
+    if not result.matches:
+        typer.echo("No matches.")
+        return
+    for m in result.matches:
+        header = f"{m.filename}:{m.start_line}-{m.end_line} [{m.kind}]"
+        typer.secho(header, fg=typer.colors.CYAN)
+        if m.captures:
+            caps = "  ".join(f"{name}={text!r}" for name, text in sorted(m.captures.items()))
+            typer.secho(f"  captures: {caps}", fg=typer.colors.BRIGHT_BLACK)
+        typer.echo(m.code.rstrip("\n"))
+        typer.echo("---")
+    if result.truncated:
+        typer.secho(
+            f"… more matches past {offset + len(result.matches)}; page with --offset/--limit.",
+            fg=typer.colors.BRIGHT_BLACK,
+            err=True,
+        )
+
+
+def _require_repo(repo: str | None) -> str:
+    """Resolve the repo for a single-repo command: ``--repo`` if given, else the
+    current git checkout's ``origin`` remote. Exits 1 with guidance if neither."""
+    selected = repo if repo is not None else _detect_local_repo()
+    if selected is None:
+        typer.secho(
+            "No repo specified and none detected from the current git checkout; "
+            "pass --repo <owner>/<repo>.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+    return selected
+
+
+def _run(base_url: str, call: Callable[[], T]) -> T:
+    """Run a ``client`` request, mapping HTTP/transport errors to a clean CLI exit
+    (mirrors the ``search`` command's error handling)."""
+    try:
+        return call()
+    except httpx.HTTPStatusError as exc:
+        typer.secho(
+            f"Request failed (HTTP {exc.response.status_code}): {_error_detail(exc)}",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1) from exc
+    except httpx.HTTPError as exc:
+        typer.secho(f"Query server unreachable at {base_url}: {exc}", fg=typer.colors.RED)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command(name="read-file")
+def read_file(
+    path: str = typer.Argument(..., help="Repo-relative file path to read."),
+    git_ref: str = typer.Option(
+        ..., "--git-ref", help="Indexed git ref, qualified as 'heads/<branch>' or 'tags/<tag>'."
+    ),
+    repo: str | None = typer.Option(
+        None, "--repo", help="Indexed repo (default: auto-detect from the git checkout)."
+    ),
+    offset: int = typer.Option(1, "--offset", help="1-based first line to print."),
+    limit: int | None = typer.Option(None, "--limit", help="Number of lines (default: to EOF)."),
+    server: str | None = typer.Option(None, "--server", help="Query server base URL."),
+) -> None:
+    """Print a file's contents as they exist in a given ref."""
+    base_url = server or settings.server_url()
+    result = _run(
+        base_url,
+        lambda: client.read_file(
+            repo=_require_repo(repo),
+            git_ref=git_ref,
+            path=path,
+            offset=offset,
+            limit=limit,
+            base_url=base_url,
+        ),
+    )
+    typer.echo(result.content, nl=False)
+
+
+@app.command(name="find-files")
+def find_files(
+    patterns: list[str] = typer.Argument(
+        None, help="Path globs (e.g. 'src/*.py'); none lists all files."
+    ),
+    git_ref: str = typer.Option(..., "--git-ref", help="Indexed git ref (e.g. 'heads/main')."),
+    repo: str | None = typer.Option(
+        None, "--repo", help="Indexed repo (default: auto-detect from the git checkout)."
+    ),
+    case: str = typer.Option("smart", "--case", help="smart | sensitive | insensitive."),
+    limit: int = typer.Option(100, "--limit", help="Max paths to return."),
+    offset: int = typer.Option(0, "--offset", help="Skip this many matches (pagination)."),
+    server: str | None = typer.Option(None, "--server", help="Query server base URL."),
+) -> None:
+    """List indexed files in a ref, optionally filtered by glob patterns."""
+    base_url = server or settings.server_url()
+    result = _run(
+        base_url,
+        lambda: client.find_files(
+            repo=_require_repo(repo),
+            git_ref=git_ref,
+            patterns=list(patterns or []),
+            case=case,
+            limit=limit,
+            offset=offset,
+            base_url=base_url,
+        ),
+    )
+    for p in result.paths:
+        typer.echo(p)
+    shown = len(result.paths)
+    total = result.total
+    if total > shown + offset:
+        typer.secho(
+            f"… {total} total (showing {shown}); page with --offset/--limit.",
+            fg=typer.colors.BRIGHT_BLACK,
+            err=True,
+        )
+
+
+@app.command()
+def repositories(
+    repo: str | None = typer.Argument(
+        None, help="Indexed repo (default: auto-detect from the git checkout)."
+    ),
+    server: str | None = typer.Option(None, "--server", help="Query server base URL."),
+) -> None:
+    """List a repo's indexed git refs and the commit SHA indexed for each."""
+    base_url = server or settings.server_url()
+    result = _run(base_url, lambda: client.repositories(_require_repo(repo), base_url=base_url))
+    typer.secho(result.repo_key, fg=typer.colors.CYAN)
+    for ref in result.refs:
+        typer.echo(f"  {ref.git_ref}\t{ref.commit_sha}")
+    if not result.refs:
+        typer.echo("  (no indexed refs)")
+
+
+@app.command()
+def version() -> None:
+    """Print the CLI version."""
+    typer.echo(__version__)
+
+
+if __name__ == "__main__":
+    app()

cocoindex_code_plus/client.py

@@ -0,0 +1,208 @@
+# © 2025 CocoIndex Inc. All rights reserved.
+# SPDX-License-Identifier: LicenseRef-CocoIndex-Proprietary
+"""Client-side helpers for talking to the query server over HTTP.
+
+The CLI uses these functions; each opens its own short-lived HTTP request, so
+there is no persistent client object to manage.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import httpx
+
+from . import settings
+from .protocol import (
+    FIND_FILES_PATH,
+    GREP_PATH,
+    READ_FILE_PATH,
+    REPOSITORIES_PATH,
+    SEMANTIC_SEARCH_PATH,
+    FindFilesResponse,
+    GrepResponse,
+    HealthResponse,
+    ReadFileResponse,
+    RepositoriesResponse,
+    SearchResponse,
+)
+
+DEFAULT_TIMEOUT = 10.0
+# Searching embeds the query and hits the database, so allow a bit more time.
+SEARCH_TIMEOUT = 30.0
+
+
+def _auth_headers() -> dict[str, str]:
+    """``Authorization: Bearer`` header when a token is configured, else empty.
+
+    The token comes from ``CCX_API_TOKEN`` (see ``settings.api_token``). Sending
+    it is harmless against a ``none``-mode server and required by an
+    ``apiKey``-mode one; ``/health`` is auth-exempt but carrying the header there
+    too keeps one code path.
+    """
+    token = settings.api_token()
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+
+def health(base_url: str | None = None) -> HealthResponse:
+    """Query the server's health endpoint.
+
+    Raises ``httpx.HTTPError`` if the server is unreachable or returns a
+    non-2xx status.
+    """
+    url = (base_url or settings.server_url()).rstrip("/")
+    resp = httpx.get(f"{url}/health", timeout=DEFAULT_TIMEOUT, headers=_auth_headers())
+    resp.raise_for_status()
+    return HealthResponse.model_validate(resp.json())
+
+
+def search(
+    query: str,
+    *,
+    top_k: int = 5,
+    offset: int = 0,
+    repo: str | None = None,
+    git_ref: str | None = None,
+    paths: list[str] | None = None,
+    base_url: str | None = None,
+) -> SearchResponse:
+    """Run a semantic search against the query server.
+
+    ``repo`` names one indexed repo as ``<owner>/<repo>`` or bare ``<repo>``;
+    ``None`` searches across all indexed repos. ``offset`` paginates the ranked
+    results; ``paths`` (globs) scopes to matching filenames.
+
+    Raises ``httpx.HTTPError`` if the server is unreachable or returns a
+    non-2xx status (e.g. 503 when the index hasn't been built yet).
+    """
+    url = (base_url or settings.server_url()).rstrip("/")
+    payload: dict[str, object] = {"query": query, "top_k": top_k, "offset": offset}
+    if repo is not None:
+        payload["repo"] = repo
+    if git_ref is not None:
+        payload["git_ref"] = git_ref
+    if paths:
+        payload["paths"] = paths
+    resp = httpx.post(
+        f"{url}{SEMANTIC_SEARCH_PATH}",
+        json=payload,
+        timeout=SEARCH_TIMEOUT,
+        headers=_auth_headers(),
+    )
+    resp.raise_for_status()
+    return SearchResponse.model_validate(resp.json())
+
+
+def grep(
+    *,
+    pattern: str,
+    language: str,
+    repo: str,
+    git_ref: str,
+    paths: list[str] | None = None,
+    limit: int = 100,
+    offset: int = 0,
+    base_url: str | None = None,
+) -> GrepResponse:
+    """Run an AST structural grep against the query server.
+
+    ``pattern`` is a by-example structural pattern (``\\`` sigil for metavariables);
+    ``language`` is the source language to parse + match. Matching is scoped to
+    ``git_ref`` of ``repo``; ``paths`` (globs) narrows the file set. Raises
+    ``httpx.HTTPError`` on an unreachable server or a non-2xx status (400 bad
+    pattern / unknown repo, 503 grep unavailable or index not built yet).
+    """
+    url = (base_url or settings.server_url()).rstrip("/")
+    payload: dict[str, object] = {
+        "pattern": pattern,
+        "language": language,
+        "repo": repo,
+        "git_ref": git_ref,
+        "limit": limit,
+        "offset": offset,
+    }
+    if paths:
+        payload["paths"] = paths
+    resp = httpx.post(
+        f"{url}{GREP_PATH}", json=payload, timeout=SEARCH_TIMEOUT, headers=_auth_headers()
+    )
+    resp.raise_for_status()
+    return GrepResponse.model_validate(resp.json())
+
+
+def read_file(
+    *,
+    repo: str,
+    git_ref: str,
+    path: str,
+    offset: int = 1,
+    limit: int | None = None,
+    base_url: str | None = None,
+) -> ReadFileResponse:
+    """Read a line window of ``path`` as it exists in ``git_ref`` of ``repo``.
+
+    ``offset`` is the 1-based first line; ``limit`` the number of lines (``None``
+    → to end of file). Raises ``httpx.HTTPError`` on an unreachable server or a
+    non-2xx status (400 unknown repo / bad range, 404 path not in ref, 503 index
+    not built yet).
+    """
+    url = (base_url or settings.server_url()).rstrip("/")
+    payload: dict[str, object] = {"repo": repo, "git_ref": git_ref, "path": path, "offset": offset}
+    if limit is not None:
+        payload["limit"] = limit
+    resp = httpx.post(
+        f"{url}{READ_FILE_PATH}", json=payload, timeout=DEFAULT_TIMEOUT, headers=_auth_headers()
+    )
+    resp.raise_for_status()
+    return ReadFileResponse.model_validate(resp.json())
+
+
+def find_files(
+    *,
+    repo: str,
+    git_ref: str,
+    patterns: list[str] | None = None,
+    case: str = "smart",
+    limit: int = 100,
+    offset: int = 0,
+    base_url: str | None = None,
+) -> FindFilesResponse:
+    """List files in ``git_ref`` of ``repo`` matching any glob in ``patterns``.
+
+    Empty ``patterns`` lists all files. Raises ``httpx.HTTPError`` on an
+    unreachable server or a non-2xx status (400 unknown repo / bad args, 503
+    index not built yet).
+    """
+    url = (base_url or settings.server_url()).rstrip("/")
+    payload: dict[str, object] = {
+        "repo": repo,
+        "git_ref": git_ref,
+        "patterns": patterns or [],
+        "case": case,
+        "limit": limit,
+        "offset": offset,
+    }
+    resp = httpx.post(
+        f"{url}{FIND_FILES_PATH}", json=payload, timeout=DEFAULT_TIMEOUT, headers=_auth_headers()
+    )
+    resp.raise_for_status()
+    return FindFilesResponse.model_validate(resp.json())
+
+
+def repositories(repo: str, *, base_url: str | None = None) -> RepositoriesResponse:
+    """List a repo's indexed refs and their HEAD commit SHAs.
+
+    ``repo`` is ``<owner>/<repo>``, a bare ``<repo>``, or the exact ``repo_key``
+    (slashes preserved for a GitLab nested namespace). Raises ``httpx.HTTPError``
+    on an unreachable server or a non-2xx status (400 unknown repo, 503 index not
+    built yet).
+    """
+    url = (base_url or settings.server_url()).rstrip("/")
+    # Keep slashes — the route captures the rest of the path as the repo id.
+    resp = httpx.get(
+        f"{url}{REPOSITORIES_PATH}/{quote(repo, safe='/')}",
+        timeout=DEFAULT_TIMEOUT,
+        headers=_auth_headers(),
+    )
+    resp.raise_for_status()
+    return RepositoriesResponse.model_validate(resp.json())

cocoindex_code_plus-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: cocoindex-code-plus
+Version: 0.1.0
+Summary: Client CLI for CocoIndex Code Plus: query indexed codebases from your workstation.
+License-Expression: LicenseRef-CocoIndex-Proprietary
+Requires-Python: >=3.11
+Requires-Dist: cocoindex-code-plus-common
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# cocoindex-code-plus (CLI)
+
+The `ccx` client CLI for CocoIndex Code Plus. See the repo root README.

cocoindex_code_plus-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+cocoindex_code_plus/cli.py,sha256=qNj5ebJZ8Mkz7IZ9Paf1vvL_AaLkOEneoWNe1dAasdA,13517
+cocoindex_code_plus/client.py,sha256=CBYFbPm3YJuR5MI132DC3Nkj4kcIUzZkJxKRhLZQ_IE,6818
+cocoindex_code_plus-0.1.0.dist-info/METADATA,sha256=Tjf4eFLotcWRdNTVFZC4S0prgfcRdmcL5BqV87prlHI,474
+cocoindex_code_plus-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cocoindex_code_plus-0.1.0.dist-info/entry_points.txt,sha256=osXgNNJtf-AaZGSdNL8vbfCPbMqrA8i-UVuDdii4fqs,52
+cocoindex_code_plus-0.1.0.dist-info/RECORD,,

cocoindex_code_plus-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cocoindex_code_plus-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ccx = cocoindex_code_plus.cli:app