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

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

@@ -0,0 +1,724 @@
+"""FlyDocs Unified API Client — tier-aware routing.
+
+Reads tier from .flydocs/config.json and routes operations to either
+the relay REST API (cloud tier) or local filesystem (_local/file_store.py).
+
+Usage:
+    from flydocs_api import get_client, output_json, fail
+    client = get_client()
+    result = client.create_issue(title="New issue", issue_type="feature")
+"""
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Project root discovery
+# ---------------------------------------------------------------------------
+
+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():
+            return current
+        current = current.parent
+    return Path.cwd()
+
+
+# ---------------------------------------------------------------------------
+# Relay backend (cloud tier)
+# ---------------------------------------------------------------------------
+
+class RelayBackend:
+    """REST client for the FlyDocs Relay API."""
+
+    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, project_root: Path, config: dict):
+        self.project_root = project_root
+        self.config = config
+        self.log_path = project_root / ".flydocs" / "logs" / "relay-ops.jsonl"
+
+        self.api_key = self._load_api_key()
+        if not self.api_key:
+            fail(
+                "FLYDOCS_API_KEY not found.\n"
+                "Checked: environment, .env.local, .env, .env.development, .env.production\n"
+                "To get your API key:\n"
+                "  1. Go to app.flydocs.ai → Settings → API Keys\n"
+                "  2. Generate a key (starts with fdk_)\n"
+                "  3. Add FLYDOCS_API_KEY=fdk_... to .env.local"
+            )
+
+        self.workspace_id = config.get("workspaceId")
+        if not self.workspace_id:
+            fail("workspaceId not found in .flydocs/config.json. Run 'flydocs setup'")
+
+        self.repo_slug = self._detect_repo_slug()
+        self.base_url = self._resolve_base_url()
+
+        # Workspace and label helpers (for create_issue label resolution)
+        self.workspace = config.get("workspace", {})
+        self.team_id = config.get("provider", {}).get("teamId")
+
+    def _load_api_key(self) -> Optional[str]:
+        if os.environ.get("FLYDOCS_API_KEY"):
+            return os.environ["FLYDOCS_API_KEY"]
+        for name in [".env.local", ".env", ".env.development", ".env.production"]:
+            env_file = self.project_root / name
+            if env_file.exists():
+                key = self._parse_env_file(env_file, "FLYDOCS_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 _detect_repo_slug(self) -> Optional[str]:
+        try:
+            url = subprocess.check_output(
+                ["git", "remote", "get-url", "origin"],
+                stderr=subprocess.DEVNULL,
+                timeout=5,
+            ).decode().strip()
+            if url.endswith(".git"):
+                url = url[:-4]
+            if ":" in url and "@" in url:
+                return url.split(":")[-1]
+            return "/".join(url.split("/")[-2:])
+        except Exception:
+            return None
+
+    def _resolve_base_url(self) -> str:
+        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:
+        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)
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "X-Workspace": self.workspace_id,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if self.repo_slug:
+            headers["X-Repo"] = self.repo_slug
+
+        data = json.dumps(body).encode("utf-8") if body else None
+
+        for attempt in range(self.MAX_RETRIES):
+            try:
+                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
+                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
+                fail("Network error: unable to reach relay API")
+
+        fail("Max retries exceeded")
+        return {}  # unreachable
+
+    def get(self, path: str, params: Optional[dict] = None) -> dict | list:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, body: Optional[dict] = None) -> dict:
+        return self._request("POST", path, body=body)
+
+    def put(self, path: str, body: Optional[dict] = None) -> dict:
+        return self._request("PUT", path, body=body)
+
+    def patch(self, path: str, body: Optional[dict] = None) -> dict:
+        return self._request("PATCH", path, body=body)
+
+    def delete(self, path: str) -> dict:
+        return self._request("DELETE", path)
+
+    def _log_operation(self, method: str, path: str, status: int, result: dict | list) -> None:
+        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
+
+    def get_category_label_id(self, issue_type: str) -> Optional[str]:
+        labels = self.config.get("issueLabels", {}).get("category", {})
+        return labels.get(issue_type)
+
+    def get_other_label_id(self, label_name: str) -> Optional[str]:
+        labels = self.config.get("issueLabels", {}).get("other", {})
+        return labels.get(label_name)
+
+    def resolve_user_id(self, name_or_id: str) -> tuple[Optional[str], Optional[str]]:
+        """Resolve a user name or ID. Returns (id, displayName)."""
+        # If it looks like a UUID, return as-is
+        if len(name_or_id) == 36 and "-" in name_or_id:
+            return name_or_id, None
+        # Try identity file
+        me_path = self.project_root / ".flydocs" / "me.json"
+        if me_path.exists():
+            try:
+                me = json.loads(me_path.read_text())
+                if me.get("displayName", "").lower() == name_or_id.lower():
+                    return me.get("id"), me.get("displayName")
+            except (json.JSONDecodeError, OSError):
+                pass
+        return name_or_id, None
+
+
+# ---------------------------------------------------------------------------
+# Local backend
+# ---------------------------------------------------------------------------
+
+class LocalBackend:
+    """Filesystem-based backend using _local/file_store.py."""
+
+    def __init__(self, project_root: Path, config: dict):
+        self.project_root = project_root
+        self.config = config
+
+
+# ---------------------------------------------------------------------------
+# Unified client
+# ---------------------------------------------------------------------------
+
+class FlyDocsClient:
+    """Tier-aware client. Routes to relay (cloud) or filesystem (local)."""
+
+    def __init__(self):
+        self.project_root = find_project_root()
+        self.config_path = self.project_root / ".flydocs" / "config.json"
+        self.config = self._load_config()
+        self.tier = self.config.get("tier", "local")
+
+        if self.tier == "cloud":
+            self._relay = RelayBackend(self.project_root, self.config)
+        else:
+            self._relay = None
+            self._local_backend = LocalBackend(self.project_root, self.config)
+
+    def _load_config(self) -> dict:
+        if self.config_path.exists():
+            with open(self.config_path, "r") as f:
+                return json.load(f)
+        return {}
+
+    @property
+    def is_cloud(self) -> bool:
+        return self.tier == "cloud"
+
+    def require_cloud(self, operation: str) -> None:
+        """Fail with clear message if operation requires cloud tier."""
+        if not self.is_cloud:
+            fail(f"{operation} requires cloud tier. Current tier: {self.tier}")
+
+    # --- Relay passthrough (for cloud scripts that need raw HTTP) ---
+
+    @property
+    def relay(self) -> RelayBackend:
+        if self._relay is None:
+            fail("Relay not available on local tier")
+        return self._relay
+
+    # --- Issue operations (tier-aware) ---
+
+    def create_issue(self, **kwargs: object) -> dict:
+        if self.is_cloud:
+            return self._cloud_create_issue(**kwargs)
+        from _local.file_store import create_issue
+        return create_issue(self.project_root, **kwargs)
+
+    def _cloud_create_issue(self, **kwargs: object) -> dict:
+        relay = self.relay
+        auto_resolved: dict[str, str] = {}
+        issue_input: dict = {
+            "teamId": relay.team_id,
+            "title": kwargs.get("title", ""),
+            "description": kwargs.get("description", ""),
+            "priority": kwargs.get("priority", 3),
+        }
+        estimate = kwargs.get("estimate")
+        if estimate:
+            issue_input["estimate"] = estimate
+
+        # Labels — category + triage + repo (auto-resolved)
+        label_ids: list[str] = []
+        issue_type = kwargs.get("issue_type", "")
+        if isinstance(issue_type, str):
+            cat_id = relay.get_category_label_id(issue_type)
+            if cat_id:
+                label_ids.append(cat_id)
+                auto_resolved["categoryLabel"] = issue_type
+        if kwargs.get("triage"):
+            triage_id = relay.get_other_label_id("triage")
+            if triage_id:
+                label_ids.append(triage_id)
+
+        # Repo label for multi-repo workspaces
+        repo_labels = relay.config.get("issueLabels", {}).get("repo", {})
+        topology = relay.config.get("topology", {})
+        topo_type = topology.get("type", 1)
+        if topo_type in (3, 4) and repo_labels:
+            # Detect current repo name from slug
+            slug = relay.repo_slug or ""
+            repo_name = slug.split("/")[-1] if "/" in slug else slug
+            for name, label_id in repo_labels.items():
+                if label_id and name.lower() in repo_name.lower():
+                    if label_id not in label_ids:
+                        label_ids.append(label_id)
+                        auto_resolved["repoLabel"] = name
+                    break
+
+        if label_ids:
+            issue_input["labelIds"] = label_ids
+
+        # Project
+        project_id = kwargs.get("project")
+        if not project_id:
+            active = relay.workspace.get("activeProjects", [])
+            if active:
+                project_id = active[0]
+                auto_resolved["project"] = "activeProjects"
+        if project_id:
+            issue_input["projectId"] = project_id
+
+        # Milestone
+        milestone_id = kwargs.get("milestone")
+        if not milestone_id:
+            milestone_id = relay.workspace.get("defaultMilestoneId")
+            if milestone_id:
+                auto_resolved["milestone"] = "defaultMilestoneId"
+        if milestone_id:
+            issue_input["projectMilestoneId"] = milestone_id
+
+        # Assignee
+        assignee = kwargs.get("assignee")
+        if assignee and isinstance(assignee, str):
+            user_id, _ = relay.resolve_user_id(assignee)
+            if user_id:
+                issue_input["assigneeId"] = user_id
+
+        result = relay.post("/issues", issue_input)
+        issue = result.get("issue", result)
+        response: dict = {
+            "id": issue.get("id", ""),
+            "identifier": issue.get("identifier", ""),
+            "title": issue.get("title", kwargs.get("title", "")),
+            "url": issue.get("url", ""),
+        }
+        if auto_resolved:
+            response["autoResolved"] = auto_resolved
+        return response
+
+    def transition(self, ref: str, status: str, comment: str) -> dict:
+        if self.is_cloud:
+            result = self.relay.post(f"/issues/{ref}/transition", {
+                "status": status.upper(),
+                "comment": comment,
+            })
+            return {
+                "success": result.get("success", True),
+                "issue": result.get("issue", ref),
+                "previousStatus": result.get("previousStatus", ""),
+                "newStatus": result.get("newStatus", status),
+            }
+        from _local.file_store import transition
+        return transition(self.project_root, ref, status, comment)
+
+    def comment(self, ref: str, body: str) -> dict:
+        if self.is_cloud:
+            result = self.relay.post(f"/issues/{ref}/comment", {"body": body})
+            return {
+                "success": result.get("success", True),
+                "commentId": result.get("commentId", ""),
+            }
+        from _local.file_store import add_comment
+        return add_comment(self.project_root, ref, body)
+
+    def list_issues(self, **kwargs: object) -> list[dict]:
+        if self.is_cloud:
+            params: dict = {}
+            for key in ("status", "assignee", "project", "milestone", "limit"):
+                val = kwargs.get(key)
+                if val is not None and val != "":
+                    params[key] = str(val).upper() if key == "status" else str(val)
+            if kwargs.get("active"):
+                params["active"] = "true"
+            if kwargs.get("mine"):
+                params["mine"] = "true"
+            # Product scope cascade (bypassed by explicit --project or --all)
+            if "project" not in params and not kwargs.get("show_all"):
+                active_projects = self.relay.workspace.get("activeProjects", [])
+                if active_projects:
+                    params["project"] = active_projects[0]
+                else:
+                    product_labels = self.relay.workspace.get("product", {}).get("labelIds", [])
+                    if product_labels:
+                        params["label"] = product_labels[0]
+            result = self.relay.get("/issues", params=params)
+            return result if isinstance(result, list) else []
+        from _local.file_store import list_issues
+        return list_issues(
+            self.project_root,
+            status=str(kwargs.get("status", "")),
+            assignee=str(kwargs.get("assignee", "")),
+            limit=int(kwargs.get("limit", 50)),
+        )
+
+    def get_issue(self, ref: str, **kwargs: object) -> dict:
+        if self.is_cloud:
+            params: dict = {}
+            fields = kwargs.get("fields")
+            if fields:
+                params["fields"] = str(fields)
+            return self.relay.get(f"/issues/{ref}", params=params)
+        from _local.file_store import get_issue
+        return get_issue(self.project_root, ref)
+
+    def assign(self, ref: str, assignee: str | None) -> dict:
+        if self.is_cloud:
+            result = self.relay.post(f"/issues/{ref}/assign", {"assignee": assignee})
+            return {
+                "success": result.get("success", True),
+                "issue": result.get("issue", ref),
+                "assignee": result.get("assignee", assignee),
+            }
+        from _local.file_store import assign_issue
+        return assign_issue(self.project_root, ref, assignee)
+
+    def update_description(self, ref: str, text: str) -> dict:
+        if self.is_cloud:
+            result = self.relay.put(f"/issues/{ref}/description", {"text": text})
+            return {
+                "success": result.get("success", True),
+                "issue": result.get("issue", ref),
+            }
+        from _local.file_store import update_description
+        return update_description(self.project_root, ref, text)
+
+    def update_issue(self, ref: str, **fields: object) -> dict:
+        if self.is_cloud:
+            body: dict = {}
+            updated: list[str] = []
+            for key in ("title", "priority", "estimate", "assignee", "description", "comment"):
+                val = fields.get(key)
+                if val is not None:
+                    body[key] = val
+                    updated.append(key)
+            state = fields.get("state")
+            if state and isinstance(state, str):
+                body["state"] = state.upper()
+                updated.append("state")
+            labels = fields.get("labels")
+            if labels and isinstance(labels, str):
+                body["labels"] = [l.strip() for l in labels.split(",") if l.strip()]
+                updated.append("labels")
+            # Milestone resolution
+            milestone = fields.get("milestone")
+            if milestone and isinstance(milestone, str):
+                milestone_id = milestone
+                if len(milestone_id) != 36 or "-" not in milestone_id:
+                    milestones = self.relay.get("/milestones")
+                    match = next((m for m in milestones if m["name"].lower() == milestone_id.lower()), None)
+                    if not match:
+                        fail(f"Milestone not found: {milestone_id}")
+                    milestone_id = match["id"]
+                body["milestoneId"] = milestone_id
+                updated.append("milestone")
+            if not body:
+                fail("No fields to update")
+            result = self.relay.patch(f"/issues/{ref}", body)
+            return {
+                "success": result.get("success", True),
+                "issue": result.get("issue", ref),
+                "updated": updated,
+            }
+        from _local.file_store import update_issue
+        return update_issue(self.project_root, ref, **fields)
+
+    def estimate(self, ref: str, points: int) -> dict:
+        if self.is_cloud:
+            result = self.relay.put(f"/issues/{ref}/estimate", {"estimate": points})
+            return {
+                "success": result.get("success", True),
+                "issue": result.get("issue", ref),
+                "estimate": result.get("estimate", points),
+            }
+        from _local.file_store import estimate_issue
+        return estimate_issue(self.project_root, ref, points)
+
+    def priority(self, ref: str, level: int) -> dict:
+        if self.is_cloud:
+            result = self.relay.put(f"/issues/{ref}/priority", {"priority": level})
+            return {
+                "success": result.get("success", True),
+                "issue": result.get("issue", ref),
+                "priority": result.get("priority", level),
+            }
+        from _local.file_store import priority_issue
+        return priority_issue(self.project_root, ref, level)
+
+    def link(self, ref: str, related_ref: str, link_type: str) -> dict:
+        if self.is_cloud:
+            result = self.relay.post(f"/issues/{ref}/link", {
+                "relatedRef": related_ref,
+                "type": link_type,
+            })
+            return {
+                "success": result.get("success", True),
+                "type": result.get("type", link_type),
+            }
+        from _local.file_store import link_issues
+        return link_issues(self.project_root, ref, related_ref, link_type)
+
+    def assign_milestone(self, ref: str, milestone_id: str) -> dict:
+        self.require_cloud("assign_milestone")
+        result = self.relay.put(f"/issues/{ref}/milestone", {"milestoneId": milestone_id})
+        return {
+            "success": result.get("success", True),
+            "issue": result.get("issue", ref),
+            "milestone": result.get("milestone", milestone_id),
+        }
+
+    def assign_cycle(self, ref: str, cycle_id: str | None = None) -> dict:
+        self.require_cloud("assign_cycle")
+        body: dict = {"cycleId": cycle_id} if cycle_id else {}
+        result = self.relay.put(f"/issues/{ref}/cycle", body)
+        return {
+            "success": result.get("success", True),
+            "issue": result.get("issue", ref),
+            "cycle": result.get("cycle", cycle_id),
+        }
+
+    # --- Project operations (cloud only) ---
+
+    def list_projects(self, **kwargs: object) -> list[dict]:
+        self.require_cloud("list_projects")
+        params: dict = {}
+        if kwargs.get("active"):
+            params["active"] = "true"
+        if kwargs.get("show_all"):
+            params["all"] = "true"
+        result = self.relay.get("/projects", params=params)
+        return result if isinstance(result, list) else []
+
+    def create_project(self, name: str, description: str | None = None) -> dict:
+        self.require_cloud("create_project")
+        body: dict = {"name": name}
+        if description:
+            body["description"] = description
+        result = self.relay.post("/projects", body)
+        return {"id": result["id"], "name": result["name"], "url": result.get("url", "")}
+
+    def list_milestones(self, **kwargs: object) -> list[dict]:
+        self.require_cloud("list_milestones")
+        params: dict = {}
+        if kwargs.get("show_all"):
+            params["all"] = "true"
+        result = self.relay.get("/milestones", params=params)
+        return result if isinstance(result, list) else []
+
+    def create_milestone(self, name: str, project: str | None = None,
+                         target_date: str | None = None) -> dict:
+        self.require_cloud("create_milestone")
+        body: dict = {"name": name}
+        if project:
+            body["projectId"] = project
+        if target_date:
+            body["targetDate"] = target_date
+        return self.relay.post("/milestones", body)
+
+    def update_milestone(self, milestone_id: str, **fields: object) -> dict:
+        self.require_cloud("update_milestone")
+        body: dict = {}
+        for key in ("name", "targetDate", "description"):
+            val = fields.get(key)
+            if val is not None:
+                body[key] = val
+        result = self.relay.patch(f"/milestones/{milestone_id}", body)
+        return {"success": result.get("success", True), "id": milestone_id, "name": result.get("name", "")}
+
+    def delete_milestone(self, milestone_id: str) -> dict:
+        self.require_cloud("delete_milestone")
+        self.relay.delete(f"/milestones/{milestone_id}")
+        return {"success": True, "id": milestone_id}
+
+    def list_cycles(self, active: bool = False) -> list[dict]:
+        self.require_cloud("list_cycles")
+        params: dict = {}
+        if active:
+            params["active"] = "true"
+        result = self.relay.get("/cycles", params=params)
+        return result if isinstance(result, list) else []
+
+    def project_update(self, health: str, body: str, project_id: str | None = None, **_kwargs: object) -> dict:
+        if self.is_cloud:
+            payload: dict = {"health": health, "body": body}
+            if project_id:
+                payload["projectId"] = project_id
+            result = self.relay.post("/projects/update", payload)
+            return {"success": result.get("success", True), "id": result.get("id", "")}
+        from _local.file_store import project_update
+        return project_update(self.project_root, health, body)
+
+    def status_summary(self) -> dict:
+        if self.is_cloud:
+            # Cloud could use relay, but local summary is always available
+            pass
+        from _local.file_store import status_summary
+        return status_summary(self.project_root)
+
+    # --- Workspace operations (cloud only) ---
+
+    def validate_setup(self) -> dict:
+        self.require_cloud("validate_setup")
+        return self.relay.get("/auth/config")
+
+    def list_labels(self) -> list[dict]:
+        self.require_cloud("list_labels")
+        result = self.relay.get("/labels")
+        return result if isinstance(result, list) else []
+
+    def list_statuses(self) -> list[dict]:
+        self.require_cloud("list_statuses")
+        result = self.relay.get("/auth/statuses")
+        return result if isinstance(result, list) else []
+
+    def list_providers(self) -> list[dict]:
+        self.require_cloud("list_providers")
+        result = self.relay.get("/providers")
+        return result if isinstance(result, list) else []
+
+    def list_teams(self) -> list[dict]:
+        self.require_cloud("list_teams")
+        result = self.relay.get("/teams")
+        return result if isinstance(result, list) else []
+
+    def create_team(self, name: str, key: str | None = None,
+                    description: str | None = None, parent: str | None = None) -> dict:
+        self.require_cloud("create_team")
+        body: dict = {"name": name}
+        if key:
+            body["key"] = key
+        if description:
+            body["description"] = description
+        if parent:
+            body["parentId"] = parent
+        result = self.relay.post("/teams", body)
+        return {"id": result["id"], "name": result["name"], "key": result.get("key", "")}
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers
+# ---------------------------------------------------------------------------
+
+_client: Optional[FlyDocsClient] = None
+
+
+def get_client() -> FlyDocsClient:
+    """Get or create singleton client."""
+    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)
+
+
+def resolve_text_input(text_arg: str | None = None, file_arg: str | None = None) -> str | None:
+    """Resolve text from --file > stdin > --text. Shared helper for dispatchers."""
+    if file_arg:
+        path = Path(file_arg)
+        if not path.exists():
+            fail(f"File not found: {file_arg}")
+        return path.read_text()
+    if text_arg is not None:
+        return text_arg
+    if not sys.stdin.isatty():
+        return sys.stdin.read().strip()
+    return None