O que é o pscan?

pscan é um utilitário de terminal que facilita encontrar e encerrar processos que ocupam uma porta específica. Em vez de encadear comandos lsof, grep e kill na memória, você executa pscan e seleciona o processo que deseja encerrar em uma lista interativa.

É a ferramenta que você busca quando address already in use aparece e você só quer resolver rápido.

O Problema que Resolve

Conflitos de porta são um atrito constante no desenvolvimento. O fluxo padrão envolve três comandos:

lsof -ti :3000       # encontrar PID
kill -9 <PID>        # encerrar

Funciona uma vez, mas depois de digitar isso pela centésima vez — e errar no PID — você começa a querer algo mais inteligente. O pscan envolve todo esse fluxo em um único comando interativo.

Funcionalidades Principais

Escaneamento interativo de portas

Execute pscan e informe a porta que deseja inspecionar. O pscan consulta a tabela de processos do OS e retorna todos os processos correspondentes com seu PID, nome e linha de comando.

pscan 3000
# Encontrados 2 processos na porta 3000:
#   [1] node (PID 8421) — next dev
#   [2] python (PID 9033) — http.server
# Encerrar qual? (1/2/all/none)

Seguro por padrão

O pscan sempre pede confirmação antes de enviar um sinal. Você pode passar --force para pular o prompt em scripts, mas o padrão é sempre interativo.

Suporte a múltiplos processos

Se vários processos compartilham uma porta (por exemplo, durante um hot-reload com falha), o pscan lista todos e permite encerrar um ou todos de uma vez.

Controle de sinal

O sinal de kill padrão é SIGTERM (gracioso). Passe --force para usar SIGKILL quando um processo não termina.

pscan 3000 --force   # SIGKILL, sem confirmação
pscan 8080           # SIGTERM interativo

Instalação

npm install -g pscan

Requisitos: Node.js ≥ 18, macOS ou Linux.

Stack Tecnológica

• TypeScript — modo strict, compilado para um único ponto de entrada CLI
• execa — execução de processos para lsof e kill
• inquirer — prompts interativos no terminal
• meow — parsing de argumentos CLI

Filosofia de Design

O pscan faz uma coisa: encontrar processos por porta e oferecer uma forma limpa de encerrá-los. Sem arquivos de configuração, sem plugins, sem serviços em segundo plano. Ele delega para as ferramentas do OS que já existem (lsof, kill) e adiciona uma interface fina e amigável por cima.