مدير الحزم

مدير حزم كنوز هو أداة قوية لإدارة مشاريعك والمكتبات التي تعتمد عليها. مشابه لـ cargo في Rust، مدير الحزم يسهل:

إنشاء مشاريع جديدة بهيكل قياسي
بناء وتشغيل المشاريع
تثبيت وإدارة المكتبات من سجل الحزم
نشر حزمك الخاصة لمشاركتها مع المجتمع
إدارة رموز API للنشر الآمن

جميع الحزم مستضافة على سجل كنوز الرسمي على packages.knoz.dev.

ملف المشروع (knoz.toml)

كل مشروع كنوز يحتوي على ملف knoz.toml يحدد معلومات المشروع واعتمادياته.

هيكل الملف الأساسي

[حزمة]
اسم = "مشروعي"
نسخة = "0.1.0"
وصف = "وصف المشروع"
رخصة = "MIT"

[اعتماديات]
# الاعتماديات هنا

الحقول المتاحة

قسم [حزمة]

الحقل	الوصف	مطلوب	مثال
اسم	اسم الحزمة	✓	`"حاسبة"`
نسخة	رقم النسخة	✓	`"0.1.0"`
وصف	وصف الحزمة	✖	`"مكتبة رياضية"`
مؤلفين	قائمة المؤلفين	✖	`["أحمد <[email protected]>"]`
رخصة	نوع الرخصة	✖	`"MIT"`
كلمات_مفتاحية	كلمات للبحث	✖	`["رياضيات", "حساب"]`
مستودع	رابط المستودع	✖	`"https://github.com/user/repo"`
موقع	رابط الموقع	✖	`"https://example.com"`
توثيق	رابط التوثيق	✖	`"https://docs.example.com"`

مثال كامل

[حزمة]
اسم = "رياضيات"
نسخة = "0.2.0"
مؤلفين = ["فريق كنوز <[email protected]>"]
وصف = "مكتبة رياضية شاملة للغة كنوز"
رخصة = "MIT"
كلمات_مفتاحية = ["رياضيات", "حساب", "أعداد"]
مستودع = "https://github.com/knoz-dev/رياضيات"
موقع = "https://knoz.dev/packages/رياضيات"

[اعتماديات]
نصوص = "^1.0.0"
شبكة = { نسخة = "0.3.2", مميزات = ["https"] }

[اعتماديات_تطوير]
اختبار = "1.0"

الأوامر الأساسية

إنشاء مشروع جديد

# إنشاء مشروع جديد
knoz جديد مشروعي

هذا ينشئ مجلد مشروع جديد مع الهيكل التالي:

مشروعي/
├── knoz.toml
├── .gitignore
├── اقرأني.md
└── src/
    └── رئيسي.كنز

محتوى الملف الرئيسي src/رئيسي.كنز:

// مشروعي - مشروع جديد بلغة كنوز
// تم إنشاؤه بواسطة مدير الحزم

دالة رئيسية() -> صحيح {
    طباعة("مرحباً من مشروعي!");
    أرجع 0;
}

بناء المشروع

# بناء المشروع (debug)
knoz بناء

# بناء للإنتاج (release)
knoz بناء --release

الملفات الناتجة تُحفظ في مجلد بناء/:

مشروعي/
├── بناء/
│   ├── مشروعي-debug      # نسخة التطوير
│   └── مشروعي            # نسخة الإنتاج (مع --release)

تشغيل المشروع

# بناء وتشغيل المشروع
knoz شغل

# تشغيل مع وسائط
knoz شغل -- arg1 arg2

تنظيف ملفات البناء

# حذف مجلد البناء
knoz نظف

إدارة الاعتماديات

إضافة اعتمادية

# إضافة حزمة للاعتماديات
knoz أضف رياضيات

# إضافة بنسخة محددة
knoz أضف رياضيات 0.2.0

# إضافة اعتمادية تطوير
knoz أضف --dev أدوات_اختبار

يُضاف إلى ملف knoz.toml تلقائياً:

[اعتماديات]
رياضيات = "^0.2.0"

[اعتماديات_تطوير]
أدوات_اختبار = "^1.0.0"

حذف اعتمادية

# حذف حزمة من المشروع
knoz حذف رياضيات

تثبيت جميع الاعتماديات

# تثبيت جميع الحزم المذكورة في knoz.toml
knoz تثبيت

أنواع الاعتماديات

1. اعتماديات من السجل

[اعتماديات]
رياضيات = "0.2.0"      # نسخة محددة بالضبط
نصوص = "^1.0.0"        # أي نسخة متوافقة (1.0.0 <= x < 2.0.0)
شبكة = "~0.3.2"        # نفس الإصدار الثانوي (0.3.2 <= x < 0.4.0)
أدوات = "*"            # أي نسخة

رموز النسخ:

^ (caret): تحديثات متوافقة - تسمح بتحديثات لا تغير الرقم الأول
~ (tilde): تحديثات رقعية - تسمح فقط بتحديثات الرقم الثالث
بدون رمز: يُعامل مثل ^ (الأحدث المتوافق)
*: أي نسخة

2. اعتماديات محلية (من مسار)

[اعتماديات]
مكتبتي = { نسخة = "*", مسار = "../مكتبتي" }

3. اعتماديات من Git

[اعتماديات]
مكتبة = { جيت = "https://github.com/user/repo", فرع = "main" }

4. اعتماديات اختيارية

[اعتماديات]
شبكة = { نسخة = "^1.0", اختياري = صحيح }

5. اعتماديات مع ميزات

[اعتماديات]
شبكة = { نسخة = "^1.0", ميزات = ["https", "json"] }

6. اعتماديات تطوير

[اعتماديات_تطوير]
أدوات_اختبار = "^1.0.0"

البحث عن الحزم

# البحث في سجل الحزم
knoz بحث رياضيات

مثال على النتائج:

🔍 جاري البحث عن: رياضيات...

📦 النتائج (2):
────────────────────────────────────────────────────────────
  📦 رياضيات
     مكتبة رياضية شاملة للغة كنوز
     📥 1234 تحميل

  📦 رياضيات_متقدمة
     دوال رياضية متقدمة ومعقدة
     📥 456 تحميل

عرض معلومات حزمة

# عرض معلومات حزمة
knoz معلومات رياضيات

مثال على النتائج:

📦 رياضيات
════════════════════════════════════════
📝 مكتبة رياضية شاملة للغة كنوز
📥 1234 تحميل
📅 تاريخ الإنشاء: 2024-01-15
🔄 آخر تحديث: 2024-12-20

📋 الإصدارات:
  • 0.3.0
  • 0.2.0
  • 0.1.0

نشر الحزم

التحضير للنشر

تأكد من وجود الملفات المطلوبة:

مكتبتي/
├── knoz.toml
├── اقرأني.md
└── src/
    └── رئيسي.كنز

وأن knoz.toml يحتوي على المعلومات الكاملة:

[حزمة]
اسم = "مكتبتي"
نسخة = "1.0.0"
وصف = "وصف واضح للحزمة"
رخصة = "MIT"
مؤلفين = ["اسمك <[email protected]>"]

تسجيل الدخول بالتوكن

# تسجيل الدخول باستخدام توكن API
knoz دخول --token arb_xxxxx

نشر الحزمة

# نشر الحزمة
knoz نشر

خطوات النشر:

📦 جاري تجهيز الحزمة للنشر...
   الاسم: مكتبتي
   النسخة: 1.0.0

🚀 جاري النشر إلى packages.knoz.dev...

✅ تم نشر مكتبتي بنجاح!
   النسخة: 1.0.0
   الرابط: https://packages.knoz.dev/packages/مكتبتي

عرض حزمي

# عرض جميع الحزم التي نشرتها
knoz حزمي

إدارة الحساب

عرض معلومات الحساب

# عرض من أنا
knoz من_أنا

مثال:

👤 مسجل الدخول باسم: اسمك
🔑 التوكن: موجود

تسجيل الخروج

# تسجيل الخروج
knoz خروج

إدارة رموز API

رموز API تمكنك من النشر بشكل آمن في CI/CD:

إنشاء رمز جديد

# إنشاء توكن جديد
knoz توكن جديد "رمز-النشر"

# إنشاء توكن مع تاريخ انتهاء
knoz توكن جديد "رمز-ci" --expires-days 365

عند الإنشاء:

🔐 جاري إنشاء توكن جديد...

✅ تم إنشاء التوكن بنجاح!

🔑 التوكن:
   arb_xxxxxxxxxxxxxxxxxxxxx

⚠️ احفظ هذا التوكن في مكان آمن!
   لن يتم عرضه مرة أخرى.

عرض قائمة الرموز

# عرض جميع التوكنات
knoz توكنات

مثال:

📋 التوكنات (2):
────────────────────────────────────────────────────────────
  🔑 رمز-النشر (ID: 1)
     تاريخ الإنشاء: 2024-01-15
     آخر استخدام: 2024-12-20

  🔑 رمز-ci (ID: 2)
     تاريخ الإنشاء: 2024-06-01

حذف رمز

# حذف توكن بالـ ID
knoz توكن حذف 1

استخدام الحزم المثبتة

استيراد حزمة

// استيراد كامل
استخدم رياضيات؛

// استيراد دالة محددة
استخدم رياضيات::جذر؛

// استيراد متعدد
استخدم رياضيات::{جذر, قوة, مطلق}؛

// استيراد مع اسم مستعار
استخدم رياضيات كـ ر؛

مثال استخدام

// استيراد المكتبة
استخدم رياضيات::{جذر, قوة}؛

دالة رئيسية() -> صحيح {
    دع نتيجة = جذر(16.0)؛
    طباعة("الجذر التربيعي لـ 16 = {}", نتيجة)؛

    دع قوة_نتيجة = قوة(2.0, 8.0)؛
    طباعة("2 أس 8 = {}", قوة_نتيجة)؛

    أرجع 0;
}

الأوامر الكاملة

أوامر المشروع

الأمر	الوصف
`knoz جديد <اسم>`	إنشاء مشروع جديد
`knoz بناء`	بناء المشروع (debug)
`knoz بناء --release`	بناء للإنتاج
`knoz شغل`	بناء وتشغيل المشروع
`knoz شغل -- <args>`	تشغيل مع وسائط
`knoz نظف`	تنظيف ملفات البناء

أوامر الاعتماديات

الأمر	الوصف
`knoz تثبيت`	تثبيت جميع الاعتماديات
`knoz أضف <حزمة>`	إضافة اعتمادية
`knoz أضف <حزمة> <نسخة>`	إضافة بنسخة محددة
`knoz أضف --dev <حزمة>`	إضافة اعتمادية تطوير
`knoz حذف <حزمة>`	حذف اعتمادية
`knoz بحث <استعلام>`	البحث عن حزم
`knoz معلومات <حزمة>`	عرض معلومات حزمة

أوامر النشر

الأمر	الوصف
`knoz نشر`	نشر الحزمة
`knoz حزمي`	عرض حزمي المنشورة

أوامر الحساب

الأمر	الوصف
`knoz دخول`	تسجيل الدخول التفاعلي
`knoz دخول --token <token>`	تسجيل الدخول بالتوكن
`knoz خروج`	تسجيل الخروج
`knoz من_أنا`	عرض معلومات الحساب

أوامر الرموز

الأمر	الوصف
`knoz توكنات`	عرض قائمة الرموز
`knoz توكن جديد <اسم>`	إنشاء رمز جديد
`knoz توكن جديد <اسم> --expires-days <أيام>`	إنشاء رمز مع انتهاء صلاحية
`knoz توكن حذف <id>`	حذف رمز

أمثلة عملية

مثال 1: إنشاء وتشغيل مشروع

# 1. إنشاء مشروع جديد
knoz جديد تطبيقي
cd تطبيقي

# 2. بناء وتشغيل
knoz شغل

# النتيجة:
# 🚀 جاري تشغيل تطبيقي...
# ──────────────────────────────────────────────────
# مرحباً من تطبيقي!

مثال 2: إضافة واستخدام حزمة

# 1. إضافة اعتمادية
knoz أضف رياضيات

# 2. تعديل src/رئيسي.كنز

استخدم رياضيات::جذر؛

دالة رئيسية() -> صحيح {
    دع س = جذر(25.0)؛
    طباعة("جذر 25 = {}", س)؛
    أرجع 0;
}

# 3. تشغيل
knoz شغل

مثال 3: نشر حزمة

# 1. تسجيل الدخول
knoz دخول

# 2. التأكد من knoz.toml
# [حزمة]
# اسم = "مكتبتي"
# نسخة = "1.0.0"
# وصف = "..."

# 3. نشر الحزمة
knoz نشر

مثال 4: النشر التلقائي (CI/CD)

name: نشر الحزمة

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: تثبيت كنز
        run: |
          curl -fsSL https://knoz.dev/install.sh | bash

      - name: نشر الحزمة
        env:
          KNOZ_TOKEN: ${{ secrets.KNOZ_TOKEN }}
        run: knoz دخول --token $KNOZ_TOKEN && knoz نشر

حل المشاكل الشائعة

لم يتم العثور على ملف knoz.toml

❌ لم يتم العثور على ملف knoz.toml
   تأكد من أنك في مجلد مشروع كنوز

الحل:

تأكد من أنك في مجلد المشروع الصحيح
أنشئ مشروع جديد: knoz جديد اسم

الملف الرئيسي غير موجود

❌ الملف الرئيسي غير موجود: src/رئيسي.كنز

الحل:

أنشئ الملف src/رئيسي.كنز
أو تأكد من صحة المسار

لم يتم تسجيل الدخول

❌ لم يتم تسجيل الدخول. استخدم: knoz دخول

الحل:

knoz دخول

التوكن غير صالح

❌ خطأ في المصادقة: التوكن غير صالح

الحل:

تحقق من التوكن
أنشئ توكن جديد: knoz توكن جديد "اسم"

خطأ في الشبكة

❌ خطأ في الشبكة: ...

الحل:

تحقق من الاتصال بالإنترنت
تحقق من توفر packages.knoz.dev

أفضل الممارسات

✓ افعل

استخدم أرقام نسخ واضحة (Semantic Versioning)
اكتب وصفاً واضحاً للحزمة
أضف ملف اقرأني.md يشرح الاستخدام
حدد الرخصة في knoz.toml
استخدم رموز API بدلاً من كلمات المرور في CI/CD
حدد تاريخ انتهاء لرموز API

✖ لا تفعل

لا تنشر حزماً بدون وصف
لا تنسَ تحديث رقم النسخة عند التعديل
لا تشارك رموز API الخاصة بك
لا تضمّن ملفات حساسة في الحزمة

🔐 أمان رموز API

احفظ الرموز في متغيرات البيئة
لا تلتزم برموز API في Git
استخدم رموز منفصلة لكل بيئة
احذف الرموز غير المستخدمة

الملخص

knoz جديد لإنشاء مشروع جديد
knoz بناء لبناء المشروع
knoz شغل لتشغيل المشروع
knoz أضف لإضافة اعتماديات
knoz تثبيت لتثبيت الاعتماديات
knoz دخول لتسجيل الدخول
knoz نشر لنشر الحزمة
knoz توكن جديد لإنشاء رمز API
جميع المعلومات في ملف knoz.toml
سجل الحزم متاح على https://packages.knoz.dev