コントリビューション

Nodaro へのコントリビューションとは、公開リポジトリ github.com/nodaroai/app.nodaro.ai に、プルリクエストとしてコードを送ることです。Nodaro は、Nodaro Sustainable Use License のもとでソースコードを公開しています（ソースアベイラブル）。このページでは、開発環境の準備、ブランチ、プルリクエスト、テスト、コントリビューター契約について説明します。

自分のサーバーで Nodaro を動かすだけなら、クイックスタートから始めてください。API を使って開発する場合は、SDK を参照してください。

リポジトリ

リポジトリは、npm workspaces を使った 1 つのモノレポで、次のフォルダーで構成されています。

プロジェクトのルールは、リポジトリのルートにある CLAUDE.md にまとめています。コーディング規約、モデルプロバイダーを追加するときのチェックリスト、ノードを追加するときのチェックリストです。軽微でないプルリクエストを出す前に、読んでおいてください。各部分がどのように組み合わさっているかは、アーキテクチャで説明しています。

開発環境を準備する

Node.js 22 以降と npm が必要です。

git clone https://github.com/nodaroai/app.nodaro.ai
cd app.nodaro.ai
npm install        # installs every workspace

cp .env.example .env

echo "INTERNAL_ORCHESTRATOR_SECRET=$(openssl rand -hex 32)" >> .env
echo "NODARO_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

npm -w @nodaro/shared run build

# Terminal 1: the API on port 9000
cd backend
npm run dev

# Terminal 2: the frontend on port 3000, which forwards /v1/* to port 9000
cd frontend
npm run dev

コーディング規約

CLAUDE.md のうち、特に重要なルールは次のとおりです。

• ファイルのサイズ：200〜400 行が目安で、800 行が絶対的な上限です。それより大きくなったファイルは分割してください。
• 本番コードに console.log を使わない：既存のロガーのパターンを使ってください。
• Conventional Commits：feat:、fix:、refactor:、docs:、chore:、test: を使い、件名は具体的に書きます。
• コミットの前には毎回型チェックを行う：backend/ と frontend/ の両方で npx tsc --noEmit を実行します。型チェックに通らないプルリクエストは、CI でブロックされます。
• Express のルーターではなく、Fastify のプラグインを使う：どのルートファイルも、Fastify のインスタンスを受け取る async 関数をエクスポートします。
• API のすべてのエンドポイントに Zod スキーマを用意する：例外はありません。スキーマはリクエストを検証し、OpenAPI ドキュメントの生成にも使われます。
• フロントエンドの状態：サーバーの状態には React Query、UI の状態には Zustand、キャンバスの状態には React Flow を使います。これらを混在させないでください。
• オブジェクトや配列を変更しない：常に新しいコピーを作成してください。Zustand と React Flow は、どちらも参照の等価性に依存しています。

ブランチとプルリクエスト

• リポジトリには、長期間使うブランチが 2 つあります。ステージング用の dev と、本番用の main です。
• リポジトリをフォークし、dev からブランチを作成して、dev に向けてプルリクエストを作成します。main からブランチを作成したり、main に直接コミットしたりしないでください。
• ブランチ名は、種類に応じて feat/、fix/、refactor/、docs/、chore/、test/ のいずれかで始めます。たとえば feat/whisper-tts-node です。
• マージされた変更は、まずステージング環境の next.nodaro.ai で動きます。約 24 時間の検証期間を経て、メンテナーが dev を main に昇格させます。

プルリクエストでは、次のことを行ってください。

• 関連する GitHub の issue をリンクします。
• UI を変更する場合は、スクリーンショットか GIF を添付します。
• ノードを追加または変更する場合は、CLAUDE.md のノードのチェックリストに従います。
• 公開パッケージを変更する場合は、changeset を追加します。Changesets を参照してください。

テスト

各ワークスペースには、それぞれの Vitest スイートがあります。リポジトリのルートからすべてを実行することも、ワークスペースを 1 つずつ実行することもできます。

npm test                       # every workspace's test script

npm -w @nodaro/shared test     # pure-logic unit tests
npm -w @nodaro/sdk test        # SDK contract tests against a mocked API
cd backend && npm test         # route and service tests
cd frontend && npm test        # component and hook tests

テストする内容は次のとおりです。

• API ルート：主要な経路と、スキーマに挙げたエッジケースをテストします。Supabase と AI プロバイダーはモックにしてください。単体テストでは、実際のプロバイダーの API を決して呼び出しません。既存のテストの多くに、そのまま流用できるセットアップがあります。
• フロントエンドのコンポーネント：React Testing Library によるスモークテストです。重いロジックは、単独で単体テストできるフックやヘルパーに置いてください。React Flow や Zustand のストアの内部はテストしないでください。
• 共有パッケージ：純粋関数の単体テストです。エクスポートするものは、フロントエンドとバックエンドの間でシリアライズできる状態を保つ必要があります。

CI では、tsc --noEmit、Vitest、簡単な lint を実行します。テストがローカルでは失敗するのに CI では通る場合や、その逆の場合は、再現手順を添えて issue を作成してください。

ffmpeg の出力チェック

通常の単体テストがチェックするのは ffmpeg に渡す引数で、ffmpeg がレンダリングする結果ではありません。別の特性テスト（characterization test）のスイートが、ffmpeg を使うすべての処理で、テスト用のフィクスチャをレンダリングします。そして、デコードした出力の特性を測定し、コミット済みの基準値と比較します。比較するのは、エネルギー、スペクトル、減衰、長さ、フレームごとの明るさです。

このスイートは npm test には含まれていません。その数値が有効なのは、本番イメージで固定している、まったく同じ ffmpeg のビルドに対してだけだからです。このスイートは、そのイメージの中で実行します。

backend/scripts/characterize-in-image.sh check   # compare with the reference values
backend/scripts/characterize-in-image.sh bless   # rewrite the reference values, on purpose only
cd backend && npm run characterize:report -- --against ffmpeg-X.json

ffmpeg を使う処理を変更した場合は、プルリクエストを作成する前に check を実行してください。CI でも実行されます。レンダリング結果を意図的に変える変更の場合は、イメージの中で bless を実行し、新しい基準値をコミットします。その際、値が変わったすべての測定項目について説明を添えてください。基準値を手で編集したり、ローカルの ffmpeg に対して bless を実行したりしないでください。スイートのバージョンガードが、それを拒否します。

ノードやモデルプロバイダーを追加する

ノードを追加すると、多くのファイルに手が入ります。API ルート、フロントエンドのコンポーネント、実行エンジン、いくつかのレジストリです。1 つでも漏れると、ピッカーの 1 つにノードが表示されない、実行ボタンを押しても何も起きないといった、わかりにくい結果になります。CLAUDE.md の New Node Registration チェックリストに、1 ステップずつ従ってください。

既存のノードにモデルを追加する作業はもっと短く、CLAUDE.md に専用の Provider Enum Sync チェックリストがあります。最も忘れやすいステップは、API ルートのスキーマです。スキーマを更新しないと、API が 400 で拒否するオプションを、エディターが表示してしまいます。

Changesets

npm に公開しているパッケージは、@nodaro/shared、@nodaro/sdk、@nodaro/cli の 3 つです。リリースには Changesets を使い、自動化されています。これらのいずれかに手を加える変更では、次を実行します。

npx changeset

パッケージとバージョンアップの種類（patch、minor、major）を選び、1 行の要約を入力します。.changeset/ に書き出されたファイルを、プルリクエストに含めてコミットします。公開パッケージを変更しているのに changeset がないプルリクエストは、Changeset Guard チェックで失敗します。リリースノートが不要な変更には、npx changeset --empty を使います。

それ以外は、すべて自動で行われます。dev では、Version Packages プルリクエストが、保留中の changeset を集めます。dev が main に昇格すると、リリースのワークフローが新しいバージョンを npm に公開し、タグを付け、GitHub のリリースを作成して、スタンドアロンの CLI バイナリをビルドし直します。backend、frontend、Remotion の各ワークスペースは公開されないので、changeset は不要です。

行動規範

親切に、敬意を持って接し、相手の善意を前提にしてください。このプロジェクトは、CODE_OF_CONDUCT.md にある Contributor Covenant 2.1 に従っています。いかなる種類のハラスメントも、プロジェクトから除外する理由になります。

• 批判するのはコードであって、人ではありません。
• 反対意見は、失礼にならないように伝えてください。「Y なので、ここはパターン X のほうがすっきりすると思います」は良い伝え方ですが、「これはダメ」は良くありません。
• 初めてのコントリビューターをレビューするメンテナーは、辛抱強く対応してください。

質問する場所

• GitHub Discussions：自由な質問、アイデア、Nodaro で作ったものの共有に使います。バグ以外のことは、Issues ではなくこちらを使ってください。
• GitHub Issues：バグの報告と機能のリクエストに使います。
• セキュリティの問題：GitHub の非公開のセキュリティアドバイザリーで報告してください。

プロジェクトについて、メンテナーに個別にメールを送るのは避けてください。公開の場での回答は、みんなの役に立ちます。セキュリティの報告や利益相反に関することは、個別に連絡してもかまいません。

ライセンスとコントリビューター契約

リポジトリには、4 段階のライセンスがあります。ほとんどのコードは、Nodaro Sustainable Use License のもとにあります。ee フォルダー内のコードと、名前に .ee. を含むファイルのコードは、Nodaro Enterprise License のもとにあります。@nodaro/prompts は FSL-1.1-Apache-2.0、@nodaro/sdk、@nodaro/shared、@nodaro/cli は Apache 2.0 のもとにあります。ライセンスを参照してください。

新しいコードの置き場所：Apache のパッケージは、公開したバージョンごとに、取り消せない形で権利を許諾することになります。新しいプロンプトエンジニアリング、カタログ、プリセットは、@nodaro/prompts か backend/ に置きます。@nodaro/shared に追加するのは、公開 API と SDK のコントラクトに必要なもの（型、通信で使う列挙型、API の利用者と共有する検証など）か、再利用のために意図して公開するものだけにしてください。どちらに当たるかを、プルリクエストに書いてください。

コントリビューター契約：コントリビューションを提出すると、Nodaro Contributor License Agreement に同意したことになります。個人と企業のどちらのコントリビューションも、同じ契約の対象です。雇用主の許可については、契約の第 2 条で扱っています。最初のプルリクエストで、cla-assistant ボットが署名を求めます。雇用主の代理としてコントリビュートする場合は、雇用主の知的財産ポリシーで認められていることを確認してください。この契約により、Nodaro は、あなたのコントリビューションを Nodaro のどのライセンスのもとでも提供できます。Sustainable Use License と Enterprise License の間で移すことも含まれます。