feat(FN-3573): harden plugin setup sync and test-isolation handling

- Add plugin setup API coverage for migration and sync edge cases
- Expand plugin route tests and implementation safeguards for setup state handling
- Update legacy API glue to align plugin setup responses with route behavior
- Keep test-isolation runtime ignore handling compatible with live app activity

Fusion-Task-Id: FN-3573

packages/dashboard/app/api/__tests__/plugin-setup-api.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fetchPluginSetupStatus, installPluginSetup } from "../../api";
+
+describe("plugin setup API helpers", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("fetchPluginSetupStatus calls setup-status endpoint with encoded id", async () => {
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ hasSetup: true, status: "installed" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+
+    const result = await fetchPluginSetupStatus("plugin/id");
+
+    expect(result).toEqual({ hasSetup: true, status: "installed" });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/plugins/plugin%2Fid/setup-status",
+      expect.objectContaining({
+        headers: expect.objectContaining({ "Content-Type": "application/json" }),
+      }),
+    );
+  });
+
+  it("fetchPluginSetupStatus includes projectId query parameter", async () => {
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ hasSetup: false }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+
+    await fetchPluginSetupStatus("my-plugin", "project/one");
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/plugins/my-plugin/setup-status?projectId=project%2Fone",
+      expect.any(Object),
+    );
+  });
+
+  it("installPluginSetup posts to setup install endpoint and supports project scope", async () => {
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ success: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+
+    const result = await installPluginSetup("my plugin", "proj");
+
+    expect(result).toEqual({ success: true });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/plugins/my%20plugin/setup/install?projectId=proj",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+});

packages/dashboard/app/api/legacy.ts

@@ -18,6 +18,7 @@ import type {
   WorkflowStepInput,
   WorkflowStepResult,
   PluginInstallation,
+  PluginSetupCheckResult,
   PluginUiSlotDefinition,
   PluginUiContributionDefinition,
   PluginDashboardViewDefinition,
@@ -7763,6 +7764,23 @@ export async function updatePluginSettings(
   });
 }
 
+export type PluginSetupStatusResponse =
+  | { hasSetup: false }
+  | { hasSetup: false; status: Extract<PluginSetupCheckResult, { status: "error" }> }
+  | ({ hasSetup: true } & PluginSetupCheckResult);
+
+/** Fetch plugin setup status */
+export async function fetchPluginSetupStatus(id: string, projectId?: string): Promise<PluginSetupStatusResponse> {
+  return api<PluginSetupStatusResponse>(withProjectId(`/plugins/${encodeURIComponent(id)}/setup-status`, projectId));
+}
+
+/** Trigger plugin setup install hook */
+export async function installPluginSetup(id: string, projectId?: string): Promise<{ success: boolean; error?: string }> {
+  return api<{ success: boolean; error?: string }>(withProjectId(`/plugins/${encodeURIComponent(id)}/setup/install`, projectId), {
+    method: "POST",
+  });
+}
+
 /** Reload a running plugin with updated code */
 export async function reloadPlugin(id: string, projectId?: string): Promise<PluginInstallation> {
   return api<PluginInstallation>(withProjectId(`/plugins/${encodeURIComponent(id)}/reload`, projectId), {

packages/dashboard/src/__tests__/plugin-routes.test.ts

@@ -17,6 +17,7 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import express from "express";
 import type { TaskStore, PluginStore, PluginLoader, PluginInstallation } from "@fusion/core";
 import { createApiRoutes } from "../routes.js";
+import { createPluginRouter } from "../plugin-routes.js";
 import { get as performGet, request as performRequest } from "../test-request.js";
 import * as projectStoreResolver from "../project-store-resolver.js";
 
@@ -978,6 +979,122 @@ describe("GET /api/plugins/ui-contributions", () => {
   });
 });
 
+describe("createPluginRouter plugin setup routes", () => {
+  let pluginStore: PluginStore;
+  let pluginLoader: PluginLoader;
+  let pluginRunner: {
+    getPluginRoutes: ReturnType<typeof vi.fn>;
+    checkPluginSetup: ReturnType<typeof vi.fn>;
+    installPluginSetup: ReturnType<typeof vi.fn>;
+    getPluginSetupInfo: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    pluginStore = createMockPluginStore();
+    pluginLoader = createMockPluginLoader();
+    pluginRunner = {
+      getPluginRoutes: vi.fn().mockReturnValue([]),
+      checkPluginSetup: vi.fn().mockResolvedValue({ status: "installed", version: "1.0.0" }),
+      installPluginSetup: vi.fn().mockResolvedValue({ success: true }),
+      getPluginSetupInfo: vi.fn().mockReturnValue([]),
+    };
+  });
+
+  function buildApp() {
+    const app = express();
+    app.use(express.json());
+    app.use("/plugins", createPluginRouter(pluginStore, pluginLoader, pluginRunner));
+    return app;
+  }
+
+  it("returns 404 for missing plugin setup status", async () => {
+    (pluginStore.getPlugin as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error("Plugin \"missing\" not found"));
+
+    const res = await REQUEST(buildApp(), "GET", "/plugins/missing/setup-status");
+
+    expect(res.status).toBe(404);
+  });
+
+  it("returns hasSetup false when plugin has no setup metadata", async () => {
+    (pluginStore.getPlugin as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ ...INSTALLED_PLUGIN, state: "started" });
+    pluginRunner.getPluginSetupInfo.mockReturnValueOnce([]);
+
+    const res = await REQUEST(buildApp(), "GET", "/plugins/my-plugin/setup-status");
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ hasSetup: false });
+  });
+
+  it("returns plugin not loaded status when setup metadata exists but plugin is stopped", async () => {
+    (pluginStore.getPlugin as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ ...INSTALLED_PLUGIN, state: "installed" });
+    pluginRunner.getPluginSetupInfo.mockReturnValueOnce([
+      {
+        pluginId: "my-plugin",
+        manifest: { binaryName: "tool", description: "desc" },
+        hooks: { checkSetup: vi.fn() },
+      },
+    ]);
+
+    const res = await REQUEST(buildApp(), "GET", "/plugins/my-plugin/setup-status");
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      hasSetup: false,
+      status: { status: "error", error: "Plugin not loaded" },
+    });
+  });
+
+  it("returns setup status when setup metadata exists and plugin is started", async () => {
+    (pluginStore.getPlugin as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ ...INSTALLED_PLUGIN, state: "started" });
+    pluginRunner.getPluginSetupInfo.mockReturnValueOnce([
+      {
+        pluginId: "my-plugin",
+        manifest: { binaryName: "tool", description: "desc" },
+        hooks: { checkSetup: vi.fn() },
+      },
+    ]);
+
+    const res = await REQUEST(buildApp(), "GET", "/plugins/my-plugin/setup-status");
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ hasSetup: true, status: "installed", version: "1.0.0" });
+  });
+
+  it("rejects setup install when plugin has no install hook", async () => {
+    (pluginStore.getPlugin as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ ...INSTALLED_PLUGIN, enabled: true });
+    pluginRunner.getPluginSetupInfo.mockReturnValueOnce([
+      {
+        pluginId: "my-plugin",
+        manifest: { binaryName: "tool", description: "desc" },
+        hooks: { checkSetup: vi.fn() },
+      },
+    ]);
+
+    const res = await REQUEST(buildApp(), "POST", "/plugins/my-plugin/setup/install", {});
+
+    expect(res.status).toBe(400);
+    expect(res.body.error).toContain("no install hook");
+  });
+
+  it("returns setup install result payload", async () => {
+    (pluginStore.getPlugin as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ ...INSTALLED_PLUGIN, enabled: true });
+    pluginRunner.getPluginSetupInfo.mockReturnValueOnce([
+      {
+        pluginId: "my-plugin",
+        manifest: { binaryName: "tool", description: "desc" },
+        hooks: { checkSetup: vi.fn(), install: vi.fn() },
+      },
+    ]);
+    pluginRunner.installPluginSetup.mockResolvedValueOnce({ success: false, error: "install failed" });
+
+    const res = await REQUEST(buildApp(), "POST", "/plugins/my-plugin/setup/install", {});
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ success: false, error: "install failed" });
+  });
+});
+
 describe("GET /api/plugins/runtimes", () => {
   let pluginStore: PluginStore;
   let pluginLoader: PluginLoader;

packages/dashboard/src/plugin-routes.ts

@@ -196,10 +196,6 @@ export function createPluginRouter(
 ): Router {
   const router = Router();
 
-  // ── Error Handler ───────────────────────────────────────────────
-
-  router.use(catchHandler);
-
   // ── Management Routes ───────────────────────────────────────────
 
   /**
@@ -366,6 +362,88 @@ export function createPluginRouter(
     res.json(updatedPlugin);
   }));
 
+  /**
+   * GET /plugins/:id/setup-status
+   * Check plugin setup status.
+   */
+  router.get("/:id/setup-status", catchHandler(async (req: Request, res: Response) => {
+    const id = req.params.id as string;
+
+    let plugin: import("@fusion/core").PluginInstallation;
+    try {
+      plugin = await pluginStore.getPlugin(id);
+    } catch (err: unknown) {
+      if (
+        (err as NodeJS.ErrnoException).code === "ENOENT"
+        || (err instanceof Error && err.message.includes("not found"))
+      ) {
+        throw notFound(`Plugin "${id}" not found`);
+      }
+      throw internalError(err instanceof Error ? err.message : "Unknown error");
+    }
+
+    if (!pluginRunner?.checkPluginSetup || !pluginRunner.getPluginSetupInfo) {
+      throw internalError("Plugin runner not available");
+    }
+
+    const setupInfo = pluginRunner.getPluginSetupInfo();
+    const hasSetup = setupInfo.some((entry) => entry.pluginId === id);
+
+    if (!hasSetup) {
+      res.json({ hasSetup: false });
+      return;
+    }
+
+    if (plugin.state !== "started") {
+      res.json({
+        hasSetup: false,
+        status: { status: "error", error: "Plugin not loaded" },
+      });
+      return;
+    }
+
+    const status = await pluginRunner.checkPluginSetup(id);
+    res.json({ hasSetup: true, ...status });
+  }));
+
+  /**
+   * POST /plugins/:id/setup/install
+   * Trigger plugin setup install hook.
+   */
+  router.post("/:id/setup/install", catchHandler(async (req: Request, res: Response) => {
+    const id = req.params.id as string;
+
+    let plugin: import("@fusion/core").PluginInstallation;
+    try {
+      plugin = await pluginStore.getPlugin(id);
+    } catch (err: unknown) {
+      if (
+        (err as NodeJS.ErrnoException).code === "ENOENT"
+        || (err instanceof Error && err.message.includes("not found"))
+      ) {
+        throw notFound(`Plugin "${id}" not found`);
+      }
+      throw internalError(err instanceof Error ? err.message : "Unknown error");
+    }
+
+    if (!plugin.enabled) {
+      throw badRequest("Plugin must be enabled before setup install");
+    }
+
+    if (!pluginRunner?.installPluginSetup || !pluginRunner.getPluginSetupInfo) {
+      throw internalError("Plugin runner not available");
+    }
+
+    const setupInfo = pluginRunner.getPluginSetupInfo();
+    const setup = setupInfo.find((entry) => entry.pluginId === id);
+    if (!setup?.hooks.install) {
+      throw badRequest("Plugin has no install hook");
+    }
+
+    const result = await pluginRunner.installPluginSetup(id);
+    res.json(result ?? { success: true });
+  }));
+
   /**
    * DELETE /plugins/:id
    * Uninstall a plugin.