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 导入。