canvas-component-push

プロジェクトの種類

このスキルを適用する前に、package.json に @drupal-canvas/headless という依存関係、または @drupal-canvas/headless- で始まる依存関係があるか確認してください。該当する依存関係がある場合、これは Canvas Headless コードベースです。まず canvas-headless を読んでください。この場合、プッシュの動作は通常と異なります。

• CLI は Headless SDK を自動的に検出し、すべてのコンポーネントを type: external としてプッシュします。対象はメタデータのみで、コンポーネントコードは含まれません。これは想定どおりの動作であり、CLI にログが記録されます。
• 外部コンポーネントはプッシュによって作成および更新されますが、削除されることはなく、canvas pull では除外されます。
• 以下の依存関係の再試行に関するガイダンスは、外部コンポーネントには適用されません。インポートはプッシュされないため、依存関係の順序による失敗は発生しません。

以下のセットアップゲート、認証の処理、接続失敗時のルールは、どちらの場合も変更なく適用されます。該当する依存関係がない場合、これは Canvas でレンダリングされる React コードベースです。コンポーネントは React（index.jsx／.tsx）で記述され、このスキルのすべての内容が記載どおり適用されます。プロジェクトの種類はこの 2 つだけです。

有効化の条件

ユーザーが Canvas へのコンポーネントのプッシュ、公開、同期、またはアップロードを明示的に依頼した場合にのみ、このスキルを実行してください。

コンポーネントの編集、検証、またはタスクの完了後に、このスキルを自動で実行しないでください。

プッシュする前に、ユーザーが対象サイト向けに Drupal Canvas CLI をインストールし、設定済みであることを確認してください。

セットアップゲート

プッシュコマンドを実行する前に、次の手順を行ってください。

1. サポートされている方法で Canvas CLI の認証が設定されていることを確認します。ローカルプロジェクトで作業する場合は、プロジェクトのルートにある .env ファイルを優先してください。CLI はシェルの環境変数、~/.canvasrc、および ~/.config/drupal-canvas/oauth.json に保存される対話型ログインのトークン（npx canvas login によって書き込まれます）も読み取ります。
2. CANVAS_SITE_URL が設定されていることを確認します。
3. 主要な認証方法（環境変数を優先）： 次のいずれか 1 つ以上を設定します。
   • CANVAS_ACCESS_TOKEN — .env またはシェルで設定され、空でないこと（多くのセットアップで最も簡単な方法です）、または
   • CANVAS_CLIENT_ID と CANVAS_CLIENT_SECRET — 両方が設定されていること（CI やサービス向けのアクセスで一般的です）。
4. トークンが設定されていない場合のフォールバック： CANVAS_SITE_URL が設定されているものの、.env またはシェルにアクセストークンもクライアント認証情報も見当たらない場合は、ブラウザーを使用した Canvas サインインのために npx canvas login を実行してください。トークンは ~/.config/drupal-canvas/oauth.json に保存されます（サイト URL をキーとして使用します）。Canvas Login を使った対話型ログイン を参照してください。このフォールバックを試すか、不要と判断するまでは、認証が未設定だとみなさないでください。
5. CANVAS_ACCESS_TOKEN が設定されている場合は、それを有効な認証方式として扱います。OAuth クライアント認証情報のフローは完全にスキップされ、CANVAS_CLIENT_ID、CANVAS_CLIENT_SECRET、CANVAS_SCOPE は無視されます。
6. 上記の確認を終えても必要な設定が不足している場合は、作業を中止し、まずセットアップを完了するようユーザーに依頼してください。
7. セットアップ手順を推測しないでください。 ユーザーに公式ドキュメントを案内します。
   • Drupal Canvas OAuth モジュールのセットアップ： https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
   • Drupal Canvas CLI パッケージ／ドキュメント： https://www.npmjs.com/package/@drupal-canvas/cli
8. ユーザーがセットアップの完了を確認してから、作業を続けてください。

プッシュの実行

コンポーネントの作業が完了し、検証も済んだら、現在の Canvas の変更を Canvas にプッシュするかユーザーに確認します。canvas push --yes は現在の変更をすべてプッシュします。特定のコンポーネントを選択する機能はありません。作業ツリーに無関係または未検証の Canvas の変更がある場合は、処理を中断し、どのように進めるかユーザーに確認してください。適切なパッケージマネージャーを使用してください。たとえば、npm を使用している場合は、次のコマンドを実行します。

npx canvas push --yes

ページが含まれていて、外部 URL を参照する画像 props がある場合、最初のプッシュは「Some pages contain media that references external URLs」のようなエラーで失敗することがあります。メディアの照合が済むまでは、これは想定される動作です。

作成したページでサポートされる画像ソース：

• 外部の http:// または https:// URL
• data:image/... URL

照合に対応する画像形式：.jpg、.png、.gif、.webp、.avif。

CLI によるローカルファイルシステムからの画像アップロードには対応していません。

ページのメディア照合

画像 props を含むページを扱う場合：

1. 次のようにページをプッシュします。

   npx canvas push --yes --include-pages
   

2. Canvas が外部メディア参照を報告した場合、次を実行します。

   npx canvas reconcile-media
   

3. ページを再度プッシュします。

   npx canvas push --yes --include-pages
   

4. ページをプルして、解決済みの入力をローカルに同期します。

   npx canvas pull --include-pages
   

照合とプルの後、次のようにページ JSON が更新されることがあります。

• 画像 prop は同じオブジェクト構造を保ちながら、解決済みの src、alt、width、height を含むようになります
• target_id や source_url などの値を持つ _provenance オブジェクトが追加されることがあります

メディアを意図的に置き換える場合を除き、後の編集でも解決済みの画像 props と _provenance を保持してください。

プルによって、安全なコンポーネント getter 呼び出しがコンテキストフックに移行されることもあります。ワークフローの完了と見なす前に、nullable な結果を含め、ソースの変更と移行診断を確認してください。プルしたコンポーネントの移行に従ってください。

プッシュの失敗への対処

デフォルトの動作：明らかな接続またはセットアップの失敗を除き、失敗したプッシュは必ず再試行します。

Canvas アプリの接続がすでに機能していることを示す失敗（依存関係や順序に関連するコンポーネントエラーなど）の場合は、プッシュを再試行してください。接続またはセットアップの失敗の場合は、再試行しないでください。

接続またはセットアップの失敗：中断して、再試行しない

プッシュが認証、認可、またはネットワーク／接続エラーで失敗した場合は、処理を中断し、まずセットアップを完了または確認するようユーザーに依頼してください。これには、無効な認証情報、未認証／禁止の応答、DNS の問題、接続拒否、ホストに到達できない、Canvas に到達する前のリクエストタイムアウト、TLS／SSL のハンドシェイク／証明書の失敗などのエラーが含まれます。

CANVAS_ACCESS_TOKEN が有効な認証モードの場合、トークン関連の失敗はセットアップの失敗として扱ってください。無効または期限切れのトークンや、トークンが受け付けられていないことを示す 401 応答などのエラーでは、再試行しないでください。

公式セットアップドキュメントを案内してください。

• Drupal Canvas OAuth モジュールのセットアップ： https://git.drupalcode.org/project/canvas/-/tree/1.x/modules/canvas_oauth#2-setup
• Drupal Canvas CLI パッケージ／ドキュメント： https://www.npmjs.com/package/@drupal-canvas/cli

まず、CLI が使用している設定ソース（たとえば、シェルの環境変数、.env、~/.canvasrc、または対話型ログインの設定／セッション）から、CANVAS_SITE_URL と有効なトークンまたはクライアント認証情報の値を確認するようユーザーに依頼してください。これらが未設定または無効な場合は、フォールバックとして npx canvas login を実行するよう案内してください（対話型トークンを更新する場合は、再度実行します）。セットアップの更新が完了したことをユーザーが確認してから、プッシュを再試行してください。

依存関係に関連する失敗

複数の新しいコンポーネントをプッシュするときに、一方のコンポーネントが別のコンポーネントに依存している場合 （例：hero が heading をインポートする）、コンポーネントが存在しないというメッセージが表示され、プッシュに失敗することがあります。これは、別のコンポーネントを含むコンポーネントが、その依存先より先にプッシュされた場合に発生します。

これは想定された動作です。 プッシュコマンドを再実行してください。以降の試行では、前回の実行で正常にプッシュされた依存先がすでに存在するため、依存するコンポーネントも正常にプッシュできるようになります。

例：

1. 1回目のプッシュ：heading がまだ存在しないため hero は失敗しますが、heading は正常にプッシュされます。
2. 2回目のプッシュ：heading が存在するため、hero は正常にプッシュされます。

複数回再試行してもプッシュに失敗し続ける場合は、必要な依存コンポーネントがすべて現在のローカル変更に含まれているか、すでに Canvas に存在していることを確認してください。