pi-lean-dimension 0.1.0 → 0.2.1

package/node_modules/pi-lean-portal/__tests__/helpers/probe-user-backend.ts

@@ -0,0 +1,198 @@
+/**
+ * `probeUserBackend` — availability probe for a user-managed stealth
+ * Python backend.
+ *
+ * Lets a user-managed stealth backend be exercised through the 130-task
+ * MiniWoB++ harness (and the shipped parity-test template) without
+ * forking the repo. The probe is engine-agnostic — it checks only that
+ * the backend's `bridge.py` exists on disk and the backend's venv
+ * python interpreter runs. No engine-specific binary probing; a
+ * template that needs a binary probe (e.g. Camoufox's
+ * `python -m camoufox fetch` check) can layer that on top.
+ *
+ * Resolution mirrors the user-backend discovery in `detectPluginType` in
+ * `pi-lean-portal/core/plugin-config.ts` so this probe and the runtime
+ * loader agree on where a backend lives:
+ * - `bridgePath` defaults to `${userBackendsDir()}/${name}/bridge.py`;
+ *   an absolute `opts.bridgePath` short-circuits (the power-user escape
+ *   hatch, mirroring the absolute-`dir` short-circuit).
+ * - `venvPython` defaults to
+ *   `${userBackendsDir()}/${name}/.venv/bin/python3`; overridable via
+ *   `PI_USER_BACKEND_<UPPERNAME>_PYTHON` so a user can point at a
+ *   non-`user-backends` venv without editing the test/template.
+ *
+ * Lives in `__tests__/helpers/` because it is only ever called from
+ * tests (and the user-backends parity template). The env overrides
+ * (`PI_USER_BACKENDS_DIR` + per-name `PI_USER_BACKEND_<NAME>_PYTHON`)
+ * are preserved from the original vendored helper.
+ *
+ * @module
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+// ─── User-backends root ───────────────────────────────────────────
+
+/**
+ * Resolve the user-backends root directory.
+ *
+ * Honors `PI_USER_BACKENDS_DIR` (an absolute path override) when set
+ * and non-empty; otherwise defaults to
+ * `~/.pi/agent/pi-lean-portal/user-backends/`.
+ *
+ * Vendored locally — see the module doc for the rationale. Sprint 2's
+ * generic runner reuses this same helper for consistency.
+ */
+export function userBackendsDir(): string {
+	const env = process.env.PI_USER_BACKENDS_DIR;
+	if (env !== undefined && env.trim() !== "") return env;
+	return join(homedir(), ".pi", "agent", "pi-lean-portal", "user-backends");
+}
+
+// ─── Backend discovery ──────────────────────────────────────────
+
+/**
+ * Discover user-managed Python backends under a user-backends root.
+ *
+ * Returns the list of `<name>` such that `${root}/<name>/bridge.py`
+ * exists and `${root}/<name>` is a directory whose basename ends with
+ * `-py` (the conventional suffix for Python bridge backends, mirroring
+ * the shipped `chromium-py` / `firefox-py` naming). Sorted for
+ * deterministic registration order. Empty when the root is missing or
+ * contains no matching directory (the normal bare-CI state — the
+ * caller treats this as a no-op).
+ *
+ * Used by the generic `bench/miniwob/suites/` runners that exercise
+ * whatever stealth backend the user has installed, without naming any.
+ */
+export function discoverUserBackends(root: string): string[] {
+	if (!existsSync(root) || !statSync(root).isDirectory()) return [];
+	let entries: string[];
+	try {
+		entries = readdirSync(root);
+	} catch {
+		return [];
+	}
+	const found: string[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith("-py")) continue;
+		const dir = join(root, entry);
+		try {
+			if (!statSync(dir).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		if (existsSync(join(dir, "bridge.py"))) found.push(entry);
+	}
+	return found.sort();
+}
+
+// ─── Types ────────────────────────────────────────────────────────
+
+/** Options for {@link probeUserBackend}. */
+export interface ProbeUserBackendOptions {
+	/**
+	 * Absolute path to the backend's `bridge.py`, overriding the default
+	 * `${userBackendsDir()}/${name}/bridge.py` resolution. Mirrors the
+	 * absolute-`dir` short-circuit in `detectPluginType`: when this is an
+	 * absolute path it wins; any other value is ignored in favor of the
+	 * default resolution.
+	 */
+	bridgePath?: string;
+}
+
+/** Result of {@link probeUserBackend}. */
+export interface ProbeUserBackendResult {
+	/**
+	 * `true` iff the bridge file exists AND the venv python interpreter
+	 * runs (`python3 --version` exits 0).
+	 */
+	available: boolean;
+	/** Resolved path to the backend's `bridge.py`. */
+	bridgePath: string;
+	/** Resolved path to the backend's venv python interpreter. */
+	venvPython: string;
+	/**
+	 * When `available` is `false`, explains the first missing piece so a
+	 * skip message is useful. `undefined` when `available` is `true`.
+	 */
+	reason?: string;
+}
+
+// ─── Public API ───────────────────────────────────────────────────
+
+/**
+ * Probe a user-managed Python backend for availability.
+ *
+ * Checks, in order:
+ *   1. The `bridge.py` exists at the resolved `bridgePath`.
+ *   2. The venv python interpreter runs (`--version` exits 0).
+ *
+ * Returns a plain object (synchronous — one `spawnSync` for the venv
+ * check, mirroring the existing `probePythonBackend` in
+ * `suites/miniwob-suite-helper.ts`). Runs once at suite-load, so
+ * blocking briefly is acceptable.
+ *
+ * @param name  Backend directory name under `user-backends/`
+ *               (e.g. `"camoufox-py"`).
+ * @param opts  Optional overrides; see {@link ProbeUserBackendOptions}.
+ *
+ * @note The `PI_USER_BACKEND_<UPPERNAME>_PYTHON` override uppercases
+ *       `name` verbatim. For names containing `-` (e.g. `camoufox-py`)
+ *       the env var contains a hyphen (`PI_USER_BACKEND_CAMOUFOX-PY_PYTHON`);
+ *       shells that forbid hyphens in `export`ed names must set it via
+ *       `settings.json` `env` or another Node-respected channel.
+ */
+export function probeUserBackend(
+	name: string,
+	opts?: ProbeUserBackendOptions,
+): ProbeUserBackendResult {
+	const root = userBackendsDir();
+
+	const bridgePath =
+		opts?.bridgePath !== undefined && isAbsolute(opts.bridgePath)
+			? opts.bridgePath
+			: join(root, name, "bridge.py");
+
+	const envPython = process.env[`PI_USER_BACKEND_${name.toUpperCase()}_PYTHON`];
+	const venvPython =
+		envPython !== undefined && envPython.trim() !== ""
+			? envPython
+			: join(root, name, ".venv", "bin", "python3");
+
+	if (!existsSync(bridgePath)) {
+		return {
+			available: false,
+			bridgePath,
+			venvPython,
+			reason: `bridge script not found: ${bridgePath}`,
+		};
+	}
+
+	const pythonRuns = (() => {
+		if (!existsSync(venvPython)) return false;
+		try {
+			const result = spawnSync(venvPython, ["--version"], {
+				stdio: "ignore",
+				timeout: 5_000,
+			});
+			return result.status === 0;
+		} catch {
+			return false;
+		}
+	})();
+
+	if (!pythonRuns) {
+		return {
+			available: false,
+			bridgePath,
+			venvPython,
+			reason: `venv python not runnable: ${venvPython}`,
+		};
+	}
+
+	return { available: true, bridgePath, venvPython };
+}

package/node_modules/pi-lean-portal/__tests__/helpers/test-server.ts

@@ -34,6 +34,20 @@ export const COOKIE_PERSISTENCE_HTML = `<!DOCTYPE html>
   </script>
 </body></html>`;
 
+/** Convenience: start a test server serving COOKIE_PERSISTENCE_HTML at "/". */
+export async function startCookiePersistenceServer(): Promise<TestServer> {
+	return startTestServer((req, res) => {
+		const url = new URL(req.url ?? "/", "http://localhost");
+		if (url.pathname === "/") {
+			res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+			res.end(COOKIE_PERSISTENCE_HTML);
+		} else {
+			res.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
+			res.end("404");
+		}
+	});
+}
+
 export async function startTestServer(
 	handler: (req: IncomingMessage, res: ServerResponse) => void,
 ): Promise<TestServer> {

package/node_modules/pi-lean-portal/__tests__/plugin-config-browser.test.ts

@@ -2,7 +2,7 @@
  * Tests for the browser configuration parsing in plugin-config.ts.
  *
  * Covers:
- * - loadBrowserConfig() defaults when no config exists
+ * - loadFullConfig().browser defaults when no config exists
  * - defaultProfile validation ("none", "session", or a named profile)
  * - defaultProfile validation
  * - maxStorageStateSize validation
@@ -11,11 +11,14 @@
  * - Merged global + project settings
  */
 
+import { join } from "node:path";
+
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import {
-	loadBrowserConfig,
+	loadFullConfig,
 	invalidateConfigCache,
-} from "../core/plugin-config";
+} from "../core/plugin-config.js";
+import { loadPluginConfigFromFile } from "./helpers/load-plugin-config-from-file.js";
 
 // ─── Mock fs to intercept settings.json reads ────────────────────
 
@@ -72,22 +75,22 @@ beforeEach(() => {
 
 // ─── Tests ───────────────────────────────────────────────────────
 
-describe("loadBrowserConfig()", () => {
+describe("loadFullConfig().browser", () => {
 	it("returns defaults when no settings.json exists", () => {
 		mockNoSettings();
-		const config = loadBrowserConfig();
+		const config = loadFullConfig().browser;
 		expect(config.defaultProfile).toBe("session");
 	});
 
 	it("returns defaults when browser section is missing", () => {
 		mockGlobalSettings({});
-		const config = loadBrowserConfig();
+		const config = loadFullConfig().browser;
 		expect(config.defaultProfile).toBe("session");
 	});
 
 	it("returns defaults when browser section has no config keys", () => {
 		mockGlobalSettings({ unrelated: true });
-		const config = loadBrowserConfig();
+		const config = loadFullConfig().browser;
 		expect(config.defaultProfile).toBe("session");
 	});
 
@@ -96,36 +99,36 @@ describe("loadBrowserConfig()", () => {
 	describe("defaultProfile", () => {
 		it("accepts a valid profile name", () => {
 			mockGlobalSettings({ defaultProfile: "work" });
-			expect(loadBrowserConfig().defaultProfile).toBe("work");
+			expect(loadFullConfig().browser.defaultProfile).toBe("work");
 		});
 
 		it("accepts hyphens and underscores", () => {
 			mockGlobalSettings({ defaultProfile: "my-work-profile" });
-			expect(loadBrowserConfig().defaultProfile).toBe("my-work-profile");
+			expect(loadFullConfig().browser.defaultProfile).toBe("my-work-profile");
 		});
 
 		it("rejects reserved names and falls back to default", () => {
 			mockGlobalSettings({ defaultProfile: "none" });
 			// "none" is reserved as a profile name but valid as a defaultProfile mode
-			const config = loadBrowserConfig();
+			const config = loadFullConfig().browser;
 			expect(config.defaultProfile).toBe("none");
 		});
 
 		it("rejects 'session' as a profile name for named profiles", () => {
 			mockGlobalSettings({ defaultProfile: "session" });
 			// "session" is reserved as a profile name but valid as a defaultProfile mode
-			const config = loadBrowserConfig();
+			const config = loadFullConfig().browser;
 			expect(config.defaultProfile).toBe("session");
 		});
 
 		it("rejects empty string", () => {
 			mockGlobalSettings({ defaultProfile: "" });
-			expect(loadBrowserConfig().defaultProfile).toBe("session");
+			expect(loadFullConfig().browser.defaultProfile).toBe("session");
 		});
 
 		it("rejects names with path traversal", () => {
 			mockGlobalSettings({ defaultProfile: "../../evil" });
-			expect(loadBrowserConfig().defaultProfile).toBe("session");
+			expect(loadFullConfig().browser.defaultProfile).toBe("session");
 		});
 	});
 
@@ -137,7 +140,7 @@ describe("loadBrowserConfig()", () => {
 				{ browser: { defaultProfile: "none" } },
 				{ browser: { defaultProfile: "work" } },
 			);
-			expect(loadBrowserConfig().defaultProfile).toBe("work");
+			expect(loadFullConfig().browser.defaultProfile).toBe("work");
 		});
 
 		it("project settings entirely replace global browser config (shallow merge)", () => {
@@ -153,8 +156,140 @@ describe("loadBrowserConfig()", () => {
 					},
 				},
 			);
-			const config = loadBrowserConfig();
+			const config = loadFullConfig().browser;
 			expect(config.defaultProfile).toBe("session");
 		});
 	});
 });
+
+// ─── Default plugin fallback (Phase 0b) ─────────────────────────
+
+describe("loadFullConfig().plugins default fallback", () => {
+	it("returns the four shipped backends when browser.plugins is absent", () => {
+		// No settings files → default fallback branch in parsePluginConfig fires.
+		mockNoSettings();
+		const { plugins, errors } = loadFullConfig().plugins;
+		expect(errors).toEqual([]);
+		const names = plugins.map((p) => p.name);
+		expect(names).toEqual(["chromium", "firefox", "chromium-py", "firefox-py"]);
+	});
+
+	it("does NOT include stealth backends (camoufox-py / stealth-py) in the default fallback", () => {
+		mockNoSettings();
+		const { plugins } = loadFullConfig().plugins;
+		const names = plugins.map((p) => p.name);
+		expect(names).not.toContain("camoufox-py");
+		expect(names).not.toContain("stealth-py");
+	});
+});
+
+// ─── loadPluginConfigFromFile ─────────────────────────────────────
+
+describe("loadPluginConfigFromFile()", () => {
+	/** Set up mock to behave like one valid bridge.py exists at a root dir. */
+	function mockValidBackendRoot(dirPath: string): void {
+		mockFs.existsSync.mockImplementation((p: string) => {
+			// The settings file itself exists
+			if (p === "/tmp/settings.json") return true;
+			if (p === "/tmp/empty.json") return true;
+			if (p === "/tmp/cached.json") return true;
+			// The backend directory exists
+			if (p === join(dirPath, "example-py")) return true;
+			if (p === join(dirPath, "my-backend")) return true;
+			// bridge.py exists (Python plugin)
+			if (p === join(dirPath, "example-py", "bridge.py")) return true;
+			if (p === join(dirPath, "my-backend", "bridge.py")) return true;
+			// index.ts does NOT exist → Python plugin, unambiguous
+			// Default stub dirs that detectPluginType checks as directories
+			if (p.startsWith("/tmp/")) return false;
+			// Everything else (e.g. global settings paths from fallback) is absent
+			return false;
+		});
+		mockFs.readFileSync.mockImplementation((p: string) => {
+			if (p === "/tmp/settings.json") {
+				return JSON.stringify({
+					browser: {
+						plugins: [
+							{
+								name: "example-py",
+								dir: "example-py",
+								enabled: true,
+								config: {
+									pythonPath: "/custom/python3",
+									capabilities: { engine: "firefox" },
+									transportTimeoutMs: 30_000,
+									launch: { headless: true },
+								},
+							},
+						],
+					},
+				});
+			}
+			if (p === "/tmp/empty.json") return "{}";
+			return "{}";
+		});
+	}
+
+	it("parses a test-local settings file with browser.plugins", () => {
+		// Point at a root with a valid bridge.py so detectPluginType passes.
+		mockValidBackendRoot("/tmp/backends");
+
+		const { plugins, errors } = loadPluginConfigFromFile("/tmp/settings.json", [
+			"/tmp/backends",
+		]);
+		expect(errors).toEqual([]);
+		expect(plugins).toHaveLength(1);
+		const p = plugins[0]!;
+		expect(p.name).toBe("example-py");
+		expect(p.enabled).toBe(true);
+		expect(p.config.pythonPath).toBe("/custom/python3");
+		expect(p.config.launch).toEqual({ headless: true });
+	});
+
+	it("falls back to default plugins when settings file has no browser key", () => {
+		// No browser key → falls through to parsePluginConfig(undefined) → defaults
+		mockFs.existsSync.mockReturnValue(true);
+		mockFs.readFileSync.mockImplementation((p: string) => {
+			if (p === "/tmp/no-browser.json")
+				return JSON.stringify({ unrelated: true });
+			return "{}";
+		});
+
+		const { plugins, errors } = loadPluginConfigFromFile(
+			"/tmp/no-browser.json",
+		);
+		expect(errors).toEqual([]);
+		const names = plugins.map((p) => p.name);
+		expect(names).toEqual(["chromium", "firefox", "chromium-py", "firefox-py"]);
+	});
+
+	it("falls back to default plugins when settings file is empty", () => {
+		// Empty JSON object → no "browser" key → same fallback.
+		mockFs.existsSync.mockReturnValue(true);
+		mockFs.readFileSync.mockImplementation((p: string) => {
+			if (p === "/tmp/empty.json") return "{}";
+			return "{}";
+		});
+
+		const { plugins, errors } = loadPluginConfigFromFile("/tmp/empty.json");
+		expect(errors).toEqual([]);
+		const names = plugins.map((p) => p.name);
+		expect(names).toEqual(["chromium", "firefox", "chromium-py", "firefox-py"]);
+	});
+
+	it("is one-shot with no caching (consecutive calls read the file each time)", () => {
+		const spy = vi.fn((_: string) =>
+			JSON.stringify({ browser: { plugins: [] } }),
+		);
+		mockFs.existsSync.mockReturnValue(true);
+		mockFs.readFileSync.mockImplementation(spy);
+
+		const testPath = "/tmp/cached.json";
+		// Call twice
+		loadPluginConfigFromFile(testPath);
+		loadPluginConfigFromFile(testPath);
+
+		// Must have been called twice (no caching)
+		expect(spy).toHaveBeenCalledTimes(2);
+	});
+});