umbraco-version-guard

Umbraco バージョンガード

このスキルの役割

Umbraco のバックオフィス API はメジャーバージョン間で変わります（ツリーデータソース、認証、OpenAPI の登録など）。これらのスキルは特定の 1 つのメジャーバージョンを対象としています。 別のメジャーバージョンのサイトに適用すると、自信満々に誤ったコードを生成します。

このスキルは事前チェックです。対象のメジャーバージョンをプラグイン自体から導出し（新しいメジャーバージョンがリリースされても古くならないように）、対象サイトのメジャーバージョンを確定的に検出し、両者を比較し、不一致の場合は正しいインストールコマンドを示して停止します。ここでは特定のメジャーバージョン番号をハードコードしておらず、両側とも計算されます。

ステップ 1 — これらのスキルが対象とするメジャーバージョンを特定する

プラグイン自身のバージョンが信頼できる情報源であり、リリースごとにメジャーバージョンが上がります。これを読み取り、先頭の番号を取得します:

# Primary: the installed plugin's version. First path is the Claude Code plugin layout;
# the greps are fallbacks for when the skill was copied flat into an editor's skills dir.
cat "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null \
  || cat ../../.claude-plugin/plugin.json 2>/dev/null \
  | grep -m1 '"version"' | grep -oE '[0-9]+' | head -1

これを TARGET_MAJOR と呼びます。どのパスも解決できない場合（plugin.json が隣にないフラットなコピーなど）は、マーケットプレイスのバージョンにフォールバックし、それでもだめな場合にのみ、姉妹スキルが記載している値を読むことにします — 決して番号をでっち上げないでください。どうしても特定できない場合は、その旨を伝え、推測するのではなくガードをスキップしてください。

ステップ 2 — サイトの Umbraco メジャーバージョンを検出する（確定的、実行中のインスタンス不要）

以下のシグナルを順に試し、番号が得られた最初のもので停止します。それぞれがメジャーバージョンのみを抽出するため、18.0.0、18.*、[18.0.0,)、または単なる 18 でも機能します。

A. Umbraco.Cms パッケージ参照（グラウンドトゥルース — 実際にインストールされているもの）。 *.csproj の PackageReference と中央パッケージ管理の *.props（PackageVersion）をカバーします。Cms の後ろの末尾の " は Umbraco.Cms.DevelopmentMode などを除外します。

grep -rhoE 'Umbraco\.Cms"[^0-9]*[0-9]+' --include='*.csproj' --include='*.props' . 2>/dev/null \
  | grep -oE '[0-9]+$' | sort -u

B. フォールバック — バックオフィスクライアント依存関係のメジャーバージョン（^18.0.0、~18.0.0、18.0.0 を処理します）:

grep -rhoE '"@umbraco-cms/backoffice":[^0-9]*[0-9]+' --include='package.json' . 2>/dev/null \
  | grep -oE '[0-9]+$' | sort -u

C. 最後の手段 — 実行中のインスタンスの Server Information API（サイトが起動している必要があります。A/B を優先してください）:

GET {baseUrl}/umbraco/management/api/v1/server/information

結果を SITE_MAJOR と呼びます。A/B/C のすべてが何も返さない場合、ワークスペースにはまだ Umbraco サイトがありません — その旨を伝えて続行します（ガードする対象がありません）。複数の異なるメジャーバージョンが見つかった場合（混在ソリューション）、それらをすべて提示し、どのプロジェクトが対象かを尋ねてください。

ステップ 3 — 比較して対応する

• SITE_MAJOR == TARGET_MAJOR → ✅ サイレントパス。一致を確認する一文を述べ（例:「サイトは Umbraco {SITE_MAJOR}.x です — これらのスキルと一致します。」）、続行します。
• SITE_MAJOR != TARGET_MAJOR → ⛔ 停止。バージョン固有のコードを生成しないでください。以下に示すように警告し、ユーザーが明示的に確認した場合にのみ続行します。

どのスキルラインを推奨するかは、リポジトリのブランチ規約に従います — 最新のメジャーバージョンは main にあり、それより古いすべてのメジャーバージョン N は vN/main ブランチにあります:

• SITE_MAJOR < TARGET_MAJOR（サイトがこれらのスキルより古い）→ サイトのメジャーバージョンに対応する古いラインを指定します:

  /plugin marketplace add https://github.com/umbraco/Umbraco-CMS-Backoffice-Skills.git#v{SITE_MAJOR}/main
  

• SITE_MAJOR > TARGET_MAJOR（これらのスキルがサイトより古い）→ 最新のメジャーバージョンはデフォルトの main にあるため、デフォルトのマーケットプレイスを再追加して更新します:

  /plugin marketplace add umbraco/Umbraco-CMS-Backoffice-Skills
  

  SITE_MAJOR に対してリリース済みのラインがまだ存在しない場合は、その旨を伝えてください — スキルがそのメジャーバージョンに追いついていない可能性があります。

これを提示する際は、実際の番号に置き換えてください。メッセージのテンプレート:

⚠️ バージョンの不一致。 このサイトは Umbraco {SITE_MAJOR} ですが、読み込まれたスキルは Umbraco {TARGET_MAJOR} を対象としています。バックオフィス API はメジャーバージョン間で異なるため、このスキルセットはあなたのサイトに対して誤ったコードを生成します。一致するラインをインストールしてください: <上記で計算されたコマンド>

Vercel Skills CLI（Cursor/Copilot/Windsurf）の場合は、リポジトリ URL を一致するブランチ（最新のメジャーバージョンには main、古いものには v{N}/main）に向けてください。

これを実行するタイミング

Umbraco バックオフィスのタスクの開始時に 1 回、コードを書く前に実行してください。エントリースキル（umbraco-quickstart、umbraco-backoffice、umbraco-extension-template）は、最初のステップとしてこのガードを参照しています。再実行はワークスペースが変化した場合にのみ行ってください。