RubyGems - copy_tuner_client - Versions diffs - 2.2.0 → 2.2.1 - Mend

copy_tuner_client 2.2.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +2 -235
data/README.md +42 -5
data/lib/copy_tuner_client/configuration.rb +37 -12
data/lib/copy_tuner_client/version.rb +1 -1
data/skills/copy-tuner-to-locales-cleanup/SKILL.md +5 -5
data/skills/copy-tuner-to-locales-migrate-prefix/SKILL.md +69 -37
data/skills/copy-tuner-to-locales-migrate-prefix/references/example-touchpoints.md +31 -10
data/skills/copy-tuner-to-locales-migrate-prefix/scripts/migrate_prefix.rb +144 -6
data/spec/copy_tuner_client/configuration_spec.rb +173 -0
data/spec/copy_tuner_client/warden_integration_spec.rb +95 -0
data/spec/support/middleware_stack.rb +39 -5
metadata +2 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fb9ea1caf782db8dac7ded7d77803a61586b5369b221b62d34e9e0290c58b06
-  data.tar.gz: ad4723a7fe5af378f68af6f786644cc549a1ebbe2523c3424af8fdaba5381433
+  metadata.gz: 6a9a2fe07a403679fa3bf6d10c72c13fadcd31536af653a79b3e6d84e80c10ab
+  data.tar.gz: b3300594e38799ec7004f4c4fb0e35b051a447c6dd8b66ffb512bb59d7b851b2
 SHA512:
-  metadata.gz: 7a894e4afd8428064c4fef7dd34db7bdfaab23879b5fa3aaabc5921437a3a80b7cf036fac920f8bf76e7274141f5a522f8364a493797084e7fee879f435d7eb4
-  data.tar.gz: 34211866166e6491e7488a8f87aadc96810afcea2f3b5069ae2b29b4b9e5f0fe9a620556e3fd55d403ed419c9ab917c34f4fee0eafea90e889a7b6d5653b0540
+  metadata.gz: 5af9d06699d0361e360ea31dd4bb67ba04d2e711e0324ee9d85ee59914404ef905e173e7b6fd6ef81ede67773784fd4788ccb45fac7399ce57ad1b67d6d094ce
+  data.tar.gz: 2143f94b230219cae83f8d317f52ba338b282894178edce8129eac5382be76836209fbb29b8dd9e25ac96d3a91a6b93fa326fed4c426f9b2304b9b12d9233482

data/CHANGELOG.md CHANGED Viewed

@@ -1,235 +1,2 @@
-## Unreleased
-- **【後方互換性に影響】** `config.exclude_key_regexp` を削除しました。後継の `config.local_first_key_regexp`
-  を使ってください。両者は対象キーの形式が異なります（`exclude_key_regexp` は locale 付き `ja.views.foo`、
-  `local_first_key_regexp` は locale を除いた `views.foo`）。正規表現から locale プレフィックスを外して
-  移行してください。挙動も異なり、`local_first_key_regexp` は lookup 時に CopyTuner キャッシュをスキップして
-  ローカル YAML を優先します（完全分離）。
-- **【後方互換性に影響】** `config.project_id` を必須にしました。未設定のまま `configure`（`apply`）すると
-  `ArgumentError: project_id is required` で失敗します。これまで `project_id` 未設定時は `api_key` へ
-  フォールバックして deprecation 警告を出していましたが、このフォールバックは削除しました。initializer に
-  `config.project_id = <プロジェクト ID>` を設定してください。
-- Copyray オーバーレイのマーカー方式を刷新。訳文への HTML コメント `<!--COPYRAY key-->` 注入をやめ、
-  可視トークン `⟦CT:key⟧` を埋め込んだうえで `CopyrayMiddleware` が `data-copyray-key` 属性に変換し、
-  トークンを HTML から完全に除去するようになりました。最終配信 HTML にコメント・トークンは残りません。
-- **【後方互換性に影響】** `config.html_escape` 設定を削除しました。HTML の安全性判定は i18n 標準
-  （`.html` / `_html` で終わるキーのみ html_safe）に統一され、この設定は参照されなくなっていました（no-op）。
-  no-op だったため動作には影響しませんが、`config.html_escape = ...` を設定している initializer は
-  `NoMethodError` になるため、その行を削除してください。`html_escape = false`（全訳文を html_safe 扱いに
-  する旧互換挙動）に依存していたアプリは、`.html` / `_html` キー命名へ移行してください。
-- Copyray オーバーレイは平文・html_safe（`.html` / `_html` キー）どちらの訳文もハイライト対象です。マーカートークンの
-  区切り記号は HTML 特殊文字ではないため、平文訳文が ActionView でエスケープされてもトークンは無傷で残り、
-  `data-copyray-key` 属性へ正しく変換されます。`<head>` 内（title/meta）はトークンを除去するのみでオーバーレイ
-  非対象ですが、従来どおりリスト導線（CopyTuner バー）から編集できます。
-- **【後方互換性に影響】** `tt` ヘルパーを削除しました。マーカー方式の刷新で `t`（`translate`）が安全にマーカー
-  注入できるようになり、`tt` の存在理由は失われました。`tt` の呼び出しは `t` へ置き換えてください。`tt` を使い続けたい
-  アプリは、ビューヘルパーで `t` に委譲するだけの `tt` を自前で定義してください（gem 撤去後は `t` と実質同義）。
-## 0.16.1
-- Support for i18n@1.13.0
-- キーの相対パス指定とdefaultオプションを組み合わせた場合の不具合修正
-## 0.16.0
-- Railsエンジン内のviewではオリジナルのtヘルパが呼ばれるように修正
-## 0.15.1
-- tヘルパーにdefault引数が渡された場合に初期値として登録されない問題を修正
-## 0.15.0
-- Drop support for ruby 2.7
-## 0.14.1
-- Fix super call in define_method
-## 0.14.0
-- Add Support for good_job
-- Drop Support for Resque
-## 0.13.5
-- Rename assets
-## 0.13.4
-- Fix csp nonce
-## 0.13.3
-- Add `media="all"` attribute to stylesheet link tag
-## 0.13.2
-- Add `crossorigin="anonymous"` attribute to script tag
-## 0.13.1
-- Add `type="module"` attribute to script tag
-## 0.13.0
-- Drop support for ruby 2.6
-## 0.12.0
-- Add `config.ignored_keys` and `config.ignored_key_handler`
-## 0.11.0
-- Remove deprecated rescue_format option
-- Fix ruby@2.7 keyword warning
-## 0.10.0
-- Add copy_tuner:detect_html_incompatible_keys task
-## 0.9.0
-- Do not upload invalid type keys
-## 0.8.1
-- Fix bug in `CopyrayMiddleware`
-## 0.8.0
-- Change the default value of config.upload_disabled_environments
-## 0.7.0
-- Add config.upload_disabled_environments
-## 0.6.2
-- Add arguments to export task
-## 0.6.1
-- Fix ruby@2.7 keyword warning
-## 0.6.0
-- Drop support for ruby 2.4
-- Drop support for rails 5.1
-## 0.5.2
-- Do not upload invalid keys
-## 0.5.1
-- Do not upload downloaded keys
-## 0.5.0
-- Drop support for ruby 2.3
-- Add tt helper
-- Add copy_tuner:detect_conflict_keys task
-- Do not re-upload empty keys
-- Fix dual loading tasks
-- Remove config.copyray_js_injection_regexp_for_debug
-- Remove config.copyray_js_injection_regexp_for_precompiled
-- Download translation when initialization
-## 0.4.11
-- changes
-  - Fix hide toggle button on mobile device.
-## 0.4.10
-- changes
-  - Hide copyray bar on all media.
-## 0.4.9
-- changes
-  - Smaller toggle button.
-  - Hide toggle button on mobile device.
-## 0.4.8
-- changes
-  - Support passenger 5.3.x
-## 0.4.7
-- changes
-  - Compatibile with bullet gem (rewrap response with ActionDispatch::Response::RackBody)
-## 0.4.6
-- changes
-  - Performance imporovement (sync with server asynchronously)
-  - Add config.middleware_position
-## 0.4.5
-- changes
-  - Fix deprecated css.
-## 0.4.4
-- bug fix
-  - Don't upload resolved default values.
-## 0.4.3
-- bug fix
-  - Start poller thread regardless of puma mode. #39
-## 0.4.2
-- changes
-  - span tag is no longer added to translation text.
-## 0.4.1
-- bug fixes
-  - js injection failed if jquery is not used. #33
-  - Fix some js error. #34
-  - Wrong key is displayed if scoped option is used. #35
-- deprecation
-  - config.copyray_js_injection_regexp_for_debug is no longer needed.
-  - config.copyray_js_injection_regexp_for_precompiled is no longer needed.
-## 0.4.0
-- Remove jQuery dependency.
-## 0.3.5
-- Support Rails 5.1
-## 0.3.4
-- Use Logger to /dev/null as default when rails console
-## 0.3.3
-- Add config.locales. (#24)
-- Fix initialization order bug. (#25)
-## 0.3.2
-- Support I18n.t :scope option.
-- Update copyray_js_injection_regexp_for_debug.
-## 0.3.1
-- Add search box to copyray bar.
-- Add disable_copyray_comment_injection to configuration.
-## 0.3.0
-- Use https as default.
-- Download blurbs from S3.
-- Add toolbar.
-- "Translations in this page" menu.
+> [!NOTE]
+> 変更履歴は [GitHub Releases](https://github.com/SonicGarden/copy-tuner-ruby-client/releases) に移行済みです。

data/README.md CHANGED Viewed

@@ -62,20 +62,57 @@ CopyTuner で一元管理している翻訳を、`views.*` のような単位で
 アプリ独自の `number.*` キー（例 `number.gift_amount`）は対象外で、従来どおり CopyTuner で管理できます。
-## Claude Code スキル
+## Middleware の挿入位置
-`skills/copy-tuner/` に Claude Code 向けのスキルが含まれています。
+CopyTuner は開発環境で `RequestSync` / `CopyrayMiddleware` を Rack の middleware スタックに挿入します。`RequestSync` はリクエスト毎に CopyTuner サーバと同期し、`CopyrayMiddleware` はページ内のマーカー（`⟦CT:key⟧`）を除去・変換します。
-### copy-tuner スキル
+挿入位置は自動で決まるため、通常は設定不要です。Devise（Warden）を使っているアプリでは `Warden::Manager` の直前、それ以外の環境ではスタック末尾に挿入されます。
-i18n キーの操作を支援するスキルです。翻訳キーの検索・登録・確認などの依頼に自動的に使用されます。
+Devise 併用時に Warden の直前へ寄せるのは `throw :warden` の挙動に対応するためです。`throw :warden` は `Warden::Manager` の `catch(:warden)` までスタックを巻き戻すため、CopyTuner の middleware が Warden より内側にあると、認証エラー時のレスポンス（`Devise::FailureApp` が返す HTML）を受け取れず、Copyray のマーカーがページに残ってしまいます。
+位置を変えたい場合は `config.middleware_position` に `{ before: SomeMiddleware }` または `{ after: SomeMiddleware }` を指定すると、このデフォルトを上書きできます。
+```ruby
+CopyTunerClient.configure do |config|
+  # ...
+  config.middleware_position = { after: Rack::Runtime }
+end
+```
+指定した middleware がスタックに存在しない場合、Rails の起動時に例外（`No such middleware to insert before: ...` / `... insert after: ...`）が発生します。
+## Claude Code スキル
+`skills/` 以下に Claude Code 向けのスキルが含まれています。
 ```
-gh skill install SonicGarden/copy-tuner-ruby-client copy-tuner --scope project
+gh skill install SonicGarden/copy-tuner-ruby-client <スキル名> --scope project
 ```
+### copy-tuner スキル
+i18n キーの操作を支援するスキルです。翻訳キーの検索・登録・確認などの依頼に自動的に使用されます。
 詳細: [skills/copy-tuner/SKILL.md](skills/copy-tuner/SKILL.md)
+### copy-tuner-to-locales-migrate-prefix スキル
+copy_tuner が集中管理する i18n キーを、prefix（正規表現）単位で `config/locales` のローカル YAML 管理へ移行するスキルです。gem は残したまま特定 prefix だけをローカル化する「部分ローカル化」と、全 prefix を移して完全撤去する「全移行」の両方に使えます。明示的に呼び出したときのみ動作します。
+詳細: [skills/copy-tuner-to-locales-migrate-prefix/SKILL.md](skills/copy-tuner-to-locales-migrate-prefix/SKILL.md)
+### copy-tuner-to-locales-cleanup スキル
+`copy-tuner-to-locales-migrate-prefix` で全 prefix の移行が完了した後に、gem・初期化子・CI・deploy・ドキュメント・MCP 設定を一括撤去し、copy_tuner 依存を完全に取り除くスキルです。明示的に呼び出したときのみ動作します。
+詳細: [skills/copy-tuner-to-locales-cleanup/SKILL.md](skills/copy-tuner-to-locales-cleanup/SKILL.md)
+### copy-tuner-to-t-migrate スキル
+copy_tuner_client v2.0.0 で削除された独自ヘルパー `tt` の呼び出しを、Rails 標準の `t`（`translate`）へ置換するスキルです。機械的に安全な箇所は一括変換し、文字列加工や `label` の第一引数に渡している箇所は 1 件ずつ確認しながら置換します。破壊的な一括書き換えを含むため、明示的に呼び出したときのみ動作します。
+詳細: [skills/copy-tuner-to-t-migrate/SKILL.md](skills/copy-tuner-to-t-migrate/SKILL.md)
 Development
 =================

data/lib/copy_tuner_client/configuration.rb CHANGED Viewed

@@ -184,6 +184,7 @@ module CopyTunerClient
       self.local_first_key_regexp = nil
       self.project_id = nil
       self.download_cache_dir = Pathname.new(Dir.pwd).join('tmp', 'cache', 'copy_tuner_client')
+      self.middleware_position = default_middleware_position
       @applied = false
     end
@@ -357,6 +358,20 @@ module CopyTunerClient
       end
     end
+    # throw :warden は Warden::Manager の catch(:warden) までスタックを巻き戻すため、
+    # Warden より内側の middleware は @app.call の戻り値を受け取れず、Devise::FailureApp の
+    # 応答がマーカー除去を経ずにブラウザへ届いてしまう。これを避けるため Warden の直前を既定位置にする。
+    #
+    # 判定に Devise の有無も見るのは、warden を require するだけで Warden::Manager を
+    # スタックに積まない gem（authtrail 等）が存在するため。定数の有無だけで決めると
+    # そうしたアプリで insert_before が対象を見つけられず起動時例外になる。
+    # スタックへ積むのは Devise の railtie（config.app_middleware.use）である。
+    def default_middleware_position
+      return nil unless defined?(::Warden::Manager) && defined?(::Devise)
+      { before: ::Warden::Manager }
+    end
     def setup_middleware
       if enable_middleware?
         logger.info 'Using copytuner sync middleware'
@@ -372,23 +387,33 @@ module CopyTunerClient
       logger.info "Available locales: #{locales.join(' ')}"
     end
-    def insert_middleware # rubocop:disable Metrics/AbcSize
-      request_sync_options = {
+    def insert_middleware
+      # NOTE: 値の nil を除外するのは、{ before: SomeClass if cond } のように条件次第で nil が入る
+      # 書き方で従来は末尾 use にフォールバックしていた挙動を保つため（キーの有無だけで分岐すると
+      # insert_before(nil) が対象を見つけられず例外になる）。
+      case middleware_position
+      in { before: target } if target
+        middleware.insert_before(target, RequestSync, request_sync_options)
+        middleware.insert_before(target, CopyTunerClient::CopyrayMiddleware)
+      in { after: target } if target
+        # NOTE: insert_after(index, *) は insert(index + 1, *) を呼ぶため、同じ対象へ 2 回挿入すると
+        # 後から挿入した方が対象に近い位置に来て順序が反転する。逆順で呼ぶことで
+        # 外側→内側が RequestSync → CopyrayMiddleware に揃う。
+        middleware.insert_after(target, CopyTunerClient::CopyrayMiddleware)
+        middleware.insert_after(target, RequestSync, request_sync_options)
+      else
+        middleware.use(RequestSync, request_sync_options)
+        middleware.use(CopyTunerClient::CopyrayMiddleware)
+      end
+    end
+    def request_sync_options
+      {
         poller: @poller,
         cache:,
         interval: sync_interval,
         ignore_regex: sync_ignore_path_regex,
       }
-      if middleware_position.is_a?(Hash) && middleware_position[:before]
-        middleware.insert_before(middleware_position[:before], RequestSync, request_sync_options)
-        middleware.insert_before(middleware_position[:before], CopyTunerClient::CopyrayMiddleware)
-      elsif middleware_position.is_a?(Hash) && middleware_position[:after]
-        middleware.insert_after(middleware_position[:after], RequestSync, request_sync_options)
-        middleware.insert_after(middleware_position[:after], CopyTunerClient::CopyrayMiddleware)
-      else
-        middleware.use(RequestSync, request_sync_options)
-        middleware.use(CopyTunerClient::CopyrayMiddleware)
-      end
     end
     # project_id は必須。未設定なら明示的に失敗させる。

data/lib/copy_tuner_client/version.rb CHANGED Viewed

@@ -1,6 +1,6 @@
 module CopyTunerClient
   # Client version
-  VERSION = '2.2.0'.freeze
+  VERSION = '2.2.1'.freeze
   # API version being used to communicate with the server
   API_VERSION = '2.0'.freeze

data/skills/copy-tuner-to-locales-cleanup/SKILL.md CHANGED Viewed

@@ -64,9 +64,10 @@ bin/rails runner '
 > NOTE: ここで `export` を実行できるのは gem がまだ入っているから。完了判定は gem 撤去より**前**に行う。
 > 補助目印: migrate は prefix を移すたびにオリジナル（`0000_original_*.yml`）から該当サブツリーを削除するので、
-> 全移行完了時点で `0000_original_*.yml` はほぼ空（残るのは非表現値の隔離 `0005_rails_non_blurb.yml` 等のみ）に
-> なっているはず。`local_first_key?` のマッチ判定が主の関門で、ファイルが空かどうかは副次的な目視確認。
-> 食い違うとき（regexp は全マッチなのにオリジナルに blurb 化できるキーが残っている等）は削除漏れを疑う。
+> **全移行を経た場合**は `0000_original_*.yml` がほぼ空になっているはず（非表現値も `migrate_prefix.rb` が
+> 移行分側の `--out` へ再適用済みで、オリジナル側に隔離ファイルとして残ることはない）。`local_first_key?`
+> のマッチ判定が主の関門で、ファイルが空かどうかは副次的な目視確認。食い違うとき（regexp は全マッチなのに
+> オリジナルに blurb 化できるキーが残っている等）は削除漏れを疑う。
 ### 2. 最終不正キーチェック
@@ -129,8 +130,7 @@ copyray コメント注入も消える。あわせて `config/environments/*.rb`
 - copy_tuner 専用の deploy ワークフローファイル（main push で翻訳をデプロイする専用ファイル）… 丸ごと削除。
 - AI エージェント用ワークフローの `mcp__copy-tuner__*` allowedTools 許可 … 削除。
-- CI の「翻訳を export するステップ」… migrate-prefix の初回で削除済みのはず。**まだ残っていれば**ここで削除する
-  （`git grep copy_tuner .github/` で確認）。
+- CI の「翻訳を export するステップ」… ここで削除する（`git grep copy_tuner .github/` で確認）。
 ### 6. deploy / 起動スクリプトを撤去

data/skills/copy-tuner-to-locales-migrate-prefix/SKILL.md CHANGED Viewed

@@ -2,24 +2,33 @@
 name: copy-tuner-to-locales-migrate-prefix
 description: >-
   copy_tuner（CopyTuner / copy_tuner_client）で集中管理している i18n データを、prefix（正規表現）単位で
-  Rails 標準の config/locales（YAML）管理へ段階移行するスキル。gem の local_first_key_regexp を使い、
-  1 回につき 1 prefix をローカルへ寄せて regexp に積み上げる。全 prefix 完了後の gem 撤去は
-  copy-tuner-to-locales-cleanup スキルで行う。
+  Rails 標準の config/locales（YAML）管理へ移すスキル。gem の local_first_key_regexp を使うので、
+  gem を残したまま特定 prefix だけをローカル管理にできる（部分ローカル化）。1 回の実行で 1 prefix。
+  全 prefix を移して gem ごと撤去したい場合は繰り返し、完了後 copy-tuner-to-locales-cleanup スキルへ進む。
+  対象 prefix はスキル引数で指定でき、未指定なら export を俯瞰して選定する。
 disable-model-invocation: true
 ---
-# copy_tuner → config/locales 段階移行スキル（prefix 単位）
+# copy_tuner → config/locales prefix 単位ローカル化スキル
-copy_tuner（`copy_tuner_client` gem）で集中管理している i18n データを、**prefix（正規表現）単位で**少しずつ
-Rails 標準の `config/locales` 配下の YAML 管理へ移していくためのワークフロー。**1 回の実行で 1 prefix だけ**
-移行し、これを繰り返す。全 prefix の移行が完了したら `copy-tuner-to-locales-cleanup` スキルで gem・CI・
-deploy・docs・MCP をまとめて撤去する。
+copy_tuner（`copy_tuner_client` gem）で集中管理している i18n データを、**prefix（正規表現）単位で**
+Rails 標準の `config/locales` 配下の YAML 管理へ移すためのワークフロー。**1 回の実行で 1 prefix だけ**扱う。
+使い方は 2 つある:
+- **部分ローカル化** — 特定 prefix だけを恒久的に `config/locales` 管理にする。**gem は残したまま**で、
+  CopyTuner 管理と locales 管理の二層が**定常状態**になる。
+- **全移行** — 上記を全 prefix ぶん繰り返す。全 prefix の移行が完了したら
+  `copy-tuner-to-locales-cleanup` スキルで gem・CI・deploy・docs・MCP をまとめて撤去する。
+**どちらの用途でもこのスキルがやること（手順 0〜10）は同一**で、差は「何回回すか」と「最後に cleanup へ
+進むか」だけ。
 このスキルは**特定のリポジトリに依存しない**。project_id・ファイルパス・CI 構成はプロジェクトごとに異なるので、
 固有値を覚えるのではなく**毎サイクル、自分が編集する箇所（initializer の regexp・config/locales）を探索して
 見つけ直す**（手順 2）。種別ごとの典型例は `references/example-touchpoints.md` を参照。
-## なぜ prefix 単位で段階移行するのか
+## なぜ prefix 単位で切るのか
 一発で全 i18n をローカル化すると、移行漏れ（ローカル YAML に書き忘れたキー）が**一斉に未訳化**して事故になる。
 prefix 単位なら、移した範囲だけが影響を受け、移行漏れはその範囲の未訳として小さく顕在化する。安全な prefix から
@@ -38,11 +47,21 @@ prefix 単位なら、移した範囲だけが影響を受け、移行漏れは
 - マッチしないキーは従来どおり CopyTuner キャッシュ優先 → 無ければローカル、という動作のまま。
 - regexp は**単一**（配列非対応）。複数 prefix は `Regexp.union` で 1 本に積み上げる。
-gem を残したまま regexp に prefix を足していくだけなので、移行途中でも CopyTuner と config/locales が安全に
-共存する。
+gem を残したまま regexp に prefix を足していくだけなので、CopyTuner と config/locales は安全に共存する。
+部分ローカル化ならこの共存が定常状態、全移行なら移行途中の状態としてそのまま成り立つ。
 ## ワークフロー（1 サイクル = 1 prefix）
+### 0. 対象 prefix の受け取り（引数）
+スキル引数で対象 prefix を渡せる（例: `devise` / `activerecord.attributes` / `views.users`）。
+- **引数あり** … それを今回の対象とし、**手順 4 の選定はスキップ**する。ただし**手順 3 の全件 export は
+  実行する**（手順 6 の `--export` 入力として必須なので省けない）。
+- 引数の prefix が export に**存在しなければ**、その旨をユーザーに報告して中断する（手順 6 のスクリプトも
+  同じ条件で異常終了するが、手順 3 の時点で気づけるほうが早い）。
+- **引数なし** … 従来どおり手順 4 の基準で 1 つ選び、**選定結果をユーザーに提示してから**手順 5 へ進む。
 ### 1. gem 前提確認
 `local_first_key_regexp` が使えるバージョンの `copy_tuner_client` が入っているか確認する。
@@ -65,14 +84,13 @@ grep 結果はセッションをまたいで残らない（複数セッション
 git grep -nI 'local_first_key_regexp' -- ':!vendor' ':!tmp' ':!node_modules'
 ls config/locales
-# 初回だけ触る（手順 9・10 用）: CI の export ステップと i18n 方針ドキュメント
-git grep -nI -e 'copy_tuner:export' -e 'CopyTuner' -- '.github/' 'doc/' 'CLAUDE.md'
+# 手順 9 用: i18n 方針ドキュメント
+git grep -nI 'CopyTuner' -- 'doc/' 'CLAUDE.md'
 ```
 - 手順 6・7 で毎回触る **initializer の `local_first_key_regexp`** の位置と、**`config/locales/`** の採番慣習
   （例: `00_`・`10_`）を確認する。
-- 手順 9（CI の export ステップ削除）・手順 10（方針ドキュメントの中間状態更新）で**初回だけ**触る箇所も
-  ここで場所だけ押さえる。
+- 手順 9（i18n 方針ドキュメントの更新）で触る箇所も、ここで場所だけ押さえる。
 #### 2-1. （初回のみ）既存 locales を `0000_original_` プレフィックスへリネーム
@@ -101,8 +119,12 @@ cleanup は自前で touchpoint を grep し直す。**このスキルでそれ
 ### 3. 残 prefix の把握
-全件を export して俯瞰し、移行済み（現在の `local_first_key_regexp` がマッチする）prefix と未移行 prefix を
-一覧化する。export は一時ファイルへ書く（`tmp/` 等の捨て場）。
+全件を export して俯瞰し、ローカル化済み（現在の `local_first_key_regexp` がマッチする）prefix と
+copy_tuner 管理のまま残っている prefix を一覧化する。export は一時ファイルへ書く（`tmp/` 等の捨て場）。
+対象 prefix が引数で指定されている場合、この一覧化は**対象 prefix が export に存在することの確認と規模把握**の
+ためになる（選定は不要）。いずれの場合も `rake copy_tuner:export` の**実行自体は必須**で、出力は手順 6 の
+`--export` 入力になる。
 ```bash
 bundle exec rake copy_tuner:export[tmp/copy_tuner_all.yml]
@@ -114,7 +136,10 @@ bundle exec rake copy_tuner:export[tmp/copy_tuner_all.yml]
 ### 4. 対象 prefix の選定
-残 prefix から **1 つ**選ぶ。影響が小さく構造が安定したものから始め、最後に大物（`views`）を回す:
+**引数で prefix が指定されている場合はこの手順をスキップ**し、手順 5 へ進む。
+残 prefix から **1 つ**選ぶ。以下の順序は**安全度の目安**で、影響が小さく構造が安定したものから始め、最後に
+大物（`views`）を回す:
 1. **gem 由来（最安全・先行）**: `devise` / `good_job` / `ice_cube` / `restrict_dependent_destroy` 等。
    値が安定しアプリ実装に依存しにくい。
@@ -123,8 +148,8 @@ bundle exec rake copy_tuner:export[tmp/copy_tuner_all.yml]
 3. **バリデーションメッセージ**: `activerecord.errors` / `activemodel.errors`。テストで検知しやすい。
 4. **モデル名・カラム名**: `activerecord.models` / `activerecord.attributes` / `activemodel.attributes` /
    `activerecord.enums`。プロジェクトの i18n 方針で「新規キー登録の例外」とされていることが多い
-   （プロジェクトの i18n 方針ドキュメントでそう規定されていることが多い）。**全撤去がゴールなのでこの prefix も最終的に移行対象に含める**。
-   例外規定の撤廃は cleanup で行う。
+   （プロジェクトの i18n 方針ドキュメントでそう規定されていることが多い）。**全 prefix を移行する場合は
+   この prefix も対象に含める**（例外規定の撤廃は cleanup で行う）。
 5. **画面テキスト（最大・最後）**: `views` / `text`。量が多く画面影響が大きいので最後に回し、画面確認の比重を
    上げる。1 回が大きすぎるなら `views.<controller>.` の 2 階層目で更に刻んでよい（regexp を `\Aviews\.users\.`
    のように書ける）。
@@ -197,6 +222,15 @@ prefix 内で `date.formats`（文字列・export 勝ち）と `date.order`（
 > 束ねている。スクリプトが中断した場合は `--out` のファイルだけが残る（オリジナルは無傷）ので、原因を直して
 > 再実行するか `--out` を消してやり直す。
+> NOTE: スクリプトは「対象 prefix の削除で実際に内容が変わったファイルだけ」を書き戻す（変更が無ければ
+> `File.write` をスキップする）。とはいえ `--originals-glob` の指定ミス等で意図しないファイルが対象に
+> 入っていないとも限らないため、実行後は必ず `git diff --stat config/locales/` で「対象 prefix を含む
+> はずのファイルだけに差分が出ているか」を確認する。対象 prefix と無関係なはずのファイルに差分が出て
+> いたら `git checkout -- <file>` で復元し、原因（`--originals-glob` や `--prefix` の指定）を見直す。
+> NOTE: 書き戻されたファイルでは**コメント・空行が失われる**（YAML 標準ライブラリはこれらを保持しない。
+> 値・エイリアス参照は保たれる）。`git diff` を見て惜しいコメントがあれば手で戻すこと。
 ### 7. local_first_key_regexp に prefix を追加
 initializer（`config/initializers/copy_tuner.rb` 等）の `CopyTunerClient.configure` ブロックで、
@@ -233,33 +267,31 @@ config.local_first_key_regexp = Regexp.union(
 > `bin/rails runner 'p CopyTunerClient.configuration.local_first_key?("<prefix>.foo")'` が `true`、隣接キー
 > （`reviews.*` 等）が `false` になることを確認しておくとよい。
-### 9. （初回のみ）CI の Export ステップを削除
+### 9. i18n 方針ドキュメントを更新
-CI で copy_tuner を export しているステップ（テストワークフロー内で `bin/rake copy_tuner:export` を走らせる類）
-は、**テスト起動前にローカルキャッシュを温める保険**にすぎない。
-このステップを削除すると、test 環境は initializer 起動時の `cache.download`（CopyTuner サーバから都度取得）
-だけになり、**本番と同じ挙動**になる。未移行 prefix も引き続きサーバから解決できるので、移行途中に消しても安全。
+i18n 方針ドキュメント（`doc/` 等）が「copy_tuner で管理／config/locales は使わない」のまま残ると、
+他の作業者や AI が「新規キーを copy_tuner と locales のどちらに足すか」を誤判断する。用途に応じて書き分ける
+（テンプレ文は `references/example-touchpoints.md` にある）:
-> WARNING: `config.disable_test_translation = true` は**入れない**こと。入れると test で CopyTuner DL が
-> 止まり、未移行 prefix が一斉に未訳化する。Export ステップ（保険）だけを消すのが正しい。
+- **部分ローカル化** … 「移行中」ではなく**恒久的な二層管理**として書く。「以下の prefix は config/locales
+  管理」「それ以外は copy_tuner 管理」「新規キーの追加先はどちら」の 3 点を明記する。
+- **全移行** … 「copy_tuner から config/locales へ段階移行中」＋現在ローカル化済みの prefix を列挙する
+  （最終形への書き換えは cleanup で行う）。
-### 10. ドキュメントの中間状態を更新
+いずれも prefix を増やすたびに列挙を更新する。
-i18n 方針ドキュメント（`doc/` 等）が「copy_tuner で管理／config/locales は使わない」のまま残ると、移行途中で
-他の作業者や AI が「新規キーを copy_tuner と locales のどちらに足すか」を誤判断する。**移行中であることと、
-現在ローカル化済みの prefix を明記する**。中間状態テンプレ文は `references/example-touchpoints.md` にある。
-prefix を増やすたびに、列挙も更新する。
+### 10. 結果を報告
-### 11. 残 prefix を報告
+今回ローカル化した prefix と、現在の `local_first_key_regexp` を報告して 1 サイクル終了。加えて:
-移行済み prefix・残 prefix の一覧と、現在の `local_first_key_regexp` を報告して 1 サイクル終了。
-残 prefix があれば次サイクルでこのスキルを再実行する。全 prefix が移行済みになったら
-`copy-tuner-to-locales-cleanup` スキルへ進む。
+- **部分ローカル化** … これで完了。残りの prefix は copy_tuner 管理のままが定常状態なので、次サイクルは不要。
+- **全移行** … copy_tuner 管理のまま残っている prefix の一覧も報告する。残りがあれば次サイクルでこのスキルを
+  再実行する。全 prefix がローカル化済みになったら `copy-tuner-to-locales-cleanup` スキルへ進む。
 ## 1 サイクル完了の目安
 - 手順 6 のスクリプトが**移行漏れゼロを確認して正常終了**し、`--out`（`0010_` 以降）に対象 prefix が配置され、
   `0000_original_*.yml` から該当サブツリーが削除されている（非表現値は `--out` 側に保持済み）。
 - `local_first_key_regexp` に対象 prefix が `\A` アンカー付きで追加されている（手順 7）。
-- 中間状態ドキュメントの「ローカル化済み prefix」が更新されている（手順 10）。
+- i18n 方針ドキュメントの「config/locales 管理の prefix」が更新されている（手順 9）。
 - （任意）rspec/画面で `translation missing` が出ないことをユーザー判断で確認（手順 8）。

data/skills/copy-tuner-to-locales-migrate-prefix/references/example-touchpoints.md CHANGED Viewed

@@ -61,7 +61,8 @@ end
 → オリジナルを `0000_original_` で先頭固定し、移行分は `0010_` 以降に置く。重複キーはロード順の**後勝ちで
 export 側が勝つ**（手作業マージ不要）。prefix を移行するたびにオリジナルから該当サブツリーを削除し、残存＝
-未移行 prefix の進捗マーカーにする（最終的にオリジナルが空＝全移行完了）。
+未移行 prefix の進捗マーカーにする（**全 prefix を移行する場合は最終的にオリジナルが空になる**）。
+部分ローカル化では、対象外 prefix がオリジナルに残り続けるのが**定常状態**であり、空にならなくてよい。
 → Rails 標準フォーマットの **配列**（`date.abbr_day_names` 等）・`date.order` の `:year` 等の**シンボル配列**・
 `number.*.precision` 等の**非表現値**は copy_tuner で表現できず export に出てこないため、`date`/`number` を移行
@@ -69,10 +70,10 @@ export 側が勝つ**（手作業マージ不要）。prefix を移行するた
 移行分（`0010_` 以降）の中へ**非表現値ごと取り込む**。別ファイルへの隔離は不要（詳細は
 `references/export-and-split.md`）。
-### CI — [migrate]（Export ステップのみ初回で削除） / [cleanup]（残り）
+### CI — [cleanup]
 - **CI の翻訳 export ステップ**（テストワークフロー内で `bin/rake copy_tuner:export` を走らせる類）…
-  「翻訳 DL 失敗でテストがコケないように」の保険。**[migrate] の初回で削除**（test が本番同等の
+  「翻訳 DL 失敗でテストがコケないように」の保険。**[cleanup] で削除**（test が本番同等の
   `cache.download` 挙動になる）。`disable_test_translation` は入れない。
 - **copy_tuner 専用の deploy ワークフロー**（main push で翻訳をデプロイする専用ファイル）…
   **[cleanup] で丸ごと削除**。
@@ -88,10 +89,11 @@ export 側が勝つ**（手作業マージ不要）。prefix を移行するた
 `config/environments/production.rb` の `config.i18n.fallbacks = true` 等。標準バックエンドでも有効なので確認のみ。
-### ドキュメント / スキル / MCP — [migrate]（中間状態更新） / [cleanup]（最終化・撤去）
+### ドキュメント / スキル / MCP — [migrate]（用途別に更新） / [cleanup]（最終化・撤去）
 - **i18n 方針ドキュメント**（`CLAUDE.md`・`doc/` 配下等）… 「copy_tuner サーバで i18n データを管理 /
-  config/locales 配下は利用しない / 新規キー登録は基本禁止」等の記述。**[migrate] で中間状態に更新**、
+  config/locales 配下は利用しない / 新規キー登録は基本禁止」等の記述。**[migrate] で更新**（部分ローカル化なら
+  恒久的な二層管理として、全移行なら段階移行中の中間状態として。テンプレは後掲）。全移行の場合のみ
   **[cleanup] で最終化**。上記を参照している他のドキュメント（`CLAUDE.md` 等）も連動。
 - **copy_tuner MCP 操作スキル**（`.claude/skills/` 配下）… **[cleanup] で無効化/削除**。
 - **補助ドキュメント** … 「多言語対応: copy_tuner サーバで i18n データを管理」のような記述を持つコマンド定義等。
@@ -107,10 +109,28 @@ copy_tuner 側のキー数・export YAML の行数はプロジェクト次第だ
 `restrict_dependent_destroy` 等。これらのトップセクションが prefix 移行の基本粒度。`views` が最大になりやすいので
 最後に回す。
-## i18n 方針ドキュメント中間状態テンプレ（[migrate] 手順 10 で使う）
+## i18n 方針ドキュメントテンプレ（[migrate] 手順 9 で使う）
-移行中はこのような記述に置き換える。`<列挙>` は現在 `local_first_key_regexp` にマッチしている prefix に
-更新する（prefix を増やすたびに更新）。
+用途に応じて 2 版ある。`<列挙>` は現在 `local_first_key_regexp` にマッチしている prefix に更新する
+（prefix を増やすたびに更新）。
+### 部分ローカル化版
+「移行中」ではなく、この状態が**恒久的に続く二層管理**であることを明記する。
+```markdown
+### 国際化（i18n）
+- **一部の prefix は config/locales（YAML）管理、それ以外は copy_tuner サーバ管理**
+- config/locales 管理の prefix（`local_first_key_regexp` にマッチ）: `<列挙>`
+- 上記以外の prefix は copy_tuner サーバで管理
+- **新規キーの追加先**: 上記 prefix のキーは config/locales へ。それ以外は copy_tuner へ
+- 複数形化対応は不要（日本語環境）
+```
+### 全移行版
+「段階移行中」であることと、いずれ cleanup で最終化される中間状態であることを明記する。
 ```markdown
 ### 国際化（i18n）
@@ -122,5 +142,6 @@ copy_tuner 側のキー数・export YAML の行数はプロジェクト次第だ
 - 複数形化対応は不要（日本語環境）
 ```
-> [cleanup] で全 prefix 完了後、この中間記述は「config/locales 管理。copy_tuner 廃止。新規キーは
-> config/locales へ。複数形化不要」に最終化する（モデル名・カラム名の例外規定も撤廃）。
+> 上記**全移行版にのみ係る注記**: [cleanup] で全 prefix 完了後、この中間記述は「config/locales 管理。
+> copy_tuner 廃止。新規キーは config/locales へ。複数形化不要」に最終化する（モデル名・カラム名の例外規定も
+> 撤廃）。部分ローカル化版は cleanup を経由しないため、この最終化は適用されない。

data/skills/copy-tuner-to-locales-migrate-prefix/scripts/migrate_prefix.rb CHANGED Viewed

@@ -8,6 +8,10 @@
 #   bin/rails runner .claude/skills/copy-tuner-to-locales-migrate-prefix/scripts/migrate_prefix.rb \
 #     -- --prefix date --export tmp/copy_tuner_all.yml --out config/locales/0010_date.yml
 #
+# このスクリプト自身の自己検証（gem メンテナ向け。Rails も bundler も不要）:
+#
+#   ruby skills/copy-tuner-to-locales-migrate-prefix/scripts/migrate_prefix.rb --self-test
+#
 # What it does, in one pass:
 #   (1) Place : extract the target prefix subtree from the 0000_original_*.yml
 #       originals (load-order deep_merge), deep_merge the export subtree on top
@@ -29,6 +33,127 @@
 require 'optparse'
 require 'yaml'
+# ---- self-test ----
+# 引数パースより前に分岐する。このスクリプトはトップレベルで即実行する造りなので、`--self-test` の
+# ときは本体へ進ませずテストだけ走らせてトップレベル return で抜ける。
+if ARGV.delete('--self-test')
+  require 'minitest/autorun'
+  require 'tmpdir'
+  require 'fileutils'
+  require 'rbconfig'
+  # 本体はトップレベルで exit するため load では検証できない。fixture を tmpdir に作り、i18n だけを
+  # 直接設定する薄いランナー経由でサブプロセス実行する（スクリプトが触るのは I18n.load_path と
+  # Backend::Simple だけなので Rails は不要）。
+  class MigratePrefixSelfTest < Minitest::Test
+    SCRIPT = File.expand_path(__FILE__)
+    # 対象 prefix（date）を持つファイル。これだけが書き戻し対象になるのが期待挙動。
+    WITH_PREFIX = "ja:\n  date:\n    formats:\n      default: \"%Y\"\n"
+    WITHOUT_PREFIX = "ja:\n  greeting: \"hello\"\n"
+    # 片方だけが対象 prefix を持つ 2 ファイル構成。「1 ファイルだけ書き戻る」ことの検証に使う。
+    MIXED_FILES = { '0000_original_a.yml' => WITH_PREFIX, '0000_original_b.yml' => WITHOUT_PREFIX }.freeze
+    EXPORT_JA = "ja:\n  date:\n    formats:\n      default: \"%Y/%m/%d\"\n"
+    EXPORT_JA_EN = "#{EXPORT_JA}en:\n  date:\n    formats:\n      default: \"%m/%d/%Y\"\n".freeze
+    # to_yaml の既定 line_width（80）を確実に超える長さにして折り返しを誘発する。
+    LONG_VALUE = (['word'] * 60).join(' ').freeze
+    def test_untouched_file_keeps_bytes
+      # コメント・空行・ダブルクォートが 1 バイトも変わらないことを見る。
+      untouched = <<~YAML
+        ja:
+          # これは greeting のコメント
+          greeting: "hello"
+          farewell: "bye"
+      YAML
+      migrate({ '0000_original_a.yml' => WITH_PREFIX, '0000_original_b.yml' => untouched }) do |out, dir|
+        # binread は ASCII-8BIT を返すため、UTF-8 の期待値を b で揃えてバイト列として比較する。
+        assert_equal(untouched.b, read(dir, '0000_original_b.yml'), "無関係なファイルが書き換わった:\n#{out}")
+      end
+    end
+    def test_missing_locale_root_is_not_added
+      migrate(MIXED_FILES, locales: %w[ja en], export: EXPORT_JA_EN) do |_out, dir|
+        MIXED_FILES.each_key do |name|
+          refute_includes(read(dir, name), 'en:', "#{name} に元ファイルに無い en ルートが新設された")
+        end
+      end
+    end
+    def test_prefix_is_pruned_from_matching_file
+      migrate({ '0000_original_a.yml' => "#{WITH_PREFIX}  greeting: \"hello\"\n" }) do |_out, dir|
+        assert_equal({ 'ja' => { 'greeting' => 'hello' } }, load_yaml(dir, '0000_original_a.yml'))
+        assert_equal(
+          { 'ja' => { 'date' => { 'formats' => { 'default' => '%Y/%m/%d' } } } },
+          load_yaml(dir, '0010_migrated.yml')
+        )
+      end
+    end
+    def test_long_value_is_not_wrapped
+      migrate({ '0000_original_a.yml' => "#{WITH_PREFIX}  greeting: \"#{LONG_VALUE}\"\n" }) do |_out, dir|
+        body = read(dir, '0000_original_a.yml')
+        assert_includes(body, "greeting: #{LONG_VALUE}\n", "長い値が折り返された:\n#{body}")
+      end
+    end
+    def test_summary_counts_changed_files
+      migrate(MIXED_FILES) do |out, _dir|
+        assert_includes(out, 'オリジナル 2 ファイル中 1 ファイル')
+      end
+    end
+    private
+    # fixture を tmpdir に配置してサブプロセス実行し、標準出力と locales ディレクトリを yield する。
+    def migrate(files, locales: %w[ja], export: EXPORT_JA)
+      Dir.mktmpdir do |dir|
+        locales_dir = File.join(dir, 'config/locales')
+        FileUtils.mkdir_p(locales_dir)
+        FileUtils.mkdir_p(File.join(dir, 'tmp'))
+        files.each { |name, body| File.write(File.join(locales_dir, name), body) }
+        File.write(File.join(dir, 'tmp/export.yml'), export)
+        write_runner(dir, locales)
+        ok, out = spawn_script(dir, locales)
+        assert(ok, "スクリプトが異常終了した:\n#{out}")
+        yield(out, locales_dir)
+      end
+    end
+    def write_runner(dir, locales)
+      File.write(File.join(dir, 'runner.rb'), <<~RUBY)
+        require 'i18n'
+        I18n.load_path = Dir['config/locales/*.yml']
+        I18n.available_locales = #{locales.map(&:to_sym).inspect}
+        I18n.default_locale = #{locales.first.to_sym.inspect}
+        load #{SCRIPT.inspect}
+      RUBY
+    end
+    def spawn_script(dir, locales)
+      args = [
+        '--prefix', 'date', '--locales', locales.join(','),
+        '--export', 'tmp/export.yml', '--out', 'config/locales/0010_migrated.yml'
+      ]
+      Dir.chdir(dir) do
+        read_io, write_io = IO.pipe
+        pid = spawn(RbConfig.ruby, File.join(dir, 'runner.rb'), '--', *args, out: write_io, err: write_io)
+        write_io.close
+        out = read_io.read
+        _, status = Process.waitpid2(pid)
+        [status.success?, out]
+      end
+    end
+    def read(dir, name) = File.binread(File.join(dir, name))
+    def load_yaml(dir, name) = YAML.safe_load_file(File.join(dir, name))
+  end
+  return
+end
 # NOTE: `bin/rails runner` は Kernel#abort が投げる SystemExit を握りつぶし終了コードが 0 になる
 # （実機確認済み）。中断を呼び出し側へ確実に伝えるため、abort ではなく warn + exit(1) を使う。
 def die(message)
@@ -160,7 +285,12 @@ end
 # locale ルートを持つ raw Hash（`{ "ja" => {...}, "en" => {...} }`）から、対象 prefix を全 locale で刈った
 # 新しい Hash を返す（非破壊）。移行漏れ検証のシミュレーションと実削除の両方で使う。
 def prune_prefix_all_locales(raw, locales, keys)
-  locales.reduce(raw) { |acc, locale| acc.merge(locale => prune_prefix(acc[locale] || {}, keys)) }
+  locales.reduce(raw) do |acc, locale|
+    # 元ファイルに無い locale ルートを新設すると、ja だけのファイルに `en: {}` が追記されてしまう。
+    next acc unless acc.key?(locale)
+    acc.merge(locale => prune_prefix(acc[locale], keys))
+  end
 end
 # ---- (1) 配置 ----
@@ -277,10 +407,18 @@ unless leaks.empty?
   die('中断。--out の内容・採番・regexp を確認すること。')
 end
-original_files.each do |f|
-  raw = YAML.safe_load_file(f, permitted_classes: [Symbol], aliases: true) || {}
-  File.write(f, prune_prefix_all_locales(raw, LOCALES, prefix_keys).to_yaml)
-end
+changed =
+  original_files.count do |f|
+    raw = YAML.safe_load_file(f, permitted_classes: [Symbol], aliases: true) || {}
+    pruned = prune_prefix_all_locales(raw, LOCALES, prefix_keys)
+    # 対象 prefix を含まないファイルを to_yaml で書き戻すと、クォート・アンカー名・折り返し・コメントの
+    # 無関係な整形差分が出る。実質的な変更があるファイルだけ書き戻す。
+    next false if pruned == raw
+    # 折り返しだけは line_width で無効化できる（アンカー名・クォートは Psych の仕様で制御できない）。
+    File.write(f, pruned.to_yaml(line_width: -1))
+    true
+  end
-puts "削除: prefix '#{PREFIX}' をオリジナル #{original_files.size} ファイルから刈り取った。"
+puts "削除: prefix '#{PREFIX}' をオリジナル #{original_files.size} ファイル中 #{changed} ファイルから刈り取った。"
 puts '完了。手順7（local_first_key_regexp 追加）が未済なら次に実施すること。'

data/spec/copy_tuner_client/configuration_spec.rb CHANGED Viewed

@@ -398,6 +398,179 @@ describe CopyTunerClient::Configuration do
     end
   end
+  describe 'middleware_position の初期値' do
+    let(:config) { described_class.new }
+    context 'Warden::Manager と Devise がどちらも定義済みのとき' do
+      before do
+        stub_const('Warden::Manager', Class.new)
+        stub_const('Devise', Module.new)
+      end
+      it '{ before: Warden::Manager } になる' do
+        expect(config.middleware_position).to eq({ before: Warden::Manager })
+      end
+    end
+    context 'Warden::Manager が未定義のとき' do
+      before { hide_const('Warden::Manager') }
+      it 'nil のままになる' do
+        expect(config.middleware_position).to be_nil
+      end
+    end
+    # NOTE: authtrail のように warden を require するだけで Warden::Manager をスタックへ積まない
+    # gem があるため、Warden 単独では既定位置にしない（insert_before が起動時例外になる）。
+    context 'Warden::Manager は定義済みだが Devise が未定義のとき' do
+      before do
+        stub_const('Warden::Manager', Class.new)
+        hide_const('Devise')
+      end
+      it 'nil のままになる' do
+        expect(config.middleware_position).to be_nil
+      end
+    end
+    context 'configure ブロック内で明示指定したとき' do
+      before do
+        stub_const('Warden::Manager', Class.new)
+        stub_const('Devise', Module.new)
+      end
+      it '明示指定した値が優先される' do
+        other = Class.new
+        CopyTunerClient.configure(apply: false) do |c|
+          c.middleware_position = { before: other }
+        end
+        expect(CopyTunerClient.configuration.middleware_position).to eq({ before: other })
+      end
+    end
+  end
+  context 'Warden::Manager がスタックにある状態で apply したとき' do
+    it_behaves_like 'applied configuration' do
+      it 'デフォルト値経由で Warden::Manager の直前に RequestSync → CopyrayMiddleware の順で入る' do
+        expect(middleware.classes).to eq(
+          [
+            Rack::ETag, Rack::TempfileReaper, CopyTunerClient::RequestSync, CopyTunerClient::CopyrayMiddleware,
+            Warden::Manager, Rack::Static
+          ]
+        )
+      end
+      it 'Warden::Manager より外側に配置される' do
+        expect(middleware.index(CopyTunerClient::RequestSync)).to be < middleware.index(Warden::Manager)
+        expect(middleware.index(CopyTunerClient::CopyrayMiddleware)).to be < middleware.index(Warden::Manager)
+      end
+      it 'RequestSync に poller / cache / interval / ignore_regex が渡る' do
+        args = middleware.args_for(CopyTunerClient::RequestSync)
+        expect(args.first).to include(
+          poller:, # rubocop:disable Sgcop/Rspec/NoMethodCallInExpectation
+          cache:,
+          interval: configuration.sync_interval,
+          ignore_regex: configuration.sync_ignore_path_regex
+        )
+      end
+    end
+    # NOTE: 実アプリの bin/rails middleware 出力を模した標準スタック。Warden::Manager / Devise は
+    # gem の依存にないため stub_const で fake の定数として定義する。
+    before do
+      stub_const('Warden::Manager', Class.new)
+      stub_const('Devise', Module.new)
+    end
+    let(:middleware) do
+      MiddlewareStack.new([Rack::ETag, Rack::TempfileReaper, Warden::Manager, Rack::Static])
+    end
+    def apply
+      configuration.middleware = middleware
+      configuration.environment_name = 'development'
+      configuration.apply
+    end
+  end
+  context 'Warden::Manager が未定義の状態で apply したとき' do
+    it_behaves_like 'applied configuration' do
+      it 'Warden::Manager 未定義時は従来どおりスタック末尾へ use される' do
+        expect(middleware.classes).to eq([CopyTunerClient::RequestSync, CopyTunerClient::CopyrayMiddleware])
+      end
+    end
+    before { hide_const('Warden::Manager') }
+    let(:middleware) { MiddlewareStack.new }
+    def apply
+      configuration.middleware = middleware
+      configuration.environment_name = 'development'
+      configuration.apply
+    end
+  end
+  context 'middleware_position に after を明示指定して apply したとき' do
+    it_behaves_like 'applied configuration' do
+      it '{after: X} 指定時は X の直後に RequestSync → CopyrayMiddleware の順で入る' do
+        expect(middleware.classes).to eq(
+          [:a, :x, CopyTunerClient::RequestSync, CopyTunerClient::CopyrayMiddleware, :b]
+        )
+      end
+    end
+    let(:middleware) { MiddlewareStack.new(%i[a x b]) }
+    def apply
+      configuration.middleware = middleware
+      configuration.middleware_position = { after: :x }
+      configuration.environment_name = 'development'
+      configuration.apply
+    end
+  end
+  context 'middleware_position に before を明示指定して apply したとき' do
+    it_behaves_like 'applied configuration' do
+      it '{before: X} 指定時は X の直前に RequestSync → CopyrayMiddleware の順で入る' do
+        expect(middleware.classes).to eq(
+          [:a, CopyTunerClient::RequestSync, CopyTunerClient::CopyrayMiddleware, :x, :b]
+        )
+      end
+    end
+    let(:middleware) { MiddlewareStack.new(%i[a x b]) }
+    def apply
+      configuration.middleware = middleware
+      configuration.middleware_position = { before: :x }
+      configuration.environment_name = 'development'
+      configuration.apply
+    end
+  end
+  # NOTE: { before: SomeClass if cond } のように条件次第で値が nil になる書き方を想定する。
+  # キーの有無だけで分岐すると insert_before(nil) が対象を見つけられず例外になる。
+  context 'middleware_position の値が nil のとき' do
+    it_behaves_like 'applied configuration' do
+      it '例外を投げずスタック末尾へ use する' do
+        expect(middleware.classes).to eq(
+          [:a, :x, :b, CopyTunerClient::RequestSync, CopyTunerClient::CopyrayMiddleware]
+        )
+      end
+    end
+    let(:middleware) { MiddlewareStack.new(%i[a x b]) }
+    def apply
+      configuration.middleware = middleware
+      configuration.middleware_position = { before: nil }
+      configuration.environment_name = 'development'
+      configuration.apply
+    end
+  end
   context 'applied without locale filter' do
     include_context 'stubbed configuration'

data/spec/copy_tuner_client/warden_integration_spec.rb ADDED Viewed

@@ -0,0 +1,95 @@
+require 'spec_helper'
+require 'copy_tuner_client/copyray_middleware'
+require 'copy_tuner_client/copyray'
+require 'copy_tuner_client/copyray/marker'
+require 'copy_tuner_client/translation_log'
+# Warden::Manager の catch(:warden) と failure app 呼び出しだけを模した fake（warden gem に依存しないため）
+class FakeWarden
+  def initialize(app, failure_app)
+    @app = app
+    @failure_app = failure_app
+  end
+  def call(env)
+    result = catch(:warden) { @app.call(env) }
+    result.is_a?(Array) ? result : @failure_app.call(env)
+  end
+end
+# NOTE: CopyrayMiddleware 単体ではなく、Warden 相当の fake との組み合わせ位置を検証するため
+# describe の第一引数はクラスではなく説明文にしている
+describe 'throw :warden と CopyrayMiddleware の位置関係' do # rubocop:disable RSpec/DescribeClass
+  def marker(key)
+    CopyTunerClient::Copyray::Marker.encode(key)
+  end
+  # NOTE: authenticate_user! 失敗を模す。throw :warden するとこの @app.call(env) は正常リターンせず、
+  # CopyrayMiddleware が内側にあると Rewriter.rewrite が実行されない。
+  let(:throwing_app) { ->(_env) { throw :warden } }
+  let(:failure_status) { 200 }
+  let(:failure_app) do
+    ->(_env) do
+      [failure_status, { 'Content-Type' => 'text/html' }, [failure_body]]
+    end
+  end
+  let(:failure_body) { "<html><body><p>#{marker('devise.failure.unauthenticated')}Please sign in</p></body></html>" }
+  before do
+    CopyTunerClient.configure do |configuration|
+      configuration.project_id = 1
+      configuration.client = FakeClient.new
+    end
+  end
+  # NOTE: append_js は Rails の ActionController::Base.helpers に依存するため、
+  # copyray_middleware_spec.rb と同じ手法で no-op スタブに差し替え、Rewriter の効果だけを見る。
+  def stub_append_js(middleware)
+    allow(middleware).to receive(:append_js) { |html, *| html }
+  end
+  context '内側構成（CopyrayMiddleware が Warden より内側）のとき' do
+    it 'マーカー ⟦CT: がレスポンスに残る（不具合の記録）' do
+      copyray = CopyTunerClient::CopyrayMiddleware.new(throwing_app)
+      stub_append_js(copyray)
+      warden = FakeWarden.new(copyray, failure_app)
+      _status, _headers, response = warden.call({})
+      result = response.join
+      expect(result).to match(CopyTunerClient::Copyray::Marker::SCAN_REGEXP)
+    end
+  end
+  context '外側構成（CopyrayMiddleware が Warden より外側）のとき' do
+    it 'マーカーが消え data-copyray-key に変換される' do
+      warden = FakeWarden.new(throwing_app, failure_app)
+      copyray = CopyTunerClient::CopyrayMiddleware.new(warden)
+      stub_append_js(copyray)
+      _status, _headers, response = copyray.call({})
+      result = response.join
+      expect(result).to include('data-copyray-key="devise.failure.unauthenticated"')
+      expect(result).not_to match(CopyTunerClient::Copyray::Marker::SCAN_REGEXP)
+    end
+    context 'failure app が 422 を返すとき（Devise.responder.error_status = :unprocessable_entity 相当）' do
+      let(:unprocessable_failure_app) do
+        ->(_env) { [422, { 'Content-Type' => 'text/html' }, [failure_body]] }
+      end
+      it 'マーカーが消え data-copyray-key に変換される' do
+        warden = FakeWarden.new(throwing_app, unprocessable_failure_app)
+        copyray = CopyTunerClient::CopyrayMiddleware.new(warden)
+        stub_append_js(copyray)
+        _status, _headers, response = copyray.call({})
+        result = response.join
+        expect(result).to include('data-copyray-key="devise.failure.unauthenticated"')
+        expect(result).not_to match(CopyTunerClient::Copyray::Marker::SCAN_REGEXP)
+      end
+    end
+  end
+end

data/spec/support/middleware_stack.rb CHANGED Viewed

@@ -1,13 +1,47 @@
+# ActionDispatch::MiddlewareStack の挿入 API を模した fake（挿入順序と引数を検証するため）
 class MiddlewareStack
-  def initialize
-    @middlewares = []
+  Entry = Struct.new(:klass, :args)
+  def initialize(existing = [])
+    @middlewares = existing.map { |klass| Entry.new(klass, []) }
+  end
+  def use(klass, *args)
+    @middlewares << Entry.new(klass, args)
+  end
+  def insert_before(target, klass, *args)
+    index = index_of!(target, 'before')
+    @middlewares.insert(index, Entry.new(klass, args))
   end
-  def use(klass, *)
-    @middlewares << klass.new('fake_app', *)
+  def insert_after(target, klass, *args)
+    index = index_of!(target, 'after')
+    @middlewares.insert(index + 1, Entry.new(klass, args))
   end
   def include?(klass)
-    @middlewares.any?(klass)
+    classes.include?(klass)
+  end
+  def classes
+    @middlewares.map(&:klass)
+  end
+  def index(klass)
+    classes.index(klass)
+  end
+  def args_for(klass)
+    @middlewares.find { |entry| entry.klass == klass }&.args
+  end
+  private
+  def index_of!(target, where)
+    index = classes.index(target)
+    raise "No such middleware to insert #{where}: #{target.inspect}" if index.nil?
+    index
   end
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: copy_tuner_client
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.2.1
 platform: ruby
 authors:
 - SonicGarden
@@ -258,6 +258,7 @@ files:
 - spec/copy_tuner_client/process_guard_spec.rb
 - spec/copy_tuner_client/request_sync_spec.rb
 - spec/copy_tuner_client/translation_log_spec.rb
+- spec/copy_tuner_client/warden_integration_spec.rb
 - spec/copy_tuner_client_spec.rb
 - spec/spec_helper.rb
 - spec/support/client_spec_helpers.rb