@proofkit/better-auth 0.4.0-beta.7 → 0.4.0-beta.9

package/bin/intent.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+try {
+  await import('@tanstack/intent/intent-library')
+} catch (e) {
+  if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
+    console.error('@tanstack/intent is not installed.')
+    console.error('')
+    console.error('Install it as a dev dependency:')
+    console.error('  npm add -D @tanstack/intent')
+    console.error('')
+    console.error('Or run directly:')
+    console.error('  npx @tanstack/intent@latest list')
+    process.exit(1)
+  }
+  throw e
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@proofkit/better-auth",
-  "version": "0.4.0-beta.7",
+  "version": "0.4.0-beta.9",
   "description": "FileMaker adapter for Better Auth",
   "type": "module",
   "main": "dist/esm/index.js",
   "bin": {
-    "better-auth": "./dist/esm/cli/index.js"
+    "better-auth": "./dist/esm/cli/index.js",
+    "intent": "./bin/intent.js"
   },
   "exports": {
     ".": {
@@ -22,11 +23,15 @@
     "fmdapi",
     "proofgeist",
     "filemaker",
-    "fmrest"
+    "fmrest",
+    "tanstack-intent"
   ],
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills",
+    "bin",
+    "!skills/_artifacts"
   ],
   "author": "",
   "license": "ISC",
@@ -48,9 +53,10 @@
     "fs-extra": "^11.3.3",
     "prompts": "^2.4.2",
     "vite": "^6.4.1",
-    "@proofkit/fmodata": "0.1.0-beta.31"
+    "@proofkit/fmodata": "0.1.0-beta.33"
   },
   "devDependencies": {
+    "@tanstack/intent": "^0.0.19",
     "@types/fs-extra": "^11.0.4",
     "@types/prompts": "^2.4.9",
     "@vitest/ui": "^3.2.4",

package/skills/better-auth-setup/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: better-auth-setup
+description: >
+  Set up self-hosted authentication with better-auth using FileMaker as the
+  database backend. Covers FileMakerAdapter, FMServerConnection, betterAuth
+  config, migration via npx @proofkit/better-auth migrate, OData prerequisites,
+  fmodata privilege, Full Access credentials for schema modification, plugin
+  migration workflow, troubleshooting "filemaker is not supported" errors.
+type: core
+library: proofkit
+library_version: "0.4.0-beta.7"
+requires:
+  - fmodata-client
+sources:
+  - "proofgeist/proofkit:packages/better-auth/src/*.ts"
+  - "proofgeist/proofkit:apps/docs/content/docs/better-auth/*.mdx"
+---
+
+## Setup
+
+### Prerequisites
+
+- OData enabled on FileMaker Server
+- API credentials with `fmodata` privilege enabled
+- Read/write access to the better-auth tables
+- Full Access credentials available for schema migration (can differ from runtime credentials)
+
+### Install packages
+
+```bash
+pnpm add @proofkit/better-auth @proofkit/fmodata
+```
+
+### Configure auth.ts
+
+```ts
+import { betterAuth } from "better-auth";
+import { FMServerConnection } from "@proofkit/fmodata";
+import { FileMakerAdapter } from "@proofkit/better-auth";
+
+const connection = new FMServerConnection({
+  serverUrl: process.env.FM_SERVER_URL!,
+  auth: {
+    username: process.env.FM_USERNAME!,
+    password: process.env.FM_PASSWORD!,
+  },
+});
+
+const db = connection.database(process.env.FM_DATABASE!);
+
+export const auth = betterAuth({
+  database: FileMakerAdapter({ database: db }),
+  // add plugins, social providers, etc.
+});
+```
+
+`FileMakerAdapter` accepts a `FileMakerAdapterConfig`:
+
+- `database` (required) -- an fmodata `Database` instance
+- `debugLogs` (optional) -- enable adapter debug logging
+- `usePlural` (optional) -- set `true` if table names are plural
+
+The adapter maps Better Auth operations (create, findOne, findMany, update, delete, count) to OData requests via `db._makeRequest`. It does not support JSON columns, native dates, or native booleans -- all values are stored as strings/numbers.
+
+### Alternative: Data API key (OttoFMS 4.11+)
+
+```ts
+const connection = new FMServerConnection({
+  serverUrl: process.env.FM_SERVER_URL!,
+  auth: {
+    apiKey: process.env.OTTO_API_KEY!,
+  },
+});
+```
+
+OData must be enabled for the key.
+
+## Core Patterns
+
+### 1. Initial migration
+
+After configuring `auth.ts`, run the migration CLI to create tables and fields in FileMaker:
+
+```bash
+npx @proofkit/better-auth migrate
+```
+
+The CLI:
+
+1. Loads your `auth.ts` config (auto-detected or via `--config <path>`)
+2. Calls `getSchema()` from `better-auth/db` to determine required tables/fields
+3. Fetches current OData metadata via `db.getMetadata()`
+4. Computes a diff: tables to create, fields to add to existing tables
+5. Prints the migration plan and prompts for confirmation
+6. Executes via `db.schema.createTable()` and `db.schema.addFields()`
+
+Only schema is modified. No layouts or relationships are created.
+
+If your runtime credentials lack Full Access, override for migration only:
+
+```bash
+npx @proofkit/better-auth migrate --username "admin" --password "admin_pass"
+```
+
+Skip confirmation with `-y`:
+
+```bash
+npx @proofkit/better-auth migrate -y
+```
+
+### 2. Adding plugins and re-migrating
+
+When you add a Better Auth plugin (e.g. `twoFactor`, `organization`), it declares additional tables/fields. After updating `auth.ts`:
+
+```ts
+import { betterAuth } from "better-auth";
+import { twoFactor } from "better-auth/plugins";
+import { FMServerConnection } from "@proofkit/fmodata";
+import { FileMakerAdapter } from "@proofkit/better-auth";
+
+const connection = new FMServerConnection({
+  serverUrl: process.env.FM_SERVER_URL!,
+  auth: {
+    username: process.env.FM_USERNAME!,
+    password: process.env.FM_PASSWORD!,
+  },
+});
+
+const db = connection.database(process.env.FM_DATABASE!);
+
+export const auth = betterAuth({
+  database: FileMakerAdapter({ database: db }),
+  plugins: [twoFactor()],
+});
+```
+
+Re-run migration:
+
+```bash
+npx @proofkit/better-auth migrate
+```
+
+The planner diffs against existing metadata, so only new tables/fields are added. Existing tables are left untouched.
+
+### 3. Troubleshooting privilege errors
+
+When migration fails with OData error code `207`, the account lacks schema modification privileges. The CLI outputs:
+
+```
+Failed to create table "tableName": Cannot modify schema.
+The account used does not have schema modification privileges.
+Use --username and --password to provide Full Access credentials.
+```
+
+Fix: provide Full Access credentials via CLI flags. These are only used for migration, not at runtime.
+
+## Common Mistakes
+
+### [CRITICAL] Using better-auth CLI instead of @proofkit/better-auth
+
+Wrong:
+```bash
+npx better-auth migrate
+```
+
+Correct:
+```bash
+npx @proofkit/better-auth migrate
+```
+
+The standard better-auth CLI does not know about the FileMaker adapter and produces: `ERROR [Better Auth]: filemaker is not supported. If it is a custom adapter, please request the maintainer to implement createSchema`. The `@proofkit/better-auth` CLI loads your auth config, extracts the `Database` instance from the adapter, and handles migration via fmodata's schema API.
+
+Source: `apps/docs/content/docs/better-auth/troubleshooting.mdx`
+
+### [HIGH] Missing Full Access credentials for schema migration
+
+Wrong:
+```bash
+# Using runtime credentials that only have fmodata privilege
+npx @proofkit/better-auth migrate
+# Fails with OData error 207: Cannot modify schema
+```
+
+Correct:
+```bash
+npx @proofkit/better-auth migrate --username "full_access_user" --password "full_access_pass"
+```
+
+Schema modification (`db.schema.createTable`, `db.schema.addFields`) requires [Full Access] privileges. Standard API accounts with `fmodata` privilege can read/write data but cannot alter schema. The CLI accepts `--username` and `--password` flags to override credentials for migration only.
+
+Source: `packages/better-auth/src/cli/index.ts`, `packages/better-auth/src/migrate.ts`
+
+### [HIGH] Removing fields added by migration
+
+Wrong:
+```
+Manually deleting "unused" fields from better-auth tables in FileMaker
+```
+
+Correct:
+```
+Keep all fields created by migration, even if you don't plan to use them
+```
+
+Better Auth expects all schema fields to exist at runtime. The adapter issues OData requests that reference these fields. Removing them causes runtime errors when Better Auth attempts to read or write those columns.
+
+Source: `apps/docs/content/docs/better-auth/installation.mdx`
+
+### [HIGH] Forgetting to re-run migration after adding plugins
+
+Wrong:
+```ts
+// Added twoFactor() plugin to auth.ts but did not re-run migration
+export const auth = betterAuth({
+  database: FileMakerAdapter({ database: db }),
+  plugins: [twoFactor()],
+});
+// Runtime errors: tables/fields for twoFactor don't exist
+```
+
+Correct:
+```bash
+# After adding any plugin to auth.ts, always re-run:
+npx @proofkit/better-auth migrate
+```
+
+Each plugin declares additional tables and fields via `getSchema()`. The migration planner diffs the full schema (including plugins) against current OData metadata. Without re-running, the new tables/fields don't exist and Better Auth throws at runtime.
+
+Source: `apps/docs/content/docs/better-auth/installation.mdx`
+
+## References
+
+- **fmodata-client** -- Better Auth uses fmodata `Database` under the hood for all OData requests. `FMServerConnection` and `database()` must be configured before `FileMakerAdapter` can work. The adapter calls `db._makeRequest()` for CRUD and `db.schema.*` for migrations.