cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/preview/__init__.py

@@ -0,0 +1 @@
+"""CAT Live Preview Infrastructure (dev server, preview manager, live reload, diagnostics)."""

calc_terminal/preview/dev_server.py

@@ -0,0 +1,303 @@
+"""CAT Live Preview — Dev Server Manager (calc_terminal/preview/dev_server.py).
+
+Owns development server lifecycle:
+- Detects project configuration (Static HTML, Vite, Next.js, CRA, Node).
+- Manages available port detection and avoids collisions.
+- Starts, stops, restarts real local HTTP server binding 127.0.0.1 strictly.
+- Prevents duplicate server processes for the same workspace.
+- Verifies server readiness before declaring live state.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Tuple
+
+
+class ServerState:
+    STOPPED = "stopped"
+    STARTING = "starting"
+    RUNNING = "running"
+    ERROR = "error"
+    RESTARTING = "restarting"
+
+
+@dataclass
+class ProjectInfo:
+    kind: str  # "static", "vite", "next", "cra", "node"
+    label: str
+    root: str
+    entry_file: Optional[str] = None
+    start_command: Optional[List[str]] = None
+    is_framework: bool = False
+
+
+def detect_project_type(root: str) -> ProjectInfo:
+    """Analyze workspace root to determine project type and start strategy."""
+    abs_root = os.path.abspath(os.path.expanduser(root or ""))
+    if not os.path.isdir(abs_root):
+        return ProjectInfo(kind="static", label="Static Web", root=abs_root)
+
+    pkg_path = os.path.join(abs_root, "package.json")
+    if os.path.isfile(pkg_path):
+        try:
+            with open(pkg_path, "r", encoding="utf-8", errors="replace") as f:
+                pkg = json.load(f)
+            scripts = pkg.get("scripts", {})
+            deps = {}
+            deps.update(pkg.get("dependencies", {}))
+            deps.update(pkg.get("devDependencies", {}))
+
+            # Vite detection
+            for cfg in ("vite.config.js", "vite.config.ts", "vite.config.mjs", "vite.config.cjs"):
+                if os.path.isfile(os.path.join(abs_root, cfg)):
+                    cmd = ["npm", "run", "dev"] if "dev" in scripts else ["npx", "vite"]
+                    return ProjectInfo(kind="vite", label="Vite", root=abs_root, start_command=cmd, is_framework=True)
+            if "vite" in deps and "dev" in scripts:
+                return ProjectInfo(kind="vite", label="Vite", root=abs_root, start_command=["npm", "run", "dev"], is_framework=True)
+
+            # Next.js detection
+            for cfg in ("next.config.js", "next.config.ts", "next.config.mjs", "next.config.cjs"):
+                if os.path.isfile(os.path.join(abs_root, cfg)):
+                    cmd = ["npm", "run", "dev"] if "dev" in scripts else ["npx", "next", "dev"]
+                    return ProjectInfo(kind="next", label="Next.js", root=abs_root, start_command=cmd, is_framework=True)
+            if "next" in deps and "dev" in scripts:
+                return ProjectInfo(kind="next", label="Next.js", root=abs_root, start_command=["npm", "run", "dev"], is_framework=True)
+
+            # Create React App detection
+            if "react-scripts" in deps:
+                cmd = ["npm", "start"]
+                return ProjectInfo(kind="cra", label="Create React App", root=abs_root, start_command=cmd, is_framework=True)
+
+            # Generic Node dev script
+            if "dev" in scripts:
+                return ProjectInfo(kind="node", label="Node Dev", root=abs_root, start_command=["npm", "run", "dev"], is_framework=True)
+            if "start" in scripts:
+                return ProjectInfo(kind="node", label="Node Start", root=abs_root, start_command=["npm", "start"], is_framework=True)
+        except Exception:
+            pass
+
+    # Static project fallback
+    index_file = None
+    for cand in ("index.html", "index.htm", "main.html", "app.html"):
+        p = os.path.join(abs_root, cand)
+        if os.path.isfile(p):
+            index_file = p
+            break
+    return ProjectInfo(kind="static", label="Static Web", root=abs_root, entry_file=index_file)
+
+
+def is_port_available(port: int, host: str = "127.0.0.1") -> bool:
+    """Check if a port is free to bind on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host, port))
+            return True
+        except OSError:
+            return False
+
+
+def find_available_port(preferred: int = 5173, fallback_ports: Optional[List[int]] = None) -> int:
+    """Find an available port starting with preferred, then fallbacks, then dynamic bind."""
+    if is_port_available(preferred):
+        return preferred
+    fallbacks = fallback_ports or [5174, 5175, 5176, 3000, 3001, 8080, 8000]
+    for p in fallbacks:
+        if is_port_available(p):
+            return p
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class DevServerManager:
+    """Manages local dev server instances with zero duplicate processes and clean lifecycle."""
+
+    _active_servers: Dict[str, DevServerManager] = {}
+    _lock = threading.RLock()
+
+    @classmethod
+    def get_or_create(cls, root: str) -> DevServerManager:
+        """Get running server for workspace root or create a new manager."""
+        norm_root = os.path.abspath(os.path.expanduser(root or ""))
+        with cls._lock:
+            if norm_root in cls._active_servers:
+                return cls._active_servers[norm_root]
+            mgr = cls(norm_root)
+            cls._active_servers[norm_root] = mgr
+            return mgr
+
+    @classmethod
+    def cleanup_all(cls) -> None:
+        """Terminate and clean up all running development servers across CAT."""
+        with cls._lock:
+            for mgr in list(cls._active_servers.values()):
+                try:
+                    mgr.stop()
+                except Exception:
+                    pass
+            cls._active_servers.clear()
+
+    def __init__(self, root: str) -> None:
+        self.root = os.path.abspath(os.path.expanduser(root or ""))
+        self.project_info = detect_project_type(self.root)
+        self.state = ServerState.STOPPED
+        self.port: Optional[int] = None
+        self.url: Optional[str] = None
+        self.last_error: str = ""
+        self._server_instance: Any = None  # LiveServer instance or subprocess.Popen
+        self._proc: Optional[subprocess.Popen] = None
+        self._logs: List[str] = []
+        self._on_state_change: Optional[Callable[[str, str], None]] = None
+
+    def set_state_listener(self, cb: Callable[[str, str], None]) -> None:
+        self._on_state_change = cb
+
+    def _notify(self, state: str, error: str = "") -> None:
+        self.state = state
+        if error:
+            self.last_error = error
+        if self._on_state_change:
+            try:
+                self._on_state_change(state, error)
+            except Exception:
+                pass
+
+    def is_running(self) -> bool:
+        if self.state != ServerState.RUNNING:
+            return False
+        if self._proc is not None:
+            return self._proc.poll() is None
+        if self._server_instance is not None:
+            return getattr(self._server_instance, "running", False)
+        return False
+
+    def start(self, preferred_port: Optional[int] = None) -> Tuple[bool, str]:
+        """Start the local development server for this project."""
+        if self.is_running():
+            return True, self.url or f"http://127.0.0.1:{self.port}/"
+
+        self._notify(ServerState.STARTING)
+        self.project_info = detect_project_type(self.root)
+
+        if not self.project_info.is_framework:
+            return self._start_static(preferred_port)
+        else:
+            return self._start_framework(preferred_port)
+
+    def _start_static(self, preferred_port: Optional[int] = None) -> Tuple[bool, str]:
+        """Start CAT's internal LiveServer with hot-reload."""
+        try:
+            from ..browser.server import LiveServer
+            self.port = find_available_port(preferred_port or 5173)
+            # Create LiveServer bound to root
+            srv = LiveServer(self.root)
+            srv.port = self.port
+            started = srv.start()
+            if not started:
+                self._notify(ServerState.ERROR, f"Port {self.port} could not be bound.")
+                return False, self.last_error
+
+            self._server_instance = srv
+            self.port = srv.port
+            self.url = f"http://127.0.0.1:{self.port}/"
+            self._notify(ServerState.RUNNING)
+            self._logs.append(f"Static dev server started at {self.url}")
+            return True, self.url
+        except Exception as e:
+            err = f"Failed to start static server: {e}"
+            self._notify(ServerState.ERROR, err)
+            return False, err
+
+    def _start_framework(self, preferred_port: Optional[int] = None) -> Tuple[bool, str]:
+        """Launch project's own dev server (e.g. Vite, Next.js)."""
+        cmd = self.project_info.start_command
+        if not cmd:
+            return self._start_static(preferred_port)
+
+        self.port = find_available_port(preferred_port or 5173)
+        try:
+            # Launch dev process safely
+            env = os.environ.copy()
+            env["PORT"] = str(self.port)
+            self._proc = subprocess.Popen(
+                cmd,
+                cwd=self.root,
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1,
+            )
+
+            # Monitor startup in background thread
+            def _reader():
+                while self._proc and self._proc.poll() is None:
+                    line = self._proc.stdout.readline()
+                    if line:
+                        self._logs.append(line.rstrip())
+                        if len(self._logs) > 500:
+                            del self._logs[:-500]
+
+            t = threading.Thread(target=_reader, daemon=True)
+            t.start()
+
+            # Wait briefly for process to initialize or report url
+            start_time = time.monotonic()
+            while time.monotonic() - start_time < 5.0:
+                if self._proc.poll() is not None:
+                    err = "\n".join(self._logs[-10:]) or "Process exited prematurely."
+                    self._notify(ServerState.ERROR, err)
+                    return False, err
+                if not is_port_available(self.port):
+                    # Port is now bound by dev server!
+                    break
+                time.sleep(0.2)
+
+            self.url = f"http://127.0.0.1:{self.port}/"
+            self._notify(ServerState.RUNNING)
+            return True, self.url
+        except Exception as e:
+            err = f"Failed to spawn dev command {cmd}: {e}"
+            self._notify(ServerState.ERROR, err)
+            return False, err
+
+    def stop(self) -> None:
+        """Cleanly stop the running development server."""
+        if self._server_instance is not None:
+            try:
+                self._server_instance.shutdown()
+            except Exception:
+                pass
+            self._server_instance = None
+
+        if self._proc is not None:
+            try:
+                self._proc.terminate()
+                self._proc.wait(timeout=2.0)
+            except Exception:
+                try:
+                    self._proc.kill()
+                except Exception:
+                    pass
+            self._proc = None
+
+        self._notify(ServerState.STOPPED)
+
+    def restart(self) -> Tuple[bool, str]:
+        """Restart the running server."""
+        self._notify(ServerState.RESTARTING)
+        self.stop()
+        time.sleep(0.3)
+        return self.start(self.port)
+
+    def get_logs(self, limit: int = 50) -> List[str]:
+        """Return latest captured stdout/stderr lines."""
+        return list(self._logs[-limit:])

calc_terminal/preview/diagnostics.py

@@ -0,0 +1,131 @@
+"""CAT Live Preview — Diagnostics & Error Mapping (calc_terminal/preview/diagnostics.py).
+
+Unified diagnostic model and error navigation:
+- Normalizes errors from browser runtime, dev server, build, and editor.
+- Extracts file, line, and column coordinates from error messages.
+- Supports jumping from Problems/Console errors directly into the source code.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import uuid
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass
+class SourceLocation:
+    """Exact source code target of a diagnostic error."""
+    file: str
+    line: Optional[int] = None
+    column: Optional[int] = None
+
+
+@dataclass
+class Diagnostic:
+    """Normalized diagnostic entry across browser, server, build, and editor."""
+    id: str
+    severity: str  # "info", "warning", "error"
+    message: str
+    file: Optional[str] = None
+    line: Optional[int] = None
+    column: Optional[int] = None
+    source: str = "editor"  # "browser", "server", "build", "editor"
+    timestamp: float = 0.0
+
+
+# Regex patterns to detect file:line:col in runtime and build errors
+# e.g., main.js:42:17, ./src/App.tsx (12:5), File "app.py", line 123
+_LOCATION_PATTERNS = [
+    re.compile(r'([a-zA-Z0-9_\-\.\/\\]+\.(?:js|jsx|ts|tsx|py|html|css)):(\d+):(\d+)'),
+    re.compile(r'([a-zA-Z0-9_\-\.\/\\]+\.(?:js|jsx|ts|tsx|py|html|css)):(\d+)'),
+    re.compile(r'File "([^"]+)", line (\d+)'),
+    re.compile(r'([a-zA-Z0-9_\-\.\/\\]+\.(?:js|jsx|ts|tsx|py|html|css))\s*\((\d+):(\d+)\)'),
+]
+
+
+def parse_error_location(error_text: str, workspace_root: Optional[str] = None) -> Optional[SourceLocation]:
+    """Extract source file, line, and column from an error string."""
+    if not error_text:
+        return None
+    for pattern in _LOCATION_PATTERNS:
+        match = pattern.search(error_text)
+        if match:
+            groups = match.groups()
+            raw_path = groups[0]
+            line = int(groups[1]) if len(groups) > 1 and groups[1] else None
+            col = int(groups[2]) if len(groups) > 2 and groups[2] else None
+
+            # Resolve relative paths against workspace root if provided
+            abs_path = raw_path
+            if workspace_root and not os.path.isabs(raw_path):
+                cand = os.path.join(workspace_root, raw_path)
+                if os.path.exists(cand):
+                    abs_path = os.path.abspath(cand)
+
+            return SourceLocation(file=abs_path, line=line, column=col)
+    return None
+
+
+class DiagnosticsManager:
+    """Collects and organizes diagnostics from all runtime and build systems."""
+
+    def __init__(self) -> None:
+        self._diagnostics: List[Diagnostic] = []
+
+    def add(self, severity: str, message: str, file: Optional[str] = None,
+            line: Optional[int] = None, column: Optional[int] = None,
+            source: str = "editor") -> Diagnostic:
+        """Add a new diagnostic item."""
+        # Auto-parse location if not explicitly provided
+        if not file or line is None:
+            loc = parse_error_location(message)
+            if loc:
+                file = file or loc.file
+                line = line if line is not None else loc.line
+                column = column if column is not None else loc.column
+
+        diag = Diagnostic(
+            id=uuid.uuid4().hex[:8],
+            severity=severity.lower(),
+            message=message.strip(),
+            file=file,
+            line=line,
+            column=column,
+            source=source,
+            timestamp=__import__("time").time(),
+        )
+        self._diagnostics.append(diag)
+        if len(self._diagnostics) > 200:
+            del self._diagnostics[:-200]
+        return diag
+
+    def list_diagnostics(self, severity: Optional[str] = None, source: Optional[str] = None) -> List[Diagnostic]:
+        """Return matching diagnostics filtered by severity and/or source."""
+        results = list(self._diagnostics)
+        if severity:
+            results = [d for d in results if d.severity == severity.lower()]
+        if source:
+            results = [d for d in results if d.source == source.lower()]
+        return results
+
+    def clear(self, source: Optional[str] = None) -> None:
+        """Clear diagnostics, optionally for a specific source."""
+        if source:
+            self._diagnostics = [d for d in self._diagnostics if d.source != source.lower()]
+        else:
+            self._diagnostics.clear()
+
+
+# Global diagnostics singleton
+_GLOBAL_DIAGNOSTICS_MANAGER: Optional[DiagnosticsManager] = None
+
+
+def get_diagnostics_manager() -> DiagnosticsManager:
+    """Return global DiagnosticsManager singleton."""
+    global _GLOBAL_DIAGNOSTICS_MANAGER
+    if _GLOBAL_DIAGNOSTICS_MANAGER is None:
+        _GLOBAL_DIAGNOSTICS_MANAGER = DiagnosticsManager()
+    return _GLOBAL_DIAGNOSTICS_MANAGER

calc_terminal/preview/live_reload.py

@@ -0,0 +1,66 @@
+"""CAT Live Preview — Live Reload Manager (calc_terminal/preview/live_reload.py).
+
+Debounced change aggregation and hot-reload dispatcher for local web projects.
+Avoids restarting dev servers on ordinary keystrokes / edits.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from typing import Callable, List, Optional, Set
+
+
+class LiveReloadManager:
+    """Aggregates file modification events and emits debounced reload requests."""
+
+    def __init__(self, debounce_sec: float = 0.25, on_reload: Optional[Callable[[List[str], bool], None]] = None) -> None:
+        self.debounce_sec = debounce_sec
+        self.on_reload = on_reload  # (changed_files, is_css_only) -> None
+        self._pending_files: Set[str] = set()
+        self._timer: Optional[threading.Timer] = None
+        self._lock = threading.Lock()
+        self._last_reload_time: float = 0.0
+
+    def notify_file_changed(self, file_path: str) -> None:
+        """Register that a file in the workspace was saved or edited."""
+        abs_path = os.path.abspath(file_path)
+        with self._lock:
+            self._pending_files.add(abs_path)
+            if self._timer is not None:
+                self._timer.cancel()
+            self._timer = threading.Timer(self.debounce_sec, self._flush)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def _flush(self) -> None:
+        """Process pending changes and invoke reload callback."""
+        with self._lock:
+            if not self._pending_files:
+                return
+            files = list(self._pending_files)
+            self._pending_files.clear()
+            self._timer = None
+
+        # Ignore if reloaded too frequently (avoid reload loops)
+        now = time.monotonic()
+        if now - self._last_reload_time < 0.1:
+            return
+        self._last_reload_time = now
+
+        # Determine if CSS only
+        is_css_only = all(f.lower().endswith(".css") for f in files)
+        if self.on_reload:
+            try:
+                self.on_reload(files, is_css_only)
+            except Exception:
+                pass
+
+    def cancel(self) -> None:
+        """Cancel any pending debounce timer."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            self._pending_files.clear()

calc_terminal/preview/manager.py

@@ -0,0 +1,129 @@
+"""CAT Live Preview — Preview Manager (calc_terminal/preview/manager.py).
+
+High-level session coordinator according to Preview API contract:
+- start(), stop(), restart(), reload(), get(), get_active().
+- Coordinates between DevServerManager, LiveReloadManager, and UI.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from .dev_server import DevServerManager, ServerState
+
+
+@dataclass
+class PreviewSession:
+    """Represents an active preview session for a project."""
+    id: str
+    project_path: str
+    url: str
+    port: int
+    status: str
+    framework: Optional[str] = None
+    created_at: float = 0.0
+
+
+class PreviewManager:
+    """Manages active preview sessions across CAT IDE."""
+
+    def __init__(self) -> None:
+        self._sessions: Dict[str, PreviewSession] = {}
+        self._path_to_session_id: Dict[str, str] = {}
+
+    def start(self, project_path: str, options: Optional[dict] = None) -> PreviewSession:
+        """Start or reuse an existing preview session for a project path."""
+        norm_path = DevServerManager(project_path).root
+        existing = self.get_active(norm_path)
+        if existing and existing.status == ServerState.RUNNING:
+            return existing
+
+        dev_mgr = DevServerManager.get_or_create(norm_path)
+        ok, url = dev_mgr.start()
+        session_id = self._path_to_session_id.get(norm_path) or uuid.uuid4().hex
+
+        status = dev_mgr.state
+        port = dev_mgr.port or 5173
+        framework = dev_mgr.project_info.kind if dev_mgr.project_info.is_framework else None
+
+        session = PreviewSession(
+            id=session_id,
+            project_path=norm_path,
+            url=url if ok else "",
+            port=port,
+            status=status,
+            framework=framework,
+            created_at=time.time(),
+        )
+        self._sessions[session_id] = session
+        self._path_to_session_id[norm_path] = session_id
+        return session
+
+    def stop(self, session_id: str) -> None:
+        """Stop a preview session."""
+        session = self.get(session_id)
+        if session:
+            dev_mgr = DevServerManager.get_or_create(session.project_path)
+            dev_mgr.stop()
+            session.status = ServerState.STOPPED
+
+    def restart(self, session_id: str) -> Optional[PreviewSession]:
+        """Restart a preview session."""
+        session = self.get(session_id)
+        if not session:
+            return None
+        dev_mgr = DevServerManager.get_or_create(session.project_path)
+        ok, url = dev_mgr.restart()
+        session.status = dev_mgr.state
+        session.url = url
+        return session
+
+    def reload(self, session_id: str) -> bool:
+        """Trigger reload of the active preview."""
+        session = self.get(session_id)
+        if not session:
+            return False
+        # Notify connected preview clients through LiveServer ws channel if static
+        dev_mgr = DevServerManager.get_or_create(session.project_path)
+        if dev_mgr._server_instance is not None and hasattr(dev_mgr._server_instance, "broadcast"):
+            try:
+                dev_mgr._server_instance.broadcast({"cmd": "reload"})
+                return True
+            except Exception:
+                pass
+        return False
+
+    def get(self, session_id: str) -> Optional[PreviewSession]:
+        """Look up a preview session by its ID."""
+        return self._sessions.get(session_id)
+
+    def get_active(self, project_path: str) -> Optional[PreviewSession]:
+        """Return the active preview session for a project path if any exists."""
+        norm_path = DevServerManager(project_path).root
+        sid = self._path_to_session_id.get(norm_path)
+        if sid:
+            return self._sessions.get(sid)
+        return None
+
+    def cleanup_all(self) -> None:
+        """Clean up all active preview sessions and dev servers."""
+        for sid in list(self._sessions.keys()):
+            self.stop(sid)
+        self._sessions.clear()
+        self._path_to_session_id.clear()
+        DevServerManager.cleanup_all()
+
+
+# Global preview manager singleton
+_GLOBAL_PREVIEW_MANAGER: Optional[PreviewManager] = None
+
+
+def get_preview_manager() -> PreviewManager:
+    """Return the global PreviewManager singleton."""
+    global _GLOBAL_PREVIEW_MANAGER
+    if _GLOBAL_PREVIEW_MANAGER is None:
+        _GLOBAL_PREVIEW_MANAGER = PreviewManager()
+    return _GLOBAL_PREVIEW_MANAGER