h4-debug 0.1.0__py3-none-any.whl

h4_debug/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

h4_debug/cli.py

@@ -0,0 +1,103 @@
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import webbrowser
+import pathlib
+
+from . import server
+
+def create_sitecustomize(mode):
+    temp_dir = tempfile.mkdtemp(prefix="h4_debug_")
+    sitecustomize_path = os.path.join(temp_dir, "sitecustomize.py")
+    
+    # We will write a sitecustomize.py that imports our interceptor
+    # and initializes it with the selected mode.
+    script = f"""
+import sys
+import os
+
+# Remove this temp dir from sys.path so we don't mess with other imports too much
+try:
+    sys.path.remove(r"{temp_dir}")
+except ValueError:
+    pass
+
+try:
+    import h4_debug.interceptor
+    h4_debug.interceptor.start_interception(mode="{mode}")
+except ImportError as e:
+    print(f"h4-debug: Failed to load interceptor: {{e}}", file=sys.stderr)
+"""
+    with open(sitecustomize_path, "w", encoding="utf-8") as f:
+        f.write(script)
+    
+    return temp_dir
+
+def main():
+    parser = argparse.ArgumentParser(description="h4-debug: Advanced application proxy debugger", usage="h4-debug [--mode MODE] command ...")
+    parser.add_argument("--mode", choices=["Normal", "Trace", "Full"], default="Normal", help="Debugging mode")
+    parser.add_argument("--port", type=int, default=8008, help="Port for the web dashboard")
+    parser.add_argument("command", nargs=argparse.REMAINDER, help="Command to run")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    command = args.command
+    # argparse puts '--' in the remainder if it's there
+    if command[0] == "--":
+        command = command[1:]
+
+    # 1. Start the web server in a background thread
+    print(f"[h4-debug] Starting dashboard on http://localhost:{args.port} ...")
+    server_thread = threading.Thread(target=server.run_server, args=(args.port,), daemon=True)
+    server_thread.start()
+
+    # Give server a moment to start
+    time.sleep(1.0)
+    
+    # Open dashboard in browser
+    webbrowser.open(f"http://localhost:{args.port}")
+
+    # 2. Setup interception environment
+    env = os.environ.copy()
+    
+    # Python interception via sitecustomize
+    sitecustomize_dir = create_sitecustomize(args.mode)
+    
+    if "PYTHONPATH" in env:
+        env["PYTHONPATH"] = f"{sitecustomize_dir}{os.pathsep}{env['PYTHONPATH']}"
+    else:
+        env["PYTHONPATH"] = sitecustomize_dir
+        
+    env["H4_DEBUG_MODE"] = args.mode
+    env["H4_DEBUG_PORT"] = str(args.port)
+
+    # 3. Launch the target process
+    print(f"[h4-debug] Launching process: {' '.join(command)}")
+    try:
+        process = subprocess.Popen(command, env=env)
+        process.wait()
+    except KeyboardInterrupt:
+        print("\n[h4-debug] Interrupted by user. Terminating process...")
+        if process:
+            process.terminate()
+            process.wait()
+    except Exception as e:
+        print(f"[h4-debug] Error running command: {e}")
+    finally:
+        print("[h4-debug] Process finished. Dashboard will remain open until you exit (Ctrl+C).")
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            print("[h4-debug] Shutting down.")
+
+if __name__ == "__main__":
+    main()

h4_debug/interceptor.py

@@ -0,0 +1,197 @@
+import builtins
+import json
+import os
+import queue
+import socket
+import sys
+import threading
+import time
+import traceback
+from datetime import datetime
+
+try:
+    from websockets.sync.client import connect
+except ImportError:
+    connect = None
+
+# We must keep references to original functions to avoid infinite recursion
+_original_open = builtins.open
+_original_socket = socket.socket
+_original_print = builtins.print
+
+class TelemetryClient:
+    def __init__(self, port):
+        self.port = port
+        self.queue = queue.Queue()
+        self.thread = threading.Thread(target=self._run, daemon=True)
+        self.thread.start()
+
+    def _run(self):
+        ws_url = f"ws://127.0.0.1:{self.port}/ws/telemetry"
+        if not connect:
+            return
+            
+        while True:
+            try:
+                # Use original socket context if websockets internally creates sockets
+                # This might be tricky because websockets uses asyncio or sync wrappers 
+                # which use the monkeypatched socket. We must be very careful.
+                # A safer approach for the telemetry thread is to unpatch socket temporarily or 
+                # ensure our hooks bypass if thread == telemetry_thread
+                with connect(ws_url) as websocket:
+                    while True:
+                        msg = self.queue.get()
+                        websocket.send(json.dumps(msg))
+                        self.queue.task_done()
+            except Exception as e:
+                time.sleep(1)
+
+    def send(self, module, event_type, data):
+        msg = {
+            "timestamp": datetime.now().isoformat(),
+            "module": module,
+            "type": event_type,
+            "data": data,
+            "thread": threading.current_thread().name
+        }
+        self.queue.put(msg)
+
+
+_telemetry = None
+_mode = "Normal"
+_telemetry_thread_id = None
+
+def _is_telemetry_thread():
+    return threading.get_ident() == _telemetry_thread_id
+
+# --- Disk Interception ---
+
+def patched_open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None):
+    if not _is_telemetry_thread() and _telemetry:
+        _telemetry.send("Disk", "open", {
+            "file": str(file),
+            "mode": mode
+        })
+    return _original_open(file, mode, buffering, encoding, errors, newline, closefd, opener)
+
+# --- Network Interception ---
+
+class PatchedSocket(_original_socket):
+    def __init__(self, family=socket.AF_INET, type=socket.SOCK_STREAM, proto=0, fileno=None):
+        super().__init__(family, type, proto, fileno)
+        self._h4_peer = None
+
+    def connect(self, address):
+        if not _is_telemetry_thread() and _telemetry:
+            self._h4_peer = address
+            _telemetry.send("Network", "connect", {
+                "address": str(address)
+            })
+        return super().connect(address)
+        
+    def send(self, data, flags=0):
+        if not _is_telemetry_thread() and _telemetry:
+            payload = data.hex() if _mode == "Full" else (data[:100].hex() + "..." if len(data)>100 else data.hex())
+            # try to decode as text
+            try:
+                text_payload = data.decode('utf-8', errors='ignore')
+            except Exception:
+                text_payload = None
+                
+            _telemetry.send("Network", "send", {
+                "address": str(self._h4_peer),
+                "bytes": len(data),
+                "payload_hex": payload,
+                "payload_text": text_payload
+            })
+        return super().send(data, flags)
+        
+    def recv(self, bufsize, flags=0):
+        data = super().recv(bufsize, flags)
+        if not _is_telemetry_thread() and _telemetry:
+            payload = data.hex() if _mode == "Full" else (data[:100].hex() + "..." if len(data)>100 else data.hex())
+            try:
+                text_payload = data.decode('utf-8', errors='ignore')
+            except Exception:
+                text_payload = None
+                
+            _telemetry.send("Network", "recv", {
+                "address": str(self._h4_peer),
+                "bytes": len(data),
+                "payload_hex": payload,
+                "payload_text": text_payload
+            })
+        return data
+
+# --- Stdout/Stderr Interception ---
+
+class PatchedStream:
+    def __init__(self, original_stream, stream_name):
+        self.original_stream = original_stream
+        self.stream_name = stream_name
+
+    def write(self, text):
+        if not _is_telemetry_thread() and _telemetry and text.strip():
+            _telemetry.send("Console", self.stream_name, {"text": text})
+        return self.original_stream.write(text)
+
+    def flush(self):
+        return self.original_stream.flush()
+
+    def __getattr__(self, name):
+        return getattr(self.original_stream, name)
+
+
+# --- Execution Tracing ---
+
+def trace_calls(frame, event, arg):
+    if _is_telemetry_thread() or not _telemetry:
+        return trace_calls
+        
+    if event == "call":
+        func_name = frame.f_code.co_name
+        filename = frame.f_code.co_filename
+        # Ignore our own files and standard library to avoid noise, unless Full Debug
+        if "h4_debug" not in filename and ("site-packages" not in filename or _mode == "Full"):
+            _telemetry.send("Execution", "call", {
+                "function": func_name,
+                "file": filename,
+                "line": frame.f_lineno
+            })
+    elif event == "exception" and _mode in ("Trace", "Full"):
+        exc_type, exc_value, exc_traceback = arg
+        filename = frame.f_code.co_filename
+        if "h4_debug" not in filename:
+            _telemetry.send("Execution", "exception", {
+                "type": exc_type.__name__,
+                "value": str(exc_value),
+                "file": filename,
+                "line": frame.f_lineno
+            })
+            
+    return trace_calls
+
+def start_interception(mode="Normal"):
+    global _telemetry, _mode, _telemetry_thread_id
+    _mode = mode
+    
+    port = int(os.environ.get("H4_DEBUG_PORT", 8008))
+    _telemetry = TelemetryClient(port)
+    _telemetry_thread_id = _telemetry.thread.ident
+    
+    # Patch Disk
+    builtins.open = patched_open
+    
+    # Patch Network
+    socket.socket = PatchedSocket
+    
+    # Patch Console
+    sys.stdout = PatchedStream(sys.stdout, "stdout")
+    sys.stderr = PatchedStream(sys.stderr, "stderr")
+    
+    # Enable Tracing if required
+    if mode in ("Trace", "Full"):
+        sys.settrace(trace_calls)
+        
+    _telemetry.send("System", "init", {"mode": mode, "pid": os.getpid()})
+

h4_debug/server.py

@@ -0,0 +1,94 @@
+import asyncio
+import json
+import os
+import uvicorn
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+app = FastAPI()
+
+# Store connected dashboard clients
+dashboard_clients = []
+
+# To persist logs for when a dashboard connects slightly after startup
+log_history = []
+MAX_HISTORY = 5000
+
+# Get the path to static files
+STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
+if not os.path.exists(STATIC_DIR):
+    os.makedirs(STATIC_DIR)
+
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+@app.get("/")
+async def get_dashboard():
+    dashboard_path = os.path.join(STATIC_DIR, "dashboard.html")
+    if os.path.exists(dashboard_path):
+        with open(dashboard_path, "r", encoding="utf-8") as f:
+            return HTMLResponse(f.read())
+    return HTMLResponse("<h1>Dashboard not found</h1>")
+
+@app.websocket("/ws/telemetry")
+async def websocket_telemetry(websocket: WebSocket):
+    """Endpoint for the intercepted process to push logs."""
+    await websocket.accept()
+    try:
+        while True:
+            data = await websocket.receive_text()
+            
+            try:
+                log_item = json.loads(data)
+                log_history.append(log_item)
+                if len(log_history) > MAX_HISTORY:
+                    log_history.pop(0)
+            except Exception:
+                pass
+                
+            # Broadcast to all dashboards
+            disconnected_clients = []
+            for client in dashboard_clients:
+                try:
+                    await client.send_text(data)
+                except Exception:
+                    disconnected_clients.append(client)
+            
+            for client in disconnected_clients:
+                if client in dashboard_clients:
+                    dashboard_clients.remove(client)
+    except WebSocketDisconnect:
+        pass
+
+@app.websocket("/ws/dashboard")
+async def websocket_dashboard(websocket: WebSocket):
+    """Endpoint for the web dashboard to receive logs."""
+    await websocket.accept()
+    
+    # Send history on connect
+    for log_item in log_history:
+        try:
+            await websocket.send_text(json.dumps(log_item))
+        except Exception:
+            break
+            
+    dashboard_clients.append(websocket)
+    try:
+        while True:
+            # Keep alive and receive commands from dashboard if needed
+            data = await websocket.receive_text()
+            cmd = json.loads(data)
+            if cmd.get("action") == "clear":
+                log_history.clear()
+    except WebSocketDisconnect:
+        if websocket in dashboard_clients:
+            dashboard_clients.remove(websocket)
+
+def run_server(port: int):
+    # Disable uvicorn access logs to keep terminal clean
+    import logging
+    log = logging.getLogger("uvicorn.access")
+    log.setLevel(logging.WARNING)
+    
+    uvicorn.run(app, host="127.0.0.1", port=port, log_level="warning")
+

h4_debug-0.1.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: h4-debug
+Version: 0.1.0
+Summary: Advanced application proxy debugger and F12-style web console
+Author-email: h4 <h4@example.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn[standard]>=0.20
+Requires-Dist: websockets>=11.0
+
+# h4-debug
+
+Advanced application proxy debugger and F12-style web console.
+
+## Usage
+
+```bash
+pip install h4-debug
+h4-debug python main.py
+```

h4_debug-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+h4_debug/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+h4_debug/cli.py,sha256=DoGUYNFxmesQFDqtVBW1XhdK35ks55-JSK4SuUAdePU,3208
+h4_debug/interceptor.py,sha256=ZFWhzmjKSLGJbHVZxTjthnR22jqtGWatyULCk49O7OI,6609
+h4_debug/server.py,sha256=YVxF8C3QoVj4riddJ-qGRr8ReqdESwY8SykcRuh4T8E,3005
+h4_debug-0.1.0.dist-info/METADATA,sha256=gk3rGtBV4gHHzGwxfk5AlzA0IakJIMwOS6evYF8mdPY,486
+h4_debug-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+h4_debug-0.1.0.dist-info/entry_points.txt,sha256=xZWjVvTnVZdESrvUUl0BEwVHT3q8-5GhA58oXvK-d2g,47
+h4_debug-0.1.0.dist-info/top_level.txt,sha256=2fWNW-Vus5YAjroqCTsKMS2I4RT9lfBkSE3aKzlWE70,9
+h4_debug-0.1.0.dist-info/RECORD,,

h4_debug-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

h4_debug-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+h4-debug = h4_debug.cli:main

h4_debug-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+h4_debug