boxsafe 1.0.0

package/core/paths/paths.ts

@@ -0,0 +1,33 @@
+import path from 'path';
+
+const CWD = process.cwd();
+
+export const MEMO_DIR = path.join(CWD, 'memo');
+export const STATES_LOGS_DIR = path.join(MEMO_DIR, 'states-logs');
+export const STATES_LOG_FILE = path.join(STATES_LOGS_DIR, 'logs.txt');
+
+export const TASKS_STATE_DIR = path.join(MEMO_DIR, 'state', 'tasks');
+export const TASKS_TASKS_DIR = path.join(TASKS_STATE_DIR, 'tasks');
+export const TASKS_STATE_FILE = path.join(TASKS_STATE_DIR, 'state.json');
+
+function resolveFromCwd(p: string): string {
+  return path.isAbsolute(p) ? p : path.join(CWD, p);
+}
+
+export function getGeneratedMarkdownPath(): string {
+  const fromEnv = process.env.BOXSAFE_MARKDOWN_PATH?.trim();
+  if (fromEnv) return resolveFromCwd(fromEnv);
+  return path.join(MEMO_DIR, 'generated', 'codelog.md');
+}
+
+export function getArtifactOutputPath(): string {
+  const fromEnv = process.env.AGENT_OUTPUT_PATH?.trim();
+  if (fromEnv) return resolveFromCwd(fromEnv);
+  return path.join(CWD, 'out.ts');
+}
+
+// path to code generated by the model
+export const pathToCode = getGeneratedMarkdownPath();
+
+// Backwards-compatible alias
+export const logs = STATES_LOG_FILE;

package/core/ports/index.ts

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview
+ * Ports da arquitetura hexagonal - Interfaces que definem contratos entre o core e o mundo externo
+ * 
+ * Baseado na estrutura existente do módulo sgmnt, adaptada para arquitetura hexagonal formal.
+ * 
+ * @module core/ports/index
+ */
+
+import type { BoxSafeConfig, CommandRun } from '../../types';
+import type { LService, LModel } from '@ai/label';
+
+// Re-export BoxSafeConfig for convenience
+export type { BoxSafeConfig, CommandRun } from '../../types';
+
+// Re-export navigate types for convenience
+export type { 
+  FileSystemEntry,
+  NavigatorConfig,
+  NavigatorResult,
+  OperationResult,
+  DirectoryListing,
+  FileReadResult,
+  FileWriteResult,
+  DirectoryCreateResult,
+  DeleteResult,
+  MetadataResult,
+  OperationError
+} from '@core/navigate/types';
+
+// ============================================================================
+// PRIMARY PORTS - Interfaces for primary actors (CLI, Web, IDE, etc.)
+// ============================================================================
+
+/**
+ * Main port for system execution - entry point for primary actors
+ * Based on existing segment system
+ */
+export interface ISystemExecutionPort {
+  /**
+   * Executes a specific system segment
+   * @param segmentName Name of the segment to be executed
+   * @param args Arguments for the segment
+   * @returns Execution result
+   */
+  executeSegment(segmentName: string, args?: any): Promise<any>;
+  
+  /**
+   * Lists all available segments
+   * @returns Map of available segments
+   */
+  listSegments(): Record<string, SegmentInfo>;
+}
+
+/**
+ * Information about a segment
+ */
+export interface SegmentInfo {
+  description: string;
+  implemented: boolean;
+  config?: any;
+}
+
+/**
+ * Port for system configuration
+ * Based on existing loadConfig
+ */
+export interface ISystemConfigurationPort {
+  /**
+   * Loads system configurations
+   * @param configPath Optional path to configuration file
+   * @returns Loaded configurations
+   */
+  loadConfiguration(configPath?: string): Promise<ConfigurationResult>;
+  
+  /**
+   * Validates system configurations
+   * @param config Configurations to be validated
+   * @returns Validation result
+   */
+  validateConfiguration(config: BoxSafeConfig): Promise<ValidationResult>;
+}
+
+/**
+ * Configuration loading result
+ */
+export interface ConfigurationResult {
+  config: BoxSafeConfig;
+  source: { path: string; loaded: boolean };
+}
+
+/**
+ * Configuration validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+// ============================================================================
+// SECONDARY PORTS - Interfaces for secondary actors (FileSystem, AI, Git, etc.)
+// ============================================================================
+
+/**
+ * Port for file system navigation
+ * Based on existing navigate module
+ */
+export interface IFileSystemPort {
+  /**
+   * Lists directory contents
+  listDirectory(path: string): Promise<any>;
+  
+  /**
+   * Reads file contents
+   */
+  readFile(path: string): Promise<any>;
+  
+  /**
+   * Writes content to a file
+   */
+  writeFile(path: string, content: string, options?: any): Promise<any>;
+  
+  /**
+   * Creates a directory
+   */
+  createDirectory(path: string, options?: any): Promise<any>;
+  
+  /**
+   * Removes file or directory
+   */
+  delete(path: string, options?: any): Promise<any>;
+  
+  /**
+   * Gets metadata of a file/directory
+   */
+  getMetadata(path: string): Promise<any>;
+}
+
+/**
+ * Port for AI model interaction
+ * Based on existing model configuration
+ */
+export interface IAIModelPort {
+  /**
+   * Sends prompt to the model
+   */
+  sendPrompt(prompt: string, options?: any): Promise<any>;
+  
+  /**
+   * Configures model to be used
+   */
+  configureModel(config: {
+    provider: LService;
+    name: LModel;
+    parameters?: Record<string, unknown>;
+  }): Promise<void>;
+}
+
+/**
+ * Port for version control (Git)
+ */
+export interface IVersionControlPort {
+  /**
+   * Executes Git command
+   */
+  executeGitCommand(command: string, args?: string[]): Promise<any>;
+  
+  /**
+   * Verifica status do repositório
+   */
+  getStatus(): Promise<any>;
+  
+  /**
+   * Cria commit
+   */
+  commit(message: string, files?: string[]): Promise<any>;
+  
+  /**
+   * Push para remoto
+   */
+  push(remote?: string, branch?: string): Promise<any>;
+}
+
+/**
+ * Port para execução de comandos
+ * Baseado na configuração commands existente
+ */
+export interface ICommandExecutionPort {
+  /**
+   * Executa comando do sistema
+   */
+  executeCommand(command: CommandRun, options?: CommandOptions): Promise<CommandResult>;
+}
+
+/**
+ * Opções para execução de comando
+ */
+export interface CommandOptions {
+  timeout?: number;
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+/**
+ * Resultado da execução de comando
+ */
+export interface CommandResult {
+  success: boolean;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  duration?: number;
+}
+
+// ============================================================================
+// DOMAIN PORTS - Interfaces específicas do domínio BoxSafe
+// ============================================================================
+
+/**
+ * Port para o loop principal do BoxSafe
+ * Baseado no módulo loop existente
+ */
+export interface IBoxSafeLoopPort {
+  /**
+   * Executa o loop iterativo principal
+   */
+  executeLoop(options: LoopOptions): Promise<LoopResult>;
+}
+
+/**
+ * Opções para o loop principal
+ */
+export interface LoopOptions {
+  service: LService;
+  model: LModel;
+  initialPrompt: string;
+  cmd: CommandRun;
+  lang: string;
+  pathOutput: string;
+  workspace?: string;
+  maxIterations?: number;
+  limit?: number;
+  signal?: AbortSignal;
+  pathGeneratedMarkdown?: string;
+  logger?: any;
+}
+
+/**
+ * Resultado do loop principal
+ */
+export interface LoopResult {
+  ok: boolean;
+  iterations: number;
+  verdict?: unknown;
+  artifacts?: { outputFile?: string };
+}
+
+// ============================================================================
+// UTILITY TYPES
+// ============================================================================
+
+/**
+ * Logger interface para uso em todos os ports
+ */
+export interface LoggerPort {
+  info: (...args: any[]) => void;
+  warn: (...args: any[]) => void;
+  error: (...args: any[]) => void;
+  debug?: (...args: any[]) => void;
+}

package/core/segments/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/core/segments/loop/index.ts

@@ -0,0 +1,18 @@
+import type { NormalizedBoxSafeConfig } from '@core/config/loadConfig';
+
+export function createLoopSegment(BSConfig: NormalizedBoxSafeConfig) {
+  return {
+    handler: async (opts?: any) => {
+      const mod = await import('@core/loop/execLoop');
+      return mod.loop(opts);
+    },
+    meta: {
+      description: 'Iterative LLM -> code -> exec loop',
+      implemented: true,
+      config: {
+        defaultLang: 'ts',
+        pathOutput: process.env.AGENT_OUTPUT_PATH ?? BSConfig.paths?.artifactOutput ?? './out.ts',
+      },
+    },
+  };
+}

package/core/segments/map.ts

@@ -0,0 +1,56 @@
+/**
+ * Segmentation map initialization
+ *
+ * Encapsulates all route logic in a single function.
+ * No arguments required—all config comes from boxsafe.config.json and env.
+ */
+import { ANSI } from "../../util/ANSI";
+import { loadBoxSafeConfig } from '@core/config/loadConfig';
+import { createLoopSegment } from './loop';
+import { createNavigateSegment } from './navigate';
+import { createVersionControlSegment } from './versionControl';
+
+/**
+ * Initialize segments map with all available routes.
+ * Loads config from boxsafe.config.json and env variables.
+ * Returns { routes, runSegment } for use in the application.
+ */
+export async function initSegments() {
+  const { config: BSConfig } = loadBoxSafeConfig();
+  const routes: Record<string, any> = {
+    loop: createLoopSegment(BSConfig),
+    navigate: createNavigateSegment(BSConfig),
+    sandbox: null, // TODO: create
+    model: {
+      primary: BSConfig.model?.primary ?? null,
+      fallback: BSConfig.model?.fallback ?? null,
+      endpoint: BSConfig.model?.endpoint ?? null,
+    },
+    commands: {
+      setup: BSConfig.commands?.setup ?? null,
+      run: BSConfig.commands?.run ?? null,
+      test: BSConfig.commands?.test ?? null,
+    },
+    interface: {
+      channel: BSConfig.interface?.channel ?? null,
+      prompt: BSConfig.interface?.prompt ?? null,
+      notifications: BSConfig.interface?.notifications ?? null,
+    },
+    teach: {
+      urls: BSConfig.teach?.urls ?? null,
+      files: BSConfig.teach?.files ?? null,
+    },
+    versionControl: createVersionControlSegment(BSConfig),
+  };
+
+  type RouteName = keyof typeof routes;
+
+  const runSegment = async (name: RouteName, args?: any) => {
+    const node = routes[name];
+    const handler = node?.handler ?? node?.run ?? null;
+    if (typeof handler === "function") return handler(args);
+    throw new Error(`Segment '${String(name)}' not implemented`);
+  };
+
+  return { routes, runSegment, BSConfig };
+}

package/core/segments/navigate/index.ts

@@ -0,0 +1,20 @@
+import type { NormalizedBoxSafeConfig } from '@core/config/loadConfig';
+
+export function createNavigateSegment(BSConfig: NormalizedBoxSafeConfig) {
+  return {
+    handler: async (params?: any) => {
+      const mod = await import('@core/navigate');
+      const workspace = BSConfig.project?.workspace ?? './';
+      const handler = mod.createNavigatorHandler(workspace);
+      return handler.execute(params);
+    },
+    meta: {
+      description: 'File system navigation with workspace boundary enforcement',
+      implemented: true,
+      config: {
+        workspace: BSConfig.project?.workspace ?? './',
+        maxFileSize: 10 * 1024 * 1024,
+      },
+    },
+  };
+}

package/core/segments/versionControl/index.ts

@@ -0,0 +1,18 @@
+import type { NormalizedBoxSafeConfig } from '@core/config/loadConfig';
+
+export function createVersionControlSegment(BSConfig: NormalizedBoxSafeConfig) {
+  return {
+    handler: async (params?: any) => {
+      const mod = await import('@core/loop/git');
+      return mod.runVersionControl(params ?? {});
+    },
+    meta: {
+      description: 'Versioning helper: commit, notes and optional push to origin',
+      implemented: true,
+      config: {
+        autoPushDefault: BSConfig.project?.versionControl?.after ?? false,
+        createNotesDefault: BSConfig.project?.versionControl?.generateNotes ?? false,
+      },
+    },
+  };
+}

package/core/util/logger.ts

@@ -0,0 +1,128 @@
+export enum LogLevel {
+    DEBUG = 1,
+    INFO,
+    WARN,
+    ERROR,
+}
+
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    module: string;
+    timestamp: Date;
+}
+
+export class Logger {
+    private static instance: Logger; // it the class itself 
+    private currentLevel: LogLevel; // current log level
+    private moduleName: string; // module name
+
+    // ANSI color codes - simplificado para melhor legibilidade
+    private static readonly COLORS = {
+        RESET: '\x1b[0m',
+        DEBUG: '\x1b[36m', // Cyan
+        INFO: '\x1b[32m',  // Green  
+        WARN: '\x1b[33m',  // Yellow
+        ERROR: '\x1b[31m', // Red
+    };
+
+    private static readonly LEVEL_NAMES = {
+        [LogLevel.DEBUG]: 'DEBUG',
+        [LogLevel.INFO]: 'INFO',
+        [LogLevel.WARN]: 'WARN',
+        [LogLevel.ERROR]: 'ERROR',
+    };
+
+    constructor(moduleName: string = 'Core', level: LogLevel = LogLevel.INFO) {
+        this.moduleName = moduleName;
+        this.currentLevel = level;
+    }
+
+    static getInstance(moduleName?: string, level?: LogLevel): Logger {  // create singleton instance
+        if (!Logger.instance) {
+            Logger.instance = new Logger(moduleName || 'Core', level);
+        }
+        return Logger.instance;
+    }
+
+    setLevel(level: LogLevel): void {
+        this.currentLevel = level;
+    }
+
+    getLevel(): LogLevel {
+        return this.currentLevel;
+    }
+
+    private formatMessage(level: LogLevel, message: string): string {
+        const levelName = Logger.LEVEL_NAMES[level];
+        const color = Logger.COLORS[levelName as keyof typeof Logger.COLORS];
+        const reset = Logger.COLORS.RESET;
+
+        return `${color}[${levelName}(${this.moduleName})]${reset} ${message}\n\n`;
+    }
+
+    private log(level: LogLevel, message: string): void {
+        if (level < this.currentLevel) {
+            return;
+        }
+
+        const formattedMessage = this.formatMessage(level, message);
+        process.stdout.write(formattedMessage);
+    }
+
+    debug(message: string): void {
+        this.log(LogLevel.DEBUG, message);
+    }
+
+    info(message: string): void {
+        this.log(LogLevel.INFO, message);
+    }
+
+    warn(message: string): void {
+        this.log(LogLevel.WARN, message);
+    }
+
+    error(message: string): void {
+        this.log(LogLevel.ERROR, message);
+    }
+
+    // Static methods for quick access
+    static debug(message: string, moduleName?: string): void {
+        const logger = new Logger(moduleName || 'Core');
+        logger.debug(message);
+    }
+
+    static info(message: string, moduleName?: string): void {
+        const logger = new Logger(moduleName || 'Core');
+        logger.info(message);
+    }
+
+    static warn(message: string, moduleName?: string): void {
+        const logger = new Logger(moduleName || 'Core');
+        logger.warn(message);
+    }
+
+    static error(message: string, moduleName?: string): void {
+        const logger = new Logger(moduleName || 'Core');
+        logger.error(message);
+    }
+
+    // Method to create a logger instance for a specific module
+    static createModuleLogger(moduleName: string, level?: LogLevel): Logger {
+        return new Logger(moduleName, level);
+    }
+}
+
+// Export a default logger instance
+export const logger = Logger.getInstance(); 
+/*
+just one instance for anything
+*/ 
+
+// Export convenience functions
+export const log = {
+    debug: (message: string, moduleName?: string) => Logger.debug(message, moduleName),
+    info: (message: string, moduleName?: string) => Logger.info(message, moduleName),
+    warn: (message: string, moduleName?: string) => Logger.warn(message, moduleName),
+    error: (message: string, moduleName?: string) => Logger.error(message, moduleName),
+};

package/docs/AGENT-TASKS.md

@@ -0,0 +1,36 @@
+**Tasks module for BoxSafe — core/loop/tasks**
+
+Overview
+- The `TasksManager` provides a minimal, predictable mechanism to load a TODO file,
+  split it into small tasks, persist task artifacts and a lightweight runtime state
+  under `memo/state/tasks`.
+
+Design goals
+- Keep implementation tiny and synchronous-friendly (async IO only).
+- Avoid complex formats: accept either `- item` lines or paragraphs separated by
+  blank lines in the TODO file.
+- Persist each task as `memo/state/tasks/tasks/task_###.md` and keep state in
+  `memo/state/tasks/state.json` with `current` and `done[]` fields.
+
+How it is used
+- The `execLoop` integrates `TasksManager` when `boxsafe.config.json` contains
+  `project.todo` pointing to a TODO file. The loop will use the current task as
+  the agent prompt, and when the agent completes a task it marks it done and
+  moves to the next. Only when all tasks complete does the loop perform the
+  normal after-success flow (versioning, notes, etc.).
+
+Files
+- `index.ts` — exports `TasksManager` class.
+
+Behavior summary
+- `TasksManager.init()` creates `memo/state/tasks` and writes individual task
+  files and `state.json` when needed.
+- `getCurrentTask()` returns the current task prompt or `null` when finished.
+- `markCurrentDone()` marks current task as done and advances to the next.
+- `isFinished()` signals completion of all tasks.
+
+Notes
+- The module intentionally keeps parsing and behavior simple to be robust and
+  easy to audit. If you want more advanced scheduling, priorities or parallel
+  execution, we can extend it, but this initial version focuses on correctness
+  and minimal surface area.