@mcptoolshop/venvkit 0.2.0 → 0.2.5

package/README.es.md

@@ -0,0 +1,263 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/venvkit/readme.png" alt="venvkit" width="400">
+</p>
+
+# venvkit
+
+> Parte de [MCP Tool Shop](https://mcptoolshop.com)
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a>
+  <a href="https://mcp-tool-shop-org.github.io/venvkit/"><img src="https://img.shields.io/badge/Landing_Page-live-blue?style=flat-square" alt="Landing Page"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/venvkit"><img src="https://img.shields.io/npm/v/@mcptoolshop/venvkit?style=flat-square&color=cb3837" alt="npm version"></a>
+</p>
+
+**Herramienta de diagnóstico para entornos virtuales de Python en flujos de trabajo de aprendizaje automático para Windows.**
+
+Analiza su sistema en busca de entornos de Python, diagnostica problemas de salud (SSL, DLL, incompatibilidades de ABI, fugas de rutas), realiza un seguimiento del historial de ejecución de tareas, detecta tareas inestables y genera un mapa del ecosistema.
+
+## Guía de inicio rápido en 30 segundos
+
+```bash
+git clone https://github.com/mcp-tool-shop-org/venvkit && cd venvkit
+npm install && npm run build
+node dist/map_cli.js --root C:\projects --httpsProbe
+# Open .venvkit/venv-map.html in your browser
+```
+
+## Características
+
+- **doctorLite** - Comprobación rápida de la salud para cualquier intérprete de Python
+- Verificación SSL/TLS
+- Fallos al cargar DLL (común con PyTorch/CUDA)
+- Incompatibilidades de ABI (ARM vs x86)
+- Comprobaciones de integridad de pip
+- Detección de fugas de `user-site` y `PYTHONPATH`
+
+- **scanEnvPaths** - Descubre todos los entornos de Python en tu sistema
+- Encuentra entornos venv, entornos conda, versiones pyenv, intérpretes base
+- Profundidad y filtrado configurables
+
+- **mapRender** - Visualiza tu ecosistema de Python
+- Salida de gráfico en formato JSON para uso programático
+- Diagramas Mermaid para documentación
+- Agrupación de intérpretes base con análisis de radio de impacto
+- Visualización de enrutamiento de tareas
+
+- **runLog** - Realiza un seguimiento del historial de ejecución de tareas
+- Formato JSONL de solo anexión
+- Registra qué entorno ejecutó qué tarea
+- Captura el éxito/fracaso con clasificación de errores
+
+- **taskCluster** - Agrupa las ejecuciones de tareas por firma
+- Detección de tareas inestables (fallos/éxitos inconsistentes)
+- Detección de inestabilidad dependiente del entorno
+- Identificación de puntos críticos de fallo
+- Análisis de contagio (causas raíz compartidas)
+
+## Instalación
+
+```bash
+npm install
+npm run build
+```
+
+## Uso de la línea de comandos
+
+```bash
+# Scan current directory and generate ecosystem map
+node dist/map_cli.js
+
+# Scan specific directories
+node dist/map_cli.js --root C:\projects --root D:\ml-experiments
+
+# Include task run history
+node dist/map_cli.js --runlog .venvkit/runs.jsonl
+
+# Output options
+node dist/map_cli.js --out ./output --minScore 50 --strict --httpsProbe
+```
+
+### Opciones de la línea de comandos
+
+| Flag | Descripción |
+| ------ | ------------- |
+| `--root, -r` | Directorio a analizar (se puede especificar varios) |
+| `--out` | Directorio de salida (por defecto: `.venvkit`) |
+| `--maxDepth` | Profundidad máxima del directorio a analizar (por defecto: 5) |
+| `--strict` | Habilitar comprobaciones de modo estricto |
+| `--httpsProbe` | Probar la conectividad HTTPS |
+| `--minScore` | Filtrar entornos por debajo de esta puntuación de salud |
+| `--concurrency` | Comprobaciones paralelas (por defecto: número de núcleos de la CPU) |
+| `--runlog` | Ruta al registro de ejecución de tareas (JSONL) |
+| `--no-tasks` | Omitir la visualización de tareas |
+
+### Salidas
+
+| File | Descripción |
+| ------ | ------------- |
+| `venv-map.json` | Datos completos del gráfico (nodos, aristas, resumen) |
+| `venv-map.mmd` | Código fuente del diagrama Mermaid |
+| `venv-map.html` | Visor interactivo |
+| `reports.json` | Informes raw de doctorLite |
+| `insights.json` | Recomendaciones prácticas |
+
+## Uso programático
+
+```typescript
+import { doctorLite, scanEnvPaths, mapRender, readRunLog } from 'venvkit';
+
+// Check a specific Python
+const report = await doctorLite({
+  pythonPath: 'C:\\project\\.venv\\Scripts\\python.exe',
+  requiredModules: ['torch', 'transformers'],
+  httpsProbe: true,
+});
+
+console.log(report.status); // 'good' | 'warn' | 'bad'
+console.log(report.score);  // 0-100
+console.log(report.findings); // Array of issues
+
+// Scan for all Python environments
+const scan = await scanEnvPaths({
+  roots: ['C:\\projects'],
+  maxDepth: 5,
+});
+
+// Run doctorLite on all found environments
+const reports = await Promise.all(
+  scan.pythonPaths.map(p => doctorLite({ pythonPath: p }))
+);
+
+// Load task execution history
+const runs = await readRunLog('.venvkit/runs.jsonl');
+
+// Generate ecosystem visualization
+const { graph, mermaid, insights } = mapRender(reports, runs, {
+  taskMode: 'clustered', // 'none' | 'runs' | 'clustered'
+  includeHotEdgeLabels: true,
+});
+```
+
+## Esquema del registro
+
+Realiza un seguimiento de las ejecuciones de tareas añadiendo eventos a un archivo JSONL:
+
+```typescript
+import { appendRunLog, newRunId } from 'venvkit';
+
+await appendRunLog('.venvkit/runs.jsonl', {
+  version: '1.0',
+  runId: newRunId(),
+  at: new Date().toISOString(),
+  task: {
+    name: 'train',
+    command: 'python train.py --epochs 10',
+    requirements: { packages: ['torch', 'transformers'] },
+  },
+  selected: {
+    pythonPath: 'C:\\project\\.venv\\Scripts\\python.exe',
+    score: 95,
+    status: 'good',
+  },
+  outcome: {
+    ok: true,
+    exitCode: 0,
+    durationMs: 45000,
+  },
+});
+```
+
+## Agrupación de tareas
+
+Cuando tienes muchas ejecuciones de tareas, venvkit las agrupa por firma:
+
+```typescript
+import { clusterRuns, isFlaky, getFailingEnvs } from 'venvkit';
+
+const clusters = clusterRuns(runs);
+
+for (const c of clusters) {
+  console.log(`${c.sig.name}: ${c.ok}/${c.runs} (${(c.successRate * 100).toFixed(0)}%)`);
+
+  if (isFlaky(c)) {
+    console.log(`  WARNING: Flaky task!`);
+    const badEnvs = getFailingEnvs(c, 3);
+    console.log(`  Failing most on: ${badEnvs.map(e => e.pythonPath).join(', ')}`);
+  }
+}
+```
+
+## Esquema del gráfico
+
+La salida de `mapRender` sigue un esquema JSON estable:
+
+```typescript
+type GraphJSONv1 = {
+  version: '1.0';
+  generatedAt: string;
+  host: { os: string; arch: string; hostname: string };
+  summary: {
+    envCount: number;
+    baseCount: number;
+    taskCount: number;
+    healthy: number;
+    warning: number;
+    broken: number;
+    runsPassed: number;
+    runsFailed: number;
+    topIssues: Array<{ code: string; count: number; hint: string }>;
+  };
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+};
+```
+
+### Tipos de nodos
+
+| Type | Descripción |
+| ------ | ------------- |
+| `base` | Intérprete de Python base (por ejemplo, `C:\Python311`) |
+| `venv` | Entorno virtual |
+| `task` | Firma de tarea (ejecuciones agrupadas) |
+
+### Tipos de aristas
+
+| Type | Descripción |
+| ------ | ------------- |
+| `USES_BASE` | Relación venv → base |
+| `ROUTES_TASK_TO` | Enrutamiento de tarea → entorno |
+| `FAILED_RUN` | Fallo de tarea → entorno (con líneas discontinuas en Mermaid) |
+
+## Códigos de error
+
+| Code | Severidad | Descripción |
+| ------ | ---------- | ------------- |
+| `SSL_BROKEN` | bad | El módulo SSL no se puede importar |
+| `CERT_STORE_FAIL` | warn | La verificación del certificado HTTPS falla |
+| `DLL_LOAD_FAIL` | bad | La carga de la DLL de la extensión nativa falla |
+| `ABI_MISMATCH` | bad | Incompatibilidad binaria (ARM/x86) |
+| `PIP_MISSING` | warn | pip no está disponible |
+| `PIP_CHECK_FAIL` | warn | Se detectan conflictos de dependencias |
+| `USER_SITE_LEAK` | warn | Los paquetes del usuario están habilitados en el entorno virtual. |
+| `PYTHONPATH_INJECTED` | warn | La variable de entorno PYTHONPATH está configurada. |
+| `ARCH_MISMATCH` | bad | Se está utilizando una versión de Python de 32 bits cuando se requiere una versión de 64 bits. |
+| `PYVENV_CFG_INVALID` | warn | Archivo pyvenv.cfg dañado o faltante. |
+
+## Desarrollo
+
+```bash
+npm install
+npm run typecheck  # Type check
+npm run test       # Run tests
+npm run build      # Build to dist/
+```
+
+## Licencia
+
+MIT.

package/README.fr.md

@@ -0,0 +1,263 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/venvkit/readme.png" alt="venvkit" width="400">
+</p>
+
+# venvkit
+
+> Fait partie de [MCP Tool Shop](https://mcptoolshop.com)
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/venvkit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a>
+  <a href="https://mcp-tool-shop-org.github.io/venvkit/"><img src="https://img.shields.io/badge/Landing_Page-live-blue?style=flat-square" alt="Landing Page"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/venvkit"><img src="https://img.shields.io/npm/v/@mcptoolshop/venvkit?style=flat-square&color=cb3837" alt="npm version"></a>
+</p>
+
+**Outil de diagnostic pour les environnements virtuels Python, conçu pour les flux de travail d'apprentissage automatique (ML) sous Windows.**
+
+Analyse votre système pour détecter les environnements Python, diagnostique les problèmes de santé (SSL, DLL, incompatibilités ABI, fuites de chemins), suit l'historique d'exécution des tâches, détecte les tâches instables et génère une carte de l'écosystème.
+
+## Démarrage rapide en 30 secondes
+
+```bash
+git clone https://github.com/mcp-tool-shop-org/venvkit && cd venvkit
+npm install && npm run build
+node dist/map_cli.js --root C:\projects --httpsProbe
+# Open .venvkit/venv-map.html in your browser
+```
+
+## Fonctionnalités
+
+- **doctorLite** - Vérification rapide de l'état de santé de n'importe quel interpréteur Python
+- Vérification SSL/TLS
+- Échecs de chargement des DLL (courant avec PyTorch/CUDA)
+- Incompatibilités ABI (ARM vs x86)
+- Vérifications de l'intégrité de pip
+- Détection des fuites de `user-site` et de `PYTHONPATH`
+
+- **scanEnvPaths** - Découvre tous les environnements Python de votre système
+- Trouve les environnements venv, conda, les versions pyenv et les interpréteurs de base.
+- Profondeur et filtrage configurables.
+
+- **mapRender** - Visualise votre écosystème Python
+- Sortie JSON pour une utilisation programmatique.
+- Diagrammes Mermaid pour la documentation.
+- Groupement des interpréteurs de base avec analyse du rayon d'impact.
+- Visualisation du routage des tâches.
+
+- **runLog** - Suit l'historique d'exécution des tâches
+- Format JSONL uniquement en ajout.
+- Enregistre quel environnement a exécuté quelle tâche.
+- Enregistre les succès/échecs avec la classification des erreurs.
+
+- **taskCluster** - Regroupe les exécutions de tâches par signature
+- Détection des tâches instables (échec/succès incohérents).
+- Détection des instabilités dépendantes de l'environnement.
+- Identification des points chauds d'échec.
+- Analyse de la contagion (causes profondes partagées).
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Utilisation de l'interface en ligne de commande (CLI)
+
+```bash
+# Scan current directory and generate ecosystem map
+node dist/map_cli.js
+
+# Scan specific directories
+node dist/map_cli.js --root C:\projects --root D:\ml-experiments
+
+# Include task run history
+node dist/map_cli.js --runlog .venvkit/runs.jsonl
+
+# Output options
+node dist/map_cli.js --out ./output --minScore 50 --strict --httpsProbe
+```
+
+### Options de l'interface en ligne de commande (CLI)
+
+| Flag | Description |
+| ------ | ------------- |
+| `--root, -r` | Répertoire à analyser (peut spécifier plusieurs) |
+| `--out` | Répertoire de sortie (par défaut : `.venvkit`) |
+| `--maxDepth` | Profondeur maximale du répertoire à analyser (par défaut : 5) |
+| `--strict` | Activer les vérifications strictes |
+| `--httpsProbe` | Tester la connectivité HTTPS |
+| `--minScore` | Filtrer les environnements en fonction de leur score de santé |
+| `--concurrency` | Vérifications parallèles (par défaut : nombre de cœurs CPU) |
+| `--runlog` | Chemin vers le fichier journal d'exécution des tâches (JSONL) |
+| `--no-tasks` | Ignorer la visualisation des tâches |
+
+### Sorties
+
+| File | Description |
+| ------ | ------------- |
+| `venv-map.json` | Données complètes du graphique (nœuds, arêtes, résumé) |
+| `venv-map.mmd` | Source du diagramme Mermaid |
+| `venv-map.html` | Visualiseur interactif |
+| `reports.json` | Rapports doctorLite bruts |
+| `insights.json` | Recommandations exploitables |
+
+## Utilisation programmatique
+
+```typescript
+import { doctorLite, scanEnvPaths, mapRender, readRunLog } from 'venvkit';
+
+// Check a specific Python
+const report = await doctorLite({
+  pythonPath: 'C:\\project\\.venv\\Scripts\\python.exe',
+  requiredModules: ['torch', 'transformers'],
+  httpsProbe: true,
+});
+
+console.log(report.status); // 'good' | 'warn' | 'bad'
+console.log(report.score);  // 0-100
+console.log(report.findings); // Array of issues
+
+// Scan for all Python environments
+const scan = await scanEnvPaths({
+  roots: ['C:\\projects'],
+  maxDepth: 5,
+});
+
+// Run doctorLite on all found environments
+const reports = await Promise.all(
+  scan.pythonPaths.map(p => doctorLite({ pythonPath: p }))
+);
+
+// Load task execution history
+const runs = await readRunLog('.venvkit/runs.jsonl');
+
+// Generate ecosystem visualization
+const { graph, mermaid, insights } = mapRender(reports, runs, {
+  taskMode: 'clustered', // 'none' | 'runs' | 'clustered'
+  includeHotEdgeLabels: true,
+});
+```
+
+## Schéma du journal d'exécution
+
+Suivez les exécutions de tâches en ajoutant des événements à un fichier JSONL :
+
+```typescript
+import { appendRunLog, newRunId } from 'venvkit';
+
+await appendRunLog('.venvkit/runs.jsonl', {
+  version: '1.0',
+  runId: newRunId(),
+  at: new Date().toISOString(),
+  task: {
+    name: 'train',
+    command: 'python train.py --epochs 10',
+    requirements: { packages: ['torch', 'transformers'] },
+  },
+  selected: {
+    pythonPath: 'C:\\project\\.venv\\Scripts\\python.exe',
+    score: 95,
+    status: 'good',
+  },
+  outcome: {
+    ok: true,
+    exitCode: 0,
+    durationMs: 45000,
+  },
+});
+```
+
+## Regroupement des tâches
+
+Lorsque vous avez de nombreuses exécutions de tâches, venvkit les regroupe par signature :
+
+```typescript
+import { clusterRuns, isFlaky, getFailingEnvs } from 'venvkit';
+
+const clusters = clusterRuns(runs);
+
+for (const c of clusters) {
+  console.log(`${c.sig.name}: ${c.ok}/${c.runs} (${(c.successRate * 100).toFixed(0)}%)`);
+
+  if (isFlaky(c)) {
+    console.log(`  WARNING: Flaky task!`);
+    const badEnvs = getFailingEnvs(c, 3);
+    console.log(`  Failing most on: ${badEnvs.map(e => e.pythonPath).join(', ')}`);
+  }
+}
+```
+
+## Schéma du graphique
+
+La sortie de `mapRender` suit un schéma JSON stable :
+
+```typescript
+type GraphJSONv1 = {
+  version: '1.0';
+  generatedAt: string;
+  host: { os: string; arch: string; hostname: string };
+  summary: {
+    envCount: number;
+    baseCount: number;
+    taskCount: number;
+    healthy: number;
+    warning: number;
+    broken: number;
+    runsPassed: number;
+    runsFailed: number;
+    topIssues: Array<{ code: string; count: number; hint: string }>;
+  };
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+};
+```
+
+### Types de nœuds
+
+| Type | Description |
+| ------ | ------------- |
+| `base` | Interpréteur Python de base (par exemple, `C:\Python311`) |
+| `venv` | Environnement virtuel |
+| `task` | Signature de la tâche (exécutions regroupées) |
+
+### Types d'arêtes
+
+| Type | Description |
+| ------ | ------------- |
+| `USES_BASE` | Relation venv → base |
+| `ROUTES_TASK_TO` | Routage tâche → environnement |
+| `FAILED_RUN` | Échec de la tâche → environnement (pointillé dans Mermaid) |
+
+## Codes d'erreur
+
+| Code | Gravité | Description |
+| ------ | ---------- | ------------- |
+| `SSL_BROKEN` | bad | Le module SSL ne parvient pas à s'importer |
+| `CERT_STORE_FAIL` | warn | La vérification du certificat HTTPS échoue |
+| `DLL_LOAD_FAIL` | bad | Le chargement de l'extension DLL native échoue |
+| `ABI_MISMATCH` | bad | Incompatibilité binaire (ARM/x86) |
+| `PIP_MISSING` | warn | pip n'est pas disponible |
+| `PIP_CHECK_FAIL` | warn | Conflits de dépendances détectés |
+| `USER_SITE_LEAK` | warn | L'installation des packages utilisateur est activée dans l'environnement virtuel. |
+| `PYTHONPATH_INJECTED` | warn | La variable d'environnement PYTHONPATH est définie. |
+| `ARCH_MISMATCH` | bad | Version 32 bits de Python utilisée alors qu'une version 64 bits est requise. |
+| `PYVENV_CFG_INVALID` | warn | Fichier pyvenv.cfg corrompu ou manquant. |
+
+## Développement
+
+```bash
+npm install
+npm run typecheck  # Type check
+npm run test       # Run tests
+npm run build      # Build to dist/
+```
+
+## Licence
+
+MIT.