Initial gradle-mirror CLI project

README.fa.md

@@ -0,0 +1,117 @@
+# gradle-mirror
+
+`gradle-mirror` یک ابزار خط فرمان (CLI) با پایتون است که با ویرایش فایل سراسری Gradle (`init.gradle.kts`) آینه‌های مخزن (mirror repositories) را فعال یا غیرفعال می‌کند.
+
+## قابلیت‌ها
+
+- فعال‌سازی آینه‌ها با درج یک بلاک مدیریت‌شده داخل `init.gradle.kts`
+- غیرفعال‌سازی با بازیابی فایل پشتیبان یا حذف بلاک بین markerها
+- رفتار idempotent (اجرای چندباره `active` باعث تکرار بلاک نمی‌شود)
+- خروجی رنگی در CLI
+- لاگ‌گیری از عملیات
+- سازگار با Linux، macOS و Windows
+
+## ساختار پروژه
+
+```text
+gradle_mirror/
+  __init__.py
+  init.py
+  cli.py
+  mirror_manager.py
+  gradle_locator.py
+  constants.py
+  utils.py
+  main.py
+pyproject.toml
+README.md
+README.fa.md
+```
+
+## پیش‌نیازها
+
+- Python 3.10 یا بالاتر
+- pip
+
+## نصب
+
+### روش 1 (پیشنهادی): نصب به‌صورت ابزار CLI
+
+در ریشه پروژه اجرا کنید:
+
+```bash
+python -m pip install .
+```
+
+بعد از نصب:
+
+```bash
+gradle-mirror --help
+```
+
+### روش 2: اجرا بدون نصب
+
+```bash
+python -m gradle_mirror.main --help
+```
+
+## استفاده
+
+### فعال‌سازی آینه‌ها
+
+```bash
+gradle-mirror active
+```
+
+نمونه خروجی:
+
+```text
+✅ Gradle mirror activated
+📁 Updated /Users/you/.gradle/init.gradle.kts
+```
+
+### غیرفعال‌سازی آینه‌ها
+
+```bash
+gradle-mirror deactive
+```
+
+## نحوه کار ابزار
+
+- مسیر Gradle User Home به این ترتیب تشخیص داده می‌شود:
+  1. اگر متغیر محیطی `GRADLE_USER_HOME` تنظیم شده باشد، همان استفاده می‌شود.
+  2. در غیر این صورت، مسیر پیش‌فرض `~/.gradle` استفاده می‌شود.
+- فایل هدف: `<gradle_home>/init.gradle.kts`
+- markerهای بلاک مدیریت‌شده:
+  - `/* gradle-mirror-start */`
+  - `/* gradle-mirror-end */`
+- فایل پشتیبان: `init.gradle.kts.bak`
+- فایل لاگ: `gradle-mirror.log`
+
+## نکات مهم
+
+- فرمان `active` اگر markerها از قبل موجود باشند، محتوای بین آن‌ها را جایگزین می‌کند (بدون تکرار).
+- فرمان `deactive` ابتدا تلاش می‌کند از فایل پشتیبان بازیابی کند.
+- اگر بعد از حذف بلاک، فایل `init.gradle.kts` خالی شود، فایل حذف می‌شود.
+
+## عیب‌یابی سریع
+
+- اگر خطای `No module named typer` گرفتید:
+
+```bash
+python -m pip install .
+```
+
+یا:
+
+```bash
+python -m pip install typer
+```
+
+- برای بررسی لاگ‌ها، فایل زیر را ببینید:
+
+```text
+~/.gradle/gradle-mirror.log
+```
+
+(اگر `GRADLE_USER_HOME` تنظیم شده باشد، لاگ داخل همان مسیر ساخته می‌شود.)