jaylog 0.2.8__tar.gz → 0.3.0a2__tar.gz

jaylog-0.3.0a2/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.3
+Name: jaylog
+Version: 0.3.0a2
+Summary: Customized Python logging library with file rotation and HTTP forwarding
+Author: Gpocas
+Author-email: Gpocas <gpocas01@gmail.com>
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Dist: pydantic>=2.0,<3.0
+Requires-Dist: pydantic-settings>=2.0,<3.0
+Requires-Dist: requests>=2.32,<3.0
+Requires-Dist: pillow>=11.0,<13.0
+Requires-Python: >=3.10, <3.14
+Project-URL: repository, https://github.com/Gpocas/jaylog
+Project-URL: Bug Tracker, https://github.com/Gpocas/jaylog/issues
+Description-Content-Type: text/markdown
+
+# jaylog
+
+Biblioteca de logging para Python com rotação de arquivos, saída colorida no console, envio HTTP para um endpoint remoto e registro automático do ambiente de execução (host reporting).
+
+📖 **Documentação completa:** https://gpocas.github.io/jaylog-book
+
+## Instalação
+
+```bash
+pip install -U --no-cache-dir jaylog
+```
+
+## Uso rápido
+
+__*.env.logging*__
+```env
+JAYLOG_APP_NAME=meu-bot
+JAYLOG_LOG_DIR=C:\logs
+```
+
+__*main.py*__
+```python
+from jaylog import JaylogSettings, configure, get_logger
+
+configure(JaylogSettings())
+
+logger = get_logger()
+
+logger.info("Olá, jaylog!")
+```
+
+Para variáveis de ambiente, cenários de uso (console-only, múltiplos loggers, cores), preparação para produção (secrets, host reporting) e referência da API, veja a [documentação guiada](https://gpocas.github.io/jaylog-book).

jaylog-0.3.0a2/README.md

@@ -0,0 +1,32 @@
+# jaylog
+
+Biblioteca de logging para Python com rotação de arquivos, saída colorida no console, envio HTTP para um endpoint remoto e registro automático do ambiente de execução (host reporting).
+
+📖 **Documentação completa:** https://gpocas.github.io/jaylog-book
+
+## Instalação
+
+```bash
+pip install -U --no-cache-dir jaylog
+```
+
+## Uso rápido
+
+__*.env.logging*__
+```env
+JAYLOG_APP_NAME=meu-bot
+JAYLOG_LOG_DIR=C:\logs
+```
+
+__*main.py*__
+```python
+from jaylog import JaylogSettings, configure, get_logger
+
+configure(JaylogSettings())
+
+logger = get_logger()
+
+logger.info("Olá, jaylog!")
+```
+
+Para variáveis de ambiente, cenários de uso (console-only, múltiplos loggers, cores), preparação para produção (secrets, host reporting) e referência da API, veja a [documentação guiada](https://gpocas.github.io/jaylog-book).

{jaylog-0.2.8 → jaylog-0.3.0a2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jaylog"
-version = "0.2.8"
+version = "0.3.0a2"
 description = "Customized Python logging library with file rotation and HTTP forwarding"
 readme = "README.md"
 authors = [
@@ -26,6 +26,24 @@ dependencies = [
 repository = "https://github.com/Gpocas/jaylog"
 "Bug Tracker" = "https://github.com/Gpocas/jaylog/issues"
 
+[dependency-groups]
+dev = [
+    "pytest>=8,<9",
+    "ruff>=0.6",
+]
+
 [build-system]
 requires = ["uv_build>=0.10.8,<0.11.0"]
 build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

jaylog-0.3.0a2/src/jaylog/__init__.py

@@ -0,0 +1,37 @@
+from jaylog._version import PROTOCOL_VERSION, __version__
+from jaylog.logger import configure, get_logger, shutdown
+from jaylog.settings import JaylogSettings
+
+__all__ = [
+    "configure",
+    "get_logger",
+    "shutdown",
+    "JaylogSettings",
+    "__version__",
+    "PROTOCOL_VERSION",
+]
+
+_DEPRECATED = {"LogEntry"}
+
+
+def __getattr__(name: str):
+    # `jaylog.models.LogEntry` era código morto — nunca foi construído, e o tipo
+    # declarado nem batia com o que o handler HTTP envia. Fica acessível por um
+    # release para não quebrar `from jaylog import LogEntry` em código de bot.
+    if name in _DEPRECATED:
+        import warnings
+
+        warnings.warn(
+            f"jaylog.{name} está depreciado e será removido na 0.4.0; "
+            "o modelo nunca foi usado pela biblioteca.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from jaylog import _compat
+
+        return getattr(_compat, name)
+    raise AttributeError(f"module 'jaylog' has no attribute '{name}'")
+
+
+def __dir__() -> list[str]:
+    return sorted([*__all__, *_DEPRECATED])

jaylog-0.3.0a2/src/jaylog/_compat.py

@@ -0,0 +1,29 @@
+"""
+Shim de depreciação de ``jaylog.models``.
+
+``LogEntry`` era código morto: nunca foi construído em lugar nenhum, e o tipo
+declarado (``log_img: Optional[str]``) nem batia com os ``bytes`` que o handler
+HTTP envia. Fica acessível por mais um release via ``jaylog.LogEntry``, que
+emite ``DeprecationWarning``. Remover na 0.4.0.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class LogEntry(BaseModel):
+    log_timestamp: datetime
+    log_level: str
+    is_exception: bool
+    log_message: str
+    service: str
+    username: str
+    hostname: str
+    ipv4: str
+    service_path: str
+    line_number: int
+    log_img: str | None = None
+
+
+__all__ = ["LogEntry"]

jaylog-0.3.0a2/src/jaylog/_version.py

@@ -0,0 +1,19 @@
+"""
+Versão do pacote e versão do protocolo de ingestão.
+
+Lookup único de ``importlib.metadata``: o valor era recalculado em
+``handlers/http_handler.py`` e voltaria a ser recalculado no reporter de host.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+#: Versão do contrato cliente <-> backend. Vai no header ``x-jaylog-protocol``
+#: e no payload de host. Mede o rollout; não dirige lógica no backend.
+PROTOCOL_VERSION = 2
+
+try:
+    __version__ = version("jaylog")
+except PackageNotFoundError:  # rodando do fonte, sem instalação
+    __version__ = "unknown"
+
+__all__ = ["__version__", "PROTOCOL_VERSION"]

jaylog-0.3.0a2/src/jaylog/context.py

@@ -0,0 +1,93 @@
+"""
+Enriquecimento do ``LogRecord``, memoizado **no próprio record**.
+
+O problema que isto resolve: ``build_log_entry_dict()`` é chamado uma vez por
+handler downstream (arquivo, console, HTTP) e mais uma vez dentro do
+``PlainTextFormatter``. Com screenshot ligado, o mesmo erro capturava a tela até
+três vezes — três ``ImageGrab.grab()`` sequenciais, cada um na casa das centenas
+de milissegundos, para produzir três imagens quase idênticas das quais duas eram
+descartadas. Memoizar no record resolve porque o record é exatamente o escopo do
+"uma vez por evento de log".
+
+O screenshot saiu do caminho compartilhado: ``record_screenshot()`` é chamado só
+pelo ``JaylogHttpHandler``, que é o único com para onde mandá-lo.
+
+.. warning::
+   Este enriquecimento tem que continuar **downstream da fila**.
+   ``QueueHandler.prepare()`` já faz ``record.msg = self.format(record)`` e zera
+   ``exc_info``; por isso, aqui embaixo, ``record.exc_info`` é sempre ``None`` e
+   o traceback sobrevive apenas por já estar embutido em ``getMessage()``. Mover
+   o enriquecimento para antes da fila (um ``Filter`` no ``QueueHandler``, por
+   exemplo) duplicaria o traceback — e ainda rodaria na thread do chamador.
+   Há um teste de regressão travando isso.
+"""
+
+import logging
+import traceback
+from datetime import datetime, timezone
+
+from jaylog.host import identity
+from jaylog.screenshot import capture_screenshot
+
+_ENTRY_ATTR = "_jaylog_entry"
+_SCREENSHOT_ATTR = "_jaylog_screenshot"
+
+
+def build_log_entry_dict(record: logging.LogRecord) -> dict:
+    """
+    Campos do log, sem ``log_img``.
+
+    ``hostname``/``username``/``ipv4`` continuam no corpo de todo log — a
+    tabela ``logs`` os mantém desnormalizados de forma permanente, então não há
+    o que migrar.
+    """
+    is_exception = getattr(record, "is_exception", False)
+
+    log_message = record.getMessage()
+    if is_exception and record.exc_info:
+        tb = "".join(traceback.format_exception(*record.exc_info)).strip()
+        log_message = f"{log_message}\n{tb}"
+
+    return {
+        "log_timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+        "log_level": "EXCEPTION" if is_exception else record.levelname,
+        "is_exception": is_exception,
+        "log_message": log_message,
+        "service": record.name,
+        "username": identity.username(),
+        "hostname": identity.hostname(),
+        "ipv4": identity.ipv4(),
+        "service_path": record.pathname,
+        "line_number": record.lineno,
+    }
+
+
+def record_entry(record: logging.LogRecord) -> dict:
+    """``build_log_entry_dict`` com o resultado guardado no record."""
+    entry = getattr(record, _ENTRY_ATTR, None)
+    if entry is None:
+        entry = build_log_entry_dict(record)
+        setattr(record, _ENTRY_ATTR, entry)
+    return entry
+
+
+def wants_screenshot(record: logging.LogRecord) -> bool:
+    return record.levelno >= logging.ERROR or bool(getattr(record, "is_exception", False))
+
+
+def record_screenshot(record: logging.LogRecord) -> bytes | None:
+    """
+    Screenshot do evento, capturado no máximo uma vez por record.
+
+    O sentinela guardado no record distingue "ainda não tentamos" de "tentamos e
+    não veio nada" — sem ele, um ``None`` legítimo faria a próxima chamada
+    capturar de novo.
+    """
+    if _SCREENSHOT_ATTR in record.__dict__:
+        return record.__dict__[_SCREENSHOT_ATTR]
+    image = capture_screenshot() if wants_screenshot(record) else None
+    record.__dict__[_SCREENSHOT_ATTR] = image
+    return image
+
+
+__all__ = ["build_log_entry_dict", "record_entry", "record_screenshot", "wants_screenshot"]

jaylog-0.3.0a2/src/jaylog/endpoints.py

@@ -0,0 +1,26 @@
+"""
+Derivação da URL do endpoint de host a partir da URL do endpoint de log.
+
+Deploys existentes já configuram ``JAYLOG_LOG_HTTP_ENDPOINT``; trocar o último
+segmento do path (``/logs/add`` -> ``/logs/host``) evita exigir uma variável
+nova de todo mundo. Quem precisar de outro caminho usa
+``JAYLOG_HOST_HTTP_ENDPOINT``.
+"""
+
+from urllib.parse import urlsplit, urlunsplit
+
+
+def derive_host_endpoint(log_endpoint: str) -> str:
+    """
+    ``https://api/logs/add`` -> ``https://api/logs/host``.
+
+    Query string e fragmento são preservados; barra final é ignorada. Uma URL
+    sem path (``https://api``) vira ``https://api/host``.
+    """
+    parts = urlsplit(log_endpoint)
+    head, sep, _last = parts.path.rstrip("/").rpartition("/")
+    path = f"{head}/host" if sep else "/host"
+    return urlunsplit((parts.scheme, parts.netloc, path, parts.query, parts.fragment))
+
+
+__all__ = ["derive_host_endpoint"]

jaylog-0.3.0a2/src/jaylog/formatters.py

@@ -0,0 +1,33 @@
+"""
+Formatação legível para arquivo.
+
+O módulo encolheu: identidade da máquina foi para ``host/identity.py`` (lazy),
+screenshot para ``screenshot.py`` e a montagem do dicionário de log para
+``context.py``. ``build_log_entry_dict`` continua reexportado aqui por compat —
+remover na 0.4.0.
+"""
+
+import logging
+from datetime import datetime
+
+from jaylog.context import build_log_entry_dict, record_entry
+from jaylog.screenshot import configure_screenshot
+
+__all__ = ["PlainTextFormatter", "build_log_entry_dict", "configure_screenshot"]
+
+
+class PlainTextFormatter(logging.Formatter):
+    """Human-readable single-line formatter for .log files."""
+
+    def __init__(self, show_service: bool = True) -> None:
+        super().__init__()
+        self.show_service = show_service
+
+    def format(self, record: logging.LogRecord) -> str:
+        entry = record_entry(record)
+        log_timestamp = (
+            datetime.fromisoformat(entry["log_timestamp"]).astimezone().strftime("%d/%m/%Y %X")
+        )
+        log_level = f"[{entry['log_level']}]"
+        service_segment = f"[{entry['service']}] | " if self.show_service else ""
+        return f"{log_timestamp} {log_level.ljust(11)} | {service_segment}{entry['log_message']}"

{jaylog-0.2.8 → jaylog-0.3.0a2}/src/jaylog/handlers/console_handler.py

@@ -4,7 +4,7 @@ from datetime import datetime
 from typing import IO
 
 from jaylog.colors import BLUE, GREEN, PURPLE, RED, RESET, YELLOW, supports_color
-from jaylog.formatters import build_log_entry_dict
+from jaylog.context import record_entry
 
 _LEVEL_COLORS = {
     "DEBUG": PURPLE,
@@ -37,12 +37,14 @@ class ConsoleFormatter(logging.Formatter):
         return f"{color}{text}{RESET}"
 
     def format(self, record: logging.LogRecord) -> str:
-        entry = build_log_entry_dict(record)
-        log_timestamp = datetime.fromisoformat(entry["log_timestamp"]).astimezone().strftime("%d/%m/%Y %X")
-        log_level = f'[{entry["log_level"]}]'
+        entry = record_entry(record)
+        log_timestamp = (
+            datetime.fromisoformat(entry["log_timestamp"]).astimezone().strftime("%d/%m/%Y %X")
+        )
+        log_level = f"[{entry['log_level']}]"
         colored_timestamp = self._paint(log_timestamp, GREEN)
-        colored_level = self._paint(log_level.ljust(11), _level_color(entry['log_level']))
-        service_segment = f'[{entry["service"]}] | ' if self.show_service else ''
+        colored_level = self._paint(log_level.ljust(11), _level_color(entry["log_level"]))
+        service_segment = f"[{entry['service']}] | " if self.show_service else ""
         return f"{colored_timestamp} {colored_level} | {service_segment}{entry['log_message']}"
 
 

jaylog-0.3.0a2/src/jaylog/handlers/http_handler.py

@@ -0,0 +1,102 @@
+import json
+import logging
+import os
+import warnings
+
+import requests
+import urllib3
+
+from jaylog._version import PROTOCOL_VERSION, __version__
+from jaylog.context import record_entry, record_screenshot
+from jaylog.host import reporter
+from jaylog.runtime import RUN_ID
+
+#: O backend sinaliza por header que não conhece este `run_id` — normalmente
+#: porque o log correu na frente do POST de host. Ver `reporter.request_resend`.
+HOST_REQUIRED_HEADER = "x-jaylog-host-required"
+
+
+def _to_multipart(fields: dict) -> dict:
+    result = {}
+    for key, value in fields.items():
+        if value is None:
+            continue
+        if isinstance(value, bytes):
+            result[key] = ("screenshot.jpg", value, "image/jpeg")
+        elif isinstance(value, bool):
+            result[key] = (None, "true" if value else "false")
+        elif not isinstance(value, str):
+            result[key] = (None, json.dumps(value))
+        else:
+            result[key] = (None, value)
+    return result
+
+
+class JaylogHttpHandler(logging.Handler):
+    """
+    HTTP handler that POSTs log records as multipart/form-data to a remote endpoint.
+
+    Non-blocking behaviour is guaranteed by the QueueListener that drives this
+    handler — emit() runs in the listener's background thread.
+
+    O **corpo** do POST é byte-a-byte o mesmo da 0.2.x: ``logs`` mantém
+    ``hostname``/``username``/``ipv4`` desnormalizados de forma permanente, então
+    não há campo a remover. O que muda são dois headers novos
+    (``x-jaylog-protocol`` e ``x-jaylog-run-id``); um backend antigo simplesmente
+    os ignora.
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: str,
+        timeout: float = 5.0,
+        proxy: str | None = None,
+        verify: bool | str = False,
+    ) -> None:
+        super().__init__()
+        self.endpoint = endpoint
+        self.timeout = timeout
+        self.verify = verify
+        self.proxy = {"http": proxy, "https": proxy} if proxy else None
+        self._session = requests.Session()
+        self._session.headers["x-api-key"] = api_key
+        self._session.headers["x-jaylog-version"] = __version__
+        self._session.headers["x-jaylog-protocol"] = str(PROTOCOL_VERSION)
+        self._session.headers["x-jaylog-run-id"] = RUN_ID
+
+    def mapLogRecord(self, record: logging.LogRecord) -> dict:
+        # Único ponto do programa que pede screenshot: é o único com para onde
+        # mandá-la. Console e arquivo não capturam mais nada.
+        entry = dict(record_entry(record))
+        entry["log_img"] = record_screenshot(record)
+        return entry
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            if self.proxy:
+                self._session.proxies.update(self.proxy)
+
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", urllib3.exceptions.InsecureRequestWarning)
+                response = self._session.post(
+                    self.endpoint,
+                    files=_to_multipart(self.mapLogRecord(record)),
+                    timeout=self.timeout,
+                    verify=self.verify,
+                )
+                if os.getenv("JAYLOG_HTTP_DEBUG") == "1":
+                    print(response.status_code)
+                    print(response.content)
+
+            if response.headers.get(HOST_REQUIRED_HEADER) == "1":
+                # O log foi aceito (202) — não há nada a reenviar aqui. O que
+                # falta é o registro de ambiente, que o reporter reenvia (com
+                # debounce, porque o header vem em toda linha afetada).
+                reporter.request_resend(record.name)
+        except Exception:
+            # `handleError` respeita `logging.raiseExceptions`: barulho em dev,
+            # silêncio em produção. O `except: pass` anterior era um buraco
+            # negro — era por causa dele que ninguém descobria que o caminho
+            # HTTP estava falhando.
+            self.handleError(record)

jaylog-0.3.0a2/src/jaylog/host/__init__.py

@@ -0,0 +1,6 @@
+# Intencionalmente vazio.
+#
+# `settings.py` precisa de `host.identity` sem arrastar `requests` (via
+# `reporter`) nem `subprocess` (via `detect_git`). Re-exportar os submódulos
+# aqui recriaria esse acoplamento no import. Importe sempre o submódulo
+# explícito: `from jaylog.host import identity`.

jaylog-0.3.0a2/src/jaylog/host/_safe.py

@@ -0,0 +1,56 @@
+"""
+``@safe``: nenhum coletor de host pode derrubar a aplicação.
+
+A coleta é observabilidade — se a leitura do Toolhelp falhar, se o antivírus
+bloquear o ``git``, se o ``pyvenv.cfg`` estiver corrompido, o campo vira
+``None`` e o resto do payload segue. O contrato é que um coletor **nunca**
+levanta.
+"""
+
+import copy
+import functools
+import os
+import sys
+import traceback
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _debug_enabled() -> bool:
+    return os.environ.get("JAYLOG_DEBUG") == "1"
+
+
+def safe(default: Any = None) -> Callable[[F], F]:
+    """
+    Devolve ``default`` quando a função levanta.
+
+    Captura ``Exception``, **não** ``BaseException``: engolir ``KeyboardInterrupt``
+    numa thread de coleta esconderia o Ctrl-C do usuário, e ``SystemExit`` tem
+    que continuar subindo.
+
+    O traceback só é impresso em stderr com ``JAYLOG_DEBUG=1`` — em produção a
+    falha é silenciosa por desenho, já que o payload carrega a evidência
+    (o campo fica ``None``).
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception:
+                if _debug_enabled():
+                    print(f"[jaylog] host: falha em {func.__name__}", file=sys.stderr)
+                    traceback.print_exc(file=sys.stderr)
+                # copy para que um default mutável (`{}`, `[]`) não seja
+                # compartilhado entre chamadas.
+                return copy.copy(default)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+__all__ = ["safe"]

jaylog-0.3.0a2/src/jaylog/host/collectors.py

@@ -0,0 +1,131 @@
+"""
+``collect_host_info()``: junta todos os detectores num ``HostInfo``.
+
+Memoizado por processo e thread-safe. O custo da coleta (~100-500 ms: um
+snapshot Toolhelp mais até seis subprocessos ``git``) é pago **uma vez**, na
+thread de startup — nunca na thread do chamador de ``configure()``.
+
+Os parâmetros de git vêm da primeira chamada: dois ``app_name`` no mesmo
+processo compartilham o mesmo ambiente, então coletar duas vezes só gastaria
+tempo para produzir o mesmo retrato.
+"""
+
+import os
+import platform
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+from jaylog.host import detect_execution, detect_git, detect_python, detect_venv, identity
+from jaylog.host._safe import safe
+from jaylog.host.models import HostInfo
+
+_lock = threading.Lock()
+_cached: HostInfo | None = None
+
+
+@safe(default=(None, None, None, None))
+def _os_info() -> tuple[str | None, str | None, str | None, str | None]:
+    uname = platform.uname()
+    return (
+        uname.system or None,
+        uname.release or None,
+        uname.version or None,
+        uname.machine or None,
+    )
+
+
+@safe(default=None)
+def _cwd() -> str | None:
+    return os.getcwd()
+
+
+@safe(default=None)
+def _collect(
+    git_enabled: bool,
+    git_dir: Path | str | None,
+    git_timeout: float,
+    git_dirty_enabled: bool,
+    git_remote_enabled: bool,
+) -> HostInfo:
+    os_system, os_release, os_version, machine = _os_info()
+    execution = detect_execution.detect_execution()
+    python = detect_python.detect_python()
+    venv = detect_venv.detect_venv()
+    git = detect_git.detect_git(
+        enabled=git_enabled,
+        git_dir=git_dir,
+        timeout=git_timeout,
+        dirty_enabled=git_dirty_enabled,
+        remote_enabled=git_remote_enabled,
+    )
+
+    return HostInfo(
+        collected_at=datetime.now(timezone.utc).isoformat(),
+        hostname=identity.hostname(),
+        username=identity.username(),
+        ipv4=identity.ipv4(),
+        os_system=os_system,
+        os_release=os_release,
+        os_version=os_version,
+        machine=machine,
+        execution_mode=execution.mode,
+        execution_detail=execution.detail,
+        session_id=execution.session_id,
+        process_id=execution.process_id,
+        parent_process_name=execution.parent_process_name,
+        python_version=python.version,
+        python_implementation=python.implementation,
+        python_executable=python.executable,
+        python_frozen=python.frozen,
+        venv_active=venv.active,
+        venv_kind=venv.kind,
+        venv_path=venv.path,
+        git_available=git.available,
+        git_version=git.version,
+        git_repo=git.repo,
+        git_root=git.root,
+        git_branch=git.branch,
+        git_commit=git.commit,
+        git_commit_short=git.commit_short,
+        git_commit_msg=git.commit_msg,
+        git_dirty=git.dirty,
+        git_remote_url=git.remote_url,
+        cwd=_cwd(),
+        entrypoint=detect_git.entrypoint_dir(),
+    )
+
+
+def collect_host_info(
+    *,
+    git_enabled: bool = True,
+    git_dir: Path | str | None = None,
+    git_timeout: float = 3.0,
+    git_dirty_enabled: bool = True,
+    git_remote_enabled: bool = True,
+) -> HostInfo:
+    """
+    Retrato do ambiente, coletado uma vez por processo.
+
+    Nunca levanta: se o ``@safe`` de backstop devolver ``None``, cai para
+    ``HostInfo.minimal()``, que ainda carrega ``run_id`` e a identidade da
+    máquina.
+    """
+    global _cached
+    with _lock:
+        if _cached is None:
+            _cached = (
+                _collect(git_enabled, git_dir, git_timeout, git_dirty_enabled, git_remote_enabled)
+                or HostInfo.minimal()
+            )
+        return _cached
+
+
+def reset_cache() -> None:
+    """Limpa a memoização. Existe para os testes; não use em produção."""
+    global _cached
+    with _lock:
+        _cached = None
+
+
+__all__ = ["collect_host_info", "reset_cache"]