fm bridge vite plugin

packages/typegen/skills/getting-started/SKILL.md

@@ -193,7 +193,7 @@ For WebViewer apps running inside FileMaker, you can use FM HTTP mode to generat
 
 **Prerequisites:**
 - FM HTTP daemon installed and running (`curl http://127.0.0.1:1365/health`)
-- FileMaker file open locally with "Connect to MCP" script run
+- FileMaker file reachable via the FM HTTP `connectedFiles` endpoint. The most common setup is to open the file locally and run a script such as "Connect to MCP", but the script name may differ in your solution as long as it establishes the bridge.
 
 1. Install packages:
 

packages/webviewer/package.json

@@ -31,6 +31,16 @@
         "default": "./dist/cjs/adapter.cjs"
       }
     },
+    "./vite-plugins": {
+      "import": {
+        "types": "./dist/esm/vite-plugins.d.ts",
+        "default": "./dist/esm/vite-plugins.js"
+      },
+      "require": {
+        "types": "./dist/cjs/vite-plugins.d.cts",
+        "default": "./dist/cjs/vite-plugins.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {
@@ -47,12 +57,14 @@
     "knip": "^5.80.2",
     "publint": "^0.3.16",
     "typescript": "^5.9.3",
-    "vite": "^6.4.1"
+    "vite": "^6.4.1",
+    "vitest": "^4.0.17"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "tsc",
     "build": "tsc && vite build && publint --strict",

packages/webviewer/src/fm-bridge.ts

@@ -0,0 +1,155 @@
+import type { HtmlTagDescriptor, Plugin } from "vite";
+
+const TRAILING_SLASH_PATTERN = /\/$/;
+const CONNECTED_FILES_TIMEOUT_MS = 5000;
+
+export interface FmBridgeOptions {
+  fileName?: string;
+  fmHttpBaseUrl?: string;
+  wsUrl?: string;
+  debug?: boolean;
+}
+
+export const defaultFmHttpBaseUrl = "http://localhost:1365";
+export const defaultWsUrl = "ws://localhost:1365/ws";
+
+export const trimToNull = (value: unknown): string | null => {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+export const normalizeBaseUrl = (value: string): string => value.replace(TRAILING_SLASH_PATTERN, "");
+
+export const resolveWsUrl = (options: Pick<FmBridgeOptions, "fmHttpBaseUrl" | "wsUrl">): string => {
+  const explicitWsUrl = trimToNull(options.wsUrl);
+  if (explicitWsUrl) {
+    return explicitWsUrl;
+  }
+
+  const baseUrl = normalizeBaseUrl(trimToNull(options.fmHttpBaseUrl) ?? defaultFmHttpBaseUrl);
+
+  try {
+    const parsed = new URL(baseUrl);
+    const wsProtocol = parsed.protocol === "https:" ? "wss:" : "ws:";
+    return `${wsProtocol}//${parsed.host}/ws`;
+  } catch {
+    return defaultWsUrl;
+  }
+};
+
+export const discoverConnectedFileName = async (baseUrl: string): Promise<string> => {
+  const connectedFilesUrl = `${normalizeBaseUrl(baseUrl)}/connectedFiles`;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, CONNECTED_FILES_TIMEOUT_MS);
+  const reachabilityErrorMessage = `fmBridge could not reach ${connectedFilesUrl}. Start fm-http and connect a FileMaker webviewer.`;
+
+  let response: Response;
+  try {
+    response = await fetch(connectedFilesUrl, {
+      signal: controller.signal,
+    });
+  } catch (error) {
+    throw new Error(reachabilityErrorMessage, {
+      cause: error,
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `fmBridge received HTTP ${response.status} from ${connectedFilesUrl}. Ensure fm-http is healthy and reachable.`,
+    );
+  }
+
+  const payload = (await response.json()) as unknown;
+  if (!Array.isArray(payload)) {
+    throw new Error(`fmBridge expected an array response from ${connectedFilesUrl}.`);
+  }
+
+  const firstFileName = payload.find((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
+
+  if (!firstFileName) {
+    throw new Error(
+      `fmBridge found no connected FileMaker files at ${connectedFilesUrl}. Open FileMaker and load /webviewer?fileName=YourFile.`,
+    );
+  }
+
+  return firstFileName;
+};
+
+export const buildMockScriptTag = (options: {
+  baseUrl: string;
+  fileName: string | null;
+  wsUrl: string;
+  debug: boolean;
+}): HtmlTagDescriptor | null => {
+  if (!options.fileName) {
+    return null;
+  }
+
+  const scriptUrl = new URL(`${normalizeBaseUrl(options.baseUrl)}/fm-mock.js`);
+  scriptUrl.searchParams.set("fileName", options.fileName);
+  scriptUrl.searchParams.set("wsUrl", options.wsUrl);
+
+  if (options.debug) {
+    scriptUrl.searchParams.set("debug", "true");
+  }
+
+  return {
+    tag: "script",
+    attrs: { src: scriptUrl.toString() },
+    injectTo: "head-prepend",
+  };
+};
+
+export const fmBridge = (options: FmBridgeOptions = {}): Plugin => {
+  const baseUrl = trimToNull(options.fmHttpBaseUrl) ?? defaultFmHttpBaseUrl;
+  const wsUrl = resolveWsUrl(options);
+  const debug = options.debug === true;
+  let resolvedFileName: string | null = trimToNull(options.fileName);
+  let isServeMode = true;
+
+  return {
+    name: "proofkit-fm-bridge",
+    apply(_config, { command }) {
+      isServeMode = command === "serve";
+      return isServeMode;
+    },
+    async configureServer() {
+      if (!isServeMode) {
+        return;
+      }
+
+      if (resolvedFileName) {
+        return;
+      }
+
+      resolvedFileName = await discoverConnectedFileName(baseUrl);
+    },
+    async transformIndexHtml() {
+      if (!isServeMode) {
+        return;
+      }
+
+      if (!resolvedFileName) {
+        resolvedFileName = await discoverConnectedFileName(baseUrl);
+      }
+
+      const tag = buildMockScriptTag({
+        baseUrl,
+        fileName: resolvedFileName,
+        wsUrl,
+        debug,
+      });
+
+      return tag ? [tag] : undefined;
+    },
+  };
+};

packages/webviewer/src/vite-plugins.ts

@@ -0,0 +1,6 @@
+import type { FmBridgeOptions as InternalFmBridgeOptions } from "./fm-bridge.js";
+import { fmBridge as createFmBridge } from "./fm-bridge.js";
+
+export interface FmBridgeOptions extends InternalFmBridgeOptions {}
+
+export const fmBridge = createFmBridge;