@mallardbay/cursor-rules 1.0.29 → 1.0.31

package/.cursor/frontend-mobile/rules/ui.mdc

@@ -0,0 +1,124 @@
+---
+description: Defines best practices for building consistent, maintainable, and library-agnostic UI in Mallard Bay React Native projects
+globs:
+alwaysApply: true
+---
+
+# UI Development Standards (React Native)
+
+## Component Abstraction Layer
+
+The mobile app uses NativeBase under the hood, but **all UI primitives must be accessed through custom wrapper components**. This abstraction enables switching to a different component library (e.g., Gluestack, Tamagui) with minimal churn.
+
+### Import Rules
+
+- **Never import directly from `native-base`** in feature code — always use the project's custom wrapper components
+- **Never import from `~components/shared/ui`** — use the abstraction layer instead
+- Wrapper components live in a dedicated directory (e.g., `src/components/primitives/` or the project's established equivalent)
+- Only the wrapper component files themselves may import from `native-base`
+
+### Wrapper Component Guidelines
+
+- Each wrapper should expose a **stable, minimal API** — only pass through props the project actually uses
+- Use TypeScript interfaces for wrapper props rather than re-exporting the library's prop types
+- Keep wrappers thin — they should delegate to the underlying library, not add business logic
+- Name wrappers after their semantic purpose (e.g., `AppText`, `AppButton`, `AppBox`) or match the library's naming if there's no ambiguity
+- Document any NativeBase-specific behavior the wrapper intentionally hides or transforms
+
+### Example Pattern
+
+```tsx
+// src/components/primitives/AppButton.tsx — ✅ Correct
+import { Button as NativeBaseButton } from "native-base"
+
+export default function AppButton(props: AppButtonProps) {
+    return <NativeBaseButton {...props} />
+}
+
+// src/features/booking/BookingCard.tsx — ✅ Correct
+import AppButton from "~components/primitives/AppButton"
+
+// src/features/booking/BookingCard.tsx — ❌ Wrong
+import { Button } from "native-base"
+import { Button } from "~components/shared/ui"
+```
+
+## Theme Usage
+
+Use theme values consistently across all components:
+
+### Colors
+
+- Use theme colors instead of hardcoded values
+- Example: `theme.colors.primary[500]` instead of `'#3B82F6'`
+
+### Spacing
+
+- Use theme spacing values for margins and padding
+- Example: `theme.space[4]` instead of numeric literals
+
+### Typography
+
+- Use theme typography settings for text styles
+- Example: `theme.fontSizes.md` instead of hardcoded numbers
+
+## Component Structure
+
+Maintain clean and consistent component structure:
+
+### Nesting
+
+- Limit component nesting to maximum depth of 3
+- Keep component hierarchy readable and maintainable
+
+### Inline Styles
+
+- Limit inline styles to maximum of 2 per component
+- Prefer theme-based styling and style props
+
+### Component Library
+
+- Use the project's custom wrapper components (abstraction layer) for all UI primitives
+- If a wrapper doesn't exist yet for a NativeBase component you need, create one in the primitives directory following the established pattern
+- Keep wrapper components minimal and focused on API stability
+
+## Platform Considerations
+
+### React Native Specifics
+
+- Use `StyleSheet.create` or NativeBase style props — avoid inline object styles
+- Prefer `FlatList` / `SectionList` over mapping arrays for long lists
+- Use platform-specific extensions (`.ios.tsx`, `.android.tsx`) only when behavior genuinely diverges
+- Test on both iOS and Android
+
+### Navigation
+
+- Follow the project's established navigation patterns (React Navigation or equivalent)
+- Keep screen components thin — delegate to feature components
+
+### Performance
+
+- Use `React.memo` for pure list item components
+- Use `useCallback` for handlers passed to list items
+- Use `useMemo` for expensive computations and filtered/sorted data
+- Avoid anonymous functions in `renderItem` and event handlers
+- Minimize bridge crossings by batching state updates
+
+## Rendering Optimization
+
+- Optimize component rendering
+- Avoid unnecessary re-renders
+- Move function definitions outside components or use `useCallback` for event handlers
+- Use `useCallback` for functions passed as props to child components
+- Use `useMemo` for expensive computations and complex data transformations
+- Memoize filtered, sorted, or mapped arrays to avoid recalculation on every render
+
+## File Patterns
+
+These rules apply to all TypeScript and TSX files in the project.
+
+## Components
+
+- Keep components small and focused on a single responsibility
+- Use functional components with hooks instead of class components
+- Prefer `export default function BookingCard() {` over `function BookingCard(): React.ReactElement | null {` when defining components

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

@@ -14,13 +14,7 @@ alwaysApply: false
     -   Functions: camelCase
     -   Constants: UPPER_SNAKE_CASE
     -   Types: PascalCase
--   Follow this ordering within files:
-    1.  Imports
-    2.  Constants
-    3.  Exported functions / components
-    4.  Helpers and other non-exported definitions
-    5.  Types (when not imported)
--   Exported members always come before non-exported members
+-   Types should be defined at the bottom of files
 -   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
 

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

@@ -69,6 +69,12 @@ These principles apply to all code changes and should guide every implementation
 ### 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
@@ -108,11 +114,18 @@ These principles apply to all code changes and should guide every implementation
 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
@@ -122,6 +135,8 @@ These principles apply to all code changes and should guide every implementation
 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
@@ -143,6 +158,7 @@ These principles apply to all code changes and should guide every implementation
 - ❌ 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

package/.cursor/rules/testing.mdc

@@ -53,14 +53,13 @@ We do not chase 100% coverage for its own sake. If a test doesn’t meaningfully
 
 ### Mocking Guidelines
 
--   **Always use mock helpers**—never define mocks inline. All mocks should come from dedicated mock helper files following existing patterns for:
+-   Use mock helpers instead of inline mocks
+-   Follow existing patterns for:
     -   Entity mocks
     -   Apollo mocks
     -   Provider mocks
--   **Mock data through Apollo mocks, not module mocks**—use Apollo mock providers to control query/mutation responses instead of mocking modules or components directly
 -   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
--   **Never mock `@mallardbay/lib-react-components`**—if truly unavoidable, stop and ask for approval first
 
 ### Test Utilities
 

package/.cursor/rules/typescript.mdc

@@ -14,13 +14,7 @@ Be as strictly as possible where it delivers clear value—specifically in preve
 
 ### File Organization
 
--   Follow this ordering within files:
-    1.  Imports
-    2.  Constants
-    3.  Exported functions / components
-    4.  Helpers and other non-exported definitions
-    5.  Types (when not imported)
--   Exported members always come before non-exported members
+-   Place types at the bottom of files
 -   Define PropTypes before component definitions
 
 ## Best Practices

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

@@ -7,6 +7,14 @@ alwaysApply: true
 
 These principles apply to all code changes and should guide every implementation decision.
 
+## Project Setup
+
+- Install dependencies with `yarn`
+- Run the project locally with `yarn start`
+- Run tests with `yarn test`
+- For large test suites, use sharding: `JEST_SHARD=1/n yarn test` where `n` is the total number of shards (never more than 10)
+  - Example: `JEST_SHARD=1/3 yarn test`, `JEST_SHARD=2/3 yarn test`, `JEST_SHARD=3/3 yarn test`
+
 ## Core Principles
 
 ### DRY (Don't Repeat Yourself)
@@ -75,8 +83,8 @@ These principles apply to all code changes and should guide every implementation
   - 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
+- Run tests with `yarn test` for affected modules, not the entire test suite unnecessarily
+- For large changes: **use test sharding** via `JEST_SHARD=1/n yarn test`—split tests across multiple shards (never more than 10)
 - **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
@@ -143,7 +151,7 @@ These principles apply to all code changes and should guide every implementation
 
 ### When Changes Are Large
 1. **Consider splitting** into multiple smaller PRs
-2. **Use test sharding**—run tests in batches, not all at once
+2. **Use test sharding** (`JEST_SHARD=1/n yarn test`)—run tests in batches, not all at once (max 10 shards)
 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

package/README.md

@@ -112,10 +112,28 @@ your-project/
 └── AGENTS.md           # Codex IDE configuration (combined rules)
 ```
 
-Both `CLAUDE.md` and `AGENTS.md` combine all applicable rules into single files, with YAML frontmatter stripped for compatibility. Each file includes header comments explaining its purpose and which tool uses it.
+Both `CLAUDE.md` and `AGENTS.md` combine all applicable rules into single files, with YAML frontmatter stripped for compatibility. Each file opens with a header comment that states the file is **auto-generated** (do not edit by hand) and that **project-specific rules** belong in `AGENTS_LOCAL.md`, plus which tool consumes the file.
 
 Skills are automatically discovered by Cursor, Claude Code, and Codex, and can be invoked with `/skill-name` in chat. The setup script copies skills to all three platform directories for cross-platform compatibility.
 
+### Project-Local Rules (`AGENTS_LOCAL.md`)
+
+If your project needs additional rules beyond what the shared configuration provides, create an `AGENTS_LOCAL.md` file in your project root. Its content will be automatically appended to both `CLAUDE.md` and `AGENTS.md` when the setup script runs.
+
+This is useful for:
+- Project-specific conventions or architectural decisions
+- Team-level overrides or additions
+- Context that only applies to a single repository
+
+```
+your-project/
+├── AGENTS_LOCAL.md    # Your project-specific rules (checked into version control)
+├── CLAUDE.md          # Generated (includes AGENTS_LOCAL.md content)
+└── AGENTS.md          # Generated (includes AGENTS_LOCAL.md content)
+```
+
+`AGENTS_LOCAL.md` is meant to be checked into version control, while `CLAUDE.md` and `AGENTS.md` are generated and should be gitignored.
+
 ## Development
 
 ### Adding New Rules

package/bin/setup-cursor.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# setup-cursor.sh — frontend & frontend-lib layering with shared base
+# setup-cursor.sh — frontend, frontend-lib, frontend-mobile & backend layering with shared base
 # Also generates CLAUDE.md for Claude Code and AGENTS.md for Codex
 
 set -e
@@ -65,6 +65,7 @@ fi
 SHARED_DIR="$SRC_DIR/.cursor/shared/rules"
 FRONTEND_DIR="$SRC_DIR/.cursor/frontend/rules"
 FRONTEND_LIB_DIR="$SRC_DIR/.cursor/frontend-lib/rules"
+FRONTEND_MOBILE_DIR="$SRC_DIR/.cursor/frontend-mobile/rules"
 BACKEND_DIR="$SRC_DIR/.cursor/backend/rules"
 SHARED_SKILLS_DIR="$SRC_DIR/.cursor/shared/skills"
 
@@ -91,8 +92,16 @@ This file provides custom instructions and project context for $tool_name.
 
 $description
 
-This file is automatically generated by @mallardbay/cursor-rules. It combines
-all applicable rules from .cursor/rules/ into a single configuration file.
+AUTO-GENERATED — DO NOT EDIT THIS FILE BY HAND. It is produced by
+@mallardbay/cursor-rules when you run the setup script (e.g. npx @mallardbay/cursor-rules <env-type>).
+Any manual changes will be overwritten on the next run.
+
+Content sources: shared and environment-specific rules copied into .cursor/rules/ as *.mdc files,
+combined here with YAML frontmatter stripped.
+
+PROJECT-SPECIFIC RULES: Add or edit AGENTS_LOCAL.md in the project root (commit that file).
+On the next setup run, its contents are appended to both CLAUDE.md and AGENTS.md. Do not put
+long-lived project-only guidance only in this file — use AGENTS_LOCAL.md instead.
 
 For more information:
 - $tool_name: See official documentation
@@ -215,12 +224,29 @@ case "$ENV_TYPE" in
     append_to_md_files "$FRONTEND_DIR"
     append_to_md_files "$FRONTEND_LIB_DIR"
     ;;
+  frontend-mobile)
+    copy_rules "$FRONTEND_MOBILE_DIR"
+    append_to_md_files "$FRONTEND_MOBILE_DIR"
+    ;;
   *)
     echo "Unknown environment type: $ENV_TYPE"
     exit 1
     ;;
 esac
 
+# Append project-local AGENTS_LOCAL.md if it exists
+if [ -f "$PROJECT_DIR/AGENTS_LOCAL.md" ]; then
+  echo "Found AGENTS_LOCAL.md — appending project-local rules"
+  echo "" >> "$CLAUDE_MD_TEMP"
+  echo "---" >> "$CLAUDE_MD_TEMP"
+  echo "" >> "$CLAUDE_MD_TEMP"
+  cat "$PROJECT_DIR/AGENTS_LOCAL.md" >> "$CLAUDE_MD_TEMP"
+  echo "" >> "$AGENTS_MD_TEMP"
+  echo "---" >> "$AGENTS_MD_TEMP"
+  echo "" >> "$AGENTS_MD_TEMP"
+  cat "$PROJECT_DIR/AGENTS_LOCAL.md" >> "$AGENTS_MD_TEMP"
+fi
+
 # Generate both CLAUDE.md and AGENTS.md
 mv "$CLAUDE_MD_TEMP" "$PROJECT_DIR/CLAUDE.md"
 mv "$AGENTS_MD_TEMP" "$PROJECT_DIR/AGENTS.md"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mallardbay/cursor-rules",
-    "version": "1.0.29",
+    "version": "1.0.31",
     "description": "Mallard Bay shared cursor rules",
     "main": "bin/setup-cursor.sh",
     "repository": "git@github.com:mallardbay/cursor-rules.git",
@@ -18,6 +18,15 @@
     "publishConfig": {
         "access": "public"
     },
+    "scripts": {
+        "test": "echo 'No tests yet'",
+        "test:ci": "echo 'No tests yet'",
+        "lint:quiet": "echo 'No linting configured yet'",
+        "release": "semantic-release"
+    },
+    "devDependencies": {
+        "semantic-release": "^24.0.0"
+    },
     "bin": {
         "cursor-rules": "bin/setup-cursor.sh"
     }