`emdash-plugin` CLI

@emdash-cms/plugin-cli は、サンドボックス化されたプラグインのスキャフォールド、ビルド、検証、公開を行います。また、パブリッシャーのサインイン、パッケージプロファイル、レジストリ探索、自動化されたリリースも管理します。インストールされるバイナリ名は emdash-plugin です。

この CLI は、パッケージプロファイルとリリースのパブリッシャー ID として Atmosphere アカウントを使用します。

CLI のインストール

pnpm dlx @emdash-cms/plugin-cli init で作成されたプラグインには、すでに固定された開発依存関係として CLI が含まれています。他のコマンドを使用する前に、既存のプラグインに追加します：

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

例では pnpm exec emdash-plugin を使用しているため、各コマンドはプラグインにインストールされたバージョンを実行します。繰り返しのビルド、ログイン、またはリリースコマンドではなく、1 回限りの 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 用の 1 つのリポジトリパッケージを準備
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 に追加する 2 つのスクリプトを示しています：

{
	"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 型の定数に割り当てられ、デフォルトとしてエクスポートされる 1 つのルートから始まります。テストは、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

アクティブなパブリッシャーセッションとローカルの Git 作成者またはリポジトリメタデータにオプトインするには、--use-detected を渡します。そのフラグがない場合、--yes は ID を持つローカルデフォルトをコピーしません。

build

build は、emdash-plugin.jsonc、src/plugin.ts、およびオプションの兄弟 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 の上にある薄いパッケージングステップです：

--validate-only は tarball の作成をスキップしますが、dist/ アーティファクトを生成します。「検証」は「最初にビルド」を意味します。

publish

publish は、プラグインをビルドして検証し、パッケージとリスティングイメージを PDS にアップロードして、リリースレコードを書き込みます。

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

publish は、プロファイルフィールドのマニフェストを読み取り、パブリッシャーピンニングを強制します。ライセンス、作成者、セキュリティ連絡先、およびその他のパッケージ情報をマニフェストに保持します。古いプロファイルフラグと --no-manifest は、レガシースクリプト公開のために引き続き利用できます。これらのフローの 1 つを維持する前に、publish --help を確認してください。

外部にホストされたパッケージバンドルを使用するには、--url <https-url> を渡します。CLI は公開する前に URL をダウンロードして検証します。ローカルの tarball がダウンロードされたバイトと一致することを確認するには、--local <path> を追加します。

完全なローカルリリースフローについては、バンドルと公開を参照してください。

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 から欠落しているプロファイルを作成するか、パッケージメタデータを置き換えずに既存の有効なプロファイルに委譲リリース設定を追加します。

プラグインディレクトリからインタラクティブセットアップを実行します。モノレポの他の場所から実行する場合は、--dir <plugin-directory> を渡します：

emdash-plugin profile setup

コマンドは、プロファイルを書き込むためにアクティブな CLI ログインを使用します。異なる署名付きリポジトリの置換を拒否します。リポジトリ、承認者、パッケージメタデータを保持しながら署名付き来歴ポリシーを変更するには、--provenance required|optional で再実行します。アクティブなアカウントがマニフェストパブリッシャーと一致しない場合は、emdash-plugin switch <did> を実行します。来歴に裏付けられたリリースの場合、プロファイルを公開した後に emdash-plugin release setup を実行します。

release setup

release setup は、1 つのプラグインディレクトリからパッケージプロファイルセットアップを実行し、次に Git リポジトリルートに 1 つの共有 .github/workflows/emdash-release.yml を作成します。ネストされたプラグインパッケージは同じワークフローを再利用します。プラグインディレクトリから実行するか、--dir <plugin-directory> を渡します。リポジトリルートは、準備するパッケージプロファイルを特定しません。

emdash-plugin release setup

profile setup フラグと次のワークフローオプションを受け入れます：

セットアップがインタラクティブターミナルで Changesets を検出すると、EmDash プラグインをどのようにリリースするかを尋ねます。Changesets リリースに従うは、emdash-plugin.jsonc を含むパッケージに対して同じバージョンを公開します。他の選択肢は、<slug>@<version> タグに従うか、手動実行のみを許可します。非インタラクティブ使用では、有効なルート設定が存在する場合は auto が Changesets を選択し、それ以外の場合はパッケージタグを選択します。

Changesets バリアントは再利用可能なワークフローです。既存の Changesets 公開ジョブの後に 1 つの呼び出し元ジョブを追加し、その公式の公開パッケージ 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]> を使用すると、1 つの手動セレクターを検証します。コマンドはパッケージをビルドまたは公開しません。

release prepare

release prepare は、生成されたワークフローのパッケージリゾルバーです。リポジトリ内の 1 つのプラグインマニフェストを見つけ、オプションのタグバージョンをチェックし、パッケージをビルドし、そのパッケージ、パブリッシャー、ディレクトリ、およびバンドル出力を GITHUB_OUTPUT に書き込みます。

生成されたワークフローは、パッケージタグを自動的に渡します：

emdash-plugin release prepare gallery@1.2.3

手動ワークフロー実行の場合は、プレーンなプラグイン ID を渡します。コマンドは、そのパッケージのマニフェストからバージョンを使用します。重複するプラグイン ID、欠落しているパッケージ、およびバージョンの不一致は、来歴が作成される前に失敗します。

プログラマティック API

Node.js から CLI のプログラマティック関数をインポートして、プラグインをビルドまたはバンドルします：

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

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

ディスカバリおよび認証情報ヘルパーの場合は、@emdash-cms/registry-client からインポートします。