Skip to content

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

20.0 KB
Raw Blame
/**
 * The Plugins page's pure decisions (features/plugins/plugins-page.tsx). One file, so the page
 * module is imported once.
 *
 * - All machines: every plugin is listed, and a machine-only one says where it runs. This
 *   server: what it is asked for, a shared plugin not removable from its table. Another
 *   machine: the state that machine reports, and what it has not received yet.
 * - A plugin is installed on an Agent once any part of it is there (a skill, or its hook
 *   package), read off the two installed lists; nothing is installed for an Agent with no
 *   snapshot or for a plugin that ships nothing.
 * - The market shelf's state for one Agent is not installed / installed / updatable, the third
 *   only ever off the server's own list of installs it says are behind.
 * - That same state divides the page's two sections: a library plugin the working Agent holds
 *   is listed as installed, one it lacks is offered — never a "not installed" card filed under
 *   "installed plugins" — while the Project's own module rows are not per-Agent and stay put.
 * - The installable list is what the deployment SHIPS, described by the registry's entry: the
 *   shelf carries an entry per plugin package the build carries, skills/hooks packages among
 *   them, and the server refuses the ones it does not ship.
 * - A library plugin's market entry is found by its package: the same bare name, or the scoped
 *   specifier carrying the card's version.
 * - The installed version is the hook package's where there is one, else the first installed
 *   skill's, and undefined where the plugin is not installed.
 * - The per-plugin reminder names the Agents the server lists as behind on it, in list order
 *   (versions are never compared here).
 * - The "update all" plan is empty when no Agent is behind, sends one request per Agent with
 *   every plugin it is behind on, and counts distinct plugins as the notice does.
 */
import { describe, expect, it } from "vitest";
import type { InstalledPluginsResponse, PluginIndexEntry, PluginItem } from "@adelie/server/api";
import {
  availablePluginRows,
  installedPluginRows,
  installedPluginVersion,
  marketEntryFor,
  marketState,
  outdatedAgentIds,
  pluginInstalled,
  pluginUpdatePlan,
  publishedPluginRows,
  rowFacets,
  splitPluginRows,
  type AgentInstalls,
  type PluginParts,
  type PluginView,
} from "../src/features/plugins/plugins-page";

const SELF = "Self000000000000";
const GPU = "Gpu0000000000000";

const row = (
  specifier: string,
  where: { everywhere: boolean; machines: string[]; here: boolean },
  active = where.here,
): InstalledPluginsResponse["plugins"][number] => ({
  specifier,
  active,
  builtin: false,
  modules: [],
  replaces: [],
  ...where,
});

const deployment: InstalledPluginsResponse = {
  plugins: [
    row("@acme/shared", { everywhere: true, machines: [], here: true }),
    row("@acme/gpu-only", { everywhere: false, machines: [GPU], here: false }),
  ],
  shipped: [],
  file: ".project_config.toml",
  machineId: SELF,
  restartPending: false,
};

const nameOf = (id: string) => (id === GPU ? "gpu-box" : "this server");
const modules = (rows: ReturnType<typeof installedPluginRows>) =>
  rows.flatMap((r) => (r.kind === "module" ? [r] : []));

describe("plugin rows per machine", () => {
  it("all machines: every plugin, and a machine-only one says where it runs", () => {
    const view: PluginView = { machineId: null, remote: null, nameOf };
    const rows = modules(installedPluginRows([], "en", deployment, [], view));
    expect(rows.map((r) => [r.specifier, r.state, r.onlyOn])).toEqual([
      ["@acme/shared", "active", undefined],
      ["@acme/gpu-only", "elsewhere", ["gpu-box"]],
    ]);
    // Offered for all machines, since the shared table does not list it.
    expect(availablePluginRows(deployment, [], view)).toEqual([]);
  });

  it("this server: what it is asked for, and a shared plugin cannot be removed from its table", () => {
    const view: PluginView = { machineId: SELF, remote: null, nameOf };
    const rows = modules(installedPluginRows([], "en", deployment, [], view));
    expect(rows.map((r) => r.specifier)).toEqual(["@acme/shared"]);
    expect(rows[0]!.removeBlocked).toBeDefined();
  });

  it("another machine: the state it reports, and what it has not received yet", () => {
    const remote: InstalledPluginsResponse = {
      ...deployment,
      machineId: GPU,
      plugins: [row("@acme/gpu-only", { everywhere: true, machines: [], here: true }, false)],
    };
    remote.plugins[0]!.error = "npm: 404";
    const view: PluginView = { machineId: GPU, remote, nameOf };
    const rows = modules(installedPluginRows([], "en", deployment, [], view));
    expect(rows.map((r) => [r.specifier, r.state, r.removeBlocked === undefined])).toEqual([
      ["@acme/shared", "unsynced", false],
      ["@acme/gpu-only", "failed", true],
    ]);
  });
});

/** One registry entry, as the shelf serves it (the fields the page reads). */
const entry = (name: string, version = "0.2.2"): PluginIndexEntry => ({
  name,
  version,
  description: `${name} as its package describes it`,
  authors: ["Prism Shadow"],
  license: "Apache-2.0",
});

describe("availablePluginRows", () => {
  const shipped: InstalledPluginsResponse = {
    ...deployment,
    shipped: ["@adelie/sandbox-bwrap"],
  };

  it("offers what the deployment ships, with the registry's entry for it", () => {
    const rows = availablePluginRows(shipped, [entry("@adelie/sandbox-bwrap")]);
    expect(rows.map((r) => [r.specifier, r.entry?.name, r.shipped])).toEqual([
      ["@adelie/sandbox-bwrap", "@adelie/sandbox-bwrap", true],
    ]);
  });

  it("leaves out a shelf entry this deployment does not ship, rather than offering one the server refuses", () => {
    // The shelf carries an entry per plugin package the build carries, and a skills package is
    // one of them — but a Project cannot ask for it: it installs to an Agent, and the install
    // endpoint answers `plugin_not_shipped` for anything outside the build's own list.
    const rows = availablePluginRows(shipped, [
      entry("@adelie/csu-mail", "2026.10.05.1"),
      entry("@adelie/sandbox-bwrap"),
    ]);
    expect(rows.map((r) => r.specifier)).toEqual(["@adelie/sandbox-bwrap"]);
  });

  it("offers a shipped package the registry has no entry for, with nothing to describe it", () => {
    const rows = availablePluginRows(shipped, []);
    expect(rows.map((r) => [r.specifier, r.entry, r.shipped])).toEqual([
      ["@adelie/sandbox-bwrap", undefined, true],
    ]);
  });
});

/**
 * The published side of the shelf: entries that are on the market because their package was
 * published to npm, not because this build carries it. The row exists so such a plugin is
 * visible where plugins are browsed, and its verb fetches it into the library.
 */
describe("publishedPluginRows", () => {
  it("offers an entry this build does not carry and the library does not hold", () => {
    const rows = publishedPluginRows(
      [entry("@adelie/not-in-this-build"), entry("@adelie/csu-mail")],
      [],
      ["csu-mail"],
    );
    expect(rows.map((r) => r.specifier)).toEqual(["@adelie/not-in-this-build"]);
  });

  it("leaves a shipped one to the row that installs it, and a library one to its card", () => {
    // The two lists name the same package differently — the shelf by its package specifier, the
    // library by the directory it was read from — so both spellings count as known.
    expect(
      publishedPluginRows([entry("@adelie/sandbox-bwrap")], ["@adelie/sandbox-bwrap"], []),
    ).toEqual([]);
    expect(publishedPluginRows([entry("@adelie/csu-mail")], [], ["csu-mail"])).toEqual([]);
    expect(publishedPluginRows([entry("csu-mail")], [], ["csu-mail"])).toEqual([]);
  });
});

describe("marketEntryFor", () => {
  const card = { name: "csu-mail", version: "2026.10.05.1" };

  it("finds the entry by the package specifier, when it carries the card's version", () => {
    const index = [entry("@adelie/csu-mail", "2026.10.05.1"), entry("@adelie/other")];
    expect(marketEntryFor(card, index)?.name).toBe("@adelie/csu-mail");
  });

  it("takes an entry named by the bare name as it is", () => {
    expect(marketEntryFor(card, [entry("csu-mail", "2026.10.05.1")])?.name).toBe("csu-mail");
  });

  it("is undefined for a name and version no entry carries — a user plugin has no package of the build's", () => {
    expect(marketEntryFor(card, [entry("@adelie/csu-mail", "2026.09.01.1")])).toBeUndefined();
    expect(marketEntryFor(card, [entry("@acme/other")])).toBeUndefined();
    expect(marketEntryFor(card, [])).toBeUndefined();
  });
});

const skill = (name: string) => ({ name, description: "", version: "2026.08.01.1" });

/** A plugin shipping two skills and a stop hook, one with a skill only, and one with a hook only. */
const FULL: PluginParts = {
  name: "orchestration",
  skills: [skill("plan"), skill("run")],
  hooks: ["stop"],
};
const SKILL_ONLY: PluginParts = { name: "web-design", skills: [skill("web-design")], hooks: [] };
const HOOK_ONLY: PluginParts = { name: "goal", skills: [], hooks: ["stop"] };

const installs = (
  skills: Record<string, string>,
  hooks: Record<string, string>,
): AgentInstalls => ({
  skills: new Map(Object.entries(skills)),
  hooks: new Map(Object.entries(hooks)),
});

describe("pluginInstalled", () => {
  it("counts a plugin as installed once any part of it is there, so a partial copy can be updated", () => {
    const whole = installs(
      { plan: "2026.08.01.1", run: "2026.08.01.1" },
      { orchestration: "2026.08.01.1" },
    );
    expect(pluginInstalled(FULL, whole)).toBe(true);
    // An older version that shipped one skill fewer, or a copy missing its hook package, is
    // what the server lists as behind: an installed plugin an update completes.
    expect(
      pluginInstalled(FULL, installs({ plan: "2026.08.01.1" }, { orchestration: "2026.08.01.1" })),
    ).toBe(true);
    expect(pluginInstalled(FULL, installs({ plan: "2026.08.01.1", run: "2026.08.01.1" }, {}))).toBe(
      true,
    );
    expect(pluginInstalled(FULL, installs({ other: "2026.08.01.1" }, {}))).toBe(false);
  });

  it("reads a skill-only plugin off the skills list and a hook-only one off the hooks list", () => {
    expect(pluginInstalled(SKILL_ONLY, installs({ "web-design": "2026.07.30.1" }, {}))).toBe(true);
    expect(pluginInstalled(SKILL_ONLY, installs({}, { "web-design": "2026.07.30.1" }))).toBe(false);
    expect(pluginInstalled(HOOK_ONLY, installs({}, { goal: "2026.08.29.1" }))).toBe(true);
    expect(pluginInstalled(HOOK_ONLY, installs({ goal: "2026.08.29.1" }, {}))).toBe(false);
  });

  it("is false for an Agent with no snapshot yet, and for a plugin that ships nothing", () => {
    expect(pluginInstalled(SKILL_ONLY, undefined)).toBe(false);
    expect(pluginInstalled({ name: "empty", skills: [], hooks: [] }, installs({}, {}))).toBe(false);
  });
});

describe("marketState", () => {
  it("reads not installed for an Agent holding none of the plugin, so the shelf offers the one click", () => {
    expect(marketState(SKILL_ONLY, undefined, false)).toBe("available");
    expect(marketState(SKILL_ONLY, installs({ other: "2026.07.01.1" }, {}), false)).toBe(
      "available",
    );
  });

  it("is installed when that Agent's copy is current, and updatable when the server lists it behind", () => {
    const there = installs({ "web-design": "2026.08.01.1" }, {});
    expect(marketState(SKILL_ONLY, there, false)).toBe("installed");
    // The flag is the server's own comparison (AgentSummary.pluginUpdates), never re-derived from
    // the two version strings here — so the tag and the library's update badge cannot disagree.
    expect(marketState(SKILL_ONLY, there, true)).toBe("updatable");
  });

  it("never calls a plugin the Agent does not have updatable, whatever the server lists", () => {
    expect(marketState(HOOK_ONLY, installs({}, {}), true)).toBe("available");
  });
});

describe("installedPluginVersion", () => {
  it("reads the hook package's version where there is one, else the first skill's", () => {
    expect(
      installedPluginVersion(
        FULL,
        installs({ plan: "2026.07.01.1", run: "2026.07.01.1" }, { orchestration: "2026.07.02.1" }),
      ),
    ).toBe("2026.07.02.1");
    expect(installedPluginVersion(SKILL_ONLY, installs({ "web-design": "2026.07.30.1" }, {}))).toBe(
      "2026.07.30.1",
    );
  });

  it("is undefined where the plugin is not installed, and reads a partial copy's first installed skill", () => {
    expect(installedPluginVersion(SKILL_ONLY, undefined)).toBeUndefined();
    expect(
      installedPluginVersion(SKILL_ONLY, installs({ other: "2026.07.01.1" }, {})),
    ).toBeUndefined();
    expect(
      installedPluginVersion(
        { name: "pair", skills: [skill("plan"), skill("run")], hooks: [] },
        installs({ run: "2026.07.01.1" }, {}),
      ),
    ).toBe("2026.07.01.1");
  });
});

/** Just the two fields the update questions read (they take a Pick, so the fixture can be one too). */
const agent = (agentId: string, ...updates: Array<{ name: string; version: string }>) => ({
  agentId,
  pluginUpdates: updates,
});

describe("outdatedAgentIds", () => {
  it("names the Agents the server lists as behind on that plugin, in list order", () => {
    const agents = [
      agent("stale", { name: "web-design", version: "2026.08.01.1" }),
      agent("current"),
      agent("other", { name: "vllm", version: "2026.08.01.1" }),
      agent(
        "also_stale",
        { name: "web-design", version: "2026.08.01.1" },
        { name: "vllm", version: "2026.08.01.1" },
      ),
    ];
    expect(outdatedAgentIds(agents, "web-design")).toEqual(["stale", "also_stale"]);
    expect(outdatedAgentIds(agents, "vllm")).toEqual(["other", "also_stale"]);
    expect(outdatedAgentIds(agents, "goal")).toEqual([]);
  });
});

describe("pluginUpdatePlan", () => {
  it("is empty when no Agent is behind, so the notice has nothing to offer", () => {
    expect(pluginUpdatePlan([agent("a"), agent("b")])).toEqual({ perAgent: [], plugins: [] });
  });

  it("sends one request per Agent, carrying every plugin that Agent is behind on", () => {
    // The install endpoint takes a list, and an Agent behind on two plugins is one overwrite
    // either way.
    expect(
      pluginUpdatePlan([
        agent(
          "alpha",
          { name: "web-design", version: "2026.08.01.3" },
          { name: "vllm", version: "2026.08.01.2" },
        ),
        agent("beta"),
        agent("gamma", { name: "web-design", version: "2026.08.01.3" }),
      ]),
    ).toEqual({
      perAgent: [
        { agentId: "alpha", names: ["vllm", "web-design"] },
        { agentId: "gamma", names: ["web-design"] },
      ],
      plugins: ["vllm", "web-design"],
    });
  });

  it("counts distinct plugins, matching what the notice above the button says", () => {
    // The gate counts by plugin because the page lists the library once. The plan's `plugins`
    // is what the confirmation lists, so the two must be the same number or the dialog would
    // contradict the block that opened it.
    const plan = pluginUpdatePlan([
      agent("alpha", { name: "shared", version: "2026.08.01.2" }),
      agent("beta", { name: "shared", version: "2026.08.01.2" }),
      agent("gamma", { name: "shared", version: "2026.08.01.2" }),
    ]);
    expect(plan.plugins).toEqual(["shared"]);
    expect(plan.perAgent).toHaveLength(3);
  });
});

/** A library plugin as the library listing carries it (only the fields the row questions read). */
const libraryPlugin = (name: string, skills: string[] = [], hooks: string[] = []): PluginItem => ({
  source: "builtin",
  name,
  description: `${name} as its package describes it`,
  version: "2026.08.01.1",
  skills: skills.map((s) => ({ name: s, description: "", version: "2026.08.01.1" })),
  hooks,
});

/** A library row, the shape `installedPluginRows` builds before the page divides the lists. */
const libraryRow = (plugin: PluginItem) => ({
  kind: "library" as const,
  plugin,
  category: "Developer",
});

describe("splitPluginRows", () => {
  const held = libraryRow(libraryPlugin("web-design", ["web-design"]));
  const missing = libraryRow(libraryPlugin("csu-mail", ["csu-mail"]));
  const projectRow = {
    kind: "module" as const,
    specifier: "@acme/shared",
    entry: undefined,
    state: "active" as const,
    shipped: false,
  };
  const nameOfRow = (row: ReturnType<typeof splitPluginRows>["installed"][number]): string =>
    row.kind === "library" ? row.plugin.name : row.specifier;

  /** A shelf entry that only the published side carries: nowhere on this machine yet. */
  const publishedRow = (name: string) => ({
    kind: "published" as const,
    specifier: name,
    entry: entry(name),
  });

  it("puts a library plugin the working Agent holds under installed, and one it lacks under available", () => {
    const { installed, available } = splitPluginRows(
      [held, missing, projectRow],
      [agent("alpha")],
      new Map([["alpha", installs({ "web-design": "2026.08.01.1" }, {})]]),
      "alpha",
    );
    // The Project's own module rows are not per-Agent and stay in the installed list.
    expect(installed.map(nameOfRow)).toEqual(["web-design", "@acme/shared"]);
    expect(available.map(nameOfRow)).toEqual(["csu-mail"]);
  });

  it("files a published plugin under available whatever Agent the page is working with", () => {
    const shelf = publishedRow("@adelie/not-in-this-build");
    const rows = [held, missing, projectRow, shelf];
    const agents = [agent("alpha")];
    const held_ = new Map([["alpha", installs({ "web-design": "2026.08.01.1" }, {})]]);

    // With an Agent selected: the library plugin it lacks is offered beside it.
    expect(splitPluginRows(rows, agents, held_, "alpha").available.map(nameOfRow)).toEqual([
      "csu-mail",
      "@adelie/not-in-this-build",
    ]);
    // With none: the library either way stays where it is, but a published plugin is nowhere
    // until it is fetched — no Agent's install state can make it installed, so it is offered
    // in both cases.
    const none = splitPluginRows(rows, agents, held_, null);
    expect(none.available.map(nameOfRow)).toEqual(["@adelie/not-in-this-build"]);
    expect(none.installed.map(nameOfRow)).not.toContain("@adelie/not-in-this-build");

    // Its facets say it is offered, and claim nothing about what it carries: nothing on this
    // machine has read the package yet.
    expect(rowFacets(shelf)).toEqual({ categories: [], kinds: [], states: ["available"] });
  });

  it("files a copy the server lists as behind under installed: an update is what that card offers", () => {
    const { installed, available } = splitPluginRows(
      [held],
      [agent("alpha", { name: "web-design", version: "2026.08.01.1" })],
      new Map([["alpha", installs({ "web-design": "2026.07.01.1" }, {})]]),
      "alpha",
    );
    expect(installed.map(nameOfRow)).toEqual(["web-design"]);
    expect(available).toEqual([]);
  });

  it("carries the shelf state it divided by, which is what the filter column counts", () => {
    const { installed, available } = splitPluginRows(
      [held, missing],
      [agent("alpha")],
      new Map([["alpha", installs({ "web-design": "2026.08.01.1" }, {})]]),
      "alpha",
    );
    // The row keeps the value the card's tag draws: a row filed under "available" can never
    // count as installed in the state filter either.
    expect(installed[0]!.kind === "library" && installed[0]!.market).toBe("installed");
    expect(available[0]!.kind === "library" && available[0]!.market).toBe("available");
    expect(rowFacets(available[0]!).states).toEqual(["available"]);
    expect(rowFacets(installed[0]!).states).toEqual(["installed"]);
    // A row the page never classified (no Agent selected) reads as installed, as it always has.
    expect(rowFacets(held).states).toEqual(["installed"]);
  });

  it("moves nothing while no Agent is selected: there is nothing to compare against", () => {
    const { installed, available } = splitPluginRows(
      [held, missing, projectRow],
      [agent("alpha")],
      new Map([["alpha", installs({ "web-design": "2026.08.01.1" }, {})]]),
      null,
    );
    expect(installed.map(nameOfRow)).toEqual(["web-design", "csu-mail", "@acme/shared"]);
    expect(available).toEqual([]);
  });
});