emdash-plugin CLI | EmDash CMS Everything

@emdash-cms/plugin-cli 是創作工具鏈：scaffold、build、watch、validate、bundle、publish，以及身份識別和探索功能。二進位檔案是 emdash-plugin。

指令

CLI 提供以下指令：

emdash-plugin init [name]                    Scaffold a new sandboxed plugin
emdash-plugin build                          Build dist/ (plugin.mjs, manifest.json, index.mjs)
emdash-plugin dev                            Watch sources and rebuild on change
emdash-plugin bundle                         Pack dist/ + assets into a registry tarball
emdash-plugin validate [path]                Validate emdash-plugin.jsonc against the schema
emdash-plugin publish --url <url>            Publish a release pointing at a hosted tarball
emdash-plugin login <handle-or-did>          Sign in with your Atmosphere account
emdash-plugin logout [--did <did>]           Revoke the active session
emdash-plugin whoami                         Show stored sessions
emdash-plugin switch <did>                   Switch the active publisher session
emdash-plugin search <query>                 Free-text registry search
emdash-plugin info <handle-or-did> <slug>    Show package details

非互動式輸出指令（whoami、validate、search、info、login、publish）接受 --json 以獲得機器可讀的輸出。探索指令（search、info）接受 --registry-url <url>（或 EMDASH_REGISTRY_URL）。

以下範例展示了大多數外掛程式新增到 package.json 的兩個指令碼：

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

`init`

使用 init 建立新外掛程式：

npx @emdash-cms/plugin-cli init my-plugin

這會建立一個自包含的外掛程式：emdash-plugin.jsonc、src/plugin.ts（satisfies SandboxedPlugin 形式的一個範例路由）、package.json、tsconfig.json、一個測試、一個 README 和 .gitignore。slug 是唯一必需的輸入。僅從 slug 建立的架構是一個有效的起點：清單包含 TODO: 註解，用於在外掛程式載入或發佈之前填寫的少數欄位——發佈者、作者和安全聯絡人。

`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 排除了它，安裝會重新建置它。

`dev`

監視 src/**、emdash-plugin.jsonc 和 package.json，在 150 毫秒處防抖重建。重建是序列化的。在失敗的重建時，它會保留最後一個良好的 dist/，以便透過工作區/檔案連結匯入外掛程式的站點繼續工作，直到下一次成功建置。Ctrl-C 乾淨退出。

透過在此處執行 pnpm dev 並在站點中執行 pnpm add file:../path/to/this，然後將外掛程式的預設匯出匯入到 emdash({ sandboxed: [...] }) 中，針對真實站點進行開發。

`validate`

emdash-plugin validate          # ./emdash-plugin.jsonc
emdash-plugin validate path/    # a specific directory

使用 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/ 產物——“validate” 意味著 “build first”。

`publish`

CLI 不託管產物；你來託管，在任何公共位置。

emdash-plugin login           # if not already logged in
emdash-plugin bundle          # produces dist/<slug>-<version>.tar.gz
# upload that tarball to a public URL, then:
emdash-plugin publish --url https://your-host/my-plugin-1.0.0.tar.gz

publish 讀取清單中的設定檔欄位並強制執行發佈者固定。在首次發佈時，傳遞 --license 和安全聯絡人（或將它們保留在清單中）。明確標誌覆蓋清單值，這在 CI 中很有用；--no-manifest 完全退出。

完整演練：打包和發佈。

程式化 API

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

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

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