شروع ساخت

ساخت Plugin

قابلیت نسخه‌داری که یک محیط نصب می‌کند. می‌تواند فرانت‌اند، بک‌اند یا هر دو را داشته باشد و باید در یک محیط مصرف‌کنندهٔ مستقل اثبات شود.

نتیجه و حالت‌های قابل ساخت

در پایان یک Plugin release منتشرشده دارید که exact artifact آن در یک Environment مستقل نصب و رفتار frontend/backend آن اثبات شده است.

frontend-only: آداپتر مرورگرِ trusted_library که داخل realm Environment اجرا می‌شود
full-stack: همان آداپتر به‌همراه BackendComponentهای بازبینی‌شده
backend-only: capability سرویسی بدون package قابل import در مرورگر

جزئیات، نمونه‌ها و قراردادهای کامل: راهنمای انسانی این محصول

پیش‌نیازهای داده‌محور

وضعیت: مسیر CLI آماده؛ گواهی Agent در انتظار
زمان تقریبی: ساخت اولیه: حدود ۱۰ دقیقه (وابسته به پروژه)
CLI دقیق: npx @al-amr/cli@0.1.0-alpha.7

می‌توانید همین حالا پروژه را با CLI عمومی بسازید و تا ارسال به بازبینی جلو بروید. این وضعیت به معنی فعال‌بودن Agent index و Context Pack رسمی نیست؛ آن دو پس از ترفیع Release Set فعال می‌شوند. زمان بالا فقط برای ساخت اولیه است، نه میزبانی و بازبینی نهایی.

شروع با AI

این دکمه یک پرامپت کامل با فرمان نسخه‌دار، راهنمای انسانی و توقف‌های اجباری کپی می‌کند. Agent باید بداند Context Pack رسمی هنوز گواهی نشده است و نباید آن را فعال فرض کند.

شروع دستی

npx @al-amr/cli@0.1.0-alpha.7 create plugin my-plugin --yes --json

فایل‌ها و ساختار پروژهٔ ایجادشده

al-amr.plugin.json — آداپترها، composition، permissionها، disclosureها و BackendComponentها
package.json و dist/index.js + dist/index.d.ts — package و export دقیق هم‌نسخه با manifest
integration.md — قرارداد تغییرناپذیر نصب، mount، cleanup و استفاده برای مصرف‌کننده
al-amr.deployments.json — endpointهای زندهٔ backend؛ رازها و protocol bytes داخل آن نیستند
protocol/service.openapi.json — بایت پروتکل pin‌شده برای backend و al-amr.lock.json v3 در Environment مصرف‌کننده

جزئیات، نمونه‌ها و قراردادهای کامل: راهنمای انسانی این محصول

تعریف Done محلی

ابتدا package manager ثبت‌شده در package.json پروژه را برای نصب dependencyها و اجرای scriptهای typecheck،build و test به‌کار ببر؛ از وجود یک manager سراسری حدس نزن.

Verifynpx @al-amr/cli@0.1.0-alpha.7 validate --cwd my-plugin --json

manifest و package version یکسان، build و test:pack موفق و package از dist قابل مصرف است.
هر adapter و composition surface در manifest، کد، type declaration و integration.md یکسان است.
permission، data/network disclosure، cleanup و optional backend grant scope دقیق و حداقلی‌اند.
هیچ Plugin دیگری یا Hub-only component برای mount شدن import نشده است.

اتصال حساب و پروژه

در همان دایرکتوری پروژه، device login را آغاز کن و کد و URL را به مالک انسانی نشان بده.
پس از تأیید انسانی، فقط resumeCommand برگشتی را اجرا کن؛ کد دستگاه را حدس یا بازتولید نکن.
پروژه را link کن؛ Registry شناسهٔ پایدار asset و Project را صادر و manifest را همگام می‌کند.
با status مالکیت، target و allowedActions را بخوان؛ Console و CLI از همان Management API استفاده می‌کنند.

npx @al-amr/cli@0.1.0-alpha.7 login --device --json
# سپس resumeCommand دقیق خروجی را اجرا کن
npx @al-amr/cli@0.1.0-alpha.7 link --yes --json
npx @al-amr/cli@0.1.0-alpha.7 status --json --non-interactive

حساب، نقش‌ها، انتقال مالکیت و tokenهای CI در راهنمای حساب و پروژه توضیح داده شده‌اند.

میزبانی یا نیازمندی‌های artifact

مسیر پیش‌فرض artifact مدیریت‌شده، tarball محلی را pack و در Managed Store محتواآدرس بارگذاری می‌کند.
در provider npm، Registry نسخه و SHA-512 را از npm resolve و همان بایت‌ها را mirror می‌کند؛ dist-tag مدرک نسخه نیست.
BackendComponent را ناشر روی HTTPS deploy می‌کند و deploymentId عمومی را تنظیم می‌کند؛ secret فقط در host می‌ماند.

تست و ارسال برای بازبینی

build و test:pack را کامل کن، سپس alamr test نسخهٔ دقیق package و مقصدهای backend اعلان‌شده را بررسی می‌کند.
برای نخستین ارسال از visibility=unlisted و channel=preview استفاده کن.
alamr publish تمام targetهای آماده را ارسال می‌کند؛ برای ادامهٔ مجموعهٔ نیمه‌کاره دوباره همان publish را اجرا کن.
status و allowedActions برگشتی Registry را نگه دار؛ نسخه یا digest منتشرشده را بازنویسی نکن.

npx @al-amr/cli@0.1.0-alpha.7 test --json --visibility unlisted --channel preview
npx @al-amr/cli@0.1.0-alpha.7 publish --yes --json
npx @al-amr/cli@0.1.0-alpha.7 status --json --non-interactive

ماشین وضعیت و digestها: چرخهٔ انتشار

بازبینی انسانی

Plugin release و هر backend deployment مقصدهای تغییرناپذیر جدا با review مستقل‌اند.
بازبین package bytes، lifecycle scripts، dependencyها، permission/disclosure، protocol artifact و endpoint سلامت را بازرسی می‌کند.
کد frontend در v0.x sandbox جاوااسکریپتی نیست؛ consumer باید trust و artifact دقیق را آگاهانه تأیید کند.

بازبین باید از حساب مستقل، inspection تازه و snapshot/artifact digest دقیق استفاده کند؛ راهنمای کامل در بازبینی انسانی است.

انتشار و اثبات مصرف

همهٔ مقصدهای full-stack باید آماده و تأیید شوند؛ alamr publish مجموعهٔ نیمه‌کاره را بدون تکرار مقصدهای ارسال‌شده resume می‌کند.
پس از publication، یک Environment مستقل exact version را inspect، preflight، add و package install می‌کند.
تعریف Done شامل mount/activation واقعی frontend، action واقعی backend در صورت اعلان و publication Environment مصرف‌کننده است.

خطاهای رایج با کد پایدار و رفع خطا

خطاها با کد پایدار در مرجع خطاها و شرح گام‌های این محصول در راهنمای انسانی آمده است.

ادامه و پاک‌سازی

تغییر bytes زیر نسخهٔ موجود ممنوع است؛ manifest و package را با هم version bump کن و release تازه بساز.
checks_failed را روی همان target اصلاح و rerun کن؛ rejection نهایی است و submission تازه می‌خواهد.
release yanked برای lock موجود قابل بازتولید می‌ماند، ولی نصب تازه نباید آن را انتخاب کند.

از روی status و کد پایدار ادامه بده: راهنمای بازیابی. برای خطای ناشناخته ابتدا JSON همان شکست را بدون حذف diagnosticها حفظ کن.