boxsafe 1.0.0

package/core/navigate/about.md

@@ -0,0 +1,128 @@
+# Navigate Module
+
+File system navigation system with safety boundaries for LLM-driven operations.
+
+## Purpose
+
+Provides a robust, type-safe interface for an LLM to:
+- List directory contents
+- Read file contents
+- Write/create files
+- Create directories
+- Delete files and directories
+- Get file/directory metadata
+
+All operations are confined to a workspace boundary and validated.
+
+## Architecture
+
+```
+navigator.ts (main class)
+├─ listDirectory()
+├─ readFile()
+├─ writeFile()
+├─ createDirectory()
+├─ delete()
+└─ getMetadata()
+
+handler.ts (sgmnt integration)
+└─ NavigatorHandler.execute(params)
+
+utils.ts (security & validation)
+├─ isWithinWorkspace()
+├─ resolvePath()
+├─ checkFileSize()
+└─ isReadable/isWritable()
+
+types.ts (exported interfaces)
+├─ NavigatorConfig
+├─ NavigatorResult
+└─ FileSystemEntry
+```
+
+## Quick Start
+
+```typescript
+import { createNavigator } from '@core/navigate';
+
+const nav = createNavigator({ workspace: '/app' });
+
+// List files
+const dir = await nav.listDirectory('src');
+if (dir.ok) {
+  console.log(dir.entries);
+}
+
+// Read file
+const file = await nav.readFile('src/main.ts');
+if (file.ok) {
+  console.log(file.content);
+}
+
+// Write file
+const write = await nav.writeFile('src/out.ts', 'export const x = 1;', {
+  createDirs: true,
+});
+
+// Create directory
+const mkdir = await nav.createDirectory('src/utils');
+
+// Get metadata
+const stat = await nav.getMetadata('src/main.ts');
+
+// Delete
+const del = await nav.delete('src/temp', { recursive: true });
+```
+
+## Integration with sgmnt
+
+Can be integrated into the segmentation map for unified command routing:
+
+```typescript
+const handler = createNavigatorHandler(workspace);
+
+await handler.execute({
+  op: 'write',
+  path: 'src/file.ts',
+  content: '...',
+  writeOptions: { createDirs: true }
+});
+```
+
+## Safety Features
+
+1. **Workspace Boundary** - All paths validated to stay within workspace
+2. **Size Limits** - File reads limited to 10MB default (configurable)
+3. **Permission Checks** - Validates read/write permissions before operations
+4. **Path Validation** - Prevents directory traversal attacks
+5. **Structured Errors** - Clear, machine-readable error results
+
+## Error Handling
+
+All operations return `NavigatorResult` - either success or error:
+
+```typescript
+type NavigatorResult = 
+  | DirectoryListing 
+  | FileReadResult 
+  | FileWriteResult 
+  | DirectoryCreateResult 
+  | DeleteResult 
+  | MetadataResult
+  | OperationError;
+
+if (result.ok) {
+  // Success - type is narrowed to specific result type
+} else {
+  // Error
+  console.error(result.error);
+}
+```
+
+## Performance Notes
+
+- No blocking operations
+- Async/await throughout
+- Efficient directory sorting (dirs first, then alphabetical)
+- Metadata included with directory listings for smart filtering
+- File read limited by configurable size limit

package/core/navigate/examples.ts

@@ -0,0 +1,367 @@
+/**
+ * @fileoverview
+ * Practical examples of using the Navigator module.
+ * These examples show common use cases for LLM-driven file operations.
+ *
+ * @module core/navigate/examples
+ */
+
+import { createNavigator, createNavigatorHandler } from '@core/navigate';
+import type { DirectoryListing, FileReadResult, FileWriteResult, MetadataResult } from '@core/navigate';
+import { Logger } from '@core/util/logger';
+
+// Type guards for proper narrowing
+const isDirectory = (result: any): result is DirectoryListing => result.ok && 'entries' in result;
+const isFileRead = (result: any): result is FileReadResult => result.ok && 'content' in result;
+const isFileWrite = (result: any): result is FileWriteResult => result.ok && 'created' in result;
+const isMetadata = (result: any): result is MetadataResult => result.ok && 'stat' in result;
+const isError = (result: any): result is { ok: false; error: string } => !result.ok;
+
+const logger = Logger.createModuleLogger('NavigateExamples');
+
+// Example 1: Basic Setup and Directory Listing
+
+async function example1_BasicListingAndExploration() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+  });
+
+  // List root workspace
+  const root = await nav.listDirectory('.');
+  if (isDirectory(root)) {
+    logger.info(`Workspace has ${root.total} items:`);
+    root.entries.forEach((entry) => {
+      const icon = entry.type === 'directory' ? '📁' : '📄';
+      const size = entry.size ? ` (${entry.size} bytes)` : '';
+      logger.info(`  ${icon} ${entry.name}${size}`);
+    });
+  }
+
+  // Navigate to specific directory
+  const srcDir = await nav.listDirectory('src');
+  if (isDirectory(srcDir)) {
+    logger.info(`Found ${srcDir.total} items in src/`);
+  }
+}
+
+// ============================================================================
+// Example 2: Reading Multiple Files for Analysis
+// ============================================================================
+
+async function example2_ReadMultipleFilesForLLMAnalysis() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+  });
+
+  // Read several related files
+  const files = ['main.ts', 'types.d.ts', 'package.json'];
+  const contents: Record<string, string> = {};
+
+  for (const file of files) {
+    const result = await nav.readFile(file);
+    if (isFileRead(result)) {
+      contents[file] = result.content;
+      logger.info(`Loaded ${file} (${result.size} bytes)`);
+    } else if (!result.ok) {
+      logger.error(`Failed to read ${file}: ${result.error}`);
+    }
+  }
+
+  // Now LLM can analyze all files together
+  logger.info(`All files loaded for analysis`);
+  return contents;
+}
+
+// ============================================================================
+// Example 3: Creating Project Structure
+// ============================================================================
+
+async function example3_CreateProjectStructure() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+  });
+
+  // Create directory structure
+  const dirs = [
+    'output',
+    'output/generated',
+    'output/reports',
+    'output/logs',
+  ];
+
+  for (const dir of dirs) {
+    const result = await nav.createDirectory(dir, { recursive: true });
+    if (isError(result)) {
+      logger.error(`Failed: ${result.error}`);
+    } else {
+      logger.info(`Created: ${result.path}`);
+    }
+  }
+}
+
+// ============================================================================
+// Example 4: Generate Multiple Code Files
+// ============================================================================
+
+async function example4_GenerateCodeFiles() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+  });
+
+  const files = [
+    {
+      path: 'generated/types.ts',
+      content: `export interface User { id: string; name: string; }`,
+    },
+    {
+      path: 'generated/utils.ts',
+      content: `export function formatName(name: string): string { return name.trim(); }`,
+    },
+    {
+      path: 'generated/index.ts',
+      content: `export * from './types';\nexport * from './utils';`,
+    },
+  ];
+
+  for (const file of files) {
+    const result = await nav.writeFile(file.path, file.content, {
+      createDirs: true,
+    });
+
+    if (isError(result)) {
+      logger.error(`✗ Failed: ${result.error}`);
+    } else {
+      logger.info(`✓ Created ${result.path}`);
+    }
+  }
+}
+
+// ============================================================================
+// Example 5: Iterate and Update Files
+// ============================================================================
+
+async function example5_IterativeFileUpdates() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+  });
+
+  // Read existing file
+  const result = await nav.readFile('src/main.ts');
+  if (!isFileRead(result)) {
+    logger.error(`Cannot read: ${isError(result) ? result.error : 'unknown'}`);
+    return;
+  }
+  let content = result.content;
+  const hasExport = content.includes('export');
+  if (!hasExport) {
+    // Add export if missing
+    content = `export ${content}`;
+  }
+
+  // Write back with updated content
+  const writeResult = await nav.writeFile('src/main.ts', content);
+  if (isFileWrite(writeResult)) {
+    logger.info(`Updated ${writeResult.path} (${writeResult.size} bytes)`);
+  } else if (isError(writeResult)) {
+    logger.error(`Write failed: ${writeResult.error}`);
+  }
+}
+
+// ============================================================================
+// Example 6: Check File Metadata Before Operations
+// ============================================================================
+
+async function example6_ValidateBeforeOperation() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+    maxFileSize: 5 * 1024 * 1024, // 5MB limit
+  });
+
+  const filePath = 'src/large.json';
+
+  // Check metadata first
+  const stat = await nav.getMetadata(filePath);
+  if (!isMetadata(stat)) {
+    logger.error(`File not found: ${isError(stat) ? stat.error : 'unknown'}`);
+    return;
+  }
+  if (stat.stat.size > 1024 * 1024) {
+    logger.warn(`File is ${stat.stat.size} bytes - may be too large`);
+  }
+  if (!stat.stat.isReadable) {
+    logger.error(`File is not readable`);
+    return;
+  }
+
+  // Now safe to read
+  const content = await nav.readFile(filePath);
+  if (isFileRead(content)) {
+    logger.info(`File content loaded: ${content.content.slice(0, 100)}`);
+  }
+}
+
+// ============================================================================
+// Example 7: LLM-Friendly Handler Integration
+// ============================================================================
+
+async function example7_HandlerIntegration() {
+  const handler = createNavigatorHandler('/home/inky/Development/boxsafe');
+
+  // Simple operations through handler
+  const list = await handler.execute({
+    op: 'list',
+    path: 'src',
+  });
+  logger.info(`Directory listing result:`);
+  logger.debug(JSON.stringify(list, null, 2));
+
+  // Write with structured params
+  const write = await handler.execute({
+    op: 'write',
+    path: 'output/result.ts',
+    content: 'export const result = "success";',
+    writeOptions: { createDirs: true },
+  });
+  logger.info(`Write result:`);
+  logger.debug(JSON.stringify(write, null, 2));
+
+  // Read with error handling
+  const read = await handler.execute({
+    op: 'read',
+    path: 'output/result.ts',
+  });
+  if (isError(read)) {
+    logger.error(`Read error: ${read.error}`);
+  } else if (isFileRead(read)) {
+    logger.info(`Content: ${read.content}`);
+  }
+
+  // Delete operation
+  const del = await handler.execute({
+    op: 'delete',
+    path: 'output/temp',
+    deleteOptions: { recursive: true },
+  });
+  logger.info(`Delete result:`);
+  logger.debug(JSON.stringify(del, null, 2));
+}
+
+// ============================================================================
+// Example 8: Batch Operations with Error Recovery
+// ============================================================================
+
+async function example8_BatchOperationsWithRecovery() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+  });
+
+  const operations = [
+    { type: 'mkdir' as const, path: 'batch/level1' },
+    { type: 'mkdir' as const, path: 'batch/level1/level2' },
+    { type: 'write' as const, path: 'batch/file1.txt', content: 'content1' },
+    { type: 'write' as const, path: 'batch/level1/file2.txt', content: 'content2' },
+  ];
+
+  const results = [];
+  for (const op of operations) {
+    try {
+      let result;
+      if (op.type === 'mkdir') {
+        result = await nav.createDirectory(op.path, { recursive: true });
+      } else if (op.type === 'write') {
+        result = await nav.writeFile(op.path, op.content, { createDirs: true });
+      }
+
+      if (result?.ok) {
+        results.push({ status: 'ok', op, result });
+      } else if (isError(result)) {
+        results.push({ status: 'error', op, error: result });
+      }
+    } catch (err) {
+      results.push({ status: 'exception', op, error: err });
+    }
+  }
+
+  logger.info(`Batch results:`);
+  logger.debug(JSON.stringify(results, null, 2));
+  return results;
+}
+
+// ============================================================================
+// Example 9: Explore Directory Tree
+// ============================================================================
+
+async function example9_ExploreDirectoryTree() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+  });
+
+  async function exploreTree(dirPath: string, depth: number = 0): Promise<void> {
+    const indent = '  '.repeat(depth);
+
+    const listing = await nav.listDirectory(dirPath);
+    if (!isDirectory(listing)) {
+      logger.error(`${indent}ERROR: ${isError(listing) ? listing.error : 'unknown'}`);
+      return;
+    }
+
+    for (const entry of listing.entries) {
+      if (entry.type === 'directory') {
+        logger.info(`${indent}📁 ${entry.name}/`);
+        if (depth < 2) await exploreTree(entry.path, depth + 1);
+      } else {
+        logger.info(`${indent}📄 ${entry.name} (${entry.size ?? 0} bytes)`);
+      }
+    }
+  }
+
+  await exploreTree('.');
+}
+
+// ============================================================================
+// Example 10: Validate Workspace Before Starting
+// ============================================================================
+
+async function example10_ValidateWorkspace() {
+  const nav = createNavigator({
+    workspace: '/home/inky/Development/boxsafe',
+  });
+
+  const requiredFiles = [
+    'package.json',
+    'tsconfig.json',
+    'types.d.ts',
+  ];
+
+  const required = [];
+  for (const file of requiredFiles) {
+    const stat = await nav.getMetadata(file);
+    const exists = isMetadata(stat);
+    const writable = exists ? stat.stat.isWritable : false;
+
+    required.push({ file, exists, writable });
+  }
+
+  logger.info(`Workspace validation:`);
+  logger.debug(JSON.stringify(required, null, 2));
+  const allReady = required.every((r) => r.exists && r.writable);
+  logger.info(`Workspace ready: ${allReady}`);
+  return allReady;
+}
+
+// ============================================================================
+// Export all examples for testing
+// ============================================================================
+
+export const examples = {
+  basicListing: example1_BasicListingAndExploration,
+  readMultiple: example2_ReadMultipleFilesForLLMAnalysis,
+  createStructure: example3_CreateProjectStructure,
+  generateFiles: example4_GenerateCodeFiles,
+  iterateUpdate: example5_IterativeFileUpdates,
+  validateMetadata: example6_ValidateBeforeOperation,
+  handlerIntegration: example7_HandlerIntegration,
+  batchOperations: example8_BatchOperationsWithRecovery,
+  exploreTree: example9_ExploreDirectoryTree,
+  validateWorkspace: example10_ValidateWorkspace,
+};

package/core/navigate/handler.ts

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview
+ * Handler for file system navigation operations.
+ * Integrates with the sgmnt (segmentation) system for unified LLM command routing.
+ *
+ * @module core/navigate/handler
+ */
+
+import type { NavigatorResult } from '@core/navigate/types';
+import { createNavigator, Navigator } from '@core/navigate/navigator';
+
+/**
+ * Parameters for navigator operations.
+ */
+export interface NavigatorOperationParams {
+  /** Operation type: 'list', 'read', 'write', 'mkdir', 'delete', 'stat' */
+  op: 'list' | 'read' | 'write' | 'mkdir' | 'delete' | 'stat';
+
+  /** File or directory path (required for all except 'list' with default) */
+  path?: string;
+
+  /** Content to write (required for 'write') */
+  content?: string;
+
+  /** Write options */
+  writeOptions?: {
+    append?: boolean;
+    createDirs?: boolean;
+  };
+
+  /** Directory creation options */
+  mkdirOptions?: {
+    recursive?: boolean;
+  };
+
+  /** Delete options */
+  deleteOptions?: {
+    recursive?: boolean;
+  };
+}
+
+/**
+ * Handler for all navigation operations.
+ * Provides a unified interface for LLM-driven file system access.
+ */
+export class NavigatorHandler {
+  private navigator: Navigator;
+
+  /**
+   * Creates a handler instance.
+   *
+   * @param workspace - Workspace root path for all operations
+   */
+  constructor(workspace: string) {
+    this.navigator = createNavigator({
+      workspace,
+      followSymlinks: false,
+      maxFileSize: 10 * 1024 * 1024, // 10MB default
+    });
+  }
+
+  /**
+   * Executes a navigation operation.
+   *
+   * @param params - Operation parameters
+   * @returns Promise resolving to operation result
+   */
+  async execute(params: NavigatorOperationParams): Promise<NavigatorResult> {
+    switch (params.op) {
+      case 'list':
+        return this.navigator.listDirectory(params.path || '.');
+
+      case 'read':
+        if (!params.path) {
+          return {
+            ok: false,
+            operation: 'read',
+            error: 'path is required for read operation',
+          };
+        }
+        return this.navigator.readFile(params.path);
+
+      case 'write':
+        if (!params.path) {
+          return {
+            ok: false,
+            operation: 'write',
+            error: 'path is required for write operation',
+          };
+        }
+        if (params.content === undefined) {
+          return {
+            ok: false,
+            operation: 'write',
+            error: 'content is required for write operation',
+          };
+        }
+        return this.navigator.writeFile(params.path, params.content, params.writeOptions);
+
+      case 'mkdir':
+        if (!params.path) {
+          return {
+            ok: false,
+            operation: 'mkdir',
+            error: 'path is required for mkdir operation',
+          };
+        }
+        return this.navigator.createDirectory(params.path, params.mkdirOptions);
+
+      case 'delete':
+        if (!params.path) {
+          return {
+            ok: false,
+            operation: 'delete',
+            error: 'path is required for delete operation',
+          };
+        }
+        return this.navigator.delete(params.path, params.deleteOptions);
+
+      case 'stat':
+        if (!params.path) {
+          return {
+            ok: false,
+            operation: 'stat',
+            error: 'path is required for stat operation',
+          };
+        }
+        return this.navigator.getMetadata(params.path);
+
+      default:
+        return {
+          ok: false,
+          operation: 'unknown',
+          error: `unknown operation: ${(params as any).op}`,
+        };
+    }
+  }
+}
+
+/**
+ * Creates a handler instance bound to a workspace.
+ *
+ * @param workspace - Workspace root path
+ * @returns NavigatorHandler instance
+ */
+export function createNavigatorHandler(workspace: string): NavigatorHandler {
+  return new NavigatorHandler(workspace);
+}

package/core/navigate/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview
+ * File system navigation module - public API exports.
+ * 
+ * Provides LLM-safe file and directory operations with workspace boundary enforcement.
+ *
+ * @module core/navigate
+ * @example
+ * ```typescript
+ * import { createNavigator } from '@core/navigate';
+ *
+ * const nav = createNavigator({ workspace: '/app' });
+ * const result = await nav.listDirectory('src');
+ * ```
+ */
+
+export { Navigator, createNavigator } from '@core/navigate/navigator';
+export { NavigatorHandler, createNavigatorHandler } from '@core/navigate/handler';
+export type {
+  NavigatorConfig,
+  NavigatorResult,
+  OperationResult,
+  OperationError,
+  DirectoryListing,
+  FileReadResult,
+  FileWriteResult,
+  DirectoryCreateResult,
+  DeleteResult,
+  MetadataResult,
+  FileSystemEntry,
+} from '@core/navigate/types';
+export type { NavigatorOperationParams } from '@core/navigate/handler';