@flydocs/cli 0.6.0-alpha.3 → 0.6.0-alpha.31

package/template/.claude/skills/flydocs-context-graph/scripts/graph_context.py

@@ -1,338 +0,0 @@
-#!/usr/bin/env python3
-"""Assemble compressed graph context for the prime hook.
-
-Given an active issue and/or git branch, traverses the graph and returns
-a compact context block suitable for injection into the prompt-submit hook.
-Stays within a ~200-400 token budget.
-
-Usage:
-    python3 .claude/skills/flydocs-context-graph/scripts/graph_context.py \
-        [--issue FLY-56] [--branch feature/context-graph] [--root PATH]
-
-Output: Plain text context block (not JSON) for direct injection into hook output.
-Returns empty string if graph doesn't exist or no relevant context found.
-"""
-
-import argparse
-import sys
-from datetime import date, timedelta
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-from graph_utils import find_project_root, load_graph
-
-
-# Maximum lines in the context block to stay within token budget
-MAX_CONTEXT_LINES = 12
-
-# Session staleness policy
-SESSION_RETENTION_DAYS = 30
-SESSION_FRESH_DAYS = 7  # Full weight within this window
-
-
-def find_issue_node(graph, issue_ref):
-    """Find a graph node matching an issue reference (e.g., FLY-56)."""
-    if not issue_ref:
-        return None
-
-    # Try exact match first
-    node_id = f"issue:{issue_ref}"
-    if node_id in graph.get("nodes", {}):
-        return node_id
-
-    # Try case-insensitive search
-    for nid in graph.get("nodes", {}):
-        if nid.lower() == node_id.lower():
-            return nid
-
-    return None
-
-
-def find_branch_nodes(graph, branch):
-    """Infer relevant nodes from a git branch name.
-
-    Branch names often contain issue refs (feature/FLY-56-context-graph)
-    or skill/module names (feature/context-graph).
-    """
-    if not branch:
-        return []
-
-    nodes = graph.get("nodes", {})
-    matches = []
-
-    # Extract issue reference from branch (e.g., FLY-56)
-    import re
-    issue_match = re.search(r"([A-Z]+-\d+)", branch, re.IGNORECASE)
-    if issue_match:
-        issue_id = find_issue_node(graph, issue_match.group(1))
-        if issue_id:
-            matches.append(issue_id)
-
-    # Match skill or module names in branch
-    branch_lower = branch.lower().replace("/", "-").replace("_", "-")
-    for node_id, node in nodes.items():
-        if node["type"] in ("skill", "module"):
-            name = node_id.split(":", 1)[-1].lower()
-            if name in branch_lower and len(name) > 3:
-                matches.append(node_id)
-
-    return matches
-
-
-def find_recent_sessions(graph, issue_nodes, today=None):
-    """Find session nodes relevant to the current work.
-
-    Returns sessions connected to active issues, or recent sessions if no
-    issue match. Applies staleness weighting — older sessions get lower weight.
-    """
-    if today is None:
-        today = date.today()
-
-    nodes = graph.get("nodes", {})
-    edges = graph.get("edges", [])
-    cutoff = today - timedelta(days=SESSION_RETENTION_DAYS)
-
-    # Find all session nodes within retention window
-    sessions = []
-    for node_id, node in nodes.items():
-        if node.get("type") != "session":
-            continue
-
-        session_date_str = node.get("date", "")
-        if not session_date_str:
-            continue
-
-        try:
-            session_date = date.fromisoformat(session_date_str)
-        except ValueError:
-            continue
-
-        if session_date < cutoff:
-            continue
-
-        # Calculate staleness weight
-        age_days = (today - session_date).days
-        if age_days <= SESSION_FRESH_DAYS:
-            weight = 1.0
-        else:
-            # Linear decay from 1.0 to 0.1 over the retention period
-            weight = max(0.1, 1.0 - (age_days / SESSION_RETENTION_DAYS) * 0.9)
-
-        sessions.append((node_id, node, session_date, weight))
-
-    if not sessions:
-        return []
-
-    # Check which sessions are connected to active issues
-    issue_set = set(issue_nodes)
-    connected = []
-    unconnected = []
-
-    for session_id, node, session_date, weight in sessions:
-        # Check if this session has WORKED_ON edges to any active issue
-        has_issue_link = False
-        for edge in edges:
-            if (edge["from"] == session_id
-                    and edge["rel"] == "WORKED_ON"
-                    and edge["to"] in issue_set):
-                has_issue_link = True
-                break
-
-        if has_issue_link:
-            connected.append((session_id, node, weight))
-        else:
-            unconnected.append((session_id, node, weight))
-
-    # Prefer connected sessions, fall back to most recent
-    if connected:
-        connected.sort(key=lambda x: x[2], reverse=True)
-        return connected[:3]
-
-    # No connected sessions — return most recent ones
-    unconnected.sort(key=lambda x: x[0], reverse=True)  # Sort by ID (date-based)
-    return unconnected[:2]
-
-
-def get_related_context(graph, start_nodes, max_depth=2):
-    """BFS traverse from start nodes and collect related context.
-
-    Returns a deduplicated list of (node_id, node, rel, depth) tuples.
-    """
-    nodes = graph.get("nodes", {})
-    edges = graph.get("edges", [])
-
-    # Build adjacency (both directions for full context)
-    forward = {}
-    reverse = {}
-    for edge in edges:
-        src, dst = edge["from"], edge["to"]
-        rel = edge["rel"]
-        weight = edge.get("weight", 1.0)
-
-        if src not in forward:
-            forward[src] = []
-        forward[src].append((dst, rel, weight))
-
-        if dst not in reverse:
-            reverse[dst] = []
-        reverse[dst].append((src, rel, weight))
-
-    visited = set(start_nodes)
-    results = []
-
-    # BFS from each start node
-    from collections import deque
-    queue = deque()
-
-    for start in start_nodes:
-        # Forward edges
-        for neighbor, rel, weight in forward.get(start, []):
-            if neighbor not in visited:
-                queue.append((neighbor, 1, rel, "forward"))
-                visited.add(neighbor)
-        # Reverse edges
-        for neighbor, rel, weight in reverse.get(start, []):
-            if neighbor not in visited:
-                queue.append((neighbor, 1, rel, "reverse"))
-                visited.add(neighbor)
-
-    while queue:
-        node_id, depth, rel, direction = queue.popleft()
-        node = nodes.get(node_id, {})
-        results.append((node_id, node, rel, depth))
-
-        if depth < max_depth:
-            adj = forward if direction == "forward" else reverse
-            for neighbor, next_rel, weight in adj.get(node_id, []):
-                if neighbor not in visited:
-                    queue.append((neighbor, depth + 1, next_rel, direction))
-                    visited.add(neighbor)
-
-    return results
-
-
-def format_context_block(graph, start_nodes, related):
-    """Format a compressed context block within the token budget."""
-    nodes = graph.get("nodes", {})
-    lines = []
-
-    # Temporal anchor
-    lines.append(f"Today is {date.today().strftime('%B %d, %Y')}")
-
-    if not related:
-        return "\n".join(lines)
-
-    # Group by type, prioritize decisions and skills
-    decisions = []
-    skills = []
-    sessions = []
-    other = []
-
-    for node_id, node, rel, depth in related:
-        node_type = node.get("type", "unknown")
-        if node_type == "decision":
-            decisions.append((node_id, node, rel))
-        elif node_type == "skill":
-            skills.append((node_id, node, rel))
-        elif node_type == "session":
-            sessions.append((node_id, node, rel))
-        else:
-            other.append((node_id, node, rel))
-
-    # Decisions — most valuable context
-    if decisions:
-        lines.append("Related decisions:")
-        for node_id, node, rel in decisions[:4]:
-            num = node_id.split(":")[-1]
-            label = node.get("label", node_id)
-            lines.append(f"  ADR-{num}: {label} ({rel})")
-
-    # Skills
-    if skills:
-        skill_names = [n.get("label", nid) for nid, n, r in skills[:3]]
-        lines.append(f"Related skills: {', '.join(skill_names)}")
-
-    # Sessions — prior work context
-    if sessions:
-        for node_id, node, rel in sessions[:2]:
-            label = node.get("label", "")
-            session_date = node.get("date", "")
-            if label:
-                lines.append(f"Prior session ({session_date}): {label}")
-
-    # Truncate to budget
-    if len(lines) > MAX_CONTEXT_LINES:
-        lines = lines[:MAX_CONTEXT_LINES]
-
-    return "\n".join(lines)
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Assemble graph context for prime hook"
-    )
-    parser.add_argument(
-        "--issue", type=str, default=None,
-        help="Active issue reference (e.g., FLY-56)"
-    )
-    parser.add_argument(
-        "--branch", type=str, default=None,
-        help="Current git branch name"
-    )
-    parser.add_argument(
-        "--root", type=str, default=None,
-        help="Project root (default: auto-detect)"
-    )
-    args = parser.parse_args()
-
-    root = Path(args.root) if args.root else find_project_root()
-    if not root:
-        # Graceful fallback — no output
-        sys.exit(0)
-
-    # Load graph — graceful fallback if missing
-    graph = load_graph(root)
-    if not graph.get("nodes"):
-        # Empty or missing graph — just output temporal anchor
-        print(f"Today is {date.today().strftime('%B %d, %Y')}")
-        sys.exit(0)
-
-    # Find starting nodes
-    start_nodes = []
-
-    issue_node = find_issue_node(graph, args.issue)
-    if issue_node:
-        start_nodes.append(issue_node)
-
-    branch_nodes = find_branch_nodes(graph, args.branch)
-    start_nodes.extend(n for n in branch_nodes if n not in start_nodes)
-
-    # If no specific entry points, just output temporal anchor
-    if not start_nodes:
-        print(f"Today is {date.today().strftime('%B %d, %Y')}")
-        sys.exit(0)
-
-    # Traverse and assemble context
-    related = get_related_context(graph, start_nodes, max_depth=2)
-
-    # Find recent sessions (connected to active issues or just recent)
-    issue_start_nodes = [n for n in start_nodes if n.startswith("issue:")]
-    recent_sessions = find_recent_sessions(graph, issue_start_nodes)
-
-    # Add sessions to related if not already present
-    seen = {r[0] for r in related}
-    for session_id, node, weight in recent_sessions:
-        if session_id not in seen:
-            related.append((session_id, node, "WORKED_ON", 1))
-            seen.add(session_id)
-
-    context = format_context_block(graph, start_nodes, related)
-
-    if context:
-        print(context)
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

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