boxsafe 1.0.0

package/docs/ARQUITETURA_CORRECAO.md

@@ -0,0 +1,121 @@
+# Correção da Arquitetura Hexagonal - Estrutura Correta
+
+## Erro Conceitual Corrigido
+
+Você estava **ABSOLUTAMENTE CORRETO**! Cometi um erro fundamental ao colocar adapters dentro do core.
+
+## Estrutura ERRADA (que eu criei inicialmente):
+
+```
+core/
+├── ports/          ✓ Correto
+├── adapters/       ✗ ERRADO - adapters ficam FORA do core
+└── domain/         ✓ Correto
+```
+
+## Estrutura CORRETA (arquitetura hexagonal propriamente dita):
+
+```
+src/
+├── core/                    ← Apenas domínio puro + interfaces
+│   ├── domain/             ← Lógica de negócio do BoxSafe
+│   └── ports/              ← Interfaces/Contratos (sem implementação)
+├── adapters/               ← FORA do core - implementações concretas
+│   ├── primary/            ← Adaptam Primary Actors (CLI, Web, IDE)
+│   │   └── cli-adapter.ts
+│   └── secondary/         ← Adaptam Secondary Actors (FS, AI, Git)
+│       ├── system/
+│       │   └── configuration.ts
+│       └── filesystem/
+│           └── node-filesystem.ts
+└── infrastructure/         ← Configuração, setup, etc.
+```
+
+## Por Que Adapters Ficam FORA do Core?
+
+### 1. **Princípio da Inversão de Dependência**
+```typescript
+// ERRADO - Core depende de implementações
+core/
+├── adapters/ ← Implementações concretas DENTRO do core
+└── ports/
+
+// CORRETO - Core depende apenas de abstrações
+core/
+└── ports/ ← Apenas interfaces
+
+adapters/ ← Implementações concretas FORA do core
+```
+
+### 2. **Core Deve Ser Puro**
+O core contém apenas:
+- **Regras de negócio** (domain logic)
+- **Interfaces** (ports)
+- **Entidades** do domínio
+
+**NUNCA** contém:
+- Implementações concretas
+- Dependências externas
+- Detalhes de infraestrutura
+
+### 3. **Adapters São Infraestrutura**
+Adapters são código de **glue** que conecta:
+- **Primary Actors** → **Core** (Primary Adapters)
+- **Core** → **Secondary Actors** (Secondary Adapters)
+
+## Fluxo Correto na Arquitetura Hexagonal
+
+```
+┌─────────────────────────────────────┐
+│           Primary Actors             │
+│         (CLI, Web, IDE)            │
+├─────────────────────────────────────┤
+│         PRIMARY ADAPTERS            │  ← FORA do core
+│    ┌─────────────────────────┐      │
+│    │    CLIAdapter          │      │
+│    │  implements ISystem   │      │
+│    │  ExecutionPort         │      │
+│    └─────────────────────────┘      │
+├─────────────────────────────────────┤
+│              CORE                  │  ← Puro, apenas interfaces
+│  ┌─────────────────────────────────┐ │
+│  │           PORTS                │ │
+│  │  ISystemExecutionPort         │ │
+│  │  IFileSystemPort              │ │
+│  │  IAIModelPort                │ │
+│  └─────────────────────────────────┘ │
+│  ┌─────────────────────────────────┐ │
+│  │         DOMAIN LOGIC           │ │
+│  │    (regras do BoxSafe)        │ │
+│  └─────────────────────────────────┘ │
+├─────────────────────────────────────┤
+│        SECONDARY ADAPTERS          │  ← FORA do core
+│  ┌─────────┬─────────────────────┐ │
+│  │ FileSystem│   AI Model         │ │
+│  │ Adapter  │   Adapter          │ │
+│  └─────────┴─────────────────────┘ │
+├─────────────────────────────────────┤
+│         Secondary Actors             │
+│    (FileSystem, AI, Git, etc.)     │
+└─────────────────────────────────────┘
+```
+
+## Benefícios da Estrutura Correta
+
+1. **Core Isolado**: Pode ser testado sem dependências externas
+2. **Flexibilidade**: Fácil trocar adapters sem afetar o core
+3. **Manutenibilidade**: Mudanças na infra não afetam o domínio
+4. **Reusabilidade**: Core pode ser usado com diferentes tecnologias
+
+## Ação Corretiva Executada
+
+1. ✅ Movido `core/adapters/` → `adapters/`
+2. ✅ Separado em `adapters/primary/` e `adapters/secondary/`
+3. ✅ Mantido `core/ports/` com apenas interfaces
+4. ✅ Criado `adapters/index.ts` para export centralizado
+
+## Conclusão
+
+Sua observação estava **100% correta**. A arquitetura hexagonal exige que adapters fiquem **fora do core** para manter o domínio puro e desacoplado de detalhes de infraestrutura.
+
+Obrigado pela correção! Isso melhora significativamente a qualidade da arquitetura.

package/docs/CONVENTIONS.md

@@ -0,0 +1,30 @@
+# Segments (skills) conventions
+
+## Folder layout
+
+Each segment must live in its own folder:
+
+- `core/sgmnt/<segment>/index.ts`
+
+`index.ts` must export a factory function:
+
+- `create<SegmentName>Segment(BSConfig)`
+
+The factory returns an object with the same shape used by `core/sgmnt/map.ts`:
+
+- `handler: (args?: any) => Promise<any>`
+- `meta: { description: string; implemented: boolean; config?: any }`
+
+## map.ts responsibilities
+
+`core/sgmnt/map.ts` is the composer:
+
+- loads config (`loadBoxSafeConfig`)
+- instantiates each segment via its factory
+- exposes `{ routes, runSegment, BSConfig }`
+
+## Adding a new segment
+
+1. Create folder `core/sgmnt/<segment>/`
+2. Implement `index.ts` exporting `create<SegmentName>Segment`
+3. Register it inside `core/sgmnt/map.ts` under `routes`.

package/docs/CRED.md

@@ -0,0 +1,112 @@
+# Credenciais Linux (credLinux)
+
+Módulo para gerenciar credenciais usando o **secret-tool** do Linux (keyring nativo).
+
+## Requisitos
+
+- Linux com `secret-tool` instalado (já vem na maioria das distros)
+- Funciona em qualquer desktop environment (GNOME, KDE, XFCE, etc.)
+
+## Importação
+
+```typescript
+import { saveCredLinux, getCredLinux, deleteCredLinux } from '@memo/desktop/pass';
+```
+
+## Funções
+
+### `saveCredLinux()`
+
+Salva uma credencial no keyring do sistema.
+
+```typescript
+const success = await saveCredLinux({
+  password: 'minha-senha-secreta',
+  label: 'GitHub Token',
+  account: 'gh-token',
+  service: 'meu-app' // opcional, default: 'box-safe'
+});
+
+// Retorna: true (sucesso) | false (erro)
+```
+
+### `getCredLinux()`
+
+Recupera uma credencial salva.
+
+```typescript
+const token = await getCredLinux({
+  account: 'gh-token',
+  service: 'meu-app' // opcional, default: 'box-safe'
+});
+
+// Retorna: string (senha) | null (não encontrada)
+```
+
+### `deleteCredLinux()`
+
+Remove uma credencial do keyring.
+
+```typescript
+const deleted = await deleteCredLinux({
+  account: 'gh-token',
+  service: 'meu-app' // opcional, default: 'box-safe'
+});
+
+// Retorna: true (sucesso) | false (erro)
+```
+
+## Exemplo Completo
+
+```typescript
+// Salvar API key
+await saveCredLinux({
+  password: 'sk-xxxxxxxxxxxxx',
+  label: 'OpenAI API Key',
+  account: 'openai-key'
+});
+
+// Usar depois
+const apiKey = await getCredLinux({ account: 'openai-key' });
+if (apiKey) {
+  console.log('Key encontrada:', apiKey);
+}
+
+// Limpar quando não precisar mais
+await deleteCredLinux({ account: 'openai-key' });
+```
+
+## Parâmetros
+
+### CredentialArgs (save)
+- `password`: senha/token a salvar
+- `label`: descrição amigável (aparece na GUI do keyring)
+- `account`: identificador único da credencial
+- `service`: (opcional) nome do app/serviço (default: `box-safe`)
+
+### LookupArgs (get/delete)
+- `account`: identificador da credencial
+- `service`: (opcional) nome do app/serviço (default: `box-safe`)
+
+## Onde ficam salvos?
+
+As credenciais são criptografadas e salvas em:
+```
+~/.local/share/keyrings/
+```
+
+Você pode visualizar usando `seahorse` (GNOME) ou a GUI do seu keyring.
+
+## Logs
+
+O módulo só loga erros no console. Se algo falhar:
+- `saveCredLinux`: retorna `false`
+- `getCredLinux`: retorna `null`
+- `deleteCredLinux`: retorna `false`
+
+Tratamento de erro fica por sua conta.
+
+
+## WINDOWS
+for windows we use keytar
+