portacode 0.3.20.dev0__tar.gz → 0.3.20.dev2__tar.gz

{portacode-0.3.20.dev0 → portacode-0.3.20.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: portacode
-Version: 0.3.20.dev0
+Version: 0.3.20.dev2
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-0.3.20.dev0 → portacode-0.3.20.dev2}/portacode/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.3.20.dev0'
-__version_tuple__ = version_tuple = (0, 3, 20, 'dev0')
+__version__ = version = '0.3.20.dev2'
+__version_tuple__ = version_tuple = (0, 3, 20, 'dev2')

portacode-0.3.20.dev2/portacode/connection/handlers/project_state/README.md

@@ -0,0 +1,312 @@
+# Project State Management - Modular Architecture
+
+This document explains the modular architecture of the project state management system, which was refactored from a single 3000+ line file into a well-organized, maintainable structure.
+
+## Overview
+
+The project state management system handles:
+- File system monitoring and change detection
+- Git repository integration and operations  
+- Tab management (file tabs, diff tabs, etc.)
+- Real-time project state synchronization
+- Client session management
+
+## Architecture
+
+The original monolithic `project_state_handlers.py` file has been broken down into the following modules:
+
+```
+project_state/
+├── __init__.py           # Public API exports
+├── models.py             # Data structures and models
+├── git_manager.py        # Git operations and repository management
+├── file_system_watcher.py # File system change monitoring
+├── manager.py            # Central project state coordinator
+├── handlers.py           # Request handlers for various operations
+├── utils.py              # Utility functions and helpers
+└── README.md             # This documentation
+```
+
+## Module Details
+
+### 1. `models.py` - Data Structures
+
+Contains all the dataclasses and models used throughout the system:
+
+- **`ProjectState`**: Complete state of a project (files, git status, tabs, etc.)
+- **`FileItem`**: Represents a file or directory with metadata
+- **`TabInfo`**: Represents an editor tab with content and metadata
+- **`MonitoredFolder`**: Represents a folder being monitored for changes
+- **`GitFileChange`**: Represents a single file change in git
+- **`GitDetailedStatus`**: Detailed git status with file hashes
+
+**Key Features:**
+- All models are dataclasses for easy serialization
+- Comprehensive typing throughout
+- Self-documenting field definitions
+
+### 2. `git_manager.py` - Git Operations
+
+Handles all Git-related functionality:
+
+**Core Responsibilities:**
+- Repository detection and initialization
+- File status tracking (staged, modified, untracked, etc.)
+- Diff generation with syntax highlighting
+- Content retrieval at different git references
+- Git commands (stage, unstage, revert)
+
+**Key Features:**
+- Graceful fallback when GitPython is not available
+- Performance optimizations for large files
+- HTML diff generation with syntax highlighting
+- Support for diff-match-patch algorithm
+- Cross-platform path handling
+
+**Performance Safeguards:**
+- Timeouts for diff generation
+- Size limits for large files
+- Batch syntax highlighting for better performance
+- Simplified diff view for very large files
+
+### 3. `file_system_watcher.py` - File System Monitoring
+
+Monitors file system changes using the watchdog library:
+
+**Core Responsibilities:**
+- Cross-platform file system monitoring
+- Event filtering and debouncing
+- Git repository change detection
+- Thread-safe async event handling
+
+**Key Features:**
+- Selective monitoring of relevant file changes
+- Special handling for .git directory changes
+- Debug tracing for troubleshooting
+- Graceful fallback when watchdog is not available
+
+**Event Filtering:**
+- Skips temporary and debug files
+- Focuses on meaningful file changes
+- Monitors git-specific files for status updates
+
+### 4. `manager.py` - Central Coordinator
+
+The main `ProjectStateManager` class that orchestrates all operations:
+
+**Core Responsibilities:**
+- Project state initialization and lifecycle
+- Folder expansion/collapse logic
+- Tab management (open, close, activate)
+- File system change processing
+- Client session management
+- State synchronization and updates
+
+**Key Features:**
+- Singleton pattern for global state management
+- Debounced file change processing
+- Flattened item structure for performance
+- Detailed debug logging and state tracking
+- Client session isolation
+
+**State Management:**
+- Each client session has independent project state
+- Monitored folders with expansion states
+- Real-time synchronization with clients
+- Orphaned state cleanup
+
+### 5. `handlers.py` - Request Handlers
+
+AsyncHandler classes for different operations:
+
+**Handler Classes:**
+- `ProjectStateFolderExpandHandler` - Expand folders
+- `ProjectStateFolderCollapseHandler` - Collapse folders  
+- `ProjectStateFileOpenHandler` - Open files in tabs
+- `ProjectStateTabCloseHandler` - Close tabs
+- `ProjectStateSetActiveTabHandler` - Set active tab
+- `ProjectStateDiffOpenHandler` - Open diff tabs
+- `ProjectStateGitStageHandler` - Stage files
+- `ProjectStateGitUnstageHandler` - Unstage files
+- `ProjectStateGitRevertHandler` - Revert files
+
+**Key Features:**
+- Consistent error handling and validation
+- Server/client session mapping
+- Automatic state updates after operations
+- Comprehensive logging
+
+### 6. `utils.py` - Utility Functions
+
+Shared utility functions:
+
+- **`generate_tab_key()`**: Creates unique keys for different tab types
+- Support for file tabs, diff tabs, untitled tabs
+- Handles git reference parameters for diff tabs
+
+## Preserved Functionality
+
+All functionality from the original file has been preserved:
+
+✅ **Complete Feature Parity**
+- All classes, methods, and functions maintained
+- Original behavior preserved exactly
+- All logging statements preserved
+- All documentation comments maintained
+
+✅ **Performance Optimizations**
+- Large file handling safeguards
+- Diff generation timeouts
+- Syntax highlighting optimizations
+- Memory-efficient processing
+
+✅ **Error Handling**
+- Graceful fallbacks for missing dependencies
+- Cross-platform compatibility
+- Comprehensive exception handling
+- Debug mode support
+
+✅ **Git Integration**
+- Full GitPython integration
+- Advanced diff capabilities
+- Multi-reference comparisons
+- HTML diff generation
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+# Import the main components
+from project_state import (
+    get_or_create_project_state_manager,
+    ProjectState,
+    GitManager
+)
+
+# Get the global project state manager
+manager = get_or_create_project_state_manager(context, control_channel)
+
+# Initialize a project
+project_state = await manager.initialize_project_state(
+    client_session_id="session123",
+    project_folder_path="/path/to/project"
+)
+```
+
+### Using Individual Components
+
+```python
+# Use GitManager independently
+from project_state import GitManager
+
+git_manager = GitManager("/path/to/project")
+if git_manager.is_git_repo:
+    status = git_manager.get_detailed_status()
+    print(f"Branch: {git_manager.get_branch_name()}")
+```
+
+### Handler Integration
+
+```python
+# Import handlers for request processing
+from project_state import ProjectStateFolderExpandHandler
+
+# Use in your handler registry
+handler = ProjectStateFolderExpandHandler()
+result = await handler.execute(message)
+```
+
+## Migration Guide
+
+The refactoring maintains complete backward compatibility:
+
+1. **Existing imports continue to work** - The original module structure is preserved
+2. **No API changes** - All function signatures remain the same
+3. **Same behavior** - All functionality works exactly as before
+4. **Performance improvements** - Better organization enables easier optimization
+
+## Benefits of Modular Architecture
+
+### 1. **Maintainability**
+- Single responsibility principle
+- Easier to locate and modify specific functionality
+- Reduced cognitive load when working on specific features
+
+### 2. **Testability**
+- Individual modules can be tested in isolation
+- Clear dependencies between components
+- Easier mocking for unit tests
+
+### 3. **Reusability**
+- Components can be used independently
+- GitManager can be used outside project state context
+- Models can be shared across different systems
+
+### 4. **Performance**
+- Better import optimization
+- Reduced memory footprint for unused components
+- Clearer performance bottleneck identification
+
+### 5. **Documentation**
+- Self-documenting module structure
+- Clear separation of concerns
+- Easier onboarding for new developers
+
+## Development Guidelines
+
+### Adding New Features
+
+1. **Identify the appropriate module** based on the feature's responsibility
+2. **Follow existing patterns** for consistency
+3. **Update the `__init__.py`** to export new public APIs
+4. **Add comprehensive logging** for debugging
+5. **Include performance safeguards** for resource-intensive operations
+
+### Modifying Existing Features
+
+1. **Maintain backward compatibility** unless breaking changes are explicitly approved
+2. **Preserve all logging statements** for debugging continuity
+3. **Update documentation** to reflect changes
+4. **Test across all affected modules** to ensure integration works
+
+### Best Practices
+
+- Use type hints consistently
+- Follow the established logging patterns
+- Include docstrings for all public methods
+- Handle errors gracefully with appropriate fallbacks
+- Consider performance implications of changes
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Import Errors**: Ensure you're importing from the correct module path
+2. **Missing Dependencies**: Check for optional dependencies (GitPython, watchdog, etc.)
+3. **Performance Issues**: Review file size limits and timeout settings
+4. **State Synchronization**: Check client session mapping and event handling
+
+### Debug Mode
+
+Enable debug mode for detailed state tracking:
+
+```python
+manager.set_debug_mode(True, "/path/to/debug.json")
+```
+
+This creates a JSON file with complete project state information for analysis.
+
+## Future Enhancements
+
+The modular architecture enables several future improvements:
+
+1. **Plugin System**: Easy addition of new file system watchers or git providers
+2. **Caching Layer**: Independent caching modules for performance
+3. **API Versioning**: Separate handler versions for backward compatibility
+4. **Microservice Architecture**: Components can be extracted to separate services
+5. **Enhanced Testing**: Module-specific test suites with better coverage
+
+## Conclusion
+
+The modular architecture maintains all functionality while providing a solid foundation for future development. The separation of concerns makes the codebase more maintainable, testable, and extensible, while preserving the robust feature set that was built in the original implementation.

{portacode-0.3.20.dev0 → portacode-0.3.20.dev2}/portacode/connection/handlers/project_state/git_manager.py

@@ -1075,9 +1075,26 @@ class GitManager:
             # Convert to relative path from repo root
             rel_path = os.path.relpath(file_path, self.repo.working_dir)
             
-            # Reset the file from HEAD (unstage)
-            self.repo.git.restore('--staged', rel_path)
-            logger.info("Successfully unstaged file: %s", rel_path)
+            # Check if repository has any commits (HEAD exists)
+            has_commits = False
+            try:
+                # Try to get HEAD commit to check if repository has commits
+                self.repo.head.commit
+                has_commits = True
+            except Exception:
+                logger.debug("Repository has no commits yet (no HEAD)")
+                has_commits = False
+            
+            if has_commits:
+                # Repository has commits - use git restore --staged
+                self.repo.git.restore('--staged', rel_path)
+                logger.info("Successfully unstaged file using restore: %s", rel_path)
+            else:
+                # Repository has no commits - use git rm --cached
+                # This handles the case where files are staged but no initial commit exists
+                self.repo.git.rm('--cached', rel_path)
+                logger.info("Successfully unstaged file using rm --cached (no HEAD): %s", rel_path)
+            
             return True
             
         except Exception as e:

{portacode-0.3.20.dev0 → portacode-0.3.20.dev2}/portacode/connection/handlers/project_state/handlers.py

@@ -395,6 +395,13 @@ class ProjectStateGitStageHandler(AsyncHandler):
             project_state = manager.projects[source_client_session]
             project_state.git_status_summary = git_manager.get_status_summary()
             project_state.git_detailed_status = git_manager.get_detailed_status()
+            
+            # Force clear the last signature to ensure update is sent
+            # This is necessary because git operations should always trigger client updates
+            if hasattr(project_state, '_last_sent_signature'):
+                logger.info("Forcing git stage update by clearing signature cache")
+                project_state._last_sent_signature = None
+            
             await manager._send_project_state_update(project_state, server_project_id)
         
         return {
@@ -444,6 +451,13 @@ class ProjectStateGitUnstageHandler(AsyncHandler):
             project_state = manager.projects[source_client_session]
             project_state.git_status_summary = git_manager.get_status_summary()
             project_state.git_detailed_status = git_manager.get_detailed_status()
+            
+            # Force clear the last signature to ensure update is sent
+            # This is necessary because git operations should always trigger client updates
+            if hasattr(project_state, '_last_sent_signature'):
+                logger.info("Forcing git unstage update by clearing signature cache")
+                project_state._last_sent_signature = None
+            
             await manager._send_project_state_update(project_state, server_project_id)
         
         return {
@@ -493,6 +507,13 @@ class ProjectStateGitRevertHandler(AsyncHandler):
             project_state = manager.projects[source_client_session]
             project_state.git_status_summary = git_manager.get_status_summary()
             project_state.git_detailed_status = git_manager.get_detailed_status()
+            
+            # Force clear the last signature to ensure update is sent
+            # This is necessary because git operations should always trigger client updates
+            if hasattr(project_state, '_last_sent_signature'):
+                logger.info("Forcing git revert update by clearing signature cache")
+                project_state._last_sent_signature = None
+            
             await manager._send_project_state_update(project_state, server_project_id)
         
         return {

{portacode-0.3.20.dev0 → portacode-0.3.20.dev2}/portacode/connection/handlers/project_state/manager.py

@@ -413,8 +413,23 @@ class ProjectStateManager:
         # Update the monitored folder to expanded state
         monitored_folder = self._find_monitored_folder(project_state, folder_path)
         if not monitored_folder:
-            logger.error("Monitored folder not found for path: %s", folder_path)
-            return False
+            logger.warning("Monitored folder not found for path: %s. Attempting to add it...", folder_path)
+            
+            # Check if the folder exists and is within the project
+            if not os.path.exists(folder_path) or not os.path.isdir(folder_path):
+                logger.error("Cannot expand folder - path does not exist or is not a directory: %s", folder_path)
+                return False
+            
+            # Check if it's within the project root
+            if not folder_path.startswith(project_state.project_folder_path):
+                logger.error("Cannot expand folder - path is outside project root: %s", folder_path)
+                return False
+            
+            # Add the folder to monitored_folders
+            logger.info("Adding missing folder to monitored_folders: %s", folder_path)
+            new_monitored = MonitoredFolder(folder_path=folder_path, is_expanded=False)
+            project_state.monitored_folders.append(new_monitored)
+            monitored_folder = new_monitored
         
         logger.info("Found monitored folder: %s, current is_expanded: %s", monitored_folder.folder_path, monitored_folder.is_expanded)
         monitored_folder.is_expanded = True
@@ -809,7 +824,11 @@ class ProjectStateManager:
         else:
             logger.info("🔍 [TRACE] ❌ No git manager found for session: %s", client_session_id)
         
-        # Sync all dependent state (items, watchdog) - no automatic directory detection
+        # Detect and add new directories created in expanded folders to monitored_folders
+        logger.info("🔍 [TRACE] Detecting new directories in expanded folders...")
+        await self._detect_and_add_new_directories(project_state)
+        
+        # Sync all dependent state (items, watchdog)
         logger.info("🔍 [TRACE] Syncing all state with monitored folders...")
         await self._sync_all_state_with_monitored_folders(project_state)
         
@@ -818,13 +837,46 @@ class ProjectStateManager:
         await self._send_project_state_update(project_state)
     
     async def _detect_and_add_new_directories(self, project_state: ProjectState):
-        """Detect new directories in monitored folders and add them to monitoring."""
-        # For each currently monitored folder, check if new subdirectories appeared
-        monitored_folder_paths = [mf.folder_path for mf in project_state.monitored_folders]
+        """Detect new directories in expanded monitored folders and add them to monitoring."""
+        logger.info("🔍 [TRACE] _detect_and_add_new_directories called")
+        
+        # Get currently expanded monitored folders
+        expanded_monitored_folders = [mf for mf in project_state.monitored_folders if mf.is_expanded]
+        logger.info("🔍 [TRACE] Found %d expanded monitored folders", len(expanded_monitored_folders))
         
-        for folder_path in monitored_folder_paths:
-            if os.path.exists(folder_path) and os.path.isdir(folder_path):
-                await self._add_subdirectories_to_monitored(project_state, folder_path)
+        existing_monitored_paths = {mf.folder_path for mf in project_state.monitored_folders}
+        new_folders_added = False
+        
+        for monitored_folder in expanded_monitored_folders:
+            folder_path = monitored_folder.folder_path
+            logger.info("🔍 [TRACE] Scanning expanded folder for new directories: %s", folder_path)
+            
+            if not os.path.exists(folder_path) or not os.path.isdir(folder_path):
+                logger.warning("🔍 [TRACE] Expanded folder no longer exists: %s", folder_path)
+                continue
+            
+            try:
+                with os.scandir(folder_path) as entries:
+                    for entry in entries:
+                        if entry.is_dir() and entry.name != '.git':
+                            if entry.path not in existing_monitored_paths:
+                                logger.info("🔍 [TRACE] ✅ Found new directory to monitor: %s", entry.path)
+                                # Add new directory as collapsed and loaded
+                                new_monitored = MonitoredFolder(folder_path=entry.path, is_expanded=False)
+                                project_state.monitored_folders.append(new_monitored)
+                                existing_monitored_paths.add(entry.path)
+                                new_folders_added = True
+                                logger.info("🔍 [TRACE] Added new directory to monitored_folders: %s", entry.path)
+                            else:
+                                logger.debug("🔍 [TRACE] Directory already monitored: %s", entry.path)
+            
+            except (OSError, PermissionError) as e:
+                logger.error("🔍 [TRACE] Error scanning expanded folder %s: %s", folder_path, e)
+        
+        if new_folders_added:
+            logger.info("🔍 [TRACE] ✅ New directories were added to monitoring")
+        else:
+            logger.debug("🔍 [TRACE] No new directories found to add")
     
     async def _reload_visible_structures(self, project_state: ProjectState):
         """Reload all visible structures with flattened items."""
@@ -835,10 +887,24 @@ class ProjectStateManager:
         logger.info("🔍 [TRACE] _send_project_state_update called for session: %s", project_state.client_session_id)
         
         # Create state signature for change detection
+        # Include detailed git file information to ensure staging/unstaging triggers updates
+        git_detailed_signature = None
+        if project_state.git_detailed_status:
+            # Create a more detailed signature that captures individual file staging states
+            staged_files = tuple(sorted([(f.file_abs_path, f.change_type) for f in project_state.git_detailed_status.staged_changes]))
+            unstaged_files = tuple(sorted([(f.file_abs_path, f.change_type) for f in project_state.git_detailed_status.unstaged_changes]))
+            untracked_files = tuple(sorted([f.file_abs_path for f in project_state.git_detailed_status.untracked_files]))
+            git_detailed_signature = {
+                "head_commit_hash": project_state.git_detailed_status.head_commit_hash,
+                "staged_files": staged_files,
+                "unstaged_files": unstaged_files,
+                "untracked_files": untracked_files
+            }
+        
         current_state_signature = {
             "git_branch": project_state.git_branch,
             "git_status_summary": project_state.git_status_summary,
-            "git_detailed_status": str(project_state.git_detailed_status) if project_state.git_detailed_status else None,
+            "git_detailed_status": git_detailed_signature,
             "open_tabs": tuple((tab.tab_id, tab.tab_type, tab.title) for tab in project_state.open_tabs.values()),
             "active_tab": project_state.active_tab.tab_id if project_state.active_tab else None,
             "items_count": len(project_state.items),

{portacode-0.3.20.dev0 → portacode-0.3.20.dev2}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: portacode
-Version: 0.3.20.dev0
+Version: 0.3.20.dev2
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-0.3.20.dev0 → portacode-0.3.20.dev2}/portacode.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ portacode/connection/handlers/session.py
 portacode/connection/handlers/system_handlers.py
 portacode/connection/handlers/tab_factory.py
 portacode/connection/handlers/terminal_handlers.py
+portacode/connection/handlers/project_state/README.md
 portacode/connection/handlers/project_state/__init__.py
 portacode/connection/handlers/project_state/file_system_watcher.py
 portacode/connection/handlers/project_state/git_manager.py