@danhachuel/pandanews 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+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.1.01 (2026-10-23)
+
+- README reescrito para o fluxo de um único comando via npx (padrão Thunderbolt): `npx @danhachuel/pandanews` instala tudo junto e sobe o app; removidas as instruções manuais de desenvolvimento (pip, uvicorn, npm)
+- Instalador completo (`pandanews install`): download de Python 3.12.7 portátil (python-build-standalone), criação de virtualenv e instalação de todas as dependências do backend em um único passo — nenhum Python pré-instalado necessário (antecipação do núcleo da Fase 4)
+- `pandanews` (start) agora sobe o backend FastAPI em 127.0.0.1:8000, serve página em 127.0.0.1:3030 e abre o navegador automaticamente; instala o runtime sozinho na primeira execução
+- Tratamento de porta ocupada (EADDRINUSE) com mensagem clara; portas configuráveis via `PANDANEWS_API_PORT` / `PANDANEWS_UI_PORT` e sem processos órfãos no encerramento
+- CORS habilitado no backend para a UI local (127.0.0.1:3030)
+
+## 0.1.00 (2026-10-23)
+
+Bootstrap inicial do repositório PandaNews.
+
+- Estrutura base de pastas: `bin/`, `scripts/`, `backend/` (app + core), `frontend/`, `.github/workflows/`
+- `AGENTS.md` com as regras permanentes do projeto (versionamento de dois dígitos, push obrigatório, release via GitHub Actions, CHANGELOG obrigatório, sessões simultâneas)
+- `package.json` com pacote `@danhachuel/pandanews` e binário `pandanews`
+- CLI `pandanews` com comandos `install`, `start` e `build` (instalação estrutural funcional; Python portátil chega na 0.2.00, Fase 4)
+- Workflow `publish-npm.yml`: validação de metadados, smoke test do instalador, publicação com dist-tag `next` via dispatch e promoção a `latest` via tags `vX.Y.ZZ`
+- Correção do passo `Apply requested version`: a etiqueta visual de dois dígitos (ex.: `0.1.00`) é normalizada para semver canônico (ex.: `0.1.0`) antes do `npm version` — o primeiro dispatch falhou com "Version not changed"
+- `README.md`, `LICENSE` (MIT), `.gitignore`, `CHANGELOG.md`
+- Release placeholder no registry npm para criar o pacote `@danhachuel/pandanews`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DanHachuel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# PandaNews
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SaaS **local** (roda no navegador) para criação e automação de múltiplos blogs de notícias com IA.
+
+- Blogs multi-tenant com tema (esporte, política, economia, tecnologia, geral) e recorte regional
+- Coleta de feeds RSS → redação via LLM com fallback **NVIDIA NIM → Google Gemini**
+- Imagens fotojornalísticas via Gemini Image
+- Fluxo editorial: rascunho → revisão humana opcional → aprovado/publicado
+- 100% local por padrão (SQLite + arquivos), com Supabase opcional
+- Agendamento automático por blog (APScheduler)
+
+## Instalação e uso — um único comando
+
+CMD / MobaXterm:
+
+```
+npx.cmd --yes --prefer-online @danhachuel/pandanews
+```
+
+Shell (PowerShell, Linux, macOS):
+
+```
+npx --yes @danhachuel/pandanews
+```
+
+Na primeira execução o PandaNews instala **tudo junto, automaticamente**: runtime Python portátil, dependências do backend e banco de dados local (SQLite). Nenhum Python, pip ou outra dependência pré-instalada é necessária — apenas **Node.js >= 20**.
+
+Opcional — pré-instalar antes do primeiro uso:
+
+```
+npx.cmd --yes --prefer-online @danhachuel/pandanews install
+npx --yes @danhachuel/pandanews install
+```
+
+O runtime fica em `.runtime/` na raiz do pacote (sobrescreva com a variável de ambiente `PANDANEWS_HOME`).
+
+## Status (versão 0.1.01)
+
+- `npx @danhachuel/pandanews` instala tudo junto (Python portátil + dependências + banco local) e sobe o backend em 127.0.0.1:8000 com página em 127.0.0.1:3030
+- A UI React completa (Dashboard, Blogs, Notícias, Imagens, Automação, Configurações) e o pipeline de notícias chegam nas próximas versões (Fases 1 a 3 do plano — ver `CHANGELOG.md`)
+
+## Regras do projeto
+
+Versionamento (PATCH de dois dígitos), release via GitHub Actions, CHANGELOG obrigatório e demais regras permanentes estão em [`AGENTS.md`](AGENTS.md).
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

package/backend/__init__.py

@@ -0,0 +1 @@
+"""PandaNews — pacote backend (entrypoint: backend.app.main:app)."""

package/backend/app/__init__.py

@@ -0,0 +1 @@
+"""PandaNews — aplicação backend (FastAPI)."""

package/backend/app/main.py

@@ -0,0 +1,21 @@
+"""PandaNews API — FastAPI.
+
+Fase 0/1: aplicação mínima com endpoint de health e CORS liberado para a UI
+local (127.0.0.1:3030). CRUD de blogs e configurações chegam na Fase 1.
+"""
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+app = FastAPI(title="PandaNews API", version="0.1.1")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3030", "http://127.0.0.1:3030"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/api/v1/health")
+def health() -> dict:
+    return {"status": "ok", "service": "pandanews", "version": app.version}

package/backend/app/routers/__init__.py

@@ -0,0 +1 @@
+"""Routers do PandaNews: blogs, noticias, configuracoes, imagens, health (Fase 1+)."""

package/backend/app/schemas.py

@@ -0,0 +1 @@
+"""Schemas Pydantic do PandaNews (preenchidos na Fase 1)."""

package/backend/core/__init__.py

@@ -0,0 +1 @@
+"""Core do PandaNews: config, database, llm_router, image_gen, pipeline."""

package/backend/core/config.py

@@ -0,0 +1 @@
+"""Configuração de runtime do PandaNews (Fase 1): .env, caminhos e constantes."""

package/backend/core/database.py

@@ -0,0 +1,6 @@
+"""Camada de dados do PandaNews (Fase 1).
+
+SQLite local por padrão (data/pandanews.db) via SQLAlchemy 2.0, com detecção
+automática de Supabase quando SUPABASE_URL e SUPABASE_SERVICE_ROLE_KEY estão
+definidas no ambiente. Tabelas: blogs, noticias, configuracoes, logs.
+"""

package/backend/core/image_gen.py

@@ -0,0 +1,6 @@
+"""Geração de imagens do PandaNews (Fase 3).
+
+Gemini Image API com prompt fotojornalístico a partir de palavras-chave da
+notícia; imagens salvas em data/imagens/{noticia_id}.png. Se falhar, a notícia
+segue sem imagem e é sinalizada na UI para ação manual.
+"""

package/backend/core/llm_router.py

@@ -0,0 +1,6 @@
+"""Router de LLM do PandaNews (Fase 1).
+
+Fallback ordenado configurável (padrão: NVIDIA NIM -> Google Gemini) usando
+llmswitch-client: roteamento por prioridade com circuit breaker. Retorna o
+texto gerado e o provedor que respondeu (registrado em noticias.llm_provider).
+"""

package/backend/core/pipeline.py

@@ -0,0 +1,6 @@
+"""Pipeline de notícias do PandaNews (Fase 3).
+
+Coleta RSS -> filtragem por relevância -> rascunho via LLM -> imagem via Gemini
+-> revisão humana opcional -> publicação. Disparado por APScheduler conforme a
+frequência de cada blog ou manualmente pela interface.
+"""

package/backend/requirements.txt

@@ -0,0 +1,10 @@
+fastapi>=0.115,<1
+uvicorn[standard]>=0.34,<1
+sqlalchemy>=2.0.36,<3
+pydantic>=2.9,<3
+apscheduler>=3.10,<4
+feedparser>=6.0.11,<7
+httpx>=0.27,<1
+python-dotenv>=1.0,<2
+llmswitch-client==0.0.1
+supabase>=2.6,<3

package/bin/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// PandaNews CLI (@danhachuel/pandanews)
+// Comandos: install | start (padrão) | build | help | version
+import { readFileSync } from 'node:fs';
+import { runInstall } from '../scripts/install.js';
+import { runStart } from '../scripts/start.js';
+import { runBuild } from '../scripts/build.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const args = process.argv.slice(2);
+const command = args.find((a) => !a.startsWith('--')) || 'start';
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+
+function printHelp() {
+  console.log(`
+PandaNews ${pkg.version} — automação de blogs de notícias com IA
+
+Uso:
+  pandanews install   Prepara o runtime local (estrutura + Python portátil)
+  pandanews           Inicia backend (127.0.0.1:8000) e UI (127.0.0.1:3030)
+  pandanews build     Compila o frontend de desenvolvimento
+
+Opções:
+  --skip-python-deps  Instalação estrutural sem Python (uso em CI)
+  --help              Mostra esta ajuda
+  --version           Mostra a versão
+`);
+}
+
+async function main() {
+  if (flags.has('--help') || command === 'help') {
+    printHelp();
+    return;
+  }
+  if (flags.has('--version') || command === 'version') {
+    console.log(pkg.version);
+    return;
+  }
+  if (command === 'install') {
+    await runInstall({ skipPythonDeps: flags.has('--skip-python-deps') });
+  } else if (command === 'start') {
+    await runStart();
+  } else if (command === 'build') {
+    await runBuild();
+  } else {
+    console.error(`Comando desconhecido: ${command}`);
+    printHelp();
+    process.exitCode = 1;
+  }
+}
+
+main().catch((err) => {
+  console.error(`pandanews: ${err && err.message ? err.message : err}`);
+  process.exitCode = 1;
+});

package/frontend/README.md

@@ -0,0 +1,8 @@
+# frontend/
+
+UI do PandaNews (React + Vite + Tailwind), inicializada na Fase 2 do plano de implementação.
+
+- Páginas: Dashboard, Blogs, Notícias, Imagens, Automação, Configurações, Logs
+- Sidebar + topbar no padrão Leadmaster
+- 7 leis de usabilidade aplicadas (Fitts, Hick, Zeigarnik, Jakob, Gradiente de Meta, von Restorff, Miller)
+- Build: `npm run build` → `dist/` servido em 127.0.0.1:3030

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@danhachuel/pandanews",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+  "bin": {
+    "pandanews": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "backend/",
+    "frontend/dist/",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build:frontend": "node scripts/build.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DanHachuel/PandaNews.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DanHachuel/PandaNews/issues"
+  },
+  "homepage": "https://github.com/DanHachuel/PandaNews#readme",
+  "keywords": [
+    "news",
+    "blog",
+    "ai",
+    "automation",
+    "rss",
+    "llm"
+  ],
+  "author": "DanHachuel",
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "extract-zip": "^2.0.1",
+    "fs-extra": "^11.3.0",
+    "node-fetch": "^3.3.2",
+    "open": "^10.2.0",
+    "ora": "^8.2.0"
+  }
+}

package/scripts/build.js

@@ -0,0 +1,25 @@
+// Compila o frontend de desenvolvimento (frontend/ -> frontend/dist).
+// A UI React + Vite + Tailwind é inicializada na Fase 2 do plano.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+
+export async function runBuild() {
+  const frontendDir = join(PKG_ROOT, 'frontend');
+  if (!existsSync(join(frontendDir, 'package.json'))) {
+    console.log('frontend/ ainda não foi inicializado — chega na Fase 2 (versão 0.2.00).');
+    return;
+  }
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  console.log('Instalando dependências do frontend...');
+  const install = spawnSync(npmCmd, ['install'], { cwd: frontendDir, stdio: 'inherit' });
+  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' });
+  if (build.status !== 0) throw new Error('Falha ao compilar o frontend.');
+  console.log('Frontend compilado em frontend/dist.');
+}

package/scripts/install.js

@@ -0,0 +1,132 @@
+// Instalador do runtime PandaNews.
+//
+// Provisiona tudo em um único comando (padrão Thunderbolt):
+// 1. estrutura de pastas (data/, .runtime/)
+// 2. Python 3.12.7 portátil via python-build-standalone (sem Python pré-instalado)
+// 3. virtualenv em .runtime/venv
+// 4. dependências do backend (backend/requirements.txt)
+// 5. marcadores de estado (.runtime/.ready, .runtime/.python-ready)
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+export const PKG_ROOT = join(__dirname, '..');
+
+const PYTHON_VERSION = '3.12.7';
+const PYTHON_RELEASE = '20241016';
+
+// Raiz de instalação: PANDANEWS_HOME sobrepõe o padrão (raiz do pacote instalado).
+export function resolveHome() {
+  return process.env.PANDANEWS_HOME ? resolve(process.env.PANDANEWS_HOME) : PKG_ROOT;
+}
+
+// Detecta plataforma e asset de python-build-standalone.
+export function detectPlatform() {
+  const arch = process.arch === 'arm64' ? 'aarch64' : 'x86_64';
+  if (process.platform === 'win32') {
+    return { os: 'windows', arch, asset: `${arch}-pc-windows-msvc-shared-install_only.tar.gz` };
+  }
+  if (process.platform === 'darwin') {
+    return { os: 'macos', arch, asset: `${arch}-apple-darwin-install_only.tar.gz` };
+  }
+  return { os: 'linux', arch, asset: `${arch}-unknown-linux-gnu-install_only.tar.gz` };
+}
+
+function pythonArchiveUrl(platform) {
+  const base = 'https://github.com/astral-sh/python-build-standalone/releases/download';
+  return `${base}/${PYTHON_RELEASE}/cpython-${PYTHON_VERSION}+${PYTHON_RELEASE}-${platform.asset}`;
+}
+
+function pythonBin(home) {
+  return process.platform === 'win32'
+    ? join(home, '.runtime', 'python', 'python.exe')
+    : join(home, '.runtime', 'python', 'bin', 'python3');
+}
+
+function venvBin(home) {
+  return process.platform === 'win32'
+    ? join(home, '.runtime', 'venv', 'Scripts', 'python.exe')
+    : join(home, '.runtime', 'venv', 'bin', 'python');
+}
+
+async function downloadPython(home, platform) {
+  const url = pythonArchiveUrl(platform);
+  const runtimeDir = join(home, '.runtime');
+  const downloadsDir = join(runtimeDir, 'downloads');
+  const archive = join(downloadsDir, `cpython-${PYTHON_VERSION}+${PYTHON_RELEASE}-${platform.asset}`);
+  mkdirSync(downloadsDir, { recursive: true });
+  console.log(`Baixando Python ${PYTHON_VERSION} portátil (${platform.os} ${platform.arch})...`);
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Falha no download do Python (${res.status}): ${url}`);
+  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]);
+  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.');
+  }
+  console.log(`Python ${PYTHON_VERSION} pronto em ${join(runtimeDir, 'python')}`);
+}
+
+function createVenv(home) {
+  console.log('Criando virtualenv...');
+  const venv = spawnSync(pythonBin(home), ['-m', 'venv', join(home, '.runtime', 'venv')], { stdio: 'inherit' });
+  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.');
+}
+
+function installDeps(home) {
+  console.log('Instalando dependências do backend (pode levar alguns minutos)...');
+  const req = join(PKG_ROOT, 'backend', 'requirements.txt');
+  const pip = spawnSync(
+    venvBin(home),
+    ['-m', 'pip', 'install', '--disable-pip-version-check', '-r', req],
+    { stdio: 'inherit' },
+  );
+  if (pip.status !== 0) throw new Error('Falha ao instalar as dependências do backend.');
+}
+
+export async function runInstall({ skipPythonDeps = false } = {}) {
+  const home = resolveHome();
+  const platform = detectPlatform();
+
+  console.log(`PandaNews install — plataforma: ${platform.os} (${platform.arch})`);
+  console.log(`Raiz do runtime: ${home}`);
+
+  // Estrutura de pastas do runtime local
+  const dirs = [
+    join(home, 'data'),
+    join(home, 'data', 'imagens'),
+    join(home, '.runtime'),
+  ];
+  for (const dir of dirs) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  if (skipPythonDeps) {
+    console.log('--skip-python-deps: instalação estrutural (uso em CI).');
+  } else if (existsSync(join(home, '.runtime', '.python-ready'))) {
+    console.log('Runtime Python já provisionado — nada a fazer.');
+  } else {
+    if (!existsSync(pythonBin(home))) {
+      await downloadPython(home, platform);
+    } else {
+      console.log('Python portátil já presente.');
+    }
+    if (!existsSync(venvBin(home))) {
+      createVenv(home);
+    } else {
+      console.log('Virtualenv já presente.');
+    }
+    installDeps(home);
+    writeFileSync(join(home, '.runtime', '.python-ready'), new Date().toISOString());
+    console.log('Dependências instaladas. Runtime Python pronto.');
+  }
+
+  writeFileSync(join(home, '.runtime', '.ready'), new Date().toISOString());
+  console.log('Instalação concluída.');
+  return home;
+}

package/scripts/start.js

@@ -0,0 +1,118 @@
+// Inicia o PandaNews: backend FastAPI (127.0.0.1:8000) + UI (127.0.0.1:3030).
+//
+// Fluxo de um único comando (padrão Thunderbolt): se o runtime não estiver
+// provisionado, executa o install completo (Python portátil + dependências)
+// antes de subir os servidores. Ao final, abre o navegador.
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { join, extname } from 'node:path';
+import { resolveHome, runInstall, PKG_ROOT } from './install.js';
+
+const BACKEND_PORT = Number(process.env.PANDANEWS_API_PORT || 8000);
+const UI_PORT = Number(process.env.PANDANEWS_UI_PORT || 3030);
+
+function venvBin(home) {
+  return process.platform === 'win32'
+    ? join(home, '.runtime', 'venv', 'Scripts', 'python.exe')
+    : join(home, '.runtime', 'venv', 'bin', 'python');
+}
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.ico': 'image/x-icon',
+};
+
+function placeholderPage() {
+  return `<!DOCTYPE html>
+<html lang="pt-BR">
+<head><meta charset="utf-8"><title>PandaNews</title></head>
+<body style="font-family: Inter, system-ui, sans-serif; background: #0b1220; color: #e6edf3; display: flex; min-height: 100vh; align-items: center; justify-content: center;">
+  <div style="text-align: center;">
+    <h1 style="font-size: 3rem; margin: 0;">🐼 PandaNews</h1>
+    <p style="color: #9aa7b5;">Backend ativo em <a style="color: #22c55e;" href="http://127.0.0.1:8000/api/v1/health">127.0.0.1:8000</a></p>
+    <p style="color: #9aa7b5;">A UI React completa chega na versão 0.2.00 (Fases 1 a 3 do plano).</p>
+  </div>
+</body>
+</html>`;
+}
+
+function serveUi(onReady) {
+  const distDir = join(PKG_ROOT, 'frontend', 'dist');
+  const server = createServer((req, res) => {
+    const url = req.url.split('?')[0];
+    const filePath = join(distDir, url === '/' ? 'index.html' : url.slice(1));
+    if (!existsSync(filePath)) {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(placeholderPage());
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': MIME[extname(filePath)] || 'application/octet-stream' });
+    res.end(readFileSync(filePath));
+  });
+  server.on('error', (err) => {
+    if (err && err.code === 'EADDRINUSE') {
+      console.error(`A porta ${UI_PORT} já está em uso. Encerre o processo que a ocupa ou defina PANDANEWS_UI_PORT.`);
+    } else {
+      console.error(`Erro no servidor de UI: ${err && err.message}`);
+    }
+    process.exit(1);
+  });
+  server.listen(UI_PORT, '127.0.0.1', onReady);
+  return server;
+}
+
+async function openBrowser(url) {
+  try {
+    const { default: open } = await import('open');
+    await open(url);
+  } catch {
+    /* ambiente sem navegador (ex.: CI) */
+  }
+}
+
+export async function runStart() {
+  const home = resolveHome();
+  if (!existsSync(join(home, '.runtime', '.ready'))) {
+    console.log('Runtime não encontrado — instalando tudo (Python portátil + dependências)...');
+    await runInstall({});
+  }
+  if (!existsSync(venvBin(home))) {
+    console.log('Runtime Python ausente. Execute o comando com `install` primeiro:');
+    console.log('  npx --yes @danhachuel/pandanews install');
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`Iniciando backend FastAPI em http://127.0.0.1:${BACKEND_PORT} ...`);
+  const uvicorn = spawn(
+    venvBin(home),
+    ['-m', 'uvicorn', 'backend.app.main:app', '--host', '127.0.0.1', '--port', String(BACKEND_PORT)],
+    { cwd: PKG_ROOT, stdio: 'inherit' },
+  );
+  uvicorn.on('exit', (code) => {
+    if (code !== 0 && code !== null) {
+      console.error(`Backend encerrou com código ${code}.`);
+      process.exit(code ?? 1);
+    }
+  });
+
+  const server = serveUi(() => {
+    console.log(`PandaNews ativo em http://127.0.0.1:${UI_PORT}`);
+    console.log('Pressione Ctrl+C para encerrar.');
+    openBrowser(`http://127.0.0.1:${UI_PORT}`);
+  });
+
+  process.on('exit', () => {
+    server.close();
+    uvicorn.kill();
+  });
+  process.on('SIGINT', () => process.exit(0));
+  process.on('SIGTERM', () => process.exit(0));
+}