WorkOS Widgets

ワークフロー概要

1. ユーザーリクエストからウィジェット対象を特定します (user-management、user-profile、admin-portal-sso-connection、admin-portal-domain-verification)。
2. 以下の順序でプロジェクトファイルをスキャンします:
   • パッケージ/依存関係マニフェスト
   • フレームワーク/ルーターエントリーポイント
   • 認証/トークンユーティリティ
   • スタイリング/コンポーネントパターン
3. references/detection.md を使用してスタック、データレイヤースタイル、スタイリング、コンポーネントシステム、パッケージマネージャーを検出します。
4. AuthKit/WorkOS の存在を確認します:
   • 検出された場合、続行します;
   • 検出されない場合、ユーザーに WORKOS_MODE=agent npx workos@latest install を実行するよう指示します。確認を待ってから続行します。
5. 検出が曖昧または矛盾している場合、1 つの焦点を絞った質問を行い、その後続行します。
6. 検出されたスタックとウィジェットに関連するリファレンスファイルのみを読み込みます。
7. スタック形状に基づいて統合を実装します:
   • ウィジェット UI が同じアプリに存在する場合、フロントエンドルート/ページ + ウィジェットコンポーネント
   • バックエンドファースト/マルチアプリアーキテクチャが検出された場合、トークンエンドポイント/サービス + クライアント統合サーフェス
8. 完成前にルーティング/配線、インポート、トークン/API 使用法を検証します。

正規入力

ユーザーリクエストから以下の入力を受け入れます (利用可能な場合):

• ウィジェットタイプ (またはリクエスト意図から推定)
• オプションのコンポーネントパス
• オプションのページ/ルートパス
• オプションのトークンエンドポイント/サービス設定
• オプションの制約 (例: 広範なリファクタリングを回避)

入力が不足している場合、既存のプロジェクト慣例と検出されたスタックから推定します。

検出と曖昧性プロトコル

• references/detection.md から検出ヒューリスティクスを適用します。
• 質問する前に探索します。マニフェストとルート/認証エントリーポイントをチェックした後も曖昧性が残る場合のみ質問します。
• 1 つの決定を解決する 1 つの具体的な質問を聞きます。
• ユーザーレスポンスがない場合、最も強い検出所有信号にデフォルト設定します。
• インストールが必要な場合、プロジェクトファイル/ロックファイルから検出されたパッケージマネージャーを使用します。

リファレンス読み込みマップ

常にこれらのコアリファレンスを読み込みます:

• references/detection.md
• references/token-strategies.md
• references/fetching-apis.md
• references/styling-and-components.md

React/TypeScript スタック (Next.js、React Router、TanStack Router、TanStack Start、Vite) の場合、また読み込みます:

• references/react-ts-standards.md

スタック固有のリファレンスガイダンスを読み込みます:

• Next.js: references/framework-nextjs.md
• React Router: references/framework-react-router.md
• TanStack Router: references/framework-tanstack-router.md
• TanStack Start: references/framework-tanstack-start.md
• Vite: references/framework-vite.md
• SvelteKit: references/framework-sveltekit.md
• Ruby: references/framework-ruby.md
• Python: references/framework-python.md
• Go: references/framework-go.md
• PHP: references/framework-php.md
• Java: references/framework-java.md
• 混合リポジトリ: references/framework-mixed-repositories.md

その後、正確に 1 つのウィジェットリファレンスを読み込みます:

• User Management: references/widget-user-management.md
• User Profile: references/widget-user-profile.md
• Admin Portal SSO Connection: references/widget-admin-portal-sso-connection.md
• Admin Portal Domain Verification: references/widget-admin-portal-domain-verification.md

グローバルウィジェットガイダンス

• references/fetching-apis.md のエンドポイントパス/メソッドを使用してウィジェット操作を実装します。リクエストボディを構築またはレスポンスを解析する場合、関連するウィジェットのスキーマについて OpenAPI spec をクエリします:

  node references/scripts/query-spec.cjs --widget <widget-name>
  

  --list を使用して利用可能なウィジェットグループを確認します。
• 読み込み、空、エラー状態を明示的でユーザーに見えるようにします。
• ミューテーション結果を見えるようにし、成功後に影響を受けたデータを更新/再度読み込みします。
• テーブル/リスト/アクション UI を既存のプロジェクト慣例に合わせます。
• 部分的/オプションデータに対して動作を回復力のあるものにし、脆弱な UI 前提を回避します。

コアガイドライン

• ホストプロジェクトと OpenAPI スキーマから既存のドメイン型を再利用します。モデル定義の重複を回避します。
• references/fetching-apis.md をパス、メソッド、スキーマクエリに使用してウィジェットリクエストを構築します。
• エンドポイント呼び出しに直接 fetch/HTTP 呼び出し (または同等のサーバー HTTP クライアント) を使用します。
• ウィジェットリクエストの一貫した認可レイヤーを実装します。必要に応じて機密エンドポイントのエレベートトークン処理を含みます。
• アプリが既に React Query または SWR を使用している場合、それらの直接呼び出しの周りのオーケストレーション/キャッシュレイヤーとして使用します。
• React/TypeScript ウィジェットコード品質期待については、references/react-ts-standards.md に従います。
• AuthKit/WorkOS が不足している場合、続行前にユーザーに WORKOS_MODE=agent npx workos@latest install を実行するよう指示します。WORKOS_MODE=agent はインストーラーを決定論的に保ちます (プロンプトなし、ブラウザなし、ホスト信頼なし); 出力を解析する必要がある場合は --json を渡します。
• 厳密に必要な場合のみ追加依存関係をインストールし、検出されたパッケージマネージャー/ツールを使用します。
• サーバー状態処理を選択されたデータレイヤーアプローチに合わせます。
• UI インタラクション状態には必要に応じてローカル状態/リデューサーを使用します。
• 既存のデザインシステムとスタイリング慣例を優先します。
• 広範な無関係なリファクタリングとグローバルスタイル書き換えを回避します。

完了要件

完了前に、すべての関連項目を検証します:

1. ウィジェットコンポーネントが存在し、コンポーネントレベルの統合がスコープ内にある場合 accessToken: string を受け入れます。
2. ルート統合がスコープ内にある場合、ルート/ページ配線が完了しています。
3. トークンソースが既存のアプリアーキテクチャと一致します (AuthKit クライアントフローまたはバックエンド WorkOS トークンフロー)。
4. API メソッドとパスがバンドルされた OpenAPI spec と一致し、データレイヤー使用法がプロジェクト慣例と一致します。
5. 必要なクエリ/ミューテーション フローに対してローディングおよびエラーブランチが存在します。

検証チェックリスト

1. エンドポイントパスと HTTP メソッドがバンドルされた OpenAPI spec から来ていることを確認します。
2. リクエスト/レスポンス処理が spec のスキーマ期待に従っていることを確認します。
3. クエリ/ミューテーション無効化/リフェッチが成功したミューテーション後に必要な場合適用されることを確認します。
4. 空/エラー/ローディング状態が明示的でユーザーに見えることを確認します。
5. パッケージインストール (ある場合) が検出されたパッケージマネージャー/ツールを使用していることを確認します。
6. 実装が既存のコードベース慣例に沿っていることを確認します。
7. 既存のコンポーネントに className または style props を渡して組み込みスタイリングをオーバーライドしていないことを確認します。各コンポーネントをそのまま使用するか、独自の props API (variant、size など) を通じて使用します。