@mcptoolshop/venvkit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# venvkit
+
+[![CI](https://github.com/mcp-tool-shop/venvkit/actions/workflows/ci.yml/badge.svg)](https://github.com/mcp-tool-shop/venvkit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Python virtual environment diagnostic toolkit for Windows ML workflows.**
+
+Scans your system for Python environments, diagnoses health issues (SSL, DLLs, ABI mismatches, path leakage), tracks task execution history, detects flaky tasks, and renders an ecosystem map.
+
+## 30-Second Quickstart
+
+```bash
+git clone https://github.com/mcp-tool-shop/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
+```
+
+## Features
+
+- **doctorLite** - Fast health check for any Python interpreter
+  - SSL/TLS verification
+  - DLL load failures (common with PyTorch/CUDA)
+  - ABI mismatches (ARM vs x86)
+  - pip sanity checks
+  - User-site and PYTHONPATH leakage detection
+
+- **scanEnvPaths** - Discover all Python environments on your system
+  - Finds venvs, conda envs, pyenv versions, base interpreters
+  - Configurable depth and filtering
+
+- **mapRender** - Visualize your Python ecosystem
+  - Graph JSON output for programmatic use
+  - Mermaid diagrams for documentation
+  - Base interpreter grouping with blast radius analysis
+  - Task routing visualization
+
+- **runLog** - Track task execution history
+  - Append-only JSONL format
+  - Records which env ran what task
+  - Captures success/failure with error classification
+
+- **taskCluster** - Aggregate task runs by signature
+  - Flaky task detection (inconsistent pass/fail)
+  - Environment-dependent flake detection
+  - Failure hotspot identification
+  - Contagion analysis (shared root causes)
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## CLI Usage
+
+```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
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--root, -r` | Directory to scan (can specify multiple) |
+| `--out` | Output directory (default: `.venvkit`) |
+| `--maxDepth` | Max directory depth to scan (default: 5) |
+| `--strict` | Enable strict mode checks |
+| `--httpsProbe` | Test HTTPS connectivity |
+| `--minScore` | Filter envs below this health score |
+| `--concurrency` | Parallel checks (default: CPU count) |
+| `--runlog` | Path to task run log (JSONL) |
+| `--no-tasks` | Skip task visualization |
+
+### Outputs
+
+| File | Description |
+|------|-------------|
+| `venv-map.json` | Full graph data (nodes, edges, summary) |
+| `venv-map.mmd` | Mermaid diagram source |
+| `venv-map.html` | Interactive viewer |
+| `reports.json` | Raw doctorLite reports |
+| `insights.json` | Actionable recommendations |
+
+## Programmatic Usage
+
+```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,
+});
+```
+
+## Run Log Schema
+
+Track task executions by appending events to a JSONL file:
+
+```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,
+  },
+});
+```
+
+## Task Clustering
+
+When you have many task runs, venvkit clusters them by 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(', ')}`);
+  }
+}
+```
+
+## Graph Schema
+
+The `mapRender` output follows a stable JSON schema:
+
+```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[];
+};
+```
+
+### Node Types
+
+| Type | Description |
+|------|-------------|
+| `base` | Base Python interpreter (e.g., `C:\Python311`) |
+| `venv` | Virtual environment |
+| `task` | Task signature (clustered runs) |
+
+### Edge Types
+
+| Type | Description |
+|------|-------------|
+| `USES_BASE` | venv → base relationship |
+| `ROUTES_TASK_TO` | task → env routing |
+| `FAILED_RUN` | task → env failure (dashed in Mermaid) |
+
+## Finding Codes
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| `SSL_BROKEN` | bad | SSL module fails to import |
+| `CERT_STORE_FAIL` | warn | HTTPS certificate verification fails |
+| `DLL_LOAD_FAIL` | bad | Native extension DLL loading fails |
+| `ABI_MISMATCH` | bad | Binary incompatibility (ARM/x86) |
+| `PIP_MISSING` | warn | pip not available |
+| `PIP_CHECK_FAIL` | warn | Dependency conflicts detected |
+| `USER_SITE_LEAK` | warn | User site-packages enabled in venv |
+| `PYTHONPATH_INJECTED` | warn | PYTHONPATH environment variable set |
+| `ARCH_MISMATCH` | bad | 32-bit Python when 64-bit required |
+| `PYVENV_CFG_INVALID` | warn | Broken or missing pyvenv.cfg |
+
+## Development
+
+```bash
+npm install
+npm run typecheck  # Type check
+npm run test       # Run tests
+npm run build      # Build to dist/
+```
+
+## License
+
+MIT

package/dist/doctorLite.d.ts

@@ -0,0 +1,75 @@
+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

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