HPC (Health Panel Collector CLI)

CLI pública para coletar métricas técnicas de projetos no SonarQube e enviá‑las ao HealthPanel, concluindo a avaliação do mês para o projeto/quality model.

📌 Visão Geral

Uma avaliação no HealthPanel tem duas partes:

1. Processo: respostas do questionário (já preenchidas na plataforma).
2. Métricas técnicas: cobertura, qualidade, segurança, dívida técnica etc. (obtidas via SonarQube).

A CLI HPC cuida apenas da segunda parte: coleta as métricas do(s) projeto(s) no SonarQube e envia para o backend do HealthPanel utilizando um token de avaliação de uso único.

🔗 Comunicação entre componentes

Fluxo resumido do que acontece quando você roda a CLI:

1. Você fornece (ou é perguntado) o Token de Avaliação (CLI Token) do HealthPanel e o token de usuário do SonarQube (PAT com permissão de leitura).
2. A CLI consulta o backend do HealthPanel para obter:
   • URL do SonarQube configurada
   • Lista de keys dos projetos Sonar (se múltiplos, vêm separados por vírgula)
3. A CLI sobe localmente (Docker) o container do metrics collector (imagem pública) que consulta a API do SonarQube.
4. O collector agrega as métricas dos projetos e retorna um JSON consolidado (score, dívida técnica em horas e itens por projeto).
5. A CLI envia essas métricas para o endpoint do HealthPanel, que conclui a avaliação do mês (status passa para concluída e o score final é recalculado com base em processo + métricas).

Diagrama simplificado:

🔑 Sobre o CLI Token

| Característica | Descrição | |----------------|-----------| | Validade | 24 horas | | Uso | Único (após concluir a avaliação, gere outro para nova coleta) | | Formato | realmId_tokenValue (a CLI extrai internamente) |

Para gerar: dentro do HealthPanel, na página de envio do formulário de avaliação do projeto, use o botão “Gerar Token para a CLI”.

🔐 Sobre o Token do SonarQube

Você precisa de um user token (PAT) com permissão de leitura do(s) projeto(s).
Criação (interface padrão do SonarQube):

http(s)://{URL_DO_SEU_SONAR}/account/security/

Esse token NÃO é armazenado no HealthPanel; ele só trafega localmente na sua execução da CLI.

🧪 Pré‑requisitos

• Node.js 18+ (ou superior compatível)
• Docker em execução (necessário para subir o container do metrics collector)
• A submissão do formulário de avaliação de processo já deve ter sido realizada no HealthPanel
• CLI Token válido e ainda não utilizado

🚀 Instalação Rápida (Uso Global)

npm i -g @db1globalsoftware/hpc

Execução:

db1-hpc --hpToken <CLI_TOKEN> --sonarToken <SONAR_TOKEN>

Se omitir flags, a CLI fará perguntas interativas.

⚠️ Você não precisa informar a URL do SonarQube nem as keys dos projetos; a CLI obtém essas informações do backend do HealthPanel.

Exemplos

# Execução com perguntas interativas
db1-hpc

# Informando porta custom para o container do collector (padrão: 5200)
db1-hpc --hpToken <CLI_TOKEN> --sonarToken <SONAR_TOKEN> --port 5200

📥 Estrutura do que é enviado ao HealthPanel

Payload (simplificado):

{
	"token": "<tokenValue>",
	"metricsHealthScore": {
		"value": 72.4,
		"technicalDebt": 180,
		"items": [
			{ "project": "api-core", "value": 74.1, "technicalDebt": 90 },
			{ "project": "frontend", "value": 70.7, "technicalDebt": 60 },
			{ "project": "shared-lib", "value": 72.0, "technicalDebt": 30 }
		]
	}
}

O backend combina esse score com o score de processo para gerar o Health Score final.

⚠️ Erros Comuns

| Mensagem | Causa Provável | Ação | |----------|----------------|------| | Project not found | Token inválido ou expirado | Gere novo token no HealthPanel | | Você precisa inserir os projetos separados por virgula | Campo sonarProjectKeys vazio no painel | Edite o projeto e salve as keys | | Você precisa inserir a URL do Sonar | Campo de URL não configurado | Atualize o cadastro do projeto | | Error while starting metrics collector container | Docker não está rodando ou porta em uso | Verifique Docker / use --port diferente | | Error while fetching metrics | Token Sonar inválido ou key inexistente | Recrie token / confira keys |

🛡️ Segurança & Privacidade

• A CLI não persiste localmente tokens após a execução.
• O token do Sonar é usado somente para a chamada de coleta.
• Use tokens com escopos mínimos necessários.
• Revogue tokens antigos periodicamente.

🧩 Desenvolvimento Local

Clone o repositório e rode:

npm install
npm run build
node dist/index.js --hpToken <CLI_TOKEN> --sonarToken <SONAR_TOKEN>

Rodar testes:

npm test

🚀 Publicação (Release)

O pacote é publicado no NPM. O pipeline (Azure DevOps) gera release após merge na main usando versionamento semântico.

❓ FAQ Rápido

• Preciso sempre de um novo CLI Token?
  Sim, ele é de uso único e expira em 24h.

• Posso rodar sem Docker?
  Não na versão atual (o coletor roda em container).

• Suporta SonarCloud?
  Sim, desde que você configure a URL correta e o token tenha acesso aos projetos.

• E se um projeto for público?
  Ainda assim informe um token; simplifica a autenticação das chamadas.