@danhachuel/pandanews 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Todas as versões publicadas são registradas aqui antes do publish (regra em AGENTS.md). A etiqueta visual usa PATCH de dois dígitos (ex.: 0.1.00); o registry npm normaliza para a versão canônica (ex.: 0.1.0).
 
+## 0.4.04 (2026-11-08)
+
+- **HOTFIX real — fim das janelas de CMD no instalador**: o 0.4.03 blindou apenas o launcher (`start.js`) e deixou o **caminho de instalação** descoberto. No Windows, `tar` (extração do Python portátil), `python -m venv` e `pip install -r requirements.txt` eram lançados **sem `windowsHide`** — era aí que as múltiplas janelas de terminal apareciam. Os três `spawnSync` de `scripts/install.js` agora nascem com `windowsHide: true` (`CREATE_NO_WINDOW`)
+- `scripts/build.js` blindado também: `npm install` e `npm run build` do frontend são chamados com `shell: true` (o wrapper `cmd.exe`/`npm.cmd` entra na conta) — ambos agora com `windowsHide: true`, sem piscar tela preta
+- Saída preservada: o instalador mantém `stdio: 'inherit'`, então o progresso continua visível **no console que o usuário já abriu** — só a janela extra deixa de existir (verificado empiricamente no Windows)
+- **Helper Python único e obrigatório**: `backend/core/proc.py` expõe `run_silent_process` / `run_silent` / `spawn_silent` / `call_silent` / `check_output_silent` / `system_silent`, aplicando `CREATE_NO_WINDOW = 0x08000000` via `creationflags` no Windows. O pipeline e o APScheduler rodam em memória (threads do `BackgroundScheduler`), sem processos do SO; o helper é o ponto único para qualquer subprocesso futuro
+- **Teste de regressão ampliado e validado**: `scripts/test-start-isolation.mjs` deixa de olhar só o `start.js` e passa a varrer **todos** os pontos de entrada — `start.js`, `install.js`, `build.js` e `bin/cli.js` — exigindo `windowsHide: true` em cada `spawn`/`spawnSync`/`exec`/`execSync` (inclusive quando as opções vêm de constante compartilhada, ex. `...SILENT_WINDOWS`)
+- O teste também trava regressões do backend Python: qualquer `subprocess.run/Popen/call/check_output/check_call` ou `os.system`/`os.popen` direto em `backend/**/*.py` falha o build (precisa passar por `backend.core.proc`)
+- E ainda barra `uvicorn` com `--reload`/`--workers` no launcher — cada worker é um processo filho extra que, no Windows, pode alocar console próprio e ignorar as flags do pai
+- **Guard verificado por mutação**: com a flag removida do `pip`, com um `subprocess.run` direto no backend e com `--reload` no uvicorn, o teste falha em todos os casos (exit 1) — não é carimbo de borracha
+- Nota de transparência: a colisão de versão com o 0.4.03 já publicado no registry foi resolvida por renumeração, conforme a regra de sessões simultâneas do AGENTS.md
+
+## 0.4.03 (2026-11-08)
+
+- **Regra permanente no AGENTS.md**: é PROIBIDO criar/publicar versões que abram janelas de terminal (CMD/PowerShell/console Python) no computador do usuário — todo processo filho deve nascer com `windowsHide: true` + grupo isolado, rodar em background com saída apenas em log e ser encerrado por código; versão que exiba janela de console é inválida (hotfix + CHANGELOG)
+- Teste de regressão reforçado: varre **todas** as chamadas `spawn`/`spawnSync` do launcher e falha se qualquer uma perder `windowsHide`/`detached` — o CI passa a barrar isso automaticamente
+- `taskkill` do encerramento gracioso também com `detached: true` (uniformidade da regra)
+
 ## 0.4.02 (2026-11-08)
 
 - **Seletor dinâmico de modelos NVIDIA NIM**: novo endpoint proxy `GET /api/v1/configuracoes/llm/nvidia/models` que consulta a NVIDIA em tempo real com a chave do usuário — a API key nunca é exposta ao frontend/Network tab

package/backend/app/main.py

@@ -31,7 +31,7 @@ async def lifespan(_: FastAPI):
     scheduler.parar()
 
 
-app = FastAPI(title="PandaNews API", version="0.4.2", lifespan=lifespan)
+app = FastAPI(title="PandaNews API", version="0.4.4", lifespan=lifespan)
 
 app.add_middleware(
     CORSMiddleware,

package/backend/core/proc.py

@@ -0,0 +1,89 @@
+"""Processos filhos silenciosos (regra permanente do AGENTS.md).
+
+O PandaNews NUNCA pode abrir janelas de terminal (CMD, PowerShell, console
+Python) no computador do usuário. No Windows, todo processo filho precisa da
+flag ``CREATE_NO_WINDOW`` (0x08000000); sem ela, qualquer ``subprocess`` ou
+gerador de console aloca uma tela preta.
+
+Este módulo é o ÚNICO ponto de entrada autorizado para subprocessos no
+backend. Nunca chame ``subprocess.run``/``subprocess.Popen``/``subprocess.call``
+nem ``os.system`` diretamente — use ``run_silent_process``/``run_silent``/
+``spawn_silent``. O teste ``scripts/test-start-isolation.mjs`` (rodado no CI)
+falha o build se encontrar uma chamada direta em ``backend/**/*.py``.
+
+Exemplos::
+
+    from backend.core.proc import run_silent_process, spawn_silent
+
+    # execução síncrona
+    run_silent_process(["ffmpeg", "-version"], check=True, capture_output=True)
+
+    # execução assíncrona (não bloqueia o event loop)
+    proc = spawn_silent(["pandoc", "--version"])
+    proc.wait()
+
+O pipeline de notícias e o APScheduler rodam em memória (threads do
+``BackgroundScheduler``), sem processos do sistema operacional — este módulo
+só é necessário quando uma ferramenta externa realmente precisa ser chamada.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+
+# Flag do Windows: o processo nasce sem console, portanto sem janela visível.
+# Ver https://learn.microsoft.com/windows/win32/procthread/process-creation-flags
+CREATE_NO_WINDOW = 0x08000000
+
+
+def silent_kwargs(kwargs: dict | None = None) -> dict:
+    """Devolve as opções de subprocesso com a flag de ocultação aplicada.
+
+    Em Windows adiciona ``creationflags=CREATE_NO_WINDOW``; nas demais
+    plataformas não há console novo a ocultar, então as opções passam
+    intactas. Nunca use ``shell=True`` junto a este helper.
+    """
+    opts = dict(kwargs or {})
+    if sys.platform == "win32":
+        opts["creationflags"] = CREATE_NO_WINDOW
+    return opts
+
+
+def run_silent_process(cmd_args, **kwargs):
+    """Substitui ``subprocess.run`` — sem janela de console no Windows."""
+    return subprocess.run(cmd_args, **silent_kwargs(kwargs))
+
+
+# Alias: mesma semântica, nome curto para uso interno.
+run_silent = run_silent_process
+
+
+def spawn_silent(cmd_args, **kwargs):
+    """Substitui ``subprocess.Popen`` — sem janela de console no Windows."""
+    return subprocess.Popen(cmd_args, **silent_kwargs(kwargs))
+
+
+def call_silent(cmd_args, **kwargs):
+    """Substitui ``subprocess.call`` — sem janela de console no Windows."""
+    return subprocess.call(cmd_args, **silent_kwargs(kwargs))
+
+
+def check_output_silent(cmd_args, **kwargs):
+    """Substitui ``subprocess.check_output`` — sem janela de console no Windows."""
+    return subprocess.check_output(cmd_args, **silent_kwargs(kwargs))
+
+
+def system_silent(cmd: str) -> int:
+    """Substitui ``os.system`` sem abrir shell visível.
+
+    ``os.system`` sempre passa por ``cmd.exe``/``/bin/sh`` e herda o console;
+    quando não há alternativa, a chamada é feita pelo helper silencioso.
+    """
+    if sys.platform == "win32":
+        proc = subprocess.run(
+            cmd,
+            shell=True,
+            creationflags=CREATE_NO_WINDOW,
+        )
+        return proc.returncode
+    return subprocess.call(cmd, shell=True)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/pandanews",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "SaaS local de criação e automação de múltiplos blogs de notícias com IA (FastAPI + React + Tailwind).",
   "license": "MIT",
   "type": "module",

package/scripts/build.js

@@ -15,12 +15,18 @@ export async function runBuild() {
     return;
   }
   const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  // Regra permanente (AGENTS.md): NENHUM spawn pode abrir janela de console
+  // no computador do usuário. No Windows o filho nasce com CREATE_NO_WINDOW
+  // (windowsHide: true) — com `shell: true` o wrapper cmd.exe também nasce
+  // oculto, sem piscar tela preta. O stdio segue 'inherit': a saída fica no
+  // console que o usuário já abriu.
+  const SILENT_WINDOWS = { windowsHide: true };
   console.log('Instalando dependências do frontend...');
   // shell: true — obrigatório para .cmd no Windows (Node >= 18)
-  const install = spawnSync(npmCmd, ['install'], { cwd: frontendDir, stdio: 'inherit', shell: true });
+  const install = spawnSync(npmCmd, ['install'], { cwd: frontendDir, stdio: 'inherit', shell: true, ...SILENT_WINDOWS });
   if (install.status !== 0) throw new Error('Falha ao instalar dependências do frontend.');
   console.log('Compilando o frontend...');
-  const build = spawnSync(npmCmd, ['run', 'build'], { cwd: frontendDir, stdio: 'inherit', shell: true });
+  const build = spawnSync(npmCmd, ['run', 'build'], { cwd: frontendDir, stdio: 'inherit', shell: true, ...SILENT_WINDOWS });
   if (build.status !== 0) throw new Error('Falha ao compilar o frontend.');
   console.log('Frontend compilado em frontend/dist.');
 }

package/scripts/install.js

@@ -21,6 +21,20 @@ import fse from 'fs-extra';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 export const PKG_ROOT = join(__dirname, '..');
 
+// ------------------------------------------------------------------------
+// Regra permanente (AGENTS.md): é PROIBIDO abrir janelas de terminal (CMD,
+// PowerShell, console Python) no computador do usuário. Todo processo filho
+// lançado pelo instalador nasce no Windows com `windowsHide: true`, que aplica
+// a flag CREATE_NO_WINDOW — nenhuma tela preta aparece.
+//
+// `detached: true` NÃO é usado aqui de propósito: essas chamadas são curtas
+// (tar/venv/pip) e o `stdio: 'inherit'` mantém o progresso no console que o
+// usuário JÁ abriu. Com CREATE_NO_WINDOW o filho escreve nos handles herdados
+// sem alocar uma janela extra. O teste scripts/test-start-isolation.mjs varre
+// este arquivo e falha o build se qualquer spawn perder o windowsHide.
+// ------------------------------------------------------------------------
+const SILENT_WINDOWS = { windowsHide: true };
+
 const PYTHON_VERSION = '3.12.7';
 const PYTHON_RELEASE = '20241016';
 
@@ -152,7 +166,7 @@ async function downloadPython(home, platform) {
   const buf = Buffer.from(await res.arrayBuffer());
   writeFileSync(archive, buf);
   console.log(`Download concluído (${(buf.length / 1024 / 1024).toFixed(1)} MB). Extraindo...`);
-  const tar = spawnSync('tar', ['-xzf', archive, '-C', runtimeDir]);
+  const tar = spawnSync('tar', ['-xzf', archive, '-C', runtimeDir], SILENT_WINDOWS);
   if (tar.status !== 0) throw new Error('Falha ao extrair o Python portátil (tar).');
   if (!existsSync(pythonBin(home))) {
     throw new Error('Extração do Python concluída, mas o binário não foi encontrado.');
@@ -162,7 +176,10 @@ async function downloadPython(home, platform) {
 
 function createVenv(home) {
   console.log('Criando virtualenv...');
-  const venv = spawnSync(pythonBin(home), ['-m', 'venv', join(home, '.runtime', 'venv')], { stdio: 'inherit' });
+  const venv = spawnSync(pythonBin(home), ['-m', 'venv', join(home, '.runtime', 'venv')], {
+    stdio: 'inherit',
+    ...SILENT_WINDOWS,
+  });
   if (venv.status !== 0) throw new Error('Falha ao criar o virtualenv.');
   if (!existsSync(venvBin(home))) throw new Error('Virtualenv criado, mas o binário não foi encontrado.');
 }
@@ -173,7 +190,7 @@ function installDeps(home) {
   const pip = spawnSync(
     venvBin(home),
     ['-m', 'pip', 'install', '--disable-pip-version-check', '-r', req],
-    { stdio: 'inherit' },
+    { stdio: 'inherit', ...SILENT_WINDOWS },
   );
   if (pip.status !== 0) throw new Error('Falha ao instalar as dependências do backend.');
 }

package/scripts/start.js

@@ -87,7 +87,7 @@ async function findFreePort(base, maxTries) {
 function encerrarPorPid(pid, motivo) {
   try {
     if (process.platform === 'win32') {
-      spawnSync('taskkill', ['/pid', String(pid), '/f', '/t'], { windowsHide: true });
+      spawnSync('taskkill', ['/pid', String(pid), '/f', '/t'], { windowsHide: true, detached: true });
     } else {
       process.kill(pid, 'SIGTERM');
     }

package/scripts/test-start-isolation.mjs

@@ -1,20 +1,134 @@
-// Teste de regressão do isolamento de processos do launcher (scripts/start.js).
+// Teste de regressão do isolamento de processos (regra permanente do AGENTS.md):
+// NENHUM spawn/exec do launcher/instalador pode abrir janela de terminal (CMD,
+// PowerShell, console Python) no computador do usuário.
 //
-// Falha se as flags de isolamento forem removidas: detached (novo grupo de
-// processos — imune a Ctrl+C do console no Windows), windowsHide (sem janela
-// fantasma), stdio no arquivo (backend sobrevive ao terminal), unref e o
-// arquivo backend.pid (encerramento gracioso por código).
+// Cobre TODOS os pontos de entrada:
+//   scripts/start.js    — backend uvicorn + taskkill
+//   scripts/install.js  — tar / venv / pip
+//   scripts/build.js    — npm.cmd install e run build (shell: true)
+//   bin/cli.js          — despacho de comandos
+//   backend/**/*.py     — nenhuma chamada direta a subprocess/os.system
 //
 // Roda em qualquer plataforma, inclusive no CI (Linux/ubuntu) — sem exigir o
 // runtime Python completo.
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
-const src = readFileSync(join(root, 'scripts', 'start.js'), 'utf8');
 
-const verificacoes = [
+const falhas = [];
+
+function assert(condicao, mensagem) {
+  console.log(`${condicao ? 'PASS' : 'FAIL'} — ${mensagem}`);
+  if (!condicao) falhas.push(mensagem);
+}
+
+// ---------------------------------------------------------------- utilidades
+
+// Extrai o conteúdo entre delimitadores balanceados, começando em `inicio`
+// (índice do delimitador de abertura). Ignora delimitadores dentro de strings.
+function ateOFechamento(src, inicio, abre, fecha) {
+  let profundidade = 1;
+  let aspa = null;
+  let escapando = false;
+  for (let i = inicio + 1; i < src.length; i++) {
+    const c = src[i];
+    if (escapando) {
+      escapando = false;
+      continue;
+    }
+    if (c === '\\') {
+      escapando = true;
+      continue;
+    }
+    if (aspa) {
+      if (c === aspa) aspa = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      aspa = c;
+      continue;
+    }
+    if (c === abre) profundidade += 1;
+    else if (c === fecha) {
+      profundidade -= 1;
+      if (profundidade === 0) return src.slice(inicio + 1, i);
+    }
+  }
+  return src.slice(inicio + 1);
+}
+
+// Texto completo dos argumentos de uma chamada, a partir do '(' encontrado.
+function argumentosDaChamada(src, indiceAbre) {
+  return ateOFechamento(src, indiceAbre, '(', ')');
+}
+
+// Objetos literais de nível de módulo (const NOME = { ... }) — servem para
+// resolver spreads como `...SILENT_WINDOWS` dentro das opções de spawn.
+function constantesDeModulo(src) {
+  const mapa = new Map();
+  const regex = /const\s+([A-Za-z_$][\w$]*)\s*=\s*\{/g;
+  let m;
+  while ((m = regex.exec(src)) !== null) {
+    const inicioChaves = m.index + m[0].length - 1;
+    mapa.set(m[1], ateOFechamento(src, inicioChaves, '{', '}'));
+  }
+  return mapa;
+}
+
+// Uma referência a constante (solta ou via spread `...NOME`) é silenciosa
+// apenas se a constante NOME trouxer windowsHide.
+function referenciaConstanteSilenciosa(argTexto, constantes) {
+  const regex = /([A-Za-z_$][\w$]*)/g;
+  let m;
+  while ((m = regex.exec(argTexto)) !== null) {
+    const definicao = constantes.get(m[1]);
+    if (definicao && /windowsHide:\s*true/.test(definicao)) return true;
+  }
+  return false;
+}
+
+// ------------------------------------------------------------ varredura JS
+
+const PONTOS_DE_ENTRADA_JS = ['scripts/start.js', 'scripts/install.js', 'scripts/build.js', 'bin/cli.js'];
+
+for (const relativo of PONTOS_DE_ENTRADA_JS) {
+  const caminho = join(root, relativo);
+  if (!existsSync(caminho)) {
+    assert(false, `${relativo} — arquivo ausente`);
+    continue;
+  }
+  const src = readFileSync(caminho, 'utf8');
+  const constantes = constantesDeModulo(src);
+
+  const chamadas = [...src.matchAll(/\b(spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\(/g)];
+  let silenciosas = 0;
+  for (const chamada of chamadas) {
+    const indiceAbre = chamada.index + chamada[0].length - 1;
+    const texto = argumentosDaChamada(src, indiceAbre);
+    if (/windowsHide:\s*true/.test(texto) || referenciaConstanteSilenciosa(texto, constantes)) {
+      silenciosas += 1;
+    } else {
+      const marca = `${chamada[1]}(${texto.slice(0, 60).replace(/\s+/g, ' ')}…)`;
+      assert(false, `${relativo} — ${marca} sem windowsHide: true (abre janela de console no usuário)`);
+    }
+  }
+  if (chamadas.length === 0) {
+    assert(true, `${relativo} — nenhuma chamada de processo direta (sem risco de janela de console)`);
+  } else {
+    assert(
+      silenciosas === chamadas.length,
+      `${relativo} — ${silenciosas}/${chamadas.length} chamadas de processo com windowsHide: true`,
+    );
+  }
+}
+
+// ------------------------------------------- isolamento do backend (start.js)
+
+const startSrc = readFileSync(join(root, 'scripts', 'start.js'), 'utf8');
+
+for (const [regex, descricao] of [
   [/detached:\s*true/, 'detached: true — grupo de processos próprio (CREATE_NEW_PROCESS_GROUP no Windows)'],
   [/windowsHide:\s*true/, 'windowsHide: true — sem janela de console fantasma'],
   [/stdio:\s*\['ignore',\s*logFd,\s*logFd\]/, "stdio: ['ignore', logFd, logFd] — saída do backend no arquivo (fd)"],
@@ -24,17 +138,81 @@ const verificacoes = [
   [/\.unref\(\)/, 'unref() — launcher não acopla o ciclo de vida ao backend'],
   [/taskkill/, 'encerramento no Windows via taskkill /PID /T (árvore de processos)'],
   [/process\.kill/, 'encerramento no Unix via signal no grupo de processos'],
+]) {
+  assert(regex.test(startSrc), descricao);
+}
+
+// Uvicorn em produção JAMAIS com --reload/--workers: cada worker é um processo
+// filho extra, que no Windows pode alocar console próprio e ignorar as flags
+// do processo pai.
+const uvicornExtras = startSrc.match(/['"]--(?:reload|workers)['"]/g);
+assert(
+  !uvicornExtras,
+  `uvicorn sem --reload/--workers (nenhum processo filho extra no Windows)${
+    uvicornExtras ? ` — encontrado: ${uvicornExtras.join(', ')}` : ''
+  }`,
+);
+
+// ------------------------------------------------ varredura Python (backend)
+
+const PROC_HELPER = join(root, 'backend', 'core', 'proc.py');
+assert(existsSync(PROC_HELPER), 'backend/core/proc.py — helper silencioso existe (ponto único de subprocesso)');
+if (existsSync(PROC_HELPER)) {
+  const procSrc = readFileSync(PROC_HELPER, 'utf8');
+  assert(/CREATE_NO_WINDOW\s*=\s*0x08000000/.test(procSrc), 'CREATE_NO_WINDOW = 0x08000000 definido no helper');
+  assert(/def run_silent_process/.test(procSrc), 'run_silent_process disponível no helper');
+  assert(/creationflags/.test(procSrc), 'helper aplica creationflags no Windows');
+}
+
+// Lista recursiva dos .py do backend (sem __pycache__).
+function listarPy(diretorio, acumulador = []) {
+  for (const entrada of readdirSync(diretorio, { withFileTypes: true })) {
+    if (entrada.name === '__pycache__') continue;
+    const caminho = join(diretorio, entrada.name);
+    if (entrada.isDirectory()) listarPy(caminho, acumulador);
+    else if (entrada.name.endsWith('.py')) acumulador.push(caminho);
+  }
+  return acumulador;
+}
+
+const PADROES_PROIBIDOS = [
+  [/subprocess\.run\(/, 'subprocess.run('],
+  [/subprocess\.Popen\(/, 'subprocess.Popen('],
+  [/subprocess\.call\(/, 'subprocess.call('],
+  [/subprocess\.check_output\(/, 'subprocess.check_output('],
+  [/subprocess\.check_call\(/, 'subprocess.check_call('],
+  [/os\.system\(/, 'os.system('],
+  [/os\.popen\(/, 'os.popen('],
 ];
 
-let falhas = 0;
-for (const [regex, descricao] of verificacoes) {
-  const ok = regex.test(src);
-  console.log(`${ok ? 'PASS' : 'FAIL'} — ${descricao}`);
-  if (!ok) falhas += 1;
+const backendDir = join(root, 'backend');
+let arquivosPy = 0;
+let diretasProibidas = 0;
+if (existsSync(backendDir)) {
+  for (const arquivo of listarPy(backendDir)) {
+    if (arquivo.endsWith(join('core', 'proc.py'))) continue; // helper autorizado
+    arquivosPy += 1;
+    const conteudo = readFileSync(arquivo, 'utf8');
+    const relativo = arquivo.slice(root.length + 1);
+    for (const [regex, rotulo] of PADROES_PROIBIDOS) {
+      if (regex.test(conteudo)) {
+        diretasProibidas += 1;
+        assert(false, `${relativo} — uso direto de ${rotulo} sem CREATE_NO_WINDOW (use backend.core.proc)`);
+      }
+    }
+  }
 }
+assert(arquivosPy > 0, `backend/ — ${arquivosPy} arquivos .py varridos`);
+assert(
+  diretasProibidas === 0,
+  'nenhuma chamada direta a subprocess/os.system no backend (todas via helper silencioso)',
+);
+
+// -------------------------------------------------------------- veredicto
 
-if (falhas > 0) {
-  console.error(`Isolamento de processos: ${falhas} verificação(ões) falharam.`);
-  process.exit(1);
+if (falhas.length === 0) {
+  console.log('Isolamento de processos: todas as verificações passaram.');
+  process.exit(0);
 }
-console.log('Isolamento de processos: todas as verificações passaram.');
+console.error(`Isolamento de processos: ${falhas.length} verificação(ões) falharam.`);
+process.exit(1);