Local & Remote File Manager

A comprehensive Node.js library and CLI for local and remote file management with advanced features including real-time file watching, compression/decompression, secure temporary file sharing via tunneling, S3-compatible object storage, and remote file operations over SSH/SFTP.

Built on top of three published @kadi.build packages, this module provides a unified, high-level API for everything from basic CRUD to serving container registries with auto-shutdown.

🌟 Features

• 📁 Local File Management — Full CRUD for files and folders with path normalization, search, and batch operations
• 🌍 Remote File Management — SSH/SFTP-based remote file operations (upload, download, list, delete) via RemoteProvider
• 👁️ Real-time File Watching — Monitor file and directory changes with event filtering and callbacks
• 🗜️ Advanced Compression — ZIP and TAR.GZ with multiple compression levels and progress tracking
• 🌐 Secure File Sharing — Temporary URL generation with 6 tunnel providers (KĀDI, ngrok, Serveo, LocalTunnel, Pinggy, localhost.run)
• 🌐 HTTP Server Provider — HTTP server management with static file serving and tunnel integration
• ⚡ Enhanced File Streaming — Range requests, MIME detection, ETag generation, and progress tracking
• 🔐 S3-Compatible Object Storage — Full S3 endpoints with authentication, bucket mapping, and analytics
• � HTTP Extensibility — Middleware chain and custom route registration on the S3 server for layering protocols (e.g. Docker Registry v2) on top of S3
• �📊 Real-Time Monitoring — Live dashboard with download progress, server stats, and auto-shutdown countdown
• 🔄 Auto-Shutdown — Intelligent shutdown on download completion, idle timeout, or manual trigger
• 📢 Event Notifications — Console, file, and webhook notification channels
• 🖥️ Production-Ready CLI — Complete command-line interface for all features
• 📦 Dual Module Support — Full CommonJS and ES Modules compatibility
• 🧪 Comprehensive Testing — 380+ automated tests across 18 test suites

📋 Table of Contents

• Architecture
• Installation
• Quick Start
• CLI Usage
• Library Usage
• Remote File Management
• S3-Compatible File Server
• Tunneling & File Sharing
• Testing
• API Reference
• Exports
• Configuration
• Contributing

🏗️ Architecture

This module is a thin orchestration layer that delegates to three published @kadi.build npm packages:

| Package | Purpose | |---------|---------| | @kadi.build/file-manager | Core file management — LocalRemoteManager, ConfigManager, LocalProvider, RemoteProvider, WatchProvider, CompressionProvider | | @kadi.build/tunnel-services | Tunnel providers — KĀDI, ngrok, Serveo, LocalTunnel, Pinggy, localhost.run with automatic failover | | @kadi.build/file-sharing | HTTP serving & S3 — FileSharingServer, S3Server, HttpServerProvider, file streaming, monitoring, auto-shutdown |

┌─────────────────────────────────────────────────────────────┐
│           @kadi.build/local-remote-file-manager-ability     │
│                                                             │
│   lib.js / lib.mjs  ←  Unified API + backward-compat shims │
│   index.js          ←  CLI (commander.js)                   │
├─────────────────────────────────────────────────────────────┤
│  @kadi.build/file-manager   │  @kadi.build/file-sharing     │
│  • LocalRemoteManager       │  • FileSharingServer           │
│  • ConfigManager            │  • S3Server / S3HttpServer     │
│  • LocalProvider            │  • HttpServerProvider          │
│  • RemoteProvider (SSH)     │  • FileStreamingUtils          │
│  • WatchProvider            │  • DownloadTracker/Monitor     │
│  • CompressionProvider      │  • ShutdownManager             │
│                             │  • MonitoringDashboard         │
├─────────────────────────────┤  • EventNotifier               │
│  @kadi.build/tunnel-services│                                │
│  • TunnelManager            │                                │
│  • KadiTunnelService        │                                │
│  • NgrokTunnelService       │                                │
│  • ServeoTunnelService      │                                │
│  • LocalTunnelService       │                                │
│  • PinggyTunnelService      │                                │
│  • LocalhostRunService      │                                │
└─────────────────────────────┴────────────────────────────────┘

🚀 Installation

As a Library

npm install @kadi.build/local-remote-file-manager-ability

From Source (CLI + Development)

git clone <repository-url>
cd local-remote-file-manager-ability
npm install

Requirements

• Node.js ≥ 18.0.0
• For tunnel services: set NGROK_AUTH_TOKEN and/or KADI_TUNNEL_TOKEN in a .env file

⚡ Quick Start

ES Modules (Recommended)

// Default import — LocalRemoteManager constructor
import LocalRemoteManager from '@kadi.build/local-remote-file-manager-ability';

// Named imports
import {
  createManager,
  createS3Server,
  compressFile,
  watchDirectory,
  ConfigManager,
  S3HttpServer,
  RemoteProvider,
  TunnelManager
} from '@kadi.build/local-remote-file-manager-ability';

CommonJS

const {
  createManager,
  createS3Server,
  compressFile,
  watchDirectory,
  LocalRemoteManager,
  ConfigManager,
  RemoteProvider
} = await import('@kadi.build/local-remote-file-manager-ability');

Minimal Example

import { createManager, compressFile } from '@kadi.build/local-remote-file-manager-ability';

// Create a manager with default config
const manager = await createManager();

// Local file operations
const local = manager.getProvider('local');
const files = await local.list('./my-directory');

// Compression
await compressFile('./my-folder', './archive.zip');

// File watching
const watcher = await manager.startWatching('./watched-folder', { recursive: true });

📖 See USAGE.md for complete examples and INTEGRATION-EXAMPLE.md for real-world integration patterns.

💻 CLI Usage

System Commands

node index.js --help                   # Show all commands
node index.js test                     # Test all providers
node index.js test --provider local    # Test specific provider
node index.js validate                 # Validate configuration
node index.js info                     # Show system information

File Operations

# Upload/copy
node index.js upload --file document.pdf --target ./uploads/document.pdf
node index.js copy --source ./file.pdf --target ./backup/file.pdf

# Download
node index.js download --source ./uploads/doc.pdf --target ./downloads/

# Move / rename / delete
node index.js move --source ./file.pdf --target ./archive/file.pdf
node index.js rename --file ./old.pdf --name new.pdf
node index.js delete --file ./old-file.pdf --yes

# List & search
node index.js list --directory ./uploads --recursive
node index.js search --query "*.pdf" --directory ./uploads

# Folder operations
node index.js mkdir --directory ./new-folder
node index.js ls-folders --directory ./uploads
node index.js rmdir --directory ./old-folder --recursive --yes

File Watching

node index.js watch ./documents                    # Watch directory
node index.js watch ./file.txt --no-recursive      # Watch single file
node index.js watch ./project --events add,change  # Filter events
node index.js watch-list --verbose                 # List active watchers
node index.js watch-stop --all                     # Stop all watchers

Compression

node index.js compress --file ./folder --output ./archive.zip
node index.js compress --file ./data --output ./backup.tar.gz --format tar.gz --level 9
node index.js decompress --file ./archive.zip --directory ./extracted/ --overwrite
node index.js compress-batch --directory ./files --output ./archives/

File Sharing & Tunneling

node index.js share ./document.pdf                 # Default 1h expiration
node index.js share ./folder --expires 30m         # 30 minutes
node index.js share ./file.zip --expires 2h        # 2 hours
node index.js tunnel-status                        # Show active tunnels
node index.js tunnel-cleanup                       # Clean up expired tunnels

S3-Compatible File Server

# Basic S3 server
node index.js serve-s3 ./storage --port 5000 --auth

# With bucket mapping
node index.js serve-s3 ./storage \
  --bucket containers:./storage/containers \
  --bucket images:./storage/images \
  --port 9000 --auth

# With tunnel (public access)
node index.js serve-s3 ./content --port 8000 --tunnel --tunnel-service ngrok

# With auto-shutdown and monitoring
node index.js serve-s3 ./data --port 7000 \
  --auto-shutdown --shutdown-delay 30000 \
  --monitor --interactive

# Server management
node index.js server-status
node index.js server-stop --all
node index.js server-cleanup

Container Registry Use Case

# Set up S3-compatible container registry
node index.js serve-s3 ./container-storage \
  --bucket containers:./container-storage/containers \
  --bucket registry:./container-storage/registry \
  --port 9000 --auto-shutdown --monitor \
  --name container-registry

# Access containers at: http://localhost:9000/containers/<filename>
# Server auto-shuts down after all downloads complete

See Container Registry Demo for complete documentation.

NPM Scripts

# Testing
npm test                    # Run local operations tests
npm run test:all            # Run all test suites sequentially
npm run test:cli            # CLI integration tests
npm run test:s3             # S3 server tests
npm run test:tunnel         # Tunnel tests
npm run test:monitor        # Auto-shutdown & monitoring

# Demos
npm run demo:basic          # Basic operations demo
npm run demo:watch          # File watching demo
npm run demo:compression    # Compression demo
npm run demo:tunnel         # File sharing demo
npm run demo:cli            # CLI integration demo
npm run demo:container-registry  # Container registry demo

# Server shortcuts
npm run serve-s3            # Start S3 server on port 5000
npm run server-status       # Check server status
npm run server-stop         # Stop all servers

📚 Library Usage

File Manager with Providers

import { LocalRemoteManager, ConfigManager } from '@kadi.build/local-remote-file-manager-ability';

const config = new ConfigManager();
await config.load();
const manager = new LocalRemoteManager(config);

// Local file operations
const local = manager.getProvider('local');
await local.copy('./source.txt', './dest.txt');
const files = await local.list('./my-dir');
const info = await local.getInfo('./file.txt');

// Compression
const compression = manager.getCompressionProvider();
await compression.compress('./folder', './archive.zip', { level: 9 });
await compression.decompress('./archive.zip', './output/');

// File watching
await manager.startWatching('./documents', {
  recursive: true,
  events: ['add', 'change', 'unlink']
});
manager.on('fileEvent', (data) => console.log('Change:', data.type, data.path));

S3-Compatible Server

import { createS3Server, S3HttpServer } from '@kadi.build/local-remote-file-manager-ability';

// Quick factory
const server = createS3Server({
  port: 5000,
  rootDirectory: './storage',
  bucketMapping: new Map([['public', './public-files']]),
  authentication: { enabled: true, tempCredentials: true },
  autoShutdown: { enabled: true, timeout: 3600000 }
});

await server.start();

// Or full control with S3HttpServer
const s3 = new S3HttpServer({
  port: 9000,
  serverName: 'container-registry',
  rootDirectory: './containers',
  enableAutoShutdown: true,
  completionShutdownDelay: 30000,
  enableRealTimeMonitoring: true,
  bucketMapping: new Map([
    ['containers', 'container-files'],
    ['registry', 'registry-data']
  ])
});

const result = await s3.start();
console.log(`S3 server: ${result.localUrl}`);
console.log(`Server ID: ${result.serverId}`);

// Generate temporary credentials
const creds = s3.generateTemporaryCredentials({ ttl: 3600 });
console.log(`Access Key: ${creds.accessKey}`);
console.log(`Expires: ${creds.expiresAt} (${creds.expiry})`); // both formats

// Validate incoming requests
const authResult = s3.validateAuthentication(incomingReq);
if (authResult.success) {
  console.log(`Authenticated as: ${authResult.user.accessKey}`);
}

// Remove a bucket programmatically
await s3.removeBucket('old-container');

Middleware & Custom Routes (Extensibility)

The S3HttpServer supports injecting middleware and custom HTTP routes into the S3 server's request pipeline. This is used by higher-level packages (e.g. container-registry-ability) to layer protocols like Docker Registry v2 on top of the S3 endpoints.

import { createS3Server } from '@kadi.build/local-remote-file-manager-ability';

const server = createS3Server({ port: 9000, rootDirectory: './storage', enableAuth: true });
const info = await server.start();

// Add authentication middleware (runs before S3 auth)
server.httpProvider.addMiddleware('ignored-server-id', 'myAuth', (req, res, next) => {
  if (req.url.startsWith('/v2') && !req.headers.authorization) {
    res.writeHead(401, { 'WWW-Authenticate': 'Basic realm="Registry"' });
    return res.end('Unauthorized');
  }
  // Validate against S3 credentials
  const result = server.validateAuthentication(req);
  if (!result.success) {
    res.writeHead(401);
    return res.end(result.error);
  }
  req.user = result.user;
  next();
}, { priority: 10 });

// Register custom routes with Express-style :param patterns
server.httpProvider.addCustomRoute('ignored-server-id', 'GET', '/v2/', (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ status: 'ok' }));
}, { priority: 5 });

server.httpProvider.addCustomRoute('ignored-server-id', 'GET', '/v2/:name/manifests/:ref', (req, res) => {
  console.log(req.params); // { name: 'myimage', ref: 'latest' }
  // ... serve manifest
}, { priority: 5 });

// List and manage registered middleware/routes
console.log(server.httpProvider.getMiddleware());    // [{ name: 'myAuth', priority: 10 }]
console.log(server.httpProvider.getCustomRoutes());  // [{ method: 'GET', path: '/v2/', priority: 5 }, ...]

// Remove when done
server.httpProvider.removeMiddleware('ignored-server-id', 'myAuth');
server.httpProvider.removeCustomRoute('ignored-server-id', 'GET', '/v2/');

Note: The first argument (serverId) in addMiddleware / addCustomRoute is accepted for backward compatibility but ignored — each S3HttpServer is a single server instance.

HTTP Server with Tunnel

import { LocalRemoteManager } from '@kadi.build/local-remote-file-manager-ability';

const manager = new LocalRemoteManager();

const serverInfo = await manager.createTunneledServer({
  port: 3000,
  rootDirectory: './public-files',
  tunnelService: 'serveo'
});

console.log(`Local:  http://localhost:${serverInfo.port}`);
console.log(`Public: ${serverInfo.tunnelUrl}`);

Real-Time Monitoring

import { MonitoringDashboard, DownloadMonitor } from '@kadi.build/local-remote-file-manager-ability';

const dashboard = new MonitoringDashboard({
  updateInterval: 1000,
  showServerStats: true,
  showDownloadProgress: true,
  showActiveDownloads: true
});

dashboard.connectToServer(s3Server);
dashboard.start();

Enhanced File Streaming

import { FileStreamingUtils, DownloadTracker } from '@kadi.build/local-remote-file-manager-ability';

const fileInfo = await FileStreamingUtils.getFileInfo('./large-file.bin');
const headers = FileStreamingUtils.generateResponseHeaders(fileInfo);
const tracker = new DownloadTracker(fileInfo.size);

const stream = await FileStreamingUtils.createReadStream('./large-file.bin');
stream.on('data', (chunk) => {
  tracker.updateProgress(chunk.length);
  console.log(`Progress: ${tracker.getProgress().percentage}%`);
});

🌍 Remote File Management

The RemoteProvider enables SSH/SFTP-based remote file operations:

import { RemoteProvider } from '@kadi.build/local-remote-file-manager-ability';

const remote = new RemoteProvider({
  host: 'myserver.example.com',
  port: 22,
  username: 'deploy',
  privateKey: '/path/to/key'
  // or: password: 'secret'
});

await remote.connect();

// Remote file operations
const files = await remote.list('/var/www/html');
await remote.upload('./local-file.txt', '/remote/path/file.txt');
await remote.download('/remote/path/file.txt', './local-copy.txt');
await remote.delete('/remote/path/old-file.txt');
const info = await remote.getInfo('/remote/path/file.txt');

await remote.disconnect();

The RemoteProvider is also accessible through the manager:

const manager = await createManager({
  remote: {
    host: 'myserver.example.com',
    username: 'deploy',
    privateKey: '/path/to/key'
  }
});

const remote = manager.getProvider('remote');
await remote.list('/var/www/');

🌐 Tunneling & File Sharing

Supported Tunnel Providers

| Provider | Auth Required | Notes | |----------|--------------|-------| | KĀDI (default) | KADI_TUNNEL_TOKEN | Primary service with custom domains, WSS transport (default) | | ngrok | NGROK_AUTH_TOKEN | Popular, stable, free tier | | Serveo | None (SSH) | Free, no signup | | LocalTunnel | None | Free, open source | | Pinggy | None (SSH) | Free tier available | | localhost.run | None (SSH) | Simple SSH-based |

WSS Transport (v1.2.0+)

The KĀDI tunnel control channel now uses WSS (WebSocket Secure) transport by default instead of direct TCP on port 7000. This resolves connection issues on enterprise and campus networks that block non-standard ports — WSS operates over port 443.

| Setting | Env Var | Values | Default | |---------|---------|--------|---------| | Transport protocol | KADI_TUNNEL_TRANSPORT | 'wss' or 'tcp' | 'wss' | | WSS gateway host | KADI_TUNNEL_WSS_HOST | hostname string | — |

To fall back to the legacy TCP transport, set KADI_TUNNEL_TRANSPORT=tcp.

Environment Variables & Configuration

As of v0.2.3, tunnel secrets are resolved via the vault/config.yml pattern (see @kadi.build/tunnel-services for details). Place a config.yml in your project root:

tunnel:
  server_addr: broker.kadi.build
  tunnel_domain: tunnel.kadi.build
  server_port: 7000
  ssh_port: 2200
  mode: frpc
  transport: wss
  wss_control_host: tunnel-control.kadi.build
  agent_id: kadi

Store tokens in the encrypted vault:

kadi secret set -v tunnel KADI_TUNNEL_TOKEN <your-token>
kadi secret set -v tunnel NGROK_AUTH_TOKEN <your-token>

Environment variables can still be used as overrides:

| Variable | Description | |----------|-------------| | KADI_TUNNEL_TOKEN | KĀDI tunnel authentication token | | NGROK_AUTH_TOKEN | Ngrok authentication token | | KADI_TUNNEL_SERVER | Tunnel server hostname | | KADI_TUNNEL_PORT | Tunnel server port | | KADI_TUNNEL_TRANSPORT | Transport mode (wss or tcp) | | KADI_TUNNEL_WSS_HOST | WSS gateway hostname | | KADI_AGENT_ID | Agent identifier |

Legacy fallback: If no vault is found, the system walks up for a .env file automatically.

Direct Tunnel Service Access

import { TunnelManager } from '@kadi.build/local-remote-file-manager-ability';

// Or import individual services from the tunnel-services package directly:
import {
  KadiTunnelService,
  NgrokTunnelService,
  ServeoTunnelService,
  TunnelManager
} from '@kadi.build/tunnel-services';

const manager = new TunnelManager({
  service: 'kadi',
  autoFallback: true,
  fallbackServices: ['ngrok', 'serveo', 'localtunnel']
});

const tunnel = await manager.connect({ port: 3000 });
console.log(`Tunnel URL: ${tunnel.url}`);

🧪 Testing

Run All Tests

npm run test:all

Individual Test Suites

npm run test:local              # Local file operations
npm run test:watch              # File watching
npm run test:compression        # Compression/decompression
npm run test:tunnel             # Tunneling & sharing
npm run test:tunnel:kadi        # KĀDI tunnel unit tests
npm run test:tunnel:ngrok-unit  # ngrok tunnel unit tests
npm run test:tunnel:all         # All tunnel services (requires tokens)
npm run test:http               # HTTP server provider
npm run test:streaming          # File streaming
npm run test:s3                 # S3-compatible storage
npm run test:monitor            # Auto-shutdown & monitoring
npm run test:cli                # CLI integration
npm run test:exports            # Library exports verification

Test Results

| Test Suite | Tests | Status | |------------|-------|--------| | Local Operations | 33 | ✅ Pass | | File Watching | 31 | ✅ Pass | | Compression | 42 | ✅ Pass | | Tunneling & Sharing | 10 | ✅ Pass | | Tunnel Provider Integration | 33 | ✅ Pass | | KĀDI Tunnel Unit | 16 | ✅ Pass | | ngrok Tunnel Unit | 16 | ✅ Pass | | HTTP Server Provider | 57 | ✅ Pass | | File Streaming | 12 | ✅ Pass | | S3 Complete | 42 | ✅ Pass | | Auto-Shutdown & Monitoring | 37 | ✅ Pass | | CLI Integration | 16 | ✅ Pass | | Upstream Integration (v1.1.0) | 72 | ✅ Pass | | Library Exports | ✓ | ✅ Pass | | ESM Imports | 8 | ✅ Pass | | CommonJS Imports | 14 | ✅ Pass | | ngrok Integration | 6 | ✅ Pass | | Total | 450+ | ✅ All Pass |

📖 API Reference

LocalRemoteManager

The main orchestrator class that manages all providers.

Core File Operations

| Method | Description | |--------|-------------| | uploadFile(source, target) | Copy file to target location | | downloadFile(source, local) | Download/copy a file | | getFileInfo(path) | Get file metadata | | listFiles(dir, options?) | List files (recursive, filtering) | | deleteFile(path) | Delete a file | | copyFile(source, dest) | Copy a file | | moveFile(source, dest) | Move a file | | renameFile(path, newName) | Rename a file | | searchFiles(pattern, options?) | Search by name pattern |

Folder Operations

| Method | Description | |--------|-------------| | createFolder(path) | Create directory (recursive) | | listFolders(dir) | List subdirectories | | deleteFolder(path, recursive?) | Delete a folder | | renameFolder(path, newName) | Rename a folder | | copyFolder(source, dest) | Copy folder structure | | moveFolder(source, dest) | Move folder structure | | getFolderInfo(path) | Get folder metadata |

File Watching

| Method | Description | |--------|-------------| | startWatching(path, options?) | Start monitoring changes | | stopWatching(watchId) | Stop a watcher | | stopAllWatching() | Stop all watchers | | listActiveWatchers() | Get active watchers | | getWatcherInfo(id) | Get watcher details | | getWatchingStatus() | Get system status |

Compression

| Method | Description | |--------|-------------| | compressFile(input, output, options?) | Compress file/directory | | decompressFile(archive, outDir, options?) | Extract archive | | compressMultipleFiles(files, outDir, options?) | Batch compress | | decompressMultipleFiles(archives, outDir, options?) | Batch extract | | getCompressionStatus() | System status |

Tunneling & File Sharing

| Method | Description | |--------|-------------| | createTunnel(options) | Create tunnel connection | | destroyTunnel(tunnelId) | Destroy tunnel | | createTemporaryUrl(filePath, options?) | Generate shareable URL | | revokeTemporaryUrl(urlId) | Revoke shared URL | | listActiveUrls() | List active URLs | | getTunnelStatus() | Tunnel system status |

HTTP Server

| Method | Description | |--------|-------------| | createHttpServer(options) | Create HTTP file server | | createTunneledServer(options) | Server + automatic tunnel | | addCustomRoute(serverId, method, path, handler, options?) | Add custom route | | stopServer(serverId) | Stop server | | stopAllServers() | Stop all servers | | getServerStatus(serverId) | Server status |

S3 Object Storage (S3HttpServer)

| Method | Description | |--------|-------------| | start() | Start S3 server. Returns { port, url, localUrl, tunnelUrl, serverId, startTime, … } | | stop() | Stop S3 server | | isRunning() | Check if running | | getStatus() | Server status | | getServerInfo() | Server metadata | | generateTemporaryCredentials(opts?) | Generate temp AWS-style credentials. Returns { accessKey, secretKey, expiresAt, expiry } | | validateAuthentication(req) | Validate a request's credentials. Returns { success, user?, error? } | | removeBucket(name) | Programmatically delete a bucket directory (idempotent) | | serverId | Stable server identifier (e.g. 'kadi-s3-9000') | | httpProvider.addMiddleware(serverId, name, handler, opts?) | Register middleware into the S3 request pipeline | | httpProvider.removeMiddleware(serverId, name) | Remove named middleware | | httpProvider.getMiddleware() | List registered middleware | | httpProvider.addCustomRoute(serverId, method, path, handler, opts?) | Register a custom HTTP route (supports :param patterns) | | httpProvider.removeCustomRoute(serverId, method, path) | Remove a custom route | | httpProvider.getCustomRoutes() | List registered routes | | httpServer | Raw HttpServerProvider instance | | s3Server | Raw S3Server instance | | tunnelManager | TunnelManager instance | | downloadMonitor | DownloadMonitor instance |

Auto-Shutdown & Monitoring

| Method | Description | |--------|-------------| | enableAutoShutdown(options) | Enable with configurable triggers | | scheduleShutdown(trigger, delay) | Manual shutdown schedule | | cancelScheduledShutdown() | Cancel scheduled shutdown | | startMonitoringDashboard(options) | Start real-time dashboard | | stopMonitoringDashboard() | Stop dashboard | | getMonitoringData() | Current monitoring snapshot |

Provider Management

| Method | Description | |--------|-------------| | getProvider(name) | Get provider ('local', 'remote', 'watch', 'compression') | | testConnection(provider) | Test provider connectivity | | validateProvider(provider) | Validate config | | getSystemInfo() | System information | | shutdown() | Graceful shutdown |

Event System

LocalRemoteManager extends EventEmitter:

| Event | Description | |-------|-------------| | fileEvent | File system changes | | compressionProgress | Compression progress | | tunnelProgress | Tunnel creation progress | | urlCreated / urlRevoked | URL lifecycle | | downloadStarted / downloadCompleted / downloadFailed | Download lifecycle | | allDownloadsComplete | All expected downloads done | | shutdownScheduled / shutdownWarning / shutdownCancelled | Shutdown lifecycle | | monitoringEnabled / dashboardUpdated | Monitoring events | | serverStarted / serverStopped / serverError | S3HttpServer lifecycle | | tunnelConnected / tunnelError | S3HttpServer tunnel events |

Error Handling

All methods throw structured errors with:

• code — Error code (ENOENT, EACCES, etc.)
• message — Human-readable description
• path — Related file/directory path
• provider — Provider name that generated the error

📦 Exports

All exports are available as both ESM named exports and CJS properties:

Classes

| Export | Description | |--------|-------------| | LocalRemoteManager | Main orchestrator | | ConfigManager | Configuration management | | S3HttpServer | S3-compatible HTTP server | | LocalProvider | Local file operations | | RemoteProvider | SSH/SFTP remote operations | | WatchProvider | File watching | | CompressionProvider | Compression/decompression | | TunnelProvider | Tunnel management (compat wrapper) | | HttpServerProvider | HTTP server management (compat wrapper) | | FileSharingServer | Direct package re-export | | S3Server | Direct package re-export | | TunnelManager | Direct package re-export | | FileStreamingUtils | Streaming utilities | | FileStreamer | File streaming class | | DownloadTracker | Download progress tracker | | DownloadMonitor | Download event monitor | | ShutdownManager | Auto-shutdown controller | | MonitoringDashboard | Real-time dashboard | | EventNotifier | Event notification system | | LocalRemoteCLI | CLI class (from index.js) |

Factory & Convenience Functions

| Export | Description | |--------|-------------| | createManager(config?) | Create configured manager instance | | createS3Server(options) | Create S3 server | | createHttpServer(options) | Create HTTP server | | compressFile(input, output) | Quick compression | | decompressFile(archive, dir) | Quick extraction | | watchDirectory(path) | Quick watch setup |

Default Export

• ESM (lib.mjs): LocalRemoteManager constructor
• CJS (lib.js): Namespace object containing all exports

⚙️ Configuration

Package Exports Map

{
  "exports": {
    ".": {
      "types": "./lib.d.ts",
      "import": "./lib.mjs",
      "require": "./lib.js"
    },
    "./cli": "./index.js"
  }
}

Dependencies

| Package | Version | Purpose | |---------|---------|---------| | @kadi.build/file-manager | ^1.0.0 | Core file management | | @kadi.build/tunnel-services | ^1.0.2 | Tunnel providers | | @kadi.build/file-sharing | ^1.1.0 | HTTP serving, S3, middleware & custom routes | | chalk | ^4.1.2 | Terminal colors | | commander | ^11.1.0 | CLI framework | | fs-extra | ^11.1.1 | Enhanced fs operations | | glob | ^10.4.5 | File pattern matching | | ora | ^5.4.1 | Terminal spinners |

📖 Additional Documentation

• USAGE.md — Detailed usage examples
• INTEGRATION-EXAMPLE.md — Real-world integration patterns
• Container Registry Demo — Container serving example

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Run tests (npm run test:all)
4. Commit changes (git commit -am 'Add feature')
5. Push to branch (git push origin feature/my-feature)
6. Create a Pull Request

📄 License

MIT © Corey Clark