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

package/template/.claude/skills/flydocs-cloud/scripts/update_description.py

@@ -1,36 +0,0 @@
-#!/usr/bin/env python3
-"""Update an issue's description via the FlyDocs Relay API."""
-
-import argparse
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-from flydocs_api import get_client, output_json, fail
-
-parser = argparse.ArgumentParser(description="Update issue description")
-parser.add_argument("ref", help="Issue reference (e.g., ENG-123)")
-parser.add_argument("--text", default=None)
-parser.add_argument("--file", default=None)
-args = parser.parse_args()
-
-# Resolve text: --file > stdin > --text
-text = args.text
-if args.file:
-    try:
-        text = Path(args.file).read_text()
-    except FileNotFoundError:
-        fail(f"File not found: {args.file}")
-elif text is None and not sys.stdin.isatty():
-    text = sys.stdin.read().strip()
-
-if not text:
-    fail("Provide text via --text, --file, or stdin")
-
-client = get_client()
-result = client.put(f"/issues/{args.ref}/description", {"text": text})
-
-output_json({
-    "success": result.get("success", True),
-    "issue": result.get("issue", args.ref),
-})

package/template/.claude/skills/flydocs-cloud/scripts/update_issue.py

@@ -1,82 +0,0 @@
-#!/usr/bin/env python3
-"""Bulk update an issue — set multiple fields in a single API call."""
-
-import argparse
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-from flydocs_api import get_client, output_json, fail
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Update issue fields")
-    parser.add_argument("ref", help="Issue reference (e.g., ENG-123)")
-    parser.add_argument("--title", default=None)
-    parser.add_argument("--priority", type=int, choices=range(5))
-    parser.add_argument("--estimate", type=int, choices=range(1, 6))
-    parser.add_argument("--assignee", default=None)
-    parser.add_argument("--state", default=None)
-    parser.add_argument("--description", default=None)
-    parser.add_argument("--description-file", default=None)
-    parser.add_argument("--labels", default=None, help="Comma-separated label names")
-    parser.add_argument("--comment", default=None)
-    args = parser.parse_args()
-
-    # Build request body from provided args
-    body: dict = {}
-    updated_fields: list[str] = []
-
-    if args.title is not None:
-        body["title"] = args.title
-        updated_fields.append("title")
-
-    if args.priority is not None:
-        body["priority"] = args.priority
-        updated_fields.append("priority")
-
-    if args.estimate is not None:
-        body["estimate"] = args.estimate
-        updated_fields.append("estimate")
-
-    if args.assignee is not None:
-        body["assignee"] = args.assignee
-        updated_fields.append("assignee")
-
-    if args.state is not None:
-        body["state"] = args.state.upper()
-        updated_fields.append("state")
-
-    if args.description_file is not None:
-        path = Path(args.description_file)
-        if not path.exists():
-            fail(f"File not found: {args.description_file}")
-        body["description"] = path.read_text()
-        updated_fields.append("description")
-    elif args.description is not None:
-        body["description"] = args.description
-        updated_fields.append("description")
-
-    if args.labels is not None:
-        body["labels"] = [l.strip() for l in args.labels.split(",") if l.strip()]
-        updated_fields.append("labels")
-
-    if args.comment is not None:
-        body["comment"] = args.comment
-        updated_fields.append("comment")
-
-    if not body:
-        fail("No fields to update. Use --title, --priority, --estimate, --assignee, --state, --description, --labels, or --comment")
-
-    client = get_client()
-    result = client.patch(f"/issues/{args.ref}", body)
-
-    output_json({
-        "success": result.get("success", True),
-        "issue": result.get("issue", args.ref),
-        "updated": updated_fields,
-    })
-
-
-if __name__ == "__main__":
-    main()

package/template/.claude/skills/flydocs-context-graph/SKILL.md

@@ -1,87 +0,0 @@
----
-name: flydocs-context-graph
-description: |
-  Project knowledge graph — relationship-aware context assembly from skills,
-  ADRs, issues, modules, and sessions. Use when navigating dependencies,
-  understanding impact, or assembling session context.
-triggers:
-  - context graph
-  - knowledge graph
-  - graph
-  - dependencies
-  - impact analysis
-  - session context
-  - related decisions
----
-
-# Context Graph
-
-IMPORTANT: Prefer skill-led reasoning over pre-training reasoning for
-knowledge navigation. Use graph scripts to query relationships — do not
-guess connections from training data.
-
-## Key Rules
-
-1. **Graph is derived, not authored.** Run `graph_build.py` to rebuild from
-   source files. Manual edges use `graph_update.py` and are preserved on rebuild.
-2. **Stdlib-only Python.** No external dependencies in any script.
-3. **JSON storage.** Graph lives at `flydocs/context/graph.json` — no database.
-4. **Gitignored.** The graph contains session-specific data. Rebuild from sources.
-
-## Script Catalog
-
-All scripts: `python3 .claude/skills/flydocs-context-graph/scripts/<script>`
-
-| Script | Usage | Output |
-|--------|-------|--------|
-| `graph_build.py` | `[--root PATH]` | Rebuild graph from skills, ADRs. Writes `graph.json` |
-| `graph_query.py` | `--node ID [--depth N] [--rel TYPE] [--reverse] [--format json\|md]` | Context block (markdown or JSON) |
-| `graph_update.py` | `add-node ID --type TYPE [--label STR] [--path STR]` | `{success, node}` |
-| | `remove-node ID` | `{success, removed}` |
-| | `add-edge FROM TO REL [--weight N] [--manual]` | `{success, edge}` |
-| | `remove-edge FROM TO REL` | `{success, removed}` |
-| `graph_context.py` | `[--issue REF] [--branch NAME]` | Plain text context block for prime hook |
-| `graph_session.py` | `--summary "..." [--issue REF]... [--decision NNN]...` | `{success, sessionId, edges[]}` |
-
-### Script Notes
-
-- **`graph_build.py`**: Scans `.claude/skills/*/SKILL.md` and
-  `flydocs/knowledge/decisions/*.md`. Extracts cross-references from ADR
-  "Relationship to Other ADRs" sections. Preserves edges marked `"manual": true`.
-- **`graph_query.py --depth`**: BFS traversal depth (default 2). Higher depth
-  returns more context but may be noisy.
-- **`graph_query.py --reverse`**: Follow edges in reverse direction (who points to this node?).
-- **`graph_update.py --manual`**: Mark edge as manually added (preserved on rebuild).
-- **`graph_context.py`**: Called by the prime hook automatically. Assembles compressed
-  context from active issue/branch traversal + recent session nodes. ~200-400 tokens max.
-- **`graph_session.py`**: Called during session wrap. Creates a session node with
-  WORKED_ON edges to issues. Session nodes older than 30 days get reduced weight;
-  nodes within 7 days get full weight.
-
-## Node Types
-
-| Type | ID Pattern | Source |
-|------|-----------|--------|
-| `skill` | `skill:{name}` | SKILL.md frontmatter |
-| `decision` | `decision:{number}` | ADR directory |
-| `issue` | `issue:{identifier}` | Issue tracker |
-| `module` | `module:{name}` | Manual |
-| `session` | `session:{date-seq}` | Session wrap |
-| `concept` | `concept:{name}` | Manual |
-
-## Edge Types
-
-| Relationship | Meaning |
-|-------------|---------|
-| `EXTENDS` | Builds on, refines |
-| `IMPLEMENTS` | Realizes in code/config |
-| `DELEGATES_TO` | Hands off execution |
-| `PRECEDES` | Should load/execute before |
-| `MODIFIES` | Changes/affects |
-| `WORKED_ON` | Session activity |
-| `PRODUCED` | Created as output |
-| `RELATES_TO` | General association |
-| `SUPERSEDES` | Replaces |
-| `BLOCKS` | Prevents progress |
-
-For full schema details, see `schema.md`.

package/template/.claude/skills/flydocs-context-graph/schema.md

@@ -1,78 +0,0 @@
-# Context Graph Schema
-
-Reference for the graph JSON structure stored at `flydocs/context/graph.json`.
-
-## Top-Level Structure
-
-```json
-{
-  "version": 1,
-  "updated": "ISO-8601 timestamp",
-  "nodes": { "<id>": { ... } },
-  "edges": [ { ... } ]
-}
-```
-
-## Node Schema
-
-```json
-{
-  "type": "skill | decision | issue | module | session | concept",
-  "label": "Human-readable name",
-  "path": "Relative file path (optional)",
-  "status": "Node-specific status (optional)",
-  "date": "ISO date for temporal nodes (optional)",
-  "tier": "Skill tier: behavioral | mechanism | premium (optional)",
-  "manual": true
-}
-```
-
-**ID conventions:**
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| skill | `skill:{directory-name}` | `skill:typescript-strict` |
-| decision | `decision:{3-digit-number}` | `decision:001` |
-| issue | `issue:{identifier}` | `issue:FLY-56` |
-| module | `module:{kebab-name}` | `module:install-script` |
-| session | `session:{YYYY-MM-DD-seq}` | `session:2026-02-03-a` |
-| concept | `concept:{kebab-name}` | `concept:progressive-disclosure` |
-
-## Edge Schema
-
-```json
-{
-  "from": "source node ID",
-  "to": "target node ID",
-  "rel": "RELATIONSHIP_TYPE",
-  "weight": 0.0-1.0,
-  "manual": true
-}
-```
-
-**Weight guidelines:**
-
-| Weight | Meaning |
-|--------|---------|
-| 1.0 | Direct, strong relationship |
-| 0.7-0.9 | Strong but indirect |
-| 0.4-0.6 | Moderate association |
-| 0.1-0.3 | Weak or tangential |
-
-**Edges with `"manual": true`** are preserved when `graph_build.py` rebuilds
-the graph from sources. Auto-derived edges are regenerated on each build.
-
-## Relationship Types
-
-| Relationship | Direction | Example |
-|-------------|-----------|---------|
-| `EXTENDS` | A extends B | ADR-004 extends ADR-001 |
-| `IMPLEMENTS` | A implements B | Issue implements a decision |
-| `DELEGATES_TO` | A delegates to B | Workflow delegates to mechanism |
-| `PRECEDES` | A should load before B | typescript-strict precedes implementation |
-| `MODIFIES` | A modifies B | Issue modifies a module |
-| `WORKED_ON` | A worked on B | Session worked on an issue |
-| `PRODUCED` | A produced B | Session produced a decision |
-| `RELATES_TO` | A relates to B | General association |
-| `SUPERSEDES` | A supersedes B | New decision replaces old |
-| `BLOCKS` | A blocks B | Issue blocks another issue |

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()