Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

29.2 KB
Raw Blame
/**
 * Plugin loading: WHICH plugins a deployment runs is CONFIGURATION, not capability
 * baked into the platform.
 *
 * The configuration is per PROJECT (the `[plugins]` table in `.project_config.toml`), because machines
 * are lent to Projects and that is what says which machines a plugin has to reach. Loading
 * is per PROCESS, though — there is one module tree — so what a deployment runs is the
 * CLOSURE: the union over its Projects. A plugin any Project asks for is in the tree, and
 * what it contributes is visible to all of them.
 *
 * The closure is read from the FILES, without the database: this runs at boot, before the
 * platform exists, and a Project is a directory holding a `.project_config.toml`.
 *
 * Resolution is anchored at `process.argv[1]`, for the same reason the packaged
 * bundle's own resolver is: a bundle running from `hmr/store` has no node_modules of
 * its own, so anchoring at the bundle would find nothing.
 *
 * Failure is per-entry and non-fatal: an unresolvable or malformed plugin is reported
 * and skipped, leaving its capability unavailable rather than failing the boot. A
 * plugin is a set of modules (core plugin/index.ts): decorated classes, named by the
 * default export, whose manifests the package's generated `ifaces.json` carries.
 */
import fs from "node:fs/promises";
import type { Dirent } from "node:fs";
import { parse as parseToml } from "smol-toml";
import { effectivePluginTable, parsePluginTables, projectConfigPath } from "@adelie/core";
import { findPackageJSON } from "node:module";
import { existsSync, readFileSync, statSync } from "node:fs";
import path from "node:path";
import { pathToFileURL } from "node:url";
import type {
  IfaceTable,
  ManifestTable,
  ModuleClass,
  ModuleDef,
  Resources,
} from "@adelie/core/kernel";
import { moduleDefOf, parseManifest } from "@adelie/core/kernel";
import { unpackedAssetsDir } from "../hmr/asset-archives.js";
import { readManifest } from "../hmr/manifest.js";
import type { Plugin } from "@adelie/core/plugin";
import type { LoadedPlugin } from "./host.js";
import { PluginHost, pluginHostFrom } from "./host.js";
import platformTable from "../ifaces.json" with { type: "json" };
import { checkIfaces, ifaceQuestions } from "./iface-check.js";
import { loadTypeScript, TypeScriptUnavailable, type TypeScript } from "./typescript.js";

/**
 * Where a Project's list lives, for a surface that has to name the file. The data root's
 * old `plugins.json` is NOT read any more: the list moved into Project config, deliberately
 * without a migration (PRFC-0010), so a deployment that had one starts with no plugins
 * until each Project asks again.
 */
export const PLUGINS_FILE = ".project_config.toml";

export type { LoadedPlugin } from "./host.js";

export interface PluginLoadResult {
  loaded: LoadedPlugin[];
  /** specifier → why it was skipped. */
  failed: Map<string, string>;
}
/** The Project ids of a data root: every directory holding a `.project_config.toml`. */
export async function listProjectIds(root: string): Promise<string[]> {
  let entries: Dirent[];
  try {
    entries = await fs.readdir(root, { withFileTypes: true });
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
    throw err;
  }
  const ids: string[] = [];
  for (const entry of entries) {
    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
    try {
      await fs.access(projectConfigPath(root, entry.name));
      ids.push(entry.name);
    } catch {
      // Not a Project directory: `hmr`, `store`, whatever else lives beside them.
    }
  }
  return ids.sort();
}

/**
 * What one Project asks `machineId` to run, in the order it wrote them; empty when it asks
 * for none. `machineId` is the machine's own id — this server's, for what it loads itself —
 * and null reads the shared table alone.
 */
export async function readProjectPluginList(
  root: string,
  projectId: string,
  machineId: string | null = null,
): Promise<string[]> {
  let text: string;
  try {
    text = await fs.readFile(projectConfigPath(root, projectId), "utf8");
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
    // A Project whose config cannot be read (permissions, a directory in its place) is a
    // configuration fault, but not this one's to fail the boot over: its models are just as
    // unreadable, and the deployment must still come up for every other Project. The list
    // view reports the fault on that Project (routes/plugins-installed.ts).
    console.warn(
      `[plugins] ${projectId}: .project_config.toml could not be read, its plugins are skipped: ${err instanceof Error ? err.message : String(err)}`,
    );
    return [];
  }
  let parsed: unknown;
  try {
    parsed = parseToml(text);
  } catch (err) {
    // The same for one that does not parse.
    console.warn(
      `[plugins] ${projectId}: .project_config.toml is not valid TOML, its plugins are skipped: ${err instanceof Error ? err.message : String(err)}`,
    );
    return [];
  }
  const tables = parsePluginTables((parsed as { plugins?: unknown }).plugins);
  return tables === undefined ? [] : Object.keys(effectivePluginTable(tables, machineId));
}

/**
 * The closure a machine runs: the union over this root's Projects of what each asks THAT
 * machine for, first-asked order. One process, one module tree — so with this server's own
 * id it is what `loadPlugins` loads, whoever asked for it; a plugin every Project lists only
 * for other machines is neither loaded nor installed here.
 */
export async function readPluginClosure(
  root: string,
  machineId: string | null = null,
): Promise<string[]> {
  const out: string[] = [];
  for (const projectId of await listProjectIds(root)) {
    for (const specifier of await readProjectPluginList(root, projectId, machineId)) {
      if (!out.includes(specifier)) out.push(specifier);
    }
  }
  return out;
}

/**
 * Where plugins are looked for, in order. Each is an npm prefix (`<dir>/package.json` +
 * `<dir>/node_modules/…`) except the installation entry, which resolves as the running
 * program does:
 *
 *   1. `<root>/plugins` — the data root's own npm prefix, for a package put there by hand
 *      (nothing in the product writes it yet; a registry install would).
 *   2. `<assets>/plugins` — the BUILTIN plugins the committed hot push carried
 *      (scripts/build-plugins.mjs), i.e. the plugins of the revision that is running.
 *   3. `<installation>/plugins` — the builtin plugins the build shipped (the desktop app
 *      stages them beside `skills/`), for a deployment nothing was ever pushed to.
 *   4. the installation entry — a plugin installed globally beside the program.
 *
 * A prefix marked `builtin` is one the harness ships, not one the operator installed.
 */
export interface PluginBase {
  file: string;
  builtin: boolean;
  /**
   * The running program's entry rather than an npm prefix: a specifier resolves from it the
   * way the program's own imports do, `node_modules` upward. A prefix answers only for what
   * is under its OWN `node_modules` — the walk upward would otherwise find a package beside
   * the program from the builtin prefix and label it built in.
   */
  program?: true;
}

/** A bare package name, scoped or not — never a subpath, a path, a URL or a version range. */
export const PACKAGE_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;

/** Why a specifier cannot name a plugin, or null when it is a package name or a path. */
export function specifierFault(specifier: string): string | null {
  if (path.isAbsolute(specifier) || PACKAGE_NAME.test(specifier)) return null;
  return `'${specifier}' is not a package name: a plugin is named by its package, never by a subpath, a URL or a version range`;
}

/** `<root>/plugins`: the npm prefix of the data root itself. */
export function pluginsPrefix(root: string): string {
  return path.join(root, "plugins");
}

export function pluginBases(root: string | undefined, assetsDir: string | null): PluginBase[] {
  const bases: PluginBase[] = [];
  if (root !== undefined && root !== "") {
    bases.push({ file: path.join(pluginsPrefix(root), "package.json"), builtin: false });
  }
  if (assetsDir !== null) {
    // A push carries the prefix as archives; they are unpacked before anything resolves.
    bases.push({
      file: path.join(unpackedAssetsDir(assetsDir), "plugins", "package.json"),
      builtin: true,
    });
  }
  const entry = process.argv[1];
  if (typeof entry === "string" && entry.length > 0) {
    bases.push({
      file: path.join(path.dirname(entry), "..", "plugins", "package.json"),
      builtin: true,
    });
    bases.push({ file: entry, builtin: false, program: true });
  }
  return bases;
}

/** The assets directory of the committed version, read from harness.json without a host. */
export async function committedAssetsDir(root: string): Promise<string | null> {
  const manifest = await readManifest(root);
  const dir = manifest?.assets?.dir;
  return typeof dir === "string" ? path.join(root, "hmr", dir) : null;
}

/**
 * The package a bare specifier names, looked up from a base the way Node looks up any
 * package (`node_modules` upward from the base): its directory, its manifest, and the base
 * that found it — or null. Nothing about the package is assumed: it is whatever npm put there.
 */
export function resolvePluginPackage(
  specifier: string,
  bases: readonly PluginBase[],
): { dir: string; manifest: string; base: PluginBase } | null {
  // A path names a file, not a package: the nearest package.json above it is the
  // package (a dev checkout's plugin, written beside its manifest). As a URL, so that a
  // Windows drive letter is not read as a URL scheme.
  const lookup = path.isAbsolute(specifier) ? pathToFileURL(specifier).href : specifier;
  for (const base of bases) {
    let manifest: string | undefined;
    try {
      manifest = findPackageJSON(lookup, base.file);
    } catch {
      manifest = undefined;
    }
    if (manifest === undefined) continue;
    // findPackageJSON walks `node_modules` upward from the base; a prefix speaks only for
    // its own (see PluginBase.program).
    if (base.program !== true) {
      const own = path.join(path.dirname(base.file), "node_modules") + path.sep;
      if (!manifest.startsWith(own)) continue;
    }
    return { dir: path.dirname(manifest), manifest, base };
  }
  return null;
}

/**
 * The file an `import "<name>"` of the package would load: `exports["."]` — a string, or its
 * `import` / `node` / `default` condition — else `main` (with `.js` supplied when it is
 * written without one), else `index.js`. The packages are ESM and name one entry, which is
 * all this reads; anything richer is the package's own business once Node imports it.
 */
function packageEntry(dir: string, manifest: string): string | null {
  let pkg: { exports?: unknown; main?: unknown };
  try {
    pkg = JSON.parse(readFileSync(manifest, "utf8")) as typeof pkg;
  } catch {
    return null;
  }
  const condition = (value: unknown): string | null => {
    if (typeof value === "string") return value;
    if (value === null || typeof value !== "object") return null;
    const v = value as Record<string, unknown>;
    return condition(v.import) ?? condition(v.node) ?? condition(v.default) ?? null;
  };
  let rel: string | null = null;
  const exp = pkg.exports;
  if (typeof exp === "string") rel = exp;
  else if (exp !== null && typeof exp === "object") {
    const table = exp as Record<string, unknown>;
    rel = condition("." in table ? table["."] : table);
  }
  rel ??= typeof pkg.main === "string" ? pkg.main : "./index.js";
  const file = path.resolve(dir, rel);
  if (!existsSync(file) && path.extname(file) === "" && existsSync(`${file}.js`)) {
    return `${file}.js`;
  }
  return file;
}

/** Where a specifier resolves from — the entry file and the base that found it — or null. */
function resolvePlugin(
  specifier: string,
  bases: readonly PluginBase[],
): { file: string; base: PluginBase } | null {
  // A path IS the entry: what the operator named is the file to import, whatever the
  // package above it declares (the dev-checkout path).
  if (path.isAbsolute(specifier)) {
    return existsSync(specifier)
      ? { file: specifier, base: { file: specifier, builtin: false } }
      : null;
  }
  // A subpath would resolve to the PACKAGE (findPackageJSON finds its manifest) and load its
  // root entry — the wrong module, silently. Refused up front, by name.
  if (!PACKAGE_NAME.test(specifier)) return null;
  const found = resolvePluginPackage(specifier, bases);
  if (found === null) return null;
  const file = packageEntry(found.dir, found.manifest);
  return file === null ? null : { file, base: found.base };
}

/**
 * The plugins a set of bases SHIPS: every package under a builtin prefix's node_modules
 * (scoped or not) whose package.json declares `penguin`. Being shipped means installing one
 * needs no download — it does not mean it is installed. Nothing here loads; the list is what
 * marks a catalogue row as available offline and lets an install skip npm.
 */
export async function discoverBuiltinPlugins(bases: readonly PluginBase[]): Promise<string[]> {
  const names: string[] = [];
  for (const base of bases) {
    if (!base.builtin) continue;
    // The prefix's own manifest names what the build shipped; what npm installed beside
    // them (their dependencies) is not offered.
    let manifest: { dependencies?: unknown };
    try {
      manifest = JSON.parse(await fs.readFile(base.file, "utf8")) as { dependencies?: unknown };
    } catch {
      continue;
    }
    const deps = manifest.dependencies;
    if (typeof deps !== "object" || deps === null) continue;
    for (const name of Object.keys(deps)) if (!names.includes(name)) names.push(name);
  }
  return names.sort();
}

/**
 * The entry file's modification time, the part of its identity a path alone misses: a
 * package updated in place keeps its path, and Node's module cache would keep serving the
 * code it loaded first. Null when the file cannot be stat'ed (the import then says why).
 */
function entryStamp(file: string): number | null {
  try {
    return statSync(file).mtimeMs;
  } catch {
    return null;
  }
}

/**
 * Resolved against the data root and the installation, never the bundle's location. The
 * import URL carries the entry's stamp, so a file rewritten in place is evaluated again
 * rather than answered from the module cache. (Only the entry: what it imports by relative
 * path stays cached, which a bundled plugin — one file — does not notice.)
 */
async function importPlugin(
  specifier: string,
  bases: readonly PluginBase[],
): Promise<{ module: unknown; file: string | null; stamp: number | null }> {
  const resolved = resolvePlugin(specifier, bases);
  if (resolved !== null) {
    if (!existsSync(resolved.file)) {
      throw new Error(`the package's entry file does not exist: ${resolved.file}`);
    }
    const stamp = entryStamp(resolved.file);
    const url = pathToFileURL(resolved.file).href + (stamp === null ? "" : `?v=${stamp}`);
    return { module: await import(url), file: resolved.file, stamp };
  }
  return { module: await import(specifier), file: null, stamp: null };
}

/** The generated table a plugin package ships beside its package.json. */
export const IFACES_FILE = "ifaces.json";

/** The `plugin` entry of a package's table: the names its default export lists, read statically by the generator. */
export interface PluginDeclaration {
  modules: readonly string[];
  replaces: readonly string[];
}

/**
/**
 * What a listed specifier DECLARES, read from its generated table alone — the package is never
 * imported. Lets a surface say which plugin a loaded module came from, and why a listed one is
 * not there, without the runtime having to publish its load report.
 */
export async function readPluginDeclaration(
  specifier: string,
  bases: readonly PluginBase[],
): Promise<{ modules: string[]; replaces: string[]; builtin: boolean } | { error: string }> {
  const fault = specifierFault(specifier);
  if (fault !== null) return { error: fault };
  const resolved = resolvePlugin(specifier, bases);
  if (resolved === null) {
    return {
      error: `'${specifier}' is not installed on this machine (nothing under <root>/plugins, the shipped plugins or the installation resolves it)`,
    };
  }
  if (!existsSync(resolved.file)) {
    return { error: `the package's entry file does not exist: ${resolved.file}` };
  }
  let read: Awaited<ReturnType<typeof readPackageTable>>;
  try {
    read = await readPackageTable(resolved.file);
  } catch (err) {
    return { error: err instanceof Error ? err.message : String(err) };
  }
  if (read === null) return { error: `no package.json above ${resolved.file}` };
  return {
    modules: [...read.plugin.modules],
    replaces: [...read.plugin.replaces],
    builtin: resolved.base.builtin,
  };
}

/**
 * The package's generated table (`ifaces.json` beside its `package.json`, the nearest one
 * above the resolved entry file): the manifest of every decorated class, the signature of
 * every interface they name. A package is a plugin by being listed; the table is its
 * MODULE payload, and a package without one ships no modules (`manifests` empty). Null
 * only when no `package.json` is above the file at all.
 */
async function readPackageTable(file: string | null): Promise<{
  where: string;
  ifaces: IfaceTable;
  manifests: ManifestTable;
  /** What the default export names, as the generator read it: the modules added and the nodes stood in for. */
  plugin: PluginDeclaration;
} | null> {
  if (file === null) return null;
  let dir = path.dirname(file);
  for (;;) {
    const where = path.join(dir, "package.json");
    try {
      await fs.access(where);
      const tableFile = path.join(dir, IFACES_FILE);
      let text: string;
      try {
        text = await fs.readFile(tableFile, "utf8");
      } catch (err) {
        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
        return {
          where,
          ifaces: { ifaces: {}, types: {} },
          manifests: {},
          plugin: { modules: [], replaces: [] },
        };
      }
      const table = JSON.parse(text) as {
        ifaces?: unknown;
        types?: unknown;
        modules?: unknown;
        plugin?: unknown;
      };
      const isRecord = (v: unknown) => typeof v === "object" && v !== null && !Array.isArray(v);
      if (!isRecord(table.ifaces) || !isRecord(table.types) || !isRecord(table.modules)) {
        throw new Error(`${tableFile}: expected { ifaces, types, modules } (gen-ifaces output)`);
      }
      const names = (v: unknown) => Array.isArray(v) && v.every((n) => typeof n === "string");
      const plugin = (table.plugin ?? {}) as { modules?: unknown; replaces?: unknown };
      if (!isRecord(plugin) || !names(plugin.modules ?? []) || !names(plugin.replaces ?? [])) {
        throw new Error(
          `${tableFile}#plugin: expected { modules: [<name>, …], replaces: [<name>, …] }`,
        );
      }
      const manifests: Record<string, ModuleDef["manifest"]> = {};
      for (const [name, doc] of Object.entries(table.modules as Record<string, unknown>)) {
        manifests[name] = parseManifest(doc, `${tableFile}#modules.${name}`);
      }
      return {
        where,
        ifaces: { ifaces: table.ifaces, types: table.types } as IfaceTable,
        manifests,
        plugin: {
          modules: (plugin.modules ?? []) as string[],
          replaces: (plugin.replaces ?? []) as string[],
        },
      };
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
    }
    const parent = path.dirname(dir);
    if (parent === dir) return null;
    dir = parent;
  }
}

/**
 * Whether the host interfaces this package compiled against — its own table copies them —
 * still fit this platform's, both for what its modules require and for what they provide.
 * The tree check cannot say: it looks a key up in one merged table, where the host's entry
 * stands, so it would compare the platform's declaration with itself.
 *
 * Two things can leave an interface uncompared, and neither fails the load — a pushed
 * platform must not take plugins away from a machine for something the plugin did not do:
 * a table that carries no copy of a host interface (the generator only writes the
 * interfaces a package DECLARES, so today that is every host interface a plugin requires),
 * and an installation whose program predates the compiler being a dependency. Both are
 * logged; an interface the table does carry, and that no longer fits, fails the load.
 */
let compilerMissingLogged = false;
async function interfaceMisfits(
  specifier: string,
  own: IfaceTable,
  defs: readonly ModuleDef[],
  assets: string | null,
): Promise<string[]> {
  const questions = ifaceQuestions(defs.map((d) => d.manifest));
  if (questions.length === 0) return [];
  let ts: TypeScript;
  try {
    ts = await loadTypeScript(assets);
  } catch (err) {
    if (!(err instanceof TypeScriptUnavailable)) throw err;
    if (!compilerMissingLogged) console.warn(`[plugins] interfaces not compared: ${err.message}`);
    compilerMissingLogged = true;
    return [];
  }
  const fit = checkIfaces(ts, platformTable as unknown as IfaceTable, own, questions);
  if (fit.uncompared.length > 0) {
    console.warn(
      `[plugins] ${specifier}: ${fit.uncompared.length} interface(s) not compared — its table carries no copy of them`,
    );
  }
  return fit.problems;
}

/** The package's default export as a Plugin, or null when it is not one. */
function asPlugin(module: unknown): Plugin | null {
  const def = (module as { default?: unknown }).default;
  const d = def as { modules?: unknown; replaces?: unknown } | null;
  const classes = (v: unknown) => Array.isArray(v) && v.every((m) => typeof m === "function");
  if (d === null || typeof d !== "object") return null;
  if (d.modules === undefined && d.replaces === undefined) return null;
  if (
    (d.modules !== undefined && !classes(d.modules)) ||
    (d.replaces !== undefined && !classes(d.replaces))
  )
    return null;
  return def as Plugin;
}

/**
 * Loads every configured plugin.
 *
 * Every failure is per entry, collected and skipped: an unresolvable specifier, a missing
 * table, a throw at import — that capability is unavailable, which a deployment can recover
 * from, and the reason is kept on the host for the list view. A Project whose config cannot
 * be read or parsed contributes nothing (readProjectPluginList): the deployment comes up for
 * every other Project, and that one's list view reports the fault.
 */
export async function loadPlugins(
  root: string,
  /**
   * The assets of the version being booted, or undefined to read the COMMITTED one.
   *
   * The distinction is the difference between loading this push's plugins and the previous
   * one's. A hot upgrade materializes its assets and publishes them BEFORE the new platform's
   * create() runs, but commits `harness.json` only after that boot succeeds — so a create()
   * that reads the committed pointer is reading the version it is replacing, and every push
   * would ship plugins one version stale. Seen exactly that way: a corrected plugin arrived
   * on a machine and the previous build's copy kept running until the NEXT push.
   */
  assetsDir?: string | null,
  /**
   * Entries an earlier App already imported, by specifier. Reused when the specifier still
   * resolves to the FILE that entry came from, unchanged since — the objects then keep their
   * identity across a swap, which is what the plugin host is parked for. A different file
   * (a push moves the builtin plugins to a new assets directory) or a file rewritten in
   * place (a package updated under `<root>/plugins`) means different code, and that is imported.
   */
  reuse: ReadonlyMap<string, LoadedPlugin> = new Map(),
  /** This server's own machine id, which selects its `[plugins.<id>]` tables; null reads the shared tables alone. */
  machineId: string | null = null,
): Promise<PluginLoadResult> {
  const failed = new Map<string, string>();
  const pushedAssets = assetsDir === undefined ? await committedAssetsDir(root) : assetsDir;
  const bases = pluginBases(root, pushedAssets);
  // The closure over this root's Projects, and nothing else. A plugin the BUILD ships is
  // available without a download — that is what `builtin` means — but availability is not
  // consent: it loads when a Project asks for it, like every other plugin.
  const specifiers = await readPluginClosure(root, machineId);
  const loaded: LoadedPlugin[] = [];
  for (const specifier of specifiers) {
    // Reused only when the SAME FILE is behind the name. A push writes the builtin plugins to
    // a new assets directory, so keeping an entry by specifier alone would run the previous
    // build's plugin code forever — the push would land everywhere except the plugins.
    const fault = specifierFault(specifier);
    if (fault !== null) {
      failed.set(specifier, fault);
      continue;
    }
    const held = reuse.get(specifier);
    const heldFile = held?.file;
    if (
      held !== undefined &&
      heldFile != null &&
      heldFile === resolvePlugin(specifier, bases)?.file &&
      held.stamp === entryStamp(heldFile)
    ) {
      loaded.push(held);
      continue;
    }
    try {
      const { module, file, stamp } = await importPlugin(specifier, bases);
      const read = await readPackageTable(file);
      if (read === null) {
        failed.set(specifier, `no package.json above ${file}`);
        continue;
      }
      const plugin = asPlugin(module);
      if (plugin === null) {
        failed.set(
          specifier,
          "the default export is not a Plugin ({ modules?: [<@Component or @Module class>, …], replaces?: [<class>, …] })",
        );
        continue;
      }
      const named = (plugin.modules?.length ?? 0) + (plugin.replaces?.length ?? 0);
      if (named > 0 && Object.keys(read.manifests).length === 0) {
        // Classes named, no table: the package was not built (gen-ifaces runs in its build).
        throw new Error(
          `the default export names module classes, but ${path.join(path.dirname(read.where), IFACES_FILE)} is missing — build the package`,
        );
      }
      // Each class is checked against its generated manifest here (a stale table is a
      // named error); the manifest is checked against the tree at boot.
      const seen = new Set<string>();
      const pair = (classes: readonly ModuleClass[] | undefined): ModuleDef[] =>
        (classes ?? []).map((cls) => {
          const def = moduleDefOf(cls, { manifests: read.manifests });
          if (seen.has(def.manifest.name)) {
            throw new Error(`the default export lists '${def.manifest.name}' twice`);
          }
          seen.add(def.manifest.name);
          return def;
        });
      const modules = pair(plugin.modules);
      const replaces = pair(plugin.replaces);
      const misfits = await interfaceMisfits(
        specifier,
        read.ifaces,
        [...modules, ...replaces],
        pushedAssets,
      );
      if (misfits.length > 0) throw new Error(misfits.join("\n"));
      loaded.push({ specifier, file, stamp, modules, replaces, ifaces: read.ifaces });
    } catch (err) {
      failed.set(specifier, err instanceof Error ? err.message : String(err));
    }
  }
  return { loaded, failed };
}

/**
 * The plugin host THIS App runs — built by the PLATFORM, at its own boot (hmr/platform.ts).
 *
 * This is the point of the whole file living below the seam: which plugins a deployment runs
 * is configuration, and how that configuration is read is policy. Both therefore travel by
 * push. A machine whose program predates a new rule — the Project closure replacing the data
 * root's plugins.json, say — learns it from the pushed platform, instead of being unable to
 * act on a list it has already been given until someone restarts it.
 *
 * What the registry keeps is the imported objects, claimed here and handed back at the
 * commit: state, not a capability. An entry the closure no longer asks for is simply not in
 * the new host; its modules leave the tree with the App that had them.
 */
export async function loadPluginHost(
  resources: Resources,
  root: string,
  /** The booting version's assets (hmr.assetsDir()), not the committed ones — see loadPlugins. */
  assetsDir?: string | null,
  /** This server's own machine id (see loadPlugins). */
  machineId: string | null = null,
): Promise<PluginHost> {
  const inherited = pluginHostFrom(resources);
  // An older generation's host may predate `entries()`; then nothing is reused and every
  // specifier is imported again, which the ESM cache makes cheap.
  const reuse =
    typeof inherited.entries === "function" ? inherited.entries() : new Map<string, LoadedPlugin>();
  const result = await loadPlugins(root, assetsDir, reuse, machineId);
  const host = new PluginHost();
  for (const entry of result.loaded) {
    // A module name clash is a LOAD failure, isolated per entry like an import failure.
    try {
      host.use(entry);
    } catch (err) {
      result.failed.set(entry.specifier, err instanceof Error ? err.message : String(err));
    }
  }
  // The reason stays on the host, not only in the log: the installed-plugins page reads it
  // there, so a plugin that failed to load is shown with why rather than as a restart that
  // would not help.
  for (const [specifier, reason] of result.failed) {
    host.skip(specifier, reason);
    console.warn(`[plugins] skipped ${specifier}: ${reason}`);
  }
  return host;
}