@tobq/boardclip 0.0.0-stage → 2.1.108

package/lib/mcp-installers.js

@@ -0,0 +1,284 @@
+'use strict';
+
+// MCP client installers.
+//
+// Registers (and removes) the BoardClip MCP server into each local AI client's
+// config. Almost every client uses the same shape - a JSON file with a map of
+// server-name -> { command, args } - so that case is handled by ONE shared
+// adapter factory; only Codex (TOML), VS Code (`servers` + type), and Zed
+// (nested `command` object) need variants. No Electron dependency: pure fs/os so
+// it is unit-testable and usable from the main process.
+//
+// All writes are idempotent and non-clobbering: other servers in the file are
+// preserved; only the `boardclip` entry is added/updated/removed.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SERVER_NAME = 'boardclip';
+
+function resolveRoots(overrides = {}) {
+  const home = overrides.home || os.homedir();
+  return {
+    home,
+    appData: overrides.appData || process.env.APPDATA || path.join(home, 'AppData', 'Roaming'),
+    xdgConfig: overrides.xdgConfig || process.env.XDG_CONFIG_HOME || path.join(home, '.config'),
+    library: overrides.library || path.join(home, 'Library', 'Application Support'),
+  };
+}
+
+// Per-OS location of an app's "config home" directory (where VS Code/Claude
+// Desktop/etc. keep user config), given a base folder name.
+function appConfigDir(roots, name) {
+  if (process.platform === 'win32') return path.join(roots.appData, name);
+  if (process.platform === 'darwin') return path.join(roots.library, name);
+  return path.join(roots.xdgConfig, name);
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+function entryExists(file) {
+  try { return fs.existsSync(file); } catch { return false; }
+}
+
+// --- Shared JSON-map adapter -------------------------------------------------
+// Covers clients that store servers as { [serversKey]: { name: entryValue } }.
+function jsonMapAdapter({ id, label, dirFor, fileName, serversKey = 'mcpServers', detectDirFor, buildEntry }) {
+  const configPath = roots => path.join(dirFor(roots), fileName);
+  const detectDir = detectDirFor || dirFor;
+  return {
+    id,
+    label,
+    configPath,
+    detect(roots) { return entryExists(detectDir(roots)); },
+    status(roots) {
+      const file = configPath(roots);
+      const data = readJson(file);
+      const enabled = !!(data && data[serversKey] && data[serversKey][SERVER_NAME]);
+      return { id, label, detected: this.detect(roots), enabled, configPath: file };
+    },
+    enable(command, roots) {
+      const file = configPath(roots);
+      const data = readJson(file) || {};
+      if (!data[serversKey] || typeof data[serversKey] !== 'object') data[serversKey] = {};
+      data[serversKey][SERVER_NAME] = buildEntry(command);
+      writeJsonAtomic(file, data);
+    },
+    disable(roots) {
+      const file = configPath(roots);
+      const data = readJson(file);
+      if (data && data[serversKey] && data[serversKey][SERVER_NAME]) {
+        delete data[serversKey][SERVER_NAME];
+        writeJsonAtomic(file, data);
+      }
+    },
+  };
+}
+
+// Standard { command, args, env } entry used by most clients.
+function stdEntry(command) {
+  const entry = { command: command.command, args: command.args.slice() };
+  if (command.env && Object.keys(command.env).length) entry.env = { ...command.env };
+  return entry;
+}
+
+// --- Codex (TOML) ------------------------------------------------------------
+// Minimal targeted edit: strip any existing [mcp_servers.boardclip] table and
+// append a fresh one, preserving the rest of the file (comments, other servers).
+function tomlString(value) {
+  return JSON.stringify(String(value)); // TOML basic-string escaping == JSON for these cases
+}
+
+function codexBlock(command) {
+  const lines = [`[mcp_servers.${SERVER_NAME}]`, `command = ${tomlString(command.command)}`];
+  lines.push(`args = [${command.args.map(tomlString).join(', ')}]`);
+  if (command.env && Object.keys(command.env).length) {
+    const pairs = Object.entries(command.env).map(([k, v]) => `${k} = ${tomlString(v)}`);
+    lines.push(`env = { ${pairs.join(', ')} }`);
+  }
+  return lines.join('\n');
+}
+
+function stripCodexBlock(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (/^\s*\[mcp_servers\.boardclip\]\s*$/.test(line)) { skipping = true; continue; }
+    if (skipping) {
+      if (/^\s*\[/.test(line)) skipping = false; // next table header ends the block
+      else continue;
+    }
+    out.push(line);
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '');
+}
+
+function codexAdapter() {
+  const dir = roots => path.join(roots.home, '.codex');
+  const configPath = roots => path.join(dir(roots), 'config.toml');
+  return {
+    id: 'codex',
+    label: 'Codex',
+    configPath,
+    detect(roots) { return entryExists(dir(roots)); },
+    status(roots) {
+      const text = (() => { try { return fs.readFileSync(configPath(roots), 'utf8'); } catch { return ''; } })();
+      return { id: 'codex', label: 'Codex', detected: this.detect(roots), enabled: /\[mcp_servers\.boardclip\]/.test(text), configPath: configPath(roots) };
+    },
+    enable(command, roots) {
+      const file = configPath(roots);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      let text = '';
+      try { text = fs.readFileSync(file, 'utf8'); } catch {}
+      const stripped = stripCodexBlock(text);
+      const next = `${stripped ? `${stripped}\n\n` : ''}${codexBlock(command)}\n`;
+      const tmp = `${file}.tmp`;
+      fs.writeFileSync(tmp, next);
+      fs.renameSync(tmp, file);
+    },
+    disable(roots) {
+      const file = configPath(roots);
+      let text;
+      try { text = fs.readFileSync(file, 'utf8'); } catch { return; }
+      const stripped = stripCodexBlock(text);
+      const tmp = `${file}.tmp`;
+      fs.writeFileSync(tmp, stripped ? `${stripped}\n` : '');
+      fs.renameSync(tmp, file);
+    },
+  };
+}
+
+// --- Zed (nested command object) ---------------------------------------------
+function zedAdapter() {
+  return jsonMapAdapter({
+    id: 'zed',
+    label: 'Zed',
+    dirFor: roots => path.join(roots.xdgConfig, 'zed'),
+    fileName: 'settings.json',
+    serversKey: 'context_servers',
+    buildEntry: command => ({ command: { path: command.command, args: command.args.slice(), env: command.env || {} } }),
+  });
+}
+
+// --- Adapter registry --------------------------------------------------------
+function buildAdapters() {
+  return [
+    jsonMapAdapter({
+      id: 'claude-code', label: 'Claude Code',
+      dirFor: roots => roots.home, fileName: '.claude.json',
+      detectDirFor: roots => path.join(roots.home, '.claude'),
+      buildEntry: stdEntry,
+    }),
+    codexAdapter(),
+    jsonMapAdapter({
+      id: 'claude-desktop', label: 'Claude Desktop',
+      dirFor: roots => appConfigDir(roots, 'Claude'), fileName: 'claude_desktop_config.json',
+      buildEntry: stdEntry,
+    }),
+    jsonMapAdapter({
+      id: 'vscode', label: 'VS Code',
+      dirFor: roots => path.join(appConfigDir(roots, 'Code'), 'User'), fileName: 'mcp.json',
+      serversKey: 'servers',
+      buildEntry: command => ({ type: 'stdio', ...stdEntry(command) }),
+    }),
+    jsonMapAdapter({
+      id: 'vscode-insiders', label: 'VS Code Insiders',
+      dirFor: roots => path.join(appConfigDir(roots, 'Code - Insiders'), 'User'), fileName: 'mcp.json',
+      serversKey: 'servers',
+      buildEntry: command => ({ type: 'stdio', ...stdEntry(command) }),
+    }),
+    jsonMapAdapter({
+      id: 'cursor', label: 'Cursor',
+      dirFor: roots => path.join(roots.home, '.cursor'), fileName: 'mcp.json',
+      buildEntry: stdEntry,
+    }),
+    jsonMapAdapter({
+      id: 'windsurf', label: 'Windsurf',
+      dirFor: roots => path.join(roots.home, '.codeium', 'windsurf'), fileName: 'mcp_config.json',
+      buildEntry: stdEntry,
+    }),
+    jsonMapAdapter({
+      id: 'cline', label: 'Cline',
+      dirFor: roots => path.join(appConfigDir(roots, 'Code'), 'User', 'globalStorage', 'saoudrizwan.claude-dev', 'settings'),
+      fileName: 'cline_mcp_settings.json',
+      buildEntry: stdEntry,
+    }),
+    jsonMapAdapter({
+      id: 'roo', label: 'Roo Code',
+      dirFor: roots => path.join(appConfigDir(roots, 'Code'), 'User', 'globalStorage', 'rooveterinaryinc.roo-cline', 'settings'),
+      fileName: 'mcp_settings.json',
+      buildEntry: stdEntry,
+    }),
+    zedAdapter(),
+    // NOTE: Continue is intentionally omitted. It configures MCP via a YAML list
+    // (~/.continue/config.yaml `mcpServers:` or .continue/mcpServers/*.yaml), not a
+    // JSON `mcpServers` map, so the shared adapter would write a file Continue
+    // ignores. Add a dedicated YAML adapter when supporting it for real.
+  ];
+}
+
+const ADAPTERS = buildAdapters();
+
+function byId(id) { return ADAPTERS.find(a => a.id === id) || null; }
+
+// --- Public API --------------------------------------------------------------
+function statuses(rootsOverride) {
+  const roots = resolveRoots(rootsOverride);
+  return ADAPTERS.map(a => a.status(roots));
+}
+
+function enable(id, command, rootsOverride) {
+  const adapter = byId(id);
+  if (!adapter) throw new Error(`unknown client: ${id}`);
+  adapter.enable(command, resolveRoots(rootsOverride));
+}
+
+function disable(id, rootsOverride) {
+  const adapter = byId(id);
+  if (!adapter) throw new Error(`unknown client: ${id}`);
+  adapter.disable(resolveRoots(rootsOverride));
+}
+
+// Install into every DETECTED client. Returns the ids touched.
+function enableDetected(command, rootsOverride) {
+  const roots = resolveRoots(rootsOverride);
+  const touched = [];
+  for (const adapter of ADAPTERS) {
+    if (!adapter.detect(roots)) continue;
+    try { adapter.enable(command, roots); touched.push(adapter.id); } catch {}
+  }
+  return touched;
+}
+
+// Remove from every client (used on uninstall / disable-all).
+function disableAll(rootsOverride) {
+  const roots = resolveRoots(rootsOverride);
+  for (const adapter of ADAPTERS) {
+    try { adapter.disable(roots); } catch {}
+  }
+}
+
+module.exports = {
+  SERVER_NAME,
+  ADAPTERS,
+  resolveRoots,
+  statuses,
+  enable,
+  disable,
+  enableDetected,
+  disableAll,
+  // exported for tests
+  stripCodexBlock,
+  codexBlock,
+};

package/lib/mcp-paths.js

@@ -0,0 +1,99 @@
+'use strict';
+
+// Shared filesystem locations for the MCP feature, used by BOTH the Electron app
+// and the standalone stdio helper (which is not Electron and cannot call
+// app.getPath). The app writes a discovery file on launch; the helper reads it to
+// locate the data dir + control pipe + auth secret. If the app never ran, the
+// helper falls back to the per-platform default data dir for read-only context.
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+const HOME = os.homedir();
+const CONFIG_DIR = path.join(HOME, '.boardclip');
+// BOARDCLIP_MCP_DISCOVERY overrides the discovery file location (used by tests
+// and unusual installs); otherwise it lives at ~/.boardclip/mcp.json.
+const DISCOVERY_FILE = process.env.BOARDCLIP_MCP_DISCOVERY || path.join(CONFIG_DIR, 'mcp.json');
+
+// Mirrors Electron's app.getPath('userData') for productName "BoardClip".
+function defaultDataDir() {
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA || path.join(HOME, 'AppData', 'Roaming');
+    return path.join(appData, 'BoardClip');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(HOME, 'Library', 'Application Support', 'BoardClip');
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(HOME, '.config');
+  return path.join(xdg, 'BoardClip');
+}
+
+// A stable per-user tag so concurrent OS users don't collide on one address.
+// BOARDCLIP_MCP_PIPE_TAG overrides it (test seam): an isolated QA instance can
+// run its own control channel beside the user's live app instead of colliding
+// on the per-user pipe with EADDRINUSE.
+function userTag() {
+  if (process.env.BOARDCLIP_MCP_PIPE_TAG) return String(process.env.BOARDCLIP_MCP_PIPE_TAG).replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 24) || 'u';
+  try {
+    const info = os.userInfo();
+    if (typeof info.uid === 'number' && info.uid >= 0) return String(info.uid);
+    if (info.username) return String(info.username).replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 24) || 'u';
+  } catch {}
+  return 'u';
+}
+
+// Stable, PER-USER control-channel address. The app records the actual bound path
+// in the discovery file, so the helper never recomputes this; it is only the
+// app's default choice.
+function defaultPipePath() {
+  if (process.platform === 'win32') {
+    // Per-user named pipe so concurrent Windows sessions (RDP / fast-user-switch)
+    // don't fight over one global pipe.
+    return `\\\\.\\pipe\\boardclip-mcp-${userTag()}`;
+  }
+  if (process.platform === 'darwin') {
+    // macOS $TMPDIR is already per-user; keep the short path (UDS ~104-char cap).
+    return path.join(os.tmpdir(), 'boardclip-mcp.sock');
+  }
+  // Linux/other unix: /tmp is shared + sticky, so scope the socket per user.
+  // Prefer XDG_RUNTIME_DIR (per-user, mode 0700, the canonical place for sockets).
+  const base = process.env.XDG_RUNTIME_DIR || os.tmpdir();
+  return path.join(base, `boardclip-mcp-${userTag()}.sock`);
+}
+
+function ensureConfigDir() {
+  try { fs.mkdirSync(CONFIG_DIR, { recursive: true }); } catch {}
+}
+
+function writeDiscovery(data) {
+  ensureConfigDir();
+  const tmp = `${DISCOVERY_FILE}.tmp`;
+  const json = JSON.stringify(data, null, 2);
+  fs.writeFileSync(tmp, json, { mode: 0o600 });
+  fs.renameSync(tmp, DISCOVERY_FILE);
+  try { fs.chmodSync(DISCOVERY_FILE, 0o600); } catch {}
+}
+
+function readDiscovery() {
+  try {
+    return JSON.parse(fs.readFileSync(DISCOVERY_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function clearDiscovery() {
+  try { fs.rmSync(DISCOVERY_FILE, { force: true }); } catch {}
+}
+
+module.exports = {
+  CONFIG_DIR,
+  DISCOVERY_FILE,
+  defaultDataDir,
+  defaultPipePath,
+  ensureConfigDir,
+  writeDiscovery,
+  readDiscovery,
+  clearDiscovery,
+};

package/lib/p2p-crypto.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// Body encryption for P2P sync v2. Every /delta request and response body is
+// AES-256-GCM sealed with a key derived (HKDF-SHA256) from the shared
+// `p2p_secret`, so clipboard contents are unreadable to anyone sharing the Wi-Fi.
+// The HMAC request signature (lib/hmac-auth.js) is unchanged and is computed
+// over the SEALED bytes: authentication of the request stays exactly as v1, the
+// GCM tag additionally binds the plaintext.
+//
+// Wire shape: iv(12) | tag(16) | ciphertext. A fresh random IV per message.
+
+const crypto = require('crypto');
+
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const HKDF_SALT = 'boardclip';
+const HKDF_INFO = 'boardclip-p2p-v2-aes-256-gcm';
+
+function deriveKey(secret) {
+  const material = String(secret || '');
+  if (!material) throw new Error('p2p-crypto: empty secret');
+  return Buffer.from(crypto.hkdfSync('sha256', material, HKDF_SALT, HKDF_INFO, KEY_BYTES));
+}
+
+function seal(key, plain) {
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const body = Buffer.isBuffer(plain) ? plain : Buffer.from(String(plain), 'utf8');
+  const encrypted = Buffer.concat([cipher.update(body), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), encrypted]);
+}
+
+function open(key, sealed) {
+  if (!Buffer.isBuffer(sealed) || sealed.length < IV_BYTES + TAG_BYTES) {
+    throw new Error('p2p-crypto: sealed body too short');
+  }
+  const iv = sealed.subarray(0, IV_BYTES);
+  const tag = sealed.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+  const encrypted = sealed.subarray(IV_BYTES + TAG_BYTES);
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+}
+
+function sealJson(key, value) {
+  return seal(key, Buffer.from(JSON.stringify(value), 'utf8'));
+}
+
+function openJson(key, sealed) {
+  return JSON.parse(open(key, sealed).toString('utf8'));
+}
+
+module.exports = { deriveKey, seal, open, sealJson, openJson, IV_BYTES, TAG_BYTES };

package/lib/p2p-discovery.js

@@ -0,0 +1,191 @@
+'use strict';
+
+// LAN peer discovery for P2P sync: ONE UDP socket, joined to the multicast group
+// on EVERY real IPv4 interface and announcing once per interface.
+//
+// Why per-interface: `socket.addMembership(group)` with no interface lets the OS
+// pick ONE adapter. On a Windows box with Hyper-V / WSL / VMware virtual
+// switches that pick is effectively random (2026-09-03: the live app joined on
+// the Hyper-V "Default Switch" 172.21.224.1 while the Mac's announcements were
+// arriving on Wi-Fi 192.168.1.182, so the two devices never paired and every
+// copy took the cloud path: 30-90 s instead of instant). Joining and sending on
+// each interface makes discovery independent of that pick, and re-enumerating
+// interfaces every 30 s covers Wi-Fi joining after launch and VPNs coming up.
+//
+// Unicast re-announce: the same announcement is also sent directly to every
+// address the caller passes (peers already heard from, pinned peers, tailnet
+// addresses). Multicast is often one-directional or filtered on APs; a peer that
+// heard us once, or that we know the address of, keeps hearing us regardless.
+//
+// Pure with respect to the socket + interface table (both injectable) so the
+// join/announce matrix is unit-tested without touching the network.
+
+const os = require('os');
+const dgram = require('dgram');
+
+// Tailscale hands out 100.64.0.0/10 (CGNAT). Multicast never crosses the tailnet
+// and link-local addresses are not routable peers, so neither gets a join.
+const CGNAT_RE = /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./;
+const LINK_LOCAL_RE = /^169\.254\./;
+
+function isTailscaleIp(ip) {
+  return CGNAT_RE.test(String(ip || ''));
+}
+
+function normalizeIp(ip) {
+  const value = String(ip || '');
+  return value.startsWith('::ffff:') ? value.slice(7) : value;
+}
+
+function transportFor(ip) {
+  return isTailscaleIp(normalizeIp(ip)) ? 'tailnet' : 'lan';
+}
+
+// Every non-internal IPv4 address that can carry LAN multicast, with its
+// adapter name. `table` is `os.networkInterfaces()` (injectable for tests).
+function lanInterfaces(table = os.networkInterfaces()) {
+  const out = [];
+  for (const [name, addrs] of Object.entries(table || {})) {
+    for (const addr of Array.isArray(addrs) ? addrs : []) {
+      if (!addr || addr.internal || !addr.address) continue;
+      if (addr.family !== 'IPv4' && addr.family !== 4) continue;
+      if (LINK_LOCAL_RE.test(addr.address) || isTailscaleIp(addr.address)) continue;
+      out.push({ name, address: addr.address });
+    }
+  }
+  return out;
+}
+
+function createDiscovery({
+  group,
+  port,
+  ttl = 1,
+  interfaces = lanInterfaces,
+  createSocket = () => dgram.createSocket({ type: 'udp4', reuseAddr: true }),
+  onMessage = () => {},
+  onError = () => {},
+  log = () => {},
+  refreshIntervalMs = 30 * 1000,
+  setInterval: schedule = setInterval,
+  clearInterval: unschedule = clearInterval,
+} = {}) {
+  if (!group || !port) throw new Error('createDiscovery needs group + port');
+  let socket = null;
+  let refreshTimer = null;
+  const joined = new Map(); // interface ip -> adapter name
+
+  async function start() {
+    if (socket) return;
+    socket = createSocket();
+    socket.on('message', (message, rinfo) => onMessage(message, rinfo));
+    socket.on('error', error => onError(error));
+    await new Promise((resolve, reject) => {
+      socket.once('error', reject);
+      socket.bind(port, () => {
+        socket.off('error', reject);
+        resolve();
+      });
+    });
+    try { socket.setMulticastTTL(ttl); } catch {}
+    // Two instances on one host (the hermetic two-instance QA) must hear each
+    // other; loopback is the default but make it explicit.
+    try { socket.setMulticastLoopback(true); } catch {}
+    refresh();
+    refreshTimer = schedule(refresh, refreshIntervalMs);
+    if (refreshTimer && refreshTimer.unref) refreshTimer.unref();
+  }
+
+  // (Re)join the group on every current interface; leave interfaces that went
+  // away. Returns what changed so callers can log it.
+  function refresh() {
+    if (!socket) return { joined: [], added: [], dropped: [] };
+    const wanted = new Map(interfaces().map(iface => [iface.address, iface.name]));
+    const added = [];
+    const dropped = [];
+    for (const [ip, name] of wanted) {
+      if (joined.has(ip)) continue;
+      try {
+        socket.addMembership(group, ip);
+        joined.set(ip, name);
+        added.push({ name, address: ip });
+      } catch (error) {
+        log('join.error', { name, address: ip, error: error && error.message });
+      }
+    }
+    for (const ip of [...joined.keys()]) {
+      if (wanted.has(ip)) continue;
+      try { socket.dropMembership(group, ip); } catch {}
+      dropped.push({ name: joined.get(ip), address: ip });
+      joined.delete(ip);
+    }
+    if (added.length || dropped.length) {
+      log('interfaces', { joined: joinedInterfaces(), added, dropped });
+    }
+    return { joined: [...joined.keys()], added, dropped };
+  }
+
+  function sendTo(body, targetPort, host, label) {
+    socket.send(body, 0, body.length, targetPort, host, error => {
+      if (error) log('send.error', { target: label, host, port: targetPort, error: error && error.message });
+    });
+  }
+
+  // Multicast once per joined interface, then unicast to every explicit target
+  // ({ host, port? }). Returns how many sends were issued.
+  function announce(body, { unicast = [] } = {}) {
+    if (!socket) return 0;
+    let sent = 0;
+    for (const ip of joined.keys()) {
+      try {
+        socket.setMulticastInterface(ip);
+        sendTo(body, port, group, `multicast via ${ip}`);
+        sent++;
+      } catch (error) {
+        log('send.error', { target: `multicast via ${ip}`, error: error && error.message });
+      }
+    }
+    if (!joined.size) {
+      // No usable interface (yet): let the OS pick, exactly the old behaviour.
+      try { sendTo(body, port, group, 'multicast default'); sent++; } catch {}
+    }
+    const seen = new Set();
+    for (const target of Array.isArray(unicast) ? unicast : []) {
+      const host = normalizeIp(target && target.host);
+      const targetPort = Number(target && target.port) || port;
+      if (!host || seen.has(`${host}:${targetPort}`)) continue;
+      seen.add(`${host}:${targetPort}`);
+      try { sendTo(body, targetPort, host, 'unicast'); sent++; } catch {}
+    }
+    return sent;
+  }
+
+  function joinedInterfaces() {
+    return [...joined.entries()].map(([address, name]) => ({ name, address }));
+  }
+
+  function stop() {
+    if (refreshTimer) unschedule(refreshTimer);
+    refreshTimer = null;
+    joined.clear();
+    const current = socket;
+    socket = null;
+    try { if (current) current.close(); } catch {}
+  }
+
+  return {
+    start,
+    stop,
+    refresh,
+    announce,
+    joinedInterfaces,
+    get running() { return !!socket; },
+  };
+}
+
+module.exports = {
+  createDiscovery,
+  lanInterfaces,
+  isTailscaleIp,
+  normalizeIp,
+  transportFor,
+};