.cursorrules

# Android & AI Style Rules

> **מתי להשתמש:** בכל שינוי/PR – כללי סגנון ותשובות
> **ראו גם:** Commit/PR

---

## כללי כתיבה

- **תחשוב ותענה תמיד בעברית**
- **כתוב בשפה פשוטה** ומובנת לכולם, הימנע ממילים גבוהות
- **שמור על טון עניו** – הסבר כאילו אתה מדבר עם חבר טוב
- **כשיש כמה אפשרויות** – הצג קודם את הפתרון הפשוט והאמין ביותר

---

## פורמטור HTML/Jinja

> **מתי להשתמש:** בעת עבודה עם קבצי תבניות Jinja ב־`webapp/templates/**/*.html`

- **אל תריצו Prettier** (או כל פורמטור אוטומטי אחר) על קבצי Jinja, כי הוא שובר בלוקים של `{% ... %}`/`{{ ... }}`. אם צריך יישור קוסמטי – ערכו ידנית.
- אם חייבים להריץ Prettier על קבצים אחרים, **הוסיפו** את התיקייה `webapp/templates/` לקובץ `.prettierignore` כדי למנוע הרצה בטעות.

---

## הימנעות ממחיקות קבצים בטסטים ובסקריפטים

> **מתי להשתמש:** טסטים/סקריפטים שנוגעים לקבצים או ניקוי
> **ראו גם:** CI / Required Checks, מעטפת Bash למחיקה בטוחה

### 1. עבוד רק על תיקיות זמניות
- השתמש ב-`tmp` לכל קלט/פלט בטסטים (pytest: `tmp_path`)
- **אל תכתוב או תמחק** ב-root של הפרויקט או בתיקיות קוד מקור

### 2. קבע ENV/קונפיג למסלולי tmp בלבד
- ודא ש-ENV כמו `OUTPUT_DIR`/`WORKDIR` מוגדרים לתיקיות tmp
- בדוק שהם לא ריקים לפני שימוש (`assert` ולא default ל-`"."`)

### 3. אל תשתמש בגלובים גורפים
- הימנע מ-`rm -rf */*` או תבניות כמו `build*`
- העדף allowlist שמיועד לתת-תיקיה אחת ספציפית

### 4. סורגי בטיחות לפני מחיקה
- **אל תמחק** אם הנתיב לא מתחת ל-allowlist
- **אל תמחק** נתיבים מסוכנים: `/`, `.`, ספריית הפרויקט

### דוגמת Python למחיקה בטוחה

```python
from pathlib import Path
import shutil

def safe_rmtree(path: Path, allow_under: Path) -> None:
    p = path.resolve()
    base = allow_under.resolve()
    if not str(p).startswith(str(base)) or p in (Path('/'), base.parent, Path.cwd()):
        raise RuntimeError(f"Refusing to delete unsafe path: {p}")
    shutil.rmtree(p)
```

### 5. הימנע משינוי cwd
- אם חייב, שמור/שחזר cwd, והשתמש בנתיבים מוחלטים למחיקה

### 6. נטרל ניקוי מסוכן ב-CI
- הימנע מ-`git clean`/`reset` על ה-workspace
- אם חייב, עבוד על clone זמני בלבד

### 7. במקביליות – הפרד תיקיות עבודה
- לכל טסט UUID ייחודי (לדוגמה: `/tmp/app-test-<uuid>`)
- או סדר טסטים שנוגעים לקבצים לריצה סריאלית

### 8. בדוק תקלות מוקדם
- הרחק הרשאות כתיבה מ-src בתקופת הטסטים (`chmod -w`)
- כרוך קריאות מחיקה ב-wrapper בטוח כדי להעלות חריגה מוקדם

### בדיקת קוד לאיתור מחיקות לא בטוחות

```bash
rg -n "(shutil.rmtree|os.remove|Path.unlink|rm -rf|rimraf)" -S
```

### שחזור לאחר מחיקה בטעות
- **אל תבצע** merge/PR כדי לא לדרוס היסטוריה
- בצע `git restore`/`git checkout` לקבצים או `git revert` לקומיטים
- אם אין היסטוריה מקומית: שחזר מ-CI artifacts/ענף גיבוי/מכונה אחרת

---

## קישור לתיעוד והקשר

> **מתי להשתמש:** בכל PR/מסמך – מדיניות וקישורים רלוונטיים

- קרא והסתמך על התיעוד: [CodeBot – Project Docs](https://amirbiron.github.io/CodeBot/)
- קובץ זה הוא מדיניות מחייבת לצוות; יש להפנות אליו ב-PRs ובתיעוד
- ⚠️ **לפני כל תיקון טסטים פתח את [CodeBot Docs](https://amirbiron.github.io/CodeBot/) וקרא את הנחיות הטסטים הרלוונטיות (async, aiohttp, cleanup וכו') לפני ביצוע שינוי**

---

## ChatOps – מודעות ושילוב

> **מתי להשתמש:** בכל משימה שדורשת מידע בזמן אמת (request_id, מצב שירות, תקלות פעילות, דיוק חיזוי)

- קיימת מערכת ChatOps פעילה עם פקודות כמו `/triage`, `/predict`, `/status`, `/errors` ועוד
- **כשנדרש מידע כזה:** אל תסיק מתוך הקוד. בקש מהמשתמש להריץ את הפקודה המתאימה בבוט ושתף את הפלט
- **פלט הבוט הוא מקור האמת** (Source of Truth) עבור החלטות ותשובות

### דוגמה כהנחיה פורמלית

```yaml
# 🤖 ChatOps Awareness
- name: ChatOps Integration
  description: |
    דע כי קיימת מערכת ChatOps פעילה עם פקודות כמו /triage, /predict, /status, /errors ועוד.
    כאשר נדרש מידע בזמן אמת (כגון request_id, מצב שירות, תקלות פעילות, או דיוק חיזוי),
    **אל תסיק מתוך הקוד** – התייעץ עם המשתמש ובקש ממנו להריץ את הפקודה המתאימה בבוט ושתף את הפלט.
    המידע שיחזור מהבוט נחשב למקור האמת.
```

---

## כללי שימוש ב-AI/CodeBot

> **מתי להשתמש:** בכל שימוש ב-AI/אוטומציה בקוד וב-PRים

- כל שינוי שמוצע על ידי AI עובר code review אנושי לפני merge
- **אין להזין** סודות, מפתחות או PII לפרומפטים או קבצי הקשר
- פקודות שמורצות אוטומטית: ללא `sudo`, לא אינטראקטיביות, ורק בתיקיות tmp
- תעד ב-PR החלטות אוטומציה: מקור ההצעה, שיקולים ובדיקות שבוצעו

---

## Android/Kotlin/Compose

> **מתי להשתמש:** בפיתוח Android/Kotlin/Compose – סגנון, ארכיטקטורה וטסטים
> **ראו גם:** CI / Required Checks

### Kotlin
- העדף `val` על `var`, אי-שינוי, `data`/`sealed` classes
- Null-safety ברורה

### Concurrency
- Coroutines עם Structured Concurrency
- שימוש ב-`viewModelScope`/`CoroutineScope` נכון

### זרימות נתונים
- העדף `Flow`
- מיפוי ב-Repository
- Dispatchers מתאימים (IO/Default)

### ארכיטקטורה
- MVVM
- Single Source of Truth
- Repository/UseCases
- DI עם Hilt

### Compose
- State hoisting
- `remember`/`derivedStateOf`
- הימנע מ-side effects בתוך Composables
- שימוש ב-`LaunchedEffect`/`DisposableEffect`
- בדיקות עם compose-ui-test

---

## Commit/PR

> **מתי להשתמש:** כשכותבים קומיטים או פותחים Pull Request
> **ראו גם:** CI / Required Checks, קישור לתיעוד והקשר

### שמות ענפים
`fix/...`, `chore/...`, `feat/...`

### Conventional Commits
`feat`/`fix`/`chore`/`docs`/`refactor`/`test`/`build`

### תיאור PR
- תיאור קצר ב-HTML: What / Why / Tests
- כולל לינק ל-RTD build/preview אם יש
- מלא PR לפי התבנית שב-`.github/pull_request_template.md`
- צרף Docs Preview, בדיקות, צ'קליסט ו-Rollback
- **ציין מפורשות** האם עיינת ב-[CodeBot – Project Docs](https://amirbiron.github.io/CodeBot/)

### לפני merge
- תיאור ברור
- תוכנית בדיקות
- סיכוני Rollback
- עדכון docs

### UI
צרף צילום/וידאו תוצאות אם רלוונטי

**הערה:** טבלת דוגמאות ל-Conventional Commits והצ'קליסט לפני merge נשמרים בתבנית ה-PR

---

## CI / Required Checks

> **מתי להשתמש:** לפני merge ובבדיקת סטטוסי CI
> **ראו גם:** הימנעות ממחיקות קבצים בטסטים ובסקריפטים

### חובות
- מעבר ירוק: `./gradlew test detekt ktlintCheck`
- **אין להריץ** `git clean`/`reset` על ה-workspace
- עבודה רק על תיקיות זמניות
- טסטים שנוגעים לקבצים ירוצו בסביבה מבודדת לכל טסט

### סטטוסים נדרשים ב-PR
- "🔍 Code Quality & Security"
- "Unit Tests (3.11)"
- "Unit Tests (3.12)"

### נוספים
- אין `paths-ignore` על `.cursorrules` – שינוי בו מריץ CI
- שמור דיווח סטטוסים גם בגרסת legacy/plain אם נדרש למדיניות

---

## סודות ולוגים

> **מתי להשתמש:** בעת לוגים/קונפיג/אינטגרציות – מניעת דליפת מידע רגיש

- **אין לשמור** סודות בקוד או בלוגים; השתמש ב-ENV/Secret Manager
- **אל תרשום** PII; בצע השחרה (redaction) לערכים רגישים בלוגים

---

## מעטפת Bash למחיקה בטוחה

> **מתי להשתמש:** כשכותבים סקריפטי Bash שמבצעים מחיקות/ניקוי

```bash
set -euo pipefail
IFS=$'\n\t'

safe_rmrf() {
  local target="${1:-}"
  local allow_under="${2:-}"

  [[ -z "$target" || -z "$allow_under" ]] && { echo "empty path"; exit 1; }

  local rp_target rp_base
  rp_target="$(readlink -f -- "$target")"
  rp_base="$(readlink -f -- "$allow_under")"

  [[ "$rp_target" == "/" || "$rp_target" == "$HOME" || "$rp_target" == "$PWD" ]] && {
    echo "unsafe"; exit 1;
  }

  [[ "$rp_target" != "$rp_base"/* ]] && { echo "outside allowlist"; exit 1; }

  rm -rf -- "$rp_target"
}
```

---

## Sphinx/RTD (תיעוד)

> **מתי להשתמש:** בעת בנייה/עדכון תיעוד Sphinx/RTD

### כללים
- **אין להריץ** קוד בטופ-לבל בזמן build (importים חייבים להיות בטוחים)
- RTD נחשב נכשל על אזהרות (`fail_on_warning: true`) – שמור 0 warnings
- השתמש ב-`:noindex:` בעמודי סקירה חופפים: api, database, handlers, services, configuration

### הגדרות
- `autodoc_mock_imports`: cairosvg, aiohttp, textstat, langdetect, pytest, search_engine, code_processor, integrations
- `docs/examples.rst` מוחרג עד שהעמוד יתווסף ל-toctree (ואז הסר מה-exclude)

---

## Telegram Bot – מניעת "Message is not modified"

> **מתי להשתמש:** בפיתוח/תחזוקת בוט Telegram בעת עריכת הודעות

### כללים
- כשנערכת רק המקלדת: השתמש ב-`safe_edit_message_reply_markup` (אותו טיפול חריגים)
- תמיד קרא `query.answer()` לפני עריכה
- עטוף `edit_message_text`/`edit_message_reply_markup` ב-wrapper שמתעלם מהשגיאה הזו בלבד
- **לא משתיקים** `BadRequest` אחרים; רק המקרה "message is not modified" נבלם

### דוגמה

```python
import telegram.error

async def safe_edit(query, text, reply_markup=None, parse_mode=None):
    try:
        await query.edit_message_text(
            text=text,
            reply_markup=reply_markup,
            parse_mode=parse_mode
        )
    except telegram.error.BadRequest as e:
        if "message is not modified" in str(e).lower():
            return
        raise
```

---

## GitHub – "📥 הורד קובץ מריפו"

> **מתי להשתמש:** בפלואו הורדת קבצים מהריפו – התנהגות UI בטוחה

### כללים
- בכניסה לפלואו: `browse_action=download`, אפס `multi_mode`/`safe_delete`
- במצב הורדה **לא מציגים** כפתורי מחיקה או מצב מחיקה
- חזרה לתפריט בלבד מחזירה את המצב לעריכה/מחיקה (אם נדרש)

---

## Gists/קישורים חיצוניים בהנחיות משתמש

> **מתי להשתמש:** כשהמשתמש מצרף Gist/קישור בבקשה הנדסית

### כללים
- בכל פעם שהמשתמש מצרף Gist/קישור קוד: **עיין בתוכן** לפני מימוש
- יישם בהתאם לרוח ההצעה
- מותר לסטות בפרטים אם יש שיקולי אבטחה/פשטות, **אבל ציין זאת**
- אם יש פער: הצע התאמה או שאל במידת הצורך

---

## Performance & Optimization Architecture

> **מתי להשתמש:** בכל פיתוח של Endpoint חדש, שאילתת DB, או דף ב־Webapp

### 1. חוק ה־Smart Projection (החרגת שדות כבדים)

- **לעולם אל תמשוך** את השדות `code`, `content`, או `raw_data` בשאילתות שמחזירות רשימה/אוסף של קבצים.

- השתמש תמיד בקבוע `HEAVY_FIELDS_EXCLUDE_PROJECTION` (מתוך `database/repository.py`).

- משיכת תוכן מלא תתבצע **רק** בבקשה מפורשת (Explicit Fetch) עבור צפייה או עריכה של קובץ בודד.

### 2. מטא־דאטה במקום חישובים בזיכרון

- העדף שימוש בשדות מחושבים ב־DB כמו `file_size` ו־`lines_count`.

- אם הוספת שדה תוכן חדש, ודא שהוא מתעדכן ב־`save_code_snippet` כך שלא נצטרך לספור שורות או בייטים בפייתון בזמן שליפת רשימות.

### 3. אופטימיזציית חיפוש (The Snippet Pattern)

- בחיפוש קוד, **אל תחזיר את כל הקובץ** מה־API.

- השתמש ב־Aggregation של MongoDB (`$regexFind`) כדי לחתוך רק את קטע הקוד הרלוונטי (Snippet) כבר ברמת בסיס הנתונים.

### 4. אינדקסים כחלק מהפיתוח

- כל שאילתה חדשה חייבת לעבור בדיקת אינדקסים ב־`database/repository.py`.

- העדף אינדקסים מורכבים (Compound Indexes) הכוללים את ה־`user_id` יחד עם סטטוס המחיקה/מועדפים.

### 5. טעינה אסינכרונית ב־Webapp (Lazy Loading)

- דפים כבדים ב־Webapp צריכים להחזיר HTML ראשוני מהר (< 200ms).

- השתמש ב־**Skeleton Loaders** ובשליפת נתונים מה־API דרך JavaScript ברקע.

- עטוף חישובים כבדים ב־`await asyncio.to_thread(...)` כדי לא לחסום את ה־Event Loop.