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

package/runtime/bin/appFrontend/httpServers.cjs

@@ -0,0 +1,221 @@
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
+const http = require("node:http");
+const path = require("node:path");
+const { appBundleArtifact } = require("./artifacts.cjs");
+const {
+  bundleConfig,
+  bundleDistDir,
+  bundleMountPath,
+  bundleUrl,
+  ensureLeadingSlash,
+  ensureTrailingSlash,
+  frontendRoot,
+  frontendUrl,
+  launcherDist
+} = require("./paths.cjs");
+
+const DEFAULT_FRONTEND_START_TIMEOUT_MS = 30000;
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForHttpOk(url, timeoutMs = DEFAULT_FRONTEND_START_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) return response;
+      lastError = new Error(`HTTP ${response.status}`);
+    } catch (error) {
+      lastError = error;
+    }
+    await delay(100);
+  }
+  throw lastError || new Error(`Timed out waiting for ${url}`);
+}
+
+function contentType(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  if (extension === ".html") return "text/html; charset=utf-8";
+  if (extension === ".js") return "text/javascript; charset=utf-8";
+  if (extension === ".css") return "text/css; charset=utf-8";
+  if (extension === ".json") return "application/json; charset=utf-8";
+  if (extension === ".svg") return "image/svg+xml";
+  if (extension === ".png") return "image/png";
+  if (extension === ".jpg" || extension === ".jpeg") return "image/jpeg";
+  if (extension === ".webp") return "image/webp";
+  return "application/octet-stream";
+}
+
+function requestPathname(requestUrl) {
+  try {
+    return decodeURIComponent(new URL(requestUrl, "http://127.0.0.1").pathname);
+  } catch {
+    return "/";
+  }
+}
+
+function staticPathForRequest(distDir, basePath, requestUrl) {
+  const root = path.resolve(distDir);
+  const normalizedBase = ensureTrailingSlash(ensureLeadingSlash(basePath));
+  let pathname = requestPathname(requestUrl);
+  if (normalizedBase !== "/" && pathname.startsWith(normalizedBase)) {
+    pathname = `/${pathname.slice(normalizedBase.length)}`;
+  }
+  if (pathname === "/" || pathname.endsWith("/")) pathname = `${pathname}index.html`;
+  const target = path.resolve(root, `.${pathname}`);
+  const relative = path.relative(root, target);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return path.join(root, "index.html");
+  return target;
+}
+
+async function serveFile(response, filePath) {
+  try {
+    const stat = await fsp.stat(filePath);
+    if (!stat.isFile()) throw new Error("not a file");
+    response.writeHead(200, { "content-type": contentType(filePath) });
+    fs.createReadStream(filePath).pipe(response);
+  } catch {
+    response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+    response.end("Not found");
+  }
+}
+
+function closeServer(server) {
+  return new Promise((resolve) => server.close(() => resolve()));
+}
+
+function startStaticFrontend(frontend, options = {}) {
+  const distDir = path.resolve(frontendRoot(frontend), frontend.dist || "dist");
+  const basePath = frontend.builtBasePath || frontend.basePath || "/";
+  const indexPath = path.join(distDir, "index.html");
+  if (!fs.existsSync(indexPath)) throw new Error(`Built frontend is missing ${indexPath}`);
+
+  const server = http.createServer(async (request, response) => {
+    const requestedFile = staticPathForRequest(distDir, basePath, request.url || "/");
+    await serveFile(response, fs.existsSync(requestedFile) ? requestedFile : indexPath);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, "127.0.0.1", () => {
+      server.off("error", reject);
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : options.port;
+      resolve({
+        appUrl: frontendUrl(port, basePath),
+        mode: "built",
+        port,
+        close: () => closeServer(server)
+      });
+    });
+  });
+}
+
+function startBundledStaticFrontend(frontend, options = {}) {
+  const bundle = bundleConfig(frontend);
+  const shellDir = launcherDist(frontend);
+  const bundleDir = bundleDistDir(frontend);
+  const basePath = frontend.launcher?.builtBasePath || frontend.builtBasePath || "/matterhorn/";
+  const mountPath = bundleMountPath(frontend);
+  const shellIndex = path.join(shellDir, "index.html");
+  const artifact = appBundleArtifact(frontend);
+  if (!fs.existsSync(shellIndex)) throw new Error(`Built launcher is missing ${shellIndex}`);
+  if (!fs.existsSync(artifact.file)) throw new Error(`Built app bundle is missing ${artifact.file}`);
+
+  const server = http.createServer(async (request, response) => {
+    const pathname = requestPathname(request.url || "/");
+    if (pathname.startsWith(mountPath)) {
+      const relativePath = pathname.slice(mountPath.length);
+      const target = path.resolve(bundleDir, relativePath || (bundle.builtEntry || "matterhorn-app.js"));
+      const relative = path.relative(bundleDir, target);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        response.end("Not found");
+        return;
+      }
+      await serveFile(response, target);
+      return;
+    }
+
+    const requestedFile = staticPathForRequest(shellDir, basePath, request.url || "/");
+    await serveFile(response, fs.existsSync(requestedFile) ? requestedFile : shellIndex);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, "127.0.0.1", () => {
+      server.off("error", reject);
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : options.port;
+      const appUrl = frontendUrl(port, basePath);
+      resolve({
+        appUrl,
+        bundleUrl: bundleUrl(appUrl, mountPath, artifact.entry),
+        bundleFile: artifact.file,
+        bundleEntry: artifact.entry,
+        bundleIntegrity: artifact.integrity,
+        bundleByteLength: artifact.byteLength,
+        mode: "built",
+        port,
+        close: () => closeServer(server)
+      });
+    });
+  });
+}
+
+function startBundleStaticFrontend(frontend, options = {}) {
+  const bundle = bundleConfig(frontend);
+  const bundleDir = bundleDistDir(frontend);
+  const mountPath = bundleMountPath(frontend);
+  const artifact = appBundleArtifact(frontend);
+
+  const server = http.createServer(async (request, response) => {
+    const pathname = requestPathname(request.url || "/");
+    if (!pathname.startsWith(mountPath)) {
+      response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      response.end("Not found");
+      return;
+    }
+    const relativePath = pathname.slice(mountPath.length);
+    const target = path.resolve(bundleDir, relativePath || (bundle.builtEntry || "matterhorn-app.js"));
+    const relative = path.relative(bundleDir, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+      response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      response.end("Not found");
+      return;
+    }
+    await serveFile(response, target);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, "127.0.0.1", () => {
+      server.off("error", reject);
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : options.port;
+      const rootUrl = frontendUrl(port, "/");
+      resolve({
+        appUrl: rootUrl,
+        bundleUrl: bundleUrl(rootUrl, mountPath, artifact.entry),
+        bundleFile: artifact.file,
+        bundleEntry: artifact.entry,
+        bundleIntegrity: artifact.integrity,
+        bundleByteLength: artifact.byteLength,
+        mode: "built",
+        port,
+        close: () => closeServer(server)
+      });
+    });
+  });
+}
+
+module.exports = {
+  startBundleStaticFrontend,
+  startBundledStaticFrontend,
+  startStaticFrontend,
+  waitForHttpOk
+};

package/runtime/bin/appFrontend/paths.cjs

@@ -0,0 +1,103 @@
+const path = require("node:path");
+
+function parseServeMode(value) {
+  if (value === true || value === undefined || value === "") return "dev";
+  const mode = String(value).trim().toLowerCase();
+  if (mode === "dev" || mode === "development") return "dev";
+  if (mode === "built" || mode === "build" || mode === "static" || mode === "dist") return "built";
+  throw new Error(`Unsupported frontend serve mode "${value}". Use dev or built.`);
+}
+
+function frontendRoot(frontend) {
+  if (!frontend?.root) throw new Error("App frontend.root is required");
+  return path.resolve(frontend.root);
+}
+
+function ensureLeadingSlash(value) {
+  if (!value) return "/";
+  return value.startsWith("/") ? value : `/${value}`;
+}
+
+function ensureTrailingSlash(value) {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function frontendUrl(port, basePath = "/") {
+  return `http://127.0.0.1:${port}${ensureTrailingSlash(ensureLeadingSlash(basePath))}`;
+}
+
+function repoRoot() {
+  return path.resolve(__dirname, "..", "..");
+}
+
+function launcherDevCommand() {
+  return {
+    command: process.execPath,
+    args: [
+      path.join(repoRoot(), "node_modules", "vite", "bin", "vite.js"),
+      "--config",
+      path.join("client", "vite.config.ts"),
+      "--host",
+      "127.0.0.1",
+      "--port",
+      "${port}",
+      "--strictPort"
+    ]
+  };
+}
+
+function launcherBuildCommand() {
+  return {
+    command: process.platform === "win32" ? "pnpm.cmd" : "pnpm",
+    args: ["run", "build:launcher"]
+  };
+}
+
+function launcherDist(frontend = {}) {
+  return path.resolve(frontend.launcher?.dist || path.join(repoRoot(), "client", "dist"));
+}
+
+function bundleConfig(frontend) {
+  if (!frontend?.bundle) throw new Error("App frontend.bundle is required");
+  return frontend.bundle;
+}
+
+function bundleMountPath(frontend) {
+  const bundle = bundleConfig(frontend);
+  return ensureTrailingSlash(ensureLeadingSlash(bundle.mountPath || `/matterhorn/apps/${frontend.appId || "app"}/`));
+}
+
+function bundleUrl(appUrl, mountPath, entry) {
+  return new URL(`${mountPath}${entry}`, appUrl).toString();
+}
+
+function bundleDistDir(frontend) {
+  const bundle = bundleConfig(frontend);
+  return path.resolve(frontendRoot(frontend), bundle.dist || "frontend/dist");
+}
+
+function bundleEntryName(frontend) {
+  return bundleConfig(frontend).builtEntry || "matterhorn-app.js";
+}
+
+function bundleEntryFile(frontend) {
+  return path.join(bundleDistDir(frontend), bundleEntryName(frontend));
+}
+
+module.exports = {
+  bundleConfig,
+  bundleDistDir,
+  bundleEntryFile,
+  bundleEntryName,
+  bundleMountPath,
+  bundleUrl,
+  ensureLeadingSlash,
+  ensureTrailingSlash,
+  frontendRoot,
+  frontendUrl,
+  launcherBuildCommand,
+  launcherDevCommand,
+  launcherDist,
+  parseServeMode,
+  repoRoot
+};

package/runtime/bin/appFrontend/ports.cjs

@@ -0,0 +1,36 @@
+const net = require("node:net");
+
+function canUsePort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+async function findAvailablePort(preferredPort) {
+  const preferred = Number(preferredPort);
+  if (Number.isInteger(preferred) && preferred > 0 && await canUsePort(preferred)) return preferred;
+  for (let attempt = 0; attempt < 60; attempt += 1) {
+    const port = 30000 + Math.floor(Math.random() * 20000);
+    if (await canUsePort(port)) return port;
+  }
+  throw new Error("Could not find an available frontend port");
+}
+
+async function selectFrontendPort(requestedPort, preferredPort) {
+  if (requestedPort === 0 || requestedPort === "0") return await findAvailablePort();
+  if (requestedPort !== undefined && requestedPort !== null && requestedPort !== "") {
+    const port = Number(requestedPort);
+    if (!Number.isInteger(port) || port <= 0) throw new Error(`Invalid frontend port "${requestedPort}"`);
+    return port;
+  }
+  return await findAvailablePort(preferredPort);
+}
+
+module.exports = {
+  findAvailablePort,
+  selectFrontendPort
+};

package/runtime/bin/appFrontend/processes.cjs

@@ -0,0 +1,127 @@
+const { spawn } = require("node:child_process");
+const { killChildTree } = require("../../scripts/killChildTree.cjs");
+const { buildMatterhornCommandEnv, redactCommandOutput } = require("./commandEnv.cjs");
+
+function quoteCmdArg(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:@=${}-]+$/.test(text)) return text;
+  return `"${text.replaceAll("\"", "\\\"")}"`;
+}
+
+function commandInvocation(command, args) {
+  if (process.platform === "win32" && ["npm", "npx", "npm.cmd", "npx.cmd", "pnpm", "pnpx", "pnpm.cmd", "pnpx.cmd"].includes(command)) {
+    const base = command.endsWith(".cmd") ? command : `${command}.cmd`;
+    return {
+      command: process.env.ComSpec || "cmd.exe",
+      args: ["/d", "/s", "/c", [base, ...args].map(quoteCmdArg).join(" ")]
+    };
+  }
+  return { command, args };
+}
+
+function replaceTokens(value, options) {
+  return String(value)
+    .replaceAll("${port}", String(options.port))
+    .replaceAll("${bundlePort}", String(options.bundlePort ?? options.port))
+    .replaceAll("${mountPath}", String(options.mountPath || "/"));
+}
+
+function commandSpec(command, name) {
+  if (!command || typeof command !== "object") throw new Error(`App frontend.${name} command is required`);
+  if (Array.isArray(command)) {
+    if (!command[0]) throw new Error(`App frontend.${name} command is empty`);
+    return { command: command[0], args: command.slice(1), env: {} };
+  }
+  for (const key of Object.keys(command)) {
+    if (key !== "command" && key !== "args" && key !== "env") {
+      throw new Error(`App frontend.${name}.${key} is not a supported command field`);
+    }
+  }
+  if (!command.command) throw new Error(`App frontend.${name}.command is required`);
+  if (command.args !== undefined && !Array.isArray(command.args)) throw new Error(`App frontend.${name}.args must be an array`);
+  if (command.env !== undefined && (!command.env || typeof command.env !== "object" || Array.isArray(command.env))) {
+    throw new Error(`App frontend.${name}.env must be an object`);
+  }
+  return {
+    command: command.command,
+    args: (command.args || []).map((arg) => String(arg)),
+    env: command.env || {}
+  };
+}
+
+function spawnCommand(spec, options) {
+  const rawArgs = spec.args.map((arg) => replaceTokens(arg, options));
+  const invocation = commandInvocation(spec.command, rawArgs);
+  const commandEnv = {
+    ...options.env,
+    ...Object.fromEntries(Object.entries(spec.env || {}).map(([key, value]) => [key, replaceTokens(value, options)]))
+  };
+  const child = spawn(invocation.command, invocation.args, {
+    cwd: options.cwd,
+    env: buildMatterhornCommandEnv({
+      trust: options.trust || "trusted-local-dev",
+      commandEnv,
+      port: options.port,
+      bundlePort: options.bundlePort ?? options.port,
+      mountPath: options.mountPath || "/",
+      unsafeInheritEnv: options.unsafeInheritEnv,
+      allowSensitiveCommandEnv: options.allowSensitiveCommandEnv
+    }),
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+    windowsHide: true
+  });
+
+  const logger = options.logger;
+  child.stdout.on("data", (chunk) => logger?.log?.(`${options.label} stdout: ${redactCommandOutput(chunk.toString("utf8").trimEnd())}`));
+  child.stderr.on("data", (chunk) => logger?.error?.(`${options.label} stderr: ${redactCommandOutput(chunk.toString("utf8").trimEnd())}`));
+  return child;
+}
+
+function runCommand(spec, options) {
+  const child = spawnCommand(spec, options);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`${options.label} timed out after ${options.timeoutMs}ms`));
+    }, options.timeoutMs);
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve();
+      else reject(new Error(`${options.label} exited ${code}`));
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
+function closeChildProcess(child) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      child.stdout?.destroy?.();
+      child.stderr?.destroy?.();
+      child.unref?.();
+      resolve();
+    }, 2000);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      child.stdout?.destroy?.();
+      child.stderr?.destroy?.();
+      child.unref?.();
+      resolve();
+    });
+    killChildTree(child);
+  });
+}
+
+module.exports = {
+  closeChildProcess,
+  commandInvocation,
+  commandSpec,
+  replaceTokens,
+  runCommand,
+  spawnCommand
+};

package/runtime/bin/appFrontend.cjs

@@ -0,0 +1,45 @@
+const { appBundleArtifact } = require("./appFrontend/artifacts.cjs");
+const { buildAppBundleFrontend, startBundleBuiltFrontend, startBuiltFrontend, startBundledBuiltFrontend } = require("./appFrontend/buildServers.cjs");
+const { startBundleDevFrontend, startBundledDevFrontend, startDevFrontend } = require("./appFrontend/devServers.cjs");
+const { startBundleStaticFrontend, startBundledStaticFrontend, startStaticFrontend, waitForHttpOk } = require("./appFrontend/httpServers.cjs");
+const { findAvailablePort } = require("./appFrontend/ports.cjs");
+const { parseServeMode } = require("./appFrontend/paths.cjs");
+
+async function startAppFrontend(appOrFrontend, options = {}) {
+  const frontend = appOrFrontend?.frontend ? { ...appOrFrontend.frontend, trust: appOrFrontend.trust } : appOrFrontend;
+  if (!frontend) throw new Error("App does not declare a frontend");
+  const mode = parseServeMode(options.mode);
+  if (frontend.bundle) {
+    if (mode === "built") return await startBundledBuiltFrontend(frontend, options);
+    return await startBundledDevFrontend(frontend, options);
+  }
+  if (mode === "built") return await startBuiltFrontend(frontend, options);
+  return await startDevFrontend(frontend, options);
+}
+
+async function startAppBundleFrontend(appOrFrontend, options = {}) {
+  const frontend = appOrFrontend?.frontend ? { ...appOrFrontend.frontend, trust: appOrFrontend.trust } : appOrFrontend;
+  if (!frontend?.bundle) throw new Error("App does not declare a bundled frontend");
+  const mode = parseServeMode(options.mode);
+  if (mode === "built") return await startBundleBuiltFrontend(frontend, options);
+  return await startBundleDevFrontend(frontend, options);
+}
+
+module.exports = {
+  appBundleArtifact,
+  buildAppBundleFrontend,
+  findAvailablePort,
+  parseServeMode,
+  startAppBundleFrontend,
+  startAppFrontend,
+  startBundleBuiltFrontend,
+  startBundleDevFrontend,
+  startBundleStaticFrontend,
+  startBuiltFrontend,
+  startBundledBuiltFrontend,
+  startBundledDevFrontend,
+  startBundledStaticFrontend,
+  startDevFrontend,
+  startStaticFrontend,
+  waitForHttpOk
+};