JSMKC の Cloudflare / D1 運用を cf CLI 前提へ段階移行する

[azumag]

背景

Cloudflare の新しい cf CLI を標準操作面にする。JSMKC は OpenNext Worker と Cloudflare D1 を利用しており、特に Prisma migrations と D1 用 SQL migrations の二重管理、および wrangler d1 migrations apply を前提とした運用契約があるため、単純置換ではなく migration correctness を優先して段階移行する。

方針

• Cloudflare 操作は cf-first
• wrangler は cf で安全に parity を確認できない箇所だけ一時 fallback
• Prisma migration と D1 migration の二重管理契約は維持
• preview / production DB を取り違えない
• migration と Worker deploy の順序・失敗時挙動を変えない
• OpenNext の既存 build/deploy 契約は cf 側の parity が取れるまで維持
• 設定は可能な範囲で cloudflare.config.ts へ移行

現在確認できる主な Wrangler 依存

• smkc-score-app/wrangler.toml
• wrangler d1 migrations apply
• wrangler d1 export
• wrangler tail
• preview schema preflight 内の Wrangler 呼び出し
• Wrangler 形式の migrations/*.sql

TODO

• Cloudflare / D1 / OpenNext / preview / observability の Wrangler 依存を完全棚卸し
• D1 migration list/apply/export の cf parity を検証
• preview schema preflight を cf へ移せるか確認
• migration ordering と fail-closed 条件をテストで固定
• wrangler.toml → cloudflare.config.ts migration を検証
• OpenNext Worker の bindings / compatibility / secrets parity を確認
• logs / tail / diagnostics を cf 前提に更新
• CI / operational docs / CLAUDE.md 等を cf-first に更新
• cf 未対応部分は fallback 理由を明記
• Wrangler 撤去後も Prisma/D1 migration parity CI が維持されることを確認

完了条件

• D1 migration の安全契約を壊さず cf-first に移行できている
• preview / production の DB 境界が維持されている
• OpenNext の build/deploy に回帰がない
• 残存 Wrangler は理由が明記された一時 fallback のみ

親Issue

• azumag/CV#52 — 全体TODO: Cloudflare運用を cf CLI 前提へ統一する

[azumag]

Safe first slice is now open as PR #4202.

Scope:

• inventories current Wrangler-dependent Cloudflare/D1/OpenNext operational surfaces;
• documents cf-first migration with Wrangler retained where parity is still unverified;
• locks production/preview D1 separation and migrate-before-deploy ordering;
• keeps the Workers Builds cost-control gate explicitly separate;
• adds static regression coverage for these boundaries.

This PR intentionally does not replace production commands or change D1 migrations, bindings/secrets, domains, or Cloudflare settings. Follow-up slices can verify cf parity surface-by-surface before switching each command/config path.

[azumag]

PR #4202 has been squash-merged as 5bd46041d1f766ca83dabea76a9885b179ebf94a.

This completes the first safe slice:

• current Wrangler-dependent Cloudflare/D1/OpenNext surfaces are documented;
• cf-first migration is explicitly parity-gated;
• production/preview D1 separation and migrate-before-deploy ordering are regression-tested;
• Workers Builds cost-control remains a separate invariant.

No production command or Cloudflare/D1 configuration was changed. Remaining #4201 work is to verify cf parity surface-by-surface (D1 list/apply/export, preview preflight, config, deploy, logs/tail) before replacing each Wrangler fallback.

[azumag]

cf-first D1 migration の safe slice を PR #4203 として実装しました。

• wrangler.toml から production / preview の DB binding を明示的に解決する fail-closed resolver を追加
• unknown environment、missing/duplicate DB binding、invalid UUID、migrations_dir drift、prod/preview 同一DBを拒否
• UUID は case-insensitive に同一性判定し、mixed-case 表記で collision guard を迂回できないよう修正
• focused regression test と transition-policy contract を追加
• 現行 migration/deploy scripts・bindings・secrets・Workers Builds 設定は変更していません

初回 CI #4352 は migration parity は success、changed-file formatting のみ failure でした。Prettier 提案どおり同じ PR で format 修正を追加済みで、fresh CI を再確認中です。

[azumag]

PR #4203 を review 済み（blocking finding なし）として squash merge しました。main は 4cdeade1ad6760ce8933f9e3232f9490059aabae です。

この slice で以下を固定しました。

• cf D1 migration が database ID 直接指定になる upstream 境界
• production / preview の repository-owned fail-closed target resolver
• unknown environment、missing/duplicate DB binding、invalid UUID、migrations_dir drift、production/preview 同一DBの拒否
• mixed-case UUID でも同一DBとして衝突判定
• focused regression tests と transition policy docs

現行 Wrangler migration/deploy scripts、bindings、secrets、Workers Builds cost gate は変更していません。#4201 はまだ全体移行が残るため open のまま継続します。

[azumag]

Safe slice は PR #4209 として実装・検証し、squash merge しました。

• merge commit: fb67de876ffc25e4e4d0e096bf5410666d2775c5
• cf d1 migrations list/apply の非実行 dry-run planner を追加
• 既存 fail-closed D1 target resolver を再利用
• production/preview の explicit database ID、apply の --dir migrations、--local 非付与を回帰テストで固定
• 現行 Wrangler migration/deploy scripts と Workers Builds 設定は未変更
• CI: Prisma/D1 parity、lint、format、unit tests、Production build、security audit が success

この slice は parity 検証面までです。実際の D1 操作切替は引き続き #4201 の後続 safe slice で扱います。