@flydocs/cli 0.5.0-beta.0

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Create a new issue in Linear."""
+
+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="Create issue")
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--type", required=True, choices=["feature", "bug", "chore", "idea"], dest="issue_type")
+    parser.add_argument("--description", default="")
+    parser.add_argument("--description-file", default="", dest="description_file")
+    parser.add_argument("--priority", type=int, default=3, choices=range(5))
+    parser.add_argument("--estimate", type=int, default=0, choices=[0, 1, 2, 3, 5])
+    parser.add_argument("--assignee", default=None)
+    parser.add_argument("--project", default=None)
+    parser.add_argument("--triage", action="store_true")
+    args = parser.parse_args()
+
+    # Resolve description: --description-file > stdin > --description
+    description = args.description
+    if args.description_file:
+        try:
+            description = Path(args.description_file).read_text()
+        except FileNotFoundError:
+            fail(f"File not found: {args.description_file}")
+    elif not description and not sys.stdin.isatty():
+        description = sys.stdin.read().strip()
+
+    client = get_client()
+
+    issue_input = {
+        "teamId": client.team_id,
+        "title": args.title,
+        "description": description,
+        "priority": args.priority,
+    }
+    if args.estimate:
+        issue_input["estimate"] = args.estimate
+
+    # Labels
+    label_ids = []
+    cat_id = client.get_category_label_id(args.issue_type)
+    if cat_id:
+        label_ids.append(cat_id)
+    if args.triage:
+        triage_id = client.get_other_label_id("triage")
+        if triage_id:
+            label_ids.append(triage_id)
+    if label_ids:
+        issue_input["labelIds"] = label_ids
+
+    # Project
+    project_id = args.project
+    if not project_id:
+        active = client.workspace.get("activeProjects", [])
+        if active:
+            project_id = active[0]
+    if project_id:
+        issue_input["projectId"] = project_id
+
+    # Assignee
+    if args.assignee:
+        user_id, _ = client.resolve_user_id(args.assignee)
+        if user_id:
+            issue_input["assigneeId"] = user_id
+
+    mutation = """mutation($input: IssueCreateInput!) {
+        issueCreate(input: $input) {
+            success
+            issue { id identifier title url }
+        }
+    }"""
+
+    result = client.query(mutation, {"input": issue_input})
+
+    data = result.get("data", {}).get("issueCreate", {})
+    if not data.get("success"):
+        # Retry without labels if team mismatch (stale label IDs in config)
+        errors = result.get("errors", [])
+        label_error = any("label" in (e.get("message", "") or "").lower() for e in errors)
+        if label_error and "labelIds" in issue_input:
+            print("Label IDs rejected — retrying without labels...", file=sys.stderr)
+            del issue_input["labelIds"]
+            result = client.query(mutation, {"input": issue_input})
+            data = result.get("data", {}).get("issueCreate", {})
+        if not data.get("success"):
+            fail(f"Failed to create issue: {result}")
+
+    issue = data["issue"]
+    output_json({"id": issue["id"], "identifier": issue["identifier"], "title": issue["title"], "url": issue["url"]})
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Create a milestone."""
+
+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="Create milestone")
+parser.add_argument("--name", required=True)
+parser.add_argument("--project", default="", help="Project ID (defaults to first activeProject)")
+parser.add_argument("--target-date", default=None, help="YYYY-MM-DD")
+args = parser.parse_args()
+
+client = get_client()
+
+project_id = args.project
+if not project_id:
+    active = client.workspace.get("activeProjects", [])
+    if active:
+        project_id = active[0]
+    else:
+        fail("No --project specified and no activeProjects in config")
+
+milestone_input = {"name": args.name, "projectId": project_id}
+if args.target_date:
+    milestone_input["targetDate"] = args.target_date
+
+result = client.query(
+    """mutation($input: ProjectMilestoneCreateInput!) {
+        projectMilestoneCreate(input: $input) {
+            success
+            projectMilestone { id name }
+        }
+    }""",
+    {"input": milestone_input},
+)
+
+data = result.get("data", {}).get("projectMilestoneCreate", {})
+if not data.get("success"):
+    fail(f"Failed to create milestone: {result}")
+
+ms = data["projectMilestone"]
+output_json({"id": ms["id"], "name": ms["name"]})

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Create a new project."""
+
+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="Create project")
+parser.add_argument("--name", required=True)
+parser.add_argument("--description", default="")
+args = parser.parse_args()
+
+client = get_client()
+
+project_input = {
+    "name": args.name,
+    "teamIds": [client.team_id],
+}
+if args.description:
+    project_input["description"] = args.description
+
+result = client.query(
+    """mutation($input: ProjectCreateInput!) {
+        projectCreate(input: $input) {
+            success
+            project { id name url }
+        }
+    }""",
+    {"input": project_input},
+)
+
+data = result.get("data", {}).get("projectCreate", {})
+if not data.get("success"):
+    fail(f"Failed to create project: {result}")
+
+project = data["project"]
+output_json({"id": project["id"], "name": project["name"], "url": project["url"]})

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Set estimate on an issue."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+if len(sys.argv) < 3:
+    fail("Usage: estimate.py <ref> <1-5>")
+
+ref = sys.argv[1]
+try:
+    estimate = int(sys.argv[2])
+except ValueError:
+    fail("Estimate must be a number (1-5)")
+
+client = get_client()
+issue_uuid = client.resolve_issue_id(ref)
+if not issue_uuid:
+    fail(f"Issue not found: {ref}")
+
+result = client.query(
+    """mutation($id: String!, $estimate: Int!) {
+        issueUpdate(id: $id, input: { estimate: $estimate }) {
+            success
+            issue { identifier estimate }
+        }
+    }""",
+    {"id": issue_uuid, "estimate": estimate},
+)
+
+if not result.get("data", {}).get("issueUpdate", {}).get("success"):
+    fail(f"Failed to set estimate: {result}")
+
+issue = result["data"]["issueUpdate"]["issue"]
+output_json({"success": True, "issue": issue["identifier"], "estimate": issue["estimate"]})

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

@@ -0,0 +1,277 @@
+"""FlyDocs Cloud API — Linear GraphQL client.
+
+Central module for all Linear API operations.
+Loads config from .flydocs/config.json and API key from .env files.
+
+Usage:
+    from flydocs_api import get_client
+    client = get_client()
+    result = client.query("{ viewer { id name } }")
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+
+class FlyDocsClient:
+    """Client for Linear GraphQL API with retry logic and config awareness."""
+
+    API_URL = "https://api.linear.app/graphql"
+    MAX_RETRIES = 5
+    RETRY_DELAY = 2
+
+    def __init__(self):
+        self.project_root = find_project_root()
+        self.config_path = self.project_root / ".flydocs" / "config.json"
+        self.log_path = self.project_root / ".flydocs" / "logs" / "linear-ops.jsonl"
+
+        self.config = self._load_config()
+        self.api_key = self._load_api_key()
+        if not self.api_key:
+            print("ERROR: LINEAR_API_KEY not found", file=sys.stderr)
+            print("Set in environment or .env/.env.local file", file=sys.stderr)
+            sys.exit(1)
+
+        self.team_id = self.config.get("provider", {}).get("teamId")
+        self.status_mapping = self.config.get("statusMapping", {})
+        self.issue_labels = self.config.get("issueLabels", {})
+        self.workspace = self.config.get("workspace", {})
+
+        # In-process caches (live for one script invocation)
+        self._id_cache: dict[str, str] = {}
+        self._team_members: Optional[list] = None
+        self._active_cycle: Optional[dict] = None
+
+    def _load_config(self) -> dict:
+        if self.config_path.exists():
+            with open(self.config_path, "r") as f:
+                return json.load(f)
+        return {}
+
+    def _load_api_key(self) -> Optional[str]:
+        if os.environ.get("LINEAR_API_KEY"):
+            return os.environ["LINEAR_API_KEY"]
+        for name in [".env.local", ".env"]:
+            env_file = self.project_root / name
+            if env_file.exists():
+                key = self._parse_env_file(env_file, "LINEAR_API_KEY")
+                if key:
+                    return key
+        return None
+
+    def _parse_env_file(self, path: Path, key: str) -> Optional[str]:
+        with open(path, "r") as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith("#") or "=" not in line:
+                    continue
+                k, _, v = line.partition("=")
+                if k.strip() == key:
+                    v = v.strip().strip("\"'")
+                    return v if v else None
+        return None
+
+    def query(self, query: str, variables: Optional[dict] = None) -> dict:
+        payload = {"query": query}
+        if variables:
+            payload["variables"] = variables
+
+        data = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": self.api_key,
+        }
+
+        for attempt in range(self.MAX_RETRIES):
+            try:
+                req = urllib.request.Request(self.API_URL, data=data, headers=headers)
+                with urllib.request.urlopen(req, timeout=10) as resp:
+                    result = json.loads(resp.read().decode("utf-8"))
+                    # Normalize null data to empty dict for safe .get() chaining.
+                    # Linear returns {"data": null, "errors": [...]} on errors,
+                    # and .get("data", {}) returns None (key exists, value is null).
+                    if result.get("data") is None:
+                        result["data"] = {}
+                    self._log_operation(query, variables, result)
+                    return result
+            except urllib.error.HTTPError as e:
+                if e.code == 429 and attempt < self.MAX_RETRIES - 1:
+                    delay = self.RETRY_DELAY * (2 ** attempt)
+                    print(f"Rate limited, retrying in {delay}s...", file=sys.stderr)
+                    time.sleep(delay)
+                    continue
+                raise
+            except (urllib.error.URLError, TimeoutError):
+                if attempt < self.MAX_RETRIES - 1:
+                    delay = self.RETRY_DELAY * (2 ** attempt)
+                    print(f"Network error, retrying in {delay}s...", file=sys.stderr)
+                    time.sleep(delay)
+                    continue
+                raise
+
+        return {"errors": [{"message": "Max retries exceeded"}]}
+
+    def mutate(self, mutation: str, variables: Optional[dict] = None) -> dict:
+        return self.query(mutation, variables)
+
+    def resolve_issue_id(self, identifier: str) -> Optional[str]:
+        """Resolve issue identifier (e.g., ENG-123) to Linear UUID."""
+        if "-" in identifier and len(identifier) > 30:
+            return identifier
+        if identifier in self._id_cache:
+            return self._id_cache[identifier]
+        result = self.query(
+            """query($term: String!) {
+                searchIssues(term: $term, first: 1) {
+                    nodes { id identifier }
+                }
+            }""",
+            {"term": identifier},
+        )
+        nodes = (result.get("data") or {}).get("searchIssues", {}).get("nodes", [])
+        if nodes:
+            self._id_cache[identifier] = nodes[0]["id"]
+            return nodes[0]["id"]
+        return None
+
+    def resolve_user_id(self, user_query: str) -> tuple[Optional[str], Optional[str]]:
+        """Resolve user email/name to (user_id, user_name)."""
+        if user_query.lower() == "me":
+            result = self.query("query { viewer { id name } }")
+            viewer = result.get("data", {}).get("viewer")
+            return (viewer["id"], viewer["name"]) if viewer else (None, None)
+
+        if self._team_members is None:
+            result = self.query(
+                """query($teamId: String!) {
+                    team(id: $teamId) {
+                        members { nodes { id name email } }
+                    }
+                }""",
+                {"teamId": self.team_id},
+            )
+            self._team_members = result.get("data", {}).get("team", {}).get("members", {}).get("nodes", [])
+
+        for member in self._team_members:
+            if user_query.lower() in member.get("email", "").lower() or \
+               user_query.lower() in member.get("name", "").lower():
+                return member["id"], member["name"]
+        return None, None
+
+    def get_state_id(self, flydocs_status: str) -> Optional[str]:
+        linear_state_name = self.status_mapping.get(flydocs_status)
+        if not linear_state_name:
+            return None
+        result = self.query(
+            """query($teamId: ID!) {
+                workflowStates(filter: { team: { id: { eq: $teamId } } }) {
+                    nodes { id name }
+                }
+            }""",
+            {"teamId": self.team_id},
+        )
+        states = result.get("data", {}).get("workflowStates", {}).get("nodes", [])
+        for state in states:
+            if state["name"].lower() == linear_state_name.lower():
+                return state["id"]
+        return None
+
+    def build_product_scope(self, filters: dict) -> dict:
+        """Apply product scope to an existing filter dict.
+
+        Priority cascade:
+          1. activeProjects set → filter to those projects
+          2. product.labelIds set → filter to issues with ALL those labels
+          3. Neither set → no additional filter (team-wide)
+        """
+        active = self.workspace.get("activeProjects", [])
+        if active:
+            if len(active) == 1:
+                filters["project"] = {"id": {"eq": active[0]}}
+            else:
+                filters["project"] = {"id": {"in": active}}
+            return filters
+
+        label_ids = self.workspace.get("product", {}).get("labelIds", [])
+        if label_ids:
+            if len(label_ids) == 1:
+                filters["labels"] = {"id": {"eq": label_ids[0]}}
+            else:
+                # Multiple labels: issue must have ALL — use AND conditions
+                label_conditions = [{"labels": {"id": {"eq": lid}}} for lid in label_ids]
+                return {"and": [filters, *label_conditions]}
+            return filters
+
+        return filters
+
+    def get_category_label_id(self, category: str) -> Optional[str]:
+        return self.issue_labels.get("category", {}).get(category)
+
+    def get_other_label_id(self, label: str) -> Optional[str]:
+        return self.issue_labels.get("other", {}).get(label)
+
+    def get_active_cycle(self) -> Optional[dict]:
+        if self._active_cycle is not None:
+            return self._active_cycle
+        result = self.query(
+            """query($teamId: ID!) {
+                cycles(filter: {
+                    team: { id: { eq: $teamId } },
+                    isActive: { eq: true }
+                }, first: 1) {
+                    nodes { id name number startsAt endsAt }
+                }
+            }""",
+            {"teamId": self.team_id},
+        )
+        cycles = result.get("data", {}).get("cycles", {}).get("nodes", [])
+        self._active_cycle = cycles[0] if cycles else None
+        return self._active_cycle
+
+    def _log_operation(self, query: str, variables: Optional[dict], result: dict):
+        self.log_path.parent.mkdir(parents=True, exist_ok=True)
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "query_hash": hash(query) % 10000,
+            "variables": variables,
+            "success": "errors" not in result,
+        }
+        with open(self.log_path, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+
+
+def find_project_root() -> Path:
+    current = Path.cwd()
+    while current != current.parent:
+        if (current / ".flydocs").is_dir():
+            return current
+        current = current.parent
+    return Path.cwd()
+
+
+_client: Optional[FlyDocsClient] = None
+
+
+def get_client() -> FlyDocsClient:
+    global _client
+    if _client is None:
+        _client = FlyDocsClient()
+    return _client
+
+
+def output_json(data: dict | list) -> None:
+    """Print JSON to stdout — standard contract output."""
+    print(json.dumps(data))
+
+
+def fail(message: str) -> None:
+    """Print error to stderr and exit 1."""
+    print(message, file=sys.stderr)
+    sys.exit(1)

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

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Get full details for an issue."""
+
+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="Get issue details")
+parser.add_argument("ref", help="Issue reference (e.g., ENG-123)")
+parser.add_argument("--fields", choices=["basic", "full"], default="full",
+                    help="basic = no comments, full = with comments (default)")
+args = parser.parse_args()
+
+client = get_client()
+
+issue_uuid = client.resolve_issue_id(args.ref)
+if not issue_uuid:
+    fail(f"Issue not found: {args.ref}")
+
+if args.fields == "basic":
+    query = """query($id: String!) {
+        issue(id: $id) {
+            id identifier title description
+            state { name }
+            assignee { name }
+            priority estimate dueDate
+            project { id name }
+            projectMilestone { id name }
+        }
+    }"""
+else:
+    query = """query($id: String!) {
+        issue(id: $id) {
+            id identifier title description
+            state { name }
+            assignee { name }
+            priority estimate dueDate
+            project { id name }
+            projectMilestone { id name }
+            comments(first: 50) {
+                nodes { id body createdAt user { name } }
+            }
+        }
+    }"""
+
+result = client.query(query, {"id": issue_uuid})
+
+issue = (result.get("data") or {}).get("issue")
+if not issue:
+    fail(f"Issue not found: {args.ref}")
+
+output = {
+    "id": issue["id"],
+    "identifier": issue["identifier"],
+    "title": issue["title"],
+    "description": issue.get("description", ""),
+    "status": issue.get("state", {}).get("name", ""),
+    "assignee": (issue.get("assignee") or {}).get("name", ""),
+    "priority": issue.get("priority", 0),
+    "estimate": issue.get("estimate", 0),
+    "dueDate": issue.get("dueDate") or "",
+    "milestone": (issue.get("projectMilestone") or {}).get("name", ""),
+    "milestoneId": (issue.get("projectMilestone") or {}).get("id", ""),
+    "project": (issue.get("project") or {}).get("name", ""),
+    "projectId": (issue.get("project") or {}).get("id", ""),
+}
+
+if args.fields == "full":
+    output["comments"] = [
+        {"id": c["id"], "body": c["body"], "createdAt": c["createdAt"], "user": c.get("user", {}).get("name", "")}
+        for c in issue.get("comments", {}).get("nodes", [])
+    ]
+
+output_json(output)

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Create a relationship between two issues."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+LINK_TYPES = {"blocks": "blocks", "related": "relatedTo", "duplicate": "duplicate"}
+
+if len(sys.argv) < 4:
+    fail(f"Usage: link.py <ref> <related_ref> <type>\nTypes: {', '.join(LINK_TYPES.keys())}")
+
+ref, related_ref, link_type = sys.argv[1], sys.argv[2], sys.argv[3].lower()
+if link_type not in LINK_TYPES:
+    fail(f"Invalid type: {link_type}. Valid: {', '.join(LINK_TYPES.keys())}")
+
+client = get_client()
+
+issue_uuid = client.resolve_issue_id(ref)
+if not issue_uuid:
+    fail(f"Issue not found: {ref}")
+
+related_uuid = client.resolve_issue_id(related_ref)
+if not related_uuid:
+    fail(f"Related issue not found: {related_ref}")
+
+# Linear enum values can't be passed as variables
+api_type = LINK_TYPES[link_type]
+result = client.query(
+    f"""mutation($issueId: String!, $relatedId: String!) {{
+        issueRelationCreate(input: {{
+            issueId: $issueId,
+            relatedIssueId: $relatedId,
+            type: {api_type}
+        }}) {{
+            success
+        }}
+    }}""",
+    {"issueId": issue_uuid, "relatedId": related_uuid},
+)
+
+if not result.get("data", {}).get("issueRelationCreate", {}).get("success"):
+    fail(f"Failed to link: {result}")
+
+output_json({"success": True, "type": link_type})

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""List cycles (sprints)."""
+
+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="List cycles")
+parser.add_argument("--active", action="store_true", help="Only active cycle")
+args = parser.parse_args()
+
+client = get_client()
+
+filters = {"team": {"id": {"eq": client.team_id}}}
+if args.active:
+    filters["isActive"] = {"eq": True}
+
+result = client.query(
+    """query($filter: CycleFilter!) {
+        cycles(filter: $filter, first: 10, orderBy: startsAt) {
+            nodes { id name number startsAt endsAt }
+        }
+    }""",
+    {"filter": filters},
+)
+
+nodes = result.get("data", {}).get("cycles", {}).get("nodes", [])
+cycles = [
+    {"id": n["id"], "name": n.get("name", ""), "number": n["number"], "startsAt": n["startsAt"], "endsAt": n["endsAt"]}
+    for n in nodes
+]
+output_json(cycles)