Skip to content

3D engine that AI agents drive

6.8 KB
Raw Blame
import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
import { isAbsolute, join, relative, resolve, sep } from 'node:path';
import { checkAddon, CORE_PACKAGE, entryOf } from '../bin/crucible-addon-check.mjs';

// Addons the person who starts the MCP server allows. Only startup options choose them (--addons, --allow-addon); no tool
// call can name one. Each is looked up in <folder>/node_modules/<name> and must pass the addon contract (docs/addons.md).

export const MAXIMUM_ADDON_BUNDLE_BYTES = 2 * 1024 * 1024;
export const MAXIMUM_ALLOWED_ADDONS = 16;
const PACKAGE_NAME = /^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/;

function isInside(folder, path) {
  const inside = relative(folder, path);
  // A name that merely starts with two dots, such as "..lib", is inside; only ".." as a whole part leaves the folder.
  return inside !== '' && inside !== '..' && !inside.startsWith(`..${sep}`) && !isAbsolute(inside);
}

// A broken package (a missing entry file, an unreadable folder) is skipped like any other failing addon: it never stops the server.
function loadOne(name, addonsFolder, version) {
  try {
    return loadOneChecked(name, addonsFolder, version);
  } catch (error) {
    return { reason: `${name} could not be read (${error.message}). Reinstall it with npm install ${name} in ${addonsFolder}.` };
  }
}

function loadOneChecked(name, addonsFolder, version) {
  if (!PACKAGE_NAME.test(name)) {
    return { reason: `"${name}" is not an npm package name. Pass the name as installed, such as my-addon or @scope/my-addon.` };
  }
  const packageFolder = join(addonsFolder, 'node_modules', ...name.split('/'));
  if (!existsSync(packageFolder)) {
    return { reason: `${name} is listed with --allow-addon but is not installed in ${join(addonsFolder, 'node_modules')}. Run npm install ${name} in ${addonsFolder}.` };
  }
  const realFolder = realpathSync(packageFolder);
  if (!isInside(addonsFolder, realFolder)) {
    return { reason: `${name} resolves to ${realFolder}, outside the addons folder ${addonsFolder}. Install the package inside that folder instead of linking it from elsewhere.` };
  }
  const { errors } = checkAddon(realFolder, { version });
  if (errors.length > 0) return { reason: `${name} fails the addon contract: ${errors.join(' ')}` };
  const pack = JSON.parse(readFileSync(join(realFolder, 'package.json'), 'utf8'));
  if (pack.name !== name) return { reason: `${name} has package name "${pack.name}" in its package.json. Install the package under its own name.` };
  if (pack['crucible'].bundleBytes > MAXIMUM_ADDON_BUNDLE_BYTES) {
    return { reason: `${name} declares bundleBytes ${pack['crucible'].bundleBytes}, above the server bound of ${MAXIMUM_ADDON_BUNDLE_BYTES} bytes (2 MiB). Ship a smaller entry file.` };
  }
  const entry = entryOf(pack);
  if (entry === null) return { reason: `${name} names no entry file. Set "exports" (or its "." import condition) or "main" to the ES module that exports registerAddon.` };
  const entryPath = resolve(realFolder, entry);
  if (!existsSync(entryPath)) return { reason: `${name} entry file ${entry} does not exist in the package. Rebuild or reinstall the addon.` };
  const realEntry = realpathSync(entryPath);
  if (!isInside(realFolder, realEntry)) return { reason: `${name} entry file resolves outside the package folder. Point main or exports inside the package.` };
  if (!/\.m?js$/.test(realEntry)) return { reason: `${name} entry file ${entry} must be an ES module ending in .js or .mjs.` };
  if (statSync(realEntry).size > MAXIMUM_ADDON_BUNDLE_BYTES) return { reason: `${name} entry file is above 2 MiB.` };
  return {
    addon: {
      name,
      version: pack.version ?? 'unknown',
      folder: realFolder,
      entry: relative(realFolder, realEntry).split(sep).join('/'),
      extensionPoints: [...pack['crucible'].extensionPoints],
    },
  };
}

/**
 * Resolve the allowlisted addons. Returns { addons, skipped } where each skipped item is { name, reason }. A missing or failing
 * addon is skipped and never stops the server. The folder must be an absolute path to an existing directory.
 */
export function resolveAddons({ folder, names = [], version }) {
  if (folder === undefined) {
    if (names.length > 0) throw new Error(`--allow-addon needs --addons <absolute folder> that holds node_modules. Add it, or remove ${names.map(name => `--allow-addon ${name}`).join(' ')}.`);
    return { addons: [], skipped: [] };
  }
  if (typeof folder !== 'string' || !isAbsolute(folder) || !existsSync(folder) || !statSync(folder).isDirectory()) {
    throw new Error('--addons must be an absolute path to an existing folder that holds node_modules.');
  }
  if (names.length > MAXIMUM_ALLOWED_ADDONS) throw new Error(`--allow-addon may be given at most ${MAXIMUM_ALLOWED_ADDONS} times.`);
  const addonsFolder = realpathSync(folder);
  const addons = [];
  const skipped = [];
  for (const name of [...new Set(names)]) {
    const { addon, reason } = loadOne(name, addonsFolder, version);
    if (addon) addons.push(addon);
    else skipped.push({ name, reason });
  }
  return { addons, skipped };
}

/** The file inside an allowlisted addon that a page request names, or null. Checks the real path on every call, so a link swapped in later fails. */
export function addonFileFor(addons, requestPath) {
  const match = /^\/addons\/(\d+)\/(.+)$/.exec(requestPath);
  const addon = match ? addons[Number(match[1])] : undefined;
  if (!addon) return null;
  let decoded;
  try {
    decoded = decodeURIComponent(match[2]);
  } catch {
    return null;
  }
  if (!/\.m?js$/.test(decoded) || decoded.includes('\0') || decoded.includes('\\')) return null;
  try {
    const real = realpathSync(resolve(addon.folder, decoded));
    return isInside(addon.folder, real) ? real : null;
  } catch {
    return null;
  }
}

/** The import map that points the host package specifiers at the page's own engine modules, so an addon shares them. */
export function addonImportMap(exportsField) {
  const imports = {};
  for (const [subpath, target] of Object.entries(exportsField)) {
    if (subpath !== '.' && !subpath.startsWith('./addons/')) continue;
    if (typeof target !== 'string' || !target.startsWith('./build/')) continue;
    imports[subpath === '.' ? CORE_PACKAGE : `${CORE_PACKAGE}/${subpath.slice(2)}`] = `/${target.slice('./build/'.length)}`;
  }
  return { imports };
}

export function addonCapabilities({ addons = [], skipped = [], registered = {}, refused = [] }) {
  return {
    configured: addons.length + skipped.length > 0,
    loaded: addons.map(addon => ({ name: addon.name, version: addon.version, extensionPoints: addon.extensionPoints, registered: registered[addon.name] ?? { controllers: [], cameraRigs: [] } })),
    skipped: [...skipped, ...refused],
    use: 'Set game.player.controller or game.camera to a registered kind name. Addons are chosen by whoever starts the server; no tool loads one.',
  };
}