خط فرمان parto-ui

parto-ui همراه بستهٔ @partodata/ui نصب می‌شود. با آن یک نفر یک بار مخزن محصول را برای Claude Code و Codex آماده می‌کند، و عامل‌ها (و خود تیم) پیش از پایان هر تغییر، کارشان را با آن بررسی می‌کنند. همهٔ فرمان‌ها آفلاین کار می‌کنند و چیزی نصب نمی‌کنند.

راه‌اندازی یک‌باره (کار یک نفر، نه عامل)

npx --no parto-ui agents init --scope app

--scope لایه‌ای را مشخص می‌کند که این اپ از سیستم طراحی استفاده می‌کند: basics (فقط توکن، فونت، ارقام، راست‌به‌چپ و تاریخ شمسی)، components (به‌علاوهٔ کامپوننت‌ها) یا app (به‌علاوهٔ قاب، قالب صفحه‌ها و قواعد سخت‌گیرانه). این فرمان:

• یک بلوک مدیریت‌شده در AGENTS.md می‌نویسد و @AGENTS.md را به CLAUDE.md اضافه می‌کند؛
• مهارت‌ها (skills) را در .claude/skills و .agents/skills به نسخهٔ نصب‌شده در node_modules پیوند می‌دهد (در ویندوز فایل‌های کوچک جایگزین می‌سازد)؛
• هوک‌های SessionStart و Stop را برای هر دو عامل ثبت می‌کند؛
• پیکربندی parto.config.json و فهرست خالی .parto/ds-gaps.json را می‌سازد.

اجرای دوباره چیزی را عوض نمی‌کند، مگر نسخهٔ جدید بسته قرارداد عامل‌ها را تغییر داده باشد. همهٔ فایل‌هایی که این فرمان می‌نویسد باید در git ثبت شوند؛ اگر .gitignore یکی از آن‌ها را نادیده بگیرد، فرمان چیزی نمی‌نویسد و خط‌هایی را که باید به .gitignore اضافه شوند چاپ می‌کند. --mcp مدخل سرور MCP را هم برای هر دو عامل می‌نویسد و --remove همه‌چیز را برمی‌گرداند.

در مونوریپو فرمان را در پوشهٔ هر اپ اجرا کنید؛ در ریشهٔ مونوریپو (به‌ویژه با pnpm) فرمان parto-ui در دسترس نیست:

cd apps/web && npx --no parto-ui agents init --scope app

عامل (Claude Code یا Codex) را هم در پوشهٔ اپ باز کنید. عاملی که در ریشهٔ مونوریپو شروع شود فقط مهارت‌های مشترک همهٔ اپ‌ها را فهرست می‌کند؛ AGENTS.md ریشه مهارت‌های خاص هر اپ را نام می‌برد و فرمان خواندن آن‌ها از ریشه را می‌دهد، مثل (cd apps/web && npx --no parto-ui skill parto-ui-build-page). پرانتز فرمان را در یک پوستهٔ فرعی اجرا می‌کند تا پوستهٔ عامل در ریشه بماند؛ Claude Code پوشهٔ کاری را میان فرمان‌ها نگه می‌دارد و بدون پرانتز، cd بعدی شکست می‌خورد. در PowerShell ویندوز همین فرمان Push-Location apps/web; npx --no parto-ui skill parto-ui-build-page; Pop-Location است؛ PowerShell هم پوشهٔ کاری را نگه می‌دارد و Pop-Location پوسته را به ریشه برمی‌گرداند.

اگر .gitignore پوشه یا فایلی از این‌ها را نادیده بگیرد، agents init پیش از نوشتن متوقف می‌شود و خط‌هایی را چاپ می‌کند که git را وادار به ثبت همین فایل‌ها می‌کنند و بقیهٔ فایل‌های همان پوشه (مثل .claude/settings.local.json) را همچنان نادیده می‌گیرند. این خط‌ها پیش از چاپ در یک مخزن موقت با خود git آزموده می‌شوند، پس یک بار اعمال آن‌ها کافی است. اگر قاعده در فایل ignore سراسری git شما (core.excludesFile) باشد، خط‌ها به .git/info/exclude همین مخزن می‌روند و آن فایل سراسری، که همهٔ مخزن‌های این دستگاه را در بر می‌گیرد، هرگز تغییر نمی‌کند. پوشه‌ای که پیوند نمادین (symlink) به بیرون مخزن یا به مسیری ناموجود باشد هم پیش از نوشتن رد می‌شود.

هوک‌ها

هوک Stop در پایان هر نوبت عامل، check --changed را فقط برای فایل‌هایی اجرا می‌کند که عامل در همین نشست تغییر داده است. تغییرهای ثبت‌نشدهٔ خود شما که پیش از شروع نشست وجود داشتند، تا وقتی عامل به آن‌ها دست نزند، بررسی نمی‌شوند. اگر یافته‌ای بماند، عامل حداکثر سه بار به کار برمی‌گردد و بعد نوبت با یک هشدار برای شما تمام می‌شود.

هوک‌ها نسخهٔ نصب‌شدهٔ بسته را اجرا می‌کنند، پس در هر کلون و هر git worktree پیش از شروع عامل باید بسته‌ها نصب شده باشند؛ وگرنه Claude Code خطای هوک نشان می‌دهد و Codex هشدار می‌دهد که تغییرها بررسی نشده‌اند. در مونوریپو هوک‌های ریشه نسخهٔ نصب‌شده در یکی از اپ‌ها را اجرا می‌کنند (خروجی agents init آن را نام می‌برد)، پس نصب فیلترشده (مثل pnpm install --filter) باید آن اپ را هم در بر بگیرد. Codex هوک‌های پروژه را فقط وقتی اجرا می‌کند که پروژه قابل‌اعتماد (trusted) باشد و هوک‌های آن در /hooks تأیید شده باشند؛ در مونوریپو ریشهٔ git را قابل‌اعتماد کنید، نه فقط پوشهٔ اپ را.

بررسی خودکار

بررسی شامل تایپ‌چک با TypeScript خود پروژه، قواعد ESLint سیستم طراحی، parto-design-lint و ثبت کمبودهای سیستم طراحی است. کدهای خروج: 0 تمیز، 1 یافته دارد، 2 پیکربندی نادرست، 3 ابزاری کم است، 4 نوشتن ممکن نشد.

check قواعد ESLint نسخهٔ نصب‌شده را برای دامنهٔ اپ اجرا می‌کند؛ در دامنهٔ app قواعد صفحه هم هست: یک قالب در هر صفحه، <h1> خام کنار عنوان قالب، دومین دکمهٔ primary و مقدارهای دلخواه چیدمان مثل max-w-[720px]، و هر یافته راه اصلاح خود را می‌گوید (npx --no parto-ui rule <id> توضیح کامل‌تر). check به eslint (9.28 یا بالاتر) و در پروژهٔ TypeScript به typescript-eslint و typescript خود پروژه نیاز دارد؛ اگر نباشند با کد 3 متوقف می‌شود و دستور نصب را چاپ می‌کند، و agents init همین را از پیش می‌گوید.

تایپ‌چک باید همهٔ فایل‌های بررسی‌شده را پوشش دهد. فایلی که include یا exclude در tsconfig آن را بیرون می‌گذارد، فایل جاوااسکریپتی که از @partodata/ui استفاده می‌کند ولی تایپ‌چک نمی‌شود، و مدخلی در compilerOptions.paths که @partodata/ui را به جایی جز بستهٔ نصب‌شده می‌برد، کد 2 می‌دهند. همین‌طور است اعلان declare module برای @partodata/ui در هر فایلی از برنامه (حتی بیرون از src) و هر تنظیمی که نوع‌های سیستم طراحی را از بستهٔ نصب‌شده نخواند (مثلاً "moduleResolution": "node10")؛ check این را با تایپ‌چک یک فایل آزمایشی که فقط در حافظه ساخته می‌شود، با TypeScript خود پروژه، می‌سنجد. اگر پوشه‌ای عمداً بیرون از تایپ‌چک است (mock، fixture یا اسکریپت)، یک نفر آن را به ignore در parto.config.json اضافه می‌کند؛ agents init این فایل‌ها را از پیش نام می‌برد. در check --changed فایلی که در نقطهٔ شروع هم بیرون از تایپ‌چک بوده و tsconfig از آن زمان تغییر نکرده، فقط هشدار می‌گیرد.

check همیشه در پوشهٔ یک اپ اجرا می‌شود. در CI یک مخزن تک‌اپ خط npx --no parto-ui check --ci را اجرا می‌کند و در مونوریپو برای هر اپ یک خط جدا، مثل (cd apps/web && npx --no parto-ui check --ci). agents init همین کار CI را با مسیر اپ‌های خود مخزن چاپ می‌کند. در GitLab نقطهٔ شروع مقایسه از متغیرهای خط لوله خوانده می‌شود؛ در CI دیگر (مثلاً GitHub Actions) آن را با --base <commit> بدهید، وگرنه check --ci با کد 2 متوقف می‌شود. شناسهٔ تمام‌صفر (نخستین push یک شاخه) با شاخهٔ پیش‌فرض مقایسه می‌شود. هوک Stop در پیام خود فرمان را با --base شروع نشست می‌دهد تا اجرای دستی همان نتیجه را بدهد.

کمبودهای سیستم طراحی (DS-GAP)

وقتی سیستم طراحی پاسخی ندارد، به‌جای راه‌حل موضعی، کمبود ثبت می‌شود:

npx --no parto-ui gap add --kind page-shape --need "status tabs with counts" --where app/alerts/page.tsx
npx --no parto-ui gap report DS-GAP-1

شناسهٔ DS-GAP-<n> در تنها راه‌های مجاز استفاده می‌شود؛ برای قاعدهٔ لینت // eslint-disable-next-line parto/<rule> -- DS-GAP-<n> در خط پیش از خطی که check گزارش می‌دهد، و درون فرزندان JSX {/* eslint-disable-next-line parto/<rule> -- DS-GAP-<n> */}، چون آنجا خطی که با // شروع شود متن است نه توضیح. درون تگی که در چند خط نوشته شده (مثل خروجی Prettier برای فهرست بلند کلاس‌ها)، همان شکل // بین ویژگی‌ها می‌آید، چون هر استثنا فقط خط بعد از خودش را می‌پوشاند و {/* */} آنجا خطای نحوی است. check توضیح غیرفعال‌سازی را مثل ESLint یکجا می‌خواند، حتی اگر فهرست قاعده‌ها به خط بعد برسد؛ نویسه‌های U+2028 و U+2029 و CR تنها (بدون LF) هم یافته‌اند، چون TypeScript و ESLint آن‌ها را شکست خط می‌شمارند و git نمی‌شمارد. بررسی CI تا وقتی یک نفر کمبود را با npx --no parto-ui gap accept DS-GAP-1 تأیید نکند، رد می‌شود. گزارش در همان فایل .parto/ds-gaps.json ذخیره می‌شود؛ آن را از مسیر معمول تیم برای تیم سیستم طراحی بفرستید.

راه‌های مجاز به دامنهٔ اپ بستگی دارند و gap add همان‌ها را با مسیر دقیق چاپ می‌کند. هر فایلی که شناسه را به کار می‌برد باید در --where همان کمبود آمده باشد؛ check ارجاع از فایل دیگر را گزارش می‌کند و دستور افزودن آن فایل را می‌دهد. افزودن فایل تازه به کمبودی که تأیید شده، آن را دوباره به بازبینی برمی‌گرداند. کمبود با npx --no parto-ui gap close DS-GAP-1 بسته می‌شود و هرگز از فایل حذف نمی‌شود؛ check --ci حذف یک مورد را رد می‌کند.

جست‌وجو و راهنما

npx --no parto-ui docs Button، npx --no parto-ui find "date range"، npx --no parto-ui rule <id> و npx --no parto-ui guide اطلاعات همان نسخهٔ نصب‌شده را چاپ می‌کنند. npx --no parto-ui help فهرست فرمان‌ها و npx --no parto-ui version نسخهٔ نصب‌شده را نشان می‌دهد. find نام‌ها، کلیدواژه‌های فارسی و انگلیسی و متن «کی استفاده شود» را جست‌وجو می‌کند، و هر قالب صفحه (ListPage، DetailPage و …) را جدا نشان می‌دهد.