boxsafe 1.0.0

package/core/loop/waterfall.ts

@@ -0,0 +1,404 @@
+import { readFile } from "node:fs/promises";
+import { Logger } from '@core/util/logger';
+
+const logger = Logger.createModuleLogger('Waterfall');
+
+export interface ExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface WaterfallContext {
+  exec: ExecResult;
+  artifacts?: {
+    outputFile?: string;
+  };
+}
+
+export interface WaterfallFail {
+  ok: false;
+  layer: string;
+  reason: string;
+  details?: string;
+  score?: number;
+  breakdown?: ScoreBreakdown;
+}
+
+export interface WaterfallSuccess {
+  ok: true;
+  score: number;
+  breakdown: ScoreBreakdown;
+}
+
+export type WaterfallResult = WaterfallFail | WaterfallSuccess;
+
+export interface ScoreBreakdown {
+  exitCode: CheckResult;
+  stderr: CheckResult;
+  outputContract: CheckResult;
+  artifacts: CheckResult;
+  totalScore: number;
+  maxScore: number;
+  percentage: number;
+}
+
+export interface CheckResult {
+  passed: boolean;
+  points: number;
+  maxPoints: number;
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  message?: string;
+}
+
+// Scoring system configuration
+const SCORING_CONFIG = {
+  PASSING_THRESHOLD: 70, // Minimum score to pass (0-100)
+  
+  WEIGHTS: {
+    exitCode: 40,
+    stderr: 20,
+    outputContract: 30,
+    artifacts: 10,
+  },
+  
+  STDERR: {
+    CRITICAL_PATTERNS: [
+      /^fatal error/im,
+      /^error:.*failed/im,
+      /segmentation fault/i,
+      /core dumped/i,
+      /unhandled exception/i,
+      /^traceback \(most recent call last\)/im,
+    ],
+    
+    WARNING_PATTERNS: [
+      /warning:/i,
+      /deprecated/i,
+      /error rate/i,
+      /exception.*registered/i,
+    ],
+    
+    WARNING_PENALTY: 50, // Penalty percentage for warnings
+  },
+  
+  OUTPUT_CONTRACT: {
+    PARTIAL_CREDIT: true,
+    PARTIAL_THRESHOLD: 50, // Minimum percentage of contracts to earn partial credit
+  },
+};
+
+/**
+ * Executes cascading validations with scoring system.
+ * Critical failures result in immediate rejection.
+ * Minor failures are accumulated to calculate final score.
+ */
+export async function waterfall(
+  ctx: WaterfallContext
+): Promise<WaterfallResult> {
+  logger.info(`Starting evaluation system`);
+  
+  const breakdown: ScoreBreakdown = {
+    exitCode: { passed: false, points: 0, maxPoints: 0, severity: 'critical' },
+    stderr: { passed: false, points: 0, maxPoints: 0, severity: 'high' },
+    outputContract: { passed: false, points: 0, maxPoints: 0, severity: 'high' },
+    artifacts: { passed: false, points: 0, maxPoints: 0, severity: 'medium' },
+    totalScore: 0,
+    maxScore: 100,
+    percentage: 0,
+  };
+
+  // Check exit code (critical - auto-fails if non-zero)
+  breakdown.exitCode = checkExitCode(ctx);
+  
+  if (!breakdown.exitCode.passed && breakdown.exitCode.severity === 'critical') {
+    logger.error(`FAILED: Non-zero exit code (critical)`);
+    return {
+      ok: false,
+      layer: 'exit-code',
+      reason: breakdown.exitCode.message || 'Process exited with non-zero code',
+      details: `exitCode=${ctx.exec.exitCode}`,
+      score: 0,
+      breakdown,
+    };
+  }
+
+  // Check stderr (can be critical or partial)
+  breakdown.stderr = checkStderr(ctx);
+  
+  if (!breakdown.stderr.passed && breakdown.stderr.severity === 'critical') {
+    logger.error(`FAILED: Critical error in stderr`);
+    return {
+      ok: false,
+      layer: 'stderr',
+      reason: breakdown.stderr.message || 'Critical error detected',
+      details: ctx.exec.stderr.slice(0, 500),
+      score: calculateTotalScore(breakdown),
+      breakdown,
+    };
+  }
+
+  // Check output contract (non-critical)
+  breakdown.outputContract = await checkOutputContract(ctx);
+
+  // Check artifacts (non-critical)
+  breakdown.artifacts = await checkArtifacts(ctx);
+
+  // Calculate final score
+  breakdown.totalScore = calculateTotalScore(breakdown);
+  breakdown.percentage = breakdown.totalScore;
+
+  logger.info(`Final Score: ${breakdown.totalScore.toFixed(1)}/100`);
+  logScoreBreakdown(breakdown);
+
+  if (breakdown.totalScore >= SCORING_CONFIG.PASSING_THRESHOLD) {
+    logger.info(`PASSED (score: ${breakdown.totalScore.toFixed(1)} >= ${SCORING_CONFIG.PASSING_THRESHOLD})`);
+    return {
+      ok: true,
+      score: breakdown.totalScore,
+      breakdown,
+    };
+  } else {
+    logger.warn(`FAILED (score: ${breakdown.totalScore.toFixed(1)} < ${SCORING_CONFIG.PASSING_THRESHOLD})`);
+    return {
+      ok: false,
+      layer: 'score-threshold',
+      reason: 'Insufficient score for approval',
+      details: `Obtained: ${breakdown.totalScore.toFixed(1)}, Required: ${SCORING_CONFIG.PASSING_THRESHOLD}`,
+      score: breakdown.totalScore,
+      breakdown,
+    };
+  }
+}
+
+function checkExitCode(ctx: WaterfallContext): CheckResult {
+  const maxPoints = SCORING_CONFIG.WEIGHTS.exitCode;
+  
+  if (ctx.exec.exitCode === 0) {
+    return {
+      passed: true,
+      points: maxPoints,
+      maxPoints,
+      severity: 'critical',
+      message: 'Exit code OK',
+    };
+  }
+
+  return {
+    passed: false,
+    points: 0,
+    maxPoints,
+    severity: 'critical',
+    message: `Process exited with code ${ctx.exec.exitCode}`,
+  };
+}
+
+function checkStderr(ctx: WaterfallContext): CheckResult {
+  const maxPoints = SCORING_CONFIG.WEIGHTS.stderr;
+  const stderr = ctx.exec.stderr || '';
+
+  // Check for critical patterns first
+  for (const pattern of SCORING_CONFIG.STDERR.CRITICAL_PATTERNS) {
+    if (pattern.test(stderr)) {
+      logger.error(`Critical error detected: ${pattern}`);
+      return {
+        passed: false,
+        points: 0,
+        maxPoints,
+        severity: 'critical',
+        message: `Critical error pattern matched: ${pattern}`,
+      };
+    }
+  }
+
+  // Check for warnings (non-critical, but deduct points)
+  let warningCount = 0;
+  for (const pattern of SCORING_CONFIG.STDERR.WARNING_PATTERNS) {
+    if (pattern.test(stderr)) {
+      warningCount++;
+    }
+  }
+
+  if (warningCount > 0) {
+    const penalty = SCORING_CONFIG.STDERR.WARNING_PENALTY / 100;
+    const points = maxPoints * (1 - penalty);
+    logger.warn(`${warningCount} warning(s) in stderr - ${SCORING_CONFIG.STDERR.WARNING_PENALTY}% penalty`);
+    return {
+      passed: true,
+      points,
+      maxPoints,
+      severity: 'medium',
+      message: `${warningCount} warning(s) detected`,
+    };
+  }
+
+  return {
+    passed: true,
+    points: maxPoints,
+    maxPoints,
+    severity: 'high',
+    message: 'No critical errors in stderr',
+  };
+}
+
+async function checkOutputContract(ctx: WaterfallContext): Promise<CheckResult> {
+  const maxPoints = SCORING_CONFIG.WEIGHTS.outputContract;
+  const raw = process.env.SUCCESS_CONTRACTS ?? '__RESULT__=SUCCESS';
+  const contracts = raw.split(',').map((s) => s.trim()).filter(Boolean);
+  const stdout = ctx.exec.stdout ?? '';
+
+  let matchedContracts = 0;
+
+  // Try JSON parse
+  try {
+    const parsed = JSON.parse(stdout);
+    if (parsed && (parsed.result === 'success' || parsed.status === 'success')) {
+      logger.info(`✓ JSON contract detected in stdout`);
+      return {
+        passed: true,
+        points: maxPoints,
+        maxPoints,
+        severity: 'high',
+        message: 'JSON success contract matched',
+      };
+    }
+  } catch {
+    // Not JSON, continue
+  }
+
+  // Check string/regex contracts in stdout
+  for (const contract of contracts) {
+    if (!contract) continue;
+    
+    const matched = contract.startsWith('/') && contract.endsWith('/')
+      ? new RegExp(contract.slice(1, -1)).test(stdout)
+      : stdout.includes(contract);
+
+    if (matched) {
+      matchedContracts++;
+      logger.info(`✓ Contract matched: ${contract}`);
+    }
+  }
+
+  // Check artifact if no matches in stdout
+  if (ctx.artifacts?.outputFile && matchedContracts === 0) {
+    try {
+      const content = await readFile(ctx.artifacts.outputFile, 'utf-8');
+      for (const contract of contracts) {
+        if (!contract) continue;
+        
+        const matched = contract.startsWith('/') && contract.endsWith('/')
+          ? new RegExp(contract.slice(1, -1)).test(content)
+          : content.includes(contract);
+
+        if (matched) {
+          matchedContracts++;
+          logger.info(`✓ Contract matched in artifact: ${contract}`);
+        }
+      }
+    } catch (err: any) {
+      logger.warn(`Could not read artifact: ${err?.message}`);
+    }
+  }
+
+  // Calculate score based on matched contracts
+  const percentage = contracts.length > 0 ? matchedContracts / contracts.length : 0;
+  
+  if (matchedContracts === contracts.length) {
+    return {
+      passed: true,
+      points: maxPoints,
+      maxPoints,
+      severity: 'high',
+      message: `All ${contracts.length} contract(s) matched`,
+    };
+  } else if (
+    SCORING_CONFIG.OUTPUT_CONTRACT.PARTIAL_CREDIT &&
+    percentage >= SCORING_CONFIG.OUTPUT_CONTRACT.PARTIAL_THRESHOLD / 100
+  ) {
+    const points = maxPoints * percentage;
+    logger.warn(`Only ${matchedContracts}/${contracts.length} contracts matched`);
+    return {
+      passed: true,
+      points,
+      maxPoints,
+      severity: 'medium',
+      message: `Partial match: ${matchedContracts}/${contracts.length} contracts`,
+    };
+  } else {
+    logger.warn(`Insufficient contracts: ${matchedContracts}/${contracts.length}`);
+    return {
+      passed: false,
+      points: 0,
+      maxPoints,
+      severity: 'high',
+      message: `Insufficient contracts: ${matchedContracts}/${contracts.length}`,
+    };
+  }
+}
+
+async function checkArtifacts(ctx: WaterfallContext): Promise<CheckResult> {
+  const maxPoints = SCORING_CONFIG.WEIGHTS.artifacts;
+
+  if (!ctx.artifacts?.outputFile) {
+    return {
+      passed: true,
+      points: maxPoints,
+      maxPoints,
+      severity: 'low',
+      message: 'No artifact required',
+    };
+  }
+
+  try {
+    const content = await readFile(ctx.artifacts.outputFile, 'utf-8');
+
+    if (!content || content.trim().length === 0) {
+      logger.warn('Empty artifact');
+      return {
+        passed: false,
+        points: 0,
+        maxPoints,
+        severity: 'medium',
+        message: 'Output artifact is empty',
+      };
+    }
+
+    logger.info(`✓ Artifact OK (${content.length} bytes)`);
+    return {
+      passed: true,
+      points: maxPoints,
+      maxPoints,
+      severity: 'low',
+      message: 'Artifact valid',
+    };
+  } catch (err: any) {
+    logger.warn(`Error reading artifact: ${err.message}`);
+    return {
+      passed: false,
+      points: 0,
+      maxPoints,
+      severity: 'medium',
+      message: `Failed to read artifact: ${err.message}`,
+    };
+  }
+}
+
+function calculateTotalScore(breakdown: ScoreBreakdown): number {
+  return (
+    breakdown.exitCode.points +
+    breakdown.stderr.points +
+    breakdown.outputContract.points +
+    breakdown.artifacts.points
+  );
+}
+
+function logScoreBreakdown(breakdown: ScoreBreakdown): void {
+  logger.info(`  Score breakdown:`);
+  logger.info(`  Exit Code:       ${breakdown.exitCode.points.toFixed(1)}/${breakdown.exitCode.maxPoints} ${breakdown.exitCode.passed ? '✓' : '✗'}`);
+  logger.info(`  Stderr:          ${breakdown.stderr.points.toFixed(1)}/${breakdown.stderr.maxPoints} ${breakdown.stderr.passed ? '✓' : '✗'}`);
+  logger.info(`  Output Contract: ${breakdown.outputContract.points.toFixed(1)}/${breakdown.outputContract.maxPoints} ${breakdown.outputContract.passed ? '✓' : '✗'}`);
+  logger.info(`  Artifacts:       ${breakdown.artifacts.points.toFixed(1)}/${breakdown.artifacts.maxPoints} ${breakdown.artifacts.passed ? '✓' : '✗'}`);
+  logger.info(`  ────────────────────────────`);
+  logger.info(`  TOTAL:           ${breakdown.totalScore.toFixed(1)}/100`);
+}

package/core/loop/writeArtifactAtomically.ts

@@ -0,0 +1,13 @@
+import { writeFile, rename } from 'node:fs/promises';
+
+export async function writeArtifactAtomically(args: {
+  tmpPath: string;
+  pathOutput: string;
+  content: string;
+  signal?: AbortSignal;
+}): Promise<void> {
+  const { tmpPath, pathOutput, content, signal } = args;
+  if (signal?.aborted) throw new Error('Aborted');
+  await writeFile(tmpPath, content, 'utf-8');
+  await rename(tmpPath, pathOutput);
+}

package/core/navigate/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.