@chenpu17/serve-here 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chen Pu
+
+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,62 @@
+# serve-here
+
+Serve any local directory over HTTP with a single command.  
+用一条命令把任意本地目录通过 HTTP 暴露出去。
+
+## Features | 功能特点
+- Instant static hosting for the current or specified directory.  
+  立即托管当前目录或指定目录。
+- Automatic `index.html` support plus clean directory listings.  
+  自动识别 `index.html`，无首页时提供整洁的目录列表。
+- Directory rows include file size and last modified time.  
+  列表项展示文件大小与最近修改时间。
+- Works as a global install or `npx` one-off.  
+  支持全局安装或通过 `npx` 临时使用。
+
+## Installation | 安装
+
+```sh
+npm install -g @chenpu17/serve-here
+```
+
+Or run it ad‑hoc without installing globally:  
+或者临时使用：
+
+```sh
+npx @chenpu17/serve-here
+```
+
+## Usage | 使用方式
+
+```sh
+serve-here [options] [directory]
+```
+
+- Installed globally, invoke via `serve-here`; with `npx`, run `npx @chenpu17/serve-here`.  
+  全局安装后直接使用 `serve-here`；临时使用时运行 `npx @chenpu17/serve-here`。
+
+- `directory`: Directory to share; defaults to the current working directory.  
+  `directory`：要共享的目录，默认使用当前工作目录。
+- `-d, --dir <path>`: Explicit directory override.  
+  `-d, --dir <path>`：显式指定要共享的目录。
+- `-p, --port <number>`: Port to listen on (default `8080`).  
+  `-p, --port <number>`：设置监听端口（默认 `8080`）。
+- `-H, --host <address>`: Host/IP to bind (default `0.0.0.0`).  
+  `-H, --host <address>`：指定绑定的主机或 IP（默认 `0.0.0.0`）。
+- `-h, --help`: Show help.  
+  `-h, --help`：查看帮助信息。
+- `-V, --version`: Print version.  
+  `-V, --version`：查看版本号。
+
+After startup you’ll see the bound addresses in the terminal. Opening them in a browser displays your static files or a table view of the directory contents.  
+启动后终端会打印可访问的地址，浏览器打开即可查看静态文件；若目录中没有 `index.html`，将显示带有文件大小和修改时间的目录表格。
+
+## Development | 开发
+
+```sh
+npm install
+npm start
+```
+
+`npm start` serves the current project directory so you can test quickly with a browser or `curl`.  
+`npm start` 会把当前项目目录作为静态资源根目录，方便通过浏览器或 `curl` 快速验证。

package/bin/serve-here.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const process = require('process');
+
+const { createStaticServer } = require('../src/server');
+const pkg = require('../package.json');
+
+const DEFAULT_PORT = 8080;
+const DEFAULT_HOST = '0.0.0.0';
+
+function main() {
+  try {
+    const options = parseArguments(process.argv.slice(2));
+
+    if (options.help) {
+      printHelp();
+      process.exit(0);
+    }
+
+    if (options.version) {
+      console.log(pkg.version);
+      process.exit(0);
+    }
+
+    const rootDir = path.resolve(options.directory || process.cwd());
+
+    let stats;
+    try {
+      stats = fs.statSync(rootDir);
+    } catch (error) {
+      console.error(`Error: directory "${rootDir}" does not exist or is not accessible.`);
+      process.exit(1);
+    }
+
+    if (!stats.isDirectory()) {
+      console.error(`Error: path "${rootDir}" is not a directory.`);
+      process.exit(1);
+    }
+
+    const server = createStaticServer({ rootDir });
+    const port = options.port || DEFAULT_PORT;
+    const host = options.host || DEFAULT_HOST;
+
+    server.on('error', error => {
+      console.error('Failed to start server:', error.message);
+      process.exit(1);
+    });
+
+    server.listen(port, host, () => {
+      const messageLines = [
+        `Serving ${rootDir}`,
+        `Listening on:`,
+        ...formatListeningAddresses(host, port)
+      ];
+      console.log(messageLines.join('\n  '));
+    });
+
+    const shutdown = () => {
+      console.log('\nShutting down...');
+      server.close(() => process.exit(0));
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+function parseArguments(args) {
+  const options = {
+    directory: undefined,
+    port: undefined,
+    host: undefined,
+    help: false,
+    version: false
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    switch (arg) {
+      case '-h':
+      case '--help':
+        options.help = true;
+        break;
+      case '-V':
+      case '--version':
+        options.version = true;
+        break;
+      case '-d':
+      case '--dir':
+      case '--directory':
+        options.directory = requireValue(args, ++i, '--dir');
+        break;
+      case '-p':
+      case '--port':
+        options.port = parsePort(requireValue(args, ++i, '--port'));
+        break;
+      case '-H':
+      case '--host':
+        options.host = requireValue(args, ++i, '--host');
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        if (options.directory) {
+          throw new Error('Multiple directories specified. Use --dir <path> to set the directory.');
+        }
+        options.directory = arg;
+        break;
+    }
+  }
+
+  return options;
+}
+
+function requireValue(args, index, flagName) {
+  const value = args[index];
+  if (value === undefined) {
+    throw new Error(`Missing value for ${flagName}`);
+  }
+  return value;
+}
+
+function parsePort(value) {
+  const port = Number.parseInt(value, 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+  return port;
+}
+
+function formatListeningAddresses(host, port) {
+  const addresses = [];
+
+  if (host === '0.0.0.0' || host === '::') {
+    addresses.push(`http://localhost:${port}/`);
+    const interfaces = os.networkInterfaces();
+    for (const iface of Object.values(interfaces)) {
+      if (!iface) continue;
+      for (const addrInfo of iface) {
+        if (addrInfo.internal) continue;
+        if (addrInfo.family !== 'IPv4' && addrInfo.family !== 4) continue;
+        addresses.push(`http://${addrInfo.address}:${port}/`);
+      }
+    }
+  } else {
+    addresses.push(`http://${host}:${port}/`);
+  }
+
+  return [...new Set(addresses)];
+}
+
+function printHelp() {
+  console.log(`serve-here v${pkg.version}
+
+Usage:
+  serve-here [options] [directory]
+
+Options:
+  -d, --dir <path>        Directory to serve (defaults to current working directory)
+  -p, --port <number>     Port to listen on (default: ${DEFAULT_PORT})
+  -H, --host <address>    Hostname or IP to bind (default: ${DEFAULT_HOST})
+  -h, --help              Show this help message
+  -V, --version           Show version`);
+}
+
+main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@chenpu17/serve-here",
+  "version": "1.0.0",
+  "description": "A minimal CLI to serve static files from a directory over HTTP.",
+  "bin": {
+    "serve-here": "bin/serve-here.js"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "start": "node bin/serve-here.js"
+  },
+  "keywords": [
+    "cli",
+    "http",
+    "static",
+    "server",
+    "serve",
+    "directory"
+  ],
+  "author": "Chen Pu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chenpu17/serve-here.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chenpu17/serve-here/issues"
+  },
+  "homepage": "https://github.com/chenpu17/serve-here#readme",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "dependencies": {
+    "mime-types": "^2.1.35"
+  }
+}

package/src/server.js

@@ -0,0 +1,332 @@
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { lookup } = require('mime-types');
+
+const { readdir, stat } = fs.promises;
+
+/**
+ * Creates an HTTP server that serves static files rooted at the provided directory.
+ *
+ * @param {object} options
+ * @param {string} options.rootDir Absolute or relative directory to serve.
+ * @param {string[]} [options.indexFiles] Index files to try when a directory is requested.
+ * @param {boolean} [options.enableDirectoryListing] Whether to render a simple directory listing when no index file exists.
+ * @param {Console} [options.logger] Logger implementation, defaults to console.
+ * @returns {http.Server}
+ */
+function createStaticServer({
+  rootDir,
+  indexFiles = ['index.html', 'index.htm'],
+  enableDirectoryListing = true,
+  logger = console
+}) {
+  if (!rootDir) {
+    throw new Error('rootDir is required to create a static server');
+  }
+
+  const resolvedRoot = path.resolve(rootDir);
+  const rootWithSep = resolvedRoot.endsWith(path.sep)
+    ? resolvedRoot
+    : `${resolvedRoot}${path.sep}`;
+
+  const server = http.createServer(async (req, res) => {
+    const startTime = Date.now();
+
+    if (!req.url) {
+      sendError(res, 400, 'Bad Request');
+      return;
+    }
+
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.setHeader('Allow', 'GET, HEAD');
+      sendError(res, 405, 'Method Not Allowed');
+      logRequest(logger, req, res.statusCode, startTime);
+      return;
+    }
+
+    let decodedPath;
+    try {
+      const url = new URL(req.url, 'http://localhost');
+      decodedPath = decodeURIComponent(url.pathname);
+    } catch (error) {
+      sendError(res, 400, 'Bad Request');
+      logRequest(logger, req, res.statusCode, startTime, error);
+      return;
+    }
+
+    const candidateSegments = decodedPath
+      .split('/')
+      .filter(segment => segment && segment !== '.');
+    const resolvedPath = path.resolve(resolvedRoot, ...candidateSegments);
+
+    if (!resolvedPath.startsWith(rootWithSep) && resolvedPath !== resolvedRoot) {
+      sendError(res, 403, 'Forbidden');
+      logRequest(logger, req, res.statusCode, startTime);
+      return;
+    }
+
+    let stats;
+    try {
+      stats = await stat(resolvedPath);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        sendError(res, 404, 'Not Found');
+      } else {
+        sendError(res, 500, 'Internal Server Error');
+        logger.error('Error reading path', resolvedPath, error);
+      }
+      logRequest(logger, req, res.statusCode, startTime, error);
+      return;
+    }
+
+    if (stats.isDirectory()) {
+      if (!decodedPath.endsWith('/')) {
+        // Align with browser expectations for relative asset loading.
+        res.statusCode = 301;
+        res.setHeader('Location', `${decodedPath}/`);
+        res.end();
+        logRequest(logger, req, res.statusCode, startTime);
+        return;
+      }
+
+      for (const indexFile of indexFiles) {
+        const candidate = path.join(resolvedPath, indexFile);
+        try {
+          const indexStats = await stat(candidate);
+          if (indexStats.isFile()) {
+            await serveFile(res, candidate, indexStats, req.method === 'HEAD');
+            logRequest(logger, req, res.statusCode, startTime);
+            return;
+          }
+        } catch (error) {
+          if (error.code !== 'ENOENT') {
+            logger.error('Error reading index file', candidate, error);
+          }
+        }
+      }
+
+      if (!enableDirectoryListing) {
+        sendError(res, 403, 'Directory listing disabled');
+        logRequest(logger, req, res.statusCode, startTime);
+        return;
+      }
+
+      try {
+        await serveDirectoryListing(
+          res,
+          decodedPath,
+          resolvedPath,
+          req.method === 'HEAD'
+        );
+        logRequest(logger, req, res.statusCode, startTime);
+        return;
+      } catch (error) {
+        sendError(res, 500, 'Internal Server Error');
+        logger.error('Error generating directory listing', resolvedPath, error);
+        logRequest(logger, req, res.statusCode, startTime, error);
+        return;
+      }
+    }
+
+    if (stats.isFile()) {
+      try {
+        await serveFile(res, resolvedPath, stats, req.method === 'HEAD');
+      } catch (error) {
+        logger.error('Error serving file', resolvedPath, error);
+        // Stream errors may happen after headers were sent.
+      }
+      logRequest(logger, req, res.statusCode, startTime);
+      return;
+    }
+
+    sendError(res, 403, 'Forbidden');
+    logRequest(logger, req, res.statusCode, startTime);
+  });
+
+  return server;
+}
+
+function sendError(res, statusCode, message) {
+  res.statusCode = statusCode;
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  res.end(`${statusCode} ${message}`);
+}
+
+async function serveFile(res, filePath, stats, headOnly) {
+  const mimeType = lookup(filePath) || 'application/octet-stream';
+  res.statusCode = 200;
+  res.setHeader('Content-Type', mimeType);
+  res.setHeader('Content-Length', stats.size);
+  res.setHeader('Last-Modified', stats.mtime.toUTCString());
+  res.setHeader('Cache-Control', 'no-cache');
+
+  if (headOnly) {
+    res.end();
+    return;
+  }
+
+  await streamFile(res, filePath);
+}
+
+function streamFile(res, filePath) {
+  return new Promise((resolve, reject) => {
+    const stream = fs.createReadStream(filePath);
+    stream.on('error', error => {
+      if (!res.headersSent) {
+        sendError(res, 500, 'Internal Server Error');
+      } else {
+        res.destroy(error);
+      }
+      reject(error);
+    });
+    stream.on('end', resolve);
+    stream.pipe(res);
+  });
+}
+
+async function serveDirectoryListing(res, requestPath, directoryPath, headOnly) {
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  const items = entries
+    .map(entry => ({
+      name: entry.name,
+      isDirectory: entry.isDirectory()
+    }))
+    .sort((a, b) => {
+      if (a.isDirectory && !b.isDirectory) return -1;
+      if (!a.isDirectory && b.isDirectory) return 1;
+      return a.name.localeCompare(b.name);
+    });
+
+  const detailedItems = [];
+  for (const item of items) {
+    const fullPath = path.join(directoryPath, item.name);
+    try {
+      const stats = await stat(fullPath);
+      detailedItems.push({
+        ...item,
+        size: stats.isFile() ? stats.size : null,
+        mtime: stats.mtime
+      });
+    } catch (error) {
+      detailedItems.push({
+        ...item,
+        size: null,
+        mtime: null
+      });
+    }
+  }
+
+  const tableRows = detailedItems
+    .map(item => {
+      const trailingSlash = item.isDirectory ? '/' : '';
+      const href = encodeURIComponent(item.name) + trailingSlash;
+      const displayName = `${escapeHtml(item.name)}${trailingSlash}`;
+      const size = item.isDirectory ? '-' : formatBytes(item.size);
+      const modified = item.mtime ? formatDate(item.mtime) : '-';
+      return `<tr><td><a href="${href}">${displayName}</a></td><td>${size}</td><td>${modified}</td></tr>`;
+    })
+    .join('\n');
+
+  const body = `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Index of ${escapeHtml(requestPath)}</title>
+    <style>
+      body { font-family: sans-serif; padding: 1rem 2rem; }
+      h1 { font-size: 1.5rem; margin-bottom: 1rem; }
+      table { border-collapse: collapse; width: 100%; max-width: 60rem; }
+      th, td { text-align: left; padding: 0.35rem 0.5rem; border-bottom: 1px solid #e1e4e8; }
+      th { font-weight: 600; background: #f6f8fa; }
+      td:nth-child(2), th:nth-child(2) { width: 8rem; }
+      td:nth-child(3), th:nth-child(3) { width: 16rem; }
+      a { text-decoration: none; color: #0366d6; }
+      a:hover { text-decoration: underline; }
+      @media (max-width: 600px) {
+        table { font-size: 0.9rem; }
+        td:nth-child(3), th:nth-child(3) { width: auto; }
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Index of ${escapeHtml(requestPath)}</h1>
+    <table>
+      <thead>
+        <tr><th>Name</th><th>Size</th><th>Last Modified</th></tr>
+      </thead>
+      <tbody>
+        ${requestPath !== '/' ? '<tr><td><a href="../">../</a></td><td>-</td><td>-</td></tr>' : ''}
+        ${tableRows}
+      </tbody>
+    </table>
+    <footer>
+      <p>
+        Served by <a href="https://github.com/chenpu17/serve-here" target="_blank" rel="noreferrer">serve-here</a>
+      </p>
+    </footer>
+  </body>
+</html>`;
+
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/html; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-cache');
+
+  if (headOnly) {
+    res.end();
+    return;
+  }
+
+  res.end(body);
+}
+
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, character => {
+    const replacements = {
+      '&': '&amp;',
+      '<': '&lt;',
+      '>': '&gt;',
+      '"': '&quot;',
+      "'": '&#39;'
+    };
+    return replacements[character] || character;
+  });
+}
+
+function formatBytes(bytes) {
+  if (bytes === null || bytes === undefined) {
+    return '-';
+  }
+  if (bytes === 0) {
+    return '0 B';
+  }
+  const units = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
+  const exponent = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(1024)),
+    units.length - 1
+  );
+  const size = bytes / 1024 ** exponent;
+  return `${size >= 10 ? size.toFixed(0) : size.toFixed(1)} ${units[exponent]}`;
+}
+
+function formatDate(date) {
+  if (!date) return '-';
+  return date.toLocaleString();
+}
+
+function logRequest(logger, req, statusCode, startTime, error) {
+  const duration = Date.now() - startTime;
+  const method = req.method;
+  const url = req.url;
+  const message = `${method} ${url} ${statusCode} ${duration}ms`;
+  if (error) {
+    logger.error(message);
+  } else {
+    logger.info ? logger.info(message) : logger.log(message);
+  }
+}
+
+module.exports = {
+  createStaticServer
+};