xaaha/hulakعميل API خفيف الوزن يعمل من سطر الأوامر وقائم على الملفات، مع أسرار مشفّرة بـ age، ودعم أصلي لـ GraphQL، وخادم MCP مدمج لسير عمل وكلاء الذكاء الاصطناعي.
<p align="center">
<img alt="Hulak" src="https://raw.githubusercontent.com/xaaha/hulak/main/assets/hulak-logo.svg" width="180" />
</p>
<h1 align="center">Hulak</h1>
<h3 align="center">
رسائلك في الطرفية.
</h3>
<p align="center">
<a href="#quick-start">البدء السريع</a> •
<a href="#graphql-explorer">مستكشف GraphQL</a> •
<a href="#project-layout">تخطيط المشروع</a> •
<a href="#documentation">التوثيق</a>
</p>
---
### شغّل طلبًا واحدًا، أو مجلدًا كاملًا، أو ابقَ تفاعليًا
<img alt="Concurrent Execution" src="https://assets.kitploit.com/production/public/readmes/12535/3ea47749f291ed181923d64f3751b68e0fa035e3c16ec44c973a65fb32ee4c5a.gif" width="720" />
```bash
hulak run ./requests/
```
يشغّل Hulak ملفات الطلبات مباشرة من مشروعك. يدعم التنفيذ المتزامن للمجلدات. ويعود إلى منتقي تفاعلي عند تشغيل `hulak` فقط.
### مستكشف GraphQL المخصص
<img alt="GraphQL Explorer" src="https://assets.kitploit.com/production/public/readmes/12535/be3004f25dc07831b622ac6bae4a8cf276dbe450518d70d0de4641accd1cb454.gif" width="720" />
تصفّح المخططات من نقاط نهاية متعددة. ابحث في العمليات. ابنِ الاستعلامات تفاعليًا. نفّذها مباشرة. احفظ الملفات المُنشأة من الطرفية.
## البدء السريع
### التثبيت
يُوزَّع Hulak عبر [xaaha/tap](https://github.com/xaaha/homebrew-tap). يتطلب Homebrew 6.0+ ثقة صريحة للمستودعات الخارجية؛ بدونها يتخطى `brew upgrade` أداة hulak بصمت. خطوة لمرة واحدة لكل جهاز:
```bash
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`
أو بنيت من المصدر، ففعّله مرة واحدة:
```bash
# 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 مع أسرار مشفّرة (الافتراضي)
```bash
mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity
```
أنشئ طلبًا مبدئيًا؛ للتحقق سريعًا من شكل ملف الطلب شغّل:
```bash
hulak example api # writes example-api.hk.yaml you can run
```
> [!Note]
> للأنواع الأخرى شغّل: `hulak example`. يمنحك الأمر الفرعي `example` طريقة سريعة لكتابة ملف طلب يمكنك تعديله. لمزيد من المعلومات شغّل `hulak example -h`
لإعداد سر يمكنك تشغيل:
```bash
hulak secrets keys set placeholder https://jsonplaceholder.typicode.com/posts -env prod
```
الآن، في ملف `example-api.hk.yaml` الخاص بك، يمكنك الإشارة إلى هذا السر:
```yaml
method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same
```
شغّل الطلب:
```bash
hulak run example-api.hk.yaml --env prod
```
### تفضّل ملفات `env/*.env` النصية بدلًا من الأسرار المشفّرة؟
```bash
hulak init classic
```
الوضع النصي مدعوم بالكامل. راجع [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md) لمزيد من المعلومات
## خزنة الأسرار المشفّرة أو ملفات `.env` النصية
يعمل Hulak في وضعين. اختر مرة واحدة أثناء `hulak init`. يمكنك الترحيل لاحقًا.
- **الخزنة (الافتراضي):** تعيش الأسرار في `.hulak/store.age`، مشفّرة بمفتاح age أو زوج مفاتيح SSH. آمنة للإيداع. تشاركها الفرق عبر ملف المستلمين. راجع [docs/store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md).
- **النصي:** تعيش الأسرار في ملفات `env/*.env` النصية. أبسط، بلا تشفير. أضف `env/` إلى `.gitignore`. راجع [docs/environment.md](https://github.com/xaaha/hulak/blob/main/docs/environment.md).
تشغّل الوضع الكلاسيكي وتريد التبديل؟ راجع [docs/migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md).
## استخدمه من وكيل ذكاء اصطناعي (MCP)
يوفّر Hulak خادم [MCP](https://modelcontextprotocol.io) مدمجًا، حتى يتمكن وكلاء مثل Claude Code وCursor وZed من تشغيل مجموعة API الخاصة بك بلغة طبيعية — "اعرض الطلبات"، "نفّذ `login` تجريبيًا على staging"، "استدعِ `getUser` واعرض الاستجابة".
لـ Claude Code، أضفه بأمر واحد:
```bash
claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests
```
يستخدم Cursor وZed وCodex وopencode وPi ملف إعداد صغير بدلًا من ذلك. راجع [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) لكل منها.
لا تغادر الأسرار جهازك أبدًا: يعمل الوكيل مع **أسماء** الطلبات والبيئات، وليس القيم المفكوكة. القراءات والتنفيذات التجريبية للقراءة فقط؛ والكتابات مُتحقَّق منها بالمخطط؛ ولا تُحفظ ملفات الاستجابة إلا عند الطلب.
الإعداد الكامل، ومرجع الأدوات، ونموذج الأمان: [docs/mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md).
## الأوامر
| الأمر | الغرض | اقرأ المزيد |
| --------- | -------------------------------------- | ---------------------------------------------------------- |
| `run` | تنفيذ ملف/ملفات طلب أو مجلد | [body.md](https://github.com/xaaha/hulak/blob/main/docs/body.md), [actions.md](https://github.com/xaaha/hulak/blob/main/docs/actions.md) |
| `gql` | واجهة مستكشف GraphQL النصية | [graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md) |
| `secrets` | إدارة الخزنة المشفّرة | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `init` | تهيئة مشروع hulak | [store.md](https://github.com/xaaha/hulak/blob/main/docs/store.md) |
| `migrate` | تحويل Postman إلى hulak | [migrating-to-vault.md](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md) |
| `example` | إنشاء ملفات طلبات نموذجية | — |
| `doctor` | فحص صحة المشروع | — |
| `mcp` | تقديم الطلبات لوكلاء الذكاء الاصطناعي عبر MCP | [mcp.md](https://github.com/xaaha/hulak/blob/main/docs/mcp.md) |
| `version` | طباعة الإصدار | — |
شغّل `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](https://github.com/xaaha/hulak/blob/main/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` تحتاج إلى وصفة.** راجع [docs/versioning.md#merge-conflicts](https://github.com/xaaha/hulak/blob/main/docs/versioning.md#merge-conflicts).
## تخطيط المشروع
```text
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
ابدأ المستكشف بملف أو مجلد:
```bash
hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql
```
اقرأ الدليل الكامل في [docs/graphql-explorer.md](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md).
## التوثيق
ابدأ من هنا للمرجع الكامل:
- [الخزنة المشفّرة](https://github.com/xaaha/hulak/blob/main/docs/store.md). نموذج التشفير، مشاركة الفريق، CI.
- [الترحيل إلى الخزنة](https://github.com/xaaha/hulak/blob/main/docs/migrating-to-vault.md). من `env/` إلى `.hulak/`.
- [إصدار خزنتك](https://github.com/xaaha/hulak/blob/main/docs/versioning.md). سير عمل Git للأسرار.
- [المقارنة](https://github.com/xaaha/hulak/blob/main/docs/comparison.md). Hulak مقابل SOPS وBruno وأمثالهما.
- [جسم الطلب](https://github.com/xaaha/hulak/blob/main/docs/body.md)
- [الإجراءات](https://github.com/xaaha/hulak/blob/main/docs/actions.md)
- [أسرار البيئة (الوضع الكلاسيكي)](https://github.com/xaaha/hulak/blob/main/docs/environment.md)
- [ملفات الاستجابة](https://github.com/xaaha/hulak/blob/main/docs/response.md)
- [مستكشف GraphQL](https://github.com/xaaha/hulak/blob/main/docs/graphql-explorer.md)
- [Auth 2.0](https://github.com/xaaha/hulak/blob/main/docs/auth20.md)
- [خادم MCP](https://github.com/xaaha/hulak/blob/main/docs/mcp.md). اعرض طلباتك لوكلاء الذكاء الاصطناعي.
لواجهة الأوامر الحية، شغّل:
```bash
hulak help
hulak <command> --help
```
## دعم المخطط
مخطط Hulak متاح في [Schema Store](https://www.schemastore.org/)، لذا يمكن للمحررات التي تدعم Schema Store تفعيل الإكمال تلقائيًا لملفات `.hk.yaml` و`.hk.yml`.
يمكنك أيضًا توجيه خادم لغة YAML مباشرة إلى:
```text
https://raw.githubusercontent.com/xaaha/hulak/refs/heads/main/assets/schema.json
```
## المساهمة
```bash
git clone https://github.com/xaaha/hulak.git
cd hulak
mise install
```
راجع [CONTRIBUTING.md](https://github.com/xaaha/hulak/blob/main/CONTRIBUTING.md) لسير عمل التطوير الكامل.
## ادعم المشروع
إذا كان Hulak مفيدًا لك، افتح تذكرة، أو اقترح ميزة، أو أرسل طلب سحب، أو ارعَ المشروع.