PkgDiet

Política de dependencias y salvaguarda MCP. Evita que los agentes de IA alucinen paquetes npm obsoletos.

Documentación

🥗 PkgDiet

Política de dependencias para el desarrollo asistido por IA de JavaScript y TypeScript.
Pon tu node_modules a dieta.

El problema: Los agentes de codificación con IA pueden proponer paquetes inexistentes, obsoletos, no aprobados o inadecuados. Los equipos necesitan una forma consistente de evaluar esas elecciones antes y después de los cambios de dependencias.

La solución: PkgDiet es una barrera de seguridad determinista para dependencias. Verifica las dependencias propuestas contra la salud del registro, el estado de obsolescencia y tu política local del proyecto antes de que se instalen, forzando a los agentes a cambiar a alternativas modernas.

🔄 El Bucle de Política en 3 Fases

PkgDiet garantiza que una dependencia se evalúe de manera idéntica en cada etapa de tu ciclo de vida de desarrollo utilizando un motor central compartido (@pkgdiet/core).

Política del Repositorio: Un único archivo .pkgdietrc.json dicta lo que está permitido, advertido o bloqueado para tu proyecto.
Guía del Agente (MCP): Los clientes de IA se conectan a PkgDiet mediante el Protocolo de Contexto de Modelo (npx pkgdiet mcp). Antes de escribir npm install, el agente pregunta a PkgDiet si un paquete cumple con la política. Si está bloqueado, PkgDiet proporciona alternativas modernas seleccionadas.
Aplicación en Merge (CI): PkgDiet se ejecuta en GitHub Actions (npx pkgdiet ci --base origin/main). Compara package.json para aislar las dependencias directas recién solicitadas. Si un paquete bloqueado eludió al agente y llegó al PR, el CI falla y detiene el merge.

🚀 Inicio Rápido

Inicializa PkgDiet en tu repositorio. Este comando interactivo crea tu política .pkgdietrc.json, configura tu flujo de trabajo CI de GitHub Actions y configura tus agentes de IA locales (Cursor, Windsurf, Cline) todo a la vez:

npx pkgdiet init

Audita tu proyecto existente para ver cómo tus node_modules actuales se comparan con tu nueva política:

npx pkgdiet audit

🛠️ Comandos CLI

Usage: pkgdiet [options] [command]

Dependency policy for AI-assisted development — audit, check, and enforce npm dependency rules

Options:
  -v, --version                  output the version number
  -h, --help                     display help for command

Commands:
  audit [options]                Audit existing dependencies for policy, health, size, and unused-package signals
  check [options] <packages...>  Evaluate npm packages against this repository’s dependency policy
  mcp [args...]                  Start the MCP JSON-RPC server over stdio for MCP-compatible AI coding agents
  ci [options]                   Enforce policy for dependency changes introduced by this branch
  alternatives                   Browse the PkgDiet alternatives dataset
  drift [options]                Scan project for dependency health drift over time
  setup                          Create a starter .pkgdietrc.json policy
  agent-setup [options]          Configure PkgDiet for AI coding agents
  init [options]                 Set up PkgDiet in this project — creates policy, CI workflow, and all AI agent configs
  pr [options]                   Generate a reviewer-ready pull request for adding PkgDiet to any GitHub repo
  policy-check [options]         Validate the repository’s .pkgdietrc.json policy

⚙️ Configuración (`.pkgdietrc.json`)

La configuración de la política admite superposiciones de entorno, listas de bloqueo explícitas y umbrales de fallo estrictos.

{
  "minHealthScore": 60,
  "warnHealthScore": 80,
  "blockDeprecated": true,
  "maxAddedSizeMB": 5.0,
  "failOn": ["BLOCK", "UNKNOWN"],
  
  "blockedPackages": {
    "moment": "Deprecated. Use date-fns instead.",
    "request": "Deprecated. Use native fetch."
  },

  "environments": {
    "ci": {
      "failOn": ["BLOCK", "UNKNOWN", "WARN"]
    }
  },

  "exceptions": {
    "lodash": {
      "allow": ["HEALTH_SCORE_MIN", "PACKAGE_OVERSIZE"],
      "expires": "2027-01-01",
      "reason": "Legacy dependency; migration planned for Q1."
    }
  }
}

Nota: Las excepciones están estrictamente limitadas. No pueden eludir PACKAGE_NOT_FOUND (alucinaciones), tiempos de espera del registro (UNKNOWN) ni entradas explícitas en blockedPackages.

🤖 Integración MCP

PkgDiet actúa como un servidor local del Protocolo de Contexto de Modelo (MCP).

Cuando tu agente de codificación con IA se conecta a PkgDiet, obtiene acceso a:

check_dependency: Evalúa un paquete npm contra tu política local .pkgdietrc.json y devuelve veredictos estructurados de ALLOW, WARN o BLOCK.
suggest_alternative: Consulta el conjunto de datos seleccionado de PkgDiet para encontrar alternativas modernas, más ligeras y mantenidas para paquetes bloqueados.

Para configurar tu agente automáticamente, ejecuta:

npx pkgdiet agent-setup --detect

🔗 Documentación y Soporte

Repositorio de GitHub: om-tajne/pkgdiet
Reportar un Problema: Rastreador de Problemas
Licencia: MIT