Servent-SSR

Gerador de estrutura, highlight EJS e snippets para o padrão Servent-SSR v7.0 (Fastify)

Crie módulos completos, components encapsulados, pages, partials e testes E2E
com convenções automáticas de CSS e JavaScript — em segundos.

O que é o Servent-SSR

Servent-SSR é um padrão arquitetural para aplicações MPA (Multi-Page Application) construídas com Node.js + Fastify + EJS. A arquitetura organiza o projeto em camadas bem definidas (Shell, Page, Component, Partial) e estabelece convenções explícitas de nomenclatura, encapsulamento e separação de responsabilidades.

A extensão é o braço operacional da plataforma: ela transforma as convenções arquiteturais em código concreto, eliminando trabalho manual repetitivo e garantindo conformidade automática com o padrão.

┌─────────────────────────────────────────────────────────────────┐
│                     SERVENT-SSR ECOSYSTEM                       │
├────────────┬────────────────┬──────────────────┬────────────────┤
│   SHELL    │     PAGE       │   COMPONENT      │   PARTIAL      │
│ index.ejs  │ pages/mod/pag/ │ components/cat/  │ partials/      │
│            │ ├ index.ejs    │ nome/            │ _nome.ejs      │
│ Assets     │ ├ style.css    │ ├ index.ejs      │                │
│ globais    │ └ script.js    │ ├ style.css      │ EJS puro       │
│ de public/ │                │ └ script.js      │ sem CSS/JS     │
└────────────┴────────────────┴──────────────────┴────────────────┘

✨ O que a Extensão Faz

📦 Instalação

Via VSIX (recomendado)

# 1. Clone ou baixe o repositório da extensão
# 2. Empacote (requer Node 20)
nvm use 20 && npm install -g @vscode/vsce
vsce package

# 3. Instale no VS Code
code --install-extension servent-ssr-3.2.0.vsix

Via Marketplace

Pesquise por "Servent-SSR" no painel de extensões do VS Code (Ctrl+Shift+X) ou acesse diretamente pelo Marketplace.

Requisitos

🚀 Primeiros Passos

1. Inicializar um projeto do zero

Ctrl+Shift+P → Servent-SSR: Inicializar Projeto → Confirmar

meu-projeto/
├── server.js                    ← Fastify configurado e pronto
├── package.json                 ← Dependências completas
├── .env                         ← SESSION_SECRET + JWT_SECRET + keys geradas
├── public/
│   ├── css/app.css
│   ├── js/app.js
│   └── vendor/
├── src/
│   ├── infrastructure/
│   │   ├── database/
│   │   │   ├── Repository.js    ← Classe base Sequelize
│   │   │   ├── connection.js
│   │   │   ├── migrator.js      ← Umzug configurado
│   │   │   ├── models/
│   │   │   │   └── user.model.js
│   │   │   └── migrations/
│   │   │       └── 001-create-users.js
│   │   └── plugins/
│   │       ├── session.plugin.js
│   │       ├── flash.plugin.js
│   │       ├── locals.plugin.js  ← reply.render() / reply.renderPublic()
│   │       ├── static.plugin.js
│   │       ├── view.plugin.js
│   │       ├── jwt-auth.plugin.js
│   │       └── auth-guard.js    ← isAuthenticated + requireRole()
│   └── modules/
│       └── auth/                ← Módulo completo de autenticação
│           ├── auth.plugin.js
│           ├── controllers/
│           ├── services/        ← bcrypt + JWT
│           └── domain/
└── src/views/
    ├── index.ejs                ← Shell HTML
    ├── pages/
    │   └── auth/login/          ← Page de login funcional
    │       ├── index.ejs
    │       ├── style.css
    │       └── script.js
    ├── components/
    │   ├── menus/
    │   ├── modals/
    │   └── sidebars/
    └── partials/
        ├── _page-header.ejs
        ├── _empty-state.ejs
        ├── _pagination.ejs
        └── _alert-flash.ejs

Credenciais do admin gerado: [email protected] / Admin@1234 Troque a senha antes do primeiro deploy em produção.

2. Instalar dependências e rodar

npm install
npx playwright install chromium  # instala o browser para testes E2E
npm run dev    # nodemon server.js → http://localhost:3000

3. Criar o primeiro módulo

Ctrl+Shift+P → Servent-SSR: Novo Módulo Completo ✨

Passo 1 — Nome do módulo:

operators

Passo 2 — Pages a criar (multi-select):

☑ list    ☑ detail    ☐ new    ☐ edit

Passo 3 — Components a criar (multi-select):

☑ sidebar-new    ☐ sidebar-edit

Passo 4 — Adicionar ao menu lateral:

☑ Sim → Label: Operators → Rota: /operators

Resultado gerado:

src/modules/operators/
├── operators.plugin.js           ← Two-Plugin Factory
├── controllers/
│   ├── operators.controller.js   ← GET /operators → reply.render()
│   └── operators.api.controller.js ← GET /api/operators → reply.send()
├── services/operators.service.js ← { kind, status, body }
├── repositories/operators.repository.js
└── domain/operators.domain.js

src/views/pages/operators/
├── list/   index.ejs + style.css (.srv-page-operators-list) + script.js
└── detail/ index.ejs + style.css (.srv-page-operators-detail) + script.js

src/views/components/
└── sidebars/new/    index.ejs + style.css + script.js

src/views/components/menus/left/index.ejs   ← item /operators, se escolhido no wizard

tests/unit/operators/operators.service.test.js

O trecho de registro no server.js é copiado automaticamente para o clipboard. Quando a opção de menu é ativada, o item do módulo também é inserido no menu lateral existente.

🧩 Comandos Completos

Todos os comandos estão disponíveis via Ctrl+Shift+P e no menu de contexto do Explorer (botão direito em qualquer pasta).

🗂️ Arquitetura Shell · Page · Component · Partial

┌──────────────────────────────────────────────────────────────────────┐
│  REQUEST HTTP                                                        │
│       ↓                                                              │
│  Fastify Route → preHandler (Guard) → Controller                    │
│                                            ↓                        │
│                                        Service (lógica pura)        │
│                                            ↓                        │
│                                        Repository (Sequelize)       │
│                                            ↓                        │
│                                        reply.render(page, dados)    │
│                                            ↓                        │
│  ┌─── SHELL: src/views/index.ejs ──────────────────────────────┐    │
│  │  Assets globais de public/css/ e public/js/                 │    │
│  │                                                             │    │
│  │  ┌─── PAGE: pages/[modulo]/[pagina]/index.ejs ──────────┐  │    │
│  │  │  <style><%- include('./style.css') %></style>         │  │    │
│  │  │                                                       │  │    │
│  │  │  <%- include('components/modals/detail/index.ejs') %> │  │    │
│  │  │  <%- include('partials/_page-header.ejs') %>          │  │    │
│  │  │                                                       │  │    │
│  │  │  <script><%- include('./script.js') %></script>       │  │    │
│  │  └───────────────────────────────────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│       ↓                                                              │
│  HTML COMPLETO entregue ao browser (sem hydration, sem runtime)     │
└──────────────────────────────────────────────────────────────────────┘

Regras de cada camada

Derivação automática de convenções

components/modals/detail/     →  .srv-modal-detail
                              →  window.Servent.Modals.Detail

components/sidebars/user-new/ →  .srv-sidebar-user-new
                              →  window.Servent.Sidebars.UserNew

pages/operators/documents/list/ →  .srv-page-operators-documents-list
                                →  window.Servent.Pages.OperatorsDocumentsList

A extensão nunca pede ao desenvolvedor que defina o prefixo CSS ou namespace. Eles são calculados automaticamente.

🎨 Highlight EJS

A extensão registra o EJS como linguagem própria com uma grammar TextMate completa. Não é necessária nenhuma configuração adicional.

<%  código JS sem output  %>   ← keyword (laranja/amarelo)
<%= output escapado       %>   ← keyword escaped (verde)
<%- output HTML/unescaped %>   ← keyword unescaped (azul)
<%# comentário EJS        %>   ← comment (cinza)

Antes da extensão:

❌  <script><%-  include('./script.js') %></script>
              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
              Erro de sintaxe sublinhado em vermelho

Depois da extensão:

✅  <script><%- include('./script.js') %></script>
    ← HTML colorido normalmente, tags EJS coloridas corretamente

O autoclose está configurado: ao digitar <%, o VS Code fecha com %> automaticamente.

✅ Validador e Code Actions

O validador analisa arquivos Servent-SSR ao abrir e ao salvar, exibindo diagnósticos diretamente no editor.

Code Actions — Correções com um clique (💡)

🔍 Hover e Go to Definition

Hover (passe o mouse)

Em .ejs — sobre um include():

╔══════════════════════════════════════════╗
║  Servent-SSR — Component                ║
║  📁 modals/detail                       ║
║  🎨 CSS: .srv-modal-detail              ║
║  🔌 JS:  window.Servent.Modals.Detail   ║
║                                          ║
║  Variáveis esperadas:                   ║
║  - title: string                        ║
║  - contentHtml: string                  ║
╚══════════════════════════════════════════╝

Em .js — sobre window.Servent.Modals.Detail:

╔══════════════════════════════════════════╗
║  Servent-SSR — window.Servent.Modals... ║
║                                          ║
║  API pública:                           ║
║  - open()                               ║
║  - close()                              ║
║                                          ║
║  [Abrir script.js]                      ║
╚══════════════════════════════════════════╝

Go to Definition (Ctrl+Click)

🧪 Gerador de Teste E2E

Com qualquer index.ejs de component ou page aberto:

Ctrl+Shift+P → Servent-SSR: Gerar Teste E2E 🧪

A extensão extrai automaticamente do template:

• IDs de elementos → page.locator('#id')
• data-attributes → page.locator('[data-*]')
• Classes .srv-* → page.locator('.srv-*')
• Campos de formulário → page.fill('[name="campo"]', ...)
• Namespace window.Servent → chamadas diretas no teste

Testes gerados por tipo:

O arquivo é salvo em tests/e2e/ espelhando o caminho do artefato e aberto automaticamente no editor.

📦 SpecForge — Importar arquivo .spec

O SpecForge é a ferramenta de especificação do ecossistema Servent-SSR. Ele exporta arquivos .spec (ZIPs renomeados) contendo .claude/skills/, .specs/changes/ e docs/.

Ctrl+Shift+P → Servent-SSR: Inicializar Projeto → 📦 Importar arquivo .spec

O file picker filtra apenas arquivos .spec. Após a extração, o .spec é deletado automaticamente — nenhum rastro fica no projeto.

Estrutura extraída:

projeto/
├── .claude/skills/          ← Skills de arquitetura para o agente AI
├── .specs/
│   ├── changes/             ← Changes prontos para execução
│   └── executar_todas.md    ← Cole no Claude para iniciar
└── docs/                    ← Documentação do projeto

🧪 Gerar Teste Playwright

Botão direito na pasta do componente → Servent-SSR: Gerar Teste Playwright

A extensão lê o script.js, extrai os métodos da API pública e gera um .spec.ts completo em tests/e2e/components/[categoria]/[nome].spec.ts.

Exemplo — dado este script.js:

window.Servent.Modals.Detalhe = {
  open:   open,
  close:  close,
  reload: reload,
};

Gera automaticamente:

• Teste de renderização do elemento raiz (#srv-modal-detalhe)
• Teste de registro do namespace window.Servent.Modals.Detalhe
• Um teste para cada método: open(), close(), reload()

Com módulo de domínio (para evitar conflito entre módulos):

User   → window.Servent.User.Modals.Detalhe
Pedidos → window.Servent.Pedidos.Modals.Detalhe

Para rodar os testes:

npm run dev              # servidor deve estar rodando
npm run test:e2e         # headless
npm run test:e2e:ui      # modo visual
npm run test:e2e:headed  # browser visível

O playwright.config.ts é gerado com baseURL lida automaticamente do .env (sem configuração manual).

🔒 Linter Embutido

O projeto gerado inclui plugins de linting que rodam ao salvar, exibindo erros no painel Problems com sublinhados no código.

ESLint — Regras Servent-SSR

Stylelint — Regras Servent-SSR

npm run lint       # ESLint nos script.js de componentes
npm run lint:css   # Stylelint nos style.css de componentes

Os plugins ficam em tools/eslint-plugin-servent-ssr/ e tools/stylelint-plugin-servent-ssr/ — embutidos no projeto, sem dependência externa.

📝 Snippets EJS

Digite o prefixo em qualquer arquivo .ejs e pressione Tab.

📝 Snippets JavaScript

Digite o prefixo em qualquer arquivo .js e pressione Tab.

📊 Servent Explorer

Um painel dedicado na Activity Bar do VS Code com mapa visual do projeto.

SERVENT EXPLORER
├── 📄 Pages
│   ├── auth
│   │   └── login
│   │       ├── index.ejs  ← clicável
│   │       ├── style.css  ← clicável
│   │       └── script.js  ← clicável
│   └── operators
│       ├── list    → .srv-page-operators-list
│       └── detail  → .srv-page-operators-detail
│
├── 🧩 Components
│   ├── menus
│   ├── modals
│   │   └── detail  → .srv-modal-detail
│   └── sidebars
│       └── new  → .srv-sidebar-new
│
└── 🧱 Partials
    ├── _page-header.ejs
    ├── _empty-state.ejs
    ├── _pagination.ejs
    └── _alert-flash.ejs

O painel atualiza automaticamente ao salvar, criar ou deletar arquivos. O botão ✨ no header abre o Wizard diretamente.

🏗️ Casos de Uso

⚙️ Configurações

📋 Changelog

v3.2.0

• ✅ Novo Módulo Completo aprimorado — wizard agora pergunta se o módulo deve ser adicionado ao menu lateral
• ✅ Menu lateral automático — cria ou atualiza src/views/components/menus/left/index.ejs com label e rota do módulo
• ✅ Detalhe como page — fluxo completo prioriza detail como página, não como modal gerado automaticamente
• ✅ Sidebars integradas às pages — pages criadas recebem botões simples para abrir os sidebars selecionados
• ✅ Títulos nos artefatos gerados — pages e sidebars nascem com títulos visíveis e consistentes
• ✅ Correções de bugs e refinamentos de fluxo — ajustes no wizard para reduzir passos manuais após criar um módulo

v3.1.0

• ✅ Gerar Teste Playwright — botão direito na pasta do componente gera .spec.ts com testes por método
• ✅ Importar arquivo .spec — integração com SpecForge no comando Inicializar Projeto
• ✅ Playwright configurado — playwright.config.ts gerado com baseURL lida do .env
• ✅ Scripts npm E2E — test:e2e, test:e2e:ui, test:e2e:headed adicionados
• ✅ Linter CSS embutido — Stylelint com regra servent-ssr/css-prefix
• ✅ Linter JS embutido — ESLint com regras servent-ssr/namespace e servent-ssr/iife
• ✅ Namespace com módulo de domínio — suporte a window.Servent.User.Modals.Detalhe
• ✅ SQL injection corrigido — Repository.js valida tableName no construtor
• ✅ Umzug + Sequelize + sqlite3 — adicionados ao package.json gerado
• ✅ write() com aviso — alerta quando arquivo já existe em vez de ignorar silenciosamente

v3.0.2

• ✅ EJS Formatter — Shift+Alt+F formata .ejs preservando tags EJS intactas
• ✅ Code Actions (💡) — correções automáticas para todos os diagnósticos
• ✅ Gerador de Teste E2E — Playwright gerado a partir do template .ejs
• ✅ Hover com documentação — assinatura de components e window.Servent.*
• ✅ Go to Definition — Ctrl+Click em include() e window.Servent.*
• ✅ Novos snippets: srv-e2e, srv-e2e-modal

v2.2.0

• ✅ Servent Explorer — painel lateral com mapa visual arquitetural
• ✅ Wizard de módulo completo — fluxo guiado com seleção de pages e components
• ✅ Snippets de migration: srv-migration, srv-migration-table, srv-migration-col
• ✅ Novo comando: Servent-SSR: Novo Partial

v2.1.0

• ✅ Validador em tempo real — DiagnosticCollection com regras de conformidade
• ✅ Highlight EJS — grammar TextMate própria para .ejs
• ✅ Novo comando: Servent-SSR: Validar Arquivo

v2.0.0

• ✅ Estrutura atualizada para Servent-SSR v7.0 (Fastify)
• ✅ Inicializar Projeto gera auth JWT completo com módulo, model, migration e seeder
• ✅ Chaves de ambiente geradas dinamicamente: srvt_local_*, srvt_dev_*, srvt_hmg_*, srvt_prd_*
• ✅ 14 snippets EJS e 17 snippets JS
• ✅ Plugin factory, controllers, services, repositories e domain gerados
• ✅ Novo comando: Servent-SSR: Novo Partial

v1.0.0

• ✅ Comandos básicos: Inicializar Projeto, Novo Módulo, Novo Componente, Nova Page
• ✅ Geração de Plugin Factory, Controller, Service, Repository, Domain
• ✅ Suporte a Express

🔗 Recursos

• Documentação completa da arquitetura Servent-SSR
• Reportar um problema
• Eduardo de Freitas Arantes

Feito com ♥ por Eduardo de Freitas Arantes