@poolzin/pool-bot 2026.3.13 → 2026.3.15

package/docs/ANALISE_OPENCLAW_PROFISSIONAL.md

@@ -0,0 +1,520 @@
+# Análise Profissional: PoolBot vs OpenClaw
+
+> **Data:** 2026-03-11  
+> **Analista:** Build Agent  
+> **Objetivo:** Identificar gaps e oportunidades de melhoria no PoolBot baseado nas práticas do OpenClaw
+
+---
+
+## 1. RESUMO EXECUTIVO
+
+Após análise profunda do código OpenClaw, identifiquei **7 áreas críticas** onde o PoolBot pode ser significativamente melhorado:
+
+| Área | OpenClaw | PoolBot | Prioridade |
+|------|----------|---------|------------|
+| **Arquitetura de Node-Host** | Separação clara em módulos (`runner.ts`, `invoke.ts`, handlers separados) | Tudo em um arquivo monolítico (`runner.ts` 1200+ linhas) | 🔴 Alta |
+| **Tratamento de Erros** | Códigos padronizados, helpers consistentes, `errorShape()` | Erros ad-hoc, strings hardcoded | 🔴 Alta |
+| **Validação de Protocolo** | AJV + schemas TypeBox completos | Validação mínima/inline | 🟡 Média |
+| **Estrutura de Comandos** | Constantes centralizadas (`node-commands.ts`) | Strings espalhadas no código | 🟡 Média |
+| **Ferramentas de Agente** | Classes de erro especializadas, helpers de parâmetros | Validação inline repetida | 🟡 Média |
+| **Testes** | Vitest com fixtures e harnesses abrangentes | Cobertura básica | 🟢 Baixa |
+| **Documentação** | AGENTS.md detalhado, CLAUDE.md symlink | AGENTS.md básico | 🟢 Baixa |
+
+---
+
+## 2. ANÁLISE DETALHADA
+
+### 2.1 Arquitetura de Node-Host
+
+#### OpenClaw (Excelente)
+```
+src/node-host/
+├── runner.ts          # Apenas orquestração (200 linhas)
+├── invoke.ts          # Lógica de invoke (800 linhas)
+├── invoke-types.ts    # Tipos compartilhados
+├── invoke-system-run.ts  # Handler específico
+├── invoke-browser.ts     # Handler específico
+└── config.ts
+```
+
+**Princípios aplicados:**
+- **SRP (Single Responsibility):** Cada arquivo tem uma responsabilidade única
+- **Composição:** `runner.ts` delega para handlers específicos
+- **Testabilidade:** Handlers podem ser testados isoladamente
+
+#### PoolBot (Problema)
+```
+src/node-host/
+└── runner.ts          # Tudo em um arquivo (1200+ linhas)
+```
+
+**Problemas identificados:**
+1. **God Object:** `handleInvoke` faz tudo (exec approvals, browser proxy, system run, file operations)
+2. **Código duplicado:** Padrões de erro repetidos em cada handler
+3. **Difícil testar:** Não há separação para testes unitários
+4. **Manutenção:** Adicionar novo comando requer editar arquivo grande
+
+---
+
+### 2.2 Tratamento de Erros
+
+#### OpenClaw (Excelente)
+
+**Códigos padronizados:**
+```typescript
+// src/gateway/protocol/index.ts
+export const ErrorCodes = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  UNAVAILABLE: -32000,
+  TIMEOUT: -32001,
+  NOT_FOUND: -32002,
+  ALREADY_EXISTS: -32003,
+  UNAUTHORIZED: -32004,
+} as const;
+```
+
+**Helper consistente:**
+```typescript
+// src/gateway/server-methods/nodes.helpers.ts
+export function errorShape(
+  code: number,
+  message: string,
+  meta?: { details?: unknown }
+): ErrorShape {
+  return { code, message, ...(meta ? { details: meta.details } : {}) };
+}
+
+// Uso em qualquer lugar:
+respond(false, undefined, errorShape(ErrorCodes.INVALID_PARAMS, "missing path"));
+```
+
+#### PoolBot (Problema)
+
+**Inconsistência:**
+```typescript
+// Cada handler faz seu próprio erro:
+await sendInvokeResult(client, frame, {
+  ok: false,
+  error: { code: "INVALID_REQUEST", message: String(err) },
+});
+
+// Em outro lugar:
+await sendInvokeResult(client, frame, {
+  ok: false,
+  error: { code: "UNAVAILABLE", message: "command not supported" },
+});
+
+// Código às vezes maiúsculo, às vezes não:
+// "INVALID_REQUEST" vs "Not found"
+```
+
+**Problemas:**
+1. Códigos não padronizados (string vs number)
+2. Mensagens hardcoded
+3. Sem estrutura consistente
+4. Difícil internacionalizar ou modificar
+
+---
+
+### 2.3 Validação de Protocolo
+
+#### OpenClaw (Excelente)
+
+**Schemas AJV completos:**
+```typescript
+// src/gateway/protocol/index.ts
+export const NodeInvokeParamsSchema = {
+  type: "object",
+  properties: {
+    nodeId: { type: "string" },
+    command: { type: "string" },
+    params: { type: "object" },
+    timeoutMs: { type: "number" },
+  },
+  required: ["nodeId", "command"],
+};
+
+export function validateNodeInvokeParams(value: unknown): value is NodeInvokeParams {
+  return validateAgainstSchema(value, NodeInvokeParamsSchema);
+}
+```
+
+#### PoolBot (Problema)
+
+**Validação inline mínima:**
+```typescript
+// Validação ad-hoc em cada handler:
+const filePath = String(params.path ?? "").trim();
+if (!filePath) {
+  throw new Error("INVALID_REQUEST: path required");
+}
+```
+
+---
+
+### 2.4 Estrutura de Comandos
+
+#### OpenClaw (Excelente)
+
+**Constantes centralizadas:**
+```typescript
+// src/infra/node-commands.ts
+export const NODE_SYSTEM_RUN_COMMANDS = [
+  "system.run.prepare",
+  "system.run",
+  "system.which",
+] as const;
+
+export const NODE_EXEC_APPROVALS_COMMANDS = [
+  "system.execApprovals.get",
+  "system.execApprovals.set",
+] as const;
+
+export const NODE_BROWSER_PROXY_COMMAND = "browser.proxy";
+```
+
+**Uso consistente:**
+```typescript
+// src/node-host/runner.ts
+commands: [
+  ...NODE_SYSTEM_RUN_COMMANDS,
+  ...NODE_EXEC_APPROVALS_COMMANDS,
+  ...(browserProxyEnabled ? [NODE_BROWSER_PROXY_COMMAND] : []),
+],
+```
+
+#### PoolBot (Problema)
+
+**Strings espalhadas:**
+```typescript
+// Hardcoded em múltiplos lugares:
+if (command === "system.execApprovals.get") { ... }
+if (command === "browser.proxy") { ... }
+if (command === "file.read") { ... }  // Novo código adicionado inline
+```
+
+---
+
+### 2.5 Ferramentas de Agente
+
+#### OpenClaw (Excelente)
+
+**Classes de erro especializadas:**
+```typescript
+// src/agents/tools/common.ts
+export class ToolInputError extends Error {
+  readonly status: number = 400;
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolInputError";
+  }
+}
+
+export class ToolAuthorizationError extends ToolInputError {
+  override readonly status = 403;
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolAuthorizationError";
+  }
+}
+```
+
+**Helpers de parâmetros reutilizáveis:**
+```typescript
+// src/agents/tools/common.ts
+export function readStringParam(
+  params: Record<string, unknown>,
+  key: string,
+  options: StringParamOptions = {},
+) {
+  const { required = false, trim = true, label = key, allowEmpty = false } = options;
+  const raw = readParamRaw(params, key);
+  if (typeof raw !== "string") {
+    if (required) {
+      throw new ToolInputError(`${label} required`);
+    }
+    return undefined;
+  }
+  // ...
+}
+```
+
+#### PoolBot (Problema)
+
+**Validação inline repetida:**
+```typescript
+// Cada ferramenta repete a mesma lógica:
+const filePath = String(params.path ?? "").trim();
+if (!filePath) {
+  throw new Error("path required");
+}
+
+// Sem helpers reutilizáveis
+// Sem classes de erro especializadas
+```
+
+---
+
+## 3. RECOMENDAÇÕES DE MELHORIA
+
+### 3.1 Refatoração de Arquitetura (Prioridade: 🔴 Alta)
+
+**Ação:** Separar `src/node-host/runner.ts` em módulos
+
+**Estrutura proposta:**
+```
+src/node-host/
+├── runner.ts              # Apenas orquestração
+├── invoke.ts              # Dispatcher de handlers
+├── handlers/
+│   ├── system-run.ts      # system.run, system.which
+│   ├── exec-approvals.ts  # execApprovals.get/set
+│   ├── browser-proxy.ts   # browser.proxy
+│   └── file-operations.ts # file.read/write/exists/delete/list
+├── types.ts               # Tipos compartilhados
+└── config.ts
+```
+
+**Benefícios:**
+- Testabilidade: cada handler pode ser testado isoladamente
+- Manutenção: mudanças em um handler não afetam outros
+- Clareza: novo desenvolvedor entende rapidamente
+
+---
+
+### 3.2 Padronização de Erros (Prioridade: 🔴 Alta)
+
+**Ação:** Criar sistema de erros padronizado
+
+**Implementação:**
+```typescript
+// src/gateway/protocol/errors.ts
+export const ErrorCodes = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  UNAVAILABLE: -32000,
+  TIMEOUT: -32001,
+  NOT_FOUND: -32002,
+} as const;
+
+export function errorShape(
+  code: number,
+  message: string,
+  meta?: { details?: unknown }
+): ErrorShape {
+  return { code, message, ...(meta?.details ? { details: meta.details } : {}) };
+}
+```
+
+**Refatorar todos os handlers para usar:**
+```typescript
+// Antes:
+await sendInvokeResult(client, frame, {
+  ok: false,
+  error: { code: "INVALID_REQUEST", message: "path required" },
+});
+
+// Depois:
+await sendInvokeResult(client, frame, {
+  ok: false,
+  error: errorShape(ErrorCodes.INVALID_PARAMS, "path required"),
+});
+```
+
+---
+
+### 3.3 Centralização de Comandos (Prioridade: 🟡 Média)
+
+**Ação:** Criar constantes para comandos de node
+
+**Implementação:**
+```typescript
+// src/infra/node-commands.ts
+export const NODE_SYSTEM_RUN_COMMANDS = [
+  "system.run",
+  "system.which",
+] as const;
+
+export const NODE_EXEC_APPROVALS_COMMANDS = [
+  "system.execApprovals.get",
+  "system.execApprovals.set",
+] as const;
+
+export const NODE_FILE_COMMANDS = [
+  "file.read",
+  "file.write",
+  "file.exists",
+  "file.delete",
+  "file.list",
+] as const;
+
+export const NODE_BROWSER_PROXY_COMMAND = "browser.proxy";
+```
+
+---
+
+### 3.4 Melhorias nos File Operations (O que já implementamos)
+
+**Status:** ✅ Implementado
+
+**O que foi feito:**
+1. Adicionado handlers para `file.read`, `file.write`, `file.exists`, `file.delete`, `file.list`
+2. Registrado comandos na lista de capabilities do node-host
+3. Adicionado ao node-command-policy como dangerous commands
+
+**O que ainda precisa ser melhorado:**
+1. **Validação de paths:** Prevenir path traversal attacks
+   ```typescript
+   // Adicionar validação:
+   if (path.includes("..") || path.startsWith("/") && isWindows) {
+     throw new Error("Invalid path: path traversal detected");
+   }
+   ```
+
+2. **Rate limiting:** Limitar operações de escrita/exclusão
+3. **Logging:** Auditoria de operações de arquivo
+4. **Tamanho máximo:** Limitar leitura/escrita de arquivos grandes
+
+---
+
+### 3.5 Validação de Schema (Prioridade: 🟡 Média)
+
+**Ação:** Implementar validação AJV para parâmetros de node.invoke
+
+**Implementação:**
+```typescript
+// src/gateway/protocol/node-invoke.ts
+import Ajv from "ajv";
+
+const ajv = new Ajv();
+
+export const FileReadParamsSchema = {
+  type: "object",
+  properties: {
+    path: { type: "string", minLength: 1 },
+    encoding: { enum: ["utf8", "base64"] },
+  },
+  required: ["path"],
+};
+
+export const validateFileReadParams = ajv.compile(FileReadParamsSchema);
+```
+
+---
+
+## 4. CORREÇÕES IMEDIATAS Necessárias
+
+### 4.1 Path Traversal Vulnerability
+
+**Problema:** Nossa implementação atual de file operations não valida paths:
+
+```typescript
+// src/node-host/runner.ts (atual)
+const filePath = String(params.path ?? "").trim();
+// Pode ser: "../../../etc/passwd"
+```
+
+**Fix necessário:**
+```typescript
+function sanitizePath(inputPath: string, allowedBasePath?: string): string {
+  const normalized = path.normalize(inputPath);
+  
+  // Bloquear path traversal
+  if (normalized.includes("..")) {
+    throw new Error("Path traversal not allowed");
+  }
+  
+  // Opcional: restringir a base path
+  if (allowedBasePath && !normalized.startsWith(allowedBasePath)) {
+    throw new Error("Path outside allowed directory");
+  }
+  
+  return normalized;
+}
+```
+
+---
+
+### 4.2 Limite de Tamanho de Arquivo
+
+**Problema:** Leitura de arquivos grandes pode causar OOM:
+
+```typescript
+// Atual: lê arquivo inteiro na memória
+const content = await fsPromises.readFile(filePath, encoding);
+```
+
+**Fix necessário:**
+```typescript
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+
+const stat = await fsPromises.stat(filePath);
+if (stat.size > MAX_FILE_SIZE) {
+  throw new Error(`File too large: ${stat.size} bytes (max ${MAX_FILE_SIZE})`);
+}
+```
+
+---
+
+### 4.3 Erros Específicos do Sistema
+
+**Problema:** Não distinguimos entre diferentes tipos de erro:
+
+```typescript
+// Atual: código genérico
+const code = (err as NodeJS.ErrnoException)?.code === "ENOENT" ? "NOT_FOUND" : "INVALID_REQUEST";
+```
+
+**Fix necessário:**
+```typescript
+function mapSystemErrorCode(code: string | undefined): number {
+  switch (code) {
+    case "ENOENT": return ErrorCodes.NOT_FOUND;
+    case "EACCES": return ErrorCodes.UNAUTHORIZED;
+    case "EISDIR": return ErrorCodes.INVALID_PARAMS;
+    case "ENOTDIR": return ErrorCodes.INVALID_PARAMS;
+    default: return ErrorCodes.INTERNAL_ERROR;
+  }
+}
+```
+
+---
+
+## 5. PLANO DE IMPLEMENTAÇÃO
+
+### Fase 1: Segurança (Imediato)
+1. ✅ Implementar file operations (feito)
+2. 🔄 Adicionar path traversal protection
+3. 🔄 Adicionar limits de tamanho
+4. 🔄 Mapear códigos de erro do sistema
+
+### Fase 2: Refatoração (Próxima sprint)
+1. Separar handlers em módulos
+2. Criar sistema de erros padronizado
+3. Centralizar constantes de comandos
+
+### Fase 3: Qualidade (Futuro)
+1. Implementar schemas AJV
+2. Criar helpers de validação de parâmetros
+3. Adicionar testes unitários para handlers
+4. Melhorar documentação
+
+---
+
+## 6. CONCLUSÃO
+
+O PoolBot tem uma base sólida, mas carece de:
+1. **Arquitetura mais modular** (aprendizado do OpenClaw)
+2. **Tratamento de erros padronizado**
+3. **Segurança reforçada** em operações de arquivo
+
+A implementação do `nodes_file` tool foi um bom começo, mas precisa de hardening de segurança antes de ser usada em produção.
+
+**Recomendação:** Priorizar as correções de segurança (Fase 1) antes de continuar com novas features.