mnfst-run 1.0.20 → 1.0.21

package/package.json

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

package/serve.mjs

@@ -31,6 +31,15 @@
  *                       panel already shows the page, so a second browser tab
  *                       is just noise. Put `--no-open` in an LLM preview's
  *                       launch config to guarantee suppression.
+ *   --attach            Supervised/agent mode (e.g. an LLM preview panel that
+ *                       assigns a port and tracks the process it spawns). Never
+ *                       starts a SECOND dev server for a project already running:
+ *                       if a server for this root exists on another port, it
+ *                       binds the assigned port and reverse-proxies to that real
+ *                       server (live reload included); if it's already on the
+ *                       assigned port it just attaches; otherwise it starts one
+ *                       normally. Let the supervisor pick the port (no --port;
+ *                       it's read from PORT). Pair with `--no-open`.
  *   --list              Print all mnfst-run servers currently running on this
  *                       machine and exit.
  *
@@ -43,7 +52,7 @@
  *                     sources and updates Alpine store reactively (no reload)
  *   other           → full page reload
  */
-import { createServer, get as httpGet }  from 'http';
+import { createServer, get as httpGet, request as httpRequest }  from 'http';
 import {
   readFileSync, statSync, watch,
   existsSync, writeFileSync, unlinkSync,
@@ -226,6 +235,12 @@ let openBrowserEnabled = !(
 );
 
 let listMode = false;
+// --attach: supervised/agent mode (e.g. Claude Code's preview panel). Guarantees
+// a live server in the FOREGROUND on the requested --port: if that exact port is
+// already serving this root, stay attached to it (don't exit) instead of bailing;
+// a separate server the user started on another port is left alone. Never writes
+// or deletes the running-server registry, so it can't clobber the user's entry.
+let attachMode = 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; }
@@ -233,6 +248,7 @@ for (let i = 0; i < args.length; i++) {
   if (args[i] === '--idle-shutdown' && args[i + 1]) { idleShutdownSec = parseInt(args[++i], 10); continue; }
   if (args[i] === '--no-open') { openBrowserEnabled = false; continue; }
   if (args[i] === '--open')    { openBrowserEnabled = true;  continue; }
+  if (args[i] === '--attach') { attachMode = true; continue; }
   if (args[i] === '--list' || args[i] === '-l') { listMode = true; continue; }
   if (!args[i].startsWith('-')) dir = args[i];
 }
@@ -362,13 +378,26 @@ if (privateEnvNames.length > 0) {
   );
 }
 
-// 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 label = dir === '.' ? basename(process.cwd()) : dir.replace(/\\/g, '/');
+
+// If a server is already serving this exact root, REUSE it — never start a
+// second dev server for the same project.
+//   - manual use: print the URL and exit.
+//   - --attach (supervisor, e.g. Claude Code's preview panel): the panel only
+//     uses a server on the port it assigned us, and can't point at a server it
+//     didn't spawn. So if the existing server is on OUR port, just attach; if
+//     it's on a different port, bind our port and reverse-proxy to it — the
+//     existing server stays the only real dev server (file-watch, live reload),
+//     and the proxy is a thin pass-through the panel can track.
 const existing = await findRunningServer(root);
 if (existing) {
+  if (attachMode) {
+    if (existing.port === port) attachToExisting(existing.port);  // already on our port — just keep alive
+    else startProxy(port, existing.port);                          // bridge our port → the real server
+    await new Promise(() => {});       // block here — never fall through and start a duplicate
+  }
   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`);
+  console.log(`\n${label} already running at ${url} (pid ${existing.pid})\n`);
   // Open the browser anyway — matches the experience of starting fresh.
   // (Skipped under --no-open / Claude Code, where the preview panel is the browser.)
   if (openBrowserEnabled) {
@@ -644,8 +673,7 @@ const server = createServer((req, res) => {
 });
 
 // --- Auto-port ---
-// Human-readable label: the dir arg as given, or the cwd folder name if serving '.'
-const label = dir === '.' ? basename(process.cwd()) : dir.replace(/\\/g, '/');
+// (`label` is defined earlier, before the reuse/dedup check.)
 
 function openBrowser(url) {
   const cmd = process.platform === 'win32' ? `start ${url}`
@@ -654,6 +682,72 @@ function openBrowser(url) {
   exec(cmd);
 }
 
+// Whether THIS process owns the running-server registry entry for `root`.
+// Stays false in --attach mode (we never claim the entry), so the exit handler
+// can't delete an entry belonging to the user's own server for the same root.
+let weOwnServer = false;
+
+// --attach: the requested port is already serving this root. Stay in the
+// foreground so the supervising preview panel keeps tracking this process,
+// without owning the server — never touch its registry; just re-probe and exit
+// once it goes away.
+function attachToExisting(p) {
+  const url = `http://localhost:${p}`;
+  console.log(`\n${label} already running at ${url} — attached.\n`);
+  if (openBrowserEnabled) openBrowser(url);
+  watchUpstream(p);
+}
+
+// Exit once the server we're bridging/attached to goes away — we're only a
+// pass-through, so there's nothing to serve without it.
+function watchUpstream(upstreamPort) {
+  setInterval(async () => {
+    const id = await probeIdentity(upstreamPort);
+    if (!id || id.root !== root) {
+      console.log('\nmnfst-run: the server it was bridging has stopped — exiting.\n');
+      process.exit(0);
+    }
+  }, 5000);
+}
+
+// --attach: a real dev server for this root is already running on `upstreamPort`,
+// but the preview panel can only use a server on the port it assigned us
+// (`listenPort`). Bind that port and transparently reverse-proxy every request
+// to the real server — including the live-reload SSE stream — so the existing
+// server stays the ONE dev server and the panel still works. We don't own a
+// server, so we never touch the registry.
+function startProxy(listenPort, upstreamPort) {
+  const proxy = createServer((creq, cres) => {
+    // Rewrite host/origin to the upstream so its loopback host + same-origin
+    // checks pass (the client speaks to us on listenPort, the server on upstream).
+    const headers = { ...creq.headers, host: `localhost:${upstreamPort}` };
+    if (headers.origin) headers.origin = `http://localhost:${upstreamPort}`;
+    if (headers.referer) {
+      headers.referer = headers.referer.split(`localhost:${listenPort}`).join(`localhost:${upstreamPort}`);
+    }
+    const preq = httpRequest(
+      { host: '127.0.0.1', port: upstreamPort, method: creq.method, path: creq.url, headers },
+      (pres) => {
+        cres.writeHead(pres.statusCode || 502, pres.headers);
+        pres.pipe(cres);   // stream — keeps SSE (text/event-stream) flowing live
+      },
+    );
+    preq.on('error', () => { try { cres.writeHead(502); cres.end('mnfst-run proxy: upstream unavailable'); } catch { /* client gone */ } });
+    creq.pipe(preq);
+  });
+  proxy.on('error', (err) => {
+    console.error(`mnfst-run: could not bind proxy port ${listenPort}: ${err.code || err.message}`);
+    process.exit(1);
+  });
+  proxy.listen(listenPort, '127.0.0.1', () => {
+    console.log(
+      `\n${label} already running at http://localhost:${upstreamPort} — ` +
+      `bridged to http://localhost:${listenPort} for the preview panel.\n`,
+    );
+  });
+  watchUpstream(upstreamPort);
+}
+
 function tryListen(p, attempt = 0) {
   if (attempt > 20) {
     console.error('mnfst-run: could not find a free port after 20 attempts.');
@@ -667,14 +761,28 @@ function tryListen(p, attempt = 0) {
   const onListening = () => {
     server.removeListener('error', onError);
     const url = `http://localhost:${p}`;
+    // A successful fresh bind means WE are the server for this root — register it
+    // (so a later manual `mnfst-run` for the same project reuses it instead of
+    // starting another). In --attach we only reach here when nothing was already
+    // running, so there's no entry to clobber.
     writeRegistry(root, p);
+    weOwnServer = true;
     console.log(`\n${label} running at ${url}\n`);
     if (openBrowserEnabled) openBrowser(url);
   };
   const onError = err => {
     server.removeListener('listening', onListening);
-    if (err.code === 'EADDRINUSE') tryListen(p + 1, attempt + 1);
-    else throw err;
+    if (err.code !== 'EADDRINUSE') { throw err; }
+    // Under --attach, if the requested port is already OUR project, attach to it
+    // (stay alive) rather than spawn a duplicate on the next port up.
+    if (attachMode && attempt === 0) {
+      probeIdentity(p).then((id) => {
+        if (id && id.root === root) attachToExisting(p);
+        else tryListen(p + 1, attempt + 1);
+      });
+      return;
+    }
+    tryListen(p + 1, attempt + 1);
   };
   server.once('listening', onListening);
   server.once('error', onError);
@@ -684,10 +792,11 @@ function tryListen(p, attempt = 0) {
   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));
+// Clean up the registry entry on graceful exit — but only if we actually own it
+// (never in --attach mode, where the entry may belong to the user's server).
+// 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`.
+process.on('exit', () => { if (weOwnServer) removeRegistry(root); });
 process.on('SIGINT',  () => process.exit(0));
 process.on('SIGTERM', () => process.exit(0));