@flydocs/cli 0.5.0-beta.0

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Query the context graph via BFS traversal.
+
+Returns related nodes for a given starting node, filtered by depth and
+relationship type. Output as compressed markdown or JSON.
+
+Usage:
+    python3 .claude/skills/flydocs-context-graph/scripts/graph_query.py \\
+        --node decision:001 [--depth 2] [--rel EXTENDS] [--reverse] [--format md|json]
+"""
+
+import argparse
+import sys
+from collections import deque
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from graph_utils import find_project_root, load_graph, output_json, fail
+
+
+def bfs_traverse(graph, start_node, max_depth, rel_filter, reverse):
+    """BFS traversal from start_node, returning discovered nodes with paths.
+
+    Returns list of (node_id, depth, edge_rel, via_node) tuples.
+    """
+    nodes = graph.get("nodes", {})
+    edges = graph.get("edges", [])
+
+    if start_node not in nodes:
+        return []
+
+    # Build adjacency from edges
+    adjacency = {}
+    for edge in edges:
+        if rel_filter and edge["rel"] not in rel_filter:
+            continue
+
+        if reverse:
+            src, dst = edge["to"], edge["from"]
+        else:
+            src, dst = edge["from"], edge["to"]
+
+        if src not in adjacency:
+            adjacency[src] = []
+        adjacency[src].append((dst, edge["rel"], edge.get("weight", 1.0)))
+
+    # BFS
+    visited = {start_node}
+    queue = deque()
+    results = []
+
+    for neighbor, rel, weight in adjacency.get(start_node, []):
+        if neighbor not in visited:
+            queue.append((neighbor, 1, rel, start_node))
+            visited.add(neighbor)
+
+    while queue:
+        node_id, depth, rel, via = queue.popleft()
+        results.append((node_id, depth, rel, via))
+
+        if depth < max_depth:
+            for neighbor, next_rel, weight in adjacency.get(node_id, []):
+                if neighbor not in visited:
+                    queue.append((neighbor, depth + 1, next_rel, node_id))
+                    visited.add(neighbor)
+
+    return results
+
+
+def format_markdown(graph, start_node, results):
+    """Format traversal results as compressed markdown context block."""
+    nodes = graph.get("nodes", {})
+    start_info = nodes.get(start_node, {})
+    label = start_info.get("label", start_node)
+
+    lines = [f"## Context for: {label}"]
+    lines.append("")
+
+    if not results:
+        lines.append("No related nodes found.")
+        return "\n".join(lines)
+
+    # Group results by node type
+    by_type = {}
+    for node_id, depth, rel, via in results:
+        node = nodes.get(node_id, {})
+        node_type = node.get("type", "unknown")
+        if node_type not in by_type:
+            by_type[node_type] = []
+        by_type[node_type].append((node_id, node, rel, depth))
+
+    # Type display order
+    type_labels = {
+        "decision": "Decisions",
+        "skill": "Skills",
+        "module": "Modules",
+        "issue": "Issues",
+        "session": "Sessions",
+        "concept": "Concepts",
+    }
+
+    for node_type in ["decision", "skill", "module", "issue", "session", "concept"]:
+        entries = by_type.get(node_type, [])
+        if not entries:
+            continue
+
+        type_label = type_labels.get(node_type, node_type.title())
+        lines.append(f"**{type_label}:**")
+
+        for node_id, node, rel, depth in entries:
+            node_label = node.get("label", node_id)
+            status = node.get("status", "")
+            status_str = f" [{status}]" if status else ""
+            lines.append(f"- {node_id}: {node_label} ({rel}){status_str}")
+
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def format_json(graph, start_node, results):
+    """Format traversal results as JSON."""
+    nodes = graph.get("nodes", {})
+
+    related = []
+    for node_id, depth, rel, via in results:
+        node = nodes.get(node_id, {})
+        related.append({
+            "id": node_id,
+            "type": node.get("type", "unknown"),
+            "label": node.get("label", node_id),
+            "relationship": rel,
+            "depth": depth,
+            "via": via,
+        })
+
+    return {
+        "node": start_node,
+        "label": nodes.get(start_node, {}).get("label", start_node),
+        "related": related,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Query the context graph")
+    parser.add_argument(
+        "--node", required=True,
+        help="Starting node ID (e.g., decision:001, skill:typescript-strict)"
+    )
+    parser.add_argument(
+        "--depth", type=int, default=2,
+        help="BFS traversal depth (default: 2)"
+    )
+    parser.add_argument(
+        "--rel", action="append", dest="rels",
+        help="Filter by relationship type (can specify multiple)"
+    )
+    parser.add_argument(
+        "--reverse", action="store_true",
+        help="Follow edges in reverse direction"
+    )
+    parser.add_argument(
+        "--format", choices=["md", "json"], default="md", dest="fmt",
+        help="Output format (default: md)"
+    )
+    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:
+        fail("Could not find project root (no .flydocs/ directory found)")
+
+    graph = load_graph(root)
+
+    if args.node not in graph.get("nodes", {}):
+        fail(f"Node not found: {args.node}")
+
+    rel_filter = set(args.rels) if args.rels else None
+    results = bfs_traverse(graph, args.node, args.depth, rel_filter, args.reverse)
+
+    if args.fmt == "json":
+        output_json(format_json(graph, args.node, results))
+    else:
+        print(format_markdown(graph, args.node, results))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Record session outcomes in the context graph.
+
+Called during session wrap to create a session node with edges to issues
+worked on and decisions produced. Supports cross-session continuity by
+building the temporal layer that graph_context.py traverses.
+
+Usage:
+    python3 .claude/skills/flydocs-context-graph/scripts/graph_session.py \
+        --summary "Completed Phase 1, started Phase 2" \
+        [--issue FLY-56] [--issue FLY-174] \
+        [--decision 006] \
+        [--date 2026-02-17] \
+        [--root PATH]
+
+Multiple --issue and --decision flags can be provided.
+"""
+
+import argparse
+import sys
+from datetime import date
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from graph_utils import (
+    find_project_root,
+    load_graph,
+    save_graph,
+    output_json,
+    fail,
+)
+
+
+# Session nodes older than this get reduced weight in graph_context.py
+DEFAULT_RETENTION_DAYS = 30
+
+
+def generate_session_id(session_date):
+    """Generate a session ID like session:2026-02-17-a.
+
+    If a session with the same date exists, increment the sequence letter.
+    """
+    base = f"session:{session_date}"
+    return base
+
+
+def find_next_session_id(graph, session_date):
+    """Find the next available session ID for a given date."""
+    nodes = graph.get("nodes", {})
+    base = f"session:{session_date}"
+
+    # Check if base ID exists, if so try a, b, c...
+    if base not in nodes:
+        return base
+
+    for suffix in "abcdefghijklmnopqrstuvwxyz":
+        candidate = f"{base}-{suffix}"
+        if candidate not in nodes:
+            return candidate
+
+    # Fallback
+    return f"{base}-z2"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Record session outcomes in the context graph"
+    )
+    parser.add_argument(
+        "--summary", required=True,
+        help="Brief session summary (1-2 sentences)"
+    )
+    parser.add_argument(
+        "--issue", action="append", dest="issues", default=[],
+        help="Issue identifier worked on (can specify multiple)"
+    )
+    parser.add_argument(
+        "--decision", action="append", dest="decisions", default=[],
+        help="ADR number produced/referenced (can specify multiple)"
+    )
+    parser.add_argument(
+        "--date", type=str, default=None,
+        help="Session date (YYYY-MM-DD, default: today)"
+    )
+    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:
+        fail("Could not find project root (no .flydocs/ directory found)")
+
+    graph = load_graph(root)
+
+    session_date = args.date or date.today().isoformat()
+    session_id = find_next_session_id(graph, session_date)
+
+    # Create session node
+    graph["nodes"][session_id] = {
+        "type": "session",
+        "label": args.summary,
+        "date": session_date,
+        "manual": True,
+    }
+
+    edges_added = []
+
+    # Create WORKED_ON edges to issues
+    for issue_ref in args.issues:
+        issue_node = f"issue:{issue_ref}"
+
+        # Create issue node if it doesn't exist
+        if issue_node not in graph["nodes"]:
+            graph["nodes"][issue_node] = {
+                "type": "issue",
+                "label": issue_ref,
+                "manual": True,
+            }
+
+        edge = {
+            "from": session_id,
+            "to": issue_node,
+            "rel": "WORKED_ON",
+            "weight": 1.0,
+            "manual": True,
+        }
+        graph["edges"].append(edge)
+        edges_added.append(f"{session_id} --WORKED_ON--> {issue_node}")
+
+    # Create PRODUCED edges to decisions
+    for decision_num in args.decisions:
+        decision_node = f"decision:{decision_num.zfill(3)}"
+
+        edge = {
+            "from": session_id,
+            "to": decision_node,
+            "rel": "PRODUCED",
+            "weight": 1.0,
+            "manual": True,
+        }
+
+        # Only add if target exists
+        if decision_node in graph["nodes"]:
+            graph["edges"].append(edge)
+            edges_added.append(f"{session_id} --PRODUCED--> {decision_node}")
+
+    save_graph(root, graph)
+
+    output_json({
+        "success": True,
+        "sessionId": session_id,
+        "date": session_date,
+        "summary": args.summary,
+        "edges": edges_added,
+    })
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Incrementally add or remove nodes and edges in the context graph.
+
+Usage:
+    python3 .claude/skills/flydocs-context-graph/scripts/graph_update.py \\
+        add-node <ID> --type <TYPE> [--label STR] [--path STR]
+
+    python3 .claude/skills/flydocs-context-graph/scripts/graph_update.py \\
+        remove-node <ID>
+
+    python3 .claude/skills/flydocs-context-graph/scripts/graph_update.py \\
+        add-edge <FROM> <TO> <REL> [--weight N] [--manual]
+
+    python3 .claude/skills/flydocs-context-graph/scripts/graph_update.py \\
+        remove-edge <FROM> <TO> <REL>
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from graph_utils import (
+    find_project_root,
+    load_graph,
+    save_graph,
+    output_json,
+    fail,
+    VALID_NODE_TYPES,
+    VALID_REL_TYPES,
+)
+
+
+def cmd_add_node(args, graph):
+    """Add a node to the graph."""
+    node_id = args.id
+    if args.type not in VALID_NODE_TYPES:
+        fail(f"Invalid node type: {args.type}. Valid: {', '.join(sorted(VALID_NODE_TYPES))}")
+
+    node = {"type": args.type}
+    if args.label:
+        node["label"] = args.label
+    else:
+        # Default label from ID
+        node["label"] = node_id.split(":", 1)[-1] if ":" in node_id else node_id
+    if args.path:
+        node["path"] = args.path
+    if args.status:
+        node["status"] = args.status
+    if args.date:
+        node["date"] = args.date
+
+    node["manual"] = True
+
+    graph["nodes"][node_id] = node
+    return {"success": True, "action": "add-node", "node": node_id}
+
+
+def cmd_remove_node(args, graph):
+    """Remove a node and its connected edges from the graph."""
+    node_id = args.id
+    if node_id not in graph["nodes"]:
+        fail(f"Node not found: {node_id}")
+
+    del graph["nodes"][node_id]
+
+    # Remove connected edges
+    before = len(graph["edges"])
+    graph["edges"] = [
+        e for e in graph["edges"]
+        if e["from"] != node_id and e["to"] != node_id
+    ]
+    removed_edges = before - len(graph["edges"])
+
+    return {
+        "success": True,
+        "action": "remove-node",
+        "removed": node_id,
+        "removedEdges": removed_edges,
+    }
+
+
+def cmd_add_edge(args, graph):
+    """Add an edge to the graph."""
+    if args.rel not in VALID_REL_TYPES:
+        fail(f"Invalid relationship: {args.rel}. Valid: {', '.join(sorted(VALID_REL_TYPES))}")
+
+    # Validate nodes exist
+    if args.source not in graph["nodes"]:
+        fail(f"Source node not found: {args.source}")
+    if args.target not in graph["nodes"]:
+        fail(f"Target node not found: {args.target}")
+
+    # Check for duplicate
+    for edge in graph["edges"]:
+        if edge["from"] == args.source and edge["to"] == args.target and edge["rel"] == args.rel:
+            fail(f"Edge already exists: {args.source} --{args.rel}--> {args.target}")
+
+    edge = {
+        "from": args.source,
+        "to": args.target,
+        "rel": args.rel,
+        "weight": args.weight,
+    }
+    if args.manual:
+        edge["manual"] = True
+
+    graph["edges"].append(edge)
+
+    return {
+        "success": True,
+        "action": "add-edge",
+        "edge": f"{args.source} --{args.rel}--> {args.target}",
+    }
+
+
+def cmd_remove_edge(args, graph):
+    """Remove an edge from the graph."""
+    before = len(graph["edges"])
+    graph["edges"] = [
+        e for e in graph["edges"]
+        if not (e["from"] == args.source and e["to"] == args.target and e["rel"] == args.rel)
+    ]
+
+    if len(graph["edges"]) == before:
+        fail(f"Edge not found: {args.source} --{args.rel}--> {args.target}")
+
+    return {
+        "success": True,
+        "action": "remove-edge",
+        "removed": f"{args.source} --{args.rel}--> {args.target}",
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Update the context graph")
+    parser.add_argument(
+        "--root", type=str, default=None,
+        help="Project root (default: auto-detect)"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # add-node
+    p_add_node = subparsers.add_parser("add-node", help="Add a node")
+    p_add_node.add_argument("id", help="Node ID (e.g., module:auth)")
+    p_add_node.add_argument("--type", required=True, help="Node type")
+    p_add_node.add_argument("--label", help="Human-readable label")
+    p_add_node.add_argument("--path", help="File path relative to project root")
+    p_add_node.add_argument("--status", help="Node status")
+    p_add_node.add_argument("--date", help="Date for temporal nodes (ISO format)")
+
+    # remove-node
+    p_rm_node = subparsers.add_parser("remove-node", help="Remove a node")
+    p_rm_node.add_argument("id", help="Node ID to remove")
+
+    # add-edge
+    p_add_edge = subparsers.add_parser("add-edge", help="Add an edge")
+    p_add_edge.add_argument("source", help="Source node ID")
+    p_add_edge.add_argument("target", help="Target node ID")
+    p_add_edge.add_argument("rel", help="Relationship type (e.g., EXTENDS)")
+    p_add_edge.add_argument("--weight", type=float, default=0.8, help="Edge weight 0.0-1.0")
+    p_add_edge.add_argument("--manual", action="store_true", help="Mark as manually added")
+
+    # remove-edge
+    p_rm_edge = subparsers.add_parser("remove-edge", help="Remove an edge")
+    p_rm_edge.add_argument("source", help="Source node ID")
+    p_rm_edge.add_argument("target", help="Target node ID")
+    p_rm_edge.add_argument("rel", help="Relationship type")
+
+    args = parser.parse_args()
+
+    root = Path(args.root) if args.root else find_project_root()
+    if not root:
+        fail("Could not find project root (no .flydocs/ directory found)")
+
+    graph = load_graph(root)
+
+    if args.command == "add-node":
+        result = cmd_add_node(args, graph)
+    elif args.command == "remove-node":
+        result = cmd_remove_node(args, graph)
+    elif args.command == "add-edge":
+        result = cmd_add_edge(args, graph)
+    elif args.command == "remove-edge":
+        result = cmd_remove_edge(args, graph)
+    else:
+        fail(f"Unknown command: {args.command}")
+
+    save_graph(root, graph)
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Shared utilities for context graph scripts."""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+GRAPH_REL_PATH = os.path.join("flydocs", "context", "graph.json")
+
+VALID_NODE_TYPES = {"skill", "decision", "issue", "module", "session", "concept"}
+VALID_REL_TYPES = {
+    "EXTENDS", "IMPLEMENTS", "DELEGATES_TO", "PRECEDES", "MODIFIES",
+    "WORKED_ON", "PRODUCED", "RELATES_TO", "SUPERSEDES", "BLOCKS",
+}
+
+
+def find_project_root(start=None):
+    """Walk up from start (or cwd) to find the directory containing .flydocs/."""
+    current = Path(start) if start else Path.cwd()
+    for parent in [current] + list(current.parents):
+        if (parent / ".flydocs").is_dir():
+            return parent
+    return None
+
+
+def graph_path(root):
+    """Return the absolute path to graph.json."""
+    return os.path.join(str(root), GRAPH_REL_PATH)
+
+
+def empty_graph():
+    """Return a new empty graph structure."""
+    return {
+        "version": 1,
+        "updated": datetime.now(timezone.utc).isoformat(),
+        "nodes": {},
+        "edges": [],
+    }
+
+
+def load_graph(root):
+    """Load graph.json from the project root. Returns empty graph if missing."""
+    path = graph_path(root)
+    if not os.path.exists(path):
+        return empty_graph()
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_graph(root, graph):
+    """Write graph.json to the project root. Creates parent dirs if needed."""
+    path = graph_path(root)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    graph["updated"] = datetime.now(timezone.utc).isoformat()
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(graph, f, indent=2)
+        f.write("\n")
+
+
+def output_json(data):
+    """Print JSON to stdout."""
+    print(json.dumps(data, indent=2))
+
+
+def fail(message):
+    """Print error to stderr and exit 1."""
+    print(message, file=sys.stderr)
+    sys.exit(1)
+
+
+def parse_frontmatter(text):
+    """Parse YAML frontmatter from a SKILL.md file (no PyYAML dependency).
+
+    Returns dict with 'name', 'description', 'triggers' keys or None.
+    """
+    match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        return None
+
+    block = match.group(1)
+    result = {}
+    current_key = None
+    current_list = None
+
+    for line in block.split("\n"):
+        # List item
+        if re.match(r"^\s+-\s+", line) and current_key:
+            value = re.sub(r"^\s+-\s+", "", line).strip()
+            if current_list is None:
+                current_list = []
+            current_list.append(value)
+            result[current_key] = current_list
+            continue
+
+        # Key: value
+        kv = re.match(r"^(\w+)\s*:\s*(.*)", line)
+        if kv:
+            if current_list is not None:
+                current_list = None
+            current_key = kv.group(1)
+            value = kv.group(2).strip().rstrip("|").rstrip(">").strip()
+            if value:
+                result[current_key] = value
+            continue
+
+        # Continuation of block scalar
+        if current_key and current_key in result and isinstance(result[current_key], str):
+            result[current_key] = result[current_key] + " " + line.strip()
+
+    # Clean up description whitespace
+    if "description" in result and isinstance(result["description"], str):
+        result["description"] = re.sub(r"\s+", " ", result["description"]).strip()
+
+    return result