mnfst-run 1.0.9 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnfst-run",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "description": "Zero-dependency dev server for Manifest projects",
   "type": "module",
   "bin": {

package/serve.mjs

@@ -4,10 +4,14 @@
  *
  * Usage:
  *   npx mnfst-run [dir] [--port 5001] [--idle-shutdown 30] [--no-idle-shutdown]
+ *   npx mnfst-run --list
  *
  *   dir                 Directory to serve (default: current directory). Any
  *                       depth of nesting is valid, e.g.
  *                       npx mnfst-run docs/articles/publishing
+ *                       If a server is already running for this directory,
+ *                       prints its URL and exits instead of starting a
+ *                       duplicate. Use `--list` to see everything running.
  *   --port              Preferred port (default: PORT env var, then 5001).
  *                       Auto-increments if the port is already in use.
  *   --idle-shutdown N   Exit N seconds after the last preview tab closes
@@ -19,6 +23,8 @@
  *                       overnight with the preview tab still open.
  *   --no-idle-shutdown  Disable auto-shutdown (useful in CI / headless cases
  *                       where no browser will connect).
+ *   --list              Print all mnfst-run servers currently running on this
+ *                       machine and exit.
  *
  * SPA vs MPA is auto-detected: if the root index.html contains
  * <meta name="manifest:prerendered"> the server disables SPA fallback.
@@ -29,10 +35,16 @@
  *                     sources and updates Alpine store reactively (no reload)
  *   other           → full page reload
  */
-import { createServer }                  from 'http';
-import { readFileSync, statSync, watch } from 'fs';
-import { join, extname, resolve, basename } from 'path';
+import { createServer, get as httpGet }  from 'http';
+import {
+  readFileSync, statSync, watch,
+  existsSync, writeFileSync, unlinkSync,
+  mkdirSync, readdirSync,
+} from 'fs';
+import { join, extname, resolve, basename, sep } from 'path';
 import { exec }                          from 'child_process';
+import { tmpdir }                        from 'os';
+import { createHash }                    from 'crypto';
 
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -114,17 +126,148 @@ let port = process.env.PORT ? parseInt(process.env.PORT, 10) : 5001;
 // sit idle overnight if the tab is still open. Disabled by
 // `--no-idle-shutdown` for CI / headless cases where no browser will connect.
 let idleShutdownSec = 30;
-let idleShutdownEnabled = true;
+// Auto-disable idle shutdown when running under CI or Claude Code, where the
+// host browser (puppeteer / headless Chromium) does not produce the normal
+// `pagehide` beacon + SSE heartbeats that the live-tab tracker relies on.
+// Without this, the server would self-exit 30s after launch even while the
+// automation is actively driving it. Manual override still works via the
+// `--no-idle-shutdown` / `--idle-shutdown <sec>` flags below.
+let idleShutdownEnabled = !(
+  process.env.CI === 'true' ||
+  process.env.CLAUDE_CODE_ENTRYPOINT ||
+  process.env.CLAUDECODE
+);
+
+let listMode = false;
 
 for (let i = 0; i < args.length; i++) {
   if ((args[i] === '--port' || args[i] === '-p') && args[i + 1]) { port = parseInt(args[++i], 10); continue; }
   if (args[i] === '--no-idle-shutdown') { idleShutdownEnabled = false; continue; }
   if (args[i] === '--idle-shutdown' && args[i + 1]) { idleShutdownSec = parseInt(args[++i], 10); continue; }
+  if (args[i] === '--list' || args[i] === '-l') { listMode = true; continue; }
   if (!args[i].startsWith('-')) dir = args[i];
 }
 
+// --- Running-server registry ---
+// One JSON file per project under `$TMPDIR/mnfst-run/`, keyed by a hash of
+// the absolute root. Each holds `{ root, port, pid, startedAt }`. Used for:
+//   1. Dedup — a second `mnfst-run <dir>` for an already-running project
+//      prints the existing URL instead of spinning up another port.
+//   2. `--list` — show what's currently running across all projects.
+// Cleanup happens on graceful exit (idle-shutdown, Ctrl+C, SIGTERM). Crash
+// recovery is automatic: stale entries are detected by the next startup via
+// PID-alive + identity-endpoint check and unlinked.
+const REGISTRY_DIR = join(tmpdir(), 'mnfst-run');
+const IDENTITY_PATH = '/__mnfst_run__';
+
+function registryFileFor(rootPath) {
+  const hash = createHash('sha1').update(rootPath).digest('hex').slice(0, 16);
+  return join(REGISTRY_DIR, hash + '.json');
+}
+
+function readRegistryEntry(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); }
+  catch { return null; }
+}
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+// Quick probe of /__mnfst_run__ to confirm the entry isn't stale (PID may
+// have been recycled to an unrelated process). Resolves to the parsed
+// identity object on success, null on timeout / non-mnfst response.
+function probeIdentity(p, timeoutMs = 400) {
+  return new Promise((resolveProbe) => {
+    let done = false;
+    const finish = (v) => { if (done) return; done = true; resolveProbe(v); };
+    const req = httpGet({ host: '127.0.0.1', port: p, path: IDENTITY_PATH, timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; if (body.length > 4096) { res.destroy(); finish(null); } });
+      res.on('end', () => { try { finish(JSON.parse(body)); } catch { finish(null); } });
+    });
+    req.on('error', () => finish(null));
+    req.on('timeout', () => { req.destroy(); finish(null); });
+  });
+}
+
+async function findRunningServer(rootPath) {
+  const file = registryFileFor(rootPath);
+  if (!existsSync(file)) return null;
+  const entry = readRegistryEntry(file);
+  if (!entry || entry.root !== rootPath || !pidAlive(entry.pid)) {
+    try { unlinkSync(file); } catch {}
+    return null;
+  }
+  const id = await probeIdentity(entry.port);
+  if (!id || id.root !== rootPath) {
+    try { unlinkSync(file); } catch {}
+    return null;
+  }
+  return entry;
+}
+
+function writeRegistry(rootPath, p) {
+  try { mkdirSync(REGISTRY_DIR, { recursive: true }); } catch {}
+  try {
+    writeFileSync(registryFileFor(rootPath), JSON.stringify({
+      root: rootPath,
+      port: p,
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+    }) + '\n');
+  } catch { /* registry is best-effort; serving still works without it */ }
+}
+
+function removeRegistry(rootPath) {
+  try { unlinkSync(registryFileFor(rootPath)); } catch {}
+}
+
+async function listRunningServers() {
+  let files;
+  try { files = readdirSync(REGISTRY_DIR); } catch { files = []; }
+  const rows = [];
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const file = join(REGISTRY_DIR, f);
+    const entry = readRegistryEntry(file);
+    if (!entry || !pidAlive(entry.pid)) { try { unlinkSync(file); } catch {} continue; }
+    const id = await probeIdentity(entry.port);
+    if (!id || id.root !== entry.root) { try { unlinkSync(file); } catch {} continue; }
+    rows.push(entry);
+  }
+  if (rows.length === 0) { console.log('No mnfst-run servers running.'); return; }
+  const portW = Math.max(4, ...rows.map(r => String(r.port).length));
+  const pidW  = Math.max(3, ...rows.map(r => String(r.pid).length));
+  console.log(`${'PORT'.padEnd(portW)}  ${'PID'.padEnd(pidW)}  URL                          ROOT`);
+  for (const r of rows) {
+    const url = `http://localhost:${r.port}`;
+    console.log(`${String(r.port).padEnd(portW)}  ${String(r.pid).padEnd(pidW)}  ${url.padEnd(28)}  ${r.root}`);
+  }
+}
+
+if (listMode) {
+  await listRunningServers();
+  process.exit(0);
+}
+
 const root = resolve(process.cwd(), dir);
 
+// Dedup: if a server is already serving this exact root, point the user at
+// it (and open the browser, since that's what they were going to do anyway).
+const existing = await findRunningServer(root);
+if (existing) {
+  const url = `http://localhost:${existing.port}`;
+  const label0 = dir === '.' ? basename(process.cwd()) : dir.replace(/\\/g, '/');
+  console.log(`\n${label0} already running at ${url} (pid ${existing.pid})\n`);
+  // Open the browser anyway — matches the experience of starting fresh.
+  const cmd = process.platform === 'win32' ? `start ${url}`
+    : process.platform === 'darwin'        ? `open ${url}`
+    : `xdg-open ${url}`;
+  exec(cmd);
+  process.exit(0);
+}
+
 // --- Auto-detect MPA ---
 function detectMPA(rootDir) {
   try {
@@ -187,29 +330,6 @@ function dropTab(tabId) {
   if (t) { clearTimeout(t); staleTimers.delete(tabId); }
 }
 
-// --- .env support ---
-// Minimal dotenv parser. Skips comments/blank lines, splits on first `=`,
-// trims whitespace, strips wrapping single/double quotes. No multiline values,
-// no `${VAR}` substitution within .env itself — we just want plain KEY=VALUE.
-function parseDotenv(text) {
-  const out = {};
-  for (const rawLine of text.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith('#')) continue;
-    const eq = line.indexOf('=');
-    if (eq === -1) continue;
-    const key = line.slice(0, eq).trim();
-    if (!key) continue;
-    let value = line.slice(eq + 1).trim();
-    if ((value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1);
-    }
-    out[key] = value;
-  }
-  return out;
-}
-
 // --- File watcher ---
 const IGNORE = /node_modules|\.git/;
 try {
@@ -218,10 +338,7 @@ try {
     clearTimeout(debounce);
     debounce = setTimeout(() => {
       const ext = extname(filename).toLowerCase();
-      const base = basename(filename);
-      if (base === '.env') {
-        broadcast({ type: 'reload' });
-      } else if (ext === '.css') {
+      if (ext === '.css') {
         broadcast({ type: 'css', file: '/' + filename.replace(/\\/g, '/') });
       } else if (['.csv', '.json', '.yaml', '.yml', '.md'].includes(ext)) {
         broadcast({ type: 'data' });
@@ -239,6 +356,18 @@ function isFile(p) {
   try { return statSync(p).isFile(); } catch { return false; }
 }
 
+// Resolve a request path against `root` and refuse anything that escapes.
+// `path.join` does NOT prevent `..` traversal — `join('/a/b', '/../../etc/passwd')`
+// returns `/etc/passwd`. Use `path.resolve` + an explicit prefix check.
+// Returns the absolute path on success, or null if the request would escape root
+// (or contains a NUL byte).
+function safeResolve(urlPath) {
+  if (urlPath.includes('\0')) return null;
+  const candidate = resolve(root, '.' + urlPath);
+  if (candidate !== root && !candidate.startsWith(root + sep)) return null;
+  return candidate;
+}
+
 function serveFile(res, filePath) {
   const ext  = extname(filePath).toLowerCase();
   const mime = MIME[ext] || 'application/octet-stream';
@@ -258,28 +387,58 @@ function serveFile(res, filePath) {
   res.end(body);
 }
 
+// DNS-rebinding defence. Even though the server binds 127.0.0.1, a malicious
+// public page (attacker.com) can perform DNS rebinding: initial resolution
+// returns the attacker's IP so the dev visits it, then DNS is flipped to
+// 127.0.0.1 so subsequent fetches reach mnfst-run while the browser still
+// treats the page origin as attacker.com (giving attacker JS read access).
+// The browser sends `Host: attacker.com` after the rebind — so reject any
+// request whose Host header isn't a known-local form on our listening port.
+function isLocalHostHeader(host, port) {
+  if (!host || typeof host !== 'string') return false;
+  const allowed = new Set([
+    `127.0.0.1:${port}`,
+    `localhost:${port}`,
+    `[::1]:${port}`,
+  ]);
+  return allowed.has(host.toLowerCase());
+}
+
+// Stricter check used by state-changing endpoints (close beacon). Same
+// allowlist applied to the Origin header.
+function isLocalOrigin(origin, port) {
+  if (!origin || typeof origin !== 'string') return false;
+  const allowed = new Set([
+    `http://127.0.0.1:${port}`,
+    `http://localhost:${port}`,
+    `http://[::1]:${port}`,
+  ]);
+  return allowed.has(origin.toLowerCase());
+}
+
 // --- HTTP server ---
 const server = createServer((req, res) => {
   const urlPath = decodeURIComponent(req.url.split('?')[0]);
 
-  // Virtual /env.js — generated from .env at the project root.
-  // Loaded by HTML before manifest.data.js so window.env is populated for
-  // ${VAR} interpolation in manifest.json. Returns an empty no-op if no
-  // .env exists, so the <script src="/env.js"> tag is always safe to include.
-  if (urlPath === '/env.js') {
-    const envPath = join(root, '.env');
-    let body = 'window.env = window.env || {};';
-    try {
-      if (isFile(envPath)) {
-        const env = parseDotenv(readFileSync(envPath, 'utf8'));
-        body = `window.env = Object.assign(window.env || {}, ${JSON.stringify(env)});`;
-      }
-    } catch { /* fall through to no-op */ }
+  // Reject any request whose Host header doesn't match our listening origin —
+  // closes DNS-rebinding even though we're bound to loopback. server.address()
+  // is the source of truth for the actual port (auto-port may have shifted).
+  const listenPort = server.address()?.port;
+  if (listenPort && !isLocalHostHeader(req.headers.host, listenPort)) {
+    res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('403 Forbidden — invalid Host header');
+    return;
+  }
+
+  // Identity endpoint: lets `mnfst-run` (and `--list`) confirm that a server
+  // on a registered port really is OUR server for the expected root, not
+  // some unrelated process that happened to inherit a recycled PID/port.
+  if (urlPath === IDENTITY_PATH) {
     res.writeHead(200, {
-      'Content-Type': 'application/javascript; charset=utf-8',
+      'Content-Type': 'application/json; charset=utf-8',
       'Cache-Control': 'no-store',
     });
-    res.end(body);
+    res.end(JSON.stringify({ name: 'mnfst-run', root, pid: process.pid }));
     return;
   }
 
@@ -321,7 +480,21 @@ const server = createServer((req, res) => {
   // Close beacon: fired by the injected script's pagehide handler when a tab
   // is actually being closed/navigated away from. This is the only signal
   // that drops a tab from openTabs in normal operation.
+  // Locked to POST + same-origin: the live-reload script already POSTs (both
+  // sendBeacon and the fetch fallback), so no DX cost; this closes the
+  // CSRF-via-GET surface where a third-party page could fire <img src=...>
+  // to nuke tabs (would still need an unguessable tabId, but defence in depth).
   if (urlPath === '/__mnfst_close__') {
+    if (req.method !== 'POST') {
+      res.writeHead(405, { 'Allow': 'POST' });
+      res.end();
+      return;
+    }
+    if (listenPort && !isLocalOrigin(req.headers.origin, listenPort)) {
+      res.writeHead(403);
+      res.end();
+      return;
+    }
     const tabId = new URL(req.url, 'http://localhost').searchParams.get('tabId');
     dropTab(tabId);
     res.writeHead(204);
@@ -330,11 +503,11 @@ const server = createServer((req, res) => {
     return;
   }
 
-  const exact = join(root, urlPath);
-  if (isFile(exact)) return serveFile(res, exact);
+  const exact = safeResolve(urlPath);
+  if (exact && isFile(exact)) return serveFile(res, exact);
 
-  const index = join(root, urlPath.replace(/\/$/, ''), 'index.html');
-  if (isFile(index)) return serveFile(res, index);
+  const indexPath = safeResolve(urlPath.replace(/\/$/, '') + '/index.html');
+  if (indexPath && isFile(indexPath)) return serveFile(res, indexPath);
 
   if (spa) {
     const fallback = join(root, 'index.html');
@@ -369,6 +542,7 @@ function tryListen(p, attempt = 0) {
   const onListening = () => {
     server.removeListener('error', onError);
     const url = `http://localhost:${p}`;
+    writeRegistry(root, p);
     console.log(`\n${label} running at ${url}\n`);
     openBrowser(url);
   };
@@ -379,7 +553,17 @@ function tryListen(p, attempt = 0) {
   };
   server.once('listening', onListening);
   server.once('error', onError);
-  server.listen(p);
+  // Bind to loopback only. Without an explicit host Node listens on `::` (all
+  // interfaces), which exposes the dev server — and every file under `root` —
+  // to anyone sharing the network (café, hotel, conference, coworking).
+  server.listen(p, '127.0.0.1');
 }
 
+// Clean up the registry entry on graceful exit. process.exit() (used by
+// idle-shutdown) fires 'exit'; SIGINT/SIGTERM are translated into a
+// process.exit so the same path runs for Ctrl+C and `kill <pid>`.
+process.on('exit', () => removeRegistry(root));
+process.on('SIGINT',  () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+
 tryListen(port);