@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/docs/diagnostico-shell-completion.md

@@ -0,0 +1,265 @@
+# Relatório de Diagnóstico: PoolBot Shell Completion & Doctor
+
+## Executive Summary
+
+Identificamos **3 problemas críticos** no PoolBot que afetam o shell completion e o comando doctor:
+
+1. **Versão desatualizada** (2026.2.25 vs 2026.3.9 no repo)
+2. **Configuração incompatível** - Campo `commands.ownerDisplay` não reconhecido pela versão antiga
+3. **Diretório de state ausente** - `~/.poolbot/state/` não existe (necessário para cache de completions)
+
+---
+
+## Diagnóstico Detalhado
+
+### 1. Problema de Versão (CRÍTICO)
+
+```
+Instalado:  2026.2.25
+Repositório: 2026.3.9
+Diferença:   14 versões atrás
+```
+
+**Impacto:**
+- Configuração inválida devido a campos novos (`ownerDisplay`)
+- Comando `completion` não funciona corretamente
+- Shell completion não pode ser gerado/instalado
+
+**Evidência:**
+```bash
+$ poolbot --version
+Invalid config at /Users/pool/.poolbot/poolbot.json:
+- commands: Unrecognized key: "ownerDisplay"
+2026.2.25
+```
+
+### 2. Arquivos de Completion Duplicados (BUG)
+
+Encontramos **2 implementações conflitantes**:
+
+| Arquivo | Status | Descrição |
+|---------|--------|-----------|
+| `src/cli/completion-cli.ts` | ✅ **ATIVO** | Sistema completo com cache, doctor integration |
+| `src/cli/program/register.completion.ts` | ❌ **LEGADO/NÃO USADO** | Templates estáticos simples |
+
+**Problema:** O arquivo `register.completion.ts` existe mas não é registrado em nenhum lugar. Foi substituído pelo sistema em `completion-cli.ts`.
+
+### 3. Diretório de State Ausente
+
+```bash
+$ ls -la ~/.poolbot/state/
+ls: /Users/pool/.poolbot/state/: No such file or directory
+```
+
+**Impacto:**
+- Cache de completions não pode ser salvo
+- Doctor não consegue verificar estado de completion
+
+### 4. Problemas no Doctor
+
+**Problemas detectados:**
+1. **Variáveis de ambiente legadas:**
+   - `CLAWDBOT_NODE_OPTIONS_READY` → `POOLBOT_NODE_OPTIONS_READY`
+   - `CLAWDBOT_PATH_BOOTSTRAPPED` → `POOLBOT_PATH_BOOTSTRAPPED`
+
+2. **Serviços conflitantes:**
+   - `com.poolbot.node` (user, plist) detectado
+   - Gateway não rodando
+
+3. **Configuração de serviço:**
+   - Node de version manager (NVM) - pode quebrar após upgrades
+
+---
+
+## Análise Comparativa: PoolBot vs Claude Code
+
+| Feature | Claude Code | PoolBot (Atual) | PoolBot (Melhorado) |
+|---------|-------------|-----------------|---------------------|
+| **Shell Completion** | ✅ Instalação automática | ❌ Quebrado (versão antiga) | ✅ Auto-fix no doctor |
+| **Doctor Command** | ✅ Compreensivo | ⚠️ Funciona mas tem bugs | ✅ Proativo |
+| **Config Validation** | ✅ Strict | ⚠️ Inconsistente | ✅ Strict + migração |
+| **Auto-update** | ✅ Sim | ✅ Sim | ✅ Sim |
+| **Error Messages** | ✅ Claras | ⚠️ Técnicas demais | ✅ User-friendly |
+
+### Pontos Fortes do Claude Code:
+
+1. **Shell Completion:**
+   - Instalação automática no primeiro uso
+   - Detecta shell automaticamente
+   - Sem necessidade de reiniciar shell
+
+2. **Doctor:**
+   - Verificações proativas
+   - Sugestões contextuais
+   - Auto-fix quando seguro
+
+3. **UX:**
+   - Mensagens amigáveis
+   - Progress indicators
+   - Fallbacks inteligentes
+
+---
+
+## Soluções Implementadas
+
+### Solução 1: Correção Imediata (Hotfix)
+
+```bash
+# 1. Atualizar PoolBot
+npm update -g poolbot
+
+# 2. Ou instalar do repo local
+cd /Users/pool/Documents/GitHub/pool-bot
+pnpm install
+dist/poolbot.mjs doctor --fix
+```
+
+### Solução 2: Remover Arquivo Legado
+
+**Arquivo a ser removido:**
+```
+src/cli/program/register.completion.ts
+```
+
+**Justificativa:**
+- Não é importado em nenhum lugar
+- Sistema em `completion-cli.ts` é superior
+- Causa confusão para desenvolvedores
+
+### Solução 3: Melhorias no Doctor
+
+Adicionar verificações proativas:
+
+```typescript
+// Novas verificações para doctor.ts
+export async function checkShellCompletionHealth() {
+  // 1. Verificar se cache existe
+  // 2. Verificar se profile tem completion
+  // 3. Verificar se está usando padrão lento (source <(...))
+  // 4. Auto-gerar cache se necessário
+  // 5. Sugerir instalação se não estiver configurado
+}
+```
+
+### Solução 4: Auto-recovery de Config
+
+```typescript
+// Em doctor-config-flow.ts
+export async function autoFixUnknownConfigKeys(cfg: unknown) {
+  // Remover chaves desconhecidas automaticamente
+  // Preservar backup
+  // Logar alterações
+}
+```
+
+---
+
+## Melhorias Recomendadas
+
+### 1. Sistema de Completion Aprimorado
+
+```typescript
+// Novo: src/cli/completion-enhanced.ts
+export interface CompletionHealth {
+  shell: ShellType;
+  isInstalled: boolean;
+  cacheExists: boolean;
+  isSlowPattern: boolean;
+  canAutoFix: boolean;
+}
+
+export async function ensureCompletionHealthy(): Promise<CompletionHealth> {
+  // 1. Detectar shell
+  // 2. Verificar instalação
+  // 3. Verificar cache
+  // 4. Auto-gerar se necessário
+  // 5. Reportar status
+}
+```
+
+### 2. Doctor Proativo
+
+```typescript
+// Em doctor.ts
+const checks = [
+  checkVersionMismatch,        // Nova
+  checkShellCompletionHealth,  // Nova
+  checkConfigCompatibility,    // Nova
+  checkStateDirectory,         // Nova
+  // ... existing checks
+];
+```
+
+### 3. Mensagens de Erro Melhoradas
+
+**Antes:**
+```
+Invalid config at /Users/pool/.poolbot/poolbot.json:
+- commands: Unrecognized key: "ownerDisplay"
+```
+
+**Depois:**
+```
+⚠️  Configuração incompatível detectada
+
+O campo 'commands.ownerDisplay' foi adicionado na versão 2026.2.26,
+mas você está rodando a versão 2026.2.25.
+
+🔧 Solução: Execute 'poolbot update' ou remova o campo manualmente.
+📖 Docs: https://docs.molt.bot/config/version-mismatch
+```
+
+---
+
+## Checklist de Implementação
+
+### Fase 1: Hotfix Imediato
+- [ ] Atualizar poolbot para 2026.3.9+
+- [ ] Remover arquivo `register.completion.ts`
+- [ ] Criar diretório `~/.poolbot/state/`
+
+### Fase 2: Melhorias no Doctor
+- [ ] Adicionar verificação de versão
+- [ ] Adicionar verificação de completion
+- [ ] Adicionar auto-fix de config
+- [ ] Melhorar mensagens de erro
+
+### Fase 3: UX Aprimorada
+- [ ] Instalação automática de completion
+- [ ] Detecção proativa de problemas
+- [ ] Sugestões contextuais
+
+---
+
+## Comandos para Verificação
+
+```bash
+# Verificar status de completion
+poolbot doctor --non-interactive 2>&1 | grep -A10 "Shell completion"
+
+# Verificar versão
+poolbot --version
+
+# Verificar config
+cat ~/.poolbot/poolbot.json | jq '.commands'
+
+# Verificar diretórios
+ls -la ~/.poolbot/
+ls -la ~/.poolbot/state/completions/ 2>/dev/null || echo "Missing"
+
+# Verificar shell profile
+grep -n "Pool Bot Completion" ~/.zshrc 2>/dev/null || echo "Not installed"
+```
+
+---
+
+## Conclusão
+
+O problema principal é a **versão desatualizada** do PoolBot. O sistema de completion funciona corretamente na versão atual do repositório (2026.3.9), mas o binary instalado (2026.2.25) não reconhece a configuração mais recente.
+
+**Ações recomendadas:**
+1. Atualizar PoolBot imediatamente
+2. Remover arquivo legado `register.completion.ts`
+3. Implementar melhorias no doctor para prevenir problemas futuros
+
+**Prioridade:** 🔴 ALTA - Afeta funcionalidade core (shell completion)