portacode 0.3.19.dev4__py3-none-any.whl → 1.4.11.dev1__py3-none-any.whl

portacode/logging_categories.py

@@ -0,0 +1,140 @@
+"""
+Categorized logging system for Portacode CLI.
+
+This module provides a logging system that allows filtering by categories
+to help developers focus on specific aspects of the application during debugging.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Set, Optional
+from enum import Enum
+
+
+class LogCategory(Enum):
+    """Available log categories for filtering."""
+    CONNECTION = "connection"
+    AUTHENTICATION = "auth"
+    WEBSOCKET = "websocket"
+    TERMINAL = "terminal"
+    PROJECT_STATE = "project_state"
+    FILE_SYSTEM = "filesystem"
+    GIT = "git"
+    HANDLERS = "handlers"
+    MULTIPLEXER = "mux"
+    SYSTEM = "system"
+    DEBUG = "debug"
+
+
+class CategorizedLogger:
+    """
+    A logger that supports category-based filtering.
+    
+    This wraps the standard Python logger but adds category support
+    for fine-grained filtering during debugging.
+    """
+    
+    def __init__(self, name: str, enabled_categories: Optional[Set[str]] = None):
+        self.logger = logging.getLogger(name)
+        self.enabled_categories = enabled_categories or set()
+        self._all_enabled = len(self.enabled_categories) == 0  # If no categories specified, show all
+    
+    def _should_log(self, category: LogCategory) -> bool:
+        """Check if a log with this category should be output."""
+        if self._all_enabled:
+            return True
+        return category.value in self.enabled_categories
+    
+    def _format_message(self, msg: str, category: LogCategory) -> str:
+        """Format message with category prefix."""
+        return f"[{category.value.upper()}] {msg}"
+    
+    def _parse_args(self, *args) -> tuple[LogCategory, tuple]:
+        """Parse arguments to extract category and remaining args."""
+        if args and isinstance(args[0], LogCategory):
+            return args[0], args[1:]
+        else:
+            return LogCategory.DEBUG, args
+    
+    def debug(self, msg: str, *args, **kwargs):
+        """Log debug message with optional category."""
+        category, remaining_args = self._parse_args(*args)
+        if self._should_log(category):
+            formatted_msg = self._format_message(msg, category)
+            self.logger.debug(formatted_msg, *remaining_args, **kwargs)
+    
+    def info(self, msg: str, *args, **kwargs):
+        """Log info message with optional category."""
+        category, remaining_args = self._parse_args(*args)
+        if self._should_log(category):
+            formatted_msg = self._format_message(msg, category)
+            self.logger.info(formatted_msg, *remaining_args, **kwargs)
+    
+    def warning(self, msg: str, *args, **kwargs):
+        """Log warning message with optional category."""
+        category, remaining_args = self._parse_args(*args)
+        if self._should_log(category):
+            formatted_msg = self._format_message(msg, category)
+            self.logger.warning(formatted_msg, *remaining_args, **kwargs)
+    
+    def error(self, msg: str, *args, **kwargs):
+        """Log error message with optional category."""
+        category, remaining_args = self._parse_args(*args)
+        if self._should_log(category):
+            formatted_msg = self._format_message(msg, category)
+            self.logger.error(formatted_msg, *remaining_args, **kwargs)
+    
+    def exception(self, msg: str, *args, **kwargs):
+        """Log exception message with optional category."""
+        category, remaining_args = self._parse_args(*args)
+        if self._should_log(category):
+            formatted_msg = self._format_message(msg, category)
+            self.logger.exception(formatted_msg, *remaining_args, **kwargs)
+
+
+# Global registry of enabled categories
+_enabled_categories: Set[str] = set()
+
+
+def configure_logging_categories(categories: Set[str]) -> None:
+    """Configure which log categories should be enabled globally."""
+    global _enabled_categories
+    _enabled_categories = categories
+
+
+def get_categorized_logger(name: str) -> CategorizedLogger:
+    """Get a categorized logger instance with current category settings."""
+    return CategorizedLogger(name, _enabled_categories)
+
+
+def list_available_categories() -> list[str]:
+    """Return a list of all available log categories."""
+    return [category.value for category in LogCategory]
+
+
+def parse_category_string(category_str: str) -> Set[str]:
+    """
+    Parse a comma-separated string of categories into a set.
+    
+    Args:
+        category_str: Comma-separated category names (e.g., "connection,auth,git")
+    
+    Returns:
+        Set of valid category names
+        
+    Raises:
+        ValueError: If any category is invalid
+    """
+    if not category_str.strip():
+        return set()
+    
+    categories = {cat.strip().lower() for cat in category_str.split(',')}
+    valid_categories = {cat.value for cat in LogCategory}
+    
+    invalid = categories - valid_categories
+    if invalid:
+        raise ValueError(f"Invalid categories: {', '.join(invalid)}. "
+                        f"Valid categories: {', '.join(sorted(valid_categories))}")
+    
+    return categories

portacode/pairing.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import socket
+from dataclasses import dataclass
+from typing import Optional
+
+import websockets
+
+PAIRING_URL_ENV = "PORTACODE_PAIRING_URL"
+DEFAULT_PAIRING_URL = "wss://portacode.com/ws/pairing/device/"
+
+
+class PairingError(Exception):
+    """Raised when pairing fails or is rejected."""
+
+
+@dataclass
+class PairingResult:
+    status: str
+    payload: dict
+
+
+async def _pair_device(
+    url: str,
+    public_key_b64: str,
+    pairing_code: str,
+    device_name: str,
+    project_paths: list[str] | None = None,
+    timeout: float = 300.0,
+) -> PairingResult:
+    async with websockets.connect(url) as ws:
+        # Initial ready/event
+        try:
+            ready = await asyncio.wait_for(ws.recv(), timeout=10)
+        except asyncio.TimeoutError as exc:
+            raise PairingError("Gateway did not acknowledge pairing request") from exc
+
+        try:
+            data = json.loads(ready)
+            if data.get("event") != "pairing_ready":
+                raise PairingError(f"Unexpected response from pairing gateway: {ready}")
+        except json.JSONDecodeError:
+            raise PairingError(f"Unexpected response from pairing gateway: {ready}") from None
+
+        payload = {
+            "code": pairing_code,
+            "device_name": device_name,
+            "public_key": public_key_b64,
+        }
+        if project_paths:
+            payload["project_paths"] = project_paths
+        await ws.send(json.dumps(payload))
+
+        while True:
+            try:
+                message = await asyncio.wait_for(ws.recv(), timeout=timeout)
+            except asyncio.TimeoutError as exc:
+                raise PairingError("Pairing timed out waiting for approval") from exc
+
+            try:
+                data = json.loads(message)
+            except json.JSONDecodeError:
+                continue
+
+            if data.get("event") != "pairing_status":
+                continue
+
+            status = data.get("status")
+            if status == "pending":
+                continue
+            if status == "approved":
+                return PairingResult(status="approved", payload=data)
+            reason = data.get("reason") or status or "unknown_error"
+            raise PairingError(reason)
+
+
+def pair_device_with_code(
+    keypair,
+    pairing_code: str,
+    device_name: Optional[str] = None,
+    project_paths: list[str] | None = None,
+    *,
+    timeout: float = 300.0,
+) -> PairingResult:
+    """Run the pairing workflow synchronously."""
+    pairing_url = os.getenv(PAIRING_URL_ENV, DEFAULT_PAIRING_URL)
+    normalized_url = pairing_url if pairing_url.startswith("ws") else f"wss://{pairing_url.lstrip('/')}"
+    friendly_name = device_name or socket.gethostname() or "Portacode Device"
+
+    public_key_b64 = keypair.public_key_der_b64()
+    return asyncio.run(
+        _pair_device(
+            normalized_url,
+            public_key_b64=public_key_b64,
+            pairing_code=pairing_code,
+            device_name=friendly_name,
+            project_paths=project_paths,
+            timeout=timeout,
+        )
+    )

portacode/static/js/test-ntp-clock.html

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>NTP Clock Test</title>
+    <style>
+        body {
+            font-family: monospace;
+            padding: 20px;
+            background: #1e1e1e;
+            color: #d4d4d4;
+        }
+        h1 {
+            color: #4ec9b0;
+        }
+        #status {
+            background: #252526;
+            padding: 15px;
+            border-radius: 5px;
+            border: 1px solid #3e3e42;
+        }
+        .synced {
+            color: #4ec9b0;
+        }
+        .not-synced {
+            color: #f48771;
+        }
+        .label {
+            color: #9cdcfe;
+            font-weight: bold;
+        }
+    </style>
+</head>
+<body>
+    <h1>NTP Clock Test - time.cloudflare.com</h1>
+    <div id="status"></div>
+    <script type="module">
+        import ntpClock from './utils/ntp-clock.js';
+
+        function updateDisplay() {
+            const status = ntpClock.getStatus();
+            const syncClass = status.isSynced ? 'synced' : 'not-synced';
+
+            document.getElementById('status').innerHTML = `
+                <p><span class="label">Sync Status:</span> <span class="${syncClass}">${status.isSynced ? '✅ SYNCED' : '❌ NOT SYNCED'}</span></p>
+                <p><span class="label">NTP Server:</span> ${status.server}</p>
+                <p><span class="label">NTP Time:</span> ${ntpClock.nowISO() || 'null (not synced)'}</p>
+                <p><span class="label">Local Time:</span> ${new Date().toISOString()}</p>
+                <p><span class="label">Offset:</span> ${status.offset !== null ? status.offset.toFixed(2) + 'ms' : 'null'}</p>
+                <p><span class="label">Last Sync:</span> ${status.lastSync || 'Never'}</p>
+                <p><span class="label">Time Since Sync:</span> ${status.timeSinceSync ? (status.timeSinceSync / 1000).toFixed(0) + 's' : 'N/A'}</p>
+            `;
+        }
+
+        // Update display every 100ms
+        setInterval(updateDisplay, 100);
+
+        // Log status to console every 5 seconds
+        setInterval(() => {
+            console.log('NTP Clock Status:', ntpClock.getStatus());
+        }, 5000);
+    </script>
+</body>
+</html>

portacode/static/js/utils/ntp-clock.js

@@ -0,0 +1,232 @@
+/**
+ * NTP Clock - Synchronized time source for distributed tracing
+ *
+ * Provides synchronization by requesting the server clock across the WebSocket
+ * channel defined in `WEBSOCKET_PROTOCOL`. The client measures round-trip time
+ * and applies an offset that compensates for latency before exposing timestamps.
+ */
+class NTPClock {
+    constructor() {
+        this.ntpServer = 'portacode-gateway';
+        this.offset = null;
+        this.lastSync = null;
+        this.lastLatencyMs = null;
+        this.syncInterval = 60 * 1000;
+        this.clockSyncTimeout = 20 * 1000;
+        this.maxSyncFailures = 3;
+
+        this._clockSyncSender = null;
+        this._failureCallback = null;
+        this._clockSyncTimer = null;
+        this._clockSyncTimeoutHandle = null;
+        this._pendingRequest = null;
+        this._autoSyncStarted = false;
+        this._clockSyncFailures = 0;
+    }
+
+    /**
+     * Register the function responsible for piping `clock_sync_request`
+     * packets over the dashboard WebSocket.
+     */
+    setClockSyncSender(sender) {
+        this._clockSyncSender = sender;
+        if (this._autoSyncStarted && !this._pendingRequest) {
+            this._scheduleSync(0);
+        }
+    }
+
+    /**
+     * Callback invoked when multiple sync failures occur in a row.
+     * Useful for triggering a transport reconnect.
+     */
+    onClockSyncFailure(callback) {
+        this._failureCallback = callback;
+    }
+
+    /**
+     * Start the auto-sync loop (idempotent). Will skip sending until a sender
+     * has been registered.
+     */
+    startAutoSync() {
+        if (this._autoSyncStarted) {
+            return;
+        }
+        this._autoSyncStarted = true;
+        this._scheduleSync(0);
+    }
+
+    /**
+     * Stop the auto-sync loop (used primarily in tests).
+     */
+    stopAutoSync() {
+        this._autoSyncStarted = false;
+        if (this._clockSyncTimer) {
+            clearTimeout(this._clockSyncTimer);
+            this._clockSyncTimer = null;
+        }
+        this._clearPendingRequest();
+    }
+
+    sync() {
+        return this._performClockSync();
+    }
+
+    /**
+     * Get current NTP-synchronized timestamp in milliseconds since epoch
+     * Returns null if not synced
+     */
+    now() {
+        if (this.offset === null) {
+            return null;
+        }
+        return Date.now() + this.offset;
+    }
+
+    /**
+     * Get current NTP-synchronized timestamp in ISO format
+     * Returns null if not synced
+     */
+    nowISO() {
+        const ts = this.now();
+        if (ts === null) {
+            return null;
+        }
+        return new Date(ts).toISOString();
+    }
+
+    handleServerSync(payload) {
+        if (!payload) {
+            return;
+        }
+        const receiveTime = Date.now();
+        let roundTrip = 0;
+        if (
+            payload.request_id &&
+            this._pendingRequest &&
+            payload.request_id === this._pendingRequest.requestId
+        ) {
+            roundTrip = Math.max(receiveTime - this._pendingRequest.sentAt, 0);
+            this._clockSyncFailures = 0;
+            this._clearPendingRequest();
+        }
+        const serverSend = typeof payload.server_send_time === 'number' ? payload.server_send_time : payload.server_time;
+        const serverReceive = payload.server_receive_time;
+        const serverAvg = (typeof serverReceive === 'number' && typeof serverSend === 'number')
+            ? (serverReceive + serverSend) / 2
+            : typeof serverSend === 'number'
+                ? serverSend
+                : undefined;
+        if (typeof serverAvg === 'number') {
+            this.updateFromServer(serverAvg, roundTrip);
+        }
+        if (payload.server_time_iso) {
+            this.serverTimeIso = payload.server_time_iso;
+        }
+        this._scheduleSync(this.syncInterval);
+    }
+
+    applyServerSync(payload) {
+        this.handleServerSync(payload);
+    }
+
+    updateFromServer(serverTimeMs, roundTripMs = 0) {
+        const receiveTime = Date.now();
+        const halfLatency = (roundTripMs || 0) / 2;
+        const estimatedServerReceived = receiveTime - halfLatency;
+        this.offset = serverTimeMs - estimatedServerReceived;
+        this.lastLatencyMs = roundTripMs;
+        this.lastSync = receiveTime;
+    }
+
+    getStatus() {
+        return {
+            server: this.ntpServer,
+            offset: this.offset,
+            lastSync: this.lastSync ? new Date(this.lastSync).toISOString() : null,
+            lastLatencyMs: this.lastLatencyMs,
+            timeSinceSync: this.lastSync ? Date.now() - this.lastSync : null,
+            isSynced: this.offset !== null
+        };
+    }
+
+    _scheduleSync(delay) {
+        if (!this._autoSyncStarted) {
+            return;
+        }
+        if (this._clockSyncTimer) {
+            clearTimeout(this._clockSyncTimer);
+        }
+        this._clockSyncTimer = setTimeout(() => this._performClockSync(), delay);
+    }
+
+    _performClockSync() {
+        if (!this._autoSyncStarted) {
+            return false;
+        }
+        if (!this._clockSyncSender) {
+            this._scheduleSync(Math.min(this.syncInterval, 3000));
+            return false;
+        }
+        if (this._pendingRequest) {
+            return false;
+        }
+        const requestId = this._generateRequestId();
+        const payload = {
+            event: 'clock_sync_request',
+            request_id: requestId,
+        };
+        this._pendingRequest = {
+            requestId,
+            sentAt: Date.now(),
+        };
+        const sent = this._clockSyncSender(payload);
+        if (!sent) {
+            this._handleClockSyncFailure();
+            return false;
+        }
+        this._clockSyncTimeoutHandle = setTimeout(() => this._handleClockSyncTimeout(), this.clockSyncTimeout);
+        return true;
+    }
+
+    _handleClockSyncTimeout() {
+        this._clockSyncFailures += 1;
+        this._clearPendingRequest();
+        if (
+            this._clockSyncFailures >= this.maxSyncFailures &&
+            typeof this._failureCallback === 'function'
+        ) {
+            this._failureCallback();
+        }
+        this._scheduleSync(this.syncInterval);
+    }
+
+    _handleClockSyncFailure() {
+        this._clockSyncFailures += 1;
+        this._clearPendingRequest();
+        if (
+            this._clockSyncFailures >= this.maxSyncFailures &&
+            typeof this._failureCallback === 'function'
+        ) {
+            this._failureCallback();
+        }
+        this._scheduleSync(this.syncInterval);
+    }
+
+    _clearPendingRequest() {
+        if (this._clockSyncTimeoutHandle) {
+            clearTimeout(this._clockSyncTimeoutHandle);
+            this._clockSyncTimeoutHandle = null;
+        }
+        this._pendingRequest = null;
+    }
+
+    _generateRequestId() {
+        return `clock_sync:${Date.now()}:${Math.floor(Math.random() * 1000000)}`;
+    }
+}
+
+// Global instance - auto-starts sync
+const ntpClock = new NTPClock();
+ntpClock.startAutoSync();
+
+export default ntpClock;

portacode/utils/NTP_ARCHITECTURE.md

@@ -0,0 +1,136 @@
+# NTP Clock Architecture
+
+## Overview
+
+All entities (client, server, device) synchronize to **time.cloudflare.com** for distributed tracing.
+
+## Architecture: Single Package for Everything
+
+All NTP clock implementations (Python and JavaScript) are in the **portacode package** to ensure DRY principles.
+
+## Python Implementation
+
+**Location:** `portacode/utils/ntp_clock.py` (in portacode package)
+
+### Import Path
+```python
+from portacode.utils.ntp_clock import ntp_clock
+```
+
+### Usage Locations
+1. **Django Server Consumers** (`server/portacode_django/dashboard/consumers.py`)
+2. **Device Base Handlers** (`portacode/connection/handlers/base.py`)
+3. **Device Client** (`server/portacode_django/data/services/device_client.py`)
+4. **Any Python code with portacode installed**
+
+### Dependencies
+- `setup.py`: Added `ntplib>=0.4.0` to `install_requires`
+- `server/portacode_django/requirements.txt`: Added `portacode>=1.3.26`
+
+### API
+```python
+# Get NTP-synchronized timestamp (None if not synced)
+ntp_clock.now_ms()      # milliseconds
+ntp_clock.now()         # seconds
+ntp_clock.now_iso()     # ISO format
+
+# Check sync status
+status = ntp_clock.get_status()
+# {
+#   'server': 'time.cloudflare.com',
+#   'offset_ms': 6.04,
+#   'last_sync': '2025-10-05T04:37:12.768445+00:00',
+#   'is_synced': True
+# }
+```
+
+## JavaScript Implementation
+
+**Location:** `portacode/static/js/utils/ntp-clock.js` (in portacode package)
+
+### Django Setup
+
+Django will serve static files from the portacode package automatically after `collectstatic`:
+
+```python
+# Django settings.py - no changes needed, just ensure:
+INSTALLED_APPS = [
+    # ... other apps
+    'portacode',  # Add portacode as an installed app (optional, for admin integration)
+]
+
+# Static files will be collected from portacode package
+STATIC_URL = '/static/'
+```
+
+After installing portacode (`pip install portacode` or `pip install -e .`), run:
+```bash
+python manage.py collectstatic
+```
+
+This will copy `portacode/static/js/utils/ntp-clock.js` to Django's static files directory.
+
+### Import Path (in Django templates/JS)
+```javascript
+import ntpClock from '/static/js/utils/ntp-clock.js';
+// or relative to your JS file:
+import ntpClock from './utils/ntp-clock.js';
+```
+
+### Usage Locations
+1. **Dashboard WebSocket** (`websocket-service.js`)
+2. **Project WebSocket** (`websocket-service-project.js`)
+
+### API
+```javascript
+// Get NTP-synchronized timestamp (null if not synced)
+ntpClock.now()          // milliseconds
+ntpClock.nowISO()       // ISO format
+
+// Check sync status
+const status = ntpClock.getStatus();
+// {
+//   server: 'time.cloudflare.com',
+//   offset: 6.04,
+//   lastSync: '2025-10-05T04:37:12.768445+00:00',
+//   isSynced: true
+// }
+```
+
+## Design Principles
+
+1. **DRY (Don't Repeat Yourself)**
+   - **Python:** Single implementation in portacode package (`portacode/utils/ntp_clock.py`)
+   - **JavaScript:** Single implementation in portacode package (`portacode/static/js/utils/ntp-clock.js`)
+   - Both served from the same package, no duplication across repos
+
+2. **No Fallback Servers**
+   - All entities MUST sync to time.cloudflare.com
+   - If sync fails, timestamps are None/null
+   - Ensures all timestamps are comparable
+
+3. **Auto-Sync**
+   - Re-syncs every 5 minutes automatically
+   - Initial sync on import/load
+   - Max 3 retry attempts before marking as failed
+
+4. **Thread-Safe (Python)**
+   - Uses threading.Lock for concurrent access
+   - Background daemon thread for periodic sync
+
+## Testing
+
+### Python
+```bash
+python tools/test_python_ntp_clock.py
+```
+
+### JavaScript
+The test file is included in the package at `portacode/static/js/test-ntp-clock.html`.
+
+After Django collectstatic, open: `/static/js/test-ntp-clock.html` in browser
+
+Or run directly from package:
+```bash
+python -c "import portacode, os; print(os.path.join(os.path.dirname(portacode.__file__), 'static/js/test-ntp-clock.html'))"
+```

portacode/utils/__init__.py

@@ -0,0 +1 @@
+"""Portacode utility modules."""