@flydocs/cli 0.5.0-beta.6 → 0.5.0-beta.8

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

@@ -0,0 +1,293 @@
+#!/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()

package/template/.cursor/hooks.json

@@ -6,11 +6,6 @@
         "matcher": "Bash",
         "command": "python3 ./.flydocs/hooks/auto-approve.py",
         "timeout": 5
-      },
-      {
-        "matcher": "mcp__linear.*",
-        "command": "python3 ./.flydocs/hooks/prefer-scripts.py",
-        "timeout": 5
       }
     ],
     "afterFileEdit": [

package/template/.env.example

@@ -22,8 +22,9 @@
 #
 
 # ===========================================
-# REQUIRED: Linear API Key
+# CLOUD TIER ONLY: Linear API Key
 # ===========================================
+# Only needed if you use cloud tier (tier: "cloud" in .flydocs/config.json)
 # Get from: Linear → Settings → API → Personal API Keys
 # Format: lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 LINEAR_API_KEY=
@@ -32,9 +33,17 @@ LINEAR_API_KEY=
 # OPTIONAL: Figma Access Token
 # ===========================================
 # Get from: Figma → Settings → Personal Access Tokens
-# Only needed if using Figma MCP for design integration
+# Only needed if using the flydocs-figma skill for design integration
 FIGMA_ACCESS_TOKEN=
 
+# ===========================================
+# OPTIONAL: Context7 API Key
+# ===========================================
+# Enables higher rate limits for library documentation lookup
+# Get from: context7.com/dashboard (free account)
+# Works without a key at lower rate limits (~1,000 calls/month)
+CONTEXT7_API_KEY=
+
 # ===========================================
 # NOTE: Team ID and Project ID are discovered automatically
 # ===========================================

package/template/.flydocs/config.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.5.0-beta.6",
+  "version": "0.5.0-beta.8",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
-  "tier": "cloud",
+  "tier": "local",
   "setupComplete": false,
   "paths": {
     "content": "flydocs"
   },
   "provider": {
-    "type": "linear",
+    "type": null,
     "teamId": null
   },
   "workspace": {
@@ -46,11 +46,6 @@
     "auth": [],
     "styling": []
   },
-  "mcp": {
-    "preferred": [],
-    "fallbackOnly": ["linear"],
-    "stackSpecific": {}
-  },
   "skills": {
     "installed": [],
     "custom": []

package/template/.flydocs/hooks/auto-approve.py

@@ -19,9 +19,9 @@ import re
 
 
 # Pattern matches any flydocs skill scripts directory
-# Covers: flydocs-local, flydocs-cloud, flydocs-workflow
+# Covers: flydocs-local, flydocs-cloud, flydocs-workflow, flydocs-context-graph
 APPROVED_PATTERN = re.compile(
-    r'\.claude/skills/flydocs-(?:local|cloud|workflow)/scripts/\w+\.py'
+    r'python3?\s+(?:["\']?(?:\$CLAUDE_PROJECT_DIR|\$\{CLAUDE_PROJECT_DIR\}|\.)["\']?/)?\.?claude/skills/flydocs-(?:local|cloud|workflow|context-graph|context7)/scripts/\w+\.py'
 )
 
 

package/template/.flydocs/hooks/post-edit.py

@@ -11,6 +11,7 @@ Exit codes:
 """
 
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
@@ -59,6 +60,18 @@ def main() -> None:
         print('{}')
         sys.exit(0)
 
+    # Validate file_path is within project directory
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+    try:
+        resolved = os.path.realpath(file_path)
+        project_resolved = os.path.realpath(project_dir)
+        if not resolved.startswith(project_resolved + os.sep) and resolved != project_resolved:
+            print('{}')
+            sys.exit(0)
+    except (OSError, ValueError):
+        print('{}')
+        sys.exit(0)
+
     # Get file extension and format
     ext = get_file_extension(file_path)
     format_file(file_path, ext)

package/template/.flydocs/templates/instructions.md

@@ -22,8 +22,9 @@
 <!-- Skills installed based on detected stack -->
 
 {{#each skills}}
+
 - `{{this}}` - See `.claude/skills/{{this}}/SKILL.md`
-{{/each}}
+  {{/each}}
 
 ---
 
@@ -72,10 +73,10 @@ src/
 
 <!-- Link to ADRs or explain key architectural choices -->
 
-| Decision | Rationale | Date |
-|----------|-----------|------|
+| Decision                         | Rationale                                | Date     |
+| -------------------------------- | ---------------------------------------- | -------- |
 | Use Server Components by default | Better performance, simpler mental model | {{date}} |
-| Convex for real-time | Built-in subscriptions, type safety | {{date}} |
+| Convex for real-time             | Built-in subscriptions, type safety      | {{date}} |
 
 ---
 
@@ -105,59 +106,6 @@ async function Page() {
 
 ---
 
-## MCP Configuration
-
-<!-- Stack-specific MCP preferences for this project -->
-
-### MCP Strategy
-
-Configure in `.flydocs/config.json`:
-
-```json
-{
-  "mcp": {
-    "preferred": ["context7", "figma"],
-    "fallbackOnly": ["linear"],
-    "stackSpecific": {
-      "convex": {
-        "note": "Use Context7 for docs, CLI for schema changes"
-      }
-    }
-  }
-}
-```
-
-- **preferred**: MCPs to use proactively (unique capabilities like Figma visuals, Context7 docs)
-- **fallbackOnly**: MCPs with script alternatives (use scripts first, MCP if script fails)
-- **stackSpecific**: Per-stack notes and usage guidance
-
-### Stack-Specific MCP Notes
-
-<!-- Uncomment and customize for your stack -->
-
-<!--
-#### Convex
-- Use Context7 MCP for Convex API documentation
-- Prefer `convex dev` CLI for schema changes over direct mutations
-- Query patterns: Use `.collect()` for small datasets, pagination for large
--->
-
-<!--
-#### Supabase
-- Use Supabase MCP for database operations when available
-- Prefer RLS policies over application-level auth checks
-- Use database functions for complex operations
--->
-
-<!--
-#### Firebase
-- Use Firebase MCP for Firestore operations
-- Prefer security rules over client-side validation
-- Use batch operations for multiple writes
--->
-
----
-
 ## Skill Overrides
 
 <!-- Override specific skill recommendations for this project -->
@@ -168,7 +116,7 @@ Configure in `.flydocs/config.json`:
 
 ```typescript
 // This project uses shorter cache times due to real-time requirements
-cacheLife('seconds');  // Instead of skill default 'hours'
+cacheLife("seconds"); // Instead of skill default 'hours'
 ```
 
 ### convex
@@ -181,7 +129,7 @@ defineTable({
   // ... fields
   createdAt: v.number(),
   updatedAt: v.number(),
-  createdBy: v.optional(v.id('users')),
+  createdBy: v.optional(v.id("users")),
 });
 ```
 
@@ -191,11 +139,11 @@ defineTable({
 
 <!-- Document required env vars for this project -->
 
-| Variable | Purpose | Required |
-|----------|---------|----------|
-| `DATABASE_URL` | Database connection | Yes |
-| `NEXT_PUBLIC_API_URL` | Public API endpoint | Yes |
-| `AUTH_SECRET` | Auth session encryption | Yes |
+| Variable              | Purpose                 | Required |
+| --------------------- | ----------------------- | -------- |
+| `DATABASE_URL`        | Database connection     | Yes      |
+| `NEXT_PUBLIC_API_URL` | Public API endpoint     | Yes      |
+| `AUTH_SECRET`         | Auth session encryption | Yes      |
 
 ---
 
@@ -208,10 +156,10 @@ defineTable({
 // Test location: Co-located with source files
 
 // Example test structure
-describe('UserService', () => {
-  it('creates a user with valid data', async () => {
+describe("UserService", () => {
+  it("creates a user with valid data", async () => {
     // Arrange
-    const input = { name: 'Test', email: 'test@example.com' };
+    const input = { name: "Test", email: "test@example.com" };
 
     // Act
     const result = await createUser(input);
@@ -224,5 +172,5 @@ describe('UserService', () => {
 
 ---
 
-*Last updated: {{date}}*
-*FlyDocs version: 6.3.0*
+_Last updated: {{date}}_
+_FlyDocs version: 6.3.0_

package/template/.flydocs/version

@@ -1 +1 @@
-0.5.0-beta.6
+0.5.0-beta.8

package/template/AGENTS.md

@@ -95,6 +95,7 @@ Consult the relevant skill BEFORE writing code or making workflow decisions.
 | Skill             | Triggers                                                                                                                | Entry                                     |
 | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
 | flydocs-cloud     | create issue, transition, comment, list issues, assign, update description, update issue, project update, Linear, cloud | .claude/skills/flydocs-cloud/SKILL.md     |
+| flydocs-context7  | context7, library docs, documentation lookup, framework docs, package docs, API reference                               | .claude/skills/flydocs-context7/SKILL.md  |
 | flydocs-estimates | estimate, cost, token usage, API cost, labor estimate, sizing, effort                                                   | .claude/skills/flydocs-estimates/SKILL.md |
 | flydocs-figma     | Figma, design, screenshot, token mapping, component from design, pixel-perfect, design system                           | .claude/skills/flydocs-figma/SKILL.md     |
 | flydocs-local     | create issue, transition, comment, list issues, assign, update description, status summary, local                       | .claude/skills/flydocs-local/SKILL.md     |