@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing-dist/pf/sprint/work.py

@@ -0,0 +1,229 @@
+"""
+Sprint work session management.
+
+Provides functions for starting and managing work on stories.
+"""
+
+from typing import Any
+
+from pf.sprint.loader import (
+    get_stories_by_status,
+    get_story_by_id,
+)
+
+
+def check_story(story_id: str) -> dict[str, Any]:
+    """Check if a story is available for work.
+
+    Args:
+        story_id: Story ID or Jira key
+
+    Returns:
+        Dict with availability status and story details
+    """
+    story = get_story_by_id(story_id)
+
+    if not story:
+        return {
+            "available": False,
+            "error": f"Story '{story_id}' not found",
+        }
+
+    status = story.get("status", "backlog")
+    assigned = story.get("assigned_to")
+
+    # Check if assigned to someone else
+    if assigned:
+        from pf.jira.client import get_current_user_email
+
+        current_user = get_current_user_email()
+        if assigned != current_user:
+            return {
+                "available": False,
+                "type": "story",
+                "story": story,
+                "reason": f"Assigned to {assigned}",
+                "assigned_to": assigned,
+            }
+
+    # Check if already in progress
+    if status == "in_progress":
+        return {
+            "available": False,
+            "type": "story",
+            "story": story,
+            "reason": "Already in progress",
+            "assigned_to": assigned,
+        }
+
+    # Check if done
+    if status in ("done", "completed"):
+        return {
+            "available": False,
+            "type": "story",
+            "story": story,
+            "reason": "Already completed",
+        }
+
+    # Check if canceled
+    if status == "canceled":
+        return {
+            "available": False,
+            "type": "story",
+            "story": story,
+            "reason": "Story is canceled",
+        }
+
+    # Available statuses: backlog, ready, planning
+    return {
+        "available": True,
+        "type": "story",
+        "story": story,
+        "title": story.get("title"),
+        "points": story.get("points"),
+        "workflow": story.get("workflow", "tdd"),
+    }
+
+
+def get_next_story() -> dict[str, Any]:
+    """Get the highest priority available story.
+
+    Considers stories with backlog, ready, or planning status.
+    Excludes stories assigned to other users.
+
+    Returns:
+        Dict with next story details or error
+    """
+    from pf.jira.client import get_current_user_email
+    from pf.sprint.loader import get_all_stories
+
+    current_user = get_current_user_email()
+    all_stories = get_all_stories()
+    available_statuses = {"backlog", "ready", "planning"}
+    backlog = [
+        s for s in all_stories
+        if s.get("status") in available_statuses
+        and (not s.get("assigned_to") or s.get("assigned_to") == current_user)
+    ]
+
+    if not backlog:
+        return {
+            "available": False,
+            "error": "No stories in backlog",
+        }
+
+    # Sort by priority (P0 > P1 > P2 > P3), preferring own assignments
+    priority_order = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+    sorted_stories = sorted(
+        backlog,
+        key=lambda s: (
+            0 if s.get("assigned_to") == current_user else 1,
+            priority_order.get(s.get("priority", "P2"), 2),
+        ),
+    )
+
+    next_story = sorted_stories[0]
+    return {
+        "available": True,
+        "type": "next",
+        "story": next_story,
+        "title": next_story.get("title"),
+        "points": next_story.get("points"),
+        "priority": next_story.get("priority", "P2"),
+    }
+
+
+def start_work(story_id: str, *, dry_run: bool = False) -> dict[str, Any]:
+    """Start work on a story.
+
+    Args:
+        story_id: Story ID to start
+        dry_run: If True, don't make changes
+
+    Returns:
+        Dict with success status and details
+    """
+    # Check availability
+    check = check_story(story_id)
+    if not check.get("available"):
+        return {
+            "success": False,
+            "error": check.get("reason") or check.get("error"),
+        }
+
+    story = check.get("story")
+
+    if dry_run:
+        return {
+            "success": True,
+            "dry_run": True,
+            "story": story,
+            "message": f"Would start work on {story_id}",
+        }
+
+    # In a real implementation, this would:
+    # 1. Create/update session file
+    # 2. Claim in Jira
+    # 3. Create branch
+    # For now, return success with story info
+    return {
+        "success": True,
+        "story": story,
+        "message": f"Ready to start work on {story_id}",
+    }
+
+
+def main(args: list[str] | None = None) -> int:
+    """CLI entry point for sprint work.
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Exit code
+    """
+    import argparse
+    import sys
+
+    parser = argparse.ArgumentParser(description="Start work on a story")
+    parser.add_argument(
+        "story_id",
+        nargs="?",
+        help="Story ID (or 'next' for highest priority)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done",
+    )
+
+    parsed = parser.parse_args(args)
+
+    if not parsed.story_id:
+        # Show backlog
+        backlog = get_stories_by_status("backlog")
+        print(f"Available stories: {len(backlog)}")
+        for story in backlog[:10]:
+            print(f"  {story.get('id')}: {story.get('title')} [{story.get('points', '?')}pts]")
+        return 0
+
+    if parsed.story_id == "next":
+        result = get_next_story()
+    else:
+        result = check_story(parsed.story_id)
+
+    if result.get("available"):
+        story = result.get("story", {})
+        print(f"Story: {story.get('id')}")
+        print(f"Title: {story.get('title')}")
+        print(f"Points: {story.get('points')}")
+        print("Status: Available")
+        return 0
+    else:
+        print(f"Not available: {result.get('error') or result.get('reason')}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

package/pennyfarthing-dist/pf/story/__init__.py

@@ -0,0 +1,65 @@
+"""
+Story management package for Pennyfarthing scripts.
+
+This package provides:
+- size: Story sizing guidelines
+- template: Story templates
+- create: Story creation
+
+Usage:
+    # Use the modules
+    from pf.story import get_sizing_guidelines, get_template
+
+    # Use CLI
+    python -m pf.story <subcommand> [args]
+"""
+
+# Re-export common functions
+# Import submodules
+# CLI entry point - import module, not function, so "from story import cli" gets the module
+from pf.story import (
+    cli,
+    create,
+    size,
+    template,
+)
+from pf.story.cli import main
+from pf.story.create import (
+    create_story,
+    generate_story_yaml,
+    validate_points,
+)
+from pf.story.size import (
+    SIZING_GUIDELINES,
+    format_size_info,
+    get_sizing_guidelines,
+)
+from pf.story.template import (
+    TEMPLATES,
+    format_template,
+    get_all_templates,
+    get_template,
+)
+
+__all__ = [
+    # Size
+    "SIZING_GUIDELINES",
+    "format_size_info",
+    "get_sizing_guidelines",
+    # Template
+    "TEMPLATES",
+    "format_template",
+    "get_all_templates",
+    "get_template",
+    # Create
+    "create_story",
+    "generate_story_yaml",
+    "validate_points",
+    # Submodules
+    "create",
+    "size",
+    "template",
+    # CLI
+    "cli",
+    "main",
+]

package/pennyfarthing-dist/pf/story/__main__.py

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

package/pennyfarthing-dist/pf/story/cli.py

@@ -0,0 +1,105 @@
+"""
+Story CLI - Fan-out CLI for story operations.
+
+Usage:
+    python -m pf.story <subcommand> [args]
+
+Subcommands:
+    size        Show sizing guidelines
+    template    Show story templates
+    create      Create a new story
+"""
+
+import argparse
+import sys
+
+
+def size(args: list[str]) -> int:
+    """Show sizing guidelines."""
+    from pf.story.size import main as size_main
+    return size_main(args)
+
+
+def template(args: list[str]) -> int:
+    """Show story templates."""
+    from pf.story.template import main as template_main
+    return template_main(args)
+
+
+def create(args: list[str]) -> int:
+    """Create a new story."""
+    from pf.story.create import main as create_main
+    return create_main(args)
+
+
+# Subcommand registry
+SUBCOMMANDS = {
+    "size": size,
+    "template": template,
+    "create": create,
+}
+
+
+def cli(args: list[str] | None = None) -> int:
+    """Main CLI entry point.
+
+    Args:
+        args: Command line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code
+    """
+    if args is None:
+        args = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="story",
+        description="Story CLI for Pennyfarthing",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Subcommands:
+    size [points]       Show sizing guidelines (optionally for specific points)
+    template [type]     Show story templates (optionally for specific type)
+    create              Create a new story
+
+Examples:
+    story size
+    story size 3
+    story template feature
+    story create MSSCI-12000 "Add feature" 3 --type feature
+""",
+    )
+
+    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())

package/pennyfarthing-dist/pf/story/create.py

@@ -0,0 +1,167 @@
+"""
+Story creation utilities.
+
+Provides functions for creating new stories.
+"""
+
+from typing import Any
+
+from pf.story.size import SIZING_GUIDELINES
+from pf.story.template import format_template
+
+
+def generate_story_yaml(
+    epic_id: str,
+    title: str,
+    points: int,
+    story_type: str = "feature",
+    priority: str = "P2",
+    workflow: str | None = None,
+) -> str:
+    """Generate YAML block for a new story.
+
+    Args:
+        epic_id: Parent epic ID
+        title: Story title
+        points: Story points
+        story_type: Story type (feature, bug, refactor, chore)
+        priority: Priority (P0, P1, P2, P3)
+        workflow: Workflow override (defaults based on points)
+
+    Returns:
+        YAML block string
+    """
+    # Determine workflow based on points if not specified
+    if workflow is None:
+        sizing = SIZING_GUIDELINES.get(points, {})
+        workflow = sizing.get("workflow", "tdd")
+
+    # Generate story ID placeholder
+    story_id = f"{epic_id}-NEW"
+
+    return format_template(
+        story_type,
+        id=story_id,
+        title=title,
+        points=points,
+        priority=priority,
+        workflow=workflow,
+    )
+
+
+def validate_points(points: int) -> dict[str, Any]:
+    """Validate story points.
+
+    Args:
+        points: Story points value
+
+    Returns:
+        Dict with valid status and message
+    """
+    valid_points = [1, 2, 3, 5, 8, 13]
+
+    if points not in valid_points:
+        return {
+            "valid": False,
+            "warning": f"Points {points} not in standard sequence: {valid_points}",
+        }
+
+    if points >= 13:
+        return {
+            "valid": True,
+            "warning": "Consider splitting: 13+ point stories are typically too large",
+        }
+
+    return {"valid": True}
+
+
+def create_story(
+    epic_id: str,
+    title: str,
+    points: int,
+    story_type: str = "feature",
+    priority: str = "P2",
+    workflow: str | None = None,
+    *,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Create a new story.
+
+    Args:
+        epic_id: Parent epic ID
+        title: Story title
+        points: Story points
+        story_type: Story type
+        priority: Priority
+        workflow: Workflow override
+        dry_run: If True, don't write to file
+
+    Returns:
+        Dict with success status and story YAML
+    """
+    # Validate points
+    validation = validate_points(points)
+
+    yaml_block = generate_story_yaml(
+        epic_id=epic_id,
+        title=title,
+        points=points,
+        story_type=story_type,
+        priority=priority,
+        workflow=workflow,
+    )
+
+    return {
+        "success": True,
+        "dry_run": dry_run,
+        "yaml": yaml_block,
+        "warning": validation.get("warning"),
+    }
+
+
+def main(args: list[str] | None = None) -> int:
+    """CLI entry point for story create.
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Exit code
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Create a new story")
+    parser.add_argument("epic_id", help="Parent epic ID")
+    parser.add_argument("title", help="Story title")
+    parser.add_argument("points", type=int, help="Story points")
+    parser.add_argument("--type", choices=["feature", "bug", "refactor", "chore"], default="feature")
+    parser.add_argument("--priority", choices=["P0", "P1", "P2", "P3"], default="P2")
+    parser.add_argument("--workflow", help="Override workflow")
+    parser.add_argument("--dry-run", action="store_true", help="Show what would be created")
+
+    parsed = parser.parse_args(args)
+
+    result = create_story(
+        epic_id=parsed.epic_id,
+        title=parsed.title,
+        points=parsed.points,
+        story_type=parsed.type,
+        priority=parsed.priority,
+        workflow=parsed.workflow,
+        dry_run=parsed.dry_run,
+    )
+
+    if result.get("warning"):
+        print(f"Warning: {result['warning']}")
+        print("")
+
+    print("Add this to sprint/current-sprint.yaml under the epic's stories:")
+    print("")
+    print(result["yaml"])
+
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

package/pennyfarthing-dist/pf/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for pf package reorganization."""