@flydocs/cli 0.6.0-alpha.1 → 0.6.0-alpha.10

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

@@ -0,0 +1,21 @@
+#!/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,5 +1,9 @@
 #!/usr/bin/env python3
-"""Set estimate on an issue via the FlyDocs Relay API."""
+"""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
@@ -8,16 +12,16 @@ 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>")
+    fail("Usage: estimate.py <ref> <points>")
 
 ref = sys.argv[1]
 try:
     estimate = int(sys.argv[2])
 except ValueError:
-    fail("Estimate must be a number (1-5)")
+    fail("Estimate must be a number")
 
-if estimate not in (1, 2, 3, 5):
-    fail("Estimate must be 1 (XS), 2 (S), 3 (M), or 5 (L)")
+if estimate < 0:
+    fail("Estimate must be a non-negative integer")
 
 client = get_client()
 result = client.put(f"/issues/{ref}/estimate", {"estimate": estimate})

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

@@ -37,6 +37,12 @@ class FlyDocsClient:
             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.base_url = self._resolve_base_url()
 
     def _load_config(self) -> dict:
@@ -93,6 +99,7 @@ class FlyDocsClient:
 
         headers = {
             "Authorization": f"Bearer {self.api_key}",
+            "X-Workspace": self.workspace_id,
             "Content-Type": "application/json",
             "Accept": "application/json",
         }
@@ -160,6 +167,10 @@ class FlyDocsClient:
         """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:

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/list_providers.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""List available providers 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
+
+
+def main():
+    client = get_client()
+    result = client.get("/providers")
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""List provider workflow states 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
+
+
+def main():
+    client = get_client()
+    result = client.get("/auth/statuses")
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""List available teams via the FlyDocs Relay API."""
+"""List available teams/projects via the FlyDocs Relay API."""
 
 import sys
 from pathlib import Path

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Refresh label config from the relay — validates and updates local config.
+
+Fetches current team labels from the relay, compares against local config,
+and reports any stale or missing label IDs. With --fix, updates local config
+to match the relay's current state.
+"""
+
+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
+
+
+def main():
+    fix_mode = "--fix" in sys.argv
+
+    client = get_client()
+
+    # Fetch current labels from relay
+    labels = client.get("/labels")
+    label_map = {l["id"]: l["name"] for l in labels}
+    label_by_name = {l["name"].lower(): l["id"] for l in labels}
+
+    # Load local config
+    config_path = client.config_path
+    if not config_path.exists():
+        fail("No .flydocs/config.json found")
+
+    with open(config_path, "r") as f:
+        config = json.load(f)
+
+    issue_labels = config.get("issueLabels", {})
+    stale: list[dict] = []
+    valid: list[dict] = []
+
+    # Check each label ID in config against relay
+    for category, entries in issue_labels.items():
+        if isinstance(entries, dict):
+            for key, label_id in entries.items():
+                if label_id in label_map:
+                    valid.append({"category": category, "key": key, "id": label_id, "name": label_map[label_id]})
+                else:
+                    # Try to find by key name
+                    resolved = label_by_name.get(key.lower())
+                    stale.append({
+                        "category": category,
+                        "key": key,
+                        "staleId": label_id,
+                        "resolvedId": resolved,
+                        "resolvedName": key if resolved else None,
+                    })
+
+    if fix_mode and stale:
+        # Update stale IDs in config
+        fixed = 0
+        for item in stale:
+            if item["resolvedId"]:
+                issue_labels[item["category"]][item["key"]] = item["resolvedId"]
+                fixed += 1
+
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+        output_json({
+            "success": True,
+            "valid": len(valid),
+            "stale": len(stale),
+            "fixed": fixed,
+            "unfixable": len(stale) - fixed,
+            "details": stale,
+        })
+    else:
+        output_json({
+            "valid": len(valid),
+            "stale": len(stale),
+            "totalProviderLabels": len(labels),
+            "details": stale if stale else "All label IDs are current",
+            "hint": "Run with --fix to update stale IDs" if stale else None,
+        })
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Set provider identity via the FlyDocs Relay API.
+
+Binds the user's provider-specific ID to their FlyDocs user record.
+Once set, ?mine=true resolves via exact provider ID matching.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+VALID_PROVIDERS = ("linear", "jira", "gitlab")
+
+if len(sys.argv) < 3:
+    fail(f"Usage: set_identity.py <provider> <provider-user-id>\n  Providers: {', '.join(VALID_PROVIDERS)}")
+
+provider = sys.argv[1].lower()
+provider_id = sys.argv[2]
+
+if provider not in VALID_PROVIDERS:
+    fail(f"Invalid provider: {provider}. Must be one of: {', '.join(VALID_PROVIDERS)}")
+
+if not provider_id:
+    fail("Provider user ID cannot be empty")
+
+client = get_client()
+result = client.post("/auth/identity", {
+    "provider": provider,
+    "providerId": provider_id,
+})
+
+output_json({
+    "success": result.get("success", True),
+    "provider": result.get("provider", provider),
+    "providerId": result.get("providerId", provider_id),
+})

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

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Get or set user preferences via the FlyDocs Relay API.
+
+With no arguments, returns current preferences (GET).
+With flags, updates preferences (POST).
+"""
+
+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="Get or set user preferences")
+    parser.add_argument("--workspace", default=None, help="Default workspace ID")
+    parser.add_argument("--assignee", default=None, help="Default assignee ('self' or user ID)")
+    parser.add_argument("--display", default=None, help="Display preferences (JSON string)")
+    args = parser.parse_args()
+
+    client = get_client()
+
+    # If no flags provided, GET current preferences
+    if args.workspace is None and args.assignee is None and args.display is None:
+        result = client.get("/auth/preferences")
+        output_json(result)
+        return
+
+    # Build update body from provided flags
+    body: dict = {}
+    if args.workspace is not None:
+        body["defaultWorkspaceId"] = args.workspace
+    if args.assignee is not None:
+        body["defaultAssignee"] = args.assignee
+    if args.display is not None:
+        body["displayPreferences"] = args.display
+
+    result = client.post("/auth/preferences", body)
+
+    output_json({
+        "success": result.get("success", True),
+        "preferences": result.get("preferences", body),
+    })
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Set provider preference via the FlyDocs Relay API.
+
+Stores the provider type on the relay (for server-side routing)
+and updates the local config (for display/reference).
+"""
+
+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
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Set provider preference")
+    parser.add_argument(
+        "provider_type",
+        choices=["linear", "jira"],
+        help="Provider type",
+    )
+    args = parser.parse_args()
+
+    client = get_client()
+    result = client.post("/auth/provider", {"providerType": args.provider_type})
+
+    # Update local config with provider type
+    config_path = client.config_path
+    if config_path.exists():
+        with open(config_path, "r") as f:
+            config = json.load(f)
+        if "provider" not in config:
+            config["provider"] = {"type": args.provider_type, "teamId": None}
+        else:
+            config["provider"]["type"] = args.provider_type
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Set status mapping on the relay API key.
+
+Maps provider workflow states to FlyDocs statuses. Pass "auto" for
+case-insensitive auto-mapping, or provide a manual mapping object.
+
+Usage:
+    set_status_mapping.py --auto
+    set_status_mapping.py --mapping '{"BACKLOG":"Backlog","IMPLEMENTING":"In Progress",...}'
+    echo '{"mapping":"auto"}' | set_status_mapping.py
+"""
+
+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
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Set status mapping on relay")
+    parser.add_argument(
+        "--auto",
+        action="store_true",
+        help="Auto-map provider states to FlyDocs statuses by name",
+    )
+    parser.add_argument(
+        "--mapping",
+        default=None,
+        help="JSON object mapping FlyDocs statuses to provider state names",
+    )
+    args = parser.parse_args()
+
+    if args.auto:
+        body: dict = {"mapping": "auto"}
+    elif args.mapping is not None:
+        try:
+            body = {"mapping": json.loads(args.mapping)}
+        except json.JSONDecodeError:
+            fail("Invalid JSON for --mapping")
+    elif not sys.stdin.isatty():
+        try:
+            body = json.loads(sys.stdin.read().strip())
+        except json.JSONDecodeError:
+            fail("Invalid JSON on stdin")
+    else:
+        fail("Provide --auto, --mapping '{...}', or pipe JSON via stdin")
+
+    client = get_client()
+    result = client.post("/auth/statuses", body)
+
+    # Store status mapping in local config as reference
+    config_path = client.config_path
+    if config_path.exists():
+        with open(config_path, "r") as f:
+            config = json.load(f)
+        if isinstance(result.get("mapping"), dict):
+            config["statusMapping"] = result["mapping"]
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
-"""Set team preference via the FlyDocs Relay API.
+"""Set team/project preference via the FlyDocs Relay API.
 
 Stores the team preference on the relay (for server-side scoping)
 and updates the local config (for display/reference).
+For Jira, this sets the active Jira project.
 """
 
 import argparse
@@ -15,8 +16,8 @@ from flydocs_api import get_client, output_json, fail
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Set team preference")
-    parser.add_argument("team_id", help="Linear team UUID")
+    parser = argparse.ArgumentParser(description="Set team or project preference")
+    parser.add_argument("team_id", help="Provider team/workspace UUID")
     args = parser.parse_args()
 
     client = get_client()
@@ -28,7 +29,7 @@ def main():
         with open(config_path, "r") as f:
             config = json.load(f)
         if "provider" not in config:
-            config["provider"] = {"type": "linear", "teamId": None}
+            config["provider"] = {"type": None, "teamId": None}
         config["provider"]["teamId"] = args.team_id
         with open(config_path, "w") as f:
             json.dump(config, f, indent=2)

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

@@ -13,13 +13,14 @@ def main():
     parser = argparse.ArgumentParser(description="Update issue fields")
     parser.add_argument("ref", help="Issue reference (e.g., ENG-123)")
     parser.add_argument("--title", default=None)
-    parser.add_argument("--priority", type=int, choices=range(5))
-    parser.add_argument("--estimate", type=int, choices=range(1, 6))
+    parser.add_argument("--priority", type=int, help="Priority (0-4, relay translates per provider)")
+    parser.add_argument("--estimate", type=int, help="Estimate points (relay translates per provider)")
     parser.add_argument("--assignee", default=None)
     parser.add_argument("--state", default=None)
     parser.add_argument("--description", default=None)
     parser.add_argument("--description-file", default=None)
     parser.add_argument("--labels", default=None, help="Comma-separated label names")
+    parser.add_argument("--milestone", default=None, help="Milestone ID or name (resolved by name lookup)")
     parser.add_argument("--comment", default=None)
     args = parser.parse_args()
 
@@ -65,10 +66,27 @@ def main():
         body["comment"] = args.comment
         updated_fields.append("comment")
 
-    if not body:
-        fail("No fields to update. Use --title, --priority, --estimate, --assignee, --state, --description, --labels, or --comment")
+    if not body and args.milestone is None:
+        fail("No fields to update. Use --title, --priority, --estimate, --assignee, --state, --description, --labels, --milestone, or --comment")
 
     client = get_client()
+
+    if args.milestone is not None:
+        milestone_id = args.milestone
+        # If it doesn't look like a UUID, resolve by name
+        if len(milestone_id) != 36 or "-" not in milestone_id:
+            milestones = client.get("/milestones")
+            match = None
+            for m in milestones:
+                if m["name"].lower() == milestone_id.lower():
+                    match = m
+                    break
+            if not match:
+                fail(f"Milestone not found: {milestone_id}")
+            milestone_id = match["id"]
+        body["milestoneId"] = milestone_id
+        updated_fields.append("milestone")
+
     result = client.patch(f"/issues/{args.ref}", body)
 
     output_json({

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Update a milestone 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
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Update milestone")
+    parser.add_argument("milestone_id", help="Milestone UUID")
+    parser.add_argument("--name", default=None)
+    parser.add_argument("--target-date", default=None, dest="target_date")
+    parser.add_argument("--description", default=None)
+    args = parser.parse_args()
+
+    body: dict = {}
+    if args.name is not None:
+        body["name"] = args.name
+    if args.target_date is not None:
+        body["targetDate"] = args.target_date
+    if args.description is not None:
+        body["description"] = args.description
+
+    if not body:
+        fail("No fields to update. Use --name, --target-date, or --description")
+
+    client = get_client()
+    result = client.patch(f"/milestones/{args.milestone_id}", body)
+
+    output_json({
+        "success": result.get("success", True),
+        "id": result.get("id", args.milestone_id),
+        "name": result.get("name", args.name),
+    })
+
+
+if __name__ == "__main__":
+    main()