أوامر مخصصة

عرّف الأوامر المخصصة وتخطيطات مساحة العمل بإضافة ملف cmux.json إلى جذر مشروعك أو ~/.config/cmux/. تظهر الأوامر في لوحة الأوامر.

مواقع الملفات

يبحث cmux عن التكوين في مكانين:

لكل مشروع: ./cmux.json — يقع في دليل مشروعك، له الأولوية
عالمي: ~/.config/cmux/cmux.json — ينطبق على جميع المشاريع، يملأ الأوامر غير المعرفة محلياً

الأوامر المحلية تتجاوز الأوامر العالمية بنفس الاسم.

يتم اكتشاف التغييرات تلقائياً — لا حاجة لإعادة التشغيل.

المخطط

يحتوي ملف cmux.json على مصفوفة commands. كل أمر إما أمر shell بسيط أو تعريف كامل لمساحة عمل:

cmux.json

{
  "commands": [
    {
      "name": "Start Dev",
      "keywords": ["dev", "start"],
      "workspace": { ... }
    },
    {
      "name": "Run Tests",
      "command": "npm test",
      "confirm": true
    }
  ]
}

أوامر بسيطة

الأمر البسيط ينفذ أمر shell في الطرفية المحددة حالياً:

cmux.json

{
  "commands": [
    {
      "name": "Run Tests",
      "keywords": ["test", "check"],
      "command": "npm test",
      "confirm": true
    }
  ]
}

الحقول

name — يظهر في لوحة الأوامر (مطلوب)
description — وصف اختياري
keywords — مصطلحات بحث إضافية للوحة الأوامر
command — أمر shell للتشغيل في الطرفية المحددة
confirm — عرض مربع حوار للتأكيد قبل التشغيل

تعمل الأوامر البسيطة في دليل العمل الحالي للطرفية المحددة. إذا كان أمرك يعتمد على مسارات نسبية للمشروع، أضف قبله cd "$(git rev-parse --show-toplevel)" && للتشغيل من جذر المستودع، أو cd /your/path && لأي دليل محدد.

أوامر مساحة العمل

يُنشئ أمر مساحة العمل مساحة عمل جديدة بتخطيط مخصص من الانقسامات والطرفيات وألواح المتصفح:

cmux.json

{
  "commands": [
    {
      "name": "Dev Environment",
      "keywords": ["dev", "fullstack"],
      "restart": "confirm",
      "workspace": {
        "name": "Dev",
        "cwd": ".",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Frontend",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Backend",
                    "command": "cargo watch -x run",
                    "cwd": "./server",
                    "env": { "RUST_LOG": "debug" }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

حقول مساحة العمل

name — اسم علامة التبويب لمساحة العمل (الافتراضي: اسم الأمر)
cwd — دليل العمل لمساحة العمل
color — لون علامة تبويب مساحة العمل
layout — شجرة التخطيط التي تحدد الانقسامات والألواح

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

يتحكم فيما يحدث عندما توجد مساحة عمل بنفس الاسم:

"ignore" — التبديل إلى مساحة العمل الموجودة (الافتراضي)
"recreate" — الإغلاق وإعادة الإنشاء دون سؤال
"confirm" — السؤال قبل إعادة الإنشاء

شجرة التخطيط

تحدد شجرة التخطيط كيفية ترتيب الألواح باستخدام عقد الانقسام المتكررة:

عقدة الانقسام

تقسم المساحة إلى فرعين:

direction — "horizontal" أو "vertical"
split — موضع الفاصل من 0.1 إلى 0.9 (الافتراضي 0.5)
children — فرعان بالضبط (انقسام أو لوح)

عقدة اللوح

عقدة طرفية تحتوي على واحد أو أكثر من الأسطح (علامات التبويب داخل اللوح).

تعريف السطح

كل سطح في لوح يمكن أن يكون طرفية أو متصفحاً:

type — "terminal" أو "browser"
name — عنوان علامة تبويب مخصص
command — أمر shell للتشغيل التلقائي عند الإنشاء (للطرفية فقط)
cwd — دليل العمل لهذا السطح
env — متغيرات البيئة كأزواج مفتاح-قيمة
url — رابط للفتح (للمتصفح فقط)
focus — التركيز على هذا السطح بعد الإنشاء

تحليل دليل العمل

. أو محذوف — دليل عمل مساحة العمل
./subdir — نسبي إلى دليل عمل مساحة العمل
~/path — موسّع إلى الدليل الرئيسي
مسار مطلق — يُستخدم كما هو

مثال كامل

cmux.json

{
  "commands": [
    {
      "name": "Web Dev",
      "description": "Docs site with live preview",
      "keywords": ["web", "docs", "next", "frontend"],
      "restart": "confirm",
      "workspace": {
        "name": "Web Dev",
        "cwd": "./web",
        "color": "#3b82f6",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Next.js",
                    "command": "npm run dev",
                    "focus": true
                  }
                ]
              }
            },
            {
              "direction": "vertical",
              "split": 0.6,
              "children": [
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "browser",
                        "name": "Preview",
                        "url": "http://localhost:3777"
                      }
                    ]
                  }
                },
                {
                  "pane": {
                    "surfaces": [
                      {
                        "type": "terminal",
                        "name": "Shell",
                        "env": { "NODE_ENV": "development" }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    },
    {
      "name": "Debug Log",
      "description": "Tail the debug event log from the running dev app",
      "keywords": ["log", "debug", "tail", "events"],
      "restart": "ignore",
      "workspace": {
        "name": "Debug Log",
        "layout": {
          "direction": "horizontal",
          "split": 0.5,
          "children": [
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Events",
                    "command": "tail -f /tmp/cmux-debug.log",
                    "focus": true
                  }
                ]
              }
            },
            {
              "pane": {
                "surfaces": [
                  {
                    "type": "terminal",
                    "name": "Shell"
                  }
                ]
              }
            }
          ]
        }
      }
    },
    {
      "name": "Setup",
      "description": "Initialize submodules and build dependencies",
      "keywords": ["setup", "init", "install"],
      "command": "./scripts/setup.sh",
      "confirm": true
    },
    {
      "name": "Reload",
      "description": "Build and launch the debug app tagged to the current branch",
      "keywords": ["reload", "build", "run", "launch"],
      "command": "./scripts/reload.sh --tag $(git branch --show-current)"
    },
    {
      "name": "Run Unit Tests",
      "keywords": ["test", "unit"],
      "command": "./scripts/test-unit.sh",
      "confirm": true
    }
  ]
}