`emdash-plugin` CLI | EmDash CMS Everything

@emdash-cms/plugin-cli 用於搭建、建置、驗證與發佈沙盒外掛。它也管理發佈者登入、套件設定檔、登錄檔探索以及自動化發佈。安裝後的二進位檔案名稱為 emdash-plugin。

該 CLI 使用 Atmosphere 帳戶作為套件設定檔與發佈的發佈者身分。

安裝 CLI

透過 pnpm dlx @emdash-cms/plugin-cli init 建立的外掛已包含 CLI 作為固定的開發相依性。在使用其他指令之前,將其加入到現有外掛中：

pnpm add -D @emdash-cms/plugin-cli

範例使用 pnpm exec emdash-plugin，這樣每個指令都會執行外掛中安裝的版本。對於一次性的 init 指令使用 pnpm dlx，而不是重複的建置、登入或發佈指令。

指令

CLI 提供以下指令：

emdash-plugin init [name]                    搭建新的沙盒外掛
emdash-plugin build                          建置 dist/ (plugin.mjs, manifest.json, index.mjs)
emdash-plugin dev                            監視原始碼並在變更時重新建置
emdash-plugin bundle                         將 dist/ + 資源打包成登錄檔 tarball
emdash-plugin validate [path]                根據架構驗證 emdash-plugin.jsonc
emdash-plugin publish                        建置、上傳並發佈版本
emdash-plugin update-package [--yes]         預覽或套用套件設定檔變更
emdash-plugin profile setup                  為委派發佈準備已簽署的套件設定檔
emdash-plugin release setup                  建立委派發佈 GitHub Actions 工作流程
emdash-plugin release plan                   為 GitHub Actions 規劃儲存庫發佈
emdash-plugin release prepare <slug[@ver]>   為 GitHub Actions 準備一個儲存庫套件
emdash-plugin login <handle-or-did>          使用 Atmosphere 帳戶登入
emdash-plugin logout [--did <did>]           撤銷活動工作階段
emdash-plugin whoami                         顯示儲存的工作階段
emdash-plugin switch <did>                   切換活動的發佈者工作階段
emdash-plugin search <query>                 登錄檔自由文字搜尋
emdash-plugin info <handle-or-did> <slug>    顯示套件詳情或清單檢查狀態

執行 emdash-plugin <command> --help 查看目前參數和旗標。用於指令碼的指令（包括 validate、publish、update-package、search、info、login 和 whoami）在其說明中列出 --json 時提供 JSON 輸出。探索指令接受 --registry-url <url> 或 EMDASH_REGISTRY_URL 環境變數。

人類可讀的輸出將登錄檔套件標識為 @<publisher-handle>/<slug>。當建置診斷需要顯示 npm 套件名稱時，會標記為 npm package。

以下範例顯示了大多數外掛加入到 package.json 的兩個指令碼：

{
	"scripts": {
		"build": "emdash-plugin build",
		"dev": "emdash-plugin dev"
	}
}

`init`

使用 init 建立新外掛：

pnpm dlx @emdash-cms/plugin-cli init my-plugin

這會搭建 emdash-plugin.jsonc、src/plugin.ts、package.json、tsconfig.json、vitest.config.ts、基於 workerd 的測試、README、AGENTS.md、本地 creating-plugins 技能以及套件管理器設定。.agents/skills 和 .claude/skills 連結到規範的 skills 目錄，.claude/CLAUDE.md 連結到 AGENTS.md，因此 Codex 和 Claude 使用相同的專案指導。原始碼從指派給 SandboxedPlugin 類型常數並作為預設匯出的一個路由開始。測試透過 EmDash 的生產沙盒包裝器和主機橋接呼叫該路由。

互動式設定會詢問發佈者、作者、安全聯絡人和來源儲存庫，然後在寫入之前顯示完整的專案摘要。必填欄位不能跳過。

CLI 偵測是 npm、pnpm、Yarn 還是 Bun 啟動了它，並產生相符的指令。使用 --package-manager 覆寫選擇。pnpm 鷹架包含 esbuild 所需的經過審查的建置指令碼策略。

非互動式設定需要明確的所有權中繼資料。在指令碼中使用以下形式：

pnpm dlx @emdash-cms/plugin-cli init my-plugin --yes \
  --publisher did:plc:abc123def456 \
  --author-name "Jane Doe" \
  --security-email security@example.com

傳遞 --use-detected 以選擇使用活動的發佈者工作階段和本地 Git 作者或儲存庫中繼資料。如果沒有該旗標，--yes 不會複製包含身分的本地預設值。

`build`

build 讀取 emdash-plugin.jsonc、src/plugin.ts 和可選的同級 package.json，並輸出以下檔案：

構件	內容
`dist/plugin.mjs` (+ `dist/plugin.d.mts`)	掛鉤和路由。由行程內 (`plugins: []`) 和沙盒載入器 (`sandboxed: []`) 載入。
`dist/manifest.json`	外掛的清單，包括從 `src/plugin.ts` 讀取的掛鉤和路由。`bundle` 按原樣包含此檔案；npm 使用者無需解析 JSONC 來源即可讀取。
`dist/index.mjs` (+ `dist/index.d.mts`)	站點在 `astro.config.mjs` 中匯入的描述符模組。僅當存在同級 `package.json` 時才輸出；僅登錄檔的外掛會跳過它，因為沒有任何東西匯入它。

dist/ 是建置輸出。不要提交它。鷹架的 .gitignore 將其排除。在打包或發佈 npm 套件之前執行 emdash-plugin build，以便其 files 清單包含要包含的產生構件。

`dev`

監視 src/**、emdash-plugin.jsonc 和 package.json，以 150 毫秒去彈跳重建。重建是序列化的。在失敗的重建中，它會保留最後一個良好的 dist/，因此透過工作區/檔案連結匯入外掛的站點會繼續工作，直到下一次成功建置。Ctrl-C 乾淨地排空。

透過在外掛目錄中執行 pnpm dev 並使用 pnpm add file:../path/to/plugin 將其安裝到站點中，針對真實站點進行開發。將外掛的預設匯出匯入到 emdash({ sandboxed: [...] })。第一個外掛教學顯示了完整的設定。

`validate`

驗證目前目錄中的清單，或傳遞不同的外掛目錄：

emdash-plugin validate          # ./emdash-plugin.jsonc
emdash-plugin validate path/    # 特定目錄

使用 tsc 風格的 file:line:column 診斷進行離線架構檢查，包括清單的跨欄位規則。無需網路。適合作為預提交或 CI 閘道。請參閱清單參考。

`bundle`

bundle 是在 build 之上的一個薄包裝步驟：

執行 build 以產生 dist/。
驗證套件：沒有 Node 內建匯入，沒有超大檔案，功能健全性檢查。
收集可選資源 - README、圖示、截圖。
打包 tarball。在 tarball 內部，plugin.mjs 被打包為 backend.js（登錄檔期望的檔案名稱）。輸出為 dist/<slug>-<version>.tar.gz。

--validate-only 跳過 tarball 建立，但仍會產生 dist/ 構件 —— “驗證”意味著”先建置”。

`publish`

publish 建置並驗證外掛，將套件和清單影像上傳到您的 PDS，然後寫入發佈記錄。

emdash-plugin login alice.example.com
emdash-plugin publish

publish 讀取清單中的設定檔欄位並強制執行發佈者鎖定。將授權、作者、安全聯絡人和其他套件資訊保留在清單中。舊的設定檔旗標和 --no-manifest 仍可用於傳統指令碼發佈；在維護其中一個流程之前檢查 publish --help。

傳遞 --url <https-url> 以使用外部託管的套件捆綁包。CLI 在發佈之前下載並驗證 URL。新增 --local <path> 以驗證本地 tarball 是否與下載的位元組相符。

有關完整的本地發佈流程，請參閱捆綁和發佈。

`info`

info 顯示來自聚合器的已批准套件詳細資訊。發佈後，傳遞發佈版本和 --watch 以追蹤目前設定檔和發佈清單檢查：

emdash-plugin info plugins.emdashcms.com audit-log --version 0.2.2 --watch

在批准之前，該指令直接從標籤器讀取狀態，並僅列印套件識別符和檢查狀態。它不會從聚合器傳回未批准的套件中繼資料。一旦套件和發佈公開，它會列印已批准的詳細資訊和規範的外掛頁面 URL。使用 Ctrl-C 停止監視不會影響已發佈的記錄或清單檢查。

檢查使用不同標籤器的登錄檔時，使用 --labeler-url <origin> 或 EMDASH_LABELER_URL。

`update-package`

使用 update-package 在不建立發佈的情況下變更現有套件設定檔。它讀取 emdash-plugin.jsonc 中的設定檔欄位，取得目前已簽署的設定檔，並列印建議的變更：

emdash-plugin update-package

除非您傳遞 --yes，否則該指令是試執行：

emdash-plugin update-package --yes

寫入使用目前記錄 CID 作為前提條件。如果另一個程序在指令讀取設定檔後變更了設定檔，則更新將失敗並顯示 STALE_RECORD，而不是覆寫較新的記錄。從清單中移除可選屬性會使其已發佈的值保持不變；明確設定預期的替換。

`profile setup`

profile setup 為自動發佈準備發佈者擁有的套件設定檔。它從 emdash-plugin.jsonc 建立缺少的設定檔，或在不替換其套件中繼資料的情況下將委派發佈設定新增到現有有效設定檔。

從外掛目錄執行互動式設定。從 monorepo 中的其他位置傳遞 --dir <plugin-directory>：

emdash-plugin profile setup

旗標	預設值	描述
`--dir <path>`	目前目錄	外掛來源目錄。
`--repository <url>`	清單 `repo`，然後是 Git `origin`	規範的公共 GitHub 儲存庫 URL。互動式設定預填偵測到的 GitHub 遠端，或在沒有可用時詢問。
`--provenance <mode>`	`required`	對於來源支援的發佈使用 `required`，或使用 `optional` 允許沒有來源的本地發佈。互動式設定會詢問。
`--confirmation <mode>`	`escalation-only`	對於權限增加使用 `escalation-only`，對於每個發佈使用 `always`。
`--yes`, `-y`	`false`	接受預設策略而不提示。當非互動式執行會變更設定檔時需要。

該指令使用活動的 CLI 登入來寫入設定檔。它拒絕替換不同的已簽署儲存庫。使用 --provenance required|optional 重新執行它以變更已簽署的來源策略，同時保留儲存庫、批准者和套件中繼資料。當活動帳戶與清單發佈者不符時，執行 emdash-plugin switch <did>。對於來源支援的發佈，在發佈設定檔後執行 emdash-plugin release setup。

`release setup`

release setup 從一個外掛目錄執行套件設定檔設定，然後在 Git 儲存庫根目錄建立一個共用的 .github/workflows/emdash-release.yml。巢狀的外掛套件重用相同的工作流程。從外掛目錄執行它或傳遞 --dir <plugin-directory>；儲存庫根目錄不會標識要準備哪個套件設定檔。

emdash-plugin release setup

它接受 profile setup 旗標以及以下工作流程選項：

旗標	預設值	描述
`--service-url <origin>`	`https://releases.emdashcms.com`	產生的 Action 使用的 HTTPS 來源。
`--action-ref <ref>`	`main`	包含發佈 Action 的 EmDash 儲存庫 ref。
`--trigger <mode>`	`auto`	發佈來源：`changesets`、`tags` 或 `manual`。當 `.changeset/config.json` 存在時，`auto` 提供 Changesets。
`--force`	`false`	替換現有的產生工作流程。沒有它，設定會保持現有檔案不變。

當設定在互動式終端機中偵測到 Changesets 時，它會詢問如何發佈 EmDash 外掛。遵循 Changesets 發佈為包含 emdash-plugin.jsonc 的套件發佈相同的版本。其他選擇遵循 <slug>@<version> 標籤或僅允許手動執行。在非互動式使用中，當存在有效的根設定時，auto 選擇 Changesets，否則選擇套件標籤。

Changesets 變體是可重用的工作流程。在現有 Changesets 發佈作業之後新增一個呼叫者作業，並傳遞其官方的已發佈套件 JSON 輸出。私有的僅 EmDash 套件需要 privatePackages.version: true 和 privatePackages.tag: true；當缺少任一選項時，設定會發出警告。

該指令永遠不會推送產生的工作流程。第一次自動執行使用 GitHub OpenID Connect 建立儲存庫連線請求；不需要 Actions 密鑰。請參閱自動化外掛發佈以檢視工作流程、授權發佈服務、連線儲存庫並發佈第一個發佈。

`release plan`

release plan 由產生的工作流程使用。使用 --published-packages <json>，它將 Changesets Action 輸出對應到包含 emdash-plugin.jsonc 的套件，驗證其版本，並將 JSON 選擇器矩陣寫入 GITHUB_OUTPUT。使用 --package <slug[@version]>，它驗證一個手動選擇器。該指令不建置或發佈套件。

`release prepare`

release prepare 是產生工作流程的套件解析器。它在儲存庫中找到一個外掛清單，檢查可選的標籤版本，建置套件，並將其套件、發佈者、目錄和捆綁輸出寫入 GITHUB_OUTPUT。

產生的工作流程自動傳遞套件標籤：

emdash-plugin release prepare gallery@1.2.3

對於手動工作流程執行，傳遞普通外掛 ID。該指令使用該套件清單中的版本。重複的外掛 ID、缺少的套件和版本不符在建立來源之前失敗。

程式化 API

透過匯入 CLI 的程式化函式從 Node.js 建置或捆綁外掛：

import { buildPlugin, bundlePlugin } from "@emdash-cms/plugin-cli";

await buildPlugin({ dir: "./my-plugin" });
const result = await bundlePlugin({ dir: "./my-plugin" });

對於探索和憑證協助程式，從 @emdash-cms/registry-client 匯入。