@pennyfarthing/core 11.2.2 → 11.3.2

package/pennyfarthing_scripts/bmad/cli.py

@@ -0,0 +1,197 @@
+"""
+CLI commands for BMAD adapter.
+
+Provides:
+    pf bmad import <path>              — Initial import from BMAD project
+    pf bmad sync --pull [--dry-run]    — Pull BMAD changes into PF YAML
+    pf bmad sync --push [--dry-run]    — Push PF changes to BMAD markdown
+    pf bmad sync --both [--dry-run]    — Bidirectional sync
+    pf bmad status                     — Drift report
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def bmad():
+    """BMAD adapter — bidirectional sprint sync."""
+    pass
+
+
+# =============================================================================
+# pf bmad import
+# =============================================================================
+
+
+@bmad.command("import")
+@click.argument("bmad_path", type=click.Path(exists=True))
+@click.option("--repos", default="axiathon", help="Default repos value for stories")
+@click.option("--dry-run", is_flag=True, help="Preview without writing")
+def bmad_import(bmad_path: str, repos: str, dry_run: bool):
+    """Import a BMAD project into PF sprint YAML.
+
+    BMAD_PATH is the path to the _bmad-output/ directory.
+    """
+    from pennyfarthing_scripts.bmad.importer import import_bmad_project
+    from pennyfarthing_scripts.common.config import get_project_root
+
+    root = get_project_root()
+    sprint_dir = root / "sprint"
+    source = Path(bmad_path).resolve()
+
+    result = import_bmad_project(
+        bmad_root=source,
+        sprint_dir=sprint_dir,
+        repos=repos,
+        dry_run=dry_run,
+        project_root=root,
+    )
+
+    if result.get("success"):
+        prefix = "[DRY-RUN] " if result.get("dry_run") else ""
+        click.echo(f"{prefix}{result['message']}")
+        click.echo(f"  Epics:   {result['epics_count']}")
+        click.echo(f"  Stories: {result['stories_count']}")
+        click.echo(f"  Points:  {result['total_points']}")
+        if result.get("epic_ids"):
+            click.echo(f"  Epic IDs: {', '.join(result['epic_ids'])}")
+    else:
+        click.echo(f"Failed: {result.get('error')}", err=True)
+        raise SystemExit(1)
+
+
+# =============================================================================
+# pf bmad sync
+# =============================================================================
+
+
+@bmad.command()
+@click.option("--pull", "direction", flag_value="pull", help="Pull BMAD changes into PF")
+@click.option("--push", "direction", flag_value="push", help="Push PF changes to BMAD")
+@click.option("--both", "direction", flag_value="both", help="Bidirectional sync")
+@click.option("--dry-run", is_flag=True, help="Preview without applying")
+@click.option("--pf-wins", is_flag=True, default=True, help="PF status wins on conflict (default)")
+@click.option("--bmad-wins", is_flag=True, help="BMAD status wins on conflict")
+@click.option("--import-new", is_flag=True, help="Import new BMAD stories not in PF")
+def sync(
+    direction: str | None,
+    dry_run: bool,
+    pf_wins: bool,
+    bmad_wins: bool,
+    import_new: bool,
+):
+    """Sync status between PF YAML and BMAD markdown."""
+    if not direction:
+        click.echo("Specify --pull, --push, or --both", err=True)
+        raise SystemExit(1)
+
+    from pennyfarthing_scripts.bmad.parser import discover_bmad_stories
+    from pennyfarthing_scripts.bmad.sync import (
+        _collect_pf_stories,
+        execute_sync_plan,
+        format_sync_plan,
+        generate_sync_plan,
+    )
+    from pennyfarthing_scripts.common.config import get_project_root, load_pennyfarthing_config
+
+    root = get_project_root()
+    config = load_pennyfarthing_config(root)
+    bmad_config = config.get("bmad", {})
+
+    source_root_str = bmad_config.get("source_root")
+    if not source_root_str:
+        click.echo(
+            "No bmad.source_root configured in .pennyfarthing/config.local.yaml",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    bmad_root = (root / source_root_str).resolve()
+    if not bmad_root.is_dir():
+        click.echo(f"BMAD source root not found: {bmad_root}", err=True)
+        raise SystemExit(1)
+
+    sprint_path = root / "sprint" / "current-sprint.yaml"
+    if not sprint_path.exists():
+        click.echo(f"Sprint file not found: {sprint_path}", err=True)
+        click.echo("Run 'pf bmad import' first.", err=True)
+        raise SystemExit(1)
+
+    story_subdir = bmad_config.get("story_dir", "implementation-artifacts")
+    wins_pf = not bmad_wins
+
+    pf_stories = _collect_pf_stories(sprint_path)
+    bmad_stories = discover_bmad_stories(bmad_root, story_dir=story_subdir)
+
+    plan = generate_sync_plan(
+        pf_stories,
+        bmad_stories,
+        direction=direction,
+        pf_wins=wins_pf,
+    )
+
+    click.echo(format_sync_plan(plan))
+
+    if not plan.changes and not (import_new and plan.bmad_only):
+        return
+
+    result = execute_sync_plan(
+        plan,
+        dry_run=dry_run,
+        sprint_path=sprint_path,
+        bmad_root=bmad_root,
+        import_new=import_new,
+    )
+
+    if dry_run:
+        click.echo(f"\n[DRY-RUN] {result.changes_planned} changes would be applied")
+        if import_new and plan.bmad_only:
+            click.echo(f"[DRY-RUN] {len(plan.bmad_only)} new stories would be imported")
+        return
+
+    click.echo(f"\nApplied {result.changes_applied}/{result.changes_planned} changes")
+    if result.new_stories_imported:
+        click.echo(f"Imported {result.new_stories_imported} new stories")
+    if result.errors:
+        for err in result.errors:
+            click.echo(f"  Error: {err}", err=True)
+        raise SystemExit(1)
+
+
+# =============================================================================
+# pf bmad status
+# =============================================================================
+
+
+@bmad.command()
+def status():
+    """Show drift report — what's out of sync between PF and BMAD."""
+    from pennyfarthing_scripts.bmad.sync import drift_report
+    from pennyfarthing_scripts.common.config import get_project_root, load_pennyfarthing_config
+
+    root = get_project_root()
+    config = load_pennyfarthing_config(root)
+    bmad_config = config.get("bmad", {})
+
+    source_root_str = bmad_config.get("source_root")
+    if not source_root_str:
+        click.echo(
+            "No bmad.source_root configured in .pennyfarthing/config.local.yaml",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    bmad_root = (root / source_root_str).resolve()
+    sprint_path = root / "sprint" / "current-sprint.yaml"
+
+    if not sprint_path.exists():
+        click.echo("No sprint file found. Run 'pf bmad import' first.", err=True)
+        raise SystemExit(1)
+
+    report = drift_report(sprint_path, bmad_root)
+    click.echo(report)

package/pennyfarthing_scripts/bmad/importer.py

@@ -0,0 +1,200 @@
+"""
+BMAD project importer — initial import from BMAD markdown to PF sprint YAML.
+
+Creates current-sprint.yaml + epic shard files from BMAD's
+implementation-artifacts/ and planning-artifacts/epics/ directories.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from pennyfarthing_scripts.bmad.parser import (
+    discover_bmad_epics,
+    discover_bmad_stories,
+    map_bmad_to_pf,
+)
+from pennyfarthing_scripts.common.config import get_project_root, load_pennyfarthing_config
+
+
+def _get_bmad_config(project_root: Path) -> dict[str, Any]:
+    """Read bmad section from .pennyfarthing/config.local.yaml."""
+    config = load_pennyfarthing_config(project_root)
+    return config.get("bmad", {})
+
+
+def _group_stories_by_epic(stories: list[dict]) -> dict[int, list[dict]]:
+    """Group story dicts by their epic number."""
+    groups: dict[int, list[dict]] = {}
+    for story in stories:
+        epic_num = int(story["epic_num"])
+        groups.setdefault(epic_num, []).append(story)
+    return groups
+
+
+def _build_epic_shard(
+    epic_num: int,
+    epic_meta: dict[str, Any] | None,
+    stories: list[dict],
+    repos: str,
+) -> dict[str, Any]:
+    """Build a PF epic shard dict from BMAD data.
+
+    Args:
+        epic_num: Epic number
+        epic_meta: Parsed BMAD epic metadata (or None if no epic file)
+        stories: List of parsed BMAD story dicts for this epic
+        repos: Default repos value
+
+    Returns:
+        PF epic shard dict ready for validation and writing.
+    """
+    title = epic_meta["title"] if epic_meta else f"Epic {epic_num}"
+    phase = epic_meta.get("phase", "MVP") if epic_meta else "MVP"
+
+    pf_stories: list[dict[str, Any]] = []
+    for story in stories:
+        pf_story: dict[str, Any] = {
+            "id": story["id"],
+            "title": story["title"],
+            "points": story.get("points", 3),
+            "priority": story.get("priority", "P1"),
+            "status": story["status"],
+            "repos": repos,
+            "workflow": story.get("workflow", "tdd"),
+            "bmad_key": story["bmad_key"],
+        }
+        if story.get("jira"):
+            pf_story["jira"] = story["jira"]
+        pf_stories.append(pf_story)
+
+    total_points = sum(s.get("points", 3) for s in pf_stories)
+
+    return {
+        "id": str(epic_num),
+        "title": title,
+        "status": "planning",
+        "description": f"Phase: {phase}",
+        "priority": "P1",
+        "points": total_points,
+        "marker": "bmad",
+        "repos": repos,
+        "stories": pf_stories,
+    }
+
+
+def import_bmad_project(
+    bmad_root: Path,
+    sprint_dir: Path,
+    *,
+    repos: str = "axiathon",
+    dry_run: bool = False,
+    project_root: Path | None = None,
+) -> dict[str, Any]:
+    """Import a BMAD project into PF sprint YAML.
+
+    Args:
+        bmad_root: Path to BMAD _bmad-output/ directory
+        sprint_dir: Path to PF sprint/ directory
+        repos: Default repos value for stories
+        dry_run: If True, preview without writing
+        project_root: Project root (auto-detect if None)
+
+    Returns:
+        Result dict with success, counts, and details.
+    """
+    from pennyfarthing_scripts.sprint.validator import validate_epic_shard
+    from pennyfarthing_scripts.sprint.yaml_io import write_sprint
+
+    root = project_root or get_project_root()
+    bmad_config = _get_bmad_config(root)
+
+    # Resolve paths from config if available
+    story_subdir = bmad_config.get("story_dir", "implementation-artifacts")
+    epic_subdir = bmad_config.get("epic_dir", "planning-artifacts/epics")
+
+    # Discover BMAD content
+    stories = discover_bmad_stories(bmad_root, story_dir=story_subdir)
+    epics_meta = discover_bmad_epics(bmad_root, epic_dir=epic_subdir)
+
+    if not stories:
+        return {"success": False, "error": f"No stories found in {bmad_root / story_subdir}"}
+
+    # Build epic metadata lookup
+    epic_lookup: dict[int, dict] = {e["epicNumber"]: e for e in epics_meta}
+
+    # Group stories by epic
+    grouped = _group_stories_by_epic(stories)
+
+    # Build epic shards
+    epic_shards: list[dict[str, Any]] = []
+    validation_errors: list[str] = []
+
+    for epic_num in sorted(grouped.keys()):
+        epic_stories = grouped[epic_num]
+        epic_meta = epic_lookup.get(epic_num)
+        shard = _build_epic_shard(epic_num, epic_meta, epic_stories, repos)
+
+        # Validate
+        result = validate_epic_shard(shard)
+        if not result.valid:
+            msgs = "; ".join(e.message for e in result.errors)
+            validation_errors.append(f"Epic {epic_num}: {msgs}")
+        else:
+            epic_shards.append(shard)
+
+    if validation_errors:
+        return {
+            "success": False,
+            "error": "Validation failed:\n  " + "\n  ".join(validation_errors),
+        }
+
+    total_stories = sum(len(e["stories"]) for e in epic_shards)
+    total_points = sum(e.get("points", 0) for e in epic_shards)
+
+    if dry_run:
+        return {
+            "success": True,
+            "dry_run": True,
+            "epics_count": len(epic_shards),
+            "stories_count": total_stories,
+            "total_points": total_points,
+            "epic_ids": [e["id"] for e in epic_shards],
+            "message": (
+                f"Would import {len(epic_shards)} epics, "
+                f"{total_stories} stories ({total_points} points)"
+            ),
+        }
+
+    # Build sprint data structure
+    today = date.today().isoformat()
+    sprint_data: dict[str, Any] = {
+        "sprint": {
+            "name": "BMAD Import",
+            "goal": f"Imported from BMAD on {today}",
+            "start_date": today,
+            "end_date": today,
+            "status": "active",
+        },
+        "epics": epic_shards,
+    }
+
+    # Write using shard-aware writer
+    sprint_path = sprint_dir / "current-sprint.yaml"
+    sprint_dir.mkdir(parents=True, exist_ok=True)
+    write_sprint(sprint_path, sprint_data)
+
+    return {
+        "success": True,
+        "epics_count": len(epic_shards),
+        "stories_count": total_stories,
+        "total_points": total_points,
+        "sprint_path": str(sprint_path),
+        "message": (
+            f"Imported {len(epic_shards)} epics, "
+            f"{total_stories} stories ({total_points} points) "
+            f"to {sprint_path}"
+        ),
+    }

package/pennyfarthing_scripts/bmad/parser.py

@@ -0,0 +1,233 @@
+"""
+BMAD markdown parser for Pennyfarthing sprint adapter.
+
+Reads BMAD story and epic markdown files and returns PF-compatible dicts.
+Story files: implementation-artifacts/{epic}-{story}-{slug}.md
+Epic files:  planning-artifacts/epics/epic-{nn}-{slug}.md
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+# =============================================================================
+# Status Mapping
+# =============================================================================
+
+BMAD_TO_PF_STATUS: dict[str, str] = {
+    "draft": "planning",
+    "ready-for-dev": "ready",
+    "in-progress": "in_progress",
+    "in-review": "in_progress",
+    "completed": "done",
+    "blocked": "backlog",
+}
+
+PF_TO_BMAD_STATUS: dict[str, str] = {
+    "planning": "draft",
+    "ready": "ready-for-dev",
+    "in_progress": "in-progress",
+    "done": "completed",
+    "backlog": "blocked",
+    "canceled": "completed",
+}
+
+
+def map_bmad_to_pf(bmad_status: str) -> str:
+    """Map a BMAD status string to a PF status."""
+    return BMAD_TO_PF_STATUS.get(bmad_status.strip().lower(), "planning")
+
+
+def map_pf_to_bmad(pf_status: str) -> str:
+    """Map a PF status string to a BMAD status."""
+    return PF_TO_BMAD_STATUS.get(pf_status.strip().lower(), "draft")
+
+
+# =============================================================================
+# Story Parsing
+# =============================================================================
+
+# Header patterns: flat Key: value lines after the # title
+_HEADER_PATTERNS: dict[str, re.Pattern[str]] = {
+    "status": re.compile(r"^Status:\s*(.+)$", re.MULTILINE),
+    "story_key": re.compile(r"^Story-Key:\s*(.+)$", re.MULTILINE),
+    "jira": re.compile(r"^Jira:\s*(.+)$", re.MULTILINE),
+    "epic_line": re.compile(r"^Epic:\s*(.+)$", re.MULTILINE),
+    "date": re.compile(r"^Date:\s*(.+)$", re.MULTILINE),
+}
+
+_TITLE_RE = re.compile(r"^#\s+Story\s+\d+\.\d+:\s*(.+)$", re.MULTILINE)
+
+# AC block: everything between ## Acceptance Criteria and the next ## heading
+_AC_RE = re.compile(
+    r"## Acceptance Criteria\s*\n(.*?)(?=\n## |\Z)", re.DOTALL
+)
+
+
+def parse_bmad_story(path: Path) -> dict[str, Any]:
+    """Parse a single BMAD story markdown file.
+
+    Args:
+        path: Path to the .md file in implementation-artifacts/
+
+    Returns:
+        PF-compatible story dict with extra bmad_key and bmad_path fields.
+    """
+    content = path.read_text()
+
+    # Extract header fields
+    fields: dict[str, str] = {}
+    for name, pattern in _HEADER_PATTERNS.items():
+        match = pattern.search(content)
+        if match:
+            fields[name] = match.group(1).strip()
+
+    story_key = fields.get("story_key", "")
+    parts = story_key.split("-", 2)  # e.g. "1-5-testing-framework" → ["1","5","testing-framework"]
+    epic_num = parts[0] if len(parts) >= 2 else "0"
+    story_num = parts[1] if len(parts) >= 2 else "0"
+    pf_id = f"{epic_num}-{story_num}"
+
+    # Title from # heading
+    title_match = _TITLE_RE.search(content)
+    title = title_match.group(1).strip() if title_match else path.stem
+
+    # BMAD status → PF status
+    bmad_status = fields.get("status", "draft")
+    pf_status = map_bmad_to_pf(bmad_status)
+
+    # Jira references (format: "DPGD-14 / DPGD-21")
+    jira_raw = fields.get("jira", "")
+
+    # Acceptance criteria summary
+    ac_match = _AC_RE.search(content)
+    ac_text = ac_match.group(1).strip() if ac_match else ""
+
+    return {
+        "id": pf_id,
+        "title": title,
+        "status": pf_status,
+        "points": 3,  # Default; BMAD stories don't carry points in impl artifacts
+        "priority": "P1",
+        "workflow": "tdd",
+        "bmad_key": story_key,
+        "bmad_status": bmad_status,
+        "bmad_path": str(path),
+        "jira": jira_raw,
+        "epic_num": epic_num,
+        "acceptance_criteria": ac_text,
+    }
+
+
+# =============================================================================
+# Epic Parsing
+# =============================================================================
+
+
+def parse_bmad_epic(path: Path) -> dict[str, Any]:
+    """Parse a BMAD epic markdown file with YAML frontmatter.
+
+    Args:
+        path: Path to epic-{nn}-{slug}.md in planning-artifacts/epics/
+
+    Returns:
+        Dict with epicNumber, title, phase, status, storyCount.
+    """
+    content = path.read_text()
+
+    # Extract YAML frontmatter between --- markers
+    fm_match = re.match(r"^---\s*\n(.*?)\n---", content, re.DOTALL)
+    if not fm_match:
+        return {
+            "epicNumber": 0,
+            "title": path.stem,
+            "phase": "MVP",
+            "status": "draft",
+            "storyCount": 0,
+        }
+
+    fm = yaml.safe_load(fm_match.group(1)) or {}
+    return {
+        "epicNumber": fm.get("epicNumber", 0),
+        "title": fm.get("title", path.stem),
+        "phase": fm.get("phase", "MVP"),
+        "status": fm.get("status", "draft"),
+        "storyCount": fm.get("storyCount", 0),
+    }
+
+
+# =============================================================================
+# Discovery
+# =============================================================================
+
+
+def discover_bmad_stories(
+    source_root: Path,
+    story_dir: str = "implementation-artifacts",
+) -> list[dict[str, Any]]:
+    """Scan BMAD implementation-artifacts/ and return parsed stories.
+
+    Args:
+        source_root: Path to _bmad-output/ (or equivalent)
+        story_dir: Subdirectory name for story files
+
+    Returns:
+        List of parsed story dicts, sorted by (epic_num, story_num).
+    """
+    artifacts_dir = source_root / story_dir
+    if not artifacts_dir.is_dir():
+        return []
+
+    stories: list[dict[str, Any]] = []
+    for md_file in sorted(artifacts_dir.glob("*.md")):
+        # Skip non-story files (e.g. 0-1-bmad-method-lifecycle.md is meta)
+        if md_file.name.startswith("0-"):
+            continue
+        # Must match {digit}-{digit}-*.md pattern
+        if not re.match(r"^\d+-\d+-", md_file.name):
+            continue
+        story = parse_bmad_story(md_file)
+        stories.append(story)
+
+    # Sort by epic number, then story number
+    def sort_key(s: dict) -> tuple[int, int]:
+        parts = s["id"].split("-")
+        return (int(parts[0]), int(parts[1]))
+
+    stories.sort(key=sort_key)
+    return stories
+
+
+def discover_bmad_epics(
+    source_root: Path,
+    epic_dir: str = "planning-artifacts/epics",
+) -> list[dict[str, Any]]:
+    """Scan BMAD planning-artifacts/epics/ and return parsed epics.
+
+    Args:
+        source_root: Path to _bmad-output/ (or equivalent)
+        epic_dir: Subdirectory path for epic files
+
+    Returns:
+        List of parsed epic dicts, sorted by epicNumber.
+    """
+    epics_dir = source_root / epic_dir
+    if not epics_dir.is_dir():
+        return []
+
+    epics: list[dict[str, Any]] = []
+    for md_file in sorted(epics_dir.glob("epic-*.md")):
+        # Skip index.md or non-epic files
+        if md_file.name == "index.md":
+            continue
+        epic = parse_bmad_epic(md_file)
+        if epic["epicNumber"] > 0:
+            epics.append(epic)
+
+    epics.sort(key=lambda e: e["epicNumber"])
+    return epics