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

package/runtime/bin/appHostCommand.cjs

@@ -0,0 +1,381 @@
+const { spawn } = require("node:child_process");
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const { slugifyRoom } = require("@mh-gg/room-link");
+const { manifestHash } = require("@mh-gg/base");
+const { appBundleArtifact, buildAppBundleFrontend, startAppBundleFrontend, parseServeMode } = require("./appFrontend.cjs");
+const { bundleConfig, bundleMountPath, frontendRoot } = require("./appFrontend/paths.cjs");
+const { commandSpec } = require("./appFrontend/processes.cjs");
+const { buildMatterhornCommandEnv } = require("./appFrontend/commandEnv.cjs");
+const { emitMatterhornBundleForRef, loadMatterhornApp } = require("./matterhornAppLoader.cjs");
+
+const MATTERHORN_OPTIONS = new Set(["--serve", "--frontend-port"]);
+const HOST_URL_OPTIONS = new Set(["--app-url", "--host-url"]);
+const DEFAULT_RELAY_CHUNK_SIZE = 11 * 1024;
+
+function splitAtSeparator(args) {
+  const index = args.indexOf("--");
+  if (index === -1) return { matterhornArgs: args, hostArgs: [] };
+  return {
+    matterhornArgs: args.slice(0, index),
+    hostArgs: args.slice(index + 1)
+  };
+}
+
+function optionHasValue(args, index) {
+  return args[index + 1] !== undefined && !args[index + 1].startsWith("--");
+}
+
+function hostArgsHaveAppUrl(args) {
+  return args.some((arg) => HOST_URL_OPTIONS.has(arg));
+}
+
+function appendHostOption(hostArgs, args, index) {
+  hostArgs.push(args[index]);
+  if (optionHasValue(args, index)) {
+    hostArgs.push(args[index + 1]);
+    return index + 1;
+  }
+  return index;
+}
+
+function parseAppHostArgs(args) {
+  const { matterhornArgs, hostArgs: separatedHostArgs } = splitAtSeparator(args);
+  const [appRef, roomName, ...rest] = matterhornArgs;
+  if (!appRef || !roomName) throw new Error("Usage: matterhorn <app-ref> <room-slug> [--serve [dev|built]] -- [host options]");
+
+  const parsed = {
+    appRef,
+    roomName: slugifyRoom(roomName),
+    serveMode: undefined,
+    frontendPort: undefined,
+    hostArgs: [...separatedHostArgs]
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const token = rest[index];
+    if (token === "--serve") {
+      if (optionHasValue(rest, index)) {
+        parsed.serveMode = parseServeMode(rest[index + 1]);
+        index += 1;
+      } else {
+        parsed.serveMode = "dev";
+      }
+      continue;
+    }
+    if (token === "--frontend-port") {
+      if (!optionHasValue(rest, index)) throw new Error("--frontend-port requires a port");
+      parsed.frontendPort = Number(rest[index + 1]);
+      if (!Number.isInteger(parsed.frontendPort) || parsed.frontendPort <= 0) throw new Error("--frontend-port must be a positive integer");
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--") && !MATTERHORN_OPTIONS.has(token)) {
+      index = appendHostOption(parsed.hostArgs, rest, index);
+      continue;
+    }
+    throw new Error(`Unexpected Matterhorn argument ${token}`);
+  }
+
+  return parsed;
+}
+
+function createHostProcessArgs(plan, options = {}) {
+  const args = [
+    path.join(__dirname, "..", "host", "host.cjs"),
+    "--room",
+    plan.roomName,
+    "--data-dir",
+    options.dataDir,
+    ...plan.hostArgs
+  ];
+  if (!hostArgsHaveAppUrl(plan.hostArgs)) args.push("--app-url", options.defaultAppUrl);
+  return args;
+}
+
+function appHostRunner(app) {
+  return app.host?.runner || "matterhorn-example-host";
+}
+
+function assertSupportedHostRunner(app) {
+  const runner = appHostRunner(app);
+  if (runner !== "matterhorn-example-host") {
+    throw new Error(`Unsupported Matterhorn host runner ${runner}`);
+  }
+}
+
+function frontendLocations(app, appFrontend) {
+  const declared = Array.isArray(app.frontend?.locations) ? app.frontend.locations : [];
+  const locations = declared.map((location) => ({ ...location }));
+  if (appFrontend?.bundleUrl) {
+    locations.unshift({
+      type: "local-server",
+      mode: appFrontend.mode,
+      url: appFrontend.bundleUrl
+    });
+  }
+  if (locations.length === 0 && app.ref) locations.push({ type: "app-ref", ref: app.ref });
+  return locations;
+}
+
+function frontendBackgroundColor(app) {
+  const color = app.frontend?.backgroundColor;
+  if (typeof color !== "string") return undefined;
+  const cleaned = color.trim();
+  if (!cleaned || cleaned.length > 128) return undefined;
+  return cleaned;
+}
+
+function cleanFrontendIconString(value, max = 64 * 1024) {
+  if (typeof value !== "string") return undefined;
+  const cleaned = value.trim();
+  if (!cleaned || cleaned.length > max) return undefined;
+  return cleaned;
+}
+
+function frontendIconDeclaration(app) {
+  const declared = app.frontend?.icon || app.frontend?.bundle?.icon;
+  if (typeof declared === "string") {
+    const iconPath = cleanFrontendIconString(declared, 512);
+    return iconPath ? { path: iconPath } : undefined;
+  }
+  if (!declared || typeof declared !== "object") return undefined;
+  const iconPath = cleanFrontendIconString(declared.path, 512);
+  const svg = cleanFrontendIconString(declared.svg);
+  const label = cleanFrontendIconString(declared.label, 120);
+  if (!iconPath && !svg) return undefined;
+  return {
+    ...(iconPath ? { path: iconPath } : {}),
+    ...(svg ? { svg } : {}),
+    ...(label ? { label } : {})
+  };
+}
+
+function safeFrontendAssetPath(root, assetPath) {
+  const base = path.resolve(root || process.cwd());
+  const file = path.resolve(base, assetPath);
+  if (file !== base && !file.startsWith(base + path.sep)) throw new Error(`Frontend icon path escapes ${base}`);
+  return file;
+}
+
+function cleanSvgIcon(value) {
+  const svg = cleanFrontendIconString(value);
+  if (!svg || !/^(?:<\?xml[\s\S]*?\?>\s*)?<svg[\s>]/i.test(svg)) return undefined;
+  if (/<(?:script|foreignObject|iframe|object|embed|link)\b/i.test(svg)) return undefined;
+  if (/\son[a-z]+\s*=/i.test(svg) || /javascript\s*:/i.test(svg)) return undefined;
+  return svg;
+}
+
+function frontendIconInfo(app) {
+  const declared = frontendIconDeclaration(app);
+  if (!declared) return undefined;
+  const svg = cleanSvgIcon(declared.svg || fs.readFileSync(safeFrontendAssetPath(app.frontend?.root || app.sourceRoot, declared.path), "utf8"));
+  if (!svg) return undefined;
+  return {
+    type: "image/svg+xml",
+    svg,
+    label: declared.label || app.name,
+    integrity: `sha256-${crypto.createHash("sha256").update(svg).digest("hex")}`,
+    byteLength: Buffer.byteLength(svg)
+  };
+}
+
+function roomFrontendInfo(app, appFrontend, relayBundle) {
+  const playerPack = app.playerPacks?.[0];
+  const bundle = relayBundle || (appFrontend?.bundleFile ? {
+    file: appFrontend.bundleFile,
+    entry: appFrontend.bundleEntry,
+    integrity: appFrontend.bundleIntegrity,
+    byteLength: appFrontend.bundleByteLength
+  } : undefined);
+  if (!playerPack || !bundle) return undefined;
+  const backgroundColor = frontendBackgroundColor(app);
+  const icon = frontendIconInfo(app);
+  return {
+    id: playerPack.id,
+    name: playerPack.name,
+    version: playerPack.version,
+    ...(relayBundle?.dynamic ? { dynamic: true } : {}),
+    appPackId: app.appPack.id,
+    appPackHash: manifestHash(app.appPack),
+    playerPackId: playerPack.id,
+    playerPackVersion: playerPack.version,
+    sourceRef: app.ref,
+    locations: frontendLocations(app, appFrontend),
+    ...(backgroundColor ? { backgroundColor } : {}),
+    ...(icon ? { icon } : {}),
+    entrypoint: bundle.entry,
+    delivery: "relay-chunks",
+    integrity: bundle.integrity,
+    byteLength: bundle.byteLength,
+    chunkSize: DEFAULT_RELAY_CHUNK_SIZE
+  };
+}
+
+function roomPluginInfo(app) {
+  return (app.hostPlugins || [])
+    .filter((plugin) => plugin?.id)
+    .map((plugin) => ({
+      id: plugin.id,
+      version: plugin.version
+    }));
+}
+
+function roomAppInfo(app, appFrontend, relayBundle) {
+  const playerPack = app.playerPacks?.[0];
+  const frontend = roomFrontendInfo(app, appFrontend, relayBundle);
+  const composition = app.appPack?.composition || app.compositionSchema;
+  return {
+    sourceRef: app.ref,
+    appPack: {
+      id: app.appPack.id,
+      version: app.appPack.version,
+      hash: manifestHash(app.appPack),
+      protocolHash: app.appPack.compatibility.appProtocolHash,
+      ...(composition ? { composition } : {})
+    },
+    ...(composition ? { composition } : {}),
+    playerPack: playerPack ? {
+      id: playerPack.id,
+      version: playerPack.version
+    } : undefined,
+    plugins: roomPluginInfo(app),
+    frontends: frontend ? [frontend] : []
+  };
+}
+
+function prebuiltRelayBundle(app) {
+  if (!app.frontend?.bundle) return undefined;
+  if (app.frontend.bundle.prebuilt !== true && app.frontend.bundle.build) return undefined;
+  return appBundleArtifact(app.frontend);
+}
+
+function sdkAppBundleEmitCommand(app, plan, options = {}) {
+  if (app.sourceKind !== "defineApp") return undefined;
+  return {
+    command: process.execPath,
+    args: [path.join(__dirname, "matterhornEmitAppBundle.cjs"), plan.appRef, options.cwd || process.cwd()],
+    cwd: app.sourceRoot || options.cwd || process.cwd()
+  };
+}
+
+function devRelayBundleRebuildConfig(app, plan, options = {}) {
+  if (!app.frontend?.bundle?.build) return undefined;
+  const bundle = bundleConfig(app.frontend);
+  const port = plan.frontendPort ?? bundle.defaultPort ?? 0;
+  const spec = commandSpec(bundle.build, "bundle.build");
+  const before = [sdkAppBundleEmitCommand(app, plan, options)].filter(Boolean);
+  return {
+    command: spec.command,
+    args: spec.args,
+    env: spec.env,
+    cwd: frontendRoot(app.frontend),
+    trust: app.trust?.commandExecution || "trusted-local-dev",
+    port,
+    bundlePort: port,
+    mountPath: bundleMountPath(app.frontend),
+    ...(before.length ? { before } : {})
+  };
+}
+
+async function runAppHostCommand(args, io = console, options = {}) {
+  const plan = parseAppHostArgs(args);
+  const cwd = options.cwd || process.cwd();
+  const app = loadMatterhornApp(plan.appRef, { cwd });
+  if (app.sourceKind === "defineApp") emitMatterhornBundleForRef(plan.appRef, { cwd });
+  assertSupportedHostRunner(app);
+  const serveMode = plan.serveMode || "dev";
+  let appFrontend;
+  let relayBundle;
+  if (app.frontend) {
+    relayBundle = prebuiltRelayBundle(app);
+    if (!relayBundle && serveMode === "dev") {
+      relayBundle = await buildAppBundleFrontend(app, {
+        port: plan.frontendPort,
+        logger: options.frontendLogger || io
+      });
+      relayBundle.dynamic = true;
+      relayBundle.sourceRoot = frontendRoot(app.frontend);
+      relayBundle.sourceRoots = [frontendRoot(app.frontend), app.sourceEntry].filter(Boolean);
+      relayBundle.rebuild = devRelayBundleRebuildConfig(app, plan, { cwd });
+    }
+    if (!relayBundle) {
+      appFrontend = await startAppBundleFrontend(app, {
+        mode: serveMode,
+        port: plan.frontendPort,
+        logger: options.frontendLogger || io
+      });
+      if (appFrontend.bundleFile) {
+        relayBundle = {
+          file: appFrontend.bundleFile,
+          entry: appFrontend.bundleEntry,
+          integrity: appFrontend.bundleIntegrity,
+          byteLength: appFrontend.bundleByteLength
+        };
+      }
+    }
+  }
+
+  io.log(`Matterhorn app: ${app.name} (${app.id}@${app.version || app.appPack?.version || "unknown"})`);
+  if (appFrontend) io.log(`App frontend: ${appFrontend.mode} ${appFrontend.appUrl}`);
+  if (relayBundle?.file) io.log(`Relay bundle: ${relayBundle.file}`);
+
+  const hostArgs = createHostProcessArgs(plan, {
+    dataDir: options.dataDir,
+    defaultAppUrl: options.defaultAppUrl
+  });
+  const roomApp = roomAppInfo(app, appFrontend, relayBundle);
+  const child = spawn(process.execPath, hostArgs, {
+    env: buildMatterhornCommandEnv({
+      trust: "matterhorn-internal",
+      commandEnv: {
+      MATTERHORN_APP_REF: plan.appRef,
+      MATTERHORN_APP_CWD: options.cwd || process.cwd(),
+      MATTERHORN_ROOM_APP: JSON.stringify(roomApp),
+      MATTERHORN_FRONTEND_BUNDLE_FILE: relayBundle?.file || "",
+      MATTERHORN_FRONTEND_BUNDLE_ID: roomApp.frontends?.[0]?.id || "",
+      MATTERHORN_FRONTEND_BUNDLE_INTEGRITY: relayBundle?.integrity || "",
+      MATTERHORN_FRONTEND_BUNDLE_DYNAMIC: relayBundle?.dynamic ? "1" : "",
+      MATTERHORN_FRONTEND_BUNDLE_SOURCE_ROOT: relayBundle?.sourceRoot || "",
+      MATTERHORN_FRONTEND_BUNDLE_SOURCE_ROOTS: relayBundle?.sourceRoots?.join(path.delimiter) || "",
+      MATTERHORN_FRONTEND_BUNDLE_REBUILD: relayBundle?.rebuild ? JSON.stringify(relayBundle.rebuild) : ""
+      }
+    }),
+    stdio: options.hostStdio || "inherit",
+    detached: options.background === true,
+    windowsHide: options.windowsHide === undefined ? false : options.windowsHide
+  });
+
+  if (options.background) {
+    child.unref();
+    return 0;
+  }
+
+  return await new Promise((resolve, reject) => {
+    child.on("exit", async (code, signal) => {
+      await appFrontend?.close?.();
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      resolve(code ?? 0);
+    });
+    child.on("error", async (error) => {
+      await appFrontend?.close?.();
+      reject(error);
+    });
+  });
+}
+
+module.exports = {
+  createHostProcessArgs,
+  hostArgsHaveAppUrl,
+  parseAppHostArgs,
+  devRelayBundleRebuildConfig,
+  sdkAppBundleEmitCommand,
+  prebuiltRelayBundle,
+  roomFrontendInfo,
+  roomAppInfo,
+  runAppHostCommand
+};