cartorio-plataforma-cli/README.md

CLI para gerenciar a Plataforma do Cartório de Criciúma com sistema de módulos

# Cartório Plataforma CLI

CLI para gerenciar a Plataforma do Cartório de Criciúma. Permite o controle centralizado de todos os componentes da plataforma, incluindo serviços de infraestrutura, core e módulos, com sistema dinâmico de descoberta de módulos.

> **⚠️ IMPORTANTE:** Esta CLI é específica para uso interno no Cartório de Criciúma e foi projetada exclusivamente para a estrutura da Plataforma do Cartório. Não é um produto genérico e requer a estrutura de diretórios e arquivos correspondente à arquitetura da Plataforma do Cartório.

## Novidades na Versão 2.0.0

A versão 2.0.0 introduz um sistema de registro e descoberta dinâmica de módulos:

- **Descoberta Automática**: Detecta automaticamente módulos através de arquivos `plataforma-manifest.js`
- **Gestão de Módulos**: Novo comando `module` para gerenciar seus módulos
- **Arquivos de Manifesto**: Definições declarativas para módulos da plataforma
- **Geração Automática de Docker Bake**: Atualiza o arquivo bake.hcl a partir dos módulos registrados

## Novidades na Versão 2.8.0

A versão 2.8.0 traz melhorias significativas no modo customizado de seleção de módulos:

- **Modo Personalizado Aprimorado**: O comando `--custom` agora permite selecionar módulos específicos com mais precisão
- **Seleção por ID e Tipo**: Suporte ao formato `id:tipo` para identificação clara dos módulos
- **Diagnóstico Aprimorado**: Feedback mais detalhado quando um módulo não é encontrado, mostrando opções disponíveis
- **Suporte ao Módulo Senhas**: Adicionamos suporte completo para os módulos de senhas (frontend e backend)

## Requisitos do Ambiente

Para utilizar esta CLI, você precisa ter:

1. A estrutura de diretórios da Plataforma do Cartório de Criciúma
2. Node.js >= 14.0.0
3. Docker e Docker Compose
4. Acesso aos repositórios da Plataforma

## Instalação

```bash
npm install -g cartorio-plataforma-cli
```

## Uso

Após a instalação, você pode usar o comando `plataforma` para gerenciar todos os aspectos da plataforma:

```bash
plataforma <comando> [opções]
```

### Comandos Disponíveis

#### Iniciar Componentes
```bash 
plataforma start [opções]
```

Opções:
- `-a, --all`: Inicia todos os componentes (Infra + Core + Módulos)
- `-i, --infra`: Inicia apenas serviços de infraestrutura (Consul, PostgreSQL, Traefik)
- `-c, --core`: Inicia infraestrutura e componentes core (Root Config, Plataforma Frontend, Plataforma Backend)
- `-f, --full`: Inicia infraestrutura, core e módulos
- `-u, --custom`: Inicia componentes personalizados
- `-m, --modules <lista>`: Lista de módulos no formato id:tipo (ex: senhas:frontend,senhas:backend)
- `-e, --env <ambiente>`: Especifica o ambiente (dev, local, prod). Padrão: local
- `-I, --interactive`: Modo interativo com assistente para seleção de componentes e ambiente
- `-n, --no-build`: Não constrói as imagens, usa as existentes

#### Parar Componentes
```bash
plataforma stop [opções]
```

Opções:
- `-e, --env <ambiente>`: Especifica o ambiente (dev, local, prod). Padrão: local
- `-i, --interactive`: Modo interativo com assistente para seleção de componentes e ambiente

#### Status dos Componentes
```bash
plataforma status [opções]
```

Opções:
- `-e, --env <ambiente>`: Especifica o ambiente (dev, local, prod). Padrão: local
- `-i, --interactive`: Modo interativo com assistente para verificação detalhada de status

#### Gerenciar Módulos
```bash
plataforma module [opções]
```

Opções:
- `--create`: Criar novo módulo
- `--list`: Listar módulos existentes
- `--update`: Atualizar arquivo bake.hcl com módulos registrados
- `--interactive`: Modo interativo (padrão: true)
- `--id <id>`: ID do módulo (para --create)
- `--name <nome>`: Nome do módulo (para --create)
- `--type <tipo>`: Tipo do módulo: frontend, backend, core, infrastructure (para --create)
- `--create-directories`: Criar diretórios para o módulo (padrão: true)

#### Visualizar Logs
```bash
plataforma logs [opções]
```

Opções:
- `-s, --service <serviço>`: Exibe logs apenas do serviço especificado
- `-e, --env <ambiente>`: Especifica o ambiente (dev, local, prod). Padrão: local
- `-f, --follow`: Segue os logs em tempo real
- `-i, --interactive`: Modo interativo para seleção de serviços

## Exemplos de Uso

Listar todos os módulos:
```bash
plataforma module --list
```

Criar um novo módulo:
```bash
plataforma module --create --interactive
```

Iniciar todos os componentes no ambiente local:
```bash
plataforma start -a
```

Iniciar em modo interativo para selecionar componentes:
```bash
plataforma start -I
```

Escolhendo a opção "Personalizado", você poderá selecionar os módulos específicos que deseja iniciar através de uma lista organizada por tipos:
- Módulos Core (Root Config)
- Serviços de Infraestrutura (Consul, PostgreSQL, Traefik)
- Módulos Frontend
- Módulos Backend

Iniciar apenas a infraestrutura em ambiente de desenvolvimento:
```bash
plataforma start -i -e dev
```

Iniciar infraestrutura e core em ambiente local:
```bash
plataforma start -c
```

Iniciar módulos específicos:
```bash
plataforma start -u -m senhas:frontend,senhas:backend
```

> **💡 Dica:** Ao usar o formato `id:tipo` no parâmetro `-m, --modules`, certifique-se de usar os IDs corretos dos módulos. Você pode executar `plataforma module --list` para ver todos os módulos disponíveis e seus IDs.

## Arquivos de Manifesto

Cada módulo deve conter um arquivo `plataforma-manifest.js` em seu diretório raiz, definindo suas configurações:

```javascript
// Exemplo: /modulo1-frontend/plataforma-manifest.js
module.exports = {
  id: "modulo1",
  name: "Módulo 1",
  type: "frontend",
  description: "Frontend do Módulo 1",
  profiles: {
    dev: "modulo1-frontend-dev",
    local: "modulo1-frontend-local", 
    prod: "modulo1-frontend-prod"
  },
  dependencies: ["plataforma-frontend"],
  docker: {
    dockerfile: {
      dev: "Dockerfile.dev",
      prod: "Dockerfile"
    },
    context: "./"
  },
  services: [
    {
      name: "frontend", 
      port: 8081,
      healthcheck: "/"
    }
  ]
};
```

## Estrutura de Diretórios Necessária

Esta CLI espera a seguinte estrutura de diretórios:

```
projeto-plataforma/
├── plataforma-infra/          # Configurações de infraestrutura
│   ├── cli/                   # O CLI da plataforma
│   ├── docker-compose.bake.hcl  # Arquivo de configuração Docker Buildx Bake
│   ├── .env.dev               # Variáveis de ambiente para desenvolvimento
│   ├── .env.local             # Variáveis de ambiente para ambiente local
│   └── .env.prod              # Variáveis de ambiente para produção
├── root-config/               # Aplicação Root Config
│   ├── plataforma-manifest.js # Manifesto definindo este componente
├── plataforma-frontend/       # Frontend da Plataforma
│   ├── plataforma-manifest.js # Manifesto definindo este componente
├── plataforma-backend/        # Backend da Plataforma
│   ├── plataforma-manifest.js # Manifesto definindo este componente
├── modulo1-frontend/          # Frontend do Módulo 1
│   ├── plataforma-manifest.js # Manifesto definindo este componente
└── ...                        # Outros módulos
```

## Suporte

Este pacote é mantido pela equipe de desenvolvimento do Cartório de Criciúma. Para suporte ou dúvidas, entre em contato com a equipe interna.

## Licença

ISC