@pennyfarthing/core 11.3.3 → 11.3.4

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

@@ -0,0 +1,372 @@
+"""Sprint story add command.
+
+Story: MSSCI-14256 - Sprint story add command
+
+This module provides:
+- generate_story_id(sprint_data, epic) -> str
+- add_story(sprint_path, epic_id, title, points, ...) -> dict
+- add_initiative_story(initiative_slug, title, points, ...) -> dict
+- story_add_command (Click command for CLI registration)
+"""
+
+from pathlib import Path
+from typing import Any
+
+import click
+from ruamel.yaml.comments import CommentedMap
+
+from pf.sprint.loader import find_epic
+from pf.sprint.validator import validate_full_sprint
+from pf.sprint.yaml_io import (
+    STORY_KEY_ORDER,
+    read_sprint,
+    write_sprint,
+)
+
+
+def _extract_epic_num(epic: Any) -> str:
+    """Extract the numeric part from an epic ID like 'epic-76' -> '76'."""
+    epic_id = str(epic.get("id", ""))
+    return epic_id.replace("epic-", "")
+
+
+def generate_story_id(sprint_data: Any, epic: Any) -> str:
+    """Generate the next story ID for an epic.
+
+    Args:
+        sprint_data: Full sprint YAML data
+        epic: The target epic dict/CommentedMap
+
+    Returns:
+        Next story ID string (e.g., "76-3")
+    """
+    epic_num = _extract_epic_num(epic)
+    stories = epic.get("stories", [])
+
+    max_seq = 0
+    for story in stories:
+        story_id = str(story.get("id", ""))
+        parts = story_id.split("-")
+        if len(parts) >= 2:
+            try:
+                seq = int(parts[-1])
+                if seq > max_seq:
+                    max_seq = seq
+            except ValueError:
+                pass
+
+    return f"{epic_num}-{max_seq + 1}"
+
+
+def add_story(
+    sprint_path: Path,
+    epic_id: str,
+    title: str,
+    points: int,
+    *,
+    story_type: str | None = None,
+    priority: str = "P1",
+    workflow: str = "tdd",
+    jira: str | None = None,
+) -> dict[str, Any]:
+    """Add a new story to an epic in the sprint YAML.
+
+    Args:
+        sprint_path: Path to sprint YAML file
+        epic_id: Epic ID to add the story to
+        title: Story title
+        points: Story points
+        story_type: Optional story type (feature, bug, chore, refactor)
+        priority: Priority (default: P1)
+        workflow: Workflow (default: tdd)
+        jira: Optional Jira key
+
+    Returns:
+        Dict with success status and story_id or error
+    """
+    data = read_sprint(sprint_path)
+
+    epic = find_epic(data, epic_id)
+    if epic is None:
+        available = []
+        for e in data.get("epics", []):
+            available.append(str(e.get("id", "")))
+        return {
+            "success": False,
+            "error": f"Epic '{epic_id}' not found. Available epics: {', '.join(available)}",
+        }
+
+    story_id = generate_story_id(data, epic)
+
+    # Build story as CommentedMap with canonical key ordering
+    story = CommentedMap()
+    fields: dict[str, Any] = {
+        "id": story_id,
+        "title": title,
+        "points": points,
+        "priority": priority,
+        "status": "backlog",
+        "workflow": workflow,
+    }
+    if jira is not None:
+        fields["jira"] = jira
+    if story_type is not None:
+        fields["type"] = story_type
+
+    # Insert keys in STORY_KEY_ORDER, then any extras
+    for key in STORY_KEY_ORDER:
+        if key in fields:
+            story[key] = fields[key]
+    for key in fields:
+        if key not in STORY_KEY_ORDER:
+            story[key] = fields[key]
+
+    # Append to epic's stories list
+    if "stories" not in epic:
+        from ruamel.yaml.comments import CommentedSeq
+        epic["stories"] = CommentedSeq()
+    epic["stories"].append(story)
+
+    # Validate before writing
+    result = validate_full_sprint(data)
+    if not result.valid:
+        # Remove the story we just added to avoid corrupting data
+        epic["stories"].pop()
+        return {
+            "success": False,
+            "error": f"Validation failed after insertion: {result.errors}",
+        }
+
+    write_sprint(sprint_path, data)
+
+    return {
+        "success": True,
+        "story_id": story_id,
+    }
+
+
+def _generate_initiative_story_id(init_data: dict[str, Any], slug: str) -> str:
+    """Generate the next standalone story ID for an initiative.
+
+    Uses the pattern {slug-prefix}-{N} where slug-prefix is derived from
+    the initiative slug (e.g., "technical-debt" -> "td", "quality-scale" -> "qs").
+    Only counts existing stories that share the same prefix.
+
+    Args:
+        init_data: Initiative YAML data
+        slug: Initiative slug (e.g., "technical-debt")
+
+    Returns:
+        Next story ID string (e.g., "td-2")
+    """
+    # Build prefix from initiative slug initials
+    parts = slug.split("-")
+    prefix = "".join(p[0] for p in parts if p)
+
+    stories = init_data.get("standalone_stories", [])
+    max_seq = 0
+    for story in stories:
+        story_id = str(story.get("id", ""))
+        # Only count stories with matching prefix
+        if not story_id.startswith(f"{prefix}-"):
+            continue
+        suffix = story_id[len(prefix) + 1:]
+        try:
+            seq = int(suffix)
+            if seq > max_seq:
+                max_seq = seq
+        except ValueError:
+            pass
+
+    return f"{prefix}-{max_seq + 1}"
+
+
+def add_initiative_story(
+    initiative_slug: str,
+    title: str,
+    points: int,
+    *,
+    story_type: str | None = None,
+    priority: str = "P1",
+    workflow: str = "tdd",
+    jira: str | None = None,
+    repos: str = "pennyfarthing",
+) -> dict[str, Any]:
+    """Add a standalone story to an initiative YAML file.
+
+    Args:
+        initiative_slug: Initiative slug (e.g., "technical-debt")
+        title: Story title
+        points: Story points
+        story_type: Optional story type (feature, bug, chore, refactor)
+        priority: Priority (default: P1)
+        workflow: Workflow (default: tdd)
+        jira: Optional Jira key
+        repos: Repos (default: pennyfarthing)
+
+    Returns:
+        Dict with success status and story_id or error
+    """
+    from pf.common.config import get_project_root
+
+    root = get_project_root()
+    init_path = root / "sprint" / f"initiative-{initiative_slug}.yaml"
+
+    if not init_path.exists():
+        available = [
+            f.stem.replace("initiative-", "")
+            for f in (root / "sprint").glob("initiative-*.yaml")
+        ]
+        return {
+            "success": False,
+            "error": f"Initiative '{initiative_slug}' not found. Available: {', '.join(sorted(available))}",
+        }
+
+    # Use ruamel.yaml to preserve block scalars and formatting
+    from ruamel.yaml import YAML as RuamelYAML
+
+    ryml = RuamelYAML()
+    ryml.preserve_quotes = True
+    ryml.default_flow_style = False
+    ryml.indent(mapping=2, sequence=4, offset=2)
+    ryml.width = 4096
+
+    with open(init_path) as f:
+        init_data = ryml.load(f)
+
+    if not init_data:
+        return {"success": False, "error": f"Empty initiative file: {init_path}"}
+
+    story_id = _generate_initiative_story_id(init_data, initiative_slug)
+
+    story: dict[str, Any] = {
+        "id": story_id,
+        "title": title,
+        "points": points,
+        "priority": priority,
+        "status": "backlog",
+        "repos": repos,
+        "workflow": workflow,
+    }
+    if jira is not None:
+        story["jira"] = jira
+    if story_type is not None:
+        story["type"] = story_type
+
+    if "standalone_stories" not in init_data:
+        init_data["standalone_stories"] = []
+    init_data["standalone_stories"].append(story)
+
+    # Update total_points
+    current_total = init_data.get("total_points", 0) or 0
+    init_data["total_points"] = current_total + points
+
+    with open(init_path, "w") as f:
+        ryml.dump(init_data, f)
+
+    return {
+        "success": True,
+        "story_id": story_id,
+    }
+
+
+@click.command("add")
+@click.argument("epic_id", type=str, required=False)
+@click.argument("title", type=str, required=False)
+@click.argument("points", type=int, required=False)
+@click.option("--type", "story_type", type=click.Choice(["feature", "bug", "chore", "refactor"]), default="feature")
+@click.option("--priority", type=click.Choice(["p0", "p1", "p2", "p3"], case_sensitive=False), default="p1")
+@click.option("--workflow", type=click.Choice(["tdd", "trivial", "bdd"]), default="tdd")
+@click.option("--jira", "jira_id", type=str, default=None)
+@click.option("--sprint-file", type=click.Path(), default=None, help="Path to sprint YAML file")
+@click.option("--initiative", type=str, default=None, help="Add as standalone story to initiative (e.g., technical-debt)")
+@click.option("--repos", type=str, default="pennyfarthing", help="Repos (default: pennyfarthing)")
+@click.option("--dry-run", is_flag=True, help="Show what would be done without making changes")
+def story_add_command(
+    epic_id: str | None,
+    title: str | None,
+    points: int | None,
+    story_type: str,
+    priority: str,
+    workflow: str,
+    jira_id: str | None,
+    sprint_file: str | None,
+    initiative: str | None,
+    repos: str,
+    dry_run: bool,
+) -> None:
+    """Add a new story to an epic or initiative.
+
+    \b
+    Epic mode (default):
+      pf sprint story add <EPIC_ID> <TITLE> <POINTS>
+
+    Initiative mode (--initiative):
+      pf sprint story add --initiative <SLUG> <TITLE> <POINTS>
+    """
+    if initiative:
+        # Initiative mode: first positional arg is title, second is points
+        # epic_id absorbs the title, title absorbs points (as str)
+        if epic_id is None:
+            raise click.ClickException("TITLE is required")
+        init_title = epic_id
+        if title is None:
+            raise click.ClickException("POINTS is required")
+        try:
+            init_points = int(title)
+        except ValueError as err:
+            raise click.ClickException(f"POINTS must be an integer, got '{title}'") from err
+
+        if dry_run:
+            click.echo(f"[DRY-RUN] Would add story to initiative {initiative}: {init_title} [{init_points}pts]")
+            return
+
+        result = add_initiative_story(
+            initiative_slug=initiative,
+            title=init_title,
+            points=init_points,
+            story_type=story_type if story_type != "feature" else None,
+            priority=priority,
+            workflow=workflow,
+            jira=jira_id,
+            repos=repos,
+        )
+
+        if result["success"]:
+            click.echo(f"Added story {result['story_id']}: {init_title} [{init_points}pts] to initiative {initiative}")
+        else:
+            raise click.ClickException(result["error"])
+    else:
+        # Epic mode: all three positional args required
+        if epic_id is None:
+            raise click.ClickException("EPIC_ID is required")
+        if title is None:
+            raise click.ClickException("TITLE is required")
+        if points is None:
+            raise click.ClickException("POINTS is required")
+
+        if dry_run:
+            click.echo(f"[DRY-RUN] Would add story to epic {epic_id}: {title} [{points}pts]")
+            return
+
+        if sprint_file is None:
+            from pf.common.config import get_project_root
+            path = get_project_root() / "sprint" / "current-sprint.yaml"
+        else:
+            path = Path(sprint_file)
+
+        result = add_story(
+            sprint_path=path,
+            epic_id=epic_id,
+            title=title,
+            points=points,
+            story_type=story_type if story_type != "feature" else None,
+            priority=priority,
+            workflow=workflow,
+            jira=jira_id,
+        )
+
+        if result["success"]:
+            click.echo(f"Added story {result['story_id']}: {title} [{points}pts]")
+        else:
+            raise click.ClickException(result["error"])

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

@@ -0,0 +1,227 @@
+"""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.yaml_io import read_sprint, write_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:
+        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:
+            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 ---
+    if 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})
+
+    # --- Step 3: Transition Jira ---
+    if jira_key:
+        result = _run(["jira", "issue", "move", jira_key, "Done"])
+        if result.returncode == 0:
+            steps.append({"step": 3, "action": "jira_done", "key": jira_key})
+        else:
+            steps.append({"step": 3, "action": "jira_done", "key": jira_key, "warning": "Already Done or failed"})
+    else:
+        steps.append({"step": 3, "action": "jira_done", "skipped": True, "warning": "No Jira key available"})
+
+    # --- Step 4: Update sprint YAML ---
+    try:
+        data = read_sprint(sprint_path)
+        parts = story_id.split("-")
+        if len(parts) < 2:
+            steps.append({"step": 4, "action": "yaml_update", "error": f"Invalid story ID: {story_id}"})
+        else:
+            epic = find_epic(data, parts[0])
+            story = find_story(epic, story_id) if epic else None
+            if story:
+                story["status"] = "done"
+                story["completed"] = today
+                write_sprint(sprint_path, data)
+                steps.append({"step": 4, "action": "yaml_update", "status": "done", "completed": today})
+            else:
+                steps.append({"step": 4, "action": "yaml_update", "warning": f"Story {story_id} not found in YAML"})
+    except Exception as exc:
+        steps.append({"step": 4, "action": "yaml_update", "error": str(exc)})
+
+    # --- 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,
+    }