forgerock-to-ping-journey-migration

ForgeRock から Ping Journey SDK への移行

開発者が既存のアプリをレガシーな ForgeRock SDK から新しい Ping Identity Journey SDK に移行できるよう支援します。このスキルでは、コードベースをスキャンし、計画をプレビューしてから、コメントアウトして置き換える（黙って削除することはありません）慎重で監査可能な移行を進めます。ビルドを検証し、開発者がレビュー担当者に渡せるレポートも残します。

対応プラットフォーム

プラットフォーム	レガシーパッケージ	新しいパッケージ	リファレンス
Android（Kotlin）	org.forgerock:forgerock-auth (FRAuth/FRSession)	com.pingidentity.sdks:journey	android-migration.md
iOS（Swift）	ForgeRock/forgerock-ios-sdk (FRAuth/FRUser)	ForgeRock/ping-ios-sdk (PingJourney/PingOidc)	ios-migration.md
JavaScript/TypeScript	@forgerock/javascript-sdk	@forgerock/journey-client + @forgerock/oidc-client	javascript-migration.md

各リファレンスファイルには、変更前と変更後の対応関係（インポート、クラス、メソッド、パラメーターの変更）がすべて記載されています。検出されたプラットフォームに一致するファイルのみを読み込み、3 つすべてを事前に読まないでください。

起動するタイミング

ユーザーが ForgeRock の認証コードを Ping SDK に移行したいと示したら、「移行」という言葉を使っていなくても、このスキルを起動します。起動のきっかけとなる発言の例：「FRAuth から移行する必要があります」「これを journey-client に変換して」「ForgeRock との連携をアップグレードするには何が必要ですか」「FRSession.authenticate を新しい SDK に置き換えて」。判断に迷った場合は提案してください。この場合は少し積極的に促すのが適切です。ユーザーのディスク上にはすでにレガシーコードがあり、ForgeRock のサポート終了時に動かなくなるためです。

---

基本原則

開始前に以下を読んでください。以降の判断すべての指針となります。

1. レガシーコードを黙って削除しないでください。 開発者が grep や diff で確認し、ワンステップでロールバックできるよう、識別しやすいマーカーを付けてコメントアウトしてください。このマーカーにより、コードレビューでも変更内容が分かりやすくなります。
2. ビルドが常に動作する状態を保ってください。 移行前にビルドが失敗している場合は、まず修正を支援してください。そうしなければ、移行後の失敗がこのスキルによるものかどうか判断できません。
3. 曖昧さがある場合は一時停止してください。 レガシー SDK と新しい SDK はアーキテクチャが異なります（コールバック → コルーチン／async-await、静的設定 → ファクトリー関数、例外送出 → Result 型）。動作に影響する判断が必要な変換では、TODO(ping-migration): を残し、先に進む前に開発者に確認してください。
4. 編集前にプレビューしてください。 変更予定箇所の完全なリストをファイルごとにまとめ、何かに手を加える前に開発者に提示してください。計画の再生成は簡単ですが、不適切な一括変更を元に戻すのは大変です。
5. レポートで説明してください。 最終成果物は開発者が読むレポートです。後回しにせず、主要な成果物として扱ってください。

---

ワークフロー

以下のフェーズを順番に実行してください。黙って省略してはいけません。開発者がフェーズの省略を希望する場合は、その旨を明示する必要があります。

フェーズ 1 — プラットフォームの検出

対象プロジェクトが使用しているプラットフォームを特定します。以下を確認してください。

• Android：build.gradle、build.gradle.kts、settings.gradle*、gradle.properties、app/src/main/AndroidManifest.xml
• iOS：Package.swift、*.xcodeproj、*.xcworkspace、Podfile、Podfile.lock
• JavaScript/TypeScript：package.json（dependencies に @forgerock/javascript-sdk または @forgerock/ping-protect が含まれるか確認）

モノレポには複数のプラットフォームが含まれる場合があります。その場合は、続行する前に、このセッションで移行する対象を開発者に確認してください。

フェーズ 2 — コンテキストの収集

プロジェクトのルートにある AGENTS.md と CLAUDE.md（およびプラットフォームに関連するサブプロジェクトのルートにあるもの）を読みます。これらのファイルには通常、エントリーポイントの情報、認証モジュールの場所、カスタムビルドコマンド、推奨される規約が記載されており、安全な移行に欠かせません。

どちらのファイルも存在しない場合は、agents-template.md をひな形として AGENTS.md の作成を提案します。プロジェクトの構成、主要な言語、ビルドコマンド、既存の認証コードの場所など、確認できる内容をもとに記入します。保存する前に、開発者に確認または修正してもらいます。このファイルは今回の移行だけでなく、今後の作業にも役立つため、少し手間をかける価値があります。

開発者が断った場合は、ファイルなしで作業を進めますが、その旨を最終レポートに記載します。

フェーズ 3 — 事前ビルドチェック

変更を加える前に、現在の状態でアプリをビルドできることを確認します。開発者に次のように尋ねます。

"今ビルドを実行して、問題のないベースラインであることを確認しますか。それとも、すでにビルドできると分かっていますか？"

実行を希望する場合、または不確かな場合は、適切なコマンドを実行します（下記のビルドコマンドを参照）。ビルドに失敗した場合は、ここで停止します。まず既存の問題を解決してください。壊れたベースラインの上では安全に移行できません。ビルドが成功したら再開します。

「ビルドできると信じて任せる」と開発者が言った場合は、そのまま進めます。ただし、ベースラインチェックを省略する選択をしたことをレポートに記録します。

フェーズ 4 — 移行範囲の確認

開発者に次のように尋ねます。

"プロジェクト全体をスキャンしますか。それとも、特定の領域（例：単一のファイル、機能モジュール、ログインフロー）を移行しますか？"

部分的な範囲を希望する場合は、それに従います。部分的な範囲はよくある正当な選択です。チームがモジュールごとに段階的な移行を希望する場合もあります。部分的な範囲の場合は、スキャンするファイルやディレクトリを正確に確認してから進めます。

フェーズ 5 — レガシーな使用箇所のスキャン

Grep と Read を使い、選択した範囲におけるレガシー SDK の使用状況を一覧にします。参照ファイルには、検索すべきレガシーシンボルがすべて記載されています。検索の主な対象は次のとおりです。

• Android: FRSession、FRUser、FRAuth、NodeListener、FROptions、FRDeviceCollector、import org.forgerock.android、WebAuthRegistrationCallback、DeviceBindingCallback、FRListener、PingOneProtect*
• iOS: FRAuth、FRSession、FRUser、FROptions、import FRAuth、import FRCore、WebAuthnRegistrationCallback、WebAuthnAuthenticationCallback、SelectIdPCallback、FRGoogleSignIn、FRFacebookSignIn、FRCaptchaEnterprise、完了ハンドラースタイルの Node.next { ... }
• JavaScript: @forgerock/javascript-sdk、Config.set、FRAuth.start、FRAuth.next、FRUser.logout、UserManager.getCurrentUser、TokenManager.getTokens、TokenStorage、FRWebAuthn、CallbackType、FRCallback、FRStep、@forgerock/ping-protect

次の項目も一覧にします。

• 依存関係ファイル — 更新が必要な宣言を把握するため、build.gradle*、Package.swift、Podfile、package.json を確認します。
• マニフェスト／設定ファイル — 新しい SDK で異なる設定が必要な場合に備え、AndroidManifest.xml のリダイレクト URI、iOS の Info.plist の URL スキーム、JS の index.html などを確認します。
• テストファイル — 認証設定コードが重複していることが多いため、同時に移行する必要があります。

フェーズ 6 — 計画の提示

編集を始める前に、調査結果を開発者に提示します。次の構成にします。

## Migration plan (preview)

Platform(s): Android
Scope: app/src/main/java/com/example/auth/**

Dependency changes (1 file):
  - app/build.gradle.kts — remove org.forgerock:forgerock-auth, add com.pingidentity.sdks:journey

Code changes (4 files, 12 sites):
  - app/src/main/java/com/example/auth/AuthManager.kt — 5 sites
      line 23: FROptionsBuilder.build { ... } → Journey { ... }
      line 41: FRSession.authenticate → journey.start
      line 56: NodeListener<FRSession> → Node sealed-class handling
      line 78: NameCallback setter → property assignment
      line 102: FRUser.getCurrentUser()?.logout() → journey.user()?.logout()
  - app/src/main/java/com/example/auth/LoginViewModel.kt — 4 sites
      ...

Manual review items (2):
  - app/src/main/java/com/example/auth/DeviceHelper.kt:87 — uses custom FRDeviceCollector
    composition; the new API uses DefaultDeviceCollector. I'll add a TODO but
    want your input on whether the custom collectors are still needed.
  - app/src/main/AndroidManifest.xml:34 — redirect URI scheme matches legacy
    sample; confirm it still applies to your new OIDC client.

Proceed? (y / partial / no)

開発者が計画を編集できるようにします。ファイルを対象から外したり、項目を先送りしたり、範囲を調整したりする場合があります。承認を得るまで、フェーズ 7 を開始してはいけません。

フェーズ 7 — 変更を適用する

各サイトで、レガシーコードをコメントアウトし、その直下に新しいコードを挿入します。grep 一回ですべての変更を見つけられるよう、次のマーカー規則を使用してください。

Android / iOS（Kotlin/Swift の行コメント）：

// [ping-migration] BEGIN legacy — safe to delete after verifying the migration
// FRSession.authenticate(context, "Login", nodeListener)
// [ping-migration] END legacy
val node: Node = journey.start("Login")

JavaScript/TypeScript（行コメント）：

// [ping-migration] BEGIN legacy — safe to delete after verifying the migration
// const step = await FRAuth.start();
// [ping-migration] END legacy
const result = await journeyClient.start({ journey: 'Login' });

開始マーカーと終了マーカーを両側に置くのはなぜでしょうか？ 1 行のコメントは diff で見落としやすいですが、対になるマーカーを使えば境界が明確になり、後で開発者が複数行を一度に選択してブロックを削除できます。

依存関係ファイル。 編集前に、新しい依存関係がすでに宣言されているか確認してください（開発者が移行を開始している場合があります）。宣言済みの場合は、その項目をスキップし、レポートに記載してください。変更する場合は、同じマーカー規則でレガシー行をコメントアウトし、その下に新しい宣言を追加してください。コメントをサポートしていない package.json の場合は、dependencies をその場で更新し、削除したパッケージと追加したパッケージの両方をレポートの「Dependencies」セクションに記載してください。

変換が曖昧な場合。 対応付けの判断が必要な場合（たとえば、コールバックベースのレガシーフローを、ファイル内の別の箇所にあるコルーチン／async ブロックに変更する必要がある場合や、NodeListener.onException を ErrorNode／FailureNode に分割するような動作変更がある場合）は、推測で進めないでください。曖昧な点を説明する TODO(ping-migration): コメントを挿入し、変更を加える前にチャットで開発者に確認してください。

// TODO(ping-migration): onException previously handled both API errors and
// unexpected exceptions. The new SDK splits these into ErrorNode (API errors,
// has .message) and FailureNode (exceptions, has .cause). Do you want to
// preserve a single error path, or branch on node type for different UX?

問題の切り分けを容易にし、レポートの整合性を保つため、ファイルは一度に 1 つずつ作業してください。

フェーズ 8 — ビルドの事後確認

開発者に次のように確認してください。

「ビルドを実行して確認する準備はできていますか？（数分かかる場合があります。）」

はいの場合は、適切なビルドコマンドを実行してください。ビルドが成功したら、フェーズ 9 に進みます。

失敗した場合：

1. エラーを提示します。
2. 原因を診断します。変換エラー、依存関係の不足、見落としたマニフェスト／plist の変更、または既存の無関係な問題でしょうか？
3. 修正を繰り返し、ビルドが成功するまで再ビルドします。
4. ビルドが失敗している状態で、移行が完了したと決して宣言しないでください。 ビルドを成功させられない場合（クラウド認証情報が必要な場合や、開発者による解決が必要な実行時の問題がある場合など）は、その旨を明確に伝えてください。✅ を付けてタスクを完了扱いにしてはいけません。

開発者がビルドの実行を辞退した場合は、レポートの先頭に次のバナーを明記してください。⚠️ Build verification was skipped — migration is not yet confirmed to compile.

フェーズ 9 — 移行レポートを作成する

プロジェクトのルート（または部分移行の場合は移行したサブプロジェクトのルート）に MIGRATION_REPORT.md を作成してください。構成には report-template.md を使用してください。レポートには以下を含める必要があります。

1. 概要 — 移行したプラットフォーム、対象範囲、日付、ビルド状況。
2. 依存関係の変更 — 追加、削除、またはコメントアウトしたままのパッケージ。
3. ファイルごとの変更 — パス、行番号（レガシー → 新規）、各変更の簡潔な説明。
4. 手動レビュー項目 — 残したすべての TODO(ping-migration): と、ファイル名および行番号。
5. スキップした項目 — 開発者が移行しないことを選択した項目。
6. ロールバック手順 — すべてのマーカーを見つける grep コマンドと、削除手順。
7. 次の手順 — 開発者が動作を確認したら、grep -R "\[ping-migration\] BEGIN legacy" を実行し、コメントアウトしたブロックを削除します。

レポートは単独で読んでも理解できる内容にしてください。セッションに参加していないレビュー担当者が、何がなぜ変更されたのかを把握できる必要があります。

---

ビルドコマンド

プロジェクト標準のビルドコマンドを使用します。AGENTS.md で指定されている場合は、そちらを優先してください。指定がない場合は、以下を使用します。

プラットフォーム	コマンド（プロジェクトの構成に合わせて調整）
Android	./gradlew assembleDebug（または ./gradlew :app:assembleDebug）
iOS（SPM）	xcodebuild -scheme <scheme> -destination 'generic/platform=iOS Simulator' build
iOS（CocoaPods）	pod install の後に xcodebuild -workspace <name>.xcworkspace -scheme <scheme> build
JavaScript	package.json で判定 — ロックファイルに応じて npm run build、pnpm build、または yarn build

プロジェクトの構成が異なる場合は、必ず開発者に正確なコマンドを確認してください。iOS ではスキームと実行先がプロジェクトごとに異なるため、初回ビルドの前に確認してください。

---

常に手動で対応が必要な項目

これらの変換は安全に自動化できません。必ずレポートで明示してください。

• エラー処理の形式変更。 レガシー SDK は例外をスローしますが、新しい SDK は Result 型や sealed 型を返します。開発者はこの境界で UX（再試行するか、何もせず失敗させるか、ログアウトするかなど）を見直したいことがよくあります。
• トークンストレージ。 レガシーアプリがカスタムストアにトークンを書き込んでいた場合、新しい SDK のデフォルトのストレージ動作は異なる可能性があります。ストレージの選択を確認してください。
• リダイレクト URI。 新しい OIDC クライアントでは、異なる URI スキームが必要になる場合があります。マニフェストや plist の設定を、新しい OIDC クライアントの設定と照合してください。
• テストフィクスチャ。 モックの FRListener 実装や偽の FRStep オブジェクトは機械的には変換できません。新しい型システムに合わせて書き直す必要があります。
• ソーシャル／IdP ハンドラー。 レガシーの FRGoogleSignIn、FRFacebookSignIn などは、個別の PingExternalIdP* モジュールに置き換えられています。アプリレベルの設定（Google Client ID、Facebook App ID）は、Ping で新たに設定する必要がある場合があります。
• デバイスバインディングと FIDO。 クラス名とフローが変更されています（WebAuthRegistrationCallback → FidoRegistrationCallback、DeviceBindingCallback.bind(...) のシグネチャは異なります）。適用前に、必ず差分を開発者に提示してください。

---

してはいけないこと

• 開発者が急いでいても、プレビューなしで移行を実行しないでください。プレビューが合意事項です。
• レガシーコードをそのまま削除しないでください。コメントアウトして置き換えるパターンが、ロールバック計画です。
• ビルドコマンドを独断で選ばないでください。特にスキームや実行先が異なる iOS では、開発者に確認してください。
• いずれかのフェーズを省略した場合や、ビルドが失敗した場合に、成功を宣言しないでください。レポートにはその旨を分かりやすく記載してください。
• 移行の一環として、シェルスクリプトや言語固有のスクリプトを生成しないでください。開発者の環境に Node、Python、Ruby がない場合があります。ファイルツールで直接編集し、プロジェクト標準のビルドツールのみを実行してください。

---

参照ファイル

• android-migration.md — Android（Kotlin）のレガシー版から新しい版への完全なマッピング。
• ios-migration.md — iOS（Swift）のレガシー版から新しい版への完全なマッピング。
• javascript-migration.md — JavaScript／TypeScript のレガシー版から新しい版への完全なマッピング。
• agents-template.md — プロジェクトに AGENTS.md がない場合に生成するためのテンプレート。
• report-template.md — 最終的な MIGRATION_REPORT.md の構成。

検出されたプラットフォームに関連する参照ファイルのみを読み込んでください。移行マッピングは長いため、すべてを事前に読み込まないでください。