@hybridlabor-api/aos 4.3.0 → 4.4.0

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

@@ -1,25 +0,0 @@
-# Archived development notes
-
-Fleet-import snapshots from **notepadpp-mcp** and generic MCP industrialization (Oct 2025). **Not maintained for pywinauto-mcp.**
-
-| File | Origin / note |
-|------|----------------|
-| [AI_DEVELOPMENT_RULES.md](AI_DEVELOPMENT_RULES.md) | nest-protect / generic AI guardrails |
-| [AI_DEVELOPMENT_TOOLS_COMPARISON.md](AI_DEVELOPMENT_TOOLS_COMPARISON.md) | Windsurf vs Cursor era |
-| [BULLETPROOF_MCP_GUIDE.md](BULLETPROOF_MCP_GUIDE.md) | `notepadpp_mcp` sync_health / file_validator |
-| [DEBUGGING_LESSONS_LEARNED.md](DEBUGGING_LESSONS_LEARNED.md) | Historical debugging log |
-| [DEVELOPMENT_PAIN_POINTS.md](DEVELOPMENT_PAIN_POINTS.md) | Historical pain points |
-| [FILE_VALIDATION_COMPLETE.md](FILE_VALIDATION_COMPLETE.md) | notepadpp file validator |
-| [FILE_VALIDATION_GUIDE.md](FILE_VALIDATION_GUIDE.md) | notepadpp file validator |
-| [LINK_PARSER_FIX.md](LINK_PARSER_FIX.md) | notepadpp link_parser |
-| [MCP_SYNC_DEBUGGING_GUIDE.md](MCP_SYNC_DEBUGGING_GUIDE.md) | MCP sync health |
-| [PYTHON_DEPENDENCY_HELL_FIX.md](PYTHON_DEPENDENCY_HELL_FIX.md) | Python 3.13 pin note (still useful background) |
-| [PYTHON_SNIPPETS_USAGE_GUIDE.md](PYTHON_SNIPPETS_USAGE_GUIDE.md) | Generic FastMCP snippets |
-| [SYNC_HEALTH_IMPROVEMENTS_SUMMARY.md](SYNC_HEALTH_IMPROVEMENTS_SUMMARY.md) | notepadpp sync_health |
-| [SYNC_HEALTH_INTEGRATION.md](SYNC_HEALTH_INTEGRATION.md) | notepadpp sync_health |
-| [SYSTEMATIC_PROJECT_UPDATES.md](SYSTEMATIC_PROJECT_UPDATES.md) | Generic update checklist |
-| [mcp-prompt-templates-vs-docstrings.md](mcp-prompt-templates-vs-docstrings.md) | Fleet docstring patterns |
-| [mcp-tool-docstring-best-practices.md](mcp-tool-docstring-best-practices.md) | Fleet docstring patterns |
-| [mcp-tool-documentation-standards.md](mcp-tool-documentation-standards.md) | Fleet docstring standards |
-
-Current contributor entry point: [../../DEVELOPMENT.md](../../DEVELOPMENT.md).

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

@@ -1,496 +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).
-# File Sync Health Improvements - Complete Summary
-
-**Date:** October 10, 2025  
-**Context:** Advanced-memory-mcp sync failure (242/1,896 files)  
-**Impact:** Prevented future silent failures across all MCP servers
-
----
-
-## The Problem We Solved
-
-### What Happened
-
-**Symptom:**
-- User reported "sync stuck at 250 mds"
-- Actually: Advanced-memory-mcp stuck at 242/1,896 files (87% incomplete)
-- Server running, tools registered, **but no scanning happening**
-- **NO ERROR MESSAGES** - complete silent failure
-
-### Root Cause
-
-```python
-# The bug pattern that caused the issue:
-def start_file_watcher(self):
-    try:
-        self.watcher = FileWatcher(self.project_path)
-        # If watcher.start() fails silently, no one knows!
-    except Exception:
-        pass  # ❌ Swallowed exception - the killer
-```
-
-**Why it was hard to diagnose:**
-1. Server appeared healthy (tools loaded)
-2. Database was created (152 KB)
-3. No errors in logs
-4. No timeouts or crashes
-5. User waited 10+ minutes for "sync" that never happened
-
----
-
-## What We Created
-
-### 1. **Comprehensive Debugging Guide**
-📄 `docs/development/MCP_SYNC_DEBUGGING_GUIDE.md`
-
-**Contents:**
-- Root cause analysis of the failure
-- Structured logging implementation
-- Health check tools
-- Progress monitoring
-- Automatic recovery
-- Testing strategies
-- Production monitoring
-- **15+ code examples**
-
-**Key Insights:**
-- Silent failures are deadly
-- Progress monitoring is essential
-- Health checks catch bugs
-- Timeouts prevent hangs
-- Metrics enable debugging
-
----
-
-### 2. **Complete Test Suite**
-📄 `tests/test_sync_health.py`
-
-**Test Coverage:**
-```python
-class TestSyncInitialization:      # 4 tests - startup
-class TestSyncHealthChecks:        # 3 tests - health monitoring
-class TestSyncStallDetection:      # 2 tests - stall detection
-class TestSyncPerformance:         # 2 tests - performance
-class TestSyncErrorHandling:       # 3 tests - error handling
-class TestSyncRecovery:            # 1 test  - recovery
-class TestSyncMonitoring:          # 2 tests - observability
-```
-
-**Total: 17 comprehensive tests** catching:
-- Silent startup failures
-- Stuck/stalled syncs
-- Permission errors
-- Performance regressions
-- Recovery mechanisms
-
----
-
-### 3. **Production-Ready Health Module**
-📄 `src/notepadpp_mcp/sync_health.py`
-
-**Features:**
-- ✅ Structured logging (structlog support)
-- ✅ State machine with clear semantics
-- ✅ Progress tracking and metrics
-- ✅ Stall detection (configurable timeout)
-- ✅ Automatic recovery (with retry limits)
-- ✅ Health check API
-- ✅ Formatted reports
-- ✅ Background monitoring
-- ✅ Error aggregation
-
-**API:**
-```python
-# Initialize
-monitor = SyncHealthMonitor(
-    project_path="/path/to/files",
-    stall_timeout=60,
-    check_interval=10,
-    max_recovery_attempts=3
-)
-
-# Start scan
-monitor.start_scan()
-
-# Update progress
-monitor.update_scan_progress(files_scanned)
-
-# Get health report
-report = monitor.get_health_report()  # machine-readable
-text = monitor.format_health_report()  # human-readable
-```
-
----
-
-### 4. **Integration Guide**
-📄 `docs/development/SYNC_HEALTH_INTEGRATION.md`
-
-**Covers:**
-- Quick start (5 minutes)
-- Complete MCP server integration
-- Advanced usage patterns
-- Custom health checks
-- Prometheus integration
-- Production monitoring
-- Troubleshooting guide
-- Best practices
-
-**Real-world examples:**
-- FastMCP integration
-- Health check tools
-- Background monitoring
-- Automatic recovery
-
----
-
-## Technical Implementation
-
-### Structured Logging
-
-**Before:**
-```python
-# Silent failure - no one knows what happened
-try:
-    self.watcher.start()
-except:
-    pass
-```
-
-**After:**
-```python
-# Every operation logged with context
-try:
-    logger.info("scan_starting", path=self.project_path)
-    self.watcher.start()
-    logger.info("scan_started", state="scanning")
-except PermissionError as e:
-    logger.error("scan_permission_denied", error=str(e))
-except Exception as e:
-    logger.error("scan_failed", 
-                error=str(e),
-                traceback=traceback.format_exc())
-```
-
----
-
-### Progress Monitoring
-
-**Before:**
-```python
-# No way to track progress
-for file in files:
-    process(file)
-```
-
-**After:**
-```python
-# Continuous progress updates
-for i, file in enumerate(files):
-    process(file)
-    
-    if i % 10 == 0:
-        monitor.update_scan_progress(i)
-        # Logs: "scan_progress: 40/1896 (21.1%)"
-```
-
----
-
-### Stall Detection
-
-**Before:**
-```python
-# Scan stuck forever, no alerts
-while scanning:
-    scan_next_file()
-```
-
-**After:**
-```python
-# Background monitoring detects stalls
-async def _monitor_loop(self):
-    while self._is_monitoring:
-        await asyncio.sleep(self.check_interval)
-        
-        if self.metrics.time_since_progress > self.stall_timeout:
-            logger.warning("sync_stalled")
-            await self._attempt_recovery()
-```
-
----
-
-### Health Checks
-
-**New MCP Tools:**
-```python
-@mcp.tool()
-async def sync_status() -> str:
-    """Get detailed sync status with diagnostics."""
-    return monitor.format_health_report()
-
-@mcp.tool()
-async def sync_health_check() -> dict:
-    """Machine-readable health check."""
-    return monitor.get_health_report()
-```
-
-**Output:**
-```
-# Sync Health Report
-
-**Status:** ✅ HEALTHY
-**State:** SCANNING
-
-## Metrics
-- **Progress:** 1250 / 1896 (65.9%)
-- **Speed:** 12.5 files/sec
-- **Runtime:** 100.0 seconds
-- **Last Progress:** 0.8 seconds ago
-
-## Watcher
-- **Status:** ALIVE
-
-## Recommendations
-- ✅ All systems healthy
-```
-
----
-
-## Impact & Benefits
-
-### For Users
-
-**Before:**
-- ❌ Silent failures
-- ❌ No progress visibility
-- ❌ Manual database inspection required
-- ❌ Restarts needed to diagnose
-
-**After:**
-- ✅ Clear progress indicators
-- ✅ Real-time health checks
-- ✅ Automatic recovery
-- ✅ Detailed diagnostics
-
----
-
-### For Developers
-
-**Before:**
-- ❌ Hard to debug
-- ❌ No test coverage for sync
-- ❌ Guessing at problems
-- ❌ Manual recovery only
-
-**After:**
-- ✅ Comprehensive logging
-- ✅ 17 tests catching issues
-- ✅ Clear error messages
-- ✅ Automatic recovery
-
----
-
-### For Operations
-
-**Before:**
-- ❌ No monitoring hooks
-- ❌ No alerts
-- ❌ Manual health checks
-- ❌ No metrics
-
-**After:**
-- ✅ Prometheus integration ready
-- ✅ Health check API
-- ✅ Structured logs for parsing
-- ✅ Detailed metrics
-
----
-
-## Lessons Learned
-
-### 1. **Silent Failures Are Deadly**
-
-```python
-# NEVER DO THIS:
-try:
-    critical_operation()
-except:
-    pass  # ❌ SILENT DEATH
-
-# ALWAYS DO THIS:
-try:
-    logger.info("operation_starting")
-    critical_operation()
-    logger.info("operation_completed")
-except SpecificError as e:
-    logger.error("operation_failed", error=str(e))
-    raise
-```
-
-### 2. **Progress Monitoring is Essential**
-
-```python
-# Users need feedback:
-for i, item in enumerate(items):
-    process(item)
-    
-    if i % 10 == 0:  # Log every 10 items
-        logger.info("progress", 
-                   current=i,
-                   total=len(items),
-                   percent=i/len(items)*100)
-```
-
-### 3. **Health Checks Catch Bugs**
-
-```python
-# Expose health check tools:
-@mcp.tool()
-async def health_check():
-    return {
-        "healthy": system.is_healthy(),
-        "state": system.state,
-        "errors": system.errors,
-        "recommendations": system.get_recommendations()
-    }
-```
-
-### 4. **Timeouts Prevent Hangs**
-
-```python
-# All long operations need timeouts:
-if time_since_progress > stall_timeout:
-    logger.warning("operation_stalled")
-    attempt_recovery()
-```
-
-### 5. **Tests Catch Regressions**
-
-```python
-# Test that sync doesn't hang:
-@pytest.mark.timeout(60)
-def test_sync_completes():
-    sync.start()
-    assert sync.state == "completed"
-```
-
----
-
-## Metrics & Statistics
-
-### Code Added
-- **3 new files:** 
-  - Debugging guide: 600+ lines
-  - Test suite: 400+ lines  
-  - Health module: 600+ lines
-  - Integration guide: 400+ lines
-- **Total:** 2,000+ lines of documentation and code
-
-### Documentation
-- **4 comprehensive guides**
-- **20+ code examples**
-- **17 test cases**
-- **15+ best practices**
-
-### Prevention
-- ✅ Prevents silent failures
-- ✅ Detects stalls automatically
-- ✅ Recovers from errors
-- ✅ Provides clear diagnostics
-
----
-
-## Future Work
-
-### Potential Enhancements
-
-1. **Metrics Export**
-   - Prometheus integration
-   - Grafana dashboards
-   - Alert rules
-
-2. **Advanced Recovery**
-   - Checkpoint/resume
-   - Parallel scanning
-   - Incremental updates
-
-3. **UI Integration**
-   - Progress bars in MCP tools
-   - Visual health dashboard
-   - Real-time updates
-
-4. **Performance Optimization**
-   - Batch processing
-   - Parallel file scanning
-   - Database optimization
-
----
-
-## How to Use
-
-### For notepadpp-mcp
-
-1. **Copy the health module:**
-   ```bash
-   # Already in: src/notepadpp_mcp/sync_health.py
-   ```
-
-2. **Add to your server:**
-   ```python
-   from sync_health import SyncHealthMonitor
-   
-   monitor = SyncHealthMonitor(project_path)
-   monitor.start_scan()
-   ```
-
-3. **Expose health tools:**
-   ```python
-   @mcp.tool()
-   async def sync_status():
-       return monitor.format_health_report()
-   ```
-
-### For Other MCP Servers
-
-1. **Copy the module:**
-   ```bash
-   cp src/notepadpp_mcp/sync_health.py your_project/
-   ```
-
-2. **Follow integration guide:**
-   ```bash
-   docs/development/SYNC_HEALTH_INTEGRATION.md
-   ```
-
-3. **Write tests:**
-   ```bash
-   cp tests/test_sync_health.py your_project/tests/
-   ```
-
----
-
-## Conclusion
-
-This work transforms a **frustrating debugging session** into **reusable infrastructure** that:
-
-✅ **Prevents** the exact failure we experienced  
-✅ **Detects** similar issues automatically  
-✅ **Recovers** from errors without manual intervention  
-✅ **Documents** best practices for all MCP servers  
-
-**The Great Advanced-Memory Sync Failure of 2025** is now a **comprehensive solution** that benefits the entire MCP ecosystem!
-
----
-
-## Related Files
-
-- 📄 [MCP_SYNC_DEBUGGING_GUIDE.md](./MCP_SYNC_DEBUGGING_GUIDE.md) - Debugging guide
-- 📄 [SYNC_HEALTH_INTEGRATION.md](./SYNC_HEALTH_INTEGRATION.md) - Integration guide  
-- 📄 [test_sync_health.py](../../tests/test_sync_health.py) - Test suite
-- 📄 [sync_health.py](../../src/notepadpp_mcp/sync_health.py) - Health module
-
----
-
-**"Dependency hell was not invented on a whim... and neither was sync hell!"** 🔥
-
-*From 87% failure to 100% visibility - October 10, 2025*
-