pi-lean-portal 0.1.0

package/core/shared/nav-settle.ts

@@ -0,0 +1,187 @@
+/**
+ * Navigation settle detection for the browser extension.
+ *
+ * After a user interaction (click, press) that may or may not trigger
+ * a page navigation, this module provides a reliable way to wait for
+ * the page to settle before reading URL / title / snapshot.
+ *
+ * The core insight: instead of a fixed sleep (e.g. `waitForTimeout(300)`)
+ * that races against navigation commit, we listen for the actual
+ * `framenavigated` event and wait for page readiness (load + networkidle)
+ * only when navigation has actually started.
+ *
+ * This eliminates the URL / DOM mismatch that causes stale-@e-ref and
+ * mismatched URL/content bugs.
+ */
+
+// ─── Public types ───────────────────────────────────────────────────
+
+/**
+ * Minimal Page-like interface sufficient for navigation settle detection.
+ *
+ * The Playwright `Page` type structurally satisfies this interface, so
+ * callers can pass a real `Page` directly. Mocks in unit tests implement
+ * this interface to avoid importing Playwright.
+ */
+export interface NavigationSettlePage {
+	url(): string;
+	mainFrame(): unknown;
+	on(event: string, handler: (...args: unknown[]) => void): void;
+	off(event: string, handler: (...args: unknown[]) => void): void;
+	waitForTimeout(ms: number): Promise<void>;
+	waitForLoadState(
+		state?: "load" | "domcontentloaded" | "networkidle",
+		options?: { timeout?: number },
+	): Promise<void>;
+}
+
+/** Options for `waitForNavigationSettle`. */
+export interface NavigationSettleOptions {
+	/**
+	 * Maximum time (ms) to wait for page readiness (load + networkidle)
+	 * when a navigation is detected.  Shared budget for both waits.
+	 * Default: 5000.
+	 */
+	navTimeoutMs?: number;
+	/**
+	 * Short settle delay (ms) when no navigation occurs. This allows
+	 * client-side rerenders / animations to finish. Default: 400.
+	 */
+	settleTimeoutMs?: number;
+}
+
+/** Result of `waitForNavigationSettle`. */
+export interface NavigationSettleResult {
+	/** Whether a `framenavigated` event was observed on the main frame. */
+	navigated: boolean;
+	/** The page URL after settling (guaranteed consistent with DOM). */
+	url: string;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Wait for the page to be fully ready after a navigation.
+ *
+ * Calls `waitForLoadState("load")` for the document + sub-resources,
+ * then also waits for network idle so that SPA same-document route
+ * changes (pushState) settle before we snapshot.  Errors/timeouts
+ * are swallowed — the caller proceeds with whatever state it has.
+ */
+async function waitForPageReady(
+	page: NavigationSettlePage,
+	timeout: number,
+): Promise<void> {
+	// Cross-document or same-document navigation started.
+	// waitForLoadState("load") resolves after the document and its
+	// sub-resources load; for same-document pushState it resolves
+	// immediately since "load" already fired.
+	await page.waitForLoadState("load", { timeout }).catch(() => {
+		// Timeout or error — continue anyway. The caller gets the
+		// current URL and can decide how to proceed.
+	});
+
+	// For SPA route changes (pushState/replaceState), "load" is already
+	// satisfied and resolves instantly — the SPA may still be fetching
+	// data. A bounded networkidle wait catches the XHR/fetch burst
+	// without hanging on long-polling sites.
+	await page.waitForLoadState("networkidle", { timeout }).catch(() => {
+		// Timeout or error — continue regardless.
+	});
+}
+
+// ─── Public API ────────────────────────────────────────────────────
+
+/**
+ * Wait for navigation to settle after a user interaction (click, press,
+ * etc.) that may or may not trigger a page navigation.
+ *
+ * **Usage:**
+ * ```ts
+ * const urlBefore = page.url();
+ * await locator.click();
+ * const { navigated, url } = await waitForNavigationSettle(page, urlBefore);
+ * ```
+ *
+ * **How it works:**
+ * 1. Registers a `framenavigated` listener on the page *before* settling.
+ * 2. Races a brief window (~150 ms) against the `framenavigated` event
+ *    so that instant navigations don't pay the full window.
+ * 3. If the main frame navigated (cross-document or same-document via
+ *    `pushState`), calls `waitForPageReady` for load + bounded networkidle
+ *    (capped at `navTimeoutMs` each).
+ * 4. Falls back to URL-change detection if the URL changed without a
+ *    `framenavigated` event (defense-in-depth).
+ * 5. Otherwise, waits `settleTimeoutMs` for client-side rerenders.
+ * 6. A late-arrival gate catches navigations that start during the settle
+ *    window (e.g. an async click handler with setTimeout).
+ *
+ * The returned URL is always read **after** settling, guaranteeing
+ * consistency between the URL and the current DOM.
+ *
+ * @param page - A Page-like object (real Playwright Page or mock).
+ * @param urlBefore - The page URL before the interaction.
+ * @param opts - Optional timeout overrides.
+ * @returns `{ navigated, url }` after the page has settled.
+ */
+export async function waitForNavigationSettle(
+	page: NavigationSettlePage,
+	urlBefore: string,
+	opts?: NavigationSettleOptions,
+): Promise<NavigationSettleResult> {
+	const navTimeout = opts?.navTimeoutMs ?? 5000;
+	const settleTimeout = opts?.settleTimeoutMs ?? 400;
+
+	let navigated = false;
+
+	// Deferred promise that resolves when framenavigated fires on the main
+	// frame.  We race this against the detection window so that instant
+	// navigations don't pay the full 150ms.
+	let navResolve: () => void = () => {};
+	const navStarted = new Promise<void>((resolve) => {
+		navResolve = resolve;
+	});
+
+	const onNav = (frame: unknown) => {
+		if (frame === page.mainFrame()) {
+			navigated = true;
+			navResolve();
+		}
+	};
+
+	page.on("framenavigated", onNav);
+
+	try {
+		// Race the detection window against the framenavigated event.
+		// Most link clicks and Enter presses trigger navigation within one
+		// event-loop tick; the race means we don't waste time when nav
+		// starts immediately.
+		await Promise.race([page.waitForTimeout(150), navStarted]);
+
+		let waitedForLoad = false;
+		if (navigated) {
+			await waitForPageReady(page, navTimeout);
+			waitedForLoad = true;
+		} else if (page.url() !== urlBefore) {
+			// URL changed without a framenavigated event (possible edge case).
+			await waitForPageReady(page, navTimeout);
+			waitedForLoad = true;
+		} else {
+			// No navigation detected yet — allow client-side rerenders /
+			// scrolling to settle before reading the snapshot.
+			await page.waitForTimeout(settleTimeout);
+		}
+
+		// Late-arrival gate: a navigation may have started during the settle
+		// timeout (e.g. an async click handler with a 200ms setTimeout).  If
+		// we didn't already call waitForPageReady but navigated has since
+		// become true (or the URL changed), wait for readiness now.
+		if (!waitedForLoad && (navigated || page.url() !== urlBefore)) {
+			await waitForPageReady(page, navTimeout);
+		}
+	} finally {
+		page.off("framenavigated", onNav);
+	}
+
+	return { navigated, url: page.url() };
+}

package/core/shared/paths.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared Path & Filename Utilities — single source of truth for temp
+ * file directories and task ID sanitization.
+ *
+ * Previously these constants and helpers were duplicated across
+ * snapshot-cache.ts, fetch-backend.ts, and router.ts. Consolidating
+ * them here prevents divergence and simplifies changes.
+ *
+ * @module paths
+ */
+
+import { tmpdir, homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** Base temp directory for all pi-lean-portal ephemeral files. */
+export const BROWSER_TEMP_DIR = `${tmpdir()}/pi-lean-portal`;
+
+/**
+ * Portal-owned data root under ~/.pi/agent/, namespaced by package name.
+ * Houses user-authored guides, browser profiles, and any other runtime
+ * user data that must survive package upgrades.
+ * Siblings: sessions/ (pi-core owned — DO NOT move under this).
+ */
+export const PORTAL_DATA_DIR = join(
+	homedir(),
+	".pi",
+	"agent",
+	"pi-lean-portal",
+);
+
+/**
+ * Sanitize a taskId (or any string) for use in filenames.
+ * Replaces any character that is not alphanumeric or hyphen with `_`.
+ *
+ * Note: `taskId()` from `task-id.ts` always returns filename-safe values
+ * (`browser-N` or `browser-default`), so callers can skip this on its
+ * output. This function is useful for sanitizing arbitrary strings such
+ * as raw pi session IDs.
+ */
+export function safeTaskId(taskId: string): string {
+	return taskId.replace(/[^a-zA-Z0-9-]/g, "_");
+}
+
+/**
+ * Ensure the browser temp directory exists (best-effort).
+ * Creates the directory recursively. Silently ignores errors so that
+ * callers don't need their own try-catch blocks.
+ */
+export function ensureBrowserTempDir(): void {
+	try {
+		mkdirSync(BROWSER_TEMP_DIR, { recursive: true });
+	} catch {
+		/* best-effort */
+	}
+}

package/core/shared/session-manager.ts

@@ -0,0 +1,258 @@
+/**
+ * Session manager — tracks browser session lifecycle per task_id.
+ *
+ * Design: sessions track metadata; browsers and contexts are managed
+ * entirely by the plugin. The session manager is Playwright-agnostic.
+ */
+
+/** Runtime state of a single browsing session */
+export interface BrowserSession {
+	taskId: string;
+	/** Name of the plugin this session is bound to (set once, never changes) */
+	pluginName: string;
+	/** The URL currently loaded in this session */
+	currentUrl?: string;
+	/** Page title if available */
+	currentTitle?: string;
+	/** Stable hash of the last snapshot's accessibility tree (for DOM-change detection) */
+	currentSnapshotFingerprint?: string;
+	/** Timestamp when element cache was last populated (for staleness detection) */
+	cachePopulatedAt?: number;
+	/** Timestamp of the last interaction that may have mutated the DOM */
+	lastInteractionAt?: number;
+	/** Timestamp of last activity */
+	lastActive: number;
+	/** Whether the session has crashed and needs recovery */
+	crashed: boolean;
+	/** Whether to auto-save storage state on cleanup */
+	persistState?: boolean;
+	/** Profile name used for this session (undefined = default) */
+	profileName?: string;
+	/** pi session ID for session-scoped profiles */
+	piSessionId?: string;
+}
+
+/** Stored last navigation for a task (used to auto-recover sessions) */
+interface LastNavEntry {
+	url: string;
+	title: string;
+	/** Plugin name that was used for the original navigation */
+	pluginName: string;
+	/** Profile name active during this navigation (for restoring state on recovery) */
+	profileName?: string;
+}
+
+class SessionManager {
+	#sessions = new Map<string, BrowserSession>();
+	/** Last navigation URL per task (survives session removal, cleared explicitly) */
+	#lastNav = new Map<string, LastNavEntry>();
+
+	createSession(taskId: string, pluginName: string): BrowserSession {
+		const existing = this.#sessions.get(taskId);
+		if (existing) {
+			existing.pluginName = pluginName;
+			delete existing.currentUrl;
+			delete existing.currentTitle;
+			existing.lastActive = Date.now();
+			existing.crashed = false;
+			return existing;
+		}
+		const session: BrowserSession = {
+			taskId,
+			pluginName,
+			lastActive: Date.now(),
+			crashed: false,
+		};
+		this.#sessions.set(taskId, session);
+		return session;
+	}
+
+	getSession(taskId: string): BrowserSession | undefined {
+		return this.#sessions.get(taskId);
+	}
+
+	updateSession(
+		taskId: string,
+		updates: Partial<
+			Pick<
+				BrowserSession,
+				| "currentUrl"
+				| "currentTitle"
+				| "pluginName"
+				| "crashed"
+				| "currentSnapshotFingerprint"
+				| "cachePopulatedAt"
+				| "lastInteractionAt"
+				| "persistState"
+				| "profileName"
+				| "piSessionId"
+			>
+		>,
+	): void {
+		const session = this.#sessions.get(taskId);
+		if (session) {
+			if (updates.currentUrl !== undefined)
+				session.currentUrl = updates.currentUrl;
+			if (updates.currentTitle !== undefined)
+				session.currentTitle = updates.currentTitle;
+			if (updates.pluginName !== undefined)
+				session.pluginName = updates.pluginName;
+			if (updates.crashed !== undefined) session.crashed = updates.crashed;
+			if (updates.currentSnapshotFingerprint !== undefined)
+				session.currentSnapshotFingerprint = updates.currentSnapshotFingerprint;
+			if (updates.cachePopulatedAt !== undefined)
+				session.cachePopulatedAt = updates.cachePopulatedAt;
+			if (updates.lastInteractionAt !== undefined)
+				session.lastInteractionAt = updates.lastInteractionAt;
+			if (updates.persistState !== undefined)
+				session.persistState = updates.persistState;
+			if (updates.profileName !== undefined)
+				session.profileName = updates.profileName;
+			if (updates.piSessionId !== undefined)
+				session.piSessionId = updates.piSessionId;
+			session.lastActive = Date.now();
+		}
+	}
+
+	// ─── Last navigation storage (for session auto-recovery) ───
+
+	setLastNav(
+		taskId: string,
+		url: string,
+		title: string,
+		pluginName: string,
+		profileName?: string,
+	): void {
+		const entry: LastNavEntry = { url, title, pluginName };
+		if (profileName !== undefined) {
+			entry.profileName = profileName;
+		}
+		this.#lastNav.set(taskId, entry);
+	}
+
+	getLastNav(taskId: string): LastNavEntry | undefined {
+		return this.#lastNav.get(taskId);
+	}
+
+	clearLastNav(taskId: string): void {
+		this.#lastNav.delete(taskId);
+	}
+
+	// ─── Session lifecycle ────────────────────────────────────────────
+
+	removeSession(taskId: string): void {
+		this.#sessions.delete(taskId);
+		this.#lastNav.delete(taskId);
+	}
+
+	async removeAll(): Promise<void> {
+		this.#sessions.clear();
+		this.#lastNav.clear();
+	}
+
+	/**
+	 * Get a display symbol for a plugin name.
+	 * Known plugins get short symbols; unknown plugins get the first 3 chars.
+	 */
+	pluginSymbol(pluginName: string): string {
+		switch (pluginName) {
+			case "chromium":
+				return "PW";
+			case "firefox":
+				return "FF";
+			default:
+				// Return up to 3 uppercase chars for custom plugins
+				return pluginName.slice(0, 3).toUpperCase();
+		}
+	}
+
+	getStatus(): string {
+		const active = this.getActiveSessions();
+		const crashed = Array.from(this.#sessions.values()).filter(
+			(s) => s.crashed,
+		);
+
+		if (active.length === 0) {
+			if (crashed.length > 0) {
+				return `${crashed.length} crashed`;
+			}
+			return "idle";
+		}
+		if (active.length === 1) {
+			const s = active[0]!;
+			const domain = s.currentUrl ? extractDomain(s.currentUrl) : undefined;
+			const sym = this.pluginSymbol(s.pluginName);
+			const profileTag = s.profileName
+				? ` [${profileDisplayName(s.profileName)}]`
+				: "";
+			let status = domain
+				? `${sym}: ${domain}${profileTag}`
+				: `${sym}${profileTag}`;
+			if (crashed.length > 0) {
+				status += ` · ${crashed.length} crashed`;
+			}
+			return status;
+		}
+		// Multiple active sessions — group by profile
+		const byProfile = new Map<string, number>();
+		for (const s of active) {
+			const key = s.profileName ?? "ephemeral";
+			byProfile.set(key, (byProfile.get(key) ?? 0) + 1);
+		}
+		const profileParts = Array.from(byProfile.entries()).map(([name, count]) =>
+			count > 1
+				? `${profileDisplayName(name)}×${count}`
+				: profileDisplayName(name),
+		);
+		const sym = this.pluginSymbol(active[0]!.pluginName);
+		let status = `${active.length} active (${sym}): ${profileParts.join(", ")}`;
+		if (crashed.length > 0) {
+			status += ` · ${crashed.length} crashed`;
+		}
+		return status;
+	}
+
+	getActiveSessions(): BrowserSession[] {
+		return Array.from(this.#sessions.values()).filter(
+			(s) => s.currentUrl && !s.crashed,
+		);
+	}
+
+	get activeCount(): number {
+		return this.getActiveSessions().length;
+	}
+
+	/**
+	 * Find the taskId for a given pi session ID.
+	 * Used by command handlers (like `/web cookies`) to resolve the correct
+	 * taskId without duplicating index.ts's monotonic counter logic.
+	 */
+	getTaskIdForPiSessionId(piSessionId: string): string | undefined {
+		for (const [taskId, session] of this.#sessions.entries()) {
+			if (session.piSessionId === piSessionId) return taskId;
+		}
+		return undefined;
+	}
+}
+
+/**
+ * Short display name for a profile in the TUI status bar.
+ * Session-scoped profiles render as a "📋 session" badge;
+ * named profiles show their name;
+ * "ephemeral" (no profile) label shows as-is.
+ */
+function profileDisplayName(name: string): string {
+	if (name.startsWith("_session-")) return "📋 session";
+	if (name === "ephemeral") return "ephemeral";
+	return name;
+}
+
+function extractDomain(url: string): string {
+	try {
+		return new URL(url).hostname;
+	} catch {
+		return url;
+	}
+}
+
+export const sessionManager = new SessionManager();

package/core/shared/settings-reader.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared settings.json reader — used by multiple modules that need to
+ * read pi's settings.json files (global and project-local).
+ *
+ * Provides a unified `readSettingsFile()` function and canonical path
+ * constants to prevent drift across the codebase.
+ *
+ * @module
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ─── Config paths ─────────────────────────────────────────────────
+
+/** Global pi settings path. */
+export const GLOBAL_SETTINGS_PATH = join(
+	homedir(),
+	".pi",
+	"agent",
+	"settings.json",
+);
+
+/** Project pi settings path (relative to cwd). */
+export const PROJECT_SETTINGS_PATH = ".pi/settings.json";
+
+// ─── Reader ────────────────────────────────────────────────────────
+
+/**
+ * Read and parse a JSON settings file. Returns {} on any failure.
+ */
+export function readSettingsFile(path: string): Record<string, unknown> {
+	try {
+		if (!existsSync(path)) return {};
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return parsed as Record<string, unknown>;
+		}
+		return {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Read global + project settings and merge them (project overrides global).
+ *
+ * Convenience wrapper so consumers don't duplicate the merge pattern.
+ *
+ * @param globalPath - Path to the global settings file (defaults to GLOBAL_SETTINGS_PATH)
+ * @param projectPath - Path to the project settings file (defaults to PROJECT_SETTINGS_PATH)
+ * @returns Merged settings object with project values taking precedence
+ */
+export function readMergedSettings(
+	globalPath: string = GLOBAL_SETTINGS_PATH,
+	projectPath: string = PROJECT_SETTINGS_PATH,
+): Record<string, unknown> {
+	const global = readSettingsFile(globalPath);
+	const project = readSettingsFile(projectPath);
+	return { ...global, ...project };
+}