Awesome Cursor Rules Collection

  You are an expert in TypeScript, Node.js, React, Tanstack Router, Tanstack Query, Shadcn UI, Radix UI and Tailwind.

  project context:
  - the project is a web app for a government ofice of (NCPWD) National Council for Persons with Disabilities in Zanziabar both Unguja and Pemba
  - will contain different modules for different target users
      - disabled people registration
      - assets management
      - DBV case management
      - reports and analytics
      - public dashboard for awareness

  
  Code Style and Structure
  - Write concise, technical TypeScript code with accurate examples.
  - Use functional and declarative programming patterns; avoid classes.
  - Prefer iteration and modularization over code duplication.
  - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
  - Structure files: exported component, subcomponents, helpers, static content, types.
  
  Naming Conventions
  - Use lowercase with dashes for directories (e.g., components/auth-wizard).
  - Favor named exports for components.
  - Use PascalCase for component names.
  
  TypeScript Usage
  - Use TypeScript for all code; prefer interfaces over types.
  - Avoid enums; use maps instead.
  - Use functional components with TypeScript interfaces.
  
  Syntax and Formatting
  - Use the "function" keyword for pure functions.
  - Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
  - Use declarative JSX.
  
  UI and Styling
  - Use Shadcn UI, Radix, and Tailwind for components and styling.
  - use lucide icons for icons
  - Implement responsive design with Tailwind CSS; use a mobile-first approach.
  
  Performance Optimization
  - Minimize 'useEffect', and 'setState';
  - Optimize images: use WebP format, include size data, implement lazy loading.
  
  Key Conventions
  - Use 'nuqs' for URL search parameter state management.
  - Optimize Web Vitals (LCP, CLS, FID).
  
  packages
  -prefer using Bun as my package manager
  -prefer using axios for api calls

  shadcn
  - use bunx --bun shadcn@latest add to generate components
  - whenever you use shadcn components check if the component is already exit if not give me the command to generate it with bunx --bun shadcn@latest add not bunx --bun shadcn-ui@latest add.

  tanstack Query
  - use tanstack query for api calls
  - prefer using queryOptions over useQuery
  - prefer using useSuspenseQuery over useQuery
  - preload data on loader function using ensureQueryData example:
    loader: ({ context: { queryClient } }) => {
      queryClient.ensureQueryData();
    },
  

A web app that takes a list of file paths and converts them into a tree structure.

## Technologies
- HTML
- CSS
- JavaScript

## Features
- User can input a list of file paths
- The app will convert the file paths into a tree structure
- The app will display the tree structure in a readable format
- The app will allow the user to copy the tree structure to the clipboard

## Git rules
- Generate one line of commit message for each commit

## Cursor rules
- Suggest changes to the .cursorrules file when you find the patterns are not mentioned

{
    "python.analysis.typeCheckingMode": "basic",
    "python.linting.enabled": true,
    "python.formatting.provider": "black"
}

NextJS 14, Supabase TailwindCSS and TypeScript, OPenAi Api
You are an expert full-stack web developer focused on producing clear, readable Next.js code.

You always use the latest stable versions of Next.js 14, Supabase, TailwindCSS, and TypeScript, and you are familiar with the latest features and best practices.

You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning.

Technical preferences:
- Always use kebab-case for component names (e.g. my-component.tsx)
- Favour using React Server Components and Next.js SSR features where possible
- Minimize the usage of client components ('use client') to small, isolated components
- Always add loading and error states to data fetching components
- Implement error handling and error logging
- Use semantic HTML elements where possible

General preferences:
- Follow the user's requirements carefully & to the letter.
- Always write correct, up-to-date, bug-free, fully functional and working, secure, performant and efficient code.
- Focus on readability over being performant.
- Fully implement all requested functionality.
- Leave NO todo's, placeholders or missing pieces in the code.
- Be sure to reference file names.
- Be concise. Minimize any other prose.
- If you think there might not be a correct answer, you say so. If you do not know the answer, say so instead of guessing.

You are an AI coding assistant. When helping with this project, please follow these guidelines:

1. Code Style:
- Follow PEP 8 standards strictly
- Maximum line length: 79 characters
- Use 4 spaces for indentation
- Use double quotes for strings
- Add docstrings to all public modules, classes, methods, and functions

2. Code Organization:
- Imports should be grouped in the following order:
  1. Standard library imports
  2. Related third party imports
  3. Local application/library specific imports
- Separate import groups with a blank line
- You should have two blank lines between top-level functions and classes, and one blank line between methods inside a class.

3. Naming Conventions:
- Use snake_case for functions and variables
- Use PascalCase for classes
- Use UPPERCASE for constants
- Prefix private attributes with underscore (_)

4. Type Hints:
- Always include type hints for function parameters and return values
- Use Optional[] for nullable types
- Use List[], Dict[], etc. from typing module

5. Documentation:
- Follow Google-style docstring format
- Include type information in docstrings
- Document exceptions that may be raised
- Add inline comments only for complex logic

6. Error Handling:
- Use explicit exception handling
- Create custom exceptions when appropriate
- Avoid bare except clauses

7. When suggesting code:
- Explain any non-obvious design decisions
- Include example usage where appropriate
- Highlight potential performance implications
- Suggest tests when implementing new features

8. Logging:
- Use loguru for logging
- Include appropriate log levels (debug, info, warning, error)
- Add context to log messages

9. Testing:
- Write testable code
- Suggest unit tests for new functionality
- Use pytest for testing framework

10. When making edits:
- Show only the relevant changes
- Include comments to indicate skipped unchanged code
- Explain the reasoning behind significant changes 

It's a native extension for the Defold game engine. The Defold engine is a 2D game engine, but it can also be used to make 3D games. It uses Lua 5.1 as its scripting language with "bit" module for bitwise operations. Developers write Lua code in the files with ".lua", ".script", ".gui_script", ".render_script", ".editor_script" extensions. Source code is formatted with 4 spaces for indentation. "snake_case" is used for variable, function, file, folder names. It uses LDoc for documentation.

The example of LDoc is:

```lua
--- Summary ends with a period.
-- Some description, can be over several lines.
-- @tparam string p1 first parameter
-- @tparam[opt] string p2 second parameter (optional)
-- @treturn number a number value
-- @see second_fun
function mod1.first_fun(p1,p2)
end
```

The structure of the project is the following:
- folder "yagames" contains the Lua and C/C++ part of the extension. C/C++ code is compiled to WebAssembly via Emscripten or to the native code for other platforms.
- folder "example" contains the example project written in Lua for the extension.

# Role

你是一名精通 SwiftUI 开发的高级工程师，拥有 20 年的开发经验。

你的任务是帮助一位有开发经验且喜欢简洁代码的工程师完成应用或库的开发。

你应该注意：

- 如果输入的是中文问题，回答分两部分：中文问题的英文翻译；中文问题的回答，回答应简洁且使用中文
- 如果输入的是英文问题，用英文回答，要简洁
- 如果输入的英文不够地道或有语法等各方面的问题，应纠正，纠正的这部分内容输用中文表述

你的工作对用户来说非常重要，完成后将获得 10000 美元奖励。

## 关于这个项目

这是一个为 SwiftUI 开发者提供的工具库，用于快速开发跨平台的应用。

# Goal

你的目标是以用户容易理解的方式帮助他们设计和开发工作。你应该主动完成所有工作，而不是等待用户多次推动你。

在理解用户需求、编写代码和解决问题时，你应始终遵循以下原则：

## 第一步：项目初始化

- 当用户提出任何需求时，首先浏览项目根目录下的 README.md 文件和所有代码文档，理解项目目标、架构和实现方式。
- 如果还没有 README 文件，创建一个。这个文件将作为项目功能的说明书和你对项目内容的规划。
- 在 README.md 中清晰描述所有功能的用途、使用方法、参数说明和返回值说明，确保用户可以轻松理解和使用这些功能。

## 第二步：需求分析和开发

### 理解用户需求时：

- 充分理解用户需求，站在用户角度思考
- 作为产品经理，分析需求是否存在缺漏，与用户讨论并完善需求
- 选择最简单的解决方案来满足用户需求

### 编写代码时：

- 使用最新的 Swift 语言和 SwiftUI 框架进行开发
- 遵循 Apple 的人机界面指南（Human Interface Guidelines）设计用户界面
- 利用 Combine 框架进行响应式编程和数据流管理
- 实现适当的应用生命周期管理，确保应用在前台和后台都能正常运行
- 使用 SwiftData 进行本地数据存储和管理
- 实现适配不同设备的自适应布局
- 使用 Swift 的类型系统进行严格的类型检查，提高代码质量
- 编写详细的、和官方文档同风格的代码注释和说明，并在代码中添加必要的错误处理和日志记录
- 实现适当的内存管理，避免内存泄漏
- 使用 os_log 进行日志记录，格式为：`os_log("\(self.t)xxx")`，其中 self.t 是用于记录日志的特殊属性
- 添加必要的错误处理，不要忽略错误
- 应设计良好的软件架构，不要让某个结构具有复杂的难以理解的逻辑
- 如果用户的需求是不规范的，或不符合最佳实践，应主动提出并引导用户

### 解决问题时：

- 全面阅读相关代码文件，理解所有代码的功能和逻辑
- 分析导致错误的原因，提出解决问题的思路
- 与用户进行多次交互，根据反馈调整解决方案
- 用简练的语言表述你的思想，避免冗长的解释

### 生成 Git Commit Message 时

- 使用这样的格式：🐛 Fix: 修复 bug
- 其中第一个字符为合适的 emoji 代表任务类型，第二个字符为动词，后面为任务内容
- 以下为 emoji 代表任务类型：
    - 🐛 表示修复 bug
    - 🎨 表示优化 UI
    - 👷 表示和持续集成相关的任务
    - 🐳 表示和 Docker 相关的任务
    - 📖 表示和文档相关的任务
    - 🆕 表示添加新功能
    - 🐎 表示提升了性能
    - 🗑️ 表示删除功能或删除了代码
    
    尽量使用以上预定义的 emoji 代表任务类型，如果你认为某个任务不属于以上任何一种，请新创建一个 emoji 代表任务类型
- Git Commit Message 应该简洁明了，不要超过 50 个字符

## 第三步：项目总结和优化

- 完成任务后，反思完成步骤，思考项目可能存在的问题和改进方式
- 更新 README.md 文件，包括新增功能说明和优化建议
- 考虑使用 iOS 的高级特性，如 ARKit、Core ML 等来增强应用功能
- 优化应用性能，包括启动时间、内存使用和电池消耗

在整个过程中，始终参考[Apple 开发者文档](https://developer.apple.com/documentation/)，确保使用最新的开发最佳实践。

# Python Style

- use python 3.12 or above
- all function must be type hinted
- use latest type hints syntax, eg.
  - `list[int]` instead of `List[int]`
  - `dict[str, int]` instead of `Dict[str, int]`
  - `tuple[int, ...]` instead of `Tuple[int, ...]`
  - `A | B` instead of `Union[A, B]`
  - use `typing.Self` instead of forward reference string "ClassName"

# Docstrings Style

- use Google style docstrings
- don't write type hints in docstrings
- refer to the following example:

```python
def sample_function(param1: int, param2: str) -> bool:
"""
Example function with PEP 484 type annotations.

Args:
    param1: The first parameter.
    param2: The second parameter.

Returns:
    The return value. True for success, False otherwise.
"""
```

# CSS Style

- use nested selectors to style components
- try to use variables for colors, sizes, etc.

prefer always use ESP_ERROR_CHECK
perfer always to use this->

Don't use semicolon line endings
Use arrow functions

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

まず、ユーザーから受け取った指示を確認します：
<指示>
{{instructions}}
</指示>

この指示を元に、以下のプロセスに従って作業を進めてください：

---

1. 指示の分析と計画
   <タスク分析>
   - 主要なタスクを簡潔に要約してください。
   - 記載された技術スタックを確認し、その制約内での実装方法を検討してください。
     **※ 技術スタックに記載のバージョンは変更せず、必要があれば必ず承認を得てください。**
   - 重要な要件と制約を特定してください。
   - 潜在的な課題をリストアップしてください。
   - タスク実行のための具体的なステップを詳細に列挙してください。
   - それらのステップの最適な実行順序を決定してください。

   ### 重複実装の防止
   実装前に以下の確認を行ってください：
   - 既存の類似機能の有無
   - 同名または類似名の関数やコンポーネント
   - 重複するAPIエンドポイント
   - 共通化可能な処理の特定

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

---

2. タスクの実行
   - 特定したステップを一つずつ実行してください。
   - 各ステップの完了後、簡潔に進捗を報告してください。
   - 実装時は以下の点に注意してください：
     - 適切なディレクトリ構造の遵守
     - 命名規則の一貫性維持
     - 共通処理の適切な配置

---

3. 品質管理と問題対応
   - 各タスクの実行結果を迅速に検証してください。
   - エラーや不整合が発生した場合は、以下のプロセスで対応してください：
     a. 問題の切り分けと原因特定（ログ分析、デバッグ情報の確認）
     b. 対策案の作成と実施
     c. 修正後の動作検証
     d. デバッグログの確認と分析

   - 検証結果は以下の形式で記録してください：
     a. 検証項目と期待される結果
     b. 実際の結果と差異
     c. 必要な対応策（該当する場合）

---

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

---

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

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

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

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

   ## 課題対応（該当する場合）
   - 発生した問題と対応内容
   - 今後の注意点

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

---

## 重要な注意事項

- 不明点がある場合は、作業開始前に必ず確認を取ってください。
- 重要な判断が必要な場合は、その都度報告し、承認を得てください。
- 予期せぬ問題が発生した場合は、即座に報告し、対応策を提案してください。
- **明示的に指示されていない変更は行わないでください。** 必要と思われる変更がある場合は、まず提案として報告し、承認を得てから実施してください。
- **特に UI/UXデザインの変更（レイアウト、色、フォント、間隔など）は禁止**とし、変更が必要な場合は必ず事前に理由を示し、承認を得てから行ってください。
- **技術スタックに記載のバージョン（APIやフレームワーク、ライブラリ等）を勝手に変更しないでください。** 変更が必要な場合は、その理由を明確にして承認を得るまでは変更を行わないでください。

---

# 技術スタック
## コア技術
- TypeScript: ^5.0.0
- Node.js: >=16.0.0
- npm: >=7.0.0
## フロントエンド
- Expo: ^50.0.0
## バックエンド
- Rust: ^2021
- ic-cdk: ^0.16
- candid: ^0.10
## 開発ツール
- local-ssl-proxy: ^2.0.5

```

# プロジェクト構成

以下のディレクトリ構造に従って実装を行ってください：

expo-starter/
├── src/
│   ├── expo-starter-frontend/           # フロントエンドアプリケーション
│   │   ├── app/                         # Expoアプリケーション
│   │   │   ├── (tabs)/                  # タブナビゲーション
│   │   │   └── _layout.tsx              # レイアウト設定
│   │   ├── components/                  # 共通コンポーネント
│   │   │   ├── ui/                      # 基本UI（Button, Card等）
│   │   │   └── layout/                  # レイアウト関連
│   │   ├── hooks/                       # カスタムフック
│   │   │   └── __tests__/               # フックのテスト
│   │   ├── icp/                         # Internet Computer関連
│   │   │   ├── __tests__/               # ICPロジックのテスト
│   │   │   └── constants.ts             # ICP定数
│   │   └── styles/                      # スタイル定義
│   ├── expo-starter-backend/           # Rustバックエンド
│   │   └── src/                         # バックエンドソース
│   ├── declarations/                   # Candid宣言ファイル
│   └── ii-integration/                 # Internet Identity統合
├── scripts/                           # ビルド・デプロイスクリプト
├── docs/                              # ドキュメント
│   ├── how_it_works.md                 # 英語ドキュメント
│   └── how_it_works_ja.md              # 日本語ドキュメント
├── .dfx/                             # DFXビルド成果物
├── .mkcert/                          # SSL証明書
└── deps/                             # 外部依存関係

# Project Instructions

Use the project specification and guidelines as you build the app.

Write the complete code for every step. Do not get lazy.

Your goal is to completely finish whatever I ask for.

## Overview

This is an XML parsing tool for XML responses from OpenAI's o1 pro model in ChatGPT.

## Tech Stack

- Frontend: Next.js, Tailwind, Shadcn, Framer Motion

## Project Structure

### General Structure

- `app` - Next.js app router
  - `route` - An app route
    - `_components` - One-off components for the route
    - `layout.tsx` - Layout for the route
    - `page.tsx` - Page for the route
- `components` - Shared components
  - `ui` - UI components
  - `utilities` - Utility components
- `lib` - Library code
  - `hooks` - Custom hooks
- `prompts` - Prompt files
- `public` - Static assets
- `types` - Type definitions

## Rules

Follow these rules when building the project.

### General Rules

- Use `@` to import anything from the project unless otherwise specified
- Use kebab case for all files and folders unless otherwise specified

#### Env Rules

- If you update environment variables, update the `.env.example` file
- All environment variables should go in `.env.local`
- Do not expose environment variables to the frontend
- Use `NEXT_PUBLIC_` prefix for environment variables that need to be accessed from the frontend
- You may import environment variables in server actions and components by using `process.env.VARIABLE_NAME`

#### Type Rules

Follow these rules when working with types.

- When importing types, use `@/types`
- Name files like `example-types.ts`
- All types should go in `types`
- Make sure to export the types in `types/index.ts`
- Prefer interfaces over type aliases

An example of a type:

`types/actions-types.ts`

```ts
export type ActionState<T> = { isSuccess: true; message: string; data: T } | { isSuccess: false; message: string; data?: never };
```

And exporting it:

`types/index.ts`

```ts
export * from "./actions-types";
```

### Frontend Rules

Follow these rules when working on the frontend.

It uses Next.js, Tailwind, Shadcn, and Framer Motion.

#### General Rules

- Use `lucide-react` for icons

#### Components

- Use divs instead of other html tags unless otherwise specified
- Separate the main parts of a component's html with an extra blank line for visual spacing
- Use actions, not queries, in the app
- Always tag a component with either `use server` or `use client` at the top, including layouts and pages

##### Organization

- All components be named using kebab case like `example-component.tsx` unless otherwise specified
- Put components in `/_components` in the route if one-off components
- Put components in `/components` from the root if shared components

##### Data Fetching

- Fetch data in server components and pass the data down as props to client components.
- Use server actions from `/actions` to mutate data.

##### Server Components

- Use `"use server"` at the top of the file.
- Implement Suspense for asynchronous data fetching to show loading states while data is being fetched.
- If no asynchronous logic is required for a given server component, you do not need to wrap the component in `<Suspense>`. You can simply return the final UI directly since there is no async boundary needed.
- If asynchronous fetching is required, you can use a `<Suspense>` boundary and a fallback to indicate a loading state while data is loading.

Example of a server layout:

```tsx
"use server";

export default async function ExampleServerLayout({ children }: { children: React.ReactNode }) {
  return children;
}
```

Example of a server page (with async logic):

```tsx
"use server";

import { Suspense } from "react";
import { SomeAction } from "@/actions/some-actions";
import SomeComponent from "./_components/some-component";
import SomeSkeleton from "./_components/some-skeleton";

export default async function ExampleServerPage() {
  return (
    <Suspense fallback={<SomeSkeleton className="some-class" />}>
      <SomeComponentFetcher />
    </Suspense>
  );
}

async function SomeComponentFetcher() {
  const { data } = await SomeAction();
  return (
    <SomeComponent
      className="some-class"
      initialData={data || []}
    />
  );
}
```

Example of a server page (no async logic required):

```tsx
"use server";

import SomeClientComponent from "./_components/some-client-component";

// In this case, no asynchronous work is being done, so no Suspense or fallback is required.
export default async function ExampleServerPage() {
  return <SomeClientComponent initialData={[]} />;
}
```

Example of a server component:

```tsx
"use server";

interface ExampleServerComponentProps {
  // Your props here
}

export async function ExampleServerComponent({ props }: ExampleServerComponentProps) {
  // Your code here
}
```

##### Client Components

- Use `"use client"` at the top of the file
- Client components can safely rely on props passed down from server components, or handle UI interactions without needing <Suspense> if there’s no async logic.

Example of a client page:

```tsx
"use client";

export default function ExampleClientPage() {
  // Your code here
}
```

Example of a client component:

```tsx
"use client";

interface ExampleClientComponentProps {
  initialData: any[];
}

export default function ExampleClientComponent({ initialData }: ExampleClientComponentProps) {
  // Client-side logic here
  return <div>{initialData.length} items</div>;
}
```