@flydocs/cli 0.6.0-alpha.2 → 0.6.0-alpha.20

package/template/.claude/skills/flydocs-context7/SKILL.md

@@ -1,105 +0,0 @@
----
-name: flydocs-context7
-description: |
-  Up-to-date library documentation via Context7 API. Use proactively when
-  working with external libraries, frameworks, or packages. Replaces MCP
-  with direct API scripts — no server, no runtime dependency.
-triggers:
-  - context7
-  - library docs
-  - documentation lookup
-  - framework docs
-  - package docs
-  - API reference
-  - how to use
----
-
-# Context7 Documentation Lookup
-
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
-library usage. Search for up-to-date docs before writing code based on
-training data alone.
-
-## Key Rules
-
-1. **Proactive invocation** -- When working with ANY external library or
-   framework, search for docs first before writing code based on training data.
-2. **Search then fetch** -- Always resolve the library ID via `search` before
-   fetching docs with `docs`.
-3. **Session cache awareness** -- Do not re-fetch docs for the same
-   library+query within a single session.
-4. **Graceful degradation** -- If rate-limited (429) or offline, note the
-   limitation and proceed with training knowledge.
-5. **Stdlib-only Python** -- No external dependencies in the script.
-6. **Token budget** -- Default 5,000 tokens per fetch to avoid context bloat.
-
-## Script Catalog
-
-All scripts: `python3 .claude/skills/flydocs-context7/scripts/<script>`
-
-| Script        | Usage                       | Output                                           |
-| ------------- | --------------------------- | ------------------------------------------------ |
-| `context7.py` | `search <library> [query]`  | JSON: library matches with id, name, description |
-| `context7.py` | `docs <library_id> <query>` | Text: relevant documentation snippets            |
-
-Options: `--type txt|json`, `--tokens N` (default 5000)
-
-## When to Use
-
-- Before implementing code that uses an external library
-- When the user asks about library APIs, patterns, or best practices
-- When encountering unfamiliar library methods or configuration
-- When upgrading dependencies and needing current API docs
-- When debugging library-specific issues
-
-## When NOT to Use
-
-- For project-internal code (use knowledge base and context graph instead)
-- For general programming concepts (training knowledge is sufficient)
-- When already fetched docs for the same library in this session
-
-## API Key (Optional)
-
-- Works without a key (anonymous, ~1,000 calls/month)
-- For higher limits, add `CONTEXT7_API_KEY=ctx7sk-xxx` to `.env`
-- Free key available at context7.com/dashboard
-
-## Example Usage
-
-```bash
-# Find the React library
-python3 .claude/skills/flydocs-context7/scripts/context7.py search "react" "hooks"
-
-# Fetch docs for React hooks
-python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/facebook/react" "useState useEffect hooks"
-
-# Get Next.js App Router docs
-python3 .claude/skills/flydocs-context7/scripts/context7.py search "next.js"
-python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/vercel/next.js" "app router middleware"
-
-# Fetch with custom token budget
-python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/expressjs/express" "routing middleware" --tokens 8000
-
-# Get output as JSON
-python3 .claude/skills/flydocs-context7/scripts/context7.py search "prisma" --type json
-```
-
-## Typical Workflow
-
-1. **Identify the library** you need docs for (from import statements,
-   `package.json`, or the task at hand).
-2. **Search** to resolve the library ID:
-   ```bash
-   python3 .claude/skills/flydocs-context7/scripts/context7.py search "react-hook-form"
-   ```
-3. **Fetch docs** for the specific topic:
-   ```bash
-   python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/react-hook-form/react-hook-form" "useForm validation"
-   ```
-4. **Apply** the retrieved documentation to your implementation.
-5. **Do not re-fetch** for the same library+query later in the session.
-
-## Related Skills
-
-- `flydocs-context-graph` -- Project-internal knowledge navigation
-- `flydocs-workflow` -- Development lifecycle and issue operations

package/template/.claude/skills/flydocs-context7/cursor-rule.mdc

@@ -1,49 +0,0 @@
----
-description: Context7 — look up library and framework documentation before writing code
-alwaysApply: true
----
-
-<!-- Condensed from SKILL.md — update both when changing patterns -->
-
-# FlyDocs Context7
-
-Proactively look up library documentation via Context7 scripts before writing
-code that uses external packages. Do not rely on training data for API details.
-
-## When to Use
-
-- Installing or importing a library you haven't used in this session
-- Unsure about API signatures, configuration options, or return types
-- Framework-specific patterns (routing, data fetching, middleware, hooks)
-- Resolving version-specific behavior or breaking changes
-
-## Scripts
-
-```bash
-# Step 1: Search for the library
-python3 .claude/skills/flydocs-context7/scripts/context7.py search "<library>" "[query]"
-
-# Step 2: Fetch docs using the library ID from search results
-python3 .claude/skills/flydocs-context7/scripts/context7.py docs "<library_id>" "<query>"
-```
-
-### Examples
-
-React hooks:
-```bash
-python3 .claude/skills/flydocs-context7/scripts/context7.py search "react" "hooks"
-python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/facebook/react" "hooks useState"
-```
-
-Next.js App Router:
-```bash
-python3 .claude/skills/flydocs-context7/scripts/context7.py search "next.js"
-python3 .claude/skills/flydocs-context7/scripts/context7.py docs "/vercel/next.js" "app router middleware"
-```
-
-## Key Rules
-
-- Always resolve the library ID first via `search` — do not guess the ID format
-- Prefer Context7 docs over training data for API specifics
-- If Context7 has no results or is rate-limited, fall back to web search
-- Cache within a session — no need to re-fetch the same library docs repeatedly

package/template/.claude/skills/flydocs-context7/scripts/context7.py

@@ -1,293 +0,0 @@
-#!/usr/bin/env python3
-"""Context7 API client for fetching library documentation.
-
-Queries the Context7 REST API to search for libraries and retrieve
-LLM-ready documentation. Replaces the Context7 MCP server with a
-lightweight script that follows the FlyDocs mechanism pattern.
-
-Usage:
-    python3 .claude/skills/flydocs-context7/scripts/context7.py \\
-        search <library_name> [query]
-
-    python3 .claude/skills/flydocs-context7/scripts/context7.py \\
-        docs <library_id> <query> [--type txt|json] [--tokens N]
-"""
-
-import argparse
-import json
-import os
-import sys
-import urllib.error
-import urllib.parse
-import urllib.request
-from pathlib import Path
-
-BASE_URL = "https://context7.com/api/v2"
-DEFAULT_TIMEOUT = 10
-DEFAULT_TOKENS = 5000
-
-
-# --- Helpers ---
-
-
-def fail(message):
-    """Print error to stderr and exit 1."""
-    print(message, file=sys.stderr)
-    sys.exit(1)
-
-
-def output_json(data):
-    """Print JSON to stdout."""
-    print(json.dumps(data, indent=2))
-
-
-def find_project_root(start=None):
-    """Walk up from start (or script location) to find the directory containing .flydocs/."""
-    current = Path(start) if start else Path(__file__).resolve().parent
-    for parent in [current] + list(current.parents):
-        if (parent / ".flydocs").is_dir():
-            return parent
-    return None
-
-
-def read_env_file(root):
-    """Read .env file at project root and return a dict of key=value pairs."""
-    env_path = root / ".env"
-    if not env_path.is_file():
-        return {}
-
-    env_vars = {}
-    try:
-        with open(env_path, "r", encoding="utf-8") as f:
-            for line in f:
-                line = line.strip()
-                # Skip empty lines and comments
-                if not line or line.startswith("#"):
-                    continue
-                if "=" not in line:
-                    continue
-                key, _, value = line.partition("=")
-                key = key.strip()
-                value = value.strip()
-                # Strip surrounding quotes if present
-                if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
-                    value = value[1:-1]
-                env_vars[key] = value
-    except OSError:
-        pass
-
-    return env_vars
-
-
-def resolve_api_key(args_key):
-    """Resolve the API key from flag, env var, or .env file. Returns None if unavailable."""
-    # 1. Explicit flag
-    if args_key:
-        return args_key
-
-    # 2. Environment variable
-    env_key = os.environ.get("CONTEXT7_API_KEY")
-    if env_key:
-        return env_key
-
-    # 3. .env file at project root
-    root = find_project_root()
-    if root:
-        env_vars = read_env_file(root)
-        dotenv_key = env_vars.get("CONTEXT7_API_KEY")
-        if dotenv_key:
-            return dotenv_key
-
-    # 4. Anonymous (no key)
-    return None
-
-
-def api_request(path, params, api_key=None):
-    """Make a GET request to the Context7 API and return parsed response data.
-
-    Handles HTTP errors, timeouts, and network failures with clear messages.
-    """
-    query_string = urllib.parse.urlencode(params)
-    url = f"{BASE_URL}/{path}?{query_string}"
-
-    request = urllib.request.Request(url)
-    request.add_header("User-Agent", "flydocs-context7/1.0")
-
-    if api_key:
-        request.add_header("Authorization", f"Bearer {api_key}")
-
-    try:
-        with urllib.request.urlopen(request, timeout=DEFAULT_TIMEOUT) as response:
-            body = response.read().decode("utf-8")
-            content_type = response.headers.get("Content-Type", "")
-            if "application/json" in content_type:
-                return json.loads(body)
-            return body
-    except urllib.error.HTTPError as e:
-        if e.code == 429:
-            fail("Rate limited by Context7 API. Wait a moment and try again.")
-        body_text = ""
-        try:
-            body_text = e.read().decode("utf-8", errors="replace")
-        except Exception:
-            pass
-        fail(f"Context7 API error (HTTP {e.code}): {e.reason}\n{body_text}".strip())
-    except urllib.error.URLError as e:
-        if "timed out" in str(e.reason).lower():
-            fail("Context7 API request timed out (10s). The service may be slow or unavailable.")
-        fail(f"Cannot reach Context7 API. Check your network connection.\nDetails: {e.reason}")
-    except OSError as e:
-        fail(f"Network error connecting to Context7 API: {e}")
-
-
-# --- Commands ---
-
-
-def cmd_search(args):
-    """Search for libraries by name and optional query."""
-    params = {"libraryName": args.library_name}
-    if args.query:
-        params["query"] = args.query
-
-    api_key = resolve_api_key(args.key)
-    data = api_request("libs/search", params, api_key=api_key)
-
-    # Normalize response — API wraps results in {"results": [...]}
-    if isinstance(data, dict) and "results" in data:
-        results = data["results"]
-    elif isinstance(data, list):
-        results = data
-    else:
-        results = []
-
-    if args.type == "json" or args.type is None:
-        # Default for search is JSON
-        compact = []
-        for lib in results:
-            compact.append({
-                "id": lib.get("id", ""),
-                "name": lib.get("title", lib.get("name", "")),
-                "description": lib.get("description", ""),
-                "trustScore": lib.get("trustScore", 0),
-            })
-        output_json(compact)
-    else:
-        # txt format for search — one line per result
-        for lib in results:
-            name = lib.get("title", lib.get("name", "unknown"))
-            lib_id = lib.get("id", "")
-            desc = lib.get("description", "")
-            score = lib.get("trustScore", 0)
-            print(f"{lib_id}  {name}  (trust: {score})")
-            if desc:
-                print(f"  {desc}")
-            print()
-
-
-def cmd_docs(args):
-    """Fetch documentation for a specific library."""
-    params = {
-        "libraryId": args.library_id,
-        "query": args.query,
-    }
-
-    output_type = args.type if args.type else "txt"
-    params["type"] = output_type
-
-    if args.tokens:
-        params["tokens"] = str(args.tokens)
-
-    api_key = resolve_api_key(args.key)
-    data = api_request("context", params, api_key=api_key)
-
-    if output_type == "json":
-        if isinstance(data, str):
-            # API returned text when we asked for JSON; wrap it
-            output_json({"content": data})
-        else:
-            output_json(data)
-    else:
-        # txt — print directly
-        if isinstance(data, str):
-            print(data)
-        elif isinstance(data, dict):
-            content = data.get("content", data.get("text", ""))
-            if content:
-                print(content)
-            else:
-                output_json(data)
-        else:
-            output_json(data)
-
-
-# --- Main ---
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Context7 API client — search libraries and fetch documentation"
-    )
-    parser.add_argument(
-        "--key", type=str, default=None,
-        help="API key override (default: CONTEXT7_API_KEY env var or .env file)"
-    )
-
-    subparsers = parser.add_subparsers(dest="command", required=True)
-
-    # search subcommand
-    search_parser = subparsers.add_parser(
-        "search",
-        help="Search for libraries by name"
-    )
-    search_parser.add_argument(
-        "library_name",
-        help="Library name to search for (e.g., 'react', 'next.js')"
-    )
-    search_parser.add_argument(
-        "query", nargs="?", default=None,
-        help="Optional search query to refine results"
-    )
-    search_parser.add_argument(
-        "--type", choices=["txt", "json"], default=None,
-        help="Output format (default: json for search)"
-    )
-    search_parser.add_argument(
-        "--tokens", type=int, default=DEFAULT_TOKENS,
-        help=f"Max tokens budget hint (default: {DEFAULT_TOKENS})"
-    )
-
-    # docs subcommand
-    docs_parser = subparsers.add_parser(
-        "docs",
-        help="Fetch documentation for a library"
-    )
-    docs_parser.add_argument(
-        "library_id",
-        help="Library ID from search results (e.g., '/vercel/next.js')"
-    )
-    docs_parser.add_argument(
-        "query",
-        help="Documentation query (e.g., 'server components', 'routing')"
-    )
-    docs_parser.add_argument(
-        "--type", choices=["txt", "json"], default=None,
-        help="Output format (default: txt for docs)"
-    )
-    docs_parser.add_argument(
-        "--tokens", type=int, default=DEFAULT_TOKENS,
-        help=f"Max tokens budget hint (default: {DEFAULT_TOKENS})"
-    )
-
-    args = parser.parse_args()
-
-    if args.command == "search":
-        cmd_search(args)
-    elif args.command == "docs":
-        cmd_docs(args)
-    else:
-        parser.print_help()
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()