@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/src/pf/sprint/status.py

@@ -0,0 +1,187 @@
+"""
+Sprint status operations.
+
+Provides functions for getting and displaying sprint status.
+"""
+
+from typing import Any
+
+from pf.sprint.loader import get_sprint_info, load_sprint
+
+
+# Map CLI filter names to YAML status values
+_FILTER_MAP: dict[str, set[str]] = {
+    "backlog": {"backlog", "ready", "planning"},
+    "todo": {"backlog", "ready", "planning"},
+    "in-progress": {"in_progress", "in-progress"},
+    "in_progress": {"in_progress", "in-progress"},
+    "in-review": {"in_review", "in-review"},
+    "in_review": {"in_review", "in-review"},
+    "done": {"done", "completed"},
+    "completed": {"done", "completed"},
+}
+
+
+def get_sprint_status(filter_status: str | None = None) -> dict[str, Any]:
+    """Get sprint status with story counts.
+
+    Args:
+        filter_status: Optional status to filter by
+
+    Returns:
+        Dict with sprint status information
+    """
+    sprint_info = get_sprint_info()
+    data = load_sprint()
+    if not data or "epics" not in data:
+        return {}
+
+    # Collect stories annotated with parent epic title
+    stories: list[dict] = []
+    for epic in data.get("epics", []):
+        if not isinstance(epic, dict):
+            continue
+        epic_title = epic.get("title", "").removeprefix("Epic: ")
+        for s in epic.get("stories", []):
+            s["_epic_title"] = epic_title
+            stories.append(s)
+    # Include standalone stories
+    for s in data.get("standalone_stories", []):
+        s["_epic_title"] = "(standalone)"
+        stories.append(s)
+
+    if not stories:
+        return {}
+
+    # Count by status
+    status_counts: dict[str, int] = {}
+    total_points = 0
+    completed_points = 0
+
+    for story in stories:
+        status = story.get("status", "backlog")
+        points = story.get("points", 0) or 0
+
+        status_counts[status] = status_counts.get(status, 0) + 1
+        total_points += points
+
+        if status in ("done", "completed"):
+            completed_points += points
+
+    # Collect filtered stories if a filter is set
+    filtered_stories: list[dict] = []
+    if filter_status:
+        match_statuses = _FILTER_MAP.get(filter_status, {filter_status})
+        filtered_stories = [
+            s for s in stories
+            if s.get("status", "backlog") in match_statuses
+        ]
+
+    return {
+        "sprint": sprint_info,
+        "total_stories": len(stories),
+        "by_status": status_counts,
+        "backlog": status_counts.get("backlog", 0),
+        "in_progress": status_counts.get("in_progress", 0),
+        "in_review": status_counts.get("in_review", 0),
+        "completed": status_counts.get("done", 0) + status_counts.get("completed", 0),
+        "total_points": total_points,
+        "completed_points": completed_points,
+        "filter": filter_status,
+        "filtered_stories": filtered_stories,
+    }
+
+
+def format_status(status: dict[str, Any]) -> str:
+    """Format sprint status as human-readable string.
+
+    Args:
+        status: Status dict from get_sprint_status
+
+    Returns:
+        Formatted status string
+    """
+    if not status:
+        return "No sprint data available"
+
+    lines = []
+
+    # Sprint header
+    sprint = status.get("sprint", {})
+    if sprint:
+        lines.append(f"Sprint: {sprint.get('name', 'Unknown')}")
+        lines.append(f"Status: {sprint.get('status', 'unknown')}")
+        if sprint.get("goal"):
+            lines.append(f"Goal: {sprint['goal']}")
+        lines.append("")
+
+    # If filtered, show matching stories as a table
+    filtered = status.get("filtered_stories", [])
+    filter_name = status.get("filter")
+
+    if filter_name and filtered:
+        label = filter_name.replace("-", " ").replace("_", " ").title()
+        lines.append(f"## {label} Stories ({len(filtered)})")
+        lines.append("")
+        lines.append("| ID | Title | Pts | Epic | Workflow |")
+        lines.append("|----|-------|-----|------|----------|")
+        for s in filtered:
+            title = s.get("title", "?")
+            if len(title) > 45:
+                title = title[:42] + "..."
+            sid = s.get("id", "?")
+            pts = s.get("points", "?")
+            epic = s.get("_epic_title", "")
+            wf = s.get("workflow", "")
+            lines.append(f"| {sid} | {title} | {pts} | {epic} | {wf} |")
+        lines.append("")
+        return "\n".join(lines)
+
+    if filter_name and not filtered:
+        lines.append(f"No stories with status: {filter_name}")
+        return "\n".join(lines)
+
+    # Default: summary counts
+    lines.append(f"Total Stories: {status.get('total_stories', 0)}")
+    lines.append(f"  Backlog: {status.get('backlog', 0)}")
+    lines.append(f"  In Progress: {status.get('in_progress', 0)}")
+    lines.append(f"  In Review: {status.get('in_review', 0)}")
+    lines.append(f"  Completed: {status.get('completed', 0)}")
+    lines.append("")
+
+    # Points
+    lines.append(f"Points: {status.get('completed_points', 0)}/{status.get('total_points', 0)}")
+
+    return "\n".join(lines)
+
+
+def main(args: list[str] | None = None) -> int:
+    """CLI entry point for sprint status.
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Exit code
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Show sprint status")
+    parser.add_argument(
+        "filter",
+        nargs="?",
+        choices=["backlog", "todo", "in-progress", "in-review", "done"],
+        help="Filter by status",
+    )
+
+    parsed = parser.parse_args(args)
+
+    status = get_sprint_status(parsed.filter)
+    print(format_status(status))
+
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

package/pennyfarthing-dist/src/pf/sprint/story_finish.py

@@ -0,0 +1,229 @@
+"""Finish a completed story: archive, merge PR, update Jira, update YAML.
+
+Replaces finish-story.sh with native Python that correctly handles
+sharded epic YAML files via read_sprint/write_sprint.
+
+Steps:
+  1. Archive session file to sprint/archive/{jira-key}-session.md
+  2. Squash merge PR via gh (handle already-merged)
+  3. Transition Jira to Done
+  4. Update sprint YAML (status: done, completed date)
+  5. Archive completed epics
+  6. Git cleanup (checkout develop, pull, delete local branch)
+  7. Remove session file
+"""
+
+import re
+import shutil
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from pf.sprint.loader import find_epic, find_story
+from pf.sprint.story_transition import transition_story
+from pf.sprint.yaml_io import read_sprint
+
+SESSION_FIELD_RE = re.compile(r"\*\*(\w[\w\s]*):\*\*\s*(.*)")
+
+
+def _parse_session(session_path: Path) -> dict[str, str]:
+    """Extract metadata fields from a session markdown file.
+
+    Parses lines like ``**Jira:** MSSCI-14467`` and
+    ``**PR:** #748 - title`` into a dict.
+    """
+    fields: dict[str, str] = {}
+    if not session_path.exists():
+        return fields
+    for line in session_path.read_text().splitlines():
+        m = SESSION_FIELD_RE.search(line)
+        if m:
+            key = m.group(1).strip().lower()
+            value = m.group(2).strip()
+            fields[key] = value
+    return fields
+
+
+def _extract_jira_key(fields: dict[str, str]) -> str | None:
+    """Get Jira key from session fields, handling markdown link format."""
+    raw = fields.get("jira", "")
+    # Strip markdown link: [MSSCI-14467](https://...)
+    raw = re.sub(r"\[([^\]]+)\].*", r"\1", raw).strip()
+    if re.match(r"^MSSCI-\d+$", raw):
+        return raw
+    return None
+
+
+def _extract_pr_number(fields: dict[str, str]) -> str | None:
+    """Get PR number from session fields like ``#748 - title``."""
+    raw = fields.get("pr", "")
+    m = re.search(r"#(\d+)", raw)
+    return m.group(1) if m else None
+
+
+def _extract_branch(fields: dict[str, str]) -> str | None:
+    """Get branch name, stripping trailing annotations like ``(pushed)``."""
+    raw = fields.get("branch", "")
+    return re.sub(r"\s*\(.*\)\s*$", "", raw).strip() or None
+
+
+def _run(cmd: list[str], **kwargs: Any) -> subprocess.CompletedProcess[str]:
+    """Run a subprocess with sane defaults."""
+    return subprocess.run(cmd, capture_output=True, text=True, **kwargs)
+
+
+def finish_story(
+    project_root: Path,
+    story_id: str,
+    *,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Finish a story: archive, merge, update Jira, update YAML, clean up.
+
+    Args:
+        project_root: Project root directory.
+        story_id: Story ID (e.g., "83-2").
+        dry_run: If True, report what would happen without side-effects.
+
+    Returns:
+        Result dict ``{success, data?, error?, steps?}``.
+    """
+    session_path = project_root / ".session" / f"{story_id}-session.md"
+    sprint_path = project_root / "sprint" / "current-sprint.yaml"
+    archive_dir = project_root / "sprint" / "archive"
+    archive_dir.mkdir(parents=True, exist_ok=True)
+
+    # --- Validate session ---
+    if not session_path.exists():
+        return {"success": False, "error": f"Session file not found: {session_path}"}
+
+    fields = _parse_session(session_path)
+    jira_key = _extract_jira_key(fields)
+    branch = _extract_branch(fields)
+    pr_number = _extract_pr_number(fields)
+
+    # Fallback: resolve Jira key from sprint YAML
+    if not jira_key:
+        try:
+            data = read_sprint(sprint_path)
+            parts = story_id.split("-")
+            if len(parts) >= 2:
+                epic = find_epic(data, parts[0])
+                story = find_story(epic, story_id) if epic else None
+                if story:
+                    jira_key = story.get("jira")
+        except Exception:
+            pass
+
+    # Fallback: resolve PR from GitHub if not in session
+    if not pr_number and branch:
+        result = _run(["gh", "pr", "list", "--head", branch, "--json", "number", "--jq", ".[0].number"])
+        if result.returncode == 0 and result.stdout.strip():
+            pr_number = result.stdout.strip()
+
+    today = date.today().isoformat()
+    steps: list[dict[str, Any]] = []
+    archive_name = f"{jira_key}-session.md" if jira_key else f"{story_id}-session.md"
+
+    # Check for dialogue file
+    dialogue_path = project_root / ".session" / f"{story_id}-dialogue.md"
+    dialogue_archive_name = (
+        f"{jira_key}-dialogue.md" if jira_key else f"{story_id}-dialogue.md"
+    )
+
+    if dry_run:
+        from pf.common.pr_config import get_pr_merge_mode
+
+        steps.append({"step": 1, "action": f"Archive session → {archive_dir / archive_name}"})
+        if dialogue_path.exists():
+            steps.append({"step": "1b", "action": f"Archive dialogue → {archive_dir / dialogue_archive_name}"})
+        if pr_number and get_pr_merge_mode() == "human":
+            steps.append({"step": 2, "action": f"PR #{pr_number} — waiting for human review and merge"})
+        elif pr_number:
+            steps.append({"step": 2, "action": f"Merge PR #{pr_number} (squash, delete branch)"})
+        else:
+            steps.append({"step": 2, "action": "No PR to merge"})
+        if jira_key:
+            steps.append({"step": 3, "action": f"Transition {jira_key} to Done"})
+        else:
+            steps.append({"step": 3, "action": "Skip Jira transition (no key)"})
+        steps.append({"step": 4, "action": f"Update sprint YAML (status: done, completed: {today})"})
+        steps.append({"step": 5, "action": "Archive completed epics"})
+        steps.append({"step": 6, "action": f"Delete local branch: {branch}"})
+        steps.append({"step": 7, "action": "Remove session file"})
+        return {"success": True, "dry_run": True, "jira_key": jira_key, "steps": steps}
+
+    # --- Step 1: Archive session ---
+    archive_dest = archive_dir / archive_name
+    shutil.copy2(session_path, archive_dest)
+    steps.append({"step": 1, "action": "archive_session", "dest": str(archive_dest)})
+
+    # --- Step 1b: Archive dialogue (if exists) ---
+    if dialogue_path.exists():
+        dialogue_dest = archive_dir / dialogue_archive_name
+        shutil.copy2(dialogue_path, dialogue_dest)
+        steps.append({"step": "1b", "action": "archive_dialogue", "dest": str(dialogue_dest)})
+
+    # --- Step 2: Merge PR ---
+    from pf.common.pr_config import get_pr_merge_mode
+
+    pr_merge_mode = get_pr_merge_mode()
+    if pr_number and pr_merge_mode == "human":
+        steps.append({
+            "step": 2, "action": "merge_pr", "pr": pr_number,
+            "mode": "human", "message": f"PR #{pr_number} ready for human review and merge",
+        })
+    elif pr_number:
+        result = _run(["gh", "pr", "merge", pr_number, "--squash", "--delete-branch"])
+        if result.returncode == 0:
+            steps.append({"step": 2, "action": "merge_pr", "pr": pr_number})
+        else:
+            steps.append({"step": 2, "action": "merge_pr", "pr": pr_number, "warning": "Already merged or failed"})
+    else:
+        steps.append({"step": 2, "action": "merge_pr", "skipped": True})
+
+    # --- Steps 3 & 4: Transition via state machine (Jira + YAML atomically) ---
+    # Two-step: in_progress → in_review → done (state machine requires review step)
+    t_result = transition_story(project_root, story_id, "in_review")
+    if t_result.get("success"):
+        t_result = transition_story(project_root, story_id, "done")
+    if t_result.get("success"):
+        if jira_key:
+            steps.append({"step": 3, "action": "jira_done", "key": jira_key})
+        else:
+            steps.append({"step": 3, "action": "jira_done", "skipped": True})
+        steps.append({"step": 4, "action": "yaml_update", "status": "done", "completed": today})
+    else:
+        if jira_key:
+            steps.append({"step": 3, "action": "jira_done", "key": jira_key, "warning": t_result.get("error", "Transition failed")})
+        else:
+            steps.append({"step": 3, "action": "jira_done", "skipped": True, "warning": "No Jira key available"})
+        steps.append({"step": 4, "action": "yaml_update", "warning": t_result.get("error", "Transition failed")})
+
+    # --- Step 5: Archive completed epics ---
+    result = _run(
+        [sys.executable, "-m", "pf.cli", "sprint", "epic", "archive"],
+        cwd=str(project_root),
+    )
+    steps.append({"step": 5, "action": "archive_epics", "ran": True})
+
+    # --- Step 6: Git cleanup ---
+    _run(["git", "checkout", "develop"], cwd=str(project_root))
+    _run(["git", "pull", "origin", "develop"], cwd=str(project_root))
+    if branch:
+        _run(["git", "branch", "-d", branch], cwd=str(project_root))
+    steps.append({"step": 6, "action": "git_cleanup", "branch": branch})
+
+    # --- Step 7: Remove session file ---
+    if session_path.exists():
+        session_path.unlink()
+    steps.append({"step": 7, "action": "remove_session"})
+
+    return {
+        "success": True,
+        "story_id": story_id,
+        "jira_key": jira_key,
+        "steps": steps,
+    }

package/pennyfarthing-dist/src/pf/sprint/story_transition.py

@@ -0,0 +1,183 @@
+"""Story lifecycle state machine with transition validation.
+
+Story: MSSCI-15428 - Implement story lifecycle state machine
+
+Provides:
+- TRANSITIONS: valid state transitions map
+- transition_story(project_root, story_id, target_status, ...) -> dict
+"""
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from pf.jira.client import get_client
+from pf.sprint.loader import find_epic, find_story
+from pf.sprint.yaml_io import read_sprint, write_sprint
+
+# Valid transitions: from_status -> set of allowed to_statuses
+TRANSITIONS: dict[str, set[str]] = {
+    "backlog": {"in_progress", "canceled"},
+    "in_progress": {"in_review", "canceled"},
+    "in_review": {"done", "canceled"},
+    "done": {"canceled"},
+    "canceled": set(),
+}
+
+_JIRA_STATUS: dict[str, str] = {
+    "backlog": "To Do",
+    "in_progress": "In Progress",
+    "in_review": "In Review",
+    "done": "Done",
+    "canceled": "Canceled",
+}
+
+
+def transition_story(
+    project_root: Path,
+    story_id: str,
+    target_status: str,
+    *,
+    reason: str | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Transition a story to a new status.
+
+    Ordering: YAML first (most important), then Jira (external).
+    If Jira fails, YAML change persists and result reports partial failure.
+    """
+    # Validate story_id format
+    parts = story_id.split("-")
+    if len(parts) < 2 or not parts[0].isdigit():
+        return {
+            "success": False,
+            "story_id": story_id,
+            "error": f"Invalid story ID format: {story_id}",
+            "steps": [],
+        }
+
+    # Load sprint data and find story
+    sprint_path = project_root / "sprint" / "current-sprint.yaml"
+    data = read_sprint(sprint_path)
+    epic = find_epic(data, parts[0])
+    story = find_story(epic, story_id) if epic else None
+
+    if not story:
+        return {
+            "success": False,
+            "story_id": story_id,
+            "error": f"Story {story_id} not found in sprint YAML",
+            "steps": [],
+        }
+
+    from_status = story["status"]
+    jira_key = story.get("jira")
+
+    # Validate transition is legal
+    valid_targets = TRANSITIONS.get(from_status, set())
+    if target_status not in valid_targets:
+        return {
+            "success": False,
+            "story_id": story_id,
+            "jira_key": jira_key,
+            "from_status": from_status,
+            "to_status": target_status,
+            "error": (
+                f"Cannot transition from {from_status} to {target_status}. "
+                f"Valid targets from {from_status}: {sorted(valid_targets)}"
+            ),
+            "steps": [],
+        }
+
+    # Dry run: validate only, no side effects
+    if dry_run:
+        return {
+            "success": True,
+            "story_id": story_id,
+            "jira_key": jira_key,
+            "from_status": from_status,
+            "to_status": target_status,
+            "steps": [],
+        }
+
+    steps: list[dict[str, Any]] = []
+
+    # Step 1: Update YAML (always first — most important state)
+    story["status"] = target_status
+    if target_status == "in_progress" and "started" not in story:
+        story["started"] = date.today().isoformat()
+    if target_status == "done":
+        story["completed"] = date.today().isoformat()
+    write_sprint(sprint_path, data)
+    steps.append({
+        "step": 1,
+        "action": "yaml_update",
+        "success": True,
+        "status": f"{from_status}\u2192{target_status}",
+    })
+
+    # Step 2: Jira transition
+    if jira_key:
+        jira_target = _JIRA_STATUS.get(target_status, target_status)
+        try:
+            client = get_client()
+            jira_result = client.transition_sync(jira_key, jira_target)
+            if jira_result.get("success"):
+                steps.append({
+                    "step": 2,
+                    "action": "jira_transition",
+                    "success": True,
+                })
+            else:
+                steps.append({
+                    "step": 2,
+                    "action": "jira_transition",
+                    "success": False,
+                    "error": jira_result.get("error", "Jira transition failed"),
+                })
+        except Exception as exc:
+            steps.append({
+                "step": 2,
+                "action": "jira_transition",
+                "success": False,
+                "error": str(exc),
+            })
+    else:
+        steps.append({
+            "step": 2,
+            "action": "jira_transition",
+            "skipped": True,
+        })
+
+    # Check for any step failures
+    failed = [s for s in steps if s.get("success") is False]
+    if failed:
+        jira_failed = any(
+            s.get("action") == "jira_transition" and s.get("success") is False
+            for s in steps
+        )
+        result: dict[str, Any] = {
+            "success": False,
+            "story_id": story_id,
+            "jira_key": jira_key,
+            "from_status": from_status,
+            "to_status": target_status,
+            "error": f"Jira sync failed: YAML updated to {target_status} but Jira transition failed",
+            "steps": steps,
+        }
+        if jira_failed:
+            result["drift"] = True
+            jira_target = _JIRA_STATUS.get(target_status, target_status)
+            result["remediation"] = (
+                f'Run `pf jira move {jira_key} "{jira_target}"` to manually sync Jira'
+            )
+        return result
+
+    return {
+        "success": True,
+        "story_id": story_id,
+        "jira_key": jira_key,
+        "from_status": from_status,
+        "to_status": target_status,
+        "steps": steps,
+    }