@justmpm/comunicate 0.1.0

package/CLAUDE.md

@@ -0,0 +1,518 @@
+# @justmpm/comunicate - Guia Completo
+
+Sistema de Comunicação Entre Agentes usando arquivos JSON locais (File-Based Architecture) otimizado para Windows.
+
+---
+
+## 📋 Índice
+
+1. [Visão Geral](#visão-geral)
+2. [Arquitetura](#arquitetura)
+3. [Instalação](#instalação)
+4. [Configuração](#configuração)
+5. [Tools MCP](#tools-mcp)
+6. [Fluxos de Trabalho](#fluxos-de-trabalho)
+7. [CLI](#cli)
+8. [Exemplos](#exemplos)
+9. [Segurança](#segurança)
+10. [Troubleshooting](#troubleshooting)
+
+---
+
+## Visão Geral
+
+O **@justmpm/comunicate** é um servidor MCP (Model Context Protocol) que permite comunicação entre múltiplos agentes através de arquivos JSON locais.
+
+### Por que File-Based?
+
+- ✅ **Zero dependências** - Sem banco de dados ou servidor externo
+- ✅ **Portátil** - Viaja com o projeto (controle de versão)
+- ✅ **Debug fácil** - Arquivos JSON human-readable
+- ✅ **No-lock** - Cada agente escreve apenas no seu próprio arquivo
+- ✅ **Otimizado Windows** - File system nativo
+
+### Conceitos Fundamentais
+
+| Conceito | Descrição |
+|----------|-----------|
+| **Agente** | Entidade que pode enviar/receber mensagens |
+| **Inbox** | Caixa de entrada exclusiva de cada agente |
+| **Domínio** | Diretórios que um agente pode editar naturalmente |
+| **Claim** | Reserva temporária de arquivo fora do domínio |
+| **Heartbeat** | Sinal de vida do agente |
+
+---
+
+## Arquitetura
+
+```
+.comunicate/
+├── registry/
+│   ├── agents.json       # Registro de agentes (com heartbeat)
+│   ├── tasks.json        # Tarefas
+│   └── claims.json       # Arquivos reservados (com sequence)
+├── messages/
+│   ├── inbox-*.json      # Caixas de entrada
+│   └── archive/          # Mensagens arquivadas (gzip)
+└── context/
+    ├── api-contracts.json
+    ├── decisions.json
+    └── progress.json
+```
+
+### Metáfora
+
+> É como uma sala de equipe onde cada pessoa tem seu próprio quadro de avisos. Você só escreve no seu quadro, mas pode ler os dos outros. Se precisar escrever no quadro de outra pessoa, você precisa pedir permissão (claim).
+
+---
+
+## Instalação
+
+### Pré-requisitos
+
+- Node.js 18+
+- Windows (otimizado para este SO)
+
+### Passo a Passo
+
+```powershell
+# 1. Clone ou copie o projeto
+cd comunicate-ai
+
+# 2. Instale dependências
+npm install
+
+# 3. Compile TypeScript
+npm run build
+
+# 4. Execute setup automatizado
+powershell -ExecutionPolicy Bypass -File setup.ps1
+```
+
+O script `setup.ps1` irá:
+- Criar estrutura de pastas
+- Gerar arquivos JSON iniciais
+- Criar token de admin
+- Mostrar configuração para Claude
+
+---
+
+## Configuração
+
+### 1. Configurar Token de Admin
+
+```powershell
+# Temporário (sessão atual)
+$env:COMUNICATE_ADMIN_TOKEN="seu-token-aqui"
+
+# Permanente (Windows)
+[Environment]::SetEnvironmentVariable("COMUNICATE_ADMIN_TOKEN", "seu-token-aqui", "User")
+```
+
+### 2. Configurar Claude Desktop
+
+Edite `%APPDATA%\Claude\settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "@justmpm/comunicate": {
+      "command": "node",
+      "args": [
+        "C:/caminho/completo/para/dist/mcp-server.js"
+      ],
+      "env": {
+        "COMUNICATE_ADMIN_TOKEN": "seu-token-aqui"
+      }
+    }
+  }
+}
+```
+
+> ⚠️ **IMPORTANTE**: Use barras normais (`/`) ou duplas barras invertidas (`\\`) nos caminhos Windows.
+
+### 3. Reinicie o Claude Desktop
+
+Após configurar, feche e reabra o Claude Desktop.
+
+---
+
+## Tools MCP
+
+### Comunicação
+
+#### `send_agent_message`
+Envia mensagem para outro agente.
+
+```json
+{
+  "token": "token-do-agente",
+  "recipientId": "frontend",
+  "message": "API pronta!",
+  "type": "task_update",
+  "priority": "high"
+}
+```
+
+**Tipos:** `text`, `assistance_request`, `task_update`, `notification`  
+**Prioridades:** `low`, `normal`, `high`, `urgent`
+
+---
+
+#### `get_agent_messages`
+Lê mensagens da inbox.
+
+```json
+{
+  "token": "token-do-agente",
+  "includeRead": false,
+  "markAsRead": true,
+  "limit": 10
+}
+```
+
+---
+
+#### `get_unread_count`
+Retorna número de mensagens não lidas.
+
+```json
+{
+  "token": "token-do-agente"
+}
+```
+
+---
+
+### Claims (Reserva de Arquivos)
+
+#### `claim_file`
+Reserva arquivo fora do domínio para edição.
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/types/api.ts",
+  "durationMinutes": 30,
+  "reason": "Adicionando tipos da API"
+}
+```
+
+> O claim expira automaticamente após o tempo definido.
+
+---
+
+#### `renew_claim`
+Renova um claim prestes a expirar (só funciona se faltarem < 5 min).
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/types/api.ts",
+  "additionalMinutes": 15
+}
+```
+
+---
+
+#### `release_file`
+Libera um arquivo reservado antes do tempo.
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/types/api.ts"
+}
+```
+
+---
+
+#### `can_edit_file`
+Verifica se pode editar um arquivo (domínio ou claim ativo).
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/components/Button.tsx"
+}
+```
+
+---
+
+### Administração (requer token de admin)
+
+#### `create_agent`
+Cria novo agente.
+
+```json
+{
+  "adminToken": "token-admin",
+  "agentId": "backend",
+  "capabilities": ["api", "database", "auth"],
+  "domains": ["src/api", "src/models"]
+}
+```
+
+**Regras para agentId:**
+- Apenas letras minúsculas, números e hífens
+- Exemplos válidos: `backend`, `frontend-v2`, `test-runner`
+
+---
+
+#### `list_agents`
+Lista todos os agentes registrados.
+
+```json
+{
+  "adminToken": "token-admin"
+}
+```
+
+---
+
+#### `get_inactive_agents`
+Lista agentes sem heartbeat (possivelmente "mortos").
+
+```json
+{
+  "adminToken": "token-admin",
+  "timeoutMinutes": 5
+}
+```
+
+---
+
+## Fluxos de Trabalho
+
+### Fluxo 1: Criar Agente e Enviar Mensagem
+
+```
+1. Admin executa: create_agent
+   → Recebe token único do agente
+   
+2. Agente salva seu token
+
+3. Agente A executa: send_agent_message
+   → Mensagem vai para inbox-B.json
+   
+4. Agente B executa: get_agent_messages
+   → Lê e processa mensagens
+```
+
+### Fluxo 2: Coordenação com Claims
+
+```
+Backend (domínio: src/models):
+  ✅ Pode editar: src/models/user.ts
+  ❌ Não pode: src/components/Button.tsx
+
+Frontend (domínio: src/components):
+  ✅ Pode editar: src/components/Button.tsx
+  ❌ Não pode: src/models/user.ts
+
+Quando Frontend precisa editar src/types/api.ts:
+  1. Executa: can_edit_file → false
+  2. Executa: claim_file → success
+  3. Executa: can_edit_file → true
+  4. [edita o arquivo]
+  5. Executa: release_file (ou espera expirar)
+```
+
+### Fluxo 3: Monitoramento de Saúde
+
+```
+Cada agente deve:
+  - Chamar qualquer tool periodicamente (atualiza lastSeen)
+  - Ou chamar updateAgentHeartbeat() via código
+
+Admin pode executar:
+  get_inactive_agents → lista agentes "zumbis"
+```
+
+---
+
+## CLI
+
+Além das tools MCP, existe uma CLI para administração:
+
+```bash
+# Listar agentes
+npm run cli -- list-agents
+
+# Criar agente
+npm run cli -- create-agent backend
+
+# Listar claims
+npm run cli -- list-claims
+
+# Verificar saúde
+npm run cli -- check-health 5
+
+# Gerar token aleatório
+npm run cli -- generate-token
+```
+
+---
+
+## Exemplos
+
+### Exemplo 1: Backend notifica Frontend
+
+```typescript
+// Backend envia atualização
+const result = sendMessage(
+  BACKEND_TOKEN,
+  'frontend',
+  'API /users pronta! Contrato: { id, name, email }',
+  { type: 'task_update', priority: 'normal' }
+);
+```
+
+### Exemplo 2: Frontend reserva arquivo
+
+```typescript
+// Verifica se pode editar
+const check = canEditFile('frontend', 'src/types/api.ts');
+if (!check.allowed) {
+  // Reserva arquivo
+  const claim = claimFile(
+    'frontend',
+    'src/types/api.ts',
+    30,
+    'Adicionando tipos'
+  );
+  
+  if (claim.success) {
+    // Agora pode editar
+    editFile('src/types/api.ts', ...);
+    
+    // Libera quando terminar
+    releaseFile('frontend', 'src/types/api.ts');
+  }
+}
+```
+
+### Exemplo 3: Notificações em tempo real
+
+```typescript
+import { startNotificationListener } from './comunicate/core/notifications';
+
+const listener = startNotificationListener('frontend', {
+  onMessage: (msg) => {
+    console.log(`Nova mensagem de ${msg.senderId}: ${msg.content}`);
+  }
+});
+
+// ... quando quiser parar:
+listener.stop();
+```
+
+---
+
+## Segurança
+
+### Timing-Safe Comparison
+
+Todos os tokens são comparados usando `crypto.timingSafeEqual()` para prevenir timing attacks.
+
+### Token de Admin
+
+- Armazene em variável de ambiente `COMUNICATE_ADMIN_TOKEN`
+- Nunca commite tokens em repositório
+- Use tokens longos e aleatórios (32+ caracteres hex)
+
+### Claims
+
+- Claims expiram automaticamente
+- Só um agente pode ter claim de um arquivo por vez
+- Sequence number previne race conditions
+
+### Domínios
+
+- Defina domínios restritos ao criar agente
+- Agente só edita arquivos dentro de seus domínios sem claim
+
+---
+
+## Troubleshooting
+
+### "Token inválido"
+
+- Verifique se o token está completo (32 caracteres hex)
+- Confirme que o agente está ativo (`list_agents`)
+- Verifique se há espaços extras
+
+### "File claimed by X"
+
+- Outro agente já reservou o arquivo
+- Espere expirar ou peça para liberar
+- Use `get_all_claims` (admin) para verificar
+
+### Mensagens não aparecem
+
+- Verifique se está usando `includeRead: true`
+- Confirme o `recipientId` no envio
+- Verifique o arquivo inbox-*.json manualmente
+
+### File watcher não funciona
+
+- O sistema tem fallback automático para polling
+- No Windows, polling é mais confiável que file watcher
+- Considere usar `startPolling()` explicitamente
+
+### Permissão negada ao escrever JSON
+
+- Verifique permissões da pasta `.comunicate/`
+- Execute como administrador se necessário
+- Verifique se outro processo está usando os arquivos
+
+---
+
+## Dicas
+
+1. **Organize domínios por responsabilidade**
+   - `backend`: `src/api`, `src/models`
+   - `frontend`: `src/components`, `src/hooks`
+   - `shared`: `src/types`, `src/utils` (use claims)
+
+2. **Renove claims antes de expirar**
+   - Se uma tarefa demorar mais que o previsto
+   - Renove quando faltarem < 5 minutos
+
+3. **Use prioridades adequadamente**
+   - `urgent`: Bugs críticos, system down
+   - `high`: Features importantes, deadlines
+   - `normal`: Comunicação rotineira
+   - `low`: Informações, updates
+
+4. **Limpe mensagens lidas periodicamente**
+   - Use `clear_read_messages` para manter inbox limpa
+   - Mensagens antigas são arquivadas automaticamente
+
+---
+
+## Referência Rápida
+
+### Criar Agente
+```json
+{"adminToken": "...", "agentId": "backend", "capabilities": ["api"], "domains": ["src/api"]}
+```
+
+### Enviar Mensagem
+```json
+{"token": "...", "recipientId": "frontend", "message": "...", "type": "task_update", "priority": "normal"}
+```
+
+### Reservar Arquivo
+```json
+{"token": "...", "filePath": "src/types/api.ts", "durationMinutes": 30, "reason": "..."}
+```
+
+### Ler Mensagens
+```json
+{"token": "...", "includeRead": false, "markAsRead": true, "limit": 10}
+```
+
+---
+
+**Versão 0.1.0** | Arquitetura File-Based | Otimizado para Windows

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @justmpm/comunicate Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @justmpm/comunicate
+
+Sistema de Comunicação Entre Agentes usando arquivos JSON locais (File-Based Architecture).
+
+## 🎯 Visão Geral
+
+O **@justmpm/comunicate** é um servidor MCP (Model Context Protocol) que permite comunicação entre múltiplos agentes através de arquivos JSON locais, eliminando a necessidade de banco de dados ou servidor dedicado.
+
+**Conceitos Fundamentais:**
+- **Pasta Local**: Tudo acontece dentro de `./.comunicate/` no projeto
+- **JSON-First**: Dados persistidos em arquivos JSON human-readable
+- **No-Lock**: Cada agente escreve apenas no seu próprio inbox
+- **Domínios Separados**: Cada agente edita arquivos em diretórios diferentes
+- **Claims**: Sistema de reserva para arquivos compartilhados
+
+## 📁 Estrutura
+
+```
+.comunicate/
+├── registry/
+│   ├── agents.json       # Registro de agentes
+│   ├── tasks.json        # Tarefas
+│   └── claims.json       # Arquivos reservados
+├── messages/
+│   ├── inbox-*.json      # Caixas de entrada
+│   └── archive/          # Mensagens arquivadas (gzip)
+└── context/
+    ├── api-contracts.json
+    ├── decisions.json
+    └── progress.json
+```
+
+## 🚀 Instalação
+
+### 1. Instalar dependências
+
+```bash
+npm install
+```
+
+### 2. Compilar TypeScript
+
+```bash
+npm run build
+```
+
+### 3. Configurar variável de ambiente
+
+```bash
+# Windows PowerShell
+$env:COMUNICATE_ADMIN_TOKEN="seu-token-admin-seguro-aqui"
+
+# Windows CMD
+set COMUNICATE_ADMIN_TOKEN=seu-token-admin-seguro-aqui
+```
+
+### 4. Configurar no Claude Desktop (Claude Settings)
+
+Edite `%APPDATA%\Claude\settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "@justmpm/comunicate": {
+      "command": "node",
+      "args": [
+        "C:/caminho/completo/para/dist/mcp-server.js"
+      ],
+      "env": {
+        "COMUNICATE_ADMIN_TOKEN": "seu-token-admin-seguro-aqui"
+      }
+    }
+  }
+}
+```
+
+## 🛠️ Tools Disponíveis
+
+### Comunicação
+
+| Tool | Descrição |
+|------|-----------|
+| `send_agent_message` | Envia mensagem para outro agente |
+| `get_agent_messages` | Lê mensagens da inbox |
+| `get_unread_count` | Conta mensagens não lidas |
+| `delete_message` | Deleta mensagem específica |
+| `clear_read_messages` | Limpa mensagens lidas |
+
+### Claims (Reserva de Arquivos)
+
+| Tool | Descrição |
+|------|-----------|
+| `claim_file` | Reserva arquivo para edição |
+| `renew_claim` | Renova claim prestes a expirar |
+| `release_file` | Libera arquivo reservado |
+| `can_edit_file` | Verifica permissão de edição |
+| `get_agent_claims` | Lista seus claims ativos |
+| `get_all_claims` | Lista todos claims (admin) |
+
+### Administração
+
+| Tool | Descrição |
+|------|-----------|
+| `create_agent` | Cria novo agente |
+| `list_agents` | Lista agentes registrados |
+| `get_inactive_agents` | Lista agentes inativos |
+
+## 📖 Exemplos de Uso
+
+### Criar um agente (admin)
+
+```json
+{
+  "adminToken": "seu-token-admin",
+  "agentId": "backend",
+  "capabilities": ["api", "database", "auth"],
+  "domains": ["src/api", "src/models"]
+}
+```
+
+### Enviar mensagem
+
+```json
+{
+  "token": "token-do-agente",
+  "recipientId": "frontend",
+  "message": "API pronta!",
+  "type": "task_update",
+  "priority": "high"
+}
+```
+
+### Reservar arquivo
+
+```json
+{
+  "token": "token-do-agente",
+  "filePath": "src/types/api.ts",
+  "durationMinutes": 30,
+  "reason": "Adicionando tipos"
+}
+```
+
+## 🔒 Segurança
+
+- **Timing-Safe Token Comparison**: Proteção contra timing attacks
+- **Retry com Backoff**: Escrita atômica com retry automático
+- **Claims Auto-Limpo**: Expirados são removidos automaticamente
+- **Sequence em Claims**: Prevenção de race conditions
+
+## 🖥️ Otimizado para Windows
+
+- File watcher com fallback para polling
+- Caminhos normalizados para Windows
+- Suporte nativo ao filesystem Windows
+
+## 📝 Licença
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * CLI para Administração do @justmpm/comunicate
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;GAEG"}