pkgdiet

🥗 PkgDiet

AI 支援による JavaScript および TypeScript 開発のための依存関係ポリシー。
node_modules をダイエットさせましょう。

問題： AI コーディングエージェント（Claude Code、Codex、Cursor、Windsurf、Cline）は、存在しないパッケージ、非推奨のパッケージ、脆弱性のあるパッケージ、またはタイポスクワッティングされたパッケージを提案します。インストールの実行を止める組み込みの仕組みはありません。

解決策： PkgDiet は、AI エージェントが生成するすべての npm install／pnpm add／yarn add コマンドを、ネイティブのエージェントフック API を使って検知し、未承認のインストールが実行される前にブロックします。

---

🔒 実証

以下を実行すると、PkgDiet が実際にリスクのある AI 生成依存関係をターミナルでブロックする様子を確認できます。

npx [email protected] demo

出力例：

🔒 PkgDiet — Live AI Dependency Enforcement Demo
   Simulating what happens when an AI agent tries to install these packages.

🟡  WARNING — moment
   Context:   AI suggested this for date formatting
   Score:     100/100
   Reason:    Efficiency Flag: Better alternatives exist for moment.
   Use this:  dayjs, date-fns

🔴  BLOCKED — request
   Context:   AI suggested this for HTTP requests
   Score:     15/100
   Reason:    Health score 15 is below minimum allowed (60).
   Use this:  undici, native fetch
   CVEs:      GHSA-p8p7-x288-28g6

   🔒 PkgDiet blocked this risky AI-generated dependency before install.

🔴  BLOCKED — node-uuid
   Context:   AI suggested this for UUID generation
   Score:     15/100
   Reason:    Health score 15 is below minimum allowed (60).
   Use this:  crypto.randomUUID(), uuid

   🔒 PkgDiet blocked this risky AI-generated dependency before install.

🟡  WARNING — lodash
   Context:   AI suggested this for array utilities
   Score:     80/100
   Reason:    Efficiency Flag: Better alternatives exist for lodash.
   Use this:  lodash-es, native JS

📊 Demo Summary: 2 blocked, 2 warned
   These checks run automatically before every npm install in your AI agent.
   Setup: npx [email protected] init

CI で機械可読な証明を得るには：

npx [email protected] demo --json

---

🚀 ワンコマンドセットアップ

npx [email protected] init

このコマンドひとつで、以下が作成されます。

ファイル	用途
.pkgdietrc.json	リポジトリの依存関係ポリシー
.github/workflows/pkgdiet.yml	GitHub Actions の CI ゲート
.cursor/mcp.json	Cursor MCP サーバー
.cursor/rules/pkgdiet.mdc	Cursor で常に適用される適用ルール
.cursorrules	Cursor の助言ルール（レガシー）
.windsurfrules	Windsurf の助言ルール
cline_mcp_settings.json	Cline MCP サーバー
.github/mcp.json	GitHub Copilot MCP
CLAUDE.md	Claude Code の助言ルール
.claude/settings.json	Claude Code の PreToolUse フック登録
.claude/hooks/pkgdiet-install-guard.sh	Claude Code の bash インストールガード
.codex/hooks.json	Codex の PreToolUse フック登録
.codex/hooks/pkgdiet-install-guard.mjs	Codex の Node.js インストールガード

---

🛡️ エージェントによる強制

PkgDiet は、助言的なルールだけでなく、各エージェントのネイティブなフック APIを使用してインストールをブロックします。

エージェント	強制メカニズム	ブロックする内容
Claude Code	PreToolUse bash フック（.claude/hooks/）	実行前の npm/pnpm/yarn install
Codex (OpenAI)	PreToolUse Node.js フック（.codex/hooks/）	実行前の npm/pnpm/yarn install
Cursor	MDC alwaysApply ルール ＋ MCP check_dependency	AI によるインストールコマンドの記述を防止
Windsurf	.windsurfrules ＋ MCP check_dependency	AI によるインストールコマンドの記述を防止
Cline	MCP check_dependency	ツール呼び出しを通じて、インストール前にブロック
GitHub Copilot	MCP check_dependency	ツール呼び出しを通じて、インストール前にブロック
CI (GitHub Actions)	pkgdiet ci ゲート	新しいパッケージがポリシーに違反した場合、PR のマージをブロック

PreToolUse フックの仕組み： Claude Code または Codex が npm install を含む Bash ツール呼び出しを生成すると、登録されたフックスクリプトが最初に実行されます。PkgDiet がゼロ以外の終了コードを返した場合、エージェントは拒否理由を受け取り、インストールを中止します。コマンドは実行されません。

---

🔄 3 フェーズのポリシーループ

PkgDiet は共有コアエンジン（@pkgdiet/core）を使用するため、すべてのインターフェースに同じ評価ロジックが適用されます。

1. リポジトリポリシー： 単一の .pkgdietrc.json ファイルで、プロジェクトで許可、警告、またはブロックする内容を指定します。
2. エージェントフック（強制）： Claude Code と Codex のネイティブな PreToolUse フックが、実行前にインストールコマンドをインターセプトします。MCP check_dependency は、ほかのエージェントがコマンドを記述する前に指示を提供します。
3. CI ゲート（フォールバック）： npx pkgdiet ci が GitHub Actions で実行され、package.json をベースコミットと比較します。追加されたパッケージがポリシーに違反した場合、PR は失敗します。

---

🛠️ CLI コマンド

Commands:
  audit           Audit existing dependencies for policy, health, size, and unused-package signals
  check           Evaluate npm packages against this repository's dependency policy
  demo            Show live proof that PkgDiet blocks risky AI-generated dependencies before install
  mcp             Start the MCP JSON-RPC server over stdio for MCP-compatible AI coding agents
  ci              Enforce policy for dependency changes introduced by this branch
  init            Set up PkgDiet — creates policy, CI workflow, and all AI agent configs
  agent-setup     Configure PkgDiet for AI coding agents (codex, cursor, claude-code, ...)
  alternatives    Browse the PkgDiet alternatives dataset
  drift           Scan project for dependency health drift over time
  policy-check    Validate the repository's .pkgdietrc.json policy

---

⚙️ 設定（.pkgdietrc.json）

{
  "minHealthScore": 70,
  "warnHealthScore": 80,
  "blockDeprecated": true,
  "blockKnownVulnerabilities": true,
  "blockTyposquats": false,
  "requirePinnedVersions": true,
  "maxPackageSizeBytes": 15728640,
  "failOn": "BLOCK",
  "securityMode": "fail-open",
  "blockedPackages": ["moment", "request"],
  "internalNamePrefixes": [],
  "environments": {
    "ci": { "minHealthScore": 80, "failOn": "BLOCK", "securityMode": "fail-closed" },
    "dev": { "minHealthScore": 60, "failOn": "BLOCK", "securityMode": "fail-open" }
  }
}

---

🤖 MCP 統合

PkgDiet はローカルの Model Context Protocol（MCP）サーバーとして動作します。

AI コーディングエージェントが PkgDiet に接続すると、次の機能を利用できます。

• check_dependency：npm パッケージをローカルの .pkgdietrc.json ポリシーに照らして評価し、根拠とともに構造化された ALLOW、WARN、または BLOCK の判定を返します。
• suggest_alternative：PkgDiet の厳選データセットを検索し、ブロックされたパッケージに代わる、最新で、軽量かつメンテナンスされているパッケージを見つけます。

含まれるインテリジェンス（すべて無料。有料サービスはありません）：

• OSV 脆弱性データベース — パッケージのバージョンに既知の CVE がないか確認します
• npm レジストリの来歴情報 — 署名付き npm 証明書を検証します
• タイポスクワットの検出 — 人気のパッケージ名 15 件以上と編集距離を比較します
• ロックファイルのバージョン固定の検証 — CI で厳密なバージョン固定を必須にします
• 依存関係の混乱の検出 — パブリックレジストリで見つかった内部プレフィックス付きパッケージをブロックします

---

🔗 ドキュメントとサポート

• GitHub リポジトリ： om-tajne/pkgdiet
• 問題の報告： 課題トラッカー
• ライセンス： MIT