الأدوات#

كل أداة تأخذ project_dir، وهو مسار مطلق لمشروع tgcloud (create_project يأخذ parent_dir وname بدلًا من ذلك).

create وinit وlogin وadd وupgrade

status وdiff وpush وdeploy وpull وfetch وreset

تشغيل handler أو endpoint، وmigrate

الحالة والمزامنة، بما فيها البوت الصامت

دورة الحياة #

الأداة	أمر CLI	الوصف
`create_project`	`npm create @tgcloud/bot`	إنشاء مشروع (`parent_dir` و`name`)
`init_project`	`tgcloud init`	إنشاء الهيكل في مجلد موجود، بما فيه Mini App إن تعرّف عليه
`login_bot`	`tgcloud login`	ربط البوت برمز CLI access‏ (`app<id>:<secret>`) عبر stdin، ويُخفى في المخرجات
`add_module`	`tgcloud add`	وحدة جديدة: `handlers/<type>` أو `endpoints/<name>` أو `lib/<path>`
`upgrade`	`tgcloud upgrade`	نقل تخطيط ما قبل 0.2.0 إلى `tgcloud/`. الافتراضي `dry_run: true`؛ التطبيق يتطلب `confirm: true`

الأداة	أمر CLI	الوصف
`status`	`tgcloud status`	التغييرات المحلية مقابل اللقطة (دون شبكة)، بما فيها الملفات الثابتة وانحراف webhook
`diff`	`tgcloud diff`	فرق سطرًا بسطر (دون شبكة)
`push`	`tgcloud push`	نشر ذرّي. لا يبني الواجهة ولا يرحّل القاعدة. `force: true` يتطلب `confirm: true`
`deploy`	`npm run build` + `tgcloud push`	يبني إن وُجد سكربت build ثم push. `skip_build: true` ينشر فقط
`pull`	`tgcloud pull`	السحابة ← اللقطة وملفات العمل. لا يكتب مجلد بناء Mini App
`fetch`	`tgcloud fetch`	السحابة ← اللقطة فقط
`reset`	`tgcloud reset`	إلغاء تعديلات الوحدات المحلية؛ يتطلب `confirm: true`

الأداة	أمر CLI	الوصف
`run_handler`	`tgcloud run`	تشغيل handler أو endpoint من غير نشر. `args` و`ctx` بصيغة JSON5. `args` هو الوسيط الأول (الحمولة: `Message` للـ handler، والمدخل للـ endpoint)؛ و`ctx` هو الثاني (`ctx.update` هو الـ Update الخام للـ handler، ويشمل `update_id`؛ و`initData` للـ endpoint)
`migrate`	`tgcloud migrate`	`dry_run: true` افتراضيًا للمعاينة. التطبيق يحتاج `dry_run: false` و`confirm: true`. `apply: "safe"` هو `--safe`، و`apply: "yes"` (الافتراضي عند التطبيق) هو `--yes`. `local: true` هو `--local`

الأداة	أمر CLI	الوصف
`webhook_status`	`tgcloud webhook`	العنوان وallowed_updates والطابور وآخر خطأ، وهل هو متزامن
`webhook_sync`	`tgcloud webhook sync`	إعادة التوجيه. `drop_pending: true` يتطلب `confirm: true`

إضافة handler أو حذفه قد تُخرج webhook عن التزامن. push لا يضمن التحديث. استدعِ webhook_sync بعد هذا النوع من النشر.

البوت صامت: webhook_status ← status / diff ← push ← webhook_sync
سجلات النشر: لا يوجد أمر لتنزيلها؛ اقرأ آخر خطأ تسليم في webhook_status ثم أعِد الإنتاج عبر run_handler (مخرجاته console.* محلية وليست للبوت المنشور)
تعارض المراجعة عند push: fetch ← diff ← push (أو force مع confirm)
تغيير المخطط: عدّل schema.js ← push ← migrate (dry-run) ← migrate مع confirm. إن لم يوجد حذف فاستخدم apply: "safe"
واجهة Mini App: deploy وليس push وحده