zcms CLI リファレンス

zcms は、拡張機能のひな型作成、公開者鍵の生成、パッケージ化、署名の検証を行う CLI です。コマンドは init、keygen、pack、verify の 4 つです。パッケージのアップロードは Developer Portal で行います。

インストール

npm install -g @zcmsorg/cli

パッケージ名は @zcmsorg/cli、インストールされるコマンドは zcms です。Node.js 22 以上が必要です。

引数を付けずに zcms を実行すると、インストールを確認でき、利用可能なコマンドが表示されます。

コマンド一覧

zcms init [<dir>] [--kind theme|plugin] [--id <reverse.dns.id>] [--name <name>]
          [--description <text>] [--author <name>] [--author-url <url>]
          [--version <semver>] [--yes]
zcms keygen [--out <dir>]
zcms pack <dir> --kind theme|plugin --key <private.pem> --pub <public.pem> [--out <file>]
zcms verify <file.zcms> [--marketplace-key <public.pem>]

コマンドを指定せずに zcms を実行すると、この使用方法が表示されます。

1. プロジェクトのひな型を作成する

zcms init

ターミナルで init を実行すると、不足している情報を順に質問し、マニフェスト、ソース、ビルドスクリプト、テストを含むプロジェクトを作成します。既存のファイルがあるディレクトリには書き込みません。

CLI からの質問なしで作成するには、--yes と必要なオプションを指定します。スクリプトや CI で実行する場合に利用できます。

zcms init ./hello --yes --kind plugin \
  --id com.acme.plugin.hello \
  --name "Hello" \
  --description "Adds a content helper." \
  --author "Acme" \
  --author-url "https://acme.example"

--yes を使う場合や対話できない CI 環境では、--kind と --id が必須です。ほかのオプションを省略すると既定値が使われ、バージョンは 0.1.0 になります。

Plugin は次の構成で生成されます。

hello/
├── plugin.json          # manifest — identity、permission、settings form
├── package.json
├── build.mjs            # esbuild -> 単一の CommonJS file
├── tsconfig.json
├── src/index.ts         # filter、action、job、setup
├── test/plugin.test.ts
├── README.md
└── .gitignore           # *.pem を ignore 済み — 下記参照

Theme も同じ構成で、theme.json、src/index.tsx（Layout、template、block）、src/theme.css を含みます。

ひな型が重要な理由

次の 2 つの要件はビルド時ではなく、拡張機能を実際のサイトで実行したときに検証されます。設定を誤ってもビルド、テスト、パッケージ化、署名、インストールまでは成功し、有効化した時点で初めてエラーになる場合があります。init が作成するプロジェクトは、最初から両方の要件を満たしています。

	要件	誤ったときに何が起きるか
プラグイン	単一の CommonJS ファイル。V8 isolate のサンドボックスが提供するモジュールは `@zcmsorg/plugin-sdk` だけです。	モジュールリゾルバーがないため、複数の出力ファイルに分かれると相対 `require()` を解決できず、有効化時にエラーになります。`build.mjs` はソースを 1 ファイルにまとめるよう設定済みです。
テーマ	エントリーポイントは ESM の `.mjs` ファイル。React は external にします。	形式を誤ると `site-runtime` はテーマを読み込めず、既定のテーマへ切り替わります。React を同梱するとホスト側と二重になり、本番環境で “invalid hook call” が発生します。

開発サイクル

cd hello
pnpm install
pnpm build       # plugin -> dist/index.js   theme -> dist/index.mjs + dist/theme.css
pnpm typecheck
pnpm test

2. 公開者の鍵ペアを生成する

zcms keygen --out ./keys

./keys に次の 2 ファイルが作成されます。

publisher-private.pem: 所有者だけが読み取り可能な秘密鍵 (0600)
publisher-public.pem: Developer Portal へ登録する公開鍵

鍵ペアは公開者ごとに一度だけ作成し、バージョンごとに作り直さないでください。CLI は既存の秘密鍵を上書きしません。

publisher-private.pem は公開者の身元を証明する秘密鍵です。漏洩すると、第三者があなたの名前でパッケージに署名できます。Git 以外の安全な場所にバックアップし、チャットや CI ログへ貼り付けないでください。

3. パッケージディレクトリを準備する

マニフェストは、パッケージ化するディレクトリのルートに置きます。

--kind plugin の場合は plugin.json
--kind theme の場合は theme.json

マニフェストには id、name、version、author、engine が必要です。entry はビルド済みファイルを指し、パッケージ化する前に存在している必要があります。プラグインは dist/index.js、テーマは dist/index.mjs です。

zcms init で作成したプロジェクトは、pnpm build の後にプロジェクトルートから zcms pack . を実行できます。CLI は開発時にしか使わないファイルを自動的に除外します。

Key material: *.pem、*.key、*.p12、*.pfx、*.keystore、id_*、.npmrc
Secret と VCS: .env*、.git、node_modules
開発専用: src、test/、build script、tsconfig*.json、tool config、source map

*.pem は常に除外されるため、./keys ディレクトリが .zcms ファイルに含まれることはありません。それでも、秘密鍵は Git の外で管理し、チャットや CI ログへ出力しないでください。

4. 拡張機能をパッケージ化して署名する

プラグインの例:

mkdir -p release

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

テーマの場合は --kind theme に変更します。--out を省略すると、現在のディレクトリに <manifest.id>-<manifest.version>.zcms が作成されます。--out を指定する場合、親ディレクトリは事前に作成してください。

コマンドはパッケージ ID、バージョン、ファイルサイズ、チェックサムを出力します。この時点では公開者の署名だけがあり、Marketplace の審査と署名が完了するまではインストールできません。

5. 提出前に検証する

zcms verify ./release/example-plugin-1.0.0.zcms

この段階では --marketplace-key を指定しません。publisher signature : VALID と表示されれば、内容のチェックサムと公開者の署名は有効です。marketplace signature : not checked は、まだ Marketplace へ提出していないため正常な表示です。

6. Marketplace のパッケージを検証する

承認済みパッケージをダウンロードした後は、Marketplace の公式公開鍵を使って両方の署名を検証します。

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

marketplace-public.pem は Marketplace の公開鍵であり、zcms keygen が生成する publisher-public.pem とは異なります。両方の署名が VALID なら、パッケージをインストールできます。

7. 審査用にアップロードする

CLI に zcms publish コマンドはありません。検証した .zcms ファイルを Developer Portal → Submit a package からアップロードしてください。検証後にビルドやパッケージ化をやり直さず、検証したファイルそのものを提出します。

審査の全手順はパッケージを公開するを参照してください。