npm package: @grupopll/pll-jenkins
Description: CLI interativo para gerenciar jobs Jenkins (list/pull/push)
Author: marcelosenna
Latest version: 1.1.0

# pll-jenkins

CLI interativo para gerenciar jobs Jenkins via terminal. Permite baixar (pull) e subir (push) jobs de uma pasta Jenkins diretamente para um repositório git, usando a branch atual como referência automática.

---

## Dependências do sistema

Antes de instalar, certifique-se de ter os seguintes programas disponíveis no PATH:

| Dependência | Motivo | Instalação (Ubuntu/Debian) |
|---|---|---|
| **Java (JRE)** | Executa o `jenkins-cli.jar` | `sudo apt install default-jre` |
| **jq** | Processa respostas JSON da API Jenkins | `sudo apt install jq` |
| **curl** | Faz chamadas HTTP nos scripts shell | `sudo apt install curl` |

> O `jenkins-cli.jar` já vem **embutido** no pacote — não é necessário baixar separadamente.

---

## Instalação

```bash
npm install -g @grupopll/pll-jenkins
```

Após a instalação, o comando `pll-jenkins` estará disponível globalmente.

---

## Configuração de credenciais

Na primeira execução de qualquer comando, o CLI irá pedir a **URL**, **usuário** e **token** do Jenkins e salvará automaticamente em `~/.pll-jenkins.json` (com permissão restrita `600`).

```
? URL do Jenkins (ex: https://jenkins.exemplo.com): https://seu-jenkins.com
? Usuário Jenkins: seu-usuario
? Token Jenkins: ********
```

Nas próximas execuções as credenciais são carregadas automaticamente, sem perguntar nada.

> O token pode ser gerado em: `https://seu-jenkins.com/user/<seu-usuario>/configure` → **API Token**

---

## Uso

```
pll-jenkins <comando>

Comandos:
  list    Lista jobs e pastas no Jenkins
  pull    Baixa jobs do Jenkins para o repositório local
  push    Sobe jobs locais de volta para o Jenkins
```

---

### `pll-jenkins list`

Lista a árvore de jobs e pastas a partir de uma pasta do Jenkins.

```bash
pll-jenkins list
```

```
? Pasta inicial (deixe vazio para raiz):

/
├── Meu-Projeto/
│   ├── main/
│   │   ├── [JOB] Auth-Request
│   │   └── [JOB] Pipeline-Deploy
│   └── uat/
│       └── [JOB] Auth-Request
└── Outro-Projeto/
    └── [JOB] Build
```

---

### `pll-jenkins pull`

Baixa os jobs de uma pasta Jenkins para dentro do repositório git local, na pasta `jenkins/`.

```bash
cd meu-repo-git   # branch: main
pll-jenkins pull
```

**Primeira execução:** abre um seletor interativo para escolher o projeto raiz no Jenkins (ex: `Meu-Projeto`). A branch git atual é adicionada automaticamente ao caminho (`Meu-Projeto/main`).

```
? Selecionar projeto Jenkins:
  > Meu-Projeto/  (entrar)
    [Usar esta pasta]
    Outro-Projeto/  (entrar)
```

Após a seleção, o arquivo `jenkins/.pll-jenkins` é criado com o nome do projeto e os jobs são baixados:

```
meu-repo-git/
└── jenkins/
    ├── .pll-jenkins          ← salvo automaticamente
    ├── Auth-Request/
    │   └── config.xml
    └── Pipeline-Deploy/
        └── config.xml
```

**Execuções seguintes:** o projeto é lido automaticamente do `jenkins/.pll-jenkins`. Basta trocar de branch e rodar novamente:

```bash
git checkout uat
pll-jenkins pull   # baixa Meu-Projeto/uat automaticamente
```

---

### `pll-jenkins push`

Sobe os jobs da pasta `jenkins/` local de volta para o Jenkins, usando a branch atual para determinar o destino.

```bash
cd meu-repo-git   # branch: main
pll-jenkins push
```

```
Projeto      : Meu-Projeto  (lido de jenkins/.pll-jenkins)
Branch atual : main
Pasta Jenkins: Meu-Projeto/main
Origem local : /home/user/meu-repo-git/jenkins

? Push de "/home/user/meu-repo-git/jenkins" → Jenkins "Meu-Projeto/main". Confirmar? (Y/n)
```

Se a pasta `Meu-Projeto/<branch>` **não existir** no Jenkins, o CLI pergunta se deseja criá-la antes de fazer o push:

```
A pasta "Meu-Projeto/uat" não existe no Jenkins.
? Criar pasta "Meu-Projeto/uat" no Jenkins? (Y/n)
Criando pasta "Meu-Projeto/uat"...
Pasta criada com sucesso.
```

---

## Fluxo típico por projeto

```bash
# 1. Clone o repositório
git clone git@github.com:sua-empresa/meu-projeto.git
cd meu-projeto

# 2. Baixe os jobs da branch main
pll-jenkins pull

# 3. Edite os config.xml conforme necessário
vim jenkins/Auth-Request/config.xml

# 4. Suba de volta para o Jenkins
pll-jenkins push

# 5. Trabalhe em outra branch
git checkout -b uat
pll-jenkins pull    # baixa Meu-Projeto/uat
pll-jenkins push    # sobe para Meu-Projeto/uat (cria se não existir)
```

---

## Estrutura do repositório após o pull

```
meu-repo-git/
└── jenkins/
    ├── .pll-jenkins          ← não commitar (adicione ao .gitignore) ou commitar para fixar o projeto
    ├── NomeDoJob/
    │   └── config.xml
    └── OutroJob/
        └── config.xml
```

> **Dica:** adicione `jenkins/.pll-jenkins` ao `.gitignore` se diferentes desenvolvedores usarem projetos Jenkins distintos, ou commite o arquivo para fixar o projeto para todo o time.

---

## Credenciais salvas

| Arquivo | Conteúdo |
|---|---|
| `~/.pll-jenkins.json` | `{ "url": "...", "user": "...", "token": "..." }` |

Para redefinir as credenciais, apague o arquivo:

```bash
rm ~/.pll-jenkins.json
```

---

## Solução de problemas

| Erro | Causa | Solução |
|---|---|---|
| `Credenciais inválidas (401)` | Token expirado ou incorreto | Gere um novo token no Jenkins e apague `~/.pll-jenkins.json` |
| `Pasta não encontrada (404)` | Pasta não existe no Jenkins | Verifique o nome ou use `pll-jenkins list` |
| `java: command not found` | Java não instalado | `sudo apt install default-jre` |
| `jq: command not found` | jq não instalado | `sudo apt install jq` |
| `jenkins/.pll-jenkins não encontrado` | Pull ainda não foi feito | Execute `pll-jenkins pull` primeiro |
| `Não está em um repositório git` | Pasta sem git | Execute dentro de um repositório git |