@pennyfarthing/core 11.4.0 → 12.0.0

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

@@ -0,0 +1,393 @@
+"""
+Pennyfarthing CLI - Command line interface for agent orchestration.
+
+Usage:
+    python -m pf.cli [OPTIONS] COMMAND [ARGS]...
+    pf [OPTIONS] COMMAND [ARGS]...
+
+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__
+
+
+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"),
+    "init":         ("pf.init.cli", "init"),
+    "prime":        ("pf.prime.cli", "prime_cmd"),
+    "upgrade":      ("pf.upgrade.cli", "upgrade"),
+    "docs":         ("pf.docs.cli", "docs"),
+    "doctor":       ("pf.doctor.cli", "doctor"),
+}
+
+
+# ---------------------------------------------------------------------------
+# 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.
+
+    Commands are organized into groups:
+
+    \b
+    workflow  - Workflow state and phase management
+    agent     - Agent session management
+    sprint    - Sprint status and story operations
+    git       - Repository operations (status, cleanup, branches, release)
+    session   - Session lifecycle (new, continue, parallel)
+    epic      - Epic lifecycle (start, close)
+    debug     - Analysis tools (hotspots, deadcode, healthscore)
+
+    \b
+    Shortcuts (sugar for common operations):
+      status   - Show sprint status (= sprint status)
+      backlog  - Show available stories (= sprint backlog)
+      work     - Start work on a story (= sprint work)
+      story    - Story operations (= sprint story)
+      gui      - Open BikeRack dashboard (= launch gui)
+      tui      - Launch terminal UI (= launch tui)
+    """
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Eagerly-defined groups (no heavy imports, just Click decorators)
+# ---------------------------------------------------------------------------
+
+_DEBUG_COMMANDS: dict[str, tuple[str, str]] = {
+    "hotspots":    ("pf.hotspots.cli", "hotspots"),
+    "deadcode":    ("pf.deadcode.cli", "deadcode"),
+    "healthscore": ("pf.healthscore.cli", "healthscore"),
+}
+
+
+@cli.group(cls=LazyGroup, lazy_commands=_DEBUG_COMMANDS)
+def debug():
+    """Debug and analysis tools.
+
+    \b
+    Subcommands:
+      hotspots     - Git history hotspot detection
+      deadcode     - Dead code detection tools
+      healthscore  - Composite codebase health score
+    """
+    pass
+
+
+@cli.group()
+def agent():
+    """Agent session management.
+
+    \b
+    Commands:
+      start    - Start an agent session with context
+      heatmap  - Visualize context distribution and attention
+    """
+    pass
+
+
+@agent.command("start")
+@click.argument("name")
+@click.option("--session-id", help="Use explicit session ID")
+@click.option("--no-persona", is_flag=True, help="Skip persona loading")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+@click.option("--minimal", is_flag=True, help="Skip all context (fastest)")
+@click.option("--full", is_flag=True, help="Include domain docs")
+@click.option("--quiet", is_flag=True, help="Suppress section headers")
+@click.option("--tier", type=click.Choice(["full", "refresh", "handoff", "minimal"], case_sensitive=False), help="Context tier level")
+def agent_start(
+    name: str,
+    session_id: str | None,
+    no_persona: bool,
+    output_json: bool,
+    minimal: bool,
+    full: bool,
+    quiet: bool,
+    tier: str | None,
+):
+    """Start an agent session with full context.
+
+    Loads agent definition, persona, behavior guide, sprint context,
+    session context, and sidecar memory.
+
+    \b
+    Arguments:
+      NAME  - Agent name (sm, tea, dev, reviewer, etc.)
+    """
+    # Lazy import - only load when command is actually invoked
+    from pf.prime import prime
+
+    exit_code = prime(
+        agent_name=name,
+        session_id=session_id,
+        no_persona=no_persona,
+        json_output=output_json,
+        minimal=minimal,
+        full=full,
+        quiet=quiet,
+        tier=tier,
+    )
+    raise SystemExit(exit_code)
+
+
+@agent.command("heatmap")
+@click.argument("name", required=False)
+@click.option("--all", "show_all", is_flag=True, help="Show summary across all primary agents")
+@click.option("--csv", "csv_output", is_flag=True, help="Output CSV for machine consumption")
+@click.option("--json", "json_output", is_flag=True, help="Output JSON")
+def agent_heatmap(
+    name: str | None,
+    show_all: bool,
+    csv_output: bool,
+    json_output: bool,
+):
+    """Visualize context distribution and attention for agent activation.
+
+    Shows a heat map of how tokens are distributed across sections of an
+    agent's activation context, with attention scores based on the
+    "Lost in the Middle" U-shaped attention model.
+
+    \b
+    Examples:
+      pf agent heatmap sm           # Detailed view for SM
+      pf agent heatmap --all        # Summary across all agents
+      pf agent heatmap dev --json   # JSON output for tooling
+    """
+    from pf.prime.heatmap import run_heatmap
+
+    exit_code = run_heatmap(
+        agent_name=name,
+        show_all=show_all,
+        csv_output=csv_output,
+        json_output=json_output,
+    )
+    raise SystemExit(exit_code)
+
+
+@cli.command("help")
+@click.argument("group", required=False)
+def help_cmd(group: str | None):
+    """Context-aware help for Pennyfarthing commands.
+
+    \b
+    Arguments:
+      GROUP  - Optional command group name (sprint, git, session, epic, jira, theme, workflow, etc.)
+    """
+
+    import yaml
+
+    from pf.common.config import get_dist_root, get_project_root
+
+    root = get_project_root()
+    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)
+        raise SystemExit(1)
+
+    registry = yaml.safe_load(registry_path.read_text())
+
+    if group is None:
+        # Show overview
+        click.echo("Pennyfarthing CLI — Command Reference")
+        click.echo("=" * 45)
+        click.echo("")
+        click.echo("Resource Groups:")
+        for name, grp in registry.get("groups", {}).items():
+            cli_cmd = grp.get("cli", "")
+            slash = grp.get("slash", "")
+            desc = grp.get("description", "")
+            parts = []
+            if slash:
+                parts.append(slash)
+            if cli_cmd:
+                parts.append(cli_cmd)
+            ref = ", ".join(parts)
+            click.echo(f"  {name:<12} {desc:<45} ({ref})")
+        click.echo("")
+        click.echo("Standalone:")
+        for name, cmd in registry.get("standalone", {}).items():
+            slash = cmd.get("slash", "")
+            desc = cmd.get("description", "")
+            click.echo(f"  {name:<12} {desc:<45} ({slash})")
+        click.echo("")
+        click.echo("Use 'pf help <group>' for detailed commands.")
+        return
+
+    # Show specific group
+    groups = registry.get("groups", {})
+    if group not in groups:
+        click.echo(f"Unknown group: {group}", err=True)
+        click.echo(f"Available groups: {', '.join(groups.keys())}", err=True)
+        raise SystemExit(1)
+
+    grp = groups[group]
+    click.echo(f"{group} — {grp.get('description', '')}")
+    click.echo("-" * 45)
+    if grp.get("cli"):
+        click.echo(f"CLI:   {grp['cli']}")
+    if grp.get("slash"):
+        click.echo(f"Slash: {grp['slash']}")
+    if grp.get("skill"):
+        click.echo(f"Skill: {grp['skill']}")
+    click.echo("")
+
+    commands = grp.get("commands", {})
+    if commands:
+        click.echo("Commands:")
+        for cmd_name, cmd in commands.items():
+            args = cmd.get("args", "")
+            desc = cmd.get("description", "")
+            if args:
+                click.echo(f"  {cmd_name} {args:<20} {desc}")
+            else:
+                click.echo(f"  {cmd_name:<25} {desc}")
+
+    subgroups = grp.get("subgroups", {})
+    for sg_name, sg in subgroups.items():
+        click.echo(f"\n  {sg_name} — {sg.get('description', '')}")
+        for cmd_name, cmd in sg.get("commands", {}).items():
+            args = cmd.get("args", "")
+            desc = cmd.get("description", "")
+            if args:
+                click.echo(f"    {cmd_name} {args:<18} {desc}")
+            else:
+                click.echo(f"    {cmd_name:<23} {desc}")
+
+
+def main():
+    """Entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,50 @@
+"""Common utilities for Pennyfarthing scripts.
+
+This package provides shared utilities used across all CLI tools:
+- output: Colored console output functions
+- config: Project configuration loading
+"""
+
+from pf.common.config import (
+    find_project_root,
+    get_dist_root,
+    get_project_root,
+    load_pennyfarthing_config,
+    load_yaml_config,
+)
+from pf.common.output import (
+    Colors,
+    _colorize,
+    _supports_color,
+    bold,
+    debug,
+    dim,
+    divider,
+    error,
+    header,
+    info,
+    success,
+    warn,
+)
+
+__all__ = [
+    # Output
+    "Colors",
+    "bold",
+    "debug",
+    "dim",
+    "divider",
+    "error",
+    "header",
+    "info",
+    "success",
+    "warn",
+    "_colorize",
+    "_supports_color",
+    # Config
+    "find_project_root",
+    "get_dist_root",
+    "get_project_root",
+    "load_pennyfarthing_config",
+    "load_yaml_config",
+]

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

@@ -0,0 +1,162 @@
+"""
+Configuration loading utilities for Pennyfarthing scripts.
+
+Provides YAML config loading with graceful degradation for missing files.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def get_project_root(start_dir: Path | None = None) -> Path:
+    """Find the Pennyfarthing project root.
+
+    Detection order:
+      1. Environment override (PROJECT_ROOT or CLAUDE_PROJECT_DIR)
+      2. Marker walk-up from start_dir/cwd
+
+    Marker preference: pennyfarthing-dist/ (non-symlink) before .pennyfarthing/.
+    This avoids confusion in nested repos where an orchestrator-level
+    .pennyfarthing/ exists above the framework's pennyfarthing-dist/.
+
+    Args:
+        start_dir: Directory to start search from (defaults to cwd)
+
+    Returns:
+        Path to project root directory
+
+    Raises:
+        FileNotFoundError: If no project root found
+    """
+    # Layer 1: Environment (caller already knows)
+    if env_root := os.environ.get("PROJECT_ROOT"):
+        return Path(env_root).resolve()
+    if env_root := os.environ.get("CLAUDE_PROJECT_DIR"):
+        return Path(env_root).resolve()
+
+    # Layer 2: Marker detection (pennyfarthing-dist first, then .pennyfarthing)
+    current = (Path(start_dir) if start_dir else Path.cwd()).resolve()
+
+    # First pass: prefer pennyfarthing-dist/ (framework repo)
+    # Must be a real directory, not a symlink (symlinks indicate consumer context)
+    check = current
+    while check != check.parent:
+        candidate = check / "pennyfarthing-dist"
+        if candidate.is_dir() and not candidate.is_symlink():
+            return check
+        check = check.parent
+
+    # Second pass: fall back to .pennyfarthing/ (consumer/orchestrator)
+    check = current
+    while check != check.parent:
+        if (check / ".pennyfarthing").is_dir():
+            return check
+        check = check.parent
+
+    raise FileNotFoundError(
+        "Could not find project root (no pennyfarthing-dist/ or .pennyfarthing/ directory found).\n"
+        "If this is a fresh clone, run: just setup"
+    )
+
+
+# Alias for backwards compatibility
+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/src/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/src/pf/common/config.py → up 4 levels
+        candidate = this_file.parent.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.
+
+    Args:
+        path: Path to the YAML file
+
+    Returns:
+        Parsed YAML as dict, or None if file doesn't exist
+    """
+    if not path.exists():
+        return None
+
+    with open(path) as f:
+        return yaml.safe_load(f)
+
+
+def load_pennyfarthing_config(project_root: Path | None = None) -> dict[str, Any]:
+    """Load .pennyfarthing/config.local.yaml.
+
+    Args:
+        project_root: Project root path (defaults to auto-detect)
+
+    Returns:
+        Config dict, or empty dict if not found
+    """
+    root = project_root or get_project_root()
+    config_path = root / ".pennyfarthing" / "config.local.yaml"
+    return load_yaml_config(config_path) or {}
+
+
+def save_pennyfarthing_config_key(
+    key: str, value: Any, project_root: Path | None = None
+) -> None:
+    """Set a top-level key in .pennyfarthing/config.local.yaml.
+
+    Creates the file if it doesn't exist. Preserves existing keys.
+
+    Args:
+        key: Top-level key (e.g., "sprint")
+        value: Value to set (dict, str, etc.)
+        project_root: Project root path (defaults to auto-detect)
+    """
+    root = project_root or get_project_root()
+    config_path = root / ".pennyfarthing" / "config.local.yaml"
+
+    config = load_yaml_config(config_path) or {}
+    config[key] = value
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "w") as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False)

package/pennyfarthing-dist/src/pf/common/hooks.py

@@ -0,0 +1,31 @@
+"""Shared hook constants for Pennyfarthing infrastructure.
+
+The 5 essential hooks required for a minimal Pennyfarthing installation.
+Used by both init (fresh project) and upgrade (npm-to-Python migration).
+"""
+
+from __future__ import annotations
+
+# The canonical hook definitions. Both init/core.py and upgrade/core.py
+# import from here instead of maintaining independent copies.
+INFRASTRUCTURE_HOOKS: dict = {
+    "SessionStart": [
+        {"hooks": [{"type": "command", "command": "pf hooks session-start"}]}
+    ],
+    "Stop": [
+        {"hooks": [{"type": "command", "command": "pf hooks session-stop"}]}
+    ],
+    "PreToolUse": [
+        {
+            "matcher": "Edit|Write",
+            "hooks": [{"type": "command", "command": "pf hooks pre-edit-check"}],
+        },
+        {
+            "matcher": "Edit|Write|Bash|Task",
+            "hooks": [{"type": "command", "command": "pf hooks context-warning"}],
+        },
+    ],
+    "PostToolUse": [
+        {"hooks": [{"type": "command", "command": "pf hooks bell-mode"}]}
+    ],
+}