npm package: @kadi.build/local-remote-file-manager-ability
Description: Local & Remote File Management System with S3-compatible container registry, HTTP server provider, file streaming, comprehensive tunnel services (kadi, ngrok, serveo, localtunnel, localhost.run, pinggy), and comprehensive testing suite
Author: Corey Clark
Latest version: 0.2.3

# 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.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)

---

## 🌟 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](#architecture)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Usage](#cli-usage)
- [Library Usage](#library-usage)
- [Remote File Management](#remote-file-management)
- [S3-Compatible File Server](#s3-compatible-file-server)
- [Tunneling & File Sharing](#tunneling--file-sharing)
- [Testing](#testing)
- [API Reference](#api-reference)
- [Exports](#exports)
- [Configuration](#configuration)
- [Contributing](#contributing)

---

## 🏗️ Architecture

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

| Package | Purpose |
|---------|---------|
| [`@kadi.build/file-manager`](https://www.npmjs.com/package/@kadi.build/file-manager) | Core file management — `LocalRemoteManager`, `ConfigManager`, `LocalProvider`, `RemoteProvider`, `WatchProvider`, `CompressionProvider` |
| [`@kadi.build/tunnel-services`](https://www.npmjs.com/package/@kadi.build/tunnel-services) | Tunnel providers — KĀDI, ngrok, Serveo, LocalTunnel, Pinggy, localhost.run with automatic failover |
| [`@kadi.build/file-sharing`](https://www.npmjs.com/package/@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

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

### From Source (CLI + Development)

```bash
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)

```javascript
// 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

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

### Minimal Example

```javascript
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](./USAGE.md) for complete examples and [INTEGRATION-EXAMPLE.md](./INTEGRATION-EXAMPLE.md) for real-world integration patterns.**

---

## 💻 CLI Usage

### System Commands

```bash
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

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
# 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

```bash
# 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](./demos/container-registry-demo/README.md) for complete documentation.

### NPM Scripts

```bash
# 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

```javascript
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

```javascript
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.

```javascript
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

```javascript
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

```javascript
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

```javascript
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:

```javascript
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:

```javascript
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:

```yaml
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:

```bash
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

```javascript
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

```bash
npm run test:all
```

### Individual Test Suites

```bash
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

```json
{
  "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](./USAGE.md) — Detailed usage examples
- [INTEGRATION-EXAMPLE.md](./INTEGRATION-EXAMPLE.md) — Real-world integration patterns
- [Container Registry Demo](./demos/container-registry-demo/README.md) — 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