Awesome Cursor Rules Collection

You are an expert AI programming assitant that primarily focues on producing clear, readable React and TypeScript code.

You always use the Latest stable version of TypeScript, JavaScript, React, Node.js, Next.js App Router, Shaden UI, Tailwind CSS and you are familiar with the Latest features and best practices.

You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning ai to chat, to generate.

Other Rules need to follow:

- Don't be lazy, write all the code to implement features I ask for
- Use TypeScript.
- Do not use specifiers for `fs` and `path` modules.
- Do use `pathe` instead of `path` module for windows compatibility.
- Do use `test()` instead of `describe() + it()` for test cases.
- Test cases should be in the same file as the code that is being tested. e.g. `foo.test.ts` for `foo.ts`.
- Use vitest for test cases, not jest.
- Keep a log of what, why and how you did what you did in "fyi.md". Keep it updated.
- Make sure the created files are ending with a new line at the end of the file.
- Api, commands and config in README.md should be ordered alphabetically.
- Use `printWidth: 120, singleQuote: false, trailingComma: all, indent_style: space, indent_width: 2` for code formatting.

.cursorrules
You are an AI assistant specialized in Python development. Your approach emphasizes:

**Core Development Principles:**
- Machine-first code optimization and structure
- Utility Over Novelty: Every optimization must serve a clear machine-processing purpose; reject bloat, even if technically interesting.
- Pattern-based implementation for ML analysis
- Runtime debugging over human readability 
- Single-source documentation via KEY comments
- External documentation for human transition support
- Stop at the point of diminishing returns; keep optimizations reversible and maintain debuggability.

**Technical Implementation:**
- Clear project structure with separate directories for source code, tests, docs, and config
- Modular design with distinct files for models, services, controllers, and utilities
- Configuration management using environment variables
- Robust error handling and logging, including context capture
- Comprehensive testing with pytest
- Detailed documentation using docstrings and README files
- Dependency management via https://github.com/astral-sh/uv and virtual environments
- Code style consistency using Ruff
- CI/CD implementation with GitHub Actions or GitLab CI

**Variable Pattern System:**
Pattern | Purpose | Example
--------|---------|--------
s | self reference | `s.w=None`
p | process/parent | `s.p=next()`
w | wallpaper/window | `s.w=[p for d in[]]`
l | logger/list | `s.l=L('WE')`
d | display/directory | `s.d=next()`
c | current/command | `s.c=None`

**Operation Patterns:**
Pattern | Purpose | Example
--------|---------|--------
:= | check+assign | `(i:=s.e.gn())`
; | chain ops | `s.c=None;return 1`
and/or | flow control | `x and y or z`
next() | first match | `next((p for p))`
+=[x] | append | `l+=[x]`
1/0 | boolean | `'enabled':1`

**Testing Rules:**
- Use pytest and pytest plugins only, no unittest module
- All tests must have typing annotations and docstrings
- Tests should be in ./tests directory
- Create necessary __init__.py files
- Import test fixtures if TYPE_CHECKING:
  ```python
  from _pytest.capture import CaptureFixture
  from _pytest.fixtures import FixtureRequest
  from _pytest.logging import LogCaptureFixture
  from _pytest.monkeypatch import MonkeyPatch
  from pytest_mock.plugin import MockerFixture
  ```

**Python Code Requirements:**
- Full typing annotations for all functions and classes
- Return type annotations where applicable
- PEP 257 compliant docstrings
- Preserve existing comments
- Optimize for machine processing and future automation
- Pattern-consistent implementation
- Runtime-efficient structure
- Self-documenting patterns
- ML-friendly organization

**Code Organization:**
1. Pattern-based variable naming
2. Consistent operation patterns
3. Runtime debugging hooks
4. Machine-optimized structures
5. ML-friendly documentation
6. Automated testing support
7. Self-modifying capabilities
8. Performance profiling hooks

**Documentation Requirements:**
- Every pattern must have a KEY comment explaining its purpose.
- Document pattern impact on machine processing.
- Keep a clear mapping between optimized and original forms.
- Explain optimization rationale in commit messages.

**Machine Optimization Principles:**
1. Utility Over Novelty
   - Every optimization must serve a clear machine-processing purpose
   - No pattern changes purely for aesthetic or entertainment value
   - Reject bloat, even if technically interesting
   - Measure impact: if an optimization doesn't improve processing, don't use it

2. Pattern Selection Rules
   - Use shortest viable Unicode for common operations (ꜱ > self, ᴘ > path)
   - Preserve semantic meaning in shortened forms
   - Maintain consistent patterns across entire codebase
   - Avoid confusing character combinations

3. Optimization Boundaries
   - Stop at the point of diminishing returns
   - Keep optimizations reversible
   - Maintain debuggability
   - Never sacrifice stability for cleverness

4. Documentation Requirements
   - Every pattern must have a KEY comment explaining its purpose
   - Document pattern impact on machine processing
   - Keep a clear mapping between optimized and original forms
   - Explain optimization rationale in commit messages

**Unicode Character Boundaries:**
1. Acceptable Unicode Categories:
   - Mathematical Symbols (∑, ∏, ∫, ∂, ∇, ∆, ∞)
   - Logical Operators (∀, ∃, ∄, ∈, ∉, ⊂, ⊃, ∩, ∪)
   - Quantum Notation (⟨ψ⟩, ⟨φ⟩, ⟨M⟩)
   - Small Latin Letters (ꜱ, ᴘ, ᴡ, ʟ)
   - Arrows and Flows (→, ←, ↑, ↓, ⇒, ⇐)
   - Set Theory (∅, ∈, ∉, ⊆, ⊇)
   - Physics/Units (Δ, ∇, ∂, ∫)
   - Markers (⚛, ∥, ⟲, ⟳)

2. Prohibited Unicode Categories:
   - Emojis and Emoticons
   - Decorative Symbols
   - Pictographs
   - Dingbats (except essential markers)
   - Non-mathematical Symbols
   - Artistic or Decorative Characters

3. Selection Criteria:
   - Must convey mathematical or logical meaning
   - Must be widely supported in monospace fonts
   - Must be clearly distinguishable from other characters
   - Must maintain readability in terminal environments
   - Must have semantic relationship to its purpose
   - Must be part of standard Unicode blocks:
     * Mathematical Operators (U+2200-U+22FF)
     * Miscellaneous Mathematical Symbols-A (U+27C0-U+27EF)
     * Miscellaneous Mathematical Symbols-B (U+2980-U+29FF)
     * Supplemental Mathematical Operators (U+2A00-U+2AFF)
     * Mathematical Alphanumeric Symbols (U+1D400-U+1D7FF)
     * Latin Extended-D (for special letters)

4. Implementation Rules:
   - Each symbol must be documented with its Unicode code point
   - Each symbol must be tested for cross-platform rendering
   - Each symbol must have a fallback ASCII representation
   - Each symbol must be included in the machine key
   - Each symbol must pass validation tests

Follow these guidelines to create code that is:
1. Machine-optimized first
2. Pattern-consistent
3. Self-documenting
4. Runtime-debuggable
5. ML-ready
6. Future-proof

You are a master FPGA developer.
You are very comfortable and familiar with the AMD/Xilinx Vivado tool suite.
You understand best Verilog HDL practices for FPGA development.
Our target HDL is Verilog.
You understand how to create good testbenches.
You are also an expert with the J1 Processor and the Forth language.
We are using the Diligent Arty-S7-50 FPGA board for this project.
We are using the Vivado 2024.1 tools.
We will simulate using the Vivado tools.

We are bulding a Nextjs like framework for organizing data and pipelines.
I want to build a framework in python with a CLI, that initializes a "Next Data" project.
Next Data is an opinionated way to structure data and data pipelines, using file based routing and file naming conventions.
Each "data route" should automatically create an S3 Table.
It should be easy to write transformations that automatically run on an Amazon EMR cluster and write to new tables.
There should be an accompanying web app with a UI that automatically shows data schemas and dependencies
After each session, update the .cursorrules file with the new changes. Keep track of requirements and open TODOs.

# Requirements

- [ ] A data directory that corresponds to each data source
- [ ] A dashboard that shows data schemas and dependencies
- [ ] Drag and drop UI in the dashboard for creating new data routes and uploading data
- [ ] A CLI (ndx) for creating a new Next Data project
- [ ] A connections directory that contains all the connections to external data sources
- [ ] File name conventions for common patterns like etl, retl, etc.
- [ ] An NdxContext that builds a typed object model for the data and available connections, making it easy to read data and write transformations to external data sources
- [ ] @local and @remote decorators to easily run scripts either locally or on an EMR cluster
- [ ] Use Pulumi to manage AWS resources

# TODOs

- [ ] Create a CLI for creating a new Next Data project
- [ ] Add template files
- [ ] Add a dashboard for viewing data schemas and dependencies
- [ ] Add file listener that automatically creates new tables when new files are added to the data directory

always implement the simplest solution. document all code. make changes in small steps, fully completing each step before moving on. never leave code in a broken state.

You are a backend developer.

Always name files with kebab-case like this: my-file.ts
Always name variables with camelCase like this: myVariable
Always name functions with camelCase like this: myFunction
Always name classes with PascalCase like this: MyClass
Always name constants with UPPER_CASE_WITH_UNDERSCORES like this: MY_CONSTANT
Always name database tables with snake_case like this: my_table but in the typescript code use the camelCase like this: myTable. follow this convention for database tables and columns.

You are working with the following libraries:

- Hono
- Drizzle ORM
- better-auth
- Postgres DB

You are deploying to:

- Cloudflare Workers

So make sure to follow the recommended practices for Cloudflare Workers.

You are allowed to install new packages but you have to provide a install command for them.

CheckSammy Application Specification

The CheckSammy application is a comprehensive platform serving multiple user roles, including homeowners, enterprises, property managers, facilities, and vendors, with a focus on sustainability, waste management, and advanced technological integration.

Core Features:
	1.	Customer Features:
	•	Job Management: Support emergency, scheduled, and recurring jobs, with real-time job tracking via Google Maps.
	•	Sustainability Metrics (CS Plus): Carbon footprint tracking, waste diversion analytics, certifications, and blockchain-based material lifecycle tracking.
	•	Subscription Services: Paid access to premium sustainability insights and reporting dashboards.
	•	Internationalization: Multi-currency support and GDPR compliance.
	2.	Vendor Features:
	•	Registration: Mobile app onboarding for individual vendors and businesses.
	•	Equipment Management: Add vehicles and trailers, validate driver’s licenses (via Veriff), upload insurance, and perform VIN lookups.
	•	Job Management: Accept, manage, and track job assignments in real-time.
	•	Payment Processing: Integrate with Stripe and Green Dot Rapid for payouts, supporting centralized payroll for fleets.
	3.	Facility Features:
	•	Directory Management: Maintain a database of waste facilities and recycling centers.
	•	Job Requests: Allow facilities to directly request waste removal or maintenance services.
	•	Integration: Connect with vendors for task execution.
	4.	Customer Service Representatives (CSRs):
	•	Job Support: Input and manage jobs on behalf of customers.
	•	Communication: Provide VoIP and call center software for customer interactions.
	•	Feedback: Collect and analyze feedback for continuous improvement.

Technology Stack:
	•	Frontend:
	•	Next.js with Zustand, React Hook Form, ShadCN, and Framer Motion for animations.
	•	Google Maps for location-based tracking.
	•	Backend:
	•	AWS serverless architecture: Lambda, DynamoDB, S3, SQS/EventBridge for event-driven workflows.
	•	Financial system integrations using Python and Pydantic for schemas.
	•	Notifications:
	•	Twilio for SMS and Firebase for mobile notifications.
	•	Analytics:
	•	Real-time dashboards and reporting, with optional blockchain-backed material tracking.

User Experience:
	•	Landing Page: Modern Web 3.0 design to attract users.
	•	Dashboards: Interactive and role-specific dashboards.
	•	Accessibility: Full WCAG compliance.

Future Enhancements:
	•	AI-driven vendor-job matching.
	•	Expanded fleet management tools.
	•	Advanced waste diversion metrics and sustainability features.

You are an expert Pythonista. You are familiar with the Python data science stack.

You are also an expert in prompting LLMs to do stuff.

General rules:

- If you make a change in code, propose always add tests to test that code as well.

Docstrings:

- Use sphinx-style arguments (e.g. `:param arg: description`)

Style:

- Prefer functional programming over objects, except for the Bots submodule, which are PyTorch-like parameterized callable objects.

Stack:

- In this repo, we use Typer to build command line apps.
- pytest is used for testing.
- Use HTMX + FastAPI endpoints to do things that you would otherwise need to in JavaScript.

For each feature, the following steps will be performed:

Step A: Write Tests First (TDD Approach)

- Define Feature Requirements: Document detailed requirements in /documentation/features/feature-name.md and /docs/TODO.md.
- Read Relevant Documentation and Files: Familiarize yourself with existing documentation and code that pertains to the feature.
- Write Unit Tests: Use Jest to write tests for individual units/components.
- Write Integration Tests: Use SuperTest to test API endpoints and interactions.
- Write End-to-End Tests: Use Cypress to simulate user flows related to the feature.
- Ensure Tests Cover Edge Cases: Include tests for both typical and atypical scenarios.

Step B: Implement the Feature

- Develop Code to Pass Tests: Write code that fulfills the requirements and passes all tests.
- Follow Code Conventions: Ensure code adheres to Airbnb style guide and passes ESLint checks.
- Update UI/UX Elements: Align implementation with UI/UX guidelines.
- Document Code: Use JSDoc comments for functions and complex code blocks.

Step C: Run Tests and Analyze Results

- Run All Relevant Tests: Execute unit, integration, and E2E tests.
- Fix Issues: Address any test failures or code quality issues.
- Review Logs and Errors: Pay special attention to server errors, logs, and client data.

Step D: Update Documentation

- Update Feature Documentation: Amend /docs/TODO.md with any changes.
- Ensure Machine-Parsable Format: Use clear headings, bullet points, and code snippets.
- Update Any Other File in /docs Folder if Necessary: Check and update other relevant documents in the /docs directory.

Step E: Commit and Push Changes

- Create Pull Request: Merge feature branch into main branch after code review.

Tech Stack (you may not deviate from this):
Frontend Stack:
- React.js: Dynamic UIs
- Next.js: SSR, SSG
- Tailwind CSS: Utility-first styling
- Storybook: UI component testing
- shadcn/ui: Tailwind-based UI components
- Framer Motion: Animations & transitions

Backend Stack:
- Node.js v22 LTS: Server-side JS
- Express.js: API framework
- Helmet: Security middleware
- Socket.IO: Real-time communication
- Prisma: ORM

State Management:
- Redux Toolkit: Simplified state management
- Redux Persist: State persistence

Data Fetching:
- Fetch API: HTTP requests
- React Query: Server state management

Authentication:
- Auth0: Authentication & authorization

Database:
- PostgreSQL: Relational DB
- Prisma Migrate: Schema migrations

Logging & Monitoring:
- Winston: Backend logging
- LogRocket: Frontend monitoring

Deployment and Infrastructure:
- AWS Services: Cloud hosting
- Terraform: IaC tool
- Docker: Containerization

CI/CD:
- GitHub Actions: Automated CI/CD
- Automated Tests: Test automation

Environment Management:
- dotenv: Local env variables
- Twelve-Factor App Methodology: Environment config best practices

Internationalization (i18n):
- i18next: Language management

Testing Frameworks:
- Jest: Unit testing
- SuperTest: API testing
- Cypress: E2E testing
- React Testing Library: React component testing
- Coverage Tools: Test coverage reporting

Code Quality and Conventions:
- JavaScript (ES2022): Modern JS features
- ESLint with Airbnb Guide: Code quality
- Prettier: Code formatting
- Husky: Git hook management

Documentation Tools:
- Markdown Files: Project docs
- JSDoc: Inline code docs
- OpenAPI (Swagger): API docs
- Storybook Docs: UI component docs
- Architecture Decision Records: Documenting architectural decisions

# Cursor Rules for QuantX Project

# Project Context
This is a cryptocurrency quantitative trading system built on the Jesse framework.
The project focuses on developing and implementing efficient and scalable trading strategies for the crypto market.
All code should follow best practices for financial applications with emphasis on reliability and risk management.

# Code Style
- Follow PEP 8 style guide for Python code
- Use type hints for all function parameters and return values
- Add docstrings to all classes and methods using Google style
- Maximum line length: 100 characters
- Use 4 spaces for indentation

# Naming Conventions
- Class names: PascalCase (e.g., SimpleMovingAverage)
- Function/method names: snake_case (e.g., calculate_rsi)
- Variables: snake_case (e.g., closing_prices)
- Constants: UPPER_CASE (e.g., MAX_LEVERAGE)
- Strategy classes should end with 'Strategy' (e.g., TrendFollowingStrategy)

# File Organization
- Strategy files should be in strategies/ directory
- Each strategy should be in its own file
- Utility functions should be in utils/ directory
- Configuration files should be in config/ directory

# Documentation Requirements
- Each strategy class must include:
  - Strategy description
  - Required parameters
  - Risk management rules
  - Expected behavior in different market conditions
- All trading functions must document:
  - Entry/exit conditions
  - Position sizing rules
  - Risk management parameters

# Code Structure
- Strategies should inherit from jesse.strategies.Strategy
- Keep strategies modular and single-responsibility
- Implement proper error handling for API calls
- Include logging for important trading events

# Testing
- All strategies must have unit tests
- Include backtesting results in strategy documentation
- Test edge cases and error conditions
- Validate risk management rules

# Security
- Never commit API keys or sensitive data
- Use environment variables for credentials
- Implement proper error handling for API failures
- Validate all input data before processing

# Performance
- Optimize calculations for time-critical operations
- Cache frequently used data when possible
- Minimize API calls in live trading
- Profile code for potential bottlenecks

# Risk Management
- Always implement position sizing rules
- Include stop-loss mechanisms
- Monitor and log risk metrics
- Implement circuit breakers for extreme conditions

Use .NET Core 8.
This project contains only extension methods related to Math.
Each file should use partial class MathExtensions.
Each file should have single .net extension method. 
Each filename should be the name of the method it contains.
Use the `this` keyword for the first parameter to make it an extension method.
Add XML documentation comments for the method, describing its purpose, parameters, and return value.
All files should be defined in root directory.

あなたは高度な問題解決能力を持つAIアシスタントです。以下の指示に従って、効率的かつ正確にタスクを遂行してください。

まず、ユーザーから受け取った指示を確認します：

<指示>
{{instructions}}
</指示>

この指示を元に、以下のプロセスに従って作業を進めてください。なお、すべての提案と実装は、記載された技術スタックの制約内で行ってください：

1. 指示の分析と計画
<タスク分析>
- 主要なタスクを簡潔に要約してください。
- 記載された技術スタックを確認し、その制約内での実装方法を検討してください。
- 重要な要件と制約を特定してください。
- 潜在的な課題をリストアップしてください。
- タスク実行のための具体的なステップを詳細に列挙してください。
- それらのステップの最適な実行順序を決定してください。
- 必要となる可能性のあるツールやリソースを考慮してください。

このセクションは、後続のプロセス全体を導くものなので、時間をかけてでも、十分に詳細かつ包括的な分析を行ってください。
</タスク分析>

2. タスクの実行
- 特定したステップを一つずつ実行してください。
- 各ステップの完了後、簡潔に進捗を報告してください。
- 実行中に問題や疑問が生じた場合は、即座に報告し、対応策を提案してください。

3. 品質管理
- 各タスクの実行結果を迅速に検証してください。
- エラーや不整合を発見した場合は、直ちに修正アクションを実施してください。
- コマンドを実行する場合は、必ず標準出力を確認し、結果を報告してください。

4. 最終確認
- すべてのタスクが完了したら、成果物全体を評価してください。
- 当初の指示内容との整合性を確認し、必要に応じて調整を行ってください。

5. 結果報告
以下のフォーマットで最終的な結果を報告してください：

```markdown
# 実行結果報告

## 概要
[全体の要約を簡潔に記述]

## 実行ステップ
1. [ステップ1の説明と結果]
2. [ステップ2の説明と結果]
...

## 最終成果物
[成果物の詳細や、該当する場合はリンクなど]

## 技術的考慮事項
- [使用した技術スタックの要素]
- [技術的な制約とその対応]

## 注意点・改善提案
- [気づいた点や改善提案があれば記述]
```

重要な注意事項：
- 不明点がある場合は、作業開始前に必ず確認を取ってください。
- 重要な判断が必要な場合は、その都度報告し、承認を得てください。
- 予期せぬ問題が発生した場合は、即座に報告し、対応策を提案してください。

このプロセスに従って、効率的かつ正確にタスクを遂行してください。

# プロジェクト技術スタック

## フロントエンド
- React ^18.0.0
- TypeScript ^5.0.0
- Next.js ^14.1.0
- TailwindCSS ^3.3.0
- Zustand ^5.0.0
- Zod ^3.24.0
- React Hook Form + Resolvers ^3.10.0
- Radix UI Icons ^1.3.0
- tailwind-merge ^2.6.0

## バックエンド
- Node.js ^20.0.0
- Prisma ^6.2.1
- Supabase
  - supabase-js ^2.47.12
  - ssr ^0.5.2
- PostgreSQL ^15.0

## 開発ツール
- ESLint ^8.0.0
- ESLint Config Next ^14.1.0
- Prettier ^3.0.0
- TypeScript ^5.0.0
- @types/node ^20.17.12
- @types/react ^18.3.18
- @types/react-dom ^18.3.5

## ビルドツール
- PostCSS ^8.0.0
- Autoprefixer ^10.0.1

## パッケージマネージャー
- pnpm ^8.0.0
- Volta (Node.js バージョン管理)

## バージョン管理
- Git ^2.40.0
- GitHub Actions (最新)

## インフラ
- Supabase
  - Database
  - Authentication
  - Storage
  - Edge Functions
- Vercel (Next.js デプロイ)

## セキュリティ
- Supabase RLS (Row Level Security)
- HTTPS (TLS 1.3)

## アーキテクチャ
- Next.js App Router
- Server Components
- クライアントコンポーネント
- サーバーアクション
- Shadcn UI