تبدیل اسکریپت Ralph به یک CLI منعطف — تکنیک Ralph Wiggum

وقتش رسیده اسکریپت ساده Ralph را به یک CLI تمیز و منعطف تبدیل کنیم — با پشتیبانی از چیزهایی مثل YoloBox. و کار بامزه این است: از خود Ralph استفاده می‌کنیم تا CLI خود Ralph را بسازد. یک نقشه کلی داریم و با هم پیش می‌رویم.

تصمیم‌های معماری قبل از PRD

اول جهت‌گیری‌ها را مشخص می‌کنیم:

CLI باید یک TUI باشد؛ برای این کار OpenTUI را انتخاب می‌کنیم.
قبل از PRD، Skill مربوط به OpenTUI را نصب می‌کنیم تا مدل هرجا لازم شد به آن ارجاع دهد (در Claude این یک Symlink به پوشه agents است).
Runtime را Bun می‌گذاریم و رابط را با React (Ink-style) می‌سازیم.

CLI — Command Line Interface

برنامه خط فرمان. اینجا Ralph را از یک اسکریپت به ابزاری با نصب سراسری و رابط تعاملی ارتقا می‌دهیم.

TUI — Terminal User Interface

رابط کاربری متنی داخل ترمینال؛ با Tab و کلید کنترل می‌شود. با OpenTUI و React ساخته می‌شود.

Bun

یک Runtime سریع جاوااسکریپت (جایگزین Node) که برای اجرا و بسته‌بندی CLI استفاده می‌شود.

ساخت PRD برای CLI

با YoloBox و Claude، PRD را می‌سازیم:

I need a PRD. Turn the ralph.js script into a CLI with a nice TUI.
Use Bun, use OpenTUI, look at the OpenTUI skill where relevant.
Create all new files in the ralph-cli directory.

مدل کد فعلی و Skill را می‌خواند و چند سؤال می‌پرسد. جواب‌های کلیدی:

صفحه‌ها: Tab در بالای صفحه که بشود بینشان چرخید و خروجی زنده هر حلقه را دید.
یک جریان تعاملی واحد: با فشردن C همه PRDهای Backlog لیست شوند و تعاملی یکی را انتخاب کنم.

قابلیت‌های نهایی CLI

PRD نهایی این‌ها را تعریف می‌کند:

قابلیت	توضیح
Tab Bar افقی	بالای صفحه، سوییچ بین ایجنت‌های در حال اجرا
Spawn با C	ساخت ایجنت جدید و انتخاب تعاملی PRD
خروجی جریانی	Session ID، بلوک تفکر، متن، Tool Call، نتیجه، خلاصه
فلگ YoloBox	اجرای همه ایجنت‌ها داخل جعبه امن
فلگ iterations	پیش‌فرض ۳۰
Status Bar	نشانگر وضعیت: سبز=در حال اجرا، تیک=کامل، قرمز=خطا، زرد=متوقف
کلید X و Q	X تب را می‌بندد (ایجنت زنده را می‌کشد)، Q کل CLI را می‌بندد

نکته مهم رفتاری: تب‌های Complete/Stopped/Error باز می‌مانند تا بشود لاگ‌ها را مرور کرد.

چطور Child Process ساخته می‌شود

بخش فنی مهم، همان الگوی اجرای مدل است — با و بدون YoloBox. در PRD واقعی CLI دقیقاً این دو فرمان آمده بود:

# اجرای مستقیم (پیش‌فرض):
claude -p --output-format stream-json --verbose

# اجرای سندباکس‌شده با --yolobox:
yolobox claude --claude-config --git-config -- -p \
  --output-format stream-json --verbose

و فهرست اولویت‌بندی‌شدهٔ همان PRD — همان موتوری که حلقه از رویش کار کرد:

High:   scaffold, CLI parsing, PRD discovery, prompt builder,
        stream-json parser, child-process spawner,
        root layout, agent panel, spawn modal, status bar, tab bar,
        global keyboard shortcuts
Medium: log entries, empty state, status indicators,
        terminal resize, quit confirmation, preflight (is yolobox installed?),
        package.json build + install-cli
Low:    autoscroll, truncating, total cost aggregation,
        --help, border polish, CLAUDE.md for future agents

ساختن با خود Ralph و نصب سراسری

روی یک Branch تازه، داخل YoloBox، `node ralph.js` را با ۳۰ Iteration اجرا می‌کنیم و OpenTUI را انتخاب می‌کنیم. حلقه بدون مشکل تمام می‌شود و پوشه `ralph-cli` ساخته می‌شود. سپس:

cd ralph-cli
bun install
bun run start          # تست
bun run build
bun run install-cli    # نصب سراسری (رمز عبور برای Symlink)

حالا `ralph` در PATH موجود است. `ralph` را می‌زنیم، با C یک ایجنت Spawn می‌کنیم، PRD انتخاب می‌کنیم، چند تب باز می‌کنیم، با کیبورد بینشان می‌چرخیم، X برای بستن، Q برای خروج. با `ralph --yolobox` همه ایجنت‌ها داخل جعبه اجرا می‌شوند.

اما یک سؤال باز ماند: اگر چند ایجنت هم‌زمان روی «یک پوشه» و PRDهای مختلف کار کنند، توی کار هم می‌روند. حل این مشکل، موضوع درس بعد است.

به زبان ساده

از خود Ralph استفاده می‌کنی تا Ralph را به یک CLI با تب و کلید میانبر تبدیل کنی. PRD را می‌نویسی، حلقه می‌سازد، بعد با همان CLI چند ایجنت موازی راه می‌اندازی.

مثال واقعی

روی Branch تازه داخل YoloBox، `node ralph.js 30` پوشه ralph-cli را ساخت. `bun run install-cli` باینری `ralph` را در PATH گذاشت. با C دو PRD انتخاب شد، چند تب باز شد، `--yolobox` همه را داخل جعبه برد.