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)

`bash
npm i -g @db1globalsoftware/hpc
`

Execução:

`bash
db1-hpc --hpToken --sonarToken
`

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.

$3

`bash


Execução com perguntas interativas

db1-hpc

Informando porta custom para o container do collector (padrão: 5200)

db1-hpc --hpToken --sonarToken --port 5200
`

---

📥 Estrutura do que é enviado ao HealthPanel

Payload (simplificado):

`json
{
"token": "",
"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:

`bash
npm install
npm run build
node dist/index.js --hpToken --sonarToken
`

Rodar testes:

`bash
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.