envdoctor

envdoctor

envdoctor は、このマシンの環境がリポジトリの要件を満たしているか確認します。リポジトリのディレクトリを指定すると、決定論的なチェックを少数実行し、それぞれの合否と修正方法を示します。リポジトリ内のコードを実行することはなく、秘密の値を出力することもありません。

インストール

インストールせずに実行します。

npx @reneturcios/envdoctor doctor [path]

または、グローバルにインストールします。

npm install -g @reneturcios/envdoctor

CLI

envdoctor doctor [path] [--json]
envdoctor mcp
envdoctor --version

• doctor [path] は path にあるリポジトリ（デフォルト：カレントディレクトリ）をチェックし、人が読みやすいレポートを出力します。--json を追加すると、機械可読なレポートが出力されます。
• mcp は標準入出力で MCP サーバーを起動します。
• --version はバージョンを出力します。

終了コード：判定が HEALTHY の場合は 0、ISSUES の場合は 1、存在しない対象を指定するなどの使用法エラーの場合は 2、読み取り側が出力パイプを早期に閉じた場合は 141 です。

MCP

MCP サーバーは次のツールを公開します。

• doctor_env は path 引数を受け取り、CLI と同じチェックを実行して、JSON レポートを返します。

チェック

v0.1 では、次の 5 つのチェックをこの順序で実行します。

1. NODE-VERSION - 実行中の Node バージョン（process.version）を、対象の package.json にある engines.node の範囲と比較します。サポートされる範囲の構文：>=、<=、>、<、=、^20.0.0 のようなキャレット範囲、~20.11.0 のようなチルダ範囲、20.11.0 のような厳密なバージョン、20.x や 20.11.x のような x 範囲、部分バージョン、および >=18 <21 のようなスペース区切りの組み合わせです。範囲がこの構文に対応しない場合は、推測せず、ルール RANGE-UNSUPPORTED の情報項目として報告します。対象に package.json がない場合、このチェックはルール NO-PACKAGE-JSON の情報項目とともにスキップされ、残りのチェックは引き続き実行されます。
2. GIT-PRESENT - git --version が成功すると合格です。
3. NPM-PRESENT - npm --version が成功すると合格です。
4. LOCKFILE - 対象に package-lock.json、yarn.lock、pnpm-lock.yaml のいずれかが存在すると合格です（レポートにはどのファイルかが示されます）。ロックファイルがない場合は、ルール NO-LOCKFILE の中程度の重要度の項目となります。
5. ENV-FILE - 対象に .env.example が存在する場合のみ適用されます。.env がない場合は、ルール ENV-MISSING の中程度の重要度の項目となり、修正方法として「.env.example を .env にコピーして値を入力する」と示します。.env が存在する場合は、.env.example のキー名と .env のキー名を比較し、.env にないキー名ごとに、ルール ENV-KEYS-MISSING の中程度の重要度の項目となります。.env.example がない場合は、環境ファイルが不要なため、このチェックは合格します。

合格したチェックはすべて counts.checksPassed に計上され、レポートの検出項目にルール CHECK-PASS の情報項目として記載されるため、出力されるレポートには実行されたすべてのチェックが表示されます。

環境変数の値が出力に読み込まれることはありません

この保証は明確です。envdoctor が比較するのはキーの名前だけです。

• .env.example と .env はどちらも、各行の最初の = より左側のテキストだけを読み取って解析します。このテキストがキー名です。
• 最初の = 以降はすべて値です。値は解析時に破棄されます。保存、返却、ログへの記録、レポート、検出項目、概要、エラーへの出力は一切されません。
• 環境ファイルに関する検出項目では、値ではなくキー名を示します。たとえば、ENV-KEYS-MISSING の検出項目は、.env.example に記載されたキーが .env にないことを示します。値については何も示しません。

判定ルール

• HEALTHY - 中または高の重要度の検出項目がありません。合格したチェック、理由を明記してスキップしたチェック、RANGE-UNSUPPORTED などの情報メモは、この判定に影響しません。
• ISSUES - 中または高の重要度の検出項目が少なくとも 1 つあります。

レポートのカウントには checksRun、checksPassed、checksFailed、checksWarned、checksSkipped が含まれ、さらに重要度別の検出項目数も含まれます。

制限事項

• v0.1 では、Node、git、npm、およびファイルのみを確認します。具体的には、engines.node の範囲、2 つのツールのバージョン、ロックファイル、および前述の環境ファイルです。
• ポート、実行中のサービス、データベース、ネットワークへの到達性は、v0.1 では確認しません。ポートとサービスの確認は今後の対応予定です。
• ディスク容量は対象外です。
• NODE-VERSION に記載されている Node の範囲構文のみがサポートされています。それ以外の範囲構文では、合格または不合格ではなく、RANGE-UNSUPPORTED の情報項目が出力されます。
• 対象リポジトリ内では何も実行されません。envdoctor が実行するコマンドは git --version と npm --version のみです。