Vitrin CLI بالتفصيل: من تسجيل الدخول إلى المعاينة والرفع وحل الأخطاء

ماذا تقدم لك الأداة؟

Vitrin CLI أداة سطر أوامر من زد لمطوري الثيمات، تتيح لك تطوير الثيمات والتحقق منها ونشرها من بيئتك المحلية مباشرة، وهي منشورة على npm باسم @zidsa/vitrin-cli.

npm install -g @zidsa/vitrin-cli

vitrin   # Launch the interactive TUI (recommended)

الواجهة التفاعلية (TUI) هي الطريقة التي يوصي بها التوثيق: لوحة تعرض الأوامر وحالة البناء لحظيًا ومعلومات الثيم والـ Authentication، وتتيح إنشاء الثيمات وتصفحها واختيارها، ونشر المعاينة بضغطة واحدة، وتكتشف الثيم في المجلد الحالي تلقائيًا. وكل ذلك متاح أيضًا كأوامر مباشرة، وهي ما يشرحه هذا الدليل.

• VITRIN_API_URL: عنوان الـ API (الافتراضي https://api.zid.sa).
• VITRIN_PARTNER_URL: عنوان لوحة الشركاء (الافتراضي https://partner.zid.sa).
• LOG_LEVEL: مستوى الـ Logs (debug أو info أو error).

تسجيل الدخول: vitrin login

يفتح الأمر vitrin login لوحة الشركاء في متصفحك لإتمام تدفق OAuth، ثم يحفظ بيانات الاعتماد محليًا. أثناء ذلك تنتظر الأداة الاستجابة على http://localhost:4444/auth/callback:

$ vitrin login
Opening Zid Partner Dashboard in your default browser...
Listening for authentication callback on http://localhost:4444/auth/callback

✅ Authentication successful!
Token saved to ~/.vitrin/config.json

• يُحفظ الرمز في ~/.vitrin/config.json. ولتسجيل الخروج شغّل vitrin logout (في الإصدار 1.3.0)، أو احذف الملف كما يذكر التوثيق: rm ~/.vitrin/config.json.
• لتتأكد أنك ما زلت مسجّلًا، شغّل vitrin list themes؛ فإذا ظهرت رسالة "Authentication required" فأعد تشغيل vitrin login.

إنشاء ثيم: vitrin new

الصيغة vitrin new <theme-name> [options] تنشئ ثيمًا جديدًا. في الإصدار 1.3.0 على npm ينسخ الأمر افتراضيًا قالب ثيم Growth الرسمي من zidsa/growth-theme، والخيار -e أو --from-existing <path> يسجّل مجلدًا موجودًا لديك كثيم Vitrin بدل النسخ، والخيار --no-git يتخطى تهيئة Git. أما الخيار -t أو --template (بقوالب basic وminimal وadvanced) الذي تذكره صفحة الأوامر في التوثيق فغير موجود في الإصدار 1.3.0. وبعد الإنشاء تقترح الأداة cd إلى المجلد ثم vitrin push. هذه البنية التي تتوقعها الأداة حسب صفحة المقدمة في التوثيق:

my-theme/
├── assets/
│   ├── styles.css
│   ├── scripts.js
│   └── images/
├── templates/
│   ├── home.jinja
│   ├── product.jinja
│   └── cart.jinja
├── layout.jinja
├── footer.jinja
├── header.jinja
├── package.json
└── theme.json

صفحة Architecture في التوثيق تضيف إلى ذلك sections/ وcomponents/ وملف الترجمة locale/ar/LC_MESSAGES/messages.po، وملفات layout.schema.json وheader.schema.json وfooter.schema.json، فاعتبر شجرة الأداة الحد الأدنى.

المعاينة على المتجر التجريبي

اعرض متاجرك التجريبية لتعرف رقم المتجر، ثم عاين الثيم عليه. مع --build تبني الأداة الثيم، وتنشئه، وتنشئ إصدارًا، وترفع الحزمة، وتثبّتها على المتجر، ثم تطبع ثلاثة IDs:

vitrin list stores
vitrin preview 123 --build

# From the preview output:
# Theme ID: 45678
# Version: 90123
# Installation: 11111

تنتهي المعاينة بتثبيت الثيم دون تفعيله، وتقترح عليك أمر التفعيل. ولتثبيت إصدار محدد يدويًا استخدم vitrin install بـ IDs المتجر والثيم والإصدار، ثم فعّله بـ ID التثبيت:

vitrin install <store-id> <theme-id> <version-id>
vitrin activate <store-id> <installation-id>

# Example
vitrin activate 123 11111

البناء والرفع: vitrin build وvitrin push

الأمر vitrin build [theme-path] يتحقق من البنية ثم يحزم الثيم في ملف .zip قابل للتوزيع. مثال التوثيق يعرض dist/theme.zip، أما في الإصدار 1.3.0 فيُسمّى الملف باسم مجلد الثيم مع طابع زمني (مثل my-theme-1714492800000.zip)، والخيار -o أو --output <path> يحدد مجلد الإخراج. أما vitrin push فيبني الثيم ويرفعه إلى Servers زد، فينشئه أو يحدّثه:

vitrin build
vitrin build --validate

vitrin push --store 123 --activate

• -s أو --store <id>: ID المتجر التجريبي الذي يُثبَّت عليه الثيم (صفحة التوثيق تذكر البريد، والإصدار 1.3.0 يأخذ الـ ID).
• -a أو --activate: تفعيل الثيم بعد تثبيته.
• -v أو --version <version>: رقم الإصدار (الافتراضي من theme.json).
• -c أو --changelog <text>: وصف تغييرات الإصدار.
• -n أو --new-version (الإصدار 1.3.0): ينشئ إصدارًا جديدًا من الثيم، إذ يحدّث push افتراضيًا آخر إصدار في مكانه.

من الممارسات الجيدة أن تمرر --changelog في كل رفع، و--version صراحةً كلما أنشأت إصدارًا جديدًا، حتى يسهل تتبع كل إصدار. وتذكّر أن push لا يرسل الثيم لمراجعة سوق الثيمات؛ الإرسال للمراجعة خطوة منفصلة: من My Themes → Themes Management في لوحة الشركاء عبر Submit to Publish، أو في الإصدار 1.3.0 عبر vitrin status --target pending_review. وتشرح الخطوات مقالتنا عن قائمة التحقق قبل النشر.

الأخطاء الشائعة وحلولها

• Authentication required: الرمز غير موجود أو منتهٍ. شغّل vitrin login.
• فشل البناء: شغّل vitrin build --validate. الأسباب الشائعة: غياب المجلد assets/ أو templates/، أو ملف package.json مفقود أو غير صالح. أما ملفات .DS_Store فتُحذف تلقائيًا أثناء البناء.
• فشل المعاينة: رمز منتهٍ (شغّل vitrin login)، أو رقم متجر غير صحيح (تحقق عبر vitrin list stores)، أو تعارض في اسم الثيم، وهذا تحلّه الأداة بتوليد اسم فريد تلقائيًا.
• أخطاء متغيرات غير معرّفة في المعاينة: منذ ديسمبر 2025 تُعرض هذه الأخطاء في معاينة التطوير. أضف قيمًا بديلة وتعامل مع القيم الاختيارية واستخدم safeget.

لتفاصيل أكثر شغّل المعاينة بـ Logs مفصّلة:

# macOS
LOG_LEVEL=debug vitrin preview 123

# Windows
$env:LOG_LEVEL="debug"; vitrin preview 123