npm package: @hed-hog/developer-mode
Description: ```markdown # @hed-hog/developer-mode
Latest version: 0.0.303

```markdown
# @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):**

    ```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:

```yaml
- 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:

```yaml
- 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`)

```ts
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:

```json
{
  "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.

```yaml
- 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.

```yaml
- 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

```bash
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`:

```bash
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.
```