feat(FN-2260): merge fusion/fn-2260

plugins/fusion-plugin-paperclip-runtime/src/__tests__/index.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import plugin from "../index.js";
+
+// ── Test Suite ─────────────────────────────────────────────────────────────────
+
+describe("paperclip-runtime plugin", () => {
+  describe("plugin manifest identity", () => {
+    it("should export a valid FusionPlugin with correct manifest fields", () => {
+      expect(plugin.manifest.id).toBe("fusion-plugin-paperclip-runtime");
+      expect(plugin.manifest.name).toBe("Paperclip Runtime Plugin");
+      expect(plugin.manifest.version).toBe("0.1.0");
+      expect(plugin.manifest.description).toBe(
+        "Provides Paperclip web access runtime for Fusion AI agents",
+      );
+      expect(plugin.manifest.author).toBe("Fusion Team");
+      expect(plugin.state).toBe("installed");
+    });
+
+    it("should have runtime manifest metadata matching manifest.json", () => {
+      expect(plugin.manifest.runtime).toBeDefined();
+      expect(plugin.manifest.runtime!.runtimeId).toBe("paperclip");
+      expect(plugin.manifest.runtime!.name).toBe("Paperclip Runtime");
+      expect(plugin.manifest.runtime!.version).toBe("0.1.0");
+    });
+
+    it("should have fusionVersion requirement", () => {
+      expect(plugin.manifest.fusionVersion).toBe(">=0.1.0");
+    });
+  });
+
+  describe("runtime placeholder registration", () => {
+    it("should have runtime registration", () => {
+      expect(plugin.runtime).toBeDefined();
+    });
+
+    it("should have correct runtime metadata", () => {
+      const runtime = plugin.runtime!;
+      expect(runtime.metadata.runtimeId).toBe("paperclip");
+      expect(runtime.metadata.name).toBe("Paperclip Runtime");
+      expect(runtime.metadata.version).toBe("0.1.0");
+    });
+
+    it("should have a factory function", () => {
+      expect(plugin.runtime!.factory).toBeDefined();
+      expect(typeof plugin.runtime!.factory).toBe("function");
+    });
+  });
+
+  describe("runtime placeholder invocation", () => {
+    it("should throw deterministic error with FN-2261 reference when factory is invoked", async () => {
+      const factory = plugin.runtime!.factory;
+
+      await expect(factory({} as any)).rejects.toThrow(
+        "Paperclip runtime implementation is deferred to FN-2261",
+      );
+    });
+
+    it("should throw error with placeholder message in the error text", async () => {
+      const factory = plugin.runtime!.factory;
+
+      try {
+        await factory({} as any);
+        expect.fail("Expected factory to throw an error");
+      } catch (error) {
+        expect((error as Error).message).toContain("placeholder");
+        expect((error as Error).message).toContain("FN-2261");
+      }
+    });
+  });
+
+  describe("hooks", () => {
+    it("should have onLoad hook", () => {
+      expect(plugin.hooks.onLoad).toBeDefined();
+      expect(typeof plugin.hooks.onLoad).toBe("function");
+    });
+
+    it("onLoad should not throw when called with valid context", () => {
+      const mockLogger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+      };
+      const mockCtx = {
+        pluginId: "fusion-plugin-paperclip-runtime",
+        settings: {},
+        logger: mockLogger,
+        emitEvent: () => {},
+        taskStore: {},
+      };
+
+      expect(() => plugin.hooks.onLoad!(mockCtx as any)).not.toThrow();
+    });
+  });
+});

plugins/fusion-plugin-paperclip-runtime/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Paperclip Runtime Plugin
+ *
+ * Provides the Paperclip web access runtime for Fusion AI agents.
+ * This is a placeholder implementation — full runtime behavior is deferred to FN-2261.
+ */
+
+import { definePlugin } from "@fusion/plugin-sdk";
+import type {
+  FusionPlugin,
+  PluginRuntimeRegistration,
+} from "@fusion/plugin-sdk";
+
+// ── Runtime Placeholder ────────────────────────────────────────────────────────
+
+/**
+ * Deferred implementation error message for Paperclip runtime.
+ * This message is thrown when the runtime factory is invoked before
+ * full implementation is complete (FN-2261).
+ */
+const DEFERRED_ERROR_MESSAGE =
+  "Paperclip runtime implementation is deferred to FN-2261. " +
+  "This is a placeholder plugin — runtime creation is not yet available.";
+
+/**
+ * Paperclip runtime factory placeholder.
+ *
+ * Throws a deterministic error indicating that the full Paperclip runtime
+ * implementation has not been completed yet.
+ *
+ * @throws Error with DEFERRED_ERROR_MESSAGE when invoked
+ */
+async function paperclipRuntimeFactory(): Promise<never> {
+  throw new Error(DEFERRED_ERROR_MESSAGE);
+}
+
+/**
+ * Paperclip runtime registration for Fusion's plugin runtime system.
+ * Uses the PluginRuntimeRegistration contract from FN-2256.
+ */
+const paperclipRuntime: PluginRuntimeRegistration = {
+  metadata: {
+    runtimeId: "paperclip",
+    name: "Paperclip Runtime",
+    description:
+      "Web access runtime for AI agents — browse pages and extract content using headless browser automation",
+    version: "0.1.0",
+  },
+  factory: paperclipRuntimeFactory,
+};
+
+// ── Plugin Definition ─────────────────────────────────────────────────────────
+
+const plugin: FusionPlugin = definePlugin({
+  manifest: {
+    id: "fusion-plugin-paperclip-runtime",
+    name: "Paperclip Runtime Plugin",
+    version: "0.1.0",
+    description: "Provides Paperclip web access runtime for Fusion AI agents",
+    author: "Fusion Team",
+    homepage: "https://github.com/gsxdsm/fusion",
+    fusionVersion: ">=0.1.0",
+    runtime: {
+      runtimeId: "paperclip",
+      name: "Paperclip Runtime",
+      description:
+        "Web access runtime for AI agents — browse pages and extract content",
+      version: "0.1.0",
+    },
+  },
+  state: "installed",
+  runtime: paperclipRuntime,
+  hooks: {
+    onLoad: (ctx) => {
+      ctx.logger.info(
+        "Paperclip Runtime Plugin loaded (placeholder — implementation deferred to FN-2261)",
+      );
+    },
+  },
+});
+
+export default plugin;