@hybridlabor-api/aos 4.3.0 → 4.4.1

package/mcps/windows-computer-use-mcp/docs/_stale/development/archive/SYSTEMATIC_PROJECT_UPDATES.md

@@ -1,532 +0,0 @@
-> **Archived fleet import** — From **notepadpp-mcp** / generic fleet dev notes. **Not** pywinauto-mcp source of truth. See [DEVELOPMENT.md](../../DEVELOPMENT.md) and [TESTING.md](../../TESTING.md).
-# 🔄 Systematic Project-Wide Updates with AI
-
-**The Challenge of Comprehensive Changes**  
-**Based on Real FastMCP 2.12 Migration Experience**  
-**Timeline**: September 2025
-
----
-
-## 🎯 The Problem: AI Can't "Catch Them All"
-
-### **What We Need vs. What AI Can Do**
-
-**What Developers Need**:
-- ✅ **Check ALL files** for import issues in one pass
-- ✅ **Update ALL tools** with correct decorators systematically  
-- ✅ **Fix ALL type hints** across the entire project
-- ✅ **Validate ALL functions** follow the same pattern
-- ✅ **Comprehensive project-wide consistency**
-
-**What AI Actually Does**:
-- ❌ **Processes 3-5 files** then "forgets" about the rest
-- ❌ **Focuses on examples** rather than comprehensive coverage
-- ❌ **Misses edge cases** in files not explicitly mentioned
-- ❌ **Inconsistent application** of patterns across files
-- ❌ **Requires multiple requests** to "catch them all"
-
-### **Real Example from Our FastMCP Migration**
-
-**The Task**: Update all tools from old pattern to FastMCP 2.12 pattern
-
-**What We Needed**:
-```
-tools/
-├── device_status.py     ← Update 3 tools
-├── device_control.py    ← Update 5 tools  
-├── system_status.py     ← Update 3 tools
-├── auth_tools.py        ← Update 3 tools
-├── config_tools.py      ← Update 5 tools
-├── help_tool.py         ← Update 3 tools
-└── about_tool.py        ← Update 2 tools
-Total: 24 tools across 7 files
-```
-
-**What Happened with AI**:
-- 🔄 **Request 1**: Fixed device_status.py and device_control.py
-- 🔄 **Request 2**: Fixed auth_tools.py and config_tools.py  
-- 🔄 **Request 3**: Fixed help_tool.py (but missed some functions)
-- 🔄 **Request 4**: Fixed remaining functions in help_tool.py
-- 🔄 **Request 5**: Fixed system_status.py
-- 🔄 **Request 6**: Finally got around to about_tool.py
-
-**Result**: Required **6 separate requests** to accomplish what should have been one systematic update.
-
----
-
-## 🛠️ Systematic Approach for Comprehensive Updates
-
-### **Phase 1: Project Inventory and Planning**
-
-#### **Step 1: Create Complete File List**
-```bash
-# Get comprehensive view of what needs updating
-find src/ -name "*.py" -type f | grep -E "(tools|server)" | sort
-
-# Example output:
-src/nest_protect_mcp/tools/__init__.py
-src/nest_protect_mcp/tools/auth_tools.py
-src/nest_protect_mcp/tools/config_tools.py
-src/nest_protect_mcp/tools/device_control.py
-src/nest_protect_mcp/tools/device_status.py
-src/nest_protect_mcp/tools/help_tool.py
-src/nest_protect_mcp/tools/system_status.py
-src/nest_protect_mcp/fastmcp_server.py
-src/nest_protect_mcp/server.py
-```
-
-#### **Step 2: Analyze Current Patterns**
-```bash
-# Find all decorator patterns
-grep -r "@" src/nest_protect_mcp/tools/ --include="*.py"
-
-# Find all import patterns  
-grep -r "from.*import" src/nest_protect_mcp/tools/ --include="*.py"
-
-# Find all function definitions
-grep -r "def " src/nest_protect_mcp/tools/ --include="*.py"
-```
-
-#### **Step 3: Create Systematic Checklist**
-
-**Template Checklist**:
-```markdown
-## Import Fixes Needed
-- [ ] src/nest_protect_mcp/tools/device_status.py
-- [ ] src/nest_protect_mcp/tools/device_control.py  
-- [ ] src/nest_protect_mcp/tools/system_status.py
-- [ ] src/nest_protect_mcp/tools/auth_tools.py
-- [ ] src/nest_protect_mcp/tools/config_tools.py
-- [ ] src/nest_protect_mcp/tools/help_tool.py
-- [ ] src/nest_protect_mcp/tools/about_tool.py
-
-## Decorator Updates Needed  
-- [ ] device_status.py: list_devices, get_device_status, get_device_events
-- [ ] device_control.py: hush_alarm, run_safety_check, set_led_brightness, sound_alarm, arm_disarm_security
-- [ ] system_status.py: get_system_status, get_process_status, get_api_status  
-- [ ] auth_tools.py: initiate_oauth_flow, handle_oauth_callback, refresh_access_token
-- [ ] config_tools.py: get_config, update_config, reset_config, export_config, import_config
-- [ ] help_tool.py: list_available_tools, get_tool_help, search_tools
-- [ ] about_tool.py: about_server, get_supported_devices
-
-Total: 24 functions across 7 files
-```
-
-### **Phase 2: Batched AI Requests Strategy**
-
-#### **Request Template for Systematic Updates**
-
-**Request Format**:
-```
-I need to systematically update [X] files for [specific change]. 
-
-FILES TO UPDATE (in this batch):
-1. src/nest_protect_mcp/tools/device_status.py
-2. src/nest_protect_mcp/tools/device_control.py
-3. src/nest_protect_mcp/tools/system_status.py
-
-SPECIFIC CHANGES NEEDED:
-- Remove `from ..tools import tool` imports
-- Remove `@tool` decorators from all functions  
-- Add proper Pydantic models for parameters
-- Keep all function logic EXACTLY the same
-- Do NOT add mocks or simplify functionality
-
-FUNCTIONS TO UPDATE:
-device_status.py: list_devices(), get_device_status(), get_device_events()
-device_control.py: hush_alarm(), run_safety_check(), set_led_brightness(), sound_alarm(), arm_disarm_security()  
-system_status.py: get_system_status(), get_process_status(), get_api_status()
-
-Please update ALL files and ALL functions in this batch. I will make separate requests for the remaining files.
-```
-
-#### **Batch Strategy for Large Projects**
-
-**Batch 1: Core Tools (3 files)**
-- device_status.py, device_control.py, system_status.py
-
-**Batch 2: Auth & Config (2 files)**  
-- auth_tools.py, config_tools.py
-
-**Batch 3: Help & Documentation (2 files)**
-- help_tool.py, about_tool.py
-
-**Batch 4: Server Integration (1 file)**
-- fastmcp_server.py (update all tool registrations)
-
-**Validation After Each Batch**:
-```bash
-# Check that changes were applied correctly
-grep -r "@tool" src/nest_protect_mcp/tools/  # Should find none
-grep -r "from ..tools import tool" src/nest_protect_mcp/tools/  # Should find none
-```
-
-### **Phase 3: Verification and Completeness Check**
-
-#### **Automated Verification Scripts**
-
-**Check Import Consistency**:
-```python
-# check_imports.py
-import os
-import ast
-
-def check_file_imports(filepath):
-    with open(filepath, 'r') as f:
-        content = f.read()
-    
-    tree = ast.parse(content)
-    imports = []
-    
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Import):
-            for alias in node.names:
-                imports.append(f"import {alias.name}")
-        elif isinstance(node, ast.ImportFrom):
-            module = node.module or ""
-            for alias in node.names:
-                imports.append(f"from {module} import {alias.name}")
-    
-    return imports
-
-# Check all tool files
-tools_dir = "src/nest_protect_mcp/tools/"
-for filename in os.listdir(tools_dir):
-    if filename.endswith('.py') and filename != '__init__.py':
-        filepath = os.path.join(tools_dir, filename)
-        imports = check_file_imports(filepath)
-        print(f"\n{filename}:")
-        for imp in imports:
-            print(f"  {imp}")
-```
-
-**Check Decorator Patterns**:
-```python
-# check_decorators.py
-import os
-import ast
-
-def check_function_decorators(filepath):
-    with open(filepath, 'r') as f:
-        content = f.read()
-    
-    tree = ast.parse(content)
-    functions = []
-    
-    for node in ast.walk(tree):
-        if isinstance(node, ast.FunctionDef):
-            decorators = [d.id if hasattr(d, 'id') else str(d) for d in node.decorator_list]
-            functions.append({
-                'name': node.name,
-                'decorators': decorators,
-                'is_async': isinstance(node, ast.AsyncFunctionDef)
-            })
-    
-    return functions
-
-# Check all tool files  
-tools_dir = "src/nest_protect_mcp/tools/"
-for filename in os.listdir(tools_dir):
-    if filename.endswith('.py') and filename != '__init__.py':
-        filepath = os.path.join(tools_dir, filename)
-        functions = check_function_decorators(filepath)
-        print(f"\n{filename}:")
-        for func in functions:
-            print(f"  {func['name']}: decorators={func['decorators']}, async={func['is_async']}")
-```
-
-#### **Manual Verification Checklist**
-
-**After Each Batch, Verify**:
-- [ ] All files in batch were actually updated
-- [ ] All functions in each file were updated
-- [ ] No functions were missed or overlooked
-- [ ] Patterns are consistently applied
-- [ ] No functionality was removed or simplified
-
-**Final Project Verification**:
-- [ ] `grep -r "@tool" src/` returns no results (old decorators removed)
-- [ ] `grep -r "from ..tools import tool" src/` returns no results (old imports removed)
-- [ ] All 24 tools still exist and have correct patterns
-- [ ] Server starts without import errors
-- [ ] All tools respond correctly in Claude Desktop
-
----
-
-## 🎯 Advanced Strategies for Complex Projects
-
-### **Strategy 1: Progressive File Updates**
-
-**For projects with 20+ files**:
-
-```
-Round 1: Update 3-4 core files
-├── Verify changes work
-├── Test server startup  
-└── Commit working state
-
-Round 2: Update next 3-4 files
-├── Apply same patterns
-├── Test integration
-└── Commit working state
-
-Round 3: Continue until complete
-├── Maintain consistency
-├── Regular testing
-└── Regular commits
-```
-
-### **Strategy 2: Pattern-Based Requests**
-
-**Instead of file-based batches, use pattern-based**:
-
-**Request 1: Import Pattern Updates**
-```
-Update imports in ALL tool files:
-- Remove: from ..tools import tool
-- Remove: from ..tools import Tool  
-- Add: (no tool-specific imports needed)
-
-Files: ALL files in src/nest_protect_mcp/tools/
-```
-
-**Request 2: Decorator Pattern Updates**
-```
-Update decorators in ALL tool files:
-- Remove: @tool decorators from all functions
-- Keep: async def function signatures
-- Keep: all function logic unchanged
-
-Files: ALL files in src/nest_protect_mcp/tools/
-```
-
-**Request 3: Parameter Model Updates**
-```
-Add Pydantic models for ALL tool functions:
-- Create BaseModel classes for each function's parameters
-- Keep parameter names and types exactly the same
-- Add proper Field descriptions
-
-Files: ALL files in src/nest_protect_mcp/tools/
-```
-
-### **Strategy 3: Validation-Driven Updates**
-
-**Use validation to drive completeness**:
-
-```python
-# comprehensive_check.py
-def validate_all_tools():
-    """Ensure every tool follows the correct pattern."""
-    
-    tools_expected = [
-        ('device_status', ['list_devices', 'get_device_status', 'get_device_events']),
-        ('device_control', ['hush_alarm', 'run_safety_check', 'set_led_brightness', 'sound_alarm', 'arm_disarm_security']),
-        ('system_status', ['get_system_status', 'get_process_status', 'get_api_status']),
-        ('auth_tools', ['initiate_oauth_flow', 'handle_oauth_callback', 'refresh_access_token']),
-        ('config_tools', ['get_config', 'update_config', 'reset_config', 'export_config', 'import_config']),
-        ('help_tool', ['list_available_tools', 'get_tool_help', 'search_tools']),
-        ('about_tool', ['about_server', 'get_supported_devices'])
-    ]
-    
-    for module_name, expected_functions in tools_expected:
-        print(f"\nValidating {module_name}.py:")
-        
-        # Check file exists
-        filepath = f"src/nest_protect_mcp/tools/{module_name}.py"
-        if not os.path.exists(filepath):
-            print(f"  ❌ File missing: {filepath}")
-            continue
-            
-        # Check functions exist  
-        functions = check_function_decorators(filepath)
-        function_names = [f['name'] for f in functions]
-        
-        for expected_func in expected_functions:
-            if expected_func in function_names:
-                print(f"  ✅ {expected_func} found")
-            else:
-                print(f"  ❌ {expected_func} MISSING")
-        
-        # Check for old patterns
-        with open(filepath, 'r') as f:
-            content = f.read()
-            
-        if "@tool" in content:
-            print(f"  ❌ Old @tool decorators still present")
-        if "from ..tools import tool" in content:
-            print(f"  ❌ Old tool imports still present")
-
-if __name__ == "__main__":
-    validate_all_tools()
-```
-
----
-
-## 🚨 Common Pitfalls and Solutions
-
-### **Pitfall 1: AI "Forgets" Files**
-
-**Problem**: AI updates 3 files, ignores the other 4
-
-**Solution**: 
-- ✅ **Explicit file enumeration** in each request
-- ✅ **Batch size limits** (3-4 files max per request)
-- ✅ **Verification after each batch**
-
-### **Pitfall 2: Inconsistent Pattern Application**
-
-**Problem**: AI applies patterns differently across files
-
-**Solution**:
-- ✅ **Provide exact code examples** for the pattern
-- ✅ **Request consistency checks** after updates
-- ✅ **Use automated validation scripts**
-
-### **Pitfall 3: Partial Function Updates**
-
-**Problem**: AI updates some functions in a file, misses others
-
-**Solution**:
-- ✅ **List ALL functions explicitly** in requests
-- ✅ **Function-by-function verification**
-- ✅ **Use grep to verify completeness**
-
-### **Pitfall 4: Silent Functionality Loss**
-
-**Problem**: AI simplifies or removes functionality during updates
-
-**Solution**:
-- ✅ **Explicit "keep all logic unchanged" instructions**
-- ✅ **Before/after comparison** of critical functions
-- ✅ **Functional testing** after each batch
-
----
-
-## 🎯 Template for Systematic Updates
-
-### **Request Template for AI**
-
-```
-SYSTEMATIC UPDATE REQUEST
-
-OBJECTIVE: [specific change needed]
-
-FILES IN THIS BATCH:
-1. [file1]
-2. [file2] 
-3. [file3]
-
-SPECIFIC CHANGES:
-- [change 1]
-- [change 2]
-- [change 3]
-
-CRITICAL REQUIREMENTS:
-- Update ALL files listed above
-- Update ALL functions in each file
-- Keep ALL existing functionality unchanged
-- Do NOT add mocks or placeholder code
-- Maintain consistent patterns across all files
-
-FUNCTIONS TO UPDATE:
-[file1]: [function1(), function2(), function3()]
-[file2]: [function1(), function2()]  
-[file3]: [function1(), function2(), function3(), function4()]
-
-VERIFICATION:
-After updates, I should be able to verify:
-- [ ] All files were modified
-- [ ] All functions follow new pattern
-- [ ] No old patterns remain
-- [ ] All functionality preserved
-
-Please confirm you understand the scope and will update ALL files and ALL functions listed.
-```
-
-### **Post-Update Verification Template**
-
-```bash
-# Verification script after AI updates
-echo "Checking batch completion..."
-
-# Check all expected files were modified
-echo "Modified files:"
-git status --porcelain
-
-# Check old patterns are removed
-echo "Checking for old patterns:"
-grep -r "@tool" src/nest_protect_mcp/tools/ || echo "✅ No old @tool decorators found"
-grep -r "from ..tools import tool" src/nest_protect_mcp/tools/ || echo "✅ No old imports found"
-
-# Check new patterns are present
-echo "Checking for new patterns:"
-grep -r "BaseModel" src/nest_protect_mcp/tools/ && echo "✅ Pydantic models found"
-
-# Test server startup
-echo "Testing server startup:"
-python -m nest_protect_mcp --test-startup
-```
-
----
-
-## 🏆 Success Example: Our FastMCP Migration
-
-### **How We Should Have Done It Systematically**
-
-**If we had followed this systematic approach**:
-
-**Day 1**: 
-- Batch 1: device_status.py, device_control.py, system_status.py
-- Verification and testing
-- Commit working state
-
-**Day 2**:
-- Batch 2: auth_tools.py, config_tools.py  
-- Batch 3: help_tool.py, about_tool.py
-- Verification and testing
-- Commit working state
-
-**Day 3**:
-- Server integration updates
-- Final verification
-- Production deployment
-
-**Total**: 3 days with systematic progress vs. our actual scattered approach
-
-### **Lessons Learned**
-
-**What Worked**:
-- ✅ **Multiple requests** were necessary (AI limitation)
-- ✅ **Verification after changes** caught missed files
-- ✅ **Git commits** provided safety nets
-
-**What Could Have Been Better**:
-- ✅ **Systematic batching** instead of ad-hoc requests
-- ✅ **Automated verification** scripts  
-- ✅ **Explicit function enumeration** in requests
-- ✅ **Pattern consistency checking**
-
----
-
-## 🎯 Recommendations for Large Projects
-
-### **For 50+ Files Projects**
-- **Batch size**: 2-3 files per request
-- **Automation**: Use verification scripts between batches
-- **Git strategy**: Commit after each successful batch
-- **Testing**: Automated testing after each batch
-
-### **For 20+ Tools Projects**  
-- **Pattern-based batching**: Group by change type, not file location
-- **Function enumeration**: List every function explicitly
-- **Consistency checking**: Automated pattern verification
-- **Safety nets**: Multiple backup strategies
-
-### **For Complex Integration Projects**
-- **Incremental approach**: One integration layer at a time
-- **Validation-driven**: Let verification scripts guide completeness  
-- **Conservative batching**: Smaller batches for complex changes
-- **Rollback readiness**: Easy rollback after each batch
-
-**Bottom Line**: AI tools can't "catch them all" in one pass, but with systematic batching and verification, you can achieve complete project-wide consistency efficiently! 🎯🔄