@pennyfarthing/core 7.8.1 → 7.8.4

package/pennyfarthing_scripts/jira/sync.py

@@ -0,0 +1,350 @@
+"""
+Jira sync for Pennyfarthing epics.
+
+Syncs epic stories to Jira with async parallel API calls.
+Ported from jira-sync.mjs for Python parallelism.
+
+Usage:
+    python -m pennyfarthing_scripts.jira sync <epic_number> [--dry-run] [--transition] [--points]
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from dataclasses import dataclass, field
+from typing import Any
+
+from pennyfarthing_scripts.common.config import get_project_root
+from pennyfarthing_scripts.jira.client import (
+    JiraClient,
+    extract_jira_key,
+    get_jira_field,
+    map_status_to_jira,
+)
+from pennyfarthing_scripts.common.output import error, info, success, warn
+from pennyfarthing_scripts.sprint.loader import find_epic, load_sprint
+
+
+@dataclass
+class SyncResult:
+    """Result of syncing a single story."""
+
+    story_id: str
+    success: bool
+    skipped: bool
+    error: str | None
+    actions: list[str] = field(default_factory=list)
+    dry_run: bool = False
+
+
+# Module-level client for async operations
+_client: JiraClient | None = None
+
+
+def _get_client() -> JiraClient:
+    """Get or create the module's JiraClient instance."""
+    global _client
+    if _client is None:
+        _client = JiraClient()
+    return _client
+
+
+def format_story_line(story: dict[str, Any]) -> str:
+    """Format a story for display.
+
+    Args:
+        story: Story dict from sprint YAML
+
+    Returns:
+        Formatted string for display
+    """
+    story_id = story.get("id", "?")
+    title = story.get("title", "Untitled")
+    status = story.get("status", "backlog")
+    return f"Story {story_id}: {title} [{status}]"
+
+
+def format_summary(synced: int, skipped: int, errors: int) -> str:
+    """Format sync summary.
+
+    Args:
+        synced: Number of stories synced
+        skipped: Number of stories skipped
+        errors: Number of errors
+
+    Returns:
+        Formatted summary string
+    """
+    return f"Summary: {synced} synced, {skipped} skipped, {errors} errors"
+
+
+async def sync_story(
+    story: dict[str, Any],
+    dry_run: bool = False,
+    do_transition: bool = False,
+    sync_points: bool = False,
+) -> SyncResult:
+    """Sync a single story to Jira.
+
+    Args:
+        story: Story dict from sprint YAML
+        dry_run: If True, don't make changes
+        do_transition: If True, transition status
+        sync_points: If True, sync story points
+
+    Returns:
+        SyncResult with outcome
+    """
+    story_id = story.get("id", "?")
+    jira_key = story.get("jira")
+
+    # Skip if no Jira key
+    if not jira_key or jira_key == "null":
+        return SyncResult(
+            story_id=story_id,
+            success=False,
+            skipped=True,
+            error=None,
+            actions=[],
+            dry_run=dry_run,
+        )
+
+    jira_key = extract_jira_key(jira_key)
+    actions: list[str] = []
+
+    # Dry run mode
+    if dry_run:
+        if do_transition:
+            actions.append("transition")
+        if sync_points:
+            actions.append("sync_points")
+        return SyncResult(
+            story_id=story_id,
+            success=True,
+            skipped=False,
+            error=None,
+            actions=actions,
+            dry_run=True,
+        )
+
+    # Get client and fetch current Jira state
+    client = _get_client()
+    issue_json = await client.get_issue_async(jira_key)
+    if not issue_json:
+        return SyncResult(
+            story_id=story_id,
+            success=False,
+            skipped=False,
+            error=f"Could not fetch {jira_key}",
+            actions=[],
+        )
+
+    current_status = get_jira_field(issue_json, "fields.status.name", "Unknown")
+    target_status = map_status_to_jira(story.get("status"))
+
+    # Transition if requested and needed
+    if do_transition and current_status != target_status:
+        result = await client.transition_async(jira_key, target_status)
+        if result.get("success"):
+            actions.append(f"transitioned: {current_status} -> {target_status}")
+        else:
+            actions.append(f"transition failed: {result.get('reason')}")
+
+    # Sync points if requested
+    story_points = story.get("points")
+    if sync_points and story_points:
+        current_points = get_jira_field(issue_json, "fields.customfield_10031")
+        current_points_int = int(current_points) if current_points else None
+
+        result = await client.sync_story_points_async(
+            jira_key, int(story_points), current_points_int
+        )
+        if result.get("success"):
+            if result.get("already_synced"):
+                actions.append(f"points already synced: {story_points}")
+            else:
+                actions.append(f"synced points: {story_points}")
+        else:
+            actions.append(f"points sync failed: {result.get('reason')}")
+
+    return SyncResult(
+        story_id=story_id,
+        success=True,
+        skipped=False,
+        error=None,
+        actions=actions,
+    )
+
+
+async def sync_epic(
+    epic: dict[str, Any],
+    dry_run: bool = False,
+    do_transition: bool = False,
+    sync_points: bool = False,
+) -> dict[str, Any]:
+    """Sync all stories in an epic to Jira.
+
+    Args:
+        epic: Epic dict from sprint YAML
+        dry_run: If True, don't make changes
+        do_transition: If True, transition status
+        sync_points: If True, sync story points
+
+    Returns:
+        Summary dict with counts
+    """
+    stories = epic.get("stories", [])
+
+    # Process all stories in parallel
+    tasks = [
+        sync_story(story, dry_run=dry_run, do_transition=do_transition, sync_points=sync_points)
+        for story in stories
+    ]
+    results = await asyncio.gather(*tasks)
+
+    # Count results
+    synced = sum(1 for r in results if r.success and not r.skipped)
+    skipped = sum(1 for r in results if r.skipped)
+    errors = sum(1 for r in results if not r.success and not r.skipped)
+
+    return {
+        "total": len(stories),
+        "synced": synced,
+        "skipped": skipped,
+        "errors": errors,
+        "results": results,
+    }
+
+
+def parse_args(args: list[str] | None = None) -> argparse.Namespace:
+    """Parse command line arguments.
+
+    Args:
+        args: Arguments to parse (defaults to sys.argv[1:])
+
+    Returns:
+        Parsed arguments namespace
+    """
+    parser = argparse.ArgumentParser(
+        description="Sync Pennyfarthing epic to Jira",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  jira sync 35                        Show sync status for epic 35
+  jira sync 35 --dry-run              Show what would be done
+  jira sync 35 --transition           Sync status to Jira
+  jira sync 35 --transition --points  Sync status and story points
+""",
+    )
+    parser.add_argument("epic", help="Epic number (e.g., '35' or 'epic-35')")
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Show what would be done without making changes"
+    )
+    parser.add_argument(
+        "--transition", action="store_true", help="Transition Jira issues to match status"
+    )
+    parser.add_argument(
+        "--points", action="store_true", help="Sync story points from Pennyfarthing to Jira"
+    )
+
+    return parser.parse_args(args)
+
+
+async def async_main(args: argparse.Namespace) -> int:
+    """Async main entry point.
+
+    Args:
+        args: Parsed arguments
+
+    Returns:
+        Exit code
+    """
+    # Find project root and load sprint
+    try:
+        project_root = get_project_root()
+    except FileNotFoundError as e:
+        error(str(e))
+        return 1
+
+    sprint_data = load_sprint(project_root)
+    if not sprint_data:
+        error("Could not load sprint data")
+        return 1
+
+    # Find epic
+    epic = find_epic(sprint_data, args.epic)
+    if not epic:
+        error(f"Epic {args.epic} not found in sprint file")
+        return 1
+
+    # Display header
+    print("", file=sys.stderr)
+    info("==========================================")
+    info(f"Epic {args.epic}: {epic.get('title', 'Untitled')}")
+    if epic.get("jira"):
+        info(f"Jira: {epic.get('jira')}")
+    info("==========================================")
+    print("", file=sys.stderr)
+
+    if args.dry_run:
+        warn("[DRY-RUN MODE] No changes will be made")
+        print("", file=sys.stderr)
+
+    stories = epic.get("stories", [])
+    if not stories:
+        warn(f"No stories found in epic {args.epic}")
+        return 0
+
+    info(f"Found {len(stories)} stories to process")
+    print("", file=sys.stderr)
+
+    # Sync epic
+    result = await sync_epic(
+        epic,
+        dry_run=args.dry_run,
+        do_transition=args.transition,
+        sync_points=args.points,
+    )
+
+    # Display results
+    for sync_result in result["results"]:
+        story = next((s for s in stories if s.get("id") == sync_result.story_id), {})
+        print("---", file=sys.stderr)
+        info(format_story_line(story))
+        if sync_result.skipped:
+            warn("  Not synced to Jira - skipping")
+        elif sync_result.error:
+            error(f"  {sync_result.error}")
+        elif sync_result.dry_run:
+            actions_str = ", ".join(sync_result.actions) if sync_result.actions else "view only"
+            warn(f"  [DRY-RUN] Would sync: {actions_str}")
+        else:
+            for action in sync_result.actions:
+                success(f"  {action}")
+
+    # Summary
+    print("", file=sys.stderr)
+    print("==========================================", file=sys.stderr)
+    success(format_summary(result["synced"], result["skipped"], result["errors"]))
+    print("==========================================", file=sys.stderr)
+
+    return 1 if result["errors"] > 0 else 0
+
+
+def main(args: list[str] | None = None) -> int:
+    """Main entry point.
+
+    Args:
+        args: Command line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code
+    """
+    parsed_args = parse_args(args)
+    return asyncio.run(async_main(parsed_args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/pennyfarthing_scripts/jira_bidirectional_sync.py

@@ -0,0 +1,37 @@
+"""
+Bidirectional sync between sprint YAML and Jira.
+
+This module re-exports from pennyfarthing_scripts.jira.bidirectional for
+backwards compatibility. New code should import from jira.bidirectional directly.
+
+Usage: python -m pennyfarthing_scripts.jira_bidirectional_sync [options]
+"""
+
+# Re-export everything from the new location
+from pennyfarthing_scripts.jira.bidirectional import (
+    SyncChange,
+    SyncPlan,
+    SyncResult,
+    async_main,
+    execute_sync_plan,
+    format_sync_plan,
+    generate_sync_plan,
+    main,
+    parse_cli_args,
+)
+
+__all__ = [
+    "SyncChange",
+    "SyncPlan",
+    "SyncResult",
+    "async_main",
+    "execute_sync_plan",
+    "format_sync_plan",
+    "generate_sync_plan",
+    "main",
+    "parse_cli_args",
+]
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

package/pennyfarthing_scripts/jira_epic_creation.py

@@ -0,0 +1,30 @@
+"""
+Create Jira epics from Pennyfarthing sprint YAML definitions.
+
+This module re-exports from pennyfarthing_scripts.jira.epic for
+backwards compatibility. New code should import from jira.epic directly.
+
+Usage:
+    python -m pennyfarthing_scripts.jira_epic_creation <epic_id> [options]
+"""
+
+# Re-export everything from the new location
+from pennyfarthing_scripts.jira.epic import (
+    build_epic_payload,
+    create_epic,
+    create_epic_from_yaml,
+    main,
+    parse_args,
+)
+
+__all__ = [
+    "build_epic_payload",
+    "create_epic",
+    "create_epic_from_yaml",
+    "main",
+    "parse_args",
+]
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

package/pennyfarthing_scripts/jira_sync.py

@@ -0,0 +1,36 @@
+"""
+Jira sync for Pennyfarthing epics.
+
+This module re-exports from pennyfarthing_scripts.jira.sync for
+backwards compatibility. New code should import from jira.sync directly.
+
+Usage:
+    python -m pennyfarthing_scripts.jira_sync <epic_number> [--dry-run] [--transition] [--points]
+"""
+
+# Re-export everything from the new location
+from pennyfarthing_scripts.jira.sync import (
+    SyncResult,
+    async_main,
+    format_story_line,
+    format_summary,
+    main,
+    parse_args,
+    sync_epic,
+    sync_story,
+)
+
+__all__ = [
+    "SyncResult",
+    "async_main",
+    "format_story_line",
+    "format_summary",
+    "main",
+    "parse_args",
+    "sync_epic",
+    "sync_story",
+]
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

package/pennyfarthing_scripts/jira_sync_story.py

@@ -0,0 +1,30 @@
+"""
+Sync a single story between Pennyfarthing sprint YAML and Jira.
+
+This module re-exports from pennyfarthing_scripts.jira.story for
+backwards compatibility. New code should import from jira.story directly.
+
+Usage:
+    python -m pennyfarthing_scripts.jira_sync_story <story_key> [options]
+"""
+
+# Re-export everything from the new location
+from pennyfarthing_scripts.jira.story import (
+    fetch_jira_issue,
+    get_story_from_sprint,
+    main,
+    parse_args,
+    sync_story,
+)
+
+__all__ = [
+    "fetch_jira_issue",
+    "get_story_from_sprint",
+    "main",
+    "parse_args",
+    "sync_story",
+]
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

package/pennyfarthing_scripts/output.py

@@ -0,0 +1,37 @@
+"""
+Console output utilities for Pennyfarthing scripts.
+
+This module re-exports from pennyfarthing_scripts.common.output for
+backwards compatibility. New code should import from common.output directly.
+"""
+
+# Re-export everything from the new location
+from pennyfarthing_scripts.common.output import (
+    Colors,
+    _colorize,
+    _supports_color,
+    bold,
+    debug,
+    dim,
+    divider,
+    error,
+    header,
+    info,
+    success,
+    warn,
+)
+
+__all__ = [
+    "Colors",
+    "_colorize",
+    "_supports_color",
+    "bold",
+    "debug",
+    "dim",
+    "divider",
+    "error",
+    "header",
+    "info",
+    "success",
+    "warn",
+]

package/pennyfarthing_scripts/preflight/__init__.py

@@ -0,0 +1,17 @@
+"""Preflight checks for Pennyfarthing workflows.
+
+This package provides async preflight checks that run in parallel
+to validate story completion before finishing.
+"""
+
+from pennyfarthing_scripts.preflight.finish import (
+    PreflightResult,
+    PreflightIssue,
+    run_finish_preflight,
+)
+
+__all__ = [
+    "PreflightResult",
+    "PreflightIssue",
+    "run_finish_preflight",
+]

package/pennyfarthing_scripts/preflight/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for python -m pennyfarthing_scripts.preflight
+"""
+
+import sys
+
+from pennyfarthing_scripts.preflight.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())

package/pennyfarthing_scripts/preflight/cli.py

@@ -0,0 +1,141 @@
+"""
+Preflight CLI - Fan-out CLI for preflight checks.
+
+Usage:
+    python -m pennyfarthing_scripts.preflight <subcommand> [args]
+
+Subcommands:
+    finish      Run finish preflight checks
+"""
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+from pennyfarthing_scripts.preflight.finish import run_finish_preflight
+
+
+def finish(args: list[str]) -> int:
+    """Run finish preflight checks."""
+    parser = argparse.ArgumentParser(
+        prog="preflight finish",
+        description="Run finish preflight checks in parallel",
+    )
+    parser.add_argument(
+        "story_id",
+        help="Story identifier (e.g., 31-10)",
+    )
+    parser.add_argument(
+        "--branch", "-b",
+        required=True,
+        help="Feature branch name",
+    )
+    parser.add_argument(
+        "--jira", "-j",
+        help="Jira issue key (optional, skips Jira checks if absent)",
+    )
+    parser.add_argument(
+        "--repo", "-r",
+        help="Repository name for PR lookup (optional)",
+    )
+    parser.add_argument(
+        "--project-root", "-p",
+        type=Path,
+        help="Project root path (defaults to cwd)",
+    )
+    parser.add_argument(
+        "--format", "-f",
+        choices=["json", "yaml"],
+        default="json",
+        help="Output format (default: json)",
+    )
+
+    parsed = parser.parse_args(args)
+
+    # Run async preflight
+    result = asyncio.run(run_finish_preflight(
+        story_id=parsed.story_id,
+        branch=parsed.branch,
+        jira_key=parsed.jira,
+        repo=parsed.repo,
+        project_root=parsed.project_root,
+    ))
+
+    # Output result
+    result_dict = result.to_dict()
+
+    if parsed.format == "yaml":
+        try:
+            import yaml
+            print(yaml.dump(result_dict, default_flow_style=False, sort_keys=False))
+        except ImportError:
+            print("YAML output requires PyYAML. Falling back to JSON.", file=sys.stderr)
+            print(json.dumps(result_dict, indent=2))
+    else:
+        print(json.dumps(result_dict, indent=2))
+
+    # Return non-zero if not ready to finish
+    return 0 if result.ready_to_finish else 1
+
+
+# Subcommand registry
+SUBCOMMANDS = {
+    "finish": finish,
+}
+
+
+def cli(args: list[str] | None = None) -> int:
+    """Main CLI entry point."""
+    if args is None:
+        args = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="preflight",
+        description="Preflight checks for Pennyfarthing workflows",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Subcommands:
+    finish <story_id> --branch <branch> [--jira <key>]
+        Run finish preflight checks in parallel
+
+Examples:
+    preflight finish 31-10 --branch feat/31-10-feature --jira MSSCI-12345
+    preflight finish 63-9 -b feat/63-9-fanout -j MSSCI-12413 -f yaml
+""",
+    )
+
+    parser.add_argument(
+        "subcommand",
+        nargs="?",
+        choices=list(SUBCOMMANDS.keys()),
+        help="Subcommand to run",
+    )
+    parser.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments for subcommand",
+    )
+
+    parsed = parser.parse_args(args)
+
+    if not parsed.subcommand:
+        parser.print_help()
+        return 0
+
+    handler = SUBCOMMANDS.get(parsed.subcommand)
+    if handler:
+        return handler(parsed.args)
+    else:
+        print(f"Unknown subcommand: {parsed.subcommand}", file=sys.stderr)
+        return 1
+
+
+def main(args: list[str] | None = None) -> int:
+    """Alias for cli()."""
+    return cli(args)
+
+
+if __name__ == "__main__":
+    sys.exit(cli())