@vellumai/assistant 0.6.4 → 0.6.6

package/src/__tests__/plugin-registry.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Tests for the plugin registry (PR 13).
+ *
+ * Covers successful registration, required-field and duplicate-name
+ * validation, capability-version negotiation error messaging, injector
+ * ordering, and middleware collection order.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  ASSISTANT_API_VERSIONS,
+  getInjectors,
+  getMiddlewaresFor,
+  getRegisteredPlugins,
+  registerPlugin,
+  resetPluginRegistryForTests,
+} from "../plugins/registry.js";
+import {
+  type CompactionArgs,
+  type CompactionResult,
+  type Injector,
+  type Middleware,
+  type Plugin,
+  PluginExecutionError,
+} from "../plugins/types.js";
+
+/** Build a minimal, valid plugin with the given name and optional extras. */
+function buildPlugin(
+  name: string,
+  extras: Partial<Omit<Plugin, "manifest">> = {},
+  requiresOverride?: Record<string, string>,
+): Plugin {
+  return {
+    manifest: {
+      name,
+      version: "0.0.1",
+      requires: requiresOverride ?? { pluginRuntime: "v1" },
+    },
+    ...extras,
+  };
+}
+
+describe("plugin registry", () => {
+  beforeEach(() => {
+    resetPluginRegistryForTests();
+  });
+
+  test("registers a minimal plugin successfully", () => {
+    const plugin = buildPlugin("alpha");
+    registerPlugin(plugin);
+
+    const registered = getRegisteredPlugins();
+    expect(registered).toHaveLength(1);
+    expect(registered[0]?.manifest.name).toBe("alpha");
+  });
+
+  test("throws on duplicate-name registration", () => {
+    registerPlugin(buildPlugin("alpha"));
+    expect(() => registerPlugin(buildPlugin("alpha"))).toThrow(
+      PluginExecutionError,
+    );
+    expect(() => registerPlugin(buildPlugin("alpha"))).toThrow(
+      "already registered",
+    );
+  });
+
+  test("throws when manifest is missing", () => {
+    // Cast through `unknown` to simulate a JS caller passing a malformed plugin.
+    expect(() => registerPlugin({} as unknown as Plugin)).toThrow(
+      PluginExecutionError,
+    );
+  });
+
+  test("throws when manifest.name is missing", () => {
+    const bad = {
+      manifest: {
+        version: "0.0.1",
+        requires: { pluginRuntime: "v1" },
+      },
+    } as unknown as Plugin;
+    expect(() => registerPlugin(bad)).toThrow(/manifest\.name is required/);
+  });
+
+  test("throws on non-kebab-case plugin names (path-traversal guard)", () => {
+    // Plugin names flow into filesystem paths (`plugins-data/<name>/`), so the
+    // registry must reject anything that could escape the storage directory
+    // or otherwise deviate from the kebab-case contract.
+    const cases = [
+      "../evil",
+      "../../etc",
+      "evil/with/slashes",
+      "has space",
+      "Has-Uppercase",
+      "-leading-hyphen",
+      "trailing-hyphen-",
+      "double--hyphen",
+      ".",
+      "",
+    ];
+    for (const name of cases) {
+      const plugin = buildPlugin(name || "x");
+      // Override the name post-build so the empty-string case exercises the
+      // same code path as the others (buildPlugin uses the literal value).
+      (plugin.manifest as { name: string }).name = name;
+      expect(() => registerPlugin(plugin)).toThrow(PluginExecutionError);
+    }
+  });
+
+  test("accepts valid kebab-case plugin names", () => {
+    for (const name of ["a", "abc", "a-b", "a1-b2", "foo-bar-baz"]) {
+      resetPluginRegistryForTests();
+      expect(() => registerPlugin(buildPlugin(name))).not.toThrow();
+    }
+  });
+
+  test("throws when manifest.version is missing", () => {
+    const bad = {
+      manifest: {
+        name: "missing-version",
+        requires: { pluginRuntime: "v1" },
+      },
+    } as unknown as Plugin;
+    expect(() => registerPlugin(bad)).toThrow(/manifest\.version is required/);
+  });
+
+  test("throws when manifest.requires is missing", () => {
+    const bad = {
+      manifest: { name: "missing-requires", version: "0.0.1" },
+    } as unknown as Plugin;
+    expect(() => registerPlugin(bad)).toThrow(/manifest\.requires is required/);
+  });
+
+  test("throws when requires.pluginRuntime is missing", () => {
+    const plugin = buildPlugin(
+      "no-runtime",
+      {},
+      // Valid shape but no pluginRuntime entry.
+      { memoryApi: "v1" },
+    );
+    expect(() => registerPlugin(plugin)).toThrow(PluginExecutionError);
+    expect(() => registerPlugin(plugin)).toThrow(/pluginRuntime/);
+  });
+
+  test("throws with version-mismatch message when a required version is not exposed", () => {
+    // The assistant seeds memoryApi with ["v1"]. Requesting v2 must fail.
+    const plugin = buildPlugin(
+      "too-new",
+      {},
+      {
+        pluginRuntime: "v1",
+        memoryApi: "v2",
+      },
+    );
+
+    expect(() => registerPlugin(plugin)).toThrow(PluginExecutionError);
+
+    // Sanity-check the assistant actually exposes only v1 for memoryApi so
+    // this test fails loudly if the capability table ever adds v2.
+    expect(ASSISTANT_API_VERSIONS.memoryApi).toEqual(["v1"]);
+
+    try {
+      registerPlugin(plugin);
+      throw new Error("expected registerPlugin to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(PluginExecutionError);
+      const msg = (err as PluginExecutionError).message;
+      // Error message must reference plugin name, API, required version,
+      // and the versions the assistant exposes.
+      expect(msg).toContain("too-new");
+      expect(msg).toContain("memoryApi");
+      expect(msg).toContain("v2");
+      expect(msg).toContain("v1");
+      expect((err as PluginExecutionError).pluginName).toBe("too-new");
+    }
+  });
+
+  test("throws with clear message when a required capability is unknown", () => {
+    const plugin = buildPlugin(
+      "asks-for-mystery",
+      {},
+      {
+        pluginRuntime: "v1",
+        thisDoesNotExist: "v1",
+      },
+    );
+    expect(() => registerPlugin(plugin)).toThrow(PluginExecutionError);
+    try {
+      registerPlugin(plugin);
+      throw new Error("expected registerPlugin to throw");
+    } catch (err) {
+      const msg = (err as PluginExecutionError).message;
+      expect(msg).toContain("asks-for-mystery");
+      expect(msg).toContain("thisDoesNotExist");
+      expect(msg).toContain("(none)");
+    }
+  });
+
+  test("getInjectors returns injectors sorted by order ascending", () => {
+    const high: Injector = {
+      name: "high-order",
+      order: 20,
+      async produce() {
+        return null;
+      },
+    };
+    const low: Injector = {
+      name: "low-order",
+      order: 10,
+      async produce() {
+        return null;
+      },
+    };
+
+    // Register the higher-order plugin first so registration order alone
+    // would produce the wrong sequence — the test proves sort-by-order wins.
+    registerPlugin(buildPlugin("high", { injectors: [high] }));
+    registerPlugin(buildPlugin("low", { injectors: [low] }));
+
+    const injectors = getInjectors();
+    expect(injectors.map((i) => i.name)).toEqual(["low-order", "high-order"]);
+  });
+
+  test("getMiddlewaresFor returns middleware in registration order", () => {
+    const firstMw: Middleware<CompactionArgs, CompactionResult> = async (
+      args,
+      next,
+    ) => next(args);
+    const secondMw: Middleware<CompactionArgs, CompactionResult> = async (
+      args,
+      next,
+    ) => next(args);
+
+    registerPlugin(
+      buildPlugin("plugin-first", { middleware: { compaction: firstMw } }),
+    );
+    registerPlugin(
+      buildPlugin("plugin-second", { middleware: { compaction: secondMw } }),
+    );
+
+    const middlewares = getMiddlewaresFor("compaction");
+    expect(middlewares).toHaveLength(2);
+    // Identity comparison proves the middleware instances come back in
+    // registration order — outer→inner composition semantics belong to the
+    // pipeline runner (PR 12), not the registry.
+    expect(middlewares[0]).toBe(firstMw);
+    expect(middlewares[1]).toBe(secondMw);
+  });
+
+  test("getMiddlewaresFor skips plugins without a middleware for the pipeline", () => {
+    const mw: Middleware<CompactionArgs, CompactionResult> = async (
+      args,
+      next,
+    ) => next(args);
+    registerPlugin(buildPlugin("bare"));
+    registerPlugin(buildPlugin("has-mw", { middleware: { compaction: mw } }));
+
+    const middlewares = getMiddlewaresFor("compaction");
+    expect(middlewares).toHaveLength(1);
+    expect(middlewares[0]).toBe(mw);
+  });
+
+  test("getRegisteredPlugins reflects registration order", () => {
+    registerPlugin(buildPlugin("one"));
+    registerPlugin(buildPlugin("two"));
+    registerPlugin(buildPlugin("three"));
+    expect(getRegisteredPlugins().map((p) => p.manifest.name)).toEqual([
+      "one",
+      "two",
+      "three",
+    ]);
+  });
+});

package/src/__tests__/plugin-route-contribution.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Tests for plugin HTTP-route contributions (PR 32).
+ *
+ * A plugin may declare a `routes` array on its {@link Plugin} shape; after
+ * `init()` succeeds, bootstrap wires each entry into the skill-route registry
+ * via {@link registerSkillRoute}, retains the opaque {@link SkillRouteHandle}
+ * it receives back, and on shutdown calls {@link unregisterSkillRoute} with
+ * that exact handle. Pattern-text matching was removed deliberately: two
+ * owners (e.g. a plugin and a skill) can legitimately register the same
+ * regex, and keying on `source + flags` would let one owner's teardown
+ * silently evict another owner's route, violating the "no traffic hits a
+ * plugin handler during onShutdown" invariant.
+ *
+ * The registry doesn't own HTTP itself — the tests here exercise:
+ *
+ *  1. Bootstrap → `registerSkillRoute` → `matchSkillRoute` returns the plugin's
+ *     handler, and the handler responds as expected.
+ *  2. Shutdown → `unregisterSkillRoute` drops the entry, and subsequent
+ *     `matchSkillRoute` lookups return `null`.
+ *  3. Plugins without `routes` (or with an empty array) bootstrap cleanly.
+ *  4. When two plugins register regex patterns with identical `source+flags`,
+ *     each plugin's shutdown only removes its own route — the other plugin's
+ *     route stays live until its own teardown runs.
+ *
+ * Uses `mock.module` to stub credential resolution — bootstrap otherwise
+ * tries to hit the real secure-key backend. `resetPluginRegistryForTests()`
+ * isolates plugin-registry state and `resetSkillRoutesForTests()` isolates
+ * skill-route-registry state between cases.
+ */
+
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Stub the credential store before importing bootstrap so the module binds to
+// the mock. Plugins in these tests don't declare `requiresCredential`, but
+// the mock keeps the test hermetic regardless of what the backend would do.
+const getSecureKeyAsyncMock = mock(
+  async (_account: string): Promise<string | undefined> => undefined,
+);
+mock.module("../security/secure-keys.js", () => ({
+  getSecureKeyAsync: getSecureKeyAsyncMock,
+}));
+
+import type { AssistantConfig } from "../config/schema.js";
+import {
+  bootstrapPlugins,
+  type DaemonContext,
+} from "../daemon/external-plugins-bootstrap.js";
+import { runShutdownHooks } from "../daemon/shutdown-registry.js";
+import {
+  registerPlugin,
+  resetPluginRegistryForTests,
+} from "../plugins/registry.js";
+import type { Plugin } from "../plugins/types.js";
+import {
+  matchSkillRoute,
+  resetSkillRoutesForTests,
+  type SkillRoute,
+} from "../runtime/skill-route-registry.js";
+
+// Redirect plugin storage creation into a per-process temp tree so the test
+// never touches a developer's real ~/.vellum.
+const TEST_INSTANCE_DIR = join(
+  tmpdir(),
+  `vellum-plugin-route-contrib-test-${process.pid}`,
+);
+process.env.BASE_DATA_DIR = TEST_INSTANCE_DIR;
+
+const fakeConfig = {} as unknown as AssistantConfig;
+const fakeCtx: DaemonContext = {
+  config: fakeConfig,
+  assistantVersion: "9.9.9-test",
+};
+
+/** Build a minimal valid plugin with optional route contributions. */
+function buildPlugin(
+  name: string,
+  extras: Partial<Omit<Plugin, "manifest">> = {},
+): Plugin {
+  return {
+    manifest: {
+      name,
+      version: "0.0.1",
+      requires: { pluginRuntime: "v1" },
+    },
+    ...extras,
+  };
+}
+
+describe("plugin route contributions", () => {
+  const echoPattern = /^\/_plugin\/echo$/;
+
+  beforeEach(async () => {
+    resetPluginRegistryForTests();
+    resetSkillRoutesForTests();
+    getSecureKeyAsyncMock.mockReset();
+    getSecureKeyAsyncMock.mockImplementation(async () => undefined);
+    await rm(TEST_INSTANCE_DIR, { recursive: true, force: true });
+  });
+
+  test("bootstrap registers a plugin's routes and the HTTP handler responds", async () => {
+    let initFired = false;
+    const route: SkillRoute = {
+      pattern: echoPattern,
+      methods: ["GET"],
+      handler: async () =>
+        new Response("echo", {
+          status: 200,
+          headers: { "content-type": "text/plain" },
+        }),
+    };
+
+    registerPlugin(
+      buildPlugin("echo-plugin", {
+        async init() {
+          initFired = true;
+        },
+        routes: [route],
+      }),
+    );
+
+    await bootstrapPlugins(fakeCtx);
+
+    // init() must have run — route registration is gated on init success.
+    expect(initFired).toBe(true);
+
+    // matchSkillRoute resolves against the same registry the HTTP server
+    // hits at request dispatch time, so a match here proves the plugin's
+    // handler is reachable from production code paths.
+    const matched = matchSkillRoute("/_plugin/echo", "GET");
+    expect(matched).not.toBeNull();
+    expect(matched!.kind).toBe("match");
+
+    // Invoke the handler through the matched record to prove the response
+    // actually comes from the plugin — not some default.
+    if (matched!.kind !== "match") throw new Error("unreachable");
+    const req = new Request("http://host/_plugin/echo");
+    const res = await matched!.route.handler(req, matched!.match);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("echo");
+  });
+
+  test("shutdown unregisters the plugin's routes", async () => {
+    const route: SkillRoute = {
+      pattern: echoPattern,
+      methods: ["GET"],
+      handler: async () => new Response("echo", { status: 200 }),
+    };
+
+    registerPlugin(buildPlugin("echo-plugin", { routes: [route] }));
+
+    await bootstrapPlugins(fakeCtx);
+
+    // Sanity: route is live after bootstrap.
+    expect(matchSkillRoute("/_plugin/echo", "GET")).not.toBeNull();
+
+    // Shutdown runs the reverse-order teardown hook registered by bootstrap.
+    await runShutdownHooks("test-shutdown");
+
+    // Route is gone — matchSkillRoute returns null because no pattern
+    // matches the path at all anymore.
+    expect(matchSkillRoute("/_plugin/echo", "GET")).toBeNull();
+  });
+
+  test("plugin with no routes bootstraps and shuts down cleanly", async () => {
+    // Declaring no `routes` field is the common case; bootstrap must skip
+    // route handling entirely (the guard is `if plugin.routes && length > 0`).
+    registerPlugin(buildPlugin("no-routes-plugin", { async init() {} }));
+
+    await bootstrapPlugins(fakeCtx);
+    await runShutdownHooks("test-shutdown");
+
+    // Nothing to verify beyond "neither throws" — an empty `routes` must not
+    // regress existing no-op bootstrap semantics.
+    expect(true).toBe(true);
+  });
+
+  test("shutdown tolerates a route whose registry entry was wiped externally", async () => {
+    // Guard against the case where a stale handle no longer points at a live
+    // registry entry (e.g. the registry was cleared externally). The shutdown
+    // hook must not crash — unregisterSkillRoute returns false, and
+    // bootstrap's try/catch around the call swallows the signal. This
+    // exercises the defensive path so a partial-crash recovery still runs
+    // every plugin's onShutdown in reverse order.
+    let shutdownFired = false;
+    registerPlugin(
+      buildPlugin("echo-plugin", {
+        routes: [
+          {
+            pattern: echoPattern,
+            methods: ["GET"],
+            handler: async () => new Response("echo", { status: 200 }),
+          },
+        ],
+        async onShutdown() {
+          shutdownFired = true;
+        },
+      }),
+    );
+
+    await bootstrapPlugins(fakeCtx);
+
+    // Simulate an external wipe before the shutdown hook runs — e.g. a
+    // different subsystem calling `resetSkillRoutesForTests` or a hot-reload
+    // flow clearing the registry. The plugin's retained handle is now stale.
+    resetSkillRoutesForTests();
+
+    await runShutdownHooks("test-shutdown");
+
+    // onShutdown still ran despite the stale handle — proving the
+    // route-unregister step does not short-circuit plugin teardown.
+    expect(shutdownFired).toBe(true);
+  });
+
+  test("shutdown of one plugin does not evict a sibling's same-pattern route", async () => {
+    // Regression for the reviewer-flagged invariant: keying unregistration on
+    // `pattern.source + flags` would let plugin-A's teardown drop plugin-B's
+    // route when both declared regex with identical text. With handle-keyed
+    // identity, each plugin's teardown removes only its own registrations.
+    //
+    // We simulate this by wiring two plugins that both contribute a route
+    // matching `/^\/_plugin\/echo$/`. Teardown runs in reverse registration
+    // order, so plugin-B is torn down first; plugin-A's route must still
+    // match afterwards, and only disappear once plugin-A's own teardown
+    // runs.
+    let pluginAShutdown = false;
+    let pluginBShutdown = false;
+
+    registerPlugin(
+      buildPlugin("plugin-a", {
+        routes: [
+          {
+            pattern: /^\/_plugin\/echo$/,
+            methods: ["GET"],
+            handler: async () => new Response("a", { status: 200 }),
+          },
+        ],
+        async onShutdown() {
+          // When plugin-A's teardown runs, plugin-B has already been torn
+          // down — but plugin-A's route must still be live because
+          // `onShutdown` fires *after* the route-unregister step for this
+          // plugin but *before* it leaves teardownPlugin. We check liveness
+          // from plugin-B's teardown instead (see below).
+          pluginAShutdown = true;
+        },
+      }),
+    );
+
+    registerPlugin(
+      buildPlugin("plugin-b", {
+        routes: [
+          {
+            pattern: /^\/_plugin\/echo$/,
+            methods: ["GET"],
+            handler: async () => new Response("b", { status: 200 }),
+          },
+        ],
+        async onShutdown() {
+          // Plugin-B's routes have already been unregistered by the time
+          // this fires, but plugin-A's route is still live — it only gets
+          // torn down after this hook returns and the loop moves on to
+          // plugin-A. Confirm the registry still has a matching route.
+          pluginBShutdown = true;
+          const matched = matchSkillRoute("/_plugin/echo", "GET");
+          expect(matched).not.toBeNull();
+          expect(matched!.kind).toBe("match");
+        },
+      }),
+    );
+
+    await bootstrapPlugins(fakeCtx);
+
+    // Both plugins' routes landed in the registry; matching returns one of
+    // them (order defined by registration, but we only care that *some*
+    // route matches before shutdown starts).
+    expect(matchSkillRoute("/_plugin/echo", "GET")).not.toBeNull();
+
+    await runShutdownHooks("test-shutdown");
+
+    expect(pluginBShutdown).toBe(true);
+    expect(pluginAShutdown).toBe(true);
+
+    // After both plugins shut down, no routes remain.
+    expect(matchSkillRoute("/_plugin/echo", "GET")).toBeNull();
+  });
+});