boxsafe 1.0.0

package/docs/NAVIGATE.md

@@ -0,0 +1,186 @@
+# Navigate Module — Documentação Completa
+
+Este documento descreve o funcionamento, a API e as melhores práticas do módulo `core/navigate` do projeto BoxSafe. O objetivo é oferecer uma referência completa, clara e utilizável pelo time e por agentes (LLMs).
+
+## Visão Geral
+
+O módulo `navigate` fornece um conjunto seguro e tipado de operações de sistema de ficheiros confinadas a um `workspace` definido. Ele é projetado para permitir que um agente (LLM) ou código do sistema:
+
+- Liste diretórios com metadados
+- Leia arquivos com limite de tamanho
+- Escreva/atualize arquivos (criando diretórios pais quando solicitado)
+- Crie diretórios (recursivos)
+- Delete arquivos e diretórios (recursivo opcional)
+- Consulte metadados de arquivos/pastas
+
+Características principais:
+
+- Boundary enforcement: todas as operações são validadas para permanecer dentro do `workspace` configurado.
+- Permissões: verificação de leitura/escrita antes de executar ações sensíveis.
+- Limits: leitura de arquivos limitada por tamanho configurável (padrão 10MB).
+- Tipos TS explícitos: `Navigator`, `NavigatorHandler` e resultados estruturados.
+
+## Arquivos Principais
+
+- `navigator.ts` — implementação principal da classe `Navigator`.
+- `handler.ts` — adaptador `NavigatorHandler` para uso por rotas/sgmnt.
+- `utils.ts` — utilitários de segurança e validação de paths (resolução, checagem de permissões, sanitização).
+- `types.ts` — definições de tipos exportadas (resultados, entradas, config).
+- `examples.ts` — exemplos práticos de uso do módulo.
+- `navigate.test.ts` — testes unitários de integração mínima.
+- `NAVIGATEDOC.md` — esta documentação.
+
+## Conceitos e Contratos
+
+Tipos principais (resumo):
+
+- `NavigatorConfig` — { workspace: string; followSymlinks?: boolean; maxFileSize?: number; logger?: Logger }
+- `FileSystemEntry` — { path, name, type: 'file'|'directory', size?, mtime?, readable, writable }
+- `DirectoryListing` — sucesso de listagem: { ok: true, path, entries: FileSystemEntry[], total }
+- `FileReadResult` — leitura: { ok: true, path, content, size, encoding }
+- `FileWriteResult` — escrita: { ok: true, path, size, created }
+- `DirectoryCreateResult` — criação de pasta: { ok: true, path, created }
+- `DeleteResult` — remoção: { ok: true, path, type, deletedAt }
+- `MetadataResult` — metadados: { ok: true, path, stat: { type, size, mtime, isReadable, isWritable } }
+- `OperationError` — falha simples: { ok: false, operation, error }
+
+Observação: as respostas são discriminadas por `ok: true | false`. Use type guards (ou checagem de propriedades) para reduzir o tipo retornado antes de acessar campos específicos.
+
+## Inicialização
+
+Use `createNavigator` quando precisar trabalhar diretamente com a API programática:
+
+```ts
+import { createNavigator } from '@core/navigate';
+
+const nav = createNavigator({
+  workspace: '/home/inky/Development/boxsafe',
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+});
+```
+
+Para integrar com a camada de rotas/segmentos (sgmnt), use `createNavigatorHandler`:
+
+```ts
+import { createNavigatorHandler } from '@core/navigate';
+
+const handler = createNavigatorHandler('/home/inky/Development/boxsafe');
+await handler.execute({ op: 'list', path: 'src' });
+```
+
+## API (métodos do `Navigator`)
+
+- `listDirectory(dirPath?: string) => Promise<DirectoryListing | OperationError>`
+  - Lista conteúdo com `FileSystemEntry[]` e metadados.
+  - Ordena: diretórios primeiro, depois arquivos alfabeticamente.
+
+- `readFile(filePath: string) => Promise<FileReadResult | OperationError>`
+  - Verifica permissões e limite de tamanho antes de ler.
+  - Retorna `encoding: 'utf-8'` e `size` (bytes).
+
+- `writeFile(filePath: string, content: string, options?: { append?: boolean; createDirs?: boolean }) => Promise<FileWriteResult | OperationError>`
+  - Se `createDirs: true`, cria diretórios pai automaticamente.
+  - Suporta `append` para anexar conteúdo.
+
+- `createDirectory(dirPath: string, options?: { recursive?: boolean }) => Promise<DirectoryCreateResult | OperationError>`
+
+- `delete(targetPath: string, options?: { recursive?: boolean }) => Promise<DeleteResult | OperationError>`
+  - Para diretórios, `recursive` padrão é `true` no handler; seja cauteloso.
+
+- `getMetadata(targetPath: string) => Promise<MetadataResult | OperationError>`
+  - Perfeito para decidir se deve ler ou não (tamanho / permissões).
+
+### Observação sobre erros
+
+O `OperationError` contém `operation` e `error` (mensagem curta). Não expõe paths resolvidos para manter erro simples e consistente — o logger interno registra detalhes quando necessário.
+
+## Boas práticas (para humanos e LLMs)
+
+1. Sempre verifique `result.ok` ou use type guards antes de acessar propriedades específicas.
+2. Prefira caminhos relativos ao workspace (`src/main.ts`) em vez de absolutos.
+3. Use `createDirs: true` em `writeFile` quando o destino puder não existir.
+4. Evite ler arquivos muito grandes — use `getMetadata` e respeite `maxFileSize`.
+5. Não confie somente em mensagens do agente — valide operações críticas externamente (p.ex. testes automatizados).
+
+## Exemplos práticos
+
+Listar diretório e ler um arquivo condicionalmente:
+
+```ts
+const list = await nav.listDirectory('src');
+if (list.ok) {
+  for (const e of list.entries) {
+    if (e.type === 'file' && e.size && e.size < 1024 * 1024) {
+      const r = await nav.readFile(e.path);
+      if (r.ok) console.log(r.content.slice(0, 200));
+    }
+  }
+}
+```
+
+Criar estrutura e escrever múltiplos arquivos:
+
+```ts
+await nav.createDirectory('output/generated', { recursive: true });
+await nav.writeFile('output/generated/index.ts', "export * from './types'", { createDirs: true });
+```
+
+Usando o `NavigatorHandler` (útil para integração com sgmnt):
+
+```ts
+const handler = createNavigatorHandler('/home/inky/Development/boxsafe');
+const res = await handler.execute({ op: 'write', path: 'out/result.txt', content: 'ok', writeOptions: { createDirs: true } });
+if (!res.ok) console.error('Handler error', res.error);
+```
+
+## Integração com `sgmnt` (map)
+
+No `core/sgmnt/map.ts` você pode adicionar uma rota/entry que instancie o handler com o workspace do `BS.config.json`:
+
+```ts
+navigate: {
+  handler: async (params?: any) => {
+    const mod = await import('@core/navigate');
+    const handler = mod.createNavigatorHandler(BSConfig.project?.workspace ?? './');
+    return handler.execute(params);
+  },
+  meta: { description: 'File navigation with workspace boundary', implemented: true }
+}
+```
+
+## Segurança e Limitações
+
+- A validação de `workspace` evita directory traversal. Se um path calculado estiver fora do `workspace`, a operação falha com `OperationError`.
+- `followSymlinks` está desligado por padrão; habilite com cautela.
+- O módulo não tenta contornar políticas de OS; ele respeita permissões do usuário que executa o processo.
+
+## Testes e Validação
+
+Executar a suite de testes localmente (ex.: `navigate.test.ts`) é recomendado após mudanças:
+
+```bash
+# rodar apenas o teste do navigate (exemplo usando tsx/ts-node conforme projeto)
+npx tsx core/navigate/navigate.test.ts
+
+# ou rodar verificação TypeScript
+npx tsc --noEmit
+```
+
+## Troubleshooting rápido
+
+- Erro `Access denied` ao ler/escrever: verifique permissões do processo e se o arquivo está dentro do `workspace`.
+- `File size exceeds limit`: aumente `maxFileSize` no `NavigatorConfig` ou use streaming externo.
+- Mensagens de erro genéricas: confira logs do `logger` (padrão `console`) para detalhes adicionais.
+
+## Notas finais
+
+O `navigate` foi projetado para ser simples, seguro e fácil de integrar com agentes LLM. A API é propositalmente pequena e previsível para minimizar erros de interpretação e facilitar validação automática em loops (ex.: `execLoop`).
+
+Se quiser, eu posso:
+
+- Adicionar exemplos de prompts para LLMs que utilizam o handler.
+- Gerar snippets de código para integração em `core/sgmnt/map.ts` automaticamente.
+- Criar um CLI leve para operações manuais de navegação para debug.
+
+----
+Documento gerado automaticamente — revise e peça ajustes.

package/docs/PRIMARY_ACTORS.md

@@ -0,0 +1,78 @@
+# Primary Actors (Atores Primários) - BoxSafe Hexagonal Architecture
+
+## Definição
+**Primary Actors** são os elementos externos que **iniciam ações** no sistema BoxSafe. Eles são o ponto de entrada e controlam o fluxo de execução.
+
+## Primary Actors Identificados
+
+### 1. **CLI (Command Line Interface)**
+- **Descrição**: Interface de linha de comando principal do BoxSafe
+- **Ponto de Entrada**: `main.ts`
+- **Como interage**: Através do `ISystemExecutionPort.executeSegment()`
+- **Exemplo de uso**: `boxsafe run --prompt "criar função X"`
+
+### 2. **IDE Extensions**
+- **Descrição**: Extensões para VS Code, IntelliJ, etc.
+- **Ponto de Entrada**: API do sistema de segmentos
+- **Como interage**: Através do `ISystemExecutionPort.executeSegment()`
+- **Exemplo de uso**: Botão "Run BoxSafe" na IDE
+
+### 3. **Web Interface**
+- **Descrição**: Interface web para uso do BoxSafe
+- **Ponto de Entrada**: Endpoint HTTP/REST
+- **Como interage**: Através do `ISystemExecutionPort.executeSegment()`
+- **Exemplo de uso**: Formulário web com prompt e configurações
+
+### 4. **API Clients**
+- **Descrição**: Clientes programáticos que usam BoxSafe
+- **Ponto de Entrada**: API REST ou GraphQL
+- **Como interage**: Através do `ISystemExecutionPort.executeSegment()`
+- **Exemplo de uso**: `POST /api/v1/execute`
+
+### 5. **Scheduled Jobs/Cron**
+- **Descrição**: Tarefas agendadas que executam BoxSafe
+- **Ponto de Entrada**: Scheduler externo
+- **Como interage**: Através do `ISystemExecutionPort.executeSegment()`
+- **Exemplo de uso**: Job noturno para analisar código
+
+### 6. **CI/CD Pipelines**
+- **Descrição**: Integração com pipelines de CI/CD
+- **Ponto de Entrada**: Hooks do pipeline
+- **Como interage**: Através do `ISystemExecutionPort.executeSegment()`
+- **Exemplo de uso**: Step do GitHub Actions
+
+## Fluxo de Interação
+
+```
+Primary Actor → ISystemExecutionPort → Core Business Logic
+     ↓
+[CLI/IDE/Web] → [executeSegment()] → [Segment Handler]
+     ↓
+Configuration → ISystemConfigurationPort → [loadConfiguration()]
+```
+
+## Características dos Primary Actors
+
+1. **Iniciam a ação**: São eles que começam o processo
+2. **Controlam o fluxo**: Determinam quando e como executar
+3. **Fornecem configuração**: Passam parâmetros e opções
+4. **Recebem resultados**: Obtêm o output da execução
+5. **São externos ao core**: Não fazem parte do domínio do BoxSafe
+
+## Mapeamento para Código Atual
+
+| Primary Actor | Implementação Atual | Port Correspondente |
+|---------------|-------------------|---------------------|
+| CLI | `main.ts` | `ISystemExecutionPort` |
+| IDE Extensions | Futuro | `ISystemExecutionPort` |
+| Web Interface | Futuro | `ISystemExecutionPort` |
+| API Clients | Futuro | `ISystemExecutionPort` |
+| Scheduled Jobs | Futuro | `ISystemExecutionPort` |
+| CI/CD Pipelines | Futuro | `ISystemExecutionPort` |
+
+## Próximos Passos
+
+1. Implementar adapters específicos para cada Primary Actor
+2. Criar pontos de entrada dedicados (CLI, Web, API)
+3. Documentar interfaces para cada tipo de ator
+4. Implementar autenticação e autorização por ator

package/docs/SECONDARY_ACTORS.md

@@ -0,0 +1,174 @@
+# Secondary Actors (Atores Secundários) - BoxSafe Hexagonal Architecture
+
+## Definição
+**Secondary Actors** são os sistemas externos que o BoxSafe **consome** para realizar suas tarefas. Eles fornecem serviços e recursos que o sistema utiliza para funcionar.
+
+## Secondary Actors Identificados
+
+### 1. **AI Model Providers**
+- **Descrição**: Provedores de modelos de linguagem
+- **Implementação Atual**: Google (Gemini), OpenAI, Anthropic, etc.
+- **Port Correspondente**: `IAIModelPort`
+- **Como interage**: Envia prompts e recebe respostas
+- **Exemplos**:
+  - Google Gemini API
+  - OpenAI GPT API
+  - Anthropic Claude API
+  - Azure OpenAI
+
+### 2. **File System**
+- **Descrição**: Sistema de arquivos do hospedeiro
+- **Implementação Atual**: Node.js `fs` module
+- **Port Correspondente**: `IFileSystemPort`
+- **Como interage**: Lê, escreve, lista, deleta arquivos e diretórios
+- **Exemplos**:
+  - Local filesystem
+  - Network filesystems
+  - Cloud storage (S3, Google Drive)
+
+### 3. **Version Control Systems**
+- **Descrição**: Sistemas de controle de versão
+- **Implementação Atual**: Git através de comandos shell
+- **Port Correspondente**: `IVersionControlPort`
+- **Como interage**: Executa comandos git, obtém status, cria commits
+- **Exemplos**:
+  - Git
+  - Mercurial
+  - SVN
+  - GitHub API
+  - GitLab API
+
+### 4. **Command Execution Environment**
+- **Descrição**: Ambiente de execução de comandos do sistema
+- **Implementação Atual**: Node.js `child_process`
+- **Port Correspondente**: `ICommandExecutionPort`
+- **Como interage**: Executa comandos shell, scripts, ferramentas
+- **Exemplos**:
+  - Shell/bash/zsh
+  - PowerShell (Windows)
+  - Docker containers
+  - CI/CD runners
+
+### 5. **Configuration Sources**
+- **Descrição**: Fontes de configuração do sistema
+- **Implementação Atual**: Arquivo JSON, variáveis de ambiente
+- **Port Correspondente**: `ISystemConfigurationPort`
+- **Como interage**: Lê e valida configurações
+- **Exemplos**:
+  - `boxsafe.config.json`
+  - Environment variables
+  - Remote configuration services
+  - Database configuration
+
+### 6. **Logging Systems**
+- **Descrição**: Sistemas de logging e monitoramento
+- **Implementação Atual**: Console, file logging
+- **Port Correspondente**: `LoggerPort`
+- **Como interage**: Registra eventos, erros, métricas
+- **Exemplos**:
+  - Console output
+  - File logging
+  - Elasticsearch
+  - CloudWatch
+  - Datadog
+
+### 7. **Network Services**
+- **Descrição**: Serviços de rede e comunicação
+- **Implementação Atual**: HTTP/HTTPS requests
+- **Port Correspondente**: (Futuro) `INetworkPort`
+- **Como interage**: Faz requisições HTTP, baixa arquivos
+- **Exemplos**:
+  - HTTP/HTTPS clients
+  - FTP clients
+  - WebSocket connections
+  - API gateways
+
+### 8. **Authentication/Authorization Services**
+- **Descrição**: Serviços de autenticação e autorização
+- **Implementação Atual**: Módulo `auth/dasktop`
+- **Port Correspondente**: (Futuro) `IAuthServicePort`
+- **Como interage**: Valida credenciais, gerencia tokens
+- **Exemplos**:
+  - OAuth providers
+  - LDAP/Active Directory
+  - JWT services
+  - Custom auth systems
+
+### 9. **Sandbox/Isolation Systems**
+- **Descrição**: Sistemas de isolamento e sandbox
+- **Implementação Atual**: Configuração Docker
+- **Port Correspondente**: (Futuro) `ISandboxPort`
+- **Como interage**: Cria ambientes isolados para execução
+- **Exemplos**:
+  - Docker containers
+  - VMs
+  - Chroot jails
+  - Cloud sandboxes
+
+## Fluxo de Interação
+
+```
+Core Business Logic → Secondary Port → Secondary Actor
+        ↓                    ↓              ↓
+[BoxSafe Loop] → [IAIModelPort] → [Google Gemini]
+        ↓                    ↓              ↓
+[Navigation] → [IFileSystemPort] → [Local FS]
+        ↓                    ↓              ↓
+[Version Ctrl] → [IVersionControlPort] → [Git]
+```
+
+## Características dos Secondary Actors
+
+1. **São consumidos pelo core**: O BoxSafe inicia a interação
+2. **Fornecem serviços**: Oferecem funcionalidades específicas
+3. **São substituíveis**: Podem ser trocados por alternativas
+4. **Requerem adapters**: Necessitam adaptação para o port
+5. **Têm dependências externas**: Podem falhar independentemente
+
+## Mapeamento para Código Atual
+
+| Secondary Actor | Implementação Atual | Port Correspondente | Status |
+|-----------------|-------------------|---------------------|---------|
+| AI Models | `@ai/label` | `IAIModelPort` | ✅ Implementado |
+| File System | `@core/navigate` | `IFileSystemPort` | ✅ Implementado |
+| Version Control | `@core/loop/git` | `IVersionControlPort` | ✅ Implementado |
+| Command Execution | `@core/loop/cmd` | `ICommandExecutionPort` | ✅ Implementado |
+| Configuration | `@core/config` | `ISystemConfigurationPort` | ✅ Implementado |
+| Logging | `@util/logger` | `LoggerPort` | ✅ Implementado |
+| Network | Manual HTTP | `INetworkPort` | 🔄 Planejado |
+| Authentication | `@core/auth` | `IAuthServicePort` | 🔄 Planejado |
+| Sandbox | Config only | `ISandboxPort` | 🔄 Planejado |
+
+## Estratégia de Adapters
+
+Cada Secondary Actor requer um adapter específico:
+
+```typescript
+// Exemplo: Adapter para Google Gemini
+class GoogleGeminiAdapter implements IAIModelPort {
+  async sendPrompt(prompt: string): Promise<any> {
+    // Implementação específica da API do Google
+  }
+  
+  async configureModel(config: ModelConfig): Promise<void> {
+    // Configuração específica
+  }
+}
+
+// Exemplo: Adapter para FileSystem
+class NodeFileSystemAdapter implements IFileSystemPort {
+  async listDirectory(path: string): Promise<any> {
+    // Implementação usando Node.js fs
+  }
+  
+  // ... outros métodos
+}
+```
+
+## Benefícios Desta Abordagem
+
+1. **Desacoplamento**: Core não depende de implementações específicas
+2. **Testabilidade**: Facilita mocks e testes unitários
+3. **Flexibilidade**: Permite trocar provedores facilmente
+4. **Manutenibilidade**: Isola mudanças externas
+5. **Extensibilidade**: Facilita adição de novos provedores

package/docs/VERSIONING.md

@@ -0,0 +1,17 @@
+# Git Versioning Module
+
+Purpose
+- Lightweight helper for staging, committing and optionally pushing changes to Git/GitHub.
+
+Behavior
+- Finds repository root (searches up from working directory)
+- Stages all changes and commits with a sensible default message
+- Optionally creates `BOXSAFE_VERSION_NOTES.md` describing the commit
+- Attempts to push to `origin` and will try a token from keyring (`gh-token`) or `PASSWORD_GIT` env var if push fails due to auth
+
+How to use
+- Programmatic: import `runVersionControl` from `@core/loop/git` and call with options `{ autoPush?: boolean, generateNotes?: boolean, commitMessage?: string }`.
+- CLI / manual: this module is intended to be invoked by the agent runtime.
+
+Security
+- Token injection only used as a fallback for a single push attempt. Prefer using native credential helpers or keyring (see `core/auth/dasktop/cred`).