コントリビュート

セットアップ

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run setup:hooks  # 旧管理対象 pre-push・post-merge の削除
bun run dev:proxy    # 開発モードのプロキシ API
bun run dev:gui      # ダッシュボード dev サーバー(別ターミナル)
bun run typecheck    # bun x tsc --noEmit
bun run test        # 全テストスイート（既定）

bun run setup:hooks は変更されていない旧管理対象の pre-push と post-merge フックを削除します。カスタムフックは保持します。pre-push フックは必須ではなくなりました。 bun run prepush は任意の手動チェックとして引き続き利用できます。

bun run dev は引き続き bun run dev:proxy のエイリアスとして動作します。ダッシュボード dev サーバーは bun run dev:gui で、GET / で提供するパッケージダッシュボードは bun run build:gui でビルドして gui/dist に作成します。

ビルドとテストコマンド

ルートパッケージは Bun ネイティブの TypeScript で、サーバーを別途 compile するステップはありません。リポジトリに 定義されたスクリプトを使えば、ローカル実行と CI を一致させられます。

bun run typecheck                 # 厳密な TypeScript 検査
bun run test:changed              # 解決した dev マージベースに対する import graph テスト
bun run test                      # tests/ の全体スイート
bun test tests/routing/router.test.ts     # 特定テストファイル
bun run build:gui                 # Vite GUI ビルド + パッケージ準備
bun run privacy:scan              # CI で使う資格情報/個人情報検査
bun run prepare:package           # パッケージランチャー/asset 更新

既定では bun run test で全テストスイートを実行してください。作業規模、マシンのリソース、 同時使用中のワークツリーに対して全体実行の負担が過大な場合でも、変更した動作を実際に検証する 回帰テストを最低限実行する必要があります。例は bun test tests/<domain>/<name>.test.ts です。 範囲を絞った理由、正確なコマンド、結果、未テストの範囲を明記してください。 bun run test:changed は補完に使えますが、すべての間接依存関係を検出するものではありません。 CI だけに任せたり、ローカルテストを一律に省略したりする例外はありません。マージ前には、 現在の PR ヘッドの正確なコミットですべての必須 CI チェックが成功している必要があります。

テストは src/ を写したドメインディレクトリ（tests/<domain>/）に置かれた Bun テストで、対応表は scripts/test-layout/layout.json です。共有 fixture は tests/helpers/、範囲の広いネイティブ等価性シナリオは tests/e2e-style/ にあります。変更した サブシステムの既存テストの近くに集中した回帰テストを追加してください。

いま読んでいるドキュメントサイトは docs-site/ にあります(Astro + Starlight)。

cd docs-site && bun install && bun dev

ドキュメントのデプロイ

公開ドキュメントは GitHub Pages の https://opencodex.me/ja/ に公開されます。 .github/workflows/deploy-docs.yml は main push で docs-site/** またはワークフロー自体が変わると 実行されます。docs-site をビルドした後、生成されたサイトをデプロイします。ドキュメント変更を push する前に以下を 実行してください。

cd docs-site
bun install --frozen-lockfile
bun run build

CI とリリース

GitHub Actions は必要な作業のみを行います。

• Cross-platform CI(.github/workflows/ci.yml)はランタイム、テスト、パッケージ、スクリプト、 TypeScript、ワークフローファイルが変更された pull request と main push で実行されます。Bun matrix は Linux、 Windows、macOS で install、typecheck、tests、privacy scan、release helper build smoke、GUI build、 ocx help を検査します。別途 3 OS レーンはバンドルランタイムを使い、Bun を別途インストールしなくても npm global install が動作するか確認します。
• Release(.github/workflows/release.yml)は手動で実行します。2 つ目の完全 CI パイプラインではなく、 dry-run や publish 前に正確なリリースコミット(GITHUB_SHA)で Cross-platform CI が 成功したか確認します。

リリースには helper を使ってください。

helper の実行前にリリース予定のバージョンを決め、デフォルトブランチから .github/workflows/dev-version-bump.yml を intended-version=<version>、 mode=pre-move で実行してください。生成された PR をレビューして dev にマージし、 main または preview に昇格してから helper を実行します。dev がすでに予定の バージョンより新しい場合は changed=false となり、バージョン更新 PR は不要です。 公開には正確なリリースコミットの CI 成功が引き続き必要です。

bun run release <version>           # バージョン bump を commit/push、publish ワークフローはデフォルト dry-run
bun run release --bump minor        # tag と npm channel から次の patch、minor、major バージョンを導出
bun run release <version> --publish # CI-gated dry-run を確認した後、実際の publish
bun run release:watch               # 直近の Release ワークフロー run を監視

明示的なバージョンの代わりに --bump patch|minor|major を指定できます。上位 core の preview tag が 作られた後は、--bump patch は古い stable patch ラインの継続を拒否します。その修正は開いている preview core に含めてください。

ブランチ

• dev — 唯一の統合先。すべての PR をここに出します。
• main — リリース専用。dev からメンテナーが昇格させるときだけ動きます。機能 PR を直接 出さないでください。
• preview — プレリリーストレイン。

Go ネイティブポートを担っていた dev2-go は廃止し、2 本の統合ラインを維持する方針も 終了しました。履歴は lidge-jun/opencodex-go-archive に読み取り専用で残しています。現在は dev の Bun ネイティブ TypeScript が単一のランタイム ラインです。

リベース PR を歓迎します。古いブランチを現在の head にリベースすることは、ノイズではなく 通常の貢献です。説明欄に元のコミットを記載してください。

規約

• ES Modules のみ(import/export)、TypeScript、strict モード。bun x tsc --noEmit をクリーンに 保ってください。
• ファイルあたり最大約 500 行 — 責任ごとに分割してください。単一の index.ts の後に小さく集中したモジュールを置いた web-search/ と vision/ サイドカーが良い例です。
• 非同期エラーは境界で処理 — サイドカーはリクエストパスにエラーを投げず、適切な marker で 低下します。
• Structure SOT — 現在のメンテナンス不変条件は structure/ に置きます。公開ユーザーワークフローは docs-site/、計画と調査の記録は devlog/ に置きます。
• export の保存 — 他のモジュールが依存している可能性があります。

カタログにプロバイダーを追加

すべてのプロバイダー選択肢と seed は canonical レジストリ(src/providers/registry/entries-extended.ts)から派生します。

{
  id: "my-provider",
  label: "My Provider",
  baseUrl: "https://api.example.com/v1",
  adapter: "openai-chat",
  authKind: "key",
  dashboardUrl: "https://example.com/keys",
  models: ["model-a", "model-b"],
  defaultModel: "model-a",
  noVisionModels: ["model-a"],   // text-only models → vision sidecar describes images
},

src/providers/derive.ts はこのエントリを ocx init、ocx provider、ダッシュボード preset、API キーログイン、 OAuth 設定 seed に供給します。enrichProviderFromCatalog() はモデルメタデータと capability 分類を 保存するプロバイダー設定にコピーします。OAuth プロトコル実装は引き続き src/oauth/ にあります。 レジストリメタデータを追加するだけでは OAuth flow は生まれません。

アダプターを追加

src/adapters/ に ProviderAdapter(アダプター参照)を実装し、 src/server/adapter-resolve.ts に名前を登録した後、出力を内部 AdapterEvent にブリッジしてください。画像 処理には image.ts を再利用し、一般的なストリーミング/ツール呼び出しは openai-chat.ts を参考にしてください。 アダプターが送信再試行を自ら担う場合のみ fetchResponse を使い、Cursor のような実際の双方向転送には runTurn を使ってください。tests/ の下に集中したテストを追加し、公開パッケージ API に含まれる factory の場合は src/index.ts からも export してください。

互換性クレームを追加

互換性クレームは src/compatibility/ に置きます。クレームの範囲はアダプターより狭く、検証済みの 正確なプロバイダー、正規化された upstream base URL、認証モード、inbound/upstream プロトコル、 model id を指定します。同じアダプターや wire format を使う別のプロバイダーや接続先へ、クレームを そのままコピーしないでください。

versioned disposition は passthrough、translated、degraded、unsupported のいずれかを使います。 passthrough 以外のクレームには具体的な制限を記載し、fixture に基づくクレームでは根拠となる正確な assertion id を指定してください。秘密情報を含まない request vector を tests/fixtures/compatibility/ に 追加し、production adapter に対して実行する集中テストを用意します。 passthrough claim が引用できるのは、manifest test でその feature に紐付けられた selector 上の equals assertion で、期待値が同じ位置の呼び出し元の値そのものであるものだけです。これにより、削除・ 書き換え・無関係なフィールドを lossless と表示できません。custom tool とその grammar のように、片方だけ 保たれうる側面は別々の claim にしてください。

compatibility manifest は受動的なデータです。通常の router、Responses handler、server startup path から manifest catalog を import したり、Compatibility Lab を有効化したりしてはいけません。

完了を主張する前に検証

上記のテスト方針に従い、型の変更には bun run typecheck を含め、影響範囲に必要な検証を 実行してください。コマンド、結果、未テストの範囲を報告し、実際に完了した検証だけを主張してください。