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

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

@@ -1,21 +0,0 @@
-#!/usr/bin/env python3
-"""Delete a milestone via the FlyDocs Relay API."""
-
-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) < 2:
-    fail("Usage: delete_milestone.py <milestone_id>")
-
-milestone_id = sys.argv[1]
-
-client = get_client()
-result = client.delete(f"/milestones/{milestone_id}")
-
-output_json({
-    "success": result.get("success", True),
-    "id": result.get("id", milestone_id),
-})

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

@@ -1,33 +0,0 @@
-#!/usr/bin/env python3
-"""Set estimate on an issue via the FlyDocs Relay API.
-
-The relay validates the estimate against the provider's scale server-side.
-Use get_estimate_scale.py to discover valid values before setting.
-"""
-
-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> <points>")
-
-ref = sys.argv[1]
-try:
-    estimate = int(sys.argv[2])
-except ValueError:
-    fail("Estimate must be a number")
-
-if estimate < 0:
-    fail("Estimate must be a non-negative integer")
-
-client = get_client()
-result = client.put(f"/issues/{ref}/estimate", {"estimate": estimate})
-
-output_json({
-    "success": result.get("success", True),
-    "issue": result.get("issue", ref),
-    "estimate": result.get("estimate", estimate),
-})

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

@@ -1,241 +0,0 @@
-"""FlyDocs Cloud API — Relay REST client.
-
-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.post("/issues", {"title": "New issue", "type": "feature"})
-"""
-
-import json
-import os
-import subprocess
-import sys
-import time
-from pathlib import Path
-from typing import Optional
-
-
-class FlyDocsClient:
-    """Client for FlyDocs Relay REST API with retry logic and config awareness."""
-
-    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" / "relay-ops.jsonl"
-
-        self.config = self._load_config()
-        self.api_key = self._load_api_key()
-        if not self.api_key:
-            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.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)
-
-        self.repo_slug = self._detect_repo_slug()
-        self.base_url = self._resolve_base_url()
-
-    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("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, "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]:
-        """Derive owner/repo slug from git remote origin URL."""
-        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]  # SSH: git@github.com:owner/repo
-            return "/".join(url.split("/")[-2:])  # HTTPS
-        except Exception:
-            return None
-
-    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)
-
-        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 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():
-            return current
-        current = current.parent
-    return Path.cwd()
-
-
-_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)

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

@@ -1,125 +0,0 @@
-#!/usr/bin/env python3
-"""Generate config.json from the relay's canonical workspace config.
-
-Calls GET /config/generate which returns server-owned fields (workspace,
-issueLabels, provider, statusMapping, etc.). Merges with local-only fields
-(tier, detectedStack, skills, designSystem, aiLabor, paths) to produce
-the final .flydocs/config.json.
-
-This replaces the pattern where each setup script (set_provider, set_team,
-set_labels, set_status_mapping) independently wrote to local config.
-Now those scripts only POST to the relay, and this script pulls the
-merged result once at the end of setup.
-
-Usage:
-    python3 generate_config.py
-    python3 generate_config.py --dry-run   # Print merged config without writing
-"""
-
-import argparse
-import json
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-from flydocs_api import get_client, output_json, fail
-
-# Fields owned by the server — overwritten from generate response
-SERVER_OWNED_FIELDS = {
-    "workspaceId",
-    "setupComplete",
-    "workspace",
-    "issueLabels",
-}
-
-# Fields owned locally — never overwritten by generate
-LOCAL_ONLY_FIELDS = {
-    "version",
-    "sourceRepo",
-    "tier",
-    "paths",
-    "detectedStack",
-    "skills",
-    "designSystem",
-    "aiLabor",
-}
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Generate config from relay")
-    parser.add_argument(
-        "--dry-run",
-        action="store_true",
-        help="Print merged config without writing to disk",
-    )
-    args = parser.parse_args()
-
-    client = get_client()
-
-    # Fetch server-owned config from relay
-    response = client.get("/config/generate")
-
-    if not response.get("valid", False):
-        missing = response.get("missing", [])
-        warnings = response.get("warnings", [])
-        parts = []
-        if missing:
-            parts.append(f"missing: {', '.join(missing)}")
-        if warnings:
-            parts.append(f"warnings: {', '.join(warnings)}")
-        detail = "; ".join(parts) if parts else "unknown reason"
-        print(f"WARNING: Config not fully valid — {detail}", file=sys.stderr)
-
-    server_config = response.get("config", {})
-
-    # Read existing local config
-    config_path = client.config_path
-    if config_path.exists():
-        with open(config_path, "r") as f:
-            local_config = json.load(f)
-    else:
-        local_config = {}
-
-    # Merge: server-owned fields overwrite, local-only fields preserved
-    merged = dict(local_config)
-
-    # Apply server-owned fields
-    if "workspaceId" in server_config:
-        merged["workspaceId"] = server_config["workspaceId"]
-    if "setupComplete" in server_config:
-        merged["setupComplete"] = server_config["setupComplete"]
-    if "workspace" in server_config:
-        merged["workspace"] = server_config["workspace"]
-    if "issueLabels" in server_config:
-        merged["issueLabels"] = server_config["issueLabels"]
-
-    # Store configVersion for freshness tracking
-    if "configVersion" in response:
-        merged["configVersion"] = response["configVersion"]
-
-    # Clean up ghost fields that are now server-owned
-    # These were written by old setup scripts but aren't in the TS type system
-    for ghost in ("provider", "statusMapping", "labels"):
-        merged.pop(ghost, None)
-
-    if args.dry_run:
-        output_json(merged)
-        return
-
-    # Write merged config
-    config_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(config_path, "w") as f:
-        json.dump(merged, f, indent=2)
-        f.write("\n")
-
-    output_json({
-        "success": True,
-        "configVersion": response.get("configVersion"),
-        "valid": response.get("valid", False),
-        "missing": response.get("missing", []),
-        "warnings": response.get("warnings", []),
-    })
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,23 +0,0 @@
-#!/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,24 +0,0 @@
-#!/usr/bin/env python3
-"""Get full details for an issue 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="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()
-
-params: dict = {}
-if args.fields == "basic":
-    params["fields"] = "basic"
-
-client = get_client()
-result = client.get(f"/issues/{args.ref}", params=params)
-
-output_json(result)

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

@@ -1,103 +0,0 @@
-#!/usr/bin/env python3
-"""Fetch current user identity from the FlyDocs Relay API.
-
-Calls GET /auth/me (no X-Workspace needed — user-scoped endpoint).
-Writes .flydocs/me.json for local identity resolution (--mine filters,
-display name in comments, etc.). This file is gitignored.
-
-Usage:
-    python3 get_me.py
-"""
-
-import json
-import os
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-from flydocs_api import find_project_root, output_json, fail
-
-
-def load_api_key(project_root: Path) -> str | None:
-    """Load API key from environment or .env files."""
-    if os.environ.get("FLYDOCS_API_KEY"):
-        return os.environ["FLYDOCS_API_KEY"]
-    for name in [".env.local", ".env"]:
-        env_file = project_root / name
-        if env_file.exists():
-            with open(env_file, "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() == "FLYDOCS_API_KEY":
-                        v = v.strip().strip("\"'")
-                        return v if v else None
-    return None
-
-
-def resolve_base_url() -> str:
-    """Resolve relay base URL from environment."""
-    env_url = os.environ.get("FLYDOCS_RELAY_URL")
-    if env_url:
-        return env_url.rstrip("/")
-    return "https://app.flydocs.ai/api/relay"
-
-
-def main() -> None:
-    import urllib.request
-    import urllib.error
-
-    project_root = find_project_root()
-    api_key = load_api_key(project_root)
-    if not api_key:
-        fail("FLYDOCS_API_KEY not found. Set in environment or .env/.env.local file")
-
-    base_url = resolve_base_url()
-    url = f"{base_url}/auth/me"
-
-    headers = {
-        "Authorization": f"Bearer {api_key}",
-        "Accept": "application/json",
-    }
-
-    try:
-        req = urllib.request.Request(url, headers=headers, method="GET")
-        with urllib.request.urlopen(req, timeout=15) as resp:
-            result = json.loads(resp.read().decode("utf-8"))
-    except urllib.error.HTTPError as e:
-        error_body = e.read().decode("utf-8") if e.fp else ""
-        try:
-            error_data = json.loads(error_body)
-        except json.JSONDecodeError:
-            error_data = {"error": error_body}
-        fail(f"API error ({e.code}): {error_data.get('error', 'Unknown')}")
-    except (urllib.error.URLError, TimeoutError):
-        fail("Network error: unable to reach relay API")
-
-    # Write me.json
-    me_data = {
-        "displayName": result.get("displayName"),
-        "email": result.get("email"),
-        "providerId": result.get("providerId"),
-        "provider": result.get("provider"),
-        "providerIdentities": result.get("providerIdentities", []),
-        "preferences": result.get("preferences", {}),
-    }
-
-    me_path = project_root / ".flydocs" / "me.json"
-    me_path.parent.mkdir(parents=True, exist_ok=True)
-    me_path.write_text(json.dumps(me_data, indent=2) + "\n")
-
-    output_json({
-        "success": True,
-        "displayName": me_data["displayName"],
-        "email": me_data["email"],
-        "provider": me_data["provider"],
-        "meJson": str(me_path),
-    })
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,28 +0,0 @@
-#!/usr/bin/env python3
-"""Create a link between two issues via the FlyDocs Relay API."""
-
-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) < 4:
-    fail("Usage: link.py <ref> <related_ref> <type>")
-
-ref, related_ref, link_type = sys.argv[1], sys.argv[2], sys.argv[3]
-
-valid_types = ("blocks", "related", "duplicate")
-if link_type not in valid_types:
-    fail(f"Link type must be one of: {', '.join(valid_types)}")
-
-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,28 +0,0 @@
-#!/usr/bin/env python3
-"""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
-
-
-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()

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

@@ -1,44 +0,0 @@
-#!/usr/bin/env python3
-"""List issues with optional filters 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
-
-
-def main():
-    parser = argparse.ArgumentParser(description="List issues")
-    parser.add_argument("--status", default="", help="Single status or comma-separated: READY,IMPLEMENTING,BLOCKED")
-    parser.add_argument("--active", action="store_true", help="All non-terminal states")
-    parser.add_argument("--project", default="")
-    parser.add_argument("--assignee", default="")
-    parser.add_argument("--milestone", default="", help="Filter by milestone ID")
-    parser.add_argument("--mine", action="store_true")
-    parser.add_argument("--limit", type=int, default=50)
-    args = parser.parse_args()
-
-    params: dict = {"limit": str(args.limit)}
-    if args.status:
-        params["status"] = args.status.upper()
-    if args.active:
-        params["active"] = "true"
-    if args.project:
-        params["project"] = args.project
-    if args.assignee:
-        params["assignee"] = args.assignee
-    if args.milestone:
-        params["milestone"] = args.milestone
-    if args.mine:
-        params["mine"] = "true"
-
-    client = get_client()
-    result = client.get("/issues", params=params)
-
-    output_json(result)
-
-
-if __name__ == "__main__":
-    main()