التحديث

يُحدّث EstaCoda عبر نفس القناة التي ثبّتته. يكتشف أمر التحديث طريقة التثبيت لديك، ثم يطبّق تحديثاً محمياً للمصدر أو يُخبرك بالأمر الخارجي الصحيح الذي عليك تشغيله. لا يقوم بالكتابة فوق أشجار عمل المساهمين بصمت، ولا يعدّل تثبيتات مدير الحزم، ولا يُعيد تشغيل الخدمات بأعمية.

سبب وجوده

النظام العميل الذي لا يستطيع تحديث نفسه بأمان يصبح عبئاً. يعامل EstaCoda التحديث كعملية موجهة بالحالة مع فحوصات ما قبل الإقلاع وإمكانية الاستعادة والوعي بطريقة التثبيت. الهدف ليس السرعة. الهدف هو الاسترداد المتوقع عندما يحدث خطأ ما.

أوامر التحديث

الأمر	السلوك	رمز الخروج
estacoda update --check	فحص فقط. لا يُعدّل الملفات أبداً.	0 إذا كان التحديث متاحاً، 2 إذا كان محدثاً، 1 عند خطأ
estacoda update	السلوك الافتراضي يعتمد على طريقة التثبيت. انظر أدناه.	0 عند النجاح/التوجيه، 1 عند خطأ، 3 عند وجود تغييرات غير مُلتزمة
estacoda update --backup	مُقبول للتأكيد الصريح. السلوك الافتراضي يُنشئ نسخة احتياطية لحالة المستخدم قبل التعديل على أي حال.	نفس الافتراضي
estacoda update --no-backup	تخطي نسخة احتياطية لحالة المستخدم. غير مُستحسن.	نفس الافتراضي
estacoda update --no-restart-gateway	يطبّق التحديث دون إعادة تشغيل خدمة بوابة مُدارة مُثبّتة.	نفس الافتراضي
estacoda update --gateway	وضع صريح للمشغّل لأغراض التوافق. بعد تحديث managed-source ناجح غيّر الكود، يُعيد تشغيل خدمة بوابة مُدارة إذا اكتشفها، أو يطبع إرشادات إعادة التشغيل اليدوية.	نفس الافتراضي

يُقبل --dry-run كمرادف لـ --check في تثبيتات غير المُدارة. في تثبيتات managed-source، يؤدي estacoda update بدون اختيارات إلى تطبيق التحديث الفعلي.

سلوك إعادة تشغيل البوابة

عندما يطبّق estacoda update تحديث كود فعلياً على تثبيت managed-source، يُعيد EstaCoda تشغيل خدمة البوابة المُدارة المُثبّتة تلقائياً إذا اكتشف واحدة.

ينطبق هذا فقط على الخدمات المُدارة بواسطة EstaCoda. لا يقتل PIDs، ولا يوقف عمليات البوابة التي تعمل في الواجهة، ولا يُعيد تشغيل جلسات البوابة التي شُغّلت يدوياً.

لا تُحاوَل إعادة تشغيل البوابة عندما:

• يكون التثبيت محدّثاً بالفعل
• يُستخدم --check
• يُستخدم --dry-run
• يفشل التحديث أو يُرفض
• تكون طريقة التثبيت Homebrew أو npm أو pnpm أو Docker أو مصدر يدوي

إذا لم تكن هناك خدمة بوابة مُدارة مُثبّتة، يبقى وضع التحديث الافتراضي صامتاً.

استخدم --no-restart-gateway لتعطيل إعادة تشغيل الخدمة المُدارة تلقائياً:

estacoda update --no-restart-gateway

هذا مفيد عندما يريد المشغّل إعادة تشغيل البوابة لاحقاً أثناء نافذة صيانة.

استخدم --gateway للوضع الصريح للمشغّل لأغراض التوافق:

estacoda update --gateway

في هذا الوضع، يُعيد EstaCoda تشغيل خدمة البوابة المُدارة بعد تحديث managed-source ناجح غيّر الكود. إذا لم يكتشف خدمة مُدارة، يطبع إرشادات إعادة التشغيل اليدوية.

توجيه طريقة التثبيت

يكتشف EstaCoda طريقة التثبيت لديك أثناء التشغيل ويوجّه سلوك التحديث وفقاً لها.

الطريقة	سلوك estacoda update
managed-source	تحديث مصدر محمي: جلب origin، التحقق من سلامة fast-forward، فحص نظافة شجرة العمل، pull، تثبيت التبعيات، build، التحقق. الاستعادة إلى pre-pull SHA عند فشل build.
manual-source	فحص وتوجيه فقط. يطبع git fetch origin && git status. لا تعديل ذاتي.
homebrew	يطبع brew upgrade kemetresearch/tap/estacoda. لا تعديل ذاتي.
docker	يطبع docker pull ghcr.io/sifr01-labs/estacoda:latest. لا تعديل ذاتي.
npm-global	يطبع npm install -g estacoda@latest. لا تعديل ذاتي.
pnpm-global	يطبع pnpm add -g estacoda@latest. لا تعديل ذاتي.
unknown	يطبع توجيهات إعادة التثبيت. لا تعديل ذاتي.

يُحدد طريقة التثبيت عن طريق اكتشاف ملف .install-method.json، والاستدلال على المسارات، وفحوصات بيئة التشغيل الحاوية. يتطلب managed-source وجود ختم صالح يطابق origin المستودع الحالي والفرع والمجلد.

مسار تحديث managed-source

إذا ثبّتت عبر curl \| bash أو مُثبّت مُدار آخر، ينفّذ estacoda update التسلسل التالي:

1. التحقق من الختم — يجب أن يُعلن .install-method.json عن managed-source مع تطابق installDir وsourceUrl والفرع.
2. التحقق من سلامة المستودع — يجب أن يكون المجلد الحالي مستودع git يطابق origin والفرع في الختم.
3. فحص شجرة العمل — يرفض إذا كانت هناك تغييرات غير مُلتزمة. رمز الخروج 3.
4. التقاط pre-pull SHA — يُحفظ للاستعادة المحتملة.
5. نسخ حالة المستخدم احتياطياً — ينسخ المسارات المحمية إلى ~/.estacoda/.backups/<label>/ ما لم يُمرر --no-backup.
6. جلب origin — فحص refs البعيدة دون تعديل.
7. حساب المسافة — عدد commits خلف origin/<branch>.
8. fast-forward pull — git pull --ff-only origin <branch>.
9. تثبيت التبعيات — pnpm install --frozen-lockfile.
10. build — pnpm run build.
11. التحقق — يجب أن ينجح node dist/index.js --version و--help.
12. كتابة ذاكرة التخزين المؤقت — يُعلّم ~/.estacoda/update-cache.json كمحتوّث.

إذا فشل أي خطوة بعد pull، يتم الاستعادة التلقائية إلى pre-pull SHA.

فحوصات التحديث عند بدء التشغيل

يفحص EstaCoda وجود تحديثات في الخلفية أثناء الجلسات التفاعلية.

• متى: بعد بدء تشغيل الجلسة، فقط عندما لا توجد معاملات سطر أوامر ويتوفر TTY.
• كيف: prefetch غير حاجز لا يُبطئ الموجه الأول.
• ذاكرة التخزين المؤقت: ~/.estacoda/update-cache.json مع TTL مدته 6 ساعات.
• الفشل: أخطاء الشبكة تفشل بصمت. لا تُعطل جلستك.
• التلميح: إذا كانت الحالة المخزنة update-available، يظهر تلميح أثناء جاهزية بدء التشغيل. يتضمن التلميح أمر التحديث الموصى به لطريقة تثبيتك.

بالنسبة لتثبيتات المصدر (المُدارة واليدوية)، يستخدم prefetch فحوصات git البعيدة دون تعديل refs المحلية. بالنسبة لتثبيتات الإصدار، يستعلم عن GitHub releases API.

حدود السلامة

• لا hard reset خارج الأدلة المُدارة. يُسمح بالمصالحة فقط في أدلة managed-source المُختومة.
• رفض شجرة العمل المتسخة. ترفض تحديثات managed-source المتابعة إذا كانت شجرة العمل تحتوي على تغييرات غير مُلتزمة. رمز الخروج 3.
• حفظ حالة المستخدم. لا يتم تدمير ~/.estacoda/profiles/ وmemory/ وsessions.sqlite وtrust.json والمسارات المحمية الأخرى أبداً بواسطة التحديث.
• الاستعادة عند الفشل. يؤدي فشل build أو التحقق بعد pull إلى الاستعادة التلقائية إلى pre-pull SHA.
• إعادة تشغيل البوابة تبقى محصورة بالخدمة. يُعيد EstaCoda تشغيل خدمات البوابة المُدارة فقط التي تُكتشف عبر abstraction service-manager بعد تحديثات managed-source ذاتية ناجحة غيّرت الكود. لا يقتل PIDs، ولا يوقف عمليات البوابة التي تعمل في الواجهة، ولا يُعيد تشغيل جلسات البوابة التي شُغّلت يدوياً. تبقى عمليات البوابة اليدوية مسؤولية المشغّل.

مسارات الحالة

المسار	الغرض
~/.estacoda/update-cache.json	ذاكرة تخزين مؤقت لفحص التحديث. عامة، وليست خاصة بملف تعريف. TTL 6 ساعات.
~/.estacoda/logs/update.log	سجل عملية التحديث. يُكتب أثناء وضع --gateway وتحديثات managed-source. يتم إخفاء بيانات الاعتماد.
~/.estacoda/.backups/<label>/	نسخة احتياطية لحالة المستخدم تُنشأ قبل تعديل managed-source. تحتوي على نسخ من المسارات المحمية، وليس المستودع المصدري نفسه.

رموز الخروج

الرمز	المعنى
0	نجاح، أو تم طباعة رسالة توجيه، أو عُرضت معلومات عن توفر التحديث.
1	خطأ: فشل شبكة، فشل build، رفض سلامة، فشل نسخ احتياطي، أو عدم تطابق الختم.
2	محدّث. لا حاجة لإجراء.
3	شجرة عمل متسخة. ارتكِم أو stash أو تجاهل التغييرات قبل إعادة المحاولة.

مسار التحديث عبر artifact فقط

توفر متغير البيئة ESTACODA_UPDATE_ARTIFACT مساراً مهملاً للتحديث عبر artifact فقط. هو قابل للوصول ولكنه ليس آلية التحديث المُوصى بها في v0.1.0. استخدم estacoda update لتثبيتات managed-source أو أمر مدير الحزم المناسب لطريقة تثبيتك.

استكشاف الأخطاء وإصلاحها

رفض التحديث برمز خروج 3 شجرة عمل managed-source تحتوي على تغييرات غير مُلتزمة. ارتكِم أو stash أو تجاهلها، ثم أعد المحاولة.

"Install method stamp does not match" ختم .install-method.json لا يتفق مع origin أو الفرع أو جذر المستودع الحالي. يحدث هذا إذا نقلت المستودع أو غيّرت remotes بعد التثبيت. عامل المستودع كـ manual-source وحدّث باستخدام git pull مباشرة.

فشل build وظهور رسالة استعادة نجح pull ولكن فشل pnpm install أو pnpm run build. تمت استعادة المستودع إلى pre-pull SHA. افحص المخرجات، وأصلح أي مشاكل بيئة محلية (إصدار Node، توفر pnpm)، ثم أعد المحاولة.

عدم ظهور تلميح التحديث عند بدء التشغيل يعمل prefetch في الخلفية فقط في الجلسات التفاعلية بدون معاملات. إذا كنت تشغل دائماً بمعاملات أو في بيئة غير TTY، فلن يُطلق prefetch. شغّل estacoda update --check يدوياً.

عدم إعادة تشغيل خدمة البوابة بعد تحديث --gateway إعادة تشغيل البوابة تحاول فقط الخدمات المُدارة المُسجلة عبر estacoda gateway install-service، وفقط بعد تحديث managed-source ناجح غيّر الكود. إذا كنت تشغل البوابة يدوياً، فأعد تشغيلها بنفسك باستخدام estacoda gateway restart.