@happier-dev/stack 0.1.0-preview.5.1

package/scripts/utils/net/ports.mjs

@@ -0,0 +1,110 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import net from 'node:net';
+import { runCaptureIfCommandExists } from '../proc/commands.mjs';
+
+export async function listListenPids(port) {
+  if (!Number.isFinite(port) || port <= 0) return [];
+  if (process.platform === 'win32') return [];
+
+  let raw = '';
+  try {
+    // `lsof` exits non-zero if no matches; normalize to empty output.
+    raw = await runCaptureIfCommandExists('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
+    if (!raw && process.platform === 'darwin') {
+      // Some non-interactive shells (launchd/GUI apps) have a PATH that omits /usr/sbin,
+      // which makes `command -v lsof` fail even though lsof exists. Fall back to absolute paths.
+      raw =
+        (await runCaptureIfCommandExists('/usr/sbin/lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'])) ||
+        (await runCaptureIfCommandExists('/usr/bin/lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'])) ||
+        '';
+    }
+  } catch {
+    raw = '';
+  }
+
+  return Array.from(
+    new Set(
+      raw
+        .split(/\s+/g)
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => Number(s))
+        .filter((n) => Number.isInteger(n) && n > 1)
+    )
+  );
+}
+
+/**
+ * Best-effort: kill any processes LISTENing on a TCP port.
+ * Used to avoid EADDRINUSE when a previous run left a server behind.
+ */
+export async function killPortListeners(port, { label = 'port' } = {}) {
+  if (!Number.isFinite(port) || port <= 0) {
+    return [];
+  }
+  if (process.platform === 'win32') {
+    return [];
+  }
+
+  const pids = await listListenPids(port);
+
+  if (!pids.length) {
+    return [];
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`[local] ${label}: freeing tcp:${port} (killing pids: ${pids.join(', ')})`);
+
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch {
+      // ignore
+    }
+  }
+
+  await delay(500);
+
+  for (const pid of pids) {
+    try {
+      process.kill(pid, 0);
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // not running / no permission
+    }
+  }
+
+  return pids;
+}
+
+export async function isTcpPortFree(port, { host = '127.0.0.1' } = {}) {
+  if (!Number.isFinite(port) || port <= 0) return false;
+
+  // Prefer lsof-based detection to catch IPv6 listeners (e.g. TCP *:8081 (LISTEN))
+  // which can make a "bind 127.0.0.1" probe incorrectly report "free" on macOS.
+  const pids = await listListenPids(port);
+  if (pids.length) return false;
+
+  // Fallback: attempt to bind.
+  return await new Promise((resolvePromise) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', () => resolvePromise(false));
+    srv.listen({ port, host }, () => {
+      srv.close(() => resolvePromise(true));
+    });
+  });
+}
+
+export async function pickNextFreeTcpPort(startPort, { reservedPorts = new Set(), host = '127.0.0.1', tries = 200 } = {}) {
+  let port = startPort;
+  for (let i = 0; i < tries; i++) {
+    // eslint-disable-next-line no-await-in-loop
+    if (!reservedPorts.has(port) && (await isTcpPortFree(port, { host }))) {
+      return port;
+    }
+    port += 1;
+  }
+  throw new Error(`[local] unable to find a free TCP port starting at ${startPort}`);
+}
+

package/scripts/utils/net/tcp_forward.mjs

@@ -0,0 +1,162 @@
+/**
+ * Lightweight TCP port forwarder using Node.js built-in `net` module.
+ *
+ * Used to expose Expo dev server (which binds to LAN IP) on the Tailscale interface,
+ * enabling remote device access over Tailscale without modifying Expo's binding behavior.
+ *
+ * Can be run standalone:
+ *   node tcp_forward.mjs --listen-host=100.x.y.z --listen-port=8081 --target-host=192.168.1.50 --target-port=8081
+ *
+ * Or imported and spawned as a managed child process.
+ */
+
+import net from 'node:net';
+
+/**
+ * Create a TCP forwarding server.
+ *
+ * @param {Object} options
+ * @param {string} options.listenHost - Host/IP to listen on (e.g., Tailscale IP)
+ * @param {number} options.listenPort - Port to listen on
+ * @param {string} options.targetHost - Host/IP to forward to (e.g., LAN IP or 127.0.0.1)
+ * @param {number} options.targetPort - Port to forward to
+ * @param {string} [options.label] - Label for logging (default: 'tcp-forward')
+ * @returns {net.Server}
+ */
+export function createTcpForwarder({ listenHost, listenPort, targetHost, targetPort, label = 'tcp-forward' }) {
+  const server = net.createServer((clientSocket) => {
+    const targetSocket = net.createConnection({ host: targetHost, port: targetPort }, () => {
+      // Connection established, pipe data both ways
+      clientSocket.pipe(targetSocket);
+      targetSocket.pipe(clientSocket);
+    });
+
+    // Handle errors on both sockets
+    clientSocket.on('error', (err) => {
+      if (err.code !== 'ECONNRESET') {
+        process.stderr.write(`[${label}] client error: ${err.message}\n`);
+      }
+      targetSocket.destroy();
+    });
+
+    targetSocket.on('error', (err) => {
+      if (err.code !== 'ECONNRESET' && err.code !== 'ECONNREFUSED') {
+        process.stderr.write(`[${label}] target error: ${err.message}\n`);
+      }
+      clientSocket.destroy();
+    });
+
+    // Clean up on close
+    clientSocket.on('close', () => targetSocket.destroy());
+    targetSocket.on('close', () => clientSocket.destroy());
+  });
+
+  server.on('error', (err) => {
+    process.stderr.write(`[${label}] server error: ${err.message}\n`);
+  });
+
+  return server;
+}
+
+/**
+ * Start a TCP forwarder and return a promise that resolves when listening.
+ *
+ * @param {Object} options - Same as createTcpForwarder
+ * @returns {Promise<{ server: net.Server, address: string, port: number }>}
+ */
+export async function startTcpForwarder(options) {
+  const { listenHost, listenPort, label = 'tcp-forward' } = options;
+  const server = createTcpForwarder(options);
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(listenPort, listenHost, () => {
+      server.removeListener('error', reject);
+      const addr = server.address();
+      const address = typeof addr === 'object' ? addr.address : listenHost;
+      const port = typeof addr === 'object' ? addr.port : listenPort;
+      process.stdout.write(`[${label}] forwarding ${address}:${port} -> ${options.targetHost}:${options.targetPort}\n`);
+      resolve({ server, address, port });
+    });
+  });
+}
+
+function trySendIpc(msg) {
+  try {
+    if (typeof process.send === 'function') {
+      process.send(msg);
+    }
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Gracefully stop a TCP forwarder server.
+ *
+ * @param {net.Server} server
+ * @param {string} [label]
+ * @returns {Promise<void>}
+ */
+export async function stopTcpForwarder(server, label = 'tcp-forward') {
+  if (!server) return;
+  return new Promise((resolve) => {
+    server.close(() => {
+      process.stdout.write(`[${label}] stopped\n`);
+      resolve();
+    });
+    // Force-close after timeout
+    setTimeout(() => {
+      resolve();
+    }, 2000);
+  });
+}
+
+// Standalone CLI mode
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const kv = new Map();
+  for (const arg of args) {
+    const m = arg.match(/^--([^=]+)=(.*)$/);
+    if (m) kv.set(m[1], m[2]);
+  }
+
+  const listenHost = kv.get('listen-host') || kv.get('listenHost');
+  const listenPort = Number(kv.get('listen-port') || kv.get('listenPort'));
+  const targetHost = kv.get('target-host') || kv.get('targetHost') || '127.0.0.1';
+  const targetPort = Number(kv.get('target-port') || kv.get('targetPort'));
+  const label = kv.get('label') || 'tcp-forward';
+
+  if (!listenHost || !listenPort || !targetPort) {
+    console.error('Usage: node tcp_forward.mjs --listen-host=<ip> --listen-port=<port> --target-host=<ip> --target-port=<port> [--label=<label>]');
+    process.exit(1);
+  }
+
+  const shutdown = () => {
+    process.stdout.write(`\n[${label}] shutting down...\n`);
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  startTcpForwarder({ listenHost, listenPort, targetHost, targetPort, label })
+    .then(() => {
+      trySendIpc({ type: 'ready', listenHost, listenPort, targetHost, targetPort, label });
+      // Keep running until signal
+    })
+    .catch((err) => {
+      trySendIpc({
+        type: 'error',
+        code: err && typeof err === 'object' ? err.code : null,
+        message: err instanceof Error ? err.message : String(err ?? 'unknown error'),
+        listenHost,
+        listenPort,
+        targetHost,
+        targetPort,
+        label,
+      });
+      console.error(`[${label}] failed to start: ${err.message}`);
+      process.exit(1);
+    });
+}

package/scripts/utils/net/url.mjs

@@ -0,0 +1,30 @@
+export function normalizeUrlNoTrailingSlash(raw) {
+  const s = String(raw ?? '').trim();
+  if (!s) return '';
+
+  let u;
+  try {
+    u = new URL(s);
+  } catch {
+    // Best-effort: if it's a plain string with trailing slash, trim it.
+    return s.endsWith('/') ? s.replace(/\/+$/, '') : s;
+  }
+
+  // Only normalize "base" URLs without search/hash.
+  // If search/hash is present, removing slashes can change semantics.
+  if (u.search || u.hash) {
+    return u.toString();
+  }
+
+  // Normalize multiple trailing slashes down to none (root) or one-less (non-root).
+  const path = u.pathname || '/';
+  if (path === '/' || path === '') {
+    return u.origin;
+  }
+  if (path.endsWith('/')) {
+    const nextPath = path.replace(/\/+$/, '');
+    return `${u.origin}${nextPath}`;
+  }
+  return u.toString();
+}
+

package/scripts/utils/net/url.test.mjs

@@ -0,0 +1,29 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { normalizeUrlNoTrailingSlash } from './url.mjs';
+
+test('normalizeUrlNoTrailingSlash removes trailing slash from origins', () => {
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/'), 'https://example.com');
+  assert.equal(normalizeUrlNoTrailingSlash('http://localhost:3005/'), 'http://localhost:3005');
+});
+
+test('normalizeUrlNoTrailingSlash removes trailing slash from path-only base URLs', () => {
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/api/'), 'https://example.com/api');
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/api///'), 'https://example.com/api');
+});
+
+test('normalizeUrlNoTrailingSlash preserves query/hash URLs', () => {
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/?q=1'), 'https://example.com/?q=1');
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/api/?q=1'), 'https://example.com/api/?q=1');
+});
+
+test('normalizeUrlNoTrailingSlash handles invalid/blank values defensively', () => {
+  assert.equal(normalizeUrlNoTrailingSlash(''), '');
+  assert.equal(normalizeUrlNoTrailingSlash('   '), '');
+  assert.equal(normalizeUrlNoTrailingSlash('not-a-url///'), 'not-a-url');
+});
+
+test('normalizeUrlNoTrailingSlash preserves hash-only URL semantics', () => {
+  assert.equal(normalizeUrlNoTrailingSlash('https://example.com/path/#hash'), 'https://example.com/path/#hash');
+});

package/scripts/utils/paths/canonical_home.mjs

@@ -0,0 +1,15 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function expandHome(p) {
+  return String(p ?? '').replace(/^~(?=[/\\])/, homedir());
+}
+
+export function getCanonicalHomeDirFromEnv(env = process.env) {
+  const fromEnv = (env.HAPPIER_STACK_CANONICAL_HOME_DIR ?? '').trim();
+  return fromEnv ? expandHome(fromEnv) : join(homedir(), '.happier-stack');
+}
+
+export function getCanonicalHomeEnvPathFromEnv(env = process.env) {
+  return join(getCanonicalHomeDirFromEnv(env), '.env');
+}

package/scripts/utils/paths/canonical_home.test.mjs

@@ -0,0 +1,28 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { homedir } from 'node:os';
+
+import { expandHome, getCanonicalHomeDirFromEnv, getCanonicalHomeEnvPathFromEnv } from './canonical_home.mjs';
+
+test('expandHome expands ~/ paths', () => {
+  assert.equal(expandHome('~/x'), `${homedir()}/x`);
+});
+
+test('expandHome expands ~\\ paths (Windows)', () => {
+  assert.equal(expandHome('~\\x'), `${homedir()}\\x`);
+});
+
+test('expandHome leaves non-home-prefixed paths unchanged', () => {
+  assert.equal(expandHome('~user/x'), '~user/x');
+  assert.equal(expandHome('/tmp/x'), '/tmp/x');
+});
+
+test('getCanonicalHomeDirFromEnv expands override and defaults to ~/.happier-stack', () => {
+  assert.equal(getCanonicalHomeDirFromEnv({ HAPPIER_STACK_CANONICAL_HOME_DIR: '~/custom-home' }), `${homedir()}/custom-home`);
+  assert.equal(getCanonicalHomeDirFromEnv({}), `${homedir()}/.happier-stack`);
+});
+
+test('getCanonicalHomeEnvPathFromEnv resolves .env under canonical home', () => {
+  const envPath = getCanonicalHomeEnvPathFromEnv({ HAPPIER_STACK_CANONICAL_HOME_DIR: '~/custom-home' });
+  assert.equal(envPath, `${homedir()}/custom-home/.env`);
+});

package/scripts/utils/paths/localhost_host.mjs

@@ -0,0 +1,112 @@
+import { getStackName } from './paths.mjs';
+import { networkInterfaces } from 'node:os';
+import { sanitizeDnsLabel } from '../net/dns.mjs';
+
+function resolveBindMode(env) {
+  const raw = (env.HAPPIER_STACK_BIND_MODE ?? '').toString().trim().toLowerCase();
+  return raw === 'lan' ? 'lan' : raw === 'loopback' ? 'loopback' : '';
+}
+
+function resolveLocalhostSubdomainPrefix(env) {
+  const raw = (env.HAPPIER_STACK_LOCALHOST_SUBDOMAIN_PREFIX ?? '').toString().trim().toLowerCase();
+  if (!raw) return 'happier';
+  // Keep legacy compatibility (older installs used happy-<stack>.localhost).
+  if (raw === 'happy') return 'happy';
+  if (raw === 'happier') return 'happier';
+  return 'happier';
+}
+
+function detectLanHost({ env = process.env } = {}) {
+  const override = (env.HAPPIER_STACK_LAN_HOST ?? '').toString().trim();
+  if (override) return override;
+
+  const nets = networkInterfaces();
+  const candidates = [];
+  for (const [ifName, addrs] of Object.entries(nets)) {
+    for (const a of addrs ?? []) {
+      if (!a || a.family !== 'IPv4' || a.internal) continue;
+      const ip = String(a.address ?? '').trim();
+      if (!ip) continue;
+      if (ip.startsWith('127.')) continue;
+      // Drop link-local IPv4 (usually not host-reachable).
+      if (ip.startsWith('169.254.')) continue;
+      let score = 0;
+      if (ifName === 'lima0' || ifName.startsWith('lima')) score += 50;
+      if (ifName.startsWith('en') || ifName.startsWith('eth')) score += 10;
+      candidates.push({ ip, ifName, score });
+    }
+  }
+
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates[0]?.ip ?? '';
+}
+
+export function resolveLocalhostHost({ stackMode, stackName = null, env = process.env } = {}) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  if (!stackMode) return 'localhost';
+  const bindMode = resolveBindMode(env);
+  if (bindMode === 'lan') {
+    const lanHost = detectLanHost({ env });
+    if (lanHost) return lanHost;
+  }
+  if (!name || name === 'main') return 'localhost';
+  const prefix = resolveLocalhostSubdomainPrefix(env);
+  return `${prefix}-${sanitizeDnsLabel(name)}.localhost`;
+}
+
+export async function preferStackLocalhostHost({ stackName = null, env = process.env } = {}) {
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  if (!name || name === 'main') return 'localhost';
+  // IMPORTANT:
+  // We intentionally do NOT gate on `dns.lookup()` here.
+  //
+  // On some systems (notably macOS), Node's DNS resolver may return ENOTFOUND for `*.localhost`
+  // even though browsers treat `*.localhost` as loopback and will load it fine.
+  //
+  // Since this hostname is primarily used for browser-facing URLs and origin isolation, we
+  // prefer a stable `<prefix>-<stack>.localhost` form by default and allow opting out via env.
+  const modeRaw = (env.HAPPIER_STACK_LOCALHOST_SUBDOMAINS ?? '')
+    .toString()
+    .trim()
+    .toLowerCase();
+  const disabled = modeRaw === '0' || modeRaw === 'false' || modeRaw === 'no' || modeRaw === 'off';
+  if (disabled) return 'localhost';
+
+  const preferredHost = resolveLocalhostHost({ stackMode: true, stackName: name, env });
+  return preferredHost || 'localhost';
+}
+
+// Best-effort: for stacks, prefer `<prefix>-<stack>.localhost` over `localhost` when it's reachable.
+// This keeps URLs stable and stack-scoped while still failing closed to plain localhost.
+export async function preferStackLocalhostUrl(url, { stackName = null, env = process.env } = {}) {
+  const raw = String(url ?? '').trim();
+  if (!raw) return '';
+  const name = (stackName ?? '').toString().trim() || getStackName(env);
+  if (!name || name === 'main') return raw;
+
+  let u = null;
+  try {
+    u = new URL(raw);
+  } catch {
+    return raw;
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return raw;
+
+  const bindMode = resolveBindMode(env);
+  const isLoopbackHost =
+    u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname.toLowerCase().endsWith('.localhost');
+  if (!isLoopbackHost) return raw;
+
+  // In LAN bind mode, prefer an IP address that is reachable from other devices/hosts.
+  // This is especially useful inside VMs (e.g. Lima vzNAT) where host-local `*.localhost`
+  // URLs are not reachable without explicit port forwarding.
+  if (bindMode === 'lan') {
+    const lanHost = detectLanHost({ env });
+    if (lanHost) return raw.replace(`://${u.hostname}`, `://${lanHost}`);
+    return raw;
+  }
+
+  const preferredHost = await preferStackLocalhostHost({ stackName: name, env });
+  if (!preferredHost || preferredHost === 'localhost') return raw;
+  return raw.replace(`://${u.hostname}`, `://${preferredHost}`);
+}

package/scripts/utils/paths/localhost_host.test.mjs

@@ -0,0 +1,58 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { preferStackLocalhostUrl, resolveLocalhostHost } from './localhost_host.mjs';
+
+test('preferStackLocalhostUrl rewrites *.localhost to LAN IP when bind mode is lan', async () => {
+  const env = {
+    HAPPIER_STACK_STACK: 'dev-auth',
+    HAPPIER_STACK_BIND_MODE: 'lan',
+    // Override LAN host so test is deterministic.
+    HAPPIER_STACK_LAN_HOST: '192.168.5.15',
+  };
+  const url = await preferStackLocalhostUrl('http://happy-dev-auth.localhost:18137', { stackName: 'dev-auth', env });
+  assert.equal(url, 'http://192.168.5.15:18137');
+});
+
+test('resolveLocalhostHost returns LAN IP when bind mode is lan', () => {
+  const env = { HAPPIER_STACK_BIND_MODE: 'lan', HAPPIER_STACK_LAN_HOST: '192.168.5.15' };
+  assert.equal(resolveLocalhostHost({ stackMode: true, stackName: 'dev-auth', env }), '192.168.5.15');
+});
+
+test('resolveLocalhostHost uses happier-<stack>.localhost by default', () => {
+  const env = {};
+  assert.equal(resolveLocalhostHost({ stackMode: true, stackName: 'dev-auth', env }), 'happier-dev-auth.localhost');
+});
+
+test('resolveLocalhostHost supports legacy prefix via HAPPIER_STACK_LOCALHOST_SUBDOMAIN_PREFIX=happy', () => {
+  const env = { HAPPIER_STACK_LOCALHOST_SUBDOMAIN_PREFIX: 'happy' };
+  assert.equal(resolveLocalhostHost({ stackMode: true, stackName: 'dev-auth', env }), 'happy-dev-auth.localhost');
+});
+
+test('resolveLocalhostHost falls back to happier prefix for invalid override values', () => {
+  const env = { HAPPIER_STACK_LOCALHOST_SUBDOMAIN_PREFIX: 'invalid-prefix' };
+  assert.equal(resolveLocalhostHost({ stackMode: true, stackName: 'dev-auth', env }), 'happier-dev-auth.localhost');
+});
+
+test('resolveLocalhostHost returns localhost for non-stack and main stack contexts', () => {
+  assert.equal(resolveLocalhostHost({ stackMode: false, stackName: 'dev-auth', env: {} }), 'localhost');
+  assert.equal(resolveLocalhostHost({ stackMode: true, stackName: 'main', env: {} }), 'localhost');
+});
+
+test('preferStackLocalhostUrl respects localhost subdomain disable policy', async () => {
+  const env = { HAPPIER_STACK_LOCALHOST_SUBDOMAINS: 'false' };
+  const raw = 'http://localhost:18137';
+  const url = await preferStackLocalhostUrl(raw, { stackName: 'dev-auth', env });
+  assert.equal(url, raw);
+});
+
+test('preferStackLocalhostUrl preserves non-http schemes and non-loopback hosts', async () => {
+  const env = { HAPPIER_STACK_BIND_MODE: 'lan', HAPPIER_STACK_LAN_HOST: '192.168.5.15' };
+  assert.equal(
+    await preferStackLocalhostUrl('ws://localhost:18137', { stackName: 'dev-auth', env }),
+    'ws://localhost:18137'
+  );
+  assert.equal(
+    await preferStackLocalhostUrl('https://example.com:18137', { stackName: 'dev-auth', env }),
+    'https://example.com:18137'
+  );
+});