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

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""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
+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 team or project preference")
+    parser.add_argument("team_id", help="Provider team/workspace UUID")
+    args = parser.parse_args()
+
+    client = get_client()
+    result = client.post("/auth/team", {"teamId": args.team_id})
+
+    # Update local config with team ID
+    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": None, "teamId": None}
+        config["provider"]["teamId"] = args.team_id
+        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/transition.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """Transition an issue to a new status with a required comment."""
 
-import json
 import sys
 from pathlib import Path
 
@@ -14,54 +13,14 @@ if len(sys.argv) < 4:
 ref, status, comment = sys.argv[1], sys.argv[2].upper(), sys.argv[3]
 client = get_client()
 
-# Resolve issue
-issue_uuid = client.resolve_issue_id(ref)
-if not issue_uuid:
-    fail(f"Issue not found: {ref}")
-
-# Get current state for previousStatus
-current_result = client.query(
-    """query($id: String!) {
-        issue(id: $id) { state { name } }
-    }""",
-    {"id": issue_uuid},
-)
-prev_state = (current_result.get("data") or {}).get("issue", {}).get("state", {}).get("name", "Unknown")
-
-# Resolve target state
-state_id = client.get_state_id(status)
-if not state_id:
-    fail(f"Unknown status: {status}. Check statusMapping in .flydocs/config.json")
-
-# Build mutation input — combine state + cycle in one call
-mutation_input: dict = {"stateId": state_id}
-if status == "IMPLEMENTING":
-    cycle = client.get_active_cycle()
-    if cycle:
-        mutation_input["cycleId"] = cycle["id"]
-
-# Update state (and cycle if IMPLEMENTING) in a single mutation
-result = client.query(
-    """mutation($id: String!, $input: IssueUpdateInput!) {
-        issueUpdate(id: $id, input: $input) {
-            success
-            issue { identifier state { name } }
-        }
-    }""",
-    {"id": issue_uuid, "input": mutation_input},
-)
-update_data = result.get("data", {}).get("issueUpdate", {})
-if not update_data.get("success"):
-    fail(f"Failed to transition: {result}")
-
-# Add comment
-formatted = f"**{status}** — {comment}"
-client.query(
-    """mutation($id: String!, $body: String!) {
-        commentCreate(input: { issueId: $id, body: $body }) { success }
-    }""",
-    {"id": issue_uuid, "body": formatted},
-)
-
-issue = update_data["issue"]
-output_json({"success": True, "issue": issue["identifier"], "previousStatus": prev_state, "newStatus": status})
+result = client.post(f"/issues/{ref}/transition", {
+    "status": status,
+    "comment": comment,
+})
+
+output_json({
+    "success": result.get("success", True),
+    "issue": result.get("issue", ref),
+    "previousStatus": result.get("previousStatus", ""),
+    "newStatus": result.get("newStatus", status),
+})

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Update an issue's description."""
+"""Update an issue's description via the FlyDocs Relay API."""
 
 import argparse
 import sys
@@ -9,39 +9,28 @@ sys.path.insert(0, str(Path(__file__).parent))
 from flydocs_api import get_client, output_json, fail
 
 parser = argparse.ArgumentParser(description="Update issue description")
-parser.add_argument("ref")
-parser.add_argument("--text", default="")
-parser.add_argument("--file", default="", dest="filepath")
+parser.add_argument("ref", help="Issue reference (e.g., ENG-123)")
+parser.add_argument("--text", default=None)
+parser.add_argument("--file", default=None)
 args = parser.parse_args()
 
+# Resolve text: --file > stdin > --text
 text = args.text
-if args.filepath:
+if args.file:
     try:
-        text = Path(args.filepath).read_text()
+        text = Path(args.file).read_text()
     except FileNotFoundError:
-        fail(f"File not found: {args.filepath}")
-if not text and not sys.stdin.isatty():
+        fail(f"File not found: {args.file}")
+elif text is None and not sys.stdin.isatty():
     text = sys.stdin.read().strip()
+
 if not text:
-    fail("Provide --text, --file, or pipe via stdin")
+    fail("Provide text via --text, --file, or stdin")
 
 client = get_client()
-issue_uuid = client.resolve_issue_id(args.ref)
-if not issue_uuid:
-    fail(f"Issue not found: {args.ref}")
-
-result = client.query(
-    """mutation($id: String!, $description: String!) {
-        issueUpdate(id: $id, input: { description: $description }) {
-            success
-            issue { identifier }
-        }
-    }""",
-    {"id": issue_uuid, "description": text},
-)
-
-if not result.get("data", {}).get("issueUpdate", {}).get("success"):
-    fail(f"Failed to update: {result}")
+result = client.put(f"/issues/{args.ref}/description", {"text": text})
 
-issue = result["data"]["issueUpdate"]["issue"]
-output_json({"success": True, "issue": issue["identifier"]})
+output_json({
+    "success": result.get("success", True),
+    "issue": result.get("issue", args.ref),
+})

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

@@ -13,96 +13,85 @@ 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()
 
-    client = get_client()
-
-    issue_uuid = client.resolve_issue_id(args.ref)
-    if not issue_uuid:
-        fail(f"Issue not found: {args.ref}")
-
-    # Build mutation input from provided args
-    mutation_input: dict = {}
+    # Build request body from provided args
+    body: dict = {}
     updated_fields: list[str] = []
 
     if args.title is not None:
-        mutation_input["title"] = args.title
+        body["title"] = args.title
         updated_fields.append("title")
 
     if args.priority is not None:
-        mutation_input["priority"] = args.priority
+        body["priority"] = args.priority
         updated_fields.append("priority")
 
     if args.estimate is not None:
-        mutation_input["estimate"] = args.estimate
+        body["estimate"] = args.estimate
         updated_fields.append("estimate")
 
     if args.assignee is not None:
-        user_id, user_name = client.resolve_user_id(args.assignee)
-        if not user_id:
-            fail(f"User not found: {args.assignee}")
-        mutation_input["assigneeId"] = user_id
+        body["assignee"] = args.assignee
         updated_fields.append("assignee")
 
     if args.state is not None:
-        state_id = client.get_state_id(args.state.upper())
-        if not state_id:
-            fail(f"Unknown status: {args.state}")
-        mutation_input["stateId"] = state_id
+        body["state"] = args.state.upper()
         updated_fields.append("state")
 
     if args.description_file is not None:
         path = Path(args.description_file)
         if not path.exists():
             fail(f"File not found: {args.description_file}")
-        mutation_input["description"] = path.read_text()
+        body["description"] = path.read_text()
         updated_fields.append("description")
     elif args.description is not None:
-        mutation_input["description"] = args.description
+        body["description"] = args.description
         updated_fields.append("description")
 
-    if not mutation_input and not args.comment:
-        fail("No fields to update. Use --title, --priority, --estimate, --assignee, --state, --description, or --comment")
-
-    # Single mutation for all field updates
-    result = None
-    if mutation_input:
-        result = client.query(
-            """mutation($id: String!, $input: IssueUpdateInput!) {
-                issueUpdate(id: $id, input: $input) {
-                    success
-                    issue { identifier title state { name } assignee { name } priority estimate }
-                }
-            }""",
-            {"id": issue_uuid, "input": mutation_input},
-        )
-        if not result.get("data", {}).get("issueUpdate", {}).get("success"):
-            fail(f"Failed to update: {result}")
-
-    # Comment is a separate mutation (Linear doesn't combine these)
-    if args.comment:
-        client.query(
-            """mutation($id: String!, $body: String!) {
-                commentCreate(input: { issueId: $id, body: $body }) { success }
-            }""",
-            {"id": issue_uuid, "body": args.comment},
-        )
+    if args.labels is not None:
+        body["labels"] = [l.strip() for l in args.labels.split(",") if l.strip()]
+        updated_fields.append("labels")
+
+    if args.comment is not None:
+        body["comment"] = args.comment
         updated_fields.append("comment")
 
-    issue = {}
-    if result:
-        issue = result["data"]["issueUpdate"]["issue"]
+    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({
-        "success": True,
-        "issue": issue.get("identifier", args.ref),
+        "success": result.get("success", True),
+        "issue": result.get("issue", args.ref),
         "updated": updated_fields,
     })
 

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()

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Validate workspace setup via the FlyDocs Relay API.
+
+Read-only validation that checks provider, team, status mapping, label config,
+and user identity. Writes result to .flydocs/validation-cache.json and sets
+setupComplete: true in config when all required checks pass.
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail
+
+
+# Required checks — failure blocks setup completion
+REQUIRED_CHECKS = {
+    "provider": {
+        "test": lambda cfg: cfg.get("provider", {}).get("connected") is True,
+        "message": "No provider connected — configure in FlyDocs dashboard",
+    },
+    "team": {
+        "test": lambda cfg: bool(cfg.get("team", {}).get("id")),
+        "message": "No team selected — configure in FlyDocs dashboard",
+    },
+    "statusMapping": {
+        "test": lambda cfg: cfg.get("statusMapping", {}).get("configured") is True,
+        "message": "Status mapping not configured — configure in FlyDocs dashboard",
+    },
+    "labelConfig": {
+        "test": lambda cfg: cfg.get("labelConfig", {}).get("configured") is True,
+        "message": "Label config not configured — configure in FlyDocs dashboard",
+    },
+}
+
+# Optional checks — warn but don't block
+OPTIONAL_CHECKS = {
+    "userIdentity": {
+        "test": lambda cfg: cfg.get("userIdentity", {}).get("linked") is True,
+        "message": (
+            "Provider identity not linked — run: "
+            "python3 .claude/skills/flydocs-cloud/scripts/set_identity.py <provider> <id>"
+        ),
+    },
+    "repos": {
+        "test": lambda cfg: (cfg.get("repos", {}).get("count", 0) or 0) > 0,
+        "message": "No repos linked — link a repo in FlyDocs dashboard settings",
+    },
+}
+
+
+def main() -> None:
+    client = get_client()
+
+    # Fetch workspace config from relay
+    config_response = client.get("/auth/config")
+
+    # Run checks
+    checks: dict[str, bool] = {}
+    valid: list[str] = []
+    missing: list[dict[str, str]] = []
+    warnings: list[dict[str, str]] = []
+
+    for name, check in REQUIRED_CHECKS.items():
+        passed = check["test"](config_response)
+        checks[name] = passed
+        if passed:
+            valid.append(name)
+        else:
+            missing.append({"check": name, "action": check["message"]})
+
+    for name, check in OPTIONAL_CHECKS.items():
+        passed = check["test"](config_response)
+        checks[name] = passed
+        if passed:
+            valid.append(name)
+        else:
+            warnings.append({"check": name, "action": check["message"]})
+
+    all_required_pass = len(missing) == 0
+
+    # Build workspace info from response
+    workspace = config_response.get("workspace", {})
+    provider_type = config_response.get("provider", {}).get("type", "unknown")
+
+    # Write validation cache
+    cache = {
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "valid": all_required_pass,
+        "workspace": {
+            "id": workspace.get("id", ""),
+            "name": workspace.get("name", ""),
+        },
+        "provider": provider_type,
+        "checks": checks,
+        "missing": [m["check"] for m in missing],
+        "warnings": [w["check"] for w in warnings],
+    }
+
+    cache_path = client.project_root / ".flydocs" / "validation-cache.json"
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(cache_path, "w") as f:
+        json.dump(cache, f, indent=2)
+        f.write("\n")
+
+    # If all required checks pass, set setupComplete in config
+    if all_required_pass:
+        config_path = client.config_path
+        if config_path.exists():
+            with open(config_path, "r") as f:
+                local_config = json.load(f)
+        else:
+            local_config = {}
+
+        local_config["setupComplete"] = True
+        with open(config_path, "w") as f:
+            json.dump(local_config, f, indent=2)
+            f.write("\n")
+
+    # Output structured report
+    report: dict = {
+        "valid": all_required_pass,
+        "checks": checks,
+        "passed": valid,
+    }
+    if missing:
+        report["missing"] = missing
+    if warnings:
+        report["warnings"] = warnings
+    if all_required_pass:
+        report["setupComplete"] = True
+
+    output_json(report)
+
+
+if __name__ == "__main__":
+    main()