envspeak

EnvSpeak

.env ファイル、Docker Compose、Kubernetes にまたがる設定／環境変数の優先順位を解決する MCP サーバー兼 CLI です。実行時に変数が実際にどの値になるのか、その理由を AI エージェント（とあなた）に伝えます。

CSS のカスケードと同じ構造の問題です。複数のソースがあり、優先順位のルールが直感的でなく、値が「勝つ」のは定義された場所が理由にすぎません。これをスタイルシートではなく、アプリケーション設定に適用します。stylesafe と stylespeak の姉妹プロジェクトで、CSS に対して同じことを行います。

問題

実際のアプリの設定は、.env、.env.local、.env.production、Docker Compose の docker-compose.yml（environment: と env_file:）、Kubernetes の ConfigMap／Secret オブジェクト、コード内のハードコードされたフォールバックから構成されます。5 つ以上のレイヤーがあり、それぞれに独自の優先順位ルールがあるため、推測どおりには組み合わさりません。よく知られた落とし穴は、.env.production.local も存在しない限り、通常の .env.local が .env.production より優先されることです。これは、一般的な dotenv の優先順位では「local」が「環境固有」より優先されるためです。設定を編集するエージェントには、変数が実際にどの値に解決されるのか、また、あるレイヤーを変更すると何が壊れるのかを知る方法がありません。

ツール

• resolve_variable — DATABASE_URL は実際にどの値になり、どのファイルが優先されるのでしょうか？
• trace_variable — すべてのドメインと環境にわたって、この変数が設定されているすべての場所を表示します。
• impact_preview — このファイル内の値を変更すると、下流では実際に何が変わるのでしょうか。また、より優先順位の高い設定によって影響を受けないものは何でしょうか？
• config_manifest — プロジェクト全体を圧縮してまとめます。すべての変数、そのソース、リスクの高い箇所（追跡対象ファイルに置かれたシークレット、フォールバックなしでコードから読み取られているが、どこにもソースがない変数）を表示します。
• diff_environments — 2 つの環境／サービス／ワークロードですべての変数を解決し、実際に異なるものを確認します。

インストール

npm install -g @patrizzos/envspeak

MCP サーバーとして

{
  "mcpServers": {
    "envspeak": {
      "command": "envspeak"
    }
  }
}

CLI として

envspeak resolve DATABASE_URL --environment production
envspeak trace LOG_LEVEL
envspeak impact --file .env --variable LOG_LEVEL --newValue debug
envspeak manifest
envspeak diff --a '{"nodeEnv":"development"}' --b '{"nodeEnv":"production"}'

--files を省略すると、envspeak は --projectRoot（デフォルトはカレントディレクトリ）以下にある .env*、Compose、Kubernetes のマニフェストファイルを自動検出します。対象を明示するには --files a,b,c を渡してください。エージェントが読み取るものを正確に制御できるため、MCP 呼び出しではこの方法を推奨します。

実装済みの優先順位規約

dotenv（Next.js／Vite 形式、事実上の標準）：process.env（シェル）> .env.[env].local > .env.local > .env.[env] > .env > コード内のフォールバック（process.env.X || 'default'）。.env.local が .env.[env] より優先される点に注意してください。これが前述の落とし穴です。

Docker Compose：docker compose run -e（CLI）> environment: > env_file:（競合する場合、リストの最後のファイルが優先）> Dockerfile の ENV（解析対象外）。

Kubernetes：インラインの env: は常に envFrom:（ConfigMap／Secret の一括インポート。これらの間ではリストの最後のエントリーが優先）より優先されます。環境変数の値はポッドの起動時に固定されます。参照先の ConfigMap／Secret を編集しても、再起動またはロールアウトなしでは実行中のポッドに反映されません。impact_preview はこの点を警告します。

各結果には confidence レベルと caveat 文字列が含まれます。シェルでのエクスポートや CLI で渡された上書きは常に可能ですが、静的解析では決して確認できないためです。envspeak は、確信できないことを確実であるかのように装わず、その旨を明示します。

セキュリティ

• 実行時の依存関係はありません。 Compose／Kubernetes ファイルに使用する YAML サブセットパーサーは npm から取り込まずに手書きされているため、サードパーティのサプライチェーンにさらされるリスクはありません。npm audit が常にクリーンなのは、この設計によるものです。
• パストラバーサルを防止します。 ファイルの読み込み先は projectRoot を基準に解決され、ツール呼び出しで細工された相対パスが渡された場合でも、その範囲外へのアクセスを拒否します。
• プロトタイプ汚染を防止します。 YAML コンテンツから解析されたオブジェクトキー（__proto__、constructor、prototype）が、プロパティへの代入に使われることはありません。
• シークレットはデフォルトでマスキングされます。 Kubernetes の Secret の値は、どのツールで表示される場合でも、完全な値ではなく ab***yz の形式でのみ表示されます。
• シークレットらしさを判定するヒューリスティックを備えています。 変数名や値の形式（AWS キー、GitHub トークン、PEM ブロック、エントロピーが高く認証情報のような文字列）にフラグを立て、.gitignore と照合したうえで、黙って通過させるのではなく secretFlag／リスクのホットスポットとして表示します。
• バックトラッキングを行わない、入力サイズに制限された正規表現を使用します。 コードのデフォルト値のスキャンに使うパターンマッチングでは、マッチする長さに上限を設け、ネストした量指定子を避けることで、大きなファイルで ReDoS が発生しないようにしています。
• これらの保護策にかかわらず、envspeak は指定されたファイルをすべて読み取ります。ファイルシステムへのアクセス権を持つツールと同様に、エージェントが渡せる files リストの範囲を制限してください。

開発

npm test   # zero dependencies — no install step needed

ライセンス

MIT