التشغيل والتنقيح

يقرأ Gitcito ملف .vscode/launch.json عندك — ملف الجذر وأي ملفات متداخلة، مجمَّعة بفواصل — ويشغّل الإعداد الذي تختاره في الطرفية المدمجة.

• متغيرات VS Code تُحَلّ (مثل ${workspaceFolder} وأخواته).
• تُنفَّذ preLaunchTask الخاصة بالإعداد أولًا.
• تُطلب قيم ${input:…} منك تفاعليًا قبل التشغيل (بنوعيها promptString وpickString). يعرض pickString خياراته كمنتقٍ حقيقي مع تحديد القيمة الافتراضية مسبقًا؛ ويُخفى إدخال promptString المعلَّم بـ password.
• تعمل مهام isBackground (المراقِبات وخوادم التطوير) منفصلةً، فلا تعطّل التشغيل أبدًا.
• تشغّل المجموعات المركّبة (compounds) كل عضو كجلسة متوازية مستقلة — في طرفية مقسّمة واحدة تحمل اسم المجموعة، بلوحة لكل عضو، تمامًا مثل جلسات التصحيح في VS Code. مع stopAll: true، يؤدي إيقاف عضو واحد إلى إيقافها كلها. المهام المشتركة بين عدة أعضاء تعمل مرة واحدة، في لوحة خاصة بها، قبل بدء الأعضاء — فيسأل موجّه رفع الإصدار مرة واحدة، لا مرة لكل عضو. تُغلق هذه اللوحة نفسها عند النجاح وتبقى مفتوحة عند الفشل.
• يُحترم serverReadyAction: عندما يطابق خرج الجلسة النمط المُهيّأ، يُفتح عنوان URL المُعلن في متصفحك (openExternally؛ كما يفتح debugWithChrome / debugWithEdge المتصفح أيضًا — لا يستطيع Gitcito إرفاق مصحّح).

يمنحك شريط أدوات عائم إيقافًا مؤقتًا واستئنافًا وإعادة تشغيل وإيقافًا، ويبدّل بين الجلسات العاملة.

فعّله من الإعدادات ← عام ← تمكين launch.json. عندها يظهر زر LAUNCH بجوار تبويبَي Git والملفات.

يظهر عضو المجموعة المركّبة بصيغة المجموعة › العضو، وإعادة تشغيله تعيد تشغيل ذلك العضو وحده. إذا غطّى الشريط شيئًا تحتاجه، اسحبه جانبًا من مقبضه — يُحفظ الموضع، والنقر المزدوج على المقبض يعيده إلى المنتصف.

ما لا يفعله Gitcito عمدًا: إنه يشغّل برامجك في طرفيات حقيقية، لكنه ليس مصحّحًا — لا نقاط توقف، ولا فحص متغيرات، ولا Debug Adapter Protocol. تعمل تكوينات attach عندما تحمل preLaunchTask (المهمة هي العمل)؛ أما attach الخالص فلا شيء لديه ليُشغَّل.

الإجراءات الساخنة — الطريق السريع بجوار «إعادة التشغيل»

معظم بيئات التشغيل التطويرية تعيد التحميل أصلًا بضغطة مفتاح واحدة: flutter run بالمفتاح r، وMetro بالمفتاح r، وnodemon بـ rs ⏎، وVitest يعيد تشغيل المجموعة بالمفتاح a. إعادة تشغيل تكوين الإطلاق للحصول على النتيجة نفسها هي الطريق البطيء — فهي تقتل العملية، وتعيد تنفيذ كل preLaunchTask، وترمي حالة التطبيق.

لذلك يقرأ Gitcito الأمر الذي يشغّله التكوين فعلًا — متتبعًا npm run dev حتى السكربتات في package.json — ويضع مفاتيح تلك البيئة في شريط التنقيح. الضغط على أحدها يكتب المفتاح في الدخل القياسي للجلسة، تمامًا كما لو كتبته أنت في الطرفية.

البيئات التي تعيد التحميل من تلقاء نفسها لا تحصل على أزرار — node --watch، ng serve، tsc --watch، cargo watch، next dev، webpack-dev-server. زر يرسل مفتاحًا لا يقرأه أحد أسوأ من غياب الزر، لأنه يبدو وكأنه نجح.

الحدود. الاكتشاف نصّي: يطابق اسم البرنامج في سطر الأوامر، لذا فالتكوين الذي يشغّل خادم التطوير عبر سكربت غلاف لا يستطيع Gitcito قراءته لن يحصل على شيء. ولا يوجد إشعار باستلام المفتاح — يومض الزر، والجواب الحقيقي هو خرج العملية نفسها. الجلسة الموقوفة مؤقتًا أو المنتهية لا تقبل أي دخل، فتصبح الأزرار معطّلة.

عندما يخطئ التخمين، قل ذلك في التكوين نفسه:

{
  "name": "API (watch)",
  "type": "node-terminal",
  "command": "./scripts/dev.sh",
  "gitcito": { "hotActions": [{ "label": "Reload", "send": "r", "icon": "reload" }] }
}

يُكتب send حرفيًا — أنهه بـ \n مع واجهة سطر أوامر تنتظر Enter. وicon اختياري: reload, restart, rerun, failed, snapshot, menu, debugger, browser, clear, paint, perf, platform, devtools, urls. مصفوفة hotActions الفارغة تُطفئ الأزرار لذلك التكوين.

هدف التشغيل — على أي جهاز يُشغَّل التكوين

التكوين الذي يبني تطبيقًا للهاتف لا بد أن يُقال له أين يعمل. وهذا الاختيار ليس حكرًا على Flutter — فـ React Native وExpo وCapacitor وxcodebuild كلها تأخذ هدفًا، وكل واحد يكتبه بطريقته. لذلك يسأل Gitcito مرة واحدة، بجوار تبويب LAUNCH، ثم يكتب الجواب بالصيغة التي تقرأها بيئة تشغيل ذلك التكوين. ولا يظهر المُنتقي إلا حين يكون في المستودع تكوين يقبل جهازًا فعلًا.

من أين تأتي القائمة — من أدوات الـ SDK الموجودة على الجهاز، تُسأل بالتوازي:

المحاكي نفسه قد تُبلّغ عنه ثلاث أدوات، لذا تُدمج المدخلات حسب المنصة والاسم؛ وعند التعادل يفوز Flutter لأن معرّفه هو ما ينتظره flutter run -d. أما الأدوات غير المثبَّتة فتُذكر بالاسم أسفل القائمة — القائمة القصيرة يجب أن تشرح نفسها.

ماذا يفعل الاختيار:

كل تكوين يُشغَّل يحصل أيضًا في بيئته على GITCITO_DEVICE_ID و GITCITO_DEVICE_NAME وGITCITO_DEVICE_PLATFORM، ويُضاف ANDROID_SERIAL حين يكون الهدف جهاز Android حقيقيًا. وهذا ما يجعل سكربت غلاف أو مهمة Gradle أو أمر adb مجرّدًا يصيب الهاتف نفسه دون أن يعيد Gitcito كتابة أي شيء.

تشغيل جهاز مطفأ. كل ما تحت غير مشغَّل يقلع عند اختياره: flutter emulators --launch، وxcrun simctl boot (مع نافذة Simulator)، أو emulator -avd منفصلًا — حتى لا يأخذ إغلاقُ Gitcito محاكيَ Android معه.

الحدود. التكوين الذي يسمّي جهازًا سلفًا — -d صريح، أو --simulator، أو deviceId الخاص بـ Dart-Code — يُترك كما هو: المُنتقي لا يتجاوز ما كتبه المؤلف أبدًا. والمعرّف الذي يحتاج إلى علامات اقتباس يرتد إلى المتغيرات البيئية بدل المخاطرة بسطر أوامر معطوب. والقائمة مُرشَّحة بحسب ما تستطيع تكويناتك بلوغه، فلن يعرض عليك مستودعٌ لـ Android وحده جهاز iPhone. والقائمة لقطة لحظية: وصّل هاتفًا ثم اضغط تحديث الأجهزة.

يُحفظ الاختيار لكل مستودع، ويُنسى حين يختفي ذلك الجهاز.

انظر أيضًا: الطرفية المدمجة

قيم الإدخال من JSON وYAML

يمكن للحقل عرض الإصدار الحالي أو تعبئة قيمة أولية من ملف المشروع. يقرأ Gitcito الملف عند كل تشغيل قبل عرض الحقول. لا تحتاج إلى إضافة VS Code.

أضف fileValues إلى حقل promptString أو pickString. تحدد كل قيمة مسار ملف نسبيًا إلى مجلد إعداد التشغيل وخاصية مفصولة بنقاط. استخدم ${fileValue:name} في description أو default. تترك قيمة default الفارغة الحقل اختياريًا.

{
  "id": "version",
  "type": "promptString",
  "description": "Current: ${fileValue:version} (${fileValue:build})",
  "default": "",
  "fileValues": {
    "version": { "file": "version.yaml", "key": "settings.base.MARKETING_VERSION" },
    "build": { "file": "version.yaml", "key": "settings.base.CURRENT_PROJECT_VERSION" }
  }
}

يدعم ملفات JSON وYAML وYML داخل المجلد حتى 1 MiB، والقيم النصية والرقمية والمنطقية. توقف الملفات المفقودة والبيانات غير الصالحة والخصائص المفقودة والمسارات الخارجية التشغيل مع خطأ. لا تُنفَّذ أوامر أو تعبيرات JavaScript. يعيد كل تشغيل جديد قراءة الملفات؛ يستخدم Restart الإجابات السابقة. لا يحل VS Code حقول Gitcito هذه افتراضيًا.