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

2026-04-13 18:58:18 -07:00
parent 748db6c605
commit db43409316
3 changed files with 320 additions and 1 deletions
--- a/.fusion/memory.md
+++ b/.fusion/memory.md
@@ -32,7 +32,11 @@
  - Retry/complete/error transitions maintain `projectId` through all lifecycle stages
  - **Background/Resume semantics**: "Send to Background" is non-destructive (closes UI/stream but preserves server session); "Close/Cancel" is explicit abandonment (session deleted). Backgrounding during startup (while "Preparing..." is shown) follows the same pattern—close local stream/UI cleanly without deleting the server session.
 - **Peer Gossip Protocol (FN-1224)**: Nodes exchange peer information via `POST /api/mesh/sync` endpoint. `PeerExchangeService` runs periodic sync cycles (default 60s interval) with all online remote nodes. `CentralCore.mergePeers()` handles peer data merging — new peers are registered via `registerGossipPeer()`, stale peers are updated with fresher data, and the local node is never overwritten. The service uses single-flight pattern to prevent overlapping syncs and refreshes local metrics before each sync.
- **Node Plugin Sync (FN-1246)**: Nodes track version information for plugin synchronization. Central schema v4 adds `versionInfo` and `pluginVersions` columns to the `nodes` table. `getAppVersion()` utility reads from nearest package.json. CentralCore methods: `updateNodeVersionInfo()`, `getNodeVersionInfo()`, `syncPlugins()`, `checkVersionCompatibility()`. Events: `node:version:updated`, `node:plugins:synced`. Key integration points for FN-1247 (API routes, CLI commands).
+- **Node Plugin Sync (FN-1246/FN-1518)**: Nodes track version information for plugin synchronization. Central schema v4 adds `versionInfo` and `pluginVersions` columns to the `nodes` table. `getAppVersion()` utility reads from nearest package.json. CentralCore methods: `updateNodeVersionInfo()`, `getNodeVersionInfo()`, `syncPlugins()`, `checkVersionCompatibility()`. Events: `node:version:updated`, `node:plugins:synced`.
+- **Node Plugin Sync Dashboard Routes (FN-1518)**: Dashboard REST API endpoints for node version info and plugin sync:
+  - `GET /api/nodes/:id/version` — Returns `NodeVersionInfo` when present, `null` when not yet stored. Returns 404 if node doesn't exist.
+  - `POST /api/nodes/:id/sync-plugins` — Compares plugins between local and remote nodes. Returns 400 if target is local (sync is remote-only), 400 if no local node registered, 404 if target missing. Calls `syncPlugins(localNodeId, remoteNodeId)` with argument order: `(localNodeId, remoteNodeId)`.
+  - `GET /api/nodes/:id/compatibility` — Checks version compatibility between local and target nodes. Returns 400 if local node missing, 400 if either version info missing, 404 if target missing. Calls `checkVersionCompatibility(localVersion, remoteVersion)` with version strings (not node IDs).
 - **Plugin Management API Routes (FN-1411)**: Plugin CRUD endpoints implemented in `createApiRoutes` with `getScopedStore(req)` pattern for multi-project support:
  - **Mode discriminator pattern** for POST /plugins: Deterministic behavior via required `mode` field with `"register"` (explicit manifest) or `"install"` (load from path) values. Missing mode, unknown mode, or ambiguous shapes return 400.
  - **Error mapping matrix**: Input/validation → 400, not found (ENOENT) → 404, lifecycle conflicts (EEXISTS) → 409, unexpected → 500.
--- a/packages/dashboard/src/tests/node-routes.test.ts
+++ b/packages/dashboard/src/tests/node-routes.test.ts
@@ -16,6 +16,9 @@ const mockUpdateProject = vi.fn();
 const mockAssignProjectToNode = vi.fn();
 const mockUnassignProjectFromNode = vi.fn();
 const mockGetMeshState = vi.fn();
+const mockGetNodeVersionInfo = vi.fn();
+const mockSyncPlugins = vi.fn();
+const mockCheckVersionCompatibility = vi.fn();

 vi.mock("@fusion/core", async () => {
  const actual = await vi.importActual<typeof import("@fusion/core")>("@fusion/core");
@@ -34,6 +37,9 @@ vi.mock("@fusion/core", async () => {
      assignProjectToNode: mockAssignProjectToNode,
      unassignProjectFromNode: mockUnassignProjectFromNode,
      getMeshState: mockGetMeshState,
+      getNodeVersionInfo: mockGetNodeVersionInfo,
+      syncPlugins: mockSyncPlugins,
+      checkVersionCompatibility: mockCheckVersionCompatibility,
    })),
  };
 });
@@ -137,6 +143,21 @@ describe("Node routes", () => {
      connectedAt: "2026-01-01T00:00:00.000Z",
      knownPeers: [],
    });
+    mockGetNodeVersionInfo.mockResolvedValue(undefined);
+    mockSyncPlugins.mockResolvedValue({
+      localNodeId: "node_local",
+      remoteNodeId: "node_remote",
+      plugins: [],
+      comparedAt: "2026-01-01T00:00:00.000Z",
+      isCompatible: true,
+      summary: "No plugins to compare",
+    });
+    mockCheckVersionCompatibility.mockReturnValue({
+      localVersion: "1.0.0",
+      remoteVersion: "1.0.0",
+      status: "compatible",
+      message: "Versions match",
+    });
  });

  it("GET /api/nodes returns an empty array when no nodes are registered", async () => {
@@ -411,4 +432,169 @@ describe("Node routes", () => {
    expect(mockUnassignProjectFromNode).toHaveBeenCalledWith("proj_123");
    expect(res.body).not.toHaveProperty("nodeId");
  });
+
+  // ── Node Version Routes ────────────────────────────────────────────────
+
+  describe("GET /api/nodes/:id/version", () => {
+    it("returns version info when available", async () => {
+      const versionInfo = {
+        appVersion: "1.2.3",
+        pluginVersions: { "my-plugin": "0.1.0" },
+        lastSyncedAt: "2026-01-01T00:00:00.000Z",
+      };
+      mockGetNode.mockResolvedValue(makeNode({ id: "node_1", versionInfo }));
+
+      const res = await request(app, "GET", "/api/nodes/node_1/version");
+
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual(versionInfo);
+    });
+
+    it("returns null when version info is absent", async () => {
+      mockGetNode.mockResolvedValue(makeNode({ id: "node_2", type: "remote" }));
+      mockGetNodeVersionInfo.mockResolvedValue(undefined);
+
+      const res = await request(app, "GET", "/api/nodes/node_2/version");
+
+      expect(res.status).toBe(200);
+      expect(res.body).toBeNull();
+    });
+
+    it("returns 404 when node is missing", async () => {
+      mockGetNode.mockResolvedValue(undefined);
+
+      const res = await request(app, "GET", "/api/nodes/missing/version");
+
+      expect(res.status).toBe(404);
+    });
+  });
+
+  describe("POST /api/nodes/:id/sync-plugins", () => {
+    it("returns 200 for remote node when local node exists", async () => {
+      const remoteNode = makeNode({ id: "node_remote", name: "remote", type: "remote", url: "http://remote:3001" });
+      const localNode = makeNode({ id: "node_local", name: "local", type: "local" });
+      const syncResult = {
+        localNodeId: "node_local",
+        remoteNodeId: "node_remote",
+        plugins: [],
+        comparedAt: "2026-01-01T00:00:00.000Z",
+        isCompatible: true,
+        summary: "No plugins to compare",
+      };
+
+      mockGetNode.mockResolvedValue(remoteNode);
+      mockListNodes.mockResolvedValue([localNode, remoteNode]);
+      mockSyncPlugins.mockResolvedValue(syncResult);
+
+      const res = await request(app, "POST", "/api/nodes/node_remote/sync-plugins");
+
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual(syncResult);
+      expect(mockSyncPlugins).toHaveBeenCalledWith("node_local", "node_remote");
+    });
+
+    it("returns 400 when target node is local", async () => {
+      const localNode = makeNode({ id: "node_local", name: "local", type: "local" });
+      mockGetNode.mockResolvedValue(localNode);
+
+      const res = await request(app, "POST", "/api/nodes/node_local/sync-plugins");
+
+      expect(res.status).toBe(400);
+      expect(res.body).toEqual({ error: "Cannot sync plugins to a local node - sync-plugins is for remote nodes only" });
+    });
+
+    it("returns 400 when no local node exists", async () => {
+      const remoteNode = makeNode({ id: "node_remote", name: "remote", type: "remote", url: "http://remote:3001" });
+      mockGetNode.mockResolvedValue(remoteNode);
+      mockListNodes.mockResolvedValue([remoteNode]); // No local node
+
+      const res = await request(app, "POST", "/api/nodes/node_remote/sync-plugins");
+
+      expect(res.status).toBe(400);
+      expect(res.body).toEqual({ error: "Local node not registered - cannot perform sync" });
+    });
+
+    it("returns 404 when target node is missing", async () => {
+      mockGetNode.mockResolvedValue(undefined);
+
+      const res = await request(app, "POST", "/api/nodes/missing/sync-plugins");
+
+      expect(res.status).toBe(404);
+    });
+  });
+
+  describe("GET /api/nodes/:id/compatibility", () => {
+    it("returns 200 when both local and target versions are available", async () => {
+      const localNode = makeNode({ id: "node_local", name: "local", type: "local" });
+      const remoteNode = makeNode({ id: "node_remote", name: "remote", type: "remote", url: "http://remote:3001" });
+      const compatibilityResult = {
+        localVersion: "1.0.0",
+        remoteVersion: "1.1.0",
+        status: "minor-difference",
+        message: "Minor version difference: local 1.0.0 vs remote 1.1.0",
+      };
+
+      mockGetNode.mockResolvedValue(remoteNode);
+      mockListNodes.mockResolvedValue([localNode, remoteNode]);
+      mockGetNodeVersionInfo
+        .mockResolvedValueOnce({ appVersion: "1.0.0", pluginVersions: {}, lastSyncedAt: "2026-01-01T00:00:00.000Z" })
+        .mockResolvedValueOnce({ appVersion: "1.1.0", pluginVersions: {}, lastSyncedAt: "2026-01-01T00:00:00.000Z" });
+      mockCheckVersionCompatibility.mockReturnValue(compatibilityResult);
+
+      const res = await request(app, "GET", "/api/nodes/node_remote/compatibility");
+
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual(compatibilityResult);
+      expect(mockCheckVersionCompatibility).toHaveBeenCalledWith("1.0.0", "1.1.0");
+    });
+
+    it("returns 400 when local node is missing", async () => {
+      const remoteNode = makeNode({ id: "node_remote", name: "remote", type: "remote", url: "http://remote:3001" });
+      mockGetNode.mockResolvedValue(remoteNode);
+      mockListNodes.mockResolvedValue([remoteNode]); // No local node
+
+      const res = await request(app, "GET", "/api/nodes/node_remote/compatibility");
+
+      expect(res.status).toBe(400);
+      expect(res.body).toEqual({ error: "Local node not registered - cannot check compatibility" });
+    });
+
+    it("returns 400 when local version info is missing", async () => {
+      const localNode = makeNode({ id: "node_local", name: "local", type: "local" });
+      const remoteNode = makeNode({ id: "node_remote", name: "remote", type: "remote", url: "http://remote:3001" });
+      mockGetNode.mockResolvedValue(remoteNode);
+      mockListNodes.mockResolvedValue([localNode, remoteNode]);
+      mockGetNodeVersionInfo
+        .mockResolvedValueOnce(undefined) // No version info for local
+        .mockResolvedValueOnce({ appVersion: "1.1.0", pluginVersions: {}, lastSyncedAt: "2026-01-01T00:00:00.000Z" });
+
+      const res = await request(app, "GET", "/api/nodes/node_remote/compatibility");
+
+      expect(res.status).toBe(400);
+      expect(res.body).toEqual({ error: "Local node has no version info yet" });
+    });
+
+    it("returns 400 when target version info is missing", async () => {
+      const localNode = makeNode({ id: "node_local", name: "local", type: "local" });
+      const remoteNode = makeNode({ id: "node_remote", name: "remote", type: "remote", url: "http://remote:3001" });
+      mockGetNode.mockResolvedValue(remoteNode);
+      mockListNodes.mockResolvedValue([localNode, remoteNode]);
+      mockGetNodeVersionInfo
+        .mockResolvedValueOnce({ appVersion: "1.0.0", pluginVersions: {}, lastSyncedAt: "2026-01-01T00:00:00.000Z" })
+        .mockResolvedValueOnce(undefined); // No version info for remote
+
+      const res = await request(app, "GET", "/api/nodes/node_remote/compatibility");
+
+      expect(res.status).toBe(400);
+      expect(res.body).toEqual({ error: "Target node has no version info yet" });
+    });
+
+    it("returns 404 when target node is missing", async () => {
+      mockGetNode.mockResolvedValue(undefined);
+
+      const res = await request(app, "GET", "/api/nodes/missing/compatibility");
+
+      expect(res.status).toBe(404);
+    });
+  });
 });
--- a/packages/dashboard/src/routes.ts
+++ b/packages/dashboard/src/routes.ts
@@ -13103,6 +13103,135 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
    }
  });

+  /**
+   * GET /api/nodes/:id/version
+   * Get version information for a node.
+   * Returns NodeVersionInfo when present, null when no version info has been stored yet.
+   */
+  router.get("/nodes/:id/version", async (req, res) => {
+    try {
+      const { CentralCore } = await import("@fusion/core");
+      const central = new CentralCore();
+      await central.init();
+
+      const node = await central.getNode(req.params.id);
+      await central.close();
+
+      if (!node) {
+        throw notFound("Node not found");
+      }
+
+      // Return versionInfo if present, null if not yet stored
+      res.json(node.versionInfo ?? null);
+    } catch (err: any) {
+      if (err instanceof ApiError) {
+        throw err;
+      }
+      rethrowAsApiError(err);
+    }
+  });
+
+  /**
+   * POST /api/nodes/:id/sync-plugins
+   * Compare plugin versions between the local node and a remote node.
+   * Returns PluginSyncResult with recommendations for each plugin.
+   */
+  router.post("/nodes/:id/sync-plugins", async (req, res) => {
+    try {
+      const { CentralCore } = await import("@fusion/core");
+      const central = new CentralCore();
+      await central.init();
+
+      // Validate target node exists
+      const targetNode = await central.getNode(req.params.id);
+      if (!targetNode) {
+        await central.close();
+        throw notFound("Node not found");
+      }
+
+      // Reject local target nodes - sync-plugins is for remote nodes only
+      if (targetNode.type === "local") {
+        await central.close();
+        throw badRequest("Cannot sync plugins to a local node - sync-plugins is for remote nodes only");
+      }
+
+      // Find the local node
+      const nodes = await central.listNodes();
+      const localNode = nodes.find((n) => n.type === "local");
+      if (!localNode) {
+        await central.close();
+        throw badRequest("Local node not registered - cannot perform sync");
+      }
+
+      // Perform plugin sync comparison
+      const result = await central.syncPlugins(localNode.id, targetNode.id);
+      await central.close();
+
+      res.json(result);
+    } catch (err: any) {
+      if (err instanceof ApiError) {
+        throw err;
+      }
+      rethrowAsApiError(err);
+    }
+  });
+
+  /**
+   * GET /api/nodes/:id/compatibility
+   * Check version compatibility between the local node and a target node.
+   * Returns VersionCompatibilityResult based on app version comparison.
+   */
+  router.get("/nodes/:id/compatibility", async (req, res) => {
+    try {
+      const { CentralCore } = await import("@fusion/core");
+      const central = new CentralCore();
+      await central.init();
+
+      // Validate target node exists
+      const targetNode = await central.getNode(req.params.id);
+      if (!targetNode) {
+        await central.close();
+        throw notFound("Node not found");
+      }
+
+      // Find the local node
+      const nodes = await central.listNodes();
+      const localNode = nodes.find((n) => n.type === "local");
+      if (!localNode) {
+        await central.close();
+        throw badRequest("Local node not registered - cannot check compatibility");
+      }
+
+      // Get version info for both nodes
+      const localVersionInfo = await central.getNodeVersionInfo(localNode.id);
+      const targetVersionInfo = await central.getNodeVersionInfo(targetNode.id);
+
+      // Validate both have version info
+      if (!localVersionInfo) {
+        await central.close();
+        throw badRequest("Local node has no version info yet");
+      }
+      if (!targetVersionInfo) {
+        await central.close();
+        throw badRequest("Target node has no version info yet");
+      }
+
+      // Check compatibility using version strings
+      const result = central.checkVersionCompatibility(
+        localVersionInfo.appVersion,
+        targetVersionInfo.appVersion,
+      );
+      await central.close();
+
+      res.json(result);
+    } catch (err: any) {
+      if (err instanceof ApiError) {
+        throw err;
+      }
+      rethrowAsApiError(err);
+    }
+  });
+
  // ── Mesh Topology Routes ────────────────────────────────────────────────

  /**