@flydocs/cli 0.6.0-alpha.2 → 0.6.0-alpha.21

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

@@ -0,0 +1,489 @@
+#!/usr/bin/env python3
+"""Issue operations dispatcher — create, get, list, transition, assign, update, and more."""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from flydocs_api import get_client, output_json, fail, resolve_text_input
+
+
+# ---------------------------------------------------------------------------
+# Subcommand handlers
+# ---------------------------------------------------------------------------
+
+def cmd_create(args: argparse.Namespace) -> None:
+    """Create a new issue."""
+    # Description resolution: --description-file > stdin > --description
+    description = resolve_text_input(file_arg=args.description_file)
+    if description is None:
+        description = args.description or ""
+
+    client = get_client()
+    result = client.create_issue(
+        title=args.title,
+        issue_type=args.type,
+        description=description,
+        priority=args.priority,
+        estimate=args.estimate,
+        assignee=args.assignee,
+        project=args.project,
+        triage=args.triage,
+    )
+    output_json(result)
+
+
+def cmd_get(args: argparse.Namespace) -> None:
+    """Get a single issue by reference."""
+    client = get_client()
+    result = client.get_issue(args.ref, fields=args.fields)
+    output_json(result)
+
+
+def cmd_list(args: argparse.Namespace) -> None:
+    """List issues with optional filters."""
+    client = get_client()
+    result = client.list_issues(
+        status=args.status,
+        active=args.active,
+        project=args.project,
+        assignee=args.assignee,
+        milestone=args.milestone,
+        mine=args.mine,
+        show_all=args.show_all,
+        limit=args.limit,
+    )
+    output_json(result)
+
+
+def cmd_transition(args: argparse.Namespace) -> None:
+    """Transition an issue to a new status with a comment."""
+    client = get_client()
+    result = client.transition(args.ref, args.status, args.comment)
+    output_json(result)
+
+
+def cmd_assign(args: argparse.Namespace) -> None:
+    """Assign or unassign an issue."""
+    assignee = None if args.unassign else args.assignee
+    client = get_client()
+    result = client.assign(args.ref, assignee)
+    output_json(result)
+
+
+def cmd_update(args: argparse.Namespace) -> None:
+    """Update one or more fields on an issue."""
+    # Description resolution: --description-file > --description
+    description = args.description
+    if args.description_file:
+        path = Path(args.description_file)
+        if not path.exists():
+            fail(f"File not found: {args.description_file}")
+        description = path.read_text()
+
+    fields: dict = {}
+    if args.title is not None:
+        fields["title"] = args.title
+    if args.priority is not None:
+        fields["priority"] = args.priority
+    if args.estimate is not None:
+        fields["estimate"] = args.estimate
+    if args.assignee is not None:
+        fields["assignee"] = args.assignee
+    if args.state is not None:
+        fields["state"] = args.state
+    if description is not None:
+        fields["description"] = description
+    if args.labels is not None:
+        fields["labels"] = args.labels
+    if args.milestone is not None:
+        fields["milestone"] = args.milestone
+    if args.comment is not None:
+        fields["comment"] = args.comment
+
+    if not fields:
+        fail("No fields to update")
+
+    client = get_client()
+    result = client.update_issue(args.ref, **fields)
+    output_json(result)
+
+
+def cmd_description(args: argparse.Namespace) -> None:
+    """Update an issue's description."""
+    # Text resolution: --file > stdin > --text
+    text = resolve_text_input(text_arg=args.text, file_arg=args.file)
+    if text is None:
+        fail("No description text provided (use --text, --file, or pipe to stdin)")
+
+    client = get_client()
+    result = client.update_description(args.ref, text)
+    output_json(result)
+
+
+def cmd_comment(args: argparse.Namespace) -> None:
+    """Add a comment to an issue."""
+    body = args.body
+    if body is None and not sys.stdin.isatty():
+        body = sys.stdin.read().strip()
+    if not body:
+        fail("No comment body provided (pass as argument or pipe to stdin)")
+
+    client = get_client()
+    result = client.comment(args.ref, body)
+    output_json(result)
+
+
+def cmd_estimate(args: argparse.Namespace) -> None:
+    """Set estimate points on an issue."""
+    if args.points < 0:
+        fail("Estimate points must be non-negative")
+
+    client = get_client()
+    result = client.estimate(args.ref, args.points)
+    output_json(result)
+
+
+def cmd_priority(args: argparse.Namespace) -> None:
+    """Set priority level on an issue."""
+    if args.level < 0 or args.level > 4:
+        fail("Priority level must be 0-4")
+
+    client = get_client()
+    result = client.priority(args.ref, args.level)
+    output_json(result)
+
+
+def cmd_link(args: argparse.Namespace) -> None:
+    """Link two issues together."""
+    client = get_client()
+    result = client.link(args.ref, args.related_ref, args.type)
+    output_json(result)
+
+
+def cmd_assign_milestone(args: argparse.Namespace) -> None:
+    """Assign an issue to a milestone."""
+    client = get_client()
+    result = client.assign_milestone(args.ref, args.milestone_id)
+    output_json(result)
+
+
+def cmd_assign_cycle(args: argparse.Namespace) -> None:
+    """Assign an issue to a cycle (or remove from current cycle)."""
+    client = get_client()
+    result = client.assign_cycle(args.ref, args.cycle_id)
+    output_json(result)
+
+
+# ---------------------------------------------------------------------------
+# PR creation
+# ---------------------------------------------------------------------------
+
+def _detect_platform() -> str:
+    """Detect git hosting platform from remote URL. Returns github|gitlab|bitbucket|unknown."""
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True, text=True, timeout=5,
+        )
+        url = result.stdout.strip().lower()
+        if "github" in url:
+            return "github"
+        if "gitlab" in url:
+            return "gitlab"
+        if "bitbucket" in url:
+            return "bitbucket"
+    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
+        pass
+    return "unknown"
+
+
+def _get_current_branch() -> str:
+    """Get current git branch name."""
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True, text=True, timeout=5,
+        )
+        return result.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
+        return ""
+
+
+def _get_default_branch() -> str:
+    """Detect the default branch (main or master)."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", "refs/heads/main"],
+            capture_output=True, timeout=5,
+        )
+        if result.returncode == 0:
+            return "main"
+    except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
+        pass
+    return "master"
+
+
+def _build_pr_body(issue_ref: str | None, summary: str | None) -> str:
+    """Build PR body from template, optionally populating from issue data."""
+    # Read the PR template
+    script_dir = Path(__file__).parent
+    template_path = script_dir.parent / "templates" / "pr" / "default.md"
+
+    if template_path.exists():
+        body = template_path.read_text()
+    else:
+        body = "## Summary\n\n{ISSUE_SUMMARY}\n\n## Changes\n\n- \n\n## Test Plan\n\n- [ ] \n\n## Notes\n\n"
+
+    # Populate issue context if available
+    if issue_ref:
+        body = body.replace("{ISSUE_REF}", issue_ref)
+        try:
+            client = get_client()
+            issue = client.get_issue(issue_ref, fields="full")
+            if isinstance(issue, dict):
+                title = issue.get("title", "")
+                description = issue.get("description", "")
+
+                # Extract AC checkboxes from description
+                ac_lines = []
+                if description:
+                    for line in description.splitlines():
+                        if re.match(r"^\s*-\s*\[[ x]\]", line, re.IGNORECASE):
+                            ac_lines.append(line)
+
+                body = body.replace("{ISSUE_SUMMARY}", title)
+                body = body.replace(
+                    "{ACCEPTANCE_CRITERIA}",
+                    "\n".join(ac_lines) if ac_lines else "See issue for acceptance criteria.",
+                )
+        except Exception:
+            body = body.replace("{ISSUE_SUMMARY}", summary or "")
+            body = body.replace("{ACCEPTANCE_CRITERIA}", "See issue for acceptance criteria.")
+    else:
+        body = body.replace("{ISSUE_REF}", "")
+        body = body.replace("{ISSUE_SUMMARY}", summary or "")
+        body = body.replace("{ACCEPTANCE_CRITERIA}", "")
+
+    # Clean up remaining placeholders
+    body = body.replace("{CHANGE_1}", "")
+    body = body.replace("{CHANGE_2}", "")
+    body = body.replace("{TEST_1}", "")
+    body = body.replace("{TEST_2}", "")
+    body = body.replace("{NOTES}", "")
+
+    return body
+
+
+def cmd_pr(args: argparse.Namespace) -> None:
+    """Create a pull/merge request with standard template."""
+    platform = _detect_platform()
+    branch = _get_current_branch()
+    base = args.base or _get_default_branch()
+
+    if not branch or branch == base:
+        fail(f"Cannot create PR from branch '{branch}' — switch to a feature branch first.")
+
+    # Build title
+    title = args.title
+    if not title and args.issue:
+        try:
+            client = get_client()
+            issue = client.get_issue(args.issue, fields="basic")
+            if isinstance(issue, dict):
+                title = issue.get("title", args.issue)
+        except Exception:
+            title = args.issue
+    if not title:
+        title = branch
+
+    # Build body from template
+    body = _build_pr_body(issue_ref=args.issue, summary=title)
+
+    if args.dry_run:
+        output_json({
+            "platform": platform,
+            "branch": branch,
+            "base": base,
+            "title": title,
+            "body": body,
+        })
+        return
+
+    # Create PR via platform CLI
+    if platform == "github":
+        cmd = ["gh", "pr", "create", "--title", title, "--body", body, "--base", base]
+        if args.draft:
+            cmd.append("--draft")
+    elif platform == "gitlab":
+        cmd = ["glab", "mr", "create", "--title", title, "--description", body, "--target-branch", base]
+        if args.draft:
+            cmd.append("--draft")
+    elif platform == "bitbucket":
+        fail("Bitbucket PR creation via CLI is not yet supported. Use the web UI or Bitbucket API.")
+    else:
+        fail(f"Could not detect git platform from remote URL. Detected: {platform}")
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+        if result.returncode != 0:
+            fail(f"PR creation failed: {result.stderr.strip()}")
+
+        pr_url = result.stdout.strip()
+
+        # Post PR link as comment on the issue
+        if args.issue:
+            try:
+                client = get_client()
+                client.comment(args.issue, f"PR created: {pr_url}")
+            except Exception:
+                pass  # Non-blocking — PR was created successfully
+
+        output_json({
+            "success": True,
+            "platform": platform,
+            "url": pr_url,
+            "branch": branch,
+            "base": base,
+        })
+    except FileNotFoundError:
+        cli = "gh" if platform == "github" else "glab"
+        fail(f"{cli} CLI not found. Install it to create PRs from the command line.")
+    except subprocess.TimeoutExpired:
+        fail("PR creation timed out.")
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="FlyDocs issue operations")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # -- create --
+    p = sub.add_parser("create", help="Create a new issue")
+    p.add_argument("--title", required=True)
+    p.add_argument("--type", required=True, choices=["feature", "bug", "chore", "idea"])
+    p.add_argument("--description", default=None)
+    p.add_argument("--description-file", default=None)
+    p.add_argument("--priority", type=int, default=3, choices=[0, 1, 2, 3, 4])
+    p.add_argument("--estimate", type=int, default=None, choices=[0, 1, 2, 3, 5])
+    p.add_argument("--assignee", default=None)
+    p.add_argument("--project", default=None)
+    p.add_argument("--triage", action="store_true")
+
+    # -- get --
+    p = sub.add_parser("get", help="Get a single issue")
+    p.add_argument("ref")
+    p.add_argument("--fields", default="full", choices=["basic", "full"])
+
+    # -- list --
+    p = sub.add_parser("list", help="List issues")
+    p.add_argument("--status", default=None)
+    p.add_argument("--active", action="store_true")
+    p.add_argument("--project", default=None)
+    p.add_argument("--assignee", default=None)
+    p.add_argument("--milestone", default=None)
+    p.add_argument("--mine", action="store_true")
+    p.add_argument("--all", action="store_true", dest="show_all", help="Bypass product scope cascade")
+    p.add_argument("--limit", type=int, default=50)
+
+    # -- transition --
+    p = sub.add_parser("transition", help="Transition issue status")
+    p.add_argument("ref")
+    p.add_argument("status")
+    p.add_argument("comment")
+
+    # -- assign --
+    p = sub.add_parser("assign", help="Assign or unassign an issue")
+    p.add_argument("ref")
+    p.add_argument("assignee", nargs="?", default=None)
+    p.add_argument("--unassign", action="store_true")
+
+    # -- update --
+    p = sub.add_parser("update", help="Update issue fields")
+    p.add_argument("ref")
+    p.add_argument("--title", default=None)
+    p.add_argument("--priority", type=int, default=None)
+    p.add_argument("--estimate", type=int, default=None)
+    p.add_argument("--assignee", default=None)
+    p.add_argument("--state", default=None)
+    p.add_argument("--description", default=None)
+    p.add_argument("--description-file", default=None)
+    p.add_argument("--labels", default=None)
+    p.add_argument("--milestone", default=None)
+    p.add_argument("--comment", default=None)
+
+    # -- description --
+    p = sub.add_parser("description", help="Update issue description")
+    p.add_argument("ref")
+    p.add_argument("--text", default=None)
+    p.add_argument("--file", default=None)
+
+    # -- comment --
+    p = sub.add_parser("comment", help="Add a comment to an issue")
+    p.add_argument("ref")
+    p.add_argument("body", nargs="?", default=None)
+
+    # -- estimate --
+    p = sub.add_parser("estimate", help="Set estimate points")
+    p.add_argument("ref")
+    p.add_argument("points", type=int)
+
+    # -- priority --
+    p = sub.add_parser("priority", help="Set priority level")
+    p.add_argument("ref")
+    p.add_argument("level", type=int)
+
+    # -- link --
+    p = sub.add_parser("link", help="Link two issues")
+    p.add_argument("ref")
+    p.add_argument("related_ref")
+    p.add_argument("type", choices=["blocks", "related", "duplicate"])
+
+    # -- assign-milestone --
+    p = sub.add_parser("assign-milestone", help="Assign issue to milestone")
+    p.add_argument("ref")
+    p.add_argument("milestone_id")
+
+    # -- assign-cycle --
+    p = sub.add_parser("assign-cycle", help="Assign issue to cycle")
+    p.add_argument("ref")
+    p.add_argument("cycle_id", nargs="?", default=None)
+
+    # -- pr --
+    p = sub.add_parser("pr", help="Create pull/merge request with standard template")
+    p.add_argument("--issue", default=None, help="Issue ref to link (e.g. FLY-123)")
+    p.add_argument("--title", default=None, help="PR title (defaults to issue title or branch name)")
+    p.add_argument("--base", default=None, help="Base branch (defaults to main/master)")
+    p.add_argument("--draft", action="store_true", help="Create as draft PR")
+    p.add_argument("--dry-run", action="store_true", help="Show what would be created without creating")
+
+    args = parser.parse_args()
+
+    commands = {
+        "create": cmd_create,
+        "get": cmd_get,
+        "list": cmd_list,
+        "transition": cmd_transition,
+        "assign": cmd_assign,
+        "update": cmd_update,
+        "description": cmd_description,
+        "comment": cmd_comment,
+        "estimate": cmd_estimate,
+        "priority": cmd_priority,
+        "link": cmd_link,
+        "assign-milestone": cmd_assign_milestone,
+        "assign-cycle": cmd_assign_cycle,
+        "pr": cmd_pr,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Project, milestone, and cycle operations dispatcher.
+
+All subcommands are cloud-only. The unified client handles tier gating
+via require_cloud().
+
+Usage:
+    python projects.py list-projects [--active] [--all]
+    python projects.py create-project --name NAME [--description DESC]
+    python projects.py list-milestones [--all]
+    python projects.py create-milestone --name NAME [--project ID] [--target-date DATE]
+    python projects.py update-milestone MILESTONE_ID [--name] [--target-date] [--description]
+    python projects.py delete-milestone MILESTONE_ID
+    python projects.py list-cycles [--active]
+"""
+
+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 cmd_list_projects(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.list_projects(active=args.active, show_all=args.show_all)
+    output_json(result)
+
+
+def cmd_create_project(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.create_project(name=args.name, description=args.description)
+    output_json(result)
+
+
+def cmd_list_milestones(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.list_milestones(show_all=args.show_all)
+    output_json(result)
+
+
+def cmd_create_milestone(args: argparse.Namespace) -> None:
+    client = get_client()
+    # Default project from activeProjects if not explicitly provided
+    project = args.project
+    if not project and client.is_cloud:
+        active = client.config.get("workspace", {}).get("activeProjects", [])
+        if active:
+            project = active[0]
+    result = client.create_milestone(
+        name=args.name,
+        project=project,
+        target_date=args.target_date,
+    )
+    output_json(result)
+
+
+def cmd_update_milestone(args: argparse.Namespace) -> None:
+    client = get_client()
+    fields: dict = {}
+    if args.name is not None:
+        fields["name"] = args.name
+    if args.target_date is not None:
+        fields["targetDate"] = args.target_date
+    if args.description is not None:
+        fields["description"] = args.description
+    if not fields:
+        fail("At least one of --name, --target-date, or --description is required")
+    result = client.update_milestone(args.milestone_id, **fields)
+    output_json(result)
+
+
+def cmd_delete_milestone(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.delete_milestone(args.milestone_id)
+    output_json(result)
+
+
+def cmd_list_cycles(args: argparse.Namespace) -> None:
+    client = get_client()
+    result = client.list_cycles(active=args.active)
+    output_json(result)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="FlyDocs project operations")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # list-projects
+    lp = sub.add_parser("list-projects", help="List projects")
+    lp.add_argument("--active", action="store_true", help="Active projects only")
+    lp.add_argument("--all", action="store_true", dest="show_all",
+                     help="Include all projects (bypass label filter)")
+
+    # create-project
+    cp = sub.add_parser("create-project", help="Create a project")
+    cp.add_argument("--name", required=True, help="Project name")
+    cp.add_argument("--description", default=None, help="Project description")
+
+    # list-milestones
+    lm = sub.add_parser("list-milestones", help="List milestones")
+    lm.add_argument("--all", action="store_true", dest="show_all",
+                     help="Include milestones from all projects")
+
+    # create-milestone
+    cm = sub.add_parser("create-milestone", help="Create a milestone")
+    cm.add_argument("--name", required=True, help="Milestone name")
+    cm.add_argument("--project", default=None, help="Project ID")
+    cm.add_argument("--target-date", default=None, dest="target_date",
+                     help="Target date (YYYY-MM-DD)")
+
+    # update-milestone
+    um = sub.add_parser("update-milestone", help="Update a milestone")
+    um.add_argument("milestone_id", help="Milestone ID")
+    um.add_argument("--name", default=None, help="New name")
+    um.add_argument("--target-date", default=None, dest="target_date",
+                     help="New target date (YYYY-MM-DD)")
+    um.add_argument("--description", default=None, help="New description")
+
+    # delete-milestone
+    dm = sub.add_parser("delete-milestone", help="Delete a milestone")
+    dm.add_argument("milestone_id", help="Milestone ID")
+
+    # list-cycles
+    lc = sub.add_parser("list-cycles", help="List cycles")
+    lc.add_argument("--active", action="store_true", help="Active cycles only")
+
+    args = parser.parse_args()
+
+    commands = {
+        "list-projects": cmd_list_projects,
+        "create-project": cmd_create_project,
+        "list-milestones": cmd_list_milestones,
+        "create-milestone": cmd_create_milestone,
+        "update-milestone": cmd_update_milestone,
+        "delete-milestone": cmd_delete_milestone,
+        "list-cycles": cmd_list_cycles,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()