boxsafe 1.0.0

package/core/navigate/navigator.ts

@@ -0,0 +1,437 @@
+/**
+ * @fileoverview
+ * Main file system navigator class for LLM-driven file operations.
+ * Provides safe, validated methods for directory and file manipulation.
+ *
+ * @description
+ * The Navigator class enforces workspace boundaries, validates operations,
+ * and returns structured results suitable for LLM consumption and iteration.
+ *
+ * All paths are automatically validated and normalized.
+ * Operations respect file size limits to prevent memory issues.
+ *
+ * @module core/navigate/navigator
+ */
+
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import type {
+  NavigatorConfig,
+  NavigatorResult,
+  DirectoryListing,
+  FileReadResult,
+  FileWriteResult,
+  DirectoryCreateResult,
+  DeleteResult,
+  MetadataResult,
+  OperationError,
+  FileSystemEntry,
+} from '@core/navigate/types';
+import { Logger } from '@core/util/logger';
+import {
+  isWithinWorkspace,
+  resolvePath,
+  isReadable,
+  isWritable,
+  checkFileSize,
+  sanitizeFilename,
+  formatPathDisplay,
+} from '@core/navigate/utils';
+
+/**
+ * File system navigator for safe LLM-driven file operations.
+ * Enforces workspace boundaries and validates all operations.
+ */
+export class Navigator {
+  private workspace: string;
+  private followSymlinks: boolean;
+  private maxFileSize: number;
+
+  /**
+   * Creates a new Navigator instance.
+   *
+   * @param config - Configuration options
+   * @throws Error if workspace doesn't exist or is invalid
+   */
+  constructor(config: NavigatorConfig) {
+    // Validate workspace directory exists
+    const stats = fsSync.statSync(config.workspace);
+    if (!stats.isDirectory()) {
+      throw new Error(`Workspace path is not a directory: ${config.workspace}`);
+    }
+
+    this.workspace = path.resolve(config.workspace); // -- absolute path 
+    this.followSymlinks = config.followSymlinks ?? false;
+    this.maxFileSize = config.maxFileSize ?? 10 * 1024 * 1024; // 10MB default
+    
+    // Create logger directly
+    const logger = Logger.createModuleLogger('Navigator');
+    logger.debug(`Initialized with workspace: ${this.workspace}`);
+  }
+
+  /**
+   * Lists the contents of a directory.
+   *
+   * @param dirPath - Path to the directory (absolute or relative to workspace)
+   * @returns Structured result with directory contents or error
+   */
+  async listDirectory(dirPath: string = '.'): Promise<NavigatorResult> {
+    try {
+      // Resolve and validate path
+      const pathResult = resolvePath(dirPath, this.workspace);
+      if (!pathResult.ok) {
+        return this.error('listDirectory', pathResult.error);
+      }
+
+      const targetPath = pathResult.path;
+
+      // Verify it's a directory
+      const stats = await fs.stat(targetPath);
+      if (!stats.isDirectory()) {
+        return this.error('listDirectory', 'Path is not a directory');
+      }
+
+      // Read directory contents
+      const entries = await fs.readdir(targetPath, { withFileTypes: true });
+
+      // Build file system entries with metadata
+      const result: FileSystemEntry[] = [];
+      for (const entry of entries) {
+        try {
+          const fullPath = path.join(targetPath, entry.name);
+          const entryStats = await fs.stat(fullPath);
+
+          const fsEntry: FileSystemEntry = {
+            path: fullPath,
+            name: entry.name,
+            type: entry.isDirectory() ? 'directory' : 'file',
+            mtime: entryStats.mtimeMs,
+            readable: isReadable(fullPath),
+            writable: isWritable(fullPath),
+          };
+
+          // Only add size for files, not directories
+          if (!entry.isDirectory()) {
+            fsEntry.size = entryStats.size;
+          }
+
+          result.push(fsEntry);
+        } catch (err: any) {
+          Logger.createModuleLogger('Navigator').warn(`Failed to stat entry ${entry.name}: ${err?.message}`);
+        }
+      }
+
+      // Sort: directories first, then alphabetically
+      result.sort((a, b) => {
+        if (a.type !== b.type) {
+          return a.type === 'directory' ? -1 : 1;
+        }
+        return a.name.localeCompare(b.name);
+      });
+
+      return {
+        ok: true,
+        path: formatPathDisplay(targetPath, this.workspace),
+        entries: result,
+        total: result.length,
+      } as DirectoryListing;
+    } catch (err: any) {
+      return this.error(
+        'listDirectory',
+        `Failed to list directory: ${err?.message ?? 'unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Reads the content of a file.
+   *
+   * @param filePath - Path to the file (absolute or relative to workspace)
+   * @returns Structured result with file content or error
+   */
+  async readFile(filePath: string): Promise<NavigatorResult> {
+    try {
+      // Resolve and validate path
+      const pathResult = resolvePath(filePath, this.workspace);
+      if (!pathResult.ok) {
+        return this.error('readFile', pathResult.error);
+      }
+
+      const targetPath = pathResult.path;
+
+      // Verify it's a file
+      const stats = await fs.stat(targetPath);
+      if (stats.isDirectory()) {
+        return this.error('readFile', 'Path is a directory, not a file');
+      }
+
+      if (!isReadable(targetPath)) {
+        return this.error('readFile', 'File is not readable (permission denied)');
+      }
+
+      // Check file size
+      const sizeCheck = checkFileSize(targetPath, this.maxFileSize);
+      if (!sizeCheck.ok) {
+        return this.error('readFile', sizeCheck.error);
+      }
+
+      // Read file content
+      const content = await fs.readFile(targetPath, 'utf-8');
+
+      return {
+        ok: true,
+        path: formatPathDisplay(targetPath, this.workspace),
+        content,
+        size: sizeCheck.size,
+        encoding: 'utf-8',
+      } as FileReadResult;
+    } catch (err: any) {
+      return this.error(
+        'readFile',
+        `Failed to read file: ${err?.message ?? 'unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Writes content to a file.
+   * Creates the file if it doesn't exist, overwrites if it does.
+   *
+   * @param filePath - Path to the file (absolute or relative to workspace)
+   * @param content - Content to write
+   * @param options - Write options
+   * @returns Structured result with operation details or error
+   */
+  async writeFile(
+    filePath: string,
+    content: string,
+    options?: { append?: boolean; createDirs?: boolean }
+  ): Promise<NavigatorResult> {
+    try {
+      // Resolve and validate path
+      const pathResult = resolvePath(filePath, this.workspace);
+      if (!pathResult.ok) {
+        return this.error('writeFile', pathResult.error);
+      }
+
+      const targetPath = pathResult.path;
+
+      // Check if file exists and is writable
+      const fileExists = fsSync.existsSync(targetPath);
+      if (fileExists) {
+        const stats = fsSync.statSync(targetPath);
+        if (stats.isDirectory()) {
+          return this.error('writeFile', 'Path is a directory, not a file');
+        }
+
+        if (!isWritable(targetPath)) {
+          return this.error(
+            'writeFile',
+            'File exists but is not writable (permission denied)'
+          );
+        }
+      } else if (!options?.createDirs && !fsSync.existsSync(path.dirname(targetPath))) {
+        return this.error(
+          'writeFile',
+          'Parent directory does not exist (use createDirs: true option)'
+        );
+      } else {
+        const dirPath = path.dirname(targetPath);
+        if (!fsSync.existsSync(dirPath)) {
+          await fs.mkdir(dirPath, { recursive: true });
+        }
+      }
+
+      // Write file
+      if (options?.append && fileExists) {
+        await fs.appendFile(targetPath, content, 'utf-8');
+      } else {
+        await fs.writeFile(targetPath, content, 'utf-8');
+      }
+
+      // Get final size
+      const finalStats = await fs.stat(targetPath);
+
+      return {
+        ok: true,
+        path: formatPathDisplay(targetPath, this.workspace),
+        size: finalStats.size,
+        created: !fileExists,
+      } as FileWriteResult;
+    } catch (err: any) {
+      return this.error(
+        'writeFile',
+        `Failed to write file: ${err?.message ?? 'unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Creates a new directory.
+   *
+   * @param dirPath - Path to the directory to create (absolute or relative to workspace)
+   * @param options - Creation options
+   * @returns Structured result with operation details or error
+   */
+  async createDirectory(
+    dirPath: string,
+    options?: { recursive?: boolean }
+  ): Promise<NavigatorResult> {
+    try {
+      // Resolve and validate path
+      const pathResult = resolvePath(dirPath, this.workspace);
+      if (!pathResult.ok) {
+        return this.error('createDirectory', pathResult.error);
+      }
+
+      const targetPath = pathResult.path;
+
+      // Check if directory already exists
+      if (fsSync.existsSync(targetPath)) {
+        const stats = fsSync.statSync(targetPath);
+        if (!stats.isDirectory()) {
+          return this.error('createDirectory', 'Path exists but is not a directory');
+        }
+
+        return {
+          ok: true,
+          path: formatPathDisplay(targetPath, this.workspace),
+          created: false,
+        } as DirectoryCreateResult;
+      }
+
+      // Create directory
+      await fs.mkdir(targetPath, { recursive: options?.recursive ?? true });
+
+      return {
+        ok: true,
+        path: formatPathDisplay(targetPath, this.workspace),
+        created: true,
+      } as DirectoryCreateResult;
+    } catch (err: any) {
+      return this.error(
+        'createDirectory',
+        `Failed to create directory: ${err?.message ?? 'unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Deletes a file or directory.
+   *
+   * @param targetPath - Path to delete (absolute or relative to workspace)
+   * @param options - Deletion options
+   * @returns Structured result with operation details or error
+   */
+  async delete(
+    targetPath: string,
+    options?: { recursive?: boolean }
+  ): Promise<NavigatorResult> {
+    try {
+      // Resolve and validate path
+      const pathResult = resolvePath(targetPath, this.workspace);
+      if (!pathResult.ok) {
+        return this.error('delete', pathResult.error);
+      }
+
+      const resolvedPath = pathResult.path;
+
+      // Check if path exists
+      if (!fsSync.existsSync(resolvedPath)) {
+        return this.error('delete', 'Path does not exist');
+      }
+
+      const stats = fsSync.statSync(resolvedPath);
+      const isDirectory = stats.isDirectory();
+
+      // Delete based on type
+      if (isDirectory) {
+        if (options?.recursive ?? true) {
+          await fs.rm(resolvedPath, { recursive: true, force: true });
+        } else {
+          await fs.rmdir(resolvedPath);
+        }
+      } else {
+        await fs.unlink(resolvedPath);
+      }
+
+      return {
+        ok: true,
+        path: formatPathDisplay(resolvedPath, this.workspace),
+        type: isDirectory ? 'directory' : 'file',
+        deletedAt: Date.now(),
+      } as DeleteResult;
+    } catch (err: any) {
+      return this.error(
+        'delete',
+        `Failed to delete: ${err?.message ?? 'unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Gets metadata about a file or directory.
+   *
+   * @param targetPath - Path to get metadata for (absolute or relative to workspace)
+   * @returns Structured result with metadata or error
+   */
+  async getMetadata(targetPath: string): Promise<NavigatorResult> {
+    try {
+      // Resolve and validate path
+      const pathResult = resolvePath(targetPath, this.workspace);
+      if (!pathResult.ok) {
+        return this.error('getMetadata', pathResult.error);
+      }
+
+      const resolvedPath = pathResult.path;
+
+      // Check if path exists
+      if (!fsSync.existsSync(resolvedPath)) {
+        return this.error('getMetadata', 'Path does not exist');
+      }
+
+      const stats = await fs.stat(resolvedPath);
+
+      return {
+        ok: true,
+        path: formatPathDisplay(resolvedPath, this.workspace),
+        stat: {
+          type: stats.isDirectory() ? 'directory' : 'file',
+          size: stats.size,
+          mtime: stats.mtimeMs,
+          isReadable: isReadable(resolvedPath),
+          isWritable: isWritable(resolvedPath),
+        },
+      } as MetadataResult;
+    } catch (err: any) {
+      return this.error(
+        'getMetadata',
+        `Failed to get metadata: ${err?.message ?? 'unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Helper method to create error results.
+   * @private
+   */
+  private error(operation: string, error: string): OperationError {
+    Logger.createModuleLogger('Navigator').debug(`${operation} failed: ${error}`);
+    return {
+      ok: false,
+      operation,
+      error,
+    };
+  }
+}
+
+/**
+ * Creates a new Navigator instance with the given configuration.
+ *
+ * @param config - Configuration options
+ * @returns Navigator instance
+ */
+export function createNavigator(config: NavigatorConfig): Navigator {
+  return new Navigator(config);
+}

package/core/navigate/types.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview
+ * Type definitions for the file system navigation module.
+ * Provides structured interfaces for file operations and results.
+ *
+ * @module core/navigate/types
+ */
+
+/**
+ * Represents a file system entry (file or directory).
+ */
+export interface FileSystemEntry {
+  /** Absolute path to the entry */
+  path: string;
+  /** Name of the entry (filename or dirname) */
+  name: string;
+  /** Type of entry: 'file' or 'directory' */
+  type: 'file' | 'directory';
+  /** Size in bytes (files only) */
+  size?: number;
+  /** Unix timestamp of last modification */
+  mtime?: number;
+  /** Whether the path is readable */
+  readable: boolean;
+  /** Whether the path is writable */
+  writable: boolean;
+}
+
+/**
+ * Result of listing directory contents.
+ */
+export interface DirectoryListing {
+  ok: true;
+  path: string;
+  entries: FileSystemEntry[];
+  total: number;
+}
+
+/**
+ * Result of reading a file.
+ */
+export interface FileReadResult {
+  ok: true;
+  path: string;
+  content: string;
+  size: number;
+  encoding: 'utf-8';
+}
+
+/**
+ * Result of writing a file.
+ */
+export interface FileWriteResult {
+  ok: true;
+  path: string;
+  size: number;
+  created: boolean;
+}
+
+/**
+ * Result of creating a directory.
+ */
+export interface DirectoryCreateResult {
+  ok: true;
+  path: string;
+  created: boolean;
+}
+
+/**
+ * Result of deleting a file or directory.
+ */
+export interface DeleteResult {
+  ok: true;
+  path: string;
+  type: 'file' | 'directory';
+  deletedAt: number;
+}
+
+/**
+ * Result of getting metadata.
+ */
+export interface MetadataResult {
+  ok: true;
+  path: string;
+  stat: {
+    type: 'file' | 'directory';
+    size: number;
+    mtime: number;
+    isReadable: boolean;
+    isWritable: boolean;
+  };
+}
+
+/**
+ * Unified error result for any operation failure.
+ */
+export interface OperationError {
+  ok: false;
+  operation: string;
+  error: string;
+}
+
+/** Union of all possible successful operation results */
+export type OperationResult =
+  | DirectoryListing
+  | FileReadResult
+  | FileWriteResult
+  | DirectoryCreateResult
+  | DeleteResult
+  | MetadataResult;
+
+/** Union of all possible results (success or error) */
+export type NavigatorResult = OperationResult | OperationError;
+
+/**
+ * Options for navigator initialization.
+ */
+export interface NavigatorConfig {
+  /** Workspace root path - all operations must stay within this boundary */
+  workspace: string;
+  /** Whether to follow symbolic links (for security) */
+  followSymlinks?: boolean;
+  /** Maximum file size to read in bytes (prevents memory issues) */
+  maxFileSize?: number;
+  /** Logger instance for debugging */
+  logger?: {
+    debug: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+  };
+}

package/core/navigate/utils.ts

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview
+ * Utility functions for path validation and security checks.
+ *
+ * @module core/navigate/utils
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { accessSync, constants } from 'node:fs';
+
+/**
+ * Validates that a given path is within the workspace boundary.
+ * Prevents directory traversal attacks and unauthorized access.
+ *
+ * @param targetPath - The path to validate
+ * @param workspace - The workspace root path
+ * @returns true if path is within workspace, false otherwise
+ */
+export function isWithinWorkspace(targetPath: string, workspace: string): boolean {
+  try {
+    const absTarget = path.resolve(targetPath);
+    const absWorkspace = path.resolve(workspace);
+    const relative = path.relative(absWorkspace, absTarget);
+
+    // If relative path starts with '..', it's outside workspace
+    return !relative.startsWith('..');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalizes and resolves a path relative to workspace.
+ * Handles both absolute and relative paths.
+ *
+ * @param inputPath - The path to normalize
+ * @param workspace - The workspace root path
+ * @returns Absolute resolved path, or error message
+ */
+export function resolvePath(inputPath: string, workspace: string): { ok: true; path: string } | { ok: false; error: string } {
+  try {
+    const resolved = path.isAbsolute(inputPath)
+      ? path.resolve(inputPath)
+      : path.resolve(workspace, inputPath);
+
+    if (!isWithinWorkspace(resolved, workspace)) {
+      return {
+        ok: false,
+        error: `Access denied: path outside workspace boundary (${resolved})`,
+      };
+    }
+
+    return { ok: true, path: resolved };
+  } catch (err: any) {
+    return {
+      ok: false,
+      error: `Failed to resolve path: ${err?.message ?? 'unknown error'}`,
+    };
+  }
+}
+
+/**
+ * Checks if a path is readable.
+ * Safely handles permission errors.
+ *
+ * @param filePath - The path to check
+ * @returns true if readable, false otherwise
+ */
+export function isReadable(filePath: string): boolean {
+  try {
+    accessSync(filePath, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks if a path is writable.
+ * Safely handles permission errors.
+ *
+ * @param filePath - The path to check
+ * @returns true if writable, false otherwise
+ */
+export function isWritable(filePath: string): boolean {
+  try {
+    accessSync(filePath, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks if a file size exceeds the maximum allowed.
+ *
+ * @param filePath - The path to check
+ * @param maxSize - Maximum allowed size in bytes
+ * @returns { ok: true; size: number } or { ok: false; error: string }
+ */
+export function checkFileSize(
+  filePath: string,
+  maxSize: number
+): { ok: true; size: number } | { ok: false; error: string } {
+  try {
+    const stats = fs.statSync(filePath);
+    if (stats.size > maxSize) {
+      return {
+        ok: false,
+        error: `File size exceeds limit: ${stats.size} bytes > ${maxSize} bytes`,
+      };
+    }
+    return { ok: true, size: stats.size };
+  } catch (err: any) {
+    return {
+      ok: false,
+      error: `Failed to check file size: ${err?.message ?? 'unknown'}`,
+    };
+  }
+}
+
+/**
+ * Sanitizes a filename to prevent directory traversal in filenames.
+ *
+ * @param filename - The filename to sanitize
+ * @returns Sanitized filename
+ */
+export function sanitizeFilename(filename: string): string {
+  return filename
+    .replace(/[/\\]/g, '_') // Remove path separators
+    .replace(/^\.|\.$/g, '') // Remove leading/trailing dots
+    .replace(/^-/, '_'); // Remove leading dash
+}
+
+/**
+ * Formats a path for display (makes it relative to workspace).
+ *
+ * @param absolutePath - The absolute path
+ * @param workspace - The workspace root
+ * @returns Display-friendly path
+ */
+export function formatPathDisplay(absolutePath: string, workspace: string): string {
+  const relative = path.relative(workspace, absolutePath);
+  return relative || '.';
+}