@mcptoolshop/venvkit 0.2.0

package/dist/scanEnvPaths.js

@@ -0,0 +1,174 @@
+// scanEnvPaths.ts
+//
+// Discover Python environments on disk (venv + base interpreters) in a fast, pragmatic way.
+// Outputs python executable paths you can feed into doctorLite + mapRender.
+//
+// Strategy (safe + useful defaults):
+// - Project-local: .venv, venv, env, .python, .pyenv (common patterns)
+// - Workspace roots you pass in
+// - Global cache: ~/.venvkit/envs (if you use it)
+// - Also looks for any directory containing pyvenv.cfg and a python executable.
+//
+// Notes:
+// - This is discovery only. You still call doctorLite for health + facts.
+// - On Windows we look for Scripts/python.exe; on POSIX bin/python.
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+function isWin() {
+    return os.platform() === "win32";
+}
+function norm(p) {
+    return isWin() ? p.toLowerCase() : p;
+}
+async function exists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isDir(p) {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function venvPythonCandidates(venvRoot) {
+    return isWin()
+        ? [path.join(venvRoot, "Scripts", "python.exe"), path.join(venvRoot, "Scripts", "python")]
+        : [path.join(venvRoot, "bin", "python"), path.join(venvRoot, "bin", "python3")];
+}
+async function detectVenvAt(dir) {
+    const cfg = path.join(dir, "pyvenv.cfg");
+    if (!(await exists(cfg)))
+        return null;
+    for (const py of venvPythonCandidates(dir)) {
+        if (await exists(py))
+            return py;
+    }
+    return null;
+}
+async function listDirSafe(dir) {
+    try {
+        return await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+}
+async function walkForVenvs(root, maxDepth, includeHidden, out) {
+    const stack = [{ dir: root, depth: 0 }];
+    while (stack.length) {
+        const cur = stack.pop();
+        if (cur.depth > maxDepth)
+            continue;
+        // quick venv detection at this directory
+        const venvPy = await detectVenvAt(cur.dir);
+        if (venvPy) {
+            out.push(venvPy);
+            // Do not descend into this venv further (keeps scan fast)
+            continue;
+        }
+        const children = await listDirSafe(cur.dir);
+        for (const name of children) {
+            if (!includeHidden && name.startsWith("."))
+                continue;
+            const full = path.join(cur.dir, name);
+            if (!(await isDir(full)))
+                continue;
+            // Skip common heavy directories
+            if (name === "node_modules" || name === "dist" || name === "build" || name === ".git")
+                continue;
+            stack.push({ dir: full, depth: cur.depth + 1 });
+        }
+    }
+}
+async function discoverProjectLocalRoots(root) {
+    const candidates = [".venv", "venv", "env", ".python", ".pyenv"];
+    const out = [];
+    for (const c of candidates) {
+        const p = path.join(root, c);
+        if (await isDir(p))
+            out.push(p);
+    }
+    return out;
+}
+async function discoverBasePythons() {
+    // Best-effort:
+    // - On Windows: common install locations
+    // - On POSIX: common binaries
+    const out = [];
+    if (isWin()) {
+        const possible = [
+            "C:\\Python312\\python.exe",
+            "C:\\Python311\\python.exe",
+            "C:\\Python310\\python.exe",
+            "C:\\Program Files\\Python312\\python.exe",
+            "C:\\Program Files\\Python311\\python.exe",
+            "C:\\Program Files\\Python310\\python.exe",
+            path.join(os.homedir(), "AppData", "Local", "Programs", "Python", "Python312", "python.exe"),
+            path.join(os.homedir(), "AppData", "Local", "Programs", "Python", "Python311", "python.exe"),
+            path.join(os.homedir(), "AppData", "Local", "Programs", "Python", "Python310", "python.exe"),
+        ];
+        for (const p of possible)
+            if (await exists(p))
+                out.push(p);
+    }
+    else {
+        const possible = ["/usr/bin/python3", "/usr/local/bin/python3", "/opt/homebrew/bin/python3", "/usr/bin/python"];
+        for (const p of possible)
+            if (await exists(p))
+                out.push(p);
+    }
+    return out;
+}
+export async function scanEnvPaths(options) {
+    const maxDepth = options.maxDepth ?? 5;
+    const includeHidden = options.includeHidden ?? false;
+    const includeUserHomeCache = options.includeUserHomeCache ?? true;
+    const dedupe = options.dedupe ?? true;
+    const roots = [...options.roots];
+    if (includeUserHomeCache) {
+        roots.push(path.join(os.homedir(), ".venvkit", "envs"));
+        roots.push(path.join(os.homedir(), ".virtualenvs"));
+    }
+    const pythonPaths = [];
+    // Fast pass: project-local patterns in each root
+    for (const r of options.roots) {
+        const locals = await discoverProjectLocalRoots(r);
+        for (const venvRoot of locals) {
+            const py = await detectVenvAt(venvRoot);
+            if (py)
+                pythonPaths.push(py);
+        }
+    }
+    // Walk: find pyvenv.cfg
+    for (const root of roots) {
+        if (!(await isDir(root)))
+            continue;
+        await walkForVenvs(root, maxDepth, includeHidden, pythonPaths);
+    }
+    // Optional: base interpreter candidates
+    const bases = await discoverBasePythons();
+    for (const b of bases)
+        pythonPaths.push(b);
+    const final = dedupe ? [...new Map(pythonPaths.map((p) => [norm(p), p])).values()] : pythonPaths;
+    // crude counts
+    const foundBases = bases.length;
+    const foundVenvs = Math.max(0, final.length - foundBases);
+    return {
+        pythonPaths: final,
+        meta: {
+            scannedRoots: roots,
+            maxDepth,
+            foundVenvs,
+            foundBases,
+        },
+    };
+}
+//# sourceMappingURL=scanEnvPaths.js.map

package/dist/scanEnvPaths.js.map

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

package/dist/scanEnvPaths.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scanEnvPaths.test.d.ts.map

package/dist/scanEnvPaths.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanEnvPaths.test.d.ts","sourceRoot":"","sources":["../scanEnvPaths.test.ts"],"names":[],"mappings":""}

package/dist/scanEnvPaths.test.js

@@ -0,0 +1,250 @@
+// scanEnvPaths.test.ts
+// Unit tests for environment path discovery
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { scanEnvPaths } from "./scanEnvPaths.js";
+describe("scanEnvPaths", () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "venvkit-scan-test-"));
+    });
+    afterEach(async () => {
+        await fs.rm(tempDir, { recursive: true, force: true });
+    });
+    // Helper to create a mock venv structure
+    async function createMockVenv(venvPath) {
+        await fs.mkdir(venvPath, { recursive: true });
+        await fs.writeFile(path.join(venvPath, "pyvenv.cfg"), "home = C:\\Python311\nversion = 3.11.5\n");
+        const binDir = os.platform() === "win32" ? "Scripts" : "bin";
+        const pyExe = os.platform() === "win32" ? "python.exe" : "python";
+        await fs.mkdir(path.join(venvPath, binDir), { recursive: true });
+        await fs.writeFile(path.join(venvPath, binDir, pyExe), "fake python");
+        return path.join(venvPath, binDir, pyExe);
+    }
+    describe("finding Python venvs", () => {
+        it("finds venv with pyvenv.cfg", async () => {
+            const venvPath = path.join(tempDir, "project", ".venv");
+            await createMockVenv(venvPath);
+            const result = await scanEnvPaths({
+                roots: [path.join(tempDir, "project")],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            expect(result.pythonPaths.length).toBeGreaterThanOrEqual(1);
+            expect(result.meta.foundVenvs).toBeGreaterThanOrEqual(1);
+        });
+        it("finds multiple venvs in project tree", async () => {
+            await createMockVenv(path.join(tempDir, "project1", ".venv"));
+            await createMockVenv(path.join(tempDir, "project2", "venv"));
+            await createMockVenv(path.join(tempDir, "project3", "env"));
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            expect(result.meta.foundVenvs).toBeGreaterThanOrEqual(3);
+        });
+        it("finds venv in standard project locations", async () => {
+            // Test standard venv folder names: .venv, venv, env
+            const projectRoot = path.join(tempDir, "myproject");
+            await fs.mkdir(projectRoot, { recursive: true });
+            const venvPath = path.join(projectRoot, ".venv");
+            await createMockVenv(venvPath);
+            const result = await scanEnvPaths({
+                roots: [projectRoot],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            expect(result.pythonPaths.some(p => p.includes(".venv"))).toBe(true);
+        });
+    });
+    describe("scan options", () => {
+        it("respects maxDepth limit", async () => {
+            // Create venv at depth 2
+            await createMockVenv(path.join(tempDir, "level1", ".venv"));
+            // Create venv at depth 4 (should not be found with maxDepth=2)
+            await createMockVenv(path.join(tempDir, "level1", "level2", "level3", ".venv"));
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 2,
+                includeUserHomeCache: false,
+            });
+            // Should find shallow venv but not deeply nested one
+            const foundPaths = result.pythonPaths.filter(p => p.includes(tempDir));
+            expect(foundPaths.length).toBe(1);
+        });
+        it("ignores hidden directories by default", async () => {
+            await createMockVenv(path.join(tempDir, ".hidden", "venv"));
+            await createMockVenv(path.join(tempDir, "visible", "venv"));
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 3,
+                includeHidden: false,
+                includeUserHomeCache: false,
+            });
+            const foundPaths = result.pythonPaths.filter(p => p.includes(tempDir));
+            expect(foundPaths.some(p => p.includes(".hidden"))).toBe(false);
+            expect(foundPaths.some(p => p.includes("visible"))).toBe(true);
+        });
+        it("includes hidden directories when flag is set", async () => {
+            await createMockVenv(path.join(tempDir, ".hidden", "venv"));
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 3,
+                includeHidden: true,
+                includeUserHomeCache: false,
+            });
+            const foundPaths = result.pythonPaths.filter(p => p.includes(tempDir));
+            expect(foundPaths.some(p => p.includes(".hidden"))).toBe(true);
+        });
+        it("deduplicates paths by default", async () => {
+            const venvPath = path.join(tempDir, "project", ".venv");
+            await createMockVenv(venvPath);
+            // Scan same root twice
+            const result = await scanEnvPaths({
+                roots: [path.join(tempDir, "project"), path.join(tempDir, "project")],
+                maxDepth: 3,
+                dedupe: true,
+                includeUserHomeCache: false,
+            });
+            const foundPaths = result.pythonPaths.filter(p => p.includes(tempDir));
+            // Should only have one entry despite scanning same location twice
+            expect(new Set(foundPaths).size).toBe(foundPaths.length);
+        });
+    });
+    describe("handling edge cases", () => {
+        it("handles empty directory", async () => {
+            const emptyDir = path.join(tempDir, "empty");
+            await fs.mkdir(emptyDir, { recursive: true });
+            const result = await scanEnvPaths({
+                roots: [emptyDir],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            const foundInTemp = result.pythonPaths.filter(p => p.includes(tempDir));
+            expect(foundInTemp.length).toBe(0);
+        });
+        it("handles permission errors gracefully", async () => {
+            // This test might behave differently on Windows vs POSIX
+            // The key is that it doesn't throw
+            const result = await scanEnvPaths({
+                roots: ["/nonexistent/path/that/should/not/exist"],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            expect(result).toBeDefined();
+            expect(result.pythonPaths).toBeDefined();
+        });
+        it("skips node_modules directory", async () => {
+            // Create a venv inside node_modules (should be skipped)
+            await createMockVenv(path.join(tempDir, "node_modules", "some-pkg", ".venv"));
+            await createMockVenv(path.join(tempDir, "src", ".venv"));
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 5,
+                includeUserHomeCache: false,
+            });
+            const foundPaths = result.pythonPaths.filter(p => p.includes(tempDir));
+            expect(foundPaths.some(p => p.includes("node_modules"))).toBe(false);
+            expect(foundPaths.some(p => p.includes("src"))).toBe(true);
+        });
+        it("skips .git directory", async () => {
+            await createMockVenv(path.join(tempDir, ".git", "hooks", ".venv"));
+            await createMockVenv(path.join(tempDir, "app", ".venv"));
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 5,
+                includeHidden: true, // Even with hidden enabled, .git should be skipped
+                includeUserHomeCache: false,
+            });
+            const foundPaths = result.pythonPaths.filter(p => p.includes(tempDir));
+            expect(foundPaths.some(p => p.includes(".git"))).toBe(false);
+        });
+        it("handles venv without python executable", async () => {
+            // Create pyvenv.cfg but no python executable
+            const venvPath = path.join(tempDir, "broken-venv");
+            await fs.mkdir(venvPath, { recursive: true });
+            await fs.writeFile(path.join(venvPath, "pyvenv.cfg"), "home = C:\\Python311\n");
+            // Deliberately don't create Scripts/python.exe
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            // Should not crash, and should not find the broken venv
+            const foundBroken = result.pythonPaths.filter(p => p.includes("broken-venv"));
+            expect(foundBroken.length).toBe(0);
+        });
+    });
+    describe("meta information", () => {
+        it("reports scanned roots in meta", async () => {
+            const root1 = path.join(tempDir, "root1");
+            const root2 = path.join(tempDir, "root2");
+            await fs.mkdir(root1, { recursive: true });
+            await fs.mkdir(root2, { recursive: true });
+            const result = await scanEnvPaths({
+                roots: [root1, root2],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            expect(result.meta.scannedRoots).toContain(root1);
+            expect(result.meta.scannedRoots).toContain(root2);
+            expect(result.meta.maxDepth).toBe(3);
+        });
+        it("counts venvs and bases separately", async () => {
+            await createMockVenv(path.join(tempDir, "venv1"));
+            await createMockVenv(path.join(tempDir, "venv2"));
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            expect(result.meta.foundVenvs).toBeGreaterThanOrEqual(2);
+            expect(typeof result.meta.foundBases).toBe("number");
+        });
+    });
+    describe("nested environment handling", () => {
+        it("detects venv and does not descend further", async () => {
+            // Create a venv with a nested venv inside (unusual but possible)
+            const outerVenv = path.join(tempDir, "outer-venv");
+            await createMockVenv(outerVenv);
+            // Create another venv inside (should not be found because we stop at outer venv)
+            const innerVenv = path.join(outerVenv, "nested", "inner-venv");
+            await createMockVenv(innerVenv);
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 10,
+                includeUserHomeCache: false,
+            });
+            const foundPaths = result.pythonPaths.filter(p => p.includes(tempDir));
+            const foundOuter = foundPaths.filter(p => p.includes("outer-venv") && !p.includes("inner-venv"));
+            const foundInner = foundPaths.filter(p => p.includes("inner-venv"));
+            // Should find outer venv
+            expect(foundOuter.length).toBe(1);
+            // Should NOT find inner venv (scan stops at venv boundary)
+            expect(foundInner.length).toBe(0);
+        });
+    });
+    describe("large directory trees", () => {
+        it("handles directory with many subdirectories", async () => {
+            // Create many directories to test performance doesn't degrade badly
+            for (let i = 0; i < 20; i++) {
+                await fs.mkdir(path.join(tempDir, `dir${i}`), { recursive: true });
+            }
+            await createMockVenv(path.join(tempDir, "dir10", ".venv"));
+            const start = Date.now();
+            const result = await scanEnvPaths({
+                roots: [tempDir],
+                maxDepth: 3,
+                includeUserHomeCache: false,
+            });
+            const elapsed = Date.now() - start;
+            expect(result.meta.foundVenvs).toBeGreaterThanOrEqual(1);
+            // Should complete in reasonable time (less than 5 seconds)
+            expect(elapsed).toBeLessThan(5000);
+        });
+    });
+});
+//# sourceMappingURL=scanEnvPaths.test.js.map

package/dist/scanEnvPaths.test.js.map

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

package/dist/taskCluster.d.ts

@@ -0,0 +1,62 @@
+import type { RunLogEventV1 } from "./runLog.js";
+export type TaskSignature = {
+    sigId: string;
+    name: string;
+    command: string;
+    requirementsKey: string;
+};
+export type TaskCluster = {
+    sig: TaskSignature;
+    runs: number;
+    ok: number;
+    fail: number;
+    successRate: number;
+    lastAt: string;
+    dominantFailure?: string;
+    failureCounts: Record<string, number>;
+    envCounts: Record<string, number>;
+    envFailCounts: Record<string, number>;
+    envOkCounts: Record<string, number>;
+};
+/**
+ * Extract a stable signature from a run event.
+ * Runs with the same signature are clustered together.
+ */
+export declare function signatureForRun(run: RunLogEventV1): TaskSignature;
+/**
+ * Cluster runs by task signature.
+ * Returns clusters sorted by run count (descending).
+ */
+export declare function clusterRuns(runs: RunLogEventV1[]): TaskCluster[];
+/**
+ * Determine if a task cluster is flaky.
+ * Flaky = both succeeds and fails, with success rate not extreme.
+ */
+export declare function isFlaky(cluster: TaskCluster): boolean;
+/**
+ * Determine if a task cluster is env-dependent flaky.
+ * This means it succeeds on some envs and fails on others.
+ */
+export declare function isEnvDependentFlaky(cluster: TaskCluster): boolean;
+/**
+ * Get the envs where this task fails most.
+ */
+export declare function getFailingEnvs(cluster: TaskCluster, limit?: number): Array<{
+    pythonPath: string;
+    failCount: number;
+    totalCount: number;
+    failRate: number;
+}>;
+/**
+ * Get summary statistics for a set of clusters.
+ */
+export declare function summarizeClusters(clusters: TaskCluster[]): {
+    totalTasks: number;
+    totalRuns: number;
+    totalOk: number;
+    totalFail: number;
+    overallSuccessRate: number;
+    flakyCount: number;
+    envDependentFlakyCount: number;
+};
+//# sourceMappingURL=taskCluster.d.ts.map

package/dist/taskCluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taskCluster.d.ts","sourceRoot":"","sources":["../taskCluster.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,aAAa,CAAC;IAEnB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IAEf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEtC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CAAC;AA6BF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,CAMjE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,WAAW,EAAE,CAuDhE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAKrD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAejE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EACpB,KAAK,SAAI,GACR,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAUxF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAwBA"}