zerochat 9.8.0__tar.gz → 9.10.0__tar.gz

{zerochat-9.8.0/zerochat.egg-info → zerochat-9.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zerochat
-Version: 9.8.0
+Version: 9.10.0
 Summary: Private local web client for AI models, tools and MCP services
 Author: Alberto Alday
 License-Expression: MIT

{zerochat-9.8.0 → zerochat-9.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zerochat"
-version = "9.8.0"
+version = "9.10.0"
 description = "Private local web client for AI models, tools and MCP services"
 readme = "README.md"
 requires-python = ">=3.10"

{zerochat-9.8.0 → zerochat-9.10.0/zerochat.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zerochat
-Version: 9.8.0
+Version: 9.10.0
 Summary: Private local web client for AI models, tools and MCP services
 Author: Alberto Alday
 License-Expression: MIT

{zerochat-9.8.0 → zerochat-9.10.0}/zerochat.py

@@ -46,7 +46,7 @@ import zlib
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 
-SOURCE_BACKEND_VERSION = "9.8.0"
+SOURCE_BACKEND_VERSION = "9.10.0"
 
 def _read_source_version(filename: str) -> str | None:
     """Lee la versión de un archivo del repositorio cuando se ejecuta desde fuentes."""
@@ -316,7 +316,7 @@ ACTIVE_HOST = DEFAULT_HOST
 # Kept only for this Python process: binds an approved browser tool call to
 # the exact JSON-RPC bytes sent to the local host.
 TOOL_AUTH_VERSION = "zerochat-tool-auth-v1"
-TOOL_AUTH_TTL_MS = 30_000
+TOOL_AUTH_TTL_MS = 60_000
 TOOL_AUTH_MAX_NONCES = 10_000
 TOOL_AUTH_KEY = secrets.token_bytes(32)
 TOOL_AUTH_SESSION_ID = secrets.token_urlsafe(18)
@@ -1344,6 +1344,92 @@ def set_project_directory(path) -> dict:
     return {"cwd": str(target), "previous_cwd": previous}
 
 
+# Visores gráficos que `git difftool` ya sabe lanzar, en orden de preferencia, con el ejecutable que los delata.
+GUI_DIFF_TOOLS = {"vscode": "code", "meld": "meld", "kdiff3": "kdiff3", "kompare": "kompare", "gvimdiff": "gvim"}
+# Respaldo cuando no hay ninguno: visor web que se instala en el entorno aislado de ZeroChat.
+WEBDIFF_REQUIREMENT = "webdiff==1.4.0"
+WEBDIFF_INSTALL_TIMEOUT_SECONDS = 120
+
+
+def _venv_webdiff() -> Path:
+    """Ruta de webdiff dentro de ~/zerochat/.venv, junto al intérprete del entorno."""
+    venv_python = get_venv_python(get_venv_dir())
+    return venv_python.with_name("webdiff" + venv_python.suffix)
+
+
+def _find_webdiff() -> str:
+    """webdiff del entorno de ZeroChat o, si no, del PATH; '' si no hay ninguno."""
+    venv_webdiff = _venv_webdiff()
+    if venv_webdiff.exists():
+        return str(venv_webdiff)
+    return shutil.which("webdiff") or ""
+
+
+def _diff_tool_settings(tool: str, webdiff_bin: str) -> list:
+    """Pares (clave, valor) de git config que deja `tool` como visor gráfico; webdiff no es un visor integrado de git."""
+    settings = [("diff.guitool", tool)]
+    if tool == "webdiff":
+        settings.insert(0, ("difftool.webdiff.cmd", f'"{webdiff_bin}" "$LOCAL" "$REMOTE"'))
+    return settings
+
+
+def detect_gui_diff_tool() -> dict:
+    """Visor que proponer cuando Git no tiene ninguno: el primero instalado o, si no hay, webdiff.
+
+    Incluye las órdenes exactas que aplicará configure_gui_diff_tool, para mostrarlas antes de confirmar.
+    """
+    tool = next((name for name, binary in GUI_DIFF_TOOLS.items() if shutil.which(binary)), "webdiff")
+    webdiff_bin = _find_webdiff()
+    return {
+        "tool": tool,
+        "install": tool == "webdiff" and not webdiff_bin,
+        "commands": [
+            shlex.join(["git", "config", "--global", key, value])
+            for key, value in _diff_tool_settings(tool, webdiff_bin or str(_venv_webdiff()))
+        ],
+    }
+
+
+def _install_webdiff() -> str:
+    """Instala webdiff en ~/zerochat/.venv y devuelve la ruta del ejecutable."""
+    ensure_virtual_environment()
+    venv_python = get_venv_python(get_venv_dir())
+    if not venv_python.exists():
+        raise RuntimeError(f"No se pudo preparar el entorno virtual de ZeroChat: falta {venv_python}")
+    res = subprocess.run(
+        [str(venv_python), "-m", "pip", "install", WEBDIFF_REQUIREMENT],
+        capture_output=True,
+        text=True,
+        timeout=WEBDIFF_INSTALL_TIMEOUT_SECONDS,
+        check=False
+    )
+    if res.returncode != 0:
+        raise RuntimeError(f"Error instalando webdiff: {(res.stderr or res.stdout).strip()[-500:]}")
+    webdiff = _venv_webdiff()
+    if not webdiff.exists():
+        raise RuntimeError(f"webdiff se instaló pero no aparece en {webdiff}")
+    return str(webdiff)
+
+
+def configure_gui_diff_tool(tool) -> dict:
+    """Deja `tool` como visor gráfico global de Git, instalando antes webdiff si es el elegido y falta."""
+    if not isinstance(tool, str) or (tool != "webdiff" and tool not in GUI_DIFF_TOOLS):
+        raise ValueError(f"Visor de diffs '{tool}' no reconocido.")
+    git_bin = shutil.which("git")
+    if not git_bin:
+        raise RuntimeError("Git no está instalado o no se encuentra en el PATH del sistema.")
+
+    webdiff_bin = ""
+    if tool == "webdiff":
+        webdiff_bin = _find_webdiff() or _install_webdiff()
+    elif not shutil.which(GUI_DIFF_TOOLS[tool]):
+        raise ValueError(f"'{GUI_DIFF_TOOLS[tool]}' no está en el PATH del sistema.")
+
+    for key, value in _diff_tool_settings(tool, webdiff_bin):
+        subprocess.run([git_bin, "config", "--global", key, value], capture_output=True, timeout=5, check=True)
+    return {"tool": tool}
+
+
 def _configured_gui_diff_tool(git_bin: str, repo_root: Path) -> str:
     """Herramienta gráfica que usaría `git difftool --gui`, o '' si no hay ninguna configurada.
 
@@ -1365,7 +1451,10 @@ def _configured_gui_diff_tool(git_bin: str, repo_root: Path) -> str:
 
 
 def open_file_diff(path: str, commit_fallback: bool = False) -> dict:
-    """Abre un visor externo de diffs (git difftool) para comparar el fichero actual frente a Git HEAD, su último commit o fichero vacío."""
+    """Abre un visor externo de diffs (git difftool) para comparar el fichero actual frente a Git HEAD, su último commit o fichero vacío.
+
+    Sin visor gráfico configurado no lanza nada y devuelve en `setup` el que propone configurar.
+    """
     if not isinstance(path, str) or not path.strip():
         raise ValueError("La ruta del archivo está vacía.")
     if len(path) > MAX_PATH_LENGTH:
@@ -1398,10 +1487,7 @@ def open_file_diff(path: str, commit_fallback: bool = False) -> dict:
 
     repo_root = Path(res.stdout.strip()).resolve()
     if not _configured_gui_diff_tool(git_bin, repo_root):
-        raise ValueError(
-            "No hay un visor gráfico de diffs configurado en Git. Configura uno, por ejemplo: "
-            "git config --global diff.guitool meld"
-        )
+        return {"success": False, "setup": detect_gui_diff_tool()}
 
     has_head = subprocess.run(
         [git_bin, "rev-parse", "--verify", "HEAD"],
@@ -2218,18 +2304,22 @@ def playwright_launch_env(config: dict) -> dict[str, str]:
 
 
 def validate_profile_browser(raw) -> dict:
-    """Navegador que exige un perfil: el propio con un motor o el del usuario con uno de sus navegadores."""
-    if isinstance(raw, dict) and raw.get("mode") == "own" and set(raw) == {"mode", "engine"} and raw["engine"] in OWN_BROWSER_ENGINES:
-        return {"mode": "own", "engine": raw["engine"]}
+    """Navegador que exige un perfil: el propio con un motor, y headless False si exige la ventana
+    visible, o el del usuario con uno de sus navegadores."""
+    if isinstance(raw, dict) and raw.get("mode") == "own" and raw.get("engine") in OWN_BROWSER_ENGINES:
+        if set(raw) == {"mode", "engine"}:
+            return {"mode": "own", "engine": raw["engine"]}
+        if set(raw) == {"mode", "engine", "headless"} and raw["headless"] is False:
+            return {"mode": "own", "engine": raw["engine"], "headless": False}
     if isinstance(raw, dict) and raw.get("mode") == "user" and set(raw) == {"mode", "userBrowser"} and raw["userBrowser"] in USER_BROWSERS:
         return {"mode": "user", "userBrowser": raw["userBrowser"]}
-    raise ValueError("browser debe ser {mode: own, engine} o {mode: user, userBrowser} con un motor o navegador admitido")
+    raise ValueError("browser debe ser {mode: own, engine[, headless: false]} o {mode: user, userBrowser} con un motor o navegador admitido")
 
 
 def browser_choice(config: dict) -> dict:
     """Modo y navegador con los que arranca Playwright MCP, en la forma de validate_profile_browser."""
     if config["mode"] == "own":
-        return {"mode": "own", "engine": config["engine"]}
+        return {"mode": "own", "engine": config["engine"], **({} if config["headless"] else {"headless": False})}
     return {"mode": "user", "userBrowser": config["userBrowser"]}
 
 
@@ -3774,6 +3864,13 @@ class ZeroChatServerHandler(BaseHTTPRequestHandler):
                 return None, {"code": -32602, "message": str(exc)}, ""
             except Exception as exc:
                 return None, {"code": -32603, "message": f"Error al abrir el visor de diffs: {exc}"}, str(exc)
+        if method == "zerochat/diff/configure":
+            try:
+                return configure_gui_diff_tool(params.get("tool")), None, ""
+            except (ValueError, RuntimeError) as exc:
+                return None, {"code": -32602, "message": str(exc)}, ""
+            except Exception as exc:
+                return None, {"code": -32603, "message": f"Error configurando el visor de diffs: {exc}"}, str(exc)
         if method == "zerochat/web/fetch":
             try:
                 return fetch_web_resource(params), None, ""
@@ -4356,10 +4453,8 @@ class ZeroChatArgumentParser(argparse.ArgumentParser):
         self.exit(RUN_EXIT_ARGS, f"{self.prog}: error: {message}\n")
 
 
-def main():
-    global ACTIVE_PORT, ACTIVE_HOST, SESSION_TOKEN, CONSOLE_CONTROL, EXIT_ON_CLOSE
-    global TOOL_AUTH_KEY, TOOL_AUTH_SESSION_ID, TOOL_AUTH_NONCES, RUN_SESSION
-
+def build_parser() -> ZeroChatArgumentParser:
+    """Opciones de la línea de órdenes."""
     parser = ZeroChatArgumentParser(description=f"ZeroChat Local Server v{VERSION}")
     # Desde Python 3.14 argparse colorea la ayuda con códigos ANSI; la consola la muestra en texto plano.
     parser.color = False
@@ -4367,6 +4462,7 @@ def main():
     parser.add_argument("--host", default=os.environ.get("ZEROCHAT_HOST", DEFAULT_HOST), help=f"Host de escucha (default: {DEFAULT_HOST})")
     parser.add_argument("--ui-url", default=None, help="URL de la interfaz web a abrir (por defecto: interfaz local en desarrollo o GitHub Pages)")
     parser.add_argument("--no-browser", action="store_true", help="No abrir automáticamente el navegador")
+    parser.add_argument("--print-url", action="store_true", help="Imprimir la URL de la interfaz con el token, entre líneas en blanco para copiarla (implica --no-browser)")
     parser.add_argument("--keep-server", action="store_true", help="Servidor: seguir en marcha al cerrar el navegador (no se combina con --prompt)")
     parser.add_argument("--no-venv", action="store_true", help="Omitir la comprobación/creación de ~/zerochat/.venv")
     parser.add_argument("--test", action="store_true", help="Ejecutar autocomprobación interna de herramientas")
@@ -4378,76 +4474,79 @@ def main():
     parser.add_argument("--allow-dangerous-tools", action="store_true", help="Con --prompt, aprobar también las herramientas que escriben o ejecutan (write_file, edit_file, run_command); las demás se aprueban siempre para la sesión")
     parser.add_argument("--headless", action="store_true", help="Con --prompt, abrir el navegador predeterminado sin ventana (si ya está abierto puede verse la pestaña)")
     parser.add_argument("--version", action="version", version=f"ZeroChat {VERSION}")
-    args = parser.parse_args()
+    return parser
 
-    # Los avisos no persisten entre ejecuciones del servidor.
-    reset_notices()
 
-    # Modo ejecución: stdout queda solo para la respuesta final; todo el registro va a stderr.
+def run_session_from_args(parser: ZeroChatArgumentParser, args) -> RunSession | None:
+    """Valida las combinaciones de opciones y devuelve la sesión de --prompt, si la hay."""
+    # Quien pide la URL la abrirá en otro sitio (otro equipo, un túnel SSH): no se abre el navegador local.
+    if args.print_url and args.prompt is None:
+        args.no_browser = True
+    if args.prompt is None:
+        if args.headless or args.keep_page or args.allow_dangerous_tools or args.profile is not None or args.export is not None:
+            parser.error("--headless, --keep-page, --allow-dangerous-tools, --profile y --export solo se usan con --prompt")
+        return None
+    if not args.prompt.strip():
+        parser.error("el prompt está vacío")
+    if args.no_browser or args.print_url:
+        parser.error("--prompt necesita abrir el navegador: no se combina con --no-browser ni con --print-url")
+    if args.keep_server:
+        parser.error("--prompt termina al devolver el resultado: no se combina con --keep-server (para no cerrar la página, --keep-page)")
+    if args.profile is not None and not args.profile.strip():
+        parser.error("--profile no puede estar vacío")
+    if args.keep_page and args.headless:
+        parser.error("--keep-page necesita la ventana del navegador: no se combina con --headless")
+    export_path = None
+    if args.export is not None:
+        export_path = Path(args.export).expanduser().absolute()
+        if export_path.suffix.lower() not in RUN_EXPORT_FORMATS:
+            parser.error(f"--export necesita una de estas extensiones: {', '.join(RUN_EXPORT_FORMATS)}")
+        if not export_path.parent.is_dir():
+            parser.error(f"--export: no existe el directorio {export_path.parent}")
+    return RunSession(args.prompt.strip(), args.profile.strip() if args.profile else None, export_path, args.keep_page, args.allow_dangerous_tools)
+
+
+def redirect_log(args):
+    """Todo el registro pasa por stdout: con --prompt va a stderr para dejar stdout a la respuesta,
+    y con --log off se descarta. Devuelve el stdout original, el de la respuesta."""
     result_out = sys.stdout
-    if args.prompt is None and (args.headless or args.keep_page or args.allow_dangerous_tools or args.profile is not None or args.export is not None):
-        parser.error("--headless, --keep-page, --allow-dangerous-tools, --profile y --export solo se usan con --prompt")
-    if args.prompt is not None:
-        if not args.prompt.strip():
-            parser.error("el prompt está vacío")
-        if args.no_browser:
-            parser.error("--prompt necesita abrir el navegador: no se combina con --no-browser")
-        if args.keep_server:
-            parser.error("--prompt termina al devolver el resultado: no se combina con --keep-server (para no cerrar la página, --keep-page)")
-        if args.profile is not None and not args.profile.strip():
-            parser.error("--profile no puede estar vacío")
-        if args.keep_page and args.headless:
-            parser.error("--keep-page necesita la ventana del navegador: no se combina con --headless")
-        export_path = None
-        if args.export is not None:
-            export_path = Path(args.export).expanduser().absolute()
-            if export_path.suffix.lower() not in RUN_EXPORT_FORMATS:
-                parser.error(f"--export necesita una de estas extensiones: {', '.join(RUN_EXPORT_FORMATS)}")
-            if not export_path.parent.is_dir():
-                parser.error(f"--export: no existe el directorio {export_path.parent}")
-        RUN_SESSION = RunSession(args.prompt.strip(), args.profile.strip() if args.profile else None, export_path, args.keep_page, args.allow_dangerous_tools)
-    # Todo el registro pasa por stdout: con --prompt va a stderr para dejar stdout a la respuesta,
-    # y con --log off se descarta.
     log_enabled = args.log == "on" if args.log else RUN_SESSION is None
     if not log_enabled:
         sys.stdout = open(os.devnull, "w", encoding="utf-8")
     elif RUN_SESSION:
         sys.stdout = sys.stderr
+    return result_out
 
-    if args.test:
-        print(timestamp_message(f"TEST list_directory {'ok' if json.loads(list_directory('.'))['success'] else 'error'}"))
-        print(timestamp_message(f"TEST read_file {'ok' if json.loads(read_file('package.json', max_lines=5))['success'] else 'error'}"))
-        print(timestamp_message(f"TEST run_command {'ok' if json.loads(run_command('echo hello'))['success'] else 'error'}"))
-        print(timestamp_message("TEST all local tools ready."))
-        return
 
+def run_self_test():
+    """--test: comprueba las herramientas locales básicas sin arrancar el servidor."""
+    print(timestamp_message(f"TEST list_directory {'ok' if json.loads(list_directory('.'))['success'] else 'error'}"))
+    print(timestamp_message(f"TEST read_file {'ok' if json.loads(read_file('package.json', max_lines=5))['success'] else 'error'}"))
+    print(timestamp_message(f"TEST run_command {'ok' if json.loads(run_command('echo hello'))['success'] else 'error'}"))
+    print(timestamp_message("TEST all local tools ready."))
+
+
+def prepare_environment(args, is_dev: bool):
+    """Limpia restos de una sesión anterior, prepara el entorno MCP y lanza las comprobaciones de fondo."""
     orphans = cleanup_orphan_jobs()
     if orphans:
         print(timestamp_message(f"Detenidos {orphans} comando(s) que seguían en marcha de una sesión anterior interrumpida."))
-
-    # 1. Asegurar el entorno MCP aislado en ambos modos de distribución.
+    # Entorno MCP aislado en ambos modos de distribución.
     if not args.no_venv:
         ensure_virtual_environment()
-
-    browser_availability = browser_action_availability()
-    if not browser_availability.get("available"):
+    if not browser_action_availability().get("available"):
         add_notice(
             "browser_action desactivada: para usarla, inicia el servicio 'playwright' en Ajustes → MCP "
             "(se instala solo). Requiere Node.js y disponer de Chrome o Edge en el sistema."
         )
-
-    # 2. Detectar entorno de desarrollo y resolver URL de destino
-    dev_root = get_dev_root()
-    static_root = get_static_root()
-    is_dev = dev_root is not None
-    is_installed = is_installed_runtime()
-
-    # 3. Comprobar versión remota en segundo plano (solo fuera del entorno de desarrollo local)
+    # Versión remota en segundo plano, solo fuera del entorno de desarrollo local.
     if not is_dev:
         threading.Thread(target=check_version, daemon=True).start()
 
-    ACTIVE_PORT = args.port if args.port is not None else int(os.environ.get("ZEROCHAT_PORT", DEFAULT_PORT))
-    ACTIVE_HOST = args.host
+
+def reset_session_credentials():
+    """Carga el token diario y renueva la clave de firma de herramientas."""
+    global SESSION_TOKEN, TOOL_AUTH_KEY, TOOL_AUTH_SESSION_ID, TOOL_AUTH_NONCES
     SESSION_TOKEN = get_daily_token()
     # A restart deliberately invalidates every browser-side signing credential.
     TOOL_AUTH_KEY = secrets.token_bytes(32)
@@ -4455,10 +4554,14 @@ def main():
     with TOOL_AUTH_NONCES_LOCK:
         TOOL_AUTH_NONCES = {}
 
-    # La interfaz local de desarrollo tiene el puerto en su origen: en otro no vería los datos guardados.
-    local_ui = static_root is not None and not args.ui_url
+
+def open_server(args, local_ui: bool) -> ThreadingHTTPServer:
+    """Abre el puerto de escucha; con --prompt, si el puerto por defecto está ocupado, usa uno libre."""
+    global ACTIVE_PORT, ACTIVE_HOST
+    ACTIVE_PORT = args.port if args.port is not None else int(os.environ.get("ZEROCHAT_PORT", DEFAULT_PORT))
+    ACTIVE_HOST = args.host
     try:
-        server = ThreadingHTTPServer((ACTIVE_HOST, ACTIVE_PORT), ZeroChatServerHandler)
+        return ThreadingHTTPServer((ACTIVE_HOST, ACTIVE_PORT), ZeroChatServerHandler)
     except OSError as exc:
         if not RUN_SESSION:
             raise
@@ -4466,42 +4569,42 @@ def main():
             hint = "" if args.port is not None else " (en desarrollo la interfaz local necesita ese puerto: cierra el zerochat que lo usa)"
             run_error(f"No se pudo escuchar en {ACTIVE_HOST}:{ACTIVE_PORT}: {exc}{hint}")
             sys.exit(RUN_EXIT_SETUP)
-        # Otro zerochat (u otro programa) usa el puerto por defecto: la ejecución usa uno libre.
-        try:
-            server = ThreadingHTTPServer((ACTIVE_HOST, 0), ZeroChatServerHandler)
-        except OSError as retry_exc:
-            run_error(f"No se pudo escuchar en {ACTIVE_HOST}: {retry_exc}")
-            sys.exit(RUN_EXIT_SETUP)
-        log_event(f"El puerto {ACTIVE_PORT} está ocupado; la ejecución usa el {server.server_address[1]}.")
-        ACTIVE_PORT = server.server_address[1]
-    exposure_warning = remote_exposure_warning(ACTIVE_HOST)
-    if exposure_warning:
-        add_notice(exposure_warning)
+    # Otro zerochat (u otro programa) usa el puerto por defecto: la ejecución usa uno libre.
+    try:
+        server = ThreadingHTTPServer((ACTIVE_HOST, 0), ZeroChatServerHandler)
+    except OSError as retry_exc:
+        run_error(f"No se pudo escuchar en {ACTIVE_HOST}: {retry_exc}")
+        sys.exit(RUN_EXIT_SETUP)
+    log_event(f"El puerto {ACTIVE_PORT} está ocupado; la ejecución usa el {server.server_address[1]}.")
+    ACTIVE_PORT = server.server_address[1]
+    return server
+
 
+def interface_urls(args, static_root) -> tuple[str, str]:
+    """Devuelve la URL de la interfaz y la de destino, con el token y el servidor en el fragmento."""
     if args.ui_url:
         ui_url = args.ui_url
     elif static_root:
         ui_url = f"http://{ACTIVE_HOST}:{ACTIVE_PORT}/zerochat.html"
     else:
         ui_url = DEFAULT_UI_URL
-
     browser_host = ACTIVE_HOST if ACTIVE_HOST in {"127.0.0.1", "localhost"} else "127.0.0.1"
     fragment = {'token': SESSION_TOKEN, 'host': browser_host, 'port': ACTIVE_PORT}
     if RUN_SESSION:
         fragment['run'] = RUN_SESSION.run_id
-    target_url = f"{ui_url}#{urlencode(fragment)}"
-    # El modo ejecución (que rechaza --keep-server) detecta con el latido que el navegador se cerró sin devolver resultado.
-    exit_on_close = not args.keep_server
-    EXIT_ON_CLOSE = exit_on_close
+    return ui_url, f"{ui_url}#{urlencode(fragment)}"
+
 
+def print_header(dev_root, ui_url: str, exposure_warning: str | None, exit_on_close: bool):
+    """Cabecera del servidor con su configuración (sin el token)."""
     print("=" * 64)
     print(f"  ZeroChat Local Server v{VERSION} (UI {UI_VERSION})")
     print(f"  Directorio de trabajo : {Path.cwd()}")
     print(f"  Datos y MCP           : {get_data_dir()}")
     print(f"  Entorno MCP           : {get_venv_dir()}")
-    if is_dev:
+    if dev_root is not None:
         print(f"  Modo de ejecución     : Desarrollo local ({dev_root})")
-    elif is_installed:
+    elif is_installed_runtime():
         print("  Modo de ejecución     : Paquete PyPI (GitHub Pages)")
     else:
         print("  Modo de ejecución     : Producción (Web universal)")
@@ -4516,31 +4619,43 @@ def main():
         print("  Auto-cierre           : Desactivado")
     print("=" * 64, flush=True)
 
-    headless_browser = None
-    if RUN_SESSION:
-        headless_browser = launch_headless_browser(target_url) if args.headless else None
-        if headless_browser is None and not launch_browser(target_url):
-            run_error("No se pudo abrir el navegador.")
-            server.server_close()
-            sys.stdout = result_out
-            sys.exit(RUN_EXIT_SETUP)
-        if headless_browser is not None:
-            threading.Thread(target=fall_back_when_headless_exits, args=(headless_browser, target_url), daemon=True).start()
-        threading.Thread(target=run_supervisor, args=(server, RUN_SESSION), daemon=True).start()
-    else:
+
+def start_interface(args, parser, server: ThreadingHTTPServer, target_url: str, result_out):
+    """Abre la interfaz: en modo ejecución, con su supervisor; si no, con el control de consola.
+    Devuelve el navegador sin ventana de --headless, si se lanzó."""
+    global CONSOLE_CONTROL
+    if args.print_url:
+        # Líneas en blanco alrededor para seleccionarla y copiarla con facilidad (p. ej. en una consola SSH del móvil).
+        print("\n" * 5 + target_url + "\n" * 5, flush=True)
+    if not RUN_SESSION:
         CONSOLE_CONTROL = ConsoleControl(server, parser, target_url=target_url)
         CONSOLE_CONTROL.start()
         if not args.no_browser:
             launch_browser(target_url)
+        return None
+    headless_browser = launch_headless_browser(target_url) if args.headless else None
+    if headless_browser is None and not launch_browser(target_url):
+        run_error("No se pudo abrir el navegador.")
+        server.server_close()
+        sys.stdout = result_out
+        sys.exit(RUN_EXIT_SETUP)
+    if headless_browser is not None:
+        threading.Thread(target=fall_back_when_headless_exits, args=(headless_browser, target_url), daemon=True).start()
+    threading.Thread(target=run_supervisor, args=(server, RUN_SESSION), daemon=True).start()
+    return headless_browser
+
+
+def start_heartbeat_watchdog(server: ThreadingHTTPServer, require_initial: bool):
+    """Detiene el servidor cuando el navegador deja de enviar latidos."""
+    threading.Thread(
+        target=heartbeat_watchdog,
+        args=(server, DEFAULT_HEARTBEAT_GRACE, DEFAULT_HEARTBEAT_TIMEOUT, require_initial),
+        daemon=True
+    ).start()
 
-    if exit_on_close:
-        require_initial = not args.no_browser
-        threading.Thread(
-            target=heartbeat_watchdog,
-            args=(server, DEFAULT_HEARTBEAT_GRACE, DEFAULT_HEARTBEAT_TIMEOUT, require_initial),
-            daemon=True
-        ).start()
 
+def install_signal_handlers(server: ThreadingHTTPServer):
+    """Ctrl+C, SIGTERM y el cierre del terminal detienen el servidor de forma ordenada."""
     def shutdown(*_):
         console_log("\n" + timestamp_message("Deteniendo servidor ZeroChat..."))
         stop_zerochat_server(server)
@@ -4551,6 +4666,10 @@ def main():
     if hasattr(signal, "SIGHUP"):
         signal.signal(signal.SIGHUP, shutdown)
 
+
+def serve(server: ThreadingHTTPServer):
+    """Atiende peticiones hasta la parada y libera después el servidor y la consola."""
+    global CONSOLE_CONTROL
     try:
         server.serve_forever()
     finally:
@@ -4560,16 +4679,58 @@ def main():
             CONSOLE_CONTROL.close()
             CONSOLE_CONTROL = None
 
+
+def finish_run(headless_browser, result_out):
+    """Modo ejecución: escribe la respuesta final en el stdout original y sale con su código."""
+    # Firefox sin ventana sigue vivo al cerrar la página; uno ya abierto solo recibió la pestaña.
+    if headless_browser is not None and headless_browser.poll() is None:
+        _kill_process_tree(headless_browser)
+    code, text = run_outcome(RUN_SESSION)
+    sys.stdout = result_out
+    if text is not None:
+        result_out.write(text if text.endswith("\n") else text + "\n")
+        result_out.flush()
+    sys.exit(code)
+
+
+def main():
+    global RUN_SESSION, EXIT_ON_CLOSE
+
+    parser = build_parser()
+    args = parser.parse_args()
+    # Los avisos no persisten entre ejecuciones del servidor.
+    reset_notices()
+    RUN_SESSION = run_session_from_args(parser, args)
+    result_out = redirect_log(args)
+
+    if args.test:
+        run_self_test()
+        return
+
+    dev_root = get_dev_root()
+    static_root = get_static_root()
+    prepare_environment(args, is_dev=dev_root is not None)
+    reset_session_credentials()
+
+    # La interfaz local de desarrollo tiene el puerto en su origen: en otro no vería los datos guardados.
+    server = open_server(args, local_ui=static_root is not None and not args.ui_url)
+    exposure_warning = remote_exposure_warning(ACTIVE_HOST)
+    if exposure_warning:
+        add_notice(exposure_warning)
+
+    ui_url, target_url = interface_urls(args, static_root)
+    # El modo ejecución (que rechaza --keep-server) detecta con el latido que el navegador se cerró sin devolver resultado.
+    EXIT_ON_CLOSE = not args.keep_server
+    print_header(dev_root, ui_url, exposure_warning, EXIT_ON_CLOSE)
+
+    headless_browser = start_interface(args, parser, server, target_url, result_out)
+    if EXIT_ON_CLOSE:
+        start_heartbeat_watchdog(server, require_initial=not args.no_browser)
+    install_signal_handlers(server)
+    serve(server)
+
     if RUN_SESSION:
-        # Firefox sin ventana sigue vivo al cerrar la página; uno ya abierto solo recibió la pestaña.
-        if headless_browser is not None and headless_browser.poll() is None:
-            _kill_process_tree(headless_browser)
-        code, text = run_outcome(RUN_SESSION)
-        sys.stdout = result_out
-        if text is not None:
-            result_out.write(text if text.endswith("\n") else text + "\n")
-            result_out.flush()
-        sys.exit(code)
+        finish_run(headless_browser, result_out)
 
 
 if __name__ == "__main__":