npm package: @preventsenior/pvs-cli
Description: CLI from Prevent Senior Tech
Author: Prevent Senior Tech
Latest version: 3.2.2

# PVS CLI - A ferramenta CLI da Prevent Senior


_O PVS-CLI é uma ferramenta de linha de comando que permite a execução de comandos de forma automatizada, facilitando a execução de tarefas repetitivas e a manutenção de ambientes de desenvolvimento._

_____


### Pré-requisitos
- Instale o [Node.js](https://nodejs.org/en/download/) (versão 18 ou superior) que inclui o [NPM](https://www.npmjs.com/get-npm) (gerenciador de pacotes do Node.js).

_____


## Instalação

Instale o PVS-CLI globalmente com o npm:
```bash
npm install -g @preventsenior/pvs-cli
```

### Auto-Update

O PVS-CLI verifica automaticamente se há uma nova versão disponível (uma vez por dia). Quando uma atualização é detectada:

1. **Notificação:** Você será informado sobre a nova versão
2. **Pergunta:** O CLI perguntará se deseja atualizar agora
3. **Atualização automática:** Se você aceitar, a atualização será feita automaticamente
4. **Fallback manual:** Se houver erro de permissão, o CLI mostrará o comando manual

**Opções:**
- ✅ **Aceitar (padrão):** Atualiza automaticamente e você roda o comando novamente
- ❌ **Recusar:** Continua com a versão atual (pode atualizar depois)
- ⏭️ **Cancelar (Ctrl+C):** Cancela e continua com a versão atual

**Nota sobre permissões:**
- **Windows:** Pode ser necessário abrir o terminal como Administrador
- **Linux/macOS:** Pode ser necessário usar `sudo` para instalações globais

**Desabilitar verificação:** A verificação automática ocorre apenas uma vez por dia para não interromper o fluxo de trabalho.

### Comandos disponíveis
- `adicionar-modulo`
- `login-aws`
- `assumir-role`
- `login-ca-aws`
- `login-docker`
- `boundary-config`
- `boundary`
- `download-artifact-backend`
- `upload-artifact-backend`
- `infra-create`
- `editar-values`
- `gravity-adicionar-api`
- `gravity-adicionar-api-consumida`

-----

## Documentação

- Comando `adicionar-modulo`:

    ```bash
    pvs adicionar-modulo
    ```
    Esse comando deve ser rodado na raiz do projeto que deseja adicionar um módulo, esse projeto deve conter a árvore de diretórios criados pelo Gravity da Prevent. Ele irá adicionar um ou mais módulos ao projeto, seguindo o padrão de módulos da Prevent Senior.
    </br></br>
    Você pode adicionar o parâmetro `--modulo` ou `-m` para passar o(s) nome(s) do(s) módulo(s) diretamente, separados por vírgula, sem precisar de interação.
    ```bash
    pvs adicionar-modulo --modulo database
    -------
    pvs adicionar-modulo -m database,kafka
    ```
    Você pode adicionar o parâmetro `--sem-exemplo` ou `-s` para remover os arquivos de exemplo do módulo gerado.
    ```bash
    pvs adicionar-modulo --sem-exemplo
    -------
    pvs adicionar-modulo -s
    ```
    Você pode adicionar o parâmetro `--git-add` ou `-g` para que esses módulos sejam adicionados ao git.
    ```bash
    pvs adicionar-modulo --git-add
    -------
    pvs adicionar-modulo -g
    ```

- Comando `login-aws`:

    #### Pré-requisitos:
    - [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) instalado e configurado.
  
    ```bash
    pvs login-aws
    ```
    Esse comando pode ser rodado em qualquer diretório. Ele irá fazer login na AWS via SSO com base no profile definido no arquivo `~/.aws/config`. Não se preocupe se você tiver mais de um profile configurado, serão todos listados para que você selecione qual deseja se autenticar. Ao final da autenticação lhe será perguntado se quer se autenticar no CodeArtifact com NPM ou Maven (Para facilitar sua vida 😁).
    </br></br>
    Você pode adicionar o parâmetro `--all-login-ca` ou `-a` para logar no Maven e NPM com CodeArtifact.
    ```bash
    pvs login-aws --all-login-ca
    -------
    pvs login-aws -a
    ```
    Você pode adicionar o parâmetro `--profile-default` ou `-pd` para executar com o profile default da AWS.
    ```bash
    pvs login-aws --profile-default
    -------
    pvs login-aws -pd
    ```
    </br></br>
    Caso você não tenha configurado o profile no arquivo `~/.aws/config` para login via SSO, você pode adicioná-lo com o comando abaixo:
    ```bash
    aws configure sso
    ```
    Após rodar o comando acima, você será solicitado a informar o `SSO URL`, `SSO Region`, `SSO Account ID`, `SSO Role Name` e `SSO Start URL`. Após informar esses dados, você terá um profile mais ou menos assim:
    ```
    [profile Developer]
    sso_session = SessionDeveloper
    sso_account_id = 000000000000
    sso_role_name = Developer
    region = sa-east-1
    output = json
    
    [sso-session SessionDeveloper]
    sso_start_url = https://sso-da-sua-empresa/start#/
    sso_region = sa-east-1
    sso_registration_scopes = sso:account:access
    ```

- Comando `assumir-role`:

    #### Pré-requisitos:
    - [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) instalado e configurado.

    ```bash
    pvs assumir-role
    ```
    Esse comando deve ser rodado no diretório raiz do projeto que queira assumir a role. Será assumida uma role padrão para apps da Prevent Senior. 
    
    Ex: `arn:aws:iam::000000000000:role/app/${env}-${app_name} | arn:aws:iam::000000000000:role/app/dev-pvs-cli`. Essa role é criada (quando solicitado) para o seu app com as permissões necessárias.
    </br></br>
    
    Você pode adicionar o parâmetro `--add-profile` ou `-p` para que o comando adicione ou atualize o profile e suas credências nos arquivos: `~/.aws/config` e `~/.aws/credentials`.
    ```bash
    pvs assumir-role --add-profile
    -------
    pvs assumir-role -p
    ```
    
    Por padrão a role que será assumida é a de `dev`, mas você pode adicionar o parâmetro `--staging` ou `-s` para assumir a role de homologação.
    ```bash
    pvs assumir-role --staging
    -------
    pvs assumir-role -s
    ```
    Você pode adicionar o parâmetro `--wildfly` ou `-w` para assumir a role para wildfly no Argo.
    ```bash
    pvs assumir-role --wildfly
    -------
    pvs assumir-role -w
    ```
    Você pode adicionar o parâmetro `--profile-default` ou `-pd` para executar com o profile default da AWS.
    ```bash
    pvs assumir-role --profile-default
    -------
    pvs assumir-role -pd
    ```
  
- Comando `login-ca-aws`:

    #### Pré-requisitos:
    - [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) instalado e configurado.

    ```bash
    pvs login-ca-aws
    ```  
    Esse comando pode ser rodado em qualquer diretório. Ele irá fazer a autenticação no CodeArtifact da AWS com base no profile selecionado.
    </br></br>
    Você posse adicionar o parâmetro `--npm` ou `-n` para que o login seja feito somente com NPM.
    ```bash
    pvs login-ca-aws --npm
    -------
    pvs login-ca-aws -n
    ```
    Ou adicionar o parâmetro `--maven` ou `-m` para que o login seja feito somente com Maven.
    ```bash
    pvs login-ca-aws --maven
    -------
    pvs login-ca-aws -m
    ```
    Você pode adicionar o parâmetro `--profile-default` ou `-pd` para executar com o profile default da AWS.
    ```bash
    pvs login-ca-aws --profile-default
    -------
    pvs login-ca-aws -pd
    ```
    **Ao omitir os parâmetros de tipo (npm/maven), o login será feito com NPM e Maven.**
    </br></br>

- Comando `login-docker`:

    #### Pré-requisitos:
    - [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) instalado e configurado.
    - [docker](https://docs.docker.com/engine/install/) instalado e configurado.

    ```bash
    pvs login-docker
    ```
    Esse comando pode ser rodado em qualquer diretório. Ele irá fazer login no Docker apontando para o ERC com base no profile selecionado.
    </br></br>
    Você pode adicionar o parâmetro `--profile-default` ou `-pd` para executar com o profile default da AWS.
    ```bash
    pvs login-docker --profile-default
    -------
    pvs login-docker -pd
    ```
    </br></br>


# Comandos adicionados na versão 1.1.0

- Comando `boundary-config`:

    **Este comando sempre irá forçar um novo login no boundary, lembre-se de estar autenticado com sua conta a_{cpf} no navegador**
    #### Pré-requisitos:
    - [boundary](https://developer.hashicorp.com/boundary/tutorials/get-started-community/community-get-started-install) na versão 0.16.0 ou superior instalado.
     
    ```bash
    pvs boundary-config
    ```  
    Esse comando pode ser rodado em qualquer diretório. Ele irá criar um arquivo de configuração para o boundary, deixando sempre um squad e um ambiente para acesso rápido.
    </br></br>
    Você pode usar o parâmetro `--show-config` ou `-s` visualizar o arquivo de configuração.
    ```bash
    pvs boundary-config --show-config
    -------
    pvs boundary-config -s
    ```
    Você pode adicionar o parâmetro `--squad` ou `-T` para informar o squad.
    ```bash
    pvs boundary-config --squad <squad_name>
    -------
    pvs boundary-config -T <squad_name>
    ```
    Você pode adicionar o parâmetro `--environment` ou `-E` para informar o ambiente, as opções são [dev,hom,prd].
    ```bash
    pvs boundary-config --environment <environment_name>
    -------
    pvs boundary-config -E <environment_name>
    ```
    **Ao omitir os parâmetros, será listado as squads que você tem permissão para selecionar, e posteriormente o ambiente.**

    ![Squads](assets/select-squad.png) ![Ambiente](assets/select-env.png)
    </br></br>

- Comando `boundary`:
    
    #### Pré-requisitos:
    - [boundary](https://developer.hashicorp.com/boundary/tutorials/get-started-community/community-get-started-install) na versão 0.16.0 ou superior instalado.
    - `pvs boundary-config` executado ou `--force-login | -f` informado junto para logar pela primeira vez.
     
    ```bash
    pvs boundary
    ```  
    Esse comando pode ser rodado em qualquer diretório. `pvs boundary` é um comando para facilitar sua conexão a um host. Se configurado com `pvs boundary-config` ele irá listar os hosts disponíveis para conexão.
    </br></br>
    Você pode adicionar o parâmetro `--squad` ou `-T` para informar a squad, o comando irá ignorar a configuração feita com o `pv boundary-config`, e irá lhe perguntar em qual ambiente deseja listar os hosts.
    ```bash
    pvs boundary --squad <squad_name>
    -------
    pvs boundary -T <squad_name>
    ```
    Você pode adicionar o parâmetro `--force-login` ou `-f` para que o comando force um novo login no boundary.
    ```bash
    pvs boundary --force-login
    -------
    pvs boundary -f
    ```

# Comandos adicionados na versão 1.2.0

- Comando `download-artifact-backend`
  #### Pré-requisitos:
  - [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) instalado e configurado.
  - `pvs login-aws` executado.

  ```bash
  pvs download-artifact-backend <artifact_name> <artifact_version>
  ```
  Esse comando pode ser rodado em qualquer diretório (Mas lembre-se, o artefato será baixado no diretório que o comando rodar). `pvs download-artifact-backend` é um comando para facilitar o download de um artefato `.war` ou `.jar` do CodeArtifact.
  </br> 
  Os parâmetros `<artifact_name>` e `<artifact_version>` são obrigatórios, e você deve informar o nome do artefato e a versão que deseja baixar.
  </br></br>
  Você pode adicionar o parâmetro `--snapshot` ou `-s` para informar que o artefato encontra-se no repositório snapshots do CodeArtifact.
  ```bash
  pvs download-artifact-backend portalweb-impl 1.0.0-SNAPSHOT --snapshot
  -------
  pvs download-artifact-backend portalweb-impl 1.0.0-SNAPSHOT -s
  ```
  Você pode adicionar o parâmetro `--type` ou `-t` para informar o tipo do artefato, pode ser `war` ou `jar`, por padrão, ao não informar o parâmetro, o tipo será `war`.
  ```bash
  pvs download-artifact-backend portalweb-impl 1.0.0 --type jar
  -------
  pvs download-artifact-backend portalweb-impl 1.0.0 -t jar
  ```
  Você pode adicionar o parâmetro `--profile-default` ou `-pd` para executar com o profile default da AWS.
  ```bash
  pvs download-artifact-backend portalweb-impl 1.0.0 --profile-default
  -------
  pvs download-artifact-backend portalweb-impl 1.0.0 -pd
  ```
_____

- Comando `upload-artifact-backend`
  #### Pré-requisitos:
  - [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) instalado e configurado.
  - [Maven](https://maven.apache.org/download.cgi) instalado e configurado.
  - `pvs login-ca-aws` executado (necessário estar logado no CodeArtifact com Maven).

  ```bash
  pvs upload-artifact-backend
  ```
  Esse comando pode ser rodado em qualquer diretório. `pvs upload-artifact-backend` é um comando para facilitar o upload de um artefato `.war` ou `.jar` para o CodeArtifact.
  </br></br>
  O comando aceita os seguintes parâmetros opcionais. Se não informados, serão solicitados interativamente:

  Você pode adicionar o parâmetro `--file` ou `-f` para informar o caminho do arquivo para upload.
  ```bash
  pvs upload-artifact-backend --file ./target/meu-app.war
  -------
  pvs upload-artifact-backend -f ./target/meu-app.war
  ```
  Você pode adicionar o parâmetro `--groupId` ou `-g` para informar o groupId do artefato.
  ```bash
  pvs upload-artifact-backend --groupId br.com.preventsenior
  -------
  pvs upload-artifact-backend -g br.com.preventsenior
  ```
  Você pode adicionar o parâmetro `--artifactId` ou `-a` para informar o artifactId do artefato.
  ```bash
  pvs upload-artifact-backend --artifactId meu-app-impl
  -------
  pvs upload-artifact-backend -a meu-app-impl
  ```
  Você pode adicionar o parâmetro `--artifactVersion` ou `-av` para informar a versão do artefato.
  ```bash
  pvs upload-artifact-backend --artifactVersion 1.0.0
  -------
  pvs upload-artifact-backend -av 1.0.0
  ```
  Você pode adicionar o parâmetro `--packaging` ou `-p` para informar o tipo de pacote (`jar` ou `war`).
  ```bash
  pvs upload-artifact-backend --packaging war
  -------
  pvs upload-artifact-backend -p war
  ```
  **Exemplo completo com todos os parâmetros:**
  ```bash
  pvs upload-artifact-backend -f ./target/meu-app.war -g br.com.preventsenior -a meu-app-impl -av 1.0.0 -p war
  ```
_____


# Comandos adicionados na versão 1.4.0

- Comando `infra-create`
  #### Pré-requisitos:
  - [Projeto TerraForm v3](https://bitbucket.org/preventsenior/terraform-v3/src/main/) clonado em sua maquina.
  - `Git` instalado e configurado para fazer commit e criar PR.

  ```bash
  pvs infra-create
  ```
  Esse comando deve ser rodado no diretório do projeto terraform-v3.
  </br>
  Ao rodar o comando, será perguntado o nome do projeto, o ambiente, o nome do squad e o nome do componente.
  </br></br>
  Com essas informações, o comando irá criar um diretório com o nome do projeto, ambiente e squad, e dentro desse diretório, será criado um arquivo `api_key_${project_name}.tf` com o conteúdo padrão para criação de uma infraestrutura da api-key.
  </br></br>
  Será criado também um arquivo chamado `header.tf` com o conteúdo padrão para criação de um header caso ainda não exista para o projeto.
_____

- Comando `editar-values`
  #### Pré-requisitos:
  - Projeto deve conter arquivos `values-{env}.yaml` (dev, hom ou prd).

  ```bash
  pvs editar-values
  ```
  Esse comando deve ser rodado no diretório do projeto que contém os arquivos `values-{env}.yaml`.
  </br></br>
  O comando permite editar interativamente o arquivo `values-{env}.yaml` através de um menu guiado. Primeiro, você seleciona o ambiente (dev, hom ou prd), depois escolhe as áreas que deseja editar (como database, kafka, redis, etc.).
  </br></br>
  **Funcionalidades:**
  - Seleção do ambiente (dev, hom, prd)
  - Edição guiada por menus interativos
  - Validação de valores durante a edição
  - Revisão de alterações antes de salvar
  - Opção de salvar ou descartar alterações
  </br></br>
  Este comando facilita a edição dos arquivos de configuração sem precisar editar manualmente o YAML, reduzindo erros de sintaxe e formatação.
_____


# Comandos Gravity

- Comando `gravity-adicionar-api`
  #### Pré-requisitos:
  - [Git](https://git-scm.com/downloads) instalado e configurado.
  - Projeto Maven com módulo main.
  - Branch `main` limpa (sem alterações pendentes).
  - Projeto deve ter a propriedade `pvs.squad.name` definida no `application.properties` do módulo main.

  ```bash
  pvs gravity-adicionar-api
  ```
  **Este comando deve ser executado na raiz do projeto e na branch main.**
  </br></br>
  O comando cria automaticamente o arquivo `api-info.yaml` do Gravity e registra a API no Gravity. Ele realiza as seguintes ações:
  </br></br>
  1. Valida se o projeto possui o módulo main
  2. Busca o nome da squad no `application.properties`
  3. Gera o arquivo `api-info.yaml` com as informações da API
  4. Adiciona a API ao arquivo `catalog-info.yaml`
  5. Realiza commit e push das alterações
  6. Registra a API no Gravity automaticamente
  7. Executa refresh no Gravity
  </br></br>
  **Importante:** O comando verifica se você está na branch main e se não há alterações pendentes antes de executar.
_____

- Comando `gravity-adicionar-api-consumida`
  #### Pré-requisitos:
  - [Git](https://git-scm.com/downloads) instalado e configurado.
  - Projeto deve possuir arquivo `catalog-info.yaml`.
  - Branch `main` limpa (sem alterações pendentes).
  - Conectado à VPN (para acessar o Gravity).

  ```bash
  pvs gravity-adicionar-api-consumida
  ```
  **Este comando deve ser executado na raiz do projeto e na branch main.**
  </br></br>
  O comando permite adicionar APIs consumidas pelo seu projeto no arquivo `catalog-info.yaml`. Ele realiza as seguintes ações:
  </br></br>
  1. Busca todas as APIs disponíveis no Gravity
  2. Filtra APIs que já estão registradas como consumidas
  3. Apresenta um menu de seleção múltipla para escolher as APIs
  4. Adiciona as APIs selecionadas ao `catalog-info.yaml`
  5. Realiza commit e push das alterações
  6. Executa refresh no Gravity
  </br></br>
  **Importante:** O comando verifica se você está na branch main e se não há alterações pendentes antes de executar.
_____


# Configuração Automática do Claude Code

O PVS-CLI configura o Claude Code **automaticamente** se ele estiver instalado. Não é necessário fazer nada!

**O que é configurado:**

1. **MCP Servers:** Adiciona servidores MCP (como `pvs-doc-framework-spring` e `taskmaster-ai`) ao arquivo `~/.claude.json`, permitindo que o Claude acesse:
   - Documentação oficial do framework Spring da Prevent Senior
   - Ferramentas de gerenciamento de tarefas (TaskMaster AI)

2. **Permissões:** Configura permissões no arquivo `~/.claude/settings.json`, incluindo:
   - Permissões para comandos bash específicos do PVS CLI
   - Permissões para ferramentas MCP do framework Spring
   - Modo padrão de aceitação de edições
   - Bloqueio de comandos perigosos e arquivos sensíveis

**Quando ocorre a configuração:**
- ✅ Na instalação do CLI (`npm install -g @preventsenior/pvs-cli`)
- ✅ Antes de qualquer comando ser executado (atualização automática e silenciosa)

**Requisito:**
- [Claude Code](https://claude.com/claude-code) deve estar instalado no sistema

**Nota:** A configuração é totalmente automática e silenciosa. Se o Claude Code não estiver instalado, a configuração é ignorada sem erros.

_____


# Autocomplete Automático

O PVS-CLI instala o autocomplete **automaticamente** na primeira execução de qualquer comando. Não é necessário fazer nada!

Se precisar gerenciar manualmente o autocomplete (casos especiais), existe um comando oculto `completion`:

```bash
pvs completion install   # Forçar reinstalação
pvs completion uninstall # Desinstalar
pvs completion fix       # Reparar problemas
```

</br></br>

**Como funciona a instalação automática:**

Na primeira vez que você executar qualquer comando do PVS-CLI, o autocomplete será automaticamente configurado no seu shell (`.bashrc` ou `.zshrc`). O comando adiciona apenas uma linha **no início** do seu arquivo de configuração do shell:

```bash
source <(pvs completion script)
```

Isso carrega o script de autocomplete dinamicamente, mantendo seus arquivos de configuração limpos e atualizados automaticamente. A linha é adicionada no início do arquivo para garantir carregamento prioritário.

</br></br>

**Compatibilidade:**

✅ **Ambientes Suportados:**
- Windows Git Bash
- Windows WSL (Bash/Zsh)
- Linux (Bash/Zsh)
- macOS (Bash/Zsh)

❌ **Ambientes NÃO Suportados:**
- Windows CMD (Prompt de Comando)
- Windows PowerShell

**Nota:** Se você usa CMD ou PowerShell no Windows, instale o [Git Bash](https://git-scm.com/downloads) para ter suporte ao autocomplete.

</br>

**Ativar o autocomplete imediatamente (SEM reiniciar o terminal):**

```bash
eval "$(pvs completion activate)"
```

Este comando aplica as configurações no shell atual instantaneamente! ⚡

</br>

**Ou use a forma tradicional:**

Recarregue o seu shell manualmente:
```bash
source ~/.bashrc  # Para Bash
-------
source ~/.zshrc   # Para Zsh
```

Ou simplesmente reinicie o terminal.

</br></br>

Com o autocomplete instalado, você pode pressionar `TAB` para autocompletar comandos e opções do PVS-CLI:

```bash
pvs <TAB>                      # Lista todos os comandos
pvs adicionar-<TAB>            # Autocompleta para "adicionar-modulo"
pvs adicionar-modulo <TAB>     # Lista todas as opções do comando
```

</br>

**Comandos adicionais do completion (uso avançado):**

Ativar imediatamente após instalação:
```bash
eval "$(pvs completion activate)"
```
Este é o comando recomendado para ativar o autocomplete sem reiniciar o terminal!

Ver o script de completion:
```bash
pvs completion script
```

Reparar problemas de configuração:
```bash
pvs completion fix
```
Use este comando se tiver erros no bash (como "binary operator expected"). Ele remove configurações antigas problemáticas e permite uma reinstalação limpa.

Desinstalar o autocomplete:
```bash
pvs completion uninstall
```

</br>

**Perguntas Frequentes (FAQ):**

**P: O autocomplete não funciona no meu Windows. O que fazer?**
R: Certifique-se de estar usando o Git Bash, não o CMD ou PowerShell. O autocomplete bash não funciona em CMD/PowerShell nativos.

**P: Preciso instalar o autocomplete manualmente?**
R: Não! A partir da versão 2.3.0, o autocomplete é instalado automaticamente na primeira execução de qualquer comando.

**P: Como ativar o autocomplete sem reiniciar o terminal?**
R: Execute: `eval "$(pvs completion activate)"` - isso ativa imediatamente no shell atual!

**P: Funciona no macOS Catalina ou superior?**
R: Sim! O CLI detecta automaticamente que o macOS Catalina+ usa zsh por padrão e configura o arquivo `.zshrc` corretamente.

**P: Funciona no WSL (Windows Subsystem for Linux)?**
R: Sim! O WSL usa Linux nativo, então bash/zsh completion funciona perfeitamente.

**P: Como verificar se o autocomplete está instalado?**
R: Verifique se o arquivo `~/.bashrc` (ou `~/.zshrc`) contém a linha: `source <(pvs completion script)`

_____



Obrigado por usar o PVS-CLI! 🚀

Se tiver alguma dúvida ou sugestão, entre em contato com time Sculptor, ficaremos felizes em ajudar! 😁