diff --git a/apps/docs/content/docs/ai/enhanced-security.mdx b/apps/docs/content/docs/ai/enhanced-security.mdx new file mode 100644 index 00000000..846796c9 --- /dev/null +++ b/apps/docs/content/docs/ai/enhanced-security.mdx @@ -0,0 +1,124 @@ +--- +title: Enhanced Security +description: Require one-time approval before an AI agent can run scripts in your FileMaker file, and manage which connections are allowed. +--- + +import { Callout } from "fumadocs-ui/components/callout"; +import { Step, Steps } from "fumadocs-ui/components/steps"; + +Enhanced Security makes ProofKit ask for your approval before a new agent connection can run scripts or read data in a FileMaker file. When it is on, the first time a client like Claude Desktop tries to run a script, a dialog appears in FileMaker Pro asking you to allow or deny that connection. + +When it is **off** (the default), any local process that can reach the ProofKit plug-in can run scripts in your connected files without a prompt. + + + Enhanced Security is in beta. The wording of dialogs and the layout of the + connection list may change in future releases. + + +## What it changes + +The ProofKit plug-in runs a local HTTP server that your agent talks to. Script-running tools (the ones an agent uses to read records or run FileMaker scripts) go through one endpoint. Enhanced Security gates that endpoint. + +| | Enhanced Security off | Enhanced Security on | +| --- | --- | --- | +| New agent connection | Auto-approved, no prompt | You approve or deny it in FileMaker Pro | +| Scope of approval | All connected files | One specific session **and** one file | +| Read-only status checks (connected files, health) | Allowed | Allowed | +| If approval expires | n/a | Agent prompts you again | + +Approval is scoped to a single session and a single file. Approving an agent for `Inventory.fmp12` does not approve it for `Customers.fmp12` — each file is approved on its own. + +## Turn it on or off + +The setting lives in the ProofKit plug-in preferences, not in your agent or in any config file. + + + + **Open the plug-in preferences.** + + In FileMaker Pro, open **Settings → Plug-Ins** (called **Preferences → Plug-Ins** on some versions), select **ProofKit**, and open its configuration. + + + + **Toggle the checkbox.** + + Check or uncheck **Enable Enhanced Security (BETA)**. + + - **Checked** — new connections require your approval. + - **Unchecked** — new connections are auto-approved. + + + + **Save.** + + On macOS the choice is saved when you close the window. On Windows, click **Save**. The change takes effect immediately for new connection attempts. + + + +## Approve a connection + +With Enhanced Security on, the first script-running request from a new connection pauses and a dialog appears in FileMaker Pro. It shows: + +- The agent client name and description (for example, `Claude Desktop`). +- The FileMaker file the connection wants to use. +- A short prefix of the session ID, so you can tell two connections apart. + +Click **Allow** to approve the connection or **Deny** to reject it. Check that you recognize the client name before approving — anything running locally can request access. + +The dialog waits about two minutes for a response. If you do not answer in time, the request fails and the agent can try again. + +Approved connections stay valid for **one hour of idle time**, refreshed each time the connection is used. After an hour without use, the approval expires and the next request prompts you again. Approvals are held in memory only, so they are also cleared when you restart FileMaker Pro or reload the plug-in. + +## Review and revoke connections + +Open the ProofKit connector Web Viewer (the window the **Connect to MCP** script opens) to see the current state. It lists: + +- **Authorized connections** — each approved session, the client name, a session ID prefix, and how long until it expires. Each has a **Revoke** button. A **Revoke all** action clears them at once. +- **Persistent tokens** — any long-lived tokens registered for automation (see below), each with its own revoke action. + +It also shows whether Enhanced Security is currently on or off. Revoking a connection takes effect immediately; the next request from that connection prompts for approval again. + +## Automation without prompts + +Interactive approval does not fit unattended workflows such as CI or a scheduled runner. For those, register a persistent token that is approved without a dialog. + + + + **Register a token from FileMaker.** + + In a startup script (or any script) in the file you want to expose, evaluate the custom function: + + ```text title="FileMaker calculation" + ProofKit_RegisterPersistentToken( "my-automation-token" ) + ``` + + A token is scoped to the file whose script registers it. Tokens live in memory only, so re-run this whenever the file opens. + + + + **Point the MCP server at the token.** + + Set these environment variables on the `proofkit-mcp` process: + + ```bash + FM_MCP_SESSION_ID=my-automation-token + FM_MCP_CLIENT_NAME="My Automation" + FM_MCP_CLIENT_DESCRIPTION="Scheduled report runner" + FM_MCP_DISABLE_INTERACTIVE_AUTHORIZATION=true + ``` + + `FM_MCP_SESSION_ID` carries the token. `FM_MCP_DISABLE_INTERACTIVE_AUTHORIZATION=true` makes the server fail with an error instead of opening a dialog if the token is missing or invalid, so an unattended run never hangs on a prompt. The client name and description appear in the connection list for auditing. + + + + + Persistent tokens are lost when the plug-in reloads or FileMaker Pro + restarts. Register them from a startup script so they are recreated each time + the file opens. + + +## Related guides + +- [Install and Connect](/docs/ai/install-and-connect) +- [Manual MCP Setup](/docs/ai/manual-mcp-setup) +- [Troubleshooting](/docs/ai/troubleshooting) diff --git a/apps/docs/content/docs/ai/meta.json b/apps/docs/content/docs/ai/meta.json index c18446c9..9189cddb 100644 --- a/apps/docs/content/docs/ai/meta.json +++ b/apps/docs/content/docs/ai/meta.json @@ -10,6 +10,7 @@ "install-and-connect", "explore-your-file", "build-a-webviewer-app", + "persistent-data", "deploy-to-filemaker", "edit-your-app", "github-workflow", @@ -19,8 +20,10 @@ "technical-requirements", "faq", "---Reference---", + "upgrade-to-3", "updating-proofkit", "manual-mcp-setup", + "enhanced-security", "telemetry", "troubleshooting" ] diff --git a/apps/docs/content/docs/ai/persistent-data.mdx b/apps/docs/content/docs/ai/persistent-data.mdx new file mode 100644 index 00000000..e05b21c7 --- /dev/null +++ b/apps/docs/content/docs/ai/persistent-data.mdx @@ -0,0 +1,77 @@ +--- +title: Persistent Data +description: Store your Web Viewer HTML so it survives a clone, using FileMaker 26's Configure Persistent Data feature. +--- + +import { Callout } from "fumadocs-ui/components/callout"; +import { Step, Steps } from "fumadocs-ui/components/steps"; + +FileMaker 26 introduces **Configure Persistent Data**, a feature that lets specific data survive when a file is cloned. ProofKit 3.0 uses it to keep your embedded Web Viewer HTML inside the FileMaker file through a clone — and therefore through a data migration. + + + Persistent data is a FileMaker 26 feature. On earlier versions, the embedded Web Viewer code still does not survive a clone, and the workarounds in [Deployment Methods](/docs/webviewer/deployment-methods) still apply. + + +## The problem this solves + +The default [embedded deployment](/docs/webviewer/deployment-methods#embedded) stores the Web Viewer app as **data** in a FileMaker field. That is simple and works offline, but it has historically had one big drawback: a clone strips all record data, so the HTML is gone. + +This matters because most production deployments and data migrations work by taking a **clone** of your development file and migrating live data into it. The embedded HTML, being record data, did not make it across — which is why teams reached for sidecar files, migration-only utility files, or hosted deployments to work around it. + +## How deployment writes the HTML + +When you install the ProofKit 3.0 add-on, you get **two versions** of the Web Viewer calculation to choose from: the original table-and-record version, and a new version that retrieves the HTML from persistent data. + +Every time you deploy, ProofKit saves the bundled HTML into a record in a table, exactly as before. In addition, **if you are developing on FileMaker 26 or later**, it also saves the HTML to a persistent data bucket. + +Because both copies are written on deploy, it is up to you to decide which one your end users load: + +- **Persistent data method** — recommended when all of your users are on FileMaker 26. +- **Table-and-record method** — required while any of your users are on a version earlier than FileMaker 26. + +## Use the persistent data method + +If every user is on FileMaker 26, use the persistent data Web Viewer. It survives clones and data migrations with no extra copy step. + + + + **Create a new layout** for the Web Viewer app. + + + + **Drag the ProofKit add-on** from the left sidebar onto the layout. + + This places a Web Viewer with the new calculation that includes the persistent data retrieval methods. + + + + **Resize the Web Viewer to fill the layout** so it stretches to the full layout size. + + + + **Tell it which app to load** using one of two options: + + - **Hard-code the app name** directly inside the Web Viewer calculation, or + - **Set the global field** for the app name before navigating the user to this layout. + + + +## Supporting users before FileMaker 26 + +If some of your users are not yet on FileMaker 26, keep using the table-and-record method, which requires the HTML to live in a record in a table. + +If you use data migrations, remember that this record data does not survive a clone. When you update the HTML, you may need to copy it over manually or run a post-migration script to move the latest HTML into the migrated file. + +## Removing pre-FileMaker 26 support + +Once all of your users are on FileMaker 26 and you no longer need the table-and-record method: + +1. Delete the **name** and **HTML** fields from the ProofKit apps table. +2. Update the `deploy_html` script so it no longer tries to save to those fields. + +After this, deployments write only to persistent data. + +## Related + +- [Deployment Methods](/docs/webviewer/deployment-methods) — how the embedded, hosted, and downloaded options compare. +- [Upgrade to 3.0](/docs/ai/upgrade-to-3) — moving an existing project onto the new add-on. diff --git a/apps/docs/content/docs/ai/upgrade-to-3.mdx b/apps/docs/content/docs/ai/upgrade-to-3.mdx new file mode 100644 index 00000000..fc245c27 --- /dev/null +++ b/apps/docs/content/docs/ai/upgrade-to-3.mdx @@ -0,0 +1,96 @@ +--- +title: Upgrade to 3.0 +description: Upgrade an existing ProofKit project to 3.0. +--- + +import { Callout } from "fumadocs-ui/components/callout"; +import { AgentPrompt } from "@/components/AgentPrompt"; + +ProofKit 3.0 adds FileMaker 26 support and renames the add-on's scripts. Grab the latest installer, then follow the steps below. + + + +## What changed + +- **All add-on scripts are now prefixed with `PK_`** so they are now less likely to conflict with previous add-ons we have released. +- **Persistent data in FileMaker 26** allows you to keep the HTML of your web viewer app in the *schema* of your FileMaker file so that it survives cloning and is now the best path for data migration. The add-on ships two Web Viewer calculations, and you pick one based on which FileMaker version your users run. See [Persistent Data](/docs/ai/persistent-data). +- **Request batching** coalesces Data API calls from the Web Viewer into fewer FileMaker script calls. This is on by default and needs no changes from you. See [Batching Data API Requests](/docs/webviewer/batching). + +## How to upgrade + +Install 3.0 the same way you update any ProofKit release: follow [Updating ProofKit](/docs/ai/updating-proofkit) to run the installer, reinstall the add-on in your FileMaker file, and redeploy your apps. + +Once 3.0 is installed, come back here for the two changes it requires: + +1. **Rename the scripts** your custom scripts and app code reference. This is the breaking change. +2. **Choose a Web Viewer calculation** based on which FileMaker version your users run. + +The renaming on the web app side is something a coding agent can do for you. Reinstalling the add-on and fixing FileMaker scripts is manual. + +## Prompt for your coding agent + +Paste this into your agent to handle the web app side. It does not touch your FileMaker file. + + + +## Renamed scripts + +Every script the add-on installs gained a `PK_` prefix. Search your FileMaker file and your app code for the old names and update each one. + +| Old name | New name | Where it is referenced | +| ----------------------- | ------------------------------- | ----------------------------------------------------------------- | +| `ExecuteDataApi` | `PK_execute_data_api` | `webviewerScriptName` in `proofkit-typegen-config.jsonc` | +| `ExecuteDataApiOnServer`| `PK_execute_data_api_on_server` | Same, when the call runs on FileMaker Server | +| `deploy_html` | `PK_deploy_html` | `scripts/filemaker.js` in your app, and custom FM deploy scripts | +| `SendCallback` | `PK_send_callback` | Custom FileMaker scripts only | + +### Web Viewer script + +The Web Viewer script name comes from your typegen config, not the generated client. Change `webviewerScriptName` and rerun typegen — do not edit the generated `client.ts` by hand, since typegen overwrites it. + +```jsonc title="proofkit-typegen-config.jsonc" +{ + "$schema": "https://proofkit.proof.sh/typegen-config-schema.json", + "config": { + // ...your existing config + "webviewerScriptName": "PK_execute_data_api", + }, +} +``` + +### Deploy script + +The deploy script name is set in `scripts/filemaker.js`. Rename it from `deploy_html` to `PK_deploy_html`. + + + Installing the 3.0 add-on creates the new scripts but cannot find every place + you called the old ones. Updating those references is on you. + + +## Choose your Web Viewer calculation + +The 3.0 add-on ships two versions of the Web Viewer calculation. When you place the Web Viewer on your layout, pick the one that matches your users: + +- **FileMaker 26 or later** — use the persistent data calculation. Your embedded HTML survives a clone and data migration. See [Persistent Data](/docs/ai/persistent-data). +- **Earlier than FileMaker 26** — use the table-and-record calculation, the same approach as before 3.0. + +## Related + +- [Persistent Data](/docs/ai/persistent-data) — keep embedded HTML through a clone on FileMaker 26. +- [Batching Data API Requests](/docs/webviewer/batching) — how the Web Viewer coalesces Data API calls. +- [Updating ProofKit](/docs/ai/updating-proofkit) — keeping the add-on and packages current. diff --git a/apps/docs/content/docs/webviewer/deployment-methods.mdx b/apps/docs/content/docs/webviewer/deployment-methods.mdx index 40c37a0e..91e340d4 100644 --- a/apps/docs/content/docs/webviewer/deployment-methods.mdx +++ b/apps/docs/content/docs/webviewer/deployment-methods.mdx @@ -3,6 +3,8 @@ title: Deployment Methods description: Learn about the different methods for deploying Web Viewer code to your FileMaker file. --- +import { Callout } from "fumadocs-ui/components/callout"; + There are many ways to deploy Web Viewer code to your FileMaker file, and each method has it's own pros and cons. This document attempts to outline the various options so you can make the best choice for your app. ## Embedded @@ -13,9 +15,13 @@ This is also the default supported deployment model in ProofKit. The main AI gui | Pros | Cons | |----------------------------------------|----------------------------------------------------------------------| -| ✅ Simple to setup and understand | ⚠️ Doesn't survive data migrations | -| ✅ Works offline | ⚠️ Unable to use server-side JavaScript libraries | -| | ⚠️ Updates requires the web developer to have access to the FileMaker file | +| ✅ Simple to setup and understand | ⚠️ Unable to use server-side JavaScript libraries | +| ✅ Works offline | ⚠️ Updates requires the web developer to have access to the FileMaker file | +| ✅ Survives data migrations (FileMaker 26+, see below) | | + + + On FileMaker 26 and later, ProofKit 3.0 stores the embedded HTML using FileMaker's [Configure Persistent Data](/docs/ai/persistent-data) feature, so the code **survives a clone — and therefore a data migration**. The migration drawback below, and its workarounds, only apply on earlier versions. + #### Considerations @@ -68,7 +74,7 @@ This technique is a hybrid of the embedded and hosted methods. Essentially, the | Feature | Embedded | Hosted | Downloaded | |--------------------------------------------|------------------|------------------|------------------| | **Simple Setup** | ✅ | ⚠️ (needs hosting) | ⚠️ (hybrid setup) | -| **Survives Data Migrations** | ❌ | ✅ | ✅ | +| **Survives Data Migrations** | ✅ (FileMaker 26) | ✅ | ✅ | | **Works Offline** | ✅ | ❌ | ✅ (after download) | | **Web Server Required?** | No | Yes | Simple (static file host or CDN) | | **Can Use Server-side JS Libraries** | ❌ | ✅ | ❌ | diff --git a/apps/docs/src/app/docs/(docs)/layout.tsx b/apps/docs/src/app/docs/(docs)/layout.tsx index ba4e88fc..71ef95bf 100644 --- a/apps/docs/src/app/docs/(docs)/layout.tsx +++ b/apps/docs/src/app/docs/(docs)/layout.tsx @@ -26,6 +26,17 @@ const llmSidebarNodes: Node[] = [ }, ]; +// Sidebar pages (by URL) that should render a "New" badge. +const newBadgePages = new Set(["/docs/ai/persistent-data"]); + +function NewBadge() { + return ( + + New + + ); +} + const docsTree = appendLlmLinks(source.pageTree); function appendLlmLinks(tree: Root): Root { @@ -36,6 +47,18 @@ function appendLlmLinks(tree: Root): Root { } function appendLlmLinksToNode(node: Node): Node { + if (node.type === "page" && newBadgePages.has(node.url)) { + return { + ...node, + name: ( + + {node.name} + + + ), + }; + } + if (node.type !== "folder") { return node; } diff --git a/apps/docs/src/components/AgentPrompt.tsx b/apps/docs/src/components/AgentPrompt.tsx new file mode 100644 index 00000000..b99083b7 --- /dev/null +++ b/apps/docs/src/components/AgentPrompt.tsx @@ -0,0 +1,30 @@ +"use client"; + +import { DynamicCodeBlock } from "fumadocs-ui/components/dynamic-codeblock"; +import { useEffect, useState } from "react"; + +/** + * Renders an agent prompt as a copyable code block, substituting `{url}` in the + * template with the page the reader is currently on. This keeps the referenced + * URL correct across preview deployments and the production site, instead of + * hard-coding a domain. + */ +export function AgentPrompt({ + template, + fallbackUrl, +}: { + /** Prompt text. Every `{url}` is replaced with the current page URL. */ + template: string; + /** URL used during SSR and before hydration. */ + fallbackUrl: string; +}) { + const [url, setUrl] = useState(fallbackUrl); + + useEffect(() => { + setUrl(`${window.location.origin}${window.location.pathname}`); + }, []); + + return ; +} + +export default AgentPrompt;