Basercms Core Plugin Convert

baserCMS 通常プラグイン → コアプラグイン 昇格手順

サードパーティ／単体配布の baserCMS プラグインを、baserCMS 本体（monorepo）のコアプラグインとして取り込む手順。 参照: plugins/bc-blog 等の既存コアプラグインが「正」の構成。

前提と役割分担

• バージョン移行（5.2→5.3 / PHP8.5）でのコード非推奨対応は basercms-plugin-5x-update スキル。
• ユニットテストの実行・集計・切り分けは basercms-unittest スキル。
• 本書は「通常プラグイン構成 → コアプラグイン構成」への構造変換に絞る。

0. 大原則 / 完成形

• コアプラグインは plugins/<bc-name>/ に置かれ、自前の .git / vendor/ / bin/ / composer.lock / phpunit.xml.dist / tests/bootstrap.php / tests/TestApp/ を持たない。テストはアプリ全体のテスト基盤で実行する。
• 依存・オートロード・テスト登録・CI 登録はルート側に集約する。
• 完成形の例（plugins/bc-blog）: README.md / composer.json / config/ / config.php / src/ / tests/ / webroot/（＋必要なら webpack.config.js）。

1. プラグイン名をコアプラグイン規約へ変更

既に規約準拠の名前なら本節はスキップ。命名規約の詳細リネーム作業自体は別途 namespace 一括置換が必要（本スキルは「コア化に伴う命名規約」のみ規定）。

• フォルダ名: ケバブケースにし、bc- プレフィックスを付与する。
  • CamelCase はハイフン区切りへ。例: CuMcp → bc-mcp、MyAwesomePlugin → bc-my-awesome-plugin。
• namespace / プラグインクラス: パスカルケースで Bc プレフィックス。例: BcMcp、メインクラス BcMcpPlugin。
• composer パッケージ名: baserproject/<bc-name>。例: baserproject/bc-mcp。
• フォルダ名（ケバブ）と namespace（パスカル）の対応: bc-mcp ⇔ BcMcp。
• 命名に伴う namespace / use / 文字列リテラル（'plugin' => 'Xxx'・URL スラッグ /xxx・コマンド名・設定キー）の一括置換、composer.json の name/autoload/extra.cakephp.plugin-name 変更も行う（誤爆防止のため先頭トークンのみ置換し、Mcp/BcBlog のようなサブ階層名は温存）。

2. プラグイン側の standalone 成果物を削除

monorepo では不要・有害（vendor 二重化や nested git）なものを削除する。

plugins/<bc-name>/
  .git                  ← nested リポジトリを削除（親 monorepo に取り込む）
  vendor/               ← 自前 vendor を削除（ルート vendor を使う）
  bin/                  ← 自前 cake バイナリを削除（ROOT/bin/cake を使う）
  composer.lock         ← 削除
  phpunit.xml.dist      ← 削除（ルート phpunit.xml.dist に testsuite を登録する）
  tests/bootstrap.php   ← 削除（ルート tests/bootstrap.php を使う）
  tests/TestApp/        ← 削除（ルート tests/TestApp を使う）
  .github/              ← 単体 CI は不要（split 先リポジトリでも別管理）。既存コアに無ければ削除
  .gitignore            ← 既存コアに無ければ削除
  VERSION.txt           ← 削除（バージョンは本体 monorepo 管理になる）
  CHANGELOG.md          ← 削除（変更履歴も本体管理）
  .phpunit.cache / .phpunit.result.cache / .DS_Store / .idea ← 削除

• 完成形は既存コア（plugins/bc-blog）に合わせる: README.md / composer.json / config/ / config.php / src/ / tests/ / webroot/（＋必要なら templates/・webpack.config.js）。
• ⚠️ .git 削除は不可逆。nested git の独自履歴が必要なら事前に退避。

3. ルート .gitignore の調整（2 種類・向きが逆なので注意）

3-1. プラグイン本体を「追跡対象」にする（無視の除外 !）

ルート .gitignore は /plugins/* で全プラグインを無視し、コアプラグインだけ ! でホワイトリストしている。コア化したプラグインを !/plugins/<bc-name> で追跡対象に加える（これを忘れると git add されず取り込まれない）。

# plugins
/plugins/*
!/plugins/baser-core
...
!/plugins/bc-seo
!/plugins/bc-mcp          ← 追加（無視の除外＝追跡対象化）
/plugins/*/vendor
/plugins/*/composer.lock

• 確認: git check-ignore -v plugins/<bc-name>/composer.json（何も返らなければ追跡対象）、git status --short plugins/<bc-name>。

3-2. webroot シンボリックリンクは「無視」する

baserCMS は webroot/<plugin_underscored> → plugins/<bc-name>/webroot のシンボリックリンクを生成する（例 webroot/bc_mcp）。実体は plugins/<bc-name>/webroot にあるため、リンク側はルート .gitignore で無視する（他コアと同じ並び）。

/webroot/bc_blog
/webroot/bc_custom_content
/webroot/bc_mcp          ← 追加（アンダースコア表記）

向きに注意: plugins/<bc-name> は追跡（! で除外）／webroot/<underscored> は無視。

4. テストを「全体実行」に載せ替える

4-1. ルート phpunit.xml.dist に testsuite を追加（⚠️ 配置順が重要）

（プラグイン側 phpunit.xml.dist は 2. で削除済み。追加するのはルート側。）

<testsuite name="BcMcp">
    <directory>plugins/bc-mcp/tests/TestCase</directory>
</testsuite>

• ⚠️ DB テーブルを持つが defaultInstallCorePlugins に入れないプラグインは、BcInstaller の testsuite より「前」に置く。BcInstaller の InstallationsControllerTest::testStep3（mode=createDb）は実際のインストール処理で全テーブルを drop し defaultInstall のプラグインのみ再作成する。後ろに置くと、自プラグインのテーブルが作り直されないまま自テストが走り全アクション 500 になる（既存の非 default コア=BcContentLink/BcCustomContent 等もすべて BcInstaller より前に並んでいる）。
  • 例: ... BcSeo の直後・BcInstaller の直前に BcMcp を置く。
  • defaultInstall に入れる方針なら BcInstaller の後でも可（createDb が作り直すため）。

4-2. マイグレーション・プラグインリストへ追加（⚠️ 複数箇所ある）

プラグインが DB マイグレーション（config/Migrations）を持つ場合、テスト用 DB にテーブルを作る／再構築するプラグインリストすべてに追加する。1 箇所でも漏れると、全体実行時にそのプラグインのテーブルだけ欠落し Could not describe columns on <table>（→ コントローラ初期化失敗で当該プラグインの全アクション 500）になる。単独 testsuite では通り、全体実行でのみ落ちるのが特徴（切り分けは basercms-plugin-5x-update のテスト基盤節も参照）。

1. ルート tests/bootstrap.php の Migrator::runMany（初期スキーマ構築）

   (new Migrator())->runMany([
       ['plugin' => 'BaserCore'],
       ...
       ['plugin' => 'BcMcp'],   // 追加
   ]);

2. 「全テーブル drop → 再マイグレーション」をするテストの $plugins 配列（複数あり）。これらは deleteTables()/deleteAllTables() で全テーブルを drop した後、ハードコードされたリストで再マイグレーションする。ここに無いとテーブルが復活せず、テスト順で先頭側に位置するため以降の全テストで欠落したままになる（実際に bc-mcp 追加時に oauth2_clients がこれで消え、OAuth2 全テストが 500 になった）。判明している箇所（両方必須）:
   • plugins/baser-core/tests/TestCase/Service/BcDatabaseServiceTest.php → test_deleteTablesForMigrations() の $plugins
   • plugins/bc-installer/tests/TestCase/Service/Admin/InstallationsAdminServiceTest.php → test_deleteAllTables() の $plugins

   $plugins = [ 'BaserCore', ..., 'BcMail', 'BcMcp', /* 追加 */ 'BcSearchIndex', ... ];

• 抜け漏れ確認（重要）: この種の再構築リストは複数ファイルに散在する。必ず grep で全部洗う:

  grep -rn "'BcWidgetArea'," plugins --include="*.php"   # 末尾要素で「コア列挙リスト」を検出

  ヒットした各リストに新プラグインが入っているか確認する（1 つでも漏れると全体実行のみで落ちる）。
• 確実な検出法: BcTestCase::setUp 冒頭に「対象テーブルの存在を各テストで記録」する一時計測を仕込み、全 suite を実行して OK→MISSING 転移点を洗い出す（転移直前の OK テストが drop 元）。全 dropper を一度に特定できる。確認後に計測は除去する。
• 切り分け診断（どのテストでテーブルが消えるか）: BcTestCase::setUp 冒頭に一時計測（ConnectionManager::get('test')->getSchemaCollection()->listTables() に対象テーブルが在るか各テストで記録）を仕込み、最初に MISSING になる直前の OK テストが drop 元。確認後に必ず除去する。

4-3. プラグイン composer.json をコアプラグイン形式へ簡素化

require-dev（baser-core 等）・scripts・config.allow-plugins・minimum-stability は削除。vendor-dir を足す。外部ランタイム依存がある場合は require に残す（後で monorepo-builder merge がルートへ集約する）。

{
    "name": "baserproject/bc-mcp",
    "description": "BcMcp plugin for baserCMS",
    "homepage": "https://basercms.net",
    "type": "cakephp-plugin",
    "license": "MIT",
    "vendor-dir": "../../vendor",
    "require": {                       // 外部依存が無ければ require ごと省略可（bc-blog 等）
        "php": "^8.1",
        "league/oauth2-server": "^8.5"
        // ...プラグイン固有の外部依存
    },
    "autoload":     { "psr-4": { "BcMcp\\": "src/" } },
    "autoload-dev": { "psr-4": { "BcMcp\\Test\\": "tests/" } }
}

• テストが他コアの Test 名前空間（BcBlog\Test 等）や App\（TestApp）を使う場合、**ルート composer.json の autoload-dev** が供給するため、プラグイン側 autoload-dev は自分の Test のみでよい。

5. システム（baserCMS / monorepo）への認識

5-1. plugins/baser-core/config/setting.php の corePlugins に追加

'corePlugins' => [ ..., 'BcMail', 'BcMcp', 'BcSeo', ... ],

5-2. defaultInstallCorePlugins への追加可否を確認

baserCMS 新規インストール時に自動有効化するなら追加（BcBlog/BcMail 等と同様）。任意機能・オプトインなら追加しない（corePlugins のみ＝管理画面から手動有効化）。 → プロジェクト方針をユーザーに確認する。

5-3. ルート composer.json への集約（autoload / autoload-dev / replace / require）

原則 vendor/bin/monorepo-builder merge で集約する（monorepo-builder.php の packageDirectories([... '/plugins']) が plugins/ 配下を自動走査し、各 composer.json をルートへマージ＋replace を管理）。

docker compose exec <container> sh -c "cd /var/www/html && vendor/bin/monorepo-builder merge"

• ⚠️ merge は全パッケージのバージョン整合をガードする。monorepo 外のローカル専用プラグイン（例 EgaRyu / BcUpdateSupporter 等）に版差があると Found conflicting package versions でブロックされる。その場合は当該プラグインの版を揃えるか、ブロック時は merge と同等の編集を手動で行う（下記）。
• merge 相当の手動編集（ルート composer.json）:
  • autoload.psr-4 に "BcMcp\\": "plugins/bc-mcp/src/"
  • autoload-dev.psr-4 に "BcMcp\\Test\\": "plugins/bc-mcp/tests/"
  • require にプラグインの外部依存（league/oauth2-server 等、ext-* 含む）
  • replace に "baserproject/bc-mcp": "<monorepo版>"（他コアに合わせる）
• 反映後、依存取得とオートロード再生成:

  docker compose exec <container> sh -c "cd /var/www/html && composer update <added-packages> --no-interaction"