x-ipe 1.0.23__py3-none-any.whl → 1.0.25__py3-none-any.whl

x_ipe/services/terminal_service.py

@@ -13,6 +13,8 @@ from collections import deque
 from datetime import datetime
 from typing import Dict, Optional, Any, Callable
 
+from x_ipe.tracing import x_ipe_tracing
+
 
 # Constants for session management
 BUFFER_MAX_CHARS = 10240  # 10KB limit for output buffer
@@ -30,15 +32,18 @@ class OutputBuffer:
     def __init__(self, max_chars: int = BUFFER_MAX_CHARS):
         self._buffer: deque = deque(maxlen=max_chars)
     
+    @x_ipe_tracing()
     def append(self, data: str) -> None:
         """Append data character by character to maintain limit."""
         for char in data:
             self._buffer.append(char)
     
+    @x_ipe_tracing()
     def get_contents(self) -> str:
         """Get all buffered content as string."""
         return ''.join(self._buffer)
     
+    @x_ipe_tracing()
     def clear(self) -> None:
         """Clear the buffer."""
         self._buffer.clear()
@@ -68,6 +73,7 @@ class PersistentSession:
         self.created_at = datetime.now()
         self._lock = threading.Lock()
     
+    @x_ipe_tracing()
     def start_pty(self, rows: int = 24, cols: int = 80) -> None:
         """Start the underlying PTY process."""
         def buffered_emit(data: str) -> None:
@@ -80,6 +86,7 @@ class PersistentSession:
         self.pty_session = PTYSession(self.session_id, buffered_emit)
         self.pty_session.start(rows, cols)
     
+    @x_ipe_tracing()
     def attach(self, socket_sid: str, emit_callback: Callable[[str], None]) -> None:
         """Attach a WebSocket connection to this session."""
         with self._lock:
@@ -88,6 +95,7 @@ class PersistentSession:
             self.state = 'connected'
             self.disconnect_time = None
     
+    @x_ipe_tracing()
     def detach(self) -> None:
         """Detach WebSocket, keeping PTY alive for reconnection."""
         with self._lock:
@@ -96,20 +104,24 @@ class PersistentSession:
             self.state = 'disconnected'
             self.disconnect_time = datetime.now()
     
+    @x_ipe_tracing()
     def get_buffer(self) -> str:
         """Get buffered output for replay."""
         return self.output_buffer.get_contents()
     
+    @x_ipe_tracing()
     def write(self, data: str) -> None:
         """Write input to PTY."""
         if self.pty_session:
             self.pty_session.write(data)
     
+    @x_ipe_tracing()
     def resize(self, rows: int, cols: int) -> None:
         """Resize the PTY."""
         if self.pty_session:
             self.pty_session._set_size(rows, cols)
     
+    @x_ipe_tracing()
     def is_expired(self, timeout_seconds: int = SESSION_TIMEOUT) -> bool:
         """Check if session has expired (1hr after disconnect)."""
         if self.state == 'connected':
@@ -119,6 +131,7 @@ class PersistentSession:
         elapsed = datetime.now() - self.disconnect_time
         return elapsed.total_seconds() > timeout_seconds
     
+    @x_ipe_tracing()
     def close(self) -> None:
         """Close session and cleanup resources."""
         if self.pty_session:
@@ -139,6 +152,7 @@ class SessionManager:
         self._cleanup_timer: Optional[threading.Timer] = None
         self._running = False
     
+    @x_ipe_tracing()
     def create_session(self, emit_callback: Callable[[str], None],
                        rows: int = 24, cols: int = 80) -> str:
         """Create new persistent session, returns session_id."""
@@ -152,16 +166,19 @@ class SessionManager:
         
         return session_id
     
+    @x_ipe_tracing()
     def get_session(self, session_id: str) -> Optional[PersistentSession]:
         """Get session by ID."""
         with self._lock:
             return self.sessions.get(session_id)
     
+    @x_ipe_tracing()
     def has_session(self, session_id: str) -> bool:
         """Check if session exists."""
         with self._lock:
             return session_id in self.sessions
     
+    @x_ipe_tracing()
     def remove_session(self, session_id: str) -> None:
         """Remove and close a session."""
         with self._lock:
@@ -169,6 +186,7 @@ class SessionManager:
         if session:
             session.close()
     
+    @x_ipe_tracing()
     def cleanup_expired(self) -> int:
         """Remove expired sessions. Returns count removed."""
         expired_ids = []
@@ -182,11 +200,13 @@ class SessionManager:
         
         return len(expired_ids)
     
+    @x_ipe_tracing()
     def start_cleanup_task(self) -> None:
         """Start background cleanup task (every 5 minutes)."""
         self._running = True
         self._schedule_cleanup()
     
+    @x_ipe_tracing()
     def stop_cleanup_task(self) -> None:
         """Stop the cleanup task."""
         self._running = False
@@ -230,6 +250,7 @@ class PTYSession:
         self.rows = 24
         self.cols = 80
     
+    @x_ipe_tracing()
     def start(self, rows: int = 24, cols: int = 80) -> None:
         """Spawn PTY with shell and start output reader."""
         import pty
@@ -310,6 +331,7 @@ class PTYSession:
         except Exception:
             pass
     
+    @x_ipe_tracing()
     def write(self, data: str) -> None:
         """Write input to PTY."""
         if self.fd is not None:
@@ -328,6 +350,7 @@ class PTYSession:
             winsize = struct.pack('HHHH', self.rows, self.cols, 0, 0)
             fcntl.ioctl(self.fd, termios.TIOCSWINSZ, winsize)
     
+    @x_ipe_tracing()
     def close(self) -> None:
         """Terminate PTY session and cleanup."""
         import signal
@@ -351,6 +374,7 @@ class PTYSession:
                 pass
             self.pid = None
     
+    @x_ipe_tracing()
     def isalive(self) -> bool:
         """Check if the PTY process is still running."""
         return self._running and self.fd is not None

x_ipe/services/themes_service.py

@@ -10,6 +10,8 @@ import re
 from pathlib import Path
 from typing import Dict, List, Any, Optional
 
+from x_ipe.tracing import x_ipe_tracing
+
 
 THEMES_DIR = 'x-ipe-docs/themes'
 THEME_PREFIX = 'theme-'
@@ -45,6 +47,7 @@ class ThemesService:
         self.project_root = Path(project_root).resolve()
         self.themes_dir = self.project_root / THEMES_DIR
     
+    @x_ipe_tracing()
     def list_themes(self) -> List[Dict[str, Any]]:
         """
         List all valid themes with metadata.
@@ -92,6 +95,7 @@ class ThemesService:
         
         return themes
     
+    @x_ipe_tracing()
     def get_theme(self, name: str) -> Optional[Dict[str, Any]]:
         """
         Get detailed information about a specific theme.

x_ipe/services/tools_config_service.py

@@ -11,6 +11,8 @@ import copy
 from pathlib import Path
 from typing import Dict, Any
 
+from x_ipe.tracing import x_ipe_tracing
+
 
 CONFIG_DIR = 'x-ipe-docs/config'
 CONFIG_FILE = 'tools.json'
@@ -56,6 +58,7 @@ class ToolsConfigService:
         self.config_path = self.config_dir / CONFIG_FILE
         self.legacy_path = self.project_root / LEGACY_PATH
     
+    @x_ipe_tracing()
     def load(self) -> Dict[str, Any]:
         """
         Load config, migrating from legacy if needed.
@@ -76,6 +79,7 @@ class ToolsConfigService:
         
         return self._create_default()
     
+    @x_ipe_tracing()
     def save(self, config: Dict[str, Any]) -> bool:
         """
         Save config to file.

x_ipe/services/tracing_service.py

@@ -0,0 +1,333 @@
+"""
+FEATURE-023: Application Action Tracing - Core
+
+TracingService for managing tracing configuration and lifecycle.
+
+Provides high-level API for starting/stopping tracing, reading
+configuration from tools.json, and cleaning up old log files.
+"""
+from datetime import datetime, timedelta, timezone
+from typing import Dict, List, Any, Optional
+from pathlib import Path
+
+from x_ipe.services.tools_config_service import ToolsConfigService
+from x_ipe.tracing.writer import TraceLogWriter
+from x_ipe.tracing.parser import TraceLogParser
+from x_ipe.tracing import x_ipe_tracing
+
+
+class TracingService:
+    """
+    Service for managing tracing configuration and lifecycle.
+    
+    Integrates with tools.json for configuration persistence and
+    provides methods for controlling tracing state.
+    
+    Usage:
+        service = TracingService("/path/to/project")
+        
+        # Check status
+        config = service.get_config()
+        is_active = service.is_active()
+        
+        # Control tracing
+        service.start(duration_minutes=15)
+        service.stop()
+        
+        # List/cleanup logs
+        logs = service.list_logs()
+        deleted = service.cleanup_on_startup()
+    """
+    
+    def __init__(self, project_root: str):
+        """
+        Initialize TracingService.
+        
+        Args:
+            project_root: Path to the project root directory
+        """
+        self.project_root = Path(project_root)
+        self.tools_config = ToolsConfigService(str(project_root))
+    
+    @x_ipe_tracing()
+    def get_config(self) -> Dict[str, Any]:
+        """
+        Get current tracing configuration.
+        
+        Returns:
+            Dictionary with tracing settings:
+            - enabled: bool
+            - stop_at: str or None (ISO timestamp)
+            - log_path: str
+            - retention_hours: int
+            - ignored_apis: list
+        """
+        config = self.tools_config.load()
+        return {
+            "enabled": config.get("tracing_enabled", False),
+            "stop_at": config.get("tracing_stop_at"),
+            "log_path": config.get("tracing_log_path", "instance/traces/"),
+            "retention_hours": config.get("tracing_retention_hours", 24),
+            "ignored_apis": config.get("tracing_ignored_apis", [])
+        }
+    
+    @x_ipe_tracing()
+    def is_active(self) -> bool:
+        """
+        Check if tracing is currently active.
+        
+        Tracing is active if:
+        - tracing_enabled is True, OR
+        - tracing_stop_at is set and in the future
+        
+        Returns:
+            True if tracing should be performed
+        """
+        config = self.get_config()
+        
+        if config["enabled"]:
+            return True
+        
+        stop_at = config["stop_at"]
+        if stop_at:
+            try:
+                # Parse ISO timestamp - keep it timezone-aware
+                stop_time = datetime.fromisoformat(
+                    stop_at.replace("Z", "+00:00")
+                )
+                return datetime.now(timezone.utc) < stop_time
+            except (ValueError, AttributeError):
+                return False
+        
+        return False
+    
+    @x_ipe_tracing()
+    def start(self, duration_minutes: int) -> Dict[str, Any]:
+        """
+        Start tracing for specified duration.
+        
+        Args:
+            duration_minutes: Duration in minutes (must be 3, 15, or 30)
+            
+        Returns:
+            Dictionary with success status and stop_at timestamp
+            
+        Raises:
+            ValueError: If duration is not 3, 15, or 30
+        """
+        if duration_minutes not in [3, 15, 30]:
+            raise ValueError("Duration must be 3, 15, or 30 minutes")
+        
+        stop_at = datetime.now(timezone.utc) + timedelta(minutes=duration_minutes)
+        # Convert +00:00 to Z for consistent format
+        stop_at_str = stop_at.isoformat().replace("+00:00", "Z")
+        
+        config = self.tools_config.load()
+        config["tracing_stop_at"] = stop_at_str
+        self.tools_config.save(config)
+        
+        return {"success": True, "stop_at": stop_at_str}
+    
+    @x_ipe_tracing()
+    def stop(self) -> Dict[str, Any]:
+        """
+        Stop tracing immediately.
+        
+        Clears tracing_stop_at and sets tracing_enabled to False.
+        
+        Returns:
+            Dictionary with success status
+        """
+        config = self.tools_config.load()
+        config["tracing_stop_at"] = None
+        config["tracing_enabled"] = False
+        self.tools_config.save(config)
+        
+        return {"success": True}
+    
+    @x_ipe_tracing()
+    def update_ignored_apis(self, patterns: List[str]) -> None:
+        """
+        Update the list of ignored API patterns.
+        
+        Args:
+            patterns: List of API path patterns to ignore
+        """
+        config = self.tools_config.load()
+        config["tracing_ignored_apis"] = patterns
+        self.tools_config.save(config)
+    
+    @x_ipe_tracing()
+    def list_logs(self) -> List[Dict[str, Any]]:
+        """
+        List all trace log files.
+        
+        Returns:
+            List of log file metadata dictionaries:
+            - trace_id: str
+            - api: str (e.g., "GET /api/project/structure")
+            - filename: str
+            - size: int (bytes)
+            - timestamp: str (ISO format)
+        """
+        config = self.get_config()
+        log_path = self.project_root / config["log_path"]
+        
+        if not log_path.exists():
+            return []
+        
+        logs = []
+        for filepath in sorted(log_path.glob("*.log"), reverse=True):
+            try:
+                # Parse filename: {timestamp}-{api}-{trace_id}.log
+                # Example: 20260202-072505-get-api-project-structure-a649c048-3d73.log
+                stem = filepath.stem
+                
+                # Extract trace_id (last 2 UUID segments: xxxxxxxx-xxxx)
+                # Split and find the UUID pattern at the end
+                parts = stem.split("-")
+                if len(parts) >= 4:
+                    # Last 2 parts form the trace_id (e.g., "a649c048-3d73")
+                    trace_id = f"{parts[-2]}-{parts[-1]}"
+                    # First 2 parts are timestamp (YYYYMMDD-HHMMSS)
+                    # Middle parts are the API name
+                    api_parts = parts[2:-2]  # Skip timestamp and trace_id
+                    api_name = "-".join(api_parts) if api_parts else "unknown"
+                    # Convert api_name back to path format (e.g., "get-api-project-structure" -> "GET /api/project/structure")
+                    api = self._filename_to_api(api_name)
+                else:
+                    trace_id = stem
+                    api = "/unknown"
+                
+                stat = filepath.stat()
+                logs.append({
+                    "trace_id": trace_id,
+                    "api": api,
+                    "filename": filepath.name,
+                    "size": stat.st_size,
+                    "timestamp": datetime.fromtimestamp(stat.st_mtime).isoformat()
+                })
+            except OSError:
+                continue
+        
+        return logs
+    
+    def _filename_to_api(self, api_name: str) -> str:
+        """
+        Convert sanitized API filename component back to API format.
+        
+        Args:
+            api_name: Sanitized name (e.g., "get-api-project-structure")
+            
+        Returns:
+            API string (e.g., "GET /api/project/structure")
+        """
+        if not api_name or api_name == "unknown":
+            return "/unknown"
+        
+        # Split by first hyphen to get method
+        parts = api_name.split("-", 1)
+        if len(parts) < 2:
+            return f"/{api_name}"
+        
+        method = parts[0].upper()
+        path_part = parts[1]
+        
+        # Convert hyphens back to slashes for path
+        path = "/" + path_part.replace("-", "/")
+        
+        return f"{method} {path}"
+    
+    @x_ipe_tracing()
+    def cleanup_on_startup(self) -> int:
+        """
+        Clean up old log files on backend startup.
+        
+        Uses retention_hours from configuration to determine
+        which files to delete.
+        
+        Returns:
+            Number of files deleted
+        """
+        config = self.get_config()
+        log_path = self.project_root / config["log_path"]
+        
+        writer = TraceLogWriter(str(log_path))
+        deleted = writer.cleanup(config["retention_hours"])
+        
+        if deleted > 0:
+            print(f"[TRACING] Cleaned up {deleted} old trace log(s)")
+        
+        return deleted
+    
+    @x_ipe_tracing()
+    def delete_all_logs(self) -> int:
+        """
+        Delete all trace log files.
+        
+        Returns:
+            Number of files deleted
+        """
+        config = self.get_config()
+        log_path = self.project_root / config["log_path"]
+        
+        if not log_path.exists():
+            return 0
+        
+        deleted = 0
+        for filepath in log_path.glob("*.log"):
+            try:
+                filepath.unlink()
+                deleted += 1
+            except OSError:
+                continue
+        
+        return deleted
+    
+    @x_ipe_tracing()
+    def get_trace(self, trace_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get parsed trace data for visualization.
+        
+        Searches for a log file matching the trace_id (exact or partial)
+        and parses it into visualization-ready structure.
+        
+        Args:
+            trace_id: Full or partial trace ID to search for
+            
+        Returns:
+            Parsed trace data or None if not found:
+            {
+                "trace_id": str,
+                "api": str,
+                "timestamp": str,
+                "total_time_ms": int,
+                "status": str,
+                "nodes": [...],
+                "edges": [...]
+            }
+        """
+        config = self.get_config()
+        log_path = self.project_root / config["log_path"]
+        
+        if not log_path.exists():
+            return None
+        
+        # Search for matching file
+        matching_file = None
+        for filepath in log_path.glob("*.log"):
+            if trace_id in filepath.stem:
+                matching_file = filepath
+                break
+        
+        if not matching_file:
+            return None
+        
+        # Parse the file
+        parser = TraceLogParser()
+        result = parser.parse(matching_file)
+        
+        # Add filename for reference
+        result["filename"] = matching_file.name
+        
+        return result

x_ipe/services/uiux_feedback_service.py

@@ -4,8 +4,12 @@ FEATURE-022-D: UI/UX Feedback Service
 Handles saving feedback entries to the file system.
 """
 import base64
+import shutil
+import re
 from pathlib import Path
-from datetime import datetime
+from datetime import datetime, timedelta
+
+from x_ipe.tracing import x_ipe_tracing
 
 
 class UiuxFeedbackService:
@@ -15,6 +19,149 @@ class UiuxFeedbackService:
         self.project_root = Path(project_root)
         self.feedback_dir = self.project_root / 'x-ipe-docs' / 'uiux-feedback'
     
+    @x_ipe_tracing()
+    def list_feedback(self, days: int = 2) -> list:
+        """
+        List feedback entries from the last N days.
+        
+        Args:
+            days: Number of days to look back (default 2)
+        
+        Returns:
+            List of feedback entries sorted by date descending
+        """
+        entries = []
+        cutoff = datetime.now() - timedelta(days=days)
+        
+        if not self.feedback_dir.exists():
+            return entries
+        
+        for folder in self.feedback_dir.iterdir():
+            if not folder.is_dir():
+                continue
+            
+            # Check folder modification time
+            mtime = datetime.fromtimestamp(folder.stat().st_mtime)
+            if mtime < cutoff:
+                continue
+            
+            # Parse feedback.md to extract details
+            feedback_md = folder / 'feedback.md'
+            if not feedback_md.exists():
+                continue
+            
+            entry = self._parse_feedback_md(folder.name, feedback_md)
+            if entry:
+                entry['mtime'] = mtime
+                entries.append(entry)
+        
+        # Sort by date descending (newest first)
+        entries.sort(key=lambda x: x['mtime'], reverse=True)
+        
+        # Remove mtime from output (internal use only)
+        for entry in entries:
+            del entry['mtime']
+        
+        return entries
+    
+    def _parse_feedback_md(self, folder_name: str, feedback_md: Path) -> dict:
+        """
+        Parse feedback.md file to extract entry details.
+        
+        Args:
+            folder_name: Name of the feedback folder
+            feedback_md: Path to feedback.md file
+        
+        Returns:
+            Dict with id, name, url, description, date
+        """
+        try:
+            content = feedback_md.read_text(encoding='utf-8')
+            
+            # Extract URL
+            url_match = re.search(r'\*\*URL:\*\*\s*(.+)', content)
+            url = url_match.group(1).strip() if url_match else ''
+            
+            # Extract date
+            date_match = re.search(r'\*\*Date:\*\*\s*(.+)', content)
+            date = date_match.group(1).strip() if date_match else ''
+            
+            # Extract description (between ## Feedback and ## Screenshot or end)
+            desc_match = re.search(r'## Feedback\s*\n\n(.+?)(?=\n## Screenshot|\Z)', content, re.DOTALL)
+            description = desc_match.group(1).strip() if desc_match else ''
+            if description == '_No description provided_':
+                description = ''
+            
+            return {
+                'id': folder_name,
+                'name': folder_name,
+                'url': url,
+                'description': description,
+                'date': date
+            }
+        except Exception:
+            return None
+    
+    @x_ipe_tracing()
+    def delete_feedback(self, feedback_id: str) -> dict:
+        """
+        Delete a feedback folder by ID.
+        
+        Args:
+            feedback_id: The feedback folder name/ID
+        
+        Returns:
+            dict with success (or error on failure)
+        """
+        try:
+            folder_path = self.feedback_dir / feedback_id
+            
+            if not folder_path.exists():
+                return {'success': False, 'error': 'Feedback not found'}
+            
+            if not folder_path.is_dir():
+                return {'success': False, 'error': 'Invalid feedback ID'}
+            
+            # Delete the folder
+            shutil.rmtree(folder_path)
+            
+            return {'success': True}
+        except Exception as e:
+            return {'success': False, 'error': str(e)}
+    
+    @x_ipe_tracing()
+    def cleanup_old_feedback(self, days: int = 7) -> int:
+        """
+        Delete feedback folders older than N days.
+        
+        Args:
+            days: Retention period in days (default 7)
+        
+        Returns:
+            Number of folders deleted
+        """
+        deleted = 0
+        cutoff = datetime.now() - timedelta(days=days)
+        
+        if not self.feedback_dir.exists():
+            return deleted
+        
+        for folder in list(self.feedback_dir.iterdir()):
+            if not folder.is_dir():
+                continue
+            
+            # Check folder modification time
+            mtime = datetime.fromtimestamp(folder.stat().st_mtime)
+            if mtime < cutoff:
+                try:
+                    shutil.rmtree(folder)
+                    deleted += 1
+                except Exception:
+                    pass
+        
+        return deleted
+    
+    @x_ipe_tracing()
     def save_feedback(self, data: dict) -> dict:
         """
         Save feedback entry to file system.