@mcptoolshop/venvkit 0.2.0 → 0.2.5

package/README.zh.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
+
+> [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>
+
+**用于 Windows 机器学习工作流程的 Python 虚拟环境诊断工具包。**
+
+该工具会扫描您的系统中的 Python 环境，诊断健康问题（SSL、DLL、ABI 不匹配、路径泄露），跟踪任务执行历史，检测不可靠的任务，并生成一个生态系统图。
+
+## 30 秒快速入门
+
+```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
+```
+
+## 功能
+
+- **doctorLite** - 快速检查任何 Python 解释器的健康状况
+- SSL/TLS 验证
+- DLL 加载失败（常见于 PyTorch/CUDA）
+- ABI 不匹配（ARM 与 x86）
+- pip 检查
+- 用户站点和 PYTHONPATH 泄露检测
+
+- **scanEnvPaths** - 发现系统中的所有 Python 环境
+- 查找 venvs、conda 环境、pyenv 版本、基本解释器
+- 可配置的深度和过滤
+
+- **mapRender** - 可视化您的 Python 生态系统
+- 图形 JSON 输出，用于程序化使用
+- Mermaid 图表，用于文档
+- 基本解释器分组，并进行影响范围分析
+- 任务路由可视化
+
+- **runLog** - 跟踪任务执行历史
+- 仅追加的 JSONL 格式
+- 记录哪个环境运行了哪个任务
+- 记录成功/失败，并进行错误分类
+
+- **taskCluster** - 按签名聚合任务运行
+- 检测不可靠的任务（不一致的通过/失败）
+- 基于环境的不可靠性检测
+- 识别失败热点
+- 传染分析（共享的根本原因）
+
+## 安装
+
+```bash
+npm install
+npm run build
+```
+
+## 命令行用法
+
+```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
+```
+
+### 命令行选项
+
+| Flag | 描述 |
+| ------ | ------------- |
+| `--root, -r` | 要扫描的目录（可以指定多个） |
+| `--out` | 输出目录（默认为：`.venvkit`） |
+| `--maxDepth` | 要扫描的最大目录深度（默认为：5） |
+| `--strict` | 启用严格模式检查 |
+| `--httpsProbe` | 测试 HTTPS 连接 |
+| `--minScore` | 过滤健康评分低于此值的环境 |
+| `--concurrency` | 并行检查（默认为：CPU 数量） |
+| `--runlog` | 任务运行日志的路径（JSONL） |
+| `--no-tasks` | 跳过任务可视化 |
+
+### 输出
+
+| File | 描述 |
+| ------ | ------------- |
+| `venv-map.json` | 完整的图形数据（节点、边、摘要） |
+| `venv-map.mmd` | Mermaid 图表源代码 |
+| `venv-map.html` | 交互式查看器 |
+| `reports.json` | 原始的 doctorLite 报告 |
+| `insights.json` | 可操作的建议 |
+
+## 程序化用法
+
+```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,
+});
+```
+
+## 运行日志模式
+
+通过将事件追加到 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,
+  },
+});
+```
+
+## 任务聚类
+
+当您有许多任务运行时，venvkit 会根据签名对它们进行聚类：
+
+```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(', ')}`);
+  }
+}
+```
+
+## 图形模式
+
+`mapRender` 输出遵循稳定的 JSON 模式：
+
+```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[];
+};
+```
+
+### 节点类型
+
+| Type | 描述 |
+| ------ | ------------- |
+| `base` | 基本 Python 解释器（例如：`C:\Python311`） |
+| `venv` | 虚拟环境 |
+| `task` | 任务签名（聚类运行） |
+
+### 边类型
+
+| Type | 描述 |
+| ------ | ------------- |
+| `USES_BASE` | venv → 基本关系 |
+| `ROUTES_TASK_TO` | 任务 → 环境路由 |
+| `FAILED_RUN` | 任务 → 环境失败（Mermaid 中以虚线表示） |
+
+## 查找代码
+
+| Code | 严重性 | 描述 |
+| ------ | ---------- | ------------- |
+| `SSL_BROKEN` | bad | SSL 模块无法导入 |
+| `CERT_STORE_FAIL` | warn | HTTPS 证书验证失败 |
+| `DLL_LOAD_FAIL` | bad | 本机扩展 DLL 加载失败 |
+| `ABI_MISMATCH` | bad | 二进制不兼容（ARM/x86） |
+| `PIP_MISSING` | warn | pip 不可用 |
+| `PIP_CHECK_FAIL` | warn | 检测到依赖项冲突 |
+| `USER_SITE_LEAK` | warn | venv 环境中启用了用户 site-packages。 |
+| `PYTHONPATH_INJECTED` | warn | 已设置 PYTHONPATH 环境变量。 |
+| `ARCH_MISMATCH` | bad | 使用了 32 位的 Python，但需要 64 位。 |
+| `PYVENV_CFG_INVALID` | warn | pyvenv.cfg 文件损坏或缺失。 |
+
+## 开发
+
+```bash
+npm install
+npm run typecheck  # Type check
+npm run test       # Run tests
+npm run build      # Build to dist/
+```
+
+## 许可证
+
+MIT 协议。

package/package.json

@@ -1,58 +1,69 @@
-{
-  "name": "@mcptoolshop/venvkit",
-  "version": "0.2.0",
-  "description": "Python virtual environment diagnostic toolkit for Windows ML workflows",
-  "author": {
-    "name": "mcp-tool-shop",
-    "email": "64996768+mcp-tool-shop@users.noreply.github.com"
-  },
-  "keywords": ["python", "venv", "virtualenv", "diagnostics", "health-check", "windows", "ml", "pytorch", "environment"],
-  "license": "MIT",
-  "homepage": "https://github.com/mcp-tool-shop/venvkit",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/mcp-tool-shop/venvkit"
-  },
-  "bugs": {
-    "url": "https://github.com/mcp-tool-shop/venvkit/issues"
-  },
-  "private": false,
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "venvkit-map": "./dist/map_cli.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "lint": "eslint .",
-    "format": "eslint . --fix",
-    "audit": "npm audit",
-    "map": "node dist/map_cli.js"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.0.0",
-    "eslint": "^9.0.0",
-    "@eslint/js": "^9.0.0",
-    "typescript-eslint": "^8.0.0"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  }
-}
+{
+  "name": "@mcptoolshop/venvkit",
+  "version": "0.2.5",
+  "description": "Python virtual environment diagnostic toolkit for Windows ML workflows",
+  "author": {
+    "name": "mcp-tool-shop",
+    "email": "64996768+mcp-tool-shop@users.noreply.github.com"
+  },
+  "keywords": [
+    "python",
+    "venv",
+    "virtualenv",
+    "diagnostics",
+    "health-check",
+    "windows",
+    "ml",
+    "pytorch",
+    "environment"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/mcp-tool-shop-org/venvkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcp-tool-shop-org/venvkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mcp-tool-shop-org/venvkit/issues"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "venvkit-map": "./dist/map_cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "format": "eslint . --fix",
+    "audit": "npm audit",
+    "map": "node dist/map_cli.js"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "eslint": "^9.0.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/dist/doctorLite.d.ts

@@ -1,75 +0,0 @@
-export type Severity = "info" | "warn" | "bad";
-export type HealthStatus = "good" | "warn" | "bad" | "unknown";
-export type FindingCode = "PYTHON_EXEC_MISSING" | "NOT_A_VENV" | "ARCH_MISMATCH" | "PIP_MISSING" | "PIP_POINTS_TO_OTHER_PYTHON" | "PYTHONPATH_INJECTED" | "USER_SITE_ENABLED" | "USER_SITE_LEAK" | "PIP_CHECK_FAIL" | "MULTI_VERSION_ON_PATH" | "RESOLVER_CONFLICT_HINT" | "OUTDATED_INSTALL_TOOLING" | "IMPORT_FAIL" | "DLL_LOAD_FAIL" | "ABI_MISMATCH" | "SSL_BROKEN" | "CERT_STORE_FAIL" | "SUBPROCESS_BROKEN" | "PYVENV_CFG_INVALID";
-export type Finding = {
-    code: FindingCode;
-    severity: Severity;
-    penalty: number;
-    what: string;
-    why: string;
-    fix: Array<{
-        title: string;
-        steps: string[];
-    }>;
-    evidence?: Record<string, unknown>;
-};
-export type RunResult = {
-    ok: boolean;
-    exitCode: number | null;
-    stdout: string;
-    stderr: string;
-    timedOut: boolean;
-};
-export type CmdRunner = (cmd: string, args: string[], opts: {
-    env?: NodeJS.ProcessEnv;
-    timeoutMs: number;
-}) => Promise<RunResult>;
-export type DoctorLiteOptions = {
-    /** Python executable path (venv python or base python). Required. */
-    pythonPath: string;
-    /** Modules to import-test (task required caps). */
-    requiredModules?: string[];
-    /** If true, also do a HTTPS probe to pypi.org (can fail in corp MITM; still useful). */
-    httpsProbe?: boolean;
-    /** If task requires 64-bit python, set true. If unknown, leave undefined. */
-    requireX64?: boolean;
-    /** Timeout per subprocess (ms). */
-    timeoutMs?: number;
-    /** If true, run heavier checks (pip check, multi-version scan). */
-    strict?: boolean;
-    /** Override environment variables passed to python. */
-    env?: Record<string, string | undefined>;
-};
-export type DoctorLiteReport = {
-    pythonPath: string;
-    ranAt: string;
-    status: HealthStatus;
-    score: number;
-    summary: string;
-    facts?: FactsResult;
-    findings: Finding[];
-};
-type FactsResult = {
-    version: string;
-    version_info: number[];
-    executable: string;
-    prefix: string;
-    base_prefix: string | null;
-    bits: number;
-    machine: string;
-    os: string;
-    py_path: string[];
-    enable_user_site: boolean | null;
-    user_site: string;
-};
-/**
- * Run a subprocess with timeout, capturing stdout/stderr.
- */
-export declare function runCmd(cmd: string, args: string[], opts: {
-    env?: NodeJS.ProcessEnv;
-    timeoutMs: number;
-}): Promise<RunResult>;
-export declare function doctorLite(opts: DoctorLiteOptions, runner?: CmdRunner): Promise<DoctorLiteReport>;
-export declare function envIdFromPythonPath(pythonPath: string): string;
-export {};
-//# sourceMappingURL=doctorLite.d.ts.map

package/dist/doctorLite.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"doctorLite.d.ts","sourceRoot":"","sources":["../doctorLite.ts"],"names":[],"mappings":"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"}