@runflow-ai/cli 0.2.11 → 0.2.12

package/CLI-DOCS.md

@@ -396,6 +396,95 @@ rf executions list
 rf traces list
 ```
 
+---
+
+## 🧪 Test (Local Testing)
+
+Inicia servidor local de observabilidade e abre o portal cloud para testar agentes.
+
+```bash
+rf test [options]
+```
+
+**Opções:**
+- `-p, --port <port>` - Porta base do servidor (default: aleatória entre 3000-4000)
+- `--no-browser` - Não abre o navegador automaticamente
+
+**Características:**
+- ✅ Zero configuração - detecta `agentId` automaticamente do `.runflow/rf.json`
+- ✅ Portas aleatórias - evita conflitos tentando até 3 portas
+- ✅ Portal cloud - usa `platform.runflow.ai` sempre atualizado
+- ✅ Dados locais - traces armazenados em `.runflow/traces/`
+- ✅ Monitoramento real-time - visualize threads, execuções e traces
+
+**Exemplo básico:**
+```bash
+# Simplesmente rode (detecta tudo automaticamente)
+rf test
+
+# Output:
+# 🧪 Runflow Test Server
+# ✓ Found agent config
+#   Agent: Agent com RAG (Agentic)
+# ✓ Local server running on port 3421
+# ✓ Opening browser...
+# 
+# 📊 Test Portal Ready!
+#    🌐 Portal: https://platform.runflow.ai/agents/abc.../test-monitor?...
+#    📡 API: http://localhost:3421
+#    💾 Storage: .runflow/traces/
+```
+
+**Com opções:**
+```bash
+# Porta customizada
+rf test --port 4500
+
+# Sem abrir navegador
+rf test --no-browser
+```
+
+**Como funciona:**
+
+1. **Lê configuração** do `.runflow/rf.json` (agentId, agentName)
+2. **Inicia servidor local** com 3 APIs de observabilidade
+3. **Tenta até 3 portas** caso a primeira esteja ocupada
+4. **Abre portal cloud** (`platform.runflow.ai`) com parâmetros corretos
+5. **Portal conecta** ao servidor local para buscar dados
+
+**APIs disponíveis:**
+- `GET /health` - Health check
+- `GET /api/v1/observability/threads` - Lista threads
+- `GET /api/v1/observability/threads/:threadId/executions` - Lista execuções
+- `GET /api/v1/observability/executions/:executionId` - Detalhes de traces
+
+**Estrutura de armazenamento:**
+```
+.runflow/
+├── rf.json              # Configuração do agente
+└── traces/              # Armazenamento de traces
+    ├── 2025-11-06/      # Pastas por data
+    │   └── session-*.json
+    └── 2025-11-07/
+        └── ...
+```
+
+**Fluxo típico de uso:**
+```bash
+# Terminal 1: Inicie o servidor de teste
+cd meu-agente/
+rf test
+
+# Terminal 2: Execute seu agente
+npm run dev
+# ou
+node agent.ts
+```
+
+**📚 Documentação completa:** [`docs/TEST-COMMAND.md`](docs/TEST-COMMAND.md)
+
+---
+
 ## Troubleshooting
 
 ### Problemas de Autenticação

package/QUICK-TEST-GUIDE.md

@@ -0,0 +1,273 @@
+# 🚀 Quick Test Guide - rf test
+
+## TL;DR
+
+```bash
+cd seu-agente/
+rf test
+```
+
+That's it! 🎉
+
+---
+
+## Passo a Passo Completo
+
+### 1. Instale ou atualize a CLI
+
+```bash
+# Se ainda não tem instalado
+npm install -g @runflow-ai/cli
+
+# Se já tem, atualize
+npm update -g @runflow-ai/cli
+```
+
+### 2. Entre no diretório do agente
+
+```bash
+cd smartfit-agents/agent-com-rag/
+# ou qualquer agente com .runflow/rf.json
+```
+
+### 3. Execute o comando test
+
+```bash
+rf test
+```
+
+**Output esperado:**
+
+```
+🧪 Runflow Test Server
+Starting local observability server...
+
+✓ Found agent config
+  Agent: Agent com RAG (Agentic)
+
+✓ Local server running on port 3421
+
+✓ Opening browser...
+
+📊 Test Portal Ready!
+
+   🌐 Portal: https://platform.runflow.ai/local-test/agents/fbc4c76d-57b3-40c3-a165-c4edcbf28434/test-monitor?apiUrl=http://localhost:3421&agentName=Agent%20com%20RAG
+   📡 API: http://localhost:3421
+   💾 Storage: /Users/danrleymorais/projects/runflow/runflow-sdk-repo/smartfit-agents/agent-com-rag/.runflow/traces
+
+⚠️  Note: Your browser may show a warning about
+   mixed content (HTTPS → HTTP). Click "Allow" if prompted.
+
+Press Ctrl+C to stop
+```
+
+### 4. Teste no navegador
+
+O portal abre automaticamente em `https://platform.runflow.ai` com:
+- Interface de teste (40% esquerda)
+- Monitoramento em tempo real (60% direita)
+
+**Features disponíveis:**
+- ✅ Enviar mensagens para o agente
+- ✅ Ver lista de threads (conversas)
+- ✅ Ver execuções por thread
+- ✅ Visualizar traces detalhados (árvore hierárquica)
+- ✅ Métricas: tokens, custo, duração
+
+### 5. Execute seu agente (em outro terminal)
+
+```bash
+# Terminal 2
+cd seu-agente/
+npm run dev
+# ou
+node agent.ts
+```
+
+As execuções aparecerão automaticamente no portal! 🎯
+
+---
+
+## 🧪 Testando com dados de exemplo
+
+Para testar a visualização sem executar o agente, use o trace de exemplo:
+
+```bash
+# 1. Crie o diretório de traces
+mkdir -p .runflow/traces/2025-11-06
+
+# 2. Copie o arquivo de exemplo
+cp /path/to/runflow-cli/docs/trace-example.json .runflow/traces/2025-11-06/session-test-1730894400000.json
+
+# 3. Edite o agentId no arquivo para corresponder ao seu
+# Substitua "fbc4c76d-..." pelo agentId do seu .runflow/rf.json
+
+# 4. Inicie o servidor
+rf test
+```
+
+Agora você verá threads e execuções de exemplo no portal! ✨
+
+---
+
+## 🎛️ Opções Avançadas
+
+### Porta customizada
+
+```bash
+rf test --port 5000
+```
+
+### Sem abrir navegador
+
+```bash
+rf test --no-browser
+
+# Depois abra manualmente:
+open https://platform.runflow.ai/agents/SEU_AGENT_ID/test-monitor?apiUrl=http://localhost:3421&mode=local
+```
+
+### Múltiplos agentes simultaneamente
+
+```bash
+# Terminal 1
+cd agent-1/
+rf test --port 3500
+
+# Terminal 2
+cd agent-2/
+rf test --port 3600
+
+# Terminal 3
+cd agent-3/
+rf test --port 3700
+```
+
+Cada um abrirá em uma aba diferente do navegador! 🔥
+
+---
+
+## 🐛 Troubleshooting
+
+### Erro: "No agentId found"
+
+```bash
+❌ No agentId found in .runflow/rf.json
+   Run "rf clone <agentId>" first
+```
+
+**Solução:**
+```bash
+# Clone um agente primeiro
+rf agents list
+# Selecione um agente e clone
+```
+
+### Erro: "Failed to start server after 3 attempts"
+
+```bash
+❌ Failed to start server after 3 attempts
+   All ports are busy. Try again later.
+```
+
+**Solução:**
+```bash
+# Tente porta específica
+rf test --port 5000
+
+# Ou mate processos ocupando portas
+lsof -ti:3000,3001,3002 | xargs kill
+```
+
+### Portal não mostra dados
+
+**Verificações:**
+1. ✅ Servidor está rodando? `curl http://localhost:3421/health`
+2. ✅ Diretório de traces existe? `ls .runflow/traces/`
+3. ✅ AgentId correto na URL?
+4. ✅ Console do navegador tem erros?
+
+**Solução comum:**
+```bash
+# Recarregue a página permitindo mixed content
+# Chrome: Click no shield icon → "Load unsafe scripts"
+# Firefox: Click no shield icon → "Disable protection"
+```
+
+### Mixed Content Warning
+
+O navegador pode avisar sobre **mixed content** (HTTPS → HTTP):
+
+**Chrome:**
+1. Click no ícone de shield na barra de endereço
+2. Click em "Load unsafe scripts"
+
+**Firefox:**
+1. Click no ícone de shield
+2. Click em "Disable protection for now"
+
+**Safari:**
+1. Safari → Preferences → Advanced
+2. Enable "Show Develop menu"
+3. Develop → Disable Cross-Origin Restrictions
+
+---
+
+## 📊 Estrutura de Dados
+
+### Storage Local
+
+```
+.runflow/
+├── rf.json                                    # Config do agente
+└── traces/                                     # Traces
+    ├── 2025-11-06/
+    │   ├── session-abc123-1730894400000.json  # Sessão 1
+    │   └── session-xyz789-1730894500000.json  # Sessão 2
+    └── 2025-11-07/
+        └── ...
+```
+
+### Formato de Trace
+
+Ver [`docs/trace-example.json`](docs/trace-example.json) para exemplo completo.
+
+**Estrutura básica:**
+```json
+{
+  "sessionId": "session-uuid-timestamp",
+  "agentId": "agent-uuid",
+  "createdAt": "2025-11-06T10:00:00Z",
+  "threads": {
+    "user@email.com": {
+      "threadId": "user@email.com",
+      "executions": [
+        {
+          "executionId": "exec-uuid",
+          "inputMessage": "Hello",
+          "outputMessage": "Hi!",
+          "status": "success",
+          "traces": [ /* árvore de traces */ ]
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## ✨ Próximos Passos
+
+1. **Teste básico:** `rf test` e envie mensagens no portal
+2. **Execute agente:** Em outro terminal, rode seu agente
+3. **Monitore:** Veja execuções em tempo real
+4. **Debug:** Analise traces detalhados
+5. **Itere:** Faça mudanças e teste novamente
+
+**Happy testing!** 🚀
+
+Para mais detalhes, veja:
+- [`docs/TEST-COMMAND.md`](docs/TEST-COMMAND.md) - Documentação completa
+- [`CLI-DOCS.md`](CLI-DOCS.md) - Todos os comandos da CLI
+

package/dist/commands/test/test.command.d.ts

@@ -1,24 +1,31 @@
 import { CommandRunner } from 'nest-commander';
 interface TestCommandOptions {
     port?: number;
-    host?: string;
-    open?: boolean;
-    verbose?: boolean;
+    noBrowser?: boolean;
 }
 export declare class TestCommand extends CommandRunner {
     private server;
-    private frontend;
+    private app;
+    private storageDir;
     run(passedParam: string[], options?: TestCommandOptions): Promise<void>;
     parsePort(val: string): number;
-    parseHost(val: string): string;
-    parseOpen(): boolean;
-    parseVerbose(val: string): boolean;
+    parseNoBrowser(): boolean;
     private loadRunflowConfig;
-    private ensureDependencies;
-    private startTestServer;
-    private startFrontend;
-    private waitForServer;
-    private runCommand;
+    private executeAgent;
+    private getRandomPort;
+    private generateSessionId;
+    private generateUserId;
+    private createFingerprint;
+    private ensureStorageDir;
+    private startObservabilityServer;
+    private setupObservabilityEndpoints;
+    private getThreads;
+    private getThreadExecutions;
+    private getExecutionTraces;
+    private countAllTraces;
+    private getAllTraceFiles;
+    private getSDKTraces;
+    private buildTraceHierarchy;
     private openBrowser;
     private setupCleanupHandlers;
     private cleanup;