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

package/runtime/bin/matterhornAppLoader.cjs

@@ -0,0 +1,588 @@
+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 APP_REF_ALIASES = {
+  "@app.matterhorn.events": "@mh-gg/example-events",
+  "@app.matterhorn.kanban": "@mh-gg/example-kanban",
+  "@app.matterhorn.wiki": "@mh-gg/example-wiki",
+  "@app.matterhorn.polls": "@mh-gg/example-polls",
+  "@app.matterhorn.budget": "@mh-gg/example-budget",
+  "@app.matterhorn.crm": "@mh-gg/example-crm",
+  "@app.matterhorn.react": "@mh-gg/example-react",
+  "@app.matterhorn.svelte": "@mh-gg/example-svelte",
+  "@app.matterhorn.vue": "@mh-gg/example-vue",
+  "@app.matterhorn.lit": "@mh-gg/example-lit",
+  "@app.matterhorn.vanilla": "@mh-gg/example-vanilla"
+};
+
+function canonicalAppRef(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 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 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 {}
+  }
+  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");
+  if (!fs.existsSync(packageFile)) return undefined;
+  const manifest = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+  const matterhornEntry = typeof manifest.matterhorn === "string"
+    ? manifest.matterhorn
+    : manifest.matterhorn?.app;
+  return path.resolve(directory, matterhornEntry || manifest.main || "index.cjs");
+}
+
+function staticPackageEntryFile(directory) {
+  const packageFile = path.join(directory, "package.json");
+  const manifest = fs.existsSync(packageFile) ? JSON.parse(fs.readFileSync(packageFile, "utf8")) : {};
+  const matterhornEntry = typeof manifest.matterhorn === "object" && typeof manifest.matterhorn.bundle === "string"
+    ? path.resolve(directory, manifest.matterhorn.bundle)
+    : undefined;
+  if (matterhornEntry && fs.existsSync(matterhornEntry)) return matterhornEntry;
+  const direct = path.join(directory, "matterhorn.app.json");
+  if (fs.existsSync(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 bundleEntry = bundleEntryFile(resolved);
+  if (bundleEntry) return bundleEntry;
+  const packageEntry = packageEntryFile(resolved);
+  if (packageEntry && fs.existsSync(packageEntry)) return packageEntry;
+  const found = candidateEntryFiles(resolved).find((file) => fs.existsSync(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 (fs.existsSync(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);
+  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 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) {
+  const file = gitAppCacheMetadataFile(target);
+  if (!fs.existsSync(file)) return undefined;
+  return readJsonFile(file);
+}
+
+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 (!fs.existsSync(target)) {
+    fs.mkdirSync(cacheRoot, { recursive: true });
+    if (pinnedCommit) {
+      runGit(["clone", "--no-checkout", parsed.source, 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, parsed.source, target]
+        : ["clone", "--depth", "1", parsed.source, 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));
+  return {
+    ...app,
+    sourceEntry: loaded.source.entryFile,
+    sourceRoot: loaded.source.sourceRoot,
+    sourceKind: defineAppExport(loaded.exports) ? "defineApp" : (loaded.source.entryFile.endsWith(".json") ? "json" : "module"),
+    trust: appTrustForSource(loaded.source, options),
+    bundleFile: path.join(app.frontend?.root || loaded.source.sourceRoot, `${app.id}.json`)
+  };
+}
+
+function loadMatterhornDeployment(ref, options = {}) {
+  return normalizeMatterhornDeployment(ref, loadMatterhornApp(ref, options));
+}
+
+function emitMatterhornBundleForRef(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?.emitMatterhornBundle) throw new Error(`Matterhorn app ${ref} does not export a defineApp() result`);
+  return sdkApp.emitMatterhornBundle({
+    ...(options.bundleOptions || {}),
+    ...(options.outDir === undefined ? {} : { outDir: options.outDir })
+  });
+}
+
+module.exports = {
+  emitMatterhornBundleForRef,
+  loadMatterhornApp,
+  loadMatterhornDeployment,
+  normalizeMatterhornApp,
+  normalizeMatterhornDeployment,
+  resolveMatterhornAppEntry,
+  canonicalAppRef,
+  gitAppRefsAllowed,
+  appTrustForSource
+};