ساخت و انتشار یک Plugin#

یک Plugin از نوع frontend-only، full-stack یا backend-only بسازید، مرزهای بسته، پروتکل، استقرار و manifest آن را صریح نگه دارید، بستهٔ تغییرناپذیر مدیریت‌شده را بارگذاری کنید، بررسی‌های انتشار را اجرا کنید و هر مقصد را برای بازبینی بفرستید. اسکلت از همان CLI عمومی و مسیر Registry استفاده می‌کند که Pluginهای first-party استفاده می‌کنند.

نتیجه#

در پایان خواهید داشت:

• یک نسخهٔ Plugin منتشرشده با artifact مدیریت‌شدهٔ آدرس‌دهی‌شده با SHA-512؛
• یک revision منتشرشدهٔ استقرار بک‌اند برای هر مؤلفهٔ اعلان‌شده؛
• یک بازبینی انسانی مستقلِ تأییدشده برای هر مقصد منجمد؛
• artifact دقیقِ نصب‌شده در یک Environment مصرف‌کنندهٔ مستقل؛
• فعال‌سازی اثبات‌شدهٔ frontend و، در صورت اعلان، action مربوط به بک‌اند توسط یک principal مصرف‌کنندهٔ مستقل.

ارسال به معنای تأیید خودکار نیست. کاتالوگ عمومی نسخه را فقط پس از گذارهای عادی بازبینی و انتشار در Registry نمایش می‌دهد.

انواع پشتیبانی‌شده#

نوع	فرمان scaffold	شکل قرارداد
Frontend-only	alamr create plugin <name>	دست‌کم یک آداپتر frontend؛ بدون مؤلفهٔ بک‌اند
Full-stack	alamr create plugin <name> --kind full-stack --with-backend	دست‌کم یک آداپتر frontend و یک مؤلفهٔ بک‌اند
Backend-only	alamr create plugin <name> --kind backend-only --with-backend	فقط مؤلفه‌های بک‌اند؛ بدون آداپتر frontend یا export مرورگر

دو گزینهٔ --kind full-stack و --with-backend یک جفت صریح‌اند؛ CLI هر یک را بدون دیگری رد می‌کند و پیش‌فرض frontend-only می‌ماند. مسیر پیش‌فرض artifact یک فایل مدیریت‌شدهٔ .tgz بارگذاری می‌کند، پس حساب انتشار npm لازم نیست؛ اگر بسته از قبل روی یک registry عمومی npm است، گزینهٔ --provider npm هم هست.

پیش‌نیازهای ساخت و انتشار#

همهٔ بلوک‌های قابل کپی، فرمان کامل و نسخه‌دار npx @al-amr/cli@0.1.0-alpha.7 را نشان می‌دهند. این نسخه برای مسیر انسانی/CLI آماده است؛ فعال‌شدن Context Pack رسمی Agent به ترفیع Release Set وابسته است.

• نسخه و integrity دقیق CLI عمومی که صفحهٔ شروع اعلام می‌کند؛ فایل package.json تولیدشده package manager انتخاب‌شده را ثبت می‌کند؛ فرمان‌های بعدی پروژه را با همان manager دقیق اجرا کنید؛
• حساب توسعه‌دهندهٔ الامر و دسترسی به Registry مقصد؛
• یک نسخهٔ معنایی دقیق برای بسته و مجوز قابل بازتوزیع؛
• میزبانی عمومی HTTPS برای هر مؤلفهٔ بک‌اند اعلان‌شده (انواع full-stack و backend-only).

گام‌های دقیق#

۱. یک Plugin از نوع frontend-only بسازید#

npx @al-amr/cli@0.1.0-alpha.7 create plugin my-plugin
cd my-plugin
npm install
npx @al-amr/cli@0.1.0-alpha.7 validate --json

src/index.ts تولیدشده یک آداپتر vanilla واقعی است:

export interface ActivateOptions {
  host: HTMLElement;
}

export function activate({ host }: ActivateOptions): () => void {
  const element = document.createElement("div");
  element.textContent = "Hello from an Al-Amr Plugin";
  host.append(element);
  return () => element.remove();
}

تابع cleanup بخشی از قرارداد با میزبان است. متن و رفتار DOM را با قابلیت خودتان جایگزین کنید، اما cleanup صریح را برای listenerها، timerها، socketها، رسانه یا دسترسی به دستگاهی که اضافه می‌کنید نگه دارید.

۲. manifest، بسته و exportها را هم‌تراز نگه دارید#

فیلدهای name، shortDescription، category و documentation را در al-amr.plugin.json برای قابلیت واقعی ویرایش کنید و این ثابت‌ها را حفظ کنید:

مرز	رابطهٔ لازم
نسخه	برابری package.json.version با al-amr.plugin.json.version
مجوز	برابری package.json.license با documentation.license
Export	وجود exportPath هر آداپتر frontend در package.json.exports
Types	وجود هر export نام‌دارِ آداپتر در اعلان TypeScript ساخته‌شده
ترکیب	اشارهٔ هر سطح معناییِ ارائه/مشارکت‌شده به یک export اعلان‌شدهٔ آداپتر
هویت	تخصیص یا همگام‌سازی شناسهٔ Plugin، Publisher و slug در Registry توسط alamr link
بک‌اند	ماندن نشانی‌های زندهٔ استقرار بیرون از manifest پلاگین

فقط مجوزهایی را بخواهید که Plugin به آن‌ها نیاز دارد. platformPermissions قابل اجرا را از نیازمندی‌های مرورگر، disclosureهای داده و شبکه و grantScopes بک‌اند جدا کنید. اگر آداپتر نقطهٔ mount ارائه می‌دهد یا به سطح میزبان UI مشارکت می‌کند، آن را زیر frontendAdapters[].composition اعلان کنید و از شناسه‌های معنایی مانند avatar.overhead استفاده کنید؛ هرگز برای تزریق UI، Plugin دیگری را import نکنید.

۳. پروژهٔ Registry را پیوند کنید#

npx @al-amr/cli@0.1.0-alpha.7 login
npx @al-amr/cli@0.1.0-alpha.7 link
npm install
npx @al-amr/cli@0.1.0-alpha.7 validate --json

وقتی شناسهٔ Project داده نشود، link از طریق Management API عمومی یک پروژهٔ Plugin می‌سازد و pluginId، شناسه و handle مربوط به Publisher و slug را در manifest همگام می‌کند. برای مسیر artifact مدیریت‌شده، نام بستهٔ جایگذارِ تولیدشده را هم به @al-amr-community/{publisher-handle}--{plugin-slug} تغییر می‌دهد. برای پیوند به پروژهٔ موجودِ متعلق به خودتان، شناسهٔ proj_* آن را بدهید. پس از پیوند، documentation.canonicalUrl را به صفحهٔ عمومی پایدار Plugin به‌روز کنید. دومین npm install فرادادهٔ package manager محلی را پس از تغییر نام بستهٔ مدیریت‌شده توسط link همگام می‌کند.

۴. بسته را بسازید و بازرسی کنید#

npm run typecheck
npm run build
npm run test:pack
npx @al-amr/cli@0.1.0-alpha.7 inspect --json
npx @al-amr/cli@0.1.0-alpha.7 validate --json

فرمان build فایل‌های dist/index.js و dist/index.d.ts را تولید می‌کند. فرمان test:pack یک اجرای آزمایشی npm pack و publint را اجرا می‌کند. اعتبارسنجی، schemaهای manifest، هویت بسته، مجوز، اسکریپت‌های چرخهٔ حیات، مشخصات وابستگی، فایل‌های استقرار و exportهای آداپتر را بررسی می‌کند. تا وقتی همهٔ فرمان‌ها کد خروج 0 ندهند ادامه ندهید.

۵. نسخهٔ تغییرناپذیر را بسازید و بررسی‌ها را اجرا کنید#

npx @al-amr/cli@0.1.0-alpha.7 test --json --visibility unlisted --channel preview

برای Plugin از نوع frontend، مسیر پیش‌فرضِ مدیریت‌شده بستهٔ محلی را pack می‌کند، نسخهٔ دقیق Plugin را می‌سازد یا دوباره استفاده می‌کند، بسته را از مرز artifact مدیریت‌شده بارگذاری می‌کند، اندازه و integrity با SHA-512 بازگردانده‌شده را بررسی می‌کند، درخواست انتشار را می‌سازد یا دوباره استفاده می‌کند و بررسی‌های انتشار را اجرا می‌کند. تکرار test نسخهٔ موجود را فقط وقتی دوباره استفاده می‌کند که محتوای manifest و بسته هنوز مطابق باشد؛ در غیر این صورت نسخهٔ معنایی را در هر دو فایل al-amr.plugin.json و package.json بالا ببرید. CLI جایگزینی محتوای تغییرناپذیر زیر یک نسخهٔ موجود Plugin را رد می‌کند.

۶. برای بازبینی ارسال کنید#

npx @al-amr/cli@0.1.0-alpha.7 publish --json --yes
npx @al-amr/cli@0.1.0-alpha.7 status --json

ارسال آمادهٔ frontend-only پیام Publication submission sent for review. را گزارش می‌کند. بررسی‌ها، بازبینی انسانی و انتشار همچنان گذارهای جداگانه‌اند. پس از انتشار، یک Environment می‌تواند نسخهٔ دقیق را بازرسی و نصب کند:

npx @al-amr/cli@0.1.0-alpha.7 inspect publisher-handle/plugin-slug --json
npx @al-amr/cli@0.1.0-alpha.7 add publisher-handle/plugin-slug --adapter default --yes

۷. انواع full-stack یا backend-only را بسازید#

وقتی Plugin هم به کد مرورگر و هم به سرویس میزبانی‌شدهٔ ناشر نیاز دارد، از پروژهٔ آغازین رسمی full-stack استفاده کنید:

npx @al-amr/cli@0.1.0-alpha.7 create plugin my-service --kind full-stack --with-backend
cd my-service
npm install
npm run validate -- --json
npm run typecheck
npm run build
npm run test:pack

برای قابلیت فقط-سرویسی بدون export مرورگر، از پروژهٔ آغازین رسمی backend-only استفاده کنید:

npx @al-amr/cli@0.1.0-alpha.7 create plugin my-service --kind backend-only --with-backend
cd my-service
npm install
npm run validate -- --json
npm run typecheck
npm run build
npm run test:pack

پروژهٔ مستقلِ تولیدشده هیچ وابستگی workspace:*، فایل محلی یا Git ندارد. هر نسخهٔ تازه با مؤلفهٔ بک‌اند باید به آن مؤلفه یک protocolArtifactId بدهد؛ پروژهٔ آغازین رسمی HTTPS فایل protocol/service.openapi.json را تولید و چکیدهٔ SHA-256 آن را pin می‌کند. Registry بایت‌های واقعی بسته‌بندی‌شده را هنگام بررسی‌ها و دوباره پیش از انتشار اعتبارسنجی می‌کند؛ فراداده به‌تنهایی اثبات پروتکل نیست.

۸. بک‌اند را میزبانی و مجموعهٔ مقصدها را ارسال کنید#

پس از alamr link، دایرکتوری packages/backend را از طریق HTTPS میزبانی کنید. متغیر AL_AMR_PLUGIN_DEPLOYMENT_ID را در پلتفرم میزبانی به مقدار dep_* صدورشدهٔ Registry تنظیم کنید؛ این هویت عمومی است، نه راز. نشانی endpoint و سلامت را در al-amr.deployments.json به‌روز کنید و سپس اجرا کنید:

npx @al-amr/cli@0.1.0-alpha.7 validate --json
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 --json --yes
npx @al-amr/cli@0.1.0-alpha.7 status --json

نسخهٔ Plugin و هر revision استقرار بک‌اند، درخواست‌های تغییرناپذیر و جداگانه‌ای هستند که مستقل بررسی می‌شوند. alamr publish کل مجموعهٔ محلی را preflight و موارد آماده را به‌صورت قابل‌ازسرگیری ارسال می‌کند؛ مجموعهٔ نیمه‌کاره با اجرای مجدد alamr publish پس از alamr status --json ادامه می‌یابد و فقط مقصدهای ready_for_review باقی‌مانده ارسال می‌شوند. پیکربندی زندهٔ endpoint فقط در al-amr.deployments.json جای دارد، هرگز در نسخهٔ Plugin، و فیلد config عمومی استقرار فرادادهٔ بازبینی‌شده است، نه محل نگه‌داشتن راز.

۹. نصب مصرف‌کننده را اثبات کنید#

پس از انتشار، نسخهٔ دقیق را در یک Environment مصرف‌کنندهٔ جداگانه نصب کنید که از همان حساب مالک منتشر نمی‌کنید، و دقیقاً یک حالت یکپارچه‌سازی را انتخاب کنید:

# Import and run the reviewed browser adapter. A full-stack release also makes
# that same release's backend components eligible for Plugin Grants.
npx @al-amr/cli@0.1.0-alpha.7 add publisher-handle/plugin-slug@1.2.3 \
  --integration frontend-adapter --adapter default --yes

# Authorize the reviewed backend-component set without adding a browser package.
npx @al-amr/cli@0.1.0-alpha.7 add publisher-handle/plugin-slug@1.2.3 \
  --integration backend-components --yes

Journey نوشتاری سپس اثبات مصرف‌کننده را بررسی می‌کند: lock نصب (ALAMR_PLUGIN_CONSUMER_INSTALL_MISSING)، فعال‌سازی frontend (ALAMR_PLUGIN_FRONTEND_ACTIVATION_MISSING)، action مربوط به بک‌اند در صورت اعلان (ALAMR_PLUGIN_BACKEND_ACTION_MISSING)، انتشار Environment مصرف‌کننده (ALAMR_PLUGIN_CONSUMER_ENVIRONMENT_PUBLICATION_MISSING) و استقلال principal مصرف‌کننده از مالک ناشر (ALAMR_PLUGIN_CONSUMER_PRINCIPAL_NOT_INDEPENDENT).

فایل‌ها و قراردادهای عمومی#

• al-amr.plugin.json — manifest مربوط به Plugin؛ schema در مرجع manifest آمده است؛
• package.json — نسخه، مجوز و exportهای هم‌تراز با manifest؛
• dist/index.js و dist/index.d.ts — entry ساخته‌شدهٔ آداپتر و اعلان نوع آن؛
• al-amr.deployments.json — نشانی‌های زندهٔ endpoint و سلامت، یک ورودی برای هر مؤلفهٔ بک‌اند اعلان‌شده؛
• protocol/service.openapi.json — بایت‌های تغییرناپذیر پروتکل که protocolArtifactId به آن‌ها اشاره می‌کند؛
• manifest.json، integration.md و types.d.ts — سطوح بازبینی تغییرناپذیری که هنگام انتشار از manifest برآورده می‌شوند؛
• al-amr.lock.json نسخهٔ ۳ — رکورد نصب در سمت Environment: ورودی‌های frontend artifact بسته و integrity با SHA-512 را نگه می‌دارند؛ ورودی‌های backend-component هیچ آداپتر، بسته یا integrity ندارند.

دروازه‌های انسانی#

دروازه	عامل	چه چیزی تأیید می‌شود
handoff مرورگر یا دستگاه در alamr login	مالک انسانی حساب	کد دستگاه و نشانی دقیقِ نمایش‌داده‌شده
alamr link	مالک پروژه	پیوند این دایرکتوری به Project دقیق در Registry
alamr publish --yes	مالک پروژه	ارسال چکیده‌های دقیق نسخه و استقرارها به‌عنوان یک مجموعهٔ آماده
تصمیم بازبینی	یک بازبین انسانی مستقل	شواهد منجمد هر مقصد؛ مالک و ارسال‌کننده نمی‌توانند خودبازبینی کنند
گذار انتشار	یک مدیر انتشار مستقل	چکیده‌های دقیق تأییدشده برای هر مقصد؛ بازبین نمی‌تواند منتشر کند
نصب مصرف‌کننده	مالک Environment مصرف‌کننده	تأیید اعتماد (--yes) برای artifact دقیقِ بازبینی‌شده و disclosureهای آن

خروجی‌های ساختاریافتهٔ مورد انتظار#

فرمان	شواهد موفقیت
alamr validate --json	کد خروج 0، مقدار ok: true و پیام اعتبار manifest
alamr test --json	پیام Publication checks completed. با نسخه، فراهم‌کنندهٔ artifact، درخواست و نتیجهٔ بررسی
alamr publish --json --yes	پیام Publication submission sent for review. برای هر مقصد آماده در مجموعه
alamr status --json	پروژه، مقصدهای تغییرناپذیرِ پیوندشده و رکوردهای فعلی انتشار
alamr inspect <spec> --json	کارت عمومی، manifest دقیق، نسخه‌ها، artifactها و نشانی راهنمای integration

خطاهای پایدار و رفع آن‌ها#

کد	معنی	قابل تلاش مجدد؟	رفع
ALAMR_USAGE	آرگومان یا گزینهٔ نامعتبر	خیر	alamr --help را اجرا و فراخوانی را اصلاح کنید
ALAMR_AUTH_REQUIRED	اعتبارنامهٔ گمشده یا منقضی	خیر	alamr login را اجرا کنید یا توکن پروژهٔ scopeدار بدهید
ALAMR_NETWORK_ERROR	Registry در دسترس نیست	بله	DNS/TLS/proxy و سلامت Registry را بررسی و دوباره تلاش کنید
ALAMR_CONFLICT	نسخه با محتوای متفاوت وجود دارد یا وضعیت تغییر کرده است	خیر	برای محتوای تغییریافته نسخهٔ معنایی را بالا ببرید؛ در غیر این صورت نخست alamr status --json را بخوانید
submission_not_ready	یک مقصد در مجموعه در وضعیت ready_for_review نیست	خیر	برای هر مقصد مشکل را رفع و alamr test را دوباره اجرا کنید؛ فقط مجموعهٔ آمادهٔ سازگار را ارسال کنید
artifact_snapshot_changed	شواهد artifact منجمد دیگر مطابق نیست	خیر	توقف کنید؛ هرگز چکیده را بازنویسی نکنید — نسخهٔ تغییرناپذیرِ تازه بسازید
backend_protocol_reference_missing	یک مؤلفهٔ بک‌اند protocolArtifactId ندارد	خیر	هر مؤلفه را به artifact اعلان‌شدهٔ OpenAPI/AsyncAPI از نوع مطابق متصل کنید
backend_protocol_artifact_bytes_missing	بایت‌های پروتکل ارجاع‌شده در بسته نیست	خیر	مسیر دقیق پروتکل را بسته‌بندی کنید؛ اعلان manifest به‌تنهایی شواهد قابل انتشار نیست
backend_protocol_artifact_digest_mismatch	بایت‌های بسته‌بندی‌شده با SHA-256 اعلان‌شده فرق دارند	خیر	چکیده را از بایت‌های دقیق بسته‌بندی‌شده بازتولید کنید، نسخهٔ معنایی را بالا ببرید و نسخهٔ تازه را تست کنید

فهرست کامل کدهای پایدار در عیب‌یابی آمده است.

تعریف «تمام‌شده»#

• نسخهٔ دقیق Plugin و هر revision استقرار بک‌اند از گذارهای مستقل بازبینی و انتشار گذشته‌اند.
• انتشار، manifest.json، integration.md، types.d.ts تغییرناپذیر و صفحهٔ نسخه در Developer Portal را از manifest بازبینی‌شده برآورده است.
• artifact دقیق در یک Environment مصرف‌کنندهٔ مستقل با یک حالت یکپارچه‌سازیِ انتخاب‌شده نصب شده و آن Environment منتشر شده است.
• فعال‌سازی frontend و، در صورت اعلان، action مربوط به بک‌اند توسط یک principal مصرف‌کنندهٔ مستقل اثبات شده است.
• بسته، manifest، تنظیمات و config استقرار هیچ credential، کلید امضا، توکن دسترسی یا مقدار خصوصی استقرار ندارند.
• نیازمندی‌های مرورگر، مبداهای شبکه، دادهٔ جمع‌آوری یا به‌اشتراک‌گذاشته‌شده و نگه‌داری به‌صداقت اعلان شده‌اند و هر منبع طولانی‌عمر cleanup دارد.

پاک‌سازی و بازیابی#

• کد frontend پلاگین در نسخهٔ v0.x کد trusted_library در realm جاوااسکریپتِ Environment میزبان است؛ رکورد معتبر integrity و بازبینی، بایت‌ها و disclosureهای بازبینی‌شده را مشخص می‌کند — sandbox جاوااسکریپتی ایجاد نمی‌کند.
• تعارض نسخه یعنی محتوا زیر یک نسخهٔ معنایی موجود تغییر کرده است: نسخهٔ معنایی را در هر دو فایل al-amr.plugin.json و package.json بالا ببرید، دوباره بسازید و یک نسخهٔ تغییرناپذیرِ تازه را تست کنید؛ هرگز محتوای تغییرناپذیر را بازنویسی نکنید.
• وضعیت checks_failed با alamr test درجا دوباره اجرا می‌شود؛ CLI فقط برای تلاش مجدد بررسی‌ها، نسخهٔ تکراری نمی‌سازد.
• رد شدن تصمیم و تاریخچه‌ای تغییرناپذیر باقی می‌گذارد. اگر release و snapshot منجمد artifact دقیقاً بدون تغییرند، alamr test و alamr publish را دوباره اجرا کنید؛ Registry می‌تواند همان درخواست منطبق را در draft باز کند بی‌آنکه تصمیم قبلی پاک شود. محتوای تغییرکرده به release تازه و افزایش SemVer در هر دو فایل al-amr.plugin.json و package.json نیاز دارد.
• مجموعهٔ ارسالِ full-stack نیمه‌کاره قابل ازسرگیری است: alamr status --json را اجرا و alamr publish را دوباره اجرا کنید؛ مقصدهای از‌پیش‌ارسال‌شده بدون تغییر می‌مانند.
• نسخهٔ yank‌شده برای نصب‌های موجودِ قفل‌شده با integrity همچنان قابل بازتولید است، اما alamr add نصب تازهٔ آن را رد می‌کند.

روش‌های بازیابی برای هر وضعیت انتشار در بازیابی و ماشین وضعیت کامل در چرخهٔ انتشار آمده است. برای نصب این نسخه در یک Environment، افزودن Plugin را دنبال کنید.