GBR SSG: Servidor de Live Preview (Dev Server)

Este documento especifica a arquitetura e os requisitos EARS para a adição de um servidor web local na aplicação CLI gbr_ssg, permitindo a visualização das páginas estáticas geradas em tempo real.

1. Estratégia de Servidor HTTP com Wisp & Mist

Para manter o acoplamento baixo e as dependências isoladas (Regra de Arquitetura Sustentável), o servidor HTTP será implementado exclusivamente na aplicação CLI (apps/gbr_ssg). O core do SSG (packages/gbr_ssg_core) permanecerá puramente focado em compilação estática de documentos (I/O livre de rede).

• *Servidor HTTP Mist:* Atua como o adaptador HTTP que escuta na porta e endereço especificados, repassando as conexões de baixo nível para a aplicação.
• *Middleware Wisp:* Trata as requisições HTTP e provê utilitários de tratamento de rotas, logs e respostas.
• *Serviço de Estáticos Nativo:* Utilizaremos wisp.serve_static para a entrega eficiente dos arquivos estáticos diretamente do disco para o cliente.
• *Mapeamento Resiliente:* 1. O roteador primeiro tenta servir o arquivo estático diretamente correspondente a partir de wisp.serve_static. 2. Se a requisição cair no fallback do serve_static (arquivo físico exato não encontrado): - Caso o caminho corresponda a um diretório físico contendo um arquivo index.html (ex: /blog ou /blog/), o roteador deve servir /blog/index.html. - Caso contrário, se o caminho não possuir extensão e existir o arquivo .html equivalente (ex: /blog/primeiro-post mapeia para /blog/primeiro-post.html), o roteador deve ler e retornar esse arquivo. - Se nenhuma das opções acima for satisfeita, o servidor retornará um erro 404 Not Found amigável.

2. Requisitos EARS

*Requisitos Ubíquos (Ubiquitous Requirements)* - *UBQ-01:* O gbr_ssg deve fornecer o comando CLI serve para subir um servidor de visualização local. - *UBQ-02:* O comando serve deve aceitar a flag --dir para configurar a pasta de onde as páginas estáticas serão lidas (padrão: ./dist). - *UBQ-03:* O comando serve deve aceitar a flag --port para configurar a porta de rede em que o servidor irá escutar (padrão: 8080). - *UBQ-04:* O servidor deve utilizar a função nativa wisp.serve_static mapeada sob a rota raiz "/" para a entrega de ativos físicos.

*Requisitos Orientados a Eventos (Event-Driven Requirements)* - *EVD-01:* Quando uma requisição GET para um diretório (ex: /blog) for interceptada e a página exata não existir, o servidor deve servir a página index correspondente (/blog/index.html). - *EVD-02:* Quando uma requisição GET para um caminho sem extensão (ex: /sobre) for interceptada e a página exata não existir, o servidor deve buscar e servir a página com a extensão .html correspondente (ex: /sobre.html).

*Requisitos de Comportamento Indesejado (Unwanted Behavior Requirements)* - *UNW-01:* Se a URL requisitada não corresponder a nenhuma página estática ou fallback resiliente, o servidor deve retornar o status 404 Not Found. - *UNW-02:* Se a porta especificada pela flag --port já estiver em uso por outro processo no sistema operacional, o servidor do SSG deve encerrar a inicialização com uma mensagem descritiva no console informando que a porta está ocupada.