pi-lean-dimension 0.1.0 → 0.2.0

package/node_modules/pi-lean-portal/__tests__/helpers/create-py-backend-harness.ts

@@ -0,0 +1,105 @@
+/**
+ * Availability probe + path resolver for shipped Python bridge backends.
+ *
+ * Returns resolved paths and a `describeIfAvailable` gate so every
+ * Python backend test file collapses to ~15 lines.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe } from "vitest";
+
+/** Optional engine-binary check for Python backends. */
+export interface PyBackendHarnessOptions {
+	/** When "firefox", also probes that the Firefox browser binary exists. */
+	engine?: "chromium" | "firefox";
+}
+
+/** Result of {@link createPyBackendTestHarness}. */
+export interface PyBackendTestHarnessResult {
+	/** Resolved path to `<bridgeName>/bridge.py`. */
+	bridgeScript: string;
+	/** Resolved path to the Python venv interpreter. */
+	pythonPath: string;
+	/** True when all prerequisites are met (python + bridge + optional engine). */
+	prerequisitesMet: boolean;
+	/**
+	 * `describe` when prerequisites are met, `describe.skip` otherwise.
+	 * Drop-in for the `describeIfAvailable` gate pattern.
+	 */
+	describeIfAvailable: typeof describe | typeof describe.skip;
+}
+
+/**
+ * Probe a shipped Python bridge backend and return resolved paths +
+ * a ready-to-use `describeIfAvailable` gate.
+ *
+ * The test caller destructures what it needs:
+ * ```
+ * const { bridgeScript, pythonPath, describeIfAvailable } = createPyBackendTestHarness("chromium-py");
+ * ```
+ *
+ * Paths resolve relative to `__tests__/helpers/` using the conventional
+ * monorepo layout: `backends/<name>/bridge.py`, `backends/python-base/.venv/bin/python3`.
+ *
+ * @param bridgeName  Backend directory name (e.g. `"chromium-py"`, `"firefox-py"`).
+ * @param options     Optional engine check.
+ */
+export function createPyBackendTestHarness(
+	bridgeName: string,
+	options?: PyBackendHarnessOptions,
+): PyBackendTestHarnessResult {
+	const bridgeScript = resolve(
+		__dirname,
+		`../../backends/${bridgeName}/bridge.py`,
+	);
+	const pythonPath = resolve(
+		__dirname,
+		"../../backends/python-base/.venv/bin/python3",
+	);
+
+	const pythonAvailable = (() => {
+		if (!existsSync(pythonPath)) return false;
+		const result = spawnSync(pythonPath, ["--version"], {
+			stdio: "ignore",
+			timeout: 5_000,
+		});
+		return result.status === 0;
+	})();
+
+	const bridgeExists = existsSync(bridgeScript);
+
+	let browserAvailable = true;
+	if (options?.engine === "firefox" && pythonAvailable) {
+		browserAvailable = (() => {
+			try {
+				const result = spawnSync(
+					pythonPath,
+					[
+						"-c",
+						"from playwright.sync_api import sync_playwright; " +
+							"p = sync_playwright().start(); " +
+							"import os; print(os.path.exists(p.firefox.executable_path)); " +
+							"p.stop()",
+					],
+					{ stdio: "pipe", timeout: 10_000 },
+				);
+				return (
+					result.status === 0 && result.stdout.toString().trim() === "True"
+				);
+			} catch {
+				return false;
+			}
+		})();
+	}
+
+	const prerequisitesMet = pythonAvailable && bridgeExists && browserAvailable;
+
+	return {
+		bridgeScript,
+		pythonPath,
+		prerequisitesMet,
+		describeIfAvailable: prerequisitesMet ? describe : describe.skip,
+	};
+}

package/node_modules/pi-lean-portal/__tests__/helpers/load-plugin-config-from-file.ts

@@ -0,0 +1,53 @@
+/**
+ * Load and validate plugin configuration from a specific settings file path.
+ *
+ * Moved out of core/plugin-config.ts so the function doesn't ship in the
+ * npm tarball (core/ is in the package `files` allowlist).
+ */
+
+import {
+	parsePluginConfig,
+	type PluginConfigLoadResult,
+	DEFAULT_BACKEND_ROOTS,
+} from "../../core/plugin-config.js";
+import { readSettingsFile } from "../../core/shared/settings-reader.js";
+
+/**
+ * Same parsing/validation as {@link import("../../core/plugin-config.js").parsePluginConfig},
+ * but reads from a specific file path instead of the merged global + project
+ * settings. One-shot read — no caching.
+ *
+ * The file must have the same top-level shape as `settings.json`:
+ * ```json
+ * { "browser": { "plugins": [...] } }
+ * ```
+ *
+ * When the file is absent or has no `browser` section, falls back to the
+ * default plugin list (same as `parsePluginConfig(undefined, …)` with no settings).
+ *
+ * @param path  Absolute or relative path to a settings.json file.
+ * @param roots  Optional ordered list of backend roots to resolve
+ *               plugin `dir` values against.  Defaults to
+ *               `DEFAULT_BACKEND_ROOTS`.
+ */
+export function loadPluginConfigFromFile(
+	path: string,
+	roots?: readonly string[],
+): PluginConfigLoadResult {
+	const raw = readSettingsFile(path);
+	const browserConfig = raw["browser"];
+	const effectiveRoots = roots ?? DEFAULT_BACKEND_ROOTS;
+
+	if (
+		!browserConfig ||
+		typeof browserConfig !== "object" ||
+		Array.isArray(browserConfig)
+	) {
+		return parsePluginConfig(undefined, effectiveRoots);
+	}
+
+	return parsePluginConfig(
+		browserConfig as Record<string, unknown>,
+		effectiveRoots,
+	);
+}

package/node_modules/pi-lean-portal/__tests__/helpers/mock-plugin.ts

@@ -19,10 +19,10 @@ import type {
 	ClearCookiesOptions,
 	StorageStateResult,
 	ResultBase,
-} from "../../core/plugin-api";
-import type { PluginConfig } from "../../core/plugin-config";
-import { DEFAULT_CAPABILITIES } from "../../core/plugin-api";
-import type { AriaCachedNode } from "../../core/shared/accessibility-tree";
+} from "../../core/plugin-api.js";
+import type { PluginConfig } from "../../core/plugin-config.js";
+import { DEFAULT_CAPABILITIES } from "../../core/plugin-api.js";
+import type { AriaCachedNode } from "../../core/shared/accessibility-tree.js";
 
 export class MockPlugin implements BrowserPlugin {
 	readonly name: string;
@@ -197,8 +197,12 @@ export class MockPlugin implements BrowserPlugin {
 			throw new Error("clearConsole failed");
 	}
 
-	async evaluate(taskId: string, expression: string): Promise<EvaluateResult> {
-		this.record("evaluate", [taskId, expression]);
+	async evaluate(
+		taskId: string,
+		expression: string,
+		readOnly?: boolean,
+	): Promise<EvaluateResult> {
+		this.record("evaluate", [taskId, expression, readOnly]);
 		if (this.shouldThrow.has("evaluate")) throw new Error("evaluate failed");
 		return {
 			success: true,
@@ -239,7 +243,7 @@ export class MockPlugin implements BrowserPlugin {
 
 	async addCookies(
 		taskId: string,
-		cookies: import("../../core/plugin-api").Cookie[],
+		cookies: import("../../core/plugin-api.js").Cookie[],
 	): Promise<ResultBase> {
 		this.record("addCookies", [taskId, cookies]);
 		if (this.shouldThrow.has("addCookies"))

package/node_modules/pi-lean-portal/__tests__/helpers/mock-python-bridge.py

@@ -36,6 +36,10 @@ def main() -> None:
         if method == "ping":
             write_response(req_id, result="pong")
 
+        elif method == "browser.init":
+            # Phase 0: accept plugin config forwarded from the adapter after ping.
+            write_response(req_id, result={"ok": True})
+
         elif method == "shutdown":
             write_response(req_id, result="shutting_down")
             sys.stdout.flush()

package/node_modules/pi-lean-portal/__tests__/helpers/persistence-suite.ts

@@ -0,0 +1,218 @@
+/**
+ * Shared persistence suite — a generic, backend-agnostic test helper that
+ * validates the cookie-persistence lifecycle across navigations.
+ *
+ * Every interactive browser backend (shipped Python, user-installed stealth)
+ * should produce the same persistence behaviour: navigate → consent dialog
+ * visible → click Accept All → cookie set → re-navigate → dialog absent
+ * → storage-state.json on disk → third navigate still clean.
+ *
+ * This helper owns the six `it` blocks and the consent-dialog click flow
+ * that every persistence file previously copy-pasted. The caller is
+ * responsible for:
+ *
+ *   - Prerequisite probing (path-based venv probe or `probeUserBackend`)
+ *   - Adapter construction (choosing shipped vs contributed paths)
+ *   - Test server lifecycle (start/stop)
+ *   - Passing `describe` or `describe.skip` depending on availability
+ *
+ * The helper references no backend names and no stealth-engine identifiers.
+ * It is git-tracked and policy-clean.
+ *
+ * @module
+ */
+
+import { it, expect, beforeAll, afterAll } from "vitest";
+import type { BrowserPlugin } from "../../core/plugin-api.js";
+import { sessionManager } from "../../core/shared/session-manager.js";
+import {
+	loadStorageState,
+	deleteStorageState,
+} from "../../core/shared/storage-state.js";
+
+// ─── Types ─────────────────────────────────────────────────────────
+
+/**
+ * Callable signature that matches both `describe` and `describe.skip`.
+ * The caller picks which one to pass based on their prerequisite probe.
+ */
+export type DescribeFn = (
+	name: string,
+	fn: () => void,
+	timeout?: number,
+) => void;
+
+/** Options for {@link runPersistenceSuite}. */
+export interface PersistenceSuiteOptions {
+	/**
+	 * Backend name, used in `it()` titles and profile prefix for
+	 * attribution (e.g. `"my-backend"`).
+	 */
+	name: string;
+
+	/**
+	 * Getter that returns the base URL of the local HTTP test server
+	 * serving {@link COOKIE_PERSISTENCE_HTML} (the consent-dialog page).
+	 *
+	 * Implemented as a getter (rather than a plain string) because the
+	 * URL is only known after the caller's `beforeAll` starts the test
+	 * server.  The helper calls this lazily from its own `beforeAll` /
+	 * `it` blocks, by which point the caller's `beforeAll` has set the
+	 * value.
+	 *
+	 * Example:
+	 * ```ts
+	 * let serverUrl: string;
+	 * beforeAll(async () => { serverUrl = (await startTestServer(h)).url; });
+	 * runPersistenceSuite(describe, { getServerUrl: () => serverUrl, ... });
+	 * ```
+	 */
+	getServerUrl: () => string;
+
+	/**
+	 * Factory that constructs and **initialises** a fresh plugin instance
+	 * for the suite.  Called once from the helper's `beforeAll`.
+	 *
+	 * The caller owns probe + adapter construction (shipped backends use
+	 * path-based venv probing; contributed backends use
+	 * `probeUserBackend`, and should pass the correct paths into the
+	 * adapter constructor here.
+	 */
+	createPlugin: () => Promise<BrowserPlugin>;
+
+	/** Per-navigate timeout in milliseconds (default 30_000). */
+	navTimeout?: number;
+
+	/** Timeout for the enclosing `describe` block (default 120_000). */
+	describeTimeout?: number;
+}
+
+// ─── Public API ─────────────────────────────────────────────────────
+
+/**
+ * Run the six persistence `it` blocks against the provided plugin.
+ *
+ * The describe block is **gated by the caller**: pass a real `describe`
+ * when prerequisites are met, or `describe.skip` to skip the entire
+ * suite.  The helper does **not** probe — that is the caller's job.
+ *
+ * Six `it` blocks (all parametrised with `opts.name` for attribution):
+ * 1. Navigate with named profile → consent dialog visible
+ * 2. Click Accept All → cookie set, dialog closes
+ * 3. Create session + set persistState (simulates the router's setup)
+ * 4. Re-navigate with same profile → dialog absent (cookies survived)
+ * 5. storage-state.json on disk with the consent cookie
+ * 6. Third navigate → still no dialog (persistence confirmed)
+ *
+ * @param describeFn  `describe` when available, `describe.skip` otherwise.
+ * @param opts        Suite options.  See {@link PersistenceSuiteOptions}.
+ */
+export function runPersistenceSuite(
+	describeFn: DescribeFn,
+	opts: PersistenceSuiteOptions,
+): void {
+	const {
+		name,
+		getServerUrl,
+		createPlugin,
+		navTimeout = 30_000,
+		describeTimeout = 120_000,
+	} = opts;
+
+	const TASK_ID = `${name}-persistence`;
+
+	describeFn(
+		`${name} cookie persistence across navigations`,
+		() => {
+			const TEST_PROFILE = `${name}-persist-${Date.now()}`;
+
+			let plugin: BrowserPlugin;
+
+			beforeAll(async () => {
+				plugin = await createPlugin();
+			});
+
+			afterAll(async () => {
+				await plugin.cleanupAll().catch(() => {});
+				deleteStorageState(TEST_PROFILE);
+			});
+
+			it(`${name}: navigates with a named profile — consent dialog is visible`, async () => {
+				const nav = await plugin.navigate(getServerUrl(), TASK_ID, navTimeout, {
+					profileName: TEST_PROFILE,
+					profileMode: "named",
+				});
+				expect(nav.success).toBe(true);
+				expect(nav.title).toContain("Cookie Persistence Test");
+				expect(nav.snapshot).toContain("Consent");
+				expect(nav.snapshot).toContain("Accept All");
+			});
+
+			it(`${name}: clicks Accept All — cookie set, consent dialog closes`, async () => {
+				const snap = await plugin.snapshot(TASK_ID);
+				expect(snap.success).toBe(true);
+
+				// Find "Accept All" button in the snapshot and extract its @e ref
+				const btnMatch = snap.snapshot.match(/@(e\d+)\b.*?button.*?Accept All/);
+				expect(btnMatch).toBeTruthy();
+				if (!btnMatch) return;
+
+				const ref = `@${btnMatch[1]!}`;
+				const clickResult = await plugin.click(TASK_ID, ref);
+				expect(clickResult.success).toBe(true);
+
+				// Verify dialog is gone from snapshot
+				if (clickResult.snapshot) {
+					expect(clickResult.snapshot).not.toContain("Consent");
+				}
+			});
+
+			it(`${name}: creates session and sets persistState (simulating the router's setup)`, async () => {
+				sessionManager.createSession(TASK_ID, name);
+				const session = sessionManager.getSession(TASK_ID);
+				expect(session).toBeDefined();
+				if (session) {
+					session.persistState = true;
+					session.profileName = TEST_PROFILE;
+				}
+			});
+
+			it(`${name}: navigates again with same profile — consent dialog does NOT reappear`, async () => {
+				const nav = await plugin.navigate(getServerUrl(), TASK_ID, navTimeout, {
+					profileName: TEST_PROFILE,
+					profileMode: "named",
+				});
+				expect(nav.success).toBe(true);
+
+				// Consent dialog should NOT be present — cookies survived in-context
+				expect(nav.snapshot).not.toContain("Consent");
+				expect(nav.snapshot).not.toContain("Accept All");
+			});
+
+			it(`${name}: storage-state.json exists on disk with the consent cookie`, async () => {
+				const state = loadStorageState(TEST_PROFILE);
+				expect(state).not.toBeNull();
+				expect(state!.cookies.length).toBeGreaterThan(0);
+
+				const consentCookie = state!.cookies.find(
+					(c: { name: string; value: string }) =>
+						c.name === "consent" && c.value === "accepted",
+				);
+				expect(consentCookie).toBeDefined();
+			});
+
+			it(`${name}: third navigate also has no consent dialog (persistence confirmed)`, async () => {
+				const nav = await plugin.navigate(getServerUrl(), TASK_ID, navTimeout, {
+					profileName: TEST_PROFILE,
+					profileMode: "named",
+				});
+				expect(nav.success).toBe(true);
+
+				// Dialog should still be absent
+				expect(nav.snapshot).not.toContain("Consent");
+				expect(nav.snapshot).not.toContain("Accept All");
+			});
+		},
+		describeTimeout,
+	);
+}