سطر الأوامر

يشغّل الأمر getman الطلبات المحفوظة من الطرفية، ويقارن عقود الواجهات البرمجية، ويدير حزم التغيير، ويبدأ خادم المحاكاة وخادم MCP. يستخدم المحرك نفسه الموجود في تطبيق سطح المكتب، لذلك تتطابق النتائج.

التثبيت والتحقق

ثبّت الأمر من Project settings → Command line & agents → Install command-line tool. يكتب هذا مشغّل getman في ~/.local/bin (على Windows، في %LOCALAPPDATA%\Getman\bin). إذا أخبرك Getman أن هذا المجلد ليس في PATH، فأضفه. يحتاج سطر الأوامر إلى Node.js 20 أو أحدث.

getman help
getman projects

تحتاج الأوامر التي تشغّل الطلبات إلى المحرك، وهو مدمج في التطبيق المثبت. أما الأوامر التي تقرأ الملفات فقط، مثل contract diff وchange list، فلا تحتاج إليه.

تشغيل الطلبات

الهدف هو طلب أو مجلد أو مجموعة. أعطِ معرّفه من getman ls، أو مساره بالاسم مثل Shop API/Orders/Get order. يعمل الاسم المجرد إذا كان فريدًا.

export GETMAN_VAR_password=…
getman run "Shop API" --workspace getman --env Local
getman run "Shop API/Orders/Get order" --workspace getman --env Local --json

تُشغَّل المجلدات والمجموعات طلباتها بترتيب الشجرة. تنتقل المتغيرات التي تضبطها سكربتات ما بعد الاستجابة إلى الطلب التالي في التشغيل نفسه.

الخيارات

الخيار	المعنى
--project P	معرّف المشروع أو اسمه، عند استخدام قاعدة بيانات التطبيق.
--workspace DIR	مجلد مزامنة، مثل getman. يقرأ ملفاته وأسراره من GETMAN_VAR_<KEY>.
--env NAME	اسم البيئة أو معرّفها.
--var k=v	متغير وقت التشغيل. يمكن تكراره. لا يُحفظ.
--iterations N، --data FILE	كرر التشغيل، أو شغّل تكرارًا لكل صف في ملف CSV أو JSON.
--timeout MS، --delay MS	مهلة الطلب، وفترة توقف بين الطلبات.
--bail	يتوقف عند أول طلب فاشل.
--allow-mutations	يرسل POST وPUT وPATCH وDELETE إلى بيئات من نوع الإنتاج.
--json، --include-bodies	يطبع مخرجات JSON، ويضمّن نصوص الاستجابات فيها.
--no-secrets	لا يقرأ قيم الأسرار، فتبقى فارغة.
--engine PATH	ملف المحرك الثنائي المراد استخدامه.

رموز الحالة ونتائج الاختبار

يفشل الطلب إذا أعادت الواجهة استجابة 4xx أو 5xx، إلا إذا كان هناك تأكيد مفعّل للحالة يتوقعها، مثل Status equals 401 لطلب يختبر حالة عدم التفويض. يستخدم تطبيق سطح المكتب والمشغّل و--bail وMCP ودليل التغيير القاعدة نفسها.

رموز الخروج

الرمز	المعنى
0	نجحت جميع الطلبات.
1	فشل اختبار.
2	فشل طلب أو سكربت: اتصال، أو مهلة، أو خطأ TLS، أو خطأ في السكربت.
3	خطأ في الاستخدام أو الإعداد، مثل مشروع أو بيئة غير معروفة، أو عدم وجود محرك.
4	تم تخطي طلب تعديل على الإنتاج.
5	الأسرار المحفوظة مقفلة أمام سطر الأوامر. فعّل الوصول من Project settings → Command line & agents، أو استخدم --no-secrets.
130	مقاطعة بالضغط على Ctrl-C.

عند انطباق أكثر من حالة، تُعتمد الأولى حسب هذا الترتيب: 130 ثم 2 ثم 4 ثم 1 ثم 0.

بوابة الإنتاج

لا تُرسل طلبات التعديل (أي شيء غير GET وHEAD وOPTIONS) إلى البيئات المدرجة في قائمة confirmMutationsIn الخاصة بالمشروع. القائمة الافتراضية هي production. يُبلَّغ عن الطلب بأنه skipped، ويخرج التشغيل بالرمز 4. استخدم --allow-mutations فقط عندما تقصد تغيير بيانات الإنتاج فعلًا. للوكلاء مسار موافقة خاص، موصوف في خادم MCP.

مخرجات JSON

مع --json، يطبع التشغيل كائنًا واحدًا بالمخطط getman.run/v1:

{
  "schema": "getman.run/v1",
  "ok": false,
  "exitCode": 1,
  "source": "workspace",
  "environment": { "name": "Local", "kind": "local" },
  "summary": { "total": 2, "passed": 1, "failed": 1, "errors": 0, "skipped": 0, "cancelled": 0 },
  "steps": [
    { "name": "Login", "method": "POST", "outcome": "passed", "status": 200, "tests": [{ "name": "has token", "passed": true }] }
  ]
}

الأخطاء التي تحدث قبل التشغيل تطبع كائن getman.error/v1 يتضمن رمز الخروج ورسالة.

العقود

getman contract export --workspace getman --out openapi.yaml
getman contract diff before.yaml after.yaml --fail-on breaking

يكتب contract export ملف OpenAPI 3.1 بصيغة YAML إلى المخرجات القياسية، أو إلى --out. يقارن contract diff ملفي OpenAPI. مع --fail-on breaking يخرج بالرمز 1 إذا وُجد تغيير كاسر. ويحتسب --fail-on potentially-breaking التغييرات المحتمل كسرها أيضًا.

حزم التغيير

getman change new --workspace getman --title "…" --migration "…" --author "Alice (backend)"
getman change list --workspace getman
getman change show GT-SHOP-001 --workspace getman
getman change verify GT-SHOP-001 --workspace getman --env Local
getman change report GT-SHOP-001 --workspace getman --consumer web --status verified
getman change state GT-SHOP-001 published --workspace getman
getman change validate --workspace getman

• يقارن change new المشروع بالملف contracts/openapi.yaml، ويكتب ملف التغيير، ويطبع المعرّف الجديد. يرفض الأمر إذا لم يتغير شيء.
• يشغّل change verify الطلبات التي يمسها التغيير، ويسجّل التشغيل كدليل. رمز خروجه هو رمز خروج التشغيل.
• يسجّل change report حالة مستهلك: pending أو in-progress أو reported أو verified أو blocked.
• ينقل change state التغيير إلى draft أو published أو withdrawn.
• يتحقق change validate من ملفات التغيير والعقد بحثًا عن علامات التعارض، وYAML غير الصالح، والمعرّفات المكررة، وعدم تطابق أسماء الملفات. يخرج بالرمز 3 عند وجود مشكلات.

تحتاج أوامر الكتابة إلى --workspace. ولا يكتب CLI في قاعدة بيانات التطبيق أبدًا. التفاصيل موجودة في حزم التغيير.

خادم المحاكاة

getman mock --workspace getman --port 4010
getman mock --from openapi.yaml

يقدّم خادم المحاكاة أمثلة الاستجابات المحفوظة على 127.0.0.1. المنفذ الافتراضي هو 4010. أوقفه بالضغط على Ctrl-C، فيخرج بالرمز 130.

الاستخدام في CI

يمكن تشغيل contract diff وchange validate من حزمة مبنية دون محرك: yarn build:cli، ثم node dist-cli/getman.mjs contract diff …. يحتاج run وchange verify إلى ملف محرك ثنائي. ابنِه بالأمر cd src-tauri && cargo build --features engine --bin engine. لم يُختبر استخدام CI بعد.