@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/pf/cli.py

@@ -1,354 +0,0 @@
-"""
-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 200ms.
-Heavy imports (httpx, workflow modules) are deferred until needed.
-"""
-
-import click
-
-# Get version from package - this is a fast import
-from pf import __version__
-
-
-@click.group()
-@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
-
-
-# Import and register sprint group (lazy registration preserves startup time)
-from pf.sprint.cli import sprint  # noqa: E402
-
-cli.add_command(sprint)
-
-# 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")
-
-# 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()
-def debug():
-    """Debug and analysis tools.
-
-    \b
-    Subcommands:
-      hotspots     - Git history hotspot detection
-      deadcode     - Dead code detection tools
-      healthscore  - Composite codebase health score
-    """
-    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.
-
-    \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)
-
-
-# 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):
-    """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_project_root
-
-    root = get_project_root()
-    registry_path = root / "pennyfarthing-dist" / "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/pf/common/__init__.py

@@ -1,48 +0,0 @@
-"""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_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_project_root",
-    "load_pennyfarthing_config",
-    "load_yaml_config",
-]

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

@@ -1,119 +0,0 @@
-"""
-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 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)