@mh-gg/cli 0.1.1-alpha.20260613T085325975Z

package/runtime/host/hostSession.cjs

@@ -0,0 +1,160 @@
+const WebSocket = require("ws");
+const { announceHost } = require("./hostAnnouncement.cjs");
+const { createHostClients } = require("./hostClients/index.cjs");
+const { relayIpcUrl } = require("./localRelayClient.cjs");
+const { createRelayMessageReceiver, parseRelayMessage, sendToRelay } = require("@mh-gg/host-ipc");
+
+function createHostSession(options) {
+  const {
+    store,
+    args,
+    logger = console
+  } = options;
+  const ipcSecret = options.localRelay?.config?.ipcSecret;
+  const reconnectRelay = options.reconnectRelay === true;
+  const relayReconnectMs = Number.isFinite(options.relayReconnectMs) ? Math.max(100, options.relayReconnectMs) : 1000;
+  let activeRelaySocket;
+  let reconnectTimer;
+  const clients = createHostClients({
+    store,
+    logger,
+    frontendBundle: options.frontendBundle,
+    frontendProgress: options.frontendProgress,
+    onStoreChange: syncStoreToRelay
+  });
+  let announced = false;
+
+  function debugHost(message, ...args) {
+    if (process.env.MATTERHORN_DEBUG === "1") logger.log(message, ...args);
+  }
+
+  function announceRegisteredRelay() {
+    if (announced) return;
+    announced = true;
+    announceHost(options);
+  }
+
+  function roomStoreSnapshot() {
+    return JSON.parse(JSON.stringify(store));
+  }
+
+  function relayAuth() {
+    if (!ipcSecret) return undefined;
+    return {
+      type: "relay-ipc",
+      secret: ipcSecret
+    };
+  }
+
+  function hostIpcMessage(message) {
+    const auth = relayAuth();
+    return auth ? { ...message, auth } : message;
+  }
+
+  function syncStoreToRelay() {
+    if (!activeRelaySocket) return;
+    sendToRelay(activeRelaySocket, hostIpcMessage({
+      type: "host.snapshot",
+      roomName: store.roomName,
+      store: roomStoreSnapshot(),
+      appRef: options.appRef,
+      appCwd: options.appCwd
+    }));
+  }
+
+  function createReconnectSocket() {
+    if (typeof options.createRelaySocket === "function") return options.createRelaySocket();
+    if (!options.localRelay?.config) return undefined;
+    return new WebSocket(relayIpcUrl(options.localRelay.config));
+  }
+
+  function scheduleRelayReconnect() {
+    if (!reconnectRelay || reconnectTimer || activeRelaySocket) return;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = undefined;
+      let relaySocket;
+      try {
+        relaySocket = createReconnectSocket();
+      } catch (error) {
+        logger.error("Local relay IPC reconnect failed:", error);
+        scheduleRelayReconnect();
+        return;
+      }
+      if (relaySocket) attachRelaySocket(relaySocket);
+      else scheduleRelayReconnect();
+    }, relayReconnectMs);
+    reconnectTimer.unref?.();
+  }
+
+  function handleRelayMessage(socket, data) {
+    const message = typeof data === "object" && !Buffer.isBuffer(data) ? data : parseRelayMessage(data);
+    if (!message) return;
+
+    if (message.type === "host.register.ok") {
+      announceRegisteredRelay();
+      return;
+    }
+
+    if (message.type === "host.register.error") {
+      logger.error(message.message || "Relay rejected host registration.");
+      return;
+    }
+
+    if (message.type === "relay/client-message") {
+      clients.handleClientMessage(socket, message.peerId, message.message);
+      return;
+    }
+
+    if (message.type === "relay/client-close") {
+      debugHost("Relay client connection closed", message.peerId);
+      clients.removeConnection(message.peerId);
+    }
+  }
+
+  function attachRelaySocket(relaySocket) {
+    const receiveRelayMessage = createRelayMessageReceiver();
+    relaySocket.on("open", () => {
+      if (reconnectTimer) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = undefined;
+      }
+      activeRelaySocket = relaySocket;
+      sendToRelay(relaySocket, hostIpcMessage({
+        type: "host.register",
+        roomName: store.roomName,
+        store: roomStoreSnapshot(),
+        appRef: options.appRef,
+        appCwd: options.appCwd,
+        relayHints: [store.relayAddress, ...args.relayPeers].filter(Boolean)
+      }));
+    });
+    relaySocket.on("message", (data) => {
+      const message = receiveRelayMessage(data);
+      if (message) handleRelayMessage(relaySocket, message);
+    });
+    relaySocket.on("close", () => {
+      if (activeRelaySocket === relaySocket) activeRelaySocket = undefined;
+      if (reconnectRelay) {
+        logger.error("Local relay IPC closed. Reconnecting when the relay is available.");
+        scheduleRelayReconnect();
+      } else {
+        logger.error("Local relay IPC closed. Stop this host or restart it after the relay is available.");
+      }
+    });
+    relaySocket.on("error", (error) => {
+      logger.error("Local relay IPC error:", error);
+    });
+  }
+
+  return {
+    attachRelaySocket,
+    connectionRoles: clients.connectionRoles,
+    handleClientMessage: clients.handleClientMessage,
+    handleRelayMessage,
+    pendingJoinConnections: clients.pendingJoinConnections
+  };
+}
+
+module.exports = {
+  createHostSession
+};

package/runtime/host/inlineProgressBar.cjs

@@ -0,0 +1,128 @@
+"use strict";
+
+function sanitizeProgressText(value) {
+  return String(value || "").replace(/[\r\n\t]+/g, " ").slice(0, 80);
+}
+
+function normalizeCount(value, fallback = 0) {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function normalizeProgressState(update = {}, previous = {}) {
+  const total = normalizeCount(update.total, normalizeCount(previous.total, 0));
+  const rawCompleted = Object.prototype.hasOwnProperty.call(update, "completed")
+    ? update.completed
+    : update.progress;
+  const completed = normalizeCount(rawCompleted, normalizeCount(previous.completed, 0));
+  const currentItem = typeof update.currentItem === "string"
+    ? sanitizeProgressText(update.currentItem)
+    : (previous.currentItem || "");
+
+  return {
+    completed: Math.max(0, total > 0 ? Math.min(completed, total) : completed),
+    total: Math.max(0, total),
+    currentItem
+  };
+}
+
+function progressRatio(done, total) {
+  if (!Number.isFinite(total) || total <= 0) return 0;
+  const safeDone = Math.max(0, Math.min(done, total));
+  return safeDone / total;
+}
+
+function formatProgressPercent(done, total) {
+  if (!Number.isFinite(total) || total <= 0) return "";
+  const percent = progressRatio(done, total) * 100;
+  return Number.isInteger(percent) ? `${percent}%` : `${percent.toFixed(1)}%`;
+}
+
+function renderProgressBar(done, total, width = 24) {
+  if (!Number.isFinite(total) || total <= 0) return "";
+  const safeWidth = Math.max(0, Math.floor(Number.isFinite(width) ? width : 24));
+  if (safeWidth <= 0) return "[]";
+
+  const filled = Math.max(0, Math.min(safeWidth, Math.floor(progressRatio(done, total) * safeWidth)));
+  const percentText = formatProgressPercent(done, total);
+  const label = percentText.length > safeWidth ? percentText.slice(0, safeWidth) : percentText;
+  const labelStart = Math.max(0, Math.floor((safeWidth - label.length) / 2));
+  let content = "";
+
+  for (let index = 0; index < safeWidth; index += 1) {
+    const labelIndex = index - labelStart;
+    if (labelIndex >= 0 && labelIndex < label.length) {
+      content += label[labelIndex];
+    } else {
+      content += index < filled ? "=" : " ";
+    }
+  }
+
+  return `[${content}]`;
+}
+
+function renderProgressLine(message, state, options = {}) {
+  const progress = normalizeProgressState(state);
+  const width = Number.isFinite(options.width) ? options.width : 24;
+  const bar = renderProgressBar(progress.completed, progress.total, width);
+  const count = progress.total > 0
+    ? `${Math.min(progress.completed, progress.total)}/${progress.total}`
+    : String(progress.completed);
+  const item = progress.currentItem ? ` ${progress.currentItem}` : "";
+  return `${message} ${bar ? `${bar} ` : ""}${count}${item}`;
+}
+
+function createNoopProgressLoader() {
+  return {
+    start() {},
+    update() {},
+    stop() {}
+  };
+}
+
+function createInlineProgressLoader(message, options = {}) {
+  const stream = options.stream || process.stderr;
+  const enabled = options.enabled !== undefined
+    ? options.enabled
+    : Boolean(stream?.isTTY);
+
+  if (!enabled || !stream || typeof stream.write !== "function") {
+    return createNoopProgressLoader();
+  }
+
+  const width = Number.isFinite(options.width) ? options.width : 24;
+  let state = normalizeProgressState();
+  let lastLine = "";
+  const clearOnStop = options.clearOnStop !== false;
+  const newlineOnStop = options.newlineOnStop === true;
+
+  function draw() {
+    const line = renderProgressLine(message, state, { width });
+    const clearLength = Math.max(0, lastLine.length - line.length);
+    stream.write(`\r${line}${" ".repeat(clearLength)}`);
+    lastLine = line;
+  }
+
+  return {
+    start() {
+      draw();
+    },
+    update(update) {
+      state = normalizeProgressState(update, state);
+      draw();
+    },
+    stop() {
+      if (clearOnStop && lastLine) stream.write("\r\x1b[2K");
+      if (newlineOnStop) stream.write("\n");
+      lastLine = "";
+    }
+  };
+}
+
+module.exports = {
+  createInlineProgressLoader,
+  formatProgressPercent,
+  normalizeProgressState,
+  renderProgressBar,
+  renderProgressLine,
+  sanitizeProgressText
+};

package/runtime/host/localPeerServer.cjs

@@ -0,0 +1,114 @@
+const { setTimeout: delay } = require("node:timers/promises");
+
+const DEFAULT_LOCAL_PEERJS_HOST = "127.0.0.1";
+const DEFAULT_LOCAL_PEERJS_PORT = 9000;
+const DEFAULT_LOCAL_PEERJS_PATH = "/peerjs";
+
+function localPeerServerConfig(options = {}) {
+  return {
+    host: options.host || process.env.MATTERHORN_PEERJS_LOCAL_HOST || DEFAULT_LOCAL_PEERJS_HOST,
+    port: Number(options.port || process.env.MATTERHORN_PEERJS_LOCAL_PORT || DEFAULT_LOCAL_PEERJS_PORT),
+    path: options.path || process.env.MATTERHORN_PEERJS_LOCAL_PATH || DEFAULT_LOCAL_PEERJS_PATH,
+    secure: false
+  };
+}
+
+function applyPeerServerEnv(peerServer) {
+  process.env.MATTERHORN_PEERJS_HOST = peerServer.host;
+  process.env.MATTERHORN_PEERJS_PORT = String(peerServer.port);
+  process.env.MATTERHORN_PEERJS_PATH = peerServer.path;
+  process.env.MATTERHORN_PEERJS_SECURE = String(peerServer.secure);
+}
+
+function peerServerUrl(config) {
+  return `http://${config.host}:${config.port}${config.path}`;
+}
+
+function peerServerIdUrl(config) {
+  const base = peerServerUrl(config).replace(/\/$/, "");
+  return `${base}/peerjs/id`;
+}
+
+async function waitForPeerServer(config, options = {}) {
+  const timeoutMs = Number(options.timeoutMs || 5000);
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(peerServerIdUrl(config));
+      if (response.ok) return true;
+      lastError = new Error(`PeerJS health returned ${response.status}`);
+    } catch (error) {
+      lastError = error;
+    }
+    await delay(100);
+  }
+  throw lastError || new Error("Timed out waiting for local PeerJS server");
+}
+
+function closePeerServer(server) {
+  const target = server?.close ? server : server?._server;
+  if (!target?.close) return Promise.resolve();
+  return new Promise((resolve) => target.close(() => resolve()));
+}
+
+async function startLocalPeerServer(options = {}) {
+  const config = localPeerServerConfig(options);
+  if (options.reuseExisting !== false) {
+    try {
+      await waitForPeerServer(config, { timeoutMs: options.reuseTimeoutMs || 300 });
+      applyPeerServerEnv(config);
+      return {
+        ...config,
+        url: peerServerUrl(config),
+        reused: true,
+        server: undefined,
+        close: () => Promise.resolve()
+      };
+    } catch {}
+  }
+
+  let PeerServer;
+  try {
+    ({ PeerServer } = require("peer"));
+  } catch (error) {
+    throw new Error(`The local PeerJS server requires the peer package. Run pnpm install once at the Matterhorn workspace root. ${error.message}`);
+  }
+  if (typeof PeerServer !== "function") throw new Error("The peer package did not export PeerServer.");
+  const server = PeerServer({
+    host: config.host,
+    port: config.port,
+    path: config.path,
+    proxied: false
+  });
+  let startupError;
+  server?.once?.("error", (error) => {
+    startupError = error;
+  });
+  applyPeerServerEnv(config);
+  try {
+    await waitForPeerServer(config, options);
+  } catch (error) {
+    await closePeerServer(server).catch(() => undefined);
+    throw startupError || error;
+  }
+  return {
+    ...config,
+    url: peerServerUrl(config),
+    reused: false,
+    server,
+    close: () => closePeerServer(server)
+  };
+}
+
+module.exports = {
+  DEFAULT_LOCAL_PEERJS_HOST,
+  DEFAULT_LOCAL_PEERJS_PATH,
+  DEFAULT_LOCAL_PEERJS_PORT,
+  applyPeerServerEnv,
+  localPeerServerConfig,
+  peerServerIdUrl,
+  peerServerUrl,
+  startLocalPeerServer,
+  waitForPeerServer
+};

package/runtime/host/localRelayClient.cjs

@@ -0,0 +1,151 @@
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const { ensureRelayConfig } = require("./relayConfig.cjs");
+const { startLocalPeerServer } = require("./localPeerServer.cjs");
+
+const DEFAULT_RELAY_START_TIMEOUT_MS = 6000;
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function relayIpcUrl(config) {
+  return `ws://${config.ipcHost}:${config.ipcPort}/room`;
+}
+
+function relayHealthUrl(config) {
+  return `http://${config.ipcHost}:${config.ipcPort}/health`;
+}
+
+async function fetchRelayInfo(config, fetcher = fetch) {
+  const response = await fetcher(relayHealthUrl(config));
+  if (!response.ok) throw new Error(`Relay health returned ${response.status}`);
+  const info = await response.json();
+  if (info.protocol !== "matterhorn-peer-relay") throw new Error("Local process is not a matterhorn relay");
+  if (info.roomPeerOpen === false) throw new Error("Local relay room peer is not live");
+  return info;
+}
+
+async function waitForRelay(config, timeoutMs = DEFAULT_RELAY_START_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+
+  while (Date.now() < deadline) {
+    try {
+      return await fetchRelayInfo(config);
+    } catch (error) {
+      lastError = error;
+      await delay(250);
+    }
+  }
+
+  throw lastError || new Error("Timed out waiting for local relay");
+}
+
+function spawnRelayProcess(config, options = {}) {
+  const relayPath = path.join(__dirname, "relay.cjs");
+  const args = [
+    relayPath,
+    "--ipc-host",
+    config.ipcHost,
+    "--ipc-port",
+    String(config.ipcPort),
+    "--relay-peer-id",
+    config.relayPeerId
+  ];
+
+  for (const relayPeer of options.relayPeers || []) {
+    args.push("--relay-peer", relayPeer);
+  }
+  if (options.iceServers) {
+    args.push("--ice", options.iceServers);
+  }
+
+  const env = { ...process.env };
+  if (options.dataDir) env.MATTERHORN_HOME = options.dataDir;
+  if (options.localPeerjs) env.MATTERHORN_PEERJS_LOCAL = "1";
+
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env
+  });
+  child.unref();
+  return child;
+}
+
+function parseIceServers(value) {
+  if (Array.isArray(value)) return value.length > 0 ? value : undefined;
+  if (!value) return undefined;
+  return String(value || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((urls) => ({ urls }));
+}
+
+async function startEmbeddedRelay(config, options = {}) {
+  const { createMatterhornRelay } = require("./relay.cjs");
+  const relay = createMatterhornRelay({
+    dataDir: options.dataDir,
+    ipcHost: config.ipcHost,
+    ipcPort: config.ipcPort,
+    storagePath: options.storagePath,
+    relayPeerId: config.relayPeerId,
+    relayPeers: options.relayPeers || [],
+    iceServers: parseIceServers(options.iceServers),
+    startPeer: options.startPeer,
+    authenticateActor: options.authenticateActor,
+    peerJsSignaling: options.peerJsSignaling
+  });
+  await relay.listen();
+  config.ipcPort = relay.config.ipcPort;
+  const info = await fetchRelayInfo(config);
+  return { relay, info };
+}
+
+async function ensureLocalRelay(options = {}) {
+  let localPeerServer;
+  if (options.localPeerjs) {
+    localPeerServer = await startLocalPeerServer(options.localPeerjs === true ? {} : options.localPeerjs);
+    options = {
+      ...options,
+      peerJsSignaling: {
+        host: localPeerServer.host,
+        port: localPeerServer.port,
+        path: localPeerServer.path,
+        secure: localPeerServer.secure
+      }
+    };
+  }
+
+  const config = ensureRelayConfig({
+    ...options,
+    forcePeerJsSignaling: Boolean(options.localPeerjs),
+    ipcHost: options.ipcHost || process.env.MATTERHORN_RELAY_IPC_HOST,
+    ipcPort: options.ipcPort ?? (process.env.MATTERHORN_RELAY_IPC_PORT ? Number(process.env.MATTERHORN_RELAY_IPC_PORT) : undefined)
+  });
+  try {
+    const info = await fetchRelayInfo(config);
+    return { config, info, localPeerServer, spawned: false };
+  } catch (error) {
+    try {
+      const embedded = await startEmbeddedRelay(config, options);
+      return { config, info: embedded.info, relay: embedded.relay, localPeerServer, spawned: true };
+    } catch (startError) {
+      await localPeerServer?.close?.().catch(() => undefined);
+      throw startError || error;
+    }
+  }
+}
+
+module.exports = {
+  ensureLocalRelay,
+  fetchRelayInfo,
+  relayHealthUrl,
+  relayIpcUrl,
+  spawnRelayProcess,
+  startEmbeddedRelay,
+  waitForRelay
+};

package/runtime/host/matterhornrc.cjs

@@ -0,0 +1,75 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function userDataDir() {
+  return process.env.MATTERHORN_HOME || path.join(os.homedir(), ".matterhorn");
+}
+
+function usermatterhornrcFile() {
+  return path.join(userDataDir(), ".matterhornrc");
+}
+
+function parseKeyValueText(text) {
+  const values = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const match = /^([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(.*)$/.exec(line);
+    if (!match) continue;
+    values[match[1]] = match[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return values;
+}
+
+function normalizematterhornrc(values) {
+  const host = values.host || values.HOST_URL || values.appUrl || values.app_url;
+  const normalized = host ? { host: String(host).trim() } : {};
+  const players = Array.isArray(values.players) ? values.players : values.playerPacks;
+  if (Array.isArray(players)) {
+    normalized.players = players
+      .filter((player) => player && typeof player === "object" && typeof player.url === "string")
+      .map((player) => ({
+        url: player.url,
+        ...(player.integrity === undefined ? {} : { integrity: String(player.integrity) }),
+        ...(player.id === undefined ? {} : { id: String(player.id) }),
+        ...(player.name === undefined ? {} : { name: String(player.name) }),
+        ...(player.version === undefined ? {} : { version: String(player.version) }),
+        ...(player.addedAt === undefined ? {} : { addedAt: String(player.addedAt) })
+      }));
+  }
+  return normalized;
+}
+
+function parsematterhornrc(text) {
+  try {
+    return normalizematterhornrc(JSON.parse(text));
+  } catch {
+    return normalizematterhornrc(parseKeyValueText(text));
+  }
+}
+
+function readmatterhornrc(file = usermatterhornrcFile()) {
+  if (!fs.existsSync(file)) return {};
+  return parsematterhornrc(fs.readFileSync(file, "utf8"));
+}
+
+function writematterhornrc(values, file = usermatterhornrcFile()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(values, null, 2)}\n`);
+}
+
+function applymatterhornrcDefaults(target = process.env, file = usermatterhornrcFile()) {
+  const values = readmatterhornrc(file);
+  if (values.host && target.APP_URL === undefined && target.HOST_URL === undefined) {
+    target.HOST_URL = values.host;
+  }
+}
+
+module.exports = {
+  applymatterhornrcDefaults,
+  readmatterhornrc,
+  userDataDir,
+  usermatterhornrcFile,
+  writematterhornrc
+};