Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

5.4 KB
Raw Blame
import { exec, execSync } from './childProcess.js';
import { promisify } from 'util';
import { isBrowserUnsafePort } from './browserUnsafePorts.js';

// Keep promisification lazy so pure platform consumers can be imported from
// tests that intentionally mock only the child-process methods they exercise.
// The call path still uses the same shared `exec` wrapper when a port probe runs.
const execAsync = (...args) => promisify(exec)(...args);

const platform = process.platform;

// Probe the real CPU for arm64, cached. Needed because a Node launched under
// Rosetta on an M-series Mac reports `process.arch === 'x64'` even though the
// hardware (and a native LM Studio) is Apple Silicon — `hw.optional.arm64` is the
// hardware truth regardless of the process's translation. try/catch is the
// sanctioned child-process boundary (the sysctl key is absent on Intel → throws).
let arm64HardwareCache;
function probeArm64Hardware() {
  if (arm64HardwareCache === undefined) {
    try {
      arm64HardwareCache = execSync('sysctl -n hw.optional.arm64', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() === '1';
    } catch {
      arm64HardwareCache = false;
    }
  }
  return arm64HardwareCache;
}

/**
 * Is this an Apple-Silicon Mac? Gates MLX model features (MLX is Apple's native
 * framework, so MLX formats only run on Apple Silicon). Detect at the route
 * boundary and pass into pure services, like `os.totalmem()`.
 *
 * `process.arch === 'arm64'` is the fast native answer; an x64 darwin process may
 * still be arm64 hardware under Rosetta, so that case probes `hw.optional.arm64`.
 * The `platform`/`arch`/`probe` overrides exist for deterministic tests.
 * @returns {boolean}
 */
export function isAppleSilicon({ platform: plat = process.platform, arch = process.arch, probe = probeArm64Hardware } = {}) {
  if (plat !== 'darwin') return false;
  if (arch === 'arm64') return true;
  return probe();
}

/**
 * Parse a platform port-discovery command into a sorted unique list. Kept pure
 * so command formats are covered deterministically instead of depending on the
 * test host's current listeners or installed utilities.
 * @param {string} stdout
 * @param {string} targetPlatform
 * @returns {number[]} Array of port numbers
 */
export function parseListeningPorts(stdout, targetPlatform = platform) {
  const ports = new Set();
  const addPort = (value) => {
    const port = Number(value);
    if (Number.isInteger(port) && port >= 1 && port <= 65535) ports.add(port);
  };

  if (targetPlatform === 'darwin') {
    for (const line of String(stdout || '').split('\n')) {
      const match = line.match(/:(\d+)\s+\(LISTEN\)/);
      if (match) addPort(match[1]);
    }
  } else if (targetPlatform === 'linux') {
    for (const line of String(stdout || '').split('\n')) {
      if (!/^\s*LISTEN\b/.test(line)) continue;
      const match = line.match(/:(\d+)\s/);
      if (match) addPort(match[1]);
    }
  } else {
    for (const line of String(stdout || '').split('\n')) {
      if (!/\bLISTENING\b/i.test(line)) continue;
      const match = line.match(/^\s*TCP\s+\S+:(\d+)\s+/i);
      if (match) addPort(match[1]);
    }
  }

  return Array.from(ports).sort((a, b) => a - b);
}

function portProbeFor(targetPlatform) {
  if (targetPlatform === 'darwin') return 'lsof -iTCP -sTCP:LISTEN -n -P';
  if (targetPlatform === 'linux') return 'ss -lntp';
  return 'netstat -an';
}

/**
 * Get list of listening TCP ports. Discovery failure is explicit: returning an
 * empty array would be indistinguishable from a host with no listeners and let
 * callers advertise occupied ports as free.
 * @param {{platform?: string, exec?: Function}} options deterministic overrides
 * @returns {Promise<number[]>} Array of port numbers
 */
export async function getListeningPorts({ platform: targetPlatform = platform, exec: run = execAsync } = {}) {
  const command = portProbeFor(targetPlatform);
  try {
    const { stdout } = await run(command);
    return parseListeningPorts(stdout, targetPlatform);
  } catch (cause) {
    const error = new Error(`Unable to discover listening ports with ${command}: ${cause.message}`);
    error.code = 'PORT_DISCOVERY_FAILED';
    error.command = command;
    error.platform = targetPlatform;
    error.cause = cause;
    throw error;
  }
}

/**
 * Check if a specific port is in use
 * @param {number} port Port to check
 * @returns {Promise<boolean>} True if port is in use
 */
export async function isPortInUse(port, probeOptions) {
  const ports = await getListeningPorts(probeOptions);
  return ports.includes(port);
}

/**
 * Find available ports in a range. Never returns a browser-blocked port
 * (`isBrowserUnsafePort`), since an app on one cannot be opened from the UI.
 * @param {number} start Start of range
 * @param {number} end End of range
 * @param {number} count Number of ports to find
 * @param {object} [probeOptions] Listener-discovery overrides
 * @param {number[]} [reservedPorts] Ports held by registered apps that are not listening right now
 * @returns {Promise<number[]>} Available ports
 */
export async function findAvailablePorts(start, end, count = 1, probeOptions, reservedPorts = []) {
  if (start > end || count <= 0) return [];
  const usedPorts = new Set([...await getListeningPorts(probeOptions), ...reservedPorts]);
  const available = [];

  for (let port = start; port <= end && available.length < count; port++) {
    if (!usedPorts.has(port) && !isBrowserUnsafePort(port)) {
      available.push(port);
    }
  }

  return available;
}

export { platform };