パッケージを公開する

この手順は、プラグインまたはテーマのローカルテストが完了した時点から始まります。手元で検証したファイルそのものを提出し、審査中にビルドし直さないでください。

ステップ 1: 公開者の鍵を生成・登録する

公開者用の Ed25519 鍵ペアを一度だけ生成します。

zcms keygen --out ./keys

publisher-private.pem は権限 0600 の秘密鍵、publisher-public.pem は公開鍵として作成されます。秘密鍵は安全にバックアップし、コミット、アップロード、Web フォームへの貼り付けを行わないでください。

Developer Portal → Publisher を開き、次の情報を登録します。

3–40 文字の slug。小文字、数字、hyphen のみを使用し、先頭と末尾に hyphen は使用しない。
表示名。
連絡先メールアドレス（任意）。
publisher-public.pem の内容全体。

1 つの公開鍵は 1 人の公開者にだけ登録できます。秘密鍵を貼り付けたり公開したりした場合は漏洩したものとみなし、新しい鍵ペアを作成してください。

ステップ 2: 掲載情報を準備する

公開ページの情報は署名済みマニフェストから作成されます。パッケージ化する前に、次のフィールドを設定してください。

Reverse-DNS 形式の id、表示名 name、セマンティックバージョン version、description、author。
engine に対応する Z-CMS のバージョン範囲。
ビルド済みの entry。通常は dist/index.js。
プラグインの permissions、機能、設定、またはテーマのテンプレートと設定。
media.screenshots に最大 3 枚のスクリーンショット。PNG、JPEG、WebP のみ、1 枚 2 MB 以下、各辺 4096 px 以下。
任意の紹介動画 URL を media.video に設定。HTTPS で誰でも閲覧できる URL を使用します。

新しい権限の追加やデータ処理方法の変更がある場合は、変更内容を明記してください。権限の増加を一般的な変更履歴の中に埋もれさせないでください。

ステップ 3: リリース用ファイルを作成する

コミット済みのロックファイルと、プロジェクトのドキュメントに記載されたツールチェーンを使い、クリーンなチェックアウトからビルドします。

型チェック、lint、ユニットテストを実行する。
マニフェストのバージョンとビルド済みエントリーポイントが正しいことを確認する。

公開者の鍵でビルド済みディレクトリをパッケージ化する。

mkdir -p release

zcms pack ./path/to/built-package --kind plugin \
  --key ./keys/publisher-private.pem \
  --pub ./keys/publisher-public.pem \
  --out ./release/package.zcms

Theme の場合は --kind theme を使用します。

zcms pack が出力したチェックサムを記録する。
公開者の署名を検証する。
Terminal window
```
zcms verify ./release/package.zcms
```
ビルドの再現性を確認する場合は、同じディレクトリをもう一度パッケージ化する。CLI はファイルを並べ替え、アーカイブのタイムスタンプを 0 にするため、チェックサムは一致します。

チェックサムが異なる場合は、タイムスタンプ、順序が変わるファイル一覧、バージョンを固定していない依存関係など、不安定な入力を取り除いてから提出してください。

ステップ 4: アップロードして提出する

Developer Portal → Submit a package を開き、.zcms ファイルを選択して Submit for review を実行します。1 ファイルの上限は 20 MB で、各開発者アカウントは連続する 1 時間に最大 10 パッケージを提出できます。

Portal で公開者、パッケージ ID、バージョンを選択する必要はありません。これらは署名済みのパッケージ情報から読み取られ、公開者は登録済みの公開鍵から特定されます。

API からアップロードする場合は、認証済みの multipart/form-data リクエストを POST /developer/submissions に送信し、ファイルを file フィールドに設定します。自分の提出履歴は GET /developer/submissions で取得できます。

ステップ 5: 自動検証

Marketplace は次の順序でパッケージを受け付けます。

コードを実行せずにアーカイブを開き、内容のチェックサムを再計算する。
登録済みの公開鍵から公開者を特定し、開発者アカウントがその公開者を所有していることを確認する。
パッケージ内の鍵だけを信用せず、登録済みの鍵で公開者の署名を検証する。
メディアを検証し、静的スキャナーを実行する。
Marketplace の署名を追加し、受け付けたパッケージを保存する。

スキャナーが reject を返した場合はエラーとなり、バージョンは作成されません。flag の場合は確認事項付きの QUARANTINED バージョンになります。問題が見つからなければ PENDING になりますが、まだ承認済みではありません。

ステップ 6: 担当者による審査

サードパーティ製の PENDING または QUARANTINED バージョンは、すべて担当者による審査が必要です。状態は PENDING、QUARANTINED、APPROVED、REJECTED のいずれかです。結果は Developer Portal と通知に表示され、却下された場合は理由も表示されます。

変更を要求された場合:

却下理由とスキャナーの確認事項を読む。
ソース、テスト、マニフェストを更新する。
バージョンを上げる。
新しい .zcms をビルド、署名、検証する。
新しいバージョンを提出する。

一度作成したバージョンは変更できません。既存バージョンと異なる内容をアップロードすると拒否され、同じ内容を再度アップロードした場合は以前の審査結果が維持されます。

ステップ 7: Marketplace の署名

zcms pack は公開者の署名を作成します。Marketplace は公開者の確認とスキャンの後、同じチェックサムへ 2 つ目の署名を追加し、両方の署名を持つ .zcms を保存します。

Marketplace の署名があっても、審査中のパッケージは公開されません。レジストリが提供するのは APPROVED で失効していないバージョンだけです。Z-CMS ランタイムはインストール前に、固定された MARKETPLACE_PUBLIC_KEY で Marketplace の署名を検証します。

ステップ 8: 公開後に確認する

担当者が承認すると、バージョンは自動的に公開レジストリで利用可能になります。承認後は次を確認します。

公開ページを開き、メタデータ、スクリーンショット、変更履歴を確認する。
Marketplace から新しいテストサイトへパッケージをインストールする。
署名の検証が成功することを確認する。
ドキュメントに記載した権限だけでパッケージを有効化する。
スモークテストを実行し、アンインストールまたはロールバックを確認する。

Marketplace からダウンロードした .zcms ファイルの署名をインストール前に手元で確認する場合は、Marketplace の公式公開鍵を指定します。

zcms verify ./downloaded-package.zcms --marketplace-key ./marketplace-public.pem

ステップ 9: リリースを維持する

サポート窓口とセキュリティ連絡先を確認します。修正版は新しいセマンティックバージョンとして公開し、既存リリースを変更しないでください。

セキュリティ問題が発生した場合は、情報公開の手順を調整し、修正版パッケージを提出します。必要に応じて、影響を受けるバージョンの失効を依頼してください。ランタイムは署名済みの失効リストを同期し、失効したパッケージを隔離します。