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, opcionalmente, 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

O token do SonarQube é opcional. Ele é necessário apenas quando o seu SonarQube/SonarCloud exige autenticação para leitura dos projetos. Projetos públicos podem ser coletados sem token.

Quando necessário, use 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. O token do SonarQube pode ser deixado em branco pressionando Enter.

⚠️ 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? O token do Sonar é opcional. Para projetos públicos, você pode deixar o campo em branco ou omitir a flag --sonarToken — a CLI fará a coleta sem autenticação.