@jadmadi/hasan-ui-cli 0.3.0

package/LICENSE

@@ -0,0 +1,148 @@
+## Hasan-UI License Declaration
+
+هذا العمل هو وَقْفٌ لله تعالى تحت شروط رُخصة وَقْف الرَّقْمِيَّة العامَّة - الإصدار الأول.
+المُستوى المُطَبَّق هو: وَقْفٌ خَيْرِيٌّ مُلْزِمٌ بالإِسْنَادِ (WaqfDPL-Khayri-Mulzim 1.0).
+
+Full license text below.
+
+---
+
+# **رُخصة وَقْف الرَّقْمِيَّة العامَّة - الإصدار الأول (Waqf-DPL 1.0)**
+
+الإصدار الأول من رُخصة وَقْف الرَّقْمِيَّة العامَّة، 1447هـ
+
+## **ديباجة: مفهوم الوَقْف في هذه الرُخصة**
+
+هذه الرُخصة هي أداةٌ شرعيَّة وقانونيَّة لتطبيق مفهوم الوَقْف الإسلامي على الأعمال الفكرية والرقمية. الوَقْف هو "حَبْس الأصل وتَسْبِيل المنفعة"، أي جَعْل العمل الفكري بحد ذاته وَقْفًا لله تعالى لا يُباع ولا يُوهَب، مع إتاحة منفعته لعموم الناس كصَدَقَةٍ جاريةٍ يرجو بها الواقف الأجر من الله.
+
+باستخدامك أو توزيعك للعمل المُرخَّص بموجب هذه الرُخصة، فإنك تُقِر وتوافق على شروطها باعتبارها عَقْدًا مُلْزِمًا بينك وبين الواقف. نحن نؤمن بأنّ العِلم والمعرفة النافعة يجب أن تكون مُتاحة للجميع، وهذه الرُخصة هي بديلٌ إسلاميٌّ يُوازِن بين حق المُبتكِر في الأجر الدائم وحق الأُمَّة في الانتفاع.
+
+## **1\. تعريفات**
+
+* **العمل**: أيُّ مادَّة فكرية أو رقمية (مثل نصوص بَرْمَجِيَّة، كُتُب، ملفات صوتية، مرئية، صُوَر، وغيرها) يضعها صاحبها تحت هذه الرُخصة.  
+* **الواقف**: هو صاحب العمل الأصلي الذي يملك الحقوق الفكرية ويختار طَوْعًا أن يُوقِف عمله تحت هذه الرُخصة.  
+* **المُنتفِع**: هو أيُّ شخص أو جهة تستخدم العمل أو تستفيد منه بأي شكلٍ من الأشكال.  
+* **الناظر**: هو الشخص الطبيعي أو الاعتباري المعيَّن من قِبل الواقف (أو من تؤول إليه نظارة الوقف شرعاً وقانوناً بعد وفاة الواقف أو عجزه) لإدارة الوقف وحمايته وإنفاذ شروطه، ويمثل الجهة المخولة باتخاذ الإجراءات الإدارية والقانونية لحماية الوقف (مثل إلغاء الرخصة عن المخالفين أو إعادة الترخيص لهم). ويُثبت التعيين بقرار مكتوب من الواقف، أو توقيع رقمي معتمد، أو بقرار من الجهة الشرعية/القضائية المختصة عند شغور النظارة. ويلتزم الناظر بالرعاية والرقابة المستمرة؛ وبما أن أتمتة المهام الوقفية برمجياً (كالفحص التلقائي والفسخ الوقائي الآلي للأكواد) جائزة ومندوبة شرعاً لتسهيل العمل وتوفير الوقت وضبط الالتزام، فإن مسؤولية الناظر تتركز في التدخل البشري لمعالجة الأعطال وإصلاح الثغرات البرمجية والأمنية فور حدوثها، ويُعتبر إهمال الأنظمة البرمجية الوقفية بعد تعطلها أو تجاهل معالجة ثغراتها تفريطاً يوجب المسؤولية والضمان شرعاً. ويُعفى الناظر من الضمان والمسؤولية في حالات القوة القاهرة والأعطال التقنية الخارجة عن إرادته (مثل تعطل خوادم شركة الاستضافة الخارجية، أو الاختراقات السيبرانية القاهرة بالرغم من اتخاذه معايير الحماية الأمنية المناسبة لقدرات الوقف). ويملك الناظر صلاحية استبدال الوقف الرقمي (الاستبدال والتعويض الفني) بنقله لبيئات تقنية أحدث أو تصفية أصوله وتوجيهها لمشروع برمجي آخر يحقق مصلحة وقفية راجحة عند تقادم التقنية الأصلية أو كثرة تكاليف تشغيلها.  
+* **العمل** **المُشْتَقّ**: هو أيُّ عمل جديد ينتج عن تعديل العمل الأصلي أو ترجمته أو الاقتباس منه أو البناء عليه.  
+* **الترجمة** **المجهولة**: هي ترجمة العمل إلى لغة أخرى دون الإسناد الصريح والواضح إلى الواقف الأصلي أو دون ذكر الرخصة الأصلية التي يخضع لها العمل (مثل نشر الترجمة باسم المترجم فقط دون ذكر الواقف أو الرخصة).  
+* **الاستخدام** **التجاري**: هو أي استخدام للعمل أو لمشتقاته يكون الغرض الأساسي منه تحقيق ربح مادي مباشر أو غير مباشر، أو تحقيق مكاسب مالية وتجارية خاصة، بصرف النظر عن الطبيعة القانونية للجهة المستخدمة للعمل (سواء كانت تجارية، حكومية، أو غير ربحية). ويُستثنى من ذلك المكاسب الثانوية التبعية غير المقصودة للمنتفع (مثل زيادة زوار الموقع الشخصي للمنتفع نتيجة لعرض المصنف الوقفي فيه بما يزيد من أرباح إعلانات موقعه الإجمالية بصفة تبعية غير مقصودة بالذات للمصنف)، كما يُستثنى من ذلك آليات "الدعم الذاتي" (Self-Funding) التي تهدف حصراً لتغطية تكاليف التشغيل والصيانة الفنية للوقف (مثل وضع روابط التبرعات، أو تفعيل وسيط إعلاني منضبط بضوابط الشريعة لتغطية فواتير الخوادم والتشغيل فقط دون تحقيق أرباح شخصية خاصة)، طالما كان أصل عرض المصنف مجانياً لعموم الناس ولم يتم بيعه أو استغلاله للتربح بشكل مباشر مقصود.  
+* **حماية بيانات المستفيدين وخصوصيتهم (أمانة البيانات)**: تُعد البيانات الشخصية والسرية للمستفيدين من الوقف الرقمي جزءاً لا يتجزأ من أمانة الوقف المعظّمة شرعاً وقانوناً؛ وبناءً عليه يلتزم المنتفع بوضع تدابير الحماية الأمنية المناسبة لخصوصية المستخدمين، ويُمنع منعاً باتاً استغلال بياناتهم تجارياً أو تسريبها أو التفريط في حمايتها، ويُعتبر خرق خصوصية بيانات المستفيدين أو بيعها بمثابة خرق جسيم لشروط الوقف يوجب بطلان رخصة الانتفاع وسقوطها فوراً.  
+* **الرُخصة**: هذه الوثيقة بجميع بنودها ومستوياتها.
+
+## **2\. مستويات الرُخصة**
+
+يمنح الواقف الحقوق التالية للمُنتفِع شريطة اختيار أحد المستويات السبعة التالية وذكره بوضوح مع العمل:
+
+### **المستوى الأول: وَقْفٌ بالإِسْنَادِ (WaqfDPL-Isnad)**
+
+*الإسناد (Attribution): هذا المستوى هو الأكثر تساهلاً، ويسمح بالانتفاع المُطْلَق مع حفظ الحق الأدبي.*  
+يحق لك بحرية:
+
+* **المشاركة**: نَسْخ وتوزيع العمل بأي وسيط أو شكل.  
+* **التعديل**: تعديل العمل وإعادة دمجه والبناء عليه.  
+* **الاستخدام**: استخدام العمل لأي غرض، بما في ذلك الأغراض التجارية.
+
+**بالشرط الوحيد التالي:**
+
+* **الإسناد**: يجب عليك نِسْبَة العمل إلى الواقف الأصلي وذِكْر هذه الرُخصة (WaqfDPL-Isnad 1.0) ورابطها إن أمكن، دون الإيحاء بأنّ الواقف يتبنَّى عملَك المُشْتَقّ.
+
+### **المستوى الثاني: وَقْفٌ مُلْزِمٌ بالإِسْنَادِ (WaqfDPL-Mulzim)**
+
+*المُلْزِم (Binding/ShareAlike): هذا المستوى يضمن استمرارية الوقف في الأعمال المشتقة (Copyleft - حقوق متروكة).*  
+**يحق لك بحرية:**
+
+* **المشاركة**: نَسْخ وتوزيع العمل بأي وسيط أو شكل.  
+* **التعديل**: تعديل العمل وإعادة دمجه والبناء عليه.  
+* **الاستخدام**: استخدام العمل لأي غرض، بما في ذلك الأغراض التجارية.
+
+**بالشروط التالية:**
+
+* **الإسناد**: يجب عليك نِسْبَة العمل إلى الواقف الأصلي وذِكْر هذه الرُخصة (WaqfDPL-Mulzim 1.0).  
+* **الإلزام**: إذا قمت بتعديل العمل أو بنيت عليه، فيجب عليك توزيع عملك المُشْتَقّ تحت نفس الرُخصة (WaqfDPL-Mulzim 1.0) حَصْرًا. هذا الشرط يُلْزِم باستمرارية الوقف ويُحقِّق مبدأ "حَبْس الأصل".
+
+### **المستوى الثالث: وَقْفٌ خَيْرِيٌّ بالإِسْنَادِ (WaqfDPL-Khayri)**
+
+*الخَيْرِيّ (NonCommercial): هذا المستوى يَقْصُر الانتفاع على الأغراض غير الربحية والخيرية.*  
+**يحق لك بحرية:**
+
+* **المشاركة**: نَسْخ وتوزيع العمل بأي وسيط أو شكل.  
+* **التعديل**: تعديل العمل وإعادة دمجه والبناء عليه، على ألا تكون رخصة العمل المشتق أكثر تقييداً من رخصة الأصل لضمان عدم تضييق المنفعة الوقفية.
+
+**بالشروط التالية:**
+
+* **الإسناد**: يجب عليك نِسْبَة العمل إلى الواقف الأصلي وذِكْر هذه الرُخصة (WaqfDPL-Khayri 1.0).  
+* **الاستخدام** **الخيري**: لا يجوز لك استخدام العمل لأغراض تجارية أو ربحية بشكلٍ أساسي، ويقتصر على الأغراض الشخصية والخيرية والتعليمية والدعوية.
+
+### 
+
+### **المستوى الرابع: وَقْفٌ خَيْرِيٌّ مُلْزِمٌ بالإِسْنَادِ (WaqfDPL-Khayri-Mulzim)**
+
+*الخيري الملزم (NonCommercial-ShareAlike): هذا المستوى يدمج حظر الربح المادي مع اشتراط استمرارية النية الوقفية في جميع التعديلات والأعمال المشتقة.*  
+**يحق لك بحرية:**
+
+* **المشاركة**: نَسْخ وتوزيع العمل بأي وسيط أو شكل.  
+* **التعديل**: تعديل العمل وإعادة دمجه والبناء عليه.
+
+**بالشروط التالية:**
+
+* **الإسناد**: يجب عليك نِسْبَة العمل إلى الواقف الأصلي وذِكْر هذه الرُخصة (WaqfDPL-Khayri-Mulzim 1.0).  
+* **الاستخدام** **الخيري**: لا يجوز لك استخدام العمل لأغراض تجارية أو ربحية مادية مباشرة.  
+* **الإلزام** **الخيري**: إذا قمت بتعديل العمل أو بنيت عليه، فيجب عليك توزيع عملك المُشْتَقّ تحت نفس الرُخصة (WaqfDPL-Khayri-Mulzim 1.0) حَصْرًا وبشكل خيري ومفتوح للجميع.
+
+### **المستوى الخامس: وَقْفٌ مَحْفُوظٌ بالإِسْنَادِ (WaqfDPL-Mahfudh)**
+
+*المَحْفُوظ (NoDerivatives): هذا المستوى يحفظ العمل على صورته الأصلية ويمنع تعديله أو ترجمته أو اقتباسه، مع تعميم منفعته بنشره ككتلة صلبة واحدة.*  
+**يحق لك بحرية:**
+
+* **المشاركة**: نَسْخ وتوزيع العمل بصورته الأصلية فقط بأي وسيط أو شكل ولأي غرض، بما في ذلك التجاري.
+
+**بالشروط التالية:**
+
+* **الإسناد**: يجب عليك نِسْبَة العمل إلى الواقف الأصلي وذِكْر هذه الرُخصة (WaqfDPL-Mahfudh 1.0).  
+* **الحِفْظ**: لا يجوز للمنتفعين تعديل العمل أو البناء عليه، ويُمنع توزيع أي عمل مُشْتَقٍّ منه، ويُمنع منعاً باتاً إجراء أي ترجمة أو اقتباس للعمل بأي شكلٍ من الأشكال. ويُستثنى من ذلك التحديثات الفنية أو أعمال الصيانة البرمجية اللازمة التي يقوم بها الواقف أو الناظر المعتمد حمايةً للوقف من الموت التقني والتقادم.
+
+### **المستوى السادس: وَقْفٌ خَيْرِيٌّ مَحْفُوظٌ بالإِسْنَادِ (WaqfDPL-Khayri-Mahfudh)**
+
+*الخيري المحفوظ (NonCommercial-NoDerivatives): هذا المستوى يجمع بين حظر الربح المادي ومنع أي تعديل أو تحوير للعمل لحماية سلامته التامة وموثوقيته.*  
+**يحق لك بحرية:**
+
+* **المشاركة**: نَسْخ وتوزيع العمل بصورته الأصلية فقط مجاناً في جميع القطاعات الخيرية والدعوية والتعليمية والشخصية.
+
+**بالشروط التالية:**
+
+* الإسناد: يجب عليك نِسْبَة العمل إلى الواقف الأصلي وذِكْر هذه الرُخصة (WaqfDPL-Khayri-Mahfudh 1.0).  
+* **الاستخدام** **الخيري**: يمنع منعاً باتاً البيع أو الاستخدام التجاري الربحي للعمل.  
+* **الحفظ** **التام**: لا يجوز للمنتفعين تعديل العمل أو دمج أجزاء منه أو قصها وتجزئتها، ويُمنع منعاً باتاً إجراء أي ترجمة أو اقتباس للعمل بأي شكلٍ من الأشكال. ويُستثنى من ذلك التحديثات الفنية أو أعمال الصيانة البرمجية اللازمة التي يقوم بها الواقف أو الناظر المعتمد حمايةً للوقف من الموت التقني والتقادم.
+
+ 
+
+### **المستوى السابع: وَقْفٌ مُقَيَّدٌ بالإِسْنَادِ (WaqfDPL-Muqayyad)**
+
+*المُقَيَّد (Restricted): هذا المستوى يسمح للواقف بوضع شرط إضافي خاص به، وهو بمثابة وعاء مرن (Wrapper) يُطبق إلزاماً استناداً إلى أحد المستويات الستة القياسية السابقة.*  
+**صيغة التطبيق الإلزامية للمستوى السابع:**
+
+* **المستوى** **الأساسي** **المطبَّق:** \[يجب ذكر أحد المستويات الستة الأولى حصراً كأساس للرخصة، مثلاً: المستوى الثالث: الوقف الخيري (WaqfDPL-Khayri 1.0)\].  
+* **الشرط** **الخاص** **الإضافي** **للواقف**: \[اكتب شرطك الخاص هنا بوضوح تام، مثال: "يُقصر منفعة هذا العمل على الأغراض التعليمية لجمعيات ودور رعاية الأيتام فقط"\].
+
+**قواعد التوافق ومنع التناقض الهيكلي (Consistency & Non-Contradiction Rules)**: للحفاظ على تماسك الرخصة وصلاحيتها القانونية، يخضع الشرط الخاص لقاعدة عدم التناقض مع المستوى الأساسي المختار:
+
+1. **قاعدة حظر التجارة**: إذا أراد الواقف منع الاستخدام التجاري بالشرط الخاص، يجب عليه اختيار مستوى أساسي يمنع التجارة أصلاً (المستويات 3 أو 4 أو 6). ويُمنع منعاً باتاً اختيار أساس يبيح التجارة (مثل المستويات 1 أو 2\) ثم حظرها بالشرط الخاص.  
+2. **قاعدة حظر التعديل**: إذا أراد الواقف منع التعديل بالشرط الخاص، يجب عليه اختيار مستوى أساسي محفوظ يمنع التعديل (المستويات 5 أو 6). ويُمنع اختيار أساس يبيح التعديل (مثل المستويات 1 أو 2\) ثم حظره بالشرط الخاص.  
+3. **قاعدة الأولوية والفساد**: في حال وجود أي تعارض أو تناقض صريح بين الشرط الخاص والمستوى الأساسي المختار، يُعتبر الشرط الخاص باطلاً ومُلغى وتُطبق شروط المستوى القياسي الأساسي المختار حمايةً لاستقرار الانتفاع ومصلحة الوقف العامة.
+
+## **3\. أحكام عامَّة (تنطبق على جميع المستويات)**
+
+* **الغرض الشرعي (سقوط الإذن بالاستخدام المحرم)**: هذا العمل هو وَقْفٌ لله تعالى لخدمة المجتمع ونشر النفع العام. ويُشترط شرعاً وقانوناً ألا يُسخر العمل أو مشتقاته في أي أغراض تخالف مبادئ الشريعة الإسلامية ومحرماتها الصارخة (مثل استخدام العمل أو دمجه في منصات القمار، أو المحتوى الإباحي، أو ترويج الشبهات العقدية الهدامة، أو المعاملات الربوية الصريحة). والواقف والناظر غير مسؤولين عن أي استخدام غير مشروع يقوم به المُنتفِع، ويُعتبر توجيه العمل لهذه المحرمات خروجاً صريحاً عن غاية الوقف يبطل عقد الإذن ويسقط رخصة الاستخدام فوراً وبشكل تلقائي عن المخالف.  
+* **الدوام** **والأبديَّة**: هذه الرُخصة أبديَّةٌ ولا تُلغَى. إذا انتهت مُدَّة حماية حقوق المِلكية الفكرية وِفْقًا للقوانين المحلية، ينتقل العمل إلى المِلْك العامّ (Public Domain)، مع بقاء نيَّة الوَقْف كصَدَقَةٍ جاريةٍ قائمةً شرعًا.  
+* **إلغاء الرخصة التلقائي عند المخالفة (الفسخ الوقائي التلقائي)**: تسقط هذه الرخصة وتُلغى حقوق الاستخدام والتوزيع الممنوحة بموجبها تلقائياً وفوراً بمجرد وقوع أي مخالفة أو خرق لشروطها من قِبل المُنتفِع (مثل عدم الإسناد، أو الاستخدام التجاري في المستويات الخيرية، أو التعديل والترجمة والاقتباس المحظور في المستويات المحفوظة، أو الترجمة دون إسناد في المستويات الأخرى، أو خرق خصوصية بيانات المستفيدين واستغلالها تجارياً، أو توجيه العمل في المحرمات الشرعية الصارخة). ويترتب على هذا الإلغاء التلقائي سقوط كافة الحقوق فوراً وتوقف المخالف عن أي منفعة جديدة، مع منحه مهلة تقنية لا تتجاوز 30 يوماً فقط للإزالة المادية والحذف لكافة النسخ التي قام بنشرها أو توزيعها مسبقاً، دون أن يؤثر ذلك على بقية المنتفعين الملتزمين. وللواقف أو الناظر إخطار المخالف رسمياً بالإلغاء، ولا يجوز إعادة الترخيص للمخالف إلا بطلب جديد وموافقة صريحة من الواقف أو الناظر بعد تصحيح المخالفة تماماً.  
+* **عدم الضمان وإخلاء المسؤولية**: يُقدِّم الواقف العمل "كما هو" دون أي ضمانات من أي نوع، صريحةً أو ضمنيَّة. لا يتحمَّل الواقف أي مسؤولية عن أي أضرار مباشرة أو غير مباشرة قد تنشأ عن استخدام العمل، إلى أقصى حدٍّ يسمح به القانون.  
+* **استخدامات الذكاء الاصطناعي والتعلُّم الآلي**: يخضع استخدام العمل في تدريب النماذج البرمجية أو أنظمة الذكاء الاصطناعي وتوليد البيانات لنفس شروط الوقف؛ حيث يلتزم المُنتفِع بالحفاظ على الإسناد للواقف، كما يُمنع منعاً باتاً استخدام العمل أو أجزائه أو مشتقاته في تدريب أي نماذج تُوزَّع تجارياً أو تُستخدم للتربح المادي والربح التجاري الخاص في جميع المستويات الخيرية (المستويات 3 و4 و6).  
+* **اقتصار الرخصة على الصيغة الرقمية**: تنطبق هذه الرخصة على المصنف في صيغته الرقمية والبرمجية والإلكترونية فقط (سواء كان كوداً، أو تطبيقاً، أو كتاباً إلكترونياً، أو وثيقة رقمية). ونشير إلى أن نسخ المصنف الرقمي أو حفظه على وسيط مادي ملموس (كأجهزة الحاسب، أو الخوادم، أو الأقراص المدمجة، أو بطاقات الذاكرة) لا يُخرجه عن كونه وقفاً رقمياً خاضعاً لأحكام هذه الرخصة؛ حيث يظل المحتوى الرقمي المخزن داخلها وقفاً رقمياً، بينما يُعتبر الوعاء المادي الحامل له (القرص أو الجهاز المادي) وقفاً منقولاً موازياً. ويخرج المصنف عن النطاق الرقمي للرخصة فقط في حال طباعته مادية على ورق فيزيائي، حيث يخضع حينها للوقف المنقول التقليدي.  
+* **دمج الأوقاف الرقمية (Waqf Integration)**: يجوز دمج المصنف الموقوف بموجب هذه الرخصة مع مصنف وقفي رقمي آخر خاضع لرخصة وقف (أو رخصة متوافقة)، لتتحد إدارتهما تحت ناظر أو إدارة واحدة، إذا كان ذلك يحقق مصلحة راجحة، كزيادة النفع العام وتخفيض التكاليف والجهود التقنية، بشرط ألا يؤدي هذا الدمج إلى نزاع أو تصادم مع الشروط الجوهرية للواقفين الأصليين.  
+* الإصدارات المستقبلية: قد تُصدِر "وَقْف" إصدارات جديدة من هذه الرُخصة. يبقى العمل مُرخَّصًا بالإصدار الذي تم نشره به، وللواقف الخيار في إعادة ترخيصه بالإصدارات الأحدث.
+
+## **ثانياً: كيفية تطبيق الرخصة وتخصيصها للمستويات الأخرى (قالب التخصيص)**
+
+لتطبيق هذه الرُخصة وتخصيصها لمستوى مختلف من المستويات السبعة على عملك، قُمْ بتضمين النص التالي في مكانٍ بارز (مثل ملف README في مشروع بَرْمَجِي، أو في صفحة حقوق النشر الإلكترونية في كتاب رقمي):
+
+"هذا العمل هو وَقْفٌ لله تعالى تحت شروط رُخصة وَقْف الرَّقْمِيَّة العامَّة - الإصدار الأول. المُستوى المُطَبَّق هو: \[اذكر هنا اسم المستوى، مثلاً: وَقْفٌ مُلْزِمٌ بالإِسْنَادِ (WaqfDPL-Mulzim 1.0)\]. \[في حال اختيار "الوقف المقيد"، أضف السطر التالي:\] الشرط الخاص للواقف هو: \[اكتب شرطك هنا\]. يمكن الاطلاع على نسخة كاملة من الرُخصة هنا: \[رابط إلى نص الرُخصة\]"

package/dist/index.js

@@ -0,0 +1,663 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/add.ts
+import { mkdirSync, writeFileSync, existsSync } from "fs";
+import { join as join2, dirname } from "path";
+import { execSync } from "child_process";
+
+// src/registry.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+var GITHUB_API = "https://api.github.com/repos/WaqfTech/hasan-ui/contents";
+function getHeaders() {
+  const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (token) {
+    return { Authorization: `token ${token}` };
+  }
+  return {};
+}
+async function fetchGithubJson(path) {
+  const normalizedPath = path.replace(/^\.\//, "");
+  const response = await fetch(`${GITHUB_API}/${normalizedPath}`, { headers: getHeaders() });
+  if (!response.ok) throw new Error(`GitHub API error: ${response.status}`);
+  const data = await response.json();
+  const content = Buffer.from(data.content, "base64").toString("utf-8");
+  return JSON.parse(content);
+}
+async function fetchGithubText(path) {
+  const normalizedPath = path.replace(/^\.\//, "");
+  const response = await fetch(`${GITHUB_API}/${normalizedPath}`, { headers: getHeaders() });
+  if (!response.ok) throw new Error(`GitHub API error: ${response.status}`);
+  const data = await response.json();
+  return Buffer.from(data.content, "base64").toString("utf-8");
+}
+async function fetchRegistryFromGithub() {
+  const allItems = [];
+  async function fetchWithIncludes(path) {
+    try {
+      const registry = await fetchGithubJson(path);
+      if (registry.items) {
+        const itemsWithPath = registry.items.map((item) => ({
+          ...item,
+          _registryPath: path
+        }));
+        allItems.push(...itemsWithPath);
+      }
+      if (registry.include) {
+        const basePath = path.substring(0, path.lastIndexOf("/") + 1);
+        for (const inc of registry.include) {
+          let resolvedPath;
+          if (inc.startsWith("registry/")) {
+            resolvedPath = inc;
+          } else {
+            const normalizedInc = inc.replace(/^\.\//, "");
+            resolvedPath = `${basePath}${normalizedInc}`;
+          }
+          await fetchWithIncludes(resolvedPath);
+        }
+      }
+    } catch {
+    }
+  }
+  await fetchWithIncludes("registry/registry.json");
+  return allItems.filter(
+    (item) => item.type !== "registry:collection" && item.name && item.titleEn
+  );
+}
+async function fetchRegistry() {
+  try {
+    const items = await fetchRegistryFromGithub();
+    if (items.length > 0) return items;
+  } catch {
+  }
+  try {
+    let resolveLocal2 = function(path) {
+      const fullPath = join(process.cwd(), path);
+      if (visited.has(fullPath)) return;
+      visited.add(fullPath);
+      let data;
+      try {
+        data = JSON.parse(readFileSync(fullPath, "utf-8"));
+      } catch {
+        return;
+      }
+      if (data.items) {
+        const itemsWithPath = data.items.map((item) => ({
+          ...item,
+          _registryPath: path
+        }));
+        allItems.push(...itemsWithPath);
+      }
+      if (data.include) {
+        const basePath = path.substring(0, path.lastIndexOf("/") + 1);
+        for (const inc of data.include) {
+          let resolvedPath;
+          if (inc.startsWith("registry/")) {
+            resolvedPath = inc;
+          } else {
+            resolvedPath = `${basePath}${inc.replace(/^\.\//, "")}`;
+          }
+          resolveLocal2(resolvedPath);
+        }
+      }
+    };
+    var resolveLocal = resolveLocal2;
+    const allItems = [];
+    const visited = /* @__PURE__ */ new Set();
+    resolveLocal2("registry/registry.json");
+    const filtered = allItems.filter(
+      (item) => item.type !== "registry:collection" && item.name && item.titleEn
+    );
+    if (filtered.length > 0) return filtered;
+  } catch {
+  }
+  console.error("Could not fetch registry. Options:");
+  console.error("  1. Set GITHUB_TOKEN env var for private repo access");
+  console.error("  2. Run from the hasan-ui directory");
+  console.error("  3. Make the repo public");
+  process.exit(1);
+}
+async function fetchFileContent(filePath, registryPath) {
+  let fullPath = filePath;
+  if (registryPath) {
+    const registryDir = registryPath.substring(0, registryPath.lastIndexOf("/") + 1);
+    fullPath = `${registryDir}${filePath}`;
+  }
+  try {
+    return await fetchGithubText(fullPath);
+  } catch {
+  }
+  try {
+    const localPath = join(process.cwd(), "registry", filePath);
+    return readFileSync(localPath, "utf-8");
+  } catch {
+  }
+  return null;
+}
+function findItem(items, name) {
+  return items.find((item) => item.name === name);
+}
+function findItemsByPattern(items, pattern) {
+  return items.filter((item) => item.name.startsWith(pattern));
+}
+function filterByType(items, type) {
+  return items.filter((item) => item.tags?.type?.includes(type));
+}
+function filterByPurpose(items, purpose) {
+  return items.filter((item) => item.tags?.purposes?.includes(purpose));
+}
+async function fetchCollections() {
+  try {
+    const collections = [];
+    async function fetchCollectionFiles(path) {
+      try {
+        const registry = await fetchGithubJson(path);
+        if (registry.items?.length) {
+          collections.push(...registry.items.map((c) => ({ ...c, _registryPath: path })));
+        }
+        if (registry.include) {
+          const basePath = path.substring(0, path.lastIndexOf("/") + 1);
+          for (const inc of registry.include) {
+            let resolvedPath;
+            if (inc.startsWith("registry/")) {
+              resolvedPath = inc;
+            } else {
+              resolvedPath = `${basePath}${inc.replace(/^\.\//, "")}`;
+            }
+            try {
+              const collection = await fetchGithubJson(resolvedPath);
+              collections.push({ ...collection, _registryPath: resolvedPath });
+            } catch {
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    await fetchCollectionFiles("registry/collections/registry.json");
+    if (collections.length > 0) return collections;
+  } catch {
+  }
+  try {
+    const collections = [];
+    const collectionsDir = join(process.cwd(), "registry", "collections");
+    const registryPath = join(collectionsDir, "registry.json");
+    const registry = JSON.parse(readFileSync(registryPath, "utf-8"));
+    if (registry.include) {
+      for (const inc of registry.include) {
+        const incPath = join(collectionsDir, inc.replace(/^\.\//, ""));
+        try {
+          const collection = JSON.parse(readFileSync(incPath, "utf-8"));
+          collections.push(collection);
+        } catch {
+        }
+      }
+    }
+    if (registry.items?.length) {
+      collections.push(...registry.items.map((c) => ({ ...c, _registryPath: "registry/collections/registry.json" })));
+    }
+    return collections;
+  } catch {
+  }
+  return [];
+}
+function findCollection(collections, name) {
+  return collections.find((c) => c.name === name);
+}
+function decodeCartUrl(url) {
+  try {
+    const match = url.match(/\/c\/([A-Za-z0-9_-]+)$/);
+    if (!match) return null;
+    const json = Buffer.from(match[1], "base64url").toString("utf-8");
+    const payload = JSON.parse(json);
+    return payload.items;
+  } catch {
+    return null;
+  }
+}
+
+// src/add.ts
+function ensureDir(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+function installDependencies(deps) {
+  if (deps.length === 0) return;
+  const hasYarn = existsSync("yarn.lock");
+  const hasPnpm = existsSync("pnpm-lock.yaml");
+  let cmd;
+  if (hasPnpm) {
+    cmd = `pnpm add ${deps.join(" ")}`;
+  } else if (hasYarn) {
+    cmd = `yarn add ${deps.join(" ")}`;
+  } else {
+    cmd = `npm install ${deps.join(" ")}`;
+  }
+  console.log(`Installing dependencies: ${deps.join(", ")}`);
+  execSync(cmd, { stdio: "inherit" });
+}
+async function add(names, options) {
+  if (options.collection) {
+    const cartItems = decodeCartUrl(options.collection);
+    if (cartItems) {
+      console.log(`Installing ${cartItems.length} items from cart URL...`);
+      await addMultiple(cartItems, options);
+      return;
+    }
+    const collections2 = await fetchCollections();
+    const collection2 = findCollection(collections2, options.collection);
+    if (!collection2) {
+      console.error(`Collection "${options.collection}" not found`);
+      console.error(
+        `Available: ${collections2.map((c) => c.name).join(", ") || "none"}`
+      );
+      process.exit(1);
+    }
+    console.log(`Installing collection: ${collection2.name} (${collection2.titleEn})`);
+    console.log(`  ${collection2.descriptionEn}`);
+    console.log(`  Items: ${collection2.items.join(", ")}
+`);
+    await addMultiple(collection2.items, options);
+    return;
+  }
+  const nameList = Array.isArray(names) ? names : [names];
+  if (nameList.length > 1) {
+    await addMultiple(nameList, options);
+    return;
+  }
+  const singleName = nameList[0];
+  const collections = await fetchCollections();
+  const collection = findCollection(collections, singleName);
+  if (collection) {
+    console.log(`Installing collection: ${collection.name} (${collection.titleEn})`);
+    console.log(`  ${collection.descriptionEn}`);
+    console.log(`  Items: ${collection.items.join(", ")}
+`);
+    await addMultiple(collection.items, options);
+    return;
+  }
+  const items = await fetchRegistry();
+  const item = findItem(items, singleName);
+  if (!item) {
+    const matches = findItemsByPattern(items, singleName);
+    if (matches.length === 0) {
+      console.error(`Component "${singleName}" not found in registry`);
+      process.exit(1);
+    }
+    for (const match of matches) {
+      await addSingle(match, options);
+    }
+    return;
+  }
+  await addSingle(item, options);
+}
+async function addMultiple(names, options) {
+  const items = await fetchRegistry();
+  const installed = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    if (installed.has(name)) continue;
+    const item = findItem(items, name);
+    if (!item) {
+      console.error(`Component "${name}" not found in registry, skipping`);
+      continue;
+    }
+    await addSingle(item, options);
+    installed.add(name);
+  }
+  console.log(`
+\u2713 Installed ${installed.size} components`);
+}
+async function addSingle(item, options) {
+  console.log(`Adding ${item.name} (${item.titleEn})...`);
+  if (item.dependencies?.length) {
+    installDependencies(item.dependencies);
+  }
+  for (const file of item.files) {
+    const targetPath = join2(process.cwd(), file.target);
+    if (existsSync(targetPath) && !options.overwrite) {
+      console.log(`  Skipping ${file.target} (already exists)`);
+      continue;
+    }
+    ensureDir(targetPath);
+    const sourceContent = await fetchFileContent(file.path, item._registryPath);
+    if (sourceContent) {
+      writeFileSync(targetPath, sourceContent);
+    } else {
+      const content = `// ${item.name} - ${item.titleEn}
+// ${item.descriptionEn}
+// Source: ${item.title}
+
+export default function ${item.name.replace(/-/g, "")}() {
+  return <div>${item.title}</div>
+}
+`;
+      writeFileSync(targetPath, content);
+    }
+    console.log(`  Created ${file.target}`);
+  }
+  console.log(`\u2713 Added ${item.name}`);
+}
+
+// src/list.ts
+async function list(options) {
+  if (options.collections) {
+    await listCollections();
+    return;
+  }
+  let items = await fetchRegistry();
+  if (items.length === 0) {
+    console.log("No components found in registry.");
+    return;
+  }
+  if (options.type) {
+    items = filterByType(items, options.type);
+    if (items.length === 0) {
+      console.log(`No components with type "${options.type}".`);
+      return;
+    }
+  }
+  if (options.purpose) {
+    items = filterByPurpose(items, options.purpose);
+    if (items.length === 0) {
+      console.log(`No components with purpose "${options.purpose}".`);
+      return;
+    }
+  }
+  const grouped = {};
+  for (const item of items) {
+    const path = item._registryPath || "";
+    let category = "other";
+    if (path.includes("/forms/")) category = "forms";
+    else if (path.includes("/navigation/")) category = "navigation";
+    else if (path.includes("/data-display/")) category = "data-display";
+    else if (path.includes("/feedback/")) category = "feedback";
+    else if (path.includes("/modals/")) category = "modals";
+    else if (path.includes("/layout/")) category = "layout";
+    else if (path.includes("/media/")) category = "media";
+    else if (path.includes("/blocks/")) category = "blocks";
+    else if (path.includes("/intents/")) category = "intents";
+    if (!grouped[category]) grouped[category] = [];
+    grouped[category].push(item);
+  }
+  const categories = options.category ? [options.category] : Object.keys(grouped).sort();
+  console.log("\n  hasan-ui components\n");
+  for (const cat of categories) {
+    const catItems = grouped[cat];
+    if (!catItems || catItems.length === 0) {
+      console.log(`  ${cat}: no components found`);
+      continue;
+    }
+    console.log(`  ${cat} (${catItems.length})`);
+    for (const item of catItems) {
+      const tags = item.tags ? ` [${item.tags.type.join(",")}/${item.tags.purposes.join(",")}]` : "";
+      console.log(`    ${item.name.padEnd(20)} ${item.titleEn}${tags}`);
+    }
+    console.log();
+  }
+  console.log(`  Total: ${items.length} components
+`);
+  console.log("  Usage: hasan-ui add <component-name>");
+  console.log("         hasan-ui add <name1> <name2> <name3>");
+  console.log("         hasan-ui add collection <name>\n");
+}
+async function listCollections() {
+  const collections = await fetchCollections();
+  if (collections.length === 0) {
+    console.log("\n  No collections found in registry.\n");
+    return;
+  }
+  console.log("\n  hasan-ui collections\n");
+  for (const col of collections) {
+    console.log(`  ${col.name.padEnd(25)} ${col.titleEn}`);
+    console.log(`    ${col.descriptionEn}`);
+    console.log(`    Items: ${col.items.join(", ")}`);
+    console.log(`    Purposes: ${col.tags?.purposes?.join(", ") || "n/a"}`);
+    console.log();
+  }
+  console.log(`  Total: ${collections.length} collections
+`);
+  console.log("  Usage: hasan-ui add collection <name>");
+  console.log("         hasan-ui add --collection <name>\n");
+}
+
+// src/init.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
+import { execSync as execSync2 } from "child_process";
+var DEFAULT_GLOBALS_CSS = `@import "tailwindcss";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme {
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+  --color-popover: hsl(var(--popover));
+  --color-popover-foreground: hsl(var(--popover-foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-ring: hsl(var(--ring));
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --font-sans: var(--font-arabic), ui-sans-serif, system-ui, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  --font-arabic: 'Noto Kufi Arabic', ui-sans-serif, system-ui, sans-serif;
+  --font-latin: 'Inter', ui-sans-serif, system-ui, sans-serif;
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: 40 15% 97%;
+  --foreground: 30 7% 21%;
+  --card: 40 15% 95%;
+  --card-foreground: 30 7% 21%;
+  --popover: 40 15% 95%;
+  --popover-foreground: 30 7% 21%;
+  --primary: 28 78% 60%;
+  --primary-foreground: 0 0% 100%;
+  --secondary: 40 15% 94%;
+  --secondary-foreground: 30 7% 21%;
+  --muted: 30 10% 90%;
+  --muted-foreground: 30 7% 50%;
+  --accent: 36 95% 66%;
+  --accent-foreground: 30 7% 21%;
+  --destructive: 0 72% 51%;
+  --destructive-foreground: 0 0% 100%;
+  --border: 30 10% 88%;
+  --input: 30 10% 88%;
+  --ring: 28 78% 60%;
+}
+
+.dark {
+  --background: 30 7% 15%;
+  --foreground: 40 15% 92%;
+  --card: 30 7% 18%;
+  --card-foreground: 40 15% 92%;
+  --popover: 30 7% 18%;
+  --popover-foreground: 40 15% 92%;
+  --primary: 28 78% 60%;
+  --primary-foreground: 30 7% 15%;
+  --secondary: 30 7% 22%;
+  --secondary-foreground: 40 15% 92%;
+  --muted: 30 7% 25%;
+  --muted-foreground: 30 7% 60%;
+  --accent: 36 95% 66%;
+  --accent-foreground: 30 7% 15%;
+  --destructive: 0 62% 50%;
+  --destructive-foreground: 0 0% 100%;
+  --border: 30 7% 28%;
+  --input: 30 7% 28%;
+  --ring: 28 78% 60%;
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  html {
+    direction: rtl;
+    text-align: start;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-family: var(--font-arabic), var(--font-latin), sans-serif;
+  }
+}
+
+@utility rtl-flip {
+  transform: scaleX(-1);
+}
+`;
+var DEFAULT_COMPONENTS_JSON = `{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "css": "src/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}
+`;
+var DEFAULT_UTILS_TS = `import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+`;
+function detectPackageManager() {
+  if (existsSync2("pnpm-lock.yaml")) return "pnpm";
+  if (existsSync2("yarn.lock")) return "yarn";
+  if (existsSync2("package-lock.json")) return "npm";
+  return "npm";
+}
+function runCommand(cmd) {
+  console.log(`  $ ${cmd}`);
+  execSync2(cmd, { stdio: "inherit" });
+}
+async function init() {
+  const cwd = process.cwd();
+  const pm = detectPackageManager();
+  console.log("Initializing hasan-ui in the current project...\n");
+  const dirs = ["src/components/ui", "src/lib"];
+  for (const dir of dirs) {
+    const fullPath = join3(cwd, dir);
+    if (!existsSync2(fullPath)) {
+      mkdirSync2(fullPath, { recursive: true });
+      console.log(`  Created ${dir}/`);
+    }
+  }
+  const cssPath = join3(cwd, "src", "globals.css");
+  if (!existsSync2(cssPath)) {
+    writeFileSync2(cssPath, DEFAULT_GLOBALS_CSS);
+    console.log("  Created src/globals.css");
+  }
+  const configPath = join3(cwd, "components.json");
+  if (!existsSync2(configPath)) {
+    writeFileSync2(configPath, DEFAULT_COMPONENTS_JSON);
+    console.log("  Created components.json");
+  }
+  const utilsPath = join3(cwd, "src", "lib", "utils.ts");
+  if (!existsSync2(utilsPath)) {
+    writeFileSync2(utilsPath, DEFAULT_UTILS_TS);
+    console.log("  Created src/lib/utils.ts");
+  }
+  const deps = ["tailwindcss", "clsx", "tailwind-merge", "class-variance-authority"];
+  const radixDeps = ["@radix-ui/react-slot"];
+  console.log("\n  Installing dependencies...");
+  if (pm === "pnpm") {
+    runCommand(`pnpm add ${[...deps, ...radixDeps].join(" ")}`);
+  } else if (pm === "yarn") {
+    runCommand(`yarn add ${[...deps, ...radixDeps].join(" ")}`);
+  } else {
+    runCommand(`npm install ${[...deps, ...radixDeps].join(" ")}`);
+  }
+  console.log("\n\u2713 hasan-ui initialized");
+  console.log("  Next: add components with `hasan-ui add <component>`");
+}
+
+// src/diff.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+async function diff(name) {
+  const items = await fetchRegistry();
+  const item = findItem(items, name);
+  if (!item) {
+    console.error(`Component "${name}" not found in registry`);
+    process.exit(1);
+  }
+  console.log(`
+  Diff for ${item.name} (${item.titleEn})
+`);
+  for (const file of item.files) {
+    const targetPath = file.target;
+    if (!existsSync3(targetPath)) {
+      console.log(`  ${targetPath}: not installed`);
+      continue;
+    }
+    const localContent = readFileSync2(targetPath, "utf-8");
+    const upstreamContent = await fetchFileContent(file.path, item._registryPath);
+    if (!upstreamContent) {
+      console.log(`  ${targetPath}: could not fetch upstream`);
+      continue;
+    }
+    if (localContent.trim() === upstreamContent.trim()) {
+      console.log(`  ${targetPath}: up to date`);
+    } else {
+      console.log(`  ${targetPath}: modified`);
+    }
+  }
+  console.log();
+}
+
+// src/index.ts
+var program = new Command();
+program.name("hasan-ui").description("hasan-ui component installer").version("0.1.0");
+program.command("init").description("Initialize hasan-ui in your project").action(async () => {
+  await init();
+});
+program.command("add").description("Add component(s) or a collection to your project").argument("[names...]", 'Component name(s) or "collection <name>"').option("--overwrite", "Overwrite existing files").option("--collection <name|url>", "Install a curated collection by name or a cart URL").action(async (names, options) => {
+  if (names[0] === "collection" && names[1]) {
+    await add(names[1], { ...options, collection: names[1] });
+    return;
+  }
+  if (names.length === 0 && !options.collection) {
+    console.error("Usage: hasan-ui add <name> | hasan-ui add <name1> <name2> | hasan-ui add collection <name> | hasan-ui add --collection <name|url>");
+    process.exit(1);
+  }
+  await add(names, options);
+});
+program.command("list").description("List all available components or collections").option("-c, --category <category>", "Filter by category (forms, navigation, data-display, feedback, blocks, intents)").option("--type <type>", "Filter by TYPE tag (primitive, form, navigation, data-display, feedback, block, template, layout, overlay, media)").option("--purpose <purpose>", "Filter by PURPOSE tag (ecommerce, education, quran, auth, admin, content, marketing, islamic, media, communication, geo, finance, general)").option("--collections", "List curated collections instead of components").action(async (options) => {
+  await list(options);
+});
+program.command("diff").description("Show diff between installed and upstream component").argument("<name>", "Component name").action(async (name) => {
+  await diff(name);
+});
+program.parse();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@jadmadi/hasan-ui-cli",
+  "version": "0.3.0",
+  "license": "SEE LICENSE IN ../../LICENSE",
+  "type": "module",
+  "bin": {
+    "hasan-ui": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8.5.1",
+    "typescript": "^6",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "test": "vitest run"
+  }
+}