@proofkit/cli 1.0.0-beta.0

package/template/extras/_cursor/conditional-rules/nextjs-framework.mdc

@@ -0,0 +1,51 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Next.js Framework Configuration
+
+This rule documents the Next.js framework setup and conventions used in this project.
+
+<rule>
+name: nextjs_framework
+description: Documents Next.js framework setup, routing conventions, and best practices
+filters:
+  - type: file_extension
+    pattern: "\\.(ts|tsx)$"
+  - type: directory
+    pattern: "src/(app|components)/"
+
+conventions:
+  routing:
+    - App Router is used (not Pages Router)
+    - Routes are defined in src/app directory
+    - Layout components should be named layout.tsx
+    - Page components should be named page.tsx
+    - Loading states should be in loading.tsx
+    - Error boundaries should be in error.tsx
+  
+  components:
+    - React Server Components (RSC) are default
+    - Client components must be marked with "use client"
+    - Components live in src/components/
+    - Shared layouts in src/components/layouts/
+    - UI components in src/components/ui/
+  
+  data_fetching:
+    - Server components fetch data directly
+    - Client components use React Query
+    - API routes defined in src/app/api/
+    - Server actions used for mutations
+
+frameworks:
+  next: "15.1.7"
+  react: "19.0.0-rc"
+  typescript: "^5"
+  mantine: "^7.17.0"
+  tanstack_query: "^5.59.0"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule> 

package/template/extras/_cursor/conditional-rules/npm.mdc

@@ -0,0 +1,60 @@
+---
+description: |
+  This rule documents the package manager configuration and usage. It should be included when:
+  1. Installing dependencies
+  2. Running scripts
+  3. Managing project packages
+  4. Running development commands
+  5. Executing build or test operations
+globs:
+  - "package.json"
+  - "package-lock.json"
+  - ".npmrc"
+alwaysApply: true
+---
+# Package Manager Configuration
+
+This rule documents the package manager setup and usage requirements.
+
+<rule>
+name: package_manager
+description: Documents package manager configuration and usage requirements
+
+configuration:
+  name: "npm"
+  version: "latest"
+  commands:
+    install: "npm install"
+    build: "npm run build"
+    dev: "npm run dev"
+    typegen: "npm run typegen"
+    typecheck: "npm run tsc"
+  notes: "Always use npm instead of yarn or pnpm for consistency"
+  dev_server_guidelines:
+    - "Never relaunch the dev server command if it may already be running"
+    - "Use npm run dev only when explicitly needed to start the server for the first time"
+    - "For code changes, just save the files and the server will automatically reload"
+
+examples:
+  - description: "Installing dependencies"
+    correct: "npm install"
+    incorrect: 
+      - "pnpm install"
+      - "yarn install"
+  
+  - description: "Running scripts"
+    correct: "npm run script-name"
+    incorrect:
+      - "pnpm run script-name"
+      - "yarn script-name"
+
+  - description: "Adding dependencies"
+    correct: "npm install package-name"
+    incorrect:
+      - "pnpm add package-name"
+      - "yarn add package-name"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule> 

package/template/extras/_cursor/conditional-rules/pnpm.mdc

@@ -0,0 +1,65 @@
+---
+description: |
+globs: 
+alwaysApply: true
+---
+---
+description: |
+  This rule documents the package manager configuration and usage. It should be included when:
+  1. Installing dependencies
+  2. Running scripts
+  3. Managing project packages
+  4. Running development commands
+  5. Executing build or test operations
+globs:
+  - "package.json"
+  - "pnpm-lock.yaml"
+  - ".npmrc"
+alwaysApply: true
+---
+# Package Manager Configuration
+
+This rule documents the package manager setup and usage requirements.
+
+<rule>
+name: package_manager
+description: Documents package manager configuration and usage requirements
+
+configuration:
+  name: "pnpm"
+  version: "latest"
+  commands:
+    install: "pnpm install"
+    build: "pnpm build"
+    dev: "pnpm dev"
+    typegen: "pnpm typegen"
+    typecheck: "pnpm tsc"
+  notes: "Always use pnpm instead of npm or yarn for consistency"
+  dev_server_guidelines:
+    - "Never relaunch the dev server command if it may already be running"
+    - "Use pnpm dev only when explicitly needed to start the server for the first time"
+    - "For code changes, just save the files and the server will automatically reload"
+
+examples:
+  - description: "Installing dependencies"
+    correct: "pnpm install"
+    incorrect: 
+      - "npm install"
+      - "yarn install"
+  
+  - description: "Running scripts"
+    correct: "pnpm run script-name"
+    incorrect:
+      - "npm run script-name"
+      - "yarn script-name"
+
+  - description: "Adding dependencies"
+    correct: "pnpm add package-name"
+    incorrect:
+      - "npm install package-name"
+      - "yarn add package-name"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule> 

package/template/extras/_cursor/conditional-rules/yarn.mdc

@@ -0,0 +1,60 @@
+---
+description: |
+  This rule documents the package manager configuration and usage. It should be included when:
+  1. Installing dependencies
+  2. Running scripts
+  3. Managing project packages
+  4. Running development commands
+  5. Executing build or test operations
+globs:
+  - "package.json"
+  - "yarn.lock"
+  - ".yarnrc"
+alwaysApply: true
+---
+# Package Manager Configuration
+
+This rule documents the package manager setup and usage requirements.
+
+<rule>
+name: package_manager
+description: Documents package manager configuration and usage requirements
+
+configuration:
+  name: "yarn"
+  version: "latest"
+  commands:
+    install: "yarn install"
+    build: "yarn build"
+    dev: "yarn dev"
+    typegen: "yarn typegen"
+    typecheck: "yarn tsc"
+  notes: "Always use yarn instead of npm or pnpm for consistency"
+  dev_server_guidelines:
+    - "Never relaunch the dev server command if it may already be running"
+    - "Use yarn dev only when explicitly needed to start the server for the first time"
+    - "For code changes, just save the files and the server will automatically reload"
+
+examples:
+  - description: "Installing dependencies"
+    correct: "yarn install"
+    incorrect: 
+      - "npm install"
+      - "pnpm install"
+  
+  - description: "Running scripts"
+    correct: "yarn script-name"
+    incorrect:
+      - "npm run script-name"
+      - "pnpm run script-name"
+
+  - description: "Adding dependencies"
+    correct: "yarn add package-name"
+    incorrect:
+      - "npm install package-name"
+      - "pnpm add package-name"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule> 

package/template/extras/_cursor/rules/cursor-rules.mdc

@@ -0,0 +1,88 @@
+---
+description: |
+  This rule documents how to manage and organize Cursor rules. It should be included when:
+  1. Creating or modifying Cursor rules
+  2. Organizing documentation for the codebase
+  3. Setting up new development patterns
+  4. Adding project-wide conventions
+  5. Managing rule file locations
+  6. Updating rule descriptions or globs
+  7. Working with .cursor directory structure
+globs:
+  - ".cursor/rules/*.mdc"
+  - ".cursor/config/*.json"
+  - ".cursor/settings/*.json"
+alwaysApply: true
+---
+# Cursor Rules Location
+
+Rules for placing and organizing Cursor rule files in the repository.
+
+<rule>
+name: cursor_rules_location
+description: Standards for placing Cursor rule files in the correct directory
+filters:
+  # Match any .mdc files
+  - type: file_extension
+    pattern: "\\.mdc$"
+  # Match files that look like Cursor rules
+  - type: content
+    pattern: "(?s)<rule>.*?</rule>"
+  # Match file creation events
+  - type: event
+    pattern: "file_create"
+
+actions:
+  - type: reject
+    conditions:
+      - pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)"
+        message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory"
+
+  - type: suggest
+    message: |
+      When creating Cursor rules:
+
+      1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
+         ```
+         .cursor/rules/
+         ├── your-rule-name.mdc
+         ├── another-rule.mdc
+         └── ...
+         ```
+
+      2. Follow the naming convention:
+         - Use kebab-case for filenames
+         - Always use .mdc extension
+         - Make names descriptive of the rule's purpose
+
+      3. Directory structure:
+         ```
+         PROJECT_ROOT/
+         ├── .cursor/
+         │   └── rules/
+         │       ├── your-rule-name.mdc
+         │       └── ...
+         └── ...
+         ```
+
+      4. Never place rule files:
+         - In the project root
+         - In subdirectories outside .cursor/rules
+         - In any other location
+         - Inside of the cursor-rules.mdc file
+
+examples:
+  - input: |
+      # Bad: Rule file in wrong location
+      rules/my-rule.mdc
+      my-rule.mdc
+      .rules/my-rule.mdc
+
+      # Good: Rule file in correct location
+      .cursor/rules/my-rule.mdc
+    output: "Correctly placed Cursor rule file"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

package/template/extras/_cursor/rules/filemaker-api.mdc

@@ -0,0 +1,176 @@
+---
+description: |
+  This rule provides guidance for working with the FileMaker Data API in this project. It should be included when:
+  1. Working with database operations or data fetching
+  2. Encountering database-related errors or type issues
+  3. Making changes to FileMaker schemas or layouts
+  4. Implementing new data access patterns
+  5. Discussing alternative data storage solutions
+  6. Working with server-side API routes or actions
+globs: 
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+  - "**/fmschema.config.mjs"
+  - "src/**/actions/*.ts"
+alwaysApply: true
+---
+# FileMaker Data API Integration
+
+This rule documents how the FileMaker Data API is integrated and used in the project.
+
+<rule>
+name: filemaker_api
+description: Documents FileMaker Data API integration patterns and conventions. FileMaker is the ONLY data source for this application - no SQL or other databases should be used.
+filters:
+  - type: file_extension
+    pattern: "\\.(ts|tsx)$"
+  - type: directory
+    pattern: "src/server/"
+  - type: content
+    pattern: "(@proofkit/cli|ZodError|typegen)"
+
+data_source_policy:
+  exclusive_source: "FileMaker Data API"
+  prohibited:
+    - "SQL databases"
+    - "NoSQL databases"
+    - "Local storage for persistent data"
+    - "Direct file system storage"
+  reason: "All data operations must go through FileMaker to maintain data integrity and business logic"
+
+troubleshooting:
+  priority_order:
+    - "ALWAYS run `{package-manager} typegen` first for ANY data loading issues"
+    - "DO NOT check environment variables unless you have a specific error message pointing to them"
+    - "Check for FileMaker schema changes"
+    - "Verify type definitions match current schema"
+    - "Review Zod validation errors"
+  rationale: "Most data loading issues are resolved by running typegen. Environment variables are rarely the cause of data loading problems and should not be investigated unless specific error messages indicate an authentication or connection issue."
+
+conventions:
+  api_setup:
+    - Uses @proofkit/fmdapi package version ^5.0.0
+    - Configuration in fmschema.config.mjs
+    - Environment variables in .env for connection details
+    - Type generation via `{package-manager} typegen` command
+  
+  data_access:
+    - ALL data operations MUST use FileMaker Data API
+    - Server-side only API calls via @proofkit/fmdapi
+    - Type-safe database operations
+    - Centralized error handling
+    - Connection pooling and session management
+    - No direct database connections outside FileMaker
+  
+  data_operations:
+    create:
+      - Use layout.create({ fieldData: {...} })
+      - Validate input against Zod schemas
+      - Returns recordId of created record
+      - Handle duplicates via FileMaker business logic
+    read:
+      - Use layout.get({ recordId }) for single record by ID
+      - Use layout.find({ query, limit, offset, sort }) for multiple records
+      - Use layout.maybeFindFirst({ query }) for optional single record
+      - Support for complex queries and sorting
+    update:
+      - Use layout.update({ recordId, fieldData })
+      - Follow FileMaker field naming conventions
+      - Respect FileMaker validation rules
+    delete:
+      - Use layout.delete({ recordId })
+      - Respect FileMaker deletion rules
+      - Handle cascading deletes via FileMaker
+    query_options:
+      - Limit and offset for pagination
+      - Sort by multiple fields with ascend/descend
+      - Complex query criteria with operators (==, *, etc.)
+      - Optional type-safe responses with Zod validation
+
+  security:
+    - Credentials stored in environment variables
+    - No direct client-side FM API access
+    - API routes validate authentication
+    - Data sanitization before queries
+    - All database access through FileMaker only
+
+type_generation:
+  process:
+    - "IMPORTANT: Running `{package-manager} typegen` solves almost all data loading problems"
+    - "Run `{package-manager} typegen` after any FileMaker schema changes"
+    - "Run `{package-manager} typegen` as first step when troubleshooting data issues"
+    - "Types are generated from FileMaker database schema"
+    - "Generated types are used in server actions and components"
+    - "Zod schemas validate runtime data against types"
+  
+  common_issues:
+    schema_changes:
+      symptoms:
+        - "No data appearing in tables"
+        - "ZodError during runtime"
+        - "Missing or renamed fields"
+        - "Type mismatches in responses"
+        - "Empty query results"
+      solution: "ALWAYS run `{package-manager} typegen && {package-manager} tsc` first"
+      important_note: "Do NOT check environment variables as a cause for data loading problems unless you have a specific known error that points to environment variables. Most data loading issues are resolved by running typegen."
+    
+    field_types:
+      symptoms:
+        - "Unexpected null values"
+        - "Type conversion errors"
+        - "Invalid date formats"
+      solution: "Update Zod schemas and type definitions"
+
+  security_notes:
+    - "Never display, log, or commit environment variables"
+    - "Never check environment variable values directly"
+    - "Keep .env files out of version control"
+    - "When troubleshooting, only verify if variables exist, never their values"
+
+patterns:
+  - Server actions wrap FM API calls
+  - Type definitions generated from FM schema
+  - Error boundaries for FM API errors
+  - Rate limiting on API routes
+  - Caching strategies for frequent queries
+
+dependencies:
+  fmdapi: "@proofkit/fmdapi@^5.0.0"
+  proofkit: "@proofkit/cli@^1.0.0"
+
+keywords:
+  database:
+    - "FileMaker"
+    - "FMREST"
+    - "Database schema"
+    - "Field types"
+    - "Type generation"
+    - "Schema changes"
+    - "Exclusive data source"
+    - "No SQL"
+    - "FileMaker only"
+    - "Data API"
+  errors:
+    - "ZodError"
+    - "TypeError"
+    - "ValidationError"
+    - "Missing field"
+    - "Runtime error"
+  commands:
+    - "typegen"
+    - "tsc"
+    - "type checking"
+    - "schema update"
+  operations:
+    - "FM.create"
+    - "FM.find"
+    - "FM.get"
+    - "FM.update"
+    - "FM.delete"
+    - "FileMaker layout"
+    - "FileMaker query"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>