@flydocs/cli 0.5.0-beta.9 → 0.6.0-alpha.10

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

@@ -1,53 +1,49 @@
-"""FlyDocs Cloud API — Linear GraphQL client.
+"""FlyDocs Cloud API — Relay REST client.
 
-Central module for all Linear API operations.
+Central module for all relay 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 } }")
+    result = client.post("/issues", {"title": "New issue", "type": "feature"})
 """
 
 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."""
+    """Client for FlyDocs Relay REST API with retry logic and config awareness."""
 
-    API_URL = "https://api.linear.app/graphql"
-    MAX_RETRIES = 5
+    DEFAULT_BASE_URL = "https://app.flydocs.ai/api/relay"
+    LOCAL_BASE_URL = "http://localhost:3000/api/relay"
+    MAX_RETRIES = 3
     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.log_path = self.project_root / ".flydocs" / "logs" / "relay-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("ERROR: FLYDOCS_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", {})
+        self.workspace_id = self.config.get("workspaceId")
+        if not self.workspace_id:
+            print("ERROR: workspaceId not found in .flydocs/config.json", file=sys.stderr)
+            print("Run 'flydocs setup' to configure your workspace", file=sys.stderr)
+            sys.exit(1)
 
-        # 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
+        self.base_url = self._resolve_base_url()
 
     def _load_config(self) -> dict:
         if self.config_path.exists():
@@ -56,12 +52,12 @@ class FlyDocsClient:
         return {}
 
     def _load_api_key(self) -> Optional[str]:
-        if os.environ.get("LINEAR_API_KEY"):
-            return os.environ["LINEAR_API_KEY"]
+        if os.environ.get("FLYDOCS_API_KEY"):
+            return os.environ["FLYDOCS_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")
+                key = self._parse_env_file(env_file, "FLYDOCS_API_KEY")
                 if key:
                     return key
         return None
@@ -78,176 +74,123 @@ class FlyDocsClient:
                     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
+    def _resolve_base_url(self) -> str:
+        """Resolve base URL: env var > config > default."""
+        env_url = os.environ.get("FLYDOCS_RELAY_URL")
+        if env_url:
+            return env_url.rstrip("/")
+        config_url = self.config.get("relay", {}).get("url")
+        if config_url:
+            return config_url.rstrip("/")
+        return self.DEFAULT_BASE_URL
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None,
+                 params: Optional[dict] = None) -> dict:
+        """Make an HTTP request to the relay API."""
+        import urllib.request
+        import urllib.error
+        import urllib.parse
+
+        url = f"{self.base_url}{path}"
+        if params:
+            filtered = {k: v for k, v in params.items() if v is not None and v != ""}
+            if filtered:
+                url += "?" + urllib.parse.urlencode(filtered, doseq=True)
 
-        data = json.dumps(payload).encode("utf-8")
         headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "X-Workspace": self.workspace_id,
             "Content-Type": "application/json",
-            "Authorization": self.api_key,
+            "Accept": "application/json",
         }
 
+        data = json.dumps(body).encode("utf-8") if body else None
+
         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)
+                req = urllib.request.Request(url, data=data, headers=headers, method=method)
+                with urllib.request.urlopen(req, timeout=15) as resp:
+                    response_body = resp.read().decode("utf-8")
+                    result = json.loads(response_body) if response_body else {}
+                    self._log_operation(method, path, resp.status, result)
                     return result
             except urllib.error.HTTPError as e:
+                error_body = e.read().decode("utf-8") if e.fp else ""
+                try:
+                    error_data = json.loads(error_body) if error_body else {}
+                except json.JSONDecodeError:
+                    error_data = {"error": error_body}
+                self._log_operation(method, path, e.code, error_data)
+
                 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
+                if e.code >= 500 and attempt < self.MAX_RETRIES - 1:
+                    delay = self.RETRY_DELAY * (2 ** attempt)
+                    print(f"Server error ({e.code}), retrying in {delay}s...", file=sys.stderr)
+                    time.sleep(delay)
+                    continue
+
+                error_msg = error_data.get("error", f"HTTP {e.code}")
+                error_code = error_data.get("code", "UNKNOWN")
+                provider = error_data.get("provider_error", "")
+                msg = f"Relay API error ({error_code}): {error_msg}"
+                if provider:
+                    msg += f" — provider: {provider}"
+                fail(msg)
             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")
+                fail("Network error: unable to reach relay API")
+
+        fail("Max retries exceeded")
+        return {}  # unreachable but satisfies type checker
+
+    def get(self, path: str, params: Optional[dict] = None) -> dict | list:
+        """GET request to relay API."""
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, body: Optional[dict] = None) -> dict:
+        """POST request to relay API."""
+        return self._request("POST", path, body=body)
+
+    def put(self, path: str, body: Optional[dict] = None) -> dict:
+        """PUT request to relay API."""
+        return self._request("PUT", path, body=body)
+
+    def patch(self, path: str, body: Optional[dict] = None) -> dict:
+        """PATCH request to relay API."""
+        return self._request("PATCH", path, body=body)
+
+    def delete(self, path: str) -> dict:
+        """DELETE request to relay API."""
+        return self._request("DELETE", path)
+
+    def _log_operation(self, method: str, path: str, status: int, result: dict | list):
+        """Log operation metadata to local log file."""
+        try:
+            from datetime import datetime, timezone
+            self.log_path.parent.mkdir(parents=True, exist_ok=True)
+            entry = {
+                "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+                "method": method,
+                "path": path,
+                "status": status,
+                "success": 200 <= status < 300,
+            }
+            with open(self.log_path, "a") as f:
+                f.write(json.dumps(entry) + "\n")
+        except Exception:
+            pass  # logging should never break operations
 
 
 def find_project_root() -> Path:
+    """Walk up from cwd to find .flydocs/ directory."""
     current = Path.cwd()
     while current != current.parent:
         if (current / ".flydocs").is_dir():
@@ -260,6 +203,7 @@ _client: Optional[FlyDocsClient] = None
 
 
 def get_client() -> FlyDocsClient:
+    """Get or create singleton client."""
     global _client
     if _client is None:
         _client = FlyDocsClient()

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

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""Get the provider's estimate scale via the FlyDocs Relay API.
+
+Returns the valid estimate values for the connected provider.
+Linear: fixed scale [0, 1, 2, 3, 5, 8, 13, 21]
+Jira: freeform (any positive number)
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json
+
+
+def main():
+    client = get_client()
+    result = client.get("/auth/estimates")
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Get full details for an issue."""
+"""Get full details for an issue via the FlyDocs Relay API."""
 
 import argparse
 import sys
@@ -14,64 +14,11 @@ 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}")
-
+params: dict = {}
 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})
+    params["fields"] = "basic"
 
-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", [])
-    ]
+client = get_client()
+result = client.get(f"/issues/{args.ref}", params=params)
 
-output_json(output)
+output_json(result)

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Create a relationship between two issues."""
+"""Create a link between two issues via the FlyDocs Relay API."""
 
 import sys
 from pathlib import Path
@@ -7,41 +7,22 @@ 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()
+    fail("Usage: link.py <ref> <related_ref> <type>")
 
-issue_uuid = client.resolve_issue_id(ref)
-if not issue_uuid:
-    fail(f"Issue not found: {ref}")
+ref, related_ref, link_type = sys.argv[1], sys.argv[2], sys.argv[3]
 
-related_uuid = client.resolve_issue_id(related_ref)
-if not related_uuid:
-    fail(f"Related issue not found: {related_ref}")
+valid_types = ("blocks", "related", "duplicate")
+if link_type not in valid_types:
+    fail(f"Link type must be one of: {', '.join(valid_types)}")
 
-# 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})
+client = get_client()
+result = client.post(f"/issues/{ref}/link", {
+    "relatedRef": related_ref,
+    "type": link_type,
+})
+
+output_json({
+    "success": result.get("success", True),
+    "type": result.get("type", link_type),
+})

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

@@ -1,35 +1,28 @@
 #!/usr/bin/env python3
-"""List cycles (sprints)."""
+"""List cycles 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="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)
+from flydocs_api import get_client, output_json
+
+
+def main():
+    parser = argparse.ArgumentParser(description="List cycles")
+    parser.add_argument("--active", action="store_true")
+    args = parser.parse_args()
+
+    params: dict = {}
+    if args.active:
+        params["active"] = "true"
+
+    client = get_client()
+    result = client.get("/cycles", params=params)
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()