Add FM HTTP adapter flow for typegen with local env validation and tests

.changeset/fm-http-typegen-flow.md

@@ -0,0 +1,6 @@
+---
+"@proofkit/fmdapi": minor
+"@proofkit/typegen": minor
+---
+
+Add FM HTTP adapter support for type generation, including local FM HTTP metadata fetch flow, env name handling, and improved adapter error parsing.

_artifacts/domain_map.yaml

@@ -2,7 +2,7 @@
 # Generated by skill-domain-discovery
 # Library: ProofKit
 # Version: fmdapi@5.0.3-beta.1, fmodata@0.1.0-beta.31, typegen@1.1.0-beta.15, webviewer@3.0.7-beta.0, better-auth@0.4.0-beta.7
-# Date: 2026-03-13
+# Date: 2026-03-16
 # Status: reviewed
 
 library:
@@ -50,6 +50,9 @@ skills:
       - 'Environment variables (FM_SERVER, FM_DATABASE, OTTO_API_KEY, FM_USERNAME, FM_PASSWORD)'
       - 'strictNumbers, strictValueLists options'
       - 'webviewerScriptName option'
+      - 'fmHttp config (local FM HTTP proxy for typegen metadata fetching)'
+      - 'FM HTTP env vars (FM_HTTP_BASE_URL, FM_CONNECTED_FILE_NAME)'
+      - 'FM HTTP auto-discovery of connectedFileName via /connectedFiles'
       - 'Field type overrides for OData'
       - 'reduceMetadata, alwaysOverrideFieldNames'
       - 'Entity ID preservation across regeneration'
@@ -59,6 +62,8 @@ skills:
       - 'Regenerate types after FileMaker schema changes'
       - 'Switch from Data API to OData config'
       - 'Configure environment variables for FM connection'
+      - 'Set up FM HTTP mode for local typegen without credentials'
+      - 'Troubleshoot FM HTTP connectivity issues'
       - 'Customize generated schemas with override files'
     failure_modes:
       - mistake: 'Editing files in generated/ or client/ directories'
@@ -168,6 +173,60 @@ skills:
         status: active
         skills: ['typegen-setup', 'fmdapi-client', 'fmodata-client']
 
+      - mistake: 'Using FmHttpAdapter in production application code'
+        mechanism: 'FmHttpAdapter is internal to typegen metadata fetching. Generated clients use WebViewerAdapter. Agent sees the adapter import in typegen source and uses it in app code.'
+        wrong_pattern: |
+          import { FmHttpAdapter } from "@proofkit/fmdapi/adapters/fm-http";
+          const client = DataApi({
+            adapter: new FmHttpAdapter({ baseUrl: "http://127.0.0.1:1365", connectedFileName: "MyFile" }),
+            layout: "Contacts",
+          });
+        correct_pattern: |
+          // Use typegen-generated client (which uses WebViewerAdapter internally)
+          import { ContactsLayout } from "./schema/client";
+          const { data } = await ContactsLayout.find({ query: { name: "==John" } });
+        source: 'source: typegen.ts, buildLayoutClient.ts'
+        priority: CRITICAL
+        status: active
+        skills: ['typegen-setup']
+
+      - mistake: 'Setting standard FM env vars when using fmHttp mode'
+        mechanism: 'fmHttp mode does not need FM_SERVER, FM_DATABASE, or OTTO_API_KEY. Agent configures both standard and fmHttp env vars, causing confusion when standard vars fail validation.'
+        wrong_pattern: |
+          # .env — agent sets both
+          FM_SERVER=https://fm.example.com
+          FM_DATABASE=MyFile.fmp12
+          OTTO_API_KEY=dk_abc123
+          FM_HTTP_BASE_URL=http://127.0.0.1:1365
+        correct_pattern: |
+          # fmHttp mode only needs these (baseUrl defaults to 127.0.0.1:1365)
+          # connectedFileName is auto-discovered if not set
+          FM_CONNECTED_FILE_NAME=MyFile
+        source: 'source: getEnvValues.ts, constants.ts'
+        priority: HIGH
+        status: active
+        skills: ['typegen-setup']
+
+      - mistake: 'Suggesting OttoFMS/FetchAdapter fallback when FM HTTP fails'
+        mechanism: 'Agent troubleshoots FM HTTP connection failure by suggesting standard auth. Developer chose fmHttp because they have no hosted credentials or are working offline. Correct troubleshooting: check daemon health (GET http://127.0.0.1:1365/health), check /connectedFiles, ensure FM file has run "Connect to MCP" script and WebViewer window is open in Browse mode.'
+        source: 'maintainer interview'
+        priority: HIGH
+        status: active
+        skills: ['typegen-setup']
+
+      - mistake: 'FM HTTP WebViewer window closed or in Layout mode'
+        mechanism: 'The FM HTTP proxy works via a WebViewer window opened by the "Connect to MCP" script in FileMaker. If this window is closed or switched to Layout mode, all proxy requests fail. Error may not be obvious — typegen just fails to connect.'
+        correct_pattern: |
+          # Troubleshooting checklist:
+          # 1. Is the fm-http daemon running? GET http://127.0.0.1:1365/health
+          # 2. Is the file connected? GET http://127.0.0.1:1365/connectedFiles
+          # 3. If file not listed: open it in FileMaker, run "Connect to MCP" script
+          # 4. Ensure the WebViewer window stays open in Browse mode (not Layout mode)
+        source: 'maintainer interview'
+        priority: HIGH
+        status: active
+        skills: ['typegen-setup']
+
   - name: 'Data API Client'
     slug: 'fmdapi-client'
     domain: 'data-access'
@@ -646,10 +705,12 @@ skills:
       - 'First typegen run'
       - 'First query with generated client'
       - 'Choosing between Data API and OData'
+      - 'FM HTTP mode for local/offline WebViewer development (no credentials needed)'
     tasks:
       - 'Set up a new project with ProofKit'
       - 'Connect to FileMaker server for the first time'
       - 'Generate types and make first data query'
+      - 'Set up FM HTTP mode for local WebViewer development'
     failure_modes:
       - mistake: 'Missing fmrest or fmodata privilege on FM account'
         mechanism: 'Data API requires fmrest extended privilege. OData requires fmodata privilege. Without these, all API calls return 401/403.'

_artifacts/skill_spec.md

@@ -15,7 +15,7 @@ ProofKit is a monorepo of TypeScript tools for building web applications integra
 
 | Skill | Type | Domain | What it covers | Failure modes |
 | --- | --- | --- | --- | --- |
-| typegen-setup | core | connecting | Config, CLI, Data API + OData modes, validators, generated file structure, env vars | 7 |
+| typegen-setup | core | connecting | Config, CLI, Data API + OData + FM HTTP modes, validators, generated file structure, env vars | 11 |
 | fmdapi-client | core | data-access | DataApi factory, adapters, token stores, CRUD, find variants, scripts, validation | 6 |
 | fmodata-client | core | data-access | FMServerConnection, schema/field builders, query builder, CRUD, relationships, batch, errors | 8 |
 | webviewer-integration | core | webviewer | fmFetch, callFMScript, WebViewerAdapter, browser-only constraints, local mode perf | 6 |
@@ -25,7 +25,7 @@ ProofKit is a monorepo of TypeScript tools for building web applications integra
 
 ## Failure Mode Inventory
 
-### typegen-setup (7 failure modes)
+### typegen-setup (11 failure modes)
 
 | # | Mistake | Priority | Source | Cross-skill? |
 | --- | --- | --- | --- | --- |
@@ -36,6 +36,10 @@ ProofKit is a monorepo of TypeScript tools for building web applications integra
 | 5 | Omitting type discriminator for OData config | HIGH | source + docs | — |
 | 6 | Manually redefining types instead of using generated/inferred types | CRITICAL | maintainer | fmdapi-client, fmodata-client |
 | 7 | Mixing Zod v3 and v4 in the same project | HIGH | maintainer | fmdapi-client, fmodata-client |
+| 8 | Using FmHttpAdapter in production application code | CRITICAL | source | — |
+| 9 | Setting standard FM env vars when using fmHttp mode | HIGH | source | — |
+| 10 | Suggesting OttoFMS/FetchAdapter fallback when FM HTTP fails | HIGH | maintainer | — |
+| 11 | FM HTTP WebViewer window closed or in Layout mode | HIGH | maintainer | — |
 
 ### fmdapi-client (6 failure modes)
 

apps/docs/content/docs/typegen/config.mdx

@@ -75,6 +75,11 @@ The typegen tool is configured using the `proofkit-typegen-config.jsonc` file at
       description:
         "If set, will generate the client using the @proofkit/webviewer package",
     },
+    fmHttp: {
+      type: "{ scriptName?: string }",
+      description:
+        "Optional local-only adapter mode for typegen metadata fetch. Generated clients still use the @proofkit/webviewer adapter.",
+    },
     generateClient: {
       type: "boolean",
       default: "true",
@@ -90,6 +95,9 @@ If set to `false`, will only generate the zod schema and/or typescript types, bu
 ### `webviewerScriptName`
 If set, will generate the client using the [@proofkit/webviewer](/docs/webviewer) package. This allows all calls to run via a FileMaker script rather than a network request. For more information, see the [@proofkit/webviewer](/docs/webviewer) documentation.
 
+### `fmHttp`
+If set, typegen uses the local FM HTTP adapter only while generating schemas and clients. The generated runtime client still uses [@proofkit/webviewer](/docs/webviewer). If `webviewerScriptName` is not set, `fmHttp.scriptName` (or `"execute_data_api"`) is used for the generated webviewer client script name.
+
 ### `clientSuffix` (default: `"Layout"`)
 The suffix to add to the client name.
 
@@ -156,4 +164,4 @@ Even if you ignore the value lists for type purposes, the value lists will still
 
 <Callout type="info">
   This setting will apply to all fields with value lists in the layout. For more granular control, override the Zod schema using the `extend` method. See the [Transformations](/docs/fmdapi/validation) page for more details.
-</Callout>
+</Callout>

btca.config.jsonc

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://btca.dev/btca.schema.json",
+  "resources": [
+    {
+      "type": "git",
+      "name": "fm-mcp",
+      "url": "https://github.com/proofgeist/fm-mcp",
+      "branch": "main"
+    }
+  ],
+  "model": "gpt-5.3-codex",
+  "provider": "openai"
+}