コントリビュート

セットアップ

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy    # 開発モードのプロキシ API
bun run dev:gui      # ダッシュボード dev サーバー(別ターミナル)
bun run typecheck    # bun x tsc --noEmit
bun run test         # bun test ./tests/

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                      # tests/ の全体スイート
bun test tests/router.test.ts     # 特定テストファイル
bun run build:gui                 # Vite GUI ビルド + パッケージ準備
bun run privacy:scan              # CI で使う資格情報/個人情報検査
bun run prepare:package           # パッケージランチャー/asset 更新

ほとんどのテストは tests/*.test.ts に並んで配置された Bun テストです。共有 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 は必要な作業のみを行います。

• Windows CI(.github/workflows/ci.yml)はランタイム、テスト、パッケージ、スクリプト、 TypeScript、ワークフローファイルが変更された pull request と main push で実行されます。Windows ジョブで install、typecheck、tests、privacy scan、release helper build smoke、GUI build、ocx help、および バンドルランタイムを使った npm global install を検査します。
• Release(.github/workflows/release.yml)は手動で実行します。2 つ目の完全 CI パイプラインではなく、 dry-run や publish 前に正確なリリースコミット(GITHUB_SHA)で Windows CI が 成功したか確認します。
• Super express release(.github/workflows/super-express-release.yml)は Windows 向けの手動 パッケージング経路です。選択した ref を 1 つの不変なコミット SHA に解決し、Release と同様に、 その正確な SHA の Windows CI が成功していなければ publish を拒否します。デスクトップリリースには、 意図的に署名していない Squirrel.Windows の Setup.exe、RELEASES、完全版 .nupkg が含まれます。

署名なしの Windows インストーラーでは、Unknown Publisher または Microsoft Defender SmartScreen の警告が表示される場合があります。関連する CI、パッケージング、リリースのジョブは、 前のステップが失敗した場合でも防御的な artifact collector を実行します。collector は明示的に安全な インストーラー/feed 出力と run metadata だけを GitHub Actions artifact に保存し、collector 自体の失敗は 元の job verdict を隠したり置き換えたりしないよう無視されます。証拠が保存されても、失敗した build が publish 対象になることはありません。

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

bun run release <version>           # バージョン bump を commit/push、publish ワークフローはデフォルト dry-run
bun run release <version> --publish # CI-gated dry-run を確認した後、実際の publish
bun run release:watch               # 直近の Release ワークフロー run を監視

ブランチ

• dev — 既定の統合先。下のスコープ付きブランチに該当しない限り、ここに PR を出します。
• dev2-go — Go ネイティブポート（go/、ネイティブランタイムのエントリポイント、Go リリースアセットのツール）向けの並行統合ラインです。dev と並んで PR を受け付けます。 Go ポートに属する作業だけをここに出し、それ以外は dev に出してください。ターゲット ブランチ検査は両方を許可しますが、両者を区別できません。スコープはレビューで決まり、 メンテナーが dev への変更を依頼することがあります。
• main — リリース専用。dev からメンテナーが昇格させるときだけ動きます。機能 PR を直接 出さないでください。
• preview — プレリリーストレイン。

主要ランタイムを Go ネイティブポートへ移行している間、dev に入った変更は dev2-go にも 反映される必要があります。コントリビューターの手順は変わりません。これまでどおり dev に PR を出してください。マージしたメンテナーがその作業を dev2-go にリベースし、go/ 側で 対応が必要な部分をポートします。両方のラインに入って初めて完了とみなします。

ポーティング PR とリベース PR を歓迎します。ある統合ラインの修正を別のラインへ運ぶこと、 古いブランチを現在の head にリベースすることは、ノイズではなく通常の貢献です。説明欄に 元のコミットを記載してください。

規約

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

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

すべてのプロバイダー選択肢と seed は canonical レジストリ(src/providers/registry.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 してください。

完了を主張する前に検証

変更を証明する最も狭いコマンドから実行してください。型は bun run typecheck、動作は集中した bun test tests/<name>.test.ts またはランタイム probe で確認した後、影響範囲に応じた広い gate を 実行します。opencodex は大きな batch より小さく検証可能な commit を好みます。