localpeek 1.0.0

package/src/logger.js

@@ -0,0 +1,208 @@
+'use strict';
+
+// CAVEMAN: No color/UI dependency. Hand-rolled ANSI + box drawing.
+// Falls back to plain text when the terminal can't handle it
+// (non-TTY, NO_COLOR, dumb terminals, piped output).
+
+const supportsColor =
+  process.stdout.isTTY &&
+  process.env.TERM !== 'dumb' &&
+  !('NO_COLOR' in process.env);
+
+const isTTY = Boolean(process.stdout.isTTY);
+
+function wrap(code) {
+  return (str) => (supportsColor ? `\u001b[${code}m${str}\u001b[0m` : String(str));
+}
+
+const colors = {
+  reset: wrap('0'),
+  bold: wrap('1'),
+  dim: wrap('2'),
+  italic: wrap('3'),
+  green: wrap('32'),
+  yellow: wrap('33'),
+  red: wrap('31'),
+  cyan: wrap('36'),
+  magenta: wrap('35'),
+  blue: wrap('34'),
+  gray: wrap('90'),
+  white: wrap('97'),
+};
+
+// Compose helpers, e.g. colors.boldCyan('x')
+colors.boldCyan = (s) => colors.bold(colors.cyan(s));
+colors.boldWhite = (s) => colors.bold(colors.white(s));
+
+const symbols = {
+  check: supportsColor ? '✓' : 'v',
+  cross: supportsColor ? '✗' : 'x',
+  warn: '!',
+  arrow: supportsColor ? '→' : '->',
+  bullet: supportsColor ? '›' : '-',
+  dot: '·',
+};
+
+// Visible-length helper: strips ANSI codes before measuring, so
+// padding/box math isn't thrown off by color codes.
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\u001b\[[0-9;]*m/g, '');
+}
+
+function visibleLength(str) {
+  return stripAnsi(str).length;
+}
+
+function padEndVisible(str, width) {
+  const len = visibleLength(str);
+  return len >= width ? str : str + ' '.repeat(width - len);
+}
+
+// ---------------------------------------------------------------
+// Basic lines
+// ---------------------------------------------------------------
+
+function blank() {
+  console.log('');
+}
+
+function raw(msg) {
+  console.log(msg);
+}
+
+function info(msg) {
+  console.log(`  ${msg}`);
+}
+
+function success(msg) {
+  console.log(`  ${colors.green(symbols.check)} ${msg}`);
+}
+
+function warn(msg) {
+  console.log(`  ${colors.yellow(symbols.warn)} ${msg}`);
+}
+
+function error(msg) {
+  console.error(`  ${colors.red(symbols.cross)} ${msg}`);
+}
+
+function line(label, value) {
+  const padded = label.padEnd(11, ' ');
+  console.log(`  ${colors.dim(padded)} ${value}`);
+}
+
+function step(n, msg) {
+  console.log(`  ${colors.dim(`${n}.`)} ${msg}`);
+}
+
+// ---------------------------------------------------------------
+// Banner — small, premium, not full ASCII-art bloat
+// ---------------------------------------------------------------
+
+function banner(version, author) {
+  blank();
+  raw(`  ${colors.boldCyan('▲ LocalPeek')} ${colors.dim(`v${version}`)}`);
+  if (author) raw(`  ${colors.dim(`by ${author}`)}`);
+  blank();
+}
+
+// ---------------------------------------------------------------
+// Boxed panel (rounded corners), auto-sized to content
+// ---------------------------------------------------------------
+
+/**
+ * Draws a rounded box around `lines` (array of pre-formatted strings,
+ * color codes allowed). Optional `title` renders inline on the top
+ * border, like a labeled panel.
+ */
+function box(lines, { title: boxTitle, minWidth = 0, padding = 1 } = {}) {
+  const contentWidth = Math.max(
+    minWidth,
+    ...lines.map(visibleLength),
+    boxTitle ? visibleLength(boxTitle) + 2 : 0
+  );
+  const innerWidth = contentWidth + padding * 2;
+
+  const top = boxTitle
+    ? `╭─ ${colors.bold(boxTitle)} ${'─'.repeat(Math.max(0, innerWidth - visibleLength(boxTitle) - 3))}╮`
+    : `╭${'─'.repeat(innerWidth)}╮`;
+  const bottom = `╰${'─'.repeat(innerWidth)}╯`;
+
+  raw(`  ${top}`);
+  for (const l of lines) {
+    const padded = padEndVisible(l, contentWidth);
+    raw(`  │${' '.repeat(padding)}${padded}${' '.repeat(padding)}│`);
+  }
+  raw(`  ${bottom}`);
+}
+
+// ---------------------------------------------------------------
+// Spinner — for "detecting project", "starting dev server", etc.
+// No-op animation when not a TTY (just prints the label once).
+// ---------------------------------------------------------------
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+function createSpinner(initialText) {
+  let text = initialText;
+  let frame = 0;
+  let timer = null;
+  let active = false;
+
+  function render() {
+    const f = colors.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length]);
+    process.stdout.write(`\r  ${f} ${text}${' '.repeat(4)}`);
+    frame += 1;
+  }
+
+  return {
+    start() {
+      if (!isTTY) {
+        raw(`  ${symbols.dot} ${text}`);
+        return this;
+      }
+      active = true;
+      render();
+      timer = setInterval(render, 80);
+      return this;
+    },
+    update(newText) {
+      text = newText;
+      if (!isTTY) {
+        raw(`  ${symbols.dot} ${text}`);
+      }
+      return this;
+    },
+    stop(finalText, kind = 'success') {
+      if (active) {
+        clearInterval(timer);
+        active = false;
+        // Clear the spinner line.
+        process.stdout.write('\r' + ' '.repeat(text.length + 8) + '\r');
+      }
+      if (finalText) {
+        if (kind === 'success') success(finalText);
+        else if (kind === 'warn') warn(finalText);
+        else info(finalText);
+      }
+    },
+  };
+}
+
+module.exports = {
+  colors,
+  symbols,
+  blank,
+  raw,
+  info,
+  success,
+  warn,
+  error,
+  line,
+  step,
+  banner,
+  box,
+  createSpinner,
+  visibleLength,
+};

package/src/network.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const os = require('os');
+const { NoLanInterfaceError } = require('./errors.js');
+
+// CAVEMAN: Do not assume the first network adapter is Wi-Fi.
+// os.networkInterfaces() order is not guaranteed to mean anything.
+// We score candidates instead of trusting position.
+
+// Interface name patterns that usually mean "not a real LAN link
+// a phone could reach" — virtual machines, containers, tunnels.
+const VIRTUAL_NAME_PATTERNS = [
+  /^docker/i,
+  /^br-/i,
+  /^veth/i,
+  /^vmnet/i,
+  /^vboxnet/i,
+  /virtualbox/i,
+  /^vEthernet/i,
+  /hyper-?v/i,
+  /^utun/i, // often VPN tunnels on macOS
+  /^tun\d*/i,
+  /^tap\d*/i,
+  /^wsl/i,
+  /loopback/i,
+  /^lo$/i,
+  /^anpi/i, // some macOS internal
+  /^awdl/i, // Apple Wireless Direct Link, not a normal LAN
+  /^llw/i,
+  /^bridge/i,
+  /^zt/i, // ZeroTier virtual adapter
+  /^tailscale/i,
+];
+
+// Names that strongly suggest a real, physical, LAN-facing link.
+const PREFERRED_NAME_PATTERNS = [
+  /^wi-?fi/i,
+  /^wlan/i,
+  /^en0$/i, // common macOS Wi-Fi name
+  /^eth\d*/i,
+  /^ethernet/i,
+  /^en\d+/i,
+];
+
+function looksVirtual(name) {
+  return VIRTUAL_NAME_PATTERNS.some((re) => re.test(name));
+}
+
+function looksPreferred(name) {
+  return PREFERRED_NAME_PATTERNS.some((re) => re.test(name));
+}
+
+/**
+ * Returns a list of candidate LAN IPv4 addresses, best guess first.
+ * Each candidate: { address, iface, score }
+ */
+function getLanCandidates() {
+  const interfaces = os.networkInterfaces();
+  const candidates = [];
+
+  for (const [name, addrs] of Object.entries(interfaces)) {
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family !== 'IPv4') continue;
+      if (addr.internal) continue; // skips 127.0.0.1
+      if (addr.address.startsWith('127.')) continue;
+
+      let score = 0;
+      if (looksVirtual(name)) score -= 10;
+      if (looksPreferred(name)) score += 5;
+
+      // Private LAN ranges are what we actually want.
+      const isPrivateA = addr.address.startsWith('10.');
+      const isPrivateB = /^172\.(1[6-9]|2\d|3[0-1])\./.test(addr.address);
+      const isPrivateC = addr.address.startsWith('192.168.');
+      const isLinkLocal = addr.address.startsWith('169.254.');
+
+      if (isLinkLocal) {
+        // 169.254.x.x means no DHCP lease — usually not reachable
+        // from another device in a useful way.
+        score -= 8;
+      } else if (isPrivateA || isPrivateB || isPrivateC) {
+        score += 3;
+      }
+
+      candidates.push({ address: addr.address, iface: name, score });
+    }
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates;
+}
+
+/**
+ * Picks the best LAN address, or throws NoLanInterfaceError.
+ * If `preferredIface` is given (via --iface flag), it wins when present.
+ */
+function getBestLanAddress(preferredIface) {
+  const candidates = getLanCandidates();
+
+  if (candidates.length === 0) {
+    throw new NoLanInterfaceError();
+  }
+
+  if (preferredIface) {
+    const match = candidates.find((c) => c.iface === preferredIface);
+    if (match) return match;
+  }
+
+  return candidates[0];
+}
+
+module.exports = { getLanCandidates, getBestLanAddress };

package/src/port.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const net = require('net');
+const http = require('http');
+
+// CAVEMAN: Do not kill random processes because a port is busy.
+// We only ever *check* ports here, never terminate anything.
+
+/**
+ * Resolves true if the port is free to bind on all interfaces.
+ */
+function isPortFree(port, host = '0.0.0.0') {
+  return new Promise((resolve) => {
+    const tester = net.createServer();
+    tester.once('error', () => resolve(false));
+    tester.once('listening', () => {
+      tester.close(() => resolve(true));
+    });
+    try {
+      tester.listen(port, host);
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * Finds the first free port starting at `start`, scanning upward.
+ * Gives up after `maxTries` attempts.
+ */
+async function findFreePort(start, maxTries = 20) {
+  let port = start;
+  for (let i = 0; i < maxTries; i++) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await isPortFree(port)) return port;
+    port += 1;
+  }
+  return null;
+}
+
+/**
+ * Best-effort check for whether something already listening on
+ * `port` looks like it could be serving the current project.
+ * This is a heuristic only — we ask for `/` and look at headers,
+ * never anything that could be treated as "safe to reuse" blindly.
+ * Returns true/false. Never throws.
+ */
+function probeExistingServer(port, host = '127.0.0.1', timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const req = http.get(
+      { host, port, path: '/', timeout: timeoutMs },
+      (res) => {
+        res.resume();
+        resolve(true);
+      }
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on('error', () => resolve(false));
+  });
+}
+
+module.exports = { isPortFree, findFreePort, probeExistingServer };

package/src/qr.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const qrcodeTerminal = require('qrcode-terminal');
+
+// CAVEMAN: QR must contain the real LAN IP, never 0.0.0.0 or localhost.
+// The caller (server.js/cli.js) is responsible for passing the right
+// URL in — this module just renders whatever string it is given.
+
+/**
+ * Renders a QR code to the terminal for `url` and resolves with the
+ * ASCII-art string (also printed as a side effect of qrcode-terminal).
+ */
+function printQr(url) {
+  return new Promise((resolve) => {
+    qrcodeTerminal.generate(url, { small: true }, (qrString) => {
+      resolve(qrString);
+    });
+  });
+}
+
+module.exports = { printQr };

package/src/server.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const { startStaticServer } = require('./adapters/html.js');
+const viteAdapter = require('./adapters/vite.js');
+const nextAdapter = require('./adapters/next.js');
+const astroAdapter = require('./adapters/astro.js');
+const genericAdapter = require('./adapters/generic.js');
+const { isPortFree } = require('./port.js');
+const { ServerStartError } = require('./errors.js');
+
+const ADAPTERS = {
+  vite: viteAdapter,
+  next: nextAdapter,
+  astro: astroAdapter,
+  generic: genericAdapter,
+};
+
+const DEFAULT_PORTS = {
+  html: 4000,
+  vite: viteAdapter.DEFAULT_PORT,
+  next: nextAdapter.DEFAULT_PORT,
+  astro: astroAdapter.DEFAULT_PORT,
+  generic: 3000,
+};
+
+function defaultPortFor(type) {
+  return DEFAULT_PORTS[type] || 3000;
+}
+
+/**
+ * Waits until something is listening on `port` (i.e. isPortFree
+ * returns false), polling every `intervalMs`, up to `timeoutMs`.
+ * Resolves true if it became busy (server is up), false on timeout.
+ */
+function waitUntilListening(port, timeoutMs = 30000, intervalMs = 300) {
+  const start = Date.now();
+  return new Promise((resolve) => {
+    const check = async () => {
+      const free = await isPortFree(port);
+      if (!free) {
+        resolve(true);
+        return;
+      }
+      if (Date.now() - start > timeoutMs) {
+        resolve(false);
+        return;
+      }
+      setTimeout(check, intervalMs);
+    };
+    check();
+  });
+}
+
+// CAVEMAN: Node warns (DEP0190) when you pass an `args` array AND
+// shell:true to spawn() — with a shell, args get concatenated into
+// one string rather than passed safely separated, so an unescaped
+// arg could break out into shell syntax. We build every argument
+// ourselves (ports, hosts, flags) so real-world risk here is low,
+// but we still quote defensively and pass ONE command string instead
+// of a separate args array, which silences the warning and is the
+// actually-correct way to use shell:true.
+function quoteArg(arg) {
+  const str = String(arg);
+  // Bare word made only of safe characters — no quoting needed.
+  if (/^[A-Za-z0-9_\-./:@=]+$/.test(str)) return str;
+
+  if (process.platform === 'win32') {
+    // CAVEMAN: cmd.exe quoting. Wrap in double quotes, escape
+    // any literal double quotes inside.
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+
+  // POSIX shells: single-quote, escaping any embedded single quotes.
+  return `'${str.replace(/'/g, `'\\''`)}'`;
+}
+
+function buildCommandString(command, args) {
+  return [command, ...args].map(quoteArg).join(' ');
+}
+
+/**
+ * Spawns the appropriate dev process for a framework project.
+ * Returns { child, stop } — stop() gracefully shuts the child down.
+ * For "html" projects, use startStaticServer instead (see cli.js).
+ */
+function spawnDevServer(project, port, host) {
+  const adapter = ADAPTERS[project.adapter] || ADAPTERS.generic;
+  const { command, args, env } = adapter.buildCommand({ project, port, host });
+  const commandString = buildCommandString(command, args);
+
+  let child;
+  try {
+    child = spawn(commandString, {
+      cwd: project.dir,
+      env,
+      // CAVEMAN: shell:true keeps this working cross-platform for
+      // npm/npx-style commands without hardcoding path resolution.
+      // Passing one pre-built, pre-quoted string (instead of a
+      // separate args array) is what avoids Node's DEP0190 warning.
+      shell: true,
+      stdio: 'inherit',
+    });
+  } catch (err) {
+    throw new ServerStartError(err.message);
+  }
+
+  function stop() {
+    if (!child || child.killed) return;
+    // CAVEMAN: Ctrl+C on Windows behaves differently than POSIX
+    // signals. A plain kill() sends SIGTERM-equivalent everywhere,
+    // which is good enough here since we spawned this process
+    // ourselves — we are not touching anyone else's process.
+    if (process.platform === 'win32') {
+      child.kill();
+    } else {
+      child.kill('SIGINT');
+    }
+  }
+
+  return { child, stop };
+}
+
+module.exports = {
+  spawnDevServer,
+  startStaticServer,
+  waitUntilListening,
+  defaultPortFor,
+  buildCommandString,
+};