@loxia-labs/loxia-autopilot-one 1.0.1

package/src/modules/fileExplorer/controller.js

@@ -0,0 +1,280 @@
+/**
+ * File Explorer Controller
+ * Handles all file system operations for the file explorer module
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+class FileExplorerController {
+  constructor(config = {}) {
+    this.config = {
+      showHidden: false,
+      allowedExtensions: [], // Empty array = all extensions allowed
+      maxDepth: 50, // Prevent infinite directory traversal
+      restrictedPaths: [], // Paths that cannot be accessed
+      ...config
+    };
+  }
+
+  /**
+   * Get file/directory stats safely
+   * @param {string} filePath - Path to check
+   * @returns {Promise<{stats: fs.Stats | null, error?: string}>}
+   */
+  async getFileStats(filePath) {
+    try {
+      const stats = await fs.stat(filePath);
+      return { stats };
+    } catch (error) {
+      return { 
+        stats: null, 
+        error: error instanceof Error ? error.message : 'Unknown error' 
+      };
+    }
+  }
+
+  /**
+   * Check if path is safe and accessible
+   * @param {string} requestedPath - Path to validate
+   * @returns {boolean}
+   */
+  isSafePath(requestedPath) {
+    try {
+      const resolvedPath = path.resolve(requestedPath);
+      
+      // Check if path is in restricted list
+      if (this.config.restrictedPaths.some(restricted => 
+        resolvedPath.startsWith(path.resolve(restricted))
+      )) {
+        return false;
+      }
+
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Filter items based on configuration
+   * @param {string} itemName - Item name to check
+   * @param {fs.Stats} stats - File stats
+   * @returns {boolean}
+   */
+  shouldIncludeItem(itemName, stats) {
+    // Check hidden files
+    if (!this.config.showHidden && itemName.startsWith('.')) {
+      return false;
+    }
+
+    // Check file extensions (only for files)
+    if (stats.isFile() && this.config.allowedExtensions.length > 0) {
+      const ext = path.extname(itemName).toLowerCase();
+      if (!this.config.allowedExtensions.includes(ext)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Browse directory contents
+   * @param {string} requestedPath - Directory path to browse
+   * @param {Object} options - Browse options
+   * @returns {Promise<{success: boolean, data?: BrowseResponse, error?: string}>}
+   */
+  async browseDirectory(requestedPath = process.cwd(), options = {}) {
+    try {
+      const normalizedPath = path.resolve(requestedPath);
+
+      // Security checks
+      if (!this.isSafePath(normalizedPath)) {
+        return {
+          success: false,
+          error: 'Access to this path is restricted'
+        };
+      }
+
+      // Check if path exists and is directory
+      const { stats, error } = await this.getFileStats(normalizedPath);
+      if (error || !stats) {
+        return {
+          success: false,
+          error: 'Path not found or inaccessible'
+        };
+      }
+
+      if (!stats.isDirectory()) {
+        return {
+          success: false,
+          error: 'Path is not a directory'
+        };
+      }
+
+      // Read directory contents
+      const items = await fs.readdir(normalizedPath);
+      const fileItems = [];
+
+      // Process each item
+      for (const item of items) {
+        const itemPath = path.join(normalizedPath, item);
+        const { stats: itemStats } = await this.getFileStats(itemPath);
+
+        if (itemStats && this.shouldIncludeItem(item, itemStats)) {
+          const fileItem = {
+            name: item,
+            path: itemPath,
+            type: itemStats.isDirectory() ? 'directory' : 'file',
+            size: itemStats.isFile() ? itemStats.size : undefined,
+            lastModified: itemStats.mtime,
+            extension: itemStats.isFile() ? path.extname(item).toLowerCase() : undefined
+          };
+          fileItems.push(fileItem);
+        }
+      }
+
+      // Sort: directories first, then files, both alphabetically
+      fileItems.sort((a, b) => {
+        if (a.type === b.type) {
+          return a.name.localeCompare(b.name);
+        }
+        return a.type === 'directory' ? -1 : 1;
+      });
+
+      // Calculate parent path
+      const parentPath = path.dirname(normalizedPath);
+      const hasParent = parentPath !== normalizedPath;
+
+      return {
+        success: true,
+        data: {
+          currentPath: normalizedPath,
+          parentPath: hasParent ? parentPath : null,
+          items: fileItems,
+          totalItems: fileItems.length,
+          directories: fileItems.filter(item => item.type === 'directory').length,
+          files: fileItems.filter(item => item.type === 'file').length
+        }
+      };
+
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Server error'
+      };
+    }
+  }
+
+  /**
+   * Get file information
+   * @param {string} filePath - File path to get info for
+   * @returns {Promise<{success: boolean, data?: FileItem, error?: string}>}
+   */
+  async getFileInfo(filePath) {
+    try {
+      if (!filePath || !this.isSafePath(filePath)) {
+        return {
+          success: false,
+          error: 'Invalid file path'
+        };
+      }
+
+      const { stats, error } = await this.getFileStats(filePath);
+      if (error || !stats) {
+        return {
+          success: false,
+          error: 'File not found'
+        };
+      }
+
+      const fileInfo = {
+        name: path.basename(filePath),
+        path: filePath,
+        type: stats.isDirectory() ? 'directory' : 'file',
+        size: stats.isFile() ? stats.size : undefined,
+        lastModified: stats.mtime,
+        extension: stats.isFile() ? path.extname(filePath).toLowerCase() : undefined
+      };
+
+      return {
+        success: true,
+        data: fileInfo
+      };
+
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Server error'
+      };
+    }
+  }
+
+  /**
+   * Get current working directory info
+   * @returns {{success: boolean, data: {cwd: string, platform: string, homedir: string}}}
+   */
+  getCurrentWorkingDirectory() {
+    return {
+      success: true,
+      data: {
+        cwd: process.cwd(),
+        platform: process.platform,
+        homedir: os.homedir()
+      }
+    };
+  }
+
+  /**
+   * Create directory
+   * @param {string} dirPath - Directory path to create
+   * @param {Object} options - Creation options
+   * @returns {Promise<{success: boolean, data?: {path: string}, error?: string}>}
+   */
+  async createDirectory(dirPath, options = {}) {
+    try {
+      if (!this.isSafePath(dirPath)) {
+        return {
+          success: false,
+          error: 'Invalid directory path'
+        };
+      }
+
+      await fs.mkdir(dirPath, { recursive: options.recursive || false });
+
+      return {
+        success: true,
+        data: {
+          path: dirPath,
+          relativePath: path.relative(process.cwd(), dirPath)
+        }
+      };
+
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to create directory',
+        code: error.code
+      };
+    }
+  }
+
+  /**
+   * Health check
+   * @returns {{success: boolean, data: {status: string, timestamp: string}}}
+   */
+  healthCheck() {
+    return {
+      success: true,
+      data: {
+        status: 'healthy',
+        timestamp: new Date().toISOString(),
+        module: 'fileExplorer'
+      }
+    };
+  }
+}
+
+export default FileExplorerController;

package/src/modules/fileExplorer/index.js

@@ -0,0 +1,37 @@
+/**
+ * File Explorer Module
+ * Main entry point for the file explorer functionality
+ */
+
+import { createFileExplorerRouter, defaultConfig } from './routes.js';
+import FileExplorerController from './controller.js';
+
+/**
+ * Initialize file explorer module
+ * @param {Object} config - Configuration options
+ * @returns {Object} Module interface
+ */
+export function initFileExplorerModule(config = {}) {
+  const mergedConfig = { ...defaultConfig, ...config };
+  const router = createFileExplorerRouter(mergedConfig);
+  const controller = new FileExplorerController(mergedConfig);
+  
+  return {
+    router,
+    controller,
+    config: mergedConfig
+  };
+}
+
+// Export individual components for advanced usage
+export { default as FileExplorerController } from './controller.js';
+export { createFileExplorerRouter, defaultConfig } from './routes.js';
+export * from './middleware.js';
+
+// Default export
+export default {
+  init: initFileExplorerModule,
+  Controller: FileExplorerController,
+  createRouter: createFileExplorerRouter,
+  defaultConfig
+};

package/src/modules/fileExplorer/middleware.js

@@ -0,0 +1,92 @@
+/**
+ * File Explorer Middleware
+ * Contains middleware functions specific to file explorer operations
+ */
+
+/**
+ * Validate path parameter middleware
+ * @param {import('express').Request} req 
+ * @param {import('express').Response} res 
+ * @param {import('express').NextFunction} next 
+ */
+export function validatePath(req, res, next) {
+  const { path } = req.query;
+  
+  if (path && typeof path !== 'string') {
+    return res.status(400).json({
+      success: false,
+      error: 'Path parameter must be a string'
+    });
+  }
+  
+  next();
+}
+
+/**
+ * Rate limiting middleware for file operations
+ * Prevents excessive file system requests
+ * @param {number} maxRequests - Max requests per window
+ * @param {number} windowMs - Time window in milliseconds
+ */
+export function createRateLimit(maxRequests = 100, windowMs = 60000) {
+  const requests = new Map();
+  
+  return (req, res, next) => {
+    const clientIp = req.ip || req.connection.remoteAddress || 'unknown';
+    const now = Date.now();
+    const windowStart = now - windowMs;
+    
+    // Get or create request history for this IP
+    if (!requests.has(clientIp)) {
+      requests.set(clientIp, []);
+    }
+    
+    const clientRequests = requests.get(clientIp);
+    
+    // Remove old requests outside the window
+    const validRequests = clientRequests.filter(timestamp => timestamp > windowStart);
+    requests.set(clientIp, validRequests);
+    
+    // Check if limit exceeded
+    if (validRequests.length >= maxRequests) {
+      return res.status(429).json({
+        success: false,
+        error: 'Too many requests',
+        retryAfter: Math.ceil(windowMs / 1000)
+      });
+    }
+    
+    // Add current request
+    validRequests.push(now);
+    
+    next();
+  };
+}
+
+/**
+ * Security headers middleware for file explorer
+ */
+export function securityHeaders(req, res, next) {
+  // Prevent caching of file system data
+  res.set({
+    'Cache-Control': 'no-cache, no-store, must-revalidate',
+    'Pragma': 'no-cache',
+    'Expires': '0'
+  });
+  
+  next();
+}
+
+/**
+ * Request logging middleware for file explorer
+ */
+export function requestLogger(req, res, next) {
+  const start = Date.now();
+  
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    console.log(`[FileExplorer] ${req.method} ${req.originalUrl} - ${res.statusCode} (${duration}ms)`);
+  });
+  
+  next();
+}

package/src/modules/fileExplorer/routes.js

@@ -0,0 +1,125 @@
+/**
+ * File Explorer Routes
+ * Defines all API endpoints for file system operations
+ */
+
+import express from 'express';
+import FileExplorerController from './controller.js';
+import { validatePath, createRateLimit, securityHeaders, requestLogger } from './middleware.js';
+
+/**
+ * Create file explorer router with all endpoints
+ * @param {Object} config - Configuration options for the file explorer
+ * @returns {express.Router} Configured express router
+ */
+export function createFileExplorerRouter(config = {}) {
+  const router = express.Router();
+  const controller = new FileExplorerController(config);
+  
+  // Apply middleware to all routes
+  router.use(requestLogger);
+  router.use(securityHeaders);
+  router.use(createRateLimit(100, 60000)); // 100 requests per minute
+
+  // Health check endpoint
+  router.get('/health', (req, res) => {
+    const result = controller.healthCheck();
+    res.json(result);
+  });
+
+  // Get current working directory
+  router.get('/cwd', (req, res) => {
+    const result = controller.getCurrentWorkingDirectory();
+    res.json(result);
+  });
+
+  // Browse directory contents
+  router.get('/browse', validatePath, async (req, res) => {
+    try {
+      const requestedPath = req.query.path;
+      const options = {
+        showHidden: req.query.showHidden === 'true'
+      };
+      
+      const result = await controller.browseDirectory(requestedPath, options);
+      
+      if (result.success) {
+        res.json(result);
+      } else {
+        const statusCode = result.error.includes('restricted') ? 403 :
+                          result.error.includes('not found') ? 404 : 400;
+        res.status(statusCode).json(result);
+      }
+    } catch (error) {
+      res.status(500).json({
+        success: false,
+        error: 'Internal server error'
+      });
+    }
+  });
+
+  // Get file information
+  router.get('/file-info', validatePath, async (req, res) => {
+    try {
+      const filePath = req.query.path;
+      const result = await controller.getFileInfo(filePath);
+      
+      if (result.success) {
+        res.json(result);
+      } else {
+        const statusCode = result.error.includes('not found') ? 404 : 400;
+        res.status(statusCode).json(result);
+      }
+    } catch (error) {
+      res.status(500).json({
+        success: false,
+        error: 'Internal server error'
+      });
+    }
+  });
+
+  // Create directory
+  router.post('/mkdir', express.json(), async (req, res) => {
+    try {
+      const { path: dirPath, recursive = false } = req.body;
+      
+      if (!dirPath) {
+        return res.status(400).json({
+          success: false,
+          error: 'Directory path is required'
+        });
+      }
+      
+      const result = await controller.createDirectory(dirPath, { recursive });
+      
+      if (result.success) {
+        res.json(result);
+      } else {
+        const statusCode = result.code === 'EEXIST' ? 409 : 400;
+        res.status(statusCode).json(result);
+      }
+    } catch (error) {
+      res.status(500).json({
+        success: false,
+        error: 'Internal server error'
+      });
+    }
+  });
+
+  return router;
+}
+
+/**
+ * Default configuration for file explorer
+ */
+export const defaultConfig = {
+  showHidden: false,
+  allowedExtensions: [], // Empty = all extensions
+  maxDepth: 50,
+  restrictedPaths: [
+    // Add system paths that should be restricted
+    // Example: '/etc', '/var', '/usr/bin'
+  ]
+};
+
+export default createFileExplorerRouter;

package/src/modules/fileExplorer/types.js

@@ -0,0 +1,44 @@
+/**
+ * File Explorer Module Types
+ * Defines types and interfaces for file system operations
+ */
+
+/**
+ * @typedef {Object} FileItem
+ * @property {string} name - File or directory name
+ * @property {string} path - Full absolute path
+ * @property {'file'|'directory'} type - Item type
+ * @property {number} [size] - File size in bytes (files only)
+ * @property {Date} [lastModified] - Last modification date
+ * @property {string} [extension] - File extension (files only)
+ */
+
+/**
+ * @typedef {Object} BrowseResponse
+ * @property {string} currentPath - Current directory path
+ * @property {string} parentPath - Parent directory path
+ * @property {FileItem[]} items - Directory contents
+ * @property {number} totalItems - Total number of items
+ * @property {number} directories - Number of directories
+ * @property {number} files - Number of files
+ */
+
+/**
+ * @typedef {Object} ApiResponse
+ * @property {boolean} success - Operation success status
+ * @property {*} [data] - Response data
+ * @property {string} [error] - Error message if failed
+ * @property {string} [code] - Error code if applicable
+ */
+
+/**
+ * @typedef {Object} FileExplorerConfig
+ * @property {boolean} showHidden - Show hidden files/directories
+ * @property {string[]} allowedExtensions - Allowed file extensions (empty = all)
+ * @property {number} maxDepth - Maximum directory traversal depth
+ * @property {string[]} restrictedPaths - Paths that cannot be accessed
+ */
+
+export {
+  // Export types as JSDoc comments for runtime usage
+};