Kernel Developer Onboarding: دليل مطور BrightAI Kernel

مرحباً بك في فريق Kernel

هالدليل يخذك من الصفر لحد ما تقدر تساهم في Kernel باستقلالية. المطلوب منك:

• خبرة في TypeScript أو JavaScript
• فهم أساسي لأمان الويب
• تثبيت Node.js 18+ وpnpm
• حساب GitHub مرتبط بالمشروع

إعداد البيئة المحلية

1. استنساخ المستودع: git clone من GitHub
2. تثبيت الاعتماديات: pnpm install
3. إعداد متغيرات البيئة: انسخ .env.example إلى .env
4. تشغيل محلي: pnpm dev
5. تشغيل الاختبارات: pnpm test

بنية المشروع

سير العمل اليومي

1. _pull latest_ من main
2. أنشئ فرع جديد من main
3. اكتب اختبارات أولاً (TDD)
4. نفّذ التغيير
5. شغّل الاختبارات وتأكد من النجاح
6. أرسل Pull Request مع وصف واضح
7. انتظر مراجعة الزميل

نصيحة يزيد

اختصارات لوحة المفاتيح

BrightAI Kernel يدعم مجموعة اختصارات لوحة مفاتيح لتسريع التنقل داخل /kernel/*. كل الاختصارات تتطلب modifier key (Cmd على macOS، Ctrl على Windows/Linux) — ما في اختصارات single-key. السبب: على لوحة المفاتيح العربية، الحرف س يطلق نفس الـ key code للحرف اللاتيني s؛ لو الـ shortcuts كانت على single keys، أي كتابة في حقل عربي تنقل المستخدم لصفحة ثانية بالخطأ (WCAG SC 2.1.4).

<table class="docs-table">
  <thead>
    <tr>
      <th>الاختصار</th>
      <th>الإجراء</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td data-label="الاختصار"><kbd>Cmd/Ctrl</kbd> + <kbd>C</kbd></td>
      <td data-label="الإجراء">الانتقال إلى <a href="/kernel/chat/">/kernel/chat/</a></td>
    </tr>
    <tr>
      <td data-label="الاختصار"><kbd>Cmd/Ctrl</kbd> + <kbd>A</kbd></td>
      <td data-label="الإجراء">الانتقال إلى <a href="/kernel/approvals/">/kernel/approvals/</a></td>
    </tr>
    <tr>
      <td data-label="الاختصار"><kbd>Cmd/Ctrl</kbd> + <kbd>S</kbd></td>
      <td data-label="الإجراء">الانتقال إلى <a href="/kernel/stats/">/kernel/stats/</a></td>
    </tr>
    <tr>
      <td data-label="الاختصار"><kbd>Cmd/Ctrl</kbd> + <kbd>T</kbd></td>
      <td data-label="الإجراء">الانتقال إلى <a href="/kernel/audit/">/kernel/audit/</a></td>
    </tr>
    <tr>
      <td data-label="الاختصار"><kbd>Cmd/Ctrl</kbd> + <kbd>R</kbd></td>
      <td data-label="الإجراء">إعادة تحميل الصفحة (يتطابق مع سلوك المتصفح الافتراضي)</td>
    </tr>
  </tbody>
</table>

<p><strong>قواعد السلوك:</strong></p>
<ul>
  <li>الاختصارات تتعطّل تلقائياً لو الـ focus داخل <code>&lt;input&gt;</code>، <code>&lt;textarea&gt;</code>، <code>&lt;select&gt;</code>، أو عنصر <code>contenteditable</code> — عشان ما تكسر الكتابة.</li>
  <li>الاختصارات معرّفة في <code>src/layouts/KernelLayout.astro</code> داخل <code>&lt;script is:inline&gt;</code> block (دالة <code>handleShortcuts</code>، السطر 500 تقريباً). ما تنطلق إلا مع modifier — راجع <code>if (!e.ctrlKey &amp;&amp; !e.metaKey) return;</code> قبل أي تعديل.</li>
  <li>لو احتجت تضيف اختصار جديد (مثلاً <kbd>Cmd/Ctrl</kbd> + <kbd>K</kbd> للأوامر)، ضع نفس الـ modifier guard + input-focus guard داخل نفس الـ block. لا تضيف اختصارات single-key في أي مكان آخر في <code>/kernel/*</code>.</li>
  <li>اختصارات المتصفح العامة (<kbd>Cmd/Ctrl</kbd> + <kbd>R</kbd> reload، <kbd>Cmd/Ctrl</kbd> + <kbd>L</kbd> location bar) تبقى كما هي — ما يتداخل معها شي.</li>
</ul>

<p><strong>اختبار سريع:</strong> افتح <a href="/kernel/">/kernel/</a>، اضغط على أي button لتركيز الـ focus عليه، ثم اضغط <kbd>C</kbd> بدون modifier — ما يصير شي. أضف <kbd>Cmd</kbd> (macOS) أو <kbd>Ctrl</kbd> (Windows/Linux) مع <kbd>C</kbd> — الصفحة تنتقل إلى <a href="/kernel/chat/">/kernel/chat/</a>.</p>