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