コンテンツにスキップ
meganemura/*

firstlight

firstlightv0.3.0MIT

Run lint, typecheck, and tests in parallel for a coding agent, and return at the first failure.

インストール

npm install firstlight

firstlight は、コーディングエージェントのために、チェックを並列で実行するツールです。 エージェントは、lint、型検査、テストを firstlight 経由で実行します。 すべてのチェックを同時に始め、最初の 1 つが失敗した時点で制御を返すので、エージェントはすぐに修正に取りかかれます。 ほかのチェックはバックグラウンドで動き続け、エージェントはその結果を後で読みます。 チェックは任意のシェルコマンドなので、プロジェクトに Node や package.json は必要ありません。 Node が必要なのは firstlight 自身だけです。 firstlight は、検査するリポジトリには何も書き込みません。

特徴

Section titled “特徴”
  • run-p と同じ引数。 firstlight run lint typecheck test は package.json のスクリプトを実行し、"lint:*" はパターンに一致するスクリプトを選びます。 "bundle exec rspec" のように空白を含む引数は、シェルコマンドとして扱います。
  • 統一された形式の診断。 tsc、vitest、node --test、archstrict では、失敗したチェックが、ログの末尾 10 行の前に file:line:col rule message の形式の行を表示します。 tsc --noEmit && vitest run のように && でつないだコマンドでは、それぞれのツールのパーサーを順に使います。
  • 成功の再利用。 同じ作業ツリーに対して同じコマンドで成功したチェックは、再実行しません。 キーは、git のツリーのハッシュ、コマンド、after に指定したチェックのキーから作ります。 --no-cache を付けると、すべてのチェックを実行します。
  • 新しい失敗だけを見る。 firstlight results --new --wait は、前回の実行になかった失敗があるときだけ終了コード 1 で終了します。 そのため、既知の失敗を抱えたプロジェクトでも、変更の可否を判定できます。
  • 失敗したものだけ再実行。 firstlight run --failed は、最新の実行で成功しなかったチェックだけを実行します。 すべてのチェックが終わって失敗が 1 つでもあれば、results と follow が次のコマンドとしてこれを示します。
  • 残り時間。 実行中のチェックには、以前に成功したときの所要時間から見積もった、おおよその残り時間が表示されます。 firstlight follow は状態が変わるたびにその変化を表示し、--json は JSON Lines を出力します。

エージェントでの使い方

Section titled “エージェントでの使い方”
  1. firstlight run lint typecheck test でチェックを始めます。 最初のチェックが失敗するかタイムアウトした時点で制御を返し、そのチェックの診断、ほかのすべてのチェックの状態、次のコマンドを示します。
  2. ほかのチェックが続く間に、失敗を直します。
  3. 残りは firstlight results --wait で読むか、firstlight follow で各チェックが終わるのを見届けます。
  4. firstlight run --failed で、成功しなかったものだけを実行します。 すべてのチェックが終わって失敗が 1 つでもあれば、これが次のコマンドとして示されます。 新しい実行は、手順 1 から残っているものをキャンセルします。

firstlight 自身が失敗したときは、次のコマンドを示す do フィールドを持つ JSON オブジェクトを 1 つ stderr に出力します。

はじめかた

Section titled “はじめかた”

firstlight には Node.js 24 以降が必要です。 それより古い Node では、どのコマンドも何もせずに止まり、エラーを表示して終了コード 1 で終了します。

ターミナルウィンドウ
npm i -D firstlight
npx firstlight --help
npx firstlight run

firstlight.json がなければ、firstlight run は package.json のスクリプト lint、typecheck、test、archstrict のうち、存在するものを実行します。 check:architecture のように、チェックらしいほかのスクリプトは実行せず、not run: の行で名前を示します。 チェックを選ぶには、firstlight init に firstlight.json を提案させ、内容を読んでから --write で書き込みます。

ターミナルウィンドウ
npx firstlight init typecheck test check:architecture
npx firstlight init typecheck test check:architecture --write

firstlight.json では独自のチェックを定義でき、after で順序を、timeoutSec で制限時間を指定します。

組み合わせ

Section titled “組み合わせ”
  • vitest が depug のレポーターを使っていると、firstlight は失敗した各テストの診断に、depug の証拠のパスと再実行のコマンドを添えます。
  • firstlight は archstrict の check の出力を診断として読み、package.json に archstrict のスクリプトがあれば既定で実行します。