hulak

عميل API أصلي لـ Git مع أسرار مشفّرة.

_{REST · GraphQL · OAuth}

البدء السريع • مستكشف GraphQL • هيكل المشروع • التوثيق

نفّذ طلبًا واحدًا، أو دليلًا كاملًا، أو ابقَ تفاعليًا

hulak run ./requests/

يشغّل Hulak ملفات الطلبات مباشرةً من مشروعك. وهو يدعم تنفيذ الأدلة بشكل متزامن. ويتحول إلى منتقي تفاعلي عند تشغيل hulak فقط.

مستكشف GraphQL مخصص

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

البدء السريع

التثبيت

يتوفر Hulak عبر xaaha/tap. يتطلب Homebrew 6.0+ ثقةً صريحةً في النواهض الخارجية (third-party taps)؛ وبدون ذلك، يتخطى brew upgrade hulak بصمت. خطوة تُنفَّذ مرة واحدة لكل جهاز:

brew trust xaaha/tap
brew install --cask xaaha/tap/hulak

خيارات تثبيت أخرى:

• go install github.com/xaaha/hulak@latest
• البناء من المصدر باستخدام go build -o hulak

إكمال الشل (go install / البناء من المصدر)

يثبّت Homebrew الإكمال تلقائيًا. إذا ثبّت عبر go install أو بنيت من المصدر، فعّل الخيار مرة واحدة:

# zsh
hulak completion zsh > "${fpath[1]}/_hulak"        # then restart your shell

# bash (macOS, Homebrew bash-completion)
hulak completion bash > $(brew --prefix)/etc/bash_completion.d/hulak

# bash (Linux)
hulak completion bash | sudo tee /etc/bash_completion.d/hulak >/dev/null

يتطلب Zsh وجود autoload -Uz compinit && compinit في ملف .zshrc.

المسار أ: عميل API مع أسرار مشفّرة (افتراضي)

mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity

أنشئ طلبًا مبدئيًا؛ وللتحقق السريع من شكل ملف الطلب، شغّل:

hulak example api  # writes example-api.hk.yaml you can run

[!Note] للأنواع الأخرى شغّل: hulak example. يمنحك الأمر الفرعي example طريقة سريعة لكتابة ملف طلب يمكنك تعديله. لمزيد من المعلومات شغّل hulak example -h

لإعداد سرّ، يمكنك تشغيل:

hulak secrets keys set placeholder  https://jsonplaceholder.typicode.com/posts -env prod

الآن، في ملف example-api.hk.yaml، يمكنك الإشارة إلى هذا السرّ:

method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same

شغّل الطلب:

hulak run example-api.hk.yaml --env prod

هل تفضّل ملفات env/*.env النصية العادية بدل الأسرار المشفّرة؟

hulak init classic

وضع النص العادي مدعوم بالكامل. راجع docs/environment.md لمزيد من المعلومات

الخزنة المشفّرة للأسرار أو ملفات .env النصية العادية

يعمل Hulak بنموذجين. اختر مرة واحدة أثناء hulak init. ويمكنك الترحيل لاحقًا.

• الخزنة (افتراضي): تخزَّن الأسرار في .hulak/store.age، مشفّرة بمفتاح age أو SSH. وهي آمنة للالتزام. تشارك الفرق عبر ملف المستفيدين. راجع docs/store.md.
• النص العادي: تخزَّن الأسرار في ملفات env/*.env بنص عادي. أبسط، وبدون تشفير. أضف env/ إلى .gitignore. راجع docs/environment.md.

تستخدم الوضع الكلاسيكي وتريد التبديل؟ راجع docs/migrating-to-vault.md.

استخدامه من وكيل ذكاء اصطناعي (MCP)

يأتي Hulak مزوّدًا بخادم MCP مدمج، بحيث يمكن لوكلاء مثل Claude Code وCursor وZed تشغيل مجموعة API الخاصة بك بلغة طبيعية — «اعرض الطلبات»، «جرّب login جافًا (dry-run) على staging»، «استدعِ getUser واعرض الاستجابة».

لإضافته إلى Claude Code، استخدم أمرًا واحدًا:

claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests

بدلًا من ذلك، تستخدم Cursor وZed وCodex وopencode وPi ملف إعداد صغير. راجع docs/mcp.md لكل أداة.

لا تغادر الأسرار جهازك أبدًا: يعمل الوكيل مع أسماء الطلبات والبيئات، وليس مع القيم المفكوكة تشفيرها أبدًا. القراءات والتشغيل الجاف (dry-runs) للقراءة فقط؛ وتُتحقق الكتابات من المخطط (schema)؛ ولا تُحفظ ملفات الاستجابة إلا عند طلب ذلك.

الإعداد الكامل ومرجع الأدوات ونموذج الأمان: docs/mcp.md.

الأوامر

شغّل hulak <command> --help للاطلاع على الخيارات والأمثلة الخاصة بكل أمر.

سلوك المنتقي

يؤدي حذف --env إلى فتح منتقي تفاعلي.

• يطلب hulak run وhulak gql الإدخال فقط عندما تشير الملفات إلى {{.key}}.
• تطلب الأوامر الفرعية لـhulak secrets الإدخال في كل مرة (باستثناء secrets list).
• تتطلب الأصداف غير التفاعلية --env <name>.

الأخطاء الشائعة

• لا تلتزم أبدًا ~/.config/hulak/identity.txt. هذا هو مفتاحك الخاص. الوضع 0600. احتفظ بنسخة احتياطية منه أولًا. راجع docs/store.md#identity-backup.
• عند أمر hulak init، ينشئ -env ملفات بيئة. إنه خيار إعداد وليس محددًا في وقت التشغيل. يهيئ hulak init -env staging prod بيئتين.
• env اسم مستعار لـsecrets. يعمل hulak env list بالطريقة نفسها التي يعمل بها hulak secrets list.
• تحتاج محررات الواجهات الرسومية إلى خيار انتظار لأمر secrets edit. استخدم EDITOR="code -w" أو EDITOR="zed --wait". وبدون ذلك، يعود المحرر فورًا وتُفقد التغييرات.
• تحتاج تعارضات الدمج في store.age إلى وصفة معالجة. راجع .

هيكل المشروع

my-project/
├── .hulak/
│   ├── store.age          # encrypted secrets (safe to commit)
│   └── recipients.txt     # public keys of recipients (safe to commit)
├── requests/
│   ├── create-user.hk.yaml
│   └── get-user.hk.yaml
└── (your project files)

~/.config/hulak/
└── identity.txt           # YOUR private key. NEVER commit. Mode 0600.

مستكشف GraphQL

ابدأ المستكشف بملف أو دليل:

hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql

اقرأ الدليل الكامل في docs/graphql-explorer.md.

التوثيق

ابدأ هنا للاطلاع على المرجع الكامل:

• الخزنة المشفّرة. نموذج التشفير والمشاركة الجماعية وCI.
• الترحيل إلى الخزنة. من env/ إلى .hulak/.
• إصدار خزنتك. سير عمل Git للأسرار.
• المقارنة. Hulak مقابل SOPS وBruno وأمثالهما.
• نص الطلب
• الإجراءات
• أسرار البيئة (الوضع الكلاسيكي)
• ملفات الاستجابة
• مستكشف GraphQL
• Auth 2.0
• خادم MCP. اعرض طلباتك لوكلاء الذكاء الاصطناعي.

للاطلاع على واجهة الأوامر المباشرة، شغّل:

hulak help
hulak <command> --help

دعم المخططات (Schema)

مخطط Hulak متاح في Schema Store؛ لذلك يمكن للمحررات التي تدعم Schema Store تفعيل الإكمال التلقائي لملفات .hk.yaml و.hk.yml.

يمكنك أيضًا توجيه خادم لغة YAML مباشرةً إلى:

https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json

المساهمة

git clone https://github.com/xaaha/hulak.git
cd hulak
mise install

راجع CONTRIBUTING.md لسير عمل التطوير الكامل.

ادعم المشروع

إذا كان Hulak مفيدًا لك، فافتح مشكلة (issue)، أو اقترح ميزة، أو أرسل طلب سحب (pull request)، أو ادعم المشروع ماليًا.