# @hed-hog/developer-mode

## 1. Visão geral do módulo

O módulo `@hed-hog/developer-mode` fornece funcionalidades para monitoramento e execução de scripts em modo desenvolvedor dentro do monorepo HedHog. Ele oferece endpoints para obtenção de informações detalhadas sobre aplicativos, bibliotecas, banco de dados, git e estatísticas do projeto, além de permitir a execução controlada e streaming em tempo real de scripts definidos nos pacotes do monorepo.

## 2. Escopo e responsabilidades

- Coletar e expor dados do ambiente de desenvolvimento, incluindo:
  - Informações sobre apps e bibliotecas presentes no monorepo.
  - Estado do banco de dados e últimas migrações.
  - Informações do repositório Git, como branch atual, PRs abertos e commits recentes.
  - Estatísticas gerais do projeto, como uso de disco, versão do Node.js e uptime.
- Permitir a execução segura e monitorada de scripts definidos nos `package.json` de apps e bibliotecas, com streaming dos logs via Server-Sent Events (SSE).
- Validar permissões para execução de scripts, limitando a scripts permitidos por app ou biblioteca.
- Integrar com outros módulos do monorepo, como `api-locale`, `api-pagination` e `api-prisma`.

## 3. Endpoints

### GET `/developer-mode`

- **Método:** GET
- **Autenticação:** Requer autenticação com papel `admin` ou `admin-developer-mode`.
- **Descrição:** Retorna um objeto com dados completos do modo desenvolvedor, incluindo apps, bibliotecas, banco de dados, git e estatísticas do projeto.
- **Parâmetros:** Nenhum.
- **Resposta:**

```json
{
  "apps": [
    {
      "name": "string",
      "path": "string",
      "framework": "nestjs" | "nextjs" | "angular" | "vue" | "react-native" | "expo",
      "database": "string | undefined",
      "description": "string",
      "port": "number | undefined",
      "status": "running" | "stopped" | "error",
      "scripts": ["string"]
    }
  ],
  "libraries": [
    {
      "name": "string",
      "version": "string",
      "latestVersion": "string | undefined",
      "installed": true,
      "description": "string",
      "scripts": [
        {
          "name": "string",
          "command": "string"
        }
      ]
    }
  ],
  "database": {
    "name": "string",
    "host": "string",
    "port": "number",
    "type": "postgresql" | "mysql" | "unknown",
    "user": "string | undefined",
    "database": "string | undefined",
    "tables": "number | undefined",
    "size": "string | undefined",
    "connections": {
      "active": "number",
      "max": "number"
    },
    "lastMigration": {
      "name": "string",
      "date": "string",
      "status": "success" | "failed" | "pending"
    } | undefined,
    "connected": "boolean | undefined"
  },
  "git": {
    "repoName": "string | undefined",
    "currentBranch": "string",
    "totalBranches": "number",
    "openPRs": "number",
    "recentCommits": [
      {
        "hash": "string",
        "message": "string",
        "author": "string",
        "authorAvatar": "string | undefined",
        "date": "string",
        "branch": "string"
      }
    ]
  },
  "stats": {
    "nodeVersion": "string",
    "diskUsage": "string",
    "totalApps": "number",
    "totalLibraries": "number",
    "dbConnections": "number",
    "gitBranch": "string",
    "lastCommit": "string",
    "uptime": "string"
  }
}

• Erros comuns:
  • 401 Unauthorized: Usuário não autenticado ou sem permissão.
  • 500 Internal Server Error: Erro interno ao coletar dados.

POST /developer-mode/scripts/stream

• Método: POST

• Autenticação: Pública (não requer autenticação).

• Descrição: Executa um script permitido para um app ou biblioteca e transmite a saída em tempo real via Server-Sent Events (SSE).

• Parâmetros:

  • Body (JSON):

    {
      "targetType": "app" | "library",
      "targetName": "string",
      "scriptName": "string"
    }

    • targetType: Define se o script será executado em um app ou biblioteca.
    • targetName: Nome do app ou biblioteca alvo.
    • scriptName: Nome do script definido no package.json do alvo.

• Resposta: Fluxo SSE com eventos:

  • start: Indica início da execução do script.
  • output: Linhas de saída padrão do script.
  • error: Linhas de erro ou mensagens de falha.
  • end: Indica término da execução, com sucesso ou falha.

• Erros comuns:

  • 400 Bad Request: Script ou alvo inválido ou não permitido.
  • 500 Internal Server Error: Erro durante a execução do script.

4. Regras de autenticação e autorização

• O endpoint GET /developer-mode é protegido e requer que o usuário possua o papel admin ou admin-developer-mode.
• O endpoint POST /developer-mode/scripts/stream é público, porém a execução de scripts é restrita a scripts permitidos para cada app ou biblioteca conforme listas internas.
• Papéis definidos no módulo:

- slug: admin-developer-mode
  name:
    en: Developer Mode Administrator
    pt: Administrador do Modo Desenvolvedor
  description:
    en: Administrator with full access to developer mode features.
    pt: Administrador com acesso total às funcionalidades do modo desenvolvedor.

• Rotas protegidas:

- url: /developer-mode
  method: GET
  relations: 
    role:
      - where:
          slug: admin
      - where:
          slug: admin-developer-mode

5. Estruturas de request/response

DTO para execução de script (RunScriptDTO)

export class RunScriptDTO {
  @IsIn(['app', 'library'])
  targetType: 'app' | 'library';

  @Matches(/^[a-zA-Z0-9_-]+$/)
  targetName: string;

  @Matches(/^[a-zA-Z0-9:_-]+$/)
  scriptName: string;
}

• targetType: Tipo do alvo, deve ser 'app' ou 'library'.
• targetName: Nome do app ou biblioteca, apenas caracteres alfanuméricos, underscore e hífen.
• scriptName: Nome do script, permite caracteres alfanuméricos, dois pontos, underscore e hífen.

Resposta do GET /developer-mode

Conforme descrito na seção 3, contém objetos detalhados para apps, bibliotecas, banco de dados, git e estatísticas.

Eventos SSE do POST /developer-mode/scripts/stream

Cada evento possui o formato:

{
  "message": "string",
  "timestamp": "ISO 8601 string"
}

Eventos possíveis: start, output, error, end.

6. Erros comuns

• 400 Bad Request
  • Script não permitido para o app ou biblioteca.
  • App ou biblioteca não encontrada.
  • Script não definido no package.json do alvo.
• 401 Unauthorized
  • Acesso ao endpoint GET /developer-mode sem autenticação ou sem papel adequado.
• 500 Internal Server Error
  • Falha ao coletar dados do sistema.
  • Erro inesperado na execução do script.

7. Banco de dados (tabelas YAML)

Este módulo não define tabelas de banco de dados próprias. As permissões são gerenciadas via papéis (role.yaml) e rotas (route.yaml):

role.yaml

• Finalidade: Define o papel de administrador do modo desenvolvedor com acesso total às funcionalidades do módulo.
• Colunas:
  • slug (string): Identificador único do papel.
  • name (objeto): Nome do papel em inglês e português.
  • description (objeto): Descrição do papel em inglês e português.
• Defaults: Não aplicável.
• Nulabilidade: Todos os campos obrigatórios.
• Integridade: slug único.
• Índices: Índice único em slug.
• Enums: Não aplicável.

- slug: admin-developer-mode
  name:
    en: Developer Mode Administrator
    pt: Administrador do Modo Desenvolvedor
  description:
    en: Administrator with full access to developer mode features.
    pt: Administrador com acesso total às funcionalidades do modo desenvolvedor.

route.yaml

• Finalidade: Define a rota protegida /developer-mode para acesso restrito aos papéis admin e admin-developer-mode.
• Colunas:
  • url (string): Caminho da rota.
  • method (string): Método HTTP.
  • relations (objeto): Relação com papéis autorizados.
• Defaults: Não aplicável.
• Nulabilidade: Todos os campos obrigatórios.
• Integridade: Associação correta com papéis existentes.
• Índices: Índice em url e method.
• Enums: Não aplicável.

- url: /developer-mode
  method: GET
  relations: 
    role:
      - where:
          slug: admin
      - where:
          slug: admin-developer-mode

8. Regras de negócio relevantes

• Scripts executáveis são restritos a uma lista branca para evitar execução arbitrária:

  • Apps permitidos e seus scripts:

    | App | Scripts Permitidos | |--------|------------------------| | admin | dev, build | | web | dev, build | | api | start:dev, build |

  • Bibliotecas permitem scripts: build, lint, test, patch, prod.

• A execução de scripts é feita via pnpm run <script>, com múltiplos fallbacks para garantir compatibilidade em diferentes ambientes (Windows, Linux, etc).

• A saída dos scripts é transmitida em tempo real via SSE, com eventos estruturados para facilitar o consumo no frontend.

• O status dos apps é detectado tentando uma requisição HEAD na porta padrão associada a cada app:

  • admin: porta 3200
  • web: porta 3000
  • api: porta 3100

• Informações do banco de dados são extraídas de arquivos .env e docker-compose.yaml para identificar conexão e estado, incluindo número de tabelas, tamanho e conexões ativas.

• Informações do Git são obtidas via comandos Git, incluindo branch atual, número de branches, PRs abertos (via GitHub CLI se disponível) e últimos commits.

• O uptime do projeto é estimado com base na data de criação do diretório da API.

• A validação de scripts e alvos impede execução de scripts não autorizados ou inexistentes.

9. Guia rápido de uso (exemplos)

Obter dados do modo desenvolvedor

curl -H "Authorization: Bearer <token>" https://api.seudominio.com/developer-mode

Resposta JSON com dados completos do monorepo.

Executar script com streaming SSE

Requisição POST para executar script dev no app admin:

curl -N -X POST https://api.seudominio.com/developer-mode/scripts/stream \
  -H "Content-Type: application/json" \
  -d '{"targetType":"app","targetName":"admin","scriptName":"dev"}'

A resposta será um fluxo SSE com eventos start, output, error e end.

Exemplo de evento SSE recebido

event: start
data: {"message":"Starting app script dev (admin)...","timestamp":"2024-06-01T12:00:00.000Z"}

event: output
data: {"message":"[HedHog] Working directory: /path/to/apps/admin","timestamp":"2024-06-01T12:00:01.000Z"}

event: output
data: {"message":"[HedHog] Script target: apps/admin","timestamp":"2024-06-01T12:00:01.500Z"}

event: output
data: {"message":"Compiling...","timestamp":"2024-06-01T12:00:05.000Z"}

event: end
data: {"success":true,"timestamp":"2024-06-01T12:05:00.000Z"}

Este módulo é essencial para desenvolvedores que desejam monitorar e interagir com o ambiente de desenvolvimento do monorepo HedHog de forma segura e eficiente.