empathy-framework 3.8.2__py3-none-any.whl → 3.9.0__py3-none-any.whl

empathy_os/cli.py

@@ -16,6 +16,7 @@ import argparse
 import sys
 import time
 from importlib.metadata import version as get_version
+from pathlib import Path
 
 from empathy_os import EmpathyConfig, EmpathyOS, load_config
 from empathy_os.cost_tracker import cmd_costs
@@ -37,9 +38,71 @@ from empathy_os.workflows import (
 )
 from empathy_os.workflows import list_workflows as get_workflow_list
 
+# Import telemetry CLI commands
+try:
+    from empathy_os.telemetry.cli import (
+        cmd_telemetry_compare,
+        cmd_telemetry_export,
+        cmd_telemetry_reset,
+        cmd_telemetry_savings,
+        cmd_telemetry_show,
+    )
+    TELEMETRY_CLI_AVAILABLE = True
+except ImportError:
+    TELEMETRY_CLI_AVAILABLE = False
+
 logger = get_logger(__name__)
 
 
+# =============================================================================
+# SECURITY UTILITIES
+# =============================================================================
+
+
+def _validate_file_path(path: str, allowed_dir: str | None = None) -> Path:
+    """Validate file path to prevent path traversal and arbitrary writes.
+
+    Args:
+        path: Path to validate
+        allowed_dir: Optional directory that must contain the path
+
+    Returns:
+        Resolved absolute Path object
+
+    Raises:
+        ValueError: If path is invalid or outside allowed directory
+
+    """
+    if not path or not isinstance(path, str):
+        raise ValueError("path must be a non-empty string")
+
+    # Check for null bytes
+    if "\x00" in path:
+        raise ValueError("path contains null bytes")
+
+    try:
+        # Resolve to absolute path
+        resolved = Path(path).resolve()
+    except (OSError, RuntimeError) as e:
+        raise ValueError(f"Invalid path: {e}")
+
+    # Check if within allowed directory
+    if allowed_dir:
+        try:
+            allowed = Path(allowed_dir).resolve()
+            resolved.relative_to(allowed)
+        except ValueError:
+            raise ValueError(f"path must be within {allowed_dir}")
+
+    # Check for dangerous system paths
+    dangerous_paths = ["/etc", "/sys", "/proc", "/dev"]
+    for dangerous in dangerous_paths:
+        if str(resolved).startswith(dangerous):
+            raise ValueError(f"Cannot write to system directory: {dangerous}")
+
+    return resolved
+
+
 # =============================================================================
 # CHEATSHEET DATA - Quick reference for all commands
 # =============================================================================
@@ -603,11 +666,114 @@ def cmd_achievements(args):
     print()
 
 
+def cmd_tier_recommend(args):
+    """Get intelligent tier recommendation for a bug/task."""
+    from empathy_os.tier_recommender import TierRecommender
+
+    recommender = TierRecommender()
+
+    # Get recommendation
+    result = recommender.recommend(
+        bug_description=args.description,
+        files_affected=args.files.split(",") if args.files else None,
+        complexity_hint=args.complexity
+    )
+
+    # Display results
+    print()
+    print("=" * 60)
+    print("  TIER RECOMMENDATION")
+    print("=" * 60)
+    print()
+    print(f"  Bug/Task: {args.description}")
+    print()
+    print(f"  📍 Recommended Tier: {result.tier}")
+    print(f"  🎯 Confidence: {result.confidence * 100:.1f}%")
+    print(f"  💰 Expected Cost: ${result.expected_cost:.3f}")
+    print(f"  🔄 Expected Attempts: {result.expected_attempts:.1f}")
+    print()
+    print(f"  📊 Reasoning:")
+    print(f"     {result.reasoning}")
+    print()
+
+    if result.similar_patterns_count > 0:
+        print(f"  ✅ Based on {result.similar_patterns_count} similar patterns")
+    else:
+        print(f"  ⚠️  No historical data - using conservative default")
+
+    if result.fallback_used:
+        print()
+        print("  💡 Tip: As more patterns are collected, recommendations")
+        print("     will become more accurate and personalized.")
+
+    print()
+    print("=" * 60)
+    print()
+
+
+def cmd_tier_stats(args):
+    """Show tier pattern learning statistics."""
+    from empathy_os.tier_recommender import TierRecommender
+
+    recommender = TierRecommender()
+    stats = recommender.get_stats()
+
+    print()
+    print("=" * 60)
+    print("  TIER PATTERN LEARNING STATS")
+    print("=" * 60)
+    print()
+
+    if stats.get("total_patterns", 0) == 0:
+        print("  No patterns collected yet.")
+        print()
+        print("  💡 Patterns are automatically collected as you use")
+        print("     cascading workflows with enhanced tracking enabled.")
+        print()
+        print("=" * 60)
+        print()
+        return
+
+    print(f"  Total Patterns: {stats['total_patterns']}")
+    print(f"  Avg Savings: {stats['avg_savings_percent']}%")
+    print()
+
+    print("  TIER DISTRIBUTION")
+    print("  " + "-" * 40)
+    for tier, count in stats["patterns_by_tier"].items():
+        percent = (count / stats["total_patterns"]) * 100
+        bar = "█" * int(percent / 5)
+        print(f"  {tier:10} {count:3} ({percent:5.1f}%) {bar}")
+    print()
+
+    print("  BUG TYPE DISTRIBUTION")
+    print("  " + "-" * 40)
+    sorted_types = sorted(
+        stats["bug_type_distribution"].items(),
+        key=lambda x: x[1],
+        reverse=True
+    )
+    for bug_type, count in sorted_types[:10]:
+        percent = (count / stats["total_patterns"]) * 100
+        print(f"  {bug_type:20} {count:3} ({percent:5.1f}%)")
+
+    print()
+    print("=" * 60)
+    print()
+
+
 def cmd_init(args):
-    """Initialize a new Empathy Framework project"""
+    """Initialize a new Empathy Framework project
+
+    Raises:
+        ValueError: If output path is invalid or unsafe
+    """
     config_format = args.format
     output_path = args.output or f"empathy.config.{config_format}"
 
+    # Validate output path to prevent path traversal attacks
+    validated_path = _validate_file_path(output_path)
+
     logger.info(f"Initializing new Empathy Framework project with format: {config_format}")
 
     # Create default config
@@ -615,13 +781,13 @@ def cmd_init(args):
 
     # Save to file
     if config_format == "yaml":
-        config.to_yaml(output_path)
+        config.to_yaml(str(validated_path))
         logger.info(f"Created YAML configuration file: {output_path}")
         logger.info(f"✓ Created YAML configuration: {output_path}")
     elif config_format == "json":
-        config.to_json(output_path)
-        logger.info(f"Created JSON configuration file: {output_path}")
-        logger.info(f"✓ Created JSON configuration: {output_path}")
+        config.to_json(str(validated_path))
+        logger.info(f"Created JSON configuration file: {validated_path}")
+        logger.info(f"✓ Created JSON configuration: {validated_path}")
 
     logger.info("\nNext steps:")
     logger.info(f"  1. Edit {output_path} to customize settings")
@@ -727,7 +893,11 @@ def cmd_patterns_list(args):
 
 
 def cmd_patterns_export(args):
-    """Export patterns from one format to another"""
+    """Export patterns from one format to another
+
+    Raises:
+        ValueError: If output path is invalid
+    """
     input_file = args.input
     input_format = args.input_format
     output_file = args.output
@@ -764,12 +934,15 @@ def cmd_patterns_export(args):
         logger.error(f"✗ Failed to load patterns: {e}")
         sys.exit(1)
 
+    # Validate output path
+    validated_output = _validate_file_path(output_file)
+
     # Save to output format
     try:
         if output_format == "json":
-            PatternPersistence.save_to_json(library, output_file)
+            PatternPersistence.save_to_json(library, str(validated_output))
         elif output_format == "sqlite":
-            PatternPersistence.save_to_sqlite(library, output_file)
+            PatternPersistence.save_to_sqlite(library, str(validated_output))
 
         logger.info(f"Saved {len(library.patterns)} patterns to {output_file}")
         logger.info(f"✓ Saved {len(library.patterns)} patterns to {output_file}")
@@ -1349,7 +1522,11 @@ def cmd_inspect(args):
 
 
 def cmd_export(args):
-    """Export patterns to file for sharing/backup"""
+    """Export patterns to file for sharing/backup
+
+    Raises:
+        ValueError: If output path is invalid
+    """
     output_file = args.output
     user_id = args.user_id
     db_path = args.db or ".empathy/patterns.db"
@@ -1373,6 +1550,9 @@ def cmd_export(args):
 
         print(f"  Found {len(patterns)} patterns")
 
+        # Validate output path
+        validated_output = _validate_file_path(output_file)
+
         if format_type == "json":
             # Create filtered library if user_id specified
             if user_id:
@@ -1383,7 +1563,7 @@ def cmd_export(args):
                 filtered_library = library
 
             # Export as JSON
-            PatternPersistence.save_to_json(filtered_library, output_file)
+            PatternPersistence.save_to_json(filtered_library, str(validated_output))
             print(f"  ✓ Exported {len(patterns)} patterns to {output_file}")
         else:
             print(f"✗ Unsupported format: {format_type}")
@@ -1682,12 +1862,18 @@ def cmd_provider_set(args):
 
 
 def cmd_sync_claude(args):
-    """Sync patterns to Claude Code rules directory."""
+    """Sync patterns to Claude Code rules directory.
+
+    Raises:
+        ValueError: If output path is invalid
+    """
     import json as json_mod
     from pathlib import Path
 
     patterns_dir = Path(args.patterns_dir)
-    output_dir = Path(args.output_dir)
+    # Validate output directory path
+    validated_output_dir = _validate_file_path(args.output_dir)
+    output_dir = validated_output_dir
 
     print("=" * 60)
     print("  SYNC PATTERNS TO CLAUDE CODE")
@@ -1723,7 +1909,9 @@ def cmd_sync_claude(args):
 
             # Write rule file
             rule_file = output_dir / f"{category}.md"
-            with open(rule_file, "w") as f:
+            # Validate rule file path before writing
+            validated_rule_file = _validate_file_path(str(rule_file), allowed_dir=str(output_dir))
+            with open(validated_rule_file, "w") as f:
                 f.write(rule_content)
 
             print(f"  ✓ {category}: {len(patterns)} patterns → {rule_file}")
@@ -2206,6 +2394,51 @@ def cmd_frameworks(args):
     return 0
 
 
+# =============================================================================
+# Telemetry CLI Command Wrappers
+# =============================================================================
+
+
+def _cmd_telemetry_show(args):
+    """Wrapper for telemetry show command."""
+    if not TELEMETRY_CLI_AVAILABLE:
+        print("Telemetry commands not available. Install telemetry dependencies.")
+        return 1
+    return cmd_telemetry_show(args)
+
+
+def _cmd_telemetry_savings(args):
+    """Wrapper for telemetry savings command."""
+    if not TELEMETRY_CLI_AVAILABLE:
+        print("Telemetry commands not available. Install telemetry dependencies.")
+        return 1
+    return cmd_telemetry_savings(args)
+
+
+def _cmd_telemetry_compare(args):
+    """Wrapper for telemetry compare command."""
+    if not TELEMETRY_CLI_AVAILABLE:
+        print("Telemetry commands not available. Install telemetry dependencies.")
+        return 1
+    return cmd_telemetry_compare(args)
+
+
+def _cmd_telemetry_reset(args):
+    """Wrapper for telemetry reset command."""
+    if not TELEMETRY_CLI_AVAILABLE:
+        print("Telemetry commands not available. Install telemetry dependencies.")
+        return 1
+    return cmd_telemetry_reset(args)
+
+
+def _cmd_telemetry_export(args):
+    """Wrapper for telemetry export command."""
+    if not TELEMETRY_CLI_AVAILABLE:
+        print("Telemetry commands not available. Install telemetry dependencies.")
+        return 1
+    return cmd_telemetry_export(args)
+
+
 def main():
     """Main CLI entry point"""
     # Configure Windows-compatible asyncio event loop policy
@@ -2607,6 +2840,98 @@ def main():
     parser_costs.add_argument("--json", action="store_true", help="Output as JSON")
     parser_costs.set_defaults(func=cmd_costs)
 
+    # Telemetry commands (usage tracking)
+    parser_telemetry = subparsers.add_parser(
+        "telemetry",
+        help="View and manage local usage telemetry",
+    )
+    telemetry_subparsers = parser_telemetry.add_subparsers(dest="telemetry_command")
+
+    # Telemetry show command
+    parser_telemetry_show = telemetry_subparsers.add_parser(
+        "show",
+        help="Show recent LLM calls",
+    )
+    parser_telemetry_show.add_argument(
+        "--limit",
+        type=int,
+        default=20,
+        help="Number of entries to show (default: 20)",
+    )
+    parser_telemetry_show.add_argument(
+        "--days",
+        type=int,
+        help="Only show entries from last N days",
+    )
+    parser_telemetry_show.set_defaults(func=lambda args: _cmd_telemetry_show(args))
+
+    # Telemetry savings command
+    parser_telemetry_savings = telemetry_subparsers.add_parser(
+        "savings",
+        help="Calculate cost savings vs baseline",
+    )
+    parser_telemetry_savings.add_argument(
+        "--days",
+        type=int,
+        default=30,
+        help="Number of days to analyze (default: 30)",
+    )
+    parser_telemetry_savings.set_defaults(func=lambda args: _cmd_telemetry_savings(args))
+
+    # Telemetry compare command
+    parser_telemetry_compare = telemetry_subparsers.add_parser(
+        "compare",
+        help="Compare two time periods",
+    )
+    parser_telemetry_compare.add_argument(
+        "--period1",
+        type=int,
+        default=7,
+        help="First period in days (default: 7)",
+    )
+    parser_telemetry_compare.add_argument(
+        "--period2",
+        type=int,
+        default=30,
+        help="Second period in days (default: 30)",
+    )
+    parser_telemetry_compare.set_defaults(func=lambda args: _cmd_telemetry_compare(args))
+
+    # Telemetry reset command
+    parser_telemetry_reset = telemetry_subparsers.add_parser(
+        "reset",
+        help="Clear all telemetry data",
+    )
+    parser_telemetry_reset.add_argument(
+        "--confirm",
+        action="store_true",
+        help="Confirm deletion",
+    )
+    parser_telemetry_reset.set_defaults(func=lambda args: _cmd_telemetry_reset(args))
+
+    # Telemetry export command
+    parser_telemetry_export = telemetry_subparsers.add_parser(
+        "export",
+        help="Export telemetry data",
+    )
+    parser_telemetry_export.add_argument(
+        "--format",
+        choices=["json", "csv"],
+        default="json",
+        help="Export format (default: json)",
+    )
+    parser_telemetry_export.add_argument(
+        "--output",
+        "-o",
+        help="Output file (default: stdout)",
+    )
+    parser_telemetry_export.add_argument(
+        "--days",
+        type=int,
+        help="Only export last N days",
+    )
+    parser_telemetry_export.set_defaults(func=lambda args: _cmd_telemetry_export(args))
+
     # New command (project scaffolding)
     parser_new = subparsers.add_parser("new", help="Create a new project from a template")
     parser_new.add_argument(
@@ -2771,6 +3096,40 @@ def main():
     )
     parser_achievements.set_defaults(func=cmd_achievements)
 
+    # Tier recommendation commands (cascading tier optimization)
+    parser_tier = subparsers.add_parser(
+        "tier",
+        help="Intelligent tier recommendations for cascading workflows",
+    )
+    tier_subparsers = parser_tier.add_subparsers(dest="tier_command")
+
+    # tier recommend
+    parser_tier_recommend = tier_subparsers.add_parser(
+        "recommend",
+        help="Get tier recommendation for a bug/task",
+    )
+    parser_tier_recommend.add_argument(
+        "description",
+        help="Description of the bug or task",
+    )
+    parser_tier_recommend.add_argument(
+        "--files",
+        help="Comma-separated list of affected files (optional)",
+    )
+    parser_tier_recommend.add_argument(
+        "--complexity",
+        type=int,
+        help="Manual complexity hint 1-10 (optional)",
+    )
+    parser_tier_recommend.set_defaults(func=cmd_tier_recommend)
+
+    # tier stats
+    parser_tier_stats = tier_subparsers.add_parser(
+        "stats",
+        help="Show tier pattern learning statistics",
+    )
+    parser_tier_stats.set_defaults(func=cmd_tier_stats)
+
     # Wizard Factory commands (create wizards 12x faster)
     add_wizard_factory_commands(subparsers)
 

empathy_os/cli_unified.py

@@ -513,6 +513,117 @@ def workflow_recommend(
     )
 
 
+# =============================================================================
+# TIER RECOMMENDATION SUBCOMMAND GROUP
+# =============================================================================
+
+tier_app = typer.Typer(help="Intelligent tier recommendations for cascading workflows")
+app.add_typer(tier_app, name="tier")
+
+
+@tier_app.command("recommend")
+def tier_recommend(
+    description: str = typer.Argument(..., help="Description of the bug or task"),
+    files: str = typer.Option(None, "--files", "-f", help="Comma-separated list of affected files"),
+    complexity: int = typer.Option(None, "--complexity", "-c", help="Manual complexity hint 1-10"),
+):
+    """Get intelligent tier recommendation for a bug/task."""
+    from empathy_os.tier_recommender import TierRecommender
+
+    recommender = TierRecommender()
+
+    # Get recommendation
+    result = recommender.recommend(
+        bug_description=description,
+        files_affected=files.split(",") if files else None,
+        complexity_hint=complexity,
+    )
+
+    # Display results
+    console.print()
+    console.print("=" * 60)
+    console.print("  [bold]TIER RECOMMENDATION[/bold]")
+    console.print("=" * 60)
+    console.print()
+    console.print(f"  [dim]Bug/Task:[/dim] {description}")
+    console.print()
+    console.print(f"  📍 [bold]Recommended Tier:[/bold] {result.tier}")
+    console.print(f"  🎯 [bold]Confidence:[/bold] {result.confidence * 100:.1f}%")
+    console.print(f"  💰 [bold]Expected Cost:[/bold] ${result.expected_cost:.3f}")
+    console.print(f"  🔄 [bold]Expected Attempts:[/bold] {result.expected_attempts:.1f}")
+    console.print()
+    console.print(f"  📊 [bold]Reasoning:[/bold]")
+    console.print(f"     {result.reasoning}")
+    console.print()
+
+    if result.fallback_used:
+        console.print("  ⚠️  [yellow]No historical data - using conservative default[/yellow]")
+        console.print()
+        console.print("  💡 [dim]Tip: As more patterns are collected, recommendations[/dim]")
+        console.print("     [dim]will become more accurate and personalized.[/dim]")
+    else:
+        console.print(f"  ✅ Based on {result.similar_patterns_count} similar patterns")
+
+    console.print()
+    console.print("=" * 60)
+    console.print()
+
+
+@tier_app.command("stats")
+def tier_stats():
+    """Show tier pattern learning statistics."""
+    from empathy_os.tier_recommender import TierRecommender
+
+    recommender = TierRecommender()
+    stats = recommender.get_stats()
+
+    if stats.get("total_patterns") == 0:
+        console.print()
+        console.print("  [yellow]No patterns loaded yet.[/yellow]")
+        console.print()
+        console.print("  💡 [dim]Patterns are collected automatically as you use")
+        console.print("     cascading workflows. Run a few workflows first.[/dim]")
+        console.print()
+        return
+
+    # Display statistics
+    console.print()
+    console.print("=" * 60)
+    console.print("  [bold]TIER PATTERN LEARNING STATS[/bold]")
+    console.print("=" * 60)
+    console.print()
+    console.print(f"  [bold]Total Patterns:[/bold] {stats['total_patterns']}")
+    console.print(f"  [bold]Avg Savings:[/bold] {stats['avg_savings_percent']}%")
+    console.print()
+    console.print("  [bold]TIER DISTRIBUTION[/bold]")
+    console.print("  " + "-" * 40)
+
+    tier_dist = stats["patterns_by_tier"]
+    total = stats["total_patterns"]
+    max_bar_width = 20
+
+    for tier in ["CHEAP", "CAPABLE", "PREMIUM"]:
+        count = tier_dist.get(tier, 0)
+        percent = (count / total * 100) if total > 0 else 0
+        bar_width = int(percent / 100 * max_bar_width)
+        bar = "█" * bar_width
+        console.print(f"  {tier:<12} {count:>2} ({percent:>5.1f}%) {bar}")
+
+    console.print()
+    console.print("  [bold]BUG TYPE DISTRIBUTION[/bold]")
+    console.print("  " + "-" * 40)
+
+    for bug_type, count in sorted(
+        stats["bug_type_distribution"].items(), key=lambda x: x[1], reverse=True
+    ):
+        percent = (count / total * 100) if total > 0 else 0
+        console.print(f"  {bug_type:<20} {count:>2} ({percent:>5.1f}%)")
+
+    console.print()
+    console.print("=" * 60)
+    console.print()
+
+
 # =============================================================================
 # UTILITY COMMANDS
 # =============================================================================

empathy_os/config/xml_config.py

@@ -18,6 +18,48 @@ from dataclasses import asdict, dataclass, field
 from pathlib import Path
 
 
+def _validate_file_path(path: str, allowed_dir: str | None = None) -> Path:
+    """Validate file path to prevent path traversal and arbitrary writes.
+
+    Args:
+        path: File path to validate
+        allowed_dir: Optional directory to restrict writes to
+
+    Returns:
+        Validated Path object
+
+    Raises:
+        ValueError: If path is invalid or unsafe
+    """
+    if not path or not isinstance(path, str):
+        raise ValueError("path must be a non-empty string")
+
+    # Check for null bytes
+    if "\x00" in path:
+        raise ValueError("path contains null bytes")
+
+    try:
+        resolved = Path(path).resolve()
+    except (OSError, RuntimeError) as e:
+        raise ValueError(f"Invalid path: {e}")
+
+    # Check if within allowed directory
+    if allowed_dir:
+        try:
+            allowed = Path(allowed_dir).resolve()
+            resolved.relative_to(allowed)
+        except ValueError:
+            raise ValueError(f"path must be within {allowed_dir}")
+
+    # Check for dangerous system paths
+    dangerous_paths = ["/etc", "/sys", "/proc", "/dev"]
+    for dangerous in dangerous_paths:
+        if str(resolved).startswith(dangerous):
+            raise ValueError(f"Cannot write to system directory: {dangerous}")
+
+    return resolved
+
+
 @dataclass
 class XMLConfig:
     """XML prompting configuration.
@@ -163,8 +205,8 @@ class EmpathyXMLConfig:
         Args:
             config_file: Path to save config (default: .empathy/config.json)
         """
-        path = Path(config_file)
-        path.parent.mkdir(parents=True, exist_ok=True)
+        validated_path = _validate_file_path(config_file)
+        validated_path.parent.mkdir(parents=True, exist_ok=True)
 
         data = {
             "xml": asdict(self.xml),
@@ -174,7 +216,7 @@ class EmpathyXMLConfig:
             "metrics": asdict(self.metrics),
         }
 
-        with open(path, "w") as f:
+        with open(validated_path, "w") as f:
             json.dump(data, f, indent=2)
 
     @classmethod