chore(repo): dev サーバのポートをセット単位で自動割当し配線を追従させる (ADR-0030)

[shinyaoguri]

目的

別プロジェクト (例: subimage) や別 worktree の dev サーバがポートを占有していると、vite が黙って +1 ずつずれ、editor の /verify プロキシ (5174 固定) や VITE_API_URL (8787 固定) がエラーも出さずに古い残骸プロセスや別物へつながる。実際に「5173 を別プロジェクトに取られ、npm run dev すると verify ばかり目に付く」混乱が発生した。複数サービスの同時デバッグを無調整で共存させる。

Closes #196 / 設計判断は ADR-0030

変更点

• scripts/dev.mjs (新規): npm run dev の起動ランチャー。既定セット {editor 5173, verify 5174, workers 8787} の 3 ポートがすべて空くまでセットごと +10 (5183/5184/8797, …) で探索し (127.0.0.1 / ::1 の両方を検査、最大 10 セット)、決定値を EDITOR_PORT / VERIFY_PORT / WORKERS_PORT で各プロセスへ注入。concurrently に names (editor/verify/workers) と色を付け、起動バナーで実 URL を明示
• packages/editor/vite.config.ts: server.port / /verify プロキシ target を env から解決。VITE_API_URL は .env がローカル既定 (http://localhost:<port>) のときのみ実 workers ポートへ追従 (staging 等の外部 URL は非干渉)。ランチャー割当時は strictPort: true (黙認ずれ禁止)
• packages/verify/vite.config.ts: 同様に server.port + strictPort
• package.json: "dev" を node scripts/dev.mjs に。個別起動 (dev:editor 等) は従来どおり固定ポート + vite フォールバック
• docs: ADR-0030 追加、ADR 索引・CLAUDE.md・CONTRIBUTING (「併用するときはポートを変える」手動運用の置換) を更新

変更しないもの: workers の CORS (dev は localhost ポート不問許可済み)、e2e (E2E_EDITOR_PORT/E2E_WORKERS_PORT で既に可変・EDITOR_PORT 未設定起動のため干渉なし)

確認方法

実機 (5173 = 別プロジェクト、5174/5175/8787 = 既存 dev サーバが占有中) で検証済み:

$ npm run dev
⚠ 既定ポート (5173/5174/8787) の一部が使用中のため +10 で起動します
  editor  http://localhost:5183/
  verify  http://localhost:5184/
  workers http://localhost:8797/

• curl http://localhost:5183/ → <title>TypedCode</title> / :5184/ → <title>TypedCode Verify</title>
• curl http://localhost:5183/verify/ → <title>TypedCode Verify</title> (プロキシが 5184 へ追従)
• curl http://localhost:8797/health → {"status":"ok","environment":"development"}
• 配信 JS 内で VITE_API_URL が http://localhost:8797 に置換されていることを確認
• strictPort: 起動中に EDITOR_PORT=5183 npm run dev:editor → フォールバックせず即失敗 (exit 1)
• npm run lint / npm run typecheck / unit tests (editor 106, verify 14) すべて green

🤖 Generated with Claude Code

[github-actions]

🚀 Preview Deployment

Name	URL
Preview	https://25cb5a10.typedcode.pages.dev

Deployed from commit 48c63d4
API: staging Workers