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

package/README.md

@@ -0,0 +1,5 @@
+# @mh-gg/cli
+
+Public Matterhorn CLI package used by the `matterhorn` npm bin.
+
+The package keeps local development on the monorepo CLI source and prepares a packaged runtime copy during `prepack`; release checks use `pack:verify`.

package/bin/matterhorn.cjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function localWorkspaceCli() {
+  const candidate = path.resolve(__dirname, "..", "..", "..", "bin", "matterhorn.cjs");
+  return fs.existsSync(candidate) ? candidate : "";
+}
+
+function packagedCli() {
+  const candidate = path.resolve(__dirname, "..", "runtime", "bin", "matterhorn.cjs");
+  return fs.existsSync(candidate) ? candidate : "";
+}
+
+function resolveCliPath() {
+  return localWorkspaceCli() || packagedCli();
+}
+
+function runNodeScript(script, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [script, ...args], {
+      stdio: "inherit",
+      windowsHide: true
+    });
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      resolve(code ?? 0);
+    });
+    child.on("error", reject);
+  });
+}
+
+async function main(args = process.argv.slice(2)) {
+  const cliPath = resolveCliPath();
+  if (!cliPath) {
+    throw new Error("Matterhorn CLI runtime is missing. Reinstall @mh-gg/cli or run pnpm --dir packages/matterhorn-cli run prepare:files.");
+  }
+  const code = await runNodeScript(cliPath, args);
+  process.exitCode = code;
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message || error);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  main,
+  resolveCliPath
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mh-gg/cli",
+  "version": "0.1.1-alpha.20260613T085325975Z",
+  "description": "Matterhorn command-line interface for hosting, deploying, and launching Matterhorn apps.",
+  "type": "commonjs",
+  "bin": {
+    "matterhorn": "./bin/matterhorn.cjs"
+  },
+  "exports": {
+    "./bin/matterhorn.cjs": "./bin/matterhorn.cjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "runtime",
+    "README.md"
+  ],
+  "dependencies": {
+    "@roamhq/wrtc": "^0.10.0",
+    "nostr-tools": "^2.23.5",
+    "peer": "^1.0.2",
+    "peerjs": "^1.5.5",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.0",
+    "xhr2": "^0.2.1",
+    "@mh-gg/host-config": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/base-plugins": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/base": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/host-store": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/event": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/protocol": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/host-runtime": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/host-ipc": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/schema": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/relay-mesh": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/relay-core": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/room-security": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/relay-runtime": "^0.1.1-alpha.20260613T085325975Z",
+    "@mh-gg/room-link": "^0.1.1-alpha.20260613T085325975Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "prepare:files": "node scripts/prepare-files.cjs",
+    "test:package": "node scripts/smoke-package.cjs",
+    "pack:verify": "pnpm run prepare:files && pnpm run test:package"
+  }
+}

package/runtime/bin/appFrontend/artifacts.cjs

@@ -0,0 +1,25 @@
+const fs = require("node:fs");
+const { createHash } = require("node:crypto");
+const { bundleDistDir, bundleEntryFile, bundleEntryName, bundleMountPath } = require("./paths.cjs");
+
+function fileIntegrity(filePath) {
+  return `sha256-${createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
+}
+
+function appBundleArtifact(frontend) {
+  const file = bundleEntryFile(frontend);
+  const stat = fs.statSync(file);
+  if (!stat.isFile()) throw new Error(`Built app bundle is missing ${file}`);
+  return {
+    file,
+    entry: bundleEntryName(frontend),
+    distDir: bundleDistDir(frontend),
+    mountPath: bundleMountPath(frontend),
+    byteLength: stat.size,
+    integrity: fileIntegrity(file)
+  };
+}
+
+module.exports = {
+  appBundleArtifact
+};

package/runtime/bin/appFrontend/buildServers.cjs

@@ -0,0 +1,176 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { appBundleArtifact } = require("./artifacts.cjs");
+const { bundleConfig, bundleDistDir, bundleEntryFile, bundleMountPath, frontendRoot, launcherBuildCommand, repoRoot } = require("./paths.cjs");
+const { commandSpec, runCommand } = require("./processes.cjs");
+const { assertAppCommandAllowed, commandEnvTrustForPolicy } = require("./commandPolicy.cjs");
+const { selectFrontendPort } = require("./ports.cjs");
+const { startBundleStaticFrontend, startBundledStaticFrontend, startStaticFrontend, waitForHttpOk } = require("./httpServers.cjs");
+const { ensureWorkspaceSdkBuild } = require("../../scripts/ensureWorkspaceSdkBuild.cjs");
+
+const DEFAULT_FRONTEND_BUILD_TIMEOUT_MS = 120000;
+
+function isIgnoredSourcePath(candidate, ignoredRoots) {
+  const base = path.basename(candidate);
+  if (base === "node_modules" || base === ".git" || base === ".matterhorn-live" || base === ".matterhorn-live-objects" || base === "coverage") return true;
+  const resolved = path.resolve(candidate);
+  return ignoredRoots.some((ignoredRoot) => {
+    const relative = path.relative(ignoredRoot, resolved);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+  });
+}
+
+function latestSourceMtime(root, ignoredRoots = []) {
+  if (!root || !fs.existsSync(root)) return 0;
+  const resolvedIgnoredRoots = ignoredRoots.filter(Boolean).map((item) => path.resolve(item));
+  const pending = [path.resolve(root)];
+  let latest = 0;
+
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (!current || isIgnoredSourcePath(current, resolvedIgnoredRoots)) continue;
+    let stat;
+    try {
+      stat = fs.statSync(current);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) {
+      if (stat.isFile()) latest = Math.max(latest, stat.mtimeMs);
+      continue;
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const entryPath = path.join(current, entry.name);
+      if (isIgnoredSourcePath(entryPath, resolvedIgnoredRoots)) continue;
+      if (entry.isDirectory()) {
+        pending.push(entryPath);
+      } else if (entry.isFile()) {
+        try {
+          latest = Math.max(latest, fs.statSync(entryPath).mtimeMs);
+        } catch {}
+      }
+    }
+  }
+
+  return latest;
+}
+
+function workspaceSdkBuildInputs() {
+  const sdkRoot = path.join(repoRoot(), "packages", "matterhorn-sdk");
+  return [
+    path.join(sdkRoot, "dist"),
+    path.join(sdkRoot, "package.json")
+  ].filter((target) => fs.existsSync(target));
+}
+
+function appBundleBuildRequired(frontend) {
+  const bundleFile = bundleEntryFile(frontend);
+  if (!fs.existsSync(bundleFile)) return true;
+  let bundleMtime = 0;
+  try {
+    const stat = fs.statSync(bundleFile);
+    if (!stat.isFile()) return true;
+    bundleMtime = stat.mtimeMs;
+  } catch {
+    return true;
+  }
+
+  const ignoredRoots = [bundleDistDir(frontend)];
+  const inputs = [frontendRoot(frontend), ...workspaceSdkBuildInputs()];
+  return inputs.some((input) => latestSourceMtime(input, ignoredRoots) > bundleMtime);
+}
+
+
+async function startBuiltFrontend(frontend, options = {}) {
+  const root = frontendRoot(frontend);
+  const port = await selectFrontendPort(options.port, frontend.defaultPort);
+  if (frontend.build) {
+    const policy = assertAppCommandAllowed(options.trust || frontend.trust, "matterhorn frontend build");
+    await runCommand(commandSpec(frontend.build, "build"), {
+      cwd: root,
+      label: "matterhorn frontend build",
+      logger: options.logger,
+      port,
+      trust: commandEnvTrustForPolicy(policy),
+      timeoutMs: options.buildTimeoutMs || DEFAULT_FRONTEND_BUILD_TIMEOUT_MS
+    });
+  }
+  const server = await startStaticFrontend(frontend, { port });
+  await waitForHttpOk(server.appUrl, options.timeoutMs);
+  return server;
+}
+
+async function startBundledBuiltFrontend(frontend, options = {}) {
+  const root = frontendRoot(frontend);
+  const port = await selectFrontendPort(options.port, frontend.defaultPort);
+  const bundle = bundleConfig(frontend);
+  const policy = assertAppCommandAllowed(options.trust || frontend.trust, "matterhorn bundled frontend build");
+  await ensureWorkspaceSdkBuild({ logger: options.logger, timeoutMs: options.buildTimeoutMs || DEFAULT_FRONTEND_BUILD_TIMEOUT_MS });
+  await runCommand(commandSpec(bundle.build, "bundle.build"), {
+    cwd: root,
+    label: "matterhorn app bundle build",
+    logger: options.logger,
+    port,
+    trust: commandEnvTrustForPolicy(policy),
+    timeoutMs: options.buildTimeoutMs || DEFAULT_FRONTEND_BUILD_TIMEOUT_MS
+  });
+  await runCommand(commandSpec(frontend.launcher?.build || launcherBuildCommand(), "launcher.build"), {
+    cwd: repoRoot(),
+    label: "matterhorn launcher build",
+    logger: options.logger,
+    port,
+    trust: commandEnvTrustForPolicy(policy),
+    timeoutMs: options.buildTimeoutMs || DEFAULT_FRONTEND_BUILD_TIMEOUT_MS
+  });
+  const server = await startBundledStaticFrontend(frontend, { port });
+  await waitForHttpOk(server.appUrl, options.timeoutMs);
+  await waitForHttpOk(server.bundleUrl, options.timeoutMs);
+  return server;
+}
+
+async function buildAppBundleFrontend(appOrFrontend, options = {}) {
+  const frontend = appOrFrontend?.frontend || appOrFrontend;
+  if (!frontend?.bundle) throw new Error("App does not declare a bundled frontend");
+  const root = frontendRoot(frontend);
+  const port = options.port ?? options.bundlePort ?? frontend.bundle.defaultPort ?? 0;
+  const policy = assertAppCommandAllowed(options.trust || frontend.trust || appOrFrontend?.trust, "matterhorn app bundle build");
+  await ensureWorkspaceSdkBuild({ logger: options.logger, timeoutMs: options.buildTimeoutMs || DEFAULT_FRONTEND_BUILD_TIMEOUT_MS });
+  if (!options.force && !appBundleBuildRequired(frontend)) {
+    options.logger?.log?.(`matterhorn app bundle build skipped: ${bundleEntryFile(frontend)} is current`);
+    return appBundleArtifact(frontend);
+  }
+  await runCommand(commandSpec(frontend.bundle.build, "bundle.build"), {
+    cwd: root,
+    label: "matterhorn app bundle build",
+    logger: options.logger,
+    port,
+    bundlePort: options.bundlePort ?? port,
+    mountPath: bundleMountPath(frontend),
+    trust: commandEnvTrustForPolicy(policy),
+    timeoutMs: options.buildTimeoutMs || DEFAULT_FRONTEND_BUILD_TIMEOUT_MS
+  });
+  return appBundleArtifact(frontend);
+}
+
+async function startBundleBuiltFrontend(frontend, options = {}) {
+  const bundle = bundleConfig(frontend);
+  const port = await selectFrontendPort(options.port ?? options.bundlePort, bundle.defaultPort);
+  await buildAppBundleFrontend(frontend, { ...options, port, bundlePort: port });
+  const server = await startBundleStaticFrontend(frontend, { port });
+  await waitForHttpOk(server.bundleUrl, options.timeoutMs);
+  return server;
+}
+
+module.exports = {
+  appBundleBuildRequired,
+  buildAppBundleFrontend,
+  startBundleBuiltFrontend,
+  startBuiltFrontend,
+  startBundledBuiltFrontend
+};

package/runtime/bin/appFrontend/commandEnv.cjs

@@ -0,0 +1,74 @@
+const MATTERHORN_PUBLIC_KEYS = new Set([
+  "MATTERHORN_APP_BUNDLE_MOUNT",
+  "MATTERHORN_APP_BUNDLE_TARGET",
+  "MATTERHORN_BUNDLE_BASE",
+  "MATTERHORN_BUNDLE_PORT",
+  "MATTERHORN_FRONTEND_PORT"
+]);
+
+function baseProcessEnv() {
+  const env = {};
+  for (const key of ["PATH", "Path", "ComSpec", "SystemRoot", "WINDIR", "TEMP", "TMP", "HOME", "USERPROFILE"]) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  return env;
+}
+
+function sensitiveEnvKey(key) {
+  const upper = String(key).toUpperCase();
+  if (MATTERHORN_PUBLIC_KEYS.has(upper)) return false;
+  if (upper === "NODE_OPTIONS" || upper === "SSH_AUTH_SOCK") return true;
+  if (upper.startsWith("AWS_") || upper.startsWith("GOOGLE_") || upper.startsWith("AZURE_")) return true;
+  return /(?:^|_)(?:TOKEN|SECRET|PASSWORD|KEY)$/.test(upper);
+}
+
+function validateCommandEnv(commandEnv = {}, options = {}) {
+  for (const key of Object.keys(commandEnv || {})) {
+    if (!sensitiveEnvKey(key)) continue;
+    if (options.trust === "trusted-local-dev" && options.allowSensitiveCommandEnv === true) continue;
+    throw new Error(`App command env key ${key} is not allowed by Matterhorn command env policy`);
+  }
+}
+
+function commandPortEnv(input = {}) {
+  const env = {};
+  if (input.port !== undefined) {
+    env.PORT = String(input.port);
+    env.MATTERHORN_FRONTEND_PORT = String(input.port);
+  }
+  if (input.bundlePort !== undefined) env.MATTERHORN_BUNDLE_PORT = String(input.bundlePort);
+  if (input.mountPath !== undefined) env.MATTERHORN_BUNDLE_BASE = String(input.mountPath || "/");
+  return env;
+}
+
+function canUnsafeInherit(input) {
+  if (input.trust !== "trusted-local-dev") return false;
+  return input.unsafeInheritEnv === true || process.env.MATTERHORN_UNSAFE_APP_FULL_ENV === "1";
+}
+
+function buildMatterhornCommandEnv(input = {}) {
+  const trust = input.trust || "untrusted-metadata";
+  const commandEnv = input.commandEnv || {};
+  validateCommandEnv(commandEnv, {
+    trust,
+    allowSensitiveCommandEnv: input.allowSensitiveCommandEnv
+  });
+  return {
+    ...(canUnsafeInherit({ ...input, trust }) ? process.env : baseProcessEnv()),
+    ...commandPortEnv(input),
+    ...commandEnv
+  };
+}
+
+const SECRET_VALUE_PATTERN = /(?:npm|github|ghp|aws|secret|token|password|key)[A-Za-z0-9_./+=:-]{8,}/gi;
+
+function redactCommandOutput(value) {
+  return String(value).replace(SECRET_VALUE_PATTERN, "[REDACTED]");
+}
+
+module.exports = {
+  buildMatterhornCommandEnv,
+  redactCommandOutput,
+  sensitiveEnvKey,
+  validateCommandEnv
+};

package/runtime/bin/appFrontend/commandPolicy.cjs

@@ -0,0 +1,23 @@
+const RUNNABLE_COMMAND_POLICIES = new Set(["allowlisted", "sandboxed", "trusted-local-dev"]);
+
+function commandPolicyFromTrust(trust) {
+  return trust?.commandExecution || "trusted-local-dev";
+}
+
+function commandEnvTrustForPolicy(policy) {
+  if (policy === "trusted-local-dev") return "trusted-local-dev";
+  if (policy === "allowlisted" || policy === "sandboxed") return "trusted-installed";
+  return "untrusted-metadata";
+}
+
+function assertAppCommandAllowed(trust, label) {
+  const policy = commandPolicyFromTrust(trust);
+  if (RUNNABLE_COMMAND_POLICIES.has(policy)) return policy;
+  throw new Error(`${label} requires app command execution trust; metadata-only app sources cannot run frontend commands`);
+}
+
+module.exports = {
+  assertAppCommandAllowed,
+  commandEnvTrustForPolicy,
+  commandPolicyFromTrust
+};

package/runtime/bin/appFrontend/devServers.cjs

@@ -0,0 +1,150 @@
+const { bundleConfig, bundleMountPath, bundleUrl, frontendRoot, frontendUrl, launcherDevCommand, repoRoot } = require("./paths.cjs");
+const { closeChildProcess, commandSpec, spawnCommand } = require("./processes.cjs");
+const { assertAppCommandAllowed, commandEnvTrustForPolicy } = require("./commandPolicy.cjs");
+const { selectFrontendPort } = require("./ports.cjs");
+const { waitForHttpOk } = require("./httpServers.cjs");
+
+async function startDevFrontend(frontend, options = {}) {
+  const root = frontendRoot(frontend);
+  const port = await selectFrontendPort(options.port, frontend.defaultPort);
+  const spec = commandSpec(frontend.dev, "dev");
+  const policy = assertAppCommandAllowed(options.trust || frontend.trust, "matterhorn frontend dev");
+  const child = spawnCommand(spec, {
+    cwd: root,
+    label: "matterhorn frontend dev",
+    logger: options.logger,
+    port,
+    trust: commandEnvTrustForPolicy(policy)
+  });
+  const appUrl = frontendUrl(port, frontend.devBasePath || frontend.basePath || "/");
+  try {
+    await waitForHttpOk(new URL(frontend.dev?.healthPath || "/", appUrl).toString(), options.timeoutMs);
+  } catch (error) {
+    await closeChildProcess(child);
+    throw error;
+  }
+  let closed = false;
+  return {
+    appUrl,
+    mode: "dev",
+    port,
+    process: child,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await closeChildProcess(child);
+    }
+  };
+}
+
+async function startBundleDevFrontend(frontend, options = {}) {
+  const root = frontendRoot(frontend);
+  const bundle = bundleConfig(frontend);
+  const bundlePort = await selectFrontendPort(options.port ?? options.bundlePort, bundle.defaultPort);
+  const mountPath = bundleMountPath(frontend);
+  const bundleSpec = commandSpec(bundle.dev, "bundle.dev");
+  const policy = assertAppCommandAllowed(options.trust || frontend.trust, "matterhorn app bundle dev");
+  const bundleChild = spawnCommand(bundleSpec, {
+    cwd: root,
+    label: "matterhorn app bundle dev",
+    logger: options.logger,
+    port: bundlePort,
+    bundlePort,
+    mountPath,
+    trust: commandEnvTrustForPolicy(policy)
+  });
+  const appUrl = frontendUrl(bundlePort, "/");
+  try {
+    const healthPath = bundle.healthPath || bundle.devEntry || "";
+    await waitForHttpOk(new URL(`${mountPath}${healthPath}`, appUrl).toString(), options.timeoutMs);
+  } catch (error) {
+    await closeChildProcess(bundleChild);
+    throw error;
+  }
+  let closed = false;
+  return {
+    appUrl,
+    bundleUrl: bundleUrl(appUrl, mountPath, bundle.devEntry || "src/index.tsx"),
+    mode: "dev",
+    port: bundlePort,
+    bundlePort,
+    process: bundleChild,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await closeChildProcess(bundleChild);
+    }
+  };
+}
+
+async function startBundledDevFrontend(frontend, options = {}) {
+  const root = frontendRoot(frontend);
+  const launcherPort = await selectFrontendPort(options.port, frontend.defaultPort);
+  const appBundlePort = await selectFrontendPort(options.bundlePort, frontend.bundle?.defaultPort);
+  const bundle = bundleConfig(frontend);
+  const mountPath = bundleMountPath(frontend);
+  const bundleSpec = commandSpec(bundle.dev, "bundle.dev");
+  const policy = assertAppCommandAllowed(options.trust || frontend.trust, "matterhorn bundled frontend dev");
+  const bundleChild = spawnCommand(bundleSpec, {
+    cwd: root,
+    label: "matterhorn app bundle dev",
+    logger: options.logger,
+    port: launcherPort,
+    bundlePort: appBundlePort,
+    mountPath,
+    trust: commandEnvTrustForPolicy(policy)
+  });
+  const bundleBaseUrl = frontendUrl(appBundlePort, "/");
+
+  try {
+    const healthPath = bundle.healthPath || bundle.devEntry || "";
+    await waitForHttpOk(new URL(`${mountPath}${healthPath}`, bundleBaseUrl).toString(), options.timeoutMs);
+  } catch (error) {
+    await closeChildProcess(bundleChild);
+    throw error;
+  }
+
+  const launcherSpec = commandSpec(frontend.launcher?.dev || launcherDevCommand(), "launcher.dev");
+  const launcherChild = spawnCommand(launcherSpec, {
+    cwd: repoRoot(),
+    label: "matterhorn launcher dev",
+    logger: options.logger,
+    port: launcherPort,
+    bundlePort: appBundlePort,
+    mountPath,
+    env: {
+      MATTERHORN_APP_BUNDLE_TARGET: bundleBaseUrl,
+      MATTERHORN_APP_BUNDLE_MOUNT: mountPath
+    },
+    trust: commandEnvTrustForPolicy(policy)
+  });
+  const appUrl = frontendUrl(launcherPort, frontend.launcher?.devBasePath || "/");
+  try {
+    await waitForHttpOk(new URL(frontend.launcher?.healthPath || "/", appUrl).toString(), options.timeoutMs);
+  } catch (error) {
+    await closeChildProcess(launcherChild);
+    await closeChildProcess(bundleChild);
+    throw error;
+  }
+
+  let closed = false;
+  return {
+    appUrl,
+    bundleUrl: bundleUrl(appUrl, mountPath, bundle.devEntry || "src/index.tsx"),
+    mode: "dev",
+    port: launcherPort,
+    bundlePort: appBundlePort,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await closeChildProcess(launcherChild);
+      await closeChildProcess(bundleChild);
+    }
+  };
+}
+
+module.exports = {
+  startBundleDevFrontend,
+  startBundledDevFrontend,
+  startDevFrontend
+};