‏راهنمای ساخت CLI حرفه‌ای با Node.js

لیران تال یه راهنمای متن‌باز جمع کرده به اسم Node.js CLI Apps Best Practices که ۴۱ تجربهٔ عملی ساخت ابزار خط فرمان رو تو دسته‌هایی مثل تجربهٔ خط فرمان، توزیع، هم‌کارکردی، دسترس‌پذیری، تست، خطاها، توسعه، آنالیتیکس، نسخه‌بندی و امنیت مرتب کرده. به گفتهٔ نویسنده، یه CLI بد به همون سادگیِ یه رابط وب بد کاربر رو دلزده می‌کنه، و ساختن CLI موفق بیشتر از هر چیزی به همدلی با کاربر و دقت تو جزئیات نیاز داره.

پایهٔ همه‌چیز، احترام به قراردادهای POSIX تو آرگومان‌هاست: فلگ کوتاه تک‌حرفی به‌عنوان مترادف فلگ بلند، امکان گروه کردن چند فلگ کوتاه، و نشون دادن آرگومان اختیاری با [] و اجباری با تو راهنما. تو این راهنما اومده که برای CLIهای کوچیک و متوسط، قبل از اضافه کردن وابستگی، اول parseArgs() از ماژول node:util رو امتحان کنین؛ سراغ commander، yargs یا Optique وقتی برین که زیردستور، راهنمای تولیدشده یا تکمیل خودکار شل لازم دارین.

import { parseArgs } from 'node:util';

const { values, positionals } = parseArgs({
  options: {
    help: { type: 'boolean', short: 'h' },
    json: { type: 'boolean' },
  },
  allowPositionals: true,
});

یه بخش جالب، چیزیه که نویسنده بهش می‌گه CLI همدل: به‌جای اینکه با نبود ورودی فقط یه خطا بندازی، کاربر رو به سمت اجرای موفق هدایت کن. ولی این همدلی شرط داره — اگه برنامه تو CI یا یه جاب زمان‌بندی‌شده یا خط لولهٔ خودکار اجرا می‌شه، نباید prompt بذاری؛ اون‌جا باید خطای شفافی بدی که بگه کدوم فلگ یا متغیر محیطی یا فایل کانفیگ می‌تونه اون مقدار گم‌شده رو تأمین کنه. همین منطق دربارهٔ رنگ هم صدق می‌کنه: styleText() از node:util وضعیت پشتیبانی ترمینال و متغیرهای محیطی کنترل رنگ رو در نظر می‌گیره و باید همیشه راه دستی خاموش کردن رنگ هم وجود داشته باشه.

بخش توزیع بیشتر دربارهٔ هزینهٔ نصبه. حجم وابستگی‌ها رو کم نگه دار، چون کاربری که با npx ابزارت رو صدا می‌زنه هر بار هزینهٔ نصب رو می‌ده. برای قفل کردن نسخه‌ها npm-shrinkwrap.json پیشنهاد می‌شه، ولی نویسنده صادقانه به روی دیگه‌ش هم اشاره می‌کنه: با قفل کردن نسخه‌ها، مسئولیت به‌روز نگه داشتن وصله‌های امنیتی می‌افته گردن خودت. اگه هم برنامه‌ت فایل کانفیگ ذخیره می‌کنه، باید طبق مشخصات XDG Base Directory بنویسه و موقع حذف نصب هم راهی برای پاک کردنش بذاره.

بقیهٔ فصل‌ها روی چیزهایی دست می‌ذارن که معمولاً فراموش می‌شن: احترام به سیگنال‌های POSIX تا CTRL+C و توقف داخل کانتینر درست کار کنه، راهنمای واقعاً مفید با -h و --help و راهنمای جدا برای هر زیردستور، جدا کردن STDOUT از STDERR، خروجی ساختاریافته برای اسکریپت‌نویس‌ها، کدهای خروج درست، حالت دیباگ و گزارش باگ بی‌دردسر. بخش امنیت هم روی کم کردن خطر تزریق آرگومان تمرکز داره. خود مخزن یه فایل SKILL.md برای ایجنت‌های هوش مصنوعی داره و به چند زبان هم ترجمه شده.

نکات کلیدی:

• ۴۱ تجربهٔ عملی در ۱۰ حوزه، از تجربهٔ کاربری تا امنیت و نسخه‌بندی
• برای پارس آرگومان اول parseArgs() از node:util رو ببین، بعد سراغ کتابخونه برو
• رنگ و prompt تعاملی باید موقع اجرا تو CI خودکار خاموش بشن و راه خاموشی دستی هم داشته باشن
• وابستگی کم = نصب سریع‌تر با npx؛ npm-shrinkwrap.json نسخه‌ها رو قفل می‌کنه ولی مسئولیت وصلهٔ امنیتی رو می‌ندازه گردن نگه‌دارنده
• کانفیگ رو طبق XDG Base Directory ذخیره کن و راه پاک کردنش رو هم بذار
• به سیگنال‌های POSIX احترام بذار و STDOUT رو از STDERR جدا کن