enonic-app-manager

Enonic CLI とローカル開発環境のヘルパー

手順

ステップ 1：ワークスペースのコンテキストを検出する

1. スキルのルートから node scripts/find-enonic-targets.mjs を実行し、現在のワークスペース内で Enonic プロジェクトのマーカー（.enonic、com.enonic.xp プラグインを含む build.gradle、xpVersion を含む gradle.properties）をスキャンします。
2. マーカーが見つかった場合は、出力からプロジェクト名、リンクされているサンドボックス、XP バージョンを確認します。以降のコマンドでは、これらの値をデフォルトとして使用します。
3. マーカーが見つからない場合は、新規セットアップとして扱い、必要に応じてサンドボックスの作成またはプロジェクトのひな形作成に進みます。

ステップ 2：CLI が利用可能であることを確認する

1. enonic --version を実行して、Enonic CLI がインストールされていることを確認します。
2. コマンドが失敗した場合は、references/cli-reference.md でインストール手順を確認し、検出した OS に適した方法を案内します。
   • npm（すべての OS）： npm install -g @enonic/cli
   • macOS： brew tap enonic/cli && brew install --no-quarantine enonic
   • Linux： wget -qO- https://repo.enonic.com/public/com/enonic/cli/installer/cli-linux/1.0.0/cli-linux-1.0.0.sh | sh
   • Windows： scoop bucket add enonic https://github.com/enonic/cli-scoop.git && scoop install enonic
3. インストール後、enonic --version で確認します。

ステップ 3：サンドボックスの管理

1. サンドボックスコマンドの一覧については、references/cli-reference.md を確認します。
2. リクエストに適した操作を選びます。
   • 作成： enonic sandbox create <name> [-v <version>] [-t <template>] [--skip-template] [-i <image>] [-f]
   • 一覧表示： enonic sandbox ls
   • 起動： enonic sandbox start <name> [--detach] [--prod] [--debug]
   • 停止： enonic sandbox stop
   • アップグレード： enonic sandbox upgrade <name> -v <version>
   • 削除： enonic sandbox delete <name> -f
   • コピー： enonic sandbox copy <source> <target>
3. サンドボックスを作成するとき、XP バージョンが指定されていなければ、バージョンを確認します。バージョンと名前が決まっている場合は、非対話形式で実行するために -f フラグを使用します。注：-f を指定すると、作成後にサンドボックスが自動的に起動します。起動をスキップするには、--skip-start も指定してください。
4. リクエストにテンプレートが含まれている場合は、利用可能なテンプレートを一覧表示するか、-t <template> フラグを使用します。プリインストールされたアプリのない空のサンドボックスを作成するには、--skip-template を使用します。
5. リクエストに Docker が含まれている場合は、ダウンロードした XP ディストリビューションの代わりに Docker イメージを使用してサンドボックスを作成するため、-i <image>（例：enonic/xp:latest-sdk）を使用します。$PATH に docker が必要です。

ステップ 4：プロジェクトのひな形作成

1. 新しいプロジェクトを作成するには、簡略化されたコマンドを使用します：enonic create <name> [-r <starter>] [-s <sandbox>] [-f]
2. よく使われるスターターには、starter-vanilla、starter-headless、starter-nextjs があります。オプションの一覧については、references/cli-reference.md を確認してください。
3. 既存のプロジェクトを別のサンドボックスにリンクするには、enonic project sandbox <name> を使用します。
4. 作成後、プロジェクトフォルダーに build.gradle と .enonic の設定が含まれていることを確認します。

ステップ 5：開発ワークフロー

1. 適切な開発コマンドを選びます。
   • 開発モード（ホットリロード）： enonic dev — サンドボックスをデタッチモードで起動し、ファイルの監視を行いながらアプリを実行します。プロジェクトのルートから実行してください。
   • ビルドのみ： enonic project build
   • サンドボックスへのデプロイ： enonic project deploy [sandbox-name] [-c] — 継続的なデプロイには -c を使用します。
   • 実行中の XP へのインストール： enonic project install
   • テストの実行： enonic project test
   • ビルド成果物のクリーンアップ： enonic project clean
   • 任意の Gradle タスク： enonic project gradle <tasks>
2. サンドボックスが実行中でない場合は、先に enonic sandbox start <name> -d で起動します。
3. 開発モードを終了するには、Ctrl-C を使用します。CLI はデタッチされたサンドボックスも自動的に停止しようとします。 ステップ 6：実行中の XP でのアプリ管理
4. 実行中の XP インスタンスでアプリを管理するには、XP のアプリコマンドについて references/cli-reference.md を読みます。
5. 操作に応じて、次のコマンドを使います。
   • URL からインストール： enonic app install --url <jar-url>
   • ファイルからインストール： enonic app install --file <path-to-jar>
   • アプリを起動： enonic app start <app-key>
   • アプリを停止： enonic app stop <app-key>
6. XP コマンドの実行には認証が必要です。--cred-file <path>（XP 7.15 以降）、mTLS の場合は --client-key <path> + --client-cert <path>（XP 7.15 以降）を使うか、環境変数 ENONIC_CLI_REMOTE_USER と ENONIC_CLI_REMOTE_PASS を設定します。

ステップ 7：CI/CD パイプラインの生成

1. GitHub Actions ワークフローのテンプレートについて、assets/enonic-ci.template.yml を読みます。
2. プロジェクトに合わせてテンプレートをカスタマイズします。
   • サンドボックス作成ステップで適切な XP バージョンを設定します。
   • アプリ名と Gradle ビルドパラメーターを設定します。
   • デプロイ先（ステージングにはサンドボックス、本番環境にはクラウド）を設定します。
3. 生成したワークフローファイルを、プロジェクトリポジトリの .github/workflows/enonic-ci.yml に配置します。

ステップ 8：トラブルシューティング

1. サンドボックスの起動またはデプロイに失敗した場合は、一般的な問題と解決策について references/troubleshooting.md を読みます。
2. 主な診断コマンド：
   • enonic sandbox ls — サンドボックスの状態と XP バージョンを確認します。
   • enonic system info — 実行中の XP インスタンスの詳細を確認します。
   • ポート 8080（HTTP）と 5005（デバッグ）が使用可能か確認します。
3. バージョンの不一致エラーが発生した場合は、CLI と XP のバージョン互換性について references/compatibility.md を読みます。

エラー処理

• scripts/find-enonic-targets.mjs で結果が見つからない場合は、失敗として終了するのではなく、新規構築の手順に従います。
• enonic --version が失敗した場合は、次に進む前に、ステップ 2 に従って CLI のインストールを案内します。
• バージョンエラーでサンドボックスの作成に失敗した場合は、references/compatibility.md を読み、互換性のある XP バージョンを提案します。
• サンドボックスの起動中にポートの競合が発生した場合は、解決手順について references/troubleshooting.md を読みます。
• enonic dev が失敗した場合は、プロジェクトに Gradle の dev タスクがあること（すべての公式スターターに含まれています）、およびリンク先のサンドボックスが存在し、別のターミナルですでに実行中ではないことを確認します。