gib-runs 2.3.2 → 2.3.5

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.3.5] - 2026-02-12
+
+### Added
+- 🔄 **Environment Variable Replacement** - Automatic replacement of `${VAR_NAME}` patterns in HTML files
+  - Reads from `.env` file automatically
+  - Works with all environment variables (APP_NAME, API_KEY, etc)
+  - No configuration needed
+
+## [2.3.4] - 2026-02-12
+
+### Added - New Features 🎉
+- 🔁 **Auto-Restart on Crash** - Server automatically restarts on unexpected errors
+  - Use `--auto-restart` flag to enable
+  - Attempts up to 5 restarts before giving up
+  - Resilient mode for production-like development
+  - Displays restart attempt count in console
+- 📤 **File Upload Endpoint** - Built-in file upload support for development
+  - Use `--enable-upload` flag to enable
+  - POST files to `/upload` endpoint
+  - 10MB file size limit
+  - Files saved to `./uploads` directory
+  - Returns JSON response with file details
+- 💚 **Health Check Endpoint** - Monitor server health and statistics
+  - Enabled by default (use `--no-health` to disable)
+  - Access via `GET /health` or `GET /_health`
+  - Returns JSON with uptime, memory usage, request count, reload count
+  - System information (CPU, memory, platform)
+  - Perfect for monitoring and debugging
+- 📝 **Request Logging to File** - Log all requests to file for debugging
+  - Use `--log-to-file` flag to enable
+  - Logs saved to `gib-runs.log` in project root
+  - JSON format with timestamp, method, URL, IP, user-agent, status, duration
+  - Automatic log rotation at 10MB
+  - Old logs backed up with timestamp
+- 🎨 **Custom Error Pages** - Beautiful, informative error pages
+  - Enabled by default (use `--no-error-page` to disable)
+  - Modern gradient design with detailed error information
+  - Shows error stack trace in development mode
+  - Covers all HTTP error codes (400, 401, 403, 404, 500, etc)
+  - Responsive design for mobile devices
+- 🌍 **Environment Variable Support** - Automatic .env file loading
+  - Automatically loads `.env` file from project root
+  - Uses dotenv package
+  - No configuration needed, just create `.env` file
+  - Perfect for API keys, database URLs, etc
+- 📡 **WebSocket Broadcasting API** - Send custom messages to all connected clients
+  - New `GibRuns.broadcast(message)` method
+  - Broadcast custom reload triggers or notifications
+  - Useful for custom build tools and integrations
+
+### Improved
+- 🔧 **Better Error Handling** - More informative error messages with stack traces
+- 📊 **Enhanced Health Monitoring** - More detailed system metrics
+- 🎯 **Middleware Architecture** - Cleaner middleware loading and organization
+- 📦 **Dependencies** - Added `dotenv` and `multer` for new features
+
+### Technical
+- Version bumped to 2.3.4
+- All existing tests passing
+- Backward compatible with all previous versions
+- New middleware files: `upload.js`, `health.js`, `logger.js`, `error-page.js`
+- Enhanced GibRuns object with `wsClients`, `autoRestart`, `restartCount` properties
+
 ## [2.3.0] - 2026-02-10
 
 ### Fixed - Critical

package/README.md

@@ -3,7 +3,7 @@
 [![license](https://img.shields.io/npm/l/gib-runs.svg)](https://github.com/levouinse/gib-runs/blob/main/LICENSE)
 [![tests](https://img.shields.io/badge/tests-32%20passing-brightgreen.svg)](https://github.com/levouinse/gib-runs)
 
-# 🚀 GIB-RUNS
+# 🚀 GIB-RUNS v2.3.5
 
 **Modern development server with live reload - Unlike some people, this actually runs on merit, not connections.**
 
@@ -61,6 +61,18 @@ The name is a playful nod to Indonesia's Vice President Gibran Rakabuming Raka,
 - 🚦 **Rate Limiting** - Protect against abuse (better protection than family connections)
 - 🌐 **Network Access** - True network binding that actually works (unlike some political promises)
 
+### New in v2.3.5 🎉
+- 🔄 **Environment Variable Replacement** - Automatic replacement of `${VAR_NAME}` in HTML files from .env
+
+### New in v2.3.5 🎉
+- 🔁 **Auto-Restart on Crash** - Automatically restart server on unexpected errors (resilient mode)
+- 📤 **File Upload Endpoint** - Built-in file upload support for development (POST to /upload)
+- 💚 **Health Check Endpoint** - Monitor server health and statistics (GET /health)
+- 📝 **Request Logging to File** - Log all requests to file for debugging (gib-runs.log)
+- 🎨 **Custom Error Pages** - Beautiful, informative error pages with stack traces
+- 🌍 **Environment Variables** - Automatic .env file loading (dotenv support)
+- 📡 **WebSocket Broadcasting** - Send custom messages to all connected clients
+
 ## 📦 Installation
 
 ### Global Installation (Recommended)
@@ -155,6 +167,11 @@ gib-runs dist --port=3000 --spa --cors --no-browser
 | `--npm-script=SCRIPT` | Run npm script (dev, start, etc) | None |
 | `--pm2` | Use PM2 process manager | `false` |
 | `--pm2-name=NAME` | PM2 app name | `gib-runs-app` |
+| `--auto-restart` | Auto-restart server on crash | `false` |
+| `--enable-upload` | Enable file upload endpoint | `false` |
+| `--no-health` | Disable health check endpoint | `false` |
+| `--log-to-file` | Log requests to file | `false` |
+| `--no-error-page` | Disable custom error pages | `false` |
 | `-v, --version` | Show version | - |
 | `-h, --help` | Show help | - |
 
@@ -372,7 +389,7 @@ gib-runs
 Network URLs are **ALWAYS shown automatically** when you start the server:
 
 ```
-🚀 GIB-RUNS v2.3.2
+🚀 GIB-RUNS v2.3.5
 "Unlike Gibran, this actually works through merit"
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   📁 Root:       /home/user/project
@@ -491,7 +508,7 @@ gib-runs --tunnel-service=tunnelto
 ### Example Output
 
 ```
-🚀 GIB-RUNS v2.3.2
+🚀 GIB-RUNS v2.3.5
 "Unlike Gibran, this actually works through merit"
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   📁 Root:       /home/user/project
@@ -621,7 +638,7 @@ pm2 list
 ### Example Output
 
 ```
-🚀 GIB-RUNS v2.3.2
+🚀 GIB-RUNS v2.3.5
 "Unlike Gibran, this actually works through merit"
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   📁 Root:       /home/user/project
@@ -648,6 +665,271 @@ pm2 list
 
 **Unlike Gibran's career, these processes run on actual merit and capability!** 🔥
 
+## 🆕 New Features in v2.3.5
+
+### Auto-Restart on Crash
+
+**Automatically restart your server when it crashes - resilient mode for development!**
+
+```bash
+# Enable auto-restart
+gib-runs --auto-restart
+
+# With other options
+gib-runs --auto-restart --port=3000 --spa
+```
+
+**How it works:**
+- Server automatically restarts on unexpected errors
+- Attempts up to 5 restarts before giving up
+- Shows restart attempt count in console
+- Perfect for unstable development environments
+- Keeps your workflow uninterrupted
+
+**Example output:**
+```
+  ✖ Server Error: ECONNRESET
+  🔄 Auto-restarting server (attempt 1/5)...
+  ✓ Server restarted successfully
+```
+
+### File Upload Endpoint
+
+**Built-in file upload support for development - no need for separate upload server!**
+
+```bash
+# Enable file upload endpoint
+gib-runs --enable-upload
+
+# Files will be saved to ./uploads directory
+```
+
+**Usage:**
+```html
+<!-- HTML Form -->
+<form action="/upload" method="POST" enctype="multipart/form-data">
+  <input type="file" name="file">
+  <button type="submit">Upload</button>
+</form>
+```
+
+```javascript
+// JavaScript Fetch API
+const formData = new FormData();
+formData.append('file', fileInput.files[0]);
+
+fetch('/upload', {
+  method: 'POST',
+  body: formData
+})
+.then(res => res.json())
+.then(data => {
+  console.log('Uploaded:', data.file);
+  // { filename: 'file-123456789.jpg', originalname: 'photo.jpg', size: 12345, path: '/path/to/uploads/...' }
+});
+```
+
+**Features:**
+- 10MB file size limit
+- Files saved to `./uploads` directory
+- Automatic directory creation
+- Unique filenames with timestamp
+- JSON response with file details
+- Error handling for invalid uploads
+
+### Health Check Endpoint
+
+**Monitor your server health and statistics - transparency in action!**
+
+```bash
+# Health check is enabled by default
+gib-runs
+
+# Disable if needed
+gib-runs --no-health
+```
+
+**Access health endpoint:**
+```bash
+# Via curl
+curl http://localhost:8080/health
+
+# Or in browser
+http://localhost:8080/health
+```
+
+**Response example:**
+```json
+{
+  "status": "healthy",
+  "uptime": 123.45,
+  "timestamp": "2026-02-12T09:00:00.000Z",
+  "server": {
+    "requests": 42,
+    "reloads": 5,
+    "memory": {
+      "rss": "45MB",
+      "heapUsed": "23MB",
+      "heapTotal": "35MB"
+    }
+  },
+  "system": {
+    "platform": "linux",
+    "arch": "x64",
+    "cpus": 8,
+    "freemem": "2048MB",
+    "totalmem": "16384MB",
+    "loadavg": [1.2, 1.5, 1.8]
+  }
+}
+```
+
+**Use cases:**
+- Monitor server performance
+- Debug memory leaks
+- Track request patterns
+- Integration with monitoring tools
+- Health checks for Docker containers
+
+### Request Logging to File
+
+**Log all requests to file for debugging - transparent and verifiable!**
+
+```bash
+# Enable file logging
+gib-runs --log-to-file
+
+# Logs saved to gib-runs.log in project root
+```
+
+**Log format (JSON):**
+```json
+{"timestamp":"2026-02-12T09:00:00.000Z","method":"GET","url":"/index.html","ip":"127.0.0.1","userAgent":"Mozilla/5.0...","status":200,"duration":"5ms"}
+{"timestamp":"2026-02-12T09:00:01.000Z","method":"GET","url":"/style.css","ip":"127.0.0.1","userAgent":"Mozilla/5.0...","status":200,"duration":"2ms"}
+```
+
+**Features:**
+- JSON format for easy parsing
+- Includes timestamp, method, URL, IP, user-agent, status, duration
+- Automatic log rotation at 10MB
+- Old logs backed up with timestamp
+- Perfect for debugging and analytics
+
+**Parse logs with jq:**
+```bash
+# Show all 404 errors
+cat gib-runs.log | jq 'select(.status == 404)'
+
+# Show slow requests (>100ms)
+cat gib-runs.log | jq 'select(.duration | tonumber > 100)'
+
+# Count requests by URL
+cat gib-runs.log | jq -r '.url' | sort | uniq -c
+```
+
+### Custom Error Pages
+
+**Beautiful, informative error pages - unlike some political errors!**
+
+```bash
+# Custom error pages enabled by default
+gib-runs
+
+# Disable if needed
+gib-runs --no-error-page
+```
+
+**Features:**
+- Modern gradient design
+- Detailed error information
+- Shows error stack trace in development mode
+- Covers all HTTP error codes (400, 401, 403, 404, 500, etc)
+- Responsive design for mobile devices
+- "Back to Home" button
+- Professional appearance
+
+**Error codes covered:**
+- 400 Bad Request
+- 401 Unauthorized
+- 403 Forbidden
+- 404 Not Found
+- 405 Method Not Allowed
+- 500 Internal Server Error
+- 502 Bad Gateway
+- 503 Service Unavailable
+
+### Environment Variables
+
+**Automatic .env file loading - no configuration needed!**
+
+```bash
+# Just create .env file in project root
+echo "API_KEY=your-secret-key" > .env
+echo "DATABASE_URL=postgres://localhost/mydb" >> .env
+
+# Start server (automatically loads .env)
+gib-runs
+```
+
+**Access in your code:**
+```javascript
+// Node.js
+const apiKey = process.env.API_KEY;
+const dbUrl = process.env.DATABASE_URL;
+
+console.log('API Key:', apiKey);
+console.log('Database:', dbUrl);
+```
+
+**Features:**
+- Automatic loading on server start
+- No configuration needed
+- Uses dotenv package
+- Perfect for API keys, database URLs, etc
+- Keeps secrets out of version control
+
+### WebSocket Broadcasting API
+
+**Send custom messages to all connected clients - programmatic control!**
+
+```javascript
+const gibRuns = require('gib-runs');
+
+// Start server
+const server = gibRuns.start({
+  port: 8080,
+  root: './public'
+});
+
+// Broadcast custom message to all clients
+gibRuns.broadcast('custom-reload');
+
+// Trigger reload from your build script
+gibRuns.broadcast('reload');
+
+// Send custom data
+gibRuns.broadcast(JSON.stringify({ type: 'notification', message: 'Build complete!' }));
+```
+
+**Use cases:**
+- Custom build tool integration
+- Trigger reload from external scripts
+- Send notifications to browser
+- Custom live reload logic
+- Integration with CI/CD pipelines
+
+**Client-side handling:**
+```javascript
+// In your HTML/JavaScript
+const ws = new WebSocket('ws://localhost:8080');
+ws.onmessage = function(event) {
+  if (event.data === 'custom-reload') {
+    console.log('Custom reload triggered!');
+    location.reload();
+  }
+};
+```
+
 ## 🐛 Troubleshooting
 
 ### No reload on changes

package/gib-run.js

@@ -140,6 +140,26 @@ for (var i = process.argv.length - 1; i >= 2; --i) {
 		opts.tunnel = true;
 		process.argv.splice(i, 1);
 	}
+	else if (arg === "--auto-restart") {
+		opts.autoRestart = true;
+		process.argv.splice(i, 1);
+	}
+	else if (arg === "--enable-upload") {
+		opts.enableUpload = true;
+		process.argv.splice(i, 1);
+	}
+	else if (arg === "--no-health") {
+		opts.enableHealth = false;
+		process.argv.splice(i, 1);
+	}
+	else if (arg === "--log-to-file") {
+		opts.logToFile = true;
+		process.argv.splice(i, 1);
+	}
+	else if (arg === "--no-error-page") {
+		opts.customErrorPage = false;
+		process.argv.splice(i, 1);
+	}
 	else if (arg.indexOf("--tunnel-service=") > -1) {
 		opts.tunnelService = arg.substring(17);
 		opts.tunnel = true;
@@ -245,7 +265,12 @@ for (var i = process.argv.length - 1; i >= 2; --i) {
 		console.log(chalk.yellow('    --exec=COMMAND         ') + chalk.gray('Run custom command'));
 		console.log(chalk.yellow('    --npm-script=SCRIPT    ') + chalk.gray('Run npm script (dev, start, etc)'));
 		console.log(chalk.yellow('    --pm2                  ') + chalk.gray('Use PM2 process manager'));
-		console.log(chalk.yellow('    --pm2-name=NAME        ') + chalk.gray('PM2 app name (default: gib-runs-app)\n'));
+		console.log(chalk.yellow('    --pm2-name=NAME        ') + chalk.gray('PM2 app name (default: gib-runs-app)'));
+		console.log(chalk.yellow('    --auto-restart         ') + chalk.gray('Auto-restart server on crash'));
+		console.log(chalk.yellow('    --enable-upload        ') + chalk.gray('Enable file upload endpoint'));
+		console.log(chalk.yellow('    --no-health            ') + chalk.gray('Disable health check endpoint'));
+		console.log(chalk.yellow('    --log-to-file          ') + chalk.gray('Log requests to file'));
+		console.log(chalk.yellow('    --no-error-page        ') + chalk.gray('Disable custom error pages\n'));
 		console.log(chalk.gray('  Examples:\n'));
 		console.log(chalk.gray('    gib-runs'));
 		console.log(chalk.gray('    gib-runs --port=3000 --verbose'));
@@ -256,7 +281,9 @@ for (var i = process.argv.length - 1; i >= 2; --i) {
 		console.log(chalk.gray('    gib-runs --npm-script=dev'));
 		console.log(chalk.gray('    gib-runs --exec="npm run build && npm start"'));
 		console.log(chalk.gray('    gib-runs --npm-script=dev --pm2 --pm2-name=my-app'));
-		console.log(chalk.gray('    gib-runs --performance --rate-limit=50\n'));
+		console.log(chalk.gray('    gib-runs --performance --rate-limit=50'));
+		console.log(chalk.gray('    gib-runs --auto-restart --enable-upload'));
+		console.log(chalk.gray('    gib-runs --log-to-file --verbose\n'));
 		process.exit();
 	}
 	else if (arg === "--test") {

package/index.js

@@ -14,7 +14,15 @@ var fs = require('fs'),
 	chokidar = require('chokidar'),
 	chalk = require('chalk');
 
+// Load environment variables from .env file
+try {
+	require('dotenv').config({ path: path.join(process.cwd(), '.env') });
+} catch (e) {
+	// dotenv not available, skip
+}
+
 var INJECTED_CODE = fs.readFileSync(path.join(__dirname, "injected.html"), "utf8");
+var packageJson = require('./package.json');
 
 var GibRuns = {
 	server: null,
@@ -24,7 +32,10 @@ var GibRuns = {
 	requestCount: 0,
 	reloadCount: 0,
 	tunnel: null,
-	processRunner: null
+	processRunner: null,
+	wsClients: [],
+	autoRestart: false,
+	restartCount: 0
 };
 
 function escape(html){
@@ -63,6 +74,12 @@ function staticServer(root) {
 			if (hasNoOrigin && (possibleExtensions.indexOf(x) > -1)) {
 				// TODO: Sync file read here is not nice, but we need to determine if the html should be injected or not
 				var contents = fs.readFileSync(filepath, "utf8");
+				
+				// Replace environment variables like ${APP_NAME}
+				contents = contents.replace(/\$\{([A-Z_]+)\}/g, function(fullMatch, varName) {
+					return process.env[varName] || fullMatch;
+				});
+				
 				for (var i = 0; i < injectCandidates.length; ++i) {
 					match = injectCandidates[i].exec(contents);
 					if (match) {
@@ -89,7 +106,12 @@ function staticServer(root) {
 				res.setHeader('Content-Length', len);
 				var originalPipe = stream.pipe;
 				stream.pipe = function(resp) {
-					originalPipe.call(stream, es.replace(new RegExp(injectTag, "i"), INJECTED_CODE + injectTag)).pipe(resp);
+					// Replace ${ENV_VAR} then inject code
+					var envReplace = es.replace(/\$\{([A-Z_]+)\}/g, function(match, varName) {
+						return process.env[varName] || match;
+					});
+					var codeInject = es.replace(new RegExp(injectTag, "i"), INJECTED_CODE + injectTag);
+					originalPipe.call(stream, envReplace).pipe(codeInject).pipe(resp);
 				};
 			}
 		}
@@ -136,6 +158,11 @@ function entryPoint(staticHandler, file) {
  * @param compression {boolean} Enable gzip compression (default: true)
  * @param qrCode {boolean} Show QR code for network URLs (default: false)
  * @param tunnel {boolean} Create public tunnel URL (default: false)
+ * @param autoRestart {boolean} Auto-restart server on crash (default: false)
+ * @param enableUpload {boolean} Enable file upload endpoint (default: false)
+ * @param enableHealth {boolean} Enable health check endpoint (default: true)
+ * @param logToFile {boolean} Log requests to file (default: false)
+ * @param customErrorPage {boolean} Use custom error pages (default: true)
  */
 GibRuns.start = function(options) {
 	options = options || {};
@@ -177,6 +204,13 @@ GibRuns.start = function(options) {
 	var usePM2 = options.pm2 || false;
 	var pm2Name = options.pm2Name || 'gib-runs-app';
 	var testMode = options.test || false;
+	var autoRestart = options.autoRestart || false;
+	var enableUpload = options.enableUpload || false;
+	var enableHealth = options.enableHealth !== false;
+	var logToFile = options.logToFile || false;
+	var customErrorPage = options.customErrorPage !== false;
+	
+	GibRuns.autoRestart = autoRestart;
 
 	if (httpsModule) {
 		try {
@@ -217,6 +251,27 @@ GibRuns.start = function(options) {
 			
 			next();
 		});
+		
+		// Add health check endpoint
+		if (enableHealth) {
+			app.use(require('./middleware/health')(GibRuns));
+		}
+		
+		// Add file upload endpoint
+		if (enableUpload) {
+			app.use(require('./middleware/upload')());
+			if (GibRuns.logLevel >= 1) {
+				console.log(chalk.cyan('  📤 File Upload: ') + chalk.green('Enabled') + chalk.gray(' (POST to /upload)'));
+			}
+		}
+		
+		// Add request logger to file
+		if (logToFile) {
+			app.use(require('./middleware/logger')({ logFile: path.join(root, 'gib-runs.log') }));
+			if (GibRuns.logLevel >= 1) {
+				console.log(chalk.cyan('  📝 File Logging: ') + chalk.green('Enabled') + chalk.gray(' (gib-runs.log)'));
+			}
+		}
 
 		// Add logger. Level 2 logs only errors
 		if (GibRuns.logLevel === 2) {
@@ -298,6 +353,11 @@ GibRuns.start = function(options) {
 		app.use(staticServerHandler) // Custom static server
 			.use(entryPoint(staticServerHandler, file))
 			.use(serveIndex(root, { icons: true }));
+		
+		// Add custom error page handler (must be last)
+		if (customErrorPage) {
+			app.use(require('./middleware/error-page')({ showStack: GibRuns.logLevel >= 2 }));
+		}
 	}
 
 	var server, protocol;
@@ -338,7 +398,17 @@ GibRuns.start = function(options) {
 			if (GibRuns.logLevel >= 3) {
 				console.error(chalk.gray('  Stack trace:'), e.stack);
 			}
-			GibRuns.shutdown();
+			
+			// Auto-restart on crash if enabled
+			if (autoRestart && GibRuns.restartCount < 5) {
+				GibRuns.restartCount++;
+				console.log(chalk.yellow('  🔄 Auto-restarting server (attempt ' + GibRuns.restartCount + '/5)...'));
+				setTimeout(function() {
+					GibRuns.start(options);
+				}, 2000);
+			} else {
+				GibRuns.shutdown();
+			}
 		}
 	});
 
@@ -353,7 +423,7 @@ GibRuns.start = function(options) {
 			// Show info about what's running
 			if (GibRuns.logLevel >= 1) {
 				console.log('\n' + chalk.cyan.bold('━'.repeat(60)));
-				console.log(chalk.cyan.bold('  🚀 GIB-RUNS') + chalk.gray(' v2.3.2'));
+				console.log(chalk.cyan.bold('  🚀 GIB-RUNS') + chalk.gray(' v' + packageJson.version));
 				console.log(chalk.gray('  "Unlike Gibran, this actually works through merit"'));
 				console.log(chalk.cyan.bold('━'.repeat(60)));
 				console.log(chalk.white('  📁 Root:       ') + chalk.yellow(root));
@@ -367,6 +437,9 @@ GibRuns.start = function(options) {
 					console.log(chalk.white('  🔄 PM2:        ') + chalk.green(' Enabled') + chalk.gray(' (process manager)'));
 				}
 				console.log(chalk.white('  🔄 Live Reload:') + chalk.green(' Enabled') + chalk.gray(' (watching for changes)'));
+				if (autoRestart) {
+					console.log(chalk.white('  🔁 Auto-Restart:') + chalk.green(' Enabled') + chalk.gray(' (resilient mode)'));
+				}
 				console.log(chalk.cyan.bold('━'.repeat(60)));
 				console.log(chalk.gray('  Press Ctrl+C to stop\n'));
 			}
@@ -443,7 +516,7 @@ GibRuns.start = function(options) {
 		// Output with beautiful formatting
 		if (GibRuns.logLevel >= 1) {
 			console.log('\n' + chalk.cyan.bold('━'.repeat(60)));
-			console.log(chalk.cyan.bold('  🚀 GIB-RUNS') + chalk.gray(' v2.3.2'));
+			console.log(chalk.cyan.bold('  🚀 GIB-RUNS') + chalk.gray(' v' + packageJson.version));
 			console.log(chalk.gray('  "Unlike Gibran, this actually works through merit"'));
 			console.log(chalk.cyan.bold('━'.repeat(60)));
 			console.log(chalk.white('  📁 Root:       ') + chalk.yellow(root));
@@ -466,6 +539,12 @@ GibRuns.start = function(options) {
 			if (https) {
 				console.log(chalk.white('  🔒 HTTPS:      ') + chalk.green(' Enabled') + chalk.gray(' (real security)'));
 			}
+			if (enableHealth) {
+				console.log(chalk.white('  💚 Health:     ') + chalk.green(' Enabled') + chalk.gray(' (GET /health)'));
+			}
+			if (autoRestart) {
+				console.log(chalk.white('  🔁 Auto-Restart:') + chalk.green(' Enabled') + chalk.gray(' (resilient mode)'));
+			}
 			console.log(chalk.cyan.bold('━'.repeat(60)));
 			console.log(chalk.gray('  Press Ctrl+C to stop'));
 			console.log(chalk.yellow('  💡 Tip: Share network URLs with your team!\n'));
@@ -540,6 +619,7 @@ GibRuns.start = function(options) {
 		};
 
 		clients.push(ws);
+		GibRuns.wsClients = clients;
 	});
 
 	var ignored = [
@@ -599,6 +679,22 @@ GibRuns.start = function(options) {
 	return server;
 };
 
+/**
+ * Broadcast custom message to all connected WebSocket clients
+ * @param {string} message - Message to broadcast
+ */
+GibRuns.broadcast = function(message) {
+	if (GibRuns.wsClients && GibRuns.wsClients.length > 0) {
+		GibRuns.wsClients.forEach(function(ws) {
+			if (ws && ws.send) {
+				ws.send(message);
+			}
+		});
+		return true;
+	}
+	return false;
+};
+
 GibRuns.shutdown = function() {
 	if (GibRuns.logLevel >= 1 && GibRuns.startTime) {
 		var uptime = ((Date.now() - GibRuns.startTime) / 1000).toFixed(2);

package/lib/tunnel.js

@@ -102,15 +102,36 @@ function startLocalTunnel(port, options) {
 				
 				tunnel.on('close', function() {
 					console.log(chalk.yellow('  ⚠ Tunnel closed'));
+					activeTunnel = null;
+					tunnelUrl = null;
+				});
+				
+				tunnel.on('error', function(err) {
+					console.error(chalk.red('  ✖ Tunnel connection error:'), err.message);
+					console.log(chalk.yellow('  ⚠ Server continues running locally'));
+					console.log(chalk.gray('  💡 Tunnel may be unstable, try alternative services:'));
+					console.log(chalk.gray('     • gib-runs --tunnel-service=cloudflared'));
+					console.log(chalk.gray('     • gib-runs --tunnel-service=ngrok --tunnel-authtoken=YOUR_TOKEN'));
+					console.log(chalk.gray('     • Or continue using local network URLs\n'));
+					
+					// Clean up tunnel reference
+					activeTunnel = null;
+					tunnelUrl = null;
 				});
 			}).catch(function(err) {
-				console.error(chalk.red('  ✖ LocalTunnel error:'), err.message);
-				console.log(chalk.yellow('  💡 Install: npm install -g localtunnel'));
+				console.error(chalk.red('  ✖ LocalTunnel failed to start:'), err.message);
+				console.log(chalk.yellow('  ⚠ Server continues running locally'));
+				console.log(chalk.gray('  💡 Possible solutions:'));
+				console.log(chalk.gray('     • Check your internet connection'));
+				console.log(chalk.gray('     • Try again later (localtunnel.me may be down)'));
+				console.log(chalk.gray('     • Use alternative: gib-runs --tunnel-service=cloudflared'));
+				console.log(chalk.gray('     • Or use local network URLs for now\n'));
 			});
 		} catch (e) {
 			console.error(chalk.red('  ✖ LocalTunnel not installed'));
 			console.log(chalk.yellow('  💡 Install: npm install -g localtunnel'));
 			console.log(chalk.gray('     Then run: gib-runs --tunnel'));
+			console.log(chalk.gray('     Server continues running locally\n'));
 		}
 	});
 }

package/middleware/error-page.js

@@ -0,0 +1,148 @@
+// Custom error pages
+// Unlike Gibran's political errors, these are properly documented and handled
+const fs = require('fs');
+const path = require('path');
+
+const errorTemplate = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>{{status}} - {{message}}</title>
+	<style>
+		* { margin: 0; padding: 0; box-sizing: border-box; }
+		body {
+			font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+			background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+			min-height: 100vh;
+			display: flex;
+			align-items: center;
+			justify-content: center;
+			padding: 20px;
+		}
+		.error-container {
+			background: white;
+			border-radius: 20px;
+			padding: 60px 40px;
+			max-width: 600px;
+			width: 100%;
+			box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+			text-align: center;
+		}
+		.error-code {
+			font-size: 120px;
+			font-weight: 900;
+			background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+			-webkit-background-clip: text;
+			-webkit-text-fill-color: transparent;
+			line-height: 1;
+			margin-bottom: 20px;
+		}
+		.error-message {
+			font-size: 24px;
+			color: #333;
+			margin-bottom: 15px;
+			font-weight: 600;
+		}
+		.error-description {
+			font-size: 16px;
+			color: #666;
+			margin-bottom: 30px;
+			line-height: 1.6;
+		}
+		.error-details {
+			background: #f5f5f5;
+			border-radius: 10px;
+			padding: 20px;
+			margin-top: 30px;
+			text-align: left;
+		}
+		.error-details pre {
+			font-family: 'Courier New', monospace;
+			font-size: 14px;
+			color: #e74c3c;
+			overflow-x: auto;
+			white-space: pre-wrap;
+			word-wrap: break-word;
+		}
+		.back-button {
+			display: inline-block;
+			padding: 15px 40px;
+			background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+			color: white;
+			text-decoration: none;
+			border-radius: 50px;
+			font-weight: 600;
+			transition: transform 0.2s;
+		}
+		.back-button:hover {
+			transform: translateY(-2px);
+		}
+		.footer {
+			margin-top: 30px;
+			font-size: 14px;
+			color: #999;
+		}
+	</style>
+</head>
+<body>
+	<div class="error-container">
+		<div class="error-code">{{status}}</div>
+		<div class="error-message">{{message}}</div>
+		<div class="error-description">{{description}}</div>
+		<a href="/" class="back-button">← Back to Home</a>
+		{{details}}
+		<div class="footer">
+			🚀 GIB-RUNS - Development Server<br>
+			<small>Unlike some careers, this error is earned, not inherited</small>
+		</div>
+	</div>
+</body>
+</html>
+`;
+
+const errorMessages = {
+	400: { message: 'Bad Request', description: 'The request could not be understood by the server.' },
+	401: { message: 'Unauthorized', description: 'Authentication is required to access this resource.' },
+	403: { message: 'Forbidden', description: 'You don\'t have permission to access this resource.' },
+	404: { message: 'Not Found', description: 'The requested resource could not be found on this server.' },
+	405: { message: 'Method Not Allowed', description: 'The request method is not supported for this resource.' },
+	500: { message: 'Internal Server Error', description: 'The server encountered an unexpected condition.' },
+	502: { message: 'Bad Gateway', description: 'The server received an invalid response from the upstream server.' },
+	503: { message: 'Service Unavailable', description: 'The server is temporarily unable to handle the request.' }
+};
+
+module.exports = function(options) {
+	options = options || {};
+	const showStack = options.showStack !== false;
+	
+	return function(err, req, res, next) {
+		if (!err) return next();
+		
+		const status = err.status || err.statusCode || 500;
+		const errorInfo = errorMessages[status] || errorMessages[500];
+		
+		let html = errorTemplate
+			.replace(/{{status}}/g, status)
+			.replace(/{{message}}/g, errorInfo.message)
+			.replace(/{{description}}/g, errorInfo.description);
+		
+		// Add error details in development
+		if (showStack && err.stack) {
+			const details = `
+				<div class="error-details">
+					<strong>Error Details:</strong>
+					<pre>${err.stack}</pre>
+				</div>
+			`;
+			html = html.replace('{{details}}', details);
+		} else {
+			html = html.replace('{{details}}', '');
+		}
+		
+		res.statusCode = status;
+		res.setHeader('Content-Type', 'text/html');
+		res.end(html);
+	};
+};

package/middleware/health.js

@@ -0,0 +1,41 @@
+// Health check endpoint
+// Unlike Gibran's political health checks, this one is transparent and honest
+const os = require('os');
+
+module.exports = function(gibRuns) {
+	return function(req, res, next) {
+		if (req.url === '/health' || req.url === '/_health') {
+			const uptime = gibRuns.startTime ? ((Date.now() - gibRuns.startTime) / 1000).toFixed(2) : 0;
+			const memUsage = process.memoryUsage();
+			
+			const health = {
+				status: 'healthy',
+				uptime: parseFloat(uptime),
+				timestamp: new Date().toISOString(),
+				server: {
+					requests: gibRuns.requestCount || 0,
+					reloads: gibRuns.reloadCount || 0,
+					memory: {
+						rss: Math.round(memUsage.rss / 1024 / 1024) + 'MB',
+						heapUsed: Math.round(memUsage.heapUsed / 1024 / 1024) + 'MB',
+						heapTotal: Math.round(memUsage.heapTotal / 1024 / 1024) + 'MB'
+					}
+				},
+				system: {
+					platform: os.platform(),
+					arch: os.arch(),
+					cpus: os.cpus().length,
+					freemem: Math.round(os.freemem() / 1024 / 1024) + 'MB',
+					totalmem: Math.round(os.totalmem() / 1024 / 1024) + 'MB',
+					loadavg: os.loadavg()
+				}
+			};
+			
+			res.statusCode = 200;
+			res.setHeader('Content-Type', 'application/json');
+			res.end(JSON.stringify(health, null, 2));
+		} else {
+			next();
+		}
+	};
+};

package/middleware/logger.js

@@ -0,0 +1,58 @@
+// Request logger to file
+// Unlike Gibran's career records, these logs are transparent and verifiable
+const fs = require('fs');
+const path = require('path');
+
+module.exports = function(options) {
+	options = options || {};
+	const logFile = options.logFile || path.join(process.cwd(), 'gib-runs.log');
+	const maxSize = options.maxSize || 10 * 1024 * 1024; // 10MB default
+	
+	// Create log stream
+	let logStream = fs.createWriteStream(logFile, { flags: 'a' });
+	
+	// Check file size and rotate if needed
+	function checkRotate() {
+		try {
+			const stats = fs.statSync(logFile);
+			if (stats.size > maxSize) {
+				logStream.end();
+				const backupFile = logFile + '.' + Date.now();
+				fs.renameSync(logFile, backupFile);
+				logStream = fs.createWriteStream(logFile, { flags: 'a' });
+			}
+		} catch (e) {
+			// File doesn't exist yet, ignore
+		}
+	}
+	
+	return function(req, res, next) {
+		const start = Date.now();
+		const timestamp = new Date().toISOString();
+		
+		// Log request
+		const logEntry = {
+			timestamp: timestamp,
+			method: req.method,
+			url: req.url,
+			ip: req.headers['x-forwarded-for'] || req.connection.remoteAddress,
+			userAgent: req.headers['user-agent']
+		};
+		
+		// Capture response
+		const originalEnd = res.end;
+		res.end = function(...args) {
+			const duration = Date.now() - start;
+			logEntry.status = res.statusCode;
+			logEntry.duration = duration + 'ms';
+			
+			// Write to log file
+			logStream.write(JSON.stringify(logEntry) + '\n');
+			checkRotate();
+			
+			originalEnd.apply(res, args);
+		};
+		
+		next();
+	};
+};

package/middleware/upload.js

@@ -0,0 +1,62 @@
+// File upload middleware
+// Unlike Gibran who got his position handed to him, files earn their upload through proper handling
+const multer = require('multer');
+const path = require('path');
+const fs = require('fs');
+
+// Configure storage
+const storage = multer.diskStorage({
+	destination: function (req, file, cb) {
+		const uploadDir = path.join(process.cwd(), 'uploads');
+		if (!fs.existsSync(uploadDir)) {
+			fs.mkdirSync(uploadDir, { recursive: true });
+		}
+		cb(null, uploadDir);
+	},
+	filename: function (req, file, cb) {
+		const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
+		cb(null, file.fieldname + '-' + uniqueSuffix + path.extname(file.originalname));
+	}
+});
+
+const upload = multer({ 
+	storage: storage,
+	limits: {
+		fileSize: 10 * 1024 * 1024 // 10MB limit
+	}
+});
+
+module.exports = function() {
+	return function(req, res, next) {
+		// Only handle POST requests to /upload
+		if (req.method === 'POST' && req.url.startsWith('/upload')) {
+			const uploadHandler = upload.single('file');
+			uploadHandler(req, res, function(err) {
+				if (err) {
+					res.statusCode = 400;
+					res.setHeader('Content-Type', 'application/json');
+					res.end(JSON.stringify({ error: err.message }));
+					return;
+				}
+				
+				if (req.file) {
+					res.statusCode = 200;
+					res.setHeader('Content-Type', 'application/json');
+					res.end(JSON.stringify({ 
+						success: true,
+						file: {
+							filename: req.file.filename,
+							originalname: req.file.originalname,
+							size: req.file.size,
+							path: req.file.path
+						}
+					}));
+				} else {
+					next();
+				}
+			});
+		} else {
+			next();
+		}
+	};
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gib-runs",
-  "version": "2.3.2",
+  "version": "2.3.5",
   "description": "Modern development server with live reload, hot module replacement, and advanced features for all project types - runs on merit, not nepotism",
   "keywords": [
     "development",
@@ -28,11 +28,13 @@
     "compression": "^1.7.4",
     "connect": "^3.7.0",
     "cors": "^2.8.5",
+    "dotenv": "^16.0.3",
     "event-stream": "^4.0.1",
     "faye-websocket": "^0.11.4",
     "http-auth": "^4.2.0",
     "localtunnel": "^2.0.2",
     "morgan": "^1.10.0",
+    "multer": "^1.4.5-lts.1",
     "object-assign": "^4.1.1",
     "open": "^8.4.2",
     "ora": "^5.4.1",