@pennyfarthing/core 11.3.8 → 11.5.0-alpha.0

package/pennyfarthing-dist/pf/bmad/parser.py

@@ -14,7 +14,6 @@ from typing import Any
 
 import yaml
 
-
 # =============================================================================
 # Status Mapping
 # =============================================================================
@@ -61,7 +60,7 @@ _HEADER_PATTERNS: dict[str, re.Pattern[str]] = {
     "date": re.compile(r"^Date:\s*(.+)$", re.MULTILINE),
 }
 
-_TITLE_RE = re.compile(r"^#\s+Story\s+\d+\.\d+:\s*(.+)$", re.MULTILINE)
+_TITLE_RE = re.compile(r"^#\s+Story\s+\d+\.\d+(?:\.\d+)?:\s*(.+)$", re.MULTILINE)
 
 # AC block: everything between ## Acceptance Criteria and the next ## heading
 _AC_RE = re.compile(
@@ -88,10 +87,17 @@ def parse_bmad_story(path: Path) -> dict[str, Any]:
             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}"
+    # Consume all leading numeric segments as the ID
+    # e.g. "1-5-testing-framework" → "1-5", "2-8-1-claroty-plugin" → "2-8-1"
+    key_parts = story_key.split("-")
+    id_segments: list[str] = []
+    for seg in key_parts:
+        if seg.isdigit():
+            id_segments.append(seg)
+        else:
+            break
+    pf_id = "-".join(id_segments) if len(id_segments) >= 2 else "0-0"
+    epic_num = id_segments[0] if id_segments else "0"
 
     # Title from # heading
     title_match = _TITLE_RE.search(content)
@@ -194,10 +200,9 @@ def discover_bmad_stories(
         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]))
+    # Sort by epic number, then story number (supports variable-length IDs like 2-8-1)
+    def sort_key(s: dict) -> tuple[int, ...]:
+        return tuple(int(p) for p in s["id"].split("-"))
 
     stories.sort(key=sort_key)
     return stories

package/pennyfarthing-dist/pf/bmad/sync.py

@@ -18,9 +18,7 @@ from pf.bmad.parser import (
     map_bmad_to_pf,
     map_pf_to_bmad,
 )
-from pf.common.config import get_project_root, load_pennyfarthing_config
-from pf.common.output import error, info, success, warn
-
+from pf.common.config import load_pennyfarthing_config
 
 # =============================================================================
 # Data Classes

package/pennyfarthing-dist/pf/bmad/test_parser.py

@@ -2,14 +2,10 @@
 
 from __future__ import annotations
 
-import tempfile
 from pathlib import Path
 
-import pytest
-
 from pf.bmad.parser import (
     BMAD_TO_PF_STATUS,
-    PF_TO_BMAD_STATUS,
     discover_bmad_stories,
     map_bmad_to_pf,
     map_pf_to_bmad,

package/pennyfarthing-dist/pf/bmad/test_sync.py

@@ -4,8 +4,6 @@ from __future__ import annotations
 
 from pathlib import Path
 
-import pytest
-
 from pf.bmad.sync import (
     BmadSyncChange,
     BmadSyncPlan,
@@ -14,7 +12,6 @@ from pf.bmad.sync import (
     generate_sync_plan,
 )
 
-
 # =============================================================================
 # Fixtures
 # =============================================================================

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

@@ -2,7 +2,7 @@
 Brownfield CLI - Analyze existing codebases.
 
 Usage:
-    python -m pf.brownfield <subcommand> [args]
+    pf debug <subcommand> [args]
 
 Subcommands:
     scan        Scan codebase and generate documentation

package/pennyfarthing-dist/pf/cli.py

@@ -5,17 +5,143 @@ Usage:
     python -m pf.cli [OPTIONS] COMMAND [ARGS]...
     pf [OPTIONS] COMMAND [ARGS]...
 
-This module uses lazy loading to keep startup time under 200ms.
-Heavy imports (httpx, workflow modules) are deferred until needed.
+This module uses lazy loading to keep startup time under 100ms.
+Command groups are imported on demand — only the invoked command's
+module is loaded. The LazyGroup class defers all imports until
+Click resolves the command name.
 """
 
+from __future__ import annotations
+
+from importlib import import_module
+
 import click
 
 # Get version from package - this is a fast import
 from pf import __version__
 
 
-@click.group()
+class LazyGroup(click.Group):
+    """A Click group that lazily imports subcommands on first access.
+
+    Each entry in ``lazy_commands`` maps a command name to a tuple of
+    (module_path, attribute_name).  The module is only imported when
+    the command is actually invoked or listed.
+    """
+
+    def __init__(
+        self,
+        *args,
+        lazy_commands: dict[str, tuple[str, str]] | None = None,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        self._lazy_commands: dict[str, tuple[str, str]] = lazy_commands or {}
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        base = super().list_commands(ctx)
+        lazy = sorted(self._lazy_commands.keys())
+        return sorted(set(base + lazy))
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.BaseCommand | None:
+        # Check eagerly-registered commands first (inline groups like agent/debug)
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd
+
+        # Resolve lazy command
+        if cmd_name in self._lazy_commands:
+            module_path, attr_name = self._lazy_commands[cmd_name]
+            mod = import_module(module_path)
+            return getattr(mod, attr_name)
+
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Lazy command registry — maps command name → (module, attribute)
+# These modules are only imported when the user invokes the command.
+# ---------------------------------------------------------------------------
+_LAZY_COMMANDS: dict[str, tuple[str, str]] = {
+    "sprint":       ("pf.sprint.cli", "sprint"),
+    "jira":         ("pf.jira.cli", "jira"),
+    "bmad":         ("pf.bmad.cli", "bmad"),
+    "theme":        ("pf.theme.cli", "theme"),
+    "validate":     ("pf.validate.cli", "validate"),
+    "bikerack":     ("pf.bikerack.cli", "bikerack"),
+    "launch":       ("pf.launch.cli", "launch"),
+    "bc":           ("pf.bc.cli", "bc"),
+    "handoff":      ("pf.handoff.cli", "handoff"),
+    "git":          ("pf.git_group.cli", "git"),
+    "session":      ("pf.session.cli", "session"),
+    "epic":         ("pf.epic.cli", "epic"),
+    "consultation": ("pf.consultation.cli", "consultation"),
+    "hooks":        ("pf.hooks.cli", "hooks"),
+    "settings":     ("pf.settings.cli", "settings"),
+    "workflow":     ("pf.workflow.cli", "workflow"),
+    "release":      ("pf.release.cli", "release"),
+    "hotspots":     ("pf.hotspots.cli", "hotspots"),
+    "deadcode":     ("pf.deadcode.cli", "deadcode"),
+    "healthscore":  ("pf.healthscore.cli", "healthscore"),
+    "package":      ("pf.package.cli", "package"),
+}
+
+
+# ---------------------------------------------------------------------------
+# Sugar shortcuts — resolved lazily via get_command override
+# ---------------------------------------------------------------------------
+_SUGAR_SHORTCUTS: dict[str, tuple[str, str, str]] = {
+    # name → (parent_module, parent_attr, sub_command_name)
+    "status":  ("pf.sprint.cli", "sprint", "status"),
+    "backlog": ("pf.sprint.cli", "sprint", "backlog"),
+    "work":    ("pf.sprint.cli", "sprint", "work"),
+    "story":   ("pf.sprint.cli", "sprint", "story"),
+    "gui":     ("pf.launch.cli", "launch", "gui"),
+    "tui":     ("pf.launch.cli", "launch", "tui"),
+}
+
+# Hidden backward-compat aliases — these resolve via _LAZY_COMMANDS
+# but are excluded from help output
+_HIDDEN_ALIASES: set[str] = {"hotspots", "deadcode", "healthscore"}
+
+
+class PennyfarthingCLI(LazyGroup):
+    """Top-level CLI group with sugar shortcuts and hidden aliases."""
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        cmds = super().list_commands(ctx)
+        # Add visible sugar shortcuts, exclude hidden aliases
+        cmds.extend(_SUGAR_SHORTCUTS.keys())
+        return sorted(c for c in set(cmds) if c not in _HIDDEN_ALIASES)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.BaseCommand | None:
+        # Sugar shortcuts — resolve the sub-command from a lazy parent group
+        if cmd_name in _SUGAR_SHORTCUTS:
+            module_path, parent_attr, sub_name = _SUGAR_SHORTCUTS[cmd_name]
+            mod = import_module(module_path)
+            parent = getattr(mod, parent_attr)
+            return parent.commands[sub_name]
+
+        # Normal lazy/eager resolution (handles both regular commands
+        # and hidden aliases since both are in _LAZY_COMMANDS)
+        return super().get_command(ctx, cmd_name)
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Override to hide sugar shortcuts from main help listing."""
+        commands = []
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None or subcommand in _SUGAR_SHORTCUTS:
+                continue
+            help_text = cmd.get_short_help_str(limit=150)
+            commands.append((subcommand, help_text))
+
+        if commands:
+            with formatter.section("Commands"):
+                formatter.write_dl(commands)
+
+
+@click.group(cls=PennyfarthingCLI, lazy_commands=_LAZY_COMMANDS)
 @click.version_option(version=__version__, prog_name="pf")
 def cli():
     """Pennyfarthing CLI - Agent orchestration utilities.
@@ -43,24 +169,18 @@ def cli():
     pass
 
 
-# Import and register sprint group (lazy registration preserves startup time)
-from pf.sprint.cli import sprint  # noqa: E402
-
-cli.add_command(sprint)
+# ---------------------------------------------------------------------------
+# Eagerly-defined groups (no heavy imports, just Click decorators)
+# ---------------------------------------------------------------------------
 
-# Top-level sugar shortcuts for common sprint operations
-cli.add_command(sprint.commands["status"], "status")
-cli.add_command(sprint.commands["backlog"], "backlog")
-cli.add_command(sprint.commands["work"], "work")
-cli.add_command(sprint.commands["story"], "story")
+_DEBUG_COMMANDS: dict[str, tuple[str, str]] = {
+    "hotspots":    ("pf.hotspots.cli", "hotspots"),
+    "deadcode":    ("pf.deadcode.cli", "deadcode"),
+    "healthscore": ("pf.healthscore.cli", "healthscore"),
+}
 
-# Import analysis groups
-from pf.deadcode.cli import deadcode  # noqa: E402
-from pf.healthscore.cli import healthscore  # noqa: E402
-from pf.hotspots.cli import hotspots  # noqa: E402
 
-
-@cli.group()
+@cli.group(cls=LazyGroup, lazy_commands=_DEBUG_COMMANDS)
 def debug():
     """Debug and analysis tools.
 
@@ -73,91 +193,6 @@ def debug():
     pass
 
 
-debug.add_command(hotspots)
-debug.add_command(deadcode)
-debug.add_command(healthscore)
-
-# Hidden backward-compat aliases
-cli.add_command(hotspots, "hotspots")
-cli.commands["hotspots"].hidden = True
-cli.add_command(deadcode, "deadcode")
-cli.commands["deadcode"].hidden = True
-cli.add_command(healthscore, "healthscore")
-cli.commands["healthscore"].hidden = True
-
-# Import and register jira group
-from pf.jira.cli import jira  # noqa: E402
-
-cli.add_command(jira)
-
-# Import and register bmad group
-from pf.bmad.cli import bmad  # noqa: E402
-
-cli.add_command(bmad)
-
-# Import and register theme group
-from pf.theme.cli import theme  # noqa: E402
-
-cli.add_command(theme)
-
-# Import and register validate group
-from pf.validate.cli import validate  # noqa: E402
-
-cli.add_command(validate)
-
-# Import and register bikerack group
-from pf.bikerack.cli import bikerack  # noqa: E402
-
-cli.add_command(bikerack)
-
-# Import and register launch group + top-level sugar aliases
-from pf.launch.cli import launch  # noqa: E402
-
-cli.add_command(launch)
-cli.add_command(launch.commands["gui"], "gui")
-cli.add_command(launch.commands["tui"], "tui")
-
-# Import and register bc group
-from pf.bc.cli import bc  # noqa: E402
-
-cli.add_command(bc)
-
-# Import and register handoff group
-from pf.handoff.cli import handoff  # noqa: E402
-
-cli.add_command(handoff)
-
-# Import and register git group
-from pf.git_group.cli import git  # noqa: E402
-
-cli.add_command(git)
-
-# Import and register session group
-from pf.session.cli import session  # noqa: E402
-
-cli.add_command(session)
-
-# Import and register epic group
-from pf.epic.cli import epic  # noqa: E402
-
-cli.add_command(epic)
-
-# Import and register consultation group
-from pf.consultation.cli import consultation  # noqa: E402
-
-cli.add_command(consultation)
-
-# Import and register hooks group
-from pf.hooks.cli import hooks  # noqa: E402
-
-cli.add_command(hooks)
-
-# Import and register settings group
-from pf.settings.cli import settings  # noqa: E402
-
-cli.add_command(settings)
-
-
 @cli.group()
 def agent():
     """Agent session management.
@@ -248,12 +283,6 @@ def agent_heatmap(
     raise SystemExit(exit_code)
 
 
-# Import and register workflow group
-from pf.workflow.cli import workflow  # noqa: E402
-
-cli.add_command(workflow)
-
-
 @cli.command("help")
 @click.argument("group", required=False)
 def help_cmd(group: str | None):
@@ -266,10 +295,15 @@ def help_cmd(group: str | None):
 
     import yaml
 
-    from pf.common.config import get_project_root
+    from pf.common.config import get_dist_root, get_project_root
 
     root = get_project_root()
-    registry_path = root / "pennyfarthing-dist" / "command-registry.yaml"
+    dist_root = get_dist_root(project_root=root)
+    if dist_root is None:
+        click.echo("Command registry not found. Run /pf-health-check.", err=True)
+        raise SystemExit(1)
+
+    registry_path = dist_root / "command-registry.yaml"
 
     if not registry_path.is_file():
         click.echo("Command registry not found. Run /pf-health-check.", err=True)

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

@@ -7,6 +7,7 @@ This package provides shared utilities used across all CLI tools:
 
 from pf.common.config import (
     find_project_root,
+    get_dist_root,
     get_project_root,
     load_pennyfarthing_config,
     load_yaml_config,
@@ -42,6 +43,7 @@ __all__ = [
     "_supports_color",
     # Config
     "find_project_root",
+    "get_dist_root",
     "get_project_root",
     "load_pennyfarthing_config",
     "load_yaml_config",

package/pennyfarthing-dist/pf/common/config.py

@@ -66,6 +66,49 @@ def get_project_root(start_dir: Path | None = None) -> Path:
 find_project_root = get_project_root
 
 
+def get_dist_root(project_root: Path | None = None) -> Path | None:
+    """Resolve the pennyfarthing-dist directory.
+
+    Checks multiple locations to support both monorepo development
+    and npm-installed consumer projects:
+      1. {project_root}/pennyfarthing-dist/ (monorepo or symlink)
+      2. {project_root}/node_modules/@pennyfarthing/core/pennyfarthing-dist/ (npm)
+      3. Relative to this file (when running from within pennyfarthing-dist/pf/)
+
+    Args:
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Path to pennyfarthing-dist directory, or None if not found
+    """
+    try:
+        root = (project_root or get_project_root()).resolve()
+    except FileNotFoundError:
+        return None
+
+    # 1. Direct: monorepo layout or symlink at project root
+    direct = root / "pennyfarthing-dist"
+    if direct.is_dir():
+        return direct
+
+    # 2. npm-installed: node_modules/@pennyfarthing/core/pennyfarthing-dist/
+    npm = root / "node_modules" / "@pennyfarthing" / "core" / "pennyfarthing-dist"
+    if npm.is_dir():
+        return npm
+
+    # 3. Relative to this file (when inside pennyfarthing-dist/pf/)
+    # Only use this fallback when no explicit project_root was given,
+    # since an explicit root scopes the search to that directory.
+    if project_root is None:
+        this_file = Path(__file__).resolve()
+        # __file__ is pennyfarthing-dist/pf/common/config.py → up 3 levels
+        candidate = this_file.parent.parent.parent
+        if candidate.name == "pennyfarthing-dist" and candidate.is_dir():
+            return candidate
+
+    return None
+
+
 def load_yaml_config(path: Path) -> dict[str, Any] | None:
     """Load a YAML configuration file.
 

package/pennyfarthing-dist/pf/common/pr_config.py

@@ -1,8 +1,9 @@
 """PR mode configuration reader.
 
-Reads the pr_mode preference from .pennyfarthing/config.local.yaml.
+Reads the pr_mode and pr_merge preferences from .pennyfarthing/config.local.yaml.
 
-Values: draft | ready | none (default: draft)
+pr_mode values: draft | ready | none (default: draft)
+pr_merge values: auto | human (default: auto)
 """
 
 from __future__ import annotations
@@ -12,6 +13,9 @@ from pf.common.config import load_pennyfarthing_config
 VALID_PR_MODES = {"draft", "ready", "none"}
 DEFAULT_PR_MODE = "draft"
 
+VALID_PR_MERGE_MODES = {"auto", "human"}
+DEFAULT_PR_MERGE_MODE = "auto"
+
 
 def get_pr_mode() -> str:
     """Read pr_mode from pennyfarthing config.
@@ -34,5 +38,26 @@ def get_pr_mode() -> str:
     return mode
 
 
+def get_pr_merge_mode() -> str:
+    """Read pr_merge from pennyfarthing config.
+
+    Looks for workflow.pr_merge in .pennyfarthing/config.local.yaml.
+    Falls back to 'auto' if not set or invalid.
+
+    Returns:
+        One of: 'auto', 'human'
+    """
+    config = load_pennyfarthing_config()
+    workflow = config.get("workflow", {})
+    if not isinstance(workflow, dict):
+        return DEFAULT_PR_MERGE_MODE
+
+    mode = workflow.get("pr_merge", DEFAULT_PR_MERGE_MODE)
+    if mode not in VALID_PR_MERGE_MODES:
+        return DEFAULT_PR_MERGE_MODE
+
+    return mode
+
+
 if __name__ == "__main__":
     print(get_pr_mode())

package/pennyfarthing-dist/pf/common/themes.py

@@ -20,7 +20,7 @@ from typing import Any
 
 import yaml
 
-from pf.common.config import get_project_root, load_yaml_config
+from pf.common.config import get_dist_root, get_project_root, load_yaml_config
 
 
 def discover_all_theme_dirs(project_root: Path | None = None) -> list[Path]:
@@ -42,10 +42,12 @@ def discover_all_theme_dirs(project_root: Path | None = None) -> list[Path]:
     if symlink_themes.is_dir():
         dirs.append(symlink_themes)
 
-    # 1b. Core themes via pennyfarthing-dist (development)
-    dist_themes = root / "pennyfarthing-dist" / "personas" / "themes"
-    if dist_themes.is_dir() and dist_themes not in dirs:
-        dirs.append(dist_themes)
+    # 1b. Core themes via pennyfarthing-dist (development or npm)
+    dist_root = get_dist_root(project_root=root)
+    if dist_root:
+        dist_themes = dist_root / "personas" / "themes"
+        if dist_themes.is_dir() and dist_themes not in dirs:
+            dirs.append(dist_themes)
 
     # 2. Theme packages via node_modules
     nm_pf = root / "node_modules" / "@pennyfarthing"

package/pennyfarthing-dist/pf/context.py

@@ -177,7 +177,7 @@ def get_claude_project_path(project_dir: str | None = None) -> Path:
         os.environ.get("PROJECT_ROOT") or
         os.getcwd()
     )
-    path_with_dashes = project_dir.replace("/", "-")
+    path_with_dashes = project_dir.replace("/", "-").replace(".", "-")
     return Path.home() / ".claude" / "projects" / path_with_dashes