busyserver 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SATPAL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# BusyServer
+
+> **A lightweight, cross-platform Node.js development and static file server.**
+
+BusyServer is a fast and production-quality static server designed for developers. It runs seamlessly anywhere Node.js is supported—including Linux, macOS, Windows, and Termux/Android environments. Whether you need an instant local server, reverse proxy, API mocks, or live-reload capabilities, BusyServer has you covered.
+
+## Features
+
+* **⚡ Live Reload**: Instant HTML, CSS, and Image hot-swapping without full page reloads via WebSockets.
+* **📂 Directory Listing**: Modern, responsive dark/light UI with breadcrumb navigation, search/filter, and column sorting.
+* **🔒 Local HTTPS**: Built-in TLS support for secure localhost testing (`--https`).
+* **🔄 Reverse Proxy**: Forward requests to a backend server to bypass CORS (`--proxy /api=http://localhost:5000`).
+* **🎭 API Mocking**: Serve JSON mocks effortlessly from a directory (`--mock ./mocks`), including HTTP-method-specific mocks.
+* **🌐 SPA Fallback**: Automatically serves `index.html` for missing files (`--spa`).
+* **📱 Real QR Code**: Scan and open on your mobile device instantly (`--qr`).
+* **🗜️ Performance**: Automatic Brotli and Gzip compression, HTTP Range requests (206 Partial Content), and ETag/304 caching.
+* **🛠️ Developer Experience**: Smart port selection/fallback, host binding, custom error pages (404, 403, 405, 500), and custom headers.
+* **📊 Web Dashboard**: Inspect active connections and server stats live at `/__busyserver`.
+* **⚙️ Persistent Config**: Use `busyserver init` to generate a `.busyserverc.json`.
+* **🛡️ Security**: Built-in protection against path traversal, null bytes, and unauthorized dotfile access.
+
+## Quick Start
+
+Run it instantly without installing:
+\`\`\`bash
+npx busyserver
+\`\`\`
+
+Or install globally via npm:
+\`\`\`bash
+npm install -g busyserver
+\`\`\`
+
+## CLI Usage
+
+Serve the current directory on an available port:
+\`\`\`bash
+busyserver
+\`\`\`
+
+Serve a specific directory with a custom port and auto-open browser:
+\`\`\`bash
+busyserver ./public -p 8080 --open
+\`\`\`
+
+Bind to a specific network interface (e.g., localhost only):
+\`\`\`bash
+busyserver --host 127.0.0.1
+\`\`\`
+
+Enable Single Page App (SPA) mode:
+\`\`\`bash
+busyserver --spa
+\`\`\`
+
+Show a QR code for easy mobile LAN access:
+\`\`\`bash
+busyserver --qr
+\`\`\`
+
+### API Mocking
+
+Need a fake backend while developing? Enable mocking:
+
+\`\`\`bash
+busyserver --mock ./mocks
+\`\`\`
+
+Create files in your mock directory (`./mocks/api`):
+- `./mocks/api/users.json` → responds to `GET /api/users`
+- `./mocks/api/users.POST.json` → responds to `POST /api/users`
+- `./mocks/api/index.json` → responds to `GET /api/`
+
+### Reverse Proxy
+
+Forward API requests to a real backend to bypass CORS:
+
+\`\`\`bash
+busyserver --proxy /api=http://localhost:5000
+\`\`\`
+
+### Local HTTPS (TLS)
+
+Test features that require secure contexts (like Service Workers or Geolocation) using local HTTPS.
+Ensure `key.pem` and `cert.pem` are present in the directory you are running the server from.
+
+\`\`\`bash
+busyserver --https
+\`\`\`
+
+## Configuration
+
+Generate a configuration file to save your project preferences:
+
+\`\`\`bash
+busyserver init
+\`\`\`
+
+This creates a `.busyserverc.json` in your project root:
+
+\`\`\`json
+{
+  "port": 3000,
+  "host": "0.0.0.0",
+  "open": false,
+  "reload": true,
+  "watch": true,
+  "spa": false,
+  "quiet": false,
+  "qr": false,
+  "https": false,
+  "compression": true,
+  "proxy": {},
+  "mock": "",
+  "ignore": [
+    "**/.git/**",
+    "**/node_modules/**"
+  ],
+  "headers": {
+    "X-Custom-Header": "BusyServer"
+  }
+}
+\`\`\`
+
+## Dashboard
+
+Navigate to `/__busyserver` in your browser while the server is running to view the live developer dashboard, monitor uptime, and see active WebSocket clients.
+
+## Development & Testing
+
+Clone the repository and install dependencies:
+
+\`\`\`bash
+npm install
+\`\`\`
+
+Run the comprehensive test suite (62 tests):
+
+\`\`\`bash
+npm test
+\`\`\`
+
+---
+*Built for modern cross-platform web development.*

package/bin/busyserver.js

@@ -0,0 +1,246 @@
+#!/bin/sh
+":" //# comment; exec node "$0" "$@"
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { startBusyServer } = require("../src/server");
+const { loadConfig } = require("../src/config");
+
+const pkg = require("../package.json");
+const args = process.argv.slice(2);
+
+// ── Init Command ────────────────────────────────────
+
+if (args[0] === "init") {
+  const configPath = path.join(process.cwd(), ".busyserverc.json");
+  if (fs.existsSync(configPath)) {
+    console.error("❌ Configuration file already exists: .busyserverc.json");
+    process.exit(1);
+  }
+
+  const defaultConfig = {
+    "port": 3000,
+    "host": "0.0.0.0",
+    "open": false,
+    "reload": true,
+    "watch": true,
+    "spa": false,
+    "quiet": false,
+    "qr": false,
+    "https": false,
+    "compression": true,
+    "proxy": {},
+    "mock": "",
+    "ignore": [
+      "**/.git/**",
+      "**/node_modules/**"
+    ],
+    "headers": {
+      "X-Custom-Header": "BusyServer"
+    }
+  };
+
+  fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+  console.log("✅ Created .busyserverc.json with default settings.");
+  process.exit(0);
+}
+
+// ── Help ────────────────────────────────────────────
+
+function showHelp() {
+  console.log(`
+🚀 BusyServer v${pkg.version} — Live Server for Termux
+
+Usage:
+  busyserver [directory] [options]
+  busyserver init                  Create .busyserverc.json
+
+Arguments:
+  directory              Directory to serve (default: current directory)
+
+Options:
+  -p, --port <number>    Server port (default: 3000)
+  --host <address>       Host to bind to (default: 0.0.0.0)
+  --open                 Open in browser automatically
+  --no-reload            Disable live reload
+  --no-watch             Disable file watching
+  --spa                  Enable SPA mode (fallback to index.html)
+  --quiet                Suppress request logging
+  --qr                   Show QR code for network URL
+  --https                Enable local HTTPS
+  --proxy <rule>         Add a proxy rule (e.g. /api=http://localhost:5000)
+  --mock <dir>           Enable API mocking from directory
+  -h, --help             Show this help message
+  -v, --version          Show version number
+
+Examples:
+  busyserver                          Serve current directory
+  busyserver ./website                Serve ./website directory
+  busyserver -p 8080 --qr             Serve on port 8080 with QR
+  busyserver --proxy /api=http://...  Proxy /api to another server
+
+Config:
+  Place a .busyserverc.json in your project root for persistent settings.
+  CLI arguments override config file values.
+`);
+}
+
+// ── Parse Arguments ─────────────────────────────────
+
+if (args.includes("-h") || args.includes("--help")) {
+  showHelp();
+  process.exit(0);
+}
+
+if (args.includes("-v") || args.includes("--version")) {
+  console.log(`busyserver v${pkg.version}`);
+  process.exit(0);
+}
+
+let directory = null;
+let cliPort = null;
+let cliHost = null;
+let explicitPort = false;
+let cliOpen = null;
+let cliReload = null;
+let cliWatch = null;
+let cliSpa = null;
+let cliQuiet = null;
+let cliQr = null;
+let cliHttps = null;
+let cliMock = null;
+let cliProxy = {};
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+
+  if (arg === "-p" || arg === "--port") {
+    const value = args[i + 1];
+    if (!value || value.startsWith("-")) {
+      console.error("❌ Port number missing after " + arg);
+      process.exit(1);
+    }
+    const num = Number(value);
+    if (!Number.isInteger(num) || num < 1 || num > 65535) {
+      console.error(`❌ Invalid port number: \${value}`);
+      process.exit(1);
+    }
+    cliPort = num;
+    explicitPort = true;
+    i++;
+  } else if (arg === "--host") {
+    const value = args[i + 1];
+    if (!value || value.startsWith("-")) {
+      console.error("❌ Host address missing after --host");
+      process.exit(1);
+    }
+    cliHost = value;
+    i++;
+  } else if (arg === "--proxy") {
+    const value = args[i + 1];
+    if (!value || value.startsWith("-") || !value.includes("=")) {
+      console.error("❌ Proxy rule must be in format /path=http://target");
+      process.exit(1);
+    }
+    const [pathPrefix, target] = value.split("=");
+    cliProxy[pathPrefix] = target;
+    i++;
+  } else if (arg === "--mock") {
+    const value = args[i + 1];
+    if (!value || value.startsWith("-")) {
+      console.error("❌ Mock directory missing after --mock");
+      process.exit(1);
+    }
+    cliMock = value;
+    i++;
+  } else if (arg === "--open") {
+    cliOpen = true;
+  } else if (arg === "--no-reload") {
+    cliReload = false;
+  } else if (arg === "--no-watch") {
+    cliWatch = false;
+  } else if (arg === "--spa") {
+    cliSpa = true;
+  } else if (arg === "--quiet") {
+    cliQuiet = true;
+  } else if (arg === "--qr") {
+    cliQr = true;
+  } else if (arg === "--https") {
+    cliHttps = true;
+  } else if (arg.startsWith("-")) {
+    console.error(`❌ Unknown option: \${arg}`);
+    console.log("Use 'busyserver --help' for available options.");
+    process.exit(1);
+  } else {
+    if (directory !== null) {
+      console.error(`❌ Unexpected argument: \${arg}`);
+      console.log("Use 'busyserver --help' for available options.");
+      process.exit(1);
+    }
+    directory = arg;
+  }
+}
+
+// ── Resolve Directory ───────────────────────────────
+
+let resolvedDir;
+
+if (directory) {
+  if (directory.startsWith("~")) {
+    directory = path.join(os.homedir(), directory.slice(1));
+  }
+  resolvedDir = path.resolve(process.cwd(), directory);
+} else {
+  resolvedDir = process.cwd();
+}
+
+try {
+  const stat = fs.statSync(resolvedDir);
+  if (!stat.isDirectory()) {
+    console.error(`❌ Path is not a directory: \${resolvedDir}`);
+    process.exit(1);
+  }
+} catch (error) {
+  if (error.code === "ENOENT") {
+    console.error(`❌ Directory not found: \${resolvedDir}`);
+  } else {
+    console.error(`❌ Cannot access directory: \${resolvedDir}`);
+  }
+  process.exit(1);
+}
+
+// ── Load Config ─────────────────────────────────────
+
+const config = loadConfig(resolvedDir);
+
+// Merge proxy config
+const finalProxy = { ...(config.proxy || {}), ...cliProxy };
+
+// ── Merge: defaults < config < CLI ──────────────────
+
+const options = {
+  root: resolvedDir,
+  port: cliPort !== null ? cliPort : config.port,
+  host: cliHost !== null ? cliHost : config.host,
+  autoPort: !explicitPort,
+  reload: cliReload !== null ? cliReload : config.reload,
+  watch: cliWatch !== null ? cliWatch : config.watch,
+  open: cliOpen !== null ? cliOpen : config.open,
+  spa: cliSpa !== null ? cliSpa : config.spa,
+  quiet: cliQuiet !== null ? cliQuiet : config.quiet,
+  qr: cliQr !== null ? cliQr : config.qr,
+  https: cliHttps !== null ? cliHttps : config.https,
+  mock: cliMock !== null ? cliMock : config.mock,
+  proxy: finalProxy,
+  compression: config.compression !== false,
+  headers: config.headers || {},
+  ignore: config.ignore || [],
+};
+
+// ── Start Server ────────────────────────────────────
+
+startBusyServer(options).catch((error) => {
+  console.error(`❌ Failed to start server: \${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "busyserver",
+  "version": "1.0.0",
+  "description": "A lightweight live-reload development server for Termux — the VS Code Live Server equivalent for your terminal.",
+  "main": "src/server.js",
+  "bin": {
+    "busyserver": "bin/busyserver.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/busyserver.js",
+    "test": "node --test test/server.test.js"
+  },
+  "keywords": [
+    "termux",
+    "live-server",
+    "live-reload",
+    "dev-server",
+    "static-server",
+    "hot-reload",
+    "websocket",
+    "cli"
+  ],
+  "author": "debuggersatpal",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/debuggersatpal/busyserver.git"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.21.3"
+  }
+}

package/src/config.js

@@ -0,0 +1,60 @@
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULTS = {
+  port: 3000,
+  host: "0.0.0.0",
+  reload: true,
+  watch: true,
+  open: false,
+  spa: false,
+  quiet: false,
+  qr: false,
+  ignore: [],
+};
+
+const CONFIG_FILE = ".busyserverc.json";
+
+/**
+ * Load configuration from .busyserverc.json in the given directory.
+ * Returns defaults merged with any file-based config.
+ */
+function loadConfig(directory) {
+  const configPath = path.join(directory, CONFIG_FILE);
+  const config = { ...DEFAULTS };
+
+  try {
+    const stat = fs.statSync(configPath);
+    if (!stat.isFile()) return config;
+  } catch {
+    return config;
+  }
+
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw);
+
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.warn(`⚠️  Invalid config in ${CONFIG_FILE}: expected an object`);
+      return config;
+    }
+
+    // Merge only known keys
+    if (typeof parsed.port === "number") config.port = parsed.port;
+    if (typeof parsed.host === "string") config.host = parsed.host;
+    if (typeof parsed.reload === "boolean") config.reload = parsed.reload;
+    if (typeof parsed.watch === "boolean") config.watch = parsed.watch;
+    if (typeof parsed.open === "boolean") config.open = parsed.open;
+    if (typeof parsed.spa === "boolean") config.spa = parsed.spa;
+    if (typeof parsed.quiet === "boolean") config.quiet = parsed.quiet;
+    if (typeof parsed.qr === "boolean") config.qr = parsed.qr;
+    if (Array.isArray(parsed.ignore)) config.ignore = parsed.ignore;
+
+    return config;
+  } catch (error) {
+    console.warn(`⚠️  Failed to parse ${CONFIG_FILE}: ${error.message}`);
+    return config;
+  }
+}
+
+module.exports = { loadConfig, DEFAULTS, CONFIG_FILE };

package/src/dashboard.js

@@ -0,0 +1,32 @@
+function generateDashboard(options, wss, watcher) {
+  const uptime = process.uptime();
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>BusyServer Dashboard</title>
+  <style>
+    body { font-family: system-ui; background: #0f172a; color: #f8fafc; padding: 2rem; margin: 0; }
+    .card { background: #1e293b; padding: 1.5rem; border-radius: 8px; margin-bottom: 1rem; border: 1px solid #334155; }
+    h1 { margin-top: 0; color: #38bdf8; }
+    .stat { display: flex; justify-content: space-between; padding: 0.5rem 0; border-bottom: 1px solid #334155; }
+    .stat:last-child { border: none; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>BusyServer Dashboard</h1>
+    <div class="stat"><span>Root</span> <span>${options.root}</span></div>
+    <div class="stat"><span>Port</span> <span>${options.port}</span></div>
+    <div class="stat"><span>Live Reload</span> <span>${options.reload ? "ON" : "OFF"}</span></div>
+    <div class="stat"><span>Watcher</span> <span>${options.watch ? "ON" : "OFF"}</span></div>
+    <div class="stat"><span>SPA Mode</span> <span>${options.spa ? "ON" : "OFF"}</span></div>
+    <div class="stat"><span>Uptime</span> <span>${Math.floor(uptime)}s</span></div>
+    <div class="stat"><span>Connected Browsers</span> <span>${wss ? wss.clients.size : 0}</span></div>
+  </div>
+</body>
+</html>`;
+}
+
+module.exports = { generateDashboard };

package/src/mock.js

@@ -0,0 +1,45 @@
+const path = require("path");
+const fs = require("fs");
+
+function handleMock(req, res, options) {
+  if (!options.mock) return false;
+
+  try {
+    const rawPath = req.url.split("?")[0];
+    const mockDir = path.resolve(process.cwd(), options.mock);
+    
+    // Try Method-specific mock: mock/api/users.GET.json
+    let mockFile = path.join(mockDir, rawPath + "." + req.method + ".json");
+    if (fs.existsSync(mockFile) && fs.statSync(mockFile).isFile()) {
+      const data = fs.readFileSync(mockFile, "utf-8");
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(data);
+      return true;
+    }
+
+    // Convert e.g. /api/users to mock/api/users.json
+    mockFile = path.join(mockDir, rawPath + ".json");
+    if (fs.existsSync(mockFile) && fs.statSync(mockFile).isFile()) {
+      const data = fs.readFileSync(mockFile, "utf-8");
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(data);
+      return true;
+    }
+
+    // Try mock/api/users/index.json
+    mockFile = path.join(mockDir, rawPath, "index.json");
+    if (fs.existsSync(mockFile) && fs.statSync(mockFile).isFile()) {
+      const data = fs.readFileSync(mockFile, "utf-8");
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(data);
+      return true;
+    }
+
+  } catch (err) {
+    // ignore
+  }
+
+  return false;
+}
+
+module.exports = { handleMock };

package/src/proxy.js

@@ -0,0 +1,46 @@
+const http = require("http");
+const https = require("https");
+
+function handleProxy(req, res, options) {
+  const proxyRules = options.proxy;
+  if (!proxyRules) return false;
+
+  const urlPath = req.url.split("?")[0];
+  let targetPrefix = null;
+  let targetUrl = null;
+
+  for (const [prefix, target] of Object.entries(proxyRules)) {
+    if (urlPath.startsWith(prefix)) {
+      targetPrefix = prefix;
+      targetUrl = target;
+      break;
+    }
+  }
+
+  if (!targetUrl) return false;
+
+  const client = targetUrl.startsWith("https") ? https : http;
+  const proxyUrl = new URL(targetUrl);
+  // Remove prefix if you want, but standard proxy often just forwards the path.
+  // Actually, standard proxy forwards the full path unless specified. Let's forward full path.
+  const proxyReq = client.request({
+    hostname: proxyUrl.hostname,
+    port: proxyUrl.port,
+    path: req.url,
+    method: req.method,
+    headers: { ...req.headers, host: proxyUrl.hostname }
+  }, (proxyRes) => {
+    res.writeHead(proxyRes.statusCode, proxyRes.headers);
+    proxyRes.pipe(res);
+  });
+
+  proxyReq.on("error", (err) => {
+    res.writeHead(502);
+    res.end("502 - Bad Gateway");
+  });
+
+  req.pipe(proxyReq);
+  return true;
+}
+
+module.exports = { handleProxy };