@hed-hog/developer-mode 0.0.270 → 0.0.274

package/README.md

@@ -0,0 +1,318 @@
+# @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
+
+```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
+
+```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.
+- Informações do banco de dados são extraídas de arquivos `.env` e `docker-compose.yaml` para identificar conexão e estado.
+- Informações do Git são obtidas via comandos Git, incluindo branch atual, número de branches, PRs abertos e últimos commits.
+
+## 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 (apps/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/developer-mode",
-  "version": "0.0.270",
+  "version": "0.0.274",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -10,9 +10,9 @@
     "@nestjs/jwt": "^11",
     "@nestjs/mapped-types": "*",
     "@hed-hog/api": "0.0.4",
-    "@hed-hog/api-prisma": "0.0.5",
+    "@hed-hog/core": "0.0.274",
     "@hed-hog/api-pagination": "0.0.6",
-    "@hed-hog/core": "0.0.270",
+    "@hed-hog/api-prisma": "0.0.5",
     "@hed-hog/api-locale": "0.0.13"
   },
   "exports": {