@poolzin/pool-bot 2026.3.13 → 2026.3.15

package/docs/plans/2026-03-11-integracao-projetos-poolbot.md

@@ -0,0 +1,666 @@
+# Integração Completa: HexStrike AI + Projetos no PoolBot
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Integrar HexStrike AI, Page Agent, XYOps e Agency Agents como extensões nativas do PoolBot, eliminando dependências externas.
+
+**Architecture:** 
+- HexStrike AI → Extensão `extensions/hexstrike-ai` com servidor embutido
+- Page Agent → Extensão `extensions/page-agent` para automação web
+- XYOps → Extensão `extensions/xyops` para operações de infraestrutura
+- Agency Agents → Extensão `extensions/agency` para gestão de agentes
+
+**Tech Stack:** TypeScript, Python (para HexStrike), Node.js 22+, PoolBot Extension SDK
+
+---
+
+## Análise dos Projetos
+
+### HexStrike AI (`/Users/pool/Downloads/hexstrike-ai-master`)
+- **Tamanho:** ~950KB (Python)
+- **Componentes:** 
+  - `hexstrike_server.py` - Servidor principal (735KB)
+  - `hexstrike_mcp.py` - Interface MCP (218KB)
+  - `requirements.txt` - Dependências Python
+- **Porta:** 8888 (localhost)
+- **Integração Atual:** Bridge existe em `extensions/hexstrike-bridge/`
+
+### Page Agent (`/Users/pool/Downloads/page-agent-main`)
+- **Tamanho:** ~1MB
+- **Componentes:**
+  - Sistema de agentes para automação web
+  - Integração com Playwright
+  - Estrutura modular
+
+### XYOps (`/Users/pool/Downloads/xyops-main`)
+- **Tamanho:** A verificar
+- **Foco:** Operações de infraestrutura e DevOps
+
+### Agency Agents (`/Users/pool/Downloads/agency-agents-main`)
+- **Tamanho:** ~112KB
+- **Componentes:**
+  - 15+ categorias de agentes especializados
+  - Marketing, Engineering, Design, etc.
+  - Estrutura de templates e prompts
+
+---
+
+## Fase 1: HexStrike AI - Integração Completa
+
+### Task 1: Criar estrutura da extensão
+
+**Files:**
+- Create: `extensions/hexstrike-ai/package.json`
+- Create: `extensions/hexstrike-ai/poolbot.plugin.json`
+- Create: `extensions/hexstrike-ai/README.md`
+
+**Step 1: Criar package.json**
+
+```json
+{
+  "name": "@poolbot/hexstrike-ai",
+  "version": "2026.3.13",
+  "description": "HexStrike AI Security Platform - Integrated Server",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start:server": "python3 src/server/hexstrike_server.py",
+    "install:deps": "pip3 install -r src/server/requirements.txt"
+  },
+  "dependencies": {
+    "poolbot": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  },
+  "poolbot": {
+    "plugin": true,
+    "server": true,
+    "python": true
+  }
+}
+```
+
+**Step 2: Criar poolbot.plugin.json**
+
+```json
+{
+  "id": "hexstrike-ai",
+  "name": "HexStrike AI",
+  "version": "2026.3.13",
+  "description": "Security scanning platform with 150+ scanners integrated",
+  "author": "PoolBot Team",
+  "main": "dist/index.js",
+  "capabilities": ["security", "scanning", "pentest"],
+  "commands": [
+    "security.status",
+    "security.tools",
+    "security.scan",
+    "security.report"
+  ],
+  "hooks": ["onInit", "onShutdown"],
+  "config": {
+    "port": 8888,
+    "host": "127.0.0.1",
+    "autoStart": true,
+    "scanners": ["nmap", "nuclei", "sqlmap", "gobuster", "wpscan"]
+  }
+}
+```
+
+**Step 3: Commit**
+
+```bash
+git add extensions/hexstrike-ai/
+git commit -m "feat(hexstrike-ai): create extension structure"
+```
+
+---
+
+### Task 2: Copiar e adaptar código Python do HexStrike
+
+**Files:**
+- Create: `extensions/hexstrike-ai/src/server/hexstrike_server.py`
+- Create: `extensions/hexstrike-ai/src/server/hexstrike_mcp.py`
+- Create: `extensions/hexstrike-ai/src/server/requirements.txt`
+
+**Step 1: Copiar arquivos Python**
+
+```bash
+cp /Users/pool/Downloads/hexstrike-ai-master/hexstrike_server.py extensions/hexstrike-ai/src/server/
+cp /Users/pool/Downloads/hexstrike-ai-master/hexstrike_mcp.py extensions/hexstrike-ai/src/server/
+cp /Users/pool/Downloads/hexstrike-ai-master/requirements.txt extensions/hexstrike-ai/src/server/
+```
+
+**Step 2: Modificar servidor para integração PoolBot**
+
+Editar `extensions/hexstrike-ai/src/server/hexstrike_server.py`:
+- Adicionar endpoint `/poolbot/health` para health checks
+- Adicionar autenticação via token PoolBot
+- Configurar CORS para comunicação com gateway
+- Adicionar logging estruturado
+
+**Step 3: Commit**
+
+```bash
+git add extensions/hexstrike-ai/src/server/
+git commit -m "feat(hexstrike-ai): import Python server code"
+```
+
+---
+
+### Task 3: Criar TypeScript wrapper e integração
+
+**Files:**
+- Create: `extensions/hexstrike-ai/src/index.ts`
+- Create: `extensions/hexstrike-ai/src/server-manager.ts`
+- Create: `extensions/hexstrike-ai/src/client.ts`
+- Create: `extensions/hexstrike-ai/tsconfig.json`
+
+**Step 1: Criar tsconfig.json**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**Step 2: Criar server-manager.ts**
+
+```typescript
+import { spawn, ChildProcess } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export interface ServerConfig {
+  port: number;
+  host: string;
+  pythonPath?: string;
+}
+
+export class HexStrikeServerManager {
+  private process: ChildProcess | null = null;
+  private config: ServerConfig;
+
+  constructor(config: Partial<ServerConfig> = {}) {
+    this.config = {
+      port: config.port ?? 8888,
+      host: config.host ?? "127.0.0.1",
+      pythonPath: config.pythonPath ?? "python3",
+    };
+  }
+
+  async start(): Promise<void> {
+    const serverPath = path.join(__dirname, "server", "hexstrike_server.py");
+    
+    this.process = spawn(this.config.pythonPath, [serverPath], {
+      env: {
+        ...process.env,
+        HEXSTRIKE_PORT: String(this.config.port),
+        HEXSTRIKE_HOST: this.config.host,
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("HexStrike server failed to start within 30s"));
+      }, 30000);
+
+      this.process?.stdout?.on("data", (data: Buffer) => {
+        const output = data.toString();
+        if (output.includes("Server started") || output.includes("Listening")) {
+          clearTimeout(timeout);
+          resolve();
+        }
+      });
+
+      this.process?.stderr?.on("data", (data: Buffer) => {
+        console.error(`[HexStrike] ${data.toString()}`);
+      });
+
+      this.process?.on("error", (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+
+      this.process?.on("exit", (code) => {
+        if (code !== 0 && code !== null) {
+          clearTimeout(timeout);
+          reject(new Error(`HexStrike server exited with code ${code}`));
+        }
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (this.process) {
+      this.process.kill("SIGTERM");
+      await new Promise((resolve) => setTimeout(resolve, 5000));
+      if (!this.process.killed) {
+        this.process.kill("SIGKILL");
+      }
+      this.process = null;
+    }
+  }
+
+  get isRunning(): boolean {
+    return this.process !== null && !this.process.killed;
+  }
+}
+```
+
+**Step 3: Criar client.ts**
+
+```typescript
+export interface ScanTarget {
+  target: string;
+  scanners?: string[];
+  options?: Record<string, unknown>;
+}
+
+export interface ScanResult {
+  id: string;
+  status: "pending" | "running" | "completed" | "failed";
+  findings: Array<{
+    severity: "info" | "low" | "medium" | "high" | "critical";
+    title: string;
+    description: string;
+    remediation?: string;
+  }>;
+  metadata: {
+    startedAt: string;
+    completedAt?: string;
+    duration?: number;
+  };
+}
+
+export class HexStrikeClient {
+  private baseUrl: string;
+  private token?: string;
+
+  constructor(config: { host?: string; port?: number; token?: string } = {}) {
+    const host = config.host ?? "127.0.0.1";
+    const port = config.port ?? 8888;
+    this.baseUrl = `http://${host}:${port}`;
+    this.token = config.token;
+  }
+
+  async health(): Promise<{ status: string; version?: string }> {
+    const response = await fetch(`${this.baseUrl}/health`);
+    if (!response.ok) throw new Error(`Health check failed: ${response.status}`);
+    return response.json();
+  }
+
+  async getTools(): Promise<string[]> {
+    const response = await fetch(`${this.baseUrl}/api/tools`, {
+      headers: this.getHeaders(),
+    });
+    if (!response.ok) throw new Error(`Failed to get tools: ${response.status}`);
+    const data = await response.json();
+    return data.tools ?? [];
+  }
+
+  async scan(target: ScanTarget): Promise<{ scanId: string }> {
+    const response = await fetch(`${this.baseUrl}/api/scan`, {
+      method: "POST",
+      headers: this.getHeaders(),
+      body: JSON.stringify(target),
+    });
+    if (!response.ok) throw new Error(`Scan failed: ${response.status}`);
+    const data = await response.json();
+    return { scanId: data.id };
+  }
+
+  async getScanResult(scanId: string): Promise<ScanResult> {
+    const response = await fetch(`${this.baseUrl}/api/scan/${scanId}`, {
+      headers: this.getHeaders(),
+    });
+    if (!response.ok) throw new Error(`Failed to get scan: ${response.status}`);
+    return response.json();
+  }
+
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
+}
+```
+
+**Step 4: Criar index.ts (entry point)**
+
+```typescript
+import type { PoolBotPlugin } from "poolbot/plugin-sdk";
+import { HexStrikeServerManager } from "./server-manager.js";
+import { HexStrikeClient } from "./client.js";
+
+interface HexStrikeConfig {
+  port?: number;
+  host?: string;
+  autoStart?: boolean;
+  token?: string;
+}
+
+export default async function createPlugin(
+  ctx: PoolBotPlugin.Context
+): Promise<PoolBotPlugin.Instance> {
+  const config = ctx.config as HexStrikeConfig;
+  const serverManager = new HexStrikeServerManager({
+    port: config.port,
+    host: config.host,
+  });
+
+  const client = new HexStrikeClient({
+    host: config.host,
+    port: config.port,
+    token: config.token,
+  });
+
+  // Auto-start server if configured
+  if (config.autoStart !== false) {
+    ctx.logger.info("Starting HexStrike AI server...");
+    await serverManager.start();
+    ctx.logger.info("HexStrike AI server started");
+  }
+
+  // Register CLI commands
+  ctx.cli
+    .command("security.status")
+    .description("Check HexStrike AI server status")
+    .action(async () => {
+      try {
+        const health = await client.health();
+        console.log("HexStrike AI Status:", health.status);
+        console.log("Version:", health.version ?? "unknown");
+      } catch (err) {
+        console.error("HexStrike AI is not running");
+        process.exit(1);
+      }
+    });
+
+  ctx.cli
+    .command("security.tools")
+    .description("List available security scanners")
+    .action(async () => {
+      const tools = await client.getTools();
+      console.log("Available scanners:");
+      for (const tool of tools) {
+        console.log(`  - ${tool}`);
+      }
+    });
+
+  ctx.cli
+    .command("security.scan")
+    .description("Run security scan on target")
+    .argument("<target>", "Target to scan")
+    .option("-s, --scanners <scanners>", "Comma-separated list of scanners")
+    .action(async (target: string, options: { scanners?: string }) => {
+      const scan = await client.scan({
+        target,
+        scanners: options.scanners?.split(","),
+      });
+      console.log("Scan started:", scan.scanId);
+    });
+
+  return {
+    name: "hexstrike-ai",
+    version: "2026.3.13",
+    async onShutdown() {
+      ctx.logger.info("Stopping HexStrike AI server...");
+      await serverManager.stop();
+    },
+  };
+}
+
+export { HexStrikeServerManager, HexStrikeClient };
+```
+
+**Step 5: Commit**
+
+```bash
+git add extensions/hexstrike-ai/src/
+git commit -m "feat(hexstrike-ai): add TypeScript wrapper and integration"
+```
+
+---
+
+### Task 4: Integrar com Gateway PoolBot
+
+**Files:**
+- Modify: `src/gateway/rpc.ts` (adicionar métodos HexStrike)
+- Modify: `extensions/hexstrike-bridge/src/index.ts` (atualizar para usar servidor local)
+
+**Step 1: Adicionar RPC methods ao gateway**
+
+Adicionar em `src/gateway/rpc.ts`:
+
+```typescript
+// HexStrike AI RPC methods
+hexstrike: {
+  status: () => Promise<{ running: boolean; version?: string }>;
+  tools: () => Promise<string[]>;
+  scan: (params: { target: string; scanners?: string[] }) => Promise<{ scanId: string }>;
+  scanResult: (params: { scanId: string }) => Promise<unknown>;
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add src/gateway/rpc.ts
+git commit -m "feat(gateway): add HexStrike AI RPC methods"
+```
+
+---
+
+## Fase 2: Page Agent Integration
+
+### Task 5: Criar estrutura Page Agent
+
+**Files:**
+- Create: `extensions/page-agent/package.json`
+- Create: `extensions/page-agent/poolbot.plugin.json`
+- Create: `extensions/page-agent/src/index.ts`
+
+**Step 1: Criar package.json**
+
+```json
+{
+  "name": "@poolbot/page-agent",
+  "version": "2026.3.13",
+  "description": "Web automation agent with Playwright integration",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "poolbot": "workspace:*",
+    "playwright": "^1.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add extensions/page-agent/
+git commit -m "feat(page-agent): create extension structure"
+```
+
+---
+
+### Task 6: Copiar e adaptar código Page Agent
+
+**Files:**
+- Create: `extensions/page-agent/src/browser.ts`
+- Create: `extensions/page-agent/src/agent.ts`
+- Create: `extensions/page-agent/src/actions.ts`
+
+**Step 1: Analisar código fonte**
+
+```bash
+ls -la /Users/pool/Downloads/page-agent-main/
+find /Users/pool/Downloads/page-agent-main/ -name "*.ts" -o -name "*.js" | head -20
+```
+
+**Step 2: Copiar e adaptar arquivos principais**
+
+Copiar lógica de automação web do Page Agent para a extensão PoolBot.
+
+**Step 3: Commit**
+
+```bash
+git add extensions/page-agent/src/
+git commit -m "feat(page-agent): import and adapt Page Agent code"
+```
+
+---
+
+## Fase 3: XYOps Integration
+
+### Task 7: Criar estrutura XYOps
+
+**Files:**
+- Create: `extensions/xyops/package.json`
+- Create: `extensions/xyops/poolbot.plugin.json`
+- Create: `extensions/xyops/src/index.ts`
+
+**Step 1: Analisar código fonte**
+
+```bash
+ls -la /Users/pool/Downloads/xyops-main/ 2>/dev/null || echo "Directory not found"
+```
+
+**Step 2: Criar estrutura base**
+
+```json
+{
+  "name": "@poolbot/xyops",
+  "version": "2026.3.13",
+  "description": "Infrastructure and DevOps operations automation",
+  "type": "module",
+  "main": "dist/index.js"
+}
+```
+
+---
+
+## Fase 4: Agency Agents Integration
+
+### Task 8: Criar estrutura Agency
+
+**Files:**
+- Create: `extensions/agency/package.json`
+- Create: `extensions/agency/poolbot.plugin.json`
+
+**Step 1: Analisar estrutura**
+
+```bash
+ls /Users/pool/Downloads/agency-agents-main/
+```
+
+**Step 2: Criar extensão que expõe templates de agentes**
+
+A extensão Agency vai fornecer templates pré-configurados para diferentes tipos de agentes (marketing, engineering, design, etc.).
+
+---
+
+## Fase 5: Build e Teste
+
+### Task 9: Build todas as extensões
+
+**Step 1: Instalar dependências**
+
+```bash
+cd extensions/hexstrike-ai && pnpm install && pnpm build
+cd ../page-agent && pnpm install && pnpm build
+cd ../xyops && pnpm install && pnpm build
+cd ../agency && pnpm install && pnpm build
+```
+
+**Step 2: Testar integração**
+
+```bash
+pnpm poolbot security status
+pnpm poolbot security tools
+```
+
+**Step 3: Commit final**
+
+```bash
+git add .
+git commit -m "feat(extensions): integrate HexStrike AI, Page Agent, XYOps, Agency"
+```
+
+---
+
+## Resumo da Integração
+
+| Projeto         | Extensão PoolBot           | Status      |
+| --------------- | -------------------------- | ----------- |
+| HexStrike AI    | `extensions/hexstrike-ai/`   | 🚧 Em progresso |
+| Page Agent      | `extensions/page-agent/`     | 🚧 Em progresso |
+| XYOps           | `extensions/xyops/`          | 🚧 Em progresso |
+| Agency Agents   | `extensions/agency/`         | 🚧 Em progresso |
+
+---
+
+## Comandos Disponíveis Após Integração
+
+```bash
+# HexStrike AI
+poolbot security status              # Verificar status do servidor
+poolbot security tools               # Listar scanners disponíveis
+poolbot security scan <target>       # Executar scan de segurança
+poolbot security report <scan-id>    # Ver resultado do scan
+
+# Page Agent
+poolbot browser agent <url>          # Iniciar agente de automação
+poolbot browser screenshot <url>     # Capturar screenshot
+poolbot browser crawl <url>          # Crawler inteligente
+
+# XYOps
+poolbot infra status                 # Status da infraestrutura
+poolbot infra deploy <stack>         # Deploy de stack
+poolbot infra monitor                # Monitoramento
+
+# Agency
+poolbot agent list                   # Listar templates de agentes
+poolbot agent create <type>          # Criar agente especializado
+```
+
+---
+
+**Próximo passo:** Executar Task 1 para começar a integração do HexStrike AI.