@davinti/vitruvio-cli (1.6.2)
Installation
@davinti:registry=https://git.davinti.com.br/api/packages/davinTI/npm/npm install @davinti/vitruvio-cli@1.6.2"@davinti/vitruvio-cli": "1.6.2"About this package
vitruvio-cli
Ferramentas de linha de comando para criação e manutenção de repositórios Vitruvio.
Pré-requisitos
- Node.js 18 ou superior
- Git instalado e acessível no terminal
- Chave SSH configurada no servidor Gitea da davinTI (necessária para clonar via SSH — há fallback automático para HTTPS)
Instalação
Linux
# 1. Clone o repositório
git clone ssh://git@git.davinti.com.br:2222/davinTI/vitruvio-cli.git
cd vitruvio-cli
# 2. Instale as dependências
npm install
# 3. Registre o comando globalmente
npm link
Se você usa mise para gerenciar versões do Node, rode também:
mise reshim
Verifique a instalação:
vitruvio --help
Windows
Abra o PowerShell ou Prompt de Comando como administrador.
# 1. Clone o repositório
git clone ssh://git@git.davinti.com.br:2222/davinTI/vitruvio-cli.git
cd vitruvio-cli
# 2. Instale as dependências
npm install
# 3. Registre o comando globalmente
npm link
Verifique a instalação:
vitruvio --help
Nota: Caso o terminal não reconheça o comando
vitruvioapós onpm link, verifique se o diretório de binários globais do npm está no PATH do sistema. Para descobrir o caminho:npm config get prefixAdicione o caminho retornado (ex:
C:\Users\SeuUsuario\AppData\Roaming\npm) nas variáveis de ambiente do sistema em Painel de Controle → Sistema → Variáveis de Ambiente → Path.
Comandos
vitruvio init <nome>
Cria um novo repositório Vitruvio a partir do template base.
vitruvio init meu-modulo
- Clona o template
projeto-basepara um diretório com o nome informado - Remove o histórico git do template e inicializa um repositório limpo sem remotes
- Pronto para você adicionar seu próprio remote e fazer o primeiro commit
Após o init:
cd meu-modulo
# Edite o vitruvio.json com a chave e nome do seu módulo
# Depois:
git remote add origin <url-do-seu-repositório>
git add .
git commit -m "feat: scaffold inicial"
vitruvio update-repo
Atualiza os arquivos CLAUDE.md gerenciados no repositório atual com a versão mais recente do template.
# Execute dentro de um repositório Vitruvio (onde há vitruvio.json)
cd meu-modulo
vitruvio update-repo
Arquivos atualizados por este comando:
CLAUDE.md
endpoints/CLAUDE.md
panels/CLAUDE.md
patches/CLAUDE.md
processes/CLAUDE.md
queries/CLAUDE.md
reports/CLAUDE.md
scripts/CLAUDE.md
Nenhum outro arquivo do repositório é tocado.
vitruvio docs
Abre a documentação Java do Vitruvio no navegador padrão.
vitruvio docs
Abre o arquivo docs/java/index.html do diretório de plataforma. Caso os arquivos não existam, o comando orienta a executar vitruvio update-base primeiro.
vitruvio update-base
Sincroniza os diretórios gerenciados do diretório de plataforma local com o repositório base-claude.
vitruvio update-base
Diretório de plataforma atualizado:
| Sistema | Caminho |
|---|---|
| Linux | ~/.local/share/vitruvio-platform/ |
| Windows | %LOCALAPPDATA%\vitruvio-platform\ |
Diretórios gerenciados (substituídos completamente):
libs/
docs/
examples/
Qualquer outro diretório ou arquivo fora dessa lista não é alterado.
vitruvio mcp
Gerencia servidores MCP (Model Context Protocol) no .mcp.json do repositório atual.
vitruvio mcp # sem argumento: mostra o uso
vitruvio mcp list # lista os MCPs disponíveis
vitruvio mcp add # cadastra um novo MCP no catálogo (interativo)
vitruvio mcp <nome> # adiciona ou atualiza esse MCP no .mcp.json (raiz do repositório atual)
vitruvio update mcp # atualiza (URL + headersHelper) todos os MCPs já listados no .mcp.json do repositório atual
vitruvio mcp add pergunta nome (chave), descrição e URL, valida o formato (nome em letras minúsculas/números/hífen, URL bem-formada, sem colidir com "list"/"add") e grava direto em src/data/mcps.json — o mesmo arquivo que os outros subcomandos leem, então vitruvio mcp <nome-novo> já funciona na próxima execução do CLI, sem passo extra.
Restrito ao time Infra da organização davinTI no Gitea. Antes de perguntar qualquer coisa, o comando confirma (via API do Gitea, usando o token de vitruvio token) que o dono do token pertence a esse time; caso contrário, recusa com uma mensagem explicando a restrição. Sem token do Gitea configurado, orienta a rodar vitruvio token primeiro.
Depois de salvar, pergunta se quer commitar e enviar (push) — sozinho, sem mais nada — só o src/data/mcps.json, direto no checkout git de onde o CLI está rodando. Isso só funciona quando essa instalação do vitruvio é de fato um clone git (ex.: via npm link, o fluxo de dev); numa instalação normal (npm install -g/vitruvio update cli) não existe .git ali, então o comando avisa que a entrada ficou só local e será perdida na próxima atualização do CLI. Recusando o commit, ou se o push falhar (sem rede, sem permissão, histórico divergente etc.), a entrada continua salva localmente — resolva o git manualmente quando quiser.
Cada entrada gerada usa headersHelper em vez de gravar o token direto no arquivo:
"liderban": {
"type": "http",
"url": "http://liderban.vproxy.lan:8000/mcp",
"headersHelper": "node \"/home/<usuário>/.vitruvio/mcp-gitea-auth-header.js\""
}
(no Windows, o mesmo caminho vira algo como node "C:\\Users\\<usuário>\\.vitruvio\\mcp-gitea-auth-header.js")
Detecção de nvm: se a máquina usa nvm (Linux/macOS), o headersHelper gerado é diferente:
"headersHelper": "NODE_VERSION=default \"/home/<usuário>/.nvm/nvm-exec\" node \"/home/<usuário>/.vitruvio/mcp-gitea-auth-header.js\""
Isso existe porque o Claude Code roda o headersHelper num shell não-interativo, que não sourcinga nvm.sh — então o node do nvm (que só existe num path versionado, ~/.nvm/versions/node/vX.Y.Z/bin/node) não está no PATH desse shell, e o helper falharia silenciosamente (a conexão aparenta "authenticated" no handshake, mas toda tool call cai em "requires re-authorization"). nvm-exec tem path fixo e resolve a versão certa em tempo de execução, então funciona independente do PATH do shell que o disparou. Sem nvm detectado (NVM_DIR/~/.nvm/nvm-exec ausentes) ou no Windows, o comando volta a ser só node "<caminho>".
- O catálogo de MCPs disponíveis (nome, descrição, URL) vive em
src/data/mcps.json— não contém segredos. - A autenticação reaproveita o mesmo token pessoal do Gitea configurado via
vitruvio token. O token nunca é escrito no.mcp.json:vitruvio mcp <nome>garante que~/.vitruvio/mcp-gitea-auth-header.jsexiste (sincronizado a partir do template emsrc/data/mcp-gitea-auth-header.js) e apontaheadersHelperpranode "<esse-arquivo>", que lê~/.vitruvio/config.jsonem tempo de execução e imprime o headerAuthorization: token <PAT>. Sem token do Gitea salvo,vitruvio mcp <nome>orienta a rodarvitruvio tokenprimeiro. - O helper é em Node.js (não bash/python) de propósito: é o único runtime que o próprio vitruvio-cli já exige em Windows e Linux/macOS, e o Claude Code executa
headersHelperdentro de um shell (cmd.exeno Windows,sh/bashno Linux/macOS) —node "<caminho>"funciona igual nos dois. vitruvio mcp <nome>grava (ou atualiza, se a chave já existir) apenas a entradamcpServers.<nome>do.mcp.json, preservando qualquer outra entrada já presente no arquivo.vitruvio update mcppercorre as entradas já presentes emmcpServerse garante que as que existem no catálogo apontam pro helper mais recente; não toca em entradas que não pertencem ao catálogo (ex.: um MCP configurado manualmente). Sem.mcp.jsonno diretório atual, o comando avisa e não faz nada. Também roda automaticamente dentro devitruvio update(sem alvo) quando há um.mcp.jsonno diretório.
Dependencies
Dependencies
| ID | Version |
|---|---|
| commander | ^12.0.0 |
| fs-extra | ^11.2.0 |