@jerryan/pi-pyvenv 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JerryAZR
+
+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,64 @@
+# @jerryan/pi-pyvenv
+
+A [pi](https://github.com/earendil-works/pi-mono) extension that transparently ensures every `python`, `python3`, `pip`, and `pip3` invocation resolves to a virtual environment — never to the system Python.
+
+## Why
+
+Coding agents love running `pip install` against the system Python. This breaks or pollutes the user's system packages. `pi-pyvenv` makes this impossible by automatically activating a venv at the **process level** before the agent starts working.
+
+## What it does
+
+On every session start, `pi-pyvenv` picks a venv in this order:
+
+1. **Respect existing activation** — If `VIRTUAL_ENV` is already set (e.g. the user activated a venv in their shell before launching pi), do nothing.
+2. **Discover project venv** — If `.venv/` or `venv/` exists in the current working directory, activate that.
+3. **Shared fallback venv** — Otherwise, activate (or create) a shared user-level venv at `~/.pi/agent/pyvenv/`.
+
+The activation mutates `process.env.PATH` and `process.env.VIRTUAL_ENV` **once** at the Node.js process level. All subsequently spawned child processes inherit it automatically — no command rewriting, no `spawnHook`, no tool interception.
+
+## Installation
+
+```bash
+pi install @jerryan/pi-pyvenv
+```
+
+Or install locally:
+
+```bash
+cd ~/.pi/agent/extensions/
+git clone https://github.com/JerryAZR/pi-pyvenv.git
+cd pi-pyvenv
+npm install
+```
+
+Then restart pi or run `/reload`.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/pyvenv status` | Show the currently active venv |
+| `/pyvenv recreate` | Delete and rebuild the shared fallback venv |
+
+## What it is NOT
+
+This extension is **not** a project-level venv manager. It does not:
+
+- Create `.venv/` in your project directory
+- Switch venvs when you change directories
+- Handle `requirements.txt`, `pyproject.toml`, or lockfiles
+- Wrap Conda, Poetry, `uv`, or `pipenv`
+
+If you are working on a real Python project, create your own `.venv/` and `pi-pyvenv` will discover and use it automatically.
+
+## Design decisions
+
+- **No system prompt injection** — The agent does not need to know a venv is active. This is pure infrastructure.
+- **No command rewriting** — We trust `PATH` precedence. Absolute paths like `/usr/bin/pip` are rare and not worth the fragility of interception.
+- **No `spawnHook`** — Process-level env mutation covers `bash` tool, `!` commands, `pi.exec()`, and other extensions.
+- **MS Store shim detection** — On Windows, broken `python3` shims (exit code 49) are automatically skipped during Python discovery.
+- **Dead venv recovery** — If the shared venv's underlying Python was removed or upgraded, it is detected and recreated on the next session start.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@jerryan/pi-pyvenv",
+  "version": "0.1.0",
+  "description": "Automatically activate a Python virtual environment for pi coding agents",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JerryAZR/pi-pyvenv.git"
+  },
+  "homepage": "https://github.com/JerryAZR/pi-pyvenv#readme",
+  "bugs": {
+    "url": "https://github.com/JerryAZR/pi-pyvenv/issues"
+  },
+  "author": "JerryAZR",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "python",
+    "venv",
+    "virtualenv"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  findProjectVenv,
+  ensureSharedVenv,
+  activateVenv,
+  getActiveVenv,
+  getSharedVenvPath,
+} from "./venv.js";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    // 1. Respect existing VIRTUAL_ENV — user already activated something
+    if (process.env.VIRTUAL_ENV) {
+      return;
+    }
+
+    // 2. Discover project venv in cwd
+    const projectVenv = findProjectVenv(ctx.cwd);
+    if (projectVenv) {
+      activateVenv(projectVenv);
+      return;
+    }
+
+    // 3. Fall back to shared venv
+    const sharedVenv = await ensureSharedVenv();
+    if (sharedVenv) {
+      activateVenv(sharedVenv);
+    }
+  });
+
+  pi.registerCommand("pyvenv", {
+    description: "Show or manage the Python virtual environment",
+    handler: async (args, ctx) => {
+      const arg = args.trim();
+
+      if (arg === "recreate") {
+        const sharedPath = getSharedVenvPath();
+        if (!getActiveVenv()?.startsWith(sharedPath)) {
+          ctx.ui.notify("Only the shared fallback venv can be recreated.", "warning");
+          return;
+        }
+
+        const ok = await ctx.ui.confirm(
+          "Recreate shared venv?",
+          `Delete ${sharedPath} and rebuild it?`
+        );
+        if (!ok) return;
+
+        const { rm } = await import("node:fs/promises");
+        try {
+          await rm(sharedPath, { recursive: true, force: true });
+          ctx.ui.notify("Shared venv deleted. Rebuilding...", "info");
+        } catch (e: any) {
+          ctx.ui.notify(`Failed to delete venv: ${e.message}`, "error");
+          return;
+        }
+
+        const rebuilt = await ensureSharedVenv();
+        if (rebuilt) {
+          activateVenv(rebuilt);
+          ctx.ui.notify(`Shared venv rebuilt: ${rebuilt}`, "info");
+        } else {
+          ctx.ui.notify("Failed to rebuild shared venv.", "error");
+        }
+        return;
+      }
+
+      if (arg === "" || arg === "status") {
+        const active = getActiveVenv();
+        if (!active) {
+          ctx.ui.notify("No Python venv is active.", "warning");
+        } else {
+          ctx.ui.notify(`Python venv: ${active}`, "info");
+        }
+        return;
+      }
+
+      ctx.ui.notify(
+        `Unknown pyvenv command: "${arg}". Try "status" or "recreate".`,
+        "warning"
+      );
+    },
+  });
+}

package/src/venv.ts

@@ -0,0 +1,146 @@
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { execFile } from "node:child_process";
+
+const VENV_NAMES = [".venv", "venv"];
+const SHARED_VENV_NAME = "pyvenv";
+
+export function findProjectVenv(cwd: string): string | null {
+  for (const name of VENV_NAMES) {
+    const p = join(cwd, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+export function getSharedVenvPath(): string {
+  return join(homedir(), ".pi", "agent", SHARED_VENV_NAME);
+}
+
+function getVenvBinDir(venvPath: string): string {
+  return process.platform === "win32"
+    ? join(venvPath, "Scripts")
+    : join(venvPath, "bin");
+}
+
+function getVenvPython(venvPath: string): string {
+  const binDir = getVenvBinDir(venvPath);
+  return process.platform === "win32"
+    ? join(binDir, "python.exe")
+    : join(binDir, "python");
+}
+
+function execFileAsync(
+  command: string,
+  args: string[],
+  timeoutMs = 10000
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    try {
+      execFile(command, args, { timeout: timeoutMs }, (error, stdout, stderr) => {
+        if (error) {
+          resolve({
+            code: (error as any).code as number ?? 1,
+            stdout: stdout.trim(),
+            stderr: stderr.trim(),
+          });
+        } else {
+          resolve({ code: 0, stdout: stdout.trim(), stderr: stderr.trim() });
+        }
+      });
+    } catch {
+      resolve({ code: 1, stdout: "", stderr: "" });
+    }
+  });
+}
+
+export async function findValidPython(): Promise<string | null> {
+  const candidates = ["python3", "python", "py"];
+  for (const cmd of candidates) {
+    const result = await execFileAsync(cmd, ["-c", "import sys; print(sys.executable)"], 5000);
+    if (result.code === 0 && result.stdout.length > 0) {
+      return cmd;
+    }
+  }
+  return null;
+}
+
+export async function smokeTestVenv(venvPath: string): Promise<boolean> {
+  const python = getVenvPython(venvPath);
+  if (!existsSync(python)) return false;
+  const result = await execFileAsync(python, ["-c", "import sys; print(sys.executable)"], 5000);
+  return result.code === 0 && result.stdout.length > 0;
+}
+
+export async function createVenv(pythonCmd: string, venvPath: string): Promise<void> {
+  const result = await execFileAsync(pythonCmd, ["-m", "venv", venvPath], 60000);
+  if (result.code !== 0) {
+    throw new Error(
+      `Failed to create venv at ${venvPath}: ${result.stderr || result.stdout}`
+    );
+  }
+}
+
+let originalPath: string | undefined;
+
+export function activateVenv(venvPath: string): void {
+  // If a different venv is already active, do nothing
+  if (process.env.VIRTUAL_ENV && process.env.VIRTUAL_ENV !== venvPath) {
+    return;
+  }
+
+  const binDir = getVenvBinDir(venvPath);
+  const pathKey =
+    Object.keys(process.env).find((k) => k.toLowerCase() === "path") ?? "PATH";
+  const existingPath = process.env[pathKey] ?? "";
+
+  // Idempotency: already active
+  if (existingPath.startsWith(`${binDir}${delimiter}`)) {
+    return;
+  }
+
+  // Store original path on first activation
+  if (originalPath === undefined) {
+    originalPath = existingPath;
+  }
+
+  const newPath = existingPath
+    ? `${binDir}${delimiter}${existingPath}`
+    : binDir;
+
+  process.env[pathKey] = newPath;
+  process.env.VIRTUAL_ENV = venvPath;
+}
+
+export function getActiveVenv(): string | undefined {
+  return process.env.VIRTUAL_ENV;
+}
+
+export function deactivateVenv(): void {
+  if (originalPath !== undefined) {
+    const pathKey =
+      Object.keys(process.env).find((k) => k.toLowerCase() === "path") ?? "PATH";
+    process.env[pathKey] = originalPath;
+  }
+  delete process.env.VIRTUAL_ENV;
+}
+
+export async function ensureSharedVenv(): Promise<string | null> {
+  const sharedPath = getSharedVenvPath();
+
+  if (existsSync(sharedPath)) {
+    if (await smokeTestVenv(sharedPath)) {
+      return sharedPath;
+    }
+    // Dead venv — remove and recreate
+    await rm(sharedPath, { recursive: true, force: true });
+  }
+
+  const python = await findValidPython();
+  if (!python) return null;
+
+  await createVenv(python, sharedPath);
+  return sharedPath;
+}