test(pluggable-widgets-mcp): add vitest infrastructure and unit tests

Adds vitest config, MCP test harness (in-memory transport), temp directory
helpers, and 55 unit tests covering config validation, security guardrails,
project tools, scaffolding/build sandbox, session state, MPK finder, and
response utilities.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rahmanunver

packages/pluggable-widgets-mcp/src/__test-utils__/mcp-test-harness.ts

@@ -0,0 +1,67 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SessionState } from "@/tools/session-state";
+
+type ToolRegistrationFn = (server: McpServer, state: SessionState) => void;
+
+interface McpTestContext {
+    server: McpServer;
+    client: Client;
+    state: SessionState;
+    cleanup: () => Promise<void>;
+}
+
+/**
+ * Creates an MCP server + client pair connected via InMemoryTransport.
+ * By default registers `registerProjectTools`; callers can pass custom registration functions.
+ */
+export function getResultText(result: Awaited<ReturnType<Client["callTool"]>>): string {
+    if ("content" in result && Array.isArray(result.content)) {
+        return result.content
+            .filter((c): c is { type: "text"; text: string } => c.type === "text")
+            .map(c => c.text)
+            .join("\n");
+    }
+    return "";
+}
+
+export function isError(result: Awaited<ReturnType<Client["callTool"]>>): boolean {
+    return "isError" in result && result.isError === true;
+}
+
+export async function createMcpTestContext(...registerFns: ToolRegistrationFn[]): Promise<McpTestContext> {
+    const state: SessionState = { projectDir: undefined };
+
+    const server = new McpServer(
+        { name: "test-server", version: "0.0.0" },
+        { capabilities: { tools: {}, logging: {} } }
+    );
+
+    // Register tools — default to project tools if none provided
+    if (registerFns.length === 0) {
+        const { registerProjectTools } = await import("@/tools/project.tools");
+        registerProjectTools(server, state);
+    } else {
+        for (const fn of registerFns) {
+            fn(server, state);
+        }
+    }
+
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    const client = new Client({ name: "test-client", version: "0.0.0" });
+
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+
+    return {
+        server,
+        client,
+        state,
+        cleanup: async () => {
+            await client.close();
+            await server.close();
+        }
+    };
+}

packages/pluggable-widgets-mcp/src/__test-utils__/temp-dir.ts

@@ -0,0 +1,76 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+interface TempMendixProjectOptions {
+    projectName?: string;
+    widgets?: string[];
+    skipMpr?: boolean;
+    skipWidgetsDir?: boolean;
+}
+
+interface TempWidgetOptions {
+    mpkName?: string;
+    versionDir?: string;
+    noMpk?: boolean;
+    noDist?: boolean;
+}
+
+interface TempDirResult {
+    dir: string;
+    cleanup: () => void;
+}
+
+/**
+ * Creates a temp directory that looks like a Mendix project.
+ * Includes a .mpr file and optionally a widgets/ dir with .mpk files.
+ */
+export function createTempMendixProject(opts: TempMendixProjectOptions = {}): TempDirResult {
+    const dir = mkdtempSync(join(tmpdir(), "mcp-test-project-"));
+    const projectName = opts.projectName ?? "TestProject";
+
+    if (!opts.skipMpr) {
+        writeFileSync(join(dir, `${projectName}.mpr`), "");
+    }
+
+    if (!opts.skipWidgetsDir) {
+        const widgetsDir = join(dir, "widgets");
+        mkdirSync(widgetsDir, { recursive: true });
+
+        if (opts.widgets) {
+            for (const w of opts.widgets) {
+                writeFileSync(join(widgetsDir, w), "");
+            }
+        }
+    }
+
+    return {
+        dir,
+        cleanup: () => rmSync(dir, { recursive: true, force: true })
+    };
+}
+
+/**
+ * Creates a temp directory that looks like a built widget.
+ * Includes a dist/ dir with an optional .mpk file (possibly nested in a version dir).
+ */
+export function createTempWidgetWithMpk(opts: TempWidgetOptions = {}): TempDirResult {
+    const dir = mkdtempSync(join(tmpdir(), "mcp-test-widget-"));
+    const mpkName = opts.mpkName ?? "TestWidget.mpk";
+
+    if (!opts.noDist) {
+        const distDir = join(dir, "dist");
+        mkdirSync(distDir, { recursive: true });
+
+        if (!opts.noMpk) {
+            const mpkDir = opts.versionDir ? join(distDir, opts.versionDir) : distDir;
+            mkdirSync(mpkDir, { recursive: true });
+            writeFileSync(join(mpkDir, mpkName), "fake-mpk-content");
+        }
+    }
+
+    return {
+        dir,
+        cleanup: () => rmSync(dir, { recursive: true, force: true })
+    };
+}

packages/pluggable-widgets-mcp/src/__tests__/config.test.ts

@@ -0,0 +1,70 @@
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+import { afterEach, describe, expect, it } from "vitest";
+import { validateProjectDir } from "@/config";
+import { createTempMendixProject } from "@/__test-utils__/temp-dir";
+
+describe("validateProjectDir", () => {
+    const cleanups: Array<() => void> = [];
+
+    afterEach(() => {
+        for (const cleanup of cleanups) cleanup();
+        cleanups.length = 0;
+    });
+
+    it("returns invalid for a non-existent directory", async () => {
+        const result = await validateProjectDir("/nonexistent/path/to/project");
+        expect(result.valid).toBe(false);
+        expect(result.error).toContain("does not exist");
+    });
+
+    it("returns invalid when directory has no .mpr file", async () => {
+        const { dir, cleanup } = createTempMendixProject({ skipMpr: true });
+        cleanups.push(cleanup);
+        const result = await validateProjectDir(dir);
+        expect(result.valid).toBe(false);
+        expect(result.error).toContain("No .mpr file");
+    });
+
+    it("returns valid with correct projectName for a proper Mendix project", async () => {
+        const { dir, cleanup } = createTempMendixProject({ projectName: "MyApp" });
+        cleanups.push(cleanup);
+        const result = await validateProjectDir(dir);
+        expect(result.valid).toBe(true);
+        expect(result.projectName).toBe("MyApp");
+    });
+
+    it("sets widgetsDir to <dir>/widgets", async () => {
+        const { dir, cleanup } = createTempMendixProject();
+        cleanups.push(cleanup);
+        const result = await validateProjectDir(dir);
+        expect(result.widgetsDir).toBe(join(dir, "widgets"));
+    });
+
+    it("lists .mpk files from widgets/ directory", async () => {
+        const { dir, cleanup } = createTempMendixProject({
+            widgets: ["Foo.mpk", "Bar.mpk"]
+        });
+        cleanups.push(cleanup);
+        const result = await validateProjectDir(dir);
+        expect(result.existingWidgets).toContain("Foo.mpk");
+        expect(result.existingWidgets).toContain("Bar.mpk");
+    });
+
+    it("returns empty existingWidgets when widgets/ dir does not exist", async () => {
+        const { dir, cleanup } = createTempMendixProject({ skipWidgetsDir: true });
+        cleanups.push(cleanup);
+        const result = await validateProjectDir(dir);
+        expect(result.valid).toBe(true);
+        expect(result.existingWidgets).toEqual([]);
+    });
+
+    it("filters out non-.mpk files from widgets/", async () => {
+        const { dir, cleanup } = createTempMendixProject({ widgets: ["Widget.mpk"] });
+        cleanups.push(cleanup);
+        // Add a non-mpk file
+        writeFileSync(join(dir, "widgets", "readme.txt"), "not a widget");
+        const result = await validateProjectDir(dir);
+        expect(result.existingWidgets).toEqual(["Widget.mpk"]);
+    });
+});

packages/pluggable-widgets-mcp/src/security/__tests__/guardrails.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { isPathWithinDirectory, isExtensionAllowed, validateFilePath } from "@/security/guardrails";
+
+describe("isPathWithinDirectory", () => {
+    it("returns true for a path within the base directory", () => {
+        expect(isPathWithinDirectory("/widgets/foo", "src/Bar.tsx")).toBe(true);
+    });
+
+    it("returns true for a nested path within the base directory", () => {
+        expect(isPathWithinDirectory("/widgets/foo", "src/components/deep/Bar.tsx")).toBe(true);
+    });
+
+    it("returns false for .. traversal escaping the base", () => {
+        expect(isPathWithinDirectory("/widgets/foo", "../../../etc/passwd")).toBe(false);
+    });
+
+    it("returns false for a sibling directory (foobar vs foo)", () => {
+        // /widgets/foobar is NOT within /widgets/foo (prefix attack)
+        expect(isPathWithinDirectory("/widgets/foo", "../foobar/secret.txt")).toBe(false);
+    });
+});
+
+describe("isExtensionAllowed", () => {
+    it.each([".tsx", ".ts", ".xml", ".scss", ".json"])("allows %s extension", ext => {
+        expect(isExtensionAllowed(`Component${ext}`)).toBe(true);
+    });
+
+    it.each([".exe", ".sh"])("rejects %s extension", ext => {
+        expect(isExtensionAllowed(`script${ext}`)).toBe(false);
+    });
+
+    it("allows .gitignore (dot-file in allowlist)", () => {
+        expect(isExtensionAllowed(".gitignore")).toBe(true);
+    });
+
+    it("allows extensionless config files like tsconfig", () => {
+        expect(isExtensionAllowed("tsconfig")).toBe(true);
+    });
+});
+
+describe("validateFilePath", () => {
+    it("does not throw for a valid path without extension check", () => {
+        expect(() => validateFilePath("/widgets/foo", "src/Bar.tsx")).not.toThrow();
+    });
+
+    it("throws for .. in the path", () => {
+        expect(() => validateFilePath("/widgets/foo", "../secret.txt")).toThrow("Path traversal");
+    });
+
+    it("throws for disallowed extension when checkExtension is true", () => {
+        expect(() => validateFilePath("/widgets/foo", "src/script.exe", true)).toThrow("extension not allowed");
+    });
+});

packages/pluggable-widgets-mcp/src/tools/__tests__/build.tools.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createMcpTestContext, getResultText, isError } from "@/__test-utils__/mcp-test-harness";
+import { createTempMendixProject } from "@/__test-utils__/temp-dir";
+import { registerBuildTools } from "@/tools/build.tools";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { SessionState } from "@/tools/session-state";
+
+describe("build-widget sandbox expansion", () => {
+    let client: Client;
+    let state: SessionState;
+    let cleanup: () => Promise<void>;
+    const tempCleanups: Array<() => void> = [];
+
+    beforeEach(async () => {
+        ({ client, state, cleanup } = await createMcpTestContext(registerBuildTools));
+    });
+
+    afterEach(async () => {
+        await cleanup();
+        for (const c of tempCleanups) c();
+        tempCleanups.length = 0;
+    });
+
+    it("rejects widget path outside allowed directories", async () => {
+        // Create a real temp dir (must exist to pass the existsSync check)
+        const rogueDir = mkdtempSync(join(tmpdir(), "mcp-test-rogue-"));
+        tempCleanups.push(() => rmSync(rogueDir, { recursive: true, force: true }));
+        state.projectDir = undefined;
+        const result = await client.callTool({
+            name: "build-widget",
+            arguments: { widgetPath: rogueDir }
+        });
+        const text = getResultText(result);
+        expect(isError(result)).toBe(true);
+        expect(text).toContain("not within an allowed directory");
+    });
+
+    it("allows widget path within state.projectDir", async () => {
+        const { dir, cleanup: tempCleanup } = createTempMendixProject();
+        tempCleanups.push(tempCleanup);
+        state.projectDir = dir;
+
+        // Create a fake widget dir inside the project with a package.json
+        const widgetDir = join(dir, "my-widget");
+        mkdirSync(widgetDir, { recursive: true });
+        writeFileSync(join(widgetDir, "package.json"), '{"name":"my-widget"}');
+
+        const result = await client.callTool({
+            name: "build-widget",
+            arguments: { widgetPath: widgetDir }
+        });
+        const text = getResultText(result);
+        // Path check passed — build itself will fail (no real widget), but NOT with sandbox error
+        expect(text).not.toContain("not within an allowed directory");
+    });
+});