@mallardbay/cursor-rules 1.0.35 → 1.1.0

package/.cursor/frontend-mobile/rules/react-native.mdc

@@ -1,92 +0,0 @@
----
-description: React Native specific conventions for styling, component structure, and patterns that complement the general UI and TypeScript rules
-globs:
-alwaysApply: true
----
-
-# React Native Development Standards
-
-These rules extend the general UI, TypeScript, and code quality standards with React Native specific conventions.
-
-## Styling
-
-### File Ordering for Styles
-
-StyleSheet definitions must live at the **bottom** of the file, after all component and helper definitions—following the same principle as types. This keeps the scannable, important logic (exports, components, hooks) at the top.
-
-**File ordering for RN component files:**
-
-1. Imports
-2. Constants
-3. Exported components / functions
-4. Helpers and non-exported definitions
-5. Types (when not imported)
-6. StyleSheet definitions (`StyleSheet.create`)
-
-### Prefer Hook-Based Styling Over Static StyleSheets
-
-When styles need access to **theme values, colors, spacing, or any dynamic context**, use a `useStyles` hook pattern instead of a top-level `StyleSheet.create`. This avoids hardcoding values that should come from the theme and prevents painful refactors later.
-
-- **Use `StyleSheet.create` only for truly static styles** that will never need theme values
-- **Use a `useStyles` hook** when styles depend on theme, colors, spacing, or dynamic values
-- Even when using `StyleSheet.create`, place it at the bottom of the file
-
-```typescript
-// Preferred: hook-based styling with theme access
-function useStyles() {
-    const theme = useTheme()
-
-    return useMemo(
-        () =>
-            StyleSheet.create({
-                container: {
-                    padding: theme.space[4],
-                    backgroundColor: theme.colors.background,
-                },
-                title: {
-                    fontSize: theme.fontSizes.lg,
-                    color: theme.colors.text,
-                },
-            }),
-        [theme]
-    )
-}
-```
-
-```typescript
-// Acceptable: static styles that genuinely don't need theme
-// BUT must be at the BOTTOM of the file
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-        alignItems: "center",
-    },
-})
-```
-
-### Avoid Hardcoded Style Values
-
-- Never hardcode colors — use theme colors
-- Never hardcode spacing — use theme spacing
-- Never hardcode font sizes — use theme typography
-- If you find yourself reaching for a hardcoded value in `StyleSheet.create`, that's a signal to switch to `useStyles`
-
-## Performance
-
-### Lists
-
-- Use `FlatList` or `SectionList` for long lists — never `ScrollView` with `.map()`
-- Always provide a `keyExtractor`
-- Use `getItemLayout` when item heights are known for better scroll performance
-- Memoize `renderItem` callbacks with `useCallback`
-
-### Images
-
-- Use cached image libraries (e.g., `react-native-fast-image`) over the default `Image` when dealing with remote URLs
-- Always specify image dimensions to avoid layout thrashing
-
-### Animations
-
-- Prefer `react-native-reanimated` over `Animated` API for complex animations
-- Run animations on the UI thread when possible
-- Avoid JS-driven animations for performance-critical interactions

package/.cursor/rules/code-quality.mdc

@@ -1,55 +0,0 @@
----
-description: Defines structure, naming, reuse, and dependency guidelines to ensure clean, maintainable, and consistent TypeScript code across the project—favoring pragmatism, proven libraries, and shared conventions.
-alwaysApply: false
----
-
-# Code Quality Standards
-
-## Code Structure
-
--   Maximum file length: 200 lines
--   Maximum function length: 50 lines
--   Naming conventions:
-    -   Components: PascalCase
-    -   Functions: camelCase
-    -   Constants: UPPER_SNAKE_CASE
-    -   Types: PascalCase
--   Exported functions/components should be defined before non-exported helpers
--   Types should be defined at the bottom of files or moved into separate `types` files when reused across files
--   Keep React component props near component definitions for readability
--   PropTypes should be defined before component definitions
--   Prefer using alias for importing components. Only use relative for tests or when there's a direct sibling
-
-## Code Reuse
-
--   Use shared libraries to avoid duplication
--   Primary libraries to use:
-    -   [@mallardbay/lib-react-components](mdc:package.json)
-    -   [@mallardbay/lib-shared-helpers](mdc:package.json)
-
-## Third party libraries
-
--   Favor battle-tested libraries over custom solutions. If a well-maintained, widely-used library solves the problem cleanly, use it. Reinventing functionality that’s already solid, reliable, and well-documented usually leads to more bugs, more maintenance, and wasted time.
--   Prioritize stability and ecosystem fit. Pick libraries that are actively maintained, have strong adoption, and fit well within our existing tech stack. Avoid fringe or unmaintained packages unless there’s a strong reason.
--   Suggest existing libraries during code review. If you spot hand-rolled code that could be replaced with a proven library, flag it. Examples:
--   Use zod or yup instead of custom input validation
--   Use date-fns instead of writing date math from scratch
--   Use radash for utility-heavy logic if readability or testability improves
--   Use react-hook-form for complex form state handling
--   Be pragmatic. Sometimes a simple custom solution is faster and easier than pulling in a heavy dependency—but always weigh short-term gains against long-term cost.
--   Make reuse easy. If we do build something custom, design it to be clean, reusable, and well-documented. That way, we’re not creating another wheel, but investing in something worth maintaining.
-
-## String Constants
-
--   Use constants instead of string literals for:
-    -   Copy text (UI content). Most projects have a `copy-constants` file
-    -   Test IDs. Most projects have `TEST_IDS` defined
-    -   Error messages
-    -   URLs
--   Source constants from:
-    -   @mallardbay/lib-shared-helpers
-    -   Local constants files
-
-## Cursor Rules
-
--   Suggest cursor rules as needed

package/.cursor/rules/code-review.mdc

@@ -1,46 +0,0 @@
----
-description: Outlines expectations for pull request size, test coverage, documentation, and review process—promoting focused, well-tested, and maintainable contributions that align with team standards and improve review efficiency.
-alwaysApply: false
----
-
-# Code Review Standards
-
-## Pull Request Guidelines
-
-### Size Requirements
-
--   Maximum PR size: 400 lines
--   Split large changes into smaller, focused PRs
--   Keep changes atomic and focused
--   Consider impact on review process
-
-## Testing Requirements
-
-Ensure comprehensive test coverage:
-
-### Test Coverage
-
--   All new code must include tests
--   Follow testing standards in [testing.mdc](mdc:.cursor/rules/testing.mdc)
--   Include unit tests for new functionality
--   Avoid making a ton of changes to existing tests while refactoring
-
-### Code Documentation
-
--   Document complex logic with comments
--   Explain non-obvious implementation details
--   Document features added and important caveats in README
-
-### Review Process
-
--   Review for code quality
--   Check for test coverage
--   Verify documentation
--   Ensure adherence to project standards
-
-## Best Practices
-
--   Keep PRs focused and manageable
--   Include clear PR descriptions
--   Reference related issues/tickets
--   Respond to review comments promptly

package/.cursor/rules/error-handling.mdc

@@ -1,48 +0,0 @@
----
-description: Defines consistent patterns for API and form error handling—focusing on clear user feedback, robust validation, and reliable logging to improve user experience, developer debugging, and overall app resilience.
-alwaysApply: false
----
-
-# Error Handling Standards
-
-## API Error Handling
-
-Implement comprehensive API error handling
-
-### Error Types
-
--   Handle network errors
--   Handle server errors
--   Handle validation errors
--   Handle Apollo-specific errors
-
-### Error Presentation
-
--   Show error toasts for user feedback
--   Use original error messages when appropriate
--   Provide clear, actionable error messages
--   Log errors for debugging
-
-## Form Validation
-
-Implement robust form validation
-
--   Validate all user inputs
--   Show validation errors clearly
--   Handle form submission errors
--   Use [@hookform/resolvers](mdc:package.json) for validation
-
-### Error Display
-
--   Show validation errors inline
--   Provide clear error messages
--   Highlight invalid fields
--   Prevent form submission with invalid data
-
-## Best Practices
-
--   Use try-catch blocks appropriately
--   Implement proper error boundaries
--   Log errors for debugging
--   Provide user-friendly error messages
--   Handle edge cases gracefully

package/.cursor/rules/general-best-practices.mdc

@@ -1,190 +0,0 @@
----
-description: Core development principles and best practices that always apply—optimized for AI agents to produce clean, maintainable, reviewable code with low cognitive complexity, clear semantics, and incremental changes.
-alwaysApply: true
----
-
-# General Best Practices
-
-These principles apply to all code changes and should guide every implementation decision.
-
-## Core Principles
-
-### DRY (Don't Repeat Yourself)
-- Extract common logic into reusable functions, utilities, or shared modules
-- Leverage existing patterns and utilities before creating new ones
-- When duplicating code, ask: "Can this be abstracted?"
-- Prefer composition and shared utilities over copy-paste solutions
-
-### Leverage Existing Patterns
-- **Always** search the codebase for similar implementations before creating new code
-- Follow established patterns, conventions, and architectural decisions
-- Use existing utilities, helpers, and shared libraries
-- Match the style and structure of related files
-- When patterns exist, use them consistently—don't invent new approaches without justification
-
-### Incremental Changes
-- **Minimize large changes in a single PR or commit**
-- Break large features into smaller, testable increments
-- Make changes that are easy to review and understand
-- Prefer multiple small PRs over one massive change
-- Each change should be independently testable and reviewable
-- If a change touches many files, consider splitting it into logical phases
-
-### Semantic Clarity
-- Use **semantic, self-documenting names** for functions, variables, and types
-- Function names should clearly describe what they do (e.g., `calculateTotalPrice` not `calc`)
-- Variable names should express intent (e.g., `userAccountBalance` not `bal`)
-- Terminology should be consistent across the codebase
-- Avoid abbreviations unless they're widely understood in the domain
-- Names should make code readable without comments
-
-### Cognitive Complexity
-- **Keep cognitive complexity low**—code should be easy to understand at a glance
-- Prefer early returns and guard clauses over deep nesting
-- Break complex logic into smaller, well-named functions
-- Maximum nesting depth: 3 levels
-- Use intermediate variables to clarify intent
-- Extract complex conditionals into named boolean functions
-- Avoid deeply nested ternaries—use if/else or extract to function
-
-### Separation of Concerns
-- **Files**: Each file should have a single, clear responsibility
-- **Functions**: Each function should do one thing well
-- Separate business logic from presentation, data access, and side effects
-- Keep UI components focused on rendering and user interaction
-- Extract business logic into pure functions or services
-- Avoid god objects or functions that do too much
-
-## Code Quality Standards
-
-### Avoid "AI Slop"
-- **Write code that's easy for humans to review**
-- Avoid generating large amounts of code without understanding context
-- Don't create unnecessary abstractions or over-engineered solutions
-- Remove unused code, imports, and dead branches
-- Clean up commented-out code and debugging statements
-- If an approach doesn't work, **clean up failed attempts** before trying another
-- Keep only relevant, working code—remove experimental code that didn't pan out
-
-### Testing and Linting
-- **Lint and test files related to your changes** before completing work
-- Run linters on modified files and fix issues
-  - Use `yarn lint:quiet` for quick iterations
-  - Use `yarn lint:quiet:slow` for deeper checks but slower when wrapping up
-- **Never disable eslint rules** to make lint errors go away—fix the underlying issues instead
-  - Do not add `eslint-disable` comments unless there's a legitimate, documented reason
-  - Do not modify eslint config files to disable rules that are flagging real problems
-  - If a rule seems incorrect, investigate why it exists and fix the code properly
-- Run tests for affected modules, not the entire test suite unnecessarily
-- For large changes: **use test sharding**—split tests across multiple runs
-- **Do not run all tests in parallel** when dealing with many changes
-- Tests should be **clear, fast, and minimize setup duplication**
-- Use shared test utilities and fixtures to reduce boilerplate
-- Each test should be independent and runnable in isolation
-
-### Before Pushing
-- **Lint the entire project** before pushing—not just modified files. Use `yarn lint:quiet:slow` for a full deep check. Your changes may introduce lint errors in files you didn't directly edit (e.g. unused exports, circular dependencies, type mismatches)
-- **Run related tests** before pushing to confirm nothing is broken. Identify test files related to your changes and run them. If unsure which tests are related, err on the side of running more rather than fewer
-- **Fix any failures before pushing**—do not push code that fails lint or tests
-- These checks are a hard gate: **no push without a clean lint and passing tests**
-
-### Code Organization
-- Group related functionality together
-- Keep related code close (cohesion)
-- Minimize dependencies between modules (loose coupling)
-- Use appropriate data structures for the problem
-- Prefer composition over inheritance
-- Make functions pure when possible (no side effects)
-- Handle edge cases explicitly—don't rely on implicit behavior
-
-### Type Safety and Clarity
-- Use TypeScript types effectively—avoid `any` unless necessary
-- Make types explicit and meaningful
-- Use const assertions and readonly where appropriate
-- Prefer `const` over `let`, avoid `var`
-- Use type guards and discriminated unions for type narrowing
-
-### Performance Considerations
-- Consider performance implications, but **avoid premature optimization**
-- Profile before optimizing—optimize bottlenecks, not everything
-- Use appropriate algorithms and data structures
-- Avoid unnecessary re-renders, re-computations, or API calls
-- Cache expensive computations when appropriate
-
-## AI Agent Workflow
-
-### Before Making Changes
-1. **Create a plan** before making changes directly—outline the approach, identify affected files, and break down the work into steps
-2. **Read existing code** to understand patterns and context
-3. **Search the codebase** for similar implementations
-4. **Check git history** to understand why code exists as it does
-5. **Identify related files** that might be affected
-6. **Ask clarifying questions** if requirements are unclear
-7. **Use MCP servers when available**—leverage Model Context Protocol servers for enhanced capabilities
-   - **Context7 MCP**: Use the context7 MCP server when available to retrieve up-to-date documentation and code examples for libraries
-   - If context7 MCP is not available, suggest adding it to improve access to library documentation
-   - **Suggest useful MCP servers**: When appropriate, suggest popular and useful MCP servers that could enhance development workflow based on the task at hand
-   - Consider MCP servers for documentation, testing, debugging, and other development tasks
-
-### During Implementation
-1. Make **small, incremental changes**
-2. **Test as you go**—verify each change works before moving on
-3. **Lint frequently**—don't accumulate lint errors
-   - Use `yarn lint:quiet` for quick iterations
-   - Use `yarn lint:quiet:slow` for deeper checks when wrapping up
-4. **Follow existing patterns**—don't reinvent the wheel
-5. **Use semantic names**—code should be self-documenting
-6. **Keep functions focused**—one responsibility per function
-7. **Extract common logic**—don't duplicate code
-
-### After Making Changes
-1. **Clean up failed attempts**—remove experimental code
-2. **Remove unused code**—imports, variables, functions
-3. **Run linters** on modified files
-   - Use `yarn lint:quiet` for quick iterations
-   - Use `yarn lint:quiet:slow` for deeper checks when wrapping up
-4. **Run relevant tests**—not the entire suite unless necessary
-5. **Verify the change works** end-to-end
-6. **Check for side effects**—ensure changes don't break unrelated code
-
-### Before Pushing
-1. **Lint the entire project** with `yarn lint:quiet:slow`—not just modified files. Fix all failures
-2. **Run related tests** and ensure they pass. If unsure which tests are related, run more rather than fewer
-3. **Do not push** until lint and tests are clean
-
-### When Changes Are Large
-1. **Consider splitting** into multiple smaller PRs
-2. **Use test sharding**—run tests in batches, not all at once
-3. **Review incrementally**—make sure each part works before moving on
-4. **Document the approach**—explain why changes are structured this way
-5. **Check impact** on related systems and files
-
-## Anti-Patterns to Avoid
-
-- ❌ Copy-pasting code instead of extracting to a function
-- ❌ Creating new patterns when existing ones work
-- ❌ Making massive changes in one go
-- ❌ Using vague names like `data`, `temp`, `value`, `thing`
-- ❌ Deeply nested conditionals and loops
-- ❌ Functions that do multiple unrelated things
-- ❌ Leaving commented-out code or debugging statements
-- ❌ Skipping tests or linting "to save time"
-- ❌ Disabling eslint rules instead of fixing the underlying issues
-- ❌ Running entire test suite for small changes
-- ❌ Leaving experimental code after failed attempts
-- ❌ Premature optimization without profiling
-- ❌ Using `any` types to avoid type errors
-- ❌ Magic numbers or strings without constants
-
-## Remember
-
-**Code is read far more often than it's written.** Write code that:
-- Is easy to understand
-- Is easy to review
-- Is easy to test
-- Is easy to modify
-- Follows established patterns
-- Has clear semantics
-- Minimizes cognitive load
-
-When in doubt, prefer clarity and simplicity over cleverness.

package/.cursor/rules/mallardbay.mdc

@@ -1,23 +0,0 @@
----
-description: Describes Mallard Bay’s mission to simplify and scale outfitter operations through purpose-built software—emphasizing real-world impact, outfitter collaboration, and a long-term vision to digitize and unify the outdoor experience industry.
-globs:
-alwaysApply: true
----
-
-# Mallard Bay: Outfitter Management System Overview
-
-Mallard Bay is a specialized platform designed to streamline operations for outfitters—businesses that offer guided outdoor experiences such as hunting, fishing, and eco-tourism. At its core, Mallard Bay operates as an outfitter management system, purpose-built to reduce administrative burden, improve customer experience, and unlock new revenue channels for guides and lodge operators.
-
-# Built for Outfitters, with Outfitters in Mind
-
-At Mallard Bay, we’re not just building software — we’re solving real problems for real people in the outfitting industry. Every feature we ship is grounded in one simple principle: if it doesn’t make an outfitter’s life easier or their business better, it doesn’t belong in our product.
-
-We work closely with outfitters of all sizes to understand their workflows, pain points, and growth challenges. From there, we prioritize meaningful features that drive efficiency, boost bookings, and enhance the guest experience.
-
-Whether it’s reducing no-shows with smart reminders, saving time through automated group booking tools, or enabling instant rebooking with dynamic availability, we’re laser-focused on delivering value — not fluff.
-
-We’re building tools that fit into the way outfitters actually work — not the way a generic booking platform thinks they should.
-
-# Vision
-
-Mallard Bay aims to be the digital backbone for the outfitting industry—a single source of truth for trip logistics, customer interaction, and business growth. The long-term goal is to transform an analog, fragmented market into a digital-first, scalable ecosystem.

package/.cursor/rules/performance.mdc

@@ -1,45 +0,0 @@
----
-description: Defines best practices for optimizing React components, rendering efficiency, and dependency management—focusing on minimizing re-renders, reducing bundle size, and enabling smooth user experiences through memoization, lazy loading, and performance-aware development.
-alwaysApply: false
----
-
-# Performance Standards
-
-## React Optimization
-
-Optimize React components for better performance:
-
-### Component Optimization
-
--   Use `React.memo` for pure components
--   Implement `useCallback` for function props
--   Use `useMemo` for expensive computations
--   Avoid inline function definitions in render
-
-## Rendering Optimization
-
-Prevent unnecessary re-renders:
-
--   Avoid inline styles in components
--   Prevent inline object creation in render
--   Use proper key props in lists
--   Memoize complex objects and callbacks
-
-### Dependencies
-
--   Prefer existing dependencies over new ones
--   Review [package.json](mdc:package.json) before adding new packages
--   Consider bundle size impact of new dependencies
--   Use tree-shaking friendly imports
-
-## Best Practices
-
--   Implement proper code splitting
--   Use lazy loading for routes and large components
--   Optimize images and assets
--   Monitor performance metrics
--   Use React DevTools for performance profiling
-
-## File Patterns
-
-These rules apply to all TypeScript and TSX files in the project.

package/.cursor/rules/testing.mdc

@@ -1,72 +0,0 @@
----
-description: Outlines practical, value-driven testing guidelines focused on reliability, developer confidence, and speed. Emphasizes high-impact coverage (not overkill), structured test organization, clear scenarios, and reusable mock/test utilities—enabling fast iteration without sacrificing quality.
-globs:
-alwaysApply: true
----
-
-# Testing Standards
-
-## Test Coverage and Structure
-
-We aim for high-impact test coverage, focused on adding value and improving developer confidence and experience. The priority is to cover critical logic, edge cases, and integration points where bugs would hurt the most. Tests should act as a safety net and enable fast, fearless iteration—not as a box-ticking exercise.
-
-We do not chase 100% coverage for its own sake. If a test doesn’t meaningfully reduce risk or help developers move faster, it’s not worth writing. The goal is smart coverage, not maximum coverage—optimize for reliability, clarity, and development speed without overengineering.
-
-**Frontend (React, React Native):** Avoid e2e tests for UI. Favor unit tests. **Backend (Node.js):** Prioritize e2e tests.
-
-### Coverage Requirements
-
--   Minimum test coverage: 80%
--   Place tests in `_tests_` directory closest to the file being tested
--   Use `.spec.ts` or `.spec.tsx` file extensions
--   Do NOT Use `.test.ts` or `.test.tsx` file extensions
-
-### Test Organization
-
--   Maximum nesting level: 2
--   Use `test` or `it` for test cases
--   Keep tests focused and atomic
--   Follow AAA pattern (Arrange, Act, Assert)
-
-### Required Scenarios
-
--   Happy path testing
--   Error case handling
--   Edge case coverage within reason. Optimize for branching logic, and avoid creating nearly identical tests
--   Aim for simplicity
--   All tests must pass before completion
-
-### Test Quality
-
--   Write clear, descriptive test names
--   Test one concept per test case
--   Avoid test interdependence
--   Use meaningful assertions
--   Avoid tests that will make the overall run slower
-
-### Component Testing
-
--   Use `renderWithProviders` for component tests
--   Use `renderHookWithProviders` for hook tests
--   Avoid mocking dependent components
--   Test component behavior, not implementation
-
-### Mocking Guidelines
-
--   Use mock helpers instead of inline mocks
--   Follow existing patterns for:
-    -   Entity mocks
-    -   Apollo mocks
-    -   Provider mocks
--   Keep mocks simple and maintainable
--   **Do not use variable matchers for Apollo mocks**—match exact variables (e.g. avoid `expect.anything()` or `variables: {}`) so tests fail when the component passes incorrect variables to queries or mutations
-
-### Test Utilities
-
--   Leverage testing utilities from [@testing-library/react](mdc:package.json)
--   Use [@testing-library/jest-dom](mdc:package.json) for DOM assertions
--   Follow established patterns in existing tests
-
-## File Patterns
-
-These rules apply to all test files with `.spec.ts` or `.spec.tsx` extensions.

package/.cursor/rules/typescript.mdc

@@ -1,29 +0,0 @@
----
-alwaysApply: true
----
-
-# TypeScript Development Standards
-
-## Type Safety
-
-Enforce comprehensive type safety across the codebase:
-
-### Strict Type Checking
-
-Be as strictly as possible where it delivers clear value—specifically in preventing bugs and improving the developer experience. The goal is to enforce strong types and catch issues early, without introducing excessive friction or overhead. If a strict setting improves safety, maintainability, or clarity, we’ll use it. If it creates noise or slows down iteration without real benefit, we’ll dial it back. This is about pragmatic strictness, not dogmatism.
-
-### File Organization
-
--   Keep exported functions/components before non-exported helpers
--   Place most types at the bottom of files or in separate `types` files when shared across files
--   Keep React component props near the component definition for readability
--   Define PropTypes before component definitions
-
-## Best Practices
-
--   Use TypeScript for all new code
--   Leverage TypeScript's type system for better code quality
--   Follow React best practices with TypeScript
--   Use proper type definitions for props and state
--   Utilize TypeScript's utility types when appropriate
--   Suggest existing libaries as needed