mnfst-run 1.0.19 → 1.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnfst-run",
-  "version": "1.0.19",
+  "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,
@@ -123,13 +132,23 @@ const LIVE_RELOAD_SCRIPT = `<script>
 })();
 \x3c/script>`;
 
-// Read a dotenv-style file from the project root and return a plain object.
-// Used to populate `window.env` in served HTML so manifest.json's `${VAR}`
-// placeholders resolve at runtime — matching the documented developer-facing
-// behaviour without requiring a build step. Returns {} when the file is
-// absent or fails to parse.
+// Read a dotenv-style file from the project root and return two maps: `public`
+// (vars eligible to ship to the browser) and `private` (vars kept server-side).
+// Only the public map is injected into `window.env`; the private map is logged
+// at startup so devs can see what was withheld, but never reaches HTML.
 //
-// Supported subset (intentionally minimal, no expansion / multiline / etc.):
+// Public/private split is by name prefix — matching the established convention
+// (Astro `PUBLIC_`, SvelteKit `PUBLIC_`, Vite `VITE_`, Next `NEXT_PUBLIC_`):
+//   - PUBLIC_FOO=…   → exposed via window.env.PUBLIC_FOO
+//   - MANIFEST_API_KEY=…, STRIPE_SECRET=…, anything else → server-side only
+//
+// Rationale: prior versions injected the entire .env, so the scaffold's own
+// MANIFEST_API_KEY (which create-starter writes with a "treat like a password"
+// comment) was visible in view-source on every served page. The prefix gate
+// makes the rule explicit at the call site rather than relying on devs to know
+// that .env values reach the browser.
+//
+// Supported parse subset (intentionally minimal, no expansion / multiline):
 //   - KEY=value                  (whitespace around `=` ok)
 //   - KEY="quoted"  /  KEY='…'   (surrounding quotes stripped)
 //   - # comments and blank lines ignored
@@ -142,8 +161,9 @@ const LIVE_RELOAD_SCRIPT = `<script>
 // by the host. See the Appwrite setup doc for the full pattern.
 function loadEnvFile(rootDir) {
   const envPath = join(rootDir, '.env');
-  if (!existsSync(envPath)) return {};
-  const env = {};
+  if (!existsSync(envPath)) return { public: {}, private: [] };
+  const publicEnv = {};
+  const privateNames = [];
   try {
     const text = readFileSync(envPath, 'utf8');
     for (const line of text.split(/\r?\n/)) {
@@ -158,22 +178,24 @@ function loadEnvFile(rootDir) {
           (value.startsWith("'") && value.endsWith("'"))) {
         value = value.slice(1, -1);
       }
-      env[key] = value;
+      if (key.startsWith('PUBLIC_')) publicEnv[key] = value;
+      else privateNames.push(key);
     }
   } catch (error) {
     console.warn('[mnfst-run] Failed to parse .env:', error.message);
   }
-  return env;
+  return { public: publicEnv, private: privateNames };
 }
 
-// Build a `<script>window.env = {…};</script>` tag from a parsed env map.
-// Returns '' when there are no vars (so the injection is a no-op for projects
-// without a .env). Escapes any `</script` substring inside string values so an
-// env value can't break out of the script tag.
-function buildEnvInjectScript(envVars) {
-  const keys = Object.keys(envVars);
+// Build a `<script>window.env = {…};</script>` tag from the public env map.
+// Returns '' when there are no public vars (so the injection is a no-op for
+// projects whose .env contains only server-side secrets). Escapes any
+// `</script` substring inside string values so an env value can't break out
+// of the script tag.
+function buildEnvInjectScript(publicEnv) {
+  const keys = Object.keys(publicEnv);
   if (keys.length === 0) return '';
-  const json = JSON.stringify(envVars).replace(/<\/script/gi, '<\\/script');
+  const json = JSON.stringify(publicEnv).replace(/<\/script/gi, '<\\/script');
   return `<script>window.env = ${json};</script>`;
 }
 
@@ -213,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; }
@@ -220,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];
 }
@@ -331,22 +360,44 @@ const root = resolve(process.cwd(), dir);
 
 // Load .env from the serving root (if present) and pre-build the inject
 // script. Kept as a single string so serveFile doesn't re-stringify on every
-// HTML response. Empty string when no .env exists — the injection step
-// becomes a no-op for projects that don't use env vars.
-const envVars = loadEnvFile(root);
-const envInjectScript = buildEnvInjectScript(envVars);
-const envCount = Object.keys(envVars).length;
-if (envCount > 0) {
-  console.log(`Loaded ${envCount} env var(s) from .env into window.env`);
+// HTML response. Empty string when no public vars exist — the injection step
+// becomes a no-op for projects whose .env holds only server-side secrets.
+const { public: publicEnv, private: privateEnvNames } = loadEnvFile(root);
+const envInjectScript = buildEnvInjectScript(publicEnv);
+const publicCount = Object.keys(publicEnv).length;
+if (publicCount > 0) {
+  console.log(`Loaded ${publicCount} PUBLIC_ env var(s) into window.env`);
+}
+if (privateEnvNames.length > 0) {
+  // Loud about what was withheld so devs notice when something they expected
+  // in the browser is server-side only — and so a misplaced PUBLIC_ prefix is
+  // obvious from the startup log.
+  console.log(
+    `[mnfst-run] ${privateEnvNames.length} non-PUBLIC_ var(s) NOT injected ` +
+    `into window.env (kept server-side): ${privateEnvNames.join(', ')}`
+  );
 }
 
-// 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) {
@@ -467,11 +518,12 @@ function serveFile(res, filePath) {
     // Only inject into full HTML documents — not component fragments
     const isFullDoc = /<!doctype\s/i.test(html) || /<html[\s>]/i.test(html);
     if (isFullDoc) {
-      // 1) Inject window.env into <head> (when .env present) so the
+      // 1) Inject window.env into <head> (when public env vars exist) so the
       //    framework's manifest.json env-var substitution can resolve
       //    `${VAR}` placeholders before any plugin reads the manifest.
       //    Must come BEFORE framework scripts execute — <head> insertion
       //    guarantees that ordering regardless of where script tags sit.
+      //    ONLY PUBLIC_-prefixed vars are eligible; see loadEnvFile().
       let injected = html;
       if (envInjectScript) {
         injected = injected.includes('</head>')
@@ -621,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}`
@@ -631,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.');
@@ -644,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);
@@ -661,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));