4bnode 4.2.0 → 4.2.1

package/lib/codegen.js

@@ -853,7 +853,6 @@ export const PACKAGE_VERSIONS = {
   mongoose: "^8.8.0",
   multer: "^1.4.5-lts.1",
   nodemailer: "^6.9.0",
-  resend: "^4.0.0",
   "bonjour-service": "^1.4.3",
 };
 
@@ -955,7 +954,7 @@ function openApiType(t) {
 // Build an OpenAPI 3.0 document from parsed endpoints + models.
 // endpoints: [{ method, path, fullPath, bodyFields[], queryFields[], params[], fileFields[], hasAuth }]
 // models: [{ name, fields:[{name,type,required}] }]
-export function buildOpenApiSpec({ title = "API", version = "1.0.0", endpoints = [], models = [] } = {}) {
+export function buildOpenApiSpec({ title = "API", version = "1.0.0", endpoints = [], models = [], apiKey = false } = {}) {
   const paths = {};
   for (const ep of endpoints) {
     const raw = ep.fullPath || ep.path || "/";
@@ -997,7 +996,18 @@ export function buildOpenApiSpec({ title = "API", version = "1.0.0", endpoints =
   const components = { securitySchemes: { bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" } } };
   if (Object.keys(schemas).length) components.schemas = schemas;
 
-  return { openapi: "3.0.0", info: { title, version }, servers: [{ url: "/" }], paths, components };
+  const spec = { openapi: "3.0.0", info: { title, version }, servers: [{ url: "/" }], paths, components };
+  if (apiKey) {
+    // App-wide gate: every operation needs x-api-key; JWT routes need both.
+    components.securitySchemes.apiKeyAuth = { type: "apiKey", in: "header", name: "x-api-key" };
+    spec.security = [{ apiKeyAuth: [] }];
+    for (const ops of Object.values(paths)) {
+      for (const op of Object.values(ops)) {
+        if (op.security) op.security = [{ apiKeyAuth: [], bearerAuth: [] }];
+      }
+    }
+  }
+  return spec;
 }
 
 // A self-contained, modern API documentation page rendered from the spec.
@@ -1098,6 +1108,7 @@ export function buildDocsHtml(specUrl = "openapi.json") {
   var SPEC_URL='${specUrl}';
   var COLORS={get:'#0079ff',post:'#22c55e',put:'#f59e0b',patch:'#a855f7',delete:'#ef4444',head:'#64748b',options:'#64748b'};
   var uid=0; var ITEMS=[];
+  var APIKEY=false; // set from the spec in render()
   function esc(s){return String(s==null?'':s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');}
   function typeName(sc){if(!sc)return'';if(sc.format==='binary')return'file';if(sc.$ref)return sc.$ref.split('/').pop();return sc.type||'string';}
   function paramsOf(op,where){return (op.parameters||[]).filter(function(p){return p.in===where;});}
@@ -1122,10 +1133,15 @@ export function buildDocsHtml(specUrl = "openapi.json") {
     });
     return out;
   }
+  // Auth headers a sample needs: x-api-key when the app-wide gate is on (spec
+  // top-level security), plus a Bearer token for routes behind the JWT guard.
+  function hasBearer(e){return !!(e.op.security&&e.op.security.some(function(s){return s.bearerAuth;}));}
+  function authPairs(e){var p=[];if(APIKEY)p.push("'x-api-key': '<your-api-key>'");if(hasBearer(e))p.push("'Authorization': 'Bearer <token>'");return p;}
   function curlSample(e){
     var NL=String.fromCharCode(10),BS=String.fromCharCode(92);var b=bodyForSample(e);var L=[];
     L.push("curl -X "+e.method.toUpperCase()+" '"+sampleUrl(e)+"'");
-    if(e.op.security)L.push("-H 'Authorization: Bearer <token>'");
+    if(APIKEY)L.push("-H 'x-api-key: <your-api-key>'");
+    if(hasBearer(e))L.push("-H 'Authorization: Bearer <token>'");
     if(b&&isMultipart(b)){
       // curl sets the multipart Content-Type (with boundary) itself; -F per field.
       fieldList(b).forEach(function(f){L.push("-F '"+f.name+"="+(f.file?"@/path/to/file":"")+"'");});
@@ -1144,7 +1160,7 @@ export function buildDocsHtml(specUrl = "openapi.json") {
     var h=[];
     // For multipart, never set Content-Type by hand — the browser adds the boundary.
     if(b&&!mp)h.push("    'Content-Type': 'application/json'");
-    if(e.op.security)h.push("    'Authorization': 'Bearer <token>'");
+    authPairs(e).forEach(function(x){h.push("    "+x);});
     if(h.length){L.push("  headers: {");L.push(h.join(","+NL));L.push("  },");}
     if(mp)L.push("  body: form");
     else if(b)L.push("  body: JSON.stringify("+indentBody(bodySkeleton(b.schema),"  ")+")");
@@ -1159,7 +1175,7 @@ export function buildDocsHtml(specUrl = "openapi.json") {
     L.push("const res = await axios({");
     L.push("  method: '"+e.method.toLowerCase()+"',");
     L.push("  url: '"+sampleUrl(e)+"',");
-    if(e.op.security)L.push("  headers: { 'Authorization': 'Bearer <token>' },");
+    if(authPairs(e).length)L.push("  headers: { "+authPairs(e).join(", ")+" },");
     if(mp)L.push("  data: form");
     else if(b)L.push("  data: "+indentBody(bodySkeleton(b.schema),"  "));
     L.push("});");
@@ -1174,7 +1190,7 @@ export function buildDocsHtml(specUrl = "openapi.json") {
     L.push("  method: '"+e.method.toUpperCase()+"',");
     if(mp){L.push("  data: form,");L.push("  processData: false,");L.push("  contentType: false,");}
     else if(b)L.push("  contentType: 'application/json',");
-    if(e.op.security)L.push("  headers: { 'Authorization': 'Bearer <token>' },");
+    if(authPairs(e).length)L.push("  headers: { "+authPairs(e).join(", ")+" },");
     if(b&&!mp)L.push("  data: JSON.stringify("+indentBody(bodySkeleton(b.schema),"  ")+"),");
     L.push("  success: function(data) {");
     L.push("    console.log(data);");
@@ -1258,6 +1274,7 @@ export function buildDocsHtml(specUrl = "openapi.json") {
   }
 
   function render(spec){
+    APIKEY=!!(spec.security&&spec.security.some(function(s){return s.apiKeyAuth;}));
     document.getElementById('apiTitle').textContent=(spec.info&&spec.info.title)||'API';
     document.getElementById('apiVersion').textContent='v'+((spec.info&&spec.info.version)||'1.0.0');
     ITEMS=collect(spec);
@@ -1462,12 +1479,27 @@ export default router;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Email — two backends: IntraApp(Postmaster) via the Resend API, or any SMTP
-// server via nodemailer. `type` selects the code path; `apiKeyOnly` tells the
-// dashboard to show a single API-key field (no host/port/user).
+// Email — two backends: Sancharak via its HTTP API, or any SMTP server via
+// nodemailer. `type` selects the code path; `apiKeyOnly` tells the dashboard to
+// show a single API-key field (no host/port/user).
 // ─────────────────────────────────────────────────────────────────────────────
+export const SANCHARAK_API_URL = "https://api.sancharak.com/v1/emails";
+
+// Why a Sancharak API key can't be right, or null if it looks fine. Catches the
+// common paste mistake of copying a key shown shortened (e.g. "snk_UwtPIq-5…"),
+// which otherwise fails deep inside fetch with a cryptic ByteString error.
+export function sancharakKeyProblem(key) {
+  const k = String(key || "").trim();
+  if (!k) return "A Sancharak API key is required.";
+  if (/[^!-~]/.test(k)) return k.includes("\u2026")
+    ? 'That key contains "…" — it looks shortened. Copy the full key from Sancharak (use its Copy button), not the abbreviated one shown in a list.'
+    : "That key contains spaces or non-ASCII characters. Copy the key again exactly as Sancharak shows it.";
+  if (!k.startsWith("snk_")) return 'A Sancharak API key starts with "snk_".';
+  if (k.length < 24) return "That key is too short (" + k.length + " characters) — it may be cut off. Copy the full key from Sancharak.";
+  return null;
+}
 export const MAIL_PROVIDERS = {
-  resend: { label: "IntraApp(Postmaster)", type: "resend", apiKeyOnly: true, hint: "Paste your API key (re_...). Sends via the Resend API — no SMTP host or port needed." },
+  sancharak: { label: "Sancharak", type: "sancharak", apiKeyOnly: true, hint: "Paste your Sancharak API key (snk_...). Sends over the Sancharak API — no SMTP host or port, no extra package." },
   smtp:   { label: "Custom SMTP",          type: "smtp",   host: "", port: 587, secure: false, hint: "Any SMTP server. Tick TLS for port 465, otherwise 587." },
 };
 
@@ -1486,20 +1518,54 @@ export function isOfficialMailDomain(email) {
 // is identical regardless of backend, so calling code never changes.
 export function buildMailerService() {
   return `// Unified mailer. Backend is chosen by MAIL_PROVIDER in .env:
-//   - "resend": IntraApp(Postmaster), via the Resend API  (RESEND_API_KEY, MAIL_FROM)
-//   - "smtp":   any SMTP server, via nodemailer            (SMTP_* vars)
-// Only the selected backend's package is imported (lazily), so you don't need
-// both installed. sendMail({ to, subject, html }) works the same either way.
+//   - "sancharak": the Sancharak HTTP API      (SANCHARAK_API_KEY, MAIL_FROM, MAIL_REPLY_TO)
+//   - "smtp":      any SMTP server, via nodemailer (SMTP_* vars)
+// Sancharak needs no package (it uses fetch); nodemailer is imported lazily only
+// for SMTP. sendMail({ to, subject, html }) works the same either way.
+import crypto from 'crypto';
+
 const PROVIDER = (process.env.MAIL_PROVIDER || 'smtp').toLowerCase();
+const SANCHARAK_URL = process.env.SANCHARAK_API_URL || '${SANCHARAK_API_URL}';
+
+const asList = (v) => (v == null || v === '' ? undefined : Array.isArray(v) ? v : String(v).split(',').map((x) => x.trim()).filter(Boolean));
+
+// POST one email to Sancharak. Each call gets its own Idempotency-Key, so a
+// retried request can never send the same email twice.
+async function sancharakSend({ from, to, replyTo, subject, text, html, idempotencyKey }) {
+  const key = String(process.env.SANCHARAK_API_KEY || '').trim();
+  if (!key) throw new Error('SANCHARAK_API_KEY is not set.');
+  // Header values must be plain ASCII; a key pasted in shortened form ("snk_…")
+  // would otherwise fail inside fetch with an unreadable ByteString error.
+  if (/[^!-~]/.test(key) || key.length < 24) throw new Error('SANCHARAK_API_KEY looks shortened or contains invalid characters. Copy the full key from Sancharak.');
+  const body = { from, to: asList(to), subject, stream: 'tx' };
+  if (replyTo) body.reply_to = asList(replyTo);
+  if (text) body.text = text;
+  if (html) body.html = html;
+  const res = await fetch(SANCHARAK_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: 'Bearer ' + key,
+      'Content-Type': 'application/json',
+      'Idempotency-Key': idempotencyKey || crypto.randomUUID(),
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15000),
+  });
+  const raw = await res.text();
+  let data = null;
+  try { data = raw ? JSON.parse(raw) : null; } catch { data = { raw }; }
+  if (!res.ok) {
+    const msg = (data && (data.message || data.error || (data.error && data.error.message))) || raw || res.statusText;
+    throw new Error('Sancharak ' + res.status + ': ' + (typeof msg === 'string' ? msg : JSON.stringify(msg)));
+  }
+  return data;
+}
 
 let _clientPromise = null;
 function getClient() {
   if (_clientPromise) return _clientPromise;
   _clientPromise = (async () => {
-    if (PROVIDER === 'resend') {
-      const { Resend } = await import('resend');
-      return { type: 'resend', resend: new Resend(process.env.RESEND_API_KEY) };
-    }
+    if (PROVIDER === 'sancharak') return { type: 'sancharak' };
     const nodemailer = (await import('nodemailer')).default;
     return {
       type: 'smtp',
@@ -1534,24 +1600,31 @@ export function emailTemplate({ title = '', body = '' } = {}) {
 
 // Send an email. Pass html or text (or use emailTemplate for html).
 // attachments: [{ filename, path }] or [{ filename, content }].
-export async function sendMail({ to, subject, html, text, from, cc, bcc, replyTo, attachments } = {}) {
+// idempotencyKey (Sancharak only): pass your own to make retries safe across restarts.
+export async function sendMail({ to, subject, html, text, from, cc, bcc, replyTo, attachments, idempotencyKey } = {}) {
   if (!to || !subject) throw new Error('sendMail requires { to, subject }');
   // 4brains.in is an official domain. Sending from it is only allowed once it has
   // been configured through the 4bnode dashboard/CLI with the authorization
   // password (which sets OFFICIAL_MAIL_AUTHORIZED). Direct/code use is blocked.
-  const effectiveFrom = from || (PROVIDER === 'resend' ? process.env.MAIL_FROM : (process.env.SMTP_FROM || process.env.SMTP_USER));
+  const effectiveFrom = from || (PROVIDER === 'sancharak' ? process.env.MAIL_FROM : (process.env.SMTP_FROM || process.env.SMTP_USER));
   const touchesOfficial = /4brains\\.in/i.test(String(effectiveFrom || '')) || (PROVIDER === 'smtp' && /4brains\\.in/i.test(String(process.env.SMTP_HOST || '')));
   if (touchesOfficial && !process.env.OFFICIAL_MAIL_AUTHORIZED) {
     throw new Error('The 4brains.in domain is official and cannot be used directly — configure it via the 4bnode dashboard (Email) with the authorization password.');
   }
   const client = await getClient();
-  if (client.type === 'resend') {
-    const { data, error } = await client.resend.emails.send({
-      from: from || process.env.MAIL_FROM,
-      to, cc, bcc, replyTo, subject, html, text, attachments,
+  if (client.type === 'sancharak') {
+    if (cc || bcc || (attachments && attachments.length)) {
+      throw new Error('cc, bcc and attachments are not supported by the Sancharak backend yet. Send separate emails, or use SMTP.');
+    }
+    return sancharakSend({
+      from: effectiveFrom,
+      to,
+      replyTo: replyTo || process.env.MAIL_REPLY_TO,
+      subject,
+      text,
+      html,
+      idempotencyKey,
     });
-    if (error) throw new Error(error.message || 'Resend send failed');
-    return data;
   }
   return client.transporter.sendMail({
     from: from || process.env.SMTP_FROM || process.env.SMTP_USER,
@@ -1559,11 +1632,13 @@ export async function sendMail({ to, subject, html, text, from, cc, bcc, replyTo
   });
 }
 
-// Verify the mailer is usable (SMTP handshake, or that the Resend key is set).
+// Verify the mailer is usable (SMTP handshake, or that the Sancharak key and
+// From address are set).
 export async function verifyMailer() {
   const client = await getClient();
-  if (client.type === 'resend') {
-    if (!process.env.RESEND_API_KEY) throw new Error('RESEND_API_KEY is not set.');
+  if (client.type === 'sancharak') {
+    if (!process.env.SANCHARAK_API_KEY) throw new Error('SANCHARAK_API_KEY is not set.');
+    if (!process.env.MAIL_FROM) throw new Error('MAIL_FROM is not set.');
     return true;
   }
   return client.transporter.verify();
@@ -1611,13 +1686,23 @@ export function buildDiscoveryModule() {
 //   - Clean shutdown sends TTL=0 "goodbye" packets so stale records do not linger
 //     in client caches for the record's full TTL (can be over an hour).
 //
-// Configure via .env:  BONJOUR_ENABLED=off | BONJOUR_NAME=... | BONJOUR_TYPE=http
+//   - OFF by default. Advertising only starts with BONJOUR_ENABLED=on.
+//   - On a machine with several networks (e.g. Wi-Fi AND Ethernet), mDNS is bound
+//     to ONE chosen interface (BONJOUR_INTERFACE=en0) and only that network's
+//     addresses are advertised. Otherwise a phone on Wi-Fi can be handed the
+//     Ethernet IP it cannot reach. The interface NAME is stored, not its IP, so a
+//     new DHCP lease does not break it.
+//
+// Configure via .env:
+//   BONJOUR_ENABLED=on | BONJOUR_NAME=... | BONJOUR_TYPE=http | BONJOUR_INTERFACE=en0
 
 import os from "os";
+import { execFileSync } from "child_process";
 
 let bonjour = null; // shared mDNS controller (created lazily, one per process)
 let published = null; // handle to the currently-advertised service, if any
 let BonjourCtor = null; // cached constructor after the first successful import
+let boundInterface = null; // interface name the current controller is bound to ("" = all)
 
 let selfState = {
   status: "idle", // idle | advertising | error | unsupported
@@ -1627,6 +1712,8 @@ let selfState = {
   host: null,
   txt: null,
   error: null,
+  interface: null, // { name, label, address } actually used, or null for all
+  warning: null,
 };
 
 // Import bonjour-service on demand. Returns the constructor, or null if the
@@ -1664,9 +1751,89 @@ function defaultServiceName() {
   return host ? base + " (" + host + ")" : base;
 }
 
-// On by default; opt out with BONJOUR_ENABLED=off.
+// Off by default; opt in with BONJOUR_ENABLED=on.
 export function isDiscoveryEnabled() {
-  return process.env.BONJOUR_ENABLED !== "off";
+  return process.env.BONJOUR_ENABLED === "on";
+}
+
+// Virtual / tunnel / container interfaces that never reach other LAN devices.
+const VIRTUAL_IFACE = /^(lo|utun|awdl|llw|gif|stf|anpi|ap|bridge|vmnet|vboxnet|docker|br-|veth|virbr|tun|tap|zt|tailscale|wg)/i;
+
+// macOS: map device names (en0) to their hardware port ("Wi-Fi", "Ethernet").
+let macPorts = null;
+function macHardwarePorts() {
+  if (macPorts) return macPorts;
+  macPorts = {};
+  try {
+    const out = execFileSync("networksetup", ["-listallhardwareports"], { encoding: "utf8", timeout: 3000 });
+    let current = null;
+    for (const raw of out.split(String.fromCharCode(10))) {
+      const line = raw.trim(); // trim also drops a Windows CR
+      const port = line.match(/^Hardware Port: (.+)$/);
+      if (port) current = port[1].trim();
+      const dev = line.match(/^Device: (.+)$/);
+      if (dev && current) macPorts[dev[1].trim()] = current;
+    }
+  } catch {}
+  return macPorts;
+}
+
+function interfaceKind(name) {
+  if (os.platform() === "darwin") {
+    const hw = macHardwarePorts()[name];
+    if (hw) return /wi-?fi|airport/i.test(hw) ? "Wi-Fi" : hw;
+  }
+  if (/^(wl|wlan|wifi)/i.test(name) || /wi-?fi|wireless|wlan/i.test(name)) return "Wi-Fi";
+  if (/^(eth|en|em|eno|ens|enp)/i.test(name) || /ethernet|lan/i.test(name)) return "Ethernet";
+  return "Network";
+}
+
+// Physical networks this machine is connected to, each with its IPv4 address.
+// Used by the dashboard / CLI to let the user choose which one to advertise on.
+export function listNetworkInterfaces() {
+  const all = os.networkInterfaces();
+  const result = [];
+  for (const name of Object.keys(all)) {
+    if (VIRTUAL_IFACE.test(name)) continue;
+    const addrs = all[name] || [];
+    const v4 = addrs.find((a) => a.family === "IPv4" && !a.internal);
+    if (!v4) continue;
+    const kind = interfaceKind(name);
+    result.push({
+      name,
+      kind,
+      label: kind + " (" + name + ")",
+      address: v4.address,
+      // 169.254.x.x = self-assigned: the cable/adapter is up but no network answered.
+      selfAssigned: v4.address.startsWith("169.254."),
+      ipv6: addrs.filter((a) => a.family === "IPv6" && !a.internal).map((a) => a.address),
+      mac: v4.mac,
+    });
+  }
+  return result;
+}
+
+// Resolve BONJOUR_INTERFACE to a live interface. Returns { iface, warning }:
+// iface null means "all interfaces".
+function resolveInterface() {
+  const wanted = (process.env.BONJOUR_INTERFACE || "").trim();
+  const list = listNetworkInterfaces();
+  if (wanted) {
+    const hit = list.find((i) => i.name === wanted);
+    if (hit) return { iface: hit, warning: null };
+    return {
+      iface: null,
+      warning: "Network " + JSON.stringify(wanted) + " is not connected; advertising on all networks instead.",
+    };
+  }
+  if (list.length > 1) {
+    return {
+      iface: null,
+      warning: "Several networks are connected (" + list.map((i) => i.label).join(", ") +
+        "). Advertising on all of them; choose one with BONJOUR_INTERFACE or in the dashboard.",
+    };
+  }
+  return { iface: null, warning: null };
 }
 
 // Snapshot of what this process is currently advertising (read by the dashboard).
@@ -1674,6 +1841,29 @@ export function getSelfState() {
   return { ...selfState, enabled: isDiscoveryEnabled() };
 }
 
+// (Re)create the mDNS controller bound to the chosen interface. Binding the
+// socket to 0.0.0.0 while pinning multicast to the interface IP keeps receiving
+// queries reliable on macOS/Linux.
+function ensureController(Ctor, iface) {
+  const key = iface ? iface.name : "";
+  if (bonjour && boundInterface === key) return;
+  if (bonjour) {
+    try { bonjour.destroy(); } catch {}
+  }
+  bonjour = iface ? new Ctor({ interface: iface.address, bind: "0.0.0.0" }) : new Ctor();
+  boundInterface = key;
+}
+
+// Keep only the chosen interface's addresses in A/AAAA records, so clients on
+// that network are never handed an IP from another network.
+function restrictAddresses(service, iface) {
+  if (!iface || typeof service.records !== "function") return;
+  const allowed = new Set([iface.address].concat(iface.ipv6));
+  const original = service.records.bind(service);
+  service.records = () =>
+    original().filter((r) => (r.type !== "A" && r.type !== "AAAA") || allowed.has(r.data));
+}
+
 // Advertise this app on the local network. Safe to call repeatedly; each call
 // replaces any prior advertisement, so a port change re-publishes cleanly. Must
 // be called AFTER the HTTP server is actually listening (so the port is bound).
@@ -1703,7 +1893,9 @@ export async function startAdvertising({ port, name, type } = {}) {
 
   // Replace any previous advertisement so two conflicting records never coexist.
   await stopAdvertising();
-  if (!bonjour) bonjour = new Ctor();
+  const { iface, warning } = resolveInterface();
+  ensureController(Ctor, iface);
+  if (warning) console.warn("mDNS: " + warning);
 
   const serviceName = name || defaultServiceName();
   const serviceType = type || process.env.BONJOUR_TYPE || "http";
@@ -1715,6 +1907,7 @@ export async function startAdvertising({ port, name, type } = {}) {
 
   try {
     published = bonjour.publish({ name: serviceName, type: serviceType, port, host, txt });
+    restrictAddresses(published, iface);
     selfState = {
       status: "advertising",
       name: serviceName,
@@ -1723,10 +1916,13 @@ export async function startAdvertising({ port, name, type } = {}) {
       host,
       txt,
       error: null,
+      interface: iface ? { name: iface.name, label: iface.label, address: iface.address } : null,
+      warning,
     };
     published.on("up", () => {
       console.log(
-        "mDNS: advertising " + JSON.stringify(serviceName) + " at " + host + ":" + port + " (_" + serviceType + "._tcp.local)",
+        "mDNS: advertising " + JSON.stringify(serviceName) + " at " + host + ":" + port + " (_" + serviceType + "._tcp.local)" +
+          (iface ? " on " + iface.label + " " + iface.address : " on all networks"),
       );
     });
     published.on("error", (err) => {
@@ -1776,6 +1972,7 @@ export async function destroyDiscovery() {
     if (bonjour) bonjour.destroy();
   } catch {}
   bonjour = null;
+  boundInterface = null;
 }
 
 // Browse the LAN for services of a given type. Collects results for timeoutMs
@@ -1784,7 +1981,7 @@ export async function destroyDiscovery() {
 export async function browse({ type = "http", timeoutMs = 2500 } = {}) {
   const Ctor = await loadBonjour();
   if (!Ctor) return { available: false, services: [] };
-  if (!bonjour) bonjour = new Ctor();
+  if (!bonjour) ensureController(Ctor, resolveInterface().iface);
 
   return new Promise((resolve) => {
     const found = new Map();
@@ -1894,3 +2091,1212 @@ export function wireDiscoveryIntoIndex(content) {
   return out;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// App-wide API key gate
+//
+// Every API route (login and registration included) requires a valid x-api-key
+// header. skeleton/src/middleware/apiKey.js is generated from
+// buildApiKeyMiddleware() (a test asserts they're identical), and the dashboard
+// writes the same file into older projects when it wires the gate in. Keys are
+// stored as SHA-256 hashes in src/api-keys.json; the plaintext is shown once.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildApiKeyMiddleware() {
+  return `// API key authentication.
+//
+// Every request to this app's API must carry a valid key in the x-api-key
+// header, including login and registration, unless the gate is switched off
+// with API_KEY_REQUIRED=off. Keys are created and revoked in the 4bnode
+// dashboard (Security -> API keys) and stored HASHED in src/api-keys.json, so
+// that file never holds a usable key. Revoking a key takes effect immediately.
+//
+//   index.js (whole app, built in):  app.use(apiKeyGate);
+//   a single router only:            app.use('/api/private', apiKey);
+//
+// Never needs a key: the /docs page, CORS preflight (OPTIONS) requests, the
+// /_dev dashboard, and any path prefix listed in API_KEY_PUBLIC_PATHS
+// (comma-separated, e.g. /health,/webhooks/stripe).
+//
+// Routes that need a signed-in user still check the JWT (auth middleware) on
+// top of this: the API key identifies the calling app, the JWT the user.
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { fileURLToPath } from 'url';
+
+const KEYS_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'api-keys.json');
+let _cache = { mtimeMs: -1, hashes: [] };
+
+export function hashApiKey(key) {
+  return crypto.createHash('sha256').update(String(key)).digest('hex');
+}
+
+// Read the keys file fresh when it changes (mtime-cached), so keys created or
+// revoked in the dashboard apply without a restart. Older files stored the
+// plaintext key; those entries are hashed on read.
+function loadKeyHashes() {
+  try {
+    const { mtimeMs } = fs.statSync(KEYS_FILE);
+    if (mtimeMs !== _cache.mtimeMs) {
+      const list = JSON.parse(fs.readFileSync(KEYS_FILE, 'utf8'));
+      const hashes = (Array.isArray(list) ? list : [])
+        .map((k) => k && (k.hash || (k.key ? hashApiKey(k.key) : null)))
+        .filter(Boolean);
+      _cache = { mtimeMs, hashes };
+    }
+  } catch {
+    _cache = { mtimeMs: -1, hashes: [] };
+  }
+  return _cache.hashes;
+}
+
+// Constant-time membership test over fixed-length digests: no early return,
+// so timing reveals neither which key matched nor the key length.
+function keyMatches(provided) {
+  const p = Buffer.from(hashApiKey(provided), 'hex');
+  let ok = false;
+  for (const h of loadKeyHashes()) {
+    const v = Buffer.from(h, 'hex');
+    if (v.length === p.length && crypto.timingSafeEqual(p, v)) ok = true;
+  }
+  return ok;
+}
+
+const apiKey = (req, res, next) => {
+  const provided = req.header('x-api-key');
+  if (!provided || !keyMatches(provided)) {
+    return res.status(401).json({ message: 'Invalid or missing API key' });
+  }
+  next();
+};
+
+function publicPaths() {
+  const extra = String(process.env.API_KEY_PUBLIC_PATHS || '')
+    .split(',')
+    .map((p) => p.trim())
+    .filter((p) => p.startsWith('/'));
+  return ['/_dev', '/docs'].concat(extra);
+}
+
+function isPublicPath(p) {
+  return publicPaths().some((pre) => {
+    const base = pre.length > 1 && pre.endsWith('/') ? pre.slice(0, -1) : pre;
+    return p === base || p.startsWith(base + '/');
+  });
+}
+
+// App-wide gate. Mount after static files and before any routes.
+export function apiKeyGate(req, res, next) {
+  if (process.env.API_KEY_REQUIRED === 'off') return next();
+  if (req.method === 'OPTIONS') return next();
+  if (isPublicPath(req.path)) return next();
+  return apiKey(req, res, next);
+}
+
+export default apiKey;
+`;
+}
+
+export const API_KEY_GATE_IMPORT = 'import { apiKeyGate } from "./src/middleware/apiKey.js";';
+export const API_KEY_GATE_USE = "app.use(apiKeyGate);";
+
+// Idempotently mount the gate in an index.js: right after static files (so
+// public assets stay public) and therefore before every route registration.
+export function wireApiKeyGateIntoIndex(content) {
+  let out = content;
+  if (!out.includes("apiKeyGate")) {
+    out = addImportAfterLastImport(out, API_KEY_GATE_IMPORT);
+  }
+  if (!out.includes(API_KEY_GATE_USE)) {
+    const block =
+      "// ── API key gate ────────────────────────────────────\n" +
+      "// Every API route (login/register included) needs a valid x-api-key header.\n" +
+      "// Manage keys in the /_dev dashboard → Security. API_KEY_REQUIRED=off disables.\n" +
+      API_KEY_GATE_USE;
+    const m = out.match(/^app\.use\(express\.static\(.*\);[ \t]*$/m);
+    if (m) {
+      const at = m.index + m[0].length;
+      out = out.slice(0, at) + "\n\n" + block + out.slice(at);
+    } else {
+      out = insertBeforeRoutesContent(out, block);
+    }
+  }
+  return out;
+}
+
+// New API key: "4b_" + 32 random bytes, base64url. Returned once to the user;
+// only hashApiKeyValue(key) is stored.
+export function generateApiKey(randomBytes) {
+  return "4b_" + Buffer.from(randomBytes(32)).toString("base64url");
+}
+
+export function hashApiKeyValue(key, createHash) {
+  return createHash("sha256").update(String(key)).digest("hex");
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Serial devices (Arduino / ESP32 over USB serial)
+//
+// Generated projects never hard-code a COM path. Devices are listed in
+// src/serial/devices.json and matched at connect time by USB serial number,
+// USB vendor/product id, or a firmware identity handshake; the manager
+// auto-reconnects, queues command -> reply with timeouts, and closes ports on
+// shutdown. Both the CLI (add-serialport) and the dashboard write these same
+// files and validate config with normalizeSerialDevice().
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const SERIAL_DEPS = ["serialport", "@serialport/parser-readline"];
+export const SERIAL_BAUD_RATES = [9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600];
+export const SERIAL_ROUTE_PREFIX = "/api/serial";
+// Identity command presets (also tried in this order when auto-adding a board).
+export const SERIAL_ID_PRESETS = [
+  { command: "ID?", label: "ID? (your own firmware)" },
+  { command: "M115", label: "M115 (Marlin / RepRap 3D printers)" },
+  { command: "$I", label: "$I (GRBL CNC)" },
+  { command: "ATI", label: "ATI (AT-command modems)" },
+];
+export const SERIAL_RULE_WHEN = ["contains", "equals", "startsWith", "regex"];
+export const SERIAL_RULE_ACTIONS = ["webhook", "send"];
+
+export function buildSerialDeviceModule() {
+  return `// Serial device manager for Arduino / ESP32 boards over USB serial.
+//
+// Generated by 4bnode. It follows the rules that keep serial hardware working
+// on an unattended machine:
+//   - Never hard-code a COM path. A device is MATCHED every time it connects,
+//     by USB serial number, USB vendor/product id, or a firmware identity
+//     handshake (send "ID?", read the reply). COM numbers and tty names change
+//     between reboots and USB ports; these do not.
+//   - Always read through a parser, so each "data" event is one complete line.
+//   - Every write ends with the delimiter the firmware expects.
+//   - send() is command -> reply with a timeout. Commands are queued, so only
+//     one is in flight and a reply can't be matched to the wrong command.
+//     Lines that can't be the reply are skipped: an echo of the command, the
+//     device's ignoreLines, and heartbeats it prints on its own (any line seen
+//     3+ times while idle, e.g. Marlin's "wait").
+//   - Wait out the board's auto-reset after opening before the first command.
+//   - Auto-reconnect: an unexpected close (board reset, cable pulled) re-runs
+//     find + open until the board is back, on whatever port it returns as.
+//   - Ports are probed one at a time, never in parallel, and a port this
+//     process already holds open is never probed (opening resets most boards).
+//   - Ports are closed on shutdown so the next launch can open them.
+//   - Hotplug: portWatcher notices boards being plugged in or removed, so an
+//     offline device reconnects the moment its board is attached.
+
+import { EventEmitter } from 'events';
+
+let SerialPortCtor = null;
+let ReadlineParserCtor = null;
+
+// Imported lazily: if the native serialport module is missing or fails to
+// load on this machine, the app still boots and devices just stay offline.
+async function loadSerial() {
+  if (SerialPortCtor) return true;
+  try {
+    SerialPortCtor = (await import('serialport')).SerialPort;
+    ReadlineParserCtor = (await import('@serialport/parser-readline')).ReadlineParser;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// USB bridge chips by vendor id. A hint, not proof: an ESP32 and an ESP8266
+// can both report 10c4 or 1a86, so confirm with the identity handshake.
+export const USB_VENDORS = {
+  '2341': 'Arduino',
+  '2a03': 'Arduino (.org)',
+  '303a': 'Espressif (ESP32 native USB)',
+  '10c4': 'Silicon Labs CP210x',
+  '1a86': 'WCH CH340 / CH9102',
+  '0403': 'FTDI',
+  '239a': 'Adafruit',
+  '2e8a': 'Raspberry Pi (RP2040)',
+  '0483': 'STMicroelectronics (STM32)',
+};
+
+// Replies that are clearly not an identity: firmware errors and bare acks
+// (e.g. Marlin answers an unknown command with "echo:Unknown command" + "ok").
+const NOT_AN_IDENTITY = /unknown command|invalid|not supported|error|^ok$|^echo:/i;
+
+// Identity commands tried in order when a board's command is unknown:
+// ID? (your own firmware), M115 (Marlin / RepRap 3D printers), $I (GRBL CNC),
+// ATI (AT-command modems). Override with SERIAL_ID_COMMANDS=ID?,M115
+export const ID_COMMANDS = ['ID?', 'M115', '$I', 'ATI'];
+
+export function idCommands() {
+  const env = String(process.env.SERIAL_ID_COMMANDS || '').split(',').map((c) => c.trim()).filter(Boolean);
+  return env.length ? env : ID_COMMANDS;
+}
+
+// Short, stable key for an identity reply, used to match and name a board.
+//   "LED-CTRL:2.1"                         -> "LED-CTRL"
+//   "FIRMWARE_NAME:Marlin 2.0.5.4 (GitHub)" -> "Marlin"
+//   "[VER:1.1h.20190825:]"                 -> "GRBL"
+export function identityKey(reply) {
+  const v = String(reply || '').trim();
+  if (!v) return null;
+  const fw = v.match(/FIRMWARE_NAME: *([A-Za-z0-9._-]+)/);
+  if (fw) return fw[1];
+  if (v.startsWith('[VER:')) return 'GRBL';
+  const head = v.split(/[: ]/)[0].replace(/[^A-Za-z0-9._-]/g, '');
+  return head ? head.slice(0, 40) : null;
+}
+
+const CR = String.fromCharCode(13);
+const LF = String.fromCharCode(10);
+const LINE_BREAKS = new RegExp('[' + CR + LF + ']', 'g');
+
+export function delimiterFor(name) {
+  return name === 'crlf' ? CR + LF : LF;
+}
+
+const openPaths = new Set(); // ports this process currently holds open
+// Last identity each port answered with (path -> "LED-CTRL:2.1"). Probing
+// resets most boards, so a reply is remembered until the board is unplugged.
+const identities = new Map();
+let probeChain = Promise.resolve(); // serializes probing across all devices
+
+function normId(v) {
+  return String(v || '').toLowerCase().replace(/^0x/, '');
+}
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Every serial port with its USB metadata.
+export async function listPorts() {
+  if (!(await loadSerial())) {
+    throw new Error('serialport is not installed. Run: npm install serialport @serialport/parser-readline');
+  }
+  const ports = await SerialPortCtor.list();
+  return ports.map((p) => {
+    const vendorId = normId(p.vendorId) || null;
+    return {
+      path: p.path,
+      vendorId,
+      productId: normId(p.productId) || null,
+      manufacturer: p.manufacturer || null,
+      serialNumber: p.serialNumber || null,
+      vendor: (vendorId && USB_VENDORS[vendorId]) || null,
+      usb: !!vendorId,
+      inUse: openPaths.has(p.path),
+      identity: identities.get(p.path) || null,
+    };
+  });
+}
+
+// Open a port, wait for the board's auto-reset, send the identity command and
+// return the first line it answers with, or null. Never touches an open port.
+export function probeIdentity(path, opts = {}) {
+  const baudRate = Number(opts.baudRate) || 115200;
+  const command = opts.command || 'ID?';
+  const delimiter = delimiterFor(opts.delimiter);
+  const timeout = Number(opts.timeout) || 1500;
+  const resetDelayMs = opts.resetDelayMs == null ? 1200 : Number(opts.resetDelayMs);
+  if (openPaths.has(path)) return Promise.resolve(null);
+  return loadSerial().then((ok) => {
+    if (!ok) return null;
+    return new Promise((resolve) => {
+      let done = false;
+      const port = new SerialPortCtor({ path, baudRate, autoOpen: false });
+      const parser = port.pipe(new ReadlineParserCtor({ delimiter }));
+      const finish = (result) => {
+        if (done) return;
+        done = true;
+        clearTimeout(guard);
+        openPaths.delete(path);
+        if (port.isOpen) port.close(() => resolve(result));
+        else resolve(result);
+      };
+      const guard = setTimeout(() => finish(null), resetDelayMs + timeout + 1500);
+      // Only a line that arrives AFTER the command counts. Lines the board was
+      // already sending on its own (boot banners, "wait" heartbeats) are noise,
+      // and so is a repeat of one of them after the command.
+      let sent = false;
+      const before = new Set();
+      parser.on('data', (line) => {
+        const v = String(line).trim();
+        if (!v) return;
+        if (!sent) {
+          before.add(v);
+          return;
+        }
+        if (before.has(v) || v === command || NOT_AN_IDENTITY.test(v)) return; // ignore echoes too
+        identities.set(path, v);
+        finish(v); // first real reply wins
+      });
+      port.on('error', () => finish(null));
+      port.open((err) => {
+        if (err) return finish(null);
+        openPaths.add(path);
+        setTimeout(() => {
+          if (done) return;
+          sent = true;
+          port.write(command + delimiter, (e) => { if (e) finish(null); });
+        }, resetDelayMs);
+      });
+    });
+  });
+}
+
+// ── Hotplug detection ──
+// Polls the port list (cheap: it does not open any port) and emits
+// "attach" / "detach" with the port's USB metadata. Boards already present
+// when watching starts are reported once as "attach" with initial: true.
+// Start it with watchPorts().
+export const portWatcher = new EventEmitter();
+portWatcher.setMaxListeners(100);
+let watchTimer = null;
+let knownPorts = null; // path -> port info from the last poll
+
+export function watchPorts(intervalMs = 2000) {
+  if (watchTimer) return portWatcher;
+  const poll = async () => {
+    let ports;
+    try {
+      ports = await listPorts();
+    } catch {
+      return; // serialport missing: nothing to watch
+    }
+    const now = new Map(ports.map((p) => [p.path, p]));
+    // The first poll reports boards already plugged in at startup
+    // (initial: true), so they are handled exactly like a fresh plug-in.
+    const initial = !knownPorts;
+    for (const [path, info] of now) {
+      if (initial || !knownPorts.has(path)) portWatcher.emit('attach', Object.assign({}, info, { initial }));
+    }
+    if (!initial) {
+      for (const [path, info] of knownPorts) {
+        if (now.has(path)) continue;
+        identities.delete(path); // a different board may come back on this path
+        portWatcher.emit('detach', info);
+      }
+    }
+    knownPorts = now;
+  };
+  poll();
+  watchTimer = setInterval(poll, intervalMs);
+  if (watchTimer.unref) watchTimer.unref();
+  return portWatcher;
+}
+
+export function unwatchPorts() {
+  if (watchTimer) clearInterval(watchTimer);
+  watchTimer = null;
+  knownPorts = null;
+}
+
+// Sleep for ms, but wake early when any board is plugged in.
+function waitOrAttach(ms) {
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(t);
+      portWatcher.off('attach', done);
+      resolve();
+    };
+    const t = setTimeout(done, ms);
+    portWatcher.on('attach', done);
+  });
+}
+
+// Every USB serial port with both identification layers: USB metadata
+// (vendor id, serial number) and the firmware identity (reply to idCommand).
+// Probes one port at a time, skips ports this process holds open, and reuses
+// remembered identities unless refresh is set.
+export async function listDevices(opts = {}) {
+  const ports = (await listPorts()).filter((p) => p.usb);
+  return withProbeLock(async () => {
+    const out = [];
+    for (const p of ports) {
+      let identity = p.identity;
+      if ((!identity || opts.refresh) && !p.inUse) identity = await probeIdentity(p.path, opts);
+      out.push(Object.assign({}, p, { identity: identity || null }));
+    }
+    return out;
+  });
+}
+
+// Try each identity command until one gets a real reply. Returns
+// { identity, command } or null. Each try opens the port (resets the board).
+export async function identifyBoard(path, opts = {}) {
+  const commands = opts.commands || idCommands();
+  for (const command of commands) {
+    const identity = await probeIdentity(path, Object.assign({}, opts, { command }));
+    if (identity) return { identity, command };
+  }
+  return null;
+}
+
+// Run fn with the global probe lock, so ports are never probed in parallel.
+function withProbeLock(fn) {
+  const run = probeChain.then(fn, fn);
+  probeChain = run.catch(() => {});
+  return run;
+}
+
+// Find a device's CURRENT path. Cheapest, non-intrusive checks first:
+// serialNumber, then vendorId/productId, then the identity handshake (which
+// opens ports, so it only runs on USB ports), then a fixed path.
+export async function resolvePort(match = {}, opts = {}) {
+  const ports = (await listPorts()).filter((p) => !p.inUse);
+  if (match.serialNumber) {
+    const hit = ports.find((p) => p.serialNumber === match.serialNumber);
+    return hit ? hit.path : null;
+  }
+  let candidates = ports;
+  if (match.vendorId) {
+    const vid = normId(match.vendorId);
+    const pid = normId(match.productId);
+    candidates = candidates.filter((p) => p.vendorId === vid && (!pid || p.productId === pid));
+    if (!match.identity) return candidates[0] ? candidates[0].path : null;
+  }
+  if (match.identity) {
+    const usb = candidates.filter((p) => p.usb);
+    return withProbeLock(async () => {
+      for (const p of usb) {
+        const id = await probeIdentity(p.path, opts);
+        if (id && id.includes(match.identity)) return p.path;
+      }
+      return null;
+    });
+  }
+  if (match.path) return ports.some((p) => p.path === match.path) ? match.path : null;
+  return null;
+}
+
+export class SerialDevice extends EventEmitter {
+  constructor(name, config = {}) {
+    super();
+    this.name = name;
+    this.match = config.match || {};
+    this.baudRate = Number(config.baudRate) || 115200;
+    this.delimiter = config.delimiter === 'crlf' ? 'crlf' : 'lf';
+    this.idCommand = config.idCommand || 'ID?';
+    this.timeout = Number(config.timeout) || 2000;
+    this.retryMs = Number(config.retryMs) || 3000;
+    this.openDelayMs = config.openDelayMs == null ? 1200 : Number(config.openDelayMs);
+    this.port = null;
+    this.parser = null;
+    this.path = null;
+    this.connected = false;
+    this.status = 'idle'; // idle | searching | connected | reconnecting | offline | error | stopped
+    this.error = null;
+    this.connectedAt = null;
+    this.ignoreLines = Array.isArray(config.ignoreLines) ? config.ignoreLines : [];
+    this._idle = new Map(); // line -> times seen while no command was in flight
+    this._inFlight = 0;
+    this.recent = []; // last lines sent (tx) and received (rx)
+    this.stats = {
+      connects: 0,
+      reconnects: 0,
+      bytesIn: 0,
+      bytesOut: 0,
+      linesIn: 0,
+      linesOut: 0,
+      lastRx: null,
+      lastTx: null,
+      replies: 0,
+      replyMsTotal: 0,
+      timeouts: 0,
+    };
+    this._stopped = true;
+    this._looping = false;
+    this._readyAt = 0;
+    this._queue = Promise.resolve();
+  }
+
+  start() {
+    if (!this._stopped) return;
+    this._stopped = false;
+    this._connectLoop();
+  }
+
+  async stop() {
+    this._stopped = true;
+    const port = this.port;
+    if (port && port.isOpen) await new Promise((r) => port.close(() => r()));
+    this._setStatus('stopped');
+  }
+
+  state() {
+    return {
+      name: this.name,
+      status: this.status,
+      connected: this.connected,
+      path: this.path,
+      error: this.error,
+      connectedAt: this.connectedAt,
+      match: this.match,
+      baudRate: this.baudRate,
+      delimiter: this.delimiter,
+      stats: Object.assign({}, this.stats, {
+        avgReplyMs: this.stats.replies ? Math.round(this.stats.replyMsTotal / this.stats.replies) : null,
+        uptimeMs: this.connected && this.connectedAt ? Date.now() - this.connectedAt : 0,
+      }),
+      recent: this.recent.slice(-50),
+    };
+  }
+
+  _setStatus(status, error) {
+    this.status = status;
+    this.error = error || null;
+    this.emit('status', status);
+  }
+
+  _log(dir, line) {
+    this.recent.push({ dir, line, ts: Date.now() });
+    if (this.recent.length > 1000) this.recent.splice(0, this.recent.length - 1000);
+  }
+
+  async _connectLoop() {
+    if (this._looping) return;
+    this._looping = true;
+    try {
+      while (!this._stopped && !this.connected) {
+        this._setStatus(this.status === 'reconnecting' ? 'reconnecting' : 'searching');
+        let path = null;
+        try {
+          path = await resolvePort(this.match, {
+            baudRate: this.baudRate,
+            command: this.idCommand,
+            delimiter: this.delimiter,
+          });
+        } catch (err) {
+          this._setStatus('error', err.message);
+        }
+        if (path && !this._stopped) {
+          try {
+            await this._open(path);
+          } catch (err) {
+            this._setStatus('error', err.message);
+          }
+        }
+        if (!this.connected && !this._stopped) {
+          if (this.status !== 'error') this._setStatus('offline', 'Device not found. Retrying.');
+          await waitOrAttach(this.retryMs);
+        }
+      }
+    } finally {
+      this._looping = false;
+    }
+  }
+
+  _open(path) {
+    return new Promise((resolve, reject) => {
+      const port = new SerialPortCtor({ path, baudRate: this.baudRate, autoOpen: false });
+      const parser = port.pipe(new ReadlineParserCtor({ delimiter: delimiterFor(this.delimiter) }));
+      port.open((err) => {
+        if (err) return reject(err);
+        if (this._stopped) {
+          port.close(() => {});
+          return reject(new Error('stopped'));
+        }
+        openPaths.add(path);
+        this.port = port;
+        this.parser = parser;
+        this.path = path;
+        this.connected = true;
+        this.connectedAt = Date.now();
+        this.stats.connects++;
+        if (this.stats.connects > 1) this.stats.reconnects++;
+        this._readyAt = Date.now() + this.openDelayMs; // board auto-resets on open
+        this._setStatus('connected');
+        this.emit('connect', path);
+
+        parser.on('data', (line) => {
+          const v = String(line).trim();
+          if (!v) return;
+          this.stats.linesIn++;
+          this.stats.bytesIn += Buffer.byteLength(String(line)) + delimiterFor(this.delimiter).length;
+          this.stats.lastRx = Date.now();
+          if (!this._inFlight) {
+            if (this._idle.size > 200) this._idle.clear();
+            this._idle.set(v, (this._idle.get(v) || 0) + 1);
+          }
+          this._log('rx', v);
+          this.emit('data', v);
+        });
+        port.on('close', () => {
+          openPaths.delete(path);
+          this.connected = false;
+          this.port = null;
+          this.parser = null;
+          if (!this._stopped) {
+            this.emit('disconnect');
+            this._setStatus('reconnecting');
+            this._connectLoop();
+          }
+        });
+        port.on('error', (e) => {
+          this.error = e.message;
+          if (this.listenerCount('error')) this.emit('error', e);
+        });
+        resolve();
+      });
+    });
+  }
+
+  async _waitReady() {
+    const ms = this._readyAt - Date.now();
+    if (ms > 0) await wait(ms);
+  }
+
+  _write(data) {
+    return new Promise((resolve, reject) => {
+      const port = this.port;
+      if (!this.connected || !port) return reject(new Error(this.name + ' is not connected'));
+      const line = String(data).replace(LINE_BREAKS, ''); // one command per write
+      this._log('tx', line);
+      this.stats.linesOut++;
+      this.stats.bytesOut += Buffer.byteLength(line) + delimiterFor(this.delimiter).length;
+      this.stats.lastTx = Date.now();
+      this.emit('tx', line);
+      port.write(line + delimiterFor(this.delimiter), (err) => {
+        if (err) return reject(err);
+        port.drain((e) => (e ? reject(e) : resolve())); // flush now: low-latency triggers
+      });
+    });
+  }
+
+  _enqueue(task) {
+    const run = this._queue.then(() => this._waitReady()).then(task);
+    this._queue = run.catch(() => {});
+    return run;
+  }
+
+  // Is this line noise rather than a reply to command?
+  _isNoise(line, command) {
+    return line === command || this.ignoreLines.includes(line) || (this._idle.get(line) || 0) >= 3;
+  }
+
+  // Send a command and resolve with the board's reply: the next line that is
+  // not noise, or (with opts.expect) the next line containing that text /
+  // matching that RegExp.
+  send(command, opts = {}) {
+    const ms = Number(opts.timeout) || this.timeout;
+    const expect = opts.expect;
+    const cmd = String(command);
+    return this._enqueue(() => new Promise((resolve, reject) => {
+      if (!this.connected) return reject(new Error(this.name + ' is not connected'));
+      let timer = null;
+      const started = Date.now();
+      this._inFlight++;
+      const onData = (line) => {
+        if (expect) {
+          if (expect instanceof RegExp ? !expect.test(line) : !line.includes(String(expect))) return;
+        } else if (this._isNoise(line, cmd)) {
+          return;
+        }
+        cleanup();
+        this.stats.replies++;
+        this.stats.replyMsTotal += Date.now() - started;
+        resolve(line);
+      };
+      let cleaned = false;
+      const cleanup = () => {
+        if (cleaned) return;
+        cleaned = true;
+        this._inFlight--;
+        clearTimeout(timer);
+        this.off('data', onData);
+      };
+      timer = setTimeout(() => {
+        cleanup();
+        this.stats.timeouts++;
+        reject(new Error('Timeout waiting for reply to ' + JSON.stringify(String(command))));
+      }, ms);
+      this.on('data', onData);
+      this._write(command).catch((err) => {
+        cleanup();
+        reject(err);
+      });
+    }));
+  }
+
+  // Fire-and-forget write (no reply expected).
+  write(data) {
+    return this._enqueue(() => this._write(data));
+  }
+}
+`;
+}
+
+export function buildSerialDevicesModule() {
+  return `// Serial devices for this app, configured in src/serial/devices.json, started
+// at boot and kept connected. Manage them in the /_dev dashboard
+// (Features -> SerialPort) or edit the JSON by hand; reloadSerialDevices()
+// applies changes without a restart.
+//
+// Plug and play: boards are detected as they are plugged in. A configured
+// device reconnects immediately, and an unknown board is added automatically
+// (matched by USB serial number, firmware identity, or USB vendor/product id)
+// unless SERIAL_AUTO_ADD=off.
+//
+// Use a device anywhere in the app:
+//   import { getDevice, onSerialLine } from './src/serial/devices.js';
+//   const reply = await getDevice('led').send('LED:ON');   // waits for the reply
+//   const stop = onSerialLine((e) => console.log(e.device, e.dir, e.line));
+//
+// Rules (per device, in devices.json): when a received line matches, call a
+// webhook or send a command to a device. See runRules() below.
+import fs from 'fs';
+import path from 'path';
+import { EventEmitter } from 'events';
+import { fileURLToPath } from 'url';
+import { SerialDevice, watchPorts, portWatcher, identifyBoard, identityKey, listPorts, listDevices } from './SerialDevice.js';
+
+const CONFIG_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), 'devices.json');
+const devices = new Map(); // name -> SerialDevice
+const events = []; // recent hotplug / auto-add / rule events, newest last
+let eventSeq = 0;
+let watching = false;
+
+// Every line sent or received by any device, plus status changes:
+//   { type: 'line', device, dir: 'rx' | 'tx', line, ts }
+//   { type: 'status', device, status, path, ts }
+export const serialBus = new EventEmitter();
+serialBus.setMaxListeners(200);
+
+export function onSerialLine(fn) {
+  const h = (e) => { if (e.type === 'line') fn(e); };
+  serialBus.on('event', h);
+  return () => serialBus.off('event', h);
+}
+
+export function readSerialConfig() {
+  try {
+    const list = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    return Array.isArray(list) ? list : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeSerialConfig(list) {
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(list, null, 2) + String.fromCharCode(10), 'utf8');
+}
+
+function logEvent(type, port, extra) {
+  const e = Object.assign({ id: ++eventSeq, type, ts: Date.now(), path: port.path || null, vendor: port.vendor || port.manufacturer || null, serialNumber: port.serialNumber || null }, extra || {});
+  events.push(e);
+  if (events.length > 100) events.splice(0, events.length - 100);
+  return e;
+}
+
+// Events after a given id (the dashboard polls with the last id it saw).
+export function getSerialEvents(sinceId = 0) {
+  return events.filter((e) => e.id > sinceId);
+}
+
+export function autoAddEnabled() {
+  return process.env.SERIAL_AUTO_ADD !== 'off';
+}
+
+// ── Rules ──
+// { id, enabled, when: 'contains'|'equals'|'startsWith'|'regex', pattern,
+//   action: 'webhook'|'send', url, target, command, cooldownMs }
+const ruleLastFired = new Map(); // "device|ruleId" -> ts
+const ruleStats = new Map(); // "device|ruleId" -> { fired, lastFired, lastError }
+
+function ruleMatches(rule, line) {
+  const p = String(rule.pattern || '');
+  if (!p) return false;
+  if (rule.when === 'equals') return line === p;
+  if (rule.when === 'startsWith') return line.startsWith(p);
+  if (rule.when === 'regex') {
+    try { return new RegExp(p).test(line); } catch { return false; }
+  }
+  return line.includes(p);
+}
+
+async function runRules(deviceName, line, config) {
+  const rules = (config && Array.isArray(config.rules)) ? config.rules : [];
+  for (const rule of rules) {
+    if (!rule || rule.enabled === false || !ruleMatches(rule, line)) continue;
+    const key = deviceName + '|' + rule.id;
+    const cooldown = Number(rule.cooldownMs) >= 0 ? Number(rule.cooldownMs) : 2000;
+    const last = ruleLastFired.get(key) || 0;
+    if (Date.now() - last < cooldown) continue;
+    ruleLastFired.set(key, Date.now());
+    const st = ruleStats.get(key) || { fired: 0, lastFired: null, lastError: null };
+    st.fired++;
+    st.lastFired = Date.now();
+    ruleStats.set(key, st);
+    try {
+      if (rule.action === 'webhook' && rule.url) {
+        const res = await fetch(rule.url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ device: deviceName, line, rule: rule.id, ts: Date.now() }),
+          signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok) throw new Error('webhook answered ' + res.status);
+      } else if (rule.action === 'send' && rule.target && rule.command) {
+        const target = devices.get(rule.target);
+        if (!target || !target.connected) throw new Error('device "' + rule.target + '" is offline');
+        await target.write(rule.command);
+      }
+      st.lastError = null;
+      logEvent('rule', {}, { name: deviceName, rule: rule.id, line });
+    } catch (err) {
+      st.lastError = err.message;
+      console.error('serial: rule ' + rule.id + ' on ' + deviceName + ' failed: ' + err.message);
+    }
+  }
+}
+
+export function getRuleStats(deviceName) {
+  const out = {};
+  for (const [key, st] of ruleStats) {
+    const [dev, id] = key.split('|');
+    if (dev === deviceName) out[id] = st;
+  }
+  return out;
+}
+
+// ── Auto-add ──
+// Does a configured device already claim this port?
+function claimedBy(port, config) {
+  return config.find((c) => {
+    const m = c.match || {};
+    if (m.serialNumber) return m.serialNumber === port.serialNumber;
+    if (m.path) return m.path === port.path;
+    if (m.vendorId && !m.identity) return m.vendorId === port.vendorId && (!m.productId || m.productId === port.productId);
+    return false; // identity matches can't be known without probing
+  });
+}
+
+function uniqueName(base, config) {
+  const clean = String(base || 'board').toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[^a-z]+/, '').replace(/-+$/, '') || 'board';
+  let name = clean.slice(0, 32);
+  let n = 2;
+  while (config.some((c) => c.name === name)) name = clean.slice(0, 30) + '-' + n++;
+  return name;
+}
+
+// Register a newly attached, unknown USB board as a device and connect it.
+async function autoAdd(port) {
+  if (claimedBy(port, readSerialConfig())) return;
+  // Let configured identity-matched devices try this port first.
+  await new Promise((r) => setTimeout(r, 2500));
+  const fresh = (await listPorts().catch(() => [])).find((p) => p.path === port.path);
+  if (!fresh || fresh.inUse) return;
+  if (claimedBy(fresh, readSerialConfig())) return;
+
+  const baudRate = Number(process.env.SERIAL_DEFAULT_BAUD) || 115200;
+  // Try the identity commands in turn (ID?, M115, $I, ATI) for a name and a
+  // firmware match; remember which command worked.
+  const found = fresh.identity ? { identity: fresh.identity, command: 'ID?' } : await identifyBoard(fresh.path, { baudRate });
+  const key = found ? identityKey(found.identity) : null;
+  // A configured device already matches this firmware: it will connect to the
+  // board itself (e.g. after a replug into another USB port).
+  if (key && !fresh.serialNumber && readSerialConfig().some((c) => c.match && c.match.identity && found.identity.includes(c.match.identity))) return;
+
+  let match;
+  if (fresh.serialNumber) match = { serialNumber: fresh.serialNumber };
+  else if (key) match = { identity: key, vendorId: fresh.vendorId };
+  else {
+    const sameModel = readSerialConfig().some((c) => c.match && c.match.vendorId === fresh.vendorId && c.match.productId === fresh.productId);
+    match = sameModel ? { path: fresh.path } : { vendorId: fresh.vendorId, productId: fresh.productId };
+  }
+  const name = uniqueName(key || (fresh.vendor || fresh.manufacturer || 'board').split(' ')[0], readSerialConfig());
+  const entry = { name, match, baudRate, delimiter: 'lf', idCommand: found ? found.command : 'ID?', timeout: 2000, enabled: true, auto: true };
+  const list = readSerialConfig();
+  if (list.some((c) => c.name === name) || claimedBy(fresh, list)) return;
+  list.push(entry);
+  writeSerialConfig(list);
+  logEvent('added', fresh, { name, identity: found ? found.identity : null });
+  console.log('serial: new board on ' + fresh.path + ' added as "' + name + '"');
+  await reloadSerialDevices();
+}
+
+function startWatching() {
+  if (watching) return;
+  watching = true;
+  watchPorts(2000);
+  portWatcher.on('attach', (port) => {
+    if (!port.usb) return;
+    logEvent(port.initial ? 'found' : 'attach', port);
+    console.log('serial: board ' + (port.initial ? 'found' : 'attached') + ' on ' + port.path + (port.vendor ? ' (' + port.vendor + ')' : ''));
+    if (autoAddEnabled()) autoAdd(port).catch((err) => console.error('serial: auto-add failed: ' + err.message));
+  });
+  portWatcher.on('detach', (port) => {
+    if (!port.usb) return;
+    logEvent('detach', port);
+    console.log('serial: board removed from ' + port.path);
+  });
+}
+
+// Start new devices, restart changed ones, stop removed ones.
+export async function reloadSerialDevices() {
+  startWatching();
+  const config = readSerialConfig().filter((c) => c && c.name && c.enabled !== false);
+  const wanted = new Map(config.map((c) => [c.name, c]));
+  for (const [name, dev] of devices) {
+    const next = wanted.get(name);
+    if (!next || dev.configKey !== JSON.stringify(next)) {
+      await dev.stop();
+      devices.delete(name);
+    }
+  }
+  for (const c of config) {
+    if (devices.has(c.name)) continue;
+    const dev = new SerialDevice(c.name, c);
+    dev.configKey = JSON.stringify(c);
+    dev.on('connect', (p) => console.log('serial: ' + c.name + ' connected on ' + p));
+    dev.on('disconnect', () => console.warn('serial: ' + c.name + ' disconnected, reconnecting...'));
+    dev.on('error', (e) => console.error('serial: ' + c.name + ' error: ' + e.message));
+    dev.on('status', (status) => serialBus.emit('event', { type: 'status', device: c.name, status, path: dev.path, ts: Date.now() }));
+    dev.on('tx', (line) => serialBus.emit('event', { type: 'line', device: c.name, dir: 'tx', line, ts: Date.now() }));
+    dev.on('data', (line) => {
+      serialBus.emit('event', { type: 'line', device: c.name, dir: 'rx', line, ts: Date.now() });
+      runRules(c.name, line, c);
+    });
+    devices.set(c.name, dev);
+    dev.start();
+  }
+  return listSerialDevices();
+}
+
+export const startSerialDevices = reloadSerialDevices;
+
+// Close every port (call on shutdown so the ports are free next launch).
+export async function stopSerialDevices() {
+  await Promise.all([...devices.values()].map((d) => d.stop().catch(() => {})));
+  devices.clear();
+}
+
+export function getDevice(name) {
+  return devices.get(name) || null;
+}
+
+// Re-exported for the dashboard / CLI: every USB port with USB metadata and
+// firmware identity (point 7 of the serial guide).
+export { listDevices };
+
+export function listSerialDevices() {
+  return [...devices.values()].map((d) => Object.assign(d.state(), { rules: getRuleStats(d.name) }));
+}
+`;
+}
+
+export function buildSerialRouter() {
+  return `// HTTP API for the serial devices. The backend owns the hardware; browsers and
+// other clients talk to it through these routes (covered by the API key gate).
+//   GET  /api/serial/devices               status + health of every device
+//   POST /api/serial/devices/:name/send    { "command": "ID?", "timeout": 2000 } -> { "reply": "..." }
+//   POST /api/serial/devices/:name/write   { "data": "LED:ON" } (no reply expected)
+//   GET  /api/serial/stream                live lines from every device (Server-Sent Events)
+//   GET  /api/serial/devices/:name/stream  live lines from one device
+//
+// Streams send the x-api-key header like any other request, so read them with
+// fetch() and a stream reader (EventSource cannot set headers):
+//   const res = await fetch('/api/serial/stream', { headers: { 'x-api-key': KEY } });
+//   const reader = res.body.getReader();   // each event: "data: {json}" + blank line
+import express from 'express';
+import { getDevice, listSerialDevices, serialBus } from '../serial/devices.js';
+
+const router = express.Router();
+
+router.get('/devices', (req, res) => {
+  res.json(listSerialDevices().map(({ recent, ...d }) => d));
+});
+
+router.post('/devices/:name/send', async (req, res) => {
+  const device = getDevice(req.params.name);
+  if (!device) return res.status(404).json({ message: 'Unknown device' });
+  if (!device.connected) return res.status(503).json({ message: 'Device offline' });
+  const command = req.body.command;
+  const timeout = req.body.timeout;
+  if (typeof command !== 'string' || !command.trim()) {
+    return res.status(400).json({ message: 'command is required' });
+  }
+  try {
+    const reply = await device.send(command, { timeout });
+    res.json({ reply });
+  } catch (err) {
+    res.status(504).json({ message: err.message });
+  }
+});
+
+router.post('/devices/:name/write', async (req, res) => {
+  const device = getDevice(req.params.name);
+  if (!device) return res.status(404).json({ message: 'Unknown device' });
+  if (!device.connected) return res.status(503).json({ message: 'Device offline' });
+  const data = req.body.data;
+  if (typeof data !== 'string' || !data.trim()) {
+    return res.status(400).json({ message: 'data is required' });
+  }
+  try {
+    await device.write(data);
+    res.json({ ok: true });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+});
+
+// Server-Sent Events: one "data: {json}" message per line / status change.
+function stream(req, res, only) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  });
+  res.write(': connected' + String.fromCharCode(10, 10));
+  const onEvent = (e) => {
+    if (only && e.device !== only) return;
+    res.write('data: ' + JSON.stringify(e) + String.fromCharCode(10, 10));
+  };
+  serialBus.on('event', onEvent);
+  const ping = setInterval(() => res.write(': ping' + String.fromCharCode(10, 10)), 25000);
+  req.on('close', () => {
+    clearInterval(ping);
+    serialBus.off('event', onEvent);
+  });
+}
+
+router.get('/stream', (req, res) => stream(req, res, null));
+
+router.get('/devices/:name/stream', (req, res) => {
+  if (!getDevice(req.params.name)) return res.status(404).json({ message: 'Unknown device' });
+  stream(req, res, req.params.name);
+});
+
+export default router;
+`;
+}
+
+// Validate + normalize one device entry for devices.json. Exactly one match
+// strategy is kept (vendorId may pair with identity to narrow the probe).
+// Throws a readable Error on invalid input.
+export function normalizeSerialDevice(input = {}) {
+  const name = String(input.name || "").trim();
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,39}$/.test(name)) {
+    throw new Error("Device name must start with a letter and use only letters, numbers, - or _ (max 40).");
+  }
+  const m = input.match || {};
+  const clean = (v, max = 120) => String(v == null ? "" : v).replace(/[\r\n]/g, "").trim().slice(0, max);
+  const hex = (v) => clean(v, 8).toLowerCase().replace(/^0x/, "");
+  let match;
+  if (clean(m.serialNumber)) match = { serialNumber: clean(m.serialNumber) };
+  else if (clean(m.identity)) {
+    match = { identity: clean(m.identity, 60) };
+    if (hex(m.vendorId)) match.vendorId = hex(m.vendorId);
+  } else if (hex(m.vendorId)) {
+    match = { vendorId: hex(m.vendorId) };
+    if (hex(m.productId)) match.productId = hex(m.productId);
+  } else if (clean(m.path)) match = { path: clean(m.path, 200) };
+  else throw new Error("Choose how to find the device: USB serial number, firmware identity, USB vendor id, or a fixed port path.");
+  if (match.vendorId && !/^[0-9a-f]{4}$/.test(match.vendorId)) throw new Error("USB vendor id must be 4 hex digits, e.g. 10c4.");
+  if (match.productId && !/^[0-9a-f]{4}$/.test(match.productId)) throw new Error("USB product id must be 4 hex digits.");
+
+  const baudRate = Number(input.baudRate) || 115200;
+  if (!Number.isInteger(baudRate) || baudRate < 300 || baudRate > 4000000) throw new Error("Baud rate must match the firmware's Serial.begin(), e.g. 115200.");
+  const timeout = Math.min(60000, Math.max(100, Number(input.timeout) || 2000));
+
+  // Saved commands: one-click buttons in the dashboard.
+  const commands = (Array.isArray(input.commands) ? input.commands : []).slice(0, 50)
+    .map((x) => ({ label: clean(x && x.label, 40), command: clean(x && x.command, 200), expectReply: !(x && x.expectReply === false) }))
+    .filter((x) => x.command)
+    .map((x) => ({ ...x, label: x.label || x.command }));
+
+  // Rules: when a received line matches, call a webhook or send a command.
+  const rules = (Array.isArray(input.rules) ? input.rules : []).slice(0, 50).map((r, i) => {
+    r = r || {};
+    const when = SERIAL_RULE_WHEN.includes(r.when) ? r.when : "contains";
+    const pattern = clean(r.pattern, 200);
+    if (!pattern) throw new Error("Rule " + (i + 1) + ": a pattern is required.");
+    if (when === "regex") {
+      try { new RegExp(pattern); } catch { throw new Error("Rule " + (i + 1) + ": invalid regular expression."); }
+    }
+    const action = SERIAL_RULE_ACTIONS.includes(r.action) ? r.action : "webhook";
+    const rule = {
+      id: clean(r.id, 40).replace(/[^a-zA-Z0-9_-]/g, "") || "rule-" + (i + 1),
+      enabled: r.enabled !== false,
+      when,
+      pattern,
+      action,
+      cooldownMs: Math.min(3600000, Math.max(0, Number(r.cooldownMs) >= 0 ? Number(r.cooldownMs) : 2000)),
+    };
+    if (action === "webhook") {
+      const url = clean(r.url, 500);
+      if (!/^https?:[/][/][^ ]+$/i.test(url)) throw new Error("Rule " + (i + 1) + ": webhook URL must start with http:// or https://.");
+      rule.url = url;
+    } else {
+      rule.target = clean(r.target, 40);
+      rule.command = clean(r.command, 200);
+      if (!rule.target || !rule.command) throw new Error("Rule " + (i + 1) + ": choose a device and a command to send.");
+    }
+    return rule;
+  });
+
+  const out = {
+    name,
+    match,
+    baudRate,
+    delimiter: input.delimiter === "crlf" ? "crlf" : "lf",
+    idCommand: clean(input.idCommand, 40) || "ID?",
+    timeout,
+    enabled: input.enabled !== false,
+  };
+  // Lines that are never a reply (heartbeats, banners). Heartbeats are also learned automatically.
+  const ignoreLines = (Array.isArray(input.ignoreLines) ? input.ignoreLines : String(input.ignoreLines || "").split(","))
+    .map((x) => clean(x, 80)).filter(Boolean).slice(0, 20);
+  if (ignoreLines.length) out.ignoreLines = ignoreLines;
+  if (commands.length) out.commands = commands;
+  if (rules.length) out.rules = rules;
+  if (input.auto === true) out.auto = true;
+  return out;
+}
+
+export const SERIAL_IMPORTS = [
+  'import { startSerialDevices, stopSerialDevices } from "./src/serial/devices.js";',
+  'import serialRouter from "./src/routes/serial.js";',
+];
+
+// Idempotently wire the serial devices into index.js: mount the HTTP routes
+// (after the API key gate, so hardware control is protected), start the
+// devices at boot, and close their ports on shutdown / nodemon restart.
+export function wireSerialIntoIndex(content) {
+  let out = content;
+  for (const line of SERIAL_IMPORTS) out = addImportAfterLastImport(out, line);
+  if (!out.includes("serialRouter)")) {
+    out = insertBeforeListenContent(out, [
+      "// ── Serial devices (src/serial/devices.json) ──",
+      'app.use("' + SERIAL_ROUTE_PREFIX + '", serialRouter);',
+      'startSerialDevices().catch((err) => console.error("serial:", err.message));',
+    ].join("\n"));
+  }
+  if (!out.includes("stopSerialDevices()")) {
+    if (out.includes("await destroyDiscovery();")) {
+      // Reuse the existing shutdown handlers (SIGINT/SIGTERM + nodemon SIGUSR2).
+      out = out.split("await destroyDiscovery();").join("await stopSerialDevices().catch(() => {}); await destroyDiscovery();");
+    } else {
+      out = out.trimEnd() + "\n\n" + [
+        "// Close serial ports on shutdown so they're free on the next launch.",
+        "let _serialShuttingDown = false;",
+        "async function _serialShutdown() {",
+        "  if (_serialShuttingDown) return;",
+        "  _serialShuttingDown = true;",
+        "  await stopSerialDevices().catch(() => {});",
+        "  process.exit(0);",
+        "}",
+        'process.on("SIGINT", _serialShutdown);',
+        'process.on("SIGTERM", _serialShutdown);',
+        'process.once("SIGUSR2", async () => {',
+        "  await stopSerialDevices().catch(() => {});",
+        '  process.kill(process.pid, "SIGUSR2");',
+        "});",
+      ].join("\n") + "\n";
+    }
+  }
+  return out;
+}
+
+// Legacy (pre-device-manager) ports were inlined in index.js as
+// "const x = new SerialPort({ path: ..., baudRate: ... })". Detect them so the
+// dashboard can show and remove them.
+export function hasLegacySerialPorts(content) {
+  return /new\s+SerialPort\(/.test(content);
+}