@proofkit/cli 1.0.0-beta.0

package/template/extras/_cursor/rules/troubleshooting-patterns.mdc

@@ -0,0 +1,240 @@
+---
+description: |
+globs: 
+alwaysApply: false
+---
+# Troubleshooting and Maintenance Patterns
+
+This rule documents common issues, error patterns, and their solutions in the project.
+
+<rule>
+name: troubleshooting_patterns
+description: Documents common runtime errors, type errors, and solutions. All data operations MUST use FileMaker Data API exclusively.
+filters:
+  - type: file_extension
+    pattern: "\\.(ts|tsx)$"
+  - type: content
+    pattern: "(Error|error|ZodError|TypeError|ValidationError|@proofkit/fmdapi)"
+
+initial_debugging_steps:
+  priority: "ALWAYS run `{package-manager} typegen` first for any data-related issues"
+  steps:
+    - "Run `{package-manager} typegen` to ensure types match FileMaker schema"
+    - "Check if error persists after typegen"
+    - "If error persists, check console for exact error messages"
+    - "Look for patterns in the troubleshooting guide below"
+  common_console_errors:
+    zod_errors:
+      pattern: "ZodError: [path] invalid_type..."
+      likely_cause: "Field name mismatch or missing field"
+      example: "ZodError: nameFirst expected string, got undefined"
+      solution: "Run typegen first, then check field names in FileMaker schema"
+    type_errors:
+      pattern: "TypeError: Cannot read property 'X' of undefined"
+      likely_cause: "Accessing field before data is loaded or field name mismatch"
+      solution: "Run typegen first, then add null checks or loading states"
+    network_errors:
+      pattern: "Failed to fetch" or "Network error"
+      likely_cause: "FileMaker connection issues"
+      solution: "Run typegen first, then check FileMaker server status and credentials"
+
+data_source_validation:
+  requirement: "All data operations must use FileMaker Data API exclusively"
+  first_step_for_data_issues: "ALWAYS run `{package-manager} typegen` first"
+  common_mistakes:
+    - "Attempting to use SQL queries"
+    - "Adding direct database connections"
+    - "Using local storage for persistent data"
+    - "Implementing alternative data stores"
+    - "Skipping typegen after FileMaker schema changes"
+    - "Using incorrect field names from old schema"
+  correct_approach:
+    - "Run typegen first"
+    - "Use @proofkit/fmdapi for all data operations"
+    - "Follow FileMaker layout and field conventions"
+    - "Use layout.create, layout.find, layout.get, layout.update, layout.delete"
+    - "Use layout.maybeFindFirst for optional records"
+
+error_patterns:
+  field_name_mismatches:
+    symptoms:
+      - "ZodError: invalid_type at path [fieldName]"
+      - "Property 'X' does not exist on type 'Y'"
+      - "TypeScript errors about missing properties"
+    common_examples:
+      - "nameFirst vs firstName"
+      - "lastName vs nameLast"
+      - "postalCode vs postal_code"
+      - "phoneNumber vs phone"
+    cause: "Mismatch between component field names and FileMaker schema"
+    solution:
+      steps:
+        - "Run `{package-manager} typegen` to update types"
+        - "Look at generated types in src/config/schemas/filemaker/"
+        - "Update component field names to match schema"
+        - "Check console for exact field name in error"
+      files_to_check:
+        - "src/config/schemas/filemaker/*.ts"
+        - "Component files using the fields"
+
+  zod_validation_errors:
+    symptoms:
+      - "Runtime ZodError: invalid_type"
+      - "Zod schema validation failed"
+      - "Property not found in schema"
+      - "Unexpected field in response"
+    cause: "FileMaker database schema changes not reflected in TypeScript types"
+    solution:
+      steps:
+        - "Run `{package-manager} typegen` to regenerate types from FileMaker schema"
+        - "Run `{package-manager} tsc` to identify type mismatches"
+        - "Check console for exact error message"
+        - "Update affected components and server actions"
+      commands:
+        - "{package-manager} typegen"
+        - "{package-manager} tsc"
+      files_to_check:
+        - "src/server/actions/*"
+        - "src/server/schema/*"
+        - "fmschema.config.mjs"
+
+  filemaker_connection:
+    symptoms:
+      - "ETIMEDOUT connecting to FileMaker"
+      - "Invalid FileMaker credentials"
+      - "Session token expired"
+      - "Layout not found"
+      - "Field not found in layout"
+      - "Invalid find criteria"
+      - "No data appearing or queries returning empty"
+    cause: "FileMaker connection, authentication, or query issues"
+    solution:
+      steps:
+        - "Run `{package-manager} typegen` to ensure schema is up to date"
+        - "Check FileMaker Server status"
+        - "Validate credentials and permissions"
+        - "Note: As an AI, you cannot directly check environment variables - always ask the user to verify them if this is determined to be the issue"
+        - "Verify layout names and field access"
+        - "Check FileMaker query syntax"
+      files_to_check:
+        - "src/server/lib/fm.ts"
+        - "fmschema.config.mjs"
+
+  data_access_errors:
+    symptoms:
+      - "Invalid operation on FileMaker record"
+      - "Record not found"
+      - "Insufficient permissions"
+      - "Invalid find request"
+    cause: "Incorrect FileMaker Data API usage or permissions"
+    solution:
+      steps:
+        - "Run `{package-manager} typegen` to ensure schema is up to date"
+        - "Verify FileMaker layout privileges"
+        - "Check record existence before operations"
+        - "Validate find criteria format"
+        - "Use proper FM API methods"
+      files_to_check:
+        - "src/server/actions/*"
+        - "src/server/lib/fm.ts"
+
+  type_errors:
+    symptoms:
+      - "Type ... is not assignable to type ..."
+      - "Property ... does not exist on type ..."
+      - "Argument of type ... is not assignable"
+    cause: "Mismatch between FileMaker schema and TypeScript types"
+    solution:
+      steps:
+        - "Run `{package-manager} typegen` to regenerate types"
+        - "Run `{package-manager} tsc` to identify type mismatches"
+        - "Update type definitions if needed"
+        - "Check for null/undefined handling"
+      commands:
+        - "{package-manager} typegen && {package-manager} tsc"
+
+  data_sync_issues:
+    symptoms:
+      - "Missing fields in table"
+      - "Unexpected null values"
+      - "Fields showing as blank"
+      - "Type mismatches between FM and frontend"
+    first_step: "ALWAYS run `{package-manager} typegen` first"
+    cause: "Mismatch between FileMaker schema and TypeScript types, or outdated type definitions"
+    solution:
+      steps:
+        - "Run `{package-manager} typegen` to regenerate types from FileMaker schema"
+        - "Check for any type errors in the console"
+        - "Verify field names match exactly between FM and generated types"
+        - "Update components if field names have changed"
+      commands:
+        - "{package-manager} typegen"
+        - "{package-manager} tsc"
+      files_to_check:
+        - "src/config/schemas/filemaker/*.ts"
+        - "fmschema.config.mjs"
+
+maintenance_tasks:
+  schema_sync:
+    description: "Keep FileMaker schema and TypeScript types in sync"
+    frequency: "After any FileMaker schema changes"
+    steps:
+      - "Run typegen to update types"
+      - "Run TypeScript compiler"
+      - "Update affected components"
+    impact: "Prevents runtime errors and type mismatches"
+
+  type_checking:
+    description: "Regular type checking for early error detection"
+    frequency: "Before deployments and after schema changes"
+    commands:
+      - "{package-manager} tsc --noEmit"
+    impact: "Catches type errors before runtime"
+
+keywords:
+  errors:
+    - "ZodError"
+    - "TypeError"
+    - "ValidationError"
+    - "Schema mismatch"
+    - "Type mismatch"
+    - "Runtime error"
+    - "Database schema"
+    - "Type generation"
+    - "FileMaker fields"
+    - "Missing property"
+    - "Invalid type"
+    - "Layout not found"
+    - "Field not found"
+    - "Invalid find request"
+  solutions:
+    - "typegen"
+    - "tsc"
+    - "type checking"
+    - "schema update"
+    - "validation fix"
+    - "error handling"
+    - "FM API methods"
+    - "FileMaker layout"
+  operations:
+    - "layout.create"
+    - "layout.find"
+    - "layout.get"
+    - "layout.update"
+    - "layout.delete"
+    - "layout.maybeFindFirst"
+    - "recordId"
+    - "fieldData"
+    - "query parameters"
+    - "sort options"
+  data_source:
+    - "FileMaker only"
+    - "No SQL"
+    - "FM Data API"
+    - "Exclusive data source"
+    - "@proofkit/fmdapi"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule> 

package/template/extras/_cursor/rules/ui-components.mdc

@@ -0,0 +1,57 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# UI Components and Styling
+
+This rule documents the UI component library and styling conventions used in the project.
+
+<rule>
+name: ui_components
+description: Documents UI component library usage and styling conventions
+filters:
+  - type: file_extension
+    pattern: "\\.(ts|tsx)$"
+  - type: directory
+    pattern: "src/components/"
+  - type: content
+    pattern: "@mantine/"
+
+conventions:
+  component_library:
+    - Mantine v7 as primary UI framework
+    - Tabler icons for iconography
+    - Mantine React Table for data grids
+    - Custom components extend Mantine base
+  
+  styling:
+    - PostCSS for processing
+    - Mantine theme customization
+    - CSS modules for component styles
+    - CSS variables for theming
+  
+  components:
+    - Atomic design principles
+    - Consistent prop interfaces
+    - Accessibility first
+    - Responsive design patterns
+  
+  forms:
+    - React Hook Form for form state
+    - Zod for validation schemas
+    - Mantine form components
+    - Custom form layouts
+
+dependencies:
+  mantine_core: "^7.17.0"
+  mantine_hooks: "^7.17.0"
+  mantine_dates: "^7.17.0"
+  mantine_notifications: "^7.17.0"
+  react_hook_form: "^7.54.2"
+  zod: "^3.24.2"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule> 

package/template/extras/config/_eslint.js

@@ -0,0 +1,27 @@
+/** @type {import("eslint").Linter.Config} */
+export const _initialConfig = {
+  parser: "@typescript-eslint/parser",
+  parserOptions: { project: true },
+  plugins: ["@typescript-eslint"],
+  extends: [
+    "next/core-web-vitals",
+    "plugin:@typescript-eslint/recommended-type-checked",
+    "plugin:@typescript-eslint/stylistic-type-checked",
+  ],
+  rules: {
+    "@typescript-eslint/array-type": "off",
+    "@typescript-eslint/consistent-type-definitions": "off",
+    "@typescript-eslint/consistent-type-imports": [
+      "warn",
+      { prefer: "type-imports", fixStyle: "inline-type-imports" },
+    ],
+    "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+    "@typescript-eslint/require-await": "off",
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-misused-promises": [
+      "error",
+      { checksVoidReturn: { attributes: false } },
+    ],
+    "@typescript-eslint/no-floating-promises": "warn",
+  },
+};

package/template/extras/config/_prettier.config.js

@@ -0,0 +1,6 @@
+/** @type {import('prettier').Config & import('prettier-plugin-tailwindcss').PluginOptions} */
+const config = {
+  plugins: ["prettier-plugin-tailwindcss"],
+};
+
+export default config;

package/template/extras/config/drizzle-config-mysql.ts

@@ -0,0 +1,12 @@
+import { type Config } from "drizzle-kit";
+
+import { env } from "~/env";
+
+export default {
+  schema: "./src/server/db/schema.ts",
+  dialect: "mysql",
+  dbCredentials: {
+    url: env.DATABASE_URL,
+  },
+  tablesFilter: ["project1_*"],
+} satisfies Config;

package/template/extras/config/drizzle-config-postgres.ts

@@ -0,0 +1,12 @@
+import { type Config } from "drizzle-kit";
+
+import { env } from "~/env";
+
+export default {
+  schema: "./src/server/db/schema.ts",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: env.DATABASE_URL,
+  },
+  tablesFilter: ["project1_*"],
+} satisfies Config;

package/template/extras/config/drizzle-config-sqlite.ts

@@ -0,0 +1,12 @@
+import { type Config } from "drizzle-kit";
+
+import { env } from "~/env";
+
+export default {
+  schema: "./src/server/db/schema.ts",
+  dialect: "sqlite",
+  dbCredentials: {
+    url: env.DATABASE_URL,
+  },
+  tablesFilter: ["project1_*"],
+} satisfies Config;

package/template/extras/config/fmschema.config.mjs

@@ -0,0 +1,9 @@
+/** @type {import("@proofkit/fmdapi/dist/utils/typegen/types.d.ts").GenerateSchemaOptions} */
+export const config = {
+  clientSuffix: "Layout",
+  schemas: [
+    // add your layouts and name schemas here
+  ],
+  clearOldFiles: true,
+  path: "./src/config/schemas/filemaker",
+};

package/template/extras/config/get-query-client.ts

@@ -0,0 +1,6 @@
+import { QueryClient } from "@tanstack/react-query";
+import { cache } from "react";
+
+// cache() is scoped per request, so we don't leak data between requests
+const getQueryClient = cache(() => new QueryClient());
+export default getQueryClient;

package/template/extras/config/postcss.config.cjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    tailwindcss: {},
+  },
+};
+
+module.exports = config;

package/template/extras/config/query-provider-vite.tsx

@@ -0,0 +1,19 @@
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+
+const queryClient = new QueryClient();
+
+export default function QueryProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools />
+    </QueryClientProvider>
+  );
+}

package/template/extras/config/query-provider.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import { QueryClientProvider } from "@tanstack/react-query";
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+
+import getQueryClient from "./get-query-client";
+
+export default function QueryProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const queryClient = getQueryClient();
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools />
+    </QueryClientProvider>
+  );
+}

package/template/extras/emailProviders/none/email.tsx

@@ -0,0 +1,24 @@
+import { render } from "@react-email/render";
+import { AuthCodeEmail } from "@/emails/auth-code";
+
+export async function sendEmail({
+  to,
+  code,
+  type,
+}: {
+  to: string;
+  code: string;
+  type: "verification" | "password-reset";
+}) {
+  // this is the HTML body of the email to be send
+  const body = await render(
+    <AuthCodeEmail validationCode={code} type={type} />
+  );
+  const subject = type === "verification" ? "Verify Your Email" : "Reset Your Password"
+  
+  // TODO: Customize this function to actually send the email to your users
+  // Learn more: https://proofkit.dev/auth/fm-addon
+  console.warn("TODO: Customize this function to actually send to your users");
+  console.log(`To ${to}: Your ${type} code is ${code}`);
+}
+

package/template/extras/emailProviders/plunk/email.tsx

@@ -0,0 +1,26 @@
+import { render } from "@react-email/render";
+import { AuthCodeEmail } from "@/emails/auth-code";
+import { plunk } from "../services/plunk";
+
+export async function sendEmail({
+  to,
+  code,
+  type,
+}: {
+  to: string;
+  code: string;
+  type: "verification" | "password-reset";
+}) {
+  // this is the HTML body of the email to be send
+  const body = await render(
+    <AuthCodeEmail validationCode={code} type={type} />
+  );
+  const subject = type === "verification" ? "Verify Your Email" : "Reset Your Password"
+  
+  await plunk.emails.send({
+    to,
+    subject,
+    body,
+  });
+}
+

package/template/extras/emailProviders/plunk/service.ts

@@ -0,0 +1,4 @@
+import Plunk from "@plunk/node";
+import { env } from "@/config/env";
+
+export const plunk = new Plunk(env.PLUNK_API_KEY);

package/template/extras/emailProviders/resend/email.tsx

@@ -0,0 +1,23 @@
+import { AuthCodeEmail } from "@/emails/auth-code";
+import { resend } from "../services/resend";
+
+export async function sendEmail({
+  to,
+  code,
+  type,
+}: {
+  to: string;
+  code: string;
+  type: "verification" | "password-reset";
+}) {
+  const subject =
+    type === "verification" ? "Verify Your Email" : "Reset Your Password";
+
+  await resend.emails.send({
+    // TODO: Change this to our own email after verifying your domain with Resend
+    from: "ProofKit <onboarding@resend.dev>",
+    to,
+    subject,
+    react: <AuthCodeEmail validationCode={code} type={type} />,
+  });
+}

package/template/extras/emailProviders/resend/service.ts

@@ -0,0 +1,4 @@
+import { Resend } from "resend";
+import { env } from "@/config/env";
+
+export const resend = new Resend(env.RESEND_API_KEY);

package/template/extras/fmaddon-auth/app/(main)/auth/profile/actions.ts

@@ -0,0 +1,93 @@
+"use server";
+import { actionClient } from "@/server/safe-action";
+import { updateEmailSchema, updatePasswordSchema } from "./schema";
+import {
+  createSession,
+  generateSessionToken,
+  getCurrentSession,
+  invalidateUserSessions,
+  setSessionTokenCookie,
+} from "@/server/auth/utils/session";
+import {
+  checkEmailAvailability,
+  updateUserPassword,
+  validateLogin,
+} from "@/server/auth/utils/user";
+import {
+  createEmailVerificationRequest,
+  sendVerificationEmail,
+  setEmailVerificationRequestCookie,
+} from "@/server/auth/utils/email-verification";
+import { redirect } from "next/navigation";
+import { verifyPasswordHash } from "@/server/auth/utils/password";
+import { verifyPasswordStrength } from "@/server/auth/utils/password";
+
+export const updateEmailAction = actionClient
+  .schema(updateEmailSchema)
+  .action(async ({ parsedInput }) => {
+    const { session, user } = await getCurrentSession();
+    if (session === null) {
+      return {
+        message: "Not authenticated",
+      };
+    }
+
+    const { email } = parsedInput;
+
+    const emailAvailable = await checkEmailAvailability(email);
+    if (!emailAvailable) {
+      return {
+        error: "This email is already used",
+      };
+    }
+
+    const verificationRequest = await createEmailVerificationRequest(
+      user.id,
+      email
+    );
+    await sendVerificationEmail(
+      verificationRequest.email,
+      verificationRequest.code
+    );
+    await setEmailVerificationRequestCookie(verificationRequest);
+    return redirect("/auth/verify-email");
+  });
+
+export const updatePasswordAction = actionClient
+  .schema(updatePasswordSchema)
+  .action(async ({ parsedInput }) => {
+    const { confirmNewPassword, currentPassword, newPassword } = parsedInput;
+
+    const { session, user } = await getCurrentSession();
+    if (session === null) {
+      return {
+        error: "Not authenticated",
+      };
+    }
+
+    const strongPassword = await verifyPasswordStrength(newPassword);
+    if (!strongPassword) {
+      return {
+        error: "Weak password",
+      };
+    }
+
+    const validPassword = Boolean(
+      await validateLogin(user.email, currentPassword)
+    );
+    if (!validPassword) {
+      return {
+        error: "Incorrect password",
+      };
+    }
+
+    await invalidateUserSessions(user.id);
+    await updateUserPassword(user.id, newPassword);
+
+    const sessionToken = generateSessionToken();
+    const newSession = await createSession(sessionToken, user.id);
+    await setSessionTokenCookie(sessionToken, newSession.expiresAt);
+    return {
+      message: "Password updated",
+    };
+  });

package/template/extras/fmaddon-auth/app/(main)/auth/profile/page.tsx

@@ -0,0 +1,27 @@
+import { getCurrentSession } from "@/server/auth/utils/session";
+import { Anchor, Container, Paper, Stack, Text, Title } from "@mantine/core";
+import { redirect } from "next/navigation";
+import UpdateEmailForm from "./profile-form";
+import UpdatePasswordForm from "./reset-password-form";
+// import EmailVerificationForm from "./email-verification-form";
+
+export default async function Page() {
+  const { user } = await getCurrentSession();
+
+  if (user === null) {
+    return redirect("/auth/login");
+  }
+
+  return (
+    <Container size={420} my={40}>
+      <Title ta="center">Profile Details</Title>
+
+      <Paper withBorder shadow="md" p={30} mt={30} radius="md">
+        <Stack>
+          <UpdateEmailForm currentEmail={user.email} />
+          <UpdatePasswordForm />
+        </Stack>
+      </Paper>
+    </Container>
+  );
+}