@mh-gg/app-runtime 0.1.1-alpha.20260627T001620833Z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matterhorn contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @mh-gg/app-runtime
+
+Runtime helpers used by Matterhorn host and relay packages to load app descriptors and run frontend bundle commands.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mh-gg/app-runtime",
+  "version": "0.1.1-alpha.20260627T001620833Z",
+  "description": "Matterhorn app runtime helpers shared by host and relay runtime packages.",
+  "type": "commonjs",
+  "main": "runtime/matterhornAppLoader.cjs",
+  "exports": {
+    ".": "./runtime/matterhornAppLoader.cjs",
+    "./app-loader": "./runtime/matterhornAppLoader.cjs",
+    "./app-ref-policy": "./runtime/appRefPolicy.cjs",
+    "./frontend/artifacts": "./runtime/appFrontend/artifacts.cjs",
+    "./frontend/command-env": "./runtime/appFrontend/commandEnv.cjs",
+    "./frontend/command-policy": "./runtime/appFrontend/commandPolicy.cjs",
+    "./frontend/processes": "./runtime/appFrontend/processes.cjs",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@mh-gg/base": "^0.1.1-alpha.20260627T001620833Z",
+    "@mh-gg/base-plugins": "^0.1.1-alpha.20260627T001620833Z",
+    "@mh-gg/schema": "^0.1.1-alpha.20260627T001620833Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT",
+  "files": [
+    "runtime",
+    "scripts",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=60 --test-coverage-include=runtime/appFrontend/artifacts.cjs --test-coverage-include=runtime/appFrontend/commandEnv.cjs --test-coverage-include=runtime/appFrontend/commandPolicy.cjs --test-coverage-include=runtime/appFrontend/processes.cjs test/*.test.cjs"
+  }
+}

package/runtime/appFrontend/artifacts.cjs

@@ -0,0 +1,101 @@
+const fs = require("node:fs");
+const { createHash } = require("node:crypto");
+const path = require("node:path");
+const { hashCanonical, validateFrontendChunkManifest } = require("@mh-gg/base");
+const { bundleDistDir, bundleEntryFile, bundleEntryName, bundleManifestFile, bundleMountPath } = require("./paths.cjs");
+
+const DOCUMENT_ENTRYPOINT = "index.html";
+
+function fileIntegrity(filePath) {
+  return `sha256-${createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
+}
+
+function manifestFileIdentity(manifest) {
+  return {
+    kind: manifest.kind,
+    version: manifest.version,
+    entrypoint: manifest.entrypoint,
+    files: [...manifest.files]
+      .map((file) => ({
+        path: file.path,
+        type: file.type || "",
+        integrity: file.integrity,
+        byteLength: file.byteLength
+      }))
+      .sort((left, right) => left.path.localeCompare(right.path)),
+    ...(manifest.frontendChunks ? { frontendChunks: manifest.frontendChunks } : {})
+  };
+}
+
+function manifestBundleIdentity(manifest) {
+  return {
+    integrity: hashCanonical(manifestFileIdentity(manifest)),
+    byteLength: manifest.files.reduce((total, file) => total + file.byteLength, 0)
+  };
+}
+
+function readBundleManifest(frontend) {
+  const file = bundleManifestFile(frontend);
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error && (error.code === "ENOENT" || error.code === "ENOTDIR")) return undefined;
+    throw error;
+  }
+  if (manifest?.kind !== "matterhorn.frontend.manifest" || manifest.version !== 1) {
+    throw new Error(`Built app bundle manifest is invalid: ${file}`);
+  }
+  if (typeof manifest.entrypoint !== "string" || !manifest.entrypoint) {
+    throw new Error(`Built app bundle manifest is missing entrypoint: ${file}`);
+  }
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0) {
+    throw new Error(`Built app bundle manifest is missing files: ${file}`);
+  }
+  for (const item of manifest.files) {
+    if (!item || typeof item.path !== "string" || !item.path || path.isAbsolute(item.path) || item.path.includes("..")) {
+      throw new Error(`Built app bundle manifest has an unsafe file path: ${file}`);
+    }
+    if (typeof item.integrity !== "string" || !item.integrity.startsWith("sha256-")) {
+      throw new Error(`Built app bundle manifest has an invalid file integrity: ${item.path}`);
+    }
+    if (!Number.isInteger(item.byteLength) || item.byteLength < 0) {
+      throw new Error(`Built app bundle manifest has an invalid file size: ${item.path}`);
+    }
+  }
+  if (!manifest.files.some((item) => item.path === DOCUMENT_ENTRYPOINT)) {
+    throw new Error(`Built app bundle manifest is missing required ${DOCUMENT_ENTRYPOINT} document.`);
+  }
+  if (manifest.frontendChunks !== undefined) {
+    manifest.frontendChunks = validateFrontendChunkManifest(manifest.frontendChunks);
+  }
+  return { file, manifest };
+}
+
+function appBundleArtifact(frontend) {
+  const file = bundleEntryFile(frontend);
+  const stat = fs.statSync(file);
+  if (!stat.isFile()) throw new Error(`Built app bundle is missing ${file}`);
+  const bundleManifest = readBundleManifest(frontend);
+  const identity = bundleManifest ? manifestBundleIdentity(bundleManifest.manifest) : {
+    byteLength: stat.size,
+    integrity: fileIntegrity(file)
+  };
+  return {
+    file,
+    entry: bundleEntryName(frontend),
+    distDir: bundleDistDir(frontend),
+    mountPath: bundleMountPath(frontend),
+    byteLength: identity.byteLength,
+    integrity: identity.integrity,
+    ...(bundleManifest ? {
+      manifestFile: bundleManifest.file,
+      manifest: bundleManifest.manifest
+    } : {})
+  };
+}
+
+module.exports = {
+  appBundleArtifact,
+  manifestBundleIdentity
+};

package/runtime/appFrontend/commandEnv.cjs

@@ -0,0 +1,95 @@
+const MATTERHORN_PUBLIC_KEYS = new Set([
+  "MATTERHORN_APP_BUNDLE_MOUNT",
+  "MATTERHORN_APP_BUNDLE_TARGET",
+  "MATTERHORN_BUNDLE_BASE",
+  "MATTERHORN_BUNDLE_PORT",
+  "MATTERHORN_FRONTEND_PORT"
+]);
+const PRODUCTION_PROFILE = "production";
+
+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 matterhornProfile(input = {}) {
+  return String(input.matterhornProfile || process.env.MATTERHORN_PROFILE || "").toLowerCase();
+}
+
+function unsafeEnvMessage(source) {
+  return `MATTERHORN_UNSAFE_APP_FULL_ENV is disabled in production profile. Use explicit app command env allowlist entries instead of inheriting the full parent environment.${source ? ` Source: ${source}.` : ""}`;
+}
+
+function assertUnsafeEnvAllowed(input = {}) {
+  if (!canUnsafeInherit(input)) return;
+  if (matterhornProfile(input) !== PRODUCTION_PROFILE) return;
+  const source = input.unsafeInheritEnv === true ? "unsafeInheritEnv" : "MATTERHORN_UNSAFE_APP_FULL_ENV";
+  const message = unsafeEnvMessage(source);
+  input.logger?.warn?.(redactCommandOutput(message));
+  input.io?.warn?.(redactCommandOutput(message));
+  throw new Error(message);
+}
+
+function buildMatterhornCommandEnv(input = {}) {
+  const trust = input.trust || "untrusted-metadata";
+  const commandEnv = input.commandEnv || {};
+  validateCommandEnv(commandEnv, {
+    trust,
+    allowSensitiveCommandEnv: input.allowSensitiveCommandEnv
+  });
+  assertUnsafeEnvAllowed({ ...input, trust });
+  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 = {
+  assertUnsafeEnvAllowed,
+  buildMatterhornCommandEnv,
+  redactCommandOutput,
+  sensitiveEnvKey,
+  validateCommandEnv
+};

package/runtime/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/appFrontend/paths.cjs

@@ -0,0 +1,121 @@
+const path = require("node:path");
+const fs = require("node:fs");
+
+const DEFAULT_BUNDLE_MANIFEST = "matterhorn-frontend-manifest.json";
+
+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));
+}
+
+function bundleManifestName(frontend) {
+  return bundleConfig(frontend).manifest || DEFAULT_BUNDLE_MANIFEST;
+}
+
+function bundleManifestFile(frontend) {
+  const bundle = bundleConfig(frontend);
+  if (bundle.manifest) return path.resolve(frontendRoot(frontend), bundle.manifest);
+  const rootManifest = path.join(path.dirname(bundleDistDir(frontend)), DEFAULT_BUNDLE_MANIFEST);
+  const legacyDistManifest = path.join(bundleDistDir(frontend), DEFAULT_BUNDLE_MANIFEST);
+  if (fs.existsSync(rootManifest) || !fs.existsSync(legacyDistManifest)) return rootManifest;
+  return legacyDistManifest;
+}
+
+module.exports = {
+  bundleConfig,
+  bundleDistDir,
+  bundleEntryFile,
+  bundleEntryName,
+  bundleManifestFile,
+  bundleManifestName,
+  bundleMountPath,
+  bundleUrl,
+  ensureLeadingSlash,
+  ensureTrailingSlash,
+  frontendRoot,
+  frontendUrl,
+  launcherBuildCommand,
+  launcherDevCommand,
+  launcherDist,
+  parseServeMode,
+  repoRoot
+};

package/runtime/appFrontend/processes.cjs

@@ -0,0 +1,135 @@
+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" && key !== "envVars" && key !== "process.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`);
+  const env = {};
+  for (const key of ["env", "envVars", "process.env"]) {
+    const value = command[key];
+    if (value === undefined) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error(`App frontend.${name}.${key} must be an object`);
+    }
+    Object.assign(env, value);
+  }
+  return {
+    command: command.command,
+    args: (command.args || []).map((arg) => String(arg)),
+    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,
+      matterhornProfile: options.matterhornProfile,
+      logger: options.logger
+    }),
+    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/appRefPolicy.cjs

@@ -0,0 +1,29 @@
+const MATTERHORN_APP_REF_RE = /^@gg\.matterhorn\.[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/;
+
+function isMatterhornAliasRef(ref) {
+  return typeof ref === "string" && ref.startsWith("@") && ref.includes(".matterhorn.");
+}
+
+function isCanonicalMatterhornAppRef(ref) {
+  return MATTERHORN_APP_REF_RE.test(String(ref || ""));
+}
+
+function assertCanonicalMatterhornAppRef(ref) {
+  if (isCanonicalMatterhornAppRef(ref)) return ref;
+  throw new Error(`Matterhorn app alias ${ref || "(empty)"} is invalid. Use @gg.matterhorn.<app>, for example @gg.matterhorn.events.`);
+}
+
+function rejectInvalidMatterhornAliasRef(ref) {
+  if (isMatterhornAliasRef(ref) && !isCanonicalMatterhornAppRef(ref)) {
+    assertCanonicalMatterhornAppRef(ref);
+  }
+  return ref;
+}
+
+module.exports = {
+  MATTERHORN_APP_REF_RE,
+  assertCanonicalMatterhornAppRef,
+  isCanonicalMatterhornAppRef,
+  isMatterhornAliasRef,
+  rejectInvalidMatterhornAliasRef
+};

package/runtime/matterhornAppLoader.cjs

@@ -0,0 +1,702 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { createHash } = require("node:crypto");
+const { createRequire } = require("node:module");
+const { fileURLToPath } = require("node:url");
+const { verifySignedManifest } = require("@mh-gg/base");
+const { rejectInvalidMatterhornAliasRef } = require("./appRefPolicy.cjs");
+
+const APP_REF_ALIASES = {
+  "@gg.matterhorn.events": "@mh-gg/example-events",
+  "@gg.matterhorn.kanban": "@mh-gg/example-kanban",
+  "@gg.matterhorn.wiki": "@mh-gg/example-wiki",
+  "@gg.matterhorn.polls": "@mh-gg/example-polls",
+  "@gg.matterhorn.budget": "@mh-gg/example-budget",
+  "@gg.matterhorn.crm": "@mh-gg/example-crm",
+  "@gg.matterhorn.react": "@mh-gg/example-react",
+  "@gg.matterhorn.svelte": "@mh-gg/example-svelte",
+  "@gg.matterhorn.vue": "@mh-gg/example-vue",
+  "@gg.matterhorn.lit": "@mh-gg/example-lit",
+  "@gg.matterhorn.vanilla": "@mh-gg/example-vanilla"
+};
+
+function canonicalAppRef(ref) {
+  rejectInvalidMatterhornAliasRef(ref);
+  return APP_REF_ALIASES[ref] || ref;
+}
+
+function builtInExampleAppRef(ref) {
+  return Object.values(APP_REF_ALIASES).includes(ref) || String(ref).startsWith("@mh-gg/example-");
+}
+
+function matterhornProfile(options = {}) {
+  return String(options.matterhornProfile || process.env.MATTERHORN_PROFILE || process.env.NODE_ENV || "development").toLowerCase();
+}
+
+function isProductionProfile(options = {}) {
+  return matterhornProfile(options) === "production";
+}
+
+function isPinnedHashMatch(actualHash, pinnedHash) {
+  if (typeof pinnedHash !== "string" || pinnedHash.length === 0) return false;
+  return pinnedHash === actualHash || pinnedHash === `sha256-${actualHash}`;
+}
+
+function hasProductionSourcePin(app, source, trust, options = {}) {
+  if (options.trustedSource === true) return true;
+  if (isPinnedHashMatch(trust.contentHash, options.pinnedHash || options.appSourceHash)) return true;
+  if (source.pinnedCommit) return true;
+  if (trust.packageIntegrity || app.pack?.artifactSha256 || app.pack?.frontendArchiveSha256) return true;
+  return false;
+}
+
+function productionSourcePolicyMessage(app, trust) {
+  return `Production profile refuses unpinned app execution for ${app.id || "unknown app"}. Install from a pinned git commit, a package artifact with integrity, or pass an explicit pinnedHash/trustedSource policy for this app source.`;
+}
+
+function appDescriptorSignatureVerified(app) {
+  try {
+    return verifySignedManifest(app.appPack).ok;
+  } catch {
+    return false;
+  }
+}
+
+function appHasCommandDescriptor(app) {
+  return Boolean(app?.frontend?.bundle?.build
+    || app?.frontend?.bundle?.dev
+    || app?.frontend?.dev
+    || app?.deployment?.launch?.command
+    || app?.launch?.command);
+}
+
+function assertProductionAppSourcePolicy(app, source, trust, options = {}) {
+  if (!isProductionProfile(options)) return;
+  if (builtInExampleAppRef(source.ref)) {
+    throw new Error("Built-in Matterhorn example apps are development/test fixtures and cannot run under the production profile. Use a pinned production app source instead.");
+  }
+  if (trust.codeExecution === "local-dev" || source.unsafeDevMode) {
+    throw new Error("Production profile refuses local development app JavaScript descriptors. Use --profile development for local app code, or install from a pinned production app source.");
+  }
+  if (trust.commandExecution === "trusted-local-dev" && appHasCommandDescriptor(app)) {
+    throw new Error("Production profile refuses local development app command descriptors. Use --profile development for local app commands, or install from a pinned production app source.");
+  }
+  if (trust.metadataMode === "executed-js" && options.trustedSource !== true && !trust.packageIntegrity && !source.pinnedCommit) {
+    throw new Error("Production profile refuses remote JavaScript app descriptors without an explicit trustedSource policy, package integrity, or pinned git commit.");
+  }
+  if (!hasProductionSourcePin(app, source, trust, options)) {
+    throw new Error(productionSourcePolicyMessage(app, trust));
+  }
+  if (!appDescriptorSignatureVerified(app)) {
+    throw new Error("Production profile refuses unsigned alpha app descriptors. Sign the app descriptor before production use.");
+  }
+}
+
+function looksLikeLocalRef(ref) {
+  return ref === "."
+    || ref === ".."
+    || ref.startsWith("./")
+    || ref.startsWith("../")
+    || ref.startsWith(".\\")
+    || ref.startsWith("..\\")
+    || ref.startsWith("/")
+    || ref.startsWith("\\")
+    || /^[A-Za-z]:[\\/]/.test(ref);
+}
+
+function fileRefPath(ref) {
+  if (ref.startsWith("file:")) return ref.slice("file:".length);
+  return ref;
+}
+
+function candidateEntryFiles(directory) {
+  return [
+    path.join(directory, "matterhorn.app.json"),
+    path.join(directory, "matterhorn.app.cjs"),
+    path.join(directory, "matterhorn.app.js"),
+    path.join(directory, "index.cjs"),
+    path.join(directory, "index.js")
+  ];
+}
+
+function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function readJsonFileIfPresent(filePath) {
+  try {
+    return readJsonFile(filePath);
+  } catch (error) {
+    if (error && (error.code === "ENOENT" || error.code === "ENOTDIR")) return undefined;
+    throw error;
+  }
+}
+
+function fileExists(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch (error) {
+    if (error && (error.code === "ENOENT" || error.code === "ENOTDIR")) return false;
+    throw error;
+  }
+}
+
+function directoryExists(filePath) {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch (error) {
+    if (error && (error.code === "ENOENT" || error.code === "ENOTDIR")) return false;
+    throw error;
+  }
+}
+
+function bundleEntryFile(directory) {
+  const candidates = fs.readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => path.join(directory, entry.name));
+  const bundles = [];
+  for (const file of candidates) {
+    try {
+      const value = readJsonFile(file);
+      if (value?.kind === "matterhorn.app-bundle" && value.appPack) bundles.push(file);
+    } catch (matterhornIgnoredError) {
+      globalThis.__matterhornIgnoredError?.(matterhornIgnoredError, "bin/matterhornAppLoader.cjs");
+    }
+  }
+  if (bundles.length > 1) throw new Error(`Local Matterhorn app ${directory} exposes multiple app bundle files: ${bundles.map((file) => path.basename(file)).join(", ")}`);
+  return bundles[0];
+}
+
+function packageEntryFile(directory) {
+  const packageFile = path.join(directory, "package.json");
+  const manifest = readJsonFileIfPresent(packageFile);
+  if (!manifest) return undefined;
+  const matterhornEntry = typeof manifest.matterhorn === "string"
+    ? manifest.matterhorn
+    : manifest.matterhorn?.app;
+  const sdkEntry = typeof manifest["matterhorn-sdk"] === "object" ? manifest["matterhorn-sdk"].app : undefined;
+  return path.resolve(directory, matterhornEntry || sdkEntry || manifest.main || "index.cjs");
+}
+
+function packagePrefersSourceEntry(directory) {
+  const manifest = readJsonFileIfPresent(path.join(directory, "package.json"));
+  return typeof manifest?.["matterhorn-sdk"]?.app === "string";
+}
+
+function staticPackageEntryFile(directory) {
+  const packageFile = path.join(directory, "package.json");
+  const manifest = readJsonFileIfPresent(packageFile) || {};
+  const matterhornEntry = typeof manifest.matterhorn === "object" && typeof manifest.matterhorn.bundle === "string"
+    ? path.resolve(directory, manifest.matterhorn.bundle)
+    : undefined;
+  if (matterhornEntry && fileExists(matterhornEntry)) return matterhornEntry;
+  const direct = path.join(directory, "matterhorn.app.json");
+  if (fileExists(direct)) return direct;
+  return bundleEntryFile(directory);
+}
+
+function localEntryFile(localPath) {
+  const resolved = path.resolve(localPath);
+  const stat = fs.statSync(resolved);
+  if (stat.isFile()) return resolved;
+  const packageEntry = packageEntryFile(resolved);
+  if (packagePrefersSourceEntry(resolved) && packageEntry && fileExists(packageEntry)) return packageEntry;
+  const bundleEntry = bundleEntryFile(resolved);
+  if (bundleEntry) return bundleEntry;
+  if (packageEntry && fileExists(packageEntry)) return packageEntry;
+  const found = candidateEntryFiles(resolved).find((file) => fileExists(file));
+  if (found) return found;
+  throw new Error(`Local Matterhorn app ${localPath} does not expose matterhorn.app.json, matterhorn.app.cjs, index.cjs, or package.json`);
+}
+
+function nearestPackageRoot(filePath) {
+  let current = fs.statSync(filePath).isDirectory() ? filePath : path.dirname(filePath);
+  while (true) {
+    if (fileExists(path.join(current, "package.json"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.dirname(filePath);
+    current = parent;
+  }
+}
+
+function gitAppRefsAllowed(options = {}) {
+  return options.allowGitAppRefs === true || process.env.MATTERHORN_ALLOW_GIT_APP_REFS === "1";
+}
+
+function trustedAppCodeAllowed(options = {}) {
+  return options.allowTrustedAppCode === true
+    || options.trustedAppCode === true;
+}
+
+function localAppCodeTrusted(options = {}) {
+  return options.localAppCodeTrusted !== false;
+}
+
+function contentHash(filePath) {
+  return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function sourceIdentity(source) {
+  return `${source.sourceKind}:${source.ref}:${source.sourceRoot}:${source.entryFile}`;
+}
+
+function matchingTrustRecord(source, options = {}) {
+  const record = options.trustRecord;
+  if (!record || typeof record !== "object") return false;
+  return record.sourceIdentity === sourceIdentity(source)
+    && record.contentHash === contentHash(source.entryFile)
+    && record.codeExecution === "trusted-installed";
+}
+
+function appTrustForSource(source, options = {}) {
+  const metadataMode = source.entryFile.endsWith(".json") ? "static-json" : "executed-js";
+  let codeExecution = "none";
+  let commandExecution = "none";
+  if (metadataMode === "executed-js") {
+    if (source.directLocal) {
+      codeExecution = "local-dev";
+      commandExecution = "trusted-local-dev";
+    } else if (matchingTrustRecord(source, options) || trustedAppCodeAllowed(options)) {
+      codeExecution = "trusted-installed";
+      commandExecution = "allowlisted";
+    }
+  } else if (source.directLocal) {
+    commandExecution = "trusted-local-dev";
+  } else if (builtInExampleAppRef(source.ref)) {
+    commandExecution = "trusted-local-dev";
+  }
+  return {
+    sourceKind: source.sourceKind,
+    metadataMode,
+    codeExecution,
+    commandExecution,
+    sourceIdentity: sourceIdentity(source),
+    contentHash: contentHash(source.entryFile),
+    ...(source.packageIntegrity ? { packageIntegrity: source.packageIntegrity } : {}),
+    ...(source.pinnedCommit ? { pinnedCommit: source.pinnedCommit } : {}),
+    ...(source.unsafeDevMode ? { unsafeDevMode: true } : {})
+  };
+}
+
+function resolveMatterhornAppEntry(ref, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const loadRef = canonicalAppRef(ref);
+  if (loadRef.startsWith("git+")) {
+    if (!gitAppRefsAllowed(options)) {
+      throw new Error("Git app refs are disabled by default. Clone the app locally or pass allowGitAppRefs: true for trusted sources.");
+    }
+    const sourceRoot = gitAppCachePath(loadRef, options);
+    const gitMetadata = readGitAppCacheMetadata(sourceRoot) || {};
+    const parsedGit = parseGitAppRef(loadRef);
+    const gitSource = {
+      sourceKind: "git",
+      pinnedCommit: gitMetadata.unsafeDevRef ? undefined : gitMetadata.commit,
+      unsafeDevMode: gitMetadata.unsafeDevRef === true,
+      sourceRef: parsedGit.source
+    };
+    const staticEntry = staticPackageEntryFile(sourceRoot);
+    if (staticEntry) return { ref: loadRef, entryFile: staticEntry, sourceRoot, directLocal: false, ...gitSource };
+    const jsSource = { ref: loadRef, entryFile: localEntryFile(sourceRoot), sourceRoot, directLocal: false, ...gitSource };
+    if (!trustedAppCodeAllowed(options) && !matchingTrustRecord(jsSource, options)) {
+      throw new Error("Git app refs can only load static JSON app bundles by default. Set allowTrustedAppCode: true only for trusted local development.");
+    }
+    return jsSource;
+  }
+
+  if (loadRef.startsWith("file:") || looksLikeLocalRef(loadRef)) {
+    const sourcePath = path.resolve(cwd, fileRefPath(loadRef));
+    const entryFile = localEntryFile(sourcePath);
+    const sourceRoot = fs.statSync(sourcePath).isDirectory() ? sourcePath : nearestPackageRoot(sourcePath);
+    const directLocal = localAppCodeTrusted(options);
+    const sourceKind = fs.statSync(sourcePath).isDirectory() ? "local-directory" : "local-file";
+    const source = { ref: loadRef, entryFile, sourceRoot, directLocal, sourceKind };
+    if (!entryFile.endsWith(".json") && !directLocal && !trustedAppCodeAllowed(options) && !matchingTrustRecord(source, options)) {
+      throw new Error("Downloaded app packages can only load static JSON app bundles by default. Set allowTrustedAppCode: true only for trusted package code.");
+    }
+    return source;
+  }
+
+  const sourceRoot = resolvePackageRoot(loadRef, cwd);
+  if (builtInExampleAppRef(loadRef)) {
+    const entryFile = packageEntryFile(sourceRoot);
+    if (entryFile && fileExists(entryFile)) return { ref: loadRef, entryFile, sourceRoot, directLocal: true, sourceKind: "package" };
+  }
+  const staticEntry = staticPackageEntryFile(sourceRoot);
+  if (staticEntry) return { ref: loadRef, entryFile: staticEntry, sourceRoot, directLocal: false, sourceKind: "package" };
+  const entryFile = resolvePackageEntryFile(loadRef, cwd);
+  const source = { ref: loadRef, entryFile, sourceRoot: nearestPackageRoot(entryFile), directLocal: false, sourceKind: "package" };
+  if (!trustedAppCodeAllowed(options) && !matchingTrustRecord(source, options)) {
+    throw new Error(`Package app ref ${loadRef} can only load static JSON app bundles by default. Set allowTrustedAppCode: true only for trusted local development.`);
+  }
+  return source;
+}
+
+function resolvePackageRoot(ref, cwd) {
+  const entryFile = resolvePackageEntryFile(ref, cwd);
+  return nearestPackageRoot(entryFile);
+}
+
+function resolvePackageEntryFile(ref, cwd) {
+  const requireFromCwd = createRequire(path.join(cwd, "matterhorn-app-loader.cjs"));
+  try {
+    return requireFromCwd.resolve(ref);
+  } catch (cwdError) {
+    try {
+      return require.resolve(ref);
+    } catch {
+      throw cwdError;
+    }
+  }
+}
+
+function moduleExportsForEntry(entryFile) {
+  if (entryFile.endsWith(".json")) return readJsonFile(entryFile);
+  delete require.cache[require.resolve(entryFile)];
+  return require(entryFile);
+}
+
+let basePluginRegistry;
+
+function schemaApi() {
+  return require("@mh-gg/schema");
+}
+
+function configuredBasePluginRegistry() {
+  if (!basePluginRegistry) {
+    const { createMicroPluginRegistry } = schemaApi();
+    const { registryRecords } = require("@mh-gg/base-plugins/composer/registry");
+    basePluginRegistry = createMicroPluginRegistry(registryRecords());
+  }
+  return basePluginRegistry;
+}
+
+function schemaModelHostPlugin(app, plugin) {
+  const { createSchemaDefinedHostPlugin } = schemaApi();
+  const { hashCanonical } = require("@mh-gg/base");
+  const composition = plugin.composition || {
+    kind: "matterhorn.app-composition.schema",
+    schemaVersion: 1,
+    app: {
+      id: app.id,
+      version: app.version || app.appPack?.version || "0.1.0",
+      name: app.name
+    },
+    primaryPlugin: {
+      id: plugin.id,
+      version: plugin.version || app.version || app.appPack?.version || "0.1.0",
+      model: plugin.model
+    },
+    plugins: plugin.plugins || [],
+    actions: plugin.actions || [],
+    views: plugin.views || [],
+    routes: plugin.routes || []
+  };
+  const hostPlugin = createSchemaDefinedHostPlugin(composition);
+  hostPlugin.stateSchemaHash = hostPlugin.stateSchemaHash || hashCanonical(hostPlugin.stateSchemaDescriptor || hostPlugin.schemas?.state?.descriptor || {});
+  hostPlugin.operationSchemaHash = hostPlugin.operationSchemaHash || hashCanonical(hostPlugin.operationSchemaDescriptor || {});
+  return hostPlugin;
+}
+
+function hydrateJsonHostPlugin(plugin, app) {
+  if (plugin?.kind === "matterhorn.schema-model-host-plugin") return schemaModelHostPlugin(app, plugin);
+  if (plugin?.kind === "matterhorn.registry-host-plugin") return registryHostPlugin(app, plugin);
+  throw new Error("JSON Matterhorn app manifests can only declare schema-model-host-plugin or registry-host-plugin entries; app reducer modules are not loadable from schema manifests");
+}
+
+function registryHostPlugin(app, plugin) {
+  const { resolveCompositionHostPluginEntries } = schemaApi();
+  const composition = app.appPack?.composition || app.compositionSchema;
+  const entries = resolveCompositionHostPluginEntries(composition, configuredBasePluginRegistry());
+  const entry = entries.find((candidate) => candidate.schema.key === plugin.key || candidate.plugin.id === plugin.id);
+  if (!entry) throw new Error(`JSON Matterhorn app bundle references unknown registry plugin ${plugin.key || plugin.id}`);
+  if (plugin.config === undefined) return entry.plugin;
+  return { ...entry.plugin, config: plugin.config };
+}
+
+function normalizeJsonAppPaths(app, source) {
+  if (!source.entryFile.endsWith(".json") && app?.kind !== "matterhorn.app-bundle") return app;
+  const manifestDir = path.dirname(source.entryFile);
+  const frontend = app.frontend ? { ...app.frontend } : undefined;
+  if (frontend) frontend.root = path.resolve(manifestDir, frontend.root || ".");
+  return {
+    ...app,
+    ...(frontend ? { frontend } : {}),
+    hostPlugins: Array.isArray(app.hostPlugins)
+      ? app.hostPlugins.map((plugin) => hydrateJsonHostPlugin(plugin, app))
+      : app.hostPlugins
+  };
+}
+
+function moduleExportsForRef(ref, options = {}) {
+  const source = resolveMatterhornAppEntry(ref, options);
+  if (!source.entryFile.endsWith(".json") && !source.directLocal && !trustedAppCodeAllowed(options) && !matchingTrustRecord(source, options)) {
+    throw new Error("Only direct local file app refs may execute app JavaScript by default. Use static JSON app bundles for package/git refs.");
+  }
+  return {
+    exports: moduleExportsForEntry(source.entryFile),
+    source
+  };
+}
+
+function gitCacheRoot(options = {}) {
+  return options.cacheDir || process.env.MATTERHORN_APP_CACHE_DIR || path.join(os.tmpdir(), "matterhorn-apps");
+}
+
+const GIT_COMMIT_RE = /^[0-9a-f]{40}$/i;
+
+function parseGitAppRef(ref) {
+  const raw = ref.slice("git+".length);
+  const fragmentIndex = raw.lastIndexOf("#");
+  if (fragmentIndex === -1) return { source: raw, refish: "" };
+  return {
+    source: raw.slice(0, fragmentIndex),
+    refish: raw.slice(fragmentIndex + 1)
+  };
+}
+
+function gitCloneSourceArgs(source) {
+  if (!source.startsWith("file:")) return [source];
+  return ["--local", fileURLToPath(source)];
+}
+
+function unsafeGitAppRefsAllowed(options = {}) {
+  return options.allowUnsafeGitAppRef === true || process.env.MATTERHORN_UNSAFE_GIT_APP_REF === "1";
+}
+
+function gitAppCacheMetadataFile(target) {
+  return path.join(target, ".git", "matterhorn-app-cache.json");
+}
+
+function readGitAppCacheMetadata(target) {
+  return readJsonFileIfPresent(gitAppCacheMetadataFile(target));
+}
+
+function writeGitAppCacheMetadata(target, metadata) {
+  fs.writeFileSync(gitAppCacheMetadataFile(target), `${JSON.stringify(metadata, null, 2)}\n`);
+}
+
+function gitHeadCommit(target) {
+  return runGit(["-C", target, "rev-parse", "HEAD"], process.cwd()).toLowerCase();
+}
+
+function gitWorkingTreeStatus(target) {
+  return runGit(["-C", target, "status", "--porcelain", "--untracked-files=all"], process.cwd());
+}
+
+function verifyGitAppCache(target, expectedCommit) {
+  const metadata = readGitAppCacheMetadata(target);
+  const actualCommit = gitHeadCommit(target);
+  const normalizedCommit = expectedCommit.toLowerCase();
+  if (metadata?.commit !== normalizedCommit || actualCommit !== normalizedCommit) {
+    throw new Error(`Git app cache ${target} is not at the pinned commit ${normalizedCommit}; remove the cache and load again`);
+  }
+  const status = gitWorkingTreeStatus(target);
+  if (status.length > 0) {
+    throw new Error(`Git app cache ${target} has local modifications; refusing to execute a tampered checkout`);
+  }
+}
+
+function warnUnsafeGitAppRef(ref, options = {}) {
+  const message = `WARNING: ${ref} is an unsafe dev git app ref. Pin git app refs to a commit SHA for deterministic loading.`;
+  if (typeof options.io?.warn === "function") options.io.warn(message);
+  else if (typeof options.warn === "function") options.warn(message);
+}
+
+function gitAppCachePath(ref, options = {}) {
+  const parsed = parseGitAppRef(ref);
+  const pinnedCommit = parsed.refish && GIT_COMMIT_RE.test(parsed.refish)
+    ? parsed.refish.toLowerCase()
+    : "";
+  if (!pinnedCommit && !unsafeGitAppRefsAllowed(options)) {
+    throw new Error("Git app refs must pin a 40-character commit SHA. Set allowUnsafeGitAppRef: true only for local development branch refs.");
+  }
+  const cacheRoot = gitCacheRoot(options);
+  const cacheIdentity = pinnedCommit ? `${parsed.source}#${pinnedCommit}` : `unsafe:${ref}`;
+  const cacheKey = createHash("sha256").update(cacheIdentity).digest("hex").slice(0, 24);
+  const target = path.join(cacheRoot, cacheKey);
+  if (!directoryExists(target)) {
+    fs.mkdirSync(cacheRoot, { recursive: true });
+    const cloneSourceArgs = gitCloneSourceArgs(parsed.source);
+    if (pinnedCommit) {
+      runGit(["clone", "--no-checkout", ...cloneSourceArgs, target], process.cwd());
+      runGit(["-C", target, "checkout", "--detach", pinnedCommit], process.cwd());
+    } else {
+      warnUnsafeGitAppRef(ref, options);
+      const args = parsed.refish
+        ? ["clone", "--depth", "1", "--branch", parsed.refish, ...cloneSourceArgs, target]
+        : ["clone", "--depth", "1", ...cloneSourceArgs, target];
+      runGit(args, process.cwd());
+    }
+    writeGitAppCacheMetadata(target, {
+      schemaVersion: 1,
+      ref,
+      source: parsed.source,
+      commit: gitHeadCommit(target),
+      unsafeDevRef: pinnedCommit ? false : true
+    });
+  }
+  const metadata = readGitAppCacheMetadata(target);
+  const expectedCommit = pinnedCommit || metadata?.commit;
+  if (!expectedCommit) {
+    throw new Error(`Git app cache ${target} does not record the resolved commit; remove the cache and load again`);
+  }
+  verifyGitAppCache(target, expectedCommit);
+  return target;
+}
+
+function runGit(args, cwd) {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true
+  });
+  if (result.error) throw new Error(`Git app ref load failed: ${result.error.message}`);
+  if (result.status === 0) return (result.stdout || "").trim();
+  const message = (result.stderr || result.stdout || "").trim();
+  throw new Error(`Git app ref load failed: ${message || `git ${args.join(" ")} exited ${result.status}`}`);
+}
+
+function defineAppExport(exports) {
+  if (exports?.toMatterhornBundle) return exports;
+  if (exports?.default?.toMatterhornBundle) return exports.default;
+  return undefined;
+}
+
+function appDescriptorFromExports(exports) {
+  const sdkApp = defineAppExport(exports);
+  if (sdkApp) return sdkApp.toMatterhornBundle();
+  return exports?.matterhornApp || exports?.default || exports;
+}
+
+function normalizeMatterhornApp(ref, exports) {
+  const app = appDescriptorFromExports(exports);
+  if (!app || typeof app !== "object" || Array.isArray(app)) {
+    throw new Error(`Matterhorn app ${ref} did not export an app descriptor`);
+  }
+  if (!app.id || !app.name) throw new Error(`Matterhorn app ${ref} must export id and name`);
+  if (!app.appPack) throw new Error(`Matterhorn app ${ref} must export appPack`);
+  return {
+    ...app,
+    ref
+  };
+}
+
+function appHostRunner(app) {
+  return app.host?.runner || app.deployment?.host?.runner || "matterhorn-example-host";
+}
+
+function normalizeLaunch(ref, launch) {
+  if (launch === undefined) return undefined;
+  if (!launch || typeof launch !== "object" || Array.isArray(launch)) {
+    throw new Error(`Matterhorn deployment ${ref} launch must be an object`);
+  }
+  if (typeof launch.command !== "string" || launch.command.length === 0) {
+    throw new Error(`Matterhorn deployment ${ref} launch.command is required`);
+  }
+  if (launch.args !== undefined && !Array.isArray(launch.args)) {
+    throw new Error(`Matterhorn deployment ${ref} launch.args must be an array`);
+  }
+  return {
+    command: launch.command,
+    args: (launch.args || []).map((arg) => String(arg))
+  };
+}
+
+function normalizeMatterhornDeployment(ref, app) {
+  if (!app || typeof app !== "object" || Array.isArray(app)) {
+    throw new Error(`Matterhorn deployment ${ref} requires an app descriptor`);
+  }
+  if (!app.id || !app.name) throw new Error(`Matterhorn deployment ${ref} must include id and name`);
+  if (!app.appPack) throw new Error(`Matterhorn deployment ${ref} must include appPack`);
+  if (!app.hostPack) throw new Error(`Matterhorn deployment ${ref} must include hostPack`);
+  if (!Array.isArray(app.hostPlugins) || app.hostPlugins.length === 0) {
+    throw new Error(`Matterhorn deployment ${ref} must include at least one host plugin`);
+  }
+  if (!Array.isArray(app.playerPacks) || app.playerPacks.length === 0) {
+    throw new Error(`Matterhorn deployment ${ref} must include at least one player pack`);
+  }
+
+  const declared = app.deployment && typeof app.deployment === "object" && !Array.isArray(app.deployment)
+    ? app.deployment
+    : {};
+  if (declared.kind !== undefined && declared.kind !== "matterhorn.self-contained-app") {
+    throw new Error(`Matterhorn deployment ${ref} kind must be matterhorn.self-contained-app`);
+  }
+  return {
+    kind: "matterhorn.self-contained-app",
+    id: app.id,
+    name: app.name,
+    version: app.version || app.appPack.version,
+    ref: app.ref || ref,
+    appPack: app.appPack,
+    hostPack: app.hostPack,
+    hostPlugins: app.hostPlugins,
+    playerPacks: app.playerPacks,
+    frontend: app.frontend,
+    host: {
+      runner: appHostRunner(app),
+      ...(declared.host || {})
+    },
+    relay: {
+      mode: "embedded",
+      autoStart: true,
+      acceptsPeerRelays: true,
+      ...(declared.relay || {})
+    },
+    frontendDelivery: {
+      mode: app.frontend?.bundle ? "relay-chunks" : "external",
+      ...(declared.frontendDelivery || declared.frontend || {})
+    },
+    launch: normalizeLaunch(ref, declared.launch),
+    trust: app.trust
+  };
+}
+
+function loadMatterhornApp(ref, options = {}) {
+  if (!ref || typeof ref !== "string") throw new Error("Matterhorn app ref is required");
+  const loaded = moduleExportsForRef(ref, options);
+  const descriptor = appDescriptorFromExports(loaded.exports);
+  const app = normalizeMatterhornApp(ref, normalizeJsonAppPaths(descriptor, loaded.source));
+  const trust = appTrustForSource(loaded.source, options);
+  assertProductionAppSourcePolicy(app, loaded.source, trust, options);
+  return {
+    ...app,
+    sourceEntry: loaded.source.entryFile,
+    sourceRoot: loaded.source.sourceRoot,
+    sourceKind: defineAppExport(loaded.exports) ? "defineApp" : (loaded.source.entryFile.endsWith(".json") ? "json" : "module"),
+    trust,
+    bundleFile: path.join(app.frontend?.root || loaded.source.sourceRoot, `${app.id}.json`)
+  };
+}
+
+function loadMatterhornDeployment(ref, options = {}) {
+  return normalizeMatterhornDeployment(ref, loadMatterhornApp(ref, options));
+}
+
+function emitAppForRef(ref, options = {}) {
+  if (!ref || typeof ref !== "string") throw new Error("Matterhorn app ref is required");
+  const source = resolveMatterhornAppEntry(ref, options);
+  const exports = moduleExportsForEntry(source.entryFile);
+  const sdkApp = defineAppExport(exports);
+  if (!sdkApp?.emit) throw new Error(`Matterhorn app ${ref} does not export a defineApp() result`);
+  return sdkApp.emit({
+    ...(options.bundleOptions || {}),
+    ...(options.outDir === undefined ? {} : { outDir: options.outDir })
+  });
+}
+
+module.exports = {
+  emitAppForRef,
+  loadMatterhornApp,
+  loadMatterhornDeployment,
+  normalizeMatterhornApp,
+  normalizeMatterhornDeployment,
+  resolveMatterhornAppEntry,
+  canonicalAppRef,
+  gitAppRefsAllowed,
+  appTrustForSource,
+  assertProductionAppSourcePolicy
+};

package/scripts/killChildTree.cjs

@@ -0,0 +1,18 @@
+const { spawn } = require("node:child_process");
+
+function killChildTree(child) {
+  if (!child?.pid) return;
+  if (process.platform === "win32") {
+    child.kill();
+    const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+      stdio: "ignore",
+      windowsHide: true
+    });
+    killer.unref();
+    return;
+  }
+  child.kill("SIGTERM");
+  setTimeout(() => child.kill("SIGKILL"), 1000).unref();
+}
+
+module.exports = { killChildTree };