Skip to content

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

18.4 KB
Raw Blame
/**
 * Behavior tests for plugin loading: plugins are CONFIGURATION read from the data
 * root, resolved against the installation, and every failure is per-entry and
 * non-fatal — the capability a plugin would have provided stays unavailable rather
 * than the boot failing.
 */
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdtemp, readFile, rm, writeFile, mkdir } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import ts from "typescript";
import {
  IFACES_FILE,
  PLUGINS_FILE,
  committedAssetsDir,
  discoverBuiltinPlugins,
  loadPlugins,
  pluginBases,
  readPluginClosure,
  readProjectPluginList,
  listProjectIds,
} from "../src/plugin/loader.js";
import { writeClassPackage } from "./plugin-fixtures.js";

let root: string;

beforeEach(async () => {
  root = await mkdtemp(path.join(tmpdir(), "penguin-plugins-"));
});
afterEach(async () => {
  await rm(root, { recursive: true, force: true });
});

/** A Project asking for these plugins: its `[plugins]` table is what the closure is read from. */
async function writeConfig(value: { plugins?: string[] }, projectId = "p1"): Promise<void> {
  const rows = (value.plugins ?? []).map((s) => `${JSON.stringify(s)} = "*"`);
  await writeProject(projectId, `models = []\n[plugins]\n${rows.join("\n")}\n`);
}

/** Raw config text, for the malformed cases. */
async function writeProject(projectId: string, text: string): Promise<void> {
  await mkdir(path.join(root, projectId), { recursive: true });
  await writeFile(path.join(root, projectId, PLUGINS_FILE), text, "utf8");
}

/** A plugin module on disk, imported by absolute specifier (the dev-checkout path). */
async function writePluginModule(name: string, body: string): Promise<string> {
  const dir = path.join(root, "mods");
  await mkdir(dir, { recursive: true });
  const file = path.join(dir, `${name}.mjs`);
  await writeFile(file, body, "utf8");
  return file;
}

/**
 * The decorators, as a plugin's bundle would carry them — here imported from this
 * checkout's built SDK by file URL, since a package under a temp dir resolves nothing.
 */
const decorators = new URL("../../core/dist/plugin/index.js", import.meta.url).href;

/** Plugin source as a plugin author writes it, lowered the way its build would lower it. */
function lower(source: string): string {
  return ts.transpileModule(source, {
    compilerOptions: { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext },
  }).outputText;
}

describe("plugin list", () => {
  it("no Project means no plugins — the default deployment shape, not an error", async () => {
    expect(await readPluginClosure(root)).toEqual([]);
    expect(await loadPlugins(root)).toEqual({ loaded: [], failed: new Map() });
  });

  it("reads the configured specifiers in order", async () => {
    await writeConfig({ plugins: ["a", "b"] });
    expect(await readProjectPluginList(root, "p1")).toEqual(["a", "b"]);
    expect(await readPluginClosure(root)).toEqual(["a", "b"]);
  });

  it("the closure is the union over Projects, each specifier once", async () => {
    // Loading is per process — one module tree — so what a deployment runs is what any of
    // its Projects asked for, and a plugin two Projects both want is still one entry.
    await writeConfig({ plugins: ["a", "shared"] }, "p1");
    await writeConfig({ plugins: ["shared", "b"] }, "p2");
    expect(await listProjectIds(root)).toEqual(["p1", "p2"]);
    expect(await readPluginClosure(root)).toEqual(["a", "shared", "b"]);
  });

  it("a directory that is not a Project is not read as one", async () => {
    await mkdir(path.join(root, "hmr"), { recursive: true });
    await writeConfig({ plugins: ["a"] }, "p1");
    expect(await listProjectIds(root)).toEqual(["p1"]);
  });

  it("a Project whose config will not parse is skipped, not fatal for the rest", async () => {
    // Its models are just as unreadable; the deployment still has to come up for everyone else.
    await writeProject("broken", "[plugins]\nx = [oops\n");
    await writeConfig({ plugins: ["a"] }, "p1");
    expect(await readProjectPluginList(root, "broken")).toEqual([]);
    expect(await readPluginClosure(root)).toEqual(["a"]);
  });

  it("a config that exists but cannot be read is skipped like one that will not parse", async () => {
    // A directory in its place stands in for every non-ENOENT read failure (EACCES,
    // EPERM, EISDIR, an I/O fault). It is that Project's fault to report (its list view
    // does), not a reason to keep every other Project's deployment from coming up.
    await writeProject("p2", 'models = []\n[plugins]\n"@acme/two" = "*"\n');
    await mkdir(path.join(root, "p1", PLUGINS_FILE), { recursive: true });
    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
    try {
      await expect(readProjectPluginList(root, "p1")).resolves.toEqual([]);
      expect(await readPluginClosure(root)).toEqual(["@acme/two"]);
      expect(warn).toHaveBeenCalledWith(expect.stringMatching(/p1: .*could not be read/));
    } finally {
      warn.mockRestore();
    }
  });

  it("entries that are not requirements are dropped, not fatal", async () => {
    // Leniency on purpose: a typo in this table must not take the Project's models with it.
    await writeProject(
      "p1",
      'models = []\n[plugins]\nok = "*"\npinned = "1.2.3"\ntabled = { version = "2" }\nbad = 7\nworse = { version = 3 }\n',
    );
    expect(await readProjectPluginList(root, "p1")).toEqual(["ok", "pinned", "tabled"]);
  });

  it("a machine runs the shared table plus its own, and no other machine's", async () => {
    // Keyed by the machine's own id, never an alias: a plugin listed for one machine is not
    // in any other machine's closure, so it is neither loaded nor installed there.
    await writeProject(
      "p1",
      'models = []\n[plugins]\nshared = "*"\n\n[plugins.Mine000000000000]\nmine = "*"\n\n[plugins.Other00000000000]\nother = "*"\n',
    );
    expect(await readProjectPluginList(root, "p1", "Mine000000000000")).toEqual(["shared", "mine"]);
    expect(await readPluginClosure(root, "Other00000000000")).toEqual(["shared", "other"]);
    // A machine whose id is not known reads the shared table alone.
    expect(await readPluginClosure(root)).toEqual(["shared"]);
  });

  it("the list form this key once had is not read: such a Project asks for none", async () => {
    // Deliberately no compatibility (PRFC-0010): a table replaced the list before release,
    // and a file still carrying the list starts with no plugins until it is written again.
    await writeProject("p1", 'plugins = ["@acme/old"]\nmodels = []\n');
    expect(await readProjectPluginList(root, "p1")).toEqual([]);
  });
});

describe("plugin loading", () => {
  /** The table the plugin's build would generate: one component, contributing one provider. */
  const oneModule = {
    ifaces: {
      "@acme/penguin-plugin-thing#Thing": { name: "Thing", methods: {}, slots: {} },
    },
    types: {},
    modules: {
      Thing: {
        name: "Thing",
        requires: {},
        provides: { Thing: "@acme/penguin-plugin-thing#Thing" },
        contributes: {
          "SandboxModule.providers": [
            { id: "thing.provider", name: "thing", dimensions: ["fs-write"] },
          ],
        },
        children: [],
      },
    },
  };
  const thingClass = `
    import { Bind, Component } from ${JSON.stringify(decorators)};
    @Component({ contributes: { "SandboxModule.providers": [{ id: "thing.provider", name: "thing", dimensions: ["fs-write"] }] } })
    export class Thing {
      @Bind("thing.provider") provider!: unknown;
      setup() { this.provider = { confine() { throw new Error("no"); } }; }
    }`;

  /**
   * A package on disk: its package.json, the generated table beside it, and an index.mjs
   * default export (`null` table = a package that ships no modules, or was never built).
   */
  async function writePackage(name: string, table: unknown | null, index: string): Promise<string> {
    const dir = path.join(root, "node_modules", ...name.split("/"));
    await mkdir(dir, { recursive: true });
    await writeFile(
      path.join(dir, "package.json"),
      JSON.stringify({ name, main: "./index.mjs" }),
      "utf8",
    );
    if (table !== null) await writeFile(path.join(dir, IFACES_FILE), JSON.stringify(table), "utf8");
    await writeFile(path.join(dir, "index.mjs"), lower(index), "utf8");
    return path.join(dir, "index.mjs");
  }

  it("boots the classes the default export names, each against its manifest in the package's table", async () => {
    const file = await writePackage(
      "@acme/penguin-plugin-thing",
      oneModule,
      `${thingClass}
       export default { modules: [Thing] };`,
    );
    await writeConfig({ plugins: [file] });
    const result = await loadPlugins(root);
    expect(result.failed.size).toBe(0);
    expect(result.loaded).toHaveLength(1);
    const entry = result.loaded[0]!;
    expect(entry.specifier).toBe(file);
    expect(entry.modules.map((m) => m.manifest.name)).toEqual(["Thing"]);
    expect(entry.modules[0]!.manifest.contributes["SandboxModule.providers"]?.[0]?.id).toBe(
      "thing.provider",
    );
    expect(entry.ifaces?.ifaces["@acme/penguin-plugin-thing#Thing"]).toBeDefined();
    // The class is the code half: its @Bind field is the contribution's implementation.
    const instance = await entry.modules[0]!.create(
      { use: {}, contributions: {}, resources: {} as never, effect: () => {} },
      {},
    );
    expect(typeof (instance.bind?.["thing.provider"] as { confine: unknown }).confine).toBe(
      "function",
    );
  });

  it("an unresolvable specifier is skipped with its reason, not fatal", async () => {
    const good = await writePackage(
      "@acme/good",
      oneModule,
      `${thingClass}
       export default { modules: [Thing] };`,
    );
    await writeConfig({ plugins: ["@nope/definitely-not-installed", good] });
    const result = await loadPlugins(root);
    // The good one still loads: failure is per entry.
    expect(result.loaded.map((entry) => entry.specifier)).toEqual([good]);
    expect(result.failed.get("@nope/definitely-not-installed")).toBeTruthy();
  });

  it("a default export that is not a list of classes is a load failure that says so", async () => {
    const file = await writePackage(
      "@acme/half",
      oneModule,
      "export default { modules: { Thing: { create() {} } } };",
    );
    await writeConfig({ plugins: [file] });
    const result = await loadPlugins(root);
    expect(result.loaded).toEqual([]);
    expect(result.failed.get(file)).toMatch(/not a Plugin/);
  });

  it("a class the table does not carry is a stale build, named as such", async () => {
    const file = await writePackage(
      "@acme/extra",
      oneModule,
      `${thingClass}
       import { Component } from ${JSON.stringify(decorators)};
       @Component() export class Ghost {}
       export default { modules: [Thing, Ghost] };`,
    );
    await writeConfig({ plugins: [file] });
    const result = await loadPlugins(root);
    expect(result.failed.get(file)).toMatch(/Ghost: not in the generated manifest table/);
  });

  it("classes under `replaces` are paired the same way, and land in the plugin's replaces", async () => {
    const file = await writePackage(
      "@acme/penguin-plugin-thing",
      {
        ...oneModule,
        modules: {
          ...oneModule.modules,
          MemoryService: {
            ...oneModule.modules.Thing,
            name: "MemoryService",
            provides: {},
            contributes: {},
          },
        },
      },
      `${thingClass}
       import { Module } from ${JSON.stringify(decorators)};
       @Module() export class MemoryService {}
       export default { modules: [Thing], replaces: [MemoryService] };`,
    );
    await writeConfig({ plugins: [file] });
    const result = await loadPlugins(root);
    expect(result.failed.size).toBe(0);
    const entry = result.loaded[0]!;
    expect(entry.modules.map((m) => m.manifest.name)).toEqual(["Thing"]);
    expect(entry.replaces.map((m) => m.manifest.name)).toEqual(["MemoryService"]);
  });

  it("a package without a table ships no modules — a plugin is a plugin by being listed", async () => {
    const file = await writePackage("@acme/skills-only", null, "export default { modules: [] };");
    await writeConfig({ plugins: [file] });
    const result = await loadPlugins(root);
    expect(result.failed.size).toBe(0);
    expect(result.loaded[0]!.modules).toEqual([]);
  });

  it("a package that names module classes but ships no table was never built, and says so", async () => {
    const file = await writePackage(
      "@acme/unbuilt",
      null,
      `${thingClass}
       export default { modules: [Thing] };`,
    );
    await writeConfig({ plugins: [file] });
    const result = await loadPlugins(root);
    expect(result.failed.get(file)).toMatch(/ifaces\.json is missing — build the package/);
  });

  it("a malformed manifest in the table is a load failure naming the module", async () => {
    const file = await writePackage(
      "@acme/bad-table",
      { ifaces: {}, types: {}, modules: { Thing: { contributes: {} } } },
      "export default { modules: [] };",
    );
    await writeConfig({ plugins: [file] });
    const result = await loadPlugins(root);
    expect(result.failed.get(file)).toMatch(/ifaces\.json#modules\.Thing/);
  });
});

describe("builtin plugins", () => {
  /** A plugin package under a prefix's node_modules, the shape scripts/build-plugins.mjs ships. */
  async function writeBuiltin(prefix: string, name: string, moduleName: string): Promise<void> {
    const dir = path.join(prefix, "node_modules", ...name.split("/"));
    await mkdir(dir, { recursive: true });
    // The prefix manifest names what was shipped, the way build-plugins writes it.
    const manifestFile = path.join(prefix, "package.json");
    const manifest = JSON.parse(
      await readFile(manifestFile, "utf8").catch(() => '{"name":"prefix","private":true}'),
    ) as { dependencies?: Record<string, string> };
    manifest.dependencies = { ...manifest.dependencies, [name]: "0.0.0" };
    await writeFile(manifestFile, JSON.stringify(manifest), "utf8");
    await writeFile(
      path.join(dir, "package.json"),
      JSON.stringify({ name, main: "./index.js", type: "module" }),
      "utf8",
    );
    await writeFile(
      path.join(dir, IFACES_FILE),
      JSON.stringify({
        ifaces: {},
        types: {},
        modules: {
          [moduleName]: {
            name: moduleName,
            requires: {},
            provides: {},
            contributes: {},
            children: [],
          },
        },
        plugin: { modules: [moduleName], replaces: [] },
      }),
      "utf8",
    );
    await writeFile(
      path.join(dir, "index.js"),
      lower(`import { Module } from ${JSON.stringify(decorators)};
             @Module() export class ${moduleName} {}
             export default { modules: [${moduleName}] };`),
      "utf8",
    );
  }

  it("lists what the build ships, scoped and unscoped, and not what the root's own prefix holds", async () => {
    const assets = path.join(root, "hmr", "store", "assets", "abc");
    await writeBuiltin(path.join(assets, "plugins"), "@acme/penguin-plugin-one", "One");
    await writeBuiltin(path.join(assets, "plugins"), "plain-plugin", "Plain");
    // The operator's own prefix is not builtin: what it holds loads only when listed.
    await writeBuiltin(path.join(root, "plugins"), "@acme/installed", "Installed");
    const bases = pluginBases(root, assets);
    expect(bases[0]).toMatchObject({ builtin: false });
    expect(bases[1]).toMatchObject({ builtin: true });
    expect(await discoverBuiltinPlugins(bases)).toEqual([
      "@acme/penguin-plugin-one",
      "plain-plugin",
    ]);
  });

  it("does not load a shipped plugin until it is listed, and then loads it from the shipped prefix", async () => {
    const assetsRel = path.join("store", "assets", "abc");
    const assets = path.join(root, "hmr", assetsRel);
    await writeBuiltin(path.join(assets, "plugins"), "@acme/penguin-plugin-one", "One");
    await mkdir(path.join(root, "hmr"), { recursive: true });
    // harness.json is what names the committed assets; the loader reads it without a host.
    await writeFile(
      path.join(root, "hmr", "harness.json"),
      JSON.stringify({ assets: { dir: assetsRel.split(path.sep).join("/") } }),
      "utf8",
    );
    // Shipped, and nothing lists it: available is not installed.
    await writeConfig({ plugins: [] });
    expect((await loadPlugins(root)).loaded).toEqual([]);

    // Listed: it loads, resolved from the assets the push carried — no npm, nothing under
    // <root>/plugins.
    await writeConfig({ plugins: ["@acme/penguin-plugin-one"] });
    const result = await loadPlugins(root);
    expect([...result.failed.entries()]).toEqual([]);
    expect(result.loaded.map((p) => p.specifier)).toEqual(["@acme/penguin-plugin-one"]);
    expect(result.loaded[0]!.modules.map((m) => m.manifest.name)).toEqual(["One"]);
  });

  it("resolves a package through its exports' import condition, as npm shipped it", async () => {
    // The sandbox backends declare `exports: { ".": { types, import: "./dist/index.js" } }`
    // and no `require` condition; the loader reads the entry an importer would, not what
    // require.resolve would (it has none).
    const assets = path.join(root, "hmr", "store", "assets", "abc");
    const dir = path.join(assets, "plugins", "node_modules", "@acme", "exported");
    await mkdir(path.join(assets, "plugins"), { recursive: true });
    await writeFile(
      path.join(assets, "plugins", "package.json"),
      '{"name":"prefix","private":true}',
    );
    await writeClassPackage(dir, {
      name: "@acme/exported",
      module: "Exported",
      main: "./dist/index.js",
      exports: { ".": { types: "./dist/index.d.ts", import: "./dist/index.js" } },
    });
    await writeConfig({ plugins: ["@acme/exported"] });
    const result = await loadPlugins(root, assets);
    expect([...result.failed.entries()]).toEqual([]);
    expect(result.loaded[0]!.file).toBe(path.join(dir, "dist", "index.js"));
  });

  it("reads a committed assets dir from harness.json, or null without one", async () => {
    expect(await committedAssetsDir(root)).toBeNull();
    await mkdir(path.join(root, "hmr"), { recursive: true });
    await writeFile(
      path.join(root, "hmr", "harness.json"),
      JSON.stringify({ assets: { dir: "store/assets/x" } }),
    );
    expect(await committedAssetsDir(root)).toBe(path.join(root, "hmr", "store/assets/x"));
  });
});