@danhachuel/leadmaster 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -6,6 +6,39 @@ O formato é baseado no [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.
 A etiqueta visual de versão usa patch de dois dígitos (ex.: `0.1.00`); o registry NPM
 normaliza para a forma canônica (ex.: `0.1.0`).
 
+## [0.1.06] — 2026-11-08
+
+### Corrigido
+
+- **Regra de comandos de instalação (AGENTS.md)** — redação ambígua permitia enviar
+  `@latest` nas mensagens de release. Agora é explícito: os comandos entregues ao
+  usuário usam **sempre a versão canônica confirmada no registry** (ex.: `0.1.6`) —
+  `@latest` é permitido apenas nas instruções permanentes (README, página NPM,
+  `legal/`).
+
+## [0.1.05] — 2026-11-08
+
+### Corrigido
+
+- **Encerramento em cascata no Windows (STATUS_CONTROL_C_EXIT / 0xC000013A)** — o
+  launcher Node e os workers Python compartilhavam o mesmo grupo de processos,
+  então Ctrl+C no terminal (MobaXterm, VS Code, perda de foco) derrubava tudo
+  junto, arriscando corromper extrações e trabalhos em andamento.
+  - `scripts/cli.mjs`: o servidor FastAPI é spawnado com **`detached: true`**
+    (no Windows, `CREATE_NEW_PROCESS_GROUP` 0x00000200) — grupo de processos
+    próprio; sinais do terminal não cascateiam para o worker, que só é
+    encerrado pelo `kill()` controlado do launcher.
+  - `backend/services/flags.py` (novo): helper `creationflags()` com
+    `CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW` (0x08000200) no Windows;
+    0 no Linux/macOS.
+  - `backend/services/extractors.py`: todas as execuções de CLI (Google Maps
+    Scraper, igmapper, Scrapling) passam a usar as flags isoladas.
+  - Testes `backend/tests/test_process_flags.py` (pytest) verificam as flags sem
+    mockar `os.name` (o que quebraria `pathlib` nas duas direções): o helper
+    recebe a plataforma por parâmetro e os testes mockam o próprio helper —
+    passam idênticos no GitHub Actions (Linux) e no Windows local.
+  - CI: novo passo "Run backend tests (pytest)" no workflow de publicação.
+
 ## [0.1.04] — 2026-11-05
 
 ### Corrigido

package/backend/requirements-test.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest>=8.0,<9.0

package/backend/services/extractors.py

@@ -16,6 +16,7 @@ from pathlib import Path
 
 import httpx
 
+from . import flags as proc_flags
 from . import storage
 
 
@@ -61,7 +62,7 @@ def extrair_google_maps(palavra_chave: str, localizacao: str, max_resultados: in
             outdir=str(outdir),
         )
         try:
-            resultado = subprocess.run(cmd, capture_output=True, text=True, timeout=1800, shell=False)
+            resultado = subprocess.run(cmd, capture_output=True, text=True, timeout=1800, shell=False, creationflags=proc_flags.creationflags())
         except FileNotFoundError as e:
             raise ExtratorNaoConfigurado(f"Não foi possível executar o CLI do Google Maps Scraper: {e}") from e
         if resultado.returncode != 0:
@@ -90,7 +91,7 @@ def extrair_instagram(profile_url: str) -> dict:
         args_template = conf.get("igmapper_args", "--profile {url} --outdir {outdir}")
         cmd = [cli] + _formatar_args(args_template, url=profile_url, outdir=str(outdir))
         try:
-            resultado = subprocess.run(cmd, capture_output=True, text=True, timeout=900, shell=False)
+            resultado = subprocess.run(cmd, capture_output=True, text=True, timeout=900, shell=False, creationflags=proc_flags.creationflags())
         except FileNotFoundError as e:
             raise ExtratorNaoConfigurado(f"Não foi possível executar o igmapper: {e}") from e
         if resultado.returncode != 0:
@@ -220,6 +221,7 @@ def enriquecer_com_site(website: str) -> dict:
             text=True,
             timeout=300,
             shell=False,
+            creationflags=proc_flags.creationflags(),
         )
     except FileNotFoundError as e:
         raise ExtratorNaoConfigurado(f"Não foi possível executar o Scrapling: {e}") from e

package/backend/services/flags.py

@@ -0,0 +1,40 @@
+"""Flags de criação de subprocessos, isolados no Windows.
+
+Problema que resolve: quando o terminal (MobaXterm, VS Code, perda de foco)
+envia Ctrl+C, o evento de interrupção (STATUS_CONTROL_C_EXIT / 0xC000013A) é
+propagado a todo o *grupo de processos* do terminal — derrubando launcher E
+workers juntos, corrompendo extrações e trabalhos em andamento.
+
+Solução: cada worker nasce em seu PRÓPRIO grupo de processos no Windows
+(`CREATE_NEW_PROCESS_GROUP`) e sem janela (`CREATE_NO_WINDOW`); assim,
+interrupções de terminal não cascateiam para os workers, e quem encerra o
+worker é o launcher, de forma controlada.
+
+No Linux/macOS o launcher já spawna com `detached: true` (sessão própria) e
+`creationflags` retorna 0 — não há alteração de comportamento.
+
+O parâmetro `so` existe para os testes: assim é possível verificar os dois
+comportamentos sem mockar `os.name` globalmente (o que quebraria `pathlib`
+nas duas direções — fingir "nt" no Linux e "posix" no Windows).
+"""
+
+import os
+import subprocess
+
+# CREATE_NEW_PROCESS_GROUP = 0x00000200 (grupo isolado de sinais do console)
+# CREATE_NO_WINDOW        = 0x08000000 (não abrir janela de console)
+# getattr com fallback literal: CREATE_NO_WINDOW não existe em todas as
+# plataformas POSIX — o módulo precisa importar limpo no Linux (CI) também.
+_WINDOWS_FLAGS = (
+    getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0x00000200)
+    | getattr(subprocess, "CREATE_NO_WINDOW", 0x08000000)
+)
+
+
+def creationflags(so: str | None = None) -> int:
+    """Flags a passar em subprocess.run/Popen. 0 no Linux/macOS."""
+    if so is None:
+        so = os.name
+    if so == "nt":
+        return _WINDOWS_FLAGS
+    return 0

package/backend/tests/conftest.py

@@ -0,0 +1,6 @@
+"""Permite `import services...` quando o pytest roda da raiz do repositório."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

package/backend/tests/test_process_flags.py

@@ -0,0 +1,88 @@
+"""Testes de isolamento de processos (Windows process groups).
+
+Verificam que os workers são criados com CREATE_NEW_PROCESS_GROUP |
+CREATE_NO_WINDOW no Windows e sem flags no POSIX — para que Ctrl+C do terminal
+não derrube launcher e workers em cascata (STATUS_CONTROL_C_EXIT).
+
+Nota de portabilidade: em vez de mockar `os.name` globalmente (o que quebra
+`pathlib` nas duas direções — "nt" fingido no Linux e "posix" fingido no
+Windows), os testes usam o parâmetro `so` do helper e mockam o próprio helper.
+Assim passam idênticos no GitHub Actions (Linux) e no Windows local.
+"""
+
+import os
+import subprocess
+import sys
+from unittest.mock import patch
+
+from services import extractors
+from services.flags import _WINDOWS_FLAGS, creationflags
+
+FLAGS_WINDOWS = _WINDOWS_FLAGS  # 0x00000200 | 0x08000000
+
+
+def _config_fake() -> dict:
+    return {
+        "extratores": {
+            # sys.executable existe em qualquer plataforma — o run é mockado.
+            "google_maps_cli": sys.executable,
+            "google_maps_args": '--kw "{palavra_chave}" --loc "{localizacao}" --email --max {max_resultados} --outdir "{outdir}"',
+            "igmapper_cli": sys.executable,
+            "igmapper_args": "--profile {url} --outdir {outdir}",
+        }
+    }
+
+
+def _completed_process(*_args, **_kwargs) -> subprocess.CompletedProcess:
+    return subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
+
+
+class TestFlags:
+    def test_windows_aplica_novo_grupo_e_sem_janela(self):
+        flags = creationflags("nt")
+        assert flags & 0x00000200, "CREATE_NEW_PROCESS_GROUP ausente"
+        assert flags & 0x08000000, "CREATE_NO_WINDOW ausente"
+        assert flags == FLAGS_WINDOWS
+
+    def test_posix_sem_flags(self):
+        assert creationflags("posix") == 0
+
+    def test_plataforma_real_sem_parametro(self):
+        esperado = FLAGS_WINDOWS if os.name == "nt" else 0
+        assert creationflags() == esperado
+
+
+class TestExtratores:
+    def _extrair_maps(self):
+        return extractors.extrair_google_maps("dentista", "São Paulo SP", 10)
+
+    def _rodar_com_flags(self, valor_flags):
+        with (
+            patch.object(extractors.proc_flags, "creationflags", return_value=valor_flags),
+            patch.object(extractors.storage, "get_config", return_value=_config_fake()),
+            patch.object(extractors.subprocess, "run", side_effect=_completed_process) as run_mock,
+        ):
+            self._extrair_maps()
+        assert run_mock.called
+        return run_mock
+
+    def test_google_maps_repassa_flags_windows(self):
+        run_mock = self._rodar_com_flags(FLAGS_WINDOWS)
+        assert run_mock.call_args.kwargs["creationflags"] == FLAGS_WINDOWS
+
+    def test_google_maps_repassa_zero_posix(self):
+        run_mock = self._rodar_com_flags(0)
+        assert run_mock.call_args.kwargs["creationflags"] == 0
+
+    def test_instagram_repassa_flags_windows(self):
+        with (
+            patch.object(extractors.proc_flags, "creationflags", return_value=FLAGS_WINDOWS),
+            patch.object(extractors.storage, "get_config", return_value=_config_fake()),
+            patch.object(extractors.subprocess, "run", side_effect=_completed_process) as run_mock,
+        ):
+            try:
+                extractors.extrair_instagram("https://instagram.com/padaria.do.largo/")
+            except extractors.ExtratorErro:
+                pass  # saída mockada vazia → "sem dados reconhecíveis" (esperado)
+        assert run_mock.called
+        assert run_mock.call_args.kwargs["creationflags"] == FLAGS_WINDOWS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/leadmaster",
-  "version": "0.1.04",
+  "version": "0.1.06",
   "description": "SaaS local de prospecção e automação: CRM, extratores de leads e agentes de IA — 100% local.",
   "license": "MIT",
   "author": "Dan Hachuel",

package/scripts/cli.mjs

@@ -374,6 +374,11 @@ function cmdStart(args) {
       console.warn('⚠ Interface construída não encontrada (frontend/dist).');
     }
 
+    // Workers nascem em grupo de processos próprio (detached: true =
+    // CREATE_NEW_PROCESS_GROUP no Windows): sinais de Ctrl+C do terminal
+    // (MobaXterm, VS Code, perda de foco) matam apenas o launcher — o
+    // servidor Python continua rodando e só é encerrado pelo kill()
+    // controlado abaixo (ou sobrevive para a próxima execução detectar).
     const child = spawn(python.cmd, [...python.args, '-m', 'uvicorn', 'main:app', '--host', '127.0.0.1', '--port', String(porta), '--no-access-log'], {
       cwd: path.join(PKG_ROOT, 'backend'),
       env: {
@@ -385,6 +390,7 @@ function cmdStart(args) {
         PYTHONIOENCODING: 'utf-8',
       },
       stdio: ['ignore', 'pipe', 'pipe'],
+      detached: true,
       windowsHide: true,
     });