@pennyfarthing/core 10.0.2 → 10.0.5

package/pennyfarthing_scripts/cli.py

@@ -0,0 +1,184 @@
+"""
+Pennyfarthing CLI - Command line interface for agent orchestration.
+
+Usage:
+    python -m pennyfarthing_scripts.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 pennyfarthing_scripts 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
+    """
+    pass
+
+
+# Import and register sprint group (lazy registration preserves startup time)
+from pennyfarthing_scripts.sprint.cli import sprint
+
+cli.add_command(sprint)
+
+# Import and register hotspots group
+from pennyfarthing_scripts.hotspots.cli import hotspots
+
+cli.add_command(hotspots)
+
+# Import and register jira group
+from pennyfarthing_scripts.jira.cli import jira
+
+cli.add_command(jira)
+
+
+@cli.group()
+def agent():
+    """Agent session management.
+
+    \b
+    Commands:
+      start  - Start an agent session with context
+    """
+    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", "json_output", 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,
+    json_output: 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 pennyfarthing_scripts.prime import prime
+
+    exit_code = prime(
+        agent_name=name,
+        session_id=session_id,
+        no_persona=no_persona,
+        json_output=json_output,
+        minimal=minimal,
+        full=full,
+        quiet=quiet,
+        tier=tier,
+    )
+    raise SystemExit(exit_code)
+
+
+@cli.group()
+def workflow():
+    """Workflow state and phase management.
+
+    \b
+    Commands:
+      check       - Check current workflow state
+      phase-check - Verify phase ownership
+      handoff     - Emit handoff marker
+    """
+    pass
+
+
+@workflow.command("check")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+def workflow_check(output_json: bool):
+    """Check current workflow state.
+
+    Returns the current story ID, phase, and workflow state.
+    """
+    # Lazy import - only load when command is actually invoked
+    from pennyfarthing_scripts.workflow import get_workflow_state
+
+    state = get_workflow_state()
+
+    if output_json:
+        import json
+
+        click.echo(json.dumps(state, indent=2))
+    else:
+        click.echo(f"State: {state.get('state', 'unknown')}")
+        if state.get("story_id"):
+            click.echo(f"Story: {state['story_id']}")
+        if state.get("workflow"):
+            click.echo(f"Workflow: {state['workflow']}")
+        if state.get("phase"):
+            click.echo(f"Phase: {state['phase']}")
+
+
+@workflow.command("phase-check")
+@click.argument("workflow_name")
+@click.argument("phase")
+def workflow_phase_check(workflow_name: str, phase: str):
+    """Check which agent owns a workflow phase.
+
+    \b
+    Arguments:
+      WORKFLOW_NAME  - The workflow type (tdd, trivial, etc.)
+      PHASE          - The phase to check (red, implement, review, etc.)
+    """
+    # Lazy import
+    from pennyfarthing_scripts.workflow import get_phase_owner
+
+    owner = get_phase_owner(workflow_name, phase)
+    click.echo(owner)
+
+
+@workflow.command("handoff")
+@click.argument("next_agent")
+def workflow_handoff(next_agent: str):
+    """Emit a handoff marker for Cyclist.
+
+    \b
+    Arguments:
+      NEXT_AGENT  - The agent to hand off to (tea, dev, reviewer, etc.)
+    """
+    # Output the marker format expected by Cyclist
+    click.echo("---")
+    click.echo("AGENT_COMMAND:")
+    click.echo(f'  marker: "<!-- CYCLIST:HANDOFF:/{next_agent} -->"')
+    click.echo(f'  fallback: "Run `/{next_agent}` to continue"')
+    click.echo("---")
+
+
+def main():
+    """Entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing_scripts/common/__init__.py

@@ -0,0 +1,49 @@
+"""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 pennyfarthing_scripts.common.output import (
+    Colors,
+    bold,
+    debug,
+    dim,
+    divider,
+    error,
+    header,
+    info,
+    success,
+    warn,
+    _colorize,
+    _supports_color,
+)
+
+from pennyfarthing_scripts.common.config import (
+    find_project_root,
+    get_project_root,
+    load_pennyfarthing_config,
+    load_yaml_config,
+)
+
+__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_scripts/common/config.py

@@ -0,0 +1,92 @@
+"""
+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, "r") as f:
+        return yaml.safe_load(f)
+
+
+def load_pennyfarthing_config() -> dict[str, Any]:
+    """Load .pennyfarthing/config.local.yaml.
+
+    Returns:
+        Config dict, or empty dict if not found
+    """
+    config_path = get_project_root() / ".pennyfarthing" / "config.local.yaml"
+    return load_yaml_config(config_path) or {}

package/pennyfarthing_scripts/common/output.py

@@ -0,0 +1,180 @@
+"""
+Console output utilities for Pennyfarthing scripts.
+
+Provides consistent colored output for CLI tools:
+- success(): Green [OK] prefix
+- info(): Blue [INFO] prefix
+- warn(): Yellow [WARN] prefix
+- error(): Red [ERROR] prefix
+
+Consolidates output formatting from jira_sync.py and provides
+a consistent interface for all CLI scripts.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TextIO
+
+
+# ANSI color codes
+class Colors:
+    """ANSI escape codes for terminal colors."""
+
+    RED = "\x1b[31m"
+    GREEN = "\x1b[32m"
+    YELLOW = "\x1b[33m"
+    BLUE = "\x1b[34m"
+    MAGENTA = "\x1b[35m"
+    CYAN = "\x1b[36m"
+    BOLD = "\x1b[1m"
+    DIM = "\x1b[2m"
+    RESET = "\x1b[0m"
+
+
+def _supports_color(stream: TextIO) -> bool:
+    """Check if the output stream supports ANSI colors.
+
+    Args:
+        stream: Output stream to check
+
+    Returns:
+        True if colors are supported
+    """
+    # Check for NO_COLOR environment variable (standard)
+    if os.environ.get("NO_COLOR"):
+        return False
+
+    # Check for FORCE_COLOR environment variable
+    if os.environ.get("FORCE_COLOR"):
+        return True
+
+    # Check if stream is a TTY
+    if hasattr(stream, "isatty") and stream.isatty():
+        return True
+
+    return False
+
+
+def _colorize(text: str, color: str, stream: TextIO = sys.stderr) -> str:
+    """Apply color to text if supported.
+
+    Args:
+        text: Text to colorize
+        color: ANSI color code
+        stream: Output stream (for TTY detection)
+
+    Returns:
+        Colorized text or plain text if colors not supported
+    """
+    if _supports_color(stream):
+        return f"{color}{text}{Colors.RESET}"
+    return text
+
+
+def success(msg: str, file: TextIO = sys.stderr) -> None:
+    """Print success message with green [OK] prefix.
+
+    Args:
+        msg: Message to print
+        file: Output stream (default: stderr)
+    """
+    prefix = _colorize("[OK]", Colors.GREEN, file)
+    print(f"{prefix} {msg}", file=file)
+
+
+def info(msg: str, file: TextIO = sys.stderr) -> None:
+    """Print info message with blue [INFO] prefix.
+
+    Args:
+        msg: Message to print
+        file: Output stream (default: stderr)
+    """
+    prefix = _colorize("[INFO]", Colors.BLUE, file)
+    print(f"{prefix} {msg}", file=file)
+
+
+def warn(msg: str, file: TextIO = sys.stderr) -> None:
+    """Print warning message with yellow [WARN] prefix.
+
+    Args:
+        msg: Message to print
+        file: Output stream (default: stderr)
+    """
+    prefix = _colorize("[WARN]", Colors.YELLOW, file)
+    print(f"{prefix} {msg}", file=file)
+
+
+def error(msg: str, file: TextIO = sys.stderr) -> None:
+    """Print error message with red [ERROR] prefix.
+
+    Args:
+        msg: Message to print
+        file: Output stream (default: stderr)
+    """
+    prefix = _colorize("[ERROR]", Colors.RED, file)
+    print(f"{prefix} {msg}", file=file)
+
+
+def debug(msg: str, file: TextIO = sys.stderr) -> None:
+    """Print debug message with dim [DEBUG] prefix.
+
+    Args:
+        msg: Message to print
+        file: Output stream (default: stderr)
+    """
+    prefix = _colorize("[DEBUG]", Colors.DIM, file)
+    print(f"{prefix} {msg}", file=file)
+
+
+def header(msg: str, char: str = "=", width: int = 60, file: TextIO = sys.stderr) -> None:
+    """Print a header with decorative lines.
+
+    Args:
+        msg: Header text
+        char: Character for decoration line
+        width: Total width of the line
+        file: Output stream (default: stderr)
+    """
+    line = char * width
+    print(f"\n{line}", file=file)
+    print(msg, file=file)
+    print(line, file=file)
+
+
+def divider(char: str = "-", width: int = 40, file: TextIO = sys.stderr) -> None:
+    """Print a divider line.
+
+    Args:
+        char: Character for divider
+        width: Width of divider
+        file: Output stream (default: stderr)
+    """
+    print(char * width, file=file)
+
+
+def bold(text: str, stream: TextIO = sys.stdout) -> str:
+    """Return bold text if colors supported.
+
+    Args:
+        text: Text to make bold
+        stream: Output stream (for TTY detection)
+
+    Returns:
+        Bold text or plain text
+    """
+    return _colorize(text, Colors.BOLD, stream)
+
+
+def dim(text: str, stream: TextIO = sys.stdout) -> str:
+    """Return dimmed text if colors supported.
+
+    Args:
+        text: Text to dim
+        stream: Output stream (for TTY detection)
+
+    Returns:
+        Dimmed text or plain text
+    """
+    return _colorize(text, Colors.DIM, stream)