@pennyfarthing/core 7.8.1 → 7.8.4

package/pennyfarthing_scripts/tests/test_story_package.py

@@ -0,0 +1,156 @@
+"""Tests for story/ library package.
+
+Story 63-9: Reorganize pennyfarthing_scripts into fan-out CLI pattern.
+
+These tests verify the story/ package modules work correctly.
+"""
+
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+
+
+class TestStorySizeModule:
+    """Tests for story/size.py module."""
+
+    def test_get_sizing_guidelines_returns_dict(self) -> None:
+        """get_sizing_guidelines should return sizing info."""
+        from pennyfarthing_scripts.story.size import get_sizing_guidelines
+
+        result = get_sizing_guidelines()
+
+        assert isinstance(result, dict)
+        # Should have point values as keys
+        assert 1 in result or "1" in result or len(result) > 0
+
+    def test_get_sizing_guidelines_for_specific_points(self) -> None:
+        """get_sizing_guidelines should filter by points."""
+        from pennyfarthing_scripts.story.size import get_sizing_guidelines
+
+        result = get_sizing_guidelines(points=3)
+
+        assert isinstance(result, dict)
+
+    def test_format_size_info(self) -> None:
+        """format_size_info should return formatted string."""
+        from pennyfarthing_scripts.story.size import format_size_info
+
+        size_info = {
+            3: {
+                "scale": "Small",
+                "complexity": "Few files, some testing",
+                "examples": ["Validation", "single component"],
+            }
+        }
+        result = format_size_info(size_info)
+
+        assert isinstance(result, str)
+        assert "Small" in result or "3" in result
+
+
+class TestStoryTemplateModule:
+    """Tests for story/template.py module."""
+
+    def test_get_template_feature(self) -> None:
+        """get_template should return feature template."""
+        from pennyfarthing_scripts.story.template import get_template
+
+        result = get_template("feature")
+
+        assert isinstance(result, dict) or isinstance(result, str)
+        # Should have template content
+
+    def test_get_template_bug(self) -> None:
+        """get_template should return bug template."""
+        from pennyfarthing_scripts.story.template import get_template
+
+        result = get_template("bug")
+
+        assert isinstance(result, dict) or isinstance(result, str)
+
+    def test_get_template_unknown_returns_default(self) -> None:
+        """get_template should return default for unknown type."""
+        from pennyfarthing_scripts.story.template import get_template
+
+        result = get_template("unknown_type")
+
+        # Should return None or default template
+        assert result is None or isinstance(result, (dict, str))
+
+    def test_get_all_templates(self) -> None:
+        """get_all_templates should return all available templates."""
+        from pennyfarthing_scripts.story.template import get_all_templates
+
+        result = get_all_templates()
+
+        assert isinstance(result, dict)
+        # Should have standard types
+        assert "feature" in result or len(result) > 0
+
+
+class TestStoryCreateModule:
+    """Tests for story/create.py module."""
+
+    def test_generate_story_yaml(self) -> None:
+        """generate_story_yaml should create valid YAML block."""
+        from pennyfarthing_scripts.story.create import generate_story_yaml
+
+        result = generate_story_yaml(
+            epic_id="MSSCI-11952",
+            title="Add error handling",
+            points=3,
+            story_type="feature",
+        )
+
+        assert isinstance(result, str)
+        # Should contain key fields
+        assert "title" in result or "Add error handling" in result
+        assert "points" in result or "3" in result
+
+    def test_generate_story_yaml_with_options(self) -> None:
+        """generate_story_yaml should support optional parameters."""
+        from pennyfarthing_scripts.story.create import generate_story_yaml
+
+        result = generate_story_yaml(
+            epic_id="MSSCI-11952",
+            title="Bug fix",
+            points=2,
+            story_type="bug",
+            priority="P1",
+            workflow="tdd",
+        )
+
+        assert isinstance(result, str)
+        # Should contain type and priority
+        assert "bug" in result.lower() or "P1" in result
+
+    def test_create_story_validates_points(self) -> None:
+        """create_story should validate point values."""
+        from pennyfarthing_scripts.story.create import create_story
+
+        # Invalid points should fail or warn
+        result = create_story(
+            epic_id="MSSCI-11952",
+            title="Test",
+            points=100,  # Invalid - too high
+            dry_run=True,
+        )
+
+        assert isinstance(result, dict)
+        # May succeed with warning or fail
+        assert "success" in result or "error" in result or "warning" in result
+
+    def test_create_story_dry_run(self) -> None:
+        """create_story with dry_run should not modify files."""
+        from pennyfarthing_scripts.story.create import create_story
+
+        result = create_story(
+            epic_id="MSSCI-11952",
+            title="Test Story",
+            points=3,
+            dry_run=True,
+        )
+
+        assert isinstance(result, dict)
+        assert result.get("dry_run") is True

package/pennyfarthing_scripts/welcome_hook.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+Welcome Hook (Python)
+
+Display a friendly welcome message on session start.
+
+For CLI: Displays ASCII art of a penny-farthing bicycle
+For Cyclist: Sends WebSocket message to display logo and welcome
+
+Called by Claude Code SessionStart hook.
+
+Story: MSSCI-12409 - Hook consistency and WheelHub consolidation
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+
+from hooks import (
+    find_project_root,
+    send_to_cyclist,
+    load_settings,
+    is_cyclist_running,
+)
+
+
+# Once-per-session guard
+_welcome_shown_file: Path | None = None
+
+
+def get_welcome_lock_path(project_root: Path) -> Path:
+    """Get path to welcome shown lock file."""
+    session_id = os.environ.get("CLAUDE_SESSION_ID", str(os.getpid()))
+    session_dir = project_root / ".session"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    return session_dir / f".welcome-shown-{session_id}"
+
+
+def was_welcome_shown(project_root: Path) -> bool:
+    """Check if welcome was already shown for this session."""
+    lock_path = get_welcome_lock_path(project_root)
+    return lock_path.exists()
+
+
+def mark_welcome_shown(project_root: Path) -> None:
+    """Mark welcome as shown for this session."""
+    lock_path = get_welcome_lock_path(project_root)
+    lock_path.touch()
+
+
+def get_project_name(project_root: Path) -> str:
+    """Get project name from package.json or directory name."""
+    package_json = project_root / "package.json"
+    if package_json.exists():
+        try:
+            with open(package_json) as f:
+                data = json.load(f)
+                name = data.get("name")
+                if name:
+                    return name
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    return project_root.name
+
+
+def get_theme(project_root: Path) -> str | None:
+    """Get current theme from settings."""
+    settings = load_settings(project_root)
+    return settings.theme
+
+
+def display_cli_welcome(project_name: str, theme: str | None) -> None:
+    """Display ASCII art welcome for CLI mode."""
+    print("""
+       ___
+      /   \\
+     |     |     Welcome to
+     |     |    ╔═══════════════════════════════════╗
+      \\___/     ║   ╔═╗╔═╗╔╗╔╔╗╔╦═╗╔═╗╔═╗╔═╗╦╔═╗   ║
+        ║       ║   ╠═╝║╣ ║║║║║║ ╠╣ ╠═╣╠╦╝ ║ ╠═╣   ║
+        ║       ║   ╩  ╚═╝╝╚╝╝╚╝╩  ╩ ╩╩╚═ ╩ ╩ ╩   ║
+      ╔═╩═╗     ╚═══════════════════════════════════╝
+     /     \\
+    │   O   │   Agent-powered development with style
+     \\     /
+      ╚═══╝
+""")
+
+    if project_name:
+        print(f"    Project: {project_name}")
+    if theme:
+        print(f"    Theme:   {theme}")
+    print()
+
+
+def send_cyclist_welcome(project_root: Path, project_name: str, theme: str | None) -> None:
+    """Send welcome message to Cyclist via WebSocket API."""
+    try:
+        send_to_cyclist(
+            endpoint="/api/welcome",
+            data={
+                "project": project_name or "",
+                "theme": theme or "",
+            },
+            project_root=project_root,
+            timeout=5,
+        )
+    except Exception:
+        # Ignore errors - don't block hook
+        pass
+
+
+def main() -> None:
+    """Main entry point for SessionStart welcome hook."""
+    try:
+        # Read and discard stdin (required by hook protocol)
+        sys.stdin.read()
+
+        # Find project root
+        project_root = find_project_root()
+        if not project_root:
+            sys.exit(0)
+
+        # Check if welcome was already shown for this session
+        if was_welcome_shown(project_root):
+            sys.exit(0)
+
+        # Mark welcome as shown
+        mark_welcome_shown(project_root)
+
+        # Get project info
+        project_name = get_project_name(project_root)
+        theme = get_theme(project_root)
+
+        # Check if running in Cyclist
+        if is_cyclist_running(project_root):
+            # Send welcome via WebSocket API
+            send_cyclist_welcome(project_root, project_name, theme)
+        else:
+            # CLI mode - display ASCII art
+            display_cli_welcome(project_name, theme)
+
+        sys.exit(0)
+
+    except Exception as e:
+        # On error, exit silently
+        print(f"[welcome-hook] Error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing_scripts/workflow.py

@@ -0,0 +1,183 @@
+"""
+Scale level detection and workflow routing for Pennyfarthing.
+
+BMAD Scale Levels:
+- Level 0: fix, bug, typo, small change, patch (1 story, no artifacts)
+- Level 1: simple, basic, small feature, add (1-10 stories, tech-spec)
+- Level 2: dashboard, several features, admin panel (5-15 stories, PRD optional arch)
+- Level 3: platform, integration, complex, system (12-40 stories, PRD + architecture)
+- Level 4: enterprise, multi-tenant, multiple products (40+ stories, full BMAD)
+
+Story: MSSCI-12416 - Define Scale Levels
+Epic: MSSCI-12415 - Scale Adaptation and Brownfield Support
+"""
+
+from typing import Any
+import re
+
+# Scale level definitions with keywords, thresholds, and metadata
+SCALE_LEVELS: dict[int, dict[str, Any]] = {
+    0: {
+        "level": 0,
+        "scope": "fix, bug, typo, small change, patch",
+        "keywords": ["fix", "bug", "typo", "patch", "hotfix", "small change"],
+        "stories_min": 1,
+        "stories_max": 1,
+        "workflow": "trivial",
+        "artifacts": [],
+    },
+    1: {
+        "level": 1,
+        "scope": "simple, basic, small feature, add",
+        "keywords": ["simple", "basic", "small", "add", "minor"],
+        "stories_min": 1,
+        "stories_max": 10,
+        "workflow": "quick-spec",
+        "artifacts": ["tech-spec"],
+    },
+    2: {
+        "level": 2,
+        "scope": "dashboard, several features, admin panel",
+        "keywords": ["dashboard", "admin panel", "several", "multiple features"],
+        "stories_min": 5,
+        "stories_max": 15,
+        "workflow": "prd",
+        "artifacts": ["prd"],
+    },
+    3: {
+        "level": 3,
+        "scope": "platform, integration, complex, system",
+        "keywords": ["platform", "integration", "complex", "system"],
+        "stories_min": 12,
+        "stories_max": 40,
+        "workflow": "prd",
+        "artifacts": ["prd", "architecture"],
+    },
+    4: {
+        "level": 4,
+        "scope": "enterprise, multi-tenant, multiple products",
+        "keywords": ["enterprise", "multi-tenant", "multiple products"],
+        "stories_min": 40,
+        "stories_max": None,  # No upper limit
+        "workflow": "prd",
+        "artifacts": ["prd", "architecture", "epics-and-stories"],
+    },
+}
+
+
+def detect_scale_level(description: str) -> int:
+    """Detect scale level from description keywords.
+
+    Keywords are matched case-insensitively. When multiple levels match,
+    the highest level wins (higher specificity).
+
+    Args:
+        description: Text describing the work to be done
+
+    Returns:
+        Scale level 0-4, defaults to 1 if no keywords match
+    """
+    description_lower = description.lower()
+    matched_level = 1  # Default
+
+    # Check from highest to lowest level (highest specificity wins)
+    for level in [4, 3, 2, 1, 0]:
+        keywords = SCALE_LEVELS[level]["keywords"]
+        for keyword in keywords:
+            # Use word boundary matching for better accuracy
+            pattern = r"\b" + re.escape(keyword.lower()) + r"\b"
+            if re.search(pattern, description_lower):
+                # Higher levels have priority, so return immediately for L4-L2
+                if level >= 2:
+                    return level
+                # For L0-L1, track the match but continue checking for higher levels
+                matched_level = level
+
+    return matched_level
+
+
+def scale_level_from_story_count(count: int) -> int:
+    """Infer scale level from estimated story count.
+
+    Args:
+        count: Estimated number of stories
+
+    Returns:
+        Scale level 0-4 based on story count thresholds
+    """
+    if count <= 1:
+        return 1  # Could be 0 or 1, default to 1
+    elif count <= 10:
+        return 1
+    elif count <= 15:
+        return 2
+    elif count <= 40:
+        return 3
+    else:
+        return 4
+
+
+def get_workflow_for_scale_level(level: int) -> str:
+    """Get the recommended workflow for a scale level.
+
+    Args:
+        level: Scale level 0-4
+
+    Returns:
+        Workflow name (trivial, quick-spec, or prd)
+    """
+    if level not in SCALE_LEVELS:
+        return "prd"  # Safe default for unknown levels
+    return SCALE_LEVELS[level]["workflow"]
+
+
+def get_required_artifacts(level: int) -> list[str]:
+    """Get required planning artifacts for a scale level.
+
+    Args:
+        level: Scale level 0-4
+
+    Returns:
+        List of required artifact names
+    """
+    if level not in SCALE_LEVELS:
+        return []
+    return SCALE_LEVELS[level]["artifacts"]
+
+
+def determine_scale_level(
+    description: str, explicit_level: int | None = None
+) -> int:
+    """Determine scale level with optional user override.
+
+    Args:
+        description: Text describing the work to be done
+        explicit_level: User-specified level override (0-4)
+
+    Returns:
+        Scale level 0-4
+
+    Raises:
+        ValueError: If explicit_level is not 0-4
+    """
+    if explicit_level is not None:
+        if explicit_level < 0 or explicit_level > 4:
+            raise ValueError(f"Scale level must be 0-4, got {explicit_level}")
+        return explicit_level
+
+    return detect_scale_level(description)
+
+
+def get_scale_level_info(level: int) -> dict[str, Any]:
+    """Get complete metadata for a scale level.
+
+    Args:
+        level: Scale level 0-4
+
+    Returns:
+        Dict with level, scope, stories_min, stories_max, workflow, artifacts
+    """
+    if level not in SCALE_LEVELS:
+        return {"level": level, "scope": "unknown", "stories_min": 0,
+                "stories_max": 0, "workflow": "prd", "artifacts": []}
+    return SCALE_LEVELS[level].copy()