パッケージを公開する

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

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

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

zcms keygen --out ./keys

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

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

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

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

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

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

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

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

ステップ 3: パッケージ化して署名する

コミット済みのロックファイルと、プロジェクトのドキュメントに記載されたツールチェーンを使い、クリーンなチェックアウトからビルドします。続いて型チェック・lint・ユニットテストを実行し、ビルド済みエントリーポイントが正しいことを確認します。バージョンを手で編集する必要はありません。zcms pack が刻印して自動的に進めます（後述の pack がバージョンを設定する を参照）。

公開する theme または plugin のパスを pack に渡す

zcms pack は ディレクトリを 1 つだけ パッケージ化します。そのディレクトリが最初の引数、つまり公開したい theme または plugin へのパスです。そのパスの外にあるものは一切含まれないため、ここで どの 拡張機能をパッケージ化するかを指定します。ディレクトリのルートには次のものが必要です。

• マニフェスト（theme は theme.json、plugin は plugin.json）
• マニフェストの entry が指すビルド済みファイル（theme は dist/index.mjs、plugin は dist/index.js）。pack はビルドを行わないため、事前にビルドしてください。

--kind はそのパスのマニフェストと一致させます。theme.json なら --kind theme、plugin.json なら --kind plugin です。

theme をパッケージ化する場合 は、theme のディレクトリをパスに指定します。

mkdir -p release

zcms pack ./themes/corporate --kind theme \
  --key ./keys/publisher-private.pem \
  --pub ./keys/publisher-public.pem \
  --out ./release/corporate-1.0.0.zcms

plugin をパッケージ化する場合 は、代わりに plugin のディレクトリを指定します。

zcms pack ./plugins/seo-toolkit --kind plugin \
  --key ./keys/publisher-private.pem \
  --pub ./keys/publisher-public.pem \
  --out ./release/seo-toolkit-1.0.0.zcms

パスは絶対パス（/home/me/themes/corporate）でも相対パス（./themes/corporate、ディレクトリ内にいる場合は .）でも構いません。マニフェストのあるディレクトリを指していれば十分です。1 コマンドにつき 1 つのパスを渡します。複数の拡張機能を公開するには、それぞれに対して zcms pack を実行してください。--out を省略すると、カレントディレクトリに <manifest.id>-<manifest.version>.zcms として出力されます。

pack がバージョンを設定する

公開前にバージョンを手で編集する必要はありません。zcms pack は現在マニフェストが宣言しているバージョンでパッケージ化し、その後バージョンを進めて（既定では patch）、新しい番号をマニフェストと package.json に書き戻します。これにより、次のリリースはすでに新しいバージョンになっています。より大きく上げるには --bump minor|major、正確なバージョンに固定するには --set-version <semver>、据え置くには --no-bump を渡します。ファイル名 <manifest.id>-<manifest.version>.zcms には実際にパッケージ化したバージョンが使われます。パッケージ化に失敗した場合はバージョンがロールバックされます。

署名は pack の中で行われる

パッケージ化が そのまま署名の工程 です。別途 zcms sign コマンドはありません。--key は公開者の 秘密鍵 で、zcms pack はファイルを書き出す際にこの鍵でパッケージのペイロードのチェックサムに署名します。--pub は対応する 公開鍵 を埋め込み、検証者がその署名を確認できるようにします。どちらもステップ 1 のものです。秘密鍵は共有マシンや CI ログに残さないでください。パッケージャーは *.pem ファイルをアーカイブに含めませんが、どこかに貼り付けてしまった鍵までは守れません。

コマンドはパッケージ ID、バージョン、ファイルサイズ、チェックサムを出力します。チェックサムは検証者と Marketplace の双方が再計算する値なので、記録しておきます。

検証してから再現性を確認する

提出するファイルそのものに対して、公開者の署名を検証します。

zcms verify ./release/corporate-1.0.0.zcms

続いて同じディレクトリをもう一度パッケージ化し、ビルドが再現可能であることを確認します。pack は実行のたびにバージョンを進めるため、両方のパッケージ化に --no-bump を付けて、その間バージョンを固定してください。CLI はファイルを並べ替え、アーカイブのタイムスタンプを 0 にするため、チェックサムは 1 回目と一致するはずです。2 つのチェックサムが異なる場合は、タイムスタンプ、順序が変わるファイル一覧、バージョンを固定していない依存関係など、不安定な入力を取り除いてから提出してください。

ステップ 4: 審査に提出する

ステップ 3 で 検証したものと同じ .zcms ファイル を提出します。検証してからアップロードするまでの間に、ビルドやパッケージ化をやり直さないでください。

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）、次に担当者による判断（ステップ 6）です。状態は Developer Portal → Submissions で確認できます。却下される場合は必ず対処可能な理由が添えられます。

ステップ 5: 自動検証

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

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

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

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

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

変更を要求された場合:

1. 却下理由とスキャナーの確認事項を読む。
2. ソース、テスト、マニフェストを更新する。
3. 新しい .zcms をビルド、署名、検証する。zcms pack が次のバージョンを自動的に刻印します（前回のパッケージ化の後、マニフェストはすでに進んでいます）。
4. 新しいバージョンを提出する。

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

ステップ 7: Marketplace の署名

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

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

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

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

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

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

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

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

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

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

テーマのデモコンテンツは自動更新されません

テーマがデモコンテンツを含む場合でも、テーマを更新してもサイトのデモデータは更新されません。新しいバージョンでそのデモデータを変更しても（翻訳の修正、ページやメニューの追加など）、各サイトは管理者が 管理画面 → Appearance を開き、有効なテーマに対して Reseed demo をクリックするまで既存のデモコンテンツのままです（新規インストールではまず Seed demo が必要）。reseed はそのテーマのデモ行だけを置き換え、管理者の実際のコンテンツには手を触れません。reseed が必要であることを変更履歴に明記してください。詳しくは デモコンテンツを提供する を参照してください。