eightstatecli 0.4.0__py3-none-any.whl

escli/commands/docs.py

@@ -0,0 +1,354 @@
+"""
+escli docs — library documentation search via Context7 API.
+
+Usage:
+  escli docs search <library>              Search for libraries
+  escli docs get <library> <query>         Resolve + fetch docs (one-shot)
+  escli docs fetch <library-id> <query>    Fetch docs by library ID
+
+Flags:
+  --tokens N     Max tokens to return
+  --page N       Page number (1-10)
+  --topic T      Focus on specific topic
+  --format F     Output format: auto|text|json|markdown
+  --refresh      Bypass cache
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import pathlib
+import sys
+import time
+
+from ..services.credentials import get_key_for_service, report_key
+
+CTX7_API = "https://context7.com/api"
+CACHE_DIR = pathlib.Path(os.environ.get("ESCLI_CACHE_DIR", pathlib.Path.home() / ".escli" / "cache"))
+CACHE_TTL_SEARCH = 86400    # 24h
+CACHE_TTL_RESOLVE = 604800  # 7d
+CACHE_TTL_DOCS = 86400      # 24h
+
+
+# ── Cache ────────────────────────────────────────────────────────
+
+def _cache_path(layer: str, key: str) -> pathlib.Path:
+    h = hashlib.sha256(key.encode()).hexdigest()
+    return CACHE_DIR / layer / f"{h}.json"
+
+
+def _cache_read(layer: str, key: str, ttl: int) -> dict | None:
+    path = _cache_path(layer, key)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+        if time.time() > data.get("expires_at", 0):
+            path.unlink(missing_ok=True)
+            return None
+        return data.get("payload")
+    except (json.JSONDecodeError, OSError):
+        path.unlink(missing_ok=True)
+        return None
+
+
+def _cache_write(layer: str, key: str, payload: dict, ttl: int):
+    path = _cache_path(layer, key)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    envelope = {
+        "created_at": time.time(),
+        "expires_at": time.time() + ttl,
+        "payload": payload,
+    }
+    path.write_text(json.dumps(envelope))
+
+
+# ── HTTP ─────────────────────────────────────────────────────────
+
+def _get_api_key() -> str | None:
+    return get_key_for_service("context7", "CONTEXT7_API_KEY")
+
+
+def _request(url: str, api_key: str | None = None) -> dict:
+    import httpx
+    headers = {"User-Agent": "escli-docs/1.0", "X-Context7-Source": "cli"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    resp = httpx.get(url, headers=headers, timeout=30, follow_redirects=True)
+
+    # Report rate state back to gate
+    if api_key:
+        remaining = resp.headers.get("ratelimit-remaining")
+        limit = resp.headers.get("ratelimit-limit")
+        reset = resp.headers.get("ratelimit-reset")
+        tier = resp.headers.get("context7-quota-tier")
+        report_key(
+            "context7",
+            api_key[-8:],
+            resp.status_code,
+            remaining=int(remaining) if remaining else None,
+            limit=int(limit) if limit else None,
+            reset=reset,
+            tier=tier,
+        )
+
+    if resp.status_code == 429:
+        print("  ✗ rate limited. try again later.", file=sys.stderr)
+        sys.exit(1)
+    if resp.status_code == 404:
+        return {"_status": 404}
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ── Commands ─────────────────────────────────────────────────────
+
+def cmd_search(args):
+    """Search for libraries by name."""
+    import urllib.parse
+    name = args.library_name
+    query = getattr(args, "query", None) or name
+    refresh = getattr(args, "refresh", False)
+    limit = getattr(args, "limit", 10) or 10
+
+    cache_key = f"search:{name.lower()}:{query.lower()}"
+    if not refresh:
+        cached = _cache_read("search", cache_key, CACHE_TTL_SEARCH)
+        if cached:
+            _print_search(cached, args, from_cache=True)
+            return 0
+
+    api_key = _get_api_key()
+    url = f"{CTX7_API}/v2/libs/search?libraryName={urllib.parse.quote(name)}&query={urllib.parse.quote(query)}"
+    data = _request(url, api_key)
+
+    if data.get("_status") == 404:
+        if args.json:
+            print(json.dumps({"success": False, "error": f"no libraries found for: {name}"}))
+        else:
+            print(f"  ✗ no libraries found for: {name}", file=sys.stderr)
+        return 1
+
+    _cache_write("search", cache_key, data, CACHE_TTL_SEARCH)
+
+    # Client-side limit
+    if "results" in data:
+        data["results"] = data["results"][:limit]
+
+    _print_search(data, args)
+    return 0
+
+
+def _print_search(data, args, from_cache=False):
+    results = data.get("results", [])
+    if args.json:
+        print(json.dumps({"success": True, "cached": from_cache, "results": results, "count": len(results)}))
+        return
+
+    if not results:
+        print("  No results found.", file=sys.stderr)
+        return
+
+    cache_label = " (cached)" if from_cache else ""
+    if not args.quiet:
+        print(f"\n  Search results{cache_label}:\n", file=sys.stderr)
+        for r in results:
+            state = r.get("state", "")
+            stars = r.get("stars", "")
+            print(f"  {r.get('id', ''):<40} {r.get('title', '')}", file=sys.stderr)
+            print(f"    state={state}  stars={stars}  {r.get('description', '')[:80]}", file=sys.stderr)
+        print(file=sys.stderr)
+
+    # Pipe-friendly: TSV to stdout
+    if args.quiet:
+        for r in results:
+            print(f"{r.get('id', '')}\t{r.get('title', '')}\t{r.get('state', '')}")
+
+
+def cmd_get(args):
+    """One-shot: resolve library name to ID, then fetch docs."""
+    import urllib.parse
+    name = args.library_name
+    query = args.query
+    refresh = getattr(args, "refresh", False)
+
+    # Resolve
+    resolve_key = f"resolve:{name.lower()}"
+    library_id = None
+    if not refresh:
+        cached = _cache_read("resolve", resolve_key, CACHE_TTL_RESOLVE)
+        if cached:
+            library_id = cached.get("id")
+
+    if not library_id:
+        api_key = _get_api_key()
+        url = f"{CTX7_API}/v2/libs/search?libraryName={urllib.parse.quote(name)}&query={urllib.parse.quote(query)}"
+        data = _request(url, api_key)
+
+        if data.get("_status") == 404:
+            if args.json:
+                print(json.dumps({"success": False, "error": f"no libraries found for: {name}"}))
+            else:
+                print(f"  ✗ no libraries found for: {name}", file=sys.stderr)
+            return 1
+
+        results = data.get("results", [])
+        finalized = [r for r in results if r.get("state") == "finalized"]
+        pick = finalized[0] if finalized else (results[0] if results else None)
+
+        if not pick:
+            if args.json:
+                print(json.dumps({"success": False, "error": f"no results for: {name}"}))
+            else:
+                print(f"  ✗ no results for: {name}", file=sys.stderr)
+            return 1
+
+        library_id = pick["id"]
+        _cache_write("resolve", resolve_key, {"id": library_id, "name": name}, CACHE_TTL_RESOLVE)
+
+    if not args.quiet:
+        print(f"  → resolved: {library_id}", file=sys.stderr)
+
+    # Fetch docs
+    return _fetch_docs(library_id, query, args)
+
+
+def cmd_fetch(args):
+    """Fetch docs directly by library ID."""
+    return _fetch_docs(args.library_id, args.query, args)
+
+
+def _fetch_docs(library_id: str, query: str, args) -> int:
+    import urllib.parse
+    tokens = getattr(args, "tokens", None)
+    page = getattr(args, "page", None)
+    topic = getattr(args, "topic", None)
+    refresh = getattr(args, "refresh", False)
+
+    cache_key = f"docs:{library_id}:{query}:{tokens}:{page}:{topic}"
+    if not refresh:
+        cached = _cache_read("docs", cache_key, CACHE_TTL_DOCS)
+        if cached:
+            _print_docs(cached, args, library_id, query, from_cache=True)
+            return 0
+
+    api_key = _get_api_key()
+    url = f"{CTX7_API}/v2/context?libraryId={urllib.parse.quote(library_id)}&query={urllib.parse.quote(query)}&type=txt"
+
+    if tokens:
+        url += f"&tokens={tokens}"
+    if page:
+        url += f"&page={page}"
+    if topic:
+        url += f"&topic={urllib.parse.quote(topic)}"
+
+    resp = _request_raw(url, api_key)
+
+    if resp.status_code == 404:
+        if args.json:
+            print(json.dumps({"success": False, "error": f"library not found: {library_id}"}))
+        else:
+            print(f"  ✗ library not found: {library_id}", file=sys.stderr)
+        return 1
+
+    body = resp.text
+    _cache_write("docs", cache_key, {"body": body}, CACHE_TTL_DOCS)
+    _print_docs({"body": body}, args, library_id, query)
+    return 0
+
+
+def _request_raw(url: str, api_key: str | None = None):
+    import httpx
+    headers = {"User-Agent": "escli-docs/1.0", "X-Context7-Source": "cli"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    resp = httpx.get(url, headers=headers, timeout=30, follow_redirects=True)
+
+    if api_key:
+        remaining = resp.headers.get("ratelimit-remaining")
+        limit = resp.headers.get("ratelimit-limit")
+        reset = resp.headers.get("ratelimit-reset")
+        tier = resp.headers.get("context7-quota-tier")
+        report_key(
+            "context7", api_key[-8:], resp.status_code,
+            remaining=int(remaining) if remaining else None,
+            limit=int(limit) if limit else None,
+            reset=reset, tier=tier,
+        )
+
+    if resp.status_code == 429:
+        print("  ✗ rate limited. try again later.", file=sys.stderr)
+        sys.exit(1)
+
+    return resp
+
+
+def _print_docs(data, args, library_id, query, from_cache=False):
+    body = data.get("body", "")
+    if args.json:
+        print(json.dumps({
+            "success": True,
+            "cached": from_cache,
+            "library_id": library_id,
+            "query": query,
+            "content": body,
+        }))
+    else:
+        print(body)
+
+
+# ── Parser ───────────────────────────────────────────────────────
+
+def register(subparsers):
+    """Register the docs subcommand group."""
+    F = argparse.RawDescriptionHelpFormatter
+
+    docs_p = subparsers.add_parser(
+        "docs", aliases=["d"], help="Library documentation search (Context7)",
+        formatter_class=F,
+        epilog="""subcommands:
+  search <library>                Search for libraries
+  get <library> <query>           Resolve + fetch docs (one-shot)
+  fetch <library-id> <query>      Fetch docs by library ID
+
+examples:
+  escli docs search react
+  escli docs get next.js "app router middleware"
+  escli docs get react "useEffect cleanup" --tokens 5000
+  escli --json --quiet docs get express "error handling"
+""")
+
+    docs_subs = docs_p.add_subparsers(dest="docs_command", metavar="subcommand")
+
+    # search
+    search_p = docs_subs.add_parser("search", aliases=["s"], help="Search for libraries")
+    search_p.add_argument("library_name", help="Library name to search for")
+    search_p.add_argument("query", nargs="?", default=None, help="Optional search query")
+    search_p.add_argument("--limit", type=int, default=10, help="Limit results (default: 10)")
+    search_p.add_argument("--refresh", action="store_true", help="Bypass cache")
+    search_p.set_defaults(func=cmd_search)
+
+    # get (one-shot: resolve + fetch)
+    get_p = docs_subs.add_parser("get", aliases=["g"], help="Resolve + fetch docs")
+    get_p.add_argument("library_name", help="Library name")
+    get_p.add_argument("query", help="Documentation query")
+    get_p.add_argument("--tokens", type=int, default=None, help="Max tokens to return")
+    get_p.add_argument("--page", type=int, default=None, help="Page number (1-10)")
+    get_p.add_argument("--topic", default=None, help="Focus on specific topic")
+    get_p.add_argument("--refresh", action="store_true", help="Bypass cache")
+    get_p.set_defaults(func=cmd_get)
+
+    # fetch (by library ID)
+    fetch_p = docs_subs.add_parser("fetch", aliases=["f"], help="Fetch docs by library ID")
+    fetch_p.add_argument("library_id", help="Library ID (e.g. /facebook/react)")
+    fetch_p.add_argument("query", help="Documentation query")
+    fetch_p.add_argument("--tokens", type=int, default=None, help="Max tokens to return")
+    fetch_p.add_argument("--page", type=int, default=None, help="Page number (1-10)")
+    fetch_p.add_argument("--topic", default=None, help="Focus on specific topic")
+    fetch_p.add_argument("--refresh", action="store_true", help="Bypass cache")
+    fetch_p.set_defaults(func=cmd_fetch)
+
+    return docs_p